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 as published by
00014  * the Free Software Foundation; either version 2 of the License, or
00015  * (at your option) any later version.
00016  *
00017  * This program is distributed in the hope that it will be useful,
00018  * but WITHOUT ANY WARRANTY; without even the implied warranty of
00019  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
00020  * GNU General Public License for more details.
00021  *
00022  * You should have received a copy of the GNU General Public License
00023  * along with this program; if not, write to the Free Software
00024  * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
00025  *
00026  * $Id: super_tone_rx.h,v 1.4 2005/11/25 14:52:00 steveu Exp $
00027  */
00028 
00029 #if !defined(_SUPER_TONE_RX_H_)
00030 #define _SUPER_TONE_RX_H_
00031 
00032 /*! \page super_tone_rx_page Supervisory tone detection
00033 
00034 \section super_tone_rx_page_sec_1 What does it do?
00035 
00036 The supervisory tone detector may be configured to detect most of the world's
00037 telephone supervisory tones - things like ringback, busy, number unobtainable,
00038 and so on.
00039 
00040 \section super_tone_rx_page_sec_2 How does it work?
00041 
00042 The supervisory tone detector is passed a series of data structures describing
00043 the tone patterns - the frequencies and cadencing - of the tones to be searched
00044 for. It constructs one or more Goertzel filters to monitor the required tones.
00045 If tones are close in frequency a single Goertzel set to the centre of the
00046 frequency range will be used. This optimises the efficiency of the detector. The
00047 Goertzel filters are applied without applying any special window functional
00048 (i.e. they use a rectangular window), so they have a sinc like response.
00049 However, for most tone patterns their rejection qualities are adequate. 
00050 
00051 The detector aims to meet the need of the standard call progress tones, to
00052 ITU-T E.180/Q.35 (busy, dial, ringback, reorder). Also, the extended tones,
00053 to ITU-T E.180, Supplement 2 and EIA/TIA-464-A (recall dial tone, special
00054 ringback tone, intercept tone, call waiting tone, busy verification tone,
00055 executive override tone, confirmation tone).
00056 */
00057 
00058 #define BINS            128
00059 
00060 typedef struct
00061 {
00062     int f1;
00063     int f2;
00064     int recognition_duration;
00065     int min_duration;
00066     int max_duration;
00067 } super_tone_rx_segment_t;
00068 
00069 typedef struct
00070 {
00071     int used_frequencies;
00072     int monitored_frequencies;
00073     int pitches[BINS/2][2];
00074     int tones;
00075     super_tone_rx_segment_t **tone_list;
00076     int *tone_segs;
00077     goertzel_descriptor_t *desc;
00078 } super_tone_rx_descriptor_t;
00079 
00080 typedef struct
00081 {
00082     super_tone_rx_descriptor_t *desc;
00083     float energy;
00084     float total_energy;
00085     int detected_tone;
00086     int rotation;
00087     void (*tone_callback)(void *data, int code);
00088     void (*segment_callback)(void *data, int f1, int f2, int duration);
00089     void *callback_data;
00090     super_tone_rx_segment_t segments[11];
00091     goertzel_state_t state[0];
00092     uint8_t filler[80];
00093 } super_tone_rx_state_t;
00094 
00095 /*! Create Add a new tone pattern to a supervisory tone detector.
00096     \param desc The supervisory tone set desciptor. If NULL, the routine will allocate space for a
00097                 descriptor.
00098     \return The supervisory tone set descriptor. */
00099 super_tone_rx_descriptor_t *super_tone_rx_make_descriptor(super_tone_rx_descriptor_t *desc);
00100 
00101 /*! Add a new tone pattern to a supervisory tone detector set.
00102     \param desc The supervisory tone set descriptor.
00103     \return The new tone ID. */
00104 int super_tone_rx_add_tone(super_tone_rx_descriptor_t *desc);
00105 
00106 /*! Add a new tone pattern element to a tone pattern in a supervisory tone detector.
00107     \param desc The supervisory tone set desciptor.
00108     \param tone The tone ID within the descriptor.
00109     \param f1 Frequency 1 (-1 for a silent period).
00110     \param f2 Frequency 2 (-1 for a silent period, or only one frequency).
00111     \param min The minimum duration, in ms.
00112     \param max The maximum duration, in ms.
00113     \return The new number of elements in the tone description. */
00114 int super_tone_rx_add_element(super_tone_rx_descriptor_t *desc,
00115                               int tone,
00116                               int f1,
00117                               int f2,
00118                               int min,
00119                               int max);
00120 
00121 /*! Initialise a supervisory tone detector.
00122     \param s The supervisory tone detector context.
00123     \param desc The tone descriptor.
00124     \param callback The callback routine called to report the valid detection or termination of
00125            one of the monitored tones.
00126     \param data An opaque pointer passed when calling the callback routine.
00127     \return The supervisory tone detector context. */
00128 super_tone_rx_state_t *super_tone_rx_init(super_tone_rx_state_t *s,
00129                                           super_tone_rx_descriptor_t *desc,
00130                                           void (*callback)(void *data, int code),
00131                                           void *data);
00132 
00133 /*! Release a supervisory tone detector.
00134     \param s The supervisory tone context.
00135     \return 0 for OK, -1 for fail. */
00136 int super_tone_rx_free(super_tone_rx_state_t *s);
00137 
00138 /*! Define a callback routine to be called each time a tone pattern element is complete. This is
00139     mostly used when analysing a tone.
00140     \param s The supervisory tone context.
00141     \param callback The callback routine. */
00142 void super_tone_rx_segment_callback(super_tone_rx_state_t *s,
00143                                     void (*callback)(void *data, int f1, int f2, int duration));
00144 
00145 /*! Apply supervisory tone detection processing to a block of audio samples.
00146     \brief Apply supervisory tone detection processing to a block of audio samples.
00147     \param super The supervisory tone context.
00148     \param amp The audio sample buffer.
00149     \param samples The number of samples in the buffer.
00150     \return The number of samples processed.
00151 */
00152 int super_tone_rx(super_tone_rx_state_t *super, const int16_t *amp, int samples);
00153 
00154 #endif
00155 /*- End of file ------------------------------------------------------------*/

Generated on Fri Nov 10 09:40:24 2006 for libspandsp by  doxygen 1.5.1