chiark - git - mdw - disorder/blob - doc/disorder_preferences.5.in

   1 .\"
   2 .\" Copyright (C) 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 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_preferences 5
  20 .SH NAME
  21 disorder_preferences \- DisOrder global and per-track preferences
  22 .SH "PER-TRACK PREFERENCES"
  23 Currently the following preferences are supported.
  24 Some are expected to be set by users, others updated automatically by plugins.
  25 .TP
  26 .B pick_at_random
  27 If this preference is present and set to "0" then the track will not
  28 be picked for random play.
  29 Otherwise it may be.
  30 .TP
  31 .B played
  32 A decimal integer giving the number times the track was played.
  33 This includes tracks that are scratched or were picked at random.
  34 .TP
  35 .B played_time
  36 The last time the track was played, as a \fBtime_t\fR converted to a
  37 decimal integer.
  38 .TP
  39 .B scratched
  40 The number of times the track has been scratched.
  41 .TP
  42 .B requested
  43 A decimal integer giving the number of times the track was requested.
  44 (Tracks that are removed before being played are not counted.)
  45 .TP
  46 .B tags
  47 Tags that apply to this track, separated by commas.
  48 Tags can contain any printing character except comma.
  49 Leading and trailing spaces are not significant but internal spaces are.
  50 .IP
  51 Using the
  52 .B required\-tags
  53 and
  54 .B prohibited\-tags
  55 global preferences, it is possible to limit the tracks that will be selected at
  56 random.
  57 .TP
  58 .B trackname_\fICONTEXT\fB_\fIPART\fR
  59 These preferences can be used to override the filename parsing rules
  60 to find a track name part.
  61 For backwards compatibility, \fBtrackname_\fIPART\fR will be used
  62 if the full version is not present.
  63 .TP
  64 .B unscratched
  65 The number of times the track has been played to completion without
  66 being scratched.
  67 .TP
  68 .B weight
  69 The weight for this track.  Weights are non-negative integers which determine
  70 the relative likelihood of a track being picked at random (i.e. if track A has
  71 twice the weight of track B then it is twice as likely to be picked at random).
  72 A track with weight 0 will not be picked at random, though \fBpick_at_random\fR
  73 is a more sensible way to configure this.
  74 .IP
  75 The default weight, used if no weight is set or the weight value is invalid, is
  76 90000.  Note that many other factors than track weight affect whether a track
  77 will be played - tracks already in the queue will not be picked at random for
  78 instance.
  79 .IP
  80 The maximum allowed weight is 2147483647.  If you set a larger value it will be
  81 clamped to this value.  Negative weights will be completely ignored and the
  82 default value used instead.
  83 .SH "GLOBAL PREFERENCES"
  84 These are the values set with \fBset\-global\fR.
  85 .TP
  86 .B required\-tags
  87 If this is set an nonempty then randomly played tracks will always have at
  88 least one of the listed tags.
  89 .TP
  90 .B prohibited\-tags
  91 If this is set an nonempty then randomly played tracks will never have any of
  92 the listed tags.
  93 .TP
  94 .B playing
  95 If unset or \fByes\fR then play is enabled.
  96 Otherwise it is disabled.
  97 Use \fBdisable\fR rather than setting it directly.
  98 .TP
  99 .B random\-play
 100 If unset or \fByes\fR then random play is enabled.
 101 Otherwise it is disabled.
 102 Use \fBdisable\fR rather than setting it directly.
 103 .PP
 104 Global preferences starting '_' are read-only (in the sense that you cannot
 105 modify them; the server may modify them as part of its normal operation).
 106 They are:
 107 .TP
 108 .B _dbversion
 109 The database version string.
 110 This is used by DisOrder to detect when it must
 111 modify the database after an upgrade.
 112 .SH "SEE ALSO"
 113 \fBdisorder\fR(1), \fBdisorderd\fR(8), \fBdisorder_config\fR(5)
 114 .\" Local Variables:
 115 .\" mode:nroff
 116 .\" fill-column:79
 117 .\" End: