libheif-rs

libheif-rs is a safe Rust wrapper around libheif-sys, the raw FFI bindings to the C libheif library, giving Rust programs typed, ownership-checked access to HEIF/HEIC image reading, decoding, and writing. It wraps every libheif handle — context, image, image handle, encoder — in a Rust struct with a matching Drop implementation, so freeing the underlying C resources happens automatically and safely instead of requiring manual release calls.

The crate supports reading files from disk, memory buffers, or a custom Reader trait for streaming sources, decoding into RGB or YCbCr color spaces with configurable chroma and bit depth, and encoding output through any available format plugin (including AV1/HEVC via libheif’s plugin system). Feature flags gate which libheif API version (v1_17 through the latest v1_23) the crate compiles against, and an optional image crate integration registers HEIF decoding hooks so downstream code can use the standard image::ImageReader interface directly.

What You Get

• Safe HeifContext type for reading HEIF files from disk paths, in-memory byte slices, or a custom streaming Reader trait
• Image and ImageHandle types exposing decoded pixel planes, Exif/XMP metadata blocks, and auxiliary image access
• Encoder wrapper supporting format-specific compression plugins (AV1, HEVC, and others available via libheif)
• Versioned feature flags (v1_17 through v1_23/latest) to target the exact libheif API surface your deployment ships
• Optional image crate integration that registers HEIF decoding hooks for use through the standard ImageReader API
• Region and track APIs (feature-gated) for reading HEIF image sequences and spatial region annotations

Common Use Cases

• Photo library ingestion - backend services decode HEIC photos uploaded from iOS devices into RGB buffers for thumbnailing or re-encoding
• Format conversion pipelines - CLI or batch tools read HEIF/HEIC files and re-encode them to AV1/HEVC-compressed outputs or hand decoded pixels to other Rust image tooling
• Metadata extraction - applications pull Exif and XMP metadata blocks out of HEIF containers without a full decode
• Cross-format image handling via the image crate - projects already built on the image crate register libheif-rs’s decoding hooks to add HEIF support transparently

Under The Hood

Architecture HeifContext owns a raw libheif_sys::heif_context pointer and mediates all file/reader/byte-buffer ingestion (context.rs, with a Source enum tracking ownership of file bytes or a boxed Reader trait object), delegating extraction of images to ImageHandle (image_handle.rs) and decoding to LibHeif::decode (heif.rs) via ColorSpace/DecodingOptions bridging; Image (image.rs) wraps decoded pixel planes with channel-indexed accessors, encoder.rs/decoder.rs wrap plugin descriptor discovery and option structs, and errors.rs centralizes HeifError with error_code/sub_code C-enum mirroring via enumn::N. The structure is a thin FFI-safety layer: one Rust type per libheif C handle, each holding a raw pointer plus a Drop impl for the paired release call, so ownership discipline is the core abstraction — the lifetime parameter on HeifContext<‘a> exists specifically to stop a context from outliving a borrowed memory buffer or boxed reader.

Tech Stack Rust 2021 edition targeting rust-version 1.82; the core dependency is libheif-sys 5.3.1, raw FFI bindings to the C libheif library that can link dynamically via pkg-config/vcpkg or be compiled from vendored sources with the embedded-libheif feature. Supporting crates are cfg-if for feature gating, enumn for C-enum-to-Rust-enum conversion, four-cc for FourCC box tags, and libc for C types; an optional dependency on the image crate (v0.25) powers the decoder-hook integration. Dev-dependencies (kamadak-exif, tempfile) support the integration test suite. There is no async runtime and no database layer — this is a synchronous, blocking FFI wrapper crate, with cargo-release automation for changelog/version bumps and vcpkg metadata for Windows builds.

Code Quality The tests/ directory holds eight integration test files (read_test.rs, write_test.rs, regions_test.rs, sequences.rs, security_limits.rs, heif_struct_test.rs, integration.rs, utils.rs) that exercise the public API end-to-end against real .heif fixtures rather than isolated unit tests — a reasonable choice for an FFI wrapper where correctness is best verified against the real underlying library. Error handling is fully typed through a HeifError{code, sub_code, message} struct and a dedicated Result<T> alias, with no unwraps in library code paths (unwrap appears only in doc examples and tests); naming follows idiomatic Rust convention, matching the C API’s semantics where useful. A CI workflow runs check-and-test, and rustfmt.toml enforces consistent formatting.

What Makes It Unique The versioned feature ladder (v1_17 through v1_23) lets consumers compile against exactly the libheif API surface their deployed system library supports, rather than forcing an all-or-nothing binding — an uncommon level of care for a niche FFI wrapper. The image crate integration is a genuinely useful bridge: calling register_all_decoding_hooks lets any code already using the wider Rust image ecosystem decode HEIF files through the standard ImageReader interface without ever touching libheif-rs types directly. The optional embedded-libheif feature, which statically compiles libheif from vendored sources, further reduces the usual friction of shipping a crate with a native system dependency.