An owner decision can say a LEAN source is still worth re-encoding (measured: x265 crf27 lands at
33-53% of the source video bitrate at SSIM mean >=0.996). --tier cannot express that: it SKIPS any
file whose classification disagrees. --force-tier applies the requested tier instead, with two
guards that stay: copy is refused for a VP9/AV1 source (iOS cannot play the result) and a re-encode
is refused for a file that is already HEVC hvc1 (that is the --overwrite decision).
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.
hoelee
Hermes Agent