flutter_mpmediaplayer #

A plugin to interface with MPMediaPlayer on iOS/iPadOS.

It reads the user's local media library: recently played songs, plus songs, albums, artists, and playlists by search.

Requirements #

• iOS 15.0 or later
• Flutter 3.44.0 or later, which is where Swift Package Manager became the default for iOS

This plugin is iOS/iPadOS only. MPMediaPlayer does not exist on Android, macOS, web, or desktop, so there is no implementation for them.

Installation #

Add the dependency:

dependencies:
  flutter_mpmediaplayer: ^1.0.0

Then add NSAppleMusicUsageDescription to ios/Runner/Info.plist. Without this key, iOS terminates the app when it requests library access.

<key>NSAppleMusicUsageDescription</key>
<string>Access song history</string>

The permission prompt shows this string. Describe what your app does with the library.

Usage #

Call authorize() before anything else.

import 'package:flutter_mpmediaplayer/flutter_mpmediaplayer.dart';

final status = await FlutterMPMediaPlayer.authorize();

if (status == AuthorizationStatus.authorized) {
  final songs = await FlutterMPMediaPlayer.getRecentTracks(
    limit: 20,
    page: 1,
  );

  for (final song in songs) {
    print('${song.title} by ${song.artist} at ${song.lastPlayedDate}');
  }
}

authorize() shows the system prompt the first time. On later calls it returns the current status without prompting. To read the status without ever prompting, use FlutterMPMediaPlayer.authorizationStatus.

API #

All methods are static on FlutterMPMediaPlayer.

Every search* method takes an optional query. Omitting it returns everything of that kind in the library.

Paging #

limit and page are required on every list method. page is 1-based. Requesting a page past the end returns an empty list.

Artwork #

artwork is PNG bytes as a Uint8List, or null when the item has none. Render it with Image.memory.

List results carry 174×174 artwork; getAlbum and getArtist carry 470×470. The tracks inside a FullAlbum carry no artwork, since they all share the album's.

Errors #

Platform failures surface as PlatformException:

• NOT_FOUND — no album, artist, or playlist with that id
• BAD_ID — the id is not a valid media library persistent id

Example #

example/ is a browser for the whole library that calls every method in the table above:

• Recent tab — getRecentTracks, with chips for the after filter
• Songs, Albums, Artists, Playlists tabs — the four search* methods, with a debounced query box
• Tapping a row — getAlbum, getArtist, or getPlaylistSongs
• Artist detail — searchAlbums and searchSongs filtered by artistId
• Every list — pages on scroll, with a button to step one page at a time
• Bug-report menu — calls the detail methods with malformed and unknown ids, so the BAD_ID and NOT_FOUND paths are reachable without editing code

License #

BSD 3-Clause. See LICENSE.