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

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