Group PJMED_JBUF

group PJMED_JBUF

Adaptive de-jitter buffering implementation.

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.

Defines

PJMEDIA_JB_DEFAULT_INIT_DELAY

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

Typedefs

typedef struct pjmedia_jbuf pjmedia_jbuf

Opaque declaration for jitter buffer.

Enums

enum pjmedia_jb_frame_type

Types of frame returned by the jitter buffer.

Values:

PJMEDIA_JB_MISSING_FRAME = 0

No frame because it’s missing

PJMEDIA_JB_NORMAL_FRAME = 1

Normal frame is being returned

PJMEDIA_JB_ZERO_PREFETCH_FRAME = 2

Zero frame is being returned because JB is bufferring.

PJMEDIA_JB_ZERO_EMPTY_FRAME = 3

Zero frame is being returned because JB is empty.

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.

Values:

PJMEDIA_JB_DISCARD_NONE = 0

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.

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)

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.

Return

PJ_SUCCESS on success.

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.

pj_status_t pjmedia_jbuf_set_ptime(pjmedia_jbuf *jb, unsigned ptime)

Set the jitter buffer’s frame duration.

Return

PJ_SUCCESS on success.

Parameters
  • jb: The jitter buffer

  • ptime: Frame duration.

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.

Return

PJ_SUCCESS on success.

Parameters
  • jb: The jitter buffer

  • prefetch: The fixed delay value, in number of frames.

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.

Return

PJ_SUCCESS on success.

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.

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.

Return

PJ_SUCCESS on success.

Parameters
  • jb: The jitter buffer.

  • algo: The discard algorithm to be used.

pj_status_t pjmedia_jbuf_destroy(pjmedia_jbuf *jb)

Destroy jitter buffer instance.

Return

PJ_SUCCESS on success.

Parameters
  • jb: The jitter buffer.

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.

Return

PJ_SUCCESS on success.

Parameters
  • jb: The jitter buffer.

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

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.

See

pjmedia_jbuf_get_frame().

See

pjmedia_jbuf_get_frame().

Parameters
  • jb: The jitter buffer.

  • frame: Buffer to receive the payload from the jitter buffer.

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.

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.

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.

See

pjmedia_jbuf_get_frame().

See

pjmedia_jbuf_get_frame().

Parameters
  • jb: The jitter buffer.

  • frame: Buffer to receive the payload from the jitter buffer.

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.

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.

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.

See

pjmedia_jbuf_get_frame().

See

pjmedia_jbuf_get_frame().

Parameters
  • jb: The jitter buffer.

  • offset: Offset from the oldest frame to be peeked.

  • frame: Buffer to receive the payload from the jitter buffer.

Parameters
  • size: Pointer to receive frame size.

  • p_frm_type: Pointer to receive frame type.

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.

unsigned pjmedia_jbuf_remove_frame(pjmedia_jbuf *jb, unsigned frame_cnt)

Remove frames from the jitter buffer.

Return

The number of frame successfully removed.

Parameters
  • jb: The jitter buffer.

  • frame_cnt: Number of frames to be removed.

pj_bool_t pjmedia_jbuf_is_full(const pjmedia_jbuf *jb)

Check if the jitter buffer is full.

Return

PJ_TRUE if it is full.

Parameters
  • jb: The jitter buffer.

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

Get jitter buffer current state/settings.

Return

PJ_SUCCESS on success.

Parameters
  • jb: The jitter buffer.

  • state: Buffer to receive jitter buffer state.

struct pjmedia_jb_state
#include <jbuf.h>

This structure describes jitter buffer state.