documentation update

mention aac and clarify the audiod section in INSTALL

diff --git a/FEATURES b/FEATURES
index 7fdd23996732a677765c6f4e850a92b14a69d182..e544d625da66968a48b291aea35e12e19a9efbeb 100644 (file)
--- a/FEATURES
+++ b/FEATURES
@@ -3,24 +3,22 @@ Features
 
 configurable audio streaming software:
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 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
        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:
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 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
        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.
 
        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
 ~~~~~~~~~~~~~~~~~~~~~~~
        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:
 ~~~~~~~~~~~~~~~~~~~~~~~
 
 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
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
        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:
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 various user interfaces and utilities:
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

diff --git a/INSTALL b/INSTALL
index adb75c5c6e02c0f8528485d3fa3d959762b1e801..9e53e1f3dbeccf49b6ee8647673823ee54bef7c2 100644 (file)
--- a/INSTALL
+++ b/INSTALL
@@ -22,7 +22,6 @@ software). Then, as root,
 
        make install
 
 
        make install
 

-

 Setup user list and create rsa keys
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 If you already have your rsa keys, skip this step. If you are new
 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.
 
 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
 
        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/
 
        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),
 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
        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"
 
        -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
 
 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 4444f9e0123516d2a02db1872e1b1a05dc2e26e4..fcf9e52053416c38e1d08e4acb853784a2b6f524 100644 (file)
--- a/NEWS
+++ b/NEWS
@@ -4,6 +4,9 @@ NEWS
 0.?.? (to be announced) "sonic convolution"
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 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
 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 5073ca55e4b9542db34787910277401db7d0048a..017bc0c31d71e4d984783d5d0a6a2e3a46a2fc14 100644 (file)
--- a/README
+++ b/README
@@ -8,11 +8,12 @@ It contains the following programs:
 
 - para_server (obligatory):
 
 
 - 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...
 
        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.
        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
 
        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.
 
        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
        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
 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
 
 
                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:
 
 
 If you intend to use the optional ortp streamer: