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: the skill and the docs each generation request reads keep the agent's rules and pointers, not history or the code's own behaviour — dates, version notes, measurement stories, copies of loop-repair, prompt-assembly, ui-kit and recolor text, and the descriptions of algorithms, thresholds, report fields and refusal lists the code and tests already own leave SKILL.md, user-workflow, video, gen, atlas-workflow, curation and video-pipeline; SKILL.md keeps the exit-75 question, the facing rules no doc holds and the "offer the RIFE install" step, its route cells name the task and the doc, and the one-shot-actions anchor is spelled the way GitHub slugs it

Soohong Kimd7db8da673a1
diff --git a/SKILL.md b/SKILL.md
index 3d442ac..c52b3bc 100644
--- a/SKILL.md
+++ b/SKILL.md
@@ -59,8 +59,6 @@ $SPRITE_GEN_ROOT/.venv/bin/sprite-gen workflow --kind sprite
$SPRITE_GEN_ROOT/.venv/bin/sprite-gen workflow --kind image
```
-Pass choices already stated in the request. The guide checks access, combines explicit choices with saved defaults, and returns only missing questions. Follow its start and finish stages. Always pass the resolved provider explicitly to generation tools. Deliver checked files before offering the curation view; save defaults only when the user agrees. The complete conversation and settings contract is owned by the linked document, not duplicated in individual pipeline docs.
-
## When codex cannot run — exit 75
A call that names no provider (`gen`, `logo`, `gen-set`, `video-set`'s mid-step redraw) runs on codex. When codex cannot run here — not signed in, or the codex usage of the account used up — and the user's choice for that is to ask (the default), the command generates nothing, prints one stderr line starting `sprite-gen ask codex-unavailable:` followed by JSON, and ends with **exit 75**. That is a question for the user, not a failure: never answer it yourself, never retry without the answer, never switch provider on your own.
@@ -72,8 +70,6 @@ Ask it in these words, with the reason from the line's `cause` (`login`: "로그
> 2. 그록으로 만들기
> 3. 멈추기
-Then run the same command again with the answer's flag from the line's `choices` — 1: `choices.openai` (`--provider openai`; `video-set`: `--still-provider openai`), 2: `choices.grok` — or, for 3 (멈추기), stop and say nothing was generated. When the user says to do the same from now on, save it: `sprite-gen defaults save --codex-unavailable openai|grok|ask --expected-revision <revision from defaults show>`. A saved `grok` or `openai` runs without asking and says so on stderr and in the report (`provider_fallback`). The rule is [gen](docs/gen.md#when-codex-cannot-run--ask-or-what-you-chose)'s.
-
## Side-view facing
Keep the side still, canvas placement and motion prompt facing the same direction.
@@ -81,17 +77,6 @@ Keep the side still, canvas placement and motion prompt facing the same directio
`--facing` for both the canvas and clip prompt. Observation is record-only by default;
it never changes the requested direction. Image correction requires explicit opt-in.
-| Command option | Values and default | Behavior |
-|---|---|---|
-| `gen --facing` | `preserve` (default), `right`, `left` | With `--ref`, an explicit direction adds a prompt requirement and checks the generated still. |
-| `gen --facing-fix` | `none` (default), `mirror`, `regen` | Record without correction; opt into mirroring an observed opposite or regenerating once and rechecking. A still-opposite regeneration is mirrored. |
-| `video --direction` | `side`, `front`, `back`, `front_diagonal`, `back_diagonal`; unset by default | `side` opts into facing inspection and a matching prompt requirement; the others skip it. The two diagonals are three-quarter views turned right (`VIEW_TEXT`); a walk or run in one is filmed pinned (`pins_last_frame`). |
-| `video --facing`, `video-set --facing` | `right` (default), `left`; `video-set` also `right,left` | Required side direction. `right,left` films every side and diagonal view both ways, each from its own still (`--base side@left=…`); none is mirrored. |
-| `gen --direction`, `--handed`; `video-prompt` / `video-set --handed` | a view; `"<item>=<left\|right> [part]"` | An item on one of the character's own sides: the still and clip prompts say where it is in each view, and mirroring is refused. |
-| `video-prompt` / `video-set` / `gen --direction` / `prepare --body-plan` | `biped` (default), `quadruped`, `legless`; or `"<figure>=<plan>"` per figure of a scene | What the subject stands on: no clip, attack, redraw, still view or sheet row prompt names a part it lacks (a horse is not walked on a person's legs, stood up, given arms in a walk sheet or told to strike with its hands), and a scene says it per figure. |
-| `video --facing-fix`, `video-set --facing-fix` | `none` (default), `mirror` | Record the observation; opt into mirroring an observed opposite in a copy. Batch side inspection is enabled by default. |
-| `video-set --play`, `--motion`; `video-prompt --play`, `--motion` | `loop`, `once-return`, `once-hold`, `lifetime`; in `video-set` `"<state>=…"` or `"<item>=…"` | How a motion plays, and its own words: a word the engine does not name (`punch`, `type_at_desk`) is filmed in that mode; a once-return strip plays once and ends on its first pose (`loop: false`, `returns: true`). Without `--play` a named state plays as its preset ([play modes](docs/video-pipeline.md#play-modes)). |
-
Direction is requested through the generation and motion prompts, which cannot guarantee model compliance.
The detector can be wrong even at high confidence: review the still before choosing `mirror` or `regen`.
Generation reports record direction, model, requested direction, model-reported confidence and correction
@@ -99,13 +84,6 @@ under `extra.facing`; video reports and batch items use `facing`. `final_directi
or a value derived from it, not independent verification; `final_direction_source` identifies which.
An uncertain or failed inspection records `unknown` and its reason and continues without correction;
front-facing observations also remain unchanged. Mirroring does not preserve left/right accessory handedness.
-It stays the default, since drawing the left-facing views costs as much again; for a character with a watch on
-one wrist or a pin on one side, offer to draw them instead with `--handed` and check them with `handed-check`
-(a colour-marked item, frame by frame; `--board` for the eye) —
-[handedness](docs/video-pipeline.md#handedness--an-item-on-one-side). In a side view an item on the far wrist
-or hand shows each time that arm swings forward, never hidden for the whole walk: draw that side still mid-stride with
-the far arm out in front of the body and the item in view (`video-prompt` says so under `still_needs`), do not
-hold the arms still, and check the loop with `handed-check --state walk`.
## Execution routes
@@ -118,14 +96,14 @@ hold the arms still, and check the loop with `handed-check --state walk`.
| Grok video sprites | `video-set` | [video-pipeline](docs/video-pipeline.md) |
| A soft part of a walk loop sways with the body (the Sway layer; a chest, a belly): an ellipse in the first cell, after `video-cycle-align`, `--read-on <sha256>` where it was read on the cut the loop was aligned from; `--stretch-floor D` to keep a least area | `video-sway` (old name `video-follow`) | [video-pipeline](docs/video-pipeline.md#6-the-sway-layer--video-sway) |
| Where that ellipse is carried in every other cell, and what the move changes there (an arm crossing a chest moves with it; the stretch, the bend and the seam): a record and boards of every cell, nothing moved | `video-sway-inspect` (old name `video-follow-inspect`) | [video-pipeline](docs/video-pipeline.md#inspecting-a-sway--video-sway-inspect) |
-| A set's directions on one sheet, standing on one ground line (a 3×3 board, an engine import): rows in compass order S SW W NW N NE E SE from each loop's `--view`, one cell size, every row as cut, an optional centre picture (`--center`) at the rows' standing height; loops of different lengths are laid and said to differ (`same_length` false) — align the set first | `video-set-sheet` | [video-pipeline](docs/video-pipeline.md#7-one-sheet-for-a-set--video-set-sheet) |
-| A walk or run that stops, from the clip's own start played backwards: a one-shot strip (`loop: false`, `hold_last: true`), GIF, WebP and report beside the loop, ending on the still as filmed; leaves the loop from the cell nearest the entry (`from_cell`), drift taken out across the frames by a straight share; a seam past 1.4 steps (`--seam-max`), a run-up that comes back to a pose it left (another motion, however short) or one over 1.5 cycles (`--run-up-max`) refused; ghost screen checked, cells placed and anchored to match the loop's pivot | `video-stop` | [video-pipeline](docs/video-pipeline.md#8-a-walk-or-run-that-stops--video-stop) |
+| A set's directions on one sheet, standing on one ground line (a 3×3 board, an engine import) | `video-set-sheet` | [video-pipeline](docs/video-pipeline.md#7-one-sheet-for-a-set--video-set-sheet) |
+| A walk or run that stops, from the clip's own start played backwards | `video-stop` | [video-pipeline](docs/video-pipeline.md#8-a-walk-or-run-that-stops--video-stop) |
| Compare the currently displayed loop with a final candidate, including after follow-through | `video-loop-compare` | [loop-comparison](docs/loop-comparison.md) |
| Restore post-processing damage in the current cut from its exact source times, preserving normal cells and playback | `video-source-manifest` → `video-loop-repair` → `video-loop-compare` | [source restoration](docs/loop-comparison.md#restoring-the-active-cut-from-source) |
-| Video sprites from a clip your agent makes with a connected video MCP (ZCRE, 지크) | `video-canvas`, `video-prompt --no-last-frame`, the agent's own MCP tools (quote, user approval, generate, save the mp4), then `video-frames` and `video-loop` (a walk or run with `--anchor motion-auto`, which holds its size), and for a walk or run cut in two or more directions `video-cycle-align --view …` over their loop directories (a set it stops on a loop that may hold two cycles: look at that loop, count its strides, and pass `--cycles <loop>=<k>`; a loop the report lists under `unnamed_feet` — its view could not tell the feet apart, or only by too small a margin (`low-margin`): look at its first candidate frame, say which own foot lands there, and align again with `--foot <loop>=left|right`). `video-set` is not run on this route, so the set stage it runs by default (`--align-cycles auto`) is yours to run. sprite-gen never calls the MCP. Walk, run and jump only: ZCRE's `grok-imagine-video-1.5` has no end frame, so idle, attack and diagonal walks are refused unless `--unpinned` | [video-pipeline](docs/video-pipeline.md#a-clip-from-a-video-mcp-on-your-agent--zcre) |
+| Video sprites from a clip your agent makes with a connected video MCP (ZCRE, 지크) | `video-canvas`, `video-prompt --no-last-frame`, the agent's own MCP tools (quote, user approval, generate, save the mp4), then `video-frames` and `video-loop`, and for a walk or run cut in two or more directions `video-cycle-align --view …` over their loop directories. sprite-gen never calls the MCP. | [video-pipeline](docs/video-pipeline.md#a-clip-from-a-video-mcp-on-your-agent--zcre) |
| Typography logo, wordmark or title lettering (로고, 타이포그래피, 타이틀 글자): the title lettered into a title screen or poster first, then only its lettering redrawn on a key and cut out with its glow; the text is read back and a misspelt logo refused | `logo --text … --style …` (`--mood` to start from a picture you have, `--lettering` to cut again for nothing) | [logo](docs/logo.md) |
| Ordinary image or edit | `gen --provider codex` or `gen --provider grok` (the subscription login first; without one grok uses `XAI_API_KEY`, and a codex signed in with an API key bills it — both per call, said on stderr) | [gen](docs/gen.md) |
-| Pixel art the model draws directly as a grid, 8–48 px (best at 32 or less): an icon, a prop, a monster, a character still, four directions, a walk draft, a tile, or a hand-drawn motion of up to 64 frames drawn four a call (`--motion`, `{name, pose}` frames, `--duration-ms`), in a style of your own (`--style`) — on your Claude subscription (`claude` signed in), or without one on `ANTHROPIC_API_KEY`, **billed per call**; `grid.txt` is the truth, `--grid` re-renders an edited one, `--resume` collects a batch instead of buying it twice | `pixel-draw` | [pixel-draw](docs/pixel-draw.md) |
+| Pixel art the model draws directly as a grid, 8–48 px, on your Claude subscription (`claude` signed in), or without one on `ANTHROPIC_API_KEY`, **billed per call** | `pixel-draw` | [pixel-draw](docs/pixel-draw.md) |
| Image generation with no login available (server, container, SaaS) | `gen --provider openai` — server/SaaS route on `OPENAI_API_KEY`, **billed per call**, never a default; it runs only when named, or when the user chose it for a codex that cannot run | [gen](docs/gen.md#subscription-first--openai-runs-only-when-you-chose-it) |
| Base and direction anchors | `anchor` | [directional-anchor-workflow](docs/directional-anchor-workflow.md) |
| Curation view or existing image candidates | `curation`, `unpack-atlas --pngs-dir` | [curation](docs/curation.md) |
@@ -144,13 +122,11 @@ hold the arms still, and check the loop with `handed-check --state walk`.
| Optional scene placement, lighting, camera and render | `scene-render`, `scene-inspect` | [scene](docs/scene.md) |
| Defaults | `defaults show`, `defaults save` (`--codex-unavailable ask\|grok\|openai`: what to do when codex cannot run), `defaults clear` | [user-workflow](docs/user-workflow.md#one-settings-owner) |
-Say a thing once: what an option says, leave out of the prompt. `--direction`, `--facing`, `--handed`, the key background and `video --direction side` each add their own sentence after your text, in one place; without `--handed` every prompt is 2.22.0's, byte for byte, and only the handed sentences are left out where your text already has them. Your prompt carries the subject, its design and its pose. Text that says the opposite of an option ("facing left" with `--facing right`, the item on the other wrist) is sent as written with a warning (`extra.prompt_notes`, `video-prompt`'s `warnings`): fix the prompt, do not send it — [prompt-assembly](docs/prompt-assembly.md).
-
-`gen --transparent` with `--ref` plans a chroma key (adding the key's background line to a prompt that names none), and publishes a result that already came back transparent on its own alpha instead of keying its outline away; `alpha.strategy_source` in the report says which (`refs-attached` keyed, `refs-attached-raw-alpha` not). A key background painted as a transparency checkerboard is refused before keying (`chroma: the background is a painted transparency checkerboard …`): generate again — [gen](docs/gen.md#transparent-output--strategy-per-provider).
+Say a thing once: what an option says, leave out of the prompt. `--direction`, `--facing`, `--handed`, the key background and `video --direction side` each add their own sentence after your text, in one place. Your prompt carries the subject, its design and its pose. Text that says the opposite of an option ("facing left" with `--facing right`, the item on the other wrist) is sent as written with a warning (`extra.prompt_notes`, `video-prompt`'s `warnings`): fix the prompt, do not send it — [prompt-assembly](docs/prompt-assembly.md).
Use existing automatic pipeline stages for background removal, extraction, alignment and export. Do not ask users to select each script. For a direct utility request, run that utility; no unrelated generation questions are needed. Preserve the row pipeline and component extraction for image sprites. One-shot grid generation and fixed cell cutting are not an alternative sprite-generation route.
-For attack repeat coverage, observed one-shot returns and structured loop failure reports, follow [video-pipeline](docs/video-pipeline.md#one-shot-actions--cycle-autoperiodicone-shot).
+For attack repeat coverage, observed one-shot returns and structured loop failure reports, follow [video-pipeline](docs/video-pipeline.md#one-shot-actions----cycle-autoperiodicone-shot).
A pinned idle or attack whose last frame the video model drew again has its wrap blended by default (`video-loop --wrap-blend auto`, a redraw only; `off` cuts as filmed), with details in [loop repair](docs/loop-repair.md#6-the-redrawn-wrap-a-pinned-clip-whose-last-frame-the-model-drew-again).
@@ -162,8 +138,8 @@ Scene creation consumes finished assets and remains optional. Asset metadata own
## RIFE for walk and run loops
-`video-loop` repairs a walk's or run's jump frames, reads a part that rushes on its way at the wrap and eases it only where the rest of the body keeps its own beat (a frame made is the whole picture, so the legs take the part's time: such a loop keeps the flow repair), closes a two-step cut's wrap that a part on its own beat leaves open with the clip's frames a cycle apart (`--overlap-wrap off` turns that alone off where RIFE runs on a CPU; the gate then refuses the cut as filmed), bridges a jumping wrap on any other loop with one, two, or four frames made round the seam, and gives its filmed ghosts way (a half-drawn frame the video model left, `ghost_given_way`), and `video-set` gives a direction set one cycle length, both with RIFE in-betweens. Install it once per machine: `$SPRITE_GEN_ROOT/.venv/bin/sprite-gen rife install` (pinned rife-ncnn-vulkan 20221029 and model rife-v4.6, SHA-256 checked, into the user data directory, ending with a check frame; Linux without a GPU first needs `libvulkan1 mesa-vulkan-drivers`). Every call runs the binary's test-time augmentation `-x -z`; on a CPU it costs 15 to 19 times a plain call, so a CPU-only machine aligning a set may set `SPRITE_GEN_RIFE_TTA=` (none) or `-z`. Without it every loop is still cut — a jump or a rush as filmed, each filmed ghost given way to the clean frame beside it — and what was left unrepaired says so: a `warning:` line on stderr and `jump_repair.rife` with `jump_repair.unmade` (the jump left as filmed) or `jump_repair.ease_skipped` (the rush) in the loop report (`applied` alone is not the sign: a ghost given way reads true), `cycle_align.<state>.applied: false` and `warnings` in `set.report.json`. When that happens, tell the user which loops went unrepaired and offer the install; after it, cut those loops again and run `video-cycle-align`. `video-loop --repair on` and `video-cycle-align` fail without RIFE instead. [loop-repair](docs/loop-repair.md).
+Without RIFE, tell the user which loops went unrepaired and offer the install; after it, cut those loops again and run `video-cycle-align`. [loop-repair](docs/loop-repair.md).
## Contracts and advanced tools
-[run-contract](docs/run-contract.md) owns numeric requests, run layout, atomic publication and curated exports. [architecture](docs/architecture.md) explains domain ownership. [docs index](docs/README.md) lists every specialized feature and QA procedure. `sprite-gen --help` derives the command map from the package catalog. Never replace an engine stage — extraction, the loop cut, set alignment, loop repair — with a script of your own while presenting the result as a pipeline output. Where a stage's result is wrong, use the engine's own options first (another cut with `video-loop --max-len` or `--cycle fixed`, `video-cycle-align --length`, `--between auto` (the default: a made frame that melted or carries a ghost takes the nearer source frame, and a filmed ghost frame a clean one beside it; a made frame the report names as a possible cross-fade of two drawings, `look`, is kept — look at it, and where the legs show twice use `--between nearest` or film that direction again) or `--between nearest`, or `--cycles <loop>=<k>` once you have counted a suspect loop's strides, or `--foot <loop>=left|right` (`video-set --align-foot <item>=…`) once you have looked at the first strike frame of a loop the report lists under `unnamed_feet`), keep the engine's result as the comparison, report the defect against the engine, and name in the delivery each stage done by hand and why. A new clip is for what no stage can reach: the drawing, the motion itself, a clip that holds no whole cycle ([loop-review](docs/loop-review.md)) — and a clip the engine names for one: when the alignment report's `retake` lists a loop (reason `held-drawings`: the cycle cut from its clip shows each drawing for two or three frames, the set's length leaves it at under 13 drawings a second, and frames between its drawings could not be made, so the loop halts there; or `filmed-ghost`: a filmed ghost frame has filmed ghosts on both sides, so no clean frame stands there and the loop shows it — `reasons` lists both where both apply), run the engine verbs first as above, then film that direction again and align the set anew rather than hand-painting the gap; tell the user what the reason was and that a new take usually fixes it ([loop-repair](docs/loop-repair.md) section 4). `video-loop --anchor motion-auto` already cuts a walk two steps long — one cycle — where a staff held above the head closes only there (`cycle.steps`, `strip.json` `steps: 2`; `video-cycle-align` aligns it as the one cycle it is). Where the clip shows its feet pass, it counts the steps on those crossings and cuts two of them, joined at the walk's own point (`cycle.step_count`, `steps: 2`, [loop-repair](docs/loop-repair.md) section 3, "The step count"). When its report's `cycle.step_screen` says `suspect` (a slow walk cut one step long, its feet not read), or `video-cycle-align` stops on a loop under `one_step`, count the steps in the loop (how often each foot lands) and cut it again with `video-loop --steps 1` if it is one step (`--steps 2` if it is two); never stretch or double it by hand. When `video-loop` warns that the top of the silhouette jumps into the loop's first frame (a staff or flag held above the head, swinging on its own beat), or that the held part does not close at the wrap below its top, that part does not close at the cut: look at the loop, and try `--cycle fixed` with another cut before filming again; a walk refused for no cycle names in its report's `cycle.candidates` the windows it measured, best first, for a cut you must deliver anyway ([loop-repair](docs/loop-repair.md) section 3, "The seam pop" and "The held side").
+[run-contract](docs/run-contract.md) owns numeric requests, run layout, atomic publication and curated exports. [architecture](docs/architecture.md) explains domain ownership. [docs index](docs/README.md) lists every specialized feature and QA procedure. `sprite-gen --help` derives the command map from the package catalog. Never replace an engine stage — extraction, the loop cut, set alignment, loop repair — with a script of your own while presenting the result as a pipeline output. Where a stage's result is wrong, use the engine's own options first, keep the engine's result as the comparison, report the defect against the engine, and name in the delivery each stage done by hand and why. A new clip is for what no stage can reach: the drawing, the motion itself, a clip that holds no whole cycle ([loop-review](docs/loop-review.md)) — and a clip the engine names for one: when the alignment report's `retake` lists a loop (reason `held-drawings`: the cycle cut from its clip shows each drawing for two or three frames, the set's length leaves it at under 13 drawings a second, and frames between its drawings could not be made, so the loop halts there; or `filmed-ghost`: a filmed ghost frame has filmed ghosts on both sides, so no clean frame stands there and the loop shows it — `reasons` lists both where both apply), run the engine verbs first as above, then film that direction again and align the set anew rather than hand-painting the gap; tell the user what the reason was and that a new take usually fixes it ([loop-repair](docs/loop-repair.md) section 4).
diff --git a/docs/atlas-workflow.md b/docs/atlas-workflow.md
index 4c3a071..d878e8d 100644
--- a/docs/atlas-workflow.md
+++ b/docs/atlas-workflow.md
@@ -12,7 +12,7 @@ Use one accepted, uncropped, full-body idle image with the intended proportions,
2. **Generate rows.** Use `gen-set --provider codex` for the GPT image-sprite route. The provider that made the base is an independent choice. Attach the resolved identity reference and that state's generated layout guide. Extra motion references must be recorded in `qa-notes.md`. Independent rows use the existing batch concurrency; [gen](gen.md) owns its execution and reports.
3. **Extract.** Run the canonical extractor for every raw row. It removes chroma, separates characters, applies the requested pixel processing and places transparent frames. Never replace this with equal-width cuts or a one-line resize for a preview. A character crossing an imaginary slot can still be extracted intact when the poses are separable. Actual missing/occluded pixels are not restored by cropping. Choose sufficient output dimensions to preserve the desired scale; [pixel-unfake](pixel-unfake.md) owns fit options.
4. **Compose and verify.** Produce the atlas, runtime manifest and animation preview with existing compose tools. Inspect the frame manifest and output reports; reject empty frames, unwanted edge/chroma remnants and identity defects. Review motion as motion using [qa-motion](qa-motion.md). Do not hide failed motion by timing changes or silently replacing poses. A user's explicit slow preview request changes display speed, not the QA verdict.
-5. **Deliver.** Send the checked files, then follow the finish stage in the user workflow. Curation display is optional. After curation edits, exports come from the curated result, not the unedited frame cache.
+5. **Deliver.** Send the checked files, then follow the finish stage in the user workflow.
```bash
$SPRITE_GEN_ROOT/.venv/bin/sprite-gen prepare --out-dir /absolute/run \
@@ -24,4 +24,4 @@ $SPRITE_GEN_ROOT/.venv/bin/sprite-gen compose-gif --run-dir /absolute/run --out-
$SPRITE_GEN_ROOT/.venv/bin/sprite-gen inspect --run-dir /absolute/run
```
-The runtime consumes `manifest.json.frame_layout`; it does not infer a grid from alpha. AI operates only at generation. Frame cleanup and atlas assembly remain deterministic, with one writer per run and atomic publication. [architecture](architecture.md) explains these boundaries. [subject-profiles](subject-profiles.md) covers effects and sparse subjects. [breathing](breathing.md), [recolor](recolor.md) and [layer-tracks](layer-tracks.md) own optional post-processing; none is an extra default question for every sprite request.
+The runtime consumes `manifest.json.frame_layout`; it does not infer a grid from alpha. AI operates only at generation. Frame cleanup and atlas assembly remain deterministic. [architecture](architecture.md) explains these boundaries. [subject-profiles](subject-profiles.md) covers effects and sparse subjects. [breathing](breathing.md), [recolor](recolor.md) and [layer-tracks](layer-tracks.md) own optional post-processing; none is an extra default question for every sprite request.
diff --git a/docs/curation.md b/docs/curation.md
index 3f768fd..8dc27ec 100644
--- a/docs/curation.md
+++ b/docs/curation.md
@@ -2,48 +2,6 @@
> Owns: The webview, standalone candidate view, finished-sheet editing and every `curation.json` field · Index: [docs/README.md](README.md)
-## Contents
-
-- [The webview in one screen (from the README, 2026-09-09)](#the-webview-in-one-screen-from-the-readme-2026-09-09)
- - [Isometric ground grid](#isometric-ground-grid)
- - [Languages](#languages)
-- [Standalone Curation View (이미지 후보 큐레이션 — 스프라이트 아님)](#standalone-curation-view-이미지-후보-큐레이션-스프라이트-아님)
-- [Curation Webview](#curation-webview)
- - [Colourway (recolor) compare and pick](#colourway-recolor-compare-and-pick)
- - [생성 트리거 관용구 (SSoT = `src/gen-trigger.js`)](#생성-트리거-관용구-ssot-srcgen-triggerjs)
-- [Editing a finished sprite sheet (no `frames/` source)](#editing-a-finished-sprite-sheet-no-frames-source)
-- [Multi-agent rules for the auto-launch (클로징 스텝 5)](#multi-agent-rules-for-the-auto-launch-클로징-스텝-5)
-- [Curation Sidecar (`curation.json`)](#curation-sidecar-curationjson)
-- [Related](#related)
-- [Base editing (same component as frames)](#base-editing-same-component-as-frames)
-
-## The webview in one screen (from the README, 2026-09-09)
-
-Generation gets you 90%. The webview is where a human takes it to *shipped* — standalone, no Studio or framework dependency, runs anywhere the skill is installed (Claude Code Desktop, the Codex app, a plain terminal).
-
-![curation webview — characters](assets/demo-character.gif)
-
-- **Two rows per state:** the **play sequence** on top and a **candidate pool** below (e.g. a second or third generated take). Drag a frame's ⠿ grip to reorder the sequence, or pull a cut up from the pool — rebuild one clean run loop from the best frames across takes. The arrangement is saved, so reopening restores it.
-- **Non-destructive transform** per frame: drag = move, wheel = scale, top handle = rotate, bottom-left = shear, plus a horizontal-flip toggle for left-right-reversed output. Edits live in a `curation.json` sidecar — source PNGs are never rewritten, and the compose step bakes the result deterministically. Preview and bake share one affine matrix, so what you align is what you get.
-- **Live preview** animates the sequence at the state's fps, with play/pause, frame-by-frame stepping, and a 0.25×–4× speed control.
-- Not just for sprites: point it at any folder of image candidates (icons, logos, generated drafts) with `unpack_atlas_run.py --pngs-dir` and use it as a general pick-the-winner view.
-
-### Isometric ground grid
-
-For isometric sets, the webview overlays the floor grid (from `meta.json` tile/anchor) so you can snap furniture to the diamond axes with the shear handle.
-
-![curation webview — isometric furniture](assets/demo-furniture.gif)
-
-<img src="assets/curator-iso.png" width="520" alt="isometric ground grid overlay" />
-
-### Languages
-
-The webview ships with English and Korean. Pass `--lang en|ko` when launching, or use the in-app toggle:
-
-```bash
-python3 sprite-gen curation --run-dir <run-dir> --lang en # or ko
-```
-
> 큐레이션뷰의 실행과 데이터 계약. 생성 완료 후 열기 선택과 저장된 기본값은 [user-workflow](user-workflow.md)가 소유한다.
## Standalone Curation View (이미지 후보 큐레이션 — 스프라이트 아님)
@@ -69,21 +27,17 @@ PORT=$(lsof -nP -a -p $! -iTCP -sTCP:LISTEN | awk 'END{sub(".*:","",$9); print $
curl -s -o /dev/null -w "%{http_code}" "http://127.0.0.1:$PORT/" # 200 = positive proof, 그 후 URL 보고
```
-- **캐릭터/스프라이트 세트 표시 기본지침 = "실제 사용하는 컷"** (maintainer 확정 2026-07-12 — "대표컷"
- 아님). 줄(state)은 `base`, `anchor-idle-down`, `idle`, `walk` … 처럼 개념 단위로 만들고, 각 줄의
+- **캐릭터/스프라이트 세트 표시 기본지침 = "실제 사용하는 컷"**. 줄(state)은 `base`, `anchor-idle-down`, `idle`, `walk` … 처럼 개념 단위로 만들고, 각 줄의
내용은 그 개념의 **실물**이다: base·방향 앵커처럼 실물이 1장이면 그 1장, 런타임 상태면 매니페스트가
실제 재생하는 프레임들을 재생 순서대로 **전부**. 임의 대표컷 발췌(예: `frame-0` 한 장만) 금지 —
게임이 행 전체를 돌리는데 한 장만 보여주면 검수 대상이 왜곡된다. 아틀라스 시트 통짜·raw
멀티프레임 row 이미지·비교용 합성 시트를 그대로 붓는 것도 금지 (셀 크기 폭발 + 선택 단위 흐림).
- 파이프라인 산출물 검수는 이 standalone 경로가 아니라 run dir 를 직접 서빙하는 파이프라인
- 큐레이션(아래 Curation Webview)이 우선이다.
-- 사용자 로컬이면 브라우저 자동 오픈이 기본, headless/원격이면 `--no-open` + URL 전달.
- 선택 회수는 `"$STAGE/run/curation.json"` 의 `selected` 인덱스를 파일명으로 역매핑. 비어 있으면 다시 묻는다 — 추측 진행 금지.
- 큐레이션을 열기로 선택했다면 이미지가 한 장이어도 이 뷰에서 확인할 수 있다. 필요한 편집 결과를 내보낸 뒤 이 작업이 시작한 서버를 종료하고 임시 `$STAGE`를 정리한다.
## Curation Webview
-**캐릭터/스프라이트 검수의 정식 뷰 = run dir 를 직접 서빙하는 이 파이프라인 뷰다** (maintainer 채택 2026-07-12).
+**캐릭터/스프라이트 검수의 정식 뷰 = run dir 를 직접 서빙하는 이 파이프라인 뷰다**.
이 뷰의 네 표시 요소(베이스 참조 줄 · 생성 재료 ref 칩 · 픽셀 격자 · 원본 화질 토글)와 그것을
채우는 `/api/run` payload 는 [`run-contract.md`](run-contract.md) §3 이 계약으로 소유한다 — 어떤
에이전트가 뷰를 차려도 같은 경험이 나오도록 스크립트가 강제한다. 아래는 그 뷰의 상호작용(선택/재배열/
@@ -94,72 +48,18 @@ $SPRITE_GEN_ROOT/.venv/bin/sprite-gen curation \
--run-dir <target>/assets/generated/sprites/<character-id>
```
-**세 진입 형식이 전부 살아 있다** — 위 콘솔 스크립트, 모듈 형식, 그리고 파일 이름을 이미 쓰고
-있는 호출자를 위한 래퍼:
-
-```bash
-$SPRITE_GEN_ROOT/.venv/bin/python -m sprite_gen.serve.serve_curation --run-dir <run-dir>
-$SPRITE_GEN_ROOT/.venv/bin/python $SPRITE_GEN_ROOT/scripts/serve_curation.py --run-dir <run-dir>
-```
-
-셋은 인자 선언 하나(`add_arguments`)와 구현 하나(`run`)를 공유하므로 플래그도 기본값도 갈릴 수
-없다 (`tests/test_curation_cli_entrypoint.py`). 콘솔 스크립트를 먼저 쓰는 이유는 기능이 아니라
-인터프리터다 — shebang 이 자기 venv 를 가리켜서 고를 것이 없다. 이 변경 이전에 만든 venv 에는
-`bin/sprite-gen` 이 없으니 `pip install -e .` 를 한 번 다시 돌리거나 위 두 형식을 쓴다.
-
-This launches a standalone local webview (no orchestrator dependency — usable from Claude Code Desktop, the Codex app, or any host with the skill installed). It shows every state's frames side by side so you can compare them in parallel. Two rows per state: a **sequence** row (the selected play order, saved to `curation.json.selected`, baked left-to-right by compose) and a **candidate pool** row below it (unselected frames, e.g. an extra generated take). A per-frame transform (drag the stage = move, bottom-right magnifier = scale, top handle = rotate, side handle = shear) corrects an off angle/position. A live preview animates the selected frames at the state fps, with play/pause, frame stepping, and a 0.25×–4× speed control.
+This launches a standalone local webview (no orchestrator dependency — usable from Claude Code Desktop, the Codex app, or any host with the skill installed). It shows every state's frames side by side so you can compare them in parallel. Two rows per state: a **sequence** row (the selected play order, saved to `curation.json.selected`, baked left-to-right by compose) and a **candidate pool** row below it (unselected frames, e.g. an extra generated take). A per-frame transform corrects an off angle/position. A live preview animates the selected frames at the state fps, with play/pause, frame stepping, and a 0.25×–4× speed control.
### Colourway (recolor) compare and pick
When the run has a bake under `variants/` (`recolor.report.json` present), the view
-adds a colourway section above the state rows (`curator/src/recolor.js`):
-
-- **Blink comparison** — one stacked stage holds every variant sheet; hovering a
- list row swaps the visible sheet in place. Side-by-side eye travel loses small
- palette shifts; blink does not.
-- **Frame-cell thumbnails** — one cell cropped from the sheet via
- `manifest.frame_layout` (first frame of the first state). Origin assumptions
- are forbidden; no layout → no crop style.
-- **Adopt** writes `curation.json.recolor.picked` as the variant **name**. A name
- the current bake no longer produces is kept and flagged (`pickedKnown: false`),
- never silently cleared. A save from a run without a recolor section does not
- author the field; the server carries the existing pick over (same carry
- contract as `anchors`).
+adds a colourway section above the state rows (`curator/src/recolor.js`).
Bake the colourways first with `sprite-gen recolor` — command, spec, and report
schema: [`recolor.md`](recolor.md).
-**Card interaction model** (maintainer 2026-07-15 — a stray click must never add/remove a frame):
-
-- **Move between rows / reorder = grab the card TITLE and drag** (the whole header strip is the handle; there is no separate ⠿ grip). A plain click on the card does nothing.
-- **넣기/빼기 (add/remove) button** in the card footer is the only click-toggle between sequence ⇄ pool (up arrow = add to sequence, down arrow = remove to pool). No color emphasis — direction icon only.
-- **Duplicate = the ⧉ button in the card header.** A clone is a full instance (own transform/pixels/order slot) that bakes the source frame's image; its footer archive button deletes the clone. See the `clones` field below.
-- **Card layout**: header = title (drag handle) + duplicate/zoom icons; footer tier 1 = size + transform readout (info); footer tier 2 = flip/reset + 넣기·빼기/archive. Hovering the title shows the full frame name in a **custom `data-tip` tooltip** (not native `title=`) whose text is selectable/copyable — so a collaborating agent can lift the exact frame path.
-
The webview UI is bilingual (English / Korean). Pass `--lang en|ko` to match the user's language (it is also toggleable in the app); default is `en`. For isometric sets imported with `--pngs-dir`, a sibling `meta.json` tile/anchor adds a ground-grid overlay for aligning furniture with the shear handle.
-All edits are **non-destructive**: they are saved to `curation.json` in the run dir, and the original `frames/<state>/frame-N.png` files are never rewritten. The compose step bakes `curation.json` deterministically, so any curation decision is reversible by editing or deleting that file.
-
-**실시간 계약 (maintainer 확정 2026-07-14/15)** — 뷰에는 '재추출' 개념이 없다. 뷰가 보여주는 것은
-항상 (raw + request + 현재 엔진 + 큐레이션)의 실시간 결과다: `/api/run`·`/api/progress` 가
-요청마다 stale 프레임 캐시를 자가치유(heal)하고, 엔진이 바뀌면 열려 있는 페이지도 다음 폴에서
-자동 재계산·리로드된다 (자세한 캐시 키 계약은 run-contract.md §2 frames-manifest 절).
-상단 버튼 3종(**아틀라스/PNG/GIF 다운로드**, `GET /download/{atlas,pngs,gifs}`)은 '게임에 적용'이
-아니라 지금 보이는 라이브 상태를 그 자리에서 계산해 zip 으로 내려주는 **다운로드**다 — 계산
-산출물은 런 폴더에도 남는다 (런 폴더 = 작업장, 다운로드 = 핸드오프).
-
-This step is optional. When there is no `curation.json`, every state uses all extracted frames in order with identity transform — an explicit default, not a silent fallback.
-
-### 생성 트리거 관용구 (SSoT = `src/gen-trigger.js`)
-
-서버에서 생성이 도는 모든 버튼(보간 `tween.js`, 리롤 `row-controls.js`, 이후 추가되는 것)은
-한 가지 표면 계약만 쓴다 — **클릭 = 파라미터 팝오버(`.gen-pop`) 토글 → 공용 모델
-select(GPT=codex / Grok=grok, `makeProviderSelect`) → 생성 버튼 → `runServerGeneration`**
-(스피너 → 진행도 워치 → POST → 에러 언랩 → 성공 시 뷰 새로고침). 모델 표기·실행 시퀀스의
-유일한 소유자는 `gen-trigger.js` 다. 트리거마다 다른 제스처(Alt클릭 모델 선택 등)를 만들지
-않는다 (maintainer 2026-07-19 통일 확정 — 회귀: 보간=팝오버 select, 리롤=Alt클릭으로 갈라져
-있었다). 줄 단위 다운로드(저장 팝오버)는 생성이 아니므로 별도 파일 `row-export.js` 소유.
-
## Editing a finished sprite sheet (no `frames/` source)
When only the combined sheet survives (a deployed asset whose run dir is gone), rebuild a curator-ready run dir with the inverse step before curating:
@@ -178,13 +78,12 @@ $SPRITE_GEN_ROOT/.venv/bin/python $SPRITE_GEN_ROOT/scripts/unpack_atlas_run.py \
The chosen layout source is always reported (`manifest` / `grid-explicit` / `auto-detect`) and stored in `unpack-source.json` for a later writeback. Then point `sprite-gen curation` at the new run dir. Auto-detect is the no-instruction default; `--grid` and `--manifest` are position-faithful (they crop full cells), while auto-detect crops each blob's content bbox and centers it in the cell.
-## Multi-agent rules for the auto-launch (클로징 스텝 5)
+## Multi-agent rules for the auto-launch
- The server picks a free port per launch (`--port 0` default) and serves exactly one run dir, so several agents curating different characters can each keep a webview open with no port or state conflicts.
- One curator webview per run dir. Two webviews on the same run dir are last-write-wins on `curation.json`; if one is already serving that run dir, reuse its URL instead of launching another.
- Pipeline writes are guarded by a run-dir lock (`.sprite-gen.lock`): extract/compose/export/unpack fail loudly when another sprite-gen process is writing the same run dir. Treat that error as "wait or pick another run dir", not as a retry-until-success loop.
- In a headless/remote session add `--no-open` and give the user the URL; on the user's own machine the default auto-opens their browser.
-- Skip the auto-launch only when the user explicitly asked for an unattended batch run.
## Curation Sidecar (`curation.json`)
@@ -221,26 +120,15 @@ The chosen layout source is always reported (`manifest` / `grid-explicit` / `aut
- `states.<state>.revision` — 행 단위 세대 스탬프 (`curation.state_revision`): 그 행의 프레임
인덱스 공간을 만드는 **원료** 세그먼트(primary raw + 선언 순서의 take raw; raw 없는 임포트
행은 프레임 파일 내용) 다이제스트의 순서 리스트. frames/ 캐시의 mtime 과 엔진 리비전은
- 입력이 아니다. top-level `run_revision` 이 어긋나면(재추출·heal·재임포트) 행별 구제로
- 넘어간다: 저장된 리스트가 현재 리스트의 **접두(prefix)** 인 행만 유지(테이크 append 는
- 인덱스 공간을 밀지 않으므로 유효), 나머지 행과 스탬프 없는 레거시 행은 드롭. 드롭은
- stderr + 웹뷰 배너(`/api/run` 의 `curationDropped`)로 보고된다. **로드는 아무것도 쓰지
- 않는다** — 드롭은 "이번 로드가 무엇을 적용하지 않는가" 이지 파일 삭제가 아니고,
- `curation.json` 은 디스크에 그대로 남는다. 원문이 실제로 덮이는 순간(`write_curation_atomic`)
- 에만 `curation.stale-<hash>.json` 백업이 난다(내용 해시 파일명, 멱등). 같은 raw 의 엔진
- 업그레이드 재유도에는 선택이 살아남고, raw 리롤은 그 행만 리셋되며, 무엇도 조용히
- 소실되지 않는다. 다이제스트의 기하 세그먼트는 셀 크기 + `pixel_unfake` +
- **파생 격자 배율**(`pixel_snap_scale`)이다 — `fit.logical_height` 선언값 자체가 아니다.
- 출력이 한 픽셀도 안 바뀌는 선언 편집(무효값 제거 등)이 전 행을 무효화하지 않게 하기 위해서다
- (회귀 hero synthetic_fixture_b 2026-07-25, 계약 = `tests/test_logical_height_contract.py`).
+ 입력이 아니다.
- `clones` — 프레임 복제 인스턴스 맵 `{복제 인덱스: 원본 프레임 인덱스}` (웹뷰 카드의 ⧉
버튼). 복제 인덱스는 물리 범위(0..N-1) 밖의 정수이고 `selected`/`order`/`transforms`/
`pixels` 에 자기 인덱스로 참여하는 정식 인스턴스다 — 자기만의 변형/픽셀편집/순서를 갖고,
compose/export/GIF 는 파일만 원본 프레임(`source_frame_index`)에서 읽는다. `frames/` 는
파생 캐시이므로 복제 파일을 만들지 않는다(복제 의도는 사이드카 소유). 웹뷰에서 복제
카드의 보관 버튼은 보관함이 아니라 인스턴스 삭제다.
-- `pixel_unfake` — **두 층위**. top-level = 런 전체 기본값(웹뷰 우측 상단 "전체 토글" — 모든 줄을 한번에 설정; 줄별 값이 섞이면 웹뷰는 이 필드를 생략한다). `states.<state>.pixel_unfake` = 줄별 override(각 줄 헤더의 토글). 해석 순서는 `curation.frame_variant(curation, state)` 가 SSoT: 줄별 값 > top-level > 기본 `true`. `false` 인 줄은 compose/export/GIF 가 적용 전 쌍둥이(`frame-N.plain.png`)를 굽고, 없거나 `true` 인 줄은 canonical `frame-N.png`. plain 쌍둥이가 없는 런에서는 **굽기에** 무의미(플래그와 무관하게 canonical 을 굽는다) — 웹뷰의 이런 줄 퍼펙 토글은 **표시 렌즈**다: 표시 렌더러가 측정 격자 `pixelScale`(격자 오버레이와 같은 k)로 재양자화해 보여줄 뿐, sidecar 로 저장되지 않고 **파이썬 파이프라인 굽기**(compose/export_pngs/compose_gif — 사이드카만 읽는다)에 영향이 없다. 단 **웹뷰 줄 GIF/WebM/MP4**(`row-export.js`)는 화면 그대로(WYSIWYG) 굽므로 토글 상태가 반영된다 (구 서버 `.pixel-preview` 온디맨드 스냅은 표시 격자와 다른 검출기로 스냅해 폐기, v1.56.91). manifest 는 줄별 `animation.rows.<state>.frame_variant` 와 top-level 요약(`pixel`/`plain`/`mixed`)을 기록한다. 상세는 [`pixel-unfake.md`](pixel-unfake.md).
-- `anchors` — 방향 앵커 **프레임 지정** `{<direction>: {state, index}}` (maintainer 2026-07-25). 그
+- `pixel_unfake` — **두 층위**. top-level = 런 전체 기본값(웹뷰 우측 상단 "전체 토글" — 모든 줄을 한번에 설정; 줄별 값이 섞이면 웹뷰는 이 필드를 생략한다). `states.<state>.pixel_unfake` = 줄별 override(각 줄 헤더의 토글). 해석 순서는 `curation.frame_variant(curation, state)` 가 SSoT: 줄별 값 > top-level > 기본 `true`. `false` 인 줄은 compose/export/GIF 가 적용 전 쌍둥이(`frame-N.plain.png`)를 굽고, 없거나 `true` 인 줄은 canonical `frame-N.png`. plain 쌍둥이가 없는 런에서는 **굽기에** 무의미(플래그와 무관하게 canonical 을 굽는다). manifest 는 줄별 `animation.rows.<state>.frame_variant` 와 top-level 요약(`pixel`/`plain`/`mixed`)을 기록한다. 상세는 [`pixel-unfake.md`](pixel-unfake.md).
+- `anchors` — 방향 앵커 **프레임 지정** `{<direction>: {state, index}}`. 그
방향의 다른 행을 생성할 때 identity 로 붙는 인스턴스 하나다 — 카드의 앵커(핀) 버튼(또는
`sprite-gen anchor --pick <state>#<index>`)이 쓰고, 지정이 없는 방향은 **앵커 행
(`<dir>_<anchor_suffix>`)의 시퀀스 첫 인스턴스**가 앵커다(index 0 이 아니다 — 삭제/재정렬을
@@ -250,21 +138,14 @@ The chosen layout source is always reported (`manifest` / `grid-explicit` / `aut
되므로 조용히 따라가지 않고, 지정을 지워 기본값으로 되돌리지도 않는다. 그 상태의 생성은
`pick-stale-generation` 으로 fail-loud 하고 뷰가 이유를 띄운다(재지정 한 번으로 풀린다).
전 행이 드롭돼도 지정은 남는다 — 남아 있어야 오류를 낼 수 있다.
- 해석·베이크 SSoT 는 `sprite_gen/curate/anchor.py`, 생성에 붙는 파일은 그 함수가 매번 다시 굽는
- 파생 캐시 `references/anchors/<dir>-anchor-x8.png` 이고, 뷰의 앵커 칩은 낡을 수 없게
- `GET /api/anchor?direction=<dir>` 라이브 베이크를 본다. 사라진 인스턴스를 가리키는 지정은
- 생성 시 fail-loud (조용한 기본값 복귀 금지) — 뷰는 로드 시 그 이유를 상태줄에 띄운다.
+ 해석·베이크 SSoT 는 `sprite_gen/curate/anchor.py`.
- `recolor` — optional adopted colourway `{ "picked": "<variant-name>" }`. Written by the
curation view's colourway Adopt button after `sprite-gen recolor` has baked sheets into
- `<run-dir>/variants/`. Keyed by **name** (a colour decision, not a frame generation), so
- re-baking does not stamp it stale the way anchors do. A name the current bake no longer
- produces is kept and reported as `pickedKnown: false` — never silently cleared. A save
- that does not author this field carries the existing value over (same contract as
- `anchors`). Reader: `curation.recolor_pick()`. Full bake + view contract:
+ `<run-dir>/variants/`. Reader: `curation.recolor_pick()`. Full bake + view contract:
[`recolor.md`](recolor.md).
- `selected` — 0-based frame indices in play order. Absent/empty → all extracted frames in order.
- `order` — optional, webview-owned: the full display order (sequence row then candidate-pool row) so reopening the curator restores the exact arrangement of both rows. `compose` / `state_plan` ignore it and key off `selected`.
-- `transforms` — keyed by 0-based frame index. `rotate` degrees (counter-clockwise positive, PIL convention), `scale` multiplier about center, `dx`/`dy` pixel offsets in the cell (+x right, +y down), `shx`/`shy` shear, `flipX` (0|1) horizontal mirror. Absent → identity. On a `fit.pixel_unfake` run, rows baking the pixel variant re-snap the transformed result onto the fixed logical grid (`apply_transform(snap_scale=…)`, mirrored live by the webview) — see [`pixel-unfake.md`](pixel-unfake.md). Every other row bakes the transform with its coverage and its colour mapped apart (`transform_cell`, [`video-pipeline.md`](video-pipeline.md) "Cells"), so a rotated or scaled keyed frame gets no lighter rim or key tint at its edge.
+- `transforms` — keyed by 0-based frame index. `rotate` degrees (counter-clockwise positive, PIL convention), `scale` multiplier about center, `dx`/`dy` pixel offsets in the cell (+x right, +y down), `shx`/`shy` shear, `flipX` (0|1) horizontal mirror. Absent → identity.
- A state missing from the sidecar uses the all-frames identity default.
- The transform is applied at compose time inside the request-sized cell, so atlas geometry never changes. `manifest.json.animation.rows.<state>.frames` reflects the curated frame count, and `manifest.json.curation_applied` records whether a sidecar was used.
@@ -283,21 +164,11 @@ The chosen layout source is always reported (`manifest` / `grid-explicit` / `aut
## Base editing (same component as frames)
The base reference row's edit button opens the **same zoom modal** used for frame
-editing (maintainer 2026-07-17: no parallel editor). What differs is only the target:
-
-- The edit space is a **logical image built from the detected base grid** — each
- detected block's center pixel sampled from the raw (`/api/base-grid` cut lines).
- Display quantization, painting, marquee, eyedropper, palette, and the grid
- overlay all live in this uniform logical space; a uniform grid over the raw
- would drift (non-uniform fractional pitch + origin offset), so the raw view
- (pixel-unfake toggle OFF) shows no uniform grid — same rule as frames' plain view.
+editing. What differs is only the target:
+
- Edits/transforms accumulate client-side and bake into `base-source` only via the
- explicit **save-to-base** button (`POST /api/base-edit`, `space: "logical"`;
- pixel ops expand to raw blocks and the transform bakes after edits with
- `curation.apply_transform` math, re-composited onto the chroma background).
+ explicit **save-to-base** button.
The original is backed up once as `.orig`. Nothing about the base ever enters
`curation.json` (the `__base__` virtual state is excluded from the payload).
- Base edits affect FUTURE generation (anchors/rerolls) — already-extracted frames
derive from raw strips and do not change.
-- The palette dock merges near-identical raw shades (Manhattan tol 24) and excludes
- the chroma background; frames show their exact quantized colors unmerged.
diff --git a/docs/gen.md b/docs/gen.md
index edac279..aae071f 100644
--- a/docs/gen.md
+++ b/docs/gen.md
@@ -2,11 +2,9 @@
> Owns: `sprite-gen gen` / `gen-set`: providers, default resolution and what a default codex that cannot run turns into, transparency strategy per provider, the billed knobs (`--quality`, `--resolution`), when a refused provider request is sent again (every direct provider call), row usage · Index: [docs/README.md](README.md)
-Generation is a first-class engine module (`sprite_gen/gen/`), not an external
-skill. One call = a prompt (+ optional reference images) → one **verified** PNG on
+Generation is a first-class engine module (`sprite_gen/gen/`). One call = a prompt (+ optional reference images) → one **verified** PNG on
disk, with an optional transparent output whose strategy is decided per provider
-(native alpha or deterministic chroma keying). The general `image-gen` skill is a
-thin shuttle over this command.
+(native alpha or deterministic chroma keying).
Providers are the backends the maintainer uses day to day. Others (Gemini,
OpenRouter, fal, BytePlus, …) are absent because nobody here uses them, not because
@@ -18,7 +16,7 @@ added, however it is invoked
| Provider | Backend | Auth | Billing | Output truth | Transparency strategy |
|---|---|---|---|---|---|
-| `codex` | codex `image_gen` | ChatGPT OAuth | your ChatGPT subscription | inline base64 in the session rollout jsonl, decoded deterministically | **`native`** — image_gen returns a real alpha channel when asked (measured, then published) |
+| `codex` | codex `image_gen` | ChatGPT OAuth | your ChatGPT subscription | inline base64 in the session rollout jsonl, decoded deterministically | **`native`** — image_gen returns a real alpha channel when asked |
| `grok` | direct Imagine `/images/generations` or `/images/edits` | Grok login (preferred) or `XAI_API_KEY` | your SuperGrok Imagine quota; console credit only on the key route | inline bytes decoded and re-encoded as a verified PNG | `chroma` — Imagine returns JPEG only; generate on a key and matte it out |
| `openai` | direct Images `/v1/images/generations` or `/v1/images/edits` | `OPENAI_API_KEY` | **billed per call** — for servers and SaaS | inline base64 decoded and published as a verified PNG | **`native`** — `background: transparent` returns a real alpha channel |
@@ -33,8 +31,7 @@ reaches the same family of GPT image models over the REST API with nothing but a
key — which is what a headless container (a Modal worker, CI, a SaaS backend) can
have, and where an interactive ChatGPT login cannot exist — and every call is
billed against that key. So it is registered, documented, and runs **only when the
-user chose it** (maintainer 확정 2026-09-20, widened 2026-10-16 from "only when
-named"):
+user chose it**:
- it runs when `--provider openai` names it, or when it is the user's own answer
for a default codex that cannot run ([below](#when-codex-cannot-run--ask-or-what-you-chose));
@@ -51,11 +48,10 @@ If you are one person generating sprites, use `codex` or `grok`.
## Default provider selection
`--provider` is **optional**. When omitted, the backend is resolved by a fixed
-precedence (maintainer 확정 2026-07-17):
+precedence:
1. **`SPRITE_GEN_DEFAULT_PROVIDER`** env var (`codex` or `grok`) — the user override.
- An unknown value fails loud, and so does `openai`: a per-call API backend is
- never a default ([subscription first](#subscription-first--openai-runs-only-when-you-chose-it)).
+ An unknown value fails loud.
2. **`codex`** — the hard default (GPT `image_gen`).
A resolved default of `codex` that cannot run here turns into what the user chose
@@ -76,8 +72,7 @@ codex that could not run was switched to the provider chosen for that.
## When codex cannot run — ask, or what you chose
A call that names no provider (`gen`, `logo`, `gen-set`, `video-set`'s mid-step
-redraw) runs on codex. When codex **cannot run here** it does not switch on its own
-(maintainer 확정 2026-10-16; until 2.44.0 it went to `grok` unasked). Codex cannot
+redraw) runs on codex. When codex **cannot run here** it does not switch on its own. Codex cannot
run when
- **it is not signed in** (`cause: login`): `codex_provider.codex_login` — the CLI is
@@ -85,7 +80,7 @@ run when
Known before anything is generated.
- **its usage is used up** (`cause: usage-limit`): `codex exec` ends on one of the
errors codex itself classes as its usage limit, read from what it says
- (`codex_provider.usage_limit`, below). Known only after `codex exec` ran, so the
+ (`codex_provider.usage_limit`). Known only after `codex exec` ran, so the
same choice applies there: the call runs again on the chosen provider.
What happens then is the user's choice, one of three:
@@ -109,24 +104,6 @@ further stage; a `video-set` lets its other items finish, as they need no codex)
report and `table.md` keep the question (`asked`), and the line names the set's own
flag. Rerun the set with the answer's flag; finished rows and items are reused.
-**The usage-limit signal** (2026-10-16, codex-rs source at `rust-v0.160.1` and
-`rust-v0.153.4`). codex classes three errors as its usage limit
-(`CodexErr::to_codex_protocol_error` → `CodexErrorInfo::UsageLimitExceeded`,
-`codex-rs/protocol/src/error.rs`): `UsageLimitReached` (an HTTP 429
-`usage_limit_reached`), `QuotaExceeded` (429 `insufficient_quota` and its billing
-codes) and `UsageNotIncluded` (429 `usage_not_included`; `codex-rs/codex-api/src/api_bridge.rs`).
-`codex exec --json` carries only their message: its `error` and `turn.failed` events
-hold `message` alone (`codex-rs/exec/src/event_processor_with_jsonl_output.rs`), the
-error event is not kept in the rollout (`codex-rs/rollout/src/policy.rs`), and codex
-exits 1. So the signal is the start of each message as codex's own tests pin it
-(`codex-rs/protocol/src/error_tests.rs`): "You've hit your usage limit" (the
-apostrophe is ASCII in 0.153.4 and U+2019 in 0.160.1), "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
-failure of `codex exec` is a failure, not the question. These sentences were read
-from the source, not seen from a used-up account; a codex release that rewords them
-is a failure until this list follows it.
-
## Direct Grok calls and authentication
`sprite-gen gen --provider grok` → `GrokProvider` → xAI Imagine API. The same
@@ -135,27 +112,12 @@ The default is `grok-imagine-image-2.0`. `--model` selects an **image API model*
not a Grok Build reasoning model.
Image and video calls share `sprite_gen/gen/xai.py` for credentials and JSON
-transport. The user's Grok subscription login (`GROK_HOME` or `~/.grok`) takes
-precedence even when `XAI_API_KEY` is set. Only an absent login file permits the
-API key (console credits); an invalid, expired or rejected login never does. See
+transport. See
[authentication and expiry](video.md#setup--pick-one-credential)
-for setup; the video modes (last-frame pin, references, `video-extend`, `video-edit`) are in [video.md](video.md#modes--which-flags-call-what). No Grok executable is needed during generation with a valid credential.
+for setup. No Grok executable is needed during generation with a valid credential.
No agent or credential fallback is started on failure; a refusal xAI documents as a request not
taken (429) is sent again, nothing else is ([a refused request sent again](#a-refused-request-sent-again)).
-New images use `/v1/images/generations`; one reference uses `/v1/images/edits`
-with `image`, two to five use `images` in input order. A single-reference edit
-inherits its source aspect ratio; `--aspect-ratio` applies to generation and
-multi-reference edits. Invalid reference files and more than five references
-fail before upload. Base64 output is requested, decoded, and converted to a real
-PNG without resizing before atomic publication. Missing or malformed image data
-fails without replacing an existing raw output.
-
-Image reports include `extra.auth_source`, `extra.transport: "xai-api"`,
-`extra.endpoint`, and `extra.aspect_ratio_source`. Tokens, signed URLs and raw
-API error bodies are not reported. Skipping the agent removes its startup and
-reasoning overhead; speed and account-quota savings are not benchmarked guarantees.
-
API contracts: [image generation](https://docs.x.ai/developers/model-capabilities/images/generation),
[image editing](https://docs.x.ai/developers/model-capabilities/images/editing),
[multi-image editing](https://docs.x.ai/developers/model-capabilities/images/multi-image-editing).
@@ -179,67 +141,7 @@ repeated `image[]` parts in the order given (up to 16). A reference that is not
readable PNG, JPEG or WebP fails before upload, and parts are named by position, not
by the local filename.
-gpt-image models always answer with inline base64 (the API does not accept
-`response_format`), so there is no signed URL to follow and no bearer token to
-forward. The payload is decoded, verified as a PNG and published atomically without
-resizing; a missing, malformed or multi-image response fails without replacing an
-existing raw output. HTTP 401/403 names the credential; any other non-200 fails
-with the status, the provider's code and the error body the provider sent.
-
-A refusal line is `<verb>: <reason> (HTTP <n>)[ code=<code>][ key=value ...]; …: <body>`:
-`code=` is the provider's `error.code` when it matches `^[A-Za-z0-9_.:-]{1,64}$`,
-and `<reason>` is `refused by the provider's content policy` when that code is a
-documented policy block (`sprite_gen/gen/refusal.py` `POLICY_CODES`: openai
-`moderation_blocked`, followed by `moderation_stage=input|output|unknown`). The
-`(HTTP <n>)` part never changes shape. The video verbs use the same `code=` and
-reason, and a clip xAI reports with `respect_moderation: false` is that refusal
-with `respect_moderation=false` in place of a code (docs/video.md). A clip xAI
-accepted and the poll timeout cut short is no refusal: its line names
-`request_id=<id>` and carries no `(HTTP <n>)`, so nothing that sends a refused
-request again sends it (docs/video.md, An unfinished generation).
-
-`<body>` is the provider's error body as received, last on the line: JSON on one
-line, anything else as its text (line breaks written as `\n`), nothing when the body
-was empty. Two things in it are masked with `[redacted]` (`refusal.masked`): strings
-shaped like an API key (`sk-…`, `xai-…`, a `Bearer` value, and the credential the
-request carried; a key the provider already masked stays as it came) and the query
-string of any URL wherever the URL starts, where a signature lives. Each string is
-masked as the provider sent it, before the body is put on one line, so only a letter
-or digit of the provider's own text in front makes `sk-`, `xai-` or `bearer` part of
-a word (`task-…`); a line break, a tab or any other character does not. The body can
-repeat the prompt, so a product that shows sprite-gen's stderr to its own users
-decides what to cut there.
-The video verbs print what xAI said the same way, through the same mask. Because the
-body comes after everything else, nothing it says moves the status, reason or code
-a caller reads off the front.
-
-`--aspect-ratio` picks the `size`. gpt-image has no long-edge preset, so the ratio
-maps to one concrete size out of a table that satisfies the documented constraints
-(both sides divisible by 16, ratio within 1:3..3:1, 655,360–8,294,400 pixels) and is
-checked by the test suite: `1:1` 1024x1024, `3:2` 1536x1024, `2:3` 1024x1536, `4:3`
-1024x768, `3:4` 768x1024, `16:9` 1536x864, `9:16` 864x1536, `2:1` 1440x720, `1:2`
-720x1440, `3:1` 1536x512, `1:3` 512x1536, plus `auto`. Omitted = 1024x1024. A ratio
-with no exact gpt-image size (`19.5:9`, say) is refused rather than rounded to a
-nearby one you would be billed for.
-
-`--transparent` asks for `background: transparent` with `output_format: png` —
-genuine alpha, the same `native` strategy as codex, and the same measurement gate
-afterwards. Measured 2026-09-20 on `gpt-image-2.5-flare` at `--quality low`: 84 % of
-the frame at alpha 0, the subject itself at alpha 251–254 (so `partial_alpha_pct`
-covers the body, exactly as codex `image_gen` does — downstream extraction treats
-`alpha ≤ 16` as transparent, so this is usable as-is).
-
-Image reports include `extra.auth_source`, `extra.transport: "openai-api"`,
-`extra.endpoint`, `extra.quality`, `extra.size`, `extra.background`, when the
-API returns it, `extra.usage` (token counts only — what the call cost, never what it
-contained), and `extra.rate_limit`: every `x-ratelimit-*` header the response carried,
-names lower-cased and values as sent (`{"x-ratelimit-remaining-requests": "49", …}`),
-`{}` when none came. OpenAI's rate-limits guide names request, token and project-token
-limits there and lists images per minute among the limits without naming a header for
-it, so whatever the images endpoints send is what the report holds.
-
-API contract: [OpenAI Images](https://developers.openai.com/api/images/) (field names
-and enums confirmed there 2026-09-20).
+API contract: [OpenAI Images](https://developers.openai.com/api/images/).
## A refused request sent again
@@ -248,44 +150,7 @@ facing check, the clip request and polls of the video verbs (docs/video.md), and
Anthropic transport of `pixel-draw` (docs/pixel-draw.md) — in `sprite_gen/gen/retry.py`:
- **A POST is sent again only when its provider documents the answer as a request it
- did not take.** That request made nothing, so asking again buys nothing twice. What
- the providers say, read 2026-10-13:
-
- | Provider | Sent again | Not sent again |
- |---|---|---|
- | OpenAI ([error codes](https://developers.openai.com/api/docs/guides/error-codes), [rate limits](https://developers.openai.com/api/docs/guides/rate-limits)) | 429 "Rate limit reached for requests" and `slow_down`; 503 `server_is_overloaded` — the two its SDKs retry | 500 "The server had an error while processing your request"; the billing 429s (`credit_balance_exhausted`, `organization_spend_limit_exceeded`, `project_spend_limit_exceeded`, `organization_usage_limit_exceeded`, type `insufficient_quota`): "Don't retry quota, billing, or other errors that require you to take action" |
- | xAI ([debugging](https://docs.x.ai/developers/debugging), [rate limits](https://docs.x.ai/developers/rate-limits)) | 429 "You are sending requests too frequently and have reached the rate limit" | everything else — it documents no 5xx |
- | Anthropic ([errors](https://platform.claude.com/docs/en/api/errors), [rate limits](https://platform.claude.com/docs/en/api/rate-limits)) | 429 `rate_limit_error`; 529 `overloaded_error`; 500 `api_error` ("Retry the request with exponential backoff") | 504 `timeout_error` "The request timed out while processing"; the spend-cap 429 (`error.details.error_code: enforced_spend_limit_reached`, no `retry-after`), which "fails until access resumes"; 502, 503 |
-
-- **The wait** is the answer's `retry-after` when the run waits that long (at most
- 120 s; a longer one is not waited out early — the request is not sent again), else
- the doubling wait the video polls wait by: 8 s, then 16 s. **Twice at most**, each
- said on stderr, the status in plain digits:
- `[gen] openai refused the request (429 rate_limit_exceeded); nothing was made — asking again in 8s (1 of 2)`.
- A refusal still there after that ends the call as any refusal does, its line saying
- `sent 3 times, no provider fallback` where it says `no retry or provider fallback`.
-- **The waits are inside the call's time limit**, counted from its first send:
- `SPRITE_GEN_GEN_TIMEOUT_SECONDS` (180) for an OpenAI or Grok image and the OpenAI
- facing check, 120 s for the Grok facing check — each send reading only what is left
- of it — the poll timeout for a clip (docs/video.md), `--batch-wait` for the reads of
- a Message Batch (docs/pixel-draw.md). A wait that would reach the limit is not
- waited: the refusal ends the call after one line,
- `[gen] openai refused the request (429 rate_limit_exceeded); nothing was made — not asking again: the 16s wait would reach the time limit (12s left)`.
- The limit is read again after the wait, right before the send: a sleep may wake
- later than it was asked to, and one that woke at the limit or past it sends nothing —
- the refusal ends the call the same way,
- `[gen] openai refused the request (429 rate_limit_exceeded); nothing was made — not asking again: the time limit came during the 8s wait`.
- A realtime `pixel-draw` call has no time limit of its own.
-- **A request that got no answer it could read is never sent again** — the connection
- broke, it timed out, or the answer broke on the way, a refusal whose body broke
- included (`xai.error_body`: a refusal's status alone is not an answer read whole).
- The server may have taken it.
-- **A GET buys nothing**, so one answered 429, 500, 502, 503, 504 or 529 is asked again
- after the same doubling wait: the video polls for as long as their poll timeout lets
- them (docs/video.md), the reads of a Message Batch twice.
-
-`video-set` runs each clip once: a 429 is sent again inside `sprite-gen video`, and a
-second run on top would make every one of its POSTs a second retry loop.
+ did not take.** That request made nothing, so asking again buys nothing twice.
## CLI
@@ -319,9 +184,7 @@ Backward-compatible wrapper: `$SPRITE_GEN_ROOT/.venv/bin/python $SPRITE_GEN_ROOT
- The pre-process raw is preserved next to the destination as `<out>.raw.png` for audit.
- `--report` writes a `sprite-gen-image-report` JSON: provider, prompt, out/raw paths,
`raw_bytes`, `elapsed_seconds`, `session_id` (codex), an `alpha` block
- (`strategy` + the measured stats), the `chroma` stats when chroma keying ran, and the
- provider-resolution fields (`provider_resolved_from`, and `provider_fallback` when a
- default codex that could not run was switched to the provider chosen for that), plus the provider `extra` block
+ (`strategy` + the measured stats), the `chroma` stats when chroma keying ran, plus the provider `extra` block
(`auth_source`, `transport`, `endpoint`, and the knobs the request actually
carried).
@@ -334,12 +197,6 @@ Backward-compatible wrapper: `$SPRITE_GEN_ROOT/.venv/bin/python $SPRITE_GEN_ROOT
**`--handed`** adds, per item, which of the character's own sides it is on and where that side is in
the view; with it, `--facing-fix mirror` is refused and `regen` never mirrors. See
[video-pipeline](video-pipeline.md#handedness--an-item-on-one-side).
-- **The engine's sentences go on after yours, as written.** The view, the turn over a reference, the
- handed item, the key background and the layout guide are attached in one place; without `--handed`
- the prompt is 2.22.0's, byte for byte. Leave out of your text what an option says. Where your own
- text says the opposite of an option ("facing left" with `--facing right`) it is left as written and
- stderr warns; the report lists it under `extra.prompt_notes`. See
- [prompt-assembly](prompt-assembly.md).
## `--quality` and `--resolution` — the two billed knobs
@@ -352,62 +209,41 @@ capability, declared in its adapter:
| `grok` | `auto` `low` `medium` | `1k` `1.5k` `2k` |
| `openai` | `auto` `low` `medium` `high` `xhigh` `max` | refused — a gpt-image `size` comes from `--aspect-ratio` |
-- **Omitted = the provider's own default.** The request body is then byte-identical
- to what the same call already sent, so nothing about existing runs changes.
+- **Omitted = the provider's own default.**
- **A level a provider cannot honour fails before the call.** It is never dropped
from a body you are about to pay for, and never downgraded to whatever the
backend felt like returning (No Silent Fallback). "Refused" above is a loud error
naming the flag, not a silently ignored argument.
- **grok prices an image on the pair**, so `2k` + `medium` costs more than `1k` +
`low`. The resolution names are **tiers, not pixel counts**: the service decides
- the pixels, and `1.5k` came back 1408x1408 at `--aspect-ratio 1:1` (실측
- 2026-09-20) — not 1536, and not 1024. Nothing here derives a size from the name.
-- The grok subsets were read off the server, not off the prose (2026-09-20 probes):
- `quality` deserializes the wider shared enum and *then* refuses per model
- (`high` → HTTP 400 "This model only supports the following quality value(s):
- low, medium, auto."), `resolution: 1.5k` renders (HTTP 200) although the
- capability guide's prose lists only 1k and 2k, and an **unknown field is not
- refused at all** — a probe carrying one rendered normally. That last one is why
- these names are checked locally instead of being left to the service to notice.
+ the pixels. Nothing here derives a size from the name.
- Every call that spends API credit rather than a subscription prints the knobs it
is being billed on in the same stderr line as the charge.
## Transparent output — strategy per provider
-`--transparent` does not mean "chroma key" any more. Each adapter declares the one
+Each adapter declares the one
strategy it can execute, and `--alpha-mode auto` (the default) follows it:
| Strategy | Who | What happens | Refused when |
|---|---|---|---|
-| `native` | `codex` (**first choice**, 2026-09-08), `openai` (`background: transparent`) | On codex the transport prompt asks image_gen for a genuinely transparent background (the bundled `imagegen` skill honours "transparent background" and keeps the generated alpha; codex reports `transparentBackground: true` on the completed item); on openai the request carries `background: transparent` with `output_format: png`, which the API answers with a real alpha channel. Either way the decoded PNG's alpha is **measured**: no alpha band or `alpha_zero_pct: 0.0` refuses to publish, RGB under alpha 0 is scrubbed, partial alpha (1–254) is left as produced and reported as `partial_alpha_pct`. | The model drew a checkerboard / flat background (RGB image) — nothing can recover alpha from that, so the run fails instead of silently keying. |
-| `chroma` | `grok` (only option), `codex` with `--alpha-mode chroma` | Generate on a `#FF00FF` (or `#00FF00`) background — pick the key by subject colour (magenta subjects → green key) — and matte it out through the frame extractor's canonical YCbCr matte (`remove_chroma_background_ycbcr`), which keys from the background chroma it detects on the borders (`detect_background_key_ycc`) rather than from the pure key alone — the RGB matte behind `cutout`/`extract`/`slice-sheet` does the same since 2026-09-11 (`detect_background_key_rgb`), so every chroma path tolerates the slightly-off green/magenta generators actually paint. Gradients and texture within that chroma family are supported. | `alpha_zero_pct: 0.0` after keying, or stale RGB under alpha 0; and, before keying, a background painted as a transparency checkerboard (below). |
+| `native` | `codex` (**first choice**), `openai` (`background: transparent`) | On codex the transport prompt asks image_gen for a genuinely transparent background; on openai the request carries `background: transparent` with `output_format: png`, which the API answers with a real alpha channel. Either way the decoded PNG's alpha is **measured**: no alpha band or `alpha_zero_pct: 0.0` refuses to publish, RGB under alpha 0 is scrubbed, partial alpha (1–254) is left as produced and reported as `partial_alpha_pct`. | The model drew a checkerboard / flat background (RGB image) — nothing can recover alpha from that, so the run fails instead of silently keying. |
+| `chroma` | `grok` (only option), `codex` with `--alpha-mode chroma` | Generate on a `#FF00FF` (or `#00FF00`) background — pick the key by subject colour (magenta subjects → green key) — and matte it out. Gradients and texture within that chroma family are supported. | `alpha_zero_pct: 0.0` after keying, or stale RGB under alpha 0; and, before keying, a background painted as a transparency checkerboard (below). |
-- **`auto` steps down to `chroma` when `--ref` is attached**, on either native provider. Measured
- 2026-09-08 (plan `sprite-gen/parts-rig`): codex `image_gen` with reference images
- returned real alpha in 1/6 runs and drew a checkerboard (RGB) in 5/6, while the same
- prompts on a `#00FF00` key + chroma keying succeeded 6/6. The decision is made before
+- **`auto` steps down to `chroma` when `--ref` is attached**, on either native provider. The decision is made before
the model runs, printed to stderr, and recorded as `alpha.strategy_source:
- "refs-attached"` (`provider-default` / `explicit` otherwise). The measurement is
- codex's; openai's edit path is not separately measured and inherits the same
- conservative default. `--alpha-mode native`
+ "refs-attached"` (`provider-default` / `explicit` otherwise). `--alpha-mode native`
still forces native alpha with refs — and fails loud on an RGB result.
- **The step down asks for its key.** A planned key needs a key background in the
prompt, so the engine adds the `--chroma-key` key's line
(`chroma.KEY_BACKGROUND_TEXT`, the sentence a clip's mid-step redraw also ends on)
to a prompt that names no key, and leaves a prompt that does as it is — no second
- line. A prompt names a key with the key's hex code (`#FF00FF`, `00ff00`) or the
- key's name right before "background", "backdrop", "chroma key", "key" or "screen"
- (`chroma.named_key_background`); a colour in the subject ("a green frog") is not a
- key. A prompt that names the other key is left on it: the matte reads the key off
+ line. A prompt that names the other key is left on it: the matte reads the key off
the borders. Write the key as "a magenta background" or "#FF00FF": "no green screen"
reads as naming green, and "a background of pure magenta" is not read
([prompt-assembly](prompt-assembly.md#known-faults-kept-for-now)).
`alpha.key_background` records `{"injected": true|false, "key": …}`,
- stderr says which, and the report's `prompt` is the prompt sent. Without the line a
- reference on white came back on opaque white (3/3, 2026-10-04) and keying white took
- the outline and the cream fills with it. With it (the same prompt otherwise, three
- takes on that RGB reference and two on the transparent one), all five came back on
- a magenta key and were keyed with the outline and cream whole. Only `auto`'s step
+ stderr says which, and the report's `prompt` is the prompt sent. Only `auto`'s step
down adds the line: `--alpha-mode chroma` is the caller's own key and prompt, and a
native run asks for alpha instead.
- **A ref run whose raw already has a transparent background is not keyed.** The key
@@ -416,103 +252,32 @@ strategy it can execute, and `--alpha-mode auto` (the default) follows it:
at alpha 0 and at least half of its one-pixel border at alpha 0 is `real-alpha`, and
it is published on its own alpha through the `native` check
(`alpha.strategy: "native"`, `alpha.strategy_source: "refs-attached-raw-alpha"`).
- Keying it reads the RGB left under alpha 0 as the background colour and mattes the
- outline and light fills away. A raw with no alpha band or no alpha-0 pixel — a drawn
- checkerboard, a key background, an opaque RGBA — is `no-alpha` and keyed as before
+ A raw with no alpha band or no alpha-0 pixel — a drawn
+ checkerboard, a key background, an opaque RGBA — is `no-alpha` and keyed
(`strategy_source: "refs-attached"`), but a painted checkerboard is refused before
keying (below). Alpha 0 that misses either bar is `ambiguous`:
- keyed as before, with a `warning` in the report and on stderr. The verdict and its
+ keyed, with a `warning` in the report and on stderr. The verdict and its
numbers are in `alpha.raw_alpha` on every ref run that planned the key. The check
belongs to `auto`'s step down only — `--alpha-mode chroma` keys whatever comes back.
- A `real-alpha` raw has no key to remove, so `--decontam` is skipped on it, not
- refused after the paid call: `alpha.decontam` records `{"requested": …, "skipped":
- …}` and stderr says so (a warning for `palette`, which demands the pass). The check
- is the counts, not the rounded percentages: a raw with a single alpha-0 pixel is
- `ambiguous`, reported as `0.0`. The judgment of the alpha band is one function,
+ The judgment of the alpha band is one function,
`chroma.alpha_verdict`: [`pixel-draw`](pixel-draw.md#gates)'s G3 asks it of every frame
it drew (a sprite or icon frame must be `real-alpha`, a tile `no-alpha`).
- Measured 2026-10-04 (codex `image_gen`, subscription, one transparent front still as
- the reference, three takes per arm): with the step down's prompt (no transparency
- request, no key colour), a transparent (RGBA) reference came back with real alpha
- 3/3 and an RGB one (the same still on white) on an opaque white background 3/3; with
- the native request (`--alpha-mode native`), both came back with real alpha 3/3 —
- no checkerboard in 6 runs, against 5 of 6 on 2026-09-08. The step down is kept
- until a larger measurement replaces that one.
- **A painted transparency checkerboard is refused before keying.** Asked for a key
background, a model sometimes paints the grey and white checkerboard that editors show
behind transparent pixels instead. The matte reads the key off the borders, so it reads
the checkerboard and keys nearly the whole image away: a UI kit sheet keyed that way has
- nothing left to cut. Every chroma key checks the raw first
- (`chroma.painted_checkerboard`). Each edge is read on its 8 nearest lines. A line is
- a checkerboard row when at least 90 % of it is grey (channels within 24 of each other),
- it holds two greys at least 12 apart (10th and 90th percentiles), and it changes from
- one to the other in at least 6 runs between changes, whose median is 4 to 128 px and
- three quarters of which lie within a quarter of it (or 2 px). A checkerboard alternates along both axes, so
- the raw is one when the top or bottom edge and the left or right edge show it. Stripes
- alternate along one axis only, a key background is not grey, and a checkered subject
- inside a key background does not reach the edges. The run then fails with its own
- reason, before anything is published:
- `chroma: the background is a painted transparency checkerboard (8 px squares along the
- top, bottom, left and right edges), not the magenta key the image was asked for; keying
- it would erase the image — generate it again`. A caller generates again.
-- `--alpha-mode chroma` on codex is for prompts that already carry a key background
- (the sprite-row pipeline today): the native request is **not** added to the prompt
+ nothing left to cut. A caller generates again.
+- `--alpha-mode chroma` on codex is for prompts that already carry a key background: the native request is **not** added to the prompt
and the raw is keyed like a grok run.
- `--alpha-mode native` on a `chroma`-only provider **fails loud before any model
call** — a strategy the backend cannot execute is not a fallback candidate, and
native → chroma never happens silently either (the prompt shapes are different).
-- Why grok is chroma-only: Grok Imagine Image 2.0 returns `image/jpeg` from both the
- `/v1/images/*` API and the CLI `image_gen`/`image_edit` tools, and the official
- docs expose no background parameter — its "background removal" is a consumer-app
- tool (4/4 drawn checkerboards on 2026-09-08). The declaration lives in
- `sprite_gen/gen/grok_provider.py` and flips only with a new measurement.
-- Measured codex output (2026-09-08, codex 0.153.4): `alpha_zero_pct ≈ 62`, body alpha
- ≈ 253 (so `partial_alpha_pct` is most of the subject), a ~1 px light fringe on a
- magenta composite. Downstream extraction treats `alpha ≤ 16` as transparent, so
- this is usable as-is; alpha snapping is deliberately not applied here.
-
-## How each provider works
-
-- **codex** — spawns a fresh `codex exec --json` in an empty sandbox
- (`--sandbox workspace-write`, `--add-dir <Codex state root>/generated_images`,
- `--skip-git-repo-check`, no `--ephemeral`). A fresh session breaks OpenAI's prompt
- cache so repeat prompts don't drag in a prior image. The session id comes from the
- `thread.started` event (older codex: a `session id:` text line — both supported); the
- inline base64 is decoded from the rollout jsonl (`image_generation_call` /
- `image_generation_end` records — both supported). The model-reported path is never
- trusted. The rollout jsonl (which holds the ~1–1.5 MB inline image) is deleted after
- extraction unless `--keep-session`.
- The adapter and child process share one Codex state root: when `CODEX_HOME` is set they use only that directory; when it is unset they use Codex's `~/.codex` default.
- Rollouts are selected by an exact session-id filename suffix.
- Missing, duplicate, or pre-existing stale matches fail rather than falling back to another root or choosing by modification time.
- The transport prompt names the skill with codex's official `$imagegen` mention, which is how a codex skill is invoked explicitly. The adapter owns that trigger alone; the caller's sprite-request prompt is passed through verbatim.
- How codex is signed in is asked once per call by `codex_provider.codex_login` (`codex login status`), the same reading the default resolution, the facing check and the guided workflow use: signed in with ChatGPT is the subscription (`auth_source: codex-login`); signed in with an API key bills that key per call, said on stderr before `codex exec` runs (`codex-api-key`); not signed in is refused with the reason before codex runs (an omitted `--provider` asks or runs what was chosen instead, [above](#when-codex-cannot-run--ask-or-what-you-chose)). A `codex exec` that ends on codex's usage limit is `codex_provider.CodexUsageLimit`: the same failure for a named codex, the same choice for a default one. What `codex login status` prints is never repeated: an API-key login can name its key.
- A codex call is stopped after `SPRITE_GEN_GEN_TIMEOUT_SECONDS` (180) without an answer and reported as a stall (`gen-timeout`).
-
-### When codex produces no image at all
-
-A run that reaches a rollout but finds zero `image_generation_call` /
-`image_generation_end` records means the built-in `image_gen` tool was never
-offered to the session, not that the model declined to use it. Built-in image
-generation is a **capability of the account behind the active Codex state root**.
-
-A session that is not offered the tool cannot be talked into it. The `$imagegen`
-mention names the skill, it does not create the tool; the model choice does not
-change it; and no `config.toml` feature toggle grants it. The remedy is to point
-`CODEX_HOME` at a Codex state root whose account provides image generation
-(`codex login status`), or to use `--provider grok`. The adapter fails loudly with
-exactly that, rather than falling back on its own.
-- **grok** — uses the [direct API contract](#direct-grok-calls-and-authentication) above.
-- **openai** — uses the [direct API contract](#direct-openai-calls-and-authentication)
- above: one HTTPS request on `OPENAI_API_KEY`, no CLI and no subprocess, which is
- the whole reason it exists (a container has a key, not a browser). Runs only when
- chosen, and billed per call.
## Sprite-row usage
-In the atlas pipeline (SKILL.md §2) the rows of a prepared run are generated by
+In the atlas pipeline the rows of a prepared run are generated by
`sprite-gen gen-set --run-dir <run>`: every non-mirrored state, `--concurrency` 6 at a
-time (lead-verified: no provider throttling at 6), each row with the identity ref the run declares (`base-source.*`, or the accepted
+time, each row with the identity ref the run declares (`base-source.*`, or the accepted
direction anchor for a direction-contract action row — `sprite_gen.curate.anchor` owns
that choice) plus its layout guide, into `raw/<state>.png`. Each row gets
`reports/gen-set/<state>.json`, the batch writes `reports/gen-set/table.md` and
@@ -523,34 +288,26 @@ unspecified, it resolves exactly as `gen` does (above): a switch to the provider
codex that cannot run is recorded per row with the row's `auth_source`, and rows that asked stop
the set with the question ([above](#when-codex-cannot-run--ask-or-what-you-chose)). Each row's
output goes to its log, but a row's billing line and a provider switch also print on the
-terminal as they happen (`base.run_logged`), so a metered row is never announced only in a file.
+terminal as they happen, so a metered row is never announced only in a file.
One row by hand is the same call `gen-set` makes: `--provider codex` (or `grok`) with
`prompts/<state>.txt`, writing `raw/<state>.png`.
-The row prompts are `prepare`'s, and were measured on people: a walk row moves "body, arm, leg", a
-front walk "alternating leg, arm, shoulder", a wave "arm pose only". For a body that is not one biped,
+The row prompts are `prepare`'s. For a body that is not one biped,
`prepare --body-plan quadruped` (or `legless`, or `"<figure>=<plan>"` per figure) writes every row
without a part the body lacks and says what it stands on
([sheet rows](video-pipeline.md#the-sheet-rows--prepare---body-plan)).
The row prompts still carry the request chroma key on the background and frame
extraction removes it downstream — rows are generated **without** `--transparent`, so
-the native strategy does not apply to them yet (moving rows to native alpha is a
-separate, measured change).
+the native strategy does not apply to them.
The correction loop (`sprite-gen correction-loop --provider-command …`) can drive this
`gen` command as its regeneration step so inspect → score → hint → regenerate closes
against a real provider.
## Speed
-On a 4-frame idle mushroom row, grok generated
-in ~18.4 s vs codex ~39.0 s (~2.1× faster). codex adhered better to negative constraints
-("no grid lines"); grok added faint cell dividers. Pick per need: grok for speed, codex
+Pick per need: grok for speed, codex
for tighter prompt adherence.
-## Related
-
-- [docs/README.md](README.md) — documentation index
-
## `--layout-guide` — room above the head and under the feet
A single still drawn from words tends to fill its frame top to bottom. Animated in place
@@ -558,10 +315,9 @@ A single still drawn from words tends to fill its frame top to bottom. Animated
draws the one-slot form of the row guide `prepare` writes for every row and attaches it
after any `--ref`:
-- the frame, its inner safe box at the row guide's margin (9.4 % of the frame, as
- `prepare`'s `DEFAULT_SAFE_MARGIN_RATIO`), and the centre line;
+- the frame, its inner safe box at the row guide's margin, and the centre line;
- an orange **crown line** and a teal **floor line**, each one margin *inside* the safe
- box (about 19 % and 81 % of the frame height). On the box's own edges a crown line
+ box. On the box's own edges a crown line
leaves hair and hats to fill the room above it, and a floor line reads as a frame
edge that the feet float above.
@@ -573,16 +329,6 @@ for `--aspect-ratio` (square without one) and the report records the cell it use
`extra.layout_guide` (size, safe margins, `crown_y`, `floor_y`); the report's `refs` are
still the caller's own.
-`--layout-guide ui-kit` attaches the UI kit layout instead: one box per element of a game
-UI kit, and a paragraph naming what to draw in each box, with straight edges between
-corner ornaments and empty centres. [`ui-kit`](ui-kit.md) cuts the sheet along the same
-boxes. The ratio chooses the layout: `--aspect-ratio 1:1` (or none) draws the square
-layout's seven frames (panel, button, pressed button, card frame, two bar frames, timer
-badge); `--aspect-ratio 2:3` draws the whole kit, those seven at the same places and, below
-them, the two bar fills, an item slot, a counter plate, a lit and an unlit dot and a
-joystick base and knob. Any other ratio is refused. `extra.layout_guide` is then
-`{"kind": "ui-kit", "width", "height", "boxes"}`.
-
The guide is an attached image, so it changes the call: openai sends it to
`/images/edits` and bills it as image input, grok sends it as a reference, and
`--transparent` steps down to chroma keying as it does for any `--ref`. How closely a
diff --git a/docs/user-workflow.md b/docs/user-workflow.md
index faf2e81..6934656 100644
--- a/docs/user-workflow.md
+++ b/docs/user-workflow.md
@@ -1,6 +1,6 @@
# Image and sprite requests
-This document owns the conversation flow. `sprite_gen/workflow/catalog.py` owns the two journeys and their choices; `workflow` derives questions and engine steps from it. Commands in this document assume `SPRITE_GEN_ROOT` is the absolute installed repository path.
+This document owns the conversation flow. `sprite_gen/workflow/catalog.py` owns the two journeys and their choices; `workflow` derives questions and engine steps from it.
## Start with the user's request
@@ -11,21 +11,14 @@ This document owns the conversation flow. `sprite_gen/workflow/catalog.py` owns
Inspect the request before asking anything. Pass choices already named by the user as explicit arguments. An existing sprite base image skips base-image generation and its provider question. An image request may still attach references to `gen --ref` for editing.
-A clip from a video MCP on the agent (ZCRE) is a third way to animate the base. `workflow` does not offer it: its motion methods are the two above, so a request that names the MCP goes to that row of the [SKILL](../SKILL.md) execution routes. The Grok video method has one step, `video-set`, which runs its own canvas, clip, frames, loop and set alignment. On the MCP route each stage is a verb the agent runs: `video-canvas` → `video-prompt --no-last-frame` → the agent's MCP tools → `video-frames` → `video-loop` (`--anchor motion-auto` for a walk or run) → `video-cycle-align`, once a walk or run is cut in two or more directions ([video-pipeline](video-pipeline.md#a-clip-from-a-video-mcp-on-your-agent--zcre)).
-
-```bash
-$SPRITE_GEN_ROOT/.venv/bin/sprite-gen workflow --kind sprite
-$SPRITE_GEN_ROOT/.venv/bin/sprite-gen workflow --kind image
-```
-
-The command is read-only: it checks available credentials, reads defaults and returns JSON. `status` is `ready`, `needs-input` or `blocked`; exit 0 means ready and exit 2 means read the questions or blockers. It never generates images, launches a browser, changes authentication or saves defaults.
+The command is read-only: it checks available credentials, reads defaults and returns JSON. `status` is `ready`, `needs-input` or `blocked`; exit 0 means ready and exit 2 means read the questions or blockers.
1. Check the returned access state and explain only what needs the user's attention.
-2. Ask the missing generation choices in `questions`, using their labels rather than CLI identifiers. For sprites, explain that the first provider creates the base drawing, while the motion method animates it. Until it is answered, `questions` also holds `codex_unavailable` ("지피티(codex)를 쓸 수 없을 때 — 로그인이 없거나 사용량을 다 썼을 때 — 어떻게 할까요?": stop and ask, Grok, or the OpenAI API billed per call). It is asked once: save the answer at once with `defaults save --codex-unavailable <answer> --expected-revision <settings_revision>` (the question's `save: general`, no `--kind`), and it is not asked again. `codex_unavailable` in the guide's answer says the choice in force and where it came from (`saved`, `SPRITE_GEN_CODEX_UNAVAILABLE`, or `default` = not yet answered).
+2. Ask the missing generation choices in `questions`, using their labels rather than CLI identifiers. For sprites, explain that the first provider creates the base drawing, while the motion method animates it. Until it is answered, `questions` also holds `codex_unavailable` ("지피티(codex)를 쓸 수 없을 때 — 로그인이 없거나 사용량을 다 썼을 때 — 어떻게 할까요?": stop and ask, Grok, or the OpenAI API billed per call). It is asked once: save the answer at once with `defaults save --codex-unavailable <answer> --expected-revision <settings_revision>` (the question's `save: general`, no `--kind`), and it is not asked again.
3. Run `workflow` again with the answers. Request choices override saved values without modifying them. When choices came from saved defaults, briefly announce them and do not ask again.
4. Gather only missing creative inputs: subject, style, requested motions and output needs. Lock the base before motion generation.
-5. Only when the start stage returns `status: ready`, run the returned pipeline through the existing tools. A populated `pipeline` is a proposal, not permission to ignore unresolved questions or blockers. Always pass its explicit provider to `gen`/`gen-set`; do not rely on the low-level CLI's omitted-provider resolution. GPT rows use `codex` even when Grok made the base. No availability-driven provider switch is allowed in this workflow. A step that still names no provider — `video-set`'s mid-step redraw for a front or back walk — follows the saved `codex_unavailable` answer when codex cannot run; when that answer is to ask, the step ends with exit 75 and the question ([gen](gen.md#when-codex-cannot-run--ask-or-what-you-chose), [SKILL](../SKILL.md#when-codex-cannot-run--exit-75)).
-6. Complete the pipeline's QA and deliver the output files. Chroma removal, extraction, placement and export are automatic stages, not user choices. Raw images are evidence, not replacements for extracted sprite frames. Follow [atlas-workflow](atlas-workflow.md), [video-pipeline](video-pipeline.md) or [gen](gen.md), as returned by the guide.
+5. Only when the start stage returns `status: ready`, run the returned pipeline through the existing tools. A populated `pipeline` is a proposal, not permission to ignore unresolved questions or blockers. Always pass its explicit provider to `gen`/`gen-set`; do not rely on the low-level CLI's omitted-provider resolution. No availability-driven provider switch is allowed in this workflow.
+6. Complete the pipeline's QA and deliver the output files. Raw images are evidence, not replacements for extracted sprite frames. Follow [atlas-workflow](atlas-workflow.md), [video-pipeline](video-pipeline.md) or [gen](gen.md), as returned by the guide.
```bash
$SPRITE_GEN_ROOT/.venv/bin/sprite-gen workflow --kind sprite \
@@ -36,9 +29,9 @@ $SPRITE_GEN_ROOT/.venv/bin/sprite-gen workflow --kind sprite \
Login, subscription and quota are separate facts. Codex uses `codex login status`; Grok uses the shared image/video credential reader, without rewriting its auth file. Neither probe proves the current media entitlement or remaining quota: those fields remain `unknown`. When access has not independently been established for the current account and request, ask the user once and pass `--confirmed-access codex` or `--confirmed-access grok`. An explicit account/access statement already in the conversation can answer this question; never manufacture confirmation from a saved provider preference. Known failed/missing credentials remain blocked even with confirmation. A successful generation is not a permanent entitlement cache.
-For Grok images and videos, the shared resolver prefers the subscription login even when `XAI_API_KEY` is configured. It selects that key only when no login file exists; an expired or invalid login stays blocked. The guide names the separate API-credit billing and requires `--confirm-api-billing` from an explicit user choice before that route becomes ready. It never silently switches from subscription use to API credit. No keys, tokens, account IDs or subscription assertions are saved as preferences, and provider diagnostics do not echo raw credential output.
+The guide names the separate API-credit billing and requires `--confirm-api-billing` from an explicit user choice before that route becomes ready.
-The documented login commands are [Codex CLI login status](https://developers.openai.com/codex/cli/reference) and [Grok CLI login](https://docs.x.ai/build/cli/reference). These are authentication contracts, not subscription-verification endpoints. Native token parsing and shared credential priority stay owned by [video](video.md).
+Native token parsing and shared credential priority stay owned by [video](video.md).
## Finish after delivering files
@@ -55,7 +48,7 @@ When the profile has no saved defaults, finish then offers: "이번 선택을
## One settings owner
-`preferences.json` in `~/.config/sprite-gen/` owns the `sprite` and `image` profiles separately, and beside them the `general` settings every profile shares: so far `codex_unavailable` (`ask`, `grok` or `openai`; what a call that names no provider does when codex cannot run — the rule is [gen](gen.md#when-codex-cannot-run--ask-or-what-you-chose)'s). `SPRITE_GEN_CONFIG_DIR` explicitly relocates that directory. A profile may be partial, for example saving only motion and curation when an existing base skipped image-provider selection. Missing fields prompt when needed. This storage is independent of a project or run; a run's numeric recipe and curation edits keep their existing owners. The file is version 2 (`profiles` and `general`); a version 1 file (profiles only) still reads, with nothing chosen for codex, and the next save writes it as version 2.
+`preferences.json` in `~/.config/sprite-gen/` owns the `sprite` and `image` profiles separately, and beside them the `general` settings every profile shares: so far `codex_unavailable` (`ask`, `grok` or `openai`; what a call that names no provider does when codex cannot run — the rule is [gen](gen.md#when-codex-cannot-run--ask-or-what-you-chose)'s). `SPRITE_GEN_CONFIG_DIR` explicitly relocates that directory. A profile may be partial, for example saving only motion and curation when an existing base skipped image-provider selection. Missing fields prompt when needed. This storage is independent of a project or run; a run's numeric recipe and curation edits keep their existing owners.
```bash
$SPRITE_GEN_ROOT/.venv/bin/sprite-gen defaults show
@@ -68,6 +61,6 @@ $SPRITE_GEN_ROOT/.venv/bin/sprite-gen defaults save --codex-unavailable ask \
--expected-revision REVISION_FROM_SHOW
```
-Use the exact `settings_revision` from the guide, or `revision` from show (`missing` for no file). Save merges only supplied fields in the selected profile, and `--codex-unavailable` into `general` (it needs no `--kind`); clear removes only that profile. Both are explicit mutations. Reads never create or rewrite settings. Corrupt or unknown settings fail with a named error instead of resetting silently.
+Use the exact `settings_revision` from the guide, or `revision` from show (`missing` for no file).
-Writes use the package's cross-platform exclusive file lock, compare the observed revision under that lock, then atomically replace the complete JSON file. Two writers with the same revision cannot overwrite each other: the first committed write wins; the second fails and must reread/reconfirm. A repeated save with the current revision and identical values leaves bytes and mtime unchanged. Atomic replacement lets read-only queries see a complete old or new snapshot without creating a lock file.
+Two writers with the same revision cannot overwrite each other: the first committed write wins; the second fails and must reread/reconfirm.
diff --git a/docs/video-pipeline.md b/docs/video-pipeline.md
index b347c54..37e5ce4 100644
--- a/docs/video-pipeline.md
+++ b/docs/video-pipeline.md
@@ -5,9 +5,7 @@
One still becomes a whole motion set: the still is padded into the canvas a state
needs, Grok Imagine animates it in place, the clip is keyed frame by frame, and one
seamless cycle is cut out as a strip, a transparent GIF and a WebP — every stage
-measured and reported, nothing recovered silently. Everything here was first run by
-hand on 2026-09-08 (15 loops: 3 directions × 5 states) and the rules below are the
-ones that survived that day.
+measured and reported, nothing recovered silently.
```
still ──video-canvas──▶ canvas.png ──video──▶ clip.mp4 ──video-frames──▶ keyed/*.png ──video-loop──▶ strip · gif · webp ──video-cycle-align──▶ one cycle length (a set)
@@ -29,212 +27,54 @@ still ──video-canvas──▶ canvas.png ──video──▶ clip.mp4 ─
| `sprite-gen video-set-sheet` | `sprite_gen/video/set_sheet.py` | the loop directories of one set, each with its `--view` → one sheet: a row per direction in compass order, one cell size, one ground line, every row as cut, + a record and an optional centre picture; the loop directories are only read ([section 7](#7-one-sheet-for-a-set--video-set-sheet)) |
| `sprite-gen video-stop` | `sprite_gen/video/stop.py` | keyed frames + a walk or run loop → one-shot stop strip (`loop: false`, `hold_last: true`), GIF, WebP, report ([section 8](#8-a-walk-or-run-that-stops--video-stop)) |
-Wrappers: `scripts/video_canvas.py`, `scripts/video_frames.py`, `scripts/video_loop.py`,
-`scripts/video_set.py`. Binaries: `ffmpeg`/`ffprobe` (frames), `img2webp` from libwebp
-(WebP with exact alpha). Both are declared in `SKILL.md` `required_bins`.
-
## 1. Canvas — the input frame decides the output frame
Grok Imagine keeps the input image's framing and **ignores `aspect_ratio` on
-image-to-video** (a `3:4` request still came back 960×960). A jump whose hair leaves
-the frame cannot be fixed by prompt — it was fixed by padding the still. So the canvas
-is a property of the motion state, owned by one table (`STATE_CANVAS`):
+image-to-video**. So the canvas
+is a property of the motion state, owned by one table (`STATE_CANVAS`).
-| State | Shape | Ratio | Room | Why |
-|---|---|---|---|---|
-| `jump` | tall | 3:4 | 34 % head-room above the still | airborne frames need height |
-| `attack` | wide | 16:9 | 20 % above the still, at least 28 % in front (facing side), 20 % behind | a weapon raised overhead needs room above, a swing extends in front, and a long weapon drawn back reaches behind |
-| `projectile` | wide | 16:9 | 34 % in front | the projectile travels away |
-| everything else | square | 1:1 | — | in-place motion fits the still |
-
-The attack's room above is 20 %, not more. On a square or upright still that puts at least
-a quarter of the still's height above it, and with the still's own margin over the crown
-(8 % of its height is enough) that holds a weapon raised about a third of the body above
-the head. More room only made the body a smaller part of the clip, so `video-loop
---body-height` scaled it up to the delivery height; at 20 % it scales down. A still cropped
+A still cropped
at the crown gets only the quarter — pass `--headroom 0.26` or more for an overhead swing.
At this headroom the 16:9 ratio, not `--lead`, sets the width of a square still's canvas,
so a smaller lead changes nothing.
`--shape tall|wide|square` overrides the row; `--headroom` / `--lead` / `--trail` tune the room
(`--trail` is the empty fraction of the width kept behind the subject, for a weapon drawn
-back before the strike); `--facing left` mirrors the wide layout. A forced shape is that shape's
-own row, not the state's: `--shape tall` is the jump row, and `--shape wide` is a forced-wide
-row with 35 % above, 28 % in front and 20 % behind — not the attack row. It lands on states
-whose own row is another shape, a jump among them, and 35 % on 16:9 keeps about the room a
-jump's tall row leaves above a square or upright still. A still wider than it is tall keeps
-less above it under forced wide than under the tall row (a 3:2 still about three fifths),
-because there the wide canvas's height follows the still's width. A walk or run forced wide
-has a row of its own (`STATE_SHAPE_CANVAS`): the same 28 % in front and 20 % behind, and nothing
-above — its feet stay on the ground. Above a square still the jump's 35 % set the width as well
-(1575 rows on 16:9 are 2800 columns, 1216 of them in front of the still), and a walker that small
-in its frame is one a video model may reframe in its first frames (section 4, "A lead-in"). A
-square still forced wide as a walk is 1969 × 1108. Headroom is a fraction of the full canvas
-height; wide canvases grow both dimensions to preserve their ratio without shrinking
-the still. A still whose corners are not one flat colour
+back before the strike); `--facing left` mirrors the wide layout. A still whose corners are not one flat colour
is refused — a non-flat background cannot be extended without guessing.
**`--fit tight` adds no room.** It is the framing for a fixed body height at a low
clip resolution: the room above makes the subject a small part of the clip, and a
-`--body-height` target then has to upscale it. Tight drops the empty rows above and
-below the subject (keeping headroom of 4 % of the subject's height), keeps the still's full width,
-and pads to the nearest framing the video model returns — 9:16, 1:1 or 16:9, with the
-midpoints at 3:4 and 4:3 — by adding height above or width on both sides. The subject is never
-scaled or cut, a long, low subject in a square still becomes a 16:9 frame it fills,
-and an upright one keeps its square. A motion that leaves the frame is clipped: pair it
-with `video-frames --allow-subject-edge-contact`. Tight picks its own shape, so it
-refuses `--shape` / `--headroom` / `--lead` / `--trail`; the report says `fit` and
-the `tight` rows it kept.
+`--body-height` target then has to upscale it. A motion that leaves the frame is clipped: pair it
+with `video-frames --allow-subject-edge-contact`.
**The canvas owns key normalization.** Image models paint "`#00FF00`" a little
-differently every run — (8, 166, 25) on 2026-09-11 — and the video model reproduces
-the input colour almost exactly (a pure-key input came back as (16, 239, 11)). So when
+differently every run and the video model reproduces
+the input colour almost exactly. So when
the flat corners are a green/magenta key at *any* brightness (`--key auto`, the
default; `--key green|magenta` to insist, refused when the corners are not that
family), the still's background is repainted to the **exact declared key** and the
-padding is that same pure key. The repaint mask is the `cutout` chroma matte's own
-alpha-0 set — the pixels the canvas repaints are exactly the pixels `video-frames` will
-erase, and the subject stays byte-identical. A corner that survives the matte fails loud
+padding is that same pure key. A corner that survives the matte fails loud
(the still is not on a key the engine can cut). `--key white` keeps the old behaviour: no
-chroma key, the padding is the corner colour. The report records `key`, `key_painted`
-(the colour the model actually used) and `normalized_px`.
+chroma key, the padding is the corner colour.
## 2. Clip — `sprite-gen video`
-Unchanged from [video.md](video.md): the user's own credential, fail-loud, `ftyp`-verified
-mp4. For loops, prompt for **in-place, evenly paced, returns-to-start** motion on a flat
+For loops, prompt for **in-place, evenly paced, returns-to-start** motion on a flat
chroma fill ("walks in place on a treadmill", "hop … return to the exact starting
stance … same height every time"). `video-set` carries those templates
(`MOTION_TEXT` / `VIEW_TEXT`). They describe the gait "for this body type" and never
-name limbs — the first drafts said "bipedal … knees … arms pumping", which prompted a
-quadruped and a legless blob into a contradiction (2026-09-09).
-
-A walk seen from the front or from behind, and a run seen from the front, take their own
-sentence (`VIEW_MOTION_TEXT`) instead: the steps lift and land straight forward and back
-under the body, toward the viewer or away from it "as if on a treadmill", and the body never
-turns to the side, steps sideways or crosses its feet; a walk also asks for a calm, natural
-cycle with small, even steps that never kick a leg out to the side. The body-neutral walk
-sentence asks for "an even left-right or front-back rhythm", and a character facing the
-viewer read that as stepping sideways: crossed feet, side kicks, a body turned to
-three-quarters. Measured on Grok (subscription), 480p 3 s, nine humanoid characters twice
-each, judged on frame sheets with the variant hidden: a front walk kept its facing and walked
-in 7 of 18 clips with the old sentence and 16 of 18 with the new one. Without the calm-steps
-clause it was 12 to 13 of 18, and five crossed their feet or kicked sideways. A back walk: 8
-of 10 with the old sentence, 10 of 10 with the new one. A front run: 11 of 18 and 15 of 18
-(a run keeps its stride and has no calm-steps clause). "on a treadmill" said as a place was
-sometimes drawn under the feet; "as if on a treadmill" was not. A side view and a run seen
-from behind keep the state's sentence (the second was not measured). A walk drawn at a
-three-quarter angle kept that angle in about half the clips (6 of 10) with the old sentence
-and in 5 of 10 with one that said to walk "toward the way its body faces in the image", and
-otherwise mostly turned to a side view: no sentence tried held a three-quarter view.
-
-Since 2.15.0 the walk says less. Spelling the steps out ("each one lifting and landing straight
-forward and back under the body") made some takes march in place, knees lifted to the waist and
-arms held stiff, so a front or back walk now says only that it walks naturally, which way it
-faces and that it stays in place: "walks naturally in place, facing the viewer, as if on a
-treadmill, without coming any closer" (and "facing away from the viewer … without moving any
-farther away"). On one character, 480p 3 s on the API, two clips per sentence: the 2.13
-sentence lifted the knees to the waist in one of two; "walks naturally" swung the arms, kept the
-knees low and kept facing the viewer in both; a third sentence that asked for low heel-to-toe
-steps and a loose arm swing kept the feet low but shuffled. Two clips each is a small sample:
-the default is generic on purpose, because how a character walks (high steps, a stroll, a
-march) is the caller's to say. The front run keeps its sentence.
-
-Since 2.16.0 every walk and run takes that form, from every view: the side walk "walks
-naturally in place, as if on a treadmill, without moving across the screen" (it said "moves in
-place on a treadmill" as a place and asked for "an even left-right or front-back rhythm"), the
-side run "runs naturally in place …", and the front and back runs "runs naturally in place,
-facing (away from) the viewer, as if on a treadmill …" (the front run spelled its strides out
-and said "toward the viewer" and "without coming any closer" in one clause). On one character,
-480p 3 s on the API: the front run kept facing in 2 of 2, the side run ran in 2 of 2, the back
-run kept facing away in the one clip whose frames passed; the side walk walked in 2 of 2.
-
-Since 2.17.0 there are two three-quarter views, `front_diagonal` and `back_diagonal`: turned to the
+name limbs.
+
+There are two three-quarter views, `front_diagonal` and `back_diagonal`: turned to the
right, the way an isometric game's character walks down and up to the right (turned over, they face
left; a character with an item on one side has them drawn facing left instead, see
-[handedness](#handedness--an-item-on-one-side)). A walk or run in one says where it heads on the screen in those words: "walks naturally in
-place, as if on a treadmill, heading diagonally away from the viewer toward the upper right, like a
-character walking up and to the right in an isometric game, without moving across the screen. It
-keeps the exact three-quarter back angle of the image the whole time: its back stays turned toward
-the viewer at that angle and its face stays hidden. It never turns into a side view." (and "toward
-the viewer and to the right … three-quarter front angle" for the front one). It is filmed pinned to
-its first frame (`PINNED_GAIT_VIEWS`, `pins_last_frame`) with the return sentence, and cut as any
-walk (`--anchor motion-auto`). The clip's view sentence points at the image ("seen from a
-three-quarter back angle, turned exactly as in the image"); a still drawn at a diagonal from another
-picture takes `STILL_VIEW_TEXT` instead (`still_view_text`), which says that the whole body turns
-about 45 degrees, what that angle shows of the chest or back and of the legs (the next paragraph),
-and which way the feet point — told less, a three-quarter back view came out as a
-side view or looking back over the shoulder. Measured on the API, 480p 3 s, pinned, five humanoid
-characters twice each, judged on frame sheets: the front and the back diagonal walk kept their angle
-in 10 of 10 each; "toward the way its body faces in the image" kept the front one in 4 to 5 of 5 and,
-on another character, the back one in 0 of 2. Idle and attack keep their angle in a diagonal (4 of
-4). A diagonal run is weaker: 2 of 4 kept the angle, the others turned toward a side view.
-
-**What a diagonal still shows of its turn.** Through 2.36.0 the diagonal still sentences said only
-the turn, the head and the feet ("the whole body and head turned about 45 degrees … the feet
-pointing toward the lower right"), and a still that turns only its head and shoes, the chest (back)
-and the legs standing as from the front (straight behind), meets those words. The sentences now say
-what the angle shows: not a front (back) view with only the head turned; the middle of the chest
-(back) and of the waist about three quarters of the way across the body toward its far edge; the
-shoulder and side nearer the viewer seen broad; the far shoulder and arm partly hidden behind the
-body; the legs at the same angle, the far foot set a little higher and partly behind the near leg;
-and not to follow a reference picture's angle. The far side of a front diagonal is the side it
-faces, of a back diagonal the other one, so `STILL_VIEW_TEXT` takes `{other}` (the side opposite
-`{facing}`) beside `{facing}`, and facing left is the same sentence with the two sides swapped. The
-clip's view sentence is unchanged: a clip starts from the still. The body plan's sentences
-(`STILL_VIEW_TEXT_ANY_BODY`) are unchanged too: they count no chest, shoulders or feet and take none
-of these clauses. The words were chosen by a before-and-after comparison on the still model; its
-measurements are kept in private evidence and none is recorded here.
-`tests/gen/test_prompt_freeze.py` holds the old words and the new (`MEASURED`): a further rewording
-fails there until it is compared again ([prompt-assembly](prompt-assembly.md)).
-
-A front or back still redrawn from a picture seen from another side has its own still sentence too:
-with the clip's one line ("seen from the front, facing the viewer directly"),
-a front still redrawn from a side picture could keep part of the picture's turn, the feet frontal
-and the head and chest turned a little toward the side the picture faces. `still_view_text("front")`
-says the whole body and head face the viewer squarely, the chest, hips and toes point straight at
-the viewer, the face is centred between both ears, and it is not turned toward either side even
-when a reference picture shows the character from another angle; `still_view_text("back")` says the
-same from behind, with the face hidden and not looking back over the shoulder. The sentence is used
-whatever the reference's view: a caller does not always know it (an uploaded picture), and on a
-front reference it changed nothing. The clip keeps its one line, since a clip starts from a still
-already drawn at its view. Measured on codex `image_gen` (subscription), five humanoid characters,
-three takes per arm, layout guide on, judged blind on full-resolution crops and with an eye-offset
-metric: from a side reference the old line already drew a frontal face in 15 of 15 by eye (the turn
-did not reproduce on this model), the new sentence in 15 of 15; from behind, both drew a straight
-back in 15 of 15; from a front reference, the old line 14 of 15 and the new 15 of 15.
-
-An attack is one timed strike, not a repeat. `MOTION_TEXT["attack"]` asks for one attack: a windup
-(about 0.5 s), one strike in front (about 0.25 s), a held impact pose (about 0.3 s) and a recovery
-to the exact starting stance (about 0.5 s), then `HOLD_TEXT["attack"]`:
-every grip stays the one the image shows — one hand stays one hand, both hands stay both hands,
-nothing let go or switched to the other hand — a hand the strike does not use stays where it is
-drawn with whatever it holds (a shield, a lantern), and the body never turns. Naming one hand
-for a weapon the still draws in both hands made the clip let go and grab again mid-attack.
+[handedness](#handedness--an-item-on-one-side)).
+
A caller's own motion paragraph (`build_prompt(motion=...)`) gets the same `HOLD_TEXT` sentence
after it, once: a request interpreter writes its motion before the still
exists and cannot know where the other hand's item is drawn, so it writes the choreography and
-the engine says what stays put. Its template
-(`ACTION_COMMON_TEXT`) drops the "evenly paced" line, keeps what the subject holds inside the
-frame, and asks for crisp frames without motion blur. `video-set` asks attack clips for 2 s
-(`STATE_DURATION_SECONDS`; every other state keeps 3 s, and `--duration` overrides every state)
-and pins the clip to end on the frame it starts from: `--last-frame` is the canvas itself
-(first-last mode, see [video.md](video.md)), so the strike has to come back to the still. That
-clip is stance -> strike -> stance, so it is cut whole like an idle (`--cycle pinned`,
-`PINNED_LOOP_STATES`): the loop starts on the ready stance and never is a fragment of the strike
-or a seam between two strikes. Asked for the same attack twice and cut by the one-shot or period
-search, a clip gave loops that started mid-strike, held both strikes, or kept only the held pose;
-asked for one attack in 3 or 4 s, it held the impact pose for about half the clip.
-
-An idle holds its feet and is pinned too. `MOTION_TEXT["idle"]` keeps both feet planted flat for
-the whole clip, limits the motion to breathing, a settle of the arms, hair and loose cloth and
-one blink, and names walking and marching in place as what not to do — a side-view full body
-asked for "a subtle weight sway" and an evenly paced loop tends to step in place. Its template
-(`PINNED_LOOP_TEXT`) replaces the "evenly paced motion so the animation loops" line with the
-return: the last frame comes back to the exact pose of the first. `video-set` pins idle clips
-to the canvas (`PIN_LAST_FRAME_STATES`) and, because such a clip starts and ends on the same
-frame, cuts it with `video-loop --cycle pinned` (`PINNED_LOOP_STATES`) instead of searching
-it for a repeat.
+the engine says what stays put.
`build_prompt(direction, state, character, facing, motion=...)` takes a caller's own motion
paragraph — whole sentences about the subject, such as a request interpreter writes per
@@ -243,38 +83,9 @@ rules stay the engine's, and an attack keeps its `HOLD_TEXT` sentence after the
walk or run gets `GAIT_HOLD_TEXT` for its view after the paragraph instead: it stays in place as
if on a treadmill and keeps facing the viewer, away from the viewer or `{facing}` the whole time,
so a caller describes the gait (a sneak, a march, a lazy stroll) and the engine keeps it on the
-spot. On one character, one clip each: a march lifted the knees high as asked and stayed in
-place, a lazy stroll seen from behind kept facing away, and a tiptoe sneak kept facing the viewer
-but read only as a slightly hunched walk.
-
-`build_prompt(..., pinned=True)` says the clip is pinned to end on its first frame, so any state
-gets `PINNED_LOOP_TEXT` (the return to the first pose) instead of the evenly paced repeat; left
-out, only `PINNED_LOOP_STATES` do. A caller that retries a walk pinned after no cycle was found
-says True; two such front-walk clips closed on their first frame (seam 0.12 and 0.24 of an
-ordinary step).
-
-`build_prompt(..., model=...)` names the clip model. **A Lite walk is calmed**: for
-`grok-imagine-video-1.5-lite` (`LITE_VIDEO_MODELS`) the built-in walk sentence is followed by
-`LITE_WALK_TEXT` — a slow, relaxed walk, small low steps, a gentle arm swing close to the body, no
-bounce, never running. Lite read "walks naturally" bigger than Pro: long, bouncy steps and a wide
-arm swing, a run more than a walk (2026-10-03, one SD character in five views, two takes each);
-with the clause every view walked. A caller's own walk paragraph is left as written. **A Lite
-back-diagonal walk also holds its head** (`LITE_HEAD_TEXT`, after the calm clause): its head swayed
-2.7–3.8 % of the body height side to side against Pro's 0.88 %, and with the sentence four takes
-swayed 1.7–3.1 % (best 1.84 %). It was measured in that view only, so it is said in that view only.
-The measured sentence ended "only the legs, arms and the end of the ponytail move"; the engine's
-says "the ends of the hair", since most characters have no ponytail. Pro prompts are unchanged.
-
-**A front or back walk starts mid-step.** From a standing still the clip model makes the first
-step itself and walks askew — the feet drawn to one line under the body, or the body turned
-three-quarters: 1 of 14 front clips walked straight from a standing still, 14 of 16 from the same
-characters redrawn mid-step (2026-10-02, four characters, blind judged; three rewordings of the walk
-sentence kept 0 of 14 from a standing SD still). `WALK_START_TEXT[direction]` is the redraw sentence for the front and the
-back — the same 2D sprite, same design, caught mid-step with one foot planted under its hip and
-the other lifted a little under its own, hips and shoulders square, arms swinging gently — and
-`walk_start_prompt(direction, key)` adds the background line for a green or magenta key
-(`starts_mid_step(state, direction)` says which clips need it). The design is the reference
-image's to keep: the sentence is drawn with the base still attached. `video-set` does this before
+spot.
+
+**A front or back walk starts mid-step.** `video-set` does this before
the canvas (`--walk-start redraw`, the default): one `sprite-gen gen --ref <base>` call per front or
back walk, on the base's own key, kept as `walk-start.png` with its report and reused while the
prompt and base are the same; a base on no chroma key is refused with `--walk-start as-given`, which
@@ -282,64 +93,26 @@ films from the base itself. Side and diagonal walks, and every other state, film
### A body that is not a person — `--body-plan`
-The measured sentences above were measured on people, and five of them name what only a person has:
-the Lite walk calm swings the arms (`LITE_WALK_TEXT`), the Lite back-diagonal head hold moves the
-arms (`LITE_HEAD_TEXT`), the idle plants both feet and settles the chest, shoulders and arms
-(`MOTION_TEXT["idle"]`), the front or back mid-step redraw puts one foot under each hip with the
-arms swinging (`WALK_START_TEXT`), and the view sentence the still is drawn with points the chest,
-hips and the toes or heels of both feet at the viewer, or the backs of the shoes (`STILL_VIEW_TEXT`). Said of a horse, a pig or a dog, they walk it on a person's legs or
-stand it up on two. The walk and run sentences themselves name no limb (since 2.0.0's "`video-set`
-motion templates no longer assume a biped"); these came later and were said to every body.
-
`video-set --body-plan`, `video-prompt --body-plan`, `gen --direction --body-plan`, `prepare
--body-plan` and
`build_prompt(body_plan=...)`, `walk_start_prompt(body_plan=...)`, `still_view_text(body_plan=...)`,
`gen.still_prompt(body_plan=...)` name what the subject stands on (`sprite_gen/video/body_plan.py`):
`biped` (the default), `quadruped` or `legless` for the character, or one `<figure>=<plan>` per figure
-of a scene (`--body-plan "the man=biped" --body-plan "the horse=quadruped"`). No body plan, or one
-biped, keeps every prompt byte for byte. Any other body gets:
+of a scene (`--body-plan "the man=biped" --body-plan "the horse=quadruped"`). Any other body gets:
| Sentence | for a body that is not one biped |
|---|---|
-| after the motion sentence (or the caller's `--motion`) | what it stands on (`body_plan.text`): "It stays on all four legs, as in the image, and never rises onto its hind legs." / "It has no legs, as in the image, and never grows legs or feet." / "Each figure keeps the body it has in the image: the man on two legs; the horse on all four legs, never rising onto its hind legs." |
-| a walk or run seen from behind | after what it stands on, `BACK_GAIT_TEXT_ANY_BODY`: "Its body stays level, square to the viewer and straight the whole time, never turning or angling to either side, so neither side of it comes into view, and it does not sway from side to side; any tail stays raised where it is in the image, only its tip swaying a little." (a scene: every figure). A four-legged back walk turned until a flank showed and swayed; with this and the still drawn square (below) it held square, and without the tail clause its tail swung on its own beat and the walk found no loop (2.38.0). A person's back walk is unchanged |
-| idle | `IDLE_TEXT_ANY_BODY`: the same stillness, standing or resting as in the image, no feet counted, no chest, shoulders or arms |
| attack | `ATTACK_TEXT_ANY_BODY`: the same timed strike "with what it is already holding, or with its own body if it holds nothing", then `HOLD_TEXT_ANY_BODY["attack"]`: anything it holds stays held the same way, a part the strike does not use stays where it is drawn, no hand counted. Which part strikes (a bite, a head-butt, a forefoot) is not guessed: a caller who knows says it with `--motion`, which gets `HOLD_TEXT_ANY_BODY` after it |
-| Lite walk calm | `LITE_WALK_TEXT_LEGGED` (no arm swing; never trotting or galloping) or, with a figure without legs, `LITE_WALK_TEXT_LEGLESS` (no steps or feet) |
-| Lite back-diagonal head hold | `LITE_HEAD_TEXT_ANY_BODY`: what moves is what it moves on and its loose ends (a tail, a mane, hair) |
-| the still's view sentence (`still_view_text`, `gen --direction`) | `STILL_VIEW_TEXT_ANY_BODY` for the front, back and diagonal views (where the body and head point; no feet, chest, hips, shoulders or shoes; the back also square and symmetric left to right, the head centred, neither side showing more, any tail from the middle, 2.38.0), the side view's `VIEW_TEXT` as it is, each ending in what it stands on (`body_plan.still_text`): ", standing on all four legs, not rearing onto its hind legs" / ", resting on its base without legs, never growing any" / ", each figure with the body it has: the man on two legs; the horse on all four legs, never rising onto its hind legs" |
-| front or back mid-step redraw | `WALK_START_TEXT_ANY_BODY`: one leg lifted, the others planted, then what it stands on; a body without legs has no step to catch and films from its base (`starts_mid_step` is false, `video-prompt` gives no `start_still`) |
Only the biped sentences were measured on clips; the others say no part the body lacks and are not
-yet measured. `--handed` keeps its own sentences (its arm sentences are for an item on an arm).
-`video-set`, `video-prompt --json` and `gen`'s `extra.view` record the plan as `body_plan`. An app
+yet measured. An app
that draws the still itself with `still_view_text` and films with `build_prompt` passes the same
`body_plan` to both: the clip starts from that still.
#### The sheet rows — `prepare --body-plan`
-The rows `prepare` writes for an image model (`prompts/<state>.txt`, [atlas workflow](atlas-workflow.md))
-were measured on people too. The walk and run rows moved "body, arm, leg, hair, and prop", the front and
-three-quarter-front walks "alternating leg, arm, shoulder", the diagonal runs traded "foot-contact phases"
-of "the left and right legs", the wave was "arm pose only: arm down, arm raised, hand tilted" (its default
-action "friendly hand wave gesture"), every row's anchor lock spent its motion on "arm counter-swing" and
-turned "the body, feet, shoulders", and a diagonal row read its facing by "shoulder overlap, hand/foot
-placement". `prepare --body-plan` (the same plans and scene form; repeatable; over the request's
-`body_plan`) gives a body that is not one biped:
-
-| Row sentence | for a body that is not one biped |
-|---|---|
-| walk, run, `running-right` / `-left` (`STATE_REQUIREMENTS`) | `STATE_REQUIREMENTS_ANY_BODY`: locomotion through "the movement of the body, whatever it moves on, loose parts such as hair, a mane or a tail, and props only" |
-| `frontwalk`, `45_frontwalk` | "alternating steps of whatever it walks on and body-height changes"; "the contact and passing poses" |
-| the diagonal runs | "alternating contact phases of whatever it moves on so the two sides clearly trade forward reach" |
-| wave | the one side that lifts, as the clip's wave does (`MOTION_TEXT["wave"]`): "lowered, lifted, swaying, returning", the body planted where it stands or rests; the default action `DEFAULT_ACTIONS_ANY_BODY["wave"]` where the request names none |
-| anchor lock (`ANCHOR_LOCK`) | `ANCHOR_LOCK_ANY_BODY`: "the contacts of whatever it moves on, body height, body lean, head bob, the bounce of hair, a mane or a tail"; rotate "the body, face angle, and gaze"; "step phase", "contacts" |
-| a diagonal row's facing | "the silhouette of hair, a mane or a tail, the overlap of near and far parts" |
-| every row, last state requirement | what it stands on (`body_plan.text`), as after a clip's motion sentence |
-
The run records the plan in `sprite-request.json` as `body_plan` (absent without one), and a run
-prepared again from that request keeps it. No body plan, or one biped, writes every row prompt as
-2.32.0 did, byte for byte (`tests/fixtures/prepare-rows-v2.32.0.json.gz`, `tests/gen/test_prompt_freeze.py`).
+prepared again from that request keeps it.
The new rows are not yet measured on an image model. A request's own `action` is its own words and is
never rewritten.
@@ -379,48 +152,25 @@ The set stage is the same step `video-set` runs after its loops are cut (`--alig
default): one `--loop-dir` per direction of the same walk or run, one `--view` each in the same
order, so that every loop starts as the same own foot lands wherever its view can tell the feet
apart. A frame that falls between two source frames is made by RIFE, and the command fails where one
-is needed and RIFE is not installed; `--between nearest` makes none. A frame RIFE made that melted
-(lost its outline where legs crossed too far) or carries a ghost (a band of part coverage) is
-replaced by the nearer source frame and named, and a filmed frame left half drawn between two
-drawings gives way to a clean source frame beside it (`--between auto`, the default; [loop
-repair](loop-repair.md) section 4, "The ghost screen"); a made frame that may cross-fade two
-drawings inside its outline is kept and named to look at (section 4, "A cross-fade inside the
-silhouette"). A loop whose view cannot
+is needed and RIFE is not installed; `--between nearest` makes none. A loop whose view cannot
tell its feet apart — or tells them apart by too small a margin (`foot_why` `low-margin`) — starts
on its larger strike and is listed under the report's `unnamed_feet` with its two strike frames in
`cycle/`: look at the first, say which own foot lands there, and run the same alignment again with
`--foot <loop>=left|right` — that loop alone turns to start on the set's foot
(`start_foot_source: "given"`).
-`--character` or `--motion` words that turn the subject another way than `--facing`, or put a
-`--handed` item on its other side, come back in `warnings`; the prompt is the same either way
-([prompt-assembly](prompt-assembly.md)).
-
`video-prompt --json` also gives the duration (the state's own, as `video-set`), whether the clip
ends on the canvas (`last_frame`), the loop cut (`cycle`) and the canvas, clip, frames and loop
commands with placeholders; a front or back walk adds `start_still`, the mid-step redraw `video-set`
-makes before its canvas (`sprite-gen gen --ref`, your image provider). Its `loop` command names no
-`--anchor` and it lists no set command: add `--anchor motion-auto` for a walk or run, and run
-`video-cycle-align` for a set, as above. `--character`, `--motion`, `--model` and `--body-plan` reach the
+makes before its canvas (`sprite-gen gen --ref`, your image provider). `--character`, `--motion`, `--model` and `--body-plan` reach the
prompt as they reach `build_prompt`. What the ZCRE route supports:
| | Through ZCRE's MCP |
|---|---|
| Model | `grok-imagine-video-1.5` (Grok Imagine Pro), image-to-video only. There is no Lite model there, so `LITE_WALK_TEXT` never applies. |
| End frame | None. `--no-last-frame` refuses what `video-set` films pinned — idle, attack, a walk or run in a diagonal (`pins_last_frame`). `--unpinned` films one anyway, with a warning: the prompt asks for an evenly paced repeat (an attack for one strike), the loop is searched instead of cut whole, and it may not close. Walk, run and jump from the side, front and back are the route. |
-| Resolution | 480p, 720p, 1080p. The clip keeps the canvas's ratio (a 1024² canvas came back 544² at 480p and 960² at 720p). |
-| Audio | Always an AAC track; there is no option to leave it out. `video-frames` reads the picture alone, records `audio_streams`, and the loop outputs carry no sound. |
-| Cover image | The mp4 also holds a one-frame mjpeg cover (`attached_pic`); `video-frames` skips it (`cover_streams`) and reads the first video stream that is not one (`stream_index`). |
-| Picture | H.264 `yuv420p` (4:2:0), 24 fps, as a `sprite-gen video` clip; the frames report records `codec` and `pix_fmt`. |
+| Resolution | 480p, 720p, 1080p. The clip keeps the canvas's ratio. |
| Side facing | `video-set`'s facing observation is not run on this route; check the still faces `--facing`. |
-| Set | `video-set`'s cycle alignment (`--align-cycles auto`) is not run on this route: once a walk or run is cut in two or more directions, run `video-cycle-align` on their loop directories, with each one's `--view`. |
-| Size | A clip here has no end frame, so a walk or run may grow or shrink as it plays: cut it with `--anchor motion-auto`, which holds the size before the search (section 4). `video-loop`'s default anchor for a walk or run, `body`, does not hold it. |
-
-Measured 2026-10-04, one side walk end to end on that route: a 1024² still, `video-canvas` (square,
-1.8 s), 720p 3 s, quoted and charged 52 credits, 33.6 s from submission to `succeeded`; the clip was
-960×960, 24 fps, 73 frames, H.264 `yuv420p` with an AAC track and a cover image; `video-frames` kept
-73 frames and no edge contact, and `video-loop --cycle auto`, at its default anchor (`body`), cut a periodic 20-frame walk (seam 0.72)
-with three frames remade by RIFE and a jolt warning (index 0.85), as a Pro walk can carry.
### Handedness — an item on one side
@@ -431,18 +181,7 @@ draw them instead, and say where the item is.
**The item, once.** `--handed "<item>=<left|right> [body part]"` names an item and the character's own
side it is on (`handedness.parse`; repeatable): `"the black smartwatch=left wrist"`. The engine works
-out where that side is in each view (`handedness.placement`):
-
-| view | own left side, turned right | own left side, turned left |
-|---|---|---|
-| `front` | the picture's right | (not turned) |
-| `back` | the picture's left | (not turned) |
-| `side` | the far side, behind the body | the near side, toward the viewer |
-| `front_diagonal` | the picture's right, far side | the picture's right, near side |
-| `back_diagonal` | the picture's left, far side | the picture's left, near side |
-
-The own right side is the mirror of every row. A side view has no picture side — both arms cross the
-middle of the body — only near and far.
+out where that side is in each view (`handedness.placement`).
**The still.** `sprite-gen gen --direction <view> [--facing right|left] --handed …` adds the engine's
view sentence (`still_view_text`, the one a diagonal or front still is drawn with) and, per item, the
@@ -454,16 +193,6 @@ falls back to mirroring a still-opposite retry: a mirror moves the item. Do not
item is on the other side — a mirrored still, or a side picture drawn the wrong way: check it with
`handed-check` first. A front or back picture, where the item's side is plain, is the safe reference.
-**The far arm of a side view.** A side view hides the far side behind the body, except for what swings
-out from behind it. A walking character's far arm comes forward of the body with every step, and what
-its wrist or hand wears shows then. So an item on a wrist, a hand, a forearm or an elbow
-(`handedness.limb`, the one table: `SWINGING_ARM_PARTS`) is said, on the far arm, to show wherever that
-arm is out in front of the body and to be hidden where the body covers it. Every other far item — on an
-ear, the head, a tail, the body, a leg, a shoulder, the upper arm — is said hidden, as in 2.22.0, and
-gets no arm sentence: a far shoulder stays behind the body as the character walks, and a leg's item
-showing as it steps forward was never filmed. 2.22.0 said every far item hidden and never named it in
-the clip, and a watch on the far wrist was then in no frame of the side walk.
-
A clip keeps what its first frame shows and makes up what it hides. For a walk or run with an item on
the far arm, draw the side still **mid-stride with both arms in view**, and say the pose in your
prompt — the engine's sentence says where the item shows, not how the character stands:
@@ -475,68 +204,21 @@ prompt — the engine's sentence says where the item shows, not how the characte
`video-prompt --json` names this under `still_needs` (and on stderr), and `video-set` under each
item's `still_needs`, whenever a walk or run has an item on the far wrist or hand of a side view.
-**The clip.** `video-prompt --handed …` and `video-set --handed …` end the clip prompt with where the
-item stays (`build_prompt(handed=...)`). The clip starts from a still already drawn with the item in
-place, so the sentence anchors to the image and names the item once, positively, where it shows: "The
-black smartwatch stays on the wrist at the right of the picture, nearer the viewer, for the whole clip,
-exactly as in the image, and on no other wrist." In a side view's walk or run with an item on a wrist,
-a hand, a forearm or an elbow, the arms are said to swing (`handedness.ARMS_SWING_TEXT`: "Both arms
-swing back and forth with each step, opposite to the legs."), and then:
-
-- on the far arm: "The black smartwatch stays on the wrist that wears it in the image, on the arm on
- the far side of the body, and shows each time that arm swings forward; the arm nearer the viewer
- stays bare, exactly as in the image."
-- on the near arm: "The black smartwatch stays on the wrist that wears it in the image, on the arm
- nearer the viewer; the other arm, on the far side of the body, stays bare both where it shows behind
- the body and where it swings out in front of it."
-
No sentence holds an arm still: the arms swing with the walk. The other arm is said bare, never as a
-list of what it must not wear — a clip prompt that lists that draws it there. Where nothing brings the
-far side into view — any other part, or a state that does not step (idle, attack) — the
-item is not named at all: "The wrist nearer the viewer stays bare, exactly as in the image, for the
-whole clip." A side view names the near part "nearer the viewer", not "in front of the body": in a
-mid-stride still the far arm is the one in front of the body. Items on the same wrist share one sentence, and with an item on each wrist neither is
-called bare. `handed-check --strap` finds a bare band that a clip still grows on the other arm. A front
-or back walk's mid-step redraw (`walk_start_prompt`, `video-prompt`'s `start_still`) ends with the
-still's handedness sentences too: redrawn from the base alone, the model may put the item on the other
-wrist.
+list of what it must not wear — a clip prompt that lists that draws it there.
**Left-facing views, drawn.** `video-set --facing right,left` films every side and diagonal view both
ways, each from its own still: `--base side@right=E.png --base side@left=W.png --base
front_diagonal@right=SE.png --base front_diagonal@left=SW.png …` (front and back once, as before). A
turned view with no still for one facing is refused, naming the `gen --direction … --facing …` call
-that draws it — the engine never turns one over for the other. Items are named `side-left-walk`, the
-table reads `side (left)`, each side still is inspected for its own facing into its own copy
-(`side-left.facing.png`), every gait is aligned across all eight (`--align-cycles auto`), and a
-left-facing diagonal is canvassed, prompted ("heading diagonally toward the viewer and to the left")
-and cut (`video-loop --facing left`) as a left one. One facing keeps the item names and table as before.
+that draws it — the engine never turns one over for the other.
**The check.** `sprite-gen handed-check --strip <loop>.strip.png --direction <view> [--facing …]
[--state walk] --handed … --marker '#RRGGBB'` (or `--image`, `--frames-dir`) finds the item by a saturated colour
-nothing else on the character has — a watch's screen — and checks every frame:
-
-- a view with a picture side: every blob of that hue is on that side of the body's centre (the mean x
- of its opaque pixels);
-- every view: the item in at most one place (blobs within 2 % of the body height are one; one smaller
- than a quarter of the largest is a speck — a clip's colour blocks tint outlines toward the item's
- hue — recorded and drawn, not judged);
-- the near side of a diagonal view: the item shows in at least half the frames; of a side view, in at
- least three quarters — a near arm is in view the whole walk, a far arm's item for the half of it the
- arm is forward, and in a side view that share is what tells the two apart. Against `--reference` a
- frame counts only when the item is more than a sliver (its largest blob larger than half the item
- seen whole);
-- the far side of a side view, an item on a wrist, a hand, a forearm or an elbow (`handedness.limb`):
- every blob is out in front of the body — on the facing side of the body's centre by at least a tenth
- of the body's height (`far_in_front`). An item that shows at or behind the centre is on the near arm,
- the wrong one. With `--state walk` or `run` it must also show in at least a quarter of the frames
- (`far_shown`); without `--state`, or for a state that does not step, that is reported unchecked.
- Against `--reference` a sliver is not judged for where it is;
-- the far side of a side view, any other item (an anklet, a shoulder piece, a pin on the head): no
- blob larger than half the item seen whole on `--reference` (a keyed front or back picture;
- `far_hidden`).
-
-Without `--reference` the size rules are not checked; the report says so (`far_hidden` /
-`near_whole`: `checked: false`) and a frame counts as shown by any blob.
+nothing else on the character has — a watch's screen — and checks every frame.
+
+With `--state walk` or `run` it must also show in at least a quarter of the frames
+(`far_shown`); without `--state`, or for a state that does not step, that is reported unchecked.
`--strap '#RRGGBB' --zone TOP,BOTTOM` adds the item's band seen without its marker: pixels of that
colour in those rows of the body (fractions of its height), eroded so outlines drop out, wider and
@@ -546,85 +228,20 @@ the zone is the character's wrist height. `--board` draws every frame with its b
expected, red not) and bands boxed, for what pixels cannot judge: an unmarked item, an item hidden on
the wrong hand. The exit code is 1 on a failure.
-A set that made its left-facing views by mirroring fails: a front view turned over puts the item on
-the wrong side; a side walk facing right (the item on the far arm, in view while that arm is forward)
-turned over shows it in too few frames for a near arm; one facing left (the item on the near arm,
-crossing the body) turned over shows it behind the body's centre; a diagonal turned over moves it
-across the picture. `tests/qa/test_handed_check.py` draws each view as it should look, passes it, and
-fails it turned over.
-
## 3. Frames — extract, key, check the edges
-`ffmpeg` extracts every frame; the clip's real fps is recorded (never assumed). Each
-frame goes through the same `cutout` engine imported stills use (`--key auto` reads
-the corners; green/magenta route to the extract matte). The matte keys from the
-background colour **as the model painted it**, not only from the pure key: the flat
-border colour is detected per frame (`extract.detect_background_key_rgb`, the mode of an
-RGB histogram over the corner/border samples that are the key's hue family) and a pixel
-is erased when it is within the key radius of *either* the pure key or that painted
-colour. The 96 radius is unchanged — what moved is its centre. Before this (2026-09-11)
-a (8, 162, 24) green sat at distance 96.38 from pure green while (7, 163, 24) sat at
-95.34, so a clip was keyed half-and-half pixel by pixel and the edge check read the
-leftover background as a clipped subject. The report records `chroma_key_painted` per
-frame.
-
-**The border is classified by a looser rule than the interior** (2026-09-12). The
-detector's "hue family" test used to be `extract.is_key_family`, the interior rule, whose
-two-channel balance (the dimmer keyed channel ≥ 0.8 of the brighter) exists to keep hot
-pink (250, 77, 150) and purple (213, 112, 246) alive *inside* the subject. Grok paints
-`#FF00FF` as (216, 46, 147) / (225, 52, 155) — blue/red ≈ 0.68 — so that rule said "not
-the key" for a colour that filled the whole border, the detector fell back to the declared
-key, and at ~120 from pure magenta the entire background survived. A flat border is
-already evidence of *background*, so the border rule `extract.is_border_key_candidate`
-drops the balance and keeps the hue signature: every keyed channel lit (>= 64), the
-darkest unkeyed channel dark (< 64) and under 35 % of the brightest keyed channel, and the
-brightest unkeyed channel under half of it, so a green screen that leans toward cyan or
-yellow, such as the studio green (0, 177, 64), is the key while a colour as near cyan or
-yellow as green is not. It is a superset of the interior rule (family union signature), so
-nothing the old detector found is lost, and hot pink and purple fail on their lit green
-channel, which is magenta's only unkeyed channel. Where the old detector found a colour,
-the detector finds the same colour, since the samples only the lean admits are read only
-when the rest make up less than 12% of the samples, and only where the declared key's own
-cut would leave the border's one background they give. One
-function classifies the border everywhere — `detect_background_key_rgb`, `cutout --key
-auto`, `video-canvas --key` and the edge-contact split below. The interior rule is
-untouched. And because the painted colour's authority is border evidence, its erase ball
-is bounded by the background it came from: it erases the signature pixels plus whatever
-inside the ball is 8-connected to them (the antialiased rim, whose blend with a lit
-subject colour lifts the unkeyed channel over the bar), never an isolated look-alike patch
-inside the subject — hot pink sits 46 from Grok's magenta. The declared key's ball stays a
-colour ball, position-blind.
-
-Two consequences worth knowing. Dark outline halo (the antialiased blend between subject
-and a dark-painted key) is now erased with the background — on the three 2026-09-11
-walk clips that was outline pixels only (0 newly opaque, interior holes ≤ 7 px per
-frame, seam ratios moving in the third decimal, periods and start frames identical).
-And **a key-family subject colour is at more risk the darker the painted background**:
-the erase ball follows the detected key, so on a still painted (20, 120, 25) a dark
-olive (40, 70, 35) inside the subject (distance 54.8) is erased, while the same olive
-survives untouched on (8, 162, 24), (5, 200, 10) or pure-key backgrounds. Choose the key
+`ffmpeg` extracts every frame; the clip's real fps is recorded (never assumed).
+
+Choose the key
away from the subject's hues ([chroma-alpha.md](chroma-alpha.md)) — that rule now covers
the painted key's darker variants too.
-Every keyed frame first has its **specks** erased (`drop_specks`): a piece of the frame — its
-opaque pixels, corners joining them — under 1 % of the frame's largest piece, the body
-(`SPECK_MIN_FRACTION`, at least 8 px), and more than a tenth of the body's height away from it
-(`SPECK_APART`). That is a fleck the model drew drifting across the background, which survived the
-matte. Small pieces near the body stay: the outline's loose pixels, a shadow drawn under a shoe,
-a part of a shoe the matte cut loose. A frame with no speck is not written again; each report
-row says how many its frame lost (`specks`) and the report totals them (`specks.dropped`,
-`specks.frames`). Without this a fleck that crossed an edge band in one frame was read as the
-subject framed too tight, and `--anchor motion-auto`, which never cleans a frame, kept it in
-the loop's cells and widened them to reach it.
-
The report also carries per-frame alpha coverage and an **edge-contact check**, read after the
specks are gone: any opaque pixel in the top/left/right 4-pixel bands is contact. Each contact pixel is
classified by its *raw* colour and the piece of the keyed frame it is in (its opaque pixels, corners
joining them, as the specks are read): the declared key's hue family in a piece with nothing else in
it is **`residual`** (background the matte did not erase); anything else is **`subject`** — a
-key-tinted pixel joined to the subject included, since a body that reaches a band brings its
-antialiased rim, the key blended into it, there first, and on a frame where only that rim is in the
-band, read by its colour alone, the clip was refused as leftover background. The two
+key-tinted pixel joined to the subject included. The two
defects fail with different messages: residual-only contact points at `video-canvas`
(normalize the base still and regenerate); subject contact means the model framed too
tight and points at a taller/wider canvas. When both occur the message names both.
@@ -634,10 +251,7 @@ message with a small residual count is still a framing problem, not a key proble
`--allow-edge-contact` turns the whole check off. `--allow-subject-edge-contact`
accepts only the subject at the edge — the clipping a `--fit tight` canvas chooses —
and still fails a frame where the key alone reaches the edge, which is a keying defect
-whatever the framing. A frame where the subject touches the edge passes with the
-key-tinted pixels beside it (fringe, or the key reflected on metal): the same reading the
-refusal message gives a mixed contact. Contacts stay in the report either way, with `edge_policy` saying which rule
-applied (`border`, `subject-allowed`, `off`).
+whatever the framing.
**A drawing cut by its own frame** (2.46.0). A bust or half-length drawing runs off the frame
itself (its sleeve is cut off at the left, its hair at the top). In every frame of its clip the
@@ -716,41 +330,7 @@ The still the clip was made from settles it. `video-frames --spill` takes:
`video-set` passes `--spill auto` with each item's `canvas.png` as the reference (override
with `--spill small|full`), so a green-free character loses the reflections while a
-character that *is* green keeps its colour. The decision and its numbers are recorded in
-the frames report under `spill`. The correction is the engine's own `despill_color` blend
-model (observed = (1−k)·subject + k·key, solved for the subject), so colours without key
-tint are untouched. `small` keeps the conservative tint threshold of 40; `full` lowers it to 8.
-For `full`, a key hue requires every keyed channel to exceed every non-keyed
-channel: `G − max(R, B)` for green, `min(R, B) − G` for magenta. This same
-excess selects pixels for correction and drives the `auto` reference check, so yellow/cyan
-are not mistaken for green, or red/blue for magenta. The average-channel tint
-metric remains unchanged in `small` and the edge matte.
-
-The blend fraction still uses the linear average-channel tint, not hue excess.
-Full correction recovers mean brightness but does not amplify colour differences
-within the keyed or non-keyed channel group. Otherwise a small red/blue imbalance
-can become a strong secondary cast when much of the observed colour is key light.
-This is bounded colour recovery, not reconstruction of the original material:
-blue or purple already present without the key hue remains unchanged.
-
-The `auto` reference test discounts dark pixels (all channels below 64) in the
-matte's 4-pixel edge-unmix band. Such contamination along an antialiased outline
-is weak evidence of an intentional material. Bright green/magenta accents still
-count even on an edge. The report names the metric, band and dark-only policy.
-Genuine key-coloured material above the 0.5% share still keeps the conservative
-mode. Tiny accents or dark, edge-only material can fall below that reference test; use `--spill small` when preserving those is essential.
-
-The reference is keyed on its subject window only. A canvas padded for motion room
-(`video-canvas`) is mostly key, and the matte's memory grows with every pixel it keys,
-so keying the whole canvas made the judgment cost grow with the padding: about 0.14 GiB
-per megapixel, past 4 GiB for a 30-megapixel canvas. The window is the box of pixels the
-hard cut cannot erase (farther than 96 from the declared key, and not the painted key's
-own colour), plus one keyed pixel all round. The painted key is read on the whole still,
-and with that ring the window gives exactly the counts the whole still gives, so the
-decision does not change. The still itself is only decoded and read a band of rows at
-a time. A window over 6 megapixels is keyed on every n-th pixel each way instead, so no
-reference costs more than that to judge. The report records `reference_size`,
-`reference_window` and `reference_stride` (1 = every pixel of the window).
+character that *is* green keeps its colour. Tiny accents or dark, edge-only material can fall below that reference test; use `--spill small` when preserving those is essential.
### Edges: `--decontam palette`
@@ -759,10 +339,7 @@ edge are a different problem. H.264 4:2:0 has already averaged the key into the
anything one or two pixels wide, and despilling what is left turns thin red strands
orange. `video-frames --decontam palette` (also `video-set --decontam palette`) re-explains
each edge pixel as a blend of the local key background with one colour the subject owns,
-and writes that colour at the pixel's observed luma. It uses the video fit and one palette
-per clip, learned on the first frame, so edge colours cannot flicker between palettes. Within
-the edge band the edge gate reads, it gives no coverage to a pixel the matte left transparent,
-so it adds no edge contact: a clip with none under `off` has none under `palette`. The
+and writes that colour at the pixel's observed luma. The
default `off` keeps frames byte-identical. Method, guards and measurements:
[chroma-alpha.md](chroma-alpha.md#decontam--give-the-edge-the-subjects-own-colour-back).
@@ -774,10 +351,7 @@ wider than the body (a skirt, a veil, a held object). Both fail `video-frames`'s
edge-contact check — the clip was made, the frames were cut, and the run stops at the
gate. The state table now routes `cheer`, `wave` and `celebrate` to the wide canvas, and
`video-set --shape wide` forces it for every state of a batch when the costume is the
-reason. The same `--shape` is what `video-canvas` already took for a single still. The
-forced canvas is the forced-wide row (35 % above), so a jump in that batch keeps its
-head-room; an attack in it gets that row too, not its own 20 %. A walk or run gets its own wide
-row, with nothing above (section 1).
+reason.
## Video Processing Pipeline and Terminal Gate
@@ -789,88 +363,19 @@ sprite-gen video-frames --clip clip.mp4 --out-dir frames --spill auto --referenc
sprite-gen video-loop --frames-dir frames/keyed --fps 24 --state death --cycle once --out-dir out
```
-In the sequence above, replace 24 with the `fps` value from `frames.report.json`. For batch operations, `sprite-gen video-set --end-frame` takes `ITEM=PATH` (e.g., `--end-frame side-death=final.png`). With no seam gate or wrap correction, nonloop insists on `--anchor none` and `--fit state`, with no optional override to anchor; nonloop states reject non-none anchor and tight fit. See [states-and-frames.md](states-and-frames.md) for the state table.
-
-For `--cycle once`, the terminal gate searches the whole clip for the first stable terminal window of $K = \max(4, \lceil\text{fps} \times 0.2\rceil)$ frames after action departure, then ends at the window end and discards later recovery or shaking. Across the window, pairwise window distance diameter divided by median subject mass must be $\le 0.025$ (premultiplied RGBA thumbnail difference divided by median terminal subject mass), detecting jitter and slow drift regardless of canvas padding. The first frame precedes departure from the initial pose. The gate refuses clips with no action; the retained cut must have a visible body and no alpha >= 8 pixels touching any source edge, ignoring the discarded tail for that check. A named terminal state's candidate end pose is screened by its geometry on alpha >= 8 body boxes, rejecting candidates as returned starting geometry if height and width/height ratio are each within 5% of initial and bottom movement is <= 2% of initial height. `death` and `fall` require median end-window height <= 80% of initial height, while `land`, `cast`, `hurt_hold` and `transform` require changed geometry. This provides a conservative geometric screen; inspect semantic pose visually. Any other motion cut `once` — a once-hold of a word of your own ([play modes](#play-modes)), or `--cycle once` on `jump`, `attack` or another state — is screened by its drawing instead: each end-window frame is moved sideways until its body box is centred where the first frame's is, and its median distance from the first frame (premultiplied RGBA thumbnail difference divided by the subject mass, as the action departure is read) must exceed 0.05. Its body box may keep its size and floor, so a shield raised across the chest is an end pose, while the first drawing come back, in place or slid sideways, is refused as the starting pose. The report's `cycle.terminal.pose` records the screen: `profile` `ground` or `changed` with the geometry ratios, or `drawing` with `departure`, `departure_min` and `shift_px` (the sideways move taken out).
+In the sequence above, replace 24 with the `fps` value from `frames.report.json`. For batch operations, `sprite-gen video-set --end-frame` takes `ITEM=PATH` (e.g., `--end-frame side-death=final.png`). With no seam gate or wrap correction, nonloop insists on `--anchor none` and `--fit state`, with no optional override to anchor. See [states-and-frames.md](states-and-frames.md) for the state table.
-Strip and preview downsampling preserves start and end endpoints. Strip metadata includes `loop: false`, `hold_last: true`, `end_frame`, and candidate `events:[{"frame": n, "name":"motion_peak"}]`. Strip `end_frame` and event `frame` are zero-based output cell indices. Report `cycle.end_frame` and `cycle.event_frame` are keyed source frame indices. `source_cut.samples` maps each strip output cell to its keyed source frame; they are not numerically equal after trimming/subsampling. WebP previews set `loop=1`, GIF previews omit loop extension, and decoded preview verification enforces `once` behavior.
+This provides a conservative geometric screen; inspect semantic pose visually.
-In `sprite-gen video`, `--image` is the start frame and `--last-frame` is the end frame. Unpinned execution is the default when omitting terminal canvas arguments. Newly added flags are `video-prompt --end-frame final.png` and `video-set --end-frame ITEM=PATH`. Both are nonloop-only; `video-prompt` also refuses `--no-last-frame`. `video-prompt` only prints instructions, does not open/validate image, whereas `video-set` checks final canvas dimensions and corner key match initial canvas. Nonloop clip cache identity includes end image SHA256; a changed end pin cache rejects until user explicitly `--force` regenerates. Terminal stability checks remain strictly enforced with pins.
+In `sprite-gen video`, `--image` is the start frame and `--last-frame` is the end frame. Unpinned execution is the default when omitting terminal canvas arguments. Nonloop clip cache identity includes end image SHA256; a changed end pin cache rejects until user explicitly `--force` regenerates.
## 4. Loop — period first, seam second, then the gait floor
-The 2026-09-08 lesson: a single-start "most similar later frame" search lands on the
-**1.5-cycle look-alike** of a gait (legs swapped) and produces a loop that hitches at
-the wrap (side walk picked 39 frames where the period was 28; run picked 25 where it
-was 17). `video-loop` therefore:
-
-1. builds the distance matrix `D` on 96-px premultiplied thumbnails;
-2. reads the **global period profile** `P[L] = mean_j |f[j] − f[j+L]|` and takes the
- *smallest* local minimum that is within 15 % of the deepest one — exact repeats dip
- again at 2× and 3× the period, the half-period look-alike dips noticeably less;
-3. only then ranks **starts** for that period (± 1 frame):
- `seam = D[i+L-1][i]` over the mean adjacent distance inside the cycle.
- Penalise distance from 1 in log space, so a repeated pose at the wrap does
- not win just because its distance is small. For walks and runs, also compare
- corresponding frames one cycle apart in the neighbourhood of the cut: a
- quarter-cycle on either side, clipped to available source pairs. Add their
- mean distance divided by the candidate's mean adjacent distance to the wrap
- penalty. This favours a coherent repeating region over an accidental endpoint
- match, without preferring an early or late start. Other states keep wrap-only
- ranking. `cycle.selection` records the half-open source-pair range, repeat
- error, normalised error, wrap penalty and combined score; `next_frame_distance`
- retains the single-frame diagnostic. Fixed cuts do not use this ranking.
- The seam is an area measure: a thin part (a staff, a flag) that jumps at the wrap
- changes few pixels and hardly moves it. `--anchor motion-auto` also weighs the top
- of the silhouette at the wrap and chooses again when it jumps, and every walk or run
- reports that jump and warns on it ([loop repair](loop-repair.md) section 3,
- "The seam pop"). Once the top jumps, the held part is read below its top too, and a staff
- that closes only on two steps is cut two steps long — one cycle (`cycle.steps`, "The held
- side"). Where the clip shows its steps, the cut is two of them — read off the crossings of the
- feet, joined at the walk's own point, the smoothest seam first — and the search's cut is kept
- where it already is that, where the clip a cut on is the same picture though the count says one
- step and the feet stand together through most of a step (a pass it did not see), and where no cut
- of two steps closes in its place
- (`cycle.step_count`, "The step count"). Where it does not, the cut taken
- is screened for one step of a cycle twice as long, over the whole clip (`cycle.step_screen`, "The
- step screen"); nothing is cut on it, and `--steps` is the count that cuts again.
-
-This neighbourhood check measures temporal consistency, not anatomical leg
-identity. A consistently repeated malformed motion can still score well; visual
-review remains necessary when correct limb alternation matters.
-
-Windows come from the state profile (`STATE_PROFILES`). **Gait states take theirs in
-seconds**, because a stride is a fact about the body, not about the clip length: walk
-0.5–1.6 s, run 0.3–1.2 s, the ceiling capped at half the clip (a cycle must be seen twice
-to be confirmed). The other states are fractions of the clip length: idle 60–95 %
-(breathing is slow and not periodic — the lowest seam is a long window, and idle is
-exempt from the periodicity gate), jump 11–45 %. Attack keeps the 11 % floor and
-searches up to 2.5 seconds while retaining at least 0.5 seconds (and at least eight
-frames) of observed repeat context. `--min-len/--max-len` override the window — on every path that
+`--min-len/--max-len` override the window — on every path that
sets a cut's length, the gait fallback, `--steps` and the one-shot failover included; a cut outside
them fails rather than being written.
-Attack's periodicity floor is `0.15 + 0.85 * max(0, 1 - (n - lag) / lag)`:
-less than a full period of comparison requires a deeper dip. Reports include both
-available pairs and the every-other-frame profile sample count. This is a coverage
-policy, not a statistical confidence estimate. Gait windows and ranking are unchanged.
-The walk floor is low on purpose: a legless body "walks" as a fast bounce (about 13
-frames at 24 fps) while a gait is 24–28, and it is the 15 % depth rule and the gait
-floor — not the window — that reject the one-step half period (on a biped and a
-quadruped the half period dipped only 55–70 % as deep as the full one). Walk used to be
-6–31 % of the clip; at the 3 s default that ceiling was 0.96 s and put a 1.0–1.3 s
-stride out of reach (2026-09-18: one of four walks refused, another cut at a half step).
-The ceiling is a bound in seconds rather than simply "half the clip" because the
-periodicity gate measures the period's dip against the profile mean over the whole
-window, and a ceiling that grows with the clip inflates that mean until a single hop
-in a jittering stand passes as a walk.
-
-For gait states, a duration above the floor is not proof that both phases are present.
-If a local minimum near twice the chosen period is within the existing 25 % repeat-error
-tolerance and still passes the periodicity gate, the detector retains the longer candidate
-once, inside the requested window. Near-exact repeats (repeat error at most 10 % of an
-ordinary adjacent step) stay short. This is a conservative response to ambiguous harmonics:
-a genuine short gait may be shown twice, at the same source speed. It does not identify
-anatomical left/right contacts. The report records `half_period_guard.reason =
+
+The report records `half_period_guard.reason =
"ambiguous-harmonic"` and `cycle.review_recommended = true`. See [loop review](loop-review.md)
for the visual review contract and manual overrides.
@@ -883,43 +388,11 @@ hold one cycle ([loop repair](loop-repair.md) section 4) it walks at twice their
The engine does not cut it shorter. Half a gait cycle on, the legs are back in place with near and
far swapped; where the two legs are drawn alike (one colour of trousers, white fur) that one step
-and a true cycle half a drawing late are **the same picture**. Every rule tried that took the half
-as a cycle — an absolute pixel distance, the legs' step count, the pose on the motion's path — cut
-some one-stride walk or run to its half step, and the leg signal fails both ways (a heel kick
-swings the stride twice a step; a diagonal view's two steps open the feet unequally). So
+and a true cycle half a drawing late are **the same picture**. So
`video-loop` cuts the period it always cut, and only **records** what a half or a third of it shows
-(`cycle.fundamental`, `sprite_gen/video/period.py`):
-
-- each candidate is the profile's own minimum within a frame of P/2 and P/3 (`checked`: `period`,
- `of`, `divisor`, `cycles`), no shorter than the gait floor (walk 0.6 s, run 0.35 s; other states
- the window's floor — under the floor a repeat is one step, the half-period guard's case);
-- it is measured: `periodicity` (its dip below the profile's mean), `pose` (how far the frame one
- candidate on lies off the motion's own path — over the short spans (a, b) around a frame, the
- least `D[a][x] + D[x][b] − D[a][b]` — over that frame's own distance, both in playback steps;
- `off_path`, `distance`), and, for the record only, the legs' `steps` and `follow`
- (`sprite_gen/video/legs.py`, the signal the foot-strike turn reads);
-- one rule, `period.verdict`, decides (`verdict`, `why`): a candidate that repeats — dips 0.15 or
- more below the profile's mean — is a `suspect`, and the suspects are listed (`suspects`). That is
- the whole rule. Nothing says "this is a cycle", and nothing says "this is not one": the pose and
- the legs are evidence for whoever looks, never a reason to refuse. A rule that refused "another
- pose" (pose 0.8 or over) missed most two-stride loops whose second stride was redrawn a little
- differently — moved a pixel, a few per cent lighter, the foot kicked higher — because in pixels
- that is off the motion's path just as a step with the legs swapped is.
-
-`review_recommended` keeps its meaning (the ambiguous-harmonic retention above). The record is for
-the set stage: `video-cycle-align` screens every loop by the same rule, stops a set on a suspect,
-and takes one cycle out of a loop only when told how many it holds (`--cycles`, [loop
-repair](loop-repair.md) section 4). The local search of `--anchor motion-auto` records the same. A
-loop whose steps are known (`steps: 2` in `strip.json`: cut two steps long on the clip's crossings or
-so a held part closes, or cut again on a count with `video-loop --steps`) returns half way at its
-second step; the set stage
-reads that return as the step it is, not a second cycle. The screen also looks the other way there:
-a cut that may be one step of a cycle twice as long (`cycle.step_screen`, read over the whole clip)
-stops the set the same way, and only a count — `video-loop --steps 1` — cuts it again.
-The rule leans one way on purpose: a suspect costs a look, a miss a loop that plays twice as fast.
-A run's half step repeats as well as most of its strides do, so a run set is suspected nearly
-every time and stops until its loops are counted; a walk's half step is under its floor more
-often. What still escapes it is a second stride that drifts across the picture in steps of four
+(`cycle.fundamental`, `sprite_gen/video/period.py`).
+
+What still escapes it is a second stride that drifts across the picture in steps of four
pixels or more without the body anchor's ramp, and any loop whose half is under the gait floor
(a walk faster than 0.6 s a step).
@@ -927,120 +400,25 @@ pixels or more without the body anchor's ramp, and any loop whose half is under
A walk or run filmed from its first frame only (no end frame) often grows or shrinks as it plays:
a front walk comes a little closer with every step, a back walk goes away. The loop is then cut on
frames that change size, so the frame one cycle after the first is not the first's size and the
-loop pops at the wrap. The change is read one cycle on (`gait_fallback.cycle_drift`): the lag at
-which the pose, cut out about its feet, matches itself best (in the state's window, at most half
-the clip), and each frame's height (to a fraction of a pixel: the rows' coverage summed) against
-the frames one, two, … of those lags later. The median of those changes per frame, carried over
-the clip, is the `drift`. At 1 % or more (`SIZE_HOLD_MIN`) every frame is scaled back to the
-first frame's size about its fitted foot point before the cycle search, so the search, the seam
-and the cells all read frames of one size. Below 1 % the frames are searched as filmed.
-
-Why one cycle on, and not a line through the clip (2.24.0): a clip that starts from a standing
-pose and settles into the walk over its first steps (knees bending, the body leaning in) is a few
-pixels shorter from then on, and a line through every frame reads that one change of pose as a
-body that shrinks the whole way, and held it. The same pose a cycle later is the same size
-unless the body really changes, and the few frames of the first pose do not move a median of the
-rest. The other way round, a settle can
-pull the line flat over a walk that does grow; one cycle on, that growth is still read and held.
-On a synthetic walker that stands 6 px taller for its first frames and then walks at one size,
-the line read −2.2 % and the hold, so scaled, then found no cycle at all; one cycle on reads 0
-and the clip is cut as filmed (`tests/video/test_gait_fallback.py`).
-
-The report says what was measured and done (`size_hold`: `drift`, `applied`, `padding_ltrb`, and
-the evidence: `method: one-cycle-on`, `lag`, `pose_match` — the pose's mismatch at that lag over
-its mean across the window, 0 for an exact repeat — `pairs`, `per_lag`, the change over one lag,
-and `drift_fitted_line`, what a line through the clip would have read). `--size-hold off` searches
-the frames as filmed, as before 2.24.0. When the hold came in (2.24.0, read off the line) it was
-measured on one front catwalk filmed from its first frame (+2.0 % over 3 s): the engine's seam
-ratio of the cut went from 1.44 to 1.19.
+loop pops at the wrap.
+
+`--size-hold off` searches
+the frames as filmed.
**A lead-in is left out of the search** (walk and run, `--cycle auto` or `periodic`). A video
model may reframe a small subject in a clip's first frames: the body grows (or shrinks) by a third
-or more in under half a second, then walks at its new size. Searched with those frames, the
-motion analysis reads the reframing as the clip's motion and the walk's repeat is lost; the gait
-fallback, which then scaled by a line through the clip, read the step as a steady growth and
-shrank the walk. So the clip's sizes are read one cycle on (`gait_fallback.cycle_drift`, the
-hold's model, a median over the whole clip). A clip opens on a lead-in when its first frame's
-height and size (the square root of the frame's summed coverage) are both off that model by 10 % or
-more, the same way (`LEAD_IN_MIN`): a reframing scales the whole body and moves both, a pose moves
-one — an item held up from the second frame on makes the first frame shorter and no lighter, legs
-spread in a side step add size and no height. The lead-in (`gait_fallback.lead_in`) runs on while
-the height stays that far off, that way; a walk's own frames stray from the model by a few percent. The search — the size hold, the motion
-analysis, the cycle search and the gait fallback — reads the clip after it as a clip of its own,
-its window included. What it finds, and what it refuses, is said in the clip's own frame numbers:
+or more in under half a second, then walks at its new size. What it finds, and what it refuses, is said in the clip's own frame numbers:
every `start` and `context_pair_range` in the report's `cycle`, refused candidates too, so a cut
-taken again from them (`--cycle fixed --start`) is the frames they name. The report records it on
-every walk and run (`lead_in`: `frames`, 0 for none; `height_change`, the walk's height where the
-lead-in ends over the first frame's, less 1; `first_off` and `first_off_size`; `search_from`, the
-first frame the search read). A cut the caller names (`fixed`, `pinned`) is the caller's frames, lead-in or not. A clip
-too short to read its size one cycle on has no lead-in (`why`). On a synthetic walker filmed at
-0.63 of its size and reframed over 9 frames, the search as filmed found no cycle, nor did the
-fallback; after its 5-frame lead-in it cuts the 24-frame walk (`tests/video/test_edge_speck_lead_in.py`).
-
-**Nothing is cut when a frame is scaled up.** A clip that shrinks is scaled up about its feet,
-and when the feet also rose in the frame (a back walk going away toward the horizon) the crown
-lands above the frame. Every frame is first widened by the room the furthest one reaches past
-each edge (`gait_fallback.undo_padding`, the same for every frame; `padding_ltrb` in the
-report), so no part is lost. A frame that needs no room keeps its size and bytes. The gait
-fallback's own scale-back (below) widens the same way. The foot point is a least-squares line
-with exactly rounded sums (`sprite_gen.util.lsq`, as are the fallback's fitted heights), the same to
-the last bit on every machine. With np.polyfit, whose last bit differs between LAPACK builds, feet
-that stand on the frame's bottom edge read a hair past it or short of it, and whether the frames
-got 2 px of room below — and so the frames the cut is searched on — turned on that bit.
+taken again from them (`--cycle fixed --start`) is the frames they name. A cut the caller names (`fixed`, `pinned`) is the caller's frames, lead-in or not.
Gates, all fail-loud: no period (profile flat, below the recorded `periodicity_min`), loop seam ratio
above `--seam-max` (2.0), GIF/WebP re-opened and checked (frame count, `loop=0`,
transparent corners, no RGB under alpha 0 in the WebP).
-A walk or run loop then has its jump frames repaired before the strip is built: one or two
-drawings in a row that leave the loop's flow — 3× their region's usual step off the line between
-the frames either side, by direction and speed, not by the size of a step — are taken out and
-made again by RIFE between those frames, each at its own time so the loop keeps its length, at
-most three calls and never made from or beside a frame made (`--repair auto`, the default;
-`--repair off` cuts as filmed). A frame the ghost screen names a filmed ghost, read on
-the cut as filmed, is replaced in the same stage first: by RIFE's frame between the two clean
-frames beside it, else by the clean frame beside it, else kept and named (`ghost_given_way`,
-`ghost_kept`) — a walk of one direction is delivered as cut and never meets the alignment that would
-take a clean frame there. Then a part that keeps its way and rushes — a tail that runs short of
-the cycle, rushing on at the wrap — has the three or four drawings either side of the rush made
-again at times that spread it, made from the frames as filmed, the body's feet, torso (the head
-and torso the motion anchor tracks; a part swaying on its own beat is not drift) and ground line
-moving no further in a step, nor the rest of it faster, than they did there (the eased retime, up
-to nine calls of its own) — played only where the rest of the body keeps its own beat on the frames
-made, step by step; a frame made is the whole picture at one time, so the legs take the time the
-tail is given, and the loop then keeps the flow repair. Before all of it, a cut two steps long whose wrap a part on its own beat
-leaves open — a tail swinging round on a beat of its own, closing on no cut of two steps — has four
-to twelve frames beside its wrap made again between the clip's frames a cycle apart and its own, so
-the wrap plays a step the clip filmed, as far as the torso held to the stretch as the loop plays it
-allows (the overlapped wrap, `wrap_overlap`; `--overlap-wrap off` turns it off alone, for a host whose
-RIFE runs on a CPU, and the gate then refuses the cut as filmed). A loop of any other state has its wrap read rather than its flow; where the wrap jumps, one, two, or four frames round it are made again by RIFE between the frames either side (the seam bridge, `repair.seam_bridge`).
-The report's `jump_repair` names the frames. RIFE
-is installed once with `sprite-gen rife install`; without it a loop that needs a frame is cut as
-filmed with a warning, each filmed ghost given way to the clean frame beside it (`--repair on`
-fails instead). A frame shown twice in a row is one frame of the GIF and WebP, checked so, and the seam gate reads a frame given way as filmed (`seam_as_filmed`). See [loop repair](loop-repair.md). The repaired loop's jolt index and the head's frame-to-frame
-moves are reported (`jolt`); beyond the reference bounds that is a warning line, and a gate
-(`video-loop: loop jolts — …`) only when `--jolt-max` / `--head-step-max` are passed.
+See [loop repair](loop-repair.md).
**Held drawings: recorded on every loop.** A video model may film a walk at 12 drawings a second
-inside a 24 fps clip, each drawing shown for two frames ("on twos", or three: "on threes"). The
-report's `drawings` says so, read over the whole clip as keyed, before any cut
-(`sprite_gen/video/held.py`): `hold` (1 every frame a drawing, 2 or 3; `null` with a `why` for a
-clip too short or still), `drawings` and `drawings_per_second`, `held_steps`, and `contrast` per
-hold — the held steps over the change steps, the evidence. `cycle_drawings` is the same reading over
-the cut alone, on the clip's steps from the cut's first frame into the frame after its last (`start`,
-`length`, `steps`; `null` with a `why` under 12 steps, one window). `strip.json` carries both
-(`drawings`: `hold`, `drawings_per_second`, `contrast`, `frames`; `cycle_drawings`: `start`,
-`length`, `steps`, `hold`, `drawings_per_second`, `contrast`, `why`) for `video-cycle-align`, which
-reads the cut's: a clip may hold its drawings for only part of its length. The second frame of a pair is rarely a
-byte copy: the model redraws it a little, so its step is small, not zero, and a rule that calls a
-step held under a fraction of the median step misses it (with half the steps held the median falls
-between the two kinds). So the judgement reads the rhythm: for a hold of 2 or 3, in windows of 12
-steps, the phase whose every second (or third) step is the change, its held steps' median over its
-change steps' median; under 0.3 the clip is held, and each step is then held when it is under the
-geometric midpoint of the two kinds' means. A motion filmed every frame has no such rhythm — its
-steps swell and shrink with the stride over a dozen frames — and a clip whose steps alternate long
-and short but move every frame reads above it; so does a frame repeated now and then (a 20 fps
-clip carried at 24). Nothing is refused here: played at its own rate a held loop is ordinary
+inside a 24 fps clip, each drawing shown for two frames ("on twos", or three: "on threes"). Nothing is refused here: played at its own rate a held loop is ordinary
limited animation. It matters when `video-cycle-align` stretches it ([loop repair](loop-repair.md)
section 4, "Held drawings").
@@ -1049,34 +427,18 @@ section 4, "Held drawings").
A video model asked to jump "over and over" sometimes jumps once and stands for the
rest of the clip. That is not a period, and the periodicity gate says so. For states
that *are* single actions by nature (`jump`, `attack`, unknown states; never `walk`,
-`run`, `idle`) `auto` then runs a second, different detector instead of failing: the
-detector finds close endpoint poses enclosing an excursion. The endpoints must differ
-by at most a quarter of the departure, with two observed rest frames on either side
-of at least four active frames. A component touching the clip's start or end is
-rejected, never repaired with padding. Departure must span at least three ordinary
-playback steps to reject incoherent jitter. Among candidates containing at least
-95 % of the largest departure, the shortest cut wins (then lower seam ratio).
-
-Acceptance uses either peak contrast above the distance-profile median (3 MADs) or
-departure from the endpoint pair relative to their mean subject mass (0.4). Unlike a
-global medoid, the pair can identify ready poses even when a held strike occupies
-most of the clip. `cycle.excursion_rule`, `return_pair`, `excursion_over_step` and
-`return_distance_over_departure` expose that evidence. These pixel measurements do
-not identify an anatomical ready pose or guarantee character consistency.
+`run`, `idle`) `auto` then runs a second, different detector instead of failing.
The failover is explicit: `cycle.kind = "one-shot"` and `periodic_attempt` preserve
both decisions. The strip sidecar carries `kind` and `loop: false`, so scene loaders
play it once on a trigger. GIF/WebP previews still loop, and the same seam and
animation gates apply. `--cycle periodic` refuses a weak periodic candidate;
`--cycle one-shot` forces return detection. Stationary clips, jitter and actions
-without an observed return fail loud. Selection and seam refusals write the requested
-report before exiting: `status = "failed"`, error, window, candidate start/length,
-seam numerator/denominator and repetition/return evidence. A walk or run refused by the
+without an observed return fail loud. A walk or run refused by the
`--anchor motion-auto` search names the windows it measured and refused, best first
-([loop review](loop-review.md), "The gait fallback"). Undefined ratios are JSON
-`null`; success records `status = "passed"`. `--cycle fixed --start N --length L` skips detection and cuts exactly
+([loop review](loop-review.md), "The gait fallback"). `--cycle fixed --start N --length L` skips detection and cuts exactly
those frames — for a clip that holds too few repeats for the periodicity gate but whose
-cycle is known (the 2026-09-09 reel jump: 2.3 hops in 145 frames). It is an explicit
+cycle is known. It is an explicit
instruction, not a failover: the report says `kind = "fixed"`, and the seam gate still
applies.
@@ -1094,20 +456,11 @@ before, with `status = "failed"`.
`--cycle pinned` is for a clip pinned to end on its first frame (`video --last-frame` set to
the start image). The cycle is every frame but the last, which re-renders the first, so the
-wrap plays like the step into that last frame. The gate is the pin, not the seam ratio: the
-last frame has to land within `max(seam_max x the mean step, PIN_NOISE_MAX)` of the first, on
-the analysis thumbnail. A near-still clip moves so little per frame that the ratio reads the
-re-render noise of the pinned frame as a jump; a clip that ends in another pose still fails,
-with its own message (`the pinned clip does not end on its first frame`). The report says
-`kind = "pinned"` and records `pin_error` and `pin_tolerance`. Where the pinned frame redraws the first, `--wrap-blend auto` (the default) takes the first frame's drawing back over the last half second, a redraw only, recorded as `wrap_blend`. Passing `--wrap-blend off` cuts as filmed, but [the seam bridge](loop-repair.md#the-seam-bridge-a-loop-that-is-not-a-walk-whose-wrap-jumps) can still make frames round the wrap of a loop that is not a walk or run; for such a loop, pass `--repair off --wrap-blend off` for the earlier bytes. See [loop repair](loop-repair.md#6-the-redrawn-wrap-a-pinned-clip-whose-last-frame-the-model-drew-again) for the gating and blending rules.
+wrap plays like the step into that last frame. Where the pinned frame redraws the first, `--wrap-blend auto` (the default) takes the first frame's drawing back over the last half second, a redraw only, recorded as `wrap_blend`. Passing `--wrap-blend off` cuts as filmed, but [the seam bridge](loop-repair.md#the-seam-bridge-a-loop-that-is-not-a-walk-whose-wrap-jumps) can still make frames round the wrap of a loop that is not a walk or run; for such a loop, pass `--repair off --wrap-blend off` for the earlier bytes. See [loop repair](loop-repair.md#6-the-redrawn-wrap-a-pinned-clip-whose-last-frame-the-model-drew-again) for the gating and blending rules.
`--cycle once-return` is for a clip pinned to end on its first frame that plays once (`video-set
--play once-return`, [play modes](#play-modes)). It keeps every frame, the last too, so the strip
starts and ends on the first pose and a game plays it once and goes on from the pose it started in.
-The gate is the pin, as for `pinned` (`the once-return clip does not end on its first frame … it does
-not return to its first pose`). The strip is sampled with both ends kept, the previews play once as a
-`once` cut's do (WebP `loop=1`, no GIF loop extension), and `strip.json` says `loop: false`,
-`hold_last: false`, `returns: true`, `end_frame` and a `motion_peak` event (the clip's largest step).
Outputs:
@@ -1118,31 +471,10 @@ Outputs:
pad** so feet meet the floor, bottom-aligned, ≤ 64 cells **and ≤ 32 000 px wide** because
Chrome refuses images near 32 767 px — the cap is on pixels, so a 650 px cell allows 49
cells and the meta says `subsampled`; ≤ 520 px tall) with `frames · w · h · body_h · delay_ms ·
- cycle_frames · cycle_seconds`. `body_h` is the **standing height** — the tallest frame whose feet touch the floor
- (a median over the cycle undercounts a jump, whose crouch and airborne frames dominate,
- and then over-scales it by ~22 %, 2026-09-09). Scale a jump strip — whose cells include
+ cycle_frames · cycle_seconds`. `body_h` is the **standing height** — the tallest frame whose feet touch the floor. Scale a jump strip — whose cells include
air room — by `body_h`, not `h`, and it reads the same size as a walk strip;
`--body-height N` does that scaling in the pipeline so every state comes out at the same
- character size (`--strip-height` stays the cap). With a target, the standing height is
- measured on the **clip's first frame** instead — the base still's pose, which every clip
- starts from — because the tallest grounded frame of an attack is its windup with the weapon
- overhead, and scaling that to N shrank the character against its walk. A video model may
- reframe the subject after the first frame — a lead-in (section 4), or less — and then the walk
- is filmed at another size than that pose: read on the first frame, filmed small, the standing
- height scaled the walk up, a lead-in's into the cell cap. So a walk or run cut for a
- `--body-height` has its size read against the first frame's (`gait_fallback.size_change`) on
- three lengths at once: the height, the mass (the square root of the summed coverage) and the
- breadth (the widest row of the upper half of the body), each the middle of the cut's frames
- over the first frame's. A pose moves them apart — a walk is shorter than its standing pose and
- broader, an item held up is taller and no heavier — and a reframing moves all three the same
- way, so the cut's change of size is the least of the three when all go one way, and none when
- they part. It is the cautious reading: a reframing smaller than what the pose itself moves one
- of the lengths by, the other way, stays a pose (a small shrink under a walk's broader body,
- for one). At 1 % or more (`SIZE_HOLD_MIN`) the standing height is read on the cut's own first
- frame (`body_ref: cut-first-frame`, and `body_ref_frame`, the clip frame it was read on). The
- report records the reading (`cut_size`: `change`, `height`, `mass`, `breadth`, `min`). The
- sidecar says which frame (`body_ref`: `first-frame`, `cut-first-frame` or
- `tallest-grounded`) and records `body_src_h` and `scale`. `delay_ms = cycle_seconds / frames`, so a
+ character size (`--strip-height` stays the cap). `delay_ms = cycle_seconds / frames`, so a
24 fps clip yields 41.67 ms cells; render at 24 fps to keep one cell per frame
(a 30 fps render of 24 fps cells is a 5:4 pulldown and judders).
- **Cells** are scaled with their coverage and their colour taken apart (`resize_cell`; a cell
@@ -1156,14 +488,7 @@ Outputs:
that mixes colours does this, in a cell and again wherever the cell is scaled later; the
resample knows no key and caps nothing (`tests/video/test_strip_resample.py`). The one
operation that compares a cell with the key bar, source restoration, handles it itself
- ([loop-comparison.md](loop-comparison.md#what-a-restored-cell-is)). The
- strip used LANCZOS over premultiplied RGBA before, which weighs the colours across an edge
- against each other and divides by the edge's low coverage: on a keyed frame, whose edge holds
- a light rim and ink with a little of the key's green, it drew a lighter rim and greener ink
- than the frame had. On the synthetic outlined figure in `tests/video/test_strip_resample.py`
- (a light rim, green-tinted ink, strands 0.5-1.4 px wide), LANCZOS left 1,462 pixels at 0.97x
- and 1,750 at 1.03x with a colour none of the source pixels under them had; the split leaves
- none, and the strands keep LANCZOS's coverage. Colour is no longer sharpened, so a 1 px line
+ ([loop-comparison.md](loop-comparison.md#what-a-restored-cell-is)). Colour is no longer sharpened, so a 1 px line
inside the body comes out a little softer than LANCZOS drew it when a cell is enlarged. The
GIF and WebP are cut from these cells. The function lives in `sprite_gen/util/resample.py`
and is the resample of every place that scaled a keyed picture with LANCZOS: a row frame fitted to its cell and the twin
@@ -1174,30 +499,21 @@ Outputs:
fallback" in [loop-review.md](loop-review.md)) and a curated transform on a smooth row
(`curation.apply_transform`). Coverage keeps BICUBIC's edge, held to the coverage of the
2 x 2 source pixels the colour mixes from, and colour is a BILINEAR mix of premultiplied
- colour. BICUBIC has the same negative lobe, smaller: on the synthetic figure it left 1,088 to
- 1,864 pixels with a colour none of the four source pixels under them had when a frame was
- scaled back by 0.84x to 1.19x, and 840 to 2,102 for a half-pixel move, a 10° rotation, a
- 0.75x shrink, a shear and a 1.3x grow with a 15° rotation; `transform_cell` leaves none. The
+ colour. The
same cost applies: colour is not sharpened. A pixel row's curated transform samples NEAREST
and is untouched. The scene GIF's ffmpeg downscale stays LANCZOS: it scales opaque composited
frames, where nothing is divided by a low coverage.
-- `<name>.gif` — `n_out` frames evenly across the cycle, 1-bit alpha, disposal 2, `loop=0`.
- `n_out` is a **playback density, not a fixed count**: `round(cycle_seconds × --gif-fps)`
- (default 24 fps = the source rate, so every cycle frame is kept; floor 4, never more than
- the cycle holds). A fixed 12 made a 2.5 s jump hold each frame 210 ms while a 1.1 s walk
- held 90 ms, and even an even 12 fps read sluggish on a jump (2026-09-09). `--n-out` and
+- `<name>.gif` — `n_out` frames evenly across the cycle, 1-bit alpha, disposal 2, `loop=0`. `--n-out` and
`--gif-fps` still override; `--strip-height` caps the cell/strip/GIF height. Scaling up
requires an explicit `--body-height` target and still respects that cap.
-- `<name>.webp` — same frames, lossless, `img2webp -exact` (Pillow's animated WebP writer
- does not pass `exact` and rewrites RGB under transparent pixels).
+- `<name>.webp` — same frames, lossless, `img2webp -exact`.
## 5. Set — the batch
`sprite-gen video-set --base side=side.png --base front=front.png --states idle,walk,run,jump,attack --out-dir set/`
runs canvas → video → frames → loop for every (direction, state). The xAI team quota
-is **2 requests per second** (five parallel starts produced two HTTP 429s): starts are
-staggered (`--start-gap 2`); a 429 is sent again inside `sprite-gen video` (8 s, 16 s,
-[a refused request sent again](gen.md#a-refused-request-sent-again)) and each clip runs once. Clip length
+is **2 requests per second**: starts are
+staggered (`--start-gap 2`); each clip runs once. Clip length
is each state's own default (3 s, attack 2 s) unless `--duration` sets one for all, and an
attack or idle clip is pinned to end on its canvas and cut whole (`--cycle pinned`). States use differently shaped canvases (square, tall, wide),
so the same character films at different pixel heights; `--body-height N` gives every state's loop the
@@ -1209,32 +525,11 @@ its item and is listed in `table.md` with its stage and error. Exit code is non-
when any item failed.
A front or back walk films from its base redrawn mid-step (`--walk-start redraw`, default; one
-image generation each, `--still-provider` picks the provider; see §2). After the loops are cut,
-every walk or run filmed in two or more directions is given one cycle
-length: each loop is resampled to the set's median length (only the frames that fall between two
-source frames are made, by RIFE, and one that melted takes the nearer source frame instead (`--align-between
-auto`, the default; `rife` keeps every made frame, `nearest` makes none))
-and turned to start as the same own foot lands in every view — read off the legs, never off an
-ear or a hat's point, and the foot told apart by the item's own view and facing (`--align-cycles
-auto`, the default; `off` keeps each loop's own length). The same step stands alone as
-`sprite-gen video-cycle-align --loop-dir … --view …`. `set.report.json` carries `cycle_align`
-per state (with `start_foot` and `start_foot_source` per item, and the loops whose foot nobody named
-under `unnamed_feet`, told back with `--align-foot <item>=left|right`), a failed alignment is listed as `cycle-align:<state>`,
-and a made frame with a smear, one that melted and was replaced, or a loop whose foot could not be named is a line under
-`warnings`. A held loop stretched past what an interpolator bridges is named for a new take: the
-state's `retake` (reason `held-drawings`, with its numbers; per item under `cycle_align.retake`) and
-a warning line ([loop repair](loop-repair.md) section 4, "Held drawings"), as is a loop that delivers a filmed
-ghost with no clean frame beside it (reason `filmed-ghost`, its cells under `ghost`; `reasons` lists both
-where both apply). Two cases skip the alignment with a warning instead of failing it (`applied: false`,
-`reason`, and a line under the report's `warnings`): no RIFE (`rife-not-installed`), and a loop
-that may hold more than one cycle (`cycle-suspects`, the loops under `suspects`; count them, then
-`video-cycle-align --cycles <loop>=<k>`). See [loop repair](loop-repair.md) section 4.
+image generation each, `--still-provider` picks the provider; see §2). See [loop repair](loop-repair.md) section 4.
### Play modes
-A state's name used to decide everything about its clip: its sentence, whether the clip is pinned to
-end on its first frame, how it is cut and whether its strip loops, so every new motion was a change to
-the engine. `--play` gives how a motion plays as a value of the request, and `--motion` gives the
+`--play` gives how a motion plays as a value of the request, and `--motion` gives the
motion's own words, so a motion the engine has no state for — a punch, typing at a desk, a block — is
filmed under a name of your own. The modes and the presets are `sprite_gen/video/play.py`.
@@ -1253,14 +548,11 @@ sprite-gen video-set --base side=side.png --base front=front.png --states idle,p
| `lifetime` | framed as an effect and pinned to an empty black frame | an effect that appears and is gone | `lifetime` | `loop: false`, `blend: add` |
`STATE=…` applies to every view of that state and `ITEM=…` (`side-punch=…`) to one item, whose own
-value wins over its state's. A key that names neither, a key given twice, an empty value or a mode the
-state cannot play is refused before any clip is made. `set.report.json` records each item's `play`
-and, where given, its `motion`.
+value wins over its state's.
-Named states are presets. Without `--play` every state is filmed, prompted and cut as before: `effect`
+Named states are presets. Without `--play` every state is filmed, prompted and cut: `effect`
as a lifetime, the six terminal states (`death`, `fall`, `land`, `cast`, `hurt_hold`, `transform`) as a
-once-hold and every other state as a loop, each with its own sentence, canvas row and cut (the prompts
-are unchanged, `tests/gen/test_prompt_freeze.py`). A state of one nature plays only that mode — `effect`
+once-hold and every other state as a loop, each with its own sentence, canvas row and cut. A state of one nature plays only that mode — `effect`
a lifetime, a terminal state a once-hold, a cyclic state (`idle`, `walk`, `run`, `talk`, `blink`,
`breathe`) a loop — and another motion is filmed under a name of its own. A named state's sentence is
used in its preset mode, and the attack's (one strike, then a recovery to the exact starting stance) in
@@ -1270,7 +562,7 @@ mode, and for a word the engine does not name, the mode's own sentence names the
A mode the request names is the cut's: a `loop` asked for is searched as a loop (`periodic`) and
refused when it does not repeat, never failed over to a single play the way a preset's `auto` cut of a
-`jump` or of an unnamed state may be ([one-shot actions](#one-shot-actions--cycle-autoperiodicone-shot)).
+`jump` or of an unnamed state may be ([one-shot actions](#one-shot-actions----cycle-autoperiodicone-shot)).
The canvas row is the state's (a motion of your own films on the square default; `--shape` widens
every canvas of the set), except that a lifetime is framed as an effect whatever its name.
@@ -1299,34 +591,7 @@ sprite-gen video-sway --loop-dir set/front-walk/loop --region 136,164,60,50 [--r
to say where it is — the engine does not find it: look at the first cell (or ask a vision model
for the four numbers once per direction; a mirrored direction takes the mirror's region).
- **The motion** is the body's own: how far each cell's body lies from the first cell's, up and
- down and side to side. The silhouette (alpha ≥ 128) is worn down: worn by r, a pixel stays when
- the square of side 2·r + 1 around it is all body. Its depth is the most the first cell can be
- worn down by and still keep a pixel, plus one; worn by a quarter of that, what swings on the
- body and is thinner than it (a tail, a ponytail, an ear, a sword or a rod held up, the legs and
- arms) is gone and the head and torso are left. Each cell is laid where its silhouette, worn by
- every whole number of pixels from a quarter to half of that depth, overlaps the first cell's,
- worn alike, most — the overlaps of every level counted in whole pixels and summed, a tie going
- to the smaller move. A pixel counts once for each level it is still in, so the deepest of the
- body counts most and a part that comes and goes cannot outweigh it, while a torso that is
- shallower in one cell (an arm swung away from it, long hair lifted off it) still counts at its
- shallower levels. A part as thick as the body outlasts the wearing — ears as wide as the head —
- and a cell that has it elsewhere than the first cell does, laid on the first cell alone, lies
- ears on ears with its body tens of pixels off. So the cells are laid twice. Laid on the first
- cell, each is moved back by its lay and the cells are counted: per level and pixel, how many
- more of them are in that level there than are not (none, where no more are). The head and
- torso are in every cell at one place and count the whole number of cells; what swings — ears
- up in some cells and flopped onto the face in others, a leg forward and back — is at any one
- place in half of the cells or fewer and counts nothing. Each cell is then laid on that count
- as it was on the first cell, and its lay less the first cell's own is the motion. A thick part
- that keeps one place in most of the cells is body to this read, which sees outlines only. The
- top of the body was read before: whatever came to the top was the
- motion, and a tail tip, a flopping ear or a sword raised over the head made it jump by the
- part's whole swing from one cell to the next. A cell with nothing in it a quarter as deep as the first
- cell's body is refused, and so is a strip with no part of the body at one place in more than
- half of its cells. The part is a damped mass on the body — its offset x from
- where the body carries it answers x'' + 2ζωx' + ω²x = −body'' — solved in the loop's periodic
- steady state per harmonic of the cycle (the first six), so it lags the bob and settles, with no
- kick at a foot strike, and the last frame leads into the first. `--freq` (2.4 Hz) and `--zeta`
+ down and side to side. `--freq` (2.4 Hz) and `--zeta`
(0.6) set the part; `--gain` (2.5) scales the physical answer and nothing else. On a front
walk with a 12 px bob in a 600 px body that is a move of about ±5 px; `--gain 1` is the mass as
measured, `0` gives back the strip as it was.
@@ -1334,37 +599,12 @@ sprite-gen video-sway --loop-dir set/front-walk/loop --region 136,164,60,50 [--r
at the centre and 0 at the rim (cos²), sampled as premultiplied bilinear colour; outside it no
pixel changes. A move so large that the weight's slope folds the picture over
(offset × π / (2 · radius) ≥ 1) is refused: lower `--gain` or give the region larger radii.
-- **`--on-fold lower`** lowers the gain for you instead of refusing, region by region. The move
- is the gain times the move at gain 1, so the gain at which a region folds is
- 2 · radius / (π · move at gain 1), and a region that folds at `--gain` takes the largest gain
- under that, in steps of 0.01; a region that does not fold keeps `--gain`. Every part hangs on
- the same body and answers the same motion, but how far a part can move before it folds is its
- own size, so a small part (an ear) does not hold a large one (a chest) back. No region goes under 1, the
+- **`--on-fold lower`** lowers the gain for you instead of refusing, region by region. No region goes under 1, the
mass as measured: one that would have to is **held** — it does not move at all, so a
follow-through is never quietly weaker than the motion it answers — and named, on stderr and in
- the record. The strip is refused only when every region is held (the message names the largest
- region and the largest gain that would not fold it). Where regions of different gains overlap,
- the larger move wins; the move there is nowhere steeper than either region's own, so nothing
- folds. A strip whose regions all take one gain — one region, or regions that fold alike, or
- none that folds — is written as one gain for the strip writes it, byte for byte, and its `gain` is
- then the `--gain` that gives this strip by itself. The default stays `refuse`, with the same
- message as 2.24.0; a strip that does not fold is the same under either.
+ the record. The default stays `refuse`; a strip that does not fold is the same under either.
- **What it writes**: the strip, GIF and WebP over the loop's own (both animations re-opened and
- checked as `video-loop` checks them), and `follow` in `<name>.strip.json` (the regions, the
- settings, the body's height in the first cell `body_px`, the first and last level it was worn
- down to `body_worn_px`, the body's bob `body_bob_px` (side to side, up and down), `dx_px`/`dy_px` per cell, `reach_px`; `gain` is the gain used and
- `gain_requested` the one asked for, and `fold` says whether it was lowered, the move asked for,
- the move at gain 1, and per region its smaller radius, how near the used move is to folding it
- (`ratio`, under 1) and the gain at which it folds). Where the regions took gains of their own,
- each region's entry also says the gain it moved by (`gain`, 0 when held) and whether it was
- held (`held`); the strip's `gain` is then the largest of them, `dx_px`/`dy_px` and `reach_px`
- are that gain's (a region moves by its own gain over that one times them), and `fold.ratio` is
- the nearest any region came to folding. A lowered gain is also named on stderr — per region,
- with the `--region` it was given, where they differ — and so is a held region; the printed
- summary then carries `region_gains`.
- All four are written and checked beside the loop first and moved over its files only once the
- record is written too, so a run that fails on the way — an animation that fails its check, a
- record that does not serialise — leaves the strip, GIF, WebP and record as they were.
+ checked as `video-loop` checks them).
`cycle/` is left as cut. The strip as it was is kept as `follow.source.png`; running
`video-sway` again reads from it, so a second run never moves a moved strip. `--board` writes the cells before and after where the part
sits lowest and highest, on white.
@@ -1383,60 +623,17 @@ place of the body, and a stretched loop moves them by a motion read anew. `--rea
names the strip they were read on — its file's sha256, as cut, before any follow-through (64
lowercase hexadecimal digits; anything else is refused before anything is read):
-- **`same`**: it is this loop's strip as cut (`follow.source.png` once a follow-through moved it).
- The follow-through is the one without `--read-on`, byte for byte, and the record says so.
-- **`transported`**: it is the cut this loop was aligned from. `video-cycle-align` records that cut
- the first time it aligns the loop (`cycle_align.origin`: its sha256, cell size, scale and crop
- origin, each cell's pixels by sha256, and the body's motion as `video-sway` reads it there),
- keeps it on every later alignment, and records where each cell of the new strip is from
- (`cycle_align.cells_from`: `{"source": i}`, a frame of `cycle.source/`, or `{"between": [i, j],
- "t": t}`, a frame made between two). Each cell is carried by the cut's reading of the cut's cell it
- is, the regions stay where they were read (the cut's cell 0), and the damped mass is solved on
- this loop's order, length and frame time: a turned loop gives the cut's follow-through cell for
- cell, a stretched one gives the new cycle's offsets on the cut's motion, duplicates and all.
-- **`uncertain`**, refused: the cut is the one, but a cell was made between two of its frames
- (RIFE, or any `between`), or a cell is not the cut's cell pixel for pixel — a crop or a scale
- changed and nothing records how, or a cell was drawn again since. A made cell has no reading of
- its own, and none is taken from the nearer frame by rounding. A cut made before its strip
- recorded its crop (`source_rect`) says nothing of where it was cropped; there the cells' pixels
- decide alone, as they do for every cell anyway.
- **`no-match`**, refused: neither — another clip, another cut, a strip nothing here was cut or
aligned from. Locate the regions again on this strip.
-A refusal writes nothing but the strip as cut kept beside the loop, as on any refusal. Without
-`--read-on` nothing of this is read or written, and the record holds no new key. With it the record
-carries `read_on` (`sha256`, `relation`; for `transported` also `policy` and `cut_cells`, the cut's
-cell each cell is) and `carry_basis`. The printed summary carries `read_on` (the relation).
-
#### A least area each move leaves — `--stretch-floor D`
The fold rule keeps a region from folding, and so lets the region's steepest pixel take nearly
nothing of the source: a line there is drawn across many pixels. `--stretch-floor D` (0 to under
-1) asks every region's move to leave each pixel at least D of its area. The weight's steepest
-slope is π/2 over each radius, so a move (ox, oy) leaves 1 − (π/2)·hypot(ox/rx, oy/ry) of a
-pixel's area, read by the way the region moves (the fold rule reads the smaller radius whichever
-way it moves). Each region takes the largest gain, in steps of 0.01, that keeps D in every cell
-— **and never one above the fold rule's**: where the direction would allow more (a region moving
-along its long axis) the fold rule's gain stands, so a floor only ever lowers. Under it the fold
-rule's handling stands: a region the floor takes under 1 is held and named, the strip is refused
-when every region is, and `--on-fold refuse` refuses a move under the floor. There is no default:
-without `--stretch-floor` the fold rule alone decides, byte for byte. A floor the move already
-keeps draws the same strip, GIF and WebP. The record carries `stretch` (`policy`, `floor`, and per
-region `per_gain` — the area a unit of gain takes at its worst cell, `least_cell` —, `rule_gain`,
-`floor_gain`, `gain`, `held`, `least_area`, `under_measured`) and `carry_basis`; a lowered or held
-region is named on stderr with what lowered it, the fold or the floor. On a loop aligned from the
+1) asks every region's move to leave each pixel at least D of its area. On a loop aligned from the
cut, give `--read-on` too: the floor is then read on the cut's motion, so a turned loop is lowered,
held or refused as the cut is.
-The floor holds the stretch, and only the stretch: what a move also does to a line — it tilts it,
-and where two regions overlap it bends it at their seam — lowers only as the gain lowers.
-`video-sway-inspect` writes all three (below).
-
-What carries a region into a cell is the lay of the body's outline (`carry_basis: {"reading":
-"outline-lay", "region": "unverified"}`). Two strips whose alpha is the same in every cell are
-carried alike, whatever moved inside the outline; whose pixels are inside a carried ellipse is not
-read, and nothing here moves a region on a guess of it.
-
### Inspecting a sway — `video-sway-inspect`
The ellipse is given in the first cell, where somebody looked. Into every other cell it is carried by the body's motion, and there nobody looked: an arm that swings across a chest is inside the chest's ellipse in those cells and moves with it, and so does a sleeve of the chest's own colour, which no count of colours finds. The Sway layer does not read what a pixel belongs to. `video-sway-inspect` (old name `video-follow-inspect`) writes what somebody needs in order to look, and moves nothing:
@@ -1447,83 +644,13 @@ sprite-gen video-sway-inspect --loop-dir set/front-run/loop --region 136,164,60,
--out-dir inspect/front-run [--scale 2] [--columns 8]
```
-- **Asked as `video-sway` is, answered by the same code.** It takes `video-sway`'s arguments
- (all but `--board`), reads the strip as cut — `follow.source.png` where a follow-through was
- already written, the strip itself where none was — and solves it where `video-sway` does
- (`follow.read_request`, `follow.solve`): the carry, each region's gain, the offsets and the
- moved cells are computed in one place, and both commands read them there. What `video-sway`
- refuses it refuses in the same words under its own name, and then writes nothing.
-- **The loop directory is read and never written**: not the strip, not its meta, and not the
- `follow.source.png` that `video-sway` keeps on its first run. An `--out-dir` at or under the
- loop directory is refused. Run before `video-sway`, it changes nothing `video-sway` writes.
- **What is inside an ellipse is not read.** Every region is written `ownership: "unknown"` in
every cell, the first included, from its centre to its rim; no cell is marked or held on a
guess. `solid_px` counts the body's silhouette under the ellipse (alpha ≥ 128), not whose
pixels they are. Saying which cells hold the part alone is for a person or a model that looks
at the board of the cells as cut, and for a second reader apart from the first.
`video-sway` takes no such list: it moves every cell.
-- **`follow-inspect.json`** (`kind: video-follow-inspection`, `schema_version: 2`):
-
- | key | what it holds |
- |---|---|
- | `input_id` | one sha256 over what the answer is read from: the schema version, the strip's sha256, the meta's `cut_sha256`, the regions, the settings, the policy and the engine's version |
- | `inputs.strip` | `file`, `sha256`, `bytes`: the strip as cut that was read |
- | `inputs.meta` | `file`, `sha256`, `bytes`: `<name>.strip.json` as read; `cut_sha256`: its sha256 without the `follow` record `video-sway` adds (keys sorted, no spaces); `follow_recorded` |
- | `inputs.cut` | `frames`, `w`, `h`, `delay_ms`, as read from the meta |
- | `inputs.regions`, `inputs.settings` | the ellipses in the order given; `gain`, `on_fold`, `freq_hz`, `zeta`, `read_on` and `stretch_floor` (null where not asked) |
- | `inputs.policy`, `inputs.engine` | the way the motion is read and a region moved, by name (`follow.POLICY`) with the constants it is fixed by, and the ways a reading is carried (`transport`) and a floor kept (`stretch_floor`), by name; the engine's `name` and `version` |
- | `follow` | the follow-through as `video-sway` records it in the strip's meta, without `gif` and `webp` |
- | `carry_basis` | `{"reading": "outline-lay", "region": "unverified"}`: what carries a region, and that whose pixels it holds is not read |
- | `regions[i]` | `index`, `ellipse` as given, `radius_px`, `gain` (0 when held), `held`, `gain_limit`; over all cells the largest `reach_px`, `fold_ratio`, `bend` and `bend_deg`, the least `jacobian_min`, the sum of `changed_px`; `ring`, its colour on the boards |
- | `seams` | per pair of moving regions that meet in some cell (`regions`: [i, j]), the largest seam: `jump`, `deg`, the `cell` and the point `at` (x, y) |
- | `cells[k]` | `index`, `carry_px` (across, down), `changed_px`, `jacobian_min`, `seams` (as above, per pair that meets in that cell), `box` (x0, y0, x1, y1: the cell's picture on both boards) and `regions[i]` |
- | `cells[k].regions[i]` | `ellipse`: the region carried (centre plus `carry_px`, the radii as given); `offset_px` (across, down) and `reach_px`: the region's own move in that cell, 0 when held; `fold_ratio`; `jacobian_min` and `jacobian_min_at` (x, y); `bend` and `bend_deg`; `ellipse_px`, `solid_px`; `changed_px`; `ownership` |
- | `boards` | `scale`, `columns`, `size`, `ground`; `source` and `moved`, each `file`, `sha256` (the PNG file) and `pixels_sha256` (its pixels) |
-
-- **`carry_px`** is how far the cell's body lies from the first cell's, in whole pixels: what
- every region's ellipse is carried by in that cell, and what `video-sway` carries it by. It
- was written nowhere before; from the record's rounded offsets it cannot be worked back for a
- strip of more than thirteen cells (the answer keeps six harmonics of the cycle).
-- **`jacobian_min`** is the least area of the source that one pixel of the moved cell takes, over
- the pixels of the region's ellipse: 1 where nothing moves, 0 where the picture stops — one line
- of the source drawn across many — and under 0 where it would run backwards, which is what the
- fold check refuses. It is read on the pixels, between each pixel's neighbours on either side
- across and down, so for a region a few pixels across it reads a little over the steepest point
- of the weight. A region that `--on-fold lower` lowered moves at the largest gain that does not
- fold it, so in the cell where it moves most it is drawn nearly stopped: not folded, and
- stretched. `jacobian_min_at` is the pixel.
- Where regions overlap the move is the larger one's, so a region's numbers there are what is
- drawn in its ellipse, not its own move alone. `changed_px` counts the pixels whose RGBA the
- move changes; outside every carried ellipse it changes none.
-- **A move does three things to the picture, and each is written apart.** It stretches it — the
- least area, `jacobian_min` (D), the one `--stretch-floor` holds. It tilts a line: the move's
- steepest slope, |offset|·π/(2·smaller radius), `bend` (G), with `bend_deg` = atan G — the same
- number as `fold_ratio`, named for what it does: at 1 a line tilts 45°, and a region `--on-fold
- lower` lowered moves just under it. A round region moving along a radius has G = 1 − D, but a
- region moving along its long axis keeps D high while G stays near 1, so neither stands for the
- other. And where two regions overlap, `video-sway` moves each pixel by the larger of their
- weighted moves (by the larger weight where they move by one gain), so across the curve where the
- two are equal the move's gradient jumps from one region's to the other's and a straight line
- bends there: `seams`, the largest jump on that curve — the norm of the difference of the two
- gradients, each the offset times the weight's gradient — and its angle `deg`. It is looked for
- along rows a quarter pixel apart, between points inside both ellipses where the larger move
- changes hands, and found there by halving. A held region has no seam. Quality is read from these
- three, not from `fold.ratio`; a floor lowers the bend and the seam only as it lowers the gain.
-- **The record names what it was read from.** It holds no path, no time and nothing of the
- machine: the same loop asked the same way writes the same record, byte for byte, anywhere.
- `input_id` is the same before and after `video-sway` is run on the loop, and another after a
- new cut, an alignment, a changed region or setting (`read_on` and `stretch_floor` among them), or
- another engine version — what somebody
- saw on one cut's boards is not evidence for another cut. `--scale` and `--columns` change the
- boards and their sha256, not `input_id` and not a number of the record but the `box`es.
- `pixels_sha256` is over a board's pixels (RGB, row by row), so another PNG writer gives the same
- one; `sha256` is the file's. The offsets, ratios and areas are rounded to 4 places.
-- **The boards** hold every cell of the strip in order, `--columns` to a row, each under its
- number (the first cell is 0), over a flat grey, `--scale` board pixels to a cell pixel. Each
- region's carried ellipse is ringed in its colour, dashed with black. The ring is on the board
- pixels just outside the ellipse — the first the move does not touch — so inside an ellipse the
- cell shows whole (but for another region's ring crossing it), and at `--scale 2` or more no
- cell pixel is covered whole. `follow-inspect.source.png` has the cells as cut;
+- `follow-inspect.source.png` has the cells as cut;
`follow-inspect.moved.png` has them as `video-sway` would write them, laid and ringed alike.
They are two files so that whoever says what is inside an ellipse can be given the cells as cut
alone, without the answer beside them.
@@ -1548,37 +675,14 @@ sprite-gen video-set-sheet --loop-dir S/loop --view front --loop-dir W/loop --vi
(`@left` faces the screen's left). A strip turned over to face the other way is a direction like any
other. A direction given twice, a front or back view with a side (its picture turned over is not a
compass direction) and a count of `--view` other than the loops' are refused before anything is written.
-- **One cell.** Each strip is laid on its pivot — the one its sidecar declares (`anchor`: the foot line
- under `video-loop --anchor feet`), else its bottom centre, where `video-loop` stands the feet — and the
- cell is the union of every pixel of every cell of every direction (and of the centre picture), centred
- on that pivot: every cell's pivot is its bottom centre (`anchor` in the record), and no pixel is dropped.
-- **One ground line.** `baseline_y` is the lowest body pixel of any cell of any direction — body as
- `video-loop` reads one, alpha 8 and over: that pixel is row `baseline_y − 1` of its cell. A fainter
- pixel (a soft shadow under the feet) is no body: it is kept, and the cell reaches below the line to hold
- it, so `cell_h` is `baseline_y` or more. A direction whose strip leaves room under its feet stands that
- much above the line, as cut: each row's `body_bottom_y` says where its lowest body pixel ends.
-- **No row scaled.** Every cell of the sheet is the strip's own cell, pixel for pixel. One size across
- the set is `video-loop --body-height`'s; the sheet never sizes a direction on its own. A board that
- shows the sheet smaller scales it as one, and stands each cell's `baseline_y` on its ground.
- **The centre picture** (`--center`): a transparent still — the set's base, the picture a board shows in
- its middle. It is scaled to the rows' standing height (the median of their `body_h`, against the
- still's own standing height read as `video-loop` reads one: its box at alpha 8 and over), its body
- stood on the ground line and centred on the pivot, alone in a cell of the sheet's size
- (`<name>.center.png`); a fainter shadow under it is kept below the line. A
+ its middle. A
still with no transparent background is refused (cut it off first: `sprite-gen cutout`), and so are
rows without `body_h` beside one.
- **Lengths.** Loops of different lengths, in frames or in frame time, are laid all the same, one frame
a column and the shorter rows' last cells empty; the record says `same_length: false` and a warning line
names each direction's length. `video-cycle-align` gives a set one cycle length.
-The record, `<name>.sheet.json` (kind `sprite-gen-video-set-sheet`, schema 1): `sheet`, `order` (the
-rows' codes), `columns`, `cell_w`, `cell_h`, `baseline_y`, `anchor` (`[cell_w / 2, baseline_y]`),
-`same_length`; `rows`, one per row with its `row`, `code`, `view`, `frames`, `delay_ms`, the strip's
-`name`, the loop directory as `input`, the strip's `strip_sha256`, `body_h` and `body_bottom_y`; and
-`center` — null, or the picture's `png`, `input`, `sha256`, its own `standing_h`, the rows' `body_h` it
-was scaled to, the `scale` and its `box` in the cell. The loop directories are only read: no strip,
-frame or frame time is changed.
-
## 8. A walk or run that stops — `video-stop`
A game character that stops running jumps from a running frame straight to its standing picture. Frames made between them (RIFE in-betweens) are the wrong tool: as [loop repair](loop-repair.md) notes, RIFE smears a changed appearance, and where two drawings are too far apart for the flow, legs come out as one shape of fill; a running frame and a separately drawn standing picture are both. Every walk or run clip filmed from a still (image to video) already holds a filmed "stand → set off" at its start: the body stands, sets off, and runs into the gait the loop is cut from. Played backwards from the frame where the clip reaches the loop, that start is the body running into the standing still — filmed frames, no frame made between two others, ending on the clip's first frame, the still as filmed. `video-stop` cuts this as a one-shot clip beside the loop: a strip, its sidecar (`loop: false`, `hold_last: true`), a GIF, a WebP and a report. Played backwards, motion runs backwards (a cape, a planted foot), which is a cost to look at. This example cuts a run's stop and plays it twice as fast:
@@ -1587,67 +691,10 @@ A game character that stops running jumps from a running frame straight to its s
sprite-gen video-stop --frames-dir run/frames/keyed --loop run/loop/run.strip.json --out-dir run/stop --speed 2
```
-- **The rest.** The clip's opening run of frames within `SAME_POSE` (0.35 steps) of its first frame by engine pose distance (`gait_fallback.poses`: 48 px thumbnails cut about the feet). A step is the clip's median neighbouring-frame pose distance in the loop's window on the clip as filmed, whether cut or aligned. The stop ends on the first frame itself, the still as filmed.
-- **The entry and the cell left from.** The first frame after the rest within `SAME_POSE` of a loop cell, searched to the end of the loop's window (`source_cut`): where the clip reaches the loop. The stop leaves from the nearest cell (`from_cell`) — a player shows the loop through that cell, then the stop — and its first frame is the clip frame before the entry. The entry frame is laid on its cell within 12 % of the cell height (coverage difference, quarter-size search then to the pixel); the first frame is searched across a cell's width.
-- **The seam and its refusal.** Reported in steps from the leaving cell into the stop's first frame. Past the jump line (1.4 steps, `stop.SEAM_MAX`, overridden by `--seam-max`), the stop is refused: "the clip reaches the loop by a jump".
-- **Another motion and its refusal.** A setting-off goes one way, from the still into the loop: the body does not come back to a pose it has left. `video-stop` finds, among the run-up's frames, the one that comes nearest back to the pose of an earlier frame of the clip (the still or one of the rest's frames, or an earlier frame of the run-up itself), counting only earlier frames the body went `TURN_BACK_AWAY` (one step) or more away from in between. That nearest comeback is recorded in the report as `turn_back` (fields `frame`: the frame that comes back; `back_to`: the earlier frame whose pose it is back at; `steps`: how far it still is from that pose; `away_frame`: the farthest frame between; `away_steps`: how far that one went), alongside `turn_back_away` (the one-step threshold); `turn_back` is null when the body never leaves any pose by a step. If that comeback is within `SAME_POSE` (0.35 steps), the run-up turned back: it holds another motion — for example a gesture that ends where it began (an arm waved, a crouch, then standing again before the run sets off), a motion done again, or a run going round a cycle of its own. The stop would play it backwards, so the command refuses, however short the motion is (two frames are enough), naming the three frames: "the run-up turns back — another motion, that the stop would play backwards". This is the only judgment that refuses another motion; the run-up's length plays no part in it, and `--run-up-max` cannot let it through. A motion carried one way into the run (an arm drawn in, a crouch, a turn before the first stride) is the setting-off's own and is not refused; the pose distance cannot tell it from a gesture carried one way into the run.
-- **The run-up and its refusal.** The frames between the rest and the entry that the stop plays before the still. A body sets off into its gait within about a cycle; a run-up longer than `RUN_UP_MAX_CYCLES` (1.5 cycles, `source_cut.length` frames, overridden by `--run-up-max`) plays strides unlike the loop's — a run of its own before the loop's, or a start slower than a setting-off — and is refused: "strides unlike the loop's, that the stop would play backwards". The seam refusal (overridden by `--seam-max`), the another-motion refusal and the run-up refusal can all be named in one message.
-- **Drift.** A body setting off may move across its frame, sliding into the still if played back as filmed. Two frames are laid where the loop stands: the entry on its cell (least coverage difference), and the first frame with its lowest body row on the loop's ground and across where it covers the loop best (mean coverage of the cells). Frames between are moved by a straight share of the difference per step of the stop, none at the entry and all on the first frame: drift is taken out without moving any frame by its own pose. Because a standing pose is laid on a running one by coverage, a run leaning or reaching away moves the still a few pixels — a straight glide over the stop, the same with drift or without it — and drift not straight over the frames shown leaves a little of itself.
- **Speed and the frame cap.** `--speed 2` plays every other frame (still kept last); `--max-frames N` (at least 2) spaces N frames evenly from the first to the still. Each frame is shown one clip tick (`--fps` defaults to the loop's `source_cut` fps, else 24). Strips wider than 32,000 px are refused; pass `--max-frames` or `--speed 2`.
-- **The ghost screen.** Frames shown pass the ghost screen delivered on every loop path (`interpolation_quality`), read on them as filmed, as `video-loop` reads its cut. Any ghost is named in the report and warned on stderr by cell and clip frame, and kept as filmed.
-- **Cell placement and anchor.** Measured on one canvas in loop cell coordinates, the stop's cell holds every shown frame and the loop's cell, centred across on the loop's cell with the same bottom unless a frame reaches lower (`loop_cell_origin`). No frame is scaled (the loop's scale). The sidecar's `anchor` is the loop's pivot there (its declared `anchor`, else bottom centre), so drawing at the pivot stands where the loop stood.
-- **Refusals and source warnings.** Refuses loops that play once (`loop: false`), are not walks or runs, sidecars missing `source_cut` (source, start, length), frame folders shorter than the loop's window reaches, `--speed` other than 1 or 2, `--max-frames` under 2, or clips whose frames after the rest never reach a loop cell within `SAME_POSE` before the window ends ("these frames are not the loop's clip"). Each refusal exits non-zero with `status: "failed"` and the error in `<name>.stop.report.json`. Keyed frames not byte-for-byte identical to the loop's cut warn on stderr (the stop is still written; the entry is found by pose, so inspect the stop), as do ghosts or an unreadable ghost screen.
-
-The outputs are `<name>.strip.png`, `<name>.strip.json`, `<name>.gif` (plays once), `<name>.webp` (plays once), and `<name>.stop.report.json` (or `--report PATH`). The GIF and WebP are reopened and checked as `video-loop` checks its own. The sidecar records `frames`, `w`, `h`, `delay_ms` (1000 / fps), `kind: "stop"`, `state: "stop"`, `loop: false`, `hold_last: true`, `end_frame`, `events: []`, `anchor`, `loop_cell_origin`, `body_h`, `body_src_h`, `scale`, `cycle_frames`, `cycle_seconds`, `from_loop` (`strip_sha256`, `state`, `frames`, `w`, `h`, `from_cell`), `source_cut` (`source`, `frames`, `entry`, `rest_end`), `speed`, and `seam_steps`. The report records `status`, `error` (on refusal), `source` (`same_as_loop`), `loop_cut` (`start`, `length`, `cells`, `state`), `step`, `loop_cell_step` (which differs for an aligned loop), `same_pose`, `turn_back_away` (the one-step threshold), `seam_max`, `run_up_max_cycles`, `rest` (`end`), `to_rest` and `to_loop` (each frame's distance in steps to the first frame and nearest cell), `entry` (`frame`, `match`, `from_cell`), `seam` (`steps`, `from_cell`, `into_frame`, `max`), `turn_back` (`frame`, `back_to`, `steps`, `away_frame`, `away_steps`; null when the body leaves no pose by a step), `run_up` (`frames`, `cycles`, `max_cycles`), `played`, `shown`, `frames_shown`, `seconds`, `drift` (`leave`, `stand`, `clip_px`, `ground`, `ground_in_cell`, `ends_on_ground`), `ghost_screen` (`frame`, `clip_frame`), `strip`, `gif`, and `webp`.
-
-## What the rules were measured on
-
-Every threshold above (the 15 % period tolerance, the 2.0 seam gate, the 0.15
-periodicity floor, the state windows, the tall/wide canvas rooms, the 2 s stagger) was
-set on one hand-run set of 15 loops (3 directions × 5 states, one SD biped) on
-2026-09-08 and every loop of that set passed the gates as written. On 2026-09-09 the
-same rules were run against two deliberately different bodies — a quadruped and a
-legless blob, generated for the test — with idle, walk and jump each. Two rules turned
-out to be *that biped's* rules and were generalized: the walk window floor (the blob's
-bounce was faster than any gait) and the assumption that an action state repeats (the
-quadruped jumped once). Everything else held unchanged, and the original biped set
-still resolves to the same periods afterwards. The subjects are not in this repository;
-the synthetic fixtures under `tests/video/` pin every rule named here.
+
+The outputs are `<name>.strip.png`, `<name>.strip.json`, `<name>.gif` (plays once), `<name>.webp` (plays once), and `<name>.stop.report.json` (or `--report PATH`).
## Related
- [docs/README.md](README.md) — documentation index
-
-### One-shot length is the clip's own fact
-
-The periodic window (`LoopProfile.min_frac` / `max_frac`) bounds *repeats*. A one-shot
-(`--cycle one-shot`, or the `auto` failover for action states) has no repeat to bound:
-the excursion is as long as the model performed it. `detect_one_shot` therefore no longer
-refuses an excursion shorter than the periodic window's lower edge — only a degenerate
-cut under `ONE_SHOT_MIN_LEN` (4 frames) or one longer than the clip is refused. A short
-set-down, a nod, a flinch come back as the frames they are.
-
-### `--anchor feet` — undo in-canvas drift
-
-"Stays centered in the frame" is a request, not a guarantee: the model may walk the
-subject across an in-place canvas, and the union crop that `build_strip` uses keeps that
-drift inside every cell, so a runtime that places the strip by its cell box sees the body
-slide back and forth once per cycle. `--anchor feet` (on `video-loop` and `video-set`)
-removes that drift and nothing else. Drift is a slow translation and a gait is periodic,
-so a straight line fitted to the body's centre (the mean x of every opaque pixel) across
-the cycle carries the drift and not the step. Each cell is shifted by that line only,
-so every cell stands on the same **mean** foot line — the mean x of the opaque pixels in
-the lowest `FOOT_BAND` (8 %) of each frame's bbox, averaged over the cycle.
-
-Do not pin each frame's own foot line. In an in-place walk one foot is lifted out of the
-floor band every step, so the per-frame foot line jumps to the planted foot by about the
-stride; pinning it makes a body that stood still lurch back and forth by that much. The
-first version of this option did exactly that, and the synthetic lifting-leg walker in
-`tests/video` pins the rule.
-
-The strip meta gains `foot_anchor`, `drift_px` (the drift removed across the cycle, in
-source pixels), `foot_sway_px` (how far the planted foot moves within the gait — kept, only
-reported) and `foot_x` (the mean foot column inside every cell), plus the spec loader's
-`anchor` as `[foot_x, h]` so a scene stands the sprite on its foot line; `video-set`'s
-table row carries `drift_px`. The default stays `none`: existing strips do not change,
-and `drift_px` / `foot_sway_px` are 0 when they were not measured.
diff --git a/docs/video.md b/docs/video.md
index 8797990..a65265c 100644
--- a/docs/video.md
+++ b/docs/video.md
@@ -5,57 +5,31 @@
`sprite-gen video` animates one still into a short mp4 through **Grok Imagine**
(xAI `POST /v1/videos/generations`). It is the video counterpart of
[`sprite-gen gen`](gen.md): one call = one still (+ prompt) → one **verified** mp4
-on disk plus a machine-readable report. The sprite-gen skill routes standalone
-video requests here from any agent engine.
+on disk plus a machine-readable report.
The same engine also pins a **last frame**, guides a clip with **reference
images**, **extends** an existing clip (`video-extend`), **edits** one with a
prompt (`video-edit`) and **asks again** for a generation a run left unfinished,
-by its `request_id` (`video-resume`). The mode table below is the design memo for those modes
-(2026-09-13); the pipeline verbs in [video-pipeline.md](video-pipeline.md)
-(`video-canvas` → `video` → `video-frames` → `video-loop`, `video-set`) keep
-calling `sprite-gen video --image …` exactly as before and know nothing about
-the new modes.
+by its `request_id` (`video-resume`).
No credential is shipped with this repository. You bring your own, in one of two
forms, and every run reports which one it used.
## Modes — which flags call what
-Measured 2026-09-13 with the subscription login (`grok-login`) and the direct
-REST calls below (vault `projects/sprite-gen/_assets/grok-video-mode-probe-2026-09-13/report.md`);
-limits from docs.x.ai `model-capabilities/video/*` read the same day.
-
| Verb / flags | Endpoint · model | Body fields | Options allowed | Local pre-checks (before any call) | `mode` |
|---|---|---|---|---|---|
-| `video --image A` | `POST /v1/videos/generations` · `grok-imagine-video-1.5` (`--model` free) | `image{url}` | duration 1–15, resolution, aspect, audio | still exists; unchanged contract (body snapshot pinned by test) | `image-to-video` |
+| `video --image A` | `POST /v1/videos/generations` · `grok-imagine-video-1.5` (`--model` free) | `image{url}` | duration 1–15, resolution, aspect, audio | still exists | `image-to-video` |
| `video --image A --last-frame B` | same · 1.5 only | `image{url}`, `last_frame{url}` | same | both stills exist; classic `grok-imagine-video` rejected | `first-last` |
| `video --last-frame B` | same · 1.5 only | `last_frame{url}` | same | classic rejected | `last-frame` |
-| `video --reference X [--reference Y …]` (+ optional `--image`) | same · 1.5 (classic accepts references alone, measured 2026-09-13, but not `--image` + references) | `reference_images:[{url}…]` (+ `image{url}`) | duration, aspect, audio; resolution **480p/720p only** | 1–7 references; prompt tags `<IMAGE_n>` with `0 ≤ n < count` (0-based); `--resolution 1080p` rejected; classic + `--image` + references rejected | `reference` |
-| `video-extend --video in.mp4 --duration N` | `POST /v1/videos/extensions` · **`grok-imagine-video` forced** (1.5 answers `400 Video extension is not supported for this model`) | `video{url}`, `duration` | duration 2–10 (extension length only; default 6). No resolution / aspect / model flags: output inherits the input's, capped at 720p | `.mp4` with an `ftyp` box; ffprobe duration 2–15 s | `extend` |
-| `video-edit --video in.mp4` | `POST /v1/videos/edits` · **`grok-imagine-video` forced** (1.5 answers `400 Video editing is not supported for this model`) | `video{url}` | none of duration / resolution / aspect / model: output inherits the input's, capped at 720p | `.mp4` with an `ftyp` box; ffprobe duration ≤ 8.7 s | `edit` |
+| `video --reference X [--reference Y …]` (+ optional `--image`) | same · 1.5 (classic accepts references alone but not `--image` + references) | `reference_images:[{url}…]` (+ `image{url}`) | duration, aspect, audio; resolution **480p/720p only** | 1–7 references; prompt tags `<IMAGE_n>` with `0 ≤ n < count` (0-based); `--resolution 1080p` rejected; classic + `--image` + references rejected | `reference` |
+| `video-extend --video in.mp4 --duration N` | `POST /v1/videos/extensions` · **`grok-imagine-video` forced** | `video{url}`, `duration` | duration 2–10 (extension length only; default 6). No resolution / aspect / model flags: output inherits the input's, capped at 720p | `.mp4` with an `ftyp` box; ffprobe duration 2–15 s | `extend` |
+| `video-edit --video in.mp4` | `POST /v1/videos/edits` · **`grok-imagine-video` forced** | `video{url}` | none of duration / resolution / aspect / model: output inherits the input's, capped at 720p | `.mp4` with an `ftyp` box; ffprobe duration ≤ 8.7 s | `edit` |
| `video-resume --request-id <id>` | **no POST** — `GET /v1/videos/{id}` only; the model is whatever the request was made with | — | none: the request is the one an earlier run submitted | the id is letters, digits, `.`, `_`, `-` | `resume` |
Invariants:
-- **The `--image`-only body is byte-for-byte what it was** (`model`, `prompt`,
- `duration`, `resolution`, `image.url`, optional `aspect_ratio` /
- `generate_audio`). A test snapshots it; the pipeline (`video-set` and the
- four pipeline verbs) is not touched by this work.
-- One of `--image`, `--last-frame`, `--reference` is required; `--image` is no
- longer required on its own.
-- `<IMAGE_n>` is **0-based**: `<IMAGE_0>` is the first `--reference`. The probe's
- three-reference run tagged `<IMAGE_0>…<IMAGE_2>` and the clip picked up the
- third image's scene under `<IMAGE_2>`; the docs' prose says the same
- ("`<AUDIO_0>` … with `<IMAGE_0>` … when you also pass images") while its code
- samples write `<IMAGE_1>`. A tag outside `0..count-1`, or any tag with no
- references, is refused locally.
-- Extension and editing inherit resolution and length from the input and take
- **no** `--resolution` / `--aspect-ratio` / `--model`; `video-extend` verifies
- that the returned clip is at least as long as the input (the API returns
- original + extension as one clip: 15.04 s in → 20.04 s out in the probe).
-- The report (`sprite-gen-video-report`) gains `mode` and `inputs` (local paths
- by role, never URLs or tokens); every existing field stays.
+- `<IMAGE_n>` is **0-based**: `<IMAGE_0>` is the first `--reference`.
## Setup — pick one credential
@@ -68,19 +42,11 @@ Resolution order is fixed for both images and videos: **the Grok subscription
login wins**, even when `XAI_API_KEY` is set. `GROK_HOME` relocates `~/.grok`.
Only when no login file exists can the configured API key use console credits.
An expired, unreadable, corrupt or API-rejected login stops the request; it never
-switches to API credit. A clip that does leave on `XAI_API_KEY` says so on stderr
-before it uploads — one line per submitted job, naming the duration and resolution
-it is billed on; the subscription route stays silent. An empty API key is ignored when the login is usable,
-but is an error when no login exists. With neither credential, the run stops
-with both setup paths spelled out.
+switches to API credit.
### The login token expires — and this tool does not refresh it
-The grok CLI stores an OIDC access token that lasts about six hours. Any
-long-lived grok session refreshes it proactively about five minutes before
-`expires_at` (2026-09-13 measurement: a resident session rewrote `auth.json` at
-00:15Z for a 00:20Z expiry), so the token only actually expires when no grok
-process has run for hours. `sprite-gen video` reads `expires_at` **before
+`sprite-gen video` reads `expires_at` **before
uploading anything**; if it has passed, the run fails with the refresh
prescription instead of gambling on a 403 mid-upload:
@@ -89,28 +55,6 @@ xai: the grok login token expired at 2026-09-08T10:56:34Z (now …); nothing was
refresh it with `grok models` run from an empty directory (e.g. `cd "$(mktemp -d)"`) — a non-agent round-trip; never a bare prompt like `grok -p …`, which starts the coding agent in your cwd — or sign in again with `grok login`. This tool never rewrites ~/.grok/auth.json itself.
```
-Why `grok models` and not a prompt: `grok -p ok` is not a ping. It starts the
-coding agent in the current directory, which reads it, may write files and may
-call paid APIs on its own (2026-09-13: run inside a worktree it overwrote a
-script and spent a video generation). `grok models` only runs the CLI's startup
-auth path (`auth: silent refresh` in `~/.grok/logs/unified.jsonl`), prints the
-model list and exits, writing nothing outside `~/.grok`. Run it from an empty
-directory anyway. If it prints a login error instead of the model list, the
-refresh token is gone too: `grok login`.
-
-Why not refresh it here: `auth.json` is the grok CLI's file, the refresh token in
-it may rotate, and a second writer would break the login the user relies on
-everywhere else. The same shape as codex's: `sprite-gen` reads `codex login status` (`codex_provider.codex_login`) and never writes codex's login either.
-
-### Direct API transport
-
-Grok Build's built-in `image_to_video` tool posts without `output.upload_url`, and
-on Zero-Data-Retention teams the API answers `HTTP 400 — Zero Data Retention teams
-must provide output.upload_url for video generation`. The same login calling
-`/v1/videos/generations` directly (no `output.upload_url`) succeeds and bills the
-Imagine quota (verified 2026-08-22, re-verified 2026-09-08). So this engine calls
-the API itself and never routes through the agent-side tool.
-
## CLI
### `sprite-gen video` — generations (image-to-video, first/last frame, references)
@@ -133,75 +77,8 @@ sprite-gen video \
At least one of `--image`, `--last-frame`, `--reference` is required. The mode is
derived from the flags (see the table above) and written to the report as `mode`.
-Backward-compatible wrapper: `$SPRITE_GEN_ROOT/.venv/bin/python $SPRITE_GEN_ROOT/scripts/generate_sprite_video.py …` (same args).
-
-What happens, in order:
-
-1. Validate the request (prompt, stills, duration, resolution, aspect ratio, the
- mode rules: ≤ 7 references, `<IMAGE_n>` tags in `0..count-1`, no tag without a
- reference, no 1080p with references, no `last_frame` / `image`+`reference` on the
- classic model) and resolve the credential — all before any network call.
-2. `POST /v1/videos/generations` with `model`, `prompt`, `duration`, `resolution`,
- then `image.url` / `last_frame.url` / `reference_images[].url` as base64 data
- URLs, optional `aspect_ratio` / `generate_audio`. A `429` — xAI's rate limit, a
- request it did not take — is sent again, twice at most, after 8 s and 16 s, while
- the wait leaves some of the poll timeout (step 3); a wait that would reach it is not
- waited, one that woke at it or past it sends nothing, and the run ends on that `429`
- ([a refused request sent again](gen.md#a-refused-request-sent-again)). A `401/403`
- names the credential source and its fix; any other reply without a `request_id`
- fails with the API's own error text.
-3. `GET /v1/videos/{request_id}` every 4 s until `status` is `done`. `failed`,
- `expired` or a non-2xx poll fails loudly — except a poll answered `429` or `500`,
- `502`, `503`, `504`, `529`, or one that gets no answer it can read (the connection failed
- or timed out; the answer broke on the way — a body shorter than its
- `Content-Length`, a status line that is not one, a refusal's body cut the same way;
- or a `200` body that is not JSON): the request was accepted, so that poll is asked
- again on the same `request_id` (a new POST would buy the clip twice; a GET buys
- nothing), after a wait that doubles from 8 s up to 60 s while the polls fail and goes
- back to 4 s on an answer — the doubling every direct provider call waits by
- ([a refused request sent again](gen.md#a-refused-request-sent-again)). A `[video] poll N of generation <id> was refused (429);
- asking again in 8s` line — or `… got no answer (timed out); asking again in 8s`,
- the reason `IncompleteRead(10 bytes read, 190 more expected)` or `response was not
- valid JSON` for an answer it could not read — goes to stderr each time.
-
- The poll timeout (`SPRITE_GEN_VIDEO_TIMEOUT_SECONDS`, default 600) is the one time
- limit of the request. It counts from the POST's first send and bounds the waits before a refused
- POST goes again (step 2), the polls, their waits and the clip's downloads (step 4) alike:
-
- - Each poll reads only what is left of it. One whose answer stalls, or comes too
- slowly for its 120 s read timeout ever to fire, is cut when the timeout comes and
- counts as a poll that got no answer (`timed out`).
- - A poll whose wait would reach the timeout is not asked, nor one whose wait woke
- at it or past it (a sleep may wake late). A generation still pending, refused or
- unanswered then is *unfinished* (below) at once, on its last poll as it came.
- - The POST is not cut by it: its answer is the one way to the `request_id`, under its
- own 120 s read timeout. One answered after the whole timeout is unfinished before
- any poll.
-
- So a caller that kills the run at a hard limit gets the `request_id` back when it
- sets the timeout under that limit, with room for the process to start and for the
- POST. A poll answered `401` or `403` — the credential stopped working after the POST,
- typically a login that expired — is unfinished at once. No clip is written on any
- failure path.
-4. Download `video.url`, verify the bytes start with an mp4 `ftyp` box, then move
- the file into `--out` atomically (`.part` staging). The clip is made by now and may
- be billed, so a download that fails never ends the run without its `request_id`, and
- a done poll that names no URL to download (none, an empty one, anything but an
- `http(s)://` string) is *unfinished* too. A download that gets no answer it can read
- (the connection refused or timed out, the body cut short of its `Content-Length`) or
- that the clip's host refuses with `429`, `500`, `502`, `503`, `504` or `529` is downloaded
- again, after 8 s and then 16 s — three downloads in all, within the poll timeout: each
- reads only what is left of it, so one that stalls or whose bytes come too slowly is
- cut when it comes (`timed out`), and one whose wait would reach it, or woke at it or
- past it, is not tried. A `[video] download N of generation <id> got no answer
- (<reason>); downloading again in 8s` (or `… was refused (503); …`) line goes to
- stderr before each. One still failing,
- one refused with another status (a `401` or `403` is asked once more with the bearer
- token first), a download the timeout leaves no time for, or bytes that are not an mp4
- end the run *unfinished* (below).
-
Reference-to-video tends to lock the opening composition to a referenced scene
-image (probe m3: the clip opened on the third reference's framing), so put
+image, so put
character references first and scene references last, or leave the scene out.
### `sprite-gen video-extend` — continue a clip
@@ -215,15 +92,7 @@ sprite-gen video-extend \
[--report longer.report.json]
```
-Model is fixed to the classic `grok-imagine-video` (`grok-imagine-video-1.5`
-answers `400 Video extension is not supported for this model`). There are no
-`--resolution` / `--aspect-ratio` / `--model` flags: the output inherits the
-input's, capped at 720p. The input is checked locally (`.mp4`, `ftyp` box,
-ffprobe length) before anything is uploaded; ffprobe missing is an error, not a
-skipped check. The API returns **input + extension as one clip** (15.04 s in →
-20.04 s out); a result shorter than the input is refused and not written. The
-report carries `mode: "extend"`, `inputs.video`, `input_duration` (ffprobe
-seconds) and `duration_requested` (the seconds added).
+The API returns **input + extension as one clip**.
### `sprite-gen video-edit` — change a clip with a prompt
@@ -235,10 +104,6 @@ sprite-gen video-edit \
[--report edited.report.json]
```
-Same fixed classic model, same inherited resolution / aspect / length (the probe's
-8.00 s input came back 7.71 s — the API trims the tail). Inputs over 8.7 s are
-refused locally with an ffmpeg trim hint; there is no `--duration` at all.
-
### `sprite-gen video-resume` — ask again for an unfinished generation
```bash
@@ -248,44 +113,20 @@ sprite-gen video-resume \
[--report clip.report.json]
```
-No POST: it polls `GET /v1/videos/{id}` exactly as step 3 above (the same retries,
-backoff and poll timeout, counted from the first poll and bounding the downloads too), then downloads, verifies and
-publishes the clip as step 4. Nothing is submitted, so nothing is bought twice and the
-`XAI_API_KEY` route prints no charge notice. Run it on the credential that submitted
+Run it on the credential that submitted
the request — the unfinished report's `auth_source`; refresh an expired login first.
-- The report is a `sprite-gen-video-report` with `mode: "resume"`, the same
- `request_id`, `inputs: {}` and `duration_requested: null`; `model` and
- `duration_reported` are what the finished poll says.
- Cut short again — the timeout, a rejected credential, or a download that failed —
it is unfinished on the same id, `verb: "video-resume"` (below), and can be resumed
again. Each resume polls afresh, so a clip whose download failed is fetched from the
URL the new poll names.
-- A request xAI does not know (`404`), or one that failed or expired, ends with its
- status like any failed poll.
-- The clip is checked as an mp4 (`ftyp` box) only: `video-extend`'s length rule needs
- the input clip, which this verb does not take.
-- The id is refused before any call unless it is letters, digits, `.`, `_` and `-`
- (it goes into the URL path).
-
-### The report
-
-`sprite-gen-video-report` carries `auth_source`, `model`, `mode`, `request_id`,
-`inputs` (local paths by role: `image`, `last_frame`, `reference_images`,
-`video`), `bytes`, `host`, requested/reported duration (`input_duration` for
-extend / edit), resolution, aspect ratio, audio flag, `elapsed_seconds`, and
-`polls`, `polls_refused` (how many of `polls` xAI answered 429 or 5xx, each asked
-again), `polls_unanswered` (how many got no answer they could read, each asked
-again) and `downloads` (how many downloads the clip took, the last one whole: 1 unless
-one failed). The pre-modes `image` field stays. **Tokens and download URLs are never
-printed or written** — only the download host (`vidgen.x.ai`).
### An unfinished generation
xAI accepted the request and the run ended before it did — the poll timeout came with
its polls still pending, refused or unanswered (or before any poll), xAI rejected the
credential on a poll, or the poll said done and the clip could not be downloaded in
-time or at all, or the poll named no URL to download it from (step 4). It may
+time or at all, or the poll named no URL to download it from. It may
finish and be billed — a clip that is done is made — so the run ends naming the
request and the `video-resume` command that asks for it again, never as a refusal to
send again:
@@ -304,81 +145,21 @@ video: generation <id> is done, but its poll named no video url to download; the
video: generation <id> is done, but its download brought 34 bytes that are not an mp4 (no ftyp box); the clip is made and may be billed — ask for request_id=<id> again with `…` instead of submitting a new request; nothing was written
```
-The line carries no `(HTTP <n>)`, the status of a refusal line (docs/gen.md): a caller
-that reads `(HTTP 429)` there sends the request again, which is unbilled only when the
-request was refused. The stderr notes before it say the status in plain digits for the
-same reason. With `--report` the run leaves a
-`sprite-gen-video-unfinished` report there, and nothing on stdout:
-
-```json
-{"kind": "sprite-gen-video-unfinished", "provider": "grok-imagine", "verb": "video",
- "auth_source": "grok-login", "model": "grok-imagine-video-1.5", "request_id": "<id>",
- "out": "/abs/clip.mp4", "polls": 14, "polls_refused": 14, "polls_unanswered": 0,
- "last_poll": {"http": 429, "status": null}, "elapsed_seconds": 600.0}
-```
-
-`last_poll` gains `"error"` (what the transport said: `timed out`,
-`IncompleteRead(10 bytes read, 190 more expected)`, `response was not valid JSON`, …)
-when the last poll got no answer it could read, its `http` then `null`. A run whose
-clip could not be downloaded adds `downloads` (how many were tried) and
-`last_download`, how the last one ended: `http` the status the clip's host refused it
-with, else `null`; `error` what the transport said when it got no answer it could read,
-or `not an mp4 (no ftyp box)` with the `bytes` that came; its `last_poll` is the done
-poll (`{"http": 200, "status": "done"}`):
-
-```json
-{"kind": "sprite-gen-video-unfinished", "provider": "grok-imagine", "verb": "video",
- "auth_source": "grok-login", "model": "grok-imagine-video-1.5", "request_id": "<id>",
- "out": "/abs/clip.mp4", "polls": 31, "polls_refused": 0, "polls_unanswered": 0,
- "last_poll": {"http": 200, "status": "done"}, "downloads": 3,
- "last_download": {"http": null, "error": "IncompleteRead(1048576 bytes read, 3195904 more expected)"},
- "elapsed_seconds": 144.0}
-```
-
-Bytes that came whole and are not an mp4 make the run unfinished, not refused, and
-are not downloaded again:
-
-- They are no verdict of xAI's on the request. Its one content-policy signal is
- `respect_moderation: false` on the done poll, read before any download and refused
- as a content-policy block. Anything else at the clip's URL — an expired link's page,
- a proxy's or captive portal's error page served `200` — is a fault in delivering a
- clip that is made.
-- The `request_id` is the only way back to a clip that may be billed. A refusal would
- leave one path, a new submission, which buys it again; `video-resume` costs a poll
- and polls afresh, so it downloads from the URL the new poll names. If those bytes
- are not an mp4 either, it is unfinished again — never a second purchase.
-- The same URL would bring the same bytes, so the run does not download it again
- itself.
-
-`auth_source` is the credential that submitted it — the one that can ask for it again.
-A report already at that path is replaced, as on success.
-Every verb that polls (`video`, `video-extend`, `video-edit`, `video-resume`) does
-the same, `verb` naming it; a `video-resume` report's `model` is `null`.
-
A POST that gets no answer it can read is not unfinished: no `request_id` could be
read, so it ends at once and is never sent again. Its line is the transport's own
(`xai: request failed or timed out; no automatic retry (the server may have accepted
it)`), or `xai: response was not valid JSON` for a whole answer that is not JSON.
-Python callers catch `xai.TransportError`, a `SystemExit` with that line and the
-transport's words in `reason`.
## Quotas and limits
- Imagine quota is a weekly SuperGrok allowance; when it is exhausted the API
- refuses the POST and the run fails with that message. A refused POST is sent again
- only when xAI's answer is `429`, a request it did not take (step 2); any other refusal
- is never sent again here — the provider may have taken it. A poll of an accepted
- request is asked again (step 3).
+ refuses the POST and the run fails with that message.
- A refused request or a failed poll names the provider's code after the status,
`(HTTP 400) code=invalid_argument`, read from a top-level `code` or the `error`
object. `invalid_argument` covers moderation and bad parameters alike, so it is
not called a content-policy refusal; a clip that comes back `done` with
`video.respect_moderation: false` is:
`<verb>: generation <id> refused by the provider's content policy (HTTP 200) respect_moderation=false; nothing was written`.
-- Duration 1–15 s, resolutions 480p/720p/1080p, the seven aspect ratios above —
- from the xAI video docs as of 2026-09-08. Reference-to-video: ≤ 7 images, 720p
- max; extension: input 2–15 s, 2–10 s added; editing: input ≤ 8.7 s (docs as of
- 2026-09-13). A value outside those is rejected locally before the call.
- Output is whatever the model returns (typically H.264 mp4 with audio unless
`--no-audio`). Downstream frame extraction is a separate step and not part of
this command.
@@ -386,4 +167,3 @@ transport's words in `reason`.
## Related
- [video-pipeline.md](video-pipeline.md#a-clip-from-a-video-mcp-on-your-agent--zcre) — a clip your agent makes with a video MCP (ZCRE) instead of this command
-- [docs/README.md](README.md) — documentation index