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): --between-cache, what keys a kept frame and who owns the directory

Soohong Kim3778e92e6821
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 09e3de1..930b042 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,6 +4,9 @@ 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.
+
- **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.
- **Preferences file version 2.** `preferences.json` keeps, beside the `sprite` and `image` profiles, the `general` settings every profile shares (`codex_unavailable`). A version 1 file still reads, with nothing chosen; the next save writes version 2, which an earlier sprite-gen refuses as unknown. `defaults save --codex-unavailable` needs no `--kind`.
diff --git a/docs/loop-repair.md b/docs/loop-repair.md
index 3d4bed1..611df97 100644
--- a/docs/loop-repair.md
+++ b/docs/loop-repair.md
@@ -538,7 +538,7 @@ same number of frames, starting on the same step.
sprite-gen video-cycle-align --loop-dir set/front-walk/loop --loop-dir set/side-walk/loop \
--loop-dir set/back-walk/loop [--view front --view side@right --view back] [--start-foot right] \
[--between auto|rife|nearest] [--length N] [--cycles back-walk=2] [--multi-cycle fail|warn] \
- [--foot side-walk=left] [--state walk] [--report set/walk.cycle-align.json]
+ [--foot side-walk=left] [--state walk] [--between-cache DIR] [--report set/walk.cycle-align.json]
```
- **A loop whose steps are counted is one cycle.** A cut two steps long — taken so a held part
@@ -896,6 +896,21 @@ 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.
- 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`