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 |
Overview
Use an MPMusicPlayerController object, or music player, to play media items from the device iPod library. There are two types of music player:
The application music player plays music locally within your app. It is not aware of the iPod app’s now-playing item, nor does it affect the iPod state.
The iPod music player employs the built-in iPod app on your behalf. On instantiation, it takes on the current iPod 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 iPod app then has your music player’s most recently-set repeat mode, shuffle mode, playback state, and now-playing item.
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
-
nowPlayingItemproperty -
indexOfNowPlayingItemproperty -
playbackStateproperty -
repeatModeproperty -
shuffleModeproperty -
volumeproperty
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.
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.hnowPlayingItem
The currently-playing media item, or the media item, within a queue, that you have designated to begin playback with.
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.
Declared In
MPMusicPlayerController.hplaybackState
The current playback state of the music player.
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.
Declared In
MPMusicPlayerController.hrepeatMode
The current repeat mode of the music player.
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.hshuffleMode
The current shuffle mode of the music player.
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.hvolume
The audio playback volume for the music player, in the range from 0.0 (silent) through 1.0 (maximum 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.hClass Methods
applicationMusicPlayer
Returns the application music player.
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.
Declared In
MPMusicPlayerController.hiPodMusicPlayer
Returns the iPod music player, which controls the iPod app’s state.
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:
Repeat mode (see “Repeat Modes”)
Shuffle mode (see “Shuffle Modes”
Now-playing item (see
nowPlayingItem)Playback state (see
playbackState)
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.
Declared In
MPMusicPlayerController.hInstance Methods
beginGeneratingPlaybackNotifications
Starts the generation of playback notifications.
Availability
- Available in iOS 3.0 and later.
See Also
Declared In
MPMusicPlayerController.hendGeneratingPlaybackNotifications
Ends the generation of playback notifications.
Availability
- Available in iOS 3.0 and later.
See Also
Declared In
MPMusicPlayerController.hsetQueueWithItemCollection:
Sets a music player’s playback queue using a media item collection.
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.
See Also
Declared In
MPMusicPlayerController.hsetQueueWithQuery:
Sets a music player’s playback queue based on a media 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.
See Also
Declared In
MPMusicPlayerController.hskipToBeginning
Restarts playback at the beginning of the currently playing media item.
Availability
- Available in iOS 3.0 and later.
See Also
Declared In
MPMusicPlayerController.hskipToNextItem
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.
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.hskipToPreviousItem
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.
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.hConstants
Playback States
Values for the playbackState property.
enum {
MPMusicPlaybackStateStopped,
MPMusicPlaybackStatePlaying,
MPMusicPlaybackStatePaused,
MPMusicPlaybackStateInterrupted,
MPMusicPlaybackStateSeekingForward,
MPMusicPlaybackStateSeekingBackward
};
typedef NSInteger MPMusicPlaybackState;
Constants
MPMusicPlaybackStateStoppedThe music player is stopped.
Available in iOS 3.0 and later.
Declared in
MPMusicPlayerController.h.MPMusicPlaybackStatePlayingThe music player is playing.
Available in iOS 3.0 and later.
Declared in
MPMusicPlayerController.h.MPMusicPlaybackStatePausedThe music player is paused.
Available in iOS 3.0 and later.
Declared in
MPMusicPlayerController.h.MPMusicPlaybackStateInterruptedThe music player has been interrupted, such as by an incoming phone call.
Available in iOS 3.0 and later.
Declared in
MPMusicPlayerController.h.MPMusicPlaybackStateSeekingForwardThe music player is seeking forward.
Available in iOS 3.0 and later.
Declared in
MPMusicPlayerController.h.MPMusicPlaybackStateSeekingBackwardThe 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
MPMusicRepeatModeDefaultThe user’s preferred repeat mode.
Available in iOS 3.0 and later.
Declared in
MPMusicPlayerController.h.MPMusicRepeatModeNoneThe music player will not repeat the current song or playlist.
Available in iOS 3.0 and later.
Declared in
MPMusicPlayerController.h.MPMusicRepeatModeOneThe music player will repeat the current song.
Available in iOS 3.0 and later.
Declared in
MPMusicPlayerController.h.MPMusicRepeatModeAllThe 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
MPMusicShuffleModeDefaultThe user’s preferred shuffle mode.
Available in iOS 3.0 and later.
Declared in
MPMusicPlayerController.h.MPMusicShuffleModeOffThe playlist is not shuffled.
Available in iOS 3.0 and later.
Declared in
MPMusicPlayerController.h.MPMusicShuffleModeSongsThe playlist is shuffled by song.
Available in iOS 3.0 and later.
Declared in
MPMusicPlayerController.h.MPMusicShuffleModeAlbumsThe playlist is shuffled by album.
Available in iOS 3.0 and later.
Declared in
MPMusicPlayerController.h.
Notifications
MPMusicPlayerControllerPlaybackStateDidChangeNotification
userInfo dictionary.Availability
- Available in iOS 3.0 and later.
Declared In
MPMusicPlayerController.hMPMusicPlayerControllerNowPlayingItemDidChangeNotification
userInfo dictionary.Availability
- Available in iOS 3.0 and later.
Declared In
MPMusicPlayerController.hMPMusicPlayerControllerVolumeDidChangeNotification
userInfo dictionary.Availability
- Available in iOS 3.0 and later.
Declared In
MPMusicPlayerController.h© 2012 Apple Inc. All Rights Reserved. (Last updated: 2012-09-19)