Web   ·   Wiki   ·   Activities   ·   Blog   ·   Lists   ·   Chat   ·   Meeting   ·   Bugs   ·   Git   ·   Translate   ·   Archive   ·   People   ·   Donate
summaryrefslogtreecommitdiffstats
path: root/arch_src/pyalsaaudio-0.2/doc/mixer-objects.html
blob: 5a4d516d225662f8623a4c08f2d8c26693ee3642 (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
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
<link rel="STYLESHEET" href="pyalsaaudio.css" type='text/css' />
<link rel="first" href="pyalsaaudio.html" title='PyAlsaAudio' />
<link rel='contents' href='contents.html' title="Contents" />
<link rel='last' href='about.html' title='About this document...' />
<link rel='help' href='about.html' title='About this document...' />
<link rel="next" href="pcm-example.html" />
<link rel="prev" href="pcm-objects.html" />
<link rel="parent" href="module-alsaaudio.html" />
<link rel="next" href="pcm-example.html" />
<meta name='aesop' content='information' />
<title>4.3 Mixer Objects</title>
</head>
<body>
<DIV CLASS="navigation">
<div id='top-navigation-panel' xml:id='top-navigation-panel'>
<table align="center" width="100%" cellpadding="0" cellspacing="2">
<tr>
<td class='online-navigation'><a rel="prev" title="4.2 PCM Objects"
  href="pcm-objects.html"><img src='previous.png'
  border='0' height='32'  alt='Previous Page' width='32' /></A></td>
<td class='online-navigation'><a rel="parent" title="4 alsaaudio"
  href="module-alsaaudio.html"><img src='up.png'
  border='0' height='32'  alt='Up One Level' width='32' /></A></td>
<td class='online-navigation'><a rel="next" title="4.4 ALSA Examples"
  href="pcm-example.html"><img src='next.png'
  border='0' height='32'  alt='Next Page' width='32' /></A></td>
<td align="center" width="100%">PyAlsaAudio</td>
<td class='online-navigation'><a rel="contents" title="Table of Contents"
  href="contents.html"><img src='contents.png'
  border='0' height='32'  alt='Contents' width='32' /></A></td>
<td class='online-navigation'><img src='blank.png'
  border='0' height='32'  alt='' width='32' /></td>
<td class='online-navigation'><img src='blank.png'
  border='0' height='32'  alt='' width='32' /></td>
</tr></table>
<div class='online-navigation'>
<b class="navlabel">Previous:</b>
<a class="sectref" rel="prev" href="pcm-objects.html">4.2 PCM Objects</A>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="module-alsaaudio.html">4 alsaaudio</A>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="pcm-example.html">4.4 ALSA Examples</A>
</div>
<hr /></div>
</DIV>
<!--End of Navigation Panel-->

<H2><A NAME="SECTION002430000000000000000"></A>
<A NAME="mixer-objects"></A>
<BR>
4.3 Mixer Objects
</H2>

<P>
Mixer objects provides access to the ALSA mixer API.

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><span class="typelabel">class</span>&nbsp;<tt id='l2h-16' xml:id='l2h-16' class="class">Mixer</tt></b>(</nobr></td>
  <td><var></var><big>[</big><var>control</var><big>]</big><var>, </var><big>[</big><var>id</var><big>]</big><var>, </var><big>[</big><var>cardname</var><big>]</big><var></var>)</td></tr></table></dt>
<dd>
<var>control</var> - specifies which control to manipulate using this mixer object. The list
of available controls can be found with the <tt class="module">alsaaudio</tt>.<tt class="function">mixers</tt> function.
The default value is 'Master' - other common controls include 'Master Mono', 'PCM', 'Line', etc.

<P>
<var>id</var> - the id of the mixer control. Default is 0

<P>
<var>cardname</var> - specifies which card should be used (this is only relevant 
if you have more than one sound card). Omit to use the default sound card
</dl>

<P>
Mixer objects have the following methods:

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-17' xml:id='l2h-17' class="method">cardname</tt></b>(</nobr></td>
  <td><var></var>)</td></tr></table></dt>
<dd>
Return the name of the sound card used by this Mixer object
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-18' xml:id='l2h-18' class="method">mixer</tt></b>(</nobr></td>
  <td><var></var>)</td></tr></table></dt>
<dd>
Return the name of the specific mixer controlled by this object, For example 'Master'
or 'PCM'
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-19' xml:id='l2h-19' class="method">mixerid</tt></b>(</nobr></td>
  <td><var></var>)</td></tr></table></dt>
<dd>
Return the ID of the ALSA mixer controlled by this object.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-20' xml:id='l2h-20' class="method">switchcap</tt></b>(</nobr></td>
  <td><var></var>)</td></tr></table></dt>
<dd>
Returns a list of the switches which are defined by this specific mixer. Possible values in
this list are:

<P>
<div class="center"><table class="realtable">
  <thead>
    <tr>
      <th class="left"  >Switch</th>
      <th class="left"  >Description</th>
      </tr>
    </thead>
  <tbody>
    <tr><td class="left"   valign="baseline"><Volume Capabilities>'Mute'</Volume></td>
        <td class="left"  >This mixer can be muted</td></tr>
    <tr><td class="left"   valign="baseline"><Volume Capabilities>'Joined Mute'</Volume></td>
        <td class="left"  >This mixer can mute all channels at the same time</td></tr>
    <tr><td class="left"   valign="baseline"><Volume Capabilities>'Playback Mute'</Volume></td>
        <td class="left"  >This mixer can mute the playback output</td></tr>
    <tr><td class="left"   valign="baseline"><Volume Capabilities>'Joined Playback Mute'</Volume></td>
        <td class="left"  >Mute playback for all channels at the same time</td></tr>
    <tr><td class="left"   valign="baseline"><Volume Capabilities>'Capture Mute'</Volume></td>
        <td class="left"  >Mute sound capture</td></tr>
    <tr><td class="left"   valign="baseline"><Volume Capabilities>'Joined Capture Mute'</Volume></td>
        <td class="left"  >Mute sound capture for all channels at a time</td></tr>
    <tr><td class="left"   valign="baseline"><Volume Capabilities>'Capture Exclusive'</Volume></td>
        <td class="left"  >Not quite sure what this is</td></tr></tbody>
</table></div>

<P>
To manipulate these swithes use the <tt class="method">setrec</tt> or <tt class="method">setmute</tt> methods
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-21' xml:id='l2h-21' class="method">volumecap</tt></b>(</nobr></td>
  <td><var></var>)</td></tr></table></dt>
<dd>
Returns a list of the volume control capabilities of this mixer. Possible values in
the list are:

<P>
<div class="center"><table class="realtable">
  <thead>
    <tr>
      <th class="left"  >Capability</th>
      <th class="left"  >Description</th>
      </tr>
    </thead>
  <tbody>
    <tr><td class="left"   valign="baseline"><Volume Capabilities>'Volume'</Volume></td>
        <td class="left"  >This mixer can control volume</td></tr>
    <tr><td class="left"   valign="baseline"><Volume Capabilities>'Joined Volume'</Volume></td>
        <td class="left"  >This mixer can control volume for all channels at the same time</td></tr>
    <tr><td class="left"   valign="baseline"><Volume Capabilities>'Playback Volume'</Volume></td>
        <td class="left"  >This mixer can manipulate the playback volume</td></tr>
    <tr><td class="left"   valign="baseline"><Volume Capabilities>'Joined Playback Volume'</Volume></td>
        <td class="left"  >Manipulate playback volumne for all channels at the same time</td></tr>
    <tr><td class="left"   valign="baseline"><Volume Capabilities>'Capture Volume'</Volume></td>
        <td class="left"  >Manipulate sound capture volume</td></tr>
    <tr><td class="left"   valign="baseline"><Volume Capabilities>'Joined Capture Volume'</Volume></td>
        <td class="left"  >Manipulate sound capture volume for all channels at a time</td></tr></tbody>
</table></div>

<P>
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-22' xml:id='l2h-22' class="method">getvolume</tt></b>(</nobr></td>
  <td><var></var><big>[</big><var>direction</var><big>]</big><var></var>)</td></tr></table></dt>
<dd>
Returns a list with the current volume settings for each channel. The list elements
are integer percentages.

<P>
The optional <var>direction</var> argument can be either 'playback' or 'capture', which is relevant
if the mixer can control both playback and capture volume. The default value is 'playback'
if the mixer has this capability, otherwise 'capture'

<P>
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-23' xml:id='l2h-23' class="method">getmute</tt></b>(</nobr></td>
  <td><var></var>)</td></tr></table></dt>
<dd>
Return a list indicating the current mute setting for each channel. 0 means not muted, 1 means muted.

<P>
This method will fail if the mixer has no playback switch capabilities.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-24' xml:id='l2h-24' class="method">getrec</tt></b>(</nobr></td>
  <td><var></var>)</td></tr></table></dt>
<dd>
Return a list indicating the current record mute setting for each channel. 0 means not recording, 1 
means not recording.

<P>
This method will fail if the mixer has no capture switch capabilities.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-25' xml:id='l2h-25' class="method">setvolume</tt></b>(</nobr></td>
  <td><var>volume,</var><big>[</big><var>channel</var><big>]</big><var>,</var><big>[</big><var>direction</var><big>]</big><var></var>)</td></tr></table></dt>
<dd>
Change the current volume settings for this mixer. The <var>volume</var> argument controls
the new volume setting as an integer percentage.

<P>
If the optional argument <var>channel</var> is present, the volume is set only for this channel. This
assumes that the mixer can control the volume for the channels independently.

<P>
The optional <var>direction</var> argument can be either 'playback' or 'capture' is relevant if the mixer
has independent playback and capture volume capabilities, and controls which of the volumes
if changed. The default is 'playback' if the mixer has this capability, otherwise 'capture'.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-26' xml:id='l2h-26' class="method">setmute</tt></b>(</nobr></td>
  <td><var>mute, </var><big>[</big><var>channel</var><big>]</big><var></var>)</td></tr></table></dt>
<dd>
Sets the mute flag to a new value. The <var>mute</var> argument is either 0 for not muted, or 1 for muted.

<P>
The optional <var>channel</var> argument controls which channel is muted. The default is to set the mute flag
for all channels.

<P>
This method will fail if the mixer has no playback mute capabilities
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-27' xml:id='l2h-27' class="method">setrec</tt></b>(</nobr></td>
  <td><var>capture,</var><big>[</big><var>channel</var><big>]</big><var></var>)</td></tr></table></dt>
<dd>
Sets the capture mute flag to a new value. The <var>capture</var> argument is either 0 for no capture, 
or 1 for capture.

<P>
The optional <var>channel</var> argument controls which channel is changed. The default is to set the capture flag
for all channels.

<P>
This method will fail if the mixer has no capture switch capabilities
</dl>

<P>
<b>A Note on the ALSA Mixer API</b>

<P>
The ALSA mixer API is extremely complicated - and hardly documented at all. <tt class="module">alsaaudio</tt> implements
a much simplified way to access this API. In designing the API I've had to make some choices which
may limit what can and cannot be controlled through the API. However, If I had chosen to implement the
full API, I would have reexposed the horrible complexity/documentation ratio of the underlying API.
At least the <tt class="module">alsaaudio</tt> API is easy to understand and use.

<P>
If my design choises prevents you from doing something that the underlying API would have allowed,
please let me know, so I can incorporate these need into future versions.

<P>
If the current state of affairs annoy you, the best you can do is to write a HOWTO on the API and
make this available on the net. Until somebody does this, the availability of ALSA mixer capable
devices will stay quite limited.

<P>
Unfortunately, I'm not able to create such a HOWTO myself, since I only understand half of the API,
and that which I do understand has come from a painful trial and error process.

<P>

<DIV CLASS="navigation">
<div class='online-navigation'>
<p></p><hr />
<table align="center" width="100%" cellpadding="0" cellspacing="2">
<tr>
<td class='online-navigation'><a rel="prev" title="4.2 PCM Objects"
  href="pcm-objects.html"><img src='previous.png'
  border='0' height='32'  alt='Previous Page' width='32' /></A></td>
<td class='online-navigation'><a rel="parent" title="4 alsaaudio"
  href="module-alsaaudio.html"><img src='up.png'
  border='0' height='32'  alt='Up One Level' width='32' /></A></td>
<td class='online-navigation'><a rel="next" title="4.4 ALSA Examples"
  href="pcm-example.html"><img src='next.png'
  border='0' height='32'  alt='Next Page' width='32' /></A></td>
<td align="center" width="100%">PyAlsaAudio</td>
<td class='online-navigation'><a rel="contents" title="Table of Contents"
  href="contents.html"><img src='contents.png'
  border='0' height='32'  alt='Contents' width='32' /></A></td>
<td class='online-navigation'><img src='blank.png'
  border='0' height='32'  alt='' width='32' /></td>
<td class='online-navigation'><img src='blank.png'
  border='0' height='32'  alt='' width='32' /></td>
</tr></table>
<div class='online-navigation'>
<b class="navlabel">Previous:</b>
<a class="sectref" rel="prev" href="pcm-objects.html">4.2 PCM Objects</A>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="module-alsaaudio.html">4 alsaaudio</A>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="pcm-example.html">4.4 ALSA Examples</A>
</div>
</div>
<hr />
<span class="release-info">Release 0.2.</span>
</DIV>
<!--End of Navigation Panel-->

</BODY>
</HTML>