inkcat

cat, but for pictures. Draws images and animated GIFs in your terminal in 24-bit colour.

inkcat photo.jpg
inkcat party.gif

Animated GIFs and WebPs play in place at their own speed until you press Ctrl-C. Stills are drawn once and hand the prompt straight back.

Using it

By default the picture fills your terminal's current width, so a wide window gets a big picture and a split pane gets a small one. Everything else is a knob you can turn:

inkcat photo.jpg -w 40           # 40 columns instead of the full width
inkcat logo.png -m ascii         # coloured ASCII rather than half-blocks
inkcat party.gif --fps 20        # ignore the GIF's timing, run at 20fps
inkcat party.gif --loops 3       # play three times, then exit
inkcat party.gif --still         # just the first frame
inkcat cat.png -o cat.txt        # save the art, then `cat cat.txt` later

| Option | Default | What it does | | --- | --- | --- | | -w, --width <n> | your terminal's width | columns to draw in, up to 300 | | -m, --mode <name> | blocks | blocks, ascii or solid | | -q, --quantize <n> | 1 (exact colour) | round colours to steps of n, for smaller files | | --fps <n> | the GIF's own timing | animation speed | | --loops <n> | runs until Ctrl-C | stop after n loops | | --still | off | draw only the first frame | | -o, --out <file> | — | write to a file instead of the screen |

Piping works the way you'd hope. inkcat photo.jpg | less -R pages it, and piping an animation gives you the first frame rather than thousands of frames of escape codes.

The three modes

blocks packs two pixel rows into every character using ▀, painting one colour on the glyph and another behind it. That's twice the vertical resolution of the other modes and the closest thing to a real picture. Use it unless you want the art to obviously look like text.

ascii picks a character by brightness ( .:-=+*#%@) and colours it. Reads as classic ASCII art and survives a projector.

solid fills each cell with a background colour and no glyph at all. Cleanest colour, least detail, and it copies and pastes without stray characters.

In your own code

import { loadArt } from 'inkcat';

const art = await loadArt('party.gif', { width: 100, mode: 'blocks' });
// { frames, delays, rows, cols, animated, format }
process.stdout.write(art.frames[0]);

frames are strings you can write straight to a terminal. To animate, write a frame, then \x1b[<rows>A\r to walk the cursor back to the top-left before the next one.

Things worth knowing

Colour. Needs a terminal with 24-bit colour, which every current one has. On Windows use Windows Terminal, not the old console host.

Fonts. blocks mode needs ▀ and ▄ in your font. Almost every monospace font has them; if you see blank cells, try -m ascii.

Formats. Anything sharp reads: PNG, JPEG, GIF, WebP, AVIF, TIFF, SVG. Transparency is respected — transparent pixels leave your terminal background showing through instead of turning black.

Size. Animations are capped at 240 frames, and every frame is rendered up front, so playback costs nothing once it starts. Saved files are large because truecolor is verbose; -q 16 shrinks them by about a third with no visible difference.

Licence

MIT