ditherer

Browser-based image and video creation for dithering, palette reduction, glitch art, print simulation, temporal effects, and filter-chain experimentation.

Audio-reactive too: drive visuals with live microphone or tab audio through per-filter, chain-wide, and screensaver patch panels.

Also useful for lightweight VJing and live visuals too: swap sources, keep output framing stable, and drive filters from live audio.

Live Site · Gallery

What it does

• Build filter chains in the browser and reorder them with drag and drop
• Process still images or video clips with realtime preview
• Route live audio metrics into filter parameters with per-filter, chain-wide, or screensaver patch panels
• Share looks through URL state or exported JSON
• Export processed output as images, GIFs, or video
• Explore a large built-in library of filters, palettes, and curated presets

Highlights

• 300+ registered filter entries spanning dithering, color, stylize, distort, glitch, blur, temporal, simulation, and analysis workflows
• Image-driven raymarching and tracing with heightfield relief, silhouette extrusion, voxel terrain, refractive glass, relief reflections, volumetric light, SDF melting, 3D fractal portals, and a progressively accumulated path-traced diorama
• Raymarched worlds and optical materials including luminance caverns, gravitational lensing, thin-film color, subsurface scattering, cone-traced occlusion, spectral prisms, recursive portal halls, fossils, cloud sculpture, and a connected procedural maze
• 129 curated chain presets for looks like VHS pause, cyberpunk, lo-fi webcam, CRT, print, anime, and glitch-art variants
• Temporal pipeline with previous-frame input/output buffers, EMA history, and frame index injection for motion- and persistence-based effects
• Worker offload for non-temporal chains so the UI stays responsive
• Gamma-correct pipeline with optional linear-light processing
• Palette tooling including built-in retro/art palettes plus adaptive and extracted palettes
• Audio-reactive modulation with microphone or tab audio input, auto-generated mappings, and draggable patch panels
• WASM + WebGL2 acceleration for the heavier filters, with a shared packages/ditherer-filters/src/gl/ pipeline (single context, pooled textures, JS-y sampling helpers) so new ports only need a shader + orchestration. Current consumers: rgbStripe (GL + WASM), Gaussian Blur (GL + WASM), Facet (WASM, 140× over JS via spatial-grid Voronoi), Bit Crush (WASM LUT), plus older WASM filters (Floyd-Steinberg, Ordered, Quantize, Levels, etc.). Each backend can be toggled from the settings pane; filters fall through cleanly on unsupported devices or when the palette isn't shader-portable
• Rich export flows for PNG, JPEG, WebP, GIF, frame sequences, WebM, and browser-dependent MP4 recording paths
• Static gallery generation from the live filter/preset registries

Audio Viz

Ditherer can drive filter parameters from live audio analysis. You can patch metrics like level, bass, beat, spectral flux, or tempo phase into numeric filter controls either per filter, across the whole chain, or in screensaver mode.

• Use microphone or tab/system audio as the source
• Auto-generate musical mappings with Auto Viz and Reroll
• Reuse modulation at the chain level or target a single filter for more surgical control
• Let screensaver mode auto-refresh its routing as the active chain changes

Examples

Representative animated previews from the generated gallery:

• Video Feedback
• Floyd-Steinberg
• Cyberpunk preset
• Traffic Trails preset

Gallery

• Browse the generated gallery in docs/gallery/GALLERY.md
• Regenerate gallery previews with npm run gallery

Filter library

The React-independent browser engine is prepared for distribution through GitHub Packages as @gyng/ditherer-filters; source and authenticated install instructions live in packages/ditherer-filters. It exports the catalog, option metadata, palettes, Canvas2D/WebGL/WASM runtime, stateful temporal sessions, capability checks, and a worker entry point.

import { createFilterSession } from "@gyng/ditherer-filters";

const session = createFilterSession([
  { id: "mono", filter: "Grayscale" },
  { id: "dither", filter: "Floyd-Steinberg" },
]);

const { canvas } = await session.process(inputCanvas);
outputContext.drawImage(canvas, 0, 0);
session.dispose();

Build and validate the distributable package with npm run build:lib and npm run test:lib. The initial package target is modern browser bundlers and accepts HTMLCanvasElement or OffscreenCanvas input.

Development

npm install
npm run dev
npm run build
npm run preview
npm run lint
npm run typecheck
npm run test

Extra repo utilities:

• npm run bench to run performance benches
• npm run bench:compare to compare benchmark runs
• npm run report:presets to find duplicate or highly similar presets
• npm run gallery to regenerate docs/gallery/GALLERY.md and preview assets

Build output and deployment

npm run build writes a static build to build/. The app uses base: "./" in Vite, so the output can be hosted from a subdirectory or copied to a static host without extra routing setup.

Architecture and contributing

• AGENTS.md covers architecture, filter registration, the temporal pipeline, and contribution expectations
• packages/ditherer-filters/src/filters/index.ts is the registry for filter metadata and worker-visible entries
• packages/ditherer-filters/src/runtime.ts owns reusable chain execution and temporal state
• src/context/FilterContext.tsx connects the library runtime to React, sharing, audio modulation, previews, and worker orchestration
• docs/plan/ contains numbered implementation plans