X-Git-Url: http://git.tuebingen.mpg.de/?p=paraslash.git;a=blobdiff_plain;f=web%2Fmanual.m4;h=5ceeac08af48642095e8b6c4d6fa7d0f2799fb22;hp=7163bb7b8d700788795ce23ef8110fb90a1154a5;hb=4a30c5e28b85d674d30ce7fc49c905cff62b5d0e;hpb=d49cd9a91015766cb19d7d43bb04048265925fe5 diff --git a/web/manual.m4 b/web/manual.m4 index 7163bb7b..5ceeac08 100644 --- a/web/manual.m4 +++ b/web/manual.m4 @@ -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* @@ -179,7 +185,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 @@ -223,6 +229,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. @@ -250,6 +260,10 @@ 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(ftp://ftp.alsa-project.org/pub/lib/, alsa-lib). On Linux, you'll need to have ALSA's development package libasound2-dev installed. @@ -258,6 +272,10 @@ Optional: libao). Needed to build the ao writer (ESD, PulseAudio,...). Debian package: libao-dev. + - XREFERENCE(http://cnswww.cns.cwru.edu/php/chet/readline/rltop.html, + GNU Readline). If this library (libreadline-dev) is installed, + para_client and para_audioc support interactive sessions. + Installation ~~~~~~~~~~~~ @@ -275,10 +293,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 @@ -478,7 +506,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. @@ -1107,6 +1135,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 +1156,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 +1177,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, @@ -1804,11 +1841,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.