iOS Developer Library

Developer

MediaPlayer Framework Reference MPMusicPlayerController Class Reference

Options
Deployment Target:

On This Page
Language:

MPMusicPlayerController

Inheritance


Conforms To


Import Statement


Swift

import MediaPlayer

Objective-C

@import MediaPlayer;

Availability


Available in iOS 3.0 and later.

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.

  • Returns the application music player.

    Declaration

    Swift

    class func applicationMusicPlayer() -> MPMusicPlayerController!

    Objective-C

    + (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.

    Import Statement

    Objective-C

    @import MediaPlayer;

    Swift

    import MediaPlayer

    Availability

    Available in iOS 3.0 and later.

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

    Declaration

    Swift

    class func iPodMusicPlayer() -> MPMusicPlayerController!

    Objective-C

    + (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.

    Import Statement

    Objective-C

    @import MediaPlayer;

    Swift

    import MediaPlayer

    Availability

    Available in iOS 3.0 and later.

    Deprecated in iOS 8.0.

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.

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

    Declaration

    Swift

    func setQueueWithQuery(_ query: MPMediaQuery!)

    Objective-C

    - (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.

    Import Statement

    Objective-C

    @import MediaPlayer;

    Swift

    import MediaPlayer

    Availability

    Available in iOS 3.0 and later.

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

    Declaration

    Swift

    func setQueueWithItemCollection(_ itemCollection: MPMediaItemCollection!)

    Objective-C

    - (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.

    Import Statement

    Objective-C

    @import MediaPlayer;

    Swift

    import MediaPlayer

    Availability

    Available in iOS 3.0 and later.

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

    Declaration

    Swift

    @NSCopying var nowPlayingItem: MPMediaItem!

    Objective-C

    @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.

    Import Statement

    Objective-C

    @import MediaPlayer;

    Swift

    import MediaPlayer

    Availability

    Available in iOS 3.0 and later.

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

    Declaration

    Swift

    var indexOfNowPlayingItem: Int { get }

    Objective-C

    @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.

    Import Statement

    Objective-C

    @import MediaPlayer;

    Swift

    import MediaPlayer

    Availability

    Available in iOS 5.0 and later.

  • The current playback state of the music player.

    Declaration

    Swift

    var playbackState: MPMusicPlaybackState { get }

    Objective-C

    @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.

    Import Statement

    Objective-C

    @import MediaPlayer;

    Swift

    import MediaPlayer

    Availability

    Available in iOS 3.0 and later.

  • The current repeat mode of the music player.

    Declaration

    Swift

    var repeatMode: MPMusicRepeatMode

    Objective-C

    @property(nonatomic) MPMusicRepeatMode repeatMode

    Discussion

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

    Import Statement

    Objective-C

    @import MediaPlayer;

    Swift

    import MediaPlayer

    Availability

    Available in iOS 3.0 and later.

  • The current shuffle mode of the music player.

    Declaration

    Swift

    var shuffleMode: MPMusicShuffleMode

    Objective-C

    @property(nonatomic) MPMusicShuffleMode shuffleMode

    Discussion

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

    Import Statement

    Objective-C

    @import MediaPlayer;

    Swift

    import MediaPlayer

    Availability

    Available in iOS 3.0 and later.

  • volume volume (iOS 7.0) Property

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

    Deprecation Statement

    To provide UI for adjusting system playback volume, use the MPVolumeView class, which provides media playback controls that iOS users expect and whose appearance you can customize.

    Declaration

    Objective-C

    @property(nonatomic) float volume

    Import Statement

    Objective-C

    @import MediaPlayer;

    Availability

    Available in iOS 3.0 and later.

    Deprecated in iOS 7.0.

  • 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.

    Declaration

    Swift

    func skipToNextItem()

    Objective-C

    - (void)skipToNextItem

    Discussion

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

    Import Statement

    Objective-C

    @import MediaPlayer;

    Swift

    import MediaPlayer

    Availability

    Available in iOS 3.0 and later.

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

    Declaration

    Swift

    func skipToBeginning()

    Objective-C

    - (void)skipToBeginning

    Import Statement

    Objective-C

    @import MediaPlayer;

    Swift

    import MediaPlayer

    Availability

    Available in iOS 3.0 and later.

  • 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.

    Declaration

    Swift

    func skipToPreviousItem()

    Objective-C

    - (void)skipToPreviousItem

    Discussion

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

    Import Statement

    Objective-C

    @import MediaPlayer;

    Swift

    import MediaPlayer

    Availability

    Available in iOS 3.0 and later.

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

  • Values for the playbackState property.

    Declaration

    Swift

    enum MPMusicPlaybackState : Int { case Stopped case Playing case Paused case Interrupted case SeekingForward case SeekingBackward }

    Objective-C

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

    Constants

    • Stopped

      MPMusicPlaybackStateStopped

      The music player is stopped.

      Available in iOS 3.0 and later.

    • Playing

      MPMusicPlaybackStatePlaying

      The music player is playing.

      Available in iOS 3.0 and later.

    • Paused

      MPMusicPlaybackStatePaused

      The music player is paused.

      Available in iOS 3.0 and later.

    • Interrupted

      MPMusicPlaybackStateInterrupted

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

      Available in iOS 3.0 and later.

    • SeekingForward

      MPMusicPlaybackStateSeekingForward

      The music player is seeking forward.

      Available in iOS 3.0 and later.

    • SeekingBackward

      MPMusicPlaybackStateSeekingBackward

      The music player is seeking backward.

      Available in iOS 3.0 and later.

    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.

    Import Statement

    Objective-C

    @import MediaPlayer;

    Swift

    import MediaPlayer

    Availability

    Available in iOS 3.0 and later.

  • Values for the repeatMode property.

    Declaration

    Swift

    enum MPMusicRepeatMode : Int { case Default case None case One case All }

    Objective-C

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

    Constants

    • Default

      MPMusicRepeatModeDefault

      The user’s preferred repeat mode.

      Available in iOS 3.0 and later.

    • None

      MPMusicRepeatModeNone

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

      Available in iOS 3.0 and later.

    • One

      MPMusicRepeatModeOne

      The music player will repeat the current song.

      Available in iOS 3.0 and later.

    • All

      MPMusicRepeatModeAll

      The music player will repeat the current playlist.

      Available in iOS 3.0 and later.

    Import Statement

    Objective-C

    @import MediaPlayer;

    Swift

    import MediaPlayer

    Availability

    Available in iOS 3.0 and later.

  • Values for the shuffleMode property.

    Declaration

    Swift

    enum MPMusicShuffleMode : Int { case Default case Off case Songs case Albums }

    Objective-C

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

    Constants

    • Default

      MPMusicShuffleModeDefault

      The user’s preferred shuffle mode.

      Available in iOS 3.0 and later.

    • Off

      MPMusicShuffleModeOff

      The playlist is not shuffled.

      Available in iOS 3.0 and later.

    • Songs

      MPMusicShuffleModeSongs

      The playlist is shuffled by song.

      Available in iOS 3.0 and later.

    • Albums

      MPMusicShuffleModeAlbums

      The playlist is shuffled by album.

      Available in iOS 3.0 and later.

    Import Statement

    Objective-C

    @import MediaPlayer;

    Swift

    import MediaPlayer

    Availability

    Available in iOS 3.0 and later.