dd1de604ad13db3889eb0eb8e52bf0e122cd3b45
[asterisk/asterisk.git] / funcs / func_jitterbuffer.c
1 /*
2  * Asterisk -- An open source telephony toolkit.
3  *
4  * Copyright (C) 2011, Digium, Inc.
5  *
6  * David Vossel <dvossel@digium.com>
7  *
8  * See http://www.asterisk.org for more information about
9  * the Asterisk project. Please do not directly contact
10  * any of the maintainers of this project for assistance;
11  * the project provides a web site, mailing lists and IRC
12  * channels for your use.
13  *
14  * This program is free software, distributed under the terms of
15  * the GNU General Public License Version 2. See the LICENSE file
16  * at the top of the source tree.
17  */
18
19 /*! \file
20  *
21  * \brief Put a jitterbuffer on the read side of a channel
22  *
23  * \author David Vossel <dvossel@digium.com>
24  *
25  * \ingroup functions
26  */
27
28 #include "asterisk.h"
29
30 ASTERISK_FILE_VERSION(__FILE__, "$Revision$")
31
32 #include "asterisk/module.h"
33 #include "asterisk/channel.h"
34 #include "asterisk/framehook.h"
35 #include "asterisk/pbx.h"
36 #include "asterisk/abstract_jb.h"
37 #include "asterisk/timing.h"
38 #include "asterisk/app.h"
39
40 /*** DOCUMENTATION
41         <function name="JITTERBUFFER" language="en_US">
42                 <synopsis>
43                         Add a Jitterbuffer to the Read side of the channel.  This dejitters the audio stream before it reaches the Asterisk core. This is a write only function.
44                 </synopsis>
45                 <syntax>
46                         <parameter name="jitterbuffer type" required="true">
47                                 <para>Jitterbuffer type can be either <literal>fixed</literal> or <literal>adaptive</literal>.</para>
48                                 <para>Used as follows. </para>
49                                 <para>Set(JITTERBUFFER(type)=max_size[,resync_threshold[,target_extra]])</para>
50                                 <para>Set(JITTERBUFFER(type)=default) </para>
51                         </parameter>
52                 </syntax>
53                 <description>
54                         <para>max_size: Defaults to 200 ms</para>
55                         <para>Length in milliseconds of buffer.</para>
56                         <para> </para>
57                         <para>resync_threshold: Defaults to 1000ms </para>
58                         <para>The length in milliseconds over which a timestamp difference will result in resyncing the jitterbuffer. </para>
59                         <para> </para>
60                         <para>target_extra: Defaults to 40ms</para>
61                         <para>This option only affects the adaptive jitterbuffer. It represents the amount time in milliseconds by which the new jitter buffer will pad its size.</para>
62                         <para> </para>
63                         <para>Examples:</para>
64                         <para>exten => 1,1,Set(JITTERBUFFER(fixed)=default);Fixed with defaults. </para>
65                         <para>exten => 1,1,Set(JITTERBUFFER(fixed)=200);Fixed with max size 200ms, default resync threshold and target extra. </para>
66                         <para>exten => 1,1,Set(JITTERBUFFER(fixed)=200,1500);Fixed with max size 200ms resync threshold 1500. </para>
67                         <para>exten => 1,1,Set(JITTERBUFFER(adaptive)=default);Adaptive with defaults. </para>
68                         <para>exten => 1,1,Set(JITTERBUFFER(adaptive)=200,,60);Adaptive with max size 200ms, default resync threshold and 40ms target extra. </para>
69                 </description>
70         </function>
71  ***/
72
73 #define DEFAULT_TIMER_INTERVAL 20
74 #define DEFAULT_SIZE  200
75 #define DEFAULT_TARGET_EXTRA  40
76 #define DEFAULT_RESYNC  1000
77 #define DEFAULT_TYPE AST_JB_FIXED
78
79 struct jb_framedata {
80         const struct ast_jb_impl *jb_impl;
81         struct ast_jb_conf jb_conf;
82         struct timeval start_tv;
83         struct ast_format last_format;
84         struct ast_timer *timer;
85         int timer_interval; /* ms between deliveries */
86         int timer_fd;
87         int first;
88         void *jb_obj;
89 };
90
91 static void jb_framedata_destroy(struct jb_framedata *framedata)
92 {
93         if (framedata->timer) {
94                 ast_timer_close(framedata->timer);
95                 framedata->timer = NULL;
96         }
97         if (framedata->jb_impl && framedata->jb_obj) {
98                 struct ast_frame *f;
99                 while (framedata->jb_impl->remove(framedata->jb_obj, &f) == AST_JB_IMPL_OK) {
100                         ast_frfree(f);
101                 }
102                 framedata->jb_impl->destroy(framedata->jb_obj);
103                 framedata->jb_obj = NULL;
104         }
105         ast_free(framedata);
106 }
107
108 static void jb_conf_default(struct ast_jb_conf *conf)
109 {
110         conf->max_size = DEFAULT_SIZE;
111         conf->resync_threshold = DEFAULT_RESYNC;
112         ast_copy_string(conf->impl, "fixed", sizeof(conf->impl));
113         conf->target_extra = DEFAULT_TARGET_EXTRA;
114 }
115
116 /* set defaults */
117 static int jb_framedata_init(struct jb_framedata *framedata, const char *data, const char *value)
118 {
119         int jb_impl_type = DEFAULT_TYPE;
120
121         /* Initialize defaults */
122         framedata->timer_fd = -1;
123         jb_conf_default(&framedata->jb_conf);
124         if (!(framedata->jb_impl = ast_jb_get_impl(jb_impl_type))) {
125                 return -1;
126         }
127         if (!(framedata->timer = ast_timer_open())) {
128                 return -1;
129         }
130         framedata->timer_fd = ast_timer_fd(framedata->timer);
131         framedata->timer_interval = DEFAULT_TIMER_INTERVAL;
132         ast_timer_set_rate(framedata->timer, 1000 / framedata->timer_interval);
133         framedata->start_tv = ast_tvnow();
134
135
136
137         /* Now check user options to see if any of the defaults need to change. */
138         if (!ast_strlen_zero(data)) {
139                 if (!strcasecmp(data, "fixed")) {
140                         jb_impl_type = AST_JB_FIXED;
141                 } else if (!strcasecmp(data, "adaptive")) {
142                         jb_impl_type = AST_JB_ADAPTIVE;
143                 } else {
144                         ast_log(LOG_WARNING, "Unknown Jitterbuffer type %s. Failed to create jitterbuffer.\n", data);
145                         return -1;
146                 }
147                 ast_copy_string(framedata->jb_conf.impl, data, sizeof(framedata->jb_conf.impl));
148         }
149
150         if (!ast_strlen_zero(value) && strcasecmp(value, "default")) {
151                 char *parse = ast_strdupa(value);
152                 int res = 0;
153                 AST_DECLARE_APP_ARGS(args,
154                         AST_APP_ARG(max_size);
155                         AST_APP_ARG(resync_threshold);
156                         AST_APP_ARG(target_extra);
157                 );
158
159                 AST_STANDARD_APP_ARGS(args, parse);
160                 if (!ast_strlen_zero(args.max_size)) {
161                         res |= ast_jb_read_conf(&framedata->jb_conf,
162                                 "jbmaxsize",
163                                 args.max_size);
164                 }
165                 if (!ast_strlen_zero(args.resync_threshold)) {
166                         res |= ast_jb_read_conf(&framedata->jb_conf,
167                                 "jbresyncthreshold",
168                                 args.resync_threshold);
169                 }
170                 if (!ast_strlen_zero(args.target_extra)) {
171                         res |= ast_jb_read_conf(&framedata->jb_conf,
172                                 "jbtargetextra",
173                                 args.target_extra);
174                 }
175                 if (res) {
176                         ast_log(LOG_WARNING, "Invalid jitterbuffer parameters %s\n", value);
177                 }
178         }
179
180         /* now that all the user parsing is done and nothing will change, create the jb obj */
181         framedata->jb_obj = framedata->jb_impl->create(&framedata->jb_conf, framedata->jb_conf.resync_threshold);
182         return 0;
183 }
184
185 static void datastore_destroy_cb(void *data) {
186         ast_free(data);
187         ast_debug(1, "JITTERBUFFER datastore destroyed\n");
188 }
189
190 static const struct ast_datastore_info jb_datastore = {
191         .type = "jitterbuffer",
192         .destroy = datastore_destroy_cb
193 };
194
195 static void hook_destroy_cb(void *framedata)
196 {
197         ast_debug(1, "JITTERBUFFER hook destroyed\n");
198         jb_framedata_destroy((struct jb_framedata *) framedata);
199 }
200
201 static struct ast_frame *hook_event_cb(struct ast_channel *chan, struct ast_frame *frame, enum ast_framehook_event event, void *data)
202 {
203         struct jb_framedata *framedata = data;
204         struct timeval now_tv;
205         unsigned long now;
206         int putframe = 0; /* signifies if audio frame was placed into the buffer or not */
207
208         switch (event) {
209         case AST_FRAMEHOOK_EVENT_READ:
210                 break;
211         case AST_FRAMEHOOK_EVENT_ATTACHED:
212         case AST_FRAMEHOOK_EVENT_DETACHED:
213         case AST_FRAMEHOOK_EVENT_WRITE:
214                 return frame;
215         }
216
217         if (chan->fdno == AST_JITTERBUFFER_FD && framedata->timer) {
218                 ast_timer_ack(framedata->timer, 1);
219         }
220
221         if (!frame) {
222                 return frame;
223         }
224
225         now_tv = ast_tvnow();
226         now = ast_tvdiff_ms(now_tv, framedata->start_tv);
227
228         if (frame->frametype == AST_FRAME_VOICE) {
229                 int res;
230                 struct ast_frame *jbframe;
231
232                 if (!ast_test_flag(frame, AST_FRFLAG_HAS_TIMING_INFO) || frame->len < 2 || frame->ts < 0) {
233                         /* only frames with timing info can enter the jitterbuffer */
234                         return frame;
235                 }
236
237                 jbframe = ast_frisolate(frame);
238                 ast_format_copy(&framedata->last_format, &frame->subclass.format);
239
240                 if (frame->len && (frame->len != framedata->timer_interval)) {
241                         framedata->timer_interval = frame->len;
242                         ast_timer_set_rate(framedata->timer, 1000 / framedata->timer_interval);
243                 }
244                 if (!framedata->first) {
245                         framedata->first = 1;
246                         res = framedata->jb_impl->put_first(framedata->jb_obj, jbframe, now);
247                 } else {
248                         res = framedata->jb_impl->put(framedata->jb_obj, jbframe, now);
249                 }
250                 if (res == AST_JB_IMPL_OK) {
251                         frame = &ast_null_frame;
252                 }
253                 putframe = 1;
254         }
255
256         if (frame->frametype == AST_FRAME_NULL) {
257                 int res;
258                 long next = framedata->jb_impl->next(framedata->jb_obj);
259
260                 /* If now is earlier than the next expected output frame
261                  * from the jitterbuffer we may choose to pass on retrieving
262                  * a frame during this read iteration.  The only exception
263                  * to this rule is when an audio frame is placed into the buffer
264                  * and the time for the next frame to come out of the buffer is
265                  * at least within the timer_interval of the next output frame. By
266                  * doing this we are able to feed off the timing of the input frames
267                  * and only rely on our jitterbuffer timer when frames are dropped.
268                  * During testing, this hybrid form of timing gave more reliable results. */
269                 if (now < next) {
270                         long int diff = next - now;
271                         if (!putframe) {
272                                 return frame;
273                         } else if (diff >= framedata->timer_interval) {
274                                 return frame;
275                         }
276                 }
277
278                 res = framedata->jb_impl->get(framedata->jb_obj, &frame, now, framedata->timer_interval);
279                 switch (res) {
280                 case AST_JB_IMPL_OK:
281                         /* got it, and pass it through */
282                         break;
283                 case AST_JB_IMPL_DROP:
284                         ast_frfree(frame);
285                         frame = &ast_null_frame;
286                         break;
287                 case AST_JB_IMPL_INTERP:
288                         if (framedata->last_format.id) {
289                                 struct ast_frame tmp = { 0, };
290                                 tmp.frametype = AST_FRAME_VOICE;
291                                 ast_format_copy(&tmp.subclass.format, &framedata->last_format);
292                                 /* example: 8000hz / (1000 / 20ms) = 160 samples */
293                                 tmp.samples = ast_format_rate(&framedata->last_format) / (1000 / framedata->timer_interval);
294                                 tmp.delivery = ast_tvadd(framedata->start_tv, ast_samp2tv(next, 1000));
295                                 tmp.offset = AST_FRIENDLY_OFFSET;
296                                 tmp.src  = "func_jitterbuffer interpolation";
297                                 frame = ast_frdup(&tmp);
298                                 break;
299                         }
300                         /* else fall through */
301                 case AST_JB_IMPL_NOFRAME:
302                         frame = &ast_null_frame;
303                         break;
304                 }
305         }
306
307         return frame;
308 }
309
310 static int jb_helper(struct ast_channel *chan, const char *cmd, char *data, const char *value)
311 {
312         struct jb_framedata *framedata;
313         struct ast_datastore *datastore = NULL;
314         struct ast_framehook_interface interface = {
315                 .version = AST_FRAMEHOOK_INTERFACE_VERSION,
316                 .event_cb = hook_event_cb,
317                 .destroy_cb = hook_destroy_cb,
318         };
319         int i = 0;
320
321         if (!(framedata = ast_calloc(1, sizeof(*framedata)))) {
322                 return 0;
323         }
324
325         if (jb_framedata_init(framedata, data, value)) {
326                 jb_framedata_destroy(framedata);
327                 return 0;
328         }
329
330         interface.data = framedata;
331
332         ast_channel_lock(chan);
333         i = ast_framehook_attach(chan, &interface);
334         if (i >= 0) {
335                 int *id;
336                 if ((datastore = ast_channel_datastore_find(chan, &jb_datastore, NULL))) {
337                         id = datastore->data;
338                         ast_framehook_detach(chan, *id);
339                         ast_channel_datastore_remove(chan, datastore);
340                 }
341
342                 if (!(datastore = ast_datastore_alloc(&jb_datastore, NULL))) {
343                         ast_framehook_detach(chan, i);
344                         ast_channel_unlock(chan);
345                         return 0;
346                 }
347
348                 if (!(id = ast_calloc(1, sizeof(int)))) {
349                         ast_datastore_free(datastore);
350                         ast_framehook_detach(chan, i);
351                         ast_channel_unlock(chan);
352                         return 0;
353                 }
354
355                 *id = i; /* Store off the id. The channel is still locked so it is safe to access this ptr. */
356                 datastore->data = id;
357                 ast_channel_datastore_add(chan, datastore);
358
359                 ast_channel_set_fd(chan, AST_JITTERBUFFER_FD, framedata->timer_fd);
360         } else {
361                 jb_framedata_destroy(framedata);
362                 framedata = NULL;
363         }
364         ast_channel_unlock(chan);
365
366         return 0;
367 }
368
369 static struct ast_custom_function jb_function = {
370         .name = "JITTERBUFFER",
371         .write = jb_helper,
372 };
373
374 static int unload_module(void)
375 {
376         return ast_custom_function_unregister(&jb_function);
377 }
378
379 static int load_module(void)
380 {
381         int res = ast_custom_function_register(&jb_function);
382         return res ? AST_MODULE_LOAD_DECLINE : AST_MODULE_LOAD_SUCCESS;
383 }
384
385 AST_MODULE_INFO_STANDARD(ASTERISK_GPL_KEY, "Jitter buffer for read side of channel.");
386