heic-decode

heic-decode is a small JavaScript library that decodes HEIC/HEIF image files into raw pixel data. Given a file buffer, it returns the image’s width, height, and a Uint8ClampedArray of RGBA pixels, ready to be re-encoded to another format, drawn to a canvas, or processed further.

It handles both single-image HEIC files and multi-image containers (such as burst photos or Live Photos), exposing a decode.all() API that lets you decode each embedded image lazily to avoid exhausting memory. Under the hood it wraps the WebAssembly build of libheif, so it runs without native compilation.

What You Get

• A promise-based decode({ buffer }) returning width, height, and RGBA pixel data
• A decode.all({ buffer }) API for multi-image HEIC containers with lazy per-image decoding
• Explicit dispose() memory management for freeing decoded image resources
• A WebAssembly-backed libheif build requiring no native compilation
• A tiny dependency footprint (only libheif-js) that runs in Node.js and the browser

Common Use Cases

• Converting iPhone HEIC photos to PNG or JPEG on a server or in the browser
• Extracting raw pixel data from HEIC files for image processing pipelines
• Handling multi-image HEIC containers like burst shots without loading everything at once

Under The Hood

Architecture - The public entry point index.js loads the WebAssembly bundle of libheif-js and passes it into a factory in lib.js, which returns one (single-image decode) and all (multi-image) functions. Decoding reads the file’s brand bytes to validate it is HEIC/HEIF, then calls libheif’s display() to render each image into a pre-allocated Uint8ClampedArray of RGBA data.

Tech Stack - Plain JavaScript (CommonJS) targeting Node.js >= 8, with a single runtime dependency on libheif-js (the WASM build of the C++ libheif library). Development uses Mocha for tests, plus jimp, pngjs, and pixelmatch to validate decoded output against reference images.

Code Quality - The library is intentionally minimal, roughly two source files, with a Mocha test suite under test/ and a pretest step that generates reference images. Brand detection and memory-disposal logic are handled explicitly, and CI runs on GitHub Actions.

API Design - The API is deliberately tiny and promise-first: one function to decode the main image and one to enumerate all images, both taking a { buffer } argument and returning plain objects. The multi-image path surfaces a dispose() call so consumers manage WASM memory explicitly, which is well documented in the README.