项目作者: biril

项目描述 :
Read MPEG audio frames & tags
高级语言: JavaScript
项目地址: git://github.com/biril/mp3-parser.git
创建时间: 2013-07-08T21:55:24Z
项目社区:https://github.com/biril/mp3-parser

开源协议:MIT License

下载


mp3 Parser

Build Status
NPM version
Bower version

Locate and read MPEG audio file sections: Individual frames as well as ID3v2 and Xing/Lame tags. For
any of these found within a given buffer, mp3 Parser will provide data indicating their presence,
their position within the buffer, as well as relevant informative data (with varying degrees of
detail).

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:

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

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

    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:

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

    1. ...
    2. <script type="text/javascript" src="path/to/mp3-parser/lib/lib.js"></script>
    3. <script type="text/javascript" src="path/to/mp3-parser/lib/xing.js"></script>
    4. <script type="text/javascript" src="path/to/mp3-parser/lib/id3v2.js"></script>
    5. <script type="text/javascript" src="path/to/mp3-parser/main.js"></script>
    6. ...

    which would export the mp3Parser global:

    1. var mp3Tags = mp3Parser.readTags(someMp3DataView);

Usage

The parser’s API consists of read____ methods, each dedicated to reading a specific section
of the MPEG audio file. The current implementation includes readFrameHeader, readFrame,
readLastFrame, readId3v2Tag, readXingTag and readTags. Each of these accepts a
DataView-wrapped ArrayBuffer
containing the audio data, and optionally an offset into the buffer.

In all cases, a ‘description’ will be returned - a hash containing key-value pairs relevant to the
specific section being read. For example, the hash returned by readFrameHeader for an mp3 file
will include an mpegAudioVersion key of value “MPEG Version 1 (ISO/IEC 11172-3)” and a
layerDescription key of value “Layer III”. A section description will always include a
_section attribute - a 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

In further detail:

readFrameHeader(view, [offset])

Read and return description of header of frame located at offset of DataView view. Returns
null in the event that no frame header is found at offset.

A couple of example descriptions:

  • Version 1, Layer III (mp3), 44.1KHz 128Kbs Joint Stereo:

    1. {
    2. _section: {
    3. type: 'frameHeader',
    4. offset: 99934,
    5. byteLength: 4
    6. },
    7. mpegAudioVersionBits: '11',
    8. mpegAudioVersion: 'MPEG Version 1 (ISO/IEC 11172-3)',
    9. layerDescriptionBits: '01',
    10. layerDescription: 'Layer III',
    11. isProtected: 1,
    12. protectionBit: '1',
    13. bitrateBits: '1001',
    14. bitrate: 128,
    15. samplingRateBits: '00',
    16. samplingRate: 44100,
    17. frameIsPaddedBit: '1',
    18. frameIsPadded: true,
    19. framePadding: 1,
    20. privateBit: '0',
    21. channelModeBits: '01',
    22. channelMode: 'Joint stereo (Stereo)'
    23. }
  • Version 2, Layer II, 16KHz 32Kbs Mono:

    1. {
    2. _section: {
    3. type: 'frameHeader',
    4. offset: 0,
    5. byteLength: 4
    6. },
    7. mpegAudioVersionBits: '10',
    8. mpegAudioVersion: 'MPEG Version 2 (ISO/IEC 13818-3)',
    9. layerDescriptionBits: '10',
    10. layerDescription: 'Layer II',
    11. isProtected: 1,
    12. protectionBit: '1',
    13. bitrateBits: '0100',
    14. bitrate: 32,
    15. samplingRateBits: '10',
    16. samplingRate: 16000,
    17. frameIsPaddedBit: '0',
    18. frameIsPadded: false,
    19. framePadding: 0,
    20. privateBit: '0',
    21. channelModeBits: '11',
    22. channelMode: 'Single channel (Mono)'
    23. }

readFrame(view, [offset[, requireNextFrame]])

Read and return description of frame located at offset of DataView view. Includes the frame
header description (see readFrameHeader) plus basic information about the frame: The frame’s
length in bytes and the index of the next frame if requireNextFrame is set. In this case, the
presence of a next valid frame will be required for this frame to be regarded as valid. Returns
null in the event that no frame is found at offset.

As an example description:

  1. {
  2. _section: {
  3. type: 'frame',
  4. offset: 99934,
  5. byteLength: 418,
  6. sampleLength: 1152,
  7. nextFrameIndex: 100352 // Available iff 'requireNextFrame'
  8. },
  9. header: { /* .. a frame header description .. */ }
  10. }

readLastFrame(view, [offset[, requireNextFrame]])

Locate and return the description of the very last valid frame in given DataView view. The search
is carried out in reverse, from given offset (or the very last octet if offset is omitted) to
the buffer’s beginning. If requireNextFrame is set, the presence of a next valid frame will be
required for any found frame to be regarded as valid (causing the method to essentially return the
next-to-last frame on success). Returns null in the event that no frame is found at offset.

readId3v2Tag(view[, offset])

Read and return description of ID3v2 Tag located at offset of
DataView view. (This will include any and all
currently supported ID3v2 frames located within the
tag). Returns null in the event that no tag is found at offset.

As an example description:

  1. {
  2. _section: {
  3. type: 'ID3v2',
  4. offset: 0,
  5. byteLength: 2048
  6. },
  7. header: {
  8. majorVersion: 3,
  9. minorRevision: 0,
  10. flagsOctet: 0,
  11. unsynchronisationFlag: false,
  12. extendedHeaderFlag: false,
  13. experimentalIndicatorFlag: false,
  14. size: 2038
  15. },
  16. frames: [{
  17. header: {
  18. id: 'TIT2',
  19. size: 12,
  20. flagsOctet1: 0,
  21. flagsOctet2: 0
  22. },
  23. name: 'Title/songname/content description',
  24. content: {
  25. encoding: 0,
  26. value: 'Flight Path'
  27. }
  28. }, {
  29. header: {
  30. id: 'TPUB',
  31. size: 10,
  32. flagsOctet1: 0,
  33. flagsOctet2: 0
  34. },
  35. name: 'Publisher',
  36. content: {
  37. encoding: 0,
  38. value: 'Planet Mu'
  39. }
  40. }, {
  41. header: {
  42. id: 'TCON',
  43. size: 4,
  44. flagsOctet1: 0,
  45. flagsOctet2: 0
  46. },
  47. name: 'Content type',
  48. content: {
  49. encoding: 0,
  50. value: '(3)'
  51. }
  52. }, {
  53. header: {
  54. id: 'TALB',
  55. size: 9,
  56. flagsOctet1: 0,
  57. flagsOctet2: 0
  58. },
  59. name: 'Album/Movie/Show title',
  60. content: {
  61. encoding: 0,
  62. value: 'Severant'
  63. }
  64. }, {
  65. header: {
  66. id: 'TRCK',
  67. size: 3,
  68. flagsOctet1: 0,
  69. flagsOctet2: 0
  70. },
  71. name: 'Track number/Position in set',
  72. content: {
  73. encoding: 0,
  74. value: '11'
  75. }
  76. }, {
  77. header: {
  78. id: 'TYER',
  79. size: 5,
  80. flagsOctet1: 0,
  81. flagsOctet2: 0
  82. },
  83. name: 'Year',
  84. content: {
  85. encoding: 0,
  86. value: '2011'
  87. }
  88. }, {
  89. /* .. more frames follow .. */
  90. }]
  91. }

readXingTag(view[, offset])

Read and return description of Xing / Lame Tag
located at offset of DataView view. Returns null in the event that no frame is found at
offset.

As an example description:

  1. {
  2. _section: {
  3. type: 'Xing',
  4. offset: 2462,
  5. byteLength: 417,
  6. nextFrameIndex: 2879
  7. },
  8. header: { /* .. a frame header description .. */ },
  9. identifier: 'Xing' // Or 'Info' if Lame tag
  10. }

readTags(view[, offset])

Read and return descriptions of all tags found up to (and additionally including) the very first
frame. Returns an array of descriptions which may include that of a located ID3V2 tag, of a located
Xing / Lame tag and of a located first frame.

You may also want to

Contributing

Contibutions are appreciated, naturally. Feel free to submit pull requests against master. Please
make sure that npm run lint and npm test are green before you do so. Pull requests featuring
appropriate unit tests are ideal. However, less than ideal pull requests are also fine, especially
until the test suite gets the documentation it deserves - probably along with some necessary
housekeeping.

Changelog

Next — Diff

TBD

0.3.0 — Nov 20, 2016Diff

  • Add support for ID3v2 CHAP frames (Thanks markusahlstrand).
  • Add support for MPEG v2 / layers I - III (Thanks jdelStrother).
  • Fix ID3v2 IPLS frame parsing defect (fixes issue #4, probably maybe).
  • Improve test-runner (switch to Jasmine). Add tests. Revise and clean-up linter config.
  • Lots of minor fixes and housekeeping.

License

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

Copyright (c) 2013-2016 Alex Lambiris