SugarAnimation
ANSI/GIF animation toolkit
Two animators in one package: it decodes a .gif from disk via ext-gd, downsamples each frame to a configurable cell grid, and paints it with 24-bit ANSI color — as full-cell background color (space glyphs) or as an ASCII luminance ramp — and it parses and replays truecolor .ansi art files frame by frame. The ready-made viewer CLI ships separately as candy-gifview.
Install
composer require sugarcraft/sugar-animation
Quickstart
# The ready-made viewer CLI is a separate app package:
# composer require sugarcraft/candy-gifview
# candy-gifview my-animation.gif # solid blocks (default)
# candy-gifview my-animation.gif density # luminance ramp
// Programmatic — "cat.gif" is just any .gif on disk:
use SugarCraft\Core\Program;
use SugarCraft\Core\ProgramOptions;
use SugarCraft\Animation\Decoder;
use SugarCraft\Animation\Player;
$frames = Decoder::decode('cat.gif', cellsW: 80, cellsH: 30);
(new Program(new Player($frames),
new ProgramOptions(useAltScreen: true)))->run();
// .ansi art — parse once, print one frame as SGR text:
use SugarCraft\Animation\AnsiArt;
$art = AnsiArt::fromFile('logo-neon-tc-72x9.ansi');
echo $art->sgrText(0), PHP_EOL; // animated files: pick a frame index
The bundled examples/play.php generates a tiny synthetic animated GIF and plays it end-to-end — a self-contained way to see the pipeline without supplying any files of your own.
What's in the box
density preset maps each cell's luminance (0.299r + 0.587g + 0.114b) to a ramp glyph and carries the color as a 24-bit foreground — the shape still reads where color is stripped.Frame.solid — full-cell 24-bit background color (space glyph). density — ASCII luminance ramp ' .:-=+*#%@' with a 24-bit foreground.Space pauses; ← / → step through frames manually.d swaps solid ↔ density without losing your position; q, Esc or Ctrl+C quits. The Player's keys are fixed — not rebindable.Renderer::withAdaptiveSize() queries the TTY via SizeIoctl (ioctl TIOCGWINSZ) and clips the art to the viewport. The cell grid is fixed at decode, so a resize clips — art never re-scales; the Player's ~78-column status line is not width-clamped, so playback looks its best at 82+ columns..ansi byte streams (SGR runs + glyphs, frame headers ESC[<n>A) parse into cell-grid frames via AnsiArt; ArtLibrary indexes a corpus and selects a slug at the deepest supported depth (tc → 256 → 16), and ArtLoop turns elapsed seconds into frame indices.playOnce(), withLoops(n) and withMaxSeconds(s) cap a run; withFixedFps() pins advance to a uniform wall-clock cadence.Decoder::MAX_INPUT_BYTES (64 MiB) on the stat, before reading. decodeBytes() and AnsiArt::fromString() take bytes you already hold — their size is your budget.Cmd::tick($seconds, …) (sugar-core) schedules frame advance — no busy-waiting in the main fiber.Untrusted .ansi input
The parser is defensive but not a sandbox. Complete OSC sequences and unknown CSI bodies are dropped, not rendered, and Frame/AnsiArt keep only canonical SGR runs, so sgrText() never replays an escape the input carried. Two caveats stand: C0 control bytes that are not part of an escape sequence are preserved as glyph data — echoing $cell->glyph raw (or sgrText()) hands them to your terminal, an audible-and-cursor hazard on hostile files — and file ingress is bounded by stat before reading (Decoder::MAX_INPUT_BYTES, 64 MiB) at AnsiArt::fromFile() and Decoder::readFile() — but fromString() parses whatever bytes you hand it, with no cap, so bound the corpora you point ArtLibrary and the string APIs at.
Reduced motion
No REDUCE_MOTION (or other reduce-motion convention) is consulted anywhere in the library — autoplay is autoplay. The real mitigations are API-side: construct the Player paused (new Player($frames, paused: true)) so nothing moves until Space, step manually with ←/→, slow the cadence with withFixedFps(), and bound the run with playOnce() / withMaxSeconds(). Consulting REDUCE_MOTION by default is a tracked code follow-up, not a current behavior.
Source & demos
- Source on GitHub
- Full README
- Runnable examples
- Originally inspired by gifterm (Go); SugarCraft is developed as a native PHP project.
API
| Class | Method | Description |
|---|---|---|
| Decoder | decode(path, cellsW, cellsH) | Decode a GIF into a list of Frame objects — stretched to exactly cellsW×cellsH (no aspect-ratio fit); throws on cap breach, missing ext-gd, or non-GIF input. |
| Decoder | decodeBytes(bytes, cellsW, cellsH, withCanvasRgba) | Decode from a byte string as a Generator; optionally carry full-canvas RGBA per frame. |
| Decoder | readFile(path) / loopCount(bytes) | Read a file off disk / read the NETSCAPE loop count (null or 0 = infinite). |
| Frame | __construct(cells, delay, disposal, transparent, rgba, …) | Value object: one frame's cells, centisecond delay, disposal method, transparency, optional RGBA. |
| Player | __construct(frames, index = 0, paused = false, preset = Renderer::PRESET_SOLID, renderer = null, fixedFps = null, maxSeconds = null, loops = null) | Create the playback TEA model. |
| Player | withFixedFps(fps) | Uniform cadence — positive finite; MAX_FPS (100,000) is a documented advisory ceiling the library does not enforce; hosts (candy-gifview) clamp. |
| Player | withMaxSeconds(s) / withLoops(n) / playOnce() | Bound the run by time, repeat count, or a single pass. |
| Player | withFrames(frames) / withWatch(probe) | Rebind the frame stream in place / install a reload probe closure. |
| AnsiArt | fromFile(path) / fromString(bytes) | Parse a .ansi byte stream into cell-grid frames. |
| AnsiArt | frameCells(i) / sgrText(i) / width() / height() / frameCount() / isAnimated() | One frame's AnsiCell grid / canonical SGR replay text / dimensions and frame metadata. |
| AnsiCell | new(glyph, sgr) | One cell: glyph plus its canonical whole-state SGR (both public readonly). |
| ArtLibrary | fromDir(dir) / pick(slug, depthTag) / randomSlug(depthTag) / mergeManifest(jsonl) | Index a .ansi corpus; select a slug at the deepest supported depth (tc → 256 → 16). |
| ArtLoop | new(frameCount, frameSeconds, pauseSeconds) / frameAt(elapsed) | Elapsed-seconds frame cycling for banners and logos. |
| Renderer | new() / withAdaptiveSize() | Unconstrained renderer / renderer that queries TTY size via SizeIoctl and clips output. |
| Renderer | renderFrame(frame, preset) | Render one frame to an ANSI string, clipped to its rows/cols. |
| Program (sugar-core) | __construct(model, options) | Create program. |
| Program (sugar-core) | run() | Start the event loop. |
| ProgramOptions (sugar-core) | __construct(useAltScreen: true, …) | Configure terminal mode. |
Demos
VHS-recorded GIF of the example shipped with the library. Regenerated by CI on pushes that touch the source.