How to Configure Constant Quality CQ in libavif

This article provides a developer’s guide on how to configure the Constant Quality (CQ) level in libavif, the reference library for encoding and decoding AVIF images. It covers the underlying concepts of quantizer limits, demonstrates how to programmatically set constant quality using the libavif C API, and explains how to achieve the same results using the avifenc command-line utility.

Understanding Quantizers in libavif

AVIF relies on the AV1 video codec standard, which controls image quality using quantization parameters (QP). In libavif, constant quality is achieved by configuring these quantizer values.

The quantizer scale in libavif ranges from 0 to 63: * 0 (AVIF_QUANTIZER_LOSSLESS): Maximum quality (completely lossless). * 63 (AVIF_QUANTIZER_WORST): Minimum quality (highest compression, lowest file size).

To achieve true Constant Quality (CQ) encoding, developers must set both the minimum and maximum quantizer bounds to the same target value. This prevents the encoder from dynamically adjusting the quality based on bitrate constraints.

Programmatic Configuration via C API

When writing application code with the libavif C API, you configure the encoder’s quality settings by modifying the fields of the avifEncoder structure.

Here is a step-by-step example of how to set up constant quality:

#include "avif/avif.h"

void configure_constant_quality(avifEncoder * encoder, int quality_value) {
    // Clamp the target quality between 0 (best) and 63 (worst)
    int qp = 63 - (quality_value * 63 / 100); // Optional: Convert 0-100 scale to 0-63 QP
    
    // Set color channel quantizers to the same value for constant quality
    encoder->minQuantizer = qp;
    encoder->maxQuantizer = qp;

    // Set alpha (transparency) channel quantizers if applicable
    encoder->minQuantizerAlpha = qp;
    encoder->maxQuantizerAlpha = qp;
}

By ensuring minQuantizer and maxQuantizer are equal, the encoder is locked into that specific CQ step for the entire image payload.

Command-Line Configuration via avifenc

If you are using the avifenc command-line tool for automation or testing, you can configure constant quality using either the quality flag or explicit quantizer limits.

Method 1: Using the Quality Flag

The easiest way is using the -q (or --quality) flag, which accepts a scale from 0 (worst) to 100 (lossless):

avifenc -q 80 input.png output.avif

Under the hood, avifenc maps this 0-100 scale to the corresponding 0-63 quantizer values and automatically matches the minimum and maximum bounds.

Method 2: Defining Exact Quantizer Limits

For precise control over the raw AV1 quantizers, use the --min and --max flags. Setting them to the same value forces constant quality:

avifenc --min 20 --max 20 input.png output.avif

Best Practices for CQ Selection