NAME
Apache::MP3::Resample - Downsample MP3/FLAC/Shorten files during streaming
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
Apache::MP3::Resample subclasses Apache::MP3::Playlist to allow the user to downsample audio files before streaming them. This allows users on slower connections to stream songs. When this module is installed, a menu of bitrates is presented in the upper right-hand corner of the screen. The user can choose from one of the bitrates, or select a mode that performs no resampling. The selected bitrate is maintained in a persistent cookie so that resampling is performed whenever the user returns to the site.
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
This class recognizes the following two configuration variables in addition to those recognized by its superclasses.
- 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
This module overrides the inherited run(), open_file() and directory_top() methods. It adds the following new 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
When the external program is invoked to downsample the MP3 data, its standard error is redirected to /dev/null. This prevents Lame's informational messages from gumming up the server error log, but also prevents the system from giving you helpful diagnostic messages, such as "file not found". If you are having trouble with the downsampling, set the configuration variable VerboseMP3Encoder to a true value in order to see the standard error messages.
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
Many people have requested this feature and/or proposed implementations. Thank you all for your help.
FLAC and Shorten support added by Caleb Epstein <cae@bklyn.org>.
AUTHOR
Copyright 2000, Lincoln Stein <lstein@cshl.org>.
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.