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
+5
View File
@@ -51,6 +51,11 @@ flat_noctts.mp4 True True ok MP4 with NO ctts box
flat_ctts1.mp4 True True ok MP4 with a single constant ctts entry
```
**Measured on the file that prompted this:** 23.0% of frames dropped before, **0.0% after**.
The full benefit case — the ten real failures this pipeline hit and the guard each one
produced — is in [`docs/WHY.md`](docs/WHY.md).
## Compatibility
| | iPad / iOS | Android |