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 simple encoder app

The simple 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 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
--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)
--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

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.

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

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

References

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