summaryrefslogtreecommitdiffstats
path: root/doc/modules.html.in
blob: fe202989e95becd18e10c2755b882a7d0662b7e4 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
<?xml version="1.0" encoding="iso-8859-1"?> <!-- -*-html-helper-*- -->
<!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>
<link rel="stylesheet" type="text/css" href="style.css" />
</head>

<body>

<h1>Loadable Modules</h1>

<p>The following loadable modules are provided with the <tt>polypaudio</tt> distribution:</p>

<h2>Device Drivers</h2>

<p>All device driver modules support the following parameters:</p>
<table>
  <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>
  <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>

<h3>module-pipe-sink</h3>

<p>Provides a simple test sink that writes the audio data to a FIFO
special file in the file system. The sink name defaults to <tt>pipe_output</tt>.</p>

<p>The following option is supported:</p>

<table>
  <tr><td><tt>file=</tt></td><td>The name of the FIFO special file to use</td></tr>
</table>

<a name="module-alsa-sink"/>

<h3>module-alsa-sink</h3>

<p>Provides a playback sink for devices supported by the <a href="http://www.alsa-project.org/">Advanced Linux
Sound Architecture</a> (ALSA). The sink name defaults to <tt>alsa_output</tt>.</p>

<p>In addition to the general device driver options described above this module supports:</p>

<table>
  <tr><td><tt>device=</tt></td><td>The ALSA device to use. (defaults to "plughw:0,0")</td></tr>
  <tr><td><tt>fragments=</tt></td><td>The desired fragments when opening the device. (defaults to 12)</td></tr>
  <tr><td><tt>fragment_size=</tt></td><td>The desired fragment size in bytes when opening the device (defaults to 1024)</td></tr>
</table>

<h3>module-alsa-source</h3>

<p>Provides a recording source for devices supported by the Advanced
Linux Sound Architecture (ALSA). The source name defaults to <tt>alsa_input</tt>.</p>

<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>

<a name="module-oss"/>

<h3>module-oss</h3>

<p>Provides both a sink and a source for playback, resp. recording on
<a href="http://www.opensound.com">Open Sound System</a> (OSS) compatible devices.</p>

<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>

<p>In addition this module supports the following options:</p>

<table>
  <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>
  <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>
</table>

<p>The sink name (resp. source name) defaults to <tt>oss_output</tt> (resp. <tt>oss_input</tt>).</p>

<h3>module-oss-mmap</h3>

<p>Similar to <tt>module-oss</tt> but uses memory mapped
(<tt>mmap()</tt>) access to the input/output buffers of the audio
device. This provides better latency behaviour but is not as
compatible as <tt>module-oss</tt>.</p>

<p>This module accepts exactly the same arguments as <a href="#module-oss"><tt>module-oss</tt></a>.</p>

<h2>Protocols</h2>

<a name="module-cli"/>

<h3>module-cli</h3>

<p>Provides the user with a simple command line interface on the
controlling TTY of the daemon. This module may not be loaded more than
once.</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>

<a name="module-cli-protocol-unix"/>
<a name="module-cli-protocol-tcp"/>
<a name="module-cli-protocol"/>

<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
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>

<p><b>Beware!</b> Users are not authenticated when connecting to this
service.</p>

<p>This module exists in two versions: with the suffix <tt>-unix</tt>
the service will listen on an UNIX domain socket in the local file
system. With the suffix <tt>-tcp</tt> it will listen on a network
transparent TCP/IP socket.</p>

<p>This module supports the following options:</p>

<table>
  <tr><td><tt>port=</tt></td><td>(only for <tt>-tcp</tt>) The port number to listen on (defaults to 4712)</td></tr>
  <tr><td><tt>loopback=</tt></td><td>(only for <tt>-tcp</tt>) Accepts
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>socket=</tt></td><td>(only for <tt>-unix</tt>) The UNIX socket name (defaults to <tt>/tmp/polypaudio/cli</tt>)</td></tr>
</table>

<h3>module-simple-protocol-{unix,tcp}</h3>

<p>An implementation of a simple protocol which allows playback by using
simple tools like <tt>netcat</tt>. Just connect to the listening
socket of this module and write the audio data to it, or read it from
it for playback, resp. recording.</p>

<p><b>Beware!</b> Users are not authenticated when connecting to this
service.</p>

<p>See <tt>module-cli-protocol-{unix,tcp}</tt> for more information
about the two possible suffixes of this module.</p>

<p>In addition to the options supported by <a href="module-cli-protocol"><tt>module-cli-protocol-*</tt></a>, this module supports:</p>

<table>
  <tr><td><tt>rate=</tt>, <tt>format=</tt>, <tt>channels=</tt></td><td>Sample format for streams connecting to this service.</td></tr>
  <tr><td><tt>playback=</tt>, <tt>record=</tt></td><td>Enable/disable playback/recording</td></tr>
  <tr><td><tt>sink=</tt>, <tt>source=</tt></td><td>Specify the sink/source this service connects to</td></tr>
</table>

<h3>module-esound-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>,
<tt>esdrec</tt> or even <tt>esdctl</tt>. Many applications, such as
XMMS, include support for this protocol.</p>

<p>See <tt>module-cli-protocol-{unix,tcp}</tt> for more information
about the two possible suffixes of this module.</p>

<p>In addition to the options supported by <a href="module-cli-protocol"><tt>module-cli-protocol-*</tt></a>, this module supports:</p>

<table>
  <tr><td><tt>sink=</tt>, <tt>source=</tt></td><td>Specify the sink/source this service connects to</td></tr>
  <tr><td><tt>public=</tt></td><td>If set to 0 not authentication is required to connect to the service</td></tr>
  <tr><td><tt>cookie=</tt></td><td>Name of the cookie file for authentication purposes</td></tr>
</table>

<p>This implementation misses some features the original ESOUND has: e.g. there is no sample cache yet. However: XMMS works fine.</p>

<h3>module-native-protocol-{unix,tcp}</h3>

<p>The native protocol of <tt>polypaudio</tt>.</p>

<p>See <tt>module-cli-protocol-{unix,tcp}</tt> for more information
about the two possible suffixes of this module.</p>

<p>In addition to the options supported by <a href="module-cli-protocol"><tt>module-cli-protocol-*</tt></a>, this module supports:</p>

<table>
  <tr><td><tt>public=</tt></td><td>If set to 0 not authentication is required to connect to the service</td></tr>
  <tr><td><tt>cookie=</tt></td><td>Name of the cookie file for authentication purposes</td></tr>
</table>

<h3>module-x11-bell</h3>

<p>Intercepts X11 bell events and plays a sample from the sample cache on each occurence.</p>

<table>
  <tr><td><tt>display=</tt></td><td>X11 display to connect to. If ommited defaults to the value of <tt>$DISPLAY</tt></td></tr>
  <tr><td><tt>sample=</tt></td><td>The sample to play. If ommited defaults to <tt>x11-bell</tt>.</td></tr>
  <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>
</table>

<hr/>
<address class="grey">Lennart Poettering &lt;@PACKAGE_BUGREPORT@&gt;, August 2004</address>
<div class="grey"><i>$Id$</i></div>
</body> </html>