taglib-wasm 0.3.3 → 0.3.9

package/README.md

@@ -1,48 +1,48 @@
 # TagLib-Wasm
 
-> TagLib for TypeScript platforms: Deno, Node.js, Bun, browsers, and Cloudflare
-> Workers
-
-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` stands on the shoulders of giants, including
+[![npm version](https://img.shields.io/npm/v/taglib-wasm.svg?logo=nodedotjs&logoColor=f5f5f5)](https://www.npmjs.com/package/taglib-wasm)
+[![npm downloads](https://img.shields.io/npm/dm/taglib-wasm.svg)](https://www.npmjs.com/package/taglib-wasm)
+[![License](https://img.shields.io/npm/l/taglib-wasm.svg)](https://github.com/CharlesWiltgen/taglib-wasm/blob/main/LICENSE)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-3178c6.svg?logo=typescript&logoColor=f5f5f5)](https://www.typescriptlang.org/)
+[![Built with Emscripten](https://img.shields.io/badge/Built%20with-Emscripten-4B9BFF.svg)](https://emscripten.org/)
+<br>[![Deno](https://img.shields.io/badge/Deno-000000?logo=deno&logoColor=white)](https://deno.land/)
+[![Node.js](https://img.shields.io/badge/Node.js-339933?logo=nodedotjs&logoColor=white)](https://nodejs.org/)
+[![Bun](https://img.shields.io/badge/Bun-000000?logo=bun&logoColor=white)](https://bun.sh/)
+[![Cloudflare Workers](https://img.shields.io/badge/Cloudflare%20Workers-F38020?logo=cloudflare&logoColor=white)](https://workers.cloudflare.com/)
+[![Electron](https://img.shields.io/badge/Electron-47848F?logo=electron&logoColor=white)](https://www.electronjs.org/)
+[![Browser](https://img.shields.io/badge/Browser-4285F4?logo=googlechrome&logoColor=white)]()
+
+**TagLib-Wasm** is the universal tagging library for TypeScript platforms: Deno,
+Node.js, Bun, Cloudflare Workers, Electron, and browsers. It’s the answer to the
+question:
+
+> “What if [**TagLib**](https://taglib.org/), but TypeScript?”
+
+This project exists because the TypeScipt/JavaScript ecosystem had no
+battle-tested audio tagging library that supports reading and writing music
+metadata to all popular audio formats. It aspires to be a universal solution for
+all **TypeScript**-capable platforms — Deno, Node.js, Bun, Electron, Cloudflare
+Workers, and browsers.
+
+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.
+TagLib itself is legendary and a core dependency of many music apps.
 
 ## 🎯 Features
 
-- **✅ 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
+- **✅ TypeScript first** – Complete type definitions and modern API
+- **✅ Wide TS/JS runtime support** – Deno, Node.js, Bun, Electron, Cloudflare
+  Workers, and browsers
+- **✅ Format abstraction** – Handles container format details automagically
+  when possible
 - **✅ 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
+- **✅ Two API styles** – Use the “Simple” API (3 functions), or the full “Core”
+  API for more advanced applications
 
 ## 📦 Installation
 
@@ -83,307 +83,103 @@ npx tsx your-script.ts
 bun add taglib-wasm
 ```
 
-## 🚀 Quick Start
-
-### Simple API
-
-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
-const tags = await readTags("song.mp3");
-console.log(tags.title, tags.artist, tags.album);
+### Electron
 
-// Write tags
-await writeTags("song.mp3", {
-  title: "New Title",
-  artist: "New Artist",
-  album: "New Album",
-});
-
-// Read audio properties
-const props = await readProperties("song.mp3");
-console.log(`Duration: ${props.length}s, Bitrate: ${props.bitrate} kbps`);
+```bash
+npm install taglib-wasm
 ```
 
-### Core API
-
-The Core API provides full control for more advanced applications.
+Works in both main and renderer processes:
 
 ```typescript
+// Main process
 import { TagLib } from "taglib-wasm";
 
-// Initialize taglib-wasm
-const taglib = await TagLib.initialize();
-
-// Load audio file from buffer
-const audioData = await readFile("song.mp3"); // Node.js/Bun: fs.readFile, Deno: Deno.readFile
-const file = taglib.openFile(audioData);
-
-// Read metadata
-const tags = file.tag();
-const props = file.audioProperties();
-
-console.log(`Title: ${tags.title}`);
-console.log(`Artist: ${tags.artist}`);
-console.log(`Duration: ${props.length}s`);
-console.log(`Bitrate: ${props.bitrate} kbps`);
-
-// Write metadata
-const tag = file.tag();
-tag.setTitle("New Title");
-tag.setArtist("New Artist");
-tag.setAlbum("New Album");
-
-// Save changes
-file.save();
-
-console.log("Updated tags:", file.tag());
-
-// Clean up
-file.dispose();
+// Renderer process (with nodeIntegration: true)
+const { TagLib } = require("taglib-wasm");
 ```
 
-### Tag Constants
+## 🚀 Quick Start
 
-taglib-wasm provides type-safe tag constants with IDE autocomplete:
+### Simple API (Recommended)
 
 ```typescript
-import { Tags } from "taglib-wasm";
+import { readTags, updateTags } from "taglib-wasm/simple";
 
-// 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];
+// Read tags - just one function call!
+const tags = await readTags("song.mp3");
+console.log(tags.title, tags.artist, tags.album);
 
-// Write properties
-file.setProperties({
-  [Tags.Title]: ["My Song"],
-  [Tags.AlbumArtist]: ["Various Artists"],
-  [Tags.Bpm]: ["128"],
+// Update tags in-place - even simpler!
+await updateTags("song.mp3", {
+  title: "New Title",
+  artist: "New Artist",
+  album: "New Album",
 });
-
-// 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
-
-### Deno
-
-```typescript
-import { TagLib } from "npm:taglib-wasm";
-
-// Initialize taglib-wasm
-const taglib = await TagLib.initialize();
-
-// Load audio file from filesystem
-const audioData = await Deno.readFile("song.mp3");
-const file = taglib.openFile(audioData);
-
-// Read metadata
-const tags = file.tag();
-const props = file.audioProperties();
-
-console.log(`Title: ${tags.title}`);
-console.log(`Artist: ${tags.artist}`);
-console.log(`Duration: ${props.length}s`);
-console.log(`Bitrate: ${props.bitrate} kbps`);
-
-// Write metadata
-const tag = file.tag();
-tag.setTitle("New Title");
-tag.setArtist("New Artist");
-tag.setAlbum("New Album");
-
-// Save changes
-file.save();
-
-console.log("Updated tags:", file.tag());
-
-// Clean up
-file.dispose();
-```
-
-### Node.js
+### Core API (Advanced)
 
 ```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);
-
-// Read metadata
-const tags = file.tag();
-const props = file.audioProperties();
-
-console.log(`Title: ${tags.title}`);
-console.log(`Artist: ${tags.artist}`);
-console.log(`Duration: ${props.length}s`);
-console.log(`Bitrate: ${props.bitrate} kbps`);
+// Load audio file
+const file = await taglib.open("song.mp3");
 
-// Write metadata
+// Read and update metadata
 const tag = file.tag();
 tag.setTitle("New Title");
 tag.setArtist("New Artist");
-tag.setAlbum("New Album");
 
 // Save changes
 file.save();
 
-console.log("Updated tags:", file.tag());
-
 // Clean up
 file.dispose();
 ```
 
-### Bun
+### Working with Cover Art
 
 ```typescript
-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));
-
-// Read metadata
-const tags = file.tag();
-const props = file.audioProperties();
+import { getCoverArt, setCoverArt } from "taglib-wasm/simple";
 
-console.log(`Title: ${tags.title}`);
-console.log(`Artist: ${tags.artist}`);
-console.log(`Duration: ${props.length}s`);
-console.log(`Bitrate: ${props.bitrate} kbps`);
-
-// Write metadata
-const tag = file.tag();
-tag.setTitle("New Title");
-tag.setArtist("New Artist");
-tag.setAlbum("New Album");
-
-// Save changes
-file.save();
-
-console.log("Updated tags:", file.tag());
+// Extract cover art
+const coverData = await getCoverArt("song.mp3");
+if (coverData) {
+  await Deno.writeFile("cover.jpg", coverData);
+}
 
-// Clean up
-file.dispose();
+// Set new cover art
+const imageData = await Deno.readFile("new-cover.jpg");
+await setCoverArt("song.mp3", imageData, "image/jpeg");
 ```
 
-### Browser
-
-```typescript
-import { TagLib } from "taglib-wasm";
+## 📚 Documentation
 
-// Initialize taglib-wasm
-const taglib = await TagLib.initialize();
+**[📖 View Full Documentation](https://charleswiltgen.github.io/taglib-wasm/)**
 
-// 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);
+### Getting Started
 
-// Read metadata
-const tags = file.tag();
-const props = file.audioProperties();
+- [Installation Guide](https://charleswiltgen.github.io/taglib-wasm/guide/installation.html)
+- [Quick Start Tutorial](https://charleswiltgen.github.io/taglib-wasm/guide/quick-start.html)
+- [All Examples](https://charleswiltgen.github.io/taglib-wasm/guide/examples.html)
 
-console.log(`Title: ${tags.title}`);
-console.log(`Artist: ${tags.artist}`);
-console.log(`Duration: ${props.length}s`);
-console.log(`Bitrate: ${props.bitrate} kbps`);
+### Guides
 
-// Write metadata
-const tag = file.tag();
-tag.setTitle("New Title");
-tag.setArtist("New Artist");
-tag.setAlbum("New Album");
+- [API Reference](https://charleswiltgen.github.io/taglib-wasm/API.html)
+- [Platform Examples](https://charleswiltgen.github.io/taglib-wasm/guide/platform-examples.html)
+- [Working with Cover Art](https://charleswiltgen.github.io/taglib-wasm/guide/cover-art.html)
+- [Cloudflare Workers Setup](https://charleswiltgen.github.io/taglib-wasm/guide/workers-setup.html)
+- [Error Handling](https://charleswiltgen.github.io/taglib-wasm/Error-Handling.html)
 
-// Save changes
-file.save();
+### Development
 
-console.log("Updated tags:", file.tag());
-
-// Clean up
-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 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
-        });
-
-        // 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 });
-  },
-};
-```
+- [Testing Guide](https://charleswiltgen.github.io/taglib-wasm/development/testing.html)
+- [Future Improvements](https://charleswiltgen.github.io/taglib-wasm/development/improvements.html)
+- [Contributing](https://charleswiltgen.github.io/taglib-wasm/CONTRIBUTING.html)
 
 ## 📋 Supported Formats
 
@@ -396,81 +192,33 @@ export default {
 - ✅ **.wav** – INFO chunk metadata
 - ✅ **Legacy formats** – Opus, APE, MPC, WavPack, TrueAudio, and more
 
-## 🎯 Extended Metadata with PropertyMap
+## 🎯 Key Features
 
-`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.
+### Extended Metadata Support
 
-### AcoustID example
+Beyond basic tags, taglib-wasm supports extended metadata:
 
 ```typescript
 import { Tags } from "taglib-wasm";
 
-// Using PropertyMap API to set extended metadata with tag constants
+// AcoustID fingerprints
 file.setProperty(
   Tags.AcoustidFingerprint,
   "AQADtMmybfGO8NCNEESLnzHyXNOHeHnG...",
 );
-file.setProperty(Tags.AcoustidId, "e7359e88-f1f7-41ed-b9f6-16e58e906997");
-
-// Or using string property names
-file.setProperty("ACOUSTID_FINGERPRINT", "AQADtMmybfGO8NCNEESLnzHyXNOHeHnG...");
 
-// 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
-// MusicBrainz metadata using PropertyMap with tag constants
+// MusicBrainz IDs
 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 with tag constants
+// ReplayGain volume normalization
 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
-
-```typescript
-// Using PropertyMap to set multiple properties at once
-const properties = file.properties(); // Get current properties
-
-// Set extended metadata with tag constants
-file.setProperties({
-  [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(Tags.AlbumArtist, "Various Artists");
-file.setProperty(Tags.Composer, "Composer Name");
-```
+[View all supported tag constants →](https://charleswiltgen.github.io/taglib-wasm/Tag-Name-Constants.html)
 
 ## 🏗️ Development
 
@@ -481,199 +229,62 @@ file.setProperty(Tags.Composer, "Composer Name");
 # Install via: https://emscripten.org/docs/getting_started/downloads.html
 
 # Clone and build
-git clone <repository>
+git clone https://github.com/CharlesWiltgen/taglib-wasm.git
 cd taglib-wasm
 
 # Build Wasm module
-deno task build:wasm
+npm run build:wasm
 
 # Run tests
-deno task test
-```
-
-### Project Structure
-
-```text
-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
-
-build/
-├── build-wasm.sh   # Complete build script with C++ wrapper
-├── taglib.js       # Generated Emscripten JavaScript
-└── taglib.wasm     # Compiled WebAssembly module
-
-tests/              # Test suite and sample audio files
-examples/           # Usage examples for different runtimes
-├── deno/           # Deno-specific examples
-├── bun/            # Bun-specific examples
-├── basic-usage.ts  # General usage example
-└── *.ts            # Advanced feature examples
-```
-
-## 🧪 Testing
-
-Comprehensive test suite validates all functionality:
-
-```bash
-# Run with Deno
-deno run --allow-read test-systematic.ts
-
-# Run with Bun
-bun run test-systematic.ts
-
-# Run with Node.js
 npm test
-
-# 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  - 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
-
-### 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
-- **UTF-8 String Handling**: Proper encoding for international metadata
-
-## 📚 API Reference
-
-### TagLib class
-
-```typescript
-class TagLib {
-  static async initialize(config?: TagLibConfig): Promise<TagLib>;
-  openFile(buffer: Uint8Array): AudioFile;
-  getModule(): TagLibModule;
-}
-```
-
-### AudioFile class
-
-```typescript
-class AudioFile {
-  // Validation
-  isValid(): boolean;
-  getFormat(): string;
-
-  // Properties
-  audioProperties(): AudioProperties;
-
-  // 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;
-}
-```
-
-### 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[] };
-```
-
-## 📖 Additional Documentation
-
-- [**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
+[View full development guide →](CONTRIBUTING.md)
 
 ## 🌐 Runtime Compatibility
 
 `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        | Native/tsx |
-| **Browser** | ✅ Full | CDN/bundler               | Good        | Via build  |
-
-**📖 See [docs/Runtime-Compatibility.md](docs/Runtime-Compatibility.md) for
-detailed runtime information**
+| Runtime                | Status  | Installation              | Notes                     |
+| ---------------------- | ------- | ------------------------- | ------------------------- |
+| **Deno**               | ✅ Full | `npm:taglib-wasm`         | Native TypeScript         |
+| **Node.js**            | ✅ Full | `npm install taglib-wasm` | TypeScript via tsx        |
+| **Bun**                | ✅ Full | `bun add taglib-wasm`     | Native TypeScript         |
+| **Browser**            | ✅ Full | Via bundler               | Full API support          |
+| **Cloudflare Workers** | ✅ Full | `taglib-wasm/workers`     | Memory-optimized build    |
+| **Electron**           | ✅ Full | `npm install taglib-wasm` | Main & renderer processes |
 
 ## 🚧 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)
+- **Memory Usage** – Entire file must be loaded into memory (may be an issue for
+  very large files)
+- **Concurrent Access** – Not thread-safe (JavaScript single-threaded nature
+  mitigates this)
+- **Cloudflare Workers** – Limited to 128MB memory per request; files larger
+  than ~100MB may fail
 
 ## 🤝 Contributing
 
-Contributions welcome!
+Contributions are welcome! Please read our [Contributing Guide](CONTRIBUTING.md)
+for details on our code of conduct and the process for submitting pull requests.
 
 ## 📄 License
 
-- **This project**: MIT License (see [LICENSE](LICENSE))
-- **TagLib library**: LGPL/MPL dual license (see
-  [lib/taglib/COPYING.LGPL](lib/taglib/COPYING.LGPL))
+This project uses dual licensing:
+
+- **TypeScript/JavaScript code** – MIT License (see [LICENSE](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](lib/taglib/COPYING.LGPL)
 
 ## 🙏 Acknowledgments