node-libwebp

A comprehensive Node.js wrapper for the libwebp library, providing easy access to all WebP tools including cwebp, dwebp, gif2webp, img2webp, webpmux, webpinfo, vwebp, and animation utilities.

Installation

npm install node-libwebp

Note: This package requires WebP binaries to be installed on your system, or you can install the libwebp-static package for bundled binaries:

npm install libwebp-static

Usage

const WebP = require('node-libwebp');
const webp = new WebP();

Available Tools

cwebp - Convert images to WebP

Convert PNG, JPEG, TIFF, or other images to WebP format.

// Basic conversion
webp.cwebp('input.png', 'output.webp');

// With grouped options
webp.cwebp('input.jpg', 'output.webp', {
    quality: 80,
    preset: 'photo',
    compression: {
        method: 4,
        size: 50000
    },
    lossy: {
        sns: 70,
        filter: 50,
        autoFilter: true
    },
    lossless: {
        enabled: false,
        nearLossless: 60
    }
});

// Advanced grouped options
webp.cwebp('input.png', 'output.webp', {
    quality: 90,
    alpha: {
        quality: 95,
        filter: 'fast',
        exact: true
    },
    crop: { x: 10, y: 10, width: 200, height: 200 },
    resize: { width: 300, height: 300 },
    compression: {
        method: 6,
        segments: 4
    },
    logging: {
        verbose: true,
        progress: true,
        printPsnr: true
    }
});

dwebp - Convert WebP to other formats

Convert WebP images to PNG, JPG, BMP, TIFF, PAM, PPM, PGM, or YUV.

// Basic conversion
webp.dwebp('input.webp', 'output.png');

// With grouped options
webp.dwebp('input.webp', 'output.jpg', {
    format: 'ppm',
    crop: { x: 0, y: 0, width: 100, height: 100 },
    resize: { width: 200, height: 200 },
    dither: {
        strength: 50,
        alpha_dither: true
    },
    decoding: {
        mt: true,
        nofancy: false,
        nofilter: false
    },
    output: {
        flip: true,
        alpha: true,
        verbose: true
    }
});

gif2webp - Convert GIF to WebP

Convert GIF animations to WebP format.

// Basic conversion
webp.gif2webp('animation.gif', 'animation.webp');

// With grouped options
webp.gif2webp('animation.gif', 'animation.webp', {
    compression: {
        quality: 75,
        lossy: true,
        method: 4,
        mixed: false
    },
    keyFrame: {
        kmin: 3,
        kmax: 5
    },
    processing: {
        mt: true,
        metadata: 'xmp',
        loopCompatibility: true
    },
    logging: {
        verbose: true,
        quiet: false
    }
});

img2webp - Create animated WebP from image sequence

Create animated WebP files from a sequence of images.

// Basic animation
const frames = [
    'frame1.png',
    'frame2.png',
    'frame3.png'
];
webp.img2webp(frames, 'animation.webp');

// With frame-specific and grouped options
const framesWithOptions = [
    { file: 'frame1.png', options: { duration: 100, lossless: true } },
    { file: 'frame2.png', options: { duration: 200, lossy: true, quality: 80 } },
    { file: 'frame3.png', options: { duration: 150 } }
];

webp.img2webp(framesWithOptions, 'animation.webp', {
    animation: {
        loop: 0, // infinite loop
        verbose: true
    },
    compression: {
        mixed: true,
        nearLossless: 80,
        sharpYuv: true
    },
    keyFrame: {
        kmin: 5,
        kmax: 15
    }
});

webpmux - Manage WebP animations and metadata

Manipulate WebP files, extract/add metadata, create animations, and more.

// Get information about a WebP file
const info = webp.webpmux.info('animation.webp');
console.log(info);

// Extract metadata
webp.webpmux.get('exif', 'input.webp', 'metadata.exif');
webp.webpmux.get('icc', 'input.webp', 'profile.icc');
webp.webpmux.get('frame', 'animation.webp', 'frame2.webp', 2);

// Set metadata
webp.webpmux.set('exif', 'metadata.exif', 'input.webp', 'output.webp');
webp.webpmux.set('icc', 'profile.icc', 'input.webp', 'output.webp');
webp.webpmux.set('loop', 5, 'animation.webp', 'output.webp');

// Strip metadata
webp.webpmux.strip('exif', 'input.webp', 'output.webp');

// Create animation from WebP frames
const frames = [
    { 
        file: 'frame1.webp', 
        duration: 100,
        x: 0, 
        y: 0,
        dispose: 0,
        blend: true
    },
    { 
        file: 'frame2.webp', 
        duration: 200,
        x: 10, 
        y: 10
    }
];

webp.webpmux.createAnimation(frames, 'animation.webp', 0, {
    a: 255, r: 255, g: 255, b: 255 // background color
});

// Change frame durations
webp.webpmux.changeDuration('animation.webp', 'output.webp', 150); // all frames
webp.webpmux.changeDuration('animation.webp', 'output.webp', 300, 2, 4); // frames 2-4

webpinfo - Display WebP file information

Get detailed information about WebP files.

// Basic info
const info = webp.webpinfo('image.webp');
console.log(info);

// Multiple files with grouped options
const info = webp.webpinfo(['image1.webp', 'image2.webp'], {
    analysis: {
        summary: true,
        bitstreamInfo: true,
        diag: true
    },
    output: {
        quiet: false
    }
});
console.log(info);

vwebp - View WebP files

Open WebP files in a viewer (requires GUI environment).

// Basic viewer
webp.vwebp('image.webp').then(() => {
    console.log('Viewer closed');
});

// With grouped options
webp.vwebp('image.webp', {
    decoding: {
        mt: true,
        nofancy: false,
        noicc: false
    },
    display: {
        info: true,
        dither: 75
    }
}).then(() => {
    console.log('Viewer closed');
}).catch(error => {
    console.error('Viewer error:', error);
});

Animation utilities

// Dump animation frames with grouped options
const frames = webp.anim_dump('animation.webp', {
    output: {
        folder: './frames',
        prefix: 'frame_'
    }
});

// Compare two animations with grouped options
const diff = webp.anim_diff('animation1.webp', 'animation2.webp', {
    comparison: {
        verbose: true,
        raw: false
    }
});
console.log(diff);

API Reference

CWebpOptions

Group	Option	Type	Description	Default
Basic	quality	number	Quality factor (0-100)	75
Basic	preset	string	Preset: default, photo, picture, drawing, icon, text	-
lossless	enabled	boolean	Use lossless compression	false
lossless	nearLossless	number	Near-lossless preprocessing (0-100)	100
lossless	level	number	Lossless compression level (0-9)	-
compression	method	number	Compression method (0-6)	4
compression	size	number	Target size in bytes	-
compression	psnr	number	Target PSNR (in dB)	-
lossy	sns	number	Spatial noise shaping (0-100)	50
lossy	filter	number	Filter strength (0-100)	60
lossy	autoFilter	boolean	Auto-filter optimization	false
alpha	quality	number	Alpha compression quality (0-100)	100
alpha	filter	string	Alpha filtering: none, fast, best	-
crop	x, y, width, height	number	Crop coordinates and dimensions	-
resize	width, height	number	Resize dimensions	-
logging	verbose	boolean	Print extra information	false
logging	progress	boolean	Show encoding progress	false

DwebpOptions

Group	Option	Type	Description	Default
Basic	format	string	Output format: png, ppm, bmp, tiff, pgm, yuv	png
crop	x, y, width, height	number	Crop coordinates and dimensions	-
resize	width, height	number	Resize dimensions	-
dither	strength	number	Dithering strength (0-100)	-
dither	alpha_dither	boolean	Use alpha dithering	false
decoding	mt	boolean	Use multi-threading	false
decoding	nofancy	boolean	Disable fancy upscaling	false
output	flip	boolean	Flip image vertically	false
output	alpha	boolean	Save alpha channel	false
output	verbose	boolean	Print extra information	false

Error Handling

All methods throw errors when operations fail:

try {
    webp.cwebp('input.png', 'output.webp', { quality: 90 });
} catch (error) {
    console.error('Conversion failed:', error.message);
}

Requirements

Node.js 8.0 or higher
WebP binaries installed on system OR libwebp-static package
For vwebp: GUI environment (X11, Windows, macOS)

License

MIT

Contributing

Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.

caed0/node-libwebp