Thu Oct 11 06:33:49 2012

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 /*! \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

Generated on Thu Oct 11 06:33:49 2012 for Asterisk - The Open Source Telephony Project by  doxygen 1.5.6