playlist 1.0
Patrick Hearon <patrickh@rice.edu>

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

Playlist is a program that recurs through a user-specified list of
directory trees 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 with MacPerl 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 or directories you intend to index. You're done.

=====
Usage
=====

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

Args can be any of the following:

 --root, --rootdir(s)  list of directories to index (separated by colons)
 --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
 --c,	 --clean       delete existing files instead of creating new ones
 --s,	 --silent      do not print out totals
 --h,	 --help	       prints this list of options plus version and author
 --v, --V, --version   prints out the version number

===========
Config file
===========

Users can keep a ~/.playlistrc file that stores various options; playlist
reads ~/.playlistrc at startup and sets options accordingly. Any option
that can be set on the command line can also be set in the config file. A
sample file looks like this:

# This is a comment
ROOTDIR=/home/joebob/music:/home/ftp/pub/porn-ska-remixes
# Note that multiple directories are separated by colons
LISTSUFFIX=m3u
FINDSUFFIX=mp3
MASTERLIST=master
INDEXFILE=index.html
CLEAN=0 # Use 1 for yes or true, 0 for no or false

# 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.
# This will all repeat for /home/ftp/pub/porn-ska-remixes.

=============
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
Adam Hawthorne (arhawth@rice.edu> for donating the guts of the treewalking code












