MPMusicPlayerController Class Reference

Inherits from
Conforms to
Framework
/System/Library/Frameworks/MediaPlayer.framework
Availability
Available in iOS 3.0 and later.
Companion guide
Declared in
MPMusicPlayerController.h
Related sample code

Overview

Use an MPMusicPlayerController object, or music player, to play media items from the device iPod library. There are two types of music player:

Home Sharing and iPod Music Players

Starting in iOS 4, the built-in iPod 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 iPod library. This means that your app cannot display the title of a home-shared song in your user interface. Specifically, if the iPod app is playing a home-shared song, and you are using an iPod 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 an iPod 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 an iPod music player, your app uses the iPod app to play audio, which means that the iPod app is the “now playing” app. The iPod app receives the remote control events, not your app. However, the iPod app responds to remote control events on your behalf. For example, if your app plays audio using an iPod 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.

Tasks

Getting a Music Player

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.

Managing Playback Mode and State

Controlling Playback

Using Music Player Notifications

These methods control the posting of playback notifications. You can nest calls to start or end these notifications.

Properties

indexOfNowPlayingItem

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

@property (nonatomic, readonly) NSUInteger indexOfNowPlayingItem
Discussion

This property’s value is NSNotFound if the index is not valid—for example, if the playback queue is empty.

Availability
  • Available in iOS 5.0 and later.
Declared In
MPMusicPlayerController.h

nowPlayingItem

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

@property (nonatomic, copy) MPMediaItem *nowPlayingItem
Discussion

To specify that playback should begin at a particular media item in the playback queue, set this property to that item while the music player is stopped or paused.

If no media item is playing or designated to play, this property’s value is nil.

If you create an iPod music player and the user plays an item from another library using Home Sharing, the value of this property is nil.

Availability
  • Available in iOS 3.0 and later.
Related Sample Code
Declared In
MPMusicPlayerController.h

playbackState

The current playback state of the music player.

@property (nonatomic, readonly) MPMusicPlaybackState playbackState
Discussion

If you configure a music player as an iPod music player, the playback state matches the playback state of the built-in iPod app. This is true whether the iPod app is using the device iPod library or a home shared library. Note, however, that when the iPod is using a home shared library, the music player’s nowPlayingItem property is nil.

For the available playback states, see “Playback States.”

Availability
  • Available in iOS 3.0 and later.
Related Sample Code
Declared In
MPMusicPlayerController.h

repeatMode

The current repeat mode of the music player.

@property (nonatomic) MPMusicRepeatMode repeatMode
Discussion

For the available repeat modes, see “Repeat Modes.” If not explicitly set, repeatMode defaults to MPMusicRepeatModeDefault.

Availability
  • Available in iOS 3.0 and later.
Declared In
MPMusicPlayerController.h

shuffleMode

The current shuffle mode of the music player.

@property (nonatomic) MPMusicShuffleMode shuffleMode
Discussion

For the available shuffle modes, see “Shuffle Modes.” If not explicitly set, shuffleMode defaults to MPMusicShuffleModeDefault.

Availability
  • Available in iOS 3.0 and later.
Declared In
MPMusicPlayerController.h

volume

The audio playback volume for the music player, in the range from 0.0 (silent) through 1.0 (maximum volume).

@property (nonatomic) float volume
Discussion

A music player’s volume has a default value of 1.0.

Availability
  • Available in iOS 3.0 and later.
Declared In
MPMusicPlayerController.h

Class Methods

applicationMusicPlayer

Returns the application music player.

+ (MPMusicPlayerController *)applicationMusicPlayer
Return Value

The application music player.

Discussion

The application music player plays music locally within your app. It does not affect the iPod state. When your app moves to the background, the music player stops if it was playing.

Availability
  • Available in iOS 3.0 and later.
Related Sample Code
Declared In
MPMusicPlayerController.h

iPodMusicPlayer

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

+ (MPMusicPlayerController *)iPodMusicPlayer
Return Value

The iPod music player.

Discussion

The iPod music player employs the iPod app on your behalf. On instantiation, it takes on the current iPod app state and controls that state as your app runs. Specifically, the shared state includes the following:

Other aspects of iPod state, such as the on-the-go playlist, are not shared. Music that is playing continues to play when your app moves to the background.

Availability
  • Available in iOS 3.0 and later.
Related Sample Code
Declared In
MPMusicPlayerController.h

Instance Methods

beginGeneratingPlaybackNotifications

Starts the generation of playback notifications.

- (void)beginGeneratingPlaybackNotifications
Availability
  • Available in iOS 3.0 and later.
Declared In
MPMusicPlayerController.h

endGeneratingPlaybackNotifications

Ends the generation of playback notifications.

- (void)endGeneratingPlaybackNotifications
Availability
  • Available in iOS 3.0 and later.
Declared In
MPMusicPlayerController.h

setQueueWithItemCollection:

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

- (void)setQueueWithItemCollection:(MPMediaItemCollection *)itemCollection
Parameters
itemCollection

A media item collection that you want as the playback queue. See MPMediaItemCollection Class Reference for a description of media item collections and how to use them.

Discussion

To begin playback after establishing a playback queue, call play.

Availability
  • Available in iOS 3.0 and later.
Declared In
MPMusicPlayerController.h

setQueueWithQuery:

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

- (void)setQueueWithQuery:(MPMediaQuery *)query
Parameters
query

A media query that specifies the collection of media items that you want as the playback queue. See MPMediaQuery Class Reference for a description of query types and how to create them.

Discussion

To begin playback after establishing a playback queue, call play.

Availability
  • Available in iOS 3.0 and later.
Declared In
MPMusicPlayerController.h

skipToBeginning

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

- (void)skipToBeginning
Availability
  • Available in iOS 3.0 and later.
Declared In
MPMusicPlayerController.h

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.

- (void)skipToNextItem
Discussion

If already at the last item in the playback queue when this method is called, ends playback.

Availability
  • Available in iOS 3.0 and later.
Declared In
MPMusicPlayerController.h

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.

- (void)skipToPreviousItem
Discussion

If already at the first item in the playback queue when this method is called, ends playback.

Availability
  • Available in iOS 3.0 and later.
Declared In
MPMusicPlayerController.h

Constants

Playback States

Values for the playbackState property.

enum {
   MPMusicPlaybackStateStopped,
   MPMusicPlaybackStatePlaying,
   MPMusicPlaybackStatePaused,
   MPMusicPlaybackStateInterrupted,
   MPMusicPlaybackStateSeekingForward,
   MPMusicPlaybackStateSeekingBackward
};
typedef NSInteger MPMusicPlaybackState;
Constants
MPMusicPlaybackStateStopped

The music player is stopped.

Available in iOS 3.0 and later.

Declared in MPMusicPlayerController.h.

MPMusicPlaybackStatePlaying

The music player is playing.

Available in iOS 3.0 and later.

Declared in MPMusicPlayerController.h.

MPMusicPlaybackStatePaused

The music player is paused.

Available in iOS 3.0 and later.

Declared in MPMusicPlayerController.h.

MPMusicPlaybackStateInterrupted

The music player has been interrupted, such as by an incoming phone call.

Available in iOS 3.0 and later.

Declared in MPMusicPlayerController.h.

MPMusicPlaybackStateSeekingForward

The music player is seeking forward.

Available in iOS 3.0 and later.

Declared in MPMusicPlayerController.h.

MPMusicPlaybackStateSeekingBackward

The music player is seeking backward.

Available in iOS 3.0 and later.

Declared in MPMusicPlayerController.h.

Discussion

You determine a music player’s state by checking the playbackState property. Depending on the property’s value, you can update your application’s user interface or take other appropriate action.

Repeat Modes

Values for the repeatMode property.

enum {
   MPMusicRepeatModeDefault,
   MPMusicRepeatModeNone,
   MPMusicRepeatModeOne,
   MPMusicRepeatModeAll
};
typedef NSInteger MPMusicRepeatMode;
Constants
MPMusicRepeatModeDefault

The user’s preferred repeat mode.

Available in iOS 3.0 and later.

Declared in MPMusicPlayerController.h.

MPMusicRepeatModeNone

The music player will not repeat the current song or playlist.

Available in iOS 3.0 and later.

Declared in MPMusicPlayerController.h.

MPMusicRepeatModeOne

The music player will repeat the current song.

Available in iOS 3.0 and later.

Declared in MPMusicPlayerController.h.

MPMusicRepeatModeAll

The music player will repeat the current playlist.

Available in iOS 3.0 and later.

Declared in MPMusicPlayerController.h.

Shuffle Modes

Values for the shuffleMode property.

enum {
   MPMusicShuffleModeDefault,
   MPMusicShuffleModeOff,
   MPMusicShuffleModeSongs,
   MPMusicShuffleModeAlbums
};
typedef NSInteger MPMusicShuffleMode;
Constants
MPMusicShuffleModeDefault

The user’s preferred shuffle mode.

Available in iOS 3.0 and later.

Declared in MPMusicPlayerController.h.

MPMusicShuffleModeOff

The playlist is not shuffled.

Available in iOS 3.0 and later.

Declared in MPMusicPlayerController.h.

MPMusicShuffleModeSongs

The playlist is shuffled by song.

Available in iOS 3.0 and later.

Declared in MPMusicPlayerController.h.

MPMusicShuffleModeAlbums

The playlist is shuffled by album.

Available in iOS 3.0 and later.

Declared in MPMusicPlayerController.h.

Notifications

MPMusicPlayerControllerPlaybackStateDidChangeNotification

Posted when the playback state has been changed programmatically or by user action. The object associated with the notification is the music player whose playback state changed. The notification has no userInfo dictionary.
Availability
Declared In
MPMusicPlayerController.h

MPMusicPlayerControllerNowPlayingItemDidChangeNotification

Posted when the currently playing media item has changed. The object associated with the notification is the music player whose now-playing item changed. The notification has no userInfo dictionary.
Availability
Declared In
MPMusicPlayerController.h

MPMusicPlayerControllerVolumeDidChangeNotification

Posted when the audio playback volume for the music player has changed. The object associated with the notification is the music player whose playback volume changed. The notification has no userInfo dictionary.
Availability
Declared In
MPMusicPlayerController.h

Did this document help you? Yes It's good, but... Not helpful...