CandyGifView
Terminal GIF viewer
The terminal GIF viewer: point it at a .gif and it sizes to your viewport, decodes via sugar-animation (which needs ext-gd), and plays the animation in the alternate screen — full-cell 24-bit blocks or an ASCII luminance-density ramp, toggled live. This is the command split out of the animation package into its own app.
Install
composer require sugarcraft/candy-gifview
Quickstart
# with a project-local install, invoke the binary as ./vendor/bin/candy-gifview
./vendor/bin/candy-gifview my-animation.gif # solid 24-bit blocks (default)
./vendor/bin/candy-gifview my-animation.gif density # luminance-density ramp
# flags
# --fps=N --speed=N|Nfps|max --duration=SECONDS --watch --paused
# keys while playing
# Space pause / resume
# Left/Right step frames
# d toggle solid <-> density
# q / Esc / Ctrl-C quit
What's in the box
One-command viewer
candy-gifview file.gif — no flags to learn; an optional second argument picks the render preset.Viewport-sizedQueries the TTY size behind a core
stream_isatty gate and reserves two rows (status line + trailing newline), so output never overflows the screen; off a TTY it falls back to a 60×24 cell grid.Alternate screenRuns the sugar-animation
Player inside a sugar-core Program with useAltScreen, so your shell buffer is untouched when you quit.Live preset toggle
d swaps solid blocks ↔ the · .:-=+*#%@ density ramp (· marks the ramp's leading space) without losing your frame position.Helpable
--help / -h print the localized usage line and exit 0; missing or unreadable files exit non-zero with the decoder's error on stderr.Testable coreAll argument handling lives in
SugarCraft\GifView\Cli — the bin is a thin shim (autoload probe with phar-identity resolution, locale wiring, then the Cli::main() hand-off), and a closure seam lets tests drive the wired Player without a terminal.LocalizedCLI usage and refusal messages ship in sixteen locales via the sugar-core i18n lookup.
Source & demos
- Source on GitHub
- Full README
- Runnable examples
- Decode + playback engine: sugarcraft/sugar-animation.
- Originally inspired by gifterm (Go); SugarCraft is developed as a native PHP project.
API
| Class | Method | Description |
|---|---|---|
| Cli | main(argv, stdout, stderr, play, watchStat, decode) | Parse args, decode, wire the Player, run the Program; returns the exit code |
| Cli | viewportCells() | TTY-sized cell grid (cols, rows-2) behind a stream_isatty gate, 60×24 fallback |
| Lang | t(key, params) | Localized CLI messages (namespace gifview) |
Demos.
VHS-recorded GIFs of every example shipped with the app. Regenerated automatically on every push that touches the source.