Package distribution

The @remedia/node package contains the JavaScript loader, compiled TypeScript declarations, and optional N-API platform packages generated by @napi-rs/cli. Npm installs the platform package that matches the current operating system and CPU. The loader does not download binaries during installation or when imported.

Each platform package @remedia/node-<platform> holds two native files:

native.js and native.d.ts are generated by napi-rs and are not edited by hand. FFmpeg selection is done by maintained TypeScript in the package (lib/native-binding.ts) that runs before native.js is imported, so regenerating the napi-rs loader does not affect it. See native library troubleshooting for the full sequence.

Release-tested platformsCopy Anchor Link

The beta release pipeline includes these native packages after each target passes its native build, Rust tests, binary inspection, and Node.js integration tests:

These release jobs run with Node.js 22.18, 24, and 26. The package declares Node.js 22.18 or newer. The Node.js test jobs also run a fresh-process test that removes every FFmpeg loader variable, imports the built package, and probes and plays audio through the discovered FFmpeg.

It runs wherever a runner has an FFmpeg 9 reachable without loader variables (for example Homebrew on the macOS runners). Installing into a clean managed prefix with the FFmpeg-only installer is not an automatic CI job; .github/scripts/smoke-packed-package.mjs performs that check against packed tarballs and is run manually. The Node-API addon also has runtime tests for decoding and playback, addon loading, Discord voice components, the embedded client, and the standalone server using the built server binary.

Additional npm platform packages are included by the current release packer:

The bootstrap addon is also built for every one of these targets, but the cross-built targets have no runtime coverage, so no runtime compatibility is claimed for them. These describe workflow coverage, not confirmation that a particular release run passed. The package gate requires all 13 configured engine addons and their 13 matching bootstrap addons. Only the five native runner targets in the first table have standalone server release binaries. WASI is excluded.

FFmpeg runtime librariesCopy Anchor Link

Remedia links dynamically to FFmpeg 9. FFmpeg is not part of the npm packages: npm installs the Remedia addons but does not install FFmpeg. Install it on the machine that runs Node.js, once, with the FFmpeg-only installer:

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

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

@remedia/node then finds ~/.remedia/ffmpeg9 automatically: no LD_LIBRARY_PATH, DYLD_LIBRARY_PATH, PATH change or launcher is needed. An existing system FFmpeg 9 (a distribution package, Homebrew, or a directory on your loader paths) is preferred when present, and REMEDIA_FFMPEG_DIR overrides both. See installing FFmpeg 9 for the order. The addon expects these FFmpeg library ABI majors:

• libavcodec 63
• libavformat 63
• libavutil 61
• libavfilter 12
• libswresample 7

Embedded mode needs FFmpeg on the Node.js host. In remote mode FFmpeg is needed on the remedia-server host, not on a remote-only client.

Linux GNU and macOS releases are linked against the matching shared FFmpeg libraries. The macOS engine addon requests them as @rpath/lib<name>.<major>.dylib instead of a fixed Homebrew path so the bootstrap can choose the installation. Windows requires the matching FFmpeg 9 DLLs and a compatible Microsoft Visual C++ v14 runtime. The Opus encoder is built from bundled source and statically linked. A separate system Opus library is not required. See the FFmpeg 9 installation guide for platform-specific setup and the building from source for local build prerequisites.

Package selectionCopy Anchor Link

The generated platform packages include os and cpu restrictions. Linux GNU and musl packages also declare their matching libc value. These fields let npm select an appropriate package and prevent a GNU addon from being installed as a musl addon.

Client packageCopy Anchor Link

@remedia/client is pure TypeScript. It declares @remedia/node as an optional peer dependency for embedded playback, so applications that use only remote server nodes can install the client without the native package. During release packing, pnpm resolves this workspace peer dependency to the actual released @remedia/node version.

Plugin host packageCopy Anchor Link

@remedia/plugin-host is pure TypeScript and ships with each npm release using the same version and dist-tag as @remedia/node and @remedia/client. Release packaging builds it, verifies both the main entrypoint and the @remedia/plugin-host/node HTTP middleware entrypoint (JavaScript and declarations), and includes the shared license notices. It requires Node.js 22.18 or newer and ESM, and does not require FFmpeg or the native addon.

npm install @remedia/plugin-host

See the plugin host guide for direct dispatch and HTTP hosting examples.

Install the packagesCopy Anchor Link

npm install @remedia/node
# Remote-only consumers need only this package:
npm install @remedia/client

Both packages require Node.js 22.18.0 or newer and use ESM. See bindings and client configuration for API examples.

Runtime discovery and troubleshootingCopy Anchor Link

Importing @remedia/node selects an FFmpeg 9 installation (REMEDIA_FFMPEG_DIR, then a system installation, then ~/.remedia/ffmpeg9), verifies ABI majors and CPU architecture, loads the five libraries, and only then loads the engine addon. If that fails, the import rejects with an FfmpegLoadError that lists every path considered, the reason each was rejected, and how to install FFmpeg or choose another prefix. getFfmpegRuntime() reports the installation that was loaded. Having an ffmpeg executable on PATH alone is insufficient: Remedia loads shared libraries, never the executable.

FFMPEG_DIR and PKG_CONFIG_PATH are build settings for compiling from source, not runtime configuration. Source builds need development headers, Rust, libclang, and the tools in the contributor guide.

For Cannot find native binding, ERR_DLOPEN_FAILED, missing DLL, or missing shared-library errors, the unresolved FFmpeg dependency is explained by the diagnostic described in native library troubleshooting, including checks for architecture (node -p process.arch), Linux libc, and optional npm dependencies. ABI majors from another FFmpeg release are not substitutes. Do not rename or symlink incompatible major versions.

Licensing and distributed noticesCopy Anchor Link

FFmpeg libraries are installed independently and are not bundled with npm packages or server binaries. Their licensing depends on the build selected by the user, including enabled components and external libraries. GPL-enabled installations are not rejected. Users must comply with the applicable licensing requirements. See FFmpeg's official licensing information and source. This is distinct from libopus, which is statically included through opus2's bundled backend, and other native Rust dependencies included in binaries.

Every npm package, including platform packages, contains LICENSE and THIRD_PARTY_NOTICES.md plus the THIRD_PARTY_LICENSES.txt appendix. Standalone server releases include per-target .tar.gz archives with the executable and all three files, as well as raw executables, all 13 engine .node addons and their 13 bootstrap addons, and accompanying notices. Release assets are staged in a GitHub draft, which becomes public only after all npm packages have been published successfully. Keep the notices with redistributed binaries. See licensing and media responsibility.

Release authorizationCopy Anchor Link

See Release authorization.