Add support for ICE/STUN/TURN in res_rtp_asterisk and chan_sip.
[asterisk/asterisk.git] / res / pjproject / pjmedia / include / pjmedia / sound.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_SOUND_H__
21 #define __PJMEDIA_SOUND_H__
22
23
24 /**
25  * @file sound.h
26  * @brief Legacy sound device API
27  */
28 #include <pjmedia-audiodev/audiodev.h>
29 #include <pjmedia/types.h>
30
31
32 PJ_BEGIN_DECL
33
34 /**
35  * @defgroup PJMED_SND Portable Sound Hardware Abstraction
36  * @ingroup PJMED_SND_PORT
37  * @brief PJMEDIA abstraction for sound device hardware
38  * @{
39  *
40  * <strong>Warning: this sound device API has been deprecated
41  * and replaced by PJMEDIA Audio Device API. Please see
42  * http://trac.pjsip.org/repos/wiki/Audio_Dev_API for more
43  * information.</strong>
44  *
45  * This section describes lower level abstraction for sound device
46  * hardware. Application normally uses the higher layer @ref
47  * PJMED_SND_PORT abstraction since it works seamlessly with 
48  * @ref PJMEDIA_PORT.
49  *
50  * The sound hardware abstraction basically runs <b>asychronously</b>,
51  * and application must register callbacks to be called to receive/
52  * supply audio frames from/to the sound hardware.
53  *
54  * A full duplex sound stream (created with #pjmedia_snd_open()) 
55  * requires application to supply two callbacks:
56  *  - <b><tt>rec_cb</tt></b> callback to be called when it has finished
57  *    capturing one media frame, and 
58  *  - <b><tt>play_cb</tt></b> callback to be called when it needs media 
59  *    frame to be played to the sound playback hardware.
60  *
61  * Half duplex sound stream (created with #pjmedia_snd_open_rec() or
62  * #pjmedia_snd_open_player()) will only need one of the callback to
63  * be specified.
64  *
65  * After sound stream is created, application need to call
66  * #pjmedia_snd_stream_start() to start capturing/playing back media
67  * frames from/to the sound device.
68  */
69
70 /** Opaque declaration for pjmedia_snd_stream. */
71 typedef struct pjmedia_snd_stream pjmedia_snd_stream;
72
73 /**
74  * Device information structure returned by #pjmedia_snd_get_dev_info.
75  */
76 typedef struct pjmedia_snd_dev_info
77 {
78     char        name[64];               /**< Device name.                   */
79     unsigned    input_count;            /**< Max number of input channels.  */
80     unsigned    output_count;           /**< Max number of output channels. */
81     unsigned    default_samples_per_sec;/**< Default sampling rate.         */
82 } pjmedia_snd_dev_info;
83
84 /** 
85  * Stream information, can be retrieved from a live stream by calling
86  * #pjmedia_snd_stream_get_info().
87  */
88 typedef struct pjmedia_snd_stream_info
89 {
90     pjmedia_dir dir;                /**< Stream direction.                  */
91     int         play_id;            /**< Playback dev id, or -1 for rec only*/
92     int         rec_id;             /**< Capture dev id, or -1 for play only*/
93     unsigned    clock_rate;         /**< Actual clock rate.                 */
94     unsigned    channel_count;      /**< Number of channels.                */
95     unsigned    samples_per_frame;  /**< Samples per frame.                 */
96     unsigned    bits_per_sample;    /**< Bits per sample.                   */
97     unsigned    rec_latency;        /**< Record latency, in samples.        */
98     unsigned    play_latency;       /**< Playback latency, in samples.      */
99 } pjmedia_snd_stream_info;
100
101 /** 
102  * This callback is called by player stream when it needs additional data
103  * to be played by the device. Application must fill in the whole of output 
104  * buffer with sound samples.
105  *
106  * @param user_data     User data associated with the stream.
107  * @param timestamp     Timestamp, in samples.
108  * @param output        Buffer to be filled out by application.
109  * @param size          The size requested in bytes, which will be equal to
110  *                      the size of one whole packet.
111  *
112  * @return              Non-zero to stop the stream.
113  */
114 typedef pj_status_t (*pjmedia_snd_play_cb)(/* in */   void *user_data,
115                                       /* in */   pj_uint32_t timestamp,
116                                       /* out */  void *output,
117                                       /* out */  unsigned size);
118
119 /**
120  * This callback is called by recorder stream when it has captured the whole
121  * packet worth of audio samples.
122  *
123  * @param user_data     User data associated with the stream.
124  * @param timestamp     Timestamp, in samples.
125  * @param output        Buffer containing the captured audio samples.
126  * @param size          The size of the data in the buffer, in bytes.
127  *
128  * @return              Non-zero to stop the stream.
129  */
130 typedef pj_status_t (*pjmedia_snd_rec_cb)(/* in */   void *user_data,
131                                      /* in */   pj_uint32_t timestamp,
132                                      /* in */   void *input,
133                                      /* in*/    unsigned size);
134
135 /**
136  * Init the sound library.
137  *
138  * @param factory       The sound factory.
139  *
140  * @return              Zero on success.
141  */
142 PJ_DECL(pj_status_t) pjmedia_snd_init(pj_pool_factory *factory);
143
144
145 /**
146  * Get the number of devices detected by the library.
147  *
148  * @return              Number of devices.
149  */
150 PJ_DECL(int) pjmedia_snd_get_dev_count(void);
151
152
153 /**
154  * Get device info.
155  *
156  * @param index         The index of the device, which should be in the range
157  *                      from zero to #pjmedia_snd_get_dev_count - 1.
158  */
159 PJ_DECL(const pjmedia_snd_dev_info*) pjmedia_snd_get_dev_info(unsigned index);
160
161
162 /**
163  * Set sound device latency, this function must be called before sound device
164  * opened, or otherwise default latency setting will be used, @see
165  * PJMEDIA_SND_DEFAULT_REC_LATENCY & PJMEDIA_SND_DEFAULT_PLAY_LATENCY.
166  *
167  * Choosing latency value is not straightforward, it should accomodate both 
168  * minimum latency and stability. Lower latency tends to cause sound device 
169  * less reliable (producing audio dropouts) on CPU load disturbance. Moreover,
170  * the best latency setting may vary based on many aspects, e.g: sound card, 
171  * CPU, OS, kernel, etc.
172  *
173  * @param input_latency     The latency of input device, in ms, set to 0
174  *                          for default PJMEDIA_SND_DEFAULT_REC_LATENCY.
175  * @param output_latency    The latency of output device, in ms, set to 0
176  *                          for default PJMEDIA_SND_DEFAULT_PLAY_LATENCY.
177  *
178  * @return                  PJ_SUCCESS on success.
179  */
180 PJ_DECL(pj_status_t) pjmedia_snd_set_latency(unsigned input_latency, 
181                                              unsigned output_latency);
182
183
184 /**
185  * Create sound stream for both capturing audio and audio playback,  from the 
186  * same device. This is the recommended way to create simultaneous recorder 
187  * and player streams (instead of creating separate capture and playback
188  * streams), because it works on backends that does not allow
189  * a device to be opened more than once.
190  *
191  * @param rec_id            Device index for recorder/capture stream, or
192  *                          -1 to use the first capable device.
193  * @param play_id           Device index for playback stream, or -1 to use 
194  *                          the first capable device.
195  * @param clock_rate        Sound device's clock rate to set.
196  * @param channel_count     Set number of channels, 1 for mono, or 2 for
197  *                          stereo. The channel count determines the format
198  *                          of the frame.
199  * @param samples_per_frame Number of samples per frame.
200  * @param bits_per_sample   Set the number of bits per sample. The normal 
201  *                          value for this parameter is 16 bits per sample.
202  * @param rec_cb            Callback to handle captured audio samples.
203  * @param play_cb           Callback to be called when the sound player needs
204  *                          more audio samples to play.
205  * @param user_data         User data to be associated with the stream.
206  * @param p_snd_strm        Pointer to receive the stream instance.
207  *
208  * @return                  PJ_SUCCESS on success.
209  */
210 PJ_DECL(pj_status_t) pjmedia_snd_open(int rec_id,
211                                       int play_id,
212                                       unsigned clock_rate,
213                                       unsigned channel_count,
214                                       unsigned samples_per_frame,
215                                       unsigned bits_per_sample,
216                                       pjmedia_snd_rec_cb rec_cb,
217                                       pjmedia_snd_play_cb play_cb,
218                                       void *user_data,
219                                       pjmedia_snd_stream **p_snd_strm);
220
221
222 /**
223  * Create a unidirectional audio stream for capturing audio samples from
224  * the sound device.
225  *
226  * @param index             Device index, or -1 to let the library choose the 
227  *                          first available device.
228  * @param clock_rate        Sound device's clock rate to set.
229  * @param channel_count     Set number of channels, 1 for mono, or 2 for
230  *                          stereo. The channel count determines the format
231  *                          of the frame.
232  * @param samples_per_frame Number of samples per frame.
233  * @param bits_per_sample   Set the number of bits per sample. The normal 
234  *                          value for this parameter is 16 bits per sample.
235  * @param rec_cb            Callback to handle captured audio samples.
236  * @param user_data         User data to be associated with the stream.
237  * @param p_snd_strm        Pointer to receive the stream instance.
238  *
239  * @return                  PJ_SUCCESS on success.
240  */
241 PJ_DECL(pj_status_t) pjmedia_snd_open_rec( int index,
242                                            unsigned clock_rate,
243                                            unsigned channel_count,
244                                            unsigned samples_per_frame,
245                                            unsigned bits_per_sample,
246                                            pjmedia_snd_rec_cb rec_cb,
247                                            void *user_data,
248                                            pjmedia_snd_stream **p_snd_strm);
249
250 /**
251  * Create a unidirectional audio stream for playing audio samples to the
252  * sound device.
253  *
254  * @param index             Device index, or -1 to let the library choose the 
255  *                          first available device.
256  * @param clock_rate        Sound device's clock rate to set.
257  * @param channel_count     Set number of channels, 1 for mono, or 2 for
258  *                          stereo. The channel count determines the format
259  *                          of the frame.
260  * @param samples_per_frame Number of samples per frame.
261  * @param bits_per_sample   Set the number of bits per sample. The normal 
262  *                          value for this parameter is 16 bits per sample.
263  * @param play_cb           Callback to be called when the sound player needs
264  *                          more audio samples to play.
265  * @param user_data         User data to be associated with the stream.
266  * @param p_snd_strm        Pointer to receive the stream instance.
267  *
268  * @return                  PJ_SUCCESS on success.
269  */
270 PJ_DECL(pj_status_t) pjmedia_snd_open_player( int index,
271                                          unsigned clock_rate,
272                                          unsigned channel_count,
273                                          unsigned samples_per_frame,
274                                          unsigned bits_per_sample,
275                                          pjmedia_snd_play_cb play_cb,
276                                          void *user_data,
277                                          pjmedia_snd_stream **p_snd_strm );
278
279
280 /**
281  * Get information about live stream.
282  *
283  * @param strm          The stream to be queried.
284  * @param pi            Pointer to stream information to be filled up with
285  *                      information about the stream.
286  *
287  * @return              PJ_SUCCESS on success or the appropriate error code.
288  */
289 PJ_DECL(pj_status_t) pjmedia_snd_stream_get_info(pjmedia_snd_stream *strm,
290                                                  pjmedia_snd_stream_info *pi);
291
292
293 /**
294  * Start the stream.
295  *
296  * @param stream        The recorder or player stream.
297  *
298  * @return              Zero on success.
299  */
300 PJ_DECL(pj_status_t) pjmedia_snd_stream_start(pjmedia_snd_stream *stream);
301
302 /**
303  * Stop the stream.
304  *
305  * @param stream        The recorder or player stream.
306  *
307  * @return              Zero on success.
308  */
309 PJ_DECL(pj_status_t) pjmedia_snd_stream_stop(pjmedia_snd_stream *stream);
310
311 /**
312  * Destroy the stream.
313  *
314  * @param stream        The recorder of player stream.
315  *
316  * @return              Zero on success.
317  */
318 PJ_DECL(pj_status_t) pjmedia_snd_stream_close(pjmedia_snd_stream *stream);
319
320 /**
321  * Deinitialize sound library.
322  *
323  * @return              Zero on success.
324  */
325 PJ_DECL(pj_status_t) pjmedia_snd_deinit(void);
326
327
328
329 /**
330  * @}
331  */
332
333 PJ_END_DECL
334
335
336 #endif  /* __PJMEDIA_SOUND_H__ */