wmadec: Simplify wma_lsp_to_curve_init().
[paraslash.git] / web / manual.m4
index 6a72771..d63b07e 100644 (file)
@@ -259,7 +259,8 @@ Optional:
        - XREFERENCE(http://www.underbit.com/products/mad/,
        libid3tag). For version-2 ID3 tag support, you'll need
        the libid3tag development package libid3tag0-dev. Without
-       libid3tag, only version one tags are recognized.
+       libid3tag, only version-1 tags are recognized. The mp3 tagger
+       also needs this library for modifying (id3v1 and id3v2) tags.
 
        - XREFERENCE(http://www.xiph.org/downloads/, ogg vorbis).
        For ogg vorbis streams you'll need libogg, libvorbis,
@@ -298,35 +299,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
@@ -374,18 +354,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:
@@ -402,14 +375,6 @@ Finally, tell para_client to connect to server_host:
 
 *Step 2*: Start para_server
 
-Before starting the server make sure you have write permissions to
-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
-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.
 
@@ -454,19 +419,8 @@ You may print the list of all known audio files with
 
 *Step 4*: Configure para_audiod
 
-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
-
-In order to make this directory writable for para_audiod, execute
-as bar@client_host
-
-       sudo chown $LOGNAME /var/paraslash
-
-
-We will also have to tell para_audiod that it should receive the
-audio stream from server_host via http:
+We will have to tell para_audiod that it should receive the audio
+stream from server_host via http:
 
        para_audiod -l info -r '.:http -i server_host'
 
@@ -483,9 +437,16 @@ streamed in which order.
 
 *Troubleshooting*
 
-It did not work? To find out why, try to receive, decode and play the
-stream manually using para_recv, para_filter and para_write as follows.
+If you receive a socket related error on server or audiod startup,
+make sure you have write permissions to the /var/paraslash directory:
 
+       sudo chown $LOGNAME /var/paraslash
+
+Alternatively, use the --afs-socket (para_server) or --socket
+(para_audiod) option to specify a different socket pathname.
+
+To identify streaming problems try to receive, decode and play the
+stream manually using para_recv, para_filter and para_write as follows.
 For simplicity we assume that you're running Linux/ALSA and that only
 MP3 files have been added to the database.
 
@@ -791,7 +752,7 @@ is applied to all audio files matching this pattern:
 
 The command
 
-       para_client -- ls -lv
+       para_client -- ls -l=v
 
 gives you a verbose listing of your audio files also showing which
 attributes are set.
@@ -1188,7 +1149,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.
 
@@ -1329,10 +1290,10 @@ to the database, so they need to transfer data the other way round,
 from the client to the server.
 
 There is no knowledge about the server commands built into para_client,
-so it does not know about addblob commands. Instead, it inspects the
-first data package sent by the server for a magic string. If this
-string was found, it sends STDIN to the server, otherwise it dumps
-data from the server to STDOUT.
+so it does not know about addblob commands. Instead, the server sends
+a special "awaiting data" packet for these commands. If the client
+receives this packet, it sends STDIN to the server, otherwise it
+dumps data from the server to STDOUT.
 
 Streaming protocols
 ~~~~~~~~~~~~~~~~~~~
@@ -1452,15 +1413,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
@@ -1470,6 +1437,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.
@@ -1581,7 +1552,7 @@ can be directly sent to the sound device or any other software that
 operates on undecoded PCM data (visualizers, equalizers etc.). Such
 filters are called _decoders_ in general, and xxxdec is the name of
 the paraslash decoder for the audio format xxx. For example, the mp3
-decoder filter is called mp3dec.
+decoder is called mp3dec.
 
 Note that the output of the decoder is about 10 times larger than
 its input. This means that filters that operate on the decoded audio
@@ -1590,8 +1561,7 @@ the audio stream before it is fed to the decoder.
 
 Paraslash relies on external libraries for most decoders, so these
 libraries must be installed for the decoder to be included in the
-para_filter and para_audiod executables. The oggdec filter depends
-on the libogg and libvorbis libraries for example.
+executables. For example, the mp3dec filter depends on the mad library.
 
 Forward error correction
 ~~~~~~~~~~~~~~~~~~~~~~~~
@@ -2040,21 +2010,19 @@ Doxygen
 ~~~~~~~
 
 Doxygen is a documentation system for various programming
-languages. The paraslash project uses Doxygen for generating the API
-reference on the web pages, but good source code documentation is
-also beneficial to people trying to understand the code structure
-and the interactions between the various source files.
+languages. The API reference on the paraslash web page is generated
+by doxygen.
 
 It is more illustrative to look at the source code for examples than
-to describe the conventions for documenting the source in this manual,
-so we only describe which parts of the code need doxygen comments,
-but leave out details on documentation conventions.
+to describe the conventions in this manual, so we only describe which
+parts of the code need doxygen comments, but leave out details on
+documentation conventions.
 
 As a rule, only the public part of the C source is documented with
 Doxygen. This includes structures, defines and enumerations in header
 files as well as public (non-static) C functions.  These should be
-documented completely. For example each parameter and the return
-value of a public function should get a descriptive comment.
+documented completely. For example, each parameter and the return
+value of a public function should get a descriptive doxygen comment.
 
 No doxygen comments are necessary for static functions and for
 structures and enumerations in C files (which are used only within
@@ -2163,6 +2131,35 @@ maintain state for each listening receiver, multicast often implies
 connectionless transport, which is the reason that it is currently
 only available via UDP.
 
+Abstract socket namespace
+~~~~~~~~~~~~~~~~~~~~~~~~~
+UNIX domain sockets are a traditional way to communicate between
+processes on the same machine. They are always reliable (see above)
+and don't reorder datagrams. Unlike TCP and UDP, UNIX domain sockets
+support passing open file descriptors or process credentials to
+other processes.
+
+The usual way to set up a UNIX domain socket (as obtained from
+socket(2)) for listening is to first bind the socket to a file system
+pathname and then call listen(2), then accept(2). Such sockets are
+called _pathname sockets_ because bind(2) creates a special socket
+file at the specified path. Pathname sockets allow unrelated processes
+to communicate with the listening process by binding to the same path
+and calling connect(2).
+
+There are two problems with pathname sockets:
+
+       * The listing process must be able to (safely) create the
+       socket special in a directory which is also accessible to
+       the connecting process.
+
+       * After an unclean shutdown of the listening process, a stale
+       socket special may reside on the file system.
+
+The abstract socket namespace is a non-portable Linux feature which
+avoids these problems. Abstract sockets are still bound to a name,
+but the name has no connection with file system pathnames.
+
 License
 ~~~~~~~
 
@@ -2215,7 +2212,8 @@ RFCs
 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)