Building and Testing dav2d: VideoLAN's Open-Source AV2 Decoder

Overview

dav2d is an open-source decoder for the AV2 video codec, developed by the VideoLAN team — the same group behind VLC media player and the popular dav1d AV1 decoder. While the Alliance for Open Media (AOM) had originally targeted an AV2 specification release by the end of 2025, the spec remains in draft status as of early 2025. Nevertheless, VideoLAN has been actively working on dav2d for months and released the initial source code in early 2025. This tutorial will guide you through setting up, building, and testing dav2d on a modern Linux system. By the end, you'll have a working decoder that can process AV2 bitstreams, even as the codec continues to evolve.

Prerequisites

Before diving into dav2d, ensure your system meets these requirements:

• Operating System: A 64-bit Linux distribution (Ubuntu 22.04+, Fedora 38+, or similar) is recommended. Windows and macOS builds are possible but not covered here.
• Build Tools: Git, a C compiler (GCC or Clang), Meson build system, and Ninja. Install them via your package manager.
• Development Libraries: pthreads, libc6-dev (or glibc-devel), and optionally nasm (for SIMD assembly optimization).
• Test Content: AV2 test bitstreams (e.g., from AOM's test set or a sample encoder like svt-av2).
• Basic Knowledge: Familiarity with the command line, compiling C projects, and codec fundamentals.

Step-by-Step Instructions

1. Cloning the Repository

Start by cloning the official dav2d repository from VideoLAN's GitLab:

git clone https://code.videolan.org/videolan/dav2d.git
cd dav2d

This fetches the latest development code. Because the AV2 spec is a moving target, we recommend checking out the master branch for the most recent changes:

git checkout master

2. Setting Up the Build System

dav2d uses the Meson build system. First, create a build directory and configure the project:

meson setup builddir --buildtype=release
cd builddir

You can pass additional options to control features. For example, to enable SIMD optimizations (highly recommended for performance), add -Denable_asm=true. To debug, use --buildtype=debug instead.

3. Compiling the Library

With the build configured, compile dav2d using Ninja:

ninja -j$(nproc)

The -j$(nproc) flag runs parallel jobs equal to your CPU cores, speeding up compilation. On modern hardware, this should take only a few minutes. If errors occur, verify that all prerequisites are installed (see Common Mistakes).

4. Installing dav2d

After successful compilation, install the library and its headers:

sudo ninja install

This copies the shared library (libdav2d.so) and development files to system directories (e.g., /usr/local/lib). If you want to avoid system-wide installation, you can use the library directly from the build directory by setting LD_LIBRARY_PATH.

5. Testing with a Sample AV2 Bitstream

dav2d includes a simple command-line tool called dav2d (or sometimes dav2d_cli) that decodes AV2 files. Obtain an AV2 test bitstream — for example, a short clip encoded with svt-av2 (the reference encoder) in IVF or OBU format. Then run:

dav2d -i sample.av2 -o decoded.y4m

This decodes sample.av2 into a Y4M video file. Check the output with a media player that supports raw YUV (e.g., ffplay):

ffplay -f rawvideo -pix_fmt yuv420p -s 1920x1080 decoded.y4m

Replace 1920x1080 with your clip's resolution. If everything works, you'll see the decoded video.

6. Integrating dav2d into Your Application

dav2d exposes a C API similar to dav1d's. Here's a minimal example that initializes the decoder and feeds a compressed frame:

#include <dav2d/dav2d.h>

int main() {
    Dav2dContext *ctx;
    Dav2dSettings s = {0};
    dav2d_default_settings(&s);
    
    int ret = dav2d_open(&ctx, &s);
    if (ret < 0) {
        fprintf(stderr, "Failed to open decoder\n");
        return 1;
    }
    
    // Assume we have a compressed packet in 'data' of size 'len'
    Dav2dPacket pkt = {0};
    pkt.data = data;
    pkt.sz = len;
    
    ret = dav2d_send_packet(ctx, &pkt);
    if (ret < 0) {
        fprintf(stderr, "Error sending packet\n");
        return 1;
    }
    
    Dav2dPicture pic;
    ret = dav2d_get_picture(ctx, &pic);
    if (ret == 0) {
        printf("Decoded picture: %dx%d\n", pic.p.w, pic.p.h);
        dav2d_picture_unref(&pic);
    }
    
    dav2d_close(ctx);
    return 0;
}

Compile with:

gcc -o decode_example decode_example.c $(pkg-config --cflags --libs dav2d)

This demonstrates a basic decode loop. For production use, handle multiple packets and threads.

Common Mistakes

• Missing dependencies: Ensure meson, ninja, and development headers for threads and SIMD (like nasm) are installed. On Ubuntu, run sudo apt install meson ninja-build nasm.
• Outdated spec: Because AV2 is a draft, the decoder may not handle all bitstreams correctly. Only use test clips encoded with the same draft version as dav2d targets. Check the repository's README for compatible encoder versions.
• Incorrect pixels format: dav2d decodes to planar YUV. When using ffplay, specify correct pixel format (yuv420p for 8-bit, yuv420p10le for 10-bit) and resolution.
• Library path issues: If you linked dynamically but didn't install system-wide, set LD_LIBRARY_PATH to the build directory. Otherwise, runtime errors will occur.
• Threading issues: By default, dav2d uses multiple threads. On older kernels or constrained environments, you may need to limit thread count via settings (set s.n_threads to 1 for debugging).

Summary

dav2d is an early but functional open-source AV2 decoder from VideoLAN, released while the AV2 specification is still in draft. This tutorial covered cloning, building, installing, and testing the decoder on Linux, along with a simple API usage example. The process is straightforward for those familiar with dav1d and Meson-based projects. As the AV2 standard evolves, dav2d will continue to mature — making now an exciting time to experiment with next-generation video compression.