334 lines
12 KiB
C
334 lines
12 KiB
C
/* File from: http://cms.speakup.nl/tech/opensource/jitterbuffer/verslag-20051209.pdf/ */
|
|
|
|
/*******************************************************
|
|
* jitterbuffer:
|
|
* an application-independent jitterbuffer, which tries
|
|
* to achieve the maximum user perception during a call.
|
|
* For more information look at:
|
|
* http://www.speakup.nl/opensource/jitterbuffer/
|
|
*
|
|
* Copyright on this file is held by:
|
|
* - Jesse Kaijen <jesse@speakup.nl>
|
|
* - SpeakUp <info@speakup.nl>
|
|
*
|
|
* Contributors:
|
|
* Jesse Kaijen <jesse@speakup.nl>
|
|
*
|
|
* Version: 1.1
|
|
*
|
|
* Changelog:
|
|
* 1.0 => 1.1 (2006-03-24) (thanks to Micheal Jerris, freeswitch.org)
|
|
* - added MSVC 2005 project files
|
|
* - added JB_NOJB as return value
|
|
*
|
|
*
|
|
* This program is free software, distributed under the terms of:
|
|
* - the GNU Lesser (Library) General Public License
|
|
* - the Mozilla Public License
|
|
*
|
|
* if you are interested in an different licence type, please contact us.
|
|
*
|
|
* How to use the jitterbuffer, please look at the comments
|
|
* in the headerfile.
|
|
*
|
|
* Further details on specific implementations,
|
|
* please look at the comments in the code file.
|
|
*/
|
|
|
|
#ifndef TINYDAV_JITTERBUFFER_H_
|
|
#define TINYDAV_JITTERBUFFER_H_
|
|
|
|
#include "tinydav_config.h"
|
|
|
|
#if !(HAVE_SPEEX_DSP && HAVE_SPEEX_JB)
|
|
|
|
TDAV_BEGIN_DECLS
|
|
|
|
/***********
|
|
* The header file consists of four parts.
|
|
* - configuration constants, structs and parameter definitions
|
|
* - functions
|
|
* - How to use the jitterbuffer and
|
|
* which responsibilities do YOU have
|
|
* - debug messages explained
|
|
*/
|
|
|
|
|
|
// configuration constants
|
|
/* Number of historical timestamps to use in calculating jitter and jitterbuffer size */
|
|
#ifndef JB_HISTORY_SIZE
|
|
# define JB_HISTORY_SIZE 500
|
|
#endif
|
|
|
|
/* minimum jitterbuffer size, disabled if 0 */
|
|
#define JB_MIN_SIZE 0
|
|
/* maximum jitterbuffer size, disabled if 0 */
|
|
#define JB_MAX_SIZE 0
|
|
/* maximum successive interpolating frames, disabled if 0 */
|
|
#define JB_MAX_SUCCESSIVE_INTERP 0
|
|
/* amount of extra delay allowed before shrinking */
|
|
#define JB_ALLOW_EXTRA_DELAY 30
|
|
/* ms between growing */
|
|
#define JB_WAIT_GROW 60
|
|
/* ms between shrinking */
|
|
#define JB_WAIT_SHRINK 250
|
|
/* ms that the JB max may be off */
|
|
#define JB_MAX_DIFF 6000 //in a RTP stream the max_diff may be 3000 packets (most packets are 20ms)
|
|
|
|
//structs
|
|
typedef struct jb_info {
|
|
long frames_received; /* Number of frames received by the jitterbuffer */
|
|
long frames_late; /* Number of frames that were late */
|
|
long frames_lost; /* Number of frames that were lost */
|
|
long frames_ooo; /* Number of frames that were Out Of Order */
|
|
long frames_dropped; /* Number of frames that were dropped due shrinkage of the jitterbuffer */
|
|
long frames_dropped_twice; /* Number of frames that were dropped because this timestamp was already in the jitterbuffer */
|
|
|
|
long delay; /* Current delay due the jitterbuffer */
|
|
long jitter; /* jitter measured within current history interval*/
|
|
long losspct; /* recent lost frame percentage (network and jitterbuffer loss) */
|
|
|
|
long delay_target; /* The delay where we want to grow to */
|
|
long losspct_jb; /* recent lost percentage due the jitterbuffer */
|
|
long last_voice_ms; /* the duration of the last voice frame */
|
|
short silence; /* If we are in silence 1-yes 0-no */
|
|
long iqr; /* Inter Quartile Range of current history, if the squareroot is taken it is a good estimate of jitter */
|
|
} jb_info;
|
|
|
|
typedef struct jb_frame {
|
|
void *data; /* the frame data */
|
|
long ts; /* the senders timestamp */
|
|
long ms; /* length of this frame in ms */
|
|
int type; /* the type of frame */
|
|
int codec; /* codec of this frame, undefined if nonvoice */
|
|
struct jb_frame *next, *prev; /* pointers to the next and previous frames in the queue */
|
|
} jb_frame;
|
|
|
|
typedef struct jb_hist_element {
|
|
long delay; /* difference between time of arrival and senders timestamp */
|
|
long ts; /* senders timestamp */
|
|
long ms; /* length of this frame in ms */
|
|
int codec; /* wich codec this frame has */
|
|
} jb_hist_element;
|
|
|
|
typedef struct jb_settings {
|
|
/* settings */
|
|
long min_jb; /* defines a hard clamp to use in setting the jitterbuffer delay */
|
|
long max_jb; /* defines a hard clamp to use in setting the jitterbuffer delay */
|
|
long max_successive_interp; /* the maximum count of successive interpolations before assuming silence */
|
|
long extra_delay; /* amount of extra delay allowed before shrinking */
|
|
long wait_grow; /* ms between growing */
|
|
long wait_shrink; /* ms between shrinking */
|
|
long max_diff; /* maximum number of milliseconds the jitterbuffer may be off */
|
|
} jb_settings;
|
|
|
|
typedef struct jitterbuffer {
|
|
struct jb_hist_element hist[JB_HISTORY_SIZE]; /* the history of the last received frames */
|
|
long hist_sorted_delay[JB_HISTORY_SIZE]; /* a sorted buffer of the delays (lowest first) */
|
|
long hist_sorted_timestamp[JB_HISTORY_SIZE]; /* a sorted buffer of the timestamps (lowest first) */
|
|
|
|
int hist_pointer; /* points to index in history for next entry */
|
|
long last_adjustment; /* the time of the last adjustment (growing or shrinking) */
|
|
long next_voice_time; /* the next ts is to be read from the jb (senders timestamp) */
|
|
long cnt_successive_interp; /* the count of consecutive interpolation frames */
|
|
long silence_begin_ts; /* the time of the last CNG frame, when in silence */
|
|
long min; /* the clock difference within current history interval */
|
|
long current; /* the present jitterbuffer adjustment */
|
|
long target; /* the target jitterbuffer adjustment */
|
|
long last_delay; /* the delay of the last packet, used for calc. jitter */
|
|
|
|
jb_frame *voiceframes; /* queued voiceframes */
|
|
jb_frame *controlframes; /* queued controlframes */
|
|
jb_settings settings; /* the settings of the jitterbuffer */
|
|
jb_info info; /* the statistics of the jitterbuffer */
|
|
} jitterbuffer;
|
|
|
|
//parameter definitions
|
|
/* return codes */
|
|
#define JB_OK 0
|
|
#define JB_EMPTY 1
|
|
#define JB_NOFRAME 2
|
|
#define JB_INTERP 3
|
|
#define JB_NOJB 4
|
|
|
|
|
|
/* frame types */
|
|
#define JB_TYPE_CONTROL 1
|
|
#define JB_TYPE_VOICE 2
|
|
#define JB_TYPE_SILENCE 3
|
|
|
|
/* the jitterbuffer behaives different for each codec. */
|
|
/* Look in the code if a codec has his function defined */
|
|
/* default is g711x behaiviour */
|
|
#define JB_CODEC_SPEEX 10 //NOT defined
|
|
#define JB_CODEC_ILBC 9 //NOT defined
|
|
#define JB_CODEC_GSM_EFR 8
|
|
#define JB_CODEC_GSM_FR 7 //NOT defined
|
|
#define JB_CODEC_G723_1 6
|
|
#define JB_CODEC_G729A 5
|
|
#define JB_CODEC_G729 4
|
|
#define JB_CODEC_G711x_PLC 3
|
|
#define JB_CODEC_G711x 2
|
|
#define JB_CODEC_OTHER 1 //NOT defined
|
|
|
|
|
|
/*
|
|
* Creates a new jitterbuffer and sets the default settings.
|
|
* Always use this function for creating a new jitterbuffer.
|
|
*/
|
|
jitterbuffer *jb_new();
|
|
|
|
/*
|
|
* The control frames and possible personal settings are kept.
|
|
* History and voice/silence frames are destroyed.
|
|
*/
|
|
void jb_reset(jitterbuffer *jb);
|
|
|
|
/*
|
|
* Resets the jitterbuffer totally, all the control/voice/silence frames are destroyed
|
|
* default settings are put as well.
|
|
*/
|
|
void jb_reset_all(jitterbuffer *jb);
|
|
|
|
/*
|
|
* Destroy the jitterbuffer and any frame within.
|
|
* Always use this function for destroying a jitterbuffer,
|
|
* otherwise there is a chance of memory leaking.
|
|
*/
|
|
void jb_destroy(jitterbuffer *jb);
|
|
|
|
/*
|
|
* Define your own settings for the jitterbuffer. Only settings !=0
|
|
* are put in the jitterbuffer.
|
|
*/
|
|
void jb_set_settings(jitterbuffer *jb, jb_settings *settings);
|
|
|
|
/*
|
|
* Get the statistics for the jitterbuffer.
|
|
* Copying the statistics directly for the jitterbuffer won't work because
|
|
* The statistics are only calculated when calling this function.
|
|
*/
|
|
void jb_get_info(jitterbuffer *jb, jb_info *stats);
|
|
|
|
/*
|
|
* Get the current settings of the jitterbuffer.
|
|
*/
|
|
void jb_get_settings(jitterbuffer *jb, jb_settings *settings);
|
|
|
|
/*
|
|
* Gives an estimation of the MOS of a call given the
|
|
* packetloss p, delay d, and wich codec is used.
|
|
* The assumption is made that the echo cancelation is around 37dB.
|
|
*/
|
|
float jb_guess_mos(float p, long d, int codec);
|
|
|
|
/*
|
|
* returns JB_OK if there are still frames left in the jitterbuffer
|
|
* otherwise JB_EMPTY is returned.
|
|
*/
|
|
int jb_has_frames(jitterbuffer *jb);
|
|
|
|
/*
|
|
* put a packet(frame) into the jitterbuffer.
|
|
* *data - points to the packet
|
|
* type - type of packet, JB_CONTROL|JB_VOICE|JB_SILENCE
|
|
* ms - duration of frame (only voice)
|
|
* ts - timestamp sender
|
|
* now - current timestamp (timestamp of arrival)
|
|
* codec - which codec the frame holds (only voice), if not defined, g711x will be used
|
|
*
|
|
* if type==control @REQUIRE: *data, type, ts, now
|
|
* if type==voice @REQUIRE: *data, type, ms, ts, now @OPTIONAL: codec
|
|
* if type==silence @REQUIRE: *data, type, ts, now
|
|
* on return *data is undefined
|
|
*/
|
|
void jb_put(jitterbuffer *jb, void *data, int type, long ms, long ts, long now, int codec);
|
|
|
|
/*
|
|
* Get a packet from the jitterbuffer if it's available.
|
|
* control packets have a higher priority above voice and silence packets
|
|
* they are always delivered as fast as possible. The delay of the jitterbuffer
|
|
* doesn't work for these packets.
|
|
* @REQUIRE 1<interpl <= jb->settings->extra_delay (=default JB_ALLOW_EXTRA_DELAY)
|
|
*
|
|
* return will be:
|
|
* JB_OK, *data points to the packet
|
|
* JB_INTERP, please interpolate for interpl milliseconds
|
|
* JB_NOFRAME, no frame scheduled
|
|
* JB_EMPTY, the jitterbuffer is empty
|
|
*/
|
|
int jb_get(jitterbuffer *jb, void **data, long now, long interpl);
|
|
|
|
/* debug functions */
|
|
typedef void (*jb_output_function_t)(const char *fmt, ...);
|
|
void jb_setoutput(jb_output_function_t warn, jb_output_function_t err, jb_output_function_t dbg);
|
|
|
|
|
|
/*******************************
|
|
* The use of the jitterbuffer *
|
|
*******************************
|
|
* Always create a new jitterbuffer with jb_new().
|
|
* Always destroy a jitterbuffer with jb_destroy().
|
|
*
|
|
* There is no lock(mutex) mechanism, that your responsibility.
|
|
* The reason for this is that different environments require
|
|
* different ways of implementing a lock.
|
|
*
|
|
* The following functions require a lock on the jitterbuffer:
|
|
* jb_reset(), jb_reset_all(), jb_destroy(), jb_set_settings(),
|
|
* jb_get_info(), jb_get_settings(), jb_has_frames(), jb_put(),
|
|
* jb_get()
|
|
*
|
|
* The following functions do NOT require a lock on the jitterbuffer:
|
|
* jb_new(), jb_guess_mos()
|
|
*
|
|
* Since control packets have a higher priority above any other packet
|
|
* a call may already be ended while there is audio left to play. We
|
|
* advice that you poll the jitterbuffer if there are frames left.
|
|
*
|
|
* If the audiopath is oneway (eg. voicemailbox) and the latency doesn't
|
|
* matter, we advice to set a minimum jitterbuffer size. Then there is
|
|
* less loss and the quality is better.
|
|
*/
|
|
|
|
|
|
/****************************
|
|
* debug messages explained *
|
|
****************************
|
|
* N - jb_new()
|
|
* R - jb_reset()
|
|
* r - jb_reset_all()
|
|
* D - jb_destroy()
|
|
* S - jb_set_settings()
|
|
* H - jb_has_frames()
|
|
* I - jb_get_info()
|
|
* S - jb_get_settings()
|
|
* pC - jb_put() put Control packet
|
|
* pT - jb_put() Timestamp was already in the queue
|
|
* pV - jb_put() put Voice packet
|
|
* pS - jb_put() put Silence packet
|
|
*
|
|
* A - jb_get()
|
|
* // below are all the possible debug info when trying to get a packet
|
|
* gC - get_control() - there is a control message
|
|
* gs - get_voice() - there is a silence frame
|
|
* gS - get_voice() - we are in silence
|
|
* gL - get_voice() - are in silence, frame is late
|
|
* gP - get_voice() - are in silence, play frame (end of silence)
|
|
* ag - get_voicecase() - grow little bit (diff < interpl/2)
|
|
* aG - get_voicecase() - grow interpl
|
|
* as - get_voicecase() - shrink by voiceframe we throw out
|
|
* aS - get_voicecase() - shrink by interpl
|
|
* aN - get_voicecase() - no time yet
|
|
* aL - get_voicecase() - frame is late
|
|
* aP - get_voicecase() - play frame
|
|
* aI - get_voicecase() - interpolate
|
|
*/
|
|
|
|
TDAV_END_DECLS
|
|
|
|
#endif /* !(HAVE_SPEEX_DSP && HAVE_SPEEX_JB) */
|
|
|
|
#endif /* TINYDAV_JITTERBUFFER_H_ */
|
|
|