MetadataTag<T> class sealed

Base sealed class for all metadata tags in the unified tagging system.

MetadataTag provides a type-safe, immutable representation of metadata values with full provenance tracking. The sealed class design ensures that all tag types are known at compile time and enables exhaustive pattern matching.

Each tag contains three essential pieces of information:

  • value: The actual metadata content (typed according to the tag type)
  • key: The semantic field type this tag represents
  • provenance: Information about where this tag value originated from

The generic type parameter T ensures type safety for tag values:

  • String for text fields (title, artist, album, etc.)
  • int for numeric fields (trackNumber, year, rating, etc.)
  • List<String> for multi-valued text fields (genre)
  • ArtworkData for artwork fields
  • Other specialized types as needed

Example usage:

// Creating a title tag
final titleTag = TitleTag('My Song');

// Creating a tag with provenance
final artistTag = ArtistTag(
  'Artist Name',
  provenance: TagProvenance(ContainerKind.id3v2, '2.4', TagConfidence.certain),
);

// Creating multi-genre tags with automatic delimiter detection
final genreTag = GenreTag.fromString('Rock;Alternative;Indie');
final genreFromSlash = GenreTag.fromString('Rock/Alternative/Indie');
final genreFromComma = GenreTag.fromString('Rock, Alternative, Indie');
// All result in: ['Rock', 'Alternative', 'Indie']

// Creating single genre tags
final singleGenre = GenreTag.single('Jazz');
final multiGenre = GenreTag(['Electronic', 'Ambient', 'Downtempo']);

// Format-specific genre parsing for container compatibility
final id3v24Genre = GenreTag.fromId3v24String('Rock\0Alternative\0Indie');
final id3v23Genre = GenreTag.fromId3v23String('Rock/Alternative/Indie');

// Updating provenance immutably
final updatedTag = titleTag.withProvenance(
  TagProvenance(ContainerKind.vorbis, '', TagConfidence.certain),
);

The sealed design ensures that:

  • All possible tag types are known at compile time
  • Pattern matching can be exhaustive
  • New tag types require explicit handling in switch statements
  • Type safety is maintained throughout the system

Memory efficiency considerations:

  • Tags are immutable and can be safely shared
  • Large payloads (like artwork) use lazy loading patterns
  • Provenance information is lightweight and cached
  • String interning may be used for common values
Implementers

Properties

hashCode → int
The hash code for this object.
no setterinherited
key → TagKey
The semantic field type that this tag represents.
final
props → List<Object?>
The list of properties that will be used to determine whether two instances are equal.
no setter
provenance → TagProvenance
Provenance information tracking the origin and reliability of this tag.
final
requiresAsyncPreparation → bool
Whether this tag requires async data loading before encoding.
no setter
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited
stringify → bool?
If set to true, the toString method will be overridden to output this instance's props.
no setterinherited
value → T
The actual metadata value stored in this tag.
final

Methods

noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
prepareForEncoding() → Future<MetadataTag<T>>
Prepares the tag for synchronous encoding by loading any async data.
prepareForEncodingAsync() → Future<MetadataTag<T>>
Prepares the tag for synchronous encoding by loading any async data.
toString() → String
A string representation of this object.
withProvenance(TagProvenance newProvenance) → MetadataTag<T>
Creates a new tag instance with updated provenance information.

Operators

operator ==(Object other) → bool
The equality operator.
inherited