← Back to branch summary

~ubuntu-branches/ubuntu/wily/sflphone/wily

« back to all changes in this revision

Viewing changes to daemon/libs/pjproject-2.1.0/pjmedia/include/pjmedia-audiodev/config.h

  • Committer: Package Import Robot
  • Author(s): Jonathan Riddell
  • Date: 2015-01-07 14:51:16 UTC
  • mfrom: (4.3.5 sid)
  • Revision ID: package-import@ubuntu.com-20150107145116-yxnafinf4lrdvrmx
Tags: 1.4.1-0.1ubuntu1
* Merge with Debian, remaining changes:
 - Drop soprano, nepomuk build-dep
* Drop ubuntu patches, now upstream

Show diffs side-by-side

added added

removed removed

Lines of Context:
daemon/libs/pjproject-2.1.0/pjmedia/include/pjmedia-audiodev/config.h
1
 
/* $Id: config.h 4150 2012-06-01 04:29:56Z ming $ */
2
 
/* 
3
 
 * Copyright (C) 2008-2011 Teluu Inc. (http://www.teluu.com)
4
 
 * Copyright (C) 2003-2008 Benny Prijono <benny@prijono.org>
5
 
 *
6
 
 * This program is free software; you can redistribute it and/or modify
7
 
 * it under the terms of the GNU General Public License as published by
8
 
 * the Free Software Foundation; either version 2 of the License, or
9
 
 * (at your option) any later version.
10
 
 *
11
 
 * This program is distributed in the hope that it will be useful,
12
 
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
13
 
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
14
 
 * GNU General Public License for more details.
15
 
 *
16
 
 * You should have received a copy of the GNU General Public License
17
 
 * along with this program; if not, write to the Free Software
18
 
 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA 
19
 
 */
20
 
#ifndef __PJMEDIA_AUDIODEV_CONFIG_H__
21
 
#define __PJMEDIA_AUDIODEV_CONFIG_H__
22
 
 
23
 
/**
24
 
 * @file config.h
25
 
 * @brief Audio config.
26
 
 */
27
 
#include <pjmedia/types.h>
28
 
#include <pj/pool.h>
29
 
 
30
 
 
31
 
PJ_BEGIN_DECL
32
 
 
33
 
/**
34
 
 * @defgroup audio_device_api Audio Device API
35
 
 * @brief PJMEDIA audio device abstraction API.
36
 
 */
37
 
 
38
 
/**
39
 
 * @defgroup s1_audio_device_config Compile time configurations
40
 
 * @ingroup audio_device_api
41
 
 * @brief Compile time configurations
42
 
 * @{
43
 
 */
44
 
 
45
 
/**
46
 
 * This setting controls whether PortAudio support should be included.
47
 
 *
48
 
 * By default it is enabled except on Windows platforms (including
49
 
 * Windows Mobile) and Symbian.
50
 
 */
51
 
#ifndef PJMEDIA_AUDIO_DEV_HAS_PORTAUDIO
52
 
#   if (defined(PJ_WIN32) && PJ_WIN32!=0) || \
53
 
       (defined(PJ_SYMBIAN) && PJ_SYMBIAN!=0)
54
 
#       define PJMEDIA_AUDIO_DEV_HAS_PORTAUDIO  0
55
 
#   else
56
 
#       define PJMEDIA_AUDIO_DEV_HAS_PORTAUDIO  1
57
 
#   endif
58
 
#endif
59
 
 
60
 
/**
61
 
 * This setting controls whether BlackBerry 10 (BB10) audio support
62
 
 * should be included.
63
 
 */
64
 
#ifndef PJMEDIA_AUDIO_DEV_HAS_BB10
65
 
#   define PJMEDIA_AUDIO_DEV_HAS_BB10           0
66
 
#endif
67
 
 
68
 
/**
69
 
 * This setting controls whether native ALSA support should be included.
70
 
 */
71
 
#ifndef PJMEDIA_AUDIO_DEV_HAS_ALSA
72
 
#   define PJMEDIA_AUDIO_DEV_HAS_ALSA           0
73
 
#endif
74
 
 
75
 
 
76
 
/**
77
 
 * This setting controls whether null audio support should be included.
78
 
 */
79
 
#ifndef PJMEDIA_AUDIO_DEV_HAS_NULL_AUDIO
80
 
#   define PJMEDIA_AUDIO_DEV_HAS_NULL_AUDIO     0
81
 
#endif
82
 
 
83
 
 
84
 
/**
85
 
 * This setting controls whether coreaudio support should be included.
86
 
 */
87
 
#ifndef PJMEDIA_AUDIO_DEV_HAS_COREAUDIO
88
 
#   define PJMEDIA_AUDIO_DEV_HAS_COREAUDIO      0
89
 
#endif
90
 
 
91
 
 
92
 
/**
93
 
 * This setting controls whether WMME support should be included.
94
 
 */
95
 
#ifndef PJMEDIA_AUDIO_DEV_HAS_WMME
96
 
#   define PJMEDIA_AUDIO_DEV_HAS_WMME           1
97
 
#endif
98
 
 
99
 
 
100
 
/**
101
 
 * This setting controls whether Symbian APS support should be included.
102
 
 */
103
 
#ifndef PJMEDIA_AUDIO_DEV_HAS_SYMB_APS
104
 
#   define PJMEDIA_AUDIO_DEV_HAS_SYMB_APS       0
105
 
#endif
106
 
 
107
 
 
108
 
/**
109
 
 * This setting controls whether Symbian APS should perform codec
110
 
 * detection in its factory initalization. Note that codec detection 
111
 
 * may take few seconds and detecting more codecs will take more time.
112
 
 * Possible values are:
113
 
 * - 0: no codec detection, all APS codec (AMR-NB, G.711, G.729, and
114
 
 *      iLBC) will be assumed as supported.
115
 
 * - 1: minimal codec detection, i.e: only detect for AMR-NB and G.711,
116
 
 *      (G.729 and iLBC are considered to be supported/unsupported when
117
 
 *      G.711 is supported/unsupported).
118
 
 * - 2: full codec detection, i.e: detect AMR-NB, G.711, G.729, and iLBC.
119
 
 * 
120
 
 * Default: 1 (minimal codec detection)
121
 
 */
122
 
#ifndef PJMEDIA_AUDIO_DEV_SYMB_APS_DETECTS_CODEC
123
 
#   define PJMEDIA_AUDIO_DEV_SYMB_APS_DETECTS_CODEC 1
124
 
#endif
125
 
 
126
 
 
127
 
/**
128
 
 * This setting controls whether Symbian VAS support should be included.
129
 
 */
130
 
#ifndef PJMEDIA_AUDIO_DEV_HAS_SYMB_VAS
131
 
#   define PJMEDIA_AUDIO_DEV_HAS_SYMB_VAS       0
132
 
#endif
133
 
 
134
 
/**
135
 
 * This setting controls Symbian VAS version to be used. Currently, valid
136
 
 * values are only 1 (for VAS 1.0) and 2 (for VAS 2.0).
137
 
 *
138
 
 * Default: 1 (VAS version 1.0)
139
 
 */
140
 
#ifndef PJMEDIA_AUDIO_DEV_SYMB_VAS_VERSION
141
 
#   define PJMEDIA_AUDIO_DEV_SYMB_VAS_VERSION   1
142
 
#endif
143
 
 
144
 
 
145
 
/**
146
 
 * This setting controls whether Symbian audio (using built-in multimedia 
147
 
 * framework) support should be included.
148
 
 */
149
 
#ifndef PJMEDIA_AUDIO_DEV_HAS_SYMB_MDA
150
 
#   define PJMEDIA_AUDIO_DEV_HAS_SYMB_MDA       PJ_SYMBIAN
151
 
#endif
152
 
 
153
 
 
154
 
/**
155
 
 * This setting controls whether the Symbian audio with built-in multimedia
156
 
 * framework backend should be started synchronously. Note that synchronous
157
 
 * start will block the application/UI, e.g: about 40ms for each direction
158
 
 * on N95. While asynchronous start may cause invalid value (always zero)
159
 
 * returned in input/output volume query, if the query is performed when
160
 
 * the internal start procedure is not completely finished.
161
 
 * 
162
 
 * Default: 1 (yes)
163
 
 */
164
 
#ifndef PJMEDIA_AUDIO_DEV_MDA_USE_SYNC_START
165
 
#   define PJMEDIA_AUDIO_DEV_MDA_USE_SYNC_START 1
166
 
#endif
167
 
 
168
 
 
169
 
/**
170
 
 * This setting controls whether the Audio Device API should support
171
 
 * device implementation that is based on the old sound device API
172
 
 * (sound.h). 
173
 
 *
174
 
 * Enable this API if:
175
 
 *  - you have implemented your own sound device using the old sound
176
 
 *    device API (sound.h), and
177
 
 *  - you wish to be able to use your sound device implementation
178
 
 *    using the new Audio Device API.
179
 
 *
180
 
 * Please see http://trac.pjsip.org/repos/wiki/Audio_Dev_API for more
181
 
 * info.
182
 
 */
183
 
#ifndef PJMEDIA_AUDIO_DEV_HAS_LEGACY_DEVICE
184
 
#   define PJMEDIA_AUDIO_DEV_HAS_LEGACY_DEVICE  0
185
 
#endif
186
 
 
187
 
 
188
 
/**
189
 
 * @}
190
 
 */
191
 
 
192
 
PJ_END_DECL
193
 
 
194
 
 
195
 
#endif  /* __PJMEDIA_AUDIODEV_CONFIG_H__ */
196
 
 
197
 
/*
198
 
 --------------------- DOCUMENTATION FOLLOWS ---------------------------
199
 
 */
200
 
 
201
 
/**
202
 
 * @addtogroup audio_device_api Audio Device API
203
 
 * @{
204
 
 
205
 
PJMEDIA Audio Device API is a cross-platform audio API appropriate for use with
206
 
VoIP applications and many other types of audio streaming applications. 
207
 
 
208
 
The API abstracts many different audio API's on various platforms, such as:
209
 
 - PortAudio back-end for Win32, Windows Mobile, Linux, Unix, dan MacOS X.
210
 
 - native WMME audio for Win32 and Windows Mobile devices
211
 
 - native Symbian audio streaming/multimedia framework (MMF) implementation
212
 
 - native Nokia Audio Proxy Server (APS) implementation
213
 
 - null-audio implementation
214
 
 - and more to be implemented in the future
215
 
 
216
 
The Audio Device API/library is an evolution from PJMEDIA @ref PJMED_SND and 
217
 
contains many enhancements:
218
 
 
219
 
 - Forward compatibility:
220
 
\n
221
 
   The new API has been designed to be extensible, it will support new API's as 
222
 
   well as new features that may be introduced in the future without breaking 
223
 
   compatibility with applications that use this API as well as compatibility 
224
 
   with existing device implementations. 
225
 
 
226
 
 - Device capabilities:
227
 
\n
228
 
   At the heart of the API is device capabilities management, where all possible
229
 
   audio capabilities of audio devices should be able to be handled in a generic
230
 
   manner. With this framework, new capabilities that may be discovered in the 
231
 
   future can be handled in manner without breaking existing applications. 
232
 
 
233
 
 - Built-in features:
234
 
\n
235
 
   The device capabilities framework enables applications to use and control 
236
 
   audio features built-in in the device, such as:
237
 
    - echo cancellation, 
238
 
    - built-in codecs, 
239
 
    - audio routing (e.g. to earpiece or loudspeaker),
240
 
    - volume control,
241
 
    - etc.
242
 
 
243
 
 - Codec support:
244
 
\n
245
 
   Some audio devices such as Nokia/Symbian Audio Proxy Server (APS) and Nokia 
246
 
   VoIP Audio Services (VAS) support built-in hardware audio codecs (e.g. G.729,
247
 
   iLBC, and AMR), and application can use the sound device in encoded mode to
248
 
   make use of these hardware codecs. 
249
 
 
250
 
 - Multiple backends:
251
 
\n
252
 
   The new API supports multiple audio backends (called factories or drivers in 
253
 
   the code) to be active simultaneously, and audio backends may be added or 
254
 
   removed during run-time. 
255
 
 
256
 
 
257
 
@section using Overview on using the API
258
 
 
259
 
@subsection getting_started Getting started
260
 
 
261
 
 -# <b>Configure the application's project settings</b>.\n
262
 
    Add the following 
263
 
    include:
264
 
    \code
265
 
    #include <pjmedia_audiodev.h>\endcode\n
266
 
    And add <b>pjmedia-audiodev</b> library to your application link 
267
 
    specifications.\n
268
 
 -# <b>Compile time settings</b>.\n
269
 
    Use the compile time settings to enable or
270
 
    disable specific audio drivers. For more information, please see
271
 
    \ref s1_audio_device_config.
272
 
 -# <b>API initialization and cleaning up</b>.\n
273
 
    Before anything else, application must initialize the API by calling:
274
 
    \code
275
 
    pjmedia_aud_subsys_init(pf);\endcode\n
276
 
    And add this in the application cleanup sequence
277
 
    \code
278
 
    pjmedia_aud_subsys_shutdown();\endcode
279
 
 
280
 
@subsection devices Working with devices
281
 
 
282
 
 -# The following code prints the list of audio devices detected
283
 
    in the system.
284
 
    \code
285
 
    int dev_count;
286
 
    pjmedia_aud_dev_index dev_idx;
287
 
    pj_status_t status;
288
 
 
289
 
    dev_count = pjmedia_aud_dev_count();
290
 
    printf("Got %d audio devices\n", dev_count);
291
 
 
292
 
    for (dev_idx=0; dev_idx<dev_count; ++i) {
293
 
        pjmedia_aud_dev_info info;
294
 
 
295
 
        status = pjmedia_aud_dev_get_info(dev_idx, &info);
296
 
        printf("%d. %s (in=%d, out=%d)\n",
297
 
               dev_idx, info.name, 
298
 
               info.input_count, info.output_count);
299
 
    }
300
 
    \endcode\n
301
 
 -# Info: The #PJMEDIA_AUD_DEFAULT_CAPTURE_DEV and #PJMEDIA_AUD_DEFAULT_PLAYBACK_DEV
302
 
    constants are used to denote default capture and playback devices
303
 
    respectively.
304
 
 -# Info: You may save the device and driver's name in your application
305
 
    setting, for example to specify the prefered devices to be
306
 
    used by your application. You can then retrieve the device index
307
 
    for the device by calling:
308
 
    \code
309
 
        const char *drv_name = "WMME";
310
 
        const char *dev_name = "Wave mapper";
311
 
        pjmedia_aud_dev_index dev_idx;
312
 
 
313
 
        status = pjmedia_aud_dev_lookup(drv_name, dev_name, &dev_idx);
314
 
        if (status==PJ_SUCCESS)
315
 
            printf("Device index is %d\n", dev_idx);
316
 
    \endcode
317
 
 
318
 
@subsection caps Device capabilities
319
 
 
320
 
Capabilities are encoded as #pjmedia_aud_dev_cap enumeration. Please see
321
 
#pjmedia_aud_dev_cap enumeration for more information.
322
 
 
323
 
 -# The following snippet prints the capabilities supported by the device:
324
 
    \code
325
 
    pjmedia_aud_dev_info info;
326
 
    pj_status_t status;
327
 
 
328
 
    status = pjmedia_aud_dev_get_info(PJMEDIA_AUD_DEFAULT_CAPTURE_DEV, &info);
329
 
    if (status == PJ_SUCCESS) {
330
 
        unsigned i;
331
 
        // Enumerate capability bits
332
 
        printf("Device capabilities: ");
333
 
        for (i=0; i<32; ++i) {
334
 
            if (info.caps & (1 << i))
335
 
                printf("%s ", pjmedia_aud_dev_cap_name(1 << i, NULL));
336
 
        }
337
 
    }
338
 
    \endcode\n
339
 
 -# Info: You can set the device settings when opening audio stream by setting
340
 
    the flags and the appropriate setting in #pjmedia_aud_param when calling
341
 
    #pjmedia_aud_stream_create()\n
342
 
 -# Info: Once the audio stream is running, you can retrieve or change the stream 
343
 
    setting by specifying the capability in #pjmedia_aud_stream_get_cap()
344
 
    and #pjmedia_aud_stream_set_cap() respectively.
345
 
 
346
 
 
347
 
@subsection creating_stream Creating audio streams
348
 
 
349
 
The audio stream enables audio streaming to capture device, playback device,
350
 
or both.
351
 
 
352
 
 -# It is recommended to initialize the #pjmedia_aud_param with its default
353
 
    values before using it:
354
 
    \code
355
 
    pjmedia_aud_param param;
356
 
    pjmedia_aud_dev_index dev_idx;
357
 
    pj_status_t status;
358
 
 
359
 
    dev_idx = PJMEDIA_AUD_DEFAULT_CAPTURE_DEV;
360
 
    status = pjmedia_aud_dev_default_param(dev_idx, &param);
361
 
    \endcode\n
362
 
 -# Configure the mandatory parameters:
363
 
    \code
364
 
    param.dir = PJMEDIA_DIR_CAPTURE_PLAYBACK;
365
 
    param.rec_id = PJMEDIA_AUD_DEFAULT_CAPTURE_DEV;
366
 
    param.play_id = PJMEDIA_AUD_DEFAULT_PLAYBACK_DEV;
367
 
    param.clock_rate = 8000;
368
 
    param.channel_count = 1;
369
 
    param.samples_per_frame = 160;
370
 
    param.bits_per_sample = 16;
371
 
    \endcode\n
372
 
 -# If you want the audio stream to use the device's built-in codec, specify
373
 
    the codec in the #pjmedia_aud_param. You must make sure that the codec
374
 
    is supported by the device, by looking at its supported format list in
375
 
    the #pjmedia_aud_dev_info.\n
376
 
    The snippet below sets the audio stream to use G.711 ULAW encoding:
377
 
    \code
378
 
    unsigned i;
379
 
 
380
 
    // Make sure Ulaw is supported
381
 
    if ((info.caps & PJMEDIA_AUD_DEV_CAP_EXT_FORMAT) == 0)
382
 
        error("Device does not support extended formats");
383
 
    for (i = 0; i < info.ext_fmt_cnt; ++i) {
384
 
        if (info.ext_fmt[i].id == PJMEDIA_FORMAT_ULAW)
385
 
            break;
386
 
    }
387
 
    if (i == info.ext_fmt_cnt)
388
 
        error("Device does not support Ulaw format");
389
 
 
390
 
    // Set Ulaw format
391
 
    param.flags |= PJMEDIA_AUD_DEV_CAP_EXT_FORMAT;
392
 
    param.ext_fmt.id = PJMEDIA_FORMAT_ULAW;
393
 
    param.ext_fmt.bitrate = 64000;
394
 
    param.ext_fmt.vad = PJ_FALSE;
395
 
    \endcode\n
396
 
 -# Note that if non-PCM format is configured on the audio stream, the
397
 
    capture and/or playback functions (#pjmedia_aud_rec_cb and 
398
 
    #pjmedia_aud_play_cb respectively) will report the audio frame as
399
 
    #pjmedia_frame_ext structure instead of the #pjmedia_frame.
400
 
 -# Optionally configure other device's capabilities. The following snippet
401
 
    shows how to enable echo cancellation on the device (note that this
402
 
    snippet may not be necessary since the setting may have been enabled 
403
 
    when calling #pjmedia_aud_dev_default_param() above):
404
 
    \code
405
 
    if (info.caps & PJMEDIA_AUD_DEV_CAP_EC) {
406
 
        param.flags |= PJMEDIA_AUD_DEV_CAP_EC;
407
 
        param.ec_enabled = PJ_TRUE;
408
 
    }
409
 
    \endcode
410
 
 -# Open the audio stream, specifying the capture and/or playback callback
411
 
    functions:
412
 
    \code
413
 
       pjmedia_aud_stream *stream;
414
 
 
415
 
       status = pjmedia_aud_stream_create(&param, &rec_cb, &play_cb, 
416
 
                                          user_data, &stream);
417
 
    \endcode
418
 
 
419
 
@subsection working_with_stream Working with audio streams
420
 
 
421
 
 -# To start the audio stream:
422
 
    \code
423
 
        status = pjmedia_aud_stream_start(stream);
424
 
    \endcode\n
425
 
    To stop the stream:
426
 
    \code
427
 
        status = pjmedia_aud_stream_stop(stream);
428
 
    \endcode\n
429
 
    And to destroy the stream:
430
 
    \code
431
 
        status = pjmedia_aud_stream_destroy(stream);
432
 
    \endcode\n
433
 
 -# Info: The following shows how to retrieve the capability value of the
434
 
    stream (in this case, the current output volume setting).
435
 
    \code
436
 
    // Volume setting is an unsigned integer showing the level in percent.
437
 
    unsigned vol;
438
 
    status = pjmedia_aud_stream_get_cap(stream, 
439
 
                                        PJMEDIA_AUD_DEV_CAP_OUTPUT_VOLUME_SETTING,
440
 
                                        &vol);
441
 
    \endcode
442
 
 -# Info: And following shows how to modify the capability value of the
443
 
    stream (in this case, the current output volume setting).
444
 
    \code
445
 
    // Volume setting is an unsigned integer showing the level in percent.
446
 
    unsigned vol = 50;
447
 
    status = pjmedia_aud_stream_set_cap(stream, 
448
 
                                        PJMEDIA_AUD_DEV_CAP_OUTPUT_VOLUME_SETTING,
449
 
                                        &vol);
450
 
    \endcode
451
 
 
452
 
 
453
 
*/
454
 
 
455
 
 
456
 
/**
457
 
 * @}
458
 
 */
459