Install FFmpeg 9

Remedia's native engine decodes audio with FFmpeg 9 shared libraries (9.0.2). It links them at runtime and does not bundle them, so FFmpeg 9 must be installed on the machine that runs the engine.

Recommended: the Remedia installerCopy Anchor Link

The installer provisions FFmpeg 9.0.2 and its shared dependencies. Run the one for your platform:

Linux and macOS

curl -fsSL https://remedia.twlite.dev/install.sh | sh -s -- --ffmpeg-only

Windows PowerShell

& ([scriptblock]::Create((irm https://remedia.twlite.dev/install.ps1))) -FFmpegOnly

• FFmpeg is installed to ~/.remedia/ffmpeg9 ($HOME\.remedia\ffmpeg9 on Windows), outside your system library directories. Your system FFmpeg is not replaced.
• @remedia/node finds that directory automatically. You do not need to set PATH, LD_LIBRARY_PATH, or any other variable.
• --ffmpeg-only / -FFmpegOnly installs only FFmpeg. It does not install remedia-server, does not add commands, and does not edit your shell profile or PATH. You can run it again to update or re-verify FFmpeg.
• The installer downloads FFmpeg from conda-forge, so it needs network access. Set REMEDIA_INSTALL_DIR to install under a different prefix. For an embedded engine using that custom prefix, set REMEDIA_FFMPEG_DIR to its ffmpeg9 directory.

Supported installer platforms: Linux x64 and ARM64 (glibc), macOS Intel and Apple Silicon, and Windows x64.

Where FFmpeg is neededCopy Anchor Link

If you are installing the full Remedia server, follow Install the server instead: its default mode installs FFmpeg and the server together.

Verify the installationCopy Anchor Link

Run this from the directory of your project, after installing @remedia/node:

node --input-type=module -e "import { Remedia } from '@remedia/node'; const engine = await Remedia.create(); await engine.close(); console.log('Remedia native runtime OK')"

It prints Remedia native runtime OK when the native addon loads and initializes. It does not test decoding or Discord voice. To see which FFmpeg installation was loaded:

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

const runtime = getFfmpegRuntime();
console.log(runtime.source, runtime.directory);

For a server, run remedia-server doctor on the audio host. If loading fails, the error lists every location that was tried and why each was rejected. See native library troubleshooting.

Manual installationCopy Anchor Link

Use these only if you do not want the installer. After installing, run the verification above.

macOSCopy Anchor Link

Install Homebrew's shared FFmpeg package, then verify its library ABI majors against the required versions:

brew install ffmpeg

@remedia/node finds Homebrew's installation under /opt/homebrew (Apple Silicon) or /usr/local (Intel) automatically. Your Node.js architecture and FFmpeg architecture must match. As an alternative, micromamba can install a pinned build:

micromamba create -n remedia-ffmpeg9 -c conda-forge 'ffmpeg=9.0.2'
micromamba activate remedia-ffmpeg9
export REMEDIA_FFMPEG_DIR="$CONDA_PREFIX"

WindowsCopy Anchor Link

Install a shared FFmpeg build. Static builds do not provide the DLLs Remedia loads.

• Scoop: install the shared build and verify that it provides the required FFmpeg 9 DLLs. Scoop adds its bin directory to PATH, which Remedia searches:

  Copy Text

  scoop install ffmpeg-shared

• Winget: install Gyan.FFmpeg.Shared, then locate its shared-library directory. A command alias for ffmpeg.exe alone does not expose the DLLs to Remedia:

  Copy Text

  winget install Gyan.FFmpeg.Shared
  Get-ChildItem "$env:LOCALAPPDATA\Microsoft\WinGet\Packages" -Filter avcodec-63.dll -Recurse
  # Set this to the containing directory printed above:
  $env:REMEDIA_FFMPEG_DIR = 'C:\path\to\shared-ffmpeg\bin'

  The package folder name can differ on your machine. Locate the directory containing avcodec-63.dll and use that path.

• Manual download: the "full_build-shared" archive from gyan.dev. Extract it and set REMEDIA_FFMPEG_DIR to its bin folder, or add that folder to PATH.

• micromamba:

  Copy Text

  micromamba create -n remedia-ffmpeg9 -c conda-forge ffmpeg=9.0.2
  micromamba activate remedia-ffmpeg9
  $env:REMEDIA_FFMPEG_DIR = $env:CONDA_PREFIX

You may also need the matching Microsoft Visual C++ Redistributable.

LinuxCopy Anchor Link

The installer supports glibc Linux. Distribution FFmpeg packages may target another ABI major. Verify the shared-library versions before choosing a system package. For a pinned FFmpeg 9 environment, use micromamba:

micromamba create -n remedia-ffmpeg9 -c conda-forge 'ffmpeg=9.0.2'
micromamba activate remedia-ffmpeg9
export REMEDIA_FFMPEG_DIR="$CONDA_PREFIX"

If your platform has no FFmpeg 9 package, build FFmpeg 9.0.2 from source with shared libraries (./configure --enable-shared), and make sure the libraries, headers and runtime loader paths all describe the same build.

AdvancedCopy Anchor Link

How @remedia/node chooses an installationCopy Anchor Link

Importing @remedia/node selects FFmpeg before the engine loads. Nothing is downloaded and no environment variable is changed. The first usable installation in this order wins:

1. REMEDIA_FFMPEG_DIR, when set. It names an installation prefix (for example ~/.remedia/ffmpeg9) or its library directory (lib on Linux and macOS, Library\bin or bin on Windows). If it cannot be loaded, the import fails and no other installation is tried.
2. A system installation: the directories your platform's loader searches, including LD_LIBRARY_PATH and standard library directories on Linux, DYLD_* paths and Homebrew's prefixes on macOS, and the Node.js directory plus PATH on Windows. The current directory is never searched.
3. The installer-managed prefix ~/.remedia/ffmpeg9.
4. Otherwise an FfmpegLoadError listing every path considered.

An installation is accepted only if all five libraries are present at the right versions, match the process architecture, resolve their own dependencies, and live in the same directory.

Required library versionsCopy Anchor Link

Older or newer majors cannot be substituted by renaming files or creating symlinks. To check a pkg-config installation, pkg-config --modversion libavcodec libavformat libavutil libavfilter libswresample should report majors 63, 63, 61, 12 and 7.

The standalone server runtimeCopy Anchor Link

The installed remedia and remedia-server launchers configure library paths, then invoke the lightweight CLI. The CLI starts remedia-server-runtime for serving and diagnostics. If you provide FFmpeg yourself (installer option --no-ffmpeg / -NoFFmpeg), the runtime relies on the system loader, so make the FFmpeg directory visible to the process: LD_LIBRARY_PATH on Linux, DYLD_LIBRARY_PATH on macOS, or PATH on Windows. Run remedia-server doctor to confirm.

Building Remedia from sourceCopy Anchor Link

Compiling Remedia (not running a published addon) needs FFmpeg 9 headers and pkg-config metadata. Set FFMPEG_DIR to the FFmpeg prefix and PKG_CONFIG_PATH to its lib/pkgconfig directory so the build links FFmpeg 9 and not another version on your machine. These variables only affect builds. They are not read when a published package runs. See CONTRIBUTING.md and verify-native-deps.mjs.

Other targetsCopy Anchor Link

FreeBSD x64 is tested against a pinned FFmpeg 9.0.2 source build. Linux musl, ARMv7 and Android targets are cross-compiled in CI but are build-only. They carry no runtime compatibility guarantee. See package distribution for platform coverage.

Inspecting a native addonCopy Anchor Link

Use ldd (Linux, FreeBSD), otool -L (macOS) or dumpbin /DEPENDENTS (Windows) to see which FFmpeg libraries an addon requests. On macOS, the published addon requests @rpath/libavcodec.63.dylib and so on, which lets @remedia/node choose among Homebrew, the managed prefix and REMEDIA_FFMPEG_DIR. A custom build whose libraries carry absolute install names elsewhere cannot be selected. Licensing implications of redistributing FFmpeg are in licensing.