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