| /* $Id$ */ |
| /* |
| * Copyright (C) 2008-2011 Teluu Inc. (http://www.teluu.com) |
| * Copyright (C) 2003-2008 Benny Prijono <benny@prijono.org> |
| * |
| * This program is free software; you can redistribute it and/or modify |
| * it under the terms of the GNU General Public License as published by |
| * the Free Software Foundation; either version 2 of the License, or |
| * (at your option) any later version. |
| * |
| * This program is distributed in the hope that it will be useful, |
| * but WITHOUT ANY WARRANTY; without even the implied warranty of |
| * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the |
| * GNU General Public License for more details. |
| * |
| * You should have received a copy of the GNU General Public License |
| * along with this program; if not, write to the Free Software |
| * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA |
| */ |
| |
| #ifndef __PJMEDIA_DELAYBUF_H__ |
| #define __PJMEDIA_DELAYBUF_H__ |
| |
| |
| /** |
| * @file delaybuf.h |
| * @brief Delay Buffer. |
| */ |
| |
| #include <pjmedia/types.h> |
| |
| /** |
| * @defgroup PJMED_DELAYBUF Adaptive Delay Buffer |
| * @ingroup PJMEDIA_FRAME_OP |
| * @brief Adaptive delay buffer with high-quality time-scale |
| * modification |
| * @{ |
| * |
| * This section describes PJMEDIA's implementation of delay buffer. |
| * Delay buffer works quite similarly like a fixed jitter buffer, that |
| * is it will delay the frame retrieval by some interval so that caller |
| * will get continuous frame from the buffer. This can be useful when |
| * the put() and get() operations are not evenly interleaved, for example |
| * when caller performs burst of put() operations and then followed by |
| * burst of get() operations. With using this delay buffer, the buffer |
| * will put the burst frames into a buffer so that get() operations |
| * will always get a frame from the buffer (assuming that the number of |
| * get() and put() are matched). |
| * |
| * The buffer is adaptive, that is it continuously learns the optimal delay |
| * to be applied to the audio flow at run-time. Once the optimal delay has |
| * been learned, the delay buffer will apply this delay to the audio flow, |
| * expanding or shrinking the audio samples as necessary when the actual |
| * audio samples in the buffer are too low or too high. It does this without |
| * distorting the audio quality of the audio, by using \a PJMED_WSOLA. |
| * |
| * The delay buffer is used in \ref PJMED_SND_PORT, \ref PJMEDIA_SPLITCOMB, |
| * and \ref PJMEDIA_CONF. |
| */ |
| |
| PJ_BEGIN_DECL |
| |
| /** Opaque declaration for delay buffer. */ |
| typedef struct pjmedia_delay_buf pjmedia_delay_buf; |
| |
| /** |
| * Delay buffer options. |
| */ |
| typedef enum pjmedia_delay_buf_flag |
| { |
| /** |
| * Use simple FIFO mechanism for the delay buffer, i.e. |
| * without WSOLA for expanding and shrinking audio samples. |
| */ |
| PJMEDIA_DELAY_BUF_SIMPLE_FIFO = 1 |
| |
| } pjmedia_delay_buf_flag; |
| |
| /** |
| * Create the delay buffer. Once the delay buffer is created, it will |
| * enter learning state unless the delay argument is specified, which |
| * in this case it will directly enter the running state. |
| * |
| * @param pool Pool where the delay buffer will be allocated |
| * from. |
| * @param name Optional name for the buffer for log |
| * identification. |
| * @param clock_rate Number of samples processed per second. |
| * @param samples_per_frame Number of samples per frame. |
| * @param channel_count Number of channel per frame. |
| * @param max_delay Maximum number of delay to be accommodated, |
| * in ms, if this value is negative or less than |
| * one frame time, default maximum delay used is |
| * 400 ms. |
| * @param options Options. If PJMEDIA_DELAY_BUF_SIMPLE_FIFO is |
| * specified, then a simple FIFO mechanism |
| * will be used instead of the adaptive |
| * implementation (which uses WSOLA to expand |
| * or shrink audio samples). |
| * See #pjmedia_delay_buf_flag for other options. |
| * @param p_b Pointer to receive the delay buffer instance. |
| * |
| * @return PJ_SUCCESS if the delay buffer has been |
| * created successfully, otherwise the appropriate |
| * error will be returned. |
| */ |
| PJ_DECL(pj_status_t) pjmedia_delay_buf_create(pj_pool_t *pool, |
| const char *name, |
| unsigned clock_rate, |
| unsigned samples_per_frame, |
| unsigned channel_count, |
| unsigned max_delay, |
| unsigned options, |
| pjmedia_delay_buf **p_b); |
| |
| /** |
| * Put one frame into the buffer. |
| * |
| * @param b The delay buffer. |
| * @param frame Frame to be put into the buffer. This frame |
| * must have samples_per_frame length. |
| * |
| * @return PJ_SUCCESS if frames can be put successfully. |
| * PJ_EPENDING if the buffer is still at learning |
| * state. PJ_ETOOMANY if the number of frames |
| * will exceed maximum delay level, which in this |
| * case the new frame will overwrite the oldest |
| * frame in the buffer. |
| */ |
| PJ_DECL(pj_status_t) pjmedia_delay_buf_put(pjmedia_delay_buf *b, |
| pj_int16_t frame[]); |
| |
| /** |
| * Get one frame from the buffer. |
| * |
| * @param b The delay buffer. |
| * @param frame Buffer to receive the frame from the delay |
| * buffer. |
| * |
| * @return PJ_SUCCESS if frame has been copied successfully. |
| * PJ_EPENDING if no frame is available, either |
| * because the buffer is still at learning state or |
| * no buffer is available during running state. |
| * On non-successful return, the frame will be |
| * filled with zeroes. |
| */ |
| PJ_DECL(pj_status_t) pjmedia_delay_buf_get(pjmedia_delay_buf *b, |
| pj_int16_t frame[]); |
| |
| /** |
| * Reset delay buffer. This will clear the buffer's content. But keep |
| * the learning result. |
| * |
| * @param b The delay buffer. |
| * |
| * @return PJ_SUCCESS on success or the appropriate error. |
| */ |
| PJ_DECL(pj_status_t) pjmedia_delay_buf_reset(pjmedia_delay_buf *b); |
| |
| /** |
| * Destroy delay buffer. |
| * |
| * @param b Delay buffer session. |
| * |
| * @return PJ_SUCCESS normally. |
| */ |
| PJ_DECL(pj_status_t) pjmedia_delay_buf_destroy(pjmedia_delay_buf *b); |
| |
| |
| PJ_END_DECL |
| |
| /** |
| * @} |
| */ |
| |
| #endif /* __PJMEDIA_DELAYBUF_H__ */ |