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