
mp3enc.hwp
==========

This plugin can be used to save sound streams and samples in the MP3 format. Once the
plugin is installed, you can make the Hollywood functions SaveMusic(), SaveSample(),
RecordAudio() and BeginMusicStream() save the sound data in the MP3 format by passing
the #SNDFMT_MP3 constant as the output format. See below for some examples.


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

This plugin requires at least Hollywood 11.0 since it 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 MP3 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 save MP3s with this plugin, just pass #SNDFMT_MP3 to functions that create sound
files, i.e. SaveMusic(), SaveSample(), RecordAudio() and BeginMusicStream(). For example,
to convert a Protracker module to an MP3 using this plugin, you could use this code:

    @REQUIRE "mp3enc"    
    OpenMusic(1, "test.mod", {TimedProtracker = True})
    SaveMusic(1, "test.mp3", #SNDFMT_MP3)    

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

    Bitrate: If this tag is provided, the MP3 will use a constant bitrate. This must
    be set in kbps, e.g. 128 or 192. If this tag is set to 0, the MP3 will be encoded
    using a variable bitrate. Defaults to 128.
    
    Quality: This tag can be used to control how much effort the encoder spends
    optimizing compression. This can be a value between 0 and 9 where 0 means
    "best quality, slowest encoding" and 9 means "fastest, lowest algorithm quality".
    Note that this setting doesn't affect the bitrate, it only controls how much CPU
    time the encoder spends making compression decisions. The most important tag
    for controlling the actual audio quality is the "Bitrate" tag (see above). The
    default quality setting is 5.

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

    SaveMusic(1, "test.mp3", #SNDFMT_MP3, {Bitrate = 192})   

When setting "Bitrate" to 0 in order to create an MP3 with a variable bitrate, you can
use the "VBRQuality" user tag to control the quality level used for variable bitrate
encoding. This can be a value between 0 and 9 where higher numbers mean better quality.
Here's an overview of the different levels:

    0    ~245 kbps    Highest
    1    ~225 kbps    Very high
    2    ~190 kbps    High
    3    ~175 kbps    Good
    4    ~165 kbps    Medium-high (default)
    5    ~130 kbps    Medium
    6    ~115 kbps    Lower
    7    ~100 kbps    Low
    8     ~85 kbps    Very low
    9     ~65 kbps    Lowest

The default VBR quality level is 4. Note that in contrast to the "Bitrate" and "Quality"
tags, "VBRQuality" is a user tag which means it's a tag that isn't supported by Hollywood
directly but it's only recognized by mp3enc.hwp. Thus, you must pass it to the mp3enc plugin
through the "UserTags" tag. Here is an example of how to pass 2 in the "VBRQuality" user tag
in order to encode an MP3 using a variable bitrate of around ~190 kbps:

    SaveMusic(1, "test.mp3", #SNDFMT_MP3, {Bitrate = 0, UserTags = {VBRQuality = 2}})


History
=======

Version 1.0:    (07-Mar-26)
- 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 2025-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.
