music-metadata

Before integrating music-metadata, ensure your environment meets the following requirements:

• Node.js: Requires version ≥ 18.
• Module System: Since version 8, the module has migrated from CommonJS to pure ECMAScript Module (ESM). It is compliant with the ECMAScript 2020 (11th Edition) standard.
• Browser Support: The module can be used in browser environments when bundled with a module bundler such as Webpack or Rollup.

The IAudioMetadata object returned by parsing functions contains several key sections:

• format: (IFormat) Audio format information (container, codec, duration, bitrate, sample rate, etc.).
• common: Generic, abstract way of accessing metadata (artist, album, title, etc.).
• trackInfo: (Experimental) An array of trackInfo objects for containers with multiple tracks (like MKV or MP4), providing details for specific audio or video tracks.
• native: A list of the original, native tags found in the file (e.g., ID3v2.3).

You can install the music-metadata module using either npm or yarn to begin extracting audio metadata in your projects.

npm install music-metadata

or

yarn add music-metadata

Since music-metadata is an ESM module, the method for importing it in CommonJS depends on your Node.js version:

1. Node.js ≥ 22: You can use standard require().
2. Node.js < 22: You must use a dynamic import().
3. TypeScript (CommonJS module): Use the load-esm package to handle the dynamic import.

// Node.js ≥ 22
const mm = require('music-metadata');

// Node.js < 22
(async () => {
  const mm = await import('music-metadata');
})();

// CommonJS TypeScript with 'load-esm'
import {loadEsm} from 'load-esm';

(async () => {
  const mm = await loadEsm<typeof import('music-metadata')>('music-metadata');
})();

When reading the duration of a stream (excluding file streams), you must provide the file size in bytes in the options object. This allows the parser to correctly calculate the duration based on the stream length.

Use parseStream from music-metadata and pass the size and mimeType in the options object, and set duration: true in the third argument (the options object for the parser itself).

import { parseStream } from 'music-metadata';
import { inspect } from 'util';

(async () => {
    const metadata = await parseStream(someReadStream, {mimeType: 'audio/mpeg', size: 26838}, {duration: true});
    console.log(inspect(metadata, {showHidden: false, depth: null}));
    someReadStream.close();
  }
)();

Use parseBlob to extract metadata from a Web API Blob or File object. This is a cross-platform function suitable for browser environments. Note that it requires environments supporting ReadableStreamBYOBReader (available in Node.js 20+).

import { parseBlob } from 'music-metadata';

(async () => {
  const fileInput = document.querySelector('input[type="file"]');
  const file = fileInput.files[0];
  
  try {
    const metadata = await parseBlob(file);
    console.log(metadata);
  } catch (error) {
    console.error('Error parsing metadata:', error.message);
  }
})();

The library provides several utility functions for processing metadata:

• orderTags(nativeTags: ITag[]): [tagId: string]: any[]: Converts native tags into a dictionary indexed by tag identifier.
• ratingToStars(rating: number): number: Converts a normalized rating value to a 0..5 star scale.
• selectCover(pictures?: IPicture[]): IPicture | null: Selects the best cover image based on image type, falling back to the first available picture.
• getSupportedMimeTypes(): Returns a list of all supported MIME-types.

Use parseFile to extract metadata from audio files located on the local filesystem. This function is specific to Node.js and is generally faster than stream-based parsing because it can perform direct file access (jumping to specific offsets).

import { parseFile } from 'music-metadata';
import { inspect } from 'node:util';

(async () => {
  try {
    const filePath = 'test/samples/MusicBrainz - Beth Hart - Sinner\'s Prayer [id3v2.3].V2.mp3';
    const metadata = await parseFile(filePath);

    // Output the parsed metadata to the console in a readable format
    console.log(inspect(metadata, { showHidden: false, depth: null }));
  } catch (error) {
    console.error('Error parsing metadata:', error.message);
  }
})();