hoelee
aad65c56d4
The gate failed a perfectly good encode (min 0.2552, mean 0.9841) because it demanded a per-frame floor of 0.985 for EVERY frame. Two measured facts say that is the wrong test: * SSIM collapses on near-flat frames. Two almost-black frames of a fade score ~0.25 while their neighbours score 0.998, so a minimum over all frames condemns good encodes. The gate now measures each source frame's luma std and drops the flat ones from the verdict (reported, never hidden; if more than half the window is flat the exclusion is skipped so the gate still means something). * A defect has a SHAPE. Measured distributions on this library: good encodes 0 of 1500 frames below 0.95; the file that triggered this 5 of 1500 below 0.85 (0.33%, isolated) at a 0.984 mean; the genuine decoder-defect files 44 of 1499 (2.9%) with the mean falling. So the verdict is now 'mean < 0.98 OR more than 1% of frames below 0.85' -> fail; a handful of scattered low frames at a healthy mean is logged as fades, not a defect - and the log line carries the counts, so the decision is auditable.
universal-video-transcode
Any video or audio file in, one MP4 out that plays on both an iPad and an Android device — at the best quality the target codec allows.
Give it a path. A file converts; a folder converts everything in it.
python scripts/transcode.py "D:/video/clip.mkv"
python scripts/transcode.py "D:/video" --recursive --dry-run # plan only, no encoding
python scripts/transcode.py "D:/video" --out D:/converted
What it does
It reads the source file (never the filename) and picks one of three recipes:
| recipe | when | video | audio |
|---|---|---|---|
copy |
H.264/HEVC with a usable timeline | -c copy — bit-identical |
copy if AAC |
fix-audio |
same, but the audio is not AAC | -c copy |
AAC 256k |
encode |
VP9/AV1, or a timeline that cannot be copied | HEVC (or x264) | copy if AAC, else AAC 256k |
A copy is used whenever a copy is possible, because a copy is lossless by definition — the strongest possible answer to "keep the quality the same".
Then it verifies the output and refuses to accept it otherwise: duration, resolution,
codec, hvc1 tag, 8-bit pixel format, uniform frame cadence, no flat composition offsets,
and a full decode pass.
Why it exists
A file can drop ~23% of its frames in a browser while r_frame_rate == avg_frame_rate
reads exactly equal — so every fps-based check calls it healthy. The cause is
deterministic and header-readable: the MP4's composition-offset table is unusable, either a
single constant ctts entry (PTS == DTS + const) or no ctts box at all (PTS == DTS).
The timestamps are then in decode order, and the decoder's reordered output frames carry
the wrong times.
This repo gates on that, structurally, without playing anything.
python scripts/selftest.py # builds both defect shapes and asserts the detector
fixture expect got verdict
src.mp4 False False ok healthy MP4, proper ctts
src.mkv False False ok Matroska - no ctts by design
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.
Compatibility
| iPad / iOS | Android | |
|---|---|---|
| Container | MP4/MOV only — no Matroska | MP4 and MKV both fine |
| Video | H.264 (all), HEVC hvc1 (A9+) |
H.264 Baseline mandatory; HEVC 5.0+ |
| Audio | AAC — never Opus | AAC and Opus both fine |
Apple is the constraint, not Android: iOS has no Matroska demuxer and cannot play Opus, so
MP4 + AAC is what forces the conversion. Two traps: HEVC must be tagged hvc1 (ffmpeg
defaults to hev1, which Apple refuses), and Android only guarantees HEVC Main profile
Level 3 — use --codec x264 when cheap/old Android hardware is in scope.
Details and citations: references/compatibility-matrix.md.
Quality policy
- Never upscale — the source resolution is preserved; there is no
scalein the pipeline. - HEVC at
-cq 27: measured SSIM 0.9937 (visually transparent) at ~source size. - H.264 (when chosen for reach) at
-crf 20. - Audio copied when already AAC; otherwise AAC 256k, where the residual error is the source's own lossy error — 320k buys nothing measurable.
-fps_mode cfron every re-encode: without it the encoder silently drops 0.5–1.3% of frames, leaving doubled intervals that play as judder.
Running it unattended
Safe to schedule — it is idempotent and self-locking:
- a lock file refuses a second instance (two concurrent NVENC jobs starve one encoder and drop frames, the exact defect this tool removes)
- an already-playable file is skipped, so a re-run costs one probe
- a failed item leaves the input untouched, so the next run retries it
- aborts below 5 GB free rather than filling the work drive
python scripts/transcode.py "Z:/media/incoming" --recursive \
--out "Z:/media/converted" >> /var/log/transcode.log 2>&1
Install as a Hermes skill
This repo is the canonical source. Copy it into the skill directory rather than editing the skill copy in place:
cp -r . "$LOCALAPPDATA/hermes/skills/media/universal-video-transcode"
See AGENTS.md for the non-negotiables.
Options
| flag | meaning |
|---|---|
--dry-run |
print the plan, encode nothing |
--codec auto|hevc|x264 |
force the video codec (x264 for maximum reach) |
--cq N / --crf N |
quality (HEVC default 27 / H.264 default 20) |
--audio 256k, --channels 0 |
audio bitrate; 0 keeps the source layout |
--cpu |
force libx265/libx264 (no NVENC) |
--keep |
keep the input file |
--overwrite |
replace an existing output |
--no-decode-check |
skip the full decode pass (faster, less safe) |
--lock PATH |
lock file location |
ffmpeg/ffprobe are taken from PATH, or from TRANSCODE_FFMPEG / TRANSCODE_FFPROBE.
License
MIT © 2026 Lee Teong Hoe (Hoelee Enterprise)