|
5
|
1 /*
|
|
|
2 * SpanDSP - a series of DSP components for telephony
|
|
|
3 *
|
|
|
4 * super_tone_rx.h - Flexible telephony supervisory tone detection.
|
|
|
5 *
|
|
|
6 * Written by Steve Underwood <steveu@coppice.org>
|
|
|
7 *
|
|
|
8 * Copyright (C) 2003 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 General Public License version 2, as
|
|
|
14 * 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 General Public License for more details.
|
|
|
20 *
|
|
|
21 * You should have received a copy of the GNU General Public License
|
|
|
22 * along with this program; if not, write to the Free Software
|
|
|
23 * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
|
|
|
24 *
|
|
|
25 * $Id: super_tone_rx.h,v 1.9 2006/10/24 13:22:02 steveu Exp $
|
|
|
26 */
|
|
|
27
|
|
|
28 #if !defined(_SUPER_TONE_RX_H_)
|
|
|
29 #define _SUPER_TONE_RX_H_
|
|
|
30
|
|
|
31 /*! \page super_tone_rx_page Supervisory tone detection
|
|
|
32
|
|
|
33 \section super_tone_rx_page_sec_1 What does it do?
|
|
|
34
|
|
|
35 The supervisory tone detector may be configured to detect most of the world's
|
|
|
36 telephone supervisory tones - things like ringback, busy, number unobtainable,
|
|
|
37 and so on.
|
|
|
38
|
|
|
39 \section super_tone_rx_page_sec_2 How does it work?
|
|
|
40
|
|
|
41 The supervisory tone detector is passed a series of data structures describing
|
|
|
42 the tone patterns - the frequencies and cadencing - of the tones to be searched
|
|
|
43 for. It constructs one or more Goertzel filters to monitor the required tones.
|
|
|
44 If tones are close in frequency a single Goertzel set to the centre of the
|
|
|
45 frequency range will be used. This optimises the efficiency of the detector. The
|
|
|
46 Goertzel filters are applied without applying any special window functional
|
|
|
47 (i.e. they use a rectangular window), so they have a sinc like response.
|
|
|
48 However, for most tone patterns their rejection qualities are adequate.
|
|
|
49
|
|
|
50 The detector aims to meet the need of the standard call progress tones, to
|
|
|
51 ITU-T E.180/Q.35 (busy, dial, ringback, reorder). Also, the extended tones,
|
|
|
52 to ITU-T E.180, Supplement 2 and EIA/TIA-464-A (recall dial tone, special
|
|
|
53 ringback tone, intercept tone, call waiting tone, busy verification tone,
|
|
|
54 executive override tone, confirmation tone).
|
|
|
55 */
|
|
|
56
|
|
|
57 /*! Tone detection indication callback routine */
|
|
|
58 typedef void (*tone_report_func_t)(void *user_data, int code);
|
|
|
59
|
|
|
60 #define BINS 128
|
|
|
61
|
|
|
62 typedef struct
|
|
|
63 {
|
|
|
64 int f1;
|
|
|
65 int f2;
|
|
|
66 int recognition_duration;
|
|
|
67 int min_duration;
|
|
|
68 int max_duration;
|
|
|
69 } super_tone_rx_segment_t;
|
|
|
70
|
|
|
71 typedef struct
|
|
|
72 {
|
|
|
73 int used_frequencies;
|
|
|
74 int monitored_frequencies;
|
|
|
75 int pitches[BINS/2][2];
|
|
|
76 int tones;
|
|
|
77 super_tone_rx_segment_t **tone_list;
|
|
|
78 int *tone_segs;
|
|
|
79 goertzel_descriptor_t *desc;
|
|
|
80 } super_tone_rx_descriptor_t;
|
|
|
81
|
|
|
82 typedef struct
|
|
|
83 {
|
|
|
84 super_tone_rx_descriptor_t *desc;
|
|
|
85 float energy;
|
|
|
86 float total_energy;
|
|
|
87 int detected_tone;
|
|
|
88 int rotation;
|
|
|
89 tone_report_func_t tone_callback;
|
|
|
90 void (*segment_callback)(void *data, int f1, int f2, int duration);
|
|
|
91 void *callback_data;
|
|
|
92 super_tone_rx_segment_t segments[11];
|
|
|
93 goertzel_state_t state[];
|
|
|
94 } super_tone_rx_state_t;
|
|
|
95
|
|
|
96 /*! Create a new supervisory tone detector descriptor.
|
|
|
97 \param desc The supervisory tone set desciptor. If NULL, the routine will allocate space for a
|
|
|
98 descriptor.
|
|
|
99 \return The supervisory tone set descriptor.
|
|
|
100 */
|
|
|
101 super_tone_rx_descriptor_t *super_tone_rx_make_descriptor(super_tone_rx_descriptor_t *desc);
|
|
|
102
|
|
|
103 /*! Free a supervisory tone detector descriptor.
|
|
|
104 \param desc The supervisory tone set desciptor.
|
|
|
105 \return 0 for OK, -1 for fail.
|
|
|
106 */
|
|
|
107 int super_tone_rx_free_descriptor(super_tone_rx_descriptor_t *desc);
|
|
|
108
|
|
|
109 /*! Add a new tone pattern to a supervisory tone detector set.
|
|
|
110 \param desc The supervisory tone set descriptor.
|
|
|
111 \return The new tone ID. */
|
|
|
112 int super_tone_rx_add_tone(super_tone_rx_descriptor_t *desc);
|
|
|
113
|
|
|
114 /*! Add a new tone pattern element to a tone pattern in a supervisory tone detector.
|
|
|
115 \param desc The supervisory tone set desciptor.
|
|
|
116 \param tone The tone ID within the descriptor.
|
|
|
117 \param f1 Frequency 1 (-1 for a silent period).
|
|
|
118 \param f2 Frequency 2 (-1 for a silent period, or only one frequency).
|
|
|
119 \param min The minimum duration, in ms.
|
|
|
120 \param max The maximum duration, in ms.
|
|
|
121 \return The new number of elements in the tone description.
|
|
|
122 */
|
|
|
123 int super_tone_rx_add_element(super_tone_rx_descriptor_t *desc,
|
|
|
124 int tone,
|
|
|
125 int f1,
|
|
|
126 int f2,
|
|
|
127 int min,
|
|
|
128 int max);
|
|
|
129
|
|
|
130 /*! Initialise a supervisory tone detector.
|
|
|
131 \param s The supervisory tone detector context.
|
|
|
132 \param desc The tone descriptor.
|
|
|
133 \param callback The callback routine called to report the valid detection or termination of
|
|
|
134 one of the monitored tones.
|
|
|
135 \param user_data An opaque pointer passed when calling the callback routine.
|
|
|
136 \return The supervisory tone detector context.
|
|
|
137 */
|
|
|
138 super_tone_rx_state_t *super_tone_rx_init(super_tone_rx_state_t *s,
|
|
|
139 super_tone_rx_descriptor_t *desc,
|
|
|
140 tone_report_func_t callback,
|
|
|
141 void *user_data);
|
|
|
142
|
|
|
143 /*! Release a supervisory tone detector.
|
|
|
144 \param s The supervisory tone context.
|
|
|
145 \return 0 for OK, -1 for fail.
|
|
|
146 */
|
|
|
147 int super_tone_rx_free(super_tone_rx_state_t *s);
|
|
|
148
|
|
|
149 /*! Define a callback routine to be called each time a tone pattern element is complete. This is
|
|
|
150 mostly used when analysing a tone.
|
|
|
151 \param s The supervisory tone context.
|
|
|
152 \param callback The callback routine.
|
|
|
153 */
|
|
|
154 void super_tone_rx_segment_callback(super_tone_rx_state_t *s,
|
|
|
155 void (*callback)(void *data, int f1, int f2, int duration));
|
|
|
156
|
|
|
157 /*! Apply supervisory tone detection processing to a block of audio samples.
|
|
|
158 \brief Apply supervisory tone detection processing to a block of audio samples.
|
|
|
159 \param super The supervisory tone context.
|
|
|
160 \param amp The audio sample buffer.
|
|
|
161 \param samples The number of samples in the buffer.
|
|
|
162 \return The number of samples processed.
|
|
|
163 */
|
|
|
164 int super_tone_rx(super_tone_rx_state_t *super, const int16_t *amp, int samples);
|
|
|
165
|
|
|
166 #endif
|
|
|
167 /*- End of file ------------------------------------------------------------*/
|
