X-Git-Url: http://git.tuebingen.mpg.de/?p=paraslash.git;a=blobdiff_plain;f=INSTALL;h=b0bbbadbfdde6ade5b2555365dc87f90ca52d5a1;hp=236e66d4bc0972ff1038b9ef0d84683d972a2a94;hb=de9a70360fcd3b5285d280ad1f229f679d453603;hpb=b80cb259ed18ac71984083af9eee8ae3f65f6e0b;ds=sidebyside diff --git a/INSTALL b/INSTALL index 236e66d4..b0bbbadb 100644 --- a/INSTALL +++ b/INSTALL @@ -7,14 +7,16 @@ Any knowledge of how to work with mouse and icons is not required. --------------------------- Install all needed packages --------------------------- - -See README for a list of required software. You don't need everything -listed there. In particular, mp3, ogg vorbis and aac support is -optional. Autoconf will detect what is installed on your system -and will only try to build those executables that can be built with -your setup. - -Note that no special library (not even the mp3 decodong library libmad) +See +<< + REQUIREMENTS +>> +for a list of required software. You don't need everything listed there. In +particular, mp3, ogg vorbis and aac support are all optional. Autoconf will +detect what is installed on your system and will only try to build those +executables that can be built with your setup. + +Note that no special library (not even the mp3 decoding library libmad) is needed for para_server if you only want to stream mp3 files. Also, it's fine to use para_server on a box without sound card as para_server only sends the audio stream to connected clients. @@ -53,24 +55,25 @@ as user foo, and that you want to connect from client_host as user bar. As foo@server_host, create ~/.paraslash/server.users by typing the following commands: + user=bar target=~/.paraslash/server.users - key=~/.paraslash/key.pub.bar + key=~/.paraslash/key.pub.$user perms=AFS_READ,AFS_WRITE,VSS_READ,VSS_WRITE mkdir -p ~/.paraslash - echo "user bar $key $perms" >> $target + echo "user $user $key $perms" >> $target This gives "bar" the full privileges. Change to the bar account on client_host and generate the key-pair with the commands - key=~/.paraslash/key.bar + key=~/.paraslash/key.$LOGNAME mkdir -p ~/.paraslash (umask 077 && openssl genrsa -out $key) Next, extract its public part: - pubkey=~/.paraslash/key.pub.bar + pubkey=~/.paraslash/key.pub.$LOGNAME openssl rsa -in $key -pubout -out $pubkey and copy the public key just created to server_host (you may @@ -88,10 +91,18 @@ Finally, tell para_client to connect to server_host: Start para_server ----------------- -For this first try, we'll use a debug level of one to make the -output of para_server more verbose. +Before starting the server make sure you have write permissions to +the directory /var/paraslash. + + sudo chown $user /var/paraslash - para_server -l 2 +Alternatively, use the --afs_socket Option to specify a different +location for the afs command socket. + +For this first try, we'll use the info loglevel to make the output +of para_server more verbose. + + para_server -l info Now you can use para_client to connect to the server and issue commands. Open a new shell (as "bar" on "client_host" in the above @@ -125,8 +136,8 @@ to the audio file table: para_client add /my/mp3/dir This might take a while, so it is a good idea to start with a directory -containing not too many audio. Note that the table only contains data -about the audio files found, not the files themselves. +containing not too many audio files. Note that the table only contains +data about the audio files found, not the files themselves. Print a list of all audio files found with @@ -136,8 +147,8 @@ Print a list of all audio files found with Start streaming manually ------------------------ - para play - para stat 2 + para_client play + para_client stat 2 This starts streaming and dumps some information about the current audio file to stdout. @@ -153,7 +164,7 @@ Paraslash comes with its own receiving and playing software, which will be described next. Try the following on client_host (assuming Linux/ALSA and an mp3 stream): - para_recv -l 2 -r 'http -i server_host' > file.mp3 + para_recv -l info -r 'http -i server_host' > file.mp3 # (interrupt with CTRL+C after a few seconds) ls -l file.mp3 # should not be empty para_filter -f mp3dec -f wav < file.mp3 > file.wav @@ -185,7 +196,7 @@ supposed to play the audio stream. Try for help. Usually you have to specify only server_host as the receiver specifier for each supported audio format, like this: - para_audiod -l 2 -r 'mp3:http -i server_host' + para_audiod -l info -r 'mp3:http -i server_host' The preferred way to use para_audiod is to run it once at system start as an unprivileged user. para_audiod needs to create a "well-known" @@ -194,7 +205,7 @@ socket is /var/paraslash/audiod_socket.$HOSTNAME -so the /var/paraslash directory should be owned by the user who +so the /var/paraslash directory should be writable for the user who runs para_audiod. If you want to change the location of the socket, use the -s option @@ -236,235 +247,8 @@ arbitrary commands. There are several flavours of key-bindings: - para: Like display, but start "para_client " instead of "". ---------- -AFS usage ---------- - -Paraslash comes with a sophisticated audio file selector called afs. -In the example above, we only used the "dummy" mode of afs 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 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. +This concludes the installation notes. Next thing you might to have a look +at is how to use paraslash's audio file selector. See +<< + README.afs +>>