FFmpeg Setup

vidpipe requires FFmpeg 6.0+ for audio extraction, silence removal, short-clip cutting, and caption burning. Both ffmpeg and ffprobe must be available.

---

Quick Check

Verify that FFmpeg is already installed and accessible:

ffmpeg -version
ffprobe -version

If both commands print version info (6.0 or higher), you're ready to go.

---

Windows

Option A: winget (recommended)

winget install Gyan.FFmpeg

After installation, restart your terminal. FFmpeg will be available on PATH.

Option B: Chocolatey

choco install ffmpeg

Option C: Manual download

1. Download the latest full build from gyan.dev/ffmpeg/builds (choose "ffmpeg-release-full.7z")
2. Extract to a permanent location, e.g. C:\tools\ffmpeg
3. Add the bin folder to your system PATH:

   # Permanently add to user PATH
   [Environment]::SetEnvironmentVariable(
     "Path",
     "$([Environment]::GetEnvironmentVariable('Path', 'User'));C:\tools\ffmpeg\bin",
     "User"
   )
   

4. Restart your terminal and verify with ffmpeg -version

Windows ARM64 (important)

Pre-built FFmpeg binaries for Windows ARM64 are less common. You must install FFmpeg manually and point the tool to it:

1. Download an ARM64 build from github.com/ArsThauwormo/FFmpeg-Builds-ARM64 or build from source
2. Extract to a known location, e.g. C:\tools\ffmpeg-arm64\
3. Set the paths in your .env or as environment variables:

FFMPEG_PATH=C:\tools\ffmpeg-arm64\bin\ffmpeg.exe
FFPROBE_PATH=C:\tools\ffmpeg-arm64\bin\ffprobe.exe

Or pass them as environment variables:

$env:FFMPEG_PATH = "C:\tools\ffmpeg-arm64\bin\ffmpeg.exe"
$env:FFPROBE_PATH = "C:\tools\ffmpeg-arm64\bin\ffprobe.exe"
vidpipe --once ./my-video.mp4

---

macOS

Homebrew (recommended)

brew install ffmpeg

This installs both ffmpeg and ffprobe and adds them to PATH.

MacPorts

sudo port install ffmpeg

---

Linux

Ubuntu / Debian

sudo apt update
sudo apt install ffmpeg

Fedora

sudo dnf install ffmpeg

Arch Linux

sudo pacman -S ffmpeg

Alpine (Docker)

RUN apk add --no-cache ffmpeg

---

Setting Custom Paths

If FFmpeg is installed to a non-standard location (or you have multiple versions), tell the tool where to find the binaries.

Via .env file

FFMPEG_PATH=/usr/local/bin/ffmpeg
FFPROBE_PATH=/usr/local/bin/ffprobe

Via environment variables

export FFMPEG_PATH=/opt/ffmpeg/bin/ffmpeg
export FFPROBE_PATH=/opt/ffmpeg/bin/ffprobe
vidpipe --watch-dir ./watch

Windows example

FFMPEG_PATH=C:\tools\ffmpeg\bin\ffmpeg.exe
FFPROBE_PATH=C:\tools\ffmpeg\bin\ffprobe.exe

Note: When FFMPEG_PATH and FFPROBE_PATH are not set, the tool defaults to ffmpeg and ffprobe — expecting them to be on your system PATH.

---

Verifying Your Installation

Run the built-in version check:

ffmpeg -version 2>&1 | head -1
# Expected: ffmpeg version 6.x.x or 7.x.x ...

ffprobe -version 2>&1 | head -1
# Expected: ffprobe version 6.x.x or 7.x.x ...

Then test that the tool can find them:

vidpipe --verbose --once /path/to/short-test-video.mp4

In verbose mode, you'll see the FFmpeg paths logged during the ingestion stage.

---

Fonts

Montserrat Bold is bundled with the package in assets/fonts/ — no manual installation required. FFmpeg is configured to use the bundled font file automatically when burning captions.

Fallback: If you need to use a different font, you can install it system-wide and update the caption generation settings. But the default setup works out of the box.

---

Troubleshooting

"ffmpeg: command not found"

FFmpeg is not on your PATH. Either:

• Install it using the instructions above
• Set FFMPEG_PATH and FFPROBE_PATH to absolute paths

"ffprobe: command not found" (but ffmpeg works)

Some minimal FFmpeg installations omit ffprobe. Reinstall the full package (not the "essentials" build).

Old FFmpeg version causes errors

Some features (e.g. advanced subtitle filters, certain codec options) require FFmpeg 6.0+. Check your version:

ffmpeg -version

If it's below 6.0, upgrade using the instructions for your platform above.

Windows ARM64: FFmpeg not found

Pre-built FFmpeg binaries for ARM64 are less common. Follow the Windows ARM64 section above to install manually and set the paths via FFMPEG_PATH and FFPROBE_PATH.