/* 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 * - SpeakUp * * Contributors: * Jesse Kaijen * * 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 1settings->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_ */