music-metadata

music-metadata

Key features:

• Comprehensive Format Support: Supports popular audio formats like MP3, MP4, FLAC, Ogg, WAV, AIFF, and more.
• Extensive Metadata Extraction: Extracts detailed metadata, including ID3v1, ID3v2, APE, Vorbis, and iTunes/MP4 tags.
• Streaming Support: Efficiently handles large audio files by reading metadata from streams, making it suitable for server-side and browser-based applications.
• Promise-Based API: Provides a modern, promise-based API for easy integration into asynchronous workflows.
• Cross-Platform: Works in both Node.js and browser environments with the help of bundlers like Webpack or Rollup.

The music-metadata module is ideal for developers working on media applications, music players, or any project that requires access to detailed audio file metadata.

Compatibility

Module: version 8 migrated from CommonJS to pure ECMAScript Module (ESM). The distributed JavaScript codebase is compliant with the ECMAScript 2020 (11th Edition) standard.

[!NOTE] See also CommonJS backward Compatibility

This module requires a Node.js ≥ 18 engine. It can also be used in a browser environment when bundled with a module bundler.

Support the Project

If you find this project useful and would like to support its development, consider sponsoring or contributing:

• Become a sponsor to Borewit

• Buy me a coffee:

Features

Support for audio file types

Supported tag headers

Following tag header formats are supported:

• APE
• ASF
• EXIF 2.3
• ID3: ID3v1, ID3v1.1, ID3v2.2, ID3v2.3, ID3v2.4 and ID3v2 Chapters 1.0
• iTunes
• RIFF/INFO
• Vorbis comment
• AIFF

Following lyric formats are supported:

• LRC
• Synchronized lyrics (SYLT)
• Unsynchronized lyrics (USULT)

Support for MusicBrainz tags as written by Picard. ReplayGain tags are supported.

Audio format & encoding details

Support for encoding / format details:

• Bit rate
• Audio bit depth
• Duration
• Encoding profile (e.g. CBR, V0, V2)

Online demo's

• Audio Tag Analyzer
• Webamp
• ICY Radio Stream Player
• Expected to be released soon: Overtone by Johannes Schickling

Usage

Installation

Install using npm:

npm install music-metadata

or using yarn:

yarn add music-metadata

API Documentation

Overview

Node.js specific functions to read an audio file or stream:

1. File Parsing: Parse audio files directly from the filesystem using the parseFile function
2. Stream Parsing: Parse audio metadata from a Node.js Readable stream using the parseStream function.

Cross-platform functions available to read an audio file or stream:

There are multiple ways to parse (read) audio tracks:

1. Web Stream Parsing: Parse audio data from a web-compatible ReadableStream using the parseWebStream function.
2. Blob Parsing: Parse audio metadata from a (Web API) Blob or File using the parseBlob function.
3. Buffer Parsing: Parse audio metadata from a Uint8Array or Buffer using the parseBuffer function.
4. Tokenizer Parsing: Use a custom or third-party strtok3 ITokenizer to parse using the parseFromTokenizer function.

[!NOTE] Direct file access in Node.js is generally faster because it can 'jump' to various parts of the file without reading intermediate data.

Node.js specific function

These functions are tailored for Node.js environments and leverage Node.js-specific APIs, making them incompatible with browser-based JavaScript engines.

parseFile function

The parseFile function is intended for extracting metadata from audio files on the local filesystem in a Node.js environment. It reads the specified file, parses its audio metadata, and returns a promise that resolves with this information.

Syntax

parseFile(filePath: string, options?: IOptions): Promise

Parameters

• filePath: string

  The path to the media file from which metadata should be extracted. This should be a valid path to an audio file on the local filesystem.

• options: IOptions (optional)

  An optional configuration object that allows customization of the parsing process. These options can include whether to calculate the file's duration, skip embedded cover art, or other parsing behaviors.

Returns

• Promise:

  A promise that resolves to an IAudioMetadata object containing metadata about the audio file. The metadata includes details such as the file format, codec, duration, bit rate, and any embedded tags like album, artist, or track information.

Usage Notes

• This function is Node.js-only and relies on Node.js-specific APIs to access the filesystem.

• For browser environments, consider using the parseBlob to parse File object objects.

Example:

The following example demonstrates how to use the parseFile function to read metadata from an audio file:

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

`parse