Generate clean 2D game sprites & animation atlases — component-row pipeline: state rows, alpha cleanup, frame extraction, runtime atlases. Codex/Claude skill.
fix(video-loop): a walk without RIFE is cut as filmed with a warning
Soohong Kimbda38a947b1f
diff --git a/sprite_gen/video/align.py b/sprite_gen/video/align.pyindex 8190913..6fb0bb7 100644--- a/sprite_gen/video/align.py+++ b/sprite_gen/video/align.py@@ -15,6 +15,9 @@ that needs the fewest made frames across the set), and a loop already that longThe loop directories are `video-loop` output directories. Their first alignment keeps the cutas filmed in `cycle.source/`; every later alignment reads from there, so running it again — orwith another length — never resamples a resampled loop.++A set that needs a made frame where no RIFE is installed raises `rife.RifeNotInstalled` with+nothing rewritten: this command fails on it, `video-set` skips the alignment with a warning."""from __future__ import annotations@@ -35,7 +38,7 @@ from sprite_gen.video import loop as loop_modfrom sprite_gen.video import rife as rife_modSNAP = 0.03 # a sample time within this of a source frame takes that frame-SOURCE_DIR = "cycle.source"+SOURCE_DIR = loop_mod.CYCLE_SOURCE_DIR # removed by video-loop whenever it cuts the loop againRATE_TOLERANCE = 0.002 # frame rates read back from the strip metadata agree within thisLOW_ALPHA = 128 # the body's top line for the foot-strike turn: solid pixels only@@ -186,6 +189,8 @@ def align_set(loop_dirs: list[Path], *, length: int | None = None, interpolate:try:out, facts = resample(frames, target, lazy)start = foot_strike_start(out)+ except rife_mod.RifeNotInstalled as exc:+ raise rife_mod.RifeNotInstalled(f"{d}: {exc}") from excexcept (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 excrecord = {**facts, "turned_by": start, "fps": round(fps, 4), "source": SOURCE_DIR,@@ -213,7 +218,12 @@ def add_arguments(parser: argparse.ArgumentParser) -> None:def run(**kwargs: object) -> int:- report = align_set(list(kwargs["loop_dir"]), length=kwargs.get("length"), report_path=kwargs.get("report")) # type: ignore[arg-type]+ try:+ report = align_set(list(kwargs["loop_dir"]), length=kwargs.get("length"), report_path=kwargs.get("report")) # type: ignore[arg-type]+ except rife_mod.RifeNotInstalled as exc:+ # Asked for by name, so no RIFE is a failure, never a quiet skip (video-set skips with a warning).+ raise SystemExit(f"video-cycle-align: {exc}; frames between source frames are made by RIFE — "+ f"`{rife_mod.INSTALL_COMMAND}` (docs/loop-repair.md)") from excprint(json.dumps({k: report[k] for k in ("length", "lengths", "made_by_rife", "cycle_seconds")}| {"loops": [{k: r[k] for k in ("name", "from", "to", "made_by_rife", "turned_by", "seam_ratio")} for r in report["loops"]]},ensure_ascii=False, indent=2))diff --git a/sprite_gen/video/batch.py b/sprite_gen/video/batch.pyindex 74e35b2..8c4b729 100644--- a/sprite_gen/video/batch.py+++ b/sprite_gen/video/batch.py@@ -31,6 +31,7 @@ from sprite_gen.video import canvas as canvas_modfrom sprite_gen.video import frames as frames_modfrom sprite_gen.video import loop as loop_modfrom sprite_gen.video import align as align_mod+from sprite_gen.video import rife as rife_modSTART_GAP_SECONDS = 2.0# Clip length the batch asks the video model for. 3 s holds two or more cycles of every@@ -531,6 +532,9 @@ def run_item(result["loop"]["half_period_guard"] = lp["cycle"].get("half_period_guard")if lp.get("motion_anchor", {}).get("applied") is False:result["loop"]["motion_anchor"] = lp["motion_anchor"]+ if "rife" in (lp.get("jump_repair") or {}):+ # cut as filmed for want of RIFE: the set report lists it under `warnings`+ result["loop"]["jump_repair"] = {k: lp["jump_repair"][k] for k in ("applied", "why", "score_max_before", "install")}result["ok"] = Trueexcept SystemExit as exc:result["ok"] = False@@ -544,7 +548,9 @@ ALIGN_MODES = ("auto", "off")def align_gaits(results: list[dict[str, Any]], root: Path, mode: str, *, interpolate: Any = None) -> dict[str, Any]:"""One cycle length per gait state across the set's directions (`video-cycle-align`,docs/loop-repair.md section 4). A state filmed in fewer than two directions has nothing to- match. A failure is recorded under its state and the batch reports it; the loops stay as cut."""+ match. A failure is recorded under its state and the batch reports it; the loops stay as cut.+ Where a frame is to be made and no RIFE is installed the state is skipped, not failed: each+ loop keeps its own length, the record says why, and a warning line names the install."""out: dict[str, Any] = {}if mode == "off":return out@@ -558,10 +564,17 @@ def align_gaits(results: list[dict[str, Any]], root: Path, mode: str, *, interpotry:report = align_mod.align_set([Path(r["dir"]) / "loop" for r in rows], interpolate=interpolate,report_path=root / f"{state}.cycle-align.json")+ except rife_mod.RifeNotInstalled as exc:+ out[state] = {"ok": True, "applied": False, "why": "RIFE not installed — each loop keeps its own length",+ "rife": str(exc), "install": rife_mod.INSTALL_COMMAND}+ print(f"video-set: warning: {state}: cycles not aligned — RIFE is not installed, so each loop keeps its own "+ f"length; run `{rife_mod.INSTALL_COMMAND}`, then `sprite-gen video-cycle-align` (docs/loop-repair.md)",+ file=sys.stderr)+ continueexcept SystemExit as exc:out[state] = {"ok": False, "error": str(exc)}continue- out[state] = {"ok": True, "length": report["length"], "lengths": report["lengths"], "made_by_rife": report["made_by_rife"],+ out[state] = {"ok": True, "applied": True, "length": report["length"], "lengths": report["lengths"], "made_by_rife": report["made_by_rife"],"report": str(root / f"{state}.cycle-align.json")}for r, row in zip(rows, report["loops"]):r["loop"]["cycle_align"] = {k: row[k] for k in ("from", "to", "made_by_rife", "turned_by", "seam_ratio")}@@ -577,6 +590,8 @@ def write_table(results: list[dict[str, Any]], path: Path) -> str:status = "OK (review gait)" if lp.get("review_recommended") else "OK"if lp.get("motion_anchor", {}).get("applied") is False:status = "OK (uncorrected; review gait)"+ if "jump_repair" in lp:+ status += " (jump not repaired: no RIFE)"lines.append(f"| {r['direction']} | {r['state']} | {lp.get('kind', 'periodic')} | {lp['cycle']} | {lp['period'] if lp['period'] is not None else '-'} | {lp['seam_ratio']:.2f} | {lp['n_out']} | {status} |")else:lines.append(f"| {r['direction']} | {r['state']} | - | - | - | - | - | FAIL: {r.get('error', '')[:80]} |")@@ -653,7 +668,12 @@ def run_set(aligned = align_gaits(results, root, align_cycles, interpolate=interpolate)table = write_table(results, root / "table.md")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")]- payload = {"kind": "sprite-gen-video-set-report", "root": str(root), "states": states, "facing": facing, "facing_fix": facing_fix, "directions": list(bases), "body_height": body_height, "ok": sum(1 for r in results if r.get("ok")), "failed": failed, "items": results, "cycle_align": aligned}+ # 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"cycle-align:{st}: not aligned — {a['why']}" for st, a in aligned.items() if a.get("applied") is False])+ if warnings:+ warnings.append(f"install RIFE with `{rife_mod.INSTALL_COMMAND}` (docs/loop-repair.md)")+ payload = {"kind": "sprite-gen-video-set-report", "root": str(root), "states": states, "facing": facing, "facing_fix": facing_fix, "directions": list(bases), "body_height": body_height, "ok": sum(1 for r in results if r.get("ok")), "failed": failed, "warnings": warnings, "items": results, "cycle_align": aligned}atomic_write_text(root / "set.report.json", json.dumps(payload, ensure_ascii=False, indent=2) + "\n")print(table)return payload@@ -694,7 +714,7 @@ def add_arguments(parser: argparse.ArgumentParser) -> None:parser.add_argument("--decontam", choices=frames_mod.DECONTAM_MODES, default="off", help="passed to video-frames: palette re-explains key-tinted edges with the subject's own colours (default off)")parser.add_argument("--walk-start", choices=WALK_START_MODES, default="redraw", help="redraw (default): a front or back walk films from its base still redrawn mid-step (one image generation, `sprite-gen gen --ref base`, kept as walk-start.png) — from a standing still the clip model walks askew; as-given: film from the base still itself")parser.add_argument("--still-provider", help="image provider for the mid-step redraw (default: sprite-gen gen's own default)")- parser.add_argument("--align-cycles", choices=ALIGN_MODES, default="auto", help="auto (default): after the loops are cut, every walk/run filmed in two or more directions is resampled to the set's median cycle length and turned to start on a foot strike (video-cycle-align; RIFE makes only the frames between source frames); off: each loop keeps its own length")+ parser.add_argument("--align-cycles", choices=ALIGN_MODES, default="auto", help="auto (default): after the loops are cut, every walk/run filmed in two or more directions is resampled to the set's median cycle length and turned to start on a foot strike (video-cycle-align; RIFE makes only the frames between source frames — where no RIFE is installed the alignment is skipped with a warning and recorded); off: each loop keeps its own length")parser.add_argument("--force", action="store_true", help="regenerate clips that already exist")diff --git a/sprite_gen/video/loop.py b/sprite_gen/video/loop.pyindex 3a5b98f..a69a28e 100644--- a/sprite_gen/video/loop.py+++ b/sprite_gen/video/loop.py@@ -84,9 +84,16 @@ BODY_ANCHOR_BAND = 0.6 # --anchor body reads the wrap offset from the top 60 %BODY_ANCHOR_SEARCH = 24 # px either side searched for the last frame's horizontal offset against the firstFOOT_BAND = 0.08 # fraction of the frame's own height, measured up from its lowest opaque row# Jump-frame repair (docs/loop-repair.md section 2). auto: walk and run loops get a RIFE frame in-# place of each frame that follows a jump; off: the loop is cut as filmed, and says so.-REPAIR_MODES = ("auto", "off")+# place of each frame that follows a jump, and a loop that needs one where no RIFE is installed is+# cut as filmed with a warning (a walk that cut before RIFE existed still cuts); on: the same, but+# no RIFE fails the loop — a caller that asked for the repair is never handed less; off: the loop+# is cut as filmed, and says so.+REPAIR_MODES = ("auto", "on", "off")FACINGS = ("right", "left")+# Where `video-cycle-align` keeps the cut as filmed (sprite_gen/video/align.py). A new cut makes+# the kept one stale, so writing the cycle removes it: an alignment after a re-cut (say, once RIFE+# is installed and the jumps are repaired) reads the new cut, not the old one.+CYCLE_SOURCE_DIR = "cycle.source"# A gait's period is a fact about the body, not about how long the clip runs: the@@ -778,9 +785,13 @@ def write_loop_report(target: Path, payload: dict[str, Any]) -> None:atomic_write_text(target, json.dumps(finite(payload), ensure_ascii=False, indent=2, allow_nan=False) + "\n")-def _repair_jumps(frames: list[Image.Image], interpolate: rife_mod.Interpolate | None, *, facing: str) -> tuple[list[Image.Image], dict[str, Any]]:+def _repair_jumps(frames: list[Image.Image], interpolate: rife_mod.Interpolate | None, *, facing: str,+ required: bool) -> tuple[list[Image.Image], dict[str, Any]]:"""`repair_mod.repair_jumps`, with RIFE located only once a frame is to be made: a loop- without a jump needs no binary. The report names the interpolator that made the frames."""+ without a jump needs no binary. The report names the interpolator that made the frames.++ A frame to make and no RIFE installed: `required` lets `RifeNotInstalled` through; otherwise+ the loop comes back as filmed and the record says why (`applied: false`, `rife`, `install`)."""made_by: list[dict[str, str]] = []def lazy(a: Image.Image, b: Image.Image, t: float) -> Image.Image:@@ -791,7 +802,17 @@ def _repair_jumps(frames: list[Image.Image], interpolate: rife_mod.Interpolate |interpolate = locatedreturn interpolate(a, b, t)- frames, record = repair_mod.repair_jumps(frames, lazy, facing=facing)+ try:+ repaired, record = repair_mod.repair_jumps(frames, lazy, facing=facing)+ except rife_mod.RifeNotInstalled as exc:+ if required:+ raise+ # RIFE is located before the first frame is made, so nothing was replaced yet.+ worst = round(float(repair_mod.jump_scores(frames, facing=facing)["score"].max()), 4)+ return frames, {"applied": False, "why": "RIFE not installed — cut as filmed", "rife": str(exc),+ "install": rife_mod.INSTALL_COMMAND, "ratio": repair_mod.JUMP_RATIO, "facing": facing,+ "score_max_before": worst, "score_max_after": worst, "replaced": []}+ frames = repairedrecord["applied"] = bool(record["replaced"])if made_by:record["interpolator"] = {"kind": "rife-ncnn-vulkan", **made_by[0]}@@ -975,29 +996,35 @@ def run_loop(write_loop_report(target, {**report_base, "status": "failed", "error": error, "cycle": cycle})raise SystemExit(error) from excreport_base["motion_anchor"] = motion- if repair == "auto" and prof.gait:+ if repair != "off" and prof.gait:report_base["jump_repair"] = Nonetry:- frames, report_base["jump_repair"] = _repair_jumps(frames, interpolate, facing=facing)+ frames, report_base["jump_repair"] = _repair_jumps(frames, interpolate, facing=facing, required=repair == "on")except (ValueError, rife_mod.RifeUnavailable) as exc:- error = (f"video-loop: {exc}; the loop has a jump frame to repair — install RIFE, or pass --repair off "- "to cut it as filmed (docs/loop-repair.md)")+ fix = (f"install RIFE (`{rife_mod.INSTALL_COMMAND}`), or pass --repair auto to cut it as filmed with a warning"+ if isinstance(exc, rife_mod.RifeNotInstalled) else "fix RIFE, or pass --repair off to cut it as filmed")+ error = f"video-loop: {exc}; the loop has a jump frame to repair — {fix} (docs/loop-repair.md)"shutil.rmtree(out_dir / FALLBACK_FRAMES_DIR, ignore_errors=True)write_loop_report(target, {**report_base, "status": "failed", "error": error, "cycle": cycle})raise SystemExit(error) from excif report_base["jump_repair"]["replaced"]:report_base["seam_measurement"] = "rendered-cells"+ if "rife" in report_base["jump_repair"]:+ print(f"video-loop: warning: a jump frame was not repaired ({report_base['jump_repair']['score_max_before']:.2f}x "+ f"the median step) — RIFE is not installed, so the loop is cut as filmed; run `{rife_mod.INSTALL_COMMAND}` "+ "and cut it again (docs/loop-repair.md)", file=sys.stderr)else:report_base["jump_repair"] = {"applied": False, "why": "--repair off" if repair == "off" else f"not a gait state ({state})"}if prof.gait:# The jolt is measured on the loop as it will play — after the repair — and reported on# every walk and run (docs/loop-repair.md section 3). Beyond the reference bounds it is a# warning line; it fails the loop only against a bound the caller passed (--jolt-max /- # --head-step-max), and only when the repair ran: --repair off cuts and reports as filmed.+ # --head-step-max), and never with --repair off, which cuts and reports as filmed. A loop+ # whose repair could not run (no RIFE) is gated as filmed, and the failure says why.jolt = repair_mod.measure_jolt(frames, facing=facing)reference = {"jolt_max": repair_mod.JOLT_REFERENCE, "head_step_max": repair_mod.HEAD_STEP_REFERENCE}warnings = repair_mod.jolt_verdict(jolt, **reference)- gated = repair == "auto" and (jolt_max is not None or head_step_max is not None)+ gated = repair != "off" and (jolt_max is not None or head_step_max is not None)over = repair_mod.jolt_verdict(jolt, jolt_max=jolt_max, head_step_max=head_step_max) if gated else []report_base["jolt"] = {**jolt, "reference": reference, "warnings": warnings,"gate": {"jolt_max": jolt_max, "head_step_max": head_step_max} if gated else None,@@ -1006,7 +1033,8 @@ def run_loop(if over:error = (f"video-loop: loop jolts — {'; '.join(over)} ({cycle.get('kind', 'periodic')} length {L} frames from {i}"f"{', after repairing frames ' + str(report_base['jump_repair']['replaced']) if report_base['jump_repair'].get('replaced') else ''}); "- "the motion does not play smoothly — regenerate the clip")+ "the motion does not play smoothly — regenerate the clip"+ f"{' (the jump repair did not run: RIFE is not installed — ' + rife_mod.INSTALL_COMMAND + ')' if 'rife' in report_base['jump_repair'] else ''}")shutil.rmtree(out_dir / FALLBACK_FRAMES_DIR, ignore_errors=True)write_loop_report(target, {**report_base, "status": "failed", "error": error, "cycle": cycle})raise SystemExit(error)@@ -1015,6 +1043,7 @@ def run_loop(cycle_dir.mkdir(parents=True, exist_ok=True)for old in cycle_dir.glob("frame-*.png"):old.unlink()+ shutil.rmtree(out_dir / CYCLE_SOURCE_DIR, ignore_errors=True)for k, im in enumerate(frames):im.save(cycle_dir / f"frame-{k:03d}.png")strip, strip_meta = build_strip(frames, max_height=strip_height, cycle_seconds=cycle_seconds, body_height=body_height, anchor="feet" if anchor == "feet" else "none", kind=str(cycle.get("kind") or "periodic"),@@ -1137,7 +1166,7 @@ def add_arguments(parser: argparse.ArgumentParser) -> None:parser.add_argument("--body-height", type=int, help="scale so the STANDING height (the subject in the clip's first frame, i.e. the base still's pose) is this many px — the same value across states gives the same character size; --strip-height stays the cap")parser.add_argument("--anchor", choices=ANCHOR_MODES, default=None, help="motion-auto: automatic stable regions, local repeat selection and XY ramp (walk/run); motion: fixed cut with explicit regions; body (default for walk/run): measure the last-to-first head-and-torso offset once and spread it as a ramp over the cycle; feet: remove in-canvas drift (a straight-line trend) so every cell stands on the mean foot line; none: leave placement as filmed (default for other states)")parser.add_argument("--anchor-region", type=motion_anchor.parse_region, action="append", help="motion anchor only: repeat twice with head then torso x0,y0,x1,y1 in the first selected frame; requires --cycle fixed and at least 6 frames")- parser.add_argument("--repair", choices=REPAIR_MODES, default="auto", help="auto (default): in a walk or run loop, a frame that follows a jump (a step 1.4x the median, whole body or the hair behind it) is replaced by RIFE's frame between its neighbours, at most 3 and never two side by side, recorded in the report (docs/loop-repair.md); off: cut as filmed")+ parser.add_argument("--repair", choices=REPAIR_MODES, default="auto", help="auto (default): in a walk or run loop, a frame that follows a jump (a step 1.4x the median, whole body or the hair behind it) is replaced by RIFE's frame between its neighbours, at most 3 and never two side by side, recorded in the report (docs/loop-repair.md); where no RIFE is installed a loop that needs a frame is cut as filmed with a warning (`sprite-gen rife install` adds RIFE); on: the same repair, but no RIFE fails the loop; off: cut as filmed")parser.add_argument("--jolt-max", type=float, default=None, help=f"walk/run: fail the repaired loop when its jolt index (how far each step strays from its neighbours' mean, over the median step) exceeds this. Default: no gate — the index is reported and a value over {repair_mod.JOLT_REFERENCE} is a warning line")parser.add_argument("--head-step-max", type=float, default=None, help=f"walk/run: fail the repaired loop when the head's largest sideways move in one frame exceeds this %% of the body height. Default: no gate — reported, and over {repair_mod.HEAD_STEP_REFERENCE} is a warning line")parser.add_argument("--facing", choices=FACINGS, default="right", help="which way the body faces in the frames (default right): the hair the jump search watches is behind it")diff --git a/sprite_gen/video/rife.py b/sprite_gen/video/rife.pyindex 6bb1a30..6dc28d3 100644--- a/sprite_gen/video/rife.py+++ b/sprite_gen/video/rife.py@@ -11,6 +11,11 @@ The binary's own CPU path (`-g -1`) returns a wrong frame with rife-v4.6 on bothLinux (measured 2026-10-03: mean error 39 against 3.3 through Vulkan), so it is never passed;a machine without a GPU runs the Vulkan path on Mesa's llvmpipe, which gives the GPU's frame.+The binary is found by SPRITE_GEN_RIFE, then on PATH, then where `sprite-gen rife install`+puts it (`install_root()`, docs/loop-repair.md section 1). A RIFE that cannot be found is+`RifeNotInstalled`, which a caller may answer by cutting the loop as filmed with a warning; a+RIFE that is found and then fails is `RifeUnavailable` and always an error.+The interpolator is a plain callable `(a, b, t) -> frame`, so a caller can be handed a stand-in(`Interpolate`), and a test needs no binary."""@@ -20,6 +25,7 @@ from __future__ import annotationsimport osimport shutilimport subprocess+import sysimport tempfilefrom pathlib import Pathfrom typing import Callable@@ -37,30 +43,73 @@ CALL_TIMEOUT_SECONDS = 120Interpolate = Callable[[Image.Image, Image.Image, float], Image.Image]+# The one line that installs it, quoted wherever a missing RIFE is reported.+INSTALL_COMMAND = "sprite-gen rife install"INSTALL_HINT = (- f"install rife-ncnn-vulkan {RELEASE} (github.com/nihui/rife-ncnn-vulkan/releases/tag/{RELEASE}; "- f"on Linux without a GPU also `libvulkan1 mesa-vulkan-drivers`) and put it on PATH or set SPRITE_GEN_RIFE "- f"to the binary — the model {MODEL}/ ships beside it (SPRITE_GEN_RIFE_MODEL overrides); see docs/loop-repair.md"+ f"run `{INSTALL_COMMAND}` (rife-ncnn-vulkan {RELEASE} with the model {MODEL}, sha256-checked, into the "+ f"user data directory), or put {BINARY} on PATH or set SPRITE_GEN_RIFE to the binary — the model {MODEL}/ "+ f"ships beside it (SPRITE_GEN_RIFE_MODEL overrides); on Linux without a GPU also `libvulkan1 mesa-vulkan-drivers`; "+ f"see docs/loop-repair.md")class RifeUnavailable(RuntimeError):- """No usable RIFE binary or model. The message names what is missing and how to install it."""+ """No usable RIFE: not installed, or found and failed. The message names what went wrong."""+++class RifeNotInstalled(RifeUnavailable):+ """No RIFE binary or model where the engine looks. The message carries the install line."""+++def platform_release() -> str:+ """The release zip's platform name for this machine (`macos`, `ubuntu`, `windows`), or '' when it ships none."""+ if sys.platform == "darwin":+ return "macos"+ if sys.platform.startswith("linux"):+ return "ubuntu"+ if sys.platform == "win32":+ return "windows"+ return ""+++def data_dir() -> Path:+ """sprite-gen's user data directory: SPRITE_GEN_DATA_DIR, else %LOCALAPPDATA%\\sprite-gen on+ Windows, else $XDG_DATA_HOME/sprite-gen or ~/.local/share/sprite-gen."""+ named = os.environ.get("SPRITE_GEN_DATA_DIR")+ if named:+ return Path(named).expanduser()+ if sys.platform == "win32" and os.environ.get("LOCALAPPDATA"):+ return Path(os.environ["LOCALAPPDATA"]) / "sprite-gen"+ return Path(os.environ.get("XDG_DATA_HOME") or Path.home() / ".local" / "share").expanduser() / "sprite-gen"+++def install_root() -> Path:+ """Where `sprite-gen rife install` puts RIFE by default, and the last place `locate()` looks."""+ return data_dir() / "rife"+++def installed_binary(root: Path | None = None, platform: str | None = None) -> Path:+ """The binary inside an install root: `<root>/rife-ncnn-vulkan-<release>-<platform>/rife-ncnn-vulkan[.exe]`."""+ platform = platform or platform_release()+ return (root or install_root()) / f"{BINARY}-{RELEASE}-{platform}" / (BINARY + (".exe" if platform == "windows" else ""))def locate() -> tuple[Path, Path]:- """(binary, model directory), from SPRITE_GEN_RIFE / PATH and SPRITE_GEN_RIFE_MODEL / beside the binary."""+ """(binary, model directory): the binary from SPRITE_GEN_RIFE, else PATH, else `install_root()`;+ the model from SPRITE_GEN_RIFE_MODEL, else beside the binary."""named = os.environ.get("SPRITE_GEN_RIFE")- found = named or shutil.which(BINARY)+ installed = installed_binary() if platform_release() else None+ found = named or shutil.which(BINARY) or (str(installed) if installed and installed.is_file() else None)if not found:- raise RifeUnavailable(f"{BINARY} not found on PATH and SPRITE_GEN_RIFE is not set; {INSTALL_HINT}")+ raise RifeNotInstalled(f"{BINARY} not found (SPRITE_GEN_RIFE is not set, it is not on PATH, and "+ f"{installed or install_root()} does not exist); {INSTALL_HINT}")binary = Path(found).expanduser()if not binary.is_file() or not os.access(binary, os.X_OK):- raise RifeUnavailable(f"{binary} is not an executable file; {INSTALL_HINT}")+ raise RifeNotInstalled(f"{binary} is not an executable file; {INSTALL_HINT}")binary = binary.resolve()model = Path(os.environ.get("SPRITE_GEN_RIFE_MODEL") or binary.parent / MODEL).expanduser()if not (model / "flownet.param").is_file() or not (model / "flownet.bin").is_file():- raise RifeUnavailable(f"RIFE model {model} has no flownet.param / flownet.bin; {INSTALL_HINT}")+ raise RifeNotInstalled(f"RIFE model {model} has no flownet.param / flownet.bin; {INSTALL_HINT}")return binary, modeldiff --git a/tests/video/test_cycle_align.py b/tests/video/test_cycle_align.pyindex 5023f79..be743fb 100644--- a/tests/video/test_cycle_align.py+++ b/tests/video/test_cycle_align.py@@ -10,6 +10,7 @@ from __future__ import annotationsimport jsonimport math+import osfrom pathlib import Pathimport numpy as np@@ -136,3 +137,52 @@ def test_video_set_aligns_each_gait_filmed_in_two_or_more_directions(tmp_path):assert rows[0]["loop"]["cycle_align"]["from"] == 20assert (tmp_path / "walk.cycle-align.json").is_file()assert batch.align_gaits(rows, tmp_path, "off") == {}+++def _no_rife(monkeypatch, tmp_path: Path) -> None:+ monkeypatch.delenv("SPRITE_GEN_RIFE", raising=False)+ # PATH keeps every other tool (img2webp, ffmpeg); only the directories holding a RIFE go+ 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 test_video_cycle_align_without_rife_fails_and_leaves_the_set_as_cut(tmp_path, monkeypatch):+ dirs = [_cut(tmp_path, n, L) for n, L in (("S", 20), ("E", 24), ("N", 28))]+ before = [(d / "walk.strip.png").read_bytes() for d in dirs]+ _no_rife(monkeypatch, tmp_path)+ with pytest.raises(SystemExit, match=r"video-cycle-align: .*rife-ncnn-vulkan not found.*sprite-gen rife install"):+ align.run(loop_dir=dirs, length=None, report=None)+ assert [(d / "walk.strip.png").read_bytes() for d in dirs] == before+++def test_video_set_without_rife_skips_the_alignment_with_a_warning(tmp_path, monkeypatch, capsys):+ from sprite_gen.video import batch++ rows = []+ for direction, length in (("front", 20), ("side", 24)):+ item = tmp_path / f"{direction}-walk"+ item.mkdir()+ _cut(item, "loop", length)+ rows.append({"item": f"{direction}-walk", "direction": direction, "state": "walk", "dir": str(item), "ok": True,+ "loop": {"n_out": length}})+ _no_rife(monkeypatch, tmp_path)+ out = batch.align_gaits(rows, tmp_path, "auto")+ assert out["walk"]["ok"] is True and out["walk"]["applied"] is False+ assert out["walk"]["install"] == "sprite-gen rife install" and "rife-ncnn-vulkan not found" in out["walk"]["rife"]+ assert [r["loop"]["n_out"] for r in rows] == [20, 24] and "cycle_align" not in rows[0]["loop"]+ assert not (tmp_path / "walk.cycle-align.json").exists()+ err = capsys.readouterr().err+ assert "video-set: warning: walk: cycles not aligned" in err and "sprite-gen rife install" in err+++def test_cutting_a_loop_again_drops_the_kept_source(tmp_path):+ """Once RIFE is installed a loop is cut again; the next alignment must read that cut."""+ dirs = [_cut(tmp_path, n, L) for n, L in (("S", 20), ("E", 24))]+ align.align_set(dirs, interpolate=Recorder())+ assert (dirs[0] / align.SOURCE_DIR).is_dir()+ keyed = tmp_path / "S-keyed"+ loop_mod.run_loop(keyed, dirs[0], fps=24.0, state="walk", min_len=None, max_len=None, n_out=None, seam_max=1000.0,+ name="walk", report_path=None, cycle_mode="fixed", start=0, length=22, anchor="none", repair="off")+ assert not (dirs[0] / align.SOURCE_DIR).exists()+ assert align.align_set(dirs, interpolate=Recorder())["lengths"] == [22, 24]diff --git a/tests/video/test_loop_repair.py b/tests/video/test_loop_repair.pyindex daaecdc..1e3d6d2 100644--- a/tests/video/test_loop_repair.py+++ b/tests/video/test_loop_repair.py@@ -2,8 +2,9 @@"""Jump-frame repair (docs/loop-repair.md section 2): only the frame after a jump is replaced,by the interpolator's frame between its two neighbours; at most three, never two side by side;the hair watched is behind the body whichever way it faces; and `video-loop` records what it-replaced, gates the cells as they now play, and refuses — naming `--repair off` — when a frame-needs making and no RIFE is installed.+replaced and gates the cells as they now play. When a frame needs making and no RIFE is+installed, `--repair auto` cuts the loop as filmed with a warning and the install line, and+`--repair on` refuses.The interpolator is a stand-in that returns the true in-between of the synthetic loop, so thetests need no binary and can say exactly which frame should come back."""@@ -12,6 +13,7 @@ from __future__ import annotationsimport jsonimport math+import osfrom pathlib import Pathimport numpy as np@@ -142,17 +144,75 @@ def test_video_loop_records_the_repair_and_plays_the_made_frame(tmp_path):assert made == [0.5]-def test_a_jump_without_rife_is_refused_naming_repair_off(tmp_path, monkeypatch):+def _no_rife(monkeypatch, tmp_path: Path) -> None:+ """No RIFE anywhere the engine looks: no SPRITE_GEN_RIFE, an empty PATH, an empty data directory."""monkeypatch.delenv("SPRITE_GEN_RIFE", raising=False)- monkeypatch.setenv("PATH", str(tmp_path / "empty"))+ # PATH keeps every other tool (img2webp, ffmpeg); only the directories holding a RIFE go+ 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 test_a_jump_without_rife_is_cut_as_filmed_with_a_warning(tmp_path, monkeypatch, capsys):+ _no_rife(monkeypatch, tmp_path)filmed, _ = _loop({10: 12})keyed = _keyed(tmp_path, filmed)- with pytest.raises(SystemExit, match=r"--repair off"):- _run(tmp_path, keyed)+ reopened = [Image.open(p).convert("RGBA") for p in sorted(keyed.glob("*.png"))][:N]+ rep = _run(tmp_path, keyed)+ assert rep["status"] == "passed"+ jr = rep["jump_repair"]+ assert jr["applied"] is False and jr["replaced"] == [] and jr["why"] == "RIFE not installed — cut as filmed"+ assert jr["install"] == "sprite-gen rife install" and "rife-ncnn-vulkan not found" in jr["rife"]+ assert jr["score_max_before"] >= repair.JUMP_RATIO and jr["score_max_after"] == jr["score_max_before"]+ assert rep["seam_measurement"] == "source-frames" and rep["jolt"]["measured"] == "as filmed"+ on_disk = np.asarray(Image.open(tmp_path / "out" / "cycle" / "frame-010.png"))+ assert np.array_equal(on_disk, np.asarray(reopened[10])) # the jump frame stays as filmed+ warning = [l for l in capsys.readouterr().err.splitlines() if "jump frame was not repaired" in l]+ assert len(warning) == 1 and "sprite-gen rife install" in warning[0]+ assert json.loads((tmp_path / "w.json").read_text())["jump_repair"]["applied"] is False+++def test_a_smooth_walk_without_rife_has_nothing_to_warn_about(tmp_path, monkeypatch, capsys):+ _no_rife(monkeypatch, tmp_path)+ filmed, _ = _loop()+ rep = _run(tmp_path, _keyed(tmp_path, filmed))+ assert rep["jump_repair"]["replaced"] == [] and "rife" not in rep["jump_repair"]+ assert "not repaired" not in capsys.readouterr().err+++def test_repair_on_without_rife_is_refused_with_the_install_line(tmp_path, monkeypatch):+ _no_rife(monkeypatch, tmp_path)+ filmed, _ = _loop({10: 12})+ with pytest.raises(SystemExit, match=r"sprite-gen rife install.*--repair auto"):+ _run(tmp_path, _keyed(tmp_path, filmed), repair="on")report = json.loads((tmp_path / "w.json").read_text())assert report["status"] == "failed" and "rife-ncnn-vulkan not found" in report["error"]+def test_repair_on_with_rife_repairs_as_auto_does(tmp_path):+ filmed, truth = _loop({10: 12})+ rep = _run(tmp_path, _keyed(tmp_path, filmed), repair="on", interpolate=lambda a, b, t: truth[10])+ assert rep["jump_repair"]["replaced"] == [10] and rep["jump_repair"]["applied"] is True+++def test_a_rife_that_is_found_and_fails_still_fails_the_loop(tmp_path):+ from sprite_gen.video import rife++ def broken(a, b, t):+ raise rife.RifeUnavailable("rife-ncnn-vulkan failed (exit 255): vkCreateInstance failed")++ filmed, _ = _loop({10: 12})+ with pytest.raises(SystemExit, match=r"vkCreateInstance failed.*--repair off"):+ _run(tmp_path, _keyed(tmp_path, filmed), interpolate=broken)+++def test_a_jolt_gate_on_a_loop_left_unrepaired_says_rife_was_missing(tmp_path, monkeypatch):+ _no_rife(monkeypatch, tmp_path)+ filmed, _ = _loop({10: 12})+ with pytest.raises(SystemExit, match=r"regenerate the clip \(the jump repair did not run: RIFE is not installed"):+ _run(tmp_path, _keyed(tmp_path, filmed), jolt_max=0.01)++def test_repair_off_cuts_as_filmed_and_says_so(tmp_path):filmed, _ = _loop({10: 12})rep = _run(tmp_path, _keyed(tmp_path, filmed), repair="off")diff --git a/tests/video/test_rife.py b/tests/video/test_rife.pyindex 99bc7bb..fa93393 100644--- a/tests/video/test_rife.py+++ b/tests/video/test_rife.py@@ -20,7 +20,7 @@ from sprite_gen.video import rifedef _fake_binary(tmp_path: Path, with_model: bool = True) -> Path:binary = tmp_path / "bin" / rife.BINARY- binary.parent.mkdir()+ binary.parent.mkdir(parents=True)binary.write_text("#!/bin/sh\nexit 0\n")binary.chmod(binary.stat().st_mode | stat.S_IXUSR)if with_model:@@ -33,10 +33,47 @@ def _fake_binary(tmp_path: Path, with_model: bool = True) -> Path:def test_missing_binary_is_refused_with_the_install_line(monkeypatch, tmp_path):monkeypatch.delenv("SPRITE_GEN_RIFE", raising=False)monkeypatch.setenv("PATH", str(tmp_path))- with pytest.raises(rife.RifeUnavailable, match="install rife-ncnn-vulkan 20221029"):+ monkeypatch.setenv("SPRITE_GEN_DATA_DIR", str(tmp_path / "data"))+ with pytest.raises(rife.RifeNotInstalled, match=r"run `sprite-gen rife install` \(rife-ncnn-vulkan 20221029"):rife.locate()+def test_the_installed_copy_is_found_after_the_environment_and_path(monkeypatch, tmp_path):+ """SPRITE_GEN_RIFE, then PATH, then the install root of `sprite-gen rife install`."""+ monkeypatch.setenv("SPRITE_GEN_DATA_DIR", str(tmp_path / "data"))+ monkeypatch.delenv("SPRITE_GEN_RIFE", raising=False)+ monkeypatch.delenv("SPRITE_GEN_RIFE_MODEL", raising=False)+ monkeypatch.setenv("PATH", str(tmp_path / "empty"))+ staged = _fake_binary(tmp_path / "staged")+ installed = rife.installed_binary()+ assert installed.parent.parent == tmp_path / "data" / "rife"+ installed.parent.parent.mkdir(parents=True)+ staged.parent.rename(installed.parent)+ assert rife.locate()[0] == installed.resolve()+ on_path = _fake_binary(tmp_path / "path")+ monkeypatch.setenv("PATH", str(on_path.parent))+ assert rife.locate()[0] == on_path.resolve()+ named = _fake_binary(tmp_path / "named")+ monkeypatch.setenv("SPRITE_GEN_RIFE", str(named))+ assert rife.locate()[0] == named.resolve()+++def test_the_data_directory_follows_the_platform_rules(monkeypatch, tmp_path):+ monkeypatch.delenv("SPRITE_GEN_DATA_DIR", raising=False)+ monkeypatch.setattr(rife.sys, "platform", "linux")+ monkeypatch.setenv("XDG_DATA_HOME", str(tmp_path / "xdg"))+ assert rife.data_dir() == tmp_path / "xdg" / "sprite-gen"+ assert rife.installed_binary().parent.name == "rife-ncnn-vulkan-20221029-ubuntu"+ monkeypatch.delenv("XDG_DATA_HOME")+ assert rife.data_dir() == Path.home() / ".local" / "share" / "sprite-gen"+ monkeypatch.setattr(rife.sys, "platform", "win32")+ monkeypatch.setenv("LOCALAPPDATA", str(tmp_path / "local"))+ assert rife.data_dir() == tmp_path / "local" / "sprite-gen"+ assert rife.installed_binary().name == "rife-ncnn-vulkan.exe"+ monkeypatch.setenv("SPRITE_GEN_DATA_DIR", str(tmp_path / "named"))+ assert rife.data_dir() == tmp_path / "named"++def test_model_beside_the_binary_is_found(monkeypatch, tmp_path):binary = _fake_binary(tmp_path)monkeypatch.setenv("SPRITE_GEN_RIFE", str(binary))