@suaveplan/audio-metadata - Universal audio metadata extractor: parses ID3v1/v2, MP4/M4A atoms, FLAC Vorbis comments, Ogg, WAV, AIFF, and returns a normalised Track record.
Summary
Universal audio metadata extractor that parses ID3v1/v2, MP4/M4A atoms, FLAC Vorbis comments, Ogg Vorbis, WAV RIFF, and AIFF/AIFC containers, returning a normalised Track record. Works in both Node.js and browser environments — zero native dependencies.
Documentation tree
- extractor — (no submodules)
- extractor — (no submodules)
- errors — (no submodules)
- metadata-error — (no submodules)
- aiff-id3 — (no submodules)
- aiff-id3 — (no submodules)
- flac-vorbis — (no submodules)
- flac-vorbis — (no submodules)
- format-detector — (no submodules)
- format-detector — (no submodules)
- id3v1 — (no submodules)
- id3v1 — (no submodules)
- id3v2 — (no submodules)
- id3v2 — (no submodules)
- mp4-atom — (no submodules)
- mp4-atom — (no submodules)
- ogg-vorbis — (no submodules)
- ogg-vorbis — (no submodules)
- wav-riff — (no submodules)
- wav-riff — (no submodules)
- utils — (no submodules)
- buffer-utils — (no submodules)
Installation
bun add @suaveplan/audio-metadata
Quick Start
import { extractMetadata } from "@suaveplan/audio-metadata";
// From a Uint8Array (e.g. via fetch or FileReader)
const response = await fetch("/song.mp3");
const buffer = new Uint8Array(await response.arrayBuffer());
const track = await extractMetadata(buffer);
console.log(track.title); // "Come Together"
console.log(track.artist); // "The Beatles"
console.log(track.album); // "Abbey Road"
console.log(track.year); // 1969
console.log(track.format); // "id3v2"
Supported Formats
| Format | Detection | Tags |
|---|---|---|
| MP3 with ID3v2.2/2.3/2.4 | Header magic ID3 |
Full tag set + cover art |
| MP3 with ID3v1/1.1 | Trailer magic TAG |
Fixed 128-byte fields |
| MP4/M4A | ftyp/moov atom |
iTunes ilst atoms |
| FLAC | fLaC magic |
Vorbis comments + stream info |
| Ogg Vorbis | OggS magic |
Vorbis comment packet |
| WAV | RIFF+WAVE magic |
LIST INFO chunks |
| AIFF/AIFC | FORM+AIFF/AIFC |
Embedded ID3 chunk |
API
extractMetadata(buffer, options?)
Module-level convenience function. Returns a Promise<Track>.
MetadataExtractor (class)
Singleton facade with multiple entry points:
extractFromBuffer(Uint8Array, options?): Promise<Track>extractFromArrayBuffer(ArrayBuffer, options?): Promise<Track>extractFromFile({ arrayBuffer(): Promise<ArrayBuffer> }, options?): Promise<Track>extractAudioMetadata(Uint8Array, options?): Promise<AudioMetadata>
Options
interface MetadataExtractionOptions {
skipCovers?: boolean; // Skip cover art. Default: false
maxCoverSize?: number; // Max cover bytes. Default: 5 MiB
skipLyrics?: boolean; // Skip lyrics. Default: false
}
Track shape
interface Track {
title?: string;
artist?: string;
album?: string;
albumArtist?: string;
year?: number;
trackNumber?: number;
totalTracks?: number;
discNumber?: number;
totalDiscs?: number;
genre?: string;
comment?: string;
lyrics?: string;
cover?: { data: Uint8Array; mimeType: string; description?: string };
duration?: number; // seconds
bitrate?: number; // kbps
sampleRate?: number; // Hz
channels?: number;
format?: AudioFormat;
rawTags?: Record<string, string | string[]>;
}
Module docs
src/utils/buffer-utils.md— Binary read helperssrc/parsers/format-detector/format-detector.md— Format detectionsrc/parsers/id3v1/id3v1.md— ID3v1/1.1 parsersrc/parsers/id3v2/id3v2.md— ID3v2.2/2.3/2.4 parsersrc/parsers/mp4-atom/mp4-atom.md— MP4/M4A atom parsersrc/parsers/flac-vorbis/flac-vorbis.md— FLAC + Vorbis commentssrc/parsers/ogg-vorbis/ogg-vorbis.md— Ogg Vorbis parsersrc/parsers/wav-riff/wav-riff.md— WAV RIFF INFO parsersrc/parsers/aiff-id3/aiff-id3.md— AIFF/AIFC + ID3 parsersrc/core/extractor/extractor.md— MetadataExtractor facadesrc/errors/metadata-error.md— Error codes