From: Andre Noll Date: Sun, 17 Apr 2016 12:32:53 +0000 (+0200) Subject: Merge branch 'refs/heads/t/markdown' X-Git-Tag: v0.5.6~36 X-Git-Url: http://git.tuebingen.mpg.de/?p=paraslash.git;a=commitdiff_plain;h=a23e12ae76608a7ba3d333d8d76d5bbba0ba3ef0 Merge branch 'refs/heads/t/markdown' The topich branch was started on 2015-12-13, and has been cooking in next since 2016-01-30. The merge resulted in conflicts for both files which were easy to resolve. * refs/heads/t/markdown: Convert manual and NEWS from grutatxt to markdown. --- a23e12ae76608a7ba3d333d8d76d5bbba0ba3ef0 diff --cc NEWS.md index 00000000,7f61b920..d8152552 mode 000000,100644..100644 --- a/NEWS.md +++ b/NEWS.md @@@ -1,0 -1,1275 +1,1283 @@@ + 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 diff --cc web/manual.md index 00000000,7d2c4cf3..3b9c2709 mode 000000,100644..100644 --- a/web/manual.md +++ b/web/manual.md @@@ -1,0 -1,2223 +1,2223 @@@ + **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 \ - libfaad-dev libspeex-dev libFLAC-dev libsamplerate-dev \ ++ 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 -[clang](http://clang.llvm.org). All gcc versions >= 3.3 are currently ++[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 + + 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 ] [if] [not] [options] + deny [with score ] [if] [not] [options] + score [if] [not] [options] + + + Here 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] [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 + + Takes the name of an attribute and matches iff that attribute is set. + + path_matches + + Takes a filename pattern and matches iff the path of the audio file + matches the pattern. + + artist_matches + album_matches + title_matches + comment_matches + + 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 ~ + bitrate ~ + frequency ~ + channels ~ + num_played ~ ++ image_id ~ ++ lyrics_id ~ + + Takes a comparator ~ of the set {<, =, <=, >, >=, !=} and a number + . Matches an audio file iff the condition ~ is + satisfied where val is the corresponding value of the audio file -(value of the year tag, bitrate in kbit/s, frequency in Hz, channel -count, play count). ++(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 " + instead of "". + + 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 ":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/) -- [alternative page](http://paraslash.systemlinux.org/) + - [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)