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