← Back to branch summary

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

« back to all changes in this revision

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