code.delx.au - pulseaudio/blob - doc/modules.html.in

   1 <?xml version="1.0" encoding="iso-8859-1"?> <!-- -*-html-helper-*- -->
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
   3 <html xmlns="http://www.w3.org/1999/xhtml">
   4 <head>
   5 <title>polypaudio: Loadable Modules</title>
   6 <link rel="stylesheet" type="text/css" href="style.css" />
   7 </head>
   8
   9 <body>
  10
  11 <h1>Loadable Modules</h1>
  12
  13 <p>The following loadable modules are provided with the <tt>polypaudio</tt> distribution:</p>
  14
  15 <h2>Device Drivers</h2>
  16
  17 <p>All device driver modules support the following parameters:</p>
  18 <table>
  19   <tr><td><tt>format=</tt></td><td>The sample format (one of <tt>u8</tt>, <tt>s16</tt>, <tt>s16le</tt>, <tt>s16le</tt>, <tt>float32</tt>, <tt>float32be</tt>, <tt>float32le</tt>, <tt>alaw</tt>, <tt>ulaw</tt>) (defaults to <tt>s16</tt>)</td></tr>
  20   <tr><td><tt>rate=</tt></td><td>The sample rate (defaults to 44100)</td></tr>
  21   <tr><td><tt>channels=</tt></td><td>Audio channels (defaults to 2)</td></tr>
  22   <tr><td><tt>sink_name=</tt>, <tt>source_name=</tt></td><td>Name for the sink (resp. source)</td></tr>
  23 </table>
  24
  25 <h3>module-pipe-sink</h3>
  26
  27 <p>Provides a simple test sink that writes the audio data to a FIFO
  28 special file in the file system. The sink name defaults to <tt>pipe_output</tt>.</p>
  29
  30 <p>The following option is supported:</p>
  31
  32 <table>
  33   <tr><td><tt>file=</tt></td><td>The name of the FIFO special file to use. (defaults to: <tt>/tmp/music.output</tt>)</td></tr>
  34 </table>
  35
  36 <h3>module-pipe-source</h3>
  37
  38 <p>Provides a simple test source that reads the audio data from a FIFO
  39 special file in the file system. The source name defaults to <tt>pipe_input</tt>.</p>
  40
  41 <p>The following option is supported:</p>
  42
  43 <table>
  44   <tr><td><tt>file=</tt></td><td>The name of the FIFO special file to use. (defaults to: <tt>/tmp/music.input</tt>)</td></tr>
  45 </table>
  46
  47
  48 <h3>module-null-sink</h3>
  49
  50 <p>Provides a simple null sink. All data written to this sink is silently dropped. This sink is clocked using the system time.</p>
  51
  52 <p>This module doesn't support any special parameters</p>
  53
  54 <a name="module-alsa-sink"/>
  55
  56 <h3>module-alsa-sink</h3>
  57
  58 <p>Provides a playback sink for devices supported by the <a href="http://www.alsa-project.org/">Advanced Linux
  59 Sound Architecture</a> (ALSA). The sink name defaults to <tt>alsa_output</tt>.</p>
  60
  61 <p>In addition to the general device driver options described above this module supports:</p>
  62
  63 <table>
  64   <tr><td><tt>device=</tt></td><td>The ALSA device to use. (defaults to "plughw:0,0")</td></tr>
  65   <tr><td><tt>fragments=</tt></td><td>The desired fragments when opening the device. (defaults to 12)</td></tr>
  66   <tr><td><tt>fragment_size=</tt></td><td>The desired fragment size in bytes when opening the device (defaults to 1024)</td></tr>
  67 </table>
  68
  69 <h3>module-alsa-source</h3>
  70
  71 <p>Provides a recording source for devices supported by the Advanced
  72 Linux Sound Architecture (ALSA). The source name defaults to <tt>alsa_input</tt>.</p>
  73
  74 <p>This module supports <tt>device=</tt>, <tt>fragments=</tt> and <tt>fragment_size=</tt> arguments the same way as <a href="#module-alsa-sink"><tt>module-alsa-sink</tt></a>.</p>
  75
  76 <a name="module-oss"/>
  77
  78 <h3>module-oss</h3>
  79
  80 <p>Provides both a sink and a source for playback, resp. recording on
  81 <a href="http://www.opensound.com">Open Sound System</a> (OSS) compatible devices.</p>
  82
  83 <p>This module supports <tt>device=</tt> (which defaults to <tt>/dev/dsp</tt>), <tt>fragments=</tt> and <tt>fragment_size=</tt> arguments the same way as <a href="#module-alsa-sink"><tt>module-alsa-sink</tt></a>.</p>
  84
  85 <p>In addition this module supports the following options:</p>
  86
  87 <table>
  88   <tr><td><tt>record=</tt></td><td>Accepts a binary numerical value for enabling (resp. disabling) the recording on this device. (defaults: to 1)</td></tr>
  89   <tr><td><tt>playback=</tt></td><td>Accepts a binary numerical value for enabling (resp. disabling) the playback on this device. (defaults: to 1)</td></tr>
  90 </table>
  91
  92 <p>The sink name (resp. source name) defaults to <tt>oss_output</tt> (resp. <tt>oss_input</tt>).</p>
  93
  94 <h3>module-oss-mmap</h3>
  95
  96 <p>Similar to <tt>module-oss</tt> but uses memory mapped
  97 (<tt>mmap()</tt>) access to the input/output buffers of the audio
  98 device. This provides better latency behaviour but is not as
  99 compatible as <tt>module-oss</tt>.</p>
 100
 101 <p>This module accepts exactly the same arguments as <a href="#module-oss"><tt>module-oss</tt></a>.</p>
 102
 103 <h3>module-combine</h3>
 104
 105 <p>This combines two or more sinks into one. A new virtual sink is
 106 allocated. All data written to it is forwarded to all connected
 107 sinks. In aequidistant intervals the sample rates of the output sinks
 108 is recalculated: i.e. even when the sink's crystals deviate (which is
 109 normally the case) output appears synchronously to the human ear. The
 110 resampling required for this may be very CPU intensive.</p>
 111
 112 <table>
 113   <tr><td><tt>sink_name=</tt></td><td>The name for the combined sink. (defaults to  <tt>combined</tt>)</td></tr>
 114   <tr><td><tt>master=</tt></td><td>The name of the first sink to link into the combined think. The sample rate/type is taken from this sink.</td></tr>
 115   <tr><td><tt>slaves=</tt></td><td>Name of additional sinks to link into the combined think, seperated by commas.</td></tr>
 116   <tr><td><tt>adjust_time=</tt></td><td>Time in seconds when to readjust the sample rate of all sinks. (defaults to 20)</td></tr>
 117   <tr><td><tt>resample_method=</tt></td><td>Resampling algorithm to
 118 use. See <tt>libsamplerate</tt>'s documentation for more
 119 information. Use one of <tt>sinc-best-quality</tt>,
 120 <tt>sinc-medium-quality</tt>, <tt>sinc-fastest</tt>,
 121 <tt>zero-order-hold</tt>, <tt>linear</tt>. If the default happens to
 122 be to slow on your machine try using <tt>zero-order-hold</tt>. This
 123 will decrease output quality however. (defaults to
 124 <tt>sinc-fastest</tt>)</td></tr> </table>
 125
 126 <h3>module-tunnel-{sink,source}</h3>
 127
 128 <p>Tunnel a remote sink/source to a local "ghost"
 129 sink/source. Requires a running polypaudio daemon on the remote server
 130 with <tt>module-native-protocol-tcp</tt> loaded. It's probably a
 131 better idea to connect to the remote sink/source directly since some
 132 buffer control is lost through this tunneling.</p>
 133
 134 <table>
 135   <tr><td><tt>server=</tt></td><td>The server to connect to</td></tr>
 136   <tr><td><tt>source=</tt></td><td>The source on the remote server. Only available for <tt>module-tunnel-source</tt>.</td></tr>
 137   <tr><td><tt>sink=</tt></td><td>The sink on the remote server. Only available for <tt>module-tunnel-sink</tt>.</td></tr>
 138   <tr><td><tt>cookie=</tt></td><td>The authentication cookie file to use.</td></tr>
 139 </table>
 140
 141 <h3>module-esound-sink</h3>
 142
 143 <p>Create a playback sink using an ESOUND server as backend. Whenever you can, try to omit this
 144 module since it has many disadvantages including bad latency
 145 and even worse latency measurement. </p>
 146
 147 <table>
 148   <tr><td><tt>server=</tt></td><td>The server to connect to</td></tr>
 149   <tr><td><tt>cookie=</tt></td><td>The authentication cookie file to use.</td></tr>
 150 </table>
 151
 152 <h2>Protocols</h2>
 153
 154 <a name="module-cli"/>
 155
 156 <h3>module-cli</h3>
 157
 158 <p>Provides the user with a simple command line interface on the
 159 controlling TTY of the daemon. This module may not be loaded more than
 160 once.</p>
 161
 162 <p>For an explanation of the simple command line language used by this
 163 module see <a href="cli.html"><tt>cli.html</tt></a>.
 164
 165 <p>This module doesn't accept any arguments.</p>
 166
 167 <a name="module-cli-protocol-unix"/>
 168 <a name="module-cli-protocol-tcp"/>
 169 <a name="module-cli-protocol"/>
 170
 171 <h3>module-cli-protocol-{unix,tcp,tcp6}</h3>
 172
 173 <p>An implemenation of a simple command line based protocol for
 174 controlling the <tt>polypaudio</tt> daemon. If loaded, the user may
 175 connect with tools like <tt>netcat</tt>, <tt>telnet</tt> or
 176 <a href="http://0pointer.de/lennart/projects/bidilink/"><tt>bidilink</tt></a> to the listening sockets and execute commands the
 177 same way as with <tt>module-cli</tt>.</p>
 178
 179 <p><b>Beware!</b> Users are not authenticated when connecting to this
 180 service.</p>
 181
 182 <p>This module exists in two versions: with the suffix <tt>-unix</tt>
 183 the service will listen on an UNIX domain socket in the local file
 184 system. With the suffix <tt>-tcp</tt> it will listen on a network
 185 transparent TCP/IP socket.</p>
 186
 187 <p>This module supports the following options:</p>
 188
 189 <table>
 190   <tr><td><tt>port=</tt></td><td>(only for <tt>-tcp</tt>) The port number to listen on (defaults to 4712)</td></tr>
 191   <tr><td><tt>loopback=</tt></td><td>(only for <tt>-tcp</tt>) Accepts
 192 a numerical binary value. If 1 the socket is bound to the loopback
 193 device, i.e. not publicly accessible. (defaults to 1)</td></tr>
 194   <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>
 195 </table>
 196
 197 <h3>module-simple-protocol-{unix,tcp,tcp6}</h3>
 198
 199 <p>An implementation of a simple protocol which allows playback by using
 200 simple tools like <tt>netcat</tt>. Just connect to the listening
 201 socket of this module and write the audio data to it, or read it from
 202 it for playback, resp. recording.</p>
 203
 204 <p><b>Beware!</b> Users are not authenticated when connecting to this
 205 service.</p>
 206
 207 <p>See <tt>module-cli-protocol-{unix,tcp}</tt> for more information
 208 about the two possible suffixes of this module.</p>
 209
 210 <p>In addition to the options supported by <a href="module-cli-protocol"><tt>module-cli-protocol-*</tt></a>, this module supports:</p>
 211
 212 <table>
 213   <tr><td><tt>rate=</tt>, <tt>format=</tt>, <tt>channels=</tt></td><td>Sample format for streams connecting to this service.</td></tr>
 214   <tr><td><tt>playback=</tt>, <tt>record=</tt></td><td>Enable/disable playback/recording</td></tr>
 215   <tr><td><tt>sink=</tt>, <tt>source=</tt></td><td>Specify the sink/source this service connects to</td></tr>
 216 </table>
 217
 218 <h3>module-esound-protocol-{unix,tcp}</h3>
 219
 220 <p>An implemenation of a protocol compatible with the <a
 221 href="http://www.tux.org/~ricdude/EsounD.html">Enlightened Sound
 222 Daemon</a> (ESOUND, <tt>esd</tt>). When you load this module you may
 223 access the <tt>polypaudio</tt> daemon with tools like <tt>esdcat</tt>,
 224 <tt>esdrec</tt> or even <tt>esdctl</tt>. Many applications, such as
 225 XMMS, include support for this protocol.</p>
 226
 227 <p>See <tt>module-cli-protocol-{unix,tcp}</tt> for more information
 228 about the two possible suffixes of this module.</p>
 229
 230 <p>In addition to the options supported by <a href="module-cli-protocol"><tt>module-cli-protocol-*</tt></a>, this module supports:</p>
 231
 232 <table>
 233   <tr><td><tt>sink=</tt>, <tt>source=</tt></td><td>Specify the sink/source this service connects to</td></tr>
 234   <tr><td><tt>public=</tt></td><td>If set to 0 not authentication is required to connect to the service</td></tr>
 235   <tr><td><tt>cookie=</tt></td><td>Name of the cookie file for authentication purposes</td></tr>
 236 </table>
 237
 238 <p>This implementation misses some features the original ESOUND has: e.g. there is no sample cache yet. However: XMMS works fine.</p>
 239
 240 <h3>module-native-protocol-{unix,tcp,tcp6}</h3>
 241
 242 <p>The native protocol of <tt>polypaudio</tt>.</p>
 243
 244 <p>See <tt>module-cli-protocol-{unix,tcp}</tt> for more information
 245 about the two possible suffixes of this module.</p>
 246
 247 <p>In addition to the options supported by <a href="module-cli-protocol"><tt>module-cli-protocol-*</tt></a>, this module supports:</p>
 248
 249 <table>
 250   <tr><td><tt>public=</tt></td><td>If set to 0 not authentication is required to connect to the service</td></tr>
 251   <tr><td><tt>cookie=</tt></td><td>Name of the cookie file for authentication purposes</td></tr>
 252 </table>
 253
 254 <h3>module-native-protocol-fd</h3>
 255
 256 <p>This is used internally when auto spawning a new daemon. Don't use it directly.</p>
 257
 258 <h2>Miscellaneous</h2>
 259
 260 <h3>module-x11-bell</h3>
 261
 262 <p>Intercepts X11 bell events and plays a sample from the sample cache on each occurence.</p>
 263
 264 <table>
 265   <tr><td><tt>display=</tt></td><td>X11 display to connect to. If ommited defaults to the value of <tt>$DISPLAY</tt></td></tr>
 266   <tr><td><tt>sample=</tt></td><td>The sample to play. If ommited defaults to <tt>x11-bell</tt>.</td></tr>
 267   <tr><td><tt>sink=</tt></td><td>Name of the sink to play the sample on. If ommited defaults to the default sink.</td></tr>
 268 </table>
 269
 270 <h3>module-x11-publish</h3>
 271
 272 <p>Publishes the access credentials to the Polypaudio server in the
 273 X11 root window. The following properties are used:
 274 <tt>POLYP_SERVER</tt>, <tt>POYLP_SINK</tt>, <tt>POLYP_SOURCE</tt>,
 275 <tt>POLYP_COOKIE</tt>. This is very useful when using SSH or any other
 276 remote login tool for logging into other machines and getting audio
 277 playback to your local speakers. The Polypaudio client libraries make
 278 use of this data automatically. Instead of using this module you may
 279 use the tool <tt>pax11publish</tt> which may be used to access, modify
 280 and import credential data from/to the X11 display.</p>
 281
 282 <table>
 283   <tr><td><tt>display=</tt></td><td>X11 display to connect to. If ommited defaults to the value of <tt>$DISPLAY</tt></td></tr>
 284   <tr><td><tt>sink=</tt></td><td>Name of the default sink. If ommited this property isn't stored in the X11 display.</td></tr>
 285   <tr><td><tt>source=</tt></td><td>Name of the default source. If ommited this property isn't stored in the X11 display.</td></tr>
 286   <tr><td><tt>cookie=</tt></td><td>Name of the cookie file of the
 287 cookie to store in the X11 display. If ommited the cookie of an
 288 already loaded protocol module is used.</td></tr> </table>
 289
 290 <h3>module-sine</h3>
 291
 292 <p>Creates a sink input and generates a sine waveform stream.</p>
 293
 294 <table>
 295   <tr><td><tt>sink=</tt></td><td>The sink to connect to. If ommited defaults to the default sink.</td></tr>
 296   <tr><td><tt>frequency=</tt></td><td>The frequency to generate in Hertz. Defaults to 440.</td></tr>
 297 </table>
 298
 299 <h3>module-esound-compat-spawnfd</h3>
 300
 301 <p>This is a compatibility module for <tt>libesd</tt> based autospawning of polypaudio. Don't use it directly.</p>
 302
 303 <h3>module-esound-compat-spawnpid</h3>
 304
 305 <p>This is a compatibility module for <tt>libesd</tt> based autospawning of polypaudio. Don't use it directly.</p>
 306
 307 <h3>module-match</h3>
 308
 309 <p>Adjust the volume of a playback stream automatically based on its name.</p>
 310
 311 <table>
 312   <tr><td><tt>table=</tt></td><td>The regular expression matching table file to use</td></tr>
 313 </table>
 314
 315 <p>The table file should contain a regexp and volume on each line, seperated by spaces. An example:</p>
 316
 317 <pre>
 318 ^sample: 25
 319 </pre>
 320
 321 <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>
 322
 323 <hr/>
 324 <address class="grey">Lennart Poettering &lt;@PACKAGE_BUGREPORT@&gt;, November 2004</address>
 325 <div class="grey"><i>$Id$</i></div>
 326 </body> </html>