How to Extract Encoding Metrics From libaom?

This article provides a practical guide on how to extract real-time encoding statistics and metrics directly from libaom, the reference software encoder for the AV1 video format. It covers the specific API functions required to retrieve frame-level data, the configuration parameters needed to enable logging, and a brief look at how these metrics can be utilized for quality analysis and bitrate control optimization.

Enabling Metric Collection in libaom

To extract statistics directly from libaom during the encoding process, you must utilize the AV1 Encoder Control interface (aom_codec_control). The encoder exposes several control IDs specifically designed to pass internal state data back to your application after a frame is processed.

Before querying metrics, ensure your encoder instance is properly initialized and that you are checking the return values of your control calls to guarantee the underlying structure is populated.

Key API Controls and Structures

The libaom API uses specific control flags to retrieve different types of encoding data. Below are the primary controls used for extracting metrics:

• AV1E_GET_ENCODE_STATS: This control fills a structure containing high-level packet and stream statistics.
• AV1E_GET_NUM_OPERATING_POINTS: Useful for scalable video coding (SVC) to determine how many operating points are being tracked.

When handling frame-by-frame loops, you will typically call aom_codec_control immediately after a successful aom_codec_encode and aom_codec_get_cx_data cycle.

// Example snippet for extracting basic encoder stats
aom_encode_stats_t stats;
if (aom_codec_control(&codec, AV1E_GET_ENCODE_STATS, &stats) == AOM_CODEC_OK) {
    // Process your metrics here
    printf("Frame size: %zu bits\n", stats.frame_size_in_bits);
}

Extracting Pass-Specific Statistics

If you are performing multi-pass encoding, libaom relies on a dedicated statistics buffer to pass information between the first and second analysis stages.

• First Pass: The encoder outputs a global statistics packet via the standard packet queue (AOM_CODEC_STATS_PKT). You must accumulate these packets into a contiguous memory buffer (aom_fixed_buf_t).
• Second Pass: You pass this accumulated buffer back into the encoder using the AV1E_SET_ROI_MAP or standard configuration structures so the encoder can adaptively adjust its rate control based on the first pass metrics.

Utilizing the Extracted Data

The metrics extracted directly from the libaom structures can be leveraged for several advanced video engineering workflows:

• Per-Frame Quantization Parameter (QP) Tracking: Monitoring the exact QP fluctuations across different frame types (I, P, B) to evaluate encoder stability.
• Visual Quality Estimation: Using block-level distortion outputs to calculate real-time structural metrics or feed into automated perceptual quality models.
• Dynamic Bitrate Adaptation: Feeding the frame-level bit distribution statistics back into an external application-layer rate control mechanism for live streaming optimization.