Asterisk - The Open Source Telephony Project  GIT-master-a1fa8df
jitterbuf.h
Go to the documentation of this file.
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 
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 
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 {
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 {
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 */
165 
166 typedef void __attribute__((format(printf, 1, 2))) (*jb_output_function_t)(const char *fmt, ...);
168 
169 /*! \brief Checks if the given time stamp is late */
170 int jb_is_late(jitterbuf *jb, long ts);
171 
172 #ifdef __cplusplus
173 }
174 #endif
175 
176 
177 #endif
long max_jitterbuf
Definition: jitterbuf.h:67
static const char type[]
Definition: chan_ooh323.c:109
jb_return_code
Definition: jitterbuf.h:47
jb_frame_type
Definition: jitterbuf.h:57
int hist_maxbuf_valid
Definition: jitterbuf.h:115
long silence_begin_ts
Definition: jitterbuf.h:91
jb_frame * frames
Definition: jitterbuf.h:118
void jb_setoutput(jb_output_function_t err, jb_output_function_t warn, jb_output_function_t dbg)
Definition: jitterbuf.c:55
long losspct
Definition: jitterbuf.h:88
void(* jb_output_function_t)(const char *fmt,...)
Definition: jitterbuf.h:166
struct jb_frame jb_frame
enum jb_return_code jb_put(jitterbuf *jb, void *data, const enum jb_frame_type type, long ms, long ts, long now)
queue a frame
Definition: jitterbuf.c:525
long frames_lost
Definition: jitterbuf.h:80
long cnt_delay_discont
Definition: jitterbuf.h:94
long last_delay
Definition: jitterbuf.h:93
enum jb_return_code jb_get(jitterbuf *jb, jb_frame *frame, long now, long interpl)
get a frame for time now (receiver&#39;s time) return value is one of JB_OK: You&#39;ve got frame! JB_DROP: H...
Definition: jitterbuf.c:785
struct jb_frame * prev
Definition: jitterbuf.h:104
int hist_ptr
Definition: jitterbuf.h:112
All configuration options for statsd client.
Definition: res_statsd.c:101
jitterbuf * jb_new(void)
new jitterbuf
Definition: jitterbuf.c:86
long last_adjustment
Definition: jitterbuf.h:92
long frames_in
Definition: jitterbuf.h:77
long jb_next(jitterbuf *jb)
when is the next frame due out, in receiver&#39;s time (0=EMPTY) This value may change as frames are adde...
Definition: jitterbuf.c:767
long resync_threshold
Definition: jitterbuf.h:68
jb_frame * free
Definition: jitterbuf.h:119
long frames_ooo
Definition: jitterbuf.h:82
int jb_is_late(jitterbuf *jb, long ts)
Checks if the given time stamp is late.
Definition: jitterbuf.c:846
#define JB_HISTORY_SZ
Definition: jitterbuf.h:33
long frames_dropped
Definition: jitterbuf.h:81
#define JB_HISTORY_MAXBUF_SZ
Definition: jitterbuf.h:40
jb_info info
Definition: jitterbuf.h:108
long last_voice_ms
Definition: jitterbuf.h:90
long target_extra
Definition: jitterbuf.h:70
jb_conf conf
Definition: jitterbuf.h:74
long ts
Definition: jitterbuf.h:101
long target
Definition: jitterbuf.h:87
void * data
Definition: jitterbuf.h:100
enum jb_return_code jb_setconf(jitterbuf *jb, jb_conf *conf)
set jitterbuf conf
Definition: jitterbuf.c:825
long frames_late
Definition: jitterbuf.h:79
long ms
Definition: jitterbuf.h:102
struct jb_info jb_info
long next_voice_ts
Definition: jitterbuf.h:89
unsigned int dropem
Definition: jitterbuf.h:116
long cnt_contig_interp
Definition: jitterbuf.h:96
struct jb_conf jb_conf
enum jb_return_code jb_getinfo(jitterbuf *jb, jb_info *stats)
get jitterbuf info: only "statistics" may be valid
Definition: jitterbuf.c:815
long resync_offset
Definition: jitterbuf.h:95
long min
Definition: jitterbuf.h:85
long frames_out
Definition: jitterbuf.h:78
struct jb_frame * next
Definition: jitterbuf.h:104
long frames_cur
Definition: jitterbuf.h:83
long jitter
Definition: jitterbuf.h:84
void jb_destroy(jitterbuf *jb)
destroy jitterbuf
Definition: jitterbuf.c:99
struct jitterbuf jitterbuf
enum jb_return_code jb_getall(jitterbuf *jb, jb_frame *frameout)
unconditionally get frames from jitterbuf until empty
Definition: jitterbuf.c:801
static snd_pcm_format_t format
Definition: chan_alsa.c:106
long current
Definition: jitterbuf.h:86
long max_contig_interp
Definition: jitterbuf.h:69
void jb_reset(jitterbuf *jb)
reset jitterbuf
Definition: jitterbuf.c:72