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

Audio format	Description	Logo
AIFF / AIFF-C	Audio Interchange File Format
AAC	ADTS / Advanced Audio Coding
APE	Monkey's Audio
ASF	Advanced Systems Format
BWF	Extended WAV format for broadcast and archiving
DSDIFF	Philips DSDIFF
DSF	Sony's DSD Stream File
FLAC	Free Lossless Audio Codec
MP2	MPEG-1 Audio Layer II (predecessor to MP3)
Matroska	Matroska (EBML), mka, mkv
MP3	MPEG-1 / MPEG-2 Audio Layer III
MPC	Musepack SV7
MPEG 4	mp4, m4a, m4v
Ogg	Open container format
Opus	Low-latency, high-quality codec for speech and music
Speex	Open-source speech codec optimized for VoIP
Theora	Open video compression format (typically paired with Ogg)
Vorbis	Vorbis audio compression
WAV	Uncompressed PCM audio in RIFF container
WebM	WebM
WV	WavPack
WMA	Windows Media Audio

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 1. 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. 1. Blob Parsing: Parse audio metadata from a (Web API) Blob or File using the parseBlob function. 1. Buffer Parsing: Parse audio metadata from a Uint8Array or Buffer using the parseBuffer function. 1. 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<IAudioMetadata>

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