speech-denoiser 1.0.0

Deep Learning-powered speech denoiser based on U-Net with bounded cIRM phase optimization

speech-denoiser

A high-performance, deep learning-powered Python library for speech enhancement and denoising.

speech-denoiser uses a state-of-the-art U-Net CNN architecture equipped with self-attention at the bottleneck and bounded complex Ideal Ratio Mask (cIRM) phase-magnitude optimization. The underlying model is fine-tuned using a MetricGAN-style adversarial objective, making it highly specialized in restoring noisy speech signals.

---

Features

• High-Quality Speech Enhancement: Restores clean speech from complex, noisy environments (trained on VCTK clean speech and DEMAND noise).
• Flexible In-Memory API: Denoise raw NumPy arrays or PyTorch tensors in one function call.
• Direct File Denoising: Load, enhance, and save clean .wav, .mp3, or other audio files in a single step.
• Overlap-Add Processing: Prevents out-of-memory errors by windowing and stitching varying-length audio dynamically.
• Automatic Resampling: Automatically handles arbitrary input sample rates (downsampling internally to $16\text{ kHz}$ for the model, and restoring the original sample rate at the output).
• No Heavy System Dependencies: Utilizes a platform-independent audio backend (soundfile), eliminating the need for complex FFmpeg installations.

---

Installation

Install the library directly from PyPI:

pip install speech-denoiser

Or install the development version directly from GitHub:

pip install git+https://github.com/denizcaylak/signal-denoising.git#subdirectory=speech-denoiser

---

Quickstart

1. Denoise a Waveform Array (In-Memory)

Perfect for integration into audio pipelines, speech recognition front-ends, or web apps:

import soundfile as sf
import speech_denoiser as sd

# 1. Load your noisy audio (supports any sample rate)
noisy_audio, sr = sf.read("noisy_speech.wav")

# 2. Denoise
# Note: By default, this searches for checkpoints/gan_last_model.pt in your working directory.
clean_audio = sd.reduce_noise(noisy_audio, sr=sr)

# 3. Save the clean audio
sf.write("clean_speech.wav", clean_audio, sr)

2. Denoise an Audio File Directly

Provide the input and output paths to enhance audio files in one step:

import speech_denoiser as sd

# Enhance file directly
sd.denoise_file("noisy_speech.mp3", "clean_speech.wav")

3. Using a Custom Checkpoint

If you want to point to a specific trained PyTorch checkpoint path:

import speech_denoiser as sd

clean_audio = sd.reduce_noise(
    noisy_audio,
    sr=sr,
    checkpoint_path="checkpoints/gan_last_model.pt",
    device="cuda"  # or "cpu"
)

---

Under the Hood

speech-denoiser operates on the complex Short-Time Fourier Transform (STFT) of the audio:

1. It extracts the Real and Imaginary channels of the spectrogram.
2. The U-Net predicts a bounded complex Ideal Ratio Mask (cIRM) constrained within $[-K, K]$ using a hyperbolic tangent activation.
3. The mask is decompressed back to its full dynamic range and applied to the noisy spectrogram via complex multiplication.
4. The clean waveform is reconstructed using the Inverse Short-Time Fourier Transform (ISTFT) and an overlap-add window to ensure seamless stitching without audio artifact seams.