MP4Box.js

Common errors

• ReferenceError: require is not defined

  cause 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

  cause 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

  cause 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.

Warnings

• breaking Version 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.
• gotcha The 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`.
• gotcha When 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.

Install

• npm install mp4box npm
• yarn add mp4box yarn
• pnpm add mp4box pnpm

Imports

• MP4Box (default export)
  wrong:

  import { MP4Box } from 'mp4box';

  correct:

  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
  wrong:

  import { createFile } from 'mp4box';

  correct:

  const mp4boxfile = MP4Box.createFile();

  `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.

Quickstart

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();