-Paraslash install notes
-=======================
+INSTALL
+=======
+----
Any knowledge of how to work with mouse and icons is not required.
+---------------------------
Install all needed packages
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
+---------------------------
+
See README for a list of required software. Don't be afraid of the long
list of unusal libraries: Most of them are only needed for optional
programs. Autoconf will detect what is installed on your system and
will only build those executables that can be built with your setup.
-
+------------------------
Install server and client
-~~~~~~~~~~~~~~~~~~~~~~~~~
+-------------------------
+
Install the package on all machines, you'd like this software to run on:
(./configure && make) > /dev/null
make install
+-----------------------------------
Setup user list and create rsa keys
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+-----------------------------------
+
If you already have your rsa keys, skip this step. If you are new
to paraslash, you have to generate an rsa key pair for each user you
want to allow to connect. You need at least one user.
Finally, tell para_client to connect to server_host:
- echo 'hostname server_host' > ~/.paraslash/client.conf
+ conf=~/.paraslash/client.conf
+ echo 'hostname server_host' > $conf
+-----------------
Start para_server
-~~~~~~~~~~~~~~~~~
+-----------------
+
For the first try, we'll use the default audio file selector, the
"random" selector which chooses audio files from the given directory
by random. You have to tell para_server via the --random_dir command
to retrieve the list of available commands and some server info.
+------------------------
Start streaming manually
-~~~~~~~~~~~~~~~~~~~~~~~~
+------------------------
para_client play
para_client stat 2
this, try the following on client_host (assuming alsa and an mp3
stream):
- para_recv -r 'http -i server_host' > file.mp3 #interrupt after a few seconds
+ para_recv -r 'http -i server_host' > file.mp3
+ # (interrupt after a few seconds)
ls -l file.mp3 # should not be empty
para_filter -f mp3dec -f wav < file.mp3 > file.wav
ls -l file.wav # should be much bigger than file.mp3
Next, put the pieces together:
- para_recv -r 'http -i server_host' | para_filter -f mp3dec -f wav | para_write -w alsa
+ para_recv -r 'http -i server_host' \
+ | para_filter -f mp3dec -f wav \
+ | para_write -w alsa
or
mpg123 http://server_host:8000/
or
xmms http://server_host:8000/
+-----------------------------
Choose an audio file selector
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+-----------------------------
+
paraslash has three different audio file selectors: random (default),
playlist and mysql.
- The random selector chooses files randomly from the given
- directory.
-
- The playlist selector allows to send a playlist to para_server
- via the lpl (load playlist) command. para_server will choose
- files from the loaded playlist in sequential order.
-
- The mysql selector stores information about your audio
- files in a mysql database. It is much more involved than
- the other two selectors and lets you chose files in many
- interesting ways. If you like to use the mysql selector,
- read README.mysql and follow the instructions given there.
- Return to this document when ready.
+ - The random selector chooses files randomly from the given
+ directory.
+ - The playlist selector allows to send a playlist to para_server
+ via the lpl (load playlist) command. para_server will choose
+ files from the loaded playlist in sequential order.
+ - The mysql selector stores information about your audio
+ files in a mysql database. It is much more involved than
+ the other two selectors and lets you chose files in many
+ interesting ways. If you like to use the mysql selector,
+ read README.mysql and follow the instructions given there.
+ Return to this document when ready.
The current audio file selector can be changed at runtime via
para_client chs new_selector
-
+---------------------
Configure para_audiod
-~~~~~~~~~~~~~~~~~~~~~
+---------------------
+
In order to automatically start the right decoder at the right time
and to offer to the clients some information on the current audio
stream and on paraslash's internal state, you should run the local
para_audioc term
para_audioc cycle
-
+--------------
Start para_gui
-~~~~~~~~~~~~~~
+--------------
+
para_gui reads the output of "para_audioc stat" and displays that
information in a curses window. It also allows you to bind keys to
arbitrary commands. There are several flavours of key-bindings:
- o internal: These are the built-in commands that can not be
- changed (help, quit, loglevel, version...).
-
- o external: Shutdown curses before launching the given command.
- Useful for starting other ncurses programs from within
- para_gui, e.g. aumix or para_dbadm. Or, use
-
- para_client mbox
-
- to write a mailbox containing one mail for each file
- in the mysql database and start mutt from within para_gui
- to browse your collection!
-
- o display: Launch the command and display its stdout in
- para_gui's bottom window.
-
- o para: Like display, but start "para_client <specified
- command>" instead of "<specified command>".
+ - internal: These are the built-in commands that can not be
+ changed (help, quit, loglevel, version...).
+ - external: Shutdown curses before launching the given command.
+ Useful for starting other ncurses programs from within
+ para_gui, e.g. aumix or para_dbadm. Or, use "para_client
+ mbox" to write a mailbox containing one mail for each file
+ in the mysql database and start mutt from within para_gui
+ to browse your collection!
+ - display: Launch the command and display its stdout in
+ para_gui's bottom window.
+ - para: Like display, but start "para_client <specified
+ command>" instead of "<specified command>".
That's all, congratulations. Check out all the other optional gimmics!
-Paraslash README
-================
+README
+======
+
+----
Paraslash is an acronym for
- Play, archive, rate and stream large audio sets happily
+_Play, archive, rate and stream large audio sets happily_
It contains the following programs:
-- para_server (obligatory):
+-----------------------
+para_server (obligatory)
+-----------------------
- This server supports audio streaming of mp3, ogg vorbis and
- aac files. It listens on a tcp port and accepts commands
- such as play, stop, pause, next from authenticated clients.
+This server supports audio streaming of mp3, ogg vorbis and aac files.
+It listens on a tcp port and accepts commands such as play, stop,
+pause, next from authenticated clients.
- The audio stream may be sent over the network by three
- different senders:
+The audio stream may be sent over the network by three different
+senders:
- The http sender is recommended for public streams that can
- be played by any player like mpg123, xmms, winamp...
+The http sender is recommended for public streams that can be played
+by any player like mpg123, xmms, winamp...
- The dccp sender is experimental and requires kernel support
- for the rather new datagram congestion control protocol.
+The dccp sender is experimental and requires kernel support for the
+rather new datagram congestion control protocol.
- The ortp sender is recommended for LAN streaming and for
- private streams that require authentication.
+The ortp sender is recommended for LAN streaming and for private
+streams that require authentication.
- It is possible to activate more than one sender simultaneously.
+It is possible to activate more than one sender simultaneously.
- para_server needs an "audio file selector" to work, mainly
- to determine which song to stream next. There are three
- selectors available: random, playlist and mysql. The former
- chooses audio files randomly and playlist can handle, well,
- playlists. Both are always supported.
+para_server needs an "audio file selector" to work, mainly to determine
+which song to stream next. There are three selectors available:
+random, playlist and mysql. The former chooses audio files randomly
+and playlist can handle, well, playlists. Both are always supported.
- The optional mysql selector connects to a mysql server which
- holds information on your audio files. It has several unusual
- features, see README.mysql for details.
+The optional mysql selector connects to a mysql server which holds
+information on your audio files. It has several unusual features,
+see README.mysql for details.
-- para_client (obligatory):
+------------------------
+para_client (obligatory)
+-----------------------
- The client program to connect to para_server.
+The client program to connect to para_server.
-- para_recv (optional)
+-------------------
+para_recv (optional)
+-------------------
- A command line http/dccp/rtp stream grabber.
+A command line http/dccp/rtp stream grabber.
-- para_filter (optional)
+---------------------
+para_filter (optional)
+---------------------
- A filter program that converts from stdin and writes to
- stdout. This one is independent from the rest of paraslash,
- so it might be useful also for different purposes.
+A filter program that converts from stdin and writes to stdout. This
+one is independent from the rest of paraslash, so it might be useful
+also for different purposes.
- para_filter combines several decoders (mp3, oggvorbis, aac)
- and a volume normalzer. New filters can be added easily due
- to the modular design. If more than one filter is specified,
- the given filters are 'piped' together in-memory, i.e. without
- calling any of the read(2)/write(2)/select(2) etc. functions.
+para_filter combines several decoders (mp3, oggvorbis, aac) and a
+volume normalzer. New filters can be added easily due to the modular
+design. If more than one filter is specified, the given filters
+are 'piped' together in-memory, i.e. without calling any of the
+read(2)/write(2)/select(2) etc. functions.
-- para_write (obligatory)
+----------------------
+para_write (obligatory)
+----------------------
- A modular audio stream writer. It supports a simple file
- writer output plugin and an optional wav/raw player for alsa.
- Debian package: libasound2-dev
+A modular audio stream writer. It supports a simple file writer output
+plugin and an optional wav/raw player for alsa. Debian package:
+libasound2-dev
-- para_audiod (optional, but recommended):
+---------------------------------------
+para_audiod (optional, but recommended)
+---------------------------------------
- The local daemon that collects information from para_server. It
- starts an appropriate receiver, filter and player as soon
- as para_server announces the availability (and the type) of
- an audio stream. para_audiod listens on a local socket and
- sends status information about para_server and para_audiod
- to local clients on request.
+The local daemon that collects information from para_server. It
+starts an appropriate receiver, filter and player as soon as
+para_server announces the availability (and the type) of an audio
+stream. para_audiod listens on a local socket and sends status
+information about para_server and para_audiod to local clients
+on request.
-- para_audioc (optional, but recommended)
+--------------------------------------
+para_audioc (optional, but recommended)
+--------------------------------------
- The client program which talks with para_audiod. Used to
- control para_audiod, to receive status info, or to grab the
- stream at any point in the filter chain.
+The client program which talks with para_audiod. Used to control
+para_audiod, to receive status info, or to grab the stream at any
+point in the filter chain.
- para_audioc (hence para_audiod) is needed by para_gui,
- para_sdl_gui and para_krell, see below.
+para_audioc (hence para_audiod) is needed by para_gui, para_sdl_gui
+and para_krell, see below.
-- para_gui (optional):
+-------------------
+para_gui (optional)
+-------------------
- Themable ncurses-based gui. It calls para_audioc and presents
- the obtained information in an ncurses window. para_gui
- provides key-bindings for the most common commands and new
- key-bindings can be added easily.
+Themable ncurses-based gui. It calls para_audioc and presents
+the obtained information in an ncurses window. para_gui provides
+key-bindings for the most common commands and new key-bindings can
+be added easily.
-- para_sdl_gui (optional):
+-----------------------
+para_sdl_gui (optional)
+-----------------------
- SDL-based gui. Similar to para_gui but presents its output
- in an X window (fullscreen mode is also available) and can
- display jpg images on a per song basis. para_sdl_gui provides
- an input prompt to enter arbitrary commands. However, it
- can also be used non-interactively (e.g. as a screen saver)
- via the -i switch.
+SDL-based gui. Similar to para_gui but presents its output in an X
+window (fullscreen mode is also available) and can display jpg images
+on a per song basis. para_sdl_gui provides an input prompt to enter
+arbitrary commands. However, it can also be used non-interactively
+(e.g. as a screen saver) via the -i switch.
-- para_krell (optional, only useful in conjunction with the mysql selector):
+-------------------------------------------------------------------------
+para_krell (optional, only useful in conjunction with the mysql selector)
+-------------------------------------------------------------------------
- A plugin for gkrellm which shows small pictures of the
- current song. It allows you to launch 27 different commands
- by clicking in different areas of its picture (9 small squares
- x 3 mouse buttons).
+A plugin for gkrellm which shows small pictures of the current song. It
+allows you to launch 27 different commands by clicking in different
+areas of its picture (9 small squares x 3 mouse buttons).
-- para_fade (optional):
+--------------------
+para_fade (optional)
+--------------------
- A (Linux-only) alarm clock and volume-fader.
+A (Linux-only) alarm clock and volume-fader.
-- para_dbadm (optional, only useful in conjunction with the mysql selector):
+-------------------------------------------------------------------------
+para_dbadm (optional, only useful in conjunction with the mysql selector)
+-------------------------------------------------------------------------
- Very simple curses-based frontend which uses libmenu. Useful
- for quickly changing the attributes of the current song
- (e.g. from para_gui as an external command).
+Very simple curses-based frontend which uses libmenu. Useful for
+quickly changing the attributes of the current song (e.g. from para_gui
+as an external command).
-- para_slider (optional, only useful in conjunction with the mysql selector):
+--------------------------------------------------------------------------
+para_slider (optional, only useful in conjunction with the mysql selector)
+--------------------------------------------------------------------------
- A small X application which shows a scrollbar for each
- attribute defined in the mysql database. It creates a stream
- definition from the values of the scrollbars. This allows
- to smoothly change the mood of the given stream without any
- file editing.
+A small X application which shows a scrollbar for each attribute
+defined in the mysql database. It creates a stream definition from
+the values of the scrollbars. This allows to smoothly change the mood
+of the given stream without any file editing.
-- bash_completion (optional):
+--------------------------
+bash_completion (optional)
+--------------------------
- A small bash script for inclusion in ~/.bashrc. It gives you
- command line completion for some paraslash commands.
+A small bash script for inclusion in ~/.bashrc. It gives you command
+line completion for some paraslash commands.
+
+------------
+Requirements
+------------
-REQUIREMENTS:
-~~~~~~~~~~~~~
In any case you need
- gcc, the gnu compiler collection (shipped with distro): gcc-3.3
- or newer is required.
-
+ or newer is required.
- openssl (needed by server, client): usually shipped with
- distro, but you might have to install the "development"
- package as well
-
- http://www.openssl.org/
-
+ distro, but you might have to install the "development"
+ package as well: http://www.openssl.org/
- software mixing, e.g. ALSA and the direct mixing plugin (dmix)
If you want to use the mysql-based audio file selector, you also need
These are usually shipped with the distro but probably not installed
by default.
-The mp3 decoder of para_filter is based on libmad:
-
- http://www.underbit.com/products/mad/
-
-If you prefer to use the libmad package provided by your distributor,
-make sure to install the corresponding development package as well.
+The mp3 decoder of para_filter is based on libmad: If you prefer to
+use the libmad package provided by your distributor, make sure to
+install the corresponding development package as well. Otherwise,
+just download libmad from http://www.underbit.com/products/mad/
-If you want to stream ogg vorbis files you'll need:
-
- - libogg, libvorbis, libvorbisfile, and a command line ogg vorbis
- decoder, e.g. para_filter or ogg123.
-
- http://www.xiph.org/downloads/
-
-Debian packages: libogg-dev libvorbis-dev
+For ogg vorbis streams you'll need libogg, libvorbis, libvorbisfile,
+and a command line ogg vorbis decoder, e.g. para_filter or ogg123.
+The corresponding Debian packages are called libogg-dev libvorbis-dev,
+other distributors chose similar names. All of these are also
+available at http://www.xiph.org/downloads/
For aac files (m4a) you'll need libfaad. Get it at
+http://www.audiocoding.com/modules/wiki/?page=AAC
- http://www.audiocoding.com/modules/wiki/?page=AAC
-
-Note that para_audiod still works even if no audio file support was
-compiled in. You'll have to use the --no_default_filters option in this
-case (and e.g. "mpg123 -" as the stream write command for mp3 streams).
-
-If you intend to use the optional ortp streamer:
-
- - libortp
-
- http://www.linphone.org/ortp/
-
+If you intend to use the optional ortp streamer, you'll need libortp:
+http://www.linphone.org/ortp/
For the optional SDL-based gui, the following packages must be installed:
- - X (usually shipped with distro)
-
- http://www.x.org/
-
- - libSDL (usually shipped with distro)
-
- http://www.libsdl.org/index.php
-
- - SDL_image
+ - X (usually shipped with distro): http://www.x.org/
+ - libSDL (usually shipped with distro): http://www.libsdl.org/index.php
+ - SDL_image: http://www.libsdl.org/projects/SDL_image/
- http://www.libsdl.org/projects/SDL_image/
-
-For para_slider, the zero memory widget library is neccessary. Get it at
-
- http://www710.univ-lyon1.fr/~exco/ZMW/
+For para_slider, the zero memory widget library is neccessary:
+http://www710.univ-lyon1.fr/~exco/ZMW/
Finally, para_krell needs
- - gtk2
-
- http://www.gtk.org/
+ - gtk2: http://www.gtk.org/
+ - gkrellm2: http://members.dslextreme.com/users/billw/gkrellm/gkrellm.html
- - gkrellm2
+-------
+LICENSE
+-------
- http://members.dslextreme.com/users/billw/gkrellm/gkrellm.html
-
-LICENSE:
-~~~~~~~~
Distribution of paraslash is covered by the GNU GPL. See file COPYING.
-THE AUTHOR:
-~~~~~~~~~~~
-Author: Andre Noll <maan@systemlinux.org>
+----------
+THE AUTHOR
+----------
+
+Andre Noll <maan@systemlinux.org>
Comments and bug reports are welcome.
+============
README.mysql
============
+----
This file describes how to use the mysql audio file selector which
comes with the paraslash package.
First of all, make sure that
- mysqld is running
-
- para_server is running and compiled with mysql support
- (type "para_client si" to find out)
-
+ (type "para_client si" to find out)
- the user who runs para_client has the paraslash DB_WRITE
- and DB_READ permissions set in server.users
-
+ and DB_READ permissions set in server.users
- the user who runs para_server has create privileges on the
- mysql server.
+ mysql server.
Remember: If something doesn't work as expected, look at the server
log file and/or increase output verbosity by using the -l switch for
server and client.
-
+------------------------------------
Specify mysql data (port, passwd,...)
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+------------------------------------
Type
Or, restart the server.
+---------------------------------------
Switch to the mysql audio file selector
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+---------------------------------------
The command
--enable-mysql-libs=/Library/MySQL/lib/mysql
+---------------------
Create a new database
-~~~~~~~~~~~~~~~~~~~~~
+---------------------
Once the mysql selector is activated, create the database:
The second command forces para_server to re-init the mysql selector.
Check the log. There should not be any warnings or errors.
-
+-------------------------------
Fill your database with content
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+-------------------------------
para_client upd
prints the list of all files known by the mysql selector. If the list
is empty, double check the mysql_audio_file_dir option.
+---------------------------------------
+Create a stream which selects all files
+---------------------------------------
-Create a stream which selects all songs
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-To keep it simple, let's only define the stream "all_songs". See below for
-advanced stream usage.
+To keep it simple, let's only define the stream "all_songs". See
+below for advanced stream usage.
para_client stradd all_songs < /dev/null
para_client sl 10 all_songs
The latter command should show you ten filenames.
-
+------------------------------
Change to the all_songs stream
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+------------------------------
para_client cs all_songs
para_client play
-
+---------------
Attribute usage
-~~~~~~~~~~~~~~~
+---------------
An attribute is simply a bit which can be set for each audio file
individually. You may have as many attributes as you like. A new
para_client da test
+------------
Stream usage
-~~~~~~~~~~~~
+------------
A stream is a pair of expressions in terms of attributes and other data
contained in the database. The first, boolian, expression determines
Example:
+~~~~~~~~
- Assume you already have an attribute "test" and you'd like to
- to restrict audio streaming to those files having the "test"
- attribute set. Define a new stream "only_test" by
+Assume you already have an attribute "test" and you'd like to to
+restrict audio streaming to those files having the "test" attribute
+set. Define a new stream "only_test" by
- echo 'accept: IS_SET(test)' | para_client stradd only_test
+ echo 'accept: IS_SET(test)' | para_client stradd only_test
- Then, after switching to the "only_test" stream with
+Then, after switching to the "only_test" stream with
- para_client cs only_test
+ para_client cs only_test
- only the desired files are going to be streamed.
+only the desired files are going to be streamed.
There is no need to keep the temporary files containing the stream
definition since you can always use the strq command to get it back:
The accept/deny expressions are used to find out which songs are
permitted. The following four cases are all possible and valid:
- o Neither accept nor deny lines: This selects all songs.
+ - Neither accept nor deny lines: This selects all songs.
- o Only accept lines: Songs that match at least one accept
- expression are accepted, all others are denied:
+ - Only accept lines: Songs that match at least one accept
+ expression are accepted, all others are denied:
accept_expr1 or accept_expr2 or ...
- o Only deny lines: Songs that match at least one deny expression are
- denied, all others are accepted:
+ - Only deny lines: Songs that match at least one deny expression are
+ denied, all others are accepted:
not (deny_expr1 or deny_expr2 ...)
- o Both accept and deny lines: A song is accepted if it matches
- at least one accept expression, but no deny expression, i.e.
+ - Both accept and deny lines: A song is accepted if it matches
+ at least one accept expression, but no deny expression, i.e.
(accept_expr1 or accept_expr2 or ..) and not
(deny_expr1 or deny_expr2 ..)
is true for a given audio file if and only if it has the attribute
"foo" set. Here are some more macros you can use:
- o IS_N_SET(attr): True if attribute attr is not set
-
- o NAME_LIKE(string): True if basename is like (in the sense
- of mysql) "string"
-
- o LASTPLAYED(): Expands to number of minutes that are gone
- since this audio file has been played (by paraslash).
-
- o NUMPLAYED(): Expands to number of times, the file has
- been played.
-
- o PICID(): Expands to the number of the picture which is
- associated with this song.
+ - IS_N_SET(attr): True if attribute attr is not set
+ - NAME_LIKE(string): True if basename is like (in the sense
+ of mysql) "string"
+ - LASTPLAYED(): Expands to number of minutes that are gone
+ since this audio file has been played (by paraslash).
+ - NUMPLAYED(): Expands to number of times, the file has
+ been played.
+ - PICID(): Expands to the number of the picture which is
+ associated with this song.
To give a real-life example, suppose you have already added the
attributes "pop", "rock" with the "na" command. Assume also that you
but not the order in which these are streamed. That's where the score
expression comes into play.
+-------
Scoring
-~~~~~~~
+-------
+
You may put a single score line anywhere in the stream definition. If
omitted, the default scoring rule specified in the configuration file
applies. If there is no default scoring rule in the config file either,
score: 40 * IS_SET(foo) + 20 * NAME_LIKE(%bar%) + LASTPLAYED()/1440
-
-Pictures
-~~~~~~~~
+------
+Images
+------
The mysql selector can also magage images that, when associated
with one or more audio files, can be displayed by para_sdl_gui and
projects / paraslash.git / commitdiff