Top level

SVT-AV1 Parameters

Configuration File Parameters

The encoder parameters are listed in this table below along with their status of support, command line parameter and the range of values that the parameters can take. Any of the parameters below that have a non-empty Configuration file parameter field, can be set by adding them to the Sample.cfg file.

Options

Usage of SvtAv1Params

To use the --svtav1-params option, the syntax is --svtav1-params option1=value1:option2=value2....

An example is:

SvtAv1EncApp \
  -i input.y4m \
  -b output.ivf \
  --svtav1-params \
  "preset=10:crf=30:irefresh-type=kf:matrix-coefficients=bt709:mastering-display=G(0.2649,0.6900)B(0.1500,0.0600)R(0.6800,0.3200)WP(0.3127,0.3290)L(1000.0,1)"

This will set --preset to 10 and --crf to 30 inside the API along with some other parameters.

Do note however, that there is no error checking for duplicate keys and only for invalid keys or values.

For more information on valid values for specific keys, refer to the EbEncSettings file.

Encoder Global Options

Rate Control Options

UseFixedQIndexOffsets and more information

UseFixedQIndexOffsets and its associated arguments (HierarchicalLevels, QIndexOffsets, ChromaQIndexOffsets, KeyFrameQIndexOffset, KeyFrameChromaQIndexOffset) are used together to specify the qindex offsets based on frame type and temporal layer when rc is set to 0.

QP value specified by the --qp argument is assigned to the pictures at the highest temporal layer. It is first converted to a qindex, then the corresponding qindex offsets are added on top of it based on the frame types (Key/Inter) and temporal layer id.

Qindex offset can be negative. The final qindex value will be clamped within the valid min/max qindex range.

For chroma plane, after deciding the qindex for the luma plane, the corresponding chroma qindex offsets are added on top of the luma plane qindex based on frame types and temporal layer id.

--qindex-offsets and --chroma-qindex-offsets have to be used after the --hierarchical-levels parameter. The number of qindex offsets should be HierarchicalLevels plus 1, and they can be enclosed in [] to separate the list.

An example command line is:

SvtAv1EncApp -i in.y4m -b out.ivf --rc 0 -q 42 --hierarchical-levels 3 --use-fixed-qindex-offsets 1 --qindex-offsets [-12,-8,-4,0] --key-frame-qindex-offset -20 --key-frame-chroma-qindex-offset -6 --chroma-qindex-offsets [-6,0,12,24]

For this command line, corresponding qindex values are:

EnableQM and more information

With EnableQM, MinQmLevel and MaxQmLevel, user can customize the quantization matrix used in quantization procedure instead of using the default one. With the default quantization matrix, all coefficients share the same weight, whereas with non-default ones, coefficients can have different weight through the settings made by users. The deviation of weight (or flatness, equivalently) is controlled by arguments MinQmLevel and MaxQmLevel. There are sixteen quantization matrix levels, ranging from level 0 to level 15. The lower the level is the larger deviation of weight the quantization matrix will provide. Level 15 is fully flat in weight and is set as the default quantization matrix. A lower level quantization matrix typically results in bitstreams with lower bitrate and slightly worse quality in CRF rate control mode. The reduction in bitrate is more obvious with low CRF than high CRF.

The quantization matrices feature signals at frame level. When the feature is enabled, the encoder decides each frame’s quantization matrix level by normalizing its qindex to user specified quantization matrix level range (from MinQmLevel to MaxQmLevel).

An example command line is:

SvtAv1EncApp -i in.y4m -b out.ivf --keyint -1 --enable-qm 1 --qm-min 0 --qm-max 15

Recode loop level table

Multi-pass Options

Pass information

--pass 3 is only available for non-crf modes and all passes except single-pass requires the --stats parameter to point to a valid path

GOP size and type Options

AV1 Specific Options

Super-Resolution

Super resolution is better described in the Super-Resolution documentation, but this basically allows the input to be encoded at a lower resolution, horizontally, but then later upscaled back to the original resolution by the decoder.

The performance of the encoder will be affected for all modes other than mode 0. And for mode 4, it should be noted that the encoder will run at least twice, one for down scaling, and another with no scaling, and then it will choose the best one for each of the appropriate frames.

For more information on the decision-making process, please look at section 2.2 of the super-resolution doc

Reference Scaling

Reference Scaling is better described in the reference scaling documentation, but this basically allows the input to be encoded and the output at a lower resolution, scaling ratio applys on both horizontally and vertically.

Example CLI of reference scaling dynamic mode:

-i input.yuv -b output.ivf --resize-mode 3 --rc 2 --pred-struct 1 --tbr 1000

TODO: Random access mode is not available until scaling event parameter is supported. An example will be added here to guide using random access mode.

Color Description Options

Appendix A Encoder Parameters

1. Thread management parameters

LogicalProcessors (--lp) and TargetSocket (--ss) parameters are used to management thread affinity on Windows and Ubuntu OS. These are some examples how you use them together.

If LogicalProcessors and TargetSocket are not set, threads are managed by OS thread scheduler.

SvtAv1EncApp.exe -i in.yuv -w 3840 -h 2160 --lp 40

If only LogicalProcessors is set, threads run on 40 logical processors. Threads may run on dual sockets if 40 is larger than logical processor number of a socket.

NOTE: On Windows, thread affinity can be set only by group on system with more than 64 logical processors. So, if 40 is larger than logical processor number of a single socket, threads run on all logical processors of both sockets.

SvtAv1EncApp.exe -i in.yuv -w 3840 -h 2160 --ss 1

If only TargetSocket is set, threads run on all the logical processors of socket 1.

SvtAv1EncApp.exe -i in.yuv -w 3840 -h 2160 --lp 20 --ss 0

If both LogicalProcessors and TargetSocket are set, threads run on 20 logical processors of socket 0. Threads guaranteed to run only on socket 0 if 20 is larger than logical processor number of socket 0.

The (--pin) option allows the user to pin/unpin the execution to/from a specific number of cores.

The combinational use of (--pin) with (--lp) results in memory reduction while allowing the execution to work on any of the cores and not restrict it to specific cores.

This is an example on how to use them together.

so -lp 4 with --pin 1 would restrict the encoder to work on cpu0-3 and reduce the resource allocation to only what's needed to using 4 cores. --lp 4 with --pin 1, would reduce the allocation to what's needed for 4 cores but not restrict the encoder to run on cpu 0-3, in this case the encoder might end up using more than 4 cores due to the multi-threading nature of the encoder, but would at least allow for more multiple -lp4 encodes to run on the same machine without them being all restricted to run on cpu 0-3 or overflow the memory usage.

Example: 72 core machine:

72 jobs x --lp 1 --pin 0 (In order to maximize the CPU utilization 72 jobs are run simultaneously with each job utilitizing 1 core without being pined to a specific core)

36 jobs x --lp 2 --pin 1

18 jobs x --lp 4 --pin 1

(--ss) and (--pin 0) is not a valid combination.(--pin) is overwritten to 1 when (-ss) is used.

2. AV1 metadata

Please see the subsection 6.4.2, 6.7.3, and 6.7.4 of the AV1 Bitstream & Decoding Process Specification for more details on some expected values.

The available options for ColorPrimaries (--color-primaries) are:

• 1: bt709, BT.709
• 2: unspecified, default
• 4: bt470m, BT.470 System M (historical)
• 5: bt470bg, BT.470 System B, G (historical)
• 6: bt601, BT.601
• 7: smpte240, SMPTE 240
• 8: film, Generic film (color filters using illuminant C)
• 9: bt2020, BT.2020, BT.2100
• 10: xyz, SMPTE 428 (CIE 1921 XYZ)
• 11: smpte431, SMPTE RP 431-2
• 12: smpte432, SMPTE EG 432-1
• 22: ebu3213, EBU Tech. 3213-E

The available options for TransferCharacteristics (--transfer-characteristics) are:

• 1: bt709, BT.709
• 2: unspecified, default
• 4: bt470m, BT.470 System M (historical)
• 5: bt470bg, BT.470 System B, G (historical)
• 6: bt601, BT.601
• 7: smpte240, SMPTE 240 M
• 8: linear, Linear
• 9: log100, Logarithmic (100 : 1 range)
• 10: log100-sqrt10, Logarithmic (100 * Sqrt(10) : 1 range)
• 11: iec61966, IEC 61966-2-4
• 12: bt1361, BT.1361
• 13: srgb, sRGB or sYCC
• 14: bt2020-10, BT.2020 10-bit systems
• 15: bt2020-12, BT.2020 12-bit systems
• 16: smpte2084, SMPTE ST 2084, ITU BT.2100 PQ
• 17: smpte428, SMPTE ST 428
• 18: hlg, BT.2100 HLG, ARIB STD-B67

The available options for MatrixCoefficients (--matrix-coefficients) are:

• 0: identity, Identity matrix
• 1: bt709, BT.709
• 2: unspecified, default
• 4: fcc, US FCC 73.628
• 5: bt470bg, BT.470 System B, G (historical)
• 6: bt601, BT.601
• 7: smpte240, SMPTE 240 M
• 8: ycgco, YCgCo
• 9: bt2020-ncl, BT.2020 non-constant luminance, BT.2100 YCbCr
• 10: bt2020-cl, BT.2020 constant luminance
• 11: smpte2085, SMPTE ST 2085 YDzDx
• 12: chroma-ncl, Chromaticity-derived non-constant luminance
• 13: chroma-cl, Chromaticity-derived constant luminance
• 14: ictcp, BT.2100 ICtCp

The available options for ColorRange (--color-range) are:

• 0: studio, default
• 1: full

The available options for ChromaSamplePosition (--chroma-sample-position) are:

• 0: unknown, default
• 1: vertical/left, horizontally co-located with luma samples, vertical position in the middle between two luma samples
• 2: colocated/topleft, co-located with luma samples

MasteringDisplay (--mastering-display) and ContentLightLevel (--content-light) parameters are used to set the mastering display and content light level in the AV1 bitstream.

MasteringDisplay takes the format of G(x,y)B(x,y)R(x,y)WP(x,y)L(max,min) where

• G(x,y) is the green channel of the mastering display
• B(x,y) is the blue channel of the mastering display
• R(x,y) is the red channel of the mastering display
• WP(x,y) is the white point of the mastering display
• L(max,min) is the light level of the mastering display

The x and y values can be coordinates from 0.0 to 1.0, as specified in CIE 1931 while the min,max values can be floating point values representing candelas per square meter, or nits. For the max,min values, they are generally specified in the range of 0.0 to 1.0, but there are no constraints on the provided values. Invalid values will be clipped accordingly.

ContentLightLevel takes the format of max_cll,max_fall where both values are integers clipped into a range of 0 to 65535.

Examples:

SvtAv1EncApp -i in.y4m -b out.ivf \
    --mastering-display "G(0.2649,0.6900)B(0.1500,0.0600)R(0.6800,0.3200)WP(0.3127,0.3290)L(1000.0,1)" \
    --content-light 100,50 \
    --color-primaries bt2020 \
    --transfer-characteristics smpte2084 \
    --matrix-coefficients bt2020-ncl \
    --chroma-sample-position topleft
    # Color primary is BT.2020, BT.2100
    # Transfer characteristic is SMPTE ST 2084, ITU BT.2100 PQ
    # matrix coefficients is BT.2020 non-constant luminance, BT.2100 YCbCr

# or

ffmpeg -y -i in.mp4 \
  -strict -2 \
  -c:a opus \
  -c:v libsvtav1 \
  -color_primaries:v bt2020 \
  -color_trc:v smpte2084 \
  -color_range:v pc \
  -chroma_sample_location:v topleft \
  -svtav1-params \
    "mastering-display=G(0.2649,0.6900)B(0.1500,0.0600)R(0.6800,0.3200)WP(0.3127,0.3290)L(1000.0,1):\
    content-light=100,50:\
    matrix-coefficients=bt2020-ncl:\
    chroma-sample-position=topleft" \
  out.mp4
# chroma-sample-position needs to be repeated because it currently isn't set ffmpeg's side