Native library troubleshooting

Start with the error from importing @remedia/node. First determine whether FFmpeg discovery failed or the engine addon failed after the libraries loaded. The fixes are different.

Which FFmpeg did Remedia load?Copy Anchor Link

import { getFfmpegRuntime } from '@remedia/node';

const { source, directory, libraries, considered } = getFfmpegRuntime();

console.log(source); // 'explicit' | 'system' | 'managed' | 'unmanaged'
console.log(directory); // for example /home/me/.remedia/ffmpeg9/lib
for (const library of libraries) console.log(library.name, library.version, library.path);

getFfmpegRuntime() performs no search and never loads anything. The selection was made when the package was imported. considered lists every candidate that was examined, in order, with outcome (selected or rejected), a reason and a detail for rejected ones. source is unmanaged only on a platform that has no bootstrap. There the operating system's loader must find FFmpeg itself and libraries is empty.

Reading an FfmpegLoadErrorCopy Anchor Link

If no installation can be loaded, importing @remedia/node rejects with an FfmpegLoadError. Its message lists the required ABI majors, each path considered with a reason, and the installer command. The same data is available as error.candidates.

FfmpegLoadError: Remedia could not load a compatible FFmpeg 9 runtime.
Required ABI majors: libavutil 61, libswresample 7, libavcodec 63, libavformat 63, libavfilter 12.
Considered:
  - system: (see detail) -> rejected (not-found): No FFmpeg 9 libraries in 9 system library directories (...).
  - managed: /home/me/.remedia/ffmpeg9 -> rejected (not-found): The Remedia installer has not installed FFmpeg here.

Install FFmpeg 9 with the Remedia installer:
  curl -fsSL https://remedia.twlite.dev/install.sh | sh -s -- --ffmpeg-only
To use another FFmpeg 9 prefix, set REMEDIA_FFMPEG_DIR to the directory that contains lib/.

An invalid REMEDIA_FFMPEG_DIR always fails: Remedia will not quietly use another installation when you named one explicitly. Unset the variable, or point it at a valid prefix.

Native addon failures after FFmpeg loadedCopy Anchor Link

If the message says FFmpeg 9 was loaded from a directory but the Remedia native addon could not be loaded, the engine addon itself failed. Common causes:

• Cannot find native binding: the optional @remedia/node-<platform> package was not installed. Reinstall with optional dependencies enabled, and check node -p "process.platform + ' ' + process.arch" and, on Linux, glibc versus musl. Packages are provided for the targets listed in package distribution.
• A dependency on a different FFmpeg major (for example libavutil.59.dylib): the addon was built against an older FFmpeg. Use an @remedia/node release built for FFmpeg 9.
• Another module in the same process loaded a different FFmpeg first. The operating system uses one copy of a library name per process. If a native module loaded an incompatible libavcodec before Remedia, Remedia may be bound to it. Load Remedia first, or avoid combining modules that bundle FFmpeg of a different build with the same major.
• NAPI_RS_NATIVE_LIBRARY_PATH still works to load a custom engine addon. FFmpeg discovery runs before it, so that addon must link FFmpeg 9 as well.

LimitsCopy Anchor Link

• A fresh Node.js process without loader variables is exercised by the fresh-process test in the Node.js test jobs wherever the runner has an FFmpeg 9 reachable without them. The installer-managed ~/.remedia/ffmpeg9 path was verified by hand on macOS ARM64 and Linux ARM64 glibc. It has no automatic CI job, and Windows, macOS x64 and Linux x64 have not been verified that way. The bootstrap is also built for the cross-built npm targets (musl, ARMv7, Windows x86 / ARM64, Android), which remain build-only: no runtime compatibility is claimed for them.
• The one-command installer supports Linux x64 / ARM64 glibc, macOS and Windows x64. On other platforms install FFmpeg 9 yourself and use REMEDIA_FFMPEG_DIR or the loader's own directories.
• Remedia does not download or update FFmpeg when imported. Run the installer again to update ~/.remedia/ffmpeg9.

Detailed referencesCopy Anchor Link

• Native library loading