# nokiatech/heif HEIF Container Reader and Writer

> nokiatech/heif is a C++ implementation of the HEIF container standard, with C++, Java and reader APIs in JavaScript. It packages already encoded visual data but does not itself encode images.

**nokiatech/heif** — High Efficiency Image File Format

- Repository: https://github.com/nokiatech/heif
- Stars: 1,790 · Forks: 247
- Language: C++
- License: NOASSERTION
- Published: 2026-10-16 · Updated: 2026-10-16 · Language: en
- Canonical page: https://hysenlabs.com/projects/nokiatech-heif

## Why nokiatech/heif Handles Containers Rather Than Image Encoding

nokiatech/heif addresses applications that need to read or write High Efficiency Image File Format containers while retaining control over the encoded image data inside them. HEIF is standardized by the Moving Picture Experts Group and is based on ISO Base Media File Format, or ISOBMFF. The repository presents itself as a reader and writer implementation of that standard.

The central boundary is important. The README states that HEIF is not an image or video encoder per se. Visual quality therefore depends on the encoder used before its output enters the container. The documented payload choices include HEVC, SHVC, MV-HEVC, AVC and JPEG. An application can use this project to organize those bitstreams, image sequences, metadata and relationships among image items, but it still needs another component to produce the compressed visual data.

That design makes the project relevant to media pipelines, image tooling and applications working with image bursts, collections, sequences, cinemagraphs or computational photography structures. It is also a poor fit for a small command-line conversion utility that accepts an unencoded image and expects one executable to produce a final HEIF file. No such conversion CLI or one-step encoding workflow is documented in the README.

## ISOBMFF Boxes and HEIF APIs in the Source Layout

The repository separates low-level container handling from higher-level access. ISO Base Media File Format box parsing and writing code is located under `srcs/common/`. Above it are the HEIF reader and writer libraries under `srcs/api/reader/` and `srcs/api/writer/`. This arrangement suggests a layered implementation in which box-level structures support format-specific reader and writer operations.

Two additional API layers are listed. `srcs/api-cpp/` contains a convenience C++ API described as wrapping the underlying reader and writer, while `srcs/api-java/` contains Java APIs using JNI. The repository also includes C++ usage examples under `srcs/examples/`. The JavaScript reader is not stored in the default branch layout described by the README. It is documented as living in the `gh-pages` branch, alongside the website content.

The supported structures extend beyond putting one coded image into a file. The release history records support for image items with decoding dependencies, entity groups, track groups, segmented tracks, edit lists, JPEG handling and multi-layered images. README news also states that the implementation follows ISO/IEC 23008-12:2017. The MIAF-specific code is maintained separately, so projects seeking MIAF behavior are directed to the `miaf` branch rather than assuming that every MIAF-specific path is present on `master`.

This is a source-level media stack rather than a packaged application. The repository entries include `build/`, `docs/`, `srcs/` and `LICENSE.TXT`, but the README does not document command-line programs for creating or displaying HEIF files.

## Building the C++ Libraries with CMake

The documented C++ build requires CMake and a compiler that supports C++11 in `PATH`. The following procedure is taken directly from the repository README. The generator name is not hard-coded because `cmake --help` lists generators available on the target platform.

This configures the native source tree and then starts the build. A successful CMake configuration should identify a generator for the local platform, and the build command should complete against that generated build configuration.

```bash
cd heif/build
cmake --help
cmake ../srcs -G"<Generator listed by above command for your target platform>"
cmake --build .
```

This is the only first-use procedure that can be presented without inventing a missing invocation. The README identifies C++ example code under `srcs/examples/`, but it does not provide a command for running an example, state its arguments, or identify a generated executable name. An engineer should therefore inspect the example source and the CMake-generated targets before assuming that `cmake --build .` creates a ready-to-run conversion utility.

The website at `https://nokiatech.github.io/heif/examples.html` is the repository's stated location for HEIF file examples, while the Wiki contains additional build instructions. The README itself does not document runtime dependencies, installation targets or a system-wide installation command.

## Building the Java API and Loading heifjni

The Java desktop path builds on the native libraries rather than replacing the C++ build. The README requires Java version 8 or newer and Gradle. It also requires the C/C++ library to be built first.

After the native build, the documented desktop command builds the Java API:

```bash
cd heif/build/java-desktop
gradle build
```

Running the Java API introduces an additional deployment condition. The native JNI library must be present in the Java library search path. The README identifies the platform-specific names as `heifjni.dll` for Windows and `heifjni.so` for Linux. It does not document a particular `PATH`, `LD_LIBRARY_PATH`, `CLASSPATH`, or application configuration value for that search path.

For Android, the documented route is to import the project under `heif/build/android` into Android Studio and build it with the Android SDK and NDK. No Gradle command, minimum Android version or NDK version is listed in the README. Those omissions matter for CI and reproducible packaging because a successful desktop Gradle build does not establish that the Android integration will work.

The project documentation also changes its stability expectations. An older release note calls the Java API relatively stable while saying the new C++ convenience API would most likely change. That statement dates from v3.2 and is historical, but it remains a reason for integrators to review the current headers and Java interfaces before committing to a public wrapper interface.

## Codec Integration Limits and HEIF Adoption Boundaries

The clearest failure mode is expecting the library to perform encoding. Since HEIF acts as a container and the visual payload depends on an encoder such as HEVC, feeding nokiatech/heif an image does not by itself establish a complete production pipeline. The application also needs codec integration, encoding decisions and any required transformation from its source format to one of the documented payload types.

There is a second limitation around specification variants and branches. General HEIF support is described on `master`, but the README directs MIAF-specific code to a separate `miaf` branch. A project should not treat those branches as interchangeable merely because both relate to HEIF-family media.

A practical alternative is a codec-first pipeline in which an HEVC, AVC or JPEG encoder performs compression and the application packages the result using platform-native HEIF tooling or application-level format handling. The difference is responsibility. nokiatech/heif concentrates on ISOBMFF box serialization and HEIF-specific reader and writer structures, including sequences, dependencies and grouping. A codec-first approach may avoid compiling this C++ stack, but the README gives no comparison of platform tools or claim that another package covers these structures.

For teams that already control HEIF container semantics and need the documented C++, Java or JNI surfaces, the source layout is the reason to consider this project. For teams seeking a ready-made image conversion command, installation package, encoder, thumbnail generator or playback application, the README does not establish that those capabilities are present.

## Nokia Licence Terms, Example Media Rights and Upgrade Scope

The repository does not use a licence category that GitHub could classify. Its README directs users to `LICENSE.TXT` for the terms governing use of the repository contents. Any adoption decision therefore has to begin with that file rather than assuming a standard open source licence such as MIT or Apache-2.0. This review does not interpret the licence or provide legal advice.

The bundled media files have separate terms. The README states that example files with `.heic`, `.png`, `.jpg` and `.gif` extensions are under copyright © Nokia Technologies 2015-2025. That means permission covering source code does not automatically settle reuse of every included media asset. Source-code licensing, example-file rights and commercial licensing are distinct questions under the repository's documentation.

Maintenance should also be assessed from repository activity rather than release labels alone. The repository is not archived, and its last push was on 2026-10-15. GitHub has no GitHub releases, although the README records a v3.7.1 release dated 2025-03-11 with bug fixes, including a missing limits include. The v3.7.0 release entry is dated 2021-10-08 and adds track-group writing support. The gap between those documented releases and the later push suggests that commit activity and formal release publication are not equivalent signals.

Upgrading requires checking API and licence changes directly in Git rather than relying only on the historical v3.2 stability note. The README also warns that backwards compatibility was not maintained during its 2016 specification update. That is not evidence about every later upgrade, but it establishes backward compatibility as an explicit concern in this project's history.

## Conclusion

Adopt nokiatech/heif when an application must inspect or construct standards-based HEIF containers around HEVC, AVC or JPEG data. Do not adopt it as a standalone image encoder. Before integration, verify the custom LICENSE.TXT terms, confirm that the required codec pipeline and JNI placement match the target platform, and review the API examples because the README does not document a command-line reading or writing workflow.

## FAQ

### Does nokiatech/heif encode HEVC, AVC or JPEG images?

No. The project is a HEIF container reader and writer, not an image or video encoder. The encoded bitstreams must be supplied through an appropriate media encoder such as HEVC.

### How do I build the C++ API for nokiatech/heif?

The README requires CMake and a C++11-capable compiler in `PATH`, then configures `srcs` from the `heif/build` directory with a locally available CMake generator and runs `cmake --build .`.

### What is required to run the nokiatech/heif Java API?

Java version 8 or newer and Gradle are required for the desktop API, and the C/C++ libraries must be built first. At runtime, `heifjni.dll` on Windows or `heifjni.so` on Linux must be in the Java library search path.

## Sources

- [Issues](https://github.com/nokiatech/heif/issues)
- [nokiatech/heif on GitHub](https://github.com/nokiatech/heif)
- [README](https://github.com/nokiatech/heif/blob/master/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/nokiatech-heif