P1 — build `zara-record-voice-fixtures` with guided realistic timing and audio quality validation #167

New issue

Open

opened 2026-08-22 21:54:33 +00:00 by lost-rob0t · 0 comments

lost-rob0t commented

2026-08-22 21:54:33 +00:00

(Migrated from github.com)

Parent epic: #151
Depends on: #166

Goal

Build the developer recording tool that reads the canonical fixture manifest, tells the human exactly what to say, waits realistic declared intervals between utterances, records each step and validates audio before accepting it.

UX requirements

select all/tag/case subset;
get-ready countdown/cue;
display exact phrase prominently;
record separate utterance files by default;
sleep/cue using manifest timing, including realistic between-argument/turn delay;
allow re-record current step/case;
resume an incomplete recording session safely;
optional continuous-session capture when manifest requests it;
summarize accepted/rejected files and reasons;
never mutate semantic expected results from what STT happened to hear.

Audio requirements

Use Zara's canonical audio helpers where possible. Validate nonempty bounded audio, format/sample rate/channels or deterministic conversion, duration, NaN/invalid samples, clipping/saturation, near-silence, peak/RMS sanity and file size. Preserve enough pre/post silence for declared VAD tests. No network needed.

Safety/path behavior

Manifest controls allowed repository fixture destination; block path traversal/symlink escape; refuse silent overwrite unless explicitly re-recording; temporary files committed atomically; interrupt/crash leaves recoverable state; no arbitrary shell commands.

Timing tests

Use fake clock/audio device in unit tests: do not make CI literally wait realistic human seconds. Prove generated prompt/cue sequence honors declared e.g. ~1.8s inter-turn timing, clamps invalid values and cancels promptly.

Acceptance

A developer can run one command and be guided through a realistic multi-turn test such as Zara, set a timer. -> pause -> Twenty seconds., producing validated fixture files exactly referenced by the shared manifest.

Parent epic: #151 Depends on: #166 ## Goal Build the developer recording tool that reads the canonical fixture manifest, tells the human exactly what to say, waits realistic declared intervals between utterances, records each step and validates audio before accepting it. ## UX requirements - select all/tag/case subset; - get-ready countdown/cue; - display exact phrase prominently; - record separate utterance files by default; - sleep/cue using manifest timing, including realistic between-argument/turn delay; - allow re-record current step/case; - resume an incomplete recording session safely; - optional continuous-session capture when manifest requests it; - summarize accepted/rejected files and reasons; - never mutate semantic expected results from what STT happened to hear. ## Audio requirements Use Zara's canonical audio helpers where possible. Validate nonempty bounded audio, format/sample rate/channels or deterministic conversion, duration, NaN/invalid samples, clipping/saturation, near-silence, peak/RMS sanity and file size. Preserve enough pre/post silence for declared VAD tests. No network needed. ## Safety/path behavior Manifest controls allowed repository fixture destination; block path traversal/symlink escape; refuse silent overwrite unless explicitly re-recording; temporary files committed atomically; interrupt/crash leaves recoverable state; no arbitrary shell commands. ## Timing tests Use fake clock/audio device in unit tests: do not make CI literally wait realistic human seconds. Prove generated prompt/cue sequence honors declared e.g. ~1.8s inter-turn timing, clamps invalid values and cancels promptly. ## Acceptance A developer can run one command and be guided through a realistic multi-turn test such as `Zara, set a timer.` -> pause -> `Twenty seconds.`, producing validated fixture files exactly referenced by the shared manifest.