spandsp 0.0.6
private/sig_tone.h
1/*
2 * SpanDSP - a series of DSP components for telephony
3 *
4 * private/sig_tone.h - Signalling tone processing for the 2280Hz, 2400Hz, 2600Hz
5 * and similar signalling tones used in older protocols.
6 *
7 * Written by Steve Underwood <steveu@coppice.org>
8 *
9 * Copyright (C) 2004 Steve Underwood
10 *
11 * All rights reserved.
12 *
13 * This program is free software; you can redistribute it and/or modify
14 * it under the terms of the GNU Lesser General Public License version 2.1,
15 * as published by the Free Software Foundation.
16 *
17 * This program is distributed in the hope that it will be useful,
18 * but WITHOUT ANY WARRANTY; without even the implied warranty of
19 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
20 * GNU Lesser General Public License for more details.
21 *
22 * You should have received a copy of the GNU Lesser General Public
23 * License along with this program; if not, write to the Free Software
24 * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
25 */
26
27#if !defined(_SPANDSP_PRIVATE_SIG_TONE_H_)
28#define _SPANDSP_PRIVATE_SIG_TONE_H_
29
30/*! \brief The coefficient set for a pair of cascaded bi-quads that make a signalling notch filter. */
31typedef struct
32{
33#if defined(SPANDSP_USE_FIXED_POINT)
34 int16_t a1[3];
35 int16_t b1[3];
36 int16_t a2[3];
37 int16_t b2[3];
38 int postscale;
39#else
40 float a1[3];
41 float b1[3];
42 float a2[3];
43 float b2[3];
44#endif
46
47/*! \brief The coefficient set for a bi-quad that makes a signalling flat filter.
48 Some signalling tone schemes require such a filter, and some don't.
49 It is termed a flat filter, to distinguish it from the sharp filter,
50 but obviously it is not actually flat. It is a broad band weighting
51 filter. */
52typedef struct
53{
54#if defined(SPANDSP_USE_FIXED_POINT)
55 /*! \brief Flat mode bandpass bi-quad parameters */
56 int16_t a[3];
57 /*! \brief Flat mode bandpass bi-quad parameters */
58 int16_t b[3];
59 /*! \brief Post filter scaling */
60 int postscale;
61#else
62 /*! \brief Flat mode bandpass bi-quad parameters */
63 float a[3];
64 /*! \brief Flat mode bandpass bi-quad parameters */
65 float b[3];
66#endif
68
69/*!
70 signalling tone descriptor. This defines the working state for a
71 single instance of the transmit and receive sides of a signalling
72 tone processor.
73*/
74typedef struct
75{
76 /*! \brief The tones used. */
77 int tone_freq[2];
78 /*! \brief The high and low tone amplitudes for each of the tones, in dBm0. */
79 int tone_amp[2][2];
80
81 /*! \brief The delay, in audio samples, before the high level tone drops
82 to a low level tone. Some signalling protocols require the
83 signalling tone be started at a high level, to ensure crisp
84 initial detection at the receiver, but require the tone
85 amplitude to drop by a number of dBs if it is sustained,
86 to reduce crosstalk levels. */
88
89 /*! \brief Some signalling tone detectors use a sharp initial filter,
90 changing to a broader, flatter, filter after some delay. This
91 parameter defines the delay. 0 means it never changes. */
93
94 /*! \brief Parameters to control the behaviour of the notch filter, used
95 to remove the tone from the voice path in some protocols. The
96 notch is applied as fast as possible, when the signalling tone
97 is detected. Its removal is delayed by this timeout, to avoid
98 clicky noises from repeated switching of the filter on rapid
99 pulses of signalling tone. */
101
102 /*! \brief The tone on persistence check, in audio samples. */
104 /*! \brief The tone off persistence check, in audio samples. */
106
107 /*! \brief The number of tones used. */
108 int tones;
109 /*! \brief The coefficients for the cascaded bi-quads notch filter. */
111 /*! \brief The coefficients for the single bi-quad flat mode filter. */
113
114 /*! \brief Minimum signalling tone to total power ratio, in dB */
116 /*! \brief Minimum total power for detection in sharp mode, in dB */
118 /*! \brief Minimum total power for detection in flat mode, in dB */
121
122/*!
123 Signalling tone transmit state
124 */
126{
127 /*! \brief The callback function used to handle signalling changes. */
128 tone_report_func_t sig_update;
129 /*! \brief A user specified opaque pointer passed to the callback function. */
131
132 /*! \brief Tone descriptor */
134
135 /*! The phase rates for the one or two tones */
136 int32_t phase_rate[2];
137 /*! The phase accumulators for the one or two tones */
138 uint32_t phase_acc[2];
139
140 /*! The scaling values for the one or two tones, and the high and low level of each tone */
141 int16_t tone_scaling[2][2];
142 /*! The sample timer, used to switch between the high and low level tones. */
144
145 /*! \brief Current transmit tone */
147 /*! \brief Current transmit timeout */
149 /*! \brief Time in current signalling state, in samples. */
151};
152
153/*!
154 Signalling tone receive state
155 */
157{
158 /*! \brief The callback function used to handle signalling changes. */
159 tone_report_func_t sig_update;
160 /*! \brief A user specified opaque pointer passed to the callback function. */
162
163 /*! \brief Tone descriptor */
165
166 /*! \brief The current receive tone */
168 /*! \brief The timeout for switching from the high level to low level tone detector. */
170 /*! \brief ??? */
172
173 struct
174 {
175#if defined(SPANDSP_USE_FIXED_POINT)
176 /*! \brief The z's for the notch filter */
177 int16_t notch_z1[2];
178 /*! \brief The z's for the notch filter */
179 int16_t notch_z2[2];
180#else
181 /*! \brief The z's for the notch filter */
182 float notch_z1[2];
183 /*! \brief The z's for the notch filter */
184 float notch_z2[2];
185#endif
186
187 /*! \brief The power output of the notch. */
189 } tone[3];
190
191#if defined(SPANDSP_USE_FIXED_POINT)
192 /*! \brief The z's for the weighting/bandpass filter. */
193 int16_t flat_z[2];
194#else
195 /*! \brief The z's for the weighting/bandpass filter. */
196 float flat_z[2];
197#endif
198 /*! \brief The output power of the flat (unfiltered or flat filtered) path. */
200
201 /*! \brief Persistence check for tone present */
203 /*! \brief The tone pattern on the last audio sample */
205
206 /*! \brief The minimum reading from the power meter for detection in flat mode */
208 /*! \brief The minimum reading from the power meter for detection in sharp mode */
210 /*! \brief The minimum ratio between notched power and total power for detection */
212
213 /*! \brief TRUE if in flat mode. FALSE if in sharp mode. */
215 /*! \brief TRUE if the notch filter is enabled in the media path */
217 /*! \brief ??? */
219 /*! \brief ??? */
221
222 /*! \brief ??? */
224 /*! \brief ??? */
226};
227
228#endif
229/*- End of file ------------------------------------------------------------*/
Definition power_meter.h:49
Definition private/sig_tone.h:75
int16_t detection_ratio
Minimum signalling tone to total power ratio, in dB.
Definition private/sig_tone.h:115
int tones
The number of tones used.
Definition private/sig_tone.h:108
int16_t flat_detection_threshold
Minimum total power for detection in flat mode, in dB.
Definition private/sig_tone.h:119
int notch_lag_time
Parameters to control the behaviour of the notch filter, used to remove the tone from the voice path ...
Definition private/sig_tone.h:100
int tone_amp[2][2]
The high and low tone amplitudes for each of the tones, in dBm0.
Definition private/sig_tone.h:79
int tone_on_check_time
The tone on persistence check, in audio samples.
Definition private/sig_tone.h:103
int high_low_timeout
The delay, in audio samples, before the high level tone drops to a low level tone....
Definition private/sig_tone.h:87
int tone_off_check_time
The tone off persistence check, in audio samples.
Definition private/sig_tone.h:105
const sig_tone_notch_coeffs_t * notch[2]
The coefficients for the cascaded bi-quads notch filter.
Definition private/sig_tone.h:110
int tone_freq[2]
The tones used.
Definition private/sig_tone.h:77
int sharp_flat_timeout
Some signalling tone detectors use a sharp initial filter, changing to a broader, flatter,...
Definition private/sig_tone.h:92
int16_t sharp_detection_threshold
Minimum total power for detection in sharp mode, in dB.
Definition private/sig_tone.h:117
const sig_tone_flat_coeffs_t * flat
The coefficients for the single bi-quad flat mode filter.
Definition private/sig_tone.h:112
The coefficient set for a bi-quad that makes a signalling flat filter. Some signalling tone schemes r...
Definition private/sig_tone.h:53
float a[3]
Flat mode bandpass bi-quad parameters.
Definition private/sig_tone.h:63
float b[3]
Flat mode bandpass bi-quad parameters.
Definition private/sig_tone.h:65
The coefficient set for a pair of cascaded bi-quads that make a signalling notch filter.
Definition private/sig_tone.h:32
Definition private/sig_tone.h:157
int high_low_timer
The timeout for switching from the high level to low level tone detector.
Definition private/sig_tone.h:169
void * user_data
A user specified opaque pointer passed to the callback function.
Definition private/sig_tone.h:161
int last_sample_tone_present
The tone pattern on the last audio sample.
Definition private/sig_tone.h:204
int notch_enabled
TRUE if the notch filter is enabled in the media path.
Definition private/sig_tone.h:216
int flat_mode_timeout
???
Definition private/sig_tone.h:218
int flat_mode
TRUE if in flat mode. FALSE if in sharp mode.
Definition private/sig_tone.h:214
float notch_z1[2]
The z's for the notch filter.
Definition private/sig_tone.h:182
power_meter_t flat_power
The output power of the flat (unfiltered or flat filtered) path.
Definition private/sig_tone.h:199
int tone_persistence_timeout
Persistence check for tone present.
Definition private/sig_tone.h:202
tone_report_func_t sig_update
The callback function used to handle signalling changes.
Definition private/sig_tone.h:159
const sig_tone_descriptor_t * desc
Tone descriptor.
Definition private/sig_tone.h:164
int32_t flat_detection_threshold
The minimum reading from the power meter for detection in flat mode.
Definition private/sig_tone.h:207
int current_notch_filter
???
Definition private/sig_tone.h:171
float notch_z2[2]
The z's for the notch filter.
Definition private/sig_tone.h:184
int32_t sharp_detection_threshold
The minimum reading from the power meter for detection in sharp mode.
Definition private/sig_tone.h:209
int signalling_state
???
Definition private/sig_tone.h:223
int notch_insertion_timeout
???
Definition private/sig_tone.h:220
int signalling_state_duration
???
Definition private/sig_tone.h:225
power_meter_t power
The power output of the notch.
Definition private/sig_tone.h:188
int current_rx_tone
The current receive tone.
Definition private/sig_tone.h:167
int32_t detection_ratio
The minimum ratio between notched power and total power for detection.
Definition private/sig_tone.h:211
float flat_z[2]
The z's for the weighting/bandpass filter.
Definition private/sig_tone.h:196
Definition private/sig_tone.h:126
int high_low_timer
Definition private/sig_tone.h:143
uint32_t phase_acc[2]
Definition private/sig_tone.h:138
int current_tx_timeout
Current transmit timeout.
Definition private/sig_tone.h:148
void * user_data
A user specified opaque pointer passed to the callback function.
Definition private/sig_tone.h:130
tone_report_func_t sig_update
The callback function used to handle signalling changes.
Definition private/sig_tone.h:128
int signalling_state_duration
Time in current signalling state, in samples.
Definition private/sig_tone.h:150
int current_tx_tone
Current transmit tone.
Definition private/sig_tone.h:146
const sig_tone_descriptor_t * desc
Tone descriptor.
Definition private/sig_tone.h:133
int16_t tone_scaling[2][2]
Definition private/sig_tone.h:141
int32_t phase_rate[2]
Definition private/sig_tone.h:136