Guide to librav1e API Configuration Structs

This article provides a clear overview of the essential configuration structs in the librav1e (rav1e) API. Developers looking to integrate this modern AV1 encoder into their applications will learn about the role of EncoderConfig, Config, and how they initialize the encoding Context. Understanding these structures is crucial for fine-tuning video quality, encoding speed, and system resource usage.

EncoderConfig

The EncoderConfig struct (represented as RaEncoderConfig in the C API) is the central repository for all encoding parameters. It defines how the video will be compressed and structured. Key parameters configured within this struct include:

• Video Dimensions: width and height of the input frames.
• Color Properties: chroma_sampling (e.g., YUV420, YUV422, YUV444), bit_depth (8, 10, or 12-bit), and color primaries.
• Speed and Quality: The speed setting (ranging from 0 for best quality/slowest to 10 for fastest).
• Rate Control: Settings for constant quality (QP), target bitrate, and rate control mode (CBR, VBR, or CQ).
• Threading and Tiling: Configuration for multi-threading, including tiles and tile_rows/tile_cols to parallelize encoding.

Config

The Config struct (or RaConfig in C) serves as a validator and builder wrapper around EncoderConfig. Developers do not feed EncoderConfig directly into the encoder. Instead, they pass it to Config.

The primary roles of Config are: * Validation: It verifies that the parameters set in EncoderConfig are valid, compatible with each other, and supported by the AV1 standard. * Context Creation: Once validated, Config is used to instantiate the actual encoder state machine by calling the initialization function (such as new_context()).

Context

While not strictly a configuration struct itself, the Context struct (RaContext) is the engine generated by your configuration. It manages the internal state of the encoder, coordinates threading, and processes the pipeline. Once a Context is built from a validated Config, the configuration parameters are locked in and cannot be altered mid-stream.

Frame

The Frame struct (RaFrame) is used to configure and hold the raw input pixel data before it is sent to the encoder Context. Developers must configure each Frame with: * Planes: Pointers to the Y, U, and V pixel buffers. * Strides: The spatial configuration (stride/pitch) of each plane to ensure the encoder reads the memory buffer correctly.

Typical Implementation Workflow

To use these structs in an application, developers follow a specific sequence:

1. Initialize EncoderConfig: Populate the struct with the desired resolution, speed, and bitrate.
2. Create Config: Pass the EncoderConfig to the Config container to run validation checks.
3. Build Context: Call the builder method on Config to generate the active Context.
4. Configure and Send Frames: Allocate Frame structs with raw video data and send them to the Context for encoding.