Class

MPMusicPlayerController

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

Declaration

class MPMusicPlayerController : NSObject

Overview

Create an instance of a music player to play media items in your app. There are two types of music player:

An application music player plays music locally within your app. It is not aware of the Music app’s now-playing item, nor does it affect the Music app’s state. There are two application music players: applicationMusicPlayer and applicationQueuePlayer. The application queue player provides greater control over the contents of the queue and is the preferred player.
The system music player employs the built-in Music app on your behalf. On instantiation, it takes on the current Music app state, such as the identification of the now-playing item. If a user switches away from your app while music is playing, that music continues to play. The Music app then has your music player’s most recently-set repeat mode, shuffle mode, playback state, and now-playing item.

Creating a new instance of MPMusicPlayerController and not specifying the player type returns a system music player.

Home Sharing and System Music Players

The built-in Music and Videos apps can play media from shared libraries using Home Sharing. However, third-party apps using the Media Player framework still have access only to the device Music library. This means that your app cannot display the title of a home-shared song in your user interface. Specifically, if the Music app is playing a home-shared song, and you are using an Music music player, the value of the nowPlayingItem property of your music player is nil. Other playback information is available, however, when playing shared media. For example, the system does update the value of the playbackState property when the system music player is playing a shared item.

Using Remote-Control Events with a Music Player

Users can initiate audio playback commands through an external headset or accessory. These commands are sent to the app as remote-control events. To receive remote-control events in your app, you must use an application music player. If you use the system music player, your app uses the Music app to play audio, which means that the Music app is the “now playing” app. The Music app receives the remote control events, not your app. However, the Music app responds to remote control events on your behalf. For example, if your app plays audio using the system music player, and you switch from your app to the iOS device’s Now Playing controls, the controls work as expected. That is, you can play or pause audio or skip to the next and previous items.

Topics

Getting a Music Player

class var applicationMusicPlayer: MPMusicPlayerController

Returns the application music player.

class var applicationQueuePlayer: MPMusicPlayerApplicationController

Returns the application queue music player.

class var systemMusicPlayer: MPMusicPlayerController & MPSystemMusicPlayerController

Returns the system music player, which controls the Music app’s state.

class var iPodMusicPlayer: MPMusicPlayerController

Returns the iPod music player, which controls the iPod app’s state.

Deprecated

Setting Up a Playback Queue

Before a music player can produce sound, it needs a playback queue. You provide the music player with its playback queue, which specifies the media items to be played.

func setQueue(with: MPMediaQuery)

Sets a music player’s playback queue based on a media query.

func setQueue(with: MPMediaItemCollection)

Sets a music player’s playback queue using a media item collection.

func setQueue(with: [String])

Sets a music player's playback queue using with media items identified by the store identifiers.

func setQueue(with: MPMusicPlayerQueueDescriptor)

Set the music player's playback queue using media items that fit the queue descriptor properties.

Playing a Media Item

func prepareToPlay(completionHandler: (Error?) -> Void)

Prepares a music player for playback.

Managing Playback Mode and State

var nowPlayingItem: MPMediaItem?

The currently-playing media item, or the media item, within a queue, that you have designated to begin playback with.

var indexOfNowPlayingItem: Int

The index of the now playing item in the current playback queue.

var playbackState: MPMusicPlaybackState

The current playback state of the music player.

var repeatMode: MPMusicRepeatMode

The current repeat mode of the music player.

var shuffleMode: MPMusicShuffleMode

The current shuffle mode of the music player.

enum MPMusicPlaybackState

The music player playback state modes.

enum MPMusicRepeatMode

The repeat modes for the media player.

enum MPMusicShuffleMode

The shuffle modes for the media player.

Controlling Playback

func skipToNextItem()

Starts playback of the next media item in the playback queue; or, the music player is not playing, designates the next media item as the next to be played.

func skipToBeginning()

Restarts playback at the beginning of the currently playing media item.

func skipToPreviousItem()

Starts playback of the previous media item in the playback queue; or, the music player is not playing, designates the previous media item as the next to be played.

func append(MPMusicPlayerQueueDescriptor)

Inserts the media items defined by the queue descriptor after the last media item in the current queue.

func prepend(MPMusicPlayerQueueDescriptor)

Inserts the media items defined by the queue descriptor into the current queue immediately after the currently playing media item.