# mrnn
Denoising by Magnitude Recurrent Neural Networks
Author: Raymond Xia (yangyanx@andrew.cmu.edu)
Implementation of COMPLEX RECURRENT NEURAL NETWORKS FOR DENOISING SPEECH SIGNALS
 by Keiichi Osako, Rita Singh, and Bhiksha Raj.

License information: All material is copyright 2017 by the CMU Robust Speech Group.  
License details are contained in http://www.cs.cmu.edu /~robust/Algorithms/RobustLicense.txt
Contact rms@cs.cmu.edu for additional inforamtion.

# Version History
* 10/15/2017 - Version 2.
  * Wiener filtering structure added.
  * More training options added.
* 09/15/2017 - Version 1.
  * Original MRNN.

# Requirement
* Python 2.7
* audiolib 2.0 (included, but need to be added to PYTHONPATH)
* Theano 0.9.0
* CUDA nvcc 8.0 (optional)

# Updates in Version 2 (as of 10/15/2017)
The updated version of MRNN is largely the same as the previous version, with two major functionalities added to it:
	1. Wiener filtering-like DNN structure.
	2. A utility class that allows specifying the ratio of noise and noisy speech in training batch. The metadata files of for LDC2015S02 data are required.


# Usage
To train a MRNN system from nothing, and assuming training data is in the
correct path, run
	```
	python train.py -o path/to/output
	```

To train a MRNN system from an existing set of NN weights, run
	```
	python train.py -m path/to/existing/weights -o path/to/output
	```

To denoise an audio signal using an existing system weights, run
	```
	python denoise.py -m path/to/existing/weights.npz -i path/to/noisy/audio.wav
	-o path/to/output.wav
	```

# Configurations & Hyper-parameters
There are a few feature-related and neural network-related hyper-parameters
that need to be determined ahead of training or denoising using MRNN. Those
parameters are available for adjustment in `config.py`, although the existing
configuration is the only configuration known to be working well (and getting
the report results).

To enable training/denoising using a Wiener-filtering-like MRNN system
(only in version 2), set hyper-parameter `WIENER` to `True` in `config.py`.

# Trained Models
Several trained models are available in the directory `model/`. All models are
trained using the configurations in `config.py`. Specifically,
    * `MRNN-A` is trained on A-channel noisy data and clean data pair with
      random initialization.
    * `MRNN-D` is trained on SSB-demodulated D-channel noisy data and clean
      data pair with the learned model `MRNN-A` used as the initialization.
    * `MRNN-H` is trained on H-channel noisy data and clean data pair with
      random initialization.
    * `MRNN-ADHXepoch`, where `X` is one of {1,2,10,20}, are trained on all
      training data for each channel-dependent model above, and their clean data
      pair, with the learned model `MRNN-A` used as the initialization and
      learning rate set to `1e-5` (1/100 of the normal learning rate). The
      number of epochs `X` shows the number of times the entire training dataset
      get passed through the system.
These learned models can be used for either denoising to reproduce the reported
results, or as the initialization parameter for learning new models.
