SpectraHush

Lightweight, streaming Berouti-style spectral subtraction for real-time audio noise reduction.

---

SpectraHush extends Boll's (1979) original spectral subtraction algorithm with the two parameters introduced by Berouti, Schwartz, and Makhoul (1979): the over-subtraction factor ($\alpha$) and the spectral floor ($\beta$), which together significantly suppress the musical noise artifacts that plague the original method.

It is intentionally small: a single-file Python implementation with no heavy DSP dependencies, suitable for embedded use, telephony pipelines, voice front-ends, and as a teaching reference for classical speech-enhancement.

Algorithm Overview

1. Convert incoming audio to overlapping STFT frames (Hann window, 75% overlap).
2. Track the background noise PSD on frames flagged as non-speech by an energy-ratio VAD.
3. Apply Berouti-style spectral subtraction:

   |S_hat(f)|^p = max( |Y(f)|^p - alpha * |N_hat(f)|^p ,  beta * |N_hat(f)|^p )
   

4. Reconstruct the time-domain signal via overlap-add (OLA), reusing the noisy phase.

Installation

Requires Python 3.9+.

git clone https://github.com/Ajaneeshwar/SpectraHush.git
cd SpectraHush
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Or install as a package (provides the spectrahush console command):

pip install -e .

Usage

1. Live microphone streaming

Stream directly from your microphone to your speakers with noise reduction applied in real time. Stay silent for the first 0.5 s so the noise profile can calibrate.

python spectral_subtraction.py live

2. Process an audio file

Apply the algorithm to a pre-recorded .wav file.

python spectral_subtraction.py file input.wav output.wav

3. Record and A/B test

Use record_test.py to record yourself and generate both a noisy and a cleaned .wav file, along with SNR-reduction metrics.

python record_test.py --duration 10 --play

Configuration

Tuning parameters live in config.yaml. Missing keys fall back to built-in defaults; CLI flags override the config.

Parameter	Description
alpha	Over-subtraction factor. Higher = more suppression, more musical noise.
beta	Spectral floor as a fraction of noise PSD. Higher = preserves natural hiss.
power	2.0 for power subtraction (default), 1.0 for magnitude subtraction.
vad_threshold_db	SNR threshold (dB) above which a frame is treated as speech.
noise_smooth	Recursive smoother for the noise PSD on noise-like frames.
mag_smooth	1-pole smoother on `

Override on the fly:

python spectral_subtraction.py file input.wav output.wav --alpha 3.0 --beta 0.05

Citation

If you use SpectraHush in academic work, please also cite the foundational papers:

@inproceedings{boll1979,
  author    = {Boll, Steven F.},
  title     = {Suppression of Acoustic Noise in Speech Using Spectral Subtraction},
  booktitle = {IEEE Transactions on Acoustics, Speech, and Signal Processing},
  year      = {1979},
  volume    = {27},
  number    = {2},
  pages     = {113--120}
}

@inproceedings{berouti1979,
  author    = {Berouti, M. and Schwartz, R. and Makhoul, J.},
  title     = {Enhancement of Speech Corrupted by Acoustic Noise},
  booktitle = {Proc. IEEE ICASSP},
  year      = {1979},
  pages     = {208--211}
}

Contributing

Bug reports, feature requests, and pull requests are welcome. See CONTRIBUTING.md for guidelines.

License

MIT License. See LICENSE for details.