spandsp: modem_echo.h Source File

spandsp 0.0.6

modem_echo.h
Go to the documentation of this file.
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
29/*! \file */
30
31#if !defined(_SPANDSP_MODEM_ECHO_H_)
32#define _SPANDSP_MODEM_ECHO_H_
33
34/*! \page modem_echo_can_page Line echo cancellation for modems
35
36\section modem_echo_can_page_sec_1 What does it do?
37This module aims to cancel electrical echoes (e.g. from 2-4 wire hybrids)
38in modem applications. It is not very suitable for speech applications, which
39require additional refinements for satisfactory performance. It is, however, more
40efficient and better suited to modem applications.
41
42\section modem_echo_can_page_sec_2 How does it work?
43The heart of the echo cancellor is an adaptive FIR filter. This is adapted to
44match the impulse response of the environment being cancelled. It must be long
45enough to adequately cover the duration of that impulse response. The signal
46being transmitted into the environment being cancelled is passed through the
47FIR filter. The resulting output is an estimate of the echo signal. This is
48then subtracted from the received signal, and the result should be an estimate
49of the signal which originates within the environment being cancelled (people
50talking in the room, or the signal from the far end of a telephone line) free
51from the echos of our own transmitted signal.
52
53The FIR filter is adapted using the least mean squares (LMS) algorithm. This
54algorithm is attributed to Widrow and Hoff, and was introduced in 1960. It is
55the commonest form of filter adaption used in things like modem line equalisers
56and line echo cancellers. It works very well if the signal level is constant,
57which is true for a modem signal. To ensure good performa certain conditions must
58be met:
59
60 - The transmitted signal has weak self-correlation.
61 - There is no signal being generated within the environment being cancelled.
62
63The difficulty is that neither of these can be guaranteed. If the adaption is
64performed while transmitting noise (or something fairly noise like, such as
65voice) the adaption works very well. If the adaption is performed while
66transmitting something highly correlative (e.g. tones, like DTMF), the adaption
67can go seriously wrong. The reason is there is only one solution for the
68adaption on a near random signal. For a repetitive signal, there are a number of
69solutions which converge the adaption, and nothing guides the adaption to choose
70the correct one.
71
72\section modem_echo_can_page_sec_3 How do I use it?
73The echo cancellor processes both the transmit and receive streams sample by
74sample. The processing function is not declared inline. Unfortunately,
75cancellation requires many operations per sample, so the call overhead is only a
76minor burden.
77*/
78
79#include "fir.h"
80
81/*!
82 Modem line echo canceller descriptor. This defines the working state for a line
83 echo canceller.
84*/
85 typedef struct modem_echo_can_state_s modem_echo_can_state_t;
86
87#if defined(__cplusplus)
88extern "C"
89{
90#endif
91
92/*! Create a modem echo canceller context.
93 \param len The length of the canceller, in samples.
94 eturn The new canceller context, or NULL if the canceller could not be created.
95*/
96SPAN_DECLARE(modem_echo_can_state_t *) modem_echo_can_init(int len);
97
98/*! Free a modem echo canceller context.
99 \param ec The echo canceller context.
100*/
101SPAN_DECLARE(void) modem_echo_can_free(modem_echo_can_state_t *ec);
102
103/*! Flush (reinitialise) a modem echo canceller context.
104 \param ec The echo canceller context.
105*/
106SPAN_DECLARE(void) modem_echo_can_flush(modem_echo_can_state_t *ec);
107
108/*! Set the adaption mode of a modem echo canceller context.
109 \param ec The echo canceller context.
110 \param adapt The mode.
111*/
112SPAN_DECLARE(void) modem_echo_can_adaption_mode(modem_echo_can_state_t *ec, int adapt);
113
114/*! Process a sample through a modem echo canceller.
115 \param ec The echo canceller context.
116 \param tx The transmitted audio sample.
117 \param rx The received audio sample.
118 eturn The clean (echo cancelled) received sample.
119*/
120SPAN_DECLARE(int16_t) modem_echo_can_update(modem_echo_can_state_t *ec, int16_t tx, int16_t rx);
121
122#if defined(__cplusplus)
123}
124#endif
125
126#endif
127/*- End of file ------------------------------------------------------------*/
modem_echo_can_adaption_mode
void modem_echo_can_adaption_mode(modem_echo_can_state_t *ec, int adapt)
Definition modem_echo.c:110
modem_echo_can_init
modem_echo_can_state_t * modem_echo_can_init(int len)
Definition modem_echo.c:65
modem_echo_can_flush
void modem_echo_can_flush(modem_echo_can_state_t *ec)
Definition modem_echo.c:98
modem_echo_can_free
void modem_echo_can_free(modem_echo_can_state_t *ec)
Definition modem_echo.c:56
modem_echo_can_update
int16_t modem_echo_can_update(modem_echo_can_state_t *ec, int16_t tx, int16_t rx)
Definition modem_echo.c:116
modem_echo_can_state_s
Definition private/modem_echo.h:39