README.afs

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