
oggvorbis.hwp
=============

This plugin enables Hollywood to load and save Ogg Vorbis audio files. The plugin
comes in two flavours: A full version named oggvorbis.hwp and the light version
oggvorbis-lite.hwp. The light version can only play Ogg Vorbis audio files while
the full version can also encode them. The Ogg Vorbis encoder is quite big (over
3 MB on some platforms) which is the reason why the plugin comes in two versions.


Requirements
============

Playing Ogg Vorbis files with this plugin is possible with Hollywood 5.0 and up.
If you want to encode Ogg Vorbis streams, however, you need at least Hollywood 11.0
since encoding Ogg Vorbis files uses new APIs introduced with Hollywood 11.0.

Note that on AmigaOS 3 it's highly recommended to use the FPU version of the plugin
because the Ogg Vorbis encoder is very heavy on floating point operations so on 68k
expect the non-FPU version to be lightyears slower than the FPU version.


Usage
=====

To play Ogg Vorbis with this plugin, just call @REQUIRE on it and then Hollywood will
'automagically' be able to open and play Ogg Vorbis audio streams using OpenMusic(),
@MUSIC and LoadSample(), e.g.

    @REQUIRE "oggvorbis-lite"   ; the light version is enough for playback
    OpenMusic(1, "test.ogg")
    PlayMusic(1)
   
To save Ogg Vorbis files with this plugin, just pass #SNDFMT_OGGVORBIS to functions that
create sound files, i.e. SaveMusic(), SaveSample(), RecordAudio() and BeginMusicStream().
For example, to convert a Protracker module to an Ogg Vorbis stream using this plugin, you
could use this code:

    @REQUIRE "oggvorbis"    
    OpenMusic(1, "test.mod", {TimedProtracker = True})
    SaveMusic(1, "test.ogg", #SNDFMT_OGGVORBIS)    

The plugin supports the following tags of Hollywood's sound output functions:

    Bitrate: If this tag is provided, the output file will use a constant bitrate. This
    must be set in kbps, e.g. 128 or 192. If this tag is set to 0, the Ogg Vorbis file
    will be encoded using a variable bitrate. Defaults to 128.
    
    Quality: This tag can be used to set the quality level in case the file is encoded
    using a variable bitrate. Note that if you want to use this tag, you must also set
    the "Bitrate" tag to 0 to enable variable bitrate encoding. The "Quality" tag must
    be a value between 0 and 100 where 0 means lowest quality (= smallest file size)
    and 100 means best quality, i.e. biggest file size. The default value of this tag
    is 40.

Here's how to save a music using a constant bitrate of 192 kbps instead of the default
128 kbps:

    SaveMusic(1, "test.ogg", #SNDFMT_OGGVORBIS, {Bitrate = 192})  
    
And here's how to save a music using a variable bitrate and a quality setting of 75%:

    SaveMusic(1, "test.ogg", #SNDFMT_OGGVORBIS, {Bitrate = 0, Quality = 75}) 
        
Using Hollywood user tags you can also attach an Ogg serial number to the output file.
This can be an arbitrary 32-bit integer. If you don't pass a serial number, the plugin
will generate a random serial number. To set a serial number for your Ogg Vorbis file,
pass the "Serial" tag in the "UserTags" table argument, e.g. like this:
     
    SaveMusic(1, "test.ogg", #SNDFMT_OGGVORBIS, {UserTags = {Serial = 12345}})


History
=======

Version 2.0:    (25-Apr-26)
- New [Android/iOS]: Added builds for Android and iOS; previously, Ogg Vorbis support
  was built directly into Hollywood for Android and iOS; this is going to change with
  the next Hollywood release which is why the plugin is now also available for Android
  and iOS
- New [macOS/Linux]: Added builds for the macOS and Linux arm64 platforms 
- New: Added support for encoding Ogg Vorbis streams; this feature requires at least
  Hollywood 11 because it uses the new sound stream export API introduced with version
  11 of Hollywood; since the code for encoding Ogg Vorbis streams is very big (over
  3 megabytes on some platforms) the plugin now comes in two flavours: oggvorbis-lite.hwp
  only contains the code necessary to play Ogg Vorbis files whereas oggvorbis.hwp
  contains the encoder as well; if you only need to play Ogg Vorbis files, you can just
  use oggvorbis-lite.hwp because it's much smaller
- New: Plugin supports Hollywood 10's user tag interface for file adapters now; all
  user tags will be forwarded to the corresponding file adapters now
  
Version 1.1:    (01-Jul-15)
- New [Linux]: Added build for Linux ARM
- Fix [Linux/MacOS]: Plugin is now compiled as position-independent code (PIC)
- Fix [OS3]: FPU version will cleanly exit now in case there is no FPU
- New: Added file types information for Hollywood 5.3

Version 1.0:    (07-Mar-12)
- First release


Bugs
====

Please report any bugs or issues via the Hollywood forums at http://forums.hollywood-mal.com/ 


Copyright
=========

This plugin is (C) Copyright 2012-2026 by Andreas Falkenhahn <andreas@airsoftsoftwair.de>
Refer to the COPYING file in this package for conditions concerning distribution
of this plugin. Visit http://www.hollywood-mal.com/ for more information
on Hollywood and more plugins.
