Asterisk - The Open Source Telephony Project GIT-master-0bf3178
app_waitforsilence.c
Go to the documentation of this file.
1/*
2 * Asterisk -- An open source telephony toolkit.
3 *
4 * Copyright (C) 1999 - 2005, Digium, Inc.
5 *
6 * WaitForSilence Application by David C. Troy <dave@popvox.com>
7 * Version 1.11 2006-06-29
8 *
9 * Mark Spencer <markster@digium.com>
10 *
11 * See http://www.asterisk.org for more information about
12 * the Asterisk project. Please do not directly contact
13 * any of the maintainers of this project for assistance;
14 * the project provides a web site, mailing lists and IRC
15 * channels for your use.
16 *
17 * This program is free software, distributed under the terms of
18 * the GNU General Public License Version 2. See the LICENSE file
19 * at the top of the source tree.
20 */
21
22/*! \file
23 *
24 * \brief Wait for Silence
25 * - Waits for up to 'x' milliseconds of silence, 'y' times \n
26 *
27 * \author David C. Troy <dave@popvox.com>
28 *
29 * \brief Wait For Noise
30 * The same as Wait For Silence but listenes noise on the chennel that is above \n
31 * the pre-configured silence threshold from dsp.conf
32 *
33 * \author Philipp Skadorov <skadorov@yahoo.com>
34 *
35 * \ingroup applications
36 */
37
38/*** MODULEINFO
39 <support_level>extended</support_level>
40 ***/
41
42#include "asterisk.h"
43
44#include "asterisk/app.h"
45#include "asterisk/file.h"
46#include "asterisk/channel.h"
47#include "asterisk/pbx.h"
48#include "asterisk/dsp.h"
49#include "asterisk/module.h"
51
52/*** DOCUMENTATION
53 <application name="WaitForSilence" language="en_US">
54 <synopsis>
55 Waits for a specified amount of silence.
56 </synopsis>
57 <syntax>
58 <parameter name="silencerequired">
59 <para>If not specified, defaults to <literal>1000</literal> milliseconds.</para>
60 </parameter>
61 <parameter name="iterations">
62 <para>If not specified, defaults to <literal>1</literal>.</para>
63 </parameter>
64 <parameter name="timeout">
65 <para>Is specified only to avoid an infinite loop in cases where silence is never achieved.</para>
66 </parameter>
67 </syntax>
68 <description>
69 <para>Waits for up to <replaceable>silencerequired</replaceable> milliseconds of silence,
70 <replaceable>iterations</replaceable> times. An optional <replaceable>timeout</replaceable>
71 specified the number of seconds to return after, even if we do not receive the specified amount of silence.
72 Use <replaceable>timeout</replaceable> with caution, as it may defeat the purpose of this application, which
73 is to wait indefinitely until silence is detected on the line. This is particularly useful for reverse-911-type
74 call broadcast applications where you need to wait for an answering machine to complete its spiel before
75 playing a message.</para>
76 <para>Typically you will want to include two or more calls to WaitForSilence when dealing with an answering
77 machine; first waiting for the spiel to finish, then waiting for the beep, etc.</para>
78 <example title="Wait for half a second of silence, twice">
79 same => n,WaitForSilence(500,2)
80 </example>
81 <example title="Wait for one second of silence, once">
82 same => n,WaitForSilence(1000)
83 </example>
84 <example title="Wait for 300 ms of silence, 3 times, and returns after 10 seconds, even if no silence detected">
85 same => n,WaitForSilence(300,3,10)
86 </example>
87 <para>Sets the channel variable <variable>WAITSTATUS</variable> to one of these values:</para>
88 <variablelist>
89 <variable name="WAITSTATUS">
90 <value name="SILENCE">
91 if exited with silence detected.
92 </value>
93 <value name="TIMEOUT">
94 if exited without silence detected after timeout.
95 </value>
96 </variable>
97 </variablelist>
98 </description>
99 <see-also>
100 <ref type="application">WaitForNoise</ref>
101 </see-also>
102 </application>
103 <application name="WaitForNoise" language="en_US">
104 <synopsis>
105 Waits for a specified amount of noise.
106 </synopsis>
107 <syntax>
108 <parameter name="noiserequired">
109 <para>If not specified, defaults to <literal>1000</literal> milliseconds.</para>
110 </parameter>
111 <parameter name="iterations">
112 <para>If not specified, defaults to <literal>1</literal>.</para>
113 </parameter>
114 <parameter name="timeout">
115 <para>Is specified only to avoid an infinite loop in cases where silence is never achieved.</para>
116 </parameter>
117 </syntax>
118 <description>
119 <para>Waits for up to <replaceable>noiserequired</replaceable> milliseconds of noise,
120 <replaceable>iterations</replaceable> times. An optional <replaceable>timeout</replaceable>
121 specified the number of seconds to return after, even if we do not receive the specified amount of noise.
122 Use <replaceable>timeout</replaceable> with caution, as it may defeat the purpose of this application, which
123 is to wait indefinitely until noise is detected on the line.</para>
124 </description>
125 <see-also>
126 <ref type="application">WaitForSilence</ref>
127 </see-also>
128 </application>
129 ***/
130
131static char *app_silence = "WaitForSilence";
132static char *app_noise = "WaitForNoise";
133
134struct wait_type {
135 const char *name;
136 const char *status;
138 int (*func)(struct ast_dsp *, struct ast_frame *, int *);
139};
140
141static const struct wait_type wait_for_silence = {
142 .name = "silence",
143 .status = "SILENCE",
144 .stop_on_frame_timeout = 1,
145 .func = ast_dsp_silence,
146};
147
148static const struct wait_type wait_for_noise = {
149 .name = "noise",
150 .status = "NOISE",
151 .stop_on_frame_timeout = 0,
152 .func = ast_dsp_noise,
153};
154
155static int do_waiting(struct ast_channel *chan, int timereqd, time_t waitstart, int timeout, const struct wait_type *wait_for)
156{
157 RAII_VAR(struct ast_format *, rfmt, NULL, ao2_cleanup);
158 int res;
159 struct ast_dsp *sildet;
160
161 rfmt = ao2_bump(ast_channel_readformat(chan));
162 if ((res = ast_set_read_format(chan, ast_format_slin)) < 0) {
163 ast_log(LOG_WARNING, "Unable to set channel to linear mode, giving up\n");
164 return -1;
165 }
166
167 /* Create the silence detector */
168 if (!(sildet = ast_dsp_new())) {
169 ast_log(LOG_WARNING, "Unable to create silence detector\n");
170 return -1;
171 }
173
174 for (;;) {
175 int dsptime = 0;
176
177 res = ast_waitfor(chan, timereqd);
178
179 /* Must have gotten a hangup; let's exit */
180 if (res < 0) {
181 pbx_builtin_setvar_helper(chan, "WAITSTATUS", "HANGUP");
182 break;
183 }
184
185 /* We waited and got no frame; sounds like digital silence or a muted digital channel */
186 if (res == 0) {
187 if (wait_for->stop_on_frame_timeout) {
188 dsptime = timereqd;
189 }
190 } else {
191 /* Looks like we did get a frame, so let's check it out */
192 struct ast_frame *f = ast_read(chan);
193 if (!f) {
194 pbx_builtin_setvar_helper(chan, "WAITSTATUS", "HANGUP");
195 break;
196 }
197 if (f->frametype == AST_FRAME_VOICE) {
198 wait_for->func(sildet, f, &dsptime);
199 }
200 ast_frfree(f);
201 }
202
203 ast_debug(1, "Got %dms of %s < %dms required\n", dsptime, wait_for->name, timereqd);
204
205 if (dsptime >= timereqd) {
206 ast_verb(3, "Exiting with %dms of %s >= %dms required\n", dsptime, wait_for->name, timereqd);
207 pbx_builtin_setvar_helper(chan, "WAITSTATUS", wait_for->status);
208 ast_debug(1, "WAITSTATUS was set to %s\n", wait_for->status);
209 res = 1;
210 break;
211 }
212
213 if (timeout && difftime(time(NULL), waitstart) >= timeout) {
214 pbx_builtin_setvar_helper(chan, "WAITSTATUS", "TIMEOUT");
215 ast_debug(1, "WAITSTATUS was set to TIMEOUT\n");
216 res = 0;
217 break;
218 }
219 }
220
221 if (rfmt && ast_set_read_format(chan, rfmt)) {
222 ast_log(LOG_WARNING, "Unable to restore format %s to channel '%s'\n", ast_format_get_name(rfmt), ast_channel_name(chan));
223 }
224
225 ast_dsp_free(sildet);
226 return res;
227}
228
229static int waitfor_exec(struct ast_channel *chan, const char *data, const struct wait_type *wait_for)
230{
231 int res = 1;
232 int timereqd = 1000;
233 int timeout = 0;
234 int iterations = 1, i;
235 time_t waitstart;
236 char *parse;
237 struct ast_silence_generator *silgen = NULL;
238
240 AST_APP_ARG(timereqd);
241 AST_APP_ARG(iterations);
242 AST_APP_ARG(timeout);
243 );
244
245 parse = ast_strdupa(data);
247
248 if (!ast_strlen_zero(args.timereqd)) {
249 if (sscanf(args.timereqd, "%30d", &timereqd) != 1 || timereqd < 0) {
250 ast_log(LOG_ERROR, "Argument '%srequired' must be an integer greater than or equal to zero.\n",
251 wait_for->name);
252 return -1;
253 }
254 }
255
256 if (!ast_strlen_zero(args.iterations)) {
257 if (sscanf(args.iterations, "%30d", &iterations) != 1 || iterations < 1) {
258 ast_log(LOG_ERROR, "Argument 'iterations' must be an integer greater than 0.\n");
259 return -1;
260 }
261 }
262
263 if (!ast_strlen_zero(args.timeout)) {
264 if (sscanf(args.timeout, "%30d", &timeout) != 1 || timeout < 0) {
265 ast_log(LOG_ERROR, "Argument 'timeout' must be an integer greater than or equal to zero.\n");
266 return -1;
267 }
268 }
269
270 if (ast_channel_state(chan) != AST_STATE_UP) {
271 ast_answer(chan); /* Answer the channel */
272 }
273
274 ast_verb(3, "Waiting %d time(s) for %dms of %s with %ds timeout\n",
275 iterations, timereqd, wait_for->name, timeout);
276
279 }
280
281 time(&waitstart);
282 for (i = 0; i < iterations && res == 1; i++) {
283 res = do_waiting(chan, timereqd, waitstart, timeout, wait_for);
284 }
285
286 if (silgen) {
288 }
289
290 return res > 0 ? 0 : res;
291}
292
293static int waitforsilence_exec(struct ast_channel *chan, const char *data)
294{
295 return waitfor_exec(chan, data, &wait_for_silence);
296}
297
298static int waitfornoise_exec(struct ast_channel *chan, const char *data)
299{
300 return waitfor_exec(chan, data, &wait_for_noise);
301}
302
303static int unload_module(void)
304{
305 int res;
308
309 return res;
310}
311
312static int load_module(void)
313{
314 int res;
315
318 return res;
319}
320
AST_MODULE_INFO_STANDARD_EXTENDED(ASTERISK_GPL_KEY, "Wait For Silence/Noise")
static char * app_silence
static int waitfornoise_exec(struct ast_channel *chan, const char *data)
static const struct wait_type wait_for_silence
static int do_waiting(struct ast_channel *chan, int timereqd, time_t waitstart, int timeout, const struct wait_type *wait_for)
static int waitforsilence_exec(struct ast_channel *chan, const char *data)
static int load_module(void)
static char * app_noise
static int unload_module(void)
static int waitfor_exec(struct ast_channel *chan, const char *data, const struct wait_type *wait_for)
static const struct wait_type wait_for_noise
Asterisk main include file. File version handling, generic pbx functions.
#define ast_strdupa(s)
duplicate a string in memory from the stack
Definition: astmm.h:298
#define ast_log
Definition: astobj2.c:42
#define ao2_cleanup(obj)
Definition: astobj2.h:1934
#define ao2_bump(obj)
Bump refcount on an AO2 object by one, returning the object.
Definition: astobj2.h:480
General Asterisk PBX channel definitions.
const char * ast_channel_name(const struct ast_channel *chan)
struct ast_silence_generator * ast_channel_start_silence_generator(struct ast_channel *chan)
Starts a silence generator on the given channel.
Definition: channel.c:8186
int ast_waitfor(struct ast_channel *chan, int ms)
Wait for input on a channel.
Definition: channel.c:3181
void ast_channel_stop_silence_generator(struct ast_channel *chan, struct ast_silence_generator *state)
Stops a previously-started silence generator on the given channel.
Definition: channel.c:8232
struct ast_frame * ast_read(struct ast_channel *chan)
Reads a frame.
Definition: channel.c:4276
int ast_set_read_format(struct ast_channel *chan, struct ast_format *format)
Sets read format on channel chan.
Definition: channel.c:5781
int ast_answer(struct ast_channel *chan)
Answer a channel.
Definition: channel.c:2824
struct ast_format * ast_channel_readformat(struct ast_channel *chan)
ast_channel_state
ast_channel states
Definition: channelstate.h:35
@ AST_STATE_UP
Definition: channelstate.h:42
Convenient Signal Processing routines.
void ast_dsp_set_threshold(struct ast_dsp *dsp, int threshold)
Set the minimum average magnitude threshold to determine talking by the DSP.
Definition: dsp.c:1788
void ast_dsp_free(struct ast_dsp *dsp)
Definition: dsp.c:1783
@ THRESHOLD_SILENCE
Definition: dsp.h:73
int ast_dsp_silence(struct ast_dsp *dsp, struct ast_frame *f, int *totalsilence)
Process the audio frame for silence.
Definition: dsp.c:1488
int ast_dsp_get_threshold_from_settings(enum threshold which)
Get silence threshold from dsp.conf.
Definition: dsp.c:2009
int ast_dsp_noise(struct ast_dsp *dsp, struct ast_frame *f, int *totalnoise)
Process the audio frame for noise.
Definition: dsp.c:1493
struct ast_dsp * ast_dsp_new(void)
Allocates a new dsp, assumes 8khz for internal sample rate.
Definition: dsp.c:1758
Generic File Format Support. Should be included by clients of the file handling routines....
const char * ast_format_get_name(const struct ast_format *format)
Get the name associated with a format.
Definition: format.c:334
Media Format Cache API.
struct ast_format * ast_format_slin
Built-in cached signed linear 8kHz format.
Definition: format_cache.c:41
Application convenience functions, designed to give consistent look and feel to Asterisk apps.
#define AST_APP_ARG(name)
Define an application argument.
#define AST_DECLARE_APP_ARGS(name, arglist)
Declare a structure to hold an application's arguments.
#define AST_STANDARD_APP_ARGS(args, parse)
Performs the 'standard' argument separation process for an application.
#define ast_frfree(fr)
@ AST_FRAME_VOICE
#define ast_debug(level,...)
Log a DEBUG message.
#define LOG_ERROR
#define ast_verb(level,...)
#define LOG_WARNING
Asterisk module definitions.
#define ASTERISK_GPL_KEY
The text the key() function should return.
Definition: module.h:46
int ast_unregister_application(const char *app)
Unregister an application.
Definition: pbx_app.c:392
#define ast_register_application_xml(app, execute)
Register an application using XML documentation.
Definition: module.h:640
#define ast_opt_transmit_silence
Definition: options.h:124
Core PBX routines and definitions.
int pbx_builtin_setvar_helper(struct ast_channel *chan, const char *name, const char *value)
Add a variable to the channel variable stack, removing the most recently set value for the same name.
#define NULL
Definition: resample.c:96
static force_inline int attribute_pure ast_strlen_zero(const char *s)
Definition: strings.h:65
Main Channel structure associated with a channel.
Definition: dsp.c:407
Definition of a media format.
Definition: format.c:43
Data structure associated with a single frame of data.
union ast_frame::@226 data
enum ast_frame_type frametype
int(* func)(struct ast_dsp *, struct ast_frame *, int *)
const char * name
const char * status
const char * args
#define RAII_VAR(vartype, varname, initval, dtor)
Declare a variable that will call a destructor function when it goes out of scope.
Definition: utils.h:941