libheif

README

go-libheif

GoLang wrapper for the libheif library, providing easy-to-use APIs for HEIC to JPEG/PNG conversions and vice versa (Also provides support for AVIF to JPEG/PNG conversions). This package was originally developed to support the php-heic-to-jpg package, which had problems while converting some HEIF images.

Implementation:

• For a swift start, consider browsing our quickstart guide on Medium.
• If you're primarily interested in a hassle-free image conversion tool, we have already integrated this module into a Command Line Interface (CLI) application and a docker image, available here.

Prerequisites

You need to install libheif before using this module. You can check the strukturag/libheif for installation instructions, but as I have found, the easiest way for me was to use brew:

brew install cmake make pkg-config x265 libde265 libjpeg libtool
brew install libheif

Note: Pay attention to the brew's recommendation while installing

You can find installation scripts in heif-converter-image repository with names:

• install-libheif.sh
• install-libheif-macos.sh
• install-libheif-windows.bat

If the installation process seems a bit challenging, we recommend to consider using the heif-converter-image which offers a ready-to-use docker image.

Installation

go get github.com/MaestroError/go-libheif

Usage

This library provides functions to convert images between HEIC/HEIF/AVIF format and other common formats such as JPEG, PNG, and WebP.

Decode HEIF to JPEG/PNG

// Simple one-step conversion
err := libheif.HeifToJpeg("input.heic", "output.jpeg", 80)
err = libheif.HeifToPng("input.heic", "output.png")

// Or use the decode API (same result, explicit naming)
err = libheif.DecodeHeifToJpeg("input.heic", "output.jpeg", 80)
err = libheif.DecodeHeifToPng("input.heic", "output.png")

Get image.Image from HEIF

img, err := libheif.ReturnImageFromHeif("input.heic")

Encode to HEIF with options

// Encode an in-memory image
err := libheif.EncodeImageAsHeif(img, "output.heic",
    libheif.WithQuality(85),
    libheif.WithCompression(libheif.CompressionHEVC),
    libheif.WithLossless(false),
)

// Convert a file (JPEG/PNG) to HEIF
err = libheif.ConvertToHeif("input.png", "output.heic",
    libheif.WithQuality(90),
)

WebP to HEIF

err := libheif.WebpToHeif("input.webp", "output.heic",
    libheif.WithQuality(85),
)

Encoder options

Option	Description
WithQuality(q int)	Quality 1-100 (higher = better)
WithCompression(c Compression)	CompressionHEVC, CompressionAV1, CompressionAVC, CompressionJPEG
WithLossless(b bool)	Enable lossless encoding
WithLogging(l LogLevel)	LogLevelNone, LogLevelBasic, LogLevelFull

Legacy API

The original functions (HeifToJpeg, HeifToPng, ImageToHeif, SaveImageAsHeif) remain available for backward compatibility.

Please consult the GoDoc documentation for more detailed information.

Running tests

The easiest way to run the test suite is via Docker:

docker build -t go-libheif-test -f Dockerfile.test .
docker run --rm go-libheif-test

Contributions

Contributions to go-libheif are wholeheartedly encouraged! We believe in the power of the open source community to build the most robust and accessible projects. Whether you are a seasoned Go developer or just getting started, your perspective and efforts can help improve this project for everyone.

Here are a few ways you might contribute:

• Bug Fixes: If you encounter a problem with go-libheif, please open an issue in the GitHub repository. Even better, if you can solve the issue, we welcome pull requests.
• New Features: Interested in expanding the capabilities of go-libheif? Please open an issue to discuss your idea before starting on the code. Once we've agreed on an approach, you can submit a pull request with your new feature.
• Documentation: Clear documentation is vital to any project. If you can clarify our instructions or add helpful examples, we would appreciate your input.

Here are the steps for contributing code:

• Fork the go-libheif repository and clone it to your local machine.
• Create a new branch for your changes.
• Make your changes and push them to your fork.
• Open a pull request from your fork's branch to the go-libheif main branch.

Please remember to be as detailed as possible in your pull request descriptions to help the maintainers understand your changes. We look forward to seeing what you contribute! Together, we can make go-libheif even better.

Credits

Thanks to @strukturag and @farindk (Dirk Farin) for his work on the libheif library 🙏

Documentation

Index

• func ConvertToHeif(srcPath string, dstPath string, opts ...EncoderOption) error
• func DecodeHeifToJpeg(heifPath string, jpegPath string, quality int) error
• func DecodeHeifToPng(heifPath string, pngPath string) error
• func EncodeImageAsHeif(img image.Image, path string, opts ...EncoderOption) error
• func HeifToJpeg(heifImagePath string, newJpegImagePath string, quality int) error
• func HeifToPng(heifImagePath string, newPngImagePath string) error
• func ImageToHeif(jpegOrPngImagePath string, newHeifImagePath string) error
• func ReturnImageFromHeif(filename string) (image.Image, error)
• func SaveImageAsHeif(i image.Image, format string, newHeifImagePath string) error
• func WebpToHeif(webpPath string, heifPath string, opts ...EncoderOption) error
• type Compression
• type EncoderOption
  • func WithCompression(compression Compression) EncoderOption
  • func WithLogging(logging LogLevel) EncoderOption
  • func WithLossless(lossless bool) EncoderOption
  • func WithQuality(quality int) EncoderOption
• type LogLevel

Functions

func ConvertToHeif

func ConvertToHeif(srcPath string, dstPath string, opts ...EncoderOption) error

ConvertToHeif converts an image file at srcPath to HEIF format and saves it to dstPath.

The source format is auto-detected via image.Decode (supports JPEG, PNG, and any other format registered with the image package). Options are passed through to EncodeImageAsHeif.

Example:

err := ConvertToHeif("input.jpeg", "output.heic", WithQuality(70))
if err != nil {
	log.Fatal(err)
}

func DecodeHeifToJpeg

func DecodeHeifToJpeg(heifPath string, jpegPath string, quality int) error

DecodeHeifToJpeg decodes a HEIF file and saves it as JPEG with the specified quality.

Quality must be between 1 and 100 inclusive; invalid values return an error. Both heifPath and jpegPath must be non-empty.

Example:

err := DecodeHeifToJpeg("input.heic", "output.jpg", 80)
if err != nil {
	log.Fatal(err)
}

func DecodeHeifToPng

func DecodeHeifToPng(heifPath string, pngPath string) error

DecodeHeifToPng decodes a HEIF file and saves it as PNG.

Both heifPath and pngPath must be non-empty.

Example:

err := DecodeHeifToPng("input.heic", "output.png")
if err != nil {
	log.Fatal(err)
}

func EncodeImageAsHeif

func EncodeImageAsHeif(img image.Image, path string, opts ...EncoderOption) error

EncodeImageAsHeif encodes an image.Image to HEIF format and saves it to the given path.

Options are applied in order using the Functional Options pattern. Defaults (quality=100, HEVC, lossless=true, LogLevelFull) are used when no options are provided.

Example:

img := image.NewRGBA(image.Rect(0, 0, 100, 100))
err := EncodeImageAsHeif(img, "output.heic", WithQuality(80), WithLossless(false))
if err != nil {
	log.Fatal(err)
}

func HeifToJpeg

func HeifToJpeg(heifImagePath string, newJpegImagePath string, quality int) error

HeifToJpeg converts an image from HEIF format to JPEG format.

This function takes the path to the input HEIF image file, the path where the output JPEG image file should be saved, and the quality of the output JPEG image.

Example:

err := HeifToJpeg("input.heic", "output.jpeg", 80)
if err != nil {
	log.Fatal(err)
}

func HeifToPng

func HeifToPng(heifImagePath string, newPngImagePath string) error

HeifToPng converts an image from HEIF format to PNG format.

This function takes the path to the input HEIF image file and the path where the output PNG image file should be saved.

Example:

err := HeifToPng("input.heic", "output.png")
if err != nil {
	log.Fatal(err)
}

func ImageToHeif

func ImageToHeif(jpegOrPngImagePath string, newHeifImagePath string) error

ImageToHeif converts an image from JPEG or PNG format to HEIF format.

This function takes the path to the input JPEG or PNG image file and the path where the output HEIF image file should be saved.

Example:

err := ImageToHeif("input.jpeg", "output.heic")
if err != nil {
	log.Fatal(err)
}

func ReturnImageFromHeif

func ReturnImageFromHeif(filename string) (image.Image, error)

ReturnImageFromHeif decodes a HEIF file and returns the resulting image.

It expects the filename of a HEIF file as input. If the file cannot be decoded or the decoded image is not in HEIF format, an error is returned.

Example:

filename := "image.heic"
img, err := returnImageFromHeif(filename)
if err != nil {
	log.Fatal(err)
}

func SaveImageAsHeif

func SaveImageAsHeif(i image.Image, format string, newHeifImagePath string) error

SaveImageAsHeif encodes an image in HEIF format and saves it to a file.

The image quality is set to 100, and lossless mode is enabled. The original image format is printed to the console.

Example:

img := image.NewRGBA(image.Rect(0, 0, 100, 100))
format := "png"
newHeifImagePath := "output.heif"
if err := SaveImageAsHeif(img, format, newHeifImagePath); err != nil {
	log.Fatal(err)
}

func WebpToHeif

func WebpToHeif(webpPath string, heifPath string, opts ...EncoderOption) error

WebpToHeif converts a WebP image file to HEIF format.

The source file must be a valid WebP image. Non-WebP files are rejected with a descriptive error naming the actual format detected. Options are passed through to EncodeImageAsHeif.

Importing this package registers the WebP decoder with Go's image package, enabling ConvertToHeif to also handle WebP files.

Example:

err := WebpToHeif("photo.webp", "photo.heic", WithQuality(80))
if err != nil {
	log.Fatal(err)
}

Types

type Compression

type Compression int

Compression wraps heif.Compression to avoid direct dependency on CGo types in public API.

const (
	CompressionHEVC Compression = iota
	CompressionAV1
	CompressionAVC
	CompressionJPEG
)

type EncoderOption

type EncoderOption func(*encoderConfig)

EncoderOption configures an encoderConfig via the Functional Options pattern. Pass any number of EncoderOption values to encoding functions.

func WithCompression

func WithCompression(compression Compression) EncoderOption

WithCompression returns an EncoderOption that sets the encoder compression type.

func WithLogging

func WithLogging(logging LogLevel) EncoderOption

WithLogging returns an EncoderOption that sets the encoder log verbosity level.

func WithLossless

func WithLossless(lossless bool) EncoderOption

WithLossless returns an EncoderOption that enables or disables lossless encoding.

func WithQuality

func WithQuality(quality int) EncoderOption

WithQuality returns an EncoderOption that sets the encoder quality. Values are clamped silently: below 1 is set to 1, above 100 is set to 100.

type LogLevel

type LogLevel int

LogLevel controls verbosity of heif encoder logging.

const (
	LogLevelNone LogLevel = iota
	LogLevelBasic
	LogLevelFull
)