Metadata-Version: 2.4
Name: speech-denoiser
Version: 1.0.0
Summary: Deep Learning-powered speech denoiser based on U-Net with bounded cIRM phase optimization
Author-email: Deniz <deniz@example.com>
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: torch>=2.0.0
Requires-Dist: torchaudio>=2.0.0
Requires-Dist: numpy>=1.24.0
Requires-Dist: soundfile>=0.12.0

# 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:

```bash
pip install speech-denoiser
```

Or install the development version directly from GitHub:

```bash
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:

```python
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:

```python
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:

```python
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.
