README.afs

   1 The audio file selector
   2 =======================
   3
   4 Paraslash comes with a sophisticated audio file selector called afs.
   5 In the installation notes, only the "dummy" mode of afs was used which
   6 gets activated automatically if nothing else was specified. In this
   7 section the various features of afs are described.
   8
   9 ----------
  10 Attributes
  11 ~~~~~~~~~~
  12
  13 An attribute is simply a bit which can be set for each audio
  14 file individually.  Up to 64  different attributes may be
  15 defined. For example, "pop", "rock", "blues", "jazz", "instrumental",
  16 "german_lyrics", "speech", whatever. It's up to you how many attributes
  17 you define and how you call them.
  18
  19 A new attribute "test" is created by
  20
  21         para_client addatt test
  22 and
  23         para_client lsatt
  24
  25 lists all available attributes. You can set the "test" attribute for
  26 an audio file by executing
  27
  28         para_client setatt test+ /path/to/the/audio/file
  29
  30 Similarly, the "test" bit can be removed from a audio file with
  31
  32         para_client setatt test- /path/to/the/audio/file
  33
  34 Instead of a path you can also use a pattern, and the attribute is
  35 applied to all audio files matching that pattern:
  36
  37         para_client setatt test+ '/test/directory/*'
  38
  39 The command
  40
  41         para_client -- ls -lv
  42
  43 gives you a verbose listing of your audio files which contains also
  44 which attributes are set.
  45
  46 In case you wonder why the double-dash in the above command is needed:
  47 It tells para_client to not interpret the options after the dashes. If
  48 you find this annoying, just say
  49
  50         alias para='para_client --'
  51
  52 and be happy. In the remainder part this alias is being used.
  53
  54 Drop the test attribute entirely from the database with
  55
  56         para rmatt test
  57
  58 Read the output of
  59
  60         para help ls
  61         para help setatt
  62
  63 for more information and a complete list of command line options to
  64 these commands.
  65
  66
  67 ----------------------
  68 Abstract mood nonsense
  69 ~~~~~~~~~~~~~~~~~~~~~~
  70
  71 [skip this part if you don't like formal definitions]
  72
  73 A mood consists of a unique name and its *mood definition*, which is a set of
  74 *mood lines* containing expressions in terms of attributes and other data
  75 contained in the database.
  76
  77 A mood defines a subset of audio files called the *admissible audio files*
  78 for that mood. A mood can be *active* which means that para_server
  79 is going to select only files from that subset of admissible files.
  80
  81 So in order to create a mood definition one has to write a set of
  82 mood lines. Mood lines come in three flavours: Accept lines, deny
  83 lines and score lines.
  84
  85 The general syntax of the three types of mood lines is
  86
  87
  88         accept [with score <score>] [if] [not] <mood_method> [options]
  89         deny [with score <score>] [if] [not] <mood_method> [options]
  90         score <score>  [if] [not] <mood_method> [options]
  91
  92
  93 Here <score> is either an integer or the string "random" which assigns
  94 a random score to all matching files. The score value changes the
  95 order in which admissible files are going to be selected, but is of
  96 minor importance for this introduction.
  97
  98 So we concentrate on the first two forms, that is accept and deny
  99 lines. As usual, everything in square brackets is optional, i.e.
 100 accept/deny lines take the following form when ignoring scores:
 101
 102         accept [if] [not] <mood_method> [options]
 103
 104 and analogously for the deny case. The "if" keyword is purely cosmetic
 105 and has no function. The "not" keyword just inverts the result, so
 106 the essence of a mood line is the mood method part and the options
 107 following thereafter.
 108
 109 A *mood method* is realized as a function which takes an audio file
 110 and computes a number from the data contained in the database.
 111 If this number is non-negative, we say the file *matches* the mood
 112 method. The file matches the full mood line if it either
 113
 114         - matches the mood method and the "not" keyword is not given,
 115 or
 116         - does not match the mood method, but the "not" keyword is given.
 117
 118 The set of admissible files for the whole mood is now defined as those
 119 files which match at least one accept mood line, but no deny mood line.
 120 More formally, a file is admissible if and only if
 121
 122         (F ~ AL1 or F ~ AL2...) and not (F ~ DL1 or F ~ DN2 ...)
 123
 124 where F is the file, AL1, AL2... are the accept lines, DL1, DL2... are
 125 the deny lines and "~" means "matches".
 126
 127 The cases where no mood lines of accept/deny type are defined need
 128 special treatment:
 129
 130         - Neither accept nor deny lines: This treats all files as admissible
 131           (in fact, that is the definition of the dummy mood which is activated
 132           automatically if no moods are available).
 133
 134         - Only accept lines: A file is admissible iff it matches at least one
 135           accept line:
 136
 137                 F ~ AL1 or F ~ AL2 or ...
 138
 139         - Only deny lines: A file is admissible iff it matches no deny line:
 140
 141                 not (F ~ DL1 or F ~ DN2 ...)
 142
 143
 144
 145 --------------------
 146 List of mood_methods
 147 ~~~~~~~~~~~~~~~~~~~~
 148
 149         no_attributes_set()
 150
 151 Takes no arguments and matches an audio file if and only if no
 152 attributes are set.
 153
 154         played_rarely()
 155
 156 Takes no arguments and matches all audio files where the number of
 157 times this audio file was selected is below the average.
 158
 159         is_set(attribute_name)
 160
 161 Takes the name of an attribute and matches iff that attribute is set.
 162
 163         name_like(pattern)
 164
 165 Takes a filename pattern and matches iff the path of the audio file
 166 matches the pattern.
 167
 168
 169 ----------
 170 Mood usage
 171 ~~~~~~~~~~
 172
 173 To create a new mood called "my_mood", write its definition into
 174 some temporary file, say "tmpfile", and add it to the mood table
 175 by executing
 176
 177         para addmood my_mood < tmpfile
 178
 179 If the mood definition is really short, you may just pipe it to the
 180 client instead of using temporary files. Like this:
 181
 182         echo "$MOOD_DEFINITION" | para addmood my_mood
 183
 184 There is no need to keep the temporary file since you can always use
 185 the catmood command to get it back:
 186
 187         para catmood my_mood
 188
 189 A mood can be activated by executing
 190
 191         para chmood my_mood
 192
 193 Once active, the list of admissible files is shown by the ls command
 194 if the "-a" switch is given:
 195
 196         para ls -a
 197
 198 -----------------------
 199 Example mood definition
 200 ~~~~~~~~~~~~~~~~~~~~~~~
 201
 202 Suppose you have defined attributes "punk" and "rock" and want to define
 203 a mood containing only Punk-Rock songs. That is, an audio file should be
 204 admissible if and only if both attributes are set. Since
 205
 206         punk and rock
 207
 208 is obviously the same as
 209
 210         not (not punk or not rock)
 211
 212 (de Morgan's rule), a mood definition that selects only Punk-Rock
 213 songs is
 214
 215         deny if not is_set punk
 216         deny if not is_set rock
 217
 218
 219 ---------
 220 Troubles?
 221 ---------
 222 If something went wrong, look at the output. If that does not give
 223 you a clue, use loglevel one (option -l 1 for most commands) to show
 224 debugging info. Almost all paraslash executables have a brief online
 225 help which is displayed by using the -h switch.
 226
 227 Still not working? Mail the author Andre Noll <maan@systemlinux.org>
 228 (english, german, or spanish language). Please provide enough info
 229 such as the version of paraslash you are using and relevant parts of
 230 the logs.