Skip to content

Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows

fix: fail fast when ffmpeg lacks libass for demo GIF builds (#1237)

Maximilian Roos340a83f6d081
diff --git a/docs/demos/CLAUDE.md b/docs/demos/CLAUDE.md
index 6d7c37b69..de662ab2d 100644
--- a/docs/demos/CLAUDE.md
+++ b/docs/demos/CLAUDE.md
@@ -92,6 +92,12 @@ Currently `wt-zellij-omnibus` has checkpoints; other TUI demos are skipped until
**Requires Go** — The VHS fork is built from source ([install Go](https://go.dev/dl/)).
+**Requires ffmpeg with libass** — The keystroke overlay uses ASS subtitles. The build script checks for this and exits with install instructions if missing. Homebrew's API-sourced bottle omits `libass`; install from the tap formula instead:
+
+```bash
+HOMEBREW_NO_INSTALL_FROM_API=1 brew install --build-from-source ffmpeg
+```
+
External dependencies are downloaded/built automatically on first run:
- **VHS** — Custom fork with keystroke overlay (cloned and built from source)
- **Claude Code binary** — Downloaded from Anthropic's release bucket
diff --git a/docs/demos/build b/docs/demos/build
index 53870c0c7..72068ae9c 100755
--- a/docs/demos/build
+++ b/docs/demos/build
@@ -38,6 +38,7 @@ from shared import ( # noqa: E402
setup_zellij_config,
setup_fish_config,
check_dependencies,
+ check_ffmpeg_libass,
setup_demo_output,
record_all_themes,
SIZE_DOCS,
@@ -487,6 +488,8 @@ Examples:
# Check dependencies (VHS is built from source, not required in PATH)
deps = ["wt", "starship", "zellij"]
check_dependencies(deps)
+ if not args.text and not args.snapshot:
+ check_ffmpeg_libass()
# Ensure VHS is built (requires Go)
vhs_binary = str(ensure_vhs_binary())
diff --git a/docs/demos/shared/__init__.py b/docs/demos/shared/__init__.py
index dde40339b..eb2a8abcc 100644
--- a/docs/demos/shared/__init__.py
+++ b/docs/demos/shared/__init__.py
@@ -22,6 +22,7 @@ from .lib import (
prepare_demo_repo,
# Demo recording infrastructure
check_dependencies,
+ check_ffmpeg_libass,
setup_demo_output,
record_all_themes,
# Text output recording
@@ -59,6 +60,7 @@ __all__ = [
"format_theme_for_vhs",
# Demo recording infrastructure
"check_dependencies",
+ "check_ffmpeg_libass",
"setup_demo_output",
"record_all_themes",
# Text output recording
diff --git a/docs/demos/shared/lib.py b/docs/demos/shared/lib.py
index 80580719b..1befc9075 100644
--- a/docs/demos/shared/lib.py
+++ b/docs/demos/shared/lib.py
@@ -271,10 +271,18 @@ def render_tape(template_path: Path, replacements: dict, repo_root: Path) -> str
return rendered
-def record_vhs(tape_path: Path, vhs_binary: str = "vhs"):
+def record_vhs(
+ tape_path: Path, vhs_binary: str = "vhs", expected_output: Path = None
+):
"""Record a demo GIF using VHS."""
run([vhs_binary, str(tape_path)], check=True)
+ if expected_output and not expected_output.exists():
+ raise RuntimeError(
+ f"VHS exited 0 but {expected_output.name} was not created. "
+ "Check ffmpeg output above — likely missing libass support."
+ )
+
def build_wt(repo_root: Path):
"""Build the wt binary."""
@@ -930,6 +938,25 @@ def check_dependencies(commands: list[str]):
raise SystemExit(f"Missing dependency: {cmd}")
+def check_ffmpeg_libass():
+ """Check that ffmpeg has libass support (required for keystroke overlay)."""
+ if not shutil.which("ffmpeg"):
+ raise SystemExit(
+ "Missing dependency: ffmpeg\n"
+ "Install with: HOMEBREW_NO_INSTALL_FROM_API=1 brew install --build-from-source ffmpeg"
+ )
+ result = subprocess.run(
+ ["ffmpeg", "-filters"],
+ capture_output=True,
+ text=True,
+ )
+ if " ass " not in result.stdout:
+ raise SystemExit(
+ "ffmpeg missing libass support (required for keystroke overlay).\n"
+ "Install with: HOMEBREW_NO_INSTALL_FROM_API=1 brew install --build-from-source ffmpeg"
+ )
+
+
def setup_demo_output(out_dir: Path) -> Path:
"""Set up demo output directory and copy starship config.
@@ -1232,6 +1259,6 @@ def record_all_themes(
tape_rendered.write_text(rendered)
print(f"\nRecording {theme_name} GIF...")
- record_vhs(tape_rendered, vhs_binary)
+ record_vhs(tape_rendered, vhs_binary, expected_output=output_gif)
tape_rendered.unlink(missing_ok=True)
print(f"GIF saved to {output_gif}")