dtmf.h

00001 /*
00002  * SpanDSP - a series of DSP components for telephony
00003  *
00004  * dtmf.h - DTMF tone generation and detection.
00005  *
00006  * Written by Steve Underwood <steveu@coppice.org>
00007  *
00008  * Copyright (C) 2001, 2005 Steve Underwood
00009  *
00010  * All rights reserved.
00011  *
00012  * This program is free software; you can redistribute it and/or modify
00013  * it under the terms of the GNU Lesser General Public License version 2.1,
00014  * as published by the Free Software Foundation.
00015  *
00016  * This program is distributed in the hope that it will be useful,
00017  * but WITHOUT ANY WARRANTY; without even the implied warranty of
00018  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
00019  * GNU Lesser General Public License for more details.
00020  *
00021  * You should have received a copy of the GNU Lesser General Public
00022  * License along with this program; if not, write to the Free Software
00023  * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
00024  */
00025 
00026 #if !defined(_SPANDSP_DTMF_H_)
00027 #define _SPANDSP_DTMF_H_
00028 
00029 /*! \page dtmf_rx_page DTMF receiver
00030 \section dtmf_rx_page_sec_1 What does it do?
00031 The DTMF receiver detects the standard DTMF digits. It is compliant with
00032 ITU-T Q.23, ITU-T Q.24, and the local DTMF specifications of most administrations.
00033 Its passes the test suites. It also scores *very* well on the standard
00034 talk-off tests. 
00035 
00036 The current design uses floating point extensively. It is not tolerant of DC.
00037 It is expected that a DC restore stage will be placed before the DTMF detector.
00038 Unless the dial tone filter is switched on, the detector has poor tolerance
00039 of dial tone. Whether this matter depends on your application. If you are using
00040 the detector in an IVR application you will need proper echo cancellation to
00041 get good performance in the presence of speech prompts, so dial tone will not
00042 exist. If you do need good dial tone tolerance, a dial tone filter can be
00043 enabled in the detector.
00044 
00045 The DTMF receiver's design assumes the channel is free of any DC component.
00046 
00047 \section dtmf_rx_page_sec_2 How does it work?
00048 Like most other DSP based DTMF detector's, this one uses the Goertzel algorithm
00049 to look for the DTMF tones. What makes each detector design different is just how
00050 that algorithm is used.
00051 
00052 Basic DTMF specs:
00053     - Minimum tone on = 40ms
00054     - Minimum tone off = 50ms
00055     - Maximum digit rate = 10 per second
00056     - Normal twist <= 8dB accepted
00057     - Reverse twist <= 4dB accepted
00058     - S/N >= 15dB will detect OK
00059     - Attenuation <= 26dB will detect OK
00060     - Frequency tolerance +- 1.5% will detect, +-3.5% will reject
00061 
00062 TODO:
00063 */
00064 
00065 /*! \page dtmf_tx_page DTMF tone generation
00066 \section dtmf_tx_page_sec_1 What does it do?
00067 
00068 The DTMF tone generation module provides for the generation of the
00069 repertoire of 16 DTMF dual tones. 
00070 
00071 \section dtmf_tx_page_sec_2 How does it work?
00072 */
00073 
00074 #define MAX_DTMF_DIGITS 128
00075 
00076 typedef void (*digits_rx_callback_t)(void *user_data, const char *digits, int len);
00077 
00078 /*!
00079     DTMF generator state descriptor. This defines the state of a single
00080     working instance of a DTMF generator.
00081 */
00082 typedef struct dtmf_tx_state_s dtmf_tx_state_t;
00083 
00084 /*!
00085     DTMF digit detector descriptor.
00086 */
00087 typedef struct dtmf_rx_state_s dtmf_rx_state_t;
00088 
00089 #if defined(__cplusplus)
00090 extern "C"
00091 {
00092 #endif
00093 
00094 /*! \brief Generate a buffer of DTMF tones.
00095     \param s The DTMF generator context.
00096     \param amp The buffer for the generated signal.
00097     \param max_samples The required number of generated samples.
00098     \return The number of samples actually generated. This may be less than 
00099             max_samples if the input buffer empties. */
00100 SPAN_DECLARE(int) dtmf_tx(dtmf_tx_state_t *s, int16_t amp[], int max_samples);
00101 
00102 /*! \brief Put a string of digits in a DTMF generator's input buffer.
00103     \param s The DTMF generator context.
00104     \param digits The string of digits to be added.
00105     \param len The length of the string of digits. If negative, the string is
00106            assumed to be a NULL terminated string.
00107     \return The number of digits actually added. This may be less than the
00108             length of the digit string, if the buffer fills up. */
00109 SPAN_DECLARE(int) dtmf_tx_put(dtmf_tx_state_t *s, const char *digits, int len);
00110 
00111 /*! \brief Change the transmit level for a DTMF tone generator context.
00112     \param s The DTMF generator context.
00113     \param level The level of the low tone, in dBm0.
00114     \param twist The twist, in dB. */
00115 SPAN_DECLARE(void) dtmf_tx_set_level(dtmf_tx_state_t *s, int level, int twist);
00116 
00117 /*! \brief Change the transmit on and off time for a DTMF tone generator context.
00118     \param s The DTMF generator context.
00119     \param on-time The on time, in ms.
00120     \param off_time The off time, in ms. */
00121 SPAN_DECLARE(void) dtmf_tx_set_timing(dtmf_tx_state_t *s, int on_time, int off_time);
00122 
00123 /*! \brief Initialise a DTMF tone generator context.
00124     \param s The DTMF generator context.
00125     \return A pointer to the DTMF generator context. */
00126 SPAN_DECLARE(dtmf_tx_state_t *) dtmf_tx_init(dtmf_tx_state_t *s);
00127 
00128 /*! \brief Release a DTMF tone generator context.
00129     \param s The DTMF tone generator context.
00130     \return 0 for OK, else -1. */
00131 SPAN_DECLARE(int) dtmf_tx_release(dtmf_tx_state_t *s);
00132 
00133 /*! \brief Free a DTMF tone generator context.
00134     \param s The DTMF tone generator context.
00135     \return 0 for OK, else -1. */
00136 SPAN_DECLARE(int) dtmf_tx_free(dtmf_tx_state_t *s);
00137 
00138 /*! Set a optional realtime callback for a DTMF receiver context. This function
00139     is called immediately a confirmed state change occurs in the received DTMF. It
00140     is called with the ASCII value for a DTMF tone pair, or zero to indicate no tone
00141     is being received.
00142     \brief Set a realtime callback for a DTMF receiver context.
00143     \param s The DTMF receiver context.
00144     \param callback Callback routine used to report the start and end of digits.
00145     \param user_data An opaque pointer which is associated with the context,
00146            and supplied in callbacks. */
00147 SPAN_DECLARE(void) dtmf_rx_set_realtime_callback(dtmf_rx_state_t *s,
00148                                                  tone_report_func_t callback,
00149                                                  void *user_data);
00150 
00151 /*! \brief Adjust a DTMF receiver context.
00152     \param s The DTMF receiver context.
00153     \param filter_dialtone TRUE to enable filtering of dialtone, FALSE
00154            to disable, < 0 to leave unchanged.
00155     \param twist Acceptable twist, in dB. < 0 to leave unchanged.
00156     \param reverse_twist Acceptable reverse twist, in dB. < 0 to leave unchanged.
00157     \param threshold The minimum acceptable tone level for detection, in dBm0.
00158            <= -99 to leave unchanged. */
00159 SPAN_DECLARE(void) dtmf_rx_parms(dtmf_rx_state_t *s,
00160                                  int filter_dialtone,
00161                                  int twist,
00162                                  int reverse_twist,
00163                                  int threshold);
00164 
00165 /*! Process a block of received DTMF audio samples.
00166     \brief Process a block of received DTMF audio samples.
00167     \param s The DTMF receiver context.
00168     \param amp The audio sample buffer.
00169     \param samples The number of samples in the buffer.
00170     \return The number of samples unprocessed. */
00171 SPAN_DECLARE(int) dtmf_rx(dtmf_rx_state_t *s, const int16_t amp[], int samples);
00172 
00173 /*! Get the status of DTMF detection during processing of the last audio
00174     chunk.
00175     \brief Get the status of DTMF detection during processing of the last
00176            audio chunk.
00177     \param s The DTMF receiver context.
00178     \return The current digit status. Either 'x' for a "maybe" condition, or the
00179             digit being detected. */
00180 SPAN_DECLARE(int) dtmf_rx_status(dtmf_rx_state_t *s);
00181 
00182 /*! \brief Get a string of digits from a DTMF receiver's output buffer.
00183     \param s The DTMF receiver context.
00184     \param digits The buffer for the received digits.
00185     \param max The maximum  number of digits to be returned,
00186     \return The number of digits actually returned. */
00187 SPAN_DECLARE(size_t) dtmf_rx_get(dtmf_rx_state_t *s, char *digits, int max);
00188 
00189 /*! \brief Initialise a DTMF receiver context.
00190     \param s The DTMF receiver context.
00191     \param callback An optional callback routine, used to report received digits. If
00192            no callback routine is set, digits may be collected, using the dtmf_rx_get()
00193            function.
00194     \param user_data An opaque pointer which is associated with the context,
00195            and supplied in callbacks.
00196     \return A pointer to the DTMF receiver context. */
00197 SPAN_DECLARE(dtmf_rx_state_t *) dtmf_rx_init(dtmf_rx_state_t *s,
00198                                              digits_rx_callback_t callback,
00199                                              void *user_data);
00200 
00201 /*! \brief Release a DTMF receiver context.
00202     \param s The DTMF receiver context.
00203     \return 0 for OK, else -1. */
00204 SPAN_DECLARE(int) dtmf_rx_release(dtmf_rx_state_t *s);
00205 
00206 /*! \brief Free a DTMF receiver context.
00207     \param s The DTMF receiver context.
00208     \return 0 for OK, else -1. */
00209 SPAN_DECLARE(int) dtmf_rx_free(dtmf_rx_state_t *s);
00210 
00211 #if defined(__cplusplus)
00212 }
00213 #endif
00214 
00215 #endif
00216 /*- End of file ------------------------------------------------------------*/

Generated on 29 Jul 2015 for spandsp by  doxygen 1.6.1