Skip to content

Generate clean 2D game sprites & animation atlases — component-row pipeline: state rows, alpha cleanup, frame extraction, runtime atlases. Codex/Claude skill.

docs(video-cycle-align): the between-cache identity is read for every frame; not_kept

Soohong Kim530353e4f906
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 930b042..4fe1dd2 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,8 +4,8 @@ All notable public changes to `sprite-gen` are recorded here. Versions track the
## Unreleased
-- **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 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`, and `unreadable` 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` take every kept frame on the second pass with matching files and report; one changed pixel remakes only its own frames while others hit; another length gives the same loops as a pass without the directory; swapped frames, different fractions, altered model files, changed binaries, different machines, or modified engine code miss the cache; corrupt, truncated, or overwritten kept files are remade and overwritten; 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 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 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.
- **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.md
index 611df97..e3ca644 100644
--- a/docs/loop-repair.md
+++ b/docs/loop-repair.md
@@ -896,21 +896,33 @@ sprite-gen video-cycle-align --loop-dir set/front-walk/loop --loop-dir set/side-
none: its cut is no longer there to read. With `cells_from` it lets a follow-through whose
regions were read on the cut be carried to the aligned loop (`video-follow --read-on`,
docs/video-pipeline.md section 6). Neither record changes a pixel of the strip, GIF or WebP.
-- **Frames between are kept for later passes** (`--between-cache DIR`): every frame RIFE makes
- between two source frames is stored in `DIR`. A later alignment given the same `DIR` takes a kept
- frame instead of making it again, such as when aligning again with `--foot` or after retaking one
- loop. A frame is taken only for identical inputs: it is keyed by the sha256 of the format, both
- source frames (mode, size, and pixel bytes), the exact fraction `t`, and the interpolator identity
- (the binary, model files, `sprite_gen/video/rife.py`, NumPy and Pillow versions, and host). Any
- change in cycle length, `--cycles`, source pixels, engine code, or host creates a new key. Each
- kept frame is a PNG file named by its key, with its pixel sha256 in a text chunk, written to a
- temporary file and renamed into place. A kept file that does not read back as that frame is made
- again, written over, and counted as `unreadable`. A taken frame is a new image of exactly the kept
- pixels, so the aligned loop is the same, byte for byte, as an alignment without the directory.
- Nothing is kept without `--between-cache` (there is no default directory). The caller gives each
- alignment its own directory and removes it when that alignment is done. The engine creates `DIR`
- mode 0700 and files mode 0600, never deletes `DIR`, and records `hits`, `misses`, and `unreadable`
- under `between_cache` in the summary and report.
+- **Frames between are kept for later passes** (`--between-cache DIR`): every frame RIFE makes between
+ two source frames is stored in `DIR`. A later alignment given the same `DIR` takes a kept frame instead
+ of making it again, such as when aligning again with `--foot` or after retaking one loop. A frame is
+ taken only for identical inputs: it is keyed by the sha256 of the format, both source frames (which
+ must be RGBA: mode, size, and pixel bytes; other modes are refused), the exact fraction `t`, and the
+ interpolator identity. The identity is read again for every frame asked for, and nothing of it is
+ remembered: 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
+ over on disk during a run changes no code that is running, so a frame made by the loaded code is kept
+ under 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 read
+ fails 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
+ environment; a caller that changes those between passes gives each pass its own directory. Reading the
+ identity 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,
+ its key is read again; if anything it is made from changed while it was being made, the frame is handed
+ on but not kept, and counted as `not_kept`. Each kept frame is a PNG file named by its key, with its
+ pixel sha256 in a text chunk, written to a temporary file and renamed into place. A kept file that does
+ not read back as that frame is made again, written over, and counted as `unreadable`. A taken frame is
+ a new image of exactly the kept pixels, so the aligned loop is the same, byte for byte, as an alignment
+ without the directory. Nothing is kept without `--between-cache` (there is no default directory). The
+ caller gives each alignment its own directory and removes it when that alignment is done. The engine
+ creates `DIR` mode 0700 and files mode 0600, never deletes `DIR`, and records `dir`, `hits`, `misses`,
+ `unreadable`, and `not_kept` under `between_cache` in the summary and report.
- Loops at different frame rates are refused (one length in frames would mean different
durations), and so is a loop cut before `cell_height_cap` was recorded (cut it again). So is a
loop never aligned whose strip as cut is missing — its `<name>.strip.png`, or `follow.source.png`