chiark / gitweb /
typo in man disorder-playrtp
[disorder] / doc / disorder.1.in
1 .\"
2 .\" Copyright (C) 2004, 2005, 2006 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 2 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, 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.
13 .\"
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
17 .\" USA
18 .\"
19 .TH disorder 1
20 .SH NAME
21 disorder \- DisOrder jukebox client
22 .SH SYNOPSIS
23 .B disorder
24 .RI [ OPTIONS ]
25 .RB [ -- ]
26 .RI [ COMMANDS ...]
27 .br
28 .B disorder
29 .B --length
30 .RI [ OPTIONS ]
31 .RB [ -- ]
32 .IR PATH ...
33 .SH DESCRIPTION
34 Without the \fB--length\fR option,
35 .B disorder
36 is used to query the \fBdisorderd\fR(8) daemon from the command line.
37 It may be used to request tracks, scratch tracks, query the current
38 state, etc, and by an administrator to shutdown or reconfigure the
39 daemon.
40 .PP
41 If no commands are specified then \fBdisorder\fR connects to the
42 daemon and then immediately disconnects.  This can be used to test
43 whether the daemon is running.  Otherwise, it executes the commands
44 specified.
45 .SH OPTIONS
46 .TP
47 .B --config \fIPATH\fR, \fB-c \fIPATH
48 Set the configuration file.  The default is
49 .IR pkgconfdir/config .
50 .TP
51 .B --debug\fR, \fB-d
52 Enable debugging.
53 .TP
54 .B --help\fR, \fB-h
55 Display a usage message.
56 .TP
57 .B --length\fR, \fB-L
58 Calculate the length in seconds of the files specified using the tracklength
59 plugin.
60 .TP
61 .B --version\fR, \fB-V
62 Display version number.
63 .TP
64 .B --help-commands\fR, \fB-H
65 List all known commands.
66 .SH COMMANDS
67 .TP
68 .B dirs \fIDIRECTORY\fR [\fB~\fIREGEXP\fR]
69 List all the directories in \fIDIRECTORY\fR.
70 .IP
71 An optional regexp may be specified, marked with an initial \fB~\fR.  Only
72 directories with a basename matching the regexp will be returned.
73 .TP
74 .B disable
75 Disables playing after the current track finishes.
76 .TP
77 .B enable
78 (Re-)enable playing.
79 .TP
80 .B files \fIDIRECTORY\fR [\fB~\fIREGEXP\fR]
81 List all the files in \fIDIRECTORY\fR.
82 .IP
83 An optional regexp may be specified, marked with an initial \fB~\fR.  Only
84 files with a basename matching the regexp will be returned.
85 .TP
86 .B get \fITRACK\fR \fIKEY\fR
87 Display the preference \fIKEY\fR for \fITRACK\fR.
88 .TP
89 .B get-global \fIKEY\fR
90 Get a global preference.
91 .TP
92 .B get-volume
93 Displays the current volume settings.
94 .TP
95 .B length \fITRACK\fR
96 Reports the length of \fITRACK\fR in seconds.
97 .TP
98 .B log
99 Writes event log messages to standard output, until the server is terminated.
100 See \fBdisorder_protocol\fR (5) for details of the output syntax.
101 .TP
102 .B move \fITRACK\fR \fIDELTA\fR
103 Move
104 .I TRACK
105 by
106 .I DELTA
107 within the queue.  Positive values move towards the head of the queue, negative
108 values towards the tail.
109 .IP
110 Note that if you specify a negative value then the
111 .B --
112 option separate (before all commands) becomes mandatory, as otherwise the
113 negative value is misinterpreted an an option.
114 .TP
115 .B part \fITRACK\fR \fICONTEXT\fI \fIPART\fR
116 Get a track name part.
117 .IP
118 \fICONTEXT\fR should be either \fBsort\fR or \fBdisplay\fR.  \fBpart\fR is the
119 part of the name desired, typically \fBartist\fR, \fBalbum\fR or \fBtitle\fR.
120 .TP
121 .B pause
122 Pause the current track.  (Note that not all players support pausing.)
123 .TP
124 .B play \fITRACKS\fR...
125 Add \fITRACKS\fR to the end of the queue.
126 .TP
127 .B playing
128 Report the currently playing track.
129 .TP
130 .B prefs \fITRACK\fR
131 Display all the preferences for \fITRACK\fR.
132 .TP
133 .B queue
134 List the current queue.  The first entry in the list is the next track to play.
135 .TP
136 .B random-disable
137 Disable random play.
138 .TP
139 .B random-enable
140 Enable random play.
141 .TP
142 .B recent
143 List recently played tracks.  The first entry is the oldest track, the last
144 entry is the most recently played one.
145 .TP
146 .B remove \fITRACK\fR
147 Remove a track from the queue.
148 .TP
149 .B resolve \fITRACK\fR
150 Resolve aliases for \fITRACK\fR and print out the real track name.
151 .TP
152 .B resume
153 Resume the current track after a pause.
154 .TP
155 .B rtp-address
156 Report the RTP brodcast address used by the server (if any).
157 .TP
158 .B scratch
159 Scratch the currently playing track.
160 .TP
161 .B scratch-id \fIID\fR
162 Scratch the currently playing track, provided it has the given ID.
163 .TP
164 .B search \fITERMS\fR
165 Search for tracks containing all of the listed terms.  The terms are
166 separated by spaces and form a single argument, so must be quoted,
167 for example:
168 .IP
169 .B "disorder search 'bowie china'"
170 .IP
171 You can limit the search to tracks with a particular tag, too, using the
172 \fBtag:\fR modifier.  For example:
173 .IP
174 .B "disorder search 'love tag:depressing'"
175 .TP
176 .B set \fITRACK\fR \fIKEY\fR \fIVALUE\fR
177 Set the preference \fIKEY\fR for \fITRACK\fR to \fIVALUE\fR.
178 .TP
179 .B set-global \fIKEY\fR \fIVALUE\fR
180 Set a global preference.
181 .TP
182 .B set-volume \fBLEFT\fR \fBRIGHT\fR
183 Sets the volume.
184 .TP
185 .B stats
186 List server statistics.
187 .TP
188 .B tags
189 List known tags.
190 .TP
191 .B unset \fITRACK\fR \fIKEY\fR
192 Unset the preference \fIKEY\fR for \fITRACK\fR.
193 .TP
194 .B unset-global \fIKEY\fR
195 Unset the global preference \fIKEY\fR.
196 .TP
197 .B version
198 Report the daemon's version number.
199 .PP
200 For
201 .B move
202 and
203 .BR remove ,
204 tracks may be specified by name or by ID.  If you use the name and a track
205 appears twice in the queue it is undefined which is affected.
206 .SS "Privileged Commands"
207 These commands are only available to privileged users.
208 .TP
209 .B become \fIUSER\fR
210 Become another user.
211 .TP
212 .B reconfigure
213 Make the daemon reload its configuration file.
214 .TP
215 .B rescan
216 Rescan the filesystem for new tracks.  There is an automatic daily rescan but
217 if you've just added some tracks and want them to show up immediately, use this
218 command.
219 .TP
220 .B shutdown
221 Shut down the daemon.
222 .SH PREFERENCES
223 Currently the following preferences are supported.  Some are expected
224 to be set by users, others updated automatically by plugins.
225 .TP
226 .B pick_at_random
227 If this preference is present and set to "0" then the track will not
228 be picked for random play.  Otherwise it may be.
229 .TP
230 .B played
231 A decimal integer giving the number times the track was played.  This
232 includes tracks that are scratched or were picked at random.
233 .TP
234 .B played_time
235 The last time the track was played, as a \fBtime_t\fR converted to a
236 decimal integer.
237 .TP
238 .B scratched
239 The number of times the track has been scratched.
240 .TP
241 .B requested
242 A decimal integer giving the number of times the track was requested.
243 (Tracks that are removed before being played are not counted.)
244 .TP
245 .B tags
246 Tags that apply to this track, separated by commas.  Tags can contain any
247 printing character except comma.  Leading and trailing spaces are not
248 significant but internal spaces are.
249 .IP
250 Using the
251 .B required-tags
252 and
253 .B prohibited-tags
254 global preferences, it is possible to limit the tracks that will be selected at
255 random.
256 .TP
257 .B trackname_\fICONTEXT\fB_\fIPART\fR
258 These preferences can be used to override the filename parsing rules
259 to find a track name part.  For backwards compatibility,
260 \fBtrackname_\fIPART\fR will be used if the full version
261 is not present.
262 .TP
263 .B unscratched
264 The number of times the track has been played to completion without
265 being scratched.
266 .SH "Superuser Commands"
267 These commands will (generally) only work for root, who must be a privileged
268 user.
269 .TP
270 .B authorize \fIUSER\fR
271 Chooses a password for \fIUSER\fR and adds it to \fIconfig.private\fR.  Also
272 creates an appropriate \fIconfig.USER\fR, be owned by the user.
273 .IP
274 If at least one \fBauthorize\fR command succeeds then the server is
275 automatically told to re-read its configuration.
276 .SH NOTES
277 .B disorder
278 is locale-aware.  If you do not set the locale correctly then it may
279 not handle non-ASCII data properly.
280 .PP
281 The client determines which user to attempt to authenticate as by
282 examining the current UID.
283 .PP
284 This program is not intended to run in a setuid environment.
285 .PP
286 The regexp syntax used by the \fBfiles\fR and \fBdirs\fR commands use the
287 syntax described in \fBpcrepattern\fR(3).  Matching is case-independent.  It is
288 strongly recommended that you quote regexps, since they often contain
289 characters treated specially by the shell.  For example:
290 .PP
291 .B "disorder dirs /Music ~'^(?!the [^t])t'"
292 .SH TROUBLESHOOTING
293 If you cannot play a track, or it does not appear in the database even after a
294 rescan, check the following things:
295 .TP
296 .B .
297 Are there any error messages in the system log?  The server logs to
298 \fBLOG_DAEMON\fR, which typically ends up in
299 .I /var/log/daemon.log
300 or
301 .IR /var/log/messages ,
302 though this depends on local configuration.
303 .TP
304 .B .
305 Is the track in a known format?  Have a look at
306 .I pkgconfdir/config
307 for the formats recognized by the local installation.  The filename matching is
308 case-sensitive.
309 .TP
310 .B .
311 Do permissions on the track allow the server to read it?
312 .TP
313 .B .
314 Do the permissions on the containing directories allow the server to read and
315 execute them?
316 .PP
317 The user the server runs as is determined by the \fBuser\fR directive in the
318 configuration file.  The README recommends using \fBjukebox\fR for this purpose
319 but it could be different locally.
320 .SH ENVIRONMENT
321 .TP
322 .B LOGNAME
323 The default username.
324 .TP
325 .B HOME
326 The user's home directory.
327 .TP
328 .B LC_ALL\fR, \fBLANG\fR, etc
329 Current locale.  See \fBlocale\fR(7).
330 .SH FILES
331 .TP
332 .I pkgconfdir/config
333 Global configuration file.  See \fBdisorder_config\fR(5).
334 .TP
335 .I ~/.disorder/passwd
336 Per-user password file
337 .TP
338 .I pkgstatedir/socket
339 Communication socket for \fBdisorder\fR(1).
340 .SH "SEE ALSO"
341 \fBdisorderd\fR(8), \fBdisorder_config\fR(5), \fBsyslog\fR(3), \fBtime\fR(2),
342 \fBpcrepattern\fR(3), \fBdisobedience\fR(1)
343 .PP
344 "\fBpydoc disorder\fR" for the Python API documentation.
345 .\" Local Variables:
346 .\" mode:nroff
347 .\" fill-column:79
348 .\" End: