Mercurial > hg > audiostuff
comparison spandsp-0.0.3/README.txt @ 5:f762bf195c4b
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 Open Source Line Echo Canceller (OSLEC) | |
2 ======================================= | |
3 | |
4 [[introduction]] | |
5 Introduction | |
6 ------------ | |
7 | |
8 Oslec is an open source high performance line echo canceller. When | |
9 used with Asterisk it works well on lines where the built-in Zaptel | |
10 echo canceller fails. No tweaks like rxgain/txgain or fxotrain are | |
11 required. Oslec is supplied as GPL licensed C source code and is free | |
12 as in speech. | |
13 | |
14 Oslec partially complies with the G168 standard and runs in real time | |
15 on x86 and Blackfin platforms. Patches exist to allow any Zaptel | |
16 compatible hardware to use Oslec. It has been successfully tested on | |
17 hardware ranging from single port X100P FXO cards to dual E1 systems. | |
18 Hardware tested includes TDM400, X100P, Sangoma A104, Rhino E1 etc. | |
19 It also works well on the link:ip04.html[IP04 embedded Asterisk | |
20 platform]. | |
21 | |
22 There is also a project underway to use | |
23 http://peter.schlaile.de/mISDN/[OSLEC with mISDN]. | |
24 | |
25 Oslec is included in many distributions, including Debian, Gentoo, | |
26 Trixbox, Elastix, and Callweaver. | |
27 | |
28 [[testimonials]] | |
29 Testimonials | |
30 ------------ | |
31 | |
32 So how good is Oslec? | |
33 | |
34 + The http://www.trixbox[Trixbox] community have been testing | |
35 Oslec, here is a | |
36 http://www.trixbox.org/forums/trixbox-forums/open-discussion/need-people-echo-problems[Trixbox | |
37 forum thread] that has feedback from many people. Start about half | |
38 way down the page, or search on the string "night and day" :-) | |
39 | |
40 + The http://callweaver.org/wiki/Zaptel[CallWeaver] project use and recommend Oslec. | |
41 | |
42 + Here is some feedback from Oslec users: | |
43 | |
44 [Gordon Henderson, posted in the Asterisk-user mailing list July 21 2008] | |
45 | |
46 ________________________________________________________________________ | |
47 I switched to OSLEC after testing HPEC on TDM400 boards, and found that it | |
48 worked much better and wasn't limited to the restricted mechanism Digium | |
49 uses for licensing (unlikely as it sounds, I have some clients who do not | |
50 have a connection to the public Internet, and never will for their phone | |
51 system) | |
52 | |
53 It also passes the wife test which HPEC didn't. | |
54 | |
55 It's also free (OS as in Open Source), which HPEC isn't, although that | |
56 wasn't my primary reason for using it - ease of use and "workability" was. | |
57 _____________________________________________________________________ | |
58 | |
59 [Michael Gernoth, Author of the Zaptel MG2 echo canceller] | |
60 | |
61 ________________________________________________________________________ | |
62 Thanks for OSLEC, it's so much better than my hacked KB1 which is called | |
63 MG2 :-) | |
64 _____________________________________________________________________ | |
65 | |
66 [David Gottschalk] | |
67 | |
68 ________________________________________________________________________ | |
69 Once I managed to get OSLEC installed (it was a big job for me, because I was | |
70 missing many of the dependancies and knowledge), it immediately fixed the echo | |
71 problems I had been unable to get rid of to date despite lots and lots of | |
72 tweeks, tests and fiddling. Even more suprisingly, it appears to converge | |
73 almost immediately from my initial test. | |
74 | |
75 This code is the best since thing since, well, Asterisk !!! | |
76 _____________________________________________________________________ | |
77 | |
78 [Nic Bellamy, Head Of Engineering; Vadacom Ltd] | |
79 | |
80 ________________________________________________________________________ | |
81 Short version: KB1 < MG2 < OSLEC < HPEC | |
82 | |
83 In the open source line echo canceller category, OSLEC is so far the | |
84 best I've seen. | |
85 | |
86 It converges reasonably fast, and thanks to it's dual-path approach, | |
87 will converge, albeit a bit slowly, on nasty echo paths where cancellers | |
88 like KB1 and MG2 will fail entirely. | |
89 | |
90 The nonlinear processor and comfort noise generator provide for a far | |
91 more pleasant listening experience than KB1/MG2. | |
92 | |
93 It's not quite up to the grade of ADT's G.168 canceller used in Digiums | |
94 HPEC product in terms of convergence speed or tail coverage. | |
95 _____________________________________________________________________ | |
96 | |
97 [Pawel Pastuszak, Astfin.org] | |
98 | |
99 ________________________________________________________________________ | |
100 Since I installed the first version of OSLEC I was hooked.... It's | |
101 been several months now since the alpha version was released; after | |
102 using OSLEC Mark and I agreed that we had to have OSLEC as the main | |
103 echo cancellation in the Astfin distribution. | |
104 ________________________________________________________________________ | |
105 | |
106 [Pavel Selivano, Parabel Ltd] | |
107 | |
108 ________________________________________________________________________ | |
109 I've been working with Oslec since March of 2007. Oslec has had some | |
110 problems, but, thanks to David, they are solved. Now, I can say Oslec | |
111 is time-tested. The best, I can note - it is still under development | |
112 (with feed-back). Thank you David for your good deed. | |
113 | |
114 BTW: comparison to Intel IPP's echo canceler have shown, Oslec is very | |
115 good :-) | |
116 ________________________________________________________________________ | |
117 | |
118 | |
119 [[news]] | |
120 Oslec News | |
121 ---------- | |
122 | |
123 + Saturday, June 7, 2008: We have worked out how to use <<rhino,Oslec with | |
124 Rhino>> PRI cards. Thanks Juan Manuel Coronado! | |
125 | |
126 + Friday, May 16, 2008: Oslec Road Map. I have kicked off a | |
127 discussion of the | |
128 http://sourceforge.net/mailarchive/forum.php?thread_name=1210895745.7127.60.camel%40localhost&forum_name=freetel-oslec[development | |
129 roadmap] for Oslec. Is hardware echo cancellation headed for | |
130 extinction? | |
131 | |
132 + Friday, May 16, 2008: Oslec chosen as the **default** | |
133 http://sourceforge.net/mailarchive/forum.php?thread_name=20080515131239.GJ27523%40xorcom.com&forum_name=freetel-oslec[echo | |
134 canceler for Debian]. Thanks Tzafrir for your work on packaging Oslec | |
135 for Debian! | |
136 | |
137 + Tuesday, May 13, 2008: link:/blog/?p=64[Oslec versus the SPA 3000] | |
138 ATA. A blog post comparing the SPA 3000 echo cancellation to Oslec on | |
139 a problem FXO line. | |
140 | |
141 + Wednesday, February 11, 2008: Oslec mailing list created. Due to | |
142 popular demand (well, Tzafrir mainly!) there is now an | |
143 https://lists.sourceforge.net/lists/listinfo/freetel-oslec[Oslec | |
144 mailing list]. | |
145 | |
146 + Sunday, February 10, 2008: Zaptel 1.4.8 patch checked into SVN, | |
147 thanks Tzafrir. | |
148 | |
149 [[install]] | |
150 Installing OSLEC with Asterisk/Zaptel | |
151 -------------------------------------- | |
152 | |
153 Notes: | |
154 | |
155 + This process also installs a system for sampling echo signals that | |
156 is helpful for developing oslec. | |
157 | |
158 + I assume Asterisk is already installed and tested. | |
159 | |
160 + I assume you are running Linux 2.6 and Zaptel 1.2.13 or a later | |
161 1.2/1.4 version of Zaptel. | |
162 | |
163 + I assume you are using a Digium TDM400 line interface card. Change | |
164 the "insmod wctdm.ko" line below to match your line interface | |
165 hardware (e.g. wcfxo for a X100P). | |
166 | |
167 + For Zaptel 1.4.x replace the 1.2.13 text below 1.4.x (tar ball and | |
168 patch file). | |
169 | |
170 + For Linux 2.4 replace the "insmod moduleXYZ.ko" lines below with | |
171 "insmod moduleXYZ.o". | |
172 | |
173 1/ Download, build and install oslec: | |
174 | |
175 $ cd ~ | |
176 $ wget http://www.rowetel.com/ucasterisk/downloads/oslec-0.1.tar.gz | |
177 $ tar xvzf oslec-0.1.tar.gz | |
178 $ cd oslec-0.1 | |
179 $ make | |
180 $ insmod kernel/oslec.ko | |
181 | |
182 Optional: If you want the latest and greatest, replace the "wget" step | |
183 with: | |
184 | |
185 $ svn co http://svn.astfin.org/software/oslec/trunk/ oslec | |
186 | |
187 NOTE: There are patches for Zaptel 1.2.13, 1.2.18, 1.2.24, 1.4.1, | |
188 1.4.3, 1.4.4, 1.4.7.1, 1.4.8, 1.4.9.2 and 1.4.11. It's quite easy to | |
189 port to other versions, please feel free to send me a new patch should | |
190 you get Oslec working with another Zaptel version. If you can't see a | |
191 patch for your Zaptel version try | |
192 http://svn.astfin.org/software/oslec/trunk/kernel[Oslec SVN] for the | |
193 latest patches. | |
194 | |
195 2/ Build, patch and install Zaptel. First obtain zaptel-1.2.13.tar.gz and: | |
196 | |
197 $ tar xvzf zaptel-1.2.13.tar.gz | |
198 $ cd zaptel-1.2.13 | |
199 $ ./configure | |
200 $ patch < ../oslec-0.1/kernel/zaptel-1.2.13.patch (see note 1 below) | |
201 $ cp ../oslec-0.1/kernel/dir/Module.symvers . (see note 2 below) | |
202 $ make | |
203 $ insmod zaptel.ko | |
204 $ insmod wctdm.ko | |
205 $ ./ztcfg | |
206 $ asterisk | |
207 | |
208 NOTE: 1: Use -p1 option for zaptel-1.4.9.2 and above | |
209 | |
210 NOTE: 2: The "cp Module.symvers" step above is optional on many systems; | |
211 it stops warnings like WARNING: "oslec_echo_can_create" [zaptel.ko] | |
212 undefined!". However on some Linux machines zaptel will not compile | |
213 without this step. | |
214 | |
215 3/ These options in zapata.conf are important: | |
216 | |
217 --------------------------------------------------------------------- | |
218 echocancel=yes | |
219 echocancelwhenbridged=no | |
220 ;echotraining=400 | |
221 --------------------------------------------------------------------- | |
222 | |
223 The *echocancelwhenbridged=no* allows faxes to pass from FXS to FXO | |
224 ports without interference from the echo canceller. This option is | |
225 important for fax signals. | |
226 | |
227 Make sure *echotraining* is disabled when using Oslec - this is not | |
228 supported and if enabled will cause the channel to be silent (i.e. no | |
229 audio will pass through). | |
230 | |
231 4/ The settings above have been shown to reliably cancel echo in 95% | |
232 of cases. If you can still hear echo you may have one of the rare | |
233 cases where your echo is longer than 16ms. To configure Oslec with a | |
234 32ms tail: | |
235 | |
236 --------------------------------------------------------------------- | |
237 echocancel=256 | |
238 echocancelwhenbridged=no | |
239 ;echotraining=400 | |
240 --------------------------------------------------------------------- | |
241 | |
242 Then restart Asterisk. | |
243 | |
244 [[pbxinaflash]] | |
245 PBX in a Flash Install | |
246 ---------------------- | |
247 | |
248 Here are the | |
249 http://pbxinaflash.com/forum/showthread.php?t=100&page=3[Oslec install | |
250 procedure] for PBX in a Flash. Check the 7-24-08 post in this thread | |
251 by Alex728 for Zaptel-1.4.11 instructions. Thanks JD Austin and Alex. | |
252 | |
253 Matt Keys has suggested that the PBX in a Flash install procedure also | |
254 worked well for Ubuntu server. | |
255 | |
256 [[rhino]] | |
257 Rhino PRI cards | |
258 --------------- | |
259 | |
260 The rhino-2.2.6 driver for Rhino PRI cards has software echo | |
261 cancellation disabled by default. This means there is no echo | |
262 cancellation unless you opt for the Rhino hardware echo cancellation | |
263 module. However the driver is easy to hack to enable software echo | |
264 cancellation, and hence Oslec. | |
265 | |
266 In the rhino-2.2.6 driver, file r1t1_base.c, r1t1_receiveprep | |
267 function, around line 800: | |
268 | |
269 --------------------------------------------------------------------- | |
270 static void r1t1_receiveprep(struct r1t1 *rh, int nextbuf) | |
271 { | |
272 /* | |
273 int x; | |
274 | |
275 for (x=0;x<rh->span.channels;x++) { | |
276 zt_ec_chunk(&rh->chans[x], rh->chans[x].readchunk, rh->ec_chunk2[x]); | |
277 memcpy(rh->ec_chunk2[x],rh->ec_chunk1[x],ZT_CHUNKSIZE); | |
278 memcpy(rh->ec_chunk1[x],rh->chans[x].writechunk,ZT_CHUNKSIZE); | |
279 } | |
280 */ | |
281 zt_receive(&rh->span); | |
282 } | |
283 --------------------------------------------------------------------- | |
284 | |
285 **Solution 1:** Simply un-comment the code and rebuild the driver: | |
286 | |
287 --------------------------------------------------------------------- | |
288 static void r1t1_receiveprep(struct r1t1 *rh, int nextbuf) | |
289 { | |
290 | |
291 int x; | |
292 | |
293 for (x=0;x<rh->span.channels;x++) { | |
294 zt_ec_chunk(&rh->chans[x], rh->chans[x].readchunk, rh->ec_chunk2[x]); | |
295 memcpy(rh->ec_chunk2[x],rh->ec_chunk1[x],ZT_CHUNKSIZE); | |
296 memcpy(rh->ec_chunk1[x],rh->chans[x].writechunk,ZT_CHUNKSIZE); | |
297 } | |
298 | |
299 zt_receive(&rh->span); | |
300 } | |
301 --------------------------------------------------------------------- | |
302 | |
303 **Solution 2:** Bob Conklin from Rhino has suggested this fix that | |
304 they have in SVN trunk: | |
305 | |
306 --------------------------------------------------------------------- | |
307 static void r1t1_receiveprep(struct r1t1 *rh, int nextbuf) | |
308 { | |
309 if (!rh->dsp_up) | |
310 zt_ec_span(&rh->span); | |
311 zt_receive(&rh->span); | |
312 } | |
313 --------------------------------------------------------------------- | |
314 | |
315 This version automatically falls back to software echo cancellation if | |
316 the DSP-based hardware echo cancellation is not present. Thanks | |
317 Bob! | |
318 | |
319 [[status]] | |
320 Status | |
321 ------ | |
322 | |
323 Current status is considered *Stable*. As of 3 January 2008: | |
324 | |
325 + Thousands of people (estimated) using Oslec on x86 platforms now. | |
326 Oslec is stable and works well. Oslec has been included in many | |
327 distributions, including Debian, Gentoo, Trixbox, Elastix, and | |
328 Callweaver. | |
329 | |
330 + Oslec works well on many different types of hardware, from single | |
331 port $10 X100P cards to dual E1s. | |
332 | |
333 + Oslec has been partially optimised for the embedded Blackfin | |
334 DSP/RISC CPU and now runs in real time on the link:ip04.html[IP04 Open | |
335 Hardware IP-PBX]. Running on several hundred IP04s now. | |
336 | |
337 + Real time runs well on FXO/FXS lines where the other Zaptel echo | |
338 cancellers (including the latest MG2) struggle. No tweaks like | |
339 levels, fxotrain, or even opermode required so far. Hardware used for | |
340 tests was a TDM400 and X100P card. | |
341 | |
342 + The simulation code passes many but not all of the G168 tests. | |
343 Some problems with high level signals near 0dBm0 and some of the G168 | |
344 echo models. Passes maybe 90% of the tests attempted so far, however | |
345 not all of the tests and/or range of test conditions have been | |
346 attempted yet. The fails are close calls (like a few dB off), not | |
347 complete breakdowns of the algorithm. | |
348 | |
349 + Oslec has been specifically developed to work with low cost line | |
350 interface hardware like the X100P. The X100P has problems with 60Hz | |
351 hum and DC offset in the rx signal, which interfere with the echo | |
352 canceller algorithm. However with the addition of some high pass | |
353 filters good results with X100P cards have been obtained using Oslec. | |
354 Line interfaces based on chips such as those from Silicon Labs | |
355 (e.g. the TDM400) have no DC offset or hum which is one reason they | |
356 tend to perform better. | |
357 | |
358 + Oslec has been optimised to deal with specific problems encountered | |
359 with soft phone clients. Due to the high quality microphones and | |
360 sound blaster hardware used on PCs, more low frequency energy is | |
361 present compared to normal telephone signals. When this low frequency | |
362 energy is sent to a hybrid it can force the hybrid into a non linear | |
363 mode. Echo cancellers assume a linear hybrid so any non-linearities | |
364 make the echo canceller fall over. The solution is to high pass | |
365 filter energy sent to the hybrid to ensure excessive low frequency | |
366 energy is removed. This means inserting a HP filter in the tx path. | |
367 | |
368 [[directories]] | |
369 Directories | |
370 ----------- | |
371 | |
372 The http://svn.astfin.org/software/oslec/trunk/[Oslec SVN repository] | |
373 combines several projects (mainly spandsp) used to develop, test, and | |
374 run oslec. | |
375 | |
376 spandsp : A subset of spandsp to support testing and development of | |
377 Oslec. The echo canceller and G168 test suite source code | |
378 live in here. | |
379 | |
380 user....: User mode apps, e.g. sampling of echo signals and a unit | |
381 test for measuring the execution speed of Oslec. | |
382 | |
383 kernel..: Builds Oslec into a kernel module. Also contains patches for | |
384 Zaptel to allow the use of Oslec. | |
385 | |
386 [[diagnostics]] | |
387 Run Time Information | |
388 -------------------- | |
389 | |
390 Set up a call that uses an analog port, then check out /proc/oslec for | |
391 real-time stats: | |
392 | |
393 [root@homework kernel]# cat /proc/oslec/info | |
394 channels....: 1 | |
395 mode........: [13] |ADAPTION|NLP|CNG| | |
396 Ltx.........: 0 | |
397 Lrx.........: 211 | |
398 Lclean......: 211 | |
399 Lclean_bg...: 211 | |
400 shift.......: 0 | |
401 Double Talk.: 1 | |
402 MIPs (last)....: 1 | |
403 MIPs (worst)...: 7 | |
404 MIPs (avergage): 1 | |
405 | |
406 You can turn the various mode switches off and on, for example: | |
407 | |
408 echo 9 > /proc/oslec/mode | |
409 | |
410 turns off comfort noise, but keeps ADAPT and NLP on. The mode | |
411 switches are listed in the | |
412 http://svn.astfin.org/software/oslec/trunk/spandsp-0.0.3/src/spandsp/echo.h[echo.h] | |
413 header file (#define ECHO_CAN_USE_*). The /proc interface only | |
414 monitors the first Zaptel call you bring up, see | |
415 http://svn.astfin.org/software/oslec/trunk/kernel/oslec_wrap.c[oslec_wrap.c] | |
416 for more information. | |
417 | |
418 There is a GUI for run-time control of Oslec, called the Oslec Control | |
419 Panel. For example you can Enable and Disable the echo canceller in | |
420 real time, as you are speaking. If you Reset the echo canceller you | |
421 can hear how long it takes to converge again. | |
422 | |
423 NOTE: The command line tool *dialog* must be installed on your system | |
424 to use the Oslec Control Panel. | |
425 | |
426 $ cd kernel | |
427 $ ./oslec-ctrl-panel.sh | |
428 | |
429 image::/images/echo/oslec_control_panel.png[Oslec Control Panel] | |
430 | |
431 [[speed]] | |
432 Execution Speed and Optimisation | |
433 -------------------------------- | |
434 | |
435 In the user directory there is a | |
436 http://svn.astfin.org/software/oslec/trunk/user/speedtest.c[speedtest.c] | |
437 program that measures how many MIPs the echo canceller consumes and | |
438 estimates how many cancellers can run in real time. The current x86 | |
439 code is vanilla C and could be greatly improved with MMX or SSE | |
440 optimisations, some of which are already coded in spandsp. There is | |
441 also much that can be done to improve execution speed on the Blackfin. | |
442 | |
443 Steve's spandsp code includes some support for MMX and SSE2 | |
444 optimisation. Define USE_MMX or USE_SSE2 in the Makefile to use this | |
445 option. At this stage only the fir.h filter code is optimised, oslec | |
446 would run much faster if lms_adapt_bg() in echo.c was also ported to | |
447 MMX/SSE2. With USE_MMX defined, the speedtest.c program dropped from | |
448 33 MIPs to 20 MIPs per channel for 256 taps/32ms. If using MMX in the | |
449 kernel (e.g. with zaptel) make sure you compile zaptel with | |
450 CONFIG_ZAPTEL_MMX to ensure the FPU state is saved in the right | |
451 places. | |
452 | |
453 To enable MMX/SSE modify this line of oslec/kernel/Makefile: | |
454 | |
455 ---------------------------------------------- | |
456 | |
457 all:: | |
458 $(MAKE) -C $(KDIR) EXTRA_CFLAGS='$(KINCLUDE) \ | |
459 -DUSE_MMX -DUSE_SSE2 -DEXPORT_SYMTAB -O6' \ | |
460 SUBDIRS=$(PWD) modules | |
461 | |
462 ---------------------------------------------- | |
463 | |
464 Thanks Nic Bellamy for help in testing MMX and Ming-Ching Tiew for | |
465 providing the correct command line for compiling with MMX/SSE. | |
466 | |
467 Some notes on further optimisation: | |
468 | |
469 1/ How do lots of MIPs in ISR affect total system performance? For | |
470 example if we are using 25% of MIP in ISR does * still run OK? Find the | |
471 CPU load knee different for user versus kernel mode cycles | |
472 consumption. | |
473 | |
474 2/ Estimated Oslec MIPs are 5(N)(Fs), N is the filter size (number of | |
475 taps), Fs=8000 is the sampling rate. Factor of 5 is comprised of 1 | |
476 for each FIR filter (forgeround and background), 2 for LMS, 1 for overhead. | |
477 This suggests that when optimised around 10 MIPs for a 32ms tail. | |
478 | |
479 3/ There are some more notes on optimisation for the Blackfin in | |
480 http://svn.astfin.org/software/oslec/trunk/spandsp-0.0.3/src/echo.c[echo.c]. | |
481 | |
482 [[credits]] | |
483 Background and Credits | |
484 ---------------------- | |
485 | |
486 Oslec started life as a prototype echo canceller and G168 test | |
487 framework from Steve Underwood's http://www.soft-switch.org/[Spandsp] | |
488 library. Steve wrote much of the DSP code used in Asterisk, and the | |
489 Zaptel echo cancellation code is heavily based on his work. | |
490 | |
491 Using the Spandsp G168 test framework, a high performance echo | |
492 canceller has been developed and carefully tested. Working together | |
493 with alpha testers the performance was brought to a beta state in June | |
494 2005. <<links,More>>. Since then many thousands of people have | |
495 installed Oslec. | |
496 | |
497 Thanks to Steve Underwood, Jean-Marc Valin, and Ramakrishnan | |
498 Muthukrishnan for their suggestions and email discussions. Thanks | |
499 also to those people who collected echo samples for me such as Mark, | |
500 Pawel, and Pavel. Thanks Nic Bellamy for help with testing, | |
501 explanation of long path issues, and MMX support. Thanks Tzafrir for | |
502 testing and patches/enhancements and Dmitry for help with | |
503 multithreaded and locking issues. | |
504 | |
505 Thanks Vieri for finding a circuit with a tail > 32ms, and Patrick for | |
506 submitting a Zaptel 1.2.18 patch. Thanks Dave Fullerton and Carlton | |
507 O'Riley for Zaptel 1.4.3/1.4.4 patches. Thanks Bill Salibrici for | |
508 finding a memory leak. Thanks Michael E. Kromer for submitting a | |
509 Zaptel 1.4.7.1 patch, and Tzafrir for the Zaptel 1.4.8 patch. Thanks | |
510 Russ Price for the Zaptel 1.2.24 patch. Thanks Chris Notley for the | |
511 1.4.11 patch. | |
512 | |
513 Thanks to Peter Schlaile for porting Oslec to mISDN. Thanks also to | |
514 Kristijan Vrban for sending me some ISDN hardware so I can help with | |
515 the ISDN/Oslec testing! | |
516 | |
517 Thanks to Tzafrir and Faidon for helping debug the muted audio | |
518 problems on 64 bit systems. | |
519 | |
520 Thanks Rudolf E. Steiner for testing Oslec on SMP and multiple E1 | |
521 systems. | |
522 | |
523 [[sample]] | |
524 Sampling Zaptel Echo | |
525 -------------------- | |
526 | |
527 Introduction | |
528 ~~~~~~~~~~~~ | |
529 | |
530 I have developed a system for sampling echo on running Zaptel/Asterisk | |
531 systems. If you do experience any echo with Oslec, please use this | |
532 system to sample the echo, then email the sample files to me. | |
533 | |
534 See the http://www.rowetel.com/blog/?p=18[Part 1 blog post] for more | |
535 information on sampling echo. | |
536 | |
537 The nice thing about is that it doesn't interfere with your running | |
538 Asterisk system. If you hear echo at any time you can fire up a | |
539 console and run "sample" to capture real-time data from the Zaptel | |
540 port. | |
541 | |
542 There are other ways to capture audio from a running Asterisk system, | |
543 for example using the built in Asterisk play and record applications. | |
544 However this system is designed to capture *exactly* the signals being | |
545 fed to & from the echo canceller - preserving the exact timing of the | |
546 signals and with no intermediate buffering. This is very important | |
547 for echo cancellation work - the algorithms depend on an exact timing | |
548 relationship between the transmit and receive signals. | |
549 | |
550 The system simultaneously captures the receive signal both before | |
551 *and* after the echo canceller - something that is difficult to do | |
552 with the built in Asterisk functions due to the location of the echo | |
553 canceller deep in the Zaptel driver. | |
554 | |
555 If you would like to help further develop Oslec, please | |
556 mailto:david_at_rowetel_dot_com[send me] your echo samples! I would | |
557 welcome any samples of your echo signals, for example where the echo | |
558 canceller isn't working well, and also cases where it does work | |
559 well. By comparing the two cases we can learn a lot about the | |
560 strengths and weaknesses of the algorithm. | |
561 | |
562 Installing | |
563 ~~~~~~~~~~ | |
564 | |
565 1/ Install Oslec ("HowTo - Run OSLEC with Asterisk/Zaptel" section above). | |
566 | |
567 2/ If you would like to use zaptap without oslec change the selected | |
568 echo canceller in zconfig.c and rebuild/install zaptel. | |
569 | |
570 3/ Compile sample.c: | |
571 | |
572 # cd user | |
573 # make | |
574 | |
575 4/ Create a device node. I used major number 33 as it was | |
576 free on my PC: | |
577 | |
578 # mknod -m 666 /dev/sample c 33 0 | |
579 | |
580 If 33 is not free choose a free major number and change the | |
581 #define SAMPLE_MAJOR in zaptel.c and recompile. | |
582 | |
583 Note it is important to "insmod zaptel.o" from inside the zaptel | |
584 directory and don't forget the ".o" (.ko for Linux 2.6). Otherwise | |
585 insmod will use the previously installed version of zaptel and | |
586 "sample" won't work. | |
587 | |
588 5/ Make the call to the Zaptel port you wish to sample. Run | |
589 sample while talking: | |
590 | |
591 # ./sample test 1 5 | |
592 | |
593 this will create test_tx.raw, test_rx.raw & test_ec.raw. There | |
594 will be a few messages on the console as the driver does it's | |
595 thing, you can check these with dmesg. | |
596 | |
597 6/ You can check your samples by playing them back through your | |
598 sound card, for example: | |
599 | |
600 # play -f s -r 8000 -s w test_ec.raw | |
601 | |
602 7/ To convert the raw files to wave files (this is more convenient for playing | |
603 and processing with the Oslec simulation): | |
604 | |
605 # sox -t raw -r 8000 -s -w -c 1 test_ec.raw test_ec.wav | |
606 # play test_ec.wav | |
607 | |
608 8/ There is an Octave script pl.m to help plot the samples: | |
609 | |
610 # cp /your/test/samples ~/oslec/user | |
611 # cd ~/oslec/user | |
612 # octave | |
613 octave:1> pl("test") | |
614 | |
615 Configuration | |
616 ~~~~~~~~~~~~~ | |
617 | |
618 + Zaptel/Asterisk 1.2.13, 1.4.0 or 1.4.1. However other versions should work | |
619 OK. | |
620 + Linux 2.4 or 2.6 Kernel | |
621 + Digium TDM400 hardware | |
622 + My zapata.conf for the FXO port under test is something like: | |
623 | |
624 --------------------------------------------------------------------- | |
625 signalling=fxs_ks | |
626 echocancel=yes | |
627 ;echocancelwhenbridged=yes | |
628 ;echotraining=400 | |
629 group=2; | |
630 conext=incoming | |
631 channel =>4 | |
632 --------------------------------------------------------------------- | |
633 | |
634 Note echo training is switched off, although this didn't make much | |
635 difference to the FXO Port when using the built-in Zaptel echo | |
636 cancellers. (helped the the FXS port though). Oslec does not support | |
637 echo training. | |
638 | |
639 [[support]] | |
640 Support | |
641 ------- | |
642 | |
643 https://lists.sourceforge.net/lists/listinfo/freetel-oslec[Oslec | |
644 mailing list]. | |
645 | |
646 [[further]] | |
647 Further Work | |
648 ------------ | |
649 | |
650 Here are some ideas for further work. | |
651 | |
652 1/ Make info screen on control panel update each second automatically. | |
653 | |
654 2/ When e/c is reset during a call it converges faster than at start of | |
655 calls. This suggests e/c is wandering off into dumb states before | |
656 the call is connected. Perhaps disabling adaption until the call | |
657 is connected would help with faster convergence | |
658 | |
659 3/ Preserving the state of the e/c between calls is also a very good | |
660 idea, current zaptel design destroys the e/c at the end of a call. | |
661 | |
662 4/ Switch on and test SSE and MMX filter code for x86. Code LMS | |
663 update for x86 in SSE or MMX. | |
664 | |
665 5/ Add a feature to /proc/oslec to extract the current estimated | |
666 impulse response. Use gnuplot or Octave to plot it in real time. | |
667 | |
668 6/ Attempt to speed convergence. | |
669 | |
670 7/ Set up test scripts for greater coverage of G168 tests. | |
671 | |
672 8/ If necessary develop a sparse approach to handle 128ms tails. | |
673 | |
674 [[Simulation]] | |
675 HowTo - OSLEC G168 Simulation | |
676 ----------------------------- | |
677 | |
678 The simulation form of Oslec is useful for Oslec development. It is | |
679 much easier to develop using a non-real time, user mode program than | |
680 saying 'Hello,...1,...2,....3" down a telephone line. The simulation | |
681 dumps internal states while it is running, which can be plotted and | |
682 analysed using Octave. | |
683 | |
684 1. Read spandsp-0.0.3/README and make sure you have installed the | |
685 dependencies like libtiff-devel, libaudiofile-devel, fftw-devel. | |
686 | |
687 2. Make, build, run a test: | |
688 | |
689 $ cd spandsp-0.0.3; | |
690 $ ./configure --enable-tests | |
691 $ make | |
692 $ cd tests | |
693 $ ./echo_tests 2a | |
694 | |
695 3. You can change the echo path model with -m [1..7] (default 1) | |
696 | |
697 4. You can change the ERL with -erl [0..whatever] (default 10.0) | |
698 | |
699 5. You can plot the internal states using Octave: | |
700 | |
701 $ cd spandsp-0.0.3/echo_tests | |
702 $ octave | |
703 octave:1> echo_dump | |
704 | |
705 The st= and en= statements at the top of echo_dump.m control which | |
706 part of the waveform is plotted. | |
707 | |
708 6. There are some sequences of tests set up in the script files: | |
709 | |
710 $ ./g168_quick.sh (useful for a quick sanity test) | |
711 $ ./g168_tests.sh (more comprehensive set of tests) | |
712 | |
713 7. For more options: | |
714 | |
715 $ ./echo_tests -h | |
716 | |
717 8. Counting passes (say if u want to see how many tests pass after making | |
718 a change): | |
719 | |
720 $ ./g168_tests.sh > lms16bit.txt | |
721 $ cat lms16bit.txt | grep PASS | wc -l | |
722 | |
723 [[links]] | |
724 Further Reading | |
725 --------------- | |
726 | |
727 + http://svn.astfin.org/software/oslec/trunk/spandsp-0.0.3/src/echo.c[echo.c] | |
728 is the heart of the Oslec echo canceller. | |
729 | |
730 There are several blog posts documenting the development of Oslec: | |
731 | |
732 + http://www.rowetel.com/blog/?p=18[Part 1 - Introduction] discusses the myth | |
733 of hardware echo cancellation and the concept of an echo canceller | |
734 developed using echo samples collected by a community. | |
735 | |
736 + http://www.rowetel.com/blog/?p=21[Part 2 - How Echo Cancellers Work] | |
737 is an easy to read introduction to echo cancellation for C programmers. | |
738 | |
739 + http://www.rowetel.com/blog/?p=22[Part 3 - Two Prototypes] discusses | |
740 two algorithms that were developed as candidates for Oslec. This is a | |
741 fairly "hard core" DSP post - some familiarity with echo cancellers is | |
742 assumed. | |
743 | |
744 + http://www.rowetel.com/blog/?p=23[Part 4 - First Phone calls] talks | |
745 about the very first real-world phone calls made using Oslec. | |
746 | |
747 + http://www.rowetel.com/blog/?p=33[Part 5 - Ready for Beta Testing]. | |
748 Walks through some of the alpha testing bugs and how they were fixed, | |
749 discusses open development methods and the need for 128ms tails. | |
750 | |
751 Some useful links: | |
752 | |
753 + Ochiai, Areseki, and Ogihara, "Echo Canceller with Two Echo Path | |
754 Models", IEEE Transactions on communications, COM-25, No. 6, June 1977. | |
755 http://www.rowetel.com/images/echo/dual_path_paper.pdf[download]. | |
756 | |
757 + The classic, very useful paper that tells you how to actually build | |
758 a real world echo canceller: Messerschmitt, Hedberg, Cole, Haoui, | |
759 Winship, "Digital Voice Echo Canceller with a | |
760 TMS320020. http://www.rowetel.com/images/echo/spra129.pdf[download]. | |
761 | |
762 + A nice | |
763 http://en.wikipedia.org/wiki/Least_mean_squares_filter[introduction to | |
764 LMS filters]. | |
765 | |
766 + Good introduction to http://www.cisco.com/univercd/cc/td/doc/cisintwk/intsolns/voipsol/ea_isd.htm[echo on VOIP calls] from Cisco. | |
767 |