searchi/tools/speech-vad/README.md

# CPU speech-activity diagnostic

Research tooling, separate from searchi's normal GPU-capable runtime. No model
download, transcription, source indexing or product default is changed.
Use the frozen source and model hashes in [the protocol](../../docs/SPEECH-VAD.md).

```sh
cmake -S tools/speech-vad -B .searchi/speech/build-vad-diagnostic -DWHISPER_SOURCE=/absolute/path/to/pinned/whisper.cpp
cmake --build .searchi/speech/build-vad-diagnostic --config Release --parallel 1
```

Run `searchi-vad-diagnostic MODEL PCM_F32LE`, retaining stdout and stderr
separately. Independently verify the model SHA-256 before running. Input must
be verified mono 16-kHz little-endian float32 PCM, at most ten minutes, with
finite samples. Decoder overshoot beyond unity is preserved without clipping.
CPU and one inference thread are fixed. Native error
logs invalidate detection even when upstream returns success. Probability
count must match the pinned 512-sample inference framing.

Output JSON retains every probability and raw centisecond interval, source
sample count and load/detection/segmentation milliseconds. Interval padding is
already applied. Preserve this raw output; a subsequent harness must explicitly
intersect intervals with actual decoded source samples and add the verified
source origin exactly once. Do not concatenate disjoint intervals without a
piecewise source map. Zero intervals are a valid no-speech decision, distinct
from nonzero exit status or missing JSON.

The wrapper fixes the preregistered segmentation parameters: threshold 0.5,
minimum speech 250 ms, silence 100 ms, maximum speech FLT_MAX, padding 30 ms,
overlap 0.1 seconds. It does not establish model accuracy or a production
speech gate. Compare the complete frozen speech/music/sound pool before judging
quality; preserve original Google audio retrieval regardless of transcription.

`gated_asr.py` runs the frozen base transcription experiment from the verified
VAD report. It preserves all five competitors, no-speech status, original source
intervals and raw ASR logs. `compare.py BASELINE GATED` reports component timing
and segment counts only; it rejects incomplete or invalid pools and does not
score retrieval quality. See the protocol document for actual evidence.
# Separate frozen VAD + DTW comparison

`gated-dtw-policy.json` combines the already frozen Silero source-intersection
decisions with the separately declared base DTW sentence-point contract.
Add `--dtw-sentences` to `gated_asr.py` and select a new output, for example
`.searchi/speech/gated-base-dtw-results-v1.json`. All five source rows remain
mandatory; explicit no-speech rows use unchanged actual frozen VAD evidence and
launch no ASR. Neither relevance labels nor the observed malformed piano output
selects a gate or a window. Original raw Google audio retrieval stays unchanged.
Original raw recognized segments and ordinary token errors remain recorded.
Valid DTW points alone determine the separate aligned candidate times; missing
or invalid points make accepted comparison scoring ineligible.

The combined manifest pins unchanged VAD report/worker, base worker, DTW policy,
DTW helper and ordinary helper hashes. It preserves the old gated policy in
`policy`, with separate `alignment_policy` and `combination_policy` provenance.
Rankers must independently validate both policies and reconstruct every frozen
VAD window and DTW point before inference/scoring. Existing gated base output
is not overwritten. A combination plan or structural tests establish no new
speech recognition or timestamp quality.

Run only after the coordinator freezes the plan and grants the exclusive CPU
slot. Use `--no-gpu --threads 1 --processors 1 --dtw base --no-flash-attn`; the
harness adds these explicitly. The twelve existing speech windows remain
bounded to 30 seconds, 4 MiB raw output and 600 seconds each. Observed gated
base processing previously took about 65 seconds including VAD cost; DTW cost
and memory have not been measured. Native DTW workspace defaults to an additional
128 MiB, which is not a total memory ceiling. Strict parse failures retain bounded
raw bytes and atomically persist incomplete status, then stop instead of skipping
a competitor. Plan preparation alone establishes no quality outcome.
DTW native logs are retained byte-exact as bounded base64 plus SHA so malformed
recognized bytes in diagnostic stderr cannot cause lossy decoding. Recognized
JSON remains strict UTF-8 and cannot be repaired by this log representation.

The frozen combination has now completed actual one-thread CPU ASR and Google
ranking: all five source identities, twelve original speech windows, 21 passages,
zero excluded windows; **6/8 strict start hits**, versus gated base 4/8, and
unchanged 6/8 overlaps. The gain against gated base is the Mars topic; Moon
already passed that baseline. Orange-soil recognition remains missing. This is
one English recording/four topics/eight correlated EN/DE queries, not German
speech validation or production hybrid evidence. See [actual evidence and hashes](../../docs/SPEECH-DTW.md).

The retained ASR/ranking/scorer artifact SHA values are respectively
`3b6a791df6503a7a4e91ed708be7b722d1c124a2cf6c5a290cd94296bebc3c41`,
`f743265a53ade09b36fef25fe4e90b70a46cd2610a12aaa976f179ab9835fe91`,
and `4cfbc0f540ed8edcbed6e45f55fac80ee11867597152928d3407dabd7db34502`.
Original failed diagnostics and source labels were not overwritten.

```powershell
$env:SEARCHI_FORCE_CPU = '1'
python tools/speech-vad/gated_asr.py --whisper .searchi/speech/build-cpu/bin/Release/whisper-cli.exe --model .searchi/speech/models/ggml-base.bin --ffmpeg .searchi/media-runtime/bin/ffmpeg.exe --ffprobe .searchi/media-runtime/bin/ffprobe.exe --vad-report .searchi/speech/vad-v6-results.json --scratch-parent .searchi/speech/gated-dtw-scratch --output .searchi/speech/gated-base-dtw-results-v1.json --dtw-sentences
tools/speech-rank/target/release/searchi-speech-rank.exe .searchi/speech/gated-base-dtw-results-v1.json fixtures/media/fixture.json C:/Users/karl/.searchi/models/embeddinggemma2 .searchi/runtime/auto/Release/searchi-gemma-worker.exe .searchi/speech/gated-base-dtw-google-ranks-v1.json
python tools/speech-eval/score.py --rankings .searchi/speech/gated-base-dtw-google-ranks-v1.json --output .searchi/speech/gated-base-dtw-google-score-v1.json
```

These are exact internal commands from the recorded run. Existing outputs are
evidence; use new filenames for another comparison and obtain the coordinator's
CPU slot. They are not user installation instructions.