Registry / serialization / id3-parser

id3-parser

JSON →
library3.0.0jsnpmunverified

id3-parser is a pure JavaScript library designed for parsing ID3 tags (versions 1 and 2.3) from MP3 audio files. The current stable version, 3.0.0, requires Node.js version 16 or newer. It offers a straightforward API with a primary `parse` function that intelligently detects and extracts metadata, alongside specific functions like `parseV1Tag` and `parseV2Tag` for targeted parsing. The library ships with TypeScript types, ensuring good developer experience in modern TypeScript and JavaScript environments. While primarily used in Node.js for server-side processing, it includes utilities (`convertFileToBuffer`, `fetchFileAsBuffer`) that facilitate its use in browser environments when bundled with tools like Webpack. Its key differentiators include its focus on robust parsing of common ID3v1 and ID3v2.3 frames, providing comprehensive metadata such as artist, album, title, year, comments, lyrics, and embedded cover art from binary data. The release cadence is typically driven by bug fixes, maintenance, and alignment with modern JavaScript ecosystem standards.

npm install id3-parser
INSTALL
IMPORT
SIG · ID3-PARSER
I
id3-parser
serializationjavascriptv3.0.0
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

parse
import parse from 'id3-parser';
const parse = require('id3-parser');
The primary parsing function is a default export. Since v3.x, the library is primarily ESM, so CommonJS 'require' is not supported.
parseV1Tag, parseV2Tag
import { parseV1Tag, parseV2Tag } from 'id3-parser';
import parseV1Tag from 'id3-parser/parseV1Tag';
These are named exports from the main package entry point for parsing specific ID3 versions.
convertFileToBuffer, fetchFileAsBuffer
import { convertFileToBuffer, fetchFileAsBuffer } from 'id3-parser/lib/util';
import { convertFileToBuffer } from 'id3-parser';
Utility functions for browser environments are exported from a specific sub-path, not the main entry. These help convert browser File objects or remote URLs into a buffer format compatible with the parser.

Demonstrates how to fetch and parse ID3 tags from a remote MP3 URL, applicable to both browser (with utilities) and Node.js environments.

import parse, { fetchFileAsBuffer } from 'id3-parser'; // This example demonstrates parsing a remote MP3 file in a browser-like environment. // In a Node.js environment, you would typically read a file into a Buffer or Uint8Array directly. async function processMp3File(url: string) { console.log(`Attempting to fetch and parse: ${url}`); try { // fetchFileAsBuffer handles fetching the URL and converting the response to a buffer // that id3-parser can process. const buffer = await fetchFileAsBuffer(url); const tags = parse(buffer); if (tags) { console.log('ID3 Tags found:'); console.log(` Title: ${tags.title || 'N/A'}`); console.log(` Artist: ${tags.artist || 'N/A'}`); console.log(` Album: ${tags.album || 'N/A'}`); console.log(` Year: ${tags.year || 'N/A'}`); if (tags.image) { console.log(` Cover Art: ${tags.image.mime}, size ${tags.image.data.byteLength} bytes`); } if (tags.comments && tags.comments.length > 0) { console.log(` Comments: ${tags.comments[0].value.substring(0, 50)}...`); } } else { console.log('No ID3 tags found in the file.'); } } catch (error) { console.error(`Failed to parse MP3 from ${url}:`, error); } } // Replace with a publicly accessible, small MP3 file URL for testing. // Note: CORS policies might prevent fetching from arbitrary domains in browsers. const exampleMp3Url = 'https://www.soundhelix.com/examples/mp3/SoundHelix-Song-1.mp3'; processMp3File(exampleMp3Url); // Example of how you might parse a Node.js Buffer (assuming `fs` and `path` are available) // import * as fs from 'fs'; // import * as path from 'path'; // const localFilePath = path.join(__dirname, 'path/to/your/audio.mp3'); // if (fs.existsSync(localFilePath)) { // const buffer = fs.readFileSync(localFilePath); // const tags = parse(buffer); // console.log('Local file tags:', tags); // }
Debug
Known issues
breakingVersion 3.x of `id3-parser` explicitly requires Node.js version 16 or newer. Running on older Node.js environments will result in runtime errors.
fix
Upgrade your Node.js environment to version 16 or later. Consider using a Node.js version manager like `nvm` or `volta` to manage multiple Node.js versions.
affects: >=3.0.0
breakingAs of version 3.x, `id3-parser` is primarily distributed as an ECMAScript Module (ESM). Direct `require()` calls for the main package entry point will likely fail with `ERR_REQUIRE_ESM`.
fix
Refactor your imports to use ES Modules syntax: `import parse from 'id3-parser';` for the default export and `import { namedExport } from 'id3-parser';` for named exports.
affects: >=3.0.0
gotcha`id3-parser` only supports ID3v1 and ID3v2.3 tags. It does not parse ID3v2.4 tags, which are a later revision of the standard and may contain different or additional frames.
fix
Be aware that MP3s tagged with ID3v2.4 will only be partially parsed (or not at all if only v2.4 tags are present). If full ID3v2.4 support is required, consider alternative libraries or pre-processing files to convert tags to ID3v2.3 if possible. The library currently does not provide a direct upgrade path to v2.4.
affects: >=1.0.0
gotchaWhen used in a browser environment, `id3-parser` requires a bundler (e.g., Webpack, Rollup, Parcel) to correctly resolve its dependencies and handle Node.js-specific constructs if any remain, as well as to convert source code to a browser-compatible format. Additionally, you'll need to use utility functions like `convertFileToBuffer` or `fetchFileAsBuffer` to prepare input data.
fix
Ensure your project uses a modern JavaScript bundler for browser deployment. Utilize `id3-parser/lib/util` functions for handling `File` objects or remote URLs in the browser.
affects: >=1.0.0
Errors
Common errors & fixes
ERR_REQUIRE_ESM: require() of ES Module .../node_modules/id3-parser/lib/index.js from ... not supported.
Attempting to import `id3-parser` using CommonJS `require()` syntax in a project where the package is treated as an ESM module.
fix
Change your import statement from `const parse = require('id3-parser');` to `import parse from 'id3-parser';`. Ensure your project's `package.json` sets `"type": "module"` or you are using `.mjs` files if mixing ESM and CJS.
TypeError: parse is not a function
Incorrectly importing the default export. Forgetting that `parse` is a default export and trying to destructure it or import it as a namespace.
fix
Use `import parse from 'id3-parser';` for the default export. Avoid `import { parse } from 'id3-parser';` (which would be for a named export `parse`) or `import * as ID3Parser from 'id3-parser'; ID3Parser.parse(...)` if `parse` is the default export.
ReferenceError: Buffer is not defined
This error typically occurs when `id3-parser` is used in a browser environment, and the input data is expected to be a Node.js `Buffer` without a proper polyfill or conversion.
fix
In browser environments, use the provided utility functions from `id3-parser/lib/util`, specifically `convertFileToBuffer(file)` for `File` objects or `fetchFileAsBuffer(url)` for remote URLs. These functions will provide a `Uint8Array` or `number[]` which `parse` can handle, avoiding direct `Buffer` usage.
Upgrade
Version history
3.0.0latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
8 hits · last 30 days
node
8
Resources
id3-parser — npm install id3-parser · libregistry