FFmpeg Integration

VVenC is officially supported in FFmpeg since 15th June 2024 (revision c75940db29).
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

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

Clone FFmpeg and go into the downloaded folder

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

Checkout the master
Additional: If you are using a FFmpeg version before 15th June 2024 or the latest FFmpeg tag 7.0, the latest VVenC patch have to be applied manually:
- wget -O libvvenc.patch https://patchwork.ffmpeg.org/series/12059/mbox/
- git apply --check libvvenc.patch
- git apply libvvenc.patch
Configure and build FFmpeg

./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)

Install ffmpeg (optional step)

sudo make install

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

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

Build and install VVenC:
sudo make g=ninja install install-prefix=/usr/local
Alternatively install via Homebrew: brew install vvenc
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.

Follow the guide given in the Media Autobuild Suite to build FFmpeg.

Clone the media-autobuild_suite

git clone https://github.com/m-ab-s/media-autobuild_suite
cd media-autobuild_suite

Patch media-autobuild_suite to enable ffmpeg with vvc support

Open the file media-autobuild_suite/build/media-suite_compile.sh in your favorite Editor
Search for line lib/cmake/vvenc/vvencConfig.cmake):

if [[ $bits = 64bit && $vvenc = y ]] &&
     do_vcs "$SOURCE_REPO_LIBVVENC"; then
 # vvenc implementation
fi

change the line fi to following code:

else
    pc_exists libvvenc || do_removeOption "--enable-libvvenc"
fi

Save and close the file media-autobuild_suite/build/media-suite_compile.sh
Open the file media-autobuild_suite/media-autobuild_suite.bat in your favorite Editor
Search for the line:
libdav1d libaom --disable-debug libfdk-aac
Change the line to:
libdav1d libaom --disable-debug libfdk-aac libvvenc
Save and close the file media-autobuild_suite/media-autobuild_suite.bat

Open the Windows PowerShell and run:
media-autobuild_suite.bat
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>

Rate control (VBR 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)

run 1st pass:
ffmpeg -i <input> -acodec copy -vcodec libvvenc -pass 1 -b:v 2M -f null /dev/null
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

libvvenc runs in fix QP mode per default, when a bitrate is not defined
ffmpeg -i <input> -an -vcodec libvvenc -qp 25 <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)

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

Provide feedback

Saved searches

Use saved searches to filter your results more quickly