Skip to content
led-ticker

Tool: gif-plan

gif-plan reads a led-ticker demo config.toml and prints the recommended --duration to render it with. It exists so the question “how long should I render this?” has a one-shot answer instead of a guess-render-recheck loop. The estimate is deliberately coarse — it models only the dominant timing terms (hold time, overflow scroll, gif loops); precision is not the goal, not wasting a render is.

The script lives at tools/gif_plan/plan.py and ships as make plan-gif. The math layer is the planner; render-demo is the pixels layer.

Usage

Section titled “Usage”
Terminal window
make plan-gif CONFIG=docs/site/demos-pinned/two_row-wrap.toml

Output is at most two lines:

duration: 8

If the file carries a # render-duration: N header and N is shorter than the estimated playtime, it adds a cutoff line and exits non-zero — that is the one check that stops you shipping a gif that clips mid-content and having to re-render:

duration: 9
cutoff: header 5s < ~8s needed

Exit codes

Section titled “Exit codes”
CodeMeaning
0Clean — recommended duration printed.
2The # render-duration: header is shorter than the estimate (expected, and ignorable, when play_count is intentionally large).
3Tool error — config not found or malformed TOML (message on stderr).

Out of scope

Section titled “Out of scope”

The estimate is coarse and intentionally ignores some cases:

  • ticker / one_at_a_time / loop_count = 0 sections — runtime-dependent, contribute 0.
  • Data-fetch widgets (weather.current, crypto, rss.feed, and plugin data widgets like baseball.scores) — depend on fetched data, contribute 0.
  • Bigsign pixel_mapper_config — naive canvas-width used.
  • Wrap floors, two-row overlay marquee, hires width, inter-widget transition time — not modelled; treat the number as a lower bound for transition-heavy playlists.
  • For looping or large-play_count demos (the play_count = 999 “keep animating” idiom) the recommended --duration is the full multi-minute playthrough, not the capture window — such demos deliberately pin a short # render-duration: header; render with the header, treat the recommendation as an upper bound.

The companion skill at .claude/skills/making-a-gif/ wraps this plus render-demo and adds LED-panel colour/contrast judgement.