TagLib-Wasm

TagLib-Wasm is the universal tagging library for TypeScript/JavaScript (TS|JS) platforms: Deno, Node.js, Bun, Cloudflare Workers, Electron (via Node.js), and browsers.

Features

• Local filesystem support – On Deno and Node.js, WASI enables seek-based I/O that reads only headers and tags from disk — not entire files
• Automatic runtime optimization – Auto-selects WASI (server) or Emscripten (browser) for optimal performance with no configuration
• Full audio format support – Supports all audio formats supported by TagLib
• TypeScript first – Complete type definitions and modern API
• Wide TS/JS runtime support – Deno, Node.js, Bun, Electron (Node.js), Cloudflare Workers, and browsers
• Format abstraction – Handles container format details automatically when possible
• Zero dependencies – Self-contained Wasm bundle
• Tested – 135+ tests across all formats
• Two API styles – Use the "Simple" API (3 functions), or the full "Core" API for more advanced applications
• Batch folder operations – Scan directories, process multiple files, find duplicates, and export metadata catalogs

Installation

Deno

import { TagLib } from "@charlesw/taglib-wasm";

Node.js

npm install taglib-wasm

Note: Requires Node.js v22.6.0 or higher. If you want to use the TypeScript version with Node.js, see the installation guide.

Bun

bun add taglib-wasm

Electron (Node.js)

npm install taglib-wasm

taglib-wasm works in Electron's main process (which is Node.js). For the renderer process, expose metadata through IPC:

// Main process
import { TagLib } from "taglib-wasm";

See Platform Examples for full IPC setup.

Deno Compiled Binaries (Offline Support)

For Deno compiled binaries that need to work offline, you can embed the WASM file:

// 1. Prepare your build by copying the WASM file
import { prepareWasmForEmbedding } from "@charlesw/taglib-wasm";
await prepareWasmForEmbedding("./taglib.wasm");

// 2. In your application, use the helper for automatic handling
import { initializeForDenoCompile } from "@charlesw/taglib-wasm";
const taglib = await initializeForDenoCompile();

// 3. Compile with the embedded WASM
// deno compile --allow-read --include taglib.wasm myapp.ts

See the complete Deno compile guide for more options including CDN loading.

For manual control:

// Load embedded WASM in compiled binaries
const wasmBinary = await Deno.readFile(
  new URL("./taglib.wasm", import.meta.url),
);
const taglib = await TagLib.initialize({ wasmBinary });

Quick Start

Import paths: Deno uses @charlesw/taglib-wasm, npm uses taglib-wasm. Examples below use npm paths — substitute accordingly.

Simple API

import {
  applyTagsToBuffer,
  readTags,
  writeTagsToFile,
} from "taglib-wasm/simple";

// Read tags
const tags = await readTags("song.mp3");
console.log(tags.title, tags.artist, tags.album);

// Apply tags and get modified buffer (in-memory)
const modifiedBuffer = await applyTagsToBuffer("song.mp3", {
  title: "New Title",
  artist: "New Artist",
  album: "New Album",
});

// Or update tags on disk (requires file path)
await writeTagsToFile("song.mp3", {
  title: "New Title",
  artist: "New Artist",
});

High-Performance Batch Processing

import { readMetadataBatch, readTagsBatch } from "taglib-wasm/simple";

// Process multiple files in parallel
const files = ["track01.mp3", "track02.mp3", /* ... */ "track20.mp3"];

// Read just tags (18x faster than sequential)
const tags = await readTagsBatch(files, { concurrency: 8 });

// Read complete metadata including cover art detection (15x faster)
const metadata = await readMetadataBatch(files, { concurrency: 8 });

// Real-world performance:
// Sequential: ~100 seconds for 20 files
// Batch: ~5 seconds for 20 files (20x speedup!)

Full API

The Full API might be a better choice for apps and utilities focused on advanced metadata management.

import { TagLib } from "taglib-wasm";

// Initialize taglib-wasm
const taglib = await TagLib.initialize();

// Load audio file (automatically cleaned up when scope exits)
using file = await taglib.open("song.mp3");

// Read and update metadata
const tag = file.tag();
tag.setTitle("New Title");
tag.setArtist("New Artist");

// Save changes
file.save();

Batch Folder Operations

Process entire music collections efficiently:

import { findDuplicates, scanFolder } from "taglib-wasm";

// Scan a music library
const result = await scanFolder("/path/to/music", {
  recursive: true,
  concurrency: 4,
  onProgress: (processed, total, file) => {
    console.log(`Processing ${processed}/${total}: ${file}`);
  },
});

console.log(`Found ${result.totalFound} audio files`);
console.log(`Successfully processed ${result.totalProcessed} files`);

// Process results
for (const file of result.files) {
  console.log(`${file.path}: ${file.tags.artist} - ${file.tags.title}`);
  console.log(`Duration: ${file.properties?.duration}s`);
}

// Find duplicates
const duplicates = await findDuplicates("/path/to/music", {
  criteria: ["artist", "title"],
});
console.log(`Found ${duplicates.size} groups of duplicates`);

Working with Cover Art

import { applyCoverArt, readCoverArt } from "taglib-wasm/simple";

// Extract cover art
const coverData = await readCoverArt("song.mp3");
if (coverData) {
  await Deno.writeFile("cover.jpg", coverData);
}

// Set new cover art
const imageData = await Deno.readFile("new-cover.jpg");
const modifiedBuffer = await applyCoverArt("song.mp3", imageData, "image/jpeg");
// Save modifiedBuffer to file if needed

Working with Ratings

import { RatingUtils, TagLib } from "taglib-wasm";

const taglib = await TagLib.initialize();
using file = await taglib.open("song.mp3");

// Read rating (normalized 0.0-1.0)
const rating = file.getRating();
if (rating !== undefined) {
  console.log(`Rating: ${RatingUtils.toStars(rating)} stars`);
}

// Set rating (4 out of 5 stars)
file.setRating(0.8);
file.save();

See the Track Ratings Guide for RatingUtils API and cross-format conversion details.

Container Format and Codec Detection

import { readProperties } from "taglib-wasm/simple";

// Get detailed audio properties including container and codec info
const props = await readProperties("song.m4a");

console.log(props.containerFormat); // "MP4" (container format)
console.log(props.codec); // "AAC" or "ALAC" (compressed media format)
console.log(props.isLossless); // false for AAC, true for ALAC
console.log(props.bitsPerSample); // 16 for most formats
console.log(props.bitrate); // 256 (kbps)
console.log(props.sampleRate); // 44100 (Hz)
console.log(props.length); // 180 (duration in seconds)

Container format vs Codec:

• Container format – How audio data and metadata are packaged (e.g., MP4, OGG)
• Codec – How audio is compressed/encoded (e.g., AAC, Vorbis)

Supported formats:

• MP4 container (.mp4, .m4a) – Can contain AAC (lossy) or ALAC (lossless)
• OGG container (.ogg) – Can contain Vorbis, Opus, FLAC, or Speex
• MP3 – Both container and codec (lossy)
• FLAC – Both container and codec (lossless)
• WAV – Container for PCM (uncompressed) audio
• AIFF – Container for PCM (uncompressed) audio

Documentation

View Full Documentation

Getting Started

• Installation Guide
• Quick Start Tutorial
• All Examples

Guides

• API Reference
• Performance Guide
• Album Processing Guide
• Platform Examples
• Working with Cover Art
• Track Ratings
• Cloudflare Workers
• Error Handling
• Contributing

Supported Formats

taglib-wasm is designed to support all formats supported by TagLib:

• .mp3 – ID3v2 and ID3v1 tags
• .m4a/.mp4 – MPEG-4/AAC metadata for AAC and Apple Lossless audio
• .flac – Vorbis comments and audio properties
• .ogg – Ogg Vorbis format with full metadata support
• .wav – INFO chunk metadata
• Additional formats – Opus, APE, MPC, WavPack, TrueAudio, AIFF, WMA, and more

Performance and Best Practices

Batch Processing for Multiple Files

When processing multiple audio files, use the optimized batch APIs for better performance:

import { readMetadataBatch, readTagsBatch } from "taglib-wasm/simple";

// Processing files one by one (can take 90+ seconds for 19 files)
for (const file of files) {
  const tags = await readTags(file); // Re-initializes for each file
}

// Batch processing (10-20x faster)
const result = await readTagsBatch(files, {
  concurrency: 8, // Process 8 files in parallel
  onProgress: (processed, total) => {
    console.log(`${processed}/${total} files processed`);
  },
});

// Read complete metadata in one batch
const metadata = await readMetadataBatch(files, { concurrency: 8 });

Performance comparison for 19 audio files:

• Sequential: ~90 seconds (4.7s per file)
• Batch (concurrency=4): ~8 seconds (11x faster)
• Batch (concurrency=8): ~5 seconds (18x faster)

Smart Partial Loading

For large audio files (>50MB), enable partial loading to reduce memory usage:

// Enable partial loading for large files
using file = await taglib.open("large-concert.flac", {
  partial: true,
  maxHeaderSize: 2 * 1024 * 1024, // 2MB header
  maxFooterSize: 256 * 1024, // 256KB footer
});

// Read operations work normally
const tags = file.tag();
console.log(tags.title, tags.artist);

// Smart save - automatically loads full file when needed
await file.saveToFile(); // Full file loaded only here

Performance gains:

• 500MB file: ~450x less memory usage (1.1MB vs 500MB)
• Initial load: 50x faster (50ms vs 2500ms)
• Memory peak: 3.3MB instead of 1.5GB

Runtime Optimization Tiers

taglib-wasm auto-selects the fastest available backend — no configuration needed:

Environment	Backend	How it works	Performance
Deno / Node.js / Bun	WASI (auto)	Seek-based filesystem I/O; reads only headers and tags	Fastest
Browsers / Workers	Emscripten (auto)	Entire file loaded into memory as buffer	Baseline
Opt-in	Wasmtime sidecar	Out-of-process WASI with direct filesystem access	Best for batch

On Deno, Node.js, and Bun you get WASI automatically — nothing to configure. For heavy batch workloads, the optional Wasmtime sidecar provides direct filesystem access via a sandboxed subprocess:

# Optional: Install Wasmtime for sidecar mode
curl https://wasmtime.dev/install.sh -sSf | bash

import { readTags, setSidecarConfig } from "taglib-wasm/simple";

// Enable sidecar mode (requires Wasmtime)
await setSidecarConfig({
  preopens: { "/music": "/home/user/Music" },
});

// Now path-based calls use direct WASI filesystem access
const tags = await readTags("/music/song.mp3");

See the Runtime Compatibility Guide for full sidecar configuration options.

Runtime Compatibility

taglib-wasm works across all major JavaScript runtimes:

Runtime	Status	Installation	Notes
Deno	Full	npm:taglib-wasm	Native TypeScript
Node.js	Full	npm install taglib-wasm	TypeScript via tsx
Bun	Partial	bun add taglib-wasm	Import + init verified; full test suite is Deno-only
Browser	Full	Via bundler	Full API support
Cloudflare Workers	Full	npm install taglib-wasm	Same unified API; see Workers guide
Electron	Node.js	npm install taglib-wasm	Main process; renderer via IPC

Known Limitations

• Memory Usage (browsers) – In browser environments, entire files are loaded into memory. On Deno/Node.js, WASI reads only headers and tags from disk.
• Concurrent Access – Not thread-safe (JavaScript single-threaded nature mitigates this)

Contributing

Contributions are welcome! Please read our Contributing Guide for details on our code of conduct and the process for submitting pull requests.

License

This project uses dual licensing:

• TypeScript/JavaScript code – MIT License (see LICENSE)
• WebAssembly binary (taglib.wasm) – LGPL-2.1-or-later (inherited from TagLib)

The TagLib library is dual-licensed under LGPL/MPL. When compiled to WebAssembly, the resulting binary must comply with LGPL requirements. This means:

• You can use taglib-wasm in commercial projects
• If you modify the TagLib C++ code, you must share those changes
• You must provide a way for users to relink with a modified TagLib

For details, see lib/taglib/COPYING.LGPL

Acknowledgments

• TagLib – Excellent audio metadata library
• Emscripten – WebAssembly compilation toolchain
• WASI – WebAssembly System Interface for server-side runtimes