FFmpeg Integration

VVenC is officially supported in FFmpeg since 15th June 2024 (revision c75940db29), and for version larger or equal to 7.1. This section describes how VVenC can be enabled and used in FFmpeg.

• To build FFmpeg the general compilation guide is needed:
  https://trac.ffmpeg.org/wiki/CompilationGuide

• To patch FFmpeg for VVenC support follow the guide depending on your operating system.

• VVenC can be enabled in FFmpeg by setting '--enable-libvvenc' in the configure step

Linux

1. Build and install VVenC where it can be found by pkg-config

• Build VVenC shared and install into a system path, e.g.:
  sudo make install install-prefix=/usr/local

1. Clone FFmpeg and go into the downloaded folder

• git clone https://git.ffmpeg.org/ffmpeg.git ffmpeg
• cd ffmpeg

2. Checkout the master
3. Configure and build FFmpeg

• add '--enable-libvvenc' to enable VVenC as VVC encoder. For instance:
• ./configure --enable-pthreads --enable-pic --enable-shared --enable-rpath --arch=amd64 --enable-demuxer=dash --enable-libxml2 --enable-libvvenc
• Add more options to your configure command to enable all needed tools and codecs
• make (use make -j to compile multi-threaded)

4. Install ffmpeg (optional step)

• sudo make install

5. Check if FFmpeg supports VVC
   ffmpeg -hide_banner -codecs | grep vvc
DEV.L. vvc H.266 / VVC (Versatile Video Coding) (encoders: libvvenc)

Patching FFmpeg tag 7.0 or versions before 15th June 2024

When using a FFmpeg version without VVenC support, the latest VVenC patch have to be applied manually before running the configure step

• wget -O libvvenc.patch https://patchwork.ffmpeg.org/series/12059/mbox/
• git apply --check libvvenc.patch
• git apply libvvenc.patch

MacOS

In general you can follow the guidelines for Linux when build on MacOS.

VVenC is also available in Homebrew.
If you want to skip the build process it can be installed by calling:
brew install vvenc

When building on an ARM platform please follow this guide:

ARM devices (M1, M2)

When running on an ARM device you have to build and install VVenC and FFmpeg for ARM To build VVenC on ARM ninja build must be used to build, as with XCode generated libraries are not working.
It can be installed by using Homebrew: brew install ninja

1. Build and install VVenC:
   sudo make g=ninja install install-prefix=/usr/local
   Alternatively install via Homebrew: brew install vvenc
2. configure and build FFmpeg:
   ./configure --enable-pthreads --enable-pic --enable-shared --enable-rpath --arch=arm64 --enable-demuxer=dash --enable-libxml2 --enable-libvvenc

Windows

As building FFmpeg for Windows can be tricky, we recommend the Media Autobuild Suite.
VVenC is already part of the suite and must be enabled during the script setup to get VVC support in FFmpeg.
To enable VVenC follow the instructions given by the script and enable VVenC when asked.

Troubleshooting: Media Autobuild Suite

FFmpeg may fail to build as the Media Autobuild Suite is kind of a moving target.
That means FFmpeg is depending on a bunch of core applications and codecs which are build from the current master branch per default. As a depending repository may fail to build or is not compatible with the ffmpeg version this section will show solutions or workarounds on known issues.

libjxl

• error during ffmpeg configure step: ERROR: libjxl >= 0.7.0 not found using pkg-config
• workaround: disable libjxl in file build/media-autobuild_suite.ini
jpegxl=2 and in file build/ffmpeg_options.txt by comment line
  #--enable-libjxl

libavif

• workaround: disable libavif in file build/media-autobuild_suite.ini
libavif=2

texinfo 7.1 not compatible with current ffmpeg head

• error during ffmpeg build step: /build/ffmpeg-git/doc/t2h.pm: Undefined subroutine &Texinfo::Config::set_from_init_file ...
• workaround: disable html generation in file build/ffmpeg_options.txt by adding
  --disable-doc

libplacebo

• workaround: disable in file build/ffmpeg_options.txt by comment line #--enable-libplacebo or setting
  --disable-libplacebo

set specific revisions

If a dependent library has changed the interface and is not compatible with ffmpeg anymore a particular revision can be set in the file build/media-suite_deps.sh, e.g. for mpv player
SOURCE_REPO_MPV=https://github.com/mpv-player/mpv.git#tag=v0.36.0
The particular FFmpeg revision can also be set in the file build/media-autobuild_suite.ini, e.g.
ffmpegPath=https://git.ffmpeg.org/ffmpeg.git#1b41631185

Available Options and Usage

Check for valid FFmpeg installation

ffmpeg -hide_banner -codecs | grep vvc
DEV.L. vvc H.266 / VVC (Versatile Video Coding) (encoders: libvvenc)

Available options

Run FFmpeg help to see available options for encoder and decoder:
ffmpeg -h encoder=libvvenc

Encoder libvvenc [H.266 / VVC Encoder VVenC]:
General capabilities: dr1 delay threads
Threading capabilities: other
Supported pixel formats: yuv420p10le

libvvenc-vvc encoder AVOptions:
-preset <int> E..V....... set encoding preset(from 0 to 4) (default medium)
faster 0 E..V....... 0
fast 1 E..V....... 1
medium 2 E..V....... 2
slow 3 E..V....... 3
slower 4 E..V....... 4
-qp <int> E..V....... set quantization (from 0 to 63) (default 32)
-qpa <boolean> E..V....... set subjective (perceptually motivated) optimization (default true)
-passlogfile <string> E..V....... Filename for 2 pass stats
-stats <string> E..V....... Filename for 2 pass stats
-period <int> E..V....... set (intra) refresh period in seconds (from 1 to INT_MAX) (default 1)
-vvenc-params <dictionary> E..V....... set the vvenc configuration using a :-separated list of key=value parameters
-level <string> E..V....... Specify level (as defined by Annex A)
-tier <int> E..V....... set vvc tier (from 0 to 1) (default main)
main 0 E..V....... main
high 1 E..V....... high

Basic Usage

• Encode a RAW video file with VVenC into mp4:
  ffmpeg -f rawvideo -vcodec rawvideo -s 1920x1080 -framerate 25 -pix_fmt yuv420p -i file_1080p_25Hz_420_8bit.yuv -an -vcodec libvvenc output.mp4

• Encode with VVenC by using a preset and bitrate:
  ffmpeg -i <input> -c:v libvvenc -b:v 2600k -preset faster <output>

available presets: faster,fast,medium,slow,slower

• Set thread count (default: auto detection)
  ffmpeg -i <input> -an -vcodec libvvenc -threads 6 <output>

Set Encoder specific parameter (vvenc-params)

• Set any available VVenC parameter via -vvenc-params (separated by :) e.g.
  ffmpeg -i <input> -an -vcodec libvvenc -vvenc-params intraperiod=64:decodingrefreshtype=idr:poc0idr=1:internalbitdepth=8 <output>

• Combines command with some available VVenC options:
  ffmpeg -i <input> -an -vcodec libvvenc -b:v 2M -qpa 0 -period 2 -preset medium -vvenc-params internalbitdepth=8:decodingrefreshtype=idr <output>

• using low decoder energy preset (preset must be set to medium)
  ffmpeg -i <input> -an -vcodec libvvenc -preset medium -vvenc-params "NumRefPics=2:DeblockLastTLayers=1:MaxMTTDepth=332222:MaxMTTDepthI=3:Affine=3:ALFSpeed=1:BCW=2:BIO=0:DMVR=0:ISP=0:LFNST=0:LMCSEnable=0:MIP=0:FastMIP=0:SAO=2:SbTMVP=0:FastMrg=2" <output>

VBR Rate control (Variable Bitrate Mode)

• Set target bitrate (VBR mode) (default: 200kbit/s)
  ffmpeg -i <input> -an -vcodec libvvenc -b:v 2000k <output>
ffmpeg -i <input> -an -vcodec libvvenc -b:v 2M <output>

• the maxrate option is available since VVenC v1.9.0 and must be at least 1.5x of the target rate
  ffmpeg -i <input> -an -vcodec libvvenc -b:v 2M -maxrate 3M <output>

• Set 2-pass encoding (default: single pass)

1. run 1st pass:
   ffmpeg -i <input> -acodec copy -vcodec libvvenc -pass 1 -b:v 2M -f null /dev/null
2. run 2nd pass:
   ffmpeg -i <input> -acodec copy -vcodec libvvenc -pass 2 -b:v 2M <output>

combined call:

ffmpeg -i <input> -acodec copy -vcodec libvvenc -pass 1 -b:v 2M -f null /dev/null &&  
ffmpeg -i <input> -acodec copy -vcodec libvvenc -pass 2 -b:v 2M <output>  

Fix QP mode (Constant Quality Mode)

• libvvenc runs in fix QP mode per default, when a bitrate is not defined
  ffmpeg -i <input> -an -vcodec libvvenc -qp 25 <output>

CQF mode (Constant Quality Factor)

• this mode is available since vvenc v1.12.0 ffmpeg -i <input> -an -vcodec libvvenc -qp 25 -maxrate 10M <output>

PSNR based encoding

The parameter -qpa enabled per default and will tune the encoder for perceptual quality.
That means the encoder will perform for better subjective quality and better MS-SSIM results.
When this setting is disabled the encoder performs for better PSRN and VMAF results.

• Disable perceptual optimization for better PSNR and VMAF ( default: enabled )
  ffmpeg -i <input> -an -vcodec libvvenc -qpa 0 <output>

Intra Period (also known as GOP or keyframe interval) and decoding refresh types

• Set intra period (keyframe interval) to 2 seconds ( default: 1sec )
  ffmpeg -i <input> -an -vcodec libvvenc -period 2 <output>

• Set intra period (keyframe interval) in frames to 64
  ffmpeg -i <input> -an -vcodec libvvenc -vvenc-params intraperiod=64 <output>

• Set decoding refreshtype ( idr,cra,idr2,cra_cre, default: cra )
  ffmpeg -i <input> -an -vcodec libvvenc -vvenc-params "decodingrefreshtype=idr" <output>

  • idr : closed GOP
  • cra : open GOP
  • cra_cre : open GOP for streaming

8-bit coding

Be aware of that this feature is only working for VVenC version >= v1.9.1.
Please be also aware of, the input content is always converted to yuv420p10le as the VVenC library only supports 10-bit input.
ffmpeg -i <input> -an -vcodec libvvenc -vvenc-params InternalBitDepth=8 <output>

HDR and SDR signalization for RAW input

• signalization is only needed when input does not contain specific information
• signalizing SDR BT.709: -vvenc-params Sdr=sdr ( BT.2020 -vvenc-params Sdr=sdr_2020)
• signalizing HDR10/PQ : -vvenc-params Hdr=pq ( BT.2020 -vvenc-params Hdr=pq_2020)
• signalizing HLG : -vvenc-params Hdr=hlg (BT.2020: -vvenc-params Hdr=hlg_2020)

Adding VUI and SEI options

• video usability information (VUI)
  ffmpeg -i <input> -an -vcodec libvvenc -vvenc-params vuiparameterspresent=1 <output>
  The VUI is automatically added as soon as SDR/HDR mode is set, e.g.
  ffmpeg -i <input> -an -vcodec libvvenc -vvenc-params sdr=sdr_709 <output>
  When the input signalizes a transfer characteristics or color primaries, the VUI is also enabled by default
• Decoded Picture Hash (DPH)
  use vvenc-params seidecodedpicturehash by using 1,2,3 (1:md5, 2=crc, 3:checksum)
  ffmpeg -i <input> -an -vcodec libvvenc -vvenc-params seidecodedpicturehash=1 <output>

Special Encoding options

• Tile encoding for faster multithreading when using more than 8 threads
  ffmpeg -i <input> -an -vcodec libvvenc -threads 16 -vvenc-params wavefrontsynchro=1:tiles=2x2 <output>

Transcoding

• Transcode Transport stream file with VVC into ISOBMFF file format:
  ffmpeg -i input.ts -an -vcodec libvvenc output.mp4

• Extract RAW ES from mp4:
  ffmpeg -i input.mp4 -an -vcodec copy -bsf h266_mp4toannexb output.266

Additional Information

To reproduce encodings from ffmpeg(libvvenc) with vvencapp the option
-aud 1 respectively --accessunitdelimiter 1
must be set in vvencapp as it always enabled in libvvenc.