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