Initialize libdav1d Decoder Context in C

This article provides a straightforward guide on how to initialize the libdav1d AV1 decoder context within a C application. It covers the necessary header inclusions, configuring the decoder settings, instantiating the context using the official API, and properly cleaning up resources to prevent memory leaks.

Step 1: Include the Header File

To use the libdav1d library, you must include its main header file in your C source code:

#include <dav1d/dav1d.h>
#include <stdio.h>

Step 2: Declare Variables

You need two primary components to initialize the decoder: 1. Dav1dSettings: A configuration structure that defines how the decoder behaves (e.g., threading models, tile limits). 2. Dav1dContext: The actual decoder instance pointer.

Dav1dSettings settings;
Dav1dContext *context = NULL;

Step 3: Populate Settings with Defaults

Before modifying any decoder settings, initialize the Dav1dSettings structure with the library’s default values using dav1d_default_settings(). This ensures all internal flags and parameters are safely populated.

dav1d_default_settings(&settings);

At this stage, you can optionally customize parameters. For example, to configure multi-threading:

// Set the number of frame threads and tile threads
settings.n_frame_threads = 4;
settings.n_tile_threads = 2;

Step 4: Open the Context

Call dav1d_open() to allocate and initialize the decoder context. This function accepts the address of your context pointer and the populated settings structure. It returns 0 on success, or a negative error code (typically an errno value) on failure.

int result = dav1d_open(&context, &settings);
if (result < 0) {
    fprintf(stderr, "Failed to initialize dav1d context: %d\n", result);
    return result;
}

Step 5: Clean Up Resources

Once your application is finished decoding frames, you must free the allocated context to prevent memory leaks. Pass the address of your context pointer to dav1d_close(). This function deallocates the context and sets your pointer to NULL.

dav1d_close(&context);

Complete Code Example

Below is a complete, minimal C program demonstrating the standard initialization and cleanup pipeline for libdav1d:

#include <dav1d/dav1d.h>
#include <stdio.h>

int main(void) {
    Dav1dSettings settings;
    Dav1dContext *context = NULL;
    int result;

    // 1. Initialize settings to default values
    dav1d_default_settings(&settings);

    // Optional: Customize configuration
    settings.n_frame_threads = 2;

    // 2. Open the decoder context
    result = dav1d_open(&context, &settings);
    if (result < 0) {
        fprintf(stderr, "Error: Could not initialize libdav1d context (Code: %d)\n", result);
        return 1;
    }

    printf("libdav1d context successfully initialized.\n");

    // 3. Clean up and close the context
    dav1d_close(&context);
    printf("libdav1d context successfully closed.\n");

    return 0;
}