Building FFmpegKitNext with Custom Libraries

FFmpegKitNext includes many external libraries out of the box, but you can also build FFmpeg with a custom external library when the bundled FFmpeg source supports the matching --enable-* configure flag, or when you maintain the required FFmpeg patch yourself.

Custom libraries work through two pieces:

1. Build options that describe the custom library source and FFmpeg integration.
2. A platform build script that compiles and installs the library.

Custom Library Options

Use --enable-custom-library-[n]-... options, where [n] starts at 1. Use consecutive indexes when building more than one custom library; the scripts scan 1..20 and stop at the first missing name.

Option	Required	Description
--enable-custom-library-[n]-name=value	Yes	Library name. The source is downloaded to src/<name>, and the build script must be named <name>.sh.
--enable-custom-library-[n]-repo=value	Yes	Git repository URL.
--enable-custom-library-[n]-repo-tag=value	Tag or commit	Git tag to checkout.
--enable-custom-library-[n]-repo-commit=value	Tag or commit	Git commit to checkout.
--enable-custom-library-[n]-package-config-file-name=value	Yes	Name passed to pkg-config, usually the .pc file name without .pc.
--enable-custom-library-[n]-ffmpeg-enable-flag=value	Yes	FFmpeg configure flag without the --enable- prefix. For example, libfoo becomes --enable-libfoo.
--enable-custom-library-[n]-license-file=value	Yes	Path to the license file relative to src/<name>.
--enable-custom-library-[n]-uses-cpp	Android only	Use this when the custom Android library requires libc++.

If the custom library is GPL or makes the resulting FFmpeg build GPL, also pass --enable-gpl.

Build Script Location

Create one build script per platform family:

Target	Script path
Android	scripts/android/<name>.sh
Linux	scripts/linux/<name>.sh
iOS, macOS, tvOS, visionOS	scripts/apple/<name>.sh

The script is run once per enabled architecture. It receives the same environment used by built-in library scripts, including:

• LIB_NAME: custom library name.
• ARCH, HOST, CFLAGS, CXXFLAGS, LDFLAGS: target-specific build values.
• LIB_INSTALL_PREFIX: install prefix for this library.
• INSTALL_PKG_CONFIG_DIR: directory where the library .pc file must be copied.
• BUILD_DIR: temporary CMake build directory, useful for CMake/Meson projects.

The script must install headers under ${LIB_INSTALL_PREFIX}/include, libraries under ${LIB_INSTALL_PREFIX}/lib or ${LIB_INSTALL_PREFIX}/lib64, and a usable pkg-config file under ${INSTALL_PKG_CONFIG_DIR}. FFmpeg is later configured with:

pkg-config --cflags <package-config-file-name>
pkg-config --libs --static <package-config-file-name>
--enable-<ffmpeg-enable-flag>

Use existing scripts under scripts/android, scripts/linux and scripts/apple as templates.

Example

Nix is the recommended way to provide the host toolchain:

./nix-android.sh -p android-r27d \
  --enable-custom-library-1-name=libfoo \
  --enable-custom-library-1-repo=https://example.com/libfoo.git \
  --enable-custom-library-1-repo-tag=v1.0.0 \
  --enable-custom-library-1-package-config-file-name=libfoo \
  --enable-custom-library-1-ffmpeg-enable-flag=libfoo \
  --enable-custom-library-1-license-file=LICENSE

If you manage the Android SDK/NDK yourself, pass the same options to the direct start script:

./scripts/start-android.sh \
  --enable-custom-library-1-name=libfoo \
  --enable-custom-library-1-repo=https://example.com/libfoo.git \
  --enable-custom-library-1-repo-tag=v1.0.0 \
  --enable-custom-library-1-package-config-file-name=libfoo \
  --enable-custom-library-1-ffmpeg-enable-flag=libfoo \
  --enable-custom-library-1-license-file=LICENSE

Use the matching nix-<target>.sh wrapper or scripts/start-<target>.sh script for other platforms.

Rebuilds and Redownloads

• --redownload-<name> removes and re-clones src/<name>.
• --rebuild-<name> rebuilds the custom library even if it is already installed under prebuilt.
• --reconf-<name> sets RECONF_<name> for the build; the custom script must use that variable if it needs to regenerate Autotools files.

When a custom library definition is valid, the build prints it in the Custom libraries: summary and logs the detailed decisions to build.log.