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 an audio file with
  35
  36         para_client setatt test- /path/to/the/audio/file
  37
  38 Instead of a path you may use a shell wildcard pattern. The attribute
  39 is 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 what follows we shall use this alias.
  57
  58 The "test" attribute can be dropped 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
  78 a set of *mood lines* containing expressions in terms of attributes
  79 and other data contained in the database.
  80
  81 A mood defines a subset of audio files called the *admissible audio files*
  82 for that mood. At any time, at most one mood can be *active* which
  83 means that para_server is going to select only files from that subset
  84 of admissible files.
  85
  86 So in order to create a mood definition one has to write a set of
  87 mood lines. Mood lines come in three flavours: Accept lines, deny
  88 lines and score lines.
  89
  90 The general syntax of the three types of mood lines is
  91
  92
  93         accept [with score <score>] [if] [not] <mood_method> [options]
  94         deny [with score <score>] [if] [not] <mood_method> [options]
  95         score <score>  [if] [not] <mood_method> [options]
  96
  97
  98 Here <score> is either an integer or the string "random" which assigns
  99 a random score to all matching files. The score value changes the
 100 order in which admissible files are going to be selected, but is of
 101 minor importance for this introduction.
 102
 103 So we concentrate on the first two forms, i.e. accept and deny
 104 lines. As usual, everything in square brackets is optional, i.e.
 105 accept/deny lines take the following form when ignoring scores:
 106
 107         accept [if] [not] <mood_method> [options]
 108
 109 and analogously for the deny case. The "if" keyword is purely cosmetic
 110 and has no function. The "not" keyword just inverts the result, so
 111 the essence of a mood line is the mood method part and the options
 112 following thereafter.
 113
 114 A *mood method* is realized as a function which takes an audio file
 115 and computes a number from the data contained in the database.
 116 If this number is non-negative, we say the file *matches* the mood
 117 method. The file matches the full mood line if it either
 118
 119         - matches the mood method and the "not" keyword is not given,
 120 or
 121         - does not match the mood method, but the "not" keyword is given.
 122
 123 The set of admissible files for the whole mood is now defined as those
 124 files which match at least one accept mood line, but no deny mood line.
 125 More formally, an audio file F is admissible if and only if
 126
 127         (F ~ AL1 or F ~ AL2...) and not (F ~ DL1 or F ~ DN2 ...)
 128
 129 where AL1, AL2... are the accept lines, DL1, DL2... are the deny
 130 lines and "~" means "matches".
 131
 132 The cases where no mood lines of accept/deny type are defined need
 133 special treatment:
 134
 135         - Neither accept nor deny lines: This treats all files as admissible
 136           (in fact, that is the definition of the dummy mood which is activated
 137           automatically if no moods are available).
 138
 139         - Only accept lines: A file is admissible iff it matches at least one
 140           accept line:
 141
 142                 F ~ AL1 or F ~ AL2 or ...
 143
 144         - Only deny lines: A file is admissible iff it matches no deny line:
 145
 146                 not (F ~ DL1 or F ~ DN2 ...)
 147
 148
 149
 150 --------------------
 151 List of mood_methods
 152 ~~~~~~~~~~~~~~~~~~~~
 153
 154         no_attributes_set
 155
 156 Takes no arguments and matches an audio file if and only if no
 157 attributes are set.
 158
 159         is_set <attribute_name>
 160
 161 Takes the name of an attribute and matches iff that attribute is set.
 162
 163         path_matches <pattern>
 164
 165 Takes a filename pattern and matches iff the path of the audio file
 166 matches the pattern.
 167
 168         artist_matches <pattern>
 169         album_matches <pattern>
 170         title_matches <pattern>
 171         comment_matches <pattern>
 172
 173 Takes an extended regular expression and matches iff the text of the
 174 corresponding tag of the audio file matches the pattern. If the tag
 175 is not set, the empty string is matched against the pattern.
 176
 177         year
 178
 179 Takes a comparator ~ of the set {<, =, <=, >, >=, !=} and a number
 180 N. Matches iff the year tag Y of the audio file is a number that
 181 satisfies the condition Y ~ N. If the audio file has no year tag,
 182 or if the tag is not a number, the file does not match.
 183
 184 ----------
 185 Mood usage
 186 ~~~~~~~~~~
 187
 188 To create a new mood called "my_mood", write its definition into
 189 some temporary file, say "tmpfile", and add it to the mood table
 190 by executing
 191
 192         para addmood my_mood < tmpfile
 193
 194 If the mood definition is really short, you may just pipe it to the
 195 client instead of using temporary files. Like this:
 196
 197         echo "$MOOD_DEFINITION" | para addmood my_mood
 198
 199 There is no need to keep the temporary file since you can always use
 200 the catmood command to get it back:
 201
 202         para catmood my_mood
 203
 204 A mood can be activated by executing
 205
 206         para select m/my_mood
 207
 208 Once active, the list of admissible files is shown by the ls command
 209 if the "-a" switch is given:
 210
 211         para ls -a
 212
 213 -----------------------
 214 Example mood definition
 215 ~~~~~~~~~~~~~~~~~~~~~~~
 216
 217 Suppose you have defined attributes "punk" and "rock" and want to define
 218 a mood containing only Punk-Rock songs. That is, an audio file should be
 219 admissible if and only if both attributes are set. Since
 220
 221         punk and rock
 222
 223 is obviously the same as
 224
 225         not (not punk or not rock)
 226
 227 (de Morgan's rule), a mood definition that selects only Punk-Rock
 228 songs is
 229
 230         deny if not is_set punk
 231         deny if not is_set rock
 232
 233
 234 ---------
 235 Troubles?
 236 ---------
 237
 238 Use the debug loglevel (option -l debug for most commands) to show
 239 debugging info. Almost all paraslash executables have a brief online
 240 help which is displayed by using the -h switch. The --detailed-help
 241 option prints the full help text.
 242
 243 para_fsck tries to fix your database. Use --force (even if your name
 244 isn't Luke) to clean up after a crash. However, first make sure
 245 para_server isn't running before executing para_fsck if para_fsck
 246 complains about busy (dirty) tables. para_fsck also contains an option
 247 to dump the contents of the database to the file system.
 248
 249 If you don't mind to recreate your database you can start
 250 from scratch by removing the entire database directory, i.e.
 251
 252         rm -rf ~/.paraslash/afs_database
 253
 254 Note that this removes all tables, in particular attribute definitions
 255 and data, and all playlist and mood definitions.
 256
 257 para_fsck operates on the osl-layer, i.e. it fixes inconsistencies
 258 in the database but doesn't know about the contents of the tables
 259 contained therein. Use
 260
 261         para_client check
 262
 263 to print out bad entries, e.g.missing audio files or invalid mood
 264 definitions.
 265
 266 Still having problems? mailto: Andre Noll <maan@systemlinux.org>