metadata-connect

Extract audio metadata from MP3, M4A, FLAC, and AIFF files with support for partial file reads - perfect for extracting metadata from remote files over the network without downloading entire files.

Features

• Partial file reading - Extract metadata by reading only file headers (10-200KB instead of entire files)
• Multiple format support - MP3 (ID3v2), M4A/MP4/AAC, FLAC, AIFF
• Complete metadata extraction - Title, artist, album, genre, year, BPM, key, and artwork
• FileReader abstraction - Works with any data source (local files, NFS, HTTP range requests, custom protocols)
• Zero runtime dependencies - Pure TypeScript implementation
• TypeScript first - Full type definitions included

Installation

npm install metadata-connect

Quick Start

Extract from a local file

import { extractMetadata, createBufferReader } from 'metadata-connect';
import { readFile } from 'fs/promises';

const buffer = await readFile('song.mp3');
const reader = createBufferReader(buffer, 'mp3');
const metadata = await extractMetadata(reader);

if (metadata) {
  console.log(metadata.title);   // "Song Title"
  console.log(metadata.artist);  // "Artist Name"
  console.log(metadata.bpm);     // 128
  console.log(metadata.key);     // "Am"

  if (metadata.artwork) {
    // metadata.artwork is a Buffer
    // metadata.artworkMimeType is 'image/jpeg' | 'image/png' | 'image/gif'
  }
}

Extract from a remote file (partial read)

The real power of metadata-connect is extracting metadata from remote files without downloading them entirely:

import { extractMetadata } from 'metadata-connect';
import type { FileReader } from 'metadata-connect';

// Create a FileReader that fetches only the requested bytes
const reader: FileReader = {
  size: fileSize, // Total file size (get from HEAD request or file stat)
  extension: 'mp3',
  async read(offset: number, length: number): Promise<Buffer> {
    // Use HTTP Range requests, NFS, or any protocol
    const response = await fetch(url, {
      headers: { Range: `bytes=${offset}-${offset + length - 1}` }
    });
    return Buffer.from(await response.arrayBuffer());
  }
};

const metadata = await extractMetadata(reader);

API Reference

extractMetadata(reader: FileReader): Promise<ExtractedMetadata | null>

Main extraction function. Returns metadata or null if the format is not supported or parsing fails.

createBufferReader(buffer: Buffer, extension: string): FileReader

Create a FileReader from a Buffer for in-memory extraction.

isExtensionSupported(extension: string): boolean

Check if a file extension is supported.

getSupportedExtensions(): string[]

Get list of supported extensions: ['mp3', 'm4a', 'mp4', 'aac', 'flac', 'aiff', 'aif']

getParserForExtension(extension: string): MetadataParser | null

Get the parser function for a specific extension.

Types

FileReader

interface FileReader {
  /** Total file size in bytes */
  readonly size: number;
  /** File extension (without dot), e.g., 'mp3', 'flac' */
  readonly extension: string;
  /** Read bytes from the file at a given offset */
  read(offset: number, length: number): Promise<Buffer>;
}

ExtractedMetadata

interface ExtractedMetadata {
  title?: string;
  artist?: string;
  album?: string;
  genre?: string;
  year?: number;
  bpm?: number;
  key?: string;
  artwork?: Buffer;
  artworkMimeType?: 'image/jpeg' | 'image/png' | 'image/gif';
}

Format Support

Format	Extension	Metadata Source
MP3	.mp3	ID3v2.2, ID3v2.3, ID3v2.4 tags
M4A/MP4	.m4a, .mp4, .aac	iTunes metadata atoms
FLAC	.flac	Vorbis comments + PICTURE blocks
AIFF	.aiff, .aif	ID3 chunk

Extracted Fields

Field	MP3	M4A	FLAC	AIFF
Title	TIT2	©nam	TITLE	ID3
Artist	TPE1	©ART	ARTIST	ID3
Album	TALB	©alb	ALBUM	ID3
Genre	TCON	©gen/gnre	GENRE	ID3
Year	TYER/TDRC	©day	DATE	ID3
BPM	TBPM	tmpo	BPM/TEMPO	ID3
Key	TKEY	-	KEY/INITIALKEY	ID3
Artwork	APIC	covr	PICTURE	ID3

Network Efficiency

The library is designed to minimize network transfer when reading from remote sources:

Format	Typical Bytes Read
MP3	10-50 KB (ID3v2 tag at file start)
FLAC	10 KB (metadata blocks at file start)
M4A/MP4	50-200 KB (atom tree traversal)
AIFF	10-50 KB (ID3 chunk location varies)

Use Cases

• DJ Software - Extract track info from CDJs/controllers over network protocols
• Media Servers - Index large music libraries without reading entire files
• Streaming Services - Quick metadata lookup for remote storage
• Browser Applications - Extract metadata using fetch with Range headers

Advanced Usage

Using Individual Parsers

import { extractFromMp3, extractFromMp4, extractFromFlac } from 'metadata-connect';

// Use specific parser directly
const metadata = await extractFromMp3(reader);

Detecting Image Types

import { detectImageType } from 'metadata-connect';

const mimeType = detectImageType(imageBuffer);
// Returns 'image/jpeg' | 'image/png' | 'image/gif' | null

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT License - see LICENSE for details.

Related Packages

• alphatheta-connect — Pioneer Pro DJ Link integration
• stagelinq — Denon StageLinq protocol integration
• rekordbox-connect — Rekordbox database integration
• serato-connect — Serato DJ integration

These libraries power Now Playing — a real-time track display app for DJs and streamers.

See Also

• music-metadata - Full-featured audio metadata library (requires full file access)
• node-id3 - ID3 tag reader/writer for Node.js