<!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>
<p>This is used internally when auto spawning a new daemon. Don't use it directly.</p>
-<h2>Miscellaneous</h2>
+<h3>module-http-protocol-tcp</h3>
+
+<p>A proof-of-concept HTTP module, which can be used to introspect
+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>X Window System</h2>
<h3>module-x11-bell</h3>
<h3>module-x11-publish</h3>
-<p>Publishes the access credentials to the Polypaudio server in the
+<p>Publishes the access credentials to the PulseAudio 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
+playback to your local speakers. The PulseAudio client libraries make
use of this data automatically. Instead of using this module you may
use the tool <tt>pax11publish</tt> which may be used to access, modify
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>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>PulseAudio 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>PulseAudio 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>PulseAudio 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
+PulseAudio 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 PulseAudio 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 PulseAudio 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) PulseAudio 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 PulseAudio 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>Publish all local sinks/sources using mDNS Zeroconf.</p>
+<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>
-<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>