taglib-wasm 0.1.0 → 0.2.4

package/README.md

@@ -1,18 +1,21 @@
 # taglib-wasm
 
-[TagLib](https://taglib.org/) is the de-facto standard library for reading and editing metadata tags (Title, Album, Artist, etc.) in all popular audio formats. See [“Goals & Features”](https://taglib.org/) for the reasons TagLib is so great.
+[TagLib](https://taglib.org/) is the most robust, de-facto standard for reading and editing metadata tags (Title, Album, Artist, etc.) in all popular audio formats. See [“Goals & Features”](https://taglib.org/) for the reasons TagLib is so great.
 
-`taglib-wasm` makes the robust, industry-standard TagLib tagging library available to browser, Deno, Node.js, and Bun apps for the first time, thanks to the magic of ✨[Wasm](https://webassembly.org/)✨ ([WebAssembly](https://webassembly.org/)).
+`taglib-wasm` is designed to be **TagLib for JavaScript/TypeScript** platforms — specifically Deno, Node.js, Bun, web browsers, and Cloudflare Workers. It does this by leveraging technologies including [TagLib](https://taglib.org/) itself, [Emscripten](https://emscripten.org/), and [Wasm](https://webassembly.org/) ([WebAssembly](https://webassembly.org/)).
 
-### Why?
+> [!NOTE]
+> I’m personally using this to solve a problem for another project I’m creating, but this project is still very much a baby. You may experience tantrums at this stage of `taglib-wasm`’s development.
 
-In the process of building my own utility to improve the metadata of my own music collection, I discovered that the JavaScipt/TypeScipt ecosystem has no battle-tested audio tagging library that supports reading and writing music metadata to all popular audio formats.
+## Why?
+
+In the process of building a utility to improve the metadata of my music collection, I discovered that the JavaScipt/TypeScipt ecosystem had no battle-tested audio tagging library that supports reading and writing music metadata to all popular audio formats.
 
 [`mp3tag.js`](https://mp3tag.js.org/) is mature and active, but only supports MP3 files and ID3 tags. TagLib was an ideal choice from a maturity and capabilities point of view, but wrappers like `node-taglib` appeared to be dormant, and I wanted to avoid making users install platform-specific dependencies whenever possible.
 
 ## 🎯 Features
 
-- **✅ Universal compatibility** – Works in browsers, Deno, Node.js, and Bun
+- **✅ Universal compatibility** – Works with Deno, Node.js, Bun, web browsers, and Cloudflare Workers
 - **✅ TypeScript first** – Complete type definitions and modern API
 - **✅ Full audio format support** – Supports all audio formats supported by TagLib
 - **✅ Format abstraction** – `taglib-wasm` deals with how tags are read from/written to in different file formats
@@ -22,23 +25,28 @@ In the process of building my own utility to improve the metadata of my own musi
 
 ## 📦 Installation
 
-```bash
-# For Deno projects
-import { TagLib } from "jsr:@taglib/wasm";
+### Deno
+
+```typescript
+import { TagLib } from "jsr:@charleswiltgen/taglib-wasm";
+```
 
-# For NPM/Node.js projects
+### Node.js
+
+```bash
 npm install taglib-wasm
+```
+### Bun
 
-# For Bun projects
+```bash
 bun add taglib-wasm
 ```
-
 ## 🚀 Quick Start
 
 ### Deno
 
 ```typescript
-import { TagLib } from "./src/mod.ts";
+import { TagLib } from "jsr:@charleswiltgen/taglib-wasm";
 
 // Initialize TagLib WASM
 const taglib = await TagLib.initialize();
@@ -63,7 +71,7 @@ file.setAlbum("New Album");
 
 console.log("Updated tags:", file.tag());
 
-// Advanced metadata (format-agnostic)
+// Automatic tag mapping (format-agnostic)
 file.setAcoustidFingerprint("AQADtMmybfGO8NCNEESLnzHyXNOHeHnG...");
 file.setAcoustidId("e7359e88-f1f7-41ed-b9f6-16e58e906997");
 file.setMusicBrainzTrackId("f4d1b6b8-8c1e-4d9a-9f2a-1234567890ab");
@@ -75,7 +83,7 @@ file.dispose();
 ### Bun
 
 ```typescript
-import { TagLib } from 'taglib-wasm';
+import { TagLib } from "taglib-wasm";
 
 // Initialize TagLib WASM
 const taglib = await TagLib.initialize();
@@ -100,7 +108,7 @@ file.setAlbum("New Album");
 
 console.log("Updated tags:", file.tag());
 
-// Advanced metadata (format-agnostic)
+// Automatic tag mapping (format-agnostic)
 file.setAcoustidFingerprint("AQADtMmybfGO8NCNEESLnzHyXNOHeHnG...");
 file.setAcoustidId("e7359e88-f1f7-41ed-b9f6-16e58e906997");
 file.setMusicBrainzTrackId("f4d1b6b8-8c1e-4d9a-9f2a-1234567890ab");
@@ -112,8 +120,8 @@ file.dispose();
 ### Node.js
 
 ```typescript
-import { TagLib } from 'taglib-wasm';
-import { readFile } from 'fs/promises';
+import { TagLib } from "taglib-wasm";
+import { readFile } from "fs/promises";
 
 // Initialize TagLib WASM
 const taglib = await TagLib.initialize();
@@ -138,7 +146,7 @@ file.setAlbum("New Album");
 
 console.log("Updated tags:", file.tag());
 
-// Advanced metadata (format-agnostic)
+// Automatic tag mapping (format-agnostic)
 file.setAcoustidFingerprint("AQADtMmybfGO8NCNEESLnzHyXNOHeHnG...");
 file.setAcoustidId("e7359e88-f1f7-41ed-b9f6-16e58e906997");
 file.setMusicBrainzTrackId("f4d1b6b8-8c1e-4d9a-9f2a-1234567890ab");
@@ -150,7 +158,7 @@ file.dispose();
 ### Browser
 
 ```typescript
-import { TagLib } from 'taglib-wasm';
+import { TagLib } from "taglib-wasm";
 
 // Initialize TagLib WASM
 const taglib = await TagLib.initialize();
@@ -177,7 +185,7 @@ file.setAlbum("New Album");
 
 console.log("Updated tags:", file.tag());
 
-// Advanced metadata (format-agnostic)
+// Automatic tag mapping (format-agnostic)
 file.setAcoustidFingerprint("AQADtMmybfGO8NCNEESLnzHyXNOHeHnG...");
 file.setAcoustidId("e7359e88-f1f7-41ed-b9f6-16e58e906997");
 file.setMusicBrainzTrackId("f4d1b6b8-8c1e-4d9a-9f2a-1234567890ab");
@@ -186,6 +194,61 @@ file.setMusicBrainzTrackId("f4d1b6b8-8c1e-4d9a-9f2a-1234567890ab");
 file.dispose();
 ```
 
+### Cloudflare Workers
+
+```typescript
+import { TagLib } from "taglib-wasm/workers";
+
+export default {
+  async fetch(request: Request): Promise<Response> {
+    if (request.method === "POST") {
+      try {
+        // Initialize TagLib WASM
+        const taglib = await TagLib.initialize({
+          memory: { initial: 8 * 1024 * 1024 }, // 8MB for Workers
+        });
+
+        // Get audio data from request
+        const audioData = new Uint8Array(await request.arrayBuffer());
+        const file = taglib.openFile(audioData);
+
+        // Read metadata
+        const tags = file.tag();
+        const props = file.audioProperties();
+
+        // Extract metadata
+        const metadata = {
+          title: tags.title,
+          artist: tags.artist,
+          album: tags.album,
+          year: tags.year,
+          genre: tags.genre,
+          duration: props.length,
+          bitrate: props.bitrate,
+          format: file.format(),
+        };
+
+        // Clean up
+        file.dispose();
+
+        return Response.json({
+          success: true,
+          metadata,
+          fileSize: audioData.length,
+        });
+      } catch (error) {
+        return Response.json({
+          error: "Failed to process audio file",
+          message: (error as Error).message,
+        }, { status: 500 });
+      }
+    }
+
+    return new Response("Send POST request with audio file", { status: 400 });
+  },
+};
+```
+
 ## 📋 Supported Formats
 
 All formats are **fully tested and working**:
@@ -197,11 +260,12 @@ All formats are **fully tested and working**:
 - ✅ **WAV** – INFO chunk metadata
 - 🔄 **Additional formats**: Opus, APE, MPC, WavPack, TrueAudio, and more
 
-## 🎯 Advanced Metadata Support
+## 🎯 Automatic Tag Mapping
 
-TagLib WASM supports **format-agnostic tag naming** so you don’t have to worry about how the same tag is stored differently in different audio container formats.
+TagLib WASM supports **automatic tag mapping** so you don’t have to worry about how the same tag is stored differently in different audio container formats.
 
 ### AcoustID example
+
 ```typescript
 // Single API works for ALL formats (MP3, FLAC, OGG, MP4)
 file.setAcoustidFingerprint("AQADtMmybfGO8NCNEESLnzHyXNOHeHnG...");
@@ -214,6 +278,7 @@ file.setAcoustidId("e7359e88-f1f7-41ed-b9f6-16e58e906997");
 ```
 
 ### MusicBrainz example
+
 ```typescript
 // Professional music database integration
 file.setMusicBrainzTrackId("f4d1b6b8-8c1e-4d9a-9f2a-1234567890ab");
@@ -222,6 +287,7 @@ file.setMusicBrainzArtistId("12345678-90ab-cdef-1234-567890abcdef");
 ```
 
 ### Volume example
+
 ```typescript
 // ReplayGain support (automatic format mapping)
 file.setReplayGainTrackGain("-6.54 dB");
@@ -234,6 +300,7 @@ file.setAppleSoundCheck("00000150 00000150 00000150 00000150...");
 ```
 
 ### Extended fields
+
 ```typescript
 // Advanced metadata fields
 file.setExtendedTag({
@@ -249,7 +316,7 @@ file.setExtendedTag({
 });
 ```
 
-**📖 See [ADVANCED_METADATA.md](ADVANCED_METADATA.md) for complete documentation**
+**📖 See [docs/Automatic-Tag-Mapping.md](docs/Automatic-Tag-Mapping.md) for complete documentation**
 
 ## 🏗️ Development
 
@@ -272,7 +339,7 @@ deno task test
 
 ### Project Structure
 
-```
+```text
 src/
 ├── mod.ts          # Main module exports
 ├── taglib.ts       # Core TagLib and AudioFile classes
@@ -284,7 +351,7 @@ build/
 ├── taglib.js       # Generated Emscripten JavaScript
 └── taglib.wasm     # Compiled WebAssembly module
 
-test-files/         # Sample audio files for testing
+tests/              # Test files and sample audio files
 tests/              # Test suite
 examples/           # Usage examples for different runtimes
 ├── deno/           # Deno-specific examples
@@ -307,12 +374,12 @@ bun run test-systematic.ts
 # Run with Node.js
 npm test
 
-# Results: 5/5 formats working ✅ across all runtimes
-# ✅ WAV  - 44.1kHz, stereo, tag reading/writing
-# ✅ MP3  - 44.1kHz, stereo, ID3 tag support
-# ✅ FLAC - 44.1kHz, stereo, Vorbis comments
-# ✅ OGG  - 44.1kHz, stereo, Vorbis comments
-# ✅ M4A  - 44.1kHz, stereo, iTunes metadata
+# Results: All formats working ✅ across all runtimes
+# ✅ WAV  - INFO chunk metadata support
+# ✅ MP3  - ID3v1/v2 tag support
+# ✅ FLAC - Vorbis comments and properties
+# ✅ OGG  - Vorbis comments
+# ✅ M4A  - iTunes-compatible metadata atoms
 ```
 
 ## 🔧 Technical Implementation
@@ -337,9 +404,9 @@ npm test
 
 ```typescript
 class TagLib {
-  static async initialize(config?: TagLibConfig): Promise<TagLib>
-  openFile(buffer: Uint8Array): AudioFile
-  getModule(): TagLibModule
+  static async initialize(config?: TagLibConfig): Promise<TagLib>;
+  openFile(buffer: Uint8Array): AudioFile;
+  getModule(): TagLibModule;
 }
 ```
 
@@ -348,51 +415,51 @@ class TagLib {
 ```typescript
 class AudioFile {
   // Validation
-  isValid(): boolean
-  format(): string
+  isValid(): boolean;
+  format(): string;
 
   // Properties
-  audioProperties(): AudioProperties
-  tag(): TagData
+  audioProperties(): AudioProperties;
+  tag(): TagData;
 
   // Tag Writing
-  setTitle(title: string): void
-  setArtist(artist: string): void
-  setAlbum(album: string): void
-  setComment(comment: string): void
-  setGenre(genre: string): void
-  setYear(year: number): void
-  setTrack(track: number): void
+  setTitle(title: string): void;
+  setArtist(artist: string): void;
+  setAlbum(album: string): void;
+  setComment(comment: string): void;
+  setGenre(genre: string): void;
+  setYear(year: number): void;
+  setTrack(track: number): void;
 
   // File Operations
-  save(): boolean
-  dispose(): void
+  save(): boolean;
+  dispose(): void;
 
-  // Advanced Metadata (Format-Agnostic)
-  extendedTag(): ExtendedTag
-  setExtendedTag(tag: Partial<ExtendedTag>): void
+  // Automatic Tag Mapping (Format-Agnostic)
+  extendedTag(): ExtendedTag;
+  setExtendedTag(tag: Partial<ExtendedTag>): void;
 
   // AcoustID Integration
-  setAcoustidFingerprint(fingerprint: string): void
-  getAcoustidFingerprint(): string | undefined
-  setAcoustidId(id: string): void
-  getAcoustidId(): string | undefined
+  setAcoustidFingerprint(fingerprint: string): void;
+  getAcoustidFingerprint(): string | undefined;
+  setAcoustidId(id: string): void;
+  getAcoustidId(): string | undefined;
 
   // MusicBrainz Integration
-  setMusicBrainzTrackId(id: string): void
-  getMusicBrainzTrackId(): string | undefined
+  setMusicBrainzTrackId(id: string): void;
+  getMusicBrainzTrackId(): string | undefined;
 
   // Volume Normalization
-  setReplayGainTrackGain(gain: string): void
-  getReplayGainTrackGain(): string | undefined
-  setReplayGainTrackPeak(peak: string): void
-  getReplayGainTrackPeak(): string | undefined
-  setReplayGainAlbumGain(gain: string): void
-  getReplayGainAlbumGain(): string | undefined
-  setReplayGainAlbumPeak(peak: string): void
-  getReplayGainAlbumPeak(): string | undefined
-  setAppleSoundCheck(iTunNORM: string): void
-  getAppleSoundCheck(): string | undefined
+  setReplayGainTrackGain(gain: string): void;
+  getReplayGainTrackGain(): string | undefined;
+  setReplayGainTrackPeak(peak: string): void;
+  getReplayGainTrackPeak(): string | undefined;
+  setReplayGainAlbumGain(gain: string): void;
+  getReplayGainAlbumGain(): string | undefined;
+  setReplayGainAlbumPeak(peak: string): void;
+  getReplayGainAlbumPeak(): string | undefined;
+  setAppleSoundCheck(iTunNORM: string): void;
+  getAppleSoundCheck(): string | undefined;
 }
 ```
 
@@ -401,10 +468,10 @@ class AudioFile {
 ```typescript
 interface TagLibConfig {
   memory?: {
-    initial?: number;  // Initial memory size (default: 16MB)
-    maximum?: number;  // Maximum memory size (default: 256MB)
+    initial?: number; // Initial memory size (default: 16MB)
+    maximum?: number; // Maximum memory size (default: 256MB)
   };
-  debug?: boolean;     // Enable debug output
+  debug?: boolean; // Enable debug output
 }
 ```
 
@@ -412,14 +479,14 @@ interface TagLibConfig {
 
 TagLib WASM works seamlessly across all major JavaScript runtimes:
 
-| Runtime | Status | Installation | Performance | TypeScript |
-|---------|--------|--------------|-------------|------------|
-| **Deno** | ✅ Full | `jsr:@taglib/wasm` | Excellent | Native |
-| **Bun** | ✅ Full | `bun add taglib-wasm` | Excellent | Native |
-| **Node.js** | ✅ Full | `npm install taglib-wasm` | Good | Via loader |
-| **Browser** | ✅ Full | CDN/bundler | Good | Via build |
+| Runtime     | Status  | Installation                      | Performance | TypeScript |
+| ----------- | ------- | --------------------------------- | ----------- | ---------- |
+| **Deno**    | ✅ Full | `jsr:@charleswiltgen/taglib-wasm` | Excellent   | Native     |
+| **Bun**     | ✅ Full | `bun add taglib-wasm`             | Excellent   | Native     |
+| **Node.js** | ✅ Full | `npm install taglib-wasm`         | Good        | Via loader |
+| **Browser** | ✅ Full | CDN/bundler                       | Good        | Via build  |
 
-**📖 See [RUNTIME_COMPATIBILITY.md](RUNTIME_COMPATIBILITY.md) for detailed runtime information**
+**📖 See [docs/Runtime-Compatibility.md](docs/Runtime-Compatibility.md) for detailed runtime information**
 
 ## 🚧 Known Limitations
 
@@ -446,7 +513,3 @@ Contributions welcome! Areas of interest:
 
 - [TagLib](https://taglib.org/) – Excellent audio metadata library
 - [Emscripten](https://emscripten.org/) – WebAssembly compilation toolchain
-
----
-
-**Status**: Production Ready - Universal audio metadata handling across all JavaScript runtimes.

package/index.ts

@@ -0,0 +1,21 @@
+/**
+ * @fileoverview Main module exports for TagLib WASM
+ *
+ * TagLib v2.1 compiled to WebAssembly with TypeScript bindings
+ * for universal audio metadata handling.
+ */
+
+export { AudioFile, TagLib } from "./src/taglib.ts";
+export type {
+  AudioFormat,
+  AudioProperties,
+  ExtendedTag,
+  FieldMapping,
+  METADATA_MAPPINGS,
+  Picture,
+  PictureType,
+  PropertyMap,
+  Tag,
+  TagLibConfig,
+} from "./src/types.ts";
+export type { TagLibModule } from "./src/wasm.ts";

package/package.json

@@ -1,10 +1,15 @@
 {
   "name": "taglib-wasm",
-  "version": "0.1.0",
+  "version": "0.2.4",
   "description": "TagLib compiled to WebAssembly with TypeScript bindings for universal audio metadata handling",
-  "main": "src/mod.ts",
-  "types": "src/mod.ts",
+  "main": "index.ts",
+  "types": "index.ts",
+  "exports": {
+    ".": "./index.ts",
+    "./workers": "./src/workers.ts"
+  },
   "files": [
+    "index.ts",
     "src/**/*",
     "build/taglib.wasm",
     "build/taglib.js",
@@ -15,13 +20,14 @@
     "build:wasm": "./build/build-wasm.sh",
     "build:ts": "tsc",
     "build": "npm run build:wasm && npm run build:ts",
-    "test": "deno run --allow-read test-systematic.ts",
-    "test:bun": "bun run test-systematic.ts", 
-    "test:node": "node --loader ts-node/esm test-systematic.ts",
+    "test": "deno run --allow-read tests/test-systematic.ts",
+    "test:bun": "bun run tests/test-systematic.ts",
+    "test:node": "node --loader ts-node/esm tests/test-systematic.ts",
     "update-taglib": "./scripts/update-taglib.sh",
-    "publish:npm": "npm publish",
-    "publish:jsr": "deno publish",
-    "publish:all": "npm run publish:npm && npm run publish:jsr"
+    "publish:npm": "echo 'Use GitHub Actions workflow for publishing'",
+    "publish:github": "echo 'Use GitHub Actions workflow for publishing'",
+    "publish:jsr": "echo 'Use GitHub Actions workflow for publishing'",
+    "publish:all": "echo 'Use GitHub Actions workflow for publishing'"
   },
   "keywords": [
     "taglib",
@@ -37,6 +43,8 @@
     "deno",
     "node",
     "browser",
+    "cloudflare",
+    "workers",
     "replaygain",
     "musicbrainz",
     "acoustid"
@@ -45,7 +53,10 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/CharlesWiltgen/taglib-wasm.git"
+    "url": "git+https://github.com/CharlesWiltgen/taglib-wasm.git"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/"
   },
   "bugs": {
     "url": "https://github.com/CharlesWiltgen/taglib-wasm/issues"