Framework

Media Player

Find and play songs, audio podcasts, audio books, and more from within your app.

Overview

Use the Media Player framework—which is part of MusicKit—to control playback of the user’s media from your app. If your app incorporates music, you can use this framework to search for audio content (songs, podcasts, books, and so on) in the user’s library. You can then play that content directly or ask the system Music app to play it. For example, a game might give users the option to play their own music while completing a particular game level.

To play content from the user’s library using the Media Player framework, use one of the built-in MPMusicPlayerController objects:

  • An application player plays music locally within your app. Use this player when you want greater control over the audio you play for the user. This player doesn’t change the state of the built-in Music app.

  • The system player employs the Music app to play audio on your behalf. Use this player when you want audio to continue playing even when the user switches away from your app.

Use media queries to retrieve the items you want to play and to populate the queue for the media player you selected. After a user gives your app permission to access their Apple Music account, your app can create playlists, add songs to their library, and play any of the millions of songs in the Apple Music catalog. If your app detects that the user isn’t yet an Apple Music member, you can also offer a trial from within your app.

You can’t play video media items directly using the Media Player framework. To play back videos containing MPMediaItem objects, use an AVPlayer object from AVFoundation. The system player also provides a way to play video items using the system apps.

Topics

Essentials

property list key NSAppleMusicUsageDescription

A message that tells the user why the app is requesting access to the user’s media library.

Name: Privacy - Media Library Usage Description

Built-In Music Playback

Playing Audio Using the Built-In Music Player

Create a media player inside your app to play audio from the user's media library.

class MPMusicPlayerController

An object used to play audio media items from the device's Music app library.

protocol MPMediaPlayback

A protocol that defines the interface for controlling audio media playback.

protocol MPSystemMusicPlayerController

A protocol for playing videos in the Music app.

Media Library Synchronization

class MPMediaLibrary

An object that represents the state of synced media items on a device.

Media Item Queries

Using Filters to Create Specialized Queries

Add a filter set to a query before populating a music player queue.

class MPMediaQuery

A query that specifies a set of media items from the device’s media library by way of a filter and a grouping type.

class MPMediaQuerySection

A range of media items or media item collections from within a media query.

class MPMediaPropertyPredicate

A set of predicates that define a filter used in a media query.

class MPMediaPredicate

An abstract class that defines classes for filtering media in a media query.

Media Player Queues

class MPMusicPlayerControllerQueue

An immutable queue containing the media items to play.

class MPMusicPlayerControllerMutableQueue

A mutable queue containing the media items to play.

class MPMusicPlayerApplicationController

A media player object that you use to revise the queue that’s currently playing.

class MPMusicPlayerMediaItemQueueDescriptor

A set of properties and methods used to modify audio media items in the player’s media queue.

class MPMusicPlayerStoreQueueDescriptor

A set of properties and methods used to modify items, based on their store identifier, in the player’s queue.

class MPMusicPlayerPlayParametersQueueDescriptor

A set of properties and methods used to modify how items are played, based on play parameters returned from MusicKit API results.

class MPMusicPlayerQueueDescriptor

The abstract base class for audio media item and store queue descriptors.

Media Items and Playlists

class MPMediaItem

A collection of properties that represents a single item contained in the media library.

class MPMediaItemArtwork

A graphical image, such as music album cover art, associated with a media item.

class MPMediaItemCollection

A sorted set of media items from the media library.

class MPMediaPlaylist

A playable collection of related media items.

class MPMediaPlaylistCreationMetadata

A set of attributes used to describe a playlist when the playlist is first created.

class MPMediaEntity

The abstract superclass for media items, media item collections, and media playlist instances.

Media Player User Interface

Displaying a Media Picker from Your App

Let users choose the music they want to play by displaying a media picker interface from within your app.

class MPMediaPickerController

A specialized view controller that provides a graphical interface for selecting media items.

class MPVolumeView

A slider control used to set the system audio output volume, and a button for choosing the audio output route.

Global Volume Setting Methods

Global functions for setting the volume alert window status.

Now Playing Information

Provide information about the current track.

Becoming a Now Playable App

Ensure your app is eligible to become the “Now Playing” app by adopting best practices for providing Now Playing Info and registering for Remote Command Center actions.

class MPNowPlayingInfoCenter

An object that you use to set now-playing information for media being played by your app.

class MPNowPlayingInfoLanguageOption

A set of interfaces used to set the language option for the now-playing item.

class MPNowPlayingInfoLanguageOptionGroup

A grouped set of language options where only a single language option can be active at a time.

Language Option Characteristic Constants

The constants used to define language characteristics.

External Player and System Event Handling

Support playback controls on external media players or the controls displayed by the system.

Handling External Player Events Notifications

Handle events for external media players.

Remote Command Center Events

Set up the remote command center to handle media player events.

Track Navigation Events

Respond to requests to change what part of a media item is played.

Media Playback Mode Events

Respond to changes in how media items are played.

Feedback and Rating Events

Respond to incoming feedback and rating events.

External Media Player Items

Provide content and interact with external media players.

class MPContentItem

An object containing the information for a displayed media item.

class MPPlayableContentManager

A shared content manager used to control interactions between your media app and system-provided or external media player interfaces.

class MPPlayableContentManagerContext

An object representing the current state of the playable endpoint.

Errors

struct MPError

Error codes for the MPError domain.

enum MPError.Code

Error codes for the Media Player error domain.

let MPErrorDomain: String

The Media Player framework error domain.

Deprecated

Deprecated Types

These symbols are deprecated and are no longer recommended.