This is the full developer documentation for led-ticker # led-ticker > A Python toolkit for RGB LED matrix signs — configurable feeds in TOML, extensible with plugins.  A \`message\` widget with rainbow per-character coloring — one of the built-in widgets. ## Two ways in [Section titled “Two ways in”](#two-ways-in) Run a sign You have, or want, an RGB LED matrix sign. Describe what it shows in a TOML config — RSS, weather, scores, countdowns, images — **no Python required.** * [Why led-ticker?](/why-led-ticker/) — is this the right tool for your sign? * [Get started](/getting-started/) — install and light up a sign in minutes * [Tutorial](/tutorial/01-setup/) — build a complete config step by step * [Browse widgets](/widgets/) — every built-in building block Build on it You want to extend led-ticker. Add widgets, transitions, color providers, fonts, or lifecycle hooks through the public `led_ticker.plugin` API — without forking core. * [Plugins](/plugins/) — how extensions install and load * [Write a plugin](/plugins/authoring/01-scaffold/) — a guided walkthrough ## What you can put on it [Section titled “What you can put on it”](#what-you-can-put-on-it) Weather (plugin)  Current conditions for any location — via the weather plugin. [Weather widget →](/widgets/weather/) MLB scores (plugin)  Live game scores and counts — via the baseball plugin. [MLB widget →](/widgets/mlb/) Crypto prices (plugin)  Multi-coin CoinGecko price ticker, trend-colored. [Crypto plugin →](/widgets/crypto-coingecko/) Animated GIFs  Play a looping GIF, with optional overlay text. [GIF widget →](/widgets/gif/) Countdowns  Count down to any date or time. [Countdown widget →](/widgets/countdown/) …and your own  The pool widget is a real, shipped plugin. [Pool plugin →](/plugins/available/) [Browse all widgets →](/widgets/) ## Writing a plugin [Section titled “Writing a plugin”](#writing-a-plugin) `led_ticker.plugin` is the public surface plugins import from — it exposes widget, transition, emoji, font, and lifecycle-hook registration, no fork of core needed. The pool water-temperature widget shown above is a real plugin that lives in [the led-ticker-plugins monorepo](https://github.com/JamesAwesome/led-ticker-plugins) and contributes `type = "pool.monitor"`. * [Plugins overview](/plugins/) — install, load, and the `[plugins]` config block * [Write a plugin](/plugins/authoring/01-scaffold/) — scaffold, build, and package one ## Where to next [Section titled “Where to next”](#where-to-next) * **Run a sign:** [Get started](/getting-started/) · [Tutorial](/tutorial/01-setup/) * **Pick content:** [Widgets](/widgets/) · [Transitions](/transitions/push/) * **Extend it:** [Plugins](/plugins/) · [Write a plugin](/plugins/authoring/01-scaffold/) * **Get the hardware:** [Building your own](/hardware/building-your-own/) Using an AI coding agent? These docs are available as plain Markdown at [`/llms.txt`](/llms.txt) (index) and [`/llms-full.txt`](/llms-full.txt) (everything in one file). # Inline emoji > 40 pixel-art glyphs (20 base + heart/cat/pride color variants) you can drop into any message text via `:slug:`. Drop `:slug:` into any message text to render a pixel-art icon inline:  :taco: :star: :flower: :sun: Example ```toml [[playlist.section.widget]] type = "message" text = ":taco: Taco Tuesday!" ``` ## Available slugs [Section titled “Available slugs”](#available-slugs) Use `:slug:` inside any text-bearing widget to render a pixel-art icon inline. Each is an 8×8 sprite in its native colors; the surrounding text uses your `font_color`. On a `default_scale > 1` panel (bigsign), every slug auto-upgrades to a 32×32 hires sprite — same horizontal footprint, 16× more detail. The slug list rots fast as new icons are added. The source of truth is `src/led_ticker/pixel_emoji.py` — `grep -E '^\s+"[a-z_]+":' src/led_ticker/pixel_emoji.py` lists every slug. Re-run `uv run python tools/render_emoji_previews.py` after adding a sprite to refresh the previews on this page. > **Plugin emoji.** Some icons ship with external plugins (install the plugin to use them; the slugs in the table below are all built in): > > * `:baseball.ball:` (white ball with red stitching) — [`baseball`](https://github.com/JamesAwesome/led-ticker-plugins/tree/main/plugins/baseball) > * `:pokeball.ball:` (red top, white bottom, button-banded) — [`pokeball`](https://github.com/JamesAwesome/led-ticker-plugins/tree/main/plugins/pokeball) | Slug | Lowres (8×8) | Hires (32×32) | Description | | ----------------- | ------------------------------------------------------ | ---------------------------------------------------- | -------------------------------------------------------- | | `:bunny:` |  |  | Bunny silhouette | | `:cat:` |  |  | Cat (default gray; see color variants below) | | `:cloud:` |  |  | Cloud icon | | `:droplet:` |  |  | Water droplet (blue teardrop) | | `:email:` |  |  | Envelope (white) | | `:flower:` |  |  | Pink flower | | `:fog:` |  |  | Fog icon | | `:heart:` |  |  | Heart (default red; see color variants below) | | `:instagram:` |  |  | Instagram glyph (magenta gradient) | | `:moon:` |  |  | Crescent moon | | `:partly_cloudy:` |  |  | Sun + cloud | | `:pride:` |  |  | Pride flag stripes (default rainbow; see variants below) | | `:rain:` |  |  | Rain icon | | `:snow:` |  |  | Snow icon | | `:star:` |  |  | Yellow star (default; see color variants below) | | `:sun:` |  |  | Sun icon | | `:taco:` |  |  | Taco | | `:thunder:` |  |  | Thunder icon | ## Color variants ### Heart colors `:heart:` defaults to red. Six additional color slugs share the same shape: | Slug | Lowres | Hires | | ---------------- | ---------------------------------------------------- | -------------------------------------------------- | | `:heart_red:` |  |  | | `:heart_orange:` |  |  | | `:heart_yellow:` |  |  | | `:heart_green:` |  |  | | `:heart_blue:` |  |  | | `:heart_purple:` |  |  | | `:heart_pink:` |  |  | ### Star colors `:star:` defaults to yellow. Six additional color slugs share the same shape: | Slug | Lowres | Hires | | --------------- | -------------------------------------------------- | ------------------------------------------------ | | `:star_red:` |  |  | | `:star_orange:` |  |  | | `:star_yellow:` |  |  | | `:star_green:` |  |  | | `:star_blue:` |  |  | | `:star_purple:` |  |  | | `:star_pink:` |  |  | ### Cat colors `:cat:` defaults to gray with yellow eyes. Five other coats are available: | Slug | Lowres | Hires | | -------------- | ------------------------------------------------ | ---------------------------------------------- | | `:cat_gray:` |  |  | | `:cat_orange:` |  |  | | `:cat_white:` |  |  | | `:cat_black:` |  |  | | `:cat_brown:` |  |  | | `:cat_cream:` |  |  | ### Pride flag variants `:pride:` defaults to the rainbow flag. Other flags: | Slug | Lowres | Hires | | ----------------- | ------------------------------------------------------ | ---------------------------------------------------- | | `:pride_rainbow:` |  |  | | `:pride_trans:` |  |  | | `:pride_bi:` |  |  | | `:pride_lesbian:` |  |  | | `:pride_nb:` |  |  | | `:pride_ace:` |  |  | | `:pride_demi:` |  |  | ## Hires on the bigsign When the panel is at `default_scale > 1`, slugs auto-render the higher-detail sprite — same horizontal footprint (8 logical columns), 16× more detail per cell. On `scale=1` (small sign), the lowres 8×8 sprite is used. `:moon:` is the canonical hires example: a 32×32 sprite with circle-subtraction shading. ## Adding a new emoji Edit `src/led_ticker/pixel_emoji.py`. Define an 8×8 pixel-data tuple (`(x, y, r, g, b)`), add it to `EMOJI_REGISTRY`. For hires, draw a 32×32 variant and add it to `HIRES_REGISTRY`. The renderer auto-handles the scale dispatch. Then run `uv run python tools/render_emoji_previews.py` to refresh the preview PNGs. See also * [widgets/message](/widgets/message/) * [concepts/color-providers](/concepts/color-providers/) # Animations > Animate text on your sign — typewriter reveals, flair.propeller spinning entry, and flair.fisheye lens-scrolling, all composing with any font_color. led-ticker has one animation right now: **typewriter** — a character-by-character reveal. Set `animation = "typewriter"` on a supported widget and the text types out one character at a time the moment the widget appears. The characters land in their final positions (no shifting), so the message assembles itself in place rather than scrolling in. Animations are a separate axis from color providers. A widget can carry both simultaneously — for example `animation = "typewriter"` and `font_color = "rainbow"` — and each effect tracks its own frame counter. The characters type out in rainbow with no interference between the two systems. Animations may also emit a per-frame `rotation` (degrees, clockwise) that the message widget renders through an offscreen rotate around the text block’s center — the flair plugin’s `propeller` effect uses this seam. On scaled displays (bigsign), the spin runs at half physical resolution from a pre-rendered snapshot that captures hires fonts and emoji at their correct size; the resting frame always renders at full detail. Animated `font_color` providers (rainbow, color\_cycle, shimmer) pause for the duration of the spin and resume at settle — the color phase keeps advancing in the background, so on settle the sweep continues exactly where it left off.  \`message\` with animation = typewriter and font\_color = rainbow Minimal ```toml [[playlist.section.widget]] type = "message" text = "Hello, world!" animation = "typewriter" ``` ## Tuning `frames_per_char` [Section titled “Tuning frames\_per\_char”](#tuning-frames_per_char) The cadence is `frames_per_char × 50 ms` per character — the engine ticks at 50 ms and advances the typewriter counter once per tick. The default of `3` gives about 150 ms per character, which feels snappy but still readable at roughly 7 characters per second. A value of `5` or `6` reads as deliberate and is a good choice when you want the audience to register each character dropping in. Values above `10` read as comically slow. There is no separate animation clock — everything runs on the same 50 ms engine tick. To override `frames_per_char`, switch from the string shorthand to an inline TOML table with a `style` key: ```toml [[playlist.section.widget]] type = "message" text = "Slow type" animation = {style = "typewriter", frames_per_char = 6} # ~300ms per char ``` ### Keeping the reveal inside `hold_time` [Section titled “Keeping the reveal inside hold\_time”](#keeping-the-reveal-inside-hold_time) Typing takes `frames_per_char × 50 ms` per character — so a 20-character message at the default `frames_per_char = 3` takes roughly 3 seconds to finish. If `hold_time` is shorter than the typing duration, the transition fires mid-reveal and the message never fully appears. `led-ticker validate` catches this (rule 61) and prints the computed typing duration alongside the effective hold time, so you can raise `hold_time` to cover the full reveal — or shorten the text. When a reveal is nearly done at transition time, the engine waits up to roughly one second for the final characters to land before switching scenes, so a message that’s one or two characters short doesn’t cut away abruptly. ## Composing with font\_color [Section titled “Composing with font\_color”](#composing-with-font_color) `animation` and `font_color` are independent axes on the same widget. Both can be set at the same time, and each effect tracks its own counter. The result is that characters type out AND each character’s color comes from the provider — a rainbow sweeps across the text as it appears, rather than the whole message flashing in at once. ```toml [[playlist.section.widget]] type = "message" text = "Now Enrolling" animation = "typewriter" font_color = "rainbow" ``` Because rainbow is a continuous-phase provider (its counter does not reset between `loop_count` repetitions), the color sweep keeps flowing even as the typewriter retypes from scratch on each loop. ## Restart-on-visit behavior [Section titled “Restart-on-visit behavior”](#restart-on-visit-behavior) Typewriter has `restart_on_visit = true` — the reveal counter resets every time the section shows the widget. With `loop_count = 2`, the widget retypes from scratch on each loop rather than resuming mid-word. With `loop_count = 1` and a multi-widget section in `slideshow` mode, the widget retypes fresh each time it appears in the rotation. This is the intentional, expected behavior — typewriter is designed to be a reveal, not a persistent animation state. See [frame counters](/reference/frame-counters/) for the full model of restart-on-visit versus continuous-phase behavior. ## Where it works [Section titled “Where it works”](#where-it-works) | Widget type | `animation = "typewriter"`? | `animation = "flair.propeller"`? | `animation = "flair.fisheye"`? | | ----------------------------- | -------------------------------------- | -------------------------------------------------------------------- | ------------------------------------------------------------------ | | `message` | yes | yes | yes | | `countdown` | no | no | no | | `gif` | yes — single-row only (see note below) | accepted but rotation is ignored [1](#user-content-fn-propeller-gif) | accepted but the lens is ignored [2](#user-content-fn-fisheye-gif) | | `image` | yes — single-row only (see note below) | accepted but rotation is ignored [1](#user-content-fn-propeller-gif) | accepted but the lens is ignored [2](#user-content-fn-fisheye-gif) | | `two_row` | no | no | no | | `weather.current`, `rss.feed` | no | no | no | On `gif` and `image` widgets, typewriter is restricted to single-row text overlays. It will raise a configuration error if `bottom_text` is also set (which activates two-row mode), if `text_align` is `"scroll"` or `"scroll_over"` (incompatible with a fixed-position reveal), or if `text` is empty. ## Tips [Section titled “Tips”](#tips) ### `animation` is only valid on `message`, `gif`, and `image` [Section titled “animation is only valid on message, gif, and image”](#animation-is-only-valid-on-message-gif-and-image) Other widget types (`two_row`, the crypto and feeds widgets) have their own draw paths and ignore `animation` silently — the validator rejects it explicitly to make the no-op visible. For dynamic color on those widgets, use `font_color = "rainbow"` or a gradient. ### Typewriter is single-row only on `gif` and `image` [Section titled “Typewriter is single-row only on gif and image”](#typewriter-is-single-row-only-on-gif-and-image) On top of the widget-type check above, typewriter on `gif` / `image` rejects three combinations: `bottom_text` set, `text_align = "scroll"` / `"scroll_over"`, or empty `text`. Typewriter still composes with `font_color = "rainbow"` and `border = "rainbow"`. *** ## `flair.propeller` (flair pack) [Section titled “flair.propeller (flair pack)”](#flairpropeller-flair-pack) `flair.propeller` is a plugin animation from the [flair pack](/plugins/available/#flair-text-effects-flair-pack) (`led-ticker-flair >= 0.2.0`, core >= 4.3). The `message` widget’s text spins in-plane like a propeller the moment the widget appears — easing out over the configured number of revolutions and settling exactly flat — then holds readable for the rest of `hold_time`. Transitions wait for the spin to finish before firing.  \`message\` with \`animation = flair.propeller\` — text spins in and settles flat ### Install [Section titled “Install”](#install) Add one line to `config/requirements-plugins.txt`: ```text led-ticker-flair ``` See [Plugins](/plugins/) for the install flow. ### Minimal config [Section titled “Minimal config”](#minimal-config) Minimal ```toml [[playlist.section.widget]] type = "message" text = "PROPELLER" center = true font_color = [255, 200, 0] animation = "flair.propeller" ``` ### Tuning the spin [Section titled “Tuning the spin”](#tuning-the-spin) Switch to an inline table to control speed and direction: ```toml [[playlist.section.widget]] type = "message" text = "PROPELLER" center = true font_color = [255, 200, 0] animation = {style = "flair.propeller", revolutions = 3, spin_seconds = 1.5, direction = "ccw"} ``` | Knob | Default | Notes | | -------------- | ------- | --------------------------------------------------------------------------------------- | | `revolutions` | `2` | Integer >= 1. Number of full 360° turns before settling. | | `spin_seconds` | `1.0` | Seconds for the full spin (ease-out). Shorter feels snappy; 2–3 s reads as deliberate. | | `direction` | `"cw"` | `"cw"` (clockwise) or `"ccw"` (counter-clockwise) — viewed from the front of the panel. | ### How the spin interacts with `hold_time` [Section titled “How the spin interacts with hold\_time”](#how-the-spin-interacts-with-hold_time) `led-ticker validate` rule 62 warns when `spin_seconds` is longer than the section’s `hold_time` — a spin that outlasts the hold cuts away before the text settles, so the message never reads cleanly. Raise `hold_time` to cover `spin_seconds` plus at least a moment of readable hold. The engine waits up to about a second for the spin to settle before firing a transition; a spin that outlasts the hold by more than that cuts away mid-spin (the rule 62 warning covers this). ### Composing with `font_color` and `border` [Section titled “Composing with font\_color and border”](#composing-with-font_color-and-border) `flair.propeller` composes with `font_color` providers and `border` effects using the same independent-axes model as typewriter. Animated color providers (`rainbow`, `color_cycle`, `shimmer`) **freeze** for the duration of the spin and resume at settle — the color phase keeps advancing in the background, so the sweep continues exactly where it left off the moment the text lands flat. This means a propeller + rainbow combo reads as: spin in (colors frozen), land flat, rainbow resumes sweeping. ### On scaled signs (bigsign) [Section titled “On scaled signs (bigsign)”](#on-scaled-signs-bigsign) On signs with `default_scale > 1`, the mid-spin frames render from a pre-rendered snapshot at half physical resolution — this captures hires fonts and emoji at their correct size but at reduced detail. The resting (settled) frame always renders at full detail. `led-ticker-flair >= 0.2.0` and core >= 4.5 are required for physical-resolution hires spin frames; on core 4.3–4.4 the spin runs but hires fonts draw unrotated (validate rule 63 warns when this condition is detected). ### Pairing with `flair.spinout` [Section titled “Pairing with flair.spinout”](#pairing-with-flairspinout) `flair.propeller` and `flair.spinout` are designed to pair: the widget spins in at entry and spins out at exit. See [the full-cycle demo](#pairing-with-flairspinout) below for the combined config.  Full cycle — \`flair.propeller\` entry spin followed by \`flair.spinout\` transition Full cycle (propeller in + spinout) ```toml [transitions] default = "flair.spinout" duration = 1.0 [[playlist.section]] mode = "slideshow" hold_time = 3.5 [[playlist.section.widget]] type = "message" text = "FULL CYCLE" center = true font_color = [255, 200, 0] animation = "flair.propeller" [[playlist.section]] mode = "slideshow" hold_time = 2.5 [[playlist.section.widget]] type = "message" text = "REPEAT" center = true font_color = [255, 100, 255] ``` *** ## `flair.fisheye` (flair pack) [Section titled “flair.fisheye (flair pack)”](#flairfisheye-flair-pack) `flair.fisheye` is a plugin animation from the [flair pack](/plugins/available/#flair-text-effects-flair-pack) (`led-ticker-flair >= 0.4.0`, core >= 4.7). A `message` widget’s scrolling text passes through a stationary “fisheye lens” centered on the panel: letters enter compressed at the edges, swell as they cross the middle, and compress again on exit. The lens is fixed — the scroll provides all the motion, so the effect runs for the whole scroll and a section can cut away at any moment.  \`message\` with \`animation = flair.fisheye\` — text scrolls through a stationary squeeze-and-bulge lens ### Install [Section titled “Install”](#install-1) Add one line to `config/requirements-plugins.txt`: ```text led-ticker-flair ``` See [Plugins](/plugins/) for the install flow. ### Minimal config [Section titled “Minimal config”](#minimal-config-1) Minimal ```toml [[playlist.section.widget]] type = "message" text = "OPEN LATE TONIGHT" animation = "flair.fisheye" ``` ### Tuning the lens [Section titled “Tuning the lens”](#tuning-the-lens) Stronger lens ```toml [[playlist.section.widget]] type = "message" text = "FLASH SALE TODAY" animation = {style = "flair.fisheye", magnify = 1.33, edge_squeeze = 0.45} ```  \`magnify = 1.33, edge\_squeeze = 0.45\` — a stronger lens: the center swells more and the edges compress harder than the default | Knob | Default | Meaning | | -------------- | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `magnify` | `1.3` | Center scale (both axes). There is a ceiling — `magnify × font line-height ≤ content_height` — above which the bulged text would run off the panel; a widget over the ceiling is skipped and the rest of the sign keeps running. For the default 6×12 font in a 16-row band the ceiling is about `1.33`. | | `edge_squeeze` | `0.6` | Edge scale (`0 < edge_squeeze ≤ magnify`). Lower means more edge compression — a more dramatic lens. | | `profile` | `"cosine"` | The edge-to-center falloff curve. `"cosine"` is the only value today. | ### What the lens does to the scroll [Section titled “What the lens does to the scroll”](#what-the-lens-does-to-the-scroll) The lens is width-preserving: a message takes exactly as long to scroll across as it would without the lens. But because the edges are compressed, they show **more** text than a plain scroll would — roughly two extra characters per side at the default squeeze, more with a stronger one. That is the lens working as intended, not a glitch. ### Live colors through the lens [Section titled “Live colors through the lens”](#live-colors-through-the-lens) Unlike `flair.propeller` (whose colors freeze during the spin), `flair.fisheye` keeps `font_color` **live**: a `rainbow` or `color_cycle` provider keeps sweeping as the text scrolls through the lens.  \`font\_color = rainbow\` with \`flair.fisheye\` — colors keep sweeping through the lens ### Static center bulge [Section titled “Static center bulge”](#static-center-bulge) Held (non-scrolling) text gets a fixed emphasis: the center of the message swells while the ends compress. Center a short message with `center = true` and skip the scroll — good for a shop sign or a headline.  \`center = true\`, no scroll — \`flair.fisheye\` bulges the middle of a held message Static bulge ```toml [[playlist.section.widget]] type = "message" text = "GRAND OPENING TODAY" center = true animation = "flair.fisheye" ``` ### Inline emoji through the lens [Section titled “Inline emoji through the lens”](#inline-emoji-through-the-lens) `:slug:` emoji ride the lens with the text — an emoji swells as it crosses the center and compresses at the edges, just like the letters around it.  \`NOW OPEN :star: WELCOME IN :star:\` — the star bulges through the lens along with the words With inline emoji ```toml [[playlist.section.widget]] type = "message" text = "NOW OPEN :star: WELCOME IN :star:" animation = "flair.fisheye" ``` ### Also works with borders and hi-res fonts [Section titled “Also works with borders and hi-res fonts”](#also-works-with-borders-and-hi-res-fonts) * **Borders**: the border frames the panel un-warped while the text warps inside it. * **Hi-res fonts**: on a scaled sign (bigsign) a hi-res font warps too, subject to the same `magnify × font line-height ≤ content_height` ceiling — a too-tall hi-res font is skipped (and the rest of the sign keeps running). On a smallsign (scale 1) a hi-res font renders normally (unwarped) and `led-ticker validate` emits a warning: the pixel-precise warp needs a scaled display. ### On scaled signs (bigsign) [Section titled “On scaled signs (bigsign)”](#on-scaled-signs-bigsign-1) The lens re-renders the scrolling text every frame at reduced resolution, so the whole scroll shows at half detail on the bigsign — the distortion masks it, and it matches the reduced detail you already see mid-spin with `flair.propeller`. ### Pairing with `flair.spinout` [Section titled “Pairing with flair.spinout”](#pairing-with-flairspinout-1) A fisheye message scrolls in through the lens; `flair.spinout` — the flair pack’s text-spin transition, documented on the [flair transitions page](/transitions/sprite/) — can spin that message out as the section changes. Set it as the transition (here as the global default) and the outgoing fisheye text spins away before the next section appears: Fisheye scroll with a spinout exit ```toml [transitions] default = "flair.spinout" duration = 1.0 [[playlist.section]] mode = "slideshow" hold_time = 3.0 [[playlist.section.widget]] type = "message" text = "GRAND OPENING TODAY" animation = "flair.fisheye" [[playlist.section]] mode = "slideshow" hold_time = 2.5 [[playlist.section.widget]] type = "message" text = "SEE YOU SOON" center = true ``` See also * [concepts/color-providers](/concepts/color-providers/) * [reference/frame-counters](/reference/frame-counters/) * [widgets/message](/widgets/message/) * [transitions/sprite](/transitions/sprite/) ## Footnotes [Section titled “Footnotes”](#footnote-label) 1. `flair.propeller` is accepted on `gif` and `image` at config-load so a section can carry both a spinning `message` and an image widget without a validation error, but the rotation has no visible effect — only `message` widgets render the spin. [↩](#user-content-fnref-propeller-gif) [↩2](#user-content-fnref-propeller-gif-2) 2. `flair.fisheye` is accepted on `gif` and `image` at config-load so a section can carry both a lens-scrolling `message` and an image widget without a validation error, but the lens has no visible effect — only `message` widgets warp. [↩](#user-content-fnref-fisheye-gif) [↩2](#user-content-fnref-fisheye-gif-2) # Borders > Rainbow chase, color_cycle, constant-color, color bands, or lightbulb marquee border around the panel perimeter. A border paints a decorative outline around the entire panel perimeter. All styles paint at physical panel resolution — a pixel-ring border is always exactly one LED wide regardless of scale, even on a big / scaled sign (`default_scale > 1`) where most content is drawn in logical pixels and expanded to fill the panel (see [Display](/concepts/display/)). *For developers:* borders bypass the block-expansion path and write directly to the real underlying canvas (`SetPixel`). The five styles and their shorthands are listed in the table below. `rainbow` and `color_cycle` also accept optional `from` / `to` RGB colors to confine the animation to a specific hue arc instead of sweeping the full spectrum.  Rainbow chase border at default speed and thickness ## Border styles [Section titled “Border styles”](#border-styles) | Style | Shorthand | Per-pixel color? | Animates? | | ------------- | ------------------------ | --------------------------- | --------- | | `rainbow` | `border = "rainbow"` | yes — hue chase | yes | | `color_cycle` | `border = "color_cycle"` | no — whole border one hue | yes | | `constant` | `border = [r,g,b]` | no — uniform | no | | `bands` | — | yes — per-band solid color | yes | | `lightbulbs` | `border = "lightbulbs"` | optional — rainbow or solid | yes | ### Rainbow chase [Section titled “Rainbow chase”](#rainbow-chase) The rainbow chase indexes each perimeter pixel by its clockwise position around the edge, then advances the entire pattern by `speed` degrees per engine tick (50 ms). The result is a smooth hue gradient that rotates continuously. `char_offset` controls how tightly the hue cycles around the perimeter: a higher value tiles more full rainbows along the edge. The simplest way to enable it is the string shorthand: String shorthand ```toml [[playlist.section.widget]] type = "message" text = "Hello" border = "rainbow" ``` To tune the three knobs, switch to an inline table: With tuning ```toml [[playlist.section.widget]] type = "message" text = "Hello" border = {style = "rainbow", thickness = 2, speed = 4, char_offset = 6} ``` **`speed`** (default `4`): degrees of hue rotation per engine tick. At 50 ms per tick, the default produces about one full revolution every 12 seconds on the bigsign’s 640-pixel perimeter. Double it to `8` for a noticeably faster sweep. **`char_offset`** (default `6`): hue spacing between adjacent perimeter pixels. At `6` and 640 pixels, roughly 10 full rainbows tile around the bigsign edge. Reduce it toward `1` for a slow gradient wash; raise it above `10` for a tighter, flickery pattern. **`thickness`** (default `1`): `1` is a single-pixel ring; `2` is two concentric rings. Thickness 2 reads better at viewing distance. The two rings share the same hue index sequence, so the inner ring continues where the outer ring ends rather than repeating. #### Restricting the hue arc [Section titled “Restricting the hue arc”](#restricting-the-hue-arc) Add `from` and `to` RGB colors to confine the chase to a specific hue arc — the chase will tile only within those two hues rather than sweeping the full 360° spectrum. The engine always takes the shorter arc between the two hues.  red → amber arc at \`speed = 3\`, \`thickness = 2\` — chase tiles only within the warm fire band, never entering green or blue ```toml # Warm fire arc — red to amber, 2-ring border border = {style = "rainbow", from = [220, 30, 0], to = [255, 180, 0], speed = 3, thickness = 2} ``` `char_offset` controls how many full arc-widths tile around the perimeter — the same density semantics as the full-wheel chase, just measured in arc-degrees instead of 360°. A narrow arc (60°) with `char_offset = 6` produces roughly the same number of tiles as the full-wheel chase, because the hue spacing is relative to the arc width. Achromatic `from`/`to` colors (gray, white, black) are rejected since their hue is undefined. Same-hue `from`/`to` is also rejected — use `border = [r, g, b]` for a static color. #### Common patterns [Section titled “Common patterns”](#common-patterns) **Fire / warm tones** — keep the chase in the red-to-amber band: ```toml border = {style = "rainbow", from = [220, 30, 0], to = [255, 180, 0], speed = 3, thickness = 2} # Red → amber chase, 2-ring border ``` **Cool ocean sweep** — blue-to-cyan arc for a cold-light feel: ```toml border = {style = "rainbow", from = [0, 80, 255], to = [0, 220, 255], speed = 4, thickness = 1} # Deep blue → cyan chase ``` **Rainbow chase + arc-restricted font\_color** — pair a full rainbow border with a brand-palette text color: ```toml [[playlist.section.widget]] type = "message" text = "Open" font_color = {style = "color_cycle", from = [255, 92, 38], to = [255, 183, 3], speed = 3} border = {style = "rainbow", from = [255, 92, 38], to = [255, 183, 3], speed = 3, thickness = 2} ``` ### Color cycle [Section titled “Color cycle”](#color-cycle) A color\_cycle border paints every perimeter pixel the same color per frame, and that color cycles through the hue wheel over time. Unlike the rainbow chase — which gives each pixel its own hue offset — color\_cycle pulses the border as a single unified color. The effect is a slow wash of light that shifts hue without any chasing motion.  \`color\_cycle\` border at \`speed = 5\`, \`thickness = 2\` — entire perimeter pulses as one hue with no per-pixel chase String shorthand uses the full 360° wheel at the default speed: String shorthand ```toml [[playlist.section.widget]] type = "message" text = "Hello" border = "color_cycle" ``` Tune `speed` and `thickness` via an inline table: With tuning ```toml [[playlist.section.widget]] type = "message" text = "Hello" border = {style = "color_cycle", speed = 5, thickness = 2} ``` **`speed`** (default `5`): degrees of hue rotation per engine tick. Higher = faster pulse. **`thickness`** (default `1`): `1` is a single-pixel ring; `2` is two concentric rings. #### Restricting the hue arc [Section titled “Restricting the hue arc”](#restricting-the-hue-arc-1) Add `from` and `to` RGB colors to confine the cycle to a specific hue arc — the border will pulse between those two colors rather than sweeping the full spectrum. The engine always takes the shorter arc between the two hues.  flame → amber arc at \`speed = 2\` — border pulses only within the phoenix-warm band, never drifting into green or blue ```toml # Flame → amber arc — stays within the §6 brand palette border = {style = "color_cycle", from = [255, 92, 38], to = [255, 183, 3], speed = 2, thickness = 2} ``` `speed = 0` is rejected — use `border = [r, g, b]` for a static color. Achromatic `from`/`to` colors (gray, white, black) are also rejected since their hue is undefined. #### Common patterns [Section titled “Common patterns”](#common-patterns-1) **Brand-palette pulse** — lock the border to your two brand hues so it never wanders off-palette: ```toml border = {style = "color_cycle", from = [255, 92, 38], to = [255, 183, 3], speed = 2, thickness = 2} # Flame → amber pulse, 2-ring border ``` **Contrasting border from text** — pair a color\_cycle border with a complementary arc on `font_color`: ```toml [[playlist.section.widget]] type = "message" text = "Open" font_color = {style = "color_cycle", from = [255, 200, 50], to = [255, 100, 0], speed = 4} # amber arc border = {style = "color_cycle", from = [120, 230, 255], to = [50, 100, 255], speed = 4} # blue arc ``` ### Constant [Section titled “Constant”](#constant) A constant border is a solid-color ring with no animation. Because it never changes frame to frame (`frame_invariant`, an internal flag), the engine’s static-text fast path applies: the border is painted once and the widget sleeps for the hold duration rather than redrawing every tick. For multi-color animated stripes, see [Bands](#bands) below.  constant magenta ring around the panel perimeter, text inside Use an RGB list as a shorthand: RGB shorthand ```toml [[playlist.section.widget]] type = "message" text = "Hello" border = [255, 100, 200] # constant magenta ``` To add thickness, switch to an inline table: With thickness ```toml [[playlist.section.widget]] type = "message" text = "Hello" border = {style = "constant", color = [255, 100, 200], thickness = 2} ``` ### Bands [Section titled “Bands”](#bands) Discrete solid-color bands marching around the perimeter — the geometry of the rainbow chase, but with a list of solid colors instead of a continuous hue ramp. Candy-cane, barber-pole, and flag-ribbon looks.  candy\_cane palette — red/white bands marching clockwise `colors` is required (no bare-string shorthand): supply a named palette or a list of two or more RGB colors. Named palette ```toml [[playlist.section.widget]] type = "message" text = "Candy" border = {style = "bands", colors = "candy_cane"} ``` Explicit colors (Italy), wider bands, reverse march ```toml [[playlist.section.widget]] type = "message" text = "Ciao" border = {style = "bands", colors = [[0, 146, 70], [255, 255, 255], [206, 43, 55]], band_width = 8, speed = -1} ``` #### Named palettes [Section titled “Named palettes”](#named-palettes) | Palette | Bands | | ------------ | --------------------------------------------------------------------------------------------- | | `rainbow` | red, orange, yellow, green, blue, purple — discrete bands, vs. the continuous `rainbow` chase | | `rasta` | red, gold, green | | `usa` | red, white, blue | | `christmas` | red, green | | `halloween` | orange, purple | | `candy_cane` | red, white |  rasta palette, band\_width = 8, thickness = 2 #### Fields [Section titled “Fields”](#fields) | Field | Default | Meaning | | ------------- | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `colors` | — (required) | palette name or list of `[r, g, b]` (2+ entries), repeating in order | | `band_width` | `6` | perimeter pixels per band | | `speed` | `1` | pixels the pattern advances per frame; negative reverses; `0` = static | | `thickness` | `1` | concentric rings (`2` = two-pixel border) | | `align_rings` | `false` | at `thickness > 1`: radially align band boundaries across rings (stacked stripes; exact along edges, rings merge at corners) instead of the woven continuous-index look | With `speed = 0` the bands are static — like a constant border, the engine’s fast path applies and the border is painted once per hold. #### Common patterns [Section titled “Common patterns”](#common-patterns-2) **Stacked double-thick stripes** — at `thickness = 2` the rings share one continuous index by default, which reads as a woven texture (the GIF under [Named palettes](#named-palettes)). Add `align_rings = true` and the same config snaps into crisp stacked stripes, aligned exactly along every edge: ```toml # woven (default) — the rasta GIF above border = {style = "bands", colors = "rasta", band_width = 8, speed = 1, thickness = 2} # stacked — same config plus align_rings border = {style = "bands", colors = "rasta", band_width = 8, speed = 1, thickness = 2, align_rings = true} ```  align\_rings = true — stacked stripes, rings marching in lockstep **Holiday static accent** — a non-moving two-color frame that costs nothing per tick (`speed = 0` rides the fast path): ```toml border = {style = "bands", colors = "christmas", speed = 0, band_width = 10} # Static red/green frame — swap in "halloween" or "candy_cane" by season ``` **Reverse-march flag** — a named flag palette walking counter-clockwise at double speed: ```toml border = {style = "bands", colors = "usa", speed = -2} # Negative speed reverses direction; |speed| sets the pace ``` ## Where it works [Section titled “Where it works”](#where-it-works) | Widget type | `border`? | | ----------------------------- | -------------------------- | | `message` | yes | | `countdown` | yes | | `two_row` | yes | | `gif` | yes | | `image` | yes | | `weather.current`, `rss.feed` | no — raises at config load | Data widgets render custom layouts and a perimeter border is not a meaningful concept for them. The config validator catches any misplaced `border =` on these types at startup so the error surfaces immediately rather than silently doing nothing. ## Continuous-phase behavior [Section titled “Continuous-phase behavior”](#continuous-phase-behavior) All animated borders (`rainbow`, `color_cycle`, `bands`, `lightbulbs`) have `restart_on_visit = false` — their phase counters advance continuously and never reset between `loop_count` repetitions. If a section repeats with `loop_count = 2`, the border picks up exactly where it left off at the end of the first loop rather than snapping back to the start. The border also composes cleanly with other effects: a single scrolling line can carry `animation = "typewriter"` and `border = "rainbow"` simultaneously, and each effect tracks its own independent counter. See [frame counters](/reference/frame-counters/) for the full model of restart-on-visit versus continuous-phase behavior. ## Lightbulbs [Section titled “Lightbulbs”](#lightbulbs) The `lightbulbs` style paints discrete NxN bulb sprites around the perimeter — the classic Vegas-marquee aesthetic. Each bulb is a fixed-size square sprite at one of \~100 (bigsign-default) clockwise-ordered positions; the animation modes flip which bulbs are “lit” vs “unlit” per frame. Both colors paint every frame, so “off” bulbs glow dimly like physical incandescent bulbs without power — the default is a warm-white lit color over a dim warm-orange unlit color. The simplest form is the string shorthand: ```toml [[playlist.section.widget]] type = "message" text = "HELLO" border = "lightbulbs" ``` Defaults: `mode = "chase"`, `bulb_size = 3` on big panels (auto-falls back to `1` on panels shorter than 32 physical pixels), `gap = 3`, warm-white lit / dim-warm-orange unlit colors. ### Modes [Section titled “Modes”](#modes) * **`chase`** — every Nth bulb (default 3rd) is lit; the lit set walks clockwise (or `direction = "ccw"`) around the perimeter, advancing one bulb position every `speed_frames` engine ticks. Classic traveling-marquee look.  \`chase\` — warm-white marquee, the lit window travels clockwise * **`alternate`** — even/odd bulbs flip on each phase. Half the bulbs lit at any time, switching every `speed_frames` ticks. Looks like a shimmer or twinkle without directional motion.  \`alternate\` — even/odd bulbs flip in place, a directionless twinkle * **`unison`** — all bulbs share state. All lit, then all unlit, alternating every `speed_frames` ticks. Loud attention-grabber.  \`unison\` — every bulb blinks on and off together ### Full table form [Section titled “Full table form”](#full-table-form) ```toml border = { style = "lightbulbs", mode = "chase", # "chase" | "alternate" | "unison" bulb_size = 3, # optional; auto from panel height gap = 3, # pixels between bulb edges lit_color = [255, 220, 140], # warm white default; or "rainbow" unlit_color = [40, 20, 0], # dim warm-orange default speed_frames = 2, # frames per state transition chase_density = 3, # only used by mode="chase" direction = "cw", # "cw" | "ccw", only used by mode="chase" hue_wraps = 1.0 } # only used when lit_color = "rainbow" ``` `speed_frames` defaults differ by mode: `2` for chase (\~100 ms per bulb step), `5` for alternate (\~250 ms per toggle), `8` for unison (\~400 ms per blink). Higher values slow the animation; the engine ticks at 50 ms. ### Rainbow bulbs [Section titled “Rainbow bulbs”](#rainbow-bulbs) Set `lit_color = "rainbow"` to color each lit bulb by its position around the perimeter — a full hue spectrum wrapped around the ring. The hues are **static in space**: they do not rotate over time, so with `mode = "chase"` the lit window travels across a fixed string of colored bulbs, exactly like a strand of party or Christmas lights. Unlit bulbs keep their `unlit_color` glow.  \`lit\_color = "rainbow"\` with \`mode = "chase"\` — a traveling lit window over a fixed rainbow string ```toml [[playlist.section.widget]] type = "message" text = "PARTY" border = { style = "lightbulbs", mode = "chase", lit_color = "rainbow" } ``` **`hue_wraps`** (default `1.0`): how many full spectra tile around the perimeter. `1.0` wraps one rainbow once around the whole edge, so adjacent bulbs differ only subtly. Raise it to `2` or `3` to tile multiple rainbows and widen the per-bulb color contrast. ```toml # Two full spectra around the ring — punchier per-bulb color border = { style = "lightbulbs", lit_color = "rainbow", hue_wraps = 2 } ``` ### When to use each style [Section titled “When to use each style”](#when-to-use-each-style) `lightbulbs` reads as a **physical object** — a marquee of light fixtures. `rainbow` / `color_cycle` read as a **graphical effect**, a halo or outline. `bands` reads as a **themed ribbon**: use it when you want a recognizable color sequence (a flag, a holiday palette) rather than a spectrum sweep. `lightbulbs` is unconditionally animated (`frame_invariant = False`) — image-widget fast paths correctly force per-tick redraws on it, same as the other animated borders. #### Common patterns [Section titled “Common patterns”](#common-patterns-3) **Vegas / theatrical marquee** — a fast, tightly-packed traveling lit window: ```toml border = { style = "lightbulbs", mode = "chase", speed_frames = 1, chase_density = 2 } # Every other bulb lit, advancing one step per engine tick ``` **Rainbow party lights** — a calm static strand of colored bulbs, all lit at once: ```toml border = { style = "lightbulbs", mode = "chase", lit_color = "rainbow", chase_density = 1 } # chase_density = 1 lights every bulb — a steady rainbow strand ``` **Holiday / themed two-color** — pick a palette for lit and unlit, then alternate: ```toml border = { style = "lightbulbs", mode = "alternate", lit_color = [200, 30, 30], unlit_color = [20, 120, 40] } # Red / green holiday twinkle ``` See also * [concepts/color-providers](/concepts/color-providers/) * [reference/frame-counters](/reference/frame-counters/) * [widgets/message](/widgets/message/) # Busy light > A persistent corner dot that lights up while you're busy, painted as an overlay over every section and transition. The busy light is a persistent indicator — a small solid dot in a corner of the panel — that turns on while you’re “busy” and off when you’re not. It is **not** a playlist widget: it does not occupy a section or take a turn in the rotation. It paints as an **overlay** on top of whatever is currently on screen, so it stays lit continuously across every section and every transition. The MVP source is the simplest one that needs no accounts or API keys: a local **file**. While the file exists, the light is on; remove it and the light goes off. A background task re-checks the file every few seconds. (Real calendar / Slack / Teams sources are a planned addition behind the same overlay — see [Extending it](#extending-it-real-busy-sources).) ## How it works [Section titled “How it works”](#how-it-works) The light is a paint callback registered on the frame’s overlay hooks. Every time the engine pushes a frame to the panel — in the main scroll/hold loop, mid-transition, or inside an image/gif `play()` loop — that single swap point runs the overlay hooks on the **real** physical canvas just before the hardware swap. Because all three render paths route through that one swap, the dot composites over everything with no special per-path handling. Painting is a handful of `SetPixel` calls in physical pixels, so the per-frame cost is negligible. The state is read on the render side and written by the background poll task; both run in the same event loop, so the on/off flag needs no locking. ## Configuration [Section titled “Configuration”](#configuration) Add a top-level `[busy_light]` block (disabled by default): Minimal ```toml [busy_light] enabled = true file_path = "~/.busy" corner = "top_right" color = [255, 0, 0] size = 4 ``` | Field | Type | Default | Notes | | --------------- | ----------- | ------------- | ---------------------------------------------------------------------------------------------------------------- | | `enabled` | bool | `false` | Master switch. When `false`, nothing is built and there is zero per-frame cost. | | `file_path` | string | `"~/.busy"` | The light is on while this file exists. `~` expands to the home directory. See [Docker](#docker) for the gotcha. | | `poll_interval` | float | `5.0` | Seconds between file checks. Lower = snappier reaction; the file stat is cheap. | | `corner` | string | `"top_right"` | One of `top_left`, `top_right`, `bottom_left`, `bottom_right`. | | `color` | `[r, g, b]` | `[255,0,0]` | Three ints, each `0`–`255`. Validated at config load. | | `size` | int | `4` | Dot side length in **physical** pixels. See [Sizing](#sizing-per-panel). | ## Toggling it [Section titled “Toggling it”](#toggling-it) When running from a source checkout, the file path is literal: ```bash touch ~/.busy # light ON (within poll_interval) rm ~/.busy # light OFF ``` ### Docker [Section titled “Docker”](#docker) This is the one sharp edge. Under Docker — the usual deploy — `~/.busy` resolves to the **container’s** home directory, which your host shell can’t reach, so toggling `~/.busy` on the host does nothing. Point `file_path` at the **bind-mounted config dir** instead. The compose file mounts `./config:/code/config:ro`, so: Docker ```toml [busy_light] enabled = true file_path = "/code/config/.busy" # in-container path ``` ```bash touch config/.busy # on the host, from the repo dir → light ON rm config/.busy # → light OFF ``` The `:ro` mount only stops the **container** from writing; the host can freely create and delete `config/.busy`, and the container sees the change. The poller only reads the file (`exists()`), so read-only is fine. ## Remote trigger (HTTP) [Section titled “Remote trigger (HTTP)”](#remote-trigger-http) Instead of a local file, the light can be flipped by an HTTP call over your LAN — ideal for triggering it from another machine such as a work laptop. Set `source = "http"`: HTTP source ```toml [busy_light] enabled = true source = "http" http_host = "0.0.0.0" http_port = 8081 ttl_seconds = 0 # 0 = explicit on/off; >0 = auto-clear after N seconds ``` Set the shared secret in the **`LED_TICKER_BUSY_TOKEN`** environment variable (for example in your `.env`) — secrets belong in the environment, not in `config.toml`: ```bash LED_TICKER_BUSY_TOKEN=change-me ``` The display reads the token env-first. A `token = "…"` field in `[busy_light]` still works as a fallback, but it logs a warning at startup telling you to move it to `LED_TICKER_BUSY_TOKEN`. With neither set, the listener is open to anyone on the LAN. The listener exposes one route (`change-me` below stands in for your `LED_TICKER_BUSY_TOKEN` value): ```bash # turn the light on / off (GET with a query param — easiest for macros) curl "http://PI-HOST:8081/busy?state=on&token=change-me" curl "http://PI-HOST:8081/busy?state=off&token=change-me" # turn on, then auto-clear after 60 seconds (per-request TTL override) curl "http://PI-HOST:8081/busy?state=on&ttl=60&token=change-me" # POST with a body works too curl -X POST "http://PI-HOST:8081/busy" -H "X-Busy-Token: change-me" -d on # read current state curl "http://PI-HOST:8081/busy?token=change-me" ``` `PI-HOST` is your Pi’s `.local` hostname (e.g. `longboi.local`) or a DHCP-reserved IP. The token may be passed as the `token=` query param or an `X-Busy-Token:` header; a wrong/missing token returns `401`. A token in the query string can appear in logs — fine on a trusted LAN; use the header form if you’d rather not. ### Exposing the port [Section titled “Exposing the port”](#exposing-the-port) * **Docker deploy:** add a port mapping to that Pi’s compose service: ```yaml services: led-ticker: ports: - "8081:8081" ``` * **Source-checkout / dev:** the process binds the host port directly — no mapping needed; just make sure no host firewall blocks it. ### TTL (auto-clear) [Section titled “TTL (auto-clear)”](#ttl-auto-clear) A busy light can auto-clear after a set time, so you don’t have to remember to send `off`. There are two ways to set it: * **Per request** — add `&ttl=N` (seconds) to a `state=on` call: `…/busy?state=on&ttl=60`. The light turns on and clears itself after `N` seconds unless refreshed by another `state=on`. This overrides the config default for that one request; `ttl=0` means “stay on until an explicit off”. An invalid `ttl` (non-numeric, negative, or non-finite like `inf`/`nan`) returns `400`. `ttl` is always a **query parameter** — even on a POST it goes in the URL (`POST …/busy?ttl=60` with the state in the body), never in the request body. * **Config default** — `ttl_seconds` in `[busy_light]` applies to every `state=on` that omits `?ttl=`. `ttl_seconds = 0` (the default) means on-until-explicit-off; set e.g. `1800` for a 30-minute safety net if the sender sleeps mid-meeting and never sends `off`. TTL applies only to the HTTP source — the file source is polled directly and never arms a deadline. ### Triggering from a Mac [Section titled “Triggering from a Mac”](#triggering-from-a-mac) Both methods reduce to one HTTP call, so neither needs anything installed on a managed work laptop: * **Manual hotkey** — Keyboard Maestro, Raycast, or a Shortcut with a global key running `curl "http://PI-HOST:8081/busy?state=on&token=…"` (and an `off` twin). * **Focus automation (hands-off)** — macOS **Shortcuts → Automation → “When \[Work] focus turns On”** → action **Get Contents of URL** (GET) `http://PI-HOST:8081/busy?state=on&token=…`; add a matching *turns Off* automation with `state=off`. macOS itself is the detector — no background app of your own. * **Auto-detect from camera use** — for a fully hands-off “on while I’m in a meeting”, watch the camera and hit the endpoint. A ready-made [Hammerspoon](https://www.hammerspoon.org) script ships in the repo at [`deploy/busy-light-camera-watcher.lua`](https://github.com/JamesAwesome/led-ticker/blob/main/deploy/busy-light-camera-watcher.lua): it flips the light on whenever any camera turns on (Zoom, Google Meet, FaceTime) and off when they all stop. Set `PI_HOST`/`TOKEN` at the top and follow the install steps in the file header. Note: a call joined with video **off** never turns the camera on, so it won’t trigger — camera use is the signal. ## Sizing per panel [Section titled “Sizing per panel”](#sizing-per-panel) `size` is in physical pixels, so the right value depends on panel height: | Panel | Height | Suggested `size` | | ----------------- | ------ | ---------------- | | Smallsign | 16 px | `3`–`4` | | Bigsign / longboi | 64 px | `8`–`10` | A `size = 4` dot is a quarter of the smallsign’s height — clearly visible. The same `4` on a 64-tall panel is a barely-visible speck, so bump it to `8`–`10` there. The dot paints **last** each frame (over the content), so it’s never hidden by what’s underneath. ## Extending it (real busy sources) [Section titled “Extending it (real busy sources)”](#extending-it-real-busy-sources) The overlay mechanism is generic and the busy state is a plain flag, so a real source is a drop-in: a new poller whose `update()` sets the busy flag from an API (Google Calendar free/busy, a Slack/Teams presence endpoint) using the shared HTTP session and the standard background-poll loop, registering the same kind of corner-dot paint hook. Nothing in the frame or the overlay mechanism changes — only where the on/off signal comes from. This is planned, not yet shipped. See also * [concepts/display](/concepts/display/) * [reference/config-options](/reference/config-options/) # Color providers > Constant, rainbow, gradient, color_cycle, shimmer, and random — how font_color accepts more than just an RGB list. `font_color` accepts six forms: a `[r, g, b]` list (constant), the string shorthands `"rainbow"`, `"color_cycle"`, `"shimmer"`, and `"random"`, or an inline table for a gradient, a ranged color cycle, or a tuned shimmer. The constant, rainbow, and color\_cycle forms cover most signs. The same field on `top_color` / `bottom_color` for `two_row` and image widgets behaves identically — pick once per widget, swap providers without changing anything else.  rainbow → color\_cycle → gradient → constant → random (shimmer not shown) Shimmer has its own demo further down — see [Shimmer](#shimmer). ## The six providers [Section titled “The six providers”](#the-six-providers) | Provider | Syntax | Per-char? | Animates? | | ---------------- | ------------------------------------------------------------ | --------- | ---------------------------------- | | Constant | `[r, g, b]` | no | no | | Rainbow | `"rainbow"` | **yes** | yes — hue sweeps per frame | | ColorCycle | `"color_cycle"` | no | yes — whole-string hue rotation | | ColorCycle range | `{style = "color_cycle", from = [...], to = [...], speed=N}` | no | yes — restricted hue arc | | Gradient | `{style = "gradient", from = [...], to = [...]}` | **yes** | no — frozen interpolation | | Shimmer | `"shimmer"` or `{style = "shimmer", shimmer = "gold", ...}` | **yes** | yes — bright-spot sweep with pause | | Random | `"random"` | no | no — picks once on visit | **Per-char** providers (rainbow, gradient, shimmer) assign a unique color to each character position and call `color_for` once per character per draw. **Whole-string** providers (constant, color\_cycle, random) compute one color per draw and apply it to the entire message. ## Constant [Section titled “Constant”](#constant) The simplest case — a fixed `[r, g, b]` triplet. Nothing animates; the color is stable across every frame and every loop. ```toml [[playlist.section.widget]] type = "message" text = "Now Open" font_color = [255, 200, 0] ``` ## Rainbow [Section titled “Rainbow”](#rainbow) Per-character hue offset that advances each frame. The first character starts at a different hue than the second, and every character’s hue sweeps forward 8° per tick (default). `rainbow` is a continuous-phase provider — the sweep does not reset between `loop_count` repetitions, so the color keeps flowing rather than snapping back to the start on each pass. ```toml [[playlist.section.widget]] type = "message" text = "Grand Opening" font_color = "rainbow" ``` Fine-tune with an inline table if the defaults are too fast or too spread: ```toml [[playlist.section.widget]] type = "message" text = "Grand Opening" font_color = {style = "rainbow", speed = 4, char_offset = 20} ``` `speed` is hue degrees advanced per 50 ms tick (default 8). `char_offset` is the hue gap between consecutive characters (default 30). ## ColorCycle [Section titled “ColorCycle”](#colorcycle) Whole-string hue rotation — every character shares one color, and that color cycles through the spectrum over time. Subtler than rainbow; useful when you want motion without the striped look. Also continuous-phase — the cycle does not reset between loops. ```toml [[playlist.section.widget]] type = "message" text = "Now Playing" font_color = "color_cycle" ``` Speed is configurable via `{style = "color_cycle", speed = N}` (degrees per tick, default 5). ### Restricting the hue arc [Section titled “Restricting the hue arc”](#restricting-the-hue-arc) Add `from` and `to` RGB colors to restrict the cycle to the shorter arc between those two hues instead of sweeping the full wheel. The engine always takes the shorter path — `from = [255, 0, 0]` (red) and `to = [0, 0, 255]` (blue) sweeps through the 120° magenta/violet arc rather than the 240° yellow/green/cyan arc. Without `from`/`to`, full-wheel behavior is unchanged. ```toml [[playlist.section.widget]] type = "message" text = "Now Playing" font_color = {style = "color_cycle", from = [225, 48, 108], to = [120, 230, 255], speed = 5} ``` `from` and `to` must both be present or both absent. Achromatic colors (gray, white, black) are rejected — their hue is undefined. `speed = 0` is also rejected; use a plain `[r, g, b]` constant instead. ### Common patterns [Section titled “Common patterns”](#common-patterns) **Brand palette sweep** — limit the cycle to your two brand colors so the animation never wanders into off-brand hues: ```toml font_color = {style = "color_cycle", from = [255, 92, 38], to = [255, 183, 3], speed = 3} # Flame → amber — stays in the phoenix-warm arc ``` **Warm-cool oscillation** — a tight arc between two complementary hues creates a slow temperature-shift effect: ```toml font_color = {style = "color_cycle", from = [255, 140, 0], to = [120, 230, 255], speed = 2} # Amber → cyan — warm/cool pulse ``` ## Gradient [Section titled “Gradient”](#gradient) A frozen left-to-right interpolation between two colors. `char_index` drives the interpolation; the frame counter is ignored — so the colors never shift, but each character gets its own tint. Unlike rainbow and color\_cycle, gradient does not require the per-tick render loop; the engine can take a paint-once-and-sleep fast path for otherwise-static content. ```toml [[playlist.section.widget]] type = "message" text = "Fade Effect" font_color = {style = "gradient", from = [255, 80, 80], to = [80, 80, 255]} ``` `from` and `to` are `[r, g, b]` triplets. The first character gets `from`, the last gets `to`, and all others interpolate linearly between them. ## Shimmer [Section titled “Shimmer”](#shimmer) A bright spot glides left-to-right across the text — one `shimmer_color` highlight sweeping over a `base_color` rest state — then pauses, then repeats. The spot fades in and out with a cosine curve so it blends smoothly rather than clipping abruptly. ```toml [[playlist.section.widget]] type = "message" text = "Now Hiring" font_color = "shimmer" ``` `"shimmer"` as a plain string uses the defaults: dim blue-gray base, white highlight, 14 chars/second, 8-char-wide spot, 0.5 s pause between sweeps. Tune with an inline table: ```toml [[playlist.section.widget]] type = "message" text = "Grand Opening" font_color = {style = "shimmer", base = [40, 40, 60], shimmer = "gold", speed = 10, width = 6, pause = 1.0} ``` | Field | Default | Description | | --------- | -------------- | -------------------------------------------------------------------------------- | | `base` | `[60, 60, 80]` | Rest color. `[r, g, b]` or a shorthand: `"white"`, `"gold"`, `"blue"`, `"cyan"`. | | `shimmer` | `"white"` | Highlight color. Same formats as `base`. | | `speed` | `14.0` | Chars per second the spot travels. Lower = slower, dreamier. | | `width` | `8.0` | Spot width in chars. Wider = broader glow; narrower = sharper. | | `pause` | `0.5` | Seconds of rest (base color only) between sweeps. | Shimmer is a continuous-phase provider — it does not reset between `loop_count` repetitions, so the sweep keeps flowing across playlist loops rather than snapping back to the start. When a section transition fires while a shimmer sweep is mid-glide, the engine waits up to roughly one second for the spot to reach its pause window before switching scenes, so the bright spot isn’t teleported by the cut. Sweeps that need longer than a second to reach their pause — or a `pause` shorter than a single frame — transition immediately, as before. **Shimmer with a dark base color:** The base defaults to a dark blue-gray (`[60, 60, 80]`). If you want truly black resting characters, set `base = [0, 0, 0]`. High-contrast setups (dark base, bright shimmer) look best; a light base with a slightly-brighter shimmer produces a subtle, professional feel. ### Common patterns [Section titled “Common patterns”](#common-patterns-1)  frost → gold coin → hot ember → neon breathe **Frost** — cool blue rest state, white highlight, slow sweep. The spot glides wide and lazy across the text, leaving it dim and icy at rest. ```toml font_color = {style = "shimmer", base = "blue", shimmer = "white", speed = 5, width = 4, pause = 1.2} ``` **Gold coin** — dark amber base, classic gold `[255, 215, 0]` (#FFD700) highlight. Narrow, fast sweep with a pause between cycles — the bright streak catches and disappears like light glancing off a spinning coin. ```toml font_color = {style = "shimmer", base = [90, 55, 0], shimmer = [255, 215, 0], speed = 18, width = 3, pause = 0.8} ``` **Hot ember** — near-black red base, orange highlight. Medium speed, narrow width — a glowing coal that briefly catches. ```toml font_color = {style = "shimmer", base = [60, 10, 0], shimmer = [255, 120, 30], speed = 12, width = 4, pause = 0.6} ``` **Neon breathe** — near-black base, bright cyan highlight, wide spot, no pause. The spot sweeps without stopping, so the text breathes continuously rather than flashing and going dark. ```toml font_color = {style = "shimmer", base = [0, 5, 0], shimmer = [0, 230, 200], speed = 5, width = 10, pause = 0} ``` ## Random [Section titled “Random”](#random) Picks a single random color at widget construction and holds it for the duration of the visit. The color does not change frame-to-frame or character-to-character; it just picks something different each time the section plays. Useful for adding variety to long-running displays without any visible animation. ```toml [[playlist.section.widget]] type = "message" text = "Daily Special" font_color = "random" ``` ## Which to use [Section titled “Which to use”](#which-to-use) * **Constant** — brand colors, anything that shouldn’t animate. * **Color\_cycle** — the whole message shifts hue together; subtler than rainbow. Add `from`/`to` to keep the sweep inside your brand palette. * **Rainbow** — per-character hue sweep; use it when flair is the point (kids’ sections, grand openings, announcements). * **Gradient** — frozen left-to-right interpolation; good when your brand has two anchor colors you want to bridge. * **Shimmer** — a gliding bright-spot sweep; good for drawing attention to a single message, “now open” signage, or any case where you want motion without the full color-sweep effect. * **Random** — picks a different color each time the section plays; no animation. ## Inline emoji and per-char providers [Section titled “Inline emoji and per-char providers”](#inline-emoji-and-per-char-providers) Rainbow and gradient sweep continuously across `:slug:` emoji boundaries. The sprite still renders in its own native colors, and the surrounding text gets per-character colors with the index advancing across the emoji segments without resetting. This means the hue does not jump or restart when it crosses an emoji — the stripe flows through the whole message as if the emoji were transparent to the color math. ```toml [[playlist.section.widget]] type = "message" text = ":star: Now Enrolling :star:" font_color = "rainbow" ``` ## Colors and animations are independent [Section titled “Colors and animations are independent”](#colors-and-animations-are-independent) `font_color` and `animation` are separate axes on a `message` widget. A widget can carry both simultaneously — for example `font_color = "rainbow"` and `animation = "typewriter"` — and each effect tracks its own frame counter independently. Characters type out in rainbow with no interference between the two effects. See [animations](/concepts/animations/) for the full animation vocabulary. See also * [concepts/fonts](/concepts/fonts/) * [widgets/message](/widgets/message/) * [assets/emoji](/assets/emoji/) # Display > How rows, cols, chain_length, parallel, scale, and pixel_mapper_config combine into a logical canvas. The `[display]` block describes your panel’s physical geometry: pixel dimensions per panel, chain length, and scaling. These values flow into every layout calculation, so a mismatch between config and hardware clips content or centers it on the wrong axis. ## The two reference builds [Section titled “The two reference builds”](#the-two-reference-builds) Two hardware configurations ship as ready-to-use examples — the maintainer’s day-to-day rigs that the demos and example configs are written against. You can match them, scale them, or build something different; the engine only cares about what `[display]` declares. The **smallsign** is a Raspberry Pi 4 with five 32×16 panels chained horizontally for a 160×16 canvas. The **bigsign** is a Raspberry Pi 5 with eight P3 32×64 panels arranged in a 2×4 vertical-serpentine layout for a 256×64 canvas. Smallsign — Pi 4 + 5× 32×16 panels = 160×16 logical ```toml [display] rows = 16 cols = 32 chain_length = 5 default_scale = 1 brightness = 60 gpio_slowdown = 2 ``` Bigsign — Pi 5 + 8× P3 32×64 vertical-serpentine 2×4 = 256×64 logical ```toml [display] rows = 32 cols = 64 chain_length = 8 parallel = 1 pixel_mapper_config = "Remap:256,64|192,32n|192,0n|128,32n|128,0n|64,32n|64,0n|0,32n|0,0n" default_scale = 4 brightness = 60 gpio_slowdown = 3 pwm_bits = 8 ``` ## Logical canvas vs real panel [Section titled “Logical canvas vs real panel”](#logical-canvas-vs-real-panel) When `default_scale > 1`, the engine wraps the real panel in a `ScaledCanvas` — the layer that expands logical pixels onto a big / scaled sign. All drawing logic stays at “16-tall logical content,” so widgets never need to know what scale they are running at; the wrapper expands each logical pixel to a `scale×scale` block on the real canvas and centers the content vertically. *For developers and plugin authors:* that expansion happens per `SetPixel` call. There is one hard ceiling you must respect: **`content_height × scale ≤ panel_h_real`**. For the bigsign at `scale = 4`, this means `content_height ≤ 16`. Push above the ceiling and the logical canvas is taller than the real panel; content placed near the top or bottom edges silently clips. If you need per-section breathing room, use `text_y_offset` on the widget rather than over-specifying `content_height`. ## Per-section overrides [Section titled “Per-section overrides”](#per-section-overrides) `scale` and `content_height` can also be set per section, overriding the display-level defaults. The classic case is a `two_row` widget: its two text rows need more horizontal room to fit handles like `@firebird.demo`, so it typically runs at `scale = 2`, giving 128 logical pixels of width instead of the default 64. ```toml [[playlist.section]] mode = "slideshow" scale = 2 content_height = 24 hold_time = 4.0 ``` ## Scheduling [Section titled “Scheduling”](#scheduling) `[display.schedule]` lets you automatically dim or darken the sign during certain hours — useful for not blasting full brightness at 3 a.m. The schedule is driven by a lightweight background task that wakes every \~30 seconds and adjusts `matrix.brightness` to match whichever window is active right now. ### Windows [Section titled “Windows”](#windows) A schedule is a list of `[[display.schedule.windows]]` entries. Each window covers a time range and specifies a brightness: ```toml [display.schedule] enabled = true timezone = "America/New_York" # set this — fresh Pis are often UTC [[display.schedule.windows]] start = "07:00" end = "18:00" brightness = 100 [[display.schedule.windows]] start = "18:00" end = "23:00" brightness = 40 [[display.schedule.windows]] start = "23:00" # wraps past midnight end = "07:00" brightness = 0 # dark — panel off overnight ``` `brightness = 0` makes the LEDs go dark (≈ zero panel power draw). **This is not a power or sleep mode** — the Pi keeps rendering at full cadence; only the LED brightness output goes to zero. ### Window resolution [Section titled “Window resolution”](#window-resolution) At each check the scheduler finds the **last matching window** in the list whose time range includes the current wall-clock time. “Last” means highest index, so place more-specific or higher-priority windows after the general ones. Because the **last** matching window wins, place a more specific window *after* a general one to override it. For example, a normal day with a dimmer lunch hour: ```toml [[display.schedule.windows]] start = "07:00" end = "23:00" brightness = 100 [[display.schedule.windows]] start = "12:00" # overrides the window above during lunch end = "13:00" brightness = 40 ``` A window **wraps past midnight** when `end < start` (e.g. `start = "23:00"`, `end = "07:00"`). That window is active from 23:00 until 06:59. ### Day filtering [Section titled “Day filtering”](#day-filtering) Add a `days` list to a window to restrict it to specific weekdays: ```toml [[display.schedule.windows]] start = "08:00" end = "18:00" brightness = 100 days = ["mon", "tue", "wed", "thu", "fri"] # weekdays only [[display.schedule.windows]] start = "10:00" end = "22:00" brightness = 60 days = ["sat", "sun"] # weekends on a gentler setting ``` An empty `days` list (the default) matches every day of the week. Midnight-wrapping windows and `days` A window that wraps past midnight (`start > end`) is anchored to its **start day**. For example: ```toml start = "23:00" end = "07:00" days = ["fri"] ``` This window is active from **Friday 23:00 through Saturday 06:59**. The early-Saturday tail belongs to Friday’s entry — not to Saturday’s — because the window started on Friday. If you also want Saturday-night coverage, add a separate window with `days = ["sat"]`. ### Timing and behavior [Section titled “Timing and behavior”](#timing-and-behavior) * **Boundary latency**: brightness changes land within approximately 30 seconds of the scheduled time, not instantly at the second. * **Step, not fade**: brightness jumps in one step when a window becomes active — there is no fade animation. * **Schedule changes need a restart**: the schedule is read at startup; there is no live-reload. Restart the display process after editing `[display.schedule]`. * **Timezone**: `timezone` accepts any IANA name (e.g. `"America/New_York"`, `"Europe/London"`). Leave it empty to use the Pi’s system time — but set it explicitly if you can; freshly imaged Pis default to UTC, which will shift your windows by several hours. ### Viewing the resolved schedule [Section titled “Viewing the resolved schedule”](#viewing-the-resolved-schedule) Run `led-ticker validate config.toml` to see the resolved schedule printed alongside the usual validation output. This is useful for confirming window coverage and catching gaps before deploying. ## `[display]` reference [Section titled “\[display\] reference”](#display-reference) The full field reference — every knob, default value, and Pi-version note — lives at [Reference: Config options](/reference/config-options/#display). The most-touched fields are above (`rows`, `cols`, `chain_length`, `default_scale`, `pixel_mapper_config`, `gpio_slowdown`); see the reference page when you need `pwm_bits`, `pwm_lsb_nanoseconds`, `rp1_pio`, or the other Pi-tuning options. See also * [concepts/fonts](/concepts/fonts/) * [widgets/two\_row](/widgets/two_row/) * [getting-started](/getting-started/) # Fonts > BDF bitmap fonts vs hi-res TTF/OTF — what to pick and why. Every text-bearing widget — `message`, `countdown`, `two_row`, `weather.current`, and the text overlay on `gif`/`image` — picks a font. led-ticker ships two flavors: pre-rasterized BDF bitmap fonts and scalable hi-res TTF/OTF fonts. The right choice depends on your panel scale and viewing distance.  BDF 6x12 (left) vs Inter-Bold @ 14px (right)  Bigsign canvas (256×64) — BDF 6×12 stretched to 48 real px (chunky) vs Inter-Bold @ 28 px (smooth, half-panel-height) ## BDF: the bundled bitmap fonts [Section titled “BDF: the bundled bitmap fonts”](#bdf-the-bundled-bitmap-fonts) BDF fonts are pre-rasterized pixel-by-pixel at a fixed cell size — there is no antialiasing, no threshold tuning, and no runtime rendering overhead. They load instantly and look crisp at the sizes they were designed for. Four aliases ship with led-ticker; the numbers are pixel cell width × height: | Alias | Cell size | Python constant | Notes | | ------ | --------- | --------------- | --------------------------------------------------------- | | `5x8` | 5×8 px | `FONT_SMALL` | Smallest readable size; fits two rows on a 16-tall canvas | | `6x10` | 6×10 px | `FONT_DELTA` | Compact alternative to the default | | `6x12` | 6×12 px | `FONT_DEFAULT` | **Default font** — omit `font` to get this | | `7x13` | 7×13 px | `FONT_LABEL` | Slightly wider strokes; good for short labels | ```toml [[playlist.section.widget]] type = "message" text = "Hello" font = "6x12" # default — can omit ``` ## Hi-res (TTF / OTF) for the bigsign [Section titled “Hi-res (TTF / OTF) for the bigsign”](#hi-res-ttf--otf-for-the-bigsign) At `default_scale = 4`, BDF text is 12 real pixels tall — small on a 64-row panel. Hi-res fonts render at any real-pixel size you specify, using the bundled Inter typeface or a font you supply yourself. Two fonts ship bundled: `Inter-Regular` and `Inter-Bold`. For a brand font (for example Adobe Beloved Sans), drop the `.otf` or `.ttf` file into `config/fonts/` next to your `config.toml` and reference it by filename stem. The directory is gitignored so licensed fonts stay off the repository. `font_size` is required for all hi-res fonts — the rasterizer needs an explicit real-pixel target and there is no sensible default to fall back on. ```toml [[playlist.section.widget]] type = "message" text = "Hello" font = "Inter-Bold" font_size = 28 ``` ## font\_threshold [Section titled “font\_threshold”](#font_threshold) Hi-res glyphs are anti-aliased during rasterization and then binarized to 1-bit before painting to the panel (LEDs are either on or off). `font_threshold` (0–255, default 128) is the cutoff: pixels at or above it are lit; below it are dark. The default 128 works well for medium-stroke fonts like Inter at typical bigsign sizes. Thin-stroked fonts — for example Beloved Sans Regular at 24–32 px — have anti-aliased edge pixels that land in the 60–100 range; at the 128 default those edges get clipped to zero, leaving glyphs visibly broken. Dropping to \~80 includes those edge pixels and restores the correct weight. **Match thresholds within a font family.** Bold at 128 has fewer lit pixels than Regular at 80 because the lower threshold fattens the regular strokes past Bold’s natural weight. Set both to the same value: ```toml [[playlist.section.widget]] type = "message" text = "@firebird.demo" font = "Beloved-Sans-Bold" font_size = 28 font_threshold = 80 # same threshold as Regular below [[playlist.section.widget]] type = "message" text = "Open 7 days" font = "Beloved-Sans-Regular" font_size = 24 font_threshold = 80 # match Bold above to preserve weight contrast ``` BDF fonts ignore `font_threshold` entirely — their bitmaps are already 1-bit. ## Character coverage [Section titled “Character coverage”](#character-coverage) Hi-res fonts pre-rasterize a fixed character set when the font loads, not lazily on demand. The set covers what most signage actually uses: * **ASCII printable**: the standard `string.printable` range — letters, digits, punctuation, whitespace. * **Extended Latin**: the most common Latin-1 accented characters (`àáâãäåæçèéêëìíîïñòóôõöøùúûüýÿ` + uppercase variants), so European-language RSS feeds render correctly. * **Extended punctuation**: bullet (`•`), middle-dot (`·`), ellipsis (`…`), em-dash (`—`), en-dash (`–`), curly quotes (`’‘“”`), and guillemets (`«»`) — the typographic marks that show up in headlines, separator lists, and brand copy. Any character outside this set falls back to the `?` glyph at render time. If you see a `?` on the panel where you expected your character, the codepoint isn’t in the rasterized set — the fix is to extend `EXTENDED_LATIN` or `EXTENDED_PUNCTUATION` in `src/led_ticker/fonts/hires_loader.py` and rebuild. A tripwire test (`tests/test_hires_font_loader.py:test_glyphs_for_extended_punctuation`) asserts the punctuation set stays rasterized AND that each glyph has lit pixels — catches both “char missing from the set” regressions and “char in set but threshold-clipped to zero pixels” issues. BDF fonts have no fallback mechanism — characters not in the BDF’s bitmap are skipped entirely (zero advance, no glyph drawn). For BDF widgets, stick to ASCII unless you’ve verified the BDF you picked includes the codepoints you need. ## Decision tree [Section titled “Decision tree”](#decision-tree) | Panel | Viewing distance | Recommended | | -------------------------------- | ---------------- | ------------------------------------------ | | Smallsign (160×16, scale=1) | Any | BDF `6x12` (default) — pixel-perfect at 1× | | Bigsign (256×64, scale=4), close | ≤ 6 ft | BDF or `Inter-Bold` @ 16–22 px | | Bigsign, medium | 6–20 ft | `Inter-Bold` @ 22–28 px | | Bigsign, far (across the street) | > 20 ft | `Inter-Bold` @ 28–32 px | See also * [concepts/display](/concepts/display/) * [concepts/color-providers](/concepts/color-providers/) * [widgets/message](/widgets/message/) # Config hot-reload > How led-ticker picks up config.toml changes while the sign is running — no restart needed for most edits. With config hot-reload enabled (the default), editing `config.toml` while the sign is running causes the display process to pick up the change automatically — no restart, no brief blank panel, no dropped-frame glitch. The old config stays active until the new one passes validation, so a typo never takes the sign down. ## What reloads, what does not [Section titled “What reloads, what does not”](#what-reloads-what-does-not) | What changed | Effect | | ----------------------------------------------------------------- | ----------------------------------------------------------------- | | `[[playlist.section]]` — sections, widgets, transitions | Reloaded at the start of the next full playlist cycle | | `[display] brightness` | Applied within \~30 seconds (the schedule tick interval) | | `[display.schedule]` — windows, timezone | Reloaded along with the rest of `[display]` | | `[display]` hardware fields (rows, cols, chain\_length, scale, …) | **Restart required** — these wire into the GPIO driver at startup | | `[busy_light]` | **Restart required** | | `[plugins]` | **Restart required** — plugins register at startup | | `[web]` | **Restart required** | If you change a restart-required field, the reload is still accepted (the reloadable changes take effect), and the sign logs a warning listing which fields need a restart. The [web status UI](/concepts/web-status-ui/) shows the same list in the **Last config reload** card under `restart_required`. ## How it works [Section titled “How it works”](#how-it-works) The display process checks `config.toml` for modifications at the top of every full playlist cycle — between the last widget of one pass and the first widget of the next. If the file’s modification time has changed, it: 1. Validates the new config in full (the same check `led-ticker validate` runs). 2. If validation fails, logs the error and keeps running on the old config — the panel never goes dark. 3. If validation passes, swaps in the new config, rebuilds the widget pool, and continues. The swap happens only between cycles, so the running cycle always finishes consistently on one config — it never splits a section across a config boundary. ## Enabling and disabling [Section titled “Enabling and disabling”](#enabling-and-disabling) Hot-reload is on by default. To opt out: Disable hot-reload ```toml [display] hot_reload = false ``` With `hot_reload = false`, the display process ignores `config.toml` modifications after startup. You need a restart for any config change to take effect. ## Feedback [Section titled “Feedback”](#feedback) **Logs** — each reload attempt logs at one of three levels: * **INFO** — clean success: `config reloaded`. * **WARNING** — partial success: `config reloaded (partial); restart required for: ` (display hardware fields changed; a restart is needed for those to take effect). * **ERROR** — rejected: `config reload rejected: ` (the new config failed validation; the running config is unchanged). ```bash docker compose logs -f led-ticker | grep reload ``` **Web status UI** — the Status tab’s **Last config reload** card shows the timestamp, whether it succeeded, the error message on failure, and which fields (if any) need a restart. The card is hidden until the first reload attempt after startup. See [Web status UI](/concepts/web-status-ui/#status-tab--snapshot-fields) for the full `last_reload` field shape. ## In Docker [Section titled “In Docker”](#in-docker) The `config` directory is mounted read-only (`./config:/code/config:ro`), which does not prevent the Pi’s own editor from updating the host file — the container sees the change through the bind mount. Hot-reload works the same way in Docker as when running from a source checkout. Tip Use `led-ticker validate config.toml` (or the web UI’s Validate tab) to confirm a candidate config before saving it — a validation pass on the command line guarantees the same check the hot-reload path runs. ## If the reload is not picking up your change [Section titled “If the reload is not picking up your change”](#if-the-reload-is-not-picking-up-your-change) * Confirm `hot_reload = false` is not set in your `[display]` block. * Check that the file’s modification time actually changed — some editors write to a temp file and rename; that still changes `mtime` and triggers a reload. A few (rare) setups write in place without updating `mtime` — `touch config.toml` forces a check. * The reload runs between cycles, not mid-render, so it may take up to one full playlist cycle to appear (a few seconds to a minute depending on hold times and widget count). * Check `docker compose logs led-ticker` for a `reload rejected` line — that means the new config failed validation and the old one is still running. See also * [concepts/web-status-ui](/concepts/web-status-ui/) * [reference/config-options](/reference/config-options/) * [reference/cli](/reference/cli/) # How rendering works > The render pipeline — what happens between your TOML config and the panel lighting up. The engine loop, the canvas, overlays, and the swap. This page is a mental model of **what happens between your `config.toml` and the panel lighting up** — useful whether you’re tuning a config or building a plugin. The other concept pages go deep on each piece; this one shows how they fit together.  A rainbow message on the panel — here's the pipeline that produces it. ## The pipeline [Section titled “The pipeline”](#the-pipeline) ```plaintext Config (TOML) ↓ parsed at startup Playlist → sections → widgets ↓ engine tick (~20 fps) widget.draw() → logical canvas ↓ ScaledCanvas expands it (when scale > 1) overlay hooks paint (e.g. the busy light) ↓ LedFrame.swap() → double-buffered → panel ``` Each section below is one step of that flow. ## The engine loop [Section titled “The engine loop”](#the-engine-loop) At startup, led-ticker parses your config into a **playlist** of [sections](/concepts/sections-and-modes/), each holding one or more **widgets**. Then a background engine runs a steady loop at **20 frames per second** — one *tick* every 50 ms. On each tick the engine: 1. **advances the frame counter(s)** — every animated effect (rainbow text, a color cycle, a typewriter) has [its own counter](/reference/frame-counters/) that moves one step; 2. **redraws** the current widget onto the canvas at its new frame; 3. **pushes** the finished frame to the panel (below), then sleeps until the next tick. A section’s **mode** decides how its widgets are shown — held in place (`slideshow`) or scrolling — and for how long; **[transitions](/transitions/)** play the animation between one widget or section and the next. (An effect whose output doesn’t change with the frame skips the per-tick redraw — see [frame counters](/reference/frame-counters/).) ## The canvas [Section titled “The canvas”](#the-canvas) Widgets don’t draw to physical LEDs directly. They draw to a **logical canvas** — a fixed 16-pixel-tall grid — using simple `(x, y)` coordinates, so a widget never needs to know how big your sign is. When your `[display]` runs at `scale > 1` (a big sign), a **`ScaledCanvas`** wraps the real panel and expands every logical pixel into a `scale × scale` block, centering the content vertically. That’s the short version — [Display](/concepts/display/) covers scaling, the `content_height × scale` ceiling, and per-section overrides in full. ## Reaching the panel [Section titled “Reaching the panel”](#reaching-the-panel) When a frame is ready, the engine calls **`LedFrame.swap()`** — the buffer swap, unrelated to the `slideshow` section mode above — which does two things in order: 1. runs every registered **overlay hook** — paint functions that draw *over* whatever’s on screen, every frame, like the [busy light](/concepts/busy-light/)’s status dot; 2. performs a **double-buffered swap**: the new frame is sent to the panel while the next one is drawn off-screen, so the display never tears or flickers mid-update. Then the loop sleeps and the next tick begins. ## Why it’s built this way [Section titled “Why it’s built this way”](#why-its-built-this-way) A few deliberate choices explain the rest: * **A fixed tick.** Driving everything from one steady \~20 fps clock keeps animations smooth and in sync, and makes timing predictable across very different signs. * **A write-only panel.** The hardware framebuffer can be written but not read back, so widgets and effects **recompute each frame** from their frame counter rather than reading the current pixels — that’s why effects are functions of the frame number. * **Logical, then physical.** Keeping drawing in logical 16-tall coordinates and expanding to the real panel at swap time means one widget runs unchanged on a tiny sign or a giant one. The full engineering rules behind this — the hardware-rendering constraints that keep the panel from freezing — live in [`docs/plugin-system.md`](https://github.com/JamesAwesome/led-ticker/blob/main/docs/plugin-system.md) and the project’s `CLAUDE.md`, for contributors and plugin authors who need them. See also * [concepts/display](/concepts/display/) * [concepts/sections-and-modes](/concepts/sections-and-modes/) * [transitions](/transitions/) # Sections and modes > Sections group widgets, modes pick the run style — slideshow, ticker, or one_at_a_time. The `[[playlist.section]]` block is the fundamental unit of a led-ticker program. Each section groups one or more widgets and tells the engine how to run them. Three modes are available: `slideshow`, `ticker`, and `one_at_a_time`. A playlist is just an ordered list of sections. The engine runs them in sequence, firing a section-to-section transition at each boundary, and loops back to the start when the last section finishes. ## `ticker` — side-by-side continuous stream [Section titled “ticker — side-by-side continuous stream”](#ticker--side-by-side-continuous-stream) All widgets in the section are joined into a single continuous stream that scrolls left across the panel without stopping. Each widget follows immediately after the last, separated by a `•` bullet character. The stream loops: when the last widget exits the left edge, the first re-enters from the right. This is the classic news ticker or stock crawl — one unbroken ribbon of content. `ticker` suits short-text widgets that the reader can absorb at a glance: a weather condition, a price update, a brief announcement. Combine several short widgets and the stream stays lively without any pauses. Transitions are not used between widgets in this mode — the bullet separator is the only break. The separator is customizable per section. Set `separator` to any string — `" * "` or `" | "` are common alternatives — or `""` for a minimal two-space gap with no glyph. `separator_color` accepts the same shapes as widget `font_color` (constant `[r, g, b]`, `"rainbow"`, or a gradient table). `separator_font` and `separator_font_size` let you match the separator’s typeface to the rest of the section. All four fields are rejected on non-`ticker` modes. `separator_size` shrinks or grows the bigsign separator circle (default 8; radius = size ÷ 2); it does not affect the smallsign BDF `•`.  \`ticker\` — three messages and a countdown flow together separated by bullets; the panel never clears ```toml [[playlist.section]] mode = "ticker" loop_count = 1 scroll_step_ms = 35 [[playlist.section.widget]] type = "message" text = "Open 9-5" font_color = [225, 48, 108] [[playlist.section.widget]] type = "countdown" text = "Summer Camps" countdown_date = 2026-06-20 font_color = [120, 220, 255] [[playlist.section.widget]] type = "message" text = "Free coffee Friday" font_color = [255, 220, 0] [[playlist.section.widget]] type = "message" text = "All ages welcome" font_color = [180, 220, 180] ``` ## `one_at_a_time` — sequential scroll [Section titled “one\_at\_a\_time — sequential scroll”](#one_at_a_time--sequential-scroll) Each widget scrolls all the way across the panel and fully off the left edge before the next widget enters from the right. Widgets never appear on screen at the same time. Each message gets its own clean moment without a held pause. `one_at_a_time` suits medium-length messages that should read as distinct items — enrollment announcements, sale callouts, or any set of messages where you want each one to complete before the next begins. Unlike `ticker`, there is never any overlap between consecutive messages; unlike `slideshow`, there is no hold and no transition animation. The effect is a clean sequence of individual scrolls.  \`one\_at\_a\_time\` — three messages and a countdown each scroll fully off before the next enters; a clean gap between widgets ```toml [[playlist.section]] mode = "one_at_a_time" loop_count = 1 scroll_step_ms = 35 [[playlist.section.widget]] type = "message" text = "Now Enrolling" font_color = [225, 48, 108] [[playlist.section.widget]] type = "countdown" text = "Summer Camps" countdown_date = 2026-06-20 font_color = [120, 220, 255] [[playlist.section.widget]] type = "message" text = "Spring Classes Open" font_color = [255, 220, 0] [[playlist.section.widget]] type = "message" text = "Drop-ins welcome" font_color = [180, 220, 180] ``` ## `slideshow` — held with transitions [Section titled “slideshow — held with transitions”](#slideshow--held-with-transitions) Each widget is displayed for `hold_time` seconds (default `3.0`). If the widget’s text overflows the panel width, it scrolls once before stopping; otherwise it holds stationary. When the hold expires a transition animation runs, and the next widget appears. `slideshow` is the natural fit for a storefront window display or information board where each item needs to be readable on its own. The transition used between widgets in the section is configured via the `transition` field. If you omit `transition`, the global `[transitions] default` applies. When a section explicitly sets `transition = "..."`, that transition is also used when the section appears — overriding the global `between_sections` setting for that section’s entry.  \`slideshow\` — three messages and a phoenix image each hold for \`hold\_time\`, then a transition (\`push\_left\` here) reveals the next ```toml [transitions] default = "push_left" duration = 0.5 [[playlist.section]] mode = "slideshow" loop_count = 1 hold_time = 2.5 [[playlist.section.widget]] type = "message" text = "Open daily" font_color = [120, 220, 255] [[playlist.section.widget]] type = "message" text = "10am - 8pm" font_color = [225, 48, 108] [[playlist.section.widget]] type = "image" path = "config/assets/phoenix_transparent.png" fit = "pillarbox" image_align = "center" hold_time = 3.0 [[playlist.section.widget]] type = "message" text = "All ages" font_color = [255, 220, 0] ``` For `gif` widgets in `slideshow` mode, `play_count = 0` plays the gif through the section’s `hold_time` — the engine computes how many complete loops fit and plays at least one. See [gif widget — `play_count = 0`](/widgets/gif/#playing-through-hold_time-play_count--0). ## `loop_count` and section progression [Section titled “loop\_count and section progression”](#loop_count-and-section-progression) `loop_count` controls how many times the engine runs through all of the section’s widgets before moving on to the next section. A `loop_count` of `1` (the default) means the engine plays each widget once and then moves on. A value of `2` plays the whole set twice, and so on. Section-to-section transitions fire once when the engine leaves the section — they are not repeated on each loop. The global `[transitions] between_sections` setting controls what transition plays at section boundaries. A section can override this by setting `transition` explicitly — when it does, that transition is used both for inter-widget swaps within the section AND for the entry transition when the section first appears. ## Tuning scroll cadence with `scroll_step_ms` [Section titled “Tuning scroll cadence with scroll\_step\_ms”](#tuning-scroll-cadence-with-scroll_step_ms) Both `ticker` and `one_at_a_time` advance one logical pixel per engine tick by default — 50 ms per pixel, or about 20 logical pixels per second. Set `scroll_step_ms` on a section to override that cadence. Lower values (30-40 ms) speed the marquee up for dense content like RSS headlines or rapid stock tickers; higher values (70-100 ms) slow it down for messages that need a deliberate read. The same value also drives the post-hold scroll on `slideshow` mode for widgets whose content overflows the panel width. ```toml [[playlist.section]] mode = "one_at_a_time" loop_count = 1 scroll_step_ms = 30 # snappier than the 50 ms default [[playlist.section.widget]] type = "rss.feed" feed_url = "https://example.com/feed" ``` The section-level `scroll_step_ms` is distinct from the per-widget `scroll_speed_ms` on `gif` and `image` widgets — the section knob controls how fast the engine’s cursor advances across widgets in scroll modes; the widget knob controls how fast text scrolls inside a single widget’s text overlay. Different layers, different code paths; both can be set in the same config. ## Section backgrounds with `bg_color` [Section titled “Section backgrounds with bg\_color”](#section-backgrounds-with-bg_color) Setting `bg_color` on a section paints a solid RGB color across the panel before any widget draws. Widgets in the section inherit that background unless they set their own `bg_color` — one line at the section level instead of repeating it on every widget. ```toml [[playlist.section]] mode = "slideshow" hold_time = 4.0 bg_color = [255, 244, 214] # brand cream — warm neutral behind all widgets in this section [[playlist.section.widget]] type = "message" text = "Now Enrolling" [[playlist.section.widget]] type = "message" text = "Spring Classes" ``` When a section has a `bg_color` and the next section has a different one, transitions paint the right color throughout — the engine forwards `outgoing_bg_color` and `incoming_bg_color` to the active transition so the panel never flashes through black at the cut-over. Widget-level `bg_color` works the same way for inter-widget transitions within a section. A widget setting its own `bg_color` overrides the section default for that widget only. Use a section-level color as the base and only set widget-level `bg_color` when one widget needs a different tint. ## `default` vs `transition` [Section titled “default vs transition”](#default-vs-transition) The `[transitions]` block uses `default = "wipe_left"` for the playlist-wide default. Inside a `[[playlist.section]]` the equivalent is `transition = "wipe_left"` — writing `default = `inside a section block has no effect (the key is silently dropped). ## Which mode to use [Section titled “Which mode to use”](#which-mode-to-use) | Mode | What it looks like | | --------------- | --------------------------------------------------------------------------------------------------------------- | | `ticker` | All widgets joined in one continuous stream, looping endlessly — the classic news ticker | | `one_at_a_time` | Each widget scrolls fully across and off before the next enters — clean sequential scrolls, no overlap | | `slideshow` | Each widget holds on screen for `hold_time`, then a transition reveals the next — storefront / info-board style | See also * [concepts/display](/concepts/display/) * [concepts/value-tokens](/concepts/value-tokens/) * [transitions/index](/transitions/index/) * [widgets/index](/widgets/index/) # Value tokens > Embed live clock, date, weather, and other values in any widget's text using the :id: token syntax. Built-in and plugin-contributed sources supported. Any text-bearing widget can embed a **value token** — a `:name:` placeholder that resolves to a live string at display time. Declare the source once at the top of your config; reference it anywhere in a `text =` field (or `top_text`, `bottom_text`, overlay text on image/gif widgets). ```plaintext text = "Open 9–5 :clock.now:" text = "Happy :date.today:!" text = "Breathe. Move. Rise." # no token — plain string ``` Tokens share the same `:slug:` syntax as [inline emoji](/assets/emoji/). An unknown `:slug:` renders as literal text (including the colons), so adding a `[[source]]` block is the only way to activate a token — a typo stays visible rather than silently disappearing. ## Declaring a source with `[[source]]` [Section titled “Declaring a source with \[\[source\]\]”](#declaring-a-source-with-source) Each value token needs a matching `[[source]]` block at the top level of your `config.toml` (alongside `[display]`, `[transitions]`, etc. — not nested inside `[[playlist.section]]`). Clock token — 12-hour time with AM/PM ```toml [[source]] id = "clock.now" # the token name → use :clock.now: in text fields type = "clock" format = "%-I:%M %p" # strftime — "9:01 AM", "12:30 PM" timezone = "America/New_York" # IANA name; omit to follow the Pi's system clock ``` Date token — day of week ```toml [[source]] id = "date.today" type = "date" format = "%A" # "Monday", "Tuesday", … timezone = "America/New_York" ``` Static token — fixed text that never changes ```toml [[source]] id = "brand.tagline" type = "static" value = "Breathe. Move. Rise." ``` The `id` becomes the token name. It must match the pattern `[a-z_][a-z0-9_.]*` — lowercase letters, digits, underscores, and dots — to be usable as a `:token:`. An id that doesn’t match the pattern is accepted, but the `:...:` placeholder won’t be recognized at display time and renders as literal text instead. A dot in the name (like `clock.now`) is fine; it is just part of the name and has no special meaning. ## Using tokens in widgets [Section titled “Using tokens in widgets”](#using-tokens-in-widgets) Reference a declared source by its `id`, wrapped in colons, in any `text =` field on a `message`, `two_row`, `gif`, or `image` widget: Clock + date in a message widget ```toml [[source]] id = "clock.now" type = "clock" format = "%-I:%M %p" timezone = "America/New_York" [[source]] id = "date.today" type = "date" format = "%A" timezone = "America/New_York" [[playlist.section]] mode = "slideshow" hold_time = 10 [[playlist.section.widget]] type = "message" text = ":date.today: :clock.now:" font_color = [255, 183, 3] ``` Tokens compose with everything else on the widget — `font_color = "rainbow"`, `animation = "typewriter"`, `border = "rainbow"`, inline emoji. The token is substituted before layout, so the rest of the pipeline sees a plain string. ## The three source types [Section titled “The three source types”](#the-three-source-types) ### `clock` — live wall-clock time [Section titled “clock — live wall-clock time”](#clock--live-wall-clock-time) `format` is a [Python `strftime` format string](https://docs.python.org/3/library/datetime.html#strftime-and-strptime-format-codes). Common patterns: | Format | Output | | ------------- | ----------------------------- | | `"%-I:%M %p"` | `9:01 AM` | | `"%I:%M %p"` | `09:01 AM` (zero-padded hour) | | `"%H:%M"` | `21:01` (24-hour) | | `"%I:%M"` | `09:01` (12-hour, no AM/PM) | `timezone` is an IANA timezone name (e.g. `"America/New_York"`, `"Europe/London"`, `"Asia/Tokyo"`). Omit it and the token follows the Pi’s system clock — a fresh Pi is often UTC, so set the timezone explicitly. ### `date` — calendar date [Section titled “date — calendar date”](#date--calendar-date) Same as `clock` but formatted for dates. Common patterns: | Format | Output | | ------------- | ------------ | | `"%A"` | `Monday` | | `"%B %-d"` | `June 30` | | `"%m/%d"` | `06/30` | | `"%a %-d %b"` | `Mon 30 Jun` | `timezone` works the same as for `clock`. ### `static` — fixed text [Section titled “static — fixed text”](#static--fixed-text) `value` is a plain string that never changes. It is the simplest source and a good way to keep a reusable phrase in one place and reference it from multiple widgets. ```toml [[source]] id = "studio.name" type = "static" value = "Firebird Yoga" # then in any widget: # text = ":studio.name: · Breathe. Move. Rise." ``` ## How live updates work [Section titled “How live updates work”](#how-live-updates-work) The display engine refreshes all synchronous sources (clock, date, static) once per second. A source’s value is compared to the previous tick — if it changed, the internal version counter increments and any widget that references that source rebuilds its display string and recalculates its layout. Widgets with no tokens are untouched. **Constant-width formats** (`%H:%M`, `%I:%M %p`) produce a value the same pixel width every tick, so the panel never reflowing mid-hold. **Variable-width formats** (`%A` — “Monday” vs “Saturday”) reflow at most once per value change (per minute or per day), cleanly at the widget’s next hold tick. During scrolling, transitions, and typewriter reveals, resolution is frozen — if a value changes mid-scroll, the new value takes effect at the next hold rather than interrupting the in-flight animation. ## Resolution order: emoji wins, then source, then literal [Section titled “Resolution order: emoji wins, then source, then literal”](#resolution-order-emoji-wins-then-source-then-literal) If a `:slug:` matches an emoji in the [emoji registry](/assets/emoji/), it renders as a pixel-art sprite — the emoji takes priority over any source with the same name. The validator (`make validate`) rejects a `[[source]]` `id` equal to an existing emoji slug, so this collision cannot occur in a valid config. An `:unknown:` slug that matches neither an emoji nor a declared source renders as literal text (`:unknown:`). This is intentional — a missing or misspelled source name stays visible so you can spot it at a glance. ## Live (polled) sources [Section titled “Live (polled) sources”](#live-polled-sources) The `clock`, `date`, and `static` sources compute their value locally and instantly — they need no network and never fail. Some source types work differently: they fetch data in the background on a repeating `interval` (in seconds) and push the result into the token when the fetch completes. These **polled sources** are contributed by plugins. A plugin registers a source type via `api.source` by subclassing `PolledDataSource` and implementing an `async def update()` method that calls `self._set_value(...)` with a new string. The engine spawns a supervised background task that calls `update()` every `interval` seconds for as long as the display is running. A polled `[[source]]` block looks the same as a built-in one — the plugin type name and any type-specific fields sit alongside `id` and `interval`: ```toml [[source]] id = "my.token" type = "some.plugin.type" # contributed by a plugin interval = 300 # fetch every 5 minutes # ...type-specific fields... ``` **Before the first fetch completes**, the token shows a short placeholder (e.g. `…`) so your layout is never blank. Once the first value arrives, it replaces the placeholder and the token updates live on the same reflow path as clock and date — any widget that references it rebuilds its display string and recalculates layout automatically. If a fetch fails, the previous value is kept and the task retries on the next `interval`. A crashed fetch task is supervised and restarted, so a transient network error doesn’t freeze the token permanently. If a polled source like `:weather.nyc:` stops updating, the [web UI’s Monitors panel](/concepts/web-status-ui/#status-tab--monitors) shows whether it is erroring (with the error message and a retry countdown) or stale (fetch wedged, no response). ### Example: live weather [Section titled “Example: live weather”](#example-live-weather) The [weather plugin](/plugins/available/#weather) contributes a `weather.current` source. Declare it once: ```toml [[source]] id = "weather.nyc" type = "weather.current" # from the weather plugin location = "New York, US" # name / ZIP / "lat,lon" interval = 1800 # refresh every 30 minutes format = "{temp_f}°F {condition}" # optional; this is the default ``` Then reference it in any widget’s text: ```toml [[playlist.section.widget]] type = "message" text = "NYC: :weather.nyc:" # → "NYC: 72°F Clear", updating live ``` The `format` string interpolates the current-conditions fields `temp_f`, `temp_c`, `condition`, `feelslike_f`, `feelslike_c`, `humidity`, `wind_mph`, and `emoji`. The `emoji` field expands to a condition icon that renders as a sprite, so `format = "{temp_f}° {emoji}"` gives `72° ☀`. The API key comes from `WEATHERAPI_KEY` in your `.env` (never in config); see the [weather plugin](/plugins/available/#weather) for setup. ## Tips [Section titled “Tips”](#tips) ### Zero-pad the hour to avoid reflowing [Section titled “Zero-pad the hour to avoid reflowing”](#zero-pad-the-hour-to-avoid-reflowing) `%H:%M` (24-hour, `09:01`) and `%I:%M` (12-hour with leading zero, `09:01`) keep the time string a fixed pixel width. `%-I:%M` (no leading zero, `9:01`) gives a narrower string for single-digit hours — fine in `slideshow` hold, but the message will reflow at 10:00 when the hour gains a digit. ### Multiple `[[source]]` blocks are fine [Section titled “Multiple \[\[source\]\] blocks are fine”](#multiple-source-blocks-are-fine) Each block declares one source. Define as many as you need; they are all global across every section. ### Tokens work in `ticker` and `one_at_a_time` modes too [Section titled “Tokens work in ticker and one\_at\_a\_time modes too”](#tokens-work-in-ticker-and-one_at_a_time-modes-too) `ticker` and `one_at_a_time` sections scroll widgets continuously. Tokens resolve normally — the value used is whatever the source holds at the moment the widget is drawn. A per-minute date or AM/PM flip takes effect the next time the widget passes through the visible area. See also * [assets/emoji](/assets/emoji/) * [concepts/sections-and-modes](/concepts/sections-and-modes/) * [widgets/message](/widgets/message/) # Web status UI > A browser dashboard for your sign — status, live config viewer/validator, asset inventory, and a token-gated config editor and plugin Store. The web status UI is a browser dashboard you open while the sign is running. By default it’s read-only, with token-gated editing (the config editor and the plugin Store). It shows you what the sign is displaying right now, lets you inspect the live config with secrets redacted, validate a config against the real sign before deploying it, and browse the fonts, images, and emoji available in your config directory. **What you’ll need:** a running led-ticker sign set up from [Getting started](/getting-started/). No additional accounts, API keys, or hardware changes required. ## What’s on the dashboard [Section titled “What’s on the dashboard”](#whats-on-the-dashboard) Five tabs, one URL (`http://:8080`): | Tab | What it shows | | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **Status** | The widget currently playing, how long it has been on screen, section health, loaded plugins, and a stale/missing indicator when the display process is down. | | **Config** | The full `config.toml` the display process loaded, with every value that looks like a secret replaced by `•••`. Safe to screenshot and share when troubleshooting. | | **Validate** | Validate a file from the config directory against the real sign, or paste a candidate config into the text area and click **Validate**. | | **Inventory** | Fonts, image/gif assets, and emoji slugs found in the config directory. | | **Store** | Browse and install catalog plugins. Browsing is open; installing or removing requires a token. |  ### Validate tab [Section titled “Validate tab”](#validate-tab) The Validate tab offers two paths:  * **Validate file** — a dropdown lists every `.toml` in the config directory. Select one and click **Validate file** to run `led-ticker validate` server-side on the real file. Validation happens on the Pi, so results are exact and secrets never leave the device. * **Load redacted copy** — fills the text area with the selected file’s content with secrets replaced by `•••`, then shows a caveat that `•••` values may validate differently than the real file. Use this when you want to inspect or hand-edit the config before re-validating; use **Validate file** when you just need a pass/fail answer. The text area is still there for pasting a config you haven’t saved to a file yet. ### Inventory tab [Section titled “Inventory tab”](#inventory-tab) The Inventory tab shows what the sidecar can see in the config directory (capped at 500 assets):  * **Fonts** — user fonts from `config/fonts/` (which take precedence over bundled ones) and the bundled BDF and hires fonts included with led-ticker. * **Assets** — image and gif files (`config/`, recursively) with their file size. * **Emoji** — core slugs and hires-only slugs baked into the installed package. Plugin emoji (such as `:baseball.ball:`) appear only while the display process is running — the sidecar itself never loads plugins, so the names come from `status.json` published by the display process. ### Store tab [Section titled “Store tab”](#store-tab) The Store tab lists every plugin in the [catalog](/plugins/available/) and shows each one’s current state — whether it is active, queued for the next restart, or available to install. Click **Install** to add a plugin or **Remove** to drop one.  **A token is required to install or remove.** Browsing the Store is open, but any write action returns 401 without a valid token. Set `LED_TICKER_WEB_TOKEN` in your `.env` (see [Auth](#auth) below). **Changes take effect on the next restart** — the same as editing `config/requirements-plugins.txt` by hand. The Store writes the manifest for you and shows a “pending restart” banner once there is a queued change. If `allow_restart = true` is set in your `[web]` block, the banner also shows a **Restart to apply** button — click it and the display process exits cleanly, then Docker’s `restart: unless-stopped` brings it back with the new plugins loaded. If `allow_restart` is not set, the banner shows a copyable command you can run yourself: ```bash docker compose restart ``` **Removal is blocked while your config still uses the plugin.** If `config.toml` references any of the plugin’s widget or transition types, the Store shows which sections they appear in and links to the Config editor so you can remove them first. Once the config is clean, click **Remove** again and restart. **Catalog plugins only.** The Store lists verified catalog plugins. Community plugins or plugins you are developing locally go in `config/requirements-plugins.txt` directly (see [Installing a plugin](/plugins/#installing-a-plugin)). ### Status tab — plugin detail [Section titled “Status tab — plugin detail”](#status-tab--plugin-detail) The Status tab’s **Plugins** card lists each loaded plugin’s registered widget, transition, and emoji names (e.g. `widgets: baseball.scores, baseball.standings · emojis: baseball.ball`). Display processes that predate v1.1 publish counts instead of names; the UI falls back to showing the raw count object in that case. ### Status tab — Overlays [Section titled “Status tab — Overlays”](#status-tab--overlays) The Status tab’s **Overlays** card shows what is compositing on top of the panel on every frame. **Busy light state** — when `[busy_light]` is configured, the card shows: * whether the dot is currently on (`● busy`) or off (`○ free`) * the source (`file` or `http`) * how many seconds remain on the active TTL deadline (`clears in Ns`), when one is armed When no `[busy_light]` block is present in the config, the card shows “busy light not configured”. **Overlay roster** — a table listing every overlay registered with the engine at startup, with its name and whether it comes from core (`busy_light`) or a plugin (the plugin’s namespace, e.g. `acme.clock`). The roster is static: it reflects what was loaded when the display process started and does not change while it is running. The Overlays card is **read-only**. The busy light’s on/off state is controlled through the `[busy_light]` TOML config and, for `source = "http"`, through the `/busy` HTTP route the display process exposes — not through this dashboard. See [Busy light](/concepts/busy-light/) for the full control surface. Note The Overlays card requires `[web]` to be configured. Display processes started without a `[web]` block do not publish overlay state, and the card will not appear. ### Status tab — Monitors [Section titled “Status tab — Monitors”](#status-tab--monitors) The Status tab’s **Monitors** panel tracks the health of every live-data source and data widget running on the sign — automatically, with nothing to configure beyond adding the source or plugin in the first place. **What it covers.** Two kinds of live-data workers show up here: * **Polled `[[source]]` value-tokens** — sources like `:weather.nyc:` or `:crypto.btc:` that fetch their value from an API on a repeating interval (see [Value tokens](/concepts/value-tokens/)). * **Data widgets** — plugin widgets that pull data in the background (weather, RSS, crypto, calendar, sports, pool, and others). **The roll-up badge.** Next to the “Health” heading in the Monitors panel, a small colored badge summarizes the worst state across all monitors at a glance — red for error, amber for stale, green for all-ok. **Per-monitor states.** Each row shows the source or widget name, its **type** (the source or widget class, like `weather.current` or `rss.feed`), and its current **value** (the last resolved data, like `72°F Sunny` or `5 items`). The type appears as muted text below the name so you can tell what a monitor is; the value confirms it’s returning real data. Each row also shows one of four states: | State | Meaning | | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **ok** | Updated within its expected interval — data is fresh. | | **error** | The last fetch failed. The row shows the error message, a consecutive-failure count, and a “retrying in …” countdown to the next attempt. | | **stale** | No successful update for well past the expected interval — the fetch task may be wedged. Stale differs from error: there is no error message because the fetch never returned, not even with a failure. | | **waiting** | The source has not completed its first fetch yet. This appears briefly at startup. | **“Sign not reporting.”** If the display process stops publishing its status snapshot, all monitor rows grey out and a warning appears at the top of the panel: “sign not reporting — monitor state may be stale.” This prevents a frozen snapshot from being mistaken for a healthy sign. Once the display process resumes, the warning clears automatically. ### Status tab — snapshot fields [Section titled “Status tab — snapshot fields”](#status-tab--snapshot-fields) The display process publishes a `status.json` file (schema version 9) containing the state of the running display. The web UI renders this snapshot; advanced users and integrations can also read it directly. Notable fields: **`failed_plugins`** — plugins that failed to load at startup (load-time errors). Each entry lists the plugin namespace and the exception message. A failed plugin’s widgets, transitions, and emoji are unavailable. Restart the display process with the plugin fixed or removed to recover. **`disabled_widgets`** — widgets the render circuit breaker has disabled during this run. If a widget’s `draw()`/`play()` raises an exception at render time, it is caught, dropped from rotation, and listed here as `{ "widget": "", "error": "" }`. The same circuit breaker also guards transition compositing, so a widget that raises during a transition is caught and dropped — the transition completes with the bad widget blank. The panel keeps running and moves on to the next widget. This is the render-time counterpart of `failed_plugins` (load-time). Restart to retry a disabled widget. **`last_reload`** — the outcome of the most recent config hot-reload attempt: `{ ok, at, error, restart_required }`. `ok` is `true` when the reload succeeded and `false` when it was rejected. `at` is an ISO-8601 timestamp. On failure, `error` contains the validation error verbatim (the same message `led-ticker validate` would print) so you can act on it without tailing logs. `restart_required` is a list of section names — `display`, `busy_light`, `plugins`, `web` — whose changes were detected but cannot take effect until you restart the display process. The card is hidden until the first reload attempt after startup. See [Config hot-reload](/concepts/hot-reload/) for full details. **`config_validation`** — the result of validating the config once at startup: `{ at, errors, warnings }`, where `at` is an ISO-8601 timestamp and `errors`/`warnings` are lists of `{ rule, location, message, fix }` (the same checks `led-ticker validate` runs). The sign always boots — an invalid widget is skipped and an invalid transition falls back to a cut — so this is the up-front diagnosis, not a boot failure. The **Config validation** card on the Status tab surfaces these issues and stays hidden when the config is clean. Reloads report through `last_reload`, not this field. ### Status tab — live preview [Section titled “Status tab — live preview”](#status-tab--live-preview) The Status tab includes a **live preview** panel that shows the actual content on the sign — the same pixels the panel is displaying, including the busy-light dot if one is configured. It updates at roughly 5 fps. **Zero cost when nobody is watching.** The preview mirror is demand-driven: it wakes up when the page loads and polls for a new frame, and goes to sleep automatically around 10 seconds after the browser tab stops polling (navigating away, closing the tab, or the page going to the background). While asleep the display process does no extra work and writes nothing to disk for the preview. When you come back, there is a brief “waking the preview…” message while the mirror reconnects — typically a couple of seconds before the first frame appears. **Scale-1 (smallsign) note.** On a 160×16 smallsign the preview pixel grid is very small. The browser scales it up to a readable size, but individual pixels are large blocks. Single-pixel-tall BDF text at the panel’s native resolution can be hard to read in the preview — this is expected and not a rendering error. Note The live preview requires a `[web]` block in the display process’s `config.toml`. Display processes started without it do not publish frames, and the preview panel will show “waking the preview…” indefinitely. **If the preview is stuck on “waking the preview…”:** * Confirm the display process is running with a `[web]` block in `config.toml` (see [Enabling it](#enabling-it) below). A process started before `[web]` was added needs a restart. * Check that the `ticker-status` named volume is shared between the display process and the sidecar — the preview frame file lands in `/run/led-ticker/` inside both containers. * If the sidecar and display process are on different versions, the display process may predate the live preview feature. Rebuild or reinstall both to the same version. ## Architecture [Section titled “Architecture”](#architecture) The dashboard is a separate **sidecar process** (`led-ticker webui`). It is unprivileged — no GPIO access, no API keys — and reads only `config.toml` and a `status.json` file the display process writes. Neither side needs the other to be up: if the display process crashes, the sidecar keeps serving (the Status tab shows a stale or missing indicator); if the sidecar is not running, the sign keeps displaying. Start order is irrelevant. The `status.json` path defaults to `/run/led-ticker/status.json` and is configurable via `status_path` in the `[web]` block. ## Enabling it [Section titled “Enabling it”](#enabling-it) Add a `[web]` block to your `config.toml`. An empty block is valid and uses the defaults: Minimal — all defaults ```toml [web] # http_host = "0.0.0.0" # listen on all LAN interfaces (default) # http_port = 8080 # (default) # token = "" # open — see Auth below ``` Presence of the block enables status publishing in the display process. Absence (no `[web]` block at all) disables the feature entirely — existing configs without the block are unaffected. ### Docker [Section titled “Docker”](#docker) The `compose.yaml` defines the `webui` service behind the `webui` compose profile, so a plain `docker compose up -d` changes nothing. Enabling the dashboard takes two steps: add the `[web]` block to `config.toml`, then start with the profile on. Both are needed — the profile starts the sidecar, and the block tells the display process to publish (and the sidecar exits without it). ```yaml # The webui service as it appears in compose.yaml (note the profile): webui: profiles: ["webui"] image: led-ticker build: . container_name: led-ticker-webui restart: unless-stopped command: ["led-ticker", "webui", "--config", "/code/config/config.toml"] network_mode: host volumes: - ./config:/code/config:ro - ticker-status:/run/led-ticker ``` The `ticker-status` named volume is the shared channel: the display process writes `status.json` there; the sidecar reads it. Both services mount the same volume so they work correctly even when one is restarted independently. Then bring it up: ```bash COMPOSE_PROFILES=webui docker compose up -d # or equivalently: docker compose --profile webui up -d # Tip: put COMPOSE_PROFILES=webui in the .env next to compose.yaml to make it sticky. ``` Open `http://.local:8080` in a browser. ## Auth [Section titled “Auth”](#auth) By default the dashboard is open — appropriate for a trusted home LAN. To add a shared token, set `LED_TICKER_WEB_TOKEN` in your `.env`: .env ```bash LED_TICKER_WEB_TOKEN=change-me ``` The display process and sidecar both read this environment variable at startup. The `token` field in `[web]` is a fallback for setups that cannot use `.env` — it works, but logs a warning that secrets belong in the environment, not the config file. With a token set, every request must include it, either as a header or a query parameter: ```bash # Header form (preferred — token does not appear in server logs) curl -H "X-Web-Token: change-me" http://pi:8080/api/status # Query-param form (convenient for browser access) http://pi:8080/?token=change-me ``` A missing or wrong token returns `401`. The query-param form works in a browser address bar, so bookmarking `http://pi:8080/?token=…` gives you one-click access. **Secrets are always redacted** from the Config tab regardless of whether auth is enabled or what token was used. The redaction runs in the sidecar, not in the browser. For anything beyond your home LAN — exposing the dashboard over the internet — put a reverse proxy (nginx, Caddy) in front and let the proxy handle TLS and stronger auth. The sidecar itself is a LAN-appliance; it has no TLS support. ## Editing the config [Section titled “Editing the config”](#editing-the-config) The **Config tab** doubles as an editor. Open it, make your changes, and click **Save**. **A token is required to save.** Set `LED_TICKER_WEB_TOKEN` in your `.env` (see [Auth](#auth) above). With no token configured, reads stay open but the editor is read-only — Save returns 403. Once a token is set, it gates every request (reads and writes alike). **What Save does, in order:** 1. Validates the submitted TOML — invalid TOML or a config that fails `led-ticker validate` is rejected and nothing is written. 2. Conflict-checks against the file on disk. If someone else saved the file since you loaded it, Save returns 409 and you can reload before retrying. 3. Backs up the current file to `config.toml.bak` in the same directory. 4. Writes the new content atomically (write to a temp file, then rename into place). The Config tab reports **“applied live”** when the running display picked up the change via hot-reload, or **“restart required for …”** listing the sections (e.g. `display`, `plugins`) whose changes need a process restart to take effect. Note The Validate tab is always available regardless of whether a token is set. Use it to check a candidate config before saving. **Deploy note.** In `compose.yaml` the webui service mounts the config directory `:rw` (the display service still mounts it `:ro`) — this is what lets the editor write `config.toml` from inside the container. ## Restarting the display process [Section titled “Restarting the display process”](#restarting-the-display-process) Some config changes — adding a plugin, changing `[display]` settings, toggling `[busy_light]` — cannot be applied by hot-reload alone. They require a full restart of the display process. The web UI can trigger that restart for you. When `allow_restart = true` is set in your `[web]` block, a **Restart to apply** button appears in the **Config tab’s** “restart required” notice (after a save that needs a restart) and in the **Store tab’s** pending-restart banner (when a plugin install or remove is queued). Clicking it: 1. Confirms the action (a brief in-button countdown lets you cancel). 2. Posts to `/api/restart` — a token must be configured and supplied (the same token that gates config saves); with no token configured the endpoint returns 403. 3. The display process detects the signal on its next loop pass and exits cleanly (`sys.exit(0)`). 4. Docker’s `restart: unless-stopped` brings the display back automatically. **The panel goes dark for roughly 5–10 seconds** while the process exits and restarts. This is expected — it is not a reboot of the Pi, and the sign resumes where it left off once the display process is back. **`allow_restart` is off by default.** Enable it by adding the field to your `[web]` block: Enabling the restart button ```toml [web] allow_restart = true # enables the Restart to apply button in the web UI ``` The `config/config.example.toml` shipped with the project sets `allow_restart = true` in its commented-out `[web]` block — uncomment the whole block to get the button alongside the other defaults. Caution `restart: unless-stopped` is already set in `compose.yaml`, so Docker deployments restart automatically. If you are running led-ticker from a source checkout without a process supervisor, clicking the button will leave the sign dark until you restart it manually — set up a supervisor or leave `allow_restart` at its default `false`. ## What it does not do [Section titled “What it does not do”](#what-it-does-not-do) * No Pi reboot. * No brightness control. ## Which build is deployed? [Section titled “Which build is deployed?”](#which-build-is-deployed) The dashboard header shows the deployed build, as `branch@sha`. Use it to confirm both containers are running the code you expect. It resolves to the first of: the ref stamped into the Docker image at build time (`make update` / `make build` compute it and pass it in), or — for a non-Docker install running from a source checkout (local dev) — the ref read from Git at runtime. * **`build unknown`** — neither applied: the image wasn’t built through `make update` (a bare `docker compose build` doesn’t stamp the commit), and it isn’t running from a Git checkout. Deploy with **`make update`** to stamp it. The sign still runs correctly; `unknown` is a label, not an error. * **`⚠ webui build …`** — the webui sidecar is on a different build than the display process. This can happen when only one service is restarted without rebuilding. Run `make update` to rebuild and recreate the running services (the webui sidecar is included when its profile is enabled). ## Troubleshooting [Section titled “Troubleshooting”](#troubleshooting) **The page doesn’t load at all (connection refused)** — The sidecar isn’t running. On Docker, the `webui` service only starts when the `webui` compose profile is enabled — check `docker compose ps`; if the container is absent, start with `COMPOSE_PROFILES=webui docker compose up -d`. If the container exists but is restarting, check `docker compose logs webui` — a missing `[web]` block in `config.toml` makes the subcommand exit with a message naming the fix. **“Status: missing” on the Status tab** — The display process has not written `status.json` yet. Confirm the display process is running (`docker compose ps`) and that both processes share the same `status_path` (default `/run/led-ticker/status.json`). The directory `/run/led-ticker/` is created by the display process on startup — if the display process has never started, the directory does not exist yet. **“engine stalled?” on the live indicator** — The display process is running (status keeps publishing) but the render loop has stopped swapping frames. This is rare; check `docker compose logs led-ticker` for a stuck widget or transition, and restart the display service. **“Status: stale” on the Status tab** — The display process wrote a status file but has not updated it recently. This usually means the process crashed or was stopped. Check `docker compose logs led-ticker`. **Browser shows nothing / 401** — A token is set in `[web]`. Add `?token=` to the URL, or configure your browser extension / bookmark with the `X-Web-Token` header. **Sidecar binds a port already in use** — The `[web]` sidecar defaults to `8080` and the `[busy_light]` HTTP source defaults to `8081`, so they don’t collide out of the box. If you override either to put both on the same port, one will fail to bind — give them distinct ports. See also * [concepts/hot-reload](/concepts/hot-reload/) * [reference/config-options](/reference/config-options/) * [concepts/busy-light](/concepts/busy-light/) * [concepts/value-tokens](/concepts/value-tokens/) * [reference/cli](/reference/cli/) # Getting started > Install led-ticker on Docker, preview configs on your laptop with no hardware, and deploy to a Raspberry Pi — start in under 5 minutes. led-ticker drives RGB LED matrix panels from a Raspberry Pi via a TOML config — RSS, weather, custom messages, animated transitions, and more. One toolchain (Docker) covers everything: try it on your laptop with no hardware, then deploy the same image to a Pi when your panels arrive. Not sure led-ticker is the right fit? → [Why led-ticker?](/why-led-ticker/) | You want… | Go to | | -------------------------------------------------------------------------------------- | ----------------------------------- | | Try it on your laptop, no hardware (2 min) | Quickstart A below | | Deploy to a Pi with panels (\~20 min) | Quickstart B below | | Build a complete sign config from scratch, ready to deploy (no hardware needed, \~1 h) | the [Tutorial](/tutorial/01-setup/) | **What you’ll need:** * A laptop (macOS, Linux, or Windows) for the laptop quickstart * A Raspberry Pi + [HUB75 panels + Adafruit HAT/Bonnet](/hardware/building-your-own/) for the Pi deploy (HUB75 is the standard connector on hobbyist RGB LED matrix panels — the Amazon/AliExpress “RGB LED matrix” panels are HUB75.) * [Docker](https://docs.docker.com/get-docker/) — the single tool that covers both ## Step 1 — Install Docker [Section titled “Step 1 — Install Docker”](#step-1--install-docker) **Linux / Raspberry Pi:** ```bash curl -fsSL https://get.docker.com | sh sudo usermod -aG docker $USER # Log out and back in (or: newgrp docker) for the group change to take effect. ``` **macOS / Windows:** install [Docker Desktop](https://docs.docker.com/get-docker/). `docker compose` v2 ships with modern Docker — the old standalone `docker-compose` command is not required. ## Quickstart A — Try it on your laptop (no hardware) [Section titled “Quickstart A — Try it on your laptop (no hardware)”](#quickstart-a--try-it-on-your-laptop-no-hardware) **\~2 minutes, Docker only.** You’ll see a browser tab showing your sign rendering live in a simulated panel — no hardware needed. Open a terminal (Terminal on macOS; WSL or a package manager like Chocolatey/Scoop provides `make` on Windows), then: ```bash # Check Docker is installed first: docker --version # Clone (downloads the repo) + start: git clone https://github.com/JamesAwesome/led-ticker.git cd led-ticker make try # make is a standard task runner, pre-installed on macOS/Linux ``` `make try` builds the image and starts a headless display engine plus the web UI — no panel, no Pi. Open **** and click the **live preview** tab to see the sign rendering in your browser. Already have a `config/config.toml`? `make try` previews it instead of the bundled example. Both of those are **plugins** baked into the try image: the scrolling [Hacker News](https://news.ycombinator.com/) headlines come from the `rss.feed` widget, and the Nyan Cat sweep between sections is an animated transition — no API keys or `.env` needed (the headlines just need an internet connection). Browse the [plugin catalog](/plugins/available/) for weather, sports scores, crypto, calendars, and more. To try a different plugin, add its package to `config/requirements-plugins.try.txt`, reference its widget or transition in `config/config.try.example.toml`, then re-run `make try`. (On a real deploy it’s simpler still — edit `config/requirements-plugins.txt` and `docker compose restart`, no rebuild.) To stop: press `Ctrl-C`, then run: ```bash make try-down ``` ## Quickstart B — Deploy to your Pi [Section titled “Quickstart B — Deploy to your Pi”](#quickstart-b--deploy-to-your-pi) **\~20 minutes, hardware required.** Before you start Your Pi should be running Raspberry Pi OS (Bookworm, 64-bit) with SSH enabled and you logged in — flash it with Raspberry Pi Imager if you haven’t. All commands below run on the Pi. `make setup` seeds the smallsign starter config and won’t overwrite an existing `config/config.toml` — if you’re building a bigsign (or your own layout), copy your config example first (step 2) so the stack boots with the right one. **1. Clone the repo:** ```bash git clone https://github.com/JamesAwesome/led-ticker.git cd led-ticker ``` **2. Copy the right example config:** ```bash # Smallsign: Pi 4 + 5× 16×32 panels = 160×16 logical canvas cp config/config.example.toml config/config.toml # Bigsign: Pi 5 + 8× P3 32×64 panels = 256×64 logical canvas cp config/config.bigsign.example.toml config/config.toml ``` Not sure which fits? See [Choosing a sign size](/hardware/building-your-own/#choosing-a-sign-size). **3. Run setup:** ```bash make setup ``` `make setup` checks Docker, seeds `.env`, builds the image, and brings the stack up. Run it once. Most config changes (sections, widgets, schedule) take effect automatically within one playlist cycle — no restart needed. Hardware-level fields (`chain_length`, `gpio_slowdown`, `default_scale`) need `make restart`. `restart: unless-stopped` in `compose.yaml` brings the ticker back up on its own after power loss. **Check it worked:** you should see the starter messages scrolling on the panels within about a minute (the first boot builds the Docker image — typically 10–20 minutes on a Pi 4; later boots are seconds). Watch progress with `make logs`; `docker compose ps` should show the service running. Panels still dark after the image is built? Check `gpio_slowdown` and start with the [Sharp edges](/hardware/building-your-own/#sharp-edges) section on the building-your-own page. Once the web UI is enabled (step 5), its [Status tab](/concepts/web-status-ui/) gives you a richer first-boot view — a live panel preview plus per-source health at a glance. **4. Panel bring-up** — after wiring, run [`make panel-test`](/tools/panel-test/) to rule out any wiring, driver, or RGB-order problems. Before running `panel-test`, make sure `config.toml` has the correct `[display]` values for `chain_length`, `rows`, and `cols` — `panel-test` reads them. If your panels are a single horizontal chain (like the smallsign), `panel-test` is all you need. For a multi-row layout (like the bigsign or a custom grid), also run the [`panel-map`](/tools/panel-map/) workflow to derive the `pixel_mapper_config` Remap string for your panel layout. **5. Optional: web UI** — add a `[web]` block to `config.toml`: ```toml [web] # defaults are fine; see the web-status-ui docs for options ``` Then start with the `webui` profile: ```bash COMPOSE_PROFILES=webui docker compose up -d ``` Both parts are needed — the `[web]` block makes the display process publish, the profile starts the sidecar. See [Web status UI](/concepts/web-status-ui/#enabling-it) for the full options. Open `http://.local:8080` for a live dashboard, config editor, and plugin Store. ## Edit your config [Section titled “Edit your config”](#edit-your-config) A config is a list of **sections**, each containing **widgets** and a **mode** (`ticker`, `slideshow`, or `one_at_a_time`). Before editing, skim [Sections and modes](/concepts/sections-and-modes/) and the [message widget](/widgets/message/) page — the two most-used building blocks. Validate any config before deploying. On a deployed sign, the easiest way is the web UI’s **Config tab** (step 5 above) — it validates before saving. On a dev machine: ```bash make validate CONFIG=config/config.toml ``` (`make validate` needs the dev dependencies — install [uv](https://docs.astral.sh/uv/) and run `make dev` once first; `make dev` checks for uv and prints the install command if it’s missing.) Private media (GIFs, images, fonts) goes in `config/local/` (gitignored) and is referenced as `path = "local/"` in your TOML. ## Run without a Pi [Section titled “Run without a Pi”](#run-without-a-pi) For a live browser preview, use Quickstart A above. The [`render-demo`](/tools/render-demo/) tool is for iterating on configs at the command line and generating GIFs — it runs the real ticker engine against a software stub and writes each config to a GIF: ```bash make dev # install Python dev deps (requires uv) make render-demo CONFIG=config/config.example.toml OUT=preview.gif open preview.gif # macOS; xdg-open on Linux ``` ## Next steps [Section titled “Next steps”](#next-steps) * **Build a config:** [Sections and modes](/concepts/sections-and-modes/) → [Widgets](/widgets/) → [Transitions](/transitions/) * **Add plugins:** [Available plugins](/plugins/available/) — RSS, weather, sports scores, crypto, calendars, and more * **Buy / build hardware:** [Building your own](/hardware/building-your-own/) → [Smallsign](/hardware/smallsign/) or [Bigsign](/hardware/bigsign/) * **Reference:** [`[display]` and section knobs](/reference/config-options/) · [CLI](/reference/cli/) See also * [tutorial/01-setup](/tutorial/01-setup/) * [concepts/sections-and-modes](/concepts/sections-and-modes/) * [hardware/building-your-own](/hardware/building-your-own/) # Hardware: Bigsign reference build > led-ticker's reference build for tall multi-row displays — Pi 5 + eight P3 32x64 panels in a 2x4 vertical-serpentine layout for a 256x64 ticker. The **bigsign** is led-ticker’s reference build for tall multi-row displays: a Raspberry Pi 5 driving eight P3 32x64 RGB matrix panels arranged in a 2x4 vertical-serpentine layout for a 256x64 canvas. The hi-res font, hi-res emoji, and `ScaledCanvas` features were all developed against this build, and the dimensions match the bigsign-flavored examples in `config/`. Different panel counts or layouts will work — the canvas math comes from `pixel_mapper_config`, not from a hardcoded shape — but the BOM, wiring diagram, and Pi-5 tuning knobs below are what we built and tested against. Drawing logic stays at a 16-tall logical canvas; `ScaledCanvas` blows it up by a factor of four to fill the panel. ## At a glance [Section titled “At a glance”](#at-a-glance) * Raspberry Pi 5 * 8x P3 32x64 RGB matrix panels in a 2x4 vertical-serpentine layout = 256x64 logical canvas * `default_scale = 4` — every logical pixel becomes a 4x4 block on the real panel, content vertically centered * Drawing logic stays at “1x scale” with 16-tall content; the wrapper handles the expansion * Same Docker image as the smallsign; the rgbmatrix library detects the SoC at runtime ## Bill of materials [Section titled “Bill of materials”](#bill-of-materials) | Component | Quantity | Notes | | ------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------- | | Raspberry Pi 5 | 1 | 4 GB is plenty. A microSD card and a USB-C power supply for the Pi itself. | | P3 32x64 RGB matrix panel | 8 | HUB75 panels with the standard 16-pin IDC connector. Matched panels render most consistently across the 2x4 grid. | | Adafruit RGB matrix HAT | 1 | Sets `hardware_mapping = "adafruit-hat"` in the config. The bonnet works equivalently. | | 5V power supply | 1 | Sized for eight P3 panels at full white — that’s serious current. A 5V / 30A+ supply with thick busbars is the comfortable headroom pick. | | 16-pin IDC ribbon cables | 7+ | One between each pair of panels in chain order. The serpentine route bends across rows so cables need to reach across the layout. | | Power pigtails / busbar | 1+ | Whatever your panels expect. Each panel has its own 2-pin power input — a busbar across the back of the frame keeps the wiring tidy. | | Shroud / frame | 1 | A 2x4 grid of P3 panels is heavy and benefits from a rigid frame. Acrylic diffuser optional. | **Total cost (rough):** \~$400–600 USD. The 8 P3 panels at $40–60 each are the dominant line item; the Pi 5 + HAT + a 30–60 A 5 V supply with thick busbars round out the build. Frame and shroud costs vary widely depending on whether you fabricate or buy. Prices change — verify before ordering. These were checked in early 2026. The rgbmatrix library detects the SoC at runtime, so the same Docker image runs on both the smallsign (Pi 4 / BCM2711) and the bigsign (Pi 5 / RP1). No separate build, no per-Pi flag — the Pi-5-specific knobs in the next section are simply ignored on a Pi 4 and vice versa. ## The 2x4 serpentine layout [Section titled “The 2x4 serpentine layout”](#the-2x4-serpentine-layout) Eight panels are tiled into a 2x4 grid (two rows of four). The data chain enters at the **bottom-right** panel and runs vertically: each column is wired bottom-to-top, with a diagonal jumper from the top of each column to the bottom of the next column to its left. There is no horizontal hop along the bottom row — the chain always climbs a column, then crosses diagonally to the bottom of the next one. All panels are installed upright (no 180° rotations). The `pixel_mapper_config` Remap string in the config tells the rgbmatrix library how each panel’s chain index maps to its physical (x, y) on the finished canvas. ```text col 1 col 2 col 3 col 4 top [8] [6] [4] [2] ↑ ↘ ↑ ↘ ↑ ↘ ↑ bot [7] [5] [3] [1] ← data chain enters here ``` Each `[N]` is the panel’s position in the chain (1 = first, 8 = last). The `↑` arrows show each column climbing bottom-to-top; the `↘` arrows show the diagonal jumper from the top of one column to the bottom of the next column to its left. If your top-row panels are physically mounted upside down (some manufacturers ship them that way), swap each top-row `n` for `s` in the Remap string — see the comment in the config snippet below. ## Config snippet [Section titled “Config snippet”](#config-snippet) The minimal `[display]` block for the bigsign — straight from `config/config.bigsign.example.toml`: ```toml [display] rows = 32 cols = 64 chain_length = 8 parallel = 1 # Remap each panel to its physical position. Serpentine chain order, all panels upright. pixel_mapper_config = "Remap:256,64|192,32n|192,0n|128,32n|128,0n|64,32n|64,0n|0,32n|0,0n" brightness = 60 gpio_slowdown = 3 # bumped from 2 to pair with RIO mode (default); raise to 4-5 if flicker hardware_mapping = "adafruit-hat" default_scale = 4 # 4× scaling fills the 64-tall canvas # --- Pi 5 performance tuning --- pwm_bits = 8 # 11 (default) → 8 ≈ 8× faster refresh, slightly worse color show_refresh_rate = true # log measured refresh Hz to stderr ``` The 256x64 logical canvas comes from the `pixel_mapper_config` Remap header (`256,64`), not from `cols * chain_length` directly — `chain_length = 8` is just the panel count for the rgbmatrix library; the mapper rearranges those panels into the 2x4 grid. ## Pi-5 tuning [Section titled “Pi-5 tuning”](#pi-5-tuning) ### `pwm_bits = 8` [Section titled “pwm\_bits = 8”](#pwm_bits--8) PWM bit depth, default 11. Cutting to 8 buys roughly **8× faster refresh** at the cost of a small drop in color depth. On a panel this big the refresh boost is the difference between visible scan-line flicker and a clean image, and the color hit is barely noticeable for text and pixel art. Leave it at 8 unless you’re displaying photos and care about smooth gradients. ### RP1 backend (RIO vs PIO) [Section titled “RP1 backend (RIO vs PIO)”](#rp1-backend-rio-vs-pio) Pi-5 only. The RP1 SoC offers two GPIO drive modes: * **RIO mode (the library default — `rp1_pio` not set)** — faster refresh, higher CPU. * **PIO mode (`rp1_pio = 1`)** — lower CPU, slower refresh. The bigsign uses RIO — the default, so nothing to set. The Pi 5 has cores to spare and the bigger panel wants every Hz it can get. Note that RIO mode requires bumping `gpio_slowdown` (next section). Before June 2026 the knob was called `rp1_rio` and PIO was the default; an old `rp1_rio = 1` line in a config is now ignored (with a startup warning) and RIO applies anyway. ### `gpio_slowdown = 3` [Section titled “gpio\_slowdown = 3”](#gpio_slowdown--3) GPIO timing slowdown, must pair with RIO mode (the default). The Pi 4 default of `2` is too aggressive when paired with RIO mode — start at `3`, and raise to `4` or `5` if you still see flicker. Higher values trade refresh rate for stability, same tradeoff as on the smallsign just at a higher floor. ## Sharp edges [Section titled “Sharp edges”](#sharp-edges) ### `content_height` cannot exceed 16 at scale = 4 [Section titled “content\_height cannot exceed 16 at scale = 4”](#content_height-cannot-exceed-16-at-scale--4) The hard ceiling is `content_height × scale ≤ panel_h_real`. For the bigsign at `scale = 4` and a 64-tall panel that’s `content_height ≤ 16`. Pushing above the ceiling makes the wrapper’s vertical offset go negative — the logical canvas is taller than the real panel — and the top + bottom rows of your content silently clip. BDF text is forgiving because cells sit near the vertical center, but hi-res emoji and large hi-res fonts surface the clip immediately (e.g. a hi-res `:instagram:` icon loses about 4 real px off the bottom). For per-row breathing room use `text_y_offset` on the widget, not a higher `content_height`. ### The `pixel_mapper_config` Remap string is sensitive to chain order [Section titled “The pixel\_mapper\_config Remap string is sensitive to chain order”](#the-pixel_mapper_config-remap-string-is-sensitive-to-chain-order) Every entry in the string must correspond to a specific panel position in your data chain — get the order wrong (or rotate one panel 180° to match the rest of the row) and you’ll see content split across panels or rendered upside down. The string in `config/config.bigsign.example.toml` matches a 2x4 serpentine starting at the bottom-right with all panels upright; if your panels are mounted differently, you’ll need to edit each entry’s orientation flag (`n`, `s`, `e`, `w`). Use [`panel-map`](/tools/panel-map/) to derive and verify the Remap string from your physical layout instead of hand-editing it. ### Hi-res emoji only render at scale ≥ 2 [Section titled “Hi-res emoji only render at scale ≥ 2”](#hi-res-emoji-only-render-at-scale--2) Slugs like `:moon:` and `:instagram:` have a 32x32 hi-res sprite in `HIRES_REGISTRY` that paints directly to the unwrapped real canvas, bypassing the wrapper’s 4x4 block expansion for sharper detail. On a smallsign at `default_scale = 1` the renderer falls back to the 8x8 lo-res sprite automatically — same icon footprint, less detail. Don’t expect hi-res emoji output on the smallsign. ### `pixel_mapper_config` for non-bigsign layouts [Section titled “pixel\_mapper\_config for non-bigsign layouts”](#pixel_mapper_config-for-non-bigsign-layouts) The Remap string follows the format `Remap:WIDTH,HEIGHT|x,yORIENT|...` with one entry per panel in chain order. Orientations: `n` = normal, `s` = 180°, `e` = 270°, `w` = 90°, `x` = discard. The bigsign’s 2×4 vertical-serpentine chain is documented above. For simpler layouts: * **2×2 grid (chain runs along the bottom row first, then top row right-to-left)**, all panels upright: `Remap:128,64|0,32n|64,32n|64,0n|0,0n` * **Single row of 4 panels**, all upright, chain enters left: `Remap:256,32|0,0n|64,0n|128,0n|192,0n` If your physical layout doesn’t match the chain order from the data cable, every panel in the wrong position needs an entry in the Remap string. See the upstream [`hzeller/rpi-rgb-led-matrix`](https://github.com/hzeller/rpi-rgb-led-matrix) README — the base for the [`jamesawesome/rpi-rgb-led-matrix`](https://github.com/JamesAwesome/rpi-rgb-led-matrix) fork led-ticker ships — for the full Remap reference. ### Wiring or driver problem? Run `panel-test` first [Section titled “Wiring or driver problem? Run panel-test first”](#wiring-or-driver-problem-run-panel-test-first) If your widgets render with the wrong colors, a garbled bottom half, only one panel lit, or visible flicker, the issue is most likely in the hardware layer (`led_rgb_sequence`, `panel_type`, `chain_length`, `gpio_slowdown`) — not in your config. The [`panel-test`](/tools/panel-test/) diagnostic isolates the hardware layer by painting flat R/G/B/W/B colors, so you can verify wiring and driver init before debugging widgets. ## Reference config [Section titled “Reference config”](#reference-config) A complete working config for this build, including the `pixel_mapper_config` string and the Pi 5 RP1 tuning this hardware needs. Drop this into `config/config.toml` and adjust the per-widget content. Complete `config.bigsign.example.toml` (256×64 bigsign) ```toml # led-ticker bigsign configuration — 256×64 canvas # # 8× P3 32×64 panels in a 2×4 vertical-serpentine layout = 256×64 logical. # Driven by a Raspberry Pi 5 through an Adafruit RGB Matrix HAT. # # Copy this to config.toml on the bigsign Pi and adjust the playlist for your # content. Full config-options reference: # https://docs.ledticker.dev/reference/config-options/ [display] rows = 32 cols = 64 chain_length = 8 parallel = 1 # pixel_mapper_config tells the rgbmatrix library how each panel's position in the # data chain maps to its physical (x, y) on the finished canvas. The bigsign # chain enters at the bottom-right panel, climbs each column bottom-to-top, # then jumps diagonally to the bottom of the next column to its left. All # panels are installed upright (no 180° rotations). See the chain diagram and # instructions for deriving your own mapper string at: # https://docs.ledticker.dev/hardware/bigsign/ # # Format: Remap:WIDTH,HEIGHT|x,yORIENT|... (one entry per panel in chain order) # Orientations: n=normal, s=180°, e=270°, w=90°, x=discard. # If your top-row panels are physically flipped 180°, swap each top-row 'n' # for 's' (e.g. "192,0n" → "192,0s"). pixel_mapper_config = "Remap:256,64|192,32n|192,0n|128,32n|128,0n|64,32n|64,0n|0,32n|0,0n" brightness = 60 # default_scale = 4 means every widget draws at the standard 16-tall logical # canvas, and the ScaledCanvas wrapper expands every pixel to a 4×4 real block # to fill the 64-tall panel. Widget code never sees the 256×64 panel directly # — all drawing is in logical-pixel coordinates. default_scale = 4 hardware_mapping = "adafruit-hat" # Pi 5 RP1 GPIO tuning. # # The library's default Pi 5 backend is RIO (Registered IO) — faster # refresh, more CPU than PIO. Set rp1_pio = 1 only to trade refresh # speed for lower CPU. # # gpio_slowdown = 3 pairs with RIO mode. The Pi 4 default of 2 is too # aggressive with RIO; raise to 4–5 if you still see flicker. # # pwm_bits = 8 drops from the 11-bit default, buying roughly 8× faster # refresh at a small color-depth cost. Barely noticeable for text and pixel # art; only relevant if you're displaying photos with smooth gradients. gpio_slowdown = 3 pwm_bits = 8 show_refresh_rate = true # log measured refresh Hz to stderr; remove once stable [title] delay = 5 # Global transition defaults. Full transition catalogue and per-family tuning # lives at https://docs.ledticker.dev/transitions/. [transitions] default = "push_left" duration = 0.5 easing = "ease_out" between_sections = "dissolve" # --- Playlist --- # Each [[playlist.section]] displays in order, then the whole playlist loops. # Sections, modes, and timing knobs: https://docs.ledticker.dev/concepts/sections-and-modes/ [[playlist.section]] mode = "ticker" loop_count = 1 # scale inherits from display.default_scale (4) [playlist.section.title] type = "message" text = "#DevOps News" font_color = "random" [[playlist.section.widget]] type = "message" text = "May the uptime be with you!" [[playlist.section.widget]] type = "message" text = "Always be shipping!" # --- Countdowns at scale=2 --- # Dropping to scale=2 gives 32px-tall content centered with 16px black bands # top and bottom — a visual change of pace between sections. [[playlist.section]] mode = "ticker" loop_count = 2 scale = 2 [playlist.section.title] type = "message" text = "Count Downs" font_color = "random" [[playlist.section.widget]] type = "countdown" text = "Days Until Summer" countdown_date = 2026-06-20 [[playlist.section.widget]] type = "countdown" text = "Days Until Fall" countdown_date = 2026-09-22 # --- GIF / image playback --- # The gif widget plays an animated GIF or static image at native physical # resolution (256×64), using the same fit/text-overlay knobs as the image # widget. Full reference: https://docs.ledticker.dev/widgets/gif/ # # `path` resolves relative to this config file's directory. Drop assets # under `/assets/` and reference by relative path. # # [[playlist.section]] # mode = "slideshow" # loop_count = 2 # # [[playlist.section.widget]] # type = "gif" # path = "assets/phoenix.gif" # fit = "pillarbox" ``` See also * [hardware/smallsign](/hardware/smallsign/) * [concepts/display](/concepts/display/) * [concepts/fonts](/concepts/fonts/) * [tools/panel-map](/tools/panel-map/) # Hardware: Building your own > Build your own scrolling RGB LED matrix sign — Raspberry Pi + HUB75 panels bill of materials, wiring, and the Docker deploy, end to end. led-ticker ships two **reference builds**: the [smallsign](/hardware/smallsign/) (Pi 4 + 5× 32×16 panels) and the [bigsign](/hardware/bigsign/) (Pi 5 + 8× P3 32×64 panels). They’re starting points, not requirements — anything in between (or beyond) is a viable build, and the engine is the same. ## Choosing a sign size [Section titled “Choosing a sign size”](#choosing-a-sign-size) The two reference builds sit at very different points on the cost / complexity / use-case curve. Use them as starting points and adjust panel count, panel pitch, or layout to fit your space. | Reference build | Cost & complexity | Use case | | --------------------------------- | ------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------- | | **Smallsign** — 5x 32x16, 160x16 | Lowest. One Pi 4, five panels, a bonnet, a 10A 5V supply. One evening of soldering and a weekend of config work. | A scrolling marquee for a desk, a shop window, or a single-line live feed (RSS, weather, countdowns). 16 rows is one BDF text line tall. | | **Bigsign** — 8x P3 32x64, 256x64 | High. Pi 5, eight P3 panels, a HAT, a 30A+ supply, a rigid frame, a 2x4 serpentine wiring run, hi-res font tuning. | Storefront-scale display. Fits hi-res emoji, two-row handles + promos, animated GIFs, and Inter / Beloved Sans rendered at native pixels. | Anything between those two — three panels in a row, six panels in a 2x3 grid, a custom non-rectangular layout — is fine; the rgbmatrix library and the led-ticker engine don’t assume the reference shapes. You’ll edit the `[display]` block (`rows`, `cols`, `chain_length`, `pixel_mapper_config`) to match your wiring. For `pixel_mapper_config` specifically, don’t hand-write the Remap string — use [`panel-map`](/tools/panel-map/) to derive it from your physical layout. You don’t need any of this hardware to start. The [`render-demo`](/tools/render-demo/) tool runs the real ticker engine against a test stub canvas and writes the output to a gif, so you can develop your config end-to-end with nothing but a laptop. ## Power budgets [Section titled “Power budgets”](#power-budgets) RGB matrix panels draw current proportional to the number of LEDs lit at any moment. The rule-of-thumb upper bound is: ```text amps_max = rows × cols × number_of_panels × 0.06A (per LED, full white) ``` That’s the **theoretical maximum** at 5V with every pixel cranked to white at the same instant. In practice that never happens — text, emoji, and animations only light a fraction of the panel — so the practical draw is roughly 30-40% of the theoretical max. | Reference build | Theoretical max | Practical pick | | --------------- | --------------- | -------------- | | Smallsign | 5V × \~150A | 5V × **10A** | | Bigsign | 5V × \~980A | 5V × **60A** | A 5V / 10A brick covers the smallsign with comfortable headroom; the bigsign wants a 5V / 30-60A supply with thick busbars (split across multiple injection points if your panels have multiple power inputs). Adafruit’s product pages publish per-panel current draw curves — cross-reference those for whichever panels you actually buy, since brightness, panel revision, and pixel pitch all shift the number. The Pi itself runs off its own USB-C supply; do **not** try to power panels off the Pi’s 5V rail. The math doesn’t work for one panel either, let alone five or eight. ## Software-first development [Section titled “Software-first development”](#software-first-development) You can develop a complete led-ticker config without owning a single panel. Two paths — pick whichever fits your workflow: **Browser preview (Docker, no Python needed)** — the fastest way to see the sign rendering: ```bash make try # build + start; open http://localhost:8080 → live preview tab ``` `make try` starts a headless engine and the web UI in Docker. Stop with `Ctrl-C` then `make try-down`. **GIF renderer (Python dev path)** — render any config to a GIF at panel resolution, useful for CI, scripted demos, and configs with live-data widgets: ```bash git clone https://github.com/JamesAwesome/led-ticker.git cd led-ticker make dev # install Python dev deps (requires uv) ``` Run the test suite — no hardware, no Docker: ```bash make test ``` `make test` runs the full suite — pyproject’s `[tool.pytest.ini_options] pythonpath = ["tests/stubs"]` puts the stub canvas on the path automatically, so no env var is needed. \~1450 tests, finishes in \~2 minutes. Render any config to a gif at panel resolution: ```bash make render-demo CONFIG=mysign.toml OUT=mysign.gif ``` A minimal config you can render right now: ```toml [display] rows = 16 cols = 32 chain_length = 5 default_scale = 1 brightness = 60 [[playlist.section]] mode = "slideshow" loop_count = 1 hold_time = 4.0 [[playlist.section.widget]] type = "message" text = "Hello, panel" font_color = "rainbow" ``` The output gif is upscaled 4x by default so individual LED pixels read clearly. See [`render-demo`](/tools/render-demo/) for the full set of flags and the long-running pipeline used for data-fetch widgets. ## Deploying to the Pi [Section titled “Deploying to the Pi”](#deploying-to-the-pi) Once your config renders the way you want, push it to a Pi. Deployment is **Docker Compose** — one command and the sign is running: ```bash make setup # Docker preflight + config/.env seed + bring-up (first time) make update # rebuild the image (real version) + recreate services (subsequent deploys) ``` `make setup` (or `make setup MODE=deploy`) checks that Docker is installed, seeds `config/config.toml` and `.env` if they don’t exist yet, and runs `docker compose up -d`. After that, `make update` rebuilds the image (with a real version baked in) and recreates the running services for every subsequent deploy. Key behaviors built into `compose.yaml`: * `restart: unless-stopped` — the ticker comes back up on power loss or crash. * Config mounted read-only (`./config:/code/config:ro`) — a typo in a hot-edit can’t crash the ticker into a half-applied state. * Hot-reload is on by default: edit `config/config.toml` on the host and most changes (sections, widgets, schedule) take effect within one playlist cycle — no restart needed. **Panel bring-up** — after wiring up the hardware and the first boot: 1. Run [`make panel-test`](/tools/panel-test/) to cycle the panel through solid R/G/B/White/Black. If colors are missing or wrong, check your wiring and the `led_rgb_sequence` config knob before going further. 2. Use the [`panel-map`](/tools/panel-map/) reveal → derive → verify workflow to build the `pixel_mapper_config` Remap string for your exact panel layout. To take the sign down for a diagnostic, `docker compose stop`; bring it back with `docker compose start`. **Repo hygiene** — your running `config/config.toml` is gitignored (it’s yours to customize per sign). Private media — images, GIFs, custom fonts — goes in `config/local/` (also gitignored) and is referenced in TOML as `path = "local/"`. ## Sharp edges [Section titled “Sharp edges”](#sharp-edges) ### The rgbmatrix library is hardcoded to a fork in the Dockerfile [Section titled “The rgbmatrix library is hardcoded to a fork in the Dockerfile”](#the-rgbmatrix-library-is-hardcoded-to-a-fork-in-the-dockerfile) If you deploy via Docker (the recommended path), you don’t need to do anything — the image already builds the correct fork. For source builds: the Dockerfile pins [`jamesawesome/rpi-rgb-led-matrix`](https://github.com/JamesAwesome/rpi-rgb-led-matrix) — our fork of `hzeller/rpi-rgb-led-matrix`. It tracks upstream’s Pi 5 RP1 support ([hzeller#1886](https://github.com/hzeller/rpi-rgb-led-matrix/pull/1886)) and adds three patches the engine depends on: a GCC-10 build fix, a Pillow shim, and a **SubFill Python binding that upstream doesn’t ship**. Because of that last one, stock upstream is not a drop-in replacement. If you `apt install` or `pip install` a different rgbmatrix on the Pi outside the Docker image — or check out upstream `hzeller/master` and `make install` it — your Pi will diverge from what the engine was tested against, and you’ll spend an afternoon chasing flicker that isn’t a config bug. Rebuild from source against the pinned fork. ### USB-C “5V 3A” power supplies aren’t dedicated panel supplies [Section titled “USB-C “5V 3A” power supplies aren’t dedicated panel supplies”](#usb-c-5v-3a-power-supplies-arent-dedicated-panel-supplies) A phone charger or a generic USB-C brick marketed as 5V 3A does not sustain rated current under inductive matrix load — the voltage sags, panels glitch, and you blame the config. Use a dedicated 5V supply sized per the power-budget table above (10A for the smallsign, 30-60A for the bigsign), with thick power leads to each panel’s 2-pin input. ### Panels run hot at full brightness [Section titled “Panels run hot at full brightness”](#panels-run-hot-at-full-brightness) P3 panels at brightness 60+ get warm to the touch within minutes; the smallsign is more forgiving but still climbs over time. For sustained or always-on installs add a fan behind the panels, or design a shroud with airflow gaps. Heat shortens LED lifespan and can warp panel substrates if it accumulates with no ventilation. ### Running from a source checkout (dev / evaluation) [Section titled “Running from a source checkout (dev / evaluation)”](#running-from-a-source-checkout-dev--evaluation) If you want to run led-ticker directly from a Python virtualenv rather than Docker — for development, custom patches, or experimentation — install the package and its deps with `make dev` (which runs `uv sync --extra dev`), then invoke `led-ticker --config config/config.toml` directly. Wheels on the Pi A source-checkout install on the Pi may compile some dependencies from source — piwheels does not provide aarch64 wheels and its cp314 armv7l coverage is incomplete as of mid-2026. The Docker image ships every wheel pre-built, so the first build (via `make setup`) is typically faster than a bare `pip install` on the Pi. ## Inspecting the running async loop (Python 3.14+) [Section titled “Inspecting the running async loop (Python 3.14+)”](#inspecting-the-running-async-loop-python-314) led-ticker is one long-lived asyncio loop plus a background task per data widget (`run_monitor_loop`) and the optional busy-light HTTP server. On Python 3.14 you can print the live task tree of a running process with no code changes or restart: ```bash # pid of the led-ticker process (inside the container or in a dev checkout) python -m asyncio pstree # flat list with awaited-by edges python -m asyncio ps ``` If a data widget’s `update()` task has died (the tell-tale: its periodic ”… updated: N stories” INFO log stopped), it will be absent from the tree — turning “is the poller still alive?” into a direct answer. See also * [hardware/smallsign](/hardware/smallsign/) * [hardware/bigsign](/hardware/bigsign/) * [tools/render-demo](/tools/render-demo/) * [tools/panel-map](/tools/panel-map/) * [getting-started](/getting-started/) # Hardware: Longboi reference build > led-ticker's reference build for widescreen single-row displays — Pi 5 + four Muen P2 128×64 panels chained horizontally for a 512×64 canvas (~1m wide). The **longboi** is led-ticker’s reference build for widescreen single-row displays: a Raspberry Pi 5 driving four [Muen P2 128×64 indoor LED panels](https://www.aliexpress.us/item/3256808899822704.html) chained horizontally for a 512×64 canvas — roughly 100 cm × 13 cm overall. The MLB scoreboard layout and the hires font pipeline were developed against this build. It sits on top of a bookcase and appears on camera during meetings, which is why the reference config is tuned to minimise flicker in video. ## At a glance [Section titled “At a glance”](#at-a-glance) * Raspberry Pi 5 * 4× Muen P2 128×64 LED panels chained left-to-right = 512×64 physical canvas * \~100 cm × 13 cm overall (four 256 mm × 128 mm panels end-to-end) * `default_scale = 4` — every logical pixel becomes a 4×4 block on the real panel; drawing logic stays at the standard 16-tall logical canvas * No `pixel_mapper_config` needed — a single horizontal chain with `chain_length = 4` is enough * Same Docker image as the bigsign; the rgbmatrix library detects the SoC at runtime ## Bill of materials [Section titled “Bill of materials”](#bill-of-materials) | Component | Quantity | Notes | | --------------------------------------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------ | | Raspberry Pi 5 | 1 | 4 GB is plenty. A microSD card and a USB-C supply for the Pi itself. | | [Muen P2 128×64 indoor LED panel](https://www.aliexpress.us/item/3256808899822704.html) | 4 | HUB75 panels, 256 mm × 128 mm each, P2 (2 mm) pitch. FM6126A driver IC — `panel_type = "FM6126A"` is required in config. | | Adafruit RGB Matrix Bonnet | 1 | Sets `hardware_mapping = "adafruit-hat"` in the config. The HAT works equivalently. | | [Mean Well LRS-200-5 5 V 40 A supply](https://www.amazon.com/dp/B0B6HSLSQQ) | 1 | 200 W headroom for four P2 panels. Wire directly to panel power inputs — do NOT power panels off the Pi. | | 16-pin IDC ribbon cables | 3+ | One between each panel in the chain. Most panels ship with a short cable; buy extras for the longer runs. | | Power distribution wire / pigtails | 1+ | Each panel has its own 2-pin power input. Daisy-chain from the PSU or use a busbar. | **Total cost (rough):** \~$300–400 USD. The PSU and four panels are the dominant line items. Cross-check current pricing before ordering. ## Assembly notes [Section titled “Assembly notes”](#assembly-notes) ### E-pin soldering (required for 64-row panels) [Section titled “E-pin soldering (required for 64-row panels)”](#e-pin-soldering-required-for-64-row-panels) Required step — do not skip 64-row panels need the **E address line** for row addressing beyond row 32. The Adafruit bonnet was designed for 32-row panels and does not wire E by default. Without it the bottom half of every panel renders mirrored or garbled. Solder a jumper wire from **GPIO 8** to the **E pad** on the Adafruit bonnet. Follow the [Adafruit RGB Matrix Bonnet setup guide](https://learn.adafruit.com/adafruit-rgb-matrix-bonnet-for-raspberry-pi/matrix-setup) for pad location and soldering instructions. This is the one step not covered by the panel datasheet or the rgbmatrix README — everything else (IDC cables, power wiring) is standard HUB75. ### Panel init sequence (`panel_type = "FM6126A"`) [Section titled “Panel init sequence (panel\_type = "FM6126A")”](#panel-init-sequence-panel_type--fm6126a) The Muen P2 panels use the FM6126A (or compatible) driver IC, which requires a proprietary initialization sequence at startup. Set `panel_type = "FM6126A"` in the config. Without it the driver powers up in a bad state and the first scan lines render with the wrong brightness or color. ### Color channel order (`led_rgb_sequence = "BRG"`) [Section titled “Color channel order (led\_rgb\_sequence = "BRG")”](#color-channel-order-led_rgb_sequence--brg) These panels wire the HUB75 R/G/B lines in a non-standard order (G → Red LED, R → Blue LED, B → Green LED). Set `led_rgb_sequence = "BRG"`. Without it all colors are wrong. ## Config snippet [Section titled “Config snippet”](#config-snippet) The minimal `[display]` block for the longboi, tuned for camera use (`pwm_bits = 7` and `limit_refresh_rate_hz = 100` reduce flicker visible in video): ```toml [display] rows = 64 cols = 128 chain_length = 4 brightness = 60 default_scale = 4 hardware_mapping = "adafruit-hat" panel_type = "FM6126A" # FM6126A init sequence — required for Muen P2 led_rgb_sequence = "BRG" # Muen P2 color channel order gpio_slowdown = 5 # Pi 5 RIO backend (default); raise if flicker persists pwm_bits = 7 # 7-bit PWM: tuned for camera; default is 11 limit_refresh_rate_hz = 100 # caps refresh to stabilise image on camera ``` ### Tuning knobs [Section titled “Tuning knobs”](#tuning-knobs) | Setting | Value | Why | | ----------------------- | ----------- | --------------------------------------------------------------------------------------------------- | | `gpio_slowdown` | `5` | Pi 5 with the default RIO backend needs higher slowdown than Pi 4. Raise to 6+ if flicker persists. | | `row_address_type` | `0` | Must remain `0` (the default) with the RIO backend. Setting `1` breaks display output. | | `pwm_bits` | `7` | 7-bit PWM keeps the refresh rate high while limiting flicker visible in video. Default is 11. | | `limit_refresh_rate_hz` | `100` | Caps the refresh to a stable rate for camera capture. Remove if not on camera. | | `panel_type` | `"FM6126A"` | Required FM6126A init sequence; without it the bottom half of panels is garbled. | | `led_rgb_sequence` | `"BRG"` | Muen P2 non-standard color wiring. Without it all colors are wrong. | | `default_scale` | `4` | Maps the 16-tall logical canvas to the 64-tall physical panel. | ## Photos [Section titled “Photos”](#photos) *Photos coming soon.* * Full display on bookcase (form factor) * E-pin solder joint on the bonnet (the critical assembly step) * Back of panels showing IDC cable routing See also * [hardware/bigsign](/hardware/bigsign/) * [hardware/building-your-own](/hardware/building-your-own/) * [widgets/mlb](/widgets/mlb/) # Hardware: Smallsign reference build > led-ticker's reference build for short single-line displays — Pi 4 + five chained 32x16 panels for a 160x16 ticker. The **smallsign** is led-ticker’s reference build for short single-line displays: a Raspberry Pi 4 driving five chained 32x16 RGB matrix panels through Adafruit’s RGB matrix bonnet for a 160x16 canvas. It’s the target the project was originally written against, and the dimensions the smallsign-flavored examples in `config/` assume. You don’t have to match it exactly — any HUB75 panel chain that fits a similar shape (Pi 4 with the adafruit-hat mapping, 16-tall canvas) will run the same configs — but the parts list and tuning notes below are what we built and tested against. ## At a glance [Section titled “At a glance”](#at-a-glance) * Raspberry Pi 4 Model B * 5x chained 32x16 RGB matrix panels = 160x16 logical canvas * \~20 fps (50ms per frame) * `default_scale = 1` — drawing logic and panel pixels are 1:1 * Same Docker image as the bigsign reference build; the rgbmatrix library detects the SoC at runtime ## Bill of materials [Section titled “Bill of materials”](#bill-of-materials) What is HUB75? HUB75 is the standard data-cable interface for RGB LED matrix panels — a 16-pin IDC connector carrying RGB + clock + addressing signals. Any panel advertised as “HUB75-compatible” works with the Adafruit bonnet / HAT and the rgbmatrix library this project uses. | Component | Quantity | Notes | | ---------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Raspberry Pi 4 Model B | 1 | 2 GB is plenty. A microSD card and a USB-C power supply for the Pi itself. | | 32x16 RGB matrix panel | 5 | HUB75 panels with the standard 16-pin IDC connector. Matched panels render most consistently. | | Adafruit RGB matrix bonnet | 1 | Sets `hardware_mapping = "adafruit-hat"` in the config. Bonnet and HAT are Adafruit’s two names for boards that do the same job — plug onto the Pi’s GPIO header and drive HUB75 panels; the bonnet is the low-profile option. | | 5V power supply | 1 | Size for the chain — five 32x16 panels at full white draw several amps. A 5V / 10A brick is a comfortable headroom pick. Do NOT power the panels off the Pi’s USB rail. | | 16-pin IDC ribbon cables | 4 | Flat ribbon cable with HUB75 plugs — carries data panel-to-panel. One between each pair of panels. Most panels ship with one short cable; you may need extras to reach all four gaps. | | Power pigtails / barrel jack | 1+ | Whatever your panels expect. Each panel has its own 2-pin power input. | | Shroud / case (optional) | 1 | Acrylic diffuser + a 3D-printed frame is the typical finish. Not required to run. | **Total cost (rough):** \~$150–200 USD depending on panel sourcing and shipping. The Pi 4 is the largest single line item; the Adafruit bonnet or HAT runs $20–25; matched 32×16 panels run $15–25 each at retail (cheaper in lots from AliExpress). Cross-check current pricing before ordering — these numbers were verified in early 2026 and panel prices fluctuate. The config tells the rgbmatrix library you’re using the bonnet/HAT via `hardware_mapping = "adafruit-hat"`. If you swap to a bare wiring harness, that flag changes too — see the upstream [`hzeller/rpi-rgb-led-matrix` README](https://github.com/hzeller/rpi-rgb-led-matrix) (the base for the [`jamesawesome/rpi-rgb-led-matrix`](https://github.com/JamesAwesome/rpi-rgb-led-matrix) fork led-ticker ships) for alternatives. ## Wiring [Section titled “Wiring”](#wiring) Before wiring, finish Adafruit’s own assembly steps for the bonnet — solder the GPIO header if yours shipped unsoldered (see [Adafruit’s bonnet guide](https://learn.adafruit.com/adafruit-rgb-matrix-bonnet-for-raspberry-pi/assembly)). That product prep is Adafruit’s territory; everything after it is covered here. Chain the five panels left-to-right with the IDC ribbon cables. **Chain order matters**: the first panel in the chain (where the bonnet’s data output plugs in) is the LEFTMOST panel on screen, and the last panel in the chain is the RIGHTMOST. If your text shows up mirrored or split across the wrong panels, you’ve got the chain reversed. Each panel has two HUB75 connectors, labeled IN and OUT on the silkscreen — data flows bonnet → panel 1 IN, then panel 1 OUT → panel 2 IN, and so on down the chain. Each panel also needs its own 5V power lead — the data ribbon does not carry panel power. Most builds share one splitter or busbar from the 5V supply, with a short 2-pin lead to each panel’s power connector. Seat the bonnet so its 40-pin socket covers all 40 pins of the Pi’s GPIO header — it only fits flush one way, with the bonnet’s board overhanging the Pi’s USB-port end when seated correctly. The bonnet’s HUB75 output plugs into the first panel’s data input. The `chain_length` field in the config (next section) tells led-ticker how many panels are linked. ## Config snippet [Section titled “Config snippet”](#config-snippet) The minimal `[display]` block for the smallsign — straight from `config/config.example.toml`: ```toml [display] rows = 16 # panel height cols = 32 # panel width chain_length = 5 # number of panels chained left-to-right brightness = 60 # 0-100, not 0-255 gpio_slowdown = 2 # mandatory on Pi 4 — bump to 3+ if flicker hardware_mapping = "adafruit-hat" # Adafruit bonnet or HAT ``` The 160x16 logical canvas is `cols * chain_length` wide by `rows` tall. Every widget on the smallsign draws to that canvas at native pixel resolution — no `ScaledCanvas` wrapper, no logical-to-physical block expansion. ## Sharp edges [Section titled “Sharp edges”](#sharp-edges) ### `gpio_slowdown` is mandatory on the Pi 4 [Section titled “gpio\_slowdown is mandatory on the Pi 4”](#gpio_slowdown-is-mandatory-on-the-pi-4) Without it (or with it set to 0) the rgbmatrix library updates the GPIO faster than the Pi 4 can keep up, and you’ll see panels glitch, flicker, or display garbage. Start at `2` — that’s the example config’s default — and bump it to 3 or higher if you still see flicker. Higher values trade refresh rate for stability. ### Do not set `default_scale` to anything other than 1 here [Section titled “Do not set default\_scale to anything other than 1 here”](#do-not-set-default_scale-to-anything-other-than-1-here) The smallsign is 16 logical rows tall and 16 physical rows tall — there is no logical-to-physical wrapping to do. The `ScaledCanvas` wrapper only kicks in when `default_scale > 1` and assumes the panel is taller than 16 logical rows, so cranking it on the smallsign just clips your content. ### Brightness is 0-100, not 0-255 [Section titled “Brightness is 0-100, not 0-255”](#brightness-is-0-100-not-0-255) Setting `brightness = 255` doesn’t make the panels brighter — the rgbmatrix library reads it as “the maximum, plus a lot more” and behavior is undefined. Stay in 0-100; 60 is a typical indoor value. ### Wiring or driver problem? Run `panel-test` first [Section titled “Wiring or driver problem? Run panel-test first”](#wiring-or-driver-problem-run-panel-test-first) If your widgets render with the wrong colors, only one panel lit, or visible flicker during scrolling, the issue is most likely in the hardware layer (`led_rgb_sequence`, `chain_length`, `gpio_slowdown`) — not in your config. The [`panel-test`](/tools/panel-test/) diagnostic isolates the hardware layer by painting flat R/G/B/W/B colors, so you can verify wiring before debugging widgets. ## Reference config [Section titled “Reference config”](#reference-config) A complete working config for this build. Drop this into `config/config.toml` and adjust the per-widget content for your sign. Complete `config.example.toml` (160×16 smallsign) ```toml # led-ticker configuration — smallsign starter (160×16 canvas) # # 5× chained 32×16 panels = 160×16 logical canvas. Driven by a Raspberry Pi 4 # through an Adafruit RGB Matrix bonnet. No pixel_mapper_config needed — panels # are a single horizontal chain_length, left-to-right. # # This starter runs entirely on BUILT-IN widgets — no plugins required, so it # boots straight from `make setup`. Want live data (weather, RSS, crypto, MLB # scores, pool temps)? Those are first-party plugins — see "Add live data with # plugins" near the bottom and https://docs.ledticker.dev/plugins/ . # # Copy this to config.toml and adjust the playlist sections for your content. # Full config-options reference: https://docs.ledticker.dev/reference/config-options/ [display] rows = 16 cols = 32 chain_length = 5 brightness = 60 gpio_slowdown = 2 # mandatory on Pi 4 — bump to 3+ if you see flicker hardware_mapping = "adafruit-hat" # hot_reload = true # live-reload config.toml edits without a restart (default on; set false to disable) # --- Optional: brightness schedule (uncomment + edit to use) --- # Example: full brightness by day, a softer evening, and a dim overnight # (10pm–7am, every day). Times are local wall-clock — set `timezone` or they # follow the Pi's system clock (often UTC). Any hour not covered by a window # uses the [display] `brightness` above. # [display.schedule] # enabled = true # timezone = "America/New_York" # set this! defaults to the Pi's system time (often UTC) # # [[display.schedule.windows]] # start = "07:00" # end = "18:00" # brightness = 100 # # [[display.schedule.windows]] # start = "18:00" # end = "22:00" # brightness = 40 # # [[display.schedule.windows]] # dim overnight, 10pm → 7am, every day # start = "22:00" # 10pm — wraps past midnight to 7am # end = "07:00" # brightness = 15 # dim, not off (set brightness = 0 to switch the panel off) # # days omitted = every day; e.g. days = ["mon", "tue", "wed", "thu", "fri"] for weekdays only [title] delay = 5 # --- Transitions --- # Global transition defaults. Full transition catalogue and per-family tuning # lives at https://docs.ledticker.dev/transitions/. The values below give a # 0.5-sec wipe between widgets within a section and a dissolve between sections # — readable on a 160×16 smallsign without being distracting. [transitions] default = "wipe_alternating" duration = 0.5 easing = "ease_out" between_sections = "dissolve" # --- Playlist --- # Each [[playlist.section]] displays in order, then the whole playlist loops. # Sections, modes, and timing knobs: https://docs.ledticker.dev/concepts/sections-and-modes/ # Welcome / brand messages. [[playlist.section]] mode = "ticker" loop_count = 1 [playlist.section.title] type = "message" text = "#DevOps News" font_color = "random" [[playlist.section.widget]] type = "message" text = "May the uptime be with you!" [[playlist.section.widget]] type = "message" text = "Always be shipping!" # Counts down to any date. Message + remaining days scroll across the panel. [[playlist.section]] mode = "ticker" loop_count = 2 [playlist.section.title] type = "message" text = "Count Downs" font_color = "random" [[playlist.section.widget]] type = "countdown" text = "Days Until Spring" countdown_date = 2027-03-20 # ← change to your own date [[playlist.section.widget]] type = "countdown" text = "Days Until Summer" countdown_date = 2027-06-20 # Counts up from any past date. Widget disappears before countup_date arrives. [[playlist.section.widget]] type = "countup" text = "Open for" countup_date = 2024-01-01 # Local time — the built-in clock widget. `format` is "12h"/"24h" or a strftime # template (e.g. "%I:%M %p %Z"); set `timezone` to an IANA name or it follows # the Pi's system clock. Knobs: https://docs.ledticker.dev/widgets/clock/ [[playlist.section]] mode = "slideshow" hold_time = 5 loop_count = 1 [playlist.section.title] type = "message" text = "Local Time" font_color = "random" [[playlist.section.widget]] type = "clock" format = "12h" timezone = "America/New_York" font_color = "rainbow" # A bundled sample animation — no plugin, no API key, and no media of your own # required. config/assets/ ships a few CC0 clips; swap `path` for your own art # in config/local/ (gitignored). Image/gif knobs: https://docs.ledticker.dev/widgets/gif/ [[playlist.section]] mode = "slideshow" hold_time = 5 loop_count = 1 [[playlist.section.widget]] type = "gif" path = "assets/phoenix.gif" fit = "pillarbox" image_align = "center" # ── Add live data with plugins ──────────────────────────────────────── # Everything above is built in. For live feeds, install a first-party plugin # (https://docs.ledticker.dev/plugins/) — copy the requirements file, add the # plugin you want, and restart (no image rebuild): # # cp config/requirements-plugins.example.txt config/requirements-plugins.txt # # uncomment the plugin line(s) you want, then: # docker compose restart # # (or use the web UI Store tab, which writes that file for you). Then add a # section using the plugin's widget type: # # led-ticker-weather weather.current current conditions (WeatherAPI.com) # led-ticker-rss rss.feed RSS / Atom headlines # led-ticker-crypto crypto.coingecko crypto prices (CoinGecko) # led-ticker-baseball baseball.scores / .standings / … + baseball.roll* transition # led-ticker-calendar calendar.events calendar (.ics) agenda / next event # led-ticker-pool pool.monitor pool water temperature (InfluxDB) # # Example — current weather (needs led-ticker-weather + WEATHERAPI_KEY in .env; # location can be a city name, zip code, or "lat,lon"): # # [[playlist.section]] # mode = "slideshow" # loop_count = 1 # # [playlist.section.title] # type = "message" # text = "Weather" # font_color = "random" # # [[playlist.section.widget]] # type = "weather.current" # text = "NYC" # location = "New York" # units = "imperial" # ────────────────────────────────────────────────────────────────────── # --- Images and media --- # Bundled sample art lives in config/assets/ and is referenced as # path = "assets/" (e.g. path = "assets/phoenix.gif"). # Your own media goes in config/local/ (gitignored), referenced as # path = "local/" (e.g. path = "local/logo.gif"). # The entire config/ directory is mounted into the container, so both # locations resolve correctly at runtime. # Busy light — a persistent corner dot that lights up while a local file # exists. The dot composites over every section and transition. (Real # calendar/Slack sources are a future addition behind the same overlay.) # # DOCKER (the usual deploy): `~/.busy` is the CONTAINER's home, which your # host can't reach. Point file_path at the bind-mounted config dir instead # and toggle the file on the host: # file_path = "/code/config/.busy" # in-container path (./config:/code/config:ro) # touch config/.busy # ON rm config/.busy # OFF # # [busy_light] # enabled = true # file_path = "/code/config/.busy" # poll_interval = 5.0 # corner = "top_right" # top_left | top_right | bottom_left | bottom_right # color = [255, 0, 0] # 3 ints, each 0-255 # size = 4 # dot side in physical px: ~4 on the 16-tall # # smallsign, ~8-10 on the 64-tall bigsign/longboi # token = "" # fallback only — prefer LED_TICKER_BUSY_TOKEN in .env # Web status UI — serves a live dashboard of what's on the panel at # http://:8080. Presence of this block enables status publishing by the # display process; the sidecar reads status.json and handles HTTP. # # DOCKER (the usual deploy): the compose.yaml webui service sits behind the # `webui` compose profile — start with `COMPOSE_PROFILES=webui docker compose up -d` # (or add COMPOSE_PROFILES=webui to your .env to make it sticky). # Docs: https://docs.ledticker.dev/concepts/web-status-ui/ # # [web] # http_host = "0.0.0.0" # http_port = 8080 # token = "" # fallback only — prefer LED_TICKER_WEB_TOKEN in .env (secrets don't belong in config.toml) # status_path = "/run/led-ticker/status.json" # default works in Docker too (shared volume mounts here) # allow_restart = true # enables the "Restart to apply" button in the web UI; requires a process supervisor # # to bring the display back — Docker's `restart: unless-stopped` (shipped in compose.yaml) # # handles this automatically. Defaults to false. ``` See also * [hardware/bigsign](/hardware/bigsign/) * [hardware/building-your-own](/hardware/building-your-own/) * [getting-started](/getting-started/) # Validation rules > Configuration mistakes the validator catches before they bite on the panel. `led-ticker validate` reads your `config.toml` and reports every rule below. Run it before you deploy: ```bash led-ticker validate config/config.toml ``` It exits non-zero on errors so you can wire it into CI. The numeric IDs in headings below match the `rule` field on `--json` output (used by the [`creating-a-config`](/tools/creating-a-config/) skill and any other programmatic consumer); they’re stable across releases. The human-readable CLI output drops them — every error / warning is self-contained on a single line. ## Errors [Section titled “Errors”](#errors) Errors block the engine from starting. Fix all of these before deploying. ### Rule 3 — `text_align = "scroll"` with `fit = "stretch"` hides the text [Section titled “Rule 3 — text\_align = "scroll" with fit = "stretch" hides the text”](#rule-3--text_align--scroll-with-fit--stretch-hides-the-text) Stretch fills every panel pixel with image, leaving no transparent regions for the scrolling text to show through. Use `text_align = "scroll_over"` (text paints on top of the image — the intended pairing with a fullscreen opaque stretch), switch `fit` to `"pillarbox"`, `"letterbox"`, or `"crop"`, or change `text_align` to `"left"`, `"right"`, or `"auto"`. ### Rule 7 — `text_x_offset` is rejected in scroll modes [Section titled “Rule 7 — text\_x\_offset is rejected in scroll modes”](#rule-7--text_x_offset-is-rejected-in-scroll-modes) Static `text_x_offset` doesn’t compose with the per-tick scroll cursor. Either set `text_x_offset = 0` or change `text_align` to `"left"` or `"right"`. ### Rule 8 — `hold_time < 0.05` is almost certainly a unit error [Section titled “Rule 8 — hold\_time < 0.05 is almost certainly a unit error”](#rule-8--hold_time--005-is-almost-certainly-a-unit-error) `hold_time` is in seconds, not milliseconds. Anything under 50 ms is rejected. If you wrote `3000` thinking ms, you want `3.0`. ### Rule 12 — `animation` is only valid on `message`, `gif`, and `image` [Section titled “Rule 12 — animation is only valid on message, gif, and image”](#rule-12--animation-is-only-valid-on-message-gif-and-image) Other widget types have their own draw paths and ignore `animation` silently — the validator rejects it explicitly to make the no-op visible. For dynamic color on `weather.current`, `rss.feed`, the crypto widgets, or `two_row`, use `font_color = "rainbow"` or a gradient instead. ### Rule 14 — `animation = "typewriter"` on `gif` / `image` is single-row only [Section titled “Rule 14 — animation = "typewriter" on gif / image is single-row only”](#rule-14--animation--typewriter-on-gif--image-is-single-row-only) Typewriter draws fixed-position glyphs and rejects three combinations: `bottom_text` set (two-row mode), `text_align = "scroll"` / `"scroll_over"` (cursor moves each tick), or empty `text`. Drop the conflicting setting. Typewriter still composes with `font_color = "rainbow"` and `border = "rainbow"`. ### Rule 22 — Font line-height exceeds the per-row band [Section titled “Rule 22 — Font line-height exceeds the per-row band”](#rule-22--font-line-height-exceeds-the-per-row-band) On `two_row`, or on `gif` / `image` with `bottom_text` set, each row gets a slice of `content_height`. A font taller than its band would clip into the other row. Pick a smaller `font_size`, raise `content_height`, set `top_row_height` to give the offending row more space, or use a BDF alias (`5x8`, `6x12`). ### Rule 25 — `start_hold` is only valid on scroll modes [Section titled “Rule 25 — start\_hold is only valid on scroll modes”](#rule-25--start_hold-is-only-valid-on-scroll-modes) `start_hold` controls the pre-roll delay before a `ticker` / `one_at_a_time` section’s first widget begins moving. It calls into `_scroll_and_delay`, which `slideshow` mode doesn’t use. Setting `start_hold` on a `slideshow` section would silently do nothing — the validator rejects it so the misconfiguration surfaces immediately. For `slideshow` mode, the per-widget hold is `hold_time`. Also rejected: `start_hold < 0`. ### Rule 26 — `separator_*` is only valid on `ticker` [Section titled “Rule 26 — separator\_\* is only valid on ticker”](#rule-26--separator_-is-only-valid-on-ticker) The `separator`, `separator_font`, `separator_font_size`, and `separator_color` fields customize the small bullet that `ticker` mode inserts between widgets in the side-by-side stream. `slideshow` mode doesn’t intersperse anything; `one_at_a_time` fully exits each widget before the next, so no separator is needed. Setting any of these fields on a non-`ticker` section would silently do nothing — the validator rejects it. Either remove the fields, or change `mode` to `"ticker"`. ### Rule 28 — `bottom_text_loops` requires `bottom_text_wrap` [Section titled “Rule 28 — bottom\_text\_loops requires bottom\_text\_wrap”](#rule-28--bottom_text_loops-requires-bottom_text_wrap) `bottom_text_loops` on a `two_row` widget controls how many full wrap cycles the bottom row must play before the section ends. A cycle is `bottom_text` + the separator — both only exist when `bottom_text_wrap = true`. In non-wrap mode the bottom row scrolls once over its overflow and there’s no cycle to count, so the validator rejects `bottom_text_loops > 0` without wrap. Negative values and `true` / `false` (bool — `bool` is a Python int subclass, so without an explicit guard `bottom_text_loops = true` would silently behave as `1`) are also rejected. Either turn on wrap mode, drop `bottom_text_loops`, or replace the bool with an integer count. ### Rule 31 — `scroll_step_ms` must be positive [Section titled “Rule 31 — scroll\_step\_ms must be positive”](#rule-31--scroll_step_ms-must-be-positive) `scroll_step_ms` is the engine’s per-tick advance, in milliseconds per logical pixel. The wraps\_forever branch in `_swap_and_scroll` computes `n_ticks = int(hold_time / scroll_speed)` where `scroll_speed = scroll_step_ms / 1000`. A value of `0` raises `ZeroDivisionError` at startup; negative values produce nonsensical tick counts. Set `scroll_step_ms` to a positive integer (typical range: 25–60 ms per pixel) or omit the field to inherit the engine default. ### Rule 29 — `text_loops` on `two_row` (did you mean `bottom_text_loops`?) [Section titled “Rule 29 — text\_loops on two\_row (did you mean bottom\_text\_loops?)”](#rule-29--text_loops-on-two_row-did-you-mean-bottom_text_loops) `text_loops` is the marquee-loop field on the `gif` / `image` widgets — those widgets are single-row by default and use the unprefixed name. The `two_row` widget is always two-row and uses `bottom_text_loops` to match its `bottom_text_wrap` / `bottom_text_separator` family. A config that writes `text_loops = N` on a `two_row` widget is almost always a copy-paste from a gif/image marquee config — the validator catches it and points at the right name. Rename `text_loops` to `bottom_text_loops` and set `bottom_text_wrap = true` (loops require wrap mode — see rule 28). ### Rule 1 — `content_height × scale` exceeds the panel height [Section titled “Rule 1 — content\_height × scale exceeds the panel height”](#rule-1--content_height--scale-exceeds-the-panel-height) `content_height × scale` must be ≤ the real panel height in pixels. When it exceeds the ceiling, the `ScaledCanvas` wrapper’s vertical offset goes negative and content silently clips at both the top and bottom edges. This is not recoverable at runtime — any section that trips this check will render broken on the panel. Lower `content_height` to `panel_h ÷ scale` (e.g. `content_height = 16` for a bigsign at `scale = 4` and a 64 px tall panel), or lower `scale`. ### Rule 34 — `scroll_speed_ms` set at section level, or `scroll_step_ms` set on a `gif`/`image` widget [Section titled “Rule 34 — scroll\_speed\_ms set at section level, or scroll\_step\_ms set on a gif/image widget”](#rule-34--scroll_speed_ms-set-at-section-level-or-scroll_step_ms-set-on-a-gifimage-widget) These two fields look similar but live at different scopes: * `scroll_step_ms` belongs on the **section** — it controls the engine’s per-tick cursor advance across all widgets in the section. * `scroll_speed_ms` belongs on the **widget** (`gif` / `image`) — it controls the text-marquee cadence inside a single widget’s `play()` loop. Writing `scroll_speed_ms` in a `[[playlist.section]]` block (section scope) silently does nothing — the section loader doesn’t know the field. Writing `scroll_step_ms` on a `gif` or `image` widget passes it as an unknown kwarg that crashes at startup. The validator catches both and points at the correct scope. ### Rule 38 — Unknown field name on a widget [Section titled “Rule 38 — Unknown field name on a widget”](#rule-38--unknown-field-name-on-a-widget) A key in a `[[playlist.section.widget]]` block doesn’t match any field the widget accepts. This previously passed validation and crashed at startup with a raw `TypeError` from attrs internals. The validator now catches it at config-load time and includes a did-you-mean suggestion: ```plaintext ✗ ERROR section[0].widget[0]: widget type='message' got unknown field: 'text_color' (did you mean 'font_color'?) Fix: Remove or rename the field. Run `led-ticker validate --list-fields message` to see valid fields. ``` Common sources: copy-pasting a field name from the wrong widget type (`text_color` instead of `font_color`; `alignement` misspelling of `center`; `scroll_speed_ms` on a non-image widget). Run `led-ticker validate --list-fields TYPE` to see all accepted fields for a given widget type. ### Rule 39 — Unknown transition name [Section titled “Rule 39 — Unknown transition name”](#rule-39--unknown-transition-name) A transition name in `[transitions] default`, `[transitions] between_sections`, or a per-section `transition` / `entry_transition` / `widget_transition` field doesn’t exist in the transition registry. A typo here always crashes at startup, so this check runs even without `--strict`. The error includes a did-you-mean hint when the typo is close to a known name: ```plaintext ✗ ERROR transitions.default: unknown transition 'wipe_alternaiting' (did you mean 'wipe_alternating'?) Fix: Check the transition name spelling. Run `led-ticker validate --list-fields` or see docs.ledticker.dev/transitions/ for the full catalogue. ``` The sentinel value `"cut"` is always accepted. For the full list of available names, see [Transitions](/transitions/). ## Warnings [Section titled “Warnings”](#warnings) Warnings don’t block the engine, but they flag a likely rendering quirk worth resolving. ### Rule 30 — `hold_time` set alongside `bottom_text_loops` [Section titled “Rule 30 — hold\_time set alongside bottom\_text\_loops”](#rule-30--hold_time-set-alongside-bottom_text_loops) When a section has an explicit `hold_time` AND a `two_row` widget with `bottom_text_loops > 0`, the engine uses `max(hold_time_ticks, bottom_text_loops × cycle_width)` to compute section duration — the larger value dominates. Common confusion: a user sets `bottom_text_loops = 3` expecting “exactly 3 loops” but their `hold_time` (say `8.0` at `scroll_step_ms = 35` ≈ 228 ticks) happens to exceed `3 × cycle_width`, and the section runs for 5+ loops instead. The fix depends on intent: for an EXACT loop count, drop `hold_time` from the section so `bottom_text_loops` is the only floor; for a FIXED duration, drop `bottom_text_loops`; if you want both as floors and you understand `max()`, ignore the warning. Rule 30 is scoped to `two_row` only — gif/image widgets handle their own timing inside `play()` and `hold_time` doesn’t reach them, so the same field combination on those widgets is harmless and silent. ### Rule 6 — `two_row` at `scale = 4` collapses the canvas to 64 logical pixels wide [Section titled “Rule 6 — two\_row at scale = 4 collapses the canvas to 64 logical pixels wide”](#rule-6--two_row-at-scale--4-collapses-the-canvas-to-64-logical-pixels-wide) Most handles fit at 64 logical px, but anything longer overflows and the bottom row scrolls unintentionally. Use `scale = 2` (128 logical px) with `content_height ≤ 16`. ### Rule 21 — `transition_duration` is in seconds, not milliseconds [Section titled “Rule 21 — transition\_duration is in seconds, not milliseconds”](#rule-21--transition_duration-is-in-seconds-not-milliseconds) `transition_duration` takes seconds. A value above `5.0` is almost always a unit error (you wrote `800` thinking ms; you wanted `0.8`). The validator flags any duration above 5 s or below 50 ms across `[transitions] default`, `[transitions] between_sections`, and per-section overrides — the fix is to divide by 1000. ### Rule 23 — Held `top_text` is wider than the canvas [Section titled “Rule 23 — Held top\_text is wider than the canvas”](#rule-23--held-top_text-is-wider-than-the-canvas) The top row on a `two_row` widget (and the top row on `gif` / `image` widgets when `bottom_text` is set) is held — it doesn’t scroll. If the rendered text is wider than the logical canvas, the right edge clips silently at runtime. The validator measures the text against the resolved font (including inline `:slug:` emoji) and warns when it would overflow. Shorten the text, drop inline emoji, lower `top_font_size`, or set the section’s `scale` lower to widen the logical canvas (each step from `scale = 4` to `scale = 2` to `scale = 1` doubles the available width). ### Rule 24 — `font` name is unknown [Section titled “Rule 24 — font name is unknown”](#rule-24--font-name-is-unknown) The named font isn’t bundled and didn’t turn up in `config/fonts/`. This is a warning, not an error: a config drafted on a laptop without the brand font is still useful, and the file may live on the Pi by deploy time. The ticker will raise at startup if the section actually runs without the font present, so resolve the warning before deploy. Drop the font file into `config/fonts/` on the deploy target, or pick one of the bundled fonts (BDF: `5x8`, `6x10`, `6x12`, `7x13`; hires: `Inter-Bold`, `Inter-Regular`). ### Rule 35 — `default = "..."` inside a `[[playlist.section]]` is silently ignored [Section titled “Rule 35 — default = "..." inside a \[\[playlist.section\]\] is silently ignored”](#rule-35--default---inside-a-playlistsection-is-silently-ignored) `default` is a key in the `[transitions]` block — it sets the global default transition for all sections. Inside a `[[playlist.section]]` block the equivalent field is `transition`, not `default`. Writing `default = "wipe_left"` inside a section block looks valid to TOML but is silently dropped by the section loader. Rename it to `transition = "wipe_left"` to get the intended per-section override. ## Strict-only checks [Section titled “Strict-only checks”](#strict-only-checks) These checks only run when you pass `--strict` to `led-ticker validate`. Use `--strict` in CI so a warning-clean config is enforced before deploy — all existing warnings are also promoted to errors in strict mode. ### Rule 40 — Asset `path` does not exist on disk [Section titled “Rule 40 — Asset path does not exist on disk”](#rule-40--asset-path-does-not-exist-on-disk) In `--strict` mode, any `path` field on a `gif` or `image` widget must point to a file that exists relative to the config file’s directory. This check is strict-only because the asset may only live on the deploy target (Pi), not on your laptop: ```plaintext ✗ ERROR section[0].widget[0]: asset path 'assets/missing.gif' does not exist (resolved to /home/pi/config/assets/missing.gif) Fix: Check the path is correct relative to the config file. In --strict mode all referenced asset files must be present. ``` Run `validate` without `--strict` during local drafting; switch to `--strict` on the Pi or in CI once all assets are in place. ### Rule 42 — `bulb_size` must be a positive integer [Section titled “Rule 42 — bulb\_size must be a positive integer”](#rule-42--bulb_size-must-be-a-positive-integer) The `bulb_size` field on a `lightbulbs` border must be a positive integer (or omitted to use the panel-size auto-default). **Fix:** Set `bulb_size = 3` (typical bigsign value) or omit the field. ### Rule 43 — `bulb_size` exceeds panel-height ceiling [Section titled “Rule 43 — bulb\_size exceeds panel-height ceiling”](#rule-43--bulb_size-exceeds-panel-height-ceiling) A `lightbulbs` border with `bulb_size > panel_height // 2` would have its top-edge and bottom-edge bulbs overlap. Catches: `bulb_size = 9` on a smallsign-class 16-row panel (max=8). **Fix:** Reduce `bulb_size` to ≤ `panel_height // 2`, or omit it to use the auto-default (3 on big panels, 1 on small). ### Rule 44 — `mode` must be `chase`, `alternate`, or `unison` [Section titled “Rule 44 — mode must be chase, alternate, or unison”](#rule-44--mode-must-be-chase-alternate-or-unison) Typo in the `mode` field, or a mode that doesn’t exist yet. **Fix:** Set `mode` to one of `chase`, `alternate`, or `unison`. ### Rule 45 — `direction` must be `cw` or `ccw` [Section titled “Rule 45 — direction must be cw or ccw”](#rule-45--direction-must-be-cw-or-ccw) The `direction` field on a chase-mode lightbulbs border must be one of those two values. **Fix:** Set `direction = "cw"` (clockwise) or `direction = "ccw"` (counter-clockwise). ### Rule 46 — `chase_density` must be an integer ≥ 1 [Section titled “Rule 46 — chase\_density must be an integer ≥ 1”](#rule-46--chase_density-must-be-an-integer--1) `chase_density = N` means “1 in N bulbs is lit”. Values less than 1 are nonsensical. **Fix:** Set `chase_density` to 1 (every bulb lit), 2 (every other), 3 (every third — classic marquee), etc. ### Rule 47 — `gap` must be ≥ 0 [Section titled “Rule 47 — gap must be ≥ 0”](#rule-47--gap-must-be--0) Negative gaps would cause bulbs to overlap, producing an undefined visual. **Fix:** Set `gap = 0` (bulbs touching) or a positive integer. ### Rule 48 — `chase_density` ignored outside chase mode (warning) [Section titled “Rule 48 — chase\_density ignored outside chase mode (warning)”](#rule-48--chase_density-ignored-outside-chase-mode-warning) `chase_density` only affects the chase animation. Setting it on `mode = "alternate"` or `mode = "unison"` is silently ignored. **Fix:** Either remove `chase_density`, or change `mode` to `chase`. ### Rule 49 — `direction` ignored outside chase mode (warning) [Section titled “Rule 49 — direction ignored outside chase mode (warning)”](#rule-49--direction-ignored-outside-chase-mode-warning) `direction` only affects the chase animation. **Fix:** Either remove `direction`, or change `mode` to `chase`. ### Rule 51 — `hue_wraps` must be a positive number [Section titled “Rule 51 — hue\_wraps must be a positive number”](#rule-51--hue_wraps-must-be-a-positive-number) `hue_wraps` controls how many full hue cycles the rainbow sweeps around the perimeter. Zero or negative values (or non-numeric values) would produce an empty or reversed rainbow with undefined behavior. **Fix:** Set `hue_wraps` to a positive number such as `1.0` (one full cycle) or `2` (two cycles). Omit it to use the default of `1.0`. ### Rule 52 — `hue_wraps` ignored unless `lit_color = "rainbow"` (warning) [Section titled “Rule 52 — hue\_wraps ignored unless lit\_color = "rainbow" (warning)”](#rule-52--hue_wraps-ignored-unless-lit_color--rainbow-warning) `hue_wraps` only affects the rainbow color sweep. When `lit_color` is a fixed color (or absent), `hue_wraps` has no effect and is silently ignored. **Fix:** Either set `lit_color = "rainbow"` to enable the rainbow effect, or remove `hue_wraps`. See also * [tools/validate](/tools/validate/) * [getting-started](/getting-started/) * [transitions](/transitions/) # Plugins > Extend led-ticker with external plugins — widgets, transitions, emojis, fonts, and lifecycle hooks — installed via a requirements file and auto-registered at startup. Plugins extend led-ticker without forking core. A plugin is a small Python package that registers extra **widgets, transitions, color providers, animations, borders, easings, emojis, fonts, or lifecycle hooks** through led-ticker’s public plugin API. The flagship example is the [pool water-temperature widget](https://github.com/JamesAwesome/led-ticker-plugins/tree/main/plugins/pool), which lives in the led-ticker-plugins monorepo and contributes `type = "pool.monitor"`. You don’t need any plugins to run led-ticker — the [built-in widgets](/widgets/) cover most signs. Reach for a plugin when you want something they don’t offer (pool temperatures, a smart-home sensor, a custom feed), and anyone can publish one without changes to core. Plugins can connect anything with an API — sensor values, custom data feeds, brand fonts, lifecycle hooks. The [pool widget](/plugins/available/) shows the pattern: an InfluxDB water-temperature query becomes a rotating display widget wired up in a single `register(api)` call. ## Installing a plugin [Section titled “Installing a plugin”](#installing-a-plugin) No rebuild needed Edit `config/requirements-plugins.txt`, then `docker compose restart` — the change applies on the next start in seconds. No image rebuild needed. **Docker (the primary path)** — edit `config/requirements-plugins.txt` and restart: ```bash # First time: create your plugin manifest from the example cp config/requirements-plugins.example.txt config/requirements-plugins.txt # Add the plugin name, then: docker compose restart ``` `requirements-plugins.txt` is a standard pip requirements file — one package per line. The startup reconcile installs everything listed and removes anything that was removed. Add a plugin by appending its name; remove it by deleting the line. No image rebuild needed. **Zero-terminal alternative:** if you have the [web status UI](/concepts/web-status-ui/) running, the **Store tab** offers a point-and-click install — see [Install from the web UI](#install-from-the-web-ui) below. **Dev / source checkout convenience** — if you also have a local dev checkout (`make dev`), the `led-ticker plugin` CLI subcommands edit the manifest for you: ```bash led-ticker plugin add pool # + line in config/requirements-plugins.txt (no install) led-ticker plugin remove pool # − line docker compose restart # installs/uninstalls on the next start led-ticker plugin install pool # add + pip install now (dev virtualenv only) led-ticker plugin uninstall pool # remove + pip uninstall ``` Note `add` / `remove` only edit a host file, so run them **on the host** from your project root (where `config/` lives) — not inside the container. Don’t reach for `docker compose exec led-ticker led-ticker plugin add …`: the container mounts `./config` read-only, so the write fails. All subcommands resolve a catalog name to a pip source (git or PyPI), or take a raw pip spec (`git+https://…` / a PyPI requirement) like `pip` itself. Run from your project root so the manifest lands in `config/requirements-plugins.txt` (the file the Docker build and startup reconcile read); pass `--config ` for a non-standard layout. See the [CLI reference](/reference/cli/#led-ticker-plugin) for all flags. `led-ticker plugin list` marks each plugin `[declared]` (in the manifest) and `[installed]` (in this environment), so you can confirm what the next restart will include. * On Docker, plugins install at container startup into a persistent `ticker-plugins` volume (separate from the image layer) — the image itself never changes. Installs are **constrained to core’s dependency versions** (a plugin can bring its own new libraries but can’t move a version core pins — a conflict is caught on start and logged, never breaks silently at runtime). * The live `config/requirements-plugins.txt` is gitignored — it’s yours to customize per sign. A fresh clone installs **no** plugins until you create it. Once installed, a plugin registers automatically via its `led_ticker.plugins` entry point — its widget types are available immediately at startup. ### Install from the web UI [Section titled “Install from the web UI”](#install-from-the-web-ui) If you have the [web status UI](/concepts/web-status-ui/) running, the **Store tab** offers a point-and-click alternative for catalog plugins. Open the dashboard, click **Store**, find the plugin you want, and click **Install**. The Store writes `config/requirements-plugins.txt` for you. **A token is required to install or remove.** Browsing the list is open, but clicking Install or Remove requires a valid token — set `LED_TICKER_WEB_TOKEN` in your `.env` (see the [web UI auth docs](/concepts/web-status-ui/#auth)). Without a token the buttons are disabled. **Changes take effect on the next `docker compose restart`** — same as editing the manifest by hand. Once you click Install, the Store shows a “pending restart” banner with a copyable restart command. Run it from your project root when you are ready: ```bash docker compose restart ``` **Removal is blocked while your config still uses the plugin.** If `config.toml` still references any of the plugin’s widget or transition types when you click Remove, the Store tells you which sections they appear in and links to the Config editor to remove them first. Once the config is clean, click Remove again and restart. **Catalog plugins only.** The Store lists only verified catalog plugins from the led-ticker-plugins monorepo. To install a community plugin or a plugin you are developing locally, add it to `config/requirements-plugins.txt` directly (see the CLI section above). ### Changing a plugin’s version or source [Section titled “Changing a plugin’s version or source”](#changing-a-plugins-version-or-source) Editing an **exact PyPI pin** (`led-ticker-pool==0.1.0` → `==0.2.0`) and restarting is enough: the reconcile compares the manifest pin against the installed version and reinstalls in place when they differ. Changing an **unpinned** line, a **range** spec (`>=`, `~=`), or a **git/URL source** (e.g. retargeting `@main` or a moved branch) is *not* reliably detected on a restart — the namespace is unchanged and the reconcile can’t tell whether the upstream source moved, so it leaves the installed copy alone (and logs an INFO saying so). To force a refresh of a non-pinned source, reset the plugin volume (see [reset all plugins](#removing-a-plugin) below). Pinning to a tag or commit SHA avoids this entirely and is recommended for production signs. ### Production deployments [Section titled “Production deployments”](#production-deployments) For a production sign, pin **every** plugin to an immutable tag or commit SHA — not `@main`, a moving branch, or a floating range. A moving source is not re-detected on restart (see [Changing a plugin’s version or source](#changing-a-plugins-version-or-source) above), and an immutable pin makes each deploy reproducible. For example: ```plaintext # config/requirements-plugins.txt (production example) led-ticker-weather==0.3.0 led-ticker-rss==0.2.1 ``` Your `config/requirements-plugins.txt` and `config.toml` are **gitignored and per-sign** — upstream changes never rewrite them for you. When a plugin’s catalog name, package, or a widget/transition `type` changes (a pack consolidation, a rename), reconcile both files on each sign at deploy: the manifest line, and any affected `type = "…"` in the config. Run `led-ticker validate config.toml` to catch a stale type before it reaches the panel. ## Removing a plugin [Section titled “Removing a plugin”](#removing-a-plugin) Delete the line from `config/requirements-plugins.txt` and restart: ```bash led-ticker plugin remove pool docker compose restart ``` The container uninstalls the plugin from the `ticker-plugins` volume on the next start. The manifest is authoritative — anything not listed is removed. Note Before removing a plugin, also remove its widget types from `config.toml`. If `config.toml` still references a plugin’s widgets when the container starts, the reconciler blocks the uninstall (you’ll see a “removal blocked” entry on the status page) and the plugin stays installed. Once you’ve removed the widgets from your config, the next `docker compose restart` will uninstall it cleanly. **To reset all plugins** (reinstall everything from scratch on the next start): ```bash docker compose down -v docker compose up -d ``` `docker compose down -v` stops the stack and removes the project’s named volumes by their real names (e.g. `led-ticker_ticker-plugins`). Running `docker volume rm ticker-plugins` with the bare name will silently fail — Compose prefixes named volumes with the project name. This is also the fix if a plugin volume becomes corrupt or out of sync. Migrating to a plugin pack If plugins you previously installed separately have since merged into a single **pack** — e.g. the homage sprite-trail plugins `led-ticker-nyancat` / `-pokeball` / `-pacman` / `-sailor_moon` are now one `led-ticker-flair` pack — replace the old per-family lines in `requirements-plugins.txt` with the single pack line, then run **`docker compose down -v`** (a plain restart is not enough). A restart leaves the old packages installed: their namespaces are now also provided by the pack, so the reconciler sees them as still-declared and won’t remove them, and the duplicate registration shows up as `namespace already claimed by another plugin` on the status page. `down -v` clears the volume so only the pack is reinstalled. ## Offline / air-gapped installs [Section titled “Offline / air-gapped installs”](#offline--air-gapped-installs) The first `docker compose restart` after adding a plugin needs network access to download it. If your sign runs without internet access, either: * **Pre-seed the volume** by running `docker compose restart` once on a networked machine (or host), then moving the volume data to the air-gapped sign. * **Build a derivative image** that bakes the plugin in: write a small Dockerfile that starts `FROM led-ticker` and adds a `RUN pip install -c /code/constraints-core.txt ` layer with your plugins, build it on a machine with network access, then deploy that image to the air-gapped sign. The `-c /code/constraints-core.txt` flag pins the install to core’s frozen dependency versions, so a baked plugin can’t bump a core-pinned dependency (the same constraint the runtime reconcile applies). One caveat: a PEP 517 build from an sdist runs in an *isolated* build environment that does **not** inherit `-c`, so the constraint only governs the final install resolution — prefer prebuilt wheels and pin to vetted, immutable sources (a tag or commit SHA, not `@main`). ## Relationship to the `[plugins]` config block [Section titled “Relationship to the \[plugins\] config block”](#relationship-to-the-plugins-config-block) These are complementary layers: * **`config/requirements-plugins.txt`** controls what is **installed** (applied at container startup). * The optional **`[plugins]` block** in `config.toml` controls what is **loaded**: `enabled` toggles plugin loading, `disable = ["namespace"]` skips a plugin, and `dir` points at a local-plugin directory. It does not install anything. A plugin must be installed **and** not disabled to be active. ## Writing a plugin [Section titled “Writing a plugin”](#writing-a-plugin) A plugin imports only from `led_ticker.plugin` (the curated public surface) and exposes a `register(api)` function under the `led_ticker.plugins` entry-point group; `api.widget("name")(cls)` registers a namespaced widget (`.`). The full surface — the `register(api)` contract, every registration method, the exported names, and the conventions — is the [Plugin API reference](/plugins/api-reference/). For loader internals, deployment, and known edges, see [`docs/plugin-system.md`](https://github.com/JamesAwesome/led-ticker/blob/main/docs/plugin-system.md). New to it? The four-page [**authoring guide**](/plugins/authoring/01-scaffold/) walks you from an empty `register(api)` to an installed widget plugin, step by step. For a complete real-world example, the [`pool`](https://github.com/JamesAwesome/led-ticker-plugins/tree/main/plugins/pool) package in the led-ticker-plugins monorepo shows the entry point, tests, and packaging end-to-end. ## If something goes wrong [Section titled “If something goes wrong”](#if-something-goes-wrong) * **`'pool.monitor' looks like a plugin widget, but no 'pool' plugin is loaded. Install it with `led-ticker plugin install pool“** at validate/startup → the plugin isn’t installed. The same hint appears for any namespaced name that doesn’t resolve — a transition, border, color provider, or animation. On Docker, run `led-ticker plugin add pool` then `docker compose restart`; from a source checkout, run `led-ticker plugin install pool`. Either way, `led-ticker plugin status` confirms what’s registered. * **A plugin’s widget shows `--`, dim values, or raises at startup** → that’s the plugin’s own runtime/config issue (e.g. pool needs `INFLUXDB_TOKEN`); check the plugin’s README. A plugin that fails to *load* is skipped with a logged error and never crashes the display. ## Available plugins [Section titled “Available plugins”](#available-plugins) See [Available plugins](/plugins/available/) for the current list and a link to each plugin’s repository. # Plugin API reference > The complete public led_ticker.plugin surface — the register(api) contract, every registration method, the exported names, and the authoring conventions. This page is for **developers writing a plugin**. It catalogs the entire public `led_ticker.plugin` surface: the `register(api)` entry point, every registration method, the names you can import, and the conventions a plugin follows. For a guided, build-it-up introduction, start with the [plugin authoring guide](/plugins/authoring/01-scaffold/); come here when you need the exact shape of something. Note A plugin imports **only** from `led_ticker.plugin`. Everything else under `led_ticker` is internal and can change without notice. If a name isn’t on this page, treat it as private. ## The `register(api)` contract [Section titled “The register(api) contract”](#the-registerapi-contract) A plugin is a Python package that exposes a top-level `register(api)` function under the `led_ticker.plugins` [entry-point group](https://packaging.python.org/en/latest/specifications/entry-points/) — an *entry point* is how an installed package advertises a hook other code can discover. The loader finds it, builds a `PluginAPI` bound to your plugin’s **namespace** (the prefix every registered name gets), and calls it: my\_plugin/\_\_init\_\_.py ```python from led_ticker.plugin import PluginAPI def register(api: PluginAPI) -> None: @api.widget("clock") class Clock: def draw(self, canvas, frame): ... ``` pyproject.toml ```toml [project.entry-points."led_ticker.plugins"] my_plugin = "my_plugin:register" ``` Two rules govern every registration: * **Auto-namespacing.** Every name you register is prefixed with your plugin’s namespace — `api.widget("clock")` in the `acme` plugin registers `acme.clock` (written in config as `type = "acme.clock"`). You cannot register a bare name or shadow a built-in. * **Atomic load.** Calls buffer until `register()` returns cleanly. If `register()` raises, the whole plugin is discarded — there is no half-registered state. `API_VERSION` (currently `(1, 1)`) is exported so a plugin can check the surface version it was built against. ## Registration methods [Section titled “Registration methods”](#registration-methods) `PluginAPI` exposes fourteen registration methods. The **decorator** forms register a class; the **call** forms register a value directly. Several examples below draw onto a **canvas** — the pixel grid for the current frame (the [`Canvas`](#exported-names) type, listed under Exported names). ### Visual building blocks [Section titled “Visual building blocks”](#visual-building-blocks) | Method | Form | Registers | | --------------------------- | --------- | ------------------------------------------------------------------------------------------------------ | | `api.widget(name)` | decorator | A [widget](/widgets/) class under `namespace.name` | | `api.transition(name)` | decorator | A [transition](/transitions/) class | | `api.backend(name)` | decorator | A rendering [backend](#backend-authoring) class (selectable as `[display] backend = "namespace.name"`) | | `api.color_provider(style)` | decorator | A [color provider](/concepts/color-providers/) class | | `api.animation(style)` | decorator | An [animation](/concepts/animations/) class | | `api.border(name)` | decorator | A [border effect](/concepts/borders/) class | | `api.source(name)` | decorator | A `DataSource` subclass under `namespace.name` — powers inline `:namespace.name:` value tokens | | `api.easing(name, fn)` | call | An easing function `(float) -> float` | ```python @api.widget("clock") class Clock: def draw(self, canvas, frame): ... @api.transition("swirl") class Swirl: def frame_at(self, t, canvas, outgoing, incoming, **kw): ... @api.backend("telnet") class TelnetBackend: def setup(self): ... def create_canvas(self): ... def swap(self, canvas): ... api.easing("snap", lambda t: 0.0 if t < 0.5 else 1.0) ``` In a transition’s `frame_at`, `t` runs 0 → 1; `outgoing` and `incoming` each have a `.draw(canvas)`; you render the in-between frame onto `canvas`, and the **return value is ignored**. A full walkthrough (building a wipe) is coming in the Extending section. ### Assets [Section titled “Assets”](#assets) | Method | Form | Registers | | ----------------------------- | ---- | -------------------------------------------------------- | | `api.emoji(slug, data)` | call | A low-res 8×8 emoji (`PixelData`) under `namespace.slug` | | `api.hires_emoji(slug, data)` | call | A hi-res emoji (`HiResEmoji`) for scaled-canvas draws | | `api.font(name, path)` | call | A font file; `path` is relative to the plugin root | → Worked example: [Custom emoji](/plugins/extending/custom-emoji/) covers the `PixelData` format, hi-res sprites, and a PNG→pixels recipe. Caution Pair every hi-res emoji with a low-res one. led-ticker keeps two emoji registries: inline `:namespace.slug:` tokens and unscaled (small) canvases resolve only through the **low-res** registry. So register a matching `api.emoji(slug, …)` for each `api.hires_emoji` — a hi-res registration with no low-res counterpart logs a warning at load. ### Lifecycle hooks [Section titled “Lifecycle hooks”](#lifecycle-hooks) | Method | Form | Registers | | --------------------- | ---- | ---------------------------------------------------------------------------- | | `api.overlay(paint)` | call | A `paint(canvas)` run every frame before the hardware swap | | `api.on_startup(fn)` | call | A hook run once after the frame + session exist; receives a `StartupContext` | | `api.on_shutdown(fn)` | call | A hook run best-effort when the run loop exits | Caution Register overlays through `api.overlay` — these are exception-guarded: if your paint function raises, led-ticker disables just that overlay and logs it, rather than letting the error freeze the panel. ## Exported names [Section titled “Exported names”](#exported-names) These are the names you can import from `led_ticker.plugin` — the types you’ll subclass or annotate against. They’re the stable surface, so anything you build on them keeps working as led-ticker evolves. ### Core [Section titled “Core”](#core) | Name | What it is | | ------------------- | ---------------------------------------------------------------------------------------------------------------------- | | `PluginAPI` | The namespace-bound registrar passed to `register(api)` | | `StartupContext` | Frozen dataclass passed to an `on_startup` hook (`frame`, `session`, `config`) | | `ValidationContext` | Geometry passed to `validate_config_warnings` (`scale`, `content_height`, `panel_width`, `panel_height`, `config_dir`) | | `API_VERSION` | `(major, minor)` tuple of the plugin surface version | ### Base classes & protocols [Section titled “Base classes & protocols”](#base-classes--protocols) | Name | What it is | | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | | `Widget` | The widget protocol (a `draw()` or play-style widget) | | `Container` | Monitor/container widget base (cycles a live `feed_stories` list) | | `Updatable` | Protocol for widgets with `async def update(self)` | | `Transition` | The [transition](/transitions/) protocol (`frame_at`) | | `ColorProvider` | The [color-provider](/concepts/color-providers/) protocol (`color_for`) | | `ColorProviderBase` | Base that enforces the `frame_invariant` class attr | | `Animation` | The [animation](/concepts/animations/) protocol (`frame_for`) | | `BorderEffect` | The [border](/concepts/borders/) protocol (`paint`) | | `BorderEffectBase` | Base that enforces the `frame_invariant` class attr | | `DataSource` | Base class for an inline value source — subclass, implement `compute() -> str`, register with `api.source(name)` | | `PolledDataSource` | Base class for async (network-backed) sources — subclass, implement `async def update()`, call `self._set_value(...)` inside it | | `SegmentMessage` | Re-exported single-line message widget (compose stories from it) | | `TwoRowMessage` | Re-exported two-row widget | | `TickerMessage` | Re-exported single-region scrolling message widget (compose/subclass for rich stories) | | `FrameAwareBase` | Base for an animated widget — inherit (with `@attrs.define`) and read effect counters via `self.frame_for(name)`; the engine drives the counters. | ### Data & types [Section titled “Data & types”](#data--types) | Name | What it is | | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `Canvas` | The draw target (`SetPixel`, `width`, `height`) | | `Color` | An rgbmatrix color value | | `ColorTuple` | Type alias `tuple[int, int, int]` for raw RGB | | `DrawResult` | The return shape of a widget `draw()` | | `AnimationFrame` | The return shape of `Animation.frame_for` | | `LensSpec` | Frozen fisheye-lens descriptor an animation returns on `AnimationFrame.lens` (`magnify`, `edge_squeeze`, `profile`); the engine owns the warp math, a plugin ships only the spec | | `PixelData` | `list[(x, y, r, g, b)]` — one tuple per lit pixel of a low-res emoji | | `HiResEmoji` | A hi-res emoji sprite — `pixels` ((x,y,r,g,b) in physical coords), `physical_size`, optional `physical_width` | | `Font` | A resolved font handle | | `HiresFont` | A resolved hi-res font | | `HiresSpec` | Frozen sprite spec for a hi-res transition: `sprite_path` (Path to a gif/webp), `flip_horizontal`, `trail` (`"none"`/`"black"`/`"rainbow"`) | | `RotationSurface` | Offscreen rotation surface for transition authors — construct once per transition instance, snapshot the outgoing on the first frame, blit per frame; re-fire detection via the `t < _last_t` pattern (see below) | | `ScaledCanvas` | The wrapper widgets receive when `default_scale > 1`; use `is_scaled(canvas)` to gate hi-res paths | | `FONT_DEFAULT` | The bundled default BDF font as a ready-to-use `Font` constant | | `FONT_SMALL` | The bundled small BDF font as a ready-to-use `Font` constant | ### Helpers [Section titled “Helpers”](#helpers) | Name | What it is | | -------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `make_color(r, g, b)` | Build a `Color` from RGB components (0–255) | | `make_rotation_surface(canvas)` | Factory for a construct-once `RotationSurface` bound to the canvas’s scale policy — the seam for transition authors; pass the live canvas on each `blit()` call, not just at construction | | `as_color_provider(color)` | Wrap a constant `Color` as a uniform (non-animated) `ColorProvider` — e.g. a widget’s default font color | | `coerce_color_provider(value, context="font_color")` | Parse a TOML color spec (constant `[r,g,b]`; `"rainbow"`/`"color_cycle"`/`"shimmer"`/`"random"`; or `{style=…}` table) into a `ColorProvider`. Use for a plugin’s own color fields. | | `draw_text(canvas, font, text, x, y, color)` | Draw text (inline `:emoji:` included); returns the next x | | `draw_with_emoji(canvas, font, cursor_pos, y, color, text, ...)` | Rich-text renderer accepting a per-char `ColorProvider` (`draw_text` is the simpler form when the color is a single `Color`; both render inline `:emoji:`) | | `count_text_chars(text)` | Count rendered characters in `text`, counting each `:emoji:` token as one (pair with a per-char provider’s `total_chars`) | | `draw_text_per_char(...)` | Lower-level per-character text draw used by data widgets | | `get_text_width(font, text)` | Pixel width of `text` in `font` | | `compute_baseline(font, ...)` | The baseline y for a font | | `compute_cursor(canvas_width, content_width, cursor_pos, padding, center)` | Resolve a start cursor + end padding for content of a given width (centering / overflow math); the second return value is inter-widget spacing for side-by-side mode — if you only need centering, use the first return value | | `resolve_font(name, ...)` | Resolve a font by name (bundled, plugin, or [BDF](/concepts/fonts/)) | | `draw_emoji_at(canvas, slug, x, y)` | Draw a registered emoji at a position | | `measure_emoji_at(canvas, slug)` | Measure a registered emoji | | `colors` | The built-in named-color module | | `format_clock(...)` | Format a time per led-ticker’s clock conventions (12h / 24h presets, or a `strftime` template) | | `run_monitor_loop(widget, interval, ..., register_monitor=True)` | The periodic-refresh loop for a monitor widget; `register_monitor=False` opts out of status-board registration (busy\_light only) | | `spawn_tracked(coro)` | Spawn a tracked background task from a `start()` / hook | | `safe_scale(canvas)` | The canvas’s logical→physical scale (`1` when unscaled) | | `compute_baseline_for_band(font, h, scale)` | Baseline for text within an arbitrary band height (multi-row layouts) | | `measure_width(font, text)` | Logical width of `text` incl. inline `:emoji:` (layout math) | | `resolve_band_heights(...)` | Split a canvas height into row bands (shared with two-row/image) | | `EMOJI_ROW_CAP` | The 8×8 low-res emoji/sprite height — per-row sprite cap for band layouts | | `ENGINE_TICK_MS` | Engine render cadence in milliseconds (50 ms = 20 fps); use for time-based animation math | | `font_line_height_logical(font, scale)` | A font’s logical line height (never hardcode a cell height) | | `unwrap_to_real(canvas)` | The raw underlying real canvas for direct `SetPixel` at native res | | `paint_hires(canvas, callback)` | Unwrap + forward `scale`/`y_offset_real` to a hi-res paint callback | | `is_scaled(canvas)` | `True` if `canvas` is a scaled wrapper — the documented gate for hi-res paths | | `snap_reset(canvas, incoming_bg_color)` | Clear + repaint a transition’s incoming background (hi-res snap helper) | | `render_hires_frame(t, canvas, outgoing, incoming, spec, **kwargs)` | Paint one frame of a hi-res sprite traversing the panel for the given `HiresSpec` (use on a `ScaledCanvas`) | | `SNAP_THRESHOLD` | The transition `t` at which to snap to the incoming frame (call `snap_reset` at/after this) | ### Backend authoring [Section titled “Backend authoring”](#backend-authoring) Register via api.backend(), not register\_backend Plugin authors register a backend with **`api.backend(name)`** from inside their `register(api)` function — it auto-namespaces the registration to `.` (selectable via `[display] backend = "."`) and is cleaned up on reload. `register_backend(name)` is the **built-in** path (used by `headless` / `rgbmatrix`); it registers a bare, un-namespaced name that `reset_plugins()` will not clean up and that could shadow a future built-in. It is listed below for completeness only — do not use it in a plugin. | Name | What it is | | ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `Backend` | The rendering-backend protocol (`setup()`, `create_canvas()`, `swap()`, `brightness()`); `brightness` is buffered before `setup()` and live after | | `BackendNotReadyError` | Raised when a canvas/swap/brightness op is attempted before `setup()` | | `register_backend(name)` | **Internal / built-in use only** (plugin authors use `api.backend()` — it auto-namespaces). Class decorator registering a backend under a bare `name` (selectable via `[display] backend = "name"`) | | `run_backend_conformance(factory)` | Run the importable conformance suite (the hardware-rendering constraints) against backends from `factory` | | `HeadlessBackend` | The shipped software backend (no hardware) — reuse it for tests or as a base for a custom backend | | `HeadlessCanvas` | The canvas produced by `HeadlessBackend`; exposes `get_pixel(x, y)` so a backend can serialize its own pixel state (use to stream/send frames in a custom output backend) | ### Using `FrameAwareBase` for animated effects [Section titled “Using FrameAwareBase for animated effects”](#using-frameawarebase-for-animated-effects) `FrameAwareBase` is the base class for any widget whose color or animation state changes frame-to-frame. Inherit from it (with `@attrs.define`) and call `self.frame_for(name)` to read per-effect counters that the engine drives; the counters advance automatically so your `draw()` doesn’t need to track time itself. `FrameAwareBase` also provides `frames_to_transition_ready()`. The engine calls it at the hold→transition handoff and may extend the hold by up to roughly one second so animated effects can finish at a natural rest point — for example, letting a shimmer sweep reach its pause window before the scene changes, or waiting for a typewriter reveal to finish its last few characters. The method aggregates `frames_to_rest(frame, total_chars)` across the widget’s effects (color providers, animations) and never raises. Widgets with per-region text (such as a two-row layout with different text in each band) override `_effect_total_chars(attr_name)` to supply each effect with the character count it actually renders with; the default uses the widget’s `text` attribute. ### `AnimationFrame.rotation` and `emits_rotation` [Section titled “AnimationFrame.rotation and emits\_rotation”](#animationframerotation-and-emits_rotation) `AnimationFrame` — the return value of `Animation.frame_for` — carries two fields: * **`visible_text: str`** — the slice of the message text to render this tick (used by typewriter). * **`rotation: float`** — a clockwise rotation in degrees to apply to the rendered text this tick. The default is `0.0`, which takes the normal draw path with no rotation. When non-zero, the message widget renders the text into an offscreen surface, rotates that surface around the text block’s center, and composites it back to the canvas. An animation that emits non-zero rotations must also set `emits_rotation = True` as a class attribute. This opt-in marker tells the validator to run rule 63. An animation can instead return a **`LensSpec`** on `AnimationFrame.lens` (default `None`) to pass the scrolling text through a stationary fisheye lens — the engine owns all of the warp math, so a plugin ships only the declarative spec (`magnify`, `edge_squeeze`, `profile`) and sets `emits_lens = True` as a class attribute (the marker for validate rule 64, the lens twin of rule 63’s hi-res-font-at-scale-1 warning). **Scale-1 displays (smallsign):** pairing a rotation-emitting animation with a hi-res font raises a configuration warning. Hi-res text renders at native-pixel resolution and the offscreen rotate path operates at logical resolution — they interact badly. Rule 63 applies only when `scale == 1`; on scaled displays the snapshot architecture described below handles the mismatch. For BDF fonts the rotate path is fully supported at any scale. **Scaled displays (bigsign, `default_scale > 1`):** the rotate path uses a snapshot-artifact architecture. Before the spin begins, the widget renders the full text — including hi-res fonts and hi-res emoji at their correct physical size — into a full-resolution offscreen buffer, then downsamples it to half-physical resolution. That half-resolution artifact is what rotates each tick, so the rotation itself runs at half detail. When the spin settles (`rotation == 0.0`), the widget reverts to the normal full-detail draw path automatically, so the resting state is always sharp. Two behavior notes for plugin animation authors: * **Mid-spin detail:** the artifact renders at half physical resolution during the spin, then sharpens on settle. This is expected and intentional — not a rendering error. * **Animated `font_color` providers freeze during the spin.** The artifact is rendered once and reused for every tick of the spin — so a rainbow or color\_cycle sweep that was moving before the spin appears frozen mid-rotation. The provider’s live phase is tracked separately throughout; on settle the widget returns to the live path and colors resume exactly where the phase clock left them. For most spin durations (under two seconds) this is imperceptible; for longer spins, consider a constant color (`font_color = [r, g, b]`) — every animated provider (rainbow, color\_cycle, shimmer) freezes the same way. ```python from led_ticker.plugin import Animation, AnimationFrame @api.animation("spin") class SpinAnimation: emits_rotation = True def frame_for(self, frame: int, full_text: str, canvas_width: int, text_width: int) -> AnimationFrame: degrees = (frame * 6) % 360 # one full revolution every 60 ticks (3 s at 20 fps) return AnimationFrame(visible_text=full_text, rotation=float(degrees)) ``` For time-based math in animation classes, `ENGINE_TICK_MS` (importable from `led_ticker.plugin`, listed in the [Helpers table](#helpers)) gives the engine’s render cadence — 50 ms per tick — so you can convert a desired rotation speed in degrees/second to a per-tick increment without hardcoding the cadence. **Transition authors** can reuse the same rotation machinery via `make_rotation_surface` and `RotationSurface` (both in the [Data & types table](#data--types) and [Helpers table](#helpers)): construct a surface once per transition instance, snapshot the outgoing into it on the first frame (`t < _last_t` detects a new firing and triggers `surface.invalidate()` so the snapshot is rebuilt fresh), then call `surface.blit(canvas, angle, canvas.width / 2)` on every subsequent frame — the snapshot is drawn exactly once per firing, and the per-frame blit operates on the cheaper half-resolution artifact on scaled displays (at scale 1 it blits the full buffer directly). Configuring a plugin backend Plugin backends can’t read custom `[display]` fields yet — `DisplayConfig` has a fixed field set, so any unrecognized key is ignored. Pass backend config (host, port, …) via **environment variables** for now. See [`docs/plugin-system.md` §12](https://github.com/JamesAwesome/led-ticker/blob/main/docs/plugin-system.md) and the planned `[display.]` follow-up. ## Conventions [Section titled “Conventions”](#conventions) A few behaviors are **conventions** the type carries, not `api.*` calls: * **`validate_config`** — a widget may define `@classmethod validate_config(cls, cfg) -> list[str]`. It’s called during config validation with the raw (pre-coercion) TOML for that widget; any returned strings become pre-flight errors. The rule travels with the widget type. * **`validate_config_warnings`** — a widget may define `@classmethod validate_config_warnings(cls, cfg: dict[str, Any], ctx: ValidationContext) -> list[str]`. Like `validate_config`, it runs at config-validation time with raw pre-coercion config; but the returned strings surface as **warnings** via `led-ticker validate` — they are never errors and never block the display from loading. The hook receives display geometry via `ValidationContext` (`scale`, `content_height`, `panel_width`, `panel_height`, `config_dir`), making it suitable for checks like “this font size may clip on a 16-tall canvas at scale=4”. A hook that raises is isolated (logged at WARNING level, then ignored). Available from core API `(1, 1)`. If your plugin must also run on older cores, guard registration with `if API_VERSION >= (1, 1):`. * **`font_color` injection** — to accept the standard `font_color` color-provider knob, declare a `font_color: object = None` field on the widget; the loader coerces the TOML value to a `ColorProvider` and injects it. Without the field, `font_color` is rejected as unknown. * **`frame_invariant`** — `ColorProviderBase` / `BorderEffectBase` require subclasses to set a `frame_invariant: bool` class attr. `True` means output never varies by frame (enables a static fast path); `False` forces a per-tick redraw. * **`restart_on_visit`** — a color provider or border may set `restart_on_visit = False` to keep a continuous animation phase across a section’s `loop_count`, instead of resetting on each visit. * **`should_display`** — a widget may define `def should_display(self) -> bool`. The engine calls it once per section pass; returning `False` removes the widget from that pass (it is re-evaluated on the next pass). Absent → always shown. A `should_display` that raises keeps the widget — a visibility check must never crash the render loop. Use it to gate a widget on a runtime condition: the built-in `countdown` / `countup` widgets hide while their day count is negative; a custom widget could show only during certain hours. ## Where to next [Section titled “Where to next”](#where-to-next) * **Build one step by step:** the [plugin authoring guide](/plugins/authoring/01-scaffold/) walks from scaffold to a packaged widget. * **Loader internals & edge cases:** [`docs/plugin-system.md`](https://github.com/JamesAwesome/led-ticker/blob/main/docs/plugin-system.md) covers discovery, the `[plugins]` config block, deployment, and known surface gaps. * **The surfaces you’ll extend:** [widgets](/widgets/), [transitions](/transitions/), [color providers](/concepts/color-providers/), [animations](/concepts/animations/), [borders](/concepts/borders/). See also * [plugins/authoring/01-scaffold](/plugins/authoring/01-scaffold/) * [plugins](/plugins/) * [concepts/color-providers](/concepts/color-providers/) # Authoring 1: Scaffold & register > Create a led-ticker plugin that loads — the register(api) entry point, the two discovery channels, and how to verify it.  What you'll build: example.counter — a widget that counts the days since a date, here DAY 2346 in icy cyan. A **plugin** is a small Python package that adds widgets (and more) to led-ticker without changing core. Over these four pages you’ll build one — `example.counter`, a deliberately tiny widget that shows the number of days since a date (no data, no async; real plugins like the [pool widget](/plugins/available/) fetch live data and render richer screens) — then survey everything else you can contribute. A plugin is just a module that exposes a `register(api)` function. led-ticker calls it once at startup and hands you an `api` object; you call methods on it to register your contributions. ## Prerequisites [Section titled “Prerequisites”](#prerequisites) You’ll work inside a led-ticker checkout: * Clone it and run `make dev` — this creates a local `.venv/` (nothing installed globally) and puts the `led-ticker` command on its `PATH`. * Your plugins live in `config/plugins/`, next to `config/config.toml`. * To run `led-ticker plugins` (below): with that venv active, run `led-ticker plugins` directly; under Docker, run `docker compose exec led-ticker led-ticker plugins`. ## The smallest plugin that loads [Section titled “The smallest plugin that loads”](#the-smallest-plugin-that-loads) 1. Create a file for your plugin. A plugin can be a single `.py` file or a package directory: ```plaintext example/ __init__.py ``` 2. Add a `register(api)` that does nothing yet: example/\_\_init\_\_.py ```python def register(api): pass ``` ## Make led-ticker discover it [Section titled “Make led-ticker discover it”](#make-led-ticker-discover-it) * Local (drop-in) Put the file under your config’s plugins directory (default `config/plugins/`): ```plaintext config/plugins/example/__init__.py ``` The plugin’s **namespace** is its file/dir name — here, `example`. * Packaged (entry point) Ship it as an installable package declaring a `led_ticker.plugins` entry point (covered in [Package & install](/plugins/authoring/03-package/)): ```toml [project.entry-points."led_ticker.plugins"] example = "example:register" ``` The entry-point **name** (`example`) is the namespace. ## Verify it loads [Section titled “Verify it loads”](#verify-it-loads) Run: ```bash led-ticker plugins ``` Your `example` namespace should appear in the list (with no contributions yet). ## Namespaces [Section titled “Namespaces”](#namespaces) Everything a plugin registers is namespaced by `.`, so plugins never collide with core or each other. The widget you build next, registered as `counter`, becomes `example.counter` in config — `type = "example.counter"`. API version The plugin API is versioned (`API_VERSION`, currently `1.0`). A plugin can declare the major version it needs with a module-level `requires_api = 1`; led-ticker skips (and logs) a plugin that needs a newer API than it provides. Import only the public surface Import only from `led_ticker.plugin` (plus `attrs` and the standard library). Anything else under `led_ticker.*` is private and may change without notice. Also: no `from __future__ import annotations` in plugin source — led-ticker runs on Python 3.14 (PEP 649) and the linter rejects it. [Continue the tutorial: Authoring 2: Build the widget →](/plugins/authoring/02-widget/) # Authoring 2: Build the widget > Register a widget, declare its config fields, implement draw(), and validate config — the full Counter widget. Now make `example.counter` real. A widget is a class registered with `api.widget`, carrying its config as fields and rendering with a `draw()` method. Follow along with the finished file The complete widget is [`examples/plugins/example/__init__.py`](https://github.com/JamesAwesome/led-ticker/blob/main/examples/plugins/example/__init__.py) (\~40 lines). Open it alongside this page — each section below is one piece of that file, and the whole thing is reproduced at the bottom. ## Register a widget class [Section titled “Register a widget class”](#register-a-widget-class) `api.widget(name)` is a decorator. Pair it with `@attrs.define` so led-ticker can inspect your config fields: ```python import attrs from led_ticker.plugin import Color, draw_text, make_color, resolve_font def register(api): @api.widget("counter") @attrs.define class Counter: since: str label: str = "DAY" color: Color | None = None bg_color: Color | None = None ``` `attrs` is a small library for declarative classes; it ships with led-ticker (no separate install), and `@attrs.define` is what lets the loader read your field names and defaults to build the widget from TOML. The class lives inside `register()` so the `api` object is in scope when the `@api.widget` decorator runs — treat the `def register(api):` wrapper as boilerplate every plugin has. Each field is a config key. In TOML: ```toml [[playlist.section.widget]] type = "example.counter" since = "2024-01-01" label = "DAY" color = [130, 220, 255] bg_color = [10, 10, 40] ``` That `[[playlist.section.widget]]` block goes inside a playlist section in your `config.toml` — see [Your first config](/tutorial/02-first-config/) for the surrounding structure. Color fields are coerced for you `color` is a known color key, so led-ticker converts an `[r, g, b]` list into a `Color` object before constructing your widget — `self.color` is already a `Color` (or `None`). `bg_color` works the same way. `font_color` — the standard text-color key — is different: it coerces to a *color provider*, an object with a `color_for(...)` method that can yield a constant color, a rainbow, a gradient, and more. So a widget that declares a `font_color` field reads `self.font_color.color_for(...)` rather than treating it as a plain `Color`. See [Color providers](/concepts/color-providers/) for the full list and how config maps to each. ## Implement `draw()` [Section titled “Implement draw()”](#implement-draw) `draw()` paints one frame and returns `(canvas, end_x)` — the canvas and the x-coordinate where your content ends (so the engine can chain widgets). A `canvas` is the display surface the engine hands your widget for this frame — you paint onto it (here via `draw_text`) and return it unchanged. ```python def draw(self, canvas, cursor_pos=0, *, y_offset=0, font_color=None): if self.bg_color is not None: canvas.Fill(self.bg_color.red, self.bg_color.green, self.bg_color.blue) font = resolve_font("6x12") color = self.color if self.color is not None else make_color(255, 255, 255) text = f"{self.label} {self._days()}" end_x = draw_text(canvas, font, text, cursor_pos, 10 + y_offset, color) return canvas, end_x ``` The helpers all come from `led_ticker.plugin`: * `resolve_font("6x12")` — a bundled BDF font (or a hi-res name + size). * `make_color(r, g, b)` — a `Color` without importing the matrix library. * `draw_text(canvas, font, text, x, y, color)` — draws text (with inline emoji support) and returns the end-x. To paint a **background**, call the canvas’s own `canvas.Fill(r, g, b)` before your text. `bg_color` is a raw `Color`, so `self.bg_color.red` / `.green` / `.blue` give the channels (that’s the `bg_color = [10, 10, 40]` in the TOML above). Leave `bg_color` unset and the widget just draws over whatever’s already on the canvas. cursor\_pos and font\_color `cursor_pos` is the x position the engine gives this widget’s slot — pass it straight to `draw_text` as the x argument (drawing at a hardcoded `0` breaks scrolling). The `y` argument to `draw_text` is the text *baseline* — `10` seats a 6×12 line on a 16-row panel; use a larger value on taller panels. `font_color` is an optional per-frame color the engine may inject (e.g. a color provider); honor it when your widget should follow a theme. This widget uses its own `color` field instead. ### Rich text: per-character animated colors [Section titled “Rich text: per-character animated colors”](#rich-text-per-character-animated-colors) `draw_text` already renders inline `:emoji:`, but it takes only a flat `Color`. When your widget should give text **per-character animated colors** (rainbow, gradient, shimmer) — as data widgets like the pool monitor do — reach for `draw_with_emoji`, which accepts a `ColorProvider`: ```python from led_ticker.plugin import ( as_color_provider, count_text_chars, draw_with_emoji, make_color, ) # Your widget receives font_color as a ColorProvider (or None). # as_color_provider wraps a fallback Color so you always have a provider: provider = font_color if font_color is not None else as_color_provider(make_color(255, 255, 255)) text = f"TEMP {value}°" total = count_text_chars(text) # counts `:slug:` tokens as one char each end_x = draw_with_emoji(canvas, font, cursor_pos, y, provider, text, frame=self.frame_for("font_color"), total_chars=total) ``` Reach for `draw_with_emoji` over `draw_text` purely when the color is a `ColorProvider` rather than a flat `Color` — both render inline emoji identically. `count_text_chars` measures the total — pair it with the provider’s `total_chars` argument so a rainbow sweeps correctly across any inline emoji in the string. For named color constants (`RED`, `DEFAULT_COLOR`, `RGB_WHITE`, …) use `led_ticker.plugin.colors`: ```python from led_ticker.plugin import colors color = colors.RED ``` Full table: [API reference → Helpers](/plugins/api-reference/#helpers). The `_days()` helper is plain Python: ```python import datetime as _dt # ... def _days(self): return (_dt.date.today() - _dt.date.fromisoformat(self.since)).days ``` ## Validate config [Section titled “Validate config”](#validate-config) Add a `validate_config` classmethod to reject bad config *before* the sign runs (it shows up in `led-ticker validate`). It receives the raw, pre-coercion config and returns a list of error strings: ```python @classmethod def validate_config(cls, cfg): errors = [] since = cfg.get("since") if since is None: errors.append("since is required (a YYYY-MM-DD date)") else: try: start = _dt.date.fromisoformat(str(since)) except ValueError: errors.append(f"since must be a YYYY-MM-DD date; got {since!r}") else: if start > _dt.date.today(): errors.append(f"since must not be in the future; got {since!r}") return errors ``` ## The complete widget [Section titled “The complete widget”](#the-complete-widget) Assembled, that’s the whole plugin — drop it in `config/plugins/example/__init__.py` (or package it, next page): ```python """Minimal example led-ticker plugin — the worked example for the authoring guide. Drop `example/` into your `config/plugins/` (local use), or package it with an `[project.entry-points."led_ticker.plugins"] example = "example:register"` entry (packaged use), then reference it in TOML as `type = "example.counter"`. Imports only `led_ticker.plugin` (the public surface) plus `attrs` and stdlib — never a private `led_ticker.*` module. """ import datetime as _dt import attrs from led_ticker.plugin import Color, draw_text, make_color, resolve_font def register(api): @api.widget("counter") @attrs.define class Counter: """Shows whole days since a configured date, e.g. ``DAY 42``.""" # Config fields. The loader builds the widget from your TOML, passing # declared keys as constructor kwargs; `@attrs.define` lets it inspect them. since: str # required — a YYYY-MM-DD date (validate_config enforces it) label: str = "DAY" # `color` is a known color key: the loader coerces an [r, g, b] list in # TOML into a Color before your widget sees it (None = default white). color: Color | None = None # `bg_color` is also a raw color key. Paint it behind the text with the # canvas's own Fill() (None = leave the background untouched). bg_color: Color | None = None @classmethod def validate_config(cls, cfg): """Pre-coercion config check; return a list of human-readable errors.""" errors = [] since = cfg.get("since") if since is None: errors.append("since is required (a YYYY-MM-DD date)") else: try: start = _dt.date.fromisoformat(str(since)) except ValueError: errors.append(f"since must be a YYYY-MM-DD date; got {since!r}") else: if start > _dt.date.today(): errors.append(f"since must not be in the future; got {since!r}") return errors def _days(self): return (_dt.date.today() - _dt.date.fromisoformat(self.since)).days def draw(self, canvas, cursor_pos=0, *, y_offset=0, font_color=None): """Render ` ` onto the canvas; return (canvas, end_x).""" if self.bg_color is not None: canvas.Fill(self.bg_color.red, self.bg_color.green, self.bg_color.blue) font = resolve_font("6x12") color = self.color if self.color is not None else make_color(255, 255, 255) text = f"{self.label} {self._days()}" end_x = draw_text(canvas, font, text, cursor_pos, 10 + y_offset, color) return canvas, end_x ``` ## See it run [Section titled “See it run”](#see-it-run) You don’t need hardware to check your work — the [test in the next chapter](/plugins/authoring/03-package/) drives `draw()` directly, and once the plugin is packaged you can render a preview GIF (next page). That preview is how the `DAY 2346` panel at the top of the guide was made. [← Back to Authoring 1: Scaffold & register](/plugins/authoring/01-scaffold/) [Continue the tutorial: Authoring 3: Package & install →](/plugins/authoring/03-package/) # Authoring 3: Package & install > Turn a local plugin into an installable package, add it to a sign, and test it locally. A local `config/plugins/` file is great while you iterate. To share a plugin or deploy it to a sign, package it. ## Declare an entry point [Section titled “Declare an entry point”](#declare-an-entry-point) A packaged plugin is a small project directory — the `pyproject.toml` sits next to your package (not inside `config/plugins/`): ```plaintext led-ticker-example/ ├── pyproject.toml ├── example/ │ └── __init__.py # your register(api) + widget └── tests/ ├── conftest.py └── test_example.py ``` Add a `pyproject.toml` next to your package and expose `register` under the `led_ticker.plugins` group. An **entry point** is metadata Python’s packaging records in an installed package; led-ticker reads it at startup (via `importlib.metadata`) to discover plugins with no manual list: ```toml [project] name = "led-ticker-example" version = "0.1.0" dependencies = ["led-ticker"] [project.entry-points."led_ticker.plugins"] example = "example:register" [build-system] requires = ["hatchling"] build-backend = "hatchling.build" ``` Once the package is installed, led-ticker discovers it automatically — no config change needed. ## Install it on a sign [Section titled “Install it on a sign”](#install-it-on-a-sign) Add the package to your led-ticker checkout’s `config/requirements-plugins.txt` and restart. A startup reconcile makes the installed plugins match the file — no image rebuild. The install flow (the constraint-based install, the gitignored live file) is covered on the [Plugins overview](/plugins/) — in short: ```bash cp config/requirements-plugins.example.txt config/requirements-plugins.txt # add a line for your package (a PyPI name, or a git URL), then: docker compose restart ``` led-ticker isn't on PyPI Plugins install alongside core’s pinned dependencies — a plugin can add its own libraries but can’t move a version core already pins. Because led-ticker is already in the image, your `dependencies = ["led-ticker"]` resolves without a PyPI fetch. See the [Plugins overview](/plugins/) for the details. ## Test it locally [Section titled “Test it locally”](#test-it-locally) You don’t need hardware — led-ticker ships a headless graphics stub. Here’s a minimal test that loads your plugin and draws once; it’s how the bundled example is tested (`tests/test_plugins/test_example_plugin.py`): ```python import shutil from pathlib import Path from led_ticker import _plugin_loader as L # internal loader — fine in tests; plugin code never imports it from led_ticker.widgets import get_widget_class # `tmp_path` is a throwaway directory pytest creates per test; `canvas` is the # stub canvas fixture (defined below). def test_counter_draws(tmp_path, canvas): L.reset_plugins() # clear any plugins a previous test left registered pdir = tmp_path / "plugins" pdir.mkdir() # shutil.copytree recursively copies a directory tree; here it drops the # plugin package into a temp plugins/ dir so the loader can discover it. shutil.copytree(Path("examples/plugins/example"), pdir / "example") L.load_plugins(pdir, entry_points_enabled=False) # load from that dir (not installed packages) widget = get_widget_class("example.counter")(since="2020-01-01") # look up the class, build one out, end_x = widget.draw(canvas) # render a single frame onto the stub canvas assert out is canvas L.reset_plugins() # leave the registry clean for the next test ``` For a plugin in its **own** repo, point `copytree` at your own package directory instead, and add the `canvas` fixture to your `conftest.py` (the [`pool`](https://github.com/JamesAwesome/led-ticker-plugins/tree/main/plugins/pool) package does exactly this): ```python # conftest.py — pytest auto-discovers fixtures defined in this file import unittest.mock as mock import pytest @pytest.fixture def canvas(): # draw() only calls methods on the canvas, so a Mock with width/height is # enough to exercise it off-hardware (no real LED matrix needed). c = mock.Mock() c.width = 160 c.height = 16 return c ``` ### Preview it as a GIF (no hardware) [Section titled “Preview it as a GIF (no hardware)”](#preview-it-as-a-gif-no-hardware) `render-demo` runs the real engine, so it only renders *installed* plugins — a local `config/plugins/` drop-in isn’t picked up. While iterating, an editable install is the fast path. First, a tiny config that uses your widget — save it as `preview.toml`: ```toml [display] rows = 16 cols = 32 chain_length = 2 [[playlist.section]] mode = "slideshow" loop_count = 1 hold_time = 3 [[playlist.section.widget]] type = "example.counter" since = "2020-01-01" label = "DAY" color = [130, 220, 255] bg_color = [10, 10, 40] ``` Then install your plugin and render it — no hardware required (run these in the same venv `make dev` created): ```bash pip install -e . # once, from your plugin directory (uses your pyproject.toml above) make render-demo CONFIG=preview.toml OUT=preview.gif # preview.gif lands in your working directory ``` `render-demo` discovers your plugin through its entry point and renders the config straight to a GIF. ## A real packaged plugin [Section titled “A real packaged plugin”](#a-real-packaged-plugin) The [`pool`](https://github.com/JamesAwesome/led-ticker-plugins/tree/main/plugins/pool) package in the led-ticker-plugins monorepo is a complete, published example: a data-fetching widget with its own `pyproject.toml`, CI, and tests. Read it when you’re ready to ship something real. Its widget is `example.counter` grown up: swap the date math for an API call and a couple of screens and you have a live data widget. [← Back to Authoring 2: Build the widget](/plugins/authoring/02-widget/) [Continue the tutorial: Authoring 4: Beyond widgets →](/plugins/authoring/04-beyond-widgets/) # Authoring 4: Beyond widgets > A map of the other plugin surfaces — transitions, color providers, animations, borders, easings, emoji, fonts, and lifecycle hooks. Widgets are the most common contribution, but `api` registers a lot more. Each call below namespaces under your plugin (`example.`). The reference plugin [`examples/plugins/acme/`](https://github.com/JamesAwesome/led-ticker/blob/main/examples/plugins/acme/__init__.py) exercises every one of these in \~100 lines; the full contracts are in [`plugin-system.md`](https://github.com/JamesAwesome/led-ticker/blob/main/docs/plugin-system.md). ## Render surfaces (decorate a class) [Section titled “Render surfaces (decorate a class)”](#render-surfaces-decorate-a-class) ```python @api.transition("swoosh") # a Transition: frame_at(t, canvas, outgoing, incoming) @api.color_provider("fire") # a ColorProvider: color_for(frame, char_index, total) @api.animation("scramble") # an Animation: frame_for(frame, text, width, text_width) @api.border("neon") # a BorderEffect: paint(canvas, frame_count) ``` Subclass the matching base (`ColorProviderBase`, `BorderEffectBase`) or implement the protocol; reference them in TOML as `transition = {type = "example.swoosh"}`, `font_color = {style = "example.fire"}`, etc. Writing a transition? See the [Writing a transition](/plugins/extending/writing-a-transition/) how-to — the `frame_at` contract and a worked wipe. Writing a color provider? See the [Custom color provider](/plugins/extending/custom-color-provider/) how-to — the `color_for` contract and a worked animated pulse. ## Value surfaces (pass data directly) [Section titled “Value surfaces (pass data directly)”](#value-surfaces-pass-data-directly) ```python api.easing("snap", lambda p: p * p) # an easing curve (0..1 -> 0..1) api.emoji("spark", [(x, y, r, g, b), ...]) # 8x8 emoji: one (x, y, r, g, b) tuple per lit pixel; use as :example.spark: api.hires_emoji("spark", HiResEmoji(...)) # hi-res variant (pair it with a low-res one) api.font("Brand", "fonts/Brand.ttf") # a bundled font file, usable as font = "example.Brand" ``` Adding your own emoji? See the [Custom emoji](/plugins/extending/custom-emoji/) how-to for the `PixelData` format, low-res vs hi-res sprites, and a PNG→pixels recipe. ## Lifecycle hooks (the “service plugin” pattern) [Section titled “Lifecycle hooks (the “service plugin” pattern)”](#lifecycle-hooks-the-service-plugin-pattern) Hooks let a plugin run code around the display loop — for example, poll an API in the background and paint a status dot over every frame: ```python api.overlay(paint) # paint(canvas) runs every frame; if it raises, the engine logs it (no crash) api.on_startup(on_startup) # on_startup(ctx: StartupContext) runs once before the loop (sync or async) api.on_shutdown(cleanup) # runs once at exit ``` Start background work with `spawn_tracked(coro)` from inside `on_startup`, and have your overlay paint whatever shared state it updates. Building a background service? See the [Service plugins](/plugins/extending/service-plugins/) how-to — an `on_startup` poller plus a status overlay. Copy the example The fastest way to add any of these is to copy the relevant block out of [`acme/__init__.py`](https://github.com/JamesAwesome/led-ticker/blob/main/examples/plugins/acme/__init__.py) and renamespace it. For the precise contracts, return types, and edge cases, see [`plugin-system.md`](https://github.com/JamesAwesome/led-ticker/blob/main/docs/plugin-system.md). ## Going further: a live data widget [Section titled “Going further: a live data widget”](#going-further-a-live-data-widget) The counter is static. Real widgets fetch data on a schedule and render the latest value — what the [pool widget](/plugins/available/) does. The pattern: poll in a startup hook, stash the result, read it in `draw()`: ```python import asyncio import aiohttp import attrs from led_ticker.plugin import draw_text, make_color, resolve_font, spawn_tracked _state = {"value": "—"} # shared: the poller writes it, draw() reads it def register(api): @api.widget("sensor") @attrs.define class Sensor: def draw(self, canvas, cursor_pos=0, *, y_offset=0, font_color=None): font = resolve_font("6x12") # just render whatever the poller last stored — draw() never blocks end_x = draw_text( canvas, font, _state["value"], cursor_pos, 10 + y_offset, make_color(255, 255, 255) ) return canvas, end_x async def _poll(): async with aiohttp.ClientSession() as session: # one reusable HTTP session while True: # runs forever in the background async with session.get("https://api.example.com/v1/value") as resp: _state["value"] = str((await resp.json())["value"]) # stash the latest reading await asyncio.sleep(60) # pause 60s (yields to the display loop) before refetching # on_startup runs once before the display loop; spawn_tracked launches the poller # as a background task (use it instead of asyncio.create_task — the engine keeps a # reference so the task isn't garbage-collected and logs it if it crashes). api.on_startup(lambda ctx: spawn_tracked(_poll())) ``` `spawn_tracked` keeps the background task alive; `on_startup` runs it once before the display loop. See [`acme`](https://github.com/JamesAwesome/led-ticker/blob/main/examples/plugins/acme/__init__.py) for a runnable version and the [`pool`](https://github.com/JamesAwesome/led-ticker-plugins/tree/main/plugins/pool) package for a production one. That’s the whole surface. Build something and [add it to the directory](/plugins/available/). [← Back to Authoring 3: Package & install](/plugins/authoring/03-package/) # Available plugins > First-party and community led-ticker plugins, and the repositories where they live. The first-party plugins live in the **[led-ticker-plugins](https://github.com/JamesAwesome/led-ticker-plugins)** monorepo — one package per plugin. To use one, add its install line to `config/requirements-plugins.txt` and run `docker compose restart` — a PyPI name like `led-ticker-pool` for the published data plugins, or a `git+https` line for the homage sprite-trail transitions (not on PyPI). See [Plugins](/plugins/) for the install flow; each plugin’s own README documents its options, layouts, and setup. ## Widgets [Section titled “Widgets”](#widgets) ### [pool](https://github.com/JamesAwesome/led-ticker-plugins/tree/main/plugins/pool) [Section titled “pool”](#pool) Pool water-temperature widget (`type = "pool.monitor"`), backed by an InfluxDB v2 server. Cycles a title card, today’s temperature, 7-day mean, and season hi/lo with zone coloring; supports `ticker` and `two_row` layouts. Full docs, options, and screenshots in the [repo README](https://github.com/JamesAwesome/led-ticker-plugins/blob/main/plugins/pool/README.md). * **Widgets:** pool.monitor Add to your `config/requirements-plugins.txt`: ```text led-ticker-pool ``` ### [baseball](https://github.com/JamesAwesome/led-ticker-plugins/tree/main/plugins/baseball) [Section titled “baseball”](#baseball) Five MLB widgets, backed by MLB’s free StatsAPI (no key required): scores (`type = "baseball.scores"`), standings (`type = "baseball.standings"`), home-game promotions/theme nights (`type = "baseball.promotions"`), Statcast superlatives — longest homer, hardest-hit ball, fastest pitch (`type = "baseball.statcast"`), and ballpark attendance with fill % (`type = "baseball.attendance"`). Also ships the `baseball.roll` / `baseball.roll_reverse` / `baseball.roll_alternating` rolling-ball sprite transition and the `:baseball.ball:` emoji. Full docs, options, and screenshots in the [repo README](https://github.com/JamesAwesome/led-ticker-plugins/blob/main/plugins/baseball/README.md). * **Widgets:** baseball.scores, baseball.standings, baseball.promotions, baseball.statcast, baseball.attendance * **Transitions:** baseball.roll, baseball.roll\_reverse, baseball.roll\_alternating * **Emoji:** :baseball.ball: Add to your `config/requirements-plugins.txt`: ```text led-ticker-baseball ``` ### [crypto](https://github.com/JamesAwesome/led-ticker-plugins/tree/main/plugins/crypto) [Section titled “crypto”](#crypto) Multi-coin CoinGecko price ticker (`type = "crypto.coingecko"`). Cycles one ticker card per coin, pulling live spot prices from the [CoinGecko API](https://www.coingecko.com/en/api). Three coin-spec styles: a single `symbol` + `symbol_id` pair, a `symbol_ids = [...]` list, or a `symbols = [...]` list that auto-resolves to unique CoinGecko IDs (raises an error if a symbol is ambiguous — set `symbol_id`/`symbol_ids` to disambiguate). Prices below $0.01 format with adaptive sub-cent precision. Keyless free tier is rate-limited to \~5 requests/min; add `api_key = "..."` (or set `COINGECKO_API_KEY`) to use a [CoinGecko demo key](https://www.coingecko.com/en/api/pricing) for a higher limit. See the [crypto.coingecko widget page](/widgets/crypto-coingecko/) for an overview, or the [repo README](https://github.com/JamesAwesome/led-ticker-plugins/blob/main/plugins/crypto/README.md) for the full options reference. * **Widgets:** crypto.coingecko Add to your `config/requirements-plugins.txt`: ```text led-ticker-crypto ``` ### [calendar](https://github.com/JamesAwesome/led-ticker-plugins/tree/main/plugins/calendar) [Section titled “calendar”](#calendar) Calendar (.ics) widget (`type = "calendar.events"`). Pulls upcoming events from any subscribed iCal feed (Google / iCloud / Outlook) and shows them as a rotating `agenda`, a live `next`-event countdown, or a held-top `two_row` card, with keyword `filter`/`highlight` and two-tone day/time coloring. Full docs, options, and screenshots in the [repo README](https://github.com/JamesAwesome/led-ticker-plugins/blob/main/plugins/calendar/README.md). * **Widgets:** calendar.events Add to your `config/requirements-plugins.txt`: ```text led-ticker-calendar ``` ### [rss](https://github.com/JamesAwesome/led-ticker-plugins/tree/main/plugins/rss) [Section titled “rss”](#rss) RSS/Atom headline widget (`type = "rss.feed"`). Fetches a remote feed and turns each headline into its own scrolling line in the section. Polls in the background with retry/backoff. Full docs, options, and screenshots in the [repo README](https://github.com/JamesAwesome/led-ticker-plugins/blob/main/plugins/rss/README.md). * **Widgets:** rss.feed Add to your `config/requirements-plugins.txt`: ```text led-ticker-rss ``` ### [weather](https://github.com/JamesAwesome/led-ticker-plugins/tree/main/plugins/weather) [Section titled “weather”](#weather) Current-conditions widget (`type = "weather.current"`) that shows temperature and a pixel-art condition icon from WeatherAPI.com (needs a free `WEATHERAPI_KEY`). Polls in the background with retry/backoff. Full docs, options, and screenshots in the [repo README](https://github.com/JamesAwesome/led-ticker-plugins/blob/main/plugins/weather/README.md). * **Widgets:** weather.current Add to your `config/requirements-plugins.txt`: ```text led-ticker-weather ``` ## Transitions [Section titled “Transitions”](#transitions) ### [Homage sprite-trail transitions (flair pack)](https://github.com/JamesAwesome/led-ticker-plugins/tree/main/plugins/flair) [Section titled “Homage sprite-trail transitions (flair pack)”](#homage-sprite-trail-transitions-flair-pack) Four pixel-art character families ship together in the `led-ticker-flair` package — one install brings all four. Each family provides `.forward`, `.reverse`, and `.alternating` variants; reference them by their namespaced slug, e.g. `transition = "pokeball.forward"`. See [Sprite transitions](/transitions/sprite/) for the full catalogue, screenshots, and per-family details. ```text led-ticker-flair ``` * **nyancat** — Nyan Cat with rainbow trail (`nyancat.forward` / `.reverse` / `.alternating`); hi-res on scaled signs. * **pokeball** — Pokéball with run-cycle sprite (`pokeball.forward` / `.reverse` / `.alternating`); hi-res on scaled signs; ships `:pokeball.ball:` emoji. * **pacman** — Pac-Man chasing three scared ghosts (`pacman.forward` / `.reverse` / `.alternating`). * **sailor\_moon** — Moon Stick wand with sparkle trail (`sailor_moon.forward` / `.reverse` / `.alternating`). - **Transitions:** nyancat.forward, nyancat.reverse, nyancat.alternating Add to your `config/requirements-plugins.txt`: ```text led-ticker-flair ``` * **Transitions:** pokeball.forward, pokeball.reverse, pokeball.alternating * **Emoji:** :pokeball.ball: Add to your `config/requirements-plugins.txt`: ```text led-ticker-flair ``` * **Transitions:** pacman.forward, pacman.reverse, pacman.alternating Add to your `config/requirements-plugins.txt`: ```text led-ticker-flair ``` * **Transitions:** sailor\_moon.forward, sailor\_moon.reverse, sailor\_moon.alternating Add to your `config/requirements-plugins.txt`: ```text led-ticker-flair ``` ### [Flair text effects (flair pack)](https://github.com/JamesAwesome/led-ticker-plugins/tree/main/plugins/flair) [Section titled “Flair text effects (flair pack)”](#flair-text-effects-flair-pack) The flair pack also ships two text effects — an animation and a transition — that pair together for a full spin-in / spin-out cycle. Both come with the same `led-ticker-flair` install. See [Animations](/concepts/animations/) and [Sprite transitions](/transitions/sprite/) for full documentation, demo GIFs, and per-knob details. * **flair.propeller** (`animation`, flair >= 0.2.0) — `message` widget text spins in-plane on entry, settling flat before hold time begins. * **flair.spinout** (`transition`, flair >= 0.3.0, core >= 4.6) — the outgoing widget’s content accelerates and spins out, then cuts to incoming. * **flair.fisheye** (`animation`, flair >= 0.4.0, core >= 4.7) — a `message` widget’s scrolling text passes through a stationary squeeze-and-bulge lens; the scroll provides the motion. - **Transitions:** flair.spinout - **Animations:** flair.propeller, flair.fisheye Add to your `config/requirements-plugins.txt`: ```text led-ticker-flair ``` *** ## Backends [Section titled “Backends”](#backends) A backend is led-ticker’s **rendering target** — where the sign is drawn (the LED panel, or an alternative like a terminal). Unlike a widget, a backend isn’t added to a section; it’s selected in your display configuration. ### [telnet](https://github.com/JamesAwesome/led-ticker-plugins/tree/main/plugins/telnet) [Section titled “telnet”](#telnet) Watch your sign in a terminal over Telnet (ANSI rendering). * **Backends:** telnet Add to your `config/requirements-plugins.txt`: ```text led-ticker-telnet ``` *** ## Add your plugin [Section titled “Add your plugin”](#add-your-plugin) Built one? It belongs here. Open a PR that adds an entry above with: * a one-line description and the link to your repo, * a repo `README` with install steps **and a minimal `config.toml` widget block** (showing `type =`, the required keys, and their defaults) so users can copy-paste — see [pool](https://github.com/JamesAwesome/led-ticker-plugins/tree/main/plugins/pool) for the shape. Every working plugin belongs here — including personal-use ones. Listing it grows what led-ticker can do and helps the next person. The [authoring guide](/plugins/authoring/01-scaffold/) takes you from nothing to a shippable widget. # Custom color provider > Build a custom color provider for led-ticker from a plugin — the color_for contract, the per_char and frame_invariant flags, and a worked animated pulse effect. This is a how-to for **plugin authors**: write a custom **color provider** — the object that decides what color text is, frame by frame. You’ll build a **pulse** that makes a message breathe brighter and dimmer. **What you’ll need:** * A scaffolded plugin — see the [authoring guide](/plugins/authoring/01-scaffold/); you only import `led_ticker.plugin`. * No hardware needed: you’ll preview with `make render-demo` (run from the repo after `make dev`). * Your plugin **installed** (`pip install -e .` from its directory) — `make render-demo` only picks up installed plugins.  Built-in color providers animating text — your pulse will breathe similarly. ## The `color_for` contract [Section titled “The color\_for contract”](#the-color_for-contract) A color provider is a class with two flags and one method: ```python class Pulse(ColorProviderBase): per_char = False frame_invariant = False def color_for(self, frame, char_index, total_chars): ... ``` * **`color_for(frame, char_index, total_chars)`** returns a `Color` for the current `frame`. `char_index` / `total_chars` describe the character being drawn (for per-character effects). * **`per_char`** — `False` returns one color for the whole string; `True` is called per character, so you can color each letter differently (using `char_index`). * **`frame_invariant`** — does your color depend on `frame`? `True` means no (a constant or gradient — led-ticker paints it once and sleeps, a performance fast-path); `False` means yes (it animates — led-ticker re-renders every tick). Danger Get `frame_invariant` right. If `color_for` uses `frame` but you declare `frame_invariant = True`, led-ticker takes the paint-once fast path and your animation **silently freezes** — with no error. Subclassing `ColorProviderBase` forces you to declare the flag so you can’t forget it. ## Build the pulse [Section titled “Build the pulse”](#build-the-pulse) The pulse keeps one color but scales its brightness up and down with a sine wave driven by `frame`: ```python def color_for(self, frame, char_index, total_chars): level = 0.65 + 0.35 * math.sin(frame * self.speed * 0.05) r, g, b = self.color return make_color(int(r * level), int(g * level), int(b * level)) ``` `make_color(r, g, b)` builds a `Color` (channels 0–255). The `0.65` is the midpoint brightness and `0.35` the swing, so brightness oscillates between about 30% and 100% — it never goes fully dark; the `0.05` just scales `frame` into the sine, so **tune `speed` from TOML and leave the `0.05` alone**. Because the output depends on `frame`, **`frame_invariant = False`**. Add a base `color` and a `speed` as constructor arguments and they’ll come from TOML. Tip Want a different color per letter (like the built-in rainbow)? Set `per_char = True` and use `char_index` / `total_chars` in `color_for` — e.g. offset the hue by `char_index`. And set the class attribute `restart_on_visit = False` (see the [API reference](/plugins/api-reference/)) to keep the animation’s phase continuous across a section’s `loop_count`. ## Register and use it [Section titled “Register and use it”](#register-and-use-it) 1. Register the class in your plugin’s `register(api)`: ```python @api.color_provider("pulse") class Pulse(ColorProviderBase): ... ``` It’s namespaced — in the `example_colorprovider` plugin it becomes `example_colorprovider.pulse`. 2. Point a text widget’s `font_color` at it in your `config/config.toml` (optionally with fields): ```toml [[playlist.section.widget]] type = "message" text = "breathing" font_color = { style = "example_colorprovider.pulse", color = [0, 200, 255], speed = 6 } ``` 3. Install your plugin so led-ticker can find it. `make render-demo` loads only **installed** plugins (see [Package & install](/plugins/authoring/03-package/)), then preview — no hardware needed: ```bash pip install -e . # run from your plugin's directory make render-demo CONFIG=config/config.toml OUT=preview.gif open preview.gif # macOS; xdg-open on Linux ``` ## Complete listing [Section titled “Complete listing”](#complete-listing) The full plugin — `examples/plugins/example_colorprovider/__init__.py`: ```python """Example led-ticker plugin: a custom 'pulse' color provider (the 'Custom color provider' how-to). Drop `example_colorprovider/` into your `config/plugins/` (local use), or package it with an `[project.entry-points."led_ticker.plugins"] example_colorprovider = "example_colorprovider:register"` entry, then use it as `font_color = {style = "example_colorprovider.pulse"}`. Imports only `led_ticker.plugin` (the public surface) plus stdlib. """ import math from led_ticker.plugin import ColorProviderBase, make_color def register(api): @api.color_provider("pulse") class Pulse(ColorProviderBase): # One color for the whole string (not per-character). per_char = False # `color_for` depends on `frame`, so the widget must re-render each tick. # Declaring this True would freeze the pulse — ColorProviderBase forces # you to set it explicitly. frame_invariant = False # Config fields come from TOML, e.g. # font_color = {style = "example_colorprovider.pulse", color = [0, 200, 255], speed = 6} def __init__(self, color=(0, 200, 255), speed=6): self.color = color self.speed = speed def color_for(self, frame, char_index, total_chars): # Brightness breathes between ~0.30 and ~1.00 as the frame advances. level = 0.65 + 0.35 * math.sin(frame * self.speed * 0.05) r, g, b = self.color return make_color(int(r * level), int(g * level), int(b * level)) ``` ## If it doesn’t work [Section titled “If it doesn’t work”](#if-it-doesnt-work) * **The color is frozen / doesn’t animate** — you declared `frame_invariant = True` but `color_for` uses `frame`. Set `frame_invariant = False`. * **`TypeError: Pulse must define 'frame_invariant'`** — declare it as a class attribute (that’s `ColorProviderBase` doing its job). * **“unknown font\_color style” / not found** — check the namespaced `style` (`example_colorprovider.pulse`, not `pulse`) and that the plugin is installed/loaded (see [Installing a plugin](/plugins/#installing-a-plugin)). See also * [concepts/color-providers](/concepts/color-providers/) * [plugins/api-reference](/plugins/api-reference/) * [plugins/extending/writing-a-transition](/plugins/extending/writing-a-transition/) # Custom emoji > Add your own inline emoji to led-ticker from a plugin — the PixelData format, registering low-res and hi-res sprites, and a PNG-to-pixels recipe. This is a how-to for **plugin authors**: add your own emoji so it renders inline in any message as `:yourplugin.slug:`. You’ll register an 8×8 sprite, see it on the sign, then add a hi-res version for scaled (big) signs. Note New to plugins? Start with the [authoring guide](/plugins/authoring/01-scaffold/) to scaffold one, then come back. You only need `led_ticker.plugin` — and, for the optional PNG recipe at the end, [Pillow](https://python-pillow.org/).  Emoji render inline in message text — the built-ins, and any you add. ## What a sprite looks like: `PixelData` [Section titled “What a sprite looks like: PixelData”](#what-a-sprite-looks-like-pixeldata) A low-res emoji is a **`PixelData`** — a `list` of `(x, y, r, g, b)` tuples, **one per lit pixel** on an 8×8 grid (`x`, `y` are 0–7; `r`, `g`, `b` are 0–255). Pixels you leave out stay transparent. The easy way to build one is to “draw” it as text, then expand it: ```python # An 8×8 heart. "X" = a lit pixel, "." = transparent. _HEART_ART = [ ".XX..XX.", "XXXXXXXX", "XXXXXXXX", "XXXXXXXX", ".XXXXXX.", "..XXXX..", "...XX...", "........", ] _RED = (220, 40, 60) HEART = [ (x, y, *_RED) for y, row in enumerate(_HEART_ART) for x, cell in enumerate(row) if cell == "X" ] # HEART == [(1, 0, 220, 40, 60), (2, 0, 220, 40, 60), ...] — 40 tuples. ``` ## Register it and show it [Section titled “Register it and show it”](#register-it-and-show-it) 1. Register the sprite inside your plugin’s `register(api)` under a slug: ```python def register(api): api.emoji("heart", HEART) ``` The slug is namespaced automatically — in the `example_emoji` plugin it becomes `example_emoji.heart`. 2. Use it inline in any message by wrapping the namespaced slug in colons. Add a section like this to the `config/config.toml` you’ll render: ```toml [[playlist.section.widget]] type = "message" text = "we :example_emoji.heart: led-ticker" ``` 3. Install your plugin so led-ticker can find it. `make render-demo` only loads **installed** plugins (via their entry point), not a local plugin directory — so package-install yours first (see [Package & install](/plugins/authoring/03-package/)): ```bash pip install -e . # run from your plugin's directory ``` 4. Preview it — no hardware needed. This renders the config from step 2: ```bash make render-demo CONFIG=config/config.toml OUT=preview.gif open preview.gif # macOS; xdg-open on Linux ``` Caution `make render-demo` discovers only **installed** plugins. A plugin you’ve merely dropped into `config/plugins/` loads when you run `led-ticker` on the sign, but won’t show up in a `render-demo` preview until you `pip install -e .` it. ## Low-res vs hi-res [Section titled “Low-res vs hi-res”](#low-res-vs-hi-res) led-ticker keeps two emoji registries: * **Low-res** — the 8×8 `PixelData` above. Used by inline `:slug:` text and by **small / unscaled signs**. This is all most plugins need. * **Hi-res** — a larger sprite in **physical** pixel coordinates. Used on **scaled (big) signs** (`default_scale > 1`) and by direct draws ([`draw_emoji_at`](/plugins/api-reference/#exported-names)). Rule of thumb: **small sign → register only the low-res sprite. Big / scaled sign → also register a hi-res version** (keep the low-res one — inline `:slug:` always resolves through it; a hi-res sprite with no low-res counterpart logs a warning at load). ## Adding a hi-res sprite [Section titled “Adding a hi-res sprite”](#adding-a-hi-res-sprite) `HiResEmoji(pixels=…, physical_size=…)` takes pixels in physical coordinates (`0 … physical_size − 1`). The quickest way is to scale your 8×8 sprite up — here, 2× into a 16×16: ```python from led_ticker.plugin import HiResEmoji HEART_HIRES = tuple( (x * 2 + dx, y * 2 + dy, r, g, b) for (x, y, r, g, b) in HEART for dx in (0, 1) for dy in (0, 1) ) def register(api): api.emoji("heart", HEART) api.hires_emoji("heart", HiResEmoji(pixels=HEART_HIRES, physical_size=16)) ``` ## From a PNG [Section titled “From a PNG”](#from-a-png) Have an image instead? This one-time helper converts an 8×8 PNG into a `PixelData` list you can paste in. It’s a script you run yourself — not part of the plugin. ```python # pip install pillow from PIL import Image img = Image.open("heart.png").convert("RGBA") # an 8×8 image pixels = [] for y in range(img.height): for x in range(img.width): r, g, b, a = img.getpixel((x, y)) if a > 0: # skip fully transparent pixels pixels.append((x, y, r, g, b)) print(pixels) # paste this as your PixelData ``` Tip Keep it 8×8 for a low-res sprite. For a hi-res sprite, use a 16×16 (or 32×32) image and pass `physical_size=16` (or `32`). ## Complete listing [Section titled “Complete listing”](#complete-listing) The full plugin — `examples/plugins/example_emoji/__init__.py`: ```python """Example led-ticker plugin: a custom inline emoji (the 'Custom emoji' how-to). Drop `example_emoji/` into your `config/plugins/` (local use), or package it with an `[project.entry-points."led_ticker.plugins"] example_emoji = "example_emoji:register"` entry, then use it inline in any message as `:example_emoji.heart:`. Imports only `led_ticker.plugin` (the public surface) plus stdlib. """ from led_ticker.plugin import HiResEmoji # An 8x8 heart. "X" = a lit pixel, "." = transparent. _HEART_ART = [ ".XX..XX.", "XXXXXXXX", "XXXXXXXX", "XXXXXXXX", ".XXXXXX.", "..XXXX..", "...XX...", "........", ] _RED = (220, 40, 60) # Low-res sprite: a PixelData = list of (x, y, r, g, b), one tuple per lit pixel. HEART = [ (x, y, *_RED) for y, row in enumerate(_HEART_ART) for x, cell in enumerate(row) if cell == "X" ] # Hi-res sprite: scale the 8x8 up 2x into a 16x16, in physical coordinates. HEART_HIRES = tuple( (x * 2 + dx, y * 2 + dy, r, g, b) for (x, y, r, g, b) in HEART for dx in (0, 1) for dy in (0, 1) ) def register(api): # Low-res: used by inline `:example_emoji.heart:` and small / unscaled signs. api.emoji("heart", HEART) # Hi-res: used on scaled (big) signs; keep the low-res one for inline use. api.hires_emoji("heart", HiResEmoji(pixels=HEART_HIRES, physical_size=16)) ``` ## If it doesn’t work [Section titled “If it doesn’t work”](#if-it-doesnt-work) * **The emoji doesn’t appear / shows as literal text** — check the slug is namespaced (`:example_emoji.heart:`, not `:heart:`) and that the plugin is installed/loaded (see [Installing a plugin](/plugins/#installing-a-plugin)). * **It shows on a small sign but not a big one** — register a hi-res sprite (above); inline use still needs the low-res one. * **A “hi-res emoji has no low-res counterpart” warning at load** — register a matching `api.emoji(slug, …)` alongside `api.hires_emoji(slug, …)`. See also * [plugins/api-reference](/plugins/api-reference/) * [assets/emoji](/assets/emoji/) * [plugins/authoring/01-scaffold](/plugins/authoring/01-scaffold/) # Service plugins > Build a service plugin for led-ticker — a background poller via on_startup and spawn_tracked, plus a status overlay painted every frame. Plus animation, border, and easing. This is a how-to for **plugin authors**: build a **service plugin** — one that runs background work and paints a live indicator on the sign, instead of (or alongside) a widget. You’ll build a status dot that turns green or red based on a background health check. The shipped [busy-light](/concepts/busy-light/) is a real-world version of this exact pattern. **What you’ll need:** * A scaffolded plugin — see the [authoring guide](/plugins/authoring/01-scaffold/); you only import `led_ticker.plugin`. * No hardware needed to develop, but an overlay shows on the sign when you run `led-ticker`. * Your plugin **installed** (`pip install -e .` from its directory). ## The lifecycle hooks [Section titled “The lifecycle hooks”](#the-lifecycle-hooks) A service plugin uses hooks instead of (or alongside) a widget: * **`api.overlay(paint)`** — registers `paint(canvas)`, run **on the real canvas just before each frame is sent to the panel**. Use it to draw an indicator over whatever else is on screen. It’s **exception-guarded**: if it raises, led-ticker disables it and logs — it can never freeze the panel. Keep it paint-only and fast. * **`api.on_startup(fn)`** — `fn` runs once, after the panel and a shared HTTP session exist. It receives a **`StartupContext`** with `.session` (a shared `aiohttp.ClientSession`), `.config` (your parsed config), and `.frame` (the live `LedFrame`). Sync or async. * **`spawn_tracked(coro)`** — start long-lived background work (a poll loop) as a tracked task from your startup hook: `spawn_tracked(poll())`. (Imported from `led_ticker.plugin` — it’s a function, not an `api.` method.) * **`api.on_shutdown(fn)`** — optional cleanup when the loop exits. Caution Do the slow work (network, sleeps) in the **poller**, never in `paint`. `paint` runs every frame — blocking or raising there stutters or disables your overlay. The painter should only read shared state and draw. ## Build the service [Section titled “Build the service”](#build-the-service) Hold shared state, paint it in the overlay, and update it from a background poller: ```python import asyncio from led_ticker.plugin import spawn_tracked def register(api): state = {"online": False} def paint(canvas): r, g, b = (0, 200, 0) if state["online"] else (200, 0, 0) canvas.SetPixel(0, 0, r, g, b) # a status dot in the corner api.overlay(paint) async def start(ctx): async def poll(): while True: try: async with ctx.session.get("https://example.com/health") as resp: state["online"] = resp.status == 200 except Exception: state["online"] = False await asyncio.sleep(30) spawn_tracked(poll()) api.on_startup(start) ``` `ctx.session` is shared across all plugins, so you don’t manage your own HTTP client. The poller loops forever on its own schedule; the overlay just reflects the latest `state`. ## Other surfaces at a glance [Section titled “Other surfaces at a glance”](#other-surfaces-at-a-glance) The remaining plugin surfaces are one-method classes (or a plain function), registered the same way. Each is shown complete in the tested [acme reference plugin](https://github.com/JamesAwesome/led-ticker/blob/main/examples/plugins/acme/__init__.py): **Animation** — transforms the text shown each frame (e.g. a typewriter): ```python @api.animation("scramble") class Scramble: def frame_for(self, frame, full_text, canvas_width, text_width): return AnimationFrame(visible_text=full_text) ``` **Border** — paints a 1–2px ring around the content each frame. Subclass `BorderEffectBase` and declare `frame_invariant` (same rule as a [color provider](/plugins/extending/custom-color-provider/)): ```python @api.border("neon") class Neon(BorderEffectBase): frame_invariant = False def paint(self, canvas, frame_count): ... # draw the ring with canvas.SetPixel ``` **Easing** — a plain `(float) -> float` curve, registered directly (no class): ```python api.easing("snap", lambda p: p * p) ``` ## Register and use it [Section titled “Register and use it”](#register-and-use-it) 1. Register the overlay + startup hook in `register(api)` (the complete listing is below). No TOML is needed — the overlay paints on every screen automatically. 2. Install your plugin so led-ticker loads it: ```bash pip install -e . # run from your plugin's directory ``` 3. Run it on the sign — the status dot appears in the corner: ```bash led-ticker --config config/config.toml ``` Note Overlays and startup hooks run on the live engine, so `make render-demo` (which renders widgets to a GIF) won’t show them — run `led-ticker` on the Pi to see a service plugin in action. ## Complete listing [Section titled “Complete listing”](#complete-listing) The full plugin — `examples/plugins/example_service/__init__.py`: ```python """Example led-ticker plugin: a 'service' plugin — a background poller + a status overlay. Drop `example_service/` into your `config/plugins/` (local use), or package it with an `[project.entry-points."led_ticker.plugins"] example_service = "example_service:register"` entry. No TOML needed — the overlay paints a corner status dot on every screen. Imports only `led_ticker.plugin` (the public surface) plus stdlib. """ import asyncio from led_ticker.plugin import spawn_tracked def register(api): # Shared state: the background poller writes it, the overlay reads it. state = {"online": False} def paint(canvas): # Runs every frame on the real canvas, BEFORE the hardware swap. Keep it # paint-only and fast, and never raise — a raising overlay is disabled and # logged, and must never be able to freeze the panel. r, g, b = (0, 200, 0) if state["online"] else (200, 0, 0) canvas.SetPixel(0, 0, r, g, b) # a status dot in the top-left corner api.overlay(paint) async def start(ctx): # Runs once, after the frame + HTTP session exist. `ctx.session` is the # shared aiohttp ClientSession; `ctx.config` is the parsed app config. async def poll(): while True: try: async with ctx.session.get("https://example.com/health") as resp: state["online"] = resp.status == 200 except Exception: state["online"] = False await asyncio.sleep(30) # Launch the long-lived poller as a tracked background task. spawn_tracked(poll()) api.on_startup(start) ``` ## If it doesn’t work [Section titled “If it doesn’t work”](#if-it-doesnt-work) * **The dot never appears** — the plugin isn’t installed/loaded (see [Installing a plugin](/plugins/#installing-a-plugin)); overlays need an installed plugin. * **The dot never changes** — the poller hit an error or the URL is unreachable (it’s caught and falls back to “offline”); check the logs and your endpoint. * **The panel stutters or froze** — you did slow or raising work in `paint`. Move it to the poller; `paint` must be fast and must not raise. See also * [concepts/busy-light](/concepts/busy-light/) * [plugins/api-reference](/plugins/api-reference/) * [plugins/extending/custom-color-provider](/plugins/extending/custom-color-provider/) # Writing a transition > Build a custom transition for led-ticker from a plugin — the frame_at contract, the canvas drawing tools, and a worked wipe effect. This is a how-to for **plugin authors**: write a custom transition — the short animation played between two widgets. You’ll build a **wipe** that sweeps the old frame away behind a colored line, then reveals the new one. **What you’ll need:** * A scaffolded plugin — see the [authoring guide](/plugins/authoring/01-scaffold/); you only import `led_ticker.plugin`. * No hardware needed: you’ll preview with `make render-demo` (run from the repo after `make dev`). * Your plugin **installed** (`pip install -e .` from its directory) — `make render-demo` only picks up installed plugins.  A wipe — a sweep line crosses the panel and the new content follows. ## The `frame_at` contract [Section titled “The frame\_at contract”](#the-frame_at-contract) A transition is a class with one method, `frame_at`, called once per frame while the transition plays: ```python def frame_at(self, t, canvas, outgoing, incoming, **kwargs): ... ``` * **`t`** runs from **0.0 to 1.0** — the transition’s progress. At `t=0` you’d show only `outgoing`; at `t=1.0`, only `incoming`. * **`canvas`** is what you draw on (the pixel grid for this frame). The engine **clears it for you before each call** — don’t clear it yourself. * **`outgoing`** and **`incoming`** are the two frames. You don’t read their pixels — you ask each to paint itself with **`frame.draw(canvas, cursor_pos=N)`**, where `cursor_pos` is a horizontal pixel offset (`0` = in place). * The **return value is ignored** — the engine renders whatever you drew onto `canvas`. Returning `canvas` is a harmless convention. Tip `frame_at` also receives a few `**kwargs` (e.g. `outgoing_scroll_pos`, `duration_ms`) that fancier transitions use. You can ignore them — this wipe does. ## The drawing tools [Section titled “The drawing tools”](#the-drawing-tools) You composite each frame with three canvas calls: * **`canvas.width`** / **`canvas.height`** — the panel size in pixels (use `getattr(canvas, "height", 16)` to be safe). * **`canvas.SubFill(x, y, w, h, r, g, b)`** — fill a rectangle with a color. This is how you “clip”: a frame drawn with `draw()` can’t be cropped, so you draw it in full and then **black out** the part you don’t want with `SubFill(…, 0, 0, 0)`. * **`canvas.SetPixel(x, y, r, g, b)`** — set a single pixel (here, the sweep line). ## Build the wipe [Section titled “Build the wipe”](#build-the-wipe) Draw the **outgoing** frame, black out everything the sweep has already crossed, draw the colored **sweep line** at the moving edge, and at the very end snap to the **incoming** frame: ```python def frame_at(self, t, canvas, outgoing, incoming, **kwargs): w = canvas.width h = getattr(canvas, "height", 16) if t >= 1.0: incoming.draw(canvas, cursor_pos=0) return canvas edge = int(t * w) # the sweep edge moves left -> right, 0 .. w outgoing.draw(canvas, cursor_pos=0) # 1. the old frame fills the canvas if edge > 0: # 2. black out everything the sweep has passed canvas.SubFill(0, 0, edge, h, 0, 0, 0) for dx in range(2): # 3. a 2px colored sweep line at the edge x = edge + dx if 0 <= x < w: for y in range(h): canvas.SetPixel(x, y, self.color[0], self.color[1], self.color[2]) return canvas ``` Two finishing touches, both wired into the class in the [complete listing](#complete-listing) below: set **`min_frames`** — a floor on the frame count, so the sweep stays smooth even when the configured duration is short — and accept a **`color`** field so the sweep line is configurable from TOML. Note This is a “sweep the old away to a colored line, then reveal the new” wipe — the same style as led-ticker’s built-in wipes. A *progressive* reveal (new content on the left, old on the right, with no black band) isn’t cleanly possible because `draw()` can’t be clipped — which is exactly why the black-out step exists. ## Register and use it [Section titled “Register and use it”](#register-and-use-it) 1. Register the class in your plugin’s `register(api)`: ```python @api.transition("wipe") class Wipe: ... ``` It’s namespaced — in the `example_transition` plugin it becomes `example_transition.wipe`. 2. Use it on a section in your `config/config.toml` (optionally with a `color`): ```toml [[playlist.section]] transition = { type = "example_transition.wipe", color = [255, 0, 0] } ``` 3. Install your plugin so led-ticker can find it. `make render-demo` loads only **installed** plugins (see [Package & install](/plugins/authoring/03-package/)), then preview — no hardware needed: ```bash pip install -e . # run from your plugin's directory make render-demo CONFIG=config/config.toml OUT=preview.gif open preview.gif # macOS; xdg-open on Linux ``` Caution The listing below mentions you can “drop `example_transition/` into `config/plugins/`” — that works when you run `led-ticker` on the sign, but a `make render-demo` preview only sees **installed** plugins. For the preview above, `pip install -e .` your plugin first. ## Complete listing [Section titled “Complete listing”](#complete-listing) The full plugin — `examples/plugins/example_transition/__init__.py`: ```python """Example led-ticker plugin: a custom 'wipe' transition (the 'Writing a transition' how-to). Drop `example_transition/` into your `config/plugins/` (local use), or package it with an `[project.entry-points."led_ticker.plugins"] example_transition = "example_transition:register"` entry, then use it in TOML as `transition = {type = "example_transition.wipe"}`. Imports only `led_ticker.plugin` (the public surface) plus stdlib. """ def register(api): @api.transition("wipe") class Wipe: # Enough frames for a smooth sweep regardless of the configured duration. min_frames = 16 # A config-driven field: `transition = {type = "example_transition.wipe", # color = [255, 0, 0]}` passes `color` here. Default: cyan. def __init__(self, color=(0, 255, 255)): self.color = color def frame_at(self, t, canvas, outgoing, incoming, **kwargs): # The engine clears the canvas before each call — don't clear it here. # Draw onto `canvas`; the return value is ignored (returning canvas # is just a convention). w = canvas.width h = getattr(canvas, "height", 16) if t >= 1.0: incoming.draw(canvas, cursor_pos=0) return canvas edge = int(t * w) # the sweep edge moves left -> right, 0 .. w outgoing.draw(canvas, cursor_pos=0) # 1. the old frame fills the canvas if edge > 0: # 2. black out everything the sweep has passed canvas.SubFill(0, 0, edge, h, 0, 0, 0) for dx in range(2): # 3. a 2px colored sweep line at the edge x = edge + dx if 0 <= x < w: for y in range(h): canvas.SetPixel(x, y, self.color[0], self.color[1], self.color[2]) return canvas ``` ## Going hi-res (bigsign) [Section titled “Going hi-res (bigsign)”](#going-hi-res-bigsign) The wipe above paints in **logical** pixels and works everywhere. On the **bigsign** (`default_scale > 1`) the canvas your `frame_at` receives is a *scaled wrapper* — every `SetPixel` it forwards expands to a `scale × scale` block. That’s perfect for text and lo-res sprites, but a hi-res transition (a sprite drawn at the panel’s *native* resolution) needs to reach past the wrapper and paint individual physical LEDs. The shipped [`baseball`](https://github.com/JamesAwesome/led-ticker-plugins/tree/main/plugins/baseball) package does exactly this; here’s the pattern. Three public symbols from `led_ticker.plugin` do the work: ```python from led_ticker.plugin import is_scaled, unwrap_to_real, snap_reset, SNAP_THRESHOLD ``` * **`is_scaled(canvas)`** — `True` only on the scaled (bigsign) path. **Gate your hi-res branch with this, not `isinstance(canvas, ScaledCanvas)`** — `is_scaled` *is* the supported predicate that replaces the `isinstance` check. At `scale = 1` it returns `False`, so the same `frame_at` falls through to your lo-res code automatically. * **`unwrap_to_real(canvas)`** — peels the wrapper and returns the underlying real canvas. Call its `.SetPixel(x, y, r, g, b)` to light one physical LED at native resolution (no block expansion). For the panel size, read `real.width` / `real.height` off the unwrapped canvas. (If you’d rather not juggle the scale yourself, `paint_hires(canvas, callback)` hands your callback the real canvas plus its `scale` and `y_offset_real`.) * **`snap_reset(canvas, incoming_bg_color)` + `SNAP_THRESHOLD`** — near the end of the transition (`t >= SNAP_THRESHOLD`, ≈0.95), reset and draw the incoming widget. `snap_reset` `Fill`s the section’s background color (or `Clear`s when it’s `None`) so a bg-colored section doesn’t flash “incoming on black” for one tick on bordered widgets. Pass the bg through from `kwargs`: `snap_reset(canvas, kwargs.get("incoming_bg_color"))`. Put together, a hi-res transition branches in `frame_at`, paints physical pixels in its hi-res helper, and snaps at the threshold: ```python from led_ticker.plugin import is_scaled, unwrap_to_real, snap_reset, SNAP_THRESHOLD class Ball: min_frames = 40 def frame_at(self, t, canvas, outgoing, incoming, **kwargs): if t >= 1.0: incoming.draw(canvas, cursor_pos=0) return canvas # The wrapper only appears on the bigsign — lo-res panels fall through. if is_scaled(canvas): return self._frame_at_hires(t, canvas, outgoing, incoming, **kwargs) return self._frame_at_lowres(t, canvas, outgoing, incoming, **kwargs) def _frame_at_hires(self, t, canvas, outgoing, incoming, **kwargs): real = unwrap_to_real(canvas) # the real canvas, native pixels panel_w, panel_h = real.width, real.height outgoing.draw(canvas) # outgoing still draws through the wrapper # ... compute the sprite/trail position from t, then light physical LEDs: x = int(t * panel_w) for y in range(panel_h): real.SetPixel(x, y, 255, 255, 255) # one native pixel — no block expansion if t >= SNAP_THRESHOLD: # ≈0.95 — wrap it up snap_reset(canvas, kwargs.get("incoming_bg_color")) incoming.draw(canvas) return canvas ``` The lo-res helper (`_frame_at_lowres`) is just your scale-1 logic from earlier — same wipe, drawn through the wrapper. Note Outgoing and incoming widgets keep drawing through the wrapper (`outgoing.draw(canvas)`); only your own per-pixel paint goes to the unwrapped real canvas. The two coordinate systems coexist on the same frame. For the exact signatures of `is_scaled`, `unwrap_to_real`, `paint_hires`, `snap_reset`, and `SNAP_THRESHOLD`, see the [API reference](/plugins/api-reference/). The [`baseball`](https://github.com/JamesAwesome/led-ticker-plugins/tree/main/plugins/baseball) package is a real, shipped example of this pattern. ### Hi-res sprite transitions [Section titled “Hi-res sprite transitions”](#hi-res-sprite-transitions) If your transition is an **animated sprite** (a gif or webp that crosses the panel), `HiresSpec` + `render_hires_frame` handle the sprite decode, scaling, trail, and snap for you — you only need to provide the file and set `trail`. Bundle the sprite inside your plugin package and build a `HiresSpec` at module load: ```python from pathlib import Path from led_ticker.plugin import HiresSpec, is_scaled, render_hires_frame _HERE = Path(__file__).parent _SPEC = HiresSpec( sprite_path=_HERE / "sprites" / "zoom.gif", # gif or webp, bundled with the plugin flip_horizontal=False, trail="black", # "none" | "black" | "rainbow" ) ``` `render_hires_frame` decodes the sprite to the panel’s native height, drives the traversal from `t`, and calls `snap_reset` at `SNAP_THRESHOLD` automatically. In `frame_at`, gate on `is_scaled(canvas)` (the supported predicate, per above — only `True` on the bigsign) and forward `**kwargs` so `incoming_bg_color` and friends reach the renderer. Fall back to your own lo-res drawing on the small sign or in test stubs: ```python def register(api): @api.transition("zoom") class Zoom: def frame_at(self, t, canvas, outgoing, incoming, **kwargs): if t >= 1.0: incoming.draw(canvas, cursor_pos=0) return canvas if is_scaled(canvas): # bigsign -> hi-res sprite return render_hires_frame( t, canvas, outgoing, incoming, _SPEC, **kwargs ) # small sign / tests -> your own lo-res fallback return self._lowres(t, canvas, outgoing, incoming, **kwargs) ``` `trail` fills the band behind the leading sprite to erase the outgoing widget’s text: `"none"` leaves the outgoing frame visible (good for transparent sprites), `"black"` paints the trail black, and `"rainbow"` sweeps a hue cycle (the nyancat style). For the full `HiresSpec` and `render_hires_frame` signatures see the [API reference](/plugins/api-reference/). ## If it doesn’t work [Section titled “If it doesn’t work”](#if-it-doesnt-work) * **“Unknown transition” / the name isn’t found** — check the namespaced `type` (`example_transition.wipe`, not `wipe`) and that the plugin is installed/loaded (see [Installing a plugin](/plugins/#installing-a-plugin)). * **The transition flickers or is too quick to see** — raise `min_frames`, or the section’s transition duration. * **The canvas looks smeared / wrong** — don’t call `canvas.Clear()` or `canvas.Fill()` yourself; the engine clears before each `frame_at`. See also * [plugins/api-reference](/plugins/api-reference/) * [plugins/extending/custom-emoji](/plugins/extending/custom-emoji/) * [plugins/authoring/01-scaffold](/plugins/authoring/01-scaffold/) # Reference: CLI > Command-line entry points and Make targets for running, validating, and developing led-ticker. led-ticker exposes one console script (`led-ticker`) with a default “run the display” mode and `validate`, `plugin`, and `webui` subcommands. Day-to-day development is wrapped in `make` targets that drive `uv`, `pytest`, `ruff`, and the docs site. The console script is registered in `pyproject.toml` as `led-ticker = "led_ticker.app:main"`. ## `led-ticker` (default) [Section titled “led-ticker (default)”](#led-ticker-default) Runs the display loop against a TOML config. With no subcommand, the CLI loads the config, builds the playlist, opens the panel, and starts rendering until interrupted. | Flag | Default | Notes | | ----------------- | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `--config` / `-c` | `config.toml` | Path to the TOML configuration file. Resolved relative to the working dir. | | `--backend` | *(config)* | Override the display backend (e.g. `headless`). Takes precedence over `[display] backend` in the config. Unknown names fail with a clear registry error. Primarily used by the `make try` Docker flow to run headless without modifying your deploy config. | The `LED_TICKER_BACKEND` environment variable is the env equivalent of `--backend` (the flag wins when both are set) — it’s how `compose.try.yaml` selects the headless backend. If the config path doesn’t exist, the CLI prints a hint pointing at `config.example.toml` and exits with status `1`. ```bash led-ticker --config config/config.toml led-ticker --config config/config.toml --backend headless ``` ## `led-ticker validate` [Section titled “led-ticker validate”](#led-ticker-validate) Validates a TOML config without opening the panel — checks every widget builds, every transition resolves, and every reference (font names, image paths, color shapes) is well-formed. Useful in CI and as a pre-flight check before deploying a config to a Pi. ```bash led-ticker validate config/config.toml led-ticker validate config/config.toml --json led-ticker validate --strict config/config.toml ``` | Flag | Default | Notes | | --------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------- | | `path` | — | Path to the config file. Required unless `--list-fields` is given. | | `--json` | off | Emit machine-readable JSON instead of human-readable text. Used by the `creating-a-config` skill. | | `--strict` | off | Promote all warnings to errors. Also checks that `gif`/`image` `path` fields exist on disk. Use in CI to enforce a warning-clean config. | | `--fix` | off | Apply auto-fixable migrations (key renames) to the config file in-place. Comments in the TOML file are **not** preserved. | | `--list-fields` | — | Print all valid fields for a widget type and exit (e.g. `--list-fields message`). No `path` argument required. | Exits `0` on a clean config, `1` on validation errors (or promoted warnings with `--strict`), `2` if the config file isn’t found. See [Tools: validate](/tools/validate/) for the full output format (human + JSON), exit codes, and CI examples. ## `led-ticker plugin` [Section titled “led-ticker plugin”](#led-ticker-plugin) Manage plugins. Two pairs of verbs: **`add` / `remove`** edit the manifest (`config/requirements-plugins.txt`) only — the **Docker** path, where a `docker compose restart` triggers a startup reconcile that installs from the manifest (no rebuild) — and **`install` / `uninstall`** also run pip, for dev / source-checkout installs. (The old `led-ticker plugins` is a deprecated alias of `plugin status`.) ```bash # Docker: edit the manifest, then restart led-ticker plugin add pool # + line in requirements-plugins.txt (no pip) led-ticker plugin remove pool # − line (no pip) docker compose restart # installs/uninstalls on the next start — no rebuild # Dev / source checkout: also pip-install now led-ticker plugin install pool # add + pip install led-ticker plugin uninstall pool # remove + pip uninstall led-ticker plugin status # plugins loaded/failed for the config led-ticker plugin list # the catalog ([declared] / [installed]) led-ticker plugin search pool # search the catalog ``` All four management verbs accept a **catalog name or a raw pip spec** (a `git+https://…` URL or a PyPI requirement, like `pip`), default the manifest to `config/requirements-plugins.txt` (run from your project root; `--config ` for a non-standard layout, warned if it’d write outside `config/`), and dedup by plugin while preserving comments. `add`/`install` take `--source git|pypi` and `--unpinned`; all take `--dry-run`. Run these **on the host**, not inside the container — they edit a host file, and the container mounts `./config` read-only, so `docker compose exec led-ticker led-ticker plugin add …` fails. If you run led-ticker purely via Docker and have no host `led-ticker` command, edit `config/requirements-plugins.txt` by hand (`cp config/requirements-plugins.example.txt config/requirements-plugins.txt`) and restart — `docker compose restart`. It’s the same manifest. ### `plugin add` / `plugin remove` (manifest only — Docker) [Section titled “plugin add / plugin remove (manifest only — Docker)”](#plugin-add--plugin-remove-manifest-only--docker) `add` resolves the name to a pip requirement and writes it to `config/requirements-plugins.txt` (pinned to the catalog’s recommended ref by default; a typo close to a catalog name gets a “did you mean …?”). Re-adding the same plugin is idempotent (“already declared” if unchanged). `remove` drops the matching line (idempotent — “not in …” if absent). Neither runs pip — they only edit the manifest. Run `docker compose restart` to apply: a startup reconcile installs/uninstalls from the manifest on the next start (no rebuild needed). The container is read-only at runtime; plugins install onto the `ticker-plugins` volume, not into the image. The bundled pool/baseball/crypto entries currently pin to `@main`, so the default (“pinned”) and `--unpinned` write the same `@main` reference today — pass a tagged pip spec (e.g. `…@v1.2.0`) for a fixed production pin until the catalog ships tags. ### `plugin install` / `plugin uninstall` (manifest + pip — dev / source checkout) [Section titled “plugin install / plugin uninstall (manifest + pip — dev / source checkout)”](#plugin-install--plugin-uninstall-manifest--pip--dev--source-checkout) `install` does what `add` does **and** pip-installs the requirement under led-ticker’s core dependency constraints (a plugin can pull new libraries but can’t move a version core pins). `uninstall` does what `remove` does **and** `pip uninstall`s the distribution. `install --save-only` is a deprecated alias of `add`. Exits with pip’s exit code on a failed install (the manifest is still updated). | Flag | Default | Notes | | ----------------- | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- | | `--source` | first source | (`add`/`install`) `git` or `pypi` — which catalog source to use. | | `--unpinned` | off (pinned) | (`add`/`install`) Write `@main` / a bare PyPI name instead of the catalog ref. (Bundled refs are `@main` today, so this is a no-op for them — see above.) | | `--dry-run` | off | Print the plan without changing anything. | | `--config` / `-c` | (none) | Non-standard layout only: use `requirements-plugins.txt` next to this config instead of `./config/`. | ### `plugin status` [Section titled “plugin status”](#plugin-status) Lists the plugins discovered for a config — both the ones that loaded and any that failed — without opening the panel. For each loaded plugin it prints the namespace, its source, and the surfaces it contributes (widgets, transitions, fonts, or hooks only); failed plugins are listed with their load error. Handy for confirming a freshly installed plugin is being picked up before you deploy. `--config` / `-c` selects the config (defaults to the top-level). Exits `0` — printing `No plugins found.` when the config is absent or lists no plugins — and `2` only if a config that exists can’t be parsed. ### `plugin list` / `plugin search ` [Section titled “plugin list / plugin search \”](#plugin-list--plugin-search-query) `list` prints the bundled catalog — each plugin’s name, summary, and the widgets/transitions it provides — marking each `[declared]` (present in `requirements-plugins.txt`, so it installs on the next restart) and/or `[installed]` (importable in this environment now). `search` filters that catalog by a case-insensitive substring over the name, summary, and provided names. `--config` / `-c` locates the manifest for the `[declared]` check. ## Make targets [Section titled “Make targets”](#make-targets) The repo’s `Makefile` wraps the common dev commands so you don’t have to remember the underlying `uv` / `pnpm` / `docker` invocations. Run `make help` to print the same list straight from the Makefile. ### Development & quality [Section titled “Development & quality”](#development--quality) | Target | What it does | | ---------------- | ------------------------------------------------------------------------------------------- | | `make dev` | `uv sync --extra dev` plus install the pre-commit and pre-push hooks. | | `make hooks` | (Re)install just the pre-commit and pre-push git hooks. | | `make test` | Run pytest with coverage (no Docker or hardware needed). | | `make lint` | Run `ruff check` over `src/` and `tests/`. | | `make typecheck` | Run `pyright` over `src/`. | | `make format` | Run `ruff format` over `src/` and `tests/`. | | `make clean` | Remove build artifacts and caches. Does **not** stop containers — use `make down` for that. | ### Deploy lifecycle [Section titled “Deploy lifecycle”](#deploy-lifecycle) The everyday ladder for running a sign, in roughly the order you use it: `setup` → `build` → `up` → `update` → `restart` → `down`, with `logs` alongside. None of these hard-code a Compose profile — set `COMPOSE_PROFILES=webui` in `.env` to include the web UI. | Target | What it does | | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | | `make setup` | One-command bootstrap: check Docker, seed `config/` + `.env`, and bring the sign up. Usage: `make setup [MODE=try\|deploy]`. | | `make build` | Build the production Docker image only — no start; single image runs on both Pi 4 and Pi 5. Prerequisite for the `*-docker` diagnostics below. | | `make up` | Start the sign from the existing image without rebuilding. | | `make update` | Update a running deploy after `git pull`: rebuild the image at the real version and recreate the services. | | `make restart` | Restart the sign without rebuilding. | | `make down` | Stop and remove the sign’s containers. | | `make logs` | Follow the sign’s logs (Ctrl-C to stop). | ### Try it with no hardware [Section titled “Try it with no hardware”](#try-it-with-no-hardware) | Target | What it does | | --------------- | ---------------------------------------------------------------------------------------------------- | | `make try` | Run led-ticker with **no hardware**: headless engine plus web-UI preview at `http://localhost:8080`. | | `make try-down` | Stop and remove the try-it containers (and their tmpfs volume). | ### Config & hardware diagnostics [Section titled “Config & hardware diagnostics”](#config--hardware-diagnostics) | Target | What it does | | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `make validate` | Run `led-ticker validate` against a config TOML. Usage: `make validate CONFIG=config/config.toml`. | | `make panel-test` | Cycle the panel through full-frame R/G/B/White/Black to diagnose hardware/wiring/driver issues. Usage: `make panel-test [CONFIG=config/config.longboi.toml] [HOLD=2]`. See [panel-test](/tools/panel-test/). | | `make panel-test-docker` | Same as `make panel-test`, but runs inside the production Docker image. Stop the running ticker first (`docker compose stop`). Usage: `make panel-test-docker [CONFIG=…] [HOLD=…]`. | | `make panel-map-reveal` | Paint the chain-calibration pattern (no mapper applied) so physical chain order and panel orientation are visible. Usage: `make panel-map-reveal [CONFIG=…] [HOLD=2]`. See [panel-map](/tools/panel-map/). | | `make panel-map-reveal-docker` | Same as `make panel-map-reveal`, but runs inside the production Docker image. Stop the running ticker first. | | `make panel-map-derive` | Generate a `Remap:` mapper string from a layout file (no hardware needed). Usage: `make panel-map-derive LAYOUT=layout.txt [CONFIG=…]`. See [panel-map](/tools/panel-map/). | | `make panel-map-derive-docker` | Same as `make panel-map-derive`, but runs inside the production Docker image. Stop the running ticker first. Usage: `make panel-map-derive-docker CONFIG=… LAYOUT=/tmp/grid.txt`. | | `make panel-map-verify` | Paint a coherent full-canvas diagnostic to verify a mapper string. Usage: `make panel-map-verify [CONFIG=…] [MAPPER="Remap:…"] [HOLD=2]`. See [panel-map](/tools/panel-map/). | | `make panel-map-verify-docker` | Same as `make panel-map-verify`, but runs inside the production Docker image. Stop the running ticker first. | ### Docs site [Section titled “Docs site”](#docs-site) | Target | What it does | | ---------------------- | ------------------------------------------------------------------------------------------- | | `make docs-dev` | Start the Astro Starlight dev server at `http://localhost:4321/` (also rebuilds demo gifs). | | `make docs-build` | Build the docs site to `docs/site/dist/`. | | `make docs-check-llms` | Build the docs and verify the `llms.txt` Markdown export. | | `make docs-lint` | Lint the docs site (`prettier --check` plus `astro check`). | | `make docs-format` | Auto-format the docs site with `prettier`. | ### Demos & asset generation [Section titled “Demos & asset generation”](#demos--asset-generation) | Target | What it does | | ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `make render-demo` | Render a single demo gif. Usage: `make render-demo CONFIG=path/to.toml OUT=out.gif`. | | `make plan-gif` | Recommend a render `--duration` for a demo and flag a `# render-duration:` header that would clip. Usage: `make plan-gif CONFIG=path/to.toml`. See [gif-plan](/tools/gif-plan/). | | `make render-emoji-previews` | Re-generate the per-slug emoji preview PNGs in `docs/site/public/emoji/`. | | `make render-long-demos` | Render every long-running widget demo (data-fetch widgets) into `docs/site/public/demos-long/`. | | `make render-long-demo` | Render one long-running demo by name. Usage: `make render-long-demo NAME=widget-weather`. | | `make render-pinned-demos` | Render every pinned short-render demo into `docs/site/public/demos-pinned/`. | | `make derive-phoenix` | Re-derive `config/assets/phoenix.*` from the vendored CC0 source. | | `make derive-pride` | Re-generate `config/assets/pride.*` (CC0 rainbow flag). | | `make derive-heart-tunnel` | Re-generate `config/assets/heart-tunnel-opaque.jpg` (CC0 heart-tunnel source). | | `make setup-demo-fonts` | Download the Atkinson Hyperlegible fonts into `docs/site/demos-long/fonts/`. | The `render-long-demos` target only runs locally — the demos make live HTTP calls and some need API keys that aren’t available in CI. Source TOMLs live in `docs/site/demos-long/`; rendered output is committed to `docs/site/public/demos-long/`. The `render-pinned-demos` target also runs locally for the same reason — pinned gifs are stable showcases on widget pages, intentionally not regenerated on every deploy. Source TOMLs live in `docs/site/demos-pinned/`; rendered output is committed to `docs/site/public/demos-pinned/`. Both targets are fail-soft: a single broken TOML doesn’t block the rest from rendering — failures get listed at the end and the target exits non- zero. ## Running with Docker Compose [Section titled “Running with Docker Compose”](#running-with-docker-compose) The production deployment uses `docker compose`. With the repo cloned on a Pi and a `config/config.toml` in place, the standard invocation is: ```bash docker compose up -d ``` The compose file mounts `./config` read-only into the container so you edit the TOML on the host and the container picks it up on restart. Its `restart: unless-stopped` policy brings the ticker back up automatically on boot and after a crash. ## Sharp edges [Section titled “Sharp edges”](#sharp-edges) ### `--led-*` flags belong to the `rgbmatrix` library, not `led-ticker` [Section titled “--led-\* flags belong to the rgbmatrix library, not led-ticker”](#--led--flags-belong-to-the-rgbmatrix-library-not-led-ticker) The `led-ticker` CLI accepts `--config` / `-c`, `--backend`, and the `validate` subcommand’s `path`, `--json`, `--strict`, `--fix`, and `--list-fields`. Hardware tuning — panel geometry, GPIO mapping, brightness, RP1 mode — is configured through the `[display]` block in your TOML, not via command-line flags. The `rgbmatrix` library’s own `--led-*` CLI flags exist (and `[display]` maps onto them internally) but you don’t pass them to `led-ticker`. See [Reference: Config options](/reference/config-options/) for the `[display]` field list. ### The test suite runs without a real Pi [Section titled “The test suite runs without a real Pi”](#the-test-suite-runs-without-a-real-pi) The repo ships test stubs for the C-only `rgbmatrix` module so the entire suite runs on macOS / CI without hardware. The stubs are found automatically: `pyproject.toml` sets `[tool.pytest.ini_options] pythonpath = ["tests/stubs"]`, so both `make test` and a direct `pytest` (e.g. from your editor’s test runner) put the stub `rgbmatrix` on the import path — no `PYTHONPATH` env var to set yourself. See also * [reference/config-options](/reference/config-options/) * [tools/validate](/tools/validate/) * [tools/render-demo](/tools/render-demo/) * [tools/gif-plan](/tools/gif-plan/) * [tools/panel-map](/tools/panel-map/) # Reference: Config options > A cross-cutting reference of every TOML knob in led-ticker, organized by config section. This page is the cross-cutting reference for every TOML knob in led-ticker, grouped by config section. Per-widget options live on each widget’s page — this page covers the top-level blocks that wrap them: `[display]`, `[title]`, `[transitions]`, `[[playlist.section]]`, `[[source]]`, `[busy_light]`, and `[web]`. Field names and defaults match the dataclasses in `src/led_ticker/config.py`. For per-widget knobs see [Widgets](/widgets/). ## Coercion behavior [Section titled “Coercion behavior”](#coercion-behavior) Some config slips that would crash startup are silently corrected with a warning. Warnings show up in `led-ticker validate` output AND in the runtime log — fix the source to silence them. **Numeric strings → numbers.** Every integer or float field accepts a string-of-digits in addition to a bare number: ```toml font_size = "25" # works (coerced to 25, warns) font_size = 25 # canonical, no warning ``` Applies to all numeric fields across `[display]`, `[[playlist.section]]`, and per-widget configs — including `rows`, `cols`, `chain_length`, `parallel`, `gpio_slowdown`, `pwm_bits`, `pwm_lsb_nanoseconds`, `pwm_dither_bits`, `rp1_pio`, `font_size`, `font_threshold`, `hold_time`, `brightness`, `content_height`, `scale`, `loop_count`, `scroll_step_ms`, `start_hold`, `separator_font_size`, and others. **Closed-set enum strings → case-insensitive.** Fields with a fixed value set (`text_align`, `text_valign`, `image_align`, `scroll_direction`, `fit`, `bottom_text_scroll`, `easing`) are case-insensitive. The canonical form is lowercase: ```toml image_align = "Left" # works (coerced to "left", warns) image_align = "left" # canonical, no warning ``` **What’s NOT coerced.** Colors (`[r, g, b]`), booleans, file paths, and free-text fields stay strict — typos here surface as hard errors rather than silent fixes. The `style` keys inside inline-table providers (`font_color = {style="rainbow", ...}`) also stay case-sensitive. ## `[display]` [Section titled “\[display\]”](#display) Hardware and panel-layout settings. Most of these map straight onto `rgbmatrix` library options. | Field | Type | Default | Notes | | -------------------------- | ------ | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `rows` | int | `16` | Panel row count (per panel, not total across the chain). 16 for 16x32 panels; 32 for P3 32x64 panels. | | `cols` | int | `32` | Panel column count (per panel). 32 for 16x32; 64 for P3 32x64. | | `chain_length` | int | `1` | Number of panels chained together. The smallsign reference uses 5; the bigsign uses 8. | | `parallel` | int | `1` | Number of parallel panel chains. Both reference builds use 1. | | `pixel_mapper_config` | string | `""` | `rgbmatrix` Remap string for non-trivial layouts (e.g. the bigsign’s 2x4 vertical-serpentine mapping). Empty string = no remap. | | `default_scale` | int | `1` | Logical-to-physical scaling. `1` matches the smallsign reference (no scaling). `4` matches the bigsign (`ScaledCanvas` blows 16-tall content up to 64). | | `brightness` | int | `100` | Panel brightness, 0-100. Both reference configs use `60`. | | `gpio_slowdown` | int | `1` | GPIO timing slowdown. Smallsign uses `2`; bigsign uses `3` (paired with the default RIO backend). Raise on flicker. | | `hardware_mapping` | string | `"adafruit-hat"` | rgbmatrix GPIO pinout. `"adafruit-hat"` covers the Adafruit HAT and bonnet. | | `pwm_bits` | int | `11` | PWM bit depth. Drop to `8` on the bigsign for \~8x faster refresh at a small color cost. | | `pwm_lsb_nanoseconds` | int | `130` | PWM LSB timing; raise toward `200+` if colors look wrong. | | `pwm_dither_bits` | int | `0` | Temporal dithering depth (0=off, 1–2). Spreads PWM energy more evenly across rows; try `1` or `2` if a specific row appears brighter than its neighbors at sub-100% brightness. | | `show_refresh_rate` | bool | `false` | Log measured refresh Hz to stderr — useful when tuning the bigsign. | | `disable_hardware_pulsing` | bool | `false` | Disable hardware PWM and use a CPU fallback. Roughly 5x slower; almost always leave at `false`. | | `hot_reload` | bool | `true` | Watch `config.toml` and live-reload sections/widgets/transitions/schedule/brightness without restarting (`[display]`, `[busy_light]`, `[plugins]`, `[web]` changes still need a restart). Set `false` to disable. | | `rp1_pio` | int | `0` | Pi 5 only. `0` = RIO backend (library default — faster refresh, more CPU). `1` = force the PIO backend (lower CPU, slower refresh). Ignored on Pi 4. | | `limit_refresh_rate_hz` | int | `0` | Cap the hardware refresh rate in Hz. `0` = unlimited. Useful on long chains where uncapped RIO-mode refresh causes visible motion artifacts — try `100` as a starting point. | | `multiplexing` | int | `0` | Panel scan-row wiring scheme. `0` = direct. Try `1`–`5` if the bottom half of the panel shows inverted or garbled content. See the rgbmatrix docs for the full list. | | `row_address_type` | int | `0` | Row address type. `0` = direct (default). Change only if the panel uses a non-standard address decoder (AB-addressed, ABC-shifted, etc.). | | `panel_type` | string | `""` | Driver IC init sequence. Set to `"FM6126A"` or `"FM6127"` for panels that use those chips (common on cheap P2/P3 AliExpress panels). Without it, FM6126A panels power up in a bad state and show the bottom half mirrored or garbled. | | `led_rgb_sequence` | string | `"RGB"` | RGB channel order. Change to `"RBG"`, `"GRB"`, etc. if colors appear wrong — e.g. purple/blue tint (missing green) often means green and blue are swapped; try `"RBG"`. | | `backend` | string | `"rgbmatrix"` | Rendering backend. `"rgbmatrix"` drives real hardware panels. `"headless"` runs with no panel (useful for development/testing without a Pi). Plugins may register additional backends. | | `schedule` | table | (disabled) | Optional brightness schedule. Nested `[display.schedule]` block — see below. | These are the common knobs. The full set of `rgbmatrix` library options is broader — see `CLAUDE.md` for the additional Pi-5 tuning notes and what each setting interacts with. ## `[display.schedule]` [Section titled “\[display.schedule\]”](#displayschedule) Optional brightness schedule. Enabled by setting `[display.schedule]` with `enabled = true`. See [Display scheduling](/concepts/display/) for the full guide. | Field | Type | Default | Notes | | ---------- | ------ | ------- | --------------------------------------------------------------------------------------------------------------------------------- | | `enabled` | bool | `false` | Master switch. When `false` the schedule is not loaded and brightness is never adjusted by the scheduler. | | `timezone` | string | `""` | IANA timezone name (e.g. `"America/New_York"`). Empty string = system local time. Set this explicitly — fresh Pis are often UTC. | | `windows` | array | `[]` | List of `[[display.schedule.windows]]` tables. Each defines a time range, brightness, and optional day-of-week filter. See below. | ### `[[display.schedule.windows]]` [Section titled “\[\[display.schedule.windows\]\]”](#displayschedulewindows) Each window is a `[[display.schedule.windows]]` table entry: | Field | Type | Default | Notes | | ------------ | ------------ | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `start` | string | (required) | Window start time in `"HH:MM"` 24-hour local wall-clock format. | | `end` | string | (required) | Window end time. When `end < start` (e.g. `start = "23:00"`, `end = "07:00"`) the window wraps past midnight. | | `brightness` | int | (required) | Panel brightness to apply, 0–100. `0` makes the panel appear dark (≈ zero power draw from the LEDs); the Pi keeps running. | | `days` | string array | `[]` | Days this window is active: `["mon", "tue", "wed", "thu", "fri", "sat", "sun"]`. Empty list means every day. For midnight-wrapping windows (`start > end`), the window is anchored to its start day — see [Day filtering](/concepts/display/#day-filtering). | ## `[title]` [Section titled “\[title\]”](#title) Title-card timing. | Field | Type | Default | Notes | | ------- | ---- | ------- | --------------------------------------------------------------------------------------------- | | `delay` | int | `5` | Seconds the section title (e.g. “#DevOps News”) holds before the section’s first widget runs. | ## `[transitions]` [Section titled “\[transitions\]”](#transitions) Global defaults for inter-widget and inter-section transitions. | Field | Type | Default | Notes | | --------------------- | -------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `default` | string | `"cut"` | Fallback inter-widget transition. Overridden per-section by `transition` or `widget_transition`. | | `duration` | float | `0.5` | Default transition duration in seconds. Sprite-trail transitions (pokeball, nyancat, scroll) typically want a longer value. | | `easing` | string | `"linear"` | Default easing curve. Accepted values: `linear`, `ease_out`, `ease_in_out`. | | `transition_fps` | float | `null` | Animation frames per second for all transitions. `null` uses the built-in default (20 fps). Raise to 30–40 on large panels to reduce choppiness. Warn if < 5 or > 120. | | `between_sections` | string / table | `"cut"` | Fallback transition fired at section boundaries. Lowest priority in the entry-transition chain — overridden by a section’s `entry_transition` or explicitly-set `transition` (see Tips below). | | `separator_color` | list / string | `null` | Color of the `scroll` transition’s separator mark. Same shapes as a widget `font_color` (`[r,g,b]`, `"rainbow"`, `"color_cycle"`, `{style=…}`). Only honored by `type = "scroll"`; rejected on other transition types. `null` defaults to white. | | `separator` | string | `null` | The `scroll` transition’s separator glyph. `null` = the default dot; `""` renders nothing (gap only). Only honored by `type = "scroll"`. | | `separator_font` | string | `null` | Font (BDF alias or hires name) for the scroll `separator` glyph. `null` uses the default 6×12 BDF font. | | `separator_font_size` | int | `null` | Pixel size for a hires `separator_font` (ignored for BDF). Required when `separator_font` is a hires font. | | `separator_size` | int | `null` | Size (logical px) of the `scroll` transition’s separator dot. `null` = the default 2. No effect on a glyph separator. Only honored by `type = "scroll"`. | Both `default` and `between_sections` accept either a bare string (transition name) or an inline table — e.g. `between_sections = { type = "wipe_left", duration = 0.8, easing = "ease_out" }`. ## `[[playlist.section]]` [Section titled “\[\[playlist.section\]\]”](#playlistsection) Each `[[playlist.section]]` is one item in the playlist. Sections run in order, then the playlist loops. | Field | Type | Default | Notes | | ---------------------- | ---------------------------- | --------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `mode` | string | `"ticker"` | One of `ticker`, `one_at_a_time`, `slideshow`. See [Sections and modes](/concepts/sections-and-modes/). | | `loop_count` | int | `1` | How many times to play this section’s widgets before moving on. `0` repeats forever within the section. | | `hold_time` | float | `3.0` | Seconds to hold each widget in `slideshow` mode. Ignored by `ticker` / `one_at_a_time`. | | `continuous_scroll` | bool | `false` | Skip the held pause for overflowing text in scroll modes. | | `transition` | string / table | inherits global `default` | Inter-widget transition for `slideshow` mode. When explicitly set, ALSO becomes the entry transition for this section (see Tips). Accepts a string (`"wipe_left"`) or an inline table — see “Inline-table transition form” below. | | `entry_transition` | string / table | `null` | Override the transition used when **this section enters** (the inter-section boundary). Takes precedence over both `transition` and the global `between_sections`. Useful when you want a dramatic entry but a quiet inter-widget swap, or vice versa. Same string / inline-table forms as `transition`. | | `widget_transition` | string / table | `null` | Override the transition used for **inter-widget swaps within this section**. Takes precedence over `transition`. Does not affect the section’s entry. Same string / inline-table forms as `transition`. | | `transition_duration` | float | inherits global | Per-section override for the `transition` duration. Does not affect `entry_transition` or `widget_transition` (set those durations inside their inline-table form). | | `transition_fps` | float | `null` | Per-section animation fps override. Equivalent to setting `transition_fps` inside the `transition = {...}` dict. Inherits from `[transitions].transition_fps` if not set. | | `transition_color` | `[r, g, b]` | `null` | Custom color for color-aware transitions (e.g. `color_flash`, `wipe_*`). | | `scale` | int | `display.default_scale` | Per-section logical-to-physical scaling override. Useful for letterboxed countdowns at `scale = 2` on the bigsign. | | `content_height` | int | `16` | Logical canvas height in rows. Hard ceiling: `content_height × scale ≤ panel_h_real` (see Tips). | | `bg_color` | `[r, g, b]` | `null` | Section-level background color. Widgets inherit this when they don’t set their own `bg_color`. | | `scroll_step_ms` | int | `null` (= 50 ms) | Milliseconds per logical pixel of scroll. Lower = faster marquee. Applies to `ticker`, `one_at_a_time`, and the post-hold scroll on `slideshow` mode. | | `separator` | string | `null` (= white `•`) | Per-section override for the bullet between `ticker` widgets. Empty string `""` renders as two spaces (no glyph, minimum gap). Non-empty strings render as-is — include surrounding spaces if you want padding (e.g. `" * "`). On bigsign (`default_scale > 1`), the default separator renders as a smooth hi-res circle painted at physical resolution; set explicitly (e.g. `separator = "•"`) to opt out and use BDF rendering instead. Rejected on non-`ticker` modes. | | `transition_colors` | `[[r,g,b], ...]` | `null` | Multi-color list for transitions that cycle through colors (e.g., `wipe_random` with multiple sweep colors). Plural form of `transition_color`. | | `separator_font` | string | `null` | Font name (BDF alias or hires file) for the separator glyph. `null` uses the default 6×12 BDF. Useful for matching the section’s widget font. | | `separator_font_size` | int | `null` | Required when `separator_font` is a hires font. Ignored for BDF (fixed cell height). | | `separator_size` | int | `null` | Size (logical px) of the ticker-mode separator circle (radius = size ÷ 2). `null` = the default 8. Only affects the bigsign hi-res circle; the smallsign BDF `•` is unaffected. Only honored by `mode = "ticker"`. | | `separator_color` | `[r, g, b]` / string / table | `null` (= white) | Color for the separator. When `separator` is unset on bigsign, this colors the hi-res circle. When `separator` is set explicitly, it colors the BDF glyph. Accepts the same shapes as widget `font_color`: constant `[r, g, b]`, `"rainbow"`, `"color_cycle"`, or `{style = "gradient", from = [...], to = [...]}`. | | `start_hold` | float | `null` (inherits `[title] delay`) | Pre-roll delay (seconds) before this section’s first widget begins scrolling. Only honored on `ticker` / `one_at_a_time`. Setting it on `slideshow` is a validation error. `start_hold = 0.0` makes the section start scrolling immediately, leaving the global `[title] delay` unchanged for other sections. | | `transition_specified` | bool | `false` | Internal flag set by the loader when the user wrote `transition = ...` in this section’s TOML. You don’t write this — it’s in the dataclass for completeness. | ### Inline-table transition form [Section titled “Inline-table transition form”](#inline-table-transition-form) When the transition needs more than just the type, prefer the inline-table form: `transition = { type = "wipe_left", duration = 0.8, easing = "ease_out", color = [255, 0, 0] }`. The flat sibling form (`transition = "wipe_left"` + `transition_duration = 0.8`) is equivalent and remains fully supported. `transition_specified` lets the engine tell user-written `transition = X` apart from the inherited default — the distinction drives entry-transition selection (see Tips). ## `[playlist.section.title]` [Section titled “\[playlist.section.title\]”](#playlistsectiontitle) A title block accepts the same field surface as a `message` widget with one alias: `color` is the title-specific spelling of `font_color`. Both work, and only on title blocks — writing `color = "random"` on a regular `[[playlist.section.widget]]` is a configuration error (the alias doesn’t apply outside titles). The only other difference from a regular widget is that it’s held for `[title] delay` seconds before the section’s first widget runs. See [the message widget page](/widgets/message/) for the full field list. ## `[[playlist.section.widget]]` [Section titled “\[\[playlist.section.widget\]\]”](#playlistsectionwidget) Per-widget options live on each widget’s page. See [Widgets](/widgets/). ## `[[source]]` [Section titled “\[\[source\]\]”](#source) Each `[[source]]` block declares a named value source that widget `text =` fields can reference with the `:id:` token syntax. Sources are global — they are not nested inside any section. You can declare as many `[[source]]` blocks as you need. See [Value tokens](/concepts/value-tokens/) for the full guide. | Field | Type | Required | Notes | | ---------- | ------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | string | yes | Token name. Must match `[a-z_][a-z0-9_.]*` to be usable as a `:token:` — an id that doesn’t match the pattern is accepted by the validator but won’t be recognized at display time (the `:...:` renders as literal text). Must not equal an existing emoji slug; duplicate ids are rejected. | | `type` | string | yes | Source class. Built-in: `"clock"`, `"date"`, `"static"`. Plugins may register additional types via `api.source`. | | `format` | string | no | strftime format string. Optional for `clock` and `date` (default `"%H:%M"`); ignored by `static`. | | `timezone` | string | no | IANA timezone name (e.g. `"America/New_York"`). Applies to `clock` and `date`. Omit to follow the Pi’s system clock (often UTC on a fresh Pi). | | `value` | string | see note | Fixed string. Required for `static`; ignored by `clock` and `date`. | All sources refresh once per second. The version counter increments only when the computed value actually changes, so constant-width clock formats (`%H:%M`) never cause a layout reflow. ## `[busy_light]` [Section titled “\[busy\_light\]”](#busy_light) A persistent corner dot painted as an overlay over every section and transition while a local file exists. Disabled by default. See [Busy light](/concepts/busy-light/) for the full guide, including the Docker `file_path` gotcha. | Field | Type | Default | Notes | | --------------- | ----------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `enabled` | bool | `false` | Master switch. When `false`, nothing is built and there is zero per-frame cost. | | `file_path` | string | `"~/.busy"` | Light is on while this file exists; `~` expands. Under Docker, use the bind-mounted path `/code/config/.busy` and toggle `config/.busy` on the host. | | `poll_interval` | float | `5.0` | Seconds between file checks. | | `corner` | string | `"top_right"` | One of `top_left`, `top_right`, `bottom_left`, `bottom_right`. Other values rejected at config load. | | `color` | `[r, g, b]` | `[255, 0, 0]` | Three ints, each `0`–`255`. Length/range rejected at config load. | | `size` | int | `4` | Dot side in physical pixels (`>= 1`). \~4 on the 16-tall smallsign, \~8–10 on the 64-tall bigsign/longboi. | | `source` | string | `"file"` | `"file"` (poll a local file) or `"http"` (remote push from a LAN HTTP call). | | `http_host` | string | `"0.0.0.0"` | Listen address when `source = "http"`. `0.0.0.0` = all interfaces. | | `http_port` | int | `8081` | Listen port when `source = "http"`. Range 1–65535. Defaults to `8081` so it doesn’t collide with `[web]`’s `8080`. | | `token` | string | `""` | Shared secret for the HTTP source. Empty = open (trusted LAN only). Prefer `LED_TICKER_BUSY_TOKEN` in `.env`; this field is a fallback used only when that env var is unset, and logs a warning when so used. | | `ttl_seconds` | float | `0.0` | HTTP source: default auto-clear seconds for a `state=on` that omits `?ttl=`. Per-request `?ttl=N` overrides it. `0` = stay on until explicit off. | ## `[web]` [Section titled “\[web\]”](#web) The optional read-only web status dashboard — a browser UI that shows what the sign is currently displaying, exposes the live config with secrets redacted, and lets you paste a candidate config through the validator. Presence of the `[web]` block (even empty) enables status publishing in the display process and allows the `led-ticker webui` sidecar to serve it. Absence disables the feature entirely — existing configs with no `[web]` block are unaffected. See [Web status UI](/concepts/web-status-ui/) for setup and usage. | Field | Type | Default | Notes | | --------------- | ------ | ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `http_host` | string | `"0.0.0.0"` | Interface the sidecar binds. `"0.0.0.0"` listens on all interfaces (all LAN addresses); `"127.0.0.1"` limits to localhost only. | | `http_port` | int | `8080` | HTTP port the sidecar serves. The compose service uses host networking, so the Pi’s port is exposed directly. | | `token` | string | `""` | Optional shared secret. Empty = open (trusted-LAN posture). Non-empty requires an `X-Web-Token` header or `?token=` query parameter on every request. Prefer `LED_TICKER_WEB_TOKEN` in `.env`; this field is a fallback used only when that env var is unset, and logs a warning when so used. | | `status_path` | string | `"/run/led-ticker/status.json"` | Path where the display process writes its status snapshot; the sidecar reads the same file. Must match between both processes. | | `allow_restart` | bool | `false` | Expose a “Restart display” button in the web UI. When `true`, clicking the button drops a marker file that the display process detects on its next loop pass and calls `sys.exit(0)`; Docker’s `restart: unless-stopped` brings it back. Set to `false` (default) to disable the control entirely. | ## Tips [Section titled “Tips”](#tips) ### Transition precedence: entry vs. inter-widget [Section titled “Transition precedence: entry vs. inter-widget”](#transition-precedence-entry-vs-inter-widget) Two independent transition slots fire per section: one when the **section enters** (inter-section boundary) and one for **swaps between widgets** within the section. Each slot resolves through its own precedence chain: **Entry transition** (when this section appears): `entry_transition` → `transition` (if explicitly set on this section) → global `between_sections` **Inter-widget transition** (swaps within this section): `widget_transition` → `transition` (if explicitly set on this section) → global `default` The key implication: writing `transition = "pokeball.forward"` on a section sets **both** slots to that transition — it fires when the section enters AND between every widget inside it. This is usually what you want for single-widget sections. For multi-widget sections where you want a dramatic entry but a quiet per-widget swap, use `entry_transition` + `widget_transition` independently instead of `transition`. If you want the global `between_sections` to fire on entry, leave `transition` unset (or use `entry_transition` explicitly). ### `content_height × scale ≤ panel_h_real` [Section titled “content\_height × scale ≤ panel\_h\_real”](#content_height--scale--panel_h_real) The wrapper centers a logical canvas of height `content_height × scale` on the real panel. On the bigsign at `scale = 4` and a 64-tall panel, that means `content_height ≤ 16`. Push above and the wrapper’s vertical offset goes negative — the logical canvas is taller than the panel — and the top + bottom rows of your content silently clip. BDF text is forgiving because cells sit near the vertical center, but hi-res emoji and large hi-res fonts surface the clip immediately. For per-row breathing room use `text_y_offset` on the widget rather than over-sizing `content_height`. See [Hardware: Bigsign](/hardware/bigsign/) for the full discussion. See also * [reference/cli](/reference/cli/) * [concepts/sections-and-modes](/concepts/sections-and-modes/) * [widgets](/widgets/) # Frame counters > Per-effect counters, restart-on-visit vs continuous phase, and how transitions pause them. Every animated effect — rainbow text, color cycle, typewriter, rainbow chase border — advances a frame counter that ticks once per 50 ms engine iteration. Each effect on a widget gets its own independent counter: a `message` with `font_color = "rainbow"`, `border = "rainbow"`, and `animation = "typewriter"` carries three counters, one per effect, that advance separately and never interfere. Most users never need to think about this model directly. The defaults produce the right visual behavior. This page is for two narrower audiences: users debugging unexpected restart behavior, and developers implementing a new effect class. ## Why per-effect counters [Section titled “Why per-effect counters”](#why-per-effect-counters) If all effects on a widget shared one counter, a typewriter restart at each loop boundary would also reset the rainbow hue phase mid-cycle — producing a visible color jump at the exact moment the typewriter retypes. Separate counters mean each effect controls its own restart policy without any coupling. The `frame_for("border")` call the border effect receives is completely independent of the `frame_for("animation")` call the typewriter effect receives, even though both sit on the same widget object. ## Restart-on-visit vs continuous [Section titled “Restart-on-visit vs continuous”](#restart-on-visit-vs-continuous) Each effect class declares a `restart_on_visit` class attribute. The engine’s `reset_frame()` call (which happens at visit entry — i.e., every time the widget begins a new display pass) resets only the counters for effects that opted into restart. | Effect | `restart_on_visit` | | ------------------------------------------ | -------------------------------------------------- | | `Typewriter` (animation) | `True` — retypes from scratch on every visit | | `Rainbow` (font\_color) | `False` — hue sweep advances continuously | | `ColorCycle` (font\_color) | `False` — whole-string cycle advances continuously | | `Gradient` (font\_color) | n/a — frame-invariant, no counter | | `Constant` (`_ConstantColor`, font\_color) | n/a — frame-invariant, no counter | | `RainbowChaseBorder` (border) | `False` — chase phase advances continuously | | `ConstantBorder` (border) | n/a — frame-invariant, no counter | **Restart on visit (`True`)** means the effect counter goes to zero whenever the section’s run loop begins showing this widget — including each iteration of `loop_count > 1`. Typewriter opts into this because it is a reveal: it should retype from scratch each time it appears, not resume mid-word. **Continuous phase (`False`)** means the counter is preserved across visit boundaries and `loop_count` iterations. Rainbow, ColorCycle, and RainbowChaseBorder opt into this so their visual flow has no discontinuity when the widget appears again. If the hue is at 180° when the first loop ends, it starts from 180° on the second loop — the animation reads as uninterrupted. A widget can carry both restart and continuous effects simultaneously. A `message` with `animation = "typewriter"` and `font_color = "rainbow"` and `loop_count = 2` will retype from scratch on the second loop (typewriter resets) while the rainbow hue picks up exactly where it left off (rainbow does not reset). ## Section transitions always reset [Section titled “Section transitions always reset”](#section-transitions-always-reset) `restart_on_visit` governs what happens between iterations of the **same widget** within a section. Section-level transitions are different: when the engine moves between sections, all effect state is reset to a fresh starting point, even for continuous-phase effects. A rainbow border that has been chasing for 20 seconds starts its chase over from position 0 when the section appears again after other sections have played. The practical consequence is that continuous-phase effects behave continuously **within a section’s lifetime** (across `loop_count` repetitions) but **not** across the full playlist cycle. That boundary is by design — sections are self-contained units, and users expect them to look the same each time they appear. ## Frame pause during transitions [Section titled “Frame pause during transitions”](#frame-pause-during-transitions) When a transition is compositing the outgoing and incoming widgets (dissolve, wipe, push, etc.), the frame counter for each affected widget is paused. `pause_frame()` is called before the transition loop begins; `resume_frame()` is called in the `finally` block when it ends. This prevents the widget’s animation from advancing during the N frames that the compositing loop runs — otherwise a typewriter widget that was at character 5 of 12 when the transition started might be at character 8 by the time it finishes, causing the text to jump forward the instant the transition resolves. The pause is automatic and applies to every frame-aware widget. Nothing in TOML or widget code needs to opt into it. ## Implementing a new effect class [Section titled “Implementing a new effect class”](#implementing-a-new-effect-class) If you are adding a new `ColorProvider` or animation effect: 1. Set `restart_on_visit: ClassVar[bool]` on the class. Default to `True` (conservative) unless the effect is explicitly designed to carry phase across visits. 2. Set `frame_invariant: ClassVar[bool] = True` if the effect produces the same output regardless of `frame` (e.g. a static gradient or constant color). Frame-invariant effects skip the per-tick redraw loop and allow the static-text fast path. 3. Do not read `widget._frame_count` directly. Read `widget.frame_for("your_attr")` — the per-effect counter that follows the correct restart policy for your class. See also * [concepts/animations](/concepts/animations/) * [concepts/borders](/concepts/borders/) * [concepts/color-providers](/concepts/color-providers/) # Sign Showcase > Real led-ticker signs running out in the world. Realistic sign configurations running led-ticker. Submit your own via the link at the bottom of this page. ## Firebird Yoga [Section titled “Firebird Yoga”](#firebird-yoga)  Note Placeholder image — real photos coming soon. | | | | ------------------- | --------------------------------------------- | | **Sign type** | bigsign | | **Location** | storefront window | | **Hardware** | Pi 5 + 8× P3 32×64 | | **Notable widgets** | `rss.feed`, `two_row`, custom messages, `gif` | Firebird Yoga is a neighborhood yoga studio whose street-facing window runs led-ticker as a 256×64 storefront display. The sign cycles brand info, the studio’s social handle on a held top row + scrolling class schedule on the bottom (`two_row`), upcoming session blurbs as plain `message` widgets, and short looping `gif` clips between sections. The palette leans on the Instagram magenta (`[225, 48, 108]`) for the social handle, with the phoenix-warm palette (flame/amber/cream) for headline text, and `font_color = "rainbow"` on the headline hold plus rainbow borders so the storefront hero stands out against the steadier brand-colored content. The bigsign runs at `default_scale = 4` with a custom `pixel_mapper_config` for the 2×4 vertical-serpentine panel layout. The display runs daily during studio hours on a Raspberry Pi 5 behind the storefront, configured from a single `config.toml` and brought back up automatically by Docker (`restart: unless-stopped`) if the process exits. The same image runs in dev on a Pi 4 + smallsign for layout iteration before promoting changes to the storefront. ## Submit your sign [Section titled “Submit your sign”](#submit-your-sign) Got a sign running led-ticker? Submit a photo + short description via the [issue template](https://github.com/JamesAwesome/led-ticker/issues/new?template=submit-sign.yml) and we’ll add it to the showcase. See also * [getting-started](/getting-started/) * [hardware/smallsign](/hardware/smallsign/) * [hardware/bigsign](/hardware/bigsign/) # Tool: creating-a-config skill > An interactive 3-mode wizard that builds, extends, or refines a led-ticker config.toml without you needing to memorize the widget catalog or the gotcha list. Unlike the other entries in this section (`render-demo` and `validate` are both CLI tools you run from a terminal), `creating-a-config` is a **Claude Code skill** — an instruction set the AI follows when you ask it to build or refine a `config.toml`. Triggered by natural-language requests like “build me a config”, “add weather to my sign”, or “fix the colors”, it runs a structured Q\&A to assemble or revise the TOML, then validates the result before writing. The skill definition lives at [`.claude/skills/creating-a-config/SKILL.md`](https://github.com/jamesawesome/led-ticker/blob/main/.claude/skills/creating-a-config/SKILL.md), with reference material in [`.claude/skills/creating-a-config/references/`](https://github.com/jamesawesome/led-ticker/tree/main/.claude/skills/creating-a-config/references) (snippets, hardware guide, decision rules, asset handling, transitions, widgets). In Claude Code it surfaces as the `/creating-a-config` slash command. The skill is platform-agnostic — anywhere a Claude agent can read the SKILL.md (Claude Code, Claude.ai, the Anthropic API), the same flow applies. It exists because configs have a long tail of sharp edges — `content_height` ceilings, `text_align="scroll"` + `fit="stretch"` collisions, font-size vs viewing-distance mismatches, brand-font defaults that need to land on every text widget — and the skill threads all of them through a structured Q\&A so you don’t have to remember them. The output of every run is verified against [`led-ticker validate`](/tools/validate) before anything is written. ## Modes [Section titled “Modes”](#modes) The skill detects which mode to run based on the user’s intent and the presence of an existing `config/config.toml`. If the intent is ambiguous, it asks. ### `new` [Section titled “new”](#new) For starting a config from scratch. Runs as a 3-phase wizard: **Phase 1 — Outline.** The skill asks 7 questions covering: sign target (small vs bigsign), use-case category, viewing distance, content sources (multi-select), brand presence, tone, and cadence. The answers drive section selection and brand-font defaults for the rest of the run. After all 7 answers it proposes a section list — one section per content source — and lets you confirm, add, remove, or reorder. **Phase 2 — Per-section pass.** For each confirmed section, the skill looks up a snippet keyed by `(use_case × widget × sign_target)` in `references/snippets.md`, asks only the widget-specific questions that snippet’s “must customize” list calls for, collects any required assets (fonts, images), writes the section TOML, and runs `led-ticker validate config/config.toml --json` against the in-progress config. Any errors or warnings are surfaced as flag-and-ask items, citing the rule and fix from the validator output. Then a quick “looks good?” before moving on. **Phase 3 — Polish.** Five-to-seven questions on the global knobs: default transition + duration + easing, `between_sections` transition, default `hold_time`, brightness, bigsign refresh tuning (only asked when sign=bigsign and tone=info-dense), and save destination. Final validation runs against the assembled config. The file is then written, and you’re prompted to optionally activate it as the live `config/config.toml` (with a `.bak` backup of any existing file). ### `add` [Section titled “add”](#add) For appending a section to an existing config. The skill reads `config/config.toml` and infers the sign target, brand colors, default transition, and use case from the existing widgets — e.g. `baseball.scores` widgets imply a sports config, multiple `rss.feed` + `weather.current` implies a personal feed, a single panel-filling `gif` implies an art piece. If the inference is uncertain, it asks. The inferred use case then drives the same snippet lookup as `new` Phase 2. After writing the new section, the skill asks where to insert (end / before section N / after section N), shows a unified diff, and applies the edit only on approval. The first in-place edit per session writes a `config/config.toml.bak`. ### `refine` [Section titled “refine”](#refine) For symptom-driven tuning of a config that’s already running. The skill reads `config/config.toml`, runs the validator to cache a base violation list, and then asks a single multi-select question with these stock symptoms: * “Too small to read at viewing distance” * “Too aggressive / busy” * “Too slow / too much dead time” * “Too fast / can’t read it” * “Wrong colors / bad contrast” * “Image fit looks bad” * “Border / animation feels off” * “Other (free text)” Each selected symptom maps to a specific delta — e.g. “too small at far distance + bigsign + currently BDF” → migrate to hires Inter at `font_size = 24–32`; “too aggressive / busy” → swap per-char rainbow for color\_cycle, drop animated borders, lengthen `hold_time` by 50%. After the symptom-driven edits, the cached validator violations are surfaced as flag-and-ask items so you can clean them up in the same pass. Each delta is shown as a unified diff, applied only on per-delta approval. ## How violations are surfaced [Section titled “How violations are surfaced”](#how-violations-are-surfaced) The skill never silently auto-fixes a violation. Every problem the validator surfaces — and every pitfall the skill’s own pass through `references/decision-rules.md` catches — is shown to you with the rule id and a one-line fix. You approve or skip each one. This applies at every checkpoint: per-section in `new` Phase 2 / `add`, the full-config run in `new` Phase 3, and the symptom + catch-all pass in `refine`. The checkpoint-level mechanics — the `errors` / `warnings` / `rule` / `fix` JSON shape the skill consumes — are documented on the [validate page](/tools/validate). ## Asset handling [Section titled “Asset handling”](#asset-handling) When a section needs assets, the skill places fonts at `config/fonts/` and images at `config/assets/`, verifies the path exists before referencing it in TOML, and never fetches URLs silently. The full decision tree for fit modes, alpha handling, and viewing-distance font-size tiers lives in [`asset-handling.md`](https://github.com/jamesawesome/led-ticker/blob/main/.claude/skills/creating-a-config/references/asset-handling.md) — the skill loads it on demand in Phase 2 and `add` mode. ## Tips [Section titled “Tips”](#tips) ### The bundled snippet library predates hi-res fonts [Section titled “The bundled snippet library predates hi-res fonts”](#the-bundled-snippet-library-predates-hi-res-fonts) Most `references/snippets.md` snippets don’t set `font` / `font_size` / `font_threshold` on every text-bearing widget, because the snippets were authored when BDF was the only option. The skill compensates by carrying the brand-font defaults from Phase 1 across every section in Phase 2 — message, countdown, two\_row, weather, image/gif text overlays, and any `[playlist.section.title]` blocks — so you don’t have to remember to set `font` on each widget yourself. If you bypass the skill and copy a snippet directly, you’ll need to add the font fields by hand. ### Running the skill outside Claude Code requires manually following the SKILL.md flow [Section titled “Running the skill outside Claude Code requires manually following the SKILL.md flow”](#running-the-skill-outside-claude-code-requires-manually-following-the-skillmd-flow) The `/creating-a-config` slash command is a Claude Code convenience; on other platforms (Claude.ai, the API) the skill is still available as instructions, but you trigger it by asking the agent to “use the creating-a-config skill” rather than via a slash command. The same Q\&A wizard runs either way — the skill is platform-agnostic, only the entry point differs. See also * [tools/validate](/tools/validate/) * [concepts/sections-and-modes](/concepts/sections-and-modes/) * [getting-started](/getting-started/) # Tool: gif-plan > Get the recommended render --duration for a led-ticker demo TOML, and a guard against shipping a clipped gif. `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`](https://github.com/jamesawesome/led-ticker/blob/main/tools/gif_plan/plan.py) and ships as `make plan-gif`. The math layer is the planner; [`render-demo`](/tools/render-demo/) is the pixels layer. ## Usage [Section titled “Usage”](#usage) ```bash make plan-gif CONFIG=docs/site/demos-pinned/two_row-wrap.toml ``` Output is at most two lines: ```text 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: ```text duration: 9 cutoff: header 5s < ~8s needed ``` ## Exit codes [Section titled “Exit codes”](#exit-codes) | Code | Meaning | | ---- | --------------------------------------------------------------------------------------------------------------------------------- | | `0` | Clean — recommended duration printed. | | `2` | The `# render-duration:` header is shorter than the estimate (expected, and ignorable, when `play_count` is intentionally large). | | `3` | Tool error — config not found or malformed TOML (message on stderr). | ## Out of scope [Section titled “Out of scope”](#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/`](https://github.com/jamesawesome/led-ticker/tree/main/.claude/skills/making-a-gif) wraps this plus `render-demo` and adds LED-panel colour/contrast judgement. See also * [tools/render-demo](/tools/render-demo/) * [reference/cli](/reference/cli/) # Tool: panel-map > Derive, verify, and calibrate the pixel_mapper_config Remap string for your custom multi-panel layout — without hand-editing. This page is for **builders wiring their own multi-panel sign** who need a `pixel_mapper_config` Remap string — the line that tells the library which panel is first in the cable chain, where each one lands on the canvas, and how each is rotated. Hand-deriving it is the usual pain: edit → photograph random scrolling text → guess → repeat. Do you need this? Only multi-row layouts (e.g. the bigsign’s 2×4 serpentine) need a `pixel_mapper_config`. If your panels are a single horizontal chain — like the smallsign — skip this page; [`panel-test`](/tools/panel-test/) is all you need. `panel-map` replaces that loop with a four-step workflow: **reveal** your layout on the panels → **transcribe** the grid you see → **derive** the string → **verify** it on the real canvas. It is implemented at [`scripts/panel_map.py`](https://github.com/jamesawesome/led-ticker/blob/main/scripts/panel_map.py) and mirrors the conventions of [`panel-test`](/tools/panel-test/). Like `panel-test`, `panel-map` reads the `[display]` section of any led-ticker config TOML and reuses the same `LedFrame` construction the main app uses — so every panel knob (`rows`, `cols`, `chain_length`, `panel_type`, `gpio_slowdown`, `rp1_pio`) is exactly what the running ticker would see. Widget config is ignored. What you’ll need **\~15 min · Docker on the Pi · `reveal`/`verify` need the panels powered; `derive` needs no hardware.** * The sign assembled and powered, panels chained as you intend to run them. * The led-ticker Docker image built once: `make build` (the `-docker` targets below run inside it). * Your config TOML with a correct `[display]` block (`rows`, `cols`, `chain_length`, `parallel`). The mapper is the only unknown we’re solving for. * A phone camera. Run `panel-test` first If your panels render solid colors wrong — color mis-sequence, garbled bottom half, only the first panel lit, visible flicker — that is a **hardware/driver** fault (`led_rgb_sequence`, `panel_type`, `gpio_slowdown`) that `panel-map` cannot fix. Run [`panel-test`](/tools/panel-test/) and confirm solid Red, Green, Blue, White, and Black each render cleanly before reaching for `panel-map`. The mapper tool assumes the hardware layer is already working. All commands below use the **`-docker` targets** — the supported path on a deployed sign. They run inside the production image, so build it once first with `make build`. (A dev host with the repo and `uv` installed can drop the `-docker` suffix; see the [subcommand reference](#subcommand-reference).) ## Bigsign worked example [Section titled “Bigsign worked example”](#bigsign-worked-example) The bigsign is a 2×4 vertical-serpentine layout: eight P3 32×64 panels, data chain entering at the bottom-right, climbing each column bottom-to-top, then jumping diagonally to the bottom of the next column to the left. Here is the end-to-end walkthrough. ### Step 1 — reveal [Section titled “Step 1 — reveal”](#step-1--reveal) Stop the ticker and paint the calibration pattern: ```bash docker compose stop make panel-map-reveal-docker CONFIG=config/config.bigsign.example.toml ``` Each physical panel lights up with a number, an up-arrow, a bright corner dot in the logical top-left, a border around the slot, and an underline directly beneath the digit so a rotated number (a sideways `6` or `9`) is never ambiguous — you read the digit relative to its underline, not relative to the room.  ### Step 2 — transcribe [Section titled “Step 2 — transcribe”](#step-2--transcribe) Shoot the wall square-on (lights toward you, camera level). Write one `` token per panel. **Write the top wall row first, left to right, exactly as the panels hang — transcribe the numbers as you see them, even when they look out of order. Do not rotate the photo to make them count up.** For the bigsign (8 panels, all installed upright) the wall above reads: ```text 1n 3n 5n 7n 2n 4n 6n 8n ``` These numbers are `reveal`’s own labels, not your cable order — they run opposite to it (here `reveal` paints `1` on the panel farthest down the chain and `8` on the cable-entry panel). That’s fine, and it’s the whole point: you never have to reason about your wiring. Transcribe what you see and `derive` untangles the snake for you. Save it to a file: ```bash cat > layout.txt <<'EOF' 1n 3n 5n 7n 2n 4n 6n 8n EOF ``` Or just open `layout.txt` in any editor (`nano layout.txt` on the Pi) and type the grid. For a single-row chain (e.g. 5 panels side by side), the grid is one line: `1n 2n 3n 4n 5n`. The `n` flag means each panel is oriented normally (arrow up, dot top-left). See the [orientation legend](#orientation-legend) below for rotated panels. ### Step 3 — derive [Section titled “Step 3 — derive”](#step-3--derive) ```bash make panel-map-derive-docker LAYOUT=layout.txt CONFIG=config/config.bigsign.example.toml ``` `derive` prints the Remap string to stdout: ```text Remap:256,64|192,32n|192,0n|128,32n|128,0n|64,32n|64,0n|0,32n|0,0n ``` Copy that into your `[display]` block: ```toml pixel_mapper_config = "Remap:256,64|192,32n|192,0n|128,32n|128,0n|64,32n|64,0n|0,32n|0,0n" ``` This string matches `config/config.bigsign.example.toml` character-for-character. A golden tripwire test keeps them in sync — if `derive` ever diverges, CI fails. ### Step 4 — verify [Section titled “Step 4 — verify”](#step-4--verify) Paste the string into your config (or supply it directly with `--mapper`) and confirm the canvas is coherent: ```bash make panel-map-verify-docker CONFIG=config/config.bigsign.example.toml # or supply the string directly: make panel-map-verify-docker MAPPER="Remap:256,64|192,32n|192,0n|128,32n|128,0n|64,32n|64,0n|0,32n|0,0n" docker compose start ``` `verify` paints a panel-seam grid and, in every cell, a **reading-order number** (1, 2, 3, 4 across the top, 5, 6, 7, 8 across the bottom — left to right, top to bottom), an up-arrow, and a red dot in the top-left corner. A **correct** mapper makes those numbers read in order across the whole wall, every arrow pointing up, every dot top-left:  A **wrong** mapper scrambles those numbers (a panel lands out of sequence) or rotates an arrow (a panel’s orientation flag is off) — each panel diagnoses itself. See [How to read verify](#how-to-read-verify) below. ## Subcommand reference [Section titled “Subcommand reference”](#subcommand-reference) ### `reveal` — chain and orientation calibration [Section titled “reveal — chain and orientation calibration”](#reveal--chain-and-orientation-calibration) Runs with `pixel_mapper_config` forced to the identity mapping (no panel rearrangement), so each panel shows the number of the raw frame-buffer slot that physically lands on it. Those numbers are the tool’s own labels — you transcribe them and `derive` converts. (They run opposite to cable order; you never need to match them to your wiring.) Photograph the result and you have everything `derive` needs. ```bash docker compose stop make panel-map-reveal-docker make panel-map-reveal-docker CONFIG=config/config.mysign.toml HOLD=5 docker compose start ``` On a dev host with the repo and `uv` installed (not a deployed sign), drop the `-docker` suffix: `make panel-map-reveal`. The make targets wrap `python scripts/panel_map.py reveal --config $(CONFIG) --hold $(HOLD)` — the same `CONFIG=` / `HOLD=` override convention as `make panel-test`. Per panel, `reveal` paints (all via `SetPixel`, never `DrawText`): * The panel number as a large BDF digit, centered. * An up-arrow — the primary rotation tell. * A bright dot in the logical top-left corner — disambiguates 90° vs 270°. * A 1 px border around the slot. * A short underline directly beneath the digit. Ctrl-C exits cleanly: a final black frame is swapped on so the panel never sticks on the calibration pattern. | Flag | Type | Default | Meaning | | ---------- | ----- | -------------------- | ------------------------------------------------------ | | `--config` | path | `config/config.toml` | Config TOML to read `[display]` from. | | `--hold` | float | `2.0` | Seconds between swap ticks (extend for a steady hold). | ### `derive` — string generator (no hardware needed) [Section titled “derive — string generator (no hardware needed)”](#derive--string-generator-no-hardware-needed) Reads the transcribed grid from `--layout FILE` and prints the `Remap:` string to stdout. Diagnostics (chain-count mismatch warnings, parse errors) go to stderr. No hardware is needed — this step is pure computation. ```bash make panel-map-derive-docker LAYOUT=layout.txt make panel-map-derive-docker LAYOUT=layout.txt CONFIG=config/config.mysign.toml ``` The `-docker` target pipes your `layout.txt` into the image’s stdin; on a dev host with `uv`, `make panel-map-derive LAYOUT=layout.txt` runs it directly. The `CONFIG` argument is read only for `chain_length × parallel`, as a correctness check on the cell count in your grid — a mismatch warns on stderr but doesn’t hard-fail. | Flag | Type | Default | Meaning | | ---------- | ---- | -------------------- | -------------------------------------------------------------------------- | | `--config` | path | `config/config.toml` | Config TOML — read for `chain_length` / `parallel` correctness check only. | | `--layout` | path | stdin | Layout file (recommended). One row per wall row, cells ``. | **Validation messages are plain-language** — for example: * `"You listed panel 1 twice. Each panel number must appear exactly once in your grid."` * `"Row 2 has 3 panels but row 1 has 4. Every wall row needs the same number of cells."` * `"'7z' isn't a valid cell. Each cell is a panel number followed by one of n, s, e, w, x (e.g. '3s')."` `derive` supports a single data chain (`parallel = 1`), which covers every reference build. A multi-chain (`parallel > 1`) config is refused with a clear message rather than emitting a silently-wrong string. ### `verify` — coherent full-canvas diagnostic [Section titled “verify — coherent full-canvas diagnostic”](#verify--coherent-full-canvas-diagnostic) Applies a candidate mapper and paints a self-diagnosing image across the whole finished canvas. A correct mapper produces a coherent, in-order image; a wrong one shows exactly which panel is off and how. ```bash docker compose stop make panel-map-verify-docker CONFIG=config/config.mysign.toml make panel-map-verify-docker MAPPER="Remap:256,64|..." docker compose start ``` On a dev host, drop the `-docker` suffix. The painted image is **independent of the mapper string** — it’s the same reference picture every time; the diagnostic lives entirely in how the hardware then routes it onto your panels. In each visible cell `verify` paints: * A panel-seam grid: faint lines every `cols` / `rows` pixels — seams should fall exactly on physical panel edges. * A reading-order number (1, 2, 3 … left to right, top to bottom) — a wrong mapper lands these out of sequence. * An up-arrow and a red top-left corner dot — a wrong orientation flag rotates them. | Flag | Type | Default | Meaning | | ---------- | ------ | -------------------- | -------------------------------------------------------------------------------------------- | | `--config` | path | `config/config.toml` | Config TOML. Uses `pixel_mapper_config` from this file unless `--mapper` overrides. | | `--hold` | float | `2.0` | Seconds between swap ticks. | | `--mapper` | string | — | Override the mapper string (e.g. paste `derive`’s output directly without editing the TOML). | ## How to read verify [Section titled “How to read verify”](#how-to-read-verify) `verify` paints reading-order numbers onto the **logical canvas** — the single flat image the software draws — and the hardware mapper then rearranges that image onto your physical panels. So a correct mapper makes the wall read in order; a wrong mapper’s mistakes show up per panel: * **A panel shows a number that’s out of sequence** (e.g. a `5` where you expect `2`) → that panel’s `x,y` position in the Remap string is wrong (a chain-order error). Fix: correct that panel’s position in `layout.txt` and re-run `derive`. * **A panel’s number or arrow looks rotated** → that panel’s orientation flag is wrong. Fix: change its flag. For `e`/`w` mix-ups the fix is a single-character swap — see [Flip-and-retry](#flip-and-retry). * **The *whole wall* is scrambled, nothing in order** → most likely either the Remap header size (`Remap:WIDTH,HEIGHT|…`) doesn’t match your real canvas, or the `reveal` photo was transcribed rotated/mirrored. Re-shoot square-on and start again from `reveal`; don’t tweak individual cells. For a single-panel fix, identify the panel by its number in the overlay, correct that one entry, and run `verify` again — you rarely need to re-transcribe the whole layout. ## Orientation legend [Section titled “Orientation legend”](#orientation-legend) What you observe on a physical panel after running `reveal` → the flag to write in your layout grid. The arrow points toward the flag letter: **e**ast = right, **w**est = left. | What you see on that physical panel | Flag | Rotation | | ----------------------------------- | ---- | ----------- | | Arrow up, dot top-left | `n` | 0° (normal) | | Arrow down, dot bottom-right | `s` | 180° | | Arrow right, dot top-right | `e` | 270° | | Arrow left, dot bottom-left | `w` | 90° | | (panel not used in the display) | `x` | discard | If a rotated panel comes out wrong `n` and `s` are unambiguous. If a 90°/270° panel reads rotated the wrong way on `verify`, swap `e` ↔ `w` for that one panel and re-derive — it’s a 10-second fix, not a re-transcribe. See [Flip-and-retry](#flip-and-retry). ### Flip-and-retry [Section titled “Flip-and-retry”](#flip-and-retry) If a rotated panel still looks wrong after `verify`, the most likely cause is an `e`/`w` swap. Fix it in about 10 seconds: 1. Identify the panel by its number in the `verify` overlay. 2. Find that cell in `layout.txt`. 3. Change `e` → `w` or `w` → `e`. 4. Re-run `make panel-map-derive-docker LAYOUT=layout.txt` to get the new string. 5. Re-run `make panel-map-verify-docker MAPPER="..."` to confirm. You don’t need to re-transcribe the whole layout for one orientation fix. ## Transcription tips [Section titled “Transcription tips”](#transcription-tips) ### Write it the way it hangs [Section titled “Write it the way it hangs”](#write-it-the-way-it-hangs) Stand in front of the wall. Write one `` token per panel — **the top wall row first, left to right, exactly as the panels hang**. A panel’s row and column in the grid are determined by where it sits on the wall, not by its cable position or rotation. `derive` re-sorts into chain order internally, so you never need to think in chain order — you only describe what you see. ### Photo discipline [Section titled “Photo discipline”](#photo-discipline) Shoot the wall square-on: lights toward you, camera level, no angle or tilt. A tilted or angled shot can mirror left/right or ambiguate top/bottom, introducing transcription errors before you even open a text file. ### Double-digit walls [Section titled “Double-digit walls”](#double-digit-walls) Numbers ≥ 10 rendered sideways (on a rotated panel) can be hard to read. For the reference builds (up to 8 panels) this is not an issue. For larger walls with 10 or more panels, allow extra time reading the `reveal` photo, or label the physical panels before shooting. ## Scope and limitations [Section titled “Scope and limitations”](#scope-and-limitations) `derive` computes **uniform-cell rectangular grids**: every wall row has the same number of panels, and every panel occupies the same `cols × rows` footprint on the canvas. It handles a **single data chain** (`parallel = 1`) — both reference builds, and the vast majority of hobbyist walls, are single-chain. * `n`, `s`, `e`, and `w` panels are all supported. `n`/`s` (0°/180°) keep a panel’s footprint; `e`/`w` (90°/270°) swap its width and height. * A wall that **mixes** rotated and un-rotated panels may be physically non-rectangular (rows of unequal pixel height). `derive` assumes a uniform grid, so for a mixed-rotation wall, use `verify` to check every panel and hand-edit any `e`/`w` entry the [flip-and-retry](#flip-and-retry) loop doesn’t settle. * `parallel > 1` (multiple electrical chains) is refused by `derive` with a clear message — hand-write the Remap string for that layout. `reveal` and `verify` are **hardware tools**: they drive the matrix and so need `--privileged` in Docker (the supported path) — the same constraint as `panel-test`. The ticker and these tools cannot share the matrix; stop the ticker (`docker compose stop`) before running either. `derive` needs no hardware. See also * [tools/panel-test](/tools/panel-test/) * [hardware/bigsign](/hardware/bigsign/) * [hardware/building-your-own](/hardware/building-your-own/) * [reference/cli](/reference/cli/) # Tool: panel-test > Cycle the panel through full-frame R, G, B, White, Black so hardware/wiring/driver issues can be diagnosed independently of any widget or config. `panel-test` paints the panel solid Red → Green → Blue → White → Black on repeat. It exists to **isolate the hardware layer from the config layer**: when widgets render wrong, this tells you whether your `led_rgb_sequence`, `panel_type`, `chain_length`, or `gpio_slowdown` is at fault before you start tearing apart your TOML. The implementation is a small script at [`scripts/panel_color_test.py`](https://github.com/jamesawesome/led-ticker/blob/main/scripts/panel_color_test.py). It reads the `[display]` section of any led-ticker config TOML and reuses the same `LedFrame` construction the main app uses — so every panel knob (FM6126A init, BRG-vs-RGB remapping, chain length, `rp1_pio`, slowdown) is exactly as the running ticker would see it. Widget config is ignored entirely. ## Quick start — host [Section titled “Quick start — host”](#quick-start--host) For a dev laptop or any non-Docker host with the `rgbmatrix` Python bindings installed: ```bash make panel-test # uses config/config.toml (this sign's config), 2s holds make panel-test CONFIG=config/config.small_sign.toml # different sign make panel-test HOLD=4 # slower cycle for a long stare ``` The make target wraps `uv run python scripts/panel_color_test.py --config $(CONFIG) --hold $(HOLD)` — same `CONFIG=` override convention as [`make validate`](/tools/validate/). Ctrl-C exits cleanly: the script paints one final black frame and swaps it on, so the panel never sticks on the last color of the cycle. ## Quick start — Docker (on the Pi) [Section titled “Quick start — Docker (on the Pi)”](#quick-start--docker-on-the-pi) This is what you’ll actually run on a deployed sign. The diagnostic and the main ticker cannot share the matrix, so stop the ticker first: ```bash docker compose stop make panel-test-docker # ...observe the panel, Ctrl-C when done... docker compose start ``` The `panel-test-docker` target runs `docker run --rm -it --privileged --network host` against the existing `led-ticker` image — same privilege flags as `compose.yaml`. The script is bind-mounted from the repo, so iteration on the script itself doesn’t require `make build`. The first run does require the image to exist (`make build` once). ## What it does [Section titled “What it does”](#what-it-does)  The script cycles indefinitely through this sequence: | # | Color | RGB | What you should see | | - | ----- | --------------- | ---------------------------------------------------------- | | 1 | Red | (255, 0, 0) | Every LED on the chain glows pure red. | | 2 | Green | (0, 255, 0) | Every LED on the chain glows pure green. | | 3 | Blue | (0, 0, 255) | Every LED on the chain glows pure blue. | | 4 | White | (255, 255, 255) | Every LED on the chain is fully lit on all three channels. | | 5 | Black | (0, 0, 0) | All LEDs off. | Each color holds for `--hold` seconds (default 2.0). Per cycle it logs `[N/5] (r, g, b)` to stderr. ## What it lets you diagnose [Section titled “What it lets you diagnose”](#what-it-lets-you-diagnose) | Symptom on panel | Likely cause | Where to fix | | -------------------------------------------------------- | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Some panels lit, others dark | Missing per-panel power lead | Check the per-panel power leads — every panel needs its own 5V lead from the supply; the data ribbon doesn’t carry power. | | Red shows green, or Green shows blue, etc. | `led_rgb_sequence` is wrong | `[display] led_rgb_sequence` in your config — see [config-options](/reference/config-options/). Common values: `"RGB"` (default), `"BRG"` (panels wired G→R, R→B, B→G — typical Muen P2). | | Bottom half of each panel garbled, mirrored, or stuck-on | `panel_type = "FM6126A"` missing or driver init not running | Set `[display] panel_type = "FM6126A"` (or `"FM6127"`). Without it FM6126A driver chips power up in a bad state. | | Only the first panel of the chain lights up | `chain_length` set wrong, or HUB75 IDC cables crossed | Verify `[display] chain_length` matches your physical chain length. Then verify each panel’s OUT goes to the next panel’s IN — easy to flip an IDC cable. | | Visible flicker during the solid-color holds | `gpio_slowdown` too low for your wiring | Bump `[display] gpio_slowdown` — Pi 4 typically wants `2`, longer chains and Pi 5 often want `3` or higher. | | Dim or visibly-off pixels during the White frame | Hardware fault on those pixels | Physical inspection — replace the panel if widespread. | | Pixels still glowing during the Black frame | Stuck-on pixels (hardware fault) | Physical inspection. Note position so you can rule it out in normal operation. | ## CLI flags [Section titled “CLI flags”](#cli-flags) | Flag | Type | Default | Meaning | | ---------- | ----- | ---------------------------- | ----------------------------------------------------------------------- | | `--config` | path | `config/config.longboi.toml` | Config TOML to read `[display]` from. Widget/section config is ignored. | | `--hold` | float | `2.0` | Seconds to hold each color before advancing. | The script has no other arguments. It always cycles R → G → B → W → B and always loops forever. ## Notes [Section titled “Notes”](#notes) * **`sudo` on the host path (host path only):** the rgbmatrix C library needs `/dev/mem` access. On a Pi running the host (non-Docker) path you’ll need `sudo uv run python scripts/panel_color_test.py …` (or just `sudo make panel-test`). The Docker path handles this via `--privileged` — Docker users don’t need `sudo`. * **Not a substitute for `validate`:** `panel-test` cannot tell you anything about your widgets, transitions, or playlist. Use [`validate`](/tools/validate/) for config-layer checks and [`render-demo`](/tools/render-demo/) for widget-layer previews. See also * [hardware/bigsign](/hardware/bigsign/) * [hardware/smallsign](/hardware/smallsign/) * [reference/cli](/reference/cli/) * [tools/validate](/tools/validate/) * [tools/panel-map](/tools/panel-map/) # Tool: render-demo > Turn a config TOML into a panel-resolution gif by running the actual ticker engine against the test stub canvas. `render-demo` is the tool that builds every gif on this docs site. It takes a led-ticker `config.toml`, runs the real ticker engine against the test stub canvas, captures every `SwapOnVSync` frame, and encodes the result to a gif at panel resolution. The script lives at [`tools/render_demo/render.py`](https://github.com/jamesawesome/led-ticker/blob/main/tools/render_demo/render.py). It exists so the docs can show what a config actually looks like on a panel without anyone needing real hardware on hand. The same engine that drives the LEDs drives the renderer, so the output matches what you’d see on the sign frame-for-frame — minus the physical brightness and viewing-angle differences of real LEDs. ## Two pipelines [Section titled “Two pipelines”](#two-pipelines) The docs site has two demo pipelines, each with its own source directory and output directory: * **Auto-rendered** — TOML lives in `docs/site/demos/`, output gif in `docs/site/public/demos/` (gitignored). Regenerated on every Cloudflare build by [`docs/site/scripts/build-demos.mjs`](https://github.com/jamesawesome/led-ticker/blob/main/docs/site/scripts/build-demos.mjs). * **Long-running** — TOML lives in `docs/site/demos-long/`, output gif in `docs/site/public/demos-long/` (committed to git). Rendered manually via `make render-long-demos`. The auto-rendered path is for static demos that finish in five seconds; the long-running path is for data-fetch widgets (RSS, weather) where five seconds isn’t enough and Cloudflare can’t make the live HTTP calls anyway. Full setup details live in the [docs/site README](https://github.com/jamesawesome/led-ticker/blob/main/docs/site/README.md#building-demo-gifs). ## Quick start [Section titled “Quick start”](#quick-start) Render any TOML to a gif from the repo root: ```bash make render-demo CONFIG=path/to/config.toml OUT=out.gif ``` For a minimal demo TOML — the same shape the auto-rendered pipeline expects: ```toml [display] rows = 16 cols = 32 chain_length = 5 default_scale = 1 brightness = 60 [[playlist.section]] mode = "slideshow" loop_count = 1 hold_time = 4.0 [[playlist.section.widget]] type = "message" text = "Hello, panel" font_color = "rainbow" ``` ```bash make render-demo CONFIG=demo.toml OUT=demo.gif ``` The output gif is upscaled 4× by default so individual LED pixels read clearly on retina displays. ## Planning before rendering [Section titled “Planning before rendering”](#planning-before-rendering) If you’re not sure what `--duration` to use, run [`gif-plan`](/tools/gif-plan/) first — it estimates the render duration from your config and suggests the right `# render-duration:` header value before you commit to a 10-second render. ## CLI flags [Section titled “CLI flags”](#cli-flags) The Makefile target wraps `uv run python tools/render_demo/render.py`. The user-facing flags: | Flag | Default | Purpose | | ------------------- | ---------- | ---------------------------------------------------------------------------- | | `--output` / `-o` | (required) | Output gif path. | | `--duration N` | `5` | Capture duration in seconds. Longer means a bigger gif. | | `--upscale N` | `4` | Pixel upscale factor. The gif is `N×` panel resolution per side. | | `--start-section N` | `0` | Start at this section index. Useful for jumping past intros on long configs. | There’s no fps flag — the engine runs at a fixed \~20 fps (50 ms per tick) and the gif is encoded at that cadence to match wall-clock playback. For per-demo overrides without touching the build script, the auto-render pipeline parses an optional `# render-duration: N` comment from the top of each TOML. A wide marquee that needs more than five seconds to complete one full traversal can declare it inline: ```toml # render-duration: 12 [[playlist.section.widget]] type = "message" text = "A long marquee that needs more time to scroll all the way across..." ``` The parser lives in `readRenderDuration` in [`build-demos.mjs`](https://github.com/jamesawesome/led-ticker/blob/main/docs/site/scripts/build-demos.mjs). Malformed values fall back to the five-second default. ## API-key-required widgets [Section titled “API-key-required widgets”](#api-key-required-widgets) Long-running demos sometimes need API keys — the `weather.current` plugin widget needs `WEATHERAPI_KEY`, and so on. To keep contributors without those keys from hitting render failures, the long-demo pipeline reads an optional `# requires-env: VAR` comment from the top of each TOML: ```toml # requires-env: WEATHERAPI_KEY [[playlist.section.widget]] type = "weather.current" location = "Brooklyn, NY" ``` When `make render-long-demos` walks `docs/site/demos-long/*.toml`, any TOML whose declared env var isn’t set in the current shell (or in `.env`) is skipped with a `[render-long-demos] SKIP …` log line. Everyone else’s demos still render. ## Tips [Section titled “Tips”](#tips) ### Live-API widgets in a five-second window often show cached or placeholder data [Section titled “Live-API widgets in a five-second window often show cached or placeholder data”](#live-api-widgets-in-a-five-second-window-often-show-cached-or-placeholder-data) The renderer captures every `SwapOnVSync` so durations match wall-clock playback exactly, but five seconds usually isn’t enough for a `weather.current` widget to complete a network fetch. Use the long-running pipeline (`# render-duration: 30`) for those, not the auto-rendered one. ### The test stub canvas does not paint hi-res TTF fonts identically to real hardware [Section titled “The test stub canvas does not paint hi-res TTF fonts identically to real hardware”](#the-test-stub-canvas-does-not-paint-hi-res-ttf-fonts-identically-to-real-hardware) The threshold-based rasterization path runs the same way, but subtle pixel-level differences can show up at small font sizes or with thin-stroked typefaces. If a demo gif looks slightly off relative to the real panel, the panel is the source of truth — tune `font_threshold` against hardware, not the gif. ### Output gif files are larger than panel resolution would suggest [Section titled “Output gif files are larger than panel resolution would suggest”](#output-gif-files-are-larger-than-panel-resolution-would-suggest) The renderer upscales gifs `--upscale` × before encoding (default 4), so a 256×64 bigsign panel becomes a 1024×256 gif on disk. That’s deliberate — the upscaling makes individual LED pixels read clearly on retina displays — but it does mean file sizes grow with the square of the upscale factor. Drop `--upscale 2` if you need a smaller artifact. See also * [tools/validate](/tools/validate/) * [tools/creating-a-config](/tools/creating-a-config/) * [concepts/display](/concepts/display/) # Tool: validate > Statically inspect a led-ticker config TOML to surface errors and warnings before they bite on the Pi. `led-ticker validate` reads a `config.toml` and reports configuration mistakes without opening a panel. It catches TOML parse errors, structural problems, widget-construction failures (via `_build_widget(validate_only=True)`), and soft layout warnings — before you deploy to the Pi. The full list is on the [Validation rules](/pitfalls/) page; the implementation lives at [`src/led_ticker/validate.py`](https://github.com/jamesawesome/led-ticker/blob/main/src/led_ticker/validate.py). It exists so that the most common config mistakes — a `text_align = "scroll"` paired with a `fit = "stretch"`, a hi-res font without `font_size`, a `content_height` that overflows the panel — surface on your laptop in milliseconds, instead of on the Pi after a deploy. It’s also the contract the [`creating-a-config`](/tools/creating-a-config) skill uses to verify generated configs: the skill calls `validate --json` and refuses to ship anything that fails. ## Quick start [Section titled “Quick start”](#quick-start) Run the validator directly with the console script or wrap it through the Makefile shortcut: ```bash led-ticker validate config/config.toml # or make validate CONFIG=config/config.toml ``` The make target is just a convenience that runs `uv run led-ticker validate` — useful when you don’t want to remember the `uv run` prefix. Warnings are gated behind a Phase-2 check — they only surface when no errors are present, so you’ll never see both classes in the same run. The two examples below show the human-readable output for an errors-only run and a warnings-only run; the [`--json`](#machine-readable-json) section mirrors the same split. ### Errors-only run [Section titled “Errors-only run”](#errors-only-run) A config that pairs `text_align = "scroll"` with `fit = "stretch"` on a gif/image widget: ```bash led-ticker validate config/config.toml ``` ```text Validating config/config.toml... ✗ ERROR section[0].widget[1]: text_align='scroll' with fit='stretch': no transparent regions for text to walk behind Fix: Use text_align='scroll_over' to paint text on top of the image, or change fit to 'pillarbox' / 'letterbox' / 'crop'. 1 issue(s): 1 error(s), 0 warning(s) ``` ### Warnings-only run [Section titled “Warnings-only run”](#warnings-only-run) A config with no hard errors but a `transition_duration` that looks like milliseconds: ```bash led-ticker validate config/config.toml ``` ```text Validating config/config.toml... ⚠ WARNING transitions.between_sections: transition_duration 800.0 looks like milliseconds (> 5 s is unusual) Fix: Divide by 1000 → 0.800 s 1 issue(s): 0 error(s), 1 warning(s) ``` ### Machine-readable JSON [Section titled “Machine-readable JSON”](#machine-readable-json) The same split applies to `--json` output (used by the [`creating-a-config`](/tools/creating-a-config) skill): ```bash led-ticker validate config/config.toml --json ``` Errors-only run: ```json { "valid": false, "path": "config/config.toml", "errors": [ { "rule": 3, "location": "section[0].widget[1]", "message": "text_align='scroll' with fit='stretch': no transparent regions for text to walk behind", "fix": "Use text_align='scroll_over' to paint text on top of the image, or change fit to 'pillarbox' / 'letterbox' / 'crop'." } ], "warnings": [] } ``` Warnings-only run: ```json { "valid": true, "path": "config/config.toml", "errors": [], "warnings": [ { "rule": 21, "location": "transitions.between_sections", "message": "transition_duration 800.0 looks like milliseconds (> 5 s is unusual)", "fix": "Divide by 1000 → 0.800 s" } ] } ``` The CLI exits `0` when the config is valid (no errors; warnings allowed), `1` when there are errors, and `2` when the file does not exist. ### Strict mode — promote warnings to errors [Section titled “Strict mode — promote warnings to errors”](#strict-mode--promote-warnings-to-errors) Pass `--strict` to treat every warning as an error and also enable asset-path existence checks ([Rule 40](/pitfalls/#rule-40--asset-path-does-not-exist-on-disk)): ```bash led-ticker validate --strict config/config.toml ``` In strict mode: * All warnings are promoted to errors — `valid` is `false` if any warnings were found. * `gif` and `image` widget `path` fields must exist on disk (relative to the config file). Exit codes are the same: `0` clean, `1` errors (or promoted warnings), `2` file not found. **CI use case:** gate deploys on a warning-clean config: ```bash led-ticker validate --strict config/config.toml || exit 1 ``` Run `validate` without `--strict` during local drafting (assets may not be present locally); switch to `--strict` on the Pi or in your CI pipeline once all assets are in place. ## Output format [Section titled “Output format”](#output-format) The JSON shape is stable and meant to be parsed: ```json { "valid": true, "path": "config/config.toml", "errors": [], "warnings": [] } ``` Each entry in `errors` and `warnings` follows the `ValidationIssue` dataclass defined in [`src/led_ticker/validate.py`](https://github.com/jamesawesome/led-ticker/blob/main/src/led_ticker/validate.py): | Field | Type | Meaning | | ---------- | ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `rule` | `int \| null` | A numeric id used internally for test assertions and tooling. Stable across releases; not surfaced in the human-readable output. `null` for unclassified errors (e.g. raw TOML parse). | | `location` | `string` | Path into the config, e.g. `section[0].widget[1]` or `transitions.between_sections`. | | `message` | `string` | What the validator found. | | `fix` | `string` | A one-line suggestion that maps the problem to a concrete config change. | | `severity` | `"error"` or `"warning"` | Errors block the ticker at runtime; warnings are advisory and the ticker will still start. | The `valid` field is true exactly when `errors` is empty — warnings do not flip it. ## What gets caught [Section titled “What gets caught”](#what-gets-caught) Quick reference. Each row maps to a longer entry on [Validation rules](/pitfalls/). | Check | Severity | Quick fix | | ---------------------------------------------------------------- | -------- | ------------------------------------------------------------------- | | `text_align="scroll"` paired with `fit="stretch"` | error | use `pillarbox`/`letterbox`/`crop` | | `text_x_offset` set with a scrolling `text_align` | error | drop the offset, or use a static `text_align` | | `hold_time < 0.05` | error | raise to ≥ 0.05 (it’s seconds, not ms) | | `animation` on a widget that doesn’t support it | error | remove it; use `font_color = "rainbow"` instead | | `animation = "typewriter"` on `gif` / `image` with conflicts | error | drop `bottom_text`, scroll mode, or empty `text` | | Per-row font line-height exceeds the band on `two_row` / two-row | error | smaller `font_size`, or raise `content_height` | | `start_hold` on `slideshow` section or negative value | error | remove `start_hold` or set it to ≥ 0 | | `separator_*` set on a non-`ticker` section | error | remove the field, or switch to `ticker` | | `bottom_text_loops` on `two_row` without `bottom_text_wrap` | error | set `bottom_text_wrap = true`, or drop the field | | `text_loops` on a `two_row` widget (rule 29) | error | rename to `bottom_text_loops` | | `scroll_step_ms <= 0` on a section (rule 31) | error | set to a positive integer (e.g. 35) | | `content_height × scale > panel_h_real` (rule 1) | error | lower `content_height` to `panel_h ÷ scale` | | `scroll_speed_ms` at section level or `scroll_step_ms` on widget | error | swap fields to the correct scope (rule 34) | | Unknown widget field name (typo in TOML) | error | run `--list-fields TYPE` to see valid names | | Unknown transition name (typo in any transition field) | error | did-you-mean hint; see [Transitions](/transitions/) for valid names | | Asset `path` does not exist on disk (`--strict` only) | error | check path is relative to config file | | `two_row` widget at `scale = 4` | warning | use `scale = 2` (128 logical px wide) | | `transition_duration` > 5 s or < 0.05 s | warning | divide by 1000 (it’s seconds, not milliseconds) | | Held `top_text` wider than the logical canvas | warning | shorten text, smaller font, or lower `scale` | | `font` name is not bundled and not in `config/fonts/` | warning | drop the font file on the deploy target | | `hold_time` set alongside `bottom_text_loops` on `two_row` | warning | drop one (or accept `max()` semantics) | | `default = "..."` written inside a section block (rule 35) | warning | rename to `transition = "..."` | ## Discovering widget fields — `--list-fields` [Section titled “Discovering widget fields — --list-fields”](#discovering-widget-fields----list-fields) If you’re not sure what fields a widget type accepts, run: ```bash led-ticker validate --list-fields message led-ticker validate --list-fields two_row led-ticker validate --list-fields gif ``` This prints the widget’s full field surface in two groups: * **Widget-level fields** — attrs fields the widget constructor accepts directly, with types and defaults. * **Dispatch-level fields** — shared fields `_build_widget` handles before construction (e.g. `font`, `font_size`, `animation`, `border`). When you use an unrecognized field name in a widget config block, the validator now catches it with a did-you-mean suggestion (rule 38). The fix line in the error output points at `--list-fields` so you can immediately see the correct name. ## Tips [Section titled “Tips”](#tips) ### The validator only catches static, config-time problems [Section titled “The validator only catches static, config-time problems”](#the-validator-only-catches-static-config-time-problems) Anything that depends on runtime state — a stale `WEATHERAPI_KEY`, an unreachable RSS feed, an `image_path` that exists in your repo but not in the Docker bind mount, a network split-brain that makes a live data fetch time out — is out of scope. A green `validate` is necessary but not sufficient; the only way to fully verify a config is to run it against the panel (or the [`render-demo`](/tools/render-demo) gif pipeline). ### Warnings are advisory, not blocking [Section titled “Warnings are advisory, not blocking”](#warnings-are-advisory-not-blocking) The ticker will start, scroll, and swap when only warnings are present, but the warning usually points at a rendering quirk you don’t actually want — a `two_row` widget cramped into a 64px logical canvas, or a `transition_duration` that looks like milliseconds when the engine wants seconds. Treat them as a checklist before you call a config done. Pass `--strict` to promote all warnings to errors and enforce a warning-clean config in CI. See the [Strict mode](#strict-mode--promote-warnings-to-errors) section above. See also * [tools/creating-a-config](/tools/creating-a-config/) * [pitfalls](/pitfalls/) * [tools/render-demo](/tools/render-demo/) # Transitions > How content swaps between widgets — push, wipe, sprite, and special effects. A transition runs between widgets in `slideshow` mode (and between sections regardless of mode). Global defaults live in `[transitions]`; each section can override them. ## The four families [Section titled “The four families”](#the-four-families) | Family | What it looks like | Best for | | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | --------------------------------- | | [Push](/transitions/push/) | Old slides off, new slides in from the opposite side | General purpose, news-ticker feel | | [Wipe](/transitions/wipe/) | Sweep line erases content, leaves new in its wake | Clean / professional | | [Sprite / flair](/transitions/sprite/) | Pixel-art character (Pac-Man, Nyan Cat, Pokéball, …) crosses the panel; or text itself spins out (`flair.spinout`) | Fun / themed | | [Special](/transitions/special/) | Cut, dissolve, color flash, split, scroll | Variety, ambient | ## Which to use [Section titled “Which to use”](#which-to-use) | Tone | Default (between widgets) | Between sections | | ----------- | ------------------------------------------------------------------- | ---------------------- | | Minimal | `cut` or `wipe_left` | `cut` | | Playful | `pokeball.alternating` or `nyancat.alternating` (plugin) | `pokeball.alternating` | | Info-dense | `push_up` | `dissolve` | | Branded-pro | `wipe_alternating` (with `transition_color` from the brand palette) | `dissolve` | ## Global settings (`[transitions]`) [Section titled “Global settings (\[transitions\])”](#global-settings-transitions) These apply everywhere unless a section overrides them: | Field | Default | Notes | | ------------------ | ---------- | ---------------------------------------------------------------------------------------------------------------------------- | | `default` | `"cut"` | Fallback inter-widget transition for every section | | `between_sections` | `"cut"` | Falls back to `default` (which is `cut` unless you change it) — sets the entry transition when a section doesn’t set its own | | `duration` | `0.5` | Transition duration in seconds. 0.3–1.5 is typical; sprite trails want 1.0–2.0 | | `easing` | `"linear"` | `linear` / `ease_out` / `ease_in_out` | Both `default` and `between_sections` accept an inline table for extra knobs: `between_sections = { type = "wipe_left", duration = 0.8, easing = "ease_out" }`. ## Per-section overrides (`[[playlist.section]]`) [Section titled “Per-section overrides (\[\[playlist.section\]\])”](#per-section-overrides-playlistsection) Each section has three transition slots, all accepting a bare string or inline table: | Field | What it controls | Precedence | | ------------------- | ---------------------------------------------------- | ---------------------------------------------------------- | | `transition` | **Both** entry and inter-widget (the shortcut) | Overrides `default` / `between_sections` for both slots | | `entry_transition` | How **this section enters** (inter-section boundary) | Highest priority for entry — overrides `transition` | | `widget_transition` | Swaps **between widgets** within this section | Highest priority for inter-widget — overrides `transition` | **The `transition` shortcut:** writing `transition = "pokeball.forward"` on a section sets that transition for *both* the entry and inter-widget swaps. This is usually what you want for single-widget sections. For multi-widget sections use `entry_transition` + `widget_transition` to control the two slots independently. **Full precedence chains:** * Entry: `entry_transition` → `transition` (if explicitly set) → `[transitions] between_sections` * Inter-widget: `widget_transition` → `transition` (if explicitly set) → `[transitions] default` Additional per-section knobs (apply on top of `transition`): * `transition_duration`: override the duration (seconds) * `transition_color`: RGB list — sweep color for wipe family and color\_flash * `transition_colors`: list of RGB lists — color pool for `wipe_alternating` / `wipe_random` * `show_pikachu` / `show_pokeball`: toggle sprite elements on the `pokeball` family (ships in the [flair pack](https://github.com/JamesAwesome/led-ticker-plugins/tree/main/plugins/flair)) See also * [transitions/push](/transitions/push/) * [transitions/wipe](/transitions/wipe/) * [transitions/sprite](/transitions/sprite/) * [transitions/special](/transitions/special/) # Push transitions > Outgoing and incoming widgets scroll together — old slides off one edge while new enters from the opposite edge. The push family scrolls the outgoing and incoming widgets together. Both are visible simultaneously during the transition.  push family — left, right, up, down, and random ## Variants [Section titled “Variants”](#variants) The `push` family scrolls the outgoing and incoming widgets together — the old slides off one edge while the new enters from the opposite edge. Both are visible simultaneously during the transition. | Name | Direction | Best for | | ------------------ | ------------------------------------------------------ | --------------------------------- | | `push_left` | Old exits left, new enters from right | General purpose, news-ticker feel | | `push_right` | Old exits right, new enters from left | "Going back" in a sequence | | `push_up` | Old exits top, new enters from bottom | Countdowns, score updates | | `push_down` | Old exits bottom, new enters from top | Variety, vertical change | | `push_alternating` | Cycles through left → right → up → down each swap | Dynamic variety | | `push_random` | Random direction each swap, never repeats back-to-back | Unpredictable variety | ## Tuning * `transition_duration` (seconds): default 0.5. Push transitions feel right at 0.4–0.8 s. Below 0.3 the motion blurs; above 1.2 it drags. * `easing`: `linear`, `ease_in_out` (default for pushes), `ease_out`. Linear is sharper; ease\_in\_out feels softer. ## Tips * Push transitions ignore `transition_color` (no sweep line, no flash). * Push reads from the engine's "outgoing scroll position" so a widget mid-scroll continues seamlessly into the push. This is why push transitions feel snappier than wipes. See also * [transitions/wipe](/transitions/wipe/) * [transitions/special](/transitions/special/) # Special transitions > Catch-all for transitions that aren't push, wipe, or sprite — cut, color_flash, dissolve, split, scroll. The special family covers transitions that don’t fit the push / wipe / sprite shapes. Most are full-canvas effects (`color_flash`, `dissolve`, `split`) or single-frame cuts; `scroll` is the odd one out — a continuous-scroll bridge that connects two widgets with a bullet separator instead of pausing for a transition.  dissolve — random pixel scatter (TV-static effect)  split — center-outward expanding black band with magenta edges  color\_flash — full-canvas flash, white / cyan / magenta via transition\_color  scroll — seamless continuous scroll with a bullet separator The scroll separator is a small white dot by default. Recolor it (e.g. to tone it down on bright content) with `separator_color` on the transition table — `transition = { type = "scroll", separator_color = [80, 80, 80] }` — accepting the same values as a widget `font_color`, including `"rainbow"`. (This is the scroll *transition’s* separator and is distinct from the ticker-mode section `separator_color`, which colors the loop separator between ticker widgets.) To use a character instead of a dot, set `separator`: `transition = { type = "scroll", separator = "·" }`. Include surrounding spaces for padding (e.g. `separator = ' · '`); set `separator_font` / `separator_font_size` only for a non-default font. `separator_size` sets the dot’s pixel size (default 2); it has no effect when a glyph separator is set. ## Variants [Section titled “Variants”](#variants) The `special` family is a catch-all for transitions that don't fit the push, wipe, or sprite shapes — instant cuts, full-canvas effects, and continuous-scroll separators. Use them as variety between sections, or as ambient cadence on a single-section playlist. | Name | What it does | Best for | | ------------- | ----------------------------------------------------------------------------------------------------------------- | ------------------------------------- | | `cut` | Instant switch — outgoing replaced by incoming on a single frame | Minimal default; "no transition" feel | | `color_flash` | Full-canvas white flash between content | Punctuating a major section change | | `dissolve` | Random pixel scatter (seeded RNG) creates a TV-static effect that resolves to the incoming widget | Dramatic between unrelated sections | | `split` | Center-outward expanding black band with magenta edge lines | Geometric / theatrical | | `scroll` | Seamless continuous scroll with a 2×2 bullet-dot separator (6 px symmetric gaps), 1 px / frame for constant speed | Marquee feel — no pause, no flash | ## Tuning * `transition_duration` (seconds): default 0.5. `cut` ignores it (single frame). `color_flash`, `dissolve`, and `split` look right between 0.4–0.8 s. `scroll` is the exception — duration is implied by content width and the 1 px / frame cadence, not by `transition_duration`. * `transition_color` (\[r, g, b]): used by `color_flash` (overrides the white) and `dissolve` (tints the static). Ignored by `cut`, `split`, `scroll`. ## Tips * **`scroll` vs `ticker` mode look similar but render differently.** `scroll` is a section-to-section transition that uses `_scroll_between` to bridge two widgets with a `•` separator at 1 px / frame. `ticker` is a section *mode* that scrolls all widgets continuously side-by-side with a separator drawn from the `DEFAULT_BUFFER_MSG` text character. Same visual rhythm, different code paths and different config surfaces. * **`dissolve` runs at physical resolution on bigsign.** Implementation unwraps the `ScaledCanvas` so the per-pixel scatter has the full 16,384-pixel grain. A logical-grain version (1,024 grain points at scale=4) collapses to fade-through-black at t=0.5 — that's a real bug the implementation avoids. If you ever rewrite `dissolve`, keep it on the unwrapped real canvas; tripwire `test_scatter_uses_physical_resolution_through_scaled_canvas` will catch a regression. See also * [transitions/push](/transitions/push/) * [transitions/wipe](/transitions/wipe/) * [transitions/sprite](/transitions/sprite/) # Sprite and flair transitions > Flair-pack transitions — Nyan Cat, Pokéball, Sailor Moon, Pac-Man sprites and the flair.spinout text-spin transition. The flair pack (`led-ticker-flair`) ships two categories of transition: **homage sprite-trails** — pixel-art characters that cross the panel — and **text-effect transitions** that manipulate the outgoing content itself. Both are referenced by their namespaced slug, e.g. `transition = "pokeball.forward"` or `transition = "flair.spinout"`. ## Homage transitions (flair pack) [Section titled “Homage transitions (flair pack)”](#homage-transitions-flair-pack) The four homage families — **nyancat**, **pokeball**, **pacman**, and **sailor\_moon** — ship together in the `led-ticker-flair` package (one install, four entry points, each with `.forward`, `.reverse`, and `.alternating` variants). ### Install [Section titled “Install”](#install) Add one line to `config/requirements-plugins.txt` (copied from `config/requirements-plugins.example.txt`): ```text led-ticker-flair ``` One install registers all four families. See [Plugins](/plugins/) for the install flow. A bare `transition = "nyancat"` (the pre-plugin spelling) raises a config-load error pointing at the namespaced `nyancat.forward` slug — the namespaced form is what the flair pack registers. Existing configs need no change The type strings (`nyancat.forward`, `pokeball.alternating`, etc.) are unchanged — only the install source consolidates. Configs already using these transitions keep working as-is. If you previously pinned individual family tags (e.g. `@nyancat-v0.1.0`), those installs continue to work; switch to the single flair line at your convenience. ### Nyan Cat (`nyancat`) [Section titled “Nyan Cat (nyancat)”](#nyan-cat-nyancat) Nyan Cat flies across the panel with a rainbow trail. Auto-activates a hi-res webp sprite on scaled signs (see [Hires](#hires) below). | Type string | Direction | | --------------------- | -------------------- | | `nyancat.forward` | Left → right | | `nyancat.reverse` | Right → left | | `nyancat.alternating` | Alternates each swap |  nyancat.forward — Nyan Cat flies left-to-right with rainbow trail ### Pokéball (`pokeball`) [Section titled “Pokéball (pokeball)”](#pokéball-pokeball) A Pokéball rolls across with a run-cycle sprite chasing. `show_pikachu` / `show_pokeball` toggle the sprite elements. Auto-activates a hi-res sprite on scaled signs (see [Hires](#hires) below). Also ships the `:pokeball.ball:` emoji. | Type string | Direction | | ---------------------- | -------------------- | | `pokeball.forward` | Left → right | | `pokeball.reverse` | Right → left | | `pokeball.alternating` | Alternates each swap |  pokeball.forward — Pokéball rolls left-to-right with run-cycle sprite chasing (default)  pokeball.forward — single-sprite modes via show\_pikachu / show\_pokeball ### Pac-Man (`pacman`) [Section titled “Pac-Man (pacman)”](#pac-man-pacman) Pac-Man chases three scared ghosts with a chomping animation. Keeps its 8-bit look at all scales. | Type string | Direction | | -------------------- | -------------------- | | `pacman.forward` | Left → right | | `pacman.reverse` | Right → left | | `pacman.alternating` | Alternates each swap |  pacman.forward — Pac-Man chases 3 scared ghosts with chomping animation ### Sailor Moon (`sailor_moon`) [Section titled “Sailor Moon (sailor\_moon)”](#sailor-moon-sailor_moon) The Moon Stick wand sweeps across with a sparkle trail. Keeps its 8-bit look at all scales. | Type string | Direction | | ------------------------- | -------------------- | | `sailor_moon.forward` | Left → right | | `sailor_moon.reverse` | Right → left | | `sailor_moon.alternating` | Alternates each swap |  sailor\_moon.forward — Moon Stick wand sweeps across with sparkle trail ## Reference [Section titled “Reference”](#reference) Sprite transitions run a pixel-art character across the panel, erasing the outgoing widget and revealing the incoming one. They are provided by four packages in the external [led-ticker-plugins](https://github.com/JamesAwesome/led-ticker-plugins) monorepo — `nyancat`, `pokeball`, `pacman`, and `sailor_moon` — each with forward, reverse, and alternating variants. Reference them by their namespaced slug, e.g. `transition = "pokeball.forward"`. Add the families you want to `config/requirements-plugins.txt` (install only the ones you use) and restart (`docker compose restart`): ```text git+https://github.com/JamesAwesome/led-ticker-plugins.git@nyancat-v0.1.0#subdirectory=plugins/nyancat git+https://github.com/JamesAwesome/led-ticker-plugins.git@pokeball-v0.1.0#subdirectory=plugins/pokeball git+https://github.com/JamesAwesome/led-ticker-plugins.git@pacman-v0.1.0#subdirectory=plugins/pacman git+https://github.com/JamesAwesome/led-ticker-plugins.git@sailor_moon-v0.1.0#subdirectory=plugins/sailor_moon ``` | Family | Variants | Hires on bigsign? | Best for | | ------------- | ----------------------------------------------------------------------- | ----------------------------------------- | ------------------- | | `nyancat` | `nyancat.forward`, `nyancat.reverse`, `nyancat.alternating` | yes (animated webp) | General playful | | `pokeball` | `pokeball.forward`, `pokeball.reverse`, `pokeball.alternating` | yes (run-cycle sprite + rolling pokeball) | Pop-culture variety | | `sailor_moon` | `sailor_moon.forward`, `sailor_moon.reverse`, `sailor_moon.alternating` | no (8-bit aesthetic is the design) | Magical / sparkle | | `pacman` | `pacman.forward`, `pacman.reverse`, `pacman.alternating` | no (8-bit aesthetic is the design) | Retro arcade | A fifth sprite family, **`baseball`** (`baseball.roll`, `baseball.roll_reverse`, `baseball.roll_alternating` — procedural ball, 8 rotation frames, hires on bigsign; best for sports sections), ships with the **[baseball](https://github.com/JamesAwesome/led-ticker-plugins/tree/main/plugins/baseball)** package in the led-ticker-plugins monorepo. Install it via `config/requirements-plugins.txt` (add `led-ticker-baseball` and restart with `docker compose restart`) before using these. ## Variants * **Forward** (`.forward`): sprite enters from the left, exits right * **Reverse** (`.reverse`): sprite enters from the right, exits left (sprite flipped horizontally) * **Alternating** (`.alternating`): cycles forward → reverse → forward each swap ## Pokeball-specific options | Option | Default | Description | | --------------- | ------- | -------------------------------------------------------------- | | `show_pikachu` | `true` | Render the run-cycle sprite chasing the ball | | `show_pokeball` | `true` | Render the pokeball sprite (set `false` for sprite-only chase) | ## Cross-scale transitions Sprite transitions work correctly when the outgoing and incoming sections have different `scale` values (e.g. a `scale=2` section swapping to a `scale=4` section). The canvas is switched to the incoming scale before the first frame, so the sprite stays physically consistent throughout — there is no size snap mid-transition. ## Tuning * `transition_duration`: sprite transitions need time to traverse the panel — 1.5–2.5 s feels right * Shorter durations clip the sprite exit; longer ones work fine ## Hires [Section titled “Hires”](#hires) `nyancat.forward` and `pokeball.forward` auto-activate hi-res sprites whenever the canvas is at `default_scale > 1` — that is, any big / scaled sign (see [Display](/concepts/display/)), typically a bigsign-style build. The hi-res variants are noticeably more detailed and read better at distance: * **nyancat** — animated webp Nyan Cat sprite at native physical resolution * **pokeball** — rolling pokeball with animated run-cycle sprite The `sailor_moon` and `pacman` families keep their 8-bit look at all scales — the chunky aesthetic is part of the design. ## Other plugin sprites [Section titled “Other plugin sprites”](#other-plugin-sprites) The rolling-**baseball** family (`baseball.roll`, `baseball.roll_reverse`, `baseball.roll_alternating`) ships with the **[baseball](https://github.com/JamesAwesome/led-ticker-plugins/tree/main/plugins/baseball)** package in the led-ticker-plugins monorepo, alongside that package’s MLB widgets and `:baseball.ball:` emoji. Install it via `config/requirements-plugins.txt` (see [Plugins](/plugins/)) to use it. *** ## Text-effect transitions (flair pack) [Section titled “Text-effect transitions (flair pack)”](#text-effect-transitions-flair-pack) ### `flair.spinout` (flair >= 0.3.0, core >= 4.6) [Section titled “flair.spinout (flair >= 0.3.0, core >= 4.6)”](#flairspinout-flair--030-core--46) `flair.spinout` spins the outgoing widget’s content out of view — starting at rest, then accelerating — before cutting to the incoming widget. Unlike a sprite trail, nothing crosses the panel; the content itself rotates and disappears. Transition duration follows `[transitions] duration` (default 0.5 s; sprite-style durations of 1.0–1.5 s look best for a full revolution or two).  \`flair.spinout\` — outgoing text accelerates and spins out before the incoming widget appears #### Install [Section titled “Install”](#install-1) `flair.spinout` is part of the same `led-ticker-flair` package as the homage sprite-trails: ```text led-ticker-flair ``` One install registers all flair transitions and animations. See [Plugins](/plugins/) for the install flow. #### Minimal config [Section titled “Minimal config”](#minimal-config) Minimal ```toml [transitions] default = "flair.spinout" duration = 1.0 [[playlist.section]] mode = "slideshow" hold_time = 3.0 [[playlist.section.widget]] type = "message" text = "SPIN OUT" center = true font_color = [0, 220, 255] [[playlist.section]] mode = "slideshow" hold_time = 2.5 [[playlist.section.widget]] type = "message" text = "AND CUT" center = true font_color = [80, 255, 80] ``` #### Knobs [Section titled “Knobs”](#knobs) | Knob | Default | Notes | | ------------- | ------- | ------------------------------------------------------- | | `revolutions` | `2` | Integer >= 1. Full turns before the content disappears. | | `direction` | `"cw"` | `"cw"` (clockwise) or `"ccw"` (counter-clockwise). | Set knobs via an inline table on `[transitions] default` or on the section’s `transition` field: ```toml [transitions] default = {type = "flair.spinout", revolutions = 1, direction = "ccw"} duration = 1.0 ``` #### Behavior notes [Section titled “Behavior notes”](#behavior-notes) * **Background color holds.** The outgoing section’s `bg_color` fills the panel for the entire spin duration — the background never flashes or drops to black mid-transition. * **Scrolled text spins from its parked position.** If the outgoing widget had been scrolling, `flair.spinout` picks up at the position where the text stopped (the same `outgoing_scroll_pos` continuity used by the push family). * **Colors freeze during the spin.** Animated `font_color` providers (`rainbow`, `color_cycle`, `shimmer`) are paused for the outgoing widget while it spins, consistent with how transitions pause frame-aware effects in general. * **Pairs with `flair.propeller`.** Use `flair.spinout` as the inter-widget or between-sections transition alongside `animation = "flair.propeller"` on `message` widgets for a full spin-in / spin-out cycle. See [flair.propeller → Pairing with flair.spinout](/concepts/animations/#pairing-with-flairspinout). See also * [transitions/push](/transitions/push/) * [transitions/wipe](/transitions/wipe/) * [concepts/animations](/concepts/animations/) # Wipe transitions > Stationary outgoing + a colored sweep line that erases the panel. The wipe family runs a colored sweep line across the panel that erases the outgoing widget direction-by-direction, then reveals the incoming widget. Snappier than push — only one widget moves — and the colored sweep line gives it a slightly more dramatic feel.  wipe family — left, right, up, down, and random ## Variants [Section titled “Variants”](#variants) The `wipe` family uses a stationary outgoing widget plus a colored sweep line that erases the panel direction-by-direction, then reveals the incoming widget. Snappier than push (no co-motion) and slightly more dramatic. | Name | Sweep direction | Default color | Best for | | ------------------ | ---------------------------------------------------------------- | ------------------------------------------------------------ | ---------------------------------- | | `wipe_left` | right→left | cyan | General purpose, professional feel | | `wipe_right` | left→right | magenta | Variety | | `wipe_up` | bottom→top | white | Vertical change | | `wipe_down` | top→bottom | green | Variety | | `wipe_alternating` | cycles through L→R→U→D | cycles colors | Dynamic variety | | `wipe_random` | random direction (no immediate repeats) + random color from pool | from `transition_colors` (default: cyan/magenta/white/green) | Unpredictable variety | ## Tuning * `transition_duration` (seconds): 0.4–0.8 feels right * `transition_color` (\[r, g, b]): override the sweep color on a single direction variant * `transition_colors` (list of \[r, g, b]): custom color pool for `wipe_alternating` / `wipe_random` ## Tips `wipe_alternating` ignores `transition_color` (the singular form) — it cycles through a built-in palette tied to each direction. Use `transition_colors` (the list form) to set the pool for both `wipe_alternating` and `wipe_random`. ## Tuning [Section titled “Tuning”](#tuning) * `transition_duration` (seconds): 0.4–0.8 feels right. Below 0.3 the sweep becomes a flash; above 1.0 it drags. * `transition_color` (\[r, g, b]): override the sweep color on any single-direction variant (`wipe_left`, `wipe_right`, `wipe_up`, `wipe_down`). * `transition_colors` (list of \[r, g, b]): custom color pool for `wipe_alternating` and `wipe_random`. Supply four colors to pair one with each direction. `wipe_alternating` ignores `transition_color` (the singular form) — it cycles through a palette tied to each direction. Use `transition_colors` to set the pool. See also * [transitions/push](/transitions/push/) * [transitions/sprite](/transitions/sprite/) # Tutorial 1: Setup > Clone led-ticker and preview the Firebird Yoga showcase live in your browser — see what you're building toward in under 2 minutes.  The destination config — three sections rotating in a loop. You'll build this in chapters 2–5. Over the next five chapters you’ll build a real bigsign config from scratch — starting with a single message and ending with a multi-section sign that rotates through a rainbow welcome card, a brand card (the @firebirdyoga.demo handle next to the hi-res Instagram sprite over a phoenix image with scrolling promo copy), and a held info section (Summer Camps, Open daily, All levels). This chapter gets the code running on your laptop. No hardware needed. Following along on a smaller sign? This tutorial uses the bigsign as its worked example, but the config steps — the `[display]` block, sections, widgets, transitions — apply just as well to the cheaper [smallsign](/hardware/smallsign/), the obvious first build. You don’t need the 8-panel rig to follow along; only the panel knobs differ. **\~2 min · no hardware needed** **What you’ll need:** * A laptop (macOS, Linux, or Windows) * [Git](https://git-scm.com/) — to clone the repository * [Docker](https://docs.docker.com/get-docker/) — the only tool needed for the live preview * **make** — standard on macOS and Linux; on Windows use WSL or Git Bash Prefer a GIF file? `make render-demo` renders any config to a shareable GIF — useful for capturing a preview to share. It requires Python 3.14 and [uv](https://docs.astral.sh/uv/); run `make dev` once to install. No GIF capture is needed to follow this tutorial: the browser preview in `make try` shows the same result live. ## Clone and start [Section titled “Clone and start”](#clone-and-start) ```bash git clone https://github.com/JamesAwesome/led-ticker.git cd led-ticker make try ``` What each command does: * **`git clone`** — downloads the repository, including all bundled fonts, example configs, and the try image. * **`cd led-ticker`** — enters the project root. All `make` targets and file paths in this tutorial assume you’re running from here. * **`make try`** — builds the try Docker image and starts a headless display engine plus the web UI sidecar. No LED panel, no Raspberry Pi needed. Once `make try` is running, open **** and click the **live preview** tab. You’ll see the bundled example — scrolling Hacker News headlines and a Nyan Cat sprite-trail transition — rendering live in your browser. ## Preview the destination config [Section titled “Preview the destination config”](#preview-the-destination-config) The GIF at the top of this page shows the Firebird Yoga config you’ll build in chapters 2–5. You can preview it live right now: stop the running session (`Ctrl-C`), copy the destination config, and start `make try` again — the config choice happens at startup: ```bash cp config/config.bigsign.firebird.example.toml config/config.toml make try ``` The browser preview switches to the Firebird Yoga sign. When you’re done exploring, delete the copy so you start fresh in Chapter 2: ```bash rm config/config.toml ``` Reproduce the GIF instead To render the destination config to a file rather than the browser, run: ```bash make render-demo CONFIG=config/config.bigsign.firebird.example.toml OUT=preview.gif open preview.gif # macOS xdg-open preview.gif # Linux ``` `make render-demo` needs `make dev` first (Python 3.14 + [uv](https://docs.astral.sh/uv/)). Open `config/config.bigsign.firebird.example.toml` in your editor and skim it. You’ll recognise each section in the preview. The comments explain the Pi-specific knobs (`pixel_mapper_config`, `gpio_slowdown`, `pwm_bits`) — safe to ignore for now; `make try` skips them via the headless backend. ## The live preview loop [Section titled “The live preview loop”](#the-live-preview-loop) From Chapter 2 onward you’ll create your own `config/config.toml`. When that file exists, `make try` previews YOUR config instead of the bundled example — hot-reloading as you edit. Save a change to `config/config.toml` while `make try` is running and the browser preview updates within one playlist cycle. `[display]`-level changes (rows, cols, scale) need a container restart: press Ctrl-C, then `make try` again. The live preview requires a `[web]` block in your config. Chapter 2 includes it in the first config you create. ## What this chapter doesn’t cover [Section titled “What this chapter doesn’t cover”](#what-this-chapter-doesnt-cover) This tutorial stays on the laptop preview throughout — but it builds toward hardware: by the end of chapter 5 you’ll have a complete config ready to put on a real sign. [Building your own](/hardware/building-your-own/) covers the wiring and panel bring-up, and [Quickstart B](/getting-started/#quickstart-b--deploy-to-your-pi) is the deploy path. Keep those tabs open for when you’re done. ## What’s next [Section titled “What’s next”](#whats-next) In Chapter 2 you’ll build a config from scratch, adding your first `[display]` block, a `[web]` block, and a single message widget. By the end of that chapter you’ll have a working one-section config and understand the basic structure every led-ticker config follows. [Continue the tutorial: Tutorial 2: Your first config →](/tutorial/02-first-config/) See also * [hardware/building-your-own](/hardware/building-your-own/) * [getting-started](/getting-started/) # Tutorial 2: Your first config > Write a minimal config.toml from scratch and see a scrolling message render live in the browser preview.  What you'll have by the end of this chapter — a single message scrolling across the sign in pink. You’ve cloned the repo and seen the bundled preview in your browser. Now you’ll write your own `config/config.toml` from scratch. By the end of this chapter you’ll have a working one-section config and understand the structure every led-ticker config follows. **\~10 min · no hardware needed** Picks up from [Chapter 1](/tutorial/01-setup/) — you’ll need the repo cloned and `make try` running (or ready to run). No new prerequisites. ## Starting point [Section titled “Starting point”](#starting-point) Delete any existing `config/config.toml` and start fresh: ```bash rm -f config/config.toml ``` Reset block — start of Chapter 2 If you ever want to reset to exactly the starting point for this chapter, create `config/config.toml` with just the `[display]` and `[web]` blocks and no widgets yet: ```toml [display] rows = 64 cols = 256 chain_length = 1 default_scale = 4 brightness = 60 [web] # lets make try show your sign live in the browser; harmless on the Pi deploy ``` ## The `[display]` block [Section titled “The \[display\] block”](#the-display-block) Open a new `config/config.toml` in your editor. Add the display block first, then a `[web]` block on the line below it: ```toml [display] rows = 64 cols = 256 chain_length = 1 default_scale = 4 brightness = 60 [web] # lets make try show your sign live in the browser; harmless on the Pi deploy ``` What each field does: * **`rows = 64`** and **`cols = 256`** — the physical dimensions of the panel array in pixels. The bigsign is eight 32×64 panels arranged in a 2×4 serpentine grid, giving a 256×64 physical canvas. * **`chain_length = 1`** — number of chains. The bigsign uses a single chain of eight panels. * **`default_scale = 4`** — the logical-to-physical ratio. All drawing happens on a **logical canvas** of `cols / scale × rows / scale` = 64×16 pixels. Every logical pixel expands to a 4×4 block on the real panel. This keeps font sizes and layout coordinates manageable, and is why the BDF pixel font looks crisp at display size. * **`brightness = 60`** — panel brightness, 0–100. 60 is a comfortable starting point. * **`[web]`** — publishes the display engine’s state so the browser preview can show your sign live. An empty block is enough; the defaults are fine for laptop use. The same block enables the web dashboard on a real Pi deploy — it’s harmless to leave it in your production config. There are several Pi-specific hardware knobs you’ll see in the example configs — `pixel_mapper_config`, `gpio_slowdown`, `hardware_mapping`, `pwm_bits`, `rp1_pio`. These control low-level GPIO timing and panel chaining. They have no effect on the laptop preview and are safe to omit until you’re deploying to real hardware. See [Hardware → Bigsign](/hardware/bigsign/) for details on those. ## Add the first widget [Section titled “Add the first widget”](#add-the-first-widget) Below the `[web]` block, add a section with one message widget: ```toml [[playlist.section]] mode = "ticker" loop_count = 1 [[playlist.section.widget]] type = "message" text = "Welcome to Firebird Yoga" font_color = [225, 48, 108] ``` A few things to notice: **The double brackets `[[...]]`** — `[[playlist.section]]` and `[[playlist.section.widget]]` use TOML’s array-of-tables syntax. Each `[[playlist.section]]` header appends a new section to the playlist array; each `[[playlist.section.widget]]` header appends a new widget to the most recently opened section. This is a common gotcha for TOML newcomers: single brackets `[...]` define a single table, double brackets `[[...]]` append to an array. **`mode = "ticker"`** — the section joins all its widgets into one continuous scrolling stream. The text enters from the right, scrolls left, and the loop repeats. Other modes (`slideshow`, `one_at_a_time`) are covered in Chapter 3. **`loop_count = 1`** — how many times to run the section before the playlist advances. For a multi-section config, `1` means each section plays once per playlist cycle. **`font_color = [225, 48, 108]`** — an RGB triple. led-ticker accepts colors as `[r, g, b]` lists anywhere a color is expected. This particular value is the Instagram magenta (`[225, 48, 108]`) the social handle uses. ## Validate [Section titled “Validate”](#validate) Before previewing, run the config validator. With `make try` running, use the try container itself (a second terminal — no Python install needed): ```bash docker exec led-ticker-try-engine led-ticker validate /code/config/config.toml ``` On a machine with the dev toolchain (`make dev` once), the direct form works too: `uv run led-ticker validate config/config.toml`. If everything is correct you’ll see: ```plaintext Validating config/config.toml... No issues found. ``` Try introducing a deliberate error — change `font_color = [225, 48, 108]` to `font_color = "pink"` and run validate again: ```plaintext Validating config/config.toml... ✗ ERROR section[0].widget[0]: unknown font_color style 'pink'; available: ['color_cycle', 'gradient', 'rainbow', 'random'] Fix: See error message for details. 1 issue(s): 1 error(s), 0 warning(s) ``` The validator catches type errors, unknown fields, and missing required values before you ever preview. Get in the habit of running it after every edit. Revert the typo before continuing. Validate from the web UI On a deployed sign, the web UI’s **Config tab** validates before saving — no terminal needed. ## Preview [Section titled “Preview”](#preview) With your config saved and the validator passing, run `make try`: ```bash make try ``` Open **** and click the **live preview** tab. You should see “Welcome to Firebird Yoga” scrolling in pink across a black background — identical to the demo at the top of this page:  The browser preview — rendered live from your config/config.toml If `make try` is still running from Chapter 1, stop it first (`Ctrl-C`) and run `make try` again — the Chapter 1 session started on the bundled example before your `config/config.toml` existed, and the config choice happens at startup. From now on you won’t need to restart: saved edits to your config hot-reload into the preview within one playlist cycle. (The exception is `[display]`-level fields, which always need a `Ctrl-C` + `make try`.) Capture a GIF instead To save a shareable GIF rather than watch the live preview, run `make render-demo CONFIG=config/config.toml OUT=preview.gif`. This needs `make dev` first (Python 3.14 + [uv](https://docs.astral.sh/uv/)). ## The edit-validate-preview loop [Section titled “The edit-validate-preview loop”](#the-edit-validate-preview-loop) Most led-ticker development follows a tight loop: edit the TOML, validate, save, and check the browser preview. Try a few concrete changes to get comfortable with it: **Change the text.** Edit `text = "Welcome to Firebird Yoga"` to something longer, then save. The browser preview updates within one playlist cycle. If you want to capture the result as a GIF with a longer duration, call the renderer directly (needs `make dev` once — see the aside above): ```bash uv run python tools/render_demo/render.py config/config.toml -o preview.gif --duration 20 ``` **Change the color.** Try a different `[r, g, b]` triple — for example `[124, 173, 232]` (sky blue) or `[255, 92, 38]` (flame orange). Validate and save after each change, then check the preview. **Add a second widget.** Append another `[[playlist.section.widget]]` block immediately after the first (still under the same `[[playlist.section]]`): ```toml [[playlist.section.widget]] type = "message" text = "Open Tuesday – Sunday * 10am – 8pm" font_color = [255, 240, 200] ``` Save. In `ticker` mode both messages appear back-to-back in a single continuous stream, separated by a small gap. The `*` character renders as a mid-dot separator — a common convention in ticker text. Each edit-validate-preview cycle takes under ten seconds on a laptop. Keep the loop tight and build confidence before moving on to the more complex sections in Chapter 3. Display-level changes need a restart Edits to widget text, colors, and section settings hot-reload within one playlist cycle while `make try` is running. Changes to `[display]` fields (`rows`, `cols`, `default_scale`) require a container restart: press Ctrl-C, then `make try` again. ## What’s next [Section titled “What’s next”](#whats-next) Chapter 3 introduces multiple sections, the `slideshow` and `one_at_a_time` modes, the `two_row` widget for two-line layouts, and hi-res emoji. You’ll go from a single message to a sign that rotates through distinct content cards. [← Back to Tutorial 1: Setup](/tutorial/01-setup/) [Continue the tutorial: Tutorial 3: Multi-widget sign →](/tutorial/03-multi-widget/) See also * [concepts/sections-and-modes](/concepts/sections-and-modes/) * [widgets/message](/widgets/message/) * [tools/validate](/tools/validate/) # Tutorial 3: Multi-widget sign > Add multiple sections, mix ticker and slideshow modes, and drop in a two_row widget with hi-res inline emoji.  What you'll have by the end of this chapter — a two-row card with a hi-res Instagram logo and scrolling promo text. Chapter 2 ended with a single `ticker` section and one message widget. This chapter adds sections, introduces the three display modes, shows how to mix widget types, and finishes with the `two_row` widget rendered at hi-res. **\~15 min · no hardware needed** Picks up from [Chapter 2](/tutorial/02-first-config/) — continue with the one-section `config/config.toml` you built there (or use the reset block below). No new prerequisites. Reset block — start of Chapter 3 If you need to reset to the starting point for this chapter, create `config/config.toml` with the state from the end of Chapter 2: ```toml [display] rows = 64 cols = 256 chain_length = 1 default_scale = 4 brightness = 60 [[playlist.section]] mode = "ticker" loop_count = 1 [[playlist.section.widget]] type = "message" text = "Welcome to Firebird Yoga" font_color = [225, 48, 108] ``` ## Sections and modes [Section titled “Sections and modes”](#sections-and-modes) A config can have multiple `[[playlist.section]]` blocks. The playlist cycles through them in order, looping forever. Each section picks its own `mode`: * **`ticker`** — all widgets in the section scroll end-to-end as one continuous stream. The text exits left and re-enters right on the next loop — the classic news ticker feel. * **`slideshow`** — each widget is displayed individually, held for `hold_time` seconds. If the content is wider than the canvas it scrolls before holding; otherwise it’s shown statically. Transitions between widgets are animated. * **`one_at_a_time`** — each widget scrolls fully off the left edge before the next one enters from the right. No overlap between consecutive messages, and no held pause or transition between them. Add a second section to your config — a `slideshow` section with two short messages: ```toml [transitions] default = "push_left" duration = 0.5 [[playlist.section]] mode = "ticker" loop_count = 1 scroll_step_ms = 40 [[playlist.section.widget]] type = "message" text = "Welcome to Firebird Yoga" font_color = [225, 48, 108] [[playlist.section.widget]] type = "message" text = "Open Tuesday – Sunday * 10am – 8pm" font_color = [255, 240, 200] [[playlist.section]] mode = "slideshow" loop_count = 1 hold_time = 2.5 transition = "push_left" [[playlist.section.widget]] type = "message" text = "Open daily" font_color = [120, 220, 255] [[playlist.section.widget]] type = "message" text = "10am – 8pm" font_color = [225, 48, 108] ``` A few new fields: * **`[transitions]`** — sets the default transition for the whole config. `push_left` slides the outgoing content off left while the incoming content slides in from the right. `duration = 0.5` sets the transition length in seconds. * **`scroll_step_ms`** — milliseconds of wall-clock time between each one-pixel scroll step. 40 ms gives a comfortable reading pace. * **`transition = "push_left"` on a section** — overrides the default for that section’s inter-widget transitions. * **`hold_time = 2.5`** — how long to hold each widget in `slideshow` mode before moving to the next. Validate, then save. The browser preview updates within one playlist cycle — you’ll see the two messages scroll side-by-side in section 1, then the sign switches to the two held cards in section 2:  Two sections: ticker followed by slideshow. The push\_left transition connects both the section boundary and the inter-widget transition within section 2. ## Adding more widget types [Section titled “Adding more widget types”](#adding-more-widget-types) The `countdown` widget shows a day-count label. It takes `message` (the label text) and `countdown_date` (a TOML date literal). Add a third section that mixes a countdown with an announcements message: ```toml [[playlist.section]] mode = "ticker" loop_count = 1 scroll_step_ms = 40 [[playlist.section.widget]] type = "countdown" text = "Summer Camps" countdown_date = 2026-06-15 font_color = [180, 220, 180] [[playlist.section.widget]] type = "message" text = "All ages welcome * Drop-ins welcome" font_color = [255, 220, 0] ``` The countdown renders as `Summer Camps: 35` (or however many days remain). It scrolls through the same `ticker` stream as the message widget on either side — no special treatment needed.  Three sections. The third section streams the countdown and the announcement message side-by-side in a ticker section. You can substitute any widget type wherever a `message` appears. The playlist engine treats them uniformly — widget output is just pixels on a canvas. ## The two\_row widget — basic [Section titled “The two\_row widget — basic”](#the-two_row-widget--basic) `two_row` splits the canvas into a fixed top row and a scrolling bottom row. The top row holds a label or handle; the bottom row scrolls through longer content. Add a new `slideshow` section for the two\_row widget. The simplest baseline uses `scale = 1` — the logical canvas is the full 256 pixels wide, with `content_height = 16` centered on the 64-row panel. The default 50/50 band split gives an 8-row top band and an 8-row bottom band, each tall enough for the bundled BDF `5x8` font: ```toml [[playlist.section]] mode = "slideshow" scale = 1 content_height = 16 loop_count = 1 hold_time = 8.0 scroll_step_ms = 35 [[playlist.section.widget]] type = "two_row" top_text = ":instagram: @firebird.demo" top_color = [225, 48, 108] top_align = "center" bottom_text = "Vinyasa · yin · hot power · restorative · slow flow · all levels" bottom_color = [255, 240, 200] bottom_align = "left" ``` The `two_row` knobs used here: * **`top_text`** / **`bottom_text`** — the content for each row. The top is held; the bottom scrolls automatically when it overflows the canvas width. * **`top_color`** / **`bottom_color`** — independent color per row. * **`top_align`** — `"center"` centers the top label. Options: `"left"`, `"center"`, `"right"`. * **`bottom_align`** — `"left"` starts the bottom scroll from the left edge.  two\_row at scale=1, content\_height=16: '@firebird.demo' held next to the 8×8 lo-res Instagram sprite on the top row, promo text scrolling across the bottom. The top row is static throughout; only the bottom row moves. `hold_time = 8.0` gives the bottom text enough time to complete one full scroll pass. The `:instagram:` emoji renders as the **8×8 lo-res sprite** here. The full-color 32×32 hi-res variant exists in the bundled emoji registry, but the 8-row top band is too short to fit it — the renderer caps emoji height at the band size and falls back to lo-res when the hi-res sprite would overflow. The next section shows how to make room for the hi-res sprite. ## Two-row with hi-res emoji — the hard configuration case [Section titled “Two-row with hi-res emoji — the hard configuration case”](#two-row-with-hi-res-emoji--the-hard-configuration-case) The basic `two_row` above renders using the default BDF `5x8` bitmap font and gets the 8×8 lo-res Instagram sprite because the 8-row top band can’t fit anything bigger. The polished version bumps to `scale = 2` and raises three knobs — `content_height`, `top_row_height`, and a hi-res `top_font` — so the full-color 32×32 Instagram sprite renders alongside Inter-Bold text. ### Why the math matters [Section titled “Why the math matters”](#why-the-math-matters) led-ticker enforces one hard ceiling on per-section sizing: ```plaintext scale × content_height ≤ panel_h_real ``` For the bigsign at `default_scale = 4`, `panel_h_real = 64`. With per-section `scale = 2`, the ceiling is `64 / 2 = 32` logical px — room to make the section taller than the previous `content_height = 16`. For the hi-res two\_row you want: | knob | basic (above) | polished | real px (polished) | | ---------------- | ------------- | ----------- | -------------------- | | `scale` | 1 | 2 | — | | `content_height` | 16 | 24 | 48 real px (≤ 64 ✓) | | `top_row_height` | default (8) | 16 | 32 real px | | bottom band | 8 | 24 − 16 = 8 | 16 real px | | `top_font` | default 5x8 | Inter-Bold | hi-res rasterisation | The 32×32 hi-res Instagram sprite is `32 real px / scale 2 = 16 logical px` tall. That fits the 16-row top band exactly — the band’s emoji cap rises from 8 (in the basic version, where scale=1 so 8 real px = 8 logical px) to 16 (here, where scale=2 so 32 real px = 16 logical px), so the renderer uses the hi-res sprite instead of falling back to lo-res. ### The config [Section titled “The config”](#the-config) ```toml [[playlist.section]] mode = "slideshow" scale = 2 content_height = 24 loop_count = 1 hold_time = 8.0 scroll_step_ms = 35 [[playlist.section.widget]] type = "two_row" top_text = ":instagram: @firebird.demo" top_row_height = 16 top_font = "Inter-Bold" top_font_size = 22 top_color = [225, 48, 108] top_align = "left" bottom_text = "Vinyasa · yin · hot power · restorative · slow flow · all levels" bottom_color = [255, 240, 200] bottom_align = "left" ``` New knobs: * **`top_row_height = 16`** — the top band takes 16 of the 24 logical rows. The remaining 8 go to the bottom row. * **`top_font = "Inter-Bold"`** — switches the top row to the bundled Inter Bold hi-res font. BDF fonts (`5x8`, `6x13`, etc.) are pixel-perfect at any scale; hi-res fonts render at physical pixel granularity and look proportional at scale ≥ 2. * **`top_font_size = 22`** — physical pixel height for the hi-res font. Required when `top_font` is a hi-res font; the validator raises an error if you omit it.  two\_row at scale=2, content\_height=24: the full-color Instagram sprite on the top row, Inter-Bold handle, BDF marquee below. Compare side-by-side with the BDF version from the previous section:  For reference: the same content at scale=1, content\_height=16 (no extra top-row space) with the default 5x8 BDF font. The Instagram sprite drops to the 8×8 lo-res variant. The hi-res path activates automatically when the **effective (per-section) scale is ≥ 2 and the band is tall enough** to fit the bigger sprite — you don’t need a separate code path. It’s the per-section `scale`, not `default_scale`, that matters: this chapter’s bigsign runs `default_scale = 4` yet the basic `two_row` section above renders lo-res because its per-section `scale = 1`. The `:instagram:` slug always resolves to the correct sprite size for the current effective scale and band height. ## Seamless wrap with a loop count [Section titled “Seamless wrap with a loop count”](#seamless-wrap-with-a-loop-count) The hi-res config above scrolls the bottom row once, end-to-end, then transitions. That works for short content but feels abrupt for marquee-style text. The bottom row supports a **continuous wrap mode**: when the text scrolls off the left edge, the next copy is already coming in from the right, separated by a glyph you control. Combine wrap with `bottom_text_loops` to declare exactly how many full passes the marquee plays before the section ends. Add three lines to the hi-res config: ```toml [[playlist.section]] mode = "slideshow" scale = 2 content_height = 24 loop_count = 1 # hold_time omitted — bottom_text_loops = 3 below controls duration scroll_step_ms = 35 [[playlist.section.widget]] type = "two_row" top_text = ":instagram: @firebird.demo" top_row_height = 16 top_font = "Inter-Bold" top_font_size = 22 top_color = [225, 48, 108] top_align = "left" bottom_text = "Vinyasa · yin · hot power · restorative · slow flow · all levels" bottom_color = [255, 240, 200] bottom_align = "left" bottom_text_wrap = true bottom_text_separator = " · " bottom_text_loops = 3 ``` What changed: * **`hold_time` is gone.** When `bottom_text_loops` is set, the engine runs for `max(hold_time_ticks, loops × cycle_width)` ticks. Removing `hold_time` uses the default (3.0s), which at `scroll_step_ms = 35` is only \~85 ticks — far fewer than `3 × cycle_width`. The loops win and the section runs for exactly 3 wrap cycles. * **`bottom_text_wrap = true`** switches the bottom row from “scroll once and stop” to a continuous chase. The text plus separator forms one cycle; copies follow each other across the canvas with no gap. * **`bottom_text_separator = " · "`** uses the same middle-dot character that’s already separating phrases inside `bottom_text`, so the seam between wrap copies reads as part of the same rhythm. The string renders as-is — the spaces around the dot are intentional padding. `""` would render as two spaces (no glyph, minimum gap); `"*"` (no surrounding space) would butt the asterisk directly against the adjacent letters. * **`bottom_text_loops = 3`** is the minimum number of full cycles before the section can transition. Only meaningful with `bottom_text_wrap = true` — setting `bottom_text_loops` on a non-wrap section is a validation error — the validator will tell you — because there’s no cycle to count when the bottom only scrolls once. A note on the field name: `bottom_text_loops` follows the `bottom_*` prefix convention used by all per-row knobs on `two_row` (`bottom_text_wrap`, `bottom_text_separator`, etc.) — the top row is held and only the bottom row can have cycles. If you’ve used the marquee loop count on a `gif` or `image` widget, the equivalent field there is called `text_loops` (no prefix), since those widgets are single-row by default and only optionally become two-row when `bottom_text` is set. Same concept, different name — the validator catches the common `text_loops` typo on `two_row` and points you at `bottom_text_loops`. A note on `hold_time`: if you set BOTH `hold_time` and `bottom_text_loops`, the engine uses whichever produces more ticks — `max(hold_time × 1000 / scroll_step_ms, bottom_text_loops × cycle_width)`. The validator warns when both are explicitly set, because the dominant value silently overrides the other depending on text length. The “exact-N-loops” pattern in this tutorial drops `hold_time` to avoid the ambiguity. ## What’s next [Section titled “What’s next”](#whats-next) Chapter 4 adds custom branding: the Atkinson Hyperlegible font for the title card and a still image widget that displays a logo. [← Back to Tutorial 2: Your first config](/tutorial/02-first-config/) [Continue the tutorial: Tutorial 4: Custom branding →](/tutorial/04-custom-branding/) See also * [concepts/sections-and-modes](/concepts/sections-and-modes/) * [widgets/two\_row](/widgets/two_row/) * [reference/config-options](/reference/config-options/) * [pitfalls](/pitfalls/) # Tutorial 4: Custom branding > Load Atkinson Hyperlegible for distance-legible text, add a logo image widget, and combine the two with a text overlay for a polished brand card.  What you'll have by the end of this chapter — a phoenix logo with a scrolling Atkinson Hyperlegible promo line underneath. Chapter 3 left you with a polished `two_row` section using Inter-Bold and the hi-res Instagram sprite. This chapter adds the last two branding pieces: a custom font that was designed for real-world legibility, and an image widget that displays your logo. **\~15 min · no hardware needed** **What you’ll need:** * The config from [Chapter 3](/tutorial/03-multi-widget/) (or the reset block below) * A brand font in `config/fonts/` — this chapter downloads **Atkinson Hyperlegible** (`AtkinsonHyperlegible-Bold.otf` and `-Regular.otf`) from the Braille Institute * A logo image in `config/assets/` — the repo ships `config/assets/phoenix_transparent.png`, used here Reset block — start of Chapter 4 If you need to reset to the starting point for this chapter, create `config/config.toml` with the state from the end of Chapter 3: ```toml [display] rows = 64 cols = 256 chain_length = 1 default_scale = 4 brightness = 60 [transitions] default = "push_left" duration = 0.5 [[playlist.section]] mode = "ticker" loop_count = 1 scroll_step_ms = 40 [[playlist.section.widget]] type = "message" text = "Welcome to Firebird Yoga" font_color = [225, 48, 108] [[playlist.section.widget]] type = "message" text = "Open Tuesday – Sunday * 10am – 8pm" font_color = [255, 240, 200] [[playlist.section]] mode = "slideshow" loop_count = 1 hold_time = 2.5 transition = "push_left" [[playlist.section.widget]] type = "message" text = "Open daily" font_color = [120, 220, 255] [[playlist.section.widget]] type = "message" text = "10am – 8pm" font_color = [225, 48, 108] [[playlist.section]] mode = "ticker" loop_count = 1 scroll_step_ms = 40 [[playlist.section.widget]] type = "countdown" text = "Summer Camps" countdown_date = 2026-06-15 font_color = [180, 220, 180] [[playlist.section.widget]] type = "message" text = "All ages welcome * Drop-ins welcome" font_color = [255, 220, 0] [[playlist.section]] mode = "slideshow" scale = 2 content_height = 24 loop_count = 1 hold_time = 8.0 scroll_step_ms = 35 [[playlist.section.widget]] type = "two_row" top_text = ":instagram: @firebird.demo" top_row_height = 16 top_font = "Inter-Bold" top_font_size = 22 top_color = [225, 48, 108] top_align = "left" bottom_text = "Vinyasa · yin · hot power · restorative · slow flow · all levels" bottom_color = [255, 240, 200] bottom_align = "left" ``` ## Adding a custom font [Section titled “Adding a custom font”](#adding-a-custom-font) led-ticker ships with Inter Bold and Inter Regular as bundled hi-res fonts, which cover most use cases. But for a venue sign that needs to be readable from across a room, a font designed specifically for legibility at distance makes a real difference. **Atkinson Hyperlegible** is a typeface created by the Braille Institute to maximize readability for people with low vision — and those same design choices (open letterforms, unambiguous character shapes, generous spacing) make it excellent for LED signs read from 3–10 metres away. It’s available free under the Open Font License. Download it from the Braille Institute: > **** — click “Download Now” for the ZIP. Alternatively, Google Fonts also hosts it: > Both sources include Regular and Bold weights. Either `.otf` or `.ttf` files work — led-ticker’s hi-res loader accepts both. Once downloaded, place the files next to your config: ```plaintext config/ config.toml fonts/ AtkinsonHyperlegible-Bold.otf AtkinsonHyperlegible-Regular.otf ``` The `config/fonts/` directory is gitignored in the led-ticker repo, so the font files won’t be committed if you’re working inside the repository. For your own production config (outside the repo), treat `fonts/` as a sibling to `config.toml` — led-ticker finds it automatically at startup. Note **Font name is the filename stem.** `AtkinsonHyperlegible-Bold.otf` is referenced in TOML as `top_font = "AtkinsonHyperlegible-Bold"`. No path, no extension — just the stem. The same applies to any other font you add to `config/fonts/`. ## Using the font in a widget [Section titled “Using the font in a widget”](#using-the-font-in-a-widget) In Chapter 3’s `two_row` section, the top row uses `top_font = "Inter-Bold"`. Swap it for the new font: ```toml [[playlist.section.widget]] type = "two_row" top_text = ":instagram: @firebird.demo" top_row_height = 16 top_font = "AtkinsonHyperlegible-Bold" top_font_size = 22 top_color = [225, 48, 108] top_align = "left" bottom_text = "Vinyasa · yin · hot power · restorative · slow flow · all levels" bottom_color = [255, 240, 200] bottom_align = "left" ``` Only `top_font` changed. Everything else — scale, band heights — stays the same. Here is the Inter-Bold version from Chapter 3 for comparison:  Chapter 3: Inter-Bold on the top row. Clean, but the double-story 'a' and closed letterforms are harder to read at distance. And the same config with Atkinson Hyperlegible-Bold:  Chapter 4: Atkinson Hyperlegible-Bold. Open single-story 'a', wider apertures, unambiguous 'n'/'m' stems — more readable at 5+ metres. The difference is subtle on-screen but pronounced on the physical panel. Atkinson’s wider letter spacing and open forms survive the LED dot-grid better than Inter’s tighter proportions at the same pixel size. If your font has thin strokes that wash out at the default rasterization threshold, the `font_threshold` knob (0–255, default 128) lets you lower the cutoff to preserve more of the hairlines. A value around 80 suits most thin-stroked typefaces. See [Concepts → Fonts](/concepts/fonts/) for the full tuning story. ## Adding a logo image [Section titled “Adding a logo image”](#adding-a-logo-image) The `image` widget displays a PNG, JPEG, or WebP still image on the panel. The repository ships with `config/assets/phoenix_transparent.png` — a PNG with a transparent background — for exactly this use case. Add a new `slideshow` section after the `two_row` section: ```toml [[playlist.section]] mode = "slideshow" loop_count = 1 hold_time = 2.5 [[playlist.section.widget]] type = "message" text = "Open daily" font_color = [120, 220, 255] [[playlist.section.widget]] type = "message" text = "10am – 8pm" font_color = [225, 48, 108] [[playlist.section.widget]] type = "image" path = "assets/phoenix_transparent.png" fit = "pillarbox" image_align = "center" hold_time = 4.0 [[playlist.section.widget]] type = "message" text = "All ages welcome" font_color = [255, 220, 0] ``` The `image` widget knobs used here: * **`path`** — path to the image file, relative to `config.toml`. The bundled `phoenix_transparent.png` lives in `config/assets/`. * **`fit = "pillarbox"`** — scales the image to fill the panel height, leaving black bars on the sides if the image is taller than it is wide. Other options: `"letterbox"` (fill width, bars top/bottom), `"stretch"` (distort to fill), `"crop"` (fill and trim). For a logo with transparent background, `"pillarbox"` is usually the right choice. * **`image_align = "center"`** — centers the image horizontally within the panel. Options: `"left"`, `"center"`, `"right"`. * **`hold_time = 4.0`** — how long to display the image before the next widget. This is the same `hold_time` knob as the section default, just set on the widget: a widget-level `hold_time` overrides the section’s `hold_time` for that one widget, and widgets that don’t set their own fall back to the section default.  Image widget in a slideshow section: two message cards, the phoenix logo, then a third message — all joined by push\_left transitions. The transparent PNG regions render as black on the panel (LEDs are off), which creates a clean silhouette effect. Opaque images fill every pixel; transparent ones let the panel background show through. ## Combining text and image [Section titled “Combining text and image”](#combining-text-and-image) The `image` widget supports the same two-row text overlay as the `two_row` widget from Chapter 3. Setting `top_text` and `bottom_text` on an `image` widget layers a held title on top and a scrolling promo line on the bottom — with the image visible behind or between them. Replace the bare image widget from above with the text overlay version: ```toml [[playlist.section.widget]] type = "image" path = "assets/phoenix_transparent.png" fit = "pillarbox" image_align = "center" hold_time = 8.0 scroll_speed_ms = 35 top_text = "Firebird" top_font = "5x8" top_color = [225, 48, 108] bottom_text = "Vinyasa · yin · hot power · restorative · slow flow · all levels" bottom_font = "AtkinsonHyperlegible-Bold" bottom_font_size = 22 bottom_color = [255, 240, 200] ``` New knobs compared to the plain image widget: * **`hold_time = 8.0`** — longer hold to give the bottom text time to complete one full scroll pass. The engine waits for at least one full traversal regardless, but setting this explicitly prevents a premature cut. * **`scroll_speed_ms = 35`** — milliseconds per one-pixel scroll step for the bottom text. Lower = faster; 35 ms is a comfortable reading pace. * **`top_text`** / **`top_font`** / **`top_color`** — held top row, same knobs as `two_row`. Using `"5x8"` (a BDF font) here means no `top_font_size` is required. At `default_scale = 4` the logical canvas is 64 columns wide; `"Firebird"` (40 px in 5x8) fits comfortably. Chapter 5 adds the full social handle and the hi-res Instagram sprite, which need a wider canvas. * **`bottom_text`** / **`bottom_font`** / **`bottom_font_size`** / **`bottom_color`** — scrolling bottom row with Atkinson Hyperlegible-Bold. `bottom_font_size` is required for any hi-res font; `22` (real pixels) fits comfortably in the bottom band at `default_scale = 4`.  Image widget with two-row text overlay: studio name held on top, the phoenix logo centered, Atkinson Hyperlegible promo text scrolling across the bottom. This is the same two-row layout primitive as Chapter 3’s `two_row` widget, applied directly to an image. The image paints behind the bottom text; where the bottom row overlaps the image, the text renders on top. Use `text_align = "scroll_over"` if you want the text always above the image (see [Widgets → image](/widgets/image/) for the full overlay paint-order options). ## What’s next [Section titled “What’s next”](#whats-next) Chapter 5 covers polish and deploy: `bg_color` for bordered sections, `border` effects, and the steps to get your config running on the Pi. [← Back to Tutorial 3: Multi-widget sign](/tutorial/03-multi-widget/) [Continue the tutorial: Tutorial 5: Polish & deploy →](/tutorial/05-polish/) See also * [concepts/fonts](/concepts/fonts/) * [widgets/image](/widgets/image/) * [assets/emoji](/assets/emoji/) # Tutorial 5: Polish & deploy > Add transitions and border effects to the Firebird Yoga config, then copy it to a Raspberry Pi and run it with Docker.  What you'll have by the end of this chapter — wipe transitions between widgets, a dissolve between sections, and an animated rainbow border on the headline widget. Chapter 4 left you with a multi-section config: a scrolling welcome strip, a swap section with per-day hours, a two-row hi-res brand card, and an image widget with a text overlay. This chapter adds two polish layers — transitions and border effects — then covers getting the config onto a Pi. **\~10 min · no hardware needed** Picks up from [Chapter 4](/tutorial/04-custom-branding/) — continue with the config you built there (or use the reset block below). No new prerequisites; the deploy section is read-only and needs no Pi. Reset block — start of Chapter 5 If you followed chapters 2–4 step by step, your config will have MORE sections than this (the ticker from chapter 2, the standalone `two_row`, and so on) — that’s expected. This reset block is a deliberately consolidated starting point for the polish work, not a literal copy of your chapter-4 end state. Either continue with your own config or start from this cleaner baseline: ```toml [display] rows = 64 cols = 256 chain_length = 1 default_scale = 4 brightness = 60 [transitions] default = "push_left" duration = 0.5 [[playlist.section]] mode = "slideshow" loop_count = 1 hold_time = 2.5 [[playlist.section.widget]] type = "message" text = "Welcome to Firebird Yoga" font_color = [225, 48, 108] [[playlist.section.widget]] type = "image" path = "assets/phoenix_transparent.png" fit = "pillarbox" image_align = "center" hold_time = 8.0 scroll_speed_ms = 35 top_text = "Firebird" top_font = "5x8" top_color = [225, 48, 108] bottom_text = "Vinyasa · yin · hot power · restorative · slow flow · all levels" bottom_font = "AtkinsonHyperlegible-Bold" bottom_font_size = 22 bottom_color = [255, 240, 200] [[playlist.section.widget]] type = "message" text = "Open daily 10am – 8pm" font_color = [120, 220, 255] [[playlist.section]] mode = "slideshow" loop_count = 1 hold_time = 2.5 [[playlist.section.widget]] type = "message" text = "Summer Camps start June 15" font_color = [180, 220, 180] [[playlist.section.widget]] type = "message" text = "All levels · All ages" font_color = [255, 220, 0] ``` ## Transitions [Section titled “Transitions”](#transitions) So far the config has used `push_left` for everything. The `[transitions]` block has two separate knobs — `default` controls transitions between widgets inside a section, and `between_sections` controls the transition when the playlist moves from one section to the next. You can set them independently. Replace the `[transitions]` block: ```toml [transitions] default = "wipe_left" duration = 0.5 between_sections = "dissolve" ``` * **`default = "wipe_left"`** — a vertical sweep line erases the outgoing widget, then the incoming widget appears behind it. More visual punch than `push_left`; the sweeping line makes each widget boundary feel intentional. * **`between_sections = "dissolve"`** — when the playlist moves from Section 1 to Section 2 (or back), pixels scatter randomly rather than sliding. The contrast with the within-section wipes gives viewers a clear signal that the topic has changed. * **`duration`** applies to both, unless overridden per-section with `transition_duration`.  wipe\_left between widgets, dissolve between sections. The wipe sweep line is visible mid-transition; the dissolve scatter marks each section boundary. The full transition catalogue covers 30+ options organised into families: * **Push** (`push_left`, `push_right`, `push_up`, `push_down`, `push_alternating`, `push_random`) — outgoing and incoming slide together as one unit. * **Wipe** (`wipe_left`, `wipe_right`, `wipe_up`, `wipe_down`, `wipe_alternating`, `wipe_random`) — outgoing stays fixed while a coloured sweep line erases it. * **Sprite trails** — `nyancat.forward`, `pokeball.forward`, `pacman.forward`, `sailor_moon.forward` (each has `.reverse` and `.alternating` variants; the first two have bigsign hi-res variants). These ship as four packages in the [led-ticker-plugins](https://github.com/JamesAwesome/led-ticker-plugins) monorepo. A rolling-`baseball.roll` family ships in the [baseball](https://github.com/JamesAwesome/led-ticker-plugins/tree/main/plugins/baseball) package. * **Special** — `cut` (instant), `color_flash`, `dissolve`, `split`, `scroll`. See the [Transitions catalogue](/transitions/) for per-family knobs and examples of each. ## Border effects [Section titled “Border effects”](#border-effects) The `border` field paints an animated ring around the panel perimeter. It accepts `"rainbow"` for a chasing hue sweep, or an RGB array like `[255, 100, 200]` for a static colour. Add `border = "rainbow"` to the headline widget: ```toml [[playlist.section.widget]] type = "message" text = "Welcome to Firebird Yoga" font_color = "rainbow" border = "rainbow" ``` `font_color = "rainbow"` was also added here — the per-character hue sweep across the text and the chasing perimeter ring use the same hue formula, so they feel like one coherent effect rather than two competing ones. For the second section’s headline: ```toml [[playlist.section.widget]] type = "message" text = "Summer Camps start June 15" font_color = [180, 220, 180] border = "rainbow" ``` A few things worth knowing about borders: * The border paints at **physical resolution** — at `default_scale = 4` it traces the real 256×64 panel edge, not the logical 64×16 wrapper. The ring is always 1 pixel wide at real-panel scale. * **Border, transitions, and font effects all compose.** The wipe transition runs cleanly over a bordered widget; the rainbow font sweep continues animating during the hold that the border is also chasing. * `border` is accepted on `message`, `countdown`, `two_row`, `gif`, and `image` widgets. It raises at config-load for other types. ## Polish the brand card [Section titled “Polish the brand card”](#polish-the-brand-card) The image widget currently shows the studio name in BDF `5x8` at `default_scale = 4`, which gives 64 logical columns. That’s enough for the short name but not for the full social handle: `@firebirdyoga.demo` (18 chars × 5 px = 90 px) would overflow the canvas by 26 px. To show the full handle and the hi-res Instagram sprite alongside it, the brand card needs its own section at `scale = 2`. Two changes — restructure the section layout, then upgrade the handle. **Restructure.** Pull the image widget out of Section 1 into its own section. This lets the brand card use `scale = 2` without affecting the welcome and info widgets, which look right at the default `scale = 4`: ```toml # Section 1 — welcome card [[playlist.section]] mode = "slideshow" loop_count = 1 hold_time = 2.5 [[playlist.section.widget]] type = "message" text = "Welcome to Firebird Yoga" font_color = "rainbow" border = "rainbow" # Section 2 — brand card (new, scale = 2) [[playlist.section]] mode = "slideshow" scale = 2 content_height = 32 loop_count = 1 hold_time = 5.0 [[playlist.section.widget]] type = "image" path = "assets/phoenix_transparent.png" fit = "pillarbox" image_align = "center" hold_time = 4.0 scroll_speed_ms = 35 top_text = ":instagram: @firebirdyoga.demo" top_row_height = 16 top_font = "Inter-Bold" top_font_size = 16 top_color = [225, 48, 108] bottom_text = "Vinyasa · yin · hot power · restorative · slow flow · all levels" bottom_font = "Inter-Bold" bottom_font_size = 22 bottom_color = [255, 240, 200] # Section 3 — info messages (the old Summer Camps + All levels section, # plus the "Open daily 10am – 8pm" message moved out of Section 1) [[playlist.section]] mode = "slideshow" loop_count = 1 hold_time = 2.5 [[playlist.section.widget]] type = "message" text = "Summer Camps start June 15" font_color = [180, 220, 180] border = "rainbow" [[playlist.section.widget]] type = "message" text = "Open daily 10am – 8pm" font_color = [120, 220, 255] [[playlist.section.widget]] type = "message" text = "All levels · All ages" font_color = [255, 220, 0] ``` What changed on the brand card: * **`scale = 2` on Section 2** — overrides `default_scale = 4` for this section. Logical canvas widens from 64 to 128 px, leaving room for the longer handle and the hi-res Instagram sprite. * **`content_height = 32`** — fills the full panel height at scale 2 (`32 × 2 = 64` real px). The hard ceiling. This matters because the phoenix image uses `fit = "pillarbox"` and looks best filling the panel. * **`top_row_height = 16`** — gives the top band 16 logical rows, which matches the hi-res Instagram sprite’s 16 logical px height (`32 real px / scale = 16 logical`). Without this, the sprite falls back to the 8×8 lo-res variant. * **`top_text = ":instagram: @firebirdyoga.demo"`** — the `:instagram:` inline emoji renders as the full-colour hi-res sprite now that the band can fit it. The remaining text is the full handle, no shortening needed. * **`top_font = "Inter-Bold"`, `top_font_size = 16`** — switched from `5x8` BDF to Inter-Bold for visual consistency with the bottom row. * **`bottom_font = "Inter-Bold"`** — switched from Atkinson Hyperlegible to the bundled Inter-Bold. Atkinson works great if you’re keeping a personal copy in `config/fonts/`, but the canonical destination config uses only bundled fonts so a fresh `git clone` can render it without the font download.  The final config. Welcome card with rainbow font + chasing border; brand card with the hi-res Instagram sprite and full @firebirdyoga.demo handle; info section with Summer Camps + Open daily + All levels. wipe\_left transitions within sections, dissolve between. ## What you’ve built [Section titled “What you’ve built”](#what-youve-built) Your config now has: * A three-section playlist in `slideshow` mode with `wipe_left` transitions between widgets and `dissolve` between sections. * A welcome card with per-character rainbow `font_color` and a chasing rainbow border around the panel perimeter. * A brand card running at per-section `scale = 2` so the hi-res Instagram sprite renders at the full 32×32 next to the `@firebirdyoga.demo` handle. The phoenix image fills the panel; promo text scrolls across the bottom row. * An info section with three message widgets — Summer Camps (rainbow border), Open daily, and All levels — held briefly so each is readable. That matches the destination config you rendered in Chapter 1 (`config/config.bigsign.firebird.example.toml`). The next step is getting it onto a Pi. ## Deploying to a Pi [Section titled “Deploying to a Pi”](#deploying-to-a-pi) Your config is ready — this is what the five chapters were building toward. **[Quickstart B](/getting-started/#quickstart-b--deploy-to-your-pi) is the complete deploy path** — it takes a Pi from bare OS to a running sign, and it ends with your panels lit. If the hardware itself isn’t built yet, [Building your own](/hardware/building-your-own/) covers panels, wiring, and power first. One difference from a stock Quickstart B run: at its “copy the right example config” step, use the config you just built here instead — copy your `config/` folder (with `config.toml`, `fonts/`, and `assets/`) into the cloned repo on the Pi. Already have the stack running? Copy the folder over and run `make restart`. The hardware pages below have the full bill of materials, wiring diagrams, and Pi-specific tuning for `gpio_slowdown`, `rp1_pio`, and `pixel_mapper_config`. See also * [hardware/bigsign](/hardware/bigsign/) * [hardware/smallsign](/hardware/smallsign/) * [hardware/building-your-own](/hardware/building-your-own/) ## What’s next from here [Section titled “What’s next from here”](#whats-next-from-here) With a working panel config as a foundation, a few directions worth exploring: * **Try other transitions.** Swap `wipe_left` for `nyancat.forward` or `pokeball.forward` (the `nyancat` / `pokeball` packages in the [led-ticker-plugins](https://github.com/JamesAwesome/led-ticker-plugins) monorepo) to see what the sprite-trail families look like on your hardware. The [Transitions catalogue](/transitions/) has a rendered preview for every option. * **Add live data widgets.** Plugin widgets pull live content and scroll it on the same canvas — `rss.feed` for headlines and `weather.current` for current conditions (the `rss` / `weather` packages), and `crypto.coingecko` (the `crypto` package) for crypto prices, all from [led-ticker-plugins](/plugins/available/). See the [Widgets reference](/widgets/) for setup details and required API keys. * **Validate before deploying.** `led-ticker validate config/config.toml` catches typos, unknown widget types, and constraint violations before you restart the panel. The [Validation rules](/pitfalls/) page lists the most common mistakes and their fix. * **Let Claude author configs for you.** The `creating-a-config` skill in Claude Code knows the widget catalogue, bigsign vs smallsign tradeoffs, and the constraint list from CLAUDE.md. Describe what you want displayed and it builds the TOML. [← Back to Tutorial 4: Custom branding](/tutorial/04-custom-branding/) # Why led-ticker? > led-ticker vs WLED, Tidbyt/tronbyt, AWTRIX, and rpi-rgb-led-matrix — when a Raspberry Pi HUB75 info sign is the right tool, and when it isn't. led-ticker is the batteries-included info-display layer for large HUB75 signs on a Raspberry Pi — the higher-level layer above the `rpi-rgb-led-matrix` driver, fully open and self-hosted. Most “LED matrix” tools solve a different problem. This page says which is which so you can pick the right one. ## Is led-ticker right for you? [Section titled “Is led-ticker right for you?”](#is-led-ticker-right-for-you) Tip Pick the tool that matches your use case: * **Addressable LED strips or panels (WS2812/SK6812), ambient effects, or lighting art** → [WLED](https://github.com/WLED/WLED) * **A cheap (\~$50) tiny desk clock or smart-home notifier** → [AWTRIX3](https://github.com/Blueforcer/awtrix3) on a Ulanzi TC001 (ESP32, 32×8) * **A small finished appliance with an app-store experience** → [Tidbyt](https://tidbyt.com/), or [tronbyt](https://github.com/tronbyt/server) to self-host one cloud-free * **Generative art or live-coded patterns** → [Pixelblaze](https://electromage.com/pixelblaze) or WLED * **A large, custom, config-driven info sign** (news / weather / crypto / sports / calendar) you self-host end-to-end → **led-ticker** ## How the tools compare [Section titled “How the tools compare”](#how-the-tools-compare) | Axis | led-ticker | rpi-rgb-led-matrix | WLED | Tidbyt / tronbyt | AWTRIX3 | | ------------------ | -------------------------- | ------------------- | ----------------------------- | ---------------------------------------------------------- | -------------------------------------- | | Hardware | HUB75 panels | HUB75 panels | Addressable WS2812 | 64×32 appliance | 32×8 (Ulanzi) | | Compute | Raspberry Pi | Raspberry Pi | ESP32 | Appliance / Pi | ESP32 | | Scale | Large, custom (256×64+) | Large | Strips / small matrices | Tiny, fixed | Tiny, fixed | | Primary use | Info feeds / signage | (you build it) | Effects / ambient art | Glanceable apps | Clock / notifier | | Content model | Declarative TOML + plugins | Write your own code | Web UI (push strings in) | App store (Pixlet) | Web UI + HA/MQTT | | Architecture | Self-contained on the Pi | Library you call | Self-contained; you feed text | tronbyt needs a self-hosted server; Tidbyt needs its cloud | Needs Home Assistant / MQTT to feed it | | Open / self-hosted | Fully open, no cloud | Open library | Open | tronbyt open / Tidbyt closed+cloud | Open firmware | | Cost band | \~$150+ | \~$150+ | \~$30+ | \~$199 / DIY | \~$50 | ## The alternatives in their own right [Section titled “The alternatives in their own right”](#the-alternatives-in-their-own-right) ### rpi-rgb-led-matrix [Section titled “rpi-rgb-led-matrix”](#rpi-rgb-led-matrix) The canonical low-level HUB75 driver that led-ticker builds on — think of it as the layer below, not a rival.[1](#user-content-fn-hzeller) It gives you full control over every pixel in C++ or Python, which is exactly right if you want to write your own rendering engine. led-ticker is the batteries-included layer on top so you don’t have to: declarative config, a plugin system for live data feeds, transitions, fonts, and emoji all come included. ### WLED [Section titled “WLED”](#wled) WLED is a widely-used platform for addressable LEDs — animated effects, a friendly web UI, and a large community.[2](#user-content-fn-wled) It is built for WS2812-style addressable strips and panels, not HUB75 (a newer, secondary path for WLED), and its text rendering works by pushing strings in rather than fetching and updating data feeds on its own. Pick WLED for ambient lighting and effects; pick led-ticker for a data-driven info sign that manages its own content. ### Tidbyt / tronbyt [Section titled “Tidbyt / tronbyt”](#tidbyt--tronbyt) Tidbyt is a polished small 64×32 appliance with an app-store model (Pixlet apps); tronbyt is the open, self-hosted way to keep one running cloud-free.[3](#user-content-fn-tidbyt) Both are a great fit for a tiny finished desk gadget. Tidbyt’s future is uncertain and the device depends on a cloud backend; tronbyt requires running its own server. If you want a large, custom, fully self-contained sign that fetches its own feeds without a separate backend, led-ticker is the better fit. ### AWTRIX3 [Section titled “AWTRIX3”](#awtrix3) AWTRIX3 turns a \~$50 Ulanzi TC001 (ESP32, 32×8 pixel matrix) into a capable clock and notifier with Home Assistant / MQTT-native integration.[4](#user-content-fn-awtrix) The device itself holds no logic — dynamic content is pushed to it from Home Assistant, MQTT, or a home server. Pick it for a cheap smart-home glance display; pick led-ticker for a large standalone sign that fetches and rotates its own content with no external backend. ## Where led-ticker fits [Section titled “Where led-ticker fits”](#where-led-ticker-fits) led-ticker’s sweet spot is large, bright, multi-panel HUB75 signs that drive their own news, weather, crypto, sports, and calendar feeds from a TOML config — fully open, self-hosted, no cloud, no smart-home backend, no subscription. If that matches what you’re building, start with [Getting started](/getting-started/) or jump straight to [building your own sign](/hardware/building-your-own/). One capability that sets led-ticker apart is **inline [value tokens](/concepts/value-tokens/)**: drop a `:weather.nyc:` or `:clock.now:` token into any widget’s text and it resolves to a live, self-updating value — so a single scrolling message can read `NYC: 72°F Sunny · 9:01 AM`, each piece refreshing on its own. Live data isn’t confined to dedicated widgets; it composes into ordinary text anywhere on the sign. ## Common questions [Section titled “Common questions”](#common-questions) ### Does led-ticker run on a Raspberry Pi 5? [Section titled “Does led-ticker run on a Raspberry Pi 5?”](#does-led-ticker-run-on-a-raspberry-pi-5) Yes — and on the Pi 4. One build runs on both: the underlying `rpi-rgb-led-matrix` driver detects the board at runtime and selects the matching GPIO backend (BCM2711 on the Pi 4, RP1 on the Pi 5). The [hardware pages](/hardware/building-your-own/) cover the small per-board tuning each one wants. ### Do I need to know Python to use it? [Section titled “Do I need to know Python to use it?”](#do-i-need-to-know-python-to-use-it) No. You describe what the sign shows in a [TOML](/reference/config-options/) config file — sections, widgets, transitions — and no code runs that you wrote. Python only enters the picture if you want to [write a plugin](/plugins/authoring/01-scaffold/) to add a new widget or live-data source. ### Can I try it without buying any hardware? [Section titled “Can I try it without buying any hardware?”](#can-i-try-it-without-buying-any-hardware) Yes. The same engine runs against a software stub and renders a config to a GIF on your laptop, so you can build and preview a whole sign before buying a single panel. The [Getting started](/getting-started/) page walks through the no-hardware path. ### Can led-ticker replace a Tidbyt? [Section titled “Can led-ticker replace a Tidbyt?”](#can-led-ticker-replace-a-tidbyt) It depends on the sign you want. For a small, finished desk appliance with an app-store experience, a [Tidbyt](https://tidbyt.com/) — or [tronbyt](https://github.com/tronbyt/server) to self-host one cloud-free — is the better buy. led-ticker is the better fit when you want a large, custom, multi-panel sign that fetches and rotates its own feeds with no separate backend or subscription. ### How much does it cost to build a sign? [Section titled “How much does it cost to build a sign?”](#how-much-does-it-cost-to-build-a-sign) A reference build lands in the low hundreds of dollars, mostly the HUB75 panels and the Raspberry Pi driving them. The [hardware pages](/hardware/building-your-own/) list the exact parts for the small (160×16) and big (256×64) reference builds so you can price your own before committing. *** *Comparisons reflect the landscape as of mid-2026.* See also * [getting-started](/getting-started/) * [hardware/building-your-own](/hardware/building-your-own/) * [plugins/available](/plugins/available/) ## Footnotes [Section titled “Footnotes”](#footnote-label) 1. [hzeller/rpi-rgb-led-matrix](https://github.com/hzeller/rpi-rgb-led-matrix) [↩](#user-content-fnref-hzeller) 2. [WLED](https://github.com/WLED/WLED) · [WLED HUB75 notes](https://kno.wled.ge/advanced/HUB75/) [↩](#user-content-fnref-wled) 3. [Tidbyt joining Modal](https://modal.com/blog/tidbyt-is-joining-modal) · [tronbyt/server](https://github.com/tronbyt/server) [↩](#user-content-fnref-tidbyt) 4. [Blueforcer/awtrix3](https://github.com/Blueforcer/awtrix3) · [ESP32-HUB75-MatrixPanel-DMA](https://github.com/mrcodetastic/ESP32-HUB75-MatrixPanel-DMA) [↩](#user-content-fnref-awtrix) # Widgets > Every built-in led-ticker widget for a Raspberry Pi LED matrix sign — scrolling messages, countdowns, images, GIFs, and two-row layouts, configured in TOML. led-ticker ships **6 built-in widget types**. Each is configured by a `[[playlist.section.widget]]` block in your TOML. This page is the menu — pick the one that fits your data, then read its page for the full options list. ## By data source [Section titled “By data source”](#by-data-source) | Widget | Source | Use when | | ----------------------------------------------------------- | --------------------------- | ------------------------------------------ | | [`message`](/widgets/message/) | static text | most lines on most signs | | [`clock`](/widgets/clock/) | local clock | current time (12h/24h, optional date/tz) | | [`countdown`](/widgets/countdown/) | local clock + a target date | ”X days until …” | | [`two_row`](/widgets/two_row/) | two static lines | held-handle + scrolling promo (storefront) | | [`gif`](/widgets/gif/) | local file | animated gifs / webp / multi-frame images | | [`image`](/widgets/image/) | static PNG / JPG | logos / single still graphics | | [`pool`](/widgets/pool/) *(plugin)* | pool\_monitor InfluxDB | water temp (today / 7-day / season) | | [`baseball.scores`](/widgets/mlb/) *(plugin)* | MLB free API | game scores / series state | | [`baseball.standings`](/widgets/mlb_standings/) *(plugin)* | MLB free API | standings (top N + tracked teams) | | [`crypto.coingecko`](/widgets/crypto-coingecko/) *(plugin)* | CoinGecko | multi-coin price ticker | | [`calendar.events`](/widgets/calendar/) *(plugin)* | iCal / .ics URL | upcoming events, agenda / next / two\_row | | [`rss.feed`](/widgets/rss_feed/) *(plugin)* | any RSS URL | news / blog headlines | | [`weather.current`](/widgets/weather/) *(plugin)* | WeatherAPI.com | forecast / current conditions | ## By complexity [Section titled “By complexity”](#by-complexity) * **Just text:** `message`, `countdown`, `clock`. No external dependencies. * **Two text rows (storefront layout):** `two_row` at section `scale=2`. * **Live data (background fetch):** all plugin widgets — `pool`, `baseball.scores`, `baseball.standings`, `crypto.coingecko`, `calendar.events`, `rss.feed`, and `weather.current`. Each has retry + exponential backoff. * **Visual:** `gif`, `image`. Both support text overlay, fit modes (pillarbox / letterbox / stretch / crop), and per-row two-row layouts. ## Common knobs [Section titled “Common knobs”](#common-knobs) Most widgets share these — see the [message widget](/widgets/message/) for the canonical surface: * `font`, `font_size`, `font_threshold` — see [Fonts](/concepts/fonts/) * `font_color` — see [Color providers](/concepts/color-providers/) * `bg_color` — RGB list, painted across the panel before content; see [Section backgrounds](/concepts/sections-and-modes/#section-backgrounds-with-bg_color) * `border` — a ring around the panel: rainbow chase, color cycle, constant, color bands, or lightbulb marquee ([Borders](/concepts/borders/)) * `animation` — typewriter (where supported) See also * [widgets/message](/widgets/message/) * [widgets/gif](/widgets/gif/) * [transitions/index](/transitions/index/) # calendar widget > The calendar (.ics) widget is provided by the calendar package in led-ticker-plugins (type = "calendar.events"). The **calendar** widget is provided by the **[calendar](https://github.com/JamesAwesome/led-ticker-plugins/tree/main/plugins/calendar)** package in the led-ticker-plugins monorepo, referenced in config as `type = "calendar.events"`. It pulls upcoming events from any subscribed iCal (`.ics`) feed and shows them as a rotating **agenda**, a live **next**-event countdown, or a held-top **two\_row** card. * **To add it to your sign:** add `led-ticker-calendar` to `config/requirements-plugins.txt` and restart (`docker compose restart`) — see [Plugins](/plugins/) for the full flow. * **Full documentation** — options, the `agenda` / `next` / `two_row` layouts, keyword filter/highlight, and colors — lives in the [calendar package README](https://github.com/JamesAwesome/led-ticker-plugins/blob/main/plugins/calendar/README.md). See the [plugin system](/plugins/) for how plugin widgets work. # clock widget > Current time display — 12h/24h presets or a custom strftime format, with optional timezone and border effects. The `clock` widget displays the current time. Every draw tick the engine calls `draw()` again, so the display stays current at the 50 ms cadence of the held-widget loop — no special mechanism needed. It reuses the same text-render surface as `message` and `countdown`, so [`font_color`](/concepts/color-providers/), [`border`](/concepts/borders/), and font knobs all work exactly the same way.  clock with format = "%H:%M:%S" and font\_color = "rainbow" — the seconds advance because the time is recomputed each draw Minimal example ```toml [[playlist.section.widget]] type = "clock" ``` ## Options [Section titled “Options”](#options) | Option | Type | Default | Description | | ------------ | ------------------------------------------------------------------------------------- | ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `format` | `"12h"` \| `"24h"` \| strftime template | `"12h"` | Time display format. The presets produce locale-independent output built from datetime fields (not strftime), so they render identically on every platform. A string containing `%` is passed to `strftime` verbatim — e.g. `"%H:%M"` or `"%a %b %d %H:%M"` for an inline date. Note: `%-` codes (no-zero-pad) are a Linux-ism and will not work on macOS or Windows. | | `timezone` | IANA name \| none | system local | Timezone override, e.g. `"America/New_York"`. Uses stdlib `zoneinfo` — no extra dependencies. Defaults to the system local timezone. | | `font` | string | `"6x12"` | BDF font name (e.g., `"5x8"`, `"6x12"`) or hires font (e.g., `"Inter-Bold"`). | | `font_size` | int | (BDF cell height) | Real-pixel font size for hires fonts. Required if `font` is a hires font name. | | `font_color` | RGB list / string / table | `[255, 255, 255]` | Constant `[r,g,b]`, `"rainbow"`, `"color_cycle"`, `"random"`, or `{style="gradient", from=[...], to=[...]}`. | | `bg_color` | RGB list | none | Background fill color. Painted across the full panel before text. | | `border` | `"rainbow"` \| `"color_cycle"` \| `"lightbulbs"` \| `[r,g,b]` \| `{style="...", ...}` | none | Perimeter border ring — five styles (rainbow chase, color cycle, constant, bands, lightbulbs); see [/concepts/borders/](/concepts/borders/). | | `center` | bool | `true` | Center the time string horizontally. Set to `false` to left-align. | | `padding` | int | `6` | Horizontal padding (logical pixels) added at the end when the widget scrolls. | ## The `format` knob [Section titled “The format knob”](#the-format-knob) ### Presets [Section titled “Presets”](#presets) `"12h"` and `"24h"` are the built-in presets. * `"12h"` — `3:09 PM` (no leading zero on the hour; `AM`/`PM` suffix) * `"24h"` — `15:09` (zero-padded hour) The presets build the string directly from `datetime` fields rather than via `strftime`, so the output is identical on every platform. ### Custom strftime format [Section titled “Custom strftime format”](#custom-strftime-format) Any string containing `%` is passed to Python’s `datetime.strftime()` verbatim. ```toml [[playlist.section.widget]] type = "clock" format = "%H:%M:%S" # 24-hour with seconds ``` You can include the date inline in the same format string: ```toml [[playlist.section.widget]] type = "clock" format = "%a %b %d %H:%M" # e.g. "Sat Jun 13 15:09" ``` Caution `%-` codes (no-zero-pad, e.g. `%-I` for hour without a leading zero) are a Linux libc extension. Python passes them through to the OS, so they work on the Raspberry Pi but will fail on macOS or Windows. If you author configs on a Mac and deploy to the Pi, test `%-` codes on the Pi directly. ## Timezone [Section titled “Timezone”](#timezone) By default the clock shows the system local time. Set `timezone` to any [IANA timezone name](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) to override it: ```toml [[playlist.section.widget]] type = "clock" timezone = "America/New_York" format = "12h" ``` The timezone is resolved via Python’s stdlib `zoneinfo` module — no extra dependencies. An invalid timezone name produces a clear validation error at config load. ## Common patterns [Section titled “Common patterns”](#common-patterns) ### 12-hour clock with a rainbow border [Section titled “12-hour clock with a rainbow border”](#12-hour-clock-with-a-rainbow-border) ```toml [[playlist.section.widget]] type = "clock" format = "12h" font_color = [255, 255, 255] border = "rainbow" ``` ### 24-hour clock with a color cycle [Section titled “24-hour clock with a color cycle”](#24-hour-clock-with-a-color-cycle) ```toml [[playlist.section.widget]] type = "clock" format = "24h" font_color = "color_cycle" ``` ### Inline date and time [Section titled “Inline date and time”](#inline-date-and-time) ```toml [[playlist.section.widget]] type = "clock" format = "%a %b %d %H:%M" ``` This renders a single line like `Sat Jun 13 15:09`. Stacked date-over-time (two rows) is a planned future addition. ### Show the timezone abbreviation [Section titled “Show the timezone abbreviation”](#show-the-timezone-abbreviation) Add `%Z` to a custom format to print the timezone abbreviation (`EDT`, `JST`, …) next to the time:  timezone = "America/New\_York", format = "%H:%M %Z" ```toml [[playlist.section.widget]] type = "clock" timezone = "America/New_York" format = "%H:%M %Z" ``` Caution `%Z` and `%z` are only populated when you set `timezone` explicitly. The default system-local clock uses a *naive* timestamp with no timezone info, so `%Z`/`%z` render blank — set `timezone` to label the time with its zone. ### Show the UTC offset [Section titled “Show the UTC offset”](#show-the-utc-offset) `%z` prints the numeric offset (`+0900`, `-0400`) instead of the abbreviation:  timezone = "Asia/Tokyo", format = "%H:%M %z" ```toml [[playlist.section.widget]] type = "clock" timezone = "Asia/Tokyo" format = "%H:%M %z" ``` To pair the zone label with a 12-hour time, combine the codes: `format = "%I:%M %p %Z"` renders `05:48 PM EDT`. ### World clock — one section per city [Section titled “World clock — one section per city”](#world-clock--one-section-per-city) Give each timezone its own `slideshow` section to rotate through several cities, each labelled with `%Z`: ```toml [[playlist.section]] mode = "slideshow" hold_time = 5 [[playlist.section.widget]] type = "clock" timezone = "America/New_York" format = "NYC %H:%M %Z" [[playlist.section]] mode = "slideshow" hold_time = 5 [[playlist.section.widget]] type = "clock" timezone = "Asia/Tokyo" format = "TYO %H:%M %Z" ``` ## Slideshow mode [Section titled “Slideshow mode”](#slideshow-mode) The clock widget is designed for `slideshow`-mode sections, where the engine holds each widget for `hold_time` seconds and redraws every tick. In a `scroll` or `ticker` section the widget will scroll across the panel like any other text widget — which may not be what you want for a clock. Recommended: slideshow section for a clock ```toml [playlist.section] mode = "slideshow" hold_time = 30 [[playlist.section.widget]] type = "clock" format = "12h" ``` ## Validation [Section titled “Validation”](#validation) `led-ticker validate` catches common mistakes before the display starts: * Unknown preset (`format = "12hr"`) → `clock: format '12hr' is not a known preset ('12h'/'24h') or a strftime template (no '%')` * Invalid timezone (`timezone = "Mars/Phobos"`) → `clock: timezone 'Mars/Phobos' is not a valid IANA timezone name` See also * [widgets/countdown](/widgets/countdown/) * [widgets/message](/widgets/message/) * [concepts/color-providers](/concepts/color-providers/) * [concepts/borders](/concepts/borders/) # countdown widget > Days until a target date — message with date arithmetic baked in. The `countdown` widget is a `message` with date arithmetic baked in. Every draw it renders `: ` where N is the number of days from today to `countdown_date`. The count is recomputed on each draw, so it rolls to the next value at midnight without restarting the process. Once `countdown_date` has passed, the widget drops out of the rotation. To count up from a past date instead, see [countup](/widgets/countup/).  countdown to 2026-06-21 with rainbow font Minimal example ```toml [[playlist.section.widget]] type = "countdown" text = "Until Summer" countdown_date = 2026-06-21 ``` ## Options [Section titled “Options”](#options) | Option | Type | Default | Description | | ---------------- | ------------------------------------------------------------------------------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `text` | string | required | Label shown before the day count, e.g. `"Until Summer"` renders as `"Until Summer: 42"`. | | `countdown_date` | date | required | Target date in TOML date syntax: `2026-12-25`. The day count is recomputed on every draw so the value updates at midnight without restarting the process. | | `font` | string | `"6x12"` | BDF font name (e.g., `"5x8"`, `"6x12"`) or hires font (e.g., `"Inter-Bold"`). | | `font_size` | int | (BDF cell height) | Real-pixel font size for hires fonts. Required if `font` is a hires font name. | | `font_threshold` | int 0–255 | `128` | Rasterization threshold for hires fonts. Lower = thicker glyphs. | | `font_color` | RGB list / string / table | `[255, 255, 0]` | Constant `[r,g,b]`, `"rainbow"`, `"color_cycle"`, `"random"`, or `{style="gradient", from=[...], to=[...]}`. | | `bg_color` | RGB list | none | Background fill color. Painted across the full panel before text. | | `border` | `"rainbow"` \| `"color_cycle"` \| `"lightbulbs"` \| `[r,g,b]` \| `{style="...", ...}` | none | Perimeter border ring — five styles (rainbow chase, color cycle, constant, bands, lightbulbs); see [/concepts/borders/](/concepts/borders/). | | `padding` | int | `6` | Horizontal padding (logical pixels) added when text scrolls. | | `timezone` | IANA name \| none | system local | Timezone for computing the day count and the show/hide boundary, e.g. `"America/New_York"`. Uses stdlib `zoneinfo` — no extra dependencies. Defaults to the sign's local date. | Set the content string with `text =`. ## Common patterns [Section titled “Common patterns”](#common-patterns) ### Branded color [Section titled “Branded color”](#branded-color)  constant \`font\_color\` paints the count and label in the same RGB ```toml [[playlist.section.widget]] type = "countdown" text = "Until the Show" countdown_date = 2026-09-01 font_color = [255, 140, 0] ``` ### Rainbow sweep [Section titled “Rainbow sweep”](#rainbow-sweep)  rainbow per-character sweep across the full text + count ```toml [[playlist.section.widget]] type = "countdown" text = "Days Left" countdown_date = 2026-12-31 font_color = "rainbow" ``` ### Rainbow border with solid text [Section titled “Rainbow border with solid text”](#rainbow-border-with-solid-text)  animated rainbow chase around the panel perimeter, white text inside ```toml [[playlist.section.widget]] type = "countdown" text = "Until Launch" countdown_date = 2026-11-15 font_color = [255, 255, 255] border = "rainbow" ``` ## Tips [Section titled “Tips”](#tips) ### Typewriter is not available on `countdown` [Section titled “Typewriter is not available on countdown”](#typewriter-is-not-available-on-countdown) `animation = "typewriter"` is rejected on `countdown` — it’s only supported on `message`, `gif`, and `image`. For dynamic color, use [`font_color = "rainbow"`](/concepts/color-providers/) or a gradient. See also * [widgets/countup](/widgets/countup/) * [widgets/message](/widgets/message/) * [widgets/two\_row](/widgets/two_row/) * [concepts/color-providers](/concepts/color-providers/) # countup widget > Days since a past date — message with date arithmetic baked in. The `countup` widget is a `message` with date arithmetic baked in. Every draw it renders `: ` where N is the number of days from `countup_date` to today. The count is recomputed on each draw, so it rolls to the next value at midnight without restarting the process. Minimal example ```toml [[playlist.section.widget]] type = "countup" text = "Days since launch" countup_date = 2024-01-01 ``` ## Before the date arrives [Section titled “Before the date arrives”](#before-the-date-arrives) If `countup_date` is still in the future, the widget does not display and a warning is emitted at config load, along the lines of: ```plaintext countup_date 2027-01-01 is in the future — this countup won't display until then (did you mean a countdown?) ``` Once the date arrives the widget shows `0` and counts up from there. To count *down* to a future date, see [countdown](/widgets/countdown/). ## Options [Section titled “Options”](#options) | Option | Type | Default | Description | | ---------------- | ------------------------------------------------------------------------------------- | ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `text` | string | required | Label shown before the day count, e.g. `"Days since launch"` renders as `"Days since launch: 42"`. | | `countup_date` | date | required | Start date in TOML date syntax: `2024-01-01`. The day count is recomputed on every draw so the value updates at midnight without restarting the process. Widget does not display until this date arrives. | | `font` | string | `"6x12"` | BDF font name (e.g., `"5x8"`, `"6x12"`) or hires font (e.g., `"Inter-Bold"`). | | `font_size` | int | (BDF cell height) | Real-pixel font size for hires fonts. Required if `font` is a hires font name. | | `font_threshold` | int 0–255 | `128` | Rasterization threshold for hires fonts. Lower = thicker glyphs. | | `font_color` | RGB list / string / table | `[255, 255, 0]` | Constant `[r,g,b]`, `"rainbow"`, `"color_cycle"`, `"random"`, or `{style="gradient", from=[...], to=[...]}`. | | `bg_color` | RGB list | none | Background fill color. Painted across the full panel before text. | | `border` | `"rainbow"` \| `"color_cycle"` \| `"lightbulbs"` \| `[r,g,b]` \| `{style="...", ...}` | none | Perimeter border ring — five styles (rainbow chase, color cycle, constant, bands, lightbulbs); see [/concepts/borders/](/concepts/borders/). | | `padding` | int | `6` | Horizontal padding (logical pixels) added when text scrolls. | | `timezone` | IANA name \| none | system local | Timezone for computing the day count and the show/hide boundary, e.g. `"America/New_York"`. Uses stdlib `zoneinfo` — no extra dependencies. Defaults to the sign's local date. | Set the content string with `text =`. ## Common patterns [Section titled “Common patterns”](#common-patterns) ### Branded color [Section titled “Branded color”](#branded-color) ```toml [[playlist.section.widget]] type = "countup" text = "Days Open" countup_date = 2024-03-15 font_color = [255, 140, 0] ``` ### Rainbow sweep [Section titled “Rainbow sweep”](#rainbow-sweep) ```toml [[playlist.section.widget]] type = "countup" text = "Days Strong" countup_date = 2023-01-01 font_color = "rainbow" ``` ### Rainbow border with solid text [Section titled “Rainbow border with solid text”](#rainbow-border-with-solid-text) ```toml [[playlist.section.widget]] type = "countup" text = "Days Running" countup_date = 2023-06-01 font_color = [255, 255, 255] border = "rainbow" ``` For full details on `font_color`, `border`, `center`, `padding`, and `bg_color`, see the [color providers](/concepts/color-providers/) and [borders](/concepts/borders/) concept pages — the knobs work identically to `countdown`. ## Tips [Section titled “Tips”](#tips) ### Typewriter is not available on `countup` [Section titled “Typewriter is not available on countup”](#typewriter-is-not-available-on-countup) `animation = "typewriter"` is rejected on `countup` — it’s only supported on `message`, `gif`, and `image`. For dynamic color, use [`font_color = "rainbow"`](/concepts/color-providers/) or a gradient. See also * [widgets/countdown](/widgets/countdown/) * [widgets/message](/widgets/message/) * [concepts/color-providers](/concepts/color-providers/) # crypto.coingecko widget > The crypto.coingecko multi-coin price ticker is provided by the crypto package in led-ticker-plugins (type = "crypto.coingecko"). The **crypto.coingecko** widget is provided by the **[crypto](https://github.com/JamesAwesome/led-ticker-plugins/tree/main/plugins/crypto)** package in the led-ticker-plugins monorepo, referenced in config as `type = "crypto.coingecko"`.  crypto.coingecko cycling BTC, ETH, and SHIB — the sub-cent SHIB price shows the adaptive formatting. * **To add it to your sign:** add `led-ticker-crypto` to `config/requirements-plugins.txt` and restart (`docker compose restart`) — see [Plugins](/plugins/) for the full flow. * **Full documentation** — options, config examples, and a demo gif — lives in the [crypto package README](https://github.com/JamesAwesome/led-ticker-plugins/blob/main/plugins/crypto/README.md). ## Features [Section titled “Features”](#features) * **Multi-coin cycling** — displays one ticker card per configured coin, rotating through the list. * **Three coin-spec styles** — use a single `symbol` + `symbol_id` pair, a `symbol_ids = [...]` list, or a `symbols = [...]` list that auto-resolves each symbol to a unique CoinGecko ID. If a symbol matches more than one coin, the widget raises an error at startup; set `symbol_id` or `symbol_ids` to disambiguate. * **Optional demo API key** — the keyless free tier is rate-limited to \~5 requests/min. Add `api_key = "..."` in config or set the `COINGECKO_API_KEY` environment variable to use a [CoinGecko demo key](https://www.coingecko.com/en/api/pricing) for a higher rate limit. * **Adaptive sub-cent formatting** — prices below $0.01 display with enough decimal places to show a meaningful value rather than rounding to zero. Full options, config examples, and a demo gif live in the [crypto package README](https://github.com/JamesAwesome/led-ticker-plugins/blob/main/plugins/crypto/README.md). # gif widget > Plays animated gifs/webp at native panel resolution, with optional text overlay. The `gif` widget plays animated images at native panel resolution — each LED maps to one pixel in the source, not a scaled block. Format-agnostic: anything Pillow opens with `n_frames` and `seek()` works (`.gif`, animated `.webp`, `.apng`, multi-frame `.tiff`). Per-frame durations come from the file’s own metadata. Set `text` and it appears on the panel alongside the animation. When the text is longer than the canvas, set `text_align = "scroll"` or `"scroll_over"` for a marquee. For two-row layouts (held top + scrolling bottom), set `bottom_text` to switch modes.  Phoenix gif with scroll\_over text overlay Minimal example ```toml [[playlist.section.widget]] type = "gif" path = "config/assets/my_animation.gif" ``` ## Options [Section titled “Options”](#options) ## Image source | Option | Type | Default | Description | | ------------- | ------ | ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `path` | string | required | Path to source file. Relative paths resolve against the config.toml directory. Any Pillow-supported animated format works: `.gif`, animated `.webp`, `.apng`, multi-frame `.tiff`. | | `fit` | string | `"pillarbox"` | How the image fills the panel: `"pillarbox"` (scale by height, black bands on sides), `"letterbox"` (scale by width, black bands top/bottom), `"stretch"` (fill panel, distorts aspect ratio), `"crop"` (scale to cover, center-crop excess). | | `image_align` | string | `"center"` | Horizontal anchor for `pillarbox`: `"left"`, `"center"`, or `"right"`. Ignored by the other three fit modes (they always fill panel width). | ## Single-row text overlay | Option | Type | Default | Description | | ---------------------- | ------------------------- | --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `text` | string | `""` | Optional text rendered alongside the gif. Inline `:slug:` emoji are rendered as pixel art. Leave empty for a silent gif with no text. | | `text_align` | string | `"auto"` | Where text appears: `"auto"` picks the side opposite `image_align` so they don't overlap; `"left"` / `"right"` place text statically; `"scroll"` scrolls text behind a transparent image silhouette; `"scroll_over"` scrolls text in front of the image. | | `text_valign` | string | `"center"` | Vertical text anchor: `"top"`, `"center"`, or `"bottom"`. | | `text_y_offset` | int | `0` | Logical-pixel shift on top of the `text_valign` baseline. Negative = up, positive = down. | | `text_x_offset` | int | `0` | Horizontal nudge for static text (`text_align = "left"` or `"right"`). Positive = right, negative = left. Rejected when used with scroll modes. | | `scroll_direction` | string | `"left"` | Direction the marquee travels: `"left"` or `"right"`. Only applies when `text_align` is `"scroll"` or `"scroll_over"`. | | `scroll_speed_ms` | int | `50` | Tick cadence in milliseconds when text scrolls. Minimum 20. | | `font` | string | `"6x12"` | BDF font alias (e.g. `"5x8"`, `"6x12"`) or hires font name (e.g. `"Inter-Regular"`). Default is the 6×12 BDF. | | `font_size` | int | none | Real-pixel font size. For BDF: snaps down to the nearest integer multiple of cell height, defaults to `cell_h × section_scale` (12 on the small sign, 48 on bigsign at scale=4). For hires fonts: required — raises at config-load without a hint if unset. | | `font_threshold` | int 0–255 | `128` | Rasterization threshold for hires fonts. Lower = thicker glyphs; useful for thin-stroked fonts like Beloved Sans Regular at \~80. BDF fonts ignore this. | | `font_color` | RGB list / string / table | `[255, 255, 0]` | Text color. Constant `[r,g,b]`, `"rainbow"`, `"color_cycle"`, `"random"`, or `{style="gradient", from=[...], to=[...]}`. | | `text_loops` | int | `0` | Minimum number of full marquee traversals before the section transitions. Only meaningful with `text_align = "scroll"` or `"scroll_over"`. `0` = no floor (one traversal is always guaranteed). In wrap mode (`text_wrap = true`), counts complete cycle traversals (one cycle = text + separator) instead. | | `text_wrap` | bool | `false` | Seamless wrap mode for the marquee. When `true`, the text repeats with a separator between copies and at least one full copy is on the panel at every tick. Requires `text_align` to be `"scroll"` or `"scroll_over"`; rejected in two-row mode. | | `text_separator` | string | `" • "` (when `text_wrap = true`) | Glyph(s) drawn between repeats in wrap mode. `""` falls back to a two-space gap. Rendered in the widget's `font` — per-separator font override isn't supported in v1. | | `text_separator_color` | color spec | inherit `font_color` | Color for the separator in wrap mode. Whole-string provider (one hue per frame); accepts the same value types as `font_color`. | ## Two-row text overlay Setting `bottom_text` to a non-empty string switches the widget to **two-row mode**: the image plays underneath, a held top row sits at the chosen alignment, and the bottom row scrolls when its text overflows the canvas width. Single-row `text_align`, `text_valign`, `text_x_offset`, and `font_size` are rejected in this mode — use the per-row knobs below. | Option | Type | Default | Description | | ----------------------------- | ------------------------- | ---------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `bottom_text` | string | `""` | Setting this non-empty activates two-row mode. Text for the scrolling bottom row; auto-scrolls left when it overflows. | | `top_text` | string | `""` | Text for the held top row. Falls back to `text` when unset (back-compat alias — set one or the other, not both). | | `top_color` | RGB list / string / table | (same as `font_color`) | Top-row text color. Same value types as `font_color`. Defaults to `font_color` when unset. | | `bottom_color` | RGB list / string / table | (same as `font_color`) | Bottom-row text color. Defaults to `font_color` when unset. | | `top_align` | string | `"center"` | Top-row horizontal alignment when text fits: `"left"`, `"center"`, or `"right"`. | | `bottom_align` | string | `"center"` | Bottom-row alignment when text fits without scrolling. Ignored when the bottom row overflows. | | `top_font` | string | (same as `font`) | Per-row font override for the top row. Falls back to `font` when unset. | | `top_font_size` | int | (BDF cell height) | Real-pixel font size for hires `top_font`. Required when `top_font` is a hires font name. | | `top_font_threshold` | int 0–255 | `128` | Rasterization threshold for hires `top_font`. | | `bottom_font` | string | (same as `font`) | Per-row font override for the bottom row. Falls back to `font` when unset. | | `bottom_font_size` | int | (BDF cell height) | Real-pixel font size for hires `bottom_font`. Required when `bottom_font` is a hires font name. | | `bottom_font_threshold` | int 0–255 | `128` | Rasterization threshold for hires `bottom_font`. | | `top_text_y_offset` | int | `0` | Vertical nudge for the top row's text in logical rows. Negative = up. | | `bottom_text_y_offset` | int | `0` | Vertical nudge for the bottom row's text in logical rows. | | `top_emoji_y_offset` | int | `0` | Vertical nudge for the top row's emoji in logical rows. Set equal to `top_text_y_offset` to shift the whole row together. | | `bottom_emoji_y_offset` | int | `0` | Vertical nudge for the bottom row's emoji in logical rows. | | `top_row_height` | int | none | Give the top band exactly N logical rows; the bottom gets the remainder. Default `None` splits 50/50. Use when the top and bottom rows need different font sizes. Must be `> 0` and `< canvas.height`. | | `bottom_text_wrap` | bool | `false` | Seamless wrap mode for the bottom row in two-row mode. When `true`, the bottom row repeats with a separator between copies and at least one full copy is on the panel at every tick. Requires `bottom_text` non-empty; top row never wraps. Only allowed in `mode = "slideshow"`. | | `bottom_text_separator` | string | `" • "` (when `bottom_text_wrap = true`) | Glyph(s) drawn between bottom-row repeats in wrap mode. `""` falls back to a two-space gap. Rendered in the bottom row's font. | | `bottom_text_separator_color` | color spec | inherit `bottom_color` | Color for the bottom separator in wrap mode. Whole-string provider (one hue per frame); accepts the same value types as `bottom_color`. Inherits `bottom_color` (NOT `font_color`) — separator is part of the bottom row. | | `text_loops` | int | `0` | Minimum number of full bottom-row wrap cycles before the section transitions in two-row mode (same field as single-row mode, reinterpreted as bottom-row cycle count when `bottom_text_wrap = true`). On the [`two_row`](/widgets/two_row/) widget the equivalent is `bottom_text_loops`. | ## GIF playback | Option | Type | Default | Description | | ------------ | ---- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `play_count` | int | `1` | Number of times the gif plays per visit. Set to `0` to play through the section's `hold_time` (the recommended idiom for "show this gif for the section's duration"). Negative values are rejected. `play_count >= 1` plays the exact count regardless of `hold_time`. | ## Animation | Option | Type | Default | Description | | ----------- | ------ | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `animation` | string | none | `"typewriter"` for character-by-character text reveal. Single-row only — raises if `bottom_text` is set or `text_align` is `"scroll"` / `"scroll_over"`. See rule 14. | ## Border and background | Option | Type | Default | Description | | ---------- | ------------------------------------------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `border` | `"rainbow"` \| `"color_cycle"` \| `"lightbulbs"` \| `[r,g,b]` \| `{style="...", ...}` | none | Perimeter border ring — five styles (rainbow chase, color cycle, constant, bands, lightbulbs); see [/concepts/borders/](/concepts/borders/). Paints at physical panel resolution (bypasses ScaledCanvas), so the border traces the real panel edge. Paints after the image and before text. | | `bg_color` | RGB list | none | Background fill for the full canvas before image and text. When set, pillarbox bands and alpha-transparent regions reveal this color instead of black. Use with a transparent-background gif to blend the silhouette against a solid color. | ## Common patterns [Section titled “Common patterns”](#common-patterns) ### Silent gif (no text) [Section titled “Silent gif (no text)”](#silent-gif-no-text)  phoenix centered with \`pillarbox\` fit, three loops ```toml [[playlist.section.widget]] type = "gif" path = "config/assets/phoenix_transparent.gif" fit = "pillarbox" image_align = "center" play_count = 3 ``` ### Scrolling marquee over the image (`scroll_over` — text in front) [Section titled “Scrolling marquee over the image (scroll\_over — text in front)”](#scrolling-marquee-over-the-image-scroll_over--text-in-front)  phoenix pinned to the left, magenta text marquees over the canvas in front of the phoenix ```toml [[playlist.section.widget]] type = "gif" path = "config/assets/phoenix_transparent.gif" fit = "pillarbox" image_align = "left" text = "Welcome to the show!" text_align = "scroll_over" font_color = [225, 48, 108] play_count = 0 # play through hold_time ``` ### Scrolling text behind a transparent silhouette (`scroll` — text walks under the image) [Section titled “Scrolling text behind a transparent silhouette (scroll — text walks under the image)”](#scrolling-text-behind-a-transparent-silhouette-scroll--text-walks-under-the-image)  text scrolls under the phoenix — visible only through the transparent pillarbox area ```toml [[playlist.section.widget]] type = "gif" path = "config/assets/phoenix_transparent.gif" fit = "pillarbox" image_align = "left" text = "Scrolling behind the phoenix!" text_align = "scroll" font_color = [200, 200, 255] play_count = 5 ``` ### Wrap mode (seamless marquee with a separator between repeats) [Section titled “Wrap mode (seamless marquee with a separator between repeats)”](#wrap-mode-seamless-marquee-with-a-separator-between-repeats)  \`text\_wrap = true\` — \`BREAKING NEWS\` chases itself across the canvas with a rainbow separator between repeats. Two copies of the message are on the panel at any tick, so the banner never goes blank. Setting `text_wrap = true` on a `scroll` or `scroll_over` marquee runs the text seamlessly — at every tick at least one full copy of the message is on the panel, with a configurable separator drawn between repeats. Use this for short slogans or breaking-news banners where the gap of an empty canvas between traversals breaks the rhythm. ```toml [[playlist.section.widget]] type = "gif" path = "config/assets/phoenix_transparent.gif" text = "BREAKING NEWS" text_wrap = true text_align = "scroll_over" text_separator = " * " # default: " • " text_separator_color = "rainbow" # default: inherit font_color ``` | Field | Type | Default | Meaning | | ---------------------- | ---------- | --------------------------------- | ------------------------------------------------------------------------ | | `text_wrap` | bool | `false` | Toggle seamless wrap. Requires `text_align ∈ ("scroll", "scroll_over")`. | | `text_separator` | string | `" • "` (when `text_wrap = true`) | Glyph(s) between repeats. `""` falls back to a two-space gap. | | `text_separator_color` | color spec | inherit `font_color` | Color for the separator; whole-string provider (one hue per frame). | Notes: * `text_loops` in wrap mode means **minimum number of cycle traversals** (one cycle = text + separator), not the off-right → off-left definition the default marquee uses. On the [`two_row`](/widgets/two_row/) widget the equivalent field is `bottom_text_loops` (prefixed to match `bottom_text_wrap` and friends on that widget). * Two-row mode (`bottom_text` set) refuses `text_wrap` in v1. * The separator renders in the widget’s `font`; a per-separator font override isn’t part of v1. ### Wrap mode (bottom row, seamless marquee) [Section titled “Wrap mode (bottom row, seamless marquee)”](#wrap-mode-bottom-row-seamless-marquee)  phoenix on the left, held magenta \`BREAKING\` up top, cyan \`tap to subscribe\` wrapping continuously on the bottom with a rainbow \`\*\` separator Setting `bottom_text_wrap = true` in two-row mode (when `bottom_text` is set) runs the bottom row as a seamless marquee — chasing itself across the canvas with a separator between repeats. Top row stays held at `top_align`; only the bottom row wraps. Engages even when the bottom text fits — predictable. ```toml [[playlist.section.widget]] type = "gif" path = "config/assets/phoenix_transparent.gif" top_text = "BREAKING" top_color = [225, 48, 108] bottom_text = "tap to subscribe" bottom_text_wrap = true bottom_text_separator = " * " # default: " • " bottom_text_separator_color = "rainbow" # default: inherit bottom_color ``` | Field | Type | Default | Meaning | | ----------------------------- | ---------- | ---------------------------------------- | -------------------------------------------------------------------------- | | `bottom_text_wrap` | bool | `false` | Toggle seamless wrap on the bottom row. Requires `bottom_text` non-empty. | | `bottom_text_separator` | string | `" • "` (when `bottom_text_wrap = true`) | Glyph(s) between bottom-row repeats. `""` falls back to a two-space gap. | | `bottom_text_separator_color` | color spec | inherit `bottom_color` | Color for the bottom separator; whole-string provider (one hue per frame). | Notes: * `bottom_text_wrap` always wraps when set, even if the bottom text fits the canvas. * Top row never wraps (refused by validation; no `top_text_wrap` field exists). * The separator color inherits `bottom_color` (NOT `font_color`) — separator is part of the bottom row. * v1’s `text_wrap` stays single-row only — in two-row mode use `bottom_text_wrap`. * `bottom_text_wrap` is only allowed in `mode = "slideshow"`. In `ticker` / `one_at_a_time` modes, validation refuses it (those modes expect widgets to terminate naturally). ### Scroll-through mode (bottom row, one offscreen pass) [Section titled “Scroll-through mode (bottom row, one offscreen pass)”](#scroll-through-mode-bottom-row-one-offscreen-pass)  phoenix on the left, held magenta \`NOW PLAYING\` up top, cyan track-title scrolling fully offscreen-to-offscreen on the bottom — keeps cycling within \`hold\_time\` Setting `bottom_text_scroll = "scroll_through"` in two-row mode forces the bottom row to do an offscreen-to-offscreen scroll on every visit — text starts fully off the right edge and ends fully off the left edge — instead of the default “held when it fits, scroll only on overflow” behavior. `bottom_align` is ignored. ```toml [[playlist.section.widget]] type = "gif" path = "config/assets/phoenix_transparent.gif" top_text = "NOW PLAYING" bottom_text = "Phoenix Rising - The OST Collection (2026)" bottom_text_scroll = "scroll_through" ``` | Field | Type | Default | Meaning | | -------------------- | ------ | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `bottom_text_scroll` | string | `"marquee"` | Bottom-row scroll style. `"marquee"` preserves the held-on-fit / scroll-on-overflow default; `"scroll_through"` forces offscreen-to-offscreen passes on every visit. | Notes: * Mutually exclusive with `bottom_text_wrap = true` — pick one. Scroll-through is one pass; wrap is a seamless tile. * Requires non-empty `bottom_text` (two-row mode). Single-row text scroll lives under `text_align = "scroll"` / `"scroll_over"`. * Only valid in `mode = "slideshow"`. In `ticker` / `one_at_a_time` modes validation refuses it (rule 32). * `hold_time` is honored as a *floor*: at least one full pass per visit, or `text_loops × (canvas_width + bottom_width)` if larger, or whatever `hold_time` admits — whichever is greatest. The bottom row keeps cycling until that floor is met. * **Loop count for the bottom-row wrap:** use `text_loops` here on gif/image widgets (same field that controls single-row wrap loops). On the [`two_row`](/widgets/two_row/) widget — which is always two-row, not optionally — the equivalent field is named `bottom_text_loops` to match its bottom-prefix convention. The validator catches the cross-widget typo (rule 29) and points you at the right name. ### Two-row text overlay (set `bottom_text` to switch modes — image plays underneath) [Section titled “Two-row text overlay (set bottom\_text to switch modes — image plays underneath)”](#two-row-text-overlay-set-bottom_text-to-switch-modes--image-plays-underneath)  gif on the right, \`@firebird.demo\` on top, scrolling promo on the bottom ```toml [[playlist.section.widget]] type = "gif" path = "config/assets/phoenix_transparent.gif" fit = "pillarbox" image_align = "right" top_text = "@firebird.demo" top_font = "5x8" top_color = [225, 48, 108] bottom_text = "Vinyasa · yin · hot power · restorative · slow flow · all levels" bottom_font = "5x8" bottom_color = [255, 240, 200] play_count = 3 ``` ### Typewriter overlay (single-row only — letters type in next to the animation) [Section titled “Typewriter overlay (single-row only — letters type in next to the animation)”](#typewriter-overlay-single-row-only--letters-type-in-next-to-the-animation)  phoenix plays on the left while \`hi friend\` types in on the right with rainbow font\_color ```toml [[playlist.section.widget]] type = "gif" path = "config/assets/phoenix_transparent.gif" fit = "pillarbox" image_align = "left" text = "hi friend" text_align = "right" font_color = "rainbow" animation = "typewriter" play_count = 0 # play through hold_time ``` ### Typewriter + rainbow border (frame the panel as the text appears) [Section titled “Typewriter + rainbow border (frame the panel as the text appears)”](#typewriter--rainbow-border-frame-the-panel-as-the-text-appears)  rainbow chase border around the perimeter, white text typing in beside the phoenix ```toml [[playlist.section.widget]] type = "gif" path = "config/assets/phoenix_transparent.gif" fit = "pillarbox" image_align = "left" text = "hi friend" text_align = "right" font_color = [255, 255, 255] animation = "typewriter" border = "rainbow" play_count = 0 # play through hold_time ``` ## Tips [Section titled “Tips”](#tips) ### Playing through `hold_time`: `play_count = 0` [Section titled “Playing through hold\_time: play\_count = 0”](#playing-through-hold_time-play_count--0) When you want a gif to fill its section’s duration rather than playing a fixed number of times, set `play_count = 0`. The engine computes how many complete loops fit in `hold_time` and plays at least one even if the time budget is shorter than the gif’s own duration. ```toml [[playlist.section]] mode = "slideshow" hold_time = 8.0 [[playlist.section.widget]] type = "gif" path = "config/assets/sparkles.gif" play_count = 0 # fills the section's hold_time ``` `play_count >= 1` plays the exact count regardless of `hold_time`. ### Typewriter is single-row only [Section titled “Typewriter is single-row only”](#typewriter-is-single-row-only) `animation = "typewriter"` rejects three combinations: `bottom_text` set (two-row layout), `text_align = "scroll"` / `"scroll_over"` (cursor moves each tick), or empty `text`. Drop the conflicting setting; typewriter still composes with `font_color = "rainbow"` and `border = "rainbow"`. ### `text_align="scroll"` needs transparency [Section titled “text\_align="scroll" needs transparency”](#text_alignscroll-needs-transparency) Stretch fills every pixel with image, leaving no transparent regions for the text to scroll through. Use `text_align="scroll_over"` for a fullscreen marquee, or pair `scroll` with a transparent `.gif` and `fit="pillarbox"`. ### `text_x_offset` is rejected in scroll modes [Section titled “text\_x\_offset is rejected in scroll modes”](#text_x_offset-is-rejected-in-scroll-modes) Static offsets don’t compose with the per-tick scroll cursor. Set `text_x_offset = 0` or change `text_align` to `"left"` or `"right"`. See also * [widgets/image](/widgets/image/) * [widgets/two\_row](/widgets/two_row/) * [assets/emoji](/assets/emoji/) * [concepts/value-tokens](/concepts/value-tokens/) # image widget > Single PNG/JPG (or single-frame gif) at native panel resolution, with optional text overlay. The `image` widget displays a single still image at native physical resolution — each LED maps to one pixel in the source. Use it for logos, product photos, brand artwork, or any single-frame graphic. This widget is essentially `gif` with a single frame: it shares the `gif` widget’s full feature surface (fit modes, text overlay, two-row, animation, border) minus the per-frame mechanics — the only widget-specific knob is `hold_time` instead of `play_count`.  Phoenix png with scroll\_over text overlay Minimal example ```toml [[playlist.section.widget]] type = "image" path = "config/assets/my_logo.png" hold_time = 4.0 ``` ## Options [Section titled “Options”](#options) ## Image source | Option | Type | Default | Description | | ------------- | ------ | ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `path` | string | required | Path to source file. Relative paths resolve against the config.toml directory. Single PNG / JPG / single-frame GIF are the primary use cases. For animated files, only frame 0 is decoded — use the `gif` widget for animation. | | `fit` | string | `"pillarbox"` | How the image fills the panel: `"pillarbox"` (scale by height, black bands on sides), `"letterbox"` (scale by width, black bands top/bottom), `"stretch"` (fill panel, distorts aspect ratio), `"crop"` (scale to cover, center-crop excess). | | `image_align` | string | `"center"` | Horizontal anchor for `pillarbox`: `"left"`, `"center"`, or `"right"`. Ignored by the other three fit modes (they always fill panel width). | ## Display duration | Option | Type | Default | Description | | ----------- | ----- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `hold_time` | float | `5.0` | How long to display the image per visit. With `text_loops > 0`, becomes a duration **floor**: the section runs for `max(hold_time, text_loops × traversal)` so a long marquee always completes. Minimum `0.05`. | ## Single-row text overlay | Option | Type | Default | Description | | ---------------------- | ------------------------- | --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `text` | string | `""` | Optional text rendered alongside the image. Inline `:slug:` emoji are rendered as pixel art. Leave empty for a silent image with no text. | | `text_align` | string | `"auto"` | Where text appears: `"auto"` picks the side opposite `image_align` so they don't overlap; `"left"` / `"right"` place text statically; `"scroll"` scrolls text behind a transparent image silhouette; `"scroll_over"` scrolls text in front of the image. | | `text_valign` | string | `"center"` | Vertical text anchor: `"top"`, `"center"`, or `"bottom"`. | | `text_y_offset` | int | `0` | Logical-pixel shift on top of the `text_valign` baseline. Negative = up, positive = down. | | `text_x_offset` | int | `0` | Horizontal nudge for static text (`text_align = "left"` or `"right"`). Positive = right, negative = left. Rejected when used with scroll modes. | | `scroll_direction` | string | `"left"` | Direction the marquee travels: `"left"` or `"right"`. Only applies when `text_align` is `"scroll"` or `"scroll_over"`. | | `scroll_speed_ms` | int | `50` | Tick cadence in milliseconds when text scrolls. Minimum 20. | | `font` | string | `"6x12"` | BDF font alias (e.g. `"5x8"`, `"6x12"`) or hires font name (e.g. `"Inter-Regular"`). Default is the 6×12 BDF. | | `font_size` | int | none | Real-pixel font size. For BDF: snaps down to the nearest integer multiple of cell height, defaults to `cell_h × section_scale` (12 on the small sign, 48 on bigsign at scale=4). For hires fonts: required — raises at config-load without a hint if unset. | | `font_threshold` | int 0–255 | `128` | Rasterization threshold for hires fonts. Lower = thicker glyphs; useful for thin-stroked fonts like Beloved Sans Regular at \~80. BDF fonts ignore this. | | `font_color` | RGB list / string / table | `[255, 255, 0]` | Text color. Constant `[r,g,b]`, `"rainbow"`, `"color_cycle"`, `"random"`, or `{style="gradient", from=[...], to=[...]}`. | | `text_loops` | int | `0` | Minimum number of full marquee traversals before the section transitions. Only meaningful with `text_align = "scroll"` or `"scroll_over"`. `0` = no floor (one traversal is always guaranteed). In wrap mode (`text_wrap = true`), counts complete cycle traversals (one cycle = text + separator) instead. | | `text_wrap` | bool | `false` | Seamless wrap mode for the marquee. When `true`, the text repeats with a separator between copies and at least one full copy is on the panel at every tick. Requires `text_align` to be `"scroll"` or `"scroll_over"`; rejected in two-row mode. | | `text_separator` | string | `" • "` (when `text_wrap = true`) | Glyph(s) drawn between repeats in wrap mode. `""` falls back to a two-space gap. Rendered in the widget's `font` — per-separator font override isn't supported in v1. | | `text_separator_color` | color spec | inherit `font_color` | Color for the separator in wrap mode. Whole-string provider (one hue per frame); accepts the same value types as `font_color`. | ## Two-row text overlay Setting `bottom_text` to a non-empty string switches the widget to **two-row mode**: the image sits underneath, a held top row sits at the chosen alignment, and the bottom row scrolls when its text overflows the canvas width. Single-row `text_align`, `text_valign`, `text_x_offset`, and `font_size` are rejected in this mode — use the per-row knobs below. | Option | Type | Default | Description | | ----------------------------- | ------------------------- | ---------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `bottom_text` | string | `""` | Setting this non-empty activates two-row mode. Text for the scrolling bottom row; auto-scrolls left when it overflows. | | `top_text` | string | `""` | Text for the held top row. Falls back to `text` when unset (back-compat alias — set one or the other, not both). | | `top_color` | RGB list / string / table | (same as `font_color`) | Top-row text color. Same value types as `font_color`. Defaults to `font_color` when unset. | | `bottom_color` | RGB list / string / table | (same as `font_color`) | Bottom-row text color. Defaults to `font_color` when unset. | | `top_align` | string | `"center"` | Top-row horizontal alignment when text fits: `"left"`, `"center"`, or `"right"`. | | `bottom_align` | string | `"center"` | Bottom-row alignment when text fits without scrolling. Ignored when the bottom row overflows. | | `top_font` | string | (same as `font`) | Per-row font override for the top row. Falls back to `font` when unset. | | `top_font_size` | int | (BDF cell height) | Real-pixel font size for hires `top_font`. Required when `top_font` is a hires font name. | | `top_font_threshold` | int 0–255 | `128` | Rasterization threshold for hires `top_font`. | | `bottom_font` | string | (same as `font`) | Per-row font override for the bottom row. Falls back to `font` when unset. | | `bottom_font_size` | int | (BDF cell height) | Real-pixel font size for hires `bottom_font`. Required when `bottom_font` is a hires font name. | | `bottom_font_threshold` | int 0–255 | `128` | Rasterization threshold for hires `bottom_font`. | | `top_text_y_offset` | int | `0` | Vertical nudge for the top row's text in logical rows. Negative = up. | | `bottom_text_y_offset` | int | `0` | Vertical nudge for the bottom row's text in logical rows. | | `top_emoji_y_offset` | int | `0` | Vertical nudge for the top row's emoji in logical rows. Set equal to `top_text_y_offset` to shift the whole row together. | | `bottom_emoji_y_offset` | int | `0` | Vertical nudge for the bottom row's emoji in logical rows. | | `top_row_height` | int | none | Give the top band exactly N logical rows; the bottom gets the remainder. Default `None` splits 50/50. Use when the top and bottom rows need different font sizes. Must be `> 0` and `< canvas.height`. | | `bottom_text_wrap` | bool | `false` | Seamless wrap mode for the bottom row in two-row mode. When `true`, the bottom row repeats with a separator between copies and at least one full copy is on the panel at every tick. Requires `bottom_text` non-empty; top row never wraps. Only allowed in `mode = "slideshow"`. | | `bottom_text_separator` | string | `" • "` (when `bottom_text_wrap = true`) | Glyph(s) drawn between bottom-row repeats in wrap mode. `""` falls back to a two-space gap. Rendered in the bottom row's font. | | `bottom_text_separator_color` | color spec | inherit `bottom_color` | Color for the bottom separator in wrap mode. Whole-string provider (one hue per frame); accepts the same value types as `bottom_color`. Inherits `bottom_color` (NOT `font_color`) — separator is part of the bottom row. | | `text_loops` | int | `0` | Minimum number of full bottom-row wrap cycles before the section transitions in two-row mode (same field as single-row mode, reinterpreted as bottom-row cycle count when `bottom_text_wrap = true`). On the [`two_row`](/widgets/two_row/) widget the equivalent is `bottom_text_loops`. | ## Animation | Option | Type | Default | Description | | ----------- | ------ | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `animation` | string | none | `"typewriter"` for character-by-character text reveal. Single-row only — raises if `bottom_text` is set or `text_align` is `"scroll"` / `"scroll_over"`. See rule 14. | ## Border and background | Option | Type | Default | Description | | ---------- | ------------------------------------------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `border` | `"rainbow"` \| `"color_cycle"` \| `"lightbulbs"` \| `[r,g,b]` \| `{style="...", ...}` | none | Perimeter border ring — five styles (rainbow chase, color cycle, constant, bands, lightbulbs); see [/concepts/borders/](/concepts/borders/). Paints at physical panel resolution (bypasses ScaledCanvas), so the border traces the real panel edge. Paints after the image and before text. | | `bg_color` | RGB list | none | Background fill for the full canvas before image and text. When set, pillarbox bands and alpha-transparent regions reveal this color instead of black. Use with a transparent-background PNG to blend the silhouette against a solid color. | ## Common patterns [Section titled “Common patterns”](#common-patterns) ### Static logo (no text) [Section titled “Static logo (no text)”](#static-logo-no-text)  transparent phoenix centered with \`pillarbox\` fit ```toml [[playlist.section.widget]] type = "image" path = "config/assets/phoenix_transparent.png" fit = "pillarbox" image_align = "center" hold_time = 4.0 ``` ### Image with scrolling text overlay (`scroll_over` — text in front of the image) [Section titled “Image with scrolling text overlay (scroll\_over — text in front of the image)”](#image-with-scrolling-text-overlay-scroll_over--text-in-front-of-the-image)  phoenix pinned to the left, magenta text marquees over the right side ```toml [[playlist.section.widget]] type = "image" path = "config/assets/phoenix_transparent.png" fit = "pillarbox" image_align = "left" text = "Follow us on Instagram!" text_align = "scroll_over" hold_time = 7.0 font_color = [200, 100, 255] ``` ### Scrolling text behind a transparent silhouette (`scroll` — text walks under the image; requires a PNG with transparency) [Section titled “Scrolling text behind a transparent silhouette (scroll — text walks under the image; requires a PNG with transparency)”](#scrolling-text-behind-a-transparent-silhouette-scroll--text-walks-under-the-image-requires-a-png-with-transparency)  text scrolls under the phoenix — visible only through the transparent pillarbox area ```toml [[playlist.section.widget]] type = "image" path = "config/assets/phoenix_transparent.png" fit = "pillarbox" image_align = "left" text = "Scrolling behind the phoenix!" text_align = "scroll" font_color = [200, 200, 255] ``` ### Wrap mode (seamless marquee with a separator between repeats) [Section titled “Wrap mode (seamless marquee with a separator between repeats)”](#wrap-mode-seamless-marquee-with-a-separator-between-repeats)  \`text\_wrap = true\` — cyan \`hi friend\` repeats with a steady yellow \`•\` separator between copies. The message is always visible somewhere on the panel; the separator color is independent of \`font\_color\`. Setting `text_wrap = true` on a `scroll` or `scroll_over` marquee runs the text seamlessly — at every tick at least one full copy of the message is on the panel, with a configurable separator drawn between repeats. Use this for short slogans or repeating banners where the gap of an empty canvas between traversals breaks the rhythm. ```toml [[playlist.section.widget]] type = "image" path = "config/assets/phoenix_transparent.png" text = "hi friend" text_wrap = true text_align = "scroll_over" font_color = [120, 230, 255] # cyan text_separator_color = [255, 200, 80] # steady yellow separator # default separator: " • " # (omit text_separator to use it) ``` | Field | Type | Default | Meaning | | ---------------------- | ---------- | --------------------------------- | ------------------------------------------------------------------------ | | `text_wrap` | bool | `false` | Toggle seamless wrap. Requires `text_align ∈ ("scroll", "scroll_over")`. | | `text_separator` | string | `" • "` (when `text_wrap = true`) | Glyph(s) between repeats. `""` falls back to a two-space gap. | | `text_separator_color` | color spec | inherit `font_color` | Color for the separator; whole-string provider (one hue per frame). | Notes: * `text_loops` in wrap mode means **minimum number of cycle traversals** (one cycle = text + separator), not the off-right → off-left definition the default marquee uses. On the [`two_row`](/widgets/two_row/) widget the equivalent field is `bottom_text_loops` (prefixed to match `bottom_text_wrap` and friends on that widget). * Two-row mode (`bottom_text` set) refuses `text_wrap` in v1. * The separator renders in the widget’s `font`; a per-separator font override isn’t part of v1. ### Wrap mode (bottom row, seamless marquee) [Section titled “Wrap mode (bottom row, seamless marquee)”](#wrap-mode-bottom-row-seamless-marquee)  still phoenix on the left, held magenta \`BREAKING\` up top, cyan \`tap to subscribe\` wrapping continuously on the bottom with a rainbow \`\*\` separator Setting `bottom_text_wrap = true` in two-row mode (when `bottom_text` is set) runs the bottom row as a seamless marquee — chasing itself across the canvas with a separator between repeats. Top row stays held at `top_align`; only the bottom row wraps. Engages even when the bottom text fits — predictable. ```toml [[playlist.section.widget]] type = "image" path = "config/assets/phoenix_transparent.png" top_text = "BREAKING" top_color = [225, 48, 108] bottom_text = "tap to subscribe" bottom_text_wrap = true bottom_text_separator = " * " # default: " • " bottom_text_separator_color = "rainbow" # default: inherit bottom_color ``` | Field | Type | Default | Meaning | | ----------------------------- | ---------- | ---------------------------------------- | -------------------------------------------------------------------------- | | `bottom_text_wrap` | bool | `false` | Toggle seamless wrap on the bottom row. Requires `bottom_text` non-empty. | | `bottom_text_separator` | string | `" • "` (when `bottom_text_wrap = true`) | Glyph(s) between bottom-row repeats. `""` falls back to a two-space gap. | | `bottom_text_separator_color` | color spec | inherit `bottom_color` | Color for the bottom separator; whole-string provider (one hue per frame). | Notes: * `bottom_text_wrap` always wraps when set, even if the bottom text fits the canvas. * Top row never wraps (refused by validation; no `top_text_wrap` field exists). * The separator color inherits `bottom_color` (NOT `font_color`) — separator is part of the bottom row. * v1’s `text_wrap` stays single-row only — in two-row mode use `bottom_text_wrap`. * `bottom_text_wrap` is only allowed in `mode = "slideshow"`. In `ticker` / `one_at_a_time` modes, validation refuses it (those modes expect widgets to terminate naturally). * **Loop count for the bottom-row wrap:** use `text_loops` here on gif/image widgets (same field that controls single-row wrap loops). On the [`two_row`](/widgets/two_row/) widget — which is always two-row, not optionally — the equivalent field is named `bottom_text_loops` to match its bottom-prefix convention. The validator catches the cross-widget typo (rule 29) and points you at the right name. ### Scroll-through mode (bottom row, one offscreen pass) [Section titled “Scroll-through mode (bottom row, one offscreen pass)”](#scroll-through-mode-bottom-row-one-offscreen-pass)  phoenix on the right, held magenta \`@firebird.demo\` on top, cream promo scrolling fully offscreen-to-offscreen on the bottom — keeps cycling within \`hold\_time\` Setting `bottom_text_scroll = "scroll_through"` in two-row mode forces the bottom row to do an offscreen-to-offscreen scroll on every visit — text starts fully off the right edge and ends fully off the left edge — instead of the default “held when it fits, scroll only on overflow” behavior. `bottom_align` is ignored. ```toml [[playlist.section.widget]] type = "image" path = "config/assets/phoenix_transparent.png" fit = "pillarbox" image_align = "right" top_text = "@firebird.demo" top_color = [225, 48, 108] bottom_text = "Firebird Yoga — now booking spring sessions — your first class is free." bottom_color = [255, 240, 200] bottom_text_scroll = "scroll_through" ``` | Field | Type | Default | Meaning | | -------------------- | ------ | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `bottom_text_scroll` | string | `"marquee"` | Bottom-row scroll style. `"marquee"` preserves the held-on-fit / scroll-on-overflow default; `"scroll_through"` forces offscreen-to-offscreen passes on every visit. | Notes: * Mutually exclusive with `bottom_text_wrap = true` — pick one. Scroll-through is one pass; wrap is a seamless tile. * Requires non-empty `bottom_text` (two-row mode). Single-row text scroll lives under `text_align = "scroll"` / `"scroll_over"`. * Only valid in `mode = "slideshow"`. In `ticker` / `one_at_a_time` modes validation refuses it (rule 32). * `hold_time` is honored as a *floor*: at least one full pass per visit, or `text_loops × (canvas_width + bottom_width)` if larger, or whatever `hold_time` admits — whichever is greatest. The bottom row keeps cycling until that floor is met. ### Two-row text overlay (set `bottom_text` to switch modes — image sits underneath) [Section titled “Two-row text overlay (set bottom\_text to switch modes — image sits underneath)”](#two-row-text-overlay-set-bottom_text-to-switch-modes--image-sits-underneath)  phoenix on the right, \`@firebird.demo\` on top, scrolling promo on the bottom ```toml [[playlist.section.widget]] type = "image" path = "config/assets/phoenix_transparent.png" fit = "pillarbox" image_align = "right" top_text = "@firebird.demo" top_font = "5x8" top_color = [225, 48, 108] bottom_text = "Open daily 10am – 8pm" bottom_font = "5x8" bottom_color = [255, 240, 200] hold_time = 7.0 ``` ### Typewriter overlay (single-row only — letters type in next to the image) [Section titled “Typewriter overlay (single-row only — letters type in next to the image)”](#typewriter-overlay-single-row-only--letters-type-in-next-to-the-image)  phoenix on the left, \`firebird\` types in on the right with rainbow font\_color ```toml [[playlist.section.widget]] type = "image" path = "config/assets/phoenix_transparent.png" fit = "pillarbox" image_align = "left" text = "firebird" text_align = "right" font_color = "rainbow" animation = "typewriter" hold_time = 8.0 ``` ### Typewriter + rainbow border (frame the panel as the text appears) [Section titled “Typewriter + rainbow border (frame the panel as the text appears)”](#typewriter--rainbow-border-frame-the-panel-as-the-text-appears)  rainbow chase border around the perimeter, white text typing in beside the phoenix ```toml [[playlist.section.widget]] type = "image" path = "config/assets/phoenix_transparent.png" fit = "pillarbox" image_align = "left" text = "firebird" text_align = "right" font_color = [255, 255, 255] animation = "typewriter" border = "rainbow" hold_time = 8.0 ``` ## Tips [Section titled “Tips”](#tips) ### Typewriter is single-row only [Section titled “Typewriter is single-row only”](#typewriter-is-single-row-only) `animation = "typewriter"` rejects three combinations: `bottom_text` set (two-row layout), `text_align = "scroll"` / `"scroll_over"` (cursor moves each tick), or empty `text`. Drop the conflicting setting; typewriter still composes with `font_color = "rainbow"` and `border = "rainbow"`. ### `text_align="scroll"` needs transparency [Section titled “text\_align="scroll" needs transparency”](#text_alignscroll-needs-transparency) Stretch fills every pixel with image, leaving no transparent regions for the text to scroll through. Use `text_align="scroll_over"` for a fullscreen marquee, or pair `scroll` with a transparent PNG and `fit="pillarbox"`. ### `text_x_offset` is rejected in scroll modes [Section titled “text\_x\_offset is rejected in scroll modes”](#text_x_offset-is-rejected-in-scroll-modes) Static offsets don’t compose with the per-tick scroll cursor. Set `text_x_offset = 0` or change `text_align` to `"left"` or `"right"`. ### `hold_time` must be at least 0.05 [Section titled “hold\_time must be at least 0.05”](#hold_time-must-be-at-least-005) `hold_time` is in seconds, not milliseconds. Anything under 50 ms is rejected — nothing shorter than one engine tick can actually display. ### Animated source files only show frame 0 [Section titled “Animated source files only show frame 0”](#animated-source-files-only-show-frame-0) The `image` widget decodes only the first frame of `.gif` / `.webp` files. Use the [`gif`](/widgets/gif/) widget for animation — it shares the entire `image` text-overlay surface plus per-frame mechanics. See also * [widgets/gif](/widgets/gif/) * [widgets/two\_row](/widgets/two_row/) * [assets/emoji](/assets/emoji/) * [concepts/value-tokens](/concepts/value-tokens/) # message widget > Static text with optional border, inline emoji, and color/animation effects. The `message` widget displays static text. It’s the most-used widget — most LED signs are 80% messages with a sprinkling of data widgets.  message with font\_color = 'rainbow' Minimal example ```toml [[playlist.section.widget]] type = "message" text = "Hello, world!" ``` ## Options [Section titled “Options”](#options) | Option | Type | Default | Description | | ---------------- | ------------------------------------------------------------------------------------- | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `text` | string | required | The text to display. Inline `:slug:` emoji are rendered as pixel art. | | `font` | string | `"6x12"` | BDF font name (e.g., `"5x8"`, `"6x12"`) or hires font (e.g., `"Inter-Bold"`). | | `font_size` | int | (BDF cell height) | Real-pixel font size for hires fonts. Required if `font` is hires. | | `font_threshold` | int 0–255 | `128` | Rasterization threshold for hires fonts. Lower = thicker glyphs. | | `font_color` | RGB list / string / table | `[255, 255, 0]` | Constant `[r,g,b]`, `"rainbow"`, `"color_cycle"`, `"random"`, or `{style="gradient", from=[...], to=[...]}`. | | `bg_color` | RGB list | none | Background fill color. Painted across the full panel before text. | | `border` | `"rainbow"` \| `"color_cycle"` \| `"lightbulbs"` \| `[r,g,b]` \| `{style="...", ...}` | none | Perimeter border ring — five styles (rainbow chase, color cycle, constant, bands, lightbulbs); see [/concepts/borders/](/concepts/borders/). | | `animation` | string / table | none | `"typewriter"` for character-by-character reveal. Use the inline-table form to tune speed: `animation = {style = "typewriter", frames_per_char = 6}` (default `frames_per_char = 3` ≈ 150 ms/char at the 50 ms engine tick). | | `padding` | int | `6` | Horizontal padding (in logical pixels) when scrolling. | | `text_y_offset` | int | `0` | Vertical text nudge in logical rows. Negative = up. | Set the content string with `text =`. ## Common patterns [Section titled “Common patterns”](#common-patterns) ### Static text with brand color [Section titled “Static text with brand color”](#static-text-with-brand-color)  constant \`font\_color\` paints every character at the same RGB ```toml [[playlist.section.widget]] type = "message" text = "Breathe. Move. Rise." font_color = [255, 92, 38] # brand flame ``` ### Inline emoji [Section titled “Inline emoji”](#inline-emoji)  \`:taco:\` resolves to the inline pixel-art sprite, with the message text following it ```toml [[playlist.section.widget]] type = "message" text = ":taco: Taco Tuesday!" ``` ### Hi-res font on the bigsign — Inter-Bold at 28px reads well at medium viewing distance [Section titled “Hi-res font on the bigsign — Inter-Bold at 28px reads well at medium viewing distance”](#hi-res-font-on-the-bigsign--inter-bold-at-28px-reads-well-at-medium-viewing-distance)  Inter-Bold at 28 px on the 256×64 bigsign canvas ```toml [[playlist.section.widget]] type = "message" text = "GRAND OPENING" font = "Inter-Bold" font_size = 28 font_color = [225, 48, 108] ``` ### Typewriter effect with rainbow text [Section titled “Typewriter effect with rainbow text”](#typewriter-effect-with-rainbow-text)  typewriter reveal composed with rainbow \`font\_color\` — each character types in at its own rainbow hue ```toml [[playlist.section.widget]] type = "message" text = "Now Enrolling" font_color = "rainbow" animation = "typewriter" ``` ### Gradient between two brand colors — each character lands at its own interpolated hue [Section titled “Gradient between two brand colors — each character lands at its own interpolated hue”](#gradient-between-two-brand-colors--each-character-lands-at-its-own-interpolated-hue)  gradient \`font\_color\` from flame to amber across the characters ```toml [[playlist.section.widget]] type = "message" text = "firebird" font_color = {style = "gradient", from = [255, 92, 38], to = [255, 183, 3]} ``` ### High-contrast caution color — black text on a yellow background [Section titled “High-contrast caution color — black text on a yellow background”](#high-contrast-caution-color--black-text-on-a-yellow-background)  black \`font\_color\` over a yellow \`bg\_color\` — readable from across the room ```toml [[playlist.section.widget]] type = "message" text = "CAUTION" font_color = [0, 0, 0] bg_color = [255, 220, 0] ``` ## Tips [Section titled “Tips”](#tips) ### Typewriter is single-row only on `gif` and `image` [Section titled “Typewriter is single-row only on gif and image”](#typewriter-is-single-row-only-on-gif-and-image) `animation = "typewriter"` works on `message` without restriction. On `gif` and `image`, three combinations are rejected: `bottom_text` set, `text_align = "scroll"` / `"scroll_over"`, or empty `text`. Typewriter still composes with `font_color = "rainbow"` and `border = "rainbow"`. See also * [widgets/countdown](/widgets/countdown/) * [widgets/two\_row](/widgets/two_row/) * [concepts/color-providers](/concepts/color-providers/) * [concepts/value-tokens](/concepts/value-tokens/) # mlb widget > The MLB scores widget is provided by the baseball package in led-ticker-plugins (type = "baseball.scores"). The **MLB scores** widget is provided by the **[baseball](https://github.com/JamesAwesome/led-ticker-plugins/tree/main/plugins/baseball)** package in the led-ticker-plugins monorepo, referenced in config as `type = "baseball.scores"`. * **To add it to your sign:** add `led-ticker-baseball` to `config/requirements-plugins.txt` and restart (`docker compose restart`) — see [Plugins](/plugins/) for the full flow. It uses MLB’s free StatsAPI, so no API key is required. * **Full documentation** — options, display modes (pre-game / in-game / final / postponed), team colors, and screenshots — lives in the [baseball package README](https://github.com/JamesAwesome/led-ticker-plugins/blob/main/plugins/baseball/README.md). The same package also ships the [`baseball.standings`](/widgets/mlb_standings/) widget, the `baseball.roll*` rolling-ball [sprite transition](/transitions/sprite/), and the `:baseball.ball:` emoji. It’s another example of led-ticker’s [plugin system](/plugins/) — a way to add widgets, transitions, and emoji that aren’t part of core. # mlb_standings widget > The MLB standings widget is provided by the baseball package in led-ticker-plugins (type = "baseball.standings"). The **MLB standings** widget is provided by the **[baseball](https://github.com/JamesAwesome/led-ticker-plugins/tree/main/plugins/baseball)** package in the led-ticker-plugins monorepo, referenced in config as `type = "baseball.standings"`. * **To add it to your sign:** add `led-ticker-baseball` to `config/requirements-plugins.txt` and restart (`docker compose restart`) — see [Plugins](/plugins/) for the full flow. It uses MLB’s free StatsAPI, so no API key is required. * **Full documentation** — options, top-N + tracked-team selection, offseason behavior, and screenshots — lives in the [baseball package README](https://github.com/JamesAwesome/led-ticker-plugins/blob/main/plugins/baseball/README.md). The same package also ships the [`baseball.scores`](/widgets/mlb/) widget, the `baseball.roll*` rolling-ball [sprite transition](/transitions/sprite/), and the `:baseball.ball:` emoji. It’s another example of led-ticker’s [plugin system](/plugins/) — a way to add widgets, transitions, and emoji that aren’t part of core. # pool widget > The pool water-temperature widget is provided by the pool package in led-ticker-plugins (type = "pool.monitor"). The **pool** widget is provided by the **[pool](https://github.com/JamesAwesome/led-ticker-plugins/tree/main/plugins/pool)** package in the led-ticker-plugins monorepo, referenced in config as `type = "pool.monitor"`. * **To add it to your sign:** add `led-ticker-pool` to `config/requirements-plugins.txt` and restart (`docker compose restart`) — see [Plugins](/plugins/) for the full flow. It needs a running InfluxDB v2 server. * **Full documentation** — options, `ticker` vs `two_row` layouts, InfluxDB setup, and screenshots — lives in the [pool package README](https://github.com/JamesAwesome/led-ticker-plugins/blob/main/plugins/pool/README.md). Pool is the flagship example of led-ticker’s [plugin system](/plugins/) — a way to add widgets that aren’t part of core. # rss.feed widget > The rss.feed RSS-headline widget is provided by the rss package in led-ticker-plugins (type = "rss.feed"). The **rss.feed** widget is provided by the **[rss](https://github.com/JamesAwesome/led-ticker-plugins/tree/main/plugins/rss)** package in the led-ticker-plugins monorepo, referenced in config as `type = "rss.feed"`. It fetches a remote RSS feed and turns each headline into its own scrolling line in the section.  RSS feed scrolling Nintendo Life headlines, each story in a different color from the default rotation. * **To add it to your sign:** add `led-ticker-rss` to `config/requirements-plugins.txt` and restart (`docker compose restart`) — see [Plugins](/plugins/) for the full flow. * **Full documentation** — options, config examples, and a demo gif — lives in the [rss package README](https://github.com/JamesAwesome/led-ticker-plugins/blob/main/plugins/rss/README.md). See the [plugin system](/plugins/) for how plugin widgets work. # two_row widget > Held top row + scrolling bottom row, ideal for storefront layouts. The `two_row` widget renders two independent text strings on the same canvas: a **held top row** for a stable identifier (handle, headline, brand tag) and a **scrolling bottom row** for promotional copy that can be longer than the canvas width. When the bottom row fits, it stays fixed using `bottom_align`; when it overflows, it scrolls left automatically. Designed for the bigsign in `slideshow` mode at `scale = 2`, where the logical canvas is 128 pixels wide — enough for most social handles without scrolling.  two\_row at scale=1 — top: @example (IG magenta), bottom: scrolling promo (cream); rendered locally so the marquee completes one full pass Minimal example ```toml [[playlist.section.widget]] type = "two_row" top_text = "@yourhandle" bottom_text = "Open daily 10–6 · all levels welcome" ``` ## Options [Section titled “Options”](#options) ## Top row | Option | Type | Default | Description | | -------------------- | ------------------------- | ----------------- | --------------------------------------------------------------------------------------------------------------------------- | | `top_text` | string | required | Text for the held top row. Inline `:slug:` emoji are rendered as pixel art. | | `top_color` | RGB list / string / table | `[255, 255, 0]` | Top-row color. Constant `[r,g,b]`, `"rainbow"`, `"color_cycle"`, `"random"`, or `{style="gradient", from=[...], to=[...]}`. | | `top_align` | string | `"center"` | Horizontal alignment when text fits: `"left"`, `"center"`, or `"right"`. | | `top_font` | string | (same as `font`) | Per-row font override. Falls back to `font` when unset. | | `top_font_size` | int | (BDF cell height) | Real-pixel font size for hires `top_font`. Required when `top_font` is a hires font name. | | `top_font_threshold` | int 0–255 | `128` | Rasterization threshold for hires `top_font`. Lower = thicker glyphs. | | `top_text_y_offset` | int | `0` | Vertical nudge for the top row's text in logical rows. Negative = up. | | `top_emoji_y_offset` | int | `0` | Vertical nudge for the top row's emoji in logical rows. Set equal to `top_text_y_offset` to shift the whole row together. | | `top_bg_color` | RGB list | none | Per-band background fill for the top row only. Painted over any `bg_color`. | ## Bottom row | Option | Type | Default | Description | | ----------------------------- | ------------------------- | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `bottom_text` | string | required | Text for the scrolling bottom row. Scrolls left when it overflows the canvas width. | | `bottom_color` | RGB list / string / table | `[255, 255, 0]` | Bottom-row color. Same value types as `top_color`. | | `bottom_align` | string | `"center"` | Alignment when bottom text fits without scrolling. Ignored when text overflows. | | `bottom_font` | string | (same as `font`) | Per-row font override for the bottom row. Falls back to `font` when unset. | | `bottom_font_size` | int | (BDF cell height) | Real-pixel font size for hires `bottom_font`. Required when `bottom_font` is a hires font name. | | `bottom_font_threshold` | int 0–255 | `128` | Rasterization threshold for hires `bottom_font`. Lower = thicker glyphs. | | `bottom_text_y_offset` | int | `0` | Vertical nudge for the bottom row's text in logical rows. Negative = up. | | `bottom_emoji_y_offset` | int | `0` | Vertical nudge for the bottom row's emoji in logical rows. | | `bottom_bg_color` | RGB list | none | Per-band background fill for the bottom row only. Painted over any `bg_color`. | | `bottom_text_wrap` | bool | `false` | Seamless wrap mode for the bottom row. When `true`, the bottom row repeats with a separator between copies and at least one full copy is on the panel at every tick. Top row never wraps. Only allowed in `mode = "slideshow"`. | | `bottom_text_separator` | string | `" • "` (when `bottom_text_wrap = true`) | Glyph(s) drawn between bottom-row repeats in wrap mode. `""` falls back to a two-space gap. Rendered in the bottom row's font. | | `bottom_text_separator_color` | color spec | inherit `bottom_color` | Color for the bottom separator in wrap mode. Whole-string provider (one hue per frame); accepts the same value types as `bottom_color`. Inherits `bottom_color` (NOT `font_color`). | | `bottom_text_loops` | int | `0` | Minimum number of full wrap cycles before the section can transition. One cycle = `bottom_text` + separator. Requires `bottom_text_wrap = true` (rule 28). On `gif` / `image` widgets the equivalent field is `text_loops`. | ## Layout | Option | Type | Default | Description | | ---------------- | ---- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `top_row_height` | int | none | Give the top band exactly N logical rows; bottom gets the remainder. Default `None` splits 50/50. Use with a small `font` on top + a larger `bottom_font` to achieve a compact tag + wide marquee. Must be `> 0` and `< canvas.height`. | | `padding` | int | `6` | Horizontal padding added to the bottom row's cursor position when scrolling (spacing between repeats). | > `scale` and `content_height` are **section-level** fields, not widget fields. Typical bigsign deployments use `scale = 2` (doubles logical canvas width to 128 px so handles fit on the top row) and `content_height = 16` (hard ceiling: `content_height × scale ≤ panel_h_real`). See [display concepts](/concepts/display) for details. ## Shared | Option | Type | Default | Description | | ---------- | ------------------------------------------------------------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `font` | string | `"5x8"` | Default font for both rows when `top_font` / `bottom_font` are unset. BDF alias (e.g. `"5x8"`, `"6x12"`) or hires font name (e.g. `"Inter-Bold"`). | | `bg_color` | RGB list | none | Background fill for the full panel before text. Per-band `top_bg_color` / `bottom_bg_color` paint on top of this. | | `border` | `"rainbow"` \| `"color_cycle"` \| `"lightbulbs"` \| `[r,g,b]` \| `{style="...", ...}` | none | Perimeter border ring — five styles (rainbow chase, color cycle, constant, bands, lightbulbs); see [/concepts/borders/](/concepts/borders/). Paints at physical panel resolution (bypasses ScaledCanvas), so the border traces the real panel edge, not the logical canvas edge. | ## Common patterns [Section titled “Common patterns”](#common-patterns) ### Brand-handle layout with inline emoji [Section titled “Brand-handle layout with inline emoji”](#brand-handle-layout-with-inline-emoji)  centered handle + inline emoji on top, left-aligned promo on the bottom (bigsign canvas, scale=2) ```toml [[playlist.section]] mode = "slideshow" scale = 2 content_height = 16 [[playlist.section.widget]] type = "two_row" top_text = "@firebirdyoga.demo :instagram:" top_color = [225, 48, 108] top_align = "center" bottom_text = "Vinyasa · yin · hot power · restorative · slow flow · all levels" bottom_color = [255, 240, 200] bottom_align = "left" ``` ### Asymmetric row split — bold tag on top, larger marquee below [Section titled “Asymmetric row split — bold tag on top, larger marquee below”](#asymmetric-row-split--bold-tag-on-top-larger-marquee-below)  Inter-Bold @ 14 handle on a 10-row top band, Inter-Bold @ 22 marquee on the 14-row bottom band `top_row_height = 10` gives the top band 10 logical rows; the bottom gets the remainder (14). The top font’s line-height has to fit the band — Inter-Bold @ 14 is 9 logical rows at scale=2, which fits the 10-row band. To go more aggressive (`top_row_height = 6` for a thinner tag), pair it with a smaller hi-res font like Inter-Regular @ 8 — but Regular at that size gets hard to read at typical viewing distances, so the bolder pairing here is the recommended starting point. ```toml [[playlist.section]] mode = "slideshow" scale = 2 content_height = 24 [[playlist.section.widget]] type = "two_row" top_text = "@firebird.demo" top_row_height = 10 top_font = "Inter-Bold" top_font_size = 14 top_color = [225, 48, 108] bottom_text = "Vinyasa • Yin • Hot Power • Restorative • Slow Flow • All Levels Welcome" bottom_font = "Inter-Bold" bottom_font_size = 22 bottom_color = [255, 240, 200] ``` ### Per-row font hierarchy (Inter-Bold handle + Inter-Regular promo) [Section titled “Per-row font hierarchy (Inter-Bold handle + Inter-Regular promo)”](#per-row-font-hierarchy-inter-bold-handle--inter-regular-promo)  Inter-Bold @ 18 on top, Inter-Regular @ 14 on the scrolling row — establishes a clear visual hierarchy Hi-res fonts at these sizes need taller bands than the default 8 logical rows. Bump `content_height` from 16 to 24 so each row gets 12 logical rows — Inter-Bold @ 18 measures 12 logical at scale=2 and only fits if the band is at least that tall. ```toml [[playlist.section]] mode = "slideshow" scale = 2 content_height = 24 [[playlist.section.widget]] type = "two_row" top_text = "@firebird.demo" top_font = "Inter-Bold" top_font_size = 18 top_color = [225, 48, 108] bottom_text = "Firebird Yoga — now booking spring sessions — your first class is free." bottom_font = "Inter-Regular" bottom_font_size = 14 bottom_color = [255, 240, 200] ``` ### Hi-res emoji on the top row — `:instagram:` renders as the full 32×32 sprite when the band can fit it [Section titled “Hi-res emoji on the top row — :instagram: renders as the full 32×32 sprite when the band can fit it”](#hi-res-emoji-on-the-top-row--instagram-renders-as-the-full-3232-sprite-when-the-band-can-fit-it)  Inter-Bold @ 22 handle next to the hi-res \`:instagram:\` sprite on a 16-row top band, scrolling promo on the 8-row bottom The hi-res sprite is 32 real pixels tall. At `scale = 2` it’s 16 logical pixels, which exactly matches `top_row_height = 16` — the sprite anchors at the top of the band with no bleed into the bottom row. Smaller bands fall back to the 8×8 lo-res sprite automatically. ```toml [[playlist.section]] mode = "slideshow" scale = 2 content_height = 24 [[playlist.section.widget]] type = "two_row" top_text = ":instagram: @firebirdyoga.demo" top_row_height = 16 top_font = "Inter-Bold" top_font_size = 22 top_color = [225, 48, 108] top_align = "left" bottom_text = "Vinyasa • yin • hot power • restorative • slow flow • all levels" bottom_color = [255, 240, 200] bottom_align = "left" ``` ### Wrap mode (bottom row, seamless marquee) [Section titled “Wrap mode (bottom row, seamless marquee)”](#wrap-mode-bottom-row-seamless-marquee)  held magenta \`BREAKING\` on top, cyan \`tap to subscribe\` wrapping continuously on the bottom with a rainbow \`\*\` separator Setting `bottom_text_wrap = true` runs the bottom row as a seamless marquee — chasing itself across the canvas with a separator between repeats. Top row stays held at `top_align`; only the bottom row wraps. Engages even when the bottom text fits — predictable. ```toml [[playlist.section.widget]] type = "two_row" top_text = "BREAKING" top_color = [225, 48, 108] bottom_text = "tap to subscribe" bottom_text_wrap = true bottom_text_separator = " * " # default: " • " bottom_text_separator_color = "rainbow" # default: inherit bottom_color ``` | Field | Type | Default | Meaning | | ----------------------------- | ---------- | ---------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | | `bottom_text_wrap` | bool | `false` | Toggle seamless wrap on the bottom row. Requires `bottom_text` non-empty. | | `bottom_text_separator` | string | `" • "` (when `bottom_text_wrap = true`) | Glyph(s) between bottom-row repeats. `""` falls back to a two-space gap. | | `bottom_text_separator_color` | color spec | inherit `bottom_color` | Color for the bottom separator; whole-string provider (one hue per frame). | | `bottom_text_loops` | int | `0` | Minimum full wrap cycles before the section can transition. `0` = no minimum. Requires `bottom_text_wrap = true`. | Notes: * `bottom_text_wrap` always wraps when set, even if the bottom text fits the canvas. * Top row never wraps (no `top_text_wrap` field exists). * The separator color inherits `bottom_color` (NOT `font_color`). * `bottom_text_wrap` is only allowed in `mode = "slideshow"`. In `ticker` / `one_at_a_time` modes, validation refuses it. ### Scroll-through mode (one pass, offscreen to offscreen) [Section titled “Scroll-through mode (one pass, offscreen to offscreen)”](#scroll-through-mode-one-pass-offscreen-to-offscreen)  held magenta \`NOW PLAYING\` on top, cyan song title flies through offscreen-to-offscreen on the bottom. \`hold\_time = 10.0\` drives the pass count via max-of math — no \`bottom\_text\_loops\` set, so the engine fills the section duration with as many passes as fit Setting `bottom_text_scroll = "scroll_through"` forces the bottom row to scroll offscreen-to-offscreen: text starts fully off the right edge, scrolls left, ends fully off the left edge. The widget exits after the computed number of passes (controlled by `bottom_text_loops` and `hold_time` — see “Pass count” below; default is one pass). `bottom_align` is ignored. Use it when you want the “marquee runs through and is done” feel — a now-playing line that flies across and the section moves on — instead of the held-when-fits / scroll-when-overflows default. ```toml [[playlist.section.widget]] type = "two_row" top_text = "NOW PLAYING" bottom_text = "Some Long Song Title - Album Name - Artist (2026)" bottom_text_scroll = "scroll_through" ``` | Field | Type | Default | Meaning | | -------------------- | ------ | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | | `bottom_text_scroll` | string | `"marquee"` | Bottom-row scroll style. `"marquee"` (default) preserves existing behavior; `"scroll_through"` forces single-pass offscreen-to-offscreen on every visit. | Behavior table: | Mode | When bottom fits | When bottom overflows | | ------------------ | ---------------------- | ------------------------------------------------- | | `"marquee"` | held at `bottom_align` | cursor-driven single-pass (last char flush right) | | `"scroll_through"` | forced scroll-through | forced scroll-through | Notes: * Mutually exclusive with `bottom_text_wrap = true` — pick one. Scroll-through repeats N offscreen-to-offscreen passes; wrap is a seamless tiled marquee. * Requires non-empty `bottom_text`. * Only valid in `mode = "slideshow"`. In `ticker` / `one_at_a_time` modes validation refuses it (rule 32), same as `bottom_text_wrap`. * **Pass count is controlled by `bottom_text_loops`** (default `0` = one pass per visit). Set `bottom_text_loops = N` to make the widget run N full passes before the section transitions: ```toml bottom_text_scroll = "scroll_through" bottom_text_loops = 3 # scroll on / scroll off, three times ``` * **`hold_time` acts as a floor.** When both `hold_time` and `bottom_text_loops` are set, the engine uses the LONGER of the two (“max” semantics): `n_passes = max(bottom_text_loops or 1, ceil((hold_time × 1000 / scroll_step_ms) / cycle_width))`. To compute the crossover: `hold_time × 1000 / scroll_step_ms` (tick count from hold; `hold_time` is seconds, `scroll_step_ms` is milliseconds) vs `bottom_text_loops × cycle_width_logical_px` (tick count from loops, since the engine advances exactly one logical pixel per tick). Whichever is bigger wins. This matches how [`gif`](/widgets/gif/) and [`image`](/widgets/image/) widgets handle the same field. ### `bottom_text_loops` [Section titled “bottom\_text\_loops”](#bottom_text_loops)  \`bottom\_text\_loops = 2\` paired with \`bottom\_text\_wrap = true\` — section's \`hold\_time = 1.0\` would normally cut the marquee mid-pass, but the loops floor extends the visit to two complete wrap cycles before transition Number of full bottom-row cycles the widget plays before the section transitions. Default `0` means “one pass” — preserved as the baseline behavior. The field requires EITHER `bottom_text_wrap = true` (seamless tiled marquee, one cycle = `bottom_text` + `bottom_text_separator`) OR `bottom_text_scroll = "scroll_through"` (one cycle = one offscreen-to-offscreen pass). * Without `bottom_text_wrap = true` or `bottom_text_scroll = "scroll_through"`, `bottom_text_loops > 0` is a validation error (rule 28) — the non-wrap, non-scroll-through bottom row scrolls once over its overflow and has no cycle to count. * **With `bottom_text_wrap = true`**: minimum number of full wrap cycles before the section transitions. When both `hold_time` and `bottom_text_loops` are set, the engine uses the LONGER of the two (“max” semantics). To compute the crossover: `hold_time × 1000 / scroll_step_ms` (tick count from hold) vs `bottom_text_loops × cycle_width_logical_px` (tick count from loops; the engine advances exactly one logical pixel per tick). Whichever is bigger wins. * **With `bottom_text_scroll = "scroll_through"`**: minimum number of offscreen-to-offscreen passes. When both `hold_time` and `bottom_text_loops` are set, the engine uses the LONGER of the two (“max” semantics). To compute the crossover: `hold_time × 1000 / scroll_step_ms` (tick count from hold) vs `bottom_text_loops × cycle_width_logical_px` (tick count from loops; the engine advances exactly one logical pixel per tick). Whichever is bigger wins. This is the same shape as the wrap-mode bullet above. * Mirrors `text_loops` on the [`gif`](/widgets/gif/) and [`image`](/widgets/image/) widgets in their two-row mode. The validator catches the cross-widget typo (rule 29) and points you at `bottom_text_loops`. ## Tips [Section titled “Tips”](#tips) ### Font line-height must fit the per-row band [Section titled “Font line-height must fit the per-row band”](#font-line-height-must-fit-the-per-row-band) Each row gets a slice of `content_height` (50/50 by default, or per `top_row_height`). If a font’s logical line-height exceeds its band, the validator rejects it. Pick a smaller `font_size`, raise `content_height`, adjust `top_row_height`, or use a BDF alias (`5x8`, `6x12`). Reference pairing: BDF `5x8` fits `content_height = 16`; Inter at sizes 14+ usually needs `content_height = 24` or larger. ### `scale = 4` is too narrow for handles [Section titled “scale = 4 is too narrow for handles”](#scale--4-is-too-narrow-for-handles) At `scale = 4` the bigsign’s logical canvas is only 64 px wide — most `@handles` clip mid-word. Use `scale = 2` (128 logical px) on this widget; you can mix scales across sections. ### `content_height` hard ceiling [Section titled “content\_height hard ceiling”](#content_height-hard-ceiling) On the bigsign: `content_height ≤ 16` at `scale = 4`, `content_height ≤ 32` at `scale = 2` (`content_height × scale ≤ panel_height`). Above the ceiling, rows near the edges clip silently. For per-row breathing room use `top_text_y_offset` / `bottom_text_y_offset`, not over-specified `content_height`. See also * [widgets/message](/widgets/message/) * [widgets/gif](/widgets/gif/) * [concepts/display](/concepts/display/) * [concepts/value-tokens](/concepts/value-tokens/) # weather.current widget > The weather.current current-conditions widget is provided by the weather package in led-ticker-plugins (type = "weather.current"). The **weather.current** widget is provided by the **[weather](https://github.com/JamesAwesome/led-ticker-plugins/tree/main/plugins/weather)** package in the led-ticker-plugins monorepo, referenced in config as `type = "weather.current"`. It shows current conditions and temperature from [WeatherAPI.com](https://www.weatherapi.com/) with a pixel-art condition icon.  Weather showing condition icon, label, and temperature in their real deployed colors. Install the plugin and set your API key, then add a widget block to your config: ```toml [[playlist.section]] mode = "slideshow" [[playlist.section.widget]] type = "weather.current" text = "NYC" location = "New York" units = "imperial" ``` To install the plugin on a Docker deploy, add its line to the plugin manifest and restart: ```bash # First plugin? Create your manifest from the example: cp -n config/requirements-plugins.example.txt config/requirements-plugins.txt # Add the package (one name per line), then restart: echo "led-ticker-weather" >> config/requirements-plugins.txt docker compose restart ``` You also need `WEATHERAPI_KEY` in your `.env` — free key at [weatherapi.com](https://www.weatherapi.com/). Other install paths (web UI Store tab, dev checkout) are on the [Plugins page](/plugins/). **Full documentation** — all options, config examples, and a demo gif — lives in the [weather package README](https://github.com/JamesAwesome/led-ticker-plugins/blob/main/plugins/weather/README.md).