Mercurial > hg > audiostuff
comparison spandsp-0.0.6pre17/src/spandsp/modem_echo.h @ 4:26cd8f1ef0b1
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 * 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 Lesser General Public License version 2.1, | |
17 * as 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 Lesser General Public License for more details. | |
23 * | |
24 * You should have received a copy of the GNU Lesser General Public | |
25 * License 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.14 2009/09/22 13:11:04 steveu Exp $ | |
29 */ | |
30 | |
31 /*! \file */ | |
32 | |
33 #if !defined(_SPANDSP_MODEM_ECHO_H_) | |
34 #define _SPANDSP_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 modem_echo_can_state_s modem_echo_can_state_t; | |
88 | |
89 #if defined(__cplusplus) | |
90 extern "C" | |
91 { | |
92 #endif | |
93 | |
94 /*! Create a modem echo canceller context. | |
95 \param len The length of the canceller, in samples. | |
96 eturn The new canceller context, or NULL if the canceller could not be created. | |
97 */ | |
98 SPAN_DECLARE(modem_echo_can_state_t *) modem_echo_can_create(int len); | |
99 | |
100 /*! Free a modem echo canceller context. | |
101 \param ec The echo canceller context. | |
102 */ | |
103 SPAN_DECLARE(void) modem_echo_can_free(modem_echo_can_state_t *ec); | |
104 | |
105 /*! Flush (reinitialise) a modem echo canceller context. | |
106 \param ec The echo canceller context. | |
107 */ | |
108 SPAN_DECLARE(void) modem_echo_can_flush(modem_echo_can_state_t *ec); | |
109 | |
110 /*! Set the adaption mode of a modem echo canceller context. | |
111 \param ec The echo canceller context. | |
112 \param adapt The mode. | |
113 */ | |
114 SPAN_DECLARE(void) modem_echo_can_adaption_mode(modem_echo_can_state_t *ec, int adapt); | |
115 | |
116 /*! Process a sample through a modem echo canceller. | |
117 \param ec The echo canceller context. | |
118 \param tx The transmitted audio sample. | |
119 \param rx The received audio sample. | |
120 eturn The clean (echo cancelled) received sample. | |
121 */ | |
122 SPAN_DECLARE(int16_t) modem_echo_can_update(modem_echo_can_state_t *ec, int16_t tx, int16_t rx); | |
123 | |
124 #if defined(__cplusplus) | |
125 } | |
126 #endif | |
127 | |
128 #endif | |
129 /*- End of file ------------------------------------------------------------*/ |