mp4box.js

MP4Box.js

NodeJS with Grunt

JavaScript library to process MP4 files in the browser (and in NodeJS), with support for progressive parsing. Inspired by the MP4Box tool from the GPAC project. It can be used to:

On this page, you’ll find documentation on how to build MP4box.js, use it in a browser or in Node JS or contribute.

Demos

API

Getting Information

Similar to MP4Box -info file.mp4, MP4Box.js can provide general information about the file (duration, number and types of tracks …). For that, create an MP4Box ISOFile object, set the onReady callback and provide data in the form of ArrayBuffer objects. MP4Box.js supports progressive parsing. You can provide small buffers at a time, the callback will be called when the ‘moov’ box is parsed.

var MP4Box = require('mp4box'); // Or whatever import method you prefer.
var mp4boxfile = MP4Box.createFile();
mp4boxfile.onError = function(e) {};
mp4boxfile.onReady = function(info) {};
mp4boxfile.appendBuffer(data);
mp4boxfile.appendBuffer(data);
mp4boxfile.appendBuffer(data);
...
mp4boxfile.flush();

onMoovStart()

The onMoovStart callback is called when the ‘moov’ box is starting to be parsed. Depending on the download speed, it may take a while to download the whole ‘moov’ box. The end of parsing is signaled by the onReady callback.

mp4boxfile.onMoovStart = function () {
	console.log("Starting to receive File Information");
}

onReady(info)

The onReady callback is called when the the ‘moov’ box has been parsed, i.e. when the metadata about the file is parsed.

mp4boxfile.onReady = function (info) {
	console.log("Received File Information");
}

The info argument is an object with the following structure.

{
  "duration":360002,
  "timescale":600,
  "isFragmented":false,
  "isProgressive":true,
  "hasIOD":true,
  "brands":["isom"],
  "created":"2014-04-15T18:24:40.000Z",
  "modified":"2014-04-15T18:24:40.000Z",
  "tracks":[
    {
	  "id":2,
	  "created":"2012-02-13T23:07:31.000Z",
	  "modified":"2014-04-16T12:22:56.000Z",
	  "movie_duration":360000,
	  "layer":0,
	  "alternate_group":0,
	  "volume":0,
	  "track_width":320,
	  "track_height":180,
	  "timescale":25000,
	  "duration":15000000,
	  "bitrate":120000,
	  "codec":"avc1.42c00d",
	  "video":{
	    "width":320,"height":180
	  },
	  "language":"und",
	  "nb_samples":15000
	},
	{
	  "id":3,
	  "created":"2012-09-12T11:14:57.000Z",
	  "modified":"2014-04-16T12:22:56.000Z",
	  "movie_duration":360002,
	  "layer":0,
	  "alternate_group":0,
	  "volume":1,
	  "track_width":0,
	  "track_height":0,
	  "timescale":44100,
	  "duration":26460160,
	  "bitrate":60000,
	  "codec":"mp4a.40.2",
	  "audio":{
	    "sample_rate":44100,
		"channel_count":1,
		"sample_size":16
	  },
	  "language":"und",
	  "nb_samples":25840
	}
  ]
}

Track information object:

Video-specific information object:

Audio-specific information object:

onError(e)

Indicates that an error has occurred during the processing. e is a String.

mp4boxfile.onError = function (e) {
	console.log("Received Error Message "+e);
}

appendBuffer(data)

Provides an ArrayBuffer to parse from. The ArrayBuffer must have a fileStart (Number) property indicating the 0-based position of first byte of the ArrayBuffer in the original file. Returns the offset (in the original file) that is expected to be the fileStart value of the next buffer. This is particularly useful when the moov box is not at the beginning of the file.

var ab = getArrayBuffer(); // any of your own method that returns an ArrayBuffer
ab.fileStart = 0;
var nextBufferStart = mp4boxfile.appendBuffer(ab);

start()

Indicates that sample processing can start (segmentation or extraction). Sample data already received will be processed and new buffer append operation will trigger sample processing as well.

stop()

Indicates that sample processing is stopped. Buffer append operations will not trigger calls to onSamples or onSegment.

flush()

Indicates that no more data will be received and that all remaining samples should be flushed in the segmentation or extraction process.

Segmentation

var mp4boxfile = MP4Box.createFile();
mp4boxfile.onReady = function(info) {
  ...
  mp4boxfile.onSegment = function (id, user, buffer, sampleNumber, last) {}
  mp4boxfile.setSegmentOptions(info.tracks[0].id, sb, options);  
  var initSegs = mp4boxfile.initializeSegmentation();  
  mp4boxfile.start();
  ...
};

setSegmentOptions(track_id, user, options)

Indicates that the track with the given track_id should be segmented, with the given options. When segments are ready, the callback onSegment is called with the user parameter. The options argument is an object with the following properties:

mp4boxfile.setSegmentOptions(1, sb, { nbSamples: 1000 });

unsetSegmentOptions(track_id)

Indicates that the track with the given track_id should not be segmented.

mp4boxfile.unsetSegmentOptions(1);

onSegment(id, user, buffer, sampleNumber, last)

Callback called when a segment is ready, according to the options passed in setSegmentOptions. user is the caller of the segmentation, for this track, and buffer is an ArrayBuffer containing the Movie Fragments for this segment.

mp4boxfile.onSegment = function (id, user, buffer, sampleNumber, last) {
	console.log("Received segment on track "+id+" for object "+user+" with a length of "+buffer.byteLength);
}

initializeSegmentation()

Indicates that the application is ready to receive segments. Returns an array of objects containing the following properties:

[
  {
	"id":2,
	"buffer":"[ArrayBuffer]",
	"user":"[SourceBuffer]"
  },
  {
	"id":3,
	"buffer":"[ArrayBuffer]",
	"user":"[SourceBuffer]"
  }
]

Extraction

It is possible to extract the samples of a track, in a similar manner to the segmentation process.

var mp4boxfile = MP4Box.createFile();
mp4boxfile.onReady = function(info) {
  ...
  /* create a texttrack */
  var texttrack = v.addTextTrack("metadata", "Text track for extraction of track "+info.tracks[0].id);
  mp4boxfile.onSamples = function (id, user, samples) {}
  mp4boxfile.setExtractionOptions(info.tracks[0].id, texttrack, options);  
  mp4boxfile.start();
  ...
};

setExtractionOptions(track_id, user, options)

Indicates that the track with the given track_id for which samples should be extracted, with the given options. When samples are ready, the callback onSamples is called with the user parameter. The options argument is an object with the following properties:

mp4boxfile.setExtractionOptions(1, texttrack, { nbSamples: 1000 });

unsetExtractionOptions(track_id)

Indicates that the samples for the track with the given track_id should not be extracted.

mp4boxfile.unsetExtractionOptions(1);

onSamples(id, user, samples)

Callback called when a set of samples is ready, according to the options passed in setExtractionOptions. user is the caller of the segmentation, for this track, and samples is an Array of samples.

mp4boxfile.onSamples = function (id, user, samples) {
	console.log("Received "+samples.length+" samples on track "+id+" for object "+user);
}

Each sample has the following structure:

{
	"track_id":4,
	"description": "[Box]",
	"is_rap":true,
	"timescale":1000,
	"dts":0,
	"cts":0,
	"duration":1000,
	"size":41,
	"data": "[ArrayBuffer]"
}

seek(time, useRap)

Indicates that the next samples to process (for extraction or segmentation) start at the given time (Number, in seconds) or at the time of the previous Random Access Point (if useRap is true, default is false). Returns the offset in the file of the next bytes to be provided via appendBuffer .

mp4boxfile.seek(10, true);

releaseUsedSamples(id, sampleNumber)

Releases the memory allocated for sample data for the given track id, up to (but excluding) the given sample number.

mp4boxfile.releaseUsedSamples(1, 250);

Build

MP4Box.js implements many features (parsing of many types of boxes, writing of boxes, sample processing, on-the-fly fragmentation …). All these features may not be needed in all applications. In order to allow for a flexible configuration of the features, and to reduce the size of the final library, MP4Box.js is split in many files and uses the Grunt system to compile a set of selected features into a single file. Currently, MP4Box.js comes in two flavors:

Grunt builds the versions of the single-file library in the dist folder, minified (mp4box.all.min.js,mp4box.simple.min.js) or not (mp4box.all.js,mp4box.simple.js).

Dependencies

In this all version, this code uses DataStream.js, with some modifications for Uint24 and Uint64 types. In the simple version, there are no external dependencies.

Browser Usage

In order to use the MP4Box.js in a browser, use grunt to build a single-file library (see above) or use a pre-built version from the demo page.

<html>
<head>
  <meta charset="utf-8">
  <title>MP4Box.js in the browser</title>
  <script src="mp4box.all.min.js"></script>
</head>
<body>
...
</body>
</html>

Node Usage

MP4Box.js can be used in Node.js. See for example the info.js example.

Contribute

If your favorite box is not parsed by MP4Box, you can easily contribute. Each box parsing code is stored in a separate file whose name is the 4CC of the box type. For instance, the parsing of the ctts box is located in ctts.js.

To contribute to MP4Box.js, simply clone the repository, run npm install and grunt test.

This site is open source. Improve this page.