shotdrift 0.2.0__py3-none-any.whl

shotdrift/__init__.py

@@ -0,0 +1,25 @@
+"""shotdrift - measure whether a video holds the camera move it was given.
+
+AI video is asked for a camera move and is not obliged to deliver one. The usual
+check is a person watching sixty clips. This measures the camera path out of the
+pixels - pan, zoom, roll, frame by frame - and reports whether one physical camera
+could have produced it.
+
+    from shotdrift import measure
+    r = measure("take_07.mp4", expect="push-in")
+    print(r.verdict, [f.code for f in r.findings])
+
+Frames already in memory - inside a generation graph, say, where the clip was
+never written to disk - skip ffmpeg entirely:
+
+    from shotdrift import measure_frames, report
+    r = measure_frames(image_batch, expect="push-in")   # (n, h, w, c), 0..1
+    print(report(r))
+"""
+
+from __future__ import annotations
+
+from .core import Result, Shot, measure, measure_frames, report
+
+__version__ = "0.2.0"
+__all__ = ["measure", "measure_frames", "report", "Result", "Shot", "__version__"]

shotdrift/cli.py

@@ -0,0 +1,95 @@
+"""shotdrift - measure whether a video holds the camera move it was given."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+from . import __version__
+from .core import measure, report
+from .expect import known as known_moves
+from .frames import DecodeError, FFmpegMissing
+from .verdict import (BROKEN, CLEAN, SOFT, UNKNOWN, at_or_above)
+
+EXIT_OK, EXIT_FINDINGS, EXIT_ERROR, EXIT_UNMEASURABLE = 0, 1, 2, 3
+
+
+def main(argv=None) -> int:
+    ap = argparse.ArgumentParser(
+        prog="shotdrift",
+        description="Measure the camera move in a video, and whether it is one a real "
+                    "camera could have made.",
+        epilog="Exit 0 clean, 1 findings at or above --min-severity, "
+               "2 could not run, 3 clip could not be measured.",
+    )
+    ap.add_argument("clips", nargs="*", metavar="CLIP")
+    ap.add_argument("--expect", metavar="MOVE",
+                    help="the move you asked for: " + ", ".join(known_moves()))
+    ap.add_argument("--list-moves", action="store_true")
+    ap.add_argument("--min-severity", choices=[CLEAN, SOFT, BROKEN], default=BROKEN,
+                    help="which findings make this exit non-zero (default: broken; "
+                         "soft findings are always printed either way)")
+    ap.add_argument("--max-side", type=int, default=512,
+                    help="analysis resolution, long edge in px (default 512)")
+    ap.add_argument("--grid", type=int, default=4, help="tiles per axis (default 4)")
+    ap.add_argument("--start", type=float, default=0.0, metavar="SEC")
+    ap.add_argument("--duration", type=float, default=None, metavar="SEC")
+    ap.add_argument("--sample-fps", type=float, default=None,
+                    help="resample before measuring; changes WHAT is measured, "
+                         "not just the cost")
+    ap.add_argument("--max-frames", type=int, default=600)
+    ap.add_argument("--anchors", type=int, default=4,
+                    help="independent first-to-frame-k checks (0 disables closure)")
+    ap.add_argument("--no-segment", action="store_true",
+                    help="measure the file as one take even if it contains cuts")
+    ap.add_argument("--json", action="store_true", help="machine-readable output")
+    ap.add_argument("--quiet", action="store_true", help="findings without the advice")
+    ap.add_argument("--version", action="version", version=f"shotdrift {__version__}")
+    args = ap.parse_args(argv)
+
+    if args.list_moves:
+        for m in known_moves():
+            print(m)
+        return EXIT_OK
+    if not args.clips:
+        ap.error("give at least one CLIP, or --list-moves")
+
+    if args.expect and args.expect not in known_moves():
+        ap.error(f"unknown move {args.expect!r}. --list-moves shows them all.")
+
+    results, rc = [], EXIT_OK
+    for name in args.clips:
+        try:
+            r = measure(name, expect=args.expect, max_side=args.max_side,
+                        grid=args.grid, start=args.start, duration=args.duration,
+                        sample_fps=args.sample_fps, anchors=args.anchors,
+                        max_frames=args.max_frames,
+                        segment=not args.no_segment)
+        except FFmpegMissing as e:
+            print(f"shotdrift: {e}", file=sys.stderr)
+            return EXIT_ERROR
+        except (DecodeError, ValueError) as e:
+            print(f"shotdrift: {name}: {e}", file=sys.stderr)
+            rc = max(rc, EXIT_ERROR)
+            continue
+
+        for s in r.shots:
+            if s.verdict == UNKNOWN:
+                rc = max(rc, EXIT_UNMEASURABLE)
+            elif at_or_above(s.findings, args.min_severity) or \
+                    (s.expect is not None and not s.expect.ok):
+                rc = max(rc, EXIT_FINDINGS)
+
+        if args.json:
+            results.append(r.as_dict())
+        else:
+            sys.stdout.write(report(r, quiet=args.quiet))
+
+    if args.json:
+        print(json.dumps({"shotdrift": __version__, "clips": results}, indent=2))
+    return rc
+
+
+if __name__ == "__main__":
+    sys.exit(main())

shotdrift/core.py

@@ -0,0 +1,236 @@
+"""One measurement, however the frames arrived, and one way of reporting it.
+
+Both halves of this file are corrections.
+
+`measure()` used to call `analyse` where the command line calls `analyse_clip`,
+so the Python API did not segment. On an edited reel that is not a small
+difference: measured as one take, a six-shot sequence reports a broken closure
+and a pile of reversals, all true and all useless, because no single camera move
+was ever there to hold. The command line was fixed for exactly that and the
+library was left behind - so `import shotdrift` gave a worse answer than
+`shotdrift` did, which nothing warned anyone about.
+
+And the text report lived inside the command line, writing straight to stdout.
+Anything else wanting the same words - a node in a generation graph, a CI
+comment - had to reimplement them, which is how two surfaces of one tool come to
+disagree about what a clip measured. It renders to a string here, and the command
+line prints what it returns.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+import numpy as np
+
+from .verdict import BROKEN, CLEAN, SOFT, UNKNOWN, at_or_above
+
+__all__ = ["Shot", "Result", "measure", "measure_frames", "report"]
+
+_MARK = {CLEAN: "ok", SOFT: "soft", BROKEN: "BROKEN", UNKNOWN: "unmeasurable"}
+_RANK = {CLEAN: 0, SOFT: 1, BROKEN: 2, UNKNOWN: 0}
+
+
+@dataclass
+class Shot:
+    """One continuous take, measured on its own."""
+    start: int
+    end: int
+    path: object = field(repr=False)
+    findings: list = field(default_factory=list)
+    verdict: str = CLEAN
+    expect: object | None = None
+
+    @property
+    def frames(self) -> int:
+        return self.end - self.start
+
+    @property
+    def ok(self) -> bool:
+        return self.verdict == CLEAN and (self.expect is None or self.expect.ok)
+
+    def as_dict(self) -> dict:
+        return {
+            "frames": [self.start, self.end],
+            "path": self.path.summary(),
+            "verdict": self.verdict,
+            "expect": self.expect.as_dict() if self.expect else None,
+            "findings": [f.as_dict() for f in self.findings],
+        }
+
+
+@dataclass
+class Result:
+    clip: str
+    shots: list = field(default_factory=list)
+    cuts: list = field(default_factory=list)
+    src_width: int = 0
+    src_height: int = 0
+    width: int = 0
+    height: int = 0
+    frame_count: int = 0
+    fps: float = 0.0
+    truncated: bool = False
+
+    # --- clip-level views over the shots -------------------------------------
+    # A clip with one shot answers exactly as it did before segmentation existed.
+    # With several, these summarise, and `shots` is there for anyone who needs the
+    # detail - a clip-level verdict on an edited sequence is a summary, not a
+    # measurement, and the distinction is kept rather than blurred.
+
+    @property
+    def path(self):
+        """The dominant shot's path: the longest one, not the first."""
+        if not self.shots:
+            return None
+        return max(self.shots, key=lambda s: s.frames).path
+
+    @property
+    def findings(self) -> list:
+        return [f for s in self.shots for f in s.findings]
+
+    @property
+    def verdict(self) -> str:
+        if not self.shots:
+            return UNKNOWN
+        return max((s.verdict for s in self.shots), key=lambda v: _RANK[v])
+
+    @property
+    def expect(self):
+        """The failing expectation if any shot failed it, else the dominant one."""
+        failed = [s.expect for s in self.shots if s.expect is not None and not s.expect.ok]
+        if failed:
+            return failed[0]
+        with_exp = [s for s in self.shots if s.expect is not None]
+        return max(with_exp, key=lambda s: s.frames).expect if with_exp else None
+
+    @property
+    def ok(self) -> bool:
+        """Every shot clean, and - if a move was declared - every shot held it."""
+        return bool(self.shots) and all(s.ok for s in self.shots)
+
+    def gated(self, min_severity: str = BROKEN) -> list:
+        return at_or_above(self.findings, min_severity)
+
+    def as_dict(self) -> dict:
+        return {
+            "clip": self.clip,
+            "source": {"width": self.src_width, "height": self.src_height,
+                       "fps": self.fps},
+            "measured_at": {"width": self.width, "height": self.height,
+                            "frames": self.frame_count,
+                            "truncated": self.truncated},
+            "cuts": self.cuts,
+            "shots": [s.as_dict() for s in self.shots],
+        }
+
+
+def _assemble(name: str, frames, grid: int, anchors: int, segment: bool,
+              expect: str | None) -> tuple[list, list]:
+    from .expect import check as check_expect
+    from .path import analyse_clip
+    from .verdict import judge, worst
+
+    shots_in, cuts = analyse_clip(frames, grid=grid, anchors=anchors,
+                                  segment=segment)
+    shots = []
+    for (a, b), p in shots_in:
+        f = judge(p)
+        shots.append(Shot(start=a, end=b, path=p, findings=f, verdict=worst(f),
+                          expect=check_expect(p, expect) if expect else None))
+    return shots, cuts
+
+
+def measure(clip: str, expect: str | None = None, *, max_side: int = 512,
+            grid: int = 4, start: float = 0.0, duration: float | None = None,
+            sample_fps: float | None = None, anchors: int = 4,
+            max_frames: int = 600, segment: bool = True) -> Result:
+    """Measure a video file. Cuts are detected and each shot measured on its own."""
+    from .frames import load
+
+    c = load(clip, max_side=max_side, sample_fps=sample_fps, start=start,
+             duration=duration, max_frames=max_frames)
+    shots, cuts = _assemble(clip, c.frames, grid, anchors, segment, expect)
+    return Result(clip=clip, shots=shots, cuts=cuts,
+                  src_width=c.src_width, src_height=c.src_height,
+                  width=c.width, height=c.height, frame_count=len(c),
+                  fps=c.fps, truncated=c.truncated)
+
+
+def measure_frames(frames, expect: str | None = None, *, name: str = "<frames>",
+                   max_side: int = 512, grid: int = 4, anchors: int = 4,
+                   segment: bool = True, fps: float = 0.0) -> Result:
+    """Measure frames that are already in memory - no file, no ffmpeg.
+
+    Takes (n, h, w) or (n, h, w, c) in uint8 0..255 or float 0..1, as a numpy
+    array or a torch tensor. This is the entry point a generation graph uses: the
+    frames exist, they were never written to disk, and the question is whether
+    the move that was asked for is in them.
+    """
+    from .ingest import to_gray_stack
+
+    stack, sw, sh = to_gray_stack(frames, max_side=max_side)
+    shots, cuts = _assemble(name, stack, grid, anchors, segment, expect)
+    n, h, w = stack.shape
+    return Result(clip=name, shots=shots, cuts=cuts, src_width=sw, src_height=sh,
+                  width=w, height=h, frame_count=n, fps=fps)
+
+
+# ------------------------------------------------------------------ report ----
+def _fmt(v, nd=4):
+    if v is None:
+        return "-"
+    if isinstance(v, float) and not np.isfinite(v):
+        return "not measurable"
+    return f"{v:.{nd}f}" if isinstance(v, float) else str(v)
+
+
+def report(r: Result, *, quiet: bool = False, header: bool = True) -> str:
+    """The human-readable report, as a string. The CLI prints this verbatim."""
+    out = []
+    w = out.append
+
+    if header:
+        w(f"\n{r.clip}")
+        rate = f" @ {r.fps:g} fps" if r.fps else ""
+        w(f"  {r.src_width}x{r.src_height} -> measured at {r.width}x{r.height}, "
+          f"{r.frame_count} frames{rate}")
+        if r.truncated:
+            w(f"  only the first {r.frame_count} frames were measured "
+              f"(--max-frames); the rest of the clip was not looked at.")
+        if r.cuts:
+            w(f"  {len(r.cuts)} cut(s) detected: this is {len(r.shots)} shot(s), "
+              f"not one take. Each is measured on its own.")
+
+    multi = len(r.shots) > 1
+    for s in r.shots:
+        p = s.path
+        if multi:
+            w(f"\n  shot {s.start}-{s.end} ({s.frames} frames)")
+        w("\n  camera path")
+        w(f"    dominant move      {p.dominant}")
+        w(f"    pan                {_fmt(p.net_pan)} of frame width "
+          f"(x {_fmt(float(p.tx[-1]))}, y {_fmt(float(p.ty[-1]))})")
+        w(f"    zoom               {_fmt(p.zoom, 3)}x")
+        w(f"    roll               {_fmt(float(np.degrees(p.net_roll)), 2)} deg")
+        w(f"    reversals          {p.reversals}  (measured, not judged)")
+        w(f"    jerk               {_fmt(p.jerk, 2)}")
+        w(f"    incoherence        {_fmt(p.incoherence)}")
+        w(f"    morph              {_fmt(p.morph, 3)}  (used to find cuts, not judged)")
+        w(f"    closure            {_fmt(p.closure)}")
+        w(f"    confidence         {_fmt(p.confidence, 2)}")
+
+        if s.expect is not None:
+            w(f"\n  asked for: {s.expect.move}")
+            w(f"    {'HELD' if s.expect.ok else 'NOT HELD'} - {s.expect.detail}")
+
+        if not s.findings:
+            w("\n  no findings: the motion is consistent with one physical camera.")
+        else:
+            w(f"\n  {len(s.findings)} finding(s)")
+            for f in s.findings:
+                w(f"    [{_MARK[f.severity]}] {f.summary}")
+                w(f"        evidence: {f.evidence}")
+                if not quiet:
+                    w(f"        {f.advice}")
+    return "\n".join(out) + "\n"

shotdrift/expect.py

@@ -0,0 +1,132 @@
+"""Check a measured path against the move that was ASKED for.
+
+This is the part that does not exist elsewhere. Everything else here describes
+what a clip did; this asks whether it did what it was told, which is the actual
+question when you type "slow push in" into a generator and get back something
+that drifts left.
+
+A declared move is checked three ways, because each failure is different and the
+distinction is what makes the output useful:
+  happened  - is there any motion on that channel at all?
+  direction - is it the way round you asked?
+  held      - was it monotonic, or did it wobble there?
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import numpy as np
+
+# name -> (channel, sign, human); sign 0 means "must not move"
+# THE SIGNS ARE CAMERA-RELATIVE, NOT CONTENT-RELATIVE, and that is the one thing
+# in this file worth reading twice. A camera panning RIGHT makes the picture move
+# LEFT, so "pan-right" expects a NEGATIVE x. Writing these the intuitive way round
+# made a correctly-measured clean pan report "x went the other way" - the
+# measurement was right and the vocabulary was wrong. Verified by test.
+MOVES: dict[str, tuple[str, int, str]] = {
+    "static":    ("none", 0, "locked off"),
+    "locked":    ("none", 0, "locked off"),
+    "push-in":   ("zoom", +1, "push in / dolly in"),    # subject grows
+    "dolly-in":  ("zoom", +1, "push in / dolly in"),
+    "zoom-in":   ("zoom", +1, "zoom in"),
+    "pull-out":  ("zoom", -1, "pull out / dolly out"),
+    "dolly-out": ("zoom", -1, "pull out / dolly out"),
+    "zoom-out":  ("zoom", -1, "zoom out"),
+    "pan-left":  ("x", +1, "pan left"),                 # camera left  -> picture right
+    "pan-right": ("x", -1, "pan right"),                # camera right -> picture left
+    "tilt-up":   ("y", +1, "tilt up"),                  # camera up    -> picture down
+    "tilt-down": ("y", -1, "tilt down"),
+    "roll-cw":   ("roll", -1, "roll clockwise"),        # camera cw    -> picture ccw
+    "roll-ccw":  ("roll", +1, "roll counter-clockwise"),
+}
+
+# A move has to clear this to count as having happened at all, in frame widths
+# (or radians / log-scale). Below it, the honest answer is "nothing happened".
+FLOOR = {"x": 0.02, "y": 0.02, "zoom": 0.02, "roll": 0.02}
+# Fraction of the travel allowed to run backwards before the move is not "held".
+BACKTRACK_OK = 0.25
+
+
+@dataclass
+class Expectation:
+    move: str
+    ok: bool
+    happened: bool
+    direction_ok: bool
+    held: bool
+    measured: float
+    backtrack: float
+    detail: str
+
+    def as_dict(self) -> dict:
+        return dict(move=self.move, ok=self.ok, happened=self.happened,
+                    direction_ok=self.direction_ok, held=self.held,
+                    measured=round(self.measured, 5),
+                    backtrack=round(self.backtrack, 4), detail=self.detail)
+
+
+def known() -> list[str]:
+    return sorted(MOVES)
+
+
+def _series(p, chan: str) -> np.ndarray:
+    if chan == "x":
+        return np.asarray(p.tx, dtype=float)
+    if chan == "y":
+        return np.asarray(p.ty, dtype=float)
+    if chan == "zoom":
+        return np.asarray(p.logscale, dtype=float)
+    if chan == "roll":
+        return np.asarray(p.roll, dtype=float)
+    raise KeyError(chan)
+
+
+def check(p, move: str) -> Expectation:
+    key = move.strip().lower().replace("_", "-")
+    if key not in MOVES:
+        raise KeyError(f"unknown move {move!r}; known: {', '.join(known())}")
+    chan, sign, human = MOVES[key]
+
+    if chan == "none":
+        # "Locked off" is a claim about every channel at once, so it is the one
+        # case that cannot be judged on a single series.
+        worst_name, worst_val, worst_floor = "pan", p.net_pan, FLOOR["x"]
+        for nm, val, fl in (("pan", p.net_pan, FLOOR["x"]),
+                            ("zoom", abs(float(np.log(max(p.zoom, 1e-6)))), FLOOR["zoom"]),
+                            ("roll", abs(p.net_roll), FLOOR["roll"])):
+            if val / fl > worst_val / worst_floor:
+                worst_name, worst_val, worst_floor = nm, val, fl
+        still = worst_val < worst_floor
+        return Expectation(
+            move=key, ok=still, happened=not still, direction_ok=still, held=still,
+            measured=worst_val, backtrack=0.0,
+            detail=(f"locked off as asked; largest movement was {worst_name} "
+                    f"{worst_val:.4f} (floor {worst_floor})") if still else
+                   (f"asked for {human}, but {worst_name} moved {worst_val:.4f}, "
+                    f"over the {worst_floor} floor"),
+        )
+
+    s = _series(p, chan)
+    net = float(s[-1] - s[0])
+    step = np.diff(s)
+    travel = float(np.sum(np.abs(step))) or 1e-9
+    against = float(np.sum(np.abs(step[np.sign(step) == -sign])))
+    backtrack = against / travel
+
+    happened = abs(net) >= FLOOR[chan]
+    direction_ok = bool(np.sign(net) == sign) if happened else False
+    held = backtrack <= BACKTRACK_OK
+    ok = happened and direction_ok and held
+
+    if not happened:
+        detail = (f"asked for {human}; {chan} moved {net:+.4f}, under the "
+                  f"{FLOOR[chan]} floor - that move did not happen")
+    elif not direction_ok:
+        detail = (f"asked for {human}; {chan} went the other way, {net:+.4f}")
+    elif not held:
+        detail = (f"{human} happened ({net:+.4f}) but {backtrack * 100:.0f}% of the "
+                  f"travel ran backwards - the move is not held")
+    else:
+        detail = f"{human} as asked: {chan} {net:+.4f}, {backtrack * 100:.0f}% backtrack"
+    return Expectation(key, ok, happened, direction_ok, held, net, backtrack, detail)

shotdrift/frames.py

@@ -0,0 +1,135 @@
+"""Decode a video to small grayscale frames with ffmpeg, and nothing else.
+
+Deliberately no OpenCV and no torch. ffmpeg is already on every machine that
+edits video, and a tool that needs a 2 GB wheel to measure a camera move will
+not get run.
+
+Everything downstream works in NORMALISED units - fractions of the frame width -
+so a threshold means the same thing on a 720p proxy and a 4K master. Reporting
+pixels at the analysis resolution would make every bound silently resolution
+dependent, which is how a measurement tool ends up with magic numbers.
+"""
+
+from __future__ import annotations
+
+import json
+import shutil
+import subprocess
+from dataclasses import dataclass
+
+import numpy as np
+
+from .ingest import analysis_size
+
+
+class FFmpegMissing(RuntimeError):
+    pass
+
+
+class DecodeError(RuntimeError):
+    pass
+
+
+@dataclass
+class Clip:
+    frames: np.ndarray      # (n, h, w) float32 in 0..1
+    width: int              # analysis width  (px)
+    height: int             # analysis height (px)
+    src_width: int          # original width  (px)
+    src_height: int         # original height (px)
+    fps: float
+    duration: float
+    truncated: bool = False   # hit the frame budget with picture still to come
+
+    def __len__(self) -> int:
+        return int(self.frames.shape[0])
+
+
+def _exe(name: str) -> str:
+    p = shutil.which(name)
+    if not p:
+        raise FFmpegMissing(
+            f"{name} not found on PATH. shotdrift measures video, so it needs "
+            "ffmpeg: `brew install ffmpeg` or `apt install ffmpeg`."
+        )
+    return p
+
+
+def probe(path: str) -> dict:
+    out = subprocess.run(
+        [_exe("ffprobe"), "-v", "error", "-select_streams", "v:0",
+         "-show_entries", "stream=width,height,avg_frame_rate,nb_read_packets",
+         "-show_entries", "format=duration", "-of", "json", path],
+        capture_output=True, text=True,
+    )
+    if out.returncode != 0:
+        raise DecodeError(f"ffprobe could not read {path}: {out.stderr.strip()[:300]}")
+    d = json.loads(out.stdout or "{}")
+    streams = d.get("streams") or []
+    if not streams:
+        raise DecodeError(f"{path} has no video stream.")
+    s = streams[0]
+    num, _, den = (s.get("avg_frame_rate") or "0/1").partition("/")
+    try:
+        fps = float(num) / float(den) if float(den) else 0.0
+    except (ValueError, ZeroDivisionError):
+        fps = 0.0
+    try:
+        dur = float((d.get("format") or {}).get("duration") or 0.0)
+    except ValueError:
+        dur = 0.0
+    return {"width": int(s["width"]), "height": int(s["height"]), "fps": fps, "duration": dur}
+
+
+def load(path: str, max_side: int = 512, sample_fps: float | None = None,
+         start: float = 0.0, duration: float | None = None,
+         max_frames: int = 600) -> Clip:
+    """Decode to grayscale. `sample_fps=None` keeps the clip's own rate.
+
+    Camera motion is measured BETWEEN ADJACENT FRAMES, so dropping the rate
+    changes what is being measured, not just the cost of measuring it. The
+    default therefore keeps every frame; `--sample-fps` exists for long clips
+    and says so in the report.
+    """
+    meta = probe(path)
+    sw, sh = meta["width"], meta["height"]
+    if sw <= 0 or sh <= 0:
+        raise DecodeError(f"{path} reports a {sw}x{sh} frame size.")
+
+    w, h = analysis_size(sw, sh, max_side)
+
+    cmd = [_exe("ffmpeg"), "-v", "error"]
+    if start > 0:
+        cmd += ["-ss", f"{start:.3f}"]
+    cmd += ["-i", path]
+    if duration is not None:
+        cmd += ["-t", f"{duration:.3f}"]
+    vf = [f"scale={w}:{h}:flags=bilinear"]
+    if sample_fps:
+        vf.insert(0, f"fps={sample_fps:g}")
+    cmd += ["-vf", ",".join(vf), "-frames:v", str(max_frames),
+            "-pix_fmt", "gray", "-f", "rawvideo", "-"]
+
+    out = subprocess.run(cmd, capture_output=True)
+    if out.returncode != 0:
+        raise DecodeError(f"ffmpeg failed on {path}: {out.stderr.decode(errors='replace').strip()[:300]}")
+
+    buf = np.frombuffer(out.stdout, dtype=np.uint8)
+    stride = w * h
+    n = buf.size // stride
+    if n < 2:
+        raise DecodeError(
+            f"{path} decoded to {n} frame(s) at {w}x{h}. Camera motion needs at "
+            "least two frames; check the file is not truncated and that any "
+            "--start/--duration window actually contains picture."
+        )
+    frames = buf[: n * stride].reshape(n, h, w).astype(np.float32) / 255.0
+    eff_fps = float(sample_fps) if sample_fps else meta["fps"]
+    # A frame budget that silently drops the rest of the clip is how a tool comes
+    # to report confidently on the first twelve seconds of a two-minute take. The
+    # window is reported, not assumed.
+    window = duration if duration is not None else max(0.0, meta["duration"] - start)
+    expected = window * eff_fps if (window and eff_fps) else 0.0
+    truncated = bool(n >= max_frames and expected > n + 1)
+    return Clip(frames=frames, width=w, height=h, src_width=sw, src_height=sh,
+                fps=eff_fps, duration=meta["duration"], truncated=truncated)