BLOG | DOCUMENTATION | TRAC

Home --> Documentations --> PJMEDIA Reference

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

#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 struct pjmedia_jbuf pjmedia_jbuf

Opaque declaration for jitter buffer.

Enumeration Type Documentation

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.

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

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
poolThe pool to allocate memory.
nameName to identify the jitter buffer for logging purpose.
frame_sizeThe 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_countMaximum 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.
ptimeIndication of frame duration, used to calculate the interval between jitter recalculation.
p_jbPointer 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
jbThe jitter buffer
prefetchThe 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
jbThe jitter buffer.
prefetchThe 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_prefetchThe minimum delay that must be applied to each incoming packets, in number of frames.
max_prefetchThe maximum allowable value for prefetch delay, in number of frames.
Returns
PJ_SUCCESS on success.
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
jbThe jitter buffer.
algoThe discard algorithm to be used.
Returns
PJ_SUCCESS on success.
pj_status_t pjmedia_jbuf_destroy ( pjmedia_jbuf jb)

Destroy jitter buffer instance.

Parameters
jbThe 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
jbThe 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
jbThe jitter buffer.
framePointer to frame buffer to be stored in the jitter buffer.
sizeThe frame size.
frame_seqThe 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
jbThe jitter buffer.
framePointer to frame buffer to be stored in the jitter buffer.
sizeThe frame size.
bit_infoBit 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_seqThe frame sequence number.
discardedFlag whether the frame is discarded by jitter buffer.
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
jbThe jitter buffer.
framePointer to frame buffer to be stored in the jitter buffer.
sizeThe frame size.
bit_infoBit 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_seqThe frame sequence number.
frame_tsThe frame timestamp.
discardedFlag 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
jbThe jitter buffer.
frameBuffer 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_typePointer 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
jbThe jitter buffer.
frameBuffer to receive the payload from the jitter buffer.
See also
pjmedia_jbuf_get_frame().
Parameters
sizePointer to receive frame size.
p_frm_typePointer to receive frame type.
See also
pjmedia_jbuf_get_frame().
Parameters
bit_infoBit 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.
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
jbThe jitter buffer.
frameBuffer to receive the payload from the jitter buffer.
See also
pjmedia_jbuf_get_frame().
Parameters
sizePointer to receive frame size.
p_frm_typePointer to receive frame type.
See also
pjmedia_jbuf_get_frame().
Parameters
bit_infoBit 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.
tsFrame timestamp.
seqFrame sequence number.
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
jbThe jitter buffer.
offsetOffset from the oldest frame to be peeked.
frameBuffer to receive the payload from the jitter buffer.
See also
pjmedia_jbuf_get_frame().
Parameters
sizePointer to receive frame size.
p_frm_typePointer to receive frame type.
See also
pjmedia_jbuf_get_frame().
Parameters
bit_infoBit 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.
tsFrame timestamp.
seqFrame sequence number.
unsigned pjmedia_jbuf_remove_frame ( pjmedia_jbuf jb,
unsigned  frame_cnt 
)

Remove frames from the jitter buffer.

Parameters
jbThe jitter buffer.
frame_cntNumber of frames to be removed.
Returns
The number of frame successfully removed.
pj_bool_t pjmedia_jbuf_is_full ( const pjmedia_jbuf jb)

Check if the jitter buffer is full.

Parameters
jbThe jitter buffer.
Returns
PJ_TRUE if it is full.
pj_status_t pjmedia_jbuf_get_state ( const pjmedia_jbuf jb,
pjmedia_jb_state state 
)

Get jitter buffer current state/settings.

Parameters
jbThe jitter buffer.
stateBuffer to receive jitter buffer state.
Returns
PJ_SUCCESS on success.

 


PJMEDIA small footprint Open Source media stack
Copyright (C) 2006-2008 Teluu Inc.