Extended Metadata with PropertyMap API

taglib-wasm provides a PropertyMap API for handling extended metadata fields beyond the basic tags (title, artist, album, etc.). This allows you to access format-specific fields and custom metadata.

🎯 The PropertyMap API

The PropertyMap API provides a unified interface for reading and writing extended metadata:

// Read all properties
const properties = file.properties();
console.log(properties); // { ALBUMARTIST: ["Various Artists"], BPM: ["120"], ... }

// Get a specific property
const acoustidId = file.getProperty("ACOUSTID_ID");

// Set a property
file.setProperty("ACOUSTID_FINGERPRINT", fingerprint);

// Set multiple properties at once
file.setProperties({
  ALBUMARTIST: ["Various Artists"],
  COMPOSER: ["Composer Name"],
  BPM: ["120"],
});

📝 Important Notes

• Property keys are typically uppercase (e.g., "ALBUMARTIST", "REPLAYGAIN_TRACK_GAIN")
• Property values in setProperties() must be arrays of strings
• Property keys may vary by format - check existing properties with file.properties()
• For MP4-specific metadata, use the setMP4Item() method
• Use the Tags constants for type-safe access: file.properties()[Tags.AlbumArtist]
• See Tag Name Constants for a comprehensive list of standard property names and format-specific mappings

📋 Format-Specific Storage Reference

AcoustID Fields

MusicBrainz Fields

Extended Fields

🚀 Usage Examples

Basic AcoustID Handling

import { TagLib } from "taglib-wasm";

const taglib = await TagLib.initialize();
const file = taglib.openFile(audioBuffer);

// Set AcoustID data (works for ANY format)
file.setAcoustidFingerprint("AQADtMmybfGO8NCNEESLnzHyXNOHeHnG...");
file.setAcoustidId("e7359e88-f1f7-41ed-b9f6-16e58e906997");

// Read AcoustID data (works for ANY format)
const fingerprint = file.getAcoustidFingerprint();
const acoustidId = file.getAcoustidId();

console.log("AcoustID:", acoustidId);
console.log("Fingerprint:", fingerprint);

MusicBrainz Integration

// Set MusicBrainz identifiers
file.setMusicBrainzTrackId("f4d1b6b8-8c1e-4d9a-9f2a-1234567890ab");
file.setMusicBrainzReleaseId("a1b2c3d4-e5f6-7890-abcd-ef1234567890");
file.setMusicBrainzArtistId("12345678-90ab-cdef-1234-567890abcdef");

// These are automatically stored in the correct format-specific location

Bulk Extended Metadata

// Set multiple fields at once
file.setExtendedTag({
  // Basic fields
  title: "Song Title",
  artist: "Artist Name",
  album: "Album Name",

  // Advanced fields
  acoustidFingerprint: "AQADtMmybfGO8NCNEESLnzHyXNOHeHnG...",
  acoustidId: "e7359e88-f1f7-41ed-b9f6-16e58e906997",
  musicbrainzTrackId: "f4d1b6b8-8c1e-4d9a-9f2a-1234567890ab",
  albumArtist: "Album Artist",
  composer: "Composer Name",
  bpm: 120,
  compilation: true,
});

// Read all extended metadata
const extendedTags = file.extendedTag();
console.log("All metadata:", extendedTags);

🔧 Implementation Details

Metadata Mapping System

The library uses a comprehensive mapping system defined in METADATA_MAPPINGS:

export const METADATA_MAPPINGS: Record<keyof ExtendedTag, FieldMapping> = {
  acoustidFingerprint: {
    id3v2: { frame: "TXXX", description: "Acoustid Fingerprint" },
    vorbis: "ACOUSTID_FINGERPRINT",
    mp4: "----:com.apple.iTunes:Acoustid Fingerprint",
  },
  // ... more mappings
};

Format Detection

The library automatically detects the audio format and uses the appropriate storage method:

1. Format Detection: Determine if file is MP3, FLAC, OGG, MP4, etc.
2. Mapping Lookup: Find the correct field mapping for that format
3. Storage: Use format-specific TagLib methods to store the data

TagLib PropertyMap Integration

Advanced metadata uses TagLib's PropertyMap system for format-agnostic field access:

// C++ implementation (conceptual)
TagLib::PropertyMap propertyMap = file->properties();
propertyMap["ACOUSTID_FINGERPRINT"] = TagLib::StringList(fingerprint);
file->setProperties(propertyMap);

🚧 Current Implementation Status

✅ Completed

• Type Definitions: Complete ExtendedTag interface
• Mapping Configuration: Full METADATA_MAPPINGS for all formats
• API Design: Format-agnostic method signatures
• Documentation: Complete usage examples and reference

🚧 In Progress

• C++ PropertyMap Integration: Requires additional C++ wrapper functions
• Format-Specific Writers: Need C++ functions for advanced field writing
• Format-Specific Readers: Need C++ functions for advanced field reading

📋 Next Steps

1. Extend C++ Wrapper: Add PropertyMap access functions
2. Implement Field Writers: Format-specific writing logic
3. Implement Field Readers: Format-specific reading logic
4. Add Wasm Exports: Export new C++ functions to JavaScript
5. Complete TypeScript Integration: Wire up API methods to C++ calls

🎯 Benefits

For Developers

• Single API: One method call works for all formats
• No Format Knowledge: Don't need to know ID3 frame names, Vorbis fields, etc.
• Consistent Behavior: Same API regardless of audio format
• Type Safety: Full TypeScript support with auto-completion

For Applications

• Professional Metadata: Proper storage following format conventions
• MusicBrainz Compatible: Follows MusicBrainz Picard conventions
• AcoustID Ready: Built-in support for audio fingerprinting
• Future Proof: Easy to add new advanced fields

📚 References

• MusicBrainz Picard Tag Mappings
• ID3v2.4 Specification
• Vorbis Comment Specification
• MP4 Metadata Specification
• AcoustID Documentation

This automatic tag mapping system represents professional-grade audio metadata handling that works seamlessly across all major audio formats. The format-agnostic approach eliminates the complexity of dealing with different metadata systems while ensuring proper, standards-compliant storage.