webp-wasm v1.0.4

Overview

webp-wasm is a module for encoding and decoding WebP images using WebAssembly. It borrows the WebP codecs from Squoosh, an open-source web app made by Chrome Labs, but it is built specifically for Node.js. Note that this will not be as fast as native C++ bindings to libwebp, but it's still very fast.

WebP image files are decoded to RGBA pixel buffers, similar to the browser ImageData structure. Likewise, when encoding pixels back to WebP, an ImageData-like object is expected, with an RGBA pixel buffer (Uint8ClampedArray). This is designed to interoperate with libraries such as node-canvas.

Please note that webp-wasm ships with WebAssembly components copied from Squoosh, which is open source and has an Apache 2.0 license.

Features

• Encode and decode WebP images, with full support for alpha transparency.
• Dynamic loading of WebAssembly modules on first use, or by manually calling load().
• Lots of available options for encoding.
• No memory leaks.

Usage

Use npm to install the module:

npm install webp-wasm

Here is a simple usage example:

const fs = require('fs/promises');
const webp = require('webp-wasm');

let buffer = await fs.readFile('my-image.webp');
let imgData = await webp.decode(buffer);
console.log(imgData);

This would output something like:

ImageData {
  data: Uint8ClampedArray(809600) [ ... ],
  width: 550,
  height: 368
}

And here is an example of encoding the pixel data back to WebP:

let buffer = await webp.encode(imgData, { quality: 75 });
await fs.writeFile('my-new-image.webp', buffer);

node-canvas

Here is an example of reading and writing a WebP image using webp-wasm and node-canvas:

const fs = require('fs/promises');
const { createCanvas, createImageData } = require('canvas');
const webp = require('webp-wasm');

(async function() {
	// load WebP file from disk into buffer
	let inBuf = await fs.readFile('my-image.webp');
	
	// decode WebP into RGBA pixels (ImageData)
	let image = await webp.decode(inBuf);
	
	// create canvas and 2d context
	let canvas = createCanvas( image.width, image.height );
	let context = canvas.getContext('2d');
	
	// convert to node-canvas native ImageData object (it's strict about this)
	let imgData = createImageData(image.data, image.width, image.height);
	
	// render pixels onto canvas
	context.putImageData( imgData, 0, 0 );
	
	// draw something else on top, just to show we can
	context.save();
	context.translate(160, 160);
	context.beginPath();
	context.lineWidth = 14;
	context.strokeStyle = '#325FA2';
	context.fillStyle = '#eeeeee';
	context.arc(0, 0, 142, 0, Math.PI * 2, true);
	context.stroke();
	context.fill();
	context.restore();
	
	// extract modified pixels from canvas
	let finalImgData = context.getImageData(0, 0, image.width, image.height);
	
	// compress back to WebP
	let outBuf = await webp.encode(finalImgData, { quality: 75 });
	
	// save final WebP to disk
	await fs.writeFile('my-new-image.webp', outBuf);
})();

API

load

The WebP WebAssembly code is automatically loaded from disk and compiled on the first call to encode() or decode(). However, if you want more control over this process, you can await load() at any time. This will load both the encoder and decoder WASM modules, making them ready for use. Example:

const webp = require('webp-wasm');

await webp.load();

Note: This is an asynchronous function, so it needs to be awaited, or promised. It also supports classic callbacks, if that's your thing.

decode

The decode() function decodes a WebP file into pixels. Specifically, it takes a Buffer or ArrayBuffer, and produces an ImageData object, containing the RGBA pixels and image dimensions. Example use:

const webp = require('webp-wasm');

let imgData = await webp.decode(buffer);

The resulting object will have the following properties:

Note: This is an asynchronous function, so it needs to be awaited, or promised. It also supports classic callbacks, if that's your thing.

encode

The encode() function encodes an image into WebP format. Specifically, it takes an ImageData object containing RGBA pixels and image dimensions, an object containing encoder options, and produces a WebP binary Buffer suitable for writing to a .webp file. Example:

const webp = require('webp-wasm');

let buffer = await webp.encode(imgData, { quality: 75 });

The options object has the following defaults, which you can override selectively on each call:

Note: This is an asynchronous function, so it needs to be awaited, or promised. It also supports classic callbacks, if that's your thing.

Caveats

Unfortunately, the Squoosh WebP decoder requires a global ImageData object definition, as it was originally written for use in browsers. Since Node.js doesn't provide one of these, we automatically polyfill one for you:

class ImageData {
	constructor(data, width, height) {
		this.data = data;
		this.width = width;
		this.height = height;
	}
}
if (!("ImageData" in global)) global.ImageData = ImageData;

This class must exist in the global object, but we only add it if it doesn't already exist (i.e. futureproofing -- one day Node.js may add this natively).

Development

To install webp-wasm for development, run these commands:

git clone https://github.com/jhuckaby/webp-wasm.git
cd webp-wasm
npm install

To pull down the latest WebP WebAssembly code from Squoosh, run the build script:

npm run build

License

The MIT License (MIT)

Copyright (c) 2023 - 2024 Joseph Huckaby and PixlCore.

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Also see the Squoosh license.