universal-video-transcode/AGENTS.md

AGENTS.md — entry point for any AI session touching this repo

This repo is the canonical source of the universal-video-transcode Hermes skill. Read this file first, then README.md, then the specific reference you need.

Owner: Lee Teong Hoe (Mr Hoelee) · [email protected] · WhatsApp +60 12-797 2969

---

1. What this is

One tool that turns any video/audio file into an MP4 that plays on both iPad and Android, at the best quality the target codec allows.

layer	what	where
the tool	scripts/transcode.py — path in, verified MP4 out	this repo
the gate	scripts/selftest.py — builds both defect shapes and asserts the detector	this repo
the skill	SKILL.md + references/ — loads into Hermes	copied to the skill dir (§4)

There are no credentials in this project, so there is no SECRETS.md.

2. The non-negotiables (read before you change anything)

1. -fps_mode cfr on every video re-encode. Without it the encoder silently drops 0.5–1.3% of frames, leaving doubled frame intervals that play as judder. verify() fails an item whose output comes back non-uniform — never remove that check.
2. -tag:v hvc1 on every HEVC output, and -pix_fmt yuv420p. Apple refuses hev1 (ffmpeg's default) and non-8-bit formats lose device compatibility.
3. Never copy a video whose timeline is defective. -c copy cannot retime — ffmpeg will not rewrite stts/ctts under stream copy — so a flat input survives into the output. plan_for() decides this; do not "simplify" it into an unconditional copy.
4. One encoder at a time. The lock file is not optional hygiene: two concurrent NVENC jobs share one encoder unit, starve each other, and drop frames.
5. Run python scripts/selftest.py after touching the detector. It is the only thing standing between this tool and shipping files that stutter.
6. Never write encode output straight to a network share. Encode to local disk, verify, then copy the complete file across; a streaming .part write leaves a corrupt stub on any blip. If the destination is remote, keep the output local.

3. Layout

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
references/verification-and-automation.md  the defect classes, the structural gate, the 2x2 proof

4. Installing the skill

cp -r . "$LOCALAPPDATA/hermes/skills/media/universal-video-transcode"

Keep this repo the source of truth and copy to the skill dir, not the reverse — edits made only in the skill dir are lost the next time it is reinstalled.

5. What "verified" means here

An output is accepted only if all of these hold, each read back from the file:

duration within 1% · resolution identical · expected video codec · hvc1 tag on HEVC · audio is AAC · 8-bit yuv420p · uniform cadence · no flat composition offsets · full decode exits 0 · read-back after the write matches.

Do not claim a fix without running the arbiter. measure_playback.py in the tubesync-selfhosted skill plays a file in real Chrome and reports getVideoPlaybackQuality().droppedVideoFrames — but note Chrome cannot decode HEVC, so an HEVC file reports 0 decoded / 0 dropped and that is not a pass. Judge HEVC by the structural gate and confirm on the Apple device.

6. Related work

• hoelee-resource-transcode — the TubeSync archive this tool was extracted from. It owns the DB-driven pipeline (tsconv.py / tsfix.py) and the deeper frame-timing forensics. tsconv.flat_timing() is that repo's copy of the detector: keep the two in step, and note that the missing-ctts shape was once missed by three duplicated copies of exactly this logic. One implementation per repo.
• references/verification-and-automation.md carries the measured 2x2 that proved the defect is container timing and not the bitstream. If you are about to argue that a bitstream property is the cause, read that first.