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