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