X-Git-Url: http://git.tuebingen.mpg.de/?p=paraslash.git;a=blobdiff_plain;f=web%2Fmanual.m4;h=55bb49a653bdfc10c5a84eaeb8c058080b2aa345;hp=3193a2f0ca6ef3901c8cb4c08e897d3e50c65dd3;hb=5c8d440eace21b3a80b7f3f5930dba90e69adeef;hpb=41b994c3243480f360fe9a2eadb32cc1fcf1239e diff --git a/web/manual.m4 b/web/manual.m4 index 3193a2f0..55bb49a6 100644 --- a/web/manual.m4 +++ b/web/manual.m4 @@ -77,11 +77,11 @@ The paraslash executables *para_server* -para_server streams binary audio data (MP3, OGG/Vorbis, OGG/Speex, -M4A, WMA files) over local and/or remote networks. It listens on a -TCP port and accepts commands such as play, stop, pause, next from -authenticated clients. There are many more commands though, see the -man page of para_server for a description of all commands. +para_server streams binary audio data (MP3, ...) over local and/or +remote networks. It listens on a TCP port and accepts commands such +as play, stop, pause, next from authenticated clients. There are +many more commands though, see the man page of para_server for a +description of all commands. It supports three built-in network streaming protocols (senders/receivers): HTTP, DCCP, or UDP. This is explained in more @@ -115,6 +115,9 @@ All connections between para_server and para_client are encrypted with a symmetric RC4 session key. For each user of paraslash you must create a public/secret RSA key pair for authentication. +If para_client is started without non-option arguments, an interactive +session (shell) is started. Command history and command completion are +supported through libreadline. *para_audiod* @@ -135,12 +138,19 @@ socket credentials, if available. The client program which talks to para_audiod. Used to control para_audiod, to receive status info, or to grab the stream at any -point of the decoding process. +point of the decoding process. Like para_client, para_audioc supports +interactive sessions on systems with libreadline. *para_recv* A command line HTTP/DCCP/UDP stream grabber. The http mode is compatible with arbitrary HTTP streaming sources (e.g. icecast). +In addition to the three network streaming modes, para_recv can also +operate in local (afh) mode. In this mode it writes the content of +an audio file on the local file system in complete chunks to stdout, +optionally 'just in time'. This allows to cut an audio file without +first decoding it, and it enables third-party software which is unaware +of the particular audio format to send complete frames in real time. *para_filter* @@ -155,11 +165,7 @@ for audio volume. A small stand-alone program that prints tech info about the given audio file to STDOUT. It can be instructed to print a "chunk table", -an array of offsets within the audio file or to write the content of -the audio file in complete chunks 'just in time'. - -This allows third-party streaming software that is unaware of the -particular audio format to send complete frames in real time. +an array of offsets within the audio file. *para_write* @@ -168,6 +174,9 @@ output plug-in and optional WAV/raw players for ALSA (Linux) and for coreaudio (Mac OS). para_write can also be used as a stand-alone WAV or raw audio player. +*para_play* + +A command line audio player. *para_gui* @@ -179,7 +188,7 @@ can be added easily. *para_fade* -An (OSS-only) alarm clock and volume-fader. +An alarm clock and volume-fader for OSS and ALSA. ----------- Quick start @@ -193,8 +202,16 @@ REFERENCE(Quick start, set up) a typical server and client. Requirements ~~~~~~~~~~~~ +For the impatient: -In any case you'll need + git clone git://git.tuebingen.mpg.de/osl + cd osl && make && sudo make install && sudo ldconfig + 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 + +Detailed description: In any case you'll need - XREFERENCE(http://systemlinux.org/~maan/osl/, libosl). The _object storage layer_ library is used by para_server. To @@ -202,9 +219,10 @@ In any case you'll need git clone git://git.tuebingen.mpg.de/osl - - XREFERENCE(ftp://ftp.gnu.org/pub/gnu/gcc, gcc). The - EMPH(gnu compiler collection) is usually shipped with the - distro. gcc-3.3 or newer is required. + - XREFERENCE(ftp://ftp.gnu.org/pub/gnu/gcc, gcc) or + XREFERENCE(http://clang.llvm.org, clang). All gcc versions + >= 3.3 are currently supported. Clang version 1.1 or newer + should work as well. - XREFERENCE(ftp://ftp.gnu.org/pub/gnu/make, gnu make) is also shipped with the disto. On BSD systems the gnu make @@ -222,6 +240,10 @@ In any case you'll need distro, but you might have to install the development package (libssl-dev or libgcrypt-dev on debian systems) as well. + - XREFERENCE(ftp://ftp.gnu.org/pub/gnu/gengetopt/, gengetopt) + is needed to generate the C code for the command line parsers + of all paraslash executables. + - XREFERENCE(ftp://ftp.gnu.org/pub/gnu/help2man, help2man) is used to create the man pages. @@ -249,6 +271,14 @@ Optional: - XREFERENCE(http://www.speex.org/, speex). In order to stream or decode speex files, libspeex (libspeex-dev) is required. + - XREFERENCE(http://flac.sourceforge.net/, flac). To stream + or decode files encoded with the _Free Lossless Audio Codec_, + libFLAC (libFLAC-dev) must be installed. + + - XREFERENCE(http://www.mega-nerd.com/SRC/index.html, + libsamplerate). The resample filter will only be compiled if + this library is installed. Debian package: libsamplerate-dev. + - XREFERENCE(ftp://ftp.alsa-project.org/pub/lib/, alsa-lib). On Linux, you'll need to have ALSA's development package libasound2-dev installed. @@ -257,6 +287,14 @@ Optional: libao). Needed to build the ao writer (ESD, PulseAudio,...). Debian package: libao-dev. + - XREFERENCE(ftp://ftp.gnu.org/pub/gnu/ncurses, curses). Needed + for para_gui. Debian package: libncurses-dev. + + - XREFERENCE(http://cnswww.cns.cwru.edu/php/chet/readline/rltop.html, + GNU Readline). If this library (libreadline-dev) is installed, + para_client, para_audioc and para_play support interactive + sessions. + Installation ~~~~~~~~~~~~ @@ -274,10 +312,20 @@ 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: +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: + + ./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 @@ -358,7 +406,7 @@ the directory /var/paraslash that has been created during installation: sudo chown $LOGNAME /var/paraslash -Alternatively, use the --afs_socket Option to specify a different +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 @@ -477,7 +525,7 @@ including ssh and gpg. An RSA key consists in fact of two keys, called the public key and the private key. A message can be encrypted with either key and only the counterpart of that key can decrypt the message. While RSA can be used for both signing and encrypting -a message, paraslash only uses RSA only for the latter purpose. The +a message, paraslash uses RSA only for the latter purpose. The RSA public key encryption and signatures algorithms are defined in detail in RFC 2437. @@ -497,12 +545,13 @@ as follows: - para_client connects to para_server and sends an authentication request for a user. It does so by connecting - to para_server, TCP 2990, the control port of para_server. + to TCP port 2990 of the server host. This port is called the + para_server _control port_. - para_server accepts the connection and forks a child process - which is supposed to handle the connection. The parent process - keeps listening on the control port while the child process - (also called para_server below) continues as follows. + which handles the incoming request. The parent process keeps + listening on the control port while the child process (also + called para_server below) continues as follows. - para_server loads the RSA public key of that user, fills a fixed-length buffer with random bytes, encrypts that buffer @@ -512,7 +561,7 @@ as follows: session key. - para_client receives the encrypted buffer and decrypts it - using the user's private key, thereby obtaining the challenge + with the user's private key, thereby obtaining the challenge buffer and the session key. It sends the SHA1 hash value of the challenge back to para_server and stores the session key for further use. @@ -541,9 +590,9 @@ file, below). The user_list file ~~~~~~~~~~~~~~~~~~ -At startup para_server reads the user list file which must contain -one line per user. The default location of the user list file may be -changed with the --user_list option. +At startup para_server reads the user list file which contains one +line per user. The default location of the user list file may be +changed with the --user-list option. There should be at least one user in this file. Each user must have an RSA key pair. The public part of the key is needed by para_server @@ -590,7 +639,7 @@ restricted on platforms that support UNIX socket credentials which allow para_audiod to obtain the Unix credentials of the connecting process. -Use para_audiod's --user_allow option to allow connections only for +Use para_audiod's --user-allow option to allow connections only for a limited set of users. ----------------------- @@ -609,10 +658,11 @@ 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 libosl, the object storage layer, 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 lightweight than a full database backend. +AFS uses XREFERENCE(http://systemlinux.org/~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 +lightweight than a full database backend. In this chapter we sketch the setup of the REFERENCE(The AFS process, AFS process) during server startup and proceed with the description @@ -622,7 +672,7 @@ and moods) explains these two audio file selection mechanisms in detail and contains pratical examples. The way REFERENCE(File renames and content changes, file renames and content changes) are detected is discussed briefly before the REFERENCE(Troubleshooting, -Troubleshooting) section which concludes the chapter. +Troubleshooting) section concludes the chapter. The AFS process ~~~~~~~~~~~~~~~ @@ -725,7 +775,7 @@ Similarly, the "test" bit can be removed from an audio file with para_client setatt test- /path/to/the/audio/file Instead of a path you may use a shell wildcard pattern. The attribute -is applied to all audio files matching that pattern: +is applied to all audio files matching this pattern: para_client setatt test+ '/test/directory/*' @@ -781,7 +831,7 @@ can be used. Note that the images and lyrics are not interpreted at all, and also the playlist and the mood blobs are only investigated when the mood -or playlist is activated by using the select command. +or playlist is activated with the select command. *The score table* @@ -797,7 +847,9 @@ next. While doing so, it computes the new score and updates the last_played and the num_played fields in the audio file table. The score table is recomputed by the select command which loads a -new mood or playlist. +mood or playlist. Audio files are chosen for streaming from the rows +of the score table on a highest-score-first basis. + Playlists and moods ~~~~~~~~~~~~~~~~~~~ @@ -809,17 +861,12 @@ terms of attributes and other type of information available in the audio file table. As an example, a mood can define a filename pattern, which is then matched against the names of audio files in the table. -Selecting a mood or playlist means the generation of a ranking -(a score table) for the set of admissible files. Audio files are -then selected on a highest-score-first basis. The score table is -recomputed at the moment the mood or playlist is selected. - *Playlists* Playlists are accommodated in the playlist table of the afs database, -using the aforementioned blob format for tables. A new filelist is -created using the addpl command, by specifying the full (absolute) -paths of all desired audio files, separated by newlines. For example +using the aforementioned blob format for tables. A new playlist is +created with the addpl command by specifying the full (absolute) +paths of all desired audio files, separated by newlines. Example: find /my/mp3/dir -name "*.mp3" | para addpl my_playlist @@ -839,7 +886,7 @@ 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. -At any time, at most one mood can be *active* which means that +At any time at most one mood can be *active* which means that para_server is going to select only files from that subset of admissible files. @@ -949,7 +996,7 @@ The year tag is special as its value is undefined if the audio file has no year tag or the content of the year tag is not a number. Such audio files never match. Another difference is the special treatment if the year tag is a two-digit number. In this case either 1900 or -2000 are added to the tag value depending on whether the number is +2000 is added to the tag value, depending on whether the number is greater than 2000 plus the current year. @@ -1107,6 +1154,15 @@ how meta data about the file is to be encoded. The bit stream of WMA is composed of superframes, each containing one or more frames of 2048 samples. For 16 bit stereo a WMA superframe is about 8K large. +*FLAC* + +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 +to 16K. Each frame starts with a header that contains all information +necessary to decode the frame. + Meta data ~~~~~~~~~ @@ -1119,10 +1175,10 @@ title, album, year and comment tags. Each of these can only be at most 32 characters long. ID3, version 2 is much more flexible but requires a separate library being installed for paraslash to support it. -Ogg vorbis files contain meta data as Vorbis comments, which are -typically implemented as strings of the form "[TAG]=[VALUE]". Unlike -ID3 version 1 tags, one may use whichever tags are appropriate for -the content. +Ogg vorbis, ogg speex and flac files contain meta data as Vorbis +comments, which are typically implemented as strings of the form +"[TAG]=[VALUE]". Unlike ID3 version 1 tags, one may use whichever +tags are appropriate for the content. AAC files usually use the MPEG-4 container format for storing meta data while WMA files wrap meta data as special objects within the @@ -1140,7 +1196,7 @@ paraslash uses the word "chunk" as common term for the building blocks of an audio file. For MP3 files, a chunk is the same as an MP3 frame, while for OGG files a chunk is an OGG page, etc. Therefore the chunk size varies considerably between audio formats, from a few hundred -bytes (MP3) up to 8K (WMA). +bytes (MP3) up to 16K (FLAC). The chunk table contains the offsets within the audio file that correspond to the chunk boundaries of the file. Like the meta data, @@ -1714,7 +1770,7 @@ a curses window. By default the command para_audioc -- stat -p -is executed, but this can be customized via the --stat_cmd option. In +is executed, but this can be customized via the --stat-cmd option. In particular it possible to use para_client -- stat -p @@ -1804,11 +1860,6 @@ branches, below), the git source code management tool is used for paraslash development. It is necessary for cloning the git repository and for getting updates. -ftp://ftp.gnu.org/pub/gnu/gengetopt/ (gengetopt). The C code for -the command line parsers of all paraslash executables is generated -by gengetopt. The generated C files are shipped in the tarballs but -are not contained in the git repository. - ftp://ftp.gnu.org/pub/gnu/m4/ (m4). Some input files for gengetopt are generated from templates by the m4 macro processor. @@ -1885,7 +1936,7 @@ the tip of topic branches you are interested in from the output of "git log next"). You should be able to safely build on top of them. However, at times "next" will be rebuilt from the tip of "master" to -get rid of merge commits that will never be in "master. The commit +get rid of merge commits that will never be in "master". The commit that replaces "next" will usually have the identical tree, but it will have different ancestry from the tip of "master".