Apache-MP3
view release on metacpan or search on metacpan
=item DirectoryIcon I<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 I<CoverImageSmall> image
into the directory that you want to customize.
=item PlaylistIcon I<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.
=item PlaylistImage I<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 I<PlaylistIcon> is used instead.
=item Fields I<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 I<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.
=item HomeLabel I<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.
=item LongList I<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.
=item MissingComment I<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
=item PathStyle I<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.
=item SongIcon I<URL>
Set the icon displayed at the beginning of each line of the MP3 file
list, "sound.gif" by default.
=item SubdirColumns I<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.
=item PlaylistColumns I<integer>
The number of columns in which to display playlists. Default 3.
=item Stylesheet I<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.
=item TitleIcon I<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 I<BaseDir>.
=item DefaultLanguage I<languagetag>
This determines what language the interface should try appearing in,
and stream songs.
=item $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.
=item $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.
=item $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.
=item $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.
=item $mp3->send_playlist($urls,$shuffle)
This method generates a playlist that is sent to the browser. It is
called from various places. C<$urls> is an array reference containing
the MP3 URLs to incorporate into the playlist, and C<$shuffle> is a
flag indicating that the order of the playlist should be randomized
prior to sending it. No return value is returned.
=item @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.
=item @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.
=item $mp3->playlist_list_bottom($playlists)
This method generates the footer at the bottom of the list
of playlists given by C<$playlists>. Currently it does nothing.
=item $mp3->playlist_list($playlists)
This method displays the playlists given by C<$playlists> in a nicely
formatted table.
=item $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().
=item $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.
=item $mp3->page_top($dir)
This method begins the HTML at the top of the page from the initial
<head> section through the opening <body>.
=item $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.
=item $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.
=item $mp3->generate_navpath_arrows($dir)
This method does the same, except that the parent directories are
displayed on a single line, separated by arrows.
=item $mp3->directory_bottom($dir)
This method generates the bottom part of the directory listing,
including the module attribution and help information.
=item $mp3->subdir_list_top($directories)
This method generates the heading at the top of the list of
subdirectories. C<$directories> is an arrayref containing the
subdirectories to display.
=item $mp3->subdir_list_bottom($directories)
This method generates the footer at the bottom of the list of
subdirectories given by C<$directories>. Currently it does nothing.
=item $mp3->subdir_list($directories)
This method invokes sort_subdirs() to sort the subdirectories given by
C<$directories> and displays them in a nicely-formatted table.
=item @directories = $mp3->sort_subdirs($directories)
This method sorts the subdirectories given in C<$directories> and
returns a sorted B<list> (not an arrayref).
=item $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().
=item $mp3->get_help
This subroutine generates the "Quick Help Summary" link at the bottom
of the page.
=item $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). C<$subdirectories>
is an array reference containing the subdirectories to display
=item $mp3->list_playlists($playlists)
This is the top-level subroutine for listing playlists. C<$playlists>
is an array reference containing the playlists to display.
=item $mp3->list_mp3s($mp3s)
This is the top-level subroutine for listing MP3 files. C<$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().
=item $mp3->mp3_table_header
This creates the first row (table headers) of the list of MP3 files.
=item $mp3->mp3_list_bottom($mp3s)
This method generates the buttons at the bottom of the MP3 file
listing. C<$mp3s> is a hashref containing information about each file.
=item $mp3->mp3_list($mp3s)
This routine sorts the MP3 files contained in C<$mp3s> and invokes
format_song() to format it for the table.
=item @buttons = $mp3->control_buttons
Return the list of buttons printed at the bottom of the MP3 file listing.
=item $arrayref = $mp3->format_song($song,$info,$count)
This method is called with three arguments. C<$song> is the path to
the MP3 file, C<$info> is a hashref containing tag information from
the song, and C<$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.
=item @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
This is a limited form of CGI::escape which does B<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.
=item @fields = $mp3->fields
Return the fields to display for each MP3 file. Reads the I<Fields>
configuration variable, or uses a default list.
=item $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().
=item $boolean = $mp3->write_cache($file,$info)
Writes MP3 information to cache. C<$file> and C<$info> are the path
to the file and its MP3 tag information, respectively. Returns a
boolean indicating the success of the operation.
=item $boolean = $mp3->download_ok
Returns true if downloading files is allowed.
=item $boolean = $mp3->stream_ok
Returns true if streaming files is allowed.
=item $boolean = $mp3->check_stream_client
Returns true if the module should check the browser/MP3 player for
whether it accepts streaming.
=item $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!
=item $boolean = $mp3->read_mp3_info
Returns true if the module should read MP3 info (true by default).
=item $seconds = $mp3->stream_timeout
Returns the number of seconds after which streaming should time out.
Used for "demo mode".
=item $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
=item $html = $mp3->home_label
Returns a fragment of HTML to use as the "Home" link in the list of
parent directories.
=item $style = $mp3->path_style
Returns the style of the list of parent directories. Either "arrows"
or "staircase".
=item $path = $mp3->cache_dir
Returns the directory for use in caching MP3 tag information
=item $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.
=item $dir = $mp3->default_dir
Returns the base directory used for resolving relative paths in the
directories to follow.
=item 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
=item $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.
=back
=head1 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
( run in 3.381 seconds using v1.01-cache-2.11-cpan-b16cb0d3907 )