@resciencelab/dither-cli

Agent-native image and video dithering from the terminal — powered by dithermark's algorithms.

Sub-second per image. No browser, no Playwright, no WebGL. Pure Node.

Install

npm i -g @resciencelab/dither-cli

Quick start

# One-shot with preset
dither apply photo.jpg -o out.png --preset gameboy

# Custom algorithm + palette + filters
dither apply photo.jpg -o out.png \
  --mode color \
  --algorithm atkinson \
  --palette ocean \
  --colors 8 \
  --color-comparison oklab \
  --brightness 110 \
  --contrast 120

# Black & white dithering
dither apply photo.jpg -o out.png --mode bw --algorithm floyd-steinberg

# Batch a folder in parallel
dither batch "shots/*.jpg" -o dithered/ --preset newsprint --concurrency 4

# Video (requires ffmpeg)
dither video in.mp4 -o out.mp4 --preset comic-book --fps 24

Showcase: 20 looks from one frame

Source image: 2001太空漫游-旋转空间站.png

Source

20-result contact sheet

Example recipes

| # | Output | Recipe | |---|---|---| | 01 | | --preset gameboy | | 02 | | --preset mac-classic | | 03 | | --preset c64 | | 04 | | --preset newsprint | | 05 | | --preset risograph | | 06 | | --preset neon | | 07 | | --mode color --algorithm ordered--bayer-16 --colors 2 --custom-colors "#0047ab,#ffffff" --color-comparison cie-lab | | 08 | | --mode color --algorithm ordered--bayer-8--hl --palette sepia --colors 6 --color-comparison hue-lightness --contrast 118 | | 09 | | --mode color --algorithm ordered--blueNoise-16--stark --palette ocean --colors 8 --color-comparison oklab --saturation 110 | | 10 | | --mode color --algorithm stucki --palette wildberry --colors 12 --color-comparison cie-lab --contrast 112 --brightness 104 | | 11 | | --mode color --algorithm xor--medium --palette mondrianchromatic --colors 8 --color-comparison rgb | | 12 | | --mode color --algorithm simplex --palette galaxy --colors 10 --color-comparison oklab-taxi --hue-rotation 18 | | 13 | | --mode bw --algorithm ordered--hatchHorizontal-4 --black-color "#111111" --white-color "#f5f1e8" --contrast 130 | | 14 | | --mode bw --algorithm adaptive-threshold --black-color "#0b1d51" --white-color "#ffffff" --blur-before 0.5 --sharpen-after 1.1 | | 15 | | --mode bw --algorithm ordered--bayer-8 --black-color "#332211" --white-color "#fff4d6" --brightness 108 --contrast 122 | | 16 | | --mode bw --algorithm atkinson --black-color "#1a1a1a" --white-color "#fdfbf5" --sharpen-before 1.2 | | 17 | | --mode color --algorithm ordered--bayer-2 --custom-colors "#000000,#0000d7,#d70000,#d700d7,#00d700,#00d7d7,#d7d700,#d7d7d7" --colors 8 --color-comparison hue --saturation 125 | | 18 | | --mode color --algorithm floyd-steinberg --custom-colors "#1b1f3b,#f7f3e9,#d7263d,#1b998b" --colors 4 --color-comparison cie-lab --contrast 120 | | 19 | | --mode color --algorithm ordered--dot-8--hl --palette lilac --colors 6 --color-comparison weighted-hsl --blur-before 0.8 --blur-after 0.3 | | 20 | | --mode color --algorithm burkes --custom-colors "#0d1b2a,#415a77,#e0e1dd,#c1121f,#ffd166" --colors 5 --color-comparison cie-xyz --sharpen-before 1.8 --contrast 125 |

Presets

10 curated presets covering classic dither aesthetics:

| Preset | Mode | Description | |--------|------|-------------| | gameboy | color | Classic Game Boy green palette, Bayer 4x4 | | mac-classic | bw | Macintosh classic 1-bit, Atkinson dithering | | c64 | color | Commodore 64 palette, Floyd-Steinberg | | gameboy-pocket | color | Game Boy Pocket grayscale, Bayer 8x8 | | comic-book | color | Halftone dots with limited palette | | newsprint | bw | Black & white halftone newspaper | | zx-spectrum | color | ZX Spectrum 8-color palette, Bayer 2x2 | | risograph | color | Risograph 3-color spot print look | | thermal-print | bw | Thermal receipt printer, horizontal hatch | | neon | color | Vibrant neon palette, Floyd-Steinberg |

dither preset list              # list all presets
dither preset inspect gameboy   # show preset details

Algorithms

30+ dither algorithms across BW and color modes:

• Error diffusion: Floyd-Steinberg, Atkinson, Stucki, Burkes, Sierra 1/2/3, Reduced Atkinson
• Ordered: Bayer 2x2/4x4/8x8/16x16, Halftone, Dot patterns
• Other: Threshold, Random, Closest Color

dither info algorithms          # list all algorithms
dither info algorithms --bw     # BW only
dither info algorithms --color  # color only

Palettes

31 built-in color palettes:

dither info palettes            # list all palettes
dither palette preview sepia    # ASCII preview
dither palette export sepia --format json  # export as JSON

Color comparison

4 color comparison methods for finding closest palette matches:

| Method | Description | |--------|-------------| | rgb | Euclidean RGB distance (default) | | luma | Weighted luma-aware distance | | lightness | HSL lightness comparison | | oklab | Perceptual OKLab distance (best quality) |

Filters

Apply pre-dither image adjustments:

dither apply photo.jpg -o out.png --preset gameboy \
  --brightness 110 \
  --contrast 120 \
  --saturation 80 \
  --pixelate 2

Config files

Save your recipe as JSON and reuse it:

{
  "name": "my-recipe",
  "mode": "color",
  "algorithm": "atkinson",
  "palette": "ocean",
  "colors": 8,
  "colorComparison": "oklab",
  "filters": {
    "brightness": 110,
    "contrast": 120,
    "saturation": 100,
    "pixelate": 1
  }
}

dither apply photo.jpg -o out.png --config my-recipe.json

Video

Requires ffmpeg on PATH. Decomposes video into frames, dithers each in parallel, recomposes.

dither video in.mp4 -o out.mp4 --preset mac-classic --fps 24 --concurrency 4

License

MIT