Domain-neutral run segmenter — frame probabilities to contiguous runs — with a backend-agnostic voice-activity-detection (VAD) shell over it.
Introduction
zuoer turns any sequence of frame probabilities into contiguous runs. The
segmenter at its centre is domain-neutral; voice activity detection is the
first and best-validated shell over it — the model-free half of a VAD
pipeline, carrying the Silero-derived segmentation semantics — and sound-event
detection is the second. It provides:
- the neutral run segmenter —
RunSegmenter, the hysteresis state machine that turns any frame-probability sequence into contiguousRuns, configured byRunOptions. It knows nothing about speech: the same machine segments sound-event probabilities, one instance per class; - the
VadBackendseam — the push-based contract (frame_hop,sample_rate,push,finish,reset, and an associatedError) that feeds PCM to a backend and emits speech probabilities through asink, one per completed model frame; - the VAD shell —
SpeechSegment/SpeechSegmenter/SpeechOptions, plain aliases for the neutral types, plus the one-shotdetect_speech_withhelper.
Every emitted Run carries the mean and peak of the frame probabilities
over its raw model-frame span — padding excluded, bridged frames included,
restarted at a force-split. That is the single source for VAD segment
confidence and sound-event confidence alike. Both are always finite and inside
[0, 1]: push_probability canonicalizes each frame first — NaN to 0.0
(inactive), everything else clamped — and the same canonical value drives the
hysteresis comparisons and the aggregates, so a malformed frame can never
reach a consumer as a NaN confidence.
Canonicalization changes no segmentation. Thresholds are clamped into
[RunOptions::MIN_THRESHOLD, 1] (0.01 at the bottom), so a frame
canonicalized to 0.0 satisfies no threshold and a frame canonicalized to
1.0 satisfies every threshold it already satisfied — exactly as the raw
value compared. The floor also keeps the hysteresis window from inverting:
end_threshold() <= start_threshold() for every configuration the setters
and the serde path can produce.
Shell correspondence
The Speech* surface is plain type aliases plus forwarding accessors — no
wrapper, no conversion, no behavioural difference:
| speech name | neutral name |
|---|---|
SpeechSegment |
Run |
SpeechSegmenter / SpeechDetector |
RunSegmenter |
SpeechOptions |
RunOptions |
min_speech_duration |
min_run_duration |
min_silence_duration |
min_gap_duration |
min_silence_at_max_speech |
min_gap_at_max_run |
max_speech_duration |
max_run_duration |
speech_pad |
pad |
The *_samples getters and the with_* / set_* builder pairs follow the
same mapping. The segmenter's own methods (push_probability, pop_pending,
finish, reset, set_sample_rate, set_frame_hop) and Run's accessors
are already neutral and are spelled the same in both surfaces.
It owns no model, no inference runtime, and no audio I/O. A model crate
implements VadBackend over its own inference — an ONNX Silero backend, a
CoreML backend, or any other — and drives the segmenter with this crate's
post-processing. The segmentation rules are the Silero-VAD-derived hysteresis
semantics; a backend that declares a different frame geometry (via
VadBackend::frame_hop) reuses them unchanged.
Usage
Implement VadBackend over your model, then run it one-shot or streaming:
use ;
let mut backend = MyBackend ;
let audio = vec!;
let segments = detect_speech_with?;
# Ok::
For streaming, feed frame probabilities to SpeechSegmenter::push_probabilities
and drain closed segments with pop_pending (and finish at end-of-stream).
The neutral core, without audio
Nothing above the frame probabilities is required. Drive RunSegmenter with
RunOptions directly and it segments any per-frame score — one instance per
sound-event class, no VadBackend and no PCM in sight. Every emitted Run
carries the mean and peak of the frames it was built from, which is where a
consumer reads its confidence:
use Duration;
use ;
// One segmenter per class. The input is whatever per-frame probabilities
// the classifier produced; the timeline unit is the classifier's hop.
let options = default
.with_sample_rate
.with_start_threshold // the end threshold derives 0.15 below
.with_min_run_duration
.with_min_gap_duration
.with_pad;
let mut dog_bark = new;
dog_bark.set_frame_hop; // 20 ms per frame at 16 kHz
dog_bark.push_probabilities;
// The run opened on the 0.9 frame and closed once the trailing gap
// reached `min_gap_duration`.
let run = dog_bark.pop_pending.expect;
assert_eq!; // 0.02 s
assert_eq!; // 0.08 s
// The aggregates span the run's raw frames only: the three above-threshold
// frames, not the sub-threshold gap that closed it and not any padding.
assert_eq!;
assert!;
// Nothing was left open at end of stream.
assert!;
Feature flags
serde— deriveSerialize/DeserializeforRunOptionsandSampleRate(Durationfields viahumantime-serde). Fields serialize under their neutral names and also accept the 0.1 speech-flavoured names as deserialization aliases. Both types carrydeny_unknown_fields, so a misspelled key in a JSON/YAML/TOML profile is refused rather than silently ignored.
Consumers
silero— the ONNX Silero VAD backend.coremlit— the CoreML VAD backend (not yet published to crates.io).
License
zuoer is under the terms of both the MIT license and the
Apache License (Version 2.0).
See LICENSE-APACHE, LICENSE-MIT for details.
Copyright (c) 2026 FinDIT studio authors.