$Id: INSTALL 884 2009-09-18 12:04:55Z varenet $

If you are upgrading from a previous version, read the UPGRADING file!

This module is pure C and works with Apache 1.3 and Apache 2

The autotools will automatically detect what is available on your system,
but here is the list of the supported audio codecs so far, with the dependencies
to enable them (Debian packages names are given as references) :

 - For audio codecs:
   * Ogg Bitstream Library Development (libogg-dev)
   * Vorbis Library Development (libvorbis-dev)
   * ID3 tag reading library from the MAD project (libid3tag0-dev)
   * MPEG audio decoder development library (libmad0-dev)
   * Free Lossless Audio Codec - C development library (libflac-dev)
   * The MPEG4 library (libmp4v2, no debian package: http://code.google.com/p/mp4v2/)
 - For archive support:
   * The libarchive library (libarchive-dev)
  
 AND

 - If you build for Apache 1.3:
   * Apache webserver development kit (apache-dev)
 - If you build for Apache 2:
   * Development headers for apache2 (apache2-dev)
   * The Apache Portable Runtime Library (libapr1-dev)
 
By default, the module will enable support for all codecs and backends, with
respect to the libraries installed on your system. You can change that and
other settings by using the following configure flags:
 * --disable-mp3	To disable MP3 support (libmad0-dev, libid3tag0-dev) (*)
 * --disable-vorbis	To disable Ogg Vorbis support (libogg-dev, libvorbis-dev)
 * --disable-flac	To disable FLAC support (libflac-dev)
 * --disable-mp4	To disable MP4 support (libmp4v2)
 * --disable-filecache	To disable flat file cache system
 * --disable-mysqlcache	To disable mysql cache system (libmysqlclient-dev)

By default, the module will be built for the version of Apache hinted by apxs.
You can set the apxs tool to be used with the following configure option:
 --with-apxs=/path/to/apxs

A few words about performance:
If you are going to use mod_musicindex on a very busy server with lots of
music, there are a few things that you can tweak to improve performance:
- First, only build the codecs that you /really/ need. This will avoid
  unnecessary lookups on new files.
- PRETTY_FOLDERS: if disabled (using negative MusicDirPerLine), the "stream,
  shuffle, download" icons located under the directories names in the listing
  will no longer be displayed (but of course those under the main directory
  name in the header banner will still remain), as enabling these
  icons has a major impact on performance. To give you an idea, on a g4@500Mhz,
  browsing a directory containing 350 subdirectories and 0 file with this
  option enabled takes ~30s, and only about 3s when it's disabled. That's a
  10 to 1 ratio! So if you have directories with a great number of
  subdirectories, consider disabling it.

NB: if you build the module without certain filetype supports, and then rebuild
    it again with added filetype supports, the cache might become corrupted:
    while running without e.g. MP4 support, any folder containing MP4 data will
    be recorded in the cache without the MP4 files and will be marked in cache
    as "up to date". The module has no way to keep track of which filetypes were
    or were not supported when the cache was created (at least not for now).

To install, 'make install', then edit your apache config and reload the server.

The Makefile will install the various web-related files (css file, icons) in
/usr/share/mod_musicindex.
You should then add an alias or copy this directory to your document root,
depending on whether you wish to modify them or not.

See the configuration section in the README file.

Enjoy!

Known supported OSes:
	* GNU/Linux
	* FreeBSD (port available)
	* OpenBSD (port available)
	* NetBSD
	* MacOS X
	* Solaris
	
If you have successfully used mod_musicindex with an OS not mentionned here,
please report to musicindex@pateam.org, with "mod_musicindex" in the subject field.

(*) Note:
There's an outstanding bug in libid3tag that will create an infinite loop that will
itself eat all available memory. This bug is fixed in the Debian package, using the
following patch from Kurt Roeckx <kurt@roeckx.be>:

diff -urNad libid3tag-0.15.1b/utf16.c /tmp/dpep.tKvO7a/libid3tag-0.15.1b/utf16.c
--- libid3tag-0.15.1b/utf16.c  2006-01-13 15:26:29.000000000 +0100
+++ libid3tag-0.15.1b/utf16.c 2006-01-13 15:27:19.000000000 +0100
@@ -282,5 +282,18 @@
 
   free(utf16);
 
+  if (end == *ptr && length % 2 != 0)
+  {
+     /* We were called with a bogus length.  It should always
+      * be an even number.  We can deal with this in a few ways:
+      * - Always give an error.
+      * - Try and parse as much as we can and
+      *   - return an error if we're called again when we
+      *     already tried to parse everything we can.
+      *   - tell that we parsed it, which is what we do here.
+      */
+     (*ptr)++;
+  }
+
   return ucs4;
 }
