FFmpeg 9 Breaking Changes: Five Flags Your Scripts Still Use

Your Dockerfile says apk add ffmpeg. The base image rebuilt last week. Now every job in the pipeline dies before it reads a single frame, and the log line is four words long: Unrecognized option 'vsync'. Nothing in your code changed.

Quick answer: The FFmpeg 9 breaking changes that kill working scripts are five hard-removed CLI flags: -vsync, -top, -qphist, -filter_complex_script, and -adrift_threshold. FFmpeg 9.0 exits immediately on each one with Unrecognized option '<flag>' instead of warning, so the fix is a one-line swap per flag (-fps_mode, setfield, delete it, -/filter_complex, aresample=async=1). If you'd rather not re-audit every script on the next major, send the same job to the FFmpeg Micro API instead of shipping an FFmpeg binary, and the encoder version stops being a thing you own.

Conventional wisdom says a pinned binary makes this someone else's problem. That's half right. Pinning works until the pin moves, and pins move for reasons outside your control: a base image bumps, a CI runner refreshes, Homebrew upgrades on a laptop, a teammate rebuilds without --platform. FFmpeg 9.0 "Lei" shipped on August 3, 2026, with 9.0.1 on August 12 and 9.0.2 on September 19. By late September the breakage had already surfaced in public repos: bradautomates/claude-video has two open issues on frame extraction failing under FFmpeg 9, 0xchamin/mcptube issue #8 is titled almost exactly the error string, and debpalash/VoiceStudio has a PR that exists only because -filter_complex_script vanished from its dubbing export.

The interesting part is who broke first. It wasn't media engineers. It was LLM and agent pipelines extracting frames with -vsync vfr, copied from a Stack Overflow answer written in 2019.

What the error actually tells you

FFmpeg 9 doesn't degrade gracefully on a removed flag. It fails argument parsing, which means it exits before touching your input file and before printing anything about codecs:

Unrecognized option 'vsync'.
Error splitting the argument list: Option not found

Exit code is 1. There's no frame count, no stream info, no partial output. That's actually useful: if you see stream metadata in the log, your flags parsed fine and your problem is somewhere else. Argument-parsing failures and encode failures look nothing alike, which rules out a whole branch of debugging in one glance.

The same two lines appear for all five flags with the name swapped. A pipeline that only checks for a non-zero exit code and retries will retry forever.

The five removed flags and the replacement for each

Four of the five had deprecation warnings for years, which is why almost nobody noticed. -fps_mode landed in FFmpeg 5.1 back in 2022 and -vsync has printed a deprecation notice ever since. Warnings on stderr in a CI job are invisible. Removal is not.

The -vsync to -fps_mode mapping is the one that bites quietly. -vsync 0 means passthrough, not constant frame rate, and people who guess reach for cfr because it sounds like the safe default. On a variable-frame-rate screen recording, cfr duplicates frames to hit the target rate. Your frame-extraction script keeps running, exits 0, and hands your vision model forty copies of the same still.

-/filter_complex reads strange enough that a reviewer will "fix" the slash back out. It's correct. FFmpeg 7.1 generalized value-from-file to -/<option> <path> for every option, then retired the two bespoke versions (-filter_script and -filter_complex_script) that predated it.

For -qphist, if you were using it to sanity-check encode quality, per-frame QP dumps are a weak proxy anyway. Scoring the output against the source with VMAF tells you what you actually wanted to know.

The NPP filters are gone, and that one has no one-line fix

FFmpeg 9.0 also deleted every libnpp filter: scale_npp, scale2ref_npp, sharpen_npp, and transpose_npp. This is a harder break than the flags because there's no drop-in equivalent that keeps frames on the GPU with identical syntax.

For scaling, scale_cuda is the closest match and covers most scale_npp usage, though the interpolation algorithms differ slightly so your output bytes won't be identical. transpose_npp has no CUDA counterpart in mainline; you either round-trip to system memory and use plain transpose, or move the whole graph to Vulkan filters. sharpen_npp is the worst off: the honest answer is unsharp on CPU, which means your GPU pipeline now has a CPU stage in the middle of it.

If you built around NPP specifically for throughput, plan a real migration, not a find-and-replace.

Audit your repo before the next rebuild

One grep finds most of it. Run this at the root of anything that shells out to FFmpeg, including n8n workflow exports, Makefiles, and YAML:

grep -rnE '[-](vsync|qphist|filter_complex_script|adrift_threshold)\b' . \
  --include='*.{js,ts,py,sh,json,yaml,yml,Dockerfile}'

-top needs its own pass because the bare word is too common to grep cleanly; search for -top with the trailing space and a digit. Also check anything that builds an argument array programmatically, since '-vsync', '0' as two strings won't match a pattern looking for -vsync 0.

Two more things the grep won't catch. FFmpeg 9 flips tls_verify to 1 by default, so an https:// input from a host with a self-signed or misconfigured certificate now fails where it used to work. And every library major was bumped for a full ABI break, so anything linking libavcodec directly needs recompiling. Wrappers that shell out to the binary, like fluent-ffmpeg or the n8n Execute Command node, only care about the flags. Bindings that link the libraries, like PyAV, need a rebuilt wheel.

Why a hosted API never sees this class of break

Here's the part that's easy to miss while you're busy fixing five flags: you're not maintaining video features, you're maintaining an encoder deployment. Every major release makes you re-audit the same scripts, and the pin you add today is the pin someone silently moves in eleven months. This is the same failure shape as n8n's distroless image breaking every published install-ffmpeg recipe: your code was fine, the substrate moved.

That's the argument for calling the FFmpeg API instead of installing FFmpeg. You submit a job, we run it on a managed toolkit, you download the output. There's no binary in your image to version-skew, no base-image PR to scramble on, and no flag in your codebase that a release can retire. The request you wrote in 2025 makes the same request in 2027.

Where that's the wrong call: if you're doing sustained GPU-bound bulk transcoding on hardware you already own and amortize, keep running it. Same if you're air-gapped, or if you need sub-second round trips inside an interactive loop. A network hop is a network hop.

Pitfalls that show up after the fix

The upgrade rarely fails a second time on the same line. It fails a few inches to the left.

FAQ

Does FFmpeg 9 still accept -vsync with a deprecation warning?

No. FFmpeg 9.0 removed -vsync entirely and exits with Unrecognized option 'vsync' during argument parsing. The warning period ran from FFmpeg 5.1 in 2022 until the 9.0 release on August 3, 2026.

What replaces -filter_complex_script in FFmpeg 9?

Use -/filter_complex script.txt, the generic read-option-value-from-file syntax introduced in FFmpeg 7.1. The file contents stay exactly the same; only the flag changes. The older -filter_script for simple filter graphs becomes -/filter:v script.txt.

Can I just pin FFmpeg 8 and skip this?

Pinning FFmpeg 8 works right now and buys you a release cycle. It doesn't hold long: distro packages roll forward, base images rebuild, and 8.x will stop getting security fixes. Treat a pin as a scheduling tool, not a fix.

Does FFmpeg 9 break fluent-ffmpeg, PyAV, or n8n workflows?

FFmpeg 9 breaks anything passing the five removed flags, which includes fluent-ffmpeg calls and n8n Execute Command nodes that shell out with -vsync. PyAV and other bindings that link libavcodec directly need rebuilding against the new ABI, because FFmpeg 9.0 bumped every library major version.

Why did my HTTPS input start failing after upgrading?

FFmpeg 9.0 changed the tls_verify default to 1, so certificate validation is now on by default for https:// and tls:// inputs. Self-signed certificates that silently worked under FFmpeg 8 now fail the handshake. Fix the certificate chain rather than setting -tls_verify 0, unless the host is one you control.

If your next hour was going to be spent grepping for -vsync across four repos, it's worth ten minutes to run one of those jobs as an API call first and see what the pipeline looks like without a binary in it. The free tier is enough to port a single script and compare the output.