Skip to main content

​
Requirements

  • Node.js 18 or higher (or Bun 1.0+)
  • FFmpeg libraries (libavcodec, libavutil, libswscale, libswresample)
  • pkg-config (for finding FFmpeg during build)
  • C++ compiler (Xcode Command Line Tools on macOS, build-essential on Linux)

​
Platform-Specific Setup

​
macOS Installation

Install FFmpeg and pkg-config via Homebrew:
brew install ffmpeg pkg-config
Ensure Homebrew is in your PATH (add to ~/.zshrc or ~/.bashrc):
export PATH="/opt/homebrew/bin:$PATH"
On Apple Silicon Macs, Homebrew installs to /opt/homebrew by default. Make sure this is in your PATH:
echo 'export PATH="/opt/homebrew/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
On Intel Macs, Homebrew installs to /usr/local. Ensure /usr/local/bin is in your PATH:
echo 'export PATH="/usr/local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

​
Install node-webcodecs

npm install node-webcodecs
First build may take 2-3 minutes as native bindings compile against your FFmpeg installation.

​
Verification

Verify your installation works: 
const { VideoEncoder, getFFmpegVersion } = require('node-webcodecs');

// Check FFmpeg version
const version = getFFmpegVersion();
console.log('FFmpeg version:', version);
// Output: { avcodec: '60.31.102', avcodecVersion: '60.31.102' }

// Check codec availability
const { hasCodec } = require('node-webcodecs');
console.log('H.264 encoder:', hasCodec('h264', 'encoder'));
console.log('VP9 decoder:', hasCodec('vp9', 'decoder'));

​
Troubleshooting

The native module failed to compile. Check that:
  1. FFmpeg libraries are installed (brew list ffmpeg or dpkg -l | grep libavcodec)
  2. pkg-config can find FFmpeg (pkg-config --modversion libavcodec)
  3. You have a C++ compiler installed
Try rebuilding:
npm rebuild node-webcodecs
FFmpeg libraries aren’t in your dynamic library path.macOS:
export DYLD_LIBRARY_PATH="/opt/homebrew/lib:$DYLD_LIBRARY_PATH"
Linux:
export LD_LIBRARY_PATH="/usr/local/lib:$LD_LIBRARY_PATH"
Add to your shell profile (.zshrc, .bashrc) to make permanent.
Install pkg-config:macOS:
brew install pkg-config
Ubuntu/Debian:
sudo apt-get install pkg-config
Windows:
choco install pkgconfiglite
If the native compilation is failing or taking too long:
  1. Check you have enough RAM (compilation needs ~2GB)
  2. Try cleaning node_modules: 
    rm -rf node_modules package-lock.json
npm install
  3. Check compiler version (GCC 7+ or Clang 5+ recommended)
v1.0.0+ includes prebuilt binaries for:
  • macOS (arm64, x64)
  • Linux (x64)
These are automatically used if your platform matches. You still need FFmpeg libraries installed at runtime.

​
Runtime Support

Node.js 18+

Full support for Node.js 18.x, 20.x, 22.x

Bun 1.0+

Full compatibility via N-API

​
Next Steps

Quick Start Tutorial

Get your first video encoding in 5 minutes

​
Sources