Hwp_OGGVorbis

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.