Does FFmpeg 5 Break Your Scripts?

FFmpeg turns 5.0; the new release has big API changes but doesn’t appear to break existing command scripts, though x265-based encodes are worth checking.

As much as we like major releases of programs that we know and love, one big question is always whether it changes how we use the program. If you haven’t heard, on January 17, 2022, FFmpeg 5.0, called “Lorentz” became available. According to FFmpeg, “a major effort underwent to remove the old encode/decode APIs and replace them with an N:M-based API.” So, if you’re working with FFmpeg via an API, the new release is cause for concern.

A comprehensive list of changes and features is available in this post from VLC lead developer Jean-Baptiste Kempf. He details that some of the main API changes are:

  • avcodec encoding+decoding change
    • Single API for Audio & Video
    • Decoupled codec input & output
  • new callback allowing encoders to output data into user-managed buffers
  • AVFrame based API in swscale
  • disentangled avformat and avcodec
  • demuxers no longer embed an entire decoder context
  • new bitstream filtering API
  • can be used as codec header analyzer
  • codec/format registration APIs removed, all formats are always registered
  • type safety: int to size_t replacements in various APIs
  • libavresample removal

He also notes that FFmpeg 4.4 is still available and supported, and lists new features.

Does FFmpeg 5 Break Existing Scripts? Probably Not

I spent the better part of the weekend checking the encoding scripts from my course on FFmpeg and the only major changes I found related to x265 encoding. To explain, a couple of years ago, when I first started producing x265, many of the significant commands had to be behind the x265-params switch and formatted differently than when encoding with x264, VP9, AV1, and other codecs. Since then, more of these switches, including for GOP and related command and bitrate controls, now use generic commands, as shown in the PowerPoint slide below.

FFmpeg 5 doesn't appear to break scripts but you might consider updating your x265 controls.

It’s not that FFmpeg 5 broke these command strings as the old ones still work, but I wanted to update them to conform to the new reality which is simpler. I’ve detailed all that in the YouTube video embedded below. The video covers:

00:00 – The bifurcated command structure involved with x265
1:16 – How to check your work with MediaInfo
3:52 – What HEVC profiles are and how to set them
6:27 – What x265 presets are and how to choose them
10:40 – How to encode with closed-GOPs

Here’s a link to a text file with the scripts, and here’s a link to the PowerPoint PDFs. If you spot anything incorrect, please let me know at

About Jan Ozer

I help companies train new technical hires in streaming media-related positions; I also help companies optimize their codec selections and encoding stacks, and evaluate new encoders and codecs.

Check Also

Per-Title Encoding 2022

My article, Buyers’ Guide to Per-Title Encoding is up on Streaming Media. Per-title encoding is …


  1. if input is yuv it’s worth to specify the frame rate with ‘-r’ (otherwise the default 25fps taken), e.g.

    ffmpeg -y -s 1920×1080 -i .test1920x1080.yuv -c:v libx265 -r 60 -g 60 -keyint_min 60 -b:v 10000k -maxrate 11000k -x265-params ref=1:bframes=0 -frames 100 swbf.h265

  2. Bart Z. Lederman

    I strongly disagree with your “probably not” about breaking scripts.

    5.0 is breaking EVERY ONE of my scripts.

    I use QSV to accelerate decoding and encoding, and they have broken everything associated with the use of the QSV hardware input and output: and they don’t properly explain the new syntax ANYWHERE I can find. None of the comments or error messages make any sense. Even when I cut and paste their suggestion in the error message into my script, it’s still flagged as an error.

    This kind of arrogant behavior has, unfortunately, been going on for a long time with the developers “deprecating” features that are needed for repairing less than perfect input files.