JitterBuffer: Adaptive jitter buffer

Classes
struct	_JitterBufferPacket

Macros
#define	JITTER_BUFFER_OK   0
#define	JITTER_BUFFER_MISSING   1
#define	JITTER_BUFFER_INSERTION   2
#define	JITTER_BUFFER_INTERNAL_ERROR   -1
#define	JITTER_BUFFER_BAD_ARGUMENT   -2
#define	JITTER_BUFFER_SET_MARGIN   0
#define	JITTER_BUFFER_GET_MARGIN   1
#define	JITTER_BUFFER_GET_AVAILABLE_COUNT   3
#define	JITTER_BUFFER_GET_AVALIABLE_COUNT   3
#define	JITTER_BUFFER_SET_DESTROY_CALLBACK   4
#define	JITTER_BUFFER_GET_DESTROY_CALLBACK   5
#define	JITTER_BUFFER_SET_DELAY_STEP   6
#define	JITTER_BUFFER_GET_DELAY_STEP   7
#define	JITTER_BUFFER_SET_CONCEALMENT_SIZE   8
#define	JITTER_BUFFER_GET_CONCEALMENT_SIZE   9
#define	JITTER_BUFFER_SET_MAX_LATE_RATE   10
#define	JITTER_BUFFER_GET_MAX_LATE_RATE   11
#define	JITTER_BUFFER_SET_LATE_COST   12
#define	JITTER_BUFFER_GET_LATE_COST   13

Typedefs
typedef struct JitterBuffer_	JitterBuffer
typedef struct _JitterBufferPacket	JitterBufferPacket

Functions
JitterBuffer *	jitter_buffer_init (int step_size)
void	jitter_buffer_reset (JitterBuffer *jitter)
void	jitter_buffer_destroy (JitterBuffer *jitter)
void	jitter_buffer_put (JitterBuffer *jitter, const JitterBufferPacket *packet)
int	jitter_buffer_get (JitterBuffer *jitter, JitterBufferPacket *packet, spx_int32_t desired_span, spx_int32_t *start_offset)
int	jitter_buffer_get_another (JitterBuffer *jitter, JitterBufferPacket *packet)
int	jitter_buffer_get_pointer_timestamp (JitterBuffer *jitter)
void	jitter_buffer_tick (JitterBuffer *jitter)
void	jitter_buffer_remaining_span (JitterBuffer *jitter, spx_uint32_t rem)
int	jitter_buffer_ctl (JitterBuffer *jitter, int request, void *ptr)
int	jitter_buffer_update_delay (JitterBuffer *jitter, JitterBufferPacket *packet, spx_int32_t *start_offset)

Detailed Description

This is the jitter buffer that reorders UDP/RTP packets and adjusts the buffer size to maintain good quality and low latency.

Macro Definition Documentation

#define JITTER_BUFFER_BAD_ARGUMENT   -2

Invalid argument

#define JITTER_BUFFER_GET_AVAILABLE_COUNT   3

Get the amount of available packets currently buffered

#define JITTER_BUFFER_GET_AVALIABLE_COUNT   3

Included because of an early misspelling (will remove in next release)

#define JITTER_BUFFER_GET_MARGIN   1

Get minimum amount of extra buffering required (margin)

#define JITTER_BUFFER_INSERTION   2

A "fake" packet is meant to be inserted here to increase buffering

#define JITTER_BUFFER_INTERNAL_ERROR   -1

There was an error in the jitter buffer

#define JITTER_BUFFER_MISSING   1

Packet is lost or is late

#define JITTER_BUFFER_OK   0

Packet has been retrieved

#define JITTER_BUFFER_SET_CONCEALMENT_SIZE   8

Tell the jitter buffer to only do concealment in multiples of the size parameter provided

#define JITTER_BUFFER_SET_DELAY_STEP   6

Tell the jitter buffer to only adjust the delay in multiples of the step parameter provided

#define JITTER_BUFFER_SET_DESTROY_CALLBACK   4

Assign a function to destroy unused packet. When setting that, the jitter buffer no longer copies packet data.

#define JITTER_BUFFER_SET_LATE_COST   12

Equivalent cost of one percent late packet in timestamp units

#define JITTER_BUFFER_SET_MARGIN   0

Set minimum amount of extra buffering required (margin)

#define JITTER_BUFFER_SET_MAX_LATE_RATE   10

Absolute max amount of loss that can be tolerated regardless of the delay. Typical loss should be half of that or less.

Typedef Documentation

typedef struct JitterBuffer_ JitterBuffer

Generic adaptive jitter buffer state

typedef struct _JitterBufferPacket JitterBufferPacket

Definition of an incoming packet

Function Documentation

int jitter_buffer_ctl	(	JitterBuffer *	jitter,
		int	request,
		void *	ptr
	)

Used like the ioctl function to control the jitter buffer parameters

Parameters

jitter	Jitter buffer state
request	ioctl-type request (one of the JITTER_BUFFER_* macros)
ptr	Data exchanged to-from function

Returns

0 if no error, -1 if request in unknown

void jitter_buffer_destroy

(

JitterBuffer *

jitter

)

Destroys jitter buffer

Parameters

jitter

Jitter buffer state

int jitter_buffer_get	(	JitterBuffer *	jitter,
		JitterBufferPacket *	packet,
		spx_int32_t	desired_span,
		spx_int32_t *	start_offset
	)

Get one packet from the jitter buffer

Parameters

jitter	Jitter buffer state
packet	Returned packet
desired_span	Number of samples (or units) we wish to get from the buffer (no guarantee)
current_timestamp	Timestamp for the returned packet

int jitter_buffer_get_another	(	JitterBuffer *	jitter,
		JitterBufferPacket *	packet
	)

Used right after jitter_buffer_get() to obtain another packet that would have the same timestamp. This is mainly useful for media where a single "frame" can be split into several packets.

Parameters

jitter	Jitter buffer state
packet	Returned packet

int jitter_buffer_get_pointer_timestamp

(

JitterBuffer *

jitter

)

Get pointer timestamp of jitter buffer

Parameters

jitter

Jitter buffer state

JitterBuffer* jitter_buffer_init

(

int

step_size

)

Initialises jitter buffer

Parameters

step_size

Starting value for the size of concleanment packets and delay adjustment steps. Can be changed at any time using JITTER_BUFFER_SET_DELAY_STEP and JITTER_BUFFER_GET_CONCEALMENT_SIZE.

Returns

Newly created jitter buffer state

void jitter_buffer_put	(	JitterBuffer *	jitter,
		const JitterBufferPacket *	packet
	)

Put one packet into the jitter buffer

Parameters

jitter	Jitter buffer state
packet	Incoming packet

void jitter_buffer_remaining_span	(	JitterBuffer *	jitter,
		spx_uint32_t	rem
	)

Telling the jitter buffer about the remaining data in the application buffer

Parameters

jitter	Jitter buffer state
rem	Amount of data buffered by the application (timestamp units)

void jitter_buffer_reset

(

JitterBuffer *

jitter

)

Restores jitter buffer to its original state

Parameters

jitter

Jitter buffer state

void jitter_buffer_tick

(

JitterBuffer *

jitter

)

Advance by one tick

Parameters

jitter

Jitter buffer state