Generate clean 2D game sprites & animation atlases — component-row pipeline: state rows, alpha cleanup, frame extraction, runtime atlases. Codex/Claude skill.
fix(video-cycle-align): a frame between is kept under the RIFE augmentation it was made with
Soohong Kim1cd1a265d68c
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 6950578..1e065c2 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -22,8 +22,8 @@ All notable public changes to `sprite-gen` are recorded here. Versions track the- **Tests** — `tests/video/test_loop_flow.py` (an ordinary walk the jump score would remake is left alone and RIFE is not called; a flung frame made again half way between its neighbours, every other frame the video's own; two flung frames made again at a third and two thirds; on twos a flung drawing made once from the frames two before and two after it and shown on both its frames; a group with one made frame at fault keeps both frames and is not tried again; the calls go to the worst frame first and stop at three, the group left named; no interpolator names the group; mirrored, the same) and `tests/video/test_loop_repair.py` (on its block walker: one flung frame, two side by side, the pair flung at the wrap taken out whole and made from the frames beside it rather than smoothed at its edges, jumps a few frames apart read a drawing a frame and not on threes, three outline-melted groups refused within the budget, groups made only from frames as filmed; `video-loop` playing two frames made again at their own times in a loop as long, and the flow numbers when no RIFE is installed); the ghost and cross-fade proposals of `tests/video/test_ghost_screen.py`, `tests/video/test_crossfade.py` and the real-RIFE case of `tests/video/test_rife.py` read through a group the flow reading is made to name.- **Tests** — `tests/video/test_loop_flow.py` (an ordinary walk whose quick swing the jump score names has no frame taken; a frame flung against the sway is the one frame taken, read behind the body and turning back; a tail that snaps back at a wrap that does not close takes a frame at the wrap; the same whichever way the body faces; a walk on twos read on its drawings, a drawing flung the two frames that show it; two frames flung in a row one group of two; three flung frames three groups, none made from a frame taken before; a span too short named `unfixed`; a loop of three drawings left alone; a loop with no body refused).-- **New: `video-cycle-align --between-cache DIR` caches frames made between source frames so later alignments take kept frames instead of making them again.** Previously, running alignment a second time to specify `--foot` or after a retake remade every interpolated frame, even though source frames and fractions did not change. Now, every frame RIFE makes between two source frames is saved in `DIR` as a PNG keyed by the sha256 of its inputs and interpolator identity, and any later run with identical inputs reuses the kept frame. The interpolator identity is read for every frame, so a binary, model or host that changed makes the frame again. A frame made while its inputs changed is handed on but not kept (`not_kept`). The user passes `--between-cache DIR` (or `between_cache=path` in Python) and removes `DIR` when the alignment is done. The summary and report record `dir`, `hits`, `misses`, `unreadable`, and `not_kept` under `between_cache`, which is `null` without the flag ([loop repair](docs/loop-repair.md#4-one-cycle-for-a-direction-set--video-cycle-align-video-set---align-cycles-auto)).-- **Tests**: `tests/video/test_between_cache.py` (two passes under `--between rife` and `--between auto`: the second takes every kept frame, with matching files and report; one changed source pixel remakes only the frames made from it while the others are taken; another length gives the same loops as a pass without the directory; swapped frames, another fraction (even one a float apart) or one moved pixel miss; frames that are not RGBA are refused; under one `rife.Rife` object, with a stand-in RIFE that runs and picks its output by its model's and its own bytes: its model's bytes written over, its binary written over, a file added to its model, and its model files under another directory name each make the frame again, and every frame taken equals the frame the same object makes without the directory; a RIFE whose model directory is gone fails as a RIFE that fails; under one `rife.Rife`: another host name or OS build, NumPy or Pillow version, or engine code loaded anew make the frame again, while `rife.py` written over on disk after the import (no code that runs) takes the frame the loaded code made; a frame made while its model was written over between RIFE's two runs is handed on as made and not kept (`not_kept`), and the next pass makes it again; corrupt, truncated or overwritten kept files are made again and written over; the directory and its files are readable and writable by the user only (no group or other permission bits); alignments without the flag store nothing; injected interpolators without an `identity()` method are refused; the summary and report record the cache counts; a `real_rife` run matches the sha256 of fresh frames). Synthetic fixtures only.+- **New: `video-cycle-align --between-cache DIR` caches frames made between source frames so later alignments take kept frames instead of making them again.** Previously, running alignment a second time to specify `--foot` or after a retake remade every interpolated frame, even though source frames and fractions did not change. Now, every frame RIFE makes between two source frames is saved in `DIR` as a PNG keyed by the sha256 of its inputs and interpolator identity, and any later run with identical inputs reuses the kept frame. The interpolator identity is read for every frame, so a binary, model, augmentation (`SPRITE_GEN_RIFE_TTA`) or host that changed makes the frame again. A frame made while its inputs changed is handed on but not kept (`not_kept`). The user passes `--between-cache DIR` (or `between_cache=path` in Python) and removes `DIR` when the alignment is done. The summary and report record `dir`, `hits`, `misses`, `unreadable`, and `not_kept` under `between_cache`, which is `null` without the flag ([loop repair](docs/loop-repair.md#4-one-cycle-for-a-direction-set--video-cycle-align-video-set---align-cycles-auto)).+- **Tests**: `tests/video/test_between_cache.py` (two passes under `--between rife` and `--between auto`: the second takes every kept frame, with matching files and report; one changed source pixel remakes only the frames made from it while the others are taken; another length gives the same loops as a pass without the directory; swapped frames, another fraction (even one a float apart) or one moved pixel miss; frames that are not RGBA are refused; under one `rife.Rife` object, with a stand-in RIFE that runs and picks its output by its model's and its own bytes: its model's bytes written over, its binary written over, a file added to its model, and its model files under another directory name each make the frame again, and every frame taken equals the frame the same object makes without the directory; a frame kept without augmentation is made again under the default `-x -z` and under `-z` alone, and taken again without; a RIFE whose model directory is gone fails as a RIFE that fails; under one `rife.Rife`: another host name or OS build, NumPy or Pillow version, or engine code loaded anew make the frame again, while `rife.py` written over on disk after the import (no code that runs) takes the frame the loaded code made; a frame made while its model was written over between RIFE's two runs is handed on as made and not kept (`not_kept`), and the next pass makes it again; corrupt, truncated or overwritten kept files are made again and written over; the directory and its files are readable and writable by the user only (no group or other permission bits); alignments without the flag store nothing; injected interpolators without an `identity()` method are refused; the summary and report record the cache counts; a `real_rife` run matches the sha256 of fresh frames). Synthetic fixtures only.- **Behavior change: a call that names no provider stops and asks when codex cannot run, unless you chose what to do.** `gen`, `logo`, `gen-set` and `video-set`'s mid-step redraw run on codex when no `--provider` is named. When codex was not signed in, they used to switch to `grok` without asking (said on stderr, kept in the report) — and with no Grok login that meant `XAI_API_KEY`, billed per call. Now codex that cannot run — not signed in (`codex login status`), or its usage used up (`codex exec` ends on one of the errors codex classes as its usage limit) — follows a choice: `ask` (the default) generates nothing and ends with one stderr line, `sprite-gen ask codex-unavailable: {…}` (the cause, the reason, the question and the flag that runs each answer), and **exit 75**; `grok` or `openai` runs that provider, said on stderr and kept in the report as `provider_fallback` (now with `cause` and `chosen_by`), `openai` with its per-call charge line as always. The choice is `SPRITE_GEN_CODEX_UNAVAILABLE`, else `sprite-gen defaults save --codex-unavailable ask|grok|openai`, else `ask`; the guided `workflow` asks it once and saves it. A usage limit is known only after `codex exec` ran, so the call runs again on the chosen provider. A named `--provider` runs as named: a named codex whose usage is used up still fails with codex's own words, exit 1. `gen-set` and `video-set` whose child asked stop with the same question and exit 75 (naming `--provider`, or `--still-provider`), their reports and tables keep it under `asked`, and `gen-set --provider` now takes `openai`. `openai` runs only when you chose it: named, or as this answer — still never a default, never the guided image provider ([gen](docs/gen.md#when-codex-cannot-run--ask-or-what-you-chose), [SKILL](SKILL.md#when-codex-cannot-run--exit-75)).- **The usage-limit signal is codex's own words, read from its source** (codex-rs at `rust-v0.160.1` and `rust-v0.153.4`): `codex exec --json` carries only the message of codex's usage-limit errors (`UsageLimitReached`, `QuotaExceeded`, `UsageNotIncluded`, which codex classes as `UsageLimitExceeded`), so `codex_provider.usage_limit` matches the start of each message as codex's tests pin it — "You've hit your usage limit" with either apostrophe (0.153.4 writes it ASCII, 0.160.1 as U+2019), "Your workspace is out of credits.", "You hit your spend cap set", "Quota exceeded. Check your plan and billing details." and "To use Codex with your ChatGPT plan, upgrade to Plus". Any other codex failure is a failure, not the question.diff --git a/docs/loop-repair.md b/docs/loop-repair.mdindex e7e2004..6f3fa03 100644--- a/docs/loop-repair.md+++ b/docs/loop-repair.md@@ -1523,14 +1523,16 @@ sprite-gen video-cycle-align --loop-dir set/front-walk/loop --loop-dir set/side-must be RGBA: mode, size, and pixel bytes; other modes are refused), the exact fraction `t`, and theinterpolator identity. The identity is read again for every frame asked for, and nothing of it isremembered: the RIFE binary file and each file in the model directory, by sha256; the model directory's- path as given to the binary (the binary reads the model's version from the directory name); the engine- code as loaded, which is the sha256 of `sprite_gen/video/rife.py` read once at import (`rife.py` written+ path as given to the binary (the binary reads the model's version from the directory name); the+ augmentation every call asks for at that moment (`rife.tta()`: `SPRITE_GEN_RIFE_TTA`, or the default+ `-x -z` when it is not set — section 1, "Which setting"), as another augmentation makes another frame; the+ engine code as loaded, which is the sha256 of `sprite_gen/video/rife.py` read once at import (`rife.py` writtenover on disk during a run changes no code that is running, so a frame made by the loaded code is keptunder that code, and a later process that loads other code gets another key and makes the frames again);the NumPy and Pillow versions; and the host as `os.uname()` reports it at that moment (host name,OS release, build, and architecture), with the OS platform. A binary or model file that cannot be readfails the alignment, as a RIFE that fails does. Any change in cycle length, `--cycles`, source pixels,- binary, model, engine code, or host makes the frame again. The key does not read the GPU driver or its+ binary, model, augmentation, engine code, or host makes the frame again. The key does not read the GPU driver or itsenvironment; a caller that changes those between passes gives each pass its own directory. Reading theidentity hashes 36.5 MB of binary and model files in about 17 ms on an Apple M1: once for a frame taken,twice for a frame made (making a frame with RIFE takes on the order of a second). After a frame is made,diff --git a/sprite_gen/video/rife.py b/sprite_gen/video/rife.pyindex bf5cf51..9c60ab5 100644--- a/sprite_gen/video/rife.py+++ b/sprite_gen/video/rife.py@@ -585,8 +585,9 @@ class Rife:"""What a frame this RIFE makes depends on besides its two frames and t, as one string (`Cache` keyson it), read as it is now on every call — nothing of it is kept, so a binary, model or machine changedunder this very RIFE is another identity: the binary's and each of the model's files by sha256, and the- model's path as the binary is handed it (the binary reads the model's version from its name); the engine- code this process loaded (`CODE_SHA256`: it turns a frame into RIFE's two runs and back) and NumPy's and+ model's path as the binary is handed it (the binary reads the model's version from its name); the+ augmentation every call asks for now (`tta()`: SPRITE_GEN_RIFE_TTA is read on every call, and another is+ another frame); the engine code this process loaded (`CODE_SHA256`: it turns a frame into RIFE's two runs and back) and NumPy's andPillow's versions; and the machine — the OS, and `uname`'s host name, OS release and build andarchitecture (platform.uname() keeps its first answer) — as the Apple GPU and llvmpipe are only measuredto agree to the third decimal of an error (docs/loop-repair.md section 1), so a frame made on one is not@@ -597,7 +598,7 @@ class Rife:except OSError as exc:raise RifeUnavailable(f"{self.binary.name}: the binary or model it runs from could not be read: {exc}") from excreturn json.dumps({- **files, "code": CODE_SHA256, "numpy": np.__version__, "pillow": PIL.__version__,+ **files, "tta": list(tta()), "code": CODE_SHA256, "numpy": np.__version__, "pillow": PIL.__version__,"machine": [sys.platform, *(os.uname() if hasattr(os, "uname") else platform.uname()[:5])]}, sort_keys=True)