TagLib Tag Name Constants and Cross-Format Mapping

This document provides a comprehensive reference for TagLib's standard tag names and how they map across different audio formats.

Overview

TagLib uses a PropertyMap system to provide format-independent tag access. This allows you to use consistent tag names across different audio formats (MP3, MP4, FLAC, OGG, WAV, etc.).

TypeScript Constants

taglib-wasm provides type-safe constants for all standard tag names via the Tags object:

import { Tags } from "taglib-wasm";

// Use constants instead of strings for better IDE support
const title = properties[Tags.Title]?.[0]; // Instead of properties["TITLE"]
const artist = properties[Tags.Artist]?.[0]; // Instead of properties["ARTIST"]
const bpm = properties[Tags.Bpm]?.[0]; // Instead of properties["BPM"]

// Constants map to the standard property names
console.log(Tags.Title); // "TITLE"
console.log(Tags.AlbumArtist); // "ALBUMARTIST"
console.log(Tags.TrackGain); // "REPLAYGAIN_TRACK_GAIN"

See the tag-constants.ts example for a complete demonstration.

Standard Property Names

These are the well-known property names defined in TagLib's PropertyMap (tpropertymap.h):

Basic Tags

Sort Names

Credits

Additional Metadata

MusicBrainz Identifiers

Podcast Properties

Format-Specific Tag Mapping

ID3v2 (MP3) Frame Mapping

ID3v2 uses 4-character frame IDs that map to property names:

MP4/M4A Atom Mapping

MP4 uses atom codes (often 4 characters starting with ©):

MP4 also supports freeform atoms using the ----:com.apple.iTunes: prefix:

Vorbis Comments (OGG, FLAC)

Vorbis Comments generally use the property names directly as field names, making them the most straightforward:

• TITLE → TITLE
• ARTIST → ARTIST
• ALBUM → ALBUM
• ALBUMARTIST → ALBUMARTIST
• TRACKNUMBER → TRACKNUMBER
• DATE → DATE
• GENRE → GENRE
• COMMENT → COMMENT
• etc.

Vorbis Comments are case-insensitive but conventionally use uppercase.

RIFF INFO (WAV)

WAV files use INFO chunks with specific FourCC codes:

Usage Examples

Reading Tags (TypeScript)

import { TagLib, Tags } from "taglib-wasm";

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

// Using tag constants (recommended for type safety)
const properties = file.properties();
const title = properties[Tags.Title]?.[0];
const artist = properties[Tags.Artist]?.[0];
const album = properties[Tags.Album]?.[0];
const musicBrainzId = properties[Tags.MusicBrainzTrackId]?.[0];

// Or using string property names directly
const title2 = properties["TITLE"]?.[0];
const artist2 = properties["ARTIST"]?.[0];

Writing Tags (TypeScript)

// Set properties using tag constants (recommended)
file.setProperties({
  [Tags.Title]: ["My Song Title"],
  [Tags.Artist]: ["Artist Name"],
  [Tags.AlbumArtist]: ["Album Artist"],
  [Tags.MusicBrainzTrackId]: ["123e4567-e89b-12d3-a456-426614174000"],
});

// Or using string property names
file.setProperty("TITLE", "My Song Title");
file.setProperty("ARTIST", "Artist Name");

// Save changes
file.save();
const outputBuffer = file.toBuffer();

Cross-Format Compatibility

When using the PropertyMap interface, TagLib automatically handles the format-specific mappings:

// This works the same for MP3, MP4, FLAC, OGG, and WAV files
file.tag.properties.set("TITLE", "Universal Title");
file.tag.properties.set("COMPOSER", "Universal Composer");

// TagLib converts these to:
// - MP3: TIT2 and TCOM frames
// - MP4: ©nam and ©wrt atoms
// - FLAC/OGG: TITLE and COMPOSER vorbis comments
// - WAV: INAM INFO chunk (COMPOSER may not be supported)

Special Considerations

Unsupported Properties

Not all formats support all properties. When a property is not supported:

• Reading returns an empty value
• Writing is ignored or stored in format-specific extension mechanisms
• Use file.tag.properties.unsupportedData() to see what couldn't be mapped

Multiple Values

Some formats support multiple values for a single property:

• Vorbis Comments naturally support multiple values
• ID3v2 can have multiple frames of the same type
• MP4 generally supports only single values

Case Sensitivity

• Property names in the PropertyMap are case-sensitive
• Vorbis Comments are case-insensitive but conventionally uppercase
• ID3v2 frame IDs are always uppercase
• MP4 atoms are case-sensitive

Complex Properties

Some properties require special handling:

• PICTURE: Embedded album art (use complexProperties())
• LYRICS: May include synchronized lyrics in some formats
• PERFORMER:<instrument>: Instrument-specific performer credits

Best Practices

1. Use Standard Names: Always use the standard property names from this document for maximum compatibility.

2. Check Format Support: Be aware that not all formats support all properties.

3. Handle Missing Values: Always check if a property exists before using its value.

4. Preserve Unknown Tags: Use properties() and setProperties() to preserve tags you don't explicitly handle.

5. Test Across Formats: If your application needs to work with multiple formats, test tag operations with each format.

References

• ID3v2 Specification
• Vorbis Comment Specification
• MP4 Metadata Atoms
• RIFF INFO Specification