Adaptive jitter buffer
[Audio Manipulation Algorithms]

---

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.

Data Structures
struct	pjmedia_jb_state
Defines
#define	PJMEDIA_JB_DEFAULT_INIT_DELAY   15
Typedefs
typedef enum pjmedia_jb_frame_type	pjmedia_jb_frame_type
typedef struct pjmedia_jb_state	pjmedia_jb_state
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 }
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_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_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_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)
pj_status_t	pjmedia_jbuf_get_state (pjmedia_jbuf *jb, pjmedia_jb_state *state)

---

Define Documentation

#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

typedef enum pjmedia_jb_frame_type pjmedia_jb_frame_type

See also:

pjmedia_jb_frame_type.

typedef struct pjmedia_jb_state pjmedia_jb_state

See also:

pjmedia_jb_state

typedef struct pjmedia_jbuf pjmedia_jbuf

Opaque declaration for jitter buffer.

---

Enumeration Type Documentation

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.

---

Function Documentation

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.

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.

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.

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.

pj_status_t pjmedia_jbuf_destroy

(

pjmedia_jbuf *

jb

)

Destroy jitter buffer instance.

Parameters:

jb

The jitter buffer.

Returns:

PJ_SUCCESS on success.

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.

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.

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.

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.

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

pj_status_t pjmedia_jbuf_get_state	(	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.