Add PLC and jitter buffer and iax2 meta trunk with timestamps (bug #2532, #3400)
[asterisk/asterisk.git] / 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
34
35 /* return codes */
36 #define JB_OK           0
37 #define JB_EMPTY        1
38 #define JB_NOFRAME      2
39 #define JB_INTERP       3
40 #define JB_DROP         4
41
42 /* frame types */
43 #define JB_TYPE_CONTROL 0
44 #define JB_TYPE_VOICE   1
45 #define JB_TYPE_VIDEO   2  /* reserved */
46 #define JB_TYPE_SILENCE 3
47
48 typedef struct jb_info {
49         /* statistics */
50         long frames_in;         /* number of frames input to the jitterbuffer.*/
51         long frames_out;        /* number of frames output from the jitterbuffer.*/
52         long frames_late;       /* number of frames which were too late, and dropped.*/
53         long frames_lost;       /* number of missing frames.*/
54         long frames_dropped;    /* number of frames dropped (shrinkage) */
55         long frames_ooo;        /* number of frames received out-of-order */
56         long frames_cur;        /* number of frames presently in jb, awaiting delivery.*/
57         long jitter;            /* jitter measured within current history interval*/
58         long min;               /* minimum lateness within current history interval */
59         long current;           /* the present jitterbuffer adjustment */
60         long target;            /* the target jitterbuffer adjustment */
61         long losspct;           /* recent lost frame percentage (* 1000) */
62         long last_voice_ts;     /* the last ts that was read from the jb - in receiver's time */
63         long last_voice_ms;     /* the duration of the last voice frame */
64         long silence;           /* we are presently playing out silence */
65         long last_adjustment;   /* the time of the last adjustment */
66
67         /* settings */
68         long max_jitterbuf;     /* defines a hard clamp to use in setting the jitter buffer delay */
69 } jb_info;
70
71 typedef struct jb_frame {
72         void *data;             /* the frame data */
73         long ts;        /* the relative delivery time expected */
74         long ms;        /* the time covered by this frame, in sec/8000 */
75         int  type;      /* the type of frame */
76         struct jb_frame *next, *prev;
77 } jb_frame;
78
79 typedef struct jitterbuf {
80         jb_info info;
81
82         /* history */
83         long history[JB_HISTORY_SZ];            /* history */
84         int  hist_ptr;                          /* points to index in history for next entry */
85         long hist_maxbuf[JB_HISTORY_MAXBUF_SZ]; /* a sorted buffer of the max delays (highest first) */
86         long hist_minbuf[JB_HISTORY_MAXBUF_SZ]; /* a sorted buffer of the min delays (lowest first) */
87         int  hist_maxbuf_valid;                 /* are the "maxbuf"/minbuf valid? */
88
89
90         jb_frame *frames;               /* queued frames */
91         jb_frame *free;                 /* free frames (avoid malloc?) */
92 } jitterbuf;
93
94
95 /* new jitterbuf */
96 jitterbuf *             jb_new(void);
97
98 /* destroy jitterbuf */
99 void                    jb_destroy(jitterbuf *jb);
100
101 /* reset jitterbuf */
102 /* NOTE:  The jitterbuffer should be empty before you call this, otherwise
103  * you will leak queued frames, and some internal structures */
104 void                    jb_reset(jitterbuf *jb);
105
106 /* queue a frame data=frame data, timings (in ms): ms=length of frame (for voice), ts=ts (sender's time) 
107  * now=now (in receiver's time)*/
108 int                     jb_put(jitterbuf *jb, void *data, int type, long ms, long ts, long now);
109
110 /* get a frame for time now (receiver's time)  return value is one of
111  * JB_OK:  You've got frame!
112  * JB_DROP: Here's an audio frame you should just drop.  Ask me again for this time..
113  * JB_NOFRAME: There's no frame scheduled for this time.
114  * JB_INTERP: Please interpolate an audio frame for this time (either we need to grow, or there was a lost frame 
115  * JB_EMPTY: The jb is empty.
116  */
117 int                     jb_get(jitterbuf *jb, jb_frame *frame, long now);
118
119 /* unconditionally get frames from jitterbuf until empty */
120 int jb_getall(jitterbuf *jb, jb_frame *frameout);
121
122 /* when is the next frame due out, in receiver's time (0=EMPTY) 
123  * This value may change as frames are added (esp non-audio frames) */
124 long                    jb_next(jitterbuf *jb);
125
126 /* get jitterbuf info: only "statistics" may be valid */
127 int                     jb_getinfo(jitterbuf *jb, jb_info *stats);
128
129 /* set jitterbuf info: only "settings" may be honored */
130 int                     jb_setinfo(jitterbuf *jb, jb_info *settings);
131
132 typedef                 void (*jb_output_function_t)(const char *fmt, ...);
133 void                    jb_setoutput(jb_output_function_t warn, jb_output_function_t err, jb_output_function_t dbg);
134
135 #ifdef __cplusplus
136 }
137 #endif
138
139
140 #endif