Asterisk - The Open Source Telephony Project  18.5.0
func_jitterbuffer.c
Go to the documentation of this file.
1 /*
2  * Asterisk -- An open source telephony toolkit.
3  *
4  * Copyright (C) 2011, Digium, Inc.
5  *
6  * David Vossel <[email protected]>
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 <[email protected]>
24  *
25  * \ingroup functions
26  */
27 
28 /*** MODULEINFO
29  <support_level>core</support_level>
30  ***/
31 
32 #include "asterisk.h"
33 
34 #include "asterisk/module.h"
35 #include "asterisk/channel.h"
36 #include "asterisk/framehook.h"
37 #include "asterisk/frame.h"
38 #include "asterisk/pbx.h"
39 #include "asterisk/abstract_jb.h"
40 #include "asterisk/timing.h"
41 #include "asterisk/app.h"
42 
43 /*** DOCUMENTATION
44  <function name="JITTERBUFFER" language="en_US">
45  <synopsis>
46  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.
47  </synopsis>
48  <syntax>
49  <parameter name="jitterbuffer type" required="true">
50  <optionlist>
51  <option name="fixed">
52  <para>Set a fixed jitterbuffer on the channel.</para>
53  </option>
54  <option name="adaptive">
55  <para>Set an adaptive jitterbuffer on the channel.</para>
56  </option>
57  <option name="disabled">
58  <para>Remove a previously set jitterbuffer from the channel.</para>
59  </option>
60  </optionlist>
61  </parameter>
62  </syntax>
63  <description>
64  <para>Jitterbuffers are constructed in two different ways.
65  The first always take four arguments: <replaceable>max_size</replaceable>,
66  <replaceable>resync_threshold</replaceable>, <replaceable>target_extra</replaceable>,
67  and <replaceable>sync_video</replaceable>.
68  Alternatively, a single argument of <literal>default</literal> can be provided,
69  which will construct the default jitterbuffer for the given
70  <replaceable>jitterbuffer type</replaceable>.</para>
71  <para>The arguments are:</para>
72  <para><replaceable>max_size</replaceable>: Length in milliseconds of the buffer.
73  Defaults to 200 ms.</para>
74  <para><replaceable>resync_threshold</replaceable>: The length in milliseconds over
75  which a timestamp difference will result in resyncing the jitterbuffer.
76  Defaults to 1000ms.</para>
77  <para>target_extra: This option only affects the adaptive jitterbuffer. It represents
78  the amount time in milliseconds by which the new jitter buffer will pad its size.
79  Defaults to 40ms.</para>
80  <para>sync_video: This option enables video synchronization with the audio stream. It can be
81  turned on and off. Defaults to off.</para>
82  <example title="Fixed with defaults" language="text">
83  exten => 1,1,Set(JITTERBUFFER(fixed)=default)
84  </example>
85  <example title="Fixed with 200ms max size" language="text">
86  exten => 1,1,Set(JITTERBUFFER(fixed)=200)
87  </example>
88  <example title="Fixed with 200ms max size and video sync support" language="text">
89  exten => 1,1,Set(JITTERBUFFER(fixed)=200,,,yes)
90  </example>
91  <example title="Fixed with 200ms max size, resync threshold 1500" language="text">
92  exten => 1,1,Set(JITTERBUFFER(fixed)=200,1500)
93  </example>
94  <example title="Adaptive with defaults" language="text">
95  exten => 1,1,Set(JITTERBUFFER(adaptive)=default)
96  </example>
97  <example title="Adaptive with 200ms max size, 60ms target extra" language="text">
98  exten => 1,1,Set(JITTERBUFFER(adaptive)=200,,60)
99  </example>
100  <example title="Adaptive with 200ms max size and video sync support" language="text">
101  exten => 1,1,Set(JITTERBUFFER(adaptive)=200,,,yes)
102  </example>
103  <example title="Set a fixed jitterbuffer with defaults; then remove it" language="text">
104  exten => 1,1,Set(JITTERBUFFER(fixed)=default)
105  exten => 1,n,Set(JITTERBUFFER(disabled)=)
106  </example>
107  <note><para>If a channel specifies a jitterbuffer due to channel driver configuration and
108  the JITTERBUFFER function has set a jitterbuffer for that channel, the jitterbuffer set by
109  the JITTERBUFFER function will take priority and the jitterbuffer set by the channel
110  configuration will not be applied.</para></note>
111  </description>
112  </function>
113  ***/
114 
115 static int jb_helper(struct ast_channel *chan, const char *cmd, char *data, const char *value)
116 {
117  struct ast_jb_conf jb_conf;
118 
119  if (!chan) {
120  ast_log(LOG_WARNING, "No channel was provided to %s function.\n", cmd);
121  return -1;
122  }
123 
124  /* Initialize and set jb_conf */
125  ast_jb_conf_default(&jb_conf);
126 
127  /* Now check user options to see if any of the defaults need to change. */
128  if (!ast_strlen_zero(data)) {
129  if (strcasecmp(data, "fixed") &&
130  strcasecmp(data, "adaptive") &&
131  strcasecmp(data, "disabled")) {
132  ast_log(LOG_WARNING, "Unknown Jitterbuffer type %s. Failed to create jitterbuffer.\n", data);
133  return -1;
134  }
135  ast_copy_string(jb_conf.impl, data, sizeof(jb_conf.impl));
136  }
137 
138  if (!ast_strlen_zero(value) && strcasecmp(value, "default")) {
139  char *parse = ast_strdupa(value);
140  int res = 0;
145  AST_APP_ARG(sync_video);
146  );
147 
148  AST_STANDARD_APP_ARGS(args, parse);
149  if (!ast_strlen_zero(args.max_size)) {
150  res |= ast_jb_read_conf(&jb_conf,
151  "jbmaxsize",
152  args.max_size);
153  }
154  if (!ast_strlen_zero(args.resync_threshold)) {
155  res |= ast_jb_read_conf(&jb_conf,
156  "jbresyncthreshold",
157  args.resync_threshold);
158  }
159  if (!ast_strlen_zero(args.target_extra)) {
160  res |= ast_jb_read_conf(&jb_conf,
161  "jbtargetextra",
162  args.target_extra);
163  }
164  if (!ast_strlen_zero(args.sync_video)) {
165  res |= ast_jb_read_conf(&jb_conf,
166  "jbsyncvideo",
167  args.sync_video);
168  }
169  if (res) {
170  ast_log(LOG_WARNING, "Invalid jitterbuffer parameters %s\n", value);
171  }
172  }
173 
174  ast_jb_create_framehook(chan, &jb_conf, 0);
175 
176  return 0;
177 }
178 
179 
181  .name = "JITTERBUFFER",
182  .write = jb_helper,
183 };
184 
185 static int unload_module(void)
186 {
187  return ast_custom_function_unregister(&jb_function);
188 }
189 
190 static int load_module(void)
191 {
192  int res = ast_custom_function_register(&jb_function);
194 }
195 
196 AST_MODULE_INFO_STANDARD(ASTERISK_GPL_KEY, "Jitter buffer for read side of channel.");
const char * name
Definition: pbx.h:119
Main Channel structure associated with a channel.
#define AST_MODULE_INFO_STANDARD(keystr, desc)
Definition: module.h:567
Asterisk main include file. File version handling, generic pbx functions.
void ast_jb_create_framehook(struct ast_channel *chan, struct ast_jb_conf *jb_conf, int prefer_existing)
Applies a jitterbuffer framehook to a channel based on a provided jitterbuffer config.
Definition: abstract_jb.c:1257
#define AST_STANDARD_APP_ARGS(args, parse)
Performs the &#39;standard&#39; argument separation process for an application.
static int unload_module(void)
#define LOG_WARNING
Definition: logger.h:274
static int jb_helper(struct ast_channel *chan, const char *cmd, char *data, const char *value)
int ast_jb_read_conf(struct ast_jb_conf *conf, const char *varname, const char *value)
Sets jitterbuffer configuration property.
Definition: abstract_jb.c:545
static int load_module(void)
const char * args
Common implementation-independent jitterbuffer stuff.
int value
Definition: syslog.c:37
int ast_custom_function_unregister(struct ast_custom_function *acf)
Unregister a custom function.
#define ast_strlen_zero(foo)
Definition: strings.h:52
void ast_jb_conf_default(struct ast_jb_conf *conf)
Sets the contents of an ast_jb_conf struct to the default jitterbuffer settings.
Definition: abstract_jb.c:890
long resync_threshold
Resynchronization threshold of the jitterbuffer implementation.
Definition: abstract_jb.h:76
#define ast_log
Definition: astobj2.c:42
General Asterisk PBX channel definitions.
Data structure associated with a custom dialplan function.
Definition: pbx.h:118
Asterisk internal frame definitions.
#define ast_strdupa(s)
duplicate a string in memory from the stack
Definition: astmm.h:300
long target_extra
amount of additional jitterbuffer adjustment
Definition: abstract_jb.h:80
char impl[AST_JB_IMPL_NAME_SIZE]
Name of the jitterbuffer implementation to be used.
Definition: abstract_jb.h:78
Core PBX routines and definitions.
static void parse(struct mgcp_request *req)
Definition: chan_mgcp.c:1872
Module has failed to load, may be in an inconsistent state.
Definition: module.h:78
FrameHook Architecture.
void ast_copy_string(char *dst, const char *src, size_t size)
Size-limited null-terminating string copy.
Definition: strings.h:401
#define ASTERISK_GPL_KEY
The text the key() function should return.
Definition: module.h:46
Asterisk module definitions.
long max_size
Max size of the jitterbuffer implementation.
Definition: abstract_jb.h:74
#define AST_DECLARE_APP_ARGS(name, arglist)
Declare a structure to hold an application&#39;s arguments.
Application convenience functions, designed to give consistent look and feel to Asterisk apps...
General jitterbuffer configuration.
Definition: abstract_jb.h:69
#define ast_custom_function_register(acf)
Register a custom function.
Definition: pbx.h:1508
Timing source management.
#define AST_APP_ARG(name)
Define an application argument.
static struct ast_custom_function jb_function