The paraslash executables
-------------------------
-### para_server ###
+<h3> para_server </h3>
para_server streams binary audio data (MP3, ...) over local and/or
remote networks. It listens on a TCP port and accepts commands such
protocols based on HTTP, DCCP, or UDP. This is explained in the
section on [networking](#Networking).
-### para_client ###
+<h3> para_client </h3>
The client program to connect to para_server. paraslash commands
are sent to para_server and the response is dumped to STDOUT. This
session (shell) is started. Command history and command completion are
supported through libreadline.
-### para_audiod ###
+<h3> para_audiod </h3>
The purpose of para_audiod is to download, decode and play an audio
stream received from para_server. A typical setup looks as follows.
current audio file. Access to the local socket may be restricted by
means of Unix socket credentials.
-### para_audioc ###
+<h3> para_audioc </h3>
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. Like para_client, para_audioc supports
interactive sessions on systems with libreadline.
-### para_recv ###
+<h3> para_recv </h3>
A command line HTTP/DCCP/UDP stream grabber. The http mode is
compatible with arbitrary HTTP streaming sources (e.g. icecast).
first decoding it, and it enables third-party software which is unaware
of the particular audio format to send complete frames in real time.
-### para_filter ###
+<h3> para_filter </h3>
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
formats and a number of processing filters, among these a normalizer
for audio volume.
-### para_afh ###
+<h3> para_afh </h3>
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.
-### para_write ###
+<h3> para_write </h3>
A modular audio stream writer. It supports a simple file writer
output plug-in and optional WAV/raw players for ALSA (Linux) and OSS.
para_write can also be used as a stand-alone WAV or raw audio player.
-### para_play ###
+<h3> para_play </h3>
A command line audio player.
-### para_gui ###
+<h3> para_gui </h3>
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_mixer ###
+<h3> para_mixer </h3>
An alarm clock and volume-fader for OSS and ALSA.
Requirements
------------
-### For the impatient ###
+<h3> For the impatient </h3>
git clone git://git.tuebingen.mpg.de/lopsub
cd lopsub && make && sudo make install
libasound2-dev libao-dev libreadline-dev libncurses-dev \
libopus-dev
-### Detailed description ###
+<h3> Detailed description </h3>
In any case you will need
Configuration
-------------
-### Create a paraslash user ###
+<h3> Create a paraslash user </h3>
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
echo 'hostname server_host' > $conf
-### Start para_server ###
+<h3> Start para_server </h3>
For this first try, we'll use the info loglevel to make the output
of para_server more verbose.
to retrieve the list of available commands and some server info.
Don't proceed if this doesn't work.
-### Create and populate the database ###
+<h3> Create and populate the database </h3>
An empty database is created with
para_client ls
-### Configure para_audiod ###
+<h3> Configure para_audiod </h3>
We will have to tell para_audiod that it should receive the audio
stream from server_host via http:
All tables are described in more detail below.
-### The audio file table ###
+<h3> The audio file table </h3>
This is the most important and usually also the largest table of the
AFS database. It contains the information needed to stream each audio
and all files which are recognized as valid audio files are added to
the database.
-### The attribute table ###
+<h3> The attribute table </h3>
The attribute table contains two columns, _name_ and _bitnum_. An
attribute is simply a name for a certain bit number in the attribute
for more information and a complete list of command line options to
these commands.
-### Blob tables ###
+<h3> Blob tables </h3>
The image, lyrics, moods and playlists tables are all blob tables.
Blob tables consist of three columns each: The identifier which is
the playlist and the mood blobs are only investigated when the mood
or playlist is activated with the select command.
-### The score table ###
+<h3> The score table </h3>
The score table describes those audio files which are admissible for
the current mood or playlist (see below). The table has two columns:
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.
-### Playlists ###
+<h3> Playlists </h3>
Playlists are accommodated in the playlist table of the afs database,
using the aforementioned blob format for tables. A new playlist is
file could not be opened for streaming, its entry is removed from
the score table (but not from the playlist).
-### Moods ###
+<h3> Moods </h3>
A mood consists of a unique name and its *mood definition*, which is
a set of *mood lines* containing expressions in terms of attributes
-### List of mood_methods ###
+<h3> List of mood_methods </h3>
no_attributes_set
greater than 2000 plus the current year.
-### Mood usage ###
+<h3> Mood usage </h3>
To create a new mood called "my_mood", write its definition into
some temporary file, say "tmpfile", and add it to the mood table
para ls -a
-### Example mood definition ###
+<h3> Example mood definition </h3>
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
The following audio formats are supported by paraslash:
-### MP3 ###
+<h3> MP3 </h3>
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
stereo), encoded with a bit rate of 128 kbit, an MP3 frame is about
400 bytes large.
-### OGG/Vorbis ###
+<h3> OGG/Vorbis </h3>
OGG is a standardized audio container format, while Vorbis is an
open source codec for lossy audio compression. Since Vorbis is most
Vorbis codec creates variable-bitrate (VBR) data, where the bitrate
may vary considerably.
-### OGG/Speex ###
+<h3> OGG/Speex </h3>
Speex is an open-source speech codec that is based on CELP (Code
Excited Linear Prediction) coding. It is designed for voice
in OGG files. As of 2012 this codec is considered obsolete since the
Oppus codec, described below, surpasses its performance in all areas.
-### OGG/Opus ###
+<h3> OGG/Opus </h3>
Opus is a lossy audio compression format standardized through RFC
6716 in 2012. It combines the speech-oriented SILK codec and the
containers. All known software patents which cover Opus are licensed
under royalty-free terms.
-### AAC ###
+<h3> AAC </h3>
Advanced Audio Coding (AAC) is a standardized, lossy compression
and encoding scheme for digital audio which is the default audio
the container format and audio files encoded with AAC have the .m4a
extension. A typical AAC frame is about 700 bytes large.
-### WMA ###
+<h3> WMA </h3>
Windows Media Audio (WMA) is an audio data compression technology
developed by Microsoft. A WMA file is usually encapsulated in the
is composed of superframes, each containing one or more frames of
2048 samples. For 16 bit stereo a WMA superframe is about 8K large.
-### FLAC ###
+<h3> FLAC </h3>
The Free Lossless Audio Codec (FLAC) compresses audio without quality
loss. It gives better compression ratios than a general purpose
sample is multiplied with a scaling factor (>= 1) which makes amp
and compress quite expensive in terms of computing power.
-### amp ###
+<h3> amp </h3>
The amp filter amplifies the audio stream by a fixed scaling factor
that must be known in advance. For para_audiod this factor is derived
is used. The reader is encouraged to write a script that performs
these computations :)
-### compress ###
+<h3> compress </h3>
Unlike the amplification filter, the compress filter adjusts the volume
of the audio stream dynamically without prior knowledge about the peak
Network protocols
-----------------
-### IP ###
+<h3> IP </h3>
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 ###
+<h3> Connection-oriented and connectionless protocols </h3>
Connectionless protocols differ from connection-oriented ones in
that state associated with the sending/receiving endpoints is treated
that the sending endpoints perform congestion control, adapting to
qualitative changes of the connection medium.
-### Reliability ###
+<h3> Reliability </h3>
In IP networking, packets can be lost, duplicated, or delivered
out of order, and different network protocols handle these
delivery. Unreliable protocols, in contrast, do not guarantee ordering
or data integrity.
-### Classification ###
+<h3> Classification </h3>
With these definitions the protocols which are used by paraslash for
steaming audio data may be classified as follows.
Below we give a short descriptions of these protocols.
-### TCP ###
+<h3> TCP </h3>
The _Transmission Control Protocol_ provides reliable, ordered delivery
of a stream and a classic window-based congestion control. In contrast
Transfer Protocol), also FTP (the File Transfer protocol), SMTP (Simple
Mail Transfer Protocol), SSH (Secure Shell) all sit on top of TCP.
-### UDP ###
+<h3> UDP </h3>
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
congestion. Error checking and correction (if at all) are performed
in the application.
-### DCCP ###
+<h3> DCCP </h3>
The _Datagram Congestion Control Protocol_ combines the
connection-oriented state maintenance known from TCP with the
control known from TCP is available as CCID-2, rate-based, "smooth"
congestion control is offered as CCID-3.
-### HTTP ###
+<h3> HTTP </h3>
The _Hypertext Transfer Protocol_ is an application layer protocol
on top of TCP. It is spoken by web servers and is most often used
protocol, the semantics of the protocol also allow the delivery of
multimedia content, such as audio over http.
-### Multicast ###
+<h3> Multicast </h3>
IP multicast is not really a protocol but a technique for one-to-many
communication over an IP network. The challenge is to deliver
projects / paraslash.git / commitdiff