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