ffmpeg-skill 3.2.3 → 3.4.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>
@@ -268,7 +269,7 @@ These are the rules the skill file gives the agent and the code enforces.
 |---|---|
 | `export.py` | Presets `youtube`, `youtube4k`, `reels`, `tiktok`, `shorts`, `linkedin`, `facebook`, `x`, `youtube-hdr` (HEVC Main10, source HDR tags kept), `youtube-av1`, `prores`, `dnxhr-lb`/`sq`/`hq`/`hqx`/`444`, the alpha masters `prores4444`/`prores4444xq`/`qtrle`/`vp9-alpha`/`hap-alpha` (alpha read back), `key-fill` (a switcher's fill + key pair), `h265`, `gif`, `copy`, all tagged BT.709 unless they carry HDR or are an editing master (`prores`, `dnxhr-*`: the source's tags kept, codec, profile and pixel format read back) (a BT.601-matrix or RGB source is converted to BT.709, not relabelled); `--normalize` meets the platform's loudness in the same call (`render.py` turns it on by default for platform presets) ; `--max-mb MB` fits the file under a size limit by a two-pass encode and measures it ; `--preset copy --repair` remuxes a damaged file (timestamps regenerated, corrupt packets dropped) and counts the errors before and after |
 | `proxy.py` | Small, low-bitrate proxy for downstream AI analysis/preview/editing decisions — resize by `--width`/`--scale`, proxy-grade `--quality` (default 30), `--fps`, `--no-audio`; not a delivery preset |
-| `check.py` | PASS / WARN / FAIL against YouTube, Shorts, Reels, TikTok, X, LinkedIn, Facebook, broadcast and podcast specs, from the same delivery table the export presets and templates read (podcast also reports chapter markers and channel count), with the fix for each failure and a `format` / `judgement` kind per row; `--content` adds black-frame, frozen-frame, silence, short audio-dropout, single-frame-flash and flat-first-frame rows ; `--compare REF` measures SSIM/PSNR against a reference; `--levels bt709\|ebu-r103` counts the luma and chroma samples outside the broadcast legal range, per clip and per window, with min/max Y/U/V; `--expect-identity` checks that the file is the one a run reported writing (`output_identity`) |
+| `check.py` | PASS / WARN / FAIL against YouTube, Shorts, Reels, TikTok, X, LinkedIn, Facebook, broadcast and podcast specs, from the same delivery table the export presets and templates read (podcast also reports chapter markers and channel count), with the fix for each failure and a `format` / `judgement` kind per row; `--content` adds black-frame, frozen-frame, silence, short audio-dropout, single-frame-flash and flat-first-frame rows ; `--compare REF` measures SSIM/PSNR against a reference, and with `--expect-changed SPAN\|none` fails when the picture changed outside the spans the caller declared; `--levels bt709\|ebu-r103` counts the luma and chroma samples outside the broadcast legal range, per clip and per window, with min/max Y/U/V; `--expect-identity` checks that the file is the one a run reported writing (`output_identity`) |
 | `report.py` | Single-file HTML delivery report: before/after sheets, media facts, loudness, compliance, the commands run; `--pack` renders a social pack table |
 
 **Orchestration**
@@ -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/SKILL.md

@@ -155,7 +155,7 @@ Variants, caveats and extra flags per row: `references/requests.md`.
 | "the recording is corrupted" | `export.py in.mp4 --preset copy --repair` |
 | "a small proxy file" | `proxy.py in.mp4 --width 640` |
 | "is this OK to upload?" | `check.py final.mp4 --platform reels` |
-| "how much quality was lost" | `check.py final.mp4 --compare master.mp4` |
+| "how much quality was lost" / "did anything else change?" | `check.py final.mp4 --compare master.mp4` / `check.py new.mp4 --compare old.mp4 --expect-changed 12-18` (or `none`) |
 | "is it broadcast legal?" | `check.py final.mp4 --levels ebu-r103` (clamp: `color.py in.mp4 --correct --legalize ebu-r103`) |
 | "send me a summary of what you did" | `report.py --before raw.mov --after final.mp4 -o report.html` |
 | "title card", "Ken Burns on a photo" | `insert.py title.png --duration 3` (`--zoom in --pan right`) |

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.4.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.4.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"},
@@ -231,7 +231,9 @@ the loudness pass or, when loudness is skipped, one volumedetect pass). `check -
 (opt-in; render.py `"check": {"content": true}`) adds `black`, `frozen` and `silence` rows
 from one decode pass, `dropouts` (2.17) from one audio-only pass, and `flashes` and `first frame` (2.23) from one
 video-only pass and a one-frame decode; without it the row set is unchanged.
-`--compare REF` adds `similarity` (SSIM/PSNR against a reference) and `--expect-identity SIZE:MTIME_NS`
+`--compare REF` adds `similarity` (SSIM/PSNR against a reference); with it, `--expect-changed
+SPAN[@X,Y,W,H]|none` adds `change_scope`, which FAILs on a change outside the declared spans and when
+the two files could not be compared, and WARNs when a declared span did not change. `--expect-identity SIZE:MTIME_NS`
 adds `identity`, against the `output_identity` every writing tool reports (2.24). `--levels
 bt709|ebu-r103` adds `legal levels` (the share of luma and chroma samples outside the legal range,
 counted in every frame; FAIL when one frame passes `--levels-tolerance`, 1 %) and the `levels`
@@ -918,6 +920,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.4.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/references/scripts.md

@@ -1210,7 +1210,7 @@ measurements that combine with each other and with `--beats`/`--highlights`:
 
 ### check.py — pre-delivery compliance
 ```
-check.py INPUT --platform youtube|shorts|reels|tiktok|x|linkedin|facebook|broadcast|podcast|custom [--no-loudness] [--content] [--compare REF] [--levels bt709|ebu-r103 [--levels-window S] [--levels-tolerance PCT]] [--expect-identity SIZE:MTIME_NS] [--json]
+check.py INPUT --platform youtube|shorts|reels|tiktok|x|linkedin|facebook|broadcast|podcast|custom [--no-loudness] [--content] [--compare REF [--expect-changed SPAN[@X,Y,W,H]|none]... [--change-floor N]] [--levels bt709|ebu-r103 [--levels-window S] [--levels-tolerance PCT]] [--expect-identity SIZE:MTIME_NS] [--json]
          [--max-duration S] [--aspect 9:16] [--lufs -14] [--tp -1] [--max-mb N]
 ```
 PASS/WARN/FAIL per check with the script that fixes it. Run it as the final
@@ -1239,6 +1239,25 @@ someone else's file. `--compare REF` (2.24) measures the picture against a refer
 the worst frame and its time, and the mean PSNR (`identical` when every pixel matches); WARN under a
 mean SSIM of 0.98. Frames of another size are not compared (WARN, "not compared"); a different frame
 count is compared pair by pair and named in `notes`, since a dropped frame shifts every later pair.
+`--expect-changed` (with `--compare`) declares where the picture is allowed to differ from the
+reference, and a `change_scope` row grades the measurement against it: `--expect-changed 12-18`
+(a span in this file's time, both ends included, repeatable), `12-18@0,880,1920,200` (only that
+rectangle of displayed pixels during the span) or `none`. A change anywhere else is a FAIL with
+its span, frame count and place, and a `look.py --compare` command at its start; a declared span
+in which nothing changed is a WARN (the edit probably did not apply); two files that are not
+encoded alike (codec, pixel format or frame rate) are a WARN and a note. **When the two cannot be
+compared (another frame size, another frame count, an unreadable frame count or a failed pass) the
+row is FAIL**, since "not measured" must not read as "nothing else changed". The measure: both
+pictures as 8-bit RGB, subtracted, each frame area-scaled to 32x18 tiles; a tile changed when its
+largest channel is above the floor (`--change-floor`, default 24 of 255). The JSON
+`change_scope` document has `declared`, `observed`, `undeclared`, `declared_unchanged`, `floor`,
+`tile`, `frames` and `quiet_peak` (the largest tile that stayed under the floor: how close the
+unchanged part came). Limits: a change much smaller than a tile is diluted (a full-contrast
+change needs about a tenth of a tile, 19x19 px at 1080p); a faint shift over the whole picture
+stays under the floor in every tile, and `similarity` is the row for that; it compares the
+picture only; an edit that changes the length cannot be paired and FAILs as not compared. Compare
+two renders made with the same encoder settings: a different preset alone moved every frame's
+largest tile to 11 in the measurements behind the default.
 `--content` (opt-in, one decode pass) adds three rows: `black` (share of the duration that is
 black: WARN > 10%, FAIL >= 95%), `frozen` (longest frozen span: WARN > max(3 s, 30% of the
 duration), FAIL when it covers >= 95%, i.e. the whole video) and `silence` (share below

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/decision.py

@@ -179,8 +179,8 @@ def parse_time(value: str, fps: Optional[float] = None) -> float:
             fps = float(rate)
         except ValueError:
             raise ValueError(f"bad @fps suffix in '{value}' (expected a number such as @29.97)")
-        if fps <= 0:
-            raise ValueError(f"bad @fps suffix in '{value}': the rate must be positive")
+        if not math.isfinite(fps) or fps <= 0:
+            raise ValueError(f"bad @fps suffix in '{value}': the rate must be a positive, finite number")
         if len(v.split(":")) != 4:
             raise ValueError(f"'{value}': the @fps suffix belongs to an hh:mm:ss:ff timecode, not to seconds or mm:ss")
     parts = v.split(":")
@@ -208,6 +208,10 @@ def parse_time(value: str, fps: Optional[float] = None) -> float:
         except ValueError:
             # not the interpreter's "could not convert string to float: 'zz'" (review 9)
             raise ValueError(f"'{value}': not a time")
+    # float() reads "nan", "inf" and "1e999": none of them is a time, and each got past the
+    # comparisons that bound a time (nan compares false with everything)
+    if not math.isfinite(total):
+        raise ValueError(f"'{value}': not a time (it is not finite)")
     return total
 
 

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
@@ -1307,3 +1328,95 @@ def compare_pictures(path: str, reference: str) -> "Optional[Dict[str, Any]]":
     mean_psnr = psnr.group(1) if psnr else None
     return {"ssim": float(ssim.group(1)), "worst_ssim": worst[1], "worst_frame": worst[0] - 1, "frames": len(frames),
             "psnr": None if mean_psnr is None else (float("inf") if mean_psnr == "inf" else float(mean_psnr))}
+
+
+# check.py --compare --expect-changed (#439): where the picture differs from the reference.
+CHANGE_GRID = (32, 18)   # tiles across and down: one is 60x60 px at 1080p
+CHANGE_FLOOR = 24        # a tile whose largest channel difference (0-255, area mean) is above this changed
+
+
+def change_tiles(path: str, reference: str, floor: int, grid: "Tuple[int, int]" = CHANGE_GRID,
+                 squares: "Tuple[str, str]" = ("", "")) -> "Optional[Dict[str, Any]]":
+    """Which tiles of which frames of `path` differ from `reference`, frame i against frame i in
+    decode order (as compare_pictures() pairs them; the caller checks sizes and frame counts).
+    Both pictures go to 8-bit RGB planes, are subtracted, and each frame of the difference is
+    area-scaled to `grid`; a tile's value is the largest of its three channels. `squares` is each
+    file's square_pixels() filter, so the grid covers the displayed picture (display_size()) and a
+    caller's rectangle in displayed pixels names the tiles it means on a non-square-pixel file.
+    {frames, changed {frame index: a bit mask of the tiles above `floor`, bit column + row * columns;
+    change_mask_tiles() lists them}, peaks {frame index: its largest tile}, quiet_peak (the largest
+    tile at or under the floor)}. A mask and not a list: two unrelated hours differ in every tile
+    of every frame, which as tuples is tens of millions of objects.
+    None when the pass fails, times out of its bytes mid-frame, or decodes no frame: nothing was
+    compared, which the caller must not read as "nothing changed"."""
+    import subprocess
+    import threading
+    from _common import runner as _runner
+    gw, gh = grid
+    sq_a, sq_b = (s + "," if s else "" for s in squares)
+    graph = (f"[0:V:0]{sq_a}settb=1/1000,setpts=N,format=gbrp[a];[1:V:0]{sq_b}settb=1/1000,setpts=N,format=gbrp[b];"
+             f"[a][b]blend=all_mode=difference:shortest=1,scale={gw}:{gh}:flags=area[o]")
+    # passthrough: the frames carry index timestamps, and a constant-rate muxer would drop
+    # nearly all of them as duplicates (12 of 300 came out without it)
+    cmd = [require_tool("ffmpeg"), "-hide_banner", "-loglevel", "error", "-nostdin", "-i", path, "-i", reference,
+           "-filter_complex", graph, "-map", "[o]", "-fps_mode", "passthrough", "-f", "rawvideo", "-pix_fmt", "rgb24", "-"]
+    # read frame by frame as ffmpeg writes them: 1728 bytes a frame is 187 MB for an hour at
+    # 30 fps, and only the frames with a changed tile are kept. Same wall-clock limit as run_analysis()
+    _runner._refuse_url_media(cmd)
+    limit = _runner._limit_for(cmd)
+    size, tiles = gw * gh * 3, gw * gh
+    changed: Dict[int, int] = {}
+    peaks: Dict[int, int] = {}
+    quiet, n, pending = 0, 0, b""
+    child = subprocess.Popen(cmd, stdout=subprocess.PIPE, stderr=subprocess.DEVNULL, **_runner.child_kwargs())
+    _runner._watch(child, cmd)
+    expired = threading.Event()
+
+    def _expire() -> None:
+        expired.set()
+        child.kill()
+
+    timer = threading.Timer(limit, _expire) if limit else None
+    if timer:
+        timer.daemon = True
+        timer.start()
+    try:
+        while True:
+            chunk = child.stdout.read(size * 64)
+            if not chunk:
+                break
+            pending += chunk
+            whole = len(pending) - len(pending) % size
+            for i in range(0, whole, size):
+                frame = pending[i:i + size]
+                top = max(frame)
+                if top <= floor:
+                    quiet = max(quiet, top)
+                else:
+                    mask = 0
+                    for t in range(tiles):
+                        value = max(frame[3 * t:3 * t + 3])
+                        if value > floor:
+                            mask |= 1 << t
+                        elif value > quiet:
+                            quiet = value
+                    changed[n], peaks[n] = mask, top
+                n += 1
+            pending = pending[whole:]
+        child.wait()
+    finally:
+        if timer:
+            timer.cancel()
+        _runner._unwatch(child)
+        child.stdout.close()
+    if expired.is_set():
+        _runner._timed_out(cmd, limit or 0)
+    if child.returncode != 0 or not n or pending:
+        return None
+    return {"frames": n, "changed": changed, "peaks": peaks, "quiet_peak": quiet}
+
+
+def change_mask_tiles(mask: int, grid: "Tuple[int, int]" = CHANGE_GRID) -> "List[Tuple[int, int]]":
+    """change_tiles()'s bit mask as [(column, row)], row by row."""
+    gw = grid[0]
+    return [(t % gw, t // gw) for t in range(grid[0] * grid[1]) if mask >> t & 1]

package/scripts/_common/runner.py

@@ -386,9 +386,37 @@ class Context:
 STATE = Context()
 
 
+def finite_float(text: str) -> float:
+    """argparse's `float`, minus nan and inf. Python's float() reads "nan", "inf" and "1e999", and
+    no flag here means any of them: they reached int() as a traceback, ffmpeg as "Invalid
+    argument" (kind ffmpeg, as if the build were at fault), or a comparison that is always false
+    and so skipped the check it guarded. add_common() registers this for every `type=float`."""
+    import argparse
+    import math
+    value = float(text)
+    if not math.isfinite(value):
+        raise argparse.ArgumentTypeError(f"{text!r} is not a finite number")
+    return value
+
+
 def add_common(ap: "argparse.ArgumentParser", codec: bool = True) -> None:
     """Add the flags every script shares. `codec=False` is for a tool that re-encodes but whose
     preset decides the encoder (export.py): it must not advertise --codec/--quality in its schema."""
+    # one place for every tool: argparse looks a `type=` up in this registry at parse time, so the
+    # flags a tool added before this call are covered as well
+    ap.register("type", float, finite_float)
+    usage_error = ap.error
+
+    def error(message: str) -> None:
+        # a --json caller gets a failure document for this refusal, as for every other bad value a
+        # tool checks itself (export.py --max-mb nan answered with one before this was shared);
+        # anything else argparse rejects stays its usage error
+        if "is not a finite number" in message and {"--json", "--json-brief"} & set(sys.argv[1:]):
+            STATE.json = True
+            die(message.replace("argument ", "", 1))
+        usage_error(message)
+
+    ap.error = error  # type: ignore[method-assign]
     g = ap.add_argument_group("agent options")
     g.add_argument("--dry-run", action="store_true", help="print the ffmpeg commands that would run, run nothing")
     g.add_argument("--json", action="store_true", help="print a JSON result (output, probe, commands) on stdout instead of the path")
@@ -1067,9 +1095,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 +1110,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

@@ -209,7 +209,8 @@ TOOL_META: Dict[str, Dict[str, Any]] = {
                   required=["ffprobe"], optional=[{"capability": "ffmpeg", "when": "loudness rows (default); the audio row's volumedetect silence test when loudness is skipped"}, {"capability": "filter:loudnorm", "when": "loudness rows (default)"},
                                                   {"capability": "filter:blackdetect", "when": "--content (black row)"}, {"capability": "filter:freezedetect", "when": "--content (frozen row)"},
                                                   {"capability": "filter:silencedetect", "when": "--content (silence row)"},
-                                                  {"capability": "filter:signalstats", "when": "--levels (legal levels row)"}, {"capability": "filter:lutyuv", "when": "--levels (legal levels row)"}],
+                                                  {"capability": "filter:signalstats", "when": "--levels (legal levels row)"}, {"capability": "filter:lutyuv", "when": "--levels (legal levels row)"},
+                                                  {"capability": "filter:blend", "when": "--expect-changed (change_scope row)"}],
                   video_required=False, audio_only=True, visual=False, verify=[], produces_artifact=False, idempotency="bit_exact", deterministic=True),
     "scenes": dict(role="analysis", inputs=["video asset", "audio asset (after 3.2.0: one scene; --beats, --audio-peaks, --speech, --highlights; --sheet and --shots need a picture)"], outputs=["scene / audio-peak / highlight JSON on stdout", "EDL text (--edl)", "per-scene contact sheet PNG (--sheet)"],
                    required=FF + ["filter:scdet"], optional=[{"capability": "filter:drawtext", "when": "--sheet"}, {"capability": "filter:tile", "when": "--sheet"},
@@ -472,6 +473,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,14 +616,16 @@ 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":
         extra = {"platform": {"type": "string"}, "ok": {"type": "boolean"}, "failed": {"type": "integer"}, "warnings": {"type": "integer"},
                  "input_identity": {"type": "object", "description": "2.24: {size, mtime_ns} of the file graded, the same shape as a writing tool's output_identity"},
                  "levels": {"type": "object", "description": "--levels only: {standard, reference, bit_depth, legal {y, c}: inclusive legal code ranges at the file's depth, window_seconds, frames, out_of_range_pct {y, u, v, chroma}: share of samples outside them (chroma: Cb and Cr samples together), brng_pct (signalstats BRNG: pixels with any component outside the fixed BT.601/709 nominal range), worst_frame {time, y_pct, chroma_pct}, min {y, u, v}, max {y, u, v}, windows: the same per --levels-window seconds ({start, end, ...})}"},
-                 "notes": {"type": "array", "items": {"type": "string"}, "description": "present when no --platform was named (youtube was assumed and judgement rows are WARN), or when --compare paired a different number of frames than the reference has"},
-                 "checks": {"type": "array", "items": {"type": "object", "properties": {"check": {"type": "string", "description": "row name; --content adds black, frozen and silence; --compare adds similarity; --levels adds legal levels; --expect-identity adds identity; audio FAILs when the track is present but silent (peak <= -50 dBFS)"}, "status": {"enum": ["PASS", "WARN", "FAIL"]}, "value": {}, "expected": {}, "fix": {"type": "string"}, "kind": {"enum": ["format", "judgement"]}}}}}
+                 "change_scope": {"type": "object", "description": "--expect-changed only, when the two files could be compared: {declared [{start, end, rect}], observed [{start, end, frames, rect [x, y, w, h], peak}]: every span with a tile above the floor, undeclared: the same for the tiles no declaration covers, declared_unchanged: declared spans in which nothing changed, floor, tile [columns, rows], frames, quiet_peak: the largest tile at or under the floor}. Times are this file's presentation times in seconds, rectangles are displayed pixels"},
+                 "notes": {"type": "array", "items": {"type": "string"}, "description": "present when no --platform was named (youtube was assumed and judgement rows are WARN), when --compare paired a different number of frames than the reference has, or when --expect-changed compared two files that are not encoded alike"},
+                 "checks": {"type": "array", "items": {"type": "object", "properties": {"check": {"type": "string", "description": "row name; --content adds black, frozen and silence; --compare adds similarity; --expect-changed adds change_scope; --levels adds legal levels; --expect-identity adds identity; audio FAILs when the track is present but silent (peak <= -50 dBFS)"}, "status": {"enum": ["PASS", "WARN", "FAIL"]}, "value": {}, "expected": {}, "fix": {"type": "string"}, "kind": {"enum": ["format", "judgement"]}}}}}
     elif name == "caption":
         extra = {"transcription": {"type": "object", "description": "with --transcribe: {engine, model, language, routing (why auto chose it), detected_language when auto detected it}; when auto ran the English-only Parakeet model on English assumed, notes says so"},
                  "caption": {"type": "object", "description": "cue layout: shifted / wrapped / rebalanced / split / extended / dropped counts, plus wrap ('phrase' or 'measured'), phrase_breaks (1.16), broken_inside_word -- atoms hard-sliced at the column edge because they did not fit alone even at the size floor (1.18.4) -- and overlong -- now residual: a single character alone wider than the column. Burn mode: cues_burned -- non-blank cues that overlap [0, duration] and are drawn -- and cues_outside -- non-blank cues wholly outside it (2.2.6); a burn with no visible cue is refused, kind input. --ass: ass_malformed -- Dialogue lines that could not be read and are not counted -- and with --offset ass_shifted / ass_unshifted -- lines moved, and lines whose timestamps could not be read, copied as they were (each count above 0 is also a diagnostics.warnings entry)"},

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/check.py

@@ -44,7 +44,7 @@ from fractions import Fraction
 from typing import Any, Dict, List, Optional, Tuple
 
 from _platforms import PLATFORMS, PLATFORM_CHOICES, TP_TOLERANCE_DB, spec_of, resolve as resolve_platform
-from _common.probe import (LEGAL_RANGE_CHOICES, measure_signal_range, COMPARE_SSIM_WARN, CONTENT_FLAT_STD, SILENT_PEAK_DBFS, compare_pictures, detect_content,
+from _common.probe import (CHANGE_FLOOR, CHANGE_GRID, change_mask_tiles, change_tiles, LEGAL_RANGE_CHOICES, measure_signal_range, COMPARE_SSIM_WARN, CONTENT_FLAT_STD, SILENT_PEAK_DBFS, compare_pictures, detect_content,
                            detect_flashes, first_frame_stats, presentation_times, measured_level_dbfs)
 from _common.emit import file_identity
 from _common import STATE, add_common, apply_common, die, emit, info, probe, require_tool, run, run_analysis, dry_run_input_pending
@@ -112,6 +112,103 @@ def display_size(v: Dict[str, Any]) -> "Tuple[int, int]":
     return (h, w) if int(v.get("rotation") or 0) % 180 == 90 else (w, h)
 
 
+def parse_expect_changed(values: "List[str]") -> "List[Dict[str, Any]]":
+    """--expect-changed values -> [{start, end, rect}] (rect [x, y, w, h] in displayed pixels, or
+    None for the whole frame); [] for `none`. Refuses anything it cannot read: a declaration that
+    was silently dropped would turn into a FAIL the caller cannot explain, or a PASS it did not earn."""
+    from _common.decision import parse_time
+    import math
+    if any(v.strip().lower() == "none" for v in values):
+        if len(values) > 1:
+            die("--expect-changed none says the picture must not change at all; it cannot be combined with a span")
+        return []
+    spans = []
+    for raw in values:
+        span, _, rect_text = raw.strip().partition("@")
+        start_text, sep, end_text = span.partition("-")
+        try:
+            if not sep or not start_text or not end_text:
+                raise ValueError(raw)
+            start, end = parse_time(start_text), parse_time(end_text)
+        except (ValueError, SystemExit):
+            die(f"--expect-changed takes START-END (seconds or H:MM:SS), optionally @X,Y,W,H, or none; got {raw!r}")
+        if not (math.isfinite(start) and math.isfinite(end)) or start < 0 or end < start:
+            die(f"--expect-changed {raw!r}: a span starts at 0 or later and ends at or after its start")
+        rect = None
+        if "@" in raw:
+            try:
+                rect = [int(n) for n in rect_text.split(",")]
+            except ValueError:
+                rect = []
+            if len(rect) != 4 or rect[0] < 0 or rect[1] < 0 or rect[2] <= 0 or rect[3] <= 0:
+                die(f"--expect-changed {raw!r}: the rectangle is X,Y,W,H in displayed pixels, whole numbers, W and H above 0")
+        spans.append({"start": start, "end": end, "rect": rect})
+    return spans
+
+
+def _runs(frames: "List[int]") -> "List[Tuple[int, int]]":
+    """Sorted frame indices -> [(first, last)] of consecutive runs."""
+    out: "List[Tuple[int, int]]" = []
+    for n in frames:
+        if out and n == out[-1][1] + 1:
+            out[-1] = (out[-1][0], n)
+        else:
+            out.append((n, n))
+    return out
+
+
+def change_scope(tiles: "Dict[str, Any]", declared: "List[Dict[str, Any]]", times: "List[float]",
+                 size: "Tuple[int, int]", floor: int) -> "Dict[str, Any]":
+    """The measured tiles against the declaration. `times` has one more entry than there are
+    frames (frame n is shown from times[n] until times[n+1]). A declared span is closed at both
+    ends and widened to whole frames: frame n is inside when its interval touches the span.
+    Inside a span with a rectangle, only the tiles the rectangle touches may change."""
+    gw, gh = CHANGE_GRID
+    w, h = size
+    tw, th = w / gw, h / gh
+
+    def allowed_mask(rect: "Optional[List[int]]") -> int:
+        if rect is None:
+            return (1 << gw * gh) - 1
+        x, y, rw, rh = rect
+        return sum(1 << (c + r * gw) for c in range(gw) for r in range(gh)
+                   if c * tw < x + rw and (c + 1) * tw > x and r * th < y + rh and (r + 1) * th > y)
+
+    spans = [dict(d, mask=allowed_mask(d["rect"]), seen=False) for d in declared]
+
+    def describe(frames: "Dict[int, int]") -> "List[Dict[str, Any]]":
+        out = []
+        for first, last in _runs(sorted(frames)):
+            union = 0
+            for n in range(first, last + 1):
+                union |= frames[n]
+            hit = change_mask_tiles(union)
+            c0, c1 = min(c for c, _ in hit), max(c for c, _ in hit)
+            r0, r1 = min(r for _, r in hit), max(r for _, r in hit)
+            x0, y0, x1, y1 = int(c0 * tw), int(r0 * th), int(round((c1 + 1) * tw)), int(round((r1 + 1) * th))
+            out.append({"start": round(times[first], 3), "end": round(times[last + 1], 3), "frames": last - first + 1,
+                        "rect": [x0, y0, x1 - x0, y1 - y0], "peak": max(tiles["peaks"][n] for n in range(first, last + 1))})
+        return out
+
+    outside: "Dict[int, int]" = {}
+    for n, changed in tiles["changed"].items():
+        left = changed
+        for d in spans:
+            if times[n] <= d["end"] and times[n + 1] > d["start"]:
+                # against the frame's own tiles, not what earlier declarations left of them: two
+                # declarations that overlap would otherwise depend on their order, and the later
+                # one would read as "nothing changed there"
+                if changed & d["mask"]:
+                    d["seen"] = True
+                left &= ~d["mask"]
+        if left:
+            outside[n] = left
+    return {"declared": [{"start": d["start"], "end": d["end"], "rect": d["rect"]} for d in declared],
+            "observed": describe(tiles["changed"]), "undeclared": describe(outside),
+            "declared_unchanged": [{"start": d["start"], "end": d["end"], "rect": d["rect"]} for d in spans if not d["seen"]],
+            "floor": floor, "tile": [gw, gh], "frames": tiles["frames"], "quiet_peak": tiles["quiet_peak"]}
+
+
 def _span_total(spans: Any) -> float:
     return sum(max(0.0, e - s) for s, e in spans)
 
@@ -158,6 +255,102 @@ def levels_row(args: argparse.Namespace, v: Dict[str, Any], row: Any) -> "Option
     return doc
 
 
+def encoding_differences(v: Dict[str, Any], rv: Dict[str, Any]) -> "List[str]":
+    """What makes two video streams "not encoded alike" for --expect-changed: part of a measured
+    difference is then the encoder's. The stored size is the file's own width and height, before
+    rotation: 1080x1920 turned to 1920x1080 against a stored 1920x1080 is the same displayed
+    picture stored another way (as is 1440x1080 at 4:3), compared and said."""
+    def stored(x: Dict[str, Any]) -> str:
+        return f"{x.get('width')}x{x.get('height')}"
+    pairs = (("codec", v.get("codec"), rv.get("codec")), ("pix_fmt", v.get("pix_fmt"), rv.get("pix_fmt")),
+             ("fps", v.get("fps"), rv.get("fps")), ("stored size", stored(v), stored(rv)))
+    return [f"{k} {a} against {b}" for k, a, b in pairs if a != b]
+
+
+def change_scope_row(args: Any, declared: "List[Dict[str, Any]]", meta: Dict[str, Any], v: Dict[str, Any], row: Any) -> "Optional[Dict[str, Any]]":
+    """--expect-changed: measure where the picture differs from the reference and grade it against
+    the declaration. A comparison that could not be made is a FAIL, never a WARN or a PASS: the
+    flag exists to stop a false "nothing else changed", and a check that did not run would be one."""
+    want = "a change only where declared" if declared else "no change in the picture"
+    look = f"look.py --compare {args.compare} --at "
+
+    def not_compared(why: str, fix: str) -> None:
+        row("change_scope", "FAIL", f"not compared: {why}", want, fix,
+            reason="nothing was measured, so this does not say the rest of the picture is unchanged")
+
+    ref = probe(args.compare)
+    rv = ref.get("video") or {}
+    if not v or not rv:
+        return not_compared("one of the files has no picture", "--expect-changed needs a video stream in both files")
+    # the displayed picture: rotation applied and non-square pixels squared (a 1440x1080 file at
+    # 4:3 is 1920x1080), which is the frame a caller measures a rectangle on and the frame both
+    # pictures are brought to before they are subtracted
+    from _common.probe import display_size as shown_size, square_pixels
+    size = shown_size(v)
+    if size != shown_size(rv):
+        return not_compared("%dx%d against %dx%d (as displayed)" % (size + shown_size(rv)),
+                            "compare two renders of the same frame size")
+    for d in declared:
+        if d["rect"] and (d["rect"][0] + d["rect"][2] > size[0] or d["rect"][1] + d["rect"][3] > size[1]):
+            # a rectangle that runs past the edge is a wrong size or a wrong file, and clipping it
+            # quietly would allow less than the caller believes it declared
+            die(f"--expect-changed: the rectangle {','.join(map(str, d['rect']))} does not fit inside the {size[0]}x{size[1]} picture")
+    origin = float(meta.get("start_time") or 0.0)
+    pts = presentation_times(args.input, float(v.get("start_time") or 0.0))
+    ref_pts = presentation_times(args.compare, float(rv.get("start_time") or 0.0))
+    nout, nref = v.get("nb_frames") or len(pts) or None, rv.get("nb_frames") or len(ref_pts) or None
+    if not nout or not nref:
+        return not_compared("a frame count could not be read", "remux the file that has no readable frame count (export.py --preset copy)")
+    if int(nout) != int(nref):
+        return not_compared(f"{nout} frames against the reference's {nref}",
+                            "an edit that changes the length cannot be paired frame by frame; compare the parts separately")
+    tiles = change_tiles(args.input, args.compare, args.change_floor, squares=(square_pixels(v), square_pixels(rv)))
+    if tiles is None:
+        return not_compared("the comparison pass failed", look + "0")
+    n = tiles["frames"]
+    fps = float(v.get("fps") or 0.0)
+    if pts and len(pts) >= n:
+        times = [max(0.0, t - origin) for t in pts[:n]]
+        times.append(times[-1] + ((times[-1] - times[-2]) if n > 1 else (1.0 / fps if fps else 0.0)))
+    else:
+        # a span is placed by each frame's own time, and a change is reported at one; an average
+        # rate would put a frame near a span's edge on the wrong side of it, and is simply wrong
+        # on variable-rate video. `none` too: its FAIL names where the change is
+        return not_compared("the frame times could not be read", "remux the file (export.py --preset copy) and check it again")
+    doc = change_scope(tiles, declared, times, size, args.change_floor)
+
+    def span(d: "Dict[str, Any]") -> str:
+        return f"{d['start']:.2f}-{d['end']:.2f}"
+
+    def place(d: "Dict[str, Any]") -> str:
+        x, y, w, h = d["rect"]
+        return f"{span(d)} ({d['frames']} frame{'s' if d['frames'] != 1 else ''}, around x {x}-{x + w}, y {y}-{y + h})"
+
+    idle = "; ".join(f"declared {span(d)} but nothing changed there" for d in doc["declared_unchanged"])
+    differ = encoding_differences(v, rv)
+    if differ:
+        STATE_NOTES.append("--expect-changed: the two files are not encoded alike (" + ", ".join(differ) + "), so part of "
+                           "what was measured is the encoder's difference, not the edit")
+    floor_note = f"floor {doc['floor']}, largest unchanged tile {doc['quiet_peak']}"
+    if doc["undeclared"]:
+        first = doc["undeclared"][0]
+        more = len(doc["undeclared"]) - 1
+        value = "changed " + place(first) + (f" and {more} more span{'s' if more != 1 else ''}" if more else "") + ": not declared"
+        row("change_scope", "FAIL", value + (f"; {idle}" if idle else "") + f" ({floor_note})", want,
+            look + f"{first['start']:g}", reason="the picture changed where the edit was not meant to reach")
+    elif idle:
+        row("change_scope", "WARN", idle + f" ({floor_note})", want, "look at that span: the edit probably did not apply",
+            reason="a declared change was not found")
+    else:
+        seen = ", ".join(span(d) for d in doc["observed"]) or "nothing"
+        value = (f"changed {seen} inside the declared span{'s' if len(declared) != 1 else ''}; nothing else above the floor"
+                 if declared else "no tile above the floor in any frame") + f" ({floor_note}, {n} frames)"
+        row("change_scope", "WARN" if differ else "PASS", value, want,
+            "compare two renders made with the same encoder settings" if differ else "",
+            reason="the two files are not encoded alike: " + ", ".join(differ) if differ else "")
+    return doc
+
+
 def main() -> int:
     STATE_NOTES.clear()  # module state: a second main() in one process starts without the first's notes
     ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
@@ -183,6 +376,14 @@ def main() -> int:
     ap.add_argument("--compare", metavar="REFERENCE",
                     help="also measure the picture against REFERENCE, frame by frame (SSIM and PSNR, one pass): a "
                          "similarity row, WARN when the mean SSIM is under 0.98, with the worst frame's time")
+    ap.add_argument("--expect-changed", action="append", metavar="SPAN[@X,Y,W,H]|none",
+                    help="with --compare: where the picture is allowed to differ from REFERENCE, as START-END in this "
+                         "file's time (repeatable), optionally only inside a rectangle of displayed pixels, or `none`. A "
+                         "change_scope row FAILs on a change anywhere else (with its time and place) or when the two "
+                         "could not be compared, and WARNs when a declared span did not change")
+    ap.add_argument("--change-floor", type=int, default=CHANGE_FLOOR, metavar="N",
+                    help="--expect-changed: a 60x60-ish tile (the frame in %dx%d) counts as changed when its largest "
+                         "channel difference is above N of 255 (default %%(default)d)" % CHANGE_GRID)
     ap.add_argument("--expect-identity", metavar="SIZE:MTIME_NS",
                     help="the output_identity a writing tool reported ({size}:{mtime_ns}): an identity row FAILs when "
                          "the file at INPUT is not that file (a later run replaced it, or a failed run left an older one)")
@@ -211,6 +412,14 @@ def main() -> int:
     if not 0 <= args.levels_tolerance <= 100:
         die(f"--levels-tolerance {args.levels_tolerance:g} is outside 0..100 (percent of a frame's samples)")
 
+    declared_changes = None
+    if args.expect_changed:
+        if not args.compare:
+            die("--expect-changed says where the picture may differ from a reference, so it needs --compare REFERENCE")
+        declared_changes = parse_expect_changed(args.expect_changed)
+    if not 1 <= args.change_floor <= 254:
+        die(f"--change-floor {args.change_floor} is outside 1..254 (a difference of 0-255 per channel)")
+
     expected_identity = None
     if args.expect_identity is not None:
         # parsed before any measurement; "" (an unset shell variable) is malformed, not absent
@@ -478,6 +687,9 @@ def main() -> int:
                     STATE_NOTES.append(f"--compare: {nout} frames against the reference's {nref}; frames were paired in "
                                        f"order, so an added or dropped frame shifts every later pair, and only the "
                                        f"first {min(int(nref), int(nout))} were compared")
+    scope_doc = None
+    if declared_changes is not None and not dry_run_input_pending(args.input) and not dry_run_input_pending(args.compare):
+        scope_doc = change_scope_row(args, declared_changes, meta, v, row)
     # read after every measurement, --compare's included, so a replacement at any point shows
     identity = None if dry_run_input_pending(args.input) else file_identity(args.input)
     if identity is not None and identity != identity_before and expected_identity is None:
@@ -520,6 +732,8 @@ def main() -> int:
     extra: Dict[str, Any] = {"notes": notes} if notes else {}
     if levels_doc is not None:
         extra["levels"] = levels_doc
+    if scope_doc is not None:
+        extra["change_scope"] = scope_doc
     if identity is not None:
         extra["input_identity"] = identity
     if failed:

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.