Mercurial > hg > audiostuff

comparison spandsp-0.0.6pre17/src/spandsp/sig_tone.h @ 4:26cd8f1ef0b1

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
import spandsp-0.0.6pre17
author Peter Meerwald <pmeerw@cosy.sbg.ac.at>
date Fri, 25 Jun 2010 15:50:58 +0200
parents
children
comparison
equal deleted inserted replaced
3:c6c5a16ce2f2 4:26cd8f1ef0b1
1 /*
2 * SpanDSP - a series of DSP components for telephony
3 *
4 * sig_tone.h - Signalling tone processing for the 2280Hz, 2400Hz, 2600Hz
5 * and similar signalling tone 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 * $Id: sig_tone.h,v 1.20 2009/09/04 14:38:46 steveu Exp $
27 */
28
29 /*! \file */
30
31 /*! \page sig_tone_page The signaling tone processor
32 \section sig_tone_sec_1 What does it do?
33 The signaling tone processor handles the 2280Hz, 2400Hz and 2600Hz tones, used
34 in many analogue signaling procotols, and digital ones derived from them.
35
36 \section sig_tone_sec_2 How does it work?
37 Most single and two voice frequency signalling systems share many features, as these
38 features have developed in similar ways over time, to address the limitations of
39 early tone signalling systems.
40
41 The usual practice is to start the generation of tone at a high energy level, so a
42 strong signal is available at the receiver, for crisp tone detection. If the tone
43 remains on for a significant period, the energy level is reduced, to minimise crosstalk.
44 During the signalling transitions, only the tone is sent through the channel, and the media
45 signal is suppressed. This means the signalling receiver has a very clean signal to work with,
46 allowing for crisp detection of the signalling tone. However, when the signalling tone is on
47 for extended periods, there may be supervisory information in the media signal, such as voice
48 announcements. To allow these to pass through the system, the signalling tone is mixed with
49 the media signal. It is the job of the signalling receiver to separate the signalling tone
50 and the media. The necessary filtering may degrade the quality of the voice signal, but at
51 least supervisory information may be heard.
52 */
53
54 #if !defined(_SPANDSP_SIG_TONE_H_)
55 #define _SPANDSP_SIG_TONE_H_
56
57 /* The optional tone sets */
58 enum
59 {
60 /*! European 2280Hz signaling tone. Tone 1 is 2280Hz. Tone 2 is not used. */
61 SIG_TONE_2280HZ = 1,
62 /*! US 2600Hz signaling tone. Tone 1 is 2600Hz. Tone 2 is not used. */
63 SIG_TONE_2600HZ,
64 /*! US 2400Hz + 2600Hz signaling tones. Tone 1 is 2600Hz. Tone 2 is 2400Hz. */
65 SIG_TONE_2400HZ_2600HZ
66 };
67
68 /* Mode control and report bits for transmit and receive */
69 enum
70 {
71 /*! Signaling tone 1 is present */
72 SIG_TONE_1_PRESENT = 0x001,
73 /*! Signaling tone 1 has changed state (ignored when setting tx mode) */
74 SIG_TONE_1_CHANGE = 0x002,
75 /*! Signaling tone 2 is present */
76 SIG_TONE_2_PRESENT = 0x004,
77 /*! Signaling tone 2 has changed state (ignored when setting tx mode) */
78 SIG_TONE_2_CHANGE = 0x008,
79 /*! The media signal is passing through. Tones might be added to it. */
80 SIG_TONE_TX_PASSTHROUGH = 0x010,
81 /*! The media signal is passing through. Tones might be extracted from it, if detected. */
82 SIG_TONE_RX_PASSTHROUGH = 0x040,
83 /*! Force filtering of the signaling tone, whether signaling is being detected or not.
84 This is mostly useful for test purposes. */
85 SIG_TONE_RX_FILTER_TONE = 0x080,
86 /*! Request an update of the transmit status, upon timeout of the previous status. */
87 SIG_TONE_TX_UPDATE_REQUEST = 0x100,
88 /*! Request an update of the receiver status, upon timeout of the previous status. */
89 SIG_TONE_RX_UPDATE_REQUEST = 0x200
90 };
91
92 /*!
93 Signaling tone descriptor. This defines the working state for a
94 single instance of the transmit and receive sides of a signaling
95 tone processor.
96 */
97 typedef struct sig_tone_descriptor_s sig_tone_descriptor_t;
98
99 typedef struct sig_tone_tx_state_s sig_tone_tx_state_t;
100
101 typedef struct sig_tone_rx_state_s sig_tone_rx_state_t;
102
103 #if defined(__cplusplus)
104 extern "C"
105 {
106 #endif
107
108 /*! Process a block of received audio samples.
109 \brief Process a block of received audio samples.
110 \param s The signaling tone context.
111 \param amp The audio sample buffer.
112 \param len The number of samples in the buffer.
113 \return The number of samples unprocessed. */
114 SPAN_DECLARE(int) sig_tone_rx(sig_tone_rx_state_t *s, int16_t amp[], int len);
115
116 /*! Set the receive mode.
117 \brief Set the receive mode.
118 \param s The signaling tone context.
119 \param mode The new mode for the receiver.
120 \param duration The duration for this mode, before an update is requested.
121 A duration of zero means forever. */
122 SPAN_DECLARE(void) sig_tone_rx_set_mode(sig_tone_rx_state_t *s, int mode, int duration);
123
124 /*! Initialise a signaling tone receiver context.
125 \brief Initialise a signaling tone context.
126 \param s The signaling tone context.
127 \param tone_type The type of signaling tone.
128 \param sig_update Callback function to handle signaling updates.
129 \param user_data An opaque pointer.
130 \return A pointer to the signalling tone context, or NULL if there was a problem. */
131 SPAN_DECLARE(sig_tone_rx_state_t *) sig_tone_rx_init(sig_tone_rx_state_t *s, int tone_type, tone_report_func_t sig_update, void *user_data);
132
133 /*! Release a signaling tone receiver context.
134 \brief Release a signaling tone receiver context.
135 \param s The signaling tone context.
136 \return 0 for OK */
137 SPAN_DECLARE(int) sig_tone_rx_release(sig_tone_rx_state_t *s);
138
139 /*! Free a signaling tone receiver context.
140 \brief Free a signaling tone receiver context.
141 \param s The signaling tone context.
142 \return 0 for OK */
143 SPAN_DECLARE(int) sig_tone_rx_free(sig_tone_rx_state_t *s);
144
145 /*! Generate a block of signaling tone audio samples.
146 \brief Generate a block of signaling tone audio samples.
147 \param s The signaling tone context.
148 \param amp The audio sample buffer.
149 \param len The number of samples to be generated.
150 \return The number of samples actually generated. */
151 SPAN_DECLARE(int) sig_tone_tx(sig_tone_tx_state_t *s, int16_t amp[], int len);
152
153 /*! Set the tone mode.
154 \brief Set the tone mode.
155 \param s The signaling tone context.
156 \param mode The new mode for the transmitted tones.
157 \param duration The duration for this mode, before an update is requested.
158 A duration of zero means forever. */
159 SPAN_DECLARE(void) sig_tone_tx_set_mode(sig_tone_tx_state_t *s, int mode, int duration);
160
161 /*! Initialise a signaling tone transmitter context.
162 \brief Initialise a signaling tone context.
163 \param s The signaling tone context.
164 \param tone_type The type of signaling tone.
165 \param sig_update Callback function to handle signaling updates.
166 \param user_data An opaque pointer.
167 \return A pointer to the signalling tone context, or NULL if there was a problem. */
168 SPAN_DECLARE(sig_tone_tx_state_t *) sig_tone_tx_init(sig_tone_tx_state_t *s, int tone_type, tone_report_func_t sig_update, void *user_data);
169
170 /*! Release a signaling tone transmitter context.
171 \brief Release a signaling tone transmitter context.
172 \param s The signaling tone context.
173 \return 0 for OK */
174 SPAN_DECLARE(int) sig_tone_tx_release(sig_tone_tx_state_t *s);
175
176 /*! Free a signaling tone transmitter context.
177 \brief Free a signaling tone transmitter context.
178 \param s The signaling tone context.
179 \return 0 for OK */
180 SPAN_DECLARE(int) sig_tone_tx_free(sig_tone_tx_state_t *s);
181
182 #if defined(__cplusplus)
183 }
184 #endif
185
186 #endif
187 /*- End of file ------------------------------------------------------------*/

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