Asterisk.org: Developer Documentation (28 Oct 2009)

Wed Oct 28 15:47:54 2009

## Asterisk developer's documentation

- Main Page
- Related Pages
- Modules
- Data Structures
- Files
- Directories

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