README.txt for snreval

Note: the latest version of this information is from the web page at
http://labrosa.ee.columbia.edu/projects/snreval/ 

USAGE

snreval is a compiled Matlab script to apply various objective measures 
of signal quality to degraded speech signals.  Once it is installed, the 
basic usage looks like this:

  $ ./run_snreval.sh arabic_400mhz.wav -vad arabic_400mhz-vad.txt -clean arabic_source.wav 
  ==========================================
  Target File: arabic_400mhz.wav
  time range: 0.0-59.8 s
    Ref File: arabic_source.wav
  Targ delay: -0.237 s
  NIST STNR = 23.8 dB
  WADA SNR  = 19.7 dB
     SNRvad = 12.3 dB
	SAR = 9.0 dB
   PESQ MOS = 2.6
  ==========================================

With the -disp 1 flag added to the command line, this should also generate 
a graphical display similar to the included screenshot snreval_screenshot.png.

The script syntax is:

  ./run_snreval.sh noisyfile -vad vadfile -clean cleanfile -start start -end end -guessvad 1 -disp 1

where all arguments except <noisyfile> are optional.  If only <noisyfile>
is specified, then only NIST STNR *1 and WADA SNR *2 are calculated.

<vadfile> names a voice activity annotation file, which consists of lines 
like:

  2.691060 3.091060 1

where the first column is the start of a voice-active region, the
second column is the end (both in secs), and the third column is a
label (which is actually ignored).  When VAD segments are available,
the script will also calculate SNRvad, which is simply the SNR based
on the average energy in voice-active regions compared to the average
energy in voice-inactive regions.

<cleanfile> specifies a soundfile containing the clean, reference
speech.  When this is provided, it allows the computation of the
signal-to-artifacts ratio SAR, which is the ratio of energy of the
best-fit linear-filtered version of the clean signal, to the energy of
the residual (which could not be predicted from the clean signal).
This uses a process similar to echo cancellation to cancel the
reference speech from the noisy signal. *3

Having the clean signal also permits the calculation of PESQ *4, a
standard used in telecomms to estimate "subjective quality" ratings on
a scale of 1 (bad) to 5 (excellent).

<start> and <end> provide times (in seconds) to limit the part of 
<noisyfile> that is analyzed.  Note that the times in <vadfile> are 
assumed to correspond to <noisyfile> before <start> is applied.

-guessvad set to 1 will let the script attempt to guess voice activity
from <cleanfile> (or <noisyfile> if <cleanfile> is not provided) using
a simple energy threshold.

-disp set to 1 enables the graphical display, otherwise the script 
simply generates the text output.

If <vadfile> or <cleanfile> cannot be found, the script treats them as not 
provided.

INSTALLATION

This package was created by the MATLAB compiler; we have now compiled it 
for 32 and 64 bit Linux, and 64 bit MacOS.  To use
it, you have to first install the MATLAB Compiler Runtime (MCR)
environment.  You must first obtain the correct version of the MCR 
installer from the links at http://labrosa.ee.columbia.edu/projects/snreval/ .
Then, from the command line prompt, you execute:

  $ sh ./MCRInstaller.bin

.. and follow the directions (you need to be running on an X display,
I think).

The run_snreval.sh script assumes that the MCR was installed in the
default location, /opt/MATLAB/MATLAB_Component_Runtime .  If you put
it somewhere else, you'll need to edit run_snreval.sh to change the
MCRROOT definition.

Once the install is finished, you should be able to simply run the
run_snreval.sh script as above.

The original Matlab code used to build this compiled target is 
available at

  http://labrosa.ee.columbia.edu/projects/snreval/

Feel free to contact me with any problems.

  -- DAn Ellis dpwe@ee.columbia.edu 2010-12-14

*1 NIST STNR - see http://labrosa.ee.columbia.edu/~dpwe/tmp/nist/doc/stnr.txt
*2 WADA SNR - see http://www.cs.cmu.edu/~robust/Papers/KimSternIS08.pdf
*3 BSS_EVAL - see http://bass-db.gforge.inria.fr/bss_eval/ 
*4 PESQ - see http://www.utdallas.edu/~loizou/speech/software.htm
