Sat Aug 6 00:39:29 2011

Asterisk developer's documentation


jitterbuf.h

Go to the documentation of this file.
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

Generated on Sat Aug 6 00:39:29 2011 for Asterisk - the Open Source PBX by  doxygen 1.4.7