Adaptive jitter buffer

Adaptive de-jitter buffering implementation. More...

Data Structures
struct	pjmedia_jb_state

Macros
#define	PJMEDIA_JB_DEFAULT_INIT_DELAY   15

Typedefs
typedef struct pjmedia_jbuf	pjmedia_jbuf

Enumerations
enum	pjmedia_jb_frame_type {   PJMEDIA_JB_MISSING_FRAME = 0 ,   PJMEDIA_JB_NORMAL_FRAME = 1 ,   PJMEDIA_JB_ZERO_PREFETCH_FRAME = 2 ,   PJMEDIA_JB_ZERO_EMPTY_FRAME = 3 }
enum	pjmedia_jb_discard_algo {   PJMEDIA_JB_DISCARD_NONE = 0 ,   PJMEDIA_JB_DISCARD_STATIC ,   PJMEDIA_JB_DISCARD_PROGRESSIVE }

Functions
pj_status_t	pjmedia_jbuf_create (pj_pool_t *pool, const pj_str_t *name, unsigned frame_size, unsigned ptime, unsigned max_count, pjmedia_jbuf **p_jb)
pj_status_t	pjmedia_jbuf_set_ptime (pjmedia_jbuf *jb, unsigned ptime)
pj_status_t	pjmedia_jbuf_set_fixed (pjmedia_jbuf *jb, unsigned prefetch)
pj_status_t	pjmedia_jbuf_set_adaptive (pjmedia_jbuf *jb, unsigned prefetch, unsigned min_prefetch, unsigned max_prefetch)
pj_status_t	pjmedia_jbuf_set_discard (pjmedia_jbuf *jb, pjmedia_jb_discard_algo algo)
pj_status_t	pjmedia_jbuf_destroy (pjmedia_jbuf *jb)
pj_status_t	pjmedia_jbuf_reset (pjmedia_jbuf *jb)
void	pjmedia_jbuf_put_frame (pjmedia_jbuf *jb, const void *frame, pj_size_t size, int frame_seq)
void	pjmedia_jbuf_put_frame2 (pjmedia_jbuf *jb, const void *frame, pj_size_t size, pj_uint32_t bit_info, int frame_seq, pj_bool_t *discarded)
void	pjmedia_jbuf_put_frame3 (pjmedia_jbuf *jb, const void *frame, pj_size_t size, pj_uint32_t bit_info, int frame_seq, pj_uint32_t frame_ts, pj_bool_t *discarded)
void	pjmedia_jbuf_get_frame (pjmedia_jbuf *jb, void *frame, char *p_frm_type)
void	pjmedia_jbuf_get_frame2 (pjmedia_jbuf *jb, void *frame, pj_size_t *size, char *p_frm_type, pj_uint32_t *bit_info)
void	pjmedia_jbuf_get_frame3 (pjmedia_jbuf *jb, void *frame, pj_size_t *size, char *p_frm_type, pj_uint32_t *bit_info, pj_uint32_t *ts, int *seq)
void	pjmedia_jbuf_peek_frame (pjmedia_jbuf *jb, unsigned offset, const void **frame, pj_size_t *size, char *p_frm_type, pj_uint32_t *bit_info, pj_uint32_t *ts, int *seq)
unsigned	pjmedia_jbuf_remove_frame (pjmedia_jbuf *jb, unsigned frame_cnt)
pj_bool_t	pjmedia_jbuf_is_full (const pjmedia_jbuf *jb)
pj_status_t	pjmedia_jbuf_get_state (const pjmedia_jbuf *jb, pjmedia_jb_state *state)

Detailed Description

This section describes PJMEDIA's implementation of de-jitter buffer. The de-jitter buffer may be set to operate in adaptive mode or fixed delay mode.

Macro Definition Documentation

PJMEDIA_JB_DEFAULT_INIT_DELAY

#define PJMEDIA_JB_DEFAULT_INIT_DELAY   15

The constant PJMEDIA_JB_DEFAULT_INIT_DELAY specifies default jitter buffer prefetch count during jitter buffer creation.

Typedef Documentation

pjmedia_jbuf

typedef struct pjmedia_jbuf pjmedia_jbuf

Opaque declaration for jitter buffer.

Enumeration Type Documentation

pjmedia_jb_frame_type

enum pjmedia_jb_frame_type

Types of frame returned by the jitter buffer.

Enumerator
PJMEDIA_JB_MISSING_FRAME	No frame because it's missing
PJMEDIA_JB_NORMAL_FRAME	Normal frame is being returned
PJMEDIA_JB_ZERO_PREFETCH_FRAME	Zero frame is being returned because JB is bufferring.
PJMEDIA_JB_ZERO_EMPTY_FRAME	Zero frame is being returned because JB is empty.

pjmedia_jb_discard_algo

enum pjmedia_jb_discard_algo

Enumeration of jitter buffer discard algorithm. The jitter buffer continuously calculates the jitter level to get the optimum latency at any time and in order to adjust the latency, the jitter buffer may need to discard some frames.

Enumerator
PJMEDIA_JB_DISCARD_NONE	Jitter buffer should not discard any frame, except when the jitter buffer is full and a new frame arrives, one frame will be discarded to make space for the new frame.
PJMEDIA_JB_DISCARD_STATIC	Only discard one frame in at least 200ms when the latency is considered much higher than it should be. When the jitter buffer is full and a new frame arrives, one frame will be discarded to make space for the new frame.
PJMEDIA_JB_DISCARD_PROGRESSIVE	The discard rate is dynamically calculated based on actual parameters such as jitter level and latency. When the jitter buffer is full and a new frame arrives, one frame will be discarded to make space for the new frame.

Function Documentation

pjmedia_jbuf_create()

pj_status_t pjmedia_jbuf_create	(	pj_pool_t *	pool,
		const pj_str_t *	name,
		unsigned	frame_size,
		unsigned	ptime,
		unsigned	max_count,
		pjmedia_jbuf **	p_jb
	)

Create an adaptive jitter buffer according to the specification. If application wants to have a fixed jitter buffer, it may call pjmedia_jbuf_set_fixed() after the jitter buffer is created. Also if application wants to alter the discard algorithm, which the default PJMEDIA_JB_DISCARD_PROGRESSIVE, it may call pjmedia_jbuf_set_discard().

This function may allocate large chunk of memory to keep the frames in the buffer.

Parameters

pool	The pool to allocate memory.
name	Name to identify the jitter buffer for logging purpose.
frame_size	The size of each frame that will be kept in the jitter buffer, in bytes. This should correspond to the minimum frame size supported by the codec. For example, a 10ms frame (80 bytes) would be recommended for G.711 codec.
max_count	Maximum number of frames that can be kept in the jitter buffer. This effectively means the maximum delay that may be introduced by this jitter buffer.
ptime	Indication of frame duration, used to calculate the interval between jitter recalculation.
p_jb	Pointer to receive jitter buffer instance.

Returns

PJ_SUCCESS on success.

pjmedia_jbuf_set_ptime()

pj_status_t pjmedia_jbuf_set_ptime	(	pjmedia_jbuf *	jb,
		unsigned	ptime
	)

Set the jitter buffer's frame duration.

Parameters

jb	The jitter buffer
ptime	Frame duration.

Returns

PJ_SUCCESS on success.

pjmedia_jbuf_set_fixed()

pj_status_t pjmedia_jbuf_set_fixed	(	pjmedia_jbuf *	jb,
		unsigned	prefetch
	)

Set the jitter buffer to fixed delay mode. The default behavior is to adapt the delay with actual packet delay.

Parameters

jb	The jitter buffer
prefetch	The fixed delay value, in number of frames.

Returns

PJ_SUCCESS on success.

pjmedia_jbuf_set_adaptive()

pj_status_t pjmedia_jbuf_set_adaptive	(	pjmedia_jbuf *	jb,
		unsigned	prefetch,
		unsigned	min_prefetch,
		unsigned	max_prefetch
	)

Set the jitter buffer to adaptive mode.

Parameters

jb	The jitter buffer.
prefetch	The initial prefetch value to be applied to the jitter buffer. Setting this to other than 0 will activate prefetch buffering, a jitter buffer feature that each time it gets empty, it won't return a normal frame until its size reaches the number specified here.
min_prefetch	The minimum delay that must be applied to each incoming packets, in number of frames.
max_prefetch	The maximum allowable value for prefetch delay, in number of frames.

Returns

PJ_SUCCESS on success.

pjmedia_jbuf_set_discard()

pj_status_t pjmedia_jbuf_set_discard	(	pjmedia_jbuf *	jb,
		pjmedia_jb_discard_algo	algo
	)

Set the jitter buffer discard algorithm. The default discard algorithm, set in jitter buffer creation, is PJMEDIA_JB_DISCARD_PROGRESSIVE.

Parameters

jb	The jitter buffer.
algo	The discard algorithm to be used.

Returns

PJ_SUCCESS on success.

pjmedia_jbuf_destroy()

pj_status_t pjmedia_jbuf_destroy

(

pjmedia_jbuf *

jb

)

Destroy jitter buffer instance.

Parameters

jb	The jitter buffer.

Returns

PJ_SUCCESS on success.

pjmedia_jbuf_reset()

pj_status_t pjmedia_jbuf_reset

(

pjmedia_jbuf *

jb

)

Restart jitter. This function flushes all packets in the buffer and reset the internal sequence number.

Parameters

jb	The jitter buffer.

Returns

PJ_SUCCESS on success.

pjmedia_jbuf_put_frame()

void pjmedia_jbuf_put_frame	(	pjmedia_jbuf *	jb,
		const void *	frame,
		pj_size_t	size,
		int	frame_seq
	)

Put a frame to the jitter buffer. If the frame can be accepted (based on the sequence number), the jitter buffer will copy the frame and put it in the appropriate position in the buffer.

Application MUST manage it's own synchronization when multiple threads are accessing the jitter buffer at the same time.

Parameters

jb	The jitter buffer.
frame	Pointer to frame buffer to be stored in the jitter buffer.
size	The frame size.
frame_seq	The frame sequence number.

pjmedia_jbuf_put_frame2()

void pjmedia_jbuf_put_frame2	(	pjmedia_jbuf *	jb,
		const void *	frame,
		pj_size_t	size,
		pj_uint32_t	bit_info,
		int	frame_seq,
		pj_bool_t *	discarded
	)

Put a frame to the jitter buffer. If the frame can be accepted (based on the sequence number), the jitter buffer will copy the frame and put it in the appropriate position in the buffer.

Application MUST manage it's own synchronization when multiple threads are accessing the jitter buffer at the same time.

Parameters

jb	The jitter buffer.
frame	Pointer to frame buffer to be stored in the jitter buffer.
size	The frame size.
bit_info	Bit precise info of the frame, e.g: a frame may not exactly start and end at the octet boundary, so this field may be used for specifying start & end bit offset.
frame_seq	The frame sequence number.
discarded	Flag whether the frame is discarded by jitter buffer.

pjmedia_jbuf_put_frame3()

void pjmedia_jbuf_put_frame3	(	pjmedia_jbuf *	jb,
		const void *	frame,
		pj_size_t	size,
		pj_uint32_t	bit_info,
		int	frame_seq,
		pj_uint32_t	frame_ts,
		pj_bool_t *	discarded
	)

Put a frame to the jitter buffer. If the frame can be accepted (based on the sequence number), the jitter buffer will copy the frame and put it in the appropriate position in the buffer.

Application MUST manage it's own synchronization when multiple threads are accessing the jitter buffer at the same time.

Parameters

jb	The jitter buffer.
frame	Pointer to frame buffer to be stored in the jitter buffer.
size	The frame size.
bit_info	Bit precise info of the frame, e.g: a frame may not exactly start and end at the octet boundary, so this field may be used for specifying start & end bit offset.
frame_seq	The frame sequence number.
frame_ts	The frame timestamp.
discarded	Flag whether the frame is discarded by jitter buffer.

pjmedia_jbuf_get_frame()

void pjmedia_jbuf_get_frame	(	pjmedia_jbuf *	jb,
		void *	frame,
		char *	p_frm_type
	)

Get a frame from the jitter buffer. The jitter buffer will return the oldest frame from it's buffer, when it is available.

Application MUST manage it's own synchronization when multiple threads are accessing the jitter buffer at the same time.

Parameters

jb	The jitter buffer.
frame	Buffer to receive the payload from the jitter buffer. Application MUST make sure that the buffer has appropriate size (i.e. not less than the frame size, as specified when the jitter buffer was created). The jitter buffer only copied a frame to this buffer when the frame type returned by this function is PJMEDIA_JB_NORMAL_FRAME.
p_frm_type	Pointer to receive frame type. If jitter buffer is currently empty or bufferring, the frame type will be set to PJMEDIA_JB_ZERO_FRAME, and no frame will be copied. If the jitter buffer detects that frame is missing with current sequence number, the frame type will be set to PJMEDIA_JB_MISSING_FRAME, and no frame will be copied. If there is a frame, the jitter buffer will copy the frame to the buffer, and frame type will be set to PJMEDIA_JB_NORMAL_FRAME.

pjmedia_jbuf_get_frame2()

void pjmedia_jbuf_get_frame2	(	pjmedia_jbuf *	jb,
		void *	frame,
		pj_size_t *	size,
		char *	p_frm_type,
		pj_uint32_t *	bit_info
	)

Get a frame from the jitter buffer. The jitter buffer will return the oldest frame from it's buffer, when it is available.

Parameters

jb	The jitter buffer.
frame	Buffer to receive the payload from the jitter buffer.

See also

pjmedia_jbuf_get_frame().

Parameters

size	On input, it points to maximum buffer length. On output, it will be filled with received frame size.
p_frm_type	Pointer to receive frame type.

See also

pjmedia_jbuf_get_frame().

Parameters

bit_info

Bit precise info of the frame, e.g: a frame may not exactly start and end at the octet boundary, so this field may be used for specifying start & end bit offset.

pjmedia_jbuf_get_frame3()

void pjmedia_jbuf_get_frame3	(	pjmedia_jbuf *	jb,
		void *	frame,
		pj_size_t *	size,
		char *	p_frm_type,
		pj_uint32_t *	bit_info,
		pj_uint32_t *	ts,
		int *	seq
	)

Get a frame from the jitter buffer. The jitter buffer will return the oldest frame from it's buffer, when it is available.

Parameters

jb	The jitter buffer.
frame	Buffer to receive the payload from the jitter buffer.

See also

pjmedia_jbuf_get_frame().

Parameters

size	On input, it points to maximum buffer length. On output, it will be filled with received frame size.
p_frm_type	Pointer to receive frame type.

See also

pjmedia_jbuf_get_frame().

Parameters

bit_info	Bit precise info of the frame, e.g: a frame may not exactly start and end at the octet boundary, so this field may be used for specifying start & end bit offset.
ts	Frame timestamp.
seq	Frame sequence number.

pjmedia_jbuf_peek_frame()

void pjmedia_jbuf_peek_frame	(	pjmedia_jbuf *	jb,
		unsigned	offset,
		const void **	frame,
		pj_size_t *	size,
		char *	p_frm_type,
		pj_uint32_t *	bit_info,
		pj_uint32_t *	ts,
		int *	seq
	)

Peek a frame from the jitter buffer. The jitter buffer state will not be modified.

Parameters

jb	The jitter buffer.
offset	Offset from the oldest frame to be peeked.
frame	Buffer to receive the payload from the jitter buffer.

See also

pjmedia_jbuf_get_frame().

Parameters

size	Pointer to receive frame size.
p_frm_type	Pointer to receive frame type.

See also

pjmedia_jbuf_get_frame().

Parameters

bit_info	Bit precise info of the frame, e.g: a frame may not exactly start and end at the octet boundary, so this field may be used for specifying start & end bit offset.
ts	Frame timestamp.
seq	Frame sequence number.

pjmedia_jbuf_remove_frame()

unsigned pjmedia_jbuf_remove_frame	(	pjmedia_jbuf *	jb,
		unsigned	frame_cnt
	)

Remove frames from the jitter buffer.

Parameters

jb	The jitter buffer.
frame_cnt	Number of frames to be removed.

Returns

The number of frame successfully removed.

pjmedia_jbuf_is_full()

pj_bool_t pjmedia_jbuf_is_full

(

const pjmedia_jbuf *

jb

)

Check if the jitter buffer is full.

Parameters

jb	The jitter buffer.

Returns

PJ_TRUE if it is full.

pjmedia_jbuf_get_state()

pj_status_t pjmedia_jbuf_get_state	(	const pjmedia_jbuf *	jb,
		pjmedia_jb_state *	state
	)

Get jitter buffer current state/settings.

Parameters

jb	The jitter buffer.
state	Buffer to receive jitter buffer state.

Returns

PJ_SUCCESS on success.

References PJ_END_DECL.