--- /dev/null
+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.
+
+----------
+Attributes
+~~~~~~~~~~
+
+An attribute is simply a bit which can be set for each audio
+file individually. Up to 64 different attributes may be
+defined. For example, "pop", "rock", "blues", "jazz", "instrumental",
+"german_lyrics", "speech", whatever. It's up to you how many attributes
+you define and how you call them.
+
+A new attribute "test" is created by
+
+ para_client addatt test
+and
+ para_client lsatt
+
+lists all available attributes. You can set the "test" attribute for
+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
+
+ 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:
+
+ para_client setatt test+ '/test/directory/*'
+
+The command
+
+ para_client -- ls -lv
+
+gives you a verbose listing of your audio files which contains also
+which attributes are set.
+
+In case you wonder why the double-dash in the above command is needed:
+It tells para_client to not interpret the options after the dashes. If
+you find this annoying, just say
+
+ alias para='para_client --'
+
+and be happy. In the remainder part this alias is being used.
+
+Drop the test attribute entirely from the database with
+
+ para rmatt test
+
+Read the output of
+
+ para help ls
+ para help setatt
+
+for more information and a complete list of command line options to
+these commands.
+
+
+----------------------
+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 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.
+
+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
+lines and score lines.
+
+The general syntax of the three types of mood lines is
+
+
+ accept [with score <score>] [if] [not] <mood_method> [options]
+ deny [with score <score>] [if] [not] <mood_method> [options]
+ score <score> [if] [not] <mood_method> [options]
+
+
+Here <score> is either an integer or the string "random" which assigns
+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
+lines. As usual, everything in square brackets is optional, i.e.
+accept/deny lines take the following form when ignoring scores:
+
+ accept [if] [not] <mood_method> [options]
+
+and analogously for the deny case. The "if" keyword is purely cosmetic
+and has no function. The "not" keyword just inverts the result, so
+the essence of a mood line is the mood method part and the options
+following thereafter.
+
+A *mood method* is realized as a function which takes an audio file
+and computes a number from the data contained in the database.
+If this number is non-negative, we say the file *matches* the mood
+method. The file matches the full mood line if it either
+
+ - matches the mood method and the "not" keyword is not given,
+or
+ - does not match the mood method, but the "not" keyword is given.
+
+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
+
+ (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".
+
+The cases where no mood lines of accept/deny type are defined need
+special treatment:
+
+ - Neither accept nor deny lines: This treats all files as admissible
+ (in fact, that is the definition of the dummy mood which is activated
+ automatically if no moods are available).
+
+ - Only accept lines: A file is admissible iff it matches at least one
+ accept line:
+
+ F ~ AL1 or F ~ AL2 or ...
+
+ - Only deny lines: A file is admissible iff it matches no deny line:
+
+ not (F ~ DL1 or F ~ DN2 ...)
+
+
+
+--------------------
+List of mood_methods
+~~~~~~~~~~~~~~~~~~~~
+
+ 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)
+
+Takes the name of an attribute and matches iff that attribute is set.
+
+ name_like(pattern)
+
+Takes a filename pattern and matches iff the path of the audio file
+matches the pattern.
+
+
+----------
+Mood usage
+~~~~~~~~~~
+
+To create a new mood called "my_mood", write its definition into
+some temporary file, say "tmpfile", and add it to the mood table
+by executing
+
+ para addmood my_mood < tmpfile
+
+If the mood definition is really short, you may just pipe it to the
+client instead of using temporary files. Like this:
+
+ echo "$MOOD_DEFINITION" | para addmood my_mood
+
+There is no need to keep the temporary file since you can always use
+the catmood command to get it back:
+
+ para catmood my_mood
+
+A mood can be activated by executing
+
+ para chmood my_mood
+
+Once active, the list of admissible files is shown by the ls command
+if the "-a" switch is given:
+
+ para ls -a
+
+-----------------------
+Example mood definition
+~~~~~~~~~~~~~~~~~~~~~~~
+
+Suppose you have defined attributes "punk" and "rock" and want to define
+a mood containing only Punk-Rock songs. That is, an audio file should be
+admissible if and only if both attributes are set. Since
+
+ punk and rock
+
+is obviously the same as
+
+ not (not punk or not rock)
+
+(de Morgan's rule), a mood definition that selects only Punk-Rock
+songs is
+
+ deny if not is_set punk
+ deny if not is_set rock
+
+
+---------
+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
+debugging info. Almost all paraslash executables have a brief online
+help which is displayed by using the -h switch.
+
+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.
projects / paraslash.git / blobdiff