DOCSEARCHbyAlgolia
Submit Docs

libavif

repository·main·Indexed 24 days ago

https://github.com/aomediacodec/libavif

A library for encoding and decoding AVIF files, featuring command-line tools avifenc and avifdec, and the avifgainmaputil utility for HDR gain map processing. It supports multiple AV1 codecs including aom, dav1d, libgav1, rav1e, and SVT-AV1, and provides Android JNI bindings for integration into Android applications.

Tokens
4.5K
Snippets
5
Records
25
Agent score
80%

What's inside libavif

  1. Handle image sequences and progressive AVIFs with avifdec

    main

    When working with image sequences or progressive AVIF files, use the following flags:

    • --index I: Specifies which frame index to decode. Use 0 for the first frame or all to decode every frame in the sequence.
    • --progressive: Enables progressive processing. When combined with --index, avifdec will use the index to choose which specific layer to decode in progressive order.

  2. Build libavif from source

    main

    Building libavif requires CMake.

    Build using installed dependencies (Recommended)

    Use this method if you have aom, libjpeg, libpng, and libyuv already installed on your system:

    git clone -b v1.2.1 https://github.com/AOMediaCodec/libavif.git
cmake -S libavif -B libavif/build -DAVIF_CODEC_AOM=SYSTEM -DAVIF_BUILD_APPS=ON
cmake --build libavif/build --config Release --parallel

    Build everything from scratch (Development/Debug)

    Use this method to build all dependencies locally. This is useful for debugging or when you want to ensure all components are built from source:

    git clone -b v1.2.1 https://github.com/AOMediaCodec/libavif.git
cmake -S libavif -B libavif/build -DCMAKE_BUILD_TYPE=Debug -DBUILD_SHARED_LIBS=OFF -DAVIF_CODEC_AOM=LOCAL -DAVIF_LIBYUV=LOCAL -DAVIF_LIBSHARPYUV=LOCAL -DAVIF_JPEG=LOCAL -DAVIF_ZLSPNG=LOCAL -DAVIF_BUILD_APPS=ON
cmake --build libavif/build --config Debug --parallel

  4. Choose a build strategy for libavif dependencies

    main

    Depending on your target environment, you should choose one of two dependency management strategies:

    1. Static/Embedded Builds (Windows or fully static releases)

    If you are building for Windows or a fully static embedded release, use the scripts provided in the ext/ directory. This is the recommended method for ensuring all dependencies are compatible and works similarly to libavif's continuous integration builders.

    To use this method, configure CMake with:

    • BUILD_SHARED_LIBS=0
    • Appropriate AVIF_* flags to specify desired codecs.

    2. Distribution/Unix-like Builds

    If you are building for a Linux distribution or a general Unix-like environment, you should ignore the ext/ directory. Instead, rely on the system's existing libraries for zlib, libpng, and libjpeg.

    To use this method, configure CMake with:

    • BUILD_SHARED_LIBS set to its default (ON).
    • The appropriate AVIF_BUILD_* flags to enable the specific shared AV1 codec libraries you intend to use.

  5. Prerequisites for libavif Android JNI Bindings

    main

    To build the libavif Android JNI bindings, you must have the following tools installed and configured:

    • Android SDK: Must be set up for Android API target 30.
    • Android NDK: Required for building the decoder (e.g., dav1d). Recommended revision: r25c.
    • Gradle
    • CMake
    • Ninja

  6. Install libavif via package managers

    main

    libavif is available as a package on most major operating systems:

    Windows

    Use vcpkg:

    vcpkg install libavif

    Alternatively, download official Windows binaries from the releases page.

    macOS

    Using Homebrew:

    brew install libavif

    Using MacPorts:

    sudo port install libavif

    Linux

    Debian-based:

    sudo apt install libavif-dev

    Red Hat-based:

    sudo yum -y install libavif

    MinGW (MSYS2 UCRT64)

    pacman -S mingw-w64-ucrt-x86_64-libavif

  7. Build the libavif man pages

    main

    The man pages for avifenc and avifdec are written in pandoc's Markdown format. To build them, you must have pandoc installed on your system. By default, building man pages is disabled in the CMake configuration.

    To enable them, set the AVIF_BUILD_MAN_PAGES CMake option to ON during your build process.

  8. Generate the libavif Android AAR package

    main

    Follow these steps to generate an AAR package containing libavif and the JNI wrapper.

    1. Clone the repository

    git clone https://github.com/AOMediaCodec/libavif.git
cd libavif

    2. Configure Environment Variables

    Set your SDK and NDK paths (NDK r25c is recommended):

    export ANDROID_SDK_ROOT="/path/to/android/sdk"
export ANDROID_NDK_HOME="/path/to/android/ndk"

    3. Build Codec Dependencies

    By default, these instructions use dav1d.

    To build dav1d:

    cd ext
./dav1d_android.sh "${ANDROID_NDK_HOME}"
cd ..

    To use libgav1 instead:

    1. Build libgav1:
    cd ext
./libgav1_android.sh "${ANDROID_NDK_HOME}"
cd ..
    1. Update avifandroidjni/src/main/jni/CMakeLists.txt:
      • Set AVIF_CODEC_DAV1D to OFF
      • Set AVIF_CODEC_LIBGAV1 to LOCAL

    4. Build libyuv

    cd ext
./libyuv_android.sh "${ANDROID_NDK_HOME}"
cd ..

    Note: To disable libyuv, set AVIF_LIBYUV to OFF in avifandroidjni/src/main/jni/CMakeLists.txt.

    5. Build the JNI Wrapper and AAR

    cd android_jni
./gradlew build assembleRelease

    The resulting AAR package will be located in: libavif/android_jni/avifandroidjni/build/outputs/aar.

  9. Importing libyuv from upstream into libavif

    main

    When importing source code from upstream libyuv into the libavif third-party directory, you must follow these specific modification rules to maintain compatibility and minimize footprint:

    1. Hierarchy: Maintain the same source hierarchy as the original libyuv.
    2. API Surface: Only include APIs used by libavif for scaling, specifically ScalePlane() and ScalePlane_12(). All other APIs must be excluded.
    3. Function Paths: Within ScalePlane() and ScalePlane_16(), only retain the following paths (and their _16 equivalents):
      • ScalePlaneVertical()
      • CopyPlane()
      • ScalePlaneBox()
      • ScalePlaneUp2_Linear()
      • ScalePlaneUp2_Bilinear()
      • ScalePlaneBilinearUp()
      • ScalePlaneBilinearDown()
      • ScalePlaneSimple()
      • Note: All other paths, including SIMD, must be stripped out.
    4. Documentation: Update the commit hash of the imported libyuv in the third_party/README.md file.
    5. API Macros: Remove LIBYUV_API from all imported functions, as these files are always built statically.
    6. File Extensions: Replace all .cc file extensions with .c.

  10. Use avifenc to compress images to AVIF

    main

    The avifenc command-line tool compresses image files (JPEG, PNG, or YUV4MPEG2/Y4M) into the AVIF format.

    Basic Syntax: avifenc [options] input.[jpg|jpeg|png|y4m] output.avif

    Common Tasks:

    • Simple compression: Convert a PNG to AVIF.
    • Specify output filename: Use -o or --output to define the output path instead of relying on the last argument.
    • Lossless encoding: Use -l or --lossless to set all defaults to lossless mode.
    avifenc input.png output.avif

  11. Enable examples and tests in libavif build

    main

    When building libavif with CMake, you can enable additional targets:

    • Examples: Enable AVIF_BUILD_EXAMPLES to build and run the code examples located in the examples/ directory.
    • Tests: Enable AVIF_BUILD_TESTS to build the C-based tests.
    • GoogleTest: If building tests, set AVIF_GTEST to SYSTEM or LOCAL to use GoogleTest.
    • Code Coverage: Enable AVIF_ENABLE_COVERAGE and build the avif_coverage target. This requires compiling with clang and having LLVM installed.

    Example for coverage:

    make avif_coverage -j

  12. Configure libavif dependencies via CMake

    main

    When building libavif from source using CMake, you can control how dependencies are handled using specific flags. Each flag can take one of three values:

    • OFF: The dependency is disabled.
    • SYSTEM: The dependency is expected to be already installed on the system (discoverable via FIND_LIBRARY).
    • LOCAL: The dependency is built locally. CMake can often download and build it automatically. If a directory for the dependency already exists in the ext/ subdirectory, CMake will use it instead of downloading a new copy.

    Codec Dependencies

    No AV1 codecs are enabled by default. You must enable at least one by setting the following options to LOCAL or SYSTEM:

    • AVIF_CODEC_AOM: libaom (Encoder and Decoder)
    • AVIF_CODEC_DAV1D: dav1d (Decoder)
    • AVIF_CODEC_LIBGAV1: libgav1 (Decoder)
    • AVIF_CODEC_RAV1E: rav1e (Encoder)
    • AVIF_CODEC_SVT: SVT-AV1 (Encoder)

    Libyuv Dependency

    libyuv is highly recommended to speed up color space conversions. It is enabled by default as SYSTEM. To build it locally, use -DAVIF_LIBYUV=LOCAL. To disable it, use -DAVIF_LIBYUV=OFF.