← Back to branch summary

~ubuntu-branches/ubuntu/trusty/sflphone/trusty

« back to all changes in this revision

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

  • Committer: Package Import Robot
  • Author(s): Mark Purcell
  • Date: 2014-01-28 18:23:36 UTC
  • mfrom: (4.3.4 sid)
  • Revision ID: package-import@ubuntu.com-20140128182336-jrsv0k9u6cawc068
Tags: 1.3.0-1
http://bugs.debian.org/735846
http://bugs.debian.org/727164
http://bugs.debian.org/718178
http://bugs.debian.org/736583
http://bugs.debian.org/722040
http://bugs.debian.org/736746
* New upstream release 
  - Fixes "New Upstream Release" (Closes: #735846)
  - Fixes "Ringtone does not stop" (Closes: #727164)
  - Fixes "[sflphone-kde] crash on startup" (Closes: #718178)
  - Fixes "sflphone GUI crashes when call is hung up" (Closes: #736583)
* Build-Depends: ensure GnuTLS 2.6
  - libucommon-dev (>= 6.0.7-1.1), libccrtp-dev (>= 2.0.6-3)
  - Fixes "FTBFS Build-Depends libgnutls{26,28}-dev" (Closes: #722040)
* Fix "boost 1.49 is going away" unversioned Build-Depends: (Closes: #736746)
* Add Build-Depends: libsndfile-dev, nepomuk-core-dev

Show diffs side-by-side

added added

removed removed

Lines of Context:
daemon/libs/pjproject-2.1.0/pjmedia/include/pjmedia/sound.h
 
1
/* $Id: sound.h 3553 2011-05-05 06:14:19Z nanang $ */
 
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__ */