Registry / serialization / music-metadata

music-metadata

library11.12.3jsnpmunverified

music-metadata is a robust and comprehensive JavaScript library for parsing audio file metadata in Node.js and browser environments (with appropriate bundlers). It supports an extensive array of audio formats including MP3, MP4, FLAC, Ogg, WAV, and AIFF, and extracts detailed metadata such as ID3v1, ID3v2, APE, Vorbis, and iTunes/MP4 tags. The current stable version is 11.12.3, with regular patch and minor releases addressing bugs, enhancing features, and updating internal dependencies. Key differentiators include its broad format and tag support, efficient streaming capabilities for handling large audio files, a modern promise-based API for asynchronous workflows, and cross-platform compatibility. It primarily operates as an ECMAScript Module (ESM) and requires Node.js version 18 or newer.

serialization

npm install music-metadata

github ↗package ↗

INSTALL

IMPORT

SIG · MUSIC-METADATA

music-metadata

serializationjavascriptv11.12.3

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

parseFile

✓ import { parseFile } from 'music-metadata';

✗ const { parseFile } = require('music-metadata');

The library is pure ECMAScript Module (ESM) since v8.0.0. CommonJS 'require' will not work directly.

parseStream

✓ import { parseStream } from 'music-metadata';

✗ import * as mm from 'music-metadata'; const metadata = await mm.parseStream(...);

Most core parsing functions are named exports, not properties of a default import. Use `parseFile`, `parseStream`, `parseBuffer` directly.

IAudioMetadata

✓ import type { IAudioMetadata } from 'music-metadata';

TypeScript users should import the `IAudioMetadata` interface for type safety.

This quickstart demonstrates how to use `music-metadata` to parse metadata from a local audio file and a readable stream, including creating a dummy file for local testing.

import { parseFile } from 'music-metadata'; import { createReadStream, promises as fsPromises } from 'node:fs'; import { join } from 'node:path'; async function getAudioMetadata(filePath: string) { try { // Create a dummy file for demonstration purposes if it doesn't exist const dummyFilePath = join(__dirname, 'dummy.mp3'); try { await fsPromises.access(dummyFilePath); } catch { // Create a minimal dummy file if it doesn't exist await fsPromises.writeFile(dummyFilePath, Buffer.from('RIFF\x00\x00\x00\x00WAVEfmt \x10\x00\x00\x00\x01\x00\x01\x00D\xac\x00\x00\x80\xbb\x00\x00\x02\x00\x10\x00data\x00\x00\x00\x00')); console.log(`Created a dummy MP3 file at ${dummyFilePath}`); } // Parse metadata from the dummy file path const metadataFromFile = await parseFile(dummyFilePath); console.log('Metadata from file:', metadataFromFile.common.artist, '-', metadataFromFile.common.title); console.log('Duration:', metadataFromFile.format.duration, 'seconds'); // Alternatively, parse from a stream const stream = createReadStream(dummyFilePath); try { const metadataFromStream = await parseFile(stream); console.log('Metadata from stream:', metadataFromStream.common.artist, '-', metadataFromStream.common.title); } finally { stream.close(); } } catch (error) { console.error('Error parsing metadata:', error); } } // Replace 'your-audio-file.mp3' with a real path for actual use getAudioMetadata('./path/to/your-audio-file.mp3');

Debug

Known issues

breakingSince version 8.0.0, music-metadata is a pure ECMAScript Module (ESM) and no longer provides a CommonJS (CJS) entry point. Direct `require()` calls will result in an `ERR_REQUIRE_ESM` error.

fix

Migrate your project to use ES Modules with `import` statements, or use a dynamic `import()` call for CJS environments.

affects: >=8.0.0

breakingThe library explicitly requires Node.js version 18 or higher. Running it on older Node.js versions may lead to runtime errors or unexpected behavior due to dependency requirements.

fix

Ensure your Node.js environment is updated to version 18 or newer. Check your `package.json`'s `engines` field.

affects: >=8.0.0

gotchaVersion 11.12.2 was released with a critical bug where TypeScript declarations were missing, leading to compilation failures for TypeScript users. This was addressed in the immediate follow-up release.

fix

Avoid using version 11.12.2; upgrade to 11.12.3 or later for correct TypeScript declaration inclusion.

affects: 11.12.2

gotchaVersion 11.12.2 included a fix for CWE-85, addressing a potential infinite loop vulnerability in the ASF parser. Users of earlier versions are advised to upgrade to mitigate this risk.

fix

Upgrade to version 11.12.2 or higher to receive the fix for the ASF parser infinite loop vulnerability.

affects: <11.12.2

Errors

Common errors & fixes

ERR_REQUIRE_ESM

Attempting to `require()` music-metadata in a CommonJS module, but the library is ESM-only.

fix

Change `const { parseFile } = require('music-metadata');` to `import { parseFile } from 'music-metadata';` in your module. Ensure your project is configured for ES Modules (e.g., `"type": "module"` in `package.json`).

Error: ENOENT: no such file or directory, open 'your-audio-file.mp3'

The specified file path does not exist or is inaccessible.

fix

Verify that the `filePath` provided to `parseFile` is correct, the file exists, and your application has the necessary read permissions.

Error: No audio format detected

The provided file or stream is not a recognized audio format or is corrupted.

fix

Ensure the input file is a valid and supported audio format (e.g., MP3, FLAC, WAV). Check the file integrity if unsure.

Upgrade

Version history

11.12.3latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

28 hits · last 30 days

node

Resources

githubhttps://github.com/Borewit/music-metadata ↗

packagehttps://www.npmjs.com/package/music-metadata ↗