README.txt for renoiser v_0.1

2011-02-11 Dan Ellis dpwe@ee.columbia.edu

USAGE

renoiser is a compiled Matlab script that can be used to separate out 
the linear component of a clean file in a filtered, noisy mixture.  It 
can then be used to recompose the mixture with the target at a modified 
relative level, or to introduce a new target, filtered to resemble 
the original, at a specified SNR.

renoiser defines a number of concepts: CLEAN is original, clean speech, 
TARGET is a clean signal that is noise-free but has been filtered by a 
channel (defined by an FIR filter FILTER); NOISE is an additional noise 
component, and MIX is a combination of TARGET and NOISE.  Thus, an 
example usage to break a MIX into a TARGET (matching a CLEAN) and a 
NOISE is:

  $ ./run_renoiser.sh -mix arabic_400mhz.wav -clean arabic_source.wav -noiseout noise.wav -targetout targ.wav -filterout filt.wav
  Reading CLEAN from arabic_source.wav ...
  Reading MIX from arabic_400mhz.wav ...
  Identifying CLEAN in MIX...
  NOISE saved to noise.wav
  FILTER saved to filt.wav
  TARGET saved to targ.wav
  Input mix SNR= 8.49 dB

This performs the decomposition, and saves out the components.  The input MIX
is the output NOISE and TARGET summed together, and the output TARGET 
is approximately the output FILTER applied to the input CLEAN (only 
approximately because the estimated filter can be slowly time-varying, and 
there is an internal timing skew adjustment that would not be preserved).

To reconstruct a new signal using these components, we could:

  $ ./run_renoiser.sh -clean arabic_source.wav -filter filt.wav -noise noise.wav -mixout mix.wav -SNR 6.0
  Reading CLEAN from arabic_source.wav ...
  Reading FILTER from filt.wav ...
  Reading NOISE from noise.wav ...
  Filtering CLEAN to produce target...
  Creating new output mix at SNR 6 dB ...
  MIX saved to mix.wav

As the messages imply, this uses the FILTER and NOISE extracted in the first 
invocation to build a new MIX at the specified SNR (as determined by 
P.56 active level estimation, thanks to Mike Brookes' Voicebox toolbox).

Note that any nonlinear distortion components related to the original 
CLEAN will remain in NOISE.  In order to have these line up as well 
as possible in the reconstructed mix, it's better to use the TARGET output, 
in which case FILTER and CLEAN are not needed:

  $ ./run_renoiser_GLNX86.sh -target targ.wav -noise noise.wav -mixout mix.wav -SNR 6.0           
  Reading NOISE from noise.wav ...
  Reading TARGET from targ.wav ...
  Creating new output mix at SNR 6 dB ...
  MIX saved to mix.wav

The analysis and this last style of recombination can be done in a single 
step: 

  $ ./run_renoiser_GLNX86.sh -mix arabic_400mhz.wav -clean arabic_source.wav -mixout mix.wav -SNR 6.0
  Reading CLEAN from arabic_source.wav ...
  Reading MIX from arabic_400mhz.wav ...
  Identifying CLEAN in MIX...
  Input mix SNR= 8.49 dB
  Creating new output mix at SNR 6 dB ...
  MIX saved to mix.wav

However, since identifying CLEAN in MIX is relatively computationally 
expensive, it's often preferable to break these steps apart.


INSTALLATION

This package was created by the MATLAB compiler, and only runs on i386
Linux (although it's possible to compile it for other targets).  To use
it, you have to first install the MATLAB Compiler Runtime (MCR)
environment, which you do by downloading the appropriate Linux installer 
from:

  http://www.ee.columbia.edu/~dpwe/tmp/MCRInstaller.bin

To install you then run it from the Linux shell like this:

  $ sh ./MCRInstaller.bin

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

The compiled 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_renoiser.sh to change the
MCRROOT definition.

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

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

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

Feel free to contact me with any problems.

  -- DAn Ellis dpwe@ee.columbia.edu 2011-02-11
