Retrieve Decoded Pictures with libdav1d API

This article explains how developers can extract decoded video frames using the libdav1d API, the industry-standard open-source AV1 decoder. It covers the asynchronous decoding loop, the essential function calls needed to retrieve output frames, and how to manage the lifecycle of the returned picture structures.

To retrieve a decoded picture from libdav1d, developers must implement a non-blocking push/pull decoding loop. Because AV1 decoding is asynchronous and frames may be reordered, feeding an input packet does not guarantee an immediate output frame.

1. Feed the Decoder with Data

Before you can retrieve a decoded picture, you must submit compressed AV1 bitstream data to the decoder context using dav1d_send_data.

Dav1dData data;
// Initialize and populate your Dav1dData structure with compressed packet data
int res = dav1d_send_data(context, &data);

2. Retrieve the Decoded Frame

Once data has been sent to the decoder, you call dav1d_get_picture to retrieve a decoded frame. This function should be called in a loop until it returns EAGAIN, which indicates that the decoder needs more input data before it can produce more output.

Dav1dPicture pic = { 0 };
int res = dav1d_get_picture(context, &pic);

3. Handle the Return Codes

The dav1d_get_picture function returns an integer status code that dictates your next step: * 0 (Success): A picture was successfully retrieved. You can now access the pixel data inside the Dav1dPicture struct. * DAG_EINVAL / Other Errors: An error occurred during decoding. * EAGAIN: No picture is currently available. You must feed more input data using dav1d_send_data before calling dav1d_get_picture again.

4. Access Frame Data and Metadata

When dav1d_get_picture succeeds, the Dav1dPicture structure contains the raw YUV (or Gray/RGB depending on the stream) pixel data and metadata: * pic.data[0], pic.data[1], pic.data[2]: Pointers to the plane buffers (Luma, Chroma U, Chroma V). * pic.stride[0], pic.stride[1]: Plane strides (byte offsets between consecutive lines of pixels). * pic.p.w and pic.p.h: Width and height of the picture. * pic.p.layout: Pixel layout (e.g., 4:2:0, 4:2:2, 4:4:0, or 4:0:0).

5. Release the Picture Reference

libdav1d uses reference counting for its output buffers. Once you are finished processing or copying the picture data, you must release the picture reference to prevent memory leaks. Use the dav1d_picture_unref function to safely return the buffer back to the decoder’s pool.

dav1d_picture_unref(&pic);