BinVote Version 0.2

• Introduction
• Command line explanation
• Examples of use
• Explanation of range exslusion
• What are envelope files - How does it work?
• Parameters description

Introduction

I have created BinVote, because all applications I found on the web weren't able to correct sufficiently WAV files containing many glitches which were very similar to jitter correction errors. Some of those applications were too universal, thus not effective in that case, the other ones were doing something but I couldn't figure out what. On top of it they left most of glitches untouched. This situation left me no other choice but to write my own tool. It was tough work but finally I reach the state BinVote produces satisfactory results. It has removed almost all unpleasant glitches from my favorite 20 minutes track leaving rest of the signal untouched.

BinVote - it is the command line tool having two main features:

• Reconstruction of original content of a file basing on its odd number of partially damaged copies.
  Corresponding bytes are compared and if values are different, voting mechanism is invoked. If there is no quorum (more than a half of the same values), the bit voting is used.
  This function was designed to correct audio tracks extracted from scratched or somehow damaged CDs. It is possible to correct many read errors applying this function to 3 or more copies of the same CD read on various CD drives. Because some CD drives can read particular audio tracks starting from slightly different places on a CD, I added automatic correlation of different copies.
  This feature can be treaded as a supplement for very good program for audio track reader - EAC (http://www.exactaudiocopy.de) by Andre'a Wiethoff.
  File format is insignificant.
• Glitches removing.
  Some of error can't be corrected even by EAC no matter what CD reader we use.
  The only way is to correct the audio signal itself.
  Only damaged area is reconstructed. It is usually about 20 to 40 samples changed for a single glitch. Of course this tools isn't yet perfect, because problem itself is very complicated. But there is a possibility to tell BinVote exactly what range should be analyzed and corrected if necessary.
  File format is significant. So far only WAV files with following format are handled:
  44.1kHz, stereo, 16 bit resolution.

 Back to top

Usage

[INPUT MEDIA FILES] represent a list of file names separated by spaces. An odd number of input files of the same size is required. Thus at least one input file is required. That's of course obvious.
<out_file> is an output file name. It has to be always present even if envelope files are only generated. It must be the last file name in the command line. Otherwise it will be interpreted as input file name.

[SWITCHES] are as follow:

-e <envelope_file>	<envelope_file> is an envelope file name TEMPLATE. When this switch is used, two envelope files will be created. One file for each channel. Files will be named as specified after -e switch but with "L" and "R" appended at the name end. (Before WAV extension). E.g -e env.wav will force binvote to create two files envL.wav and envR.wav.
-g	Glitches will be removed. In this case the input accepts only WAV files. If -g isn't present in the command line then only voting mechanism will be invoked. No envelope files will be generated.
-u	Glitches will be removed only in places where inconsistencies between copies were detected. 0.5 second margins are added before and after spotted positions.
-weak <value>	Weak signal coefficient. By default it is 2.27. See below for further explanation.
-medium <value>	Medium signal coefficient. By default it is 2.4. See below for further explanation.
-strong <value>	Strong signal coefficient. By default it is 9. See below for further explanation.
-dyn <value>	Dynamics coefficient used when calculating envelope. By default 0.01. See below for further explanation.
-maxg <value>	Maximum glitch length. By default it is 18 samples.
-mindist <value>	Minimum nominal distance between two pikes. By default it is 500 samples. See below for further explanation.
-freq <value>	Hi-pass filter for emphasizing glitches. 2000 by default.
-hifreq <value>	Lo-pass filter for emphasizing glitches.10000 by default. Eliminates noise that could interfere a glitches search algorithm.
-y	Overwrite output file without asking.
-excl <ranges_file>	Exclude from search ranges of samples listed in a <ranges_file> file. Glitches detected in those ranges won't be removed. See below for further explanation.
-incl <ranges>	Include in search ranges of samples listed in a <ranges_file> file. Glitches detected in those ranges will be removed. See below for further explanation.

Order of parameters is free with two exceptions, (1) output file have to be specified after all input files have been specified, (2) when both -excl and -incl switches have been used, then the resulting set of ranges differs depending on their order.

Back to top

 

Explanation of range exslusion.

a.)		-excl file1.txt	b.)	-incl file2.txt
	file1.txt ranges		file2.txt ranges
	resulting ranges		resulting ranges
c.)		-excl file1.txt -incl file2.txt	d.)	-incl file2.txt -excl file2.txt
	-excl file1.txt		-incl file2.txt
	file2.txt ranges		file1.txt ranges
	resulting ranges		resulting ranges

A range file can be almost of any type of text file providing that each range is described by a single line. A range can be described either by specifying start and stop moment or by simply describing where the center of suspected range lies. In the second case half second margins will be assumed. Times in many formats are allowed as well as sample numbers. Any separators and text before and after ranges will be ignored.
E.g. log files from EAC program can used as range files.

Back to top

 

Examples of use:

1. Removing glitches in entire input file with no envelope generation. All output from BinVote is redirected to a log.txt file. So later it will be easy to see what was modified and what wasn't, where the pikes where detected and what were the reasons of leaving pikes uncorrected (if that happens).
   binvote in.wav -g out.wav > log.txt
3. Removing glitches within ranges given in eac_read_errors.log file with envelope files generation:
   binvote in.wav -e env.wav -g -y out.wav -incl eac_read_errors.log
5. Voting only (Reconstructing file basing on its multiple copy):
   binvote in1.bin in2.bin in3.bin in4.bin in5.bin -y out.bin
7. Voting and glitch removal but only in all places where at least one inconsistence was detected across all copies:
   binvote in1.wav in2.wav in3.wav -g -u out.wav
9. Customized glitches removal with storing all binvote message to log.txt file:
   binvote in.wav -weak 2.45 -medium 3.1 -dyn 0.003 out.wav > log.txt

Back to top

 

What are envelope files - How does it work?

To begin with, I would like to stress that this tool isn't intended to make fully automatic glitches removal. (On the beginning it was intended to do so, but very soon it appeared that the problem of glitches removal is really hard to solve. Sometimes it was really pain in the ass to find and correct some glitches even by myself. I was looking through the wave listening suspected area hundreds of times and yet I wasn't unable to find damaged area although it was clearly audible!)
It may only support that difficult process. It is hardly impossible to get decent result on the first run of the tool. Thus, it is strongly recommended to check the results, to look into envelope files and binvote logs in order to see what places were corrected, whether the setting aren't too sensitive or too insensitive. Having good headphones or audio system is a must, because you have to know what pikes are recognized by you as glitches and what as a correct signal.
BinVote uses various heuristics to guess it at its best, but some tuning will be required rather for sure.
And that's what the envelope files are for.

Envelopes are generated to help a user of BinVote tool to see how a signal correction will be performed and to understand how to match various coefficients to attain desired results. Envelope files are just WAV files, so there is no need to design any special tool in order to view the files and see how the algorithm works. You can use any WAV editor which allow for WAV file visualization. The best are those editors which allow you to synchronise all opened files. There is a separate envelope file generated for each channel.

The following picture presents example contents of an envelope file.


It shows how one channel of an input file will be processed. The upper graph shows the level of signal changes while the lower graph shows signal envelope combined with information on which area was modified. Envelope shows current estimated signal changes level with certain delayed reaction for fast and short signal changes. If in a given place the value is negative that means that in this place a glitch was detected and removed. BinVote inverts envelope value for each modified sample. Usually less than 0.01% of original input signal is modified.

On the next picture you can see the meaning of the signals stored in an envelope file.



If the ratio between signal changes (signal in the top channel) and the envelope signal (signal in the bottom channel) exceeds the level of pike coefficient calculated for current envelope value then that sample (and its neighbors) is considered as a potential glitch and is further analyzed.

Graph below shows how that pike coefficient depends on "weak", "medium" and "strong" signal coefficient values. This curve is a parabola intersecting all those 3 points. (Although seeing on the picture below it is hard to believe in it, it is really a parabola, but the horizontal axis isn't scaled linearly).



Download that useful (I hope) Microsoft Excel Worksheet containing the way the envelope files should be interpreted together with formula helping to match proper coefficients. The file is only 60kB big.

Back to top

 

Parameters description

BinVote uses heuristic algorithms to remove glitches, that need a lot of additional parameters. For many cases default values should be sufficient in order to remove most of glitches, but efficiency strongly depends on the signal itself.

weak, medium and strong signals coefficient are explained by the picture above. They determine sensitivity of detection algorithm. I would like to clarify that "weak" signal coefficient is given for value of envelope equal to 60, "medium", for value equal to 400 and "strong" for 1600 as it can be seen on that picture.
dyn tell the algorithm about how fast slopes can appear in the signal. The less value the envelope changes less dynamically. Thus, it is easier to detect any possible pikes and glitches. But from the other hand, more fast signal slopes can be interpreted as glitches. Of course there is other mechanism preventing from misinterpeting slopes as glitches, but you have to careful.
maxg determine the maximum width of a glitch. This value should be as small as possible. Bigger values may cause that many deliberate pikes will be eliminated.
mindist tell BinVote what is the minimum distance between two potential glitches. This value isn't, however the absolute value. It is scaled depending on how strong a detected pike is. The stronger pike the smaller distance is allowed. In general, this value should be as big as possible. Usually glitches appear alone so it is good to make some experiments and increase this value even a couple of times.
freq and hifreq determine the bandwidth of a band-pass filter used for initial signal preparation for further processing. Of course it is used only for internal purposes and do not have any direct influence on an output signal. It only helps the algorithm to "hear" better the glitches.

Back to top