Metadata-Version: 2.4
Name: voxrt-wake-word
Version: 0.1.5
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 wake-word detection for Linux aarch64 — Raspberry Pi 3/4/5, Zero 2, Jetson, AWS Graviton
Keywords: wake-word,keyword-spotting,kws,voice,speech,voice-assistant,raspberry-pi,jetson,edge,on-device,embedded,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-wake-word-linux#readme
Project-URL: Homepage, https://voxrt.com
Project-URL: Issues, https://github.com/VoxRT/voxrt-wake-word-linux/issues
Project-URL: Repository, https://github.com/VoxRT/voxrt-wake-word-linux

# voxrt-wake-word

**On-device wake-phrase detection for Linux aarch64.** Custom Rust inference runtime, ~48K-parameter depthwise-separable convnet, 16 kHz mono PCM in, threshold-crossing events out. Detects the phrase **"Hey Assistant"**.

Runs on Raspberry Pi 3 / 4 / 5 / Zero 2, NVIDIA Jetson, AWS Graviton, and every other aarch64 Linux SBC on a **glibc 2.17+** baseline. Measured **RTF 0.053** on a Raspberry Pi Zero 2 W — 5.3 % of one A53 core, sustained.

Companion to [`voxrt-wake-word-android`](https://github.com/VoxRT/voxrt-wake-word-android) (JitPack) and [`voxrt-wake-word-ios`](https://github.com/VoxRT/voxrt-wake-word-ios) (SPM). Same runtime, same model, same `Detection` schema.

## Install

```sh
pip install voxrt-wake-word
```

One `abi3` wheel covers Python 3.9 / 3.10 / 3.11 / 3.12 / 3.13.

Get the wake-phrase model:

```sh
curl -LO https://github.com/VoxRT/voxrt-wake-word-models/releases/download/v0.1.0/voxrt_wake_word.vxrt
```

## Quick start

```python
from voxrt_wake_word import WakeWordEngine

engine = WakeWordEngine.from_path("voxrt_wake_word.vxrt")
engine.threshold = 0.9
engine.cooldown_frames = 100

for chunk in microphone_iter():           # int16 mono @ 16 kHz, any size
    for d in engine.push_pcm_i16(chunk):
        print(f"wake! t={d.timestamp_sec:.3f}s score={d.score:.4f}")
```

## API

```python
class WakeWordEngine:
    @staticmethod
    def from_path(path: str)  -> WakeWordEngine:  ...
    @staticmethod
    def from_bytes(data: bytes) -> WakeWordEngine: ...

    threshold:       float   # default 0.9, sigmoid-space [0, 1]
    cooldown_frames: int     # default 100 (= 1.0 s at 10 ms hop)

    def push_pcm_i16(self, pcm: list[int])   -> list[Detection]: ...
    def push_pcm_f32(self, pcm: list[float]) -> list[Detection]: ...
    def current_score(self) -> float
    def reset(self) -> None
```

`Detection.frame_index: int`, `Detection.timestamp_sec: float`, `Detection.score: float` — same shape as `WakeWordDetection` on Android (Kotlin) and iOS (Swift).

## Model quality

Test split: 5,240 positive utterances + 6,416 hard-negatives. **ROC AUC 0.9966**, at the default `threshold = 0.9`: precision **0.993**, recall **0.982**, FPR **0.5 %**. Full breakdown at [thresholds 0.5 / 0.85 / 0.9 / 0.95](https://github.com/VoxRT/voxrt-wake-word-linux#model-quality).

## Docs + examples

Full API docs, live-microphone streaming example (via `sounddevice`), and the equivalent wrappers for Node.js / Go / C / Rust are in the main repository:

<https://github.com/VoxRT/voxrt-wake-word-linux>

## License

- Python wrapper source: [Apache-2.0](https://github.com/VoxRT/voxrt-wake-word-linux/blob/main/LICENSE).
- Compiled binary (`voxrt_wake_word.abi3.so`) + model weights (`voxrt_wake_word.vxrt`): proprietary — see `LICENSE-BINARY` inside the wheel or [in the repo](https://github.com/VoxRT/voxrt-wake-word-linux/blob/main/LICENSE-BINARY).

Commercial licensing for custom wake phrases (your brand name, additional languages, multi-phrase): **help@voxrt.com** · [voxrt.com](https://voxrt.com).

