media_metadata #

A Flutter plugin to read (and partially write) metadata from media files (audio and video) on Android, iOS, macOS, Windows, and Linux.

Fields returned #

Metadata #

ImageMetadata #

All image data — embedded artwork, a generated video thumbnail, or a standalone image file's own content — is exposed through a single ImageMetadata object on metadata.imageMetadata.

Usage #

import 'package:media_metadata/media_metadata.dart';

// Read metadata from a file path
final metadata = await MediaMetadata.read('/storage/emulated/0/Music/song.mp3');

if (metadata != null) {
  print(metadata.title);       // "Bohemian Rhapsody"
  print(metadata.artist);      // "Queen"
  print(metadata.album);       // "A Night at the Opera"
  print(metadata.duration);    // Duration(minutes: 5, seconds: 55)
  print(metadata.year);        // 1975
  print(metadata.trackNumber); // 11
  print(metadata.comment);     // any free-text comment tag
  print(metadata.audioCodec);  // e.g. "MP3", "AAC"
  print(metadata.sampleRate);  // e.g. 44100

  // Display the album art
  final art = metadata.imageMetadata;
  if (art?.data != null) {
    Image.memory(art!.data!);
    print('${art.type} ${art.width}x${art.height}, generated: ${art.isGenerated}');
  }
}

// Write metadata back to a file
final success = await MediaMetadata.write(
  '/storage/emulated/0/Pictures/photo.jpg',
  Metadata(title: 'Vacation', artist: 'Unknown', year: 2024),
);
if (success) {
  print('Metadata written successfully');
}

// Check if a file is supported before reading
if (MediaMetadata.isSupported('/path/to/file.mp3')) {
  // supported
}

Generating a thumbnail for videos without cover art (createThumbnail) #

Many video files simply don't have an embedded cover (unlike most music files). Pass createThumbnail: true to have the plugin capture a real frame from the video — the same kind of image a file explorer or media player would show — whenever no real embedded artwork is found:

final metadata = await MediaMetadata.read(
  '/storage/emulated/0/Movies/clip.mp4',
  createThumbnail: true,
);

final art = metadata?.imageMetadata;
if (art?.data != null) {
  Image.memory(art!.data!);
  if (art.isGenerated) {
    // This is a captured video frame, not a real embedded cover.
  }
}

Notes:

• createThumbnail only has an effect for video files (.mp4, .mkv, .3gp, .3gpp, .mov) that have no real embedded artwork. If a real cover is found, it is always returned as-is and isGenerated stays false.
• It is false by default, since generating a thumbnail (decoding/seeking into the video) is significantly more expensive than reading existing tags.
• The plugin never fabricates a generic file-type/media-player icon as a substitute for missing artwork — createThumbnail always captures genuine video content, or returns nothing.
• Generated thumbnails (isGenerated == true) are intentionally not written back by MediaMetadata.write even if you pass them along in an updated Metadata, to avoid accidentally saving a generated frame as if it were a real cover.

Write support #

The MediaMetadata.write API writes the metadata fields supported by the current platform and returns true when the operation succeeds.

Supported platforms:

• Android: audio tags via ID3v2 (best-effort) for .mp3; image metadata via ExifInterface for .jpg, .jpeg, .png, .webp, .heic
• Windows: file metadata via the Shell Property Store, including comment and the album cover (imageMetadata.data)
• Linux: audio metadata (including comment) via TagLib when available
• iOS / macOS: currently not supported; the API returns false

Technical audio/video info (sampleRate, audioBitrate, videoCodec, frameRate, ...) is always derived from the encoded stream itself and is read-only on every platform — it is never written back.

Setup #

Android #

Add the following permissions to your AndroidManifest.xml:

<!-- Android < 13 -->
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE"
    android:maxSdkVersion="32" />

<!-- Android 13+ -->
<uses-permission android:name="android.permission.READ_MEDIA_IMAGES" />
<uses-permission android:name="android.permission.READ_MEDIA_VIDEO" />
<uses-permission android:name="android.permission.READ_MEDIA_AUDIO" />

Request the permission at runtime using permission_handler or another package.

The plugin uses Android's built-in MediaMetadataRetriever and MediaExtractor — no extra dependencies required beyond androidx.exifinterface (added automatically by the plugin's build.gradle). createThumbnail uses MediaMetadataRetriever.getFrameAtTime, also built-in.

iOS / macOS #

No additional setup needed. Uses AVFoundation and ImageIO (both system frameworks). createThumbnail uses AVAssetImageGenerator.

Windows #

Uses the Windows Shell Property Store (IPropertyStore) and Media Foundation for tags and technical info, plus direct parsing of ID3v2/MP4 atoms for embedded artwork (no dependency on system thumbnail handlers). Requires Windows 10 or later. No extra SDKs needed — links against propsys, mfplat, mfreadwrite, shlwapi, and windowscodecs.

createThumbnail uses IShellItemImageFactory — the same mechanism Explorer uses to show video thumbnails — but only ever for videos, and only when explicitly requested.

Linux #

Uses TagLib for metadata extraction. Install the development package:

sudo apt install libtag1-dev   # Debian/Ubuntu
sudo dnf install taglib-devel  # Fedora

The plugin will compile without TagLib but will only return file sizes in that case.

createThumbnail shells out to ffmpeg if it's installed on the system:

sudo apt install ffmpeg

If ffmpeg isn't found, createThumbnail simply has no effect (no thumbnail is generated) — it never falls back to a generic icon.

Platform notes #

On every platform, real embedded artwork is always preferred over a generated thumbnail, and a generated thumbnail is never produced for audio files or silently substituted with a generic icon.