Speex  1.2~beta4
Classes | Defines | Typedefs | Functions
JitterBuffer: Adaptive jitter buffer

Classes

struct  _JitterBufferPacket

Defines

#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

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


Define Documentation

#define JITTER_BUFFER_BAD_ARGUMENT   -2

Invalid argument

Get the amount of available packets currently buffered

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

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

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

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

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)

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

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:
jitterJitter buffer state
requestioctl-type request (one of the JITTER_BUFFER_* macros)
ptrData exchanged to-from function
Returns:
0 if no error, -1 if request in unknown
void jitter_buffer_destroy ( JitterBuffer jitter)

Destroys jitter buffer

Parameters:
jitterJitter 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:
jitterJitter buffer state
packetReturned packet
desired_spanNumber of samples (or units) we wish to get from the buffer (no guarantee)
current_timestampTimestamp 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:
jitterJitter buffer state
packetReturned packet

Get pointer timestamp of jitter buffer

Parameters:
jitterJitter buffer state
JitterBuffer* jitter_buffer_init ( int  step_size)

Initialises jitter buffer

Parameters:
step_sizeStarting 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:
jitterJitter buffer state
packetIncoming 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:
jitterJitter buffer state
remAmount of data buffered by the application (timestamp units)
void jitter_buffer_reset ( JitterBuffer jitter)

Restores jitter buffer to its original state

Parameters:
jitterJitter buffer state
void jitter_buffer_tick ( JitterBuffer jitter)

Advance by one tick

Parameters:
jitterJitter buffer state