$Id: README 1025 2013-04-09 11:17:37Z varenet $ Copyright (C) 2002-2006 Regis BOUDIN, (C) 2002-2013 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@slashdirt.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" Order allow,deny Allow from all ------------------------------------------------- NOTE: make sure to NOT add an ending '/' for the above paths. 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 - valid-rss.png 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). ------------------------------------------------- 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 ------------------------------------------------- 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 It's a known "feature" that search with the MySQL backend will also behave "naturally". i.e. searching for "leger" will return results for "leger" and "léger". 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.