pproenca FFmpeg Build Configuration
Configure working FFmpeg compilation for any target platform.
Quick Decision: Which Build Approach?
| Scenario | Approach | Reference |
|---|---|---|
| Need binaries quickly | Pre-built from BtbN or gyan.dev | — |
| Production deployment | Docker-based build | references/docker-builds.md |
| Development/debugging | Native build on target | Platform reference |
| Cross-compiling | Docker + toolchain | references/cross-compile.md |
| Node.js native addon | Shared libs + pkg-config | references/shared-libs.md |
Build Workflow
- Determine requirements → License, codecs, platform, linking
- Install dependencies → Platform toolchain + codec libraries
- Configure FFmpeg →
./configurewith flags - Build →
make -j$(nproc) && make install - Verify →
ffmpeg -versionand-buildconf
Step 1: License Decision
Will you DISTRIBUTE the binary?
├─ NO → Any configuration including --enable-nonfree
└─ YES → Need GPL codecs (x264, x265)?
├─ YES → --enable-gpl (GPL v2+)
└─ NO → Default LGPL 2.1+
License flags:
- Default: LGPL 2.1+ (can link with proprietary code)
--enable-gpl: Enables GPL codecs (x264, x265, xvid)--enable-version3: Upgrade to (L)GPL v3 (needed for some libs)--enable-nonfree: Patent-encumbered codecs (NOT redistributable)
Step 2: Linking Decision
| Use Case | Linking | Flags |
|---|---|---|
| Standalone binary | Static | --enable-static --disable-shared |
| Native addon | Shared | --enable-shared --disable-static --enable-pic |
| Both | Both | --enable-static --enable-shared --enable-pic |
Step 3: Configure Patterns
Minimal LGPL (redistributable)
./configure \
--prefix=/usr/local \
--enable-shared \
--enable-pic \
--disable-debug \
--disable-doc
Standard GPL (common codecs)
./configure \
--prefix=/usr/local \
--enable-gpl \
--enable-shared \
--enable-pic \
--enable-libx264 \
--enable-libx265 \
--enable-libvpx \
--enable-libopus \
--enable-libvorbis \
--disable-debug \
--disable-doc
Full Build (not redistributable)
./configure \
--prefix=/usr/local \
--enable-gpl \
--enable-nonfree \
--enable-version3 \
--enable-shared \
--enable-pic \
--enable-libx264 \
--enable-libx265 \
--enable-libvpx \
--enable-libaom \
--enable-libsvtav1 \
--enable-libdav1d \
--enable-libopus \
--enable-libvorbis \
--enable-libmp3lame \
--enable-libfdk-aac \
--disable-debug \
--disable-doc
For Native Addons (Node.js/Python bindings)
./configure \
--prefix=/usr/local \
--enable-shared \
--disable-static \
--enable-pic \
--enable-gpl \
--enable-libx264 \
--enable-libx265 \
--enable-libvpx
# After install, verify:
pkg-config --libs --cflags libavcodec libavformat libavutil
Codec Quick Reference
| Codec | Flag | License | Ubuntu Package |
|---|---|---|---|
| H.264 | --enable-libx264 |
GPL | libx264-dev |
| H.265 | --enable-libx265 |
GPL | libx265-dev |
| VP8/VP9 | --enable-libvpx |
BSD | libvpx-dev |
| AV1 decode | --enable-libdav1d |
BSD | libdav1d-dev |
| AV1 encode | --enable-libaom |
BSD | libaom-dev |
| AV1 fast | --enable-libsvtav1 |
BSD | libsvtav1-dev |
| AAC HQ | --enable-libfdk-aac |
Nonfree | libfdk-aac-dev |
| MP3 | --enable-libmp3lame |
LGPL | libmp3lame-dev |
| Opus | --enable-libopus |
BSD | libopus-dev |
| Vorbis | --enable-libvorbis |
BSD | libvorbis-dev |
See references/codec-matrix.md for full codec dependency details.
Environment Variables
Essential for custom prefix builds:
export PREFIX=/usr/local
export PATH="$PREFIX/bin:$PATH"
export LD_LIBRARY_PATH="$PREFIX/lib:$LD_LIBRARY_PATH"
export PKG_CONFIG_PATH="$PREFIX/lib/pkgconfig:$PKG_CONFIG_PATH"
export CFLAGS="-I$PREFIX/include"
export LDFLAGS="-L$PREFIX/lib"
Common Errors Quick Reference
| Error | Fix |
|---|---|
ERROR: x264 not found |
export PKG_CONFIG_PATH=/usr/local/lib/pkgconfig |
libavcodec.so: cannot open |
export LD_LIBRARY_PATH=/usr/local/lib |
nasm/yasm not found |
apt install nasm |
make: *** No targets |
Check ffbuild/config.log for configure errors |
undefined reference to |
Check link order in --extra-ldflags |
See references/troubleshooting.md for detailed solutions.
Platform References
- Linux →
references/platform-linux.md - macOS →
references/platform-macos.md - Windows →
references/platform-windows.md - Cross-compile →
references/cross-compile.md - Docker builds →
references/docker-builds.md - vcpkg (Windows) →
references/vcpkg.md