1
/* $Id: delaybuf.h 3841 2011-10-24 09:28:13Z ming $ */
3
* Copyright (C) 2008-2011 Teluu Inc. (http://www.teluu.com)
4
* Copyright (C) 2003-2008 Benny Prijono <benny@prijono.org>
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.
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.
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
21
#ifndef __PJMEDIA_DELAYBUF_H__
22
#define __PJMEDIA_DELAYBUF_H__
27
* @brief Delay Buffer.
30
#include <pjmedia/types.h>
33
* @defgroup PJMED_DELAYBUF Adaptive Delay Buffer
34
* @ingroup PJMEDIA_FRAME_OP
35
* @brief Adaptive delay buffer with high-quality time-scale
39
* This section describes PJMEDIA's implementation of delay buffer.
40
* Delay buffer works quite similarly like a fixed jitter buffer, that
41
* is it will delay the frame retrieval by some interval so that caller
42
* will get continuous frame from the buffer. This can be useful when
43
* the put() and get() operations are not evenly interleaved, for example
44
* when caller performs burst of put() operations and then followed by
45
* burst of get() operations. With using this delay buffer, the buffer
46
* will put the burst frames into a buffer so that get() operations
47
* will always get a frame from the buffer (assuming that the number of
48
* get() and put() are matched).
50
* The buffer is adaptive, that is it continuously learns the optimal delay
51
* to be applied to the audio flow at run-time. Once the optimal delay has
52
* been learned, the delay buffer will apply this delay to the audio flow,
53
* expanding or shrinking the audio samples as necessary when the actual
54
* audio samples in the buffer are too low or too high. It does this without
55
* distorting the audio quality of the audio, by using \a PJMED_WSOLA.
57
* The delay buffer is used in \ref PJMED_SND_PORT, \ref PJMEDIA_SPLITCOMB,
58
* and \ref PJMEDIA_CONF.
63
/** Opaque declaration for delay buffer. */
64
typedef struct pjmedia_delay_buf pjmedia_delay_buf;
67
* Delay buffer options.
69
typedef enum pjmedia_delay_buf_flag
72
* Use simple FIFO mechanism for the delay buffer, i.e.
73
* without WSOLA for expanding and shrinking audio samples.
75
PJMEDIA_DELAY_BUF_SIMPLE_FIFO = 1
77
} pjmedia_delay_buf_flag;
80
* Create the delay buffer. Once the delay buffer is created, it will
81
* enter learning state unless the delay argument is specified, which
82
* in this case it will directly enter the running state.
84
* @param pool Pool where the delay buffer will be allocated
86
* @param name Optional name for the buffer for log
88
* @param clock_rate Number of samples processed per second.
89
* @param samples_per_frame Number of samples per frame.
90
* @param channel_count Number of channel per frame.
91
* @param max_delay Maximum number of delay to be accommodated,
92
* in ms, if this value is negative or less than
93
* one frame time, default maximum delay used is
95
* @param options Options. If PJMEDIA_DELAY_BUF_SIMPLE_FIFO is
96
* specified, then a simple FIFO mechanism
97
* will be used instead of the adaptive
98
* implementation (which uses WSOLA to expand
99
* or shrink audio samples).
100
* See #pjmedia_delay_buf_flag for other options.
101
* @param p_b Pointer to receive the delay buffer instance.
103
* @return PJ_SUCCESS if the delay buffer has been
104
* created successfully, otherwise the appropriate
105
* error will be returned.
107
PJ_DECL(pj_status_t) pjmedia_delay_buf_create(pj_pool_t *pool,
110
unsigned samples_per_frame,
111
unsigned channel_count,
114
pjmedia_delay_buf **p_b);
117
* Put one frame into the buffer.
119
* @param b The delay buffer.
120
* @param frame Frame to be put into the buffer. This frame
121
* must have samples_per_frame length.
123
* @return PJ_SUCCESS if frames can be put successfully.
124
* PJ_EPENDING if the buffer is still at learning
125
* state. PJ_ETOOMANY if the number of frames
126
* will exceed maximum delay level, which in this
127
* case the new frame will overwrite the oldest
128
* frame in the buffer.
130
PJ_DECL(pj_status_t) pjmedia_delay_buf_put(pjmedia_delay_buf *b,
134
* Get one frame from the buffer.
136
* @param b The delay buffer.
137
* @param frame Buffer to receive the frame from the delay
140
* @return PJ_SUCCESS if frame has been copied successfully.
141
* PJ_EPENDING if no frame is available, either
142
* because the buffer is still at learning state or
143
* no buffer is available during running state.
144
* On non-successful return, the frame will be
145
* filled with zeroes.
147
PJ_DECL(pj_status_t) pjmedia_delay_buf_get(pjmedia_delay_buf *b,
151
* Reset delay buffer. This will clear the buffer's content. But keep
152
* the learning result.
154
* @param b The delay buffer.
156
* @return PJ_SUCCESS on success or the appropriate error.
158
PJ_DECL(pj_status_t) pjmedia_delay_buf_reset(pjmedia_delay_buf *b);
161
* Destroy delay buffer.
163
* @param b Delay buffer session.
165
* @return PJ_SUCCESS normally.
167
PJ_DECL(pj_status_t) pjmedia_delay_buf_destroy(pjmedia_delay_buf *b);
176
#endif /* __PJMEDIA_DELAYBUF_H__ */