5 Paraslash is an acronym for
7 _Play, archive, rate and stream large audio sets happily_
9 It contains the following programs:
11 -----------------------
12 para_server (obligatory)
13 -----------------------
15 para_server streams binary audio data (mp3/ogg/m4a files) over local
16 and/or remote networks. It listens on a tcp port and accepts commands
17 such as play, stop, pause, next from authenticated clients. However,
18 there are many more commands.
20 It supports three builtin streaming methods (senders): http, dccp,
23 The audio stream may be sent over the network by three different
26 * The http sender is recommended for public streams that can be played
27 by any player like mpg123, xmms, itunes, winamp...
29 * The dccp sender is experimental and requires kernel support for the
30 rather new datagram congestion control protocol.
32 * The ortp sender is recommended for LAN streaming and for private
33 streams that require authentication.
35 It is possible to activate more than one sender simultaneously.
37 para_server needs an audio file selector to work, mainly to determine
38 which audio file to stream next. The following three selectors are
41 * The random selector chooses audio files out of a given directory
44 * The playlist selector chooses files from a specified playlist
46 * The (optional) mysql selector is more involved. It connects
47 to a mysql server which holds information on your audio files
48 and maintains statistics on the available audio files. Audio
49 file selection works by sending a user-defined sql-query
50 to the mysql server. This allows rather sophisticated
51 configurations and is explained in detail in README.mysql.
53 It is possible to switch between all supported selectors at any time.
55 Despite of all these features, paraslash is lightweight. The
56 stripped binary of para_server with all its features compiled in
57 (mysql/random/playlist selector, mp3/ogg/aac support, http/dccp/ortp
58 support) is about 120K on i386 under Linux. para_audiod (see below)
61 ------------------------
62 para_client (obligatory)
63 -----------------------
65 The client program to connect to para_server. paraslash commands
66 are sent to para_server and the response is dumped to stdout. This
67 can be used by any scripting language to produce user interfaces with
68 little programming effort.
70 All connections between para_server and para_client are encrypted by
71 default. For each user of paraslash you must create a public/secret
72 key pair for authentication. The (authenticated) connection is crypted
73 with a symmetric rc4 session key.
79 A command line http/dccp/rtp stream grabber. The http mode of this tool
80 can be used to receive date from any http streaming source.
83 para_filter (optional)
86 A filter program that converts from stdin and writes to stdout. It
87 is completely independent from the rest of paraslash, so it might be
88 useful also for different purposes.
90 para_filter combines several decoders (mp3, oggvorbis, aac) and a
91 volume normalzer. New filters can be added easily due to the modular
92 design. If more than one filter is specified, the given filters
93 are 'piped' together in-memory, i.e. without calling any of the
94 read(2)/write(2)/select(2) etc. functions.
96 ----------------------
97 para_write (obligatory)
98 ----------------------
100 A modular audio stream writer. It supports a simple file writer
101 output plugin and optional wav/raw players for alsa (linux-only,
102 Debian package: libasound2-dev) and Mac OS. para_write can also be
103 used as a stand-alone wav or raw audio player.
105 ---------------------------------------
106 para_audiod (optional, but recommended)
107 ---------------------------------------
109 The local daemon that collects information from para_server.
111 It runs on the client side and connects to para_server. The audio
112 stream is read from the network and sent through any of paraslash's
113 filters (decoder, volume normalizer,...). The resulting stream is
114 written to an output plugin (writer), e.g. the alsa writer on linux
115 systems. It is possible to capture the stream at any position in the
118 para_audiod starts an appropriate receiver, filter and player as soon as
119 para_server announces the availability (and the type) of an audio stream.
120 Moreover, it listens on a local socket and sends status information about
121 para_server and para_audiod to local clients on request.
123 --------------------------------------
124 para_audioc (optional, but recommended)
125 --------------------------------------
127 The client program which talks with para_audiod. Used to control
128 para_audiod, to receive status info, or to grab the stream at any
129 point in the filter chain.
131 para_audioc (hence para_audiod) is needed by para_gui, para_sdl_gui
132 and para_krell, see below.
138 Themable ncurses-based gui. It calls para_audioc and presents
139 the obtained information in an ncurses window. para_gui provides
140 key-bindings for the most common commands and new key-bindings can
143 -----------------------
144 para_sdl_gui (optional)
145 -----------------------
147 SDL-based gui. Similar to para_gui but presents its output in an X
148 window (fullscreen mode is also available) and can display jpg images
149 on a per song basis. para_sdl_gui provides an input prompt to enter
150 arbitrary commands. However, it can also be used non-interactively
151 (e.g. as a screen saver) via the -i switch.
153 -------------------------------------------------------------------------
154 para_krell (optional, only useful in conjunction with the mysql selector)
155 -------------------------------------------------------------------------
157 A plugin for gkrellm which shows small pictures of the current song. It
158 allows you to launch 27 different commands by clicking in different
159 areas of its picture (9 small squares x 3 mouse buttons).
165 A (Linux-only) alarm clock and volume-fader.
167 -------------------------------------------------------------------------
168 para_dbadm (optional, only useful in conjunction with the mysql selector)
169 -------------------------------------------------------------------------
171 Very simple curses-based frontend which uses libmenu. Useful for
172 quickly changing the attributes of the current song (e.g. from para_gui
173 as an external command).
175 --------------------------------------------------------------------------
176 para_slider (optional, only useful in conjunction with the mysql selector)
177 --------------------------------------------------------------------------
179 A small X application which shows a scrollbar for each attribute
180 defined in the mysql database. It creates a stream definition from
181 the values of the scrollbars. This allows to smoothly change the mood
182 of the given stream without any file editing.
184 --------------------------
185 bash_completion (optional)
186 --------------------------
188 A small bash script for inclusion in ~/.bashrc. It gives you command
189 line completion for some paraslash commands.
197 - gcc, the gnu compiler collection (shipped with distro): gcc-3.3
198 or newer is required.
199 - openssl (needed by server, client): usually shipped with
200 distro, but you might have to install the "development package"
201 (called libssl-dev on debian systems) as well:
202 http://www.openssl.org/
203 - software mixing, e.g. ALSA and the direct mixing plugin (dmix)
205 If you want to use the mysql-based audio file selector, you also need
211 These are usually shipped with the distro but probably not installed
214 The mp3 decoder of para_filter is based on libmad: If you prefer to
215 use the libmad package provided by your distributor, make sure to
216 install the corresponding development package as well. Otherwise,
217 just download libmad from http://www.underbit.com/products/mad/
219 For ogg vorbis streams you'll need libogg, libvorbis, libvorbisfile,
220 The corresponding Debian packages are called libogg-dev libvorbis-dev,
221 other distributors chose similar names. All of these are also
222 available at http://www.xiph.org/downloads/
224 For aac files (m4a) you'll need libfaad. Get it at
225 http://www.audiocoding.com/modules/wiki/?page=AAC
227 If you intend to use the optional ortp streamer, you'll need libortp:
228 http://www.linphone.org/ortp/
230 For the optional SDL-based gui, the following packages must be installed:
232 - X (usually shipped with distro): http://www.x.org/
233 - libSDL (usually shipped with distro): http://www.libsdl.org/index.php
234 - SDL_image: http://www.libsdl.org/projects/SDL_image/
236 For para_slider, the zero memory widget library is neccessary:
237 http://www710.univ-lyon1.fr/~exco/ZMW/
239 Finally, para_krell needs
241 - gtk2: http://www.gtk.org/
242 - gkrellm2: http://members.dslextreme.com/users/billw/gkrellm/gkrellm.html
248 Distribution of paraslash is covered by the GNU GPL. See file COPYING.
254 Andre Noll <maan@systemlinux.org>
255 Comments and bug reports are welcome.