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