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: require an img2webp that supports -exact; CI installs libwebp 1.4.0

Soohong Kima0e5e93a22b2
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index e219b0a..5d6a791 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -19,8 +19,12 @@ jobs:
steps:
- uses: actions/checkout@v4
- - name: Install the pipeline's required binaries (ffmpeg for video-frames, libwebp for video-loop)
- run: sudo apt-get update -qq && sudo apt-get install -y -qq ffmpeg webp
+ - name: Install the pipeline's required binaries (ffmpeg for video-frames, libwebp >= 1.3 for video-loop -exact)
+ run: |
+ sudo apt-get update -qq && sudo apt-get install -y -qq ffmpeg
+ curl -fsSL https://storage.googleapis.com/downloads.webmproject.org/releases/webp/libwebp-1.4.0-linux-x86-64.tar.gz | tar -xz -C /tmp
+ sudo cp /tmp/libwebp-1.4.0-linux-x86-64/bin/* /usr/local/bin/
+ img2webp -version && img2webp -h 2>&1 | grep -q -- -exact
- uses: actions/setup-python@v5
with:
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 7d76ce2..799b772 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,7 +4,7 @@ All notable public changes to `sprite-gen` are recorded here. Versions track the
## v2.0.3 - One standing height
-- CI installs `ffmpeg` and `webp` (the declared required binaries) so the video tests run there; the `video-loop` tests that need `img2webp` skip cleanly where it is absent.
+- `video-loop` checks that `img2webp` actually supports `-exact` (libwebp >= 1.3; Ubuntu 22.04 ships 1.2.x) and fails by name otherwise instead of writing WebP with rewritten RGB under alpha; CI installs `ffmpeg` and the official libwebp 1.4.0 binaries so the video tests run there, and those tests skip cleanly where support is absent.
- `video-loop` `body_h` is the standing height (tallest floor-contact frame) instead of the cycle's median bbox height, which under-measured jumps and over-scaled them by ~22 %; `--body-height N` scales every state to the same standing height directly in the pipeline (`--strip-height` remains the cap). README heroes regenerated at one standing height.
## v2.0.2 - Heroes from the pipeline
diff --git a/sprite_gen/video/loop.py b/sprite_gen/video/loop.py
index a57578d..6b8fb62 100644
--- a/sprite_gen/video/loop.py
+++ b/sprite_gen/video/loop.py
@@ -304,12 +304,30 @@ def build_strip(frames: list[Image.Image], *, max_cells: int = STRIP_MAX_CELLS,
return strip, meta
+def img2webp_supports_exact(binary: str | None = None) -> bool:
+ """libwebp added `-exact` to img2webp in 1.3; older builds (Ubuntu 22.04: 1.2.x) reject the
+ flag with "Unknown option" and would rewrite RGB under alpha 0. Detected from `-h`, never assumed."""
+ binary = binary or shutil.which("img2webp")
+ if not binary:
+ return False
+ try:
+ proc = subprocess.run([binary, "-h"], capture_output=True, text=True, timeout=10)
+ except (OSError, subprocess.TimeoutExpired):
+ return False
+ return "-exact" in (proc.stdout + proc.stderr)
+
+
def write_webp(frames: list[Image.Image], out: Path, *, delay_ms: int, workdir: Path) -> None:
"""Animated WebP through libwebp's img2webp with -exact (Pillow's animated writer drops `exact`
and rewrites RGB under alpha 0 to white; measured 2026-09-08)."""
img2webp = shutil.which("img2webp")
if not img2webp:
raise SystemExit("video-loop: `img2webp` not found on PATH — install libwebp (brew install webp) for exact-alpha WebP")
+ if not img2webp_supports_exact(img2webp):
+ raise SystemExit(
+ "video-loop: this img2webp has no `-exact` option (libwebp < 1.3; Ubuntu 22.04 ships 1.2.x) — "
+ "install libwebp >= 1.3 (brew install webp, or the official binaries from storage.googleapis.com/downloads.webmproject.org)"
+ )
workdir.mkdir(parents=True, exist_ok=True)
paths = []
for k, im in enumerate(frames):
diff --git a/tests/video/test_video_pipeline.py b/tests/video/test_video_pipeline.py
index c637745..fb0729e 100644
--- a/tests/video/test_video_pipeline.py
+++ b/tests/video/test_video_pipeline.py
@@ -21,7 +21,7 @@ from sprite_gen.video import loop as loop_mod
GREEN = (0, 255, 0)
HAS_FFMPEG = shutil.which("ffmpeg") is not None and shutil.which("ffprobe") is not None
-HAS_IMG2WEBP = shutil.which("img2webp") is not None
+HAS_IMG2WEBP = shutil.which("img2webp") is not None and __import__("sprite_gen.video.loop", fromlist=["x"]).img2webp_supports_exact() # presence is not support: libwebp < 1.3 has no -exact
def _still(tmp_path: Path, size=(120, 160), key=GREEN, name="still.png") -> Path: