NAME
/etc/disorder/config - DisOrder jukebox configuration
DESCRIPTION
The purpose of DisOrder is to organize and play digital audio files,
under the control of multiple users. /etc/disorder/config is the pri-
mary configuration file; the web interface uses a number of others (see
disorder.cgi(8)).
Tracks
DisOrder can be configured with multiple collections of tracks, index-
ing them by their filename, and picking players on the basis of file-
name patterns (for instance, "*.mp3").
Although the model is of filenames, it is not inherent that there are
corresponding real files - merely that they can be interpreted by the
chosen player. See disorder(3) for more details about this.
Each track can have a set of preferences associated with it. These are
simple key-value pairs; they can be used for anything you like, but a
number of keys have specific meanings. See disorder_preferences(5) for
more details about these.
Track Names
Track names are derived from filenames under the control of regular
expressions, rather than attempting to interpret format-specific embed-
ded name information. They can be overridden by setting preferences.
Names for display are distinguished from names for sorting, so with the
right underlying filenames an album can be displayed in its original
order even if the displayed track titles are not lexically sorted.
Server State
A collection of global preferences define various bits of server state:
whether random play is enabled, what tags to check for when picking at
random, etc. See disorder_preferences(5) for more information.
Users And Access Control
DisOrder distinguishes between multiple users. This is for access con-
trol and reporting, not to provide different views of the world: i.e.
preferences and so on are global.
Each user has an associated set of rights which control which commands
they may execute. Normally you would give all users most rights, and
expect them to cooperate (they are after all presumed to be in a shared
sound environment).
The full set of rights are:
read User can perform read-only operations
play User can add tracks to the queue
move any
User can move any track
move mine
User can move their own tracks
move random
User can move randomly chosen tracks
remove any
User can remove any track
remove mine
User can remove their own tracks
remove random
User can remove randomly chosen tracks
scratch any
User can scratch any track
scratch mine
User can scratch their own tracks
scratch random
User can scratch randomly chosen tracks
volume User can change the volume
admin User can perform admin operations
rescan User can initiate a rescan
register
User can register new users. Normally only the guest user would
have this right.
userinfo
User can edit their own userinfo
prefs User can modify track preferences
global prefs
User can modify global preferences
pause User can pause/resume
Access control is entirely used-based. If you configure DisOrder to
listen for TCP/IP connections then it will accept a connection from
anywhere provided the right password is available. Passwords are never
transmitted over TCP/IP connections in clear, but everything else is.
The expected model is that host-based access control is imposed at the
network layer.
Web Interface
The web interface is controlled by a collection of template files, one
for each kind of page, and a collection of option files. These are
split up and separate from the main configuration file to
See disorder.cgi(8) for more information.
Searching And Tags
Search strings contain a list of search terms separated by spaces. A
search term can either be a single word or a tag, prefixed with "tag:".
Search words are compared without regard to letter case or accents;
thus, all of the following will be considered to be equal to one
another:
LATIN CAPITAL LETTER E
LATIN SMALL LETTER E
LATIN CAPITAL LETTER E WITH GRAVE
LATIN SMALL LETTER E WITH GRAVE
LATIN CAPITAL LETTER E plus COMBINING GRAVE ACCENT
LATIN SMALL LETTER E plus COMBINING GRAVE ACCENT
The same rules apply to tags but in addition leading and trailing
whitespace is disregarded and all whitespace sequences are treated as
equal when they appear as internal whitespace.
Where several tags are listed, for instance the tags preference for a
track, the tags are separated by commas. Therefore tags may not con-
tain commas.
CONFIGURATION FILE
General Syntax
Lines are split into fields separated by whitespace (space, tab, line
feed, carriage return, form feed). Comments are started by the number
sign ("#").
Fields may be unquoted (in which case they may not contain spaces and
may not start with a quotation mark or apostrophe) or quoted by either
quotation marks or apostrophes. Inside quoted fields every character
stands for itself, except that a backslash can only appear as part of
one of the following escape sequences:
\\ Backslash
\" Quotation mark
\' Apostrophe
\n Line feed
No other escape sequences are allowed.
Within any line the first field is a configuration command and any fur-
ther fields are parameters. Lines with no fields are ignored.
After editing the config file use disorder reconfigure to make it re-
read it. If there is anything wrong with it the daemon will record a
log message and ignore the new config file. (You should fix it before
next terminating and restarting the daemon, as it cannot start up with-
out a valid config file.)
Configuration Files
Configuration files are read in the following order:
/etc/disorder/config
/etc/disorder/config.private
Should be readable only by the jukebox group. Not really useful
any more and will be abolished in future.
~USERNAME/.disorder/passwd
Per-user client configuration. Optional but if it exists must
be readable only by the relevant user. Would normally contain a
password directive.
/etc/disorder/config.USERNAME
Per-user system-controlled client configuration. Optional but
if it exists must be readable only by the relevant user. Would
normally contain a password directive.
The prefererred location for per-user passwords is ~/.disor-
der/passwd and disorder authorize writes there now.
Global Configuration
home DIRECTORY
The home directory for state files. Defaults to /var/lib/disor-
der. The server will create this directory on startup if it
does not exist.
This setting cannot be changed during the lifetime of the
server.
plugins PATH
Adds a directory to the plugin path. (This is also used by the
web interface.)
Plugins are opened the first time they are required and never
after, so after changing a plugin you must restart the server
before it is guaranteed to take effect.
If plugins is used without arguments the plugin path is cleared.
Server Configuration
alias PATTERN
Defines the pattern use construct virtual filenames from track-
name_ preferences.
Most characters stand for themselves, the exception being {
which is used to insert a track name part in the form {name} or
{/name}.
The difference is that the first form just inserts the name part
while the second prefixes it with a / if it is nonempty.
The pattern should not attempt to include the collection root,
which is automatically included, but should include the proper
extension.
The default is {/artist}{/album}{/title}{ext}.
This setting cannot be changed during the lifetime of the
server.
api NAME
Selects the backend used to play sound and to set the volume.
The following options are available:
alsa Use the ALSA API. This is only available on Linux sys-
tems, on which it is the default.
coreaudio
Use Apple Core Audio. This only available on OS X sys-
tems, on which it is the default.
oss Use the OSS (/dev/dsp) API. Not available on all plat-
forms.
command
Execute a command. This is the default if speaker_com-
mand is specified, or if no native is available.
You might want to set pause_mode with this backend.
rtp Transmit audio over the network. This is the default if
broadcast is specified. You can use disorder-playrtp(1)
to receive and play the resulting stream on Linux and OS
X. network is a deprecated synonym for this API.
authorization_algorithm ALGORITHM
Defines the algorithm used to authenticate clients. The valid
options are sha1 (the default), sha256, sha384 and sha512. See
disorder_protocol(5) for more details.
broadcast [FAMILY] ADDRESS PORT
Transmit sound data to ADDRESS using UDP port PORT. This
implies api rtp.
FAMILY can be -4 or -6 to force IPv4 or IPv6, if this is not
implied by ADDRESS. Note that IPv6 is not currently well
tested.
See also multicast_loop and multicast_ttl.
broadcast_from [FAMILY] ADDRESS PORT
Sets the (local) source address used by broadcast.
FAMILY can be -4 or -6 to force IPv4 or IPv6, if this is not
implied by ADDRESS. Note that IPv6 is not currently well
tested.
channel CHANNEL
The mixer channel that the volume control should use.
For api oss the possible values are:
pcm Output level for the audio device. This is probably
what you want and is the default.
speaker Output level for the PC speaker, if that is connected to
the sound card.
pcm2 Output level for alternative codec device.
vol Master output level. The OSS documentation recommends
against using this, as it affects all output devices.
You can also specify channels by number, if you know the right
value.
For api alsa, this is the name of the mixer control to use. The
default is PCM. Use amixer scontrols or similar to get a full
list.
For api coreaudio, volume setting is not currently supported.
collection MODULE ENCODING ROOT
collection MODULE ROOT
collection ROOT
Define a collection of tracks.
MODULE defines which plugin module should be used for this col-
lection. Use the supplied fs module for tracks that exist as
ordinary files in the filesystem. If no MODULE is specified
then fs is assumed.
ENCODING defines the encoding of filenames in this collection.
For fs this would be the encoding you use for filenames. Exam-
ples might be iso-8859-1 or utf-8. If no encoding is specified
then the current locale's character encoding is used.
NB that this default depends on the locale the server runs in,
which is not necessarily the same as that of ordinary users,
depending how the system is configured. It's best to explicitly
specify it to be certain.
ROOT is the root in the filesystem of the filenames and is
passed to the plugin module. It must be an absolute path and
should not end with a "/".
cookie_key_lifetime SECONDS
Lifetime of the signing key used in constructing cookies. The
default is one week.
If this is changed during the lifetime of the server, the cur-
rent key doesn't hvave its lifetime retroactively changed.
cookie_login_lifetime SECONDS
Lifetime of a cookie enforced by the server. When the cookie
expires the user will have to log in again even if their browser
has remembered the cookie that long. The default is one day.
If this is changed during the lifetime of the server, cookies
that have already een generated don't hvave their lifetime
retroactively changed.
default_rights RIGHTS
Defines the set of rights given to new users. The argument is a
comma-separated list of rights. For the possible values see
Users And Access Control above.
The default is to allow everything except admin and register.
device NAME
Sound output device.
For api oss this is the path to the device to use. If it is set
to default then /dev/dsp and /dev/audio will be tried.
For api alsa this is the device name to use.
For api coreaudio this can be either the UID or the human-read-
able name of the desired device. For a list of names, visit
System Preferences -> Sound and look at the Type column. For
example, you might use "Built-in Output" for the built-in
speaker or "Built-in Line Output" if you have connected external
speakers. Remember to quote the name.
The default is default, which is intended to map to whatever the
system's default is.
history INTEGER
Specifies the number of recently played tracks to remember
(including failed tracks and scratches).
If this is changed during the lifetime of the server, it won't
actually reduce the size of the list until it is next modified.
listen [FAMILY] [HOST] SERVICE
Listen for connections on the address specified by HOST and port
specified by SERVICE. If HOST is omitted, or is *, then listens
on all local addresses.
FAMILY can be -4 or -6 to force IPv4 or IPv6, if this is not
implied by HOST. Note that IPv6 is not currently well tested.
Normally the server only listens on a UNIX domain socket.
mixer DEVICE
The mixer device name, if it needs to be specified separately
from device.
For api oss this should be the path to the mixer device and the
default is /dev/mixer.
For api alsa, this is the index of the mixer control to use.
The default is 0.
For api coreaudio, volume setting is not currently supported.
mount_rescan yes|no
Determines whether mounts and unmounts will cause an automatic
rescan. The default is yes.
multicast_loop yes|no
Determines whether multicast packets are loop backed to the
sending host. The default is yes. This only applies if api is
set to rtp and broadcast is actually a multicast address.
multicast_ttl HOPS
Set the maximum number of hops to send multicast packets. This
only applies if api is set to rtp and broadcast is actually a
multicast address. The default is 1.
namepart PART REGEXP SUBST [CONTEXT [REFLAGS]]
Determines how to extract trackname part PART from a track name
(with the collection root part removed). Used in @recent@,
@playing@ and @search@.
Track names can be different in different contexts. For
instance the sort string might include an initial track number,
but this would be stripped for the display string. CONTEXT
should be a glob pattern matching the contexts in which this
directive will be used.
Valid contexts are sort and display.
All the namepart directives are considered in order. The first
directive for the right part, that matches the desired context,
and with a REGEXP that matches the track is used, and the value
chosen is constructed from SUBST according to the substitution
rules below.
Note that searches use the raw track name and trackname_ prefer-
ences but not (currently) the results of namepart, so generating
words via this option that aren't in the original track name
will lead to confusing results.
If you supply no namepart directives at all then a default set
will be supplied automatically. But if you supply even one then
you must supply all of them. The defaults are equivalent to:
namepart title "/([0-9]+ *[-:] *)?([^/]+)\.[a-zA-Z0-9]+$" $2 display
namepart title "/([^/]+)\.[a-zA-Z0-9]+$" $1 sort
namepart album "/([^/]+)/[^/]+$" $1 *
namepart artist "/([^/]+)/[^/]+/[^/]+$" $1 *
namepart ext "(\.[a-zA-Z0-9]+)$" $1 *
This setting cannot be changed during the lifetime of the
server.
new_bias WEIGHT
The weight for new tracks. The default is 450000, i.e. recently
added tracks are a fifty times as likely to be picked as normal.
New values of this option may be picked up from the configura-
tion file even without a reload.
new_bias_age SECONDS
The maximum age of tracks that new_bias applies to, in seconds.
The default is one week.
New values of this option may be picked up from the configura-
tion file even without a reload.
new_max MAX
The maximum number of tracks to list when reporting newly
noticed tracks. The default is 100.
nice_rescan PRIORITY
Set the recan subprocess priority. The default is 10.
(Note that higher values mean the process gets less CPU time;
UNIX priority values are backwards.)
nice_server PRIORITY
Set the server priority. This is applied to the server at
startup time (and not when you reload configuration). The
server does not use much CPU itself but this value is inherited
by programs it executes. If you have limited CPU then it might
help to set this to a small negative value. The default is 0.
Changes to this value during the lifetime of the server are
ignored.
nice_speaker PRIORITY
Set the speaker process priority. This is applied to the
speaker process at startup time (and not when you reload the
configuration). The speaker process is not massively CPU inten-
sive by today's standards but depends on reasonably timely
scheduling. If you have limited CPU then it might help to set
this to a small negative value. The default is 0.
Changes to this value during the lifetime of the server are
ignored.
noticed_history
The maximum days that a track can survive in the database of
newly added tracks. The default is 31.
pause_mode MODE
Sets the pause mode for the command backend. The possible val-
ues are:
silence
Send silent (0-value) samples when paused. This is the
default.
suspend
Stop writing when paused.
player PATTERN MODULE [OPTIONS.. [--]] ARGS...
Specifies the player for files matching the glob PATTERN. MOD-
ULE specifies which plugin module to use.
The following options are supported:
-- Defines the end of the list of options. Needed if the
first argument to the plugin starts with a "-".
The following are the standard modules:
exec COMMAND ARGS...
The command is executed via execvp(3), not via the shell.
The PATH environment variable is searched for the exe-
cutable if it is not an absolute path. The command is
expected to know how to open its own sound device.
execraw COMMAND ARGS...
Identical to the exec except that the player is expected
to use the DisOrder raw player protocol. disorder-
decode(8) can decode several common audio file formats to
this format.
shell [SHELL] COMMAND
The command is executed using the shell. If SHELL is
specified then that is used, otherwise sh will be used.
In either case the PATH environment variable is searched
for the shell executable if it is not an absolute path.
The track name is stored in the environment variable
TRACK.
Be careful of the interaction between the configuration
file quoting rules and the shell quoting rules.
If multiple player commands match a track then the first match
is used.
For the server to be able to calculate track lengths, there
should be a tracklength command corresponding to each player
command.
If player is used without arguments, the list of players is
cleared.
Although players can be changed during the lifetime of the
server, note that background decoders will not be stopped and
restarted using changed configuration once they have been
started.
queue_pad COUNT
The target size of the queue. If random play is enabled then
randomly picked tracks will be added until the queue is at least
this big. The default is 10.
If this is reduced during the lifetime of the server, the queue
won't be reduced in size to fit; it just won't start growing
again until it is under the new value. However, if it is
increased, new tracks will start being added immediately.
reminder_interval SECONDS
The minimum number of seconds that must elapse between password
reminders. The default is 600, i.e. 10 minutes.
remote_userman yes|no
User management over TCP connection is only allowed if this is
set to yes. By default it is set to no.
replay_min SECONDS
The minimum number of seconds that must elapse after a track has
been played before it can be picked at random. The default is 8
hours. If this is set to 0 then there is no limit, though cur-
rent disorder-choose will not pick anything currently listed in
the recently-played list.
New values of this option may be picked up from the configura-
tion file even without a reload.
sample_format BITS/RATE/CHANNELS
Describes the sample format expected by the speaker_command
(below). The components of the format specification are as fol-
lows:
BITS The number of bits per sample. Optionally, may be
suffixed by b or l for big-endian and little-endian
words. If neither is used the native byte order is
assumed.
RATE The number of samples per second.
CHANNELS The number of channels.
The default is 16/44100/2.
With the rtp backend the sample format is forced to 16b/44100/2
and with the coreaudio backend it is forced to 16/44100/2, in
both cases regardless of what is specified in the configuration
file.
signal NAME
Defines the signal to be sent to track player process groups
when tracks are scratched. The default is SIGKILL.
Signals are specified by their full C name, i.e. SIGINT and not
INT or Interrupted or whatever.
sox_generation 0|1
Determines whether calls to sox(1) should use -b, -x, etc (if
the generation is 0) or -bits, -L etc (if it is 1). See the
documentation for your installed copy of sox to determine which
you need. The default is set according to the version of sox
found when DisOrder was built. If you run on a system with a
different version of sox, you will need to set this option.
speaker_backend NAME
This is an alias for api; see above.
speaker_command COMMAND
Causes the speaker subprocess to pipe audio data into shell com-
mand COMMAND, rather than writing to a local sound card. The
sample format is determine by sample_format above.
Note that if the sample format is wrong then sox(1) is invoked
to translate it. If sox is not installed then this will not
work.
scratch PATH
Specifies a scratch. When a track is scratched, a scratch track
is played at random. Scratches are played using the same logic
as other tracks.
At least for the time being, path names of scratches must be
encoded using UTF-8 (which means that ASCII will do).
If scratch is used without arguments then the list of scratches
is cleared.
stopword WORD ...
Specifies one or more stopwords that should not take part in
searches over track names.
If stopword is used without arguments then the list of stopwords
is cleared.
There is a default set of stopwords built in, but this option
can be used to augment or replace that list.
This setting cannot be changed during the lifetime of the
server.
tracklength PATTERN MODULE
Specifies the module used to calculate the length of files
matching PATTERN. MODULE specifies which plugin module to use.
If tracklength is used without arguments then the list of mod-
ules is cleared.
Track lengths are cached in the database, and changing this set-
ting won't cause them to be regenerated.
user USERNAME
Specifies the user to run as. Only makes sense if invoked as
root (or the target user).
This setting cannot be changed during the lifetime of the server
(and if it is changed with a restart, you will need to adjust
file permissions on the server's database).
Client Configuration
These options would normally be used in ~USERNAME/.disorder/passwd or
/etc/disorder/config.USERNAME.
connect [FAMILY] HOST SERVICE
Connect to the address specified by HOST and port specified by
SERVICE.
FAMILY can be -4 or -6 to force IPv4 or IPv6, if this is not
implied by HOST. Note that IPv6 is not currently well tested.
password PASSWORD
Specify password.
username USERNAME
Specify username. The default is inferred from the current UID.
Web Interface Configuration
mail_sender ADDRESS
The email address that appears in the From: field of any mail
messages sent by the web interface. This must be set if you
have online registration enabled.
refresh SECONDS
Specifies the maximum refresh period in seconds. The refresh
period is the time after which the web interface's queue and
manage pages will automatically reload themselves. Default 15.
refresh_min SECONDS
Specifies the minimum refresh period in seconds. Default 1.
sendmail PATH
The path to the Sendmail executable. This must support the -bs
option (Postfix, Exim and Sendmail should all work). The
default is the sendmail executable found at compile time.
short_display CHARACTERS
Defines the maximum number of characters to include in a short
name part. Default 30.
smtp_server HOSTNAME
The hostname (or address) of the SMTP server to use for sending
mail. The default is 127.0.0.1. If sendmail is set then that
is used instead.
transform TYPE REGEXP SUBST [CONTEXT [REFLAGS]]
Determines how names are sorted and displayed in track choice
displays.
TYPE is the type of transformation; usually track or dir but you
can define your own.
CONTEXT is a glob pattern matching the context. Standard con-
texts are sort (which determines how directory names are sorted)
and display (which determines how they are displayed). Again,
you can define your own.
All the transform directives are considered in order. If the
TYPE, REGEXP and the CONTEXT match then a new track name is con-
structed from SUBST according to the substitution rules below.
If several match then each is executed in order.
If you supply no transform directives at all then a default set
will be supplied automatically. But if you supply even one then
you must supply all of them. The defaults are:
transform track "^.*/([0-9]+ *[-:] *)?([^/]+)\.[a-zA-Z0-9]+$" $2 display
transform track "^.*/([^/]+)\.[a-zA-Z0-9]+$" $1 sort
transform dir "^.*/([^/]+)$" $1 *
transform dir "^(the) ([^/]*)" "$2 $1" sort i
transform dir "[[:punct:]]" "" sort g
url URL
Specifies the URL of the web interface. This URL will be used
in generated web pages. The default is inferred at runtime, so
this option no longer needs to be specified.
This must be the full URL, e.g. http://myhost/cgi-bin/jukebox
and not /cgi-bin/jukebox.
REGEXP SUBSTITUTION RULES
Regexps are PCRE regexps, as defined in pcrepattern(3). The only
option used is PCRE_UTF8. Remember that the configuration file syntax
means you have to escape backslashes and quotes inside quoted strings.
In a SUBST string the following sequences are interpreted specially:
$1 ... $9
These expand to the first to ninth bracketed subexpression.
$& This expands to the matched part of the subject string.
$$ This expands to a single $ symbol.
All other pairs starting with $ are undefined (and might be used for
something else in the future, so don't rely on the current behaviour.)
If i is present in REFLAGS then the match is case-independent. If g is
present then all matches are replaced, otherwise only the first match
is replaced.
TRACK NAME PARTS
The traditional track name parts are artist, album and title, with the
obvious intended meaning. These are controlled by configuration and by
trackname_ preferences.
In addition there are two built-in parts, path which is the whole path
name and ext which is the filename extension, including the initial dot
(or the empty string if there is not extension).
SEE ALSO
disorder(1), sox(1), disorderd(8), disorder-dump(8), pcrepattern(3),
disorder_templates(5), disorder_actions(5), disorder.cgi(8), disor-
der_preferences(5)