include/jitterbuf.h

   1 /*
   2  * jitterbuf: an application-independent jitterbuffer
   3  *
   4  * Copyrights:
   5  * Copyright (C) 2004-2005, Horizon Wimba, Inc.
   6  *
   7  * Contributors:
   8  * Steve Kann <stevek@stevek.com>
   9  *
  10  * This program is free software, distributed under the terms of
  11  * the GNU Lesser (Library) General Public License
  12  *
  13  * Copyright on this file is disclaimed to Digium for inclusion in Asterisk
  14  */
  15
  16 /*! \file
  17  * \brief
  18  * jitterbuf: an application-independent jitterbuffer
  19  * \ref jitterbuf.c
  20  */
  21
  22
  23 #ifndef _JITTERBUF_H_
  24 #define _JITTERBUF_H_
  25
  26 #ifdef __cplusplus
  27 extern "C" {
  28 #endif
  29
  30 /*! \name configuration constants */
  31 /*@{ */
  32         /*! Number of historical timestamps to use in calculating jitter and drift */
  33 #define JB_HISTORY_SZ           500
  34         /*! what percentage of timestamps should we drop from the history when we examine it;
  35          * this might eventually be something made configurable */
  36 #define JB_HISTORY_DROPPCT      3
  37         /*! the maximum droppct we can handle (say it was configurable). */
  38 #define JB_HISTORY_DROPPCT_MAX  4
  39         /*! the size of the buffer we use to keep the top and botton timestamps for dropping */
  40 #define JB_HISTORY_MAXBUF_SZ    JB_HISTORY_SZ * JB_HISTORY_DROPPCT_MAX / 100
  41         /*! amount of additional jitterbuffer adjustment  */
  42 #define JB_TARGET_EXTRA 40
  43         /*! ms between growing and shrinking; may not be honored if jitterbuffer runs out of space */
  44 #define JB_ADJUST_DELAY 40
  45 /*@} */
  46
  47 enum jb_return_code {
  48         /* return codes */
  49         JB_OK,            /* 0 */
  50         JB_EMPTY,         /* 1 */
  51         JB_NOFRAME,       /* 2 */
  52         JB_INTERP,        /* 3 */
  53         JB_DROP,          /* 4 */
  54         JB_SCHED          /* 5 */
  55 };
  56
  57 enum jb_frame_type {
  58         /* frame types */
  59         JB_TYPE_CONTROL,  /*!< 0            */
  60         JB_TYPE_VOICE,    /*!< 1            */
  61         JB_TYPE_VIDEO,    /*!< 2 - reserved */
  62         JB_TYPE_SILENCE   /*!< 3            */
  63 };
  64
  65 typedef struct jb_conf {
  66         /* settings */
  67         long max_jitterbuf;     /*!< defines a hard clamp to use in setting the jitter buffer delay */
  68         long resync_threshold;  /*!< the jb will resync when delay increases to (2 * jitter) + this param */
  69         long max_contig_interp; /*!< the max interp frames to return in a row */
  70         long target_extra ;      /*!< amount of additional jitterbuffer adjustment, overrides JB_TARGET_EXTRA */
  71 } jb_conf;
  72
  73 typedef struct jb_info {
  74         jb_conf conf;
  75
  76         /* statistics */
  77         long frames_in;         /*!< number of frames input to the jitterbuffer.*/
  78         long frames_out;        /*!< number of frames output from the jitterbuffer.*/
  79         long frames_late;       /*!< number of frames which were too late, and dropped.*/
  80         long frames_lost;       /*!< number of missing frames.*/
  81         long frames_dropped;    /*!< number of frames dropped (shrinkage) */
  82         long frames_ooo;        /*!< number of frames received out-of-order */
  83         long frames_cur;        /*!< number of frames presently in jb, awaiting delivery.*/
  84         long jitter;            /*!< jitter measured within current history interval*/
  85         long min;               /*!< minimum lateness within current history interval */
  86         long current;           /*!< the present jitterbuffer adjustment */
  87         long target;            /*!< the target jitterbuffer adjustment */
  88         long losspct;           /*!< recent lost frame percentage (* 1000) */
  89         long next_voice_ts;     /*!< the ts of the next frame to be read from the jb - in receiver's time */
  90         long last_voice_ms;     /*!< the duration of the last voice frame */
  91         long silence_begin_ts;  /*!< the time of the last CNG frame, when in silence */
  92         long last_adjustment;   /*!< the time of the last adjustment */
  93         long last_delay;        /*!< the last now added to history */
  94         long cnt_delay_discont; /*!< the count of discontinuous delays */
  95         long resync_offset;     /*!< the amount to offset ts to support resyncs */
  96         long cnt_contig_interp; /*!< the number of contiguous interp frames returned */
  97 } jb_info;
  98
  99 typedef struct jb_frame {
 100         void *data;               /* the frame data */
 101         long ts;                  /* the relative delivery time expected */
 102         long ms;                  /* the time covered by this frame, in sec/8000 */
 103         enum jb_frame_type type;  /* the type of frame */
 104         struct jb_frame *next, *prev;
 105 } jb_frame;
 106
 107 typedef struct jitterbuf {
 108         jb_info info;
 109
 110         /* history */
 111         long history[JB_HISTORY_SZ];            /*!< history */
 112         int  hist_ptr;                          /*!< points to index in history for next entry */
 113         long hist_maxbuf[JB_HISTORY_MAXBUF_SZ]; /*!< a sorted buffer of the max delays (highest first) */
 114         long hist_minbuf[JB_HISTORY_MAXBUF_SZ]; /*!< a sorted buffer of the min delays (lowest first) */
 115         int  hist_maxbuf_valid;                 /*!< are the "maxbuf"/minbuf valid? */
 116         unsigned int dropem:1;                  /*!< flag to indicate dropping frames (overload) */
 117
 118         jb_frame *frames;               /*!< queued frames */
 119         jb_frame *free;                 /*!< free frames (avoid malloc?) */
 120 } jitterbuf;
 121
 122
 123 /*! \brief new jitterbuf */
 124 jitterbuf *             jb_new(void);
 125
 126 /*! \brief destroy jitterbuf */
 127 void                    jb_destroy(jitterbuf *jb);
 128
 129 /*! \brief reset jitterbuf
 130  * \note The jitterbuffer should be empty before you call this, otherwise
 131  * you will leak queued frames, and some internal structures */
 132 void                    jb_reset(jitterbuf *jb);
 133
 134 /*!\brief  queue a frame
 135  *
 136  * data=frame data, timings (in ms): ms=length of frame (for voice), ts=ts (sender's time)
 137  * now=now (in receiver's time) return value is one of
 138  * JB_OK: Frame added. Last call to jb_next() still valid
 139  * JB_DROP: Drop this frame immediately
 140  * JB_SCHED: Frame added. Call jb_next() to get a new time for the next frame
 141  */
 142 enum jb_return_code jb_put(jitterbuf *jb, void *data, const enum jb_frame_type type, long ms, long ts, long now);
 143
 144 /*! \brief get a frame for time now (receiver's time)  return value is one of
 145  * JB_OK:  You've got frame!
 146  * JB_DROP: Here's an audio frame you should just drop.  Ask me again for this time..
 147  * JB_NOFRAME: There's no frame scheduled for this time.
 148  * JB_INTERP: Please interpolate an interpl-length frame for this time (either we need to grow, or there was a lost frame)
 149  * JB_EMPTY: The jb is empty.
 150  */
 151 enum jb_return_code jb_get(jitterbuf *jb, jb_frame *frame, long now, long interpl);
 152
 153 /*! \brief unconditionally get frames from jitterbuf until empty */
 154 enum jb_return_code jb_getall(jitterbuf *jb, jb_frame *frameout);
 155
 156 /*! \brief when is the next frame due out, in receiver's time (0=EMPTY)
 157  * This value may change as frames are added (esp non-audio frames) */
 158 long    jb_next(jitterbuf *jb);
 159
 160 /*! \brief get jitterbuf info: only "statistics" may be valid */
 161 enum jb_return_code jb_getinfo(jitterbuf *jb, jb_info *stats);
 162
 163 /*! \brief set jitterbuf conf */
 164 enum jb_return_code jb_setconf(jitterbuf *jb, jb_conf *conf);
 165
 166 typedef void __attribute__((format(printf, 1, 2))) (*jb_output_function_t)(const char *fmt, ...);
 167 void jb_setoutput(jb_output_function_t err, jb_output_function_t warn, jb_output_function_t dbg);
 168
 169 #ifdef __cplusplus
 170 }
 171 #endif
 172
 173
 174 #endif