icodec

icodec

Image encoders & decoders built with WebAssembly.

Module	Encoder	Decoder
jpeg	MozJPEG
png	OxiPNG + imagequant	image-png
qoi	qoi
webp	libwebp
heic	libheif + x265	libheif + libde265
avif	libavif + aom
jxl	libjxl
wp2	libwebp2

[!WARNING] Since libheif does not support specify thread count for x265 encoder, The encode of the heic module only work on webworker, and has performance issue.

Usage

Requirement: The target environment must support WebAssembly SIMD.

pnpm add icodec

Use in browser:

// All codec modules (see the table above) are named export.
import { avif, jxl } from "icodec";

const response = await fetch("https://raw.githubusercontent.com/Kaciras/icodec/master/test/snapshot/image.avif")

// This should be called once before you invoke `decode()`
await avif.loadDecoder();

// Decode AVIF to ImageData.
const image = avif.decode(await response.arrayBuffer());

// Encode the image to JPEG XL, also need to load the encoder WASM first.
await jxl.loadEncoder();

/*
 * The image parameter must have properties:
 * {
 *     width: number;
 *     height: number;
 *     data: Uint8Array | Uint8ClampedArray;
 * }
 */
const encoded = jxl.encode(image, /*{ options }*/);

Type of each codec module:

/**
 * Provides a uniform type for codec modules that support encoding.
 *
 * @example
 * import { wp2, ICodecModule } from "icodec";
 *
 * const encoder: ICodecModule<wp2.Options> = wp2;
 */
interface ICodecModule<T = any> {
  /**
   * The default options of `encode` function.
   */
  defaultOptions: Required<T>;

  /**
   * The MIME type string of the format.
   */
  mimeType: string;

  /**
   * File extension (without the dot) of this format.
   */
  extension: string;

  /**
   * Load the decoder WASM file, must be called once before decode.
   *
   * @param source If pass a string, it's the URL of WASM file to fetch,
   *               else it will be treated as the WASM bytes.
   * @return the underlying WASM module, which is not part of
   *               the public API and can be changed at any time.
   */
  loadDecoder(source?: WasmSource): Promise<any>;

  /**
   * Convert the image to raw RGBA data.
   */
  decode(input: Uint8Array): ImageData;

  /**
   * Load the encoder WASM file, must be called once before encode.
   *
   * @param source If pass a string, it's the URL of WASM file to fetch,
   *               else it will be treated as the WASM bytes.
   * @return the underlying WASM module, which is not part of
   *               the public API and can be changed at any time.
   */
  loadEncoder(source?: WasmSource): Promise<any>;

  /**
   * Encode an image with RGBA pixels data.
   */
  encode(image: ImageDataLike, options?: T): Uint8Array;
}

The png module export extra members:

/**
 * Reduces the colors used in the image at a slight loss, using a combination
 * of vector quantization algorithms.
 *
 * Can be used before other compression algorithm to boost compression ratio.
 */
function reduceColors(image: ImageDataLike, options?: QuantizeOptions): Uint8Array;

To use icodec in Node, just change the import specifier to icodec/node, and loadEncoder/loadDecoder will use readFileSync instead of fetch.

import { avif, jxl } from "icodec/node";

If your bundler requires special handing of WebAssembly, you can pass the URL of WASM files to load* function. WASM files are exported in the format icodec/<codec>-<enc|dec>.wasm.

import { avif, jxl } from "icodec";

// Example for Vite
import AVIFEncWASM from "icodec/avif-enc.wasm?url";
import JxlDecWASM from "icodec/jxl-dec.wasm?url";

await avif.loadDecoder(AVIFEncWASM);
await jxl.loadEncoder(JxlDecWASM);

Contribute

To build WASM modules, you will need to install:

• Cmake >= 3.24
• Rust & wasm-pack
• Emscripten
• Perl
• Git
• A proper C/C++ compiler toolchain, depending on your operating system

Run the build script:

node build.js

TODOs:

• Could it be possible to remove HEIC & VVIC encoder dependency on pthread, or limit the number of threads?
• Cannot specify vvenc & vvdec paths for libheif build.

Rnn tests:

pnpm exec tsc
node --test test/test-*.js

Start web demo:

node start-demo.js