Dynamic MP3 Lister v2.0.1 Documentation - 10/20/01
Free for non-profit, personal use
Benjamin Kuz (ben@slax0rnet.com)
http://ben.ursux.com

Introduction
------------

Dynamic MP3 Lister is a fast easy way to share your MP3s over the web.  The script is designed to take the hassle
out of creating static pages to access MP3s by creating plaintext files that contain all the information about every
MP3 in a given path, recursively.  It then outputs the information in a clean, easy to read format.

Features
--------

- Simple setup
- MP3 information extraction for items such as time, bitrate, channels, frequency and filesize
- Recursive search function to find all MP3s under a given path, and get information such as number of contained files
  and the total size of contained files
- Support for following symlinks during recursion
- Filename search capabilities
- On-the-fly sorting under any heading
- Playlist creation that doesn't require disk writes for both single files, and entire folders
- Easy directory navigation system
- Works with *nix and windows systems

Installation
------------

Installing the script is easy, just unpack it and copy it to the web folder that you want to use it in.  You will
need to make that directory writeable by the script, as the script creates two files:  mp3.csh and dir.csh for storing
the collected file information.

In UNIX/Linux, the command to make a directory writeable is 'chmod 777 yourfolder'

After that is done, you can proceed with configuration of the script in any plaintext editor.

        Configuration Variables
        -----------------------

        $streaming
        ----------
        If set to true, it will enable playlist creation, and display the options on the web end for retrieving them
        
        $useheaderpic
        -------------
        If set to true, when changing directories, the script will look for 'index.jpg' in that directory.  If the
        script finds it, it will display the image in the header.  Useful if you want to display album graphics on a
        per folder basis.
        
        $startdir
        ---------
        Where the script starts looking for MP3s.  The script should also reside at this location.  Cache files will
        also be created in this folder on first run.  This path must be inside of $websiteroot.  No trailing slash
        should come at the end of this path, and windows paths should be represented with forward slashes.
        IE:  $startdir='c:/apache/mywebfolder/mp3';
        
        $websiteroot
        ------------
        The path to the root of your web directory.  Used to figure out the relative web paths of files.  No trailing 
        slash should come at the end of this path, and windows paths should be represented with forward slashes.
        IE:  $websiteroot='c:/apache/mywebfolder';
        
        $host
        -----
        The hostname including HTTP://
        IE:  $host='http://ben.ursux.com';
        
        $refreshpass
        ------------
        The password needed to refresh the file caches if a change is made.  It's strongly recommended that you have
        a password, especially if you're using the script in conjunction with a lot of files.  The process of building
        the lists can be very CPU intensive, so it's best if only the administrator has access to it.
        
        $PHP_SELF
        ---------
        Some systems may require that this variable be defined.  If you find that the script failes to change
        directories in netscape or opera, set this variable at the top of the script to whatever you've named the
        script.  Please note that the case of the variable matters.
        IE:  $PHP_SELF="mp3.php";
        
After that's done, the first time you access the script, it will begin recursing the directories and building the cache.
After the cache has been created, it will not create them again unless they are deleted, or the refresh option is used.
The rest of the script's operation should be fairly straight forward.  Have Fun!

Changelog
---------

2.0.0
- Inital release of this rewrite

2.0.1
- Fixed a problem stopping some MP3s information from being retrieved
- Files in the list are now properly urlencoded
- Inital script run welcome added
- Added additional error handling
- fixed some foreach() errors caused by there being no directories on a refresh

Credits
-------

Big thank-yous go out to the following people for their efforts in helping me get this script together:

- Jerrett Taylor (http://jerrett.net) for answering PHP/HTML/CSS questions, and for the hosting
- nightwolf for help with WIN32 support and beta testing
- Jibril Aziz Gueye for suggestions related to the index.jpg functions, and for beta testing
- the crew at #php/EFNet for answering technical questions
- Panacea- at #webdesign for the input on number encoding systems
- Eric Guitard for locating the directory link bug in 1.2.0
- Sam- at deskcode.com for his suggestions on improving this script
- the coffee maker for endless amounts of programmer fuel ;)

Final Note
----------

A few of you suggested some things that didn't make it in to this release, some because I just wanted to get certain
features done now, and some because after some consideration, I decided I didn't want to include them.  Thanks to
all people who made suggestions though, it all helps.

Benjamin Kuz (FA-q on EFNet)
ben@slax0rnet.com
http://ben.ursux.com    |    Webmaster
http://slax0rnet.com    |    Admin
http://ursux.com        |    Admin
#slax0rnet/EFNet        |    Botmaster
