Introduction
============
-In this chapter we give an [overview](#Overview) of the interactions of
-the two main programs contained in the paraslash package, followed by
+In this chapter we give an [overview](#Overview) of the interactions
+of the programs contained in the paraslash package, followed by
[brief descriptions](#The.paraslash.executables) 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.
+applications, para_server and para_audiod. para_server maintains
+the audio file database and acts as the streaming source, while
+para_audiod is the streaming client. Usually, both run in the
+background on different hosts but a local setup is also possible.
A simplified picture of a typical setup is as follows
- server_host client_host
- ~~~~~~~~~~~ ~~~~~~~~~~~
- +-----------+ audio stream +-----------+
- |para_server| -----------------------------> |para_audiod|
- +-----------+ +-----------+
- ^ ^
- | |
- | | connect
- | |
- | |
- | +-----------+
- | |para_audioc|
- | +-----------+
- |
- |
- | connect +-----------+
- +-------------------------------------- |para_client|
- +-----------+
+ .____________________.
+ | ______ |
+ .-----------------------. | .d########b. |
+ |.---------------------.| | .d############b |
+ || || | .d######""####//b. |
+ || || | 9######( )######P |
+ || || | 'b######++######d' |
+ || Screen || | "9############P" |
+ || || | "9a########P" |
+ || || | `""""'' |
+ |`---------------------'| | ________________ |
+ `-----------------------' | |________________| |
+ ___) (___ |____________________|
+ `-._______.-' loudspeaker
+ | |
+ | |
+ | |
+ .____/ \___. ._____________. ._____/ \_____.
+ | | | | | |
+ | para_gui |-----| para_audioc |-----| para_audiod |
+ |____ ___| |_____________| |_____ _____|
+ \ / \ /
+ | |
+ | |
+ | |
+ ._____/ \_____. ._____/ \_____.
+ | | | |
+ | para_client |-----------------------| para_server |
+ |_____________| |_____ _____|
+ \ /
+ |
+ |
+ .-'"""`-.
+ ( )
+ |`-.___.-'|
+ | |
+ |. ' " ` .|
+ | |
+ `-.___.-'
+ Database
+
+The two client programs, para_client and para_audioc communicate with
+para_server and para_audiod, respectively.
+
+para_gui controls para_server and para_audiod by executing para_client
+and para_audioc. In particular, it runs a command to obtain the state
+of para_audiod and para_server, and the metadata of the current audio
+file. This information is pretty-printed in a curses window.
+
The paraslash executables
-------------------------
para_server streams binary audio data (MP3, ...) over local and/or
remote networks. It listens on a TCP port and accepts commands such
-as play, stop, pause, next from authenticated clients. There are
-many more commands though, see the man page of para_server for a
-description of all commands.
-
-It supports three built-in network streaming protocols
-(senders/receivers): HTTP, DCCP, or UDP. This is explained in more
-detail in the section on [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
+as play, stop, pause, next from authenticated clients. The components
+of para_server are illustrated in the following diagram:
+
+ ______________________________________________________________________ network
+ | | | | |
+ | .-'""""`-. | | | |
+ | ( ) | | | |
+ .____/ \_____. |`-.____.-'| .____/ \____/ \____/ \____. |
+ | | | | | | |
+ | dispatcher | | database | | senders (http/udp/dccp) | |
+ |____ _____| | | |___________ ___________| |
+ \ / |. ' "" ` .| \ / |
+ | | | | |
+ | `-.____.-' | |
+ | | | |
+ | | | |
+ | | | |
+ | ._____/ \_____. .________/ \________. |
+ | | | | | |
+ | | audio file |________| virtual streaming | |
+ | | selector | | system | |
+ | |_____ _____| |________ ________| |
+ | \ / \ / |
+ | | | |
+ | | | |
+ | | ._________________. | |
+ | | | | | |
+ | `---| command handler |---' |
+ | |____ ___ ____| |
+ | \ / \ / |
+ | | | |
+ | | | |
+ | | | |
+ `-------------------------' `--------------------------'
+
+
+Incoming connections arrive at the dispatcher which creates a process
+dedicated to the connection. Its task is to authenticate the client
+and to run the command handler which forwards the client request to
+either the audio file selector or the virtual streaming system. Results
+(if any) are sent back to the client.
+
+The audio file selector manages audio files using various database
+tables. It maintains statistics on the usage of all audio files such as
+last-played time and the number of times each file was selected. It
+is also responsible for selecting and loading audio files for
+streaming. 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.
-
+including information found in (ID3) tags. Simple playlists are also
+supported. It is possible to store images (album covers) and lyrics
+in the database and associate these to the corresponding audio files.
The section on the [audio file selector](#The.audio.file.selector)
-discusses this topic.
+discusses this topic in more detail.
+Another component of para_server is the virtual streaming system,
+which controls the paraslash senders. During streaming it requests
+small chunks of data (e.g., mp3 frames) from the audio file selector
+and feeds them to the senders which forward the chunks to connected
+clients.
+
+The three senders of para_server correspond to network streaming
+protocols based on HTTP, DCCP, or UDP. This is explained in the
+section on [networking](#Networking).
### para_client ###
### 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.
-
+The purpose of para_audiod is to download, decode and play an audio
+stream received from para_server. A typical setup looks as follows.
+
+
+ .----------------------------.
+ | |
+ | |
+ ._____/ \_____. .___/ \____.
+ | | .----------| |
+ | para_server | | .______| receiver |
+ |_____ ____| | | |___ ____|
+ \ / | | \ /
+ | | | |
+ | | | |
+ | | | |
+ ._____/ \_____. | | .___/ \____.
+ | | | | | |
+ | status task |-----+ | | filter 1 |
+ |_____________| | |___ ____|
+ | \ /
+ | | .____________________.
+ | | | ______ |
+ .____________. | .___/ \____. | .d########b. |
+ | | | | | | .d############b |
+ | dispatcher |----------' | filter 2 | | .d######""####//b. |
+ |_____ ____| |___ ____| | 9######( )######P |
+ \ / \ / | 'b######++######d' |
+ | | | "9############P" |
+ | | | "9a########P" |
+ ._____/ \_____. .___/ \____. | `""""'' |
+ | | | | | ________________ |
+ | para_audioc | | writer |------| |________________| |
+ |_____________| |__________| |____________________|
+
+
+The status task of para_audiod connects to para_server and runs the
+"stat" command to retrieve the current server status. If an audio
+stream is available, para_audiod starts a so-called buffer tree to
+play the stream.
+
+The buffer tree consists of a receiver, any number of filters and a
+writer. The receiver downloads the audio stream from para_server and
+the filters decode or modify the received data. The writer plays the
+decoded stream.
+
+The dispatcher of para_audiod listens on a local socket and runs
+audiod commands on behalf of para_audioc. For example, para_gui runs
+para_audioc to obtain status information about para_audiod and the
+current audio file. Access to the local socket may be restricted by
+means of Unix socket credentials.
### para_audioc ###
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.
+also with para_client via the command handler whenever an AFS command
+is executed, for example to answer a database query.
-Besides the traditional playlists, AFS supports audio file selection
+Besides the simple 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
+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 employs [libosl](http://people.tuebingen.mpg.de/maan/osl/), the
-object storage layer library, as the backend library for storing
-information on audio files, playlists, etc. This library offers
-functionality similar to a relational database, but is much more
-lightweight than a full database backend.
-
In this chapter we sketch the setup of the [AFS
process](#The.AFS.process) during server startup and proceed with the
description of the [layout](#Database.layout) of the various database
tables. The section on [playlists and moods](#Playlists.and.moods)
explains these two audio file selection mechanisms in detail
-and contains pratical examples. The way [file renames and content
+and contains practical examples. The way [file renames and content
changes](#File.renames.and.content.changes) are detected is discussed
briefly before the [Troubleshooting](#Troubleshooting) section
concludes the chapter.
---------------
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.
+the database tables. The AFS process accepts incoming connections
+which arrive either on a pipe which is shared with para_server,
+or on the local socket it is listening on. The setup is as follows.
+
+ .___________________. .______________.
+ | | | |
+ | virtual streaming | | audio format |
+ | system | | handler |
+ |_________ _______| |_____ ______|
+ \ / \ /
+ | |
+ .-'""""`-. | | .-'""""`-.
+ ( ) | | ( )
+ |`-.____.-'| .__/ \________________/ \___. |`-.____.-'|
+ | | | | | |
+ | file |----| AFS (audio file selector) |----| OSL |
+ | system | | process | | database |
+ | | |___________________________| | |
+ |. ' "" ` .| | |. ' "" ` .|
+ | | | | |
+ `-.____.-' | `-.____.-'
+ ._______/ \_______.
+ | |
+ | command handler |
+ |_______ _______|
+ \ /
+ |
+ |
+ |
+ ._____/ \_____.
+ | |
+ | para_client |
+ |_____________|
+
+The virtual streaming system, which is part of the server process,
+communicates with the AFS process via pipes and shared memory. When
+the current audio file changes, it sends a notification through the
+shared pipe. The AFS process queries the database to determine the
+next audio file, opens it, verifies that it has not been changed since
+it was added to the database and passes the open file descriptor back
+to the virtual streaming system, along with audio file meta-data such
+as file name, duration, audio format and so on. The virtual streaming
+system then starts to stream the file.
+
+The command handlers of all AFS server commands use the local socket
+to query or update the database. For example, the command handler of
+the add command sends the path of an audio file to the local socket.
+The AFS process opens the file and tries to find an audio format
+handler which recognizes the file. If all goes well, a new database
+entry with metadata obtained from the audio format handler is added
+to the database.
+
+Note that AFS employs
+[libosl](http://people.tuebingen.mpg.de/maan/osl/), the object
+storage layer library, as the database backend. This library offers
+functionality similar to a relational database, but is much more
+lightweight than a full featured database management system.
Database layout
---------------
+Metadata about the known audio files is stored in an OSL database. This
+database consists of the following tables:
+
+- The audio file table contains path, hash and metadata of each
+known file.
+
+- The "attributes" table maps each of the 64 possible attributes to a
+string.
+
+- The "blob" tables store images, lyrics, moods, playlists. All of
+these are optional.
+
+- The "score" table describes the subset of admissible files for the
+current playlist or mood.
+
+All tables are described in more detail below.
+
### The audio file table ###
This is the most important and usually also the largest table of the
projects / paraslash.git / blobdiff