ID3 Tag Parser

Common errors

• ERR_REQUIRE_ESM: require() of ES Module .../node_modules/id3-parser/lib/index.js from ... not supported.

  cause 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

  cause 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

  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.
  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.

Warnings

• breaking 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.
  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.
• breaking 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`.
  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.
• 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.
• gotcha 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.
  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.

Install

• npm install id3-parser npm
• yarn add id3-parser yarn
• pnpm add id3-parser pnpm

Imports

• parse
  wrong:

  const parse = require('id3-parser');

  correct:

  import parse from '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
  wrong:

  import parseV1Tag from 'id3-parser/parseV1Tag';

  correct:

  import { parseV1Tag, parseV2Tag } from 'id3-parser';

  These are named exports from the main package entry point for parsing specific ID3 versions.
• convertFileToBuffer, fetchFileAsBuffer
  wrong:

  import { convertFileToBuffer } from 'id3-parser';

  correct:

  import { convertFileToBuffer, fetchFileAsBuffer } from 'id3-parser/lib/util';

  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.

Quickstart

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);
// }