astobj2: Add backtrace to log_bad_ao2.
[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_REGISTER_FILE()
35
36 #include "asterisk/module.h"
37 #include "asterisk/channel.h"
38 #include "asterisk/framehook.h"
39 #include "asterisk/frame.h"
40 #include "asterisk/pbx.h"
41 #include "asterisk/abstract_jb.h"
42 #include "asterisk/timing.h"
43 #include "asterisk/app.h"
44
45 /*** DOCUMENTATION
46         <function name="JITTERBUFFER" language="en_US">
47                 <synopsis>
48                         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.
49                 </synopsis>
50                 <syntax>
51                         <parameter name="jitterbuffer type" required="true">
52                                 <optionlist>
53                                         <option name="fixed">
54                                                 <para>Set a fixed jitterbuffer on the channel.</para>
55                                         </option>
56                                         <option name="adaptive">
57                                                 <para>Set an adaptive jitterbuffer on the channel.</para>
58                                         </option>
59                                         <option name="disabled">
60                                                 <para>Remove a previously set jitterbuffer from the channel.</para>
61                                         </option>
62                                 </optionlist>
63                         </parameter>
64                 </syntax>
65                 <description>
66                         <para>Jitterbuffers are constructed in two different ways.
67                         The first always take three arguments: <replaceable>max_size</replaceable>,
68                         <replaceable>resync_threshold</replaceable>, and <replaceable>target_extra</replaceable>.
69                         Alternatively, a single argument of <literal>default</literal> can be provided,
70                         which will construct the default jitterbuffer for the given
71                         <replaceable>jitterbuffer type</replaceable>.</para>
72                         <para>The arguments are:</para>
73                         <para><replaceable>max_size</replaceable>: Length in milliseconds of the buffer.
74                         Defaults to 200 ms.</para>
75                         <para><replaceable>resync_threshold</replaceable>: The length in milliseconds over
76                         which a timestamp difference will result in resyncing the jitterbuffer.
77                         Defaults to 1000ms.</para>
78                         <para>target_extra: This option only affects the adaptive jitterbuffer. It represents
79                         the amount time in milliseconds by which the new jitter buffer will pad its size.
80                         Defaults to 40ms.</para>
81                         <example title="Fixed with defaults" language="text">
82                         exten => 1,1,Set(JITTERBUFFER(fixed)=default)
83                         </example>
84                         <example title="Fixed with 200ms max size" language="text">
85                         exten => 1,1,Set(JITTERBUFFER(fixed)=200)
86                         </example>
87                         <example title="Fixed with 200ms max size, resync threshold 1500" language="text">
88                         exten => 1,1,Set(JITTERBUFFER(fixed)=200,1500)
89                         </example>
90                         <example title="Adaptive with defaults" language="text">
91                         exten => 1,1,Set(JITTERBUFFER(adaptive)=default)
92                         </example>
93                         <example title="Adaptive with 200ms max size, 60ms target extra" language="text">
94                         exten => 1,1,Set(JITTERBUFFER(adaptive)=200,,60)
95                         </example>
96                         <example title="Set a fixed jitterbuffer with defaults; then remove it" language="text">
97                         exten => 1,1,Set(JITTERBUFFER(fixed)=default)
98                         exten => 1,n,Set(JITTERBUFFER(disabled)=)
99                         </example>
100                         <note><para>If a channel specifies a jitterbuffer due to channel driver configuration and
101                         the JITTERBUFFER function has set a jitterbuffer for that channel, the jitterbuffer set by
102                         the JITTERBUFFER function will take priority and the jitterbuffer set by the channel
103                         configuration will not be applied.</para></note>
104                 </description>
105         </function>
106  ***/
107
108 static int jb_helper(struct ast_channel *chan, const char *cmd, char *data, const char *value)
109 {
110         struct ast_jb_conf jb_conf;
111
112         if (!chan) {
113                 ast_log(LOG_WARNING, "No channel was provided to %s function.\n", cmd);
114                 return -1;
115         }
116
117         /* Initialize and set jb_conf */
118         ast_jb_conf_default(&jb_conf);
119
120         /* Now check user options to see if any of the defaults need to change. */
121         if (!ast_strlen_zero(data)) {
122                 if (strcasecmp(data, "fixed") &&
123                                 strcasecmp(data, "adaptive") &&
124                                 strcasecmp(data, "disabled")) {
125                         ast_log(LOG_WARNING, "Unknown Jitterbuffer type %s. Failed to create jitterbuffer.\n", data);
126                         return -1;
127                 }
128                 ast_copy_string(jb_conf.impl, data, sizeof(jb_conf.impl));
129         }
130
131         if (!ast_strlen_zero(value) && strcasecmp(value, "default")) {
132                 char *parse = ast_strdupa(value);
133                 int res = 0;
134                 AST_DECLARE_APP_ARGS(args,
135                         AST_APP_ARG(max_size);
136                         AST_APP_ARG(resync_threshold);
137                         AST_APP_ARG(target_extra);
138                 );
139
140                 AST_STANDARD_APP_ARGS(args, parse);
141                 if (!ast_strlen_zero(args.max_size)) {
142                         res |= ast_jb_read_conf(&jb_conf,
143                                 "jbmaxsize",
144                                 args.max_size);
145                 }
146                 if (!ast_strlen_zero(args.resync_threshold)) {
147                         res |= ast_jb_read_conf(&jb_conf,
148                                 "jbresyncthreshold",
149                                 args.resync_threshold);
150                 }
151                 if (!ast_strlen_zero(args.target_extra)) {
152                         res |= ast_jb_read_conf(&jb_conf,
153                                 "jbtargetextra",
154                                 args.target_extra);
155                 }
156                 if (res) {
157                         ast_log(LOG_WARNING, "Invalid jitterbuffer parameters %s\n", value);
158                 }
159         }
160
161         ast_jb_create_framehook(chan, &jb_conf, 0);
162
163         return 0;
164 }
165
166
167 static struct ast_custom_function jb_function = {
168         .name = "JITTERBUFFER",
169         .write = jb_helper,
170 };
171
172 static int unload_module(void)
173 {
174         return ast_custom_function_unregister(&jb_function);
175 }
176
177 static int load_module(void)
178 {
179         int res = ast_custom_function_register(&jb_function);
180         return res ? AST_MODULE_LOAD_DECLINE : AST_MODULE_LOAD_SUCCESS;
181 }
182
183 AST_MODULE_INFO_STANDARD(ASTERISK_GPL_KEY, "Jitter buffer for read side of channel.");
184