audiosronnx 0.0.1__tar.gz

audiosronnx-0.0.1/LICENSE

@@ -0,0 +1,17 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   Copyright 2026 TigreGóticoLda
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

audiosronnx-0.0.1/MANIFEST.in

@@ -0,0 +1,3 @@
+include LICENSE
+include README.md
+recursive-include audiosronnx/data *

audiosronnx-0.0.1/PKG-INFO

@@ -0,0 +1,179 @@
+Metadata-Version: 2.4
+Name: audiosronnx
+Version: 0.0.1
+Summary: Pure-ONNX multi-engine audio super-resolution / bandwidth extension (upscale speech to 48 kHz)
+Author-email: JarbasAi <jarbasai@mailfence.com>
+License: Apache-2.0
+Project-URL: Homepage, https://github.com/TigreGotico/audiosronnx
+Project-URL: Repository, https://github.com/TigreGotico/audiosronnx
+Keywords: audio super resolution,bandwidth extension,speech enhancement,onnx,upsampling,lavasr,novasr,48khz
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
+Classifier: Intended Audience :: Developers
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy
+Requires-Dist: onnxruntime>=1.17
+Requires-Dist: huggingface_hub
+Requires-Dist: scipy
+Requires-Dist: soundfile
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Requires-Dist: pytest-cov; extra == "test"
+Provides-Extra: convert
+Requires-Dist: torch; extra == "convert"
+Requires-Dist: onnx; extra == "convert"
+Requires-Dist: huggingface_hub; extra == "convert"
+Requires-Dist: vocos; extra == "convert"
+Requires-Dist: einops; extra == "convert"
+Dynamic: license-file
+
+# audiosronnx
+
+Pure-ONNX, multi-engine **audio super-resolution / bandwidth extension**. Upscale
+low-sample-rate or low-bandwidth speech — 8 kHz telephony, muffled recordings,
+low-fidelity TTS — to a clean **48 kHz** signal. Inference runs entirely on
+onnxruntime; there is **no torch at runtime**.
+
+audiosronnx is the super-resolution sibling of the TigreGotico pure-ONNX speech
+libraries ([`vadonnx`](https://github.com/TigreGotico/vadonnx),
+[`voiceclonnx`](https://github.com/TigreGotico/voiceclonnx),
+[`speakeronnx`](https://github.com/TigreGotico/speakeronnx)) and mirrors their
+conventions: a single `load_sr(engine=...)` entry point, an engine registry, a
+HuggingFace-backed model resolver with an XDG cache, and a small CLI.
+
+## Install
+
+```bash
+pip install audiosronnx
+```
+
+Runtime dependencies: `numpy`, `onnxruntime`, `scipy`, `soundfile`, `huggingface_hub`.
+ONNX models are downloaded on first use from the Hugging Face Hub and cached under
+`~/.local/share/audiosronnx`.
+
+## Engines
+
+| Engine | Input SR | Output SR | Size | CPU speed | License | Status |
+|--------|----------|-----------|------|-----------|---------|--------|
+| **lavasr** (default) | 8–48 kHz | 48 kHz | ~52 MB | ~50× realtime | Apache-2.0 | shipped |
+| **novasr** | 16 kHz | 48 kHz | ~52 KB | ~1000× realtime | Apache-2.0 | shipped |
+
+- **lavasr** — a Vocos-based bandwidth-extension model with a Linkwitz-Riley spectral
+  merge that preserves the original low band, plus an optional UL-UNAS denoiser. It
+  accepts any input rate from 8 to 48 kHz and is the best-quality engine. All spectral
+  DSP (STFT, ISTFT, mel filterbank, resampling, merge) runs in numpy/scipy, so no
+  `torch.stft` ever enters an ONNX graph.
+- **novasr** — a tiny conv1d / BigVGAN-snake generator that upsamples 16 kHz to 48 kHz
+  in a single time-domain pass. Extremely fast and memory-light, at lower fidelity than
+  lavasr; useful for on-device enhancement and quick dataset restoration.
+
+Both engines are derived from the LavaSR/NovaSR projects by Yatharth Sharma
+([LavaSR](https://github.com/ysharma3501/LavaSR),
+[NovaSR](https://github.com/ysharma3501/NovaSR)), Apache-2.0.
+
+## Quickstart
+
+```python
+from audiosronnx import load_sr
+
+sr = load_sr("lavasr")                      # default engine
+
+# low-level primitive: numpy array or path in, (float32 mono, 48000) out
+out, rate = sr.upscale("telephone_8k.wav")  # -> (np.ndarray float32, 48000)
+
+# array input (you supply the sample rate)
+import soundfile as sf
+audio, in_sr = sf.read("input.wav")
+out, rate = sr.upscale(audio, in_sr)
+
+# file / directory helpers
+sr.upscale_file("in.wav", "out_48k.wav")
+sr.upscale_dir("clips_in/", "clips_out_48k/")
+
+# the fast tiny engine instead
+fast = load_sr("novasr")
+fast.upscale_file("in_16k.wav", "out_48k.wav")
+```
+
+LavaSR options:
+
+```python
+sr = load_sr("lavasr", denoise=True, cutoff_hz=6000)
+```
+
+## CLI
+
+```bash
+audiosronnx list                              # list engines
+audiosronnx probe input.wav                   # print format / duration
+audiosronnx upscale in.wav out.wav            # default engine (lavasr)
+audiosronnx upscale in.wav out.wav --engine novasr
+audiosronnx upscale in.wav out.wav --denoise  # lavasr denoiser stage
+audiosronnx upscale-dir clips_in/ clips_out/
+```
+
+## API
+
+- `load_sr(engine="lavasr", *, providers=None, cache_dir=None, revision=None, **kwargs) -> SRModel`
+- `SRModel.upscale(audio, sample_rate=None) -> (np.ndarray float32 mono, 48000)` —
+  `audio` is a path, raw int16 PCM bytes, or a numpy array. The low-level primitive.
+- `SRModel.upscale_file(in_path, out_path) -> str`
+- `SRModel.upscale_dir(in_dir, out_dir) -> list[str]`
+- `available_models()`, `get_engine(alias)`, `register_engine(entry)`, `ENGINE_REGISTRY`
+
+### Custom / third-party engines
+
+Subclass `SRModel`, implement `_upscale_array(audio, sample_rate) -> np.ndarray` (a
+48 kHz mono float32 array), and register an `EngineEntry`:
+
+```python
+from audiosronnx import SRModel, EngineEntry, register_engine
+
+class MySR(SRModel):
+    output_sample_rate = 48000
+    def _upscale_array(self, audio, sample_rate):
+        ...  # run your ONNX session, return a 48 kHz float32 array
+
+register_engine(EngineEntry(alias="mysr", adapter_class=MySR, license="MIT"))
+```
+
+## Model hosting
+
+Exported ONNX weights are hosted on the Hugging Face Hub and pinned by revision:
+
+- `TigreGotico/audiosronnx-lavasr` — `backbone.onnx`, `spec_head.onnx`, `denoiser_core.onnx`
+- `TigreGotico/audiosronnx-novasr` — `novasr.onnx`
+
+The export scripts under `conversion/` reproduce these from the upstream PyTorch
+checkpoints and validate each ONNX graph against its PyTorch submodule (max absolute
+error).
+
+## Evaluated but not shipped
+
+The audio super-resolution landscape was surveyed for other models to export. These
+were evaluated and are **not** shipped, for the reasons given:
+
+| Model | License | Reason not shipped |
+|-------|---------|--------------------|
+| **AP-BWE** | MIT | Permissive and ONNX-friendly (convolutional amplitude/phase predictor; STFT stays outside the graph). A strong candidate not yet packaged here. |
+| **HiFi-GAN-BWE** | MIT | Permissive, time-domain, ships its own export script. A strong candidate not yet packaged here. |
+| **FLowHigh** | MIT | Single-step flow matching, but depends on an external BigVGAN vocoder plus a mel/STFT front-end — a multi-component export rather than one clean graph. |
+| **AudioSR** | MIT | ~6 GB latent-diffusion model (VAE + LDM + vocoder, iterative sampler, ~0.6× realtime on GPU). Not CPU-runnable at usable latency; impractical to export. |
+| **NU-Wave2** | none | Diffusion (iterative sampler) and the repository ships no license file. |
+| **mdctGAN** | unclear (NOASSERTION) | Unclear license, and its MDCT front-end relies on `torch.fft`, which exports to ONNX unreliably. |
+| **VoiceFixer / NVSR** | MIT | Speech *restoration* rather than pure bandwidth extension; two-stage mel-predictor + neural vocoder, heavier and less focused than the shipped engines. |
+
+An engine is only shipped when it exports cleanly to ONNX, runs on CPU via
+onnxruntime, carries a permissive license, and produces verified 48 kHz output.
+
+## License
+
+Apache-2.0. The shipped model weights are Apache-2.0 (LavaSR, NovaSR).

audiosronnx-0.0.1/README.md

@@ -0,0 +1,142 @@
+# audiosronnx
+
+Pure-ONNX, multi-engine **audio super-resolution / bandwidth extension**. Upscale
+low-sample-rate or low-bandwidth speech — 8 kHz telephony, muffled recordings,
+low-fidelity TTS — to a clean **48 kHz** signal. Inference runs entirely on
+onnxruntime; there is **no torch at runtime**.
+
+audiosronnx is the super-resolution sibling of the TigreGotico pure-ONNX speech
+libraries ([`vadonnx`](https://github.com/TigreGotico/vadonnx),
+[`voiceclonnx`](https://github.com/TigreGotico/voiceclonnx),
+[`speakeronnx`](https://github.com/TigreGotico/speakeronnx)) and mirrors their
+conventions: a single `load_sr(engine=...)` entry point, an engine registry, a
+HuggingFace-backed model resolver with an XDG cache, and a small CLI.
+
+## Install
+
+```bash
+pip install audiosronnx
+```
+
+Runtime dependencies: `numpy`, `onnxruntime`, `scipy`, `soundfile`, `huggingface_hub`.
+ONNX models are downloaded on first use from the Hugging Face Hub and cached under
+`~/.local/share/audiosronnx`.
+
+## Engines
+
+| Engine | Input SR | Output SR | Size | CPU speed | License | Status |
+|--------|----------|-----------|------|-----------|---------|--------|
+| **lavasr** (default) | 8–48 kHz | 48 kHz | ~52 MB | ~50× realtime | Apache-2.0 | shipped |
+| **novasr** | 16 kHz | 48 kHz | ~52 KB | ~1000× realtime | Apache-2.0 | shipped |
+
+- **lavasr** — a Vocos-based bandwidth-extension model with a Linkwitz-Riley spectral
+  merge that preserves the original low band, plus an optional UL-UNAS denoiser. It
+  accepts any input rate from 8 to 48 kHz and is the best-quality engine. All spectral
+  DSP (STFT, ISTFT, mel filterbank, resampling, merge) runs in numpy/scipy, so no
+  `torch.stft` ever enters an ONNX graph.
+- **novasr** — a tiny conv1d / BigVGAN-snake generator that upsamples 16 kHz to 48 kHz
+  in a single time-domain pass. Extremely fast and memory-light, at lower fidelity than
+  lavasr; useful for on-device enhancement and quick dataset restoration.
+
+Both engines are derived from the LavaSR/NovaSR projects by Yatharth Sharma
+([LavaSR](https://github.com/ysharma3501/LavaSR),
+[NovaSR](https://github.com/ysharma3501/NovaSR)), Apache-2.0.
+
+## Quickstart
+
+```python
+from audiosronnx import load_sr
+
+sr = load_sr("lavasr")                      # default engine
+
+# low-level primitive: numpy array or path in, (float32 mono, 48000) out
+out, rate = sr.upscale("telephone_8k.wav")  # -> (np.ndarray float32, 48000)
+
+# array input (you supply the sample rate)
+import soundfile as sf
+audio, in_sr = sf.read("input.wav")
+out, rate = sr.upscale(audio, in_sr)
+
+# file / directory helpers
+sr.upscale_file("in.wav", "out_48k.wav")
+sr.upscale_dir("clips_in/", "clips_out_48k/")
+
+# the fast tiny engine instead
+fast = load_sr("novasr")
+fast.upscale_file("in_16k.wav", "out_48k.wav")
+```
+
+LavaSR options:
+
+```python
+sr = load_sr("lavasr", denoise=True, cutoff_hz=6000)
+```
+
+## CLI
+
+```bash
+audiosronnx list                              # list engines
+audiosronnx probe input.wav                   # print format / duration
+audiosronnx upscale in.wav out.wav            # default engine (lavasr)
+audiosronnx upscale in.wav out.wav --engine novasr
+audiosronnx upscale in.wav out.wav --denoise  # lavasr denoiser stage
+audiosronnx upscale-dir clips_in/ clips_out/
+```
+
+## API
+
+- `load_sr(engine="lavasr", *, providers=None, cache_dir=None, revision=None, **kwargs) -> SRModel`
+- `SRModel.upscale(audio, sample_rate=None) -> (np.ndarray float32 mono, 48000)` —
+  `audio` is a path, raw int16 PCM bytes, or a numpy array. The low-level primitive.
+- `SRModel.upscale_file(in_path, out_path) -> str`
+- `SRModel.upscale_dir(in_dir, out_dir) -> list[str]`
+- `available_models()`, `get_engine(alias)`, `register_engine(entry)`, `ENGINE_REGISTRY`
+
+### Custom / third-party engines
+
+Subclass `SRModel`, implement `_upscale_array(audio, sample_rate) -> np.ndarray` (a
+48 kHz mono float32 array), and register an `EngineEntry`:
+
+```python
+from audiosronnx import SRModel, EngineEntry, register_engine
+
+class MySR(SRModel):
+    output_sample_rate = 48000
+    def _upscale_array(self, audio, sample_rate):
+        ...  # run your ONNX session, return a 48 kHz float32 array
+
+register_engine(EngineEntry(alias="mysr", adapter_class=MySR, license="MIT"))
+```
+
+## Model hosting
+
+Exported ONNX weights are hosted on the Hugging Face Hub and pinned by revision:
+
+- `TigreGotico/audiosronnx-lavasr` — `backbone.onnx`, `spec_head.onnx`, `denoiser_core.onnx`
+- `TigreGotico/audiosronnx-novasr` — `novasr.onnx`
+
+The export scripts under `conversion/` reproduce these from the upstream PyTorch
+checkpoints and validate each ONNX graph against its PyTorch submodule (max absolute
+error).
+
+## Evaluated but not shipped
+
+The audio super-resolution landscape was surveyed for other models to export. These
+were evaluated and are **not** shipped, for the reasons given:
+
+| Model | License | Reason not shipped |
+|-------|---------|--------------------|
+| **AP-BWE** | MIT | Permissive and ONNX-friendly (convolutional amplitude/phase predictor; STFT stays outside the graph). A strong candidate not yet packaged here. |
+| **HiFi-GAN-BWE** | MIT | Permissive, time-domain, ships its own export script. A strong candidate not yet packaged here. |
+| **FLowHigh** | MIT | Single-step flow matching, but depends on an external BigVGAN vocoder plus a mel/STFT front-end — a multi-component export rather than one clean graph. |
+| **AudioSR** | MIT | ~6 GB latent-diffusion model (VAE + LDM + vocoder, iterative sampler, ~0.6× realtime on GPU). Not CPU-runnable at usable latency; impractical to export. |
+| **NU-Wave2** | none | Diffusion (iterative sampler) and the repository ships no license file. |
+| **mdctGAN** | unclear (NOASSERTION) | Unclear license, and its MDCT front-end relies on `torch.fft`, which exports to ONNX unreliably. |
+| **VoiceFixer / NVSR** | MIT | Speech *restoration* rather than pure bandwidth extension; two-stage mel-predictor + neural vocoder, heavier and less focused than the shipped engines. |
+
+An engine is only shipped when it exports cleanly to ONNX, runs on CPU via
+onnxruntime, carries a permissive license, and produces verified 48 kHz output.
+
+## License
+
+Apache-2.0. The shipped model weights are Apache-2.0 (LavaSR, NovaSR).

audiosronnx-0.0.1/audiosronnx/__init__.py

@@ -0,0 +1,39 @@
+"""audiosronnx — pure-ONNX multi-engine audio super-resolution / bandwidth extension.
+
+Upscale low-sample-rate or low-bandwidth speech (e.g. 8 kHz telephony) to a clean
+48 kHz signal. Inference runs entirely on onnxruntime — no torch at runtime.
+
+Quick start::
+
+    from audiosronnx import load_sr
+
+    sr = load_sr("lavasr")                       # default engine
+    out, rate = sr.upscale("telephone_8k.wav")   # -> (float32 mono array, 48000)
+    sr.upscale_file("in.wav", "out_48k.wav")
+
+Engines are downloaded on first use from Hugging Face Hub and cached under an XDG
+data directory. ``load_sr("novasr")`` selects the tiny fast engine instead.
+"""
+from .api import load_sr
+from .base import (
+    ENGINE_REGISTRY,
+    OUTPUT_SAMPLE_RATE,
+    EngineEntry,
+    SRModel,
+    available_models,
+    get_engine,
+    register_engine,
+)
+from .version import __version__
+
+__all__ = [
+    "load_sr",
+    "available_models",
+    "SRModel",
+    "EngineEntry",
+    "ENGINE_REGISTRY",
+    "register_engine",
+    "get_engine",
+    "OUTPUT_SAMPLE_RATE",
+    "__version__",
+]

audiosronnx-0.0.1/audiosronnx/api.py

@@ -0,0 +1,45 @@
+"""Public entry point: :func:`load_sr`."""
+from __future__ import annotations
+
+from typing import List, Optional
+
+from .base import SRModel, available_models, get_engine
+
+# Importing the engines package registers every built-in adapter.
+from . import engines  # noqa: F401
+
+__all__ = ["load_sr", "available_models"]
+
+DEFAULT_ENGINE = "lavasr"
+
+
+def load_sr(
+    engine: str = DEFAULT_ENGINE,
+    *,
+    providers: Optional[List[str]] = None,
+    cache_dir: Optional[str] = None,
+    revision: Optional[str] = None,
+    **engine_kwargs,
+) -> SRModel:
+    """Load an audio super-resolution engine behind the unified :class:`SRModel` API.
+
+    Args:
+        engine: registry alias (``"lavasr"`` (default) or ``"novasr"``).
+        providers: onnxruntime execution providers (default CPU).
+        cache_dir: override the model download cache directory.
+        revision: pin a HuggingFace revision for the model weights.
+        **engine_kwargs: forwarded to the engine adapter (e.g. ``denoise=True``,
+            ``cutoff_hz=6000`` for LavaSR).
+
+    Returns:
+        A ready-to-use :class:`~audiosronnx.base.SRModel`.
+
+    Example:
+        >>> from audiosronnx import load_sr
+        >>> sr = load_sr("lavasr")
+        >>> out, rate = sr.upscale("telephone_8k.wav")   # -> (float32 array, 48000)
+    """
+    entry = get_engine(engine)
+    return entry.adapter_class(
+        providers=providers, cache_dir=cache_dir, revision=revision, **engine_kwargs
+    )

audiosronnx-0.0.1/audiosronnx/audio.py

@@ -0,0 +1,128 @@
+"""Audio I/O and resampling helpers (numpy core, soundfile for file I/O).
+
+Everything in :mod:`audiosronnx` works internally with mono ``float32`` PCM in the
+range ``[-1, 1]``. These helpers convert the shapes users pass in (a WAV path or a
+numpy array of various dtypes) into that canonical form, and resample between rates.
+"""
+from __future__ import annotations
+
+import math
+import wave
+from typing import Tuple, Union
+
+import numpy as np
+
+AudioLike = Union[str, bytes, bytearray, memoryview, np.ndarray]
+
+
+def to_float32_mono(audio: Union[bytes, bytearray, memoryview, np.ndarray]) -> np.ndarray:
+    """Convert audio of various dtypes/containers to mono float32 in [-1, 1].
+
+    Accepts raw little-endian ``int16`` PCM bytes, or a numpy array of dtype
+    ``int16`` / ``int32`` / ``uint8`` / ``float32`` / ``float64``. Multi-channel
+    arrays (shape ``(n, channels)``) are downmixed by averaging channels.
+    """
+    if isinstance(audio, (bytes, bytearray, memoryview)):
+        return np.frombuffer(bytes(audio), dtype="<i2").astype(np.float32) / 32768.0
+
+    if not isinstance(audio, np.ndarray):
+        raise TypeError(f"audio must be bytes or np.ndarray, got {type(audio).__name__}")
+
+    arr = audio
+    if arr.ndim == 2:
+        arr = arr.mean(axis=1)
+    elif arr.ndim > 2:
+        raise ValueError(f"audio array must be 1-D or 2-D, got {arr.ndim}-D")
+
+    if arr.dtype == np.float32:
+        out = arr
+    elif arr.dtype == np.float64:
+        out = arr.astype(np.float32)
+    elif arr.dtype == np.int16:
+        out = arr.astype(np.float32) / 32768.0
+    elif arr.dtype == np.int32:
+        out = arr.astype(np.float32) / 2147483648.0
+    elif arr.dtype == np.uint8:
+        out = (arr.astype(np.float32) - 128.0) / 128.0
+    else:
+        raise TypeError(f"unsupported audio dtype: {arr.dtype}")
+
+    return np.ascontiguousarray(out, dtype=np.float32)
+
+
+def resample(x: np.ndarray, src_sr: int, dst_sr: int) -> np.ndarray:
+    """Resample mono float32 audio from ``src_sr`` to ``dst_sr``.
+
+    Uses ``scipy.signal.resample_poly`` when SciPy is installed (the default for a
+    full install), otherwise falls back to linear interpolation via
+    :func:`numpy.interp`.
+    """
+    if src_sr == dst_sr or x.size == 0:
+        return x.astype(np.float32, copy=False)
+    try:
+        from scipy.signal import resample_poly  # type: ignore
+
+        g = math.gcd(int(src_sr), int(dst_sr))
+        up, down = int(dst_sr) // g, int(src_sr) // g
+        return resample_poly(x, up, down).astype(np.float32)
+    except Exception:
+        n_out = int(round(x.shape[0] * dst_sr / src_sr))
+        if n_out <= 0:
+            return np.zeros(0, dtype=np.float32)
+        src_idx = np.linspace(0.0, x.shape[0] - 1, num=n_out, dtype=np.float64)
+        return np.interp(src_idx, np.arange(x.shape[0]), x).astype(np.float32)
+
+
+def read_wav(path: str) -> Tuple[np.ndarray, int]:
+    """Read audio into mono float32. Returns ``(audio, sample_rate)``.
+
+    Uses :mod:`soundfile` when available (handles WAV/FLAC/OGG and any subtype),
+    otherwise falls back to the standard-library :mod:`wave` module for PCM WAV.
+    """
+    try:
+        import soundfile as sf  # type: ignore
+
+        audio, sr = sf.read(str(path), dtype="float32", always_2d=False)
+        if audio.ndim > 1:
+            audio = audio.mean(axis=1)
+        return np.ascontiguousarray(audio, dtype=np.float32), int(sr)
+    except ImportError:
+        pass
+
+    with wave.open(str(path), "rb") as wf:
+        sr = wf.getframerate()
+        n_channels = wf.getnchannels()
+        sampwidth = wf.getsampwidth()
+        raw = wf.readframes(wf.getnframes())
+
+    if sampwidth == 2:
+        arr = np.frombuffer(raw, dtype="<i2").astype(np.float32) / 32768.0
+    elif sampwidth == 4:
+        arr = np.frombuffer(raw, dtype="<i4").astype(np.float32) / 2147483648.0
+    elif sampwidth == 1:
+        arr = (np.frombuffer(raw, dtype=np.uint8).astype(np.float32) - 128.0) / 128.0
+    else:
+        raise ValueError(f"unsupported WAV sample width: {sampwidth} bytes")
+
+    if n_channels > 1:
+        arr = arr.reshape(-1, n_channels).mean(axis=1)
+    return np.ascontiguousarray(arr, dtype=np.float32), sr
+
+
+def write_wav(path: str, audio: np.ndarray, sample_rate: int) -> None:
+    """Write mono float32 ``audio`` as 16-bit PCM WAV to ``path``."""
+    audio = np.clip(np.asarray(audio, dtype=np.float32), -1.0, 1.0)
+    try:
+        import soundfile as sf  # type: ignore
+
+        sf.write(str(path), audio, int(sample_rate), subtype="PCM_16")
+        return
+    except ImportError:
+        pass
+
+    pcm = (audio * 32767.0).astype("<i2")
+    with wave.open(str(path), "wb") as wf:
+        wf.setnchannels(1)
+        wf.setsampwidth(2)
+        wf.setframerate(int(sample_rate))
+        wf.writeframes(pcm.tobytes())