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 edgescolor_flash — full-canvas flash, white / cyan / magenta via transition_colorscroll — 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.
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.
