Skip to content

Dynamically linked libheif for nodejs. Native HEIC/HEIF image decoding and information using dynamically linked libheif.

License

Notifications You must be signed in to change notification settings

SeriousBug/libheif-node-dy

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

12 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

libheif-node-dy npm MIT

Native HEIC/HEIF image decoding and information, using dynamically linked libheif. Supports converting HEIC to JPEG, PNG, and other formats when combined with Sharp.

This package dynamically links against libheif. You must have libheif and its headers installed yourself. It is widely available on most platforms:

  • Debian, Ubuntu: libheif1 libheif-dev
  • ArchLinux, EndeavourOS: libheif
  • Alpine Linux: libheif-dev
  • MacOS (Homebrew): libheif

Once you have libheif installed, you can install this package with npm install libheif-node-dy.

Usage

const fs = require('fs');
const { decode, getInfo } = require('libheif-node-dy');
// Or, import { decode, getInfo } from 'libheif-node-dy';

// Or any other way to get your image into a Buffer
const image = fs.readFileSync('path-to.heic');
// There is more information available! Check the type definitions.
const { width, height } = getInfo(image);
const decodedImage = decode(image);

// To convert it into JPEG or PNG, use it with sharp:
const sharp = require('sharp');
const newImage = sharp(decodedImage, {
  raw: {
    height,
    width,
    channels: 4,
  },
});
newImage.jpeg().toFile("image.jpg");
// Or .toBuffer() to get a buffer to use in something else

You can also look at the benchmark/convert.js file, which is an example CLI program for converting HEIC files to JPEGs.

Performance

libheif-node-dy is around 3 to 5 times faster than heic-decode in decoding images.

4 violin plots. X axes are labeled Time (ms). First plot: Small images, about 0.6MP. libheif-node-dy averages around 80, heic-decode is between 264 and 284. Second plot: Medium images, about 2.5MP. libheif-node-dy averages around 280, heic-decode is slightly above 1039. Third plot: Large images, about 5.7MP. libheif-node-dy averages around 600, heic-decode is between 2322 and 2522. Fourth plot: Extra large images, 9.1MP to 24MP. libheif-node-dy averages around 1500, heic-decode is slightly below 7884.

Licensing

This package is licensed under MIT. libheif is licensed under LGPL, which grants an exception for dynamic linking. This package dynamically links against libheif, which should satisfy that requirement. This means you can use this package without licensing your software under GPL, so long as you don't bundle your application in a way that restricts users from being able to replace libheif.

Note that other packages like libheif-js, and thus its dependencies like heic-decode may require you to license your software under GPL if you bundle them within your application in a way that users could not replace the library. Bundlers like rollup, webpack, and others that bundle all code into one or a few files very likely will violate the LGPL exception, and will therefore require you to distribute your application under GPL, if you do distribute your application.

This is not legal advice, and I'm not a lawyer. Contact a lawyer if you have questions on how these licenses apply to your application.