README

   1 Paraslash README
   2 ================
   3 Paraslash is an acronym for
   4
   5         Play, archive, rate and stream large audio sets happily
   6
   7 It contains the following programs:
   8
   9 - para_server (obligatory):
  10
  11         This server listens on a tcp port and accepts commands such as
  12         play, stop, pause, next. However, there are many more commands.
  13
  14         For audio streaming, at least one sender must be activated.
  15         At the moment, paraslash contains two internal senders:
  16
  17         The http sender is recommended for public streams that can
  18         be played by any player like mpg123, xmms, winamp...
  19
  20         The ortp sender is recommended for LAN streaming and for
  21         private streams that require authentication.
  22
  23         It is possible to activate more than one sender simultaneously.
  24         All senders have the same set of commands that allow to
  25         control the access permissions of the stream.
  26
  27         para_server needs a "database tool" to work, mainly to
  28         determine which song to stream next. There are three such
  29         tools available: random, plm and mysql. The former chooses
  30         audio files randomly and plm, the playlist manager, can handle
  31         playlists. Both are always supported.
  32
  33         The (optional) mysql database tool connects to a mysql server
  34         which holds information on your audio files. It has several
  35         unusual features, see README.mysql for details.
  36
  37 - para_client (obligatory):
  38
  39         The client program to connect to para_server.
  40
  41 - para_recv (optional)
  42
  43         A command line http/ortp stream grabber.
  44
  45 - para_filter (optional)
  46
  47         An filter program that converts from stdin and writes to
  48         stdout. This one is independent from the rest of paraslash,
  49         so it might be useful also for different purposes.
  50
  51         para_filter combines an mp3 decoder an oggvorbis decoder
  52         and a volume normalzer. New filters can be added easily due
  53         to the modular design. If more than one filter is specified,
  54         the given filters are 'piped' together in-memory, i.e. without
  55         calling any of the read(2)/write(2)/select(2) etc. functions.
  56
  57 - para_play (optional)
  58
  59         A small wav/raw player for alsa.
  60
  61 - para_audiod (optional, but recommended):
  62
  63         The local daemon that starts playback and collects information
  64         from para_server to be forwarded to local clients.
  65
  66         para_audiod reads the audio stream from the network if
  67         para_server indicates that there is a stream available. It may
  68         be sent through any of the supported filters (see para_filter
  69         above) before the result is fed to the output software
  70         (default: para_play) which must be capable of reading from
  71         stdin, but is not restricted otherwise.
  72
  73 - para_audioc (optional, but recommended)
  74
  75         A small client that can talk to para_audiod. Used to control
  76         para_audiod and to receive status info. It can also be used to
  77         grab the stream at any point in the filter chain. para_audioc
  78         is needed by para_gui, para_sdl_gui and para_krell, see below.
  79
  80 - para_gui (optional, but recommended):
  81
  82         Themable ncurses-based gui. It calls para_audioc and presents
  83         the obtained information in an ncurses window. para_gui
  84         provides key-bindings for the most common commands and new
  85         key-bindings can be added easily.
  86
  87 - para_sdl_gui (optional):
  88
  89         SDL-based gui. Similar to para_gui but presents its output in
  90         an X window (fullscreen mode is also available) and can display
  91         jpg images on a per song basis. para_sdl_gui provides an input
  92         prompt to enter arbitrary commands. However, it can also be used
  93         non-interactively (e.g. as a screen saver) via the -i switch.
  94
  95 - para_krell (optional, only useful in conjunction with the mysql dbtool):
  96
  97         A plugin for gkrellm which shows small pictures of the
  98         current song. It allows you to launch 27 different commands
  99         by clicking in different areas of its picture (9 small squares
 100         x 3 mouse buttons).
 101
 102 - para_fade (optional):
 103
 104         A (Linux-only) alarm clock and volume-fader.
 105
 106 - para_dbadm (optional, only useful in conjunction with the mysql dbtool):
 107
 108         Very simple curses-based frontend which uses libmenu. Useful
 109         for quickly changing the attributes of the current song
 110         (e.g. from para_gui as an external command).
 111
 112 - para_slider (optional, only useful in conjunction with the mysql dbtool):
 113
 114         A small X application which shows a scrollbar for each
 115         attribute defined in the mysql database. It creates a stream
 116         definition from the values of the scrollbars. This allows
 117         to smoothly change the mood of the given stream without any
 118         file editing.
 119
 120 - bash_completion (optional):
 121
 122         A small bash script for inclusion in ~/.bashrc. It gives you
 123         command line completion for some paraslash commands.
 124
 125 REQUIREMENTS:
 126 ~~~~~~~~~~~~~
 127 In any case you need
 128
 129         - gcc, the gnu compiler collection (shipped with distro): gcc-3
 130         or newer is prefered, but gcc-2.95 is still supported. Note
 131         that gcc-2.95 may spit out many warnings like unused function
 132         parameters and missing initializers. These are all harmless
 133         and may be ignored.
 134
 135         - openssl (needed by server, client): usually shipped with
 136         distro, but you might have to install the "development"
 137         package as well
 138
 139                 http://www.openssl.org/
 140
 141         - software mixing, e.g. ALSA and the direct mixing plugin (dmix)
 142
 143 If you want to use the mysql-based dbtool (recommended), you also need
 144
 145         - mysql-server
 146         - mysql-client
 147         - libmysqlclient
 148
 149 These are usually shipped with the distro but probably not installed
 150 by default.
 151
 152 The mp3 decoder of para_filter is based on libmad:
 153
 154                 http://www.underbit.com/products/mad/
 155
 156 If you prefer to use the libmad package provided by your distributor,
 157 make sure to install the corresponding development package as well.
 158
 159 If you want to stream ogg vorbis files you'll need:
 160
 161         - libogg, libvorbis, libvorbisfile, and a command line ogg vorbis
 162                 player, e.g. para_filter or ogg123.
 163
 164                 http://www.xiph.org/downloads/
 165
 166 Note that para_audiod still works even if neither mp3 nor ogg support
 167 was compiled in. You'll have to use the --no_default_filters option
 168 in this case (and e.g. "mpg123 -" as the stream write command).
 169
 170 If you intend to use the optional ortp streamer:
 171
 172         - libortp
 173
 174                 http://www.linphone.org/ortp/
 175
 176
 177 For the optional SDL-based gui, the following packages must be installed:
 178
 179         - X (usually shipped with distro)
 180
 181                 http://www.x.org/
 182
 183         - libSDL (usually shipped with distro)
 184
 185                 http://www.libsdl.org/index.php
 186
 187         - SDL_image
 188
 189                 http://www.libsdl.org/projects/SDL_image/
 190
 191 For para_slider, the zero memory widget library is neccessary. Get it at
 192
 193                 http://www710.univ-lyon1.fr/~exco/ZMW/
 194
 195 Finally, para_krell needs
 196
 197         - gtk2
 198
 199                 http://www.gtk.org/
 200
 201         - gkrellm2
 202
 203                 http://members.dslextreme.com/users/billw/gkrellm/gkrellm.html
 204
 205 LICENSE:
 206 ~~~~~~~~
 207 Distribution of paraslash is covered by the GNU GPL. See file COPYING.
 208
 209 LIMITATIONS:
 210 ~~~~~~~~~~~~
 211 The mysql database tool assumes that the basenames of your audio files
 212 are unique. If this is not the case, don't use this database tool,
 213 rename your files, or create your own database tool.
 214
 215 THE AUTHOR:
 216 ~~~~~~~~~~~
 217 Author: Andre Noll <maan@systemlinux.org>
 218 Comments and bug reports are welcome.