SourceForge Logo

w3juke configuration

Stream Decoders

A stream of data that represents audio can be compressed with a variety of different systems. These range from the trivial packaging of raw binary waveforms into .WAV files, to a much more complex system, such as Ogg Vorbis. There are other formats that are extremely popular, such as the Motion Pictures Expert Group's Layer 1, Type 3 encoding, commonly refereed to as MP3 that are also useful to have supported. Since the area of audio compression and playback is undergoing rapid development, it is useful to have an extensible system to handle new audio compression systems as they become available.

One of the challenges with handling many different types of data is correctly recognizing the type of data and then invoking the correct program to handle that type of data. While the w3juke program doesn't directly do any playback of audio data, it does have a sophisticated data retrieval and buffering subsystem to make it possible to retrieve programs over network connections transparently to the playback programs.

Configuration File

The configuration file for w3juke consists of a series of commands. While commands don't need to be given in a particular order, they are parsed in the order listed. The configuration file can normally be found in the users ~/.w3juke directory and is named conf.

Note: The format of the configuration file is still subject to change. So, don't be to surprised if someday the options in the configuration file suddenly mutate into a new and wondrous form. That's the purpose of experimental software, now isn't it? If we knew what the final format of the configuration files needed to look like, well we would have just implemented that, now wouldn't we?

Environmental Variables

The w3juke program will use environmental variables to control how the contents of the conf are interpreted. The reference to the name of the environmental variable must be enclosed in the curly braces, preceded by a dollar sign. This syntax should be very familiar to users of make and writers of sh programs.

Multiple substitutions can be performed on a single line. The value of a substitution is not parsed a second time for additional environmental variable substitution. One substitution pass is all that you get. Newlines in a variable are treated as a literal, not as the end of the command line.

If the referenced environmental variable is not set in the user's environment, the variable will not be expanded and left as literal text.

remote-control /tmp/${USER}-w3juke-remote

Command Keywords in the conf file

No modern configuration file would complete without the ability for the user to litter the configuration with helpful notes about what does what.
Index Files
The first area concerns locating the index files for the collections of music that are available for playback.
Cookie Files
The second concerns the location of any HTTP cookie files that are in use.
Stream Decoders
The third section concerns the configuration of the various stream decoders (aka: Player Programs) that are available for playing back audio streams.
Mapping Statements
The final section concerns mapping local files into the Artist/Album/Track hierarchy that w3juke demands.
Miscellaneous Options
A couple of things that aren't necessarily fully baked.


Comment lines start with a hash character. Mixed command and comment lines probably don't work correctly. So don't do it!

# This is a comment line.
# This is also a comment line.
# Comment lines do not need to have any text on them (like the previous line).

Index Files

Index files tell w3juke where to locate lists of audio data. They can start with either a http:, data:, or file: prefix, to tell w3juke how to load that list of audio data.

# We have access to several sets of audio data.  Public, and restricted-access...
# Multiple index files can be listed
# N.B.: the reads will more or less intermingle, so be careful with races!
index file:/tmp/mp3-index.txt
# If you have no indexes listed, an internal default is used.  You can
# put a "fake" index in if you want to do everything with maps statements:
index file:/dev/null

Cookie Files

This command tag lets w3juke locate a file to get cookies to send to web servers that require it to read the audio data. (e.g.: Currently only the classic Netscape 4.X cookie file format is supported.

# My Netscape cookies, they're likely the only ones that it'll need to use...
cookies ~/.netscape/cookies

Decoders/Player Programs

These statements make up a set of matching criteria for w3juke to classify a file or HTTP data stream. It also specifies the the application (and the flags for the application) to run when such a file or data stream is sent.

If a handler for a particular datatype is listed multiple times, the last encountered handler in the configuration file takes precedence. As well, adding a handler for datatype foo/bar will also automatically add a handler for foo/x-bar, provided there wasn't already a handler for foo/x-bar. This facility is added as to support the Web servers that send back experimental forms of content data types.

Default handlers for common datatypes are always installed for the user, even if no other handlers are specified by the user. Those default handlers are listed in the Examples: section.

The handle keyword takes three additional tag:value data items.

A list of file suffixes that would cause a local file to be classified as this type of data source. It is probably worth noting that the filename extension is only used if no content-type is available. (e.g.:When reading from a file, or when retrieving a file from a truly substandard Web server.) If there is not handler listed for a given content type received from a HTTP server, or the extension is unknown, the audio data will be skipped. This is useful in the case where a file no longer exists and the Web server returns an error document of type "text/html".
A list of mime data types that a HTTP server might send that indicate the classification of the following data stream.
An application to run and the flags that it requires for data buffering and whatnot. The flags for the application must also prepare that application from reading its data stream from stdin. This is true even in the event that the data stream is being read off a local disk.
handle ext: ogg vorb mime: audio/vorbis audio/ogg-vorbis application/ogg application/vorbis exec: ogg123 -d oss -q -
handle ext: mp3 mpeg3 mime: audio/mp3 audio/mpeg3 audio/mpeg exec: mpg123 -b 1024 -q -
handle ext: wav aiff aif aifc mime: audio/aiff audio/wav exec: sox -t wav - -t ossdsp /dev/dsp
handle ext: au snd mime: audio/basic exec: sox -t au - -t ossdsp /dev/dsp

Mapping Statements

Map statements are used to associate an Artist/Disc/Track entry to a URL, or a filename. The shell syntax of ~username is expanded in file names as a convenience feature. The format for mapping state is map URL is: A/D/T. If the name of the file has white space (spaces, tabs) in it, you will have to use the file: form of the specifier and encode the whitespace as %XX characters. The is: of the specifier is literal.

map file:~joker/duke%20ellingtons%20woody.mp3 is: The Projectiles/Six Song Sea Dee/??-Duke Ellington's Woody
map ~joker/thanksgiving_1989.mp3 is: Anarchy Steering Committee/Unknown/98-Thanksgiving 1989: I Am A Lesbian...
map is: The Projectiles/Six Song Sea Dee/Song of the Volga Surfmen

Miscellaneous Options

I could tell you what these things do, but then I would have to hurt you. Better that you figure it out yourselves...

Remote Control

w3juke uses a Unix Domain Socket for control by other applications. There is a helper application called w3juke-helper that can give commands to w3juke to allow it to pause, insert a audio file to play, empty the play queue and so forth. This needs to be better documented. This command tells w3juke where to put the Unix Domain Socket.

If the remote-control keyword is not set explicitly, it defaults to /tmp/${USER}-w3juke-remote.

remote-control /path/to/file
remote-control /tmp/${USER}-w3juke-remote

Buffer Sizes

As discussed elsewhere on these Web pages, w3juke has a sophisticated buffering capability internal to itself. This command allows the user to set some of the buffering characteristics of the program. Each number can be suffixed with K, M, or G. These mean kilobyte, megabyte and gigabyte, respectively.

The first number sets the size of the buffer allocated for each audio file. The second number is how much must be read in before the song starts (or restarts) playing (this value is a starting point, it is adjusted as the program runs). The third number is used to decide when to start reading again after the buffer is full. Setting this parameter too low will make w3juke use more CPU time. If you TCP stack sucks, it can also increase the networking loading.

There is little sanity checking on these parameters. If you make the program core dump, well congratulations, you were warned.

buffer-size NUM NUM NUM
buffer-size 1M 256K 16K


Because w3juke can pull data from HTTP servers, it must be able to resolve the hostname down to an IP address. Most lame application programs will just ask the nameserver for this data, each time they need to perform this mapping. This can result in additional, unwanted network traffic.

To give the user enough rope to hang themselves, w3juke implements a cache of hostname to IP address mappings. How long the data will be cached is controllable by the user, via the dns-cache-ttl keyword. If no value is explicitly set by the user, w3juke defaults to caching DNS data for 86400 seconds (24 hours).

If you have a local DNS server, either caching or recursive, you should probably turn off the DNS information caching by setting this value to zero. (See example below.)

dns-cache-ttl SECONDS
# turn off the dns cache, because there is a local caching nameserver
dns-cache-ttl 0

Including other files

Just in case one file isn't enough w3juke can read it's configuration from multiple files. For a little added fun these files are read asynchronously - in other words if you have two included conf files you don't know if the first is all read before the second, or even the normal config file.

There is no checking for loops.

include URL-or-filename
# Include another user's config file
include ~stripes/.w3juke/conf

# Include a file full of maps off a web server

Turning off prefetching

Normally when the end of one song is read another song is chosen and the first part is read into a buffer. That way when the current song ends the next one can start playing without waiting for the buffer to fill. This is a very good thing.

As good as it is, there are a few disadvantages:

Thus, you can disable the prefetch.

Format and example:

Showing added & deleted tracks on startup

Some people would like to know what changes, without having to click somewhere to get that information. Some other people don't want anything disturbing their tidy little world. During startup w3juke can be configured to satisfy either group of people. Turning the following config line on will result in an automatic display (via a dialog) of all additions and deletions of audio tracks since the programs previous run.

At some point in the future, we will be better able to satisfy people who want their tidy little world left alone, by disabling the notification in the main window totally.

Format and example:
# I want to know everything without having to ask

Remapping URLs

For debugging it is sometimes useful to remap some URLs to others, for example you may want to test a new version of track-fetch.cgi and test it before making everyone use it. You could change the index (and/or map) and test it, but then you might miss something from .m3u files. Or you can give this whole remapping thing a shot.

# Change lame URLs to cool ones
url_remap lame-URL cool-URL
# Remap things like
# to things like
#  -- cool, eh?

Making the ratings slider show the current rating

The ratings slider is normally only used to set a new rating. If you desire, you can have the slider reflect the current rating. This is useful if you normally just want to adjust the ratings up or down a little bit. It is also a bit irritating if you expect things to be where you left them last.

Format and example:

End Notes

That's pretty much it for the configuration file. It's all pretty straightforward. It is no more complicated than it needs to be. Really.

Valid HTML 4.01!email: w3juke at
$Date: 2001/10/15 23:45:42 $