Sinter
Browser image compression for JPEG, PNG, WebP, AVIF, BMP, GIF, and HEIC.
---
**Sinter** is a browser-side image compression library for apps that need image
files smaller before upload, preview, or download. It takes a browser `Blob` or `File`,
applies the options you choose, and returns a compressed image `Blob`.
- JPEG, PNG, WebP, AVIF, BMP, GIF, HEIC
- Keep the input format or convert to another supported format
- Resize, quality control, and best-effort file size targeting
- Runs compression off the main UI flow in supported browsers
- Safe to import in SSR-capable apps; compression runs on the client
## Install
```bash
npm install sinter-js
```
## Basic Usage
```js
import { sinter } from "sinter-js";
const blob = await sinter()
.toFormat("webp")
.maxQuality(80)
.maxDimensions({ width: 1200 })
.compress(file);
```
Every setting returns a new pipeline, including copies of nested options. Repeated
calls replace the whole setting; options may appear in any order after format selection.
Keep the returned value when changing settings. Pipelines can be reused:
```js
const pipeline = sinter()
.toFormat("webp")
.maxQuality(80)
.maxDimensions({ width: 1200 });
const firstBlob = await pipeline.compress(firstFile);
const secondBlob = await pipeline.compress(secondFile);
```
Canvas or cropper `Blob` output works directly:
```js
const pngBlob = await new Promise((resolve, reject) => {
canvas.toBlob(blob => (blob ? resolve(blob) : reject(new Error("canvas export failed"))), "image/png");
});
const webpBlob = await sinter()
.toFormat("webp")
.maxQuality(82)
.maxDimensions({ width: 512, height: 512 })
.targetSize(500, "KB")
.compress(pngBlob);
```
## API
Start with `sinter()`, choose an output format policy, then add any compression
options before calling `compress(file)`.
```js
await sinter()
.allowFormats(["avif", "webp"], "webp")
.codecOptions({ webp: { lossless: false } })
.maxQuality(80)
.maxDimensions({ width: 1200 })
.targetSize(1, "MB")
.timeout(30)
.compress(file);
```
### Format
| Method | Description |
|--------|-------------|
| `keepFormat()` | Use the input format for the output |
| `toFormat(format)` | Encode to one output format |
| `allowFormats(allowed, fallback)` | Keep the input format when it is allowed; otherwise use `fallback` |
Supported formats:
```js
"jpeg" | "png" | "webp" | "avif" | "bmp" | "gif" | "heic"
```
### Compression
| Method | Description |
|--------|-------------|
| `codecOptions(options)` | Set encoder options for formats this pipeline can produce |
| `maxQuality(n)` | Set the maximum quality from `1` to `100` |
| `maxDimensions({ width?, height? })` | Resize within the given bounds while preserving aspect ratio |
| `targetSize(value, unit)` | Try to fit the output under a target size; `unit` must be `"KB"` or `"MB"` |
| `timeout(seconds)` | Reject if compression takes longer than the limit |
| `firstFrame()` | Extract the first composited animation frame |
| `compress(input: Blob)` | Run the pipeline and return `Promise`; `File` also works |
### Codec Options
```js
sinter()
.toFormat("avif")
.codecOptions({ avif: { speed: 4 } })
.compress(file);
```
| Format | Options |
|--------|---------|
| `jpeg` | `{ progressive?: boolean }` |
| `webp` | `{ lossless?: boolean }` |
| `avif` | `{ speed?: number }` |
| `png` | None |
| `bmp`, `gif`, `heic` | None |
## Behavior
- Input format is detected from file bytes, not the file extension.
- `targetSize()` is best effort. Some images may not fit the requested target.
- For lossy output formats, size fitting lowers quality before reducing dimensions.
- `maxQuality()` does not change BMP output quality.
- If same-format compression would make the file larger, Sinter returns the
original bytes when no resize or size target was requested. Explicit `firstFrame()`
always runs, even when its output is larger.
## Animation and quality
GIF, WebP, PNG (APNG), and AVIF preserve animations across conversion. Frames are
composited and processed sequentially; frame count, representable timing, and
finite/infinite playback semantics are retained. Missing loop metadata means one play.
APNG uses the public format name `"png"`.
`firstFrame()` selects the first composited animation frame, excluding a separate
APNG poster. JPEG, BMP, and HEIC output automatically extract that frame. Still
inputs also work with `firstFrame()`.
GIF quality controls the palette ceiling: unspecified/100 allows 256 colors;
otherwise `max(2, round(q * 256 / 100))`, including transparency. Alpha below 128
becomes transparent; other pixels become opaque. Quality 100 does not preserve
all original colors. PNG quality below 100 enables palette quantization.
HEIC quality is passed to libheif's 1–100 quality API. AVIF color and alpha share
the quality cap; `speed` remains 1–10 (default 10). Resizing never raises quality.
Size fitting evaluates the minimum quality/color candidate, up to seven search
steps, then up to eight 0.7× dimension reductions. It stops at unchanged dimensions
or one pixel. If the target cannot be met, the smallest valid observed result is
returned. WebP `lossless: true` skips lossy quality search and only reduces dimensions.
KB and MB mean 1024 and 1024² bytes. Each candidate starts from original pixels.
## Migrating from v1
This is a v2 major API change. Replace `dimensions()` with `maxDimensions()` and
`size()` with `targetSize()`; the old names are removed. Assign the result of each
setter instead of relying on mutation. Repeated `codecOptions()` calls replace
all previous codec options, and repeated `maxDimensions()` calls replace the
whole bounding box. You no longer need to wrap a `Blob` in a `File`.
## Browser And SSR
Sinter can be imported in SSR-capable apps because it does not access browser
globals at import time.
Call `compress(file)` from browser client code. Other runtimes are not part of
the public API and may reject with `SinterCodecError`.
## WASM loading
Codecs load on demand. Once the input and output formats are known, their
required modules load in parallel. No manual codec registration is needed.
| Module | Contents |
| --- | --- |
| `jpeg.wasm`, `bmp.wasm`, `webp.wasm` | Read/write support for each format |
| `gif.wasm` | GIF read/write and palette quantization |
| `png.wasm` | PNG/APNG read/write and APNG quantization |
| `avif-decoder.wasm`, `avif-encoder.wasm` | Separate AVIF read/write support |
| `heic-decoder.wasm`, `heic-encoder.wasm` | Separate HEIC read/write support |
For example, JPEG → AVIF loads only `jpeg.wasm` and `avif-encoder.wasm`.
PNG and APNG share one module. Same-file modules are reused within a job;
workers are terminated after each job, and cross-job downloads depend on HTTP
caching. Serve WASM files with suitable cache and compression headers.
Demo-only resize/quantization comparison code is excluded from the npm build.
## Errors
```js
import { SinterValidationError, SinterCodecError } from "sinter-js";
```
| Error | When |
|-------|------|
| `SinterValidationError` | Invalid input, such as an empty file or an out-of-range option |
| `SinterCodecError` | Compression failed, timed out, or ran outside the public browser API path |
## Development
Use Bun, Zig 0.16.0, Rust with the `wasm32-wasip1` target, and Emscripten 6.0.9
with CMake to build native codecs. Source archives and crate versions are pinned.
```sh
bun install
bun run assets:fetch
bun run demo
```
The gallery has 32 individually runnable cases, filters, downloads, independent
browser checks, and a separate upload tab. Large internet inputs stay in
`~/.cache/sinter/test-assets`; source, license, and hashes are in
`assets/test/sources.json`. Every gallery input is an unmodified web download;
source and license links are displayed on each row. Small internal regression fixtures are generated independently
with Pillow 12.1.1 by `scripts/generate-patterns.py`, with fixed expectations.
The diagnostics panel compares cold and warm end-to-end timings and reports
observed WASM linear-memory capacity (not whole-process or GPU memory).
## License
Sinter source is MIT. Bundled codecs retain their own licenses, including
LGPL-3.0 for libheif and libde265. See
`packages/module/THIRD_PARTY_NOTICES.md` and `licenses/` in the package.
The native sources and pinned build scripts needed to rebuild the WASM are included.
Pass an optional `{ signal: abortController.signal }` as the second argument to
`compress()` to cancel browser work and terminate its Worker. Existing one-argument
calls are unchanged. Cancellation rejects with the signal’s reason.