node-webcodecs

WebCodecs API for Node.js — encode and decode video/audio with browser-compatible APIs, powered by FFmpeg.

Why node-webcodecs?

Feature	node-webcodecs	Browser WebCodecs
Video Codecs	H.264, H.265, VP8, VP9, AV1	Varies by browser
Audio Codecs	AAC, Opus, MP3, FLAC	Varies by browser
Container Muxing	MP4	Not in spec
Demuxing	Any FFmpeg format	Not in spec
Server-side	Yes	Browser only

Installation

npm install @pproenca/node-webcodecs

Prebuilt binaries with FFmpeg statically linked are included for:

• macOS ARM64 (Apple Silicon)
• macOS x64 (Intel)
• Linux x64 (musl, fully static)

Building from Source

For other platforms or to force a source build:

npm install @pproenca/node-webcodecs --build-from-source

This requires FFmpeg 5.0+ development libraries:

macOS:

brew install ffmpeg pkg-config

Ubuntu/Debian:

sudo apt-get install libavcodec-dev libavformat-dev libavutil-dev \
  libswscale-dev libswresample-dev libavfilter-dev pkg-config

Fedora/RHEL:

sudo dnf install ffmpeg-devel pkg-config

Quick Start

Encode

import { VideoEncoder, VideoFrame } from "@pproenca/node-webcodecs";

const encoder = new VideoEncoder({
  output: (chunk) => chunks.push(chunk),
  error: console.error,
});

encoder.configure({
  codec: "avc1.42001e",
  width: 1920,
  height: 1080,
  bitrate: 5_000_000,
});

const frame = new VideoFrame(rgbaBuffer, {
  format: "RGBA",
  codedWidth: 1920,
  codedHeight: 1080,
  timestamp: 0,
});

encoder.encode(frame);
frame.close();
await encoder.flush();

Decode

import { VideoDecoder, EncodedVideoChunk } from "@pproenca/node-webcodecs";

const decoder = new VideoDecoder({
  output: (frame) => {
    // Process frame...
    frame.close();
  },
  error: console.error,
});

decoder.configure({
  codec: "avc1.42001e",
  codedWidth: 1920,
  codedHeight: 1080,
});

decoder.decode(new EncodedVideoChunk({ type: "key", timestamp: 0, data }));
await decoder.flush();

Mux to MP4

import { Muxer } from "@pproenca/node-webcodecs";

const muxer = new Muxer({ filename: "output.mp4" });

muxer.addVideoTrack({
  codec: "avc1.42001e",
  width: 1920,
  height: 1080,
  description: codecDescription,
});

muxer.writeVideoChunk(chunk);
muxer.finalize();

Demux

import { Demuxer } from "@pproenca/node-webcodecs";

const demuxer = new Demuxer({
  onTrack: (track) => console.log(track.codec),
  onChunk: (chunk, trackIndex) => decoder.decode(chunk),
  onError: console.error,
});

demuxer.open("input.mp4");
demuxer.demux();
demuxer.close();

See examples/ for complete working code.

API

This library implements the W3C WebCodecs specification.

Class	Description
VideoEncoder / VideoDecoder	Compress / decompress video
AudioEncoder / AudioDecoder	Compress / decompress audio
VideoFrame / AudioData	Raw media containers
EncodedVideoChunk / EncodedAudioChunk	Compressed media packets
ImageDecoder	Decode JPEG, PNG, WebP, GIF
Muxer / Demuxer	Container I/O (beyond W3C spec)

Video codecs: H.264, H.265, VP8, VP9, AV1 Audio codecs: AAC, Opus, MP3 (decode), FLAC (decode)

See docs/codecs.md for codec strings and pixel formats.

See docs/best-practices.md for resource management, error handling, and queue management guidance.

Contributing

See CONTRIBUTING.md.

License

MIT