Library API & format

Programmatic API for embedding milli in Node / browser projects, plus the binary .milli format spec.

• Library API
• .milli format
• Supported inputs

Library API

milli ships a programmatic API for embedding in Node apps:

import { AsciiPlayer } from '@amansingh-afk/milli';

const p = await AsciiPlayer.load('./logo.milli');

// fullscreen playback with auto-cleanup on Ctrl+C
await p.play({ loop: true, fps: 30 });

// or drive manually (for custom scheduling):
const t0 = Date.now();
setInterval(() => {
  const ansi = p.renderAnsiAt(Date.now() - t0); // time-based, loop-aware
  process.stdout.write(ansi);
}, 33);

// or pull raw cells for your own renderer:
const grid = p.frame(0); // grid[y][x] = { glyph: 'X', fg: [r,g,b], bg: [r,g,b] }

Lower-level exports (engine, format, renderers):

import {
  frameToCells, fitGrid,                 // engine: pixel data → cells
  encodeMilli, decodeMilli, frameToGrid, // format: .milli encode/decode
  cellsToAnsi, cellsToAnsiDiff,          // ANSI rendering
  play,                                  // fullscreen player
} from '@amansingh-afk/milli';

Browser subpath

For browser / React projects use the /web subpath — Node-only modules (sharp, node:fs) are excluded:

import { decodeMilli, frameToGrid } from '@amansingh-afk/milli/web';

See recipes.md#react--web-embed for a worked React example.

.milli format

Compact animated ASCII format, optimized for instant playback:

• Keyframe + delta — every Nth frame is a full snapshot; intermediate frames store only changed cells (40% change threshold). Typical ~30-70% smaller than JSON.
• Glyph dedupe — shared glyph table across all frames
• Gzipped — pako deflate for an extra ~30% on top
• Self-describing — version, width, height, delays, loop flag baked in
• Zero runtime deps — decoder is pure JS, no sharp needed

Use cases:

• Ship a pre-baked splash with your CLI (require('my-cli/splash.milli'))
• Load-once, play-many (web apps, TUIs)
• Network-friendly (small over the wire)

Supported inputs

Backed by sharp for image decoding:

Format	image	play	convert	export
PNG	✓	-	✓	✓
JPEG	✓	-	✓	✓
WebP (animated)	✓	✓	✓	✓
GIF	✓	✓	✓	✓
APNG	✓	✓	✓	✓
TIFF	✓	-	✓	✓
AVIF / HEIF	✓	-	✓	✓
SVG (rasterized)	✓	-	✓	✓
.milli	-	✓	-	-

Video (mp4/webm) is planned — for now, extract frames with ffmpeg -i input.mp4 -r 12 frames/%04d.png and process each.