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: keep the video-pipeline rules, drop the operator set they were measured on

Soohong Kim261cb8ae9e12
diff --git a/CHANGELOG.md b/CHANGELOG.md
index ae5255a..6a58a26 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -5,7 +5,7 @@ All notable public changes to `sprite-gen` are recorded here. Versions track the
## Unreleased (v2.0.0) - Video to Sprite
- Added the `sprite_gen/video` domain: `sprite-gen video-canvas` (state canvas — tall for jumps, wide for attacks, square otherwise; the still's corner key fills the padding), `sprite-gen video-frames` (ffmpeg extraction + cutout keying with an edge-contact gate), `sprite-gen video-loop` (global-period cycle detection, strip with `body_h` metadata, 1-bit-alpha GIF, `img2webp -exact` WebP, seam and periodicity gates, output re-verification) and `sprite-gen video-set` (directions × states with staggered starts and a bounded HTTP 429 retry, per-item reports and a table).
-- Declared `ffmpeg` and `img2webp` as required binaries for the video pipeline; `docs/video-pipeline.md` records the contract and the 2026-09-08 measurements it comes from. A new domain plus new required binaries is why this is a major version.
+- Declared `ffmpeg` and `img2webp` as required binaries for the video pipeline; `docs/video-pipeline.md` records the contract and the rules behind it. A new domain plus new required binaries is why this is a major version.
- Slimmed `SKILL.md` into a route-first hub (still / atlas / video-to-loop / utilities) under the 24 KB skill budget; the interpreter rationale, the rename gate and the breathing contract moved verbatim to `docs/interpreter.md`, `docs/rename-gate.md` and `docs/breathing.md`.
## v1.61.0 - Image to Video
diff --git a/docs/video-pipeline.md b/docs/video-pipeline.md
index 8c00a63..42acd75 100644
--- a/docs/video-pipeline.md
+++ b/docs/video-pipeline.md
@@ -109,15 +109,10 @@ are idempotent (an existing clip is reused unless `--force`); one failure stops
its item and is listed in `table.md` with its stage and error. Exit code is non-zero
when any item failed.
-## Measured on 2026-09-08 (claudecy SD paladin, 15 loops)
+## What the rules were measured on
-| Direction | State | Period (frames) | Loop seam | Notes |
-|---|---|---|---|---|
-| side | walk | 28 | 0.81 | first pass picked 39 (1.4 cycles) |
-| side | run | 17 | 0.84 | first pass picked 25 (1.5 cycles) |
-| side | jump | 61 | 0.88 | tall canvas; square clip clipped the hair |
-| side | attack | 25 | 1.72 | return pose varies — the weakest state |
-| front | idle | 134 | 0.25 | long window |
-| back | jump | 43 | 0.67 | first tall clip jumped out of frame; "modest hop" prompt |
-
-All 15 passed the 2.0 seam gate; every GIF/WebP verified transparent with `loop=0`.
+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) on 2026-09-08 and every
+loop of that set passed the gates as written. The set itself is operator data and is
+not in this repository; the synthetic fixtures under `tests/video/` pin the same rules.
diff --git a/sprite_gen/video/batch.py b/sprite_gen/video/batch.py
index 8726c60..d304051 100644
--- a/sprite_gen/video/batch.py
+++ b/sprite_gen/video/batch.py
@@ -194,7 +194,7 @@ def add_arguments(parser: argparse.ArgumentParser) -> None:
parser.add_argument("--base", action="append", default=[], help="direction=still.png (repeatable: side=..., front=..., back=...)")
parser.add_argument("--states", default="idle,walk,run,jump,attack", help="comma list of motion states")
parser.add_argument("--out-dir", required=True, type=Path, help="batch root; one folder per direction-state")
- parser.add_argument("--character", help="short subject phrase used in the prompts (e.g. 'The chibi paladin girl')")
+ parser.add_argument("--character", help="short subject phrase used in the prompts (e.g. 'The armored knight')")
parser.add_argument("--duration", type=int, default=6)
parser.add_argument("--resolution", default="720p")
parser.add_argument("--key", choices=("auto", "green", "magenta", "white"), default="auto")
diff --git a/tests/video/test_video_pipeline.py b/tests/video/test_video_pipeline.py
index efab7a2..05b46de 100644
--- a/tests/video/test_video_pipeline.py
+++ b/tests/video/test_video_pipeline.py
@@ -227,8 +227,8 @@ def test_drop_specks_erases_detached_slivers_only() -> None:
def test_prompt_uses_state_and_view_and_optional_character() -> None:
- p = batch_mod.build_prompt("side", "walk", "The chibi paladin girl")
- assert p.startswith("2D game sprite animation. The chibi paladin girl walks")
+ p = batch_mod.build_prompt("side", "walk", "The armored knight")
+ assert p.startswith("2D game sprite animation. The armored knight walks")
assert "seen from the exact side" in p
assert "The character" in batch_mod.build_prompt("back", "jump", None)