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