Client doc update

[disorder] / doc / disorder.1.in

.\"
.\" Copyright (C) 2004-2008 Richard Kettlewell
.\"
.\" This program is free software; you can redistribute it and/or modify
.\" it under the terms of the GNU General Public License as published by
.\" the Free Software Foundation; either version 2 of the License, or
.\" (at your option) any later version.
.\"
.\" This program is distributed in the hope that it will be useful, but
.\" WITHOUT ANY WARRANTY; without even the implied warranty of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
.\" General Public License for more details.
.\"
.\" You should have received a copy of the GNU General Public License
.\" along with this program; if not, write to the Free Software
.\" Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
.\" USA
.\"
.TH disorder 1
.SH NAME
disorder \- DisOrder jukebox client
.SH SYNOPSIS
.B disorder
.RI [ OPTIONS ]
.RB [ \-\- ]
.RI [ COMMANDS ...]
.SH DESCRIPTION
.B disorder
is used to query the \fBdisorderd\fR(8) daemon from the command line.
It may be used to request tracks, scratch tracks, query the current
state, etc, and by an administrator to shutdown or reconfigure the
daemon.
.PP
If no commands are specified then \fBdisorder\fR connects to the
daemon and then immediately disconnects.
This can be used to test whether the daemon is running.
Otherwise, it executes the commands specified.
.PP
This man page documents the command-line client.
See \fBdisorderd\fR (8) for information about the server process
and \fBdisorder_config\fR (5) for documentation of the configuration file.
.SH OPTIONS
.TP
.B \-\-config \fIPATH\fR, \fB\-c \fIPATH
Set the configuration file.
The default is
.IR pkgconfdir/config .
.TP
.B \-\-debug\fR, \fB\-d
Enable debugging.
.TP
.B \-\-help\fR, \fB\-h
Display a usage message.
.TP
.B \-\-version\fR, \fB\-V
Display version number.
.TP
.B \-\-help\-commands\fR, \fB\-H
List all known commands.
.SH COMMANDS
.TP
.B adduser \fIUSERNAME PASSWORD\fR [\fIRIGHTS\fR]
Create a new user.
If \fIRIGHTS\fR is not specified then the \fBdefault_rights\fR
setting from the server's configuration file applies.
.TP
.B authorize \fIUSERNAME\fR [\fIRIGHTS\fR]
Create user \fIUSERNAME\fR with a random password.
User \fIUSERNAME\fR must be a UNIX login user (not just any old string).
If \fIRIGHTS\fR is not specified then the \fBdefault_rights\fR
setting from the server's configuration file applies.
.IP
\fI~USERNAME/.disorder/passwd\fR is created with the password in it, so the new
user should be able to log in immediately.
.IP
If writing the \fIpasswd\fR file fails then the user will already have been
created in DisOrder's user database.
Use \fBdisorder deluser\fR to remove them before trying again.
.TP
.B deluser \fIUSERNAME\fR
Delete a user.
.TP
.B dirs \fIDIRECTORY\fR [\fB~\fIREGEXP\fR]
List all the directories in \fIDIRECTORY\fR.
.IP
An optional regexp may be specified, marked with an initial \fB~\fR.
Only directories with a basename matching the regexp will be returned.
.TP
.B disable
Disable playing after the current track finishes.
.TP
.B edituser \fIUSERNAME PROPERTY VALUE
Set some property of a user.
.TP
.B enable
(Re-)enable playing.
.TP
.B files \fIDIRECTORY\fR [\fB~\fIREGEXP\fR]
List all the files in \fIDIRECTORY\fR.
.IP
An optional regexp may be specified, marked with an initial \fB~\fR.
Only files with a basename matching the regexp will be returned.
.TP
.B get \fITRACK\fR \fIKEY\fR
Display the preference \fIKEY\fR for \fITRACK\fR.
See \fBdisorder_preferences\fR (5).
.TP
.B get\-global \fIKEY\fR
Get a global preference.
See \fBdisorder_preferences\fR (5).
.TP
.B get\-volume
Display the current volume settings.
.TP
.B length \fITRACK\fR
Display the length of \fITRACK\fR in seconds.
.TP
.B log
Write event log messages to standard output, until the server is terminated.
See \fBdisorder_protocol\fR (5) for details of the output syntax.
.TP
.B move \fITRACK\fR \fIDELTA\fR
Move
.I TRACK
by
.I DELTA
within the queue.
Positive values move towards the head of the queue, negative
values towards the tail.
.IP
Note that if you specify a negative value then the
.B \-\-
option separate (before all commands) becomes mandatory, as otherwise the
negative value is misinterpreted an an option.
.TP
.B part \fITRACK\fR \fICONTEXT\fI \fIPART\fR
Get a track name part.
.IP
\fICONTEXT\fR should be either \fBsort\fR or \fBdisplay\fR.
\fBpart\fR is the part of the name desired, typically \fBartist\fR,
\fBalbum\fR or \fBtitle\fR.
.TP
.B pause
Pause the current track.
(Note that not all players support pausing.)
.TP
.B play \fITRACKS\fR...
Add \fITRACKS\fR to the end of the queue.
.TP
.B playing
Report the currently playing track.
.TP
.B playlist-del \fIPLAYLIST\fR
Deletes playlist \fIPLAYLIST\fR.
.TP
.B playlist-get \fIPLAYLIST\fR
Gets the contents of playlist \fIPLAYLIST\fR.
.TP
.B playlist-set \fIPLAYLIST\fR [\fIPATH\fR]
Set the contents of playlist \fIPLAYLIST\fR.
If an absolute path name is specified then the track list is read from
that filename.
Otherwise the track list is read from standard input.
In either case, the list is terminated either by end of file or by a line
containing a single ".".
.TP
.B playlists
Lists known playlists (in no particular order).
.TP
.B prefs \fITRACK\fR
Display all the preferences for \fITRACK\fR.
See \fBdisorder_preferences\fR (5).
.TP
.B queue
List the current queue.
The first entry in the list is the next track to play.
.TP
.B random\-disable
Disable random play.
.TP
.B random\-enable
Enable random play.
.TP
.B recent
List recently played tracks.
The first entry is the oldest track, the last entry is the most
recently played one.
.TP
.B reconfigure
Make the daemon reload its configuration file.
.TP
.B remove \fITRACK\fR
Remove a track from the queue.
.TP
.B rescan
Rescan the filesystem for new tracks.
There is an automatic daily rescan but if you've just added some tracks
and want them to show up immediately, use this command.
.TP
.B resolve \fITRACK\fR
Resolve aliases for \fITRACK\fR and print out the real track name.
.TP
.B resume
Resume the current track after a pause.
.TP
.B rtp\-address
Report the RTP brodcast address used by the server (if any).
.TP
.B schedule-del \fIEVENT\fR
Delete a scheduled event.
.TP
.B schedule-list
List scheduled events.
Each line contains the ID, a timestamp, 'N' or 'J' for normal or junk priority,
the user, the action and action-specific data.
.TP
.B schedule-play \fIWHEN PRIORITY TRACK\fI
Play \fITRACK\fR at time \fIWHEN\fR.
Various time/date formats are supported depending on locale but the following
three will always work:
.RS
.RS
.TP
.B "YYYY-MM-DD HH:MM:SS"
.TP
.B "HH:MM:SS"
.TP
.B "HH:MM"
.RE
.RE
.IP
\fIPRIORITY\fR should be \fBjunk\fR or \fBnormal\fR.
This determines how the event is handled if it becomes due when the server is
down.
Junk events are just discarded in this case, while normal events will be
executed when the server comes back up, even if this is much later.
.TP
.B schedule-set-global \fIWHEN PRIORITY NAME VALUE\fI
Set global preference \fINAME\fR to \fIVALUE\fR at time \fIWHEN\fR.
.TP
.B schedule-unset-global \fIWHEN PRIORITY NAME\fI
Unset global preference \fINAME\fR at time \fIWHEN\fR.
.TP
.B scratch
Scratch the currently playing track.
.TP
.B scratch\-id \fIID\fR
Scratch the currently playing track, provided it has the given ID.
.TP
.B search \fITERMS\fR
Search for tracks containing all of the listed terms.
The terms are separated by spaces and form a single argument,
so must be quoted, for example:
.IP
.B "disorder search 'bowie china'"
.IP
You can limit the search to tracks with a particular tag, too, using the
\fBtag:\fR modifier.
For example:
.IP
.B "disorder search 'love tag:depressing'"
.TP
.B set \fITRACK\fR \fIKEY\fR \fIVALUE\fR
Set the preference \fIKEY\fR for \fITRACK\fR to \fIVALUE\fR.
See \fBdisorder_preferences\fR (5).
.TP
.B set\-global \fIKEY\fR \fIVALUE\fR
Set a global preference.
See \fBdisorder_preferences\fR (5).
.TP
.B set\-volume \fBLEFT\fR \fBRIGHT\fR
Set the volume.
.TP
.B setup\-guest \fR[\fB\-\-no\-online\-registration\fR]
Create the "guest" user for use by the web interface.
This user will have no password and will only have the "read" and
"register" rights, the latter allowing new users to automatically
register themselves via the web interface.
.IP
With the option \fB\-\-no-online\-registration\fR, the "register" right is
suppressed and users must be manually created by an administrator.
.IP
If online registration is desired then \fBmail_sender\fR must be set in the
configuration file.
See \fBdisorder_config\fR(5).
.TP
.B shutdown
Shut down the daemon.
.TP
.B stats
List server statistics.
.TP
.B tags
List known tags.
.TP
.B unset \fITRACK\fR \fIKEY\fR
Unset the preference \fIKEY\fR for \fITRACK\fR.
See \fBdisorder_preferences\fR (5).
.TP
.B unset\-global \fIKEY\fR
Unset the global preference \fIKEY\fR.
See \fBdisorder_preferences\fR (5).
.TP
.B userinfo \fIUSERNAME PROPERTY
Get some property of a user.
.TP
.B users
List known users.
.TP
.B version
Report the daemon's version number.
.PP
For
.B move
and
.BR remove ,
tracks may be specified by name or by ID.
If you use the name and a track appears twice in the queue it is
undefined which is affected.
.SH NOTES
.B disorder
is locale-aware.
If you do not set the locale correctly then it may not handle non-ASCII
data properly.
.PP
The client determines which user to attempt to authenticate as by examining the
current UID.
This can be overridden in a per-user configuration file, see
\fBdisorder_config\fR(5).
.PP
See \fBdisorder_protocol\fR(5) for the rights required to run each command.
(For instance, \fBshutdown\fR requires the \fBadmin\fR right, which most users
would not normally have.)
.PP
This program is not intended to run in a setuid environment.
.PP
The regexp syntax used by the \fBfiles\fR and \fBdirs\fR commands use the
syntax described in \fBpcrepattern\fR(3).
Matching is case-independent.
It is strongly recommended that you quote regexps, since they often
contain characters treated specially by the shell.
For example:
.PP
.B "disorder dirs /Music ~'^(?!the [^t])t'"
.SH TROUBLESHOOTING
If you cannot play a track, or it does not appear in the database even after a
rescan, check the following things:
.TP
.B .
Are there any error messages in the system log?  The server logs to
\fBLOG_DAEMON\fR, which typically ends up in
.I /var/log/daemon.log
or
.IR /var/log/messages ,
though this depends on local configuration.
.TP
.B .
Is the track in a known format?  Have a look at
.I pkgconfdir/config
for the formats recognized by the local installation.
The filename matching is case-sensitive.
.TP
.B .
Do permissions on the track allow the server to read it?
.TP
.B .
Do the permissions on the containing directories allow the server to read and
execute them?
.PP
The user the server runs as is determined by the \fBuser\fR directive in the
configuration file.
The README recommends using \fBjukebox\fR for this purpose but it could
be different locally.
.SH ENVIRONMENT
.TP
.B HOME
The user's home directory.
.TP
.B LC_ALL\fR, \fBLANG\fR, etc
Current locale.
See \fBlocale\fR(7).
.SH FILES
.TP
.I pkgconfdir/config
Global configuration file.
See \fBdisorder_config\fR(5).
.TP
.I ~/.disorder/passwd
Per-user password file
.TP
.I pkgstatedir/socket
Communication socket for \fBdisorder\fR(1).
.SH "SEE ALSO"
\fBdisorderd\fR(8), \fBdisorder_config\fR(5), \fBsyslog\fR(3), \fBtime\fR(2),
\fBpcrepattern\fR(3), \fBdisobedience\fR(1), \fBdisorder.cgi\fR(8),
\fBdisorder_preferences\fR(5)
.PP
"\fBpydoc disorder\fR" for the Python API documentation.
.\" Local Variables:
.\" mode:nroff
.\" fill-column:79
.\" End: