taglib-wasm 0.2.7 → 0.3.1

package/README.md

@@ -1,17 +1,14 @@
 # taglib-wasm
 
-[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.
+This is the Wasm version of [**TagLib**](https://taglib.org/), the most robust, de-facto standard for reading and editing metadata tags (Title, Album, Artist, etc.) in all popular audio formats. `taglib-wasm` exists because the JavaScipt/TypeScipt ecosystem had no battle-tested audio tagging library that supports reading and writing music metadata to all popular audio formats — until now!
 
-`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/)).
+`taglib-wasm` stands on the shoulders of giants, including [TagLib](https://taglib.org/) itself, [Emscripten](https://emscripten.org/), and [Wasm](https://webassembly.org/) ([WebAssembly](https://webassembly.org/)).
 
-> [!NOTE]
-> This project is a baby, and you’re likely to experience some surprises at this stage of its development. I’m extremely moditivated to help address them, though.
+`taglib-wasm` aspires to be a universal solution for **JavaScript/TypeScript** platforms — Deno, Node.js, Bun, web browsers, and Cloudflare Workers. Note: This project is a baby, and you’re likely to experience some surprises at this stage of its development. I’m extremely motivated to help address them, since I’ll also be depending on this project.
 
-## Why?
+## 🤔 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.
+Because there’s nothing like it. [`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
 
@@ -29,7 +26,7 @@ In the process of building a utility to improve the metadata of my music collect
 ### Deno
 
 ```typescript
-import { TagLib } from "jsr:@charleswiltgen/taglib-wasm";
+import { TagLib } from "npm:taglib-wasm";
 ```
 
 ### Node.js
@@ -38,6 +35,13 @@ import { TagLib } from "jsr:@charleswiltgen/taglib-wasm";
 npm install taglib-wasm
 ```
 
+**Note:** The NPM package ships TypeScript source files. Use a TypeScript loader like [`tsx`](https://github.com/privatenumber/tsx):
+
+```bash
+npm install --save-dev tsx
+npx tsx your-script.ts
+```
+
 ### Bun
 
 ```bash
@@ -74,13 +78,13 @@ console.log(`Duration: ${props.length}s, Bitrate: ${props.bitrate} kbps`);
 Full control when you need it:
 
 ```typescript
-import { TagLib } from "jsr:@charleswiltgen/taglib-wasm";
+import { TagLib } from "taglib-wasm";
 
 // Initialize taglib-wasm
 const taglib = await TagLib.initialize();
 
 // Load audio file from buffer
-const audioData = await Deno.readFile("song.mp3");
+const audioData = await readFile("song.mp3"); // Node.js/Bun: fs.readFile, Deno: Deno.readFile
 const file = taglib.openFile(audioData);
 
 // Read metadata
@@ -93,16 +97,15 @@ console.log(`Duration: ${props.length}s`);
 console.log(`Bitrate: ${props.bitrate} kbps`);
 
 // Write metadata
-file.setTitle("New Title");
-file.setArtist("New Artist");
-file.setAlbum("New Album");
+const tag = file.tag();
+tag.setTitle("New Title");
+tag.setArtist("New Artist");
+tag.setAlbum("New Album");
 
-console.log("Updated tags:", file.tag());
+// Save changes
+file.save();
 
-// Automatic tag mapping (format-agnostic)
-file.setAcoustidFingerprint("AQADtMmybfGO8NCNEESLnzHyXNOHeHnG...");
-file.setAcoustidId("e7359e88-f1f7-41ed-b9f6-16e58e906997");
-file.setMusicBrainzTrackId("f4d1b6b8-8c1e-4d9a-9f2a-1234567890ab");
+console.log("Updated tags:", file.tag());
 
 // Clean up
 file.dispose();
@@ -110,16 +113,17 @@ file.dispose();
 
 ## Platform examples
 
-### Deno
+### Node.js
 
 ```typescript
-import { TagLib } from "jsr:@charleswiltgen/taglib-wasm";
+import { TagLib } from "taglib-wasm";
+import { readFile } from "fs/promises";
 
 // Initialize taglib-wasm
 const taglib = await TagLib.initialize();
 
 // Load audio file from filesystem
-const audioData = await Deno.readFile("song.mp3");
+const audioData = await readFile("song.mp3");
 const file = taglib.openFile(audioData);
 
 // Read metadata
@@ -132,33 +136,31 @@ console.log(`Duration: ${props.length}s`);
 console.log(`Bitrate: ${props.bitrate} kbps`);
 
 // Write metadata
-file.setTitle("New Title");
-file.setArtist("New Artist");
-file.setAlbum("New Album");
+const tag = file.tag();
+tag.setTitle("New Title");
+tag.setArtist("New Artist");
+tag.setAlbum("New Album");
 
-console.log("Updated tags:", file.tag());
+// Save changes
+file.save();
 
-// Automatic tag mapping (format-agnostic)
-file.setAcoustidFingerprint("AQADtMmybfGO8NCNEESLnzHyXNOHeHnG...");
-file.setAcoustidId("e7359e88-f1f7-41ed-b9f6-16e58e906997");
-file.setMusicBrainzTrackId("f4d1b6b8-8c1e-4d9a-9f2a-1234567890ab");
+console.log("Updated tags:", file.tag());
 
 // Clean up
 file.dispose();
 ```
 
-### Node.js
+### Bun
 
 ```typescript
 import { TagLib } from "taglib-wasm";
-import { readFile } from "fs/promises";
 
 // Initialize taglib-wasm
 const taglib = await TagLib.initialize();
 
-// Load audio file from filesystem
-const audioData = await readFile("song.mp3");
-const file = taglib.openFile(audioData);
+// Load from file system (Bun's native file API)
+const audioData = await Bun.file("song.mp3").arrayBuffer();
+const file = taglib.openFile(new Uint8Array(audioData));
 
 // Read metadata
 const tags = file.tag();
@@ -170,22 +172,21 @@ console.log(`Duration: ${props.length}s`);
 console.log(`Bitrate: ${props.bitrate} kbps`);
 
 // Write metadata
-file.setTitle("New Title");
-file.setArtist("New Artist");
-file.setAlbum("New Album");
+const tag = file.tag();
+tag.setTitle("New Title");
+tag.setArtist("New Artist");
+tag.setAlbum("New Album");
 
-console.log("Updated tags:", file.tag());
+// Save changes
+file.save();
 
-// Automatic tag mapping (format-agnostic)
-file.setAcoustidFingerprint("AQADtMmybfGO8NCNEESLnzHyXNOHeHnG...");
-file.setAcoustidId("e7359e88-f1f7-41ed-b9f6-16e58e906997");
-file.setMusicBrainzTrackId("f4d1b6b8-8c1e-4d9a-9f2a-1234567890ab");
+console.log("Updated tags:", file.tag());
 
 // Clean up
 file.dispose();
 ```
 
-### Bun
+### Browser
 
 ```typescript
 import { TagLib } from "taglib-wasm";
@@ -193,9 +194,11 @@ import { TagLib } from "taglib-wasm";
 // Initialize taglib-wasm
 const taglib = await TagLib.initialize();
 
-// Load from file system (Bun's native file API)
-const audioData = await Bun.file("song.mp3").arrayBuffer();
-const file = taglib.openFile(new Uint8Array(audioData));
+// Load from file input or fetch
+const fileInput = document.querySelector('input[type="file"]');
+const audioFile = fileInput.files[0];
+const audioData = new Uint8Array(await audioFile.arrayBuffer());
+const file = taglib.openFile(audioData);
 
 // Read metadata
 const tags = file.tag();
@@ -207,33 +210,30 @@ console.log(`Duration: ${props.length}s`);
 console.log(`Bitrate: ${props.bitrate} kbps`);
 
 // Write metadata
-file.setTitle("New Title");
-file.setArtist("New Artist");
-file.setAlbum("New Album");
+const tag = file.tag();
+tag.setTitle("New Title");
+tag.setArtist("New Artist");
+tag.setAlbum("New Album");
 
-console.log("Updated tags:", file.tag());
+// Save changes
+file.save();
 
-// Automatic tag mapping (format-agnostic)
-file.setAcoustidFingerprint("AQADtMmybfGO8NCNEESLnzHyXNOHeHnG...");
-file.setAcoustidId("e7359e88-f1f7-41ed-b9f6-16e58e906997");
-file.setMusicBrainzTrackId("f4d1b6b8-8c1e-4d9a-9f2a-1234567890ab");
+console.log("Updated tags:", file.tag());
 
 // Clean up
 file.dispose();
 ```
 
-### Browser
+### Deno
 
 ```typescript
-import { TagLib } from "taglib-wasm";
+import { TagLib } from "npm:taglib-wasm";
 
 // Initialize taglib-wasm
 const taglib = await TagLib.initialize();
 
-// Load from file input or fetch
-const fileInput = document.querySelector('input[type="file"]');
-const audioFile = fileInput.files[0];
-const audioData = new Uint8Array(await audioFile.arrayBuffer());
+// Load audio file from filesystem
+const audioData = await Deno.readFile("song.mp3");
 const file = taglib.openFile(audioData);
 
 // Read metadata
@@ -246,16 +246,15 @@ console.log(`Duration: ${props.length}s`);
 console.log(`Bitrate: ${props.bitrate} kbps`);
 
 // Write metadata
-file.setTitle("New Title");
-file.setArtist("New Artist");
-file.setAlbum("New Album");
+const tag = file.tag();
+tag.setTitle("New Title");
+tag.setArtist("New Artist");
+tag.setAlbum("New Album");
 
-console.log("Updated tags:", file.tag());
+// Save changes
+file.save();
 
-// Automatic tag mapping (format-agnostic)
-file.setAcoustidFingerprint("AQADtMmybfGO8NCNEESLnzHyXNOHeHnG...");
-file.setAcoustidId("e7359e88-f1f7-41ed-b9f6-16e58e906997");
-file.setMusicBrainzTrackId("f4d1b6b8-8c1e-4d9a-9f2a-1234567890ab");
+console.log("Updated tags:", file.tag());
 
 // Clean up
 file.dispose();
@@ -318,72 +317,70 @@ export default {
 
 ## 📋 Supported Formats
 
-All formats are **fully tested and working**:
+`tag-wasm` is designed to support all formats supported by TagLib:
 
-- ✅ **MP3** – ID3v2 and ID3v1 tags
-- ✅ **MP4/M4A** – Standard MPEG (iTunes-compatible) metadata atoms
-- ✅ **FLAC** – Vorbis comments and audio properties
-- ✅ **OGG Vorbis** – Vorbis comments
-- ✅ **WAV** – INFO chunk metadata
-- 🔄 **Additional formats**: Opus, APE, MPC, WavPack, TrueAudio, and more
+- ✅ **.m4a (.mp4)** – Standard MPEG-4/AAC metadata for AAC and Apple Lossless audio
+- ✅ **.mp3** – ID3v2 and ID3v1 tags
+- ✅ **.flac** – Vorbis comments and audio properties
+- ✅ **.wav** – INFO chunk metadata
+- ✅ **Legacy formats**: Opus, APE, MPC, WavPack, TrueAudio, and more
 
-## 🎯 Automatic Tag Mapping
+## 🎯 Extended Metadata with PropertyMap
 
-`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.
+`taglib-wasm` provides a **PropertyMap API** for accessing extended metadata beyond the basic tags. This allows you to read and write format-specific fields and custom metadata.
 
 ### AcoustID example
 
 ```typescript
-// Single API works for ALL formats (MP3, FLAC, OGG, MP4)
-file.setAcoustidFingerprint("AQADtMmybfGO8NCNEESLnzHyXNOHeHnG...");
-file.setAcoustidId("e7359e88-f1f7-41ed-b9f6-16e58e906997");
-
-// Automatically stores in format-specific locations:
-// • MP3: TXXX frames with proper descriptions
-// • FLAC/OGG: ACOUSTID_FINGERPRINT and ACOUSTID_ID Vorbis comments
-// • MP4: ----:com.apple.iTunes:Acoustid... freeform atoms
+// Using PropertyMap API to set extended metadata
+file.setProperty("ACOUSTID_FINGERPRINT", "AQADtMmybfGO8NCNEESLnzHyXNOHeHnG...");
+file.setProperty("ACOUSTID_ID", "e7359e88-f1f7-41ed-b9f6-16e58e906997");
+
+// Note: Property keys may vary by format
+// Use file.properties() to see all available properties
+file.save(); // Don't forget to save!
 ```
 
 ### MusicBrainz example
 
 ```typescript
-// Professional music database integration
-file.setMusicBrainzTrackId("f4d1b6b8-8c1e-4d9a-9f2a-1234567890ab");
-file.setMusicBrainzReleaseId("a1b2c3d4-e5f6-7890-abcd-ef1234567890");
-file.setMusicBrainzArtistId("12345678-90ab-cdef-1234-567890abcdef");
+// MusicBrainz metadata using PropertyMap
+file.setProperty("MUSICBRAINZ_TRACKID", "f4d1b6b8-8c1e-4d9a-9f2a-1234567890ab");
+file.setProperty("MUSICBRAINZ_ALBUMID", "a1b2c3d4-e5f6-7890-abcd-ef1234567890");
+file.setProperty("MUSICBRAINZ_ARTISTID", "12345678-90ab-cdef-1234-567890abcdef");
 ```
 
 ### Volume example
 
 ```typescript
-// ReplayGain support (automatic format mapping)
-file.setReplayGainTrackGain("-6.54 dB");
-file.setReplayGainTrackPeak("0.987654");
-file.setReplayGainAlbumGain("-8.12 dB");
-file.setReplayGainAlbumPeak("0.995432");
-
-// Apple Sound Check support
-file.setAppleSoundCheck("00000150 00000150 00000150 00000150...");
+// ReplayGain volume normalization
+file.setProperty("REPLAYGAIN_TRACK_GAIN", "-6.54 dB");
+file.setProperty("REPLAYGAIN_TRACK_PEAK", "0.987654");
+file.setProperty("REPLAYGAIN_ALBUM_GAIN", "-8.12 dB");
+file.setProperty("REPLAYGAIN_ALBUM_PEAK", "0.995432");
 ```
 
 ### Extended fields
 
 ```typescript
-// Advanced metadata fields
-file.setExtendedTag({
-  albumArtist: "Various Artists",
-  composer: "Composer Name",
-  bpm: 120,
-  compilation: true,
-  discNumber: 1,
-  totalTracks: 12,
-  // Volume normalization
-  replayGainTrackGain: "-6.54 dB",
-  appleSoundCheck: "00000150...",
+// Using PropertyMap to set multiple properties at once
+const properties = file.properties(); // Get current properties
+
+// Set extended metadata
+file.setProperties({
+  ALBUMARTIST: ["Various Artists"],
+  COMPOSER: ["Composer Name"],
+  BPM: ["120"],
+  COMPILATION: ["1"],
+  DISCNUMBER: ["1"],
+  TRACKTOTAL: ["12"],
+  // Note: Property keys vary by format
 });
-```
 
-**📖 See [docs/Automatic-Tag-Mapping.md](docs/Automatic-Tag-Mapping.md) for complete documentation**
+// Or set individual properties
+file.setProperty("ALBUMARTIST", "Various Artists");
+file.setProperty("COMPOSER", "Composer Name");
+```
 
 ## 🏗️ Development
 
@@ -418,8 +415,7 @@ build/
 ├── taglib.js       # Generated Emscripten JavaScript
 └── taglib.wasm     # Compiled WebAssembly module
 
-tests/              # Test files and sample audio files
-tests/              # Test suite
+tests/              # Test suite and sample audio files
 examples/           # Usage examples for different runtimes
 ├── deno/           # Deno-specific examples
 ├── bun/            # Bun-specific examples
@@ -483,53 +479,63 @@ class TagLib {
 class AudioFile {
   // Validation
   isValid(): boolean;
-  format(): string;
+  getFormat(): string;
 
   // Properties
   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;
+  // Tag Access (returns Tag object with getters and setters)
+  tag(): Tag;
+
+  // PropertyMap API for extended metadata
+  properties(): PropertyMap;
+  setProperties(properties: PropertyMap): void;
+  getProperty(key: string): string | undefined;
+  setProperty(key: string, value: string): void;
+
+  // MP4-specific methods
+  isMP4(): boolean;
+  getMP4Item(key: string): string | undefined;
+  setMP4Item(key: string, value: string): void;
+  removeMP4Item(key: string): void;
 
   // File Operations
   save(): boolean;
+  getFileBuffer(): Uint8Array;
   dispose(): 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;
-
-  // MusicBrainz Integration
-  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;
+### Tag interface
+
+```typescript
+interface Tag {
+  // Basic metadata (getters)
+  title: string;
+  artist: string;
+  album: string;
+  comment: string;
+  genre: string;
+  year: number;
+  track: number;
+
+  // Setters
+  setTitle(value: string): void;
+  setArtist(value: string): void;
+  setAlbum(value: string): void;
+  setComment(value: string): void;
+  setGenre(value: string): void;
+  setYear(value: number): void;
+  setTrack(value: number): void;
 }
 ```
 
+### PropertyMap type
+
+```typescript
+type PropertyMap = { [key: string]: string[] };
+```
+
 ## 🎛️ Configuration
 
 ```typescript
@@ -548,7 +554,7 @@ interface TagLibConfig {
 
 | Runtime     | Status  | Installation                      | Performance | TypeScript |
 | ----------- | ------- | --------------------------------- | ----------- | ---------- |
-| **Deno**    | ✅ Full | `jsr:@charleswiltgen/taglib-wasm` | Excellent   | Native     |
+| **Deno**    | ✅ Full | `npm: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  |