--- /dev/null
+ NEWS
+ ====
+
+ ------------------------------------------
+ current master branch "cascading gradient"
+ ------------------------------------------
+
++The highlight of this release is the new -m flag for para_afh which
++lets it modify the meta tags of the given audio file(s). This feature
++is supported for all audio formats. Many small cleanups and bug fixes
++not mentioned here have accumulated and are also part of the release.
++
+ - para_afh learned to modify meta tags of mp3 wma ogg spx
+ opus flac aac files.
+ - afs commands propagate error codes to the client.
+ - The check command now also checks the attribute table for
+ inconsistencies.
+ - New -v flag for the version command (print verbose version string)
+ - New option --priority for para_server and para_audiod.
++- New mood methods: image_id and lyrics_id.
++- The manual and this NEWS file have been converted to markdown.
+
++Download: [tarball](./releases/paraslash-git.tar.bz2)
+
+ --------------------------------------
+ 0.5.5 (2015-09-20) "magnetic momentum"
+ --------------------------------------
+
+ Many new features and a lot of other improvements.
+
+ - On Linux systems, local sockets are now created in the
+ abstract name space by default. This allows to get rid of
+ the socket specials in /var/paraslash.
+ - The --user-allow option of para_audiod now accepts also
+ usernames rather than only user IDs.
+ - New autoconf macros to avoid duplication in configure.ac.
+ - Status items (as shown by para_gui) are updated correctly
+ when the meta information of the current audio changes.
+ - para_server and para_audiod no longer refuse to start in
+ the background if no log file is given. Instead, all log
+ messages go to /dev/null in this case.
+ - Web page cleanup.
+ - New syntax for the -l and -s options of the ls command.
+ These options should now be specified as -l=v rather than
+ -lv, for example. The old syntax still works, but support
+ will be dropped in v0.6.0.
+
+ Downloads:
+ [tarball](./releases/paraslash-0.5.5.tar.bz2),
+ [signature](./releases/paraslash-0.5.5.tar.bz2.asc)
+
+ ------------------------------------------
+ 0.5.4 (2015-01-23) "exponential alignment"
+ ------------------------------------------
+
+ Another cleanup and bugfix release.
+
+ - New server command: tasks.
+ - Minor cleanups to daemon.c.
+ - New URLs for home page and git services.
+ - Improved error diagnostics for the mvblob commands.
+ - New sender subcommand: status.
+ - Improved help text for server and afs commands.
+ - audiod memory leak fixes.
+ - Miscellaneous improvements to the build system.
+ - oss_writer improvements.
+ - Improved handling of mp3 files with both id3v1 and id3v2 tags.
+
+ Downloads:
+ [tarball](./releases/paraslash-0.5.4.tar.bz2),
+ [signature](./releases/paraslash-0.5.4.tar.bz2.asc)
+
+ ---------------------------------------------
+ 0.5.3 (2014-08-01) "symbolic synchronization"
+ ---------------------------------------------
+
+ Not many new features, but lots of fixes and usability improvements.
+
+ - para_gui has been converted to use the paraslash scheduler.
+ - Various alsa-related fixes, mostly for the raspberry pi.
+ - Many scheduler improvements and cleanups.
+ - The test suite has been extended to include sanity checks
+ for the generated man pages.
+ - ao_writer fixes. This writer was in a quite bad shape. Many
+ serious bugs have been fixed.
+ - new audiod command: version.
+ - Minor improvements to the bitstream API.
+ - The cpsi command now prints a meaningful error message if
+ none of the given patterns matched any audio file.
+
+ Downloads:
+ [tarball](./releases/paraslash-0.5.3.tar.bz2),
+ [signature](./releases/paraslash-0.5.3.tar.bz2.asc)
+
+ ----------------------------------------
+ 0.5.2 (2014-04-11) "orthogonal interior"
+ ----------------------------------------
+
+ The new sync filter, the AES_CTR128 stream cipher and the overhauled
+ network code are the highlights of this release. It also includes a
+ fair number of smaller fixes and improvements not mentioned here.
+
+ - The new sync filter synchronizes playback between multiple
+ clients.
+ - Connections between para_server and para_client are now
+ encrypted by means of AES rather than RC4 if both sides
+ support it. RC4 is still available as a fallback. This
+ feature is fully transparent, i.e. no command line options
+ are necessary, and a client linked against openssl can
+ speak with a server linked against libgcrypt and vice versa.
+ - Major cleanup of the networking subsystem.
+ - Improvements to para_fade: the new set mode, multi-channel
+ initial volumes, better error logging.
+ - The man pages of para_audiod, para_filter, para_recv, and
+ para_write contain the relevant options for receivers, filters,
+ writers. This broke in 0.5.0.
+ - ogg/vorbis latency improvements.
+ - Improved user manual.
+ - Minor fixes to avoid clang warnings.
+
+ Downloads:
+ [tarball](./releases/paraslash-0.5.2.tar.bz2),
+ [signature](./releases/paraslash-0.5.2.tar.bz2.asc)
+
+ ------------------------------------------
+ 0.5.1 (2013-12-20) "temporary implication"
+ ------------------------------------------
+
+ Lots of fixes and improvements all over the place, and a major overhaul
+ of the build system.
+
+ - Audiod improvements and fixes.
+ - Buffer tree robustness improvements.
+ - Cleanup of the mood subsystem.
+ - Fixes and cleanups for the flac decoder.
+ - Latency improvements for the ogg/opus decoder.
+ - Crypto support is now optional. On systems without
+ openssl/gcrypt, the build succeeds but para_server,
+ para_audiod, para_client won't be built.
+ - The build system now works for cross-compile setups.
+ - The dependency tree has been flattened, which speeds up
+ builds and avoids to recreate the man pages on every change.
+ - The error code helper has been rewritten from perl to C,
+ which further improves build time.
+ - Many small bugs in the build system have been identified
+ and fixed.
+
+ Downloads:
+ [tarball](./releases/paraslash-0.5.1.tar.bz2),
+ [signature](./releases/paraslash-0.5.1.tar.bz2.asc)
+
+ ----------------------------------------
+ 0.5.0 (2013-08-23) "invertible validity"
+ ----------------------------------------
+
+ Some API-breaking changes, one serious bug fix, and a lot of bike-shedding.
+
+ - The sideband compatibility code has been removed, hence
+ sideband connections (introduced in 0.4.11) are now mandatory.
+ - Addblob commands can produce output.
+ - The stat command no longer sends garbage when para_server was
+ compiled against libgcrypt.
+ - Dependencies for gengetopt files are computed automatically.
+ This eliminates a constant source of build bugs.
+ - The setatt command now accepts file name patterns rather than only
+ path names.
+ - overview.pdf is now based on dia, a simple diagram creation program.
+ The new version is much more detailed and contains descriptions of
+ the various programs of the paraslash package.
+ - The separator of all multi-word options has been changed from
+ underscore to dash. For example --log_color becomes --log-color.
+ - Overhauled web pages and the new logo.
+
+ Downloads:
+ [tarball](./releases/paraslash-0.5.0.tar.bz2),
+ [signature](./releases/paraslash-0.5.0.tar.bz2.asc)
+
+ --------------------------------------
+ 0.4.13 (2013-07-29) "spectral gravity"
+ --------------------------------------
+
+ One more 0.4.x release before the API-breaking changes for 0.5.0 go
+ in. The main features of this release are the ogg/opus audio format,
+ and UTF-8 support, but it includes also tons of other improvements
+ and fixes all over the place.
+
+ - New audio format: ogg/opus.
+ - UTF8 support for para_gui and the mp3 audio format handler.
+ - Scheduler improvements and fixes.
+ - The obsolete gettimeofday() function has been replaced
+ by clock_gettime() on systems which support it.
+ - Speed and usability improvements for para_gui.
+ - para_client now restores the fd flags of stdin and stdout
+ on shutdown.
+ - Improved manual pages.
+ - Consistent version strings for all executables.
+ - Reduced dependencies on generated files result in fewer
+ recompilations on changes.
+ - Performance improvements for the compress filter.
+ - Improved downloads web page.
+
+ -----------------------------------------
+ 0.4.12 (2012-12-20) "volatile relativity"
+ -----------------------------------------
+ The new command line player, the resample filter, ALSA support for
+ para_fade, and the improved build system are the highlights of this
+ release which probably marks the end of the 0.4.x series.
+
+ - The afh receiver and the para_play executable.
+ - The resample filter: A sample rate converter based on
+ libsamplerate.
+ - The "versions" directory has been removed from the master
+ branch. The tarballs of the old releases are now available
+ in the new "releases" branch.
+ - Overhaul of the build system: All generated files are now
+ written to the "build" directory.
+ - The modular mixer API and the alsa mixer.
+ - Minor fixes for the osx writer.
+
+ --------------------------------------
+ 0.4.11 (2012-07-20) "mutual diversity"
+ --------------------------------------
+
+ The major feature in this release is the new sideband API for
+ client-server communication. This API will be used exclusively starting
+ with 0.5.0, which breaks backward compatibility but allows to get rid
+ of quite some compatibility code. Other noteworthy changes include
+ decoder latency improvements and a long-standing bug fix for the
+ ALSA writer.
+
+ - Sideband connections: If both para_server and para_client
+ support this feature, data is sent as a multiplexed stream.
+ - The --no_default_filters option of para_filter has been
+ removed.
+ - Several fixes and latency improvements to various decoders.
+ - The ALSA writer now limits the prebuffer time to 500ms.
+ - Documentation improvements.
+ - Overhaul of the command_util.sh script.
+ - Fixes for some minor problems found by the clang analyzer.
+ - Compiles (almost) without warnings on gcc-3.
+ - Robustness improvements of the buffer tree code.
+
+ ------------------------------------------
+ 0.4.10 (2012-03-30) "heterogeneous vacuum"
+ ------------------------------------------
+
+ Nothing earth-shaking in this release, but quite a few usability
+ improvements and the usual mix of cleanups and fixes.
+
+ - The --no_default_filters option of para_filter has been
+ deprecated. It still works but has no effect and will be
+ removed in the next version.
+ - para_gui now prints also the stderr output of the executing
+ command in the bottom window.
+ - Cleanup and consolidation of the various wrappers for
+ write(), writev(), send() and friends.
+ - The obscure error messages on mmap() failures have been
+ replaced by meaningful messages. This affects mainly
+ para_afh.
+ - para_audioc: Cleanups and memory leak fixes.
+ - Test 0004-server no longer fails if para_server is not
+ being built.
+ - New configure options: --with-id3tag-{headers,libs}.
+
+ -------------------------------------
+ 0.4.9 (2011-12-06) "hybrid causality"
+ -------------------------------------
+
+ Support for another audio format, interactive mode for para_client
+ and para_audiod and many small improvements/fixes all over the place.
+
+ - Support for flac, the free lossless audio codec.
+ - Fix for an endless loop in the mp3 decoder for certain
+ (corrupt) mp3 files.
+ - When executed without specifying a command, para_client
+ and para_audioc start an interactive shell (requires
+ libreadline being installed). The interactive mode offers
+ full tab completion and command line history.
+ - autogen.sh now detects a distcc setup and adjusts the
+ parameter for the -j option of make accordingly.
+ - Shared memory areas are no longer restricted to 64K. We now
+ detect the maximal size of a shared memory area at runtime.
+ - cleanup of the internal uptime API.
+ - para_server prefaults the mmapped audio file to avoid
+ delays on slow media.
+ - A new test for the test-suite that exercises the
+ communication between para_server and para_audiod.
+ - The alsa writer eats up less CPU cycles when configured to
+ use the DMIX plugin.
+ - Simplified and unified receiver code.
+ - Makefile cleanups.
+ - Commands which print a list of matching audio files now
+ emit a meaningful error message if no audio file matched the
+ given pattern(s).
+
+ --------------------------------------
+ 0.4.8 (2011-08-19) "nested assignment"
+ --------------------------------------
+
+ Gcrypt support, the overhauled osx writer and regex format specifiers
+ are the highlights of this release.
+
+ - support for libgcrypt as a drop-in replacement for openssl.
+ Run configure --enable-cryptolib=gcrypt to link against
+ libgcrypt. The two crypto implementations are compatible to
+ each other, i.e. a para_client executable linked against
+ gcrypt can connect to para_server linked against libssl
+ and vice versa.
+ - Rewrite of the osx writer (output plugin for Mac OS).
+ - audiod: The format specifier for receivers, filters and
+ writers is now treated as a regular expression. This allows
+ to replace 5 lines in the config file (one for each audio
+ format) by one single line. See the manual for details.
+ - The \*.cmdline.[ch] files are no longer contained in the released
+ tarballs. This reduces the size of the tarballs but requires
+ gengetopt to build the tarball.
+ - Compiles cleanly also with llvm/clang.
+ - Corrupt mp3 files are handled more gracefully.
+ - The alsa writer uses poll fds instead of computing timeouts.
+ - Cleanup of the generic writer API.
+ - sched: Optimized zero timeouts.
+ - vss timeout cleanups.
+ - oggdec fixes and improvements.
+
+ --------------------------------------
+ 0.4.7 (2011-06-01) "infinite rollback"
+ --------------------------------------
+
+ The new ao writer, support for ssh RSA keys and a couple of other
+ enhancements.
+
+ - Support for ESD, Pulseaudio, AIX, Solaris, IRIX and other
+ platforms through the libao audio library.
+ - Support for RSA keys generated with ssh-keygen.
+ - configure: improved options for ogg/vorbis/speex.
+ - The git version reported by --version always matches HEAD.
+ - The autogen script detects the number of processors and
+ runs a parallel make if possible.
+ - Major cleanup of the crypto API.
+ - Documentation updates.
+
+ ------------------------------------------
+ 0.4.6 (2011-03-31) "deterministic entropy"
+ ------------------------------------------
+
+ Lots of ogg/vorbis improvements, the new test suite, enhancements
+ for para_gui and a fair amount of other bug fixes.
+
+ - For DCCP/OGG streams the audio file header is only sent once
+ at the beginning of the stream rather than periodically
+ every five seconds. This reduces network traffic and the
+ FEC group size.
+ - The vorbis comment header is replaced by an empty dummy header
+ before the header is sent over the network. This also results in
+ less network traffic and smaller FEC groups.
+ - The new "test" make target allows to perform some sanity checks prior
+ to installing the package.
+ - ogg timing fixes and performance improvements
+ - Scheduler improvements
+ - Proper exit codes for para_write
+ - para_gui: New option --theme to select a startup theme. Several
+ other improvements and fixes.
+ - aacdec error message cleanups
+ - simplified color error handling
+
+ --------------------------------------------
+ 0.4.5 (2010-12-17) "symmetric randomization"
+ --------------------------------------------
+
+ Bug fixes, internal cleanups and variable-sized FEC slices.
+
+ - Contains a fix for an invalid-free-bug in the ogg audio format
+ handler code.
+ - Switching off the DCCP sender works again.
+ - para_audiod handles crashes of para_server more robustly.
+ - Internal scheduler and writer cleanups.
+ - Reduced latency due to variable-sized FEC slices.
+ - Improved documentation and error diagnostics.
+ - The build of para_server is now optional, allowing the build
+ to succeed in case libosl is not installed.
+
+ ------------------------------------------
+ 0.4.4 (2010-08-06) "persistent regularity"
+ ------------------------------------------
+
+ Support for yet another audio format, para_write improvements and
+ bug fixes.
+
+ - Support for the speex codec.
+ - Support for sample formats other than 16 bit little endian.
+ - error2.h is now created by a perl script which speeds up configure
+ considerably.
+ - Fix a bug in the aac decoder which could lead to segfaults in
+ para_filter/para_audiod.
+ - Fixes for autoconf-2.66.
+
+ ----------------------------------------
+ 0.4.3 (2010-07-05) "imaginary radiation"
+ ----------------------------------------
+
+ Many improvements for the DCCP and the UDP transport, the new user
+ manual and the usual mix of bug fixes and internal improvements.
+
+ - FEC support for the DCCP sender (Gerrit Renker). The new
+ --dccp_max_slice_size, --dccp_data_slices_per_group and
+ --dccp_slices_per_group options can be used to set the FEC
+ parameters for the DCCP transport.
+ - DNS lookups for UDP targets (Gerrit Renker).
+ - The new user manual replaces the README, README.afs, REQUIREMENTS
+ and INSTALL documents.
+ - Fix an end-of-file detection bug in the oggdec filter.
+ - The new nonblock API.
+ - Both options of the oggdec filter have been removed.
+ - New debug mode for the internal scheduler.
+
+ ------------------------------------------
+ 0.4.2 (2010-04-23) "associative expansion"
+ ------------------------------------------
+
+ It's been some time since the last release, but finally here is
+ paraslash-0.4.2. The bulk of the changes comes from the new buffer
+ tree API, but there are changes all over the tree. Mainly performance
+ and usability improvements, but also quite some bug fixes.
+
+ - The new buffer tree API.
+ - DCCP: Support for CCID negotiation (Gerrit Renker).
+ - UDP robustness fixes.
+ - The --bufsize option for mp3dec is gone as it no longer makes sense
+ for the new buffer tree API.
+ - Fix audible buffer underruns for wma streams.
+ - The alsa writer no longer prints meaningless underrun durations.
+ - audiod: Defaults work also for udp streams. If no filter is
+ given for an audio format that is received via upd, fecdec is
+ automatically added as the first filter (along with the decoder).
+
+ ---------------------------------------
+ 0.4.1 (2009-12-22) "concurrent horizon"
+ ---------------------------------------
+
+ Support for another audio format, minor feature enhancements and lots of bug
+ fixes. All fixes that have been accumulated in the maint branch (in particular
+ those mentionened in the 0.3.6 release notes) appear in this release as well.
+
+ - wma support.
+ - new afh option: --human to activate human-readable output.
+ - new server/audiod option: --log-timing to print timing information.
+ - build system improvements.
+ - source code documentation updates.
+
+ -------------------------------------
+ 0.3.6 (2009-12-07) "cubic continuity"
+ -------------------------------------
+
+ Quite a few bugs have been found and fixed since 0.3.5, so here's
+ another 0.3.x release. No new features.
+
+ - Always check return value of malloc().
+ - ogg vorbis/FEC: Do not write garbage after the audio file header.
+ - exit if root privileges could not be dropped.
+ - FEC: Fix computation of extra slices.
+ - oss: Fix check for empty input buffer.
+ - Avoid buffer underruns due to filter chain output buffer constraints.
+ - server: Fix assignment of afs_pid.
+ - Don't panic if the afs database contains unknown audio formats.
+ - http/dccp: Do not send the audio file header twice.
+ - FEC: Timing improvements.
+
+ ----------------------------------------------
+ 0.4.0 (2009-11-10) "simultaneous independence"
+ ----------------------------------------------
+
+ Two significant changes which require the new version number: The
+ improved authentication dialog and the fact that the database code
+ has been moved to a library, libosl. To use the new version, you have
+ to generate new RSA keys, see INSTALL for details. A shell script is
+ provided for conversion of the 0.3 database to the new 0.4 format.
+
+ - stronger crypto for client authentication
+ - the database code has been moved to a library
+ - improved status item handling
+ - cleanup of the build system
+ - The "-V" option now also prints the git version
+ - the new parser-friendly listing mode for the ls and stat commands
+ - mandatory rc4 encryption
+ - major audio format handler cleanups
+ - (id3,...) tags are no longer stored as a combined string in the database
+ - new mood methods: artist_matches, title_matches, comment_matches,
+ album_matches, year_maches, year.
+
+ --------------------------------------------
+ 0.3.5 (2009-09-21) "symplectic separability"
+ --------------------------------------------
+
+ Full client support for \*BSD Unixes, complete re-write of the ogg
+ vorbis audio format handler, various improvements all over the place
+ and the usual mix of bugfixes. This release marks the end of the 0.3
+ series if no serious problems show up.
+
+ - the new oss writer (supported on \*BSD and Linux)
+ - rewrite of the ogg vorbis audio format handler. It's
+ recommended to replace the chunk tables of existing ogg
+ vorbis files in the afs database by re-adding these files
+ with "add -f".
+ - support for netmask subsets (Gerrit Renker)
+ - the new prebuffer filter
+ - improved signal handling
+ - variable fec output buffer size
+ - improved FEC timing fixes audible buffer underruns in UDP mode
+ - --log_color actually works
+ - new ls option: -d (print dates as seconds after the epoch)
+ - update to gengetopt 2.22.2
+ - support for RSA keys of size > 512 bits
+ - new option "mixer_channel" for para_fade
+
+ -----------------------------------------
+ 0.3.4 (2009-05-07) "elliptic inheritance"
+ -----------------------------------------
+
+ The new udp sender, forward error correction, colored logs and various
+ other improvements. As the udp sender does not depend on any special
+ libraries, it is built unconditionally.
+
+ - The udp sender replaces the ortp sender. The new code uses forward
+ error correction to protect against packet losses. Many thanks to
+ Gerrit Renker for providing ipv6 support.
+ - The default port for udp streaming now defaults to 8000, like
+ for the http and the dccp senders/receivers.
+ - Loglevels are now specified as symbolic names, e.g.
+ "--loglevel info".
+ - improved ipv4 and ipv6 URI parser (Gerrit Renker).
+ - para_server/para_audiod: Color support for log messages.
+ - new options for mp3dec: --ignore-crc, --bufsize
+ - new audiod option: --config-file.
+ - gengetopt cleanups.
+ - Improved help/man pages: The documentation of para_audiod,
+ para_recv, para_filter and para_write now also contains
+ all options of the available receivers/filters/writers. The
+ man page of para_fade contains a description of the different
+ modes of operation.
+ - More source code documentation.
+ - vss timing fixes.
+
+ --------------------------------------------
+ 0.3.3 (2008-12-01) "axiomatic perspectivity"
+ --------------------------------------------
+
+ Internal code cleanups, bug fixes, improved tag handling and the new
+ amplification filter.
+
+ - para_server uses the generic scheduling code.
+ - overhaul of the virtual streaming system.
+ - mp3: id3 version 2 support via libid3tag (optional)
+ - ogg: vorbis comment support.
+ - aac meta info support.
+ - mp3 audio format handler cleanups.
+ - new filter: "amp" to amplify the amplitude of the audio stream
+ - new status item/database entry: amplification. It is
+ used by the amp filter to pre-amplify the audio stream.
+ - fix a close-without-open bug in para_write.
+ - fix a bug in com_init() which was introduced in 0.3.2.
+ - better error diagnostics for para_client.
+
+ -----------------------------------------
+ 0.3.2 (2008-04-11) "probabilistic parity"
+ -----------------------------------------
+
+ The new para_afh executable, scheduling and documentation improvements.
+
+ - new ls option: -lc (list chunk table)
+ - new executable: para_afh, the stand-alone audio file handler tool
+ - afs commands can send output more than SHMMAX (32MB on Linux). This
+ also reduces the memory usage of commands that produce large amounts
+ of output.
+ - major scheduler and audiod cleanups.
+ - more detailed and much nicer man pages.
+
+ ---------------------------------------
+ 0.3.1 (2008-02-23) "liquid interaction"
+ ---------------------------------------
+
+ A mix of cleanups, bug fixes, improvements, and some new features. No
+ significant changes to the new database (osl) code, which is generally
+ a good sign.
+
+ - Share some similar/duplicate code between the http and the
+ dccp sender.
+ - Generic access control lists for paraslash senders.
+ - dccp sender: Access control lists, connection limiting and support
+ for the allow,deny,on,off,help sender commands.
+ - The default dccp port changed from 5001 to 8000 (suggested by
+ Gerrit Renker).
+ - para_server starts even if not all public keys could be loaded.
+ - Audiod performance improvements.
+ - fix a bug in the "off" command of the http sender.
+ - fix some fd and memory leaks.
+ - Update to gengetopt-2.22.
+
+ -------------------------------------
+ 0.3.0 (2008-01-12) "solar saturation"
+ -------------------------------------
+
+ paraslash.0.3.0 -- 'WWDBND --what would databases never do?'.
+
+
+ Usually one might expect lots of new features AND a big increase in size
+ for a major release like this.
+
+ However, paraslash-0.3.0.tar.bz2 is the smallest paraslash tarball
+ ever. The decrease in size is mostly due to the removal of some
+ graphical tools (which were only quick hacks anyway). But also the
+ fact that the mysql code is gone cuts down the size a bit.
+
+ Being independent of mysql comes at a cost: The fact that paraslash
+ now contains its own database (the object storage layer, osl) increases
+ the (stripped) binary size of para_server by ~50K on i386.
+
+ - no more restrictions on unique basenames.
+ - independent of mysql: The new self-contained object
+ storage layer (osl) replaces the mysql database.
+ - New executable para_fsck: Check integrity of osl tables.
+ - Lyrics support.
+ - Reliable audio file move/rename detection.
+ - More portable than ever: Tested on Linux (x86_32, x86_64, sparc64),
+ MacOS (ppc32, x86_32), FreeBSD (x86_32), NetBSD (x86_32) and
+ Solaris (sparc64).
+ - the new osl-based audio file selector (afs) replaces the random,
+ the playlist and the mysql selector of paraslash-0.2.x.
+ - IPv6 support (thanks to Gerrit Renker).
+ - paraslash-0.2.x streams are now called "moods". Writing
+ 0.3.x-mood definitions should be both easier and more
+ powerful than writing 0.2.x-stream definitions.
+ - para_krell, para_slider, para_para_sdl_gui, para_dbadm have
+ been removed. The world is a better place without them. However,
+ para_gui is still there.
+ - afs tracks audio file selection also in playlist mode.
+ - few easy-to-use afs commands replace the many not-so-easy-to-use
+ mysql commands (and are available also in playlist mode).
+ - Improved error subsystem.
+ - The earth-shaking new logo.
+
+ -----------------------------------------
+ 0.2.17 (2007-11-20) "isotropic threshold"
+ -----------------------------------------
+
+ Mainly bugfixes and cleanups in this version which marks the end of
+ the 0.2.x series if no serious bugs show up after the release.
+
+ - mysql_selector: fix a locking bug.
+ - universal chunk queueing.
+ - dccp sender uses chunk queueing if write() returns EAGAIN (thanks
+ to Gerrit Renker).
+ - be more carful wrt. signed vs. unsigned argument passing.
+ - cleanup error.h and fix some references to invalid error
+ codes.
+ - update to gengetopt-2.21.
+ - update to ortp-0.13.1.
+ - autoconf: extend checks for headers, library functions and
+ compiler characteristics.
+ - Fix streaming of large mp3 files.
+ - Fix an off-by-one bug in playlist handling.
+
+ --------------------------------------
+ 0.2.16 (2007-04-05) "neural discharge"
+ --------------------------------------
+
+ The main change in this release is the major audio format handler
+ cleanup which removes some similar/duplicate code and makes it easier
+ to implement plugins for other audio formats. Of course, the usual mix
+ of other improvements/changes/bugfixes also made it into the release.
+
+ - simplified audio format handlers (most of the handling functions
+ were moved one layer up to the virtual streaming system).
+ - para_server uses mmap to read audio files
+ - repositioning of mp3 streams is much faster, in particular for
+ jumping near the end of large mp3 files.
+ - permission flags DB_READ,DB_WRITE have been renamed to AFS_READ
+ and AFS_WRITE.
+ - fix a bug in para_filter that caused decoding of aac files
+ to start only after a few seconds.
+ - fix osx_writer hangs
+ - simplified dccp code (thanks to Gerrit Renker)
+ - the compress filter works also on big endian systems (ppc)
+
+ -----------------------------------------
+ 0.2.15 (2007-02-16) "inductive resonance"
+ -----------------------------------------
+
+ Minor improvements, more documentation and a bunch of bug fixes.
+
+ - para_server: The server.users file is only read once on server
+ startup rather than for each connection
+ - mp3dec: Fix decoding of corrupt mp3 files
+ - afs (audio file sender) is now called vss (virtual streaming
+ system). Consequently, the permission flags specified in
+ ~/.paraslash/server.users have also changed: AFS_READ and AFS_WRITE
+ become VSS_READ and VSS_WRITE respectively.
+ - para_audiod/para_filter: Fix a bug that caused the last chunk
+ of audio data not being written under certain circumstances
+ - audiod: compute the difference of server time and local time
+ correctly
+ - para_server/para_audiod: Fix some memory leaks
+ - documentation improvements
+ - configure.ac: fix checks for para_krell
+ - new man pages
+
+ -------------------------------------------
+ 0.2.14 (2006-10-15) "transient singularity"
+ -------------------------------------------
+
+ The only major enhancement of this version is the osx writer which completes
+ the Mac OS Port and was originally planned already for 0.2.13 but had to wait
+ until now for reasons beyond the scope of this changelog entry.
+
+ - new output plugin for Mac Os: the osx writer
+ - rename configure command line options from --enable-xxx-headers to
+ --with-xxx-headers and --enable-xxx-libs to --with-xxx-libs
+ - configure: new command line options: --with-mad-headers,
+ --with-mad-libs, --with-oggvorbis-headers, and --with-oggvorbis-libs
+ - some robustness fixes
+ - dymamic audio format recognition for audiod
+ - para_server: new command line option: --autoplay_delay
+ - para_audiod: new command line option: --clock_diff_count
+
+ ---------------------------------------
+ 0.2.13 (2006-07-14) "sonic convolution"
+ ---------------------------------------
+
+ A bunch of new features and core changes.
+
+ - the new paraslash scheduler, short and sweet.
+ - Support for m4a/mp4 files via the new aac audio format
+ handler/filter (requires libfaad).
+ - each writer has its own command line parser, just like
+ para_recv and para_filter.
+ - para_client and para_audioc use the error subsystem
+ - writers are integrated in para_audiod (currently linux-only)
+ - para_client is integrated in para_audiod
+ - random/playlist selector: improved info strings
+ - new audiod commands: tasks, kill
+ - update to libortp-0.10.1
+ - para_fade: wake time defaults to 8 hours from now
+ - update to autoconf-2.60
+
+ ------------------------------------------
+ 0.2.12 (2006-05-12) "oriented abstraction"
+ ------------------------------------------
+
+ Many user-visible changes in this release and lots of new
+ features:
+
+ - the new optional dccp sender/receiver. It uses the datagram
+ congestion control protocol. You'll need a fairly new kernel
+ for this.
+ - paraslash works on Mac OS X (thanks to Gerd Becker)
+ - para_play renamed to para_write
+ - modular output plugin design (writers) for para_write
+ - new file_writer output plugin for para_write
+ - compress filter speed improvements
+ - update to libortp-0.9.1
+ - update to gengetopt-2.17rc
+ - para_client no longer depends on libreadline (as the
+ code for the interactive mode was removed).
+ - gcc-2-95 is no longer a supported compiler. It may still
+ work, but it gets no more testing.
+ - the tarball no longer contains the screenshot images which
+ reduces its size quite a bit.
+ - configure: new command line options: --enable-mysql-headers
+ and --enable-mysql-libs
+
+ ------------------------------------
+ 0.2.11 (2006-03-11) "atomic duality"
+ ------------------------------------
+
+ Here it is, the first paraslash release developed with git. There
+ are fairly many user-visible changes in this release. As two out of
+ the three "database tools" of paraslash don't use a database at all,
+ they are now called "audio file selectors" instead.
+
+ - the cdt command (change database tool) becomes chs (change
+ selector)
+ - no more colon separators: The syntax of some options of
+ para_audiod and para_filter have changed. Use --help for
+ more info (and some examples).
+ - update to gengetopt-2.16 (thanks to Lorenzo Bettini)
+ - switch from cvs to git (should've done that earlier)
+ - the new ipc subsystem
+ - new audio file selector: playlist
+ - para_server: the dopey selector is now called "random",
+ and is the default selector. Use the --selector option to
+ choose another selector at startup, or the chs command to
+ change the selector at runtime.
+ - X86_64 fixes (thanks to Steffen Klassert)
+ - para_play fixes
+
+ --------------------------------------
+ 0.2.10 (2006-02-17) "cyclic attractor"
+ --------------------------------------
+
+ Huge documentation update, a scrollable window for para_gui, ortp
+ improvements, and of course many small fixes not mentioned here.
+ The diffstat below is rather misleading as most insertions are due
+ to the new source documentation.
+
+ - autoconf cleanup
+ - para_server also uses the new error subsystem
+ - lots of new documentation (UTSL)
+ - gui improvements:
+ - keysyms for cursor keys and for next/previous page keys
+ - scrollable output window
+ - new internal commands: scroll up/down, page up/down
+ - fix color of command output.
+ - ortp: the --chunk_time and --header flags are no longer needed
+ for para_recv/para_audiod as this information is now encoded in
+ each rtp packet sent by para_server.
+
+ -------------------------------------------
+ 0.2.9 (2006-01-24) "progressive turbulence"
+ -------------------------------------------
+
+ Internal audiod receivers/filters, the new error subsystem and
+ a lot of small improvements.
+
+ - para_recv and para_filter are integrated into the para_audiod
+ binary, i.e. audiod no longer spawns a new process for
+ each receiver/filter. As para_recv and para_filter might be
+ useful as standalone programs, they still get built (linked
+ against the same object files that are also used for audiod).
+ - further ortp timing improvements should reduce the CPU usage
+ of the ortp receiver.
+ - improved audio grabbing. The 'grab' command of para_audiod
+ has its own set of command line options. Read the output of
+ "para_audioc help grab" for more info.
+ - oggdec: configurable input prebuffer size.
+ - the new error subsystem gives better error diagnostics
+ and reduces code size.
+
+ -----------------------------------------
+ 0.2.8 (2006-01-02) "dynamic accumulation"
+ -----------------------------------------
+
+ The new modular filter design and the para_play-hangs bugfix.
+
+ - new executable: para_filter. It combines para_mp3dec,
+ para_oggdec and para_compress. It also adds a further filter
+ type, wav, that just inserts a wave header at the desired point
+ of the filter chain. All 'piping' is done in-memory (i.e. no
+ read/write operations are used).
+ - para_play: fix a stupid bug that caused it to hang under
+ certain circumstances.
+
+ -------------------------------------------
+ 0.2.7 (2006-12-27) "transparent invariance"
+ -------------------------------------------
+
+ Not many user-visible changes but a fair amount of internal improvements.
+
+ - The http sender buffers data if it can not be sent
+ out immediately (because the socket is not writable). This
+ should prevent para_server from shutting down the connection
+ too early on a loaded network.
+ - para_play also prebuffers data if it is told to start at a
+ future time by the --start_time option.
+ - The return of para_recv: It combines para_ortp_recv and
+ para_http_recv. Use the --receiver option to switch between
+ the two. para_recv builds without libortp, but contains
+ only the http receiver in this case.
+ - update to ortp 0.8.1. As this ortp release contains incompatible
+ changes, para_recv-0.2.7 won't link against older ortp libs.
+ - improved ortp timings.
+ - use of gcc-extensions that #define away for non-gcc and
+ gcc < 3.0.
+
+ -------------------------------------------
+ 0.2.6 (2005-10-29) "recursive compensation"
+ -------------------------------------------
+
+ Transparent session encryption (uses openssl's Alleged RC4 cipher),
+ the internal find command and several other improvements and cleanups.
+
+ - Encrypt the session if encryption is requested by the client
+ (default for para_client 0.2.6). This is backwards
+ compatible, so older clients can still connect to para_server
+ 0.2.6. Use the new client option --plain to request an
+ uncrypted session (off by default, must be set to on in
+ order to connect to para_server 0.2.x with 0 <= x <= 5).
+ - para_server uses an internal function to locate audio files
+ rather than calling find(1). The server option
+ --mysql_audio_file_dir replaces --mysql_find_cmd.
+ - documentation update
+ - man pages
+ - header file cleanup
+ - para_client code cleanup
+ - para_gui: faster display of output of display commands
+
+ ------------------------------------------
+ 0.2.5 (2005-10-13) "aggressive resolution"
+ ------------------------------------------
+
+ This release adds internal senders, i.e. no more external programs are
+ spawned for sending out the audio data. There are two different senders
+ available: The http sender and the ortp sender (former para_send which
+ is no longer needed).
+
+ The new sender code has a plugin-like design so it can be easily
+ extended should there be be any future need for supporting another
+ network streaming protocol. All senders are completely independent of
+ each other. In particular, the http and the ortp sender can operate
+ in parallel.
+
+ - new server command: sender to control senders at runtime.
+ Read the output of "para_server -h" and "para_client help
+ sender" for more information.
+ - para_recv renamed to para_ortp_recv
+ - new executable: para_http_recv, a simple command line
+ http receiver.
+ - major afs/mp3/ogg code simplifications due to internal
+ senders.
+ - ogg timing improvements
+ - fix several minor memory leaks (found by valgrind)
+ - empty stream definitions work again
+ - com_ne(): ignore errors on remove
+ - audiod: fix segfault on server restart
+
+ ---------------------------------------
+ 0.2.4 (2005-09-21) "toxic anticipation"
+ ---------------------------------------
+
+ Several small improvements, fixes and the new grab command.
+
+ - audiod:
+ - new command: "grab" to grab the output of the stream reader
+ or any filters. Read the output of "para_audioc help grab"
+ for more information.
+ - fix memory leak
+ - code cleanup
+ - audioc: new command line option: --bufsize to specify a
+ buffer size different from the default size 8192.
+ - improved error diagnostics for para_play.
+ - new configure option: --enable-ssldir so search for openssl in
+ non-standard places
+ - sdl_gui: Make it look nice again for 1024x768
+ - server: report total size of memory allocated with sbrk by malloc,
+ new command line option: --announce_time
+
+ -----------------------------------------
+ 0.2.3 (2005-09-01) "hydrophilic movement"
+ -----------------------------------------
+
+ Two new executables and major feature enhancements.
+
+ - audiod filters: It is now possible to specify arbitrary many
+ (including none) filters for each supported audio
+ format. This can be used e.g. for normalizing volume,
+ transforming or grabbing the audio stream, or for using
+ visualizers. Read the output of "para_audiod -h" for the
+ syntax of the new --filter_cmd option.
+ - new executable: para_play, a tiny alsa player. It
+ can play wave files or raw pcm (16 bit little endian)
+ from stdin.
+ - new executable: para_compress, a dynamic range compressor
+ intended to keep audio output at a consistent volume. Derived
+ from [AudioCompress](http://trikuare.cx/code/AudioCompress.html).
+ - audiod: New option: --stream_delay. This can be used in
+ a local network to syncronize the audio output of all
+ clients that play the same stream.
+
+ ------------------------------------------
+ 0.2.2 (2005-08-19) "tangential excitation"
+ ------------------------------------------
+
+ Mostly internal changes in this release, but also some new commands
+ for the mysql database tool.
+
+ - cleanup exec.c, fix para_exec bug
+ - compile time loglevel (log messages below the given level
+ won't be compiled in, which reduces the size of the
+ resulting binaries)
+ - new log macros that shorten the size of the source code.
+ - workaround a gcc-4.1 bug (?) that caused send_cred_buffer()
+ to send only zeros. With this workaround, para_audioc works
+ again.
+ - avoid gcc-4 warning: conflicting types for built-in function 'clog'
+ - new mysql commands: "rm" (remove entry), "mv" (rename entry) "ne"
+ (new entry), "snp" (set numplayed). Read the manual for more
+ information.
+
+ ---------------------------------------
+ 0.2.1 (2005-08-15) "surreal experience"
+ ---------------------------------------
+
+ Here comes paraslash-0.2.1. It contains a couple of new features and,
+ surprise, only minor bug fixes.
+
+ - kill noisy mp3 debug message
+ - cleanup of the build system
+ - para_server and para_client directly use the crypto routines
+ of the openssl library rather than invoking the openssl command
+ line utitlity
+ - server/audiod: new option --user to switch to the given user
+ when invoked as root. Read the output of "para_server -h" for
+ more information.
+ - gui/sdl_gui: new option --stat_cmd to be used to retrieve the
+ status. Default: "para_audioc stat"
+ - sdl_gui: new option --pic_cmd to be used to download the picture.
+ Default: "para_client pic"
+ - audiod: 5 slots ought to be enough for everybody
+ - audiod: new status item: Uptime, kill hup command
+
+ ------------------------------------------
+ 0.2.0 (2005-08-06) "distributed diffusion"
+ ------------------------------------------
+
+ After several month of increased development activity, paraslash-0.2.0
+ has arrived. It contains many new features and is much more
+ self-contained than the old 0.1.x series. Enjoy!
+
+ - para_server: fix hang on song change and crash on sighup.
+ Speed up mysql queries. The DIR_LIKE macro is gone.
+ - new executables: para_audiod, the local audio daemon that
+ starts playback (uses SCM_CREDENTIALS socket magic) and
+ para_audioc, the corresponding client.
+ - new executables: para_mp3dec/para_oggdec, two really teensy
+ decoders. para_mp3dec is based on libmad, para_oggdec requires
+ libvorbisfile.
+ - ovsend/ovrecv are capable of streaming ogg as well as mp3, so
+ they are now called para_send and para_recv respectively.
+ - documentation updates
+ - para_gui is themable. For now there is the default theme that
+ looks as before and the simple theme: blue and easy.
+ - gui: audio streaming is now handled by audiod. Time display shows
+ playback time rather than streaming time
+ - slider: update to libzmw-0.2.0
+ - para_krell: fix crash on server shutdown
+ - switch from gzip to bzip2
+
+ ----------------------------------------
+ 0.1.7 (2005-04-18) "melting penetration"
+ ----------------------------------------
+
+ The main change in this release is clearly the oggvorbis rewrite,
+ but there are also lots of smaller changes. If you intend to use both
+ the mp3 and the ogg plugin, it is recommended to use software mixing,
+ e.g. the dmix plugin which is provided by ALSA.
+
+ - new executables: para_ovsend and para_ovrecv for sending/receiving
+ oggvorbis files via rtp. Requires the open rtp library. Get it at
+ http://www.linphone.org/ortp/
+ - rewrite of the ogg_vorbis core code
+ - configure detects libzmw and, if detected, includes
+ para_slider to the list of binaries to be built by make
+ - server stream writers read from their associated fifo rather
+ than from stdin
+ - slider: two new sliders, lastplayed and numplayed
+ - fix nasty double free bug which caused random segfaults in case of
+ mp3 files with invalid header information
+ - gui: new command line option: --stream_timeout=seconds to
+ deactivate a slot if it is idle for that many seconds (default=`5')
+ - diffstats
+
+ ---------------------------------------
+ 0.1.6 (2005-03-05) "asymptotic balance"
+ ---------------------------------------
+
+ Only little user-visible changes in this release. Mainly bugfixes and
+ core code cleanup. This is probably the most stable version ever if you
+ stick to mp3...
+
+ - fix several memory leaks
+ - rename default name of mysql database from "music" to "paraslash".
+ Use para_server's --mysql_database option if you do not want to
+ rename your old database.
+ - rework ogg vorbis code
+ - make update command work on mysql servers with LOCAL_INFILE
+ disabled
+ - gui: improved stream I/O (slots)
+ - simplified audio format API
+ - para_pob_ogg is gone
+
+ ------------------------------------
+ 0.1.5 (2004-12-31) "opaque eternity"
+ ------------------------------------
+
+ Let's slide gently into the new year.
+
+ - new: para_slider (not built automatically, type "make
+ para_slider" to build). A toy for those who always felt that
+ creating stream definitions is difficult. See screenshots,
+ README and FEATURES for more info.
+ - improved signal handling. Fixes server segfault on SIGHUP
+ for linux kernels newer than Aug 24 2004 and makes para_gui
+ race-free.
+ - reload database tool on SIGHUP
+ - improved help message for sl
+ - do not log "broken pipe" messages as errors. They are
+ perfectly ok.
+ - fix wrong error message on permission errors
+
+ -----------------------------------------
+ 0.1.4 (2004-12-19) "tunneling transition"
+ -----------------------------------------
+
+ Bugfix release. As expected, 0.1.3 introduced a bunch of new bugs.
+ Hopefully, most of them got wiped out with this release. Some
+ enhancements went also in.
+
+ - improved error diagnostics for all commands
+ - stradd/picadd: overwrite previous contents if entry already
+ exists, rather than returning errors
+ - stradd: use current stream if invoked without args
+ - faster (and hopefully more stable) ogg-vorbis handling
+ - para_krell: reap children to avoid zombie-flooding in case
+ no server is running
+ - si: report also server pid
+ - server: don't busy-loop if dbtool reports only invalid files.
+ - gui: CTRL+C works again, fix stream_read command line option
+ - fix pic_add, hist
+ - fix mysql dbtool startup in case no database exists
+ - many small fixes and cleanups
+
+ ---------------------------------------
+ 0.1.3: (2004-12-10) "vanishing inertia"
+ ---------------------------------------
+
+ Starting from this release, the database tools are integrated in the
+ server binary. This decreases server startup time, reduces code size
+ and speeds up database commands. However, the layout of the underlying
+ mysql database changed only slightly and 0.1.3 should be backwards
+ compatible in that respect.
+
+ Visible changes:
+
+ - If mysql is not detected at compile time, or fails to init
+ at runtime, fall back to the dopey database tool which should
+ always work.
+ - para_dbtool and dbtool.conf are gone. All mysql specific
+ options are read from server.conf and are prefixed by 'mysql_'.
+ - new command: cdt (change database tool)
+ - new command line option: dbtool (choose startup database tool)
+ - The name of current stream is now stored in the database,
+ so paraslash remembers its current stream when restarted.
+ - new command: csp (change stream and play)
+ - para_gui also reports current database tool and server uptime
+
+ -------------------------------------------
+ 0.1.2: (2004-11-28) "spherical fluctuation"
+ -------------------------------------------
+
+ Point release before the big dbtool changes go in.
+
+ - dbtool: rename ca to cam (copy all meta data). It now also
+ copies numplayed and lastplayed time as well as the picture
+ id.
+ - fix endless-loop-bug caused by mp3 files with invalid header
+
+ -----------------------------------------
+ 0.1.1: (2004-11-05) "floating atmosphere"
+ -----------------------------------------
+
+ - gkrellm plugin
+ - new dbtool command: mbox. Browse your sound-file collection
+ with your favorite mail reader.
+ - several small fixes
+
+ -------------------------------------
+ 0.1.0: (2004-10-22) "rotating cortex"
+ -------------------------------------
+
+ - fix logging bug for loglevel > VERBOSE
+ - fix skip command
+ - correct timings for vbr mp3s
+ - modular audio format support
+ - ogg-vorbis support (experimental)
+ - new server option: autoplay
+
+ -----------------------------------------
+ 0.0.99: (2004-07-25) "harmonic deviation"
+ -----------------------------------------
+
+ - rename projectname from icc to paraslash (play, archive, rate
+ and stream large audio sets happily)
+ - paraslash is no longer restricted to one particular audio
+ streaming software
+ - new dbtool commands (stradd, strq, strdel) for easy stream
+ managment w/o configuration file. That obsoletes stream_defs
+ file/config option for dbtool.
+ - picadd accepts jpeg data from stdin
+ - new server commands: ps (select previous stream), sc (song change)
+ - new default pictures for sdl_gui
+ - gui: new key_map option for binding commands and internal
+ functions to arbitrary keys, nice help screen, rip out
+ soundcard/linux specific stuff, avoid noise artefacts while jumping,
+ show silly logo on startup
+ - new executables: para_fade for fading volume, para_dbadm for
+ manipulating attributes
+ - cdb adds _all_ tables to mysql database
+ - revised and beautified documentation
+ - sample dbtool rewritten in C
+ - autoconf
+
+ ---------------------------------------------
+ 0.0.98: (2003-12-26) "incremental smoothness"
+ ---------------------------------------------
+
+ - kick icecast in favour of poc. That removes some races and reduces
+ core code considerably.
+ - cbr/vbr is displayed by stat and gui/sdl_gui. New status flags
+ give finer info on afs' status.
+ - gui can start decoder (see config options). Further new gui
+ commands: refresh (^L), jmp (F1-F10)
+ - gui rereads conf on SIGUSR1 instead of SIGHUP. SIGHUP
+ terminates gui. This fixes dead instances consuming memory
+ continuously.
+ - new dbtool command: verb for sending verbatim sql queries.
+ - fix pid_list races (by removing pid_list)
+ - codename funnies
+
+ --------------------
+ 0.0.97: (2003-10-26)
+ --------------------
+
+ - installation prefix now defaults to /usr/local
+ - new commands for gui: snozze, sleep and reread config
+ - config file for gui and sdl_gui
+ - fix problems with filenames containing funny characters
+ (reported by Thomas Forell)
+ - improved signal handling for gui, now it rereads conf on SIGHUP
+ - new dbtool command: cdb (create database)
+ - switch from argtable to gengetopt
+ - major code cleanup and speed improvements
+ - fix several potential buffer overflows
+ - many small fixes and cleanups
+
+ -------------------
+ 0.0.96 (2003-08-30)
+ -------------------
+
+ - easy stream_defs syntax
+ - sdl_gui can display images associated to the file being played
+ - Major feature enhancements for icc_gui including dynamic text
+ placement and the top/bottom window design
+ - vrfy/clean now also checks for NULL values in attributes as
+ well as for invalid picture pointers
+ - fix long outstanding case sensitivity bug
+ - many small fixes and cleanups
+
+ -------------------
+ 0.0.95 (2003-06-29)
+ -------------------
+
+ - sdl gui runs much faster
+ - new dbtool command: ca (copy attributes)
+ - count and display number of times the song has been played
+ - new feature: scoring
+ - command line options for sdl_gui
+ - simpler syntax of streams file
+ - decrease network traffic of stat
+ - fix zombie bug
+ - many small fixes and cleanups
+
+ -------------------
+ 0.0.94 (2003-05-04)
+ -------------------
+
+ - new server command: ns (next stream)
+ - new icc_gui command: c (change stream)
+ - internal mp3info
+ - stat shows also id3 tag info
+ - new sdl based gui
+ - log flodding bug fixed
+ - many small fixes and cleanups
+
+ -------------------
+ 0.0.93 (2003-03-28)
+ -------------------
+
+ - colors for icc_gui
+ - icc_gui sets volume directly (linux only)
+ - proper locking that fixes some races
+ - fix security bug that caused commands to be executed even
+ with unsufficient permissions
+ - new command: hup to make all servers reread their configuration file
+ - icecast meta data streaming
+ - many small fixes and cleanups
--- /dev/null
- libfaad-dev libspeex-dev libFLAC-dev libsamplerate-dev \
+ **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 [overview](#Overview) of the interactions of
+ the two main 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.
+
+ 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|
+ +-----------+
+ The paraslash executables
+ -------------------------
+
+ ### para_server ###
+
+ 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
+ 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 [audio file selector](#The.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 session key. For each user of paraslash you must
+ create a public/secret RSA key pair for authentication.
+
+ If para_client is started without non-option arguments, an interactive
+ session (shell) is started. Command history and command completion are
+ supported through libreadline.
+
+ ### para_audiod ###
+
+ 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. Like para_client, para_audioc supports
+ interactive sessions on systems with libreadline.
+
+ ### para_recv ###
+
+ A command line HTTP/DCCP/UDP stream grabber. The http mode is
+ compatible with arbitrary HTTP streaming sources (e.g. icecast).
+ In addition to the three network streaming modes, para_recv can also
+ operate in local (afh) mode. In this mode it writes the content of
+ an audio file on the local file system in complete chunks to stdout,
+ optionally 'just in time'. This allows to cut an audio file without
+ first decoding it, and it enables third-party software which is unaware
+ of the particular audio format to send complete frames in real time.
+
+ ### para_filter ###
+
+ 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 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.
+
+ ### 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_play ###
+
+ A command line 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 alarm clock and volume-fader for OSS and ALSA.
+
+ ===========
+ Quick start
+ ===========
+
+ This chapter lists the [necessary software](#Requirements)
+ that must be installed to compile the paraslash package, describes
+ how to [compile and install](#Installation) the paraslash
+ source code and the steps that have to be performed in order to
+ [set up](#Configuration) a typical server and client.
+
+ Requirements
+ ------------
+ ### For the impatient ###
+
+ git clone git://git.tuebingen.mpg.de/osl
+ cd osl && make && sudo make install && sudo ldconfig
+ sudo apt-get install autoconf libssl-dev help2man gengetopt \
+ libmad0-dev libid3tag0-dev libasound2-dev libvorbis-dev \
-[clang](http://clang.llvm.org). All gcc versions >= 3.3 are currently
++ libfaad-dev libspeex-dev libFLAC-dev libsamplerate-dev realpath \
+ libasound2-dev libao-dev libreadline-dev libncurses-dev \
+ libopus-dev
+
+ ### Detailed description ###
+
+ In any case you will need
+
+ - [libosl](http://people.tuebingen.mpg.de/maan/osl/). 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
+
+ - [gcc](ftp://ftp.gnu.org/pub/gnu/gcc) or
-(value of the year tag, bitrate in kbit/s, frequency in Hz, channel
-count, play count).
++[clang](http://clang.llvm.org). All gcc versions >= 4.2 are currently
+ supported. Clang version 1.1 or newer should work as well.
+
+ - [gnu make](ftp://ftp.gnu.org/pub/gnu/make) is also shipped with the
+ disto. On BSD systems the gnu make executable is often called gmake.
+
+ - [bash](ftp://ftp.gnu.org/pub/gnu/bash). Some scripts which run
+ during compilation require the _Bourne again shell_. It is most
+ likely already installed.
+
+ - [gengetopt](ftp://ftp.gnu.org/pub/gnu/gengetopt/) is needed to
+ generate the C code for the command line parsers of all paraslash
+ executables.
+
+ - [help2man](ftp://ftp.gnu.org/pub/gnu/help2man) is used to create
+ the man pages.
+
+ Optional:
+
+ - [openssl](http://www.openssl.org/) or
+ [libgcrypt](ftp://ftp.gnupg.org/gcrypt/libgcrypt/). At least one
+ of these two libraries is needed as the backend for cryptographic
+ routines on both the server and the client side. Both openssl and
+ libgcrypt are usually shipped with the distro, but you might have
+ to install the development package (`libssl-dev` or `libgcrypt-dev`
+ on debian systems) as well.
+
+ - [libmad](http://www.underbit.com/products/mad/). 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.
+
+ - [libid3tag](http://www.underbit.com/products/mad/). For version-2
+ ID3 tag support, you willl need the libid3tag development package
+ `libid3tag0-dev`. Without libid3tag, only version-1 tags are
+ recognized. The mp3 tagger also needs this library for modifying
+ (id3v1 and id3v2) tags.
+
+ - [ogg vorbis](http://www.xiph.org/downloads/). For ogg vorbis streams
+ you need libogg, libvorbis, libvorbisfile. The corresponding Debian
+ packages are called `libogg-dev` and `libvorbis-dev`.
+
+ - [libfaad](http://www.audiocoding.com/). For aac files (m4a) you
+ need libfaad (`libfaad-dev`).
+
+ - [speex](http://www.speex.org/). In order to stream or decode speex
+ files, libspeex (`libspeex-dev`) is required.
+
+ - [flac](http://flac.sourceforge.net/). To stream or decode files
+ encoded with the _Free Lossless Audio Codec_, libFLAC (`libFLAC-dev`)
+ must be installed.
+
+ - [libsamplerate](http://www.mega-nerd.com/SRC/index.html). The
+ resample filter will only be compiled if this library is
+ installed. Debian package: `libsamplerate-dev`.
+
+ - [alsa-lib](ftp://ftp.alsa-project.org/pub/lib/). On Linux, you will
+ need to have the ALSA development package `libasound2-dev` installed.
+
+ - [libao](http://downloads.xiph.org/releases/ao/). Needed to build
+ the ao writer (ESD, PulseAudio,...). Debian package: `libao-dev`.
+
+ - [curses](ftp://ftp.gnu.org/pub/gnu/ncurses). Needed for
+ para_gui. Debian package: `libncurses-dev`.
+
+ - [GNU
+ Readline](http://cnswww.cns.cwru.edu/php/chet/readline/rltop.html). If
+ this library (`libreadline-dev`) is installed, para_client, para_audioc
+ and para_play support interactive sessions.
+
+ Installation
+ ------------
+ To build the sources from a tarball, execute
+
+ ./configure && make
+
+ To build from git or a gitweb snapshot, run this command instead:
+
+ ./autogen.sh
+
+ 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 (optionally)
+
+ make test
+
+ to run the paraslash test suite. If all tests pass, execute as root
+
+ make install
+
+ to install executables under /usr/local/bin and the man pages under
+ /usr/local/man.
+
+ Configuration
+ -------------
+
+ ### 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/id_rsa.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
+
+ ssh-keygen -q -t rsa -b 2048 -N '' -f $key
+
+ This generates the two files id_rsa and id_rsa.pub in ~/.ssh. Note
+ that para_server won't accept keys shorter than 2048 bits. Moreover,
+ para_client rejects private keys which are world-readable.
+
+ para_server only needs to know the public key of the key pair just
+ created. Copy this public key to server_host:
+
+ src=~/.ssh/id_rsa.pub
+ dest=.paraslash/id_rsa.pub.$LOGNAME
+ scp $src foo@server_host:$dest
+
+ Finally, tell para_client to connect to server_host:
+
+ conf=~/.paraslash/client.conf
+ echo 'hostname server_host' > $conf
+
+
+ ### Start para_server ###
+
+ 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.
+
+ ### 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
+
+ ### Configure para_audiod ###
+
+ We will have to tell para_audiod that it should receive the audio
+ stream from server_host via http:
+
+ para_audiod -l info -r '.:http -i server_host'
+
+ 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 [audio file selector](#The.audio.file.selector) for how
+ to use playlists and moods to specify which files should be streamed
+ in which order.
+
+ Troubleshooting
+ ---------------
+
+ If you receive a socket related error on server or audiod startup,
+ make sure you have write permissions to the /var/paraslash directory:
+
+ sudo chown $LOGNAME /var/paraslash
+
+ Alternatively, use the --afs-socket (para_server) or --socket
+ (para_audiod) option to specify a different socket pathname.
+
+ To identify streaming problems try to receive, decode and play the
+ stream manually using para_recv, para_filter and para_write as follows.
+ For simplicity we assume that you're running Linux/ALSA and that only
+ MP3 files have been added to the database.
+
+ 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
+ a stream cipher, either RC4 or AES in integer counter mode.
+
+ In this chapter we briefly describe RSA, RC4 and AES, and sketch the
+ [authentication handshake](#Client-server.authentication)
+ between para_client and para_server. User management is discussed
+ in the section on [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 [separate section](#Connecting.para_audiod).
+
+ RSA, RC4, AES
+ -------------
+
+ 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 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.
+
+ AES, the advanced encryption standard, is a well-known symmetric block
+ cipher, i.e. a transformation operating on fixed-length blocks which
+ is determined by a single key for both encryption and decryption. Any
+ block cipher can be turned into a stream cipher by generating
+ a pseudo-random key stream by encrypting successive values of a
+ counter. The AES_CTR128 stream cipher used in paraslash is obtained
+ in this way from the AES block cipher with a 128 bit block size.
+
+ 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 TCP port 2990 of the
+ server host. This port is called the para_server _control port_.
+
+ - para_server accepts the connection and forks a child process which
+ handles the incoming request. 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 session key.
+
+ - para_client receives the encrypted buffer and decrypts it with 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 stream cipher with
+ the session key known to both peers.
+
+ paraslash relies on the quality of the pseudo-random bytes provided
+ by the crypto library (openssl or libgcrypt), on the security of the
+ implementation of the RSA, RC4 and AES 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
+ [Quick start](#Quick.start) and discussed in more detail
+ [below](#The.user_list.file).
+
+ The user_list file
+ ------------------
+
+ At startup para_server reads the user list file which contains 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.
+
+ 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 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
+ changes](#File.renames.and.content.changes) are detected is discussed
+ briefly before the [Troubleshooting](#Troubleshooting) section
+ 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, ...).
+
+ - 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 this pattern:
+
+ para_client setatt test+ '/test/directory/*'
+
+ The command
+
+ para_client -- ls -l=v
+
+ 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 with 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
+ mood or playlist. Audio files are chosen for streaming from the rows
+ of the score table on a highest-score-first basis.
+
+
+ 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.
+
+ ### Playlists ###
+
+ Playlists are accommodated in the playlist table of the afs database,
+ using the aforementioned blob format for tables. A new playlist is
+ created with the addpl command by specifying the full (absolute)
+ paths of all desired audio files, separated by newlines. 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>
++ image_id ~ <num>
++ lyrics_id ~ <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
-- [alternative page](http://paraslash.systemlinux.org/)
++(value of the year tag, bitrate in kbit/s, etc.).
+
+ 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 is 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 (-l debug) to show debugging info. All paraslash
+ executables have a brief online help which is displayed when -h is
+ given. 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:
+
+ oslfsck -fd ~/.paraslash/afs_database-0.4
+
+ However, make sure para_server isn't running before executing oslfsck.
+
+ 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.
+
+ Similarly, para_audiod refuses to start if its socket file exists, since
+ this indicates that another instance of para_audiod is running. After
+ a crash a stale socket file might remain and you must run
+
+ para_audiod --force
+
+ once to fix it up.
+
+ =======================================
+ 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.
+
+ ### OGG/Speex ###
+
+ Speex is an open-source speech codec that is based on CELP (Code
+ Excited Linear Prediction) coding. It is designed for voice
+ over IP applications, has modest complexity and a small memory
+ footprint. Wideband and narrowband (telephone quality) speech are
+ supported. As for Vorbis audio, Speex bit-streams are often stored
+ 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 ###
+
+ Opus is a lossy audio compression format standardized through RFC
+ 6716 in 2012. It combines the speech-oriented SILK codec and the
+ low-latency CELT (Constrained Energy Lapped Transform) codec. Like
+ OGG/Vorbis and OGG/Speex, Opus data is usually encapsulated in OGG
+ containers. All known software patents which cover Opus are licensed
+ under royalty-free terms.
+
+ ### 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.
+
+ ### FLAC ###
+
+ The Free Lossless Audio Codec (FLAC) compresses audio without quality
+ loss. It gives better compression ratios than a general purpose
+ compressor like zip or bzip2 because FLAC is designed specifically
+ for audio. A FLAC-encoded file consists of frames of varying size, up
+ to 16K. Each frame starts with a header that contains all information
+ necessary to decode the frame.
+
+ Meta data
+ ---------
+
+ 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, ogg speex and flac files contain meta data as Vorbis
+ comments, which are typically implemented as strings of the form
+ "[TAG]=[VALUE]". Unlike ID3 version 1 tags, one may use whichever
+ tags are appropriate for the content.
+
+ AAC files usually use the MPEG-4 container format for storing meta
+ data while WMA files wrap meta data as special objects within the
+ 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 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 16K (FLAC).
+
+ The chunk table contains the offsets within the audio file that
+ correspond to the chunk boundaries of the file. Like the meta data,
+ 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 prints the technical data, the chunk table
+ and the meta data of a file. Moreover, all audio format handlers are
+ combined in the afh receiver which is part of para_recv and para_play.
+
+ ==========
+ 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 [control
+ service](#The.paraslash.control.service), followed by a section
+ on the various [streaming protocols](#Streaming.protocols)
+ in which the data connections are described. The way
+ audio file headers are embedded into the stream is discussed
+ [briefly](#Streams.with.headers.and.headerless.streams) before the
+ [example section](#Networking.examples) 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 [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.
+
+ server_host client_host
+ ~~~~~~~~~~~ ~~~~~~~~~~~
+
+ +-----------+ connect +-----------+
+ |para_server|<------------------------------ |para_client|
+ +-----------+ +-----------+
+ | ^
+ | fork +---+ |
+ +----------> |AFS| |
+ | +---+ |
+ | ^ |
+ | | |
+ | | connect (cookie) |
+ | | |
+ | | |
+ | fork +-----+ inherited connection |
+ +---------->|child|<--------------------------+
+ +-----+
+
+ 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, the server sends
+ a special "awaiting data" packet for these commands. If the client
+ receives this packet, it sends STDIN to the server, otherwise it
+ dumps data from the server to STDOUT.
+
+ Streaming protocols
+ -------------------
+
+ 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 [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
+ [FEC](#Forward.error.correction) below.
+
+ Streams with headers and headerless streams
+ -------------------------------------------
+
+ For OGG/Vorbis, OGG/Speex and wma streams, some of the information
+ needed to decode the stream is only contained in the audio file
+ header of the container format but not in each data chunk. 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.
+
+ Networking examples
+ -------------------
+
+ The "si" (server info) command lists some information about the
+ currently running server process.
+
+ -> Show PIDs, number of connected clients, uptime, and more:
+
+ para_client si
+
+ The sender command of para_server prints information about senders,
+ like the various access control lists, and it allows to (de-)activate
+ senders and to change the access permissions at runtime.
+
+ -> List all senders
+
+ para_client sender
+
+ -> Obtain general help for the sender command:
+
+ para_client help sender
+
+ -> Get help for a specific sender (contains further examples):
+
+ s=http # or dccp or udp
+ para_client sender $s help
+
+ -> Show status of the http sender
+
+ para_client sender http status
+
+ By default para_server activates both the HTTP and th DCCP sender on
+ startup. This can be changed via command line options or para_server's
+ config file.
+
+ -> 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
+ echo receiver \".:http -i $s\" > $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 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 can
+ be used as the prefix for the filter option. Example:
+
+ para_audiod -f 'mp3:prebuffer --duration 300'
+
+ The "mp3" prefix above is actually interpreted as a POSIX extended
+ regular expression. Therefore
+
+ para_audiod -f '.:prebuffer --duration 300'
+
+ activates the prebuffer filter for all supported audio formats (because
+ "." matches all audio formats) while
+
+ para_audiod -f 'wma|ogg:prebuffer --duration 300'
+
+ activates it only for wma and ogg streams.
+
+ 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 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
+ executables. For example, the mp3dec filter depends on the mad library.
+
+ Forward error correction
+ ------------------------
+
+ As already mentioned [earlier](#Streaming.protocols), paraslash
+ uses forward error correction (FEC) for the unreliable UDP and
+ DCCP transports. 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 reordering 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 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 audio data from STDIN. If
+ this data starts with a wav header, sample rate, sample format and
+ channel count are read from the header. Otherwise CD audio (44.1KHz
+ 16 bit little endian, 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.
+
+ - *AO*. _Libao_ is a cross-platform audio library which supports a wide
+ variety of platforms including PulseAudio (gnome), ESD (Enlightened
+ Sound Daemon), AIX, Solaris and IRIX. The ao writer plays audio
+ through an output plugin of libao.
+
+ 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.
+
+ - [git](http://git.or.cz/). As described in more detail
+ [below](#Git.branches), the git source code management tool is used for
+ paraslash development. It is necessary for cloning the git repository
+ and for getting updates.
+
+ - [m4](ftp://ftp.gnu.org/pub/gnu/m4/). Some input files for gengetopt
+ are generated from templates by the m4 macro processor.
+
+ - [autoconf](ftp://ftp.gnu.org/pub/gnu/autoconf/) GNU autoconf creates
+ the configure file which is shipped in the tarballs but has to be
+ generated when compiling from git.
+
+ - [discount](http://www.pell.portland.or.us/~orc/Code/discount). The
+ HTML version of this manual and some of the paraslash web pages are
+ written in the Markdown markup language and are translated into html
+ with the converter of the *Discount* package.
+
+ - [doxygen](http://www.stack.nl/~dimitri/doxygen/). The documentation
+ of paraslash's C sources uses the doxygen documentation system. The
+ conventions for documenting the source code is described in the
+ [Doxygen section](#Doxygen).
+
+ - [global](ftp://ftp.gnu.org/pub/gnu/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.
+
+ However, at times "next" will be rebuilt from the tip of "master" to
+ get rid of merge commits that will never be in "master". The commit
+ that replaces "next" will usually have the identical tree, but it
+ will have different ancestry from the tip of "master".
+
+ 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 [there](http://www.kernel.org/doc/Documentation/CodingStyle),
+ 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 API reference on the paraslash web page is generated
+ by doxygen.
+
+ It is more illustrative to look at the source code for examples than
+ to describe the conventions 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 doxygen 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.
+
+ Abstract socket namespace
+ -------------------------
+ UNIX domain sockets are a traditional way to communicate between
+ processes on the same machine. They are always reliable (see above)
+ and don't reorder datagrams. Unlike TCP and UDP, UNIX domain sockets
+ support passing open file descriptors or process credentials to
+ other processes.
+
+ The usual way to set up a UNIX domain socket (as obtained from
+ socket(2)) for listening is to first bind the socket to a file system
+ pathname and then call listen(2), then accept(2). Such sockets are
+ called _pathname sockets_ because bind(2) creates a special socket
+ file at the specified path. Pathname sockets allow unrelated processes
+ to communicate with the listening process by binding to the same path
+ and calling connect(2).
+
+ There are two problems with pathname sockets:
+
+ * The listing process must be able to (safely) create the
+ socket special in a directory which is also accessible to
+ the connecting process.
+
+ * After an unclean shutdown of the listening process, a stale
+ socket special may reside on the file system.
+
+ The abstract socket namespace is a non-portable Linux feature which
+ avoids these problems. Abstract sockets are still bound to a name,
+ but the name has no connection with file system pathnames.
+
+ License
+ -------
+
+ 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
+ --------
+ - [Polynomial Codes over Certain Finite
+ Fields](http://kom.aau.dk/~heb/kurser/NOTER/KOFA01.PDF) by Reed, Irving
+ S.; Solomon, Gustave (1960), Journal of the Society for Industrial
+ and Applied Mathematics (SIAM) 8 (2): 300-304, doi:10.1137/0108018)
+
+ RFCs
+ ----
+
+ - [RFC 768](http://www.ietf.org/rfc/rfc768.txt) (1980): User Datagram
+ Protocol
+
+ - [RFC 791](http://www.ietf.org/rfc/rfc791.txt) (1981): Internet
+ Protocol
+
+ - [RFC 2437](http://www.ietf.org/rfc/rfc2437.txt) (1998): RSA
+ Cryptography Specifications
+
+ - [RFC 4340](http://www.ietf.org/rfc/rfc4340.txt) (2006): Datagram
+ Congestion Control Protocol (DCCP)
+
+ - [RFC 4341](http://www.ietf.org/rfc/rfc4341.txt) (2006): Congestion
+ Control ID 2: TCP-like Congestion Control
+
+ - [RFC 4342](http://www.ietf.org/rfc/rfc4342.txt) (2006): Congestion
+ Control ID 3: TCP-Friendly Rate Control (TFRC)
+
+ - [RFC 6716](http://www.ietf.org/rfc/rfc6716.txt) (2012): Definition
+ of the Opus Audio Codec
+
+ Application web pages
+ ---------------------
+
+ - [paraslash](http://people.tuebingen.mpg.de/maan/paraslash/)
+ - [xmms](http://xmms2.org/wiki/Main_Page)
+ - [mpg123](http://www.mpg123.de/)
+ - [gstreamer](http://gstreamer.freedesktop.org/)
+ - [icecast](http://www.icecast.org/)
+ - [Audio Compress](http://beesbuzz.biz/code/audiocompress.php)
+
+ External documentation
+ ----------------------
+
+ - [The mathematics of
+ Raid6](http://kernel.org/pub/linux/kernel/people/hpa/raid6.pdf)
+ by H. Peter Anvin
+
+ - [Effective Erasure Codes for reliable Computer Communication
+ Protocols](http://info.iet.unipi.it/~luigi/fec_ccr.ps.gz) by Luigi
+ Rizzo
+
+ Code
+ ----
+ - [Original FEC
+ implementation](http://info.iet.unipi.it/~luigi/vdm.tar.gz) by
+ Luigi Rizzo)
projects / paraslash.git / commitdiff