Commit 20259c1a for libheif
commit 20259c1afcc85e616ee1255f48c86580be404d67
Author: Dirk Farin <dirk.farin@gmail.com>
Date: Tue Dec 30 12:51:54 2025 +0100
Update README
diff --git a/README.md b/README.md
index f4f86e87..933aee1e 100644
--- a/README.md
+++ b/README.md
@@ -2,14 +2,18 @@
[](https://github.com/strukturag/libheif/actions) [](https://ci.appveyor.com/project/strukturag/libheif) [](https://scan.coverity.com/projects/strukturag-libheif)
-libheif is an ISO/IEC 23008-12:2017 HEIF and AVIF (AV1 Image File Format) file format decoder and encoder.
-There is partial support for ISO/IEC 23008-12:2022 (2nd Edition) capabilities.
-
-HEIF and AVIF are new image file formats employing HEVC (H.265) or AV1 image coding, respectively, for the
+libheif is an ISO/IEC 23008-12 HEIF and AVIF (AV1 Image File Format) file format decoder and encoder.
+HEIC and AVIF are new image file formats employing HEVC (H.265) or AV1 image coding, respectively, for the
best compression ratios currently possible.
-libheif makes use of [libde265](https://github.com/strukturag/libde265) for HEIC image decoding and x265 for encoding.
+On top of HEIC and AVIF, libheif also supports HEIF images coded with VVC, AVC, JPEG, JPEG-2000, and ISO/IEC 23001-17.
+The ISO/IEC 23001-17 codec is built-in to libheif and allows to store lossless images and video in many different formats.
+
+libheif makes use of various codec libraries for implementing each compression format.
+For HEIC, [libde265](https://github.com/strukturag/libde265) is used by default for decoding and x265 for encoding.
For AVIF, libaom, dav1d, svt-av1, or rav1e are used as codecs.
+libheif can be built with a subset of the supported codecs to keep the size and the number of dependencies low.
+Alternatively, the libheif codecs can also be built as separate plugins that can be installed and loaded dynamically when used.
## Supported features
@@ -18,19 +22,20 @@ libheif has support for:
* HEIC, AVIF, VVC, AVC, JPEG-in-HEIF, JPEG2000, uncompressed (ISO/IEC 23001-17:2024) codecs
* alpha channels, depth maps, thumbnails, auxiliary images
* multiple images in a file
+* HEIF image sequences and MP4 video, including alpha channels
* tiled images with decoding individual tiles and encoding tiled images by adding tiles one after another
* HDR images, correct color transform according to embedded color profiles
* image transformations (crop, mirror, rotate), overlay images
* plugin interface to add alternative codecs
* reading EXIF and XMP metadata
* region annotations and mask images
-* decoding of files while downloading (e.g. extract image size before file has been completely downloaded)
+* streaming of images and video by requesting data from the network through a data-reader interface
Supported codecs:
| Format | Decoders | Encoders |
|:-------------|:-------------------:|:----------------------------:|
| HEIC | libde265, ffmpeg | x265, kvazaar |
-| AVIF | AOM, dav1d | AOM, rav1e, svt-av1 |
+| AVIF | libaom, dav1d | libaom, rav1e, svt-av1 |
| VVC | vvdec | vvenc, uvg266 |
| AVC | openh264, ffmpeg | x264 |
| JPEG | libjpeg(-turbo) | libjpeg(-turbo) |
@@ -38,7 +43,7 @@ Supported codecs:
| HTJ2K | OpenJPEG | OpenJPH |
| uncompressed | built-in | built-in |
-## API
+## Programming API
The library has a C API for easy integration and wide language support.
@@ -46,7 +51,7 @@ The decoder automatically supports both HEIF and AVIF (and the other compression
The encoder can be switched between HEIF and AVIF simply by setting `heif_compression_HEVC` or `heif_compression_AV1`
to `heif_context_get_encoder_for_format()`, or using any of the other compression formats.
-Loading the primary image in an HEIF file is as easy as this:
+### Loading the primary image from a HEIF file
```C
heif_context* ctx = heif_context_alloc();
@@ -71,7 +76,7 @@ heif_image_handle_release(handle);
heif_context_free(ctx);
```
-Writing an HEIF file can be done like this:
+### Writing a HEIF file
```C
heif_context* ctx = heif_context_alloc();
@@ -94,7 +99,7 @@ heif_context_write_to_file(ctx, "output.heic");
heif_context_free(ctx);
```
-Get the EXIF data from an HEIF file:
+### Get the EXIF data from a HEIF file
```C
heif_item_id exif_id;
@@ -107,18 +112,26 @@ if (n==1) {
}
```
-See the header file `heif.h` for the complete C API.
+### Image sequences, MP4 video
-There is also a C++ API which is a header-only wrapper to the C API.
-Hence, you can use the C++ API and still be binary compatible.
-Code using the C++ API is much less verbose than using the C API directly.
+See the [image sequences API documentation](https://github.com/strukturag/libheif/wiki/Reading-and-Writing-Sequences).
+Since HEIF image sequences are very similar to MP4 video, libheif can also read and write MP4 video (without audio)
+with all supported codecs.
-### Reading and Writing Tiled Images
+### High-resolution tiled images
For very large resolution images, it is not always feasible to process the whole image.
In this case, `libheif` can process the image tile by tile.
-See [this tutorial](https://github.com/strukturag/libheif/wiki/Reading-and-Writing-Tiled-Images) on how to use the API for this.
+See the [image tiling API documentation](https://github.com/strukturag/libheif/wiki/Reading-and-Writing-Tiled-Images).
+
+### More documenation
+
+See the header files for the complete C API.
+
+There is also a C++ API which is a header-only wrapper to the C API.
+Hence, you can use the C++ API and still be binary compatible.
+Code using the C++ API is much less verbose than using the C API directly.
## Compiling
@@ -391,6 +404,8 @@ You can [sponsor](https://github.com/sponsors/farindk) the development using the
A big thank you goes to these major sponsors for supporting the development of libheif:
+* AOMedia
+* OGC (Open Geospatial Consortium)
* Pinterest
* Shopify <img src="logos/sponsors/shopify.svg" alt="shopify-logo" height="20"/>
* StrukturAG
@@ -403,5 +418,5 @@ The sample applications are distributed under the terms of the MIT License.
See COPYING for more details.
Copyright (c) 2017-2020 Struktur AG</br>
-Copyright (c) 2017-2025 Dirk Farin</br>
+Copyright (c) 2017-2026 Dirk Farin</br>
Contact: Dirk Farin <dirk.farin@gmail.com>