/ 
Apache-MP3-2.00
River stage zero No dependents
/ Apache::MP3

NAME

Apache::MP3 - Generate browsable directories of MP3 files

SYNOPSIS

# httpd.conf or srm.conf
AddType audio/mpeg    mp3 MP3

# httpd.conf or access.conf
<Location /songs>
  SetHandler perl-script
  PerlHandler Apache::MP3
  PerlSetVar  AllowDownload     yes
  PerlSetVar  AllowStream       yes
  PerlSetVar  CheckStreamClient yes
</Location>

DESCRIPTION

This module takes an MP3 file directory hierarchy and makes it browsable.

MP3 files are displayed in a list that shows the MP3 title, artist, duration and bitrate. Subdirectories are displayed with "CD" icons. The user can download an MP3 file to disk by clicking on its title, stream it to an MP3 decoder by clicking on the "play" link, or select a subset of songs to stream by selecting checkboxes and pressing a "Play Selected" button. Users can also stream the entire contents of a directory.

NOTE: This version of Apache::MP3 is substantially different from the pre-2.0 version described in The Perl Journal. Specifically, the format to use for HREF links has changed. See Linking for details.

Installation

This section describes the installation process.

1. Prequisites

This module requires mod_perl and MP3::Info, both of which are available on CPAN.

2. Configure MIME types

Apache must be configured to recognize the mp3 and MP3 extensions as MIME type audio/mpeg. Add the following to httpd.conf or srm.conf:

AddType audio/mpeg mp3 MP3
3. Install icons and stylesheet

This module uses a set of icons and a cascading stylesheet to generate its song listings. By default, the module expects to find them at the url /apache_mp3. Create a directory named apache_mp3 in your document root, and copy into it the contents of the "icons" directory from the Apache-MP3 distribution.

The Customizing section describes how to choose a different location for the icons.

4. Set Apache::MP3 as handler for MP3 directory

In httpd.conf or access.conf, create a <Location> or <Directory> section, and make Apache::MP3 the handler for this directory. This example assumes you are using the URL /songs as the directory where you will be storing song files:

<Location /songs>
  SetHandler perl-script
  PerlHandler Apache::MP3
</Location>
5. Set up MP3 directory

Create a directory in the web server document tree that will contain the MP3 files to be served. The module recognizes and handles subdirectories appropriately. I suggest organizing directories by artist and or CD title. For directories containing multiple tracks from the same CD, proceed each mp3 file with the track number. This will ensure that the directory listing sorts in the right order.

Open up the MP3 URL in your favorite browser. If things don't seem to be working, checking the server error log for informative messages.

Customizing

Apache::MP3 can be customized in two ways: (1) by changing per-directory variables, and (2) changing settings in the Apache::MP3 cascading stylesheet.

Per-directory variables are set by PerlSetVar directives in the Apache::MP3 <Location> or <Directory> section. For example, to change the icon displayed next to subdirectories of MP3s, you would use PerlSetVar to change the DirectoryIcon variable:

PerlSetVar DirectoryIcon big_cd.gif
PerlSetVar IconDir URL

The IconDir variable sets the URL in which Apache::MP3 will look for its icons and stylesheet. The default is /apache_mp3. The directory name must begin with a slash and is a URL, not a physical directory.

PerlSetVar Stylesheet stylesheet.css

Set the URL of the cascading stylesheet to use, "apache_mp3.css" by default. If the URL begins with a slash it is treated as an absolute URL. Otherwise it is interpreted as relative to the IconDir directory.

PerlSetVar ParentIcon icon.gif

Set the URL of the icon to use for moving to the parent directory, "back.gif" by default. Here and in the other icon-related directives, URLs that do not begin with a slash are treated as relative to IconDir.

PerlSetVar TitleIcon icon.gif

Set the icon displayed next to the current directory's name, "cd_icon.gif" by default.

PerlSetVar DirectoryIcon icon.gif

Set the icon displayed next to subdirectories in directory listings, "cd_icon_small.gif" by default.

PerlSetVar SongIcon icon.gif

Set the icon displayed next to MP3 files, "sound.gif" by default.

PerlSetVar AllowDownload yes|no

You may wish for users to be able to stream songs but not download them to their local disk. If you set AllowDownload to "no", Apache::MP3 will not generate a download link for MP3 files. It will also activate some code that makes it very inconvenient (although not impossible) for users to download the MP3s.

The arguments "yes", "no", "true" and "false" are recognized. The default is "yes".

PerlSetVar AllowStream yes|no

If you set AllowStream to "no", users will not be able to stream songs or generate playlists. I am not sure why one would want this feature, but it is included for completeness. The default is "yes."

PerlSetVar CheckStreamClient yes|no

Setting CheckStreamClient to "yes" enables code that checks whether the client claims to be able to accept streaming MPEG data. This check isn't foolproof, but supports at least the most popular MP3 decoders (WinAmp, RealPlayer, xmms, mpg123). It also makes it harder for users to download songs by pretending to be a streaming player.

The default is "no".

You may change the appearance of Apache::MP3-generated pages by editing its cascading stylesheet. In addition to the normal tags, three style classes are defined:

TR.title

This class applies to the top line of the table that lists the MP3 files. It is used to give the line a distinctive mustard-colored background.

TD.normal

This class applies to even-numbered lines in the MP3 file table. It is used to give these lines a white background.

TD.highlight

This class applies to odd-numbered lines in the MP3 file table. It is used to give these lines a light blue background.

Linking

You may wish to create links to MP3 files and directories manually. The rules for creating HREFs are different from those used in earlier versions of Apache::MP3, a decision forced by the fact that the playlist format used by popular MP3 decoders has changed.

The following rules apply:

Download an MP3 file

Create an HREF using the unchanged name of the MP3 file. For example, to download the song at /songs/Madonna/like_a_virgin.mp3, use:

<a href="/songs/Madonna/like_a_virgin.mp3">Like a Virgin</a>
Stream an MP3 file

Replace the MP3 file's extension with .m3u and add the query string "play=1". Apache::MP3 will generate a playlist for the streaming MP3 decoder to load. Example:

<a href="/songs/Madonna/like_a_virgin.m3u?play=1">
        Like a streaming Virgin</a>
Play a whole directory

Append "/playlist.m3u?Play+All=1" to the end of the directory name:

<a href="/songs/Madonna/playlist.m3u?Play+All=1">Madonna Lives!</a>

The capitalization of "Play All" is significant. Apache::Mp3 will generate a playlist containing all MP3 files within the directory.

Play a set of MP3s within a directory

Append "/playlist.m3u?Play+Selected=1;file=file1;file=file2..." to the directory name:

<a
href="/songs/Madonna/playlist.m3u?Play+Selected=1;file=like_a_virgin.mp3;file=evita.mp3">
Two favorites</a>

Again, the capitalization of "Play Selected" counts.

SEE ALSO

MP3::Info, Apache

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.