Hwp_MP3Enc

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.