ffmpeg-skill 3.3.0 → 3.4.0

package/README.md

@@ -269,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**

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/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.3.0`) | 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.3.0", "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`

package/package.json

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

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

@@ -1328,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")

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"},
@@ -622,8 +623,9 @@ def output_schema(name: str, meta: Dict[str, Any], hw: bool = False) -> Dict[str
         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/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: