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