chiark / gitweb /
Switch to GPL v3
[disorder] / doc / disorder.1.in
1 .\"
2 .\" Copyright (C) 2004-2008 Richard Kettlewell
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 3 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,
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 .\" 
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/>.
16 .\"
17 .TH disorder 1
18 .SH NAME
19 disorder \- DisOrder jukebox client
20 .SH SYNOPSIS
21 .B disorder
22 .RI [ OPTIONS ]
23 .RB [ \-\- ]
24 .RI [ COMMANDS ...]
25 .SH DESCRIPTION
26 .B disorder
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
30 daemon.
31 .PP
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.
36 .PP
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.
40 .SH OPTIONS
41 .TP
42 .B \-\-config \fIPATH\fR, \fB\-c \fIPATH
43 Set the configuration file.
44 The default is
45 .IR pkgconfdir/config .
46 .TP
47 .B \-\-debug\fR, \fB\-d
48 Enable debugging.
49 .TP
50 .B \-\-help\fR, \fB\-h
51 Display a usage message.
52 .TP
53 .B \-\-version\fR, \fB\-V
54 Display version number.
55 .TP
56 .B \-\-help\-commands\fR, \fB\-H
57 List all known commands.
58 .SH COMMANDS
59 .TP
60 .B adduser \fIUSERNAME PASSWORD\fR [\fIRIGHTS\fR]
61 Create a new user.
62 If \fIRIGHTS\fR is not specified then the \fBdefault_rights\fR
63 setting from the server's configuration file applies.
64 .TP
65 .B authorize \fIUSERNAME\fR [\fIRIGHTS\fR]
66 Create user \fIUSERNAME\fR with a random password.
67 User \fIUSERNAME\fR must be a UNIX login user (not just any old string).
68 If \fIRIGHTS\fR is not specified then the \fBdefault_rights\fR
69 setting from the server's configuration file applies.
70 .IP
71 \fI~USERNAME/.disorder/passwd\fR is created with the password in it, so the new
72 user should be able to log in immediately.
73 .IP
74 If writing the \fIpasswd\fR file fails then the user will already have been
75 created in DisOrder's user database.
76 Use \fBdisorder deluser\fR to remove them before trying again.
77 .TP
78 .B deluser \fIUSERNAME\fR
79 Delete a user.
80 .TP
81 .B dirs \fIDIRECTORY\fR [\fB~\fIREGEXP\fR]
82 List all the directories in \fIDIRECTORY\fR.
83 .IP
84 An optional regexp may be specified, marked with an initial \fB~\fR.
85 Only directories with a basename matching the regexp will be returned.
86 .TP
87 .B disable
88 Disable playing after the current track finishes.
89 .TP
90 .B edituser \fIUSERNAME PROPERTY VALUE
91 Set some property of a user.
92 .TP
93 .B enable
94 (Re-)enable playing.
95 .TP
96 .B files \fIDIRECTORY\fR [\fB~\fIREGEXP\fR]
97 List all the files in \fIDIRECTORY\fR.
98 .IP
99 An optional regexp may be specified, marked with an initial \fB~\fR.
100 Only files with a basename matching the regexp will be returned.
101 .TP
102 .B get \fITRACK\fR \fIKEY\fR
103 Display the preference \fIKEY\fR for \fITRACK\fR.
104 See \fBdisorder_preferences\fR (5).
105 .TP
106 .B get\-global \fIKEY\fR
107 Get a global preference.
108 See \fBdisorder_preferences\fR (5).
109 .TP
110 .B get\-volume
111 Display the current volume settings.
112 .TP
113 .B length \fITRACK\fR
114 Display the length of \fITRACK\fR in seconds.
115 .TP
116 .B log
117 Write event log messages to standard output, until the server is terminated.
118 See \fBdisorder_protocol\fR (5) for details of the output syntax.
119 .TP
120 .B move \fITRACK\fR \fIDELTA\fR
121 Move
122 .I TRACK
123 by
124 .I DELTA
125 within the queue.
126 Positive values move towards the head of the queue, negative
127 values towards the tail.
128 .IP
129 Note that if you specify a negative value then the
130 .B \-\-
131 option separate (before all commands) becomes mandatory, as otherwise the
132 negative value is misinterpreted an an option.
133 .TP
134 .B part \fITRACK\fR \fICONTEXT\fI \fIPART\fR
135 Get a track name part.
136 .IP
137 \fICONTEXT\fR should be either \fBsort\fR or \fBdisplay\fR.
138 \fBpart\fR is the part of the name desired, typically \fBartist\fR,
139 \fBalbum\fR or \fBtitle\fR.
140 .TP
141 .B pause
142 Pause the current track.
143 (Note that not all players support pausing.)
144 .TP
145 .B play \fITRACKS\fR...
146 Add \fITRACKS\fR to the end of the queue.
147 .TP
148 .B playing
149 Report the currently playing track.
150 .TP
151 .B prefs \fITRACK\fR
152 Display all the preferences for \fITRACK\fR.
153 See \fBdisorder_preferences\fR (5).
154 .TP
155 .B queue
156 List the current queue.
157 The first entry in the list is the next track to play.
158 .TP
159 .B random\-disable
160 Disable random play.
161 .TP
162 .B random\-enable
163 Enable random play.
164 .TP
165 .B recent
166 List recently played tracks.
167 The first entry is the oldest track, the last entry is the most
168 recently played one.
169 .TP
170 .B reconfigure
171 Make the daemon reload its configuration file.
172 .TP
173 .B remove \fITRACK\fR
174 Remove a track from the queue.
175 .TP
176 .B rescan
177 Rescan the filesystem for new tracks.
178 There is an automatic daily rescan but if you've just added some tracks
179 and want them to show up immediately, use this command.
180 .TP
181 .B resolve \fITRACK\fR
182 Resolve aliases for \fITRACK\fR and print out the real track name.
183 .TP
184 .B resume
185 Resume the current track after a pause.
186 .TP
187 .B rtp\-address
188 Report the RTP brodcast address used by the server (if any).
189 .TP
190 .B schedule-del \fIEVENT\fR
191 Delete a scheduled event.
192 .TP
193 .B schedule-list
194 List scheduled events.
195 Each line contains the ID, a timestamp, 'N' or 'J' for normal or junk priority,
196 the user, the action and action-specific data.
197 .TP
198 .B schedule-play \fIWHEN PRIORITY TRACK\fI
199 Play \fITRACK\fR at time \fIWHEN\fR.
200 Various time/date formats are supported depending on locale but the following
201 three will always work:
202 .RS
203 .RS
204 .TP
205 .B "YYYY-MM-DD HH:MM:SS"
206 .TP
207 .B "HH:MM:SS"
208 .TP
209 .B "HH:MM"
210 .RE
211 .RE
212 .IP
213 \fIPRIORITY\fR should be \fBjunk\fR or \fBnormal\fR.
214 This determines how the event is handled if it becomes due when the server is
215 down.
216 Junk events are just discarded in this case, while normal events will be
217 executed when the server comes back up, even if this is much later.
218 .TP
219 .B schedule-set-global \fIWHEN PRIORITY NAME VALUE\fI
220 Set global preference \fINAME\fR to \fIVALUE\fR at time \fIWHEN\fR.
221 .TP
222 .B schedule-unset-global \fIWHEN PRIORITY NAME\fI
223 Unset global preference \fINAME\fR at time \fIWHEN\fR.
224 .TP
225 .B scratch
226 Scratch the currently playing track.
227 .TP
228 .B scratch\-id \fIID\fR
229 Scratch the currently playing track, provided it has the given ID.
230 .TP
231 .B search \fITERMS\fR
232 Search for tracks containing all of the listed terms.
233 The terms are separated by spaces and form a single argument,
234 so must be quoted, for example:
235 .IP
236 .B "disorder search 'bowie china'"
237 .IP
238 You can limit the search to tracks with a particular tag, too, using the
239 \fBtag:\fR modifier.
240 For example:
241 .IP
242 .B "disorder search 'love tag:depressing'"
243 .TP
244 .B set \fITRACK\fR \fIKEY\fR \fIVALUE\fR
245 Set the preference \fIKEY\fR for \fITRACK\fR to \fIVALUE\fR.
246 See \fBdisorder_preferences\fR (5).
247 .TP
248 .B set\-global \fIKEY\fR \fIVALUE\fR
249 Set a global preference.
250 See \fBdisorder_preferences\fR (5).
251 .TP
252 .B set\-volume \fBLEFT\fR \fBRIGHT\fR
253 Set the volume.
254 .TP
255 .B setup\-guest \fR[\fB\-\-no\-online\-registration\fR]
256 Create the "guest" user for use by the web interface.
257 This user will have no password and will only have the "read" and
258 "register" rights, the latter allowing new users to automatically
259 register themselves via the web interface.
260 .IP
261 With the option \fB\-\-no-online\-registration\fR, the "register" right is
262 suppressed and users must be manually created by an administrator.
263 .IP
264 If online registration is desired then \fBmail_sender\fR must be set in the
265 configuration file.
266 See \fBdisorder_config\fR(5).
267 .TP
268 .B shutdown
269 Shut down the daemon.
270 .TP
271 .B stats
272 List server statistics.
273 .TP
274 .B tags
275 List known tags.
276 .TP
277 .B unset \fITRACK\fR \fIKEY\fR
278 Unset the preference \fIKEY\fR for \fITRACK\fR.
279 See \fBdisorder_preferences\fR (5).
280 .TP
281 .B unset\-global \fIKEY\fR
282 Unset the global preference \fIKEY\fR.
283 See \fBdisorder_preferences\fR (5).
284 .TP
285 .B userinfo \fIUSERNAME PROPERTY
286 Get some property of a user.
287 .TP
288 .B users
289 List known users.
290 .TP
291 .B version
292 Report the daemon's version number.
293 .PP
294 For
295 .B move
296 and
297 .BR remove ,
298 tracks may be specified by name or by ID.
299 If you use the name and a track appears twice in the queue it is
300 undefined which is affected.
301 .SH NOTES
302 .B disorder
303 is locale-aware.
304 If you do not set the locale correctly then it may not handle non-ASCII
305 data properly.
306 .PP
307 The client determines which user to attempt to authenticate as by examining the
308 current UID.
309 This can be overridden in a per-user configuration file, see
310 \fBdisorder_config\fR(5).
311 .PP
312 See \fBdisorder_protocol\fR(5) for the rights required to run each command.
313 (For instance, \fBshutdown\fR requires the \fBadmin\fR right, which most users
314 would not normally have.)
315 .PP
316 This program is not intended to run in a setuid environment.
317 .PP
318 The regexp syntax used by the \fBfiles\fR and \fBdirs\fR commands use the
319 syntax described in \fBpcrepattern\fR(3).
320 Matching is case-independent.
321 It is strongly recommended that you quote regexps, since they often
322 contain characters treated specially by the shell.
323 For example:
324 .PP
325 .B "disorder dirs /Music ~'^(?!the [^t])t'"
326 .SH TROUBLESHOOTING
327 If you cannot play a track, or it does not appear in the database even after a
328 rescan, check the following things:
329 .TP
330 .B .
331 Are there any error messages in the system log?  The server logs to
332 \fBLOG_DAEMON\fR, which typically ends up in
333 .I /var/log/daemon.log
334 or
335 .IR /var/log/messages ,
336 though this depends on local configuration.
337 .TP
338 .B .
339 Is the track in a known format?  Have a look at
340 .I pkgconfdir/config
341 for the formats recognized by the local installation.
342 The filename matching is case-sensitive.
343 .TP
344 .B .
345 Do permissions on the track allow the server to read it?
346 .TP
347 .B .
348 Do the permissions on the containing directories allow the server to read and
349 execute them?
350 .PP
351 The user the server runs as is determined by the \fBuser\fR directive in the
352 configuration file.
353 The README recommends using \fBjukebox\fR for this purpose but it could
354 be different locally.
355 .SH ENVIRONMENT
356 .TP
357 .B HOME
358 The user's home directory.
359 .TP
360 .B LC_ALL\fR, \fBLANG\fR, etc
361 Current locale.
362 See \fBlocale\fR(7).
363 .SH FILES
364 .TP
365 .I pkgconfdir/config
366 Global configuration file.
367 See \fBdisorder_config\fR(5).
368 .TP
369 .I ~/.disorder/passwd
370 Per-user password file
371 .TP
372 .I pkgstatedir/socket
373 Communication socket for \fBdisorder\fR(1).
374 .SH "SEE ALSO"
375 \fBdisorderd\fR(8), \fBdisorder_config\fR(5), \fBsyslog\fR(3), \fBtime\fR(2),
376 \fBpcrepattern\fR(3), \fBdisobedience\fR(1), \fBdisorder.cgi\fR(8),
377 \fBdisorder_preferences\fR(5)
378 .PP
379 "\fBpydoc disorder\fR" for the Python API documentation.
380 .\" Local Variables:
381 .\" mode:nroff
382 .\" fill-column:79
383 .\" End: