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.

Method	Returns
`authorize()`	`AuthorizationStatus`
`authorizationStatus`	`AuthorizationStatus`
`getRecentTracks({after, limit, page})`	`List<PlayedSong>`
`getAlbum(albumId)`	`FullAlbum`
`getArtist(artistId)`	`Artist`
`searchSongs({query, artistId, limit, page})`	`List<Song>`
`searchAlbums({query, artistId, limit, page})`	`List<Album>`
`searchArtists({query, limit, page})`	`List<Artist>`
`searchPlaylists({query, limit, page})`	`List<Playlist>`
`getPlaylistSongs({playlistId, limit, page})`	`List<Song>`

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.