Installation

​

Requirements

• Node.js 18 or higher (or Bun 1.0+)
• On linux-x64, linux-arm64, and macOS arm64: nothing else. npm install node-webcodecs works with zero system dependencies.
• Elsewhere: FFmpeg libraries (libavcodec, libavutil, libswscale, libswresample), plus pkg-config and a C++ compiler when building from source

1. Dynamic prebuild — links your system FFmpeg (all its codecs, including GPL ones like x264/x265). Requires matching FFmpeg runtime libraries: 6.x on Linux (e.g. Ubuntu 24.04), current Homebrew FFmpeg on macOS.
2. Static prebuild — bundled LGPL-only FFmpeg, shipped as a platform-specific @node-webcodecs/static-* optional dependency (~15 MB). Works in any Docker image, Lambda, or Fly with no FFmpeg installed. H.264 encode via openh264, AV1 encode via SVT-AV1, AV1 decode via dav1d; software HEVC encode is unavailable (hardware HEVC still works).
3. Source build — compiles against your FFmpeg dev headers via cmake-js.

​

Platform-Specific Setup

brew install ffmpeg pkg-config

export PATH="/opt/homebrew/bin:$PATH"

echo 'export PATH="/opt/homebrew/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

echo 'export PATH="/usr/local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

npm install node-webcodecs

sudo apt-get update
sudo apt-get install build-essential pkg-config \
  libavcodec-dev libavutil-dev libswscale-dev libswresample-dev

npm install node-webcodecs

# For FFmpeg 6.x
sudo apt-get install ffmpeg=7:6.* libavcodec-dev=7:6.*

# Check installed version
ffmpeg -version

sudo add-apt-repository ppa:savoury1/ffmpeg4
sudo apt-get update
sudo apt-get install ffmpeg libavcodec-dev

vcpkg install ffmpeg:x64-windows

choco install pkgconfiglite

npm install node-webcodecs

FROM node:22-slim

WORKDIR /app
COPY package*.json ./
RUN npm install
COPY . .

CMD ["node", "index.js"]

FROM ubuntu:24.04
RUN apt-get update && apt-get install -y nodejs npm \
    libavcodec60 libavutil58 libswscale7 libswresample4 \
    && rm -rf /var/lib/apt/lists/*

docker build -t my-video-app .
docker run my-video-app

​

Verification

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

npm rebuild node-webcodecs

export DYLD_LIBRARY_PATH="/opt/homebrew/lib:$DYLD_LIBRARY_PATH"

export LD_LIBRARY_PATH="/usr/local/lib:$LD_LIBRARY_PATH"

brew install pkg-config

sudo apt-get install pkg-config

choco install pkgconfiglite

​

Runtime Support

​

Next Steps

​

Sources

• Mintlify Quickstart
• Setting up a Documentation Site with Mintlify
• A Step-by-Step Guide to Creating a Beautiful Documentation Site with Mintlify