00001 /* 00002 * jitterbuf: an application-independent jitterbuffer 00003 * 00004 * Copyrights: 00005 * Copyright (C) 2004-2005, Horizon Wimba, Inc. 00006 * 00007 * Contributors: 00008 * Steve Kann <stevek@stevek.com> 00009 * 00010 * This program is free software, distributed under the terms of 00011 * the GNU Lesser (Library) General Public License 00012 * 00013 * Copyright on this file is disclaimed to Digium for inclusion in Asterisk 00014 */ 00015 00016 /*! \file 00017 * \brief 00018 * jitterbuf: an application-independent jitterbuffer 00019 * \ref jitterbuf.c 00020 */ 00021 00022 00023 #ifndef _JITTERBUF_H_ 00024 #define _JITTERBUF_H_ 00025 00026 #ifdef __cplusplus 00027 extern "C" { 00028 #endif 00029 00030 /*! \name configuration constants */ 00031 /*@{ */ 00032 /*! Number of historical timestamps to use in calculating jitter and drift */ 00033 #define JB_HISTORY_SZ 500 00034 /*! what percentage of timestamps should we drop from the history when we examine it; 00035 * this might eventually be something made configurable */ 00036 #define JB_HISTORY_DROPPCT 3 00037 /*! the maximum droppct we can handle (say it was configurable). */ 00038 #define JB_HISTORY_DROPPCT_MAX 4 00039 /*! the size of the buffer we use to keep the top and botton timestamps for dropping */ 00040 #define JB_HISTORY_MAXBUF_SZ JB_HISTORY_SZ * JB_HISTORY_DROPPCT_MAX / 100 00041 /*! amount of additional jitterbuffer adjustment */ 00042 #define JB_TARGET_EXTRA 40 00043 /*! ms between growing and shrinking; may not be honored if jitterbuffer runs out of space */ 00044 #define JB_ADJUST_DELAY 40 00045 /*@} */ 00046 00047 enum jb_return_code { 00048 /* return codes */ 00049 JB_OK, /* 0 */ 00050 JB_EMPTY, /* 1 */ 00051 JB_NOFRAME, /* 2 */ 00052 JB_INTERP, /* 3 */ 00053 JB_DROP, /* 4 */ 00054 JB_SCHED /* 5 */ 00055 }; 00056 00057 enum jb_frame_type { 00058 /* frame types */ 00059 JB_TYPE_CONTROL, /*!< 0 */ 00060 JB_TYPE_VOICE, /*!< 1 */ 00061 JB_TYPE_VIDEO, /*!< 2 - reserved */ 00062 JB_TYPE_SILENCE /*!< 3 */ 00063 }; 00064 00065 typedef struct jb_conf { 00066 /* settings */ 00067 long max_jitterbuf; /*!< defines a hard clamp to use in setting the jitter buffer delay */ 00068 long resync_threshold; /*!< the jb will resync when delay increases to (2 * jitter) + this param */ 00069 long max_contig_interp; /*!< the max interp frames to return in a row */ 00070 long target_extra ; /*!< amount of additional jitterbuffer adjustment, overrides JB_TARGET_EXTRA */ 00071 } jb_conf; 00072 00073 typedef struct jb_info { 00074 jb_conf conf; 00075 00076 /* statistics */ 00077 long frames_in; /*!< number of frames input to the jitterbuffer.*/ 00078 long frames_out; /*!< number of frames output from the jitterbuffer.*/ 00079 long frames_late; /*!< number of frames which were too late, and dropped.*/ 00080 long frames_lost; /*!< number of missing frames.*/ 00081 long frames_dropped; /*!< number of frames dropped (shrinkage) */ 00082 long frames_ooo; /*!< number of frames received out-of-order */ 00083 long frames_cur; /*!< number of frames presently in jb, awaiting delivery.*/ 00084 long jitter; /*!< jitter measured within current history interval*/ 00085 long min; /*!< minimum lateness within current history interval */ 00086 long current; /*!< the present jitterbuffer adjustment */ 00087 long target; /*!< the target jitterbuffer adjustment */ 00088 long losspct; /*!< recent lost frame percentage (* 1000) */ 00089 long next_voice_ts; /*!< the ts of the next frame to be read from the jb - in receiver's time */ 00090 long last_voice_ms; /*!< the duration of the last voice frame */ 00091 long silence_begin_ts; /*!< the time of the last CNG frame, when in silence */ 00092 long last_adjustment; /*!< the time of the last adjustment */ 00093 long last_delay; /*!< the last now added to history */ 00094 long cnt_delay_discont; /*!< the count of discontinuous delays */ 00095 long resync_offset; /*!< the amount to offset ts to support resyncs */ 00096 long cnt_contig_interp; /*!< the number of contiguous interp frames returned */ 00097 } jb_info; 00098 00099 typedef struct jb_frame { 00100 void *data; /* the frame data */ 00101 long ts; /* the relative delivery time expected */ 00102 long ms; /* the time covered by this frame, in sec/8000 */ 00103 enum jb_frame_type type; /* the type of frame */ 00104 struct jb_frame *next, *prev; 00105 } jb_frame; 00106 00107 typedef struct jitterbuf { 00108 jb_info info; 00109 00110 /* history */ 00111 long history[JB_HISTORY_SZ]; /*!< history */ 00112 int hist_ptr; /*!< points to index in history for next entry */ 00113 long hist_maxbuf[JB_HISTORY_MAXBUF_SZ]; /*!< a sorted buffer of the max delays (highest first) */ 00114 long hist_minbuf[JB_HISTORY_MAXBUF_SZ]; /*!< a sorted buffer of the min delays (lowest first) */ 00115 int hist_maxbuf_valid; /*!< are the "maxbuf"/minbuf valid? */ 00116 unsigned int dropem:1; /*!< flag to indicate dropping frames (overload) */ 00117 00118 jb_frame *frames; /*!< queued frames */ 00119 jb_frame *free; /*!< free frames (avoid malloc?) */ 00120 } jitterbuf; 00121 00122 00123 /*! \brief new jitterbuf */ 00124 jitterbuf * jb_new(void); 00125 00126 /*! \brief destroy jitterbuf */ 00127 void jb_destroy(jitterbuf *jb); 00128 00129 /*! \brief reset jitterbuf 00130 * \note The jitterbuffer should be empty before you call this, otherwise 00131 * you will leak queued frames, and some internal structures */ 00132 void jb_reset(jitterbuf *jb); 00133 00134 /*!\brief queue a frame 00135 * 00136 * data=frame data, timings (in ms): ms=length of frame (for voice), ts=ts (sender's time) 00137 * now=now (in receiver's time) return value is one of 00138 * JB_OK: Frame added. Last call to jb_next() still valid 00139 * JB_DROP: Drop this frame immediately 00140 * JB_SCHED: Frame added. Call jb_next() to get a new time for the next frame 00141 */ 00142 enum jb_return_code jb_put(jitterbuf *jb, void *data, const enum jb_frame_type type, long ms, long ts, long now); 00143 00144 /*! \brief get a frame for time now (receiver's time) return value is one of 00145 * JB_OK: You've got frame! 00146 * JB_DROP: Here's an audio frame you should just drop. Ask me again for this time.. 00147 * JB_NOFRAME: There's no frame scheduled for this time. 00148 * JB_INTERP: Please interpolate an interpl-length frame for this time (either we need to grow, or there was a lost frame) 00149 * JB_EMPTY: The jb is empty. 00150 */ 00151 enum jb_return_code jb_get(jitterbuf *jb, jb_frame *frame, long now, long interpl); 00152 00153 /*! \brief unconditionally get frames from jitterbuf until empty */ 00154 enum jb_return_code jb_getall(jitterbuf *jb, jb_frame *frameout); 00155 00156 /*! \brief when is the next frame due out, in receiver's time (0=EMPTY) 00157 * This value may change as frames are added (esp non-audio frames) */ 00158 long jb_next(jitterbuf *jb); 00159 00160 /*! \brief get jitterbuf info: only "statistics" may be valid */ 00161 enum jb_return_code jb_getinfo(jitterbuf *jb, jb_info *stats); 00162 00163 /*! \brief set jitterbuf conf */ 00164 enum jb_return_code jb_setconf(jitterbuf *jb, jb_conf *conf); 00165 00166 typedef void __attribute__((format(printf, 1, 2))) (*jb_output_function_t)(const char *fmt, ...); 00167 void jb_setoutput(jb_output_function_t err, jb_output_function_t warn, jb_output_function_t dbg); 00168 00169 #ifdef __cplusplus 00170 } 00171 #endif 00172 00173 00174 #endif