README.md

mp3 Parser

Build Status NPM version Bower version

Locate and read mp3 sections: Individual mp3 frames as well as ID3v2 and Xing/Lame tags. For each of these sections present within a given mp3 file, mp3 Parser will provide data indicating their presence, their boundaries within the file, as well as any available informative data. In the current implementation, the latter is strictly true only for frames as thorough parsing and data-extraction from ID3v2 and Xing/Lame tags is work in progress. The primary use case (and raison d'etre) for this initial revision is performing precise cuts at frame / tag boundaries.

Set up

To use mp3 Parser

  • install with bower, bower install mp3-parser or
  • install with npm, npm install mp3-parser or
  • just include the relevant files (see below), in case you're targeting a browser and don't want to go over npm or bower.

mp3 Parser may be used as a CommonJS module on Node or in a browser, either as an AMD module or through plain <script> tags. It's automatically exported in the appropriate format depending on the current environment:

  • When working with CommonJS (e.g. Node), assuming mp3 Parser is npm installed:

      var mp3Parser = require("mp3-parser");
      var mp3Tags = mp3Parser.readTags(someMp3DataView);
    
  • When working with an AMD loader (e.g. requireJS):

      // Your module
      define(["path/to/mp3-parser/main"], function (mp3Parser) {
          var mp3Tags = mp3Parser.readTags(someMp3DataView);
      });
    

    In the example above, it is assumed that mp3-parser source files live in path/to/mp3-parser (relative to the root path used for module lookups). When using requireJS you may prefer to treat mp3-parser as a package:

      // Configure requireJS for the mp3-parser package ..
      require.config({
          packages: [{
              name: "mp3-parser",
              location: "path/to/mp3-parser"
          }]
      })
    
      // .. and refer to mp3-parser module by its given package name
      define(["mp3-parser"], function (mp3Parser) {
          var mp3Tags = mp3Parser.readTags(someMp3DataView);
      });
    
  • Setting up mp3 Parser in projects targetting browsers, without an AMD module loader, is unfortunately quite verbose as a number of files need to be included (in specific order). This should be mitigated in the future, but for now you would need:

      ...
      <script type="text/javascript" src="path/to/mp3-parser/lib/lib.js"></script>
      <script type="text/javascript" src="path/to/mp3-parser/lib/xing.js"></script>
      <script type="text/javascript" src="path/to/mp3-parser/lib/id3v2.js"></script>
      <script type="text/javascript" src="path/to/mp3-parser/main.js"></script>
      ...
    

    which would export the mp3Parser global:

      var mp3Tags = mp3Parser.readTags(someMp3DataView);
    

Usage

The parser exposes a collection of read____ methods, each dedicated to reading a specific section of the mp3 file. The current implementation includes readFrameHeader, readFrame, readId3v2Tag and readXingTag. Each of these accepts a DataView-wrapped ArrayBuffer, which should contain the actual mp3 data, and optionally an offset into the buffer.

All methods return a description of the section read in the form of a hash containing key-value pairs relevant to the section. For example the hash returned by readFrameHeader always contains an mpegAudioVersion key of value "MPEG Version 1 (ISO/IEC 11172-3)" and a layerDescription key of value "Layer III". A description will always have a _section hash with type, byteLength and offset keys:

  • type: "frame", "frameHeader", "Xing" or "ID3v2"
  • byteLenfth: Size of the section in bytes
  • offset: Buffer offset at which this section resides

Further documentation is forthcoming. You can also

License

Licensed and freely distributed under the MIT License (LICENSE.txt).

Copyright (c) 2013-2014 Alex Lambiris