ffmpeg-skill 3.8.10 → 3.8.11

package/README.md

@@ -441,7 +441,7 @@ Without the other 30, an agent writes raw ffmpeg for those jobs, and a mistake t
 - `join.py` puts transitions between clips that differ in size, frame rate or audio layout. Done by hand, those clips have to be normalised first or xfade fails.
 - `sync.py` and `multicam.py` find the offset between two recordings by audio cross-correlation. No ffmpeg filter measures it.
 
-Every command a tool ran is in its `--json` `commands`, shell-quoted so it can be pasted and run again, and `--dry-run` prints the commands without running anything. In the 100-prompt agent eval (1.17.0, [Tested on real footage](#tested-on-real-footage)) the agent made no raw ffmpeg calls and reported no false successes.
+Every command a tool records as run is in its `--json` `commands` (`batch.py` lists none of its steps' commands, and a measurement pass is listed only where the tool records it), shell-quoted so it can be pasted and run again, except a line that names a file the tool wrote for the run and removed when it exited (such as a concat list, an ffmetadata file, a drawtext text file, a two-pass log or a stage's intermediate), and `--dry-run` on a writing tool prints the commands without writing the output (some dry runs still run a measurement, and `verify.py` ignores `--dry-run`: see below). In the 100-prompt agent eval (1.17.0, [Tested on real footage](#tested-on-real-footage)) the agent made no raw ffmpeg calls and reported no false successes.
 
 ### What does `verified` check, and what can it not tell me?
 

package/docs/contract.md

@@ -21,7 +21,7 @@ The contract is derived from the code that runs, not maintained beside it:
 | Field | Meaning | Changes when |
 |---|---|---|
 | `contract_version` | shape of this document (`2.0`) | a key is renamed, removed or changes meaning |
-| `skill.version` | the npm / package.json version (`3.8.10`) | any release |
+| `skill.version` | the npm / package.json version (`3.8.11`) | any release |
 
 A release that adds a tool or a flag keeps `contract_version`; a breaking change to the
 ToolSpec shape bumps it. Consumers pin on `contract_version` and read `skill.version`
@@ -149,7 +149,7 @@ JSON would have been rewritten for that. The flat keys, typed per tool in `outpu
   "deprecated": [],
   "removed": [{"what": "...", "since": "1.10.0", "replacement": "...", "removed_in": "2.0.0", "where": "cli | json | mcp | behaviour"},
               {"what": "running on FFmpeg 5.x (the requirements.ffmpeg floor)", "since": "2.14.0", "replacement": "FFmpeg 6.1 or later; ...", "removed_in": "3.0.0", "where": "behaviour"}],
-  "skill": {"id": "ffmpeg-skill", "version": "3.8.10", "execution_mode": "local", "kind": "execution",
+  "skill": {"id": "ffmpeg-skill", "version": "3.8.11", "execution_mode": "local", "kind": "execution",
             "entrypoints": {"cli": "...", "mcp": "...", "contract": "...", "doctor": "..."},
             "not_provided": ["AI reasoning", "decisions", "production plans", "project IR", "approvals", "network access", "transcription engine"]},
   "requirements": {"python": ">=3.10 (standard library only)", "ffmpeg": ">=6.1", "ffprobe": ">=6.1"},
@@ -936,7 +936,8 @@ before, and, when `--json` was given, on stdout:
 `message` carries the script's own reason (missing input, ffprobe failure, the last
 stderr lines of ffmpeg, the verification that failed); an optional `error.hint` names the
 flag change that would make a retry meaningful (never a diagnosis of the media); `commands` lists what was planned
-or run so the caller can retry or report without re-deriving the command; `kind: ffmpeg`
+or run so the caller can retry or report without re-deriving the command (a line that names a file
+the tool wrote for the run and removed when it exited, such as a concat list, is a record of it); `kind: ffmpeg`
 failures add `ffmpeg_returncode` (ffmpeg's own exit code; the process exits 1). `code` is a
 purely additive, statically-mapped relabelling of `kind` (never a new distinction `kind`
 doesn't already make) for a caller that wants a stable enum instead of matching `kind`
@@ -976,8 +977,10 @@ says it is kept without the step that was stopped, and the document carries it a
 **Source carry-over.** Every tool that writes a media file compares what its first input carried
 besides the picture and the sound with the file it wrote, and says so in `source_carry:
 {kept: [...], dropped: [...]}`. The items are `subtitles`, `chapters`, `cover_art`,
-`audio_channels` (a surround source only: more than two), `creation_time`, `audio_language` and
-`timecode`. A timecode is compared by its value: it is kept when the written start timecode
+`audio_channels` (a surround source only: more than two), `attachments` (Matroska attached files,
+such as the fonts of a subtitle track; only a Matroska output holds them), `video_streams` (a
+source with more than one playable picture: the tools write one), `creation_time`,
+`audio_language` and `timecode`. A timecode is compared by its value: it is kept when the written start timecode
 labels the frame the output starts on, which is the source's own label or, where the tool moved
 the picture's start (`cut` from a later frame, `fit --method trim`, `sync --trim-second`, a
 `render.py` clip with an `in`), the label of the source frame the output now starts on. A join of
@@ -985,9 +988,12 @@ several ranges (`cut --segments`, `--remove` leaving two or more) writes no star
 no single start labels the frames after the first join. The key is present only when the source
 had at least one of them, so a result for a plain source is unchanged. It is absent under `--dry-run`, for a still or GIF output, and when two
 or more inputs have a picture or sound (which one's items the output should carry is the tool's
-choice). An item bound to a stream the output does not have at all is not compared (a sound-only
+choice). `render.py`, whose stages run as their own tools, compares a project whose clips are all
+one file, with no music, replacement or effects track and no video layer, with that file; its
+timecode counts as kept when every stage that compared it kept it. An item bound to a stream the output does not have at all is not compared (a sound-only
 extract has no subtitle track to lose). It is a report, not a check: `verified` does not depend on
-it. A dropped `subtitles`, `chapters`, `cover_art` or `audio_channels` also records one
+it. A dropped `subtitles`, `chapters`, `cover_art`, `audio_channels`, `attachments` or
+`video_streams` also records one
 `source_items_dropped` warning and a notes line; a subtitle track the tool already reports through
 `dropped_non_av_streams` is not warned about twice, and a lost tag is listed without a warning.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ffmpeg-skill",
-  "version": "3.8.10",
+  "version": "3.8.11",
   "mcpName": "io.github.kajisho5/ffmpeg-skill",
   "description": "Agent Skill that gives coding agents (Claude Code, Cursor, Codex) a local video editor: 42 FFmpeg tools with a machine-readable contract, contract-derived MCP server, FFmpeg capability detection, probe-first / verify-last workflow. Cut, join, silence removal, fit, captions and karaoke, overlays, motion graphics, HDR to SDR, LUTs, audio clean-up and typed dynamics, sync with drift correction, multicam, loudness, delivery checks, project rendering, batch. No API keys, no cloud, no dependencies.",
   "keywords": [

package/references/scripts.md

@@ -412,7 +412,9 @@ burned-in line that does not move. That is a border blend, not inpainting,
 and a logo that travels or subtitles that change position are out of
 scope. The filter reads a 1 px ring outside the box, so the box cannot
 touch the frame edge, and it only interpolates 8-bit YUV (an HDR or 10-bit
-source is refused; `color.py --to-sdr` first). The rest of the frame, and
+source is refused; `color.py --to-sdr` first). Blur and pixelate cover the
+rectangle exactly at an odd `--x`/`--y` too (on 4:2:0 the chroma sample on an
+odd edge is shared with the pixel outside). The rest of the frame, and
 the whole clip's timeline, are untouched -- to cover only part of the
 timeline, `cut.py` the clip into segments first.
 
@@ -471,6 +473,8 @@ background.py -o OUT.mov --duration T --width W --height H --transparent
 No input file: ffmpeg's own `color`/`gradients` source filters generate the
 clip directly. For a title-card background, a placeholder layer, or a base
 for `overlay.py` to composite onto. `--width`/`--height` must be even.
+`--angle DEG` (any value, 0 = left to right, 90 = top to bottom) runs the gradient from the corner
+the direction starts from (C1) to the opposite one (C2).
 `--transparent` writes a canvas with alpha 0 in every pixel in an alpha line:
 ProRes 4444 with 16-bit alpha (default; `.mov`/`.mkv`), `qtrle` (`.mov`), `png`
 (`.mov`/`.mkv`) or `vp9` (`.webm`/`.mkv`). It is the base layer
@@ -485,7 +489,9 @@ reverse.py INPUT [--no-audio] [-o OUT]
 Reverses video (and audio, unless `--no-audio`) with ffmpeg's `reverse`/
 `areverse` filters, which buffer the whole clip in memory — keep this to
 clips it makes sense to reverse (seconds to a couple of minutes), not
-something this tool limits for you.
+something this tool limits for you. A `memory_heavy` warning says when the
+decoded frames come to more than about 2 GiB (size, chroma, depth and frame
+count, not the length alone).
 
 ### stabilize.py — motion stabilisation
 ```
@@ -567,10 +573,11 @@ extend` only works with `--at` at (or past) the clip's end and just makes
 the last frame last `--hold` seconds longer, with nothing pushed; `--mode insert` at
 the clip's end (no `--at`) does the same. Audio is
 silent during the held frame in `--mode insert` (there is no source audio
-for a frozen moment that didn't exist before). `--mode insert` drops a
-subtitle/data track rather than copy it with timestamps that no longer match
-the pushed picture (`dropped_non_av_streams: true` in the result), as
-`fit.py --method speed` does; `--mode extend` keeps it.
+for a frozen moment that didn't exist before). A hold inside the clip or at
+its start drops a subtitle/data track rather than copy it with timestamps that
+no longer match the pushed picture (`dropped_non_av_streams: true` in the
+result), as `fit.py --method speed` does; a hold of the last frame (`--mode
+extend`, or no `--at`) pushes nothing and keeps it.
 
 ### pad.py — add black/silent padding at the start/end
 ```

package/scripts/_common/decision.py

@@ -385,6 +385,25 @@ def stream_starts(meta: Optional[Dict[str, Any]]) -> Tuple[float, float]:
     return out[0], out[1]
 
 
+# The size of the decoded clip above which a tool that holds every frame (reverse, a boomerang)
+# says `memory_heavy`.
+HELD_FRAMES_WARN_BYTES = 2 * 1024 ** 3
+
+
+def held_frames_bytes(v: Dict[str, Any], frames: float) -> int:
+    """About how many bytes `frames` decoded frames of the picture `v` (a probe()'s `video`) take:
+    the picture's size, its chroma planes (4:2:0 1.5x, 4:2:2 2x, 4:4:4 3x, an alpha plane one
+    more) and 2 bytes a sample above 8 bits. The one estimate reverse.py and loop.py --boomerang
+    warn from: reverse.py's was the clip's duration alone, so a 30 s 4K60 clip (tens of GB) got
+    no warning and a 61 s 320x180 one did (A174)."""
+    pix = str(v.get("pix_fmt") or "")
+    planes = 3.0 if "444" in pix or pix.startswith(("gbr", "rgb", "bgr")) else 2.0 if "422" in pix else 1.5
+    if pix.startswith(("yuva", "gbra", "rgba", "bgra", "argb", "abgr", "ya")):
+        planes += 1.0
+    depth = 2 if (v.get("bit_depth") or 8) > 8 else 1
+    return int((v.get("width") or 0) * (v.get("height") or 0) * planes * depth * max(0.0, frames))
+
+
 def frame_rate(meta: Optional[Dict[str, Any]]) -> float:
     """The video's frame rate as cut.py's grid takes it: r_frame_rate, else fps; 0.0 when unknown."""
     v = (meta or {}).get("video") or {}

package/scripts/_common/emit.py

@@ -167,10 +167,11 @@ def _report_dropped_hdr10_metadata(meta: Dict[str, Any], ctx: "Context") -> None
 # source_carry: the items compared, in report order. The first group is content a viewer or
 # listener notices missing and raises the warning; the second is tags, listed but never warned
 # about (every camera file has a creation_time, so a warning for it would fire on every run).
-CARRY_CONTENT = ("subtitles", "chapters", "cover_art", "audio_channels")
+CARRY_CONTENT = ("subtitles", "chapters", "cover_art", "audio_channels", "attachments", "video_streams")
 CARRY_TAGS = ("creation_time", "audio_language", "timecode")
 _CARRY_NAMES = {"subtitles": "subtitle track", "chapters": "chapters", "cover_art": "cover picture",
-                "audio_channels": "audio channels"}
+                "audio_channels": "audio channels", "attachments": "attached files (a subtitle track's fonts)",
+                "video_streams": "video streams"}
 
 
 def source_carry(output: Optional[str], ctx: "Context", extra: Dict[str, Any]) -> "Optional[Dict[str, List[str]]]":
@@ -205,7 +206,9 @@ def source_carry(output: Optional[str], ctx: "Context", extra: Dict[str, Any]) -
             continue
         if item == "audio_channels" and src[item] <= 2:
             continue  # mono and stereo are what every tool writes; only a surround layout can be folded down
-        if item in ("subtitles", "timecode") and src["has_video"] and not out["has_video"]:
+        if item == "video_streams" and src[item] <= 1:
+            continue  # one picture is what every tool writes; only a second one can be left out
+        if item in ("subtitles", "timecode", "attachments", "video_streams") and src["has_video"] and not out["has_video"]:
             continue
         if item in ("audio_channels", "audio_language") and not out["has_audio"]:
             continue
@@ -227,8 +230,8 @@ def source_carry(output: Optional[str], ctx: "Context", extra: Dict[str, Any]) -
     if loud:
         parts = []
         for i in loud:
-            if i == "audio_channels":
-                parts.append(f"{src[i] - out.get(i, 0)} of its {src[i]} audio channels")
+            if i in ("audio_channels", "video_streams"):
+                parts.append(f"{src[i] - out.get(i, 0)} of its {src[i]} {_CARRY_NAMES[i]}")
             else:
                 parts.append("its " + _CARRY_NAMES[i])
         warn("the source carried " + ", ".join(parts) + " that this output does not have "

package/scripts/_common/probe.py

@@ -433,6 +433,11 @@ def probe(path: str, role: str = "input") -> Dict[str, Any]:
         "subtitles": len(subs),
         "chapters": len(raw.get("chapters") or []),
         "cover_art": sum(1 for s in streams if s.get("codec_type") == "video" and s.get("disposition", {}).get("attached_pic", 0)),
+        # Matroska attachments (a subtitle track's fonts, A256) and the playable pictures beside
+        # the one probe() describes, which a tool that writes one picture leaves out (A258)
+        "attachments": sum(1 for s in streams if s.get("codec_type") == "attachment"),
+        "video_streams": sum(1 for s in streams if s.get("codec_type") == "video"
+                             and not s.get("disposition", {}).get("attached_pic", 0)),
         "creation_time": 1 if any(k.lower() == "creation_time" for k in (fmt.get("tags") or {})) else 0,
         "audio_language": 1 if lang and lang.lower() != "und" else 0,
         "timecode": 1 if out["timecode"].get("value") else 0,

package/scripts/_common/runner.py

@@ -2253,6 +2253,45 @@ def ffmpeg_failure_extra(stderr: str) -> Dict[str, Any]:
     return {"hint": cls[1], "error_extra": {"reason": cls[0], "details": cls[2]}} if cls else {}
 
 
+
+
+MATROSKA_EXT = frozenset({".mkv", ".mka", ".mks"})
+
+
+def carried_stream_maps(src: Optional[str], output: str, *, chapters: bool = True, attachments: bool = True) -> List[str]:
+    """What a command that keeps a source's subtitle/data streams (`-map 0:s? -map 0:d?`, or
+    `-map 0`) adds so the written file carries what the source does, and nothing it does not:
+
+    - `-map -0:N` for an MP4/MOV chapter track. FFmpeg reads the QuickTime chapter text track as a
+      data stream (codec tag `text`) and its muxer writes a new one from the chapters it is given;
+      the copied one was written as a `gpmd` data track holding the old titles, so
+      `metadata.py --clear-chapters` left them behind and every pass added a track (A173).
+    - `-map 0:t? -c:t copy` into Matroska: a subtitle track's fonts are attachments, which no
+      `-map 0:s?`/`0:d?` selects, so every tool that kept the subtitles dropped the fonts they are
+      drawn with (A256). Other containers hold no attachments; source_carry reports them dropped.
+
+    Nothing when the source cannot be read here (the command then runs as before)."""
+    if not src or not os.path.isfile(src):
+        return []
+    try:
+        out = subprocess.run([found_exe("ffprobe"), "-v", "error", "-show_entries",
+                              "stream=index,codec_type,codec_tag_string:chapter=id", "-of", "json", src],
+                             stdout=subprocess.PIPE, stderr=subprocess.DEVNULL, text=True, encoding="utf-8",
+                             errors="replace", timeout=_probe_limit()).stdout
+        doc = json.loads(out or "{}")
+    except (OSError, subprocess.TimeoutExpired, ValueError):
+        return []
+    streams = doc.get("streams") or []
+    maps: List[str] = []
+    if chapters and doc.get("chapters"):
+        for s in streams:
+            if s.get("codec_type") == "data" and str(s.get("codec_tag_string") or "").lower() == "text":
+                maps += ["-map", f"-0:{s.get('index')}"]
+    if attachments and os.path.splitext(output)[1].lower() in MATROSKA_EXT and any(s.get("codec_type") == "attachment" for s in streams):
+        maps += ["-map", "0:t?", "-c:t", "copy"]
+    return maps
+
+
 def fail_if_classified(proc: subprocess.CompletedProcess) -> None:
     """Stop with a failed attempt's own error when ffmpeg named a cause a second encode would hit
     the same way (a full disk, a missing encoder or filter, an unreadable input): the rule
@@ -2334,7 +2373,9 @@ def run_keeping_subtitles(cmd: List[str], output: str, relabel_timecode: bool =
     so a source's tmcd data track is not copied -- its label, at the source's rate, would win over
     the new one; the MOV/MP4 muxer builds the track again from the label."""
     skip_tmcd = ["-map", "-0:d:m:timecode"] if relabel_timecode else []
-    first = run(cmd + ["-map", "0:s?", "-map", "0:d?"] + skip_tmcd + ["-c:s", "copy", "-c:d", "copy", output], check=False)
+    src = next((str(cmd[i + 1]) for i, a in enumerate(cmd[:-1]) if a == "-i"), None)
+    first = run(cmd + ["-map", "0:s?", "-map", "0:d?"] + skip_tmcd + carried_stream_maps(src, output)
+                + ["-c:s", "copy", "-c:d", "copy", output], check=False)
     if first.returncode == 0:
         return False
     if classify_ffmpeg_failure(first.stderr or "") or not _has_non_av_streams(cmd):

package/scripts/_contract.py

@@ -489,7 +489,7 @@ DIAGNOSTIC_CODES = {
     "emoji_not_drawn": ("warnings", "caption.py / graphics.py --emoji auto: no glyph, colour path or PNG asset draws these emoji here (doctor fonts.emoji mode none), so they were left out of the drawn text; also graphics.py --text-render drawtext, which has no font fallback; {count, reason}"),
     "emoji_mono_drawn_in_colour": ("warnings", "caption.py / graphics.py --emoji mono on a build whose libass draws the emoji face in colour: nothing makes the glyph monochrome, so the result's emoji.mode is color (graphics.py --text-render drawtext draws none: mode none, emoji_not_drawn)"),
     "hdr10_metadata_dropped": ("warnings", "a PQ output measured without the source's HDR10 mastering-display and/or content-light metadata (an encoder with no option for it, e.g. prores_ks or libaom on FFmpeg before 7); {dropped, codec}"),
-    "source_items_dropped": ("warnings", "the written file lacks a subtitle track, chapters, a cover picture or surround channels the first input carried (source_carry lists everything kept and dropped, tags included); not repeated for a subtitle track the tool already reports through dropped_non_av_streams; {dropped}"),
+    "source_items_dropped": ("warnings", "the written file lacks a subtitle track, chapters, a cover picture, surround channels, attached files or a second video stream the first input carried (source_carry lists everything kept and dropped, tags included); not repeated for a subtitle track the tool already reports through dropped_non_av_streams; {dropped}"),
     "audio_tracks_dropped": ("warnings", "the source has more audio tracks than the output kept (the tools write one; cut.py also reports dropped_audio_streams). Not compared when two or more inputs have sound (grid --audio-from, a mix): which source the output carries is the tool's choice; {source, kept, dropped}"),
     "grid_no_drawtext": ("fallbacks", "grid.py --label auto on a build without the drawtext filter: the cells were not labelled, as with --label none"),
     "scenes_sheet_no_drawtext": ("fallbacks", "scenes.py --sheet on a build without the drawtext filter: the sheet was drawn without timecode stamps, as with --no-timecode"),
@@ -689,7 +689,7 @@ def output_schema(name: str, meta: Dict[str, Any], hw: bool = False) -> Dict[str
                                "levels": {"type": "object", "description": "--analyze only, on an input with a video stream: picture levels sampled at 2 fps over the first 20 s, on an 8-bit scale inferred from the values measured (a 10-bit or deeper picture whose luma never passes code 255 is read as 8-bit and left unscaled) {scale, y_min, y_max, y_avg, y_low_p5, y_high_p95, saturation_avg, looks_like_log, note}; {error} when no frame was analysed. Measured under --dry-run too"}},
                 "additionalProperties": True}
     base = {"status": {"enum": ["completed"]}, "output": {"type": ["string", "null"], "description": "path written, or null"},
-            "dry_run": {"type": "boolean"}, "commands": {"type": "array", "items": {"type": "string"}, "description": "the ffmpeg command lines this run planned or ran to write its output (render.py and waveform.py: their stages' too); a measurement pass is listed only where the tool records it (e.g. loudness.py pass 1, check.py, stabilize.py pass 1), and batch.py lists none of its steps' (each results row's step documents carry their own)"},
+            "dry_run": {"type": "boolean"}, "commands": {"type": "array", "items": {"type": "string"}, "description": "the ffmpeg command lines this run planned or ran to write its output (render.py and waveform.py: their stages' too), shell-quoted; a line that names a file the tool wrote for the run and removed when it exited (such as a concat list, an ffmetadata file, a drawtext text file, a two-pass log or a stage's intermediate) cannot be run again as printed; a measurement pass is listed only where the tool records it (e.g. loudness.py pass 1, check.py, stabilize.py pass 1), and batch.py lists none of its steps' (each results row's step documents carry their own)"},
             "probe": {"type": "object", "description": "probe of the output when a file was written"},
             "output_identity": {"type": "object", "description": "2.24: {size, mtime_ns} of the file this run wrote, absent under --dry-run; pass it to check.py --expect-identity SIZE:MTIME_NS so the check grades this file and not whatever later sits at the path"},
             "encoder": {"type": "string", "description": "the video encoder the last ffmpeg command used (after any GPU->CPU fallback; under --dry-run the planned one; render.py and waveform.py: their stages' commands included), `copy` for a stream copy; absent when no command encoded video"},
@@ -698,7 +698,7 @@ def output_schema(name: str, meta: Dict[str, Any], hw: bool = False) -> Dict[str
             "verified": {"type": "boolean", "description": "true only when the artifact was written, probed, and every self-check the tool ran (verification) met its target; false under --dry-run"},
             "verification": {"type": "array", "items": {"type": "object", "properties": {"step": {"type": "string"}, "ok": {"type": "boolean"}, "stage": {"type": "string"}, "property": {"type": "string"}, "expected": {}, "measured": {}, "delta": {}, "tolerance": {}, "provenance": {"enum": ["specification", "user_specified", "independent_measurement", "input_premeasurement"]}, "attribution": {"enum": ["artifact", "reference", "instrument", "provenance", "unresolved"]}}}, "description": "what the tool itself verified: probe, plus loudness (loudness.py, export platform presets; ok false with reason not_measured when it could not be read), check (render), report.py's sections (loudness, compliance, contact_sheet) and batch.py's items (item). render.py also lists every stage's own steps beyond its artifact probe, tagged with `stage` (a cached stage's as recorded), so its `verified` is the conjunction of every stage's. Since 2.18 a step may carry the property it measured with expected, measured, delta, tolerance and the provenance of the expected value; cut, join and export add a `streams` step comparing the output's video/audio streams with the input's; a step with ok false carries `attribution` (unresolved until a tool knows the cause)"},
             "unverified": {"type": "array", "items": {"type": "string"}, "description": "2.18: the properties of the output this tool did not measure (the unverified range), e.g. caption's rendered_placement; `verified` covers the measured properties only"},
-            "source_carry": {"type": "object", "description": "what the first input carried besides its picture and sound, compared with the written file: {kept: [...], dropped: [...]} over subtitles, chapters, cover_art, audio_channels (a surround source only), creation_time, audio_language, timecode (kept only when the written start timecode is the label of the frame the output starts on: the source's own, or moved there by a tool that moved the picture's start; a join of several ranges writes none). Present only when the source had at least one of them; absent under --dry-run, for a still or GIF output, and when two or more inputs have a picture or sound. A report, not a check: `verified` does not depend on it. A dropped subtitles/chapters/cover_art/audio_channels also records a source_items_dropped warning"},
+            "source_carry": {"type": "object", "description": "what the first input carried besides its picture and sound, compared with the written file: {kept: [...], dropped: [...]} over subtitles, chapters, cover_art, audio_channels (a surround source only), attachments (Matroska attached files, such as a subtitle track's fonts), video_streams (a source with more than one playable picture), creation_time, audio_language, timecode (kept only when the written start timecode is the label of the frame the output starts on: the source's own, or moved there by a tool that moved the picture's start; a join of several ranges writes none). Present only when the source had at least one of them; absent under --dry-run, for a still or GIF output, and when two or more inputs have a picture or sound (render.py: a project whose clips are one file, with no music, replacement, effects track or video layer, is compared with that file). A report, not a check: `verified` does not depend on it. A dropped subtitles/chapters/cover_art/audio_channels/attachments/video_streams also records a source_items_dropped warning"},
             "diagnostics": DIAGNOSTICS_SCHEMA}
     extra: Dict[str, Any] = {}
     if name == "check":

package/scripts/background.py

@@ -22,6 +22,35 @@ from _common.emit import note
 from _common import STATE,  add_common, apply_common, die, draws_chroma, emit, ffmpeg_base, info, parse_time, probe, rgb_chain_to_bt709, run, validate_color, video_args, X264_PRESETS, time_arg, fmt_secs
 
 
+def gradient_source(w: int, h: int, fps: float, c0: str, c1: str, angle: float) -> str:
+    """The `gradients` source for a `w`x`h` gradient at `angle` degrees (0 = left to right, 90 =
+    top to bottom) that runs from the frame's first corner along that direction to its last: c0
+    on the corner the direction starts from, c1 on the one opposite.
+
+    `gradients` takes its two points inside its own frame: a coordinate below -1 is refused and
+    one outside 0..w-1 / 0..h-1 is replaced by a seeded random one. The points were (0, 0) and the
+    width along the angle, so every angle outside 0-90 failed as kind ffmpeg (135 put x1 at -45:
+    A169), and inside it the far point was past the frame (x1 = w at 0, y1 = w at 90) and drawn
+    from the seed instead. A line of any direction that crosses the whole frame fits inside a
+    square canvas as wide as the frame's diagonal, so the gradient is drawn there, through the
+    centre, over the frame's extent along the direction (w|cos| + h|sin|), and the frame is cropped
+    from the middle."""
+    rad = math.radians(angle)
+    c, s = math.cos(rad), math.sin(rad)
+    side = 2 * math.ceil((math.hypot(w, h) + 4) / 2)  # even, so the centred crop is whole pixels
+    half = (w * abs(c) + h * abs(s)) / 2
+    mid = side / 2
+    x0, y0, x1, y1 = (round(mid - half * c), round(mid - half * s), round(mid + half * c), round(mid + half * s))
+    # gradients defaults to seed=-1 (a random seed picked fresh each run) and speed=0.01 (a
+    # slow rotation applied every frame), so without pinning both, this "static" background
+    # was neither reproducible between runs nor actually static across its own duration --
+    # violating the bit_exact/deterministic contract _contract.py declares for this tool.
+    # speed's own valid range bottoms out at 1e-05 (0 is refused), so that's the closest to
+    # motionless the filter allows.
+    return (f"gradients=size={side}x{side}:rate={fps:g}:c0={c0}:c1={c1}:x0={x0}:y0={y0}:x1={x1}:y1={y1}"
+            f":seed=0:speed=1e-05,crop={w}:{h}:{(side - w) // 2}:{(side - h) // 2}")
+
+
 def main() -> int:
     ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
     ap.add_argument("-o", "--output", required=True, help="output file")
@@ -66,16 +95,7 @@ def main() -> int:
             die(f"--gradient needs two colours as C1:C2, got '{args.gradient}'")
         validate_color(c0, "--gradient")
         validate_color(c1, "--gradient")
-        rad = math.radians(args.angle)
-        x1 = round(args.width * math.cos(rad))
-        y1 = round(args.width * math.sin(rad))
-        # gradients defaults to seed=-1 (a random seed picked fresh each run) and speed=0.01 (a
-        # slow rotation applied every frame), so without pinning both, this "static" background
-        # was neither reproducible between runs nor actually static across its own duration --
-        # violating the bit_exact/deterministic contract _contract.py declares for this tool.
-        # speed's own valid range bottoms out at 1e-05 (0 is refused), so that's the closest to
-        # motionless the filter allows.
-        src_filter = f"gradients=size={args.width}x{args.height}:rate={args.fps:g}:c0={c0}:c1={c1}:x0=0:y0=0:x1={x1}:y1={y1}:seed=0:speed=1e-05"
+        src_filter = gradient_source(args.width, args.height, args.fps, c0, c1, args.angle)
         colours = [c0, c1]
     else:
         validate_color(args.color, "--color")

package/scripts/broll.py

@@ -105,9 +105,15 @@ def main() -> int:
         dur_b = input_length(meta_b)
         if dur_b and start_b + length > dur_b + 0.01 and not STATE.dry_run:
             die(f"cutaway {i + 1}: {path} has only {dur_b - start_b:.3f}s from {start_b:g}s, {length:g}s asked for")
-        if cutaways and at < cutaways[-1]["at"] + cutaways[-1]["length"]:
-            die(f"cutaway {i + 1} at {at:g}s overlaps the previous one (ends {cutaways[-1]['at'] + cutaways[-1]['length']:g}s)")
         cutaways.append({"path": path, "at": at, "length": length, "from": start_b, "has_audio": bool(meta_b.get("audio")), "meta": meta_b})
+    # overlap is a property of the windows in time, not of the order they were given in: compared
+    # against the one given before it, a later window listed first was called overlapping (A179)
+    order = sorted(range(len(cutaways)), key=lambda k: cutaways[k]["at"])
+    for prev, k in zip(order, order[1:]):
+        end_prev = cutaways[prev]["at"] + cutaways[prev]["length"]
+        if cutaways[k]["at"] < end_prev:
+            die(f"cutaway {k + 1} at {cutaways[k]['at']:g}s overlaps cutaway {prev + 1} "
+                f"({cutaways[prev]['at']:g}s to {end_prev:g}s)")
     if args.audio != "a" and not all(c["has_audio"] for c in cutaways):
         die("--audio b/mix needs audio on every B-roll clip")
 

package/scripts/caption.py

@@ -56,7 +56,7 @@ from _common import asr as _asr
 from _common.asr import ENGINE_CHOICES
 from _common.emit import warn
 from _common.probe import display_size, square_pixels, square_pixels_note
-from _common.runner import subtitle_codec_for, subtitle_container_holds
+from _common.runner import carried_stream_maps, subtitle_codec_for, subtitle_container_holds
 from _common.fonts import font_choice, record_font_choice
 from _common import (ASR_INSTALL_HINT, die_no_engine, parse_srt, transcribe, whisper_word_timings,
                      write_srt)
@@ -1787,7 +1787,7 @@ def main() -> int:
         if meta.get("audio"):
             maps += ["-map", f"0:a:{args.audio_stream}"]
         if existing_subs:
-            maps += ["-map", "0:s?"]
+            maps += ["-map", "0:s?"] + carried_stream_maps(args.input, output, chapters=False)  # their fonts (A256)
         for n in range(len(added)):
             maps += ["-map", f"{n + 1}:0"]
         cmd += maps + ["-c:v", "copy"] + (["-c:a", "copy"] if meta.get("audio") else [])

package/scripts/color.py

@@ -32,7 +32,7 @@ import os
 import sys
 from typing import List, Optional
 
-from _common.runner import fail_if_classified
+from _common.runner import carried_stream_maps, fail_if_classified
 from _common import STATE, add_common, analyze_levels, LEGAL_RANGE_CHOICES, legal_limits, measure_signal_range, apply_common, emit, aac_args, cfr_args, default_output, die, escape_filter_path, ffmpeg_base, ffmpeg_bsfs, info, probe, require_tool, run, run_analysis, run_keeping_subtitles, x264_args, X264_PRESETS, fmt_secs
 from _common.emit import note, warn
 from _common.color import is_rgb, rgb_to_bt709_filter
@@ -329,7 +329,8 @@ def retag(args: argparse.Namespace, meta: dict, has_audio: bool, src_alpha=lambd
     ext = os.path.splitext(output)[1].lower()
     tags = ["-colorspace", names[0], "-color_primaries", names[1], "-color_trc", names[2]]
     bsf = retag_bsf(meta, args.retag)
-    cmd = ffmpeg_base() + ["-i", args.input, "-map", "0", "-c", "copy"] + bsf + tags
+    cmd = (ffmpeg_base() + ["-i", args.input, "-map", "0"] + carried_stream_maps(args.input, output, attachments=False)
+           + ["-c", "copy"] + bsf + tags)
     if ext in (".mp4", ".mov", ".m4v"):
         cmd += ["-movflags", "+faststart"]
     cmd.append(output)
@@ -357,8 +358,9 @@ def retag(args: argparse.Namespace, meta: dict, has_audio: bool, src_alpha=lambd
         info("re-encoding video/audio with the new tags (subtitles/data streams kept)")
         label = ["-vf", f"setparams=color_primaries={names[1]}:color_trc={names[2]}:colorspace={names[0]}"]
         enc = x264_args(args.crf, args.preset, keep_bt709=False) + (aac_args() if has_audio else [])
-        cmd = ffmpeg_base() + ["-i", args.input, "-map", "0:v:0", "-map", f"0:a:{args.audio_stream}?",
-                                "-map", "0:s?", "-map", "0:d?"] + label + enc + ["-c:s", "copy", "-c:d", "copy", output]
+        cmd = (ffmpeg_base() + ["-i", args.input, "-map", "0:v:0", "-map", f"0:a:{args.audio_stream}?",
+                                "-map", "0:s?", "-map", "0:d?"] + carried_stream_maps(args.input, output) + label + enc
+               + ["-c:s", "copy", "-c:d", "copy", output])
         proc2 = run(cmd, check=False)
         fail_if_classified(proc2)
         if proc2.returncode != 0:
@@ -552,7 +554,8 @@ def main() -> int:
             die("--strip-dovi only applies to HEVC (Dolby Vision) streams")
         if not v.get("dolby_vision"):
             warn("no Dolby Vision metadata detected; removing unregistered SEI anyway", "dovi_not_detected")
-        cmd = ffmpeg_base() + ["-i", args.input, "-map", "0", "-c", "copy", "-bsf:v", "filter_units=remove_types=62", "-tag:v", "hvc1"]
+        cmd = (ffmpeg_base() + ["-i", args.input, "-map", "0"] + carried_stream_maps(args.input, output, attachments=False)
+               + ["-c", "copy", "-bsf:v", "filter_units=remove_types=62", "-tag:v", "hvc1"])
         if os.path.splitext(output)[1].lower() in (".mp4", ".mov", ".m4v"):
             cmd += ["-movflags", "+faststart"]
         cmd.append(output)

package/scripts/crop.py

@@ -62,7 +62,9 @@ def main() -> int:
     has_audio = bool(meta.get("audio"))
 
     output = args.output or default_output(args.input, "crop")
-    vf = [f"crop={args.width}:{args.height}:{args.x}:{args.y}", "setsar=1"]
+    # exact=1: without it crop rounds an odd --x/--y down to the chroma grid of a 4:2:0 frame,
+    # and the rectangle written was one pixel left of / above the one asked for (A170's sibling)
+    vf = [f"crop={args.width}:{args.height}:{args.x}:{args.y}:exact=1", "setsar=1"]
     if square_pixels(meta["video"]):
         vf.insert(0, square_pixels(meta["video"]))
         note(square_pixels_note(meta["video"]))

package/scripts/export.py

@@ -46,7 +46,7 @@ import tempfile
 from pathlib import Path
 from typing import Dict, List, Optional
 
-from _common.runner import child_exit_code, fail_if_classified, kept_clause, mark_delivered
+from _common.runner import carried_stream_maps, child_exit_code, fail_if_classified, kept_clause, mark_delivered
 from _common import STATE, run_analysis, add_common, apply_common, bt709_label_filter, bt709_matrix_args, bt709_tag_args, child_args, emit, cfr_args, default_output, die, encoder_args, ffmpeg_base, info, probe, require_tool, run, run_tool, validate_color, pad_filters, add_pad_fill_args, fmt_secs
 from _common.decision import hw_preset_video, restate_last_swap
 from _common.emit import note, record_fallback, record_skip, warn
@@ -321,15 +321,19 @@ _subtitle_codec = subtitle_codec_for
 
 def _data_streams(path: str) -> List[Dict[str, object]]:
     """The data streams of a file ({index, codec}), without its attachments (probe()'s
-    data_streams counts both, and -map 0:d maps only the data streams)."""
+    data_streams counts both, and -map 0:d maps only the data streams) and without an MP4/MOV
+    chapter track, which the muxer writes again from the chapters (carried_stream_maps, A173)."""
     proc = run([require_tool("ffprobe"), "-v", "error", "-select_streams", "d", "-show_entries",
-                "stream=codec_name,codec_tag_string", "-of", "json", path], quiet=True)
+                "stream=codec_name,codec_tag_string:chapter=id", "-of", "json", path], quiet=True)
     try:
-        streams = json.loads(proc.stdout or "{}").get("streams") or []
+        doc = json.loads(proc.stdout or "{}")
     except ValueError:
         # an unread list would map nothing and report nothing dropped
         die(f"ffprobe's data-stream list for {path} did not parse", kind="ffmpeg")
-    return [{"index": n, "codec": s.get("codec_name") or s.get("codec_tag_string")} for n, s in enumerate(streams)]
+    streams = doc.get("streams") or []
+    chapter_track = bool(doc.get("chapters"))
+    return [{"index": n, "codec": s.get("codec_name") or s.get("codec_tag_string")} for n, s in enumerate(streams)
+            if not (chapter_track and str(s.get("codec_tag_string") or "").lower() == "text")]
 
 
 def _run_keeping_non_av(cmd: List[str], output: str, sub_codecs: List[str], data: int) -> List[str]:
@@ -338,10 +342,13 @@ def _run_keeping_non_av(cmd: List[str], output: str, sub_codecs: List[str], data
     subtitles + data, subtitles alone, neither; each retry is a `non_av_streams_dropped` fallback
     with the attempt's error. `cmd` already maps the picture and the sound and has no output.
     Returns the stream types dropped ([] when everything mapped was written)."""
+    src = next((str(cmd[i + 1]) for i, a in enumerate(cmd[:-1]) if a == "-i"), None)
     sub_args: List[str] = ["-map", "0:s"] if sub_codecs else []
     for n, codec in enumerate(sub_codecs):
         sub_args += [f"-c:s:{n}", codec]
-    data_args = ["-map", "0:d", "-c:d", "copy"] if data else []
+    if sub_codecs:
+        sub_args += carried_stream_maps(src, output, chapters=False)  # the fonts the subtitles are drawn with (A256)
+    data_args = (["-map", "0:d"] + carried_stream_maps(src, output, attachments=False) + ["-c:d", "copy"]) if data else []
     rungs = [(sub_args + data_args, [])]
     if sub_codecs and data:
         rungs.append((sub_args, ["data"]))
@@ -389,7 +396,9 @@ def _non_av_report(subs: List[Dict], sub_codecs: List[str], data: List[Dict], dr
         written_data = _data_streams(output)
     for kind, streams, written in (("subtitle", subs, written_subs), ("data", data, written_data)):
         for n, s in enumerate(streams):
-            row = {"type": kind, "index": n, "codec": s.get("codec")}
+            # a data row keeps its n-th-of-type index in the source: the chapter text track is left
+            # out of the list, so a timecode track after it is data stream 1, not 0
+            row = {"type": kind, "index": s.get("index", n) if kind == "data" else n, "codec": s.get("codec")}
             if kind == "subtitle":
                 row["language"] = s.get("language")
             if STATE.dry_run and kind not in dropped:

package/scripts/freeze.py

@@ -67,7 +67,8 @@ def main() -> int:
     # no frame at or after --at (no --at holds at the clip's end): the insert tail would be empty
     # and the hold lost, so hold the last frame as --mode extend does (#416 review)
     vend = v0 + (meta["video"].get("duration") or dur - v0)
-    if args.mode == "extend" or cut_at >= vend - 0.5 / rate:
+    holds_end = args.mode == "extend" or cut_at >= vend - 0.5 / rate
+    if holds_end:
         # tpad's stop_duration clones the last frame for the given duration; no PTS surgery
         # needed since it only ever appends past the real end.
         vf = f"tpad=stop_mode=clone:stop_duration={args.hold:.3f}"
@@ -127,10 +128,12 @@ def main() -> int:
         cmd += aac_args()
     else:
         cmd += ["-an"]
-    if args.mode == "insert":
+    if not holds_end:
         # the picture gains `hold` seconds at `at`; a stream-copied subtitle track would keep its
         # old timestamps and every cue after the freeze would fire early (same reasoning as
-        # fit.py --method speed). Drop it rather than ship captions that lie.
+        # fit.py --method speed). Drop it rather than ship captions that lie. A hold of the last
+        # frame (the default with no --at, or an --at at the end) moves nothing, so the track is
+        # kept as --mode extend keeps it (A180)
         run(cmd + [output])
         dropped_streams = bool(meta.get("subtitle_streams") or meta.get("data_streams"))
     else:

package/scripts/graphics.py

@@ -564,7 +564,9 @@ def main(force_route: Optional[str] = None) -> int:
         rise = int(fs * 0.5)
         pop = f"min(1,(t-{s:.3f})/0.25)"
         xe = f"{m_left}" if "left" in pos else f"w-text_w-{m_right}"
-        ye = (f"{m_top}+{rise}*(1-{pop})" if "top" in pos else f"h-text_h-{m_bottom}-{rise}*(1-{pop})")
+        # every position rises into place, on both routes: a bottom chip started `rise` px above
+        # its rest on drawtext and dropped, where the ASS \move below rises (A177)
+        ye = (f"{m_top}+{rise}*(1-{pop})" if "top" in pos else f"h-text_h-{m_bottom}+{rise}*(1-{pop})")
         alpha = f"min({pop},{fade_a})"
         align = (7 if "left" in pos else 9) if "top" in pos else (1 if "left" in pos else 3)
         y_rest = m_top if "top" in pos else H - m_bottom

package/scripts/grid.py

@@ -26,7 +26,7 @@ import os
 import sys
 
 from _common import add_common, apply_common, aac_args, cfr_args, default_output, die, emit, X264_PRESETS, fmt_secs, \
-    as_limited, draws_chroma, drawn_chain, escape_drawtext, ffmpeg_base, info, label_chain, matrix_chain, range_chain, probe, run, validate_color, video_args
+    as_limited, draws_chroma, drawn_chain, drawtext_text_opts, escape_drawtext, ffmpeg_base, info, label_chain, matrix_chain, range_chain, probe, run, validate_color, video_args
 from _common.fonts import font_choice, record_font_choice
 from _common import drawtext_fontfile  # noqa: E402
 from _common import ffmpeg_filters, filter_missing_hint  # noqa: E402
@@ -173,7 +173,9 @@ def main() -> int:
         if args.label == "auto":
             font_file = label_fonts[i]["file"]
             font_opt = drawtext_fontfile(font_file) if font_file else f"font='{escape_drawtext(args.font)}'"
-            drawn.append((f"drawtext=text='{escape_drawtext(labels[i])}':{font_opt}:fontsize={args.font_size}:"
+            # the textfile= route every other drawn text takes: escape_drawtext() is for a font name,
+            # and dropped an apostrophe or a percent sign from a file name's label (A178)
+            drawn.append((f"drawtext={drawtext_text_opts(labels[i])}:{font_opt}:fontsize={args.font_size}:"
                           f"fontcolor={args.font_color}:x=w-tw-{LABEL_MARGIN}:y=h-th-{LABEL_MARGIN}:"
                           f"box=1:boxcolor=black@0.5:boxborderw=4", "null"))
         gap_r = args.gap if i % args.cols < args.cols - 1 else 0

package/scripts/loop.py

@@ -34,7 +34,7 @@ import tempfile
 
 from _common import STATE, concat_list_line, add_common, aac_args, apply_common, cfr_args, default_output, die, emit, ffmpeg_base, info, parse_time, probe, refuse_output_is_input, require_filter, require_tool, run, video_args, X264_PRESETS, time_arg, fmt_secs
 from _common.emit import warn
-from _common.decision import av_trim, length_output_t
+from _common.decision import HELD_FRAMES_WARN_BYTES, av_trim, held_frames_bytes, length_output_t, stream_starts
 from _common.probe import decode_gray_frames, decode_pcm_mono
 from _common.emit import input_length
 
@@ -60,9 +60,8 @@ def _boomerang_graph(meta, src_dur: float, times) -> str:
             f"-- cut the clip shorter first (cut.py)")
     # reverse holds the clip's decoded frames; split, trim and loop pass references to the same
     # frames, so the peak is about one clip (measured: the same max RSS as a plain reverse)
-    bytes_per_frame = v["width"] * v["height"] * 1.5 * (2 if (v.get("bit_depth") or 8) > 8 else 1)
-    held = bytes_per_frame * frames
-    if held > 2 * 1024 ** 3:
+    held = held_frames_bytes(v, frames)
+    if held > HELD_FRAMES_WARN_BYTES:
         warn(f"--boomerang holds about {held / 1024 ** 3:.1f} GiB of decoded frames in memory "
              f"({frames} frames of {v['width']}x{v['height']}) -- cut the clip shorter first (cut.py) if RAM is tight",
              "memory_heavy", bytes=int(held))
@@ -160,7 +159,12 @@ def _seamless_unit_cmd(meta, src: str, unit: str, rate: str, frames: int, fade_f
     if has_audio:
         # acrossfade writes nothing when its first input is exactly the fade long (FFmpeg 6.1 and
         # 7.1, measured), so the fade is built by hand: tail faded out + head faded in, summed
-        graph += (f";[0:a:0]aresample=async=1:first_pts=0,apad,atrim=end={length:.6f},asplit=3[at][ah][ab];"
+        # the sound is shifted by the picture's start, the constant setpts=PTS-STARTPTS takes off the
+        # picture: rebased to its own start (aresample's first_pts=0 alone), a picture that starts
+        # 0.2 s after its sound came out 200 ms behind it in every repeat (A168)
+        v0 = stream_starts(meta)[0]
+        graph += (f";[0:a:0]atrim=start={v0:.6f},asetpts=PTS-{v0:.6f}/TB,aresample=async=1:first_pts=0,"
+                  f"apad,atrim=end={length:.6f},asplit=3[at][ah][ab];"
                   f"[at]atrim=start={cut:.6f},asetpts=PTS-STARTPTS,afade=t=out:d={fade:.6f}:curve=tri[ta];"
                   f"[ah]atrim=end={fade:.6f},asetpts=PTS-STARTPTS,afade=t=in:d={fade:.6f}:curve=tri[ha];"
                   f"[ta][ha]amix=inputs=2:normalize=0:duration=longest[xa];"

package/scripts/metadata.py

@@ -35,6 +35,7 @@ from _common import (guard_sidecar, add_common, apply_common, default_output, de
                      die, emit, ffmpeg_base, fmt_chapter_time, info, propose_chapters, time_arg, probe, run,
                      STATE, read_text_or_die)
 from _common.emit import input_length
+from _common.runner import carried_stream_maps
 
 CHAPTER_CONTAINERS = {".mp4", ".m4v", ".m4a", ".mov", ".mkv", ".mka", ".webm"}
 TAG_KEYS = ("title", "artist", "album", "comment", "date", "genre")
@@ -267,6 +268,9 @@ def main() -> int:
         cmd += ["-map", "0", "-map_metadata", "0", "-map_chapters", "-1"]
     else:
         cmd += ["-map", "0", "-map_metadata", "0", "-map_chapters", "0"]
+    # not the source's MP4/MOV chapter track: the muxer writes one from the chapters it is given,
+    # and the copy was a stray data track holding the old titles (A173)
+    cmd += carried_stream_maps(args.input, output, attachments=False)
     for key, value in tags.items():
         cmd += ["-metadata", f"{key}={value}"]
     cmd += ["-c", "copy"]

package/scripts/redact.py

@@ -101,7 +101,14 @@ def main() -> int:
                                (square + "," if square else "") + f"delogo=x={args.x}:y={args.y}:w={args.width}:h={args.height}",
                                "-map", "0:v:0"]
     else:
-        crop = f"crop={args.width}:{args.height}:{args.x}:{args.y}"
+        # exact=1: crop rounds an odd x/y down to the chroma grid of a 4:2:0 frame otherwise, and
+        # overlay always does, so an odd rectangle was taken from and put back one pixel up and
+        # left (its last column and row left as they were, one outside it changed: A170). The
+        # patch is taken exactly, given a transparent first column/row where x/y is odd, and put
+        # at the even position before it: the luma inside the rectangle is replaced, the luma
+        # outside is not (the chroma pair on an odd edge is shared, so it is half mixed)
+        crop = f"crop={args.width}:{args.height}:{args.x}:{args.y}:exact=1"
+        ox, oy = args.x % 2, args.y % 2
         if args.mode == "blur":
             # boxblur refuses a radius above half the plane: the chroma planes of 4:2:0 are half-size,
             # so they get their own (halved) radius; a 30 px region with the default 20 used to fail
@@ -110,7 +117,12 @@ def main() -> int:
             region = f"{crop},boxblur={radius}:{radius}:{chroma}:{radius}"
         else:
             region = f"{crop},scale={max(1, args.width // args.block_size)}:{max(1, args.height // args.block_size)}:flags=neighbor,scale={args.width}:{args.height}:flags=neighbor"
-        fc = f"[0:v]{square + ',' if square else ''}split=2[base][region];[region]{region}[patched];[base][patched]overlay={args.x}:{args.y}{overlay_format(meta)}[out]"
+        if ox or oy:
+            deep = overlay_format(meta)
+            region += (f",format=yuva444p{'10le' if deep else ''},"
+                       f"pad={args.width + 2 * ox}:{args.height + 2 * oy}:{ox}:{oy}:color=black@0")
+        fc = (f"[0:v]{square + ',' if square else ''}split=2[base][region];[region]{region}[patched];"
+              f"[base][patched]overlay={args.x - ox}:{args.y - oy}{overlay_format(meta)}[out]")
         cmd = ffmpeg_base() + ["-i", args.input, "-filter_complex", fc, "-map", "[out]"]
     if has_audio:
         cmd += ["-map", f"0:a:{args.audio_stream}?"]

package/scripts/render.py

@@ -74,7 +74,7 @@ from typing import Any, Dict, List, Optional, Sequence
 
 from export import PRESETS, PLATFORM_OF
 from _platforms import PLATFORMS, caption_defaults, resolve as resolve_platform
-from _common import guard_sidecar, STATE, add_common, aspect_ratio, brand_caption_style, load_brand, apply_common, child_args, die, emit, info, option_args, probe, require_tool, run, run_tool, place_output, refuse_output_is_input, _check_existing_output, _check_output_path, fingerprint, PLAN_VERSION, ffmpeg_version, X264_PRESETS
+from _common import guard_sidecar, STATE, add_common, aspect_ratio, brand_caption_style, load_brand, apply_common, child_args, die, emit as _emit, info, option_args, probe, require_tool, run, run_tool, place_output, refuse_output_is_input, _check_existing_output, _check_output_path, fingerprint, PLAN_VERSION, ffmpeg_version, X264_PRESETS
 from _common.runner import HW_ENV, HW_FORCED_ENV, add_hw_orchestrator_args, child_exit_code, found_exe, kept_clause, kept_deliverables, mark_delivered, owned_identity, read_json, remember_written
 from _common.emit import absorb_stage, audit, record_fallback, record_skip, refuse, warn
 from _common.decision import rebase_project_paths
@@ -691,6 +691,59 @@ def check_snap_to(snap: Any, label: str) -> None:
 
 _LAST_DOC: Dict[str, Any] = {}   # the JSON document the most recent sh() child printed
 
+# source_carry for a render (A255): the one picture/sound source of a project with one, and what
+# each stage that ran said about the start timecode ("kept", "dropped", None: a stage that compared
+# nothing, "unknown": a cache hit whose entry did not keep it). main() resets both.
+PROJECT_SOURCE: Dict[str, Any] = {"src": None, "timecode": []}
+
+
+def _timecode_verdict(doc: Any) -> Optional[str]:
+    """What a stage's document says about the start timecode: "kept", "dropped", or None when its
+    source_carry compared none."""
+    carry = doc.get("source_carry") if isinstance(doc, dict) else None
+    if not isinstance(carry, dict):
+        return None
+    return "dropped" if "timecode" in (carry.get("dropped") or []) else "kept" if "timecode" in (carry.get("kept") or []) else None
+
+
+def project_source(proj: Dict[str, Any], rel) -> Optional[str]:
+    """The project's single picture/sound source -- its clips all one file, and no music,
+    replacement or effects track, no video layer and no audiogram picture beside it -- or None,
+    when the output mixes several (source_carry is then not compared, as for any tool with two
+    sources)."""
+    srcs = {os.path.realpath(rel(c["src"])) for c in proj.get("clips") or [] if isinstance(c, dict) and isinstance(c.get("src"), str)}
+    audio = proj.get("audio") if isinstance(proj.get("audio"), dict) else {}
+    others = [audio.get(k) for k in ("music", "replace", "effects") if audio.get(k)]
+    overlays = proj.get("overlays") if isinstance(proj.get("overlays"), list) else []
+    others += [ov.get("video") for ov in overlays if isinstance(ov, dict) and ov.get("video")]
+    if proj.get("audiogram"):
+        others.append("audiogram")  # the picture is the waveform over an image, not the clip's
+    return next(iter(srcs)) if len(srcs) == 1 and not others else None
+
+
+def emit(output: Optional[str], **extra: Any) -> None:
+    """emit(), with render.py's source_carry: the stages run as children, so this process never
+    probed the project's source as an input and its result carried no source_carry at all, even
+    for a one-clip render that lost the source's subtitle track (A255). The source is probed here
+    (after the stages' intermediates, which are not sources), so emit() compares it with the
+    delivered file. A stage that moves the picture's start writes the label of the frame it starts
+    on, which is not the source's: the timecode counts as kept when every stage that compared it
+    kept it, as dropped when one dropped it, and is compared with the source's own label when no
+    stage said (nothing ran, or a cache entry written before stages' source_carry was kept)."""
+    src = PROJECT_SOURCE.get("src")
+    if src and output and not STATE.dry_run and os.path.isfile(src) and os.path.isfile(output) \
+            and os.path.realpath(src) != os.path.realpath(output) and "source_carry" not in extra:
+        STATE.first_input, STATE.video_inputs, STATE.audio_inputs = None, set(), set()
+        probe(src)
+        said = PROJECT_SOURCE["timecode"]
+        if "dropped" in said:
+            STATE.expected_timecode = ""
+        elif "kept" in said and "unknown" not in said:
+            STATE.expected_timecode = (probe(output, role="output").get("timecode") or {}).get("value") or ""
+        else:
+            STATE.expected_timecode = None
+    _emit(output, **extra)
+
 
 def _refuse_uncached_earlier_stage(stage: str) -> None:
     """--from STAGE promises the earlier stages come from the cache. When one does not, say so
@@ -783,6 +836,7 @@ def sh(script: str, *argv: Any, extra: List[str] = None, stage: str = None) -> s
             code=int(doc.get("exit_code") or 1), kind=err.get("kind") or "input", stage=script, error_extra=error_extra, **extra_fields)
     _LAST_DOC.clear()
     _LAST_DOC.update(doc if isinstance(doc, dict) else {})
+    PROJECT_SOURCE["timecode"].append(_timecode_verdict(doc))
     absorb_stage(Path(script).stem, doc)  # a stage's GPU facts (ran on VideoToolbox, fell back and why) and its diagnostics reach this result
     out_path = str(doc.get("output") or "")
     if not STATE.dry_run:
@@ -981,6 +1035,10 @@ def cache_lookup(stage: str, key: str, dest: str, tool: Optional[str] = None) ->
         shutil.copy2(art, dest)     # ... and a copy where it does not. Never a move: the cache
     CACHE["saved_seconds"] += float(meta.get("seconds") or 0.0)
     result = meta.get("result")
+    # what the stage said about the start timecode, for render's source_carry; an entry written
+    # before its source_carry was kept does not say
+    PROJECT_SOURCE["timecode"].append(_timecode_verdict(result) if isinstance(result, dict) and "source_carry" in result
+                                      else "unknown")
     if isinstance(result, dict):
         absorb_stage(tool or stage, dict(result, status="completed", dry_run=False))  # tagged as the stage's tool, as a live run is
     else:
@@ -994,7 +1052,9 @@ def _stage_result(doc: Any) -> Dict[str, Any]:
     """What a cache entry keeps of the stage's own --json document, replayed on a hit."""
     if not isinstance(doc, dict):
         return {}
-    return {k: doc[k] for k in ("verified", "verification", "notes", "diagnostics") if k in doc}
+    kept = {k: doc[k] for k in ("verified", "verification", "notes", "diagnostics") if k in doc}
+    kept["source_carry"] = doc.get("source_carry")  # None too: the stage compared nothing (render's source_carry)
+    return kept
 
 
 def cache_store(stage: str, key: str, produced: str, seconds: float, doc: Any = None) -> None:
@@ -1472,6 +1532,7 @@ def main() -> int:
     add_hw_orchestrator_args(ap)
     args = ap.parse_args()
     apply_common(args)
+    PROJECT_SOURCE.update(src=None, timecode=[])
     STATE.audit_log = os.path.abspath(args.audit_log) if args.audit_log else None
 
     if args.list_templates:
@@ -1650,6 +1711,7 @@ def main() -> int:
     CACHE.clear()
     CACHE.update(_fresh_cache())
     CONTENT_KEYED.clear()
+    PROJECT_SOURCE.update(src=project_source(proj, rel), timecode=[])
     if args.cache:
         cdir = Path(args.cache)
         try:

package/scripts/reverse.py

@@ -17,7 +17,8 @@ import sys
 
 from _common import add_common, apply_common, aac_args, cfr_args, default_output, die, emit, ffmpeg_base, info, probe, run, video_args, X264_PRESETS, fmt_secs
 from _common.emit import warn
-from _common.decision import av_clip_length, av_trim, frame_durations, frame_rate, stream_starts
+from _common.decision import (HELD_FRAMES_WARN_BYTES, av_clip_length, av_trim, delivered_rate, frame_durations, frame_rate,
+                              held_frames_bytes, stream_starts)
 
 
 def main() -> int:
@@ -37,10 +38,16 @@ def main() -> int:
     has_audio = bool(meta.get("audio")) and not args.no_audio
 
     output = args.output or default_output(args.input, "reverse")
-    if (meta.get("duration") or 0) > 60:
-        warn(f"reverse buffers every decoded frame in memory; {meta['duration']:.0f}s of "
-             f"{meta['video']['width']}x{meta['video']['height']} can exhaust RAM -- cut the part to reverse first (cut.py)",
-             "memory_heavy", duration=meta["duration"])
+    # keyed on what is held (every decoded frame), not on the length alone (A174): the estimate
+    # loop.py --boomerang warns from, over the frames of the picture's length at its rate
+    v = meta["video"]
+    vdur = v.get("duration") or meta.get("duration") or 0.0
+    frames = v.get("nb_frames") or vdur * (frame_rate(meta) or v.get("fps") or 30.0)
+    held = held_frames_bytes(v, frames)
+    if held > HELD_FRAMES_WARN_BYTES:
+        warn(f"reverse holds about {held / 1024 ** 3:.1f} GiB of decoded frames in memory "
+             f"({vdur:.0f}s of {v['width']}x{v['height']}) -- cut the part to reverse first (cut.py) if RAM is tight",
+             "memory_heavy", duration=meta.get("duration"), bytes=held)
     cmd = ffmpeg_base() + ["-i", args.input]
     if has_audio:
         # Both streams are reversed about one end (#409); each reversed about its own end put a sound
@@ -55,14 +62,20 @@ def main() -> int:
         # setpts: from FFmpeg 7.0 setpts leaves its output's frame rate unknown and its frames'
         # durations 0, so a tpad after it clones nothing (the picture stayed 0.6 s short on 7.1);
         # the closing fps gives the frames their durations back (frame_durations).
-        rate = frame_rate(meta) or meta["video"].get("fps") or 30.0
+        # the rate the encoder line delivers (cfr_args: a VFR source is conformed to its average
+        # rate), so the graph's closing fps and the output's -r are one grid: the graph closed on
+        # r_frame_rate and -r then resampled it, 51 frames for 49 that ran 81 ms past the sound (A234)
+        # The trim that drops the hold's spare clones stays on the source's own grid (half a frame
+        # of r_frame_rate before the end): half a delivered frame cut a real last frame that sits
+        # nearer the end than that, and reverse then opened on the one before it.
+        rate = delivered_rate(meta) or frame_rate(meta) or meta["video"].get("fps") or 30.0
         length = av_clip_length(meta, rate)
         vlen = meta["video"].get("duration") or length
         end = math.ceil(length * rate - 1e-6) / rate
         vtrim, atrim = av_trim(stream_starts(meta)[0], None)
         cmd += ["-filter_complex",
                 f"[0:v:0]tpad=stop_mode=clone:stop_duration={max(0.0, end - vlen) + 2 / rate:.6f},{vtrim},"
-                f"trim=end={end - 0.5 / rate:.6f},reverse,{frame_durations(meta, rate)}[v];"
+                f"trim=end={end - 0.5 / max(rate, frame_rate(meta) or rate):.6f},reverse,{frame_durations(meta, rate)}[v];"
                 f"[0:a:0]{atrim},apad=whole_dur={end:.6f},atrim=end={end:.6f},areverse,asetpts=N/SR/TB[a]",
                 "-map", "[v]", "-map", "[a]"]
     else:

package/scripts/straighten.py

@@ -80,9 +80,20 @@ def main() -> int:
         dw, dh = display_size(meta["video"])
         aspect = max(dw / dh, dh / dw) if dw and dh else 1.0
         s = abs(math.cos(radians)) + aspect * abs(math.sin(radians))
-        # crop dimensions must round down to even (4:2:0 chroma); trunc(.../2)*2 floors to the
-        # nearest even value instead of leaving an odd width/height that the encoder would refuse.
-        rotate = f"scale=iw*{s:.8f}:ih*{s:.8f},rotate={radians:.8f},crop=trunc(iw/{s:.8f}/2)*2:trunc(ih/{s:.8f}/2)*2"
+        # The window is the displayed frame's own size, to even (4:2:0 chroma), and the scaled frame
+        # is rounded UP to even so it still covers it. Scaling to iw*s and cropping back to
+        # trunc(iw/s/2)*2 lost to two roundings: 1920x1080 came out 1918x1078, and the scale's
+        # rounding left a non-square SAR such as 6112:6111 (A235).
+        cw, ch = (dw // 2 * 2, dh // 2 * 2) if dw and dh else (0, 0)
+        if cw and ch:
+            # the margin on each axis is a multiple of 4, so the centred crop's offset is even:
+            # crop floors an odd one to the chroma grid, which moved the window a pixel up and
+            # left and could bring the fill into the top-left corner
+            sw, sh = (c + math.ceil(max(0.0, c * s - c) / 4) * 4 for c in (cw, ch))
+            rotate = (f"scale={sw}:{sh},setsar=1,"
+                      f"rotate={radians:.8f},crop={cw}:{ch},setsar=1")
+        else:  # a dry run's pending input has no size yet: the old expression, planned only
+            rotate = f"scale=iw*{s:.8f}:ih*{s:.8f},rotate={radians:.8f},crop=trunc(iw/{s:.8f}/2)*2:trunc(ih/{s:.8f}/2)*2"
 
     # a rotation of non-square pixels is a shear on screen: the picture is squared at its
     # display aspect first (#411)