mp4writer

Browser-based MP4 muxer and demuxer using WebCodecs and mp4box.js.

Encode H.264 video and Opus audio from raw VideoFrame and AudioData objects, then assemble them into a valid MP4 file — entirely in the browser with zero server-side dependencies.

Features

• Push-based encoding — feed in VideoFrames and AudioData, get back a complete MP4 buffer
• Pull-based demuxing — random-access seeking and full sequential reads from existing MP4 files

Install

npm install mp4writer

Quick start

Encoding an MP4

import { MP4PushMuxerEncoder } from "mp4writer";

const muxer = new MP4PushMuxerEncoder();
await muxer.configureEncoders(1920, 1080);

// Push audio
await muxer.processAudioBuffer(audioBuffer);

// Push video frames
for (const frame of videoFrames) {
  await muxer.pushVideoFrame(frame);
}

// Produce the final MP4
const mp4 = await muxer.multiplexToBuffer();
muxer.closeEncoders();

Demuxing an MP4

import { MP4PullDemuxer } from "mp4writer";

const demuxer = new MP4PullDemuxer(mp4Blob);
const config = await demuxer.getVideoDecoderConfig();

// Read all samples sequentially
const samples = await demuxer.readAllSamples();

// Or seek to a specific timestamp
const { samples: seekSamples, ptsIndex } = await demuxer.seek(5000);

Full decode-transform-encode example

import { MP4PullDemuxer, MP4PushMuxerEncoder, isConfigured } from "mp4writer";
import { secToUs } from "mp4writer";

const demuxer = new MP4PullDemuxer(inputBlob);
const muxer = new MP4PushMuxerEncoder();

const config = await demuxer.getVideoDecoderConfig();
await muxer.configureEncoders(config.codedWidth!, config.codedHeight!);
await muxer.processAudioBuffer(audioBuffer);

const decoder = new VideoDecoder({
  output: async (frame) => {
    // Transform the frame (draw on it, filter, etc.)
    const canvas = new OffscreenCanvas(frame.displayWidth, frame.displayHeight);
    const ctx = canvas.getContext("2d")!;
    ctx.drawImage(frame, 0, 0);
    frame.close();

    const modified = new VideoFrame(canvas, {
      timestamp: frame.timestamp,
      duration: frame.duration!,
    });
    await muxer.pushVideoFrame(modified);
  },
  error: console.error,
});

decoder.configure(config);
await isConfigured(decoder);

for (const sample of await demuxer.readAllSamples()) {
  decoder.decode(
    new EncodedVideoChunk({
      type: sample.is_sync ? "key" : "delta",
      timestamp: secToUs(sample.cts / sample.timescale),
      duration: secToUs(sample.duration / sample.timescale),
      data: sample.data,
    }),
  );
}

await decoder.flush();
const mp4 = await muxer.multiplexToBuffer();
muxer.closeEncoders();

API

MP4PushMuxerEncoder

Method	Description
configureEncoders(width, height)	Configure the H.264 video encoder and Opus audio encoder
pushVideoFrame(frame)	Encode a VideoFrame (closed automatically after encoding)
pushAudioData(data)	Encode an AudioData chunk (closed automatically after encoding)
processAudioBuffer(buffer)	Convert an AudioBuffer to AudioData and encode it
multiplexToBuffer()	Flush encoders and produce the final MP4 buffer
closeEncoders()	Release encoder resources
checkBrowserSupport()	Static — check if the browser supports the required APIs

Constructor accepts an optional MP4PushMuxerEncoderConfig:

Option	Default	Description
videoBitrate	2_000_000	Video bitrate in bits/s
videoChunkSec	~0.033 (30fps)	Duration of each video chunk in seconds
keyframeIntevalSec	2	Keyframe interval in seconds
latencyMode	"realtime"	"realtime" or "quality"
audioBitrate	64_000	Audio bitrate in bits/s
audioSampleRate	48_000	Audio sample rate in Hz
audioOutputChannels	2	Number of audio output channels

MP4PullDemuxer

Method	Description
getVideoDecoderConfig()	Get a VideoDecoderConfig for the first video track (times out after 10s)
seek(timestampMs)	Seek to a timestamp and return a decoder-ready window of samples
readAllSamples()	Read all video samples with data, in DTS order
dtsIndexToPtsIndex(dtsIndex)	Convert a DTS index to a PTS index
timestampMsToPtsIndex(timestampMs)	Find the PTS index for a given timestamp

isConfigured(codec, timeoutMs?)

Returns a Promise that resolves when a VideoEncoder, AudioEncoder, VideoDecoder, or AudioDecoder reaches the "configured" state. Times out after timeoutMs (default 10s).

Browser support

Requires the WebCodecs API with H.264 encoding support. Use MP4PushMuxerEncoder.checkBrowserSupport() to verify at runtime.

Licence

MIT — Nicholas Waltz