Usage

Overview

The encoder project includes two encoder executables, a simple encoder app (vvencapp) and a full featured expert encoder (vvencFFapp).

How to use the encoder app

The encoder app (vvencapp) can be used in one of five predefined presets. Each preset represents a different tradeoff between encoder runtime and video quality. In the slowest preset, the encoder reaches the highest compression gain, whilst in the fastest preset the runtime is significantly decreased. These preset configurations have been determined based on the Pareto optimal configuration set of the encoder configuration space, which is detailed in ⁹.
A detailed overview of the tool configuration of each preset is available in the Presets section. A list of the main encoder command line parameters is shown in the table.

Option	Default	Description
--help,-h		Show basic help
--fullhelp		Show full help
--input,-i	not set	Raw yuv input file (use - to read from standard input)
--size,-s	1920x1080	Input file resolution (width x height)
--framerate,-r	60	Temporal rate of input file. Required for rate control and calculation of output bit-rate. Also recommended with perceptual QP adaptation (see --qpa option below).
--framescale	1	The denominator of the framerate to enable fractional rate specification.
--fps	60/1	Fractional framerate specification, setting --framerate and --framescale using a single parameter with a fraction syntax (denominator defaults to 1 if not present).
--format,-c	yuv420	Set input format to YUV 4:2:0 8bit (yuv420) or YUV 4:2:0 10bit (yuv420_10)
--output,-o	not set	Bit-stream output file
--preset	medium	Preset for specific encoding setting (faster, fast, medium, slow, slower)
--qp,-q	32	Quantization parameter (0..63)
--bitrate,-b	0	Bit-rate for rate control (0 constant QP encoding rate control off, otherwise bits per second). use e.g. 1.5M, 1.5Mbps, 1500k, 1500kbps, 1500000bps, 1500000. Rate control requires correct framerate.
--maxrate,-m	0	Approximate maximum instantaneous bitrate for constrained VBR in rate control (0: no rate cap; use e.g. 3.5M, 3.5Mbps, 3500k, 3500kbps, 3500000bps, 3500000). Can also be specified as a multiplier of the target bitrate with suffix x, e.g. -b 1Mbps -m 2x is equivalent to -b 1Mbps -m 2Mpbs.
--passes,-p	2	Number of passes used for rate control
--pass	not set	Set current rate control pass. If not set, encoder will run both passes one after the other in one call. If set to [1,2], encoder will execute first or second pass only. Requires --rcstatsfile to be set (see below).
--rcstatsfile	not set	Rate control statistics file, to store or load first pass rate control statistics data.
--qpa	1	Perceptual QP adaptation (QPA) to improve subjective video quality (0: off, 1: on)
--refreshsec,-rs	1	Intra period/refresh in seconds
--refreshtype,-rt	cra	intra refresh type (idr, cra, cra_cre: CRA, constrained RASL picture encoding)
--hdr	off	HDR mode of the input signal: SDR (off), HDR10 with PQ transfer function and BT.709 color primaries (pq or hdr10) or BT.2020 color primaries (pq_2020 or hdr10_2020), HLG transfer function and BT.709 color primaries (hlg) or BT.2020 color primaries (hlg_2020)
--sdr	off	SDR mode of the input signal: SDR (off), SDR with BT.709, BT.2020 or BT.470BG (sdr_709,sdr_2020,sdr_470bg)
--threads,-t	Size ≥ 720p: 8 else: 4	Number of threads (1..N)
--mtprofile	auto	enable automatic multi-threading setting (enables tiles, IFP and WPP automatically depending on the number of threads)
--ifp	auto	inter-frame parallelization(IFP) (0: off, 1: on, with sync. offset of two CTU lines)
--additional	not set	additional options as string (e.g: "bitrate=1000000:passes=1")

Example usage of vvencapp

Given a YUV 4:2:0 input file with a bit-depth of 8bit and a resolution of 176x144 pixels, the following call will encode the input file with the medium speedup preset: vvencapp --preset medium -i BUS_176x144_75@15.yuv -s 176x144 -r 15 -o str.266

Best Practice

In general the input can be defined as RAW YUV or by using y4m (https://wiki.multimedia.cx/index.php/YUV4MPEG2) input.

Basic example by using RAW YUV 420 p input:
vvencapp -i input.yuv -s 1920x1080 --fps 50/1 -o str.266
As y4m contains the particular description of the content no further parameter have to be set:
vvencapp -i input.y4m -o str.266

When using piped input the input file has to be defined as -. The option --y4m must only be set when the piped input is in y4m syntax. e.g.:
vvencapp -i - --y4m -o str.266

Encoding Modes

VVenC can be used in different configurations:

• Constant Quality Mode (constant/fix QP)
• Constant Quality Factor (constant QP mode + subjecte optimization + maximum Bitrate)
• Rate control (RC) with Variable Bitrate (VBR)

Constant Quality Mode (fix QP)

For constant Quality the quantization parameter (QP) has to be specified in the range of 0-63.
where the default QP of 32 will give an average good quality. The higher the QP the less bitrate and the worse the quality of the compressed video. The lower the QP the more bitrate and better the video quality gets. Good results can be received in the range between QP 21 and 47.

The following example takes the medium preset and uses the QP 30:
vvencapp --preset medium -i input.yuv -s 1920x1080 --fps 50/1 -q 30 -o str.266

Constant Quality Factor (CQF)

The Constant Quality Factor mode takes a given quantization parameter (QP) to predefine a quality and optimizes the subjective (perceived) video quality with a maximum bitrate.
The maximum bitrate option can also be used in the constant bitrate mode.

The following example takes the medium preset and uses the QP 27 with a maximum bitrate of 5Mbit/s:
vvencapp --preset medium -i input.yuv -s 1920x1080 -q 27 --qpa 1 -m 5M -o str.266

Variable Bitrate Mode (VBR) with rate control

When talking about rate control the Constant Bitrate Mode (CBR) comes in mind first.
In comparisson to CBR the VBR mode tries to achieve the lowest possible file size at the highest possible quality by a given bitrate. This results in a compressed bitstream that scores in the defined bitrate in average but will distribute the bits depending on the given content.
To prevent bitrate peaks the maximum bitrate option can be used which must be at least 1.5x the given target bitrate.
VVenC can be uses in single-pass or two-pass rate control mode.

In the following some examples of different rate control modes are shown.

• Single-pass rate control with maximum bitrate:
  vvencapp -i input.y4m -b 2M -m 5M -p 1 -o str.266

• Tow-pass rate control with subjective optimization maximum bitrate:
  vvencapp -i input.y4m -b 2M -m 5M -p 2 --qpa 1 -o str.266

The encoder application will run the two passes internally one after another.
Both passes can be executed individually by defining the current pass.
The intermediate results are written into a json file which must be defined by using the option --rcstatsfile.

This example runs each pass individually by using for each run the same options but the pass number:
vvencapp -i input.y4m -b 2M -m 5M -p 1 --pass 1 --rcstatsfile stats.json -o str.266
vvencapp -i input.y4m -b 2M -m 5M -p 2 --pass 2 --rcstatsfile stats.json -o str.266

When using the second pass with other options then used in the first pass unpredictable results and errors may occur.

Special use cases with rate control

Chunk based encoding (e.g. for Dynamic Adaptive Streaming over HTTP (DASH))

vvencapp -i input_3840x2160.y4m -b 4M -m 8M -rt cra_cre -rs 4 --additional MaxPicSize=3840x2160 -o str_3840x2160.266
vvencapp -i input_1920x1080.y4m -b 2M -m 4M -rt cra_cre -rs 4 --additional MaxPicSize=3840x2160 -o str_1920x1080.266
vvencapp -i input_1280x720.y4m -b 1M -m 2M -rt cra_cre -rs 4 --additional MaxPicSize=3840x2160 -o str_1280x720.266
The refresh type defines the RASL encoding contraint and RPR.
The chunk size is given as Intra period in seconds (4 seconds in this example).
The MaxPicSize constraint defines the maximal possible resolution which is signalized in the SPS.

Library

The VVenC project provides an easy to use C-library. This section gives a rough overview of how to use the VVenC library. For simplicity, it assumes the vvenc.h header is included and the vvenc.lib or libvvenc.a library is linked statically into the application.

The following steps are required to use the encoder:

1. Initialize the encoder:

vvenc_config params;

vvenc_init_default ( &params, width, height, framerate, bit_rate, qp, preset );

vvencEncoder* encoder = vvenc_encoder_create();
vvenc_encoder_open( encoder, &params );

2. Allocate and initialize the YUV Buffer

vvencYUVBuffer* yuvbuf = vvenc_YUVBuffer_alloc();
vvenc_YUVBuffer_alloc_buffer( yuvbuf, params.m_internChromaFormat, params.m_SourceWidth, params.m_SourceHeight );

3. Allocate and initialize the access unit storage for output packets

vvencAccessUnit* au = vvenc_accessUnit_alloc();

const int auSizeScale = vvenccfg.m_internChromaFormat <= VVENC_CHROMA_420 ? 2 : 3;
vvenc_accessUnit_alloc_payload( au, auSizeScale * params.m_SourceWidth * params.m_SourceHeight + 1024 );

4. Initialize encoder pass (only needed if 2-pass rate control is used, otherwise done internally )

vvenc_init_pass( encoder, pass, statsfilename );

5. Set the yuv input packet

yuvbuf.planes[0].ptr = (int16_t*)frame->data[0];
yuvbuf.planes[1].ptr = (int16_t*)frame->data[1];
yuvbuf.planes[2].ptr = (int16_t*)frame->data[2];

yuvbuf.planes[0].width  = frame->width;
yuvbuf.planes[0].height = frame->height;
yuvbuf.planes[0].stride = frame->linesize[0] >> 1; // if stride of input image is in bytes, we have to half it, as vvenc uses 16bit samples

yuvbuf.planes[1].width  = frame->width >>1;
yuvbuf.planes[1].height = frame->height >>1;
yuvbuf.planes[1].stride = frame->linesize[1] >> 1;

yuvbuf.planes[2].width  = frame->width >>1;
yuvbuf.planes[2].height = frame->height >>1;
yuvbuf.planes[2].stride = frame->linesize[2] >> 1;

yuvbuf.cts     = frame->pts;
yuvbuf.ctsValid = true;

6. Pass the yuv input packet to the encoder

int ret = vvenc_encode( encoder, yuvbuf, au, &encDone );
if( ret != VVENC_OK  ) {
    return -1;    // abort on error for simplicity
}
if ( au->payloadUsedSize > 0 ) {
  //   process the encoder access unit
}

6. Repeat from steps 5 and 6 until all input packets have been passed to the encoder. Then start flushing the encoder (step 7).
7. Wait for and extract next encoded access unit from the encoder.
   When all encoded access units are returned, the encDone flag is set to 1.

vvencYUVBuffer* yuvFlush = NULL;

while ( !encDone ){
  int ret = vvenc_encode( encoder, yuvFlush, au, &encDone );
  if( ret != VVENC_OK  ) {
      return -1;    // abort on error for simplicity
  }
  if ( au->payloadUsedSize > 0 ) {
    //   process the encoder access unit
  }
}

9. Free encoder, YUV buffer and access unit storage.

vvenc_encoder_close( encoder );
vvenc_YUVBuffer_free( yuvbuf, true  ); // release storage and payload memory
vvenc_accessUnit_free( au, true ); // release storage and payload memory

How to use the full featured expert mode encoder?

The expert mode encoder (vvencFFapp) is based on the VTM configuration scheme. Most of the parameters have been kept similar to VTM, but for some parameters, additional modes are available. Furthermore, not supported options have been removed.
Example configuration files for the expert mode encoder can be found in the cfg sub-directory as seen in the following table.
Nevertheless the expert mode encoder application is not installed per default anymore.

Configuration File	Description
sequence.cfg	Sequence specific configuration parameters. Must be always adapted to the input sequence.
randomaccess_[faster, fast, medium, slow, slower].cfg	Random access configuration for different presets. Each configuration file corresponds to one of the 5 preset modes.
qpa.cfg	Perceptually optimized QPA configuration file.
rc1p.cfg	Single pass rate control configuration, overriding default fix QP setup.
rc2p.cfg	Two pass rate control configuration, overriding default fix QP setup.

Example usage of vvencFFapp

In order to start your first experiments with the expert mode encoder, adapt the sequence.cfg configuration file to your input YUV source file and use the following command: vvencFFapp -c randomaccess_medium.cfg -c sequence.cfg

How to map command line parameters of the standard encoder into the full featured expert mode encoder?

The export mode encoder (vvencFFapp) can be used in the same manner as the standard encoder (vvencapp) by using the adapted expert option names. Be aware of that some options have different default values. The following table shows only expert options that differs from the standard encoder:

Option(standard)	Default	Option(full feature)	Default
--input,-i <str>	-	--InputFile <str>	-
--size,-s <wxh>	1920x1080	--Size,-s <wxh>	0x0
		--SourceWidth <int> --SourceHeight <int>	0
--format,-c <str>	yuv420	--InputBitDepth <int>	8
--internal-bitdepth <int>	10	--InternalBitDepth <int>	10
--framerate,-r <int>	60	--FrameRate,-fr <int>	0
--framescale <int>	1	--FrameScale <int>	1
--tickspersec <int>	90000	--TicksPerSecond <int>	90000
--frames <int>	0	--FramesToBeEncoded <int>	0
--frameskip <int>	0	--FrameSkip <int>	0
--tiles <cxr>	1x1	--Tiles <cxr>	1x1
--output,-o <str>	not set	--BitstreamFile,-b <str>	not set
--qp,-q <int>	32	--QP <int>	32
--bitrate,-b <int>	0	--TargetBitrate <int>	0
--maxrate,-m <int>	0	--MaxBitrate <int>	0
--passes,-p <int>	-1	--NumPasses <int>	-1
--pass <int>	-1	--Pass <int>	-1
--rcstatsfile <str>	-	--RCStatsFile <str>	-
--qpa <int>	1	--PerceptQPA,-qpa <int>	0
--refreshtype,-rt <str>	cra	--DecodingRefreshType <str>	cra
--refreshsec,rs <int>	1	--RefreshSec <int>	1
--threads,-t <int>	size >= 1280x720: 8, else: 4	--Threads,-t <int>	0
--hdr <str>	off	--Hdr <str>	off
--profile <str>	auto	--Profile <str>	auto
--level <str>	auto	--Level <str>	auto
--tier <str>	auto	--Tier <str>	auto
--accessunitdelimiter,-aud <int>	auto	--AccessUnitDelimiter,-aud <int>	auto
--vuiparameterspresent,-vui <int>	auto	--VuiParametersPresent,-vui <int>	auto
--hrdparameterspresent,-hrd <int>	auto	--HrdParametersPresent,-hrd <int>	auto
--decodedpicturehash,-dph <int>	off	--SEIDecodedPictureHash,-dph <int>	off

Example vvencapp vs. vvencFFapp

Given a YUV 4:2:0 input file with a bit-depth of 8bit and a resolution of 176x144 pixels,
the following calls will encode the input file with the medium speedup preset with 1Mbit/s
by using Two pass rate control.
Both calls will produce the same output.

Standard encoder:

vvencapp --preset medium -i BUS_176x144_75@15.yuv -s 176x144 -r 15 -b 1000000 -p 2 -o str.266

Full featured expert mode encoder:

vvencFFapp --preset medium --InputFile BUS_176x144_75@15.yuv -s 176x144 -fr 15 -TargetBitrate 1000000 --NumPasses 2 -qpa 1 -t -1 -b str.266

References

• [9] J. Brandenburg et al., “Towards Fast and Efficient VVC Encoding”, IEEE 22nd Workshop on Multimedia Signal Processing (MMSP 2020), Tampere, Finland, 2020.