codem-isoboxer

codem-isoboxer

• http://github.com/madebyhiro/codem-isoboxer

Description

Codem-isoboxer is a small browser-based MPEG-4 (ISOBMFF) parser. It is meant to be small, fast and efficient. A typical use-case would be inclusion in a new player framework (for emerging standards such as MPEG-DASH which rely on ISOBMFF for most situations) or to extract metadata from MPEG-4 files:

• Parsing emsg boxes for in-band events;
• Parsing mdat boxes for extracting subtitles;
• Validating ISOBMFF segments before playing them back;
• [etc.]

Currently a limited set of ISOBMFF boxes is supported (alphabetically):

ISO/IEC 14496-12:2012 (ISOBMFF)

• free / skip
• ftyp / styp
• mdat
• mdia
• mdhd
• moov / moof
• mvhd / mfhd
• sidx
• tfhd / tkhd
• tfdt
• traf / trak
• trun

ISO/IEC 23009-1:2014 (MPEG-DASH)

• emsg

Support for more boxes can easily be added by adding additional box parsers in src/iso_box.js. Several utility functions are included to help with reading the various ISOBMFF data types from the raw file.

Requirements

A modern web browser with support for:

• ArrayBuffer
• DataView

Usage

Include one of the files in the dist folder (regular or uglified) in your web page/application:

<script type="text/javascript" src="iso_boxer.min.js"></script>

Then, you can parse a file by calling the create function:

var parsedFile = ISOBoxer.create(arrayBuffer);

The arrayBuffer can for example be obtained by issuing an XHR request, or by using the FileReader API to read a local file.

Codem-isoboxer makes no assumptions on the validity of the given file and/or segment. It also does minimal handling of the data types and provides mostly a raw interface. Some frequently used attributes are parsed to easier-to-use types, such as the major brand and list of compatible brands in the ftyp box.

Another way to use the software is to only retrieve the boxes you are interested in. This way you don't have to traverse the box structure yourself:

var parsedFile = ISOBoxer.create(arrayBuffer);  // Parse the file
var ftyp       = parsedFile.fetch('ftyp');      // Fetch the first box with the specified type (`ftyp`)
var mdats      = parsedFile.fetchAll('mdat');   // Fetch all the boxes with the specified type (`mdat`)

Traversal of the box structure is always depth first.

NodeJS

Does it work in NodeJS? Well, it's mostly meant to be run in a web browser, but since Node supports most features it shouldn't be a problem. You can install it using NPM:

npm install codem-isoboxer

Then use it in your code (NodeJS v0.10.36 tested, 0.12.x should work as well):

var ISOBoxer = require('codem-isoboxer');
var arrayBuffer = new Uint8Array(fs.readFileSync('my_test_file.mp4')).buffer;
var parsedFile = ISOBoxer.create(arrayBuffer);

Et voila. It does not support any of the fancy stream stuff from Node.

Development

Check out the source from Github. Make changes to the files in /src. We use grunt to build the distribution files. If you add a box parser be sure to include a comment that points toward the relevant section in the specs. And if at all possible add a (small!) file to test/fixtures to provide an example.

Building

grunt

Using grunt watcher

You can use grunt-contrib-watch to watch for changes to the source and automatically build it:

grunt watch

Demo

Open test/index.html in your browser. Use the file picker to select a local MPEG-4 file to parse it. Results will be in the window.parsedFile variable. Inspect it from your browser's console. Some test files are included in test/fixtures.

License

Codem-isoboxer is released under the MIT license, see LICENSE.txt.

Changelog

codem-isoboxer 0.0.2 (2015/03/26) ##

• Added fetch and fetchAll functions to ISOFile