The canonical voice loop now lives in zeroclaw-channel-voice
(`~/projects/zeroclaw/crates/zeroclaw-channel-voice`, binary
`voice_server`). It routes the LLM path through zeroclaw's agent
runtime — multi-turn history, tools, memory, provider routing —
instead of the OpenAI-compatible direct path here.
Same WS wire protocol so `examples/converse_client.rs` drives both;
no client-side migration needed.
This binary is intentionally kept buildable for:
1. Reproducing perf_history.md Phase 8.10 benches.
2. Standalone (no-agent) use when zeroclaw isn't desired.
Module doc + main() startup banner updated to point at the new home.
Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
8-gen bench (4 emotions × 2 corpora) at seed=42 against firdhokk
Whisper-LV3:
target RAVDESS CREMA-D
happy happy (0.999) ✓ happy (0.999) ✓
angry neutral (0.92) sad (0.99)
fearful happy (0.998) fearful (0.984) ✓
sad angry (0.99) fearful (0.99)
CREMA-D 2/4 vs RAVDESS 1/4. Larger / more naturalistic corpus
produces more class-pure fearful direction. Neither corpus solves
angry or sad — recipe shifts into 'vague expressivity' rather than
class-specific corners.
Practical: prefer CREMA-D when available; A/B both per emotion if
class precision matters.
Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
Three real bugs found while running a YouTube → train → eval pipeline
end-to-end on real corpora:
1. emotion2vec was producing near-constant logits regardless of input.
Per config.yaml `normalize: true` — data2vec2/emotion2vec expects
per-utterance zero-mean unit-variance normalization on the raw
waveform before the local_encoder. Added inside the EmotionDetector
trait impl so all callers get it.
Verified empirically: 4 different audio inputs (Carlini talk,
audience question, McConaughey speech) now produce different argmax
classes. Before fix: all 4 produced identical logits.
2. The 9→5 emotion fold was collapsing every real-world clip to
[excited]. happy / surprised / other all mapped to Excited covered
~95% of natural speech. Replaced with a direct 9-class identity
mapping; EmotionLabel gained Disgusted, Fearful, Happy, Surprised,
Unk variants. Now: 132 [surprised] + 12 [excited] across the
Carlini corpus instead of 144 [excited].
3. lora_train_emotional --peak-lr / --epochs flags. The canned 3-stage
recipe over-fits on small (~100 clip) corpora at extended rank 8;
users need to tune. (The recipe stays as defaults; flags are pure
overrides.)
Plus diagnostic: examples/emotion2vec_probe — feed real audio files
into emotion2vec and dump per-class logits. Used to find bug #1.
Lib suite still 131/131 (the test that locked the 9→5 fold updated
to lock the new identity mapping).
Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
Port complete. The Phase 13.3 prosody-rule placeholder is now
retire-able by setting one CLI flag — the real candle-ported
emotion2vec_plus_base classifier slots in behind the same
EmotionDetector trait the placeholder used.
impl EmotionDetector for Emotion2Vec — builds (1, 1, T) tensor on
stored device, runs forward, argmaxes the 9 logits, maps to the
5-bucket label via Classifier::tag_for_class. Empty input
short-circuits to Neutral.
Emotion2Vec struct gained a `device` field so the trait impl can
build tensors without an out-of-band handle. new() / load_from_pickle()
threaded through; existing tests + smoke binary updated.
audio_to_manifest --use-emotion2vec — pairs with --auto-emotion-tag
to swap ProsodyDetector for Emotion2Vec, boxed as
Box<dyn EmotionDetector> so the call site is unchanged.
converse_server --use-emotion2vec — same pattern; built once at boot
and stored in Shared as Box<dyn EmotionDetector + Send + Sync>.
~150 ms/turn forward cost vs <1 ms for prosody, but actually runs
SOTA SER. Removed redundant reactive_emotion: bool field — the
Option<Box<dyn>> already encodes the same state.
Verified end-to-end on Metal:
- audio_to_manifest --use-emotion2vec on 2-speaker concat → both
tagged [excited] (prosody had said [neutral] on same input)
- converse_server --quantized-gguf … --lora … --reactive-emotion
--use-emotion2vec boots, 1 bench turn 0 errors, /metrics shows
reactive_emotion_total{label="excited"} 1 — same tag
audio_to_manifest produced. Cross-consumer consistency.
Phase 13.8 complete (slices 1+2+3+4 shipped). The emotional-voice
stack now has a real, trained, candle-ported SER classifier with
no Python sidecar, no ort, no whisper.cpp.
Lib suite 120/120.
Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
Composes Phase 13.4 reactive emotion with LLM message construction so
the assistant's RESPONSE TEXT adapts to detected user tone, not just
TTS prosody.
--emotion-aware-llm flag (requires --reactive-emotion). When a non-
Neutral label is detected, the LLM-facing copy of the user message is
augmented with `\n\n[user audio tone: {label} — adjust your response
in tone and content to match]`. Per-turn only — the augmentation lives
in history_clone, never in the persistent history, so subsequent turns
aren't biased by stale signals.
Verified end-to-end: server with Q8 + LoRA + reactive-emotion +
emotion-aware-llm booted, bench turn completed 0 errors. Mock LLM
echoed back the augmented text (taking ~44s of TTS), confirming the
annotation reached the LLM. Lib suite 110/110.
The full reactive voice loop now adapts both prosody (TTS emotion_hint)
AND content (LLM annotated user message) to detected user tone. Both
paths flow through the same EmotionDetector trait, so when emotion2vec_
plus_base lands the placeholder swaps cleanly.
Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
The "cry-back when user sounds sad" feature from personal_voice_training_
guide.md §5. Composes everything from today's session: Phase 13.3
prosody-rule SER feeds Phase 12.2 emotion_hint plumbing, run per turn
inside the production voice loop.
--reactive-emotion flag. Per turn, between STT finalization and the
LLM/TTS opts construction:
1. Trim the 2 s silence pad off user_audio_24k
2. audio_io::resample 24 → 16 kHz (rubato, already in deps)
3. ProsodyDetector::default().classify() over the speech buffer
4. If non-Neutral → use the tag as the turn's emotion_hint
5. Otherwise fall back to the static --emotion-hint
EmotionDetector trait means a future emotion2vec_plus_base candle port
slots in here without changing this code path.
End-to-end verified: Q8 + LoRA + reactive-emotion server, single bench
turn through WS, 0 errors, server logged
`reactive-emotion: detected [calm]` and used it as the response's
emotion_hint. Lib suite 110/110.
Architecture now demonstrates the full Maya-class reactive voice loop:
user audio → STT → ProsodyDetector → LLM → CSM TTS with matching tag
→ assistant responds in matching emotional register. All in-crate,
sub-2s TTFA combo preserved.
Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
Remove the `--lora and --quantized-gguf cannot combine` bail. That
guard was wallpaper from before Phase 12.1 added LoRA hooks to
csm_quantized.rs. The shared apply_lora_adapter helper routes through
the model.rs wrapper which dispatches to either backbone, so FP and Q8
paths are equivalent from the call site's perspective.
Verified end-to-end:
- generate --quantized-gguf … --lora … runs with extended LoRA on the
quantized backbone, auto-detects metadata via Phase 12.5, produces
audio.
- converse_server --quantized-gguf … --lora … --stream-tts boots,
warms up, listens; converse_server_bench --turns 1 completes
cleanly (0 errors, tts_per_utterance=2610ms, e2e_first_audio=3657ms).
CLI flag docstring updated to advertise the now-combined behaviour.
This is the production-deployable combo: sub-2s TTFA Q8 + personalized
voice from Phase 12.x training.
Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
Trained adapters now embed (rank, alpha, target_modules, crate_version)
as JSON in safetensors __metadata__["rtx_csm_lora"]. apply_lora_adapter
reads it at load time so users no longer have to remember matching
--lora-rank/--lora-alpha/--extended-lora flags from training.
LoraAdapterMetadata::is_extended() heuristic: target_modules contains
any MLP path or output_proj or k_proj. Handles both the canonical
extended() preset and future custom configs that overlap it.
apply_lora_adapter rank/alpha/extended params became Option<_>
(None = use file metadata, Some = override). Both callers updated.
save_lora_adapter_with_metadata is the new path used by both trainers;
the plain save_lora_adapter still exists for the metadata-less case
(per-stage curriculum snapshots).
safetensors dep bumped 0.4 → 0.7 to match candle 0.9's transitive pin
so candle's Tensor: View impl is in scope for serialize_to_file
(candle's own save wrapper hardcodes the metadata arg to None).
Backward compat: pre-12.5 adapters load fine when explicit CLI flags
are passed; auto-detect path is skipped silently.
Verified end-to-end: trained adapter saved with metadata,
`generate --lora <path>` (no other flags) auto-detected
rank=8 alpha=16 extended=true and applied. Older metadata-less adapter
still loaded with explicit flags. 3 new unit tests; lib suite 99/99.
Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
Closes the train→generate loop the lora_train comment has promised
since Phase 3 ("forthcoming --lora flag on generate").
apply_lora_adapter(generator, path, rank, alpha, extended, device)
shared helper in src/training.rs wraps add_lora_to_backbone +
load_lora_adapter + refresh_lora. Both examples/generate and
examples/converse_server now call it instead of inlining their own
versions, and both now take --extended-lora to opt into Phase 12.1
coverage. Classic q+v adapters still load without the flag.
lora_train.rs now prints the exact `--lora <path> --lora-rank N
--lora-alpha N [--extended-lora]` command-line you need to apply the
trained adapter at inference, replacing the (forthcoming) message.
End-to-end verified: a Phase 12.3 curriculum-trained adapter loaded
into generate with identical seed/text produces different audio
(92KB vs 61KB, EOT @ frame 24 vs 16) — confirming the adapter takes
effect through to the sampled output. The 3-utterance smoke adapter
hasn't learned anything meaningful but the wiring is sound.
Phase 12 emotional voice stack now complete end-to-end:
12.1 capacity → 12.2 control tokens → 12.3 curriculum → 12.4 inference.
Lib suite 96/96.
Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
GenerateOptions gains emotion_hint: Option<String>. After text
normalization, the hint (if Some) is prepended as `<tag> <text>` so the
Llama BPE tokenizer encodes it as ordinary tokens. Plumbed through
generate, generate_streaming, and generate_with_profile (via delegation),
plus a `--emotion-hint` flag on examples/generate and a Shared field
+ CLI flag on examples/converse_server (per-turn ConverseOptions).
GenerateOptions lost Copy because Option<String> isn't Copy; updated
the four callers that depended on it (bench, longform, converse synth
+ stream) to .clone() the opts at the call site. Cheap — the struct
is small and clones are per-turn, not per-frame.
On the un-adapted base this is a no-op cosmetic prefix. The point is to
unlock Phase 12.1-fine-tuned adapters: train with `[whisper] X` paired
with whispered audio, and the adapter learns the tag→prosody mapping at
inference time.
Verified end-to-end: --emotion-hint "[whisper]" --max-audio-ms 3000
produced a valid 24kHz mono WAV through tokenizer → backbone → Mimi
with no panics. Lib suite 96/96 (added 4 apply_emotion_hint unit tests).
Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
Adds `--watermark-silentcipher` flag to converse_server. Sesame's actual
production watermarker is now a drop-in option in the conversation
pipeline alongside the existing AudioSeal flags.
Usage:
--watermark-silentcipher hf # download from sony/silentcipher
--watermark-silentcipher /path/to/dir # local checkpoint dir
--watermark-message 0xCAFE # 16-bit message (also drives AudioSeal)
Mutex with `--watermark-generator` / `--watermark-detector` (AudioSeal):
the Generator only carries one watermarker. Both are wrapped with
`ResampledWatermarker(24 kHz <-> 16 kHz)` for the CSM TTS path.
End-to-end production test (Q8 + Kyutai + mock LLM + SilentCipher 0xCAFE):
client TTFA: 7888 ms
total wall: 21860 ms
assistant audio: 12.16 s @ 24 kHz, written to /tmp/converse_silent_response.wav
re-detect: confidence 0.7614, payload 0x0000CAFE (PASS)
The 0.76 confidence (vs 1.00 in the standalone CLI test) is expected —
the assistant audio went through 24->16->24 resample plus stream-
encode-decode, all of which add noise. Still well above the 0.7
threshold we use for `Option<u16> -> Some/None` mapping in the
Watermarker trait impl.
A/B vs AudioSeal on the same /tmp/asr_test.flac (10.43 s @ 24 kHz):
AudioSeal SilentCipher
Embed timing not in CLI 988 ms (0.10x rt)
Detect timing not in CLI 1493 ms (0.14x rt)
Bit accuracy 16/16 bits 15/15 codes
Confidence 1.0000 1.0000
Message 0xCAFE 0xCAFE (decimal 51966)
Both bit-perfect. AudioSeal carries 16 bits, SilentCipher carries up
to ~24 bits per patch (15 base-3 codes). For our use (16-bit job_id
or message hash), either fits.
Production recommendation: ship SilentCipher for literal Sesame
parity AND the structural advantages (smaller model, identical bit
accuracy, confidence-based threshold). AudioSeal stays available for
callers who want the per-sample presence map (which SilentCipher
doesn't provide).
Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
Quick TTFA win identified by the Phase 9.1 spike's "alternative quick
win" recommendation: tune the streaming Mimi chunk size before
attempting the full VoXtream port. The default `--stream-chunk-frames`
was 4 (320 ms per chunk); dropping to 2 (160 ms) saves ~155 ms on
client TTFA with no measurable downside.
Bench (Q8 + stream + Moonshine + mock LLM, 3 turns each):
chunk_frames=4 llm_to_first_audio 533 ms e2e_first_audio 939 ms
chunk_frames=2 llm_to_first_audio 374 ms e2e_first_audio 784 ms ← new default
chunk_frames=1 llm_to_first_audio 283 ms e2e_first_audio 664 ms
Per-utterance TTS gen comparable across all three (~5.7-5.9 s for the
4-sentence mock LLM reply), so smaller chunks don't add meaningful
decode overhead. The trade is just send-loop overhead + slightly
more network packets.
Production users can drop to 1 for tightest TTFA via
`--stream-chunk-frames 1`. The 2 default is the conservative middle
ground.
This obviates most of the Tier 2.1 (VoXtream look-ahead) urgency: the
first-chunk latency is now ~280-380 ms server-side; the remaining
bottleneck is Moonshine STT (332 ms) and Z.AI TTFT (1300 ms), not
TTS. VoXtream's 102 ms first-packet claim could close the remaining
TTS-side gap (374 -> ~100 ms = -270 ms) but the integration cost is
high relative to the win.
Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
Wires the Phase 8.5-8.9 Moonshine port as a drop-in alternative to
Kyutai STT in the conversation server. New `--moonshine` flag (mutex
with `--whisper` and `--vad`). Pure candle, no external runtime — no
ggml/protobuf conflicts unlike `--whisper`.
Architecture:
- AsrEngine enum extended with Moonshine(MoonshineAsr) variant
- MoonshineAsr bundles { encoder, decoder, tokenizer, cfg, device }
plus a transcribe_24k() that resamples 24->16 kHz, encodes,
greedy-decodes (KV-cached), detokenizes
- Renamed Shared.whisper_mode -> Shared.batch_asr to cover both
Whisper and Moonshine (both batch-only, skip parallel STT)
- Receive loop's match arms now exhaustive over all three variants
- At EOT, transcript construction branches:
Kyutai -> join words from incremental Word/EndWord stream
Moonshine -> transcribe_24k() over accumulated audio
Whisper -> transcribe_24k() (asr feature)
End-to-end verified (mock LLM, Q8 + stream + warmup + Moonshine, real
LibriSpeech 10.43 s):
recv_phase: 0 ms (batch ASR; audio just buffers)
stt_post: 406 ms (Moonshine transcribe at EOT)
llm_to_first_audio: 533 ms
total_turn: 23617 ms
*** Client TTFA: 939 ms *** (sub-second!)
Compared to Kyutai (Phase 8.2 extended warmup baseline):
Kyutai TTFA p50 4915 ms
Moonshine TTFA 939 ms ← -80%
Moonshine produces near-perfect transcript: "He hoped there would be
stew for dinner, turnips and carrots and bruised potatoes, and fat,
mutton pieces to be ladled out in thick, peppered, flour-fat and
sauce." matching the LibriSpeech ground truth.
This is the new production-recommended voice-loop config for
English-only deploys:
converse_server \\
--quantized-gguf <Q8> --stream-tts --moonshine \\
[--vad-gate] # energy VAD still useful for skipping silence
[--llm-extra-body '{"thinking":{"type":"disabled"}}' # for Z.AI]
For multilingual (en+fr) deploys, stick with Kyutai 1B (the default).
Phase 8 is now feature-complete on the optimization tracks the
research surfaced:
- Tier 1 (warmup, energy VAD, ort gate): SHIPPED
- Tier 2.2 (Moonshine candle port): SHIPPED end-to-end (8.4-8.10)
- Tier 2.1 (VoXtream), Tier 3 (Frame-Stacked, VADUSA): deferred,
documented in plan + perf_history.md
Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
Increased the boot warm-up from `max_audio_ms=200` (~3 frames) to
`max_audio_ms=2000` (~25 frames) and switched the prompt to a fuller
sentence so more Metal kernel paths fire during the throwaway gen.
The original 200 ms warm-up only compiled the early fast paths; the
first user turn still paid 4-5 s of additional kernel compilation as
new branches lit up under longer-context generation. The 2 s warm-up
gives the JIT a chance to compile everything.
3-turn bench (mock LLM, Q8 + stream, M-series Metal, 10.43 s
LibriSpeech in):
Metric Original warm-up Extended warm-up Δ
Boot warm-up cost 819 ms 2748 ms +1.9 s
client first_audio_ms p50 4915 ms 529 ms -89%
llm_to_first_audio 4892 ms 627 ms -87%
total_turn 18408 ms 18112 ms wash
Sub-second TTFA on every turn. The extra 2 s at boot is paid back on
the first user turn — every turn after is pure win.
This is the new production-recommended config:
--quantized-gguf <Q8> --stream-tts --vad-gate
(warm-up always on; no flag toggle).
Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
Original plan: gate STT work via Silero V5 VAD using
voice_activity_detector / ort to skip silent chunks. Phase 8.1.2's
ort_conflict_probe initially passed (no Metal regression). But on
first server boot, sentencepiece-sys's protobuf 3.14 collides with
ort's bundled protobuf 3.21 at process startup:
[libprotobuf FATAL ...] This program was compiled against version
3.14.0 of the Protocol Buffer runtime library, which is not
compatible with the installed version (3.21.12) ... in
sentencepiece-sys-0.13.1
Updated the probe binary to also load Kyutai STT (which links
sentencepiece) — now correctly catches the conflict at probe time.
Same risk class as the whisper-rs/ggml issue from Phase 7.6: external
ML runtimes don't always coexist in the same Rust process.
Pivoted to a pure-Rust energy-based VAD: RMS amplitude threshold per
incoming chunk. ~30 LOC, no external runtime, no protobuf risk.
Catches obvious silence (room tone, pauses) — misses quiet speech
(whispering). Acceptable for typical mic-distance voice loops.
Wired into examples/converse_server as `--vad-gate` /
`--vad-gate-threshold 0.01`. The receive loop checks RMS before each
binary chunk's STT call; silence chunks skip step_pcm entirely.
Orthogonal to existing `--vad` (Kyutai semantic-VAD-for-EOT).
Bench (mock LLM, Q8+stream, 10s LibriSpeech in, ~90% speech):
baseline: recv_phase = 4834 ms
--vad-gate: recv_phase = 4509 ms (-7%, matches the ~10% silence
in this audio)
Real-world voice-agent audio is 30-50% silence; expect proportional
savings (~30-50% recv_phase reduction). Larger silence content =
larger VAD win.
Cargo.toml: keeps the optional `vad` feature + voice_activity_detector
dep wired (path remains for a future Silero-via-candle port). The
ort_conflict_probe example continues to require `--features vad` so
the conflict-detection path stays exercised.
Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
Wraps the per-frame Kyutai STT calls in handle_connection's receive
loop with tokio::task::spawn_blocking. The async runtime worker is
freed during the ~80ms/frame compute so other tasks/connections can
run on the same worker pool.
Single-connection latency is unchanged (STT is hardware-bound at ~1×
realtime). The win is multi-tenant concurrency: with N WebSocket
connections, no longer blocks all N on one connection's STT work.
Two call sites updated:
- carry-over feed (turn-start barge-in audio)
- main receive loop (per-binary-chunk step_pcm)
Pattern: clone Arc<Shared>, move into spawn_blocking, use
tokio::sync::Mutex::blocking_lock() inside the closure (legal there).
The blocking_lock requires the Mutex to be reachable via Send + 'static
captures — that's why we clone shared rather than borrow.
Cannot show the multi-tenant win in the existing single-connection
bench harness; bench thermals also confound direct A/B. Functional
correctness verified via running bench (transcripts produced, no
errors).
Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
Wires --whisper flag in converse_server using the existing whisper-rs
asr feature. AsrEngine enum (Kyutai default + Whisper variant gated on
"asr" feature) lets the receive loop branch on backend. Whisper path:
buffer audio during receive, transcribe full buffer at EOT — batch-only,
no VAD, no incremental words.
Adds examples/whisper_profile binary measuring Whisper-tiny in
isolation against the same audio used for stt_profile.
Standalone profile findings (M-series):
Kyutai STT 1B : 80.8 ms / 80 ms audio 1.01x realtime
Whisper-tiny : 209 ms / 10.43 s audio 0.020x (~50x faster)
But the full-stack bench reveals a critical regression: linking
whisper-rs's C++ runtime into the same binary as candle/CSM costs
2-3x across ALL CSM inference (recv_phase, tts_per_utterance,
total_turn) even when --whisper is NOT used. Build flag matters.
Build recv tts/u total
--features metal 4196 3113 18707
--features metal,asr (Kyutai) 10019 7803 43366 <- linkage cost
--features metal,asr +whisper 0 12921 54028 <- worse
Suspected cause: ggml/whisper.cpp's BLAS or Metal context init
conflicts with candle's. Production verdict: build WITHOUT asr
feature; accept Kyutai's 1x realtime STT cost. The standalone
whisper_profile binary still works for batch transcribe measurement.
Real Whisper integration would need a sidecar process pattern (whisper
running as a separate binary, IPC to converse_server). Documented in
the --whisper CLI help. Flag stays as opt-in with explicit warning.
Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
Adds Converse::run_streaming using Generator::generate_streaming. Chunks
are emitted via a per-chunk callback as they're decoded; per-sentence
callback fires once for /metrics + transcript bookkeeping. Skips
post-process and watermark — both require full-sentence context.
Wires --stream-tts and --stream-chunk-frames into examples/converse_server.
Combining --stream-tts with --watermark-* is rejected at boot.
Critical architectural fix: tokio::join!(conv_fut, pump_fut) polls
cooperatively in ONE task, so the sync TTS gen blocks the runtime worker
and prevents pump_fut from draining the chunk channel. Switched to
tokio::spawn(conv_fut) + pump_fut.await on the original task — now the
runtime can schedule pump_fut on a different worker while conv_fut is
mid-synthesize. Without the spawn, chunks pile up and arrive in burst at
sentence boundaries (defeating the streaming purpose).
A/B (warmed FP, mock LLM, 10.43s LibriSpeech in):
Phase Non-stream Stream+spawn Δ
llm_to_first_audio 4892ms 1942ms -2950ms
total_turn 18408ms 19628ms +1220ms (variance)
Client-side TTFA 9345ms 6789ms -2556ms
~3s TTFA reduction is the production win. total_turn is roughly unchanged
(chunk delivery overhead exists but is small). For voice-loop deployments
where time-to-first-audio dominates UX, this is the right default.
Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
Issues one throwaway Generator.generate() call after model load + before
accepting connections. Pays Metal kernel compilation + first-frame KV
cache init up-front so the first real user turn doesn't carry that
overhead.
A/B (mock LLM, FP CSM, M-series Metal, 10.43s LibriSpeech in):
no warm-up sentence[0] tts_gen=5679ms total=24818ms
with warm-up sentence[0] tts_gen=4272ms total=18654ms
Warm-up cost at boot: 1417ms. Direct saving on first-sentence TTS gen:
~1.4s. The warm-up pays for itself on the first turn and is amortized
to zero across the server's lifetime.
Failures during warm-up are logged at warn level and the server boots
anyway — first turn falls back to the original cold-start behavior.
Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
Adds explicit phase boundaries inside the WS connection loop so we can
see where voice-loop wall-time actually goes. Each turn emits one info
log line plus four new gauges on /metrics:
recv_phase_ms turn_start -> EOT received (audio_recv + parallel STT)
stt_post_phase_ms EOT received -> conv_fut start (post-EOT flush)
llm_to_first_audio_ms conv_fut start -> first PCM byte (LLM + 1st sentence TTS)
conv_total_ms conv_fut start -> all sentences TTS'd
total_turn_ms turn_start -> done event
First measured turn (mock LLM, FP CSM, M-series Metal, 10.43s LibriSpeech):
recv=4740ms stt_post=29ms llm_to_first_audio=4126ms
conv_total=12735ms total=17505ms
Two findings worth keeping:
1. stt_post=29ms confirms the Phase 6c.3d parallel-STT optimization is
working — the post-EOT flush is effectively free, all the heavy
lifting happened during receive.
2. Earlier "12s STT" estimate from the bench tool's transcript_ms was
measuring the wrong thing (its clock includes bench-side audio_send
that dumps frames at full speed; the server finishes receive in
~4.7s of which most is parallel STT). The instrumentation now
attributes time correctly.
Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
Adds `extra_body: serde_json::Map<String, Value>` to `GenConfig`. The
OpenAiCompatibleClient serializes the typed ChatRequest to a Value, then
merges extra_body's keys at the top level of the request body before
sending. extra_body is empty by default, so existing callers see no
behavioral change.
Use cases:
- **Z.AI thinking-disabled** for voice-AI: glm-4.5/4.6/4.7 default to
reasoning_content traversal which burns tokens before content emits.
Pass `{"thinking":{"type":"disabled"}}` and reasoning_tokens drops to
0. Verified: curl direct = 2.1s vs 30s+ with thinking.
- **vLLM guided decoding**: `{"guided_json": {...}}`.
- **Anthropic-compat thinking budget** (when proxied through an
OpenAI-compat shim).
Wires `--llm-extra-body '<JSON>'` into examples/converse_server: parsed
once at boot, stored in Shared.llm_extra_body, cloned per-turn into
gen_cfg. Boot rejects malformed JSON or non-object payloads.
Smoke test: examples/llm_extra_body_smoke.rs hits Z.AI directly with
and without extra_body, prints ttf_chunk and total stream time. Latest
run on glm-4.5: WITHOUT extra_body 1283ms, WITH thinking-disabled
1385ms — both fast on this prompt; the field is correctly forwarded
either way (other prompts that trigger reasoning_content show the
30s+ delta).
Note: the first end-to-end test through converse_server still showed
~46s wall (vs 1.4s for the LLM call alone), implying the latency
bottleneck is local STT (~12s on this hardware) + TTS gen, not the
LLM. extra_body code path is verified independently via the smoke
test.
Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
Wires two more capabilities into examples/converse_server.rs:
--lora <path> [--lora-rank N --lora-alpha A] inject voice-clone adapter
--watermark-generator <path> \
--watermark-detector <path> embed AudioSeal on every
[--watermark-message 0xCAFE] assistant utterance
LoRA path: parallels examples/generate.rs — load Generator (FP), build
LoraConfig, add_lora_to_backbone(VarMap), load_lora_adapter, refresh_lora.
Voice clones now work in the conversation pipeline. Combining with
--quantized-gguf is rejected at boot; the LoRA-on-Q8 path works in
generate but the server hasn't been audited so it's gated for now.
Watermark path: parallels examples/generate.rs — load AudioSeal generator
+ detector safetensors via VarBuilder::from_mmaped_safetensors, build
AudioSealWatermarker, wrap in ResampledWatermarker(24k↔16k), install via
generator.set_watermarker(...). converse.rs::synthesize already calls
the watermarker per-utterance, so no plumbing changes needed downstream.
Verified end-to-end:
* boot server with --watermark-generator/-detector --watermark-message 0xCAFE
* single conversation turn (10.43s LibriSpeech in -> 4.24s assistant out)
* detect on response WAV: mean_presence=0.9995, decoded=0xCAFE,
16/16 message bits matching after full STT->LLM->TTS->post->watermark
->24k->WS->wav round-trip.
Also adds audioseal_apply --detect-only flag (skip embed, run detector
against arbitrary WAV) — used to verify the round-trip above. --out is
now optional and only required when not in detect-only mode.
Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
Wires --quantized-gguf into converse_server: loads CSM-1B from a Q8/Q4_K_M
GGUF (output of examples/quantize) instead of the FP safetensors. Mimi
codec stays FP — only the TTS Llama backbone+decoder is quantized.
Q8 bench (3 turns, mock LLM, M-series Metal):
turn_total_ms: mean=20807ms p50=20903ms p95=23253ms
transcript_ms: mean=4750ms p50=5137ms (STT, unchanged — Q8 only affects TTS)
first_audio_ms: mean=3306ms p50=3422ms (Q8 backbone first-frame)
vs FP baseline (~26s mean total): ~20% faster end-to-end with 3x memory
reduction (6.2GB safetensors -> 2GB GGUF, mmap-loadable).
Also adds a 50ms exponential-decay fade-out chunk before the barge_in
event: when the user interrupts, instead of cutting the assistant's
audio mid-sample (audible click on the client side), we ramp the last
50ms of output toward silence with -4t envelope and low-amplitude
pseudo-noise. Drained pending TTS chunks first so the fade is the
last thing the client hears before the barge_in event.
Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
Restructured the converse_server's user-audio receive loop to feed STT
incrementally as PCM frames arrive, instead of accumulating all audio
then transcribing in one block at end-of-turn.
Both VAD and non-VAD paths share the same incremental-ingest logic:
- Reset STT once per turn
- On every binary frame: append to user_audio_24k AND step_pcm with
the new slice
- collect_transcript_events() helper pairs Word/EndWord, detoks via
sentencepiece, accumulates transcript_words
- On EOT: stt.finish() drains the asr_delay buffer, transcript_words
are joined into user_text — essentially instant
- Carry-over barge-in audio gets fed first (preserving the start of
the next user turn's speech)
Empirical numbers (3 turns, 10.43s LibriSpeech, mock LLM, --realtime):
Before (sync STT): transcript_ms p50=5219ms p95=5444ms
After (parallel STT): transcript_ms p50=45ms p95=48ms [-99%]
Total turn time went UP (24.9s vs 17.7s p50) only because the realtime
client now actually takes 10s to send 10s of speech (previously it
dumped instantly — unrealistic for voice).
For real voice traffic the user-perceived latency improvement is:
Before: ~9s of silence after user stops speaking
After: ~4.5s of silence (transcript ready in 45ms + 4.4s LLM+TTS)
Bench harness gains --realtime flag that paces frames at audio
playback rate — required to measure the parallel-STT win since the
default dump-everything-at-once mode can't show overlap.
Phase 6 status: feature-complete and now performance-optimized.
Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
Phase 6c.3c verification: extended converse_client with
--barge-in-after-ms flag that injects a 200 ms audio frame N ms after
the assistant starts speaking, then watches for the
{"event":"barge_in"} server response.
Verified end-to-end on Metal:
Input: 10.43s LibriSpeech FLAC
STT transcript: matched correctly
Mock LLM streamed 4-sentence response with 50ms/token delays
Client injected barge-in 100 ms into TTS streaming
Server log: "barge-in detected (4800 samples carried over)"
Client log: "[server] barge_in event received -- TTS cancelled"
WAV file: 1.60s of TTS captured before cutoff
Mock LLM upgraded to multi-sentence with tokio::time::sleep(50ms)
between chunks — exercises the streaming pipeline long enough for
barge-in tests to fire mid-response.
The full Rust Unmute conversational stack is now feature-verified:
voice-in, voice-out, interruptible, VAD-driven, authed, metrics-
instrumented. Strategic Phase 6 deliverable shipped end-to-end.
Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
Final piece of the Rust Unmute stack. tokio::select! between TTS audio
chunks and incoming WebSocket frames during the speaking phase: a
non-empty binary frame from the user fires barge-in.
Mechanism:
- AtomicBool cancel signal shared between conv_fut and pump_fut
- TTS callback checks cancel and returns Err to abort conv.run early
- pump_fut detects user audio, sets cancel, drains pending chunks,
sends {"event":"barge_in"} to client
- The barge-in audio bytes are decoded and stashed as carry_over
- Next turn starts with the carried-over audio already buffered
(so the user doesn't have to re-speak the start of their interrupt)
- assistant_text is empty when cancelled → don't add to chat history
(the assistant turn was incomplete)
Also handles "EOT" text mid-TTS as user wanting to stop assistant
(cancels but doesn't carry over audio).
PumpResult enum covers Done / BargeIn(samples) / Disconnected.
Phase 6 status — strategic deliverable feature-complete:
6a STT: working
6b LLM client: working
6c.1 text->LLM->TTS: working
6c.2 WebSocket duplex MVP: working
6c.3a streaming TTS chunks: working
6c.3b semantic VAD: working
6c.3c barge-in: shipped (this commit)
6d.{auth,shutdown,metrics,rate-limit}: shipped
87 lib tests pass.
Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
Phase 6d.rate-limit:
Per-connection sliding-window token bucket (60s window) on the
WebSocket. Two limits: --rate-audio-secs-per-min (default 600,
60 of which exhausts the bucket on a 1-minute monologue), and
--rate-turns-per-min (default 60). Excess fires an error event +
closes the connection.
Verified: with --rate-turns-per-min 1, two SEPARATE WS connections
each get a fresh per-connection bucket (by design — defends against
a single misbehaving client; for per-IP, the bucket would need to
live globally on Shared).
Phase 6c.3b: semantic VAD via extra_heads
- Added Stt::load_default_with_vad() which downloads
`kyutai/stt-1b-en_fr-candle` (the VAD-enabled variant: 4 extra
heads × 6-dim categorical, trained for end-of-turn detection).
- config_stt_1b_en_fr_vad() builds the LM config with the
ExtraHeadsConfig that loads `extra_heads.X.weight` from the
checkpoint. The standard 1B en/fr config has extra_heads = None.
- Stt::end_of_turn_probability(&AsrEvent::Step) extracts head index
2's probability (per the Kyutai reference Python script). 2 unit
tests.
- converse_server gains --vad / --vad-threshold / --vad-consecutive
flags. When --vad is set: STT runs incrementally during the WS
receive loop, watches Step events for end-of-turn probability,
and auto-fires EOT when the threshold is exceeded for K
consecutive frames. Sends {"event":"vad_eot"} to the client when
triggered, then proceeds to LLM + TTS without needing a manual
"EOT" text frame.
87 lib tests pass.
Phase 6 status:
6a STT: working
6b LLM client: working
6c.1 text->LLM->TTS: working
6c.2 WebSocket duplex MVP: working
6c.3a streaming TTS chunks: working
6c.3b semantic VAD: shipped (this commit)
6d.{auth,shutdown,metrics,rate-limit}: shipped (this commit)
6c.3c barge-in (interrupt assistant mid-speak): deferred
The Rust Unmute conversational stack is now feature-complete for the
strategic Phase 6 deliverable.
Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
Production hardening pass on the Rust Unmute MVP:
6c.3a: streaming audio output. Replaced the "collect-then-send" loop
with a tokio mpsc channel + tokio::join! between conv.run and the
WS sender. Audio chunks are forwarded to the client AS each sentence
completes TTS, instead of waiting for the full assistant response.
Drop the channel sender at end of conv.run to signal the pump exit.
6d.auth: Bearer token auth. --auth-token flag (or RTX_AUTH_TOKEN env)
on the server requires an Authorization: Bearer <token> header on the
WebSocket upgrade. Rejected upgrades return 401. Server logs a warn
if no token is configured (open dev mode). converse_client gains a
matching --auth-token flag.
6d.shutdown: Graceful SIGINT/SIGTERM. tokio::signal handlers wired
into axum::serve.with_graceful_shutdown(). Verified: SIGINT log line
"received SIGINT, shutting down gracefully" + clean exit 0.
6d.metrics: /metrics Prometheus-style endpoint. Counters
(turns_total, errors_total, connections_total) + gauges
(connections_active, stt/tts/e2e_first_audio latency averages).
Verified end-to-end: rtx_csm_turns_total 1 / errors_total 3 (from
earlier 401 attempts) / e2e_first_audio_ms_avg 21295 / etc.
Verified all four together: 401 on bad/missing auth, 200 + WS upgrade
on correct auth, full round-trip metrics, clean SIGINT exit.
Phase 6 status:
6a STT: working
6b LLM client: working
6c.1 text->LLM->TTS: working
6c.2 WebSocket duplex MVP: working
6c.3a streaming TTS chunks: working (this commit)
6c.3b semantic VAD / barge-in: deferred
6d.{auth,shutdown,metrics}: shipped (this commit)
6d.rate-limit: deferred
Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
Full-stack pure-Rust voice conversation server + CLI client:
Client -> Server binary frames: 16-bit LE PCM @ 24 kHz mono
Client -> Server text "EOT": signal end-of-turn
Server: STT (Kyutai 1B en/fr) -> transcript
LLM (OpenAI-compatible OR mock echo) -> token stream
Converse: sentence buffer -> CSM TTS -> 16-bit LE PCM
Server -> Client text {"event":"transcript","text":"..."}
Server -> Client binary frames: assistant audio
Server -> Client text {"event":"done","assistant":"..."}
Per-connection chat history; multiple turns supported per socket.
--mock-llm mode for testing without API keys (echoes user transcript).
examples/converse_server.rs: axum WebSocket server.
examples/converse_client.rs: CLI; streams WAV in as user turn, saves
response audio out.
Verified end-to-end on Metal:
Input: 10.43s LibriSpeech FLAC ("He hoped there would be stew...")
STT transcript: matched (full sentence captured by 23/25 words)
Mock LLM: "I heard you say: <transcript>."
CSM TTS: response audio streamed back via WebSocket
Round-trip wall-clock: 6.86s (TTFA on first audio chunk: 6.86s; the
pipeline is sequential per turn — Phase 6c.3 would pipeline LLM
tokens with TTS to get TTFA much lower).
This is the Rust Unmute MVP: PCM in, voice out, no Python in the
runtime path. Strategic Phase 6 deliverable.
Phase 6 status:
6a STT: working
6b LLM client: working
6c.1 text->LLM->TTS: working
6c.2 WebSocket duplex MVP: working (this commit)
6c.3 streaming pipeline + auto-EOT + barge-in: deferred
6d productionization: deferred
Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
