1 The audio file selector
2 =======================
4 Paraslash comes with a sophisticated audio file selector called *afs*.
7 <a href="INSTALL.html">installation notes</a>,
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
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.
23 A new attribute "test" is created by
25 para_client addatt test
29 lists all available attributes. You can set the "test" attribute for
30 an audio file by executing
32 para_client setatt test+ /path/to/the/audio/file
34 Similarly, the "test" bit can be removed from an audio file with
36 para_client setatt test- /path/to/the/audio/file
38 Instead of a path you may use a shell wildcard pattern. The attribute
39 is applied to all audio files matching that pattern:
41 para_client setatt test+ '/test/directory/*'
47 gives you a verbose listing of your audio files which contains also
48 which attributes are set.
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
54 alias para='para_client --'
56 and be happy. In what follows we shall use this alias.
58 The "test" attribute can be dropped from the database with
67 for more information and a complete list of command line options to
71 ----------------------
72 Abstract mood nonsense
73 ~~~~~~~~~~~~~~~~~~~~~~
75 [skip this part if you don't like formal definitions]
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.
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
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.
90 The general syntax of the three types of mood lines is
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]
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.
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:
107 accept [if] [not] <mood_method> [options]
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.
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
119 - matches the mood method and the "not" keyword is not given,
121 - does not match the mood method, but the "not" keyword is given.
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
127 (F ~ AL1 or F ~ AL2...) and not (F ~ DL1 or F ~ DN2 ...)
129 where AL1, AL2... are the accept lines, DL1, DL2... are the deny
130 lines and "~" means "matches".
132 The cases where no mood lines of accept/deny type are defined need
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).
139 - Only accept lines: A file is admissible iff it matches at least one
142 F ~ AL1 or F ~ AL2 or ...
144 - Only deny lines: A file is admissible iff it matches no deny line:
146 not (F ~ DL1 or F ~ DN2 ...)
156 Takes no arguments and matches an audio file if and only if no
159 is_set <attribute_name>
161 Takes the name of an attribute and matches iff that attribute is set.
163 path_matches <pattern>
165 Takes a filename pattern and matches iff the path of the audio file
168 artist_matches <pattern>
169 album_matches <pattern>
170 title_matches <pattern>
171 comment_matches <pattern>
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.
182 Takes a comparator ~ of the set {<, =, <=, >, >=, !=} and a number
183 <num>. Matches an audio file iff the condition <val> ~ <num> is
184 satisfied where val is the corresponding value of the audio file
185 (bitrate in kbit/s, frequency in Hz, channel count, value of the
188 The year tag is special as its value is undefined if the audio file
189 has no year tag or the content of the year tag is not a number. Such
190 audio files never match. Another difference is the special treatment
191 if the year tag is a two-digit number. In this case either 1900 or
192 2000 are added to the tag value, depending on whether the number is
193 greater than 2000 plus the current year.
200 To create a new mood called "my_mood", write its definition into
201 some temporary file, say "tmpfile", and add it to the mood table
204 para addmood my_mood < tmpfile
206 If the mood definition is really short, you may just pipe it to the
207 client instead of using temporary files. Like this:
209 echo "$MOOD_DEFINITION" | para addmood my_mood
211 There is no need to keep the temporary file since you can always use
212 the catmood command to get it back:
216 A mood can be activated by executing
218 para select m/my_mood
220 Once active, the list of admissible files is shown by the ls command
221 if the "-a" switch is given:
225 -----------------------
226 Example mood definition
227 ~~~~~~~~~~~~~~~~~~~~~~~
229 Suppose you have defined attributes "punk" and "rock" and want to define
230 a mood containing only Punk-Rock songs. That is, an audio file should be
231 admissible if and only if both attributes are set. Since
235 is obviously the same as
237 not (not punk or not rock)
239 (de Morgan's rule), a mood definition that selects only Punk-Rock
242 deny if not is_set punk
243 deny if not is_set rock
250 Use the debug loglevel (option -l debug for most commands) to show
251 debugging info. Almost all paraslash executables have a brief online
252 help which is displayed by using the -h switch. The --detailed-help
253 option prints the full help text.
255 para_fsck tries to fix your database. Use --force (even if your name
256 isn't Luke) to clean up after a crash. However, first make sure
257 para_server isn't running before executing para_fsck if para_fsck
258 complains about busy (dirty) tables. para_fsck also contains an option
259 to dump the contents of the database to the file system.
261 If you don't mind to recreate your database you can start
262 from scratch by removing the entire database directory, i.e.
264 rm -rf ~/.paraslash/afs_database
266 Note that this removes all tables, in particular attribute definitions
267 and data, and all playlist and mood definitions.
269 para_fsck operates on the osl-layer, i.e. it fixes inconsistencies
270 in the database but doesn't know about the contents of the tables
271 contained therein. Use
275 to print out bad entries, e.g.missing audio files or invalid mood
278 Still having problems? mailto: Andre Noll <maan@systemlinux.org>