mssndcard.h 12.9 KB
Newer Older
aymeric's avatar
aymeric committed
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
/*
mediastreamer2 library - modular sound and video processing and streaming
Copyright (C) 2006  Simon MORLAT (simon.morlat@linphone.org)

This program is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License
as published by the Free Software Foundation; either version 2
of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
*/

#ifndef sndcard_h
#define sndcard_h

Simon Morlat's avatar
Simon Morlat committed
23
#include <mediastreamer2/mscommon.h>
aymeric's avatar
aymeric committed
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41

/**
 * @file mssndcard.h
 * @brief mediastreamer2 mssndcard.h include file
 *
 * This file provide the API needed to manage
 * soundcard filters.
 *
 */

/**
 * @defgroup mediastreamer2_soundcard Sound Card API - manage audio capture/play filters.
 * @ingroup mediastreamer2_api
 * @{
 */

struct _MSSndCardManager{
	MSList *cards;
42
	MSList *descs;
aymeric's avatar
aymeric committed
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
};

/**
 * Structure for sound card manager object.
 * @var MSSndCardManager
 */
typedef struct _MSSndCardManager MSSndCardManager;

enum _MSSndCardMixerElem{
	MS_SND_CARD_MASTER,
	MS_SND_CARD_PLAYBACK,
	MS_SND_CARD_CAPTURE
};

/**
 * Structure for sound card mixer values.
 * @var MSSndCardMixerElem
 */
typedef enum _MSSndCardMixerElem MSSndCardMixerElem;

enum _MSSndCardCapture {
	MS_SND_CARD_MIC,
	MS_SND_CARD_LINE
};

68
/**
aymeric's avatar
aymeric committed
69
70
 * Structure for sound card capture source values.
 * @var MSSndCardCapture
71
 */
aymeric's avatar
aymeric committed
72
typedef enum _MSSndCardCapture MSSndCardCapture;
73
74
75
76
77
78
79

enum _MSSndCardControlElem {
	MS_SND_CARD_MASTER_MUTE,
	MS_SND_CARD_PLAYBACK_MUTE,
	MS_SND_CARD_CAPTURE_MUTE
};

aymeric's avatar
aymeric committed
80
/**
aymeric's avatar
aymeric committed
81
82
 * Structure for sound card mixer values.
 * @var MSSndCardControlElem
aymeric's avatar
aymeric committed
83
 */
aymeric's avatar
aymeric committed
84
typedef enum _MSSndCardControlElem MSSndCardControlElem;
aymeric's avatar
aymeric committed
85
86
87
88
89
90
91
92
93

struct _MSSndCard;

typedef void (*MSSndCardDetectFunc)(MSSndCardManager *obj);
typedef void (*MSSndCardInitFunc)(struct _MSSndCard *obj);
typedef void (*MSSndCardUninitFunc)(struct _MSSndCard *obj);
typedef void (*MSSndCardSetLevelFunc)(struct _MSSndCard *obj, MSSndCardMixerElem e, int percent);
typedef void (*MSSndCardSetCaptureFunc)(struct _MSSndCard *obj, MSSndCardCapture e);
typedef int (*MSSndCardGetLevelFunc)(struct _MSSndCard *obj, MSSndCardMixerElem e);
94
typedef int (*MSSndCardSetControlFunc)(struct _MSSndCard *obj, MSSndCardControlElem e, int val);
95
typedef int (*MSSndCardGetControlFunc)(struct _MSSndCard *obj, MSSndCardControlElem e);
aymeric's avatar
aymeric committed
96
97
98
typedef struct _MSFilter * (*MSSndCardCreateReaderFunc)(struct _MSSndCard *obj);
typedef struct _MSFilter * (*MSSndCardCreateWriterFunc)(struct _MSSndCard *obj);
typedef struct _MSSndCard * (*MSSndCardDuplicateFunc)(struct _MSSndCard *obj);
99
typedef void (*MSSndCardUnloadFunc)(MSSndCardManager *obj);
aymeric's avatar
aymeric committed
100
101
102
103
104
105
106
107

struct _MSSndCardDesc{
	const char *driver_type;
	MSSndCardDetectFunc detect;
	MSSndCardInitFunc init;
	MSSndCardSetLevelFunc set_level;
	MSSndCardGetLevelFunc get_level;
	MSSndCardSetCaptureFunc set_capture;
108
109
	MSSndCardSetControlFunc set_control;
	MSSndCardGetControlFunc get_control;
aymeric's avatar
aymeric committed
110
111
112
113
	MSSndCardCreateReaderFunc create_reader;
	MSSndCardCreateWriterFunc create_writer;
	MSSndCardUninitFunc uninit;
	MSSndCardDuplicateFunc duplicate;
114
	MSSndCardUnloadFunc unload;
aymeric's avatar
aymeric committed
115
116
117
118
119
120
121
122
123

};

/**
 * Structure for sound card description object.
 * @var MSSndCardDesc
 */
typedef struct _MSSndCardDesc MSSndCardDesc;

Simon Morlat's avatar
Simon Morlat committed
124
125
126
#define MS_SND_CARD_CAP_DISABLED (0) /**<This soundcard is disabled.*/
#define MS_SND_CARD_CAP_CAPTURE (1) /**<This sound card can capture sound */
#define MS_SND_CARD_CAP_PLAYBACK (1<<1) /**<This sound card can playback sound */
127
#define MS_SND_CARD_CAP_BUILTIN_ECHO_CANCELLER (1<<2) /**<This sound card has built-in echo cancellation*/
aymeric's avatar
aymeric committed
128
129
130
131
132
133
134

struct _MSSndCard{
	MSSndCardDesc *desc;
	char *name;
	char *id;
	unsigned int capabilities;
	void *data;
jehan's avatar
jehan committed
135
	int preferred_sample_rate;
Simon Morlat's avatar
Simon Morlat committed
136
	int latency;
aymeric's avatar
aymeric committed
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
};

/**
 * Structure for sound card object.
 * @var MSSndCard
 */
typedef struct _MSSndCard MSSndCard;

#ifdef __cplusplus
extern "C"{
#endif

/**
 * @defgroup mediastreamer2_soundcardmanager Sound Card Manager API
 * @ingroup mediastreamer2_soundcard
 * @{
 */

/**
 * Retreive a sound card manager object.
 *
 * Returns: MSSndCardManager if successfull, NULL otherwise.
 */
Simon Morlat's avatar
Simon Morlat committed
160
MS2_PUBLIC MSSndCardManager * ms_snd_card_manager_get(void);
aymeric's avatar
aymeric committed
161
162
163
164
165

/**
 * Destroy a sound card manager object.
 *
 */
Simon Morlat's avatar
Simon Morlat committed
166
MS2_PUBLIC void ms_snd_card_manager_destroy(void);
aymeric's avatar
aymeric committed
167
168
169
170
171
172
173
174
175

/**
 * Retreive a sound card object based on its name.
 *
 * @param m    A sound card manager containing sound cards.
 * @param id   A name for card to search.
 *
 * Returns: MSSndCard if successfull, NULL otherwise.
 */
Simon Morlat's avatar
Simon Morlat committed
176
MS2_PUBLIC MSSndCard * ms_snd_card_manager_get_card(MSSndCardManager *m, const char *id);
aymeric's avatar
aymeric committed
177
178
179
180
181
182
183
184

/**
 * Retreive the default sound card object.
 *
 * @param m    A sound card manager containing sound cards.
 *
 * Returns: MSSndCard if successfull, NULL otherwise.
 */
Simon Morlat's avatar
Simon Morlat committed
185
MS2_PUBLIC MSSndCard * ms_snd_card_manager_get_default_card(MSSndCardManager *m);
aymeric's avatar
aymeric committed
186

187
188
189
190
191
192
193
/**
 * Retreive the default capture sound card object.
 *
 * @param m    A sound card manager containing sound cards.
 *
 * Returns: MSSndCard if successfull, NULL otherwise.
 */
Simon Morlat's avatar
Simon Morlat committed
194
MS2_PUBLIC MSSndCard * ms_snd_card_manager_get_default_capture_card(MSSndCardManager *m);
195
196
197
198
199
200
201
202

/**
 * Retreive the default playback sound card object.
 *
 * @param m    A sound card manager containing sound cards.
 *
 * Returns: MSSndCard if successfull, NULL otherwise.
 */
Simon Morlat's avatar
Simon Morlat committed
203
MS2_PUBLIC MSSndCard * ms_snd_card_manager_get_default_playback_card(MSSndCardManager *m);
204

aymeric's avatar
aymeric committed
205
206
207
208
209
210
211
/**
 * Retreive the list of sound card objects.
 *
 * @param m    A sound card manager containing sound cards.
 *
 * Returns: MSList of cards if successfull, NULL otherwise.
 */
Simon Morlat's avatar
Simon Morlat committed
212
MS2_PUBLIC const MSList * ms_snd_card_manager_get_list(MSSndCardManager *m);
aymeric's avatar
aymeric committed
213
214
215
216
217
218
219
220

/**
 * Add a sound card object in a sound card manager's list.
 *
 * @param m    A sound card manager containing sound cards.
 * @param c    A sound card object.
 *
 */
Simon Morlat's avatar
Simon Morlat committed
221
MS2_PUBLIC void ms_snd_card_manager_add_card(MSSndCardManager *m, MSSndCard *c);
aymeric's avatar
aymeric committed
222
223
224
225
226
227
228
229

/**
 * Register a sound card description in a sound card manager.
 *
 * @param m      A sound card manager containing sound cards.
 * @param desc   A sound card description object.
 *
 */
Simon Morlat's avatar
Simon Morlat committed
230
MS2_PUBLIC void ms_snd_card_manager_register_desc(MSSndCardManager *m, MSSndCardDesc *desc);
aymeric's avatar
aymeric committed
231

232
233
234
235
/**
 * Ask all registered MSSndCardDesc to re-detect their soundcards.
 * @param m The sound card manager.
**/
Simon Morlat's avatar
Simon Morlat committed
236
MS2_PUBLIC void ms_snd_card_manager_reload(MSSndCardManager *m);
237

Simon Morlat's avatar
Simon Morlat committed
238

aymeric's avatar
aymeric committed
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
/** @} */

/**
 * @defgroup mediastreamer2_soundcardfilter Sound Card Filter API
 * @ingroup mediastreamer2_soundcard
 * @{
 */

/**
 * Create an INPUT filter based on the selected sound card.
 *
 * @param obj      A sound card object.
 *
 * Returns: A MSFilter if successfull, NULL otherwise.
 */
Simon Morlat's avatar
Simon Morlat committed
254
MS2_PUBLIC struct _MSFilter * ms_snd_card_create_reader(MSSndCard *obj);
aymeric's avatar
aymeric committed
255
256
257
258
259
260
261
262

/**
 * Create an OUPUT filter based on the selected sound card.
 *
 * @param obj      A sound card object.
 *
 * Returns: A MSFilter if successfull, NULL otherwise.
 */
Simon Morlat's avatar
Simon Morlat committed
263
MS2_PUBLIC struct _MSFilter * ms_snd_card_create_writer(MSSndCard *obj);
aymeric's avatar
aymeric committed
264
265
266
267
268
269
270
271

/**
 * Create a new sound card object.
 *
 * @param desc   A sound card description object.
 *
 * Returns: MSSndCard if successfull, NULL otherwise.
 */
Simon Morlat's avatar
Simon Morlat committed
272
MS2_PUBLIC MSSndCard * ms_snd_card_new(MSSndCardDesc *desc);
aymeric's avatar
aymeric committed
273

jehan's avatar
jehan committed
274
275
276
277
278
279
280
281
282
/**
 * Create a new sound card object.
 *
 * @param desc   A sound card description object.
 * @param card mame
 *
 * Returns: MSSndCard if successfull, NULL otherwise.
 */
	
Simon Morlat's avatar
Simon Morlat committed
283
MS2_PUBLIC MSSndCard * ms_snd_card_new_with_name(MSSndCardDesc *desc,const char* name);
aymeric's avatar
aymeric committed
284
285
286
287
288
/**
 * Destroy sound card object.
 *
 * @param obj   A MSSndCard object.
 */
Simon Morlat's avatar
Simon Morlat committed
289
MS2_PUBLIC void ms_snd_card_destroy(MSSndCard *obj);
aymeric's avatar
aymeric committed
290
291
292
293
294
295
296
297
298
299

/**
 * Duplicate a sound card object.
 *
 * This helps to open several time a sound card.
 *
 * @param card   A sound card object.
 *
 * Returns: MSSndCard if successfull, NULL otherwise.
 */
Simon Morlat's avatar
Simon Morlat committed
300
MS2_PUBLIC MSSndCard * ms_snd_card_dup(MSSndCard *card);
aymeric's avatar
aymeric committed
301
302
303
304
305
306
307
308
309
310

/**
 * Retreive a sound card's driver type string.
 *
 * Internal driver types are either: "OSS, ALSA, WINSND, PASND, CA"
 *
 * @param obj   A sound card object.
 *
 * Returns: a string if successfull, NULL otherwise.
 */
Simon Morlat's avatar
Simon Morlat committed
311
MS2_PUBLIC const char *ms_snd_card_get_driver_type(const MSSndCard *obj);
aymeric's avatar
aymeric committed
312
313
314
315
316
317
318
319

/**
 * Retreive a sound card's name.
 *
 * @param obj   A sound card object.
 *
 * Returns: a string if successfull, NULL otherwise.
 */
Simon Morlat's avatar
Simon Morlat committed
320
MS2_PUBLIC const char *ms_snd_card_get_name(const MSSndCard *obj);
aymeric's avatar
aymeric committed
321
322
323
324
325
326
327
328

/**
 * Retreive sound card's name ($driver_type: $name).
 *
 * @param obj    A sound card object.
 *
 * Returns: A string if successfull, NULL otherwise.
 */
Simon Morlat's avatar
Simon Morlat committed
329
MS2_PUBLIC const char *ms_snd_card_get_string_id(MSSndCard *obj);
aymeric's avatar
aymeric committed
330
331
332
333
334
335
336
337
338


/**
 * Retreive sound card's capabilities.
 *
 * <PRE>
 *   MS_SND_CARD_CAP_CAPTURE
 *   MS_SND_CARD_CAP_PLAYBACK
 *   MS_SND_CARD_CAP_CAPTURE|MS_SND_CARD_CAP_PLAYBACK
339
 *   MS_SND_CARD_CAP_BUILTIN_ECHO_CANCELLER
aymeric's avatar
aymeric committed
340
341
342
343
344
345
 * </PRE>
 *
 * @param obj    A sound card object.
 *
 * Returns: A unsigned int if successfull, 0 otherwise.
 */
Simon Morlat's avatar
Simon Morlat committed
346
MS2_PUBLIC unsigned int ms_snd_card_get_capabilities(const MSSndCard *obj);
aymeric's avatar
aymeric committed
347

Simon Morlat's avatar
Simon Morlat committed
348
349
350
351
352
353
354
355
356
/**
 * Returns the sound card minimal latency (playback+record), in milliseconds.
 * This value is to be used by the software echo cancellers to know where to search for the echo (optimization).
 * Typically, an echo shall not be found before the value returned by this function.
 * If this value is not known, then it should return 0.
 * @param obj    A sound card object.
**/
MS2_PUBLIC int ms_snd_card_get_minimal_latency(MSSndCard *obj);

aymeric's avatar
aymeric committed
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
/**
 * Set some mixer level value.
 *
 * <PRE>
 *   MS_SND_CARD_MASTER,
 *   MS_SND_CARD_PLAYBACK,
 *   MS_SND_CARD_CAPTURE
 * </PRE>
 * Note: not implemented on all sound card filters.
 *
 * @param obj      A sound card object.
 * @param e        A sound card mixer object.
 * @param percent  A volume level.
 *
 */
Simon Morlat's avatar
Simon Morlat committed
372
MS2_PUBLIC void ms_snd_card_set_level(MSSndCard *obj, MSSndCardMixerElem e, int percent);
aymeric's avatar
aymeric committed
373
374
375
376
377
378
379
380
381
382
383
384
385
386

/**
 * Get some mixer level value.
 *
 * <PRE>
 *   MS_SND_CARD_MASTER,
 *   MS_SND_CARD_PLAYBACK,
 *   MS_SND_CARD_CAPTURE
 * </PRE>
 * Note: not implemented on all sound card filters.
 *
 * @param obj      A sound card object.
 * @param e        A sound card mixer object.
 *
387
 * Returns: A int if successfull, <0 otherwise.
aymeric's avatar
aymeric committed
388
 */
Simon Morlat's avatar
Simon Morlat committed
389
MS2_PUBLIC int ms_snd_card_get_level(MSSndCard *obj, MSSndCardMixerElem e);
aymeric's avatar
aymeric committed
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404

/**
 * Set some source for capture.
 *
 * <PRE>
 *   MS_SND_CARD_MIC,
 *   MS_SND_CARD_LINE
 * </PRE>
 * Note: not implemented on all sound card filters.
 *
 * @param obj      A sound card object.
 * @param c        A sound card capture value.
 *
 * Returns: A int if successfull, 0 otherwise.
 */
Simon Morlat's avatar
Simon Morlat committed
405
MS2_PUBLIC void ms_snd_card_set_capture(MSSndCard *obj, MSSndCardCapture c);
aymeric's avatar
aymeric committed
406

407
408
409
410
411
412
413
414
415
416
417
418
419
420
/**
 * Set some mixer control.
 *
 * <PRE>
 *   MS_SND_CARD_MASTER_MUTE, -> 0: unmute, 1: mute
 *   MS_SND_CARD_PLAYBACK_MUTE, -> 0: unmute, 1: mute
 *   MS_SND_CARD_CAPTURE_MUTE -> 0: unmute, 1: mute
 * </PRE>
 * Note: not implemented on all sound card filters.
 *
 * @param obj      A sound card object.
 * @param e        A sound card control object.
 * @param percent  A value for control.
 *
421
 * Returns: 0 if successfull, <0 otherwise.
422
 */
Simon Morlat's avatar
Simon Morlat committed
423
MS2_PUBLIC int ms_snd_card_set_control(MSSndCard *obj, MSSndCardControlElem e, int val);
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439

/**
 * Get some mixer control.
 *
 * <PRE>
 *   MS_SND_CARD_MASTER_MUTE, -> return 0: unmute, 1: mute
 *   MS_SND_CARD_PLAYBACK_MUTE, -> return 0: unmute, 1: mute
 *   MS_SND_CARD_CAPTURE_MUTE -> return 0: unmute, 1: mute
 * </PRE>
 * Note: not implemented on all sound card filters.
 *
 * @param obj      A sound card object.
 * @param e        A sound card mixer object.
 *
 * Returns: A int if successfull, <0 otherwise.
 */
Simon Morlat's avatar
Simon Morlat committed
440
MS2_PUBLIC int ms_snd_card_get_control(MSSndCard *obj, MSSndCardControlElem e);
441

jehan's avatar
jehan committed
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
/**
 * Get preferred sample rate
 *
 * @param obj      A sound card object.
 *
 * Returns: return sample rate in khz
 */
MS2_PUBLIC int ms_snd_card_get_preferred_sample_rate(const MSSndCard *obj);

/**
 * set preferred sample rate. The underlying card will try to avoid any resampling for this samplerate.
 *
 * @param obj      A sound card object.
 * @param rate     sampling rate. 
 *
 * Returns:  0 if successfull, <0 otherwise.
 */
MS2_PUBLIC int ms_snd_card_set_preferred_sample_rate(MSSndCard *obj,int rate);
	

aymeric's avatar
aymeric committed
462
463
464
465
466
467
468
/**
 * Create a alsa card with user supplied pcm name and mixer name.
 * @param pcmdev The pcm device name following alsa conventions (ex: plughw:0)
 * @param mixdev The mixer device name following alsa conventions.
 *
 * Returns: a MSSndCard object, NULL if alsa support is not available.
 */
Simon Morlat's avatar
Simon Morlat committed
469
MS2_PUBLIC MSSndCard * ms_alsa_card_new_custom(const char *pcmdev, const char *mixdev);
aymeric's avatar
aymeric committed
470
471


472
473
474
475
476
477
478
/**
 * Use supplied sample rate to open alsa devices (forced rate).
 * Has no interest except workarouding driver bugs.
 * Use -1 to revert to normal behavior.
**/
MS2_PUBLIC void ms_alsa_card_set_forced_sample_rate(int samplerate);

aymeric's avatar
aymeric committed
479
480
481
482
483
484
485
486
487
/** @} */

#ifdef __cplusplus
}
#endif

/** @} */

#endif