54fb9513b1ac9d5f51c0524a642dfb9959e45ff7
[paraslash.git] / README
1 README
2 ======
3
4 ----
5 Paraslash is an acronym for
6
7 _Play, archive, rate and stream large audio sets happily_
8
9 It contains the following programs:
10
11 -----------------------
12 para_server (obligatory)
13 -----------------------
14
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.
19
20 It supports three builtin streaming methods (senders): http, dccp,
21 or rtp.
22
23 The audio stream may be sent over the network by three different
24 senders:
25
26 * The http sender is recommended for public streams that can be played
27 by any player like mpg123, xmms, itunes, winamp...
28
29 * The dccp sender is experimental and requires kernel support for the
30 rather new datagram congestion control protocol.
31
32 * The ortp sender is recommended for LAN streaming and for private
33 streams that require authentication.
34
35 It is possible to activate more than one sender simultaneously.
36
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
39 built in:
40
41 * The random selector chooses audio files out of a given directory
42 by random
43
44 * The playlist selector chooses files from a specified playlist
45
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.
52
53 It is possible to switch between all supported selectors at any time.
54
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)
59 is even smaller.
60
61 ------------------------
62 para_client (obligatory)
63 -----------------------
64
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.
69
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.
74
75 -------------------
76 para_recv (optional)
77 -------------------
78
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.
81
82 ---------------------
83 para_filter (optional)
84 ---------------------
85
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.
89
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.
95
96 ----------------------
97 para_write (obligatory)
98 ----------------------
99
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.
104
105 ---------------------------------------
106 para_audiod (optional, but recommended)
107 ---------------------------------------
108
109 The local daemon that collects information from para_server.
110
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
116 filter chain.
117
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.
122
123 --------------------------------------
124 para_audioc (optional, but recommended)
125 --------------------------------------
126
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.
130
131 para_audioc (hence para_audiod) is needed by para_gui, para_sdl_gui
132 and para_krell, see below.
133
134 -------------------
135 para_gui (optional)
136 -------------------
137
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
141 be added easily.
142
143 -----------------------
144 para_sdl_gui (optional)
145 -----------------------
146
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.
152
153 -------------------------------------------------------------------------
154 para_krell (optional, only useful in conjunction with the mysql selector)
155 -------------------------------------------------------------------------
156
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).
160
161 --------------------
162 para_fade (optional)
163 --------------------
164
165 A (Linux-only) alarm clock and volume-fader.
166
167 -------------------------------------------------------------------------
168 para_dbadm (optional, only useful in conjunction with the mysql selector)
169 -------------------------------------------------------------------------
170
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).
174
175 --------------------------------------------------------------------------
176 para_slider (optional, only useful in conjunction with the mysql selector)
177 --------------------------------------------------------------------------
178
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.
183
184 --------------------------
185 bash_completion (optional)
186 --------------------------
187
188 A small bash script for inclusion in ~/.bashrc. It gives you command
189 line completion for some paraslash commands.
190
191 ------------
192 Requirements
193 ------------
194
195 In any case you need
196
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)
204
205 If you want to use the mysql-based audio file selector, you also need
206
207 - mysql-server
208 - mysql-client
209 - libmysqlclient
210
211 These are usually shipped with the distro but probably not installed
212 by default.
213
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/
218
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/
223
224 For aac files (m4a) you'll need libfaad. Get it at
225 http://www.audiocoding.com/modules/wiki/?page=AAC
226
227 If you intend to use the optional ortp streamer, you'll need libortp:
228 http://www.linphone.org/ortp/
229
230 For the optional SDL-based gui, the following packages must be installed:
231
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/
235
236 For para_slider, the zero memory widget library is neccessary:
237 http://www710.univ-lyon1.fr/~exco/ZMW/
238
239 Finally, para_krell needs
240
241 - gtk2: http://www.gtk.org/
242 - gkrellm2: http://members.dslextreme.com/users/billw/gkrellm/gkrellm.html
243
244 -------
245 LICENSE
246 -------
247
248 Distribution of paraslash is covered by the GNU GPL. See file COPYING.
249
250 ----------
251 THE AUTHOR
252 ----------
253
254 Andre Noll <maan@systemlinux.org>
255 Comments and bug reports are welcome.