docs: the benefit case — ten real failures and the guard each produced

docs/WHY.md records the headline case and the guards, all traceable to failures this
pipeline actually hit rather than hypotheticals:

- the file that dropped 23.0% of frames while r_frame_rate == avg_frame_rate read
  exactly equal, and which a full library scan did not flag
- 27 invisible stutterers (1.2% of the library) with the same signature
- a detector that missed one of the two defect shapes (no ctts box) entirely
- a "lossless" remux that faithfully carried the stutter through -c copy
- a re-download that reproduced the defect, because the source mkv is already flat
- a video that played only its first 10 seconds after a short network copy, where
  getsize() returned stale metadata and size-based verification passed
- a 115-file batch lost to a full disk
- two concurrent encoders starving each other and dropping frames
- an iPad refusing an otherwise perfect file over hev1 vs hvc1
- Opus copied into an MP4

Also carries the reproduction (scripts/selftest.py), why a browser cannot be the
automated gate (Chrome decodes no HEVC, so an HEVC file reports 0/0 and looks perfect),
the 2x2 that proves the cause is container timing and not the bitstream, and cron /
Task Scheduler recipes with the reason each is safe to schedule.
This commit is contained in:
Hermes Agent
2026-10-04 13:16:50 +08:00
parent 0cdb54f910
commit 3619adaf7c
3 changed files with 131 additions and 0 deletions
+1
View File
@@ -43,6 +43,7 @@ There are **no credentials** in this project, so there is no `SECRETS.md`.
```
SKILL.md the Hermes skill (installed per §4)
README.md human-facing overview
docs/WHY.md the benefit case: ten real failures + the guard each produced
scripts/transcode.py the tool: plan -> encode -> verify -> keep input on failure
scripts/selftest.py proves the detector; both defect shapes, no false positives
references/compatibility-matrix.md per-platform codec/container facts with citations