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