PHPackages sugarcraft/sugar-reel - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Utility & Helpers](/categories/utility) 4. / 5. sugarcraft/sugar-reel ActiveLibrary[Utility & Helpers](/categories/utility) sugarcraft/sugar-reel ===================== Terminal video player for SugarCraft — plays mp4 (and more) by decoding frames on the fly and rendering them to ASCII / ANSI / truecolor half-block / sixel / kitty output. 00PHP Since Jun 22Pushed todayCompare [ Source](https://github.com/sugarcraft/sugar-reel)[ Packagist](https://packagist.org/packages/sugarcraft/sugar-reel)[ RSS](/packages/sugarcraft-sugar-reel/feed)WikiDiscussions master Synced today READMEChangelogDependenciesVersions (1)Used By (0) SugarReel ========= [](#sugarreel) [![CI](https://github.com/detain/sugarcraft/actions/workflows/ci.yml/badge.svg?branch=master)](https://github.com/detain/sugarcraft/actions/workflows/ci.yml)[![codecov](https://camo.githubusercontent.com/15c4a1d81704d837ffd182874f704511b719bbd83c57398f84764d9f012e9541/68747470733a2f2f636f6465636f762e696f2f67682f64657461696e2f737567617263726166742f6272616e63682f6d61737465722f67726170682f62616467652e7376673f666c61673d73756761722d7265656c)](https://app.codecov.io/gh/sugarcraft?flags%5B0%5D=sugar-reel)[![Packagist Version](https://camo.githubusercontent.com/9f7e3df15766d721bff8f71bd072b7224efd5254d67024914c4781356547ee13/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f737567617263726166742f73756761722d7265656c3f6c6162656c3d7061636b6167697374)](https://packagist.org/packages/sugarcraft/sugar-reel)[![License](https://camo.githubusercontent.com/7013272bd27ece47364536a221edb554cd69683b68a46fc0ee96881174c4214c/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4d49542d626c75652e737667)](LICENSE)[![PHP](https://camo.githubusercontent.com/fd3accad83cd317a9843432403191b4e555c55d57d63e10897f3f1dff5ed169e/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f7068702d254532253839254135382e332d3838393262662e737667)](https://www.php.net/) Terminal **video player** — plays `mp4` / `gif` / `avi` / `webm` and more on the fly, rendering each frame as ASCII, ANSI 256-color, truecolor half-blocks, or via modern graphics protocols (sixel / kitty / iTerm2). Like `mpv -vo tct`, but in PHP and reusing the SugarCraft rendering stack throughout. ``` composer require sugarcraft/sugar-reel ``` ``` use SugarCraft\Reel\Player; // Play a video with auto-detected terminal capability. $player = Player::open('clip.mp4', cols: 80, rows: 24); // Run it (Space=play, q=quit). (new \SugarCraft\Core\Program($player))->run(); ``` > **Status:** Step 7 ✓ — full implementation with ffmpeg decode pipe, pure-PHP GIF fallback, all rendering modes (ascii/ansi256/truecolor/ half-block/sixel/kitty/iTerm2), delta repaint, seek, speed control, and a runnable example. Install ------- [](#install) ``` composer require sugarcraft/sugar-reel ``` Requires: - PHP 8.3+ - `ffmpeg` and `ffprobe` in `$PATH` for `mp4`/`avi`/`webm` playback - `ext-gd` for `.gif` playback (pure-PHP fallback, no ffmpeg needed) - A terminal with at least 256-color support for ANSI modes Usage ----- [](#usage) ``` # Built-in synthetic test pattern (no video file needed) php examples/play.php # Play a real video file php examples/play.php video.mp4 # Force a specific rendering mode php examples/play.php video.mp4 halfblock php examples/play.php video.mp4 ascii # Force auto mode (probe terminal, pick best available) php examples/play.php video.mp4 auto # Set terminal dimensions SUGAR_REEL_COLS=120 SUGAR_REEL_ROWS=40 php examples/play.php ``` ### Rendering modes [](#rendering-modes) ModeDescriptionTerminal requirement`ascii`Grayscale luminance ramp (` .,:;i1tfLCG08@`)Any`ansi256`256-color cube + grey ramp256-color`truecolor`24-bit RGB truecolor24-bit color`halfblock`24-bit `▀` half-blocks, 2× vertical resolution24-bit color`sixel`Sixel graphics protocol (DEC)Sixel-capable`kitty`Kitty graphics protocol (DCS APC)Kitty-compatible`iterm2`iTerm2 inline image (OSC 1337)iTerm2 / WezTerm`auto`Probe terminal, pick best available (default)—Auto mode probes the terminal using `Mosaic::diagnose()` (for sixel/kitty/ iTerm2) and falls back to `ColorProfile::detect()` for ANSI modes. ### Luminance ramp selection [](#luminance-ramp-selection) ASCII/ANSI256 text modes use a luminance ramp to map pixel brightness to characters. Three named ramps are available: RampCharactersBest for`minimal`` .:-=+*#%@`Low-resolution / high contrast`standard`` .,:;i1tfLCG08@`General use (default)`dense``` .`^",:;Il!i><~+\_-?\]\[}{1)(\\/tfjrxnuvczXYUJCLQ0OZmwqpdbkhao\*#MW&8%B@$````` // Use the dense ramp for more detailed ASCII output Reel::open('video.mp4')->withRamp('dense')->play(); ``` Keyboard controls ----------------- [](#keyboard-controls) KeyAction`Space`Pause / resume`←`Seek backward 10 frames`→`Seek forward 10 frames`[`Decrease playback speed (−0.25×, min 0.25×)`]`Increase playback speed (+0.25×, max 4.0×)`0`–`9`Seek to 0–90% of video duration`m`Cycle to next rendering mode`q` / `Esc`Quit`resize`Terminal resize (SIGWINCH) re-scales video automatically`loop`Loop is set at open time via `Reel::new()->withLoop(true)->play()` (no keyboard shortcut)Architecture ------------ [](#architecture) ``` video file (mp4/gif/avi/webm) │ ▼ ┌───────────────────┐ ┌─────────────────┐ │ VideoSource::probe│ │ DecoderFactory │ │ (ffprobe JSON) │────▶│ create() │ └───────────────────┘ └────────┬─────────┘ │ ┌────────────┴────────────┐ │ │ GifDecoder FfmpegDecoder (pure PHP / GD) (ffmpeg pipe) │ │ └────────────┬───────────┘ ▼ ┌──────────────────────┐ │ RgbFrame (rgb24) │ └──────────┬─────────────┘ │ ┌─────────┴──────────────┐ │ FrameRenderer / │ │ Mosaic bridge │ └─────────┬──────────────┘ │ ┌─────────┴──────────────┐ │ Player (TEA Model) │ │ tick() → view() │ └─────────┬──────────────┘ │ ┌─────────▼──────────────┐ │ Program (candy-core) │ │ raw mode + alt screen│ └────────────────────────┘ ``` - **Decode:** `FfmpegDecoder` shells out to `ffmpeg` for raw RGB frames (pre-scaled to cell dimensions). `GifDecoder` wraps candy-flip's pure-PHP GIF decoder. - **Render:** Delegates to candy-mosaic for sixel/kitty/iTerm2. Uses candy-palette for color mapping. Delta repaint via candy-buffer. - **Pace:** `Cmd::tick()` wall-clock alignment via `Sync`, no busy-waiting. - **Audio:** `AudioPlayer` shells out to `ffplay` or `mpv --no-video` as the audio master clock. Prior art --------- [](#prior-art) SugarReel has no single upstream. Its decode → render → pace pipeline draws on three terminal-video projects, credited here: - [maxcurzi/tplay](https://github.com/maxcurzi/tplay) — Rust terminal media player. - [seatedro/glyph](https://github.com/seatedro/glyph) — edge-aware ASCII/ANSI video renderer. - [joelibaceta/video-to-ascii](https://github.com/joelibaceta/video-to-ascii) — Python video-to-ASCII player. The rendering stack is reused from the SugarCraft ecosystem rather than reinvented: [candy-mosaic](../candy-mosaic) (image → cell renderers), [candy-flip](../candy-flip) (downsampling / dithering), [candy-palette](../candy-palette)(color mapping), and [candy-core](../candy-core) (TEA runtime + frame pacing). Known limitations ----------------- [](#known-limitations) - **Audio plays at 1.0× regardless of playback speed.** Changing speed with `[`/`]` only affects video pacing. The audio companion (ffplay/mpv) always plays at normal speed. A/V will diverge noticeably when using speeds other than 1.0×. - **Seeking repositions audio but not frame-exactly.** A seek creates a new AudioPlayer at the correct offset, but the video frame timing and audio timing are only approximately synchronized (frame-skip resync keeps them close at 1.0×). - **GIF playback fills the terminal in HalfBlock mode** (each cell = 2 source rows). In text modes (ascii/ansi256/truecolor) the GIF renders at its native pixel dimensions without 2× vertical scaling. ### Health Score 20 — LowBetter than 13% of packages Maintenance65 Regular maintenance activity Popularity0 Limited adoption so far Community6 Small or concentrated contributor base Maturity11 Early-stage or recently created project Bus Factor1 Top contributor holds 100% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Community Maintainers ![](https://www.gravatar.com/avatar/b1036e0717211b8030b83cbe729e8ba6ba442fdbd5285fb97a39d7dcfe339342?d=identicon)[detain](/maintainers/detain) --- Top Contributors [![detain](https://avatars.githubusercontent.com/u/1364504?v=4)](https://github.com/detain "detain (34 commits)") ### Embed Badge ![Health badge](/badges/sugarcraft-sugar-reel/health.svg) ``` [![Health](https://phpackages.com/badges/sugarcraft-sugar-reel/health.svg)](https://phpackages.com/packages/sugarcraft-sugar-reel) ``` PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)