All 22 apps

CandyGifView

Terminal GIF viewer

inspired by namzug16/gifterm gif animation viewer cli

CandyGifView code coverage

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 viewercandy-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 toggled 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

Try the quickstart →

API

ClassMethodDescription
Climain(argv, stdout, stderr, play, watchStat, decode)Parse args, decode, wire the Player, run the Program; returns the exit code
CliviewportCells()TTY-sized cell grid (cols, rows-2) behind a stream_isatty gate, 60×24 fallback
Langt(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.

VHS recording: candy-gifview playing a synthetic GIF — solid 24-bit blocks, then the ASCII density ramp

View

Synthetic gif played through the viewer CLI, both presets.