ascii-animation

ASCII Animation

Render motion entirely with text characters. ASCII output is extremely lightweight, distinctive, and works in browsers (<pre>/canvas), terminals (ANSI), and over any 3D scene (Three.js AsciiEffect).

When to use

• Build terminal/CLI intros, loaders, banners, or a retro/hacker aesthetic.
• Convert an image, video frame, or 3D scene into animated ASCII.
• Add an ASCII post-effect over an existing canvas/WebGL render.
• Create generative text fields (plasma, sine waves, noise, tunnels).

Core concept: the brightness ramp

Map luminance (0..1) to a character whose ink density matches. Order characters dark-to-light. Pick the index with Math.round(lum * (ramp.length - 1)).

Common ramps (dark to light):

• Short (10): .:-=+*#%@
• Medium (16): .'\^",:;Il!i><~+_-?][}{1)(|/tfjrxnuvczXYUJCLQ0OZmwqpdbkhao*#MW&8%B@$` truncated — see table below.
• Standard 70-level (Paul Bourke), best for photos: $@B%8&WM#*oahkbdpqwmZO0QLCJUYXzcvunxrjft/\|()1{}[]?-_+~<>i!lI;:,"^`'. (reverse for dark-on-light).

Compute relative luminance from sRGB (perceptual):

const lum = (0.2126 * r + 0.7152 * g + 0.0722 * b) / 255; // 0..1

Invert when drawing dark text on a light background: lum = 1 - lum.

Character cell aspect correction (the #1 gotcha)

Monospace character cells are taller than wide — roughly 0.5 width:height. Sampling a square pixel grid produces a vertically stretched image. Correct by sampling fewer rows than columns: for a target of cols characters wide, use rows = Math.round(cols * (imgH / imgW) * fontAspect) where fontAspect ≈ 0.5. Equivalently, when drawing to an offscreen canvas, set its height to cols * aspect * 0.5.

Web rendering: <pre> vs canvas

• <pre> + textContent: simplest. One string with \n per row. Fine up to ~120×60 chars at 30fps. Set white-space: pre; font-family: monospace; line-height: 1;.
• Canvas fillText: needed for per-character color, larger grids, or 60fps. Draw each char at x * cellW, y * cellH. Faster than thousands of DOM nodes.