docs(stt): record why transcript cuts are not snapped to quiet points

[EtienneLescot]

Summary

Measured the quiet-point cut snap suggested in #1023 on tools/stt-eval/word-timing (TTS corpus of 48 clips, clean and noisy, CTC aligner):

• Snapping unconditionally to the quietest 10 ms lands inside words (a fricative or a stop closure is quieter than the boundary): clean one-word deletes go from 49% to 48/41/33% at ±10/20/30 ms.
• Gated to near-silence (30 dB under the boundary), it moves 48 of 6,509 boundaries and changes no figure.
• The only gain (+2 points), a cut in the middle of a short gap, is what cut-breath.ts already does.

The numbers now sit in transcription-and-captions.md, with the other ideas tried and left out. The vocabulary prompt (part 1) needs the whisper-stt helper to read a prompt field and set initial_prompt, so it is left for a follow-up with a helper rebuild.

Related issue

Part of #1023

Type of change

• Documentation

Release impact

• No release note needed

Desktop impact

• Not platform-specific

Testing

• Docs only. Measured with the installed v2.0.0 helper (Vulkan) and the app's cached CTC aligners; not on real speech (LibriSpeech is not on disk).

🤖 Generated with Claude Code

Summary by CodeRabbit

• Documentation
  • Added measured results for word-boundary snapping at three time ranges, compared with the existing cut-breath behavior and an earlier RMS-based approach.
  • Documented that restricting snapping to near-silence affected 48 of 6,509 boundaries and did not change the measured results.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: defaults
• Review profile: CHILL
• Plan: Advanced
• Run ID: d439e55c-a021-4b08-abc7-9de047d21076

📥 Commits

Reviewing files that changed from the base of the PR and between 6e27423 and 1a3920f.

📒 Files selected for processing (1)

• technical-documentation/architecture/transcription-and-captions.md

Included review availability: This review used your included allowance. Your plan provides up to 8 included reviews per hour; 4 remain after this review.

---

📝 Walkthrough

Walkthrough

The architecture documentation adds measurements from evaluating cut snapping between words with gaps under 100 ms. It compares quietest-point snapping windows with existing cut-breath behavior and records results for near-silence and RMS snapping.

Changes

Cut-Snapping Evaluation

Layer / File(s)	Summary
Document cut-snapping results technical-documentation/architecture/transcription-and-captions.md	The documentation reports clean one-word delete rates of 48%, 41%, and 33% for quietest-point snapping within ±10, ±20, and ±30 ms, compared with 51% for existing cut-breath behavior. It also records that near-silence snapping changed no results and that the old RMS snap had similar results.

Priority: ⬇️ Low

Estimated code review effort: 1 (Trivial) | ~4 minutes

Change: Other

Suggested reviewers: vitaligusatinsky

Merge Risk: ⚪ Minimal · up to 1a392

The documentation contains an inaccurate pointer to the RMS-snap discussion, but this is a minor issue and does not materially affect merge readiness.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly describes the main change: documenting why transcript cuts are not snapped to quiet points.
Description check	✅ Passed	The description covers the change, related issue, documentation type, release and platform impact, and testing. It also explains the measurement limits and deferred follow-up. The screenshots section …
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 0…
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

• Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}