Adaptive Delay Buffer

Adaptive delay buffer with high-quality time-scale modification. More...

Typedefs
typedef struct pjmedia_delay_buf	pjmedia_delay_buf

Enumerations
enum	pjmedia_delay_buf_flag { PJMEDIA_DELAY_BUF_SIMPLE_FIFO = 1 }

Functions
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)
pj_status_t	pjmedia_delay_buf_put (pjmedia_delay_buf *b, pj_int16_t frame[])
pj_status_t	pjmedia_delay_buf_get (pjmedia_delay_buf *b, pj_int16_t frame[])
pj_status_t	pjmedia_delay_buf_reset (pjmedia_delay_buf *b)
pj_status_t	pjmedia_delay_buf_destroy (pjmedia_delay_buf *b)

Detailed Description

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 PJMED_WSOLA.

The delay buffer is used in Sound Device Port, Media channel splitter/combiner, and Conference Bridge.

Typedef Documentation

pjmedia_delay_buf

typedef struct pjmedia_delay_buf pjmedia_delay_buf

Opaque declaration for delay buffer.

Enumeration Type Documentation

pjmedia_delay_buf_flag

enum pjmedia_delay_buf_flag

Delay buffer options.

Enumerator
PJMEDIA_DELAY_BUF_SIMPLE_FIFO	Use simple FIFO mechanism for the delay buffer, i.e. without WSOLA for expanding and shrinking audio samples.

Function Documentation

pjmedia_delay_buf_create()

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
	)

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.

Parameters

pool	Pool where the delay buffer will be allocated from.
name	Optional name for the buffer for log identification.
clock_rate	Number of samples processed per second.
samples_per_frame	Number of samples per frame.
channel_count	Number of channel per frame.
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.
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.
p_b	Pointer to receive the delay buffer instance.

Returns

PJ_SUCCESS if the delay buffer has been created successfully, otherwise the appropriate error will be returned.

pjmedia_delay_buf_put()

pj_status_t pjmedia_delay_buf_put	(	pjmedia_delay_buf *	b,
		pj_int16_t	frame[]
	)

Put one frame into the buffer.

Parameters

b	The delay buffer.
frame	Frame to be put into the buffer. This frame must have samples_per_frame length.

Returns

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.

pjmedia_delay_buf_get()

pj_status_t pjmedia_delay_buf_get	(	pjmedia_delay_buf *	b,
		pj_int16_t	frame[]
	)

Get one frame from the buffer.

Parameters

b	The delay buffer.
frame	Buffer to receive the frame from the delay buffer.

Returns

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.

pjmedia_delay_buf_reset()

pj_status_t pjmedia_delay_buf_reset

(

pjmedia_delay_buf *

b

)

Reset delay buffer. This will clear the buffer's content. But keep the learning result.

Parameters

b	The delay buffer.

Returns

PJ_SUCCESS on success or the appropriate error.

pjmedia_delay_buf_destroy()

pj_status_t pjmedia_delay_buf_destroy

(

pjmedia_delay_buf *

b

)

Destroy delay buffer.

Parameters

b	Delay buffer session.

Returns

PJ_SUCCESS normally.

References PJ_END_DECL.