Examples

This guide provides an overview of all taglib-wasm examples and how to run them across different JavaScript runtimes.

Example Categories

Common Examples

The examples/common/ directory contains runtime-agnostic examples that demonstrate core functionality:

• basic-usage.ts - Basic tag reading and writing operations
• simple-api.ts - Using the simplified high-level API
• automatic-tag-mapping.ts - Format-agnostic metadata handling
• replaygain-soundcheck.ts - Volume normalization metadata
• tag-constants.ts - Using type-safe tag constants
• embind-example.ts - Direct usage of the Embind-based low-level API

Runtime-Specific Examples

• browser/ - Browser-specific implementations
• node/ - Node.js-specific patterns
• bun/ - Bun runtime examples
• deno/ - Deno runtime examples
• workers/ - Cloudflare Workers serverless deployment

Running Examples

Prerequisites

First, ensure you have taglib-wasm installed:

# NPM/Node.js/Bun
npm install taglib-wasm

# Deno
import { TagLib } from "npm:taglib-wasm";

Running Common Examples

The examples in common/ can be run in any runtime. When running locally, you may need to build the project first:

# Build the project (if running from source)
npm run build

Deno

deno run --allow-read examples/common/basic-usage.ts

Node.js

# TypeScript files need to be compiled first
npm run build:ts
node dist/examples/common/basic-usage.js

# Or use tsx for direct execution
npx tsx examples/common/basic-usage.ts

Bun

bun examples/common/basic-usage.ts

Platform-Specific Examples

See the Platform Examples guide for detailed instructions on running examples in specific environments.

Example Highlights

Basic Tag Operations

The basic-usage.ts example shows fundamental operations:

import { TagLib } from "taglib-wasm";

// Initialize the library
const taglib = await TagLib.load();

// Read an audio file
const audioFile = taglib.openFile(audioBuffer);

// Read tags
const tag = audioFile.getTag();
console.log(`Title: ${tag.title()}`);
console.log(`Artist: ${tag.artist()}`);

// Modify tags
tag.setTitle("New Title");
tag.setArtist("New Artist");

// Save changes
audioFile.save();
const modifiedBuffer = audioFile.getFileBuffer();

// Clean up
audioFile.dispose();

Simple API

The simple-api.ts example demonstrates the high-level API:

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

// Read tags
const metadata = await readTags(audioBuffer);
console.log(metadata);

// Write tags
const modifiedBuffer = await applyTags(audioBuffer, {
  title: "New Title",
  artist: "New Artist",
  album: "New Album",
});

Format-Agnostic Metadata

The automatic-tag-mapping.ts example shows how taglib-wasm handles metadata across different formats:

// Works the same for MP3, FLAC, M4A, etc.
const tags = {
  MUSICBRAINZ_TRACKID: "550e8400-e29b-41d4-a716-446655440000",
  REPLAYGAIN_TRACK_GAIN: "-6.5 dB",
  ACOUSTID_ID: "12345678-1234-1234-1234-123456789012",
};

// TagLib automatically maps to the correct format-specific fields
const modifiedBuffer = await applyTags(audioBuffer, tags);

Import Paths

When using taglib-wasm in your own project, replace the example import paths:

// Examples use relative imports (for development)
import { TagLib } from "../../src/taglib.js";

// Your project should use package imports
import { TagLib } from "taglib-wasm"; // NPM
import { TagLib } from "npm:taglib-wasm"; // Deno

Next Steps

• Check out the Platform Examples for runtime-specific patterns
• See the Cloudflare Workers Setup for serverless deployment
• Read the API Reference for detailed documentation
• Explore Cover Art handling for working with embedded images