# 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_SET_MAX_LATE_RATE 10
#define | JITTER_BUFFER_SET_LATE_COST 12

## 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)

## 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

#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_DELAY_STEP 7

#define JITTER_BUFFER_GET_DESTROY_CALLBACK 5

#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

Destroy jitter buffer

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

Get one packet from the jitter buffer

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

Get pointer timestamp of jitter buffer

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

Initialise jitter buffer

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

Put one packet into the jitter buffer

Parameters:

  | jitter | Jitter buffer state
  | packet | Incoming packet

Put one packet into the jitter buffer

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

Reset jitter buffer

void jitter_buffer_tick | ( | JitterBuffer * | jitter | ) |

Advance by one tick

Parameters:

  | jitter | Jitter buffer state