FFmpeg setup
How cliply manages FFmpeg for local video processing.
On this page
FFmpeg is the video processing tool that powers clip export and freeze-frame extraction in the cliply desktop app. You do not need to install it manually — cliply downloads and manages its own copy on first use.
How it works
The first time you try to export a clip or extract a freeze frame, the app checks whether a usable FFmpeg binary is available. The resolution order is:
- Managed binary — a copy cliply previously downloaded into the app's data folder
- Environment variable — a path set via
FFMPEG_PATH(for advanced users) - Homebrew (Apple Silicon) —
/opt/homebrew/bin/ffmpegif present - Homebrew (Intel / manual) —
/usr/local/bin/ffmpegif present - MacPorts —
/opt/local/bin/ffmpegif present
If none of these are found, the app shows a Download FFmpeg banner.
One-click download
See the banner
When you attempt an export without FFmpeg available, a banner appears: "FFmpeg required — approximately 60 MB one-time download."
Click Download
Click the Download button. A progress bar shows the download status. The binary is fetched from cliply's release server, not directly from a third party.
Checksum verification
After the download completes, the app verifies the file's SHA-256 checksum before accepting it. If the checksum does not match, the file is discarded and the banner reappears.
Ready
The export button re-enables immediately. The binary is stored in the app's data folder and reused across sessions.
Where the binary is stored
The managed binary lives in:
~/Library/Application Support/app.cliply.desktop/bin/ffmpeg
(The folder path uses app.cliply.desktop.dev during development.)
To force a re-download — for example, if the binary becomes corrupted — delete the bin/ directory. The app will detect the missing binary and show the download banner again.
Why cliply doesn't bundle FFmpeg
FFmpeg is not included in the app download for two reasons:
- License compliance. Distributing a common FFmpeg build would include GPL-licensed codecs. cliply uses Apple's native H.264 encoder (
h264_videotoolbox) to stay license-clean. The managed download shifts the GPL compliance burden to the user's own machine. - Download size. A static FFmpeg binary adds roughly 100 MB to every install, most of which most users will never exercise in the first session.
Troubleshooting
| Problem | Fix |
|---|---|
| Download fails immediately | Check your internet connection and retry |
| "Checksum mismatch" error | Retry the download — the file may have been corrupted in transit |
| Export fails after download | Delete ~/Library/Application Support/app.cliply.desktop/bin/ and retry — the app will re-download a fresh copy |
| Already have Homebrew FFmpeg | The app will find it automatically; no download needed |
The managed download works on Intel Macs too — the app downloads the matching x86_64 build automatically. If you prefer, you can still install FFmpeg yourself with Homebrew (brew install ffmpeg) and the app will pick it up from /usr/local/bin/ffmpeg.