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.