{"id":16085,"library":"id3-parser","title":"ID3 Tag Parser","description":"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.","status":"active","version":"3.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/creeperyang/id3-parser","tags":["javascript","id3","id3 parser","id3 tag","id3v2","id3v1","mp3 metadata","mp3","typescript"],"install":[{"cmd":"npm install id3-parser","lang":"bash","label":"npm"},{"cmd":"yarn add id3-parser","lang":"bash","label":"yarn"},{"cmd":"pnpm add id3-parser","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The primary parsing function is a default export. Since v3.x, the library is primarily ESM, so CommonJS 'require' is not supported.","wrong":"const parse = require('id3-parser');","symbol":"parse","correct":"import parse from 'id3-parser';"},{"note":"These are named exports from the main package entry point for parsing specific ID3 versions.","wrong":"import parseV1Tag from 'id3-parser/parseV1Tag';","symbol":"parseV1Tag, parseV2Tag","correct":"import { parseV1Tag, parseV2Tag } from 'id3-parser';"},{"note":"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.","wrong":"import { convertFileToBuffer } from 'id3-parser';","symbol":"convertFileToBuffer, fetchFileAsBuffer","correct":"import { convertFileToBuffer, fetchFileAsBuffer } from 'id3-parser/lib/util';"}],"quickstart":{"code":"import parse, { fetchFileAsBuffer } from 'id3-parser';\n\n// This example demonstrates parsing a remote MP3 file in a browser-like environment.\n// In a Node.js environment, you would typically read a file into a Buffer or Uint8Array directly.\n\nasync function processMp3File(url: string) {\n  console.log(`Attempting to fetch and parse: ${url}`);\n  try {\n    // fetchFileAsBuffer handles fetching the URL and converting the response to a buffer\n    // that id3-parser can process.\n    const buffer = await fetchFileAsBuffer(url);\n    const tags = parse(buffer);\n\n    if (tags) {\n      console.log('ID3 Tags found:');\n      console.log(`  Title: ${tags.title || 'N/A'}`);\n      console.log(`  Artist: ${tags.artist || 'N/A'}`);\n      console.log(`  Album: ${tags.album || 'N/A'}`);\n      console.log(`  Year: ${tags.year || 'N/A'}`);\n      if (tags.image) {\n        console.log(`  Cover Art: ${tags.image.mime}, size ${tags.image.data.byteLength} bytes`);\n      }\n      if (tags.comments && tags.comments.length > 0) {\n        console.log(`  Comments: ${tags.comments[0].value.substring(0, 50)}...`);\n      }\n    } else {\n      console.log('No ID3 tags found in the file.');\n    }\n  } catch (error) {\n    console.error(`Failed to parse MP3 from ${url}:`, error);\n  }\n}\n\n// Replace with a publicly accessible, small MP3 file URL for testing.\n// Note: CORS policies might prevent fetching from arbitrary domains in browsers.\nconst exampleMp3Url = 'https://www.soundhelix.com/examples/mp3/SoundHelix-Song-1.mp3';\nprocessMp3File(exampleMp3Url);\n\n// Example of how you might parse a Node.js Buffer (assuming `fs` and `path` are available)\n// import * as fs from 'fs';\n// import * as path from 'path';\n// const localFilePath = path.join(__dirname, 'path/to/your/audio.mp3');\n// if (fs.existsSync(localFilePath)) {\n//   const buffer = fs.readFileSync(localFilePath);\n//   const tags = parse(buffer);\n//   console.log('Local file tags:', tags);\n// }\n","lang":"typescript","description":"Demonstrates how to fetch and parse ID3 tags from a remote MP3 URL, applicable to both browser (with utilities) and Node.js environments."},"warnings":[{"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.","message":"Version 3.x of `id3-parser` explicitly requires Node.js version 16 or newer. Running on older Node.js environments will result in runtime errors.","severity":"breaking","affected_versions":">=3.0.0"},{"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.","message":"As 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`.","severity":"breaking","affected_versions":">=3.0.0"},{"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.","message":"`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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"When 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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"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.","cause":"Attempting to import `id3-parser` using CommonJS `require()` syntax in a project where the package is treated as an ESM module.","error":"ERR_REQUIRE_ESM: require() of ES Module .../node_modules/id3-parser/lib/index.js from ... not supported."},{"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.","cause":"Incorrectly importing the default export. Forgetting that `parse` is a default export and trying to destructure it or import it as a namespace.","error":"TypeError: parse is not a function"},{"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.","cause":"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.","error":"ReferenceError: Buffer is not defined"}],"ecosystem":"npm"}