ArtworkTag class final

Represents an artwork metadata tag for audio files.

ArtworkTag contains embedded artwork images associated with the track or album, using lazy loading to optimize memory usage. This tag maps to format-specific implementations across different container types:

Format mappings:

  • ID3v2: APIC frame (with picture type and description)
  • Vorbis: METADATA_BLOCK_PICTURE (FLAC) or base64 encoded (OGG)
  • MP4: covr atom
  • ID3v1: Not supported (will be omitted)

The artwork data is loaded lazily through the ArtworkData class, which means the image bytes are only loaded when actually needed. This provides significant memory efficiency when working with large audio collections.

Example usage:

// Create artwork with lazy loading
final artworkData = ArtworkData(
  mimeType: 'image/jpeg',
  type: ArtworkType.frontCover,
  description: 'Album front cover',
  dataLoader: () async => await File('cover.jpg').readAsBytes(),
);
final artworkTag = ArtworkTag(artworkData);

// Create with provenance information
final artworkWithProvenance = ArtworkTag(
  artworkData,
  provenance: TagProvenance(
    ContainerKind.id3v2,
    '2.4',
    TagConfidence.certain,
  ),
);

// Access artwork metadata without loading image data
print('MIME Type: ${artworkTag.value.mimeType}');
print('Type: ${artworkTag.value.type}');
print('Description: ${artworkTag.value.description}');

// Load the actual image data when needed
final imageBytes = await artworkTag.value.data;
print('Image size: ${imageBytes.length} bytes');

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

Multiple artwork images of different types (front cover, back cover, artist photos, etc.) can be present in a single audio file. Each artwork tag represents one image with its associated metadata.

The lazy loading mechanism ensures that:

  • Metadata can be examined without loading image data
  • Memory usage remains low when scanning large collections
  • Image data is only loaded when actually needed for display or processing
  • Multiple references to the same artwork share the same loader
Inheritance

Constructors

ArtworkTag.new(ArtworkData value, {TagProvenance provenance = const TagProvenance.none()})
Creates a new ArtworkTag with the specified artwork data.
const

Properties

hashCode → int
The hash code for this object.
no setterinherited
key → TagKey
The semantic field type that this tag represents.
finalinherited
props → List<Object?>
The list of properties that will be used to determine whether two instances are equal.
no setterinherited
provenance → TagProvenance
Provenance information tracking the origin and reliability of this tag.
finalinherited
requiresAsyncPreparation → bool
Whether this artwork tag requires async data loading before encoding.
no setteroverride
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 → ArtworkData
The actual metadata value stored in this tag.
finalinherited

Methods

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

Operators

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