ArtworkData class

Represents artwork data embedded in audio metadata with lazy loading support.

ArtworkData encapsulates all information about an artwork image including its MIME type, artwork type classification, optional description, and the actual image data through a lazy loading mechanism. This design enables efficient memory usage when working with large audio collections.

The class implements Equatable for proper comparison, but excludes the data loader from equality checks to ensure that two artwork instances with the same metadata but different loading mechanisms are considered equal.

Memory Efficiency

The artwork data itself is loaded lazily through a Future<Uint8List> loader function. This means:

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

Container Format Support

ArtworkData is designed to work across different audio container formats:

ID3v2: APIC frames with MIME type, picture type, and description
MP4: covr atoms with type detection and optional descriptions
Vorbis: METADATA_BLOCK_PICTURE blocks with full metadata
ID3v1: Not supported (no artwork capability)

Usage Examples

// Creating artwork data with a lazy loader
final artworkData = ArtworkData(
  mimeType: 'image/jpeg',
  type: ArtworkType.frontCover,
  description: 'Album front cover',
  dataLoader: () async {
    // Load image data from file, network, or container
    return await loadImageBytes();
  },
);

// Examining metadata without loading image data
print('MIME Type: ${artworkData.mimeType}');
print('Type: ${artworkData.type}');
print('Description: ${artworkData.description}');

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

// Comparing artwork instances (excludes data loader)
final artwork1 = ArtworkData(
  mimeType: 'image/png',
  type: ArtworkType.backCover,
  dataLoader: loader1,
);
final artwork2 = ArtworkData(
  mimeType: 'image/png',
  type: ArtworkType.backCover,
  dataLoader: loader2,
);
print(artwork1 == artwork2); // true - same metadata, different loaders

MIME Type Guidelines

Common MIME types for audio artwork:

image/jpeg - JPEG images (most common, good compression)
image/png - PNG images (lossless, supports transparency)
image/gif - GIF images (rare, limited color palette)
image/bmp - Bitmap images (rare, large file sizes)
image/webp - WebP images (modern, good compression)

Performance Considerations

Metadata access is immediate and lightweight
Image data loading is deferred until data getter is called
Multiple calls to data may trigger multiple loads (no caching)
Consider caching loaded data at the application level if needed
Large artwork collections should use streaming or pagination

Thread Safety

ArtworkData instances are immutable after construction, making them safe to share across threads. However, the lazy loading mechanism may not be thread-safe depending on the implementation of the data loader function.

Implementers

OptimizedArtworkData

Constructors

ArtworkData.new({required String mimeType, required ArtworkType type, String? description, required Future<Uint8List> dataLoader()}): Creates a new ArtworkData instance with the specified metadata and loader.
const
ArtworkData.immediate({required String mimeType, required ArtworkType type, String? description, required Uint8List data}): Creates a new ArtworkData instance with immediately available data.
const
ArtworkData.lazy({required String mimeType, required ArtworkType type, String? description, required Future<Uint8List> dataLoader()}): Creates a new ArtworkData instance with lazy loading capability.
const

Properties

data → Future<Uint8List>: Gets the actual image data by calling the appropriate loader.
no setter
description → String?: Optional human-readable description of the artwork.
final
fileExtension → String?: Returns the typical file extension for this artwork's MIME type.
no setter
formatDescription → String: Returns a human-readable description of this artwork's format.
no setter
hashCode → int: The hash code for this object.
no setterinherited
hasImmediateData → bool: Whether image data is available without async loading.
no setter
immediateData → Uint8List?: Gets immediately available image data for synchronous operations.
no setter
isLossy → bool: Returns true if this artwork's MIME type uses lossy compression.
no setter
isVector → bool: Returns true if this artwork's MIME type is vector-based.
no setter
mimeType → String: The MIME type of the artwork image.
final
mimeTypeEnum → MimeType?: Returns the MimeType enum value for this artwork's MIME type.
no setter
props → List<Object?>: Returns a list of properties used for equality comparison.
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
supportsTransparency → bool: Returns true if this artwork's MIME type supports transparency.
no setter
type → ArtworkType: The type/category of this artwork image.
final

Methods

noSuchMethod(Invocation invocation) → dynamic: Invoked when a nonexistent method or property is accessed.
inherited
toString() → String: Returns a string representation of this artwork data.

Operators

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