add documentation for the new RTP modules

git-svn-id: file:///home/lennart/svn/public/pulseaudio/trunk@731 fefdeb5f-60dc-0310-8127-8f9354f1896f

3 files changed, 184 insertions, 24 deletions

diff --git a/doc/FAQ.html.in b/doc/FAQ.html.in
index 0e7382178..7adc24414 100644
--- a/doc/FAQ.html.in
+++ b/doc/FAQ.html.in
@@ -67,7 +67,7 @@
 <tt>realtime</tt>, or increase the fragment sizes of the audio
   drivers. The former will allow Polypaudio to activate
   <tt>SCHED_FIFO</tt> high priority scheduling (root rights are dropped
-  immediately after this) Keep in mind that this is a potential security hole!</p></li>
+  immediately after this). Keep in mind that this is a potential security hole!</p></li>
 
    <li><p><b>The <tt>polypaudio</tt>  executable is installed SUID root by default. Why this? Isn't this a potential security hole?</b></p>
 
@@ -103,7 +103,12 @@ in <tt>~/.polypaudio/</tt>.</p></li>
 
 <li><p><b>How do I use polypaudio over the network?</b></p>
 
-<p>Just set <tt>$POLYP_SERVER</tt> to the host name of the polypaudio server.</p>
+<p>Just set <tt>$POLYP_SERVER</tt> to the host name of the polypaudio
+server. For authentication you need the same auth cookies on all sides. For
+that copy <tt>~./polypaudio-cookie</tt> to all clients that shall
+be allowed to connect.</p>
+
+<p>Alternatively the authorization cookies can be stored in the X11 server.</p></li>
 
 <li><p><b>Is polypaudio capable of providing synchronized audio playback over the network for movie players like <tt>mplayer</tt>?</b></p>
 
@@ -126,7 +131,7 @@ connect to a running polypaudio daemon try using the following commands:</p>
 <pre>killall -USR2 polypaudio
 bidilink unix-client:/tmp/polypaudio/cli</pre>
 
-<p><i>BTW: Someone should package that great tool for Debian!</i></p>
+<p><i>BTW: Someone should package this great tool for Debian!</i></p>
 
 <p><b>New:</b> There's now a tool <tt>pacmd</tt> that automates sending SIGUSR2 to the daemon and running a bidilink like tool for you.</p>
 </li>
@@ -146,7 +151,91 @@ bidilink unix-client:/tmp/polypaudio/cli</pre>
 </li>
 
 <li><p><b>Why the heck does libpolyp link against libX11?</b></p>
-<p>The Polypaudio client libraries look for some X11 root window properties for the credentials of the Polypaudio server to access. You may compile Polypaudio without X11 for disabling this.</p></li>
+<p>The Polypaudio client libraries look for some X11 root window
+properties for the credentials of the Polypaudio server to access. You
+may compile Polypaudio without X11 for disabling this feature.</p></li>
+
+<li><p><b>How can I use Polypaudio as an RTP based N:N multicast
+conferencing solution for the LAN?</b></p> <p>After loading all the
+necessary audio drivers for recording and playback, just load the RTP
+reciever and sender modules with default parameters:</p>
+
+<pre>
+load-module module-rtp-send
+load-module module-rtp-recv
+</pre>
+
+<p>As long as the Polypaudio daemon runs, the microphone data will be
+streamed to the network and the data from other hosts is played back
+locally. Please note that this may cause quite a lot of traffic. Hence
+consider passing <tt>rate=8000 format=ulaw channels=1</tt> to the
+sender module to save bandwith while still maintaining good quality
+for speech transmission.</p></li>
+
+<li><p><b>What is this RTP/SDP/SAP thing all about?</b></p>
+
+<p>RTP is the <i>Realtime Transfer Protocol</i>. It is a well-known
+protocol for transferring audio and video data over IP. SDP is the <i>Session
+Description Protocol</i> and can be used to describe RTP sessions. SAP
+is the <i>Session Announcement Protocol</i> and can be used to
+announce RTP sessions that are described with SDP. (Modern SIP based VoIP phones use RTP/SDP for their sessions, too)</p>
+
+<p>All three protocols are defined in IETF RFCs (RFC3550, RFC3551,
+RFC2327, RFC2327). They can be used in both multicast and unicast
+fashions. Polypaudio exclusively uses multicast RTP/SDP/SAP containing audio data.</p>
+
+<p>For more information about using these technologies with Polypaudio have a look on the <a href="modules.html#rtp">respective module's documentation</a>.
+
+<li><p><b>How can I use Polypaudio to stream music from my main PC to my LAN with multiple PCs with speakers?</b></p>
+
+<p>On the sender side create an RTP sink:</p>
+
+<pre>
+load-module module-null-sink sink_name=rtp
+load-module module-rtp-send source=rtp_monitor
+set-default-sink rtp
+</pre>
+
+<p>This will make <tt>rtp</tt> the default sink, i.e. all applications will write to this virtual RTP device by default.</p>
+
+<p>On the client sides just load the reciever module:</p>
+<pre>
+load-module module-rtp-recv
+</pre>
+
+<p>Now you can play your favourite music on the sender side and all clients will output it simultaneously.</p>
+
+
+<p>BTW: You can have more than one sender machine set up like this. The audio data will be mixed on the client side.</p></li>
+
+<li><p><b>How can I use Polypaudio to share a single LINE-IN/MIC jack on the entire LAN?</b></p>
+
+<p>On the sender side simply load the RTP sender module:</p>
+
+<pre>
+load-module module-rtp-send
+</pre>
+
+<p>On the reciever sides, create an RTP source:</p>
+
+<pre>
+load-module module-null-sink sink_name=rtp
+load-module module-rtp-recv sink=rtp
+set-default-source rtp_monitor
+</pre>
+
+<p>Now the audio data will be available from the default source <tt>rtp_monitor</tt>.</p>
+
+<li><p><b>When sending multicast RTP traffic it is recieved on the entire LAN but not by the sender machine itself!</b></p>
+
+<p>Pass <tt>loop=1</tt> to the sender module!</p></li>
+
+<li><p><b>Can I have more than one multicast RTP group?</b></p>
+
+<p>Yes! Simply use a new multicast group address. Use
+the <tt>destination</tt>/<tt>sap_address</tt> arguments of the RTP
+modules to select them. Choose your group addresses from the range
+<tt>225.0.0.x</tt> to make sure the audio data never leaves the LAN.</p></li>
 
 </ol>
 
diff --git a/doc/README.html.in b/doc/README.html.in
index 3847a9e85..0e9b82610 100644
--- a/doc/README.html.in
+++ b/doc/README.html.in
@@ -44,7 +44,7 @@ Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.</p>
 
 <div class="news-date">Thu Apr 13 2006: </div> <p class="news-text"><a
 href="@PACKAGE_URL@polypaudio-0.8.tar.gz">Version 0.8</a> released;
-changes include: too many to count; many, many minor fixes.</p>
+changes include: too many to count - consider reading <a href="http://0pointer.de/blog/projects/polypaudio-0.8.html">this blog entry</a> for more information; many, many minor fixes.</p>
 
 <div class="news-date">Sun Nov 21 2004: </div> <p class="news-text"><a
 href="@PACKAGE_URL@polypaudio-0.7.tar.gz">Version 0.7</a> released;
@@ -152,6 +152,7 @@ available. A simple main loop implementation is available as well.</p>
   <li><tt>module-lirc</tt>: a module to control the volume of a sink with infrared remote controls supported by LIRC.</li>
   <li><tt>module-mmkbd-evdev</tt>: a module to control the volume of a sink with the special volume keys of a multimeda keyboard.</li>
   <li><tt>module-zeroconf-publish</tt>: a module to publish local sources/sinks using mDNS zeroconf.</li>
+  <li><tt>module-rtp-send</tt>, <tt>module-rtp-recv</tt>: a module to implement RTP/SAP/SDP based audio streaming.</li>
 </ul>
 
 <p><tt>polypaudio</tt> is the successor of my previous, ill-fated
diff --git a/doc/modules.html.in b/doc/modules.html.in
index 67f0e1723..54cec804e 100644
--- a/doc/modules.html.in
+++ b/doc/modules.html.in
@@ -283,7 +283,7 @@ module and point your browser to <a
 href="http://localhost:4714/">http://localhost:4714/</a>. This module takes the same arguments
 as <tt>module-cli-protocol-tcp</tt>.</p>
 
-<h2>Miscellaneous</h2>
+<h2>X Window System</h2>
 
 <h3>module-x11-bell</h3>
 
@@ -315,6 +315,94 @@ and import credential data from/to the X11 display.</p>
 cookie to store in the X11 display. If ommited the cookie of an
 already loaded protocol module is used.</td></tr> </table>
 
+<h2>Volume Control</h2>
+
+<h3>module-mmkbd-evdev</h3>
+
+<p>Adjust the volume of a sink when the special multimedia buttons of modern keyboards are pressed.</p>
+
+<table>
+  <tr><td><tt>device=</tt></td><td>Linux input device ("<tt>evdev</tt>", defaults to <tt>/dev/input/event0</tt>)</td></tr>
+  <tr><td><tt>sink=</tt></td><td>The sink to control</td></tr>
+</table>
+
+<h3>module-lirc</h3>
+
+<p>Adjust the volume of a sink when the volume buttons of an infrared remote control are pressed (through LIRC).</p>
+
+<table>
+  <tr><td><tt>config=</tt></td><td>The LIRC configuration file</td></tr>
+  <tr><td><tt>appname=</tt></td><td>The application name to pass to LIRC (defaults to <tt>polypaudio</tt>)</td></tr>
+  <tr><td><tt>sink=</tt></td><td>The sink to control</td></tr>
+</table>
+
+<a name="rtp"/>
+<h2>RTP/SDP/SAP Transport</h2>
+
+<p>Polypaudio can stream audio data to an IP multicast group via the
+standard protocols <a
+href="http://en.wikipedia.org/wiki/Real-time_Transport_Protocol">RTP</a>,
+<a
+href="http://en.wikipedia.org/wiki/Session_Announcement_Protocol">SAP</a>
+and <a
+href="http://en.wikipedia.org/wiki/Session_Description_Protocol">SDP</a>
+(RFC3550, RFC3551, RFC2327, RFC2327). This can be used for multiple
+different purposes: for sharing a single microphone on multiple
+computers on the local LAN, for streaming music from a single
+controlling PC to multiple PCs with speakers or to implement a simple
+"always-on" teleconferencing solution.</p>
+
+<p>The current implementation is designed to be used exlusively in
+local area networks, though Internet multicasting is theoretically
+supported. Only uncompressed audio is supported, hence you won't be
+able to multicast more than a few streams at the same time over a
+standard LAN.</p>
+
+<p>Polypaudio implements both a sender and a reciever for RTP
+traffic. The sender announces itself via SAP/SDP on the same multicast
+group as it sends the RTP data to. The reciever picks up the SAP/SDP
+announcements and creates a playback stream for each
+session. Alternatively you can use any RTP capable client to
+recieve and play back the RTP data (such as <tt>mplayer</tt>).</p>
+
+<h3>module-rtp-send</h3>
+
+<p>This is the sender side of the RTP/SDP/SAP implementation. It reads
+audio data from an existing source and forwards it to the network
+encapsulated in RTP. In addition it sends SAP packets with an SDP
+session description.</p>
+
+<p>In combination with the monitor source of <tt>module-null-sink</tt>
+you can use this module to create an RTP sink.</p>
+
+<table>
+  <tr><td><tt>source=</tt></td><td>The source to read the audio data from. If ommited defaults to the default source.</td></tr>
+  <tr><td><tt>format=, rate=, channels=</tt></td><td>Sample format to use, defaults to the source's.</td></tr>
+  <tr><td><tt>destination=</tt></td><td>Destination multicast group for both RTP and SAP packets, defaults to <tt>224.0.0.56</tt></td></tr>
+  <tr><td><tt>port=</tt></td><td>Destination port number of the RTP
+traffic. If ommited defaults to a randomly chosen even port
+number. Please keep in mind that the RFC suggests to use only even
+port numbers for RTP traffic.</td></tr>
+  <tr><td><tt>mtu=</tt></td><td>Maximum payload size for RTP packets. If ommited defaults to 1280</td></tr>
+  <tr><td><tt>loop=</tt></td><td>Takes a boolean value, specifying whether locally generated RTP traffic should be looped back to the local host. Disabled by default.</td></tr>
+</table>
+
+<h3>module-rtp-recv</h3>
+
+<p>This is the reciever side of the RTP/SDP/SAP implementation. It
+picks up SAP session announcements and creates an RTP playback stream
+for each.</p>
+
+<p>In combination with <tt>module-null-sink</tt> you can use this
+module to create an RTP source.</p>
+
+<table>
+  <tr><td><tt>sink=</tt></td><td>The sink to connect to. If ommited defaults to the default sink.</td></tr>
+  <tr><td><tt>sap_address=</tt></td><td>The multicast group to join for SAP announcements, defaults to <tt>224.0.0.56</tt>.</td></tr>
+</table>
+
+<h2>Miscellaneous</h2>
+
 <h3>module-sine</h3>
 
 <p>Creates a sink input and generates a sine waveform stream.</p>
@@ -360,24 +448,6 @@ already loaded protocol module is used.</td></tr> </table>
 
 <p>Publish all local sinks/sources using mDNS Zeroconf.</p>
 
-<h3>module-mmkbd-evdev</h3>
-
-<p>Adjust the volume of a sink when the special multimedia buttons of modern keyboards are pressed.</p>
-
-<table>
-  <tr><td><tt>device=</tt></td><td>Linux input device ("<tt>evdev</tt>", defaults to <tt>/dev/input/event0</tt>)</td></tr>
-  <tr><td><tt>sink=</tt></td><td>The sink to control</td></tr>
-</table>
-
-<h3>module-lirc</h3>
-
-<p>Adjust the volume of a sink when the volume buttons of an infrared remote control are pressed (through LIRC).</p>
-
-<table>
-  <tr><td><tt>config=</tt></td><td>The LIRC configuration file</td></tr>
-  <tr><td><tt>appname=</tt></td><td>The application name to pass to LIRC (defaults to <tt>polypaudio</tt>)</td></tr>
-  <tr><td><tt>sink=</tt></td><td>The sink to control</td></tr>
-</table>
 
 <hr/>
 <address class="grey">Lennart Poettering &lt;@PACKAGE_BUGREPORT@&gt;, April 2006</address>