Repository navigation
Codec Guide
Dus Mamud edited this page Nov 9, 2026
·
1 revision
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) |
-
Quality scales are native per codec. The core uses
0..1; codec packages use their engine's scale (MozJPEG/libwebp1..100/0..100, AVIF0..100withspeed0..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
pngencoder doesn't write interlaced files; runoptimize(..., { 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
gifcrate (not gifsicle) — so every@dusrelpackage stays MIT except the fenced HEIC engine.
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.
Released under the MIT License · © 2026 Dus Mamud · A Dusrel project · The HEIC engine (libheif/libde265) is LGPL-3.0, fenced to @dusrel/image-heic · Docs · Playground
Start here
Reference
Project
Elsewhere