playlist 0.2
Patrick Hearon <patrickh@rice.edu>

========
Overview
========

Playlist is a program that recurs through a directory tree (which begins at
a user-specified location in your filesystem) and builds html and plaintext
lists of files and directories it finds within. It compares filenames it
finds with a user-supplied suffix and only accepts files that match. You
can then, for example, use the plaintext files as mp3 playlists and use the
html files as a convenient way to browse your collection of songs using a
browser, be it kfm or MSIE or Netscape or whatever. (Yes, the files
generated work equally well with either Windows or Unix programs. I cannot
say what will happen on a Mac; maybe someone can tell me how it goes.)

============
Installation
============

First, if your perl is not found at /usr/bin/perl, you will need to alter
line 1 of playlist to point to perl's location on your system.

Next, move the playlist program to /usr/local/bin (or wherever you like, it
really doesn't matter). Edit the sample playlistrc file to suit your tastes
and move it to ~/.playlistrc. Make sure you have write access to the
directory you intend to use as your ROOTDIR. You're done.

=====
Usage
=====

playlist [--arg1=value1] [--arg2=value2] [...]

Args can be any of the following:

 --root, --rootdir     path to starting directory
 --ls,   --listsuffix  filename extension for lists (without preceding ".")
 --fs,   --findsuffix  filename extension to list (without preceding ".")
 --ml,   --masterlist  name of master list (relative to rootdir)
 --idx,  --indexfile   name of html version of list for each directory

===========
Config file
===========
Users can keep a ~/.playlistrc file that stores various options; playlist
reads ~/.playlistrc at startup and sets options accordingly. A sample file
looks like this:

# This is a comment
ROOTDIR=/home/joebob/music
LISTSUFFIX=m3u
FINDSUFFIX=mp3
MASTERLIST=master
INDEXFILE=index.html

# This file will start in /home/joebob/music and recur on all
# its subdirectories, placing files named "index.html" and
# [dirname].m3u in each directory. Additionally, a comprehensive
# list called "master.m3u" will be placed in /home/joebob/music.

=============
Compatibility
=============

This program was originally intended to create mp3 playlists, but it soon
became clear that it can be used for an arbitrary filetype; you could, for
instance, use it to find all .jpg files in a directory tree and make quick
and dirty web pages with the index.html files.

The suffix ".m3u" is the default for most mp3 players, but you can change
it to whatever you prefer. Most popular Linux and Windows mp3 players will
work well with the playlists generated by this script (kmp3, replay,
WinAmp), with the notable exception of x11amp: x11amp keeps its playlists
in your ~/.x11amp directory and does not seem to allow you to use playlists
found elsewhere. This is a limitation of x11amp; if you hate it, I suggest
switching to replay or kmp3 or eMusic or something.

Also, if you keep your mp3 files on a fat32 partition and mount it from
Linux, be aware that this program will of course need to write to that
partition as it creates the files. If you run it as a user that doesn't
have write privileges for that partition, you'll probably have problems. If
you've got root access, you can either fix the privileges for all users by
setting the umask in /etc/fstab to something more permissive, or you can
create a user group that is granted write access.

=======
Copying
=======
This program is released under the terms of the GNU Public License. For more information, refer to the file COPYING, included with this distribution, or the original online version of the license, located at:
http://www.gnu.org/copyleft/gpl.html

=======
Credits
=======
Sam Carter <petrov@rice.edu> for good ideas and mad Perl savoir-faire













