Emscripten Compatibility

Web releases are built and tested with the Emscripten versions listed below.

For FFmpegKitNext, each Web release is built and tested against one known-good Emscripten version. How that version is selected depends on which build path you use:

• ./nix-web.sh (recommended) pins Emscripten through the project flake, so it always uses the tested version for that release.
• ./web.sh does not pin anything. It uses whichever emcc is on PATH, so matching the version listed below is your responsibility.

Building with a different version is possible but is not covered by the tested matrix.

Releases

FFmpegKitNext	Emscripten	Target	Nix profile
9.0.0	5.0.6	wasm32-unknown-emscripten	web-wasm32-emscripten
8.1.1	5.0.6	wasm32-unknown-emscripten	web-wasm32-emscripten

Notes:

• Web/WebAssembly support was added in 8.1.1. Earlier releases do not provide Web binaries.
• The version used by ./nix-web.sh comes from the nixpkgsWeb input in flake.lock, resolved through the web-wasm32-emscripten profile. ./web.sh has no such pin.

Checking The Version In Use

The Nix profile provides the exact Emscripten version used for a release:

./nix-web.sh -p web-wasm32-emscripten
emcc --version

When building without Nix, ./web.sh uses the emcc already on PATH. Check which one that is:

emcc --version

If it does not match the version listed above, install and activate the matching one through emsdk before running ./web.sh:

./emsdk install 5.0.6
./emsdk activate 5.0.6
source ./emsdk_env.sh

Build Configuration

The following Emscripten settings are applied by the Web build scripts:

Setting	Default	Notes
pthreads	enabled	Required by the C++ ffmpeg-kit wrapper. Disable the wrapper with --disable-pthreads to build a FFmpeg core without threads.
WebAssembly SIMD	enabled	-msimd128. --enable-relaxed-simd adds -mrelaxed-simd for experimental builds.
Exceptions	Wasm EH	-fwasm-exceptions with -sWASM_LEGACY_EXCEPTIONS=0.
Linkage	dynamic	The main module loads FFmpeg side modules at runtime. --static links one main WebAssembly module.

Notes

• Using an Emscripten version other than the tested one is the most common cause of Web build failures, and it is the usual failure mode for ./web.sh builds because that script accepts whatever emcc is on PATH. Newer toolchains change undefined-symbol strictness and C++ runtime linking, which can break libraries that build cleanly on the tested version.
• Because pthreads are enabled by default, the hosting page must be cross-origin isolated. See Web Prerequisites for the required COOP/COEP response headers.
• Emscripten's EM_CACHE sysroot is rebuilt on first use when it is empty. The Nix profile seeds it from the packaged Emscripten cache.