voice-gateway-service/pjproject/pjmedia/include/pjmedia/delaybuf.h

/* 
 * 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__ */