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 encrypted
  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 normalizer 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 plug-in 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 plug-in
 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.