chiark / gitweb /
TABLE_FIND() now uses typeof. We're committed to GCC anyway so it
[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
05dcfac6
RK
490.B new_bias \fIWEIGHT\fR
491The weight for new tracks.
492The default is 900000, i.e. recently added tracks are a hundred times as likely
493to be picked as normal.
494.TP
495.B new_bias_age \fISECONDS\fR
496The maximum age of tracks that \fBnew_bias\fR applies to, in seconds.
497The default is one week.
498.TP
d742bb47 499.B new_max \fIMAX\fR
c0c23a60
RK
500The maximum number of tracks to list when reporting newly noticed tracks.
501The default is 100.
d742bb47 502.TP
460b9539 503.B nice_rescan \fIPRIORITY\fR
c0c23a60
RK
504Set the recan subprocess priority.
505The default is 10.
460b9539 506.IP
507(Note that higher values mean the process gets less CPU time; UNIX priority
04e42396 508values are backwards.)
460b9539 509.TP
510.B nice_server \fIPRIORITY\fR
c0c23a60
RK
511Set the server priority.
512This is applied to the server at startup time (and not when you reload
513configuration).
514The server does not use much CPU itself but this value is inherited
515by programs it executes.
516If you have limited CPU then it might help to set this to a small
517negative value.
518The default is 0.
460b9539 519.TP
520.B nice_speaker \fIPRIORITY\fR
c0c23a60
RK
521Set the speaker process priority.
522This is applied to the speaker process at startup time (and not when
523you reload the configuration).
524The speaker process is not massively CPU intensive by today's
525standards but depends on reasonably timely scheduling.
526If you have limited CPU then it might help to set this to a small
527negative value.
528The default is 0.
460b9539 529.TP
2a10b70b
RK
530.B noticed_history
531The maximum days that a track can survive in the database of newly added
c0c23a60
RK
532tracks.
533The default is 31.
2a10b70b 534.TP
0d350ff0 535.B player \fIPATTERN\fR \fIMODULE\fR [\fIOPTIONS.. [\fB\-\-\fR]] \fIARGS\fR...
c0c23a60
RK
536Specifies the player for files matching the glob \fIPATTERN\fR.
537\fIMODULE\fR specifies which plugin module to use.
460b9539 538.IP
539The following options are supported:
540.RS
541.TP
0d350ff0 542.B \-\-wait\-for\-device\fR[\fB=\fIDEVICE\fR]
460b9539 543Waits (for up to a couple of seconds) for the default, or specified, libao
544device to become openable.
545.TP
0d350ff0 546.B \-\-
c0c23a60 547Defines the end of the list of options.
0d350ff0 548Needed if the first argument to the plugin starts with a "\-".
460b9539 549.RE
550.IP
551The following are the standard modules:
552.RS
553.TP
554.B exec \fICOMMAND\fR \fIARGS\fR...
555The command is executed via \fBexecvp\fR(3), not via the shell.
556The \fBPATH\fR environment variable is searched for the executable if it is not
557an absolute path.
558The command is expected to know how to open its own sound device.
559.TP
560.B execraw \fICOMMAND\fR \fIARGS\fR...
561Identical to the \fBexec\fR except that the player is expected to use the
ce6c36be 562DisOrder raw player protocol.
563.BR disorder-decode (8)
c0c23a60
RK
564can decode several common audio file formats to this format.
565If your favourite format is not supported, but you have a player
566which uses libao, there is also a libao driver which supports this format;
567see below for more information about this.
460b9539 568.TP
569.B shell \fR[\fISHELL\fR] \fICOMMAND\fR
c0c23a60
RK
570The command is executed using the shell.
571If \fISHELL\fR is specified then that is used, otherwise \fBsh\fR will be used.
572In either case the \fBPATH\fR environment variable is searched for the shell
573executable if it is not an absolute path.
574The track name is stored in the environment variable
460b9539 575\fBTRACK\fR.
576.IP
577Be careful of the interaction between the configuration file quoting rules and
578the shell quoting rules.
579.RE
580.IP
581If multiple player commands match a track then the first match is used.
62dc3748
RK
582.IP
583For the server to be able to calculate track lengths, there should be a
584.B tracklength
585command corresponding to each
586.B player
587command.
40c30921
RK
588.IP
589If
590.B player
591is used without arguments, the list of players is cleared.
460b9539 592.TP
593.B prefsync \fISECONDS\fR
c0c23a60
RK
594The interval at which the preferences log file will be synchronised.
595Defaults to 3600, i.e. one hour.
460b9539 596.TP
459d4402 597.B queue_pad \fICOUNT\fR
c0c23a60
RK
598The target size of the queue.
599If random play is enabled then randomly picked tracks will be added until
600the queue is at least this big.
601The default is 10.
459d4402 602.TP
6207d2f3 603.B reminder_interval \fISECONDS\fR
c0c23a60
RK
604The minimum number of seconds that must elapse between password reminders.
605The default is 600, i.e. 10 minutes.
6207d2f3 606.TP
810b8083
RK
607.B remote_userman yes\fR|\fBno
608User management over TCP connection is only allowed if this is set to
609\fByes\fR. By default it is set to \fBno\fR.
610.TP
cebe3127
RK
611.B replay_min \fISECONDS\fR
612The minimum number of seconds that must elapse after a track has been played
613before it can be picked at random. The default is 8 hours. If this is set to
6140 then there is no limit, though current \fBdisorder-choose\fR will not pick
615anything currently listed in the recently-played list.
616.TP
405fea4e 617.B sample_format \fIBITS\fB/\fIRATE\fB/\fICHANNELS
c0c23a60
RK
618Describes the sample format expected by the \fBspeaker_command\fR (below).
619The components of the format specification are as follows:
405fea4e 620.RS
621.TP 10
622.I BITS
c0c23a60
RK
623The number of bits per sample.
624Optionally, may be suffixed by \fBb\fR or \fBl\fR for big-endian and
625little-endian words.
626If neither is used the native byte order is assumed.
405fea4e 627.TP
628.I RATE
629The number of samples per second.
630.TP
631.I CHANNELS
632The number of channels.
633.PP
634The default is
635.BR 16/44100/2 .
937be4c0
RK
636.PP
637With the
638.B network
639backend the sample format is forced to
e99d42b1 640.B 16b/44100/2
937be4c0
RK
641and with the
642.B coreaudio
643backend it is forced to
644.BR 16/44100/2 ,
645in both cases regardless of what is specified in the configuration file.
405fea4e 646.RE
647.TP
460b9539 648.B signal \fINAME\fR
649Defines the signal to be sent to track player process groups when tracks are
c0c23a60
RK
650scratched.
651The default is \fBSIGKILL\fR.
460b9539 652.IP
653Signals are specified by their full C name, i.e. \fBSIGINT\fR and not \fBINT\fR
654or \fBInterrupted\fR or whatever.
655.TP
5330d674 656.B sox_generation \fB0\fR|\fB1
0d350ff0
RK
657Determines whether calls to \fBsox\fR(1) should use \fB\-b\fR, \fB\-x\fR, etc (if
658the generation is 0) or \fB\-\fIbits\fR, \fB\-L\fR etc (if it is 1).
c0c23a60
RK
659See the documentation for your installed copy of \fBsox\fR to determine
660which you need.
25ca855b 661The default is 0.
5330d674 662.TP
bd8895a8 663.B speaker_backend \fINAME
664This is an alias for \fBapi\fR; see above.
665.TP
405fea4e 666.B speaker_command \fICOMMAND
667Causes the speaker subprocess to pipe audio data into shell command
c0c23a60
RK
668\fICOMMAND\fR, rather than writing to a local sound card.
669The sample format is determine by
405fea4e 670.B sample_format
671above.
77cfc7a2 672.IP
673Note that if the sample format is wrong then
674.BR sox (1)
c0c23a60
RK
675is invoked to translate it.
676If
77cfc7a2 677.B sox
678is not installed then this will not work.
405fea4e 679.TP
460b9539 680.B scratch \fIPATH\fR
c0c23a60
RK
681Specifies a scratch.
682When a track is scratched, a scratch track is played at random.
460b9539 683Scratches are played using the same logic as other tracks.
684.IP
685At least for the time being, path names of scratches must be encoded using
686UTF-8 (which means that ASCII will do).
40c30921
RK
687.IP
688If \fBscratch\fR is used without arguments then the list of scratches is
689cleared.
460b9539 690.TP
691.B stopword \fIWORD\fR ...
692Specifies one or more stopwords that should not take part in searches
693over track names.
40c30921
RK
694.IP
695If \fBstopword\fR is used without arguments then the list of stopwords is
696cleared.
86be0c30 697.IP
698There is a default set of stopwords built in, but this option can be used to
699augment or replace that list.
62dc3748
RK
700.TP
701.B tracklength \fIPATTERN\fR \fIMODULE\fR
702Specifies the module used to calculate the length of files matching
c0c23a60
RK
703\fIPATTERN\fR.
704\fIMODULE\fR specifies which plugin module to use.
40c30921
RK
705.IP
706If \fBtracklength\fR is used without arguments then the list of modules is
707cleared.
eb5dc014 708.TP
90ad6c6e 709.B user \fIUSERNAME\fR
c0c23a60
RK
710Specifies the user to run as.
711Only makes sense if invoked as root (or the target user).
460b9539 712.SS "Client Configuration"
713.TP
ccf0aafa 714.B connect \fIHOST SERVICE\fR
460b9539 715Connect to the address specified by \fIHOST\fR and port specified by
ccf0aafa 716\fISERVICE\fR.
460b9539 717.SS "Web Interface Configuration"
718.TP
e70701e7 719.B mail_sender \fIADDRESS\fR
720The email address that appears in the From: field of any mail messages sent by
c0c23a60
RK
721the web interface.
722This must be set if you have online registration enabled.
e70701e7 723.TP
460b9539 724.B refresh \fISECONDS\fR
c0c23a60
RK
725Specifies the maximum refresh period in seconds.
726Default 15.
460b9539 727.TP
61507e3c
RK
728.B short_display \fICHARACTERS\fR
729Defines the maximum number of characters to include in a \fBshort\fR name
c0c23a60
RK
730part.
731Default 30.
61507e3c 732.TP
e70701e7 733.B smtp_server \fIHOSTNAME\fR
c0c23a60
RK
734The hostname (or address) of the SMTP server to use for sending mail.
735The default is 127.0.0.1.
e70701e7 736.TP
460b9539 737.B templates \fIPATH\fR ...
738Specifies the directory containing templates used by the web
c0c23a60
RK
739interface.
740If a template appears in more than one template directory
460b9539 741then the one in the earliest directory specified is chosen.
742.IP
743See below for further details.
40c30921
RK
744.IP
745If \fBtemplates\fR is used without arguments then the template path is cleared.
460b9539 746.TP
747.B transform \fITYPE\fR \fIREGEXP\fR \fISUBST\fR [\fICONTEXT\fR [\fIREFLAGS\fR]]
748Determines how names are sorted and displayed in track choice displays.
749.IP
750\fITYPE\fR is the type of transformation; usually \fBtrack\fR or
751\fBdir\fR but you can define your own.
752.IP
c0c23a60
RK
753\fICONTEXT\fR is a glob pattern matching the context.
754Standard contexts are \fBsort\fR (which determines how directory names
755are sorted) and \fBdisplay\fR (which determines how they are displayed).
756Again, you can define your own.
460b9539 757.IP
c0c23a60
RK
758All the \fBtransform\fR directives are considered in order.
759If the \fITYPE\fR, \fIREGEXP\fR and the \fICONTEXT\fR match
460b9539 760then a new track name is constructed from
c0c23a60
RK
761\fISUBST\fR according to the substitution rules below.
762If several match then each is executed in order.
460b9539 763.IP
764If you supply no \fBtransform\fR directives at all then a default set will be
c0c23a60
RK
765supplied automatically.
766But if you supply even one then you must supply all of them.
767The defaults are:
25ca855b
RK
768.PP
769.nf
770transform track "^.*/([0-9]+ *[-:] *)?([^/]+)\\.[a-zA-Z0-9]+$" $2 display
771transform track "^.*/([^/]+)\\.[a-zA-Z0-9]+$" $1 sort
772transform dir "^.*/([^/]+)$" $1 *
773transform dir "^(the) ([^/]*)" "$2 $1" sort i
774transform dir "[[:punct:]]" "" sort g
775.fi
460b9539 776.TP
777.B url \fIURL\fR
c0c23a60
RK
778Specifies the URL of the web interface.
779This URL will be used in generated web pages.
780The default is inferred at runtime, so this option no
b64c2805 781longer needs to be specified.
460b9539 782.IP
783This must be the full URL, e.g. \fBhttp://myhost/cgi-bin/jukebox\fR and not
784\fB/cgi-bin/jukebox\fR.
785.SS "Authentication Configuration"
90ad6c6e
RK
786These options would normally be used in \fI~\fRUSERNAME\fI/.disorder/passwd\fR
787or
788\fIpkgconfdir/config.\fRUSERNAME.
460b9539 789.TP
460b9539 790.B password \fIPASSWORD\fR
791Specify password.
792.TP
460b9539 793.B username \fIUSERNAME\fR
c0c23a60
RK
794Specify username.
795The default is taken from the environment variable \fBLOGNAME\fR.
460b9539 796.SH "GLOBAL PREFERENCES"
0d350ff0 797These are the values set with \fBset\-global\fR.
460b9539 798.TP
0d350ff0 799.B required\-tags
460b9539 800If this is set an nonempty then randomly played tracks will always have at
801least one of the listed tags.
460b9539 802.TP
0d350ff0 803.B prohibited\-tags
460b9539 804If this is set an nonempty then randomly played tracks will never have any of
805the listed tags.
806.TP
807.B playing
c0c23a60
RK
808If unset or \fByes\fR then play is enabled.
809Otherwise it is disabled.
810Use \fBdisable\fR rather than setting it directly.
460b9539 811.TP
0d350ff0 812.B random\-play
c0c23a60
RK
813If unset or \fByes\fR then random play is enabled.
814Otherwise it is disabled.
460b9539 815Use \fBdisable\fR rather than setting it directly.
f9635e06
RK
816.PP
817Global preferences starting '_' are read-only (in the sense that you cannot
c0c23a60
RK
818modify them; the server may modify them as part of its normal operation).
819They are:
f9635e06
RK
820.TP
821.B _dbversion
c0c23a60
RK
822The database version string.
823This is used by DisOrder to detect when it must
f9635e06 824modify the database after an upgrade.
460b9539 825.SH "LIBAO DRIVER"
826.SS "Raw Protocol Players"
827Raw protocol players are expected to use the \fBdisorder\fR libao driver.
828Programs that use libao generally have command line options to select the
829driver and pass options to it.
830.SS "Driver Options"
831The known driver options are:
832.TP
833.B fd
c0c23a60
RK
834The file descriptor to write to.
835If this is not specified then the driver looks like the environment
836variable \fBDISORDER_RAW_FD\fR.
837If that is not set then the default is 1 (i.e. standard output).
460b9539 838.TP
839.B fragile
840If this is set to a nonzero value then the driver will call \fB_exit\fR(2) if a
c0c23a60
RK
841write to the output file descriptor fails.
842This is a workaround for buggy players such as \fBogg123\fR that ignore
843write errors.
3e1616b6
RK
844.SH "REGEXP SUBSTITUTION RULES"
845Regexps are PCRE regexps, as defined in \fBpcrepattern\fR(3).
846The only option used is \fBPCRE_UTF8\fR.
847Remember that the configuration file syntax means you have to
848escape backslashes and quotes inside quoted strings.
849.PP
850In a \fISUBST\fR string the following sequences are interpreted
851specially:
852.TP
853.B $1 \fR... \fB$9
854These expand to the first to ninth bracketed subexpression.
855.TP
856.B $&
857This expands to the matched part of the subject string.
858.TP
859.B $$
860This expands to a single \fB$\fR symbol.
861.PP
862All other pairs starting with \fB$\fR are undefined (and might be used
863for something else in the future, so don't rely on the current
864behaviour.)
865.PP
866If \fBi\fR is present in \fIREFLAGS\fR then the match is case-independent.
867If \fBg\fR is present then all matches are replaced, otherwise only the first
868match is replaced.
460b9539 869.SH "TRACK NAME PARTS"
870The traditional track name parts are \fBartist\fR, \fBalbum\fR and \fBtitle\fR,
c0c23a60
RK
871with the obvious intended meaning.
872These are controlled by configuration and by \fBtrackname_\fR preferences.
460b9539 873.PP
874In addition there are two built-in parts, \fBpath\fR which is the whole path
875name and \fBext\fR which is the filename extension, including the initial dot
876(or the empty string if there is not extension).
877.SH "SEE ALSO"
0d350ff0 878\fBdisorder\fR(1), \fBsox\fR(1), \fBdisorderd\fR(8), \fBdisorder\-dump\fR(8),
5c1ae3bc
RK
879\fBpcrepattern\fR(3), \fBdisorder_templates\fR(5), \fBdisorder_actions\fR(5),
880\fBdisorder.cgi\fR(8)
460b9539 881.\" Local Variables:
882.\" mode:nroff
883.\" fill-column:79
884.\" End: