Mercurial > hg > audiostuff

comparison spandsp-0.0.6pre17/src/spandsp/dtmf.h @ 4:26cd8f1ef0b1

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
import spandsp-0.0.6pre17
author Peter Meerwald <pmeerw@cosy.sbg.ac.at>
date Fri, 25 Jun 2010 15:50:58 +0200
parents
children
comparison
equal deleted inserted replaced
3:c6c5a16ce2f2 4:26cd8f1ef0b1
1 /*
2 * SpanDSP - a series of DSP components for telephony
3 *
4 * dtmf.h - DTMF tone generation and detection.
5 *
6 * Written by Steve Underwood <steveu@coppice.org>
7 *
8 * Copyright (C) 2001, 2005 Steve Underwood
9 *
10 * All rights reserved.
11 *
12 * This program is free software; you can redistribute it and/or modify
13 * it under the terms of the GNU Lesser General Public License version 2.1,
14 * as published by the Free Software Foundation.
15 *
16 * This program is distributed in the hope that it will be useful,
17 * but WITHOUT ANY WARRANTY; without even the implied warranty of
18 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
19 * GNU Lesser General Public License for more details.
20 *
21 * You should have received a copy of the GNU Lesser General Public
22 * License along with this program; if not, write to the Free Software
23 * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
24 *
25 * $Id: dtmf.h,v 1.32 2009/02/10 13:06:47 steveu Exp $
26 */
27
28 #if !defined(_SPANDSP_DTMF_H_)
29 #define _SPANDSP_DTMF_H_
30
31 /*! \page dtmf_rx_page DTMF receiver
32 \section dtmf_rx_page_sec_1 What does it do?
33 The DTMF receiver detects the standard DTMF digits. It is compliant with
34 ITU-T Q.23, ITU-T Q.24, and the local DTMF specifications of most administrations.
35 Its passes the test suites. It also scores *very* well on the standard
36 talk-off tests.
37
38 The current design uses floating point extensively. It is not tolerant of DC.
39 It is expected that a DC restore stage will be placed before the DTMF detector.
40 Unless the dial tone filter is switched on, the detector has poor tolerance
41 of dial tone. Whether this matter depends on your application. If you are using
42 the detector in an IVR application you will need proper echo cancellation to
43 get good performance in the presence of speech prompts, so dial tone will not
44 exist. If you do need good dial tone tolerance, a dial tone filter can be
45 enabled in the detector.
46
47 The DTMF receiver's design assumes the channel is free of any DC component.
48
49 \section dtmf_rx_page_sec_2 How does it work?
50 Like most other DSP based DTMF detector's, this one uses the Goertzel algorithm
51 to look for the DTMF tones. What makes each detector design different is just how
52 that algorithm is used.
53
54 Basic DTMF specs:
55 - Minimum tone on = 40ms
56 - Minimum tone off = 50ms
57 - Maximum digit rate = 10 per second
58 - Normal twist <= 8dB accepted
59 - Reverse twist <= 4dB accepted
60 - S/N >= 15dB will detect OK
61 - Attenuation <= 26dB will detect OK
62 - Frequency tolerance +- 1.5% will detect, +-3.5% will reject
63
64 TODO:
65 */
66
67 /*! \page dtmf_tx_page DTMF tone generation
68 \section dtmf_tx_page_sec_1 What does it do?
69
70 The DTMF tone generation module provides for the generation of the
71 repertoire of 16 DTMF dual tones.
72
73 \section dtmf_tx_page_sec_2 How does it work?
74 */
75
76 #define MAX_DTMF_DIGITS 128
77
78 typedef void (*digits_rx_callback_t)(void *user_data, const char *digits, int len);
79
80 /*!
81 DTMF generator state descriptor. This defines the state of a single
82 working instance of a DTMF generator.
83 */
84 typedef struct dtmf_tx_state_s dtmf_tx_state_t;
85
86 /*!
87 DTMF digit detector descriptor.
88 */
89 typedef struct dtmf_rx_state_s dtmf_rx_state_t;
90
91 #if defined(__cplusplus)
92 extern "C"
93 {
94 #endif
95
96 /*! \brief Generate a buffer of DTMF tones.
97 \param s The DTMF generator context.
98 \param amp The buffer for the generated signal.
99 \param max_samples The required number of generated samples.
100 \return The number of samples actually generated. This may be less than
101 max_samples if the input buffer empties. */
102 SPAN_DECLARE(int) dtmf_tx(dtmf_tx_state_t *s, int16_t amp[], int max_samples);
103
104 /*! \brief Put a string of digits in a DTMF generator's input buffer.
105 \param s The DTMF generator context.
106 \param digits The string of digits to be added.
107 \param len The length of the string of digits. If negative, the string is
108 assumed to be a NULL terminated string.
109 \return The number of digits actually added. This may be less than the
110 length of the digit string, if the buffer fills up. */
111 SPAN_DECLARE(int) dtmf_tx_put(dtmf_tx_state_t *s, const char *digits, int len);
112
113 /*! \brief Change the transmit level for a DTMF tone generator context.
114 \param s The DTMF generator context.
115 \param level The level of the low tone, in dBm0.
116 \param twist The twist, in dB. */
117 SPAN_DECLARE(void) dtmf_tx_set_level(dtmf_tx_state_t *s, int level, int twist);
118
119 /*! \brief Change the transmit on and off time for a DTMF tone generator context.
120 \param s The DTMF generator context.
121 \param on-time The on time, in ms.
122 \param off_time The off time, in ms. */
123 SPAN_DECLARE(void) dtmf_tx_set_timing(dtmf_tx_state_t *s, int on_time, int off_time);
124
125 /*! \brief Initialise a DTMF tone generator context.
126 \param s The DTMF generator context.
127 \return A pointer to the DTMF generator context. */
128 SPAN_DECLARE(dtmf_tx_state_t *) dtmf_tx_init(dtmf_tx_state_t *s);
129
130 /*! \brief Release a DTMF tone generator context.
131 \param s The DTMF tone generator context.
132 \return 0 for OK, else -1. */
133 SPAN_DECLARE(int) dtmf_tx_release(dtmf_tx_state_t *s);
134
135 /*! \brief Free a DTMF tone generator context.
136 \param s The DTMF tone generator context.
137 \return 0 for OK, else -1. */
138 SPAN_DECLARE(int) dtmf_tx_free(dtmf_tx_state_t *s);
139
140 /*! Set a optional realtime callback for a DTMF receiver context. This function
141 is called immediately a confirmed state change occurs in the received DTMF. It
142 is called with the ASCII value for a DTMF tone pair, or zero to indicate no tone
143 is being received.
144 \brief Set a realtime callback for a DTMF receiver context.
145 \param s The DTMF receiver context.
146 \param callback Callback routine used to report the start and end of digits.
147 \param user_data An opaque pointer which is associated with the context,
148 and supplied in callbacks. */
149 SPAN_DECLARE(void) dtmf_rx_set_realtime_callback(dtmf_rx_state_t *s,
150 tone_report_func_t callback,
151 void *user_data);
152
153 /*! \brief Adjust a DTMF receiver context.
154 \param s The DTMF receiver context.
155 \param filter_dialtone TRUE to enable filtering of dialtone, FALSE
156 to disable, < 0 to leave unchanged.
157 \param twist Acceptable twist, in dB. < 0 to leave unchanged.
158 \param reverse_twist Acceptable reverse twist, in dB. < 0 to leave unchanged.
159 \param threshold The minimum acceptable tone level for detection, in dBm0.
160 <= -99 to leave unchanged. */
161 SPAN_DECLARE(void) dtmf_rx_parms(dtmf_rx_state_t *s,
162 int filter_dialtone,
163 int twist,
164 int reverse_twist,
165 int threshold);
166
167 /*! Process a block of received DTMF audio samples.
168 \brief Process a block of received DTMF audio samples.
169 \param s The DTMF receiver context.
170 \param amp The audio sample buffer.
171 \param samples The number of samples in the buffer.
172 \return The number of samples unprocessed. */
173 SPAN_DECLARE(int) dtmf_rx(dtmf_rx_state_t *s, const int16_t amp[], int samples);
174
175 /*! Get the status of DTMF detection during processing of the last audio
176 chunk.
177 \brief Get the status of DTMF detection during processing of the last
178 audio chunk.
179 \param s The DTMF receiver context.
180 \return The current digit status. Either 'x' for a "maybe" condition, or the
181 digit being detected. */
182 SPAN_DECLARE(int) dtmf_rx_status(dtmf_rx_state_t *s);
183
184 /*! \brief Get a string of digits from a DTMF receiver's output buffer.
185 \param s The DTMF receiver context.
186 \param digits The buffer for the received digits.
187 \param max The maximum number of digits to be returned,
188 \return The number of digits actually returned. */
189 SPAN_DECLARE(size_t) dtmf_rx_get(dtmf_rx_state_t *s, char *digits, int max);
190
191 /*! \brief Initialise a DTMF receiver context.
192 \param s The DTMF receiver context.
193 \param callback An optional callback routine, used to report received digits. If
194 no callback routine is set, digits may be collected, using the dtmf_rx_get()
195 function.
196 \param user_data An opaque pointer which is associated with the context,
197 and supplied in callbacks.
198 \return A pointer to the DTMF receiver context. */
199 SPAN_DECLARE(dtmf_rx_state_t *) dtmf_rx_init(dtmf_rx_state_t *s,
200 digits_rx_callback_t callback,
201 void *user_data);
202
203 /*! \brief Release a DTMF receiver context.
204 \param s The DTMF receiver context.
205 \return 0 for OK, else -1. */
206 SPAN_DECLARE(int) dtmf_rx_release(dtmf_rx_state_t *s);
207
208 /*! \brief Free a DTMF receiver context.
209 \param s The DTMF receiver context.
210 \return 0 for OK, else -1. */
211 SPAN_DECLARE(int) dtmf_rx_free(dtmf_rx_state_t *s);
212
213 #if defined(__cplusplus)
214 }
215 #endif
216
217 #endif
218 /*- End of file ------------------------------------------------------------*/

Repositories maintained by Peter Meerwald, pmeerw@pmeerw.net.