trivial loglevel adjustements
[paraslash.git] / INSTALL
diff --git a/INSTALL b/INSTALL
index 41a45c4..9e53e1f 100644 (file)
--- a/INSTALL
+++ b/INSTALL
@@ -22,7 +22,6 @@ software). Then, as root,
 
        make install
 
-
 Setup user list and create rsa keys
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 If you already have your rsa keys, skip this step. If you are new
@@ -32,7 +31,8 @@ want to allow to connect. You need at least one user.
 Let's assume that you'd like to run the server on host server_host
 as user foo, and that you want to connect from client_host as user bar.
 
-As foo@server_host, create ~/.paraslash/server.users:
+As foo@server_host, create ~/.paraslash/server.users by typing the
+following commands:
 
        target=~/.paraslash/server.users
        key=~/.paraslash/key.pub.bar
@@ -54,7 +54,9 @@ Next, extract its public part:
        pubkey=~/.paraslash/key.pub.bar
        openssl rsa -in $key -pubout -out $pubkey
 
-and copy the public key just created to server_host:
+and copy the public key just created to server_host (you may
+skip this step for a single-user setup, i.e. if foo=bar and
+server_host=client_host):
 
        scp $pubkey foo@server_host:.paraslash/
 
@@ -64,7 +66,12 @@ Finally, tell para_client to connect to server_host:
 
 Start para_server
 ~~~~~~~~~~~~~~~~~
-       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
+line option where this selector should look for audio files.
+
+       para_server --random_dir=/my/mp3/directory
 
 Now you can use para_client to connect to the server and issue
 commands. Open a new shell (as "bar" on "client_host" in the above
@@ -75,11 +82,41 @@ example) and try
 
 to retrieve the list of available commands and some server info.
 
+Start streaming manually
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+       para_client play
+       para_client stat 2
+
+This starts streaming and dumps some information on the current song
+to stdout.
+
+You should now be able to receive and listen to the stream. To check
+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
+       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
+       para_write -w alsa < file.wav
+
+If this works, proceed. Otherwise doublecheck what is logged by
+para_server and use the --loglevel option of para_recv, para_filter
+and para_write to increase verbosity.
+
+Next, put the pieces together:
+
+       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),
-plm (the playlist manager) and mysql.
+playlist and mysql.
 
        The random selector chooses files randomly from the given
        directory.
@@ -97,38 +134,8 @@ plm (the playlist manager) and mysql.
 
 The current audio file selector can be changed at runtime via
 
-       para_client cdt new_selector
-
-
+       para_client chs new_selector
 
-Start streaming manually
-~~~~~~~~~~~~~~~~~~~~~~~~
-
-       para_client play
-       para_client stat 2
-
-This starts streaming and dumps some information on the current song
-to stdout.
-
-You should now be able to listen to the stream with any player
-capable of reading from stdin. To check this, try the following
-on client_host:
-
-       mp3:
-
-       para_recv -r 'http -i server_host' | para_filter -f mp3dec -f wav | para_play
-       or
-       mpg123 http://server_host:8000/
-       or
-       xmms http://server_host:8000/
-
-       ogg:
-
-       para_recv -r 'http -i server_host' | para_filter -f oggdec -f wav | para_play
-
-If this works, proceede. Otherwise doublecheck what is logged by
-para_server and use the --loglevel option of para_recv, para_filter
-to increase verbosity.
 
 Configure para_audiod
 ~~~~~~~~~~~~~~~~~~~~~
@@ -141,17 +148,24 @@ the audio stream. Try
        para_audiod -h
 
 for help. Usually you have to specify at least server_host as the
-receiver specifier, like this:
+receiver specifier for each supported audio format, like this:
 
        -r 'mp3:http -i server_host'
 
 The prefered way to use para_audiod is to run it once at system start
 as an unprivileged user. para_audiod needs to create a "well-known"
-socket for the clients to connect to. If you want to change the
-default socket (e.g. because you do not have write access for the
-directory where the socket resides), use the -s option or the config
-file to change the default. Note that in this case you'll also have
-to specify the same value for para_audioc's -s option.
+socket for the clients to connect to. The default path for this
+socket is
+
+       /var/paraslash/audiod_socket.$HOSTNAME
+
+so the /var/paraslash directory should be owned by the user who
+runs para_audiod.
+
+If you want to change location of the default socket, use the -s
+option for para_audiod or the config file ~/.paraslash/audiod.conf
+to change the default. Note that in this case you'll also have to
+specify the same value for para_audioc's -s option.
 
 If para_server is playing, you should be able to listen to the audio
 stream as soon as para_audiod is started.  Once it is running, try
@@ -174,23 +188,23 @@ 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...).
+       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
+       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!
+       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.
+       para_gui's bottom window.
 
        o para: Like display, but start "para_client <specified
-         command>" instead of "<specified command>".
+       command>" instead of "<specified command>".
 
 
 That's all, congratulations. Check out all the other optional gimmics!