Skip to content

Home

Jump to bottom
Mattias Carlsson edited this page Sep 3, 2026 · 4 revisions

mediaforge

A POSIX shell build system that compiles FFmpeg from source, together with ~110 modular dependency recipes, into an isolated prefix. Nothing outside the checkout is touched until you explicitly install.

This wiki carries the explanatory material: worked sequences, the reasoning behind a default, and the things that are true about a build but do not fit in a flag description.

The authoritative reference is the copy in your own checkout, not this wiki. Nothing here defines a flag, a default, a host requirement, or an install step — those are only correct relative to a commit, so they live where commits are:

Those links show the tip of develop. If you are on a tagged release, read the files in your checkout instead — Documentation/usage.md beside the mediaforge.sh that will actually parse your flags. The whole reason the reference is in-tree is that it is version-matched, and a link to a moving branch gives that away.

That split is deliberate, and it is not a preference. A wiki is a separate repository: it is not tagged with a release, it is not present when you clone, no pull request reviews an edit to it, and no gate can read it offline. Two of this project's tests grep the in-tree docs on every push — one asserts that every flag the parser accepts is documented, the other that a specific behavioural default is stated — so the reference is checked, and a copy here would not be. It is also the shape upstream uses: FFmpeg keeps its option reference in-tree and regenerated, and puts its encode guides on a separate wiki.

So this wiki may grow freely, and it never becomes the place a flag is defined. Pages here link to usage.md rather than restating it.

Pages

  • Worked examples — start here. Goal-shaped sequences: a first build, the codecs most people want, a debuggable build, a portable static binary, pinning to an FFmpeg release, retrying one failed package.
  • Choosing implementations — the six mutex groups, the six-rung precedence ladder, where your choices get stored, and the one exception that jumps the ladder.
  • Debug builds and split DWARF — what --debug actually produces, why the installed prefix is no longer self-contained, and the quiet way to lose your debug information.
  • Troubleshooting a failed build — read the log that is still on disk, retry one recipe, and the failures that do not look like failures: a skipped outdated recipe, a mixed-level refusal, and a debugger that stops resolving source while the binary keeps running.

Quick start

git clone https://github.com/crippledgeek/mediaforge.git
cd mediaforge
./mediaforge.sh build          # free codecs only, into ./workspace
./mediaforge.sh install        # interactive prefix menu

Prefer an isolated prefix such as ~/.local/mediaforge, and do not wrap install in sudo for a prefix you own — the installer elevates itself only when the destination needs it. See Worked examples for why that matters.

Clone this wiki locally