mp4box

library2.3.0jsnpmunverified

MP4Box.js is a robust JavaScript library designed for comprehensive processing of MP4 files, including parsing, segmentation, and sample extraction. It enables advanced functionalities directly within web browsers or Node.js environments, making it a critical tool for working with the Media Source Extensions (MSE) API for adaptive streaming. The current stable version is 2.3.0, with a history of frequent minor and patch releases, indicating active development and maintenance. Key differentiators include its progressive parsing capabilities, cross-platform support, and its direct inspiration from the well-established GPAC MP4Box tool, providing a powerful and familiar API for developers handling MP4 media.

serialization web-framework

npm install mp4box

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · MP4BOX

mp4box

serializationjavascriptv2.3.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

MP4Box (default export)

✓ import MP4Box from 'mp4box';

✗ import { MP4Box } from 'mp4box';

The library exports a default object/namespace which contains the `createFile` factory and other utilities. The `require('mp4box')` syntax in the README is for CommonJS environments; use `import MP4Box from 'mp4box'` for modern ESM.

createFile

✓ const mp4boxfile = MP4Box.createFile();

✗ import { createFile } from 'mp4box';

`createFile` is a method of the default `MP4Box` export, not a direct named export from the module. It acts as a factory to create an `MP4File` instance.

TypeScript Types (MP4File, MP4Info)

✓ import type { MP4File, MP4Info, MP4Track } from 'mp4box';

For TypeScript projects, explicitly import types like `MP4File` (the interface for the object returned by `createFile()`), `MP4Info` (the structure passed to `onReady`), or `MP4Track` using `import type` for better clarity and bundler optimization.

This quickstart demonstrates how to progressively parse an MP4 file by fetching data chunks and appending them to an `MP4File` instance. It sets up `onMoovStart` and `onReady` callbacks to log file metadata as it becomes available. The example fetches a small MP4 from GitHub to simulate real-world usage.

import MP4Box from 'mp4box'; const mp4boxfile = MP4Box.createFile(); mp4boxfile.onError = function(e) { console.error('MP4Box error:', e); }; mp4boxfile.onMoovStart = function () { console.log('Starting to receive File Information (moov box)'); }; mp4boxfile.onReady = function(info) { console.log('Received File Information:', info); // Example: Log track details info.tracks.forEach(track => { console.log(`Track ID: ${track.id}, Type: ${track.movie_type}, Codec: ${track.codec}, Duration: ${track.duration/track.timescale}s`); }); }; // Simulate appending data (e.g., from a fetched MP4 file) async function loadMp4Data() { // In a real scenario, 'url' would be the path to your MP4 file const url = 'https://raw.githubusercontent.com/gpac/mp4box.js/master/test/initial-media/mp4/frag_raw.mp4'; const response = await fetch(url); const reader = response.body.getReader(); let offset = 0; while (true) { const { done, value } = await reader.read(); if (done) { mp4boxfile.flush(); // Signal end of file break; } const buffer = value.buffer; // value is a Uint8Array, get its underlying ArrayBuffer buffer.fileStart = offset; // Important for MP4Box to track byte ranges mp4boxfile.appendBuffer(buffer); offset += buffer.byteLength; } } loadMp4Data();

Debug

Known issues

breakingVersion 2.0.0 introduced significant internal changes, including the replacement of `MP4BoxStream` with `DataStream`. This impacts custom implementations that might have directly interacted with the stream abstraction.

fix

Review your code for direct dependencies on `MP4BoxStream`. Adapt to use `DataStream` or other new APIs as per the v2.0.0 release notes and updated documentation. Most users interacting via `appendBuffer` should not be directly affected, but custom extensions might need updates.

affects: >=2.0.0

gotchaThe library's examples and default export behavior (especially with `require('mp4box')`) can be confusing for modern JavaScript projects. While it provides CommonJS compatibility, the preferred and most robust way to use `mp4box.js` in current Node.js and browser environments is via ESM `import` statements.

fix

Always use `import MP4Box from 'mp4box';` for ESM-enabled projects. Avoid `require()` in environments where ESM is the default or preferred module system to prevent errors like `ReferenceError: require is not defined`.

affects: >=1.0.0

gotchaWhen appending data using `mp4boxfile.appendBuffer(buffer)`, it is crucial to set the `fileStart` property on the `ArrayBuffer` or `TypedArray` you provide. This property, indicating the byte offset of the buffer within the original file, is essential for `MP4Box.js` to correctly parse box offsets and structure.

fix

Ensure that `buffer.fileStart = currentOffset;` is set before calling `appendBuffer()`. If omitted, parsing errors or incorrect metadata extraction will occur, especially with fragmented or progressively loaded files.

affects: >=1.0.0

Errors

Common errors & fixes

ReferenceError: require is not defined

Attempting to use `require('mp4box')` in an ECMAScript Module (ESM) context (e.g., in a `.mjs` file or a Node.js project with `"type": "module"` in package.json).

fix

Change your import statement to `import MP4Box from 'mp4box';`.

TypeError: MP4Box.createFile is not a function

Incorrectly importing the `MP4Box` object using named imports (e.g., `import { MP4Box } from 'mp4box';`) when it is exported as a default.

fix

Use the correct default import: `import MP4Box from 'mp4box';`.

Cannot read properties of undefined (reading 'fileStart') or similar parsing errors after appendBuffer

The `ArrayBuffer` passed to `appendBuffer` is missing the `fileStart` property, which indicates the byte offset of the buffer's data within the original file.

fix

Before calling `mp4boxfile.appendBuffer(buffer);`, ensure you set `buffer.fileStart = currentByteOffset;` where `currentByteOffset` is the starting position of that buffer's data in the complete file.

Upgrade

Version history

2.3.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/gpac/mp4box.js ↗

packagehttps://www.npmjs.com/package/mp4box ↗

homepagehttps://gpac.github.io/mp4box.js/ ↗