AOMedia AV1 Codec: aom_codec_enc_cfg Struct Reference

| AOMedia AV1 Codec

Data Fields
aom_codec_enc_cfg Struct Reference
Common Algorithm Interface » Encoder Algorithm Interface

Encoder configuration structure. More...

`#include <aom_encoder.h>`

## Data Fields
unsigned int | g_usage
| Algorithm specific "usage" value.
unsigned int | g_threads
| Maximum number of threads to use.
unsigned int | g_profile
| Bitstream profile to use.
unsigned int | g_w
| Width of the frame.
unsigned int | g_h
| Height of the frame.
unsigned int | g_limit
| Max number of frames to encode.
unsigned int | g_forced_max_frame_width
| Forced maximum width of the frame.
unsigned int | g_forced_max_frame_height
| Forced maximum height of the frame.
aom_bit_depth_t | g_bit_depth
| Bit-depth of the codec.
unsigned int | g_input_bit_depth
| Bit-depth of the input frames.
struct aom_rational | g_timebase
| Stream timebase units.
aom_codec_er_flags_t | g_error_resilient
| Enable error resilient modes.
enum aom_enc_pass | g_pass
| Multi-pass Encoding Mode.
unsigned int | g_lag_in_frames
| Allow lagged encoding.
unsigned int | rc_dropframe_thresh
| Temporal resampling configuration, if supported by the codec.
unsigned int | rc_resize_mode
| Mode for spatial resampling, if supported by the codec.
unsigned int | rc_resize_denominator
| Frame resize denominator.
unsigned int | rc_resize_kf_denominator
| Keyframe resize denominator.
aom_superres_mode | rc_superres_mode
| Frame super-resolution scaling mode.
unsigned int | rc_superres_denominator
| Frame super-resolution denominator.
unsigned int | rc_superres_kf_denominator
| Keyframe super-resolution denominator.
unsigned int | rc_superres_qthresh
| Frame super-resolution q threshold.
unsigned int | rc_superres_kf_qthresh
| Keyframe super-resolution q threshold.
enum aom_rc_mode | rc_end_usage
| Rate control algorithm to use.
aom_fixed_buf_t | rc_twopass_stats_in
| Two-pass stats buffer.
aom_fixed_buf_t | rc_firstpass_mb_stats_in
| first pass mb stats buffer.
unsigned int | rc_target_bitrate
| Target data rate.
unsigned int | rc_min_quantizer
| Minimum (Best Quality) Quantizer.
unsigned int | rc_max_quantizer
| Maximum (Worst Quality) Quantizer.
unsigned int | rc_undershoot_pct
| Rate control adaptation undershoot control.
unsigned int | rc_overshoot_pct
| Rate control adaptation overshoot control.
unsigned int | rc_buf_sz
| Decoder Buffer Size.
unsigned int | rc_buf_initial_sz
| Decoder Buffer Initial Size.
unsigned int | rc_buf_optimal_sz
| Decoder Buffer Optimal Size.
unsigned int | rc_2pass_vbr_bias_pct
| Two-pass mode CBR/VBR bias.
unsigned int | rc_2pass_vbr_minsection_pct
| Two-pass mode per-GOP minimum bitrate.
unsigned int | rc_2pass_vbr_maxsection_pct
| Two-pass mode per-GOP maximum bitrate.
int | fwd_kf_enabled
| Option to enable forward reference key frame.
enum aom_kf_mode | kf_mode
| Keyframe placement mode.
unsigned int | kf_min_dist
| Keyframe minimum interval.
unsigned int | kf_max_dist
| Keyframe maximum interval.
unsigned int | sframe_dist
| sframe interval
unsigned int | sframe_mode
| sframe insertion mode
unsigned int | large_scale_tile
| Tile coding mode.
unsigned int | monochrome
| Monochrome mode.
unsigned int | full_still_picture_hdr
| full_still_picture_hdr
unsigned int | save_as_annexb
| Bitstream syntax mode.
int | tile_width_count
| Number of explicit tile widths specified.
int | tile_height_count
| Number of explicit tile heights specified.
int | tile_widths [64]
| Array of specified tile widths.
int | tile_heights [64]
| Array of specified tile heights.
unsigned int | use_fixed_qp_offsets
| Whether encoder should use fixed QP offsets.
int | fixed_qp_offsets [5]
| Deprecated and ignored. DO NOT USE.
cfg_options_t | encoder_cfg
| Options defined per config file.

## Detailed Description

Encoder configuration structure.

This structure contains the encoder settings that have common representations across all codecs. This doesn't imply that all codecs support all features, however.

## Field Documentation

## ◆ g_usage

unsigned int aom_codec_enc_cfg::g_usage

Algorithm specific "usage" value.

Algorithms may define multiple values for usage, which may convey the intent of how the application intends to use the stream. If this value is non-zero, consult the documentation for the codec to determine its meaning.

## ◆ g_threads

unsigned int aom_codec_enc_cfg::g_threads

Maximum number of threads to use.

For multi-threaded implementations, use no more than this number of threads. The codec may use fewer threads than allowed. The value 0 is equivalent to the value 1.

## ◆ g_profile

unsigned int aom_codec_enc_cfg::g_profile

Bitstream profile to use.

Some codecs support a notion of multiple bitstream profiles. Typically this maps to a set of features that are turned on or off. Often the profile to use is determined by the features of the intended decoder. Consult the documentation for the codec to determine the valid values for this parameter, or set to zero for a sane default. profile of bitstream to use

## ◆ g_w

unsigned int aom_codec_enc_cfg::g_w

Width of the frame.

This value identifies the presentation resolution of the frame, in pixels. Note that the frames passed as input to the encoder must have this resolution. Frames will be presented by the decoder in this resolution, independent of any spatial resampling the encoder may do.

## ◆ g_h

unsigned int aom_codec_enc_cfg::g_h

Height of the frame.

This value identifies the presentation resolution of the frame, in pixels. Note that the frames passed as input to the encoder must have this resolution. Frames will be presented by the decoder in this resolution, independent of any spatial resampling the encoder may do.

## ◆ g_limit

unsigned int aom_codec_enc_cfg::g_limit

Max number of frames to encode.

If force video mode is off (the default) and g_limit is 1, the encoder will encode a still picture (still_picture is set to 1 in the sequence header OBU). If in addition full_still_picture_hdr is 0 (the default), the encoder will use a reduced header (reduced_still_picture_header is set to 1 in the sequence header OBU) for the still picture.

## ◆ g_forced_max_frame_width

unsigned int aom_codec_enc_cfg::g_forced_max_frame_width

Forced maximum width of the frame.

If this value is non-zero then it is used to force the maximum frame width written in write_sequence_header().

## ◆ g_forced_max_frame_height

unsigned int aom_codec_enc_cfg::g_forced_max_frame_height

Forced maximum height of the frame.

If this value is non-zero then it is used to force the maximum frame height written in write_sequence_header().

## ◆ g_bit_depth

aom_bit_depth_t aom_codec_enc_cfg::g_bit_depth

Bit-depth of the codec.

This value identifies the bit_depth of the codec, Only certain bit-depths are supported as identified in the aom_bit_depth_t enum.

## ◆ g_input_bit_depth

unsigned int aom_codec_enc_cfg::g_input_bit_depth

Bit-depth of the input frames.

This value identifies the bit_depth of the input frames in bits. Note that the frames passed as input to the encoder must have this bit-depth.

## ◆ g_timebase

struct aom_rational aom_codec_enc_cfg::g_timebase

Stream timebase units.

Indicates the smallest interval of time, in seconds, used by the stream. For fixed frame rate material, or variable frame rate material where frames are timed at a multiple of a given clock (ex: video capture), the RECOMMENDED method is to set the timebase to the reciprocal of the frame rate (ex: 1001/30000 for 29.970 Hz NTSC). This allows the pts to correspond to the frame number, which can be handy. For re-encoding video from containers with absolute time timestamps, the RECOMMENDED method is to set the timebase to that of the parent container or multimedia framework (ex: 1/1000 for ms, as in FLV).

## ◆ g_error_resilient

aom_codec_er_flags_t aom_codec_enc_cfg::g_error_resilient

Enable error resilient modes.

The error resilient bitfield indicates to the encoder which features it should enable to take measures for streaming over lossy or noisy links.

## ◆ g_pass

enum aom_enc_pass aom_codec_enc_cfg::g_pass

Multi-pass Encoding Mode.

This value should be set to the current phase for multi-pass encoding. For single pass, set to AOM_RC_ONE_PASS.

## ◆ g_lag_in_frames

unsigned int aom_codec_enc_cfg::g_lag_in_frames

Allow lagged encoding.

If set, this value allows the encoder to consume a number of input frames before producing output frames. This allows the encoder to base decisions for the current frame on future frames. This does increase the latency of the encoding pipeline, so it is not appropriate in all situations (ex: realtime encoding).

Note that this is a maximum value – the encoder may produce frames sooner than the given limit. Set this value to 0 to disable this feature.

## ◆ rc_dropframe_thresh

unsigned int aom_codec_enc_cfg::rc_dropframe_thresh

Temporal resampling configuration, if supported by the codec.

Temporal resampling allows the codec to "drop" frames as a strategy to meet its target data rate. This can cause temporal discontinuities in the encoded video, which may appear as stuttering during playback. This trade-off is often acceptable, but for many applications is not. It can be disabled in these cases.

Note that not all codecs support this feature. All aom AVx codecs do. For other codecs, consult the documentation for that algorithm.

This threshold is described as a percentage of the target data buffer. When the data buffer falls below this percentage of fullness, a dropped frame is indicated. Set the threshold to zero (0) to disable this feature.

## ◆ rc_resize_mode

unsigned int aom_codec_enc_cfg::rc_resize_mode

Mode for spatial resampling, if supported by the codec.

Spatial resampling allows the codec to compress a lower resolution version of the frame, which is then upscaled by the decoder to the correct presentation resolution. This increases visual quality at low data rates, at the expense of CPU time on the encoder/decoder.

## ◆ rc_resize_denominator

unsigned int aom_codec_enc_cfg::rc_resize_denominator

Frame resize denominator.

The denominator for resize to use, assuming 8 as the numerator.

Valid denominators are 8 - 16 for now.

## ◆ rc_resize_kf_denominator

unsigned int aom_codec_enc_cfg::rc_resize_kf_denominator

Keyframe resize denominator.

The denominator for resize to use, assuming 8 as the numerator.

Valid denominators are 8 - 16 for now.

## ◆ rc_superres_mode

aom_superres_mode aom_codec_enc_cfg::rc_superres_mode

Frame super-resolution scaling mode.

Similar to spatial resampling, frame super-resolution integrates upscaling after the encode/decode process. Taking control of upscaling and using restoration filters should allow it to outperform normal resizing.

## ◆ rc_superres_denominator

unsigned int aom_codec_enc_cfg::rc_superres_denominator

Frame super-resolution denominator.

The denominator for superres to use. If fixed it will only change if the cumulative scale change over resizing and superres is greater than 1/2; this forces superres to reduce scaling.

Valid denominators are 8 to 16.

Used only by AOM_SUPERRES_FIXED.

## ◆ rc_superres_kf_denominator

unsigned int aom_codec_enc_cfg::rc_superres_kf_denominator

Keyframe super-resolution denominator.

The denominator for superres to use. If fixed it will only change if the cumulative scale change over resizing and superres is greater than 1/2; this forces superres to reduce scaling.

Valid denominators are 8 - 16 for now.

## ◆ rc_superres_qthresh

unsigned int aom_codec_enc_cfg::rc_superres_qthresh

Frame super-resolution q threshold.

The q level threshold after which superres is used. Valid values are 1 to 63.

Used only by AOM_SUPERRES_QTHRESH

## ◆ rc_superres_kf_qthresh

unsigned int aom_codec_enc_cfg::rc_superres_kf_qthresh

Keyframe super-resolution q threshold.

The q level threshold after which superres is used for key frames. Valid values are 1 to 63.

Used only by AOM_SUPERRES_QTHRESH

## ◆ rc_end_usage

enum aom_rc_mode aom_codec_enc_cfg::rc_end_usage

Rate control algorithm to use.

Indicates whether the end usage of this stream is to be streamed over a bandwidth constrained link, indicating that Constant Bit Rate (CBR) mode should be used, or whether it will be played back on a high bandwidth link, as from a local disk, where higher variations in bitrate are acceptable.

## ◆ rc_twopass_stats_in

aom_fixed_buf_t aom_codec_enc_cfg::rc_twopass_stats_in

Two-pass stats buffer.

A buffer containing all of the stats packets produced in the first pass, concatenated.

## ◆ rc_firstpass_mb_stats_in

aom_fixed_buf_t aom_codec_enc_cfg::rc_firstpass_mb_stats_in

first pass mb stats buffer.

A buffer containing all of the first pass mb stats packets produced in the first pass, concatenated.

## ◆ rc_target_bitrate

unsigned int aom_codec_enc_cfg::rc_target_bitrate

Target data rate.

Target bitrate to use for this stream, in kilobits per second.

## ◆ rc_min_quantizer

unsigned int aom_codec_enc_cfg::rc_min_quantizer

Minimum (Best Quality) Quantizer.

The quantizer is the most direct control over the quality of the encoded image. The range of valid values for the quantizer is codec specific. Consult the documentation for the codec to determine the values to use. To determine the range programmatically, call aom_codec_enc_config_default() with a usage value of 0.

## ◆ rc_max_quantizer

unsigned int aom_codec_enc_cfg::rc_max_quantizer

Maximum (Worst Quality) Quantizer.

The quantizer is the most direct control over the quality of the encoded image. The range of valid values for the quantizer is codec specific. Consult the documentation for the codec to determine the values to use. To determine the range programmatically, call aom_codec_enc_config_default() with a usage value of 0.

## ◆ rc_undershoot_pct

unsigned int aom_codec_enc_cfg::rc_undershoot_pct

Rate control adaptation undershoot control.

This value, controls the tolerance of the VBR algorithm to undershoot and is used as a trigger threshold for more aggressive adaptation of Q.

Valid values in the range 0-100.

## ◆ rc_overshoot_pct

unsigned int aom_codec_enc_cfg::rc_overshoot_pct

Rate control adaptation overshoot control.

This value, controls the tolerance of the VBR algorithm to overshoot and is used as a trigger threshold for more aggressive adaptation of Q.

Valid values in the range 0-100.

## ◆ rc_buf_sz

unsigned int aom_codec_enc_cfg::rc_buf_sz

Decoder Buffer Size.

This value indicates the amount of data that may be buffered by the decoding application. Note that this value is expressed in units of time (milliseconds). For example, a value of 5000 indicates that the client will buffer (at least) 5000ms worth of encoded data. Use the target bitrate (rc_target_bitrate) to convert to bits/bytes, if necessary.

## ◆ rc_buf_initial_sz

unsigned int aom_codec_enc_cfg::rc_buf_initial_sz

Decoder Buffer Initial Size.

This value indicates the amount of data that will be buffered by the decoding application prior to beginning playback. This value is expressed in units of time (milliseconds). Use the target bitrate (rc_target_bitrate) to convert to bits/bytes, if necessary.

## ◆ rc_buf_optimal_sz

unsigned int aom_codec_enc_cfg::rc_buf_optimal_sz

Decoder Buffer Optimal Size.

This value indicates the amount of data that the encoder should try to maintain in the decoder's buffer. This value is expressed in units of time (milliseconds). Use the target bitrate (rc_target_bitrate) to convert to bits/bytes, if necessary.

## ◆ rc_2pass_vbr_bias_pct

unsigned int aom_codec_enc_cfg::rc_2pass_vbr_bias_pct

Two-pass mode CBR/VBR bias.

Bias, expressed on a scale of 0 to 100, for determining target size for the current frame. The value 0 indicates the optimal CBR mode value should be used. The value 100 indicates the optimal VBR mode value should be used. Values in between indicate which way the encoder should "lean."

## ◆ rc_2pass_vbr_minsection_pct

unsigned int aom_codec_enc_cfg::rc_2pass_vbr_minsection_pct

Two-pass mode per-GOP minimum bitrate.

This value, expressed as a percentage of the target bitrate, indicates the minimum bitrate to be used for a single GOP (aka "section")

## ◆ rc_2pass_vbr_maxsection_pct

unsigned int aom_codec_enc_cfg::rc_2pass_vbr_maxsection_pct

Two-pass mode per-GOP maximum bitrate.

This value, expressed as a percentage of the target bitrate, indicates the maximum bitrate to be used for a single GOP (aka "section")

## ◆ kf_mode

enum aom_kf_mode aom_codec_enc_cfg::kf_mode

Keyframe placement mode.

This value indicates whether the encoder should place keyframes at a fixed interval, or determine the optimal placement automatically (as governed by the kf_min_dist and kf_max_dist parameters)

## ◆ kf_min_dist

unsigned int aom_codec_enc_cfg::kf_min_dist

Keyframe minimum interval.

This value, expressed as a number of frames, prevents the encoder from placing a keyframe nearer than kf_min_dist to the previous keyframe. At least kf_min_dist frames non-keyframes will be coded before the next keyframe. Set kf_min_dist equal to kf_max_dist for a fixed interval.

## ◆ kf_max_dist

unsigned int aom_codec_enc_cfg::kf_max_dist

Keyframe maximum interval.

This value, expressed as a number of frames, forces the encoder to code a keyframe if one has not been coded in the last kf_max_dist frames. A value of 0 implies all frames will be keyframes. Set kf_min_dist equal to kf_max_dist for a fixed interval.

## ◆ sframe_dist

unsigned int aom_codec_enc_cfg::sframe_dist

sframe interval

This value, expressed as a number of frames, forces the encoder to code an S-Frame every sframe_dist frames.

## ◆ sframe_mode

unsigned int aom_codec_enc_cfg::sframe_mode

sframe insertion mode

This value must be set to 1 or 2, and tells the encoder how to insert S-Frames. It will only have an effect if sframe_dist != 0.

If altref is enabled:

- if sframe_mode == 1, the considered frame will be made into an S-Frame only if it is an altref frame
- if sframe_mode == 2, the next altref frame will be made into an S-Frame.

Otherwise: the considered frame will be made into an S-Frame.

## ◆ large_scale_tile

unsigned int aom_codec_enc_cfg::large_scale_tile

Tile coding mode.

This value indicates the tile coding mode. A value of 0 implies a normal non-large-scale tile coding. A value of 1 implies a large-scale tile coding.

## ◆ monochrome

unsigned int aom_codec_enc_cfg::monochrome

Monochrome mode.

If this is nonzero, the encoder will generate a monochrome stream with no chroma planes.

## ◆ full_still_picture_hdr

unsigned int aom_codec_enc_cfg::full_still_picture_hdr

full_still_picture_hdr

If this is nonzero, the encoder will generate a full header (reduced_still_picture_header is set to 0 in the sequence header OBU) even for still picture encoding. If this is zero (the default), a reduced header (reduced_still_picture_header is set to 1 in the sequence header OBU) is used for still picture encoding. This flag has no effect when a regular video with more than a single frame is encoded.

## ◆ save_as_annexb

unsigned int aom_codec_enc_cfg::save_as_annexb

Bitstream syntax mode.

This value indicates the bitstream syntax mode. A value of 0 indicates bitstream is saved as Section 5 bitstream. A value of 1 indicates the bitstream is saved in Annex-B format

## ◆ tile_width_count

int aom_codec_enc_cfg::tile_width_count

Number of explicit tile widths specified.

This value indicates the number of tile widths specified A value of 0 implies no tile widths are specified. Tile widths are given in the array tile_widths[]

## ◆ tile_height_count

int aom_codec_enc_cfg::tile_height_count

Number of explicit tile heights specified.

This value indicates the number of tile heights specified A value of 0 implies no tile heights are specified. Tile heights are given in the array tile_heights[]

## ◆ tile_widths

int aom_codec_enc_cfg::tile_widths[64]

Array of specified tile widths.

This array specifies tile widths (and may be empty) The number of widths specified is given by tile_width_count

## ◆ tile_heights

int aom_codec_enc_cfg::tile_heights[64]

Array of specified tile heights.

This array specifies tile heights (and may be empty) The number of heights specified is given by tile_height_count

## ◆ use_fixed_qp_offsets

unsigned int aom_codec_enc_cfg::use_fixed_qp_offsets

Whether encoder should use fixed QP offsets.

If a value of 1 is provided, encoder will use fixed QP offsets for frames at different levels of the pyramid. If a value of 0 is provided, encoder will NOT use fixed QP offsets. Note: This option is only relevant for –end-usage=q.

## ◆ fixed_qp_offsets

int aom_codec_enc_cfg::fixed_qp_offsets[5]

Deprecated and ignored. DO NOT USE.

TODO(aomedia:3269): Remove fixed_qp_offsets in libaom v4.0.0.

The documentation for this struct was generated from the following file:

- aom/aom_encoder.h