Metadata-Version: 2.4
Name: mashood-neural-snr
Version: 0.1.1
Summary: Blind SNR estimation using DeepFilterNet. Includes bundled model weights.
Home-page: https://github.com/mashoodAwan/mashood-neural-snr
Author: Muhammad Mashood Awan
Author-email: mashoodawan27@gmail.com
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: torch==2.0.1
Requires-Dist: torchaudio==2.0.2
Requires-Dist: numpy
Requires-Dist: scipy
Requires-Dist: pandas
Requires-Dist: deepfilternet
Requires-Dist: soundfile
Requires-Dist: tqdm
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# mashood-neural-snr 🎧

[![PyPI version](https://img.shields.io/pypi/v/mashood-neural-snr.svg)](https://pypi.org/project/mashood-neural-snr/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Downloads](https://static.pepy.tech/badge/mashood-neural-snr)](https://pepy.tech/project/mashood-neural-snr)

**A Robust Blind SNR Estimator for Single-Channel Audio using Deep Learning.**

`mashood-neural-snr` solves the "Cocktail Party Problem" for SNR estimation. It uses **Neural Source Separation** (DeepFilterNet) to mathematically isolate speech from noise, allowing for accurate signal-to-noise ratio calculation even when noise overlaps with speech.

---

## 🚀 Quick Start

### Installation
```bash
pip install mashood-neural-snr
```

### Usage
```python
from neural_snr import snr

# Returns SNR in Decibels (dB)
score = snr("path/to/my_audio.wav")

print(f"Estimated SNR: {score:.2f} dB")
```

---

## 1. Problem Definition: The Challenge of Mixed Signals

In a "Blind" analysis scenario, the objective is to calculate the Signal-to-Noise Ratio (SNR) of a recording where clean speech and background noise are already mixed. Access to the discrete ground-truth files (Clean Speech and Isolated Noise) is unavailable.

### 1.1 Limitations of Traditional DSP (VAD)

Conventional Digital Signal Processing approaches, such as Voice Activity Detection (VAD) (e.g., WADA-SNR, NIST STNR), rely on a binary segmentation strategy. These algorithms identify "Silence" segments to estimate the noise floor and assume this noise level remains constant under the speech.

**The "Overlap" Failure Mode:**

This approach fails in real-world acoustic environments due to the Signal Overlap Problem.

- **Dynamic Noise:** If a transient noise source (e.g., a siren, a car passing, or a door slamming) occurs simultaneously with the speech, a VAD algorithm cannot isolate it.
- **Result:** The algorithm classifies the loud noise as "Speech Energy." Consequently, the noise power is under-estimated, and the signal power is over-estimated, leading to a falsely inflated SNR calculation.

---

## 2. The Solution: Neural Source Separation

To address the limitations of VAD, this methodology employs **DeepFilterNet**, a state-of-the-art speech enhancement model, as a semantic source separator.

Unlike traditional filters that rely on frequency gating, DeepFilterNet acts as a **Non-Linear Semantic Filter**. Trained on massive datasets of human speech, the model learns to identify the harmonic structure of the voice. It can effectively separate speech from background noise even when they overlap completely in both time and frequency domains.

---

## 3. Methodology: "Reverse-Engineering" the Noise

The core concept relies on isolating the speech component to mathematically derive the noise profile via subtraction.

### 3.1 The Mathematical Workflow

The audio signal is modeled as an additive mixture:

$$y(t) = s(t) + n(t)$$

*(Where $y$ is mixture, $s$ is speech, $n$ is noise)*

**Step 1: Inference (Speech Estimation)**

The noisy mixture is processed through the DeepFilterNet model to generate an estimated clean signal.

$$s_{est} = \text{Model}(y)$$

**Step 2: Residual Extraction**

Since the mixture is the sum of its parts, the noise profile can be derived by subtracting the estimated speech from the original mixture.

$$n_{est} = y - s_{est}$$

**Step 3: SNR Calculation**

The SNR is computed by comparing the average power (Mean Squared Error) of the separated components.

$$SNR_{dB} = 10 \cdot \log_{10}\left(\frac{P_{s\_est}}{P_{n\_est}}\right)$$

---

## 4. Engineering Constraints & Correction

Direct subtraction fails due to **Neural Network Latency** and **Gain Mismatch**. Without correction, the extracted noise profile contains "ghostly" artifacts of the speech. We apply the following corrections:

### 4.1 Latency Correction (Time Alignment)

Neural networks introduce a processing delay. Direct subtraction of misaligned signals causes phase cancellation errors.

**Solution:** Cross-Correlation analysis is performed to detect the precise time lag. The estimated speech is then time-shifted to align perfectly with the original mixture.

### 4.2 Amplitude Scaling (Least Squares Projection)

The model often outputs audio at a normalized volume that differs from the input.

**Solution:** A scaling factor ($\alpha$) is calculated using Least Squares Projection. This projects the estimated speech onto the mixture to find the optimal volume level that maximizes cancellation.

**Corrected Noise Formula:**

$$n_{final} = y - (\alpha \cdot s_{aligned})$$

---

## 5. Experimental Validation

To quantify robustness, a controlled evaluation was performed using a **Standard Speech Dataset** (speech mixed with noise at strictly controlled intervals).

### 5.1 Benchmark Results

| Condition   | Label SNR | Avg Est. SNR | Abs Error | Status |
|-------------|-----------|--------------|-----------|--------|
| Clean       | +20 dB    | 18.76 dB     | ~1.3 dB   | ✅     |
| Good        | +15 dB    | 14.72 dB     | 0.7 dB    | ✅     |
| Fair        | +10 dB    | 9.95 dB      | 0.5 dB    | ✅     |
| Noisy       | +5 dB     | 4.95 dB      | 0.4 dB    | ✅     |
| Very Noisy  | -5 dB     | -5.10 dB     | 0.5 dB    | ✅     |
| Harsh       | -10 dB    | -9.83 dB     | 0.8 dB    | ✅     |
| Extreme     | -20 dB    | -14.24 dB    | ~6.1 dB   | ⚠️     |

### 5.2 Analysis

**1. The High-Precision Zone (+20 dB to -10 dB)**

The algorithm performs optimally across this wide range. Because the speech signal maintains enough semantic integrity, the model successfully separates the voice.

- **Observation:** The Absolute Error is consistently low, frequently falling below 1.0 dB.
- **Conclusion:** Highly reliable for standard environments.

**2. The Detection Limit (-20 dB)**

The data demonstrates a physical limit at -20 dB.

- **Physical Limitation:** At -20 dB, speech energy is submerged so deep below the noise floor that it appears as "Noise Only" to both the human ear and the AI.
- **Failure Mode:** The model outputs near-silence for speech, making the ratio calculation mathematically impossible.

---

## 6. Conclusion

By utilizing **DeepFilterNet** to semantically separate speech from noise and applying **Cross-Correlation** and **Least Squares scaling**, `mashood-neural-snr` provides a robust measurement of audio quality.

This approach offers a significant advantage over traditional DSP methods as it accurately accounts for overlapping noise, resulting in a physically consistent measurement.

---

## 📄 License

MIT License
