w3juke index file format

Why Have Index Files?

Early in the design of w3juke it was decided that the model of playback that we wanted to support was much like a NNTP news server. In this sense, the data (audio) was stored in a centralized location, with a single repository for all the people working at a given location. Each user would have a local history file listing the last time a particular track was played back, and each user could have their own preferences about each of the items in the audio repository.

In order to make finding new additions to the central repository easy, fast and efficient for the client programs, we decided to have a centrally created and maintained list of songs available on the server. This is the Index File that w3juke will load, to get a concise listing of what songs are available off a given server.

The w3juke program has gotten more sophisticated as further development has occurred -- it now has the ability to merge the contents of multiple index files at runtime, into a memory resident master list of available audio data.

The Index File Format

The format of the index file that w3juke uses is very straightforward. Remember that the classification goal of of w3juke is to have mapped a data file source into an Artist/Album/Track tuple.

The file consists of multiple chunks of data, where each chunk has some or all of the following contents:

BASE URL: Sets the stem URL for accessing the the audio files listed in this chunk. Currently, only stem forms of http: and file: are supported. In the future, other types of access may be supported.
ARTIST artist: Sets the name of the Artist for accessing the audio files listed in this chunk.
DISC disc name: Sets the Album/Disc name for accessing the audio files listed in this chunk.
TRACK tracknumber-trackname: Sets the Trank name for a particular audio track. Typically the tracknumber on the disk is prepended to the name, using a two digit track number, padded with a zero digit if the track number is less than 10.

So what does it all mean?

The various pieces above are glued together to make a URL that a particular audio track can be accessed from. Perhaps and example will help...

Example:

BASE http://audiophile.example.com/restricted/
ARTIST The Presidents Of The United States Of America
DISC The Presidents Of The United States Of America
TRACK 01-Kitty.mp3
TRACK 02-Feather Pluckn.mp3
TRACK 03-Lump.mp3
TRACK 04-Stranger.mp3
TRACK 05-Boll Weevil.mp3
TRACK 06-Peaches.mp3
TRACK 07-Dune Buggy.mp3
TRACK 08-We Are Not Going To Make It.mp3
TRACK 09-Kick Out The Jams.mp3
TRACK 10-Body.mp3
TRACK 11-Back Porch.mp3
TRACK 12-Candy.mp3
TRACK 13-Naked And Famous.mp3
DISC II
TRACK 01-Ladies And Gentlemen Part I.mp3
TRACK 02-Lunatic To Love.mp3
TRACK 03-Volcano.mp3
TRACK 04-Mach 5.mp3
TRACK 05-Twig.mp3
TRACK 06-Bug City.mp3
TRACK 07-Bath Of Fire.mp3
TRACK 08-Tiki God.mp3
TRACK 09-L.I.P..mp3
TRACK 10-Froggie.mp3
TRACK 11-Toob Amplifier.mp3
TRACK 12-Supermodel.mp3
TRACK 13-Puffy Little Shoes.mp3
TRACK 14-Ladies And Gentlemen Part II.mp3
TRACK 15-Magic Johnson Dream (Uncredited Track).mp3

The above example lists two chunks of data, representing two albums by the same group, The Presidents Of The United States of America. The first is their self-title album, The Presidents Of The United States of America. The second is their album merely entitled II. Both albums can be accessed off the (fictitious) server audiophile.example.com.

The URL that would be constructed to access the first track of the first album look like the following example, after the standard HTTP escaping of space characters is performed:

http://audiophile.example.com/restricted/The%20Presidents%20Of%20The%20United%20States%20Of%20America/The%20Presidents%20Of%20The%20United%20States%20Of%20America/01-Kitty.mp3

Other Keywords

There is another keyword that might show up in an index file. This is the URL-TRACK keyword. It allows for a literal insertion of the location of an audio track into the playlist.

Format:

URL-TRACK url trackname

Example:

URL-TRACK Rush/Exit...Stage%20Left/01-The%20Spirit%20Of%20Radio.mp3 01-The Spirit Of Radio

In the absence of any directory information in the url, the constructed URL will be referenced relative to the current BASE statement in effect.

Example:

BASE http://mp3meharder.example.com/vault/archive
URL-TRACK d7f66aaa6af5bf7e6b5a446d7254e889.mp3 09-Supernova - Chewbacca
URL-TRACK gimme_gimme_gimme.ogg 01-Fictitious Song Name

The first track in this example will be accessed via the following URL:

http://mp3meharder.example.com/vault/archive/d7f66aaa6af5bf7e6b5a446d7254e889.mp3

The second track would be accessed via the following constructed URL:

http://mp3meharder.example.com/vault/archive/gimme_gimme_gimme.ogg

email: w3juke at pix.net
$Date: 2001/09/28 22:24:50 $