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