chiark / gitweb /
Documentation tweaks
[disorder] / doc / disorder_config.5.in
CommitLineData
460b9539 1.\"
8f9616f1 2.\" Copyright (C) 2004-2008 Richard Kettlewell
460b9539 3.\"
4.\" This program is free software; you can redistribute it and/or modify
5.\" it under the terms of the GNU General Public License as published by
6.\" the Free Software Foundation; either version 2 of the License, or
7.\" (at your option) any later version.
8.\"
9.\" This program is distributed in the hope that it will be useful, but
10.\" WITHOUT ANY WARRANTY; without even the implied warranty of
11.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12.\" General Public License for more details.
13.\"
14.\" You should have received a copy of the GNU General Public License
15.\" along with this program; if not, write to the Free Software
16.\" Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
17.\" USA
18.\"
19.TH disorder_config 5
20.SH NAME
21pkgconfdir/config - DisOrder jukebox configuration
22.SH DESCRIPTION
23The purpose of DisOrder is to organize and play digital audio files, under the
c0c23a60
RK
24control of multiple users.
25\fIpkgconfdir/config\fR is the primary configuration file but this
26man page currently documents all of its various configuration files.
460b9539 27.SS Tracks
28DisOrder can be configured with multiple collections of tracks, indexing them
29by their filename, and picking players on the basis of filename patterns (for
30instance, "*.mp3").
31.PP
32Although the model is of filenames, it is not inherent that there are
33corresponding real files - merely that they can be interpreted by the chosen
c0c23a60
RK
34player.
35See \fBdisorder\fR(3) for more details about this.
460b9539 36.PP
c0c23a60
RK
37Each track can have a set of preferences associated with it.
38These are simple key-value pairs; they can be used for anything you
39like, but a number of keys have specific meanings.
40See \fBdisorder\fR(1) for more details about these.
460b9539 41.SS "Track Names"
42Track names are derived from filenames under the control of regular
43expressions, rather than attempting to interpret format-specific embedded name
c0c23a60
RK
44information.
45They can be overridden by setting preferences.
460b9539 46.PP
47Names for display are distinguished from names for sorting, so with the right
48underlying filenames an album can be displayed in its original order even if
49the displayed track titles are not lexically sorted.
50.SS "Server State"
51A collection of global preferences define various bits of server state: whether
52random play is enabled, what tags to check for when picking at random, etc.
53.SS "Users And Access Control"
c0c23a60
RK
54DisOrder distinguishes between multiple users.
55This is for access control and reporting, not to provide different
56views of the world: i.e. preferences and so on are global.
460b9539 57.PP
eb5dc014 58Each user has an associated set of rights which contorl which commands they may
c0c23a60
RK
59execute.
60Normally you would give all users most rights, and expect them to
eb5dc014
RK
61cooperate (they are after all presumed to be in a shared sound environment).
62.PP
63The full set of rights are:
64.TP
65.B read
66User can perform read-only operations
67.TP
68.B play
69User can add tracks to the queue
70.TP
71.B "move any"
72User can move any track
73.TP
74.B "move mine"
75User can move their own tracks
76.TP
77.B "move random"
78User can move randomly chosen tracks
79.TP
80.B "remove any"
81User can remove any track
82.TP
83.B "remove mine"
84User can remove their own tracks
85.TP
86.B "remove random"
87User can remove randomly chosen tracks
88.TP
89.B "scratch any"
90User can scratch any track
91.TP
92.B "scratch mine"
93User can scratch their own tracks
94.TP
95.B "scratch random"
96User can scratch randomly chosen tracks
97.TP
98.B volume
99User can change the volume
100.TP
101.B admin
102User can perform admin operations
103.TP
104.B rescan
105User can initiate a rescan
106.TP
107.B register
c0c23a60
RK
108User can register new users.
109Normally only the
eb5dc014
RK
110.B guest
111user would have this right.
112.TP
113.B userinfo
114User can edit their own userinfo
115.TP
116.B prefs
117User can modify track preferences
118.TP
119.B "global prefs"
120User can modify global preferences
121.TP
122.B pause
123User can pause/resume
460b9539 124.PP
c0c23a60
RK
125Access control is entirely used-based.
126If you configure DisOrder to listen for TCP/IP connections then it will
127accept a connection from anywhere provided the right password is
128available.
129Passwords are never transmitted over TCP/IP connections in clear,
130but everything else is.
131The expected model is that host-based access control is imposed at
132the network layer.
460b9539 133.SS "Web Interface"
134The web interface is controlled by a collection of template files, one for each
c0c23a60
RK
135kind of page, and a collection of option files.
136These are split up and separate from the main configuration file to
137make it more convenient to override specific bits.
460b9539 138.PP
139The web interface connects to the DisOrder server like any other user, though
c0c23a60
RK
140it is given a special privilege to "become" any other user.
141(Thus, any process with the same UID as the web interface is very
142powerful as far as DisOrder goes.
143This model will be changed in a future version.)
460b9539 144.PP
145Access control to the web interface is (currently) separate from DisOrder's own
146access control (HTTP authentication is required) but uses the same user
147namespace.
5c1ae3bc
RK
148.PP
149See \fBdisorder.cgi\fR(8) for more information.
180dcdb0 150.SS "Searching And Tags"
c0c23a60
RK
151Search strings contain a list of search terms separated by spaces.
152A search term can either be a single word or a tag, prefixed with "tag:".
180dcdb0
RK
153.PP
154Search words are compared without regard to letter case or accents; thus, all
155of the following will be considered to be equal to one another:
156.PP
157.nf
158 LATIN CAPITAL LETTER E
159 LATIN SMALL LETTER E
160 LATIN CAPITAL LETTER E WITH GRAVE
161 LATIN SMALL LETTER E WITH GRAVE
162 LATIN CAPITAL LETTER E plus COMBINING GRAVE ACCENT
163 LATIN SMALL LETTER E plus COMBINING GRAVE ACCENT
164.fi
165.PP
166The same rules apply to tags but in addition leading and trailing whitespace is
167disregarded and all whitespace sequences are treated as equal when they appear
168as internal whitespace.
169.PP
170Where several tags are listed, for instance the tags preference for a track,
c0c23a60
RK
171the tags are separated by commas.
172Therefore tags may not contain commas.
460b9539 173.SH "CONFIGURATION FILE"
174.SS "General Syntax"
175Lines are split into fields separated by whitespace (space, tab, line
c0c23a60
RK
176feed, carriage return, form feed).
177Comments are started by the number sign ("#").
460b9539 178.PP
179Fields may be unquoted (in which case they may not contain spaces and
180may not start with a quotation mark or apostrophe) or quoted by either
c0c23a60
RK
181quotation marks or apostrophes.
182Inside quoted fields every character stands for itself, except that
183a backslash can only appear as part of one of the following escape sequences:
460b9539 184.TP
185.B \e\e
186Backslash
187.TP
188.B \e"
189Quotation mark
190.\" "
191.TP
192.B \e'
193Apostrophe
194.TP
195.B \en
196Line feed
197.PP
198No other escape sequences are allowed.
199.PP
200Within any line the first field is a configuration command and any
c0c23a60
RK
201further fields are parameters.
202Lines with no fields are ignored.
460b9539 203.PP
204After editing the config file use \fBdisorder reconfigure\fR to make
c0c23a60
RK
205it re-read it.
206If there is anything wrong with it the daemon will record a log
207message and ignore the new config file.
208(You should fix it before next terminating and restarting the daemon,
209as it cannot start up without a valid config file.)
eb5dc014
RK
210.SS "Configuration Files"
211Configuration files are read in the following order:
212.TP
213.I pkgconfdir/config
214.TP
215.I pkgconfdir/config.private
c0c23a60
RK
216Should be readable only by the jukebox group.
217Not really useful any more and will be abolished in future.
eb5dc014 218.TP
90ad6c6e 219.I ~\fRUSERNAME\fI/.disorder/passwd
c0c23a60
RK
220Per-user client configuration.
221Optional but if it exists must be readable only by the relevant user.
222Would normally contain a \fBpassword\fR directive.
5b14453f 223.TP
90ad6c6e 224.I pkgconfdir/config.\fRUSERNAME
c0c23a60
RK
225Per-user system-controlled client configuration.
226Optional but if it exists must be readable only by the relevant user.
227Would normally contain a \fBpassword\fR directive.
5b14453f
RK
228.IP
229The prefererred location for per-user passwords is \fI~/.disorder/passwd\fR and
c0c23a60 230\fBdisorder authorize\fR writes there now.
460b9539 231.SS "Global Configuration"
232.TP
233.B home \fIDIRECTORY\fR
c0c23a60
RK
234The home directory for state files.
235Defaults to
460b9539 236.IR pkgstatedir .
659d87e8 237The server will create this directory on startup if it does not exist.
460b9539 238.TP
0c6bcae0 239.B plugins \fIPATH\fR
c0c23a60
RK
240Adds a directory to the plugin path.
241(This is also used by the web interface.)
460b9539 242.IP
243Plugins are opened the first time they are required and never after,
244so after changing a plugin you must restart the server before it is
245guaranteed to take effect.
40c30921
RK
246.IP
247If
248.B plugins
249is used without arguments the plugin path is cleared.
460b9539 250.SS "Server Configuration"
251.TP
252.B alias \fIPATTERN\fR
253Defines the pattern use construct virtual filenames from \fBtrackname_\fR
254preferences.
255.IP
256Most characters stand for themselves, the exception being \fB{\fR which is used
257to insert a track name part in the form \fB{\fIname\fB}\fR or
258\fB{/\fIname\fB}\fR.
259.IP
260The difference is that the first form just inserts the name part while the
261second prefixes it with a \fB/\fR if it is nonempty.
262.IP
263The pattern should not attempt to include the collection root, which is
264automatically included, but should include the proper extension.
265.IP
266The default is \fB{/artist}{/album}{/title}{ext}\fR.
267.TP
bd8895a8 268.B api \fINAME\fR
c0c23a60
RK
269Selects the backend used to play sound and to set the volume.
270The following options are available:
bd8895a8 271.RS
272.TP
273.B alsa
c0c23a60
RK
274Use the ALSA API.
275This is only available on Linux systems, on which it is the default.
bd8895a8 276.TP
277.B coreaudio
c0c23a60
RK
278Use Apple Core Audio.
279This only available on OS X systems, on which it is the default.
bd8895a8 280.TP
281.B oss
c0c23a60
RK
282Use the OSS (/dev/dsp) API.
283Not available on all platforms.
bd8895a8 284.TP
285.B command
c0c23a60
RK
286Execute a command.
287This is the default if
bd8895a8 288.B speaker_command
289is specified, or if no native is available.
290.TP
291.B network
c0c23a60
RK
292Transmit audio over the network.
293This is the default if \fBbroadcast\fR is specified.
294You can use
bd8895a8 295.BR disorder-playrtp (1)
296to receive and play the resulting stream on Linux and OS X.
297.RE
298.TP
25ca855b 299.B authorization_algorithm \fIALGORITHM\fR
c0c23a60
RK
300Defines the algorithm used to authenticate clients.
301The valid options are sha1 (the default), sha256, sha384 and sha512.
302See
637fdea3
RK
303.BR disorder_protocol (5)
304for more details.
305.TP
30ad4dab 306.B broadcast \fIADDRESS\fR \fIPORT\fR
c0c23a60
RK
307Transmit sound data to \fIADDRESS\fR using UDP port \fIPORT\fR.
308This implies \fBapi network\fR.
61941295
RK
309.IP
310See also \fBmulticast_loop\fR and \fBmulticast_ttl\fR.
30ad4dab 311.TP
312.B broadcast_from \fIADDRESS\fR \fIPORT\fR
313Sets the (local) source address used by \fBbroadcast\fR.
314.TP
460b9539 315.B channel \fICHANNEL\fR
bd8895a8 316The mixer channel that the volume control should use.
317.IP
318For \fBapi oss\fR the possible values are:
460b9539 319.RS
320.TP 8
321.B pcm
c0c23a60
RK
322Output level for the audio device.
323This is probably what you want and is the default.
460b9539 324.TP
325.B speaker
326Output level for the PC speaker, if that is connected to the sound card.
327.TP
328.B pcm2
329Output level for alternative codec device.
330.TP
331.B vol
c0c23a60
RK
332Master output level.
333The OSS documentation recommends against using this, as it affects all
334output devices.
460b9539 335.RE
336.IP
bd8895a8 337You can also specify channels by number, if you know the right value.
338.IP
c0c23a60
RK
339For \fBapi alsa\fR, this is the name of the mixer control to use.
340The default is \fBPCM\fR.
341Use \fBamixer scontrols\fR or similar to get a full list.
bd8895a8 342.IP
343For \fBapi coreaudio\fR, volume setting is not currently supported.
460b9539 344.TP
345.B collection \fIMODULE\fR \fIENCODING\fR \fIROOT\fR
01cef138
RK
346.TP
347.B collection \fIMODULE\fR \fIROOT\fR
348.TP
349.B collection \fIROOT\fR
460b9539 350Define a collection of tracks.
351.IP
352\fIMODULE\fR defines which plugin module should be used for this
c0c23a60
RK
353collection.
354Use the supplied \fBfs\fR module for tracks that exist as ordinary
355files in the filesystem.
356If no \fIMODULE\fR is specified then \fBfs\fR is assumed.
357.IP
358\fIENCODING\fR defines the encoding of filenames in this collection.
359For \fBfs\fR this would be the encoding you use for filenames.
0d350ff0 360Examples might be \fBiso\-8859\-1\fR or \fButf\-8\fR.
c0c23a60
RK
361If no encoding is specified then the current locale's character encoding
362is used.
460b9539 363.IP
01cef138
RK
364NB that this default depends on the locale the server runs in, which is not
365necessarily the same as that of ordinary users, depending how the system is
c0c23a60
RK
366configured.
367It's best to explicitly specify it to be certain.
460b9539 368.IP
369\fIROOT\fR is the root in the filesystem of the filenames and is
c0c23a60
RK
370passed to the plugin module.
371It must be an absolute path and should not end with a "/".
460b9539 372.TP
dafbdc04
RK
373.B cookie_key_lifetime \fISECONDS\fR
374Lifetime of the signing key used in constructing cookies. The default is one
375week.
376.TP
377.B cookie_login_lifetime \fISECONDS\fR
378Lifetime of a cookie enforced by the server. When the cookie expires the user
379will have to log in again even if their browser has remembered the cookie that
380long. The default is one day.
381.TP
04e1fa7c 382.B default_rights \fIRIGHTS\fR
c0c23a60
RK
383Defines the set of rights given to new users.
384The argument is a comma-separated list of rights.
385For the possible values see
04e1fa7c
RK
386.B "Users And Access Control"
387above.
388.IP
389The default is to allow everything except \fBadmin\fR and \fBregister\fR
390(modified in legacy configurations by the obsolete \fBrestrict\fR directive).
391.TP
460b9539 392.B device \fINAME\fR
bd8895a8 393Sound output device.
394.IP
c0c23a60
RK
395For \fBapi oss\fR this is the path to the device to use.
396If it is set to \fBdefault\fR then \fI/dev/dsp\fR and \fI/dev/audio\fR
397will be tried.
bd8895a8 398.IP
399For \fBapi alsa\fR this is the device name to use.
400.IP
401For \fBapi coreaudio\fR this is currently ignored.
402.IP
b25aac59 403The default is \fBdefault\fR, which is intended to map to whatever the system's
404default is.
460b9539 405.TP
406.B gap \fISECONDS\fR
c0c23a60
RK
407Specifies the number of seconds to leave between tracks.
408The default is 0.
49a773eb
RK
409.IP
410NB this option currently DOES NOT WORK. If there is genuine demand it might be
411reinstated.
460b9539 412.TP
413.B history \fIINTEGER\fR
414Specifies the number of recently played tracks to remember (including
415failed tracks and scratches).
416.TP
417.B listen \fR[\fIHOST\fR] \fISERVICE\fR
418Listen for connections on the address specified by \fIHOST\fR and port
c0c23a60
RK
419specified by \fISERVICE\fR.
420If \fIHOST\fR is omitted then listens on all local addresses.
460b9539 421.IP
422Normally the server only listens on a UNIX domain socket.
423.TP
424.B lock yes\fR|\fBno
c0c23a60
RK
425Determines whether the server locks against concurrent operation.
426Default is \fByes\fR.
427There is no good reason to set this to \fBno\fR and the option will
25ca855b 428probably be removed in a future version.
460b9539 429.TP
bd8895a8 430.B mixer \fIDEVICE\fR
431The mixer device name, if it needs to be specified separately from
432\fBdevice\fR.
433.IP
434For \fBapi oss\fR this should be the path to the mixer device and the default
435is \fI/dev/mixer\fR.
436.IP
c0c23a60
RK
437For \fBapi alsa\fR, this is the index of the mixer control to use.
438The default is 0.
bd8895a8 439.IP
440For \fBapi coreaudio\fR, volume setting is not currently supported.
460b9539 441.TP
61941295 442.B multicast_loop yes\fR|\fBno
c0c23a60
RK
443Determines whether multicast packets are loop backed to the sending host.
444The default is \fByes\fR.
445This only applies if \fBapi\fR is set to \fBnetwork\fR and \fBbroadcast\fR
446is actually a multicast address.
61941295 447.TP
23205f9c 448.B multicast_ttl \fIHOPS\fR
c0c23a60
RK
449Set the maximum number of hops to send multicast packets.
450This only applies if \fBapi\fR is set to \fBnetwork\fR and
451\fBbroadcast\fR is actually a multicast address.
452The default is 1.
23205f9c 453.TP
460b9539 454.B namepart \fIPART\fR \fIREGEXP\fR \fISUBST\fR [\fICONTEXT\fR [\fIREFLAGS\fR]]
455Determines how to extract trackname part \fIPART\fR from a
456track name (with the collection root part removed).
457Used in \fB@recent@\fR, \fB@playing@\fR and \fB@search@\fR.
458.IP
c0c23a60
RK
459Track names can be different in different contexts.
460For instance the sort string might include an initial track number,
461but this would be stripped for the display string.
462\fICONTEXT\fR should be a glob pattern matching the
460b9539 463contexts in which this directive will be used.
464.IP
465Valid contexts are \fBsort\fR and \fBdisplay\fR.
466.IP
c0c23a60
RK
467All the \fBnamepart\fR directives are considered in order.
468The first directive for the right part, that matches the desired context,
460b9539 469and with a \fIREGEXP\fR that
470matches the track is used, and the value chosen is constructed from
471\fISUBST\fR according to the substitution rules below.
472.IP
473Note that searches use the raw track name and \fBtrackname_\fR preferences but
474not (currently) the results of \fBnamepart\fR, so generating words via this option
475that aren't in the original track name will lead to confusing results.
476.IP
477If you supply no \fBnamepart\fR directives at all then a default set will be
c0c23a60
RK
478supplied automatically.
479But if you supply even one then you must supply all of them.
480The defaults are equivalent to:
25ca855b
RK
481.PP
482.nf
483namepart title "/([0-9]+ *[-:] *)?([^/]+)\\.[a-zA-Z0-9]+$" $2 display
484namepart title "/([^/]+)\\.[a-zA-Z0-9]+$" $1 sort
485namepart album "/([^/]+)/[^/]+$" $1 *
486namepart artist "/([^/]+)/[^/]+/[^/]+$" $1 *
487namepart ext "(\\.[a-zA-Z0-9]+)$" $1 *
488.fi
460b9539 489.TP
d742bb47 490.B new_max \fIMAX\fR
c0c23a60
RK
491The maximum number of tracks to list when reporting newly noticed tracks.
492The default is 100.
d742bb47 493.TP
460b9539 494.B nice_rescan \fIPRIORITY\fR
c0c23a60
RK
495Set the recan subprocess priority.
496The default is 10.
460b9539 497.IP
498(Note that higher values mean the process gets less CPU time; UNIX priority
04e42396 499values are backwards.)
460b9539 500.TP
501.B nice_server \fIPRIORITY\fR
c0c23a60
RK
502Set the server priority.
503This is applied to the server at startup time (and not when you reload
504configuration).
505The server does not use much CPU itself but this value is inherited
506by programs it executes.
507If you have limited CPU then it might help to set this to a small
508negative value.
509The default is 0.
460b9539 510.TP
511.B nice_speaker \fIPRIORITY\fR
c0c23a60
RK
512Set the speaker process priority.
513This is applied to the speaker process at startup time (and not when
514you reload the configuration).
515The speaker process is not massively CPU intensive by today's
516standards but depends on reasonably timely scheduling.
517If you have limited CPU then it might help to set this to a small
518negative value.
519The default is 0.
460b9539 520.TP
2a10b70b
RK
521.B noticed_history
522The maximum days that a track can survive in the database of newly added
c0c23a60
RK
523tracks.
524The default is 31.
2a10b70b 525.TP
0d350ff0 526.B player \fIPATTERN\fR \fIMODULE\fR [\fIOPTIONS.. [\fB\-\-\fR]] \fIARGS\fR...
c0c23a60
RK
527Specifies the player for files matching the glob \fIPATTERN\fR.
528\fIMODULE\fR specifies which plugin module to use.
460b9539 529.IP
530The following options are supported:
531.RS
532.TP
0d350ff0 533.B \-\-wait\-for\-device\fR[\fB=\fIDEVICE\fR]
460b9539 534Waits (for up to a couple of seconds) for the default, or specified, libao
535device to become openable.
536.TP
0d350ff0 537.B \-\-
c0c23a60 538Defines the end of the list of options.
0d350ff0 539Needed if the first argument to the plugin starts with a "\-".
460b9539 540.RE
541.IP
542The following are the standard modules:
543.RS
544.TP
545.B exec \fICOMMAND\fR \fIARGS\fR...
546The command is executed via \fBexecvp\fR(3), not via the shell.
547The \fBPATH\fR environment variable is searched for the executable if it is not
548an absolute path.
549The command is expected to know how to open its own sound device.
550.TP
551.B execraw \fICOMMAND\fR \fIARGS\fR...
552Identical to the \fBexec\fR except that the player is expected to use the
ce6c36be 553DisOrder raw player protocol.
554.BR disorder-decode (8)
c0c23a60
RK
555can decode several common audio file formats to this format.
556If your favourite format is not supported, but you have a player
557which uses libao, there is also a libao driver which supports this format;
558see below for more information about this.
460b9539 559.TP
560.B shell \fR[\fISHELL\fR] \fICOMMAND\fR
c0c23a60
RK
561The command is executed using the shell.
562If \fISHELL\fR is specified then that is used, otherwise \fBsh\fR will be used.
563In either case the \fBPATH\fR environment variable is searched for the shell
564executable if it is not an absolute path.
565The track name is stored in the environment variable
460b9539 566\fBTRACK\fR.
567.IP
568Be careful of the interaction between the configuration file quoting rules and
569the shell quoting rules.
570.RE
571.IP
572If multiple player commands match a track then the first match is used.
62dc3748
RK
573.IP
574For the server to be able to calculate track lengths, there should be a
575.B tracklength
576command corresponding to each
577.B player
578command.
40c30921
RK
579.IP
580If
581.B player
582is used without arguments, the list of players is cleared.
460b9539 583.TP
584.B prefsync \fISECONDS\fR
c0c23a60
RK
585The interval at which the preferences log file will be synchronised.
586Defaults to 3600, i.e. one hour.
460b9539 587.TP
459d4402 588.B queue_pad \fICOUNT\fR
c0c23a60
RK
589The target size of the queue.
590If random play is enabled then randomly picked tracks will be added until
591the queue is at least this big.
592The default is 10.
459d4402 593.TP
6207d2f3 594.B reminder_interval \fISECONDS\fR
c0c23a60
RK
595The minimum number of seconds that must elapse between password reminders.
596The default is 600, i.e. 10 minutes.
6207d2f3 597.TP
810b8083
RK
598.B remote_userman yes\fR|\fBno
599User management over TCP connection is only allowed if this is set to
600\fByes\fR. By default it is set to \fBno\fR.
601.TP
cebe3127
RK
602.B replay_min \fISECONDS\fR
603The minimum number of seconds that must elapse after a track has been played
604before it can be picked at random. The default is 8 hours. If this is set to
6050 then there is no limit, though current \fBdisorder-choose\fR will not pick
606anything currently listed in the recently-played list.
607.TP
405fea4e 608.B sample_format \fIBITS\fB/\fIRATE\fB/\fICHANNELS
c0c23a60
RK
609Describes the sample format expected by the \fBspeaker_command\fR (below).
610The components of the format specification are as follows:
405fea4e 611.RS
612.TP 10
613.I BITS
c0c23a60
RK
614The number of bits per sample.
615Optionally, may be suffixed by \fBb\fR or \fBl\fR for big-endian and
616little-endian words.
617If neither is used the native byte order is assumed.
405fea4e 618.TP
619.I RATE
620The number of samples per second.
621.TP
622.I CHANNELS
623The number of channels.
624.PP
625The default is
626.BR 16/44100/2 .
937be4c0
RK
627.PP
628With the
629.B network
630backend the sample format is forced to
e99d42b1 631.B 16b/44100/2
937be4c0
RK
632and with the
633.B coreaudio
634backend it is forced to
635.BR 16/44100/2 ,
636in both cases regardless of what is specified in the configuration file.
405fea4e 637.RE
638.TP
460b9539 639.B signal \fINAME\fR
640Defines the signal to be sent to track player process groups when tracks are
c0c23a60
RK
641scratched.
642The default is \fBSIGKILL\fR.
460b9539 643.IP
644Signals are specified by their full C name, i.e. \fBSIGINT\fR and not \fBINT\fR
645or \fBInterrupted\fR or whatever.
646.TP
5330d674 647.B sox_generation \fB0\fR|\fB1
0d350ff0
RK
648Determines whether calls to \fBsox\fR(1) should use \fB\-b\fR, \fB\-x\fR, etc (if
649the generation is 0) or \fB\-\fIbits\fR, \fB\-L\fR etc (if it is 1).
c0c23a60
RK
650See the documentation for your installed copy of \fBsox\fR to determine
651which you need.
25ca855b 652The default is 0.
5330d674 653.TP
bd8895a8 654.B speaker_backend \fINAME
655This is an alias for \fBapi\fR; see above.
656.TP
405fea4e 657.B speaker_command \fICOMMAND
658Causes the speaker subprocess to pipe audio data into shell command
c0c23a60
RK
659\fICOMMAND\fR, rather than writing to a local sound card.
660The sample format is determine by
405fea4e 661.B sample_format
662above.
77cfc7a2 663.IP
664Note that if the sample format is wrong then
665.BR sox (1)
c0c23a60
RK
666is invoked to translate it.
667If
77cfc7a2 668.B sox
669is not installed then this will not work.
405fea4e 670.TP
460b9539 671.B scratch \fIPATH\fR
c0c23a60
RK
672Specifies a scratch.
673When a track is scratched, a scratch track is played at random.
460b9539 674Scratches are played using the same logic as other tracks.
675.IP
676At least for the time being, path names of scratches must be encoded using
677UTF-8 (which means that ASCII will do).
40c30921
RK
678.IP
679If \fBscratch\fR is used without arguments then the list of scratches is
680cleared.
460b9539 681.TP
682.B stopword \fIWORD\fR ...
683Specifies one or more stopwords that should not take part in searches
684over track names.
40c30921
RK
685.IP
686If \fBstopword\fR is used without arguments then the list of stopwords is
687cleared.
86be0c30 688.IP
689There is a default set of stopwords built in, but this option can be used to
690augment or replace that list.
62dc3748
RK
691.TP
692.B tracklength \fIPATTERN\fR \fIMODULE\fR
693Specifies the module used to calculate the length of files matching
c0c23a60
RK
694\fIPATTERN\fR.
695\fIMODULE\fR specifies which plugin module to use.
40c30921
RK
696.IP
697If \fBtracklength\fR is used without arguments then the list of modules is
698cleared.
eb5dc014 699.TP
90ad6c6e 700.B user \fIUSERNAME\fR
c0c23a60
RK
701Specifies the user to run as.
702Only makes sense if invoked as root (or the target user).
460b9539 703.SS "Client Configuration"
704.TP
ccf0aafa 705.B connect \fIHOST SERVICE\fR
460b9539 706Connect to the address specified by \fIHOST\fR and port specified by
ccf0aafa 707\fISERVICE\fR.
460b9539 708.SS "Web Interface Configuration"
709.TP
e70701e7 710.B mail_sender \fIADDRESS\fR
711The email address that appears in the From: field of any mail messages sent by
c0c23a60
RK
712the web interface.
713This must be set if you have online registration enabled.
e70701e7 714.TP
460b9539 715.B refresh \fISECONDS\fR
c0c23a60
RK
716Specifies the maximum refresh period in seconds.
717Default 15.
460b9539 718.TP
61507e3c
RK
719.B short_display \fICHARACTERS\fR
720Defines the maximum number of characters to include in a \fBshort\fR name
c0c23a60
RK
721part.
722Default 30.
61507e3c 723.TP
e70701e7 724.B smtp_server \fIHOSTNAME\fR
c0c23a60
RK
725The hostname (or address) of the SMTP server to use for sending mail.
726The default is 127.0.0.1.
e70701e7 727.TP
460b9539 728.B templates \fIPATH\fR ...
729Specifies the directory containing templates used by the web
c0c23a60
RK
730interface.
731If a template appears in more than one template directory
460b9539 732then the one in the earliest directory specified is chosen.
733.IP
734See below for further details.
40c30921
RK
735.IP
736If \fBtemplates\fR is used without arguments then the template path is cleared.
460b9539 737.TP
738.B transform \fITYPE\fR \fIREGEXP\fR \fISUBST\fR [\fICONTEXT\fR [\fIREFLAGS\fR]]
739Determines how names are sorted and displayed in track choice displays.
740.IP
741\fITYPE\fR is the type of transformation; usually \fBtrack\fR or
742\fBdir\fR but you can define your own.
743.IP
c0c23a60
RK
744\fICONTEXT\fR is a glob pattern matching the context.
745Standard contexts are \fBsort\fR (which determines how directory names
746are sorted) and \fBdisplay\fR (which determines how they are displayed).
747Again, you can define your own.
460b9539 748.IP
c0c23a60
RK
749All the \fBtransform\fR directives are considered in order.
750If the \fITYPE\fR, \fIREGEXP\fR and the \fICONTEXT\fR match
460b9539 751then a new track name is constructed from
c0c23a60
RK
752\fISUBST\fR according to the substitution rules below.
753If several match then each is executed in order.
460b9539 754.IP
755If you supply no \fBtransform\fR directives at all then a default set will be
c0c23a60
RK
756supplied automatically.
757But if you supply even one then you must supply all of them.
758The defaults are:
25ca855b
RK
759.PP
760.nf
761transform track "^.*/([0-9]+ *[-:] *)?([^/]+)\\.[a-zA-Z0-9]+$" $2 display
762transform track "^.*/([^/]+)\\.[a-zA-Z0-9]+$" $1 sort
763transform dir "^.*/([^/]+)$" $1 *
764transform dir "^(the) ([^/]*)" "$2 $1" sort i
765transform dir "[[:punct:]]" "" sort g
766.fi
460b9539 767.TP
768.B url \fIURL\fR
c0c23a60
RK
769Specifies the URL of the web interface.
770This URL will be used in generated web pages.
771The default is inferred at runtime, so this option no
b64c2805 772longer needs to be specified.
460b9539 773.IP
774This must be the full URL, e.g. \fBhttp://myhost/cgi-bin/jukebox\fR and not
775\fB/cgi-bin/jukebox\fR.
776.SS "Authentication Configuration"
90ad6c6e
RK
777These options would normally be used in \fI~\fRUSERNAME\fI/.disorder/passwd\fR
778or
779\fIpkgconfdir/config.\fRUSERNAME.
460b9539 780.TP
460b9539 781.B password \fIPASSWORD\fR
782Specify password.
783.TP
460b9539 784.B username \fIUSERNAME\fR
c0c23a60
RK
785Specify username.
786The default is taken from the environment variable \fBLOGNAME\fR.
460b9539 787.SH "GLOBAL PREFERENCES"
0d350ff0 788These are the values set with \fBset\-global\fR.
460b9539 789.TP
0d350ff0 790.B required\-tags
460b9539 791If this is set an nonempty then randomly played tracks will always have at
792least one of the listed tags.
460b9539 793.TP
0d350ff0 794.B prohibited\-tags
460b9539 795If this is set an nonempty then randomly played tracks will never have any of
796the listed tags.
797.TP
798.B playing
c0c23a60
RK
799If unset or \fByes\fR then play is enabled.
800Otherwise it is disabled.
801Use \fBdisable\fR rather than setting it directly.
460b9539 802.TP
0d350ff0 803.B random\-play
c0c23a60
RK
804If unset or \fByes\fR then random play is enabled.
805Otherwise it is disabled.
460b9539 806Use \fBdisable\fR rather than setting it directly.
f9635e06
RK
807.PP
808Global preferences starting '_' are read-only (in the sense that you cannot
c0c23a60
RK
809modify them; the server may modify them as part of its normal operation).
810They are:
f9635e06
RK
811.TP
812.B _dbversion
c0c23a60
RK
813The database version string.
814This is used by DisOrder to detect when it must
f9635e06 815modify the database after an upgrade.
460b9539 816.SH "LIBAO DRIVER"
817.SS "Raw Protocol Players"
818Raw protocol players are expected to use the \fBdisorder\fR libao driver.
819Programs that use libao generally have command line options to select the
820driver and pass options to it.
821.SS "Driver Options"
822The known driver options are:
823.TP
824.B fd
c0c23a60
RK
825The file descriptor to write to.
826If this is not specified then the driver looks like the environment
827variable \fBDISORDER_RAW_FD\fR.
828If that is not set then the default is 1 (i.e. standard output).
460b9539 829.TP
830.B fragile
831If this is set to a nonzero value then the driver will call \fB_exit\fR(2) if a
c0c23a60
RK
832write to the output file descriptor fails.
833This is a workaround for buggy players such as \fBogg123\fR that ignore
834write errors.
3e1616b6
RK
835.SH "REGEXP SUBSTITUTION RULES"
836Regexps are PCRE regexps, as defined in \fBpcrepattern\fR(3).
837The only option used is \fBPCRE_UTF8\fR.
838Remember that the configuration file syntax means you have to
839escape backslashes and quotes inside quoted strings.
840.PP
841In a \fISUBST\fR string the following sequences are interpreted
842specially:
843.TP
844.B $1 \fR... \fB$9
845These expand to the first to ninth bracketed subexpression.
846.TP
847.B $&
848This expands to the matched part of the subject string.
849.TP
850.B $$
851This expands to a single \fB$\fR symbol.
852.PP
853All other pairs starting with \fB$\fR are undefined (and might be used
854for something else in the future, so don't rely on the current
855behaviour.)
856.PP
857If \fBi\fR is present in \fIREFLAGS\fR then the match is case-independent.
858If \fBg\fR is present then all matches are replaced, otherwise only the first
859match is replaced.
460b9539 860.SH "TRACK NAME PARTS"
861The traditional track name parts are \fBartist\fR, \fBalbum\fR and \fBtitle\fR,
c0c23a60
RK
862with the obvious intended meaning.
863These are controlled by configuration and by \fBtrackname_\fR preferences.
460b9539 864.PP
865In addition there are two built-in parts, \fBpath\fR which is the whole path
866name and \fBext\fR which is the filename extension, including the initial dot
867(or the empty string if there is not extension).
868.SH "SEE ALSO"
0d350ff0 869\fBdisorder\fR(1), \fBsox\fR(1), \fBdisorderd\fR(8), \fBdisorder\-dump\fR(8),
5c1ae3bc
RK
870\fBpcrepattern\fR(3), \fBdisorder_templates\fR(5), \fBdisorder_actions\fR(5),
871\fBdisorder.cgi\fR(8)
460b9539 872.\" Local Variables:
873.\" mode:nroff
874.\" fill-column:79
875.\" End: