Mercurial > hg > audiostuff

comparison spandsp-0.0.3/spandsp-0.0.3/src/spandsp/modem_echo.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 * modem_echo.h - An echo cancellor, suitable for electrical echos in GSTN modems
5 *
6 * Written by Steve Underwood <steveu@coppice.org>
7 *
8 * Copyright (C) 2001, 2004 Steve Underwood
9 *
10 * Based on a bit from here, a bit from there, eye of toad,
11 * ear of bat, etc - plus, of course, my own 2 cents.
12 *
13 * All rights reserved.
14 *
15 * This program is free software; you can redistribute it and/or modify
16 * it under the terms of the GNU General Public License version 2, as
17 * published by the Free Software Foundation.
18 *
19 * This program is distributed in the hope that it will be useful,
20 * but WITHOUT ANY WARRANTY; without even the implied warranty of
21 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
22 * GNU General Public License for more details.
23 *
24 * You should have received a copy of the GNU General Public License
25 * along with this program; if not, write to the Free Software
26 * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
27 *
28 * $Id: modem_echo.h,v 1.7 2006/10/24 13:45:28 steveu Exp $
29 */
30
31 /*! \file */
32
33 #if !defined(_MODEM_ECHO_H_)
34 #define _MODEM_ECHO_H_
35
36 /*! \page modem_echo_can_page Line echo cancellation for modems
37
38 \section modem_echo_can_page_sec_1 What does it do?
39 This module aims to cancel electrical echoes (e.g. from 2-4 wire hybrids)
40 in modem applications. It is not very suitable for speech applications, which
41 require additional refinements for satisfactory performance. It is, however, more
42 efficient and better suited to modem applications.
43
44 \section modem_echo_can_page_sec_2 How does it work?
45 The heart of the echo cancellor is an adaptive FIR filter. This is adapted to
46 match the impulse response of the environment being cancelled. It must be long
47 enough to adequately cover the duration of that impulse response. The signal
48 being transmitted into the environment being cancelled is passed through the
49 FIR filter. The resulting output is an estimate of the echo signal. This is
50 then subtracted from the received signal, and the result should be an estimate
51 of the signal which originates within the environment being cancelled (people
52 talking in the room, or the signal from the far end of a telephone line) free
53 from the echos of our own transmitted signal.
54
55 The FIR filter is adapted using the least mean squares (LMS) algorithm. This
56 algorithm is attributed to Widrow and Hoff, and was introduced in 1960. It is
57 the commonest form of filter adaption used in things like modem line equalisers
58 and line echo cancellers. It works very well if the signal level is constant,
59 which is true for a modem signal. To ensure good performa certain conditions must
60 be met:
61
62 - The transmitted signal has weak self-correlation.
63 - There is no signal being generated within the environment being cancelled.
64
65 The difficulty is that neither of these can be guaranteed. If the adaption is
66 performed while transmitting noise (or something fairly noise like, such as
67 voice) the adaption works very well. If the adaption is performed while
68 transmitting something highly correlative (e.g. tones, like DTMF), the adaption
69 can go seriously wrong. The reason is there is only one solution for the
70 adaption on a near random signal. For a repetitive signal, there are a number of
71 solutions which converge the adaption, and nothing guides the adaption to choose
72 the correct one.
73
74 \section modem_echo_can_page_sec_3 How do I use it?
75 The echo cancellor processes both the transmit and receive streams sample by
76 sample. The processing function is not declared inline. Unfortunately,
77 cancellation requires many operations per sample, so the call overhead is only a
78 minor burden.
79 */
80
81 #include "fir.h"
82
83 /*!
84 Modem line echo canceller descriptor. This defines the working state for a line
85 echo canceller.
86 */
87 typedef struct
88 {
89 int adapt;
90 int taps;
91
92 fir16_state_t fir_state;
93 /*! Echo FIR taps (16 bit version) */
94 int16_t *fir_taps16;
95 /*! Echo FIR taps (32 bit version) */
96 int32_t *fir_taps32;
97
98 int tx_power;
99 int rx_power;
100
101 int curr_pos;
102 } modem_echo_can_state_t;
103
104 /*! Create a modem echo canceller context.
105 \param len The length of the canceller, in samples.
106 eturn The new canceller context, or NULL if the canceller could not be created.
107 */
108 modem_echo_can_state_t *modem_echo_can_create(int len);
109
110 /*! Free a modem echo canceller context.
111 \param ec The echo canceller context.
112 */
113 void modem_echo_can_free(modem_echo_can_state_t *ec);
114
115 /*! Flush (reinitialise) a modem echo canceller context.
116 \param ec The echo canceller context.
117 */
118 void modem_echo_can_flush(modem_echo_can_state_t *ec);
119
120 /*! Set the adaption mode of a modem echo canceller context.
121 \param ec The echo canceller context.
122 \param adapt The mode.
123 */
124 void modem_echo_can_adaption_mode(modem_echo_can_state_t *ec, int adapt);
125
126 /*! Process a sample through a modem echo canceller.
127 \param ec The echo canceller context.
128 \param tx The transmitted audio sample.
129 \param rx The received audio sample.
130 eturn The clean (echo cancelled) received sample.
131 */
132 int16_t modem_echo_can_update(modem_echo_can_state_t *ec, int16_t tx, int16_t rx);
133
134 #endif
135 /*- End of file ------------------------------------------------------------*/

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