X-Git-Url: http://git.tuebingen.mpg.de/?a=blobdiff_plain;f=web%2Fmanual.m4;h=0a5f580a79d4fbe603aa87c90c959e90b4d089ce;hb=1c12b35b710ff503d3ccfb969f65a63ecc5652f0;hp=20cae69ab7e00d6d50b8f5026ab5c42d8e39c33b;hpb=62a2e10a42e4f9b6556ba7e58f70f52ffa3dfa99;p=paraslash.git diff --git a/web/manual.m4 b/web/manual.m4 index 20cae69a..0a5f580a 100644 --- a/web/manual.m4 +++ b/web/manual.m4 @@ -209,11 +209,12 @@ For the impatient: sudo apt-get install autoconf libssl-dev help2man gengetopt \ libmad0-dev libid3tag0-dev libasound2-dev libvorbis-dev \ libfaad-dev libspeex-dev libFLAC-dev libsamplerate-dev \ - libasound2-dev libao-dev libreadline-dev libncurses-dev + libasound2-dev libao-dev libreadline-dev libncurses-dev \ + libopus-dev Detailed description: In any case you'll need - - XREFERENCE(http://systemlinux.org/~maan/osl/, libosl). + - XREFERENCE(http://people.tuebingen.mpg.de/maan/osl/, libosl). The _object storage layer_ library is used by para_server. To clone the source code repository, execute @@ -297,35 +298,14 @@ Optional: Installation ~~~~~~~~~~~~ +To build the sources from a tarball, execute -First make sure all non-optional packages listed in the section on -REFERENCE(Requirements, required software) are installed on your -system. + ./configure && make -You don't need everything listed there. In particular, MP3, OGG/Vorbis, -OGG/Speex and AAC support are all optional. The configure script 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 decoder library (not even the MP3 decoding library -libmad) is needed for para_server if you only want to stream MP3 or WMA -files. Also, it's fine to use para_server on a box without sound card. - -Next, install the paraslash package on all machines, you'd like this -software to run on. If you compile from a released tarball, execute - - (./configure && make) > /dev/null - -When compiling from git or from snapshots downloaded via gitweb, -the above command will not work because the configure script is not -included in the git repository. In this case the following command -should be used instead: +To build from git or a gitweb snapshot, run this command instead: ./autogen.sh -This runs autoconf to generate the configure script, then runs it as -above. Therefore you'll need autoconf for this to work. - There should be no errors but probably some warnings about missing packages which usually implies that not all audio formats will be supported. If headers or libs are installed at unusual locations you @@ -373,18 +353,11 @@ following commands: Next, change to the "bar" account on client_host and generate the key pair with the commands - ssh-keygen -t rsa -b 2048 - # hit enter twice to create a key with no passphrase + ssh-keygen -q -t rsa -b 2048 -N '' -f $key -This generates the two files id_rsa and id_rsa.pub in ~/.ssh. Note -that paraslash can also read keys generated by the "openssl genrsa" -command. However, since keys created with ssh-keygen can also be used -for ssh, this method is recommended. - -Note that para_server refuses to use a key if it is shorter than 2048 -bits. In particular, the RSA keys of paraslash 0.3.x will not work -with version 0.4.x. Moreover, para_client refuses to use a (private) -key which is world-readable. +This generates the two files id_rsa and id_rsa.pub in ~/.ssh. Note +that para_server won't accept keys shorter than 2048 bits. Moreover, +para_client rejects private keys which are world-readable. para_server only needs to know the public key of the key pair just created. Copy this public key to server_host: @@ -667,7 +640,7 @@ known audio files to those which satisfy certain criteria. It also maintains tables containing images (e.g. album cover art) and lyrics that can be associated with one or more audio files. -AFS uses XREFERENCE(http://systemlinux.org/~maan/osl/, libosl), the +AFS uses XREFERENCE(http://people.tuebingen.mpg.de/maan/osl/, libosl), the object storage layer library, as the backend library for storing information on audio files, playlists, etc. This library offers functionality similar to a relational database, but is much more @@ -1080,17 +1053,18 @@ It is possible to change the behaviour of the add command by using the Troubleshooting ~~~~~~~~~~~~~~~ -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. The --detailed-help -option prints the full help text. +Use the debug loglevel (-l debug) to show debugging info. All paraslash +executables have a brief online help which is displayed when -h is +given. 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. +database: + + oslfsck -fd ~/.paraslash/afs_database-0.4 + +However, make sure para_server isn't running before executing oslfsck. If you don't mind to recreate your database you can start from scratch by removing the entire database directory, i.e. @@ -1108,6 +1082,14 @@ care about the table contents. To check for invalid table contents, use This prints out references to missing audio files as well as invalid playlists and mood definitions. +Similarly, para_audiod refuses to start if its socket file exists, since +this indicates that another instance of para_audiod is running. After +a crash a stale socket file might remain and you must run + + para_audiod --force + +once to fix it up. + --------------------------------------- Audio formats and audio format handlers --------------------------------------- @@ -1144,7 +1126,17 @@ Excited Linear Prediction) coding. It is designed for voice over IP applications, has modest complexity and a small memory footprint. Wideband and narrowband (telephone quality) speech are supported. As for Vorbis audio, Speex bit-streams are often stored -in OGG files. +in OGG files. As of 2012 this codec is considered obsolete since the +Oppus codec, described below, surpasses its performance in all areas. + +*OGG/Opus* + +Opus is a lossy audio compression format standardized through RFC +6716 in 2012. It combines the speech-oriented SILK codec and the +low-latency CELT (Constrained Energy Lapped Transform) codec. Like +OGG/Vorbis and OGG/Speex, Opus data is usually encapsulated in OGG +containers. All known software patents which cover Opus are licensed +under royalty-free terms. *AAC* @@ -1168,7 +1160,7 @@ is composed of superframes, each containing one or more frames of The Free Lossless Audio Codec (FLAC) compresses audio without quality loss. It gives better compression ratios than a general purpose compressor like zip or bzip2 because FLAC is designed specifically -for audio. A FLAC-encoded file consits of frames of varying size, up +for audio. A FLAC-encoded file consists of frames of varying size, up to 16K. Each frame starts with a header that contains all information necessary to decode the frame. @@ -1226,10 +1218,9 @@ chunk table and reads the meta data. The audio format handler code is linked into para_server and executed via the _add_ command. The same code is also available as a stand-alone -tool, para_afh, which can be used to print the technical data, the -chunk table and the meta data of a file. Furthermore, one can use -para_afh to cut an audio file, i.e. to select some of its chunks to -produce a new file containing only these chunks. +tool, para_afh, which prints the technical data, the chunk table +and the meta data of a file. Moreover, all audio format handlers are +combined in the afh receiver which is part of para_recv and para_play. ---------- Networking @@ -1433,15 +1424,21 @@ the stream. Examples ~~~~~~~~ -The sender command of para_server allows to (de-)activate senders -and to change the access permissions senders at runtime. The "si" -(server info) command is used to list the streaming options of the -currently running server as well as the various sender access lists. +The "si" (server info) command lists some information about the +currently running server process. --> Show client/target/access lists: +-> Show PIDs, number of connected clients, uptime, and more: para_client si +The sender command of para_server prints information about senders, +like the various access control lists, and it allows to (de-)activate +senders and to change the access permissions at runtime. + +-> List all senders + + para_client sender + -> Obtain general help for the sender command: para_client help sender @@ -1451,6 +1448,10 @@ currently running server as well as the various sender access lists. s=http # or dccp or udp para_client sender $s help +-> Show status of the http sender + + para_client sender http status + By default para_server activates both the HTTP and th DCCP sender on startup. This can be changed via command line options or para_server's config file. @@ -1515,10 +1516,10 @@ the output to STDOUT, the filter modules of para_audiod are always connected to a receiver which produces the input stream and a writer which absorbs the output stream. -Some filters depend on a specific library being installed and are -not compiled in if this library was not found at compile time. To -see the list of supported filters, run para_filter and para_audiod -with the --help option. The output looks similar to the following: +Some filters depend on a specific library and are not compiled in +if this library was not found at compile time. To see the list of +supported filters, run para_filter and para_audiod with the --help +option. The output looks similar to the following: Available filters: compress wav amp fecdec wmadec prebuffer oggdec aacdec mp3dec @@ -2190,11 +2191,14 @@ RFCs Congestion Control ID 2: TCP-like Congestion Control - XREFERENCE(http://www.ietf.org/rfc/rfc4342.txt, RFC 4342) (2006): Congestion Control ID 3: TCP-Friendly Rate Control (TFRC) + - XREFERENCE(http://www.ietf.org/rfc/rfc6716.txt, RFC 6716) (2012): + Definition of the Opus Audio Codec Application web pages ~~~~~~~~~~~~~~~~~~~~~ - - XREFERENCE(http://paraslash.systemlinux.org/, paraslash) + - XREFERENCE(http://people.tuebingen.mpg.de/maan/paraslash/, paraslash) + - XREFERENCE(http://paraslash.systemlinux.org/, paraslash (alternative page)) - XREFERENCE(http://xmms2.org/wiki/Main_Page, xmms) - XREFERENCE(http://www.mpg123.de/, mpg123) - XREFERENCE(http://gstreamer.freedesktop.org/, gstreamer)