chiark - git - mdw - disorder/blob - doc/disorder.1.in

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