spandsp 0.0.6
|
00001 /* 00002 * SpanDSP - a series of DSP components for telephony 00003 * 00004 * modem_echo.h - An echo cancellor, suitable for electrical echos in GSTN modems 00005 * 00006 * Written by Steve Underwood <steveu@coppice.org> 00007 * 00008 * Copyright (C) 2001, 2004 Steve Underwood 00009 * 00010 * Based on a bit from here, a bit from there, eye of toad, 00011 * ear of bat, etc - plus, of course, my own 2 cents. 00012 * 00013 * All rights reserved. 00014 * 00015 * This program is free software; you can redistribute it and/or modify 00016 * it under the terms of the GNU Lesser General Public License version 2.1, 00017 * as published by the Free Software Foundation. 00018 * 00019 * This program is distributed in the hope that it will be useful, 00020 * but WITHOUT ANY WARRANTY; without even the implied warranty of 00021 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 00022 * GNU Lesser General Public License for more details. 00023 * 00024 * You should have received a copy of the GNU Lesser General Public 00025 * License along with this program; if not, write to the Free Software 00026 * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. 00027 */ 00028 00029 /*! \file */ 00030 00031 #if !defined(_SPANDSP_MODEM_ECHO_H_) 00032 #define _SPANDSP_MODEM_ECHO_H_ 00033 00034 /*! \page modem_echo_can_page Line echo cancellation for modems 00035 00036 \section modem_echo_can_page_sec_1 What does it do? 00037 This module aims to cancel electrical echoes (e.g. from 2-4 wire hybrids) 00038 in modem applications. It is not very suitable for speech applications, which 00039 require additional refinements for satisfactory performance. It is, however, more 00040 efficient and better suited to modem applications. 00041 00042 \section modem_echo_can_page_sec_2 How does it work? 00043 The heart of the echo cancellor is an adaptive FIR filter. This is adapted to 00044 match the impulse response of the environment being cancelled. It must be long 00045 enough to adequately cover the duration of that impulse response. The signal 00046 being transmitted into the environment being cancelled is passed through the 00047 FIR filter. The resulting output is an estimate of the echo signal. This is 00048 then subtracted from the received signal, and the result should be an estimate 00049 of the signal which originates within the environment being cancelled (people 00050 talking in the room, or the signal from the far end of a telephone line) free 00051 from the echos of our own transmitted signal. 00052 00053 The FIR filter is adapted using the least mean squares (LMS) algorithm. This 00054 algorithm is attributed to Widrow and Hoff, and was introduced in 1960. It is 00055 the commonest form of filter adaption used in things like modem line equalisers 00056 and line echo cancellers. It works very well if the signal level is constant, 00057 which is true for a modem signal. To ensure good performa certain conditions must 00058 be met: 00059 00060 - The transmitted signal has weak self-correlation. 00061 - There is no signal being generated within the environment being cancelled. 00062 00063 The difficulty is that neither of these can be guaranteed. If the adaption is 00064 performed while transmitting noise (or something fairly noise like, such as 00065 voice) the adaption works very well. If the adaption is performed while 00066 transmitting something highly correlative (e.g. tones, like DTMF), the adaption 00067 can go seriously wrong. The reason is there is only one solution for the 00068 adaption on a near random signal. For a repetitive signal, there are a number of 00069 solutions which converge the adaption, and nothing guides the adaption to choose 00070 the correct one. 00071 00072 \section modem_echo_can_page_sec_3 How do I use it? 00073 The echo cancellor processes both the transmit and receive streams sample by 00074 sample. The processing function is not declared inline. Unfortunately, 00075 cancellation requires many operations per sample, so the call overhead is only a 00076 minor burden. 00077 */ 00078 00079 #include "fir.h" 00080 00081 /*! 00082 Modem line echo canceller descriptor. This defines the working state for a line 00083 echo canceller. 00084 */ 00085 typedef struct modem_echo_can_state_s modem_echo_can_state_t; 00086 00087 #if defined(__cplusplus) 00088 extern "C" 00089 { 00090 #endif 00091 00092 /*! Create a modem echo canceller context. 00093 \param len The length of the canceller, in samples. 00094 eturn The new canceller context, or NULL if the canceller could not be created. 00095 */ 00096 SPAN_DECLARE(modem_echo_can_state_t *) modem_echo_can_init(int len); 00097 00098 /*! Free a modem echo canceller context. 00099 \param ec The echo canceller context. 00100 */ 00101 SPAN_DECLARE(void) modem_echo_can_free(modem_echo_can_state_t *ec); 00102 00103 /*! Flush (reinitialise) a modem echo canceller context. 00104 \param ec The echo canceller context. 00105 */ 00106 SPAN_DECLARE(void) modem_echo_can_flush(modem_echo_can_state_t *ec); 00107 00108 /*! Set the adaption mode of a modem echo canceller context. 00109 \param ec The echo canceller context. 00110 \param adapt The mode. 00111 */ 00112 SPAN_DECLARE(void) modem_echo_can_adaption_mode(modem_echo_can_state_t *ec, int adapt); 00113 00114 /*! Process a sample through a modem echo canceller. 00115 \param ec The echo canceller context. 00116 \param tx The transmitted audio sample. 00117 \param rx The received audio sample. 00118 eturn The clean (echo cancelled) received sample. 00119 */ 00120 SPAN_DECLARE(int16_t) modem_echo_can_update(modem_echo_can_state_t *ec, int16_t tx, int16_t rx); 00121 00122 #if defined(__cplusplus) 00123 } 00124 #endif 00125 00126 #endif 00127 /*- End of file ------------------------------------------------------------*/