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