ffmpeg-skill 3.2.3 → 3.3.0

package/README.md

@@ -20,6 +20,7 @@ No cloud · No API keys · Python standard library</p>
 
 <p align="center">
   <a href="https://github.com/kajisho5/ffmpeg-skill/actions/workflows/ci.yml"><img src="https://github.com/kajisho5/ffmpeg-skill/actions/workflows/ci.yml/badge.svg" alt="tests"></a>
+  <a href="https://scorecard.dev/viewer/?uri=github.com/kajisho5/ffmpeg-skill"><img src="https://api.scorecard.dev/projects/github.com/kajisho5/ffmpeg-skill/badge" alt="OpenSSF Scorecard"></a>
   <a href="https://www.npmjs.com/package/ffmpeg-skill"><img src="https://img.shields.io/npm/v/ffmpeg-skill" alt="npm"></a>
   <a href="#ffmpeg-compatibility"><img src="https://img.shields.io/badge/ffmpeg-6.1%20%7C%207.1%20%7C%208%20%7C%209%20tested-orange" alt="FFmpeg 6.1, 7.1, 8 and 9 tested in CI"></a>
   <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-green" alt="MIT"></a>
@@ -595,6 +596,16 @@ claude plugin marketplace add kajisho5/ffmpeg-skill                    # older v
 claude plugin install ffmpeg-skill@ffmpeg-skill                        # then install from it
 ```
 
+The same repository installs as a plugin in two more hosts (checked against Codex CLI 0.167 and Gemini CLI 0.68):
+
+```bash
+codex plugin marketplace add kajisho5/ffmpeg-skill     # Codex: add the marketplace,
+codex plugin add ffmpeg-skill@ffmpeg-skill             # then the plugin
+gemini extensions install https://github.com/kajisho5/ffmpeg-skill   # Gemini CLI
+```
+
+Those hosts find a plugin's skill only at `skills/ffmpeg-skill/SKILL.md`, a generated copy of the root `SKILL.md` (`.github/scripts/build_plugin_skill.py`; a test fails when it is stale). A Cursor plugin manifest (`.cursor-plugin/plugin.json`) is in the repository for the Cursor Marketplace; it follows Cursor's reference and has not been through their review yet.
+
 The plugin namespaces the skill as `ffmpeg-skill:ffmpeg-skill`. The manifests are [.claude-plugin/plugin.json](.claude-plugin/plugin.json), whose version follows every release automatically, and [.claude-plugin/marketplace.json](.claude-plugin/marketplace.json), which lists the plugin from the repository root. Before 2.17.1 the README's one-line `claude plugin install kajisho5/ffmpeg-skill` could not work, because there was no marketplace file.
 
 Without Node: clone this repository and copy `SKILL.md`, `package.json`, `scripts/`, `templates/`, `references/`, `docs/` and `mcp/` into your agent's skills directory (the same set `npx ffmpeg-skill` installs; without `templates/` no `--template` renders, and without `package.json` the contract reports its version as unknown).
@@ -629,7 +640,7 @@ FFmpeg itself:
 
 ## Stability
 
-3.x keeps every tool name, CLI argument, JSON output key and exit code working: nothing is removed or renamed, and nothing optional becomes required, until 4.0. The full list of what is promised and what is not, and the three-step deprecation policy, is in [docs/contract.md](docs/contract.md#stability-guarantee-3x). It is enforced by a test that pins every tool's argument names against a snapshot, so a breaking change fails CI instead of slipping into a patch. 2.0.0 made the five changes announced since 1.10.0 -- `--crf` removed in favour of `--quality` (except on `export.py`, whose preset chooses the encoder), an existing output refused without `--overwrite`, `probe`'s `hdr` narrowed to a real HDR signal, `json`/`progress` out of the MCP schema, the `result_v2` preview withdrawn -- listed with what to change in [docs/contract.md](docs/contract.md#what-20-changed) and under `removed` in `contract --json`. 3.0.0 is the second break: it removed FFmpeg 5.x and Python 3.9 (announced in 2.14.0 and 2.10.9), made `cut.py` keep an `.mp4`/`.mov` copy's edit list, keep an SDR HEVC source HEVC and use `--vfr-guard sampled` by default (`--no-edit-list`, `--no-keep-hevc` and `--vfr-guard average` restore 2.x), and changed what `cut.py`'s `precision` (now the least exact segment's) and `keyframe_snapped` (now equal to `start_snapped`) mean (`contract_version` 2.0) -- see [docs/contract.md](docs/contract.md#what-30-changed).
+3.x keeps every tool name, CLI argument, JSON output key and exit code working: nothing is removed or renamed, and nothing optional becomes required, until 4.0. The full list of what is promised and what is not, and the three-step deprecation policy, is in [docs/contract.md](docs/contract.md#stability-guarantee-3x). It is enforced by a test that pins every tool's argument names against a snapshot, so a breaking change fails CI instead of slipping into a patch. Releases are batched: related fixes and features ship together as one version rather than one version per merged pull request, so a dependent project sees fewer, larger steps. Pin a tagged version, not `main`. 2.0.0 made the five changes announced since 1.10.0 -- `--crf` removed in favour of `--quality` (except on `export.py`, whose preset chooses the encoder), an existing output refused without `--overwrite`, `probe`'s `hdr` narrowed to a real HDR signal, `json`/`progress` out of the MCP schema, the `result_v2` preview withdrawn -- listed with what to change in [docs/contract.md](docs/contract.md#what-20-changed) and under `removed` in `contract --json`. 3.0.0 is the second break: it removed FFmpeg 5.x and Python 3.9 (announced in 2.14.0 and 2.10.9), made `cut.py` keep an `.mp4`/`.mov` copy's edit list, keep an SDR HEVC source HEVC and use `--vfr-guard sampled` by default (`--no-edit-list`, `--no-keep-hevc` and `--vfr-guard average` restore 2.x), and changed what `cut.py`'s `precision` (now the least exact segment's) and `keyframe_snapped` (now equal to `start_snapped`) mean (`contract_version` 2.0) -- see [docs/contract.md](docs/contract.md#what-30-changed).
 
 ## Development
 

package/bin/install.js

@@ -14,6 +14,7 @@
  *   npx ffmpeg-skill --uninstall     # remove from the selected targets
  *   npx ffmpeg-skill contract --json # machine-readable execution contract (see docs/contract.md)
  *   npx ffmpeg-skill doctor [--json] # which required ffmpeg capabilities this machine has
+ *   npx ffmpeg-skill mcp              # stdio MCP server (python3 mcp/server.py); registry clients pass `mcp`
  *
  * Already installed? re-run `npx ffmpeg-skill` to refresh ~/.claude/skills/ffmpeg-skill
  * Copies are not updated automatically.
@@ -98,7 +99,8 @@ function warnMissingPython(platform, spawn, warn) {
 }
 
 function main() {
-// `contract` / `doctor` are answered by scripts/_contract.py; everything else installs.
+// `contract` / `doctor` are answered by scripts/_contract.py. `mcp` is the stdio server
+// (server.json's packageArguments). Everything else installs.
 if (args[0] === 'contract' || args[0] === 'doctor') {
   const py = runWithPython([path.join(ROOT, 'scripts', '_contract.py'), ...args], process.platform, spawnSync);
   if (py.missing) {
@@ -107,6 +109,14 @@ if (args[0] === 'contract' || args[0] === 'doctor') {
   }
   process.exit(py.error ? 127 : (py.status == null ? 1 : py.status));
 }
+if (args[0] === 'mcp') {
+  const py = runWithPython([path.join(ROOT, 'mcp', 'server.py'), ...args.slice(1)], process.platform, spawnSync);
+  if (py.missing) {
+    console.error(`error: could not find a Python 3.10+ interpreter (tried: ${py.candidates.join(', ')}). Install Python 3.10+ and ensure it is on PATH.`);
+    process.exit(127);
+  }
+  process.exit(py.error ? 127 : (py.status == null ? 1 : py.status));
+}
 
 const home = os.homedir();
 const targets = [];

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.2.3`) | any release |
+| `skill.version` | the npm / package.json version (`3.3.0`) | 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.2.3", "execution_mode": "local", "kind": "execution",
+  "skill": {"id": "ffmpeg-skill", "version": "3.3.0", "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"},
@@ -918,6 +918,19 @@ that is so: once a tool has written its deliverable and runs a further step on i
 says it is kept without the step that was stopped, and the document carries it as `output`
 (3.1.6, #415).
 
+**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`. 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
+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
+`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.
+
 **Diagnostics.** What a run decided on its own -- a warning, a fallback it took, a step it
 skipped -- is recorded as it happens (a stderr line too) and lands in the document as
 `diagnostics: {warnings, fallbacks, skipped}`, each entry `{code, message, ...facts}`; it is

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "ffmpeg-skill",
-  "version": "3.2.3",
+  "version": "3.3.0",
+  "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": [
     "ffmpeg",

package/references/gotchas.md

@@ -54,6 +54,13 @@ on a stream copy as on a re-encode
 (`cut.py` reports it: `dropped_audio_streams`, an `audio_tracks_dropped` warning). Keep ProRes masters
 at source colour: `export.py --preset prores` does not retag.
 
+What else the source carried is compared on every write: `source_carry: {kept, dropped}` lists
+subtitles, chapters, a cover picture, surround channels, `creation_time`, the audio language tag
+and the start timecode, and a lost subtitle track, chapter list, cover picture or surround layout
+is a `source_items_dropped` warning. Read it before telling the user the file is complete; to
+carry the items over, use the tool that keeps them (`export.py` keeps subtitle tracks,
+`metadata.py` writes chapters and tags).
+
 Re-encoding an HDR (iPhone, HDR10) source through an SDR path flattens the
 colours. The scripts keep HDR; if you hand-write ffmpeg (never do — see SKILL.md),
 do not tag BT.709 on BT.2020 pixels.

package/scripts/_common/color.py

@@ -69,8 +69,11 @@ def is_rgb(meta: Optional[Dict[str, Any]]) -> bool:
     return bool(_RGB_PIX_FMT_RE.match(str(((meta or {}).get("video") or {}).get("pix_fmt") or "")))
 
 
-_MATRIX_FILTER_RE = re.compile(r"^(?:colorspace=ispace=(?:%s):iprimaries=bt709:itrc=bt709:space=bt709:primaries=bt709:trc=bt709|(?:format=rgb24,)?%s)$"
-                               % ("|".join(NON_BT709_MATRICES), re.escape(rgb_to_bt709_filter())))
+# An odd-sized BT.601 source is padded to even for the colorspace filter and cropped back to its
+# own size after it (bt709_matrix_filter): both wrap the conversion in the one -vf the merge finds.
+_EVEN_PAD = "pad=ceil(iw/2)*2:ceil(ih/2)*2:0:0,"
+_MATRIX_FILTER_RE = re.compile(r"^(?:(?:%s)?colorspace=ispace=(?:%s):iprimaries=bt709:itrc=bt709:space=bt709:primaries=bt709:trc=bt709(?:,crop=iw-[01]:ih-[01]:0:0:exact=1)?|(?:format=rgb24,)?%s)$"
+                               % (re.escape(_EVEN_PAD), "|".join(NON_BT709_MATRICES), re.escape(rgb_to_bt709_filter())))
 _INPUT_VIDEO_REF = re.compile(r"\[(\d+):v(?::0)?\]")
 
 
@@ -102,7 +105,19 @@ def bt709_matrix_filter(meta: Optional[Dict[str, Any]]) -> Optional[str]:
         return ("format=rgb24," if v.get("pix_fmt") == "pal8" else "") + rgb_to_bt709_filter()
     if matrix not in NON_BT709_MATRICES:
         return None
-    return f"colorspace=ispace={matrix}:iprimaries=bt709:itrc=bt709:space=bt709:primaries=bt709:trc=bt709"
+    # the colorspace filter refuses an odd width or height outright ("Invalid odd size"), and a
+    # 4:2:0 JPEG can have one (a phone screenshot, #437). The frame is padded by one row and/or
+    # column, converted, and cropped back to its own size: no source pixel is lost or resampled
+    # (a 4:2:0 frame's chroma planes are the same size either way), so a caller's own crop or
+    # scale sees the frame it measured. Nothing changes for an even-sized source. FFmpeg rotates
+    # a rotated source before the graph, so the odd axis is read after the same swap.
+    w, h = int(v.get("width") or 0), int(v.get("height") or 0)
+    if int(v.get("rotation") or 0) % 180 == 90:
+        w, h = h, w
+    conv = f"colorspace=ispace={matrix}:iprimaries=bt709:itrc=bt709:space=bt709:primaries=bt709:trc=bt709"
+    if w % 2 or h % 2:
+        return f"{_EVEN_PAD}{conv},crop=iw-{w % 2}:ih-{h % 2}:0:0:exact=1"
+    return conv
 
 
 def bt709_label_filter(meta: Optional[Dict[str, Any]]) -> Optional[str]:

package/scripts/_common/emit.py

@@ -163,6 +163,74 @@ def _report_dropped_hdr10_metadata(meta: Dict[str, Any], ctx: "Context") -> None
         ctx.notes.append(note_line)
 
 
+# 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_TAGS = ("creation_time", "audio_language", "timecode")
+_CARRY_NAMES = {"subtitles": "subtitle track", "chapters": "chapters", "cover_art": "cover picture",
+                "audio_channels": "audio channels"}
+
+
+def source_carry(output: Optional[str], ctx: "Context", extra: Dict[str, Any]) -> "Optional[Dict[str, List[str]]]":
+    """What the first input carried besides its picture and sound, and whether the written file
+    still has it (#401): {"kept": [...], "dropped": [...]}, or None when the source had none of
+    it or the two files are not comparable. Measured on the written file, so the tool, encoder or
+    FFmpeg version that dropped it does not matter. A report, not a check: `verified` is not
+    touched. Not compared: two or more picture or sound sources (which one's items the output
+    should carry is the tool's choice), an output that is not a media file, and items bound to a
+    stream the output does not have at all (a sound-only extract has no subtitle track or
+    timecode to lose; a picture-only output has no audio channels). Audio channels are an item
+    only for a surround source (more than two)."""
+    from .probe import MEDIA_EXT, _STILL_EXT, carry_inventory
+    first = getattr(STATE, "first_input", None)
+    if not first or not output:
+        return None
+    # a tool that reads its own output back (cut.py measures the cut it wrote) probed it as an
+    # input too: that is not a second source
+    own = os.path.realpath(output)
+    if any(len(set(getattr(STATE, name, None) or ()) - {own}) > 1 for name in ("video_inputs", "audio_inputs")):
+        return None
+    ext = os.path.splitext(output)[1].lower()
+    if ext not in MEDIA_EXT or ext in _STILL_EXT:
+        return None  # a still, a contact sheet or an animated GIF holds none of these
+    src, out = carry_inventory(first[0]), carry_inventory(output)
+    if not src or not out or os.path.realpath(first[0]) == os.path.realpath(output):
+        return None
+    kept: List[str] = []
+    dropped: List[str] = []
+    for item in CARRY_CONTENT + CARRY_TAGS:
+        if not src.get(item):
+            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"]:
+            continue
+        if item in ("audio_channels", "audio_language") and not out["has_audio"]:
+            continue
+        (kept if out.get(item, 0) >= src[item] else dropped).append(item)
+    if not kept and not dropped:
+        return None
+    said = set()
+    if extra.get("dropped_non_av_streams") or any(w.get("code") == "non_av_streams_dropped" for w in ctx.fallbacks):
+        said.add("subtitles")  # the tool's own field already says the track went
+    loud = [i for i in dropped if i in CARRY_CONTENT and i not in said]
+    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")
+            else:
+                parts.append("its " + _CARRY_NAMES[i])
+        warn("the source carried " + ", ".join(parts) + " that this output does not have "
+             "(source_carry lists everything kept and dropped)",
+             "source_items_dropped", ctx=ctx, dropped=loud)
+        note_line = ctx.warnings[-1]["message"] if ctx.warnings else None
+        if note_line and note_line not in ctx.notes:
+            ctx.notes.append(note_line)
+    return {"kept": kept, "dropped": dropped}
+
+
 def refuse(kind: str, reason: str, msg: str, *, hint: Optional[str] = None, code: int = 1,
            ctx: "Optional[Context]" = None, extra: "Optional[Dict[str, Any]]" = None, **details: Any) -> "None":
     """die() for a refusal a caller has to act on: `error.reason` is a stable snake_case code for
@@ -710,6 +778,9 @@ def emit(output: Optional[str], *, ctx: "Optional[Context]" = None, **extra: Any
         meta = verify_output(output)  # dies (status: failed, kind: output) if the artifact is unusable
         _report_dropped_audio_tracks(meta, ctx)
         _report_dropped_hdr10_metadata(meta, ctx)
+        carry = source_carry(output, ctx, extra)
+        if carry and "source_carry" not in extra:
+            extra["source_carry"] = carry
     if ctx.json:
         doc: Dict[str, Any] = {"status": "completed", "output": output, "dry_run": ctx.dry_run, "commands": list(ctx.commands)}
         if meta:

package/scripts/_common/probe.py

@@ -402,9 +402,30 @@ def probe(path: str, role: str = "input") -> Dict[str, Any]:
                              (out.get("video") or {}).get("hdr10_static"))
     if role == "input" and out["timecode"].get("value") and getattr(STATE, "source_timecode", None) is None:
         STATE.source_timecode = (out["timecode"]["value"], duration)
+    # what a source carries besides its picture and sound, for emit()'s source_carry comparison:
+    # kept beside the probe, not in it, so no probe document changes
+    lang = (audio.get("tags") or {}).get("language") if audio else None
+    _CARRY[os.path.realpath(path)] = {
+        "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)),
+        "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,
+        "audio_channels": (_to_int(audio.get("channels")) or 0) if audio else 0,
+        "has_video": bool(video), "has_audio": bool(audio),
+    }
     return out
 
 
+_CARRY: Dict[str, Dict[str, Any]] = {}
+
+
+def carry_inventory(path: str) -> "Optional[Dict[str, Any]]":
+    """The carry-over items probe() last read off `path` (see emit()'s source_carry), or None."""
+    return _CARRY.get(os.path.realpath(path)) if path else None
+
+
 def _hdr10_static(ffprobe: str, path: str, stream: Dict[str, Any]) -> "Optional[Dict[str, Any]]":
     """A PQ stream's mastering display and content light level, from the stream (an mdcv/clli box,
     a Matroska colour element) or else its first frame (the HEVC SEI / AV1 metadata OBU): one

package/scripts/_common/runner.py

@@ -1067,9 +1067,14 @@ class _OutputLock:
 def _odd_dimension_retry(cmd: List[str], stderr: str) -> Optional[List[str]]:
     """An odd-sized source (641x359 screen captures, some 4:4:4 masters) fails every yuv420p
     encode with "width/height not divisible by 2" (sweep F8, 15 tools). Return the same command
-    with an even-dimension scale prepended to its -vf chain (or a new -vf when the command had
+    with an even-dimension scale appended to its -vf chain (or a new -vf when the command had
     none); None when the failure is something else or the graph is a -filter_complex the
-    caller has to fix itself."""
+    caller has to fix itself.
+
+    Appended, not prepended: what the encoder refuses is the frame the chain hands it, and a
+    chain can make an even frame odd again (squaring non-square pixels to 636x1401, a conversion
+    that restores the source's own size). Through 3.2.3 the scale went first, so caption.py on an
+    odd-sized clip retried and failed the same way (#438)."""
     if "not divisible by 2" not in stderr or EVEN_SCALE in cmd or any(EVEN_SCALE in a for a in cmd):
         return None
     if "-filter_complex" in cmd:
@@ -1077,7 +1082,7 @@ def _odd_dimension_retry(cmd: List[str], stderr: str) -> Optional[List[str]]:
     new = list(cmd)
     if "-vf" in new:
         i = new.index("-vf") + 1
-        new[i] = EVEN_SCALE + "," + new[i]
+        new[i] = new[i] + "," + EVEN_SCALE
         return new
     if "-c:v" in new and new[new.index("-c:v") + 1] == "copy":
         return None

package/scripts/_contract.py

@@ -472,6 +472,7 @@ DIAGNOSTIC_CODES = {
     # fonts and text
     "emoji_not_drawn": ("warnings", "caption.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; {count, reason}"),
     "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}"),
     "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"),
@@ -614,6 +615,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. 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"},
             "diagnostics": DIAGNOSTICS_SCHEMA}
     extra: Dict[str, Any] = {}
     if name == "check":

package/scripts/caption.py

@@ -75,6 +75,11 @@ __all__ = ["parse_srt", "write_srt", "transcribe", "whisper_word_timings", "die_
            "text_width_em"]
 
 ALIGN = {"bottom": 2, "top": 8, "center": 5, "bottom-left": 1, "bottom-right": 3, "top-left": 7, "top-right": 9}
+# libass reads a force_style Alignment in the legacy SSA numbering (1-3 bottom, 5-7 top, 9-11
+# middle), not the v4+ numpad one a Style line uses: only the bottom row is the same number in
+# both. Through 3.2.3 the SRT burn passed the numpad value, so --position top landed mid-left,
+# center top-left, top-left top-right (#436, measured on libass 0.17.1 and FFmpeg 9.0.2).
+FORCE_STYLE_ALIGN = {"bottom": 2, "top": 6, "center": 10, "bottom-left": 1, "bottom-right": 3, "top-left": 5, "top-right": 7}
 
 TIME_RE = re.compile(
     r"^\s*(?P<a>[\d:.,@]+)\s*(?:-->|-|–|to)\s*(?P<b>[\d:.,@]+)\s+(?P<text>.+)$"  # @ = the 1.9 @fps suffix
@@ -1750,7 +1755,7 @@ def main() -> int:
             f"Outline={args.outline:g}",
             f"Shadow={args.shadow:g}",
             f"Bold={-1 if args.bold else 0}",
-            f"Alignment={ALIGN[args.position]}",
+            f"Alignment={FORCE_STYLE_ALIGN[args.position]}",
             f"MarginV={args.margin}",
         ]
         force = ",".join(style).replace("\\", "\\\\").replace("'", "\\'")

package/scripts/stabilize.py

@@ -27,7 +27,7 @@ import sys
 import tempfile
 from pathlib import Path
 
-from _common import STATE, add_common, apply_common, aac_args, cfr_args, default_output, die, emit, escape_filter_path, ffmpeg_base, info, probe, require_tool, run, video_args, X264_PRESETS, run_analysis, dry_run_input_pending, fmt_secs
+from _common import STATE, add_common, apply_common, aac_args, cfr_args, default_output, die, emit, escape_filter_path, ffmpeg_base, info, probe, require_tool, run, video_args, X264_PRESETS, run_analysis, dry_run_input_pending, fmt_secs, record_fallback, EVEN_SCALE
 
 
 def main() -> int:
@@ -63,7 +63,18 @@ def main() -> int:
         trf_arg = escape_filter_path(trf)
 
         ffmpeg = require_tool("ffmpeg")
-        detect_vf = f"vidstabdetect=shakiness={args.shakiness}:result={trf_arg}"
+        # vid.stab asserts on an odd frame (ffmpeg aborts in pass 1, #438), so both passes see an
+        # even one. Recorded like the runner's own odd-size retry: the output is a pixel narrower
+        # or shorter than the source.
+        v = meta["video"]
+        w, h = int(v.get("width") or 0), int(v.get("height") or 0)
+        if int(v.get("rotation") or 0) % 180 == 90:
+            w, h = h, w
+        even = f"{EVEN_SCALE}," if (w % 2 or h % 2) else ""
+        if even:
+            record_fallback("source has odd dimensions; scaling to even before stabilizing (vid.stab needs it)",
+                            "odd_dimensions_scaled_even", output=output, scale=EVEN_SCALE)
+        detect_vf = f"{even}vidstabdetect=shakiness={args.shakiness}:result={trf_arg}"
         if args.tripod:
             # A frame number, not a boolean: frame 1 is the standard reference for "lock to
             # this fixed frame" (mirrors vidstabtransform's own tripod=1 below).
@@ -78,7 +89,7 @@ def main() -> int:
                 die(f"stabilization analysis (pass 1) failed:\n{proc.stderr.strip()[-1500:]}", kind="ffmpeg")
 
         crop_mode = {"keep": 0, "black": 1}[args.crop]
-        transform_vf = f"vidstabtransform=input={trf_arg}:smoothing={args.smoothing}:crop={crop_mode}:zoom={args.zoom:g}:optzoom=1"
+        transform_vf = f"{even}vidstabtransform=input={trf_arg}:smoothing={args.smoothing}:crop={crop_mode}:zoom={args.zoom:g}:optzoom=1"
         if args.tripod:
             # Equivalent to relative=0:smoothing=0 -- overrides --smoothing, since averaging a
             # camera path makes no sense once every frame is locked to one fixed reference.