Skip to content

Codec Guide

Dus Mamud edited this page Nov 9, 2026 · 1 revision

Codec Guide

Every codec is its own package with its own lazily loaded WASM — install one, pay for one. Sizes below are the measured 1.0.x artifacts.

Package Engine Encode Decode WASM size (enc / dec) Pick it when
@dusrel/image-jpeg MozJPEG 4.1.5 Yes Yes ~410 KB / ~167 KB You need the best JPEG — progressive output, proper chroma control
@dusrel/image-webp libwebp 1.6.0 Yes Yes ~265 KB / ~126 KB Modern default: lossy + lossless + alpha in one format
@dusrel/image-avif libaom 3.12.1 + libavif 1.4.2 Yes Yes ~3.40 MB / ~3.47 MB Smallest photos; quality is worth the bigger download (lazy, cached)
@dusrel/image-png Rust png 0.18.1 Yes Yes ~113 KB / ~142 KB Lossless PNG without the canvas encoder's limits
@dusrel/image-oxipng OxiPNG 10.2.1 Optimise — single module Squeeze an existing PNG losslessly (levels 0–6, interlace control)
@dusrel/image-jxl libjxl 0.11.2 Yes Yes ~2.29 MB / ~884 KB JPEG XL — excellent lossless and lossy, growing support
@dusrel/image-qoi Rust qoi 0.4.1 Yes Yes ~33 KB / ~35 KB Tiny lossless codec for game assets, sprites, pixel data
@dusrel/image-heic libheif 1.23.7 + libde265 1.0.15 — Yes — / ~1.15 MB Reading iPhone photos; decode-only (no encoder — HEVC encoding is patent-encumbered)
@dusrel/image-gif Rust gif 0.14.2 Yes Yes ~125 KB (single module) Animated GIF encode/decode/optimise
@dusrel/image-quantize quantizr 1.4.3 — — ~58 KB Palette quantisation — PNG-8 style savings before a PNG encode
@dusrel/image-resize Rust resize 0.8.9 — — ~158 KB Resampling quality matters (7 filters; Lanczos3 default)

Notes that save debugging time

  • Quality scales are native per codec. The core uses 0..1; codec packages use their engine's scale (MozJPEG/libwebp 1..100/0..100, AVIF 0..100 with speed 0..10, default 9). Each package's README documents its own scale.
  • AVIF speed defaults to 9 (of 10) — near-best size at a fraction of the slowest setting's time. Lower it only when bytes matter more than milliseconds.
  • Single-threaded by design. No codec needs SharedArrayBuffer, so nothing here needs COOP/COEP headers. Threaded builds were considered and rejected for embed compatibility (ADR-0006).
  • PNG interlace (Adam7) is OxiPNG's job — the Rust png encoder doesn't write interlaced files; run optimize(..., { interlace: 'on' }) when you need it.
  • HEIC is decode-only and native-first. Safari 17+ decodes HEIC itself; everywhere else the WASM build takes over transparently. The engine (libheif + libde265) is LGPL-3.0 and ships unmodified in its own package; the wrapper is MIT (ADR-0008).
  • Licence hygiene is deliberate. GPL engines were replaced, not wrapped: palette quantisation uses permissive quantizr (not libimagequant), GIF uses the Rust gif crate (not gifsicle) — so every @dusrel package stays MIT except the fenced HEIC engine.

Making a codec an output format

Register the encoder once and the format works everywhere — processImage, the pipeline, the batch engine:

import { encode } from '@dusrel/image-jxl';

await processImage(file, {
  format: 'image/jxl',
  codecs: [{ mimeType: 'image/jxl', encode: (d) => encode(d, { quality: 85 }) }],
});

Asset loading (self-hosting, CDN pinning, the Vite dev fix): Bundlers and Codec Assets.

Clone this wiki locally