spandsp 3.0.0
dtmf.h
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
26#if !defined(_SPANDSP_DTMF_H_)
27#define _SPANDSP_DTMF_H_
28
29/*! \page dtmf_rx_page DTMF receiver
30\section dtmf_rx_page_sec_1 What does it do?
31The DTMF receiver detects the standard DTMF digits. It is compliant with
32ITU-T Q.23, ITU-T Q.24, and the local DTMF specifications of most administrations.
33Its passes the test suites. It also scores *very* well on the standard
34talk-off tests.
35
36The current design uses floating point extensively. It is not tolerant of DC.
37It is expected that a DC restore stage will be placed before the DTMF detector.
38Unless the dial tone filter is switched on, the detector has poor tolerance
39of dial tone. Whether this matter depends on your application. If you are using
40the detector in an IVR application you will need proper echo cancellation to
41get good performance in the presence of speech prompts, so dial tone will not
42exist. If you do need good dial tone tolerance, a dial tone filter can be
43enabled in the detector.
44
45The DTMF receiver's design assumes the channel is free of any DC component.
46
47\section dtmf_rx_page_sec_2 How does it work?
48Like most other DSP based DTMF detector's, this one uses the Goertzel algorithm
49to look for the DTMF tones. What makes each detector design different is just how
50that algorithm is used.
51
52Basic DTMF specs:
53 - Minimum tone on = 40ms
54 - Minimum tone off = 50ms
55 - Maximum digit rate = 10 per second
56 - Normal twist <= 8dB accepted
57 - Reverse twist <= 4dB accepted
58 - S/N >= 15dB will detect OK
59 - Attenuation <= 26dB will detect OK
60 - Frequency tolerance +- 1.5% will detect, +-3.5% will reject
61
62TODO:
63*/
64
65/*! \page dtmf_tx_page DTMF tone generation
66\section dtmf_tx_page_sec_1 What does it do?
67
68The DTMF tone generation module provides for the generation of the
69repertoire of 16 DTMF dual tones.
70
71\section dtmf_tx_page_sec_2 How does it work?
72*/
73
74#define MAX_DTMF_DIGITS 128
75
76typedef void (*digits_rx_callback_t)(void *user_data, const char *digits, int len);
77typedef void (*digits_tx_callback_t)(void *user_data);
78
79/*!
80 DTMF generator state descriptor. This defines the state of a single
81 working instance of a DTMF generator.
82*/
83typedef struct dtmf_tx_state_s dtmf_tx_state_t;
84
85/*!
86 DTMF digit detector descriptor.
87*/
88typedef struct dtmf_rx_state_s dtmf_rx_state_t;
89
90#if defined(__cplusplus)
91extern "C"
92{
93#endif
94
95/*! \brief Generate a buffer of DTMF tones.
96 \param s The DTMF generator context.
97 \param amp The buffer for the generated signal.
98 \param max_samples The required number of generated samples.
99 \return The number of samples actually generated. This may be less than
100 max_samples if the input buffer empties. */
101SPAN_DECLARE(int) dtmf_tx(dtmf_tx_state_t *s, int16_t amp[], int max_samples);
102
103/*! \brief Put a string of digits in a DTMF generator's input buffer.
104 \param s The DTMF generator context.
105 \param digits The string of digits to be added.
106 \param len The length of the string of digits. If negative, the string is
107 assumed to be a NULL terminated string.
108 \return The number of digits actually added. This may be less than the
109 length of the digit string, if the buffer fills up. */
110SPAN_DECLARE(int) dtmf_tx_put(dtmf_tx_state_t *s, const char *digits, int len);
111
112/*! \brief Change the transmit level for a DTMF tone generator context.
113 \param s The DTMF generator context.
114 \param level The level of the low tone, in dBm0.
115 \param twist The twist, in dB. */
116SPAN_DECLARE(void) dtmf_tx_set_level(dtmf_tx_state_t *s, int level, int twist);
117
118/*! \brief Change the transmit on and off time for a DTMF tone generator context.
119 \param s The DTMF generator context.
120 \param on-time The on time, in ms.
121 \param off_time The off time, in ms. */
122SPAN_DECLARE(void) dtmf_tx_set_timing(dtmf_tx_state_t *s, int on_time, int off_time);
123
124/*! \brief Initialise a DTMF tone generator context.
125 \param s The DTMF generator context.
126 \param callback An optional callback routine, used to get more digits.
127 \param user_data An opaque pointer which is associated with the context,
128 and supplied in callbacks.
129 \return A pointer to the DTMF generator context. */
130SPAN_DECLARE(dtmf_tx_state_t *) dtmf_tx_init(dtmf_tx_state_t *s,
131 digits_tx_callback_t callback,
132 void *user_data);
133
134/*! \brief Release a DTMF tone generator context.
135 \param s The DTMF tone generator context.
136 \return 0 for OK, else -1. */
137SPAN_DECLARE(int) dtmf_tx_release(dtmf_tx_state_t *s);
138
139/*! \brief Free a DTMF tone generator context.
140 \param s The DTMF tone generator context.
141 \return 0 for OK, else -1. */
142SPAN_DECLARE(int) dtmf_tx_free(dtmf_tx_state_t *s);
143
144/*! Set a optional realtime callback for a DTMF receiver context. This function
145 is called immediately a confirmed state change occurs in the received DTMF. It
146 is called with the ASCII value for a DTMF tone pair, or zero to indicate no tone
147 is being received.
148 \brief Set a realtime callback for a DTMF receiver context.
149 \param s The DTMF receiver context.
150 \param callback Callback routine used to report the start and end of digits.
151 \param user_data An opaque pointer which is associated with the context,
152 and supplied in callbacks. */
153SPAN_DECLARE(void) dtmf_rx_set_realtime_callback(dtmf_rx_state_t *s,
154 span_tone_report_func_t callback,
155 void *user_data);
156
157/*! \brief Adjust a DTMF receiver context.
158 \param s The DTMF receiver context.
159 \param filter_dialtone True to enable filtering of dialtone, false
160 to disable, < 0 to leave unchanged.
161 \param twist Acceptable twist, in dB. < 0.0 to leave unchanged.
162 \param reverse_twist Acceptable reverse twist, in dB. < 0.0 to leave unchanged.
163 \param threshold The minimum acceptable tone level for detection, in dBm0.
164 <= -99.0 to leave unchanged. */
165SPAN_DECLARE(void) dtmf_rx_parms(dtmf_rx_state_t *s,
166 int filter_dialtone,
167 float twist,
168 float reverse_twist,
169 float threshold);
170
171/*! Process a block of received DTMF audio samples.
172 \brief Process a block of received DTMF audio samples.
173 \param s The DTMF receiver context.
174 \param amp The audio sample buffer.
175 \param samples The number of samples in the buffer.
176 \return The number of samples unprocessed. */
177SPAN_DECLARE(int) dtmf_rx(dtmf_rx_state_t *s, const int16_t amp[], int samples);
178
179/*! Fake processing of a missing block of received DTMF audio samples.
180 (e.g due to packet loss).
181 \brief Fake processing of a missing block of received DTMF audio samples.
182 \param s The DTMF receiver context.
183 \param len The number of samples to fake.
184 \return The number of samples unprocessed. */
185SPAN_DECLARE(int) dtmf_rx_fillin(dtmf_rx_state_t *s, int samples);
186
187/*! Get the status of DTMF detection during processing of the last audio
188 chunk.
189 \brief Get the status of DTMF detection during processing of the last
190 audio chunk.
191 \param s The DTMF receiver context.
192 \return The current digit status. Either 'x' for a "maybe" condition, or the
193 digit being detected. */
194SPAN_DECLARE(int) dtmf_rx_status(dtmf_rx_state_t *s);
195
196/*! \brief Get a string of digits from a DTMF receiver's output buffer.
197 \param s The DTMF receiver context.
198 \param digits The buffer for the received digits.
199 \param max The maximum number of digits to be returned,
200 \return The number of digits actually returned. */
201SPAN_DECLARE(size_t) dtmf_rx_get(dtmf_rx_state_t *s, char *digits, int max);
202
203/*! \brief Get the logging context associated with a DTMF receiver context.
204 \param s The DTMF receiver context.
205 \return A pointer to the logging context */
206SPAN_DECLARE(logging_state_t *) dtmf_rx_get_logging_state(dtmf_rx_state_t *s);
207
208/*! \brief Initialise a DTMF receiver context.
209 \param s The DTMF receiver context.
210 \param callback An optional callback routine, used to report received digits. If
211 no callback routine is set, digits may be collected, using the dtmf_rx_get()
212 function.
213 \param user_data An opaque pointer which is associated with the context,
214 and supplied in callbacks.
215 \return A pointer to the DTMF receiver context. */
216SPAN_DECLARE(dtmf_rx_state_t *) dtmf_rx_init(dtmf_rx_state_t *s,
217 digits_rx_callback_t callback,
218 void *user_data);
219
220/*! \brief Release a DTMF receiver context.
221 \param s The DTMF receiver context.
222 \return 0 for OK, else -1. */
223SPAN_DECLARE(int) dtmf_rx_release(dtmf_rx_state_t *s);
224
225/*! \brief Free a DTMF receiver context.
226 \param s The DTMF receiver context.
227 \return 0 for OK, else -1. */
228SPAN_DECLARE(int) dtmf_rx_free(dtmf_rx_state_t *s);
229
230#if defined(__cplusplus)
231}
232#endif
233
234#endif
235/*- End of file ------------------------------------------------------------*/
void dtmf_tx_set_level(dtmf_tx_state_t *s, int level, int twist)
Change the transmit level for a DTMF tone generator context.
Definition dtmf.c:622
int dtmf_tx_free(dtmf_tx_state_t *s)
Free a DTMF tone generator context.
Definition dtmf.c:669
size_t dtmf_rx_get(dtmf_rx_state_t *s, char *buf, int max)
Get a string of digits from a DTMF receiver's output buffer.
Definition dtmf.c:394
logging_state_t * dtmf_rx_get_logging_state(dtmf_rx_state_t *s)
Get the logging context associated with a DTMF receiver context.
Definition dtmf.c:448
int dtmf_tx(dtmf_tx_state_t *s, int16_t amp[], int max_samples)
Generate a buffer of DTMF tones.
Definition dtmf.c:551
void dtmf_rx_set_realtime_callback(dtmf_rx_state_t *s, span_tone_report_func_t callback, void *user_data)
Set a realtime callback for a DTMF receiver context.
Definition dtmf.c:411
dtmf_tx_state_t * dtmf_tx_init(dtmf_tx_state_t *s, digits_tx_callback_t callback, void *user_data)
Initialise a DTMF tone generator context.
Definition dtmf.c:636
int dtmf_rx_status(dtmf_rx_state_t *s)
Get the status of DTMF detection during processing of the last audio chunk.
Definition dtmf.c:382
dtmf_rx_state_t * dtmf_rx_init(dtmf_rx_state_t *s, digits_rx_callback_t callback, void *user_data)
Initialise a DTMF receiver context.
Definition dtmf.c:454
int dtmf_rx_free(dtmf_rx_state_t *s)
Free a DTMF receiver context.
Definition dtmf.c:514
int dtmf_rx(dtmf_rx_state_t *s, const int16_t amp[], int samples)
Process a block of received DTMF audio samples.
Definition dtmf.c:132
int dtmf_rx_release(dtmf_rx_state_t *s)
Release a DTMF receiver context.
Definition dtmf.c:508
int dtmf_tx_put(dtmf_tx_state_t *s, const char *digits, int len)
Put a string of digits in a DTMF generator's input buffer.
Definition dtmf.c:598
int dtmf_tx_release(dtmf_tx_state_t *s)
Release a DTMF tone generator context.
Definition dtmf.c:662
int dtmf_rx_fillin(dtmf_rx_state_t *s, int samples)
Fake processing of a missing block of received DTMF audio samples.
Definition dtmf.c:363
void dtmf_tx_set_timing(dtmf_tx_state_t *s, int on_time, int off_time)
Change the transmit on and off time for a DTMF tone generator context.
Definition dtmf.c:629
void dtmf_rx_parms(dtmf_rx_state_t *s, int filter_dialtone, float twist, float reverse_twist, float threshold)
Adjust a DTMF receiver context.
Definition dtmf.c:421
struct logging_state_s logging_state_t
Definition logging.h:72
Definition private/dtmf.h:55
float reverse_twist
Definition private/dtmf.h:87
float threshold
Definition private/dtmf.h:89
bool filter_dialtone
Definition private/dtmf.h:65
char digits[MAX_DTMF_DIGITS+1]
Definition private/dtmf.h:112
Definition private/dtmf.h:34