Apache::MP3 version 2.0x

This module takes a hierarchy of directories containing MP3 files and
presents it as a browsable song library for streaming over the web.
It requires the Apache web server, the mod_perl embedded Perl
interpreter, and the MP3::Info module.

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. Users can
also stream the entire contents of a directory, or select a subset of
songs to play.

A DEMO is available at http://www.modperl.com/Songs.  In this demo,
stream time is limited to 30 seconds in order to avoid copyright
infringement.

See the "screenshots" directory for some pictures of Apache::MP3 in
action.

See below for CHANGES.

INSTALLATION

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
 AddType audio/playlist m3u M3U

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 F<apache_mp3> directory
from the Apache-MP3 distribution.

You may change the location of this directory by setting the
I<BaseDir> configuration variable.  See the I<Customizing> section for
more details.

4. Set Apache::MP3 to be the handler for the MP3 directory

In httpd.conf or access.conf, create a E<lt>LocationE<gt> or
E<lt>DirectoryE<gt> 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>

If you would prefer an MP3 file listing that allows the user to sort
it in various ways, set the handler to use the Apache::MP3::Sorted
subclass instead.  A further elaboration is Apache::MP3::Playlist,
which uses cookies to manage a persistent playlist for the user.

5. Load MP3::Info in the Perl Startup file (optional)

For the purposes of faster startup and memory efficiency, you may load
the MP3::Info module at server startup time.  If you have a mod_perl
"startup" file, enter these lines:

  use MP3::Info;
  use Apache::MP3;

6. 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
hierarchically by artist and/or album name.

If you place a file named "cover.jpg" in any of the directories, that
image will be displayed at the top of the directory listing.  You can
use this to display cover art.

If you place a list of .mp3 file names in a file with the .m3u
extension, it will be treated as a playlist and displayed to the user
with a distinctive icon.  Selecting the playlist icon will download
the playlist and stream its contents.  The playlist must contain
relative file names, but may refer to subdirectories, as in this
example:

  # file: folk_favorites.m3u
  Never_a_Moment_s_Thought_v2.mp3
  Peter Paul & Mary - Leaving On A Jet Plane.mp3
  Simon and Garfunkel/Simon And Garfunkel - April Come She Will.mp3

7. Set up an information cache directory (optional)

In order to generate its MP3 listing, Apache::MP3 must open each sound
file, extract its header information, and close it.  This is time
consuming, particularly when recursively generating playlists across
multiple directories.  To speed up this process, Apache::MP3 has the
ability cache MP3 file information in a separate directory area.

To configure this, choose a directory that the Web server has write
access for, such as /usr/tmp.  Then add a configuration variable like
the following to the <Location> directive:

 PerlSetVar  CacheDir       /usr/tmp/mp3_cache

If the designated directory does not exist, Apache::MP3 will attempt
to create it, limited of course by the Web server's privileges.  You
may need to create the mp3_cache directory yourself if /usr/tmp is not 
world writable.

TESTING IT

Open up the MP3 URL in your favorite browser.  You should be able to
see directory listings, and download and stream your songs.  If things
don't seem to be working, checking the server error log for messages.

Run "perldoc Apache::MP3" for more configuration information.

CHANGES

Revision history for Perl extension Apache::MP3.

2.14 Sat Dec 30 23:10:32 EST 2000
	- Fixed documentation to indicate that AddType requires dots before the
		.mp3 and .MP3 extension names.
	- Made the cache writing taint safe.
	- Fixed generation of extended playlists to work with earlier versions
		of WinAmp.
	- Added playlist and local streaming patches kindly provided by
		Jamie O'Shaughnessy.
	- Fixed display of directory path links when the current directory has same
		name as a parent directory.

2.13 Thu Nov 30 12:17:31 EST 2000
	- Patch from Jeffrey Sumler to prevent faults when streaming files containing
		regular expression metacharacters
	- Fix to prevent entire directory from being streamed when the directory
		has same name as the desired MP3 file (Jeffrey Sumler identified problem).

2.12 Tue Nov 21 08:39:15 EST 2000
	** IMPORTANT NOTE **
	I have normalized field names and added some new fields.  In particular, "kbps" has
	been renamed "bitrate".  If you are using the mp3info caching feature, please delete 
	your cache directory so that the new fields are correctly cached

	-Check for invalid songs in playlist and refuse to play them.
	-Added Jeffrey Seifert's patch for cover art.  You can now place a file named
		"cover.jpg" in an album subdirectory and have it appear next to
		the album's name.
	-Added Chris Nandor's patch for Accept-Range so that certain players can
		fetch selected portions of the song (in theory at least).
	-Added Kee Hinkley's extended playlist patch, which allows WinAmp (and other players?)
		to display the title and duration of the song in the playlist.
	-Added Gary Johnston's patch which fixes truncated songs when streaming from a
		Windows server (the old binmode() trap).

2.11 Sat Sep  9 18:04:55 EDT 2000
	Added Tim Ayer's patches for sorting.  Now can sort playlists 
		on multiple fields (nice!)
	Detect when playlist cookie is full, alert user, and suppress 
		further attempts to add to playlist.
	Documentation fixes.

2.10 Sun Sep  3 20:29:41 MET DST 2000
	Ooops.  Playlist.pm was inadvertently left out; now it's back in.
	Fixed divide by zero error on corrupt MP3 files.

2.08 Wed Aug 30 22:39:38 EDT 2000
	Added playlist functionality.
	Temporarily changed form POST method to GET to work around an (apparent) bug
		in mod_perl's ability to redirect from a POST to a GET (Apache hangs
		after returning from handler).  It "used to work" just fine.
	Suppressed appearance of authentication information
		XMMS/WinAmp scrolling marquee

2.07 Sat Aug 26 13:49:30 EDT 2000
	Fixed caching routines so that information about failed mp3_info()
		lookups is cached as well.

2.06 Fri Aug 25 23:39:00 EDT 2000
	Fixed bug in [stream] button that caused module to fail on
		directories containing parentheses and other RE
		metacharacters

2.05 Fri Aug 25 08:10:04 EDT 2000
	Changed directory layout to get faster loading
	Now supports HTTP authentication (passwords)
	Supports directories with spaces and funny characters

2.04 Tue Aug 22 04:38:07 PDT 2000
	Completely revamped to make more object oriented
	Apahce::MP3::Sorted subclass
	Added help page
	
2.02 Sun May 28 12:18:37 2000
	More information on MP3::Info segfaults
	Added installation directions to README

2.01 Sat May 27 00:32:18 2000
	Added information on a workaround for random segfaults related to MP3::Info

2.00  Sat May 27 00:00:09 2000
	- original version; created by h2xs 1.20 with options
		-A -X -f -n Apache-MP3

1.00  February 2000
      Old defunct version.


AUTHOR

Lincoln Stein, <lstein@cshl.org>
