Mercurial > hg > audiostuff

comparison spandsp-0.0.3/spandsp-0.0.3/src/spandsp/super_tone_rx.h @ 5:f762bf195c4b

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
import spandsp-0.0.3
author Peter Meerwald <pmeerw@cosy.sbg.ac.at>
date Fri, 25 Jun 2010 16:00:21 +0200
parents
children
comparison
equal deleted inserted replaced
4:26cd8f1ef0b1 5:f762bf195c4b
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 ------------------------------------------------------------*/

Repositories maintained by Peter Meerwald, pmeerw@pmeerw.net.