2 .\" Copyright (C) 2004, 2005, 2006, 2007 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 2 of the License, or
7 .\" (at your option) any later version.
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.
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
21 disorder \- DisOrder jukebox client
29 is used to query the \fBdisorderd\fR(8) daemon from the command line.
30 It may be used to request tracks, scratch tracks, query the current
31 state, etc, and by an administrator to shutdown or reconfigure the
34 If no commands are specified then \fBdisorder\fR connects to the
35 daemon and then immediately disconnects. This can be used to test
36 whether the daemon is running. Otherwise, it executes the commands
40 .B --config \fIPATH\fR, \fB-c \fIPATH
41 Set the configuration file. The default is
42 .IR pkgconfdir/config .
48 Display a usage message.
50 .B --version\fR, \fB-V
51 Display version number.
53 .B --help-commands\fR, \fB-H
54 List all known commands.
57 .B adduser \fIUSER PASSWORD\fR [\fIRIGHTS\fR]
58 Create a new user. If \fIRIGHTS\fR is not specified then the
59 \fBdefault_rights\fR setting from the server's configuration file applies.
61 .B authorize \fIUSER\fR [\fIRIGHTS\fR]
62 Create \fIUSER\fR with a random password. \fIUSER\fR must be a UNIX login
63 user (not just any old string). If \fIRIGHTS\fR is not specified then the
64 \fBdefault_rights\fR setting from the server's configuration file applies.
66 An appropriate \fIconfig.USER\fR is created, owned by the user, so they should
67 be able to log in immediately.
72 .B dirs \fIDIRECTORY\fR [\fB~\fIREGEXP\fR]
73 List all the directories in \fIDIRECTORY\fR.
75 An optional regexp may be specified, marked with an initial \fB~\fR. Only
76 directories with a basename matching the regexp will be returned.
79 Disable playing after the current track finishes.
81 .B edituser \fIUSER PROPERTY VALUE
82 Set some property of a user.
87 .B files \fIDIRECTORY\fR [\fB~\fIREGEXP\fR]
88 List all the files in \fIDIRECTORY\fR.
90 An optional regexp may be specified, marked with an initial \fB~\fR. Only
91 files with a basename matching the regexp will be returned.
93 .B get \fITRACK\fR \fIKEY\fR
94 Display the preference \fIKEY\fR for \fITRACK\fR.
96 .B get-global \fIKEY\fR
97 Get a global preference.
100 Display the current volume settings.
102 .B length \fITRACK\fR
103 Display the length of \fITRACK\fR in seconds.
106 Write event log messages to standard output, until the server is terminated.
107 See \fBdisorder_protocol\fR (5) for details of the output syntax.
109 .B move \fITRACK\fR \fIDELTA\fR
114 within the queue. Positive values move towards the head of the queue, negative
115 values towards the tail.
117 Note that if you specify a negative value then the
119 option separate (before all commands) becomes mandatory, as otherwise the
120 negative value is misinterpreted an an option.
122 .B part \fITRACK\fR \fICONTEXT\fI \fIPART\fR
123 Get a track name part.
125 \fICONTEXT\fR should be either \fBsort\fR or \fBdisplay\fR. \fBpart\fR is the
126 part of the name desired, typically \fBartist\fR, \fBalbum\fR or \fBtitle\fR.
129 Pause the current track. (Note that not all players support pausing.)
131 .B play \fITRACKS\fR...
132 Add \fITRACKS\fR to the end of the queue.
135 Report the currently playing track.
138 Display all the preferences for \fITRACK\fR.
141 List the current queue. The first entry in the list is the next track to play.
150 List recently played tracks. The first entry is the oldest track, the last
151 entry is the most recently played one.
154 Make the daemon reload its configuration file.
156 .B remove \fITRACK\fR
157 Remove a track from the queue.
160 Rescan the filesystem for new tracks. There is an automatic daily rescan but
161 if you've just added some tracks and want them to show up immediately, use this
164 .B resolve \fITRACK\fR
165 Resolve aliases for \fITRACK\fR and print out the real track name.
168 Resume the current track after a pause.
171 Report the RTP brodcast address used by the server (if any).
174 Scratch the currently playing track.
176 .B scratch-id \fIID\fR
177 Scratch the currently playing track, provided it has the given ID.
179 .B search \fITERMS\fR
180 Search for tracks containing all of the listed terms. The terms are
181 separated by spaces and form a single argument, so must be quoted,
184 .B "disorder search 'bowie china'"
186 You can limit the search to tracks with a particular tag, too, using the
187 \fBtag:\fR modifier. For example:
189 .B "disorder search 'love tag:depressing'"
191 .B set \fITRACK\fR \fIKEY\fR \fIVALUE\fR
192 Set the preference \fIKEY\fR for \fITRACK\fR to \fIVALUE\fR.
194 .B set-global \fIKEY\fR \fIVALUE\fR
195 Set a global preference.
197 .B set-volume \fBLEFT\fR \fBRIGHT\fR
200 .B setup-guest \fR[\fB--no-online-registration\fR]
201 Create the "guest" user for use by the web interface. This user will have no
202 password and will only have the "read" and "register" rights, the latter
203 allowing new users to automatically register themselves via the web interface.
205 With the option \fB--no-online-registration\fR, the "register" right is
206 suppressed and users must be manually created by an administrator.
208 If online registration is desired then \fBmail_sender\fR must be set in the
209 configuration file. See \fBdisorder_config\fR(5).
212 Shut down the daemon.
215 List server statistics.
220 .B unset \fITRACK\fR \fIKEY\fR
221 Unset the preference \fIKEY\fR for \fITRACK\fR.
223 .B unset-global \fIKEY\fR
224 Unset the global preference \fIKEY\fR.
226 .B userinfo \fIUSER PROPERTY
227 Get some property of a user.
233 Report the daemon's version number.
239 tracks may be specified by name or by ID. If you use the name and a track
240 appears twice in the queue it is undefined which is affected.
242 Currently the following preferences are supported. Some are expected
243 to be set by users, others updated automatically by plugins.
246 If this preference is present and set to "0" then the track will not
247 be picked for random play. Otherwise it may be.
250 A decimal integer giving the number times the track was played. This
251 includes tracks that are scratched or were picked at random.
254 The last time the track was played, as a \fBtime_t\fR converted to a
258 The number of times the track has been scratched.
261 A decimal integer giving the number of times the track was requested.
262 (Tracks that are removed before being played are not counted.)
265 Tags that apply to this track, separated by commas. Tags can contain any
266 printing character except comma. Leading and trailing spaces are not
267 significant but internal spaces are.
273 global preferences, it is possible to limit the tracks that will be selected at
276 .B trackname_\fICONTEXT\fB_\fIPART\fR
277 These preferences can be used to override the filename parsing rules
278 to find a track name part. For backwards compatibility,
279 \fBtrackname_\fIPART\fR will be used if the full version
283 The number of times the track has been played to completion without
287 is locale-aware. If you do not set the locale correctly then it may
288 not handle non-ASCII data properly.
290 The client determines which user to attempt to authenticate as by examining the
291 current UID. This can be overridden in a per-user configuration file, see
292 \fBdisorder_config\fR(5).
294 See \fBdisorder_protocol\fR(5) for the rights required to run each command.
295 (For instance, \fBshutdown\fR requires the \fBadmin\fR right, which most users
296 would not normally have.)
298 This program is not intended to run in a setuid environment.
300 The regexp syntax used by the \fBfiles\fR and \fBdirs\fR commands use the
301 syntax described in \fBpcrepattern\fR(3). Matching is case-independent. It is
302 strongly recommended that you quote regexps, since they often contain
303 characters treated specially by the shell. For example:
305 .B "disorder dirs /Music ~'^(?!the [^t])t'"
307 If you cannot play a track, or it does not appear in the database even after a
308 rescan, check the following things:
311 Are there any error messages in the system log? The server logs to
312 \fBLOG_DAEMON\fR, which typically ends up in
313 .I /var/log/daemon.log
315 .IR /var/log/messages ,
316 though this depends on local configuration.
319 Is the track in a known format? Have a look at
321 for the formats recognized by the local installation. The filename matching is
325 Do permissions on the track allow the server to read it?
328 Do the permissions on the containing directories allow the server to read and
331 The user the server runs as is determined by the \fBuser\fR directive in the
332 configuration file. The README recommends using \fBjukebox\fR for this purpose
333 but it could be different locally.
337 The default username.
340 The user's home directory.
342 .B LC_ALL\fR, \fBLANG\fR, etc
343 Current locale. See \fBlocale\fR(7).
347 Global configuration file. See \fBdisorder_config\fR(5).
349 .I ~/.disorder/passwd
350 Per-user password file
352 .I pkgstatedir/socket
353 Communication socket for \fBdisorder\fR(1).
355 \fBdisorderd\fR(8), \fBdisorder_config\fR(5), \fBsyslog\fR(3), \fBtime\fR(2),
356 \fBpcrepattern\fR(3), \fBdisobedience\fR(1)
358 "\fBpydoc disorder\fR" for the Python API documentation.
~mdw / disorder / blob