NAME

SYNOPSIS

 # httpd.conf or access.conf
 AddType audio/shorten .shn .SHN
 AddType audio/flac .flac

 Alias /apache_mp3 /usr/share/libapache-mp3-perl

 <Location /songs>
   SetHandler perl-script
   PerlHandler Apache::MP3::Resample
   PerlSetVar CacheDir          /var/cache/Apache::MP3
   PerlSetVar AllowDownload     no
   PerlSetVar SortFields        Album,Track,Title,-Duration
   PerlSetVar Fields            Track,Title,Artist,Album,Duration,Bitrate
 </Location>

DESCRIPTION

This module requires a command-line MP3 encoder to resample and reencode the audio data. If not otherwise specified, Apache::MP3::Resample will try to use the Open Source Lame MP3 encoder. This utility is available at http://www.sulaco.org/mp3. Version 3.90 was used during the development of this module. Your results with other versions may vary.

When you install Lame (or the encoder of your choice), be sure to place it in a directory located in Apache's PATH so that the module can find them at run time. You may need to set the PATH environment variable during Apache's launch, or by explicitly adding a SetEnv directive to the Apache configuration file.

You should be aware that the decoding/reencoding process is CPU-intensive, and server performance may degrade as the number of simultaneous users increases.

CUSTOMIZATION

MP3Encoder

The command to use to invoke the MP3 encoder. It should accept CDDA data on standard input and write MP3 data to standard output. The command should contain the replacement sequences b<%b> and b<%f>. At run time, b<%b> will be replaced with the options used to set the bitrate and sampling frequency, while b<%f> will contain the MP3 file to be streamed.

If not present, the following default is used:

  lame --mp3input %b - <%f
    

DecompressorPresets

A list of MIME types and decompression programs to use for each. The format uses a variant of the standard Perl hash format, in which the keys are the MIME types for the audio files and the values are the command which will be used to decompress files of that type. The token "%f" will be replaced by the name of the compressed audio file and the command should end with a pipe (|) character. Here is a simple example, which is also the default list:

    PerlSetVar  DecompressorPresets  '"audio/shorten" => "shorten -x %f -|",\
                                      "audio/flac" => "flac -d -c -s %f|"'
    

Note the use of quotation marks and backslashes to protect whitespace and newlines respectively.

ResamplePresets

A list of bitrates and the command-line options to pass to the encoder. The format uses a variant of the standard Perl hash format, in which the keys are the bitrates to present to the user and the values are command-line options to pass to the encoder. Here is a simple example:

    PerlSetVar  ResamplePresets  '16 kbps => -b16,\
                                  56 kbps => -b56,\
                                 128 kbps => -b128,\
                                 160 kbps => -b160'
    

Note the use of quotation marks and backslashes to protect whitespace and newlines respectively.

Here is another example, which takes advantage of the --preset feature present in newer versions of Lame.

    PerlSetVar  ResamplePresets 'phone => --preset phone,\
                                 voice  => --preset voice,\
                                 fm     => --preset fm, \
                                 tape   => --preset tape,\
                                 hifi   => --preset hifi,\
                                 cd     => --preset cd'
    

The user will see a popup menu containing the entries "16 kbps", "56 kbps" and so forth, as well as a blank ("--") entry that is provided automatically. Upon selecting each option the corresponding command-line arguments will be slotted into the "%s" variable in the encoder line specified by MP3Encoder.

More complex command line options are possible. For example, to invoke VBR (variable bitrate) encoding and resample the output to 22.05 kHz, you could apply these options

    PerlSetVar  ResamplePresets  '16 => -b16 -v --resample 22.05,\
                                  56 => -b56 -v --resample 22.05,\
                                 128 => -b128 -v --resample 22.05,\
                                 160 => -b160 -v --resample 22.05'
    

Lame only accepts certain combinations of command-line options, and I do not fully understand the restrictions. Please do not e-mail me with Lame-related questions.

The default presets are:

     24  kbps => -b24 --lowpass 4.0  --highpass 0.1  --resample 8,
     40  kbps => -b40 --lowpass 4.0  --resample 16,
     56  kbps => -b56 --lowpass 12.0 --resample 22.05,
     64  kbps => -b64 --lowpass 15.0 --resample 22.05,
     96  kbps => -b96 --lowpass 15.0,
     128 kbps => -b128 --lowpass 18,
     160 kbps => -b160,
     192 kbps => -b192
    

METHODS

bitrate()

Set or get the command-line options to pass to the encoder for a desired bitrate.

stream_parms()

Return the parameters to append to an MP3 playlist entry in order to activate resampling.

presets()

Get the names of the bitrate presets specified by the ResamplePresets configuration variable, or the default names. Called with an argument equal to the name of a preset, returns the command-line arguments to pass to the encoder.

sample_popup()

Draws the popup menu with the sample rate options.

BUGS

Also, the module does not function properly unless CacheDir is set and points to a directory which exists and is writeable by the Apache server.

ACKNOWLEDGEMENTS

FLAC and Shorten support added by Caleb Epstein <cae@bklyn.org>.

AUTHOR

This module is distributed under the same terms as Perl itself. Feel free to use, modify and redistribute it as long as you retain the correct attribution.

SEE ALSO