cascadevad-onnx 0.1.0__tar.gz

cascadevad_onnx-0.1.0/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog
+
+## 0.1.0
+
+Initial release of **cascadevad**, a derivative work of
+[vadonnx](https://github.com/TigreGotico/vadonnx) (© TigreGótico Lda, Apache-2.0).
+
+- Renamed the package to `cascadevad`.
+- Added the cost-adaptive **confidence-gated cascade** (`cascadevad.cascade`): a cheap gate
+  VAD runs on every frame and a strong expert VAD is invoked only where it would change the
+  decision, with pluggable routing, an admission-control SLA, calibration, and a fused
+  cost-adaptive ensemble.
+- Re-hosted the ONNX model mirror at
+  [`aryashah00/cascadevad-models`](https://huggingface.co/aryashah00/cascadevad-models)
+  (one subfolder per model).
+- Unified multi-backend VAD serving over ONNX Runtime (Silero, MarbleNet, pyannote, FSMN,
+  SpeechBrain, TEN) inherited from the upstream project.

cascadevad_onnx-0.1.0/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.

cascadevad_onnx-0.1.0/MANIFEST.in

@@ -0,0 +1,5 @@
+include LICENSE
+include README.md
+include CHANGELOG.md
+recursive-include cascadevad/data *.onnx *.json *.npz *.npy
+recursive-include test/resources *

cascadevad_onnx-0.1.0/NOTICE

@@ -0,0 +1,14 @@
+cascadevad
+Copyright 2026 aistra
+
+This product is a derivative work of "vadonnx"
+Copyright 2026 TigreGótico Lda (https://github.com/TigreGotico/vadonnx),
+licensed under the Apache License, Version 2.0 (see LICENSE).
+
+Modifications by aistra (Arya Shah <arya.shah@aistra.com>): renamed the package to
+cascadevad, added the cost-adaptive confidence-gated cascade (cascadevad/cascade.py),
+and re-hosted the ONNX model mirror at https://huggingface.co/aryashah00/cascadevad-models.
+
+Bundled and downloaded VAD model weights retain their respective upstream licenses
+(Silero, NVIDIA NeMo Frame-VAD/MarbleNet, pyannote segmentation-3.0, FunASR FSMN,
+SpeechBrain, TEN). See docs/licensing.md for per-model license terms.

cascadevad_onnx-0.1.0/PKG-INFO

@@ -0,0 +1,135 @@
+Metadata-Version: 2.4
+Name: cascadevad-onnx
+Version: 0.1.0
+Summary: Load arbitrary Voice Activity Detection (VAD) models behind a unified ONNX API
+Author-email: Arya Shah <arya.shah@aistra.com>
+License: Apache-2.0
+Project-URL: Homepage, https://github.com/arya-aistra/cascadevad
+Project-URL: Repository, https://github.com/arya-aistra/cascadevad
+Project-URL: Models, https://huggingface.co/aryashah00/cascadevad-models
+Keywords: vad,voice activity detection,onnx,speech,silero,audio
+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: Programming Language :: Python :: 3.14
+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
+License-File: NOTICE
+Requires-Dist: numpy
+Requires-Dist: onnxruntime>=1.17
+Requires-Dist: huggingface_hub
+Provides-Extra: fsmn
+Requires-Dist: kaldi-native-fbank; extra == "fsmn"
+Provides-Extra: mic
+Requires-Dist: sounddevice; extra == "mic"
+Provides-Extra: resample
+Requires-Dist: scipy; extra == "resample"
+Provides-Extra: all
+Requires-Dist: kaldi-native-fbank; extra == "all"
+Requires-Dist: sounddevice; extra == "all"
+Requires-Dist: scipy; extra == "all"
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Requires-Dist: pytest-cov; extra == "test"
+Provides-Extra: convert
+Requires-Dist: onnx; extra == "convert"
+Requires-Dist: huggingface_hub; extra == "convert"
+Requires-Dist: requests; extra == "convert"
+Provides-Extra: convert-marblenet
+Requires-Dist: cascadevad-onnx[convert]; extra == "convert-marblenet"
+Requires-Dist: nemo_toolkit[asr]; extra == "convert-marblenet"
+Requires-Dist: torch; extra == "convert-marblenet"
+Provides-Extra: convert-speechbrain
+Requires-Dist: cascadevad-onnx[convert]; extra == "convert-speechbrain"
+Requires-Dist: speechbrain; extra == "convert-speechbrain"
+Requires-Dist: torch; extra == "convert-speechbrain"
+Dynamic: license-file
+
+# cascadevad
+
+Load arbitrary **Voice Activity Detection** models behind a single, unified API — every
+model runs through [ONNX Runtime](https://onnxruntime.ai/). One streaming/​batch
+interface, one audio-format story, pluggable models.
+
+```python
+from cascadevad import load_vad
+
+vad = load_vad("silero")                              # bundled, works fully offline
+prob = vad.process_chunk(pcm_bytes)                   # streaming → float in [0, 1]
+segments = vad.get_speech_segments(audio, sample_rate=16000)
+# -> [SpeechSegment(start=0.32, end=2.27), SpeechSegment(start=3.27, end=4.45), ...]
+```
+
+## Why
+
+Every VAD ships its own loader, audio format, feature pipeline and state handling.
+`cascadevad` hides that behind one `VADModel` interface: feed it audio (raw `int16`
+bytes, numpy arrays, any sample rate) and get back per-frame speech probabilities or
+ready-made speech segments. Models are described *declaratively* by an
+[`IOSignature`](docs/custom_models.md), so a single generic engine drives most of them
+and you can point the same API at any custom `.onnx` file.
+
+- **Lightweight runtime** — only `numpy`, `onnxruntime`, `huggingface_hub`.
+- **Offline by default** — a small Silero model is bundled in the wheel.
+- **Streaming and batch** — `process_chunk()` for live audio, `get_speech_segments()` /
+  `probabilities()` for whole buffers.
+- **Bring your own model** — load any ONNX VAD by path/URL with a signature.
+- **Extensible** — third parties register backends/models via entry points.
+
+## Install
+
+```bash
+uv pip install cascadevad-onnx          # runtime (numpy + onnxruntime + huggingface_hub)
+uv pip install "cascadevad-onnx[mic]"   # + microphone examples
+```
+
+## Models
+
+| name | rate | parity vs upstream | notes |
+|------|------|--------------------|-------|
+| `silero` / `silero-8k` / `silero-op15` | 16k / 8k / 16k | MAE 0 | bundled default, raw PCM |
+| `marblenet` / `marblenet-int8` | 16k | MAE 4e-4 | NVIDIA NeMo Frame-VAD, multilingual ([license](docs/licensing.md)) |
+| `pyannote` / `pyannote-int8` | 16k | MAE 0 | pyannote segmentation-3.0, windowed |
+| `fsmn` / `fsmn-quant` | 16k | tracks upstream | FunASR FSMN-VAD; needs `cascadevad-onnx[fsmn]` |
+| `speechbrain` | 16k | MAE 0 | SpeechBrain CRDNN, LibriParty-trained |
+| `ten` | 16k | — | feature extractor provided by TEN's native library |
+
+See [docs/backends.md](docs/backends.md) for per-model detail and the
+[benchmark](benchmark/results/REPORT.md) for measured comparisons across datasets,
+including WebRTC and energy baselines.
+
+Models other than the bundled Silero are downloaded on first use from the
+[`aryashah00/cascadevad-models`](https://huggingface.co/aryashah00/cascadevad-models) HuggingFace
+repo and cached under `$XDG_DATA_HOME/cascadevad`. See [docs/backends.md](docs/backends.md) for
+per-model detail and parity notes.
+
+## CLI
+
+```bash
+cascadevad list                       # list available models
+cascadevad probe silero               # print a model's ONNX input/output signature
+cascadevad segment speech.wav         # print detected speech segments of a WAV
+```
+
+## Documentation
+
+- [Quickstart](docs/quickstart.md)
+- [Streaming](docs/streaming.md)
+- [Custom models & `IOSignature`](docs/custom_models.md)
+- [Backends & parity notes](docs/backends.md)
+- [Plugins](docs/plugins.md)
+- [Model conversion](docs/conversion.md)
+- [Licensing](docs/licensing.md)
+- [API reference](docs/api.md)
+
+## License
+
+Apache-2.0. Bundled/downloaded model weights retain their upstream licenses — see
+[docs/licensing.md](docs/licensing.md).

cascadevad_onnx-0.1.0/README.md

@@ -0,0 +1,81 @@
+# cascadevad
+
+Load arbitrary **Voice Activity Detection** models behind a single, unified API — every
+model runs through [ONNX Runtime](https://onnxruntime.ai/). One streaming/​batch
+interface, one audio-format story, pluggable models.
+
+```python
+from cascadevad import load_vad
+
+vad = load_vad("silero")                              # bundled, works fully offline
+prob = vad.process_chunk(pcm_bytes)                   # streaming → float in [0, 1]
+segments = vad.get_speech_segments(audio, sample_rate=16000)
+# -> [SpeechSegment(start=0.32, end=2.27), SpeechSegment(start=3.27, end=4.45), ...]
+```
+
+## Why
+
+Every VAD ships its own loader, audio format, feature pipeline and state handling.
+`cascadevad` hides that behind one `VADModel` interface: feed it audio (raw `int16`
+bytes, numpy arrays, any sample rate) and get back per-frame speech probabilities or
+ready-made speech segments. Models are described *declaratively* by an
+[`IOSignature`](docs/custom_models.md), so a single generic engine drives most of them
+and you can point the same API at any custom `.onnx` file.
+
+- **Lightweight runtime** — only `numpy`, `onnxruntime`, `huggingface_hub`.
+- **Offline by default** — a small Silero model is bundled in the wheel.
+- **Streaming and batch** — `process_chunk()` for live audio, `get_speech_segments()` /
+  `probabilities()` for whole buffers.
+- **Bring your own model** — load any ONNX VAD by path/URL with a signature.
+- **Extensible** — third parties register backends/models via entry points.
+
+## Install
+
+```bash
+uv pip install cascadevad-onnx          # runtime (numpy + onnxruntime + huggingface_hub)
+uv pip install "cascadevad-onnx[mic]"   # + microphone examples
+```
+
+## Models
+
+| name | rate | parity vs upstream | notes |
+|------|------|--------------------|-------|
+| `silero` / `silero-8k` / `silero-op15` | 16k / 8k / 16k | MAE 0 | bundled default, raw PCM |
+| `marblenet` / `marblenet-int8` | 16k | MAE 4e-4 | NVIDIA NeMo Frame-VAD, multilingual ([license](docs/licensing.md)) |
+| `pyannote` / `pyannote-int8` | 16k | MAE 0 | pyannote segmentation-3.0, windowed |
+| `fsmn` / `fsmn-quant` | 16k | tracks upstream | FunASR FSMN-VAD; needs `cascadevad-onnx[fsmn]` |
+| `speechbrain` | 16k | MAE 0 | SpeechBrain CRDNN, LibriParty-trained |
+| `ten` | 16k | — | feature extractor provided by TEN's native library |
+
+See [docs/backends.md](docs/backends.md) for per-model detail and the
+[benchmark](benchmark/results/REPORT.md) for measured comparisons across datasets,
+including WebRTC and energy baselines.
+
+Models other than the bundled Silero are downloaded on first use from the
+[`aryashah00/cascadevad-models`](https://huggingface.co/aryashah00/cascadevad-models) HuggingFace
+repo and cached under `$XDG_DATA_HOME/cascadevad`. See [docs/backends.md](docs/backends.md) for
+per-model detail and parity notes.
+
+## CLI
+
+```bash
+cascadevad list                       # list available models
+cascadevad probe silero               # print a model's ONNX input/output signature
+cascadevad segment speech.wav         # print detected speech segments of a WAV
+```
+
+## Documentation
+
+- [Quickstart](docs/quickstart.md)
+- [Streaming](docs/streaming.md)
+- [Custom models & `IOSignature`](docs/custom_models.md)
+- [Backends & parity notes](docs/backends.md)
+- [Plugins](docs/plugins.md)
+- [Model conversion](docs/conversion.md)
+- [Licensing](docs/licensing.md)
+- [API reference](docs/api.md)
+
+## License
+
+Apache-2.0. Bundled/downloaded model weights retain their upstream licenses — see
+[docs/licensing.md](docs/licensing.md).

cascadevad_onnx-0.1.0/cascadevad/__init__.py

@@ -0,0 +1,36 @@
+"""cascadevad — load arbitrary Voice Activity Detection models behind a unified ONNX API.
+
+Quick start::
+
+    from cascadevad import load_vad
+
+    vad = load_vad("silero")                       # bundled, works offline
+    prob = vad.process_chunk(pcm_bytes)            # streaming, float in [0, 1]
+    segments = vad.get_speech_segments(audio, sample_rate=16000)
+"""
+from .api import list_models, load_vad, register_model
+from .base import VADModel
+from .cascade import (
+    AdmissionController,
+    CascadeVAD,
+    UncertaintyBandRouter,
+)
+from .registry import ModelSpec
+from .segment import SpeechSegment, probs_to_segments
+from .signature import IOSignature
+from .version import __version__
+
+__all__ = [
+    "load_vad",
+    "list_models",
+    "register_model",
+    "VADModel",
+    "CascadeVAD",
+    "UncertaintyBandRouter",
+    "AdmissionController",
+    "IOSignature",
+    "ModelSpec",
+    "SpeechSegment",
+    "probs_to_segments",
+    "__version__",
+]

cascadevad_onnx-0.1.0/cascadevad/api.py

@@ -0,0 +1,109 @@
+"""Public entry points: :func:`load_vad`, :func:`list_models`, :func:`register_model`."""
+from __future__ import annotations
+
+from typing import List, Optional, Union
+
+from .base import VADModel
+from .registry import (
+    ModelSpec,
+    get_backend,
+    get_spec,
+    list_models,
+    register_model,
+)
+from .resolver import (
+    download_url,
+    is_onnx_path,
+    is_url,
+    resolve_spec_file,
+    sidecar_signature,
+)
+from .signature import IOSignature, coerce_signature
+
+__all__ = ["load_vad", "list_models", "register_model"]
+
+
+def load_vad(
+    name: str = "silero",
+    *,
+    signature: Union[IOSignature, dict, None] = None,
+    threshold: Optional[float] = None,
+    neg_threshold: Optional[float] = None,
+    providers: Optional[List[str]] = None,
+    intra_threads: int = 1,
+    inter_threads: int = 1,
+    revision: Optional[str] = None,
+    cache_dir: Optional[str] = None,
+    **backend_kwargs,
+) -> VADModel:
+    """Load a VAD model behind the unified :class:`~cascadevad.base.VADModel` API.
+
+    ``name`` may be a built-in/registered/plugin model name (e.g. ``"silero"``,
+    ``"ten"``, ``"fsmn"``, ``"marblenet"``), a local ``.onnx`` path, or an
+    ``http(s)://`` URL. For an arbitrary custom ONNX file, pass ``signature`` (an
+    :class:`IOSignature` or dict) describing its IO; if omitted, a
+    ``<model>.signature.json`` sidecar is used when present.
+
+    Args:
+        name: model name, ``.onnx`` path, or URL.
+        signature: required for custom ONNX without a sidecar; ignored for known models
+            unless you want to override the registry signature.
+        threshold: activation threshold for speech. When omitted, each backend's own
+            default applies (0.5 for most models, 0.7 for ``speechbrain``).
+        neg_threshold: deactivation threshold (defaults to ``threshold - 0.15``).
+        providers: ONNX Runtime execution providers (default CPU).
+        intra_threads / inter_threads: ORT threading (default 1 each, low latency).
+        revision: pin a HuggingFace revision (overrides the registry default).
+        cache_dir: override the download cache directory.
+        **backend_kwargs: forwarded to the backend constructor.
+
+    Returns:
+        A ready-to-use :class:`~cascadevad.base.VADModel`.
+    """
+    sig = coerce_signature(signature)
+
+    # common backend kwargs; pass threshold only when given so each backend keeps its
+    # own default otherwise.
+    common = dict(providers=providers, intra_threads=intra_threads,
+                  inter_threads=inter_threads, neg_threshold=neg_threshold,
+                  **backend_kwargs)
+    if threshold is not None:
+        common["threshold"] = threshold
+
+    # 1. explicit local .onnx file
+    if is_onnx_path(name) and not is_url(name):
+        import os
+
+        if not os.path.isfile(name):
+            raise FileNotFoundError(f"no such ONNX file: {name}")
+        sig = sig or sidecar_signature(name)
+        if sig is None:
+            raise ValueError(
+                f"loading a raw .onnx ({name}) requires a `signature` "
+                "or a <model>.signature.json sidecar"
+            )
+        from .onnx_backend import OnnxVAD
+
+        return OnnxVAD(name, sig, **common)
+
+    # 2. URL
+    if is_url(name):
+        path = download_url(name, cache_dir)
+        sig = sig or sidecar_signature(path)
+        if sig is None:
+            raise ValueError("loading a URL model requires a `signature`")
+        from .onnx_backend import OnnxVAD
+
+        return OnnxVAD(path, sig, **common)
+
+    # 3. registry name
+    spec: Optional[ModelSpec] = get_spec(name)
+    if spec is None:
+        raise KeyError(
+            f"unknown model {name!r}; known: {list_models()} "
+            "(or pass a .onnx path / URL with a signature)"
+        )
+    path = resolve_spec_file(spec, revision, cache_dir)
+    sig = sig or spec.signature
+    backend_cls = get_backend(spec.backend)
+    return backend_cls(path, sig, **common)

cascadevad_onnx-0.1.0/cascadevad/audio.py

@@ -0,0 +1,107 @@
+"""Audio normalization, resampling and WAV reading helpers (numpy-only core).
+
+Everything in :mod:`cascadevad` works internally with mono ``float32`` PCM in the range
+``[-1, 1]``. These helpers convert the various shapes users pass in (raw ``int16``
+bytes, numpy int/float arrays, stereo) into that canonical form and resample between
+sample rates.
+"""
+from __future__ import annotations
+
+import wave
+from typing import Tuple, Union
+
+import numpy as np
+
+AudioLike = Union[bytes, bytearray, memoryview, np.ndarray]
+
+
+def to_float32_mono(audio: AudioLike) -> 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`` / ``float32`` / ``float64``. Multi-channel arrays
+    (shape ``(n, channels)``) are downmixed by averaging channels.
+    """
+    if isinstance(audio, (bytes, bytearray, memoryview)):
+        arr = np.frombuffer(bytes(audio), dtype="<i2").astype(np.float32) / 32768.0
+        return arr
+
+    if not isinstance(audio, np.ndarray):
+        raise TypeError(
+            f"audio must be bytes or np.ndarray, got {type(audio).__name__}"
+        )
+
+    arr = audio
+    # downmix to mono
+    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:  # unsigned 8-bit PCM, midpoint 128
+        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 ``[resample]``
+    extra), otherwise falls back to linear interpolation via :func:`numpy.interp`,
+    which is adequate for voice activity detection framing.
+    """
+    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
+
+        from math import gcd
+
+        g = 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:
+        # linear interpolation fallback (no extra deps)
+        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 a PCM WAV file into mono float32 audio. Returns ``(audio, sample_rate)``.
+
+    Uses the standard-library :mod:`wave` module so no third-party audio dependency
+    is required for examples and tests.
+    """
+    with wave.open(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

cascadevad_onnx-0.1.0/cascadevad/backends/__init__.py

@@ -0,0 +1,8 @@
+"""Optional backend subclasses for models that need glue beyond a plain signature."""
+from .fsmn import FsmnVAD
+from .marblenet import MarbleVAD
+from .pyannote import PyannoteVAD
+from .speechbrain import SbVAD
+from .ten import TenVAD
+
+__all__ = ["TenVAD", "FsmnVAD", "MarbleVAD", "SbVAD", "PyannoteVAD"]