$Id: README,v 1.33 2004/05/29 11:53:39 varenet Exp $

Copyright: 2002-2004 Regis BOUDIN, Thibaut VARENE

    This package is free software; you can redistribute it and/or
    modify it under the terms of the GNU Lesser General Public
    License as published by the Free Software Foundation; either
    version 2.1 of the License, or (at your option) any later version.

    This package is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
    Lesser General Public License for more details.

    You should have received a copy of the GNU Lesser General Public
    License along with this package; if not, write to the Free Software
    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307  USA


mod_musicindex is an Apache module aimed at being a C implementation of the
Perl module Apache::MP3 (http://search.cpan.org/dist/Apache-MP3/).

It allows nice displaying of directories containing MP3 or Ogg Vorbis files,
including sorting them on various fields, streaming and/or downloading them,
constructing playlists and searching them.
It features a cache subsystem, currently based on mirroring the tree
structure handled by the module, storing files data into flat text files.
It can also delegate streaming of files to an icecast server, as long as they
can be accessed using the same URI ("staticdir" option).
If you add a picture of a CD cover in a directory, it will be displayed in the
upper left corner of the web page and as a thumbnail in the parent directory.
The file must be named "cover.jpg", "cover.png" or "cover.gif".

A possibility to build cross-directories playlists is under development.
This feature is a work in progress but basically works, even though it still
needs to be tested.

The musicindex directory contains a sample musicindex.css file. For more
information, see below.

This is a pre-final release, use it at your own risks.

This software is under heavy development and testing, and feedback would be
greatly appreciated.

Don't hesitate to mail puffin@esiee.fr with subject "mod_musicindex"

Here's a sample httpd.conf extract:

LoadModule musicindex_module /usr/lib/apache/1.3/mod_musicindex.so
# Replace the above line with what make install will tell you.
<Directory /var/www/MP3/>
    Options Indexes MultiViews FollowSymlinks
    AllowOverride Indexes
    MusicLister On
    MusicSortOrder      album disc track artist title length bitrate filetype filename uri
    MusicFields		title artist length bitrate
    MusicAllowDownload Off
    MusicAllowStream On
    MusicAllowSearch On
    MusicCssDefault	musicindex.css
    MusicCachePath	/tmp/musicindex
    MusicPageTitle	Myname
    MusicIceServer	[ice.domain.my]:8000
    MusicCookieLife	300
</Directory>

Please note that, as any configuration example, it must adapted to your own
system and needs. Please refer to necessary manpages, documentation and howtos.

If you set AllowOverride Indexes (instead of None), it makes it possible to
enable, disable or configure most of the options (actually, all of them, except
the last 4 of the above example) in .htaccess files (it is a brand new feature,
not well tested, do not hesitate to report any remark/suggestion).

The values showed in this example are the default ones for MusicSortOrder,
MusicFields, MusicPageTitle, MusicCssDefault and MusicCookieLife, so they only
need to be declared if you want to use different ones. All fields aren't
mandatory, as you can see, so you can use "MusicSortOrder album disc track" for
instance.

Allowed values for MusicSortOrder and MusicFields are : track, disc, length,
bitrate, artist, album, title, filename, date, filetype, genre and uri (which
is the full pathname of a given file).

MusicCookieLife sets the lifetime in seconds of the cookie for custom playlists.

The search system is quite experimental, as well as cache subsystem.
To disable any of these features, just remove the appropriate line in the conf
example above, or set them to "Off" instead of "On".
Note that setting an icecast server automatically enable streaming.
If the MusicIceServer begins with a semicolon ':', the module assumes that
the icecast server is running on the same host than the webserver, and the
number following the colon is the port which icecast listens for clients,
(quite usefull when you access the machine with different addresses).

CSS : additional css files in the musicindex directory will be automatically
detected and made available as alternate stylesheets. The default one is
musicindex.css (unless MusicCssDefault is set otherwise). If you use a packaged
version of this module and want to use a different default stylesheet than the
one we provide, you are strongly encouraged to use the configuration option, as
an update of your disribution package would probably overwrite the
musicindex.css file.


NB: Icons were downloaded from http://art.gnome.org/icons.php.
From http://art.gnome.org/icons.php:
 Most of the icons of this section were done by Tuomas "tigert" Kuosamen
 and Jakub "jimmac" Steiner. Some icons were done by Garrett LeSage, Ed
 Halley, and Roman "star" Beigelbeck.

The current stylesheet (musicindex.css) was originally inspired from the
original Apache::MP3 one.

The mod_musicindex devel team.
