Skip to content

Set up FFmpeg

FFmpeg is a free, open source program that reads and writes video. Kitlig hands it every video job instead of shipping its own copy, so you install it once on your machine and Kitlig finds it from then on.

If you never touch video in Kitlig, you can skip this page. Image generation, 3D work, and mocap all run without it.

What Kitlig greys out without it

Tools that need FFmpeg stay visible but greyed out until it's installed. Clicking a greyed tool opens the FFmpeg setup window instead of failing partway through, so you're never left with a broken result.

  • Every tool on the video player's toolbar: trim, re-fps, crop, pad, resize, extract audio, extract frame, image sequence, and re-encode. See Video tools.
  • Extract frames in Tracking. That's step one of every session made from a video, so a tracking session can't start without it. See Tracking.
  • Render Insert in planar tracking, which encodes your comp to an mp4, and the video export of tracked targets.
  • Everything in Redub, and the Export and Package actions in Video mode.
  • The audio operations that run on your machine: stem separation, Mix Audio, Replace & Remix, and Combine Media.
  • Reading the resolution, frame rate, and duration of a video when you import it.

In the operation lists, an amber film icon marks an entry that needs FFmpeg. On the Workflow canvas a node that needs it shows a needs FFmpeg tag; you can still build the graph, but Run opens the setup window until FFmpeg is there.

Screenshots from the player still work, and so do the crop, pad, and resize tools on image assets. Those don't go through FFmpeg.

Why you install it yourself

The FFmpeg builds that include H.264 and H.265, the codecs nearly all footage uses, are licensed under the GPL. Kitlig is commercial software and can't redistribute them. Pointing Kitlig at your own install means you get every codec rather than a cut-down build.

Let Kitlig install it

The quickest route. On Windows and macOS, Kitlig can run your system's package manager for you.

  1. Click any greyed-out video tool, or the FFmpeg not set up note in the status bar along the bottom of the window. The FFmpeg setup window opens.
  2. Read the short license note. FFmpeg is a separate program with its own license, and clicking the button means you accept it.
  3. Click Install FFmpeg for me. On Windows this runs winget install --id Gyan.FFmpeg -e; on macOS it runs brew install ffmpeg. The exact command is printed beside the button, and nothing else on your computer changes.
  4. Watch the log. A Windows install takes about a minute. Homebrew installs a few helper libraries as well, so allow several minutes on a Mac.
  5. When it finishes, the status flips to Found FFmpeg with a version number. Kitlig re-checks on its own; there's nothing to restart.

The same button lives in Settings under Tools & Apps, and on the FFmpeg step of the welcome tour.

When the button isn't offered

Kitlig only offers the button when it finds a package manager it can drive: winget on Windows, Homebrew on macOS. Without one, or on Linux, the setup window shows the steps below instead. On a Mac without Homebrew, the first step is to install Homebrew from brew.sh, then come back and click the button.

Install it yourself

Pick the one for your system and run it in a terminal. Each installs a full build with all the common codecs. The setup window shows these same commands with a copy button next to each.

winget install --id Gyan.FFmpeg -e

No winget? Download the "release essentials" zip from gyan.dev, the builds page that ffmpeg.org links to for Windows. Unzip it somewhere permanent such as C:\ffmpeg, then point Kitlig straight at C:\ffmpeg\bin\ffmpeg.exe (see below). If Windows warns that it protected your PC, choose More info, then Run anyway.

brew install ffmpeg

This needs Homebrew. Without it, download a build from evermeet.cx, the macOS builds page that ffmpeg.org links to, and point Kitlig at the file. The first time you open it macOS may say it can't verify the developer; right-click the file, choose Open, and confirm once.

sudo apt install ffmpeg      # Debian, Ubuntu, Mint
sudo dnf install ffmpeg      # Fedora (needs RPM Fusion enabled)
sudo pacman -S ffmpeg        # Arch

Switch back to Kitlig afterwards. It re-checks when the window regains focus, so the greyed tools clear on their own. If they don't, click Re-check in Settings.

Checking that Kitlig found it

Open Settings, choose Tools & Apps, and find the FFmpeg section. Found FFmpeg with a version number means you're done. Underneath it, Kitlig names where the install came from, which is handy when you have more than one copy on the machine.

Not found means Kitlig looked and came up empty. The status bar along the bottom of the window says FFmpeg not set up as well; click it to open the setup window.

Kitlig looks before it asks

You usually don't have to do anything here. Kitlig checks your PATH and the usual install folders on its own, so a normal install is picked up without being told. The controls below are for the times that doesn't happen.

If Kitlig can't find it

Click Locate FFmpeg... and pick the program file yourself. On Windows that's ffmpeg.exe, usually in the bin folder of wherever you unzipped it. On macOS and Linux it's a file called ffmpeg with no extension.

Once you've set a path by hand, Kitlig uses it and stops guessing. If you later want it back on autopilot, click Use auto-detect.

If a codec is missing

Some FFmpeg builds ship without H.264 or H.265. This is common in minimal Linux packages. Kitlig checks which encoders your build has, and works around the gaps where it can: if H.264 is missing but your graphics card can encode it, Kitlig uses the card instead and says so in Settings.

When there's no way to encode a codec at all, Kitlig tells you which one and stops rather than producing a broken file. The fix is to install a fuller build, listed as "full" on the FFmpeg downloads page.

Next step

You're set up. Head to Sandbox Mode and generate your first asset.