Metadata-Version: 2.4
Name: akiki
Version: 0.0.2
Summary: Local streaming voice activity detection with Akiki VAD
Author: Akiki AI
License-Expression: Apache-2.0
Project-URL: Homepage, https://huggingface.co/Akiki-AI
Keywords: vad,audio,speech,voice-activity-detection
Classifier: Development Status :: 3 - Alpha
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Multimedia :: Sound/Audio :: Analysis
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.24
Requires-Dist: onnxruntime>=1.17
Requires-Dist: soundfile>=0.12
Provides-Extra: pytorch
Requires-Dist: torch>=2.1; extra == "pytorch"
Dynamic: license-file

# Akiki

Run streaming voice activity detection locally with a small bundled Akiki VAD
model. The default engine is the Rust `akiki-vad-engine` from
`akiki-inference`. If no compatible local Rust library is available, it tries
ONNX Runtime, then PyTorch. No model download or network connection is needed.
ONNX Runtime is installed as the portable fallback; PyTorch is optional.

```bash
pip install akiki
akiki --version
akiki recording.wav
```

Audio must be mono at 16,000 Hz. The CLI prints one JSON object per complete
16 ms frame: its start, end, speech probability and threshold decision.

```python
import soundfile as sf
from akiki import VAD

audio, sample_rate = sf.read("recording.wav", dtype="float32")
vad = VAD()
for frame in vad.push(audio, sample_rate=sample_rate):
    print(frame)
vad.reset()  # Start a new recording.
print(vad.engine)  # The engine actually selected: rust, onnx or pytorch.
vad.close()  # Release engine resources; VAD also supports `with`.
```

`push()` accepts arbitrary buffer sizes and retains incomplete frames between
calls. A trailing incomplete frame is left pending; it is not padded or scored.
Use `VAD(threshold=0.6)` or `akiki recording.wav --threshold 0.6` to change the
threshold. Probabilities are always returned.

Choose an engine explicitly with `VAD(engine="rust")`, `VAD(engine="onnx")` or
`VAD(engine="pytorch")`, or use `akiki recording.wav --engine onnx`.
An explicit choice fails with an explanation if unavailable. Install
`akiki[pytorch]` to enable the PyTorch alternative. With the default
`engine="auto"`, `vad.engine_errors` explains any skipped engines. Selection
happens once when a detector is created; a stream keeps its selected engine.
All engines use the same selected release weights and the same streaming API.

Rust uses a shared library through its existing C ABI. Point to an existing
host-compatible library using `VAD(library_path="/local/libakiki_vad_engine.so")`,
`--library-path`, or `AKIKI_VAD_LIBRARY`. Otherwise, discovery checks the library
bundled in the wheel, the local build below, `CARGO_TARGET_DIR`, and release/debug
builds under `~/projects/Akiki/akiki-inference` and
`/projects/Akiki/akiki-inference`. Set `AKIKI_INFERENCE_DIR` for another checkout.
The library names are `libakiki_vad_engine.so` on Linux,
`libakiki_vad_engine.dylib` on macOS, and `akiki_vad_engine.dll` on Windows.
The loader checks the required ABI and model dimensions. Libraries the OS cannot
load, older libraries without the required API, or libraries that cannot load
the model cause automatic selection to continue to the next engine.

To build for this host from the existing local checkout and cached Cargo
dependencies:

```bash
python tools/build_native.py --inference-dir /home/arthurdent/projects/Akiki/akiki-inference
```

This runs Cargo offline and writes only to `.cache/native-target` in this
project. Runtime selection never invokes a compiler or fetches dependencies.

The existing `model_path` argument accepts an ONNX path or a portable `.pt`
checkpoint path with the same `.json` sidecar. Alternate formats are looked up
beside it: `<stem>.onnx`, `<stem>.pt` and `<stem>-native/`. A custom PyTorch
sidecar must include `pytorch_sha256`. A native directory contains `config.json`,
`model.safetensors` and an `export.json` with `config_sha256` and
`model_safetensors_sha256`; its configuration must identify the same model.
Corrupt model files raise an error.

Version 0.0.2 bundles the selected **Akiki VAD release model: seed 1730**, with
210,561 parameters and a 16 ms output hop. It was trained from scratch using
Silero 6.2.3-labelled data and teacher-only validation. Training ran all 48 windows
with cosine LR decay and a low-rate settling phase. No AMI/ICSI or online acoustic
augmentation was used. The model card, frozen recipe and release identity are
included under `akiki/models/`. `VAD().model_id` identifies the loaded release.

Recorded AP is 98.0187% on TEN and 99.3045% on VoxConverse. These repeatedly
inspected benchmarks informed the seed selection and are development comparisons.

Code and bundled Akiki weights are provided under Apache-2.0. Source audio and
the independent teacher retain their original licences; neither is distributed
in this package.

Ship one wheel per OS/architecture, each containing only its matching shared
library. Because Python calls a C ABI through `ctypes`, these wheels can use
`py3-none-<platform>` tags across supported Python versions. Keep a
`py3-none-any` wheel without a native library for the portable fallback. Pip
selects a compatible platform wheel when one is available. See the
[Python packaging platform tag specification](https://packaging.python.org/en/latest/specifications/platform-compatibility-tags/).

Build the portable wheel and source archive normally:

```bash
uv build
```

Build a wheel containing an existing library with:

```bash
AKIKI_NATIVE_LIBRARY="$PWD/.cache/native-target/release/libakiki_vad_engine.so" uv build --wheel
```

The build hook marks that wheel as platform-specific and puts the library in
`akiki/native/`. Repeat on each supported OS/architecture. Use baseline CPU
builds, with the engine's runtime SIMD dispatch. For public Linux wheels, build
and validate in an appropriate manylinux or musllinux environment and repair
with auditwheel; a local `linux_x86_64` build alone does not establish that
portability. macOS and Windows libraries likewise need builds and validation on
their target platforms. The source archive never bundles a host library.

`./publish.sh` validates and publishes the portable wheel/source pair after
local authentication. Platform wheels can be validated and uploaded separately
with `twine check <wheel>` and `twine upload <wheel>`. No publishing is performed
by the build helper.
