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