From: Andre Noll Date: Thu, 5 May 2016 13:37:51 +0000 (+0200) Subject: Merge branch 'refs/heads/t/wmadec' X-Git-Tag: v0.5.6~32 X-Git-Url: http://git.tuebingen.mpg.de/?p=paraslash.git;a=commitdiff_plain;h=becfb4be64a123630775b6517279ed20e4b498f8;hp=5d1a0c07877d301f72247e819441498afc26918d Merge branch 'refs/heads/t/wmadec' This topic branch was cooking in next for two months. * refs/heads/t/wmadec: wmadec: Simplify wma_lsp_to_curve_init(). wmadec: Make pwd->reset_block_lengths a boolean. bitstream.h: Remove some superflous parentheses. wmadec: Simplify get_vlc(). --- diff --git a/INSTALL b/INSTALL index 4cc4b1fe..85b4fab1 100644 --- a/INSTALL +++ b/INSTALL @@ -34,5 +34,3 @@ Example for cross-compiling For details see the user manual: http://people.tuebingen.mpg.de/maan/paraslash/manual.html -or - http://paraslash.systemlinux.org/manual.html diff --git a/Makefile.real b/Makefile.real index ee0bf447..289e027a 100644 --- a/Makefile.real +++ b/Makefile.real @@ -174,7 +174,8 @@ $(man_dir)/para_server.1: man_util_command_lists := $(server_command_lists) $(man_dir)/para_audiod.1: man_util_command_lists := $(audiod_command_lists) $(man_dir)/para_play.1: man_util_command_lists := $(play_command_lists) -$(man_dir)/para_%.1: $(ggo_dir)/%.ggo man_util.bash | $(man_dir) $(help2man_dir) +$(man_dir)/para_%.1: $(ggo_dir)/%.ggo man_util.bash \ + git-version.h | $(man_dir) $(help2man_dir) @[ -z "$(Q)" ] || echo 'MAN $<' $(Q) \ COMMAND_LISTS="$(man_util_command_lists)" \ diff --git a/NEWS b/NEWS deleted file mode 100644 index a5bef9f6..00000000 --- a/NEWS +++ /dev/null @@ -1,1273 +0,0 @@ -NEWS -==== - ------------------------------------------- -current master branch "cascading gradient" ------------------------------------------- - - - 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. - - --------------------------------------- -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. - -Download: ./releases/paraslash-0.5.5.tar.bz2 (tarball) -./releases/paraslash-0.5.5.tar.bz2.asc (signature) - ------------------------------------------- -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: ./releases/paraslash-0.5.4.tar.bz2 (tarball) -./releases/paraslash-0.5.4.tar.bz2.asc (signature) - ---------------------------------------------- -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: ./releases/paraslash-0.5.3.tar.bz2 (tarball), -./releases/paraslash-0.5.3.tar.bz2.asc (signature) - ----------------------------------------- -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: ./releases/paraslash-0.5.2.tar.bz2 (tarball), -./releases/paraslash-0.5.2.tar.bz2.asc (signature) - ------------------------------------------- -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: ./releases/paraslash-0.5.1.tar.bz2 (tarball), -./releases/paraslash-0.5.1.tar.bz2.asc (signature) - ----------------------------------------- -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: ./releases/paraslash-0.5.0.tar.bz2 (tarball), -./releases/paraslash-0.5.0.tar.bz2.asc (signature) - --------------------------------------- -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 --git a/NEWS.md b/NEWS.md new file mode 100644 index 00000000..6ea6ecfe --- /dev/null +++ b/NEWS.md @@ -0,0 +1,1284 @@ +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. +- Cleanup of the wma decoder and bitstream code. + +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 --git a/README b/README index 0a0aae88..d8a545fc 100644 --- a/README +++ b/README @@ -6,7 +6,6 @@ Distribution of paraslash is covered by the GNU GPL, version 2 unless otherwise stated. See file COPYING. Web page: http://people.tuebingen.mpg.de/maan/paraslash/ -Alternative web page: http://paraslash.systemlinux.org/ Gitweb: http://git.tuebingen.mpg.de/paraslash.git/ Git URL: git://git.tuebingen.mpg.de/paraslash.git Email: Andre Noll diff --git a/aac_afh.c b/aac_afh.c index d3e69454..c49f30de 100644 --- a/aac_afh.c +++ b/aac_afh.c @@ -317,7 +317,7 @@ close: return ret; } -static const char* aac_suffixes[] = {"m4a", "mp4", NULL}; +static const char * const aac_suffixes[] = {"m4a", "mp4", NULL}; /** * the init function of the aac audio format handler * diff --git a/afh.h b/afh.h index 7a30947a..dad67351 100644 --- a/afh.h +++ b/afh.h @@ -88,7 +88,7 @@ struct audio_format_handler { */ void (*init)(struct audio_format_handler*); /** Typical file endings for files that can be handled by this afh. */ - const char **suffixes; + const char * const *suffixes; /** * Check if this audio format handler can handle the file. * diff --git a/afs.c b/afs.c index d5afc6d9..0b24a3b8 100644 --- a/afs.c +++ b/afs.c @@ -424,7 +424,7 @@ static int pass_afd(int fd, char *buf, size_t size) { struct msghdr msg = {.msg_iov = NULL}; struct cmsghdr *cmsg; - char control[255]; + char control[255] __a_aligned(8); int ret; struct iovec iov; @@ -502,7 +502,6 @@ static int activate_mood_or_playlist(char *arg, int *num_admissible) enum play_mode mode; int ret; - PARA_INFO_LOG("new playlist: %s\n", arg); if (!arg) { ret = change_current_mood(NULL); /* always successful */ mode = PLAY_MODE_MOOD; diff --git a/aft.c b/aft.c index 261054df..f14440e6 100644 --- a/aft.c +++ b/aft.c @@ -696,7 +696,13 @@ static int get_local_time(uint64_t *seconds, char *buf, size_t size, return -E_STRFTIME; return 1; } - if (!strftime(buf, size, "%b %e %Y", tm)) + /* + * If the given time is more than six month away from the current time, + * we print only the year. The additional space character in the format + * string below makes the formated date align nicely with dates that + * contain the time (those written by the above strftime() statement). + */ + if (!strftime(buf, size, "%b %e %Y", tm)) return -E_STRFTIME; return 1; } diff --git a/attribute.c b/attribute.c index f3f8ea7a..4cb29828 100644 --- a/attribute.c +++ b/attribute.c @@ -437,13 +437,13 @@ err: static int att_logical_or(struct osl_row *row, void *data) { - uint64_t *att_mask = data; + uint64_t *att_mask = data, one = 1; struct osl_object bitnum_obj; int ret = osl_get_object(attribute_table, row, ATTCOL_BITNUM, &bitnum_obj); if (ret < 0) return ret; - *att_mask |= 1 << *(unsigned char *)bitnum_obj.data; + *att_mask |= one << *(unsigned char *)bitnum_obj.data; return 0; } diff --git a/blob.c b/blob.c index 2e0a4762..ca39de0d 100644 --- a/blob.c +++ b/blob.c @@ -496,6 +496,8 @@ static int blob_get_name_by_id(struct osl_table *table, uint32_t id, ret = osl(osl_get_object(table, row, BLOBCOL_NAME, &obj)); if (ret < 0) return ret; + if (*(char *)obj.data == '\0') + return -E_DUMMY_ROW; *name = (char *)obj.data; return 1; } diff --git a/client.c b/client.c index 34cc9189..31cfff09 100644 --- a/client.c +++ b/client.c @@ -323,11 +323,7 @@ static void lsatt_completer(struct i9e_completion_info *ci, struct i9e_completion_result *cr) { char *opts[] = {"-i", "-l", "-r", NULL}; - - if (ci->word[0] == '-') - i9e_complete_option(opts, ci, cr); - else - complete_attributes(ci->word, &cr->matches); + i9e_complete_option(opts, ci, cr); } static void mvatt_completer(struct i9e_completion_info *ci, diff --git a/command.c b/command.c index bde14587..93de2d2d 100644 --- a/command.c +++ b/command.c @@ -161,9 +161,8 @@ static unsigned get_status(struct misc_meta_data *nmmd, int parser_friendly, static int check_sender_args(int argc, char * const * argv, struct sender_command_data *scd) { int i; - /* this has to match sender.h */ - const char *subcmds[] = {"add", "delete", "allow", "deny", "on", "off", NULL}; + const char *subcmds[] = {SENDER_SUBCOMMANDS NULL}; scd->sender_num = -1; if (argc < 3) return -E_COMMAND_SYNTAX; @@ -183,19 +182,19 @@ static int check_sender_args(int argc, char * const * argv, struct sender_comman if (!senders[scd->sender_num].client_cmds[scd->cmd_num]) return -E_SENDER_CMD; switch (scd->cmd_num) { - case SENDER_ON: - case SENDER_OFF: + case SENDER_on: + case SENDER_off: if (argc != 3) return -E_COMMAND_SYNTAX; break; - case SENDER_DENY: - case SENDER_ALLOW: + case SENDER_deny: + case SENDER_allow: if (argc != 4 || parse_cidr(argv[3], scd->host, sizeof(scd->host), &scd->netmask) == NULL) return -E_COMMAND_SYNTAX; break; - case SENDER_ADD: - case SENDER_DELETE: + case SENDER_add: + case SENDER_delete: if (argc != 4) return -E_COMMAND_SYNTAX; return parse_fec_url(argv[3], scd); @@ -358,8 +357,8 @@ static int com_sender(struct command_context *cc) } switch (scd.cmd_num) { - case SENDER_ADD: - case SENDER_DELETE: + case SENDER_add: + case SENDER_delete: assert(senders[scd.sender_num].resolve_target); ret = senders[scd.sender_num].resolve_target(cc->argv[3], &scd); if (ret < 0) diff --git a/dccp_send.c b/dccp_send.c index b038fc01..92dd9333 100644 --- a/dccp_send.c +++ b/dccp_send.c @@ -225,12 +225,12 @@ void dccp_send_init(struct sender *s) s->shutdown_clients = dccp_shutdown_clients; s->resolve_target = NULL; s->help = generic_sender_help; - s->client_cmds[SENDER_ON] = dccp_com_on; - s->client_cmds[SENDER_OFF] = dccp_com_off; - s->client_cmds[SENDER_DENY] = dccp_com_deny; - s->client_cmds[SENDER_ALLOW] = dccp_com_allow; - s->client_cmds[SENDER_ADD] = NULL; - s->client_cmds[SENDER_DELETE] = NULL; + s->client_cmds[SENDER_on] = dccp_com_on; + s->client_cmds[SENDER_off] = dccp_com_off; + s->client_cmds[SENDER_deny] = dccp_com_deny; + s->client_cmds[SENDER_allow] = dccp_com_allow; + s->client_cmds[SENDER_add] = NULL; + s->client_cmds[SENDER_delete] = NULL; k = conf.dccp_data_slices_per_group_arg; n = conf.dccp_slices_per_group_arg; diff --git a/error.h b/error.h index b7352333..830d0f8d 100644 --- a/error.h +++ b/error.h @@ -246,7 +246,6 @@ extern const char **para_errlist[]; #define MOOD_ERRORS \ PARA_ERROR(NO_MOOD, "no mood available"), \ - PARA_ERROR(DUMMY_ROW, "attempted to access blob dummy object"), \ #define MM_ERRORS \ @@ -261,6 +260,7 @@ extern const char **para_errlist[]; #define BLOB_ERRORS \ PARA_ERROR(BLOB_SYNTAX, "blob syntax error"), \ + PARA_ERROR(DUMMY_ROW, "attempted to access blob dummy object"), \ #define PLAYLIST_ERRORS \ diff --git a/flac_afh.c b/flac_afh.c index 51c3c314..2e2842b1 100644 --- a/flac_afh.c +++ b/flac_afh.c @@ -515,7 +515,7 @@ free_pfad: return ret; } -static const char* flac_suffixes[] = {"flac", NULL}; +static const char * const flac_suffixes[] = {"flac", NULL}; /** * The init function of the flac audio format handler. diff --git a/gui.c b/gui.c index 1a89681d..9d96e70f 100644 --- a/gui.c +++ b/gui.c @@ -296,7 +296,7 @@ static int align_str(WINDOW* win, char *str, unsigned int len, waddstr(win, str); } else { add_spaces(win, num / 2); - waddstr(win, str[0]? str: ""); + waddstr(win, str); add_spaces(win, num - num / 2); } return 1; @@ -776,7 +776,7 @@ static void init_curses(void) { if (curses_active()) return; - if (top.win && refresh() == ERR) /* refresh is really needed */ + if (refresh() == ERR) /* refresh is really needed */ die(EXIT_FAILURE, "refresh() failed\n"); if (LINES < theme.lines_min || COLS < theme.cols_min) die(EXIT_FAILURE, "Terminal (%dx%d) too small" diff --git a/http_send.c b/http_send.c index daf39e73..9d0f49ae 100644 --- a/http_send.c +++ b/http_send.c @@ -256,12 +256,12 @@ void http_send_init(struct sender *s) s->shutdown_clients = http_shutdown_clients; s->resolve_target = NULL; s->help = generic_sender_help; - s->client_cmds[SENDER_ON] = http_com_on; - s->client_cmds[SENDER_OFF] = http_com_off; - s->client_cmds[SENDER_DENY] = http_com_deny; - s->client_cmds[SENDER_ALLOW] = http_com_allow; - s->client_cmds[SENDER_ADD] = NULL; - s->client_cmds[SENDER_DELETE] = NULL; + s->client_cmds[SENDER_on] = http_com_on; + s->client_cmds[SENDER_off] = http_com_off; + s->client_cmds[SENDER_deny] = http_com_deny; + s->client_cmds[SENDER_allow] = http_com_allow; + s->client_cmds[SENDER_add] = NULL; + s->client_cmds[SENDER_delete] = NULL; init_sender_status(hss, conf.http_access_arg, conf.http_access_given, conf.http_port_arg, conf.http_max_clients_arg, diff --git a/interactive.c b/interactive.c index 4de81d0d..ce48af32 100644 --- a/interactive.c +++ b/interactive.c @@ -31,7 +31,6 @@ struct i9e_private { struct task *task; struct btr_node *stdout_btrn; bool last_write_was_status; - bool line_handler_running; bool input_eof; bool caught_sigint; bool caught_sigterm; @@ -414,10 +413,6 @@ static void update_winsize(void) i9ep->empty_line[i9ep->num_columns] = '\0'; } -/** - * Defined key sequences are mapped to keys starting with this offset. I.e. - * pressing the first defined key sequence yields the key number \p KEY_OFFSET. - */ static int dispatch_key(__a_unused int count, __a_unused int key) { int i, ret; @@ -484,7 +479,6 @@ int i9e_open(struct i9e_client_info *ici, struct sched *s) if (ici->producer) { rl_callback_handler_install("", i9e_line_handler); i9e_attach_to_stdout(ici->producer); - rl_set_keymap(i9ep->bare_km); } else rl_callback_handler_install(i9ep->ici->prompt, i9e_line_handler); return 1; @@ -561,8 +555,6 @@ void ie9_print_status_bar(char *buf, unsigned len) * Tell i9e that the caller received a signal. * * \param sig_num The number of the signal received. - * - * Currently the function only cares about \p SIGINT, but this may change. */ void i9e_signal_dispatch(int sig_num) { diff --git a/mm.c b/mm.c index d6f3573c..92856ec3 100644 --- a/mm.c +++ b/mm.c @@ -191,6 +191,22 @@ static int mm_channels_score_function(__a_unused const char *path, return mm_compare_num_score_function(afhi->channels, private); } +static int mm_image_id_score_function(__a_unused const char *path, + const struct afs_info *afsi, + __a_unused const struct afh_info *afhi, + const void *private) +{ + return mm_compare_num_score_function(afsi->image_id, private); +} + +static int mm_lyrics_id_score_function(__a_unused const char *path, + const struct afs_info *afsi, + __a_unused const struct afh_info *afhi, + const void *private) +{ + return mm_compare_num_score_function(afsi->lyrics_id, private); +} + static int mm_num_played_score_function(__a_unused const char *path, const struct afs_info *afsi, __a_unused const struct afh_info *afhi, @@ -356,5 +372,7 @@ const struct mood_method mood_methods[] = { {DEFINE_COMPARE_NUM_MOOD_METHOD(frequency)}, {DEFINE_COMPARE_NUM_MOOD_METHOD(channels)}, {DEFINE_COMPARE_NUM_MOOD_METHOD(num_played)}, + {DEFINE_COMPARE_NUM_MOOD_METHOD(image_id)}, + {DEFINE_COMPARE_NUM_MOOD_METHOD(lyrics_id)}, {.parser = NULL} }; diff --git a/mood.c b/mood.c index d29c62c2..daa8196a 100644 --- a/mood.c +++ b/mood.c @@ -446,7 +446,7 @@ static int64_t normalized_value(int64_t x, int64_t n, int64_t sum, int64_t qd) { if (!n || !qd) return 0; - return 100 * (n * x - sum) / (int64_t)int_sqrt(n * qd); + return 100 * (n * x - sum) / (int64_t)int_sqrt(n) / (int64_t)int_sqrt(qd); } static long compute_score(struct afs_info *afsi, long mood_score) @@ -460,7 +460,7 @@ static long compute_score(struct afs_info *afsi, long mood_score) static int add_afs_statistics(const struct osl_row *row) { - uint64_t n, x, s; + uint64_t n, x, s, q; struct afs_info afsi; int ret; @@ -470,14 +470,18 @@ static int add_afs_statistics(const struct osl_row *row) n = statistics.num; x = afsi.last_played; s = statistics.last_played_sum; - if (n > 0) - statistics.last_played_qd += (x - s / n) * (x - s / n) * n / (n + 1); + if (n > 0) { + q = (x > s / n)? x - s / n : s / n - x; + statistics.last_played_qd += q * q * n / (n + 1); + } statistics.last_played_sum += x; x = afsi.num_played; s = statistics.num_played_sum; - if (n > 0) - statistics.num_played_qd += (x - s / n) * (x - s / n) * n / (n + 1); + if (n > 0) { + q = (x > s / n)? x - s / n : s / n - x; + statistics.num_played_qd += q * q * n / (n + 1); + } statistics.num_played_sum += x; statistics.num++; return 1; @@ -604,7 +608,8 @@ static int add_if_admissible(struct osl_row *aft_row, void *data) * the last number a_n was replaced by b) may be computed in O(1) time in terms * of n, q, a_n, b, and S as * - * q' = q + d * s - (2 * S + d) * d / n, + * q' = q + d * s - (2 * S + d) * d / n + * = q + d * (s - 2 * S / n - d /n), * * where d = b - a_n, and s = b + a_n. * @@ -621,7 +626,7 @@ _static_inline_ int64_t update_quadratic_deviation(int64_t n, int64_t old_qd, { int64_t delta = new_val - old_val; int64_t sigma = new_val + old_val; - return old_qd + delta * sigma - (2 * old_sum + delta) * delta / n; + return old_qd + delta * (sigma - 2 * old_sum / n - delta / n); } static int update_afs_statistics(struct afs_info *old_afsi, struct afs_info *new_afsi) diff --git a/mp3_afh.c b/mp3_afh.c index 73e744ec..74d65fff 100644 --- a/mp3_afh.c +++ b/mp3_afh.c @@ -684,7 +684,7 @@ static int mp3_get_file_info(char *map, size_t numbytes, int fd, return 1; } -static const char* mp3_suffixes[] = {"mp3", NULL}; +static const char * const mp3_suffixes[] = {"mp3", NULL}; /** * the init function of the mp3 audio format handler diff --git a/net.c b/net.c index 463033bb..42418e5f 100644 --- a/net.c +++ b/net.c @@ -1018,7 +1018,7 @@ static void dispose_fds(int *fds, unsigned num) */ int recv_cred_buffer(int fd, char *buf, size_t size) { - char control[255]; + char control[255] __a_aligned(8); struct msghdr msg; struct cmsghdr *cmsg; struct iovec iov; diff --git a/ogg_afh.c b/ogg_afh.c index 32f8bc1b..29f08965 100644 --- a/ogg_afh.c +++ b/ogg_afh.c @@ -171,8 +171,6 @@ fail: PARA_ERROR_LOG("%s\n", para_strerror(-ret)); } -static const char* ogg_suffixes[] = {"ogg", NULL}; - static int vorbis_make_meta_packet(struct taginfo *tags, ogg_packet *result) { vorbis_comment vc; @@ -206,6 +204,9 @@ static int vorbis_rewrite_tags(const char *map, size_t mapsize, free(packet.packet); return ret; } + +static const char * const ogg_suffixes[] = {"ogg", NULL}; + /** * The init function of the ogg vorbis audio format handler. * diff --git a/opus_afh.c b/opus_afh.c index ace83008..b1469b47 100644 --- a/opus_afh.c +++ b/opus_afh.c @@ -17,7 +17,7 @@ #include "opus_common.h" #include "ogg_afh_common.h" -static const char* opus_suffixes[] = {"opus", NULL}; +static const char * const opus_suffixes[] = {"opus", NULL}; #define OPUS_COMMENT_HEADER "OpusTags" @@ -96,7 +96,8 @@ static int opus_packet_callback(ogg_packet *packet, int packet_num, if (ret < 0) return ret; afhi->channels = oh->channels; - afhi->techinfo = make_message("header version %d, input sample rate: %dHz", + afhi->techinfo = make_message( + "header version %d, input sample rate: %" PRIu32 "Hz", oh->version, oh->input_sample_rate); /* * The input sample rate is irrelevant for afhi->frequency as diff --git a/opus_common.c b/opus_common.c index 927df1f3..67a8841e 100644 --- a/opus_common.c +++ b/opus_common.c @@ -104,7 +104,7 @@ int opus_parse_header(const char *packet, int len, struct opus_header *h) if (!read_chars(&p, &ch, 1)) return -E_OPUS_HEADER; h->version = ch; - if((h->version & 240) != 0) /* Only major version 0 supported. */ + if ((h->version & 240) != 0) /* Only major version 0 supported. */ return -E_OPUS_HEADER; if (!read_chars(&p, &ch, 1)) diff --git a/play.c b/play.c index 55c9ec1b..927f5dc6 100644 --- a/play.c +++ b/play.c @@ -277,7 +277,8 @@ static int eof_cleanup(struct play_task *pt) memset(&pt->wn, 0, sizeof(struct writer_node)); task_reap(&pt->fn.task); - decoder->close(&pt->fn); + if (decoder->close) + decoder->close(&pt->fn); btr_remove_node(&pt->fn.btrn); free(pt->fn.conf); memset(&pt->fn, 0, sizeof(struct filter_node)); diff --git a/playlist.c b/playlist.c index 9616ed0f..01392030 100644 --- a/playlist.c +++ b/playlist.c @@ -191,8 +191,6 @@ static int handle_audio_file_event(enum afs_events event, void *data) char *new_path; const struct osl_row *row = data; - if (!current_playlist.name) - return 1; if (event == AUDIO_FILE_RENAME) { ret = row_belongs_to_score_table(row, NULL); if (ret < 0) @@ -237,7 +235,9 @@ int playlists_event_handler(enum afs_events event, int ret; struct afsi_change_event_data *aced = data; - switch(event) { + if (!current_playlist.name) + return 1; + switch (event) { case AFSI_CHANGE: return playlist_update_audio_file(aced->aft_row); case AUDIO_FILE_RENAME: diff --git a/send.h b/send.h index 09eb78ba..0c74f0ea 100644 --- a/send.h +++ b/send.h @@ -6,16 +6,21 @@ /** \file send.h Sender-related defines and structures. */ -/** The sender subcommands. */ +#define SENDER_SUBCOMMANDS \ + SENDER_SUBCOMMAND(add) /**< Add a target (udp only). */ \ + SENDER_SUBCOMMAND(delete) /**< Delete a target (udp only). */ \ + SENDER_SUBCOMMAND(allow) /**< Allow connections from given IP address(es). */ \ + SENDER_SUBCOMMAND(deny) /**< Deny connections from given IP address(es). */ \ + SENDER_SUBCOMMAND(on) /**< Activate the sender. */ \ + SENDER_SUBCOMMAND(off) /**< Deactivate the sender. */ \ + +#define SENDER_SUBCOMMAND(_name) SENDER_ ## _name, enum sender_subcommand { - SENDER_ADD, /**< Add a target (udp only). */ - SENDER_DELETE, /**< Delete a target (udp only). */ - SENDER_ALLOW, /**< Allow connections from given IP address(es). */ - SENDER_DENY, /**< Deny connections from given IP address(es). */ - SENDER_ON, /**< Activate the sender. */ - SENDER_OFF, /**< Deactivate the sender. */ + SENDER_SUBCOMMANDS NUM_SENDER_CMDS /**< Used as array size in struct \ref sender. */ }; +#undef SENDER_SUBCOMMAND +#define SENDER_SUBCOMMAND(_name) #_name, /** * Describes one supported sender of para_server. diff --git a/spx_afh.c b/spx_afh.c index 108cfaa4..b780635b 100644 --- a/spx_afh.c +++ b/spx_afh.c @@ -118,8 +118,6 @@ static int spx_get_comments(unsigned char *comments, int length, return 1; } -static const char* speex_suffixes[] = {"spx", "speex", NULL}; - static int spx_packet_callback(ogg_packet *packet, int packet_num, __a_unused int serial, struct afh_info *afhi, void *private_data) @@ -251,6 +249,8 @@ static int spx_rewrite_tags(const char *map, size_t mapsize, return ret; } +static const char * const speex_suffixes[] = {"spx", "speex", NULL}; + /** * The init function of the ogg/speex audio format handler. * diff --git a/string.c b/string.c index c820bdca..701448e0 100644 --- a/string.c +++ b/string.c @@ -1073,7 +1073,7 @@ __must_check int strwidth(const char *s, size_t *result) return -ERRNO_TO_PARA_ERROR(errno); if (num_wchars == 0) return 0; - dest = para_malloc(num_wchars * sizeof(*dest)); + dest = para_malloc((num_wchars + 1) * sizeof(*dest)); src = s; memset(&state, 0, sizeof(state)); num_wchars = mbsrtowcs(dest, &src, num_wchars, &state); diff --git a/t/t0004-server.sh b/t/t0004-server.sh index 76128512..3cb37d42 100755 --- a/t/t0004-server.sh +++ b/t/t0004-server.sh @@ -48,6 +48,30 @@ required_objects[$i]='ogg_afh' cmdline[$i]="ls -l=v ${oggs_base[@]}" good[$i]='^basename:' +let i++ +commands[$i]='addatt' +required_objects[$i]='' +cmdline[$i]="addatt $(seq 64 | tr '\n' ' ')" +bad[$i]='.' + +let i++ +commands[$i]='lsatt' +required_objects[$i]='' +cmdline[$i]="lsatt" +good[$i]='^1$' + +let i++ +commands[$i]='setatt' +required_objects[$i]='ogg_afh' +cmdline[$i]="setatt 33+ ${oggs[@]}" +bad[$i]='.' + +let i++ +commands[$i]="ls" +required_objects[$i]='ogg_afh' +cmdline[$i]="ls -l=v -p ${oggs[@]}" +good[$i]='^attributes_txt: 33' + let i++ commands[$i]="term" cmdline[$i]="term" diff --git a/t/test-lib.sh b/t/test-lib.sh index 0e702b53..99e575d3 100644 --- a/t/test-lib.sh +++ b/t/test-lib.sh @@ -272,7 +272,7 @@ fixup_dirs() { local wd=$(pwd) - test_dir="$wd/${0%/*}" + test_dir="$(realpath $wd/${0%/*})" test_audio_file_dir="$test_dir/audio_files" [[ -z "$o_results_dir" ]] && o_results_dir="$test_dir/test-results" diff --git a/udp_send.c b/udp_send.c index faae208c..425118a1 100644 --- a/udp_send.c +++ b/udp_send.c @@ -46,6 +46,8 @@ struct udp_target { struct fec_client *fc; /** The FEC parameters for this target. */ struct fec_client_parms fcp; + /** Whether we already sent the FEC eof packet to this target. */ + bool sent_fec_eof; }; static struct list_head targets; @@ -54,15 +56,16 @@ static int sender_status; static void udp_close_target(struct sender_client *sc) { const char *buf; - size_t len = vss_get_fec_eof_packet(&buf); - - /* - * Ignore the return value of write() since we are closing the target - * anyway. The sole purpose of the "do_nothing" statement is to silence - * gcc. - */ - if (write(sc->fd, buf, len)) - do_nothing; + size_t len; + struct udp_target *ut = sc->private_data; + + if (ut->sent_fec_eof) + return; + PARA_NOTICE_LOG("sending FEC EOF\n"); + len = vss_get_fec_eof_packet(&buf); + /* Ignore write() errors since we are closing the target anyway. */ + if (write(sc->fd, buf, len) == len) + ut->sent_fec_eof = true; } static void udp_delete_target(struct sender_client *sc, const char *msg) @@ -187,14 +190,14 @@ static int udp_resolve_target(const char *url, struct sender_command_data *scd) static int udp_com_on(__a_unused struct sender_command_data *scd) { - sender_status = SENDER_ON; + sender_status = SENDER_on; return 1; } static int udp_com_off(__a_unused struct sender_command_data *scd) { udp_shutdown_targets(); - sender_status = SENDER_OFF; + sender_status = SENDER_off; return 1; } @@ -232,9 +235,11 @@ static int udp_com_delete(struct sender_command_data *scd) /** Initialize UDP session and set maximum payload size. */ static int udp_init_fec(struct sender_client *sc) { + struct udp_target *ut = sc->private_data; int mps; PARA_NOTICE_LOG("sending to udp %s\n", sc->name); + ut->sent_fec_eof = false; mps = generic_max_transport_msg_size(sc->fd) - sizeof(struct udphdr); PARA_INFO_LOG("current MPS = %d bytes\n", mps); return mps; @@ -277,7 +282,7 @@ static void udp_send_fec(struct sender_client *sc, char *buf, size_t len) { int ret; - if (sender_status == SENDER_OFF) + if (sender_status == SENDER_off) return; if (len == 0) return; @@ -366,7 +371,7 @@ static char *udp_status(void) "status: %s\n" "port: %s\n" "targets: %s\n", - (sender_status == SENDER_ON)? "on" : "off", + (sender_status == SENDER_on)? "on" : "off", stringify_port(conf.udp_default_port_arg, "udp"), tgts? tgts : "(none)" ); @@ -425,15 +430,15 @@ void udp_send_init(struct sender *s) s->post_select = NULL; s->shutdown_clients = udp_shutdown_targets; s->resolve_target = udp_resolve_target; - s->client_cmds[SENDER_ON] = udp_com_on; - s->client_cmds[SENDER_OFF] = udp_com_off; - s->client_cmds[SENDER_DENY] = NULL; - s->client_cmds[SENDER_ALLOW] = NULL; - s->client_cmds[SENDER_ADD] = udp_com_add; - s->client_cmds[SENDER_DELETE] = udp_com_delete; - sender_status = SENDER_OFF; + s->client_cmds[SENDER_on] = udp_com_on; + s->client_cmds[SENDER_off] = udp_com_off; + s->client_cmds[SENDER_deny] = NULL; + s->client_cmds[SENDER_allow] = NULL; + s->client_cmds[SENDER_add] = udp_com_add; + s->client_cmds[SENDER_delete] = udp_com_delete; + sender_status = SENDER_off; udp_init_target_list(); if (!conf.udp_no_autostart_given) - sender_status = SENDER_ON; + sender_status = SENDER_on; PARA_DEBUG_LOG("udp sender init complete\n"); } diff --git a/vss.c b/vss.c index cbc05d13..51db7686 100644 --- a/vss.c +++ b/vss.c @@ -905,7 +905,7 @@ static void vss_pre_select(struct sched *s, void *context) static int recv_afs_msg(int afs_socket, int *fd, uint32_t *code, uint32_t *data) { - char control[255], buf[8]; + char control[255] __a_aligned(8), buf[8]; struct msghdr msg = {.msg_iov = NULL}; struct cmsghdr *cmsg; struct iovec iov; diff --git a/web/manual.m4 b/web/manual.m4 deleted file mode 100644 index d63b07e8..00000000 --- a/web/manual.m4 +++ /dev/null @@ -1,2236 +0,0 @@ -dnl To generate the html version, execute -dnl m4 web/manual.m4 | grutatxt --toc - -define(`LOCAL_LINK_NAME', `translit(`$1', `A-Z -', `a-z__')') -define(`REMOVE_NEWLINE', `translit(`$1',` -', ` ')') - -define(`REFERENCE', ./``#''`LOCAL_LINK_NAME($1)' (`REMOVE_NEWLINE($2)')) -define(`XREFERENCE', `$1' (`REMOVE_NEWLINE($2)')) -define(`EMPH', ``_''`REMOVE_NEWLINE($1)'``_'') - -Paraslash user manual -===================== - -This document describes how to install, configure and use the paraslash -network audio streaming system. Most chapters start with a chapter -overview and conclude with an example section. We try to focus on -general concepts and on the interaction of the various pieces of the -paraslash package. Hence this user manual is not meant as a replacement -for the manual pages that describe all command line options of each -paraslash executable. - ------------- -Introduction ------------- - -In this chapter we give an REFERENCE(Overview, overview) of the -interactions of the two main programs contained in the paraslash -package, followed by REFERENCE(The paraslash executables, brief -descriptions) of all executables. - -Overview -~~~~~~~~ - -The core functionality of the para suite is provided by two main -executables, para_server and para_audiod. The former maintains a -database of audio files and streams these files to para_audiod which -receives and plays the stream. - -In a typical setting, both para_server and para_audiod act as -background daemons whose functionality is controlled by client -programs: the para_audioc client controls para_audiod over a local -socket while the para_client program connects to para_server over a -local or remote networking connection. - -Typically, these two daemons run on different hosts but a local setup -is also possible. - -A simplified picture of a typical setup is as follows -<< -
- 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 REFERENCE(Networking, networking). - -The built-in audio file selector of paraslash is used to manage your -audio files. It maintains statistics on the usage of all available -audio files such as last-played time, and the number of times each -file was selected. - -Additional information may be added to the database to allow -fine-grained selection based on various properties of the audio file, -including information found in (ID3) tags. However, old-fashioned -playlists are also supported. - -It is also possible to store images (album covers) and lyrics in the -database and associate these to the corresponding audio files. - -The section on the REFERENCE(The audio file selector, audio file -selector) discusses this topic. - - -*para_client* - -The client program to connect to para_server. paraslash commands -are sent to para_server and the response is dumped to STDOUT. This -can be used by any scripting language to produce user interfaces with -little programming effort. - -All connections between para_server and para_client are encrypted -with a symmetric 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 REFERENCE(Requirements, necessary software) -that must be installed to compile the paraslash package, describes -how to REFERENCE(Installation, compile and install) the paraslash -source code and the steps that have to be performed in order to -REFERENCE(Quick start, set up) a typical server and client. - -Requirements -~~~~~~~~~~~~ -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 \ - libasound2-dev libao-dev libreadline-dev libncurses-dev \ - libopus-dev - -Detailed description: In any case you'll need - - - XREFERENCE(http://people.tuebingen.mpg.de/maan/osl/, libosl). - The _object storage layer_ library is used by para_server. To - clone the source code repository, execute - - git clone git://git.tuebingen.mpg.de/osl - - - XREFERENCE(ftp://ftp.gnu.org/pub/gnu/gcc, gcc) or - XREFERENCE(http://clang.llvm.org, clang). All gcc versions - >= 3.3 are currently supported. Clang version 1.1 or newer - should work as well. - - - XREFERENCE(ftp://ftp.gnu.org/pub/gnu/make, gnu make) is - also shipped with the disto. On BSD systems the gnu make - executable is often called gmake. - - - XREFERENCE(ftp://ftp.gnu.org/pub/gnu/bash, bash). Some - scripts which run during compilation require the EMPH(Bourne - again shell). It is most likely already installed. - - - XREFERENCE(ftp://ftp.gnu.org/pub/gnu/gengetopt/, gengetopt) - is needed to generate the C code for the command line parsers - of all paraslash executables. - - - XREFERENCE(ftp://ftp.gnu.org/pub/gnu/help2man, help2man) - is used to create the man pages. - -Optional: - - - XREFERENCE(http://www.openssl.org/, openssl) or - XREFERENCE(ftp://ftp.gnupg.org/gcrypt/libgcrypt/, 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. - - - XREFERENCE(http://www.underbit.com/products/mad/, libmad). - To compile in MP3 support for paraslash, the development - package must be installed. It is called libmad0-dev on - debian-based systems. Note that libmad is not necessary on - the server side, i.e. for sending MP3 files. - - - XREFERENCE(http://www.underbit.com/products/mad/, - libid3tag). For version-2 ID3 tag support, you'll need - the libid3tag development package libid3tag0-dev. Without - libid3tag, only version-1 tags are recognized. The mp3 tagger - also needs this library for modifying (id3v1 and id3v2) tags. - - - XREFERENCE(http://www.xiph.org/downloads/, ogg vorbis). - For ogg vorbis streams you'll need libogg, libvorbis, - libvorbisfile. The corresponding Debian packages are called - libogg-dev and libvorbis-dev. - - - XREFERENCE(http://www.audiocoding.com/, libfaad). For aac - files (m4a) you'll need libfaad (libfaad-dev). - - - XREFERENCE(http://www.speex.org/, speex). In order to stream - or decode speex files, libspeex (libspeex-dev) is required. - - - XREFERENCE(http://flac.sourceforge.net/, flac). To stream - or decode files encoded with the _Free Lossless Audio Codec_, - libFLAC (libFLAC-dev) must be installed. - - - XREFERENCE(http://www.mega-nerd.com/SRC/index.html, - libsamplerate). The resample filter will only be compiled if - this library is installed. Debian package: libsamplerate-dev. - - - XREFERENCE(ftp://ftp.alsa-project.org/pub/lib/, alsa-lib). On - Linux, you'll need to have ALSA's development package - libasound2-dev installed. - - - XREFERENCE(http://downloads.xiph.org/releases/ao/, - libao). Needed to build the ao writer (ESD, PulseAudio,...). - Debian package: libao-dev. - - - XREFERENCE(ftp://ftp.gnu.org/pub/gnu/ncurses, curses). Needed - for para_gui. Debian package: libncurses-dev. - - - XREFERENCE(http://cnswww.cns.cwru.edu/php/chet/readline/rltop.html, - GNU Readline). 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 -~~~~~~~~~~~~~ - -*Step 1*: Create a paraslash user - -In order to control para_server at runtime you must create a paraslash -user. As authentication is based on the RSA crypto system you'll have -to create an RSA key pair. If you already have a user and an RSA key -pair, you may skip this step. - -In this section we'll assume a typical setup: You would like to run -para_server on some host called server_host as user foo, and you want -to connect to para_server from another machine called client_host as -user bar. - -As foo@server_host, create ~/.paraslash/server.users by typing the -following commands: - - user=bar - target=~/.paraslash/server.users - key=~/.paraslash/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 - - -*Step 2*: 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. - -*Step 3*: Create and populate the database - -An empty database is created with - - para_client init - -This initializes a couple of empty tables under -~/.paraslash/afs_database-0.4. You normally don't need to look at these -tables, but it's good to know that you can start from scratch with - - rm -rf ~/.paraslash/afs_database-0.4 - -in case something went wrong. - -Next, you need to add some audio files to that database so that -para_server knows about them. Choose an absolute path to a directory -containing some audio files and add them to the audio file table: - - para_client add /my/mp3/dir - -This might take a while, so it is a good idea to start with a directory -containing not too many files. Note that the table only contains data -about the audio files found, not the files themselves. - -You may print the list of all known audio files with - - para_client ls - -*Step 4*: Configure para_audiod - -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 REFERENCE(The audio file selector, audio file selector) -for how to use playlists and moods to specify which files should be -streamed in which order. - -*Troubleshooting* - -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 -REFERENCE(Client-server authentication, authentication handshake) -between para_client and para_server. User management is discussed -in the section on REFERENCE(The user_list file, the user_list file). -These sections are all about communication between the client and the -server. Connecting para_audiod is a different matter and is described -in a REFERENCE(Connecting para_audiod, separate section). - - - -RSA, 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 REFERENCE(Quick start, -Quick start) and discussed in more detail REFERENCE(The user_list -file, below). - -The user_list file -~~~~~~~~~~~~~~~~~~ - -At startup para_server reads the user list file which 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 uses XREFERENCE(http://people.tuebingen.mpg.de/maan/osl/, libosl), 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 REFERENCE(The AFS process, -AFS process) during server startup and proceed with the description -of the REFERENCE(Database layout, layout) of the various database -tables. The section on REFERENCE(Playlists and moods, playlists -and moods) explains these two audio file selection mechanisms -in detail and contains pratical examples. The way REFERENCE(File -renames and content changes, file renames and content changes) are -detected is discussed briefly before the REFERENCE(Troubleshooting, -Troubleshooting) section 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 ~ - -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). - -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 REFERENCE(The paraslash control -service, control service), followed by a section on the various -REFERENCE(Streaming protocols, streaming protocols) in which the data -connections are described. The way audio file headers are embedded into -the stream is discussed REFERENCE(Streams with headers and headerless -streams, briefly) before the REFERENCE(Networking examples, example -section) which illustrates typical commands for real-life scenarios. - -Both IPv4 and IPv6 are supported. - -The paraslash control service -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -para_server is controlled at runtime via the paraslash control -connection. This connection is used for server commands (play, stop, -...) as well as for afs commands (ls, select, ...). - -The server listens on a TCP port and accepts connections from clients -that connect the open port. Each connection causes the server to fork -off a client process which inherits the connection and deals with that -client only. In this classical accept/fork approach the server process -is unaffected if the child dies or goes crazy for whatever reason. In -fact, the child process can not change address space of server process. - -The section on REFERENCE(Client-server authentication, client-server -authentication) above described the early connection establishment -from the crypto point of view. Here it is described what happens -after the connection (including crypto setup) has been established. -There are four processes involved during command dispatch as sketched -in the following diagram. - -<< -
- 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 REFERENCE(Network protocols, network protocols) -for brief descriptions of the various protocols relevant for network -audio streaming with paraslash. - -It is possible to activate more than one sender simultaneously. -Senders can be controlled at run time and via config file and command -line options. - -Note that audio connections are _not_ encrypted. Transport or Internet -layer encryption should be used if encrypted data connections are -needed. - -Since DCCP and TCP are both connection-oriented protocols, connection -establishment/teardown and access control are very similar between -these two streaming protocols. UDP is the most lightweight option, -since in contrast to TCP/DCCP it is connectionless. It is also the -only protocol supporting IP multicast. - -The HTTP and the DCCP sender listen on a (TCP/DCCP) port waiting for -clients to connect and establish a connection via some protocol-defined -handshake mechanism. Both senders maintain two linked lists each: -The list of all clients which are currently connected, and the list -of access control entries which determines who is allowed to connect. -IP-based access control may be configured through config file and -command line options and via the "allow" and "deny" sender subcommands. - -Upon receiving a GET request from the client, the HTTP sender sends -back a status line and a message. The body of this message is the -audio stream. This is common practice and is supported by many popular -clients which can thus be used to play a stream offered by para_server. -For DCCP things are a bit simpler: No messages are exchanged between -the receiver and sender. The client simply connects and the sender -starts to stream. - -DCCP is an experimental protocol which offers a number of new features -not available for TCP. Both ends can negotiate these features using -a built-in negotiation mechanism. In contrast to TCP/HTTP, DCCP is -datagram-based (no retransmissions) and thus should not be used over -lossy media (e.g. WiFi networks). One useful feature offered by DCCP -is access to a variety of different congestion-control mechanisms -called CCIDs. Two different CCIDs are available per default on Linux: - - - - _CCID 2_. A Congestion Control mechanism similar to that - of TCP. The sender maintains a congestion window and halves - this window in response to congestion. - - - - _CCID-3_. Designed to be fair when competing for bandwidth. - It has lower variation of throughput over time compared with - TCP, which makes it suitable for streaming media. - -Unlike the HTTP and DCCP senders, the UDP sender maintains only a -single list, the _target list_. This list describes the set of clients -to which the stream is sent. There is no list for access control and -no "allow" and "deny" commands for the UDP sender. Instead, the "add" -and "delete" commands can be used to modify the target list. - -Since both UDP and DCCP offer an unreliable datagram-based transport, -additional measures are necessary to guard against disruptions over -networks that are lossy or which may be subject to interference (as -is for instance the case with WiFi). Paraslash uses FEC (Forward -Error Correction) to guard against packet losses and reordering. The -stream is FEC-encoded before it is sent through the UDP socket and -must be decoded accordingly on the receiver side. - -The packet size and the amount of redundancy introduced by FEC can -be configured via the FEC parameters which are dictated by server -and may also be configured through the "sender" command. The FEC -parameters are encoded in the header of each network packet, so no -configuration is necessary on the receiver side. See the section on -REFERENCE(Forward error correction, FEC) below. - -Streams with headers and headerless streams -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -For OGG/Vorbis, 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. - -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 REFERENCE(Streaming protocols, earlier), -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. - -http://git.or.cz/ (git). As described in more detail REFERENCE(Git -branches, below), the git source code management tool is used for -paraslash development. It is necessary for cloning the git repository -and for getting updates. - -ftp://ftp.gnu.org/pub/gnu/m4/ (m4). Some input files for gengetopt -are generated from templates by the m4 macro processor. - -ftp://ftp.gnu.org/pub/gnu/autoconf/ (autoconf) GNU autoconf creates -the configure file which is shipped in the tarballs but has to be -generated when compiling from git. - -http://www.triptico.com/software/grutatxt.html (grutatxt). The -HTML version of this manual and some of the paraslash web pages are -generated by the grutatxt plain text to HTML converter. If changes -are made to these text files the grutatxt package must be installed -to regenerate the HTML files. - -http://www.stack.nl/~dimitri/doxygen/ (doxygen). The documentation -of paraslash's C sources uses the doxygen documentation system. The -conventions for documenting the source code is described in the -REFERENCE(Doxygen, Doxygen section). - -ftp://ftp.gnu.org/pub/gnu/global (global). This is used to generate -browsable HTML from the C sources. It is needed by doxygen. - -Git branches -~~~~~~~~~~~~ - -Paraslash has been developed using the git source code management -tool since 2006. Development is organized roughly in the same spirit -as the git development itself, as described below. - -The following text passage is based on "A note from the maintainer", -written by Junio C Hamano, the maintainer of git. - -There are four branches in the paraslash repository that track the -source tree: "master", "maint", "next", and "pu". - -The "master" branch is meant to contain what is well tested and -ready to be used in a production setting. There could occasionally be -minor breakages or brown paper bag bugs but they are not expected to -be anything major, and more importantly quickly and easily fixable. -Every now and then, a "feature release" is cut from the tip of this -branch, named with three dotted decimal digits, like 0.4.2. - -Whenever changes are about to be included that will eventually lead to -a new major release (e.g. 0.5.0), a "maint" branch is forked off from -"master" at that point. Obvious, safe and urgent fixes after the major -release are applied to this branch and maintenance releases are cut -from it. New features never go to this branch. This branch is also -merged into "master" to propagate the fixes forward. - -A trivial and safe enhancement goes directly on top of "master". -New development does not usually happen on "master", however. -Instead, a separate topic branch is forked from the tip of "master", -and it first is tested in isolation; Usually there are a handful such -topic branches that are running ahead of "master". The tip of these -branches is not published in the public repository to keep the number -of branches that downstream developers need to worry about low. - -The quality of topic branches varies widely. Some of them start out as -"good idea but obviously is broken in some areas" and then with some -more work become "more or less done and can now be tested by wider -audience". Luckily, most of them start out in the latter, better shape. - -The "next" branch is to merge and test topic branches in the latter -category. In general, this branch always contains the tip of "master". -It might not be quite rock-solid production ready, but is expected to -work more or less without major breakage. The maintainer usually uses -the "next" version of paraslash for his own pleasure, so it cannot -be _that_ broken. The "next" branch is where new and exciting things -take place. - -The two branches "master" and "maint" are never rewound, and "next" -usually will not be either (this automatically means the topics that -have been merged into "next" are usually not rebased, and you can find -the tip of topic branches you are interested in from the output of -"git log next"). You should be able to safely build on top of them. - -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 XREFERENCE(http://www.kernel.org/doc/Documentation/CodingStyle, -there), here are the most important points. - - - Burn the GNU coding standards. - - Never use spaces for indentation. - - Tabs are 8 characters, and thus indentations are also 8 characters. - - Don't put multiple assignments on a single line. - - Avoid tricky expressions. - - Don't leave whitespace at the end of lines. - - The limit on the length of lines is 80 columns. - - Use K&R style for placing braces and spaces: - - if (x is true) { - we do y - } - - - Use a space after (most) keywords. - - Do not add spaces around (inside) parenthesized expressions. - - Use one space around (on each side of) most binary and ternary operators. - - Do not use cute names like ThisVariableIsATemporaryCounter, call it tmp. - - Mixed-case names are frowned upon. - - Descriptive names for global variables are a must. - - Avoid typedefs. - - Functions should be short and sweet, and do just one thing. - - The number of local variables shouldn't exceed 10. - - Gotos are fine if they improve readability and reduce nesting. - - Don't use C99-style "// ..." comments. - - Names of macros defining constants and labels in enums are capitalized. - - Enums are preferred when defining several related constants. - - Always use the paraslash wrappers for allocating memory. - - If the name of a function is an action or an imperative. - command, the function should return an error-code integer - (<0 means error, >=0 means success). If the name is a - predicate, the function should return a "succeeded" boolean. - - -Doxygen -~~~~~~~ - -Doxygen is a documentation system for various programming -languages. The 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 -~~~~~~~~ - - Reed, Irving S.; Solomon, Gustave (1960), - XREFERENCE(http://kom.aau.dk/~heb/kurser/NOTER/KOFA01.PDF, - Polynomial Codes over Certain Finite Fields), Journal of the - Society for Industrial and Applied Mathematics (SIAM) 8 (2): - 300-304, doi:10.1137/0108018) - -RFCs -~~~~ - - - XREFERENCE(http://www.ietf.org/rfc/rfc768.txt, RFC 768) (1980): - User Datagram Protocol - - XREFERENCE(http://www.ietf.org/rfc/rfc791.txt, RFC 791) (1981): - Internet Protocol - - XREFERENCE(http://www.ietf.org/rfc/rfc2437.txt, RFC 2437) (1998): - RSA Cryptography Specifications - - XREFERENCE(http://www.ietf.org/rfc/rfc4340.txt, RFC 4340) - (2006): Datagram Congestion Control Protocol (DCCP) - - XREFERENCE(http://www.ietf.org/rfc/rfc4341.txt, RFC 4341) (2006): - Congestion Control ID 2: TCP-like Congestion Control - - XREFERENCE(http://www.ietf.org/rfc/rfc4342.txt, RFC 4342) (2006): - Congestion Control ID 3: TCP-Friendly Rate Control (TFRC) - - XREFERENCE(http://www.ietf.org/rfc/rfc6716.txt, RFC 6716) (2012): - Definition of the Opus Audio Codec - -Application web pages -~~~~~~~~~~~~~~~~~~~~~ - - - XREFERENCE(http://people.tuebingen.mpg.de/maan/paraslash/, paraslash) - - XREFERENCE(http://paraslash.systemlinux.org/, paraslash (alternative page)) - - XREFERENCE(http://xmms2.org/wiki/Main_Page, xmms) - - XREFERENCE(http://www.mpg123.de/, mpg123) - - XREFERENCE(http://gstreamer.freedesktop.org/, gstreamer) - - XREFERENCE(http://www.icecast.org/, icecast) - - XREFERENCE(http://beesbuzz.biz/code/audiocompress.php, Audio Compress) - -External documentation -~~~~~~~~~~~~~~~~~~~~~~ - - - XREFERENCE(http://kernel.org/pub/linux/kernel/people/hpa/raid6.pdf, - H. Peter Anvin: The mathematics of Raid6) - - XREFERENCE(http://info.iet.unipi.it/~luigi/fec_ccr.ps.gz, - Luigi Rizzo: Effective Erasure Codes for reliable Computer - Communication Protocols) - -Code -~~~~ - - XREFERENCE(http://info.iet.unipi.it/~luigi/vdm.tar.gz, - Original FEC implementation by Luigi Rizzo) - diff --git a/web/manual.md b/web/manual.md new file mode 100644 index 00000000..3b9c2709 --- /dev/null +++ b/web/manual.md @@ -0,0 +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 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 >= 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, 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/) +- [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) diff --git a/wma_afh.c b/wma_afh.c index 0b6081cf..929e732b 100644 --- a/wma_afh.c +++ b/wma_afh.c @@ -642,7 +642,7 @@ out: return ret; } -static const char* wma_suffixes[] = {"wma", NULL}; +static const char * const wma_suffixes[] = {"wma", NULL}; /** * The init function of the wma audio format handler.