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:

enumerator PJMEDIA_JB_MISSING_FRAME

No frame because it’s missing

enumerator PJMEDIA_JB_NORMAL_FRAME

Normal frame is being returned

enumerator PJMEDIA_JB_ZERO_PREFETCH_FRAME

Zero frame is being returned because JB is bufferring.

enumerator PJMEDIA_JB_ZERO_EMPTY_FRAME

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:

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.

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

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

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

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.

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.

  • size – Pointer to receive frame size.

  • p_frm_type – Pointer to receive frame type.

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

struct pjmedia_jb_state
#include <jbuf.h>

This structure describes jitter buffer state.