super_tone_rx.h

00001 /*
00002  * SpanDSP - a series of DSP components for telephony
00003  *
00004  * super_tone_rx.h - Flexible telephony supervisory tone detection.
00005  *
00006  * Written by Steve Underwood <steveu@coppice.org>
00007  *
00008  * Copyright (C) 2003 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: super_tone_rx.h,v 1.11 2007/04/05 19:20:49 steveu Exp $
00026  */
00027 
00028 #if !defined(_SPANDSP_SUPER_TONE_RX_H_)
00029 #define _SPANDSP_SUPER_TONE_RX_H_
00030 
00031 /*! \page super_tone_rx_page Supervisory tone detection
00032 
00033 \section super_tone_rx_page_sec_1 What does it do?
00034 
00035 The supervisory tone detector may be configured to detect most of the world's
00036 telephone supervisory tones - things like ringback, busy, number unobtainable,
00037 and so on.
00038 
00039 \section super_tone_rx_page_sec_2 How does it work?
00040 
00041 The supervisory tone detector is passed a series of data structures describing
00042 the tone patterns - the frequencies and cadencing - of the tones to be searched
00043 for. It constructs one or more Goertzel filters to monitor the required tones.
00044 If tones are close in frequency a single Goertzel set to the centre of the
00045 frequency range will be used. This optimises the efficiency of the detector. The
00046 Goertzel filters are applied without applying any special window functional
00047 (i.e. they use a rectangular window), so they have a sinc like response.
00048 However, for most tone patterns their rejection qualities are adequate. 
00049 
00050 The detector aims to meet the need of the standard call progress tones, to
00051 ITU-T E.180/Q.35 (busy, dial, ringback, reorder). Also, the extended tones,
00052 to ITU-T E.180, Supplement 2 and EIA/TIA-464-A (recall dial tone, special
00053 ringback tone, intercept tone, call waiting tone, busy verification tone,
00054 executive override tone, confirmation tone).
00055 */
00056 
00057 /*! Tone detection indication callback routine */
00058 typedef void (*tone_report_func_t)(void *user_data, int code, int level);
00059 
00060 #define BINS            128
00061 
00062 typedef struct
00063 {
00064     int f1;
00065     int f2;
00066     int recognition_duration;
00067     int min_duration;
00068     int max_duration;
00069 } super_tone_rx_segment_t;
00070 
00071 typedef struct
00072 {
00073     int used_frequencies;
00074     int monitored_frequencies;
00075     int pitches[BINS/2][2];
00076     int tones;
00077     super_tone_rx_segment_t **tone_list;
00078     int *tone_segs;
00079     goertzel_descriptor_t *desc;
00080 } super_tone_rx_descriptor_t;
00081 
00082 typedef struct
00083 {
00084     super_tone_rx_descriptor_t *desc;
00085     float energy;
00086     float total_energy;
00087     int detected_tone;
00088     int rotation;
00089     tone_report_func_t tone_callback;
00090     void (*segment_callback)(void *data, int f1, int f2, int duration);
00091     void *callback_data;
00092     super_tone_rx_segment_t segments[11];
00093     goertzel_state_t state[];
00094 } super_tone_rx_state_t;
00095 
00096 /*! Create a new supervisory tone detector descriptor.
00097     \param desc The supervisory tone set desciptor. If NULL, the routine will allocate space for a
00098                 descriptor.
00099     \return The supervisory tone set descriptor.
00100 */
00101 super_tone_rx_descriptor_t *super_tone_rx_make_descriptor(super_tone_rx_descriptor_t *desc);
00102 
00103 /*! Free a supervisory tone detector descriptor.
00104     \param desc The supervisory tone set desciptor.
00105     \return 0 for OK, -1 for fail.
00106 */
00107 int super_tone_rx_free_descriptor(super_tone_rx_descriptor_t *desc);
00108 
00109 /*! Add a new tone pattern to a supervisory tone detector set.
00110     \param desc The supervisory tone set descriptor.
00111     \return The new tone ID. */
00112 int super_tone_rx_add_tone(super_tone_rx_descriptor_t *desc);
00113 
00114 /*! Add a new tone pattern element to a tone pattern in a supervisory tone detector.
00115     \param desc The supervisory tone set desciptor.
00116     \param tone The tone ID within the descriptor.
00117     \param f1 Frequency 1 (-1 for a silent period).
00118     \param f2 Frequency 2 (-1 for a silent period, or only one frequency).
00119     \param min The minimum duration, in ms.
00120     \param max The maximum duration, in ms.
00121     \return The new number of elements in the tone description.
00122 */
00123 int super_tone_rx_add_element(super_tone_rx_descriptor_t *desc,
00124                               int tone,
00125                               int f1,
00126                               int f2,
00127                               int min,
00128                               int max);
00129 
00130 /*! Initialise a supervisory tone detector.
00131     \param s The supervisory tone detector context.
00132     \param desc The tone descriptor.
00133     \param callback The callback routine called to report the valid detection or termination of
00134            one of the monitored tones.
00135     \param user_data An opaque pointer passed when calling the callback routine.
00136     \return The supervisory tone detector context.
00137 */
00138 super_tone_rx_state_t *super_tone_rx_init(super_tone_rx_state_t *s,
00139                                           super_tone_rx_descriptor_t *desc,
00140                                           tone_report_func_t callback,
00141                                           void *user_data);
00142 
00143 /*! Release a supervisory tone detector.
00144     \param s The supervisory tone context.
00145     \return 0 for OK, -1 for fail.
00146 */
00147 int super_tone_rx_free(super_tone_rx_state_t *s);
00148 
00149 /*! Define a callback routine to be called each time a tone pattern element is complete. This is
00150     mostly used when analysing a tone.
00151     \param s The supervisory tone context.
00152     \param callback The callback routine.
00153 */
00154 void super_tone_rx_segment_callback(super_tone_rx_state_t *s,
00155                                     void (*callback)(void *data, int f1, int f2, int duration));
00156 
00157 /*! Apply supervisory tone detection processing to a block of audio samples.
00158     \brief Apply supervisory tone detection processing to a block of audio samples.
00159     \param super The supervisory tone context.
00160     \param amp The audio sample buffer.
00161     \param samples The number of samples in the buffer.
00162     \return The number of samples processed.
00163 */
00164 int super_tone_rx(super_tone_rx_state_t *super, const int16_t amp[], int samples);
00165 
00166 #endif
00167 /*- End of file ------------------------------------------------------------*/

Generated on Tue Jul 24 11:29:28 2007 for libspandsp by  doxygen 1.5.2