@rafaelsilvadeveloper/fast-media-tags

An ultra-lightweight, zero-dependency, and extremely fast binary ID3v2 tag parser for Node.js, Bun, Edge, and browser environments.

Features

• 🚀 High Performance: Parses ID3 tags by reading only the first few Kilobytes of the audio file, saving memory, bandwidth, and CPU cycles.
• 📦 Zero Dependencies: Pure TypeScript/JavaScript binary operations. Works out-of-the-box in Node.js, Bun, Edge/Serverless functions, and modern browsers.
• 🖼️ Album Art (APIC): Decodes cover photos (MIME type, format, type, description) and automatically exposes base64 and binary array data.
• 🛡️ TypeScript Definitions: Strongly typed return signatures.

Installation

npm install @rafaelsilvadeveloper/fast-media-tags

Usage

Reading tags from an ArrayBuffer

import { readAudioTags } from '@rafaelsilvadeveloper/fast-media-tags';

// In browser or bun
const buffer = await file.arrayBuffer();
const tags = await readAudioTags(buffer);

console.log(tags.title);  // 'Synthwave Dreams'
console.log(tags.artist); // 'CyberRunner'
console.log(tags.album);  // 'Grid Horizons'

Reading tags from a Blob / File (Browser or Bun)

import { readAudioTags } from '@rafaelsilvadeveloper/fast-media-tags';

// Directly pass a Blob or HTML5 File object
const tags = await readAudioTags(fileBlob);
if (tags.picture) {
  console.log(`Album Art format: ${tags.picture.format}`);
  // base64 ready for <img src="...">
  const imageSrc = tags.picture.base64;
}

Reading tags from a local File Path (Node.js & Bun)

import { readAudioTags } from '@rafaelsilvadeveloper/fast-media-tags';

const tags = await readAudioTags('./music/track.mp3');
console.log(`Title: ${tags.title}, Year: ${tags.year}`);

Supported Tags

• title (TIT2)
• artist (TPE1)
• album (TALB)
• year (TYER or TDRC)
• genre (TCON)
• picture (APIC)

Support

For support, questions, or discussions, join our Discord server:

License

MIT