<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
-<title>polypaudio: Loadable Modules</title>
+<title>PulseAudio: Loadable Modules</title>
<link rel="stylesheet" type="text/css" href="style.css" />
</head>
<h1>Loadable Modules</h1>
-<p>The following loadable modules are provided with the <tt>polypaudio</tt> distribution:</p>
+<p>The following loadable modules are provided with the PulseAudio distribution:</p>
<h2>Device Drivers</h2>
<tr><td><tt>rate=</tt></td><td>The sample rate (defaults to 44100)</td></tr>
<tr><td><tt>channels=</tt></td><td>Audio channels (defaults to 2)</td></tr>
<tr><td><tt>sink_name=</tt>, <tt>source_name=</tt></td><td>Name for the sink (resp. source)</td></tr>
-</table>
+ <tr><td><tt>channel_map=</tt></td><td>Channel map. A list of
+comma-seperated channel names. The currently defined channel names
+are: <tt>left</tt>, <tt>right</tt>, <tt>mono</tt>, <tt>center</tt>,
+<tt>front-left</tt>, <tt>front-right</tt>, <tt>front-center</tt>,
+<tt>rear-center</tt>, <tt>rear-left</tt>, <tt>rear-right</tt>,
+<tt>lfe</tt>, <tt>subwoofer</tt>, <tt>front-left-of-center</tt>,
+<tt>front-right-of-center</tt>, <tt>side-left</tt>,
+<tt>side-right</tt>, <tt>aux0</tt>, <tt>aux1</tt> to <tt>aux15</tt>,
+<tt>top-center</tt>, <tt>top-front-left</tt>,
+<tt>top-front-right</tt>, <tt>top-front-center</tt>,
+<tt>top-rear-left</tt>, <tt>top-rear-right</tt>,
+<tt>top-rear-center</tt>, (Default depends on the number of channels
+and the driver)</td></tr> </table>
<h3>module-pipe-sink</h3>
<p>This module supports all arguments thet <tt>module-oss</tt> supports except <tt>device=</tt>.</p>
+<a name="module-combine"/>
<h3>module-combine</h3>
<p>This combines two or more sinks into one. A new virtual sink is
allocated. All data written to it is forwarded to all connected
sinks. In aequidistant intervals the sample rates of the output sinks
-is recalculated: i.e. even when the sink's crystals deviate (which is
+is recalculated: i.e. even when the sinks' crystals deviate (which is
normally the case) output appears synchronously to the human ear. The
resampling required for this may be very CPU intensive.</p>
<h3>module-tunnel-{sink,source}</h3>
<p>Tunnel a remote sink/source to a local "ghost"
-sink/source. Requires a running polypaudio daemon on the remote server
+sink/source. Requires a running PulseAudio daemon on the remote server
with <tt>module-native-protocol-tcp</tt> loaded. It's probably a
better idea to connect to the remote sink/source directly since some
buffer control is lost through this tunneling.</p>
<h3>module-esound-sink</h3>
-<p>Create a playback sink using an ESOUND server as backend. Whenever you can, try to omit this
+<p>Create a playback sink using an <a href="http://www.tux.org/~ricdude/apps.html">ESOUND</a> server as backend. Whenever you can, try to omit this
module since it has many disadvantages including bad latency
and even worse latency measurement. </p>
<p>For an explanation of the simple command line language used by this
module see <a href="cli.html"><tt>cli.html</tt></a>.
-<p>This module doesn't accept any arguments.</p>
+<table>
+ <tr><td><tt>exit_on_eof=</tt></td><td>Accepts a binary numerical argument specifying whether the daemon shuld exit after an EOF was recieved from STDIN (default: 0)</td></tr>
+</table>
<a name="module-cli-protocol-unix"/>
<a name="module-cli-protocol-tcp"/>
<h3>module-cli-protocol-{unix,tcp}</h3>
<p>An implemenation of a simple command line based protocol for
-controlling the <tt>polypaudio</tt> daemon. If loaded, the user may
+controlling the PulseAudio daemon. If loaded, the user may
connect with tools like <tt>netcat</tt>, <tt>telnet</tt> or
<a href="http://0pointer.de/lennart/projects/bidilink/"><tt>bidilink</tt></a> to the listening sockets and execute commands the
same way as with <tt>module-cli</tt>.</p>
a numerical binary value. If 1 the socket is bound to the loopback
device, i.e. not publicly accessible. (defaults to 1)</td></tr>
<tr><td><tt>listen=</tt></td><td>(only for <tt>-tcp</tt>) The IP address to listen on. If specified, supersedes the value specified in <tt>loopback=</tt></td></tr>
- <tr><td><tt>socket=</tt></td><td>(only for <tt>-unix</tt>) The UNIX socket name (defaults to <tt>/tmp/polypaudio/cli</tt>)</td></tr>
+ <tr><td><tt>socket=</tt></td><td>(only for <tt>-unix</tt>) The UNIX socket name (defaults to <tt>/tmp/pulse/cli</tt>)</td></tr>
</table>
<h3>module-simple-protocol-{unix,tcp}</h3>
<p>An implemenation of a protocol compatible with the <a
href="http://www.tux.org/~ricdude/EsounD.html">Enlightened Sound
Daemon</a> (ESOUND, <tt>esd</tt>). When you load this module you may
-access the <tt>polypaudio</tt> daemon with tools like <tt>esdcat</tt>,
+access the PulseAudio daemon with tools like <tt>esdcat</tt>,
<tt>esdrec</tt> or even <tt>esdctl</tt>. Many applications, such as
XMMS, include support for this protocol.</p>
<h3>module-native-protocol-{unix,tcp}</h3>
-<p>The native protocol of <tt>polypaudio</tt>.</p>
+<p>The native protocol of PulseAudio.</p>
<p>See <tt>module-cli-protocol-{unix,tcp}</tt> for more information
about the two possible suffixes of this module.</p>
<h3>module-http-protocol-tcp</h3>
<p>A proof-of-concept HTTP module, which can be used to introspect
-the current status of the polypaudio daemon using HTTP. Just load this
+the current status of the PulseAudio daemon using HTTP. Just load this
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>
<p>Publishes the access credentials to the Polypaudio server in the
X11 root window. The following properties are used:
-<tt>POLYP_SERVER</tt>, <tt>POYLP_SINK</tt>, <tt>POLYP_SOURCE</tt>,
-<tt>POLYP_COOKIE</tt>. This is very useful when using SSH or any other
+<tt>PULSE_SERVER</tt>, <tt>POYLP_SINK</tt>, <tt>PULSE_SOURCE</tt>,
+<tt>PULSE_COOKIE</tt>. This is very useful when using SSH or any other
remote login tool for logging into other machines and getting audio
playback to your local speakers. The Polypaudio client libraries make
use of this data automatically. Instead of using this module you may
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>pulseaudio</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>JACK Connectivity</h2>
+
+<p>Polypaudio can be hooked up to a <a
+href="http://jackit.sourceforge.net/">JACK Audio Connection Kit</a> server which is a specialized sound server used for professional audio production on Unix/Linux. Both a
+Polypaudio sink and a source are available. For each channel a port is
+created in the JACK server.</p>
+
+<h3>module-jack-sink</h3>
+
+<p>This module implements a Polypaudio sink that connects to JACK and registers as many output ports as requested.</p>
+
+<table>
+ <tr><td><tt>sink_name=</tt></td><td>The name for the Polypaudio sink. If ommited defaults to <tt>jack_out</tt>.</td></tr>
+ <tr><td><tt>server_name=</tt></td><td>The JACK server to connect to. If ommited defaults to the default server.</td></tr>
+ <tr><td><tt>client_name=</tt></td><td>The client name to tell the JACK server. If ommited defaults to <tt>PulseAudio</tt>.</td></tr>
+ <tr><td><tt>channels=</tt></td><td>Number of channels to register. If ommited defaults to the number of physical playback ports of the JACK server.</td></tr>
+ <tr><td><tt>connect=</tt></td><td>Takes a boolean value. If enabled (the default) Polypaudio will try to connect its ports to the physicial playback ports of the JACK server</td></tr>
+</table>
+
+<h3>module-jack-source</h3>
+
+<p>This module implements a Polypaudio source that connects to JACK
+and registers as many input ports as requested. Takes the same
+arguments as <tt>module-jack-sink</tt>, except for <tt>sink_name</tt>
+which is replaced by <tt>source_name</tt> (with a default of <tt>jack_in</tt>) for obvious reasons.</p>
+
+<h2>Miscellaneous</h2>
+
<h3>module-sine</h3>
<p>Creates a sink input and generates a sine waveform stream.</p>
<h3>module-esound-compat-spawnfd</h3>
-<p>This is a compatibility module for <tt>libesd</tt> based autospawning of polypaudio. Don't use it directly.</p>
+<p>This is a compatibility module for <tt>libesd</tt> based autospawning of PulseAudio. Don't use it directly.</p>
<h3>module-esound-compat-spawnpid</h3>
-<p>This is a compatibility module for <tt>libesd</tt> based autospawning of polypaudio. Don't use it directly.</p>
+<p>This is a compatibility module for <tt>libesd</tt> based autospawning of PulseAudio. Don't use it directly.</p>
<h3>module-match</h3>
<p>Adjust the volume of a playback stream automatically based on its name.</p>
<table>
- <tr><td><tt>table=</tt></td><td>The regular expression matching table file to use</td></tr>
+ <tr><td><tt>table=</tt></td><td>The regular expression matching table file to use (defaults to <tt>~/.pulse/match.table</tt>)</td></tr>
</table>
<p>The table file should contain a regexp and volume on each line, seperated by spaces. An example:</p>
<pre>
-^sample: 25
+^sample: 32000
</pre>
-<p>The volumes of all streams with titles starting with <tt>sample:</tt> are automatically set to 25. (FYI: All sample cache streams start with <tt>sample:</tt>)</p>
+<p>The volumes of all streams with titles starting with <tt>sample:</tt> are automatically set to 32000. (FYI: All sample cache streams start with <tt>sample:</tt>)</p>
-<h3>module-detect</h3>
+<h3>module-volume-restore</h3>
-<p>Automatically detect the available sound hardware and load modules for it. Supports OSS, ALSA, Solaris and Win32 output drivers.
+<p>Adjust the volume of a playback stream automatically based on its name.</p>
<table>
- <tr><td><tt>just-one=</tt></td><td>If set to <tt>1</tt> the module will only try to load a single sink/source and than stop.</td></tr>
+ <tr><td><tt>table=</tt></td><td>The table file to use (defaults to <tt>~/.pulse/volume.table</tt>)</td></tr>
</table>
-<h3>module-zeroconf-publish</h3>
+<p>In contrast to <tt>module-match</tt> this module needs no explicit
+configuration. Instead the volumes are saved and restored in a fully
+automatical fashion depending on the client name to identify
+streams. The volume for a stream is automatically saved every time it is
+changed and than restored when a new stream is created.</p>
-<p>Publish all local sinks/sources using mDNS Zeroconf.</p>
-
-<h3>module-mmkbd-evdev</h3>
+<h3>module-detect</h3>
-<p>Adjust the volume of a sink when the special multimedia buttons of modern keyboards are pressed.</p>
+<p>Automatically detect the available sound hardware and load modules for it. Supports OSS, ALSA, Solaris and Win32 output drivers.
<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>
+ <tr><td><tt>just-one=</tt></td><td>If set to <tt>1</tt> the module will only try to load a single sink/source and than stop.</td></tr>
</table>
-<h3>module-lirc</h3>
+<h3>module-zeroconf-publish</h3>
-<p>Adjust the volume of a sink when the volume buttons of an infrared remote control are pressed (through LIRC).</p>
+<p>Publish all local sinks/sources using mDNS Zeroconf.</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 <@PACKAGE_BUGREPORT@>, April 2006</address>