dtmf.h

Go to the documentation of this file.
00001 /*
00002  * SpanDSP - a series of DSP components for telephony
00003  *
00004  * dtmf.h - 
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 General Public License version 2, as
00014  * 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 General Public License for more details.
00020  *
00021  * You should have received a copy of the GNU General Public License
00022  * along with this program; if not, write to the Free Software
00023  * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
00024  *
00025  * $Id: dtmf.h,v 1.18 2007/12/20 11:11:16 steveu Exp $
00026  */
00027 
00028 #if !defined(_SPANDSP_DTMF_H_)
00029 #define _SPANDSP_DTMF_H_
00030 
00031 /*! \page dtmf_rx_page DTMF receiver
00032 \section dtmf_rx_page_sec_1 What does it do?
00033 The DTMF receiver detects the standard DTMF digits. It is compliant with
00034 ITU-T Q.23, ITU-T Q.24, and the local DTMF specifications of most administrations.
00035 Its passes the test suites. It also scores *very* well on the standard
00036 talk-off tests. 
00037 
00038 The current design uses floating point extensively. It is not tolerant of DC.
00039 It is expected that a DC restore stage will be placed before the DTMF detector.
00040 Unless the dial tone filter is switched on, the detector has poor tolerance
00041 of dial tone. Whether this matter depends on your application. If you are using
00042 the detector in an IVR application you will need proper echo cancellation to
00043 get good performance in the presence of speech prompts, so dial tone will not
00044 exist. If you do need good dial tone tolerance, a dial tone filter can be
00045 enabled in the detector.
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 (*dtmf_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
00083 {
00084     tone_gen_state_t tones;
00085     int current_sample;
00086     /* The queue structure MUST be followed immediately by the buffer */
00087     queue_state_t queue;
00088     char digits[MAX_DTMF_DIGITS + 1];
00089 } dtmf_tx_state_t;
00090 
00091 /*!
00092     DTMF digit detector descriptor.
00093 */
00094 typedef struct
00095 {
00096     /*! Optional callback funcion to deliver received digits. */
00097     dtmf_rx_callback_t callback;
00098     /*! An opaque pointer passed to the callback function. */
00099     void *callback_data;
00100     /*! Optional callback funcion to deliver real time digit state changes. */
00101     tone_report_func_t realtime_callback;
00102     /*! An opaque pointer passed to the real time callback function. */
00103     void *realtime_callback_data;
00104     /*! TRUE if dialtone should be filtered before processing */
00105     int filter_dialtone;
00106     /*! Maximum acceptable "normal" (lower bigger than higher) twist ratio */
00107     float normal_twist;
00108     /*! Maximum acceptable "reverse" (higher bigger than lower) twist ratio */
00109     float reverse_twist;
00110 
00111     /*! 350Hz filter state for the optional dialtone filter */
00112     float z350[2];
00113     /*! 440Hz filter state for the optional dialtone filter */
00114     float z440[2];
00115 
00116     /*! Tone detector working states for the row tones. */
00117     goertzel_state_t row_out[4];
00118     /*! Tone detector working states for the column tones. */
00119     goertzel_state_t col_out[4];
00120     /*! The accumlating total energy on the same period over which the Goertzels work. */
00121     float energy;
00122     /*! The result of the last tone analysis. */
00123     uint8_t last_hit;
00124     /*! The confirmed digit we are currently receiving */
00125     uint8_t in_digit;
00126     /*! The current sample number within a processing block. */
00127     int current_sample;
00128 
00129     /*! The number of digits which have been lost due to buffer overflows. */
00130     int lost_digits;
00131     /*! The number of digits currently in the digit buffer. */
00132     int current_digits;
00133     /*! The received digits buffer. This is a NULL terminated string. */
00134     char digits[MAX_DTMF_DIGITS + 1];
00135 } dtmf_rx_state_t;
00136 
00137 #if defined(__cplusplus)
00138 extern "C"
00139 {
00140 #endif
00141 
00142 /*! \brief Generate a buffer of DTMF tones.
00143     \param s The DTMF generator context.
00144     \param amp The buffer for the generated signal.
00145     \param max_samples The required number of generated samples.
00146     \return The number of samples actually generated. This may be less than 
00147             max_samples if the input buffer empties. */
00148 int dtmf_tx(dtmf_tx_state_t *s, int16_t amp[], int max_samples);
00149 
00150 /*! \brief Put a string of digits in a DTMF generator's input buffer.
00151     \param s The DTMF generator context.
00152     \param digits The string of digits to be added.
00153     \param len The length of the string of digits. If negative, the string is
00154            assumed to be a NULL terminated string.
00155     \return The number of digits actually added. This may be less than the
00156             length of the digit string, if the buffer fills up. */
00157 size_t dtmf_tx_put(dtmf_tx_state_t *s, const char *digits, ssize_t len);
00158 
00159 /*! \brief Change the transmit level for a DTMF tone generator context.
00160     \param s The DTMF generator context.
00161     \param level The level of the low tone, in dBm0.
00162     \param twist The twist, in dB. */
00163 void dtmf_tx_set_level(dtmf_tx_state_t *s, int level, int twist);
00164 
00165 /*! \brief Initialise a DTMF tone generator context.
00166     \param s The DTMF generator context.
00167     \return A pointer to the DTMF generator context. */
00168 dtmf_tx_state_t *dtmf_tx_init(dtmf_tx_state_t *s);
00169 
00170 /*! \brief Free a DTMF tone generator context.
00171     \param s The DTMF tone generator context.
00172     \return 0 for OK, else -1. */
00173 int dtmf_tx_free(dtmf_tx_state_t *s);
00174 
00175 /*! Set a optional realtime callback for a DTMF receiver context. This function
00176     is called immediately a confirmed state change occurs in the received DTMF. It
00177     is called with the ASCII value for a DTMF tone pair, or zero to indicate no tone
00178     is being received.
00179     \brief Set a realtime callback for a DTMF receiver context.
00180     \param s The DTMF receiver context.
00181     \param callback Callback routine used to report the start and end of digits.
00182     \param user_data An opaque pointer which is associated with the context,
00183            and supplied in callbacks. */
00184 void dtmf_rx_set_realtime_callback(dtmf_rx_state_t *s,
00185                                    tone_report_func_t callback,
00186                                    void *user_data);
00187 
00188 /*! \brief Adjust a DTMF receiver context.
00189     \param s The DTMF receiver context.
00190     \param filter_dialtone TRUE to enable filtering of dialtone, FALSE
00191            to disable, < 0 to leave unchanged.
00192     \param twist Acceptable twist, in dB. < 0 to leave unchanged.
00193     \param reverse_twist Acceptable reverse twist, in dB. < 0 to leave unchanged. */
00194 void dtmf_rx_parms(dtmf_rx_state_t *s, int filter_dialtone, int twist, int reverse_twist);
00195 
00196 /*! Process a block of received DTMF audio samples.
00197     \brief Process a block of received DTMF audio samples.
00198     \param s The DTMF receiver context.
00199     \param amp The audio sample buffer.
00200     \param samples The number of samples in the buffer.
00201     \return The number of samples unprocessed. */
00202 int dtmf_rx(dtmf_rx_state_t *s, const int16_t amp[], int samples);
00203 
00204 /*! Get the status of DTMF detection during processing of the last audio
00205     chunk.
00206     \brief Get the status of DTMF detection during processing of the last
00207            audio chunk.
00208     \param s The DTMF receiver context.
00209     \return The current digit status. Either 'x' for a "maybe" condition, or the
00210             digit being detected. */
00211 int dtmf_rx_status(dtmf_rx_state_t *s);
00212 
00213 /*! \brief Get a string of digits from a DTMF receiver's output buffer.
00214     \param s The DTMF receiver context.
00215     \param digits The buffer for the received digits.
00216     \param max The maximum  number of digits to be returned,
00217     \return The number of digits actually returned. */
00218 size_t dtmf_rx_get(dtmf_rx_state_t *s, char *digits, int max);
00219 
00220 /*! \brief Initialise a DTMF receiver context.
00221     \param s The DTMF receiver context.
00222     \param callback An optional callback routine, used to report received digits. If
00223            no callback routine is set, digits may be collected, using the dtmf_rx_get()
00224            function.
00225     \param user_data An opaque pointer which is associated with the context,
00226            and supplied in callbacks.
00227     \return A pointer to the DTMF receiver context. */
00228 dtmf_rx_state_t *dtmf_rx_init(dtmf_rx_state_t *s,
00229                               dtmf_rx_callback_t callback,
00230                               void *user_data);
00231 
00232 /*! \brief Free a DTMF receiver context.
00233     \param s The DTMF receiver context.
00234     \return 0 for OK, else -1. */
00235 int dtmf_rx_free(dtmf_rx_state_t *s);
00236 
00237 #if defined(__cplusplus)
00238 }
00239 #endif
00240 
00241 #endif
00242 /*- End of file ------------------------------------------------------------*/

Generated on Wed Apr 16 02:37:05 2008 for libspandsp by  doxygen 1.5.1