workmanrc, workmandb - database and preferences files for workman
$HOME/.workmanrc or value of WORKMANRC variable
$HOME/.workmandb or value(s) of WORKMANDB variable
The .workmandb file stores information about compact discs. It is
generated by workman(1) based on user input. Its companion file,
.workmanrc, stores the general user preferences and the user
preferences for each disc. The distinction between the two is that
.workmandb contains only the hard information about a CD (the disc
name, artist, track titles, etc.) and is often shared among several
users. .workmanrc, on the other hand, contains settings like the
user’s email address sent to the CDDB server, the default volumes of
particular tracks, the numbers of tracks to be avoided, and so forth.
Each user generally maintains a private .workmanrc, even if a shared
.workmandb is being used.
Though workman(1) stores different information in each file, both files
have an identical format; most of this manual page will not distinguish
between the two. Each line of the file is of the form
[s-]keyword [optional whitespace-separated arguments]
Empty lines are ignored. Lines starting with unrecognized keywords are
retained and written back out verbatim when the database is saved. The
program preserves the ordering of unrecognized lines, and their
positions relative to the track information. This allows the database
to be extended to hold any sort of information desired by the user.
Keywords that begin with "s-" apply to sections rather than tracks.
See the sections keyword below. A CD entry with "s-" keywords must
have a sections keyword as well. This is done for backward
compatibility and will disappear eventually, and in any case only
applies to keywords found in .workmandb (the assumption is that users
won’t downgrade the versions they run, so .workmanrc doesn’t need to be
Some keywords are delimiters that modify the meanings of keywords that
follow; others are position-independent and may occur anywhere in the
file. (In general, the position-independent keywords are concerned
with settings for the tool as a whole, rather than for a particular
The keywords, and their arguments, follow. All numeric arguments are
in decimal unless otherwise specified.
These keywords must appear before the first CD’s entry, and represent
global settings for the tool. They are usually found in .workmanrc.
whendone eject | stop | repeat
Select the default action taken by workman(1) when a CD is
finished playing. The default is stop.
If specified, workman(1) will play unknown CDs (those not listed
in .workmanrc) when they’re inserted.
cddbprotocol cddbp | http | proxy
Protocol to be used for CDDB requests. workman(1) can either
use the CDDBP or the HTTP protocol. PROXY denotes the use of a
proxy server for CDDBP requests. If this keyword is not set
workman(1) does not use CDDB support.
name of the CDDB server to be used, e.g. de3.freedb.org. If
port is not provided we use port 888 for CDDBP requests and port
80 for HTTP requests.
This is the user’s email address that will be sent to the CDDB
server. It must be given in the form user@host. If this address
is not provided an identification based on the login name and
the hostname will be sent.
If the HTTP protocol is used this keyword provides the path to
the CGI script answering the CDDB requests. This is usually
The name of a proxy that can be used for CDDB requests. If port
is not provided port 80 will be used.
The rest of the keywords describe specific CDs.
tracks ntracks start1 start2 ... startn length
This keyword delimits the start of a particular CD’s entry (and
thus the end of the previous entry.) Its arguments contain the
information used to distinguish one disc from another. The
first argument, ntracks, is the number of tracks on the CD. For
each of those tracks, there is a start value, which is the
starting frame of the track (a frame is approximately 1/75th of
a second.) The final argument is the length of the CD in
sections nsects start1 start2 ... startn
Workman(1) allows the user to split a CD’s physical tracks into
smaller virtual tracks called sections. The sections keyword,
which must immediately follow tracks, defines the starting
positions of the sections. Sections are inserted into the track
list, and track numbers are adjusted accordingly, e.g. section
1.2 as presented to the user is represented as track 2 in the
database file. If the sections listed in .workmandb and
.workmanrc differ, .workmandb takes precedence, and sections
listed only in .workmanrc are discarded.
The name of the current disc, as supplied by the user.
The artist’s name for the current disc, as supplied by the user.
The default play mode for the CD is mode, a numeric value. 0 is
the "normal" play mode (play all tracks sequentially) and 1 is
"shuffle" mode. If mode is 2 or greater, the default play
sequence is a playlist (mode 2 meaning the first playlist, 3
meaning the second, etc.)
If autoplay is present, this CD will begin playing immediately
when it is inserted.
The default play volume of the CD, a value from 0 to 32. If
volume is 0, the CD has no default volume (since 0 is the
default, cdvolume will usually not be present in that case.)
playlist name number track1 track2 ...
Define a playlist for the current CD. The name does not contain
any whitespace; whitespace is converted to "_" on output and "_"
is converted to whitespace on input. (See the BUGS section.)
The number argument is the number of tracks contained in the
playlist; the rest of the line is a list of track numbers.
Playlists are ordered; see the playmode keyword above.
The name of a track. This delimits the start of a track’s
information. The name argument is optional; it will not be
present unless the user has supplied a track name. This line
may be divided into display lines with the "//" token.
Additionally, a display line beginning with "+" indicates that
the rest of the display line contains a replacement disc title
(usually the name of a group of tracks, such as "Symphony No. 2"
on a disc with more than one piece of music.) A display line
beginning with "@" replaces the artist’s name for the track. If
"+" or "@" is the only character on a display line, workman(1)
will use the title or artist from the previous track, searching
backwards as necessary. If a display line is empty, the
corresponding display line from the previous track is used.
The current track is a continuation of the previous one (e.g.
the second movement of a symphony.)
Don’t play a track (specified by number) unless it’s
specifically requested by the user.
volume track volume
The default play volume for track, specified by number. volume
is a number from 0 to 32. See cdvolume above.
mark frame mark-id
Define a mark. Marks with IDs other than START and END are
currently ignored. Those two marks represent the start and end
of the part of the CD to be repeated (as set from the Goodies
popup) respectively. The frame value is an absolute frame
The first example is a .workmandb entry for a hypothetical disc. At
least, I hope it’s hypothetical.
tracks 6 150 10341 20449 45117 100104 150100 1609
cdname Amazing Accordion Tunes - The Early Years
artist The Hemophiliacs
track Polka ’Till the Sun Goes Down
track I’ve Got Rocks In My Heart, Baby...
track ...But I Still Get Stoned On You
track You Never Know How Late It Is Until the Clock Strikes Blue
track +The Big Exhibition//@Mussorgsky//IX. La Cabane//Allegro
track +//@////Andante mosso
The third track is a continuation of the second. The fifth track is an
excerpt from a larger work, originally written by someone else; it has
a two-line track title. The sixth track is a continuation of the
fifth; it uses the same title and artist, and the first line of the
track title is the same, but the second is different.
The .workmanrc entry for the same CD might look like:
tracks 6 150 10341 20449 45117 100104 150100 1609
playlist Originals 3 2 3 1
volume 3 20
The tracks line, naturally, is the same in both files, since it
identifies which CD the entry is for. This CD plays at maximum volume
in shuffle mode by default. It has one playlist with tracks 2, 3, and
1. When inserted, it will start up automatically. Track 4 is
particularly unpleasant, so the user never wants to hear it. And track
3 should be played more quietly than the others.
The playlist keyword is not well thought-out. The name should go at
the end of the line, so it can contain whitespace or whatever else the
The file updating algorithm used by workman(1) leaves big holes
(consisting of empty lines) in the database files. It makes an attempt
to fill the holes when possible rather than growing the files.