Hermes Agent
3619adaf7c
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.
125 lines
5.2 KiB
Markdown
125 lines
5.2 KiB
Markdown
# 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.
|
||
|
||
```sh
|
||
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.
|
||
|
||
```sh
|
||
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`](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`](references/compatibility-matrix.md).
|
||
|
||
## Quality policy
|
||
|
||
- **Never upscale** — the source resolution is preserved; there is no `scale` in 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 cfr` on 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
|
||
|
||
```sh
|
||
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:
|
||
|
||
```sh
|
||
cp -r . "$LOCALAPPDATA/hermes/skills/media/universal-video-transcode"
|
||
```
|
||
|
||
See [`AGENTS.md`](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`.
|