Generate clean 2D game sprites & animation atlases — component-row pipeline: state rows, alpha cleanup, frame extraction, runtime atlases. Codex/Claude skill.
feat(video-loop): held cells found on every cut and made again with RIFE's frames between by default, and a cut given above its clip's rate (--out-fps)
Soohong Kimea42ccbd82e5
diff --git a/sprite_gen/frames/unpack_atlas.py b/sprite_gen/frames/unpack_atlas.pyindex df5c29a..b4a038c 100644--- a/sprite_gen/frames/unpack_atlas.py+++ b/sprite_gen/frames/unpack_atlas.py@@ -273,6 +273,24 @@ def import_pngs(out_dir: Path, png_paths: list[Path], state_name: str, labels: lreturn import_png_groups(out_dir, [{"name": state_name, "paths": png_paths, "labels": labels}], iso)+def loop_marks(folder: Path, count: int) -> dict[int, str]:+ """The cells of a video-loop `cycle/` folder (one `*.strip.json` beside it, holding `count` cycle frames) that the+ held fill made between their neighbours (`made`) and that still show the picture before them (`held`), from the+ strip metadata's `held_fill` (docs/loop-repair.md section 7); nothing for any other folder. A cut given at+ `--out-fps` has every cell made at its own time: its held cells alone are marked."""+ metas = sorted(folder.parent.glob("*.strip.json")) if folder.name == "cycle" else []+ if len(metas) != 1:+ return {}+ meta = json.loads(metas[0].read_text(encoding="utf-8"))+ held = meta.get("held_fill")+ if not isinstance(held, dict) or meta.get("cycle_frames") != count:+ return {}+ marks = {} if "out_fps" in meta else {int(c): "made" for c in held.get("made", [])}+ for run in held.get("held_runs", []):+ marks.update({c: "held" for c in range(int(run["start"]) + 1, int(run["start"]) + int(run["length"]))})+ return marks++def import_png_groups(out_dir: Path, groups: list[dict[str, Any]], iso: dict[str, Any] | None = None,base_src: Path | None = None, run_dir: Path | None = None) -> dict[str, Any]:"""Import separate PNGs as one or more curator rows (states).@@ -562,6 +580,10 @@ def _run(args: argparse.Namespace):"refs": _group_refs(sub)})if not groups:raise SystemExit(f"no PNGs in {src}")+ for group in groups:+ # a video-loop cut's cells: each made between its neighbours, or still the picture before it, says so on its card+ marks = loop_marks(group["paths"][0].parent, len(group["paths"]))+ group["labels"] = [f"{label} ({marks[k]})" if k in marks else label for k, label in enumerate(group["labels"])]# imported ref roles are validated fail-loud (run-contract §4). A _refs file whose# prefix isn't a known role (anchor/basis/guide) is malformed input — reject it# loudly instead of silently relabeling it as guide (No Silent Fallback).diff --git a/sprite_gen/video/align.py b/sprite_gen/video/align.pyindex 1c085bf..a61e5dc 100644--- a/sprite_gen/video/align.py+++ b/sprite_gen/video/align.py@@ -197,7 +197,8 @@ def held_drawings(frames: list[Image.Image], *, fps: float, clip: dict[str, Any]loop's: a clip held for part of its length is held where it was cut. The clip's stands where thecut was too short to read, or was cut before that record (`span_why` says which). The cut cycleis the fallback for a loop cut before either record (`source` cycle, read as a ring): it is short,- and `--anchor motion-auto` shifts each cut frame, so a pair's repeat may no longer read as one."""+ and `--anchor motion-auto` shifts each cut frame, so a pair's repeat may no longer read as one. It is+ also how a loop whose held cells `video-loop` made again (`held_fill`) is read: as it plays."""n = len(frames)if clip and clip.get("hold"):whole = {"hold": clip["hold"], "drawings_per_second": clip["drawings_per_second"], "contrast": clip.get("contrast")}@@ -977,6 +978,10 @@ def _loop_files(loop_dir: Path) -> tuple[Path, dict[str, Any]]:for key in ("cycle_frames", "cycle_seconds", "cell_height_cap", "kind"):if key not in meta:raise ValueError(f"{metas[0]}: no `{key}` — cut the loop again with this sprite-gen (video-loop) before aligning it")+ if "out_fps" in meta:+ raise ValueError(f"{metas[0]}: cut at --out-fps {meta['out_fps']:g}, its cells each made at a time of their own — the "+ "alignment makes its own frames between: align the loop cut at its clip's rate (video-loop without "+ "--out-fps)")strip = cut_strip(loop_dir, metas[0], meta)if strip is not None and not strip.is_file():raise ValueError(f"{loop_dir}: no {strip.name} — a first alignment reads the strip as cut to record where its cells are from "@@ -1336,7 +1341,11 @@ def align_set(loop_dirs: list[Path], *, length: int | None = None, interpolate:except (ValueError, rife_mod.RifeUnavailable) as exc:raise SystemExit(f"video-cycle-align: {d}: {exc}; frames between source frames are made by RIFE (docs/loop-repair.md)") from excstart = strike["start"]- drawings = held_drawings(frames, fps=fps, clip=loops[i][2].get("drawings"), cut=loops[i][2].get("cycle_drawings"))+ # A loop whose held cells video-loop made again (`held_fill`) shows a picture a cell where its clip held them: the+ # clip's readings say how it was filmed, not how it plays, and its own cells are read.+ filled = bool((loops[i][2].get("held_fill") or {}).get("made"))+ drawings = held_drawings(frames, fps=fps, clip=None if filled else loops[i][2].get("drawings"),+ cut=None if filled else loops[i][2].get("cycle_drawings"))# the ghosts passed over or kept as frames of cycle.source/, each cell where it now standsghost_at = sorted(({**g, "at": (g["at"] - start) % target, "source": index[g["source"]], "taken": index[g["taken"]]}for g in facts["ghost_at"]), key=lambda g: g["at"])diff --git a/sprite_gen/video/batch.py b/sprite_gen/video/batch.pyindex 54ba644..0292388 100644--- a/sprite_gen/video/batch.py+++ b/sprite_gen/video/batch.py@@ -37,6 +37,7 @@ from sprite_gen.video import facing as facing_modfrom sprite_gen.video import canvas as canvas_modfrom sprite_gen.video import frames as frames_modfrom sprite_gen.video import loop as loop_mod+from sprite_gen.video import held_fill as held_fill_modfrom sprite_gen.video import align as align_modfrom sprite_gen.video import body_plan as body_modfrom sprite_gen.video.body_plan import Body@@ -720,6 +721,8 @@ def run_item(end_frame: Path | None = None,play: str | None = None,motion: str | None = None,+ fill_held: str = "auto",+ out_fps: float | None = None,) -> dict[str, Any]:"""One (direction, state) item, canvas to loop. `play` is the request's play mode for it (`play.MODES`; None, thestate's preset) and `motion` the caller's own motion text in place of the state's sentence."""@@ -859,7 +862,8 @@ def run_item(result["frames"]["decontam_warning"] = decontam_notelp = loop_mod.run_loop(Path(fr["keyed_dir"]), item_dir / "loop", fps=float(fr["fps"]), state=state, min_len=None, max_len=None, n_out=None, seam_max=loop_mod.SEAM_RATIO_MAX, name=item, report_path=item_dir / "loop.report.json", anchor=anchor, body_height=body_height,cycle_mode=cycle_for(state, direction, play, pinned=pins),- facing=facing if direction in handed_mod.LATERAL_VIEWS else "right")+ facing=facing if direction in handed_mod.LATERAL_VIEWS else "right",+ fill_held=fill_held, out_fps=out_fps)result["loop"] = {"kind": lp["cycle"].get("kind", "periodic"), "cycle": lp["cycle"]["length"], "period": lp["cycle"]["period_global"], "cycle_ratio": round(lp["cycle"]["ratio"], 3), "seam_ratio": lp["resampled_seam_ratio"], "n_out": lp["n_out"], "drift_px": lp["strip"].get("drift_px", 0), "gif": lp["gif"]["file"], "webp": lp["webp"]["file"], "strip": lp["strip"]["path"]}result["loop"]["review_recommended"] = lp["cycle"].get("review_recommended", False)result["loop"]["half_period_guard"] = lp["cycle"].get("half_period_guard")@@ -876,6 +880,12 @@ def run_item(result["loop"]["step_screen"] = {k: lp["cycle"]["step_screen"][k] for k in ("lag", "ratio", "depth", "coverage")}if lp.get("motion_anchor", {}).get("applied") is False:result["loop"]["motion_anchor"] = lp["motion_anchor"]+ # The cut's poses over its cells, its held runs as delivered, and what became of them (docs/loop-repair.md section 7).+ held = lp["held_fill"]+ result["loop"]["poses"] = held_fill_mod.said(held)+ result["loop"]["held_fill"] = {"before": held_fill_mod.said(held["before"]), "held_runs": held["held_runs"],+ "made": held["made"], **({"unmade": held["unmade"]} if "unmade" in held else {}),+ **({"out_fps": held["out_fps"]} if "out_fps" in held else {})}if "rife" in (lp.get("jump_repair") or {}):# cut as filmed for want of RIFE: the set report lists it under `warnings` (a wrap the seam bridge read carries# its `seam`, not the flow's `off_max_before`)@@ -1091,6 +1101,8 @@ def run_set(end_frames: dict[str, Path] | None = None,play: dict[str, str] | None = None,motion: dict[str, str] | None = None,+ fill_held: str = "auto",+ out_fps: float | None = None,) -> dict[str, Any]:"""`bases` maps a view to its still; `facing` is right, left or `right,left` (`facings_of`), and a view filmedboth ways is keyed `view@right` and `view@left` (`resolve_bases`). `handed` (`handedness.parse`) puts each@@ -1132,6 +1144,9 @@ def run_set(raise SystemExit("video-set: non-loop states need --fit state and --anchor none")aligned_items = [i for i, _, s, _, _ in items if align_cycles == "auto" and loop_mod.profile_for(s).gaitand sum(1 for _, _, s2, _, _ in items if s2 == s) >= 2]+ if out_fps is not None and aligned_items:+ raise SystemExit(f"video-set: --out-fps gives each cut at a higher rate, and the cycle alignment of {', '.join(aligned_items)} "+ "makes its own frames between to one length — pass --align-cycles off with it")for item, foot in (align_feet or {}).items():if item not in aligned_items:raise SystemExit(f"video-set: --align-foot {item}={foot}: {item} is not an item the set aligns (a walk or run filmed in two or "@@ -1153,7 +1168,7 @@ def run_set(return prepare_sidewith ThreadPoolExecutor(max_workers=max(1, concurrency)) as ex:- futures = {ex.submit(run_item, item=i, direction=d, state=s, base=b, root=root, character=character, duration=duration, resolution=resolution, key=key, force=force, gap=gap, video_runner=video_runner, shape=shape, anchor=anchor, spill=spill, facing=f, facing_fix=facing_fix, prepare_side=side_preparer(f), body_height=body_height, fit=fit, decontam=decontam, walk_start=walk_start, redraw_runner=redraw_runner, still_provider=still_provider, handed=handed, body_plan=body_plan, **({"end_frame": end_frames[i]} if end_frames and i in end_frames else {}), **({"play": plays[i]} if i in plays else {}), **({"motion": motions[i]} if i in motions else {})): i for i, d, s, f, b in items}+ futures = {ex.submit(run_item, item=i, direction=d, state=s, base=b, root=root, character=character, duration=duration, resolution=resolution, key=key, force=force, gap=gap, video_runner=video_runner, shape=shape, anchor=anchor, spill=spill, facing=f, facing_fix=facing_fix, prepare_side=side_preparer(f), body_height=body_height, fit=fit, decontam=decontam, walk_start=walk_start, redraw_runner=redraw_runner, still_provider=still_provider, handed=handed, body_plan=body_plan, **({"end_frame": end_frames[i]} if end_frames and i in end_frames else {}), **({"play": plays[i]} if i in plays else {}), **({"motion": motions[i]} if i in motions else {}), fill_held=fill_held, out_fps=out_fps): i for i, d, s, f, b in items}for fut in as_completed(futures):r = fut.result()results.append(r)@@ -1164,6 +1179,10 @@ def run_set(failed = [r["item"] for r in results if not r.get("ok")] + [f"cycle-align:{st}" for st, a in aligned.items() if not a.get("ok")]# What the set left undone for want of RIFE — never a failure, never silent.warnings = ([f"{r['item']}: jump frame not repaired — {r['loop']['jump_repair']['why']}" for r in results if r.get("ok") and "jump_repair" in r["loop"]]+ + [f"{r['item']}: held cells {r['loop']['held_fill']['unmade']['cells']} shown as filmed — RIFE is not installed"+ for r in results if r.get("ok") and "unmade" in r["loop"]["held_fill"]]+ + [f"{r['item']}: --out-fps {r['loop']['held_fill']['out_fps']['asked']:g} not met — {r['loop']['held_fill']['out_fps']['why']}"+ for r in results if r.get("ok") and not r["loop"]["held_fill"].get("out_fps", {"applied": True})["applied"]]+ [f"cycle-align:{st}: not aligned — {a['why']}" for st, a in aligned.items() if a.get("reason") == "rife-not-installed"])if warnings:warnings.append(f"install RIFE with `{rife_mod.install_command()}` (docs/loop-repair.md)")@@ -1280,6 +1299,13 @@ def add_arguments(parser: argparse.ArgumentParser) -> None:help="which own foot lands on the first strike of an item's loop (e.g. front-walk=left), for a loop the ""alignment report lists under `unnamed_feet` (video-cycle-align --foot; repeatable): that loop starts as ""the set's start foot lands, recorded start_foot_source given")+ parser.add_argument("--fill-held", choices=held_fill_mod.MODES, default="auto",+ help="each cut's neighbour cells showing the same picture (video-loop --fill-held): auto (default) makes "+ "them again with RIFE's frames between, off cuts them as filmed; each item's `loop.poses` says its poses "+ "over its cells")+ parser.add_argument("--out-fps", type=float, default=None,+ help="give each cut at this rate, above its clip's, made of frames between (video-loop --out-fps); with "+ "a walk or run filmed in two or more directions, pass --align-cycles off")parser.add_argument("--force", action="store_true", help="regenerate clips that already exist")@@ -1302,6 +1328,7 @@ def run(**kwargs: object) -> int:body_plan=body_mod.parse_all(list(kwargs.get("body_plan") or [])) or None, # type: ignore[arg-type]play=_parse_keyed(list(kwargs.get("play") or []), "--play") or None, # type: ignore[arg-type]motion=_parse_keyed(list(kwargs.get("motion") or []), "--motion") or None, # type: ignore[arg-type]+ fill_held=str(kwargs.get("fill_held") or "auto"), out_fps=kwargs.get("out_fps"), # type: ignore[arg-type])return 0 if not payload["failed"] else 1diff --git a/sprite_gen/video/held_fill.py b/sprite_gen/video/held_fill.pynew file mode 100644index 0000000..ad73d00--- /dev/null+++ b/sprite_gen/video/held_fill.py@@ -0,0 +1,320 @@+# SPDX-License-Identifier: Apache-2.0+"""Held cells: neighbour cells of a cut that show the same picture, found, made again as the frames between the poses+beside them, and read again (docs/loop-repair.md section 7).++A clip may show a frame twice or three times in a row: a video model that stalls, a rate carried to another by+repeating frames (20 fps in 24 repeats one in six), a cut mapped to a higher rate by taking the nearer frame. Played,+the motion stops on that picture and jumps on: one pose, two or three cells. Each cut `video-loop` makes is read for+them (`same_steps`, `reading`): the cells, the poses (the cells less the ones that show their neighbour's picture+again) and each run of cells showing one picture (`held_runs`, its first cell and how many). The cells are read as+filmed, before an anchor moves each frame of a pair apart.++The same picture is a step no thumbnail pixel of which (the analysis thumbnail `video-loop` cuts by, premultiplied)+changes by more than PIXEL_SAME, but for at most CHANGED_MAX of the subject's pixels. A textured figure shown three+times, encoded by libx264 at crf 18, 23 and 28 and keyed by `video-frames`, changes no pixel of a frame shown again by+more than 0.008, 0.020 and 0.051; an arm 8 px thick on a 120 x 140 figure grown by one pixel changes 1.2 % of the+subject's pixels by more than PIXEL_SAME. A distance over the subject's mass (`nonloop.STABLE_MAX`, which reads a once+cut's settled end) does not part them: the arm's pixel reads under it. Read on a thumbnail 96 px on its longer side, a+small part's move of a fraction of one of its pixels reads as the same picture, as a hold plays.++`fill` makes each run's cells again, between the run's first cell and the next pose, at their own times — the cells of a+run of three a third and two thirds of the way — so the cut keeps its length, its beat, its first and last cells and+its wrap: a made cell stands where a held cell stood. A run is kept as filmed where filling it would change what the+cut means: longer than HOLD_MAX cells (a drawing held on threes is three: longer is a hold the motion means), the opening+or the closing pose of a cut played once, the last cells of a loop (their next pose is across its wrap). A cut drawn on+twos or threes keeps every run (`drawn`): limited animation, each drawing shown as long as the next. It is drawn so where+its held-drawings reading (`held.measure_cycle`, which `video-cycle-align` reads) gives a hold of 2 or 3 and every run is+that long, but a run cut short at the cut's first or last cell: a clip carried to a higher rate by repeating frames+reads a hold too (24 fps carried to 60 shows each frame two or three times), its runs two and three cells by turns, and+a clip that stalls now and then reads none. A frame made+is judged as the frames the alignment makes are (`align.measure_made`, `faults`), and for a part standing still on+both sides of it (`still_kept`: a foot planted, a hand on a ledge), which must stand where it stood; a frame refused is+made again at another fraction of RETIME_T within half a cell of its own time, else the run is kept as filmed and says+why. A run is made whole or kept whole: half made it would step back.++`upsample` gives a cut at a rate above its own (`--out-fps`) its frames between, at their own times, never a frame+shown again; a cell where both frames beside its time show one picture (a hold kept) is that picture."""++from __future__ import annotations++import math+from collections.abc import Sequence+from typing import Any++from PIL import Image, ImageFilter++from sprite_gen._deps import np+from sprite_gen.video import held as held_mod+from sprite_gen.video import legs as legs_mod+from sprite_gen.video import rife as rife_mod+from sprite_gen.video.interpolation_quality import faults, ghost_screen, looks++MODES = ("auto", "off")+PIXEL_SAME = 0.1 # a thumbnail pixel (premultiplied, 0..1) that changes by more than this has changed+CHANGED_MAX = 0.005 # the same picture: at most this share of the subject's thumbnail pixels changed+HOLD_MAX = max(held_mod.HOLDS) # a run of cells longer than a drawing on threes is a hold the motion means: kept+# A part standing still on both sides of a frame made (`still_kept`): its outline pixels, solid (legs.LOW_ALPHA) and+# within STILL_RGB of each other in both frames, must be solid and within STILL_RGB in the frame made, within a pixel,+# for at least STILL_KEPT_MIN of them in every window of rife.GHOST_BAND of the body high holding STILL_MIN_PX or more.+STILL_RGB = 24+STILL_KEPT_MIN = 0.8+STILL_MIN_PX = 12+SNAP = 0.03 # a time within this of a frame takes that frame (align.SNAP)+++def _thumbs(frames: Sequence[Image.Image]) -> np.ndarray:+ from sprite_gen.video.loop import _small_features # the thumbnail video-loop cuts by (loop imports this module)++ return np.stack([_small_features(f).reshape(-1, 4) for f in frames])+++def same_steps(frames: Sequence[Image.Image]) -> list[bool]:+ """For each step of `frames` (cell k to k + 1), whether the two show the same picture."""+ t = _thumbs(frames)+ out = []+ for a, b in zip(t, t[1:]):+ subject = int((np.maximum(a[:, 3], b[:, 3]) > 0.5).sum())+ changed = int((np.abs(a - b).max(axis=1) > PIXEL_SAME).sum())+ out.append(changed <= CHANGED_MAX * subject)+ return out+++def runs(same: Sequence[bool]) -> list[dict[str, int]]:+ """Each run of cells showing one picture: its first cell and how many (two or more). Not read across a wrap."""+ found, k = [], 0+ while k < len(same):+ if not same[k]:+ k += 1+ continue+ start = k+ while k < len(same) and same[k]:+ k += 1+ found.append({"start": start, "length": k - start + 1})+ return found+++def reading(same: Sequence[bool]) -> dict[str, Any]:+ """The cells, the poses and the held runs of a cut whose steps are `same`."""+ held = runs(same)+ cells = len(same) + 1+ return {"cells": cells, "poses": cells - sum(r["length"] - 1 for r in held), "held_runs": held}+++def said(record: dict[str, Any]) -> str:+ """The poses over the cells, as a person is told them: `poses/cells`."""+ return f"{record['poses']}/{record['cells']}"+++def _edge(solid: np.ndarray) -> np.ndarray:+ inner = np.asarray(Image.fromarray(np.uint8(solid) * 255).filter(ImageFilter.MinFilter(3))) > 0+ return solid & ~inner+++def still_kept(frame: Image.Image, a: Image.Image, b: Image.Image) -> dict[str, Any]:+ """Whether a part standing still in `a` and `b` stands where it stood in `frame`, made between them: the outline+ pixels both draw in one place in one colour (`still`), and the share of them `frame` draws there too, within a+ pixel (`kept`), the least over windows of rife.GHOST_BAND of the body high that hold STILL_MIN_PX of them (`reads`+ false where none does)."""+ A, B, F = (np.asarray(im.convert("RGBA"), dtype=np.int16) for im in (a, b, frame))+ sa, sb, sf = (x[..., 3] >= legs_mod.LOW_ALPHA for x in (A, B, F))+ still = _edge(sa) & _edge(sb) & (np.abs(A[..., :3] - B[..., :3]).max(axis=-1) <= STILL_RGB)+ drawn = sf & (np.abs(F[..., :3] - A[..., :3]).max(axis=-1) <= STILL_RGB)+ near = np.asarray(Image.fromarray(np.uint8(drawn) * 255).filter(ImageFilter.MaxFilter(3))) > 0+ rows = np.nonzero((sa | sb).any(axis=1))[0]+ if not rows.size:+ return {"reads": False, "still_px": 0}+ top, bottom = int(rows[0]), int(rows[-1])+ win = max(8, round((bottom - top + 1) * rife_mod.GHOST_BAND))+ still_rows, kept_rows = still.sum(axis=1), (still & near).sum(axis=1)+ least, at = None, None+ for y in range(top, max(top, bottom - win + 1) + 1, max(1, win // 4)):+ n = int(still_rows[y:y + win].sum())+ if n >= STILL_MIN_PX:+ share = float(kept_rows[y:y + win].sum()) / n+ if least is None or share < least:+ least, at = share, y+ if least is None:+ return {"reads": False, "still_px": int(still.sum())}+ return {"reads": True, "still_px": int(still.sum()), "kept": round(least, 4), "at_row": at, "window_px": win}+++def judge(frame: Image.Image, a: Image.Image, b: Image.Image, t: float, *, reads: bool) -> tuple[dict[str, Any], list[str]]:+ """A frame made between `a` and `b` at `t`: the alignment's measure and faults (`align.measure_made`, `faults`),+ and `contact` where a part standing still on both sides does not stand where it stood (`still_kept`)."""+ from sprite_gen.video.align import measure_made # align imports loop, which imports this module++ measure = measure_made(frame, a, b, t, reads=reads)+ contact = still_kept(frame, a, b)+ wrong = faults(measure) + (["contact"] if contact["reads"] and contact["kept"] < STILL_KEPT_MIN else [])+ return {**measure, "contact": contact}, wrong+++def _made(interpolate: rife_mod.Interpolate, a: Image.Image, b: Image.Image, t: float, window: tuple[float, float], *,+ reads: bool) -> tuple[Image.Image | None, dict[str, Any]]:+ """The frame between `a` and `b` at `t`, or at the fraction of RETIME_T nearest it inside `window` that is made+ with no fault and, made only off its time, with its ghost band under RETIME_WINDOW_MAX in every window (align's+ bar for a frame made again at another fraction); None and what each try was refused for, where none is."""+ from sprite_gen.video.align import RETIME_T, RETIME_WINDOW_MAX++ tries = []+ for at in [t] + sorted((r for r in RETIME_T if window[0] < r < window[1] and abs(r - t) > 1e-3), key=lambda r: (abs(r - t), r)):+ frame = interpolate(a, b, at)+ measure, wrong = judge(frame, a, b, at, reads=reads)+ seen = at != t and (measure.get("ghost_window") or 0.0) >= RETIME_WINDOW_MAX+ tries.append({"t": round(at, 4), "faults": wrong, **({"window_over": RETIME_WINDOW_MAX} if seen and not wrong else {})})+ if not wrong and not seen:+ return frame, {"t": round(at, 4), **({"from_t": round(t, 4)} if at != t else {}),+ "contact": measure["contact"], "look": looks(measure), "tries": tries}+ return None, {"t": round(t, 4), "tries": tries}+++def drawn(found: Sequence[dict[str, int]], n: int, hold: int | None) -> int | None:+ """The hold of a cut of `n` cells drawn on twos or threes, or None: the held-drawings reading's `hold` 2 or 3, and+ every held run `found` that many cells long, but one cut short at the cut's first or last cell (see the module)."""+ if hold not in held_mod.HOLDS or not found:+ return None+ edge = lambda r: r["start"] == 0 or r["start"] + r["length"] == n # noqa: E731+ return hold if all(r["length"] == hold or (r["length"] < hold and edge(r)) for r in found) else None+++def _fillable(run: dict[str, int], n: int, *, ring: bool, on: int | None = None) -> str | None:+ """Why a held run is kept as filmed, or None where it is made again. `on` is the hold of a cut drawn on twos or+ threes (`drawn`)."""+ if on is not None:+ return (f"the cut is drawn on {'twos' if on == 2 else 'threes'} (its held-drawings reading holds {on}, and so does "+ "every run): limited animation, kept as filmed")+ if run["length"] > HOLD_MAX:+ return (f"held {run['length']} cells, longer than a drawing on threes ({HOLD_MAX}): a hold the motion means, "+ "kept as filmed")+ if run["start"] + run["length"] == n:+ return ("the loop's last cells: their next pose is across its wrap, and the wrap stays as cut" if ring else+ "the cut's closing pose, kept as filmed")+ if run["start"] == 0 and not ring:+ return "the cut's opening pose, kept as filmed"+ return None+++def fill(frames: list[Image.Image], interpolate: rife_mod.Interpolate | None, *, ring: bool,+ same: Sequence[bool] | None = None, mode: str = "auto", reads: bool | None = None,+ hold: int | None = None) -> tuple[list[Image.Image], dict[str, Any]]:+ """`frames` with each held run's cells made again between the run's first cell and the next pose (see the module),+ and the record: the reading before (`before`, each run `filled` or why not), the cells made (`made`, and how each+ was, `frames`), the cells left for want of an interpolator (`unmade`, `interpolate` None), the hold of a cut drawn+ on twos or threes (`drawn`), and the reading of the frames returned (`cells`, `poses`, `held_runs`). `same` is the+ steps' reading as filmed (`same_steps` of `frames` where None); `reads` whether the ghost screen reads the cut (read+ on `frames` where None); `hold` the cut's held-drawings reading (`held.measure_cycle`)."""+ if mode not in MODES:+ raise ValueError(f"fill mode {mode!r}: one of {', '.join(MODES)}")+ same = list(same_steps(frames) if same is None else same)+ n = len(frames)+ on = drawn(runs(same), n, hold)+ out = list(frames)+ before = []+ made: list[int] = []+ unmade: list[int] = []+ rows: list[dict[str, Any]] = []+ for run in runs(same):+ row: dict[str, Any] = dict(run)+ cells = list(range(run["start"] + 1, run["start"] + run["length"]))+ why = "--fill-held off" if mode == "off" else _fillable(run, n, ring=ring, on=on)+ if why is None and interpolate is None:+ unmade += cells+ why = "no interpolator"+ if why is not None:+ before.append({**row, "filled": False, "why": why})+ continue+ if reads is None:+ reads = bool(ghost_screen(frames)["reads"])+ a, b = run["start"], run["start"] + run["length"]+ taken, tried = [], []+ for c in cells:+ t = (c - a) / (b - a)+ half = 0.5 / (b - a)+ frame, how = _made(interpolate, frames[a], frames[b % n], t, (t - half, t + half), reads=reads)+ tried.append({"cell": c, "between": [a, b % n], **how})+ if frame is None:+ break+ taken.append((c, frame))+ if len(taken) < len(cells):+ refused = sorted({f for row_ in tried for t_ in row_["tries"] for f in t_["faults"]})+ before.append({**row, "filled": False, "faults": refused, "tries": tried,+ "why": f"a frame between was refused ({', '.join(refused) or 'ghost band over the retime bar'}): kept as filmed"})+ continue+ for c, frame in taken:+ out[c] = frame+ made += cells+ rows += tried+ before.append({**row, "filled": True, "made": cells})+ record: dict[str, Any] = {+ "mode": mode, "pixel_same": PIXEL_SAME, "changed_max": CHANGED_MAX, "hold_max": HOLD_MAX,+ "before": {**reading(same), "held_runs": before},+ "made": made, "frames": rows,+ "contact": [{"cell": r["cell"], **r["contact"]} for r in rows if r["contact"]["reads"]],+ }+ if on is not None:+ record["drawn"] = on+ if unmade:+ record["unmade"] = {"cells": unmade}+ record.update(reading(same_steps(out)) if made else reading(same))+ return out, record+++def times(n: int, fps: float, out_fps: float, *, ring: bool) -> list[float]:+ """The times, in frames of the cut, of the cells of a cut of `n` frames at `fps` given at `out_fps`: a loop's+ round(n·out_fps/fps) cells over its cycle, a cut played once from its first frame to its last."""+ if ring:+ count = round(n * out_fps / fps)+ return [k * n / count for k in range(count)]+ count = round((n - 1) * out_fps / fps) + 1+ return [k * (n - 1) / (count - 1) for k in range(count)]+++def upsample(frames: list[Image.Image], interpolate: rife_mod.Interpolate, *, ring: bool, fps: float, out_fps: float,+ reads: bool | None = None) -> tuple[list[Image.Image], dict[str, Any]]:+ """`frames` given at `out_fps` (`times`): a cell on a frame's time is that frame, one between two frames showing+ one picture is that picture, any other is made between the two at its own time (`_made`, within half a cell of+ it), and one no frame made is taken for is the nearer frame and named (`shown_again`)."""+ n = len(frames)+ at = times(n, fps, out_fps, ring=ring)+ same = same_steps(frames + ([frames[0]] if ring else []))+ if reads is None:+ reads = bool(ghost_screen(frames)["reads"])+ spacing = fps / out_fps+ out: list[Image.Image] = []+ made: list[dict[str, Any]] = []+ shown_again: list[int] = []+ for k, tau in enumerate(at):+ near = round(tau)+ if abs(tau - near) <= SNAP:+ out.append(frames[near % n])+ continue+ a = math.floor(tau)+ if same[a]:+ out.append(frames[a])+ continue+ t = tau - a+ frame, how = _made(interpolate, frames[a], frames[(a + 1) % n], t, (t - spacing / 2, t + spacing / 2), reads=reads)+ if frame is None:+ out.append(frames[near % n])+ shown_again.append(k)+ made.append({"cell": k, "between": [a, (a + 1) % n], "taken": near % n, **how})+ continue+ out.append(frame)+ made.append({"cell": k, "between": [a, (a + 1) % n], **how})+ return out, {"asked": out_fps, "fps": fps, "applied": True, "cells": len(out), "times": [round(x, 4) for x in at],+ "made": sum(1 for m in made if "taken" not in m), "shown_again": shown_again, "frames": made}+++def public(record: dict[str, Any]) -> dict[str, Any]:+ """The record as the strip metadata carries it: the reading as delivered (`cells`, `poses`, `held_runs`), before+ (each run `filled` or why not, with its faults), the cells made and left, and the rate asked — not each try."""+ out: dict[str, Any] = {k: record[k] for k in ("mode", "why", "drawn", "cells", "poses", "held_runs", "made") if k in record}+ before = record["before"]+ out["before"] = {"cells": before["cells"], "poses": before["poses"],+ "held_runs": [{k: v for k, v in r.items() if k != "tries"} for r in before["held_runs"]]}+ if "unmade" in record:+ out["unmade"] = {k: record["unmade"][k] for k in ("cells", "why", "install") if k in record["unmade"]}+ if "out_fps" in record:+ out["out_fps"] = {k: record["out_fps"][k] for k in ("asked", "fps", "applied", "cells", "made", "shown_again", "why", "install")+ if k in record["out_fps"]}+ return outdiff --git a/sprite_gen/video/loop.py b/sprite_gen/video/loop.pyindex 0c6b674..5f6191a 100644--- a/sprite_gen/video/loop.py+++ b/sprite_gen/video/loop.py@@ -53,6 +53,7 @@ from sprite_gen.video import part_pop as part_pop_modfrom sprite_gen.video import cadence as cadence_modfrom sprite_gen.video import crossings as crossings_modfrom sprite_gen.video import held as held_mod+from sprite_gen.video import held_fill as held_fill_modfrom sprite_gen.video import body_turn as body_turn_modfrom sprite_gen.video import legs as legs_modfrom sprite_gen.video import period as period_mod@@ -1315,6 +1316,91 @@ def _bridge_lines(bridge: dict[str, Any]) -> list[str]:return [f"{said}, and no frames made round it close it ({refused}): cut as filmed (docs/loop-repair.md section 2)"]+def _located(interpolate: rife_mod.Interpolate | None, made_by: list[dict[str, str]]) -> Any:+ """`interpolate`, or RIFE located the first time a frame is asked for (`made_by` then names it)."""+ def lazy(a: Image.Image, b: Image.Image, t: float) -> Image.Image:+ nonlocal interpolate+ if interpolate is None:+ found = rife_mod.Rife()+ made_by.append(found.describe())+ interpolate = found+ return interpolate(a, b, t)++ lazy.counts = lambda: interpolate.counts() if made_by else {} # type: ignore[attr-defined]+ return lazy+++def _fill_held(frames: list[Image.Image], interpolate: rife_mod.Interpolate | None, *, ring: bool, same: list[bool],+ mode: str, hold: int | None) -> tuple[list[Image.Image], dict[str, Any]]:+ """`held_fill.fill` on the cut, with RIFE located only once a frame is to be made: a cut with no held cell, or only+ runs kept as filmed, needs no binary. The record names the interpolator that made the frames. A frame to make and no+ RIFE installed: the held cells are delivered as filmed, and the record says which and how to install it (`unmade`)."""+ made_by: list[dict[str, str]] = []+ lazy = _located(interpolate, made_by)+ asked = partial(held_fill_mod.fill, ring=ring, same=same, mode=mode, hold=hold)+ try:+ frames, record = asked(frames, lazy)+ except rife_mod.RifeNotInstalled as exc:+ # RIFE is located before the first frame is made, so nothing was made yet: read again with no interpolator.+ frames, record = asked(frames, None)+ record["unmade"].update(why="RIFE is not installed", rife=str(exc), install=rife_mod.install_command())+ return frames, record+ if record["made"]:+ record["interpolator"] = {**made_by[0], **lazy.counts()} if made_by else {"kind": "injected"}+ return frames, record+++def _upsample(frames: list[Image.Image], interpolate: rife_mod.Interpolate | None, *, ring: bool, fps: float,+ out_fps: float) -> tuple[list[Image.Image], dict[str, Any]]:+ """`held_fill.upsample` on the cut, with RIFE located only once a frame is to be made. No RIFE installed: the cut is+ delivered at its own rate, never with a frame shown again for each cell between, and the record says so."""+ made_by: list[dict[str, str]] = []+ lazy = _located(interpolate, made_by)+ try:+ out, record = held_fill_mod.upsample(frames, lazy, ring=ring, fps=fps, out_fps=out_fps)+ except rife_mod.RifeNotInstalled as exc:+ return frames, {"asked": out_fps, "fps": fps, "applied": False, "cells": len(frames),+ "why": "RIFE is not installed", "rife": str(exc), "install": rife_mod.install_command()}+ if record["made"]:+ record["interpolator"] = {**made_by[0], **lazy.counts()} if made_by else {"kind": "injected"}+ return out, record+++def _fill_lines(record: dict[str, Any]) -> list[str]:+ """What became of the cut's held cells, in words (`video-loop: warning:` lines): the cells left for want of RIFE, the+ runs a frame between was refused for, the frames made to look at. A run kept as the motion's own says nothing."""+ lines = []+ if "unmade" in record:+ cells = record["unmade"]["cells"]+ lines.append(f"{len(cells)} held cell{'s' if len(cells) > 1 else ''} ({', '.join(map(str, cells))}) shown as filmed — "+ f"RIFE is not installed, so no frame between was made ({held_fill_mod.said(record['before'])} poses/cells); "+ f"run `{record['unmade']['install']}` and cut it again (docs/loop-repair.md section 7)")+ for run in record["before"]["held_runs"]:+ if run.get("faults") is not None:+ last = run["start"] + run["length"] - 1+ lines.append(f"held cells {run['start']}-{last} kept as filmed: {run['why']} — look at them in the loop, or film "+ "it again (docs/loop-repair.md section 7)")+ for made in record.get("frames", []):+ if made["look"]:+ a, b = made["between"]+ lines.append(f"cell {made['cell']} was made between cells {a} and {b}, which may cross-fade two drawings inside "+ "its outline; kept, a reading to look at (docs/loop-repair.md section 4)")+ return lines+++def _out_fps_lines(record: dict[str, Any]) -> list[str]:+ """What became of a rate asked above the clip's (`--out-fps`), in words: not met for want of RIFE, or cells where no+ frame between was made and the frame beside them is shown again."""+ if not record["applied"]:+ return [f"--out-fps {record['asked']:g} was not met — RIFE is not installed, so the cut is delivered at its own "+ f"{record['fps']:g} fps; run `{record['install']}` and cut it again (docs/loop-repair.md section 7)"]+ again = record["shown_again"]+ if not again:+ return []+ return [f"{len(again)} cell{'s' if len(again) > 1 else ''} of --out-fps {record['asked']:g} ({', '.join(map(str, again))}) "+ "show the frame beside them again: no frame between was made there without a fault (docs/loop-repair.md section 7)"]++def _shifts(analysis: dict[str, Any]) -> tuple[np.ndarray, int]:"""The analysis translation `auto_motion.analyse` measured, whole pixels a frame, and the room it needs."""shifts = np.rint(np.asarray(analysis["analysis_only_translation_xy"], dtype=np.float64)).astype(int)@@ -2115,6 +2201,8 @@ def _cut_loop(unfixed: str = "warn",seam_pop_max: float | None = repair_mod.SEAM_POP_REFERENCE,body_turn: str = "warn",+ fill_held: str = "auto",+ out_fps: float | None = None,) -> dict[str, Any]:state = state.strip().lower() if state else stateif state == effect.STATE:@@ -2154,6 +2242,14 @@ def _cut_loop(raise SystemExit(f"video-loop: --seam-pop-max {seam_pop_max}: a bound over 0, or off")if body_turn not in body_turn_mod.MODES:raise SystemExit(f"video-loop: unknown --body-turn {body_turn!r}; expected one of {', '.join(body_turn_mod.MODES)}")+ if fill_held not in held_fill_mod.MODES:+ raise SystemExit(f"video-loop: unknown --fill-held {fill_held!r}; expected one of {', '.join(held_fill_mod.MODES)}")+ if out_fps is not None:+ if not (math.isfinite(out_fps) and out_fps > fps):+ raise SystemExit(f"video-loop: --out-fps {out_fps:g} is not above the clip's {fps:g} fps: a cut is given at a higher "+ "rate than it was filmed (its frames between made), a lower one is its preview's (--gif-fps)")+ if cycle_mode == "lifetime":+ raise SystemExit("video-loop: --out-fps: an effect's lifetime plays as filmed")if anchor is None:# gaits drift a few pixels over a cycle and the wrap shows it; in-place states do notanchor = "body" if profile_for(state).gait else "none"@@ -2422,6 +2518,7 @@ def _cut_loop(# ~gif_fps (a fixed 12 made a 2.5 s jump hold each frame 210 ms while a 1.1 s walk held 90 ms)if n_out is None:n_out = max(GIF_FRAMES_MIN, round(L / fps * gif_fps))+ n_asked = n_outn_out = min(n_out, L) # never ask for more distinct frames than the cycle holdsout_dir = out_dir.expanduser().resolve()@@ -2443,6 +2540,9 @@ def _cut_loop(im, d = drop_specks(im, alpha_over=16, diagonal=False, apart=0)specks += dframes.append(im)+ # Each step of the cut as filmed, read for a picture shown again (held_fill.same_steps): before an anchor moves each+ # frame of a pair apart.+ same = held_fill_mod.same_steps(frames)if prof.gait:report_base["gait"] = evidence_mod.gait_observation(frames, cycle)@@ -2474,6 +2574,28 @@ def _cut_loop("recipe": RECIPE, "wrap_dx_px": wrap_dx,"before_repair_pixels_sha256": [evidence_mod.digest(f.tobytes()) for f in frames],}+ # A loop closes on its first cell again; a cut played once runs from its first to its last.+ ring = cycle["kind"] not in ("one-shot", "lifetime", *nonloop.KINDS)+ if cycle["kind"] == "lifetime":+ report_base["held_fill"] = {"mode": fill_held, "why": "an effect's lifetime is played as filmed", "made": [],+ "before": held_fill_mod.reading(same), **held_fill_mod.reading(same)}+ else:+ # The cells that show the picture before them again, made between the poses beside them (docs/loop-repair.md+ # section 7), on the cut as anchored, before anything reads its flow or its wrap. A cut drawn on twos or threes+ # keeps them: its hold as video-cycle-align reads it, over the cut, else over the clip.+ cut_drawings = report_base["cycle_drawings"]+ hold = cut_drawings["hold"] if cut_drawings["hold"] is not None else report_base["drawings"]["hold"]+ try:+ frames, report_base["held_fill"] = _fill_held(frames, interpolate, ring=ring, same=same, mode=fill_held, hold=hold)+ except (ValueError, rife_mod.RifeUnavailable) as exc:+ error = (f"video-loop: {exc}; the cut shows a picture again and the frames between are to be made — fix RIFE, "+ "or pass --fill-held off to cut it as filmed (docs/loop-repair.md section 7)")+ refuse(target, out_dir, name, {**report_base, "status": "failed", "error": error, "cycle": cycle})+ raise SystemExit(error) from exc+ if report_base["held_fill"]["made"]:+ report_base["seam_measurement"] = "rendered-cells"+ for line in _fill_lines(report_base["held_fill"]):+ print(f"video-loop: warning: {name}: {line}", file=sys.stderr)if prof.gait:# The ghost screen of the cut as filmed (docs/loop-repair.md section 4), read before the jump repair: each# filmed ghost it names is a target of that repair, which gives it way to a clean frame where there is one.@@ -2649,6 +2771,29 @@ def _cut_loop(if not report_base["ghost_screen"]["reads"]:print(f"video-loop: warning: the ghost screen does not read this cut — {report_base['ghost_screen']['why']}; no frame ""of it is named a ghost, here or in video-cycle-align, so look at cycle/ (docs/loop-repair.md)", file=sys.stderr)+ held_record = report_base["held_fill"]+ upsampled = None+ if out_fps is not None:+ # A rate above the clip's: every cell at its own time, made between the frames beside it (held_fill.upsample).+ try:+ frames, held_record["out_fps"] = _upsample(frames, interpolate, ring=ring, fps=fps, out_fps=out_fps)+ except (ValueError, rife_mod.RifeUnavailable) as exc:+ error = (f"video-loop: {exc}; --out-fps {out_fps:g} makes the frames between the clip's — fix RIFE, or cut it "+ "without --out-fps (docs/loop-repair.md section 7)")+ refuse(target, out_dir, name, {**report_base, "status": "failed", "error": error, "cycle": cycle})+ raise SystemExit(error) from exc+ for line in _out_fps_lines(held_record["out_fps"]):+ print(f"video-loop: warning: {name}: {line}", file=sys.stderr)+ if held_record["out_fps"]["applied"]:+ upsampled = held_record["out_fps"]["times"]+ report_base["seam_measurement"] = "rendered-cells"+ as_filmed = {} # the cells are each made at a time of their own: read as they play+ if not ring:+ cycle_seconds = len(frames) / out_fps # first to last frame as filmed, each cell 1/out_fps+ n_out = min(n_asked, len(frames))+ # The cut as delivered, read again: its poses over its cells.+ held_record.update(held_fill_mod.reading(held_fill_mod.same_steps(frames)))+ C = len(frames) # the cells delivered: the cut's frames, or more at --out-fpscycle_dir.mkdir(parents=True, exist_ok=True)for old in cycle_dir.glob("frame-*.png"):old.unlink()@@ -2680,9 +2825,14 @@ def _cut_loop(# The cut as its seam is read: each cell given way to the frame beside it as filmed (`seam_as_filmed`).seam_frames = [as_filmed.get(k, f) for k, f in enumerate(frames)]strip_meta["source_cut"] = {"source": report_base["source"], "start": i, "length": L,- "samples": [i + k for k in strip_meta["sample_indices"]]}+ **({"samples": [i + k for k in strip_meta["sample_indices"]]} if upsampled is None else+ {"times": [round(i + upsampled[k], 4) for k in strip_meta["sample_indices"]]})}+ if upsampled is not None:+ # Each cell is a time of its own, at a rate above the clip's: the cells are not the clip's frames.+ strip_meta.update(out_fps=out_fps, source_fps=fps)if cycle["kind"] in nonloop.KINDS:- strip_meta.update(nonloop.metadata(cycle, strip_meta["sample_indices"]))+ strip_meta.update(nonloop.metadata(cycle, strip_meta["sample_indices"] if upsampled is None else+ [upsampled[k] for k in strip_meta["sample_indices"]]))if state:# `video-cycle-align` reads the gait floor of this state when it screens a loop for two cycles.strip_meta["state"] = str(state).strip().lower()@@ -2698,6 +2848,8 @@ def _cut_loop(} | ({"why": report_base["cycle_drawings"]["why"]} if "why" in report_base["cycle_drawings"] else {})if "clip_feet" in report_base:strip_meta["clip_feet"] = report_base["clip_feet"]+ # The cut's held cells, what became of them, and its poses over its cells (docs/loop-repair.md section 7).+ strip_meta["held_fill"] = held_fill_mod.public(held_record)# A cut frame that is no longer the frame as filmed for a filmed ghost, and one kept with no clean frame beside# it: `cycle/` is the alignment's material (`cycle.source/`), whose screen no longer sees a ghost given way, so the# strip says it, and an alignment carries it over (frames of the cut).@@ -2734,9 +2886,10 @@ def _cut_loop(idx = [strip_meta["sample_indices"][k] for k in preview_indices]pick = [strip.crop((k * strip_meta["w"], 0, (k + 1) * strip_meta["w"], strip_meta["h"])) for k in preview_indices]else:- idx = [min(L - 1, i2) for i2 in (round(k * L / n_out) for k in range(n_out))]- pick = resampled_cells(strip, strip_meta, idx, L)- seam_idx = [i + j for j in idx]+ idx = [min(C - 1, i2) for i2 in (round(k * C / n_out) for k in range(n_out))]+ pick = resampled_cells(strip, strip_meta, idx, C)+ # The source frames the distances were read on: a cell made at --out-fps reads as the frame at or before its time.+ seam_idx = [i + (j if upsampled is None else min(L - 1, math.floor(upsampled[j]))) for j in idx]on_cells = report_base["seam_measurement"] == "rendered-cells"# A walk's or run's seam is read between its drawings, as its steps are (`seam_drawings`), where the seam ratio gates# the cut: not a pin or a cut played once. Any other loop's, and a walk drawn a frame each, on every frame.@@ -2757,7 +2910,7 @@ def _cut_loop(if on_cells or ramped:# The actual corrected/repaired/resampled strip cells, with the same limit — a cell given way to the frame# beside it as filmed (`seam_as_filmed`), on the strip the cut makes with those frames; a walk's between its drawings.- cells = resampled_cells(*strip_of(seam_frames), idx, L) if as_filmed else pick+ cells = resampled_cells(*strip_of(seam_frames), idx, C) if as_filmed else pickon, cells_read = seam_drawings(cells) if by_drawing else (list(range(len(cells))), None)adjacent, wrap, steps = _seam_on_cells([cells[k] for k in on])if ramped:@@ -2979,6 +3132,19 @@ def add_arguments(parser: argparse.ArgumentParser) -> None:"another holds a cycle. Where none does: warn (default), the cut the search takes with the turn in, ""and a warning line; refuse, the clip is refused in a line of its own (`video-loop: the body turns ""in the walk`), to be filmed again at the still's angle")+ parser.add_argument("--fill-held", choices=held_fill_mod.MODES, default="auto",+ help="neighbour cells of the cut that show the same picture (a frame shown twice or three times): auto "+ "(default) makes each run of them again with RIFE's frames between the pose before and the pose "+ f"after, the cut's length, beat, first and last cells and wrap kept, and a run longer than "+ f"{held_fill_mod.HOLD_MAX} cells, the opening or closing pose of a cut played once, a loop's last "+ "cells and a cut drawn on twos or threes kept as filmed; off cuts them as filmed. Either way the report and the strip metadata record "+ "the held runs and the poses over the cells (`held_fill`, docs/loop-repair.md section 7); with no "+ "RIFE installed the cells are shown as filmed, with a warning")+ parser.add_argument("--out-fps", type=float, default=None,+ help="give the cut at this rate, above the clip's (--fps): every cell at its own time, made by RIFE "+ "between the frames beside it — never a frame shown again. A loop keeps its cycle's seconds, a "+ "cut played once runs from its first frame to its last; the strip metadata says `out_fps`. With no "+ "RIFE installed the cut is delivered at its own rate, with a warning (docs/loop-repair.md section 7)")parser.add_argument("--name", default="loop", help="basename for strip/gif/webp outputs")parser.add_argument("--report", type=Path)@@ -3001,6 +3167,7 @@ def run(**kwargs: object) -> int:unfixed=str(kwargs.get("unfixed") or "warn"),seam_pop_max=kwargs.get("seam_pop_max", repair_mod.SEAM_POP_REFERENCE), # type: ignore[arg-type]body_turn=str(kwargs.get("body_turn") or "warn"),+ fill_held=str(kwargs.get("fill_held") or "auto"), out_fps=kwargs.get("out_fps"), # type: ignore[arg-type])summary = {k: payload[k] for k in ("state", "frames_total", "window", "cycle_seconds", "n_out", "delay_ms", "resampled_seam_ratio", "specks_dropped", "report")}summary["cycle"] = {k: payload["cycle"].get(k) for k in ("kind", "start", "length", "period_global", "ratio", "review_recommended", "half_period_guard", "fundamental")}@@ -3068,6 +3235,11 @@ def run(**kwargs: object) -> int:if payload.get("retake"):summary["retake"] = {k: payload["retake"][k] for k in ("reason", "remedy")}summary["strip"] = {k: payload["strip"][k] for k in ("path", "frames", "w", "h", "body_h", "delay_ms")}+ held = payload["held_fill"]+ summary["held_fill"] = {"poses_cells": held_fill_mod.said(held), "before": held_fill_mod.said(held["before"]),+ "held_runs": held["held_runs"], "made": held["made"],+ **({"unmade": held["unmade"]["cells"]} if "unmade" in held else {}),+ **({"out_fps": {k: held["out_fps"][k] for k in ("asked", "applied", "cells")}} if "out_fps" in held else {})}print(json.dumps(summary, ensure_ascii=False, indent=2))return 0diff --git a/sprite_gen/video/source.py b/sprite_gen/video/source.pyindex d51107c..959e8a8 100644--- a/sprite_gen/video/source.py+++ b/sprite_gen/video/source.py@@ -207,7 +207,9 @@ def project(baseline: Any, source: Source) -> tuple[Projection | None, str | Non# A held cut is read again only where its report records each frame's move, and the cut's frames before repair to# prove every one of them on (`source_projection`, the moves of the cells the repair replaced included).held = bool(hold.get("applied"))- if (any(k in m for k in ("cycle_align", "motion_anchor", "wrap_blend"))+ # A cut whose held cells were made again (`held_fill`), or whose cells are times of their own (`out_fps`), shows+ # frames the source does not hold.+ if (any(k in m for k in ("cycle_align", "motion_anchor", "wrap_blend", "out_fps")) or (m.get("held_fill") or {}).get("made")or held and ("cut_frames" not in hold or report.get("source_projection") is None)):return None, "source-processing-unsupported"moves, pad = _cut_moves(hold, n) if held else (None, None)diff --git a/sprite_gen/video/stop.py b/sprite_gen/video/stop.pyindex 9029105..113c8c1 100644--- a/sprite_gen/video/stop.py+++ b/sprite_gen/video/stop.py@@ -68,6 +68,7 @@ from sprite_gen.util.gif_utils import save_clean_giffrom sprite_gen.util.resample import resize_cellfrom sprite_gen.video import evidence as evidence_modfrom sprite_gen.video import gait_fallback+from sprite_gen.video import held_fill as held_fill_modfrom sprite_gen.video import loop as loop_modfrom sprite_gen.video import nonloopfrom sprite_gen.video.interpolation_quality import ghost_screen@@ -132,6 +133,9 @@ def read_loop(meta_path: Path) -> tuple[dict[str, Any], list[Image.Image], str]:raise SystemExit(f"{PROG}: {strip_path.name} is {strip.size[0]}x{strip.size[1]}, its sidecar says {n * w}x{h}")if meta.get("loop") is False:raise SystemExit(f"{PROG}: {meta_path.name} plays once (loop false); a stop leaves a loop")+ if "out_fps" in meta:+ raise SystemExit(f"{PROG}: {meta_path.name} was cut at --out-fps {meta['out_fps']:g}, its cells each a time of their own; "+ "a stop is cut from a loop at its clip's rate (video-loop without --out-fps)")state = str(meta.get("state") or "")if not loop_mod.profile_for(state).gait:raise SystemExit(f"{PROG}: {meta_path.name} is a {state or 'state-less'} loop; a stop is cut from a walk or run loop")@@ -422,7 +426,13 @@ def make_stop(frames_dir: Path, loop_meta: Path, out_dir: Path, *, name: str = "last = _box(stop_cells[-1])# Read as filmed, at the keyed frames' own size, as video-loop reads its cut: a part-covered band is a# number of pixels thick, and scaled down a ghost's band falls under it.- screen = ghost_screen([Image.open(files[j]).convert("RGBA") for j in shown])+ filmed = [Image.open(files[j]).convert("RGBA") for j in shown]+ screen = ghost_screen(filmed)+ # The stop's frames shown again (docs/loop-repair.md section 7): named, never made between — a stop plays the clip's+ # filmed frames, none made between two others.+ reading = held_fill_mod.reading(held_fill_mod.same_steps(filmed))+ held = {"mode": "off", "why": "a stop plays the clip's filmed frames, none made between two others", "made": [],+ "before": reading, **reading}for g in screen.get("ghosts", []):g["clip_frame"] = shown[g["frame"]]delay = round(1000 / fps, 2)@@ -435,7 +445,7 @@ def make_stop(frames_dir: Path, loop_meta: Path, out_dir: Path, *, name: str = ""from_loop": {"strip_sha256": strip_sha, "state": meta.get("state"), "frames": len(cells), "w": w, "h": h,"from_cell": found["entry"]["from_cell"]},"source_cut": {"source": identity, "frames": shown, "entry": found["entry"]["frame"], "rest_end": found["rest"]["end"]},- "speed": speed, "seam_steps": found["seam"]["steps"],+ "speed": speed, "seam_steps": found["seam"]["steps"], "held_fill": held,}out_dir.mkdir(parents=True, exist_ok=True)strip = Image.new("RGBA", (cw * len(stop_cells), ch), (0, 0, 0, 0))@@ -469,6 +479,9 @@ def make_stop(frames_dir: Path, loop_meta: Path, out_dir: Path, *, name: str = "f"{100 * g['ghost']:.2f} % of its body — a filmed ghost, kept as filmed", file=sys.stderr)if not screen["reads"]:print(f"{PROG}: warning: the ghost screen does not read this stop — {screen['why']}", file=sys.stderr)+ for run in held["held_runs"]:+ print(f"{PROG}: warning: cells {run['start']}-{run['start'] + run['length'] - 1} show one picture "+ f"({held_fill_mod.said(held)} poses/cells): the clip stalls there, played as filmed", file=sys.stderr)payload["report"] = str(target)return payloaddiff --git a/tests/frames/test_chroma_decontam.py b/tests/frames/test_chroma_decontam.pyindex e582983..4199823 100644--- a/tests/frames/test_chroma_decontam.py+++ b/tests/frames/test_chroma_decontam.py@@ -680,7 +680,7 @@ def test_video_set_hands_its_decontam_to_video_frames_and_lists_the_warning(tmp_monkeypatch.setattr(batch.frames_mod, "run_frames", frames_stub)monkeypatch.setattr(batch.loop_mod, "run_loop", lambda *a, **kw: {"cycle": {"length": 10, "period_global": 10, "ratio": 0.2},- "resampled_seam_ratio": 0.2, "n_out": 10, "gif": {"file": "loop.gif"},+ "resampled_seam_ratio": 0.2, "held_fill": {"cells": 10, "poses": 10, "held_runs": [], "made": [], "before": {"cells": 10, "poses": 10, "held_runs": []}}, "n_out": 10, "gif": {"file": "loop.gif"},"webp": {"file": "loop.webp"}, "strip": {"path": "strip.png"}})monkeypatch.setattr(batch, "_staggered_start", lambda gap: None)still = Path(__file__).parents[1] / "fixtures" / "facing" / "left.png"diff --git a/tests/video/held_fill_inputs.py b/tests/video/held_fill_inputs.pynew file mode 100644index 0000000..b594f14--- /dev/null+++ b/tests/video/held_fill_inputs.py@@ -0,0 +1,134 @@+# SPDX-License-Identifier: Apache-2.0+"""Synthetic clips for the held-cell tests (tests/video/test_held_fill.py): figures that move every frame, and the same+figures with frames shown again. No real footage."""++from __future__ import annotations++import math+from pathlib import Path++import numpy as np+from PIL import Image++W, H = 120, 140+N = 24 # a walk's cycle, frames+++def walker(phase: float) -> Image.Image:+ """A torso and head that bob a pixel with the step, and a dark foot going round a circle at an even speed, far enough+ a frame that a third of one moves it a pixel or more: every frame moves, and every time between two frames."""+ a = np.zeros((H, W, 4), dtype=np.uint8)+ bob = round(2 * (1 + math.cos(2 * phase)) / 2)+ a[30 + bob:100, 50:70] = (90, 90, 200, 255)+ a[10 + bob:30 + bob, 48:72] = (230, 190, 160, 255)+ fx, fy = 60 + round(28 * math.cos(phase)), 105 + round(28 * math.sin(phase))+ a[fy - 6:fy + 6, fx - 6:fx + 6] = (60, 60, 60, 255)+ return Image.fromarray(a, "RGBA")+++def walk(frames: int = N + 6) -> list[Image.Image]:+ return [walker(2 * math.pi * k / N) for k in range(frames)]+++def hopper(y: int, *, x: int = 52) -> Image.Image:+ """A block body standing `y` px off the floor, with an arm across it."""+ a = np.zeros((H, W, 4), dtype=np.uint8)+ top = 40 - y+ a[top:top + 80, x:x + 18] = (200, 80, 30, 255)+ a[top + 20:top + 26, x - 10:x + 28] = (60, 60, 60, 255)+ return Image.fromarray(a, "RGBA")+++def hop(rest: int = 12, air: int = 14) -> list[Image.Image]:+ """Standing still, one hop up and down over `air` frames (a different height every frame), standing still again."""+ heights = [round(36 * math.sin(math.pi * (k + 1) / (air + 1))) + k % 2 for k in range(air)]+ return [hopper(0)] * rest + [hopper(h) for h in heights] + [hopper(0)] * rest+++def swing(frames: int = 25) -> list[Image.Image]:+ """An arm swung out and back once, the last frame drawing the first again (a clip pinned to end on its start)."""+ out = []+ for k in range(frames):+ a = np.zeros((H, W, 4), dtype=np.uint8)+ a[30:110, 50:70] = (90, 90, 200, 255)+ # even reaches, an odd pixel more every other frame: no two neighbours alike, the last the first again+ reach = 2 * round(15 * math.sin(math.pi * k / (frames - 1))) + (k % 2 if 0 < k < frames - 1 else 0)+ a[50:58, 70:76 + reach] = (60, 60, 60, 255)+ out.append(Image.fromarray(a, "RGBA"))+ return out+++def topple(count: int = 60) -> list[Image.Image]:+ """A body that stands still, sinks to the ground a pixel or more every frame, then lies still (a once cut's end)."""+ out = []+ for k in range(count):+ t = min(1.0, max(0.0, (k - 6) / 30))+ a = np.zeros((96, 128, 4), dtype=np.uint8)+ height = round(64 - 40 * t)+ width = round(16 + 36 * t)+ a[86 - height:86, 40:40 + width] = (200, 80, 30, 255)+ out.append(Image.fromarray(a, "RGBA"))+ return out+++def save(frames: list[Image.Image], d: Path) -> Path:+ d.mkdir(parents=True)+ for k, f in enumerate(frames):+ f.save(d / f"{k:04d}.png")+ return d+++def shown_again(frames: list[Image.Image], at: dict[int, int]) -> list[Image.Image]:+ """`frames` with frame k shown `at[k]` times (its copies byte for byte the same), the rest once: a clip that stalls."""+ out = []+ for k, f in enumerate(frames):+ out.extend([f] * at.get(k, 1))+ return out+++def planter(reach: float) -> Image.Image:+ """A body standing on a foot planted on the floor (a light block, the same in every frame), an arm reaching out+ `reach` px."""+ a = np.zeros((H, W, 4), dtype=np.uint8)+ a[30:110, 50:70] = (90, 90, 200, 255)+ a[110:H - 8, 52:68] = (200, 160, 40, 255)+ a[50:58, 70:76 + round(reach)] = (60, 60, 60, 255)+ return Image.fromarray(a, "RGBA")+++def slid(image: Image.Image, dx: int = 3) -> Image.Image:+ """`image` with its planted foot moved `dx` px along the floor: an in-between that drags a contact."""+ a = np.asarray(image).copy()+ foot = a[110:H - 8].copy() # under the body: the foot alone+ a[110:H - 8] = 0+ a[110:H - 8, dx:] = foot[:, : W - dx]+ return Image.fromarray(a, "RGBA")+++class Between:+ """Stand-in interpolator: the true frame of a synthetic clip between two of its frames, drawn again at its own+ time. Each frame is known by its pixels — `draw` at each of `times`, and every frame it makes — so a frame made+ from a frame made is known too. With a `period`, a later frame drawn at an earlier time is the next cycle's+ (a loop's wrap). `calls` lists (time of a, time of b, t) of each frame asked for."""++ def __init__(self, draw, times, *, period: float | None = None, after=None):+ self.draw, self.period, self.after = draw, period, after+ self.known: dict[bytes, float] = {}+ for t in times:+ self.known.setdefault(draw(t).tobytes(), float(t) % period if period else float(t))+ self.calls: list[tuple[float, float, float]] = []++ def __call__(self, a: Image.Image, b: Image.Image, t: float) -> Image.Image:+ ta, tb = self.known[a.tobytes()], self.known[b.tobytes()]+ if self.period and tb <= ta:+ tb += self.period+ at = ta + t * (tb - ta)+ im = self.draw(at % self.period if self.period else at)+ self.known.setdefault(im.tobytes(), at % self.period if self.period else at)+ self.calls.append((ta, tb, round(t, 4)))+ return self.after(im) if self.after else im+++def walk_at(time: float) -> Image.Image:+ """The walker `time` frames into its cycle."""+ return walker(2 * math.pi * time / N)diff --git a/tests/video/test_attack_motion.py b/tests/video/test_attack_motion.pyindex 6e0ceb4..3c7807d 100644--- a/tests/video/test_attack_motion.py+++ b/tests/video/test_attack_motion.py@@ -109,7 +109,7 @@ def test_video_set_gives_every_state_the_same_body_height(tmp_path: Path, monkeydef fake_loop(frames_dir, out_dir, **kw):seen.append((kw["state"], kw.get("body_height")))cycles[kw["state"]] = kw.get("cycle_mode")- return {"cycle": {"kind": "periodic", "length": 24, "period_global": 24, "ratio": 0.2}, "resampled_seam_ratio": 0.3,+ return {"cycle": {"kind": "periodic", "length": 24, "period_global": 24, "ratio": 0.2}, "resampled_seam_ratio": 0.3, "held_fill": {"cells": 10, "poses": 10, "held_runs": [], "made": [], "before": {"cells": 10, "poses": 10, "held_runs": []}},"n_out": 8, "gif": {"file": "g"}, "webp": {"file": "w"}, "strip": {"path": "s", "drift_px": 0}}def video(image, prompt, out, report, **kw):diff --git a/tests/video/test_batch_facing.py b/tests/video/test_batch_facing.pyindex 0074d6d..e24a3a6 100644--- a/tests/video/test_batch_facing.py+++ b/tests/video/test_batch_facing.py@@ -18,7 +18,7 @@ def offline(monkeypatch):"keyed_dir": str(out)})monkeypatch.setattr(batch.loop_mod, "run_loop", lambda *a, **kw: {"cycle": {"length": 10, "period_global": 10, "ratio": 0.2},- "resampled_seam_ratio": 0.2, "n_out": 10, "gif": {"file": "loop.gif"},+ "resampled_seam_ratio": 0.2, "held_fill": {"cells": 10, "poses": 10, "held_runs": [], "made": [], "before": {"cells": 10, "poses": 10, "held_runs": []}}, "n_out": 10, "gif": {"file": "loop.gif"},"webp": {"file": "loop.webp"}, "strip": {"path": "strip.png"}})monkeypatch.setattr(batch, "_staggered_start", lambda gap: None)diff --git a/tests/video/test_batch_handed.py b/tests/video/test_batch_handed.pyindex afbfdf6..da7405b 100644--- a/tests/video/test_batch_handed.py+++ b/tests/video/test_batch_handed.py@@ -24,7 +24,7 @@ def offline(monkeypatch):def run_loop(*a, **kw):loops.append((kw["name"], kw["facing"]))- return {"cycle": {"length": 10, "period_global": 10, "ratio": 0.2}, "resampled_seam_ratio": 0.2, "n_out": 10,+ return {"cycle": {"length": 10, "period_global": 10, "ratio": 0.2}, "resampled_seam_ratio": 0.2, "held_fill": {"cells": 10, "poses": 10, "held_runs": [], "made": [], "before": {"cells": 10, "poses": 10, "held_runs": []}}, "n_out": 10,"gif": {"file": "loop.gif"}, "webp": {"file": "loop.webp"}, "strip": {"path": "strip.png"}}monkeypatch.setattr(batch.loop_mod, "run_loop", run_loop)monkeypatch.setattr(batch, "_staggered_start", lambda gap: None)diff --git a/tests/video/test_body_plan.py b/tests/video/test_body_plan.pyindex ebb1c2e..c020c2b 100644--- a/tests/video/test_body_plan.py+++ b/tests/video/test_body_plan.py@@ -258,7 +258,7 @@ def test_video_set_says_the_body_plan_in_the_redraw_and_the_clip(tmp_path, monkemonkeypatch.setattr(batch.frames_mod, "run_frames", lambda clip, out, **kw: {"fps": 24, "frames": 10, "alpha_zero_pct_min": 50, "alpha_zero_pct_max": 60, "keyed_dir": str(out)})monkeypatch.setattr(batch.loop_mod, "run_loop", lambda *a, **kw: {- "cycle": {"length": 10, "period_global": 10, "ratio": 0.2}, "resampled_seam_ratio": 0.2, "n_out": 10,+ "cycle": {"length": 10, "period_global": 10, "ratio": 0.2}, "resampled_seam_ratio": 0.2, "held_fill": {"cells": 10, "poses": 10, "held_runs": [], "made": [], "before": {"cells": 10, "poses": 10, "held_runs": []}}, "n_out": 10,"gif": {"file": "loop.gif"}, "webp": {"file": "loop.webp"}, "strip": {"path": "strip.png"}})monkeypatch.setattr(batch, "_staggered_start", lambda gap: None)redraws: list[str] = []diff --git a/tests/video/test_gait_guard_anchor_wide.py b/tests/video/test_gait_guard_anchor_wide.pyindex ec2e7ad..3a00759 100644--- a/tests/video/test_gait_guard_anchor_wide.py+++ b/tests/video/test_gait_guard_anchor_wide.py@@ -218,7 +218,7 @@ def test_video_set_passes_shape_and_anchor_through(tmp_path: Path, monkeypatch,def fake_loop(frames_dir, out_dir, **kw):seen["anchor"] = kw.get("anchor")- report = {"cycle": {"kind": "periodic", "length": 24, "period_global": 24, "ratio": 0.2}, "resampled_seam_ratio": 0.3, "n_out": 8, "gif": {"file": "g"}, "webp": {"file": "w"}, "strip": {"path": "s", "drift_px": 0}}+ report = {"cycle": {"kind": "periodic", "length": 24, "period_global": 24, "ratio": 0.2}, "resampled_seam_ratio": 0.3, "held_fill": {"cells": 10, "poses": 10, "held_runs": [], "made": [], "before": {"cells": 10, "poses": 10, "held_runs": []}}, "n_out": 8, "gif": {"file": "g"}, "webp": {"file": "w"}, "strip": {"path": "s", "drift_px": 0}}if anchor == "motion-auto":report["motion_anchor"] = {"applied": False, "reason": "fine-match-at-search-boundary"}return reportdiff --git a/tests/video/test_held_fill.py b/tests/video/test_held_fill.pynew file mode 100644index 0000000..a93566f--- /dev/null+++ b/tests/video/test_held_fill.py@@ -0,0 +1,470 @@+# SPDX-License-Identifier: Apache-2.0+"""Held cells (sprite_gen/video/held_fill.py, docs/loop-repair.md section 7): neighbour cells of a cut that show the+same picture are found on every cut `video-loop` makes, recorded (`held_fill`: the held runs, the poses and the cells)+and, by default, made again as the frames between the pose before them and the pose after; the cut's first and last+cells, its length, its beat and its wrap stay as they were, and a part standing still in both stays where it stood.+A clip asked for at a higher rate than it was filmed (`--out-fps`) is given frames between, not frames shown again.+With no RIFE the cut is delivered as filmed with a warning naming the motion and the install line; `--fill-held off`+cuts it as before. A cut with no held cell comes out byte for byte as before (the six inputs below, pinned on the+engine before the fill).++The interpolator is a stand-in that draws the synthetic clip again at the time asked for (`Between`), so the tests+need no binary and say which frame comes back."""++from __future__ import annotations++import hashlib+import json+import os+from pathlib import Path++import numpy as np+import pytest+from PIL import Image++from sprite_gen.video import held_fill+from sprite_gen.video import loop as loop_mod+from tests.video.held_fill_inputs import (N, Between, hop, planter, save, shown_again, slid, swing, topple, walk,+ walk_at)+++def _no_rife(monkeypatch, tmp_path: Path) -> None:+ """No RIFE anywhere the engine looks: no SPRITE_GEN_RIFE, no directory on PATH holding one, an empty data+ directory."""+ monkeypatch.delenv("SPRITE_GEN_RIFE", raising=False)+ path = [d for d in os.environ.get("PATH", "").split(os.pathsep) if d and not (Path(d) / "rife-ncnn-vulkan").exists()]+ monkeypatch.setenv("PATH", os.pathsep.join(path))+ monkeypatch.setenv("SPRITE_GEN_DATA_DIR", str(tmp_path / "data"))+++def _run(tmp_path: Path, frames: list[Image.Image], name: str = "m", **kw) -> dict:+ keyed = save(frames, tmp_path / f"{name}-keyed")+ return loop_mod.run_loop(keyed, tmp_path / f"{name}-out", fps=24.0, min_len=None, max_len=None, n_out=None,+ seam_max=loop_mod.SEAM_RATIO_MAX, name=name, report_path=None, **kw)+++def _sha(path: Path) -> str:+ return hashlib.sha256(path.read_bytes()).hexdigest()+++def _bytes(out: Path, name: str) -> dict[str, str]:+ cycle = hashlib.sha256(b"".join(p.read_bytes() for p in sorted((out / "cycle").glob("frame-*.png")))).hexdigest()+ return {"strip": _sha(out / f"{name}.strip.png"), "gif": _sha(out / f"{name}.gif"), "webp": _sha(out / f"{name}.webp"),+ "cycle": cycle}+++def _meta(rep: dict) -> dict:+ return json.loads(Path(rep["strip"]["path"]).with_suffix("").with_suffix(".strip.json").read_text())+++def _cycle(rep: dict) -> list[Image.Image]:+ return [Image.open(p).convert("RGBA") for p in sorted((Path(rep["out_dir"]) / "cycle").glob("frame-*.png"))]+++# Pinned on the engine before the fill (886936e): a cut with no held cell is delivered as it was, byte for byte.+UNHELD = {+ "walk-fixed": (lambda: walk(), dict(state="walk", cycle_mode="fixed", start=0, length=N, anchor="none", repair="off"), {+ "strip": "2335f3f5da57e08074113d6d30b89a672a3ff1f969ff645c667e07f3d08eaba1",+ "gif": "27f05c499a83e66621c9853efdb61fb591bfa386fbceb159c0a09822f79989c9",+ "webp": "4c9922b16ff73385a87f363d7aac567b5f1885df667fafce91702935fb8451b7",+ "cycle": "26be9c07e34ad0976013e7f5ce5b40af10c071ef78fb6b749ac389deb01e4a8d"}),+ "walk-auto": (lambda: walk(N * 3 + 4), dict(state="walk", repair="off"), {+ "strip": "d9c2143deb3cb3f90d932a4cd47132dcc196a2c83227eea85588c58b3cbc2ca3",+ "gif": "1b53603c32cd6bcca445374eb9403a68d9e1914c6bdf126c49b5312fadd9d62e",+ "webp": "6ae3c4465ef484691deb63883cee6439f8e401ae6d9fc121fd4233a9d8c2215a",+ "cycle": "73de53310593c2792d4ef3b957e4f303befaeb2db5dc79c2e39649a66c0d108a"}),+ "hop-one-shot": (lambda: hop(), dict(state="jump", cycle_mode="one-shot"), {+ "strip": "4c2317151d8ac0f78b2cf05fd00f90d77ec6a84adb418e076693675b92155032",+ "gif": "084867009d141d032adea38edaec5e7277f9f7cc03d59e1498b926c5e4146546",+ "webp": "5d6b8b67c7e515096c002da2f715088b12e1b1f2174de865bda35dd4d2ab8a6f",+ "cycle": "9ccfbada05cf1b964bebea30c67cb92170713f6950dfa348a9d54afb20ddf43a"}),+ "swing-pinned": (lambda: swing(), dict(state="attack", cycle_mode="pinned", anchor="none"), {+ "strip": "74ea7ee259b254744c76ab3d2b5ca3a2a0ee8baa04d7f7beafd1ecf39966d76d",+ "gif": "3944bc371f1b167707a06c069411960d7043f40d784108cb4c231adcfee77fcd",+ "webp": "feea1f26d5dcb5eceb49706440db1c0037b5a95c692ca4ddfa58072c28e3ec70",+ "cycle": "fee8b88afd0ccbbde09c6e14411514bedf030a47dde290a9218fe9c00bbe7457"}),+ "topple-once": (lambda: topple(), dict(state="death", cycle_mode="once"), {+ "strip": "59629dc0b1ba7796e5a7650fc99696e22d84b958012e9d898bb321860118ed0e",+ "gif": "0f71d5df9da9ca3645193481c042dde32cfe6d9d344018835ee09715a08a7809",+ "webp": "6adb35ceaa211abb535e46998df6b513bfd58fa57340d47af652fd28f784a24d",+ "cycle": "6d15da447a24801ec6f4618328e18c7e75dc15a871649d47dd1889db301a8570"}),+ "swing-once-return": (lambda: swing(), dict(state="leap", cycle_mode="once-return", anchor="none"), {+ "strip": "67c113649569ee63f704ba0f4fc9c70a9c26ec50e0e5f25937ebb8c8db3d4638",+ "gif": "af0b2a32648ee4316edbabd5392ea652519a51939e67407c80650859c5fa21da",+ "webp": "ba0ad2de4a5b264ebfc61cd0657f22864340629e842abd2e1ec3929c39362ada",+ "cycle": "c0a3d63b81c139f83566e658959214f965efd136b85e810c86d78bb57551375e"}),+}++[email protected]("case", sorted(UNHELD))+def test_a_cut_with_no_held_cell_is_delivered_byte_for_byte_as_before(case, tmp_path, monkeypatch):+ _no_rife(monkeypatch, tmp_path) # nothing is made, so nothing looks for RIFE+ frames, kw, pinned = UNHELD[case]+ rep = _run(tmp_path, frames(), case, **kw)+ assert _bytes(Path(rep["out_dir"]), case) == pinned+ record = _meta(rep)["held_fill"]+ assert record == held_fill.public(rep["held_fill"])+ assert record["mode"] == "auto" and record["made"] == [] and "unmade" not in record+ cells = rep["cycle"]["length"]+ assert record["cells"] == cells+ if case == "topple-once":+ # It lies still for its last five cells: the cut's closing pose, kept.+ assert record["held_runs"] == [{"start": cells - 5, "length": 5}]+ assert record["before"]["held_runs"][0]["filled"] is False+ assert record["poses"] == cells - 4+ else:+ assert record["held_runs"] == [] and record["poses"] == cells+++STALLED = {5: 2, 13: 3} # the walk's frame 5 shown twice, frame 13 three times+STALLED_OFF = { # the stalled walk cut on the engine before the fill (886936e)+ "strip": "f208b850b2265fd6ce10ce4993998895f70a065f5cea118ef71230581f02ad15",+ "gif": "c25a5d96b123e0237045774d689b9d2205ca51f16e67745e8ea9d290b285e3fb",+ "webp": "117d7b8b18b2e2ff42434890ca58efd0f0855c1db2f9b55515174ac481c749c7",+ "cycle": "5753f68c10942635e9518220423301f04805cbb845abaea7300ba01fb4e1c8cb",+}+STALLED_CUT = dict(state="walk", cycle_mode="fixed", start=0, length=N + 3, anchor="none", repair="off")+++def test_a_stalled_walk_has_its_held_cells_made_between_the_poses_beside_them(tmp_path):+ between = Between(walk_at, range(N + 6), period=N)+ rep = _run(tmp_path, shown_again(walk(), STALLED), interpolate=between, **STALLED_CUT)+ record = rep["held_fill"]+ assert record["before"]["cells"] == N + 3 and record["before"]["poses"] == N+ assert [(r["start"], r["length"], r["filled"]) for r in record["before"]["held_runs"]] == [(5, 2, True), (14, 3, True)]+ assert record["made"] == [6, 15, 16]+ # Each made at its own time between the pose before the run and the pose after it: half way, a third and two thirds.+ assert sorted(between.calls) == [(5.0, 6.0, 0.5), (13.0, 14.0, 0.3333), (13.0, 14.0, 0.6667)]+ assert (record["cells"], record["poses"], record["held_runs"]) == (N + 3, N + 3, [])+ cells = _cycle(rep)+ assert cells[6].tobytes() == walk_at(5.5).tobytes()+ assert cells[15].tobytes() == walk_at(13 + 1 / 3).tobytes()+ # Every other cell is the cut's as filmed: the first and the last, the length, the beat.+ filmed = shown_again(walk(), STALLED)[: N + 3]+ assert len(cells) == N + 3+ assert all(cells[k].tobytes() == filmed[k].tobytes() for k in range(N + 3) if k not in (6, 15, 16))+ assert _meta(rep)["held_fill"] == held_fill.public(record)+ assert rep["seam_measurement"] == "rendered-cells"+++def test_fill_held_off_cuts_the_stalled_walk_as_before_and_still_names_its_runs(tmp_path):+ rep = _run(tmp_path, shown_again(walk(), STALLED), fill_held="off", **STALLED_CUT)+ assert _bytes(Path(rep["out_dir"]), "m") == STALLED_OFF+ record = rep["held_fill"]+ assert record["mode"] == "off" and record["made"] == []+ assert [(r["start"], r["length"], r["filled"], r["why"]) for r in record["before"]["held_runs"]] == [+ (5, 2, False, "--fill-held off"), (14, 3, False, "--fill-held off")]+ assert (record["cells"], record["poses"]) == (N + 3, N)+++def test_no_rife_delivers_the_held_cells_as_filmed_and_says_which_motion(tmp_path, monkeypatch, capsys):+ _no_rife(monkeypatch, tmp_path)+ rep = _run(tmp_path, shown_again(walk(), STALLED), name="stalled-walk", **STALLED_CUT)+ assert rep["status"] == "passed"+ out = Path(rep["out_dir"])+ # The images are the cut as filmed: what --fill-held off delivers.+ off = _run(tmp_path, shown_again(walk(), STALLED), name="off", fill_held="off", **STALLED_CUT)+ assert {k: v for k, v in _bytes(out, "stalled-walk").items()} == _bytes(Path(off["out_dir"]), "off")+ record = rep["held_fill"]+ assert record["made"] == [] and record["unmade"]["cells"] == [6, 15, 16]+ assert record["unmade"]["install"] == loop_mod.rife_mod.install_command()+ assert (record["cells"], record["poses"]) == (N + 3, N)+ err = capsys.readouterr().err+ assert "stalled-walk" in err and "RIFE is not installed" in err and loop_mod.rife_mod.install_command() in err+++def test_a_hold_longer_than_three_cells_is_the_motion_s_own_and_kept(tmp_path):+ between = Between(walk_at, range(N + 6), period=N)+ rep = _run(tmp_path, shown_again(walk(), {9: 5}), interpolate=between,+ **{**STALLED_CUT, "length": N + 4})+ run = rep["held_fill"]["before"]["held_runs"]+ assert [(r["start"], r["length"], r["filled"]) for r in run] == [(9, 5, False)]+ assert "longer than" in run[0]["why"]+ assert between.calls == [] and rep["held_fill"]["held_runs"] == [{"start": 9, "length": 5}]+++def test_a_walk_drawn_on_twos_is_limited_animation_and_kept(tmp_path):+ # Each drawing shown twice, as a clip of 12 drawings a second at 24 fps is (sprite_gen/video/held.py).+ twos = shown_again(walk(), {k: 2 for k in range(N + 6)})+ cut = {**STALLED_CUT, "length": 2 * N}+ between = Between(walk_at, range(N + 6), period=N)+ rep = _run(tmp_path, twos, interpolate=between, **cut)+ record = rep["held_fill"]+ assert rep["cycle_drawings"]["hold"] == 2 and record["drawn"] == 2+ assert between.calls == [] and record["made"] == []+ assert all(not r["filled"] and "drawn on twos" in r["why"] for r in record["before"]["held_runs"])+ assert (record["cells"], record["poses"]) == (2 * N, N)+ off = _run(tmp_path, twos, name="off", fill_held="off", **cut)+ assert _bytes(Path(rep["out_dir"]), "m") == _bytes(Path(off["out_dir"]), "off")+++def test_a_walk_carried_to_60_fps_by_repeating_frames_reads_a_hold_and_is_filled_to_a_pose_a_cell(tmp_path):+ # 24 fps carried to 60 by the frame under each time: each frame shown three and two times by turns. Its rhythm+ # reads a hold of 2, but its runs are not each two cells: the frames between are made.+ filmed = walk(2 * N + 2)+ carried = [filmed[k * 24 // 60] for k in range(len(filmed) * 60 // 24)]+ between = Between(walk_at, range(2 * N + 2), period=N)+ keyed = save(carried, tmp_path / "carried-keyed")+ rep = loop_mod.run_loop(keyed, tmp_path / "carried-out", fps=60.0, min_len=None, max_len=None, n_out=None,+ seam_max=loop_mod.SEAM_RATIO_MAX, name="m", report_path=None, interpolate=between,+ state="walk", anchor="none", repair="off")+ record = rep["held_fill"]+ assert rep["cycle_drawings"]["hold"] == 2 and "drawn" not in record+ assert {r["length"] for r in record["before"]["held_runs"]} == {2, 3}+ assert record["before"]["poses"] < record["before"]["cells"] == rep["cycle"]["length"] == 60+ assert (record["cells"], record["poses"], record["held_runs"]) == (60, 60, [])+ cells, start = _cycle(rep), rep["cycle"]["start"]+ assert cells[0].tobytes() == carried[start].tobytes() and cells[-1].tobytes() == carried[start + 59].tobytes()+++def test_a_once_cut_and_a_one_shot_have_their_held_cells_made_too(tmp_path):+ frames = topple()+ stalled = shown_again(frames, {20: 2})+ times = {f.tobytes(): float(k) for k, f in enumerate(frames)}+ between = Between(lambda t: _topple_at(t), [])+ between.known.update(times)+ rep = _run(tmp_path, stalled, "fall", interpolate=between, state="death", cycle_mode="once")+ record = rep["held_fill"]+ start = rep["cycle"]["start"]+ assert [(r["start"], r["filled"]) for r in record["before"]["held_runs"] if r["filled"]] == [(20 - start, True)]+ assert between.calls == [(20.0, 21.0, 0.5)]+ hopped = shown_again(hop(), {18: 2})+ rep = _run(tmp_path, hopped, "hop", interpolate=lambda a, b, t: Image.blend(a, b, t), state="jump", cycle_mode="one-shot")+ assert any(r["start"] + rep["cycle"]["start"] == 18 for r in rep["held_fill"]["before"]["held_runs"])+++def _topple_at(time: float) -> Image.Image:+ """`topple`'s body `time` frames in, between its frames as well."""+ t = min(1.0, max(0.0, (time - 6) / 30))+ a = np.zeros((96, 128, 4), dtype=np.uint8)+ height, width = round(64 - 40 * t), round(16 + 36 * t)+ a[86 - height:86, 40:40 + width] = (200, 80, 30, 255)+ return Image.fromarray(a, "RGBA")+++# The fill on a cut's frames, as `video-loop` calls it: which runs it makes, which it keeps and why.+++def _reach(time: float) -> Image.Image:+ return planter(4 * time)+++def _planted(times: list[float]) -> list[Image.Image]:+ return [_reach(t) for t in times]+++def test_a_part_standing_still_on_both_sides_stays_where_it_stood():+ frames = _planted([0, 1, 2, 3, 3, 4, 5, 6])+ out, record = held_fill.fill(frames, Between(_reach, range(7)), ring=False)+ assert record["made"] == [4]+ assert out[4].tobytes() == _reach(3.5).tobytes()+ assert record["before"]["held_runs"][0]["filled"] is True+ assert record["contact"][0]["kept"] == 1.0+++def test_a_frame_between_that_drags_a_planted_foot_is_not_taken():+ frames = _planted([0, 1, 2, 3, 3, 4, 5, 6])+ out, record = held_fill.fill(frames, Between(_reach, range(7), after=slid), ring=False)+ assert record["made"] == []+ assert out[4].tobytes() == frames[4].tobytes() # the held cell, as filmed+ run = record["before"]["held_runs"][0]+ assert run["filled"] is False and "contact" in run["faults"]+ assert record["held_runs"] == [{"start": 3, "length": 2}]+++def test_the_opening_and_the_closing_pose_of_a_cut_played_once_are_kept():+ frames = _planted([0, 0, 1, 2, 3, 4, 4])+ calls: list = []+ out, record = held_fill.fill(frames, lambda a, b, t: calls.append(t) or a, ring=False)+ whys = [r["why"] for r in record["before"]["held_runs"]]+ assert calls == [] and record["made"] == []+ assert "opening" in whys[0] and "closing" in whys[1]+++def test_a_loop_s_held_cells_at_its_wrap_are_kept_and_at_its_start_made():+ frames = _planted([0, 0, 1, 2, 3, 4, 5, 5])+ between = Between(_reach, range(7), period=None)+ # The wrap closes on cell 0 again: a frame between the last pose and the first is the wrap's, not the hold's.+ out, record = held_fill.fill(frames, between, ring=True)+ runs = record["before"]["held_runs"]+ assert (runs[0]["start"], runs[0]["filled"]) == (0, True)+ assert (runs[1]["start"], runs[1]["filled"]) == (6, False) and "wrap" in runs[1]["why"]+ assert record["made"] == [1] and out[0].tobytes() == frames[0].tobytes() and out[7].tobytes() == frames[7].tobytes()+++def test_codec_copies_read_as_the_same_picture_and_the_slowest_motion_does_not():+ still = planter(10)+ noisy = np.asarray(still).astype(np.int16)+ noisy[..., :3] += np.random.default_rng(0).integers(-3, 4, size=noisy[..., :3].shape).astype(np.int16)+ noisy = Image.fromarray(np.clip(noisy, 0, 255).astype(np.uint8), "RGBA")+ assert held_fill.same_steps([still, noisy, planter(11)]) == [True, False]+++# A higher rate than the clip's: frames between, never frames shown again.+++def test_a_walk_asked_for_at_60_fps_is_made_of_frames_between(tmp_path):+ between = Between(walk_at, range(N + 6), period=N)+ rep = _run(tmp_path, walk(), "walk60", interpolate=between, out_fps=60.0,+ state="walk", cycle_mode="fixed", start=0, length=N, anchor="none", repair="off")+ meta = _meta(rep)+ record = rep["held_fill"]+ assert record["out_fps"]["applied"] is True and record["out_fps"]["cells"] == 60+ assert (record["cells"], record["poses"], record["held_runs"]) == (60, 60, [])+ assert meta["frames"] == 60 and meta["cycle_seconds"] == 1.0 and meta["delay_ms"] == pytest.approx(16.67)+ assert meta["out_fps"] == 60.0+ cells = _cycle(rep)+ assert len(cells) == 60+ assert cells[0].tobytes() == walk_at(0).tobytes() and cells[5].tobytes() == walk_at(2).tobytes()+ assert cells[1].tobytes() == walk_at(0.4).tobytes()+ assert len({c.tobytes() for c in cells}) == 60+++def test_a_one_shot_asked_for_at_60_fps_keeps_its_first_and_last_frame(tmp_path):+ frames = hop()+ times = {f.tobytes(): float(k) for k, f in enumerate(frames)}+ made: list = []++ def between(a, b, t):+ made.append((times[a.tobytes()], times[b.tobytes()], round(t, 4)))+ return Image.blend(a, b, t)++ rep = _run(tmp_path, frames, "hop60", interpolate=between, out_fps=60.0, state="jump", cycle_mode="one-shot")+ L = rep["cycle"]["length"]+ record = rep["held_fill"]+ cells = _cycle(rep)+ assert len(cells) == round((L - 1) * 2.5) + 1 == record["cells"]+ filmed = hop()[rep["cycle"]["start"]: rep["cycle"]["start"] + L]+ assert cells[0].tobytes() == filmed[0].tobytes() and cells[-1].tobytes() == filmed[-1].tobytes()+ assert record["out_fps"]["applied"] is True+++def test_no_rife_delivers_a_clip_asked_for_at_a_higher_rate_at_its_own(tmp_path, monkeypatch, capsys):+ _no_rife(monkeypatch, tmp_path)+ rep = _run(tmp_path, walk(), "walk60", out_fps=60.0, state="walk", cycle_mode="fixed", start=0, length=N,+ anchor="none", repair="off")+ assert rep["status"] == "passed" and _meta(rep)["frames"] == N and "out_fps" not in _meta(rep)+ assert rep["held_fill"]["out_fps"]["applied"] is False+ err = capsys.readouterr().err+ assert "walk60" in err and "--out-fps 60" in err and loop_mod.rife_mod.install_command() in err+++def test_a_rate_under_the_clip_s_own_is_refused(tmp_path):+ with pytest.raises(SystemExit, match="--out-fps 12"):+ _run(tmp_path, walk(), out_fps=12.0, state="walk", cycle_mode="fixed", start=0, length=N, anchor="none")+++def test_video_loop_and_video_set_take_the_switches():+ import argparse++ from sprite_gen.video import batch++ parser = argparse.ArgumentParser()+ loop_mod.add_arguments(parser)+ args = parser.parse_args(["--frames-dir", "f", "--out-dir", "o", "--fill-held", "off", "--out-fps", "60"])+ assert (args.fill_held, args.out_fps) == ("off", 60.0)+ assert parser.parse_args(["--frames-dir", "f", "--out-dir", "o"]).fill_held == "auto"+ parser = argparse.ArgumentParser()+ batch.add_arguments(parser)+ args = parser.parse_args(["--out-dir", "o", "--fill-held", "off", "--out-fps", "60"])+ assert (args.fill_held, args.out_fps) == ("off", 60.0)+ assert parser.parse_args(["--out-dir", "o"]).fill_held == "auto"+++def test_video_set_hands_the_switches_to_each_cut(monkeypatch, tmp_path):+ from sprite_gen.video import batch++ seen: list[dict] = []+ monkeypatch.setattr(batch.frames_mod, "run_frames", lambda clip, out, **kw: {+ "fps": 24, "frames": 10, "alpha_zero_pct_min": 50, "alpha_zero_pct_max": 60, "keyed_dir": str(out)})++ def run_loop(*a, **kw):+ seen.append(kw)+ return {"cycle": {"length": 10, "period_global": 10, "ratio": 0.2}, "resampled_seam_ratio": 0.2, "n_out": 10,+ "gif": {"file": "loop.gif"}, "webp": {"file": "loop.webp"}, "strip": {"path": "strip.png"},+ "held_fill": {"cells": 10, "poses": 9, "held_runs": [{"start": 3, "length": 2}], "made": [],+ "before": {"cells": 10, "poses": 9, "held_runs": [{"start": 3, "length": 2, "filled": False,+ "why": "--fill-held off"}]}}}++ def video(image, prompt, out, report, **kw):+ out.write_bytes(b"test-video")+ report.write_text(json.dumps({"prompt": prompt}))+ return 0++ monkeypatch.setattr(batch.loop_mod, "run_loop", run_loop)+ monkeypatch.setattr(batch, "_staggered_start", lambda gap: None)+ still = tmp_path / "front.png"+ Image.new("RGBA", (64, 64), (200, 80, 30, 255)).save(still)+ result = batch.run_set(bases={"front": still}, states=["idle"], root=tmp_path / "set", character=None, duration=3,+ resolution="720p", key="green", concurrency=1, force=False, gap=0, video_runner=video,+ align_cycles="off", fill_held="off", out_fps=60.0)+ assert [(kw["fill_held"], kw["out_fps"]) for kw in seen] == [("off", 60.0)]+ # The set's report says each motion's poses over its cells.+ assert result["items"][0]["loop"]["poses"] == "9/10"+++def test_a_cut_with_cells_made_is_not_restored_from_its_source_frames(tmp_path):+ """The source frames do not hold a cell made between two of them: restoration (`video-loop-repair`) reads the cut+ as one it cannot project (`source-processing-unsupported`), as it reads a blended wrap."""+ import shutil+ import subprocess++ from sprite_gen.video import source+ from sprite_gen.video.compare import Loop++ if not shutil.which("ffmpeg") or not loop_mod.img2webp_supports_exact():+ pytest.skip("ffmpeg and img2webp >=1.5 required")+ filmed = shown_again(walk(), STALLED)+ keyed = save(filmed, tmp_path / "keyed")+ out = tmp_path / "cut"+ loop_mod.run_loop(keyed, out, fps=24.0, min_len=None, max_len=None, n_out=None, seam_max=loop_mod.SEAM_RATIO_MAX,+ name="walk", report_path=None, interpolate=Between(walk_at, range(N + 6), period=N), **STALLED_CUT)+ files = sorted(keyed.glob("*.png"))+ frames_report = tmp_path / "frames.json"+ frames_report.write_text(json.dumps({"kind": "sprite-gen-video-frames-report", "fps": 24.0, "frames": len(files),+ "width": filmed[0].width, "height": filmed[0].height, "stream_index": 0,+ "key": "green"}))+ clip = tmp_path / "clip.mp4"+ subprocess.run(["ffmpeg", "-v", "error", "-framerate", "24", "-i", str(keyed / "%04d.png"), "-c:v", "libx264",+ "-pix_fmt", "yuv420p", str(clip)], check=True)+ manifest = tmp_path / "source.json"+ manifest.write_text(json.dumps(source.manifest(clip=clip, canvas=files[0], frames_report=frames_report, files=files,+ timestamps=source.timestamps(clip, 0))))+ loop = Loop.read(out / "walk.strip.png", out / "walk.strip.json", out / "walk.loop.report.json")+ projection, issue = source.project(loop, source.Source.read(+ source_manifest=manifest, source_frames_dir=keyed, source_clip=clip, source_canvas=files[0],+ source_frames_report=frames_report))+ assert (projection, issue) == (None, "source-processing-unsupported")+++def test_the_alignment_and_a_stop_refuse_a_loop_cut_at_a_rate_of_its_own(tmp_path):+ from sprite_gen.video import align, stop++ rep = _run(tmp_path, walk(), "walk60", interpolate=Between(walk_at, range(N + 6), period=N), out_fps=60.0,+ state="walk", cycle_mode="fixed", start=0, length=N, anchor="none", repair="off")+ out = Path(rep["out_dir"])+ with pytest.raises(ValueError, match="--out-fps 60"):+ align._loop_files(out)+ with pytest.raises(SystemExit, match="--out-fps 60"):+ stop.read_loop(out / "walk60.strip.json")+++def test_the_curation_view_marks_the_cells_made_and_the_cells_still_held(tmp_path):+ """A loop's `cycle/` imported into the curation view (`unpack-atlas --pngs-dir`): each card of a cell the fill made+ says `made`, of a cell still showing the picture before it `held`."""+ from sprite_gen import cli++ rep = _run(tmp_path, shown_again(walk(), {**STALLED, 20: 5}), interpolate=Between(walk_at, range(N + 6), period=N),+ **{**STALLED_CUT, "length": N + 7})+ assert rep["held_fill"]["made"] == [6, 15, 16]+ assert cli.main(["unpack-atlas", "--pngs-dir", str(Path(rep["out_dir"]) / "cycle"), "--out-dir", str(tmp_path / "run")]) == 0+ rows = json.loads((tmp_path / "run" / "frames" / "frames-manifest.json").read_text())["rows"]+ labels = rows[0]["labels"]+ assert [k for k, label in enumerate(labels) if label.endswith(" (made)")] == [6, 15, 16]+ assert [k for k, label in enumerate(labels) if label.endswith(" (held)")] == [24, 25, 26, 27]+ assert labels[0] == "frame-000"diff --git a/tests/video/test_idle_still.py b/tests/video/test_idle_still.pyindex 4933844..af82ae5 100644--- a/tests/video/test_idle_still.py+++ b/tests/video/test_idle_still.py@@ -78,7 +78,7 @@ def test_video_set_pins_idle_and_cuts_it_whole(tmp_path: Path, monkeypatch) -> Ndef fake_loop(frames_dir, out_dir, **kw):seen["cycle_mode"] = kw.get("cycle_mode")- return {"cycle": {"kind": "pinned", "length": 47, "period_global": None, "ratio": 1.0}, "resampled_seam_ratio": 1.0, "n_out": 47,+ return {"cycle": {"kind": "pinned", "length": 47, "period_global": None, "ratio": 1.0}, "resampled_seam_ratio": 1.0, "held_fill": {"cells": 10, "poses": 10, "held_runs": [], "made": [], "before": {"cells": 10, "poses": 10, "held_runs": []}}, "n_out": 47,"gif": {"file": "g"}, "webp": {"file": "w"}, "strip": {"path": "s", "drift_px": 0}}def video(image, prompt, out, report, **kw):diff --git a/tests/video/test_loop_prop_seam_held.py b/tests/video/test_loop_prop_seam_held.pyindex a07daf5..53703b9 100644--- a/tests/video/test_loop_prop_seam_held.py+++ b/tests/video/test_loop_prop_seam_held.py@@ -404,6 +404,8 @@ GHOST_KEYS_2430 = {"ghost_screen", "ghost_at"}# Unreleased: every cut of the cut's length the clip holds, read for the same foot twice (video-loop), and the aligned# loop's beat and its cut's screen steps (docs/loop-repair.md section 4)CLIP_FEET_KEYS, BEAT_KEYS = {"clip_feet"}, {"beat", "screen"}+# 3.8.0: the cut's held cells, read and made again (docs/loop-repair.md section 7)+HELD_FILL_KEYS_3800 = {"held_fill"}def test_cycle_align_writes_a_loop_without_a_held_part_as_before(tmp_path, staffless):@@ -425,7 +427,7 @@ def test_cycle_align_writes_a_loop_without_a_held_part_as_before(tmp_path, staffassert all("cycles_kept" not in row and "steps" not in row for row in out["loops"])for d in dirs:meta = json.loads((d / "loop.strip.json").read_text())- assert set(meta) == STRIP_KEYS_2350 | SOURCE_KEYS_2390 | CLIP_FEET_KEYS+ assert set(meta) == STRIP_KEYS_2350 | SOURCE_KEYS_2390 | CLIP_FEET_KEYS | HELD_FILL_KEYS_3800assert set(meta["cycle_align"]) == CYCLE_ALIGN_KEYS_2350 | CORRESPONDENCE_KEYS_2410 | GHOST_KEYS_2430 | BEAT_KEYS# The cut's source stays as the cut wrote it: `cycle_align` says the cells were turned after it, so it# no longer names each cell's frame (docs/loop-comparison.md). The rebuilt strip names its own cells —diff --git a/tests/video/test_once.py b/tests/video/test_once.pyindex 1921a4e..35e92fd 100644--- a/tests/video/test_once.py+++ b/tests/video/test_once.py@@ -176,7 +176,7 @@ def test_batch_sends_terminal_pin_and_does_not_reuse_a_changed_pin(tmp_path, mondef loop_stub(frames, out, **kw):assert kw["cycle_mode"] == "once" and kw["anchor"] == "none"return {"cycle": {"kind": "once", "length": 24, "period_global": None, "ratio": 0},- "resampled_seam_ratio": None, "n_out": 24, "gif": {"file": "g"}, "webp": {"file": "w"}, "strip": {"path": "s"}}+ "resampled_seam_ratio": None, "held_fill": {"cells": 10, "poses": 10, "held_runs": [], "made": [], "before": {"cells": 10, "poses": 10, "held_runs": []}}, "n_out": 24, "gif": {"file": "g"}, "webp": {"file": "w"}, "strip": {"path": "s"}}monkeypatch.setattr(batch.canvas_mod, "run_canvas", canvas_stub)monkeypatch.setattr(batch.frames_mod, "run_frames", frames_stub)diff --git a/tests/video/test_play.py b/tests/video/test_play.pyindex c4eafbc..e71915a 100644--- a/tests/video/test_play.py+++ b/tests/video/test_play.py@@ -184,7 +184,7 @@ def stub_set(tmp_path, monkeypatch, *, bases, states, **kwargs):def loop_stub(frames, out, **kw):seen.setdefault(out.parent.name, {})["cycle"] = kw["cycle_mode"]return {"cycle": {"kind": kw["cycle_mode"], "length": 24, "period_global": None, "ratio": 0},- "resampled_seam_ratio": None, "n_out": 24, "gif": {"file": "g"}, "webp": {"file": "w"}, "strip": {"path": "s"}}+ "resampled_seam_ratio": None, "held_fill": {"cells": 10, "poses": 10, "held_runs": [], "made": [], "before": {"cells": 10, "poses": 10, "held_runs": []}}, "n_out": 24, "gif": {"file": "g"}, "webp": {"file": "w"}, "strip": {"path": "s"}}monkeypatch.setattr(batch.frames_mod, "run_frames", frames_stub)monkeypatch.setattr(batch.loop_mod, "run_loop", loop_stub)diff --git a/tests/video/test_stop.py b/tests/video/test_stop.pyindex fcb65fe..84470e8 100644--- a/tests/video/test_stop.py+++ b/tests/video/test_stop.py@@ -146,6 +146,9 @@ def test_stop_plays_the_start_backwards_from_the_loop_to_the_first_frame(tmp_patassert smeta["from_loop"]["from_cell"] == out["entry"]["from_cell"] and smeta["body_h"] == lmeta["body_h"]assert smeta["source_cut"]["source"]["sha256"] == lmeta["source_cut"]["source"]["sha256"]assert out["source"]["same_as_loop"] is True+ # Read for a picture shown again, as every cut is; a stop plays its filmed frames, none made between.+ assert smeta["held_fill"]["mode"] == "off" and smeta["held_fill"]["made"] == []+ assert (smeta["held_fill"]["cells"], smeta["held_fill"]["poses"], smeta["held_fill"]["held_runs"]) == (len(shown), len(shown), [])with Image.open(tmp_path / "stop" / "stop.gif") as gif:assert gif.n_frames == len(shown) and gif.info.get("loop") is Nonereport = json.loads((tmp_path / "stop" / "stop.stop.report.json").read_text())diff --git a/tests/video/test_video_pipeline.py b/tests/video/test_video_pipeline.pyindex 7282100..fa40d8e 100644--- a/tests/video/test_video_pipeline.py+++ b/tests/video/test_video_pipeline.py@@ -443,7 +443,7 @@ def test_run_set_runs_each_clip_once_and_tables_failures(tmp_path: Path, monkeypmonkeypatch.setattr(batch_mod.time, "sleep", lambda s: None) # no real stagger waitsmonkeypatch.setattr(frames_mod, "run_frames", lambda clip, out_dir, **kw: {"fps": 24.0, "frames": 10, "alpha_zero_pct_min": 60.0, "alpha_zero_pct_max": 70.0, "keyed_dir": str(out_dir / "keyed")})monkeypatch.setattr(batch_mod.frames_mod, "run_frames", frames_mod.run_frames)- monkeypatch.setattr(batch_mod.loop_mod, "run_loop", lambda frames_dir, out_dir, **kw: {"cycle": {"length": 12, "period_global": 12, "ratio": 0.3, "review_recommended": kw["state"] == "run"}, "resampled_seam_ratio": 0.5, "n_out": 12, "gif": {"file": "x.gif"}, "webp": {"file": "x.webp"}, "strip": {"path": "x.png"}})+ monkeypatch.setattr(batch_mod.loop_mod, "run_loop", lambda frames_dir, out_dir, **kw: {"cycle": {"length": 12, "period_global": 12, "ratio": 0.3, "review_recommended": kw["state"] == "run"}, "resampled_seam_ratio": 0.5, "held_fill": {"cells": 10, "poses": 10, "held_runs": [], "made": [], "before": {"cells": 10, "poses": 10, "held_runs": []}}, "n_out": 12, "gif": {"file": "x.gif"}, "webp": {"file": "x.webp"}, "strip": {"path": "x.png"}})payload = batch_mod.run_set(bases={"side": base}, states=["walk", "run", "jump"], root=tmp_path / "set", character=None, duration=6, resolution="720p", key="green", concurrency=3, force=False, gap=0.0, video_runner=fake_video)