optiq-mcp

Try the demo · Documentation · Benchmarks

Browser-side image optimisation for uploads. For every image Optiq encodes a bounded set of candidates (MozJPEG, libwebp, libavif, oxipng — compiled to WebAssembly), measures each one, and returns the smallest output that satisfies your constraint:

• lossless — decoded pixels (including alpha) are verified identical to the input;

• visually-lossless — pixels may differ; SSIM ≥ 0.99 against the input (configurable);

• balanced (default) — SSIM ≥ 0.975, smaller search budget, faster AVIF preset.

AVIF is held to a stricter SSIM threshold than JPEG and WebP. It was calibrated against the independent SSIMULACRA2 metric, which showed SSIM is too lenient on AVIF's smoothing.

The same engine also runs in Node and powers:

• a CLI (npx optiq-image);

• a Vite plugin;

• an MCP server for AI agents (optiq-mcp, source in mcp/).

In the browser, work runs in a Web Worker; the main thread only posts a Blob and receives an ArrayBuffer. Results carry the chosen codec/settings, every candidate tried, the measured quality, warnings, fallbacks and unmet constraints.

Benchmarks: see Benchmark results and bench/results/RESULTS.md. Optiq is not uniformly better than the alternatives; the trade-offs (size vs. time vs. memory) are listed there per category.

Install

pnpm add optiq-image      # or npm / yarn

Requirements: an ES2022 browser with module Workers and WebAssembly (Chrome/Edge 80+, Firefox 114+, Safari 15+). AVIF output is only useful where your audience can decode AVIF (Chrome 85+, Firefox 93+, Safari 16.4+); remove it with autoFormats: ["jpeg", "png", "webp"] otherwise.

Bundler setup (Vite 7 and 8)

// vite.config.ts
export default defineConfig({
  worker: { format: "es" }, // codecs are loaded with dynamic import() inside the worker
  optimizeDeps: {           // dev only: pre-bundling breaks `new URL("x.wasm", import.meta.url)`
    exclude: ["optiq-image", "@jsquash/jpeg", "@jsquash/png", "@jsquash/webp", "@jsquash/avif", "@jsquash/oxipng", "@jsquash/resize"],
  },
});

webpack 5 and Parcel 2 understand new Worker(new URL("./worker.js", import.meta.url), { type: "module" }) and new URL("*.wasm", import.meta.url) natively. For anything else pass workerFactory to createCompressor. Each codec is a separate chunk, fetched on first use (AVIF ≈ 3.5 MB, others 35–350 KB).

Related MCP server: 🪄 ImageSorcery MCP

Usage

import { compressImage, isOptiqError } from "optiq-image";

const controller = new AbortController();
try {
  const result = await compressImage(file, {
    mode: "balanced",
    maxWidthOrHeight: 2560,
    signal: controller.signal,
    onProgress: (e) => console.log(e.stage, Math.round(e.progress * 100), e.bestBytes),
  });
  result.blob;            // Blob with the right MIME type (image/avif, image/webp, ...)
  result.fileName;        // "IMG_0042.webp" — extension matches the encoded bytes
  result.sizeReductionRatio, result.qualityMetric, result.codec, result.warnings;
  if (!result.constraintsMet) console.warn(result.unmetConstraints);
} catch (e) {
  if (isOptiqError(e)) console.warn(e.code, e.message); // e.g. UNSUPPORTED_FORMAT, ABORTED
  // the original `file` is untouched — upload it instead
}

React:

function useCompressed(file?: File) {
  const [state, set] = useState<{ result?: CompressionResult; error?: unknown; progress: number }>({ progress: 0 });
  useEffect(() => {
    if (!file) return;
    const ac = new AbortController();
    compressImage(file, { signal: ac.signal, onProgress: (e) => set((s) => ({ ...s, progress: e.progress })) })
      .then((result) => set({ result, progress: 1 }), (error) => !ac.signal.aborted && set({ error, progress: 0 }));
    return () => ac.abort(); // terminates the worker job
  }, [file]);
  return state;
}

For explicit control over workers use createCompressor({ maxWorkers, workerFactory, codecFallback, allowMainThread, recycleAfterPixels }).

Options

Progress stages: reading → probing → decoding → (resizing) → analyzing → encoding … → finalizing → done.

Error codes: INVALID_INPUT, UNSUPPORTED_FORMAT, MALFORMED_INPUT, INPUT_TOO_LARGE, INVALID_OPTIONS, INCOMPATIBLE_OPTIONS (e.g. JPEG requested for a transparent image), CONSTRAINTS_UNSATISFIABLE, CODEC_UNAVAILABLE, UNSUPPORTED_ENVIRONMENT, WORKER_ERROR, ABORTED (name === "AbortError").

React, CLI, Vite plugin

import { useOptiq } from "optiq-image/react";
const { status, result, progress, cancel } = useOptiq(file, { mode: "fast" });

View example (upload form with progress, cancel and S3) · React hook docs

npx optiq-image ./photos --out ./photos-optimized      # static images, in parallel worker threads

import { optiq } from "optiq-image/vite";               // optimises build output in place
export default defineConfig({ plugins: [optiq()] });

MCP server (optiq-mcp)

This repository contains an MCP server, published on npm as optiq-mcp and in the official MCP Registry as io.github.Baukaalm/optiq-mcp. Its source is in mcp/:

• mcp/src/index.ts is the implementation;

• mcp/test/ holds end-to-end tests that run it with the official MCP client;

• mcp/server.json is the registry entry.

It is a local stdio server built on the TypeScript MCP SDK, and it gives AI agents two tools for the images in a project:

claude mcp add optiq -- npx -y optiq-mcp                                    # Claude Code

{ "mcpServers": { "optiq": { "command": "npx", "args": ["-y", "optiq-mcp"] } } }

The JSON config works for Claude Desktop, Cursor and other MCP clients.

For agents that drive the CLI instead, there is an Agent Skill. The documentation site also has an llms.txt. See the agents guide.

Uploading to S3

import { compressAndUpload } from "optiq-image/upload";
const out = await compressAndUpload(file, { requestPresignedUpload: (req) => fetch("/api/presign", …).then((r) => r.json()) });

Compression is optional and never blocks the upload: if it fails or does not help, the original is uploaded. Presigned URLs must come from your backend — see docs/guide/s3.md for the contract and a backend sketch.

Supported formats

Formats are detected from file content. Extensions and MIME types are ignored (a .jpg that is a PNG is a PNG).

Guarantees and limitations

• Lossless means decoded RGBA equality, verified per candidate, for the decoder Optiq uses. JPEG decoders are not bit-exact across implementations, so “lossless” for a JPEG input is only ever a byte-level container rewrite (metadata removal), never a re-encode.

• Transparency is never dropped: JPEG is excluded when any pixel has alpha < 255.

• Orientation: EXIF orientation is applied to the pixels of re-encoded outputs (tag reset to 1) and preserved in container-level outputs.

• Colour: ICC profiles are carried into JPEG/PNG/WebP outputs. AVIF output is tagged sRGB and is not used for images with a non-sRGB profile. sRGB profiles are dropped only with preserveMetadata: false (or for AVIF output, where the nclx sRGB tag is equivalent). No colour conversion is performed.

• Metadata: kept by default. AVIF output is skipped when EXIF/XMP must be preserved (no AVIF metadata writer). With preserveMetadata: false, EXIF (including GPS), XMP, comments and trailing data are removed.

• Animation is never silently flattened.

• SSIM is a proxy for perception, not perception: it under-weights banding in smooth gradients and chroma bleeding. Validate thresholds on your own content.

• Memory: large images need several hundred MB inside the worker (see benchmarks). WASM memory is returned by terminating the worker, which happens automatically after jobs above 8 MP.

• Speed: searching costs multiple encodes. Use balanced, lower maxCandidates, searchStrategy: "fixed", or drop AVIF from autoFormats when latency matters more than bytes.

Licensing

Optiq: Apache-2.0. Bundled codecs (via jSquash, Apache-2.0 wrappers): MozJPEG (IJG + BSD-3 + zlib), libwebp (BSD-3), libavif (BSD-2) with libaom (BSD-2 + AOMedia patent licence), Rust png, oxipng, resize (MIT/Apache-2.0). All permit commercial redistribution with notices. No GPL code is included (libimagequant was rejected for that reason).

Benchmark results

The corpus has 24 images (listed in bench/corpus/manifest.json):

• 10 Kodak photos (8 JPEG q92, 2 PNG);

• 3 phone-style 12 MP JPEGs;

• 2 screenshots and 2 text graphics;

• 4 transparent illustrations;

• 3 gradients.

Measured on an Apple M4 Pro (14 cores, 24 GB), macOS arm64, Node 24.15 and headless Chromium 156. Every output was decoded with the same decoders and scored against the input twice:

• with SSIM, the metric Optiq uses to choose outputs, so it favours Optiq;

• independently with SSIMULACRA2 (libjxl's ssimulacra2), a perception-tuned metric that Optiq never sees.

On the SSIMULACRA2 scale, 90 is very high (indistinguishable at 1:1), 80 is high, 70 is medium and 50 is low. Full tables and per-image rows are in bench/results/RESULTS.md.

Perceptual, all 24 images (Node; same encoders as the browser)

Browser (Chromium), against browser-image-compression 2.0.2 and canvas

What the numbers say:

• balanced vs WebP 0.8. Files are 19% smaller with about the same SSIMULACRA2 (median 79.4 vs 78.5–78.6). Per image, balanced is smaller and scores higher on 11/24, and is never worse on both. The other 13 are trade-offs.

• visually-lossless vs WebP 0.8. About the same total size (6.70 vs 6.50 MB) at clearly higher quality: median 85.8 vs 78.6, and 19/24 images at 80+ vs 6/24.

• AVIF q50 is much smaller, at lower quality (median 71.2). Whether that trade is right is a product decision. Optiq spends bytes to stay above its threshold.

• An earlier version claimed more than the data supports. It said "24/24 meet SSIM 0.975 vs 18/24 for WebP 0.8". SSIMULACRA2 showed that SSIM was too lenient on AVIF: balanced then had a median of 73.9, below WebP 0.8. AVIF is now held to a stricter SSIM threshold, calibrated against SSIMULACRA2 on 91 held-out images (modes). That costs +2.7% bytes in balanced.

• Gradients remain the weak spot. They score 64–72 in every Optiq mode and for every codec, because SSIM under-rates banding.

• Category matters.

  • Screenshots: −89.7% vs −62.8% for WebP q80.

  • Text: −91.8% vs −46.6% (lossless WebP and screen-content encodes win there).

  • Large 12 MP phone photos: −41.5% with metadata kept, −43.8% without, vs −30.7% for WebP q80.

• Optiq is slow and memory-hungry by comparison. It runs several encodes plus decodes and quality checks per image.

  • Typical: 1–4 s per image, 3–5 s for 12 MP photos.

  • Worst case, a 5 MP dashboard screenshot: 17 s in balanced, 48 s in visually-lossless.

  • Memory: median peak RSS ≈ 300 MB, up to 1.1 GB.

  • Single canvas/libvips encodes take 5–800 ms.

  • Work runs in a worker, so the UI stays responsive (max main-thread gap 11 ms during a 12 MP job).

Lossless (sc-lossless, Node): pixel-exact on 24/24 and never larger than the input (total −20.4%). PNG photos −27% (oxipng), screenshots −76% and text −91% (about the same as libvips lossless WebP effort 6), transparent illustrations −42% and gradients −66%, where libvips PNG max compression reached −60% / −76% but its outputs were not pixel-exact against the reference. JPEG inputs: only metadata can be removed losslessly (0% with the default preserveMetadata: true; no jpegtran in this build).

Development

Toolchain: Node ≥ 20 (tested with 24.15), pnpm 11, Playwright Chromium (pnpm exec playwright install chromium chromium-headless-shell). No Rust toolchain is required: all WASM comes prebuilt from pinned jSquash packages.

pnpm install
pnpm typecheck
pnpm test             # unit + integration tests in Node (real WASM codecs)
pnpm test:browser     # builds, bundles a consumer page with Vite, runs it in Chromium (incl. CSP/no-WASM fallback)
pnpm test:demo        # demo end-to-end (light/dark/mobile): compress → presign → PUT to mock S3
pnpm pack:check       # pack the tarball, install it in a fresh Vite app, typecheck, build, run (does not publish)
pnpm demo             # React + HeroUI demo with a mock presigned-S3 backend
pnpm docs:dev         # VitePress documentation site
pnpm bench:corpus     # download/render the benchmark corpus (24 images)
pnpm bench:node       # Optiq vs libvips (sharp), with peak RSS per run
pnpm bench:browser    # Optiq vs browser-image-compression and canvas, in Chromium
pnpm bench:report     # writes bench/results/RESULTS.md

Documentation site (guides, API reference generated from the TSDoc comments, benchmarks, architecture): pnpm docs:dev, or read the Markdown in docs/. Design notes: docs/architecture.md.