X-Git-Url: http://git.tuebingen.mpg.de/?p=paraslash.git;a=blobdiff_plain;f=INSTALL;h=0f4c18b647e0e6c2fc921bbded745275458d70c7;hp=236e66d4bc0972ff1038b9ef0d84683d972a2a94;hb=87c857765884b6d05a2b090fa9509e90d220a2f8;hpb=b80cb259ed18ac71984083af9eee8ae3f65f6e0b diff --git a/INSTALL b/INSTALL index 236e66d4..0f4c18b6 100644 --- a/INSTALL +++ b/INSTALL @@ -1,470 +1,13 @@ -INSTALL -======= - ----- 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) -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. - -------------------------- -Install server and client -------------------------- - -Install the package on all machines, you'd like this software to run on: - - (./configure && make) > /dev/null - -There should be no errors but probably some warnings about missing -software packages which usually implies that not all audio formats will -be supported. If headers or libs are installed at unusual locations -you might need to tell the configure script to find them. Try - - ./configure --help - -to see a list of options. If the paraslash package was compiled -successfully, execute as root, - - make install - ------------------------------------ -Setup user list and create rsa keys ------------------------------------ - -If you already have your rsa keys, skip this step. If you are new -to paraslash, you have to generate an rsa key pair for each user you -want to allow to connect. You need at least one user. - -Let's assume that you'd like to run the server on host server_host -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: - - target=~/.paraslash/server.users - key=~/.paraslash/key.pub.bar - perms=AFS_READ,AFS_WRITE,VSS_READ,VSS_WRITE - mkdir -p ~/.paraslash - echo "user bar $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 - mkdir -p ~/.paraslash - (umask 077 && openssl genrsa -out $key) - -Next, extract its public part: - - pubkey=~/.paraslash/key.pub.bar - openssl rsa -in $key -pubout -out $pubkey - -and copy the public key just created to server_host (you may -skip this step for a single-user setup, i.e. if foo=bar and -server_host=client_host): - - scp $pubkey foo@server_host:.paraslash/ - -Finally, tell para_client to connect to server_host: - - conf=~/.paraslash/client.conf - echo 'hostname server_host' > $conf - ------------------ -Start para_server ------------------ - -For this first try, we'll use a debug level of one to make the -output of para_server more verbose. - - para_server -l 2 - -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 -example) and try - - para_client help - para_client si - -to retrieve the list of available commands and some server info. -Don't proceed if this doesn't work. - -------------------- -Create the database -------------------- - - para_client init - -This creates some empty tables under ~/.paraslash/afs_database. -You normally don't need to look at these tables, but it's good -to know that you can start from scratch with - - rm -rf ~/.paraslash/afs_database - -in case something went wrong. - -Next, you need to fill the audio file table of that database with -contents so that para_server knows about your audio files. Choose an -absolute path to a directory containing some audio files and add them -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. - -Print a list of all audio files found with - - para_client ls - ------------------------- -Start streaming manually ------------------------- - - para play - para stat 2 - -This starts streaming and dumps some information about the current -audio file to stdout. - -You should now be able to receive the stream and listen to it. If -you have mpg123 or xmms handy, execute on client_host - - mpg123 http://server_host:8000/ -or - xmms http://server_host:8000/ - -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 - # (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 - ls -l file.wav # should be much bigger than file.mp3 - para_write -w alsa < file.wav - -If this works, proceed. Otherwise double check what is logged by -para_server and use the --loglevel option of para_recv, para_filter -and para_write to increase verbosity. - -Next, put the pieces together: - - para_recv -r 'http -i server_host' \ - | para_filter -f mp3dec -f wav \ - | para_write -w alsa - ---------------------- -Configure para_audiod ---------------------- - -In order to automatically start the right decoder at the right time -and to offer to the clients some information on the current audio -stream and on paraslash's internal state, you should run the local -audio daemon, para_audiod, on every machine in your network which is -supposed to play the audio stream. Try - - para_audiod -h - -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' - -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" -socket for the clients to connect to. The default path for this -socket is - - /var/paraslash/audiod_socket.$HOSTNAME - -so the /var/paraslash directory should be owned by the user who -runs para_audiod. - -If you want to change the location of the socket, use the -s option -for para_audiod or the config file ~/.paraslash/audiod.conf to change -the default. Note that in this case you'll also have to specify the -same value for para_audioc's -s option. - -If para_server is playing, you should be able to listen to the audio -stream as soon as para_audiod is started. Once it is running, try - - para_audioc stat - -That should dump some information to stdout. Other commands include - - para_audioc off - para_audioc on - para_audioc sb - para_audioc term - para_audioc cycle - --------------- -Start para_gui --------------- - -para_gui reads the output of "para_audioc stat" and displays that -information in a curses window. It also allows you to bind keys to -arbitrary commands. There are several flavours of key-bindings: - - - internal: These are the built-in commands that can not be - changed (help, quit, loglevel, version...). - - external: Shutdown curses before launching the given command. - Useful for starting other ncurses programs from within - para_gui, e.g. aumix or dialog scripts. Or, use the mbox - output format to write a mailbox containing one mail for each - (admissible) file the audio file selector knows about. Then - start mutt from within para_gui to browse your collection! - - display: Launch the command and display its stdout in - para_gui's bottom window. - - 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) +From tarball: -(de Morgan's rule), a mood definition that selects only Punk-Rock -songs is + ./configure && make && sudo make install - deny if not is_set punk - deny if not is_set rock +From git: + ./autogen.sh && sudo make install ---------- -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. +For details see the user manual: -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. + http://paraslash.systemlinux.org/manual.html