documentation update
authorAndre <maan@p133.(none)>
Sat, 13 May 2006 19:38:39 +0000 (21:38 +0200)
committerAndre <maan@p133.(none)>
Sat, 13 May 2006 19:38:39 +0000 (21:38 +0200)
mention aac and clarify the audiod section in INSTALL

FEATURES
INSTALL
NEWS
README

index 7fdd239..e544d62 100644 (file)
--- a/FEATURES
+++ b/FEATURES
@@ -3,24 +3,22 @@ Features
 
 configurable audio streaming software:
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-       para_server streams binary audio data (mp3/ogg files) over
-       local and/or remote networks. It supports three builtin
+       para_server streams binary audio data (mp3/ogg/m4a files)
+       over local and/or remote networks. It supports three builtin
        streaming methods (senders): http, dccp, or rtp.
 
        para_audiod runs on the client side and connects to
        para_server. The audio stream is read from the network and
-       sent through any of paraslash's filters (mp3 decoder, ogg
-       vorbis decoder, volume normalizer,...). The resulting stream
-       is written to an external program's standard in, usually an
-       audio player like para_write, which comes with paraslash and
-       contains an alsa player.  It is possible to capture the stream
-       at any position in the filter chain.
-
-       The receiving/filtering software is also available as
-       standalone command line tool: para_recv reads the stream and
-       writes to stdout; para_filter reads from stdin, converts the
-       stream according to the given --filter command line options
-       and writes the transformed stream to stdout.
+       sent through any of paraslash's filters (decoder, volume
+       normalizer,...). The resulting stream is written to an external
+       program's standard in, usually an audio player like para_write,
+       which comes with paraslash and contains an alsa player. It
+       is possible to capture the stream at any position in the
+       filter chain.
+
+       The receiving/filtering/playing software is also available
+       as standalone command line tool: para_recv, para_filter,
+       and para_write.
 
 configurable audio file selectors:
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -32,8 +30,8 @@ configurable audio file selectors:
        or files given by a playlist respectively.
 
        The (optional) mysql selector is more involved. It manages
-       statistics on your audio files, and audio file selection is
-       done by sending a user-defined sql-query to the mysql server.
+       statistics on your audio files, and audio file selection works
+       by sending a user-defined sql-query to the mysql server.
        This allows rather sophisticated configurations and is
        explained in detail in README.mysql.
 
@@ -44,8 +42,8 @@ small memory footprint:
 ~~~~~~~~~~~~~~~~~~~~~~~
        paraslash is lightweight. The stripped binary of para_server
        with all its features compiled in (mysql/random/playlist
-       selector, mp3/ogg support, http/dccp/ortp support) is about 110K
-       on i386 under Linux. para_audiod is even smaller.
+       selector, mp3/ogg/aac support, http/dccp/ortp support) is
+       about 120K on i386 under Linux. para_audiod is even smaller.
 
 command line interface:
 ~~~~~~~~~~~~~~~~~~~~~~~
@@ -57,7 +55,9 @@ authentication/encryption via openssl:
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
        All connections between para_server and para_client are
        encrypted by default.  For each user of paraslash you must
-       create a public/secret key pair for authentication/encryption.
+       create a public/secret key pair for authentication. The
+       (authenticated) connection is crypted with a symmetric rc4
+       session key.
 
 various user interfaces and utilities:
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
diff --git a/INSTALL b/INSTALL
index adb75c5..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
@@ -92,11 +91,21 @@ Start streaming manually
 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:
+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
 
-       mp3:
+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
@@ -104,14 +113,6 @@ on client_host:
        or
        xmms http://server_host:8000/
 
-       ogg:
-
-       para_recv -r 'http -i server_host' | para_filter -f oggdec -f wav | para_write -w alsa
-
-If this works, proceed. Otherwise doublecheck what is logged by
-para_server and use the --loglevel option of para_recv, para_filter
-to increase verbosity.
-
 Choose an audio file selector
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 paraslash has three different audio file selectors: random (default),
@@ -147,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
diff --git a/NEWS b/NEWS
index 4444f9e..fcf9e52 100644 (file)
--- a/NEWS
+++ b/NEWS
@@ -4,6 +4,9 @@ NEWS
 0.?.? (to be announced) "sonic convolution"
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
+       o aac filter and aac audio format handler (requires libfaad)
+
+
 0.2.12 (2006-05-12) "oriented abstraction"
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 Many user-visible changes in this release and lots of new
diff --git a/README b/README
index 5073ca5..017bc0c 100644 (file)
--- a/README
+++ b/README
@@ -8,11 +8,12 @@ It contains the following programs:
 
 - para_server (obligatory):
 
-       This server 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.
 
-       For audio streaming, at least one of the three supported senders
-       of para_server  must be activated:
+       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...
@@ -24,8 +25,6 @@ It contains the following programs:
        private streams that require authentication.
 
        It is possible to activate more than one sender simultaneously.
-       All senders have the same set of commands that allow to
-       control the access permissions of the stream.
 
        para_server needs an "audio file selector" to work, mainly
        to determine which song to stream next. There are three
@@ -51,7 +50,7 @@ It contains the following programs:
        stdout. This one is independent from the rest of paraslash,
        so it might be useful also for different purposes.
 
-       para_filter combines an mp3 decoder an oggvorbis decoder
+       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
@@ -161,15 +160,19 @@ make sure to install the corresponding development package as well.
 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.
+       decoder, e.g. para_filter or ogg123.
 
                http://www.xiph.org/downloads/
 
 Debian packages: libogg-dev libvorbis-dev
 
-Note that para_audiod still works even if neither mp3 nor ogg 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 aac files (m4a) you'll need libfaad. Get it at
+
+       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: