taglib-wasm 0.2.8 → 0.3.1

package/README.md

@@ -26,7 +26,7 @@ Because there’s nothing like it. [`mp3tag.js`](https://mp3tag.js.org/) is matu
 ### Deno
 
 ```typescript
-import { TagLib } from "jsr:@charleswiltgen/taglib-wasm";
+import { TagLib } from "npm:taglib-wasm";
 ```
 
 ### Node.js
@@ -78,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
@@ -97,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();
@@ -137,16 +136,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();
@@ -174,16 +172,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();
@@ -213,16 +210,51 @@ 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");
+
+// Save changes
+file.save();
 
 console.log("Updated tags:", file.tag());
 
-// Automatic tag mapping (format-agnostic)
-file.setAcoustidFingerprint("AQADtMmybfGO8NCNEESLnzHyXNOHeHnG...");
-file.setAcoustidId("e7359e88-f1f7-41ed-b9f6-16e58e906997");
-file.setMusicBrainzTrackId("f4d1b6b8-8c1e-4d9a-9f2a-1234567890ab");
+// Clean up
+file.dispose();
+```
+
+### 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();
@@ -293,63 +325,62 @@ export default {
 - ✅ **.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
 
@@ -384,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
@@ -449,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
@@ -514,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  |