### Compile dav1d using Meson and Ninja

Source: https://github.com/videolan/dav1d/blob/master/README.md

General compilation steps for dav1d. Ensure Meson, Ninja, and nasm are installed. Create a build directory, configure with meson setup, and compile with ninja.

```bash
mkdir build && cd build
meson setup ..
ninja
```

--------------------------------

### Configure dav1d for Static Linking

Source: https://github.com/videolan/dav1d/blob/master/README.md

Modify the meson setup command to enable static linking by adding the --default-library=static flag.

```bash
meson setup .. --default-library=static
```

--------------------------------

### Setup dav1d Test Data

Source: https://github.com/videolan/dav1d/blob/master/README.md

Clone the dav1d-test-data repository to fetch necessary test data.

```bash
git clone https://code.videolan.org/videolan/dav1d-test-data.git tests/dav1d-test-data
```

--------------------------------

### Build dav1d Documentation

Source: https://github.com/videolan/dav1d/blob/master/README.md

Compile dav1d documentation. Ensure doxygen and graphviz are installed. Configure meson with -Denable_docs=true and build using ninja doc/html.

```bash
meson setup .. -Denable_docs=true
ninja doc/html
```

--------------------------------

### Cross-Compile dav1d for Windows x64

Source: https://github.com/videolan/dav1d/blob/master/README.md

Configure meson for cross-compilation to 64-bit Windows. Requires mingw-w64 to be installed.

```bash
meson setup .. --cross-file=../package/crossfiles/x86_64-w64-mingw32.meson
```

--------------------------------

### Cross-Compile dav1d for Windows x32

Source: https://github.com/videolan/dav1d/blob/master/README.md

Configure meson for cross-compilation to 32-bit Windows. Requires mingw-w64 to be installed.

```bash
meson setup .. --cross-file=../package/crossfiles/i686-w64-mingw32.meson
```

--------------------------------

### Print dav1d Library Version

Source: https://context7.com/videolan/dav1d/llms.txt

Display the installed version of the dav1d library. This command is useful for checking compatibility or reporting issues.

```bash
dav1d --version
```

--------------------------------

### Dav1d CLI Tool Usage Examples

Source: https://context7.com/videolan/dav1d/llms.txt

The dav1d command-line tool decodes AV1 bitstreams to various output formats. Use flags to specify input/output files, thread count, frame delay, and other options.

```sh
# Decode an IVF file to YUV4MPEG2
dav1d -i input.ivf -o output.y4m
```

```sh
# Decode to raw YUV with 8 threads, low-latency (frame delay=1)
dav1d -i input.ivf -o output.yuv --threads 8 --framedelay 1
```

--------------------------------

### Query dav1d Library Version

Source: https://context7.com/videolan/dav1d/llms.txt

Use `dav1d_version()` to get a human-readable version string and `dav1d_version_api()` with macros to check ABI compatibility. Verify major version match and that the library's minor version is greater than or equal to the tool's minor version.

```c
#include "dav1d/dav1d.h"
#include <stdio.h>

int main(void) {
    // Human-readable release version string, e.g. "1.5.3"
    const char *ver = dav1d_version();
    printf("dav1d version: %s\n", ver);

    // Packed API version: 0x00XXYYZZ (major=XX, minor=YY, patch=ZZ)
    unsigned api = dav1d_version_api();
    printf("API version: %d.%d.%d\n",
           DAV1D_API_MAJOR(api),
           DAV1D_API_MINOR(api),
           DAV1D_API_PATCH(api));

    // Compatibility check: same major, library minor >= tool minor
    if (DAV1D_API_VERSION_MAJOR != DAV1D_API_MAJOR(api) ||
        DAV1D_API_VERSION_MINOR  > DAV1D_API_MINOR(api))
    {
        fprintf(stderr, "Library/tool version mismatch!\n");
        return 1;
    }
    return 0;
}
// Output:
// dav1d version: 1.5.3
// API version: 7.0.0

```

--------------------------------

### Retrieve Decoded Frames with Dav1d

Source: https://context7.com/videolan/dav1d/llms.txt

Call `dav1d_get_picture` to get the next decoded frame. The caller owns the picture and must call `dav1d_picture_unref`. Returns `DAV1D_ERR(EAGAIN)` if more input is needed. Repeated calls drain all buffered frames at end-of-stream.

```c
#include "dav1d/dav1d.h"
#include <errno.h>
#include <stdio.h>

void process_picture(const Dav1dPicture *p) {
    // p->p.w, p->p.h  — dimensions in pixels
    // p->p.bpc        — 8 or 10 bits per component
    // p->p.layout     — DAV1D_PIXEL_LAYOUT_I420 / I422 / I444 / I400
    // p->data[0/1/2]  — Y / U / V plane pointers
    // p->stride[0]    — luma stride in bytes
    // p->stride[1]    — chroma stride in bytes
    printf("Frame %dx%d %dbpc layout=%d\n",
           p->p.w, p->p.h, p->p.bpc, (int)p->p.layout);
}

// Full decode loop including EOS drain:
int decode_loop(Dav1dContext *c, Dav1dData *data,
                int (*read_data)(Dav1dData *)) {
    int res = 0;

    do {
        res = dav1d_send_data(c, data);
        if (res < 0 && res != DAV1D_ERR(EAGAIN))
            return res;

        Dav1dPicture p = { 0 };
        res = dav1d_get_picture(c, &p);
        if (res == 0) {
            process_picture(&p);
            dav1d_picture_unref(&p);
        } else if (res != DAV1D_ERR(EAGAIN)) {
            return res;
        }
    } while (data->sz > 0 || read_data(data) == 0);

    // EOS drain
    Dav1dPicture p = { 0 };
    while ((res = dav1d_get_picture(c, &p)) == 0) {
        process_picture(&p);
        dav1d_picture_unref(&p);
    }
    return (res == DAV1D_ERR(EAGAIN)) ? 0 : res;
}
```

--------------------------------

### Retrieve Decode Error Metadata with dav1d_get_decode_error_data_props

Source: https://context7.com/videolan/dav1d/llms.txt

Call dav1d_get_decode_error_data_props after a non-EAGAIN error from dav1d_send_data() or dav1d_get_picture() to get metadata about the problematic input packet. The caller is responsible for freeing the returned Dav1dDataProps using dav1d_data_props_unref().

```c
#include "dav1d/dav1d.h"
#include <stdio.h>
#include <errno.h>

void handle_decode_error(Dav1dContext *c, int err) {
    if (err >= 0 || err == DAV1D_ERR(EAGAIN))
        return;

    Dav1dDataProps props;
    if (dav1d_get_decode_error_data_props(c, &props) == 0) {
        fprintf(stderr, "Decode error on packet: ts=%
```

```c
PRId64 " offset=%
```

```c
PRId64 " size=%zu\n",
                props.timestamp, props.offset, props.size);
        dav1d_data_props_unref(&props);
    }
}
```

--------------------------------

### Run dav1d Tests with Test Data

Source: https://github.com/videolan/dav1d/blob/master/README.md

Configure meson with -Dtestdata_tests=true and run tests using 'meson test -v' after compiling.

```bash
meson test -v
```

--------------------------------

### Run Dav1d Decoder Conformance Tests

Source: https://github.com/videolan/dav1d/blob/master/README.md

Execute the dav1d conformance tests using the provided script and bitstreams. Ensure you have downloaded and extracted the argon conformance bitstreams.

```bash
tar -xvf argon.tar.zst
```

```bash
tests/dav1d_argon.bash -d build/tools/dav1d -a argon
```

--------------------------------

### Initialize dav1d Decoder Settings

Source: https://context7.com/videolan/dav1d/llms.txt

Call `dav1d_default_settings()` to populate a `Dav1dSettings` struct with safe defaults before opening a decoder. This ensures forward compatibility. Customize fields like `n_threads`, `max_frame_delay`, `apply_grain`, and `inloop_filters` as needed.

```c
#include "dav1d/dav1d.h"

Dav1dSettings s;
dav1d_default_settings(&s);

// Defaults after the call:
// s.n_threads          = 0  (auto-detect logical CPU count)
// s.max_frame_delay    = 0  (auto: ceil(sqrt(n_threads)))
// s.apply_grain        = 1  (film grain applied by dav1d_get_picture)
// s.operating_point    = 0  (base layer)
// s.all_layers         = 1  (output all spatial SVC layers)
// s.frame_size_limit   = 0  (unlimited)
// s.inloop_filters     = DAV1D_INLOOPFILTER_ALL
// s.decode_frame_type  = DAV1D_DECODEFRAMETYPE_ALL
// s.strict_std_compliance = 0
// s.output_invisible_frames = 0

// Override for low-latency single-threaded use:
s.n_threads       = 1;
s.max_frame_delay = 1;

// Override to skip film grain (e.g. for GPU-side application):
s.apply_grain = 0;

// Disable loop-restoration post-filter for speed:
s.inloop_filters = DAV1D_INLOOPFILTER_DEBLOCK | DAV1D_INLOOPFILTER_CDEF;

```

--------------------------------

### Cross-Compile dav1d for Linux 32-bit

Source: https://github.com/videolan/dav1d/blob/master/README.md

Configure meson for cross-compilation to 32-bit Linux.

```bash
meson setup .. --cross-file=../package/crossfiles/i686-linux32.meson
```

--------------------------------

### dav1d_default_settings

Source: https://context7.com/videolan/dav1d/llms.txt

Initializes a `Dav1dSettings` struct with safe default values. This function should always be called before customizing individual settings to ensure forward compatibility.

```APIDOC
## dav1d_default_settings 

### Description
Initializes a `Dav1dSettings` struct with safe default values before a decoder context is opened. Always call this before customizing individual fields to ensure forward compatibility when new fields are added.

### Method
C Function

### Parameters
- **s** (*Dav1dSettings*)
  - Output: A pointer to a `Dav1dSettings` struct to be populated with default values.

### Request Example
```c
#include "dav1d/dav1d.h"

Dav1dSettings s;
dav1d_default_settings(&s);

// Defaults after the call:
// s.n_threads          = 0  (auto-detect logical CPU count)
// s.max_frame_delay    = 0  (auto: ceil(sqrt(n_threads)))
// s.apply_grain        = 1  (film grain applied by dav1d_get_picture)
// s.operating_point    = 0  (base layer)
// s.all_layers         = 1  (output all spatial SVC layers)
// s.frame_size_limit   = 0  (unlimited)
// s.inloop_filters     = DAV1D_INLOOPFILTER_ALL
// s.decode_frame_type  = DAV1D_DECODEFRAMETYPE_ALL
// s.strict_std_compliance = 0
// s.output_invisible_frames = 0

// Override for low-latency single-threaded use:
s.n_threads       = 1;
s.max_frame_delay = 1;

// Override to skip film grain (e.g. for GPU-side application):
s.apply_grain = 0;

// Disable loop-restoration post-filter for speed:
s.inloop_filters = DAV1D_INLOOPFILTER_DEBLOCK | DAV1D_INLOOPFILTER_CDEF;
```

### Response
No direct return value, but the `Dav1dSettings` struct is populated.
```

--------------------------------

### Manage Input Data Buffers with Dav1d

Source: https://context7.com/videolan/dav1d/llms.txt

Use `dav1d_data_create` for library-managed allocation or `dav1d_data_wrap` to wrap existing buffers without copying. `dav1d_data_unref` releases references; ownership is transferred on successful submission.

```c
#include "dav1d/dav1d.h"
#include <string.h>
#include <stdio.h>

// --- Method 1: library-managed allocation ---
static int fill_from_library_alloc(Dav1dData *data, const uint8_t *src, size_t sz) {
    uint8_t *buf = dav1d_data_create(data, sz);
    if (!buf) return -1;
    memcpy(buf, src, sz);
    // Optionally set metadata:
    data->m.timestamp = 1000; // container PTS in timebase units
    data->m.offset    = 0;    // byte offset in stream
    return 0;
}

// --- Method 2: zero-copy wrap of existing buffer ---
static void my_free(const uint8_t *buf, void *cookie) {
    free((void *)buf); // or release back to your pool
}

static int fill_from_existing(Dav1dData *data, uint8_t *src, size_t sz) {
    int res = dav1d_data_wrap(data, src, sz, my_free, NULL);
    if (res < 0) {
        fprintf(stderr, "dav1d_data_wrap failed: %d\n", res);
        return res;
    }
    return 0;
}

// --- Cleanup if dav1d_send_data was never called ---
static void discard(Dav1dData *data) {
    if (data->sz > 0)
        dav1d_data_unref(data); // triggers my_free callback
}
```

--------------------------------

### Open dav1d Decoder Context

Source: https://context7.com/videolan/dav1d/llms.txt

Use `dav1d_open()` to allocate and initialize a `Dav1dContext` with specified settings. This context is essential for all decoding operations and must be paired with `dav1d_close()`. Handle potential negative return values indicating errors.

```c
#include "dav1d/dav1d.h"
#include <stdlib.h>
#include <stdio.h>

int open_decoder(Dav1dContext **c_out) {
    Dav1dSettings s;
    dav1d_default_settings(&s);
    s.n_threads = 4;
    s.max_frame_delay = 2;

    int res = dav1d_open(c_out, &s);
    if (res < 0) {
        fprintf(stderr, "dav1d_open failed: %s (code %d)\n",
                strerror(-res), res);
        return res;
    }
    return 0;
    // Caller is responsible for calling dav1d_close(c_out) when done.
}

```

--------------------------------

### Decode and Verify with MD5 Checksum

Source: https://context7.com/videolan/dav1d/llms.txt

Use this command to decode an input IVF file and verify its integrity against a pre-computed MD5 checksum file. Ensure 'expected.md5' contains the correct checksum for 'input.ivf'.

```bash
dav1d -i input.ivf --verify expected.md5
```

--------------------------------

### Custom Picture Buffer Allocator for Dav1d

Source: https://context7.com/videolan/dav1d/llms.txt

Implement a custom picture buffer allocator by providing alloc_picture_callback and release_picture_callback functions. This allows for zero-copy integration with GPU or custom memory pools. Buffers must be aligned to DAV1D_PICTURE_ALIGNMENT (64 bytes) and padded.

```c
#include "dav1d/dav1d.h"
#include <stdlib.h>
#include <stdio.h>

static int my_alloc(Dav1dPicture *pic, void *cookie) {
    const int hbd       = pic->p.bpc > 8;
    const int aw        = (pic->p.w + 127) & ~127; // 128-pixel alignment
    const int ah        = (pic->p.h + 127) & ~127;
    const int has_chroma = pic->p.layout != DAV1D_PIXEL_LAYOUT_I400;
    const int ss_hor    = pic->p.layout != DAV1D_PIXEL_LAYOUT_I444;
    const int ss_ver    = pic->p.layout == DAV1D_PIXEL_LAYOUT_I420;

    ptrdiff_t y_stride  = aw << hbd;
    ptrdiff_t uv_stride = has_chroma ? y_stride >> ss_hor : 0;
    pic->stride[0] = y_stride;
    pic->stride[1] = uv_stride;

    size_t y_sz  = y_stride  * ah;
    size_t uv_sz = uv_stride * (ah >> ss_ver);
    uint8_t *buf = aligned_alloc(DAV1D_PICTURE_ALIGNMENT,
                                 y_sz + 2 * uv_sz + DAV1D_PICTURE_ALIGNMENT);
    if (!buf) return DAV1D_ERR(ENOMEM);

    pic->data[0] = buf;
    pic->data[1] = has_chroma ? buf + y_sz             : NULL;
    pic->data[2] = has_chroma ? buf + y_sz + uv_sz     : NULL;
    pic->allocator_data = buf;
    return 0;
}

static void my_release(Dav1dPicture *pic, void *cookie) {
    free(pic->allocator_data);
}

// Wire into settings:
Dav1dSettings s;
dav1d_default_settings(&s);
s.allocator = (Dav1dPicAllocator) {
    .cookie = NULL,
    .alloc_picture_callback   = my_alloc,
    .release_picture_callback = my_release,
};
```

--------------------------------

### Custom Log Callback for Dav1d

Source: https://context7.com/videolan/dav1d/llms.txt

Replace default stderr logging with a custom vprintf-compatible callback by setting the Dav1dLogger. Setting callback to NULL silences all library logs. A cookie can be passed for context.

```c
#include "dav1d/dav1d.h"
#include <stdarg.h>
#include <stdio.h>

static void my_logger(void *cookie, const char *fmt, va_list ap) {
    FILE *log_file = (FILE *)cookie;
    fprintf(log_file, "[dav1d] ");
    vfprintf(log_file, fmt, ap);
}

Dav1dSettings s;
dav1d_default_settings(&s);
s.logger = (Dav1dLogger) {
    .cookie   = stderr,        // pass any context pointer
    .callback = my_logger,
};
// To suppress all logging:
// s.logger.callback = NULL;
```

--------------------------------

### Realtime Playback Pacing with Caching

Source: https://context7.com/videolan/dav1d/llms.txt

Decode an input IVF file with realtime playback pacing, matching the input frame rate. This command caches 4 frames ahead and outputs to 'output.y4m'.

```bash
dav1d -i input.ivf -o output.y4m --realtime input --realtime-cache 4
```

--------------------------------

### dav1d_version / dav1d_version_api

Source: https://context7.com/videolan/dav1d/llms.txt

Query the release version string or a packed integer API version of the dav1d library. It's crucial to verify ABI compatibility at startup.

```APIDOC
## dav1d_version / dav1d_version_api 

### Description
Query the release version string or a packed integer API version of the dav1d library. Callers should verify ABI compatibility at startup.

### Method
C Function

### Parameters
None

### Request Example
```c
#include "dav1d/dav1d.h"
#include <stdio.h>

int main(void) {
    // Human-readable release version string, e.g. "1.5.3"
    const char *ver = dav1d_version();
    printf("dav1d version: %s\n", ver);

    // Packed API version: 0x00XXYYZZ (major=XX, minor=YY, patch=ZZ)
    unsigned api = dav1d_version_api();
    printf("API version: %d.%d.%d\n",
           DAV1D_API_MAJOR(api),
           DAV1D_API_MINOR(api),
           DAV1D_API_PATCH(api));

    // Compatibility check: same major, library minor >= tool minor
    if (DAV1D_API_VERSION_MAJOR != DAV1D_API_MAJOR(api) ||
        DAV1D_API_VERSION_MINOR  > DAV1D_API_MINOR(api)) {
        fprintf(stderr, "Library/tool version mismatch!\n");
        return 1;
    }
    return 0;
}
```

### Response
#### Success Response
Returns the version information.

#### Response Example
```
dav1d version: 1.5.3
API version: 7.0.0
```
```

--------------------------------

### Benchmark Decode Speed with Null Output

Source: https://context7.com/videolan/dav1d/llms.txt

Measure the decode speed of an input IVF file without writing any output. This is useful for benchmarking performance. Specify the number of threads and quiet mode for cleaner output.

```bash
dav1d -i input.ivf -o /dev/null --threads 16 --quiet
```

--------------------------------

### dav1d_open

Source: https://context7.com/videolan/dav1d/llms.txt

Allocates and opens a decoder context using the provided settings. This context is the central object for all decode operations and must be paired with `dav1d_close()`.

```APIDOC
## dav1d_open 

### Description
Allocates and opens a decoder context using the provided settings. The returned context is the central object for all subsequent decode operations. Must be paired with `dav1d_close()`.

### Method
C Function

### Parameters
- **c_out** (*Dav1dContext **)
  - Output: A pointer to a `Dav1dContext` pointer that will be set to the newly allocated decoder context.
- **s** (*const Dav1dSettings *)
  - Input: A pointer to a `Dav1dSettings` struct containing the desired decoder configuration.

### Request Example
```c
#include "dav1d/dav1d.h"
#include <stdlib.h>
#include <stdio.h>

int open_decoder(Dav1dContext **c_out) {
    Dav1dSettings s;
    dav1d_default_settings(&s);
    s.n_threads = 4;
    s.max_frame_delay = 2;

    int res = dav1d_open(c_out, &s);
    if (res < 0) {
        fprintf(stderr, "dav1d_open failed: %s (code %d)\n",
                strerror(-res), res);
        return res;
    }
    return 0;
    // Caller is responsible for calling dav1d_close(c_out) when done.
}
```

### Response
#### Success Response (0)
Returns 0 on success. The `Dav1dContext` pointer is set via `c_out`.

#### Error Response (< 0)
Returns a negative error code on failure. Common errors include:
- `EINVAL`: Invalid settings provided.
- `ENOMEM`: Memory allocation failed.
```

--------------------------------

### Dav1dPicAllocator

Source: https://context7.com/videolan/dav1d/llms.txt

Allows for custom picture buffer allocation and release, enabling integration with GPU or custom memory pools.

```APIDOC
## Dav1dPicAllocator — Custom picture buffer allocator

### Description
Hooks into the decoder's frame buffer lifecycle via `alloc_picture_callback` and `release_picture_callback`. Enables zero-copy integration with GPU upload paths, hardware decoders, or custom memory pools. Buffers must be aligned to `DAV1D_PICTURE_ALIGNMENT` (64) bytes and padded by the same amount.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```c
#include "dav1d/dav1d.h"
#include <stdlib.h>
#include <stdio.h>

static int my_alloc(Dav1dPicture *pic, void *cookie) {
    const int hbd       = pic->p.bpc > 8;
    const int aw        = (pic->p.w + 127) & ~127; // 128-pixel alignment
    const int ah        = (pic->p.h + 127) & ~127;
    const int has_chroma = pic->p.layout != DAV1D_PIXEL_LAYOUT_I400;
    const int ss_hor    = pic->p.layout != DAV1D_PIXEL_LAYOUT_I444;
    const int ss_ver    = pic->p.layout == DAV1D_PIXEL_LAYOUT_I420;

    ptrdiff_t y_stride  = aw << hbd;
    ptrdiff_t uv_stride = has_chroma ? y_stride >> ss_hor : 0;
    pic->stride[0] = y_stride;
    pic->stride[1] = uv_stride;

    size_t y_sz  = y_stride  * ah;
    size_t uv_sz = uv_stride * (ah >> ss_ver);
    uint8_t *buf = aligned_alloc(DAV1D_PICTURE_ALIGNMENT,
                                 y_sz + 2 * uv_sz + DAV1D_PICTURE_ALIGNMENT);
    if (!buf) return DAV1D_ERR(ENOMEM);

    pic->data[0] = buf;
    pic->data[1] = has_chroma ? buf + y_sz             : NULL;
    pic->data[2] = has_chroma ? buf + y_sz + uv_sz     : NULL;
    pic->allocator_data = buf;
    return 0;
}

static void my_release(Dav1dPicture *pic, void *cookie) {
    free(pic->allocator_data);
}

// Wire into settings:
Dav1dSettings s;
dav1d_default_settings(&s);
s.allocator = (Dav1dPicAllocator) {
    .cookie = NULL,
    .alloc_picture_callback   = my_alloc,
    .release_picture_callback = my_release,
};
```

### Response
This section describes the callbacks within `Dav1dPicAllocator`:

#### `alloc_picture_callback`
- **pic** (Dav1dPicture*) - Pointer to the `Dav1dPicture` structure to be allocated.
- **cookie** (void*) - User-provided cookie passed to the allocator.
- **Returns** (int) - 0 on success, or a negative error code (e.g., `DAV1D_ERR(ENOMEM)`) on failure.

#### `release_picture_callback`
- **pic** (Dav1dPicture*) - Pointer to the `Dav1dPicture` structure to be released.
- **cookie** (void*) - User-provided cookie passed to the allocator.
```

--------------------------------

### dav1d_data_create / dav1d_data_wrap / dav1d_data_unref

Source: https://context7.com/videolan/dav1d/llms.txt

Manage input data buffers for the dav1d decoder. These functions allow for allocating new buffers, wrapping existing ones to avoid copies, and releasing references to data.

```APIDOC
## dav1d_data_create / dav1d_data_wrap / dav1d_data_unref

### Description
Manage input data buffers for the dav1d decoder. `dav1d_data_create` allocates a new reference-counted buffer, `dav1d_data_wrap` wraps an existing buffer with a user-supplied free callback, and `dav1d_data_unref` releases the reference.

### Functions

#### `dav1d_data_create(Dav1dData *data, size_t sz)`

Allocates a new reference-counted buffer of `sz` bytes and returns a writable pointer.

#### `dav1d_data_wrap(Dav1dData *data, const uint8_t *buf, size_t sz, dav1d_free_callback cb, void *cookie)`

Wraps an existing buffer with a user-supplied free callback, avoiding a copy. `cb` is the callback function to be called when the buffer is no longer needed. `cookie` is a user-supplied value passed to the callback.

#### `dav1d_data_unref(Dav1dData *data)`

Releases the reference to the data buffer. Ownership of a successfully sent `Dav1dData` is transferred to the library.
```

--------------------------------

### Reset Decoder State for Seeking (dav1d_flush)

Source: https://context7.com/videolan/dav1d/llms.txt

Discards all buffered frames and resets the decoder state. Use before seeking. Decoding will not resume until a new Sequence Header OBU is received.

```c
#include "dav1d/dav1d.h"

void seek_to(Dav1dContext *c, long new_byte_offset,
             FILE *stream, Dav1dData *pending_data) {
    // Discard any partially buffered data
    if (pending_data->sz > 0)
        dav1d_data_unref(pending_data);

    // Reset the decoder — discards all buffered/reference frames
    dav1d_flush(c);

    // Seek the underlying byte stream
    fseek(stream, new_byte_offset, SEEK_SET);

    // The next dav1d_send_data() call must contain a Sequence Header OBU
    // for decoding to resume. Use dav1d_parse_sequence_header() to scan
    // ahead if the seek position is uncertain.
}
```

--------------------------------

### Dav1dLogger

Source: https://context7.com/videolan/dav1d/llms.txt

Provides a custom logging callback to replace or control dav1d's default logging behavior.

```APIDOC
## Dav1dLogger — Custom log callback

### Description
Replaces the default stderr logging with a user-supplied `vprintf`-compatible callback. Setting `callback = NULL` silences all library log output entirely. The `cookie` pointer is forwarded to every call.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```c
#include "dav1d/dav1d.h"
#include <stdarg.h>
#include <stdio.h>

static void my_logger(void *cookie, const char *fmt, va_list ap) {
    FILE *log_file = (FILE *)cookie;
    fprintf(log_file, "[dav1d] ");
    vfprintf(log_file, fmt, ap);
}

Dav1dSettings s;
dav1d_default_settings(&s);
s.logger = (Dav1dLogger) {
    .cookie   = stderr,        // pass any context pointer
    .callback = my_logger,
};
// To suppress all logging:
// s.logger.callback = NULL;
```

### Response
This section describes the callbacks within `Dav1dLogger`:

#### `callback`
- **cookie** (void*) - User-provided context pointer.
- **fmt** (const char*) - The format string for the log message.
- **ap** (va_list) - Variable arguments for the format string.
- **Returns** (void) - This callback does not return a value.
```

--------------------------------

### Apply Film Grain (dav1d_apply_grain)

Source: https://context7.com/videolan/dav1d/llms.txt

Applies AV1 film grain synthesis to a picture decoded with apply_grain=0. If no metadata exists, returns a new reference to the same data. Useful for GPU-side synthesis with a CPU fallback.

```c
#include "dav1d/dav1d.h"
#include <stdio.h>

// decode with apply_grain = 0 in Dav1dSettings, then:
int apply_grain_if_present(Dav1dContext *c,
                            const Dav1dPicture *decoded,
                            Dav1dPicture *out_with_grain) {
    int res = dav1d_apply_grain(c, out_with_grain, decoded);
    if (res < 0) {
        fprintf(stderr, "dav1d_apply_grain error: %d\n", res);
        return res;
    }
    // out_with_grain now owns a reference — call dav1d_picture_unref() when done.
    // The original `decoded` picture still holds its own reference.
    return 0;
}
```

--------------------------------

### Decode Limited Frames and Skip Frames

Source: https://context7.com/videolan/dav1d/llms.txt

Decode only the first 100 frames of an input IVF file and skip the initial 10 frames. The decoded output will be saved to 'output.yuv'.

```bash
dav1d -i input.ivf -o output.yuv --limit 100 --skip 10
```

--------------------------------

### Query Decoder Events (dav1d_get_event_flags)

Source: https://context7.com/videolan/dav1d/llms.txt

Returns accumulated Dav1dEventFlags since the last call, clearing them afterward. Flags indicate new sequences or updated operating parameters.

```c
#include "dav1d/dav1d.h"
#include <stdio.h>

void check_events(Dav1dContext *c) {
    enum Dav1dEventFlags flags;
    if (dav1d_get_event_flags(c, &flags) < 0)
        return;

    if (flags & DAV1D_EVENT_FLAG_NEW_SEQUENCE) {
        printf("New coded sequence detected — reinitialize downstream pipeline\n");
    }
    if (flags & DAV1D_EVENT_FLAG_NEW_OP_PARAMS_INFO) {
        printf("Operating parameters info updated\n");
    }
}
```

--------------------------------

### Query Decoder Frame Delay with dav1d_get_frame_delay

Source: https://context7.com/videolan/dav1d/llms.txt

Use dav1d_get_frame_delay to determine the number of frames the decoder will buffer. This is useful for sizing upstream queues or calculating output latency. The function returns a value between 1 and max_frame_delay.

```c
#include "dav1d/dav1d.h"
#include <stdio.h>

void report_delay(void) {
    Dav1dSettings s;
    dav1d_default_settings(&s);
    s.n_threads = 8;
    // max_frame_delay = 0 means auto: ceil(sqrt(8)) = 3

    int delay = dav1d_get_frame_delay(&s);
    if (delay < 0) {
        fprintf(stderr, "dav1d_get_frame_delay error: %d\n", delay);
        return;
    }
    printf("Decoder will buffer up to %d frame(s)\n", delay);
    // Output (with n_threads=8): Decoder will buffer up to 3 frame(s)

    // For zero-latency use:
    s.n_threads = 1;
    s.max_frame_delay = 1;
    delay = dav1d_get_frame_delay(&s);
    printf("Low-latency delay: %d frame(s)\n", delay);
    // Output: Low-latency delay: 1 frame(s)
}
```

--------------------------------

### Feed Bitstream Data to Dav1d Decoder

Source: https://context7.com/videolan/dav1d/llms.txt

Use `dav1d_send_data` to submit AV1 OBUs. On success (0), ownership transfers. Returns `DAV1D_ERR(EAGAIN)` if the internal queue is full, requiring `dav1d_get_picture()` to be called first.

```c
#include "dav1d/dav1d.h"
#include <errno.h>
#include <stdio.h>

// Returns 0 on successful send, DAV1D_ERR(EAGAIN) if caller must drain first,
// or another negative error code on fatal error.
int send_packet(Dav1dContext *c, Dav1dData *data) {
    int res = dav1d_send_data(c, data);
    if (res == 0) {
        // data->sz is now 0; ownership transferred; do NOT call dav1d_data_unref.
        return 0;
    }
    if (res == DAV1D_ERR(EAGAIN)) {
        // Internal queue full — caller must call dav1d_get_picture() first.
        return res;
    }
    // Fatal error: ownership NOT transferred; caller must unref.
    dav1d_data_unref(data);
    fprintf(stderr, "dav1d_send_data error: %s\n", strerror(-res));
    return res;
}
```

--------------------------------

### dav1d_get_frame_delay

Source: https://context7.com/videolan/dav1d/llms.txt

Queries the decoder's internal frame buffering delay based on provided settings. This is useful for sizing upstream queues or calculating output latency.

```APIDOC
## dav1d_get_frame_delay — Query decoder frame delay

### Description
Returns the number of frames the decoder will buffer internally (not counting reference frames) for a given `Dav1dSettings`. The value is in `[1, max_frame_delay]`. Use this to size upstream demux queues or to calculate the expected output latency before the pipeline is primed.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```c
#include "dav1d/dav1d.h"
#include <stdio.h>

void report_delay(void) {
    Dav1dSettings s;
    dav1d_default_settings(&s);
    s.n_threads = 8;
    // max_frame_delay = 0 means auto: ceil(sqrt(8)) = 3

    int delay = dav1d_get_frame_delay(&s);
    if (delay < 0) {
        fprintf(stderr, "dav1d_get_frame_delay error: %d\n", delay);
        return;
    }
    printf("Decoder will buffer up to %d frame(s)\n", delay);
    // Output (with n_threads=8): Decoder will buffer up to 3 frame(s)

    // For zero-latency use:
    s.n_threads = 1;
    s.max_frame_delay = 1;
    delay = dav1d_get_frame_delay(&s);
    printf("Low-latency delay: %d frame(s)\n", delay);
    // Output: Low-latency delay: 1 frame(s)
}
```

### Response
#### Success Response (0)
- **delay** (int) - The number of frames the decoder will buffer internally. Returns a negative value on error.
```

--------------------------------

### dav1d_get_picture

Source: https://context7.com/videolan/dav1d/llms.txt

Retrieve a decoded frame from the decoder. This function returns the next decoded `Dav1dPicture` in display order. The caller takes ownership and must call `dav1d_picture_unref()` when finished.

```APIDOC
## dav1d_get_picture

### Description
Retrieve a decoded frame from the decoder. Returns the next decoded `Dav1dPicture` in display order. The caller takes ownership and must call `dav1d_picture_unref()` when finished. Returns `DAV1D_ERR(EAGAIN)` when more input is needed. To drain all buffered frames at end-of-stream, call repeatedly until `EAGAIN` is returned.

### Method
`int dav1d_get_picture(Dav1dContext *c, Dav1dPicture *p)`

### Parameters

- `c` (*Dav1dContext*): Pointer to the dav1d decoder context.
- `p` (*Dav1dPicture*): Pointer to a `Dav1dPicture` structure to be filled with the decoded frame data.

### Return Value

- `0`: Success. A decoded picture is available in `p`.
- `DAV1D_ERR(EAGAIN)`: More input is needed by the decoder. Call `dav1d_send_data()`.
- Negative error code: A fatal error occurred.
```

--------------------------------

### dav1d_send_data

Source: https://context7.com/videolan/dav1d/llms.txt

Feed OBU bitstream data to the decoder. This function submits one or more concatenated AV1 OBUs for decoding. Ownership of the `Dav1dData` reference transfers to the library on success.

```APIDOC
## dav1d_send_data

### Description
Feed OBU bitstream data to the decoder. Submits one or more concatenated AV1 OBUs for decoding. On success (`0`), ownership of the `Dav1dData` reference transfers to the library. Returns `DAV1D_ERR(EAGAIN)` when the decoder's internal frame queue is full and `dav1d_get_picture()` must be called first to drain a frame.

### Method
`int dav1d_send_data(Dav1dContext *c, Dav1dData *data)`

### Parameters

- `c` (*Dav1dContext*): Pointer to the dav1d decoder context.
- `data` (*Dav1dData*): Pointer to the `Dav1dData` structure containing the bitstream data.

### Return Value

- `0`: Success. Ownership of `data` is transferred to the library.
- `DAV1D_ERR(EAGAIN)`: The decoder's internal queue is full. Call `dav1d_get_picture()` to drain a frame.
- Negative error code: A fatal error occurred. Ownership of `data` is NOT transferred; the caller must call `dav1d_data_unref()`.
```

--------------------------------

### Parse Sequence Header (dav1d_parse_sequence_header)

Source: https://context7.com/videolan/dav1d/llms.txt

Parses a Dav1dSequenceHeader from a buffer without a Dav1dContext. Useful for probing stream parameters before opening a decoder or scanning after a seek.

```c
#include "dav1d/dav1d.h"
#include <stdio.h>
#include <errno.h>

int probe_stream(const uint8_t *buf, size_t sz) {
    Dav1dSequenceHeader seq;
    int res = dav1d_parse_sequence_header(&seq, buf, sz);
    if (res == DAV1D_ERR(ENOENT)) {
        printf("No Sequence Header OBU found in buffer\n");
        return -1;
    }
    if (res < 0) {
        fprintf(stderr, "Parse error: %s\n", strerror(-res));
        return res;
    }

    printf("Profile: %u\n", seq.profile);
    printf("Max dimensions: %dx%d\n", seq.max_width, seq.max_height);
    printf("Pixel layout: %d (0=mono,1=I420,2=I422,3=I444)\n", (int)seq.layout);
    printf("Bit depth index: %u (0=8bpc, 1=10bpc, 2=12bpc)\n", seq.hbd);
    printf("Color range: %s\n", seq.color_range ? "JPEG [0,255]" : "MPEG [16,235]");
    printf("Film grain: %s\n", seq.film_grain_present ? "yes" : "no");
    // Color primaries: seq.pri, transfer: seq.trc, matrix: seq.mtrx
    return 0;
}
```

--------------------------------

### Close dav1d Decoder Context

Source: https://context7.com/videolan/dav1d/llms.txt

Call `dav1d_close()` to free a `Dav1dContext` and release all associated memory. This function sets the context pointer to NULL upon successful completion. It also implicitly flushes any buffered frames without outputting them.

```c
#include "dav1d/dav1d.h"

void cleanup(Dav1dContext **c) {
    if (*c) {
        dav1d_close(c);
        // *c is now NULL
    }
}

```

--------------------------------

### dav1d_flush

Source: https://context7.com/videolan/dav1d/llms.txt

Resets the decoder state by discarding all internally buffered frames. This function should be used before seeking to a new position in the stream. After flushing, the decoder will not produce output until a new Sequence Header OBU is received.

```APIDOC
## dav1d_flush

### Description
Discards all internally buffered frames and resets the decoder state. Use before seeking to a new position in the stream. After flushing, the decoder will not produce output until a new Sequence Header OBU is received via `dav1d_send_data()`.

### Function Signature
```c
void dav1d_flush(Dav1dContext *c)
```

### Parameters
- **c** (`Dav1dContext *`) - A pointer to the `Dav1dContext` to flush.
```

--------------------------------

### dav1d_parse_sequence_header

Source: https://context7.com/videolan/dav1d/llms.txt

Parses a Dav1dSequenceHeader from a raw buffer without requiring a full Dav1dContext. This is useful for probing stream parameters before opening a decoder or for scanning forward after a seek.

```APIDOC
## dav1d_parse_sequence_header

### Description
Parses a `Dav1dSequenceHeader` from a raw buffer without requiring a full `Dav1dContext`. Useful for probing stream parameters (dimensions, color space, bit depth, film grain capability) before opening a decoder, or for scanning forward after a seek to find the next valid Sequence Header.

### Function Signature
```c
int dav1d_parse_sequence_header(Dav1dSequenceHeader *seq, const uint8_t *buf, size_t sz)
```

### Parameters
- **seq** (`Dav1dSequenceHeader *`) - Pointer to a `Dav1dSequenceHeader` struct to be filled with parsed data.
- **buf** (`const uint8_t *`) - Pointer to the buffer containing the sequence header data.
- **sz** (`size_t`) - The size of the buffer in bytes.

### Return Value
- Returns 0 on success.
- Returns `DAV1D_ERR(ENOENT)` if no Sequence Header OBU is found in the buffer.
- Returns a negative error code on parse error.
```

--------------------------------

### Release Decoded Picture Reference (dav1d_picture_unref)

Source: https://context7.com/videolan/dav1d/llms.txt

Decrement the reference count of a Dav1dPicture. Buffers are freed when the count reaches zero. The struct is zeroed on return.

```c
#include "dav1d/dav1d.h"

void consume_frame(Dav1dPicture *p) {
    // Access picture data...
    uint8_t *y_plane = (uint8_t *)p->data[0];
    ptrdiff_t y_stride = p->stride[0]; // may be negative for bottom-up frames
    (void)y_plane;
    (void)y_stride;

    // Always release when done, even on error paths:
    dav1d_picture_unref(p);
    // p->data[0/1/2] are now NULL; p->ref is NULL.
}
```

--------------------------------

### dav1d_close

Source: https://context7.com/videolan/dav1d/llms.txt

Frees a decoder context and releases all internally allocated memory. This function sets the context pointer to NULL upon successful completion.

```APIDOC
## dav1d_close 

### Description
Closes the decoder instance and releases all internally allocated memory. Sets the pointer to NULL on return. Implicitly flushes any buffered frames without outputting them.

### Method
C Function

### Parameters
- **c** (*Dav1dContext **)
  - Input/Output: A pointer to a `Dav1dContext` pointer. This pointer will be set to NULL after the context is closed.

### Request Example
```c
#include "dav1d/dav1d.h"

void cleanup(Dav1dContext **c) {
    if (*c) {
        dav1d_close(c);
        // *c is now NULL
    }
}
```

### Response
No return value. The `Dav1dContext` pointer is set to NULL.
```