2 .\" Copyright (C) 2004-2008 Richard Kettlewell
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 3 of the License, or
7 .\" (at your option) any later version.
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.
14 .\" You should have received a copy of the GNU General Public License
15 .\" along with this program. If not, see <http://www.gnu.org/licenses/>.
19 disorder \- DisOrder jukebox client
27 is used to query the \fBdisorderd\fR(8) daemon from the command line.
28 It may be used to request tracks, scratch tracks, query the current
29 state, etc, and by an administrator to shutdown or reconfigure the
32 If no commands are specified then \fBdisorder\fR connects to the
33 daemon and then immediately disconnects.
34 This can be used to test whether the daemon is running.
35 Otherwise, it executes the commands specified.
37 This man page documents the command-line client.
38 See \fBdisorderd\fR (8) for information about the server process
39 and \fBdisorder_config\fR (5) for documentation of the configuration file.
42 .B \-\-config \fIPATH\fR, \fB\-c \fIPATH
43 Set the configuration file.
47 environment variable, defaulting to
48 .IR pkgconfdir/config .
50 .B \-\-debug\fR, \fB\-d
53 .B \-\-help\fR, \fB\-h
54 Display a usage message.
56 .B \-\-version\fR, \fB\-V
57 Display version number.
59 .B \-\-help\-commands\fR, \fB\-H
60 List all known commands.
63 .B adduser \fIUSERNAME PASSWORD\fR [\fIRIGHTS\fR]
65 If \fIRIGHTS\fR is not specified then the \fBdefault_rights\fR
66 setting from the server's configuration file applies.
69 Adopts track \fIID\fR (in the queue).
70 The track will show up as submitted by the calling user.
72 .B authorize \fIUSERNAME\fR [\fIRIGHTS\fR]
73 Create user \fIUSERNAME\fR with a random password.
74 User \fIUSERNAME\fR must be a UNIX login user (not just any old string).
75 If \fIRIGHTS\fR is not specified then the \fBdefault_rights\fR
76 setting from the server's configuration file applies.
78 \fI~USERNAME/.disorder/passwd\fR is created with the password in it, so the new
79 user should be able to log in immediately.
81 If writing the \fIpasswd\fR file fails then the user will already have been
82 created in DisOrder's user database.
83 Use \fBdisorder deluser\fR to remove them before trying again.
85 .B deluser \fIUSERNAME\fR
88 .B dirs \fIDIRECTORY\fR [\fB~\fIREGEXP\fR]
89 List all the directories in \fIDIRECTORY\fR.
91 An optional regexp may be specified, marked with an initial \fB~\fR.
92 Only directories with a basename matching the regexp will be returned.
95 Disable playing after the current track finishes.
97 .B edituser \fIUSERNAME PROPERTY VALUE
98 Set some property of a user.
103 .B files \fIDIRECTORY\fR [\fB~\fIREGEXP\fR]
104 List all the files in \fIDIRECTORY\fR.
106 An optional regexp may be specified, marked with an initial \fB~\fR.
107 Only files with a basename matching the regexp will be returned.
109 .B get \fITRACK\fR \fIKEY\fR
110 Display the preference \fIKEY\fR for \fITRACK\fR.
111 See \fBdisorder_preferences\fR (5).
113 .B get\-global \fIKEY\fR
114 Get a global preference.
115 See \fBdisorder_preferences\fR (5).
118 Display the current volume settings.
120 .B length \fITRACK\fR
121 Display the length of \fITRACK\fR in seconds.
124 Write event log messages to standard output, until the server is terminated.
125 See \fBdisorder_protocol\fR (5) for details of the output syntax.
127 .B move \fITRACK\fR \fIDELTA\fR
133 Positive values move towards the head of the queue, negative
134 values towards the tail.
136 Note that if you specify a negative value then the
138 option separate (before all commands) becomes mandatory, as otherwise the
139 negative value is misinterpreted an an option.
141 .B part \fITRACK\fR \fICONTEXT\fI \fIPART\fR
142 Get a track name part.
144 \fICONTEXT\fR should be either \fBsort\fR or \fBdisplay\fR.
145 \fBpart\fR is the part of the name desired, typically \fBartist\fR,
146 \fBalbum\fR or \fBtitle\fR.
149 Pause the current track.
150 (Note that not all players support pausing.)
152 .B play \fITRACKS\fR...
153 Add \fITRACKS\fR to the end of the queue.
156 Report the currently playing track.
158 .B playlist-del \fIPLAYLIST\fR
159 Deletes playlist \fIPLAYLIST\fR.
161 .B playlist-get \fIPLAYLIST\fR
162 Gets the contents of playlist \fIPLAYLIST\fR.
164 .B playlist-set \fIPLAYLIST\fR [\fIPATH\fR]
165 Set the contents of playlist \fIPLAYLIST\fR.
166 If an absolute path name is specified then the track list is read from
168 Otherwise the track list is read from standard input.
169 In either case, the list is terminated either by end of file or by a line
170 containing a single ".".
173 Lists known playlists (in no particular order).
176 Display all the preferences for \fITRACK\fR.
177 See \fBdisorder_preferences\fR (5).
180 List the current queue.
181 The first entry in the list is the next track to play.
190 List recently played tracks.
191 The first entry is the oldest track, the last entry is the most
195 Make the daemon reload its configuration file.
197 Not all configuration options can be modified during the lifetime of the
198 server; of those that can't, some will just be ignored if they change while
199 others will cause the new configuration to be rejected.
200 See \fBdisorder_config\fR(5) for details.
202 .B remove \fITRACK\fR
203 Remove a track from the queue.
206 Rescan the filesystem for new tracks.
207 There is an automatic daily rescan but if you've just added some tracks
208 and want them to show up immediately, use this command.
210 .B resolve \fITRACK\fR
211 Resolve aliases for \fITRACK\fR and print out the real track name.
214 Resume the current track after a pause.
217 Report the RTP brodcast address used by the server (if any).
219 .B schedule-del \fIEVENT\fR
220 Delete a scheduled event.
223 List scheduled events.
224 Each line contains the ID, a timestamp, 'N' or 'J' for normal or junk priority,
225 the user, the action and action-specific data.
227 .B schedule-play \fIWHEN PRIORITY TRACK\fI
228 Play \fITRACK\fR at time \fIWHEN\fR.
229 Various time/date formats are supported depending on locale but the following
230 three will always work:
234 .B "YYYY-MM-DD HH:MM:SS"
242 \fIPRIORITY\fR should be \fBjunk\fR or \fBnormal\fR.
243 This determines how the event is handled if it becomes due when the server is
245 Junk events are just discarded in this case, while normal events will be
246 executed when the server comes back up, even if this is much later.
248 .B schedule-set-global \fIWHEN PRIORITY NAME VALUE\fI
249 Set global preference \fINAME\fR to \fIVALUE\fR at time \fIWHEN\fR.
251 .B schedule-unset-global \fIWHEN PRIORITY NAME\fI
252 Unset global preference \fINAME\fR at time \fIWHEN\fR.
255 Scratch the currently playing track.
257 .B scratch\-id \fIID\fR
258 Scratch the currently playing track, provided it has the given ID.
260 .B search \fITERMS\fR
261 Search for tracks containing all of the listed terms.
262 The terms are separated by spaces and form a single argument,
263 so must be quoted, for example:
265 .B "disorder search 'bowie china'"
267 You can limit the search to tracks with a particular tag, too, using the
271 .B "disorder search 'love tag:depressing'"
273 .B set \fITRACK\fR \fIKEY\fR \fIVALUE\fR
274 Set the preference \fIKEY\fR for \fITRACK\fR to \fIVALUE\fR.
275 See \fBdisorder_preferences\fR (5).
277 .B set\-global \fIKEY\fR \fIVALUE\fR
278 Set a global preference.
279 See \fBdisorder_preferences\fR (5).
281 .B set\-volume \fBLEFT\fR \fBRIGHT\fR
284 .B setup\-guest \fR[\fB\-\-no\-online\-registration\fR]
285 Create the "guest" user for use by the web interface.
286 This user will have no password and will only have the "read" and
287 "register" rights, the latter allowing new users to automatically
288 register themselves via the web interface.
290 With the option \fB\-\-no-online\-registration\fR, the "register" right is
291 suppressed and users must be manually created by an administrator.
293 If online registration is desired then \fBmail_sender\fR must be set in the
295 See \fBdisorder_config\fR(5).
298 Shut down the daemon.
301 List server statistics.
306 .B unset \fITRACK\fR \fIKEY\fR
307 Unset the preference \fIKEY\fR for \fITRACK\fR.
308 See \fBdisorder_preferences\fR (5).
310 .B unset\-global \fIKEY\fR
311 Unset the global preference \fIKEY\fR.
312 See \fBdisorder_preferences\fR (5).
314 .B userinfo \fIUSERNAME PROPERTY
315 Get some property of a user.
321 Report the daemon's version number.
327 tracks may be specified by name or by ID.
328 If you use the name and a track appears twice in the queue it is
329 undefined which is affected.
333 If you do not set the locale correctly then it may not handle non-ASCII
336 The client determines which user to attempt to authenticate as by examining the
338 This can be overridden in a per-user configuration file, see
339 \fBdisorder_config\fR(5).
341 See \fBdisorder_protocol\fR(5) for the rights required to run each command.
342 (For instance, \fBshutdown\fR requires the \fBadmin\fR right, which most users
343 would not normally have.)
345 This program is not intended to run in a setuid environment.
347 The regexp syntax used by the \fBfiles\fR and \fBdirs\fR commands use the
348 syntax described in \fBpcrepattern\fR(3).
349 Matching is case-independent.
350 It is strongly recommended that you quote regexps, since they often
351 contain characters treated specially by the shell.
354 .B "disorder dirs /Music ~'^(?!the [^t])t'"
356 If you cannot play a track, or it does not appear in the database even after a
357 rescan, check the following things:
360 Are there any error messages in the system log? The server logs to
361 \fBLOG_DAEMON\fR, which typically ends up in
362 .I /var/log/daemon.log
364 .IR /var/log/messages ,
365 though this depends on local configuration.
368 Is the track in a known format? Have a look at
370 for the formats recognized by the local installation.
371 The filename matching is case-sensitive.
374 Do permissions on the track allow the server to read it?
377 Do the permissions on the containing directories allow the server to read and
380 The user the server runs as is determined by the \fBuser\fR directive in the
382 The README recommends using \fBjukebox\fR for this purpose but it could
383 be different locally.
387 Main configuration file to use instead of
388 .IR pkgconfdir/config .
395 Per-user configuration and state directory to use instead of
396 .BR $HOME/.disorder .
398 .B DISORDER_PRIVCONFIG
399 Private configuration file to use instead of
400 .IR pkgconfdir/config.private .
402 .B DISORDER_USERCONFIG
403 Per-user configuration file to use instead of
404 .BR $DISORDER_HOME/passwd .
406 .B DISORDER_USERCONFIG_SYS
407 System-provided per-user configuration file to use instead of
408 .BR $DISORDER_HOME/passwd .
411 The user's home directory.
413 .B LC_ALL\fR, \fBLANG\fR, etc
419 Global configuration file.
420 See \fBdisorder_config\fR(5).
422 .I ~/.disorder/passwd
423 Per-user password file
425 .I pkgstatedir/socket
426 Communication socket for \fBdisorder\fR(1).
428 \fBdisorderd\fR(8), \fBdisorder_config\fR(5), \fBsyslog\fR(3), \fBtime\fR(2),
429 \fBpcrepattern\fR(3), \fBdisobedience\fR(1), \fBdisorder.cgi\fR(8),
430 \fBdisorder_preferences\fR(5)
432 "\fBpydoc disorder\fR" for the Python API documentation.