ffheif

A small library that decodes HEIF / HEIC / HIF still images to raw 16-bit RGBA using FFmpeg.

This library doesn't contain any patented HEVC/H.265 decoding code. Instead, the bundled FFmpeg hands off HEVC bitstreams to a hardware decoder provided by the OS / GPU driver (VideoToolbox, D3D11VA, Vulkan, CUDA, VAAPI, or DXVA2); there is no software fallback available. In other words, this library only parses the HEIF container, demuxes the HEVC bitstream and forwards it to the platform's hardware video pipeline. If no such pipeline is available, the decoding fails.

The output format is RGBA64LE: 8 bytes per pixel, 16-bit unsigned per channel, little-endian, tightly packed (stride = width * 8). 8-bit input is zero-extended into the high byte; 10-bit HDR input keeps full precision.

Build

FFmpeg is vendored as a submodule under third_party/ffmpeg and linked statically. There is no runtime dependency on system FFmpeg.

Requires:

• CMake ≥ 3.21, a C23 compiler
• nasm (≥ 2.13) - optional; absent → FFmpeg builds without x86 asm (slower)
• Linux: dev headers for libva, vulkan-headers, ffnvcodec-headers (any subset - missing ones drop that hwaccel)
• macOS: Xcode command-line tools
• Windows: MSVC or MinGW
• At decode time, a working hardware backend: VideoToolbox, D3D11VA, Vulkan, CUDA, VAAPI, or DXVA2

git clone --recurse-submodules https://github.com/fstanis/ffheif
cmake -S ffheif -B ffheif/build -DCMAKE_BUILD_TYPE=Release
cmake --build ffheif/build -j

See THIRD_PARTY_NOTICES.md for the FFmpeg version, configure flags, and LGPL-2.1 source availability.

Usage

#include <ffheif.h>

ffheif_decoder* dec = ffheif_decoder_new();

ffheif_image img;
ffheif_decode(dec, bytes, len, &img);
// img.pixels   - RGBA64LE, img.pixels_len bytes
// img.info     - dimensions, bit depth, color metadata, exif_orientation, ...

ffheif_image_free(&img);
ffheif_decoder_free(dec);

ffheif_decode allocates img.pixels and fills img.info. Ownership transfers to the caller; release with ffheif_image_free. Pixels are in the bitstream's decoded orientation - rotate by img.info.exif_orientation if you need them upright. The ffheif_decoder is reusable and caches the successful hardware backend across calls.

License

This project is licensed under the GNU Lesser General Public License version 2.1 or later (LGPL v2.1+). See the LICENSE file for details.