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