voxrt-kws — Python

Version: v0.1.0 · Wheel names: voxrt_kws-0.1.0-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl, voxrt_kws-0.1.0-cp39-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl.

Single abi3 wheel per arch covers Python 3.9 → 3.13 via the pyo3 stable-ABI bridge. pip picks the right wheel for your interpreter's platform automatically.

Install

pip install voxrt-kws

Or pin a specific version's wheel from a GitHub Release for offline installs.

Quickstart

from voxrt_kws import KwsEngine

engine = KwsEngine.from_path("voxrt_kws.vxrt")
engine.threshold = 0.9        # sigmoid-space, shared across all classes

for chunk in mic_iter():                 # list[int16], bytes, or numpy int16 array
    for det in engine.push_pcm_i16(chunk):
        print(f"[{det.class_name}] t={det.timestamp_sec:.3f}s "
              f"score={det.score:.4f}")

Discover the model's class list at runtime (no hard-coding — the .vxrt carries config.classes in its JSON manifest):

print(engine.class_names)     # ['yes', 'no', 'cancel', 'play', ...]
print(engine.sample_rate)     # 16000

Tuning

Every firing knob is a mutable Python attribute — reconfigure between chunks safely, or set at construction time via kwargs to from_path / from_bytes:

engine = KwsEngine.from_path(
    "voxrt_kws.vxrt",
    threshold=0.85,
    consecutive_frames_required=5,
    cooldown_frames=50,
)

# …later, at runtime …
engine.threshold = 0.9
engine.reset()                # zero state, timestamps restart at 0

Module-level defaults (mirror KwsSessionConfig::default() in the Rust core):

import voxrt_kws
voxrt_kws.DEFAULT_THRESHOLD                       # 0.9
voxrt_kws.DEFAULT_CONSECUTIVE_FRAMES_REQUIRED     # 3
voxrt_kws.DEFAULT_COOLDOWN_FRAMES                 # 25

Examples

Three shipped end-to-end examples live under examples/:

• quickstart/ — pure stdlib, walks a 16 kHz mono 16-bit WAV in 32 ms chunks, prints detections + wall-clock RTF. No numpy / sounddevice / soundfile — works on a fresh Python install anywhere.
• alsa-mic-quickstart/ — live microphone via sounddevice (portaudio backend). Same event loop as the C ALSA example, in Python. Aimed at Pi / Jetson / kiosk deployments.
• ws-detect-server/ — WebSocket detection server via the websockets package. Same wire protocol as the C ws-detect-server — one connection = one KwsEngine; server sends a hello JSON with the class list, then a detect JSON per firing. Ready for a browser / mobile mic frontend.

What the SDK gives you

KwsEngine is a synchronous, stateful function. Each push_pcm_* call blocks the calling thread for the duration of the inference work (∼10 ms per 32 ms chunk on Pi Zero 2 W, ∼0.33 ms on x86_64 AVX2). No GIL release in the current wheel — release the GIL manually with threading if you need parallelism across engines.

Under the hood: mmap .vxrt → AES-GCM decrypt → JSON manifest parse → streaming Conformer-Medium (d=96, 4 blocks, ~636 K params, ~1.3 MB fp16 weights). Runtime dispatches every hot op through NEON (aarch64) or AVX2+FMA (x86_64) with a scalar fallback for pre-Haswell x86_64.

License

• Wrapper sources (this crate, README, examples): Apache-2.0.
• Compiled .so bundled inside the wheel: proprietary, see LICENSE-BINARY.
• Keyword model weights (voxrt_kws.vxrt): proprietary in-house, same terms as LICENSE-BINARY.

Commercial licensing for custom keyword vocabularies, additional languages, or bulk-device deployments: help@voxrt.com.

Links

• Repo (docs, examples, issues): https://github.com/VoxRT/voxrt-kws-linux
• Model releases: https://github.com/VoxRT/voxrt-kws-models
• Browser SDK: https://github.com/VoxRT/voxrt-kws-browser
• Brand: https://voxrt.com