-
Notifications
You must be signed in to change notification settings - Fork 12
Hydra ffmpeg integration
Hydra downloads HLS and DASH streams without FFmpeg. FFmpeg is optional — it is only needed to convert what was downloaded into a different container, and to combine separate video and audio tracks into one file.
This page explains exactly what changes when FFmpeg is present, how Hydra finds it, and how to install it on every supported platform.
- Do I actually need FFmpeg?
- What FFmpeg changes
- How Hydra finds FFmpeg
- Installing FFmpeg
- Pointing Hydra at a specific build
- Verifying the integration
- What Hydra runs
- Troubleshooting
- FAQ
No — for most downloads. Hydra fetches, decrypts and assembles stream segments entirely on its own. FFmpeg never touches the network and is never used to download anything.
You need FFmpeg only in these cases:
| Situation | Without FFmpeg | With FFmpeg |
|---|---|---|
| HLS with MPEG-TS segments, saved as TS | ✅ Works | ✅ Works |
| HLS with MPEG-TS segments, saved as MP4 | ❌ Refused | ✅ Remuxed to MP4 |
| Fragmented MP4 (fMP4/CMAF) segments, saved as MP4 | ✅ Works — stays fragmented | ✅ Remuxed to a regular, faststart MP4 |
| Fragmented MP4 segments, saved as TS | ❌ Refused | ✅ Remuxed to TS |
| DASH with separate video and audio tracks | ✅ Video + audio in one file |
Hydra never silently produces a broken file. When a conversion is impossible it refuses with an explanation instead of writing a
.mp4that is really MPEG-TS inside. That is why some rows are marked "Refused" rather than falling back.
Many HLS streams ship MPEG-TS (.ts) segments. Concatenated, they form a valid .ts file that plays in VLC and mpv — but not in every browser, editor, or phone gallery.
With FFmpeg, Hydra converts the assembled file to MP4 using a stream copy — the video and audio are never re-encoded, so there is no quality loss and the conversion runs at disk speed rather than CPU speed.
Without FFmpeg, Hydra offers the TS row instead. In the browser extension's "Download this video" menu, TS streams list both a TS and an MP4 row so you can take the one your machine can produce.
fMP4/CMAF segments already concatenate into a playable .mp4. But the moov atom (the index) sits at the end, and the file stays fragmented — which older players and video editors handle poorly.
When FFmpeg is available, Hydra always remuxes MP4 output with -movflags +faststart, moving the index to the front. The file becomes seekable immediately and is an ordinary MP4 that any editor accepts.
Without FFmpeg, the fragmented file is handed over as-is — it plays, so refusing would be unhelpful.
MPEG-DASH usually keeps video and audio in separate representations. Combining them is a real muxing step, not a concatenation.
With FFmpeg, Hydra downloads both tracks and muxes them into one file. Without it, you get the video track only, and Hydra logs a warning naming the reason.
Alternate audio renditions and subtitles are downloaded as separate tracks; combining them into a single file requires FFmpeg for the same reason DASH does.
Hydra looks for an executable named ffmpeg (ffmpeg.exe on Windows) in this order, and stops at the first hit:
1. The HYDRA_FFMPEG environment variable.
If set, this path is used and nothing else is tried. If it is set but wrong, Hydra reports "not found" rather than quietly falling back to a different FFmpeg — that silent fallback is how "why is it still using the old build?" happens.
2. Your PATH.
Every directory in PATH, in order.
3. Well-known install locations.
A GUI application launched from Finder, the Dock, or a desktop launcher inherits a minimal PATH that often omits /opt/homebrew/bin and /usr/local/bin. So Hydra also checks:
/opt/homebrew/bin (Homebrew on Apple Silicon)
/usr/local/bin (Homebrew on Intel, manual installs)
/usr/bin
/bin
/opt/local/bin (MacPorts)
/snap/bin (Snap)
/var/lib/flatpak/exports/bin (Flatpak)
C:\Program Files\ffmpeg\bin
C:\ffmpeg\bin
A candidate counts only if it is a regular file and, on Unix, has an execute bit set.
Detection is cached for 5 seconds. Install FFmpeg while Hydra is running and the Options window reflects it within a few seconds — no restart needed.
winget install --id Gyan.FFmpeg -eClose and reopen Hydra afterwards so it inherits the updated PATH.
choco install ffmpeg-full -yscoop install ffmpeg- Download a release full build from https://www.gyan.dev/ffmpeg/builds/ or https://github.com/BtbN/FFmpeg-Builds/releases.
- Extract the archive to
C:\ffmpegso thatffmpeg.exesits atC:\ffmpeg\bin\ffmpeg.exe. - That path is one Hydra checks automatically — you can stop here. To make FFmpeg available to every program, also add it to
PATH:
setx PATH "$env:PATH;C:\ffmpeg\bin"Then sign out and back in, or reboot, for the change to reach already-running applications.
Note:
setxtruncatesPATHat 1024 characters. If yourPATHis long, use Settings → System → About → Advanced system settings → Environment Variables and edit it there instead.
brew install ffmpegThis installs to /opt/homebrew/bin/ffmpeg on Apple Silicon or /usr/local/bin/ffmpeg on Intel. Both are checked automatically, so Hydra finds it even when launched from the Dock.
sudo port install ffmpegInstalls to /opt/local/bin/ffmpeg, which Hydra also checks automatically.
- Download a build from https://evermeet.cx/ffmpeg/ (Intel) or https://osxexperts.net/ (Apple Silicon).
- Move the binary somewhere permanent and make it executable:
sudo mkdir -p /usr/local/bin
sudo mv ~/Downloads/ffmpeg /usr/local/bin/ffmpeg
sudo chmod +x /usr/local/bin/ffmpeg- macOS Gatekeeper will block an unsigned download on first run. Clear the quarantine flag:
sudo xattr -dr com.apple.quarantine /usr/local/bin/ffmpegOr approve it once under System Settings → Privacy & Security.
sudo apt update && sudo apt install ffmpegFFmpeg lives in RPM Fusion, not Fedora's own repositories:
sudo dnf install https://mirrors.rpmfusion.org/free/fedora/rpmfusion-free-release-$(rpm -E %fedora).noarch.rpm
sudo dnf install ffmpeg --allowerasingsudo dnf install epel-release
sudo dnf install https://mirrors.rpmfusion.org/free/el/rpmfusion-free-release-$(rpm -E %rhel).noarch.rpm
sudo dnf install ffmpegsudo pacman -S ffmpegsudo zypper install ffmpegsudo apk add ffmpegsudo snap install ffmpegInstalls to /snap/bin/ffmpeg, which Hydra checks automatically.
FFmpeg is normally a runtime extension rather than a standalone Flatpak. Prefer your distribution's package. If you already have an FFmpeg exported at /var/lib/flatpak/exports/bin/ffmpeg, Hydra will find it.
curl -LO https://johnvansickle.com/ffmpeg/releases/ffmpeg-release-amd64-static.tar.xz
tar xf ffmpeg-release-amd64-static.tar.xz
sudo install -m755 ffmpeg-*-static/ffmpeg /usr/local/bin/ffmpegIf you installed Hydra as a Snap or Flatpak, the sandbox may prevent it from seeing an FFmpeg on the host. Install FFmpeg through the same packaging system, or use
HYDRA_FFMPEGwith a path inside the sandbox's reach.
To use a build that is not on PATH, or to pin one exact version, set HYDRA_FFMPEG to the full path of the executable — not its directory.
Linux / macOS — add to ~/.bashrc, ~/.zshrc, or ~/.config/environment.d/:
export HYDRA_FFMPEG=/opt/custom/ffmpeg-7.1/bin/ffmpegmacOS GUI launches do not read your shell profile. To make the variable visible to Hydra launched from the Dock:
launchctl setenv HYDRA_FFMPEG /opt/custom/ffmpeg-7.1/bin/ffmpegWindows (PowerShell, persistent):
[Environment]::SetEnvironmentVariable("HYDRA_FFMPEG", "C:\tools\ffmpeg\bin\ffmpeg.exe", "User")Restart Hydra after setting it.
HYDRA_FFMPEGis absolute. If it is set and the path is not a working executable, Hydra reports FFmpeg as missing rather than searchingPATH— deliberately, so a pinned build is never silently replaced by another one.
Open Options → Extensions. The FFmpeg row shows:
- 🟢 green dot + "Installed" — the detected path is shown in the row's tooltip.
- 🔴 red dot — with a button linking to this page.
Hydra records FFmpeg's status once at launch, on the banner line:
[2026-08-30 11:02:41.318] [INFO ] hydra-gui 0.3.14 | macos aarch64 | macOS 26.6.2 | 10 core(s) | ffmpeg: /opt/homebrew/bin/ffmpeg
and again per stream, so you can tell which state applied to a specific download:
[INFO ] #7 hls (hls declared): 412 segments, ~184320000 bytes, 8 connection(s), ffmpeg present
Open the log with Help → Logs.
ffmpeg -versionIf that prints a version but Hydra still says "not found", it is almost always the GUI PATH problem — see Troubleshooting.
Hydra invokes FFmpeg with a stream copy in every case. It never re-encodes, so conversions are lossless and fast.
Remux to MP4 (from MPEG-TS):
ffmpeg -y -loglevel error -i input.ts -c copy -bsf:a aac_adtstoasc -movflags +faststart output.mp4aac_adtstoasc is required because AAC inside MPEG-TS is ADTS-framed while MP4 expects it raw. Without that filter the video is fine and the audio is silence or noise — the worst kind of failure, because it looks like it worked.
Remux to MP4 (from fragmented MP4):
ffmpeg -y -loglevel error -i input.mp4 -c copy -movflags +faststart output.mp4Combine DASH video and audio:
ffmpeg -y -loglevel error -i video.mp4 -i audio.mp4 -c copy -map 0:v:0 -map 1:a:0 -movflags +faststart output.mp4If FFmpeg exits non-zero, Hydra keeps the assembled file rather than deleting your download, and reports the last line of FFmpeg's error. In the GUI this appears as a warning; the file you get is the playable assembly, not the requested container.
Your shell's PATH is richer than the one a GUI application inherits. This is the single most common cause on macOS and Linux.
Fix: install to one of the well-known locations listed above, or set HYDRA_FFMPEG (on macOS, with launchctl setenv so the Dock-launched app sees it).
Running applications do not pick up PATH changes. Fully quit Hydra — including the tray icon — and start it again. If it persists, sign out and back in.
An unsigned static build is quarantined. Clear the flag:
sudo xattr -dr com.apple.quarantine /usr/local/bin/ffmpegFFmpeg was not available at the moment the download finished. Check the per-stream log line for ffmpeg absent. Install FFmpeg, then re-download — or play the .ts file, which is valid.
Almost always an MPEG-TS source remuxed without aac_adtstoasc. Hydra applies that filter automatically; if you converted the file yourself, add it. If Hydra produced it, please open an issue with the log.
The stream keeps audio in a separate representation and FFmpeg was missing, so only the video track could be delivered. The log records dash audio unusable with the reason. Install FFmpeg and re-download.
Sandbox confinement. Install FFmpeg through the same packaging system, or use a classic (.deb/.rpm) Hydra build.
Does FFmpeg download anything? No. Hydra does all networking itself. FFmpeg only ever reads a local file that has already been downloaded and writes another local file.
Will remuxing reduce quality?
No. Every FFmpeg invocation uses -c copy, which repackages the existing compressed streams without decoding or re-encoding them.
Which FFmpeg version do I need?
Anything from the last several years. Hydra uses only long-stable flags (-c copy, -movflags, -bsf:a, -map). Version 4.0 or newer is comfortably sufficient; the current release is always a safe choice.
Do I need ffprobe too?
No. Hydra only invokes ffmpeg.
Can I use it with the CLI?
Yes — detection is identical. hydra --container mp4 <manifest-url> uses FFmpeg when available; --container ts avoids needing it for MPEG-TS sources.
Is FFmpeg bundled with Hydra? No. FFmpeg is licensed under LGPL/GPL, and builds differ in their enabled components; bundling one would constrain Hydra's own licensing and ship a codec set that may not suit you. Installing it yourself keeps that choice — and the update cadence — in your hands.
Does Hydra use FFmpeg to bypass DRM? No. Hydra refuses DRM-protected streams (Widevine, PlayReady, FairPlay, SAMPLE-AES) by name and never requests a key. FFmpeg is used only for container conversion of content that downloaded successfully.