{"id":25092814,"url":"https://github.com/biril/mp3-parser","last_synced_at":"2025-04-16T01:54:25.683Z","repository":{"id":57303464,"uuid":"11266471","full_name":"biril/mp3-parser","owner":"biril","description":"Read MPEG audio frames \u0026 tags","archived":false,"fork":false,"pushed_at":"2018-09-10T13:27:57.000Z","size":794,"stargazers_count":43,"open_issues_count":3,"forks_count":16,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-04-07T03:08:16.119Z","etag":null,"topics":["audio","id3","lame","mp2","mp3","mpeg-audio","xing"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/biril.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2013-07-08T21:55:24.000Z","updated_at":"2024-10-27T14:38:52.000Z","dependencies_parsed_at":"2022-08-31T00:00:55.314Z","dependency_job_id":null,"html_url":"https://github.com/biril/mp3-parser","commit_stats":null,"previous_names":[],"tags_count":10,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/biril%2Fmp3-parser","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/biril%2Fmp3-parser/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/biril%2Fmp3-parser/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/biril%2Fmp3-parser/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/biril","download_url":"https://codeload.github.com/biril/mp3-parser/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249183101,"owners_count":21226141,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["audio","id3","lame","mp2","mp3","mpeg-audio","xing"],"created_at":"2025-02-07T14:34:56.823Z","updated_at":"2025-04-16T01:54:25.663Z","avatar_url":"https://github.com/biril.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"mp3 Parser\n==========\n\n[![Build Status](https://travis-ci.org/biril/mp3-parser.png)](https://travis-ci.org/biril/mp3-parser)\n[![NPM version](https://badge.fury.io/js/mp3-parser.png)](http://badge.fury.io/js/mp3-parser)\n[![Bower version](https://badge.fury.io/bo/mp3-parser.png)](http://badge.fury.io/bo/mp3-parser)\n\nLocate and read MPEG audio file sections: Individual frames as well as ID3v2 and Xing/Lame tags. For\nany of these found within a given buffer, mp3 Parser will provide data indicating their presence,\ntheir position within the buffer, as well as relevant informative data (with varying degrees of\ndetail).\n\n\nSet up\n------\n\nTo use mp3 Parser\n\n* install with bower, `bower install mp3-parser` or\n* install with npm, `npm install mp3-parser` or\n* just include the relevant files (see below), in case you're targeting a browser and don't want to\n    go over npm or bower.\n\nmp3 Parser may be used as a CommonJS module on Node or in a browser, either as an AMD module or\nthrough plain `\u003cscript\u003e` tags. It's automatically exported in the appropriate format depending on\nthe current environment:\n\n* When working _with CommonJS_ (e.g. Node), assuming mp3 Parser is `npm install`ed:\n\n    ```javascript\n    var mp3Parser = require(\"mp3-parser\");\n    var mp3Tags = mp3Parser.readTags(someMp3DataView);\n    ```\n\n* When working _with an AMD loader_ (e.g. requireJS):\n\n    ```javascript\n    // Your module\n    define([\"path/to/mp3-parser/main\"], function (mp3Parser) {\n        var mp3Tags = mp3Parser.readTags(someMp3DataView);\n    });\n    ```\n\n    In the example above, it is assumed that mp3-parser source files live in\n    `path/to/mp3-parser` (relative to the root path used for module lookups). When using requireJS\n    you may prefer to [treat mp3-parser as a package](http://requirejs.org/docs/api.html#packages):\n\n    ```javascript\n    // Configure requireJS for the mp3-parser package ..\n    require.config({\n        packages: [{\n            name: \"mp3-parser\",\n            location: \"path/to/mp3-parser\"\n        }]\n    })\n\n    // .. and refer to mp3-parser module by its given package name\n    define([\"mp3-parser\"], function (mp3Parser) {\n        var mp3Tags = mp3Parser.readTags(someMp3DataView);\n    });\n    ```\n\n\n* Setting up mp3 Parser in projects targetting _browsers, without an AMD module loader_, is\n    unfortunately quite verbose as it relies on the (order-specific) inclusion of a number of\n    sources. This should be mitigated in the future, but for now you would need:\n\n    ```html\n    ...\n    \u003cscript type=\"text/javascript\" src=\"path/to/mp3-parser/lib/lib.js\"\u003e\u003c/script\u003e\n    \u003cscript type=\"text/javascript\" src=\"path/to/mp3-parser/lib/xing.js\"\u003e\u003c/script\u003e\n    \u003cscript type=\"text/javascript\" src=\"path/to/mp3-parser/lib/id3v2.js\"\u003e\u003c/script\u003e\n    \u003cscript type=\"text/javascript\" src=\"path/to/mp3-parser/main.js\"\u003e\u003c/script\u003e\n    ...\n    ```\n\n    which would export the `mp3Parser` global:\n\n    ```javascript\n    var mp3Tags = mp3Parser.readTags(someMp3DataView);\n    ```\n\n\nUsage\n-----\n\nThe parser's API consists of `read____` methods, each dedicated to reading a specific section\nof the MPEG audio file. The current implementation includes `readFrameHeader`, `readFrame`,\n`readLastFrame`, `readId3v2Tag`, `readXingTag` and `readTags`. Each of these accepts a\n[DataView](http://www.khronos.org/registry/typedarray/specs/latest/#8)-wrapped ArrayBuffer\ncontaining the audio data, and optionally an offset into the buffer.\n\nIn all cases, a 'description' will be returned - a hash containing key-value pairs relevant to the\nspecific section being read. For example, the hash returned by `readFrameHeader` for an mp3 file\nwill include an `mpegAudioVersion` key of value \"MPEG Version 1 (ISO/IEC 11172-3)\" and a\n`layerDescription` key of value \"Layer III\". A section description will always include a\n`_section` attribute - a hash with `type`, `byteLength` and `offset` keys:\n\n* `type`: \"frame\", \"frameHeader\", \"Xing\" or \"ID3v2\"\n* `byteLenfth`: Size of the section in bytes\n* `offset`: Buffer offset at which this section resides\n\nIn further detail:\n\n\n### readFrameHeader(view, [offset])\n\nRead and return description of header of frame located at `offset` of DataView `view`. Returns\n`null` in the event that no frame header is found at `offset`.\n\nA couple of example descriptions:\n\n* Version 1, Layer III (mp3), 44.1KHz 128Kbs Joint Stereo:\n\n    ```javascript\n    {\n        _section: {\n            type: 'frameHeader',\n            offset: 99934,\n            byteLength: 4\n        },\n        mpegAudioVersionBits: '11',\n        mpegAudioVersion: 'MPEG Version 1 (ISO/IEC 11172-3)',\n        layerDescriptionBits: '01',\n        layerDescription: 'Layer III',\n        isProtected: 1,\n        protectionBit: '1',\n        bitrateBits: '1001',\n        bitrate: 128,\n        samplingRateBits: '00',\n        samplingRate: 44100,\n        frameIsPaddedBit: '1',\n        frameIsPadded: true,\n        framePadding: 1,\n        privateBit: '0',\n        channelModeBits: '01',\n        channelMode: 'Joint stereo (Stereo)'\n    }\n    ```\n\n* Version 2, Layer II, 16KHz 32Kbs Mono:\n\n    ```javascript\n    {\n        _section: {\n            type: 'frameHeader',\n            offset: 0,\n            byteLength: 4\n        },\n        mpegAudioVersionBits: '10',\n        mpegAudioVersion: 'MPEG Version 2 (ISO/IEC 13818-3)',\n        layerDescriptionBits: '10',\n        layerDescription: 'Layer II',\n        isProtected: 1,\n        protectionBit: '1',\n        bitrateBits: '0100',\n        bitrate: 32,\n        samplingRateBits: '10',\n        samplingRate: 16000,\n        frameIsPaddedBit: '0',\n        frameIsPadded: false,\n        framePadding: 0,\n        privateBit: '0',\n        channelModeBits: '11',\n        channelMode: 'Single channel (Mono)'\n    }\n    ```\n\n### readFrame(view, [offset[, requireNextFrame]])\n\nRead and return description of frame located at `offset` of DataView `view`. Includes the frame\nheader description (see `readFrameHeader`) plus basic information about the frame: The frame's\nlength in bytes and the index of the next frame _if_ `requireNextFrame` is set. In this case, the\npresence of a _next_ valid frame will be required for _this_ frame to be regarded as valid. Returns\n`null` in the event that no frame is found at `offset`.\n\nAs an example description:\n\n```javascript\n{\n    _section: {\n        type: 'frame',\n        offset: 99934,\n        byteLength: 418,\n        sampleLength: 1152,\n        nextFrameIndex: 100352 // Available iff 'requireNextFrame'\n    },\n    header: { /* .. a frame header description .. */ }\n}\n```\n\n\n### readLastFrame(view, [offset[, requireNextFrame]])\n\nLocate and return the description of the very last valid frame in given DataView `view`. The search\nis carried out in reverse, from given `offset` (or the very last octet if `offset` is omitted) to\nthe buffer's beginning. If `requireNextFrame` is set, the presence of a next valid frame will be\nrequired for any found frame to be regarded as valid (causing the method to essentially return the\nnext-to-last frame on success). Returns `null` in the event that no frame is found at `offset`.\n\n\n### readId3v2Tag(view[, offset])\n\nRead and return description of [ID3v2 Tag](http://id3.org/id3v2.3.0) located at `offset` of\nDataView `view`. (This will include any and all\n[currently supported ID3v2 frames](https://github.com/biril/mp3-parser/wiki) located within the\ntag). Returns `null` in the event that no tag is found at `offset`.\n\nAs an example description:\n\n```javascript\n{\n    _section: {\n        type: 'ID3v2',\n        offset: 0,\n        byteLength: 2048\n    },\n    header: {\n        majorVersion: 3,\n        minorRevision: 0,\n        flagsOctet: 0,\n        unsynchronisationFlag: false,\n        extendedHeaderFlag: false,\n        experimentalIndicatorFlag: false,\n        size: 2038\n    },\n    frames: [{\n        header: {\n            id: 'TIT2',\n            size: 12,\n            flagsOctet1: 0,\n            flagsOctet2: 0\n        },\n        name: 'Title/songname/content description',\n        content: {\n            encoding: 0,\n            value: 'Flight Path'\n        }\n    }, {\n        header: {\n            id: 'TPUB',\n            size: 10,\n            flagsOctet1: 0,\n            flagsOctet2: 0\n        },\n        name: 'Publisher',\n        content: {\n            encoding: 0,\n            value: 'Planet Mu'\n        }\n    }, {\n        header: {\n            id: 'TCON',\n            size: 4,\n            flagsOctet1: 0,\n            flagsOctet2: 0\n        },\n        name: 'Content type',\n        content: {\n            encoding: 0,\n            value: '(3)'\n        }\n    }, {\n        header: {\n            id: 'TALB',\n            size: 9,\n            flagsOctet1: 0,\n            flagsOctet2: 0\n        },\n        name: 'Album/Movie/Show title',\n        content: {\n            encoding: 0,\n            value: 'Severant'\n        }\n    }, {\n        header: {\n            id: 'TRCK',\n            size: 3,\n            flagsOctet1: 0,\n            flagsOctet2: 0\n        },\n        name: 'Track number/Position in set',\n        content: {\n            encoding: 0,\n            value: '11'\n        }\n    }, {\n        header: {\n            id: 'TYER',\n            size: 5,\n            flagsOctet1: 0,\n            flagsOctet2: 0\n        },\n        name: 'Year',\n        content: {\n            encoding: 0,\n            value: '2011'\n        }\n    }, {\n        /* .. more frames follow .. */\n    }]\n}\n```\n\n\n### readXingTag(view[, offset])\n\nRead and return description of [Xing / Lame Tag](http://gabriel.mp3-tech.org/mp3infotag.html)\nlocated at `offset` of DataView `view`. Returns `null` in the event that no frame is found at\n`offset`.\n\nAs an example description:\n\n```javascript\n{\n    _section: {\n        type: 'Xing',\n        offset: 2462,\n        byteLength: 417,\n        nextFrameIndex: 2879\n    },\n    header: { /* .. a frame header description .. */ },\n    identifier: 'Xing' // Or 'Info' if Lame tag\n}\n```\n\n\n### readTags(view[, offset])\n\nRead and return descriptions of all tags found up to (and additionally including) the very first\nframe. Returns an array of descriptions which may include that of a located ID3V2 tag, of a located\nXing / Lame tag and of a located first frame.\n\n\nYou may also want to\n--------------------\n\n* View the [annotated version of the source](http://biril.github.io/mp3-parser/).\n* Try out the [load remote](https://github.com/biril/mp3-parser/tree/0.3.0/example/load-remote),\n    [read file](https://github.com/biril/mp3-parser/tree/0.3.0/example/read-file)\n    \u0026 [cmd line parse](https://github.com/biril/mp3-parser/tree/0.3.0/example/cmd-line-parse) examples.\n* Take a look at [the project's wiki](https://github.com/biril/mp3-parser/wiki) which contains a\n    list of currently (un)supported ID3v2 tag frames.\n\n\nContributing\n------------\n\nContibutions are appreciated, naturally. Feel free to submit pull requests against `master`. Please\nmake sure that `npm run lint` and `npm test` are green before you do so. Pull requests featuring\nappropriate unit tests are ideal. However, less than ideal pull requests are also fine, especially\nuntil the test suite gets the documentation it deserves - probably along with some necessary\nhousekeeping.\n\n\nChangelog\n---------\n\n#### Next — [Diff](https://github.com/biril/mp3-parser/compare/0.3.0...master)\n\nTBD\n\n\n#### 0.3.0 — _Nov 20, 2016_ — [Diff](https://github.com/biril/mp3-parser/compare/0.2.7...0.3.0)\n\n* Add support for ID3v2 CHAP frames (Thanks [markusahlstrand](https://github.com/markusahlstrand)).\n* Add support for MPEG v2 / layers I - III (Thanks [jdelStrother](https://github.com/jdelStrother)).\n* Fix ID3v2 IPLS frame parsing defect (fixes [issue #4](https://github.com/biril/mp3-parser/issues/4), probably maybe).\n* Improve test-runner (switch to Jasmine). Add tests. Revise and clean-up linter config.\n* Lots of minor fixes and housekeeping.\n\n\nLicense\n-------\n\nLicensed and freely distributed under the MIT License (LICENSE.txt).\n\nCopyright (c) 2013-2016 Alex Lambiris\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbiril%2Fmp3-parser","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbiril%2Fmp3-parser","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbiril%2Fmp3-parser/lists"}