taglib-wasm 0.3.1 → 0.3.3

package/README.md

@@ -1,25 +1,48 @@
-# taglib-wasm
+# TagLib-Wasm
 
-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 for TypeScript platforms: Deno, Node.js, Bun, browsers, and Cloudflare
+> Workers
 
-`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/)).
+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` 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.
+`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/)).
+
+`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?
 
-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.
+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
 
-- **✅ Universal compatibility** – Works with Deno, Node.js, Bun, web browsers, and Cloudflare Workers
+- **✅ 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
-- **✅ Zero dependencies** – Self-contained WASM bundle
+- **✅ 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
+- **✅ Zero dependencies** – Self-contained Wasm bundle
 - **✅ Memory efficient** – In-memory processing without filesystem access
-- **✅ Production ready** – Growing test suite helps ensure safety and reliability
-- **🆕 Two API styles** – Choose between Simple (3 functions) or Core (full control) APIs
+- **✅ Production ready** – Growing test suite helps ensure safety and
+  reliability
+- **🆕 Two API styles** – Choose between Simple (3 functions) or Core (full
+  control) APIs
 
 ## 📦 Installation
 
@@ -35,7 +58,19 @@ import { TagLib } from "npm: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):
+The package uses TypeScript. You have two options:
+
+#### Option 1: Use Node’s native TypeScript support
+
+```bash
+# Node.js 22.6.0+ with experimental flag
+node --experimental-strip-types your-script.ts
+
+# Node.js 23.6.0+ (no flag needed)
+node your-script.ts
+```
+
+#### Option 2: TypeScript loader (recommended for production)
 
 ```bash
 npm install --save-dev tsx
@@ -52,16 +87,17 @@ bun add taglib-wasm
 
 ### Simple API
 
-Inspired by [go-taglib](https://github.com/sentriz/go-taglib)’s excellent developer experience:
+This was inspired by [go-taglib](https://github.com/sentriz/go-taglib), a
+similar project for Go created at about the same time.
 
 ```typescript
 import { readProperties, readTags, writeTags } from "taglib-wasm/simple";
 
-// Read tags - just one function call!
+// Read tags
 const tags = await readTags("song.mp3");
 console.log(tags.title, tags.artist, tags.album);
 
-// Write tags - simple as can be
+// Write tags
 await writeTags("song.mp3", {
   title: "New Title",
   artist: "New Artist",
@@ -75,7 +111,7 @@ console.log(`Duration: ${props.length}s, Bitrate: ${props.bitrate} kbps`);
 
 ### Core API
 
-Full control when you need it:
+The Core API provides full control for more advanced applications.
 
 ```typescript
 import { TagLib } from "taglib-wasm";
@@ -111,19 +147,51 @@ console.log("Updated tags:", file.tag());
 file.dispose();
 ```
 
+### Tag Constants
+
+taglib-wasm provides type-safe tag constants with IDE autocomplete:
+
+```typescript
+import { Tags } from "taglib-wasm";
+
+// Use constants for better type safety and autocomplete
+const properties = file.properties();
+
+// Read properties
+const title = properties[Tags.Title]?.[0];
+const albumArtist = properties[Tags.AlbumArtist]?.[0];
+const musicBrainzId = properties[Tags.MusicBrainzArtistId]?.[0];
+
+// Write properties
+file.setProperties({
+  [Tags.Title]: ["My Song"],
+  [Tags.AlbumArtist]: ["Various Artists"],
+  [Tags.Bpm]: ["128"],
+});
+
+// All constants provide IDE autocomplete
+Tags.Title; // → "TITLE"
+Tags.Artist; // → "ARTIST"
+Tags.AlbumArtist; // → "ALBUMARTIST"
+Tags.TrackGain; // → "REPLAYGAIN_TRACK_GAIN"
+// ... and many more
+```
+
+See [Tag Name Constants](docs/Tag-Name-Constants.md) for the complete list of
+available tags and format-specific mappings.
+
 ## Platform examples
 
-### Node.js
+### Deno
 
 ```typescript
-import { TagLib } from "taglib-wasm";
-import { readFile } from "fs/promises";
+import { TagLib } from "npm:taglib-wasm";
 
 // Initialize taglib-wasm
 const taglib = await TagLib.initialize();
 
 // Load audio file from filesystem
-const audioData = await readFile("song.mp3");
+const audioData = await Deno.readFile("song.mp3");
 const file = taglib.openFile(audioData);
 
 // Read metadata
@@ -150,17 +218,18 @@ console.log("Updated tags:", file.tag());
 file.dispose();
 ```
 
-### Bun
+### Node.js
 
 ```typescript
 import { TagLib } from "taglib-wasm";
+import { readFile } from "fs/promises";
 
 // 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 audio file from filesystem
+const audioData = await readFile("song.mp3");
+const file = taglib.openFile(audioData);
 
 // Read metadata
 const tags = file.tag();
@@ -186,7 +255,7 @@ console.log("Updated tags:", file.tag());
 file.dispose();
 ```
 
-### Browser
+### Bun
 
 ```typescript
 import { TagLib } from "taglib-wasm";
@@ -194,11 +263,9 @@ import { TagLib } from "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());
-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();
@@ -224,16 +291,18 @@ console.log("Updated tags:", file.tag());
 file.dispose();
 ```
 
-### Deno
+### Browser
 
 ```typescript
-import { TagLib } from "npm:taglib-wasm";
+import { TagLib } from "taglib-wasm";
 
 // Initialize taglib-wasm
 const taglib = await TagLib.initialize();
 
-// Load audio file from filesystem
-const audioData = await Deno.readFile("song.mp3");
+// 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
@@ -269,7 +338,8 @@ export default {
   async fetch(request: Request): Promise<Response> {
     if (request.method === "POST") {
       try {
-        // Initialize taglib-wasm
+        // Initialize taglib-wasm with Workers-specific configuration
+        // See docs/Cloudflare-Workers.md for memory configuration details
         const taglib = await TagLib.initialize({
           memory: { initial: 8 * 1024 * 1024 }, // 8MB for Workers
         });
@@ -319,22 +389,33 @@ export default {
 
 `tag-wasm` is designed to support all formats supported by TagLib:
 
-- ✅ **.m4a (.mp4)** – Standard MPEG-4/AAC metadata for AAC and Apple Lossless audio
+- ✅ **.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
+- ✅ **Legacy formats** – Opus, APE, MPC, WavPack, TrueAudio, and more
 
 ## 🎯 Extended Metadata with PropertyMap
 
-`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.
+`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
-// Using PropertyMap API to set extended metadata
+import { Tags } from "taglib-wasm";
+
+// Using PropertyMap API to set extended metadata with tag constants
+file.setProperty(
+  Tags.AcoustidFingerprint,
+  "AQADtMmybfGO8NCNEESLnzHyXNOHeHnG...",
+);
+file.setProperty(Tags.AcoustidId, "e7359e88-f1f7-41ed-b9f6-16e58e906997");
+
+// Or using string property names
 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
@@ -344,20 +425,29 @@ file.save(); // Don't forget to save!
 ### MusicBrainz example
 
 ```typescript
-// 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");
+// MusicBrainz metadata using PropertyMap with tag constants
+file.setProperty(
+  Tags.MusicBrainzTrackId,
+  "f4d1b6b8-8c1e-4d9a-9f2a-1234567890ab",
+);
+file.setProperty(
+  Tags.MusicBrainzAlbumId,
+  "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
+);
+file.setProperty(
+  Tags.MusicBrainzArtistId,
+  "12345678-90ab-cdef-1234-567890abcdef",
+);
 ```
 
 ### Volume example
 
 ```typescript
-// 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");
+// ReplayGain volume normalization with tag constants
+file.setProperty(Tags.TrackGain, "-6.54 dB");
+file.setProperty(Tags.TrackPeak, "0.987654");
+file.setProperty(Tags.AlbumGain, "-8.12 dB");
+file.setProperty(Tags.AlbumPeak, "0.995432");
 ```
 
 ### Extended fields
@@ -366,20 +456,20 @@ file.setProperty("REPLAYGAIN_ALBUM_PEAK", "0.995432");
 // Using PropertyMap to set multiple properties at once
 const properties = file.properties(); // Get current properties
 
-// Set extended metadata
+// Set extended metadata with tag constants
 file.setProperties({
-  ALBUMARTIST: ["Various Artists"],
-  COMPOSER: ["Composer Name"],
-  BPM: ["120"],
-  COMPILATION: ["1"],
-  DISCNUMBER: ["1"],
-  TRACKTOTAL: ["12"],
+  [Tags.AlbumArtist]: ["Various Artists"],
+  [Tags.Composer]: ["Composer Name"],
+  [Tags.Bpm]: ["120"],
+  [Tags.Compilation]: ["1"],
+  [Tags.DiscNumber]: ["1"],
+  [Tags.TrackTotal]: ["12"],
   // Note: Property keys vary by format
 });
 
 // Or set individual properties
-file.setProperty("ALBUMARTIST", "Various Artists");
-file.setProperty("COMPOSER", "Composer Name");
+file.setProperty(Tags.AlbumArtist, "Various Artists");
+file.setProperty(Tags.Composer, "Composer Name");
 ```
 
 ## 🏗️ Development
@@ -394,7 +484,7 @@ file.setProperty("COMPOSER", "Composer Name");
 git clone <repository>
 cd taglib-wasm
 
-# Build WASM module
+# Build Wasm module
 deno task build:wasm
 
 # Run tests
@@ -408,7 +498,7 @@ src/
 ├── mod.ts          # Main module exports
 ├── taglib.ts       # Core TagLib and AudioFile classes
 ├── types.ts        # TypeScript type definitions
-└── wasm.ts         # WASM module interface and utilities
+└── wasm.ts         # Wasm module interface and utilities
 
 build/
 ├── build-wasm.sh   # Complete build script with C++ wrapper
@@ -442,23 +532,29 @@ npm test
 # ✅ MP3  - ID3v1/v2 tag support
 # ✅ FLAC - Vorbis comments and properties
 # ✅ OGG  - Vorbis comments
-# ✅ M4A  - iTunes-compatible metadata atoms
+# ✅ M4A  - MPEG-4 (AAC and Apple Lossless) metadata
 ```
 
 ## 🔧 Technical Implementation
 
 ### Key architecture decisions
 
-1. **Memory Management**: Uses Emscripten's `allocate()` for reliable JS↔WASM data transfer
-2. **Buffer-Based Processing**: `TagLib::ByteVectorStream` enables in-memory file processing
-3. **C++ Wrapper**: Custom C functions bridge TagLib's C++ API to WASM exports
-4. **Type Safety**: Complete TypeScript definitions for all audio formats and metadata
+1. **Memory Management**: Uses Emscripten's `allocate()` for reliable JS↔Wasm
+   data transfer
+2. **Buffer-Based Processing**: `TagLib::ByteVectorStream` enables in-memory
+   file processing
+3. **C++ Wrapper**: Custom C functions bridge TagLib's C++ API to Wasm exports
+4. **Type Safety**: Complete TypeScript definitions for all audio formats and
+   metadata
 
 ### Critical implementation details
 
-- **ByteVectorStream**: Enables processing audio files from memory buffers without filesystem
-- **ID-based Object Management**: C++ objects managed via integer IDs for memory safety
-- **Emscripten allocate()**: Ensures proper memory synchronization between JS and WASM
+- **ByteVectorStream**: Enables processing audio files from memory buffers
+  without filesystem
+- **ID-based Object Management**: C++ objects managed via integer IDs for memory
+  safety
+- **Emscripten allocate()**: Ensures proper memory synchronization between JS
+  and Wasm
 - **UTF-8 String Handling**: Proper encoding for international metadata
 
 ## 📚 API Reference
@@ -536,51 +632,48 @@ interface Tag {
 type PropertyMap = { [key: string]: string[] };
 ```
 
-## 🎛️ Configuration
+## 📖 Additional Documentation
 
-```typescript
-interface TagLibConfig {
-  memory?: {
-    initial?: number; // Initial memory size (default: 16MB)
-    maximum?: number; // Maximum memory size (default: 256MB)
-  };
-  debug?: boolean; // Enable debug output
-}
-```
+- [**Tag Name Constants**](docs/Tag-Name-Constants.md) - Comprehensive reference
+  for standard tag names and cross-format mapping
+- [**Automatic Tag Mapping**](docs/Automatic-Tag-Mapping.md) - How taglib-wasm
+  handles format-specific tag differences
+- [**Implementation Details**](docs/Implementation.md) - Technical details about
+  the Wasm implementation
+- [**Runtime Compatibility**](docs/Runtime-Compatibility.md) - Platform-specific
+  setup and considerations
 
 ## 🌐 Runtime Compatibility
 
-`taglib-wasm` works seamlessly across all major JavaScript runtimes:
+`taglib-wasm` works across all major JavaScript runtimes:
 
-| Runtime     | Status  | Installation                      | Performance | TypeScript |
-| ----------- | ------- | --------------------------------- | ----------- | ---------- |
-| **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  |
+| Runtime     | Status  | Installation              | Performance | TypeScript |
+| ----------- | ------- | ------------------------- | ----------- | ---------- |
+| **Deno**    | ✅ Full | `npm:taglib-wasm`         | Excellent   | Native     |
+| **Bun**     | ✅ Full | `bun add taglib-wasm`     | Excellent   | Native     |
+| **Node.js** | ✅ Full | `npm install taglib-wasm` | Good        | Native/tsx |
+| **Browser** | ✅ Full | CDN/bundler               | Good        | Via build  |
 
-**📖 See [docs/Runtime-Compatibility.md](docs/Runtime-Compatibility.md) for detailed runtime information**
+**📖 See [docs/Runtime-Compatibility.md](docs/Runtime-Compatibility.md) for
+detailed runtime information**
 
 ## 🚧 Known Limitations
 
-- **File Writing**: Saves only affect in-memory representation (no filesystem persistence)
-- **Large Files**: Memory usage scales with file size (entire file loaded into memory)
-- **Concurrent Access**: Not thread-safe (JavaScript single-threaded nature)
+- **File Writing** – Saves only affect in-memory representation (no filesystem
+  persistence)
+- **Large Files** – Memory usage scales with file size (entire file loaded into
+  memory)
+- **Concurrent Access** – Not thread-safe (JavaScript single-threaded nature)
 
 ## 🤝 Contributing
 
-Contributions welcome! Areas of interest:
-
-- Additional format support (DSF, DSDIFF, etc.)
-- Advanced metadata implementation (PropertyMap integration)
-- Performance optimizations
-- Runtime-specific optimizations
-- Documentation improvements
+Contributions welcome!
 
 ## 📄 License
 
 - **This project**: MIT License (see [LICENSE](LICENSE))
-- **TagLib library**: LGPL/MPL dual license (see [lib/taglib/COPYING.LGPL](lib/taglib/COPYING.LGPL))
+- **TagLib library**: LGPL/MPL dual license (see
+  [lib/taglib/COPYING.LGPL](lib/taglib/COPYING.LGPL))
 
 ## 🙏 Acknowledgments