Pippin

pippin consumes images (png, jpeg, svg) and outputs high-resolution ASCII / UTF-8 representations to your terminal. With --animate it consumes an animated gif and re-renders every frame as text — exporting a frame directory or a self-playing text-animation gif.

Features

• Input: png, jpeg, svg (plus anything Pillow opens: bmp, gif, webp, tiff)
• Charsets: ascii, utf8, blocks (+ --custom-chars)
• Preview to terminal (ANSI truecolor optional) and export to .txt / .ansi
• Color coding of characters (foreground truecolor sampled from source)
• Contrast / brightness / invert / aspect correction
• GIF animation mode (--animate): live terminal playback, frame-directory export, and self-playing text-animation .gif re-export

Install

No Python install required: each v* tag ships self-contained single-file binaries (.github/workflows/release.yml, matrix linux-x64|osx-arm64|win-x64) attached to that tag's GitHub Release. SVG works out of the box — cairo is bundled inside the binary.

curl -fSL -o /tmp/pippin-dl/pippin-linux-x64 https://github.com/fluxion-dev/pippin/releases/download/v0.1.0/pippin-linux-x64
chmod +x /tmp/pippin-dl/pippin-linux-x64
/tmp/pippin-dl/pippin-linux-x64 --version
# 0.1.0

gh release download v0.1.0 -p 'pippin-linux-x64' -D /tmp/pippin-dl --repo fluxion-dev/pippin
chmod +x /tmp/pippin-dl/pippin-linux-x64
/tmp/pippin-dl/pippin-linux-x64 --version
# 0.1.0

Direct asset URLs (each v* tag attaches the three binaries plus the sdist/wheel):

• https://github.com/fluxion-dev/pippin/releases/download/v0.1.0/pippin-linux-x64
• https://github.com/fluxion-dev/pippin/releases/download/v0.1.0/pippin-osx-arm64
• https://github.com/fluxion-dev/pippin/releases/download/v0.1.0/pippin-win-x64.exe

Notes:

• macOS builds are arm64 (Apple silicon) only. Downloaded binaries are unsigned — on macOS run xattr -d com.apple.quarantine pippin-osx-arm64 after downloading; Windows may show a SmartScreen prompt.
• Prefer pip? pip install pippin-art (or pipx install pippin-art), then pippin --version. SVG via pip needs system cairo (see below).

From source (editable install with dev extras):

python3 -m venv .venv
source .venv/bin/activate
python -m pip install -e ".[dev]"

System deps for SVG (cairosvg needs cairo):

# Fedora
sudo dnf install cairo pango gdk-pixbuf2
# Debian/Ubuntu
sudo apt install libcairo2 libpango-1.0-0 libgdk-pixbuf2.0-0

Usage

# Preview (UTF-8 + color by default)
pippin photo.jpg

# ASCII, no color, fixed width
pippin logo.png --charset ascii --no-color --width 80

# Preview + export (ANSI escapes preserved when --color)
pippin input.svg --charset utf8 --color --width 120 --export out.ansi

# Export only (no terminal preview)
pippin input.jpg --export out.txt --no-preview

# Tweak rendering
pippin input.png --width 160 --contrast 1.2 --brightness 1.1 --invert
pippin input.png --charset blocks --custom-chars " .:-=+*#%@"

# Animate (uniform 12fps playback/encode by default)
pippin anim.gif --animate --width 100
pippin anim.gif --animate --width 100 --no-preview -o frames/        # frame_*.txt/.ansi + meta.json
pippin anim.gif --animate --width 100 --no-preview -o text_anim.gif  # self-playing text gif
pippin anim.gif --animate --native-timing --width 80                 # preserve source frame timing

CLI reference

pippin INPUT [-w WIDTH] [-H HEIGHT] [--charset {ascii,utf8,blocks} | --custom-chars STR]
             [--color | --no-color] [--preview | --no-preview]
             [-o FILE] [--invert] [--contrast F] [--brightness F] [--aspect F]
             [--animate] [--fps FPS] [--native-timing] [--max-frames N] [--sample N]
             [--loop N] [--gif-font PATH] [--gif-font-size N]

Export format: if --color is on, the export file contains ANSI escapes (.ansi-ready). With --no-color it is plain text.

Ramps

• ascii: .:-=+*#%@ (10 levels, pure 7-bit)
• utf8: `^\",:;Il!i~+_-?][}{1)(|\\/tfjrxnuvczXYUJCLQ0OZmwqpdbkhao*#MW&8%B@$ (70 levels)
• blocks: ░▒▓█ (5 levels, uniform blocks)

Notes

• SVG is rasterized via cairosvg at 3× target width, then downsampled — so vector edges stay sharp at high resolutions.
• Transparency is composited onto black (use --invert for light terminals, compositing background is fixed black for predictable luminance).
• For best quality use --width 120–240 with --charset utf8.