speech-selib 0.1.0__tar.gz

speech_selib-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 github.com/nipponjo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

speech_selib-0.1.0/PKG-INFO

@@ -0,0 +1,133 @@
+Metadata-Version: 2.4
+Name: speech-selib
+Version: 0.1.0
+Summary: A simple speech enhancement library using ONNX models
+Home-page: https://github.com/nipponjo/selib
+Author: nipponjo
+Author-email: nipponjo <nipponjo.git@gmail.com>
+Project-URL: Homepage, https://github.com/nipponjo/selib
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Telecommunications Industry
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Multimedia
+Classifier: Topic :: Multimedia :: Sound/Audio
+Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.8.0
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy
+Requires-Dist: librosa
+Requires-Dist: onnxruntime-gpu; sys_platform != "darwin"
+Requires-Dist: onnxruntime; sys_platform == "darwin"
+Dynamic: author
+Dynamic: home-page
+Dynamic: license-file
+Dynamic: requires-python
+
+# SeLib
+
+SeLib is a small speech-enhancement library for ONNX models. It provides a
+simple `enhance()` function, lightweight model wrappers, and utility functions for audio/noise experiments.
+
+## Install
+
+Install the package directly from GitHub while the project is still small and moving quickly.
+
+```bash
+# Install SeLib and its Python dependencies.
+pip install git+https://github.com/nipponjo/selib.git
+```
+
+## Basic Use
+
+The shortest path is `selib.enhance(wave, model_id)`. Pass a mono NumPy waveform at the sample rate expected by the model.
+```python
+import librosa
+import selib
+
+from selib.utils import NoiseGenerator, snr_mixer
+
+# Load clean speech at the model sample rate.
+wave_clean, sr = librosa.load("./data/clean_freesound_33711.wav", sr=48000)
+
+# Create artificial noise and mix it with the clean speech at 5 dB SNR.
+noise_gen = NoiseGenerator(sample_rate=sr)
+noise = noise_gen.sample(n_samples=len(wave_clean))
+wave_noisy = snr_mixer(wave_clean, noise, snr=5)
+
+# Enhance with a registered model id.
+# The ONNX model is downloaded and cached automatically on first use.
+wave_enhanced = selib.enhance(wave_noisy, "deepfilternet3")
+```
+
+You can also save the enhanced waveform directly. The loaded model is cached by
+default, so repeated calls with the same `model_id` do not reload the ONNX
+session.
+
+```python
+# Save as 24-bit PCM WAV while returning the enhanced NumPy array.
+wave_enhanced = selib.enhance(
+    wave_noisy,
+    "deepfilternet3",    
+    save_to="enhanced.wav",
+    bits_per_sample=24,
+)
+```
+
+## Model Objects
+
+For more control, load the model wrapper once and call its
+`enhance()` method directly.
+
+```python
+from selib import load_model
+from selib.models import DeepFilterNetOnnx
+
+# load_model() chooses the correct wrapper from the registry metadata.
+model: DeepFilterNetOnnx = load_model("deepfilternet3")
+
+# DeepFilterNetOnnx supports extra options such as attenuation limiting.
+wave_enhanced = model.enhance(wave_noisy, atten_lim_db=12)
+```
+
+Magnitude-mask models can also be used directly. They predict a mask, multiply
+it with the noisy magnitude spectrogram, and reuse the noisy phase.
+
+```python
+from selib import MagnitudeMaskModel
+
+# ul_unas_16k is a 16 kHz magnitude-mask model.
+mask_model = MagnitudeMaskModel("ul_unas_16k")
+wave_enhanced = mask_model.enhance(wave_noisy_16k)
+```
+
+## Metrics
+
+SeLib includes a few quick NumPy-only metrics that do not require PESQ/STOI or
+other external scoring libraries.
+
+```python
+from selib.metrics import snr, segsnr, si_sdr
+
+# Compare clean reference speech against an enhanced waveform.
+print("SNR:", snr(wave_clean, wave_enhanced))
+print("segSNR:", segsnr(wave_clean, wave_enhanced, sample_rate=sr))
+print("SI-SDR:", si_sdr(wave_clean, wave_enhanced))
+```
+
+## Available Models
+
+| Model ID | Type | Sample rate | #params | Paper | Repository |
+| --- | --- | --- | --- | --- | --- |
+| `deepfilternet3` | DeepFilterNet | 48 kHz | 2.13M | [arXiv:2305.08227](https://arxiv.org/abs/2305.08227) | [GitHub](https://github.com/rikorose/deepfilternet) |
+| `deepfilternet2` | DeepFilterNet | 48 kHz | 2.31M | [arXiv:2205.05474](https://arxiv.org/abs/2205.05474) | [GitHub](https://github.com/rikorose/deepfilternet) |
+| `deepfilternet1` | DeepFilterNet | 48 kHz | 1.78M | [arXiv:2110.05588](https://arxiv.org/abs/2110.05588) | [GitHub](https://github.com/rikorose/deepfilternet) |
+| `ul_unas_16k` | Magnitude mask | 16 kHz | 0.171M | [arXiv:2503.00340](https://arxiv.org/abs/2503.00340) | [GitHub](https://github.com/Xiaobin-Rong/ul-unas) |
+
+DeepFilterNet models use ERB masks plus deep-filter coefficients. Magnitude-mask
+models predict a spectrogram mask and reconstruct audio with the noisy phase.

speech_selib-0.1.0/README.md

@@ -0,0 +1,102 @@
+# SeLib
+
+SeLib is a small speech-enhancement library for ONNX models. It provides a
+simple `enhance()` function, lightweight model wrappers, and utility functions for audio/noise experiments.
+
+## Install
+
+Install the package directly from GitHub while the project is still small and moving quickly.
+
+```bash
+# Install SeLib and its Python dependencies.
+pip install git+https://github.com/nipponjo/selib.git
+```
+
+## Basic Use
+
+The shortest path is `selib.enhance(wave, model_id)`. Pass a mono NumPy waveform at the sample rate expected by the model.
+```python
+import librosa
+import selib
+
+from selib.utils import NoiseGenerator, snr_mixer
+
+# Load clean speech at the model sample rate.
+wave_clean, sr = librosa.load("./data/clean_freesound_33711.wav", sr=48000)
+
+# Create artificial noise and mix it with the clean speech at 5 dB SNR.
+noise_gen = NoiseGenerator(sample_rate=sr)
+noise = noise_gen.sample(n_samples=len(wave_clean))
+wave_noisy = snr_mixer(wave_clean, noise, snr=5)
+
+# Enhance with a registered model id.
+# The ONNX model is downloaded and cached automatically on first use.
+wave_enhanced = selib.enhance(wave_noisy, "deepfilternet3")
+```
+
+You can also save the enhanced waveform directly. The loaded model is cached by
+default, so repeated calls with the same `model_id` do not reload the ONNX
+session.
+
+```python
+# Save as 24-bit PCM WAV while returning the enhanced NumPy array.
+wave_enhanced = selib.enhance(
+    wave_noisy,
+    "deepfilternet3",    
+    save_to="enhanced.wav",
+    bits_per_sample=24,
+)
+```
+
+## Model Objects
+
+For more control, load the model wrapper once and call its
+`enhance()` method directly.
+
+```python
+from selib import load_model
+from selib.models import DeepFilterNetOnnx
+
+# load_model() chooses the correct wrapper from the registry metadata.
+model: DeepFilterNetOnnx = load_model("deepfilternet3")
+
+# DeepFilterNetOnnx supports extra options such as attenuation limiting.
+wave_enhanced = model.enhance(wave_noisy, atten_lim_db=12)
+```
+
+Magnitude-mask models can also be used directly. They predict a mask, multiply
+it with the noisy magnitude spectrogram, and reuse the noisy phase.
+
+```python
+from selib import MagnitudeMaskModel
+
+# ul_unas_16k is a 16 kHz magnitude-mask model.
+mask_model = MagnitudeMaskModel("ul_unas_16k")
+wave_enhanced = mask_model.enhance(wave_noisy_16k)
+```
+
+## Metrics
+
+SeLib includes a few quick NumPy-only metrics that do not require PESQ/STOI or
+other external scoring libraries.
+
+```python
+from selib.metrics import snr, segsnr, si_sdr
+
+# Compare clean reference speech against an enhanced waveform.
+print("SNR:", snr(wave_clean, wave_enhanced))
+print("segSNR:", segsnr(wave_clean, wave_enhanced, sample_rate=sr))
+print("SI-SDR:", si_sdr(wave_clean, wave_enhanced))
+```
+
+## Available Models
+
+| Model ID | Type | Sample rate | #params | Paper | Repository |
+| --- | --- | --- | --- | --- | --- |
+| `deepfilternet3` | DeepFilterNet | 48 kHz | 2.13M | [arXiv:2305.08227](https://arxiv.org/abs/2305.08227) | [GitHub](https://github.com/rikorose/deepfilternet) |
+| `deepfilternet2` | DeepFilterNet | 48 kHz | 2.31M | [arXiv:2205.05474](https://arxiv.org/abs/2205.05474) | [GitHub](https://github.com/rikorose/deepfilternet) |
+| `deepfilternet1` | DeepFilterNet | 48 kHz | 1.78M | [arXiv:2110.05588](https://arxiv.org/abs/2110.05588) | [GitHub](https://github.com/rikorose/deepfilternet) |
+| `ul_unas_16k` | Magnitude mask | 16 kHz | 0.171M | [arXiv:2503.00340](https://arxiv.org/abs/2503.00340) | [GitHub](https://github.com/Xiaobin-Rong/ul-unas) |
+
+DeepFilterNet models use ERB masks plus deep-filter coefficients. Magnitude-mask
+models predict a spectrogram mask and reconstruct audio with the noisy phase.

speech_selib-0.1.0/pyproject.toml

@@ -0,0 +1,38 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "speech-selib"
+version = "0.1.0"
+description = "A simple speech enhancement library using ONNX models"
+readme = "README.md"
+requires-python = ">=3.8.0"
+authors = [
+    { name = "nipponjo", email = "nipponjo.git@gmail.com" },
+]
+dependencies = [
+    "numpy",
+    "librosa",
+    "onnxruntime-gpu; sys_platform != 'darwin'",
+    "onnxruntime; sys_platform == 'darwin'",
+]
+classifiers = [
+    "Programming Language :: Python",
+    "Programming Language :: Python :: 3",
+    "Intended Audience :: Science/Research",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Telecommunications Industry",
+    "Topic :: Software Development :: Libraries",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Multimedia",
+    "Topic :: Multimedia :: Sound/Audio",
+    "Topic :: Multimedia :: Sound/Audio :: Speech",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+
+[project.urls]
+Homepage = "https://github.com/nipponjo/selib"
+
+[tool.setuptools.packages.find]
+where = ["."]

speech_selib-0.1.0/selib/__init__.py

@@ -0,0 +1,7 @@
+from .models.factory import enhance, load_model
+from . import metrics
+
+__all__ = [
+    "enhance",
+    "load_model",
+]

speech_selib-0.1.0/selib/metrics/__init__.py

@@ -0,0 +1,31 @@
+from .basic import (
+    mae,
+    mse,
+    power_db,
+    rms,
+    rmse,
+    segmental_snr,
+    segsnr,
+    si_sdr,
+    si_snr,
+    snr,
+)
+
+try:
+    from .dnsmos import DnsMosSigBakOvrOnnx
+except ImportError:
+    DnsMosSigBakOvrOnnx = None
+
+__all__ = [
+    "DnsMosSigBakOvrOnnx",
+    "mae",
+    "mse",
+    "power_db",
+    "rms",
+    "rmse",
+    "segmental_snr",
+    "segsnr",
+    "si_sdr",
+    "si_snr",
+    "snr",
+]

speech_selib-0.1.0/selib/metrics/basic.py

@@ -0,0 +1,245 @@
+"""Lightweight NumPy metrics for speech enhancement.
+
+These metrics do not depend on external perceptual-metric packages such as
+PESQ, STOI, or DNSMOS. They are useful for quick checks, regression tests, and
+objective comparisons when a clean reference signal is available.
+"""
+
+from __future__ import annotations
+
+from typing import Optional, Sequence, Union
+import warnings
+
+import numpy as np
+
+ArrayLike = Union[np.ndarray, Sequence[float]]
+_WARNED_UNEQUAL_LENGTH = False
+
+
+def _as_1d_float(name: str, x: ArrayLike) -> np.ndarray:
+    """Convert input audio to a contiguous 1-D float64 array."""
+    x = np.asarray(x, dtype=np.float64).reshape(-1)
+    if x.size == 0:
+        raise ValueError(f"{name} must contain at least one sample")
+    return x
+
+
+def _align_pair(reference: ArrayLike,
+                estimate: ArrayLike) -> tuple[np.ndarray, np.ndarray]:
+    """Convert and truncate two signals to a shared length."""
+    global _WARNED_UNEQUAL_LENGTH
+    reference = _as_1d_float("reference", reference)
+    estimate = _as_1d_float("estimate", estimate)
+    n = min(reference.size, estimate.size)
+    if n == 0:
+        raise ValueError("reference and estimate must contain samples")
+    if reference.size != estimate.size and not _WARNED_UNEQUAL_LENGTH:
+        warnings.warn(
+            "reference and estimate have unequal lengths "
+            f"({reference.size} vs {estimate.size}); aligning by truncating "
+            f"both signals to the first {n} samples.",
+            RuntimeWarning,
+            stacklevel=2,
+        )
+        _WARNED_UNEQUAL_LENGTH = True
+    return reference[:n], estimate[:n]
+
+
+def power_db(x: ArrayLike, eps: float = 1e-12) -> float:
+    """Return average signal power in dB.
+
+    Parameters
+    ----------
+    x : ndarray
+        Input waveform.
+    eps : float, default=1e-12
+        Numerical floor applied before ``log10``.
+
+    Returns
+    -------
+    float
+        ``10 * log10(mean(x ** 2))`` in dB.
+    """
+    x = _as_1d_float("x", x)
+    return float(10.0 * np.log10(np.mean(np.square(x)) + eps))
+
+
+def rms(x: ArrayLike) -> float:
+    """Return root-mean-square amplitude."""
+    x = _as_1d_float("x", x)
+    return float(np.sqrt(np.mean(np.square(x))))
+
+
+def mse(reference: ArrayLike, estimate: ArrayLike) -> float:
+    """Return mean squared error between two aligned waveforms."""
+    reference, estimate = _align_pair(reference, estimate)
+    return float(np.mean(np.square(reference - estimate)))
+
+
+def rmse(reference: ArrayLike, estimate: ArrayLike) -> float:
+    """Return root mean squared error between two aligned waveforms."""
+    return float(np.sqrt(mse(reference, estimate)))
+
+
+def mae(reference: ArrayLike, estimate: ArrayLike) -> float:
+    """Return mean absolute error between two aligned waveforms."""
+    reference, estimate = _align_pair(reference, estimate)
+    return float(np.mean(np.abs(reference - estimate)))
+
+
+def snr(reference: ArrayLike,
+        estimate: ArrayLike,
+        eps: float = 1e-12) -> float:
+    """Return signal-to-noise ratio in dB.
+
+    ``reference`` is normally the clean speech signal. ``estimate`` may be a
+    noisy or enhanced signal. The residual ``reference - estimate`` is treated
+    as noise/error.
+
+    Parameters
+    ----------
+    reference : ndarray
+        Clean reference waveform.
+    estimate : ndarray
+        Estimated waveform to compare against ``reference``.
+    eps : float, default=1e-12
+        Numerical floor for the denominator.
+
+    Returns
+    -------
+    float
+        SNR in dB.
+    """
+    reference, estimate = _align_pair(reference, estimate)
+    signal_power = np.sum(np.square(reference))
+    noise_power = np.sum(np.square(reference - estimate))
+    return float(10.0 * np.log10((signal_power + eps) / (noise_power + eps)))
+
+
+def segmental_snr(reference: ArrayLike,
+                  estimate: ArrayLike,
+                  sample_rate: int = 16000,
+                  frame_ms: float = 20.0,
+                  hop_ms: Optional[float] = None,
+                  min_snr_db: float = -10.0,
+                  max_snr_db: float = 35.0,
+                  eps: float = 1e-12) -> float:
+    """Return mean clipped frame-wise SNR in dB.
+
+    Segmental SNR computes SNR per short frame and averages the clipped values.
+    Clipping keeps silent or near-silent frames from dominating the score.
+
+    Parameters
+    ----------
+    reference : ndarray
+        Clean reference waveform.
+    estimate : ndarray
+        Estimated waveform to compare against ``reference``.
+    sample_rate : int, default=16000
+        Sample rate in Hz, used to convert frame and hop durations to samples.
+    frame_ms : float, default=20.0
+        Frame length in milliseconds.
+    hop_ms : float, optional
+        Hop length in milliseconds. Defaults to ``frame_ms``.
+    min_snr_db : float, default=-10.0
+        Lower clipping bound for each frame SNR.
+    max_snr_db : float, default=35.0
+        Upper clipping bound for each frame SNR.
+    eps : float, default=1e-12
+        Numerical floor for frame powers.
+
+    Returns
+    -------
+    float
+        Mean clipped segmental SNR in dB.
+    """
+    reference, estimate = _align_pair(reference, estimate)
+    if hop_ms is None:
+        hop_ms = frame_ms
+
+    frame_len = max(1, int(round(sample_rate * frame_ms / 1000.0)))
+    hop_len = max(1, int(round(sample_rate * hop_ms / 1000.0)))
+    if reference.size < frame_len:
+        return snr(reference, estimate, eps=eps)
+
+    values = []
+    for start in range(0, reference.size - frame_len + 1, hop_len):
+        ref_frame = reference[start:start + frame_len]
+        err_frame = ref_frame - estimate[start:start + frame_len]
+        frame_snr = 10.0 * np.log10(
+            (np.sum(np.square(ref_frame)) + eps)
+            / (np.sum(np.square(err_frame)) + eps)
+        )
+        values.append(np.clip(frame_snr, min_snr_db, max_snr_db))
+    return float(np.mean(values))
+
+
+def segsnr(reference: ArrayLike,
+           estimate: ArrayLike,
+           sample_rate: int = 16000,
+           frame_ms: float = 20.0,
+           hop_ms: Optional[float] = None,
+           min_snr_db: float = -10.0,
+           max_snr_db: float = 35.0,
+           eps: float = 1e-12) -> float:
+    """Alias for ``segmental_snr``."""
+    return segmental_snr(
+        reference,
+        estimate,
+        sample_rate=sample_rate,
+        frame_ms=frame_ms,
+        hop_ms=hop_ms,
+        min_snr_db=min_snr_db,
+        max_snr_db=max_snr_db,
+        eps=eps,
+    )
+
+
+def si_sdr(reference: ArrayLike,
+           estimate: ArrayLike,
+           zero_mean: bool = True,
+           eps: float = 1e-12) -> float:
+    """Return scale-invariant signal-to-distortion ratio in dB.
+
+    SI-SDR removes gain differences between ``reference`` and ``estimate``
+    before measuring residual error. This is often more useful than plain SNR
+    when an enhancement model changes output loudness.
+
+    Parameters
+    ----------
+    reference : ndarray
+        Clean reference waveform.
+    estimate : ndarray
+        Estimated waveform to compare against ``reference``.
+    zero_mean : bool, default=True
+        If True, remove the mean from both signals before projection.
+    eps : float, default=1e-12
+        Numerical floor for divisions and logarithms.
+
+    Returns
+    -------
+    float
+        SI-SDR in dB.
+    """
+    reference, estimate = _align_pair(reference, estimate)
+    if zero_mean:
+        reference = reference - np.mean(reference)
+        estimate = estimate - np.mean(estimate)
+
+    scale = np.sum(estimate * reference) / (np.sum(np.square(reference)) + eps)
+    target = scale * reference
+    noise = estimate - target
+    return float(
+        10.0 * np.log10(
+            (np.sum(np.square(target)) + eps)
+            / (np.sum(np.square(noise)) + eps)
+        )
+    )
+
+
+def si_snr(reference: ArrayLike,
+           estimate: ArrayLike,
+           zero_mean: bool = True,
+           eps: float = 1e-12) -> float:
+    """Alias for ``si_sdr``."""
+    return si_sdr(reference, estimate, zero_mean=zero_mean, eps=eps)