mssndcard.h 11.4 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 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41
/*
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

#include "mscommon.h"

/**
 * @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;

124
#define MS_SND_CARD_CAP_DISABLED (0)
aymeric's avatar
aymeric committed
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
#define MS_SND_CARD_CAP_CAPTURE (1)
#define MS_SND_CARD_CAP_PLAYBACK (1<<1)

struct _MSSndCard{
	MSSndCardDesc *desc;
	char *name;
	char *id;
	unsigned int capabilities;
	void *data;
};

/**
 * 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
157
MS2_PUBLIC MSSndCardManager * ms_snd_card_manager_get(void);
aymeric's avatar
aymeric committed
158 159 160 161 162

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

/**
 * 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
173
MS2_PUBLIC MSSndCard * ms_snd_card_manager_get_card(MSSndCardManager *m, const char *id);
aymeric's avatar
aymeric committed
174 175 176 177 178 179 180 181

/**
 * 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
182
MS2_PUBLIC MSSndCard * ms_snd_card_manager_get_default_card(MSSndCardManager *m);
aymeric's avatar
aymeric committed
183

184 185 186 187 188 189 190
/**
 * 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
191
MS2_PUBLIC MSSndCard * ms_snd_card_manager_get_default_capture_card(MSSndCardManager *m);
192 193 194 195 196 197 198 199

/**
 * 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
200
MS2_PUBLIC MSSndCard * ms_snd_card_manager_get_default_playback_card(MSSndCardManager *m);
201

aymeric's avatar
aymeric committed
202 203 204 205 206 207 208
/**
 * 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
209
MS2_PUBLIC const MSList * ms_snd_card_manager_get_list(MSSndCardManager *m);
aymeric's avatar
aymeric committed
210 211 212 213 214 215 216 217

/**
 * 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
218
MS2_PUBLIC void ms_snd_card_manager_add_card(MSSndCardManager *m, MSSndCard *c);
aymeric's avatar
aymeric committed
219 220 221 222 223 224 225 226

/**
 * 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
227
MS2_PUBLIC void ms_snd_card_manager_register_desc(MSSndCardManager *m, MSSndCardDesc *desc);
aymeric's avatar
aymeric committed
228

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

aymeric's avatar
aymeric committed
235 236 237 238 239 240 241 242 243 244 245 246 247 248 249
/** @} */

/**
 * @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
250
MS2_PUBLIC struct _MSFilter * ms_snd_card_create_reader(MSSndCard *obj);
aymeric's avatar
aymeric committed
251 252 253 254 255 256 257 258

/**
 * 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
259
MS2_PUBLIC struct _MSFilter * ms_snd_card_create_writer(MSSndCard *obj);
aymeric's avatar
aymeric committed
260 261 262 263 264 265 266 267

/**
 * 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
268
MS2_PUBLIC MSSndCard * ms_snd_card_new(MSSndCardDesc *desc);
aymeric's avatar
aymeric committed
269

270 271 272 273 274 275 276 277 278
/**
 * 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
279
MS2_PUBLIC MSSndCard * ms_snd_card_new_with_name(MSSndCardDesc *desc,const char* name);
aymeric's avatar
aymeric committed
280 281 282 283 284
/**
 * Destroy sound card object.
 *
 * @param obj   A MSSndCard object.
 */
Simon Morlat's avatar
Simon Morlat committed
285
MS2_PUBLIC void ms_snd_card_destroy(MSSndCard *obj);
aymeric's avatar
aymeric committed
286 287 288 289 290 291 292 293 294 295

/**
 * 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
296
MS2_PUBLIC MSSndCard * ms_snd_card_dup(MSSndCard *card);
aymeric's avatar
aymeric committed
297 298 299 300 301 302 303 304 305 306

/**
 * 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
307
MS2_PUBLIC const char *ms_snd_card_get_driver_type(const MSSndCard *obj);
aymeric's avatar
aymeric committed
308 309 310 311 312 313 314 315

/**
 * 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
316
MS2_PUBLIC const char *ms_snd_card_get_name(const MSSndCard *obj);
aymeric's avatar
aymeric committed
317 318 319 320 321 322 323 324

/**
 * 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
325
MS2_PUBLIC const char *ms_snd_card_get_string_id(MSSndCard *obj);
aymeric's avatar
aymeric committed
326 327 328 329 330 331 332 333 334 335 336 337 338 339 340


/**
 * 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
 * </PRE>
 *
 * @param obj    A sound card object.
 *
 * Returns: A unsigned int if successfull, 0 otherwise.
 */
Simon Morlat's avatar
Simon Morlat committed
341
MS2_PUBLIC unsigned int ms_snd_card_get_capabilities(const MSSndCard *obj);
aymeric's avatar
aymeric committed
342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357

/**
 * 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
358
MS2_PUBLIC void ms_snd_card_set_level(MSSndCard *obj, MSSndCardMixerElem e, int percent);
aymeric's avatar
aymeric committed
359 360 361 362 363 364 365 366 367 368 369 370 371 372

/**
 * 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.
 *
373
 * Returns: A int if successfull, <0 otherwise.
aymeric's avatar
aymeric committed
374
 */
Simon Morlat's avatar
Simon Morlat committed
375
MS2_PUBLIC int ms_snd_card_get_level(MSSndCard *obj, MSSndCardMixerElem e);
aymeric's avatar
aymeric committed
376 377 378 379 380 381 382 383 384 385 386 387 388 389 390

/**
 * 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
391
MS2_PUBLIC void ms_snd_card_set_capture(MSSndCard *obj, MSSndCardCapture c);
aymeric's avatar
aymeric committed
392

393 394 395 396 397 398 399 400 401 402 403 404 405 406
/**
 * 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.
 *
407
 * Returns: 0 if successfull, <0 otherwise.
408
 */
Simon Morlat's avatar
Simon Morlat committed
409
MS2_PUBLIC int ms_snd_card_set_control(MSSndCard *obj, MSSndCardControlElem e, int val);
410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425

/**
 * 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
426
MS2_PUBLIC int ms_snd_card_get_control(MSSndCard *obj, MSSndCardControlElem e);
427

aymeric's avatar
aymeric committed
428 429 430 431 432 433 434
/**
 * 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
435
MS2_PUBLIC MSSndCard * ms_alsa_card_new_custom(const char *pcmdev, const char *mixdev);
aymeric's avatar
aymeric committed
436 437 438 439 440 441 442 443 444 445 446


/** @} */

#ifdef __cplusplus
}
#endif

/** @} */

#endif