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
|
<HTML>
<HEAD>
<TITLE>Advanced Linux Sound Architecture - Library API: Mixer Interface</TITLE>
</HEAD>
<BODY>
<A HREF="soundapi-3.html">Previous</A>
<A HREF="soundapi-5.html">Next</A>
<A HREF="soundapi.html#toc4">Table of Contents</A>
<HR>
<H2><A NAME="s4">4. Mixer Interface</A></H2>
<P>The Mixer Interface allows applications to change the volume level of
a soundcard's input/output channels in both the linear range (0-100)
and in decibels. It also supports features like hardware mute, input
sound source, etc.</P>
<H2><A NAME="ss4.1">4.1 Low-Level Layer</A></H2>
<P>Mixer devices aren't opened exclusively. This allows applications to
open a device multiple times with one or more processes.</P>
<H3>int snd_mixer_open( void **handle, int card, int device ) </H3>
<P>Creates new handle and opens a connection to the kernel sound
mixer interface for soundcard number <I>card</I> (0-N) and mixer
device number <I>device</I>. Also checks if protocol is
compatible to prevent use of old programs with new kernel API. Function
returns zero if successful, otherwise it returns an error code.</P>
<H3>int snd_mixer_close( void *handle ) </H3>
<P>Frees all resources allocated to the mixer handle and
closes its connection to the kernel sound mixer interface. Function
returns zero if successful, otherwise it returns an error code.</P>
<H3>int snd_mixer_file_descriptor( void *handle ) </H3>
<P>Returns the file descriptor for the connection to the kernel sound
mixer interface. This function should be used only in very
special cases. Function returns a negative error code if an
error was encountered. </P>
<P>The file descriptor should be used for the <I>select</I> synchronous
multiplexer function for deterimeing read direction. Applications should
call <I>snd_mixer_read</I> function if some data is waiting to be read.
It is recomended that you do this, since it leaves place for this function
to handle some new kernel API specifications.</P>
<H3>int snd_mixer_channels( void *handle ) </H3>
<P>Returns the count of mixer channels for appropriate mixer device, otherwise
the return value is negative, and signifies an error code. Never returns
zero.</P>
<H3>int snd_mixer_info( void *handle, snd_mixer_info_t *info ) </H3>
<P>Fills the *info structure with information about the mixer associated with
*handle. Returns zero if successful, otherwise it returns an error code.
<HR>
<PRE>
#define SND_MIXER_INFO_CAP_EXCL_RECORD 0x00000001
struct snd_mixer_info {
unsigned int type; /* type of soundcard - SND_CARD_TYPE_XXXX */
unsigned int channels; /* count of mixer devices */
unsigned int caps; /* some flags about this device (SND_MIXER_INFO_CAP_XXXX) */
unsigned char id[32]; /* ID of this mixer */
unsigned char name[80]; /* name of this device */
char reserved[ 32 ]; /* reserved for future use */
};
</PRE>
<HR>
</P>
<H3>int snd_mixer_channel( void *handle, const char *channel_id ) </H3>
<P>Returns the channel number (index) associated with channel_id (channel name),
or returns an error code.
<HR>
<PRE>
#define SND_MIXER_ID_MASTER "Master"
#define SND_MIXER_ID_BASS "Bass"
#define SND_MIXER_ID_TREBLE "Treble"
#define SND_MIXER_ID_SYNTHESIZER "Synth"
#define SND_MIXER_ID_SYNTHESIZER1 "Synth 1"
#define SND_MIXER_ID_FM "FM"
#define SND_MIXER_ID_EFFECT "Effect"
#define SND_MIXER_ID_PCM "PCM"
#define SND_MIXER_ID_PCM1 "PCM 1"
#define SND_MIXER_ID_LINE "Line-In"
#define SND_MIXER_ID_MIC "MIC"
#define SND_MIXER_ID_CD "CD"
#define SND_MIXER_ID_GAIN "Record-Gain"
#define SND_MIXER_ID_IGAIN "In-Gain"
#define SND_MIXER_ID_OGAIN "Out-Gain"
#define SND_MIXER_ID_LOOPBACK "Loopback"
#define SND_MIXER_ID_SPEAKER "PC Speaker"
#define SND_MIXER_ID_AUXA "Aux A"
#define SND_MIXER_ID_AUXB "Aux B"
#define SND_MIXER_ID_AUXC "Aux C"
</PRE>
<HR>
</P>
<H3>int snd_mixer_exact_mode( void *handle, int enable ) </H3>
<P>Turns on or off (by default) exact mode. This mode allows to application
set/get volume values in exact range which uses hardware. In non-exact
mode is range always from 0 to 100 and conversion to hardware range does
driver. Function returns zero if successful, otherwise it returns an error
code.</P>
<H3>int snd_mixer_channel_info( void *handle, int channel, snd_mixer_channel_info_t *info ) </H3>
<P>Fills the *info structure. The argument <I>channel</I> specifies channel
(0 to N) for which is the info requested. Function returns zero if
successful, otherwise it returns an error code.
<HR>
<PRE>
#define SND_MIXER_CINFO_CAP_RECORD 0x00000001
#define SND_MIXER_CINFO_CAP_STEREO 0x00000002
#define SND_MIXER_CINFO_CAP_MUTE 0x00000004
#define SND_MIXER_CINFO_CAP_HWMUTE 0x00000008 /* channel supports hardware mute */
#define SND_MIXER_CINFO_CAP_DIGITAL 0x00000010 /* channel does digital (not analog) mixing */
#define SND_MIXER_CINOF_CAP_INPUT 0x00000020 /* input channel */
struct snd_mixer_channel_info {
unsigned int channel; /* channel # (filled by application) */
unsigned int parent; /* parent channel # or SND_MIXER_PARENT */
unsigned char name[12]; /* name of this device */
unsigned int caps; /* some flags about this device (SND_MIXER_CINFO_XXXX) */
int min; /* min. value when exact mode (or always 0) */
int max; /* max. value when exact mode (or always 100) */
int min_dB; /* minimum decibel value (*100) */
int max_dB; /* maximum decibel value (*100) */
int step_dB; /* step decibel value (*100) */
unsigned char reserved[16];
};
</PRE>
<HR>
</P>
<H3>int snd_mixer_channel_read( void *handle, int channel, snd_mixer_channel_t *data ) </H3>
<P>Fills the *data structure. The argument <I>channel</I> specifies
the channel (0 to N) for which is data requested. Function returns
zero if successful, otherwise it returns an error code.
<HR>
<PRE>
#define SND_MIXER_FLG_RECORD 0x00000001 /* channel record source flag */
#define SND_MIXER_FLG_MUTE_LEFT 0x00010000
#define SND_MIXER_FLG_MUTE_RIGHT 0x00020000
#define SND_MIXER_FLG_MUTE 0x00030000
#define SND_MIXER_FLG_DECIBEL 0x40000000
#define SND_MIXER_FLG_FORCE 0x80000000
struct snd_mixer_channel {
unsigned int channel; /* channel # (filled by application) */
unsigned int flags; /* some flags to read/write (SND_MIXER_FLG_XXXX) */
int left; /* min - max when exact mode (or 0 - 100) */
int right; /* min - max when exact mode (or 0 - 100) */
int left_dB; /* dB * 100 */
int right_dB; /* dB * 100 */
unsigned char reserved[16];
};
</PRE>
<HR>
</P>
<P>
<DL>
<DT><B>SND_MIXER_FLG_RECORD</B><DD><P>Record source flag.</P>
<DT><B>SND_MIXER_FLG_DECIBEL</B><DD><P>If this bit is set, driver set volume from dB variables <I>left_dB</I>
and <I>right_dB</I>.</P>
<DT><B>SND_MIXER_FLG_FORCE</B><DD><P>Force set - this bit shouldn't be used from user space. Reserved for
kernel.</P>
</DL>
</P>
<H3>int snd_mixer_channel_write( void *handle, int channel, snd_mixer_channel_t *data ) </H3>
<P>Writes the *data structure to kernel. The <I>channel</I> argument
specifies the channel (0 to N) for which is data is to be applied.
Function returns zero if successful, otherwise it returns an error code.
This functions is the opposite of <I>snd_mixer_channel_read</I>.</P>
<H3>int snd_mixer_special_read( void *handle, snd_mixer_special_t *special ) </H3>
<P>Not documented...</P>
<H3>int snd_mixer_special_write( void *handle, snd_mixer_special_t *special ) </H3>
<P>Not documented...</P>
<H3>int snd_mixer_read( void *handle, snd_mixer_callbacks_t *callbacks ) </H3>
<P>This function reads and parses data from driver. Parsed actions are returned
back to the application using the <I>callbacks</I> structure. Applications
should not parse data from the driver in standard cases. This function
returns immediately after all data is read from driver. Does not
block process.
<HR>
<PRE>
typedef struct snd_mixer_callbacks {
void *private_data; /* should be used by application */
void (*channel_was_changed)( void *private_data, int channel );
void *reserved[15]; /* reserved for future use - must be NULL!!! */
} snd_mixer_callbacks_t;
</PRE>
<HR>
</P>
<H2><A NAME="ss4.2">4.2 Examples</A></H2>
<P>The following example shows installed mixer channels for soundcard #0 and
mixer device #0 in the system, and also sets the master volume (if present)
to 50.</P>
<P>
<BLOCKQUOTE><CODE>
<HR>
<PRE>
int card = 0, device = 0, err;
void *handle;
snd_mixer_info_t info;
snd_mixer_channel_t channel;
if ( (err = snd_mixer_open( &handle, card, device )) < 0 ) {
fprintf( stderr, "open failed: %s\n", snd_strerror( err ) );
return;
}
if ( (err = snd_mixer_info( handle, &info )) < 0 ) {
fprintf( stderr, "info failed: %s\n", snd_strerror( err ) );
snd_mixer_close( handle );
return;
}
printf( "Installed MIXER channels for card #i and device %i: %i\n",
card + 1, device, info.channels );
master = snd_mixer_channel( handle, SND_MIXER_ID_MASTER );
if ( master >= 0 ) {
if ( (err = snd_mixer_read( handle, master, &channel )) < 0 ) {
fprintf( stderr, "master read failed: %s\n", snd_strerror( err ) );
snd_mixer_close( handle );
return;
}
channel -> left = channel -> right = 50;
if ( (err = snd_mixer_write( handle, master, &channel )) < 0 ) {
fprintf( stderr, "master write failed: %s\n", snd_strerror( err ) );
snd_mixer_close( handle );
return;
}
}
snd_mixer_close( handle );
</PRE>
<HR>
</CODE></BLOCKQUOTE>
</P>
<HR>
<A HREF="soundapi-3.html">Previous</A>
<A HREF="soundapi-5.html">Next</A>
<A HREF="soundapi.html#toc4">Table of Contents</A>
</BODY>
</HTML>
|
