Use non-blocking API for signal handling.
[paraslash.git] / README.afs
index e5c23a5..5162566 100644 (file)
@@ -1,10 +1,14 @@
 The audio file selector
 =======================
 
-Paraslash comes with a sophisticated audio file selector called afs.
-In the installation notes, only the "dummy" mode of afs was used which
-gets activated automatically if nothing else was specified. In this
-section the various features of afs are described.
+Paraslash comes with a sophisticated audio file selector called *afs*.
+In the
+<<
+<a href="INSTALL.html">installation notes</a>,
+>>
+only the "dummy" mode of afs was used which gets activated automatically if
+nothing else was specified. In this section the various features of afs are
+described.
 
 ----------
 Attributes
@@ -27,12 +31,12 @@ an audio file by executing
 
        para_client setatt test+ /path/to/the/audio/file
 
-Similarly, the "test" bit can be removed from a audio file with
+Similarly, the "test" bit can be removed from an audio file with
 
        para_client setatt test- /path/to/the/audio/file
 
-Instead of a path you can also use a pattern, and the attribute is
-applied to all audio files matching that pattern:
+Instead of a path you may use a shell wildcard pattern. The attribute
+is applied to all audio files matching that pattern:
 
        para_client setatt test+ '/test/directory/*'
 
@@ -49,9 +53,9 @@ you find this annoying, just say
 
        alias para='para_client --'
 
-and be happy. In the remainder part this alias is being used.
+and be happy. In what follows we shall use this alias.
 
-Drop the test attribute entirely from the database with
+The "test" attribute can be dropped from the database with
 
        para rmatt test
 
@@ -70,13 +74,14 @@ Abstract mood nonsense
 
 [skip this part if you don't like formal definitions]
 
-A mood consists of a unique name and its *mood definition*, which is a set of
-*mood lines* containing expressions in terms of attributes and other data
-contained in the database.
+A mood consists of a unique name and its *mood definition*, which is
+a set of *mood lines* containing expressions in terms of attributes
+and other data contained in the database.
 
 A mood defines a subset of audio files called the *admissible audio files*
-for that mood. A mood can be *active* which means that para_server
-is going to select only files from that subset of admissible files.
+for that mood. At any time, at most one mood can be *active* which
+means that para_server is going to select only files from that subset
+of admissible files.
 
 So in order to create a mood definition one has to write a set of
 mood lines. Mood lines come in three flavours: Accept lines, deny
@@ -95,7 +100,7 @@ a random score to all matching files. The score value changes the
 order in which admissible files are going to be selected, but is of
 minor importance for this introduction.
 
-So we concentrate on the first two forms, that is accept and deny
+So we concentrate on the first two forms, i.e. accept and deny
 lines. As usual, everything in square brackets is optional, i.e.
 accept/deny lines take the following form when ignoring scores:
 
@@ -117,12 +122,12 @@ or
 
 The set of admissible files for the whole mood is now defined as those
 files which match at least one accept mood line, but no deny mood line.
-More formally, a file is admissible if and only if
+More formally, an audio file F is admissible if and only if
 
        (F ~ AL1 or F ~ AL2...) and not (F ~ DL1 or F ~ DN2 ...)
 
-where F is the file, AL1, AL2... are the accept lines, DL1, DL2... are
-the deny lines and "~" means "matches".
+where AL1, AL2... are the accept lines, DL1, DL2... are the deny
+lines and "~" means "matches".
 
 The cases where no mood lines of accept/deny type are defined need
 special treatment:
@@ -146,25 +151,48 @@ special treatment:
 List of mood_methods
 ~~~~~~~~~~~~~~~~~~~~
 
-       no_attributes_set()
+       no_attributes_set
 
 Takes no arguments and matches an audio file if and only if no
 attributes are set.
 
-       played_rarely()
-
-Takes no arguments and matches all audio files where the number of
-times this audio file was selected is below the average.
-
-       is_set(attribute_name)
+       is_set <attribute_name>
 
 Takes the name of an attribute and matches iff that attribute is set.
 
-       path_matches(pattern)
+       path_matches <pattern>
 
 Takes a filename pattern and matches iff the path of the audio file
 matches the pattern.
 
+       artist_matches <pattern>
+       album_matches <pattern>
+       title_matches <pattern>
+       comment_matches <pattern>
+
+Takes an extended regular expression and matches iff the text of the
+corresponding tag of the audio file matches the pattern. If the tag
+is not set, the empty string is matched against the pattern.
+
+       year ~ <num>
+       bitrate ~ <num>
+       frequency ~ <num>
+       channels ~ <num>
+       num_played ~ <num>
+
+Takes a comparator ~ of the set {<, =, <=, >, >=, !=} and a number
+<num>. Matches an audio file iff the condition <val> ~ <num> is
+satisfied where val is the corresponding value of the audio file
+(value of the year tag, bitrate in kbit/s, frequency in Hz, channel
+count, play count).
+
+The year tag is special as its value is undefined if the audio file
+has no year tag or the content of the year tag is not a number. Such
+audio files never match. Another difference is the special treatment
+if the year tag is a two-digit number. In this case either 1900 or
+2000 are added to the tag value depending on whether the number is
+greater than 2000 plus the current year.
+
 
 ----------
 Mood usage
@@ -188,7 +216,7 @@ the catmood command to get it back:
 
 A mood can be activated by executing
 
-       para chmood my_mood
+       para select m/my_mood
 
 Once active, the list of admissible files is shown by the ls command
 if the "-a" switch is given:
@@ -219,12 +247,33 @@ songs is
 ---------
 Troubles?
 ---------
-If something went wrong, look at the output. If that does not give
-you a clue, use loglevel one (option -l 1 for most commands) to show
+
+Use the debug loglevel (option -l debug for most commands) to show
 debugging info. Almost all paraslash executables have a brief online
-help which is displayed by using the -h switch.
+help which is displayed by using the -h switch. The --detailed-help
+option prints the full help text.
+
+If para_server crashed or was killed by SIGKILL (signal 9), it
+may refuse to start again because of "dirty osl tables". In this
+case you'll have to run the oslfsck program of libosl to fix your
+database. It might be necessary to use --force (even if your name
+isn't Luke). However, make sure para_server isn't running before
+executing oslfsck --force.
+
+If you don't mind to recreate your database you can start
+from scratch by removing the entire database directory, i.e.
+
+       rm -rf ~/.paraslash/afs_database-0.4
+
+Be aware that this removes all attribute definitions, all playlists
+and all mood definitions.
+
+Although oslfsck fixes inconsistencies in database tables it doesn't
+care about the table contents. To check for invalid table contents, use
+
+       para_client check
+
+This prints out references to missing audio files as well as invalid
+playlists and mood definitions.
 
-Still not working? Mail the author Andre Noll <maan@systemlinux.org>
-(english, german, or spanish language). Please provide enough info
-such as the version of paraslash you are using and relevant parts of
-the logs.
+Still having problems? mailto: Andre Noll <maan@systemlinux.org>