asciiplay

Play GIFs as live ASCII animation in the terminal.

asciiplay reads every frame of an animated GIF, converts each one to ASCII art, and plays it back in your terminal at the original frame rate. Supports color output, three character ramps, braille mode (4x resolution), frame rate control, and file output.

Requirements

• Node 22+

For development: pnpm

Install

npm install -g asciiplay

Or clone and build from source:

git clone https://github.com/psandis/asciiplay.git
cd asciiplay
pnpm install
pnpm build

Quick Start

asciiplay images/nyan-cat.gif
asciiplay images/nyan-cat.gif --color
asciiplay images/nyan-cat.gif --color --loop
asciiplay images/nyan-cat.gif --braille --color --loop

Use asciiplay or aplay, both are identical. Press Ctrl+C to stop.

CLI Options

asciiplay <file> [options]
aplay <file> [options]

Run asciiplay --help at any time to see the full option list in your terminal.

| Option | Short | Default | Description | |--------|-------|---------|-------------| | --width <number> | -w | terminal columns | Output width in characters. | | --height <number> | -H | derived from aspect ratio | Output height in characters. | | --ramp <name> | -r | classic | Character ramp: classic, blocks, or dense. | | --invert | -i | off | Invert brightness mapping. | | --color | -c | off | Color output using original image colors. | | --braille | -b | off | Render in braille (2x4 pixels per character, 4x effective resolution). | | --loop | -l | off | Loop animation indefinitely. Press Ctrl+C to stop. | | --fps <number> | -f | GIF delay | Override frame rate. Range: 0.1–120. | | --output <file> | -o | | Write all ASCII frames to a file instead of playing in the terminal. | | --version | -V | | Print version and exit. | | --help | -h | | Show all options and exit. |

Usage Guide

Color

Without --color the output is grayscale: each character's brightness maps to the original pixel luminance. With --color each character is colored with the original RGB value of the corresponding pixel.

asciiplay images/nyan-cat.gif              # grayscale
asciiplay images/nyan-cat.gif --color      # full color

Color is always recommended for GIFs with rich color content.

Loop

By default the animation plays once and exits. Use --loop to repeat indefinitely.

asciiplay images/nyan-cat.gif --color --loop

Press Ctrl+C to stop. The terminal is restored (cursor shown, screen cleared) on exit.

Frame Rate

By default asciiplay uses the delay embedded in each GIF frame. Most GIFs encode this correctly. Use --fps to override when the GIF has wrong or missing timing, or when you want to slow down or speed up playback.

asciiplay images/nyan-cat.gif --color --loop             # original speed (GIF delay)
asciiplay images/nyan-cat.gif --color --loop --fps 6     # half speed
asciiplay images/nyan-cat.gif --color --loop --fps 24    # faster

--fps accepts any value between 0.1 and 120. The minimum effective delay is 16ms regardless of fps.

Ramps

The ramp controls which characters are used to represent brightness levels.

asciiplay images/nyan-cat.gif --ramp classic    # default: @ % # * + = - : . space
asciiplay images/nyan-cat.gif --ramp blocks     # block chars: █ ▓ ▒ ░ space
asciiplay images/nyan-cat.gif --ramp dense      # full printable ASCII, maximum detail

| Ramp | Characters | Best for | |------|-----------|----------| | classic | @%#*+=-:. | general use, photos | | blocks | █▓▒░ | bold, high contrast | | dense | full printable ASCII set | maximum detail |

Invert

Dark pixels map to dense characters, bright pixels to light characters. If your GIF has a dark subject on a bright background and renders mostly empty, use --invert to flip the mapping.

asciiplay images/nyan-cat.gif --invert
asciiplay images/nyan-cat.gif --invert --color

Braille Mode

--braille renders using Unicode braille patterns (U+2800–U+28FF). Each braille character covers a 2x4 pixel block instead of 1x1, giving 4x the effective resolution at the same terminal size. Works best with --color.

asciiplay images/nyan-cat.gif --braille
asciiplay images/nyan-cat.gif --braille --color --loop

Braille mode ignores --ramp. Use --invert to flip the dot threshold if the output looks mostly filled or mostly empty.

Sizing

Auto mode fills the terminal. Override width, height, or both:

asciiplay images/nyan-cat.gif --width 80             # fixed width, height from aspect ratio
asciiplay images/nyan-cat.gif --height 30            # fixed height, width from aspect ratio
asciiplay images/nyan-cat.gif --width 80 --height 30 # exact dimensions

Terminal characters are approximately 2x taller than wide. The auto height calculation divides by 2 to compensate so a square GIF renders as square in the terminal.

Output to File

Use --output to write all ASCII frames to a text file instead of playing in the terminal. The file contains every frame joined with newlines. Color output includes ANSI escape sequences.

asciiplay images/nyan-cat.gif --output nyan.txt          # grayscale frames to file
asciiplay images/nyan-cat.gif --color --output nyan.txt  # color frames with ANSI codes

File Structure

asciiplay/
├── src/
│   ├── index.ts       # CLI entry point
│   ├── convert.ts     # frame-to-ASCII: ramp and braille rendering
│   ├── decoder.ts     # GIF frame extraction via sharp
│   ├── player.ts      # animation loop, terminal control, SIGINT cleanup
│   └── ramps.ts       # character ramp definitions
├── tests/
│   └── convert.test.ts
├── scripts/
│   └── generate-fixtures.mjs
├── images/
│   └── nyan-cat.gif
├── .gitignore
├── .node-version
├── LICENSE
├── README.md
├── biome.json
├── package.json
├── pnpm-lock.yaml
├── tsup.config.ts
└── tsconfig.json

Development

git clone https://github.com/psandis/asciiplay.git
cd asciiplay
pnpm install
pnpm build
pnpm test
pnpm lint
asciiplay --help

Testing

pnpm test

11 tests covering ramp output dimensions, line width, character set validity, invert mode, braille output geometry, braille Unicode range, braille edge cases (fully dark/bright frames), and color mode.

Related

• Asciiclaw: Convert images to ASCII art
• Unasciiclaw: Convert ASCII art back to images
• Feedclaw: RSS/Atom feed reader and AI digest builder
• Dustclaw: Find out what is eating your disk space
• Driftclaw: Deployment drift detection across environments
• Dietclaw: Codebase health monitor
• Mymailclaw: Email scanner, categorizer, and cleaner
• Wirewatch: Network traffic monitor with AI anomaly detection
• OpenClaw: The open claw ecosystem

License

See MIT