LazyArtworkLoader class

A lazy loader for artwork data that extracts image bytes from container data on demand.

LazyArtworkLoader provides memory-efficient artwork loading by deferring the extraction of image data until it's actually needed. This is particularly important when working with large audio collections where loading all artwork data upfront would consume excessive memory.

The loader works with a slice of container bytes defined by an offset and length, allowing it to extract artwork data from various audio container formats without loading the entire file into memory.

Memory Efficiency

The lazy loading approach provides several benefits:

  • Reduced memory usage when scanning large collections
  • Faster initial metadata loading (artwork metadata without image data)
  • On-demand data access only when artwork is actually displayed or processed
  • Ability to work with large container files without loading everything

Container Format Support

LazyArtworkLoader is designed to work with artwork embedded in various audio container formats:

  • ID3v2: APIC frame image data within ID3v2 tags
  • MP4: covr atom image data within MP4 ilst atoms
  • Vorbis: METADATA_BLOCK_PICTURE image data within Vorbis comments
  • FLAC: METADATA_BLOCK_PICTURE blocks within FLAC metadata

Usage Examples

// Create a lazy loader for artwork at specific offset in container
final loader = LazyArtworkLoader(
  containerBytes: id3v2TagBytes,
  offset: 45,        // Start of APIC frame image data
  length: 12580,     // Length of image data
);

// Load the artwork data when needed
final imageBytes = await loader.load();
print('Loaded ${imageBytes.length} bytes of image data');

// Use with ArtworkData for complete lazy loading
final artworkData = ArtworkData(
  mimeType: 'image/jpeg',
  type: ArtworkType.frontCover,
  description: 'Album cover',
  dataLoader: () => loader.load(),
);

Performance Considerations

  • The container bytes are held in memory, so this is most efficient when the container data is already loaded (e.g., ID3v2 tags, MP4 atoms)
  • Each call to load creates a new sublist, so consider caching results if the same artwork will be accessed multiple times
  • The offset and length are validated on construction to prevent runtime errors
  • Large artwork images may still cause memory pressure when loaded

Error Handling

The loader validates parameters during construction and will throw:

Thread Safety

LazyArtworkLoader instances are immutable after construction and safe to share across threads. The load method is also thread-safe as it only performs read operations on the container bytes.

Constructors

LazyArtworkLoader(Uint8List containerBytes, int offset, int length)
Creates a new LazyArtworkLoader with the specified container data and bounds.

Properties

hashCode → int
The hash code for this object.
no setterinherited
length → int
Gets the length in bytes of the artwork data.
no setter
offset → int
Gets the byte offset where artwork data begins in the container.
no setter
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited

Methods

createStreamingLoader({int chunkSize = 64 * 1024}) → StreamingArtworkLoader
Creates a streaming loader for this artwork data.
load() → Future<Uint8List>
Extracts and returns the artwork data from the container bytes.
loadWithCompression({double compressionThreshold = 0.9}) → Future<CompressedArtworkData>
Loads the artwork data with compression if beneficial.
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
shouldUseStreaming({int streamingThreshold = 5 * 1024 * 1024}) → bool
Determines if this artwork should use streaming based on size.
toString() → String
Returns a string representation of this lazy artwork loader.
override

Operators

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