X-Git-Url: http://git.tuebingen.mpg.de/?a=blobdiff_plain;f=README.afs;fp=README.afs;h=e627ca76b9ea7c6d748f38fe633c698e5b100241;hb=e5e8648e4e4bd1edb1823dc932c96a7a271b27a4;hp=0000000000000000000000000000000000000000;hpb=f918ea4a69580a9d99852fcdd410923fcfad7393;p=paraslash.git diff --git a/README.afs b/README.afs new file mode 100644 index 00000000..e627ca76 --- /dev/null +++ b/README.afs @@ -0,0 +1,230 @@ +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 ] [if] [not] [options] + deny [with score ] [if] [not] [options] + score [if] [not] [options] + + +Here 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] [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 +(english, german, or spanish language). Please provide enough info +such as the version of paraslash you are using and relevant parts of +the logs.