Metadata-Version: 2.4
Name: voxrt-kws
Version: 0.1.0
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
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 :: Rust
Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
License-File: LICENSE
License-File: LICENSE-BINARY
Summary: On-device 14-way streaming keyword spotter for Linux x86_64 + aarch64 — servers, containers, Pi 3/4/5, Jetson, Graviton
Keywords: kws,keyword-spotting,wake-word,hotword,voice-command,streaming,voice,voice-assistant,raspberry-pi,jetson,graviton,edge,on-device,embedded,server,cloud,self-hosted,voxrt
Author-email: VoxRT authors <help@voxrt.com>
License-Expression: Apache-2.0
Requires-Python: >=3.9
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Documentation, https://github.com/VoxRT/voxrt-kws-linux#readme
Project-URL: Homepage, https://voxrt.com
Project-URL: Issues, https://github.com/VoxRT/voxrt-kws-linux/issues
Project-URL: Repository, https://github.com/VoxRT/voxrt-kws-linux

# 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

```sh
pip install voxrt-kws
```

Or pin a specific version's wheel from a [GitHub Release](https://github.com/VoxRT/voxrt-kws-linux/releases/tag/v0.1.0)
for offline installs.

## Quickstart

```python
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):

```python
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`:

```python
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):

```python
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/`](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/`](examples/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/`](examples/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](LICENSE).
- Compiled `.so` bundled inside the wheel: proprietary, see [LICENSE-BINARY](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>

