.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.
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?
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.
Format:
${VARIABLE NAME}
Example:
remote-control /tmp/${USER}-w3juke-remote
conf filew3juke
demands.Comment lines start with a hash character. Mixed command and comment lines probably don't work correctly. So don't do it!
Examples:# 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 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... index http://audiophile.example.com/public/mp3-index.txt index http://audiophile.example.com/restricted/mp3-index.txt # 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
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.: mp3.com) 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
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.
ext:mime:exec: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
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 http://chooser.mp3.com/cgi-bin/play/play.cgi/AAIAQueqAADABG5vcm1QBAAAAFLrKwAAUQIAAABD5_szOWnPbMXEo8CkpThclPtbRXA-/song_of_the_volga_surfmen.mp3 is: The Projectiles/Six Song Sea Dee/Song of the Volga Surfmen
I could tell you what these things do, but then I would have to hurt you. Better that you figure it out yourselves...
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/fileExample:
remote-control /tmp/${USER}-w3juke-remote
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.
Format:buffer-size NUM NUM NUMExample:
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.)
Format:dns-cache-ttl SECONDSExample:
# turn off the dns cache, because there is a local caching nameserver dns-cache-ttl 0
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.
Format:include URL-or-filenameExample:
# Include another user's config file include ~stripes/.w3juke/conf # Include a file full of maps off a web server include http://www.tons-o-songs.com/w3juke.map
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:
w3juke.Thus, you can disable the prefetch.
Format and example:noprefetch
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 show-track-changes-automatically
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.
Format:# Change lame URLs to cool ones url_remap lame-URL cool-URLExample:
# Remap things like http://www.example.com/track-fetch.cgi?tracknum=7631 # to things like http://www.example.com/new-track-fetch.cgi?tracknum=7631 # -- cool, eh? url_remap http://www.example.com/track-fetch.cgi http://www.example.com/new-track-fetch.cgi
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:show-current-rating-in-slider
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.
email: w3juke at
pix.net