MP3(3p)               User Contributed Perl Documentation              MP3(3p)



NAME
       Apache::MP3 - Generate streamable directories of MP3 and Ogg Vorbis
       files

SYNOPSIS
        # httpd.conf or srm.conf
        AddType audio/mpeg     mp3 MP3
        AddType audio/playlist m3u M3U
        AddType audio/x-scpls  pls PLS
        AddType application/x-ogg ogg OGG

        # httpd.conf or access.conf
        <Location /songs>
          SetHandler perl-script
          PerlHandler Apache::MP3
        </Location>

         # Or use the Apache::MP3::Sorted subclass to get sortable directory listings
        <Location /songs>
          SetHandler perl-script
          PerlHandler Apache::MP3::Sorted
        </Location>

         # Or use the Apache::MP3::Playlist subclass to get persistent playlists
        <Location /songs>
          SetHandler perl-script
         PerlHandler Apache::MP3::Playlist
        </Location>

       A demo version can be browsed at http://www.modperl.com/Songs/.

DESCRIPTION
       This module makes it possible to browse and search a directory
       hierarchy containing MP3, Ogg Vorbis, or Wav files, sort them on
       various fields, download them, stream them to an MP3 decoder like
       WinAmp, and construct playlists.  The display is configurable and
       subclassable.

       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, MP3::Info (to stream MP3 files),
           Ogg::Vorbis (to stream OggVorbis files), and Audio::Wav (for Wave
           files) all of which are available on CPAN.

           The module will automatically adjust for the absence of one or more
           of the MP3::Info, Ogg::Vorbis or Audio::Wav modules by inhibiting
           the display of the corresponding file type.

       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
            AddType audio/x-scpls  pls PLS
            AddType application/x-ogg ogg OGG
            AddType audio/wav wav WAV

           Note that you need extemely large amounts of bandwidth to stream
           Wav files, and that few audio file players currently support this
           type of streaming.  Wav file support is primarily intended to allow
           for convenient downloads.

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

           You may change the location of this directory by setting the
           BaseDir configuration variable.  See the 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 <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>

           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

           Likewise, if you place a list of shoutcast URLs into a file with
           the pls extension, it will be treated as a playlist and displayed
           to the user with a distinctive icon.  Selecting the playlist icon
           will contact the shoutcast servers in the playlist and stream their
           contents.  The playlist syntax is as in this example:

             [playlist]
             numberofentries=2
             File1=http://205.188.245.132:8038
             Title1=Monkey Radio: Grooving. Sexy. Beats.
             Length1=-1
             File2=http://205.188.234.67:8052
             Title2=SmoothJazz
             Length2=-1
             Version=2

           Example shoutcast files can be downloaded from
           http://www.shoutcast.com You can find a lot of good MP3 broadcasts
           there, most of them commercial-free.

           Apache::MP3 permits you to directly use CDDB data without embedding
           it in ID3 tags.  To take advantage of this feature, your MP3 files
           should have file names of this form: track-XX.mp3.  Then, place a
           CDDB index file in the same directory as the tracks and name it
           INDEX.  For example, you might execute this command

             cddbcmd cddb read soundtrack cb115c11 > INDEX

           to create an INDEX file for the Mulholland Drive soundtrack.  The
           32-bit disc ID can be obtained with a program such as cd-discid.

       7. Setting up the the MP3 search engine (optional)
           The search feature does a precache of the file information for your
           entire MP3 collection when you start the webserver.  For MP3 files,
           this includes the ID3 information, as well as any other information
           available.  This may be possible for other filetypes as well.

           The precaching process server start means that it will take more
           time to start your webserver -- noticeably longer if you have many
           MP3 files.  It also means that when you add new files under the
           'BaseDir' directory, they will not be searchable until you restart
           the server.  Thems the breaks.

           By default, the MP3 search feature is enabled.  In order to disable
           it, add a configuration variable like the following to the
           Apache::MP3 <Location> directive:

            PerlSetVar  DisableSearch  1

           Currently Apache::MP3 searching is not configurable and is hard-
           coded to allow you to search for artists, song names, genres,
           albums, and files.  The searchbox is also hard-coded to appear in
           the upper right corner of the page.  Contributions are welcome that
           will allow this feature to be customizable.

           The search data resides in a disk cache.  I haven't figured out a
           good way to check if the file is stale (if media files have changed
           or moved, for instance).  I'd recommend unlinking the search file
           from your perl.startup file.  The search cache is at
           $CacheDir/search.

       8. 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.

       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.

CUSTOMIZING
       Apache::MP3 can be customized in three ways: (1) by changing per-
       directory variables; (2) changing settings in the Apache::MP3 cascading
       stylesheet; and (3) subclassing Apache::MP3 or Apache::MP3::Sorted.

   Per-directory configuration variables
       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

       This following table summarizes the configuration variables.  A more
       detailed explanation of each follows in the subsequent sections.

       Table 1: Configuration Variables

        Name                  Value            Default
        ----                  -----            -------
        GENERAL OPTIONS
        AllowDownload         yes|no           yes
        AllowStream           yes|no           yes
        AllowPlayLocally      yes|no           yes
        CheckStreamClient     yes|no           no
        ReadMP3Info           yes|no           yes
        StreamTimeout         integer          0

        DIRECTORY OPTIONS
        BaseDir               URL              /apache_mp3
        CacheDir              path             -none-
        HelpImgURL            URL              apache_mp3_fig1.gif:374x292
        StreamBase            URL              -none-
        LocalNet              subnet           -none-

        DISPLAY OPTIONS
        ArrowIcon             URL              right_arrow.gif
        CoverImage            filename         cover.jpg
        CoverImageSmall       filename         cover_small.jpg
        PlaylistImage         filename         playlist.jpg
        DescriptionFormat     string           -see below-
        DirectoryIcon         URL              cd_icon_small.gif
        PlaylistIcon          URL              playlist.gif
        Fields                list             title,artist,duration,bitrate
        HomeLabel             string           "Home" (or translation)
        LongList              integer          10
        MissingComment        string           "unknown" (or translation)
        PathStyle             Staircase|Arrows Staircase
        SongIcon              URL              sound.gif
        SubdirColumns         integer          1
        Stylesheet            URL              apache_mp3.css
        TitleIcon             URL              cd_icon.gif
        DefaultLanguage       languagetag      en-US

   General Configuration Variables
       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 inconvenient (but not
           impossible) for users to download the MP3s.

           The module recognizes the arguments "yes", "no", "true" and
           "false".  The default is "yes".

           Note that this setting only affects MP3 files.  Other files,
           including cover art and playlists, can still be downloaded.

       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."

       AllowPlayLocally yes|no
           If you set AllowPlayLocally to "yes", then the playlists generated
           by the module will point to the physical files when handling
           requests from a user that happens to be working on the same
           machine.  This is more efficient, and allows the user to pause
           playback, fast forward, and so on.  Otherwise, the module will
           treat local users and remote users the same.  The default is "no".

       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".

       ReadMP3Info yes|no
           This controls whether to extract field information from the MP3
           files.  The default is "yes".

           If "no" is specified, all fields in the directory listing will be
           blank except for filename and description, which will both be set
           to the physical filename of the MP3 file.

       StreamTimeout integer
           For demo mode, you can specify a stream timeout in seconds.
           Apache::MP3 will cease streaming the file after the time specified.
           Because this feature uses the average bitrate of the song, it may
           be off by a second or two when streaming variable bitrate MP3s.

   Configuration Variables Affecting Paths and Directories
       BaseDir URL
           The BaseDir variable sets the URL in which Apache::MP3 will look
           for its icons and stylesheet.  You may use any absolute local or
           remote URL. Relative URLs are not accepted.

           The default is "/apache_mp3."

       CacheDir path
           This variable sets the directory path for Apache::MP3's cache of
           MP3 file information.  This must be an absolute path in the
           physical file system and be writable by Apache.  If not specified,
           Apache::MP3 will not cache the file information, resulting in
           slower performance on large directories.

       HelpImgURL URL:widthxheight
           The URL of the image that's inlined on the page that appears when
           the user presses the "Quick Help Summary" link at the bottom of the
           page.  You can declare the size of this image by adding ":WxH" to
           the end of the URL, where W and H are the width and height,
           respectively.

           Default: apache_mp3_help.gif:614x498

           Note: I prepared this image on an airplane, so it isn't as clean as
           I would like.  Volunteers to make a better help page are welcomed!

       StreamBase URL
           A URL to use as the base for streaming.  The default is to use the
           same host for both directory listings and streaming.  This may be
           of use when running behind a firewall and the web server can't
           figure out the correct address for the playlist automatically.

           Example:

           If the song requested is
           http://www.foobar.com/Songs/Madonna_live.m3u?stream=1

           and StreamBase is set to http://streamer.myhost.net, then the URL
           placed in the playlist will be

            http://streamer.myhost.net/Songs/Madonna_live.m3u?stream=1

           The path part of the URL is simply appended to StreamBase.  If you
           want to do more sophisticated URL processing, use mod_rewrite or
           equivalent.

       LocalNet URL
           This configuration variable is used in conjunction with StreamBase
           to disable StreamBase for clients on the local network.  This is
           needed for firewall configurations in which the web server is
           accessed by one address & port by hosts behind the firewall, and by
           another address & port by hosts outside the firewall.

           The argument is a dotted subnet address, or a space-delimited list
           of subnets.  For example:

             PerlSetVar LocalNet "192.168.1 192.168.2 127.0.0.1"

           Address matching is done by matching the address from left to
           right, with an implied dot added to the end of the subnet address.
           More complex subnet matching using netmasks is desirable, but not
           implemented.

   Configuration Variables Affecting the Visual Display
       ArrowIcon URL
           Set the icon used for the arrows displayed between the components
           of the directory path at the top of the directory listing.

       CoverImage filename
           Before displaying a directory, Apache::MP3 will look inside the
           directory for an image file.  This feature allows you to display
           digitized album covers or other customized icons.  The default is
           "cover.jpg", but the image file name can be changed with
           CoverImage.  If the file does not exist, the image specified by
           TitleIcon will be displayed instead.

       CoverImageSmall filename
           Before displaying the list of subdirectories, Apache::MP3 will
           check inside of each for an image file of this name.  If one is
           present, the image will displayed rather than the generic
           DirectoryIcon.  The default is "cover_small.jpg".

       DescriptionFormat string
           The "Description" field, which is used both in the Description
           column of the directory index and in the metadata sent to the
           player during streaming, has a default format of
           title-artist-album.  The description is constructed in such a way
           that the hyphen is omitted if the corresponding field of the song's
           MP3 tag is empty.

           You can customize this behavior by providing a DescriptionFormat
           string.  These strings combine constant characters with %x format
           codes in much the way that sprintf() does.  For example, the
           directive shown below will create descriptions similar to [Madonna]
           Like a Virgin (1980).

             PerlSetVar DescriptionFormat "[%a] %t (%y)"

           The full list of format codes follows:

           Table 2: DescriptionFormat Field Codes

             Code         Description
             ----         -----------

             %a           Artist name
             %c           Comment
             %d           Duration, in format 00:00 (like 15:20 for 15 mins 20 sec)
             %f           Name of physical file (minus path)
             %g           Genre
             %l           Album name
             %m           Minutes portion of duration, usually used with %s
             %n           Track number
             %q           Sample rate, in kHz
             %r           Bitrate, in kbps
             %s           Seconds portion of duration, usually used with %m
             %S           Duration, expressed as total seconds
             %t           Title
             %y           Year

       DirectoryIcon URL
           Set the icon displayed next to subdirectories in directory
           listings, "cd_icon_small.gif" by default.  This can be overridden
           on a directory-by-directory basis by placing a CoverImageSmall
           image into the directory that you want to customize.

       PlaylistIcon URL
           Set the icon displayed next to playlists in the playlist listings,
           "playlist.gif" by default.  You can change this icon on a
           directory-by-directory basis by placing a file with this name in
           the current directory.

       PlaylistImage filename
           Before displaying a playlist, the module will check inside the
           current directory for an image file named "playlist.jpg" to use as
           its icon.  This directive changes the name of the playlist image
           file.  If no image is found, the icon specified by PlaylistIcon is
           used instead.

       Fields title,artist,duration,bitrate
           Specify what MP3 information fields to display in the song listing.
           This should be a list delimited by commas, "|" symbols, or any
           other non-word character.

           The following are valid fields:

           Table 3: Field Names For use with the Fields Configuration Variable

               Field        Description
               -----        -----------

               album        The album
               artist       The artist
               bitrate      The bitrate, expressed in kbps
               comment      The comment field
               duration     Duration of the song in hour, minute, second format
               description  Description as specified by DescriptionFormat
               filename     The physical name of the .mp3 file
               genre        The genre
               min          The minutes portion of the duration
               seconds      Total duration of the song in seconds
               sec          The seconds portion of the duration
               samplerate   The sampling rate, in KHz
               title        The title of the song
               track        The track number
               year         The album year

           Note that MP3 rip and encoding software differ in what fields they
           capture and the exact format of such fields as the title and album.
           Field names are case insensitive.

           Previous versions of this module used "kbps" instead of "bitrate".
           This has been changed.

       HomeLabel string
           This is the label for the link used to return to the site's home
           page.  You may use plain text or any fragment of HTML, such as an
           <IMG> tag.

       LongList integer
           The number of lines in the list of MP3 files after which it is
           considered "long".  In long lists, the control buttons are placed
           at the top as well as at the bottom of the table.  Defaults to 10.

       MissingComment string
           This is the text string to use when an MP3 or Vorbis comment is
           missing; it is "unknown" (or its translation) by default. For
           example, if the module is configured to display the artist name,
           but a music file is missing this field, "unknown" (or its
           translation) will be printed instead. To turn this feature off, use
           an argument of "off"; missing fields will then be blank.

             PerlSetVar MissingComment off

       PathStyle Staircase|Arrows
           Controls the style with which the parent directories are displayed.
           The options are "Staircase" (the default), which creates a
           staircase-style display (each child directory is on a new line and
           offset by 0.3 em).  The other is "Arrows", in which the entire
           directory list is on a single line and separated by graphic arrows.
           Try them both and choose the one you prefer.

       SongIcon URL
           Set the icon displayed at the beginning of each line of the MP3
           file list, "sound.gif" by default.

       SubdirColumns integer
           The number of columns in which to display subdirectories (the small
           "CD icons").  A value other than 1 suppresses the display of
           subdirectory access-time and modification-time info.  Default 1.

       PlaylistColumns integer
           The number of columns in which to display playlists. Default 3.

       Stylesheet URL
           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
           BaseDir directory.

       TitleIcon URL
           Set the icon displayed next to the current directory's name in the
           absence of a coverimage, "cd_icon.gif" by default.  In this, and
           the other icon-related directives, relative URLs are treated as
           relative to BaseDir.

       DefaultLanguage languagetag
           This determines what language the interface should try appearing
           in, if none of the languages from the browser's Accept-Language
           header can be supported.  For information on language tags, see
           I18N::LangTags::List.  Example value: "zh-cn" for PRC-style
           Chinese.

   Stylesheet-Based Configuration
       You can change the appearance of the page by changing the cascading
       stylesheet that accompanies this module, apache_mp3.css.  The following
       table describes the tags that can be customized:

       Table 4: Stylesheet Class Names

        Class Name           Description
        ----------           ----------

        BODY                 General defaults
        H1                   Current directory path
        H2                   "CD Directories" and "Song List" headings
        TR.title             Style for the top line of the song listing
        TR.normal            Style for odd-numbered song listing lines
        TR.highlight         Style for even-numbered song listing lines
        .directory           Style for the title of the current directory
        .subdirectory        Style for the title of subdirectories
        P                    Ordinary paragraphs
        A                    Links
        INPUT                Fill-out form fields

   Subclassing this Module
       For more extensive customization, you can subclass this module.  The
       Apache::MP3::Sorted module illustrates how to do this.

       Briefly, your module should inherit from Apache::MP3 (or
       Apache::MP3::Sorted) either by setting the @ISA package global or, in
       Perl 5.6 and higher, with the "use base" directive.  Your module can
       then override existing methods and define new ones.

       This module uses the mod_perl method invocation syntax for handler
       invocation.  Because of this, if you override the handler() method, be
       sure to give it a prototype of ($$).  If you override new(), be sure to
       place the Apache::Request object in an instance variable named 'r'.
       See the MP3.pm module for details.

       One implication of using the method invocation syntax is that the
       Apache::MP3 object is created at server configuration time.  This means
       that you cannot tweak the code and simply restart the server, but must
       formally stop and relaunch the server every time you change the code or
       install a new version.  This disadvantage is balanced by a savings in
       memory consumption and performance.

       See The Apache::MP3 API below for more information on overriding
       Apache::MP3 methods.

Linking to this module
       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>

       Stream a 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.

       Stream a directory heirarchy recursively
           Append "/playlist.m3u?Play+All+Recursive=1" to the end of the
           directory name:

            <a href="/Songs/HipHop/playlist.m3u?Play+All+Recursive=1">Rock me</a>

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

       Shuffle and stream a directory
           Append "/playlist.m3u?Shuffle+All=1" to the end of the directory
           name:

            <a href="/Songs/HipHop/playlist.m3u?Shuffle+All">Rock me</a>

           Apache::MP3 will generate a playlist containing all MP3 files
           within the directory and all its subdirectories, and then randomize
           its order.

       Shuffle an entire directory heirarchy recursively
           Append "/playlist.m3u?Shuffle+All+Recursive=1" to the end of the
           directory name:

            <a href="/Songs/HipHop/playlist.m3u?Shuffle+All+Recursive=1">Rock me</a>

           Apache::MP3 will generate a playlist containing all MP3 files
           within the directory and all its subdirectories, and then randomize
           its order.

       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.

       Display a sorted directory
           Append "?sort=field" to the end of the directory name, where field
           is any of the MP3 field names:

            <a href="/Songs/Madonna/?sort=duration">Madonna lives!</a>

The Apache::MP3 API
       The Apache::MP3 object is a blessed hash containing a single key, "r",
       which points at the current request object.  This can be retrieved
       conveniently using the r() method.

       Apache::MP3 builds up its directory listing pages in pieces, using a
       hierarchical scheme.  The following diagram summarizes which methods
       are responsible for generating the various parts.  It might help to
       study it alongside a representative HTML page:

        list_directory()
        -------------------------  page top --------------------------------
           page_top()
           directory_top()
             display_searchform()

           process_search() page_bottom() if(user search)

           <CDICON> <DIRECTORY> -> <DIRECTORY> -> <DIRECTORY>
           [Shuffle All] [Stream All]

           list_subdirs()

                subdir_list_top()
                ------------------------------------------------------------
                <CD Directories (6)>

                subdir_list()
                      <cdicon> <title>   <cdicon> <title>  <cdicon> <title>
                      <cdicon> <title>   <cdicon> <title>  <cdicon> <title>

                subdir_list_bottom()  # does nothing
                ------------------------------------------------------------

           list_playlists()

                playlist_list_top()
                ------------------------------------------------------------
                <CD Playlists (6)>

                playlist_list()
                      <cdicon> <title>   <cdicon> <title>  <cdicon> <title>
                      <cdicon> <title>   <cdicon> <title>  <cdicon> <title>

                playlist_list_bottom()  # does nothing
                ------------------------------------------------------------

           list_mp3s()
                mp3_list_top()
                ------------------------------------------------------------
                <Song List (4)>

                mp3_list()
                    mp3_list_top()
                      mp3_table_header()
                         <Select>                  Title          Kbps

                      format_song() # called for each row
                         <icon>[] [fetch][stream]  Like a virgin  128
                         <icon>[] [fetch][stream]  American Pie   128
                         <icon>[] [fetch][stream]  Santa Evita     96
                         <icon>[] [fetch][stream]  Boy Toy        168

                    mp3_list_bottom()
                      [Play Selected] [Shuffle Selected]

           directory_bottom()
        -------------------------  page bottom -----------------------------

   Method Calls
       This section lists each of the Apache::MP3 method calls briefly.

       $response_code = handler($request)
           This is a the standard mod_perl handler() subroutine.  It creates a
           new Apache::MP3 object, and then invokes its run() method.

       $mp3 = Apache::MP3->new(@args)
           This is a constructor.  It stores the passed args in a hash and
           returns a new Apache::MP3 object.  If a single argument is passed
           it assumes that it is an Apache::Request object and stores it under
           the key "r".  You should not have to modify this method.

       $request = $mp3->r()
           Return the stored request object.

       $boolean = $mp3->is_local()
           Returns true if the requesting client is on the same machine as the
           server.

       $response_code = $mp3->run()
           This is the method that interprets the CGI parameters and
           dispatches to the routines that draw the directory listing,
           generate playlists, and stream songs.

       $response_code = $mp3->process_directory($dir)
           This is the top-level method for generating the directory listing.
           It performs various consistency checks on the passed directory URL
           and returns an Apache response code.  The list_directory() method
           actually does most of the formatting work.

       $response_code = $mp3->download_file($file)
           This method is called to download a file (not stream it).  It is
           passed the URL of the requested file and returns an Apache response
           code.  It checks whether downloads are allowed and if so allows
           Apache to take its default action.

       $response_code = $mp3->stream($file)
           This method is called to stream an MP3 file.  It is passed the URL
           of the requested file and returns an Apche response code.  It
           checks whether streaming is allowed and then passes the request on
           to send_stream().

       $fh = $mp3->open_file($file)
           This method is called by stream() to open the file to be streamed.
           It accepts a file path and returns a filehandle.  This can be
           overridden to do interesting things to the MP3 file, such as
           resample it or collect statistics.

       $mp3->send_playlist($urls,$shuffle)
           This method generates a playlist that is sent to the browser.  It
           is called from various places.  $urls is an array reference
           containing the MP3 URLs to incorporate into the playlist, and
           $shuffle is a flag indicating that the order of the playlist should
           be randomized prior to sending it.  No return value is returned.

       $mp3_info = $mp3->find_mp3s($recurse)
           This method searches for all MP3 files in the currently requested
           directory.  $recurse, if true, causes the method to recurse through
           all subdirectories.  The return value is a hashref in which the
           keys are the URLs of the found MP3s, and the values are hashrefs
           containing the MP3 tag fields recovered from the files ("title",
           etc.).

       @urls = $mp3->sort_mp3s($mp3_info)
           This method sorts the hashref of MP3 files returned from
           find_mp3s(), returning an array.  The implementation of this method
           in Apache::MP3 sorts by physical file name only.
           Apache::MP3::Sorted has a more sophisticated implementation.

       @mp3s = $mp3->load_playlist($playlist)
           This method loads a playlist file (.m3u) from disk and returns a
           list of MP3 files contained in the playlist.

       $mp3->playlist_list_bottom($playlists)
           This method generates the footer at the bottom of the list of
           playlists given by $playlists. Currently it does nothing.

       $mp3->playlist_list($playlists)
           This method displays the playlists given by $playlists in a nicely
           formatted table.

       $html = $mp3->format_playlist($playlist)
           This method formats the indicated playlist by creating a fragment
           of HTML containing the playlist icon, the stream links and the
           playlist name. It returns a HTML fragment used by playlist_list().

       $response_code = $mp3->list_directory($dir)
           This is the top level formatter for directory listings.  It is
           passed the URL of a directory and returns an Apache response code.

       $mp3->page_top($dir)
           This method begins the HTML at the top of the page from the initial
           <head> section through the opening <body>.

       $mp3->directory_top($dir)
           This method lists the top part of the directory, including the
           title, the directory navigation list, and the big CD Icon in the
           upper left.

       $mp3->generate_navpath_staircase($dir)
           This method generates the list of parent directories, displaying
           them as links so that the user can navigate.  It takes the URL of
           the current directory and returns no result.

       $mp3->generate_navpath_arrows($dir)
           This method does the same, except that the parent directories are
           displayed on a single line, separated by arrows.

       $mp3->directory_bottom($dir)
           This method generates the bottom part of the directory listing,
           including the module attribution and help information.

       $mp3->subdir_list_top($directories)
           This method generates the heading at the top of the list of
           subdirectories.  $directories is an arrayref containing the
           subdirectories to display.

       $mp3->subdir_list_bottom($directories)
           This method generates the footer at the bottom of the list of
           subdirectories given by $directories.  Currently it does nothing.

       $mp3->subdir_list($directories)
           This method invokes sort_subdirs() to sort the subdirectories given
           by $directories and displays them in a nicely-formatted table.

       @directories = $mp3->sort_subdirs($directories)
           This method sorts the subdirectories given in $directories and
           returns a sorted list (not an arrayref).

       $html = $mp3->format_subdir($directory)
           This method formats the indicated subdirectory by creating a
           fragment of HTML containing the little CD icon, the shuffle and
           stream links, and the subdirectory's name.  It returns an HTML
           fragment used by subdir_list().

       $mp3->get_help
           This subroutine generates the "Quick Help Summary" link at the
           bottom of the page.

       $mp3->list_subdirs($subdirectories)
           This is the top-level subroutine for listing subdirectories (the
           part of the page in which the little CD icons appears).
           $subdirectories is an array reference containing the subdirectories
           to display

       $mp3->list_playlists($playlists)
           This is the top-level subroutine for listing playlists. $playlists
           is an array reference containing the playlists to display.

       $mp3->list_mp3s($mp3s)
           This is the top-level subroutine for listing MP3 files.  $mp3s is a
           hashref in which the key is the path of the MP3 file and the value
           is a hashref containing MP3 tag info about it.  This generates the
           buttons at the top of the table and then calls mp3_table_header()
           and mp3_list_bottom().

       $mp3->mp3_table_header
           This creates the first row (table headers) of the list of MP3
           files.

       $mp3->mp3_list_bottom($mp3s)
           This method generates the buttons at the bottom of the MP3 file
           listing. $mp3s is a hashref containing information about each file.

       $mp3->mp3_list($mp3s)
           This routine sorts the MP3 files contained in $mp3s and invokes
           format_song() to format it for the table.

       @buttons = $mp3->control_buttons
           Return the list of buttons printed at the bottom of the MP3 file
           listing.

       $arrayref = $mp3->format_song($song,$info,$count)
           This method is called with three arguments.  $song is the path to
           the MP3 file, $info is a hashref containing tag information from
           the song, and $count is an integer containing the song's position
           in the list (which currently is unusued).  The method invokes
           format_song_controls() and format_song_fields() to generate a list
           of elements to be incorporated into cells of the table, and returns
           an array reference.

       @array = $mp3->format_song_controls($song,$info,$count)
           This method is called with the same arguments as format_song().  It
           returns a list (not an arrayref) containing the "control" elements
           of one row of the MP3 list.  The control elements are all the doo-
           dads on the left-hand side of the display, including the music
           icon, the checkbox, and the [fetch] and [stream] links.

       @array = $mp3->format_song_fields($song,$info,$count)
           This method is called with the same arguments as format_song().  It
           returns a list (not an arrayref) containing the rest of a row of
           the MP3 file display.  This will include the title, artist, and so
           forth, depending on the values of the Fields configuration.
           variable.

       ($directories,$mp3s) = $mp3->read_directory($dir)
           This method reads the directory in $dir, generating an arrayref
           containing the subdirectories and a hashref containing the MP3
           files and their information, which are returned as a two-element
           list.

       $hashref = $mp3->fetch_info($file)
           This method fetches the MP3 information for $file and returns a
           hashref containing the MP3 tag information as well as some
           synthesized fields.  The synthesized fields are track, which
           contains the same information as tracknum; description, which
           contains the title, album and artist merged together; and duration,
           which contains the duration of the song expressed as hours, minutes
           and seconds.  Other fields are taken directly from the MP3 tag, but
           are downcased (for convenience to other routines).

       Apache::MP3->path_escape($scalarref)
           This is a limited form of CGI::escape which does not escape the
           slash symbol ("/").  This allows URIs that correspond to
           directories to be escaped safely.  The escape is done inplace on
           the passed scalar reference.

       @fields = $mp3->fields
           Return the fields to display for each MP3 file.  Reads the Fields
           configuration variable, or uses a default list.

       $hashref = $mp3->read_cache($file)
           Reads the cache for MP3 information about the indicated file.
           Returns a hashref of the same format used by fetch_info().

       $boolean = $mp3->write_cache($file,$info)
           Writes MP3 information to cache.  $file and $info are the path to
           the file and its MP3 tag information, respectively.  Returns a
           boolean indicating the success of the operation.

       $result_code = $mp3->send_stream($file,$uri)
           The send_stream() method generates an ICY (shoutcast) header for
           the indicated file (given by physical path $file and URI $uri) and
           streams it to the client.  It returns an Apache result code
           indicating the success of the operation.

       $boolean = $mp3->download_ok
           Returns true if downloading files is allowed.

       $boolean = $mp3->stream_ok
           Returns true if streaming files is allowed.

       $boolean = $mp3->check_stream_client
           Returns true if the module should check the browser/MP3 player for
           whether it accepts streaming.

       $boolean = $mp3->is_stream_client
           Returns true if this MP3 player can accept streaming.  Note that
           this is not a foolproof method because it checks a variety of non-
           standardized headers and user agent names!

       $boolean = $mp3->read_mp3_info
           Returns true if the module should read MP3 info (true by default).

       $seconds = $mp3->stream_timeout
           Returns the number of seconds after which streaming should time
           out.  Used for "demo mode".

       $lines = $mp3->file_list_is_long
           Returns the number of lines in the MP3 file listing after which the
           list is considered to be "long".  When a long list is encountered,
           the module places the control buttons at both the top and bottom of
           the MP3 file table, rather than at the bottom only.  This method

       $html = $mp3->home_label
           Returns a fragment of HTML to use as the "Home" link in the list of
           parent directories.

       $style = $mp3->path_style
           Returns the style of the list of parent directories.  Either
           "arrows" or "staircase".

       $path = $mp3->cache_dir
           Returns the directory for use in caching MP3 tag information

       $int = $mp3->subdir_columns
           Returns the number of columns to use in displaying subdirectories
           (little CD icons).  If the return value is 1, directory access-time
           and modification-time are displayed.  If not equal to one, these
           data are suppressed.

       $dir = $mp3->default_dir
           Returns the base directory used for resolving relative paths in the
           directories to follow.

       miscellaneous directories and files
           The following methods return the values of their corresponding
           configuration variables, resolved against the base directory, if
           need be:

            stylesheet()   URI to the stylesheet file
            parent_icon()  URI to the icon to use to move up in directory
                                hierarchy (no longer used)
            cd_icon        URI for the big CD icon printed in the upper left corner
            song_icon      URI for the music note icons printed for each MP3 file
            arrow_icon     URI for the arrow used in the navigation bar
            help_url       URI of the document to display when user asks for help

           The following methods return the values of their corresponding
           configuration variables, resolved against the current directory,
           but if that fails, against the base directory.  This is useful for
           customizing the appearance icons on a per-directory basis.  For
           example, I like my directories containing shoutcast playlists to
           appear differently than my directories containing mp3 and m3u
           files.

            cd_list_icon   URI for the little CD icons in the subdirectory listing
            playlist_icon  URI for the playlist icon

       $boolean = $mp3->skip_directory($dir)
           This method is called during directory listings.  It returns true
           if the directory should not be displayed.  Currently it skips
           directories beginning with a dot and various source code management
           directories.  You may subclass this to skip over other directories.

BUGS
       Although it is pure Perl, this module relies on an unusual number of
       compiled modules.  Perhaps for this reason, it appears to be sensitive
       to certain older versions of modules.

   Random segfaults in httpd children
       Before upgrading to Apache/1.3.6 mod_perl/1.24, I would see random
       segfaults in the httpd children when using this module.  This problem
       disappeared when I installed a newer mod_perl.

       If you experience this problem, I have found that one workaround is to
       load the MP3::Info module at server startup time using the mod_perl
       perl.startup script made the problem go away.  This is an excerpt from
       my perl.startup file:

        # the !/usr/local/bin/perl
        ...
        use Apache::Registry ();
        use Apache::Constants();
        use MP3::Info;
        use Apache::MP3;
        use CGI();
        use CGI::Carp ();

   Can't use -d $r->finfo
       Versions of mod_perl prior to 1.22 crash when using the idiom -d
       $r->finfo (or any other idiom).  Since there are many older versions
       still out there, I have replaced $r->finfo with $r->filename and marked
       their locations in comments.  To get increased performance, change back
       to $r->finfo.

   Misc
       In the directory display, the alignment of subdirectory icon with the
       subdirectory title is a little bit off.  I want to move the title a bit
       lower using some stylesheet magic.  Can anyone help?

SEE ALSO
       Apache::MP3::Sorted, Apache::MP3::Playlist, MP3::Info, Apache,
       Apache::MP3::L10N

ACKNOWLEDGEMENTS
       Tim Ayers <tayers@bridge.com> found and fixed a misfeature in the way
       that playlists were sorted.

       Chris Nandor identified various bugs in the module and provided
       patches.

       Sean M. Burke (<sburke@cpan.org>) internationalized this module and
       coordinated the translators/localizers.  Each
       translator/localizer/consultant is thanked in the respective
       "Apache/MP3/L10N/langname.pm" file.

       Caleb Epstein <cae@bklyn.org>), for generalizing the resampling module.

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.



perl v5.12.2                      2003-10-06                           MP3(3p)
