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 <a name="module-alsa-sink"/>
  48
  49 <h3>module-alsa-sink</h3>
  50
  51 <p>Provides a playback sink for devices supported by the <a href="http://www.alsa-project.org/">Advanced Linux
  52 Sound Architecture</a> (ALSA). The sink name defaults to <tt>alsa_output</tt>.</p>
  53
  54 <p>In addition to the general device driver options described above this module supports:</p>
  55
  56 <table>
  57   <tr><td><tt>device=</tt></td><td>The ALSA device to use. (defaults to "plughw:0,0")</td></tr>
  58   <tr><td><tt>fragments=</tt></td><td>The desired fragments when opening the device. (defaults to 12)</td></tr>
  59   <tr><td><tt>fragment_size=</tt></td><td>The desired fragment size in bytes when opening the device (defaults to 1024)</td></tr>
  60 </table>
  61
  62 <h3>module-alsa-source</h3>
  63
  64 <p>Provides a recording source for devices supported by the Advanced
  65 Linux Sound Architecture (ALSA). The source name defaults to <tt>alsa_input</tt>.</p>
  66
  67 <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>
  68
  69 <a name="module-oss"/>
  70
  71 <h3>module-oss</h3>
  72
  73 <p>Provides both a sink and a source for playback, resp. recording on
  74 <a href="http://www.opensound.com">Open Sound System</a> (OSS) compatible devices.</p>
  75
  76 <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>
  77
  78 <p>In addition this module supports the following options:</p>
  79
  80 <table>
  81   <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>
  82   <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>
  83 </table>
  84
  85 <p>The sink name (resp. source name) defaults to <tt>oss_output</tt> (resp. <tt>oss_input</tt>).</p>
  86
  87 <h3>module-oss-mmap</h3>
  88
  89 <p>Similar to <tt>module-oss</tt> but uses memory mapped
  90 (<tt>mmap()</tt>) access to the input/output buffers of the audio
  91 device. This provides better latency behaviour but is not as
  92 compatible as <tt>module-oss</tt>.</p>
  93
  94 <p>This module accepts exactly the same arguments as <a href="#module-oss"><tt>module-oss</tt></a>.</p>
  95
  96 <h3>module-combine</h3>
  97
  98 <p>This combines two or more sinks into one. A new virtual sink is
  99 allocated. All data written to it is forwarded to all connected
 100 sinks. In aequidistant intervals the sample rates of the output sinks
 101 is recalculated: i.e. even when the sink's crystals deviate (which is
 102 normally the case) output appears synchronously to the human ear. The
 103 resampling required for this may be very CPU intensive.</p>
 104
 105 <table>
 106   <tr><td><tt>sink_name=</tt></td><td>The name for the combined sink. (defaults to  <tt>combined</tt>)</td></tr>
 107   <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>
 108   <tr><td><tt>slaves=</tt></td><td>Name of additional sinks to link into the combined think, seperated by commas.</td></tr>
 109   <tr><td><tt>adjust_time=</td><td>Time in seconds when to readjust the sample rate of all sinks. (defaults to 20)</td></tr>
 110   <tr><td><tt>resample_method=</td><td>Resampling algorithm to
 111 use. See <tt>libsamplerate</tt>'s documentation for more
 112 information. Use one of <tt>sinc-best-quality</tt>,
 113 <tt>sinc-medium-quality</tt>, <tt>sinc-fastest</tt>,
 114 <tt>zero-order-hold</tt>, <tt>linear</tt>. If the default happens to
 115 be to slow on your machine try using <tt>zero-order-hold</tt>. This
 116 will decrease output quality however. (defaults to
 117 <tt>sinc-fastest</tt>)</td></tr> </table>
 118
 119 <h2>Protocols</h2>
 120
 121 <a name="module-cli"/>
 122
 123 <h3>module-cli</h3>
 124
 125 <p>Provides the user with a simple command line interface on the
 126 controlling TTY of the daemon. This module may not be loaded more than
 127 once.</p>
 128
 129 <p>For an explanation of the simple command line language used by this
 130 module see <a href="cli.html"><tt>cli.html</tt></a>.
 131
 132 <p>This module doesn't accept any arguments.</p>
 133
 134 <a name="module-cli-protocol-unix"/>
 135 <a name="module-cli-protocol-tcp"/>
 136 <a name="module-cli-protocol"/>
 137
 138 <h3>module-cli-protocol-{unix,tcp}</h3>
 139
 140 <p>An implemenation of a simple command line based protocol for
 141 controlling the <tt>polypaudio</tt> daemon. If loaded, the user may
 142 connect with tools like <tt>netcat</tt>, <tt>telnet</tt> or
 143 <a href="http://0pointer.de/lennart/projects/bidilink/"><tt>bidilink</tt></a> to the listening sockets and execute commands the
 144 same way as with <tt>module-cli</tt>.</p>
 145
 146 <p><b>Beware!</b> Users are not authenticated when connecting to this
 147 service.</p>
 148
 149 <p>This module exists in two versions: with the suffix <tt>-unix</tt>
 150 the service will listen on an UNIX domain socket in the local file
 151 system. With the suffix <tt>-tcp</tt> it will listen on a network
 152 transparent TCP/IP socket.</p>
 153
 154 <p>This module supports the following options:</p>
 155
 156 <table>
 157   <tr><td><tt>port=</tt></td><td>(only for <tt>-tcp</tt>) The port number to listen on (defaults to 4712)</td></tr>
 158   <tr><td><tt>loopback=</tt></td><td>(only for <tt>-tcp</tt>) Accepts
 159 a numerical binary value. If 1 the socket is bound to the loopback
 160 device, i.e. not publicly accessible. (defaults to 1)</td></tr>
 161   <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>
 162 </table>
 163
 164 <h3>module-simple-protocol-{unix,tcp}</h3>
 165
 166 <p>An implementation of a simple protocol which allows playback by using
 167 simple tools like <tt>netcat</tt>. Just connect to the listening
 168 socket of this module and write the audio data to it, or read it from
 169 it for playback, resp. recording.</p>
 170
 171 <p><b>Beware!</b> Users are not authenticated when connecting to this
 172 service.</p>
 173
 174 <p>See <tt>module-cli-protocol-{unix,tcp}</tt> for more information
 175 about the two possible suffixes of this module.</p>
 176
 177 <p>In addition to the options supported by <a href="module-cli-protocol"><tt>module-cli-protocol-*</tt></a>, this module supports:</p>
 178
 179 <table>
 180   <tr><td><tt>rate=</tt>, <tt>format=</tt>, <tt>channels=</tt></td><td>Sample format for streams connecting to this service.</td></tr>
 181   <tr><td><tt>playback=</tt>, <tt>record=</tt></td><td>Enable/disable playback/recording</td></tr>
 182   <tr><td><tt>sink=</tt>, <tt>source=</tt></td><td>Specify the sink/source this service connects to</td></tr>
 183 </table>
 184
 185 <h3>module-esound-protocol-{unix,tcp}</h3>
 186
 187 <p>An implemenation of a protocol compatible with the <a
 188 href="http://www.tux.org/~ricdude/EsounD.html">Enlightened Sound
 189 Daemon</a> (ESOUND, <tt>esd</tt>). When you load this module you may
 190 access the <tt>polypaudio</tt> daemon with tools like <tt>esdcat</tt>,
 191 <tt>esdrec</tt> or even <tt>esdctl</tt>. Many applications, such as
 192 XMMS, include support for this protocol.</p>
 193
 194 <p>See <tt>module-cli-protocol-{unix,tcp}</tt> for more information
 195 about the two possible suffixes of this module.</p>
 196
 197 <p>In addition to the options supported by <a href="module-cli-protocol"><tt>module-cli-protocol-*</tt></a>, this module supports:</p>
 198
 199 <table>
 200   <tr><td><tt>sink=</tt>, <tt>source=</tt></td><td>Specify the sink/source this service connects to</td></tr>
 201   <tr><td><tt>public=</tt></td><td>If set to 0 not authentication is required to connect to the service</td></tr>
 202   <tr><td><tt>cookie=</tt></td><td>Name of the cookie file for authentication purposes</td></tr>
 203 </table>
 204
 205 <p>This implementation misses some features the original ESOUND has: e.g. there is no sample cache yet. However: XMMS works fine.</p>
 206
 207 <h3>module-native-protocol-{unix,tcp}</h3>
 208
 209 <p>The native protocol of <tt>polypaudio</tt>.</p>
 210
 211 <p>See <tt>module-cli-protocol-{unix,tcp}</tt> for more information
 212 about the two possible suffixes of this module.</p>
 213
 214 <p>In addition to the options supported by <a href="module-cli-protocol"><tt>module-cli-protocol-*</tt></a>, this module supports:</p>
 215
 216 <table>
 217   <tr><td><tt>public=</tt></td><td>If set to 0 not authentication is required to connect to the service</td></tr>
 218   <tr><td><tt>cookie=</tt></td><td>Name of the cookie file for authentication purposes</td></tr>
 219 </table>
 220
 221 <h3>module-native-protocol-fd</h3>
 222
 223 <p>This is used internally when auto spawning a new daemon.</p>
 224
 225 <h2>Miscellaneous</h2>
 226
 227 <h3>module-x11-bell</h3>
 228
 229 <p>Intercepts X11 bell events and plays a sample from the sample cache on each occurence.</p>
 230
 231 <table>
 232   <tr><td><tt>display=</tt></td><td>X11 display to connect to. If ommited defaults to the value of <tt>$DISPLAY</tt></td></tr>
 233   <tr><td><tt>sample=</tt></td><td>The sample to play. If ommited defaults to <tt>x11-bell</tt>.</td></tr>
 234   <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>
 235 </table>
 236
 237 <h3>module-sine</h3>
 238
 239 <p>Creates a sink input and generates a sine waveform stream.</p>
 240
 241 <table>
 242   <tr><td><tt>sink=</tt></td><td>The sink to connect to. If ommited defaults to the default sink.</td></tr>
 243   <tr><td><tt>frequency=</tt></td><td>The frequency to generate in Hertz. Defaults to 440.</td></tr>
 244 </table>
 245
 246 <hr/>
 247 <address class="grey">Lennart Poettering &lt;@PACKAGE_BUGREPORT@&gt;, September 2004</address>
 248 <div class="grey"><i>$Id$</i></div>
 249 </body> </html>