homebrew-ffmpeg: a Homebrew tap for ffmpeg with the optional libraries turned on

A third party tap, and why the core formula is not enough

Homebrew ships an ffmpeg formula, and it deliberately leaves out a group of libraries. That is a sensible upstream decision and a recurring source of friction, because the missing pieces are exactly the ones some people need. The decklink flag for Blackmagic DeckLink capture hardware is the classic example, as are the speech synthesis and audio fingerprinting options.

homebrew-ffmpeg is the answer to that gap. The README describes it as a third party tap for Homebrew which provides a formula for ffmpeg including options for enabling additional features and libraries. The repository is minimal by design, holding only .github/, Formula/ and README.md, because a tap is a formula definition rather than a code project.

The primary language is Ruby, which is what Homebrew formulae are written in, and the default branch is master. The CI badge points at a GitHub Actions workflow named main.yml, so every formula change is built in an automated environment before it lands.

The licence field on the repository is not stated, so there is no licence to point at. For a tap that only distributes a formula, that is a smaller concern than it would be for code you link against, but it is worth knowing that the terms are not spelled out in the metadata.

The practical scale of this project should be understood correctly. It is not a fork of ffmpeg, it does not patch the codec, and it does not maintain its own builds of the libraries it pulls in. It is a formula that asks Homebrew to build ffmpeg with more of them, and its whole value is in getting the dependency ordering right.

The default install, and the one conflict you will hit

Installation assumes Homebrew is already present, which the README states as the first requirement. The default sequence is three commands.

brew trust homebrew-ffmpeg/ffmpeg
brew tap homebrew-ffmpeg/ffmpeg
brew install homebrew-ffmpeg/ffmpeg/ffmpeg

The trust step is specific to this tap and is the first thing that differs from an ordinary third party tap. The fully qualified name homebrew-ffmpeg/ffmpeg/ffmpeg then appears in every subsequent command, because the tap is named homebrew-ffmpeg and the formula inside it is also called ffmpeg.

There is one conflict the README warns about, and it is worth reading before you run anything. If you already have ffmpeg installed from Homebrew core, you will receive an error, and you need to first run brew uninstall ffmpeg before you can use this tap.

That is a deliberate trade-off rather than a bug. Homebrew will not let two different formulae own the same command names, and this formula installs ffmpeg, ffprobe and ffplay. The alternative, installing both at once, is exactly what the --with-alt-name option exists to solve, and that option is documented further down.

The consequence for you is a moment of churn. If you already have the core ffmpeg, you uninstall it, install this one, and you are committed to this tap for upgrades, since brew upgrade homebrew-ffmpeg/ffmpeg/ffmpeg targets the tapped formula rather than the core one.

The formula itself installs a long list of libraries by default: libaom for the AV1 encoder, fontconfig and freetype for font access, frei0r filters, lame for MP3, libass for ASS subtitles, libvorbis, libvpx for VP8 and VP9, opus, rtmpdump, sdl2, snappy, svt-av1, theora, x264 for H.264, x265 for HEVC, and xz.

Options are per library, and some have to come first

The optional features are not a single switch. Each one is a separate --with- flag on the formula, and the README's table names them along with what each pulls in.

The list includes --with-chromaprint for the audio fingerprinting library, --with-decklink for DeckLink support, --with-dvd for a DVD-Video demuxer powered by libdvdnav and libdvdread, --with-libflite for text to speech synthesis, --with-game-music-emu for Game Music Emu support, --with-ggml as a tensor library for machine learning that is needed for whisper.cpp, --with-jack for Jack audio device support, --with-jpeg-xl for JPEG XL, and --with-libaribb24 for decoding ARIB and ISDB captions.

To see the full list on your own machine before committing to anything, run:

brew options homebrew-ffmpeg/ffmpeg/ffmpeg

Then install with the flags you want:

brew install homebrew-ffmpeg/ffmpeg/ffmpeg --with-<option1> --with-<option2> ...

If you want everything, the README gives the compact form:

brew install homebrew-ffmpeg/ffmpeg/ffmpeg $(brew options homebrew-ffmpeg/ffmpeg/ffmpeg --compact)

The full-options install is where the dependency constraints bite. The README warns that this may install libraries for which you need extra SDKs installed, such as --with-decklink, or libraries which have to be installed before running the formula, such as --with-chromaprint.

The decklink case is the sharpest one. The README states that the DeckLink SDK has to be installed before running the FFmpeg formula, and it links to Blackmagic Design forum directions if you hit difficulties on macOS. The libflite case is similar but more awkward, since flite has to be installed before running the formula and this is not supported directly via Homebrew, with the README pointing at issue 157 for installation options.

The chromaprint entry carries its own note about a cyclic dependency issue, with a workaround described in the Troubleshooting section of the README.

So the README also offers a filtered install for the common case of wanting everything except the two options with no native homebrew-core repos:

brew install homebrew-ffmpeg/ffmpeg/ffmpeg $(brew options homebrew-ffmpeg/ffmpeg/ffmpeg --compact | tr ' ' '\n' | grep -v 'with-decklink' | grep -v 'with-libflite' | grep -v 'with-alt-name' | xargs)

Reading that command tells you the ordering problem is not abstract: a build script that links against the DeckLink SDK cannot link against an SDK that is not on the machine yet.

HEAD builds and the alt-name install

Two options change what gets installed rather than which libraries are linked in, and they are the two that make this tap usable in situations where you cannot simply replace the core ffmpeg.

The first is --HEAD. FFmpeg recommends installing the latest Git master version over a release, the README explains, and this formula builds the latest release by default, so you need to ask for the Git version explicitly:

brew install homebrew-ffmpeg/ffmpeg/ffmpeg --HEAD

The warning attached to it is the important part. The maintainers do not generally provide support for HEAD builds, since they may cause issues with other Homebrew-supplied formulae. That is an honest statement of the risk: a master build can change behaviour underneath a script that expects the release, and the tap will not help you when it does.

The second is --with-alt-name. The README gives the reason as needing to install the commands of this FFmpeg formula under an alternative name, for example having the regular ffmpeg, ffprobe and ffplay commands in parallel with ffmpeg-alt, ffprobe-alt and ffplay-alt.

brew install homebrew-ffmpeg/ffmpeg/ffmpeg --with-alt-name

This is the option that changes the calculus of the whole tap. Without it, adopting this tap means uninstalling the core ffmpeg and owning a replacement. With it, the two coexist, the standard commands stay pointing at the core formula, and the alt-named ones give you the extra codecs. For a machine where something else already depends on the core ffmpeg, that is the difference between this tap being usable and not.

Worth noting the asymmetry in how the two are described. The alt-name option is presented as a normal feature, while the HEAD option carries an explicit support disclaimer. One is a supported way to install, the other is a supported way to experiment.

Updating, and the difference between release and HEAD upgrades

Updates follow Homebrew's normal model, with one branch for each installation kind.

For a release install, Homebrew is updated and the tapped formula is upgraded in a single command:

brew update && brew upgrade homebrew-ffmpeg/ffmpeg/ffmpeg

For a HEAD install, the fetch flag is added so the upgrade pulls the latest commit rather than the latest release:

brew update && brew upgrade homebrew-ffmpeg/ffmpeg/ffmpeg --fetch-HEAD

The two-line command form is the right pattern here because brew update and the upgrade are separate steps with a real dependency between them. Running brew upgrade alone against a stale Homebrew index will resolve the formula against old metadata, and the mismatch shows up as an unexplained failure rather than as a clear error.

The maintenance picture for the tap itself is modest but current. The last push was on 2026-10-22 and the repository is not archived, with a GitHub Actions CI workflow on the master branch. It has no GitHub releases, which is normal for a Homebrew tap, since the artefacts are the formula files rather than tagged versions, and Homebrew itself does the version tracking from the upstream ffmpeg release.

What that means for you in practice is that upgrading is a pull of the tap and a rebuild of ffmpeg, which takes time, and that the tap has no version history of its own to consult when something breaks. The changelog you consult is Homebrew's and ffmpeg's, not the tap's.

Where this tap is the wrong answer

There are three limits, and the first is the one the README is most candid about.

The first is that the library you want may not be installable at all through Homebrew. The flite option needs the library installed before the formula runs and is not supported directly via Homebrew, with the README sending you to issue 157 for options. The DeckLink option needs the Blackmagic SDK installed first. These are not build failures you can retry your way out of; they are external prerequisites, and on a machine you do not administer, such as a locked-down laptop or a CI image, they may be unobtainable.

The second is that the alternative options are unmaintained in a way that the project does not hide. --HEAD has no support commitment from the maintainers, and the reason given is that HEAD builds may cause issues with other Homebrew-supplied formulae. If your ffmpeg is in a production pipeline, an upstream master build that changed a default flag is a real operational risk, and the tap offers no way to pin a specific master commit.

The third is the cost of the swap. If the only thing you need is, say, the AV1 encoder or the Opus encoder, the core Homebrew ffmpeg formula already installs libaom and opus by default, and you would be uninstalling a working binary and rebuilding a larger one to get features you already have. The tap earns its keep only when the specific option you need is one of the optional ones, and the list of optional ones is short enough to check against your requirements before you commit.

The honest alternative is to build ffmpeg yourself from source, which is what a lot of people who need a specific combination end up doing. The difference in approach is that a source build gives you every option ffmpeg offers, including ones this tap does not wrap, and it gives you version control over exactly which commit you run. What it costs is the dependency work, the platform-specific flags for each library, and on macOS the need to keep that build current against new Xcode releases. The tap's proposition is that Homebrew handles the build system for you and you only name the options you want, accepting a curated subset of the available flags and, for the two awkward ones, manual preparation of the prerequisite SDK.

Editorial conclusion

Adopt homebrew-ffmpeg if you need an ffmpeg feature that the Homebrew core formula leaves out, such as DeckLink capture, flite speech synthesis or chromaprint fingerprinting, since the tap turns each into a documented install flag. Do not adopt it if the core formula already covers your codecs, because installing this tap requires uninstalling the core ffmpeg first. Before you install, read the option list with brew options homebrew-ffmpeg/ffmpeg/ffmpeg and check the ordering constraints on decklink and flite, and note the last push was on 2026-10-22.

Frequently asked questions

Official sources

1. homebrew-ffmpeg/homebrew-ffmpeg on GitHub
2. Issues
3. README