$Id: README 913 2010-01-23 21:07:49Z varenet $

Copyright (C) 2002-2006 Regis BOUDIN, (C) 2002-2010 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 version 2.1, as published by the Free Software Foundation.

    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., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301, USA

** 1. Presentation **

mod_musicindex is an Apache module initially 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, FLAC, Ogg Vorbis or
MP4/AAC files, including sorting them on various fields, streaming and/or
downloading them, constructing playlists and searching them.

It features a cache system, currently based on mirroring the tree
structure handled by the module, storing files data using a flat text
files backend, or a (currently experimental) MySQL database.

It can also delegate streaming of files to e.g. 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. The file name must match the following scheme:
"(.){cover,folder}.{jpg,png,gif}"
eg: "cover.png" or ".folder.jpg" are valid names.

The musicindex directory contains a sample musicindex.css file. For more
information, see the end of this file.

This software will certainly see more development, so any feedback would be
greatly appreciated.

Don't hesitate to mail musicindex@pateam.org with subject "mod_musicindex"


** 2. Configuration **

a) Loading the module:

To use this module, it has to be enabled in Apache configuration. If you got
this module already packaged, this is probably already done. Otherwise, here
is a sample Apache 1.3 configuration line:
-------------------------------------------------
LoadModule musicindex_module /usr/lib/apache/1.3/mod_musicindex.so
-------------------------------------------------
The path might be different on your system, check your system's documentation.

b) Setting up look&feel data:

The style files (a CSS stylesheet and a few icons) need to be accessible under
"/musicindex" (mod_musicindex's "data directory") on the webserver. Yet they are
typicaly installed in /usr/share/mod_musicindex. You have two options here:
1) Add the following alias to your Apache configuration :
-------------------------------------------------
Alias /musicindex "/usr/share/mod_musicindex"
<Directory /usr/share/mod_musicindex">
    Order allow,deny
    Allow from all
</Directory>
-------------------------------------------------
2) Copy the files to some place and have this place accessible as "/musicindex"
   on the webserver, eg using the above mentioned Alias scheme.

Mind that files in /usr/share/mod_musicindex might be overwritten on module
upgrades, thus if you want to modify these files to suit your needs, you most
likely *want* to use the second method.
In that case, if the module finds the following icons in its data directory, it
will use them instead of the remote ones, also disabling remote check links:
- valid-xhtml11
- vcss
- loveRss.gif

If you don't know what this is about, go for the first option and paste the
configuration snippet to your Apache configuration file.

c) Configuring the features:

This is fairly simple; here is an exhaustive Apache configuration example.
Of course you don't need to add everything, since many things are configured by
default (see below).
-------------------------------------------------
<Directory /var/www/MP3/>
    Options		Indexes MultiViews FollowSymlinks
    AllowOverride	Indexes
# Can be overriden in .htaccess
    MusicIndex		On +Stream +Download +Search -Rss -Tarball
    MusicSortOrder      album disc track artist title length bitrate freq filetype filename uri
    MusicFields		title artist album length bitrate
    MusicPageTitle	Myname
    MusicDefaultCss	musicindex.css
    MusicDirPerLine	3
# Can only be set in apache configuration
    MusicDefaultDisplay	HTML
    MusicIndexCache	file://tmp/musicindex
    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.

The MusicIndex Option replaces altogether MusicLister, MusicAllowDownload,
MusicAllowStream, MusicAllowSearch, and MusicAllowRss. To enable or disable the
module, give On or Off as an option. To enable or disable the other features,
just give '+' or '-' followed by Download, Stream, Search, Rss or Tarball.
You can have all of them on the same line as shown in the exemple.
Note that the old options NO LONGER WORK and have been removed.
The new (experimental) tarball download feature allows to download the whole
content of directories or playlist by generating a tar archive on the fly.
Note: tarball generation can be allowed for files that are not allowed for
download. That is to say that you can deny the right to download each file
separately, yet allow them to be downloaded as part of a tar archive.

If you set AllowOverride Indexes (instead of None), it makes it possible to
enable, disable or configure the options marked as being overridable in
.htaccess files.

The values shown in this example are the default ones for MusicSortOrder,
MusicFields, MusicDefaultCss, MusicCookieLife and MusicDirPerLine, 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, freq, artist, album, title, filename, date, filetype, genre and uri
(uri is the full pathname of a given file, and is only effective in
MusicSortOrder).

MusicCookieLife sets the lifetime in seconds of the cookie for custom playlists,
which are stored in a cookie on the client-side, and are thus subject to the
client's browser limitation with respect to cookie size (impacting in particular
the number of songs that can be added to a custom playlist). Generally, you
shouldn't expect to be able to add much more than a few dozen songs to a custom
playlist.

MusicDirPerLine is pretty much self-explanatory. If using negative values, the
icons below each folder in the listing will no longer be displayed, which has a
significant positive impact on the module's performance (see INSTALL for details).

The RSS feed can be obtained by appending "?action=RSS" to the URL. By default,
the maximum number of items in the RSS feeds is set to 20.
If you want more entries to be displayed, you can append "?limit=X&action=RSS"
to the URL instead, X being the number of items you want.

Thanks to Mattia Dongili's work, you can also get a podcast by using
"action=podcast" instead of "action=RSS". The feature is enabled when you allow
RSS streams in the module.

Note that setting an icecast server does not automatically enable streaming
anymore. You have to manually enable it. (This can be useful if you want to
use icecast, but enable streaming only for some subdirectories).
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).

Please also note that disallowing file downloads while still granting
stream permission is purely cosmetic: to Apache, both operations (stream and
download) are actually the same one. No need to add that as soon as bytes are
streamed to the internet, they can be saved on the remote computer, so there is
no real point in trying to harden separation between stream and download either.

MusicIndexCache sets up the cache subsystem. It must be in the form
'backend://parameters'. Here are the backends configuration syntaxes:
- flat file: 'file://absolute/path/to/cache/tree'
  This path must EXIST and be read/write accessible for the webserver's uid.
- mysql db: 'mysql://user[:password]@hostname/database'
  password is optional. Module must have full access to the database:
  SELECT, INSERT, UPDATE, DELETE, CREATE, INDEX, DROP, LOCK TABLES
  It will create 3 tables: musicindexdirs, musicindexfiles, musicindexformat.
  Note: with the MySQL cache backend, search becomes dependent on mysql's
  fulltext search restrictions. In particular, the stopword list applies;
  words present in 50% or more of the rows do not match; and the minimum (and
  maximum) length of words to match apply (this is a mysql configuration option.
  Minimum length for words to be considered usually defaults to 4 or 5).
  See http://dev.mysql.com/doc/refman/4.1/en/fulltext-fine-tuning.html
  This backend has been tested but is still considered EXPERIMENTAL.

CSS : additional css files in mod_musicindex's data directory will be automatically
detected and made available as alternate stylesheets. The default one is
musicindex.css (unless MusicDefaultCss is set otherwise).

MusicDefaultDisplay gives you the possibility to chose which output will be the
default one. The default is of course HTML, or you can change it to RSS, so that
you can only browse RSS data. This feature will be expanded later.


** 3. Internationalization **

mod_musicindex is gettext-capable. We currently have French, Italian and
Brazilian-Portuguese translations, feel free to submit more languages.
mod_musicindex will use the default locale used by apache (usually the system's
default locale). You can change that by doing eg: "env LANG=fr apache".
Non existent locales will use the default English one.


** 4. Acknowledgements **

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.

We are in need of a decent (and free) iconset. If you think you can help us,
please contact us!

The current stylesheet (musicindex.css) was initially inspired from the
original Apache::MP3 one. If you have more interesting ones you think are
worth being distributed, please don't hesitate to submit them, as long as they
are GPL-compatible.

The mod_musicindex devel team.