--- /dev/null
+dnl To generate the html version, execute
+dnl m4 web/manual.m4 | grutatxt --toc
+
+define(`LOCAL_LINK_NAME', `translit(`$1', `A-Z
+', `a-z__')')
+define(`REMOVE_NEWLINE', `translit(`$1',`
+', ` ')')
+
+define(`REFERENCE', ./``#''`LOCAL_LINK_NAME($1)' (`REMOVE_NEWLINE($2)'))
+define(`XREFERENCE', `$1' (`REMOVE_NEWLINE($2)'))
+define(`EMPH', ``_''`REMOVE_NEWLINE($1)'``_'')
+
+Paraslash user manual
+=====================
+
+This document describes how to install, configure and use the paraslash
+network audio streaming system. Most chapters start with a chapter
+overview and conclude with an example section. We try to focus on
+general concepts and on the interaction of the various pieces of the
+paraslash package. Hence this user manual is not meant as a replacement
+for the manual pages that describe all command line options of each
+paraslash executable.
+
+------------
+Introduction
+------------
+
+In this chapter we give an REFERENCE(Overview, overview) of the
+interactions of the two main programs contained in the paraslash
+package, followed by REFERENCE(The paraslash executables, brief
+descriptions) of all executables.
+
+Overview
+~~~~~~~~
+
+The core functionality of the para suite is provided by two main
+executables, para_server and para_audiod. The former maintains a
+database of audio files and streams these files to para_audiod which
+receives and plays the stream.
+
+In a typical setting, both para_server and para_audiod act as
+background daemons whose functionality is controlled by client
+programs: the para_audioc client controls para_audiod over a local
+socket while the para_client program connects to para_server over a
+local or remote networking connection.
+
+Typically, these two daemons run on different hosts but a local setup
+is also possible.
+
+A simplified picture of a typical setup is as follows
+<<
+<pre>
+ server_host client_host
+ ~~~~~~~~~~~ ~~~~~~~~~~~
+
+ +-----------+ audio stream +-----------+
+ |para_server| -----------------------------> |para_audiod|
+ +-----------+ +-----------+
+ ^ ^
+ | |
+ | | connect
+ | |
+ | |
+ | +-----------+
+ | |para_audioc|
+ | +-----------+
+ |
+ |
+ | connect +-----------+
+ +-------------------------------------- |para_client|
+ +-----------+
+</pre>
+>>
+
+The paraslash executables
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+*para_server*
+
+para_server streams binary audio data (MP3, OGG/Vorbis, 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.
+
+It supports three built-in network streaming protocols
+(senders/receivers): HTTP, DCCP, or UDP. This is explained in more
+detail in the section on REFERENCE(Networking, networking).
+
+The built-in audio file selector of paraslash is used to manage your
+audio files. It maintains statistics on the usage of all available
+audio files such as last-played time, and the number of times each
+file was selected.
+
+Additional information may be added to the database to allow
+fine-grained selection based on various properties of the audio file,
+including information found in (ID3) tags. However, old-fashioned
+playlists are also supported.
+
+It is also possible to store images (album covers) and lyrics in the
+database and associate these to the corresponding audio files.
+
+The section on the REFERENCE(The audio file selector, audio file
+selector) discusses this topic.
+
+
+*para_client*
+
+The client program to connect to para_server. paraslash commands
+are sent to para_server and the response is dumped to STDOUT. This
+can be used by any scripting language to produce user interfaces with
+little programming effort.
+
+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.
+
+
+*para_audiod*
+
+The local daemon that collects information from para_server.
+
+It runs on the client side and connects to para_server. As soon as
+para_server announces the availability of an audio stream, para_audiod
+starts an appropriate receiver, any number of filters and a paraslash
+writer to play the stream.
+
+Moreover, para_audiod listens on a local socket and sends status
+information about para_server and para_audiod to local clients on
+request. Access via this local socket may be restricted by using Unix
+socket credentials, if available.
+
+
+*para_audioc*
+
+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.
+
+*para_recv*
+
+A command line HTTP/DCCP/UDP stream grabber. The http mode is
+compatible with arbitrary HTTP streaming sources (e.g. icecast).
+
+*para_filter*
+
+A filter program that reads from STDIN and writes to STDOUT.
+Like para_recv, this is an atomic building block which can be used
+to assemble higher-level audio receiving facilities. It combines
+several different functionalities in one tool: decoders for multiple
+audio formats (MP3, OGG/Vorbis, AAC, WMA) and a number of processing
+filters, among these a normalizer for audio volume.
+
+*para_afh*
+
+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.
+
+*para_write*
+
+A modular audio stream writer. It supports a simple file writer
+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_gui*
+
+Curses-based gui that presents status information obtained in a curses
+window. Appearance can be customized via themes. para_gui provides
+key-bindings for the most common server commands and new key-bindings
+can be added easily.
+
+
+*para_fade*
+
+An (OSS-only) alarm clock and volume-fader.
+
+-----------
+Quick start
+-----------
+
+This chapter lists the REFERENCE(Requirements, necessary software)
+that must be installed to compile the paraslash package, describes
+how to REFERENCE(Installation, compile and install) the paraslash
+source code and the steps that have to be performed in order to
+REFERENCE(Quick start, set up) a typical server and client.
+
+Requirements
+~~~~~~~~~~~~
+
+In any case you'll need
+
+ - XREFERENCE(http://systemlinux.org/~maan/osl/, libosl).
+ The _object storage layer_ library is used by para_server. To
+ clone the source code repository, execute
+
+ 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/make, gnu make) is
+ also shipped with the disto. On BSD systems the gnu make
+ executable is often called gmake.
+
+ - XREFERENCE(ftp://ftp.gnu.org/pub/gnu/bash, bash). Some
+ scripts which run during compilation require the EMPH(Bourne
+ again shell). It is most likely already installed.
+
+ - XREFERENCE(http://www.openssl.org/, openssl). The EMPH(Secure
+ Sockets Layer) library is needed for cryptographic routines
+ on both the server and the client side. It is usually shipped
+ with the distro, but you might have to install the "development
+ package" (called libssl-dev on debian systems) as well.
+
+ - XREFERENCE(ftp://ftp.gnu.org/pub/gnu/help2man, help2man)
+ is used to create the man pages.
+
+Optional:
+
+ - XREFERENCE(http://www.underbit.com/products/mad/, libmad).
+ To compile in MP3 support for paraslash, the development
+ package must be installed. It is called libmad0-dev on
+ debian-based systems. Note that libmad is not necessary on
+ the server side, i.e. for sending MP3 files.
+
+ - 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.
+
+ - XREFERENCE(http://www.xiph.org/downloads/, ogg vorbis).
+ For ogg vorbis streams you'll need libogg, libvorbis,
+ libvorbisfile. The corresponding Debian packages are called
+ libogg-dev and libvorbis-dev.
+
+ - XREFERENCE(http://www.audiocoding.com/, libfaad). For aac
+ files (m4a) you'll need libfaad (libfaad-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.
+
+Installation
+~~~~~~~~~~~~
+
+First make sure all non-optional packages listed in the section on
+REFERENCE(Requirements, required software) are installed on your
+system.
+
+You don't need everything listed there. In particular, MP3, OGG/Vorbis
+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:
+
+ (./configure && make) > /dev/null
+
+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
+might need to tell the configure script where to find them. Try
+
+ ./configure --help
+
+to see a list of options. If the paraslash package was compiled
+successfully, execute as root,
+
+ make install
+
+to install executables under /usr/local/bin and the man pages under
+/usr/local/man.
+
+Configuration
+~~~~~~~~~~~~~
+
+*Step 1*: Create a paraslash user
+
+In order to control para_server at runtime you must create a paraslash
+user. As authentication is based on the RSA crypto system you'll have
+to create an RSA key pair. If you already have a user and an RSA key
+pair, you may skip this step.
+
+In this section we'll assume a typical setup: You would like to run
+para_server on some host called server_host as user foo, and you want
+to connect to para_server from another machine called client_host as
+user bar.
+
+As foo@server_host, create ~/.paraslash/server.users by typing the
+following commands:
+
+ user=bar
+ target=~/.paraslash/server.users
+ key=~/.paraslash/key.pub.$user
+ perms=AFS_READ,AFS_WRITE,VSS_READ,VSS_WRITE
+ mkdir -p ~/.paraslash
+ echo "user $user $key $perms" >> $target
+
+Next, change to the "bar" account on client_host and generate the
+key pair with the commands
+
+ key=~/.paraslash/key.$LOGNAME
+ mkdir -p ~/.paraslash
+ (umask 077 && openssl genrsa -out $key 2048)
+
+para_server only needs to know the public key of the key pair just
+created. It can be extracted with
+
+ pubkey=~/.paraslash/key.pub.$LOGNAME
+ openssl rsa -in $key -pubout -out $pubkey
+
+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
+
+
+*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.
+
+ para_server -l info
+
+Now you can use para_client to connect to the server and issue
+commands. Open a new shell as bar@client_host 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.
+
+*Step 3*: Create and populate the database
+
+An empty database is created with
+
+ para_client init
+
+This initializes a couple of empty tables under
+~/.paraslash/afs_database-0.4. 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-0.4
+
+in case something went wrong.
+
+Next, you need to add some audio files to that database so that
+para_server knows about them. 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 files. Note that the table only contains data
+about the audio files found, not the files themselves.
+
+You may print the list of all known audio files with
+
+ para_client ls
+
+*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:
+
+ para_audiod -l info -r 'mp3:http -i server_host'
+
+You should now be able to listen to the audio stream once para_server
+starts streaming. To activate streaming, execute
+
+ para_client play
+
+Since no playlist has been specified yet, the "dummy" mode which
+selects all known audio files is activated automatically. See the
+section on the REFERENCE(The audio file selector, audio file selector)
+for how to use playlists and moods to specify which files should be
+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.
+
+For simplicity we assume that you're running Linux/ALSA and that only
+MP3 files have been added to the database.
+
+ para_recv -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
+
+Double check what is logged by para_server and use the --loglevel
+option of para_recv, para_filter and para_write to increase verbosity.
+
+---------------
+User management
+---------------
+
+para_server uses a challenge-response mechanism to authenticate
+requests from incoming connections, similar to ssh's public key
+authentication method. Authenticated connections are encrypted using
+the RC4 stream cipher.
+
+In this chapter we briefly describe RSA and RC4 and sketch the
+REFERENCE(Client-server authentication, authentication handshake)
+between para_client and para_server. User management is discussed
+in the section on REFERENCE(The user_list file, the user_list file).
+These sections are all about communication between the client and the
+server. Connecting para_audiod is a different matter and is described
+in a REFERENCE(Connecting para_audiod, separate section).
+
+
+
+RSA and RC4
+~~~~~~~~~~~
+
+RSA is an asymmetric block cipher which is used in many applications,
+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
+RSA public key encryption and signatures algorithms are defined in
+detail in RFC 2437.
+
+RC4 is a stream cipher, i.e. the input is XORed with a pseudo-random
+key stream to produce the output. Decryption uses the same function
+calls as encryption. While RC4 supports variable key lengths,
+paraslash uses a fixed length of 256 bits, which is considered a
+strong encryption by today's standards. Since the same key must never
+be used twice, a different, randomly-generated key is used for every
+new connection.
+
+Client-server authentication
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The authentication handshake between para_client and para_server goes
+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.
+
+ - 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.
+
+ - para_server loads the RSA public key of that user, fills a
+ fixed-length buffer with random bytes, encrypts that buffer
+ using the public key and sends the encrypted buffer to the
+ client. The first part of the buffer is the challenge which
+ is used for authentication while the second part is the RC4
+ session key.
+
+ - para_client receives the encrypted buffer and decrypts it
+ using 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.
+
+ - para_server also computes the SHA1 hash of the challenge
+ and compares it against what was sent back by the client.
+
+ - If the two hashes do not match, the authentication has
+ failed and para_server closes the connection.
+
+ - Otherwise the user is considered authenticated and the client
+ is allowed to proceed by sending a command to be executed. From
+ this point on the communication is encrypted using the RC4
+ stream cipher with the session key known to both peers.
+
+paraslash relies on the quality of openssl's cryptographically strong
+pseudo-random bytes, on the security of the implementation of the
+openssl RSA and RC4 crypto routines and on the infeasibility to invert
+the SHA1 function.
+
+Neither para_server or para_client create RSA keys on their own. This
+has to be done once for each user as sketched in REFERENCE(Quick start,
+Quick start) and discussed in more detail REFERENCE(The user_list
+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.
+
+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
+while the private key is needed by para_client. Each line of the
+user list file must be of the form
+
+ user <username> <key> <perms>
+
+where _username_ is an arbitrary string (usually the user's login
+name), _key_ is the full path to that user's public RSA key, and
+_perms_ is a comma-separated list of zero or more of the following
+permission bits:
+
+ +---------------------------------------------------------+
+ | AFS_READ | read the contents of the databases |
+ +-----------+---------------------------------------------+
+ | AFS_WRITE | change database contents |
+ +-----------+---------------------------------------------+
+ | VSS_READ | obtain information about the current stream |
+ +-----------+---------------------------------------------+
+ | VSS_WRITE | change the current stream |
+ +---------------------------------------------------------+
+
+The permission bits specify which commands the user is allowed to
+execute. The output of
+
+ para_client help
+
+contains in the third column the permissions needed to execute the
+command.
+
+A new RSA key can be created with
+
+ openssl genrsa -out <private_key> 2048
+
+and the public part may be extracted with
+
+ openssl rsa -in <private_key> -pubout -out <public_key>
+
+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.
+
+It is possible to make para_server reread the user_list file by
+executing the paraslash "hup" command or by sending SIGHUP to the
+PID of para_server.
+
+
+Connecting para_audiod
+~~~~~~~~~~~~~~~~~~~~~~
+
+para_audiod listens on a Unix domain socket. Those sockets are
+for local communication only, so only local users can connect to
+para_audiod. The default is to let any user connect but this can be
+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
+a limited set of users.
+
+-----------------------
+The audio file selector
+-----------------------
+
+paraslash comes with a sophisticated audio file selector (AFS),
+whose main task is to determine which file to stream next, based on
+information on the audio files stored in a database. It communicates
+also with para_client whenever an AFS command is executed, for example
+to answer a database query.
+
+Besides the traditional playlists, AFS supports audio file selection
+based on _moods_ which act as a filter that limits the set of all
+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.
+
+In this chapter we sketch the setup of the REFERENCE(The AFS process,
+AFS process) during server startup and proceed with the description
+of the REFERENCE(Database layout, layout) of the various database
+tables. The section on REFERENCE(Playlists and moods, playlists
+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.
+
+The AFS process
+~~~~~~~~~~~~~~~
+
+On startup, para_server forks to create the AFS process which opens
+the OSL database tables. The server process communicates with the
+AFS process via pipes and shared memory. Usually, the AFS process
+awakes only briefly whenever the current audio file changes. The AFS
+process determines the next audio file, opens it, verifies it has
+not been changed since it was added to the database and passes the
+open file descriptor to the server process, along with audio file
+meta-data such as file name, duration, audio format and so on. The
+server process then starts to stream the audio file.
+
+The AFS process also accepts connections from local clients via
+a well-known socket. However, only child processes of para_server
+may connect through this socket. All server commands that have the
+AFS_READ or AFS_WRITE permission bits use this mechanism to query or
+change the database.
+
+Database layout
+~~~~~~~~~~~~~~~
+
+*The audio file table*
+
+This is the most important and usually also the largest table of the
+AFS database. It contains the information needed to stream each audio
+file. In particular the following data is stored for each audio file.
+
+ - SHA1 hash value of the audio file contents. This is computed
+ once when the file is added to the database. Whenever AFS
+ selects this audio file for streaming the hash value is
+ recomputed and checked against the value stored in the
+ database to detect content changes.
+
+ - The time when this audio file was last played.
+
+ - The number of times the file has been played so far.
+
+ - The attribute bitmask.
+
+ - The image id which describes the image associated with this
+ audio file.
+
+ - The lyrics id which describes the lyrics associated with
+ this audio file.
+
+ - The audio format id (MP3, OGG, AAC, WMA).
+
+ - An amplification value that can be used by the amplification
+ filter to pre-amplify the decoded audio stream.
+
+ - The chunk table. It describes the location and the timing
+ of the building blocks of the audio file. This is used by
+ para_server to send chunks of the file at appropriate times.
+
+ - The duration of the audio file.
+
+ - Tag information contained in the audio file (ID3 tags,
+ Vorbis comments, ...).
+
+ - The number of channels
+
+ - The encoding bitrate.
+
+ - The sampling frequency.
+
+To add or refresh the data contained in the audio file table, the _add_
+command is used. It takes the full path of either an audio file or a
+directory. In the latter case, the directory is traversed recursively
+and all files which are recognized as valid audio files are added to
+the database.
+
+*The attribute table*
+
+The attribute table contains two columns, _name_ and _bitnum_. An
+attribute is simply a name for a certain bit number in the attribute
+bitmask of the audio file table.
+
+Each of the 64 bits of the attribute bitmask can be set for each
+audio file individually. Hence up to 64 different attributes may be
+defined. For example, "pop", "rock", "blues", "jazz", "instrumental",
+"german_lyrics", "speech", whatever. You are free to choose as
+many attributes as you like and there are no naming restrictions
+for attributes.
+
+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 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:
+
+ para_client setatt test+ '/test/directory/*'
+
+The command
+
+ para_client -- ls -lv
+
+gives you a verbose listing of your audio files also showing 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 what follows we shall use this alias.
+
+The "test" attribute can be dropped 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.
+
+*Blob tables*
+
+The image, lyrics, moods and playlists tables are all blob tables.
+Blob tables consist of three columns each: The identifier which is
+a positive non-negative number that is auto-incremented, the name
+(an arbitrary string) and the content (the blob).
+
+All blob tables support the same set of actions: cat, ls, mv, rm
+and add. Of course, _add_ is used for adding new blobs to the table
+while the other actions have the same meaning as the corresponding
+Unix commands. The paraslash commands to perform these actions are
+constructed as the concatenation of the table name and the action. For
+example addimg, catimg, lsimg, mvimg, rmimg are the commands that
+manipulate or query the image table.
+
+The add variant of these commands is special as these commands read
+the blob contents from stdin. To add an image to the image table the
+command
+
+ para addimg image_name < file.jpg
+
+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.
+
+*The score table*
+
+Unlike all other tables the contents of the score table remain in
+memory and are never stored on disk. The score table contains two
+columns: The SHA1 hash value (of an audio file) and its current
+score.
+
+However, only those files which are admissible for the current mood
+or playlist are contained in the score table. The audio file selector
+always chooses the row with the highest score as the file to stream
+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.
+
+Playlists and moods
+~~~~~~~~~~~~~~~~~~~
+
+Playlists and moods offer two different ways of specifying the set of
+admissible files. A playlist in itself describes a set of admissible
+files. A mood, in contrast, describes the set of admissible files in
+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
+
+ find /my/mp3/dir -name "*.mp3" | para addpl my_playlist
+
+If _my_playlist_ already exists it is overwritten. To activate the
+new playlist, execute
+
+ para select p/my_playlist
+
+The audio file selector will assign scores to each entry of the list,
+in descending order so that files will be selected in order. If a
+file could not be opened for streaming, its entry is removed from
+the score table (but not from the playlist).
+
+*Moods*
+
+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
+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 <score>] [if] [not] <mood_method> [options]
+ deny [with score <score>] [if] [not] <mood_method> [options]
+ score <score> [if] [not] <mood_method> [options]
+
+
+Here <score> 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, i.e. 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] <mood_method> [options]
+
+and analogously for the deny case. The "if" keyword is only syntactic
+sugar 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 a 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, an audio file F is admissible if and only if
+
+ (F ~ AL1 or F ~ AL2...) and not (F ~ DL1 or F ~ DN2 ...)
+
+where 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.
+
+ is_set <attribute_name>
+
+Takes the name of an attribute and matches iff that attribute is set.
+
+ path_matches <pattern>
+
+Takes a filename pattern and matches iff the path of the audio file
+matches the pattern.
+
+ artist_matches <pattern>
+ album_matches <pattern>
+ title_matches <pattern>
+ comment_matches <pattern>
+
+Takes an extended regular expression and matches iff the text of the
+corresponding tag of the audio file matches the pattern. If the tag
+is not set, the empty string is matched against the pattern.
+
+ year ~ <num>
+ bitrate ~ <num>
+ frequency ~ <num>
+ channels ~ <num>
+ num_played ~ <num>
+
+Takes a comparator ~ of the set {<, =, <=, >, >=, !=} and a number
+<num>. Matches an audio file iff the condition <val> ~ <num> is
+satisfied where val is the corresponding value of the audio file
+(value of the year tag, bitrate in kbit/s, frequency in Hz, channel
+count, play count).
+
+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
+greater than 2000 plus the current year.
+
+
+*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 select m/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)
+
+(de Morgan's rule), a mood definition that selects only Punk-Rock
+songs is
+
+ deny if not is_set punk
+ deny if not is_set rock
+
+
+
+File renames and content changes
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Since the audio file selector knows the SHA1 of each audio file that
+has been added to the afs database, it recognizes if the content of
+a file has changed, e.g. because an ID3 tag was added or modified.
+Also, if a file has been renamed or moved to a different location,
+afs will detect that an entry with the same hash value already exists
+in the audio file table.
+
+In both cases it is enough to just re-add the new file. In the
+first case (file content changed), the audio table is updated, while
+metadata such as the num_played and last_played fields, as well as
+the attributes, remain unchanged. In the other case, when the file
+is moved or renamed, only the path information is updated, all other
+data remains as before.
+
+It is possible to change the behaviour of the add command by using the
+"-l" (lazy add) or the "-f" (force add) option.
+
+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.
+
+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.
+
+If you don't mind to recreate your database you can start
+from scratch by removing the entire database directory, i.e.
+
+ rm -rf ~/.paraslash/afs_database-0.4
+
+Be aware that this removes all attribute definitions, all playlists
+and all mood definitions and requires to re-initialize the tables.
+
+Although oslfsck fixes inconsistencies in database tables it doesn't
+care about the table contents. To check for invalid table contents, use
+
+ para_client check
+
+This prints out references to missing audio files as well as invalid
+playlists and mood definitions.
+
+---------------------------------------
+Audio formats and audio format handlers
+---------------------------------------
+
+Audio formats
+~~~~~~~~~~~~~
+
+The following audio formats are supported by paraslash:
+
+*MP3*
+
+Mp3, MPEG-1 Audio Layer 3, is a common audio format for audio storage,
+designed as part of its MPEG-1 standard. An MP3 file is made up of
+multiple MP3 frames, which consist of a header and a data block. The
+size of an MP3 frame depends on the bit rate and on the number
+of channels. For a typical CD-audio file (sample rate of 44.1 kHz
+stereo), encoded with a bit rate of 128 kbit, an MP3 frame is about
+400 bytes large.
+
+*OGG/Vorbis*
+
+OGG is a standardized audio container format, while Vorbis is an
+open source codec for lossy audio compression. Since Vorbis is most
+commonly made available via the OGG container format, it is often
+referred to as OGG/Vorbis. The OGG container format divides data into
+chunks called OGG pages. A typical OGG page is about 4KB large. The
+Vorbis codec creates variable-bitrate (VBR) data, where the bitrate
+may vary considerably.
+
+*AAC*
+
+Advanced Audio Coding (AAC) is a standardized, lossy compression
+and encoding scheme for digital audio which is the default audio
+format for Apple's iPhone, iPod, iTunes. Usually MPEG-4 is used as
+the container format and audio files encoded with AAC have the .m4a
+extension. A typical AAC frame is about 700 bytes large.
+
+*WMA*
+
+Windows Media Audio (WMA) is an audio data compression technology
+developed by Microsoft. A WMA file is usually encapsulated in the
+Advanced Systems Format (ASF) container format, which also specifies
+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.
+
+Meta data
+~~~~~~~~~
+
+Unfortunately, each audio format has its own conventions how meta
+data is added as tags to the audio file.
+
+For MP3 files, ID3, version 1 and 2 are widely used. ID3 version 1
+is rather simple but also very limited as it supports only artist,
+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.
+
+AAC files usually use the MPEG-4 container format for storing meta
+data while WMA files wrap meta data as special objects within the
+ASF container format.
+
+paraslash only tracks the most common tags that are supported by
+all tag variants: artist, title, year, album, comment. When a file
+is added to the AFS database, the meta data of the file is extracted
+and stored in the audio file table.
+
+Chunks and chunk tables
+~~~~~~~~~~~~~~~~~~~~~~~
+
+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/Vorbis 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).
+
+The chunk table contains the offsets within the audio file that
+correspond to the chunk boundaries of the file. Like the meta data,
+the chunk table is computed and stored in the database whenever an
+audio file is added.
+
+The paraslash senders (see below) always send complete chunks. The
+granularity for seeking is therefore determined by the chunk size.
+
+Audio format handlers
+~~~~~~~~~~~~~~~~~~~~~
+
+For each audio format paraslash contains an audio format handler whose
+first task is to tell whether a given file is a valid audio file of
+this type. If so, the audio file handler extracts some technical data
+(duration, sampling rate, number of channels etc.), computes the
+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.
+
+----------
+Networking
+----------
+
+Paraslash uses different network connections for control and data.
+para_client communicates with para_server over a dedicated TCP control
+connection. To transport audio data, separate data connections are
+used. For these data connections, a variety of transports (UDP, DCCP,
+HTTP) can be chosen.
+
+The chapter starts with the REFERENCE(The paraslash control
+service, control service), followed by a section on the various
+REFERENCE(Streaming protocols, streaming protocols) in which the data
+connections are described. The way audio file headers are embedded into
+the stream is discussed REFERENCE(Streams with headers and headerless
+streams, briefly) before the REFERENCE(Networking examples, example
+section) which illustrates typical commands for real-life scenarios.
+
+Both IPv4 and IPv6 are supported.
+
+The paraslash control service
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+para_server is controlled at runtime via the paraslash control
+connection. This connection is used for server commands (play, stop,
+...) as well as for afs commands (ls, select, ...).
+
+The server listens on a TCP port and accepts connections from clients
+that connect the open port. Each connection causes the server to fork
+off a client process which inherits the connection and deals with that
+client only. In this classical accept/fork approach the server process
+is unaffected if the child dies or goes crazy for whatever reason. In
+fact, the child process can not change address space of server process.
+
+The section on REFERENCE(Client-server authentication, client-server
+authentication) above described the early connection establishment
+from the crypto point of view. Here it is described what happens
+after the connection (including crypto setup) has been established.
+There are four processes involved during command dispatch as sketched
+in the following diagram.
+
+<<
+<pre>
+ server_host client_host
+ ~~~~~~~~~~~ ~~~~~~~~~~~
+
+ +-----------+ connect +-----------+
+ |para_server|<------------------------------ |para_client|
+ +-----------+ +-----------+
+ | ^
+ | fork +---+ |
+ +----------> |AFS| |
+ | +---+ |
+ | ^ |
+ | | |
+ | | connect (cookie) |
+ | | |
+ | | |
+ | fork +-----+ inherited connection |
+ +---------->|child|<--------------------------+
+ +-----+
+</pre>
+>>
+
+Note that the child process is not a child of the afs process,
+so communication of these two processes has to happen via local
+sockets. In order to avoid abuse of the local socket by unrelated
+processes, a magic cookie is created once at server startup time just
+before the server process forks off the AFS process. This cookie is
+known to the server, AFS and the child, but not to unrelated processes.
+
+There are two different kinds of commands: First there are commands
+that cause the server to respond with some answer such as the list
+of all audio files. All but the addblob commands (addimg, addlyr,
+addpl, addmood) are of this kind. The addblob commands add contents
+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.
+
+Streaming protocols
+~~~~~~~~~~~~~~~~~~~
+
+A network (audio) stream usually consists of one streaming source,
+the _sender_, and one or more _receivers_ which read data over the
+network from the streaming source.
+
+Senders are thus part of para_server while receivers are part of
+para_audiod. Moreover, there is the stand-alone tool para_recv which
+can be used to manually download a stream, either from para_server
+or from a web-based audio streaming service.
+
+The following three streaming protocols are supported by paraslash:
+
+ - HTTP. Recommended for public streams that can be played by
+ any player like mpg123, xmms, itunes, winamp, etc. The HTTP
+ sender is supported on all operating systems and all platforms.
+
+ - DCCP. Recommended for LAN streaming. DCCP is currently
+ available only for Linux.
+
+ - UDP. Recommended for multicast LAN streaming.
+
+See the Appendix on REFERENCE(Network protocols, network protocols)
+for brief descriptions of the various protocols relevant for network
+audio streaming with paraslash.
+
+It is possible to activate more than one sender simultaneously.
+Senders can be controlled at run time and via config file and command
+line options.
+
+Note that audio connections are _not_ encrypted. Transport or Internet
+layer encryption should be used if encrypted data connections are
+needed.
+
+Since DCCP and TCP are both connection-oriented protocols, connection
+establishment/teardown and access control are very similar between
+these two streaming protocols. UDP is the most lightweight option,
+since in contrast to TCP/DCCP it is connectionless. It is also the
+only protocol supporting IP multicast.
+
+The HTTP and the DCCP sender listen on a (TCP/DCCP) port waiting for
+clients to connect and establish a connection via some protocol-defined
+handshake mechanism. Both senders maintain two linked lists each:
+The list of all clients which are currently connected, and the list
+of access control entries which determines who is allowed to connect.
+IP-based access control may be configured through config file and
+command line options and via the "allow" and "deny" sender subcommands.
+
+Upon receiving a GET request from the client, the HTTP sender sends
+back a status line and a message. The body of this message is the
+audio stream. This is common practice and is supported by many popular
+clients which can thus be used to play a stream offered by para_server.
+For DCCP things are a bit simpler: No messages are exchanged between
+the receiver and sender. The client simply connects and the sender
+starts to stream.
+
+DCCP is an experimental protocol which offers a number of new features
+not available for TCP. Both ends can negotiate these features using
+a built-in negotiation mechanism. In contrast to TCP/HTTP, DCCP is
+datagram-based (no retransmissions) and thus should not be used over
+lossy media (e.g. WiFi networks). One useful feature offered by DCCP
+is access to a variety of different congestion-control mechanisms
+called CCIDs. Two different CCIDs are available per default on Linux:
+
+
+ - _CCID 2_. A Congestion Control mechanism similar to that
+ of TCP. The sender maintains a congestion window and halves
+ this window in response to congestion.
+
+
+ - _CCID-3_. Designed to be fair when competing for bandwidth.
+ It has lower variation of throughput over time compared with
+ TCP, which makes it suitable for streaming media.
+
+Unlike the HTTP and DCCP senders, the UDP sender maintains only a
+single list, the _target list_. This list describes the set of clients
+to which the stream is sent. There is no list for access control and
+no "allow" and "deny" commands for the UDP sender. Instead, the "add"
+and "delete" commands can be used to modify the target list.
+
+Since both UDP and DCCP offer an unreliable datagram-based transport,
+additional measures are necessary to guard against disruptions over
+networks that are lossy or which may be subject to interference (as
+is for instance the case with WiFi). Paraslash uses FEC (Forward
+Error Correction) to guard against packet losses and reordering. The
+stream is FEC-encoded before it is sent through the UDP socket and
+must be decoded accordingly on the receiver side.
+
+The packet size and the amount of redundancy introduced by FEC can
+be configured via the FEC parameters which are dictated by server
+and may also be configured through the "sender" command. The FEC
+parameters are encoded in the header of each network packet, so no
+configuration is necessary on the receiver side. See the section on
+REFERENCE(Forward error correction, FEC) below.
+
+Streams with headers and headerless streams
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+For ogg vorbis and wma streams, not all information needed to decode
+the stream is contained in each data chunk but only in the audio
+file header of the container format. Therefore clients must be able
+to obtain this information in case streaming starts in the middle of
+the file or if para_audiod is started while para_server is already
+sending a stream.
+
+This is accomplished in different ways, depending on the streaming
+protocol. For connection-oriented streams (HTTP, DCCP) the audio file
+header is sent prior to audio file data. This technique however does
+not work for the connectionless UDP transport. Hence the audio file
+header is periodically being embedded into the UDP audio data stream.
+By default, the header is resent after five seconds. The receiver has
+to wait until the next header arrives before it can start decoding
+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.
+
+-> Show client/target/access lists:
+
+ para_client si
+
+-> Obtain general help for the sender command:
+
+ para_client help sender
+
+-> Get help for a specific sender (contains further examples):
+
+ s=http # or dccp or udp
+ para_client sender $s help
+
+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.
+
+-> List config file options for senders:
+
+ para_server -h
+
+All senders share the "on" and "off" commands, so senders may be
+activated and deactivated independently of each other.
+
+-> Switch off the http sender:
+
+ para_client sender http off
+
+-> Receive a DCCP stream using CCID2 and write the output into a file:
+
+ host=foo.org; ccid=2; filename=bar
+ para_recv --receiver "dccp --host $host --ccid $ccid" > $filename
+
+Note the quotes around the arguments for the dccp receiver. Each
+receiver has its own set of command line options and its own command
+line parser, so arguments for the dccp receiver must be protected
+from being interpreted by para_recv.
+
+-> Start UDP multicast, using the default multicast address:
+
+ para_client sender udp add 224.0.1.38
+
+-> Receive FEC-encoded multicast stream and write the output into a file:
+
+ filename=foo
+ para_recv -r udp > $filename
+
+-> Add an UDP unicast for a client to the target list of the UDP sender:
+
+ t=client.foo.org
+ para_client sender udp add $t
+
+-> Receive this (FEC-encoded) unicast stream:
+
+ filename=foo
+ para_recv -r 'udp -i 0.0.0.0' > $filename
+
+-> Create a minimal config for para_audiod for HTTP streams:
+
+ c=$HOME/.paraslash/audiod.conf.min; s=server.foo.com
+ formats="mp3 ogg aac wma" # remove what you do not have
+ for f in $formats; do echo receiver \"$f:http -i $s\"; done > $c
+ para_audiod --config $c
+
+-------
+Filters
+-------
+
+A paraslash filter is a module which transforms an input stream into
+an output stream. Filters are included in the para_audiod executable
+and in the stand-alone tool para_filter which usually contains the
+same modules.
+
+While para_filter reads its input stream from STDIN and writes
+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:
+
+ Available filters:
+ compress wav amp fecdec wmadec prebuffer oggdec aacdec mp3dec
+
+Out of these filter modules, a chain of filters can be constructed,
+much in the way Unix pipes can be chained, and analogous to the use
+of modules in gstreamer: The output of the first filter becomes the
+input of the second filter. There is no limitation on the number of
+filters and the same filter may occur more than once.
+
+Like receivers, each filter has its own command line options which
+must be quoted to protect them from the command line options of
+the driving application (para_audiod or para_filter). Example:
+
+ para_filter -f 'mp3dec --ignore-crc' -f 'compress --damp 1'
+
+For para_audiod, each audio format has its own set of filters. The
+name of the audio format for which the filter should be applied is
+used as the prefix for the filter option. Example:
+
+ para_audiod -f 'mp3:prebuffer --duration 300'
+
+Decoders
+~~~~~~~~
+
+For each supported audio format there is a corresponding filter
+which decodes audio data in this format to 16 bit PCM data which
+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.
+
+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
+stream have to deal with much more data than filters that transform
+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.
+
+Forward error correction
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+As already mentioned REFERENCE(Streaming protocols, earlier),
+paraslash uses forward error correction (FEC) for the unreliable
+UDP transport. FEC is a technique which was invented already in
+1960 by Reed and Solomon and which is widely used for the parity
+calculations of storage devices (RAID arrays). It is based on the
+algebraic concept of finite fields, today called Galois fields, in
+honour of the mathematician Galois (1811-1832). The FEC implementation
+of paraslash is based on code by Luigi Rizzo.
+
+Although the details require a sound knowledge of the underlying
+mathematics, the basic idea is not hard to understand: For positive
+integers k and n with k < n it is possible to compute for any k given
+data bytes d_1, ..., d_k the corresponding r := n -k parity bytes p_1,
+..., p_r such that all data bytes can be reconstructed from *any*
+k bytes of the set
+
+ {d_1, ..., d_k, p_1, ..., p_r}.
+
+FEC-encoding for unreliable network transports boils down to slicing
+the audio stream into groups of k suitably sized pieces called _slices_
+and computing the r corresponding parity slices. This step is performed
+in para_server which then sends both the data and the parity slices
+over the unreliable network connection. If the client was able
+to receive at least k of the n = k + r slices, it can reconstruct
+(FEC-decode) the original audio stream.
+
+From these observations it is clear that there are three different
+FEC parameters: The slice size, the number of data slices k, and the
+total number of slices n. It is crucial to choose the slice size
+such that no fragmentation of network packets takes place because
+FEC only guards against losses and reodering but fails if slices are
+received partially.
+
+FEC decoding in paralash is performed through the fecdec filter which
+usually is the first filter (there can be other filters before fecdec
+if these do not alter the audio stream).
+
+
+Volume adjustment (amp and compress)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The amp and the compress filter both adjust the volume of the audio
+stream. These filters operate on uncompressed audio samples. Hence
+they are usually placed directly after the decoding filter. Each
+sample is multiplied with a scaling factor (>= 1) which makes amp
+and compress quite expensive in terms of computing power.
+
+*amp*
+
+The amp filter which amplifies the audio stream by a fixed scaling
+factor that must be known in advance. For para_audiod this factor is
+derived from the amplification field of the audio file's entry in
+the audio file table while para_filter uses the value given at the
+command line.
+
+The optimal scaling factor F for an audio file is the largest real
+number F >= 1 such that after multiplication with F all samples still
+fit into the sample interval [-32768, 32767]. One can use para_filter
+in combination with the sox utility to compute F:
+
+ para_filter -f mp3dec -f wav < file.mp3 | sox -t wav - -e stat -v
+
+The amplification value V which is stored in the audio file table,
+however, is an integer between 0 and 255 which is connected to F
+through the formula
+
+ V = (F - 1) * 64.
+
+To store V in the audio file table, the command
+
+ para_client -- touch -a=V file.mp3
+
+is used. The reader is encouraged to write a script that performs
+these computations :)
+
+*compress*
+
+Unlike the amplification filter, the compress filter adjusts the volume
+of the audio stream dynamically without prior knowledge about the peak
+value. It maintains the maximal volume of the last n samples of the
+audio stream and computes a suitable amplification factor based on that
+value and the various configuration options. It tries to chose this
+factor such that the adjusted volume meets the desired target level.
+
+Note that it makes sense to combine amp and compress.
+
+Misc filters (wav and prebuffer)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+These filters are rather simple and do not modify the audio stream at
+all. The wav filter is only useful with para_filter and in connection
+with a decoder. It asks the decoder for the number of channels and the
+sample rate of the stream and adds a Microsoft wave header containing
+this information at the beginning. This allows to write wav files
+rather than raw PCM files (which do not contain any information about
+the number of channels and the sample rate).
+
+The prebuffer filter simply delays the output until the given time has
+passed (starting from the time the first byte was available in its
+input queue) or until the given amount of data has accumulated. It
+is mainly useful for para_audiod if the standard parameters result
+in buffer underruns.
+
+Both filters require almost no additional computing time, even when
+operating on uncompressed audio streams, since data buffers are simply
+"pushed down" rather than copied.
+
+Examples
+~~~~~~~~
+
+-> Decode an mp3 file to wav format:
+
+ para_filter -f mp3dec -f wav < file.mp3 > file.wav
+
+-> Amplify a raw audio file by a factor of 1.5:
+
+ para_filter -f amp --amp 32 < foo.raw > bar.raw
+
+------
+Output
+------
+
+Once an audio stream has been received and decoded to PCM format,
+it can be sent to a sound device for playback. This part is performed
+by paraslash _writers_ which are described in this chapter.
+
+Writers
+~~~~~~~
+
+A paraslash writer acts as a data sink that consumes but does not
+produce audio data. Paraslash writers operate on the client side and
+are contained in para_audiod and in the stand-alone tool para_write.
+
+The para_write program reads uncompressed 16 bit audio data from
+STDIN. If this data starts with a wav header, sample rate and channel
+count are read from the header. Otherwise CD audio (44.1KHz stereo)
+is assumed but this can be overridden by command line options.
+para_audiod, on the other hand, obtains the sample rate and the number
+of channels from the decoder.
+
+Like receivers and filters, each writer has an individual set of
+command line options, and for para_audiod writers can be configured
+per audio format separately. It is possible to activate more than
+one writer for the same stream simultaneously.
+
+OS-dependent APIs
+~~~~~~~~~~~~~~~~~
+
+Unfortunately, the various flavours of Unix on which paraslash
+runs on have different APIs for opening a sound device and starting
+playback. Hence for each such API there is a paraslash writer that
+can play the audio stream via this API.
+
+*ALSA*. The _Advanced Linux Sound Architecture_ is only available on
+Linux systems. Although there are several mid-layer APIs in use by
+the various Linux distributions (ESD, Jack, PulseAudio), paraslash
+currently supports only the low-level ALSA API which is not supposed
+to be change. ALSA is very feature-rich, in particular it supports
+software mixing via its DMIX plugin. ALSA is the default writer on
+Linux systems.
+
+*OSS*. The _Open Sound System_ is the only API on *BSD Unixes and
+is also available on Linux systems, usually provided by ALSA as an
+emulation for backwards compatibility. This API is rather simple but
+also limited. For example only one application can open the device
+at any time. The OSS writer is activated by default on BSD Systems.
+
+*OSX*. Mac OS X has yet another API called CoreAudio. The OSX writer
+for this API is only compiled in on such systems and is of course
+the default there.
+
+*FILE*. The file writer allows to capture the audio stream and
+write the PCM data to a file on the file system rather than playing
+it through a sound device. It is supported on all platforms and is
+always compiled in.
+
+Examples
+~~~~~~~~
+
+-> Use the OSS writer to play a wav file:
+
+ para_write --writer oss < file.wav
+
+-> Enable ALSA software mixing for mp3 streams
+
+ para_audiod --writer 'mp3:alsa -d plug:swmix'
+
+
+---
+Gui
+---
+
+para_gui executes an arbitrary command which is supposed to print
+status information to STDOUT. It then displays this information in
+a curses window. By default the command
+
+ para_audioc -- stat -p
+
+is executed, but this can be customized via the --stat_cmd option. In
+particular it possible to use
+
+ para_client -- stat -p
+
+to make para_gui work on systems on which para_audiod is not running.
+
+Key bindings
+~~~~~~~~~~~~
+
+It is possible to bind keys to arbitrary commands via custom
+key-bindings. Besides the internal keys which can not be changed (help,
+quit, loglevel, version...), the following flavours of key-bindings
+are supported:
+
+ - 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 <specified
+ command>" instead of "<specified command>".
+
+The general form of a key binding is
+
+ key_map k:m:c
+
+which maps key k to command c using mode m. Mode may be x, d or p
+for external, display and paraslash commands, respectively.
+
+Themes
+~~~~~~
+
+Currently there are only two themes for para_gui. It is easy, however,
+to add more themes. To create a new theme one has to define the
+position, color and geometry for for each status item that should be
+shown by this theme. See gui_theme.c for examples.
+
+The "." and "," keys are used to switch between themes.
+
+Examples
+~~~~~~~~
+
+-> Show server info:
+
+ key_map "i:p:si"
+
+-> Jump to the middle of the current audio file by pressing F5:
+
+ key_map "<F5>:p:jmp 50"
+
+-> vi-like bindings for jumping around:
+
+ key_map "l:p:ff 10"
+ key_map "h:p:ff 10-"
+ key_map "w:p:ff 60"
+ key_map "b:p:ff 60-"
+
+-> Print the current date and time:
+
+ key_map "D:d:date"
+
+-> Call other curses programs:
+
+ key_map "U:x:aumix"
+ key_map "!:x:/bin/bash"
+ key_map "^E:x:/bin/sh -c 'vi ~/.paraslash/gui.conf'"
+
+-----------
+Development
+-----------
+
+Tools
+~~~~~
+
+In order to compile the sources from the git repository (rather than
+from tar balls) and for contributing non-trivial changes to the
+paraslash project, some additional tools should be installed on a
+developer machine.
+
+http://git.or.cz/ (git). As described in more detail REFERENCE(Git
+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.
+
+ftp://ftp.gnu.org/pub/gnu/autoconf/ (autoconf) GNU autoconf creates
+the configure file which is shipped in the tarballs but has to be
+generated when compiling from git.
+
+http://www.triptico.com/software/grutatxt.html (grutatxt). The
+HTML version of this manual and some of the paraslash web pages are
+generated by the grutatxt plain text to HTML converter. If changes
+are made to these text files the grutatxt package must be installed
+to regenerate the HTML files.
+
+http://www.stack.nl/~dimitri/doxygen/ (doxygen). The documentation
+of paraslash's C sources uses the doxygen documentation system. The
+conventions for documenting the source code is described in the
+REFERENCE(Doxygen, Doxygen section).
+
+ftp://ftp.gnu.org/pub/gnu/global (global). This is used to generate
+browsable HTML from the C sources. It is needed by doxygen.
+
+Git branches
+~~~~~~~~~~~~
+
+Paraslash has been developed using the git source code management
+tool since 2006. Development is organized roughly in the same spirit
+as the git development itself, as described below.
+
+The following text passage is based on "A note from the maintainer",
+written by Junio C Hamano, the maintainer of git.
+
+There are four branches in the paraslash repository that track the
+source tree: "master", "maint", "next", and "pu".
+
+The "master" branch is meant to contain what is well tested and
+ready to be used in a production setting. There could occasionally be
+minor breakages or brown paper bag bugs but they are not expected to
+be anything major, and more importantly quickly and easily fixable.
+Every now and then, a "feature release" is cut from the tip of this
+branch, named with three dotted decimal digits, like 0.4.2.
+
+Whenever changes are about to be included that will eventually lead to
+a new major release (e.g. 0.5.0), a "maint" branch is forked off from
+"master" at that point. Obvious, safe and urgent fixes after the major
+release are applied to this branch and maintenance releases are cut
+from it. New features never go to this branch. This branch is also
+merged into "master" to propagate the fixes forward.
+
+A trivial and safe enhancement goes directly on top of "master".
+New development does not usually happen on "master", however.
+Instead, a separate topic branch is forked from the tip of "master",
+and it first is tested in isolation; Usually there are a handful such
+topic branches that are running ahead of "master". The tip of these
+branches is not published in the public repository, to keep the number
+of branches that downstream developers need to worry about low.
+
+The quality of topic branches varies widely. Some of them start out as
+"good idea but obviously is broken in some areas" and then with some
+more work become "more or less done and can now be tested by wider
+audience". Luckily, most of them start out in the latter, better shape.
+
+The "next" branch is to merge and test topic branches in the latter
+category. In general, this branch always contains the tip of "master".
+It might not be quite rock-solid production ready, but is expected to
+work more or less without major breakage. The maintainer usually uses
+the "next" version of paraslash for his own pleasure, so it cannot
+be _that_ broken. The "next" branch is where new and exciting things
+take place.
+
+The two branches "master" and "maint" are never rewound, and "next"
+usually will not be either (this automatically means the topics that
+have been merged into "next" are usually not rebased, and you can find
+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.
+
+The "pu" (proposed updates) branch bundles the remainder of the
+topic branches. The "pu" branch, and topic branches that are only in
+"pu", are subject to rebasing in general. By the above definition
+of how "next" works, you can tell that this branch will contain quite
+experimental and obviously broken stuff.
+
+When a topic that was in "pu" proves to be in testable shape, it
+graduates to "next". This is done with
+
+ git checkout next
+ git merge that-topic-branch
+
+Sometimes, an idea that looked promising turns out to be not so good
+and the topic can be dropped from "pu" in such a case.
+
+A topic that is in "next" is expected to be polished to perfection
+before it is merged to "master". Similar to the above, this is
+done with
+
+ git checkout master
+ git merge that-topic-branch
+ git branch -d that-topic-branch
+
+Note that being in "next" is not a guarantee to appear in the next
+release (being in "master" is such a guarantee, unless it is later
+found seriously broken and reverted), nor even in any future release.
+
+Coding Style
+~~~~~~~~~~~~
+
+The preferred coding style for paraslash coincides more or less
+with the style of the Linux kernel. So rather than repeating what is
+written XREFERENCE(http://www.kernel.org/doc/Documentation/CodingStyle,
+there), here are the most important points.
+
+ - Burn the GNU coding standards.
+ - Never use spaces for indentation.
+ - Tabs are 8 characters, and thus indentations are also 8 characters.
+ - Don't put multiple assignments on a single line.
+ - Avoid tricky expressions.
+ - Don't leave whitespace at the end of lines.
+ - The limit on the length of lines is 80 columns.
+ - Use K&R style for placing braces and spaces:
+
+ if (x is true) {
+ we do y
+ }
+
+ - Use a space after (most) keywords.
+ - Do not add spaces around (inside) parenthesized expressions.
+ - Use one space around (on each side of) most binary and ternary operators.
+ - Do not use cute names like ThisVariableIsATemporaryCounter, call it tmp.
+ - Mixed-case names are frowned upon.
+ - Descriptive names for global variables are a must.
+ - Avoid typedefs.
+ - Functions should be short and sweet, and do just one thing.
+ - The number of local variables shouldn't exceed 10.
+ - Gotos are fine if they improve readability and reduce nesting.
+ - Don't use C99-style "// ..." comments.
+ - Names of macros defining constants and labels in enums are capitalized.
+ - Enums are preferred when defining several related constants.
+ - Always use the paraslash wrappers for allocating memory.
+ - If the name of a function is an action or an imperative.
+ command, the function should return an error-code integer
+ (<0 means error, >=0 means success). If the name is a
+ predicate, the function should return a "succeeded" boolean.
+
+
+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.
+
+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.
+
+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.
+
+No doxygen comments are necessary for static functions and for
+structures and enumerations in C files (which are used only within
+this file). This does not mean, however, that those entities need
+no documentation at all. Instead, common sense should be applied to
+document what is not obvious from reading the code.
+
+--------
+Appendix
+--------
+
+Network protocols
+~~~~~~~~~~~~~~~~~
+
+*IP*. The _Internet Protocol_ is the primary networking protocol
+used for the Internet. All protocols described below use IP as the
+underlying layer. Both the prevalent IPv4 and the next-generation
+IPv6 variant are being deployed actively worldwide.
+
+*Connection-oriented and connectionless protocols*. Connectionless
+protocols differ from connection-oriented ones in that state
+associated with the sending/receiving endpoints is treated
+implicitly. Connectionless protocols maintain no internal knowledge
+about the state of the connection. Hence they are not capable of
+reacting to state changes, such as sudden loss or congestion on the
+connection medium. Connection-oriented protocols, in contrast, make
+this knowledge explicit. The connection is established only after
+a bidirectional handshake which requires both endpoints to agree
+on the state of the connection, and may also involve negotiating
+specific parameters for the particular connection. Maintaining an
+up-to-date internal state of the connection also in general means
+that the sending endpoints perform congestion control, adapting to
+qualitative changes of the connection medium.
+
+*Reliability*. In IP networking, packets can be lost, duplicated,
+or delivered out of order, and different network protocols handle
+these problems in different ways. We call a transport-layer protocol
+_reliable_, if it turns the unreliable IP delivery into an ordered,
+duplicate- and loss-free delivery of packets. Sequence numbers
+are used to discard duplicates and re-arrange packets delivered
+out-of-order. Retransmission is used to guarantee loss-free
+delivery. Unreliable protocols, in contrast, do not guarantee ordering
+or data integrity.
+
+*Classification*. With these definitions the protocols which are used
+by paraslash for steaming audio data may be classified as follows.
+
+ - HTTP/TCP: connection-oriented, reliable,
+ - UDP: connectionless, unreliable,
+ - DCCP: connection-oriented, unreliable.
+
+Below we give a short descriptions of these protocols.
+
+*TCP*. The _Transmission Control Protocol_ provides reliable,
+ordered delivery of a stream and a classic window-based congestion
+control. In contrast to UDP and DCCP (see below), TCP does not have
+record-oriented or datagram-based syntax, i.e. it provides a stream
+which is unaware and independent of any record (packet) boundaries.
+TCP is used extensively by many application layers. Besides HTTP (the
+Hypertext Transfer Protocol), also FTP (the File Transfer protocol),
+SMTP (Simple Mail Transfer Protocol), SSH (Secure Shell) all sit on
+top of TCP.
+
+*UDP*. The _User Datagram Protocol_ is the simplest transport-layer
+protocol, built as a thin layer directly on top of IP. For this reason,
+it offers the same best-effort service as IP itself, i.e. there is no
+detection of duplicate or reordered packets. Being a connectionless
+protocol, only minimal internal state about the connection is
+maintained, which means that there is no protection against packet
+loss or network congestion. Error checking and correction (if at all)
+are performed in the application.'
+
+*DCCP*. The _Datagram Congestion Control Protocol_ combines the
+connection-oriented state maintenance known from TCP with the
+unreliable, datagram-based transport of UDP. This means that it
+is capable of reacting to changes in the connection by performing
+congestion control, offering multiple alternative approaches. But it
+is bound to datagram boundaries (the maximum packet size supported
+by a medium), and like UDP it lacks retransmission to protect
+against loss. Due to the use of sequence numbers, it is however
+able to react to loss (interpreted as a congestion indication) and
+to ignore out-of-order and duplicate packets. Unlike TCP it allows
+to negotiate specific, binding features for a connection, such as
+the choice of congestion control: classic, window-based congestion
+control known from TCP is available as CCID-2, rate-based, "smooth"
+congestion control is offered as CCID-3.
+
+*HTTP*. _The Hypertext Transfer Protocol_ is an application layer
+protocol on top of TCP. It is spoken by web servers and is most often
+used for web services. However, as can be seen by the many Internet
+radio stations and YouTube/Flash videos, http is by far not limited to
+the delivery of web pages only. Being a simple request/response based
+protocol, the semantics of the protocol also allow the delivery of
+multimedia content, such as audio over http.
+
+*Multicast*. IP multicast is not really a protocol but a technique
+for one-to-many communication over an IP network. The challenge is to
+deliver information to a group of destinations simultaneously using
+the most efficient strategy to send the messages over each link of
+the network only once. This has benefits for streaming multimedia:
+the standard one-to-one unicast offered by TCP/DCCP means that
+n clients listening to the same stream also consume n-times the
+resources, whereas multicast requires to send the stream just once,
+irrespective of the number of receivers. Since it would be costly to
+maintain state for each listening receiver, multicast often implies
+connectionless transport, which is the reason that it is currently
+only available via UDP.
+
+License
+~~~~~~~
+
+Paraslash is licensed under the GPL, version 2. Most of the code
+base has been written from scratch, and those parts are GPL V2
+throughout. Notable exceptions are FEC and the WMA decoder. See the
+corresponding source files for licencing details for these parts. Some
+code sniplets of several other third party software packages have
+been incorporated into the paraslash sources, for example log message
+coloring was taken from the git sources. These third party software
+packages are all published under the GPL or some other license
+compatible to the GPL.
+
+Acknowledgements
+~~~~~~~~~~~~~~~~
+
+Many thanks to Gerrit Renker who read an early draft of this manual
+and contributed significant improvements.
+
+----------
+References
+----------
+
+Articles
+~~~~~~~~
+ - Reed, Irving S.; Solomon, Gustave (1960),
+ XREFERENCE(http://kom.aau.dk/~heb/kurser/NOTER/KOFA01.PDF,
+ Polynomial Codes over Certain Finite Fields), Journal of the
+ Society for Industrial and Applied Mathematics (SIAM) 8 (2):
+ 300-304, doi:10.1137/0108018)
+
+RFCs
+~~~~
+
+ - XREFERENCE(http://www.ietf.org/rfc/rfc768.txt, RFC 768) (1980):
+ User Datagram Protocol
+ - XREFERENCE(http://www.ietf.org/rfc/rfc791.txt, RFC 791) (1981):
+ Internet Protocol
+ - XREFERENCE(http://www.ietf.org/rfc/rfc2437.txt, RFC 2437) (1998):
+ RSA Cryptography Specifications
+ - XREFERENCE(http://www.ietf.org/rfc/rfc4340.txt, RFC 4340)
+ (2006): Datagram Congestion Control Protocol (DCCP)
+ - XREFERENCE(http://www.ietf.org/rfc/rfc4341.txt, RFC 4341) (2006):
+ 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)
+
+Application web pages
+~~~~~~~~~~~~~~~~~~~~~
+
+ - XREFERENCE(http://paraslash.systemlinux.org/, paraslash)
+ - XREFERENCE(http://xmms2.org/wiki/Main_Page, xmms)
+ - XREFERENCE(http://www.mpg123.de/, mpg123)
+ - XREFERENCE(http://gstreamer.freedesktop.org/, gstreamer)
+ - XREFERENCE(http://www.icecast.org/, icecast)
+ - XREFERENCE(http://beesbuzz.biz/code/audiocompress.php, Audio Compress)
+
+External documentation
+~~~~~~~~~~~~~~~~~~~~~~
+
+ - XREFERENCE(http://kernel.org/pub/linux/kernel/people/hpa/raid6.pdf,
+ H. Peter Anvin: The mathematics of Raid6)
+ - XREFERENCE(http://info.iet.unipi.it/~luigi/fec_ccr.ps.gz,
+ Luigi Rizzo: Effective Erasure Codes for reliable Computer
+ Communication Protocols)
+
+Code
+~~~~
+ - XREFERENCE(http://info.iet.unipi.it/~luigi/vdm.tar.gz,
+ Original FEC implementation by Luigi Rizzo)
+
projects / paraslash.git / commitdiff