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