Skip to content

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

video-loop: GIF/WebP frame count follows the cycle at a fixed playback rate

Soohong Kim9d14ef9324d6
diff --git a/CHANGELOG.md b/CHANGELOG.md
index d852ae9..13be34e 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -2,6 +2,10 @@
All notable public changes to `sprite-gen` are recorded here. Versions track the `version:` field in `SKILL.md` and `pyproject.toml`.
+## Unreleased (v2.1.0)
+
+- `video-loop` GIF/WebP frame count follows the cycle length at a fixed playback rate (`--gif-fps`, default 12) instead of a per-state fixed count: a 2.5 s jump now gets ~30 frames at ~84 ms instead of 12 frames at 210 ms, so every state plays at the same density. `--n-out` still overrides; the report records `gif_fps`.
+
## v2.0.0 - Four pipelines, one taxonomy
### Highlights
diff --git a/SKILL.md b/SKILL.md
index 322c9cf..1a78b80 100644
--- a/SKILL.md
+++ b/SKILL.md
@@ -1,6 +1,6 @@
---
name: sprite-gen
-version: 2.0.0
+version: 2.1.0
description: "Generate clean 2D game sprites and animation atlases with a component-row pipeline: base identity, numeric sprite-request SSoT, per-state layout guides, image-gen row strips, chroma-key alpha cleanup, connected-component frame extraction, cell-based atlas composition, QA reports, and runtime manifest frame_layout. Its curation webview also serves ANY image-candidate set (icons, logos, generated drafts) — agent chat can't render images, this can: unpack_atlas_run --pngs-dir import, then serve_curation side-by-side compare/pick. Palette-swap bake (`sprite-gen recolor`) turns a base sheet + palette map into N colourway sheets; the curation view blink-compares and adopts a pick into curation.json.recolor.picked. Curation triggers (KR/EN): 큐레이션, 큐레이션뷰, 큐레이션 해줘, 이미지 후보 보여줘/안 보임, 나란히 비교, 골라볼게 띄워줘, curation view, show image candidates side by side, let me pick. Recolor triggers (KR/EN): 팔레트 스왑, 팔레트 베이크, 리컬러, 색깔 바꾸기, 컬러웨이, 색 변형, 팔레트 맵, 색갈이, palette swap, recolor, colourway, colorway, bake variants, palette map."
license: Apache-2.0
depends_on:
diff --git a/docs/assets/hero-paladin-jump.gif b/docs/assets/hero-paladin-jump.gif
index c4737f6..0b7fd2b 100644
Binary files a/docs/assets/hero-paladin-jump.gif and b/docs/assets/hero-paladin-jump.gif differ
diff --git a/docs/video-pipeline.md b/docs/video-pipeline.md
index b071c9f..27899c4 100644
--- a/docs/video-pipeline.md
+++ b/docs/video-pipeline.md
@@ -120,6 +120,10 @@ Outputs:
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).
- `<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 12 fps, floor 4, never more than the cycle holds), so a 2.5 s jump gets ~30 frames
+ and a 1.1 s walk ~13 and both play at the same rate. A fixed 12 made the jump hold each
+ frame 210 ms while the walk held 90 ms (2026-09-09). `--n-out` still overrides.
- `<name>.webp` — same frames, lossless, `img2webp -exact` (Pillow's animated WebP writer
does not pass `exact` and rewrites RGB under transparent pixels).
diff --git a/pyproject.toml b/pyproject.toml
index 4a6d5ba..5338c9c 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -12,7 +12,7 @@ build-backend = "setuptools.build_meta"
name = "sprite-gen"
# Release discipline: keep this package metadata version synchronized with
# SKILL.md's `version:` field in the same release commit.
-version = "2.0.0"
+version = "2.1.0"
description = "Component-row pipeline for clean 2D game sprites and animation atlases"
readme = "README.md"
license = "Apache-2.0"
diff --git a/sprite_gen/video/loop.py b/sprite_gen/video/loop.py
index 5c52b80..ba1ed43 100644
--- a/sprite_gen/video/loop.py
+++ b/sprite_gen/video/loop.py
@@ -45,6 +45,8 @@ STRIP_MAX_HEIGHT = 520
SEAM_RATIO_MAX = 2.0 # loop seam / mean adjacent distance inside the cycle
SPECK_MIN_FRACTION = 0.01 # detached components smaller than this fraction of the body are keying specks
PERIODICITY_MIN = 0.15 # the period must dip at least 15% below the profile mean (flat profile = no repeat)
+GIF_FPS_DEFAULT = 12.0 # GIF/WebP playback density: n_out = cycle_seconds x this, so a 2.5 s jump and a 1.1 s walk play at the same rate
+GIF_FRAMES_MIN = 4
ONE_SHOT_MIN_CONTRAST = 3.0 # one-shot: the excursion peak must stand this far above the rest-pose noise (in MADs)
ONE_SHOT_PAD = 2 # one-shot: rest frames kept on each side of the excursion so the seam is rest -> rest
CYCLE_MODES = ("auto", "periodic", "one-shot")
@@ -54,7 +56,6 @@ CYCLE_MODES = ("auto", "periodic", "one-shot")
class LoopProfile:
min_frac: float # window as a fraction of the clip's frame count
max_frac: float
- n_out: int # frames in the resampled GIF/WebP
why: str
periodic: bool = True # gate: the profile must show a real period (idle is exempt)
one_shot_ok: bool = False # the state is an action that may legitimately happen once (jump, attack) -> one-shot detector may take over
@@ -62,12 +63,12 @@ class LoopProfile:
# State -> detection window. Fractions of the clip length so 6 s and 10 s clips both work.
STATE_PROFILES: dict[str, LoopProfile] = {
- "idle": LoopProfile(0.60, 0.95, 16, "breathing is slow and not strictly periodic; the lowest seam is a long window", periodic=False),
- "walk": LoopProfile(0.06, 0.31, 12, "full gait = two steps; the floor admits a legless body's fast bounce (~13 frames at 24 fps) — the 15% depth rule, not the window, rejects the one-step half period"),
- "run": LoopProfile(0.07, 0.23, 10, "faster gait"),
- "jump": LoopProfile(0.11, 0.45, 12, "crouch-spring-land-return", one_shot_ok=True),
- "attack": LoopProfile(0.11, 0.45, 12, "swing and return to ready", one_shot_ok=True),
- "default": LoopProfile(0.10, 0.45, 12, "generic in-place action", one_shot_ok=True),
+ "idle": LoopProfile(0.60, 0.95, "breathing is slow and not strictly periodic; the lowest seam is a long window", periodic=False),
+ "walk": LoopProfile(0.06, 0.31, "full gait = two steps; the floor admits a legless body's fast bounce (~13 frames at 24 fps) — the 15% depth rule, not the window, rejects the one-step half period"),
+ "run": LoopProfile(0.07, 0.23, "faster gait"),
+ "jump": LoopProfile(0.11, 0.45, "crouch-spring-land-return", one_shot_ok=True),
+ "attack": LoopProfile(0.11, 0.45, "swing and return to ready", one_shot_ok=True),
+ "default": LoopProfile(0.10, 0.45, "generic in-place action", one_shot_ok=True),
}
@@ -339,6 +340,7 @@ def run_loop(
name: str,
report_path: Path | None,
cycle_mode: str = "auto",
+ gif_fps: float = GIF_FPS_DEFAULT,
) -> dict[str, Any]:
if cycle_mode not in CYCLE_MODES:
raise SystemExit(f"video-loop: unknown --cycle {cycle_mode!r}; expected one of {', '.join(CYCLE_MODES)}")
@@ -350,7 +352,6 @@ def run_loop(
n = len(files)
lo = min_len if min_len is not None else max(4, round(n * prof.min_frac))
hi = max_len if max_len is not None else max(lo + 2, round(n * prof.max_frac))
- n_out = n_out or prof.n_out
D = distance_matrix(files)
periodic_attempt: dict[str, Any] | None = None
if cycle_mode == "one-shot":
@@ -373,6 +374,10 @@ def run_loop(
"regenerate the clip, or pass --cycle one-shot for a single performed action"
)
i, L = cycle["start"], cycle["length"]
+ # playback density, not a fixed count: a long cycle gets more frames so every state plays at
+ # ~gif_fps (a fixed 12 made a 2.5 s jump hold each frame 210 ms while a 1.1 s walk held 90 ms)
+ if n_out is None:
+ n_out = max(GIF_FRAMES_MIN, round(L / fps * gif_fps))
n_out = min(n_out, L) # never ask for more distinct frames than the cycle holds
out_dir = out_dir.expanduser().resolve()
@@ -432,6 +437,7 @@ def run_loop(
"periodic_attempt": periodic_attempt,
"cycle_seconds": round(cycle_seconds, 4),
"n_out": n_out,
+ "gif_fps": gif_fps,
"delay_ms": delay_ms,
"resampled_seam_ratio": round(seam_ratio, 4),
"seam_max": seam_max,
@@ -454,7 +460,8 @@ def add_arguments(parser: argparse.ArgumentParser) -> None:
parser.add_argument("--state", help="motion state (idle/walk/run/jump/attack) — selects the detection window")
parser.add_argument("--min-len", type=int, help="override: minimum cycle length in frames")
parser.add_argument("--max-len", type=int, help="override: maximum cycle length in frames")
- parser.add_argument("--n-out", type=int, help="frames in the GIF/WebP (default from the state profile)")
+ parser.add_argument("--n-out", type=int, help="frames in the GIF/WebP (default: cycle seconds x --gif-fps)")
+ parser.add_argument("--gif-fps", type=float, default=GIF_FPS_DEFAULT, help=f"GIF/WebP playback density (default {GIF_FPS_DEFAULT:g}); every state plays at this rate regardless of cycle length")
parser.add_argument("--seam-max", type=float, default=SEAM_RATIO_MAX, help=f"loop seam gate (default {SEAM_RATIO_MAX})")
parser.add_argument("--cycle", choices=CYCLE_MODES, default="auto", help="auto: periodic first, one-shot failover for action states (recorded in the report); periodic / one-shot force one detector")
parser.add_argument("--name", default="loop", help="basename for strip/gif/webp outputs")
@@ -467,7 +474,7 @@ def run(**kwargs: object) -> int:
fps=float(kwargs.get("fps") or 24.0), state=kwargs.get("state"), # type: ignore[arg-type]
min_len=kwargs.get("min_len"), max_len=kwargs.get("max_len"), n_out=kwargs.get("n_out"), # type: ignore[arg-type]
seam_max=float(kwargs.get("seam_max") or SEAM_RATIO_MAX), name=str(kwargs.get("name") or "loop"), report_path=kwargs.get("report"), # type: ignore[arg-type]
- cycle_mode=str(kwargs.get("cycle") or "auto"),
+ cycle_mode=str(kwargs.get("cycle") or "auto"), gif_fps=float(kwargs.get("gif_fps") or GIF_FPS_DEFAULT),
)
summary = {k: payload[k] for k in ("state", "frames_total", "window", "cycle_seconds", "n_out", "delay_ms", "resampled_seam_ratio", "specks_dropped", "report")}
summary["cycle"] = {k: payload["cycle"].get(k) for k in ("kind", "start", "length", "period_global", "ratio")}
diff --git a/tests/video/test_video_pipeline.py b/tests/video/test_video_pipeline.py
index cce91dc..17a0bbc 100644
--- a/tests/video/test_video_pipeline.py
+++ b/tests/video/test_video_pipeline.py
@@ -134,7 +134,7 @@ def test_run_frames_extracts_a_real_clip(tmp_path: Path) -> None:
# --- loop ----------------------------------------------------------------------------
-def _gait_frames(tmp_path: Path, *, period: int, n: int, size=(64, 64)) -> list[Path]:
+def _gait_frames(tmp_path: Path, *, period: int, n: int, size=(64, 64), stamp: bool = False) -> list[Path]:
"""A 'walker': a body block plus one leg that swings with `period`; the swing is
mirror-symmetric every half period (the classic 1.5-cycle trap) but a side marker
breaks the symmetry slightly, exactly like a near/far leg in a side view."""
@@ -155,6 +155,9 @@ def _gait_frames(tmp_path: Path, *, period: int, n: int, size=(64, 64)) -> list[
# near-leg marker only on the first half of the period
if math.sin(phase) >= 0:
im.putpixel((leg_x, 50), (255, 255, 0, 255))
+ if stamp: # recolour one BODY pixel per frame so no two frames are identical (a detached
+ # marker would be erased as a speck; GIF writers merge byte-identical frames)
+ im.putpixel((26 + t % 12, 10 + (t // 12) % 30), (90, 200, 90, 255))
p = d / f"frame-{t:04d}.png"
im.save(p)
files.append(p)
@@ -289,6 +292,22 @@ def test_strip_cap_is_on_pixels_not_cells() -> None:
assert strip.width == meta["w"] * meta["frames"]
+def test_gif_frame_count_follows_cycle_length_at_a_fixed_playback_rate(tmp_path: Path) -> None:
+ """A 2.5 s jump used to get the same 12 frames as a 1.1 s walk and play at ~5 fps
+ (2026-09-09, lead: '점프만 혼자 왜 프레임이 느리냐')."""
+ (tmp_path / "long").mkdir()
+ _gait_frames(tmp_path / "long", period=60, n=150, stamp=True) # 60 frames @ 24 fps = 2.5 s
+ rep = loop_mod.run_loop(tmp_path / "long" / "keyed", tmp_path / "long-out", fps=24.0, state="jump", min_len=None, max_len=None, n_out=None, seam_max=2.0, name="j", report_path=None)
+ assert rep["n_out"] == 30 and 80 <= rep["delay_ms"] <= 90
+ (tmp_path / "short").mkdir()
+ _gait_frames(tmp_path / "short", period=26, n=100, stamp=True) # 1.08 s
+ rep2 = loop_mod.run_loop(tmp_path / "short" / "keyed", tmp_path / "short-out", fps=24.0, state="walk", min_len=None, max_len=None, n_out=None, seam_max=2.0, name="w", report_path=None)
+ assert 12 <= rep2["n_out"] <= 14 and abs(rep2["delay_ms"] - rep["delay_ms"]) <= 15 # ~1.1 s at 12 fps; the period may resolve to 24-26
+ explicit = loop_mod.run_loop(tmp_path / "short" / "keyed", tmp_path / "short-out2", fps=24.0, state="walk", min_len=None, max_len=None, n_out=8, seam_max=2.0, name="w8", report_path=None)
+ assert explicit["n_out"] == 8
+ assert rep["n_out"] <= rep["cycle"]["length"] and rep2["n_out"] <= rep2["cycle"]["length"]
+
+
def test_drop_specks_erases_detached_slivers_only() -> None:
im = Image.new("RGBA", (40, 40), (0, 0, 0, 0))
for y in range(5, 35):