Media Player Framework Reference

Contents

Introduction 8 Classes 9 MPMediaEntity Class Reference 10

Overview 10 Tasks 10 Class Methods 11 Instance Methods 11 Constants 13

MPMediaItem Class Reference 14

Overview 14 Tasks 15 Class Methods 15 Constants 16

MPMediaItemArtwork Class Reference 27

Overview 27 Tasks 27 Properties 28 Instance Methods 28

MPMediaItemCollection Class Reference 30

Overview 30 Tasks 31 Properties 31 Class Methods 33 Instance Methods 34

MPMediaLibrary Class Reference 35

Overview 35 Tasks 35 Properties 36

2011-10-12 | 2011 Apple Inc. All Rights Reserved.

Contents

Class Methods 36 Instance Methods 37 Notifications 37

MPMediaPickerController Class Reference 39

Overview 39 Tasks 40 Properties 40 Instance Methods 42

MPMediaPlaylist Class Reference 44

Overview 44 Constants 45

MPMediaPredicate Class Reference 48

Overview 48

MPMediaPropertyPredicate Class Reference 49

Overview 49 Tasks 49 Properties 50 Class Methods 51 Constants 53

MPMediaQuery Class Reference 54

Overview 54 Tasks 55 Properties 57 Class Methods 60 Instance Methods 64 Constants 66

MPMediaQuerySection Class Reference 69

Overview 69 Tasks 69 Properties 70

MPMovieAccessLog Class Reference 71

Overview 71 Tasks 71

2011-10-12 | 2011 Apple Inc. All Rights Reserved.

Contents

Properties 72

MPMovieAccessLogEvent Class Reference 74

Overview 74 Tasks 74 Properties 75

MPMovieErrorLog Class Reference 80

Overview 80 Tasks 80 Properties 81

MPMovieErrorLogEvent Class Reference 83

Overview 83 Tasks 83 Properties 84

MPMoviePlayerController Class Reference 87

Overview 87 Tasks 91 Properties 93 Instance Methods 105 Constants 108 Notifications 117

MPMoviePlayerViewController Class Reference 124

Overview 124 Tasks 125 Properties 125 Instance Methods 125

MPMusicPlayerController Class Reference 127

Overview 127 Tasks 128 Properties 130 Class Methods 133 Instance Methods 135 Constants 141 Notifications 143

2011-10-12 | 2011 Apple Inc. All Rights Reserved.

Contents

MPNowPlayingInfoCenter Class Reference 145

Overview 145 Tasks 146 Properties 146 Class Methods 147 Constants 147

MPTimedMetadata Class Reference 150

Overview 150 Tasks 150 Properties 151 Constants 152 Notifications 153

MPVolumeView Class Reference 155

Overview 155 Tasks 156 Properties 156 Instance Methods 157

UIViewController MediaPlayer Additions Reference 159

Overview 159 Tasks 159 Instance Methods 159

Protocols 161 MPMediaPickerControllerDelegate Protocol Reference 162

Overview 162 Tasks 162 Instance Methods 163

MPMediaPlayback Protocol Reference 164

Overview 164 Tasks 164 Properties 165 Instance Methods 166 Notifications 170

Functions 171

2011-10-12 | 2011 Apple Inc. All Rights Reserved.

Contents

Media Player Functions Reference 172

Overview 172 Functions 172

Document Revision History 174

2011-10-12 | 2011 Apple Inc. All Rights Reserved.

Tables and Listings

MPMediaQuery Class Reference 54

Table 10-1 Convenience constructors from the MPMediaQuery class 55

MPVolumeView Class Reference 155

Listing 21-1 Adding a volume view to your view hierarchy 155

2011-10-12 | 2011 Apple Inc. All Rights Reserved.

Introduction

Framework Header file directories Declared in

/System/Library/Frameworks/MediaPlayer.framework /System/Library/Frameworks/MediaPlayer.framework/Headers MPMediaEntity.h MPMediaItem.h MPMediaItemCollection.h MPMediaLibrary.h MPMediaPickerController.h MPMediaPlayback.h MPMediaPlaylist.h MPMediaQuery.h MPMediaQuerySection.h MPMoviePlayerController.h MPMoviePlayerViewController.h MPMusicPlayerController.h MPNowPlayingInfoCenter.h MPVolumeSettings.h MPVolumeView.h

The Media Player framework provides facilities for playing movie, music, audio podcast, and audio book files. This framework also gives your application access to the iPod library, letting you find and play audio-based media items synced from iTunes on the desktop. iPod library access is read-only. This frameworks MPVolumeView class lets you present a control to let the user adjust system audio output volume and choose among the available output routes, such as for sending audio to an AirPlay-enabled device. The MPMoviePlayerController and MPTimedMetadata classes let you play streamed video content and respond to time-based metadata contained in the stream. Starting in iOS 4.3, you can configure a movie player to support wireless movie playback to AirPlay-enabled hardware.

2011-10-12 | 2011 Apple Inc. All Rights Reserved.

Classes

2011-10-12 | 2011 Apple Inc. All Rights Reserved.

MPMediaEntity Class Reference

Inherits from Conforms to

NSObject NSCoding NSObject (NSObject)

Framework Availability Declared in Companion guide

/System/Library/Frameworks/MediaPlayer.framework Available in iOS 4.2 and later.

iPod Library Access Programming Guide

Overview
The MPMediaEntity class serves as the abstract superclass for MPMediaItem and MPMediaItemCollection instances, and in turn for MPMediaPlaylist instances. As the superclass, MPMediaEntity defines methods used by those subclasses.

Tasks
Working with Media Properties
+ canFilterByProperty:

(page 11) Indicates if a media property key can be used to construct a media property predicate. (page 12) Gets the value for a specified media property key. (page 11) Executes a provided block with the fetched values for the given item properties.

valueForProperty:

enumerateValuesForProperties:usingBlock:

2011-10-12 | 2011 Apple Inc. All Rights Reserved.

10

MPMediaEntity Class Reference Class Methods

Class Methods
canFilterByProperty:
Indicates if a media property key can be used to construct a media property predicate.
+ (BOOL)canFilterByProperty:(NSString *)property

Parameters
property

The key for the media property that you want to examine. Return Value YES if the property you are testing can be used to construct a media property predicate (of type MPMediaPropertyPredicate); otherwise, NO. Discussion The media property keys you can use with this property are listed in this document and in General Media Item Property Keys (page 18), Podcast Item Property Keys (page 24), Playlist Property Keys (page 46), and User-Defined Property Keys (page 25). Availability Available in iOS 4.2 and later. Declared in
MPMediaEntity.h

Instance Methods
enumerateValuesForProperties:usingBlock:
Executes a provided block with the fetched values for the given item properties.
- (void) enumerateValuesForProperties: (NSSet *) properties usingBlock: (void (^)(NSString *property, id value, BOOL *stop)) block;

Parameters
properties

A set of property keys that you want the values for.

2011-10-12 | 2011 Apple Inc. All Rights Reserved.

11

MPMediaEntity Class Reference Instance Methods

block

A block object that executes for each fetched property value. If a value is not available, your block is sent nil. Discussion Use this method to get property values in a batch fashion. In some cases, enumerating over a set of property keys can be more efficient than fetching each individual property with valueForProperty: (page 12). The media property keys you can use with this property are listed in this document and in General Media Item Property Keys (page 18), Podcast Item Property Keys (page 24), Playlist Property Keys (page 46), and User-Defined Property Keys (page 25). Availability Available in iOS 4.2 and later. Declared in
MPMediaEntity.h

valueForProperty:
Gets the value for a specified media property key.
- (id) valueForProperty: (NSString *) property

Parameters
property

The media property key that you want the corresponding value of. Return Value The value for the media property key. Discussion The media property keys you can use with this property are listed in this document and in General Media Item Property Keys (page 18), Podcast Item Property Keys (page 24), Playlist Property Keys (page 46), and User-Defined Property Keys (page 25). Availability Available in iOS 4.2 and later. Declared in
MPMediaEntity.h

2011-10-12 | 2011 Apple Inc. All Rights Reserved.

12

MPMediaEntity Class Reference Constants

Constants
Media Entity Property Keys
You obtain metadata for a media entity by calling the valueForProperty method with these property keys. Some properties can also be used to build media property predicates, as described in MPMediaPropertyPredicate Class Reference . These properties are marked here as filterable .
NSString *const MPMediaEntityPropertyPersistentID; // filterable

Constants
MPMediaEntityPropertyPersistentID

The persistent identifier for a media entity. Value is an NSNumber object containing a uint64_t (unsigned long long). Can be used to build a media property predicate as described in MPMediaPropertyPredicate Class Reference . Available in iOS 4.2 and later. Declared in MPMediaEntity.h.

2011-10-12 | 2011 Apple Inc. All Rights Reserved.

13

MPMediaItem Class Reference

Inherits from Conforms to

MPMediaEntity : NSObject NSCoding (MPMediaEntity) NSObject (NSObject)

Framework Availability Declared in Companion guide Related sample code

/System/Library/Frameworks/MediaPlayer.framework Available in iOS 3.0 and later. MPMediaItem.h iPod Library Access Programming Guide AddMusic

Overview
A media item represents a single piece of media (such as one song or one video podcast) in the iPod library. A media item has an overall unique identifier, accessed using the MPMediaItemPropertyPersistentID (page 19) property key, as well as specific identifiers for its metadata. These identifiers persists across application launches. A media item can have a wide range of metadata associated with it. You access this metadata using the valueForProperty: (page 12) method along with the property keys described in this document. The You can also access metadata in a batch fashion using the enumerateValuesForProperties:usingBlock: (page 11) method. In some cases, this is more efficient. Both of these methods are defined in MPMediaEntity, the abstract superclass of MPMediaItemCollection, and described in MPMediaEntity Class Reference . You use attributes of media items to build media queries for searching the iPod library. These attributes are described in Media Item Type Flags (page 16), General Media Item Property Keys (page 18), and Podcast Item Property Keys (page 24). In addition, the MPMediaEntityPropertyPersistentID (page 13) property is described in Media Entity Property Keys (page 13). Media queries are described in MPMediaQuery Class Reference .

2011-10-12 | 2011 Apple Inc. All Rights Reserved.

14

MPMediaItem Class Reference Tasks

Starting in iOS 5.0, a media item can represent a video from the iPod library, whereas previously only audio was supported. See Media Item Type Flags (page 16).

Tasks
Obtaining Group Properties
+ persistentIDPropertyForGroupingType:

(page 15) Obtains the persistent identifier key for a specified grouping type. (page 16) Obtains the title key for a specified grouping type.

+ titlePropertyForGroupingType:

Class Methods
persistentIDPropertyForGroupingType:
Obtains the persistent identifier key for a specified grouping type.
+ (NSString *) persistentIDPropertyForGroupingType: (MPMediaGrouping) groupingType;

Parameters
groupingType

The grouping type that you want the persistent identifier key for. Discussion Use this convenience method to obtain the key for a specific persistent identifier based on a grouping type. You can use that key, in turn, to obtain the value of a specific persistent ID of a media item, such as album title or artist name. Using this method simplifies such tasks as drilling down from an artist, to albums by that artist, to a specific album. For example, the following statement returns the persistent identifier key for the album grouping type:
NSString *albumIDKey = [MPMediaItem persistentIDPropertyForGroupingType: MPMediaGroupingAlbum];

You could then obtain the specific persistent ID that you want by using the valueForProperty: (page 12)method. Grouping keys are described in Media Item Collection Grouping Keys (page 66).

2011-10-12 | 2011 Apple Inc. All Rights Reserved.

15

MPMediaItem Class Reference Constants

Availability Available in iOS 4.2 and later. Declared in

MPMediaQuery.h

titlePropertyForGroupingType:
Obtains the title key for a specified grouping type.
+ (NSString * )titlePropertyForGroupingType: (MPMediaGrouping) groupingType;

Parameters
groupingType

The grouping type that you want the title key for. Discussion Use this convenience method to obtain the key for the title that corresponds to a specified grouping type. For example, the following statement obtains the title key for the album grouping type:
NSString *titleIDKey = [MPMediaItem titlePropertyForGroupingType: MPMediaGroupingAlbum];

You could then obtain the specific title that you want by using the valueForProperty: (page 12) method. Grouping keys are described in Media Item Collection Grouping Keys (page 66). Availability Available in iOS 4.2 and later. Declared in
MPMediaQuery.h

Constants
Media Item Type Flags
Media item types, used as possible values for the MPMediaItemPropertyMediaType (page 21) property. A media item can have more than one media item type.

2011-10-12 | 2011 Apple Inc. All Rights Reserved.

16

MPMediaItem Class Reference Constants

enum { // audio media types MPMediaTypeMusic MPMediaTypePodcast MPMediaTypeAudioBook MPMediaTypeAnyAudio // video media types MPMediaTypeMovie MPMediaTypeTVShow MPMediaTypeVideoPodcast MPMediaTypeMusicVideo MPMediaTypeVideoITunesU MPMediaTypeAnyVideo // generic media type MPMediaTypeAny

= = = =

1 << 0, 1 << 1, 1 << 2, 0x00ff,

= = = = = =

1 << 8, 1 << 9, 1 << 10, 1 << 11, 1 << 12, 0xff00,

= ~0

}; typedef NSInteger MPMediaType;

Constants
MPMediaTypeMusic

If set, the media item contains music. Available in iOS 3.0 and later. Declared in MPMediaItem.h.
MPMediaTypePodcast

If set, the media item contains a podcast. Available in iOS 3.0 and later. Declared in MPMediaItem.h.
MPMediaTypeAudioBook

If set, the media item contains an audio book. Available in iOS 3.0 and later. Declared in MPMediaItem.h.
MPMediaTypeAnyAudio

If set, the media item contains an unspecified type of audio content. Available in iOS 3.0 and later. Declared in MPMediaItem.h.
MPMediaTypeMovie

If set, the media item contains a movie. Available in iOS 5.0 and later. Declared in MPMediaItem.h.

2011-10-12 | 2011 Apple Inc. All Rights Reserved.

17

MPMediaItem Class Reference Constants

MPMediaTypeTVShow

If set, the media item contains a TV show. Available in iOS 5.0 and later. Declared in MPMediaItem.h.
MPMediaTypeVideoPodcast

If set, the media item contains a video podcast. Available in iOS 5.0 and later. Declared in MPMediaItem.h.
MPMediaTypeMusicVideo

If set, the media item contains a music video. Available in iOS 5.0 and later. Declared in MPMediaItem.h.
MPMediaTypeVideoITunesU

If set, the media item contains an iTunes U video. Available in iOS 5.0 and later. Declared in MPMediaItem.h.
MPMediaTypeAnyVideo

If set, the media item contains an unspecified type of video content. Available in iOS 5.0 and later. Declared in MPMediaItem.h.
MPMediaTypeAny

If set, the media item contains an unspecified type of audio. Available in iOS 3.0 and later. Declared in MPMediaItem.h.

General Media Item Property Keys

You obtain metadata for a media item by calling the valueForProperty method with these property keys. Some properties can also be used to build media property predicates, as described in MPMediaPropertyPredicate Class Reference . These properties are marked here as filterable .

2011-10-12 | 2011 Apple Inc. All Rights Reserved.

18

MPMediaItem Class Reference Constants

NSString NSString NSString NSString NSString NSString NSString NSString NSString NSString NSString NSString NSString NSString NSString NSString NSString NSString NSString NSString NSString NSString NSString NSString NSString NSString

*const *const *const *const *const *const *const *const *const *const *const *const *const *const *const *const *const *const *const *const *const *const *const *const *const *const

MPMediaItemPropertyPersistentID; MPMediaItemPropertyAlbumPersistentID; MPMediaItemPropertyArtistPersistentID; MPMediaItemPropertyAlbumArtistPersistentID; MPMediaItemPropertyGenrePersistentID; MPMediaItemPropertyComposerPersistentID; MPMediaItemPropertyPodcastPersistentID; MPMediaItemPropertyMediaType; MPMediaItemPropertyTitle; MPMediaItemPropertyAlbumTitle; MPMediaItemPropertyArtist; MPMediaItemPropertyAlbumArtist; MPMediaItemPropertyGenre; MPMediaItemPropertyComposer; MPMediaItemPropertyPlaybackDuration; MPMediaItemPropertyAlbumTrackNumber; MPMediaItemPropertyAlbumTrackCount; MPMediaItemPropertyDiscNumber; MPMediaItemPropertyDiscCount; MPMediaItemPropertyArtwork; MPMediaItemPropertyLyrics; MPMediaItemPropertyIsCompilation; MPMediaItemPropertyReleaseDate; MPMediaItemPropertyBeatsPerMinute; MPMediaItemPropertyComments; MPMediaItemPropertyAssetURL;

// // // // // // // // // // // // // //

filterable filterable filterable filterable filterable filterable filterable filterable filterable filterable filterable filterable filterable filterable

// filterable

Constants
MPMediaItemPropertyPersistentID

The persistent identifier for the media item. Value is an NSNumber object containing a uint64_t (unsigned long long). The value of the MPMediaItemPropertyPersistentID identifier persists across application launches and across syncs that do not change the sync status of the media item. The value is not guaranteed to persist across a sync/unsync/sync cycle. Can be used to build a media property predicate as described in MPMediaPropertyPredicate Class Reference . Available in iOS 3.0 and later. Declared in MPMediaItem.h.

2011-10-12 | 2011 Apple Inc. All Rights Reserved.

19

MPMediaItem Class Reference Constants

MPMediaItemPropertyAlbumPersistentID

The persistent identifier for an album. Value is an NSNumber object containing a uint64_t (unsigned long long). The value of the MPMediaItemPropertyAlbumPersistentID identifier persists across application launches and across syncs that do not change the sync status of the media item. The value is not guaranteed to persist across a sync/unsync/sync cycle. Can be used to build a media property predicate as described in MPMediaPropertyPredicate Class Reference . Available in iOS 4.2 and later. Declared in MPMediaItem.h.
MPMediaItemPropertyArtistPersistentID

The persistent identifier for an artist. Value is an NSNumber object containing a uint64_t (unsigned long long). The value of the MPMediaItemPropertyArtistPersistentID identifier persists across application launches and across syncs that do not change the sync status of the media item. The value is not guaranteed to persist across a sync/unsync/sync cycle. Can be used to build a media property predicate as described in MPMediaPropertyPredicate Class Reference . Available in iOS 4.2 and later. Declared in MPMediaItem.h.
MPMediaItemPropertyAlbumArtistPersistentID

The persistent identifier for an album artist. Value is an NSNumber object containing a uint64_t (unsigned long long). The value of the MPMediaItemPropertyAlbumArtistPersistentID identifier persists across application launches and across syncs that do not change the sync status of the media item. The value is not guaranteed to persist across a sync/unsync/sync cycle. Can be used to build a media property predicate as described in MPMediaPropertyPredicate Class Reference . Available in iOS 4.2 and later. Declared in MPMediaItem.h.
MPMediaItemPropertyGenrePersistentID

The persistent identifier for a genre. Value is an NSNumber object containing a uint64_t (unsigned long long). The value of the MPMediaItemPropertyGenrePersistentID identifier persists across application launches and across syncs that do not change the sync status of the media item. The value is not guaranteed to persist across a sync/unsync/sync cycle. Can be used to build a media property predicate as described in MPMediaPropertyPredicate Class Reference . Available in iOS 4.2 and later. Declared in MPMediaItem.h.

2011-10-12 | 2011 Apple Inc. All Rights Reserved.

20

MPMediaItem Class Reference Constants

MPMediaItemPropertyComposerPersistentID

The persistent identifier for a composer. Value is an NSNumber object containing a uint64_t (unsigned long long). The value of the MPMediaItemPropertyComposerPersistentID identifier persists across application launches and across syncs that do not change the sync status of the media item. The value is not guaranteed to persist across a sync/unsync/sync cycle. Can be used to build a media property predicate as described in MPMediaPropertyPredicate Class Reference . Available in iOS 4.2 and later. Declared in MPMediaItem.h.
MPMediaItemPropertyPodcastPersistentID

The persistent identifier for an audio podcast. Value is an NSNumber object containing a uint64_t (unsigned long long). The value of the MPMediaItemPropertyPodcastPersistentID identifier persists across application launches and across syncs that do not change the sync status of the media item. The value is not guaranteed to persist across a sync/unsync/sync cycle. Can be used to build a media property predicate as described in MPMediaPropertyPredicate Class Reference . Available in iOS 4.2 and later. Declared in MPMediaItem.h.
MPMediaItemPropertyMediaType

The media type of the media item. Value is an an NSNumber object representing an NSInteger data type. The NSInteger value represents a bit field flag, or set of flags, from Media Item Type Flags (page 16). Can be used to build a media property predicate as described in MPMediaPropertyPredicate Class Reference . Available in iOS 3.0 and later. Declared in MPMediaItem.h.
MPMediaItemPropertyTitle

The title (or name) of the media item. This property is unrelated to the MPMediaItemPropertyAlbumTitle (page 22) property. Value is an NSString object. Can be used to build a media property predicate as described in MPMediaPropertyPredicate Class Reference . Available in iOS 3.0 and later. Declared in MPMediaItem.h.

2011-10-12 | 2011 Apple Inc. All Rights Reserved.

21

MPMediaItem Class Reference Constants

MPMediaItemPropertyAlbumTitle

The title of an album, such as Live On Mars as opposed to the title of an individual song on the album, , such as Crater Dance (radio edit) (which you specify using the MPMediaItemPropertyTitle (page 21) property). Value is an NSString object. Can be used to build a media property predicate as described in MPMediaPropertyPredicate Class Reference . Available in iOS 3.0 and later. Declared in MPMediaItem.h.
MPMediaItemPropertyArtist

The performing artist(s) for a media itemwhich may vary from the primary artist for the album that a media item belongs to. For example, if the album artist is Joseph Fable, the artist for one of the songs in the album may be Joseph Fable featuring Thomas Smithson Value is an NSString object. . Can be used to build a media property predicate as described in MPMediaPropertyPredicate Class Reference . Available in iOS 3.0 and later. Declared in MPMediaItem.h.
MPMediaItemPropertyAlbumArtist

The primary performing artist for an album as a whole. Value is an NSString object. Can be used to build a media property predicate as described in MPMediaPropertyPredicate Class Reference . Available in iOS 3.0 and later. Declared in MPMediaItem.h.
MPMediaItemPropertyGenre

The musical or film genre of the media item. Value is an NSString object. Can be used to build a media property predicate as described in MPMediaPropertyPredicate Class Reference . Available in iOS 3.0 and later. Declared in MPMediaItem.h.
MPMediaItemPropertyComposer

The musical composer for the media item. Value is an NSString object. Can be used to build a media property predicate as described in MPMediaPropertyPredicate Class Reference . Available in iOS 3.0 and later. Declared in MPMediaItem.h.
MPMediaItemPropertyPlaybackDuration

The playback duration of the media item. Value is an NSNumber object representing a duration in seconds as an NSTimeInterval. Available in iOS 3.0 and later. Declared in MPMediaItem.h.

2011-10-12 | 2011 Apple Inc. All Rights Reserved.

22

MPMediaItem Class Reference Constants

MPMediaItemPropertyAlbumTrackNumber

The track number of the media item, for a media item that is part of an album. Value is an NSNumber object representing an NSUInteger data type. Available in iOS 3.0 and later. Declared in MPMediaItem.h.
MPMediaItemPropertyAlbumTrackCount

The number of tracks in the album that contains the media item. Value is an NSNumber object representing an NSUInteger data type. For an audio streaming app, the system provides a default value of 1 for this property. Available in iOS 3.0 and later. Declared in MPMediaItem.h.
MPMediaItemPropertyDiscNumber

The disc number of the media item, for a media item that is part of a multi-disc album. Value is an NSNumber object representing an NSUInteger data type. Available in iOS 3.0 and later. Declared in MPMediaItem.h.
MPMediaItemPropertyDiscCount

The number of discs in the album that contains the media item. Value is an NSNumber object representing an NSUInteger data type. Available in iOS 3.0 and later. Declared in MPMediaItem.h.
MPMediaItemPropertyArtwork

The artwork image for the media item. Value is a media item image, described in MPMediaItemArtwork Class Reference . Available in iOS 3.0 and later. Declared in MPMediaItem.h.
MPMediaItemPropertyLyrics

The lyrics for the media item. Value is an NSString object. Available in iOS 3.0 and later. Declared in MPMediaItem.h.
MPMediaItemPropertyIsCompilation

A Boolean value indicating whether the media item is part of a compilation (YES), or not (NO). Corresponds to the the Part of a compilation checkbox in the Info tab in the Get Info dialog in iTunes. Value is an NSNumber object representing a BOOL data type. Available in iOS 3.0 and later. Declared in MPMediaItem.h.

2011-10-12 | 2011 Apple Inc. All Rights Reserved.

23

MPMediaItem Class Reference Constants

MPMediaItemPropertyReleaseDate

The date on which the media item was first publicly released. Value is an NSDate object. Available in iOS 4.0 and later. Declared in MPMediaItem.h.
MPMediaItemPropertyBeatsPerMinute

The number of musical beats per minute for the media item, corresponding to the BPM field in the Info tab in the Get Info dialog in iTunes. Value is an NSNumber object representing an NSUInteger data type. Available in iOS 4.0 and later. Declared in MPMediaItem.h.
MPMediaItemPropertyComments

Textual information about the media item, corresponding to the Comments field in in the Info tab in the Get Info dialog in iTunes. Value is an NSString object. Available in iOS 4.0 and later. Declared in MPMediaItem.h.
MPMediaItemPropertyAssetURL

A URL pointing to the media item, from which an AVAsset object (or other URL-based AV Foundation object) can be created, with any options as desired. Value is an NSURL object. The URL has the custom scheme of ipod-library. For example, a URL might look like this:
ipod-library://item/item.m4a?id=12345

Usage of the URL outside of the AV Foundation framework is not supported. Available in iOS 4.0 and later. Declared in MPMediaItem.h.

Podcast Item Property Keys

You obtain metadata for a podcast media item by calling the valueForProperty method with these property keys. So-called filterable properties can also be used to build media property predicates, as described in MPMediaPropertyPredicate Class Reference .

2011-10-12 | 2011 Apple Inc. All Rights Reserved.

24

MPMediaItem Class Reference Constants

NSString *const MPMediaItemPropertyPodcastTitle;

// filterable

Constants
MPMediaItemPropertyPodcastTitle

The title of a podcast, such as This Martian Drudgery as opposed to the title of an individual episode , of a podcast such as Episode 12: Another Cold Day At The Pole (which you specify using the MPMediaItemPropertyTitle (page 21) property). Value is an NSString object. Can be used to build a media property predicate as described in MPMediaPropertyPredicate Class Reference . Available in iOS 3.0 and later. Declared in MPMediaItem.h.

User-Defined Property Keys

You obtain user-defined metadata for a media item by calling the valueForProperty: (page 12) method with these property keys. User-defined properties cannot be used to build media property predicates.
NSString NSString NSString NSString NSString *const *const *const *const *const MPMediaItemPropertyPlayCount; MPMediaItemPropertySkipCount; MPMediaItemPropertyRating; MPMediaItemPropertyLastPlayedDate; MPMediaItemPropertyUserGrouping;

Constants
MPMediaItemPropertyPlayCount

The number of times the user has played the media item. Value is an NSNumber object representing an NSUInteger data type. Available in iOS 3.0 and later. Declared in MPMediaItem.h.
MPMediaItemPropertySkipCount

The number of times the user has skipped playing the item. Value is an NSNumber object representing an NSUInteger data type. Available in iOS 3.0 and later. Declared in MPMediaItem.h.
MPMediaItemPropertyRating

The user-specified rating of the object in the range [0...5], where a value of 5 indicates the most favorable rating. Value is an NSNumber object representing an NSUInteger data type. Available in iOS 3.0 and later. Declared in MPMediaItem.h.

2011-10-12 | 2011 Apple Inc. All Rights Reserved.

25

MPMediaItem Class Reference Constants

MPMediaItemPropertyLastPlayedDate

The most recent calendar date on which the user played the media item. Value is an NSDate object. Available in iOS 3.0 and later. Declared in MPMediaItem.h.
MPMediaItemPropertyUserGrouping

Corresponds to the Grouping field in the Info tab in the Get Info dialog in iTunes. Value is an NSString object. Available in iOS 4.0 and later. Declared in MPMediaItem.h.

2011-10-12 | 2011 Apple Inc. All Rights Reserved.

26

MPMediaItemArtwork Class Reference

Inherits from Conforms to Framework Availability Declared in Companion guide Related sample code

NSObject NSObject (NSObject) /System/Library/Frameworks/MediaPlayer.framework Available in iOS 3.0 and later.

iPod Library Access Programming Guide AddMusic

Overview
An MPMediaItemArtwork object, or media item artwork, represents a graphical image, such as music album cover art, associated with a media item. Media items are described in MPMediaItem Class Reference .

Tasks
Using a Media Item Image
imageWithSize:

(page 28) Creates and returns a UIImage object of a specified size. (page 29) Initializes a media item artwork instance with a full-size image. property

initWithImage:

bounds (page 28)

The overall bounds, in points, of the image associated with the media item artwork.
imageCropRect (page 28)

property

The bounds, in points, of the content area for the full size image associated with the media item artwork.

2011-10-12 | 2011 Apple Inc. All Rights Reserved.

27

MPMediaItemArtwork Class Reference Properties

Properties
For more about Objective-C properties, see Properties in The Objective-C Programming Language .

bounds
The overall bounds, in points, of the image associated with the media item artwork.
@property (nonatomic, readonly) CGRect bounds

Availability Available in iOS 3.0 and later. Declared in

MPMediaItem.h

imageCropRect
The bounds, in points, of the content area for the full size image associated with the media item artwork.
@property (nonatomic, readonly) CGRect imageCropRect

Availability Available in iOS 3.0 and later. Declared in

MPMediaItem.h

Instance Methods
imageWithSize:
Creates and returns a UIImage object of a specified size.
- (UIImage *)imageWithSize:(CGSize)size

Parameters
size

The size, in points, for the new UIImage object. Availability Available in iOS 3.0 and later.

2011-10-12 | 2011 Apple Inc. All Rights Reserved.

28

MPMediaItemArtwork Class Reference Instance Methods

Related Sample Code AddMusic

Declared in
MPMediaItem.h

initWithImage:
Initializes a media item artwork instance with a full-size image.
- (id)initWithImage:(UIImage *)image

Parameters
image

The image to use to initialize the media item artwork instance. Discussion This method assumes that the crop rectangle of the image matches the bounds of the image, as defined by the images size in points. That is, this method assumes the image you supply is tightly cropped. Availability Available in iOS 5.0 and later. Declared in
MPMediaItem.h

2011-10-12 | 2011 Apple Inc. All Rights Reserved.

29

MPMediaItemCollection Class Reference

Inherits from Conforms to

MPMediaEntity : NSObject NSCoding (MPMediaEntity) NSObject (NSObject)

Framework Availability Declared in Companion guide Related sample code

/System/Library/Frameworks/MediaPlayer.framework Available in iOS 3.0 and later.

iPod Library Access Programming Guide AddMusic

Overview
A media item collection is a sorted set of media items (instances of the MPMediaItem class) from the iPod library. Typically, you use this class by requesting an array of collections from a media query by way of its collections property. Media queries are described in MPMediaQuery Class Reference . The grouping type for the media query determines the arrangement of the media items you obtain. You also use the media query collections property to obtain synced playlists, as described in MPMediaPlaylist Class Reference . A media item collection can have a wide range of metadata associated with it. You access this metadata using the valueForProperty: (page 12) method along with the property keys described in this document. The You can also access metadata in a batch fashion using the enumerateValuesForProperties:usingBlock: (page 11) method. In some cases, this is more efficient. Both of these methods are defined in MPMediaEntity (the abstract superclass of MPMediaItemCollection) and described in MPMediaEntity Class Reference .

2011-10-12 | 2011 Apple Inc. All Rights Reserved.

30

MPMediaItemCollection Class Reference Tasks

Tasks
Creating a Media Item Collection
+ collectionWithItems:

(page 33) Creates a media item collection by copying an array of media items. (page 34) Initializes a media item collection with an array of media items.

initWithItems:

Using a Media Item Collection

items (page 32)

property

The media items in a media item collection.

representativeItem (page 32)

property

A media item whose properties are representative of the other media items in a collection.
count (page 31)

property

The number of media items in a collection.

mediaTypes (page 32)

property

The types of the media items in a collection.

Properties
For more about Objective-C properties, see Properties in The Objective-C Programming Language .

count
The number of media items in a collection.
@property (nonatomic, readonly) NSUInteger count;

Discussion In some cases, using this property is more efficient than fetching the items array and asking for the count. Availability Available in iOS 3.0 and later.
Related Sample Code AddMusic

2011-10-12 | 2011 Apple Inc. All Rights Reserved.

31

MPMediaItemCollection Class Reference Properties

Declared in
MPMediaItemCollection.h

items
The media items in a media item collection.
@property (nonatomic, readonly) NSArray *items;

Availability Available in iOS 3.0 and later.

Related Sample Code AddMusic

Declared in
MPMediaItemCollection.h

mediaTypes
The types of the media items in a collection.
@property (nonatomic, readonly) MPMediaType mediaTypes;

Discussion The media item types are listed in the Media Item Type Flags (page 16) enumeration in MPMediaItem Class Reference . Availability Available in iOS 3.0 and later. Declared in
MPMediaItemCollection.h

representativeItem
A media item whose properties are representative of the other media items in a collection.

2011-10-12 | 2011 Apple Inc. All Rights Reserved.

32

MPMediaItemCollection Class Reference Class Methods

@property (nonatomic, readonly) MPMediaItem *representativeItem;

Discussion The media items in a collection typically share common property values, owing to how the collection was built. For example, if you build a collection based on a predicate that uses the MPMediaItemPropertyArtist property, all items in the collection share the same artist name. You can use the representativeItem property to efficiently obtain values for such common propertiesoften more efficiently than fetching an item from the items array. Availability Available in iOS 3.0 and later. Declared in
MPMediaItemCollection.h

Class Methods
collectionWithItems:
Creates a media item collection by copying an array of media items.
+ (MPMediaItemCollection *) collectionWithItems: (NSArray *) items;

Parameters
items

The array of media items you are assigning to the media item collection. Return Value A media item collection. Availability Available in iOS 3.0 and later.
Related Sample Code AddMusic

Declared in
MPMediaItemCollection.h

2011-10-12 | 2011 Apple Inc. All Rights Reserved.

33

MPMediaItemCollection Class Reference Instance Methods

Instance Methods
initWithItems:
Initializes a media item collection with an array of media items.
- (id) initWithItems: (NSArray *) items;

Parameters
items

The array of items you are assigning to the media item collection. Availability Available in iOS 3.0 and later. Declared in
MPMediaItemCollection.h

2011-10-12 | 2011 Apple Inc. All Rights Reserved.

34

MPMediaLibrary Class Reference

Inherits from Conforms to

NSObject NSCoding NSObject (NSObject)

Framework Availability Declared in Companion guide

/System/Library/Frameworks/MediaPlayer.framework Available in iOS 3.0 and later.

iPod Library Access Programming Guide

Overview
An MPMediaLibrary object, or media library, represents the state of the set of synced media items (such as songs) on a device. The complete library of media items itself is called the iPod library . A user may sync their device, changing the content of the iPod library, while your application is running. You can use the notification provided by this class to ensure that your applications cache of the iPod library is up-to-date. To retrieve media items from the iPod library, build a custom query as described in MPMediaPropertyPredicate Class Reference and MPMediaQuery Class Reference .

Tasks
Using the Default Media Library
+ defaultMediaLibrary

(page 36) Gets an instance of the default media library. property

lastModifiedDate (page 36)

The calendar date on which a media library was last modified.

2011-10-12 | 2011 Apple Inc. All Rights Reserved.

35

MPMediaLibrary Class Reference Properties

beginGeneratingLibraryChangeNotifications

(page 37) Asks a media library to turn on notifications for device-to-computer synchronizations. (page 37) Asks a media library to turn off notifications for device-to-computer synchronizations.

endGeneratingLibraryChangeNotifications

Properties
For more about Objective-C properties, see Properties in The Objective-C Programming Language .

lastModifiedDate
The calendar date on which a media library was last modified.
@property (nonatomic, readonly) NSDate *lastModifiedDate;

Availability Available in iOS 3.0 and later. Declared in

MPMediaLibrary.h

Class Methods
defaultMediaLibrary
Gets an instance of the default media library.
+ (MPMediaLibrary *)defaultMediaLibrary

Availability Available in iOS 3.0 and later. Declared in

MPMediaLibrary.h

2011-10-12 | 2011 Apple Inc. All Rights Reserved.

36

MPMediaLibrary Class Reference Instance Methods

Instance Methods
beginGeneratingLibraryChangeNotifications
Asks a media library to turn on notifications for device-to-computer synchronizations.
- (void)beginGeneratingLibraryChangeNotifications

Discussion This method is nestablethat is, you can call it multiple times. To turn off notifications, you must call endGeneratingLibraryChangeNotifications (page 37) the same number of times that you called beginGeneratingLibraryChangeNotifications. Availability Available in iOS 3.0 and later. Declared in
MPMediaLibrary.h

endGeneratingLibraryChangeNotifications
Asks a media library to turn off notifications for device-to-computer synchronizations.
- (void)endGeneratingLibraryChangeNotifications

Availability Available in iOS 3.0 and later. See Also

beginGeneratingLibraryChangeNotifications

(page 37)

Declared in
MPMediaLibrary.h

Notifications
MPMediaLibraryDidChangeNotification
When MPMediaLibraryDidChangeNotification is posted, your application should reevaluate items or playlists that you previously cached.

2011-10-12 | 2011 Apple Inc. All Rights Reserved.

37

MPMediaLibrary Class Reference Notifications

Availability Available in iOS 3.0 and later. Declared in

MPMediaLibrary.h

2011-10-12 | 2011 Apple Inc. All Rights Reserved.

38

MPMediaPickerController Class Reference

Inherits from Conforms to

UIViewController : UIResponder : NSObject NSCoding (UIViewController) UIAppearanceContainer (UIViewController) NSObject (NSObject)

Framework Availability Declared in Companion guide Related sample code

/System/Library/Frameworks/MediaPlayer.framework Available in iOS 3.0 and later.

iPod Library Access Programming Guide AddMusic

Overview
An MPMediaPickerController object, or media item picker, is a specialized view controller that you employ to provide a graphical interface for selecting media items. To display a media item picker, present it modally on an existing view controller. Media items are described in MPMediaItem Class Reference . To respond to user selections and to dismiss a media item picker, use the MPMediaPickerControllerDelegate protocol as described in MPMediaPickerControllerDelegate Protocol Reference .

2011-10-12 | 2011 Apple Inc. All Rights Reserved.

39

MPMediaPickerController Class Reference Tasks

Notes The MPMediaPickerController class supports portrait mode only. This class does support subclassing. The view hierarchy for this class is private; do not modify the view hierarchy.

Tasks
Initializing a Media Item Picker
init

(page 42) Initializes a media item picker for all media types. (page 43) Initializes a media item picker for specified media types.

initWithMediaTypes:

Using a Media Item Picker

allowsPickingMultipleItems (page 40)

property

A Boolean value specifying multiple (YES) or single (NO) selection behavior for a media item picker.
delegate (page 41)

property

The delegate for a media item picker.

mediaTypes (page 41)

property

The media types that media item picker presents.

prompt (page 42)

property

A prompt, for the user, that appears above the navigation bar buttons.

Properties
For more about Objective-C properties, see Properties in The Objective-C Programming Language .

allowsPickingMultipleItems
A Boolean value specifying multiple (YES) or single (NO) selection behavior for a media item picker.

2011-10-12 | 2011 Apple Inc. All Rights Reserved.

40

MPMediaPickerController Class Reference Properties

@property (nonatomic) BOOL allowsPickingMultipleItems;

Discussion The default behavior for a media item picker is NO, which means that the picker allows selection of only a single media item. In this instance, the button for dismissing the picker is labeled Cancel. When using the multiple-selection version, the button for dismissing the picker is labeled Done. Availability Available in iOS 3.0 and later.
Related Sample Code AddMusic

Declared in
MPMediaPickerController.h

delegate
The delegate for a media item picker.
@property (nonatomic, assign) id <MPMediaPickerControllerDelegate> delegate;

Discussion Typically, you set the delegate to be the same object that initializes and displays the media item picker. The delegate protocol is described in MPMediaPickerControllerDelegate Protocol Reference . Availability Available in iOS 3.0 and later.
Related Sample Code AddMusic

Declared in
MPMediaPickerController.h

mediaTypes
The media types that media item picker presents.
@property (nonatomic, readonly) MPMediaType mediaTypes;

Discussion The available media types are listed in the Media Item Type Flags (page 16) enumeration.

2011-10-12 | 2011 Apple Inc. All Rights Reserved.

41

MPMediaPickerController Class Reference Instance Methods

Availability Available in iOS 3.0 and later. Declared in

MPMediaPickerController.h

prompt
A prompt, for the user, that appears above the navigation bar buttons.
@property (nonatomic, copy) NSString *prompt;

Availability Available in iOS 3.0 and later.

Related Sample Code AddMusic

Declared in
MPMediaPickerController.h

Instance Methods
init
Initializes a media item picker for all media types.
- (id) init;

Discussion The default media type for a media item picker is MPMediaTypeAny (page 18). Availability Available in iOS 3.0 and later. See Also
initWithMediaTypes:

(page 43)

Declared in
MPMediaPickerController.h

2011-10-12 | 2011 Apple Inc. All Rights Reserved.

42

MPMediaPickerController Class Reference Instance Methods

initWithMediaTypes:
Initializes a media item picker for specified media types.
- (id) initWithMediaTypes: (MPMediaType) mediaTypes;

Parameters
mediaTypes

An integer representing the media types for the media item picker. See the Media Item Type Flags (page 16) enumeration. Availability Available in iOS 3.0 and later. See Also init (page 42)
Related Sample Code AddMusic

Declared in
MPMediaPickerController.h

2011-10-12 | 2011 Apple Inc. All Rights Reserved.

43

MPMediaPlaylist Class Reference

Inherits from Conforms to

MPMediaItemCollection : MPMediaEntity : NSObject NSCoding (MPMediaEntity) NSObject (NSObject)

Framework Availability Declared in Companion guide

/System/Library/Frameworks/MediaPlayer.framework Available in iOS 3.0 and later.

iPod Library Access Programming Guide

Overview
A media playlist is a playable collection of related media items. (Media items are described in MPMediaItem Class Reference .) Each playlist has a name, a set of attributes, and a unique identifier that persists across application launches. Users configure playlists using iTunes on the desktop or by creating an on-the-go playlist on the device. To your iOS application, playlists are read-only. To obtain playlists, configure a media query that is grouped by playlist. Each returned media item collection is a media playlist. The following code snippet illustrates this by logging playlist and song names to the Xcode debugger console:
MPMediaQuery *myPlaylistsQuery = [MPMediaQuery playlistsQuery]; NSArray *playlists = [myPlaylistsQuery collections];

for (MPMediaPlaylist *playlist in playlists) { NSLog (@"%@", [playlist valueForProperty: MPMediaPlaylistPropertyName]);

NSArray *songs = [playlist items]; for (MPMediaItem *song in songs) { NSString *songTitle =

2011-10-12 | 2011 Apple Inc. All Rights Reserved.

44

MPMediaPlaylist Class Reference Constants

[song valueForProperty: MPMediaItemPropertyTitle]; NSLog (@"\t\t%@", songTitle); } }

The API for building a media query is described in MPMediaPropertyPredicate Class Reference and MPMediaQuery Class Reference . The methods for querying media playlist property values are described in MPMediaEntity Class Reference .

Constants
Playlist Attribute Flags
Playlist attributes, used as possible values for the MPMediaPlaylistPropertyPlaylistAttributes (page 46) property.
enum { MPMediaPlaylistAttributeNone = 0, MPMediaPlaylistAttributeOnTheGo = (1 << 0), MPMediaPlaylistAttributeSmart = (1 << 1), MPMediaPlaylistAttributeGenius = (1 << 2) }; typedef NSInteger MPMediaPlaylistAttribute;

Constants
MPMediaPlaylistAttributeNone

If set, the playlist has no attributes. Available in iOS 3.0 and later. Declared in MPMediaPlaylist.h.
MPMediaPlaylistAttributeOnTheGo

If set, the playlist was created on a device rather than synced from iTunes. Available in iOS 3.0 and later. Declared in MPMediaPlaylist.h.
MPMediaPlaylistAttributeSmart

If set, the playlist is a smart playlist, whose members are determined by user-specified rules. Available in iOS 3.0 and later. Declared in MPMediaPlaylist.h.

2011-10-12 | 2011 Apple Inc. All Rights Reserved.

45

MPMediaPlaylist Class Reference Constants

MPMediaPlaylistAttributeGenius

If set, the playlist is a Genius playlist. Available in iOS 3.0 and later. Declared in MPMediaPlaylist.h.

Playlist Property Keys

Use these keys with the canFilterByProperty: (page 11) and valueForProperty: (page 12) methods to obtain information about a playlist. Properties described as filterable can be used to build media property predicates (see MPMediaPropertyPredicate Class Reference ).
NSString NSString NSString NSString *const *const *const *const MPMediaPlaylistPropertyPersistentID; MPMediaPlaylistPropertyName; MPMediaPlaylistPropertyPlaylistAttributes; MPMediaPlaylistPropertySeedItems; // filterable // filterable // filterable

Constants
MPMediaPlaylistPropertyPersistentID

The persistent identifier for the playlist. Value is an NSNumber object containing a UInt64_t (unsigned long long). Can be used to build a media property predicate as described in MPMediaQuery Class Reference . Available in iOS 3.0 and later. Declared in MPMediaPlaylist.h.
MPMediaPlaylistPropertyName

The name of the playlist. Value is an NSString object. Can be used to build a media property predicate as described in MPMediaQuery Class Reference . Available in iOS 3.0 and later. Declared in MPMediaPlaylist.h.
MPMediaPlaylistPropertyPlaylistAttributes

The attributes associated with the playlist. Value is an NSNumber object containing an NSInteger data type. Fields in the NSInteger identify the attributes of the playlist. A playlist may have any combination of attributes described in Playlist Attribute Flags (page 45). Can be used to build a media property predicate as described in MPMediaQuery Class Reference . Available in iOS 3.0 and later. Declared in MPMediaPlaylist.h.

2011-10-12 | 2011 Apple Inc. All Rights Reserved.

46

MPMediaPlaylist Class Reference Constants

MPMediaPlaylistPropertySeedItems

The items seeded to generate the playlist; applies only to Genius playlists. Value is an NSArray object containing one or more MPMediaItem objects. Value is nil for playlists that do not have the MPMediaPlaylistAttributeGenius (page 46) flag set. Available in iOS 3.0 and later. Declared in MPMediaPlaylist.h.

2011-10-12 | 2011 Apple Inc. All Rights Reserved.

47

MPMediaPredicate Class Reference

Inherits from Conforms to

NSObject NSCoding NSObject (NSObject)

Framework Availability Declared in Companion guide

/System/Library/Frameworks/MediaPlayer.framework Available in iOS 3.0 and later.

iPod Library Access Programming Guide

Overview
Use this classs concrete subclass, described in MPMediaPropertyPredicate Class Reference , to define the filter in a media query to retrieve a subset of media items from the iPod library. Media queries are described in MPMediaQuery Class Reference . In iPod library queries, a predicate is a statement of a logical condition that you want to test each media item against. Those media items that satisfy the condition are retrieved in the query result.

2011-10-12 | 2011 Apple Inc. All Rights Reserved.

48

MPMediaPropertyPredicate Class Reference

Inherits from Conforms to

MPMediaPredicate : NSObject NSCoding (MPMediaPredicate) NSObject (NSObject)

Framework Availability Declared in Companion guide

/System/Library/Frameworks/MediaPlayer.framework Available in iOS 3.0 and later.

iPod Library Access Programming Guide

Overview
Use one or more MPMediaPropertyPredicate objects, or media property predicates, to define the filter in a media query to retrieve a subset of media items from the iPod library. A predicate in this context is a statement of a logical condition that you want to test each media item against. Those items that satisfy the condition are retrieved in the query result. You define iPod library queries, and retrieve query results, using the MPMediaQuery class, described in MPMediaQuery Class Reference . The media items and media item collections that you retrieve with a query are described in MPMediaItem Class Reference and MPMediaItemCollection Class Reference .

Tasks
Creating Media Property Predicates
+ predicateWithValue:forProperty:

(page 51) Creates a media property predicate with the default comparison type. (page 52) Creates a media property predicate with a specified comparison type.

+ predicateWithValue:forProperty:comparisonType:

2011-10-12 | 2011 Apple Inc. All Rights Reserved.

49

MPMediaPropertyPredicate Class Reference Properties

Examining Media Property Predicates

property (page 50)

property

The property that the media property predicate uses when you invoke a query.
value (page 51)

property

The value that the media property predicate matches against when you invoke a query.
comparisonType (page 50)

property

The type of matching comparison that the media property predicate performs when you invoke a query.

Properties
For more about Objective-C properties, see Properties in The Objective-C Programming Language .

comparisonType
The type of matching comparison that the media property predicate performs when you invoke a query.
@property (nonatomic, readonly) MPMediaPredicateComparison comparisonType;

Discussion For comparison types, see Media Property Predicate Comparison Types (page 53). Availability Available in iOS 3.0 and later. Declared in
MPMediaQuery.h

property
The property that the media property predicate uses when you invoke a query.
@property (nonatomic, readonly, copy) NSString *property;

Availability Available in iOS 3.0 and later. Declared in

MPMediaQuery.h

2011-10-12 | 2011 Apple Inc. All Rights Reserved.

50

MPMediaPropertyPredicate Class Reference Class Methods

value
The value that the media property predicate matches against when you invoke a query.
@property (nonatomic, readonly) id value;

Availability Available in iOS 3.0 and later. Declared in

MPMediaQuery.h

Class Methods
predicateWithValue:forProperty:
Creates a media property predicate with the default comparison type.
+ (MPMediaPropertyPredicate *)predicateWithValue:(id)value

forProperty:(NSString *)property

Parameters
predicateWithValue:

The property value that you want to match when you query the iPod library. For example, if you specify the MPMediaItemPropertyArtist constant in the forProperty parameter, in this parameter you supply a string containing the artist name.
forProperty:

A so-called filterable propertyone that can be used to build a media property predicate. See General Media Item Property Keys (page 18) and Podcast Item Property Keys (page 24) in MPMediaItem Class Reference . Return Value A media property predicate. Discussion This is a convenience method that uses the default logical comparison type of MPMediaPredicateComparisonEqualTo (page 53). Availability Available in iOS 3.0 and later.

2011-10-12 | 2011 Apple Inc. All Rights Reserved.

51

MPMediaPropertyPredicate Class Reference Class Methods

See Also
+ predicateWithValue:forProperty:comparisonType:

(page 52)

Declared in
MPMediaQuery.h

predicateWithValue:forProperty:comparisonType:
Creates a media property predicate with a specified comparison type.
+ (MPMediaPropertyPredicate *)predicateWithValue:(id)value

forProperty:(NSString *)property comparisonType:(MPMediaPredicateComparison)comparisonType

Parameters
predicateWithValue:

The property value that you want to match when you query the iPod library. For example, if you specify the MPMediaItemPropertyArtist constant in the forProperty parameter, in this parameter you supply a string containing the artist name.
forProperty:

A so-called filterable propertyone that can be used to build a media property predicate. See General Media Item Property Keys (page 18) and Podcast Item Property Keys (page 24) in MPMediaItem Class Reference .
comparisonType:

The logical comparison type for the predicate. See Media Property Predicate Comparison Types (page 53). Return Value A media property predicate. Availability Available in iOS 3.0 and later. See Also
+ predicateWithValue:forProperty:

(page 51)

Declared in
MPMediaQuery.h

2011-10-12 | 2011 Apple Inc. All Rights Reserved.

52

MPMediaPropertyPredicate Class Reference Constants

Constants
Media Property Predicate Comparison Types
Logical comparison types for media queries.
enum { MPMediaPredicateComparisonEqualTo, MPMediaPredicateComparisonContains }; typedef NSInteger MPMediaPredicateComparison;

Constants
MPMediaPredicateComparisonEqualTo

Matches when a media items value for a given property is equal to the value in the media property predicate. Available in iOS 3.0 and later. Declared in MPMediaQuery.h.
MPMediaPredicateComparisonContains

Matches when a media items value for a given property is contained in the value of the media property predicate. Available in iOS 3.0 and later. Declared in MPMediaQuery.h.

2011-10-12 | 2011 Apple Inc. All Rights Reserved.

53

MPMediaQuery Class Reference

Inherits from Conforms to

NSObject NSCoding NSCopying NSObject (NSObject)

Framework Availability Declared in Companion guide

/System/Library/Frameworks/MediaPlayer.framework Available in iOS 3.0 and later.

iPod Library Access Programming Guide

Overview
A media query specifies a set of media items (instances of MPMediaItem) from the iPod library by way of a filter and a grouping type. Filter and grouping type are both optional; an unqualified query matches the entire library. A query has at most one grouping type. A querys filter can consist of any number of media property predicates. You build filters using methods described in MPMediaPropertyPredicate Class Reference , based on property keys described in MPMediaItem Class Reference . After creating and configuring a query, you use it to retrieve media items or media item collections. Collections are described in MPMediaItemCollection Class Reference . You can also use a query to retrieve an array of MPMediaQuerySection instances, useful for displaying the results of a query in the user interface of your app. See the itemSections (page 59) and collectionSections (page 58) properties. This class includes a number of convenience constructors that each apply a grouping type and, in most cases, match a subset of the iPod library. Table 10-1 summarizes the features of these constructors. See MPMediaItem Class Reference for descriptions of the entries in the Filter column. See Media Item Collection Grouping Keys (page 66) for descriptions of the entries in the Grouping type column.

2011-10-12 | 2011 Apple Inc. All Rights Reserved.

54

MPMediaQuery Class Reference Tasks

Table 10-1

Convenience constructors from the MPMediaQuery class Matches entire iPod library Filter Grouping type

Constructor name

albumsQuery artistsQuery audiobooksQuery compilationsQuery

MPMediaTypeMusic MPMediaTypeMusic MPMediaTypeAudioBook MPMediaTypeAny with MPMediaItemPropertyIsCompilation MPMediaTypeAny MPMediaTypeAny MPMediaTypeAny MPMediaTypePodcast MPMediaTypeMusic

MPMediaGroupingAlbum MPMediaGroupingArtist MPMediaGroupingTitle MPMediaGroupingAlbum

composersQuery genresQuery playlistsQuery podcastsQuery songsQuery

Yes Yes Yes -

MPMediaGroupingComposer MPMediaGroupingGenre MPMediaGroupingPlaylist MPMediaGroupingPodcastTitle MPMediaGroupingTitle

Tasks
Creating Media Queries
The class methods in this section create queries which you can use directly or modify as described in Configuring Media Queries (page 56). For each class method, the querys groupingType (page 59) property is set automatically according to the name of the method. For example, the albumsQuery method assigns a grouping type of MPMediaGroupingAlbum. The grouping type specifies the nature of the media item collections you can then retrieve from the query. Some class methods match the entire iPod library while others match a subset, as described in the Discussion sections for each method.
+ albumsQuery

(page 60) Creates a media query that matches music items and that groups and sorts collections by album name. (page 60) Creates a media query that matches music items and that groups and sorts collections by artist name.

+ artistsQuery

2011-10-12 | 2011 Apple Inc. All Rights Reserved.

55

MPMediaQuery Class Reference Tasks

+ songsQuery

(page 64) Creates a media query that matches music items and that groups and sorts collections by song name. (page 63) Creates a media query that matches the entire iPod library and that groups and sorts collections by playlist name. (page 63) Creates a media query that matches podcast items and that groups and sorts collections by podcast name. (page 61) Creates a media query that matches audio book items and that groups and sorts collections by audio book name. (page 61) Creates a media query that matches compilation items and that groups and sorts collections by album name. (page 62) Creates a media query that matches all media items and that groups and sorts collections by composer name. (page 62) Creates a media query that matches all media items and that groups and sorts collections by genre name. (page 65) Initializes a generic media query. (page 65) Initializes a media query with a set of media property predicates.

+ playlistsQuery

+ podcastsQuery

+ audiobooksQuery

+ compilationsQuery

+ composersQuery

+ genresQuery

init

initWithFilterPredicates:

Configuring Media Queries

filterPredicates (page 58)

property

The media property predicates of the media query.

groupingType (page 59)

property

The grouping for collections retrieved with the media query.

itemSections (page 59)

property

An array of MPMediaQuerySection instances representing the section grouping of the query's specified media items.

2011-10-12 | 2011 Apple Inc. All Rights Reserved.

56

MPMediaQuery Class Reference Properties

collectionSections (page 58)

property

An array of MPMediaQuerySection instances representing the section grouping of the query's specified media item collections.
addFilterPredicate:

(page 64) Adds a media property predicate to a query. (page 65) Removes a filter predicate from a query.

removeFilterPredicate:

Performing Media Queries

You obtain a specified array of media items or media item collections from the iPod library by calling the items (page 59) or collections (page 57) accessor methods.
items (page 59)

property

An array of media items that match the media querys predicate.

collections (page 57)

property

An array of media item collections whose contained items match the querys media property predicate.

Properties
For more about Objective-C properties, see Properties in The Objective-C Programming Language .

collections
An array of media item collections whose contained items match the querys media property predicate.
@property (nonatomic, readonly) NSArray *collections;

Discussion The returned array of collections are grouped and sorted by the groupingType of the media query. The following code snippet illustrates how to use this property:
// Specify a media query; this one matches the entire iPod library because it // does not contain a media property predicate MPMediaQuery *everything = [[MPMediaQuery alloc] init];

// Configure the media query to group its media items; here, grouped by artist [everything setGroupingType: MPMediaGroupingArtist];

2011-10-12 | 2011 Apple Inc. All Rights Reserved.

57

MPMediaQuery Class Reference Properties

// Obtain the media item collections from the query NSArray *collections = [everything collections];

Each element of the collections array now contains a media item collection. Each collection contains the media items from the iPod library by a particular artist. The elements of the array are sorted by artist name. For the available grouping types, see Media Item Collection Grouping Keys (page 66). Availability Available in iOS 3.0 and later. Declared in
MPMediaQuery.h

collectionSections
An array of MPMediaQuerySection instances representing the section grouping of the query's specified media item collections.
@property (nonatomic, readonly) NSArray *collectionSections;

Discussion The value of this property may be nil if there is no appropriate section grouping of the media item collections. Availability Available in iOS 4.2 and later. Declared in
MPMediaQuery.h

filterPredicates
The media property predicates of the media query.
@property (nonatomic, retain) NSSet *filterPredicates;

Discussion The General Media Item Property Keys (page 18) and Podcast Item Property Keys (page 24) enumerations in MPMediaItem Class Reference contain the keys you can use to construct predicates.

2011-10-12 | 2011 Apple Inc. All Rights Reserved.

58

MPMediaQuery Class Reference Properties

Availability Available in iOS 3.0 and later. Declared in

MPMediaQuery.h

groupingType
The grouping for collections retrieved with the media query.
@property (nonatomic) MPMediaGrouping groupingType;

Discussion The default grouping type is MPMediaGroupingTitle (page 66). See Media Item Collection Grouping Keys (page 66) for the list of available grouping types. Availability Available in iOS 3.0 and later. Declared in
MPMediaQuery.h

items
An array of media items that match the media querys predicate.
@property (nonatomic, readonly) NSArray *items;

Discussion If no items match the predicate, this method returns an empty array. On error, returns nil. Availability Available in iOS 3.0 and later. Declared in
MPMediaQuery.h

itemSections
An array of MPMediaQuerySection instances representing the section grouping of the query's specified media items.

2011-10-12 | 2011 Apple Inc. All Rights Reserved.

59

MPMediaQuery Class Reference Class Methods

@property (nonatomic, readonly) NSArray *itemSections;

Discussion The value of this property may be nil if there is no appropriate section grouping of the media items. Availability Available in iOS 4.2 and later. Declared in
MPMediaQuery.h

Class Methods
albumsQuery
Creates a media query that matches music items and that groups and sorts collections by album name.
+ (MPMediaQuery *)albumsQuery

Return Value A media query that matches media items of type MPMediaTypeMusic (page 17) and has a grouping type of MPMediaGroupingAlbum (page 66). Discussion A media item can have more than one media type; for example, an item could be of types music and podcast. An albumsQuery query matches all MPMediaTypeMusic items, whether or not they are also of other media types. Availability Available in iOS 3.0 and later. Declared in
MPMediaQuery.h

artistsQuery
Creates a media query that matches music items and that groups and sorts collections by artist name.
+ (MPMediaQuery *)artistsQuery

2011-10-12 | 2011 Apple Inc. All Rights Reserved.

60

MPMediaQuery Class Reference Class Methods

Return Value A media query that matches media items of type MPMediaTypeMusic (page 17) and has a grouping type of MPMediaGroupingArtist (page 67). Discussion A media item can have more than one media type; for example, an item could be of types music and podcast. An artistsQuery query matches all MPMediaTypeMusic items, whether or not they are also of other media types. Availability Available in iOS 3.0 and later. Declared in
MPMediaQuery.h

audiobooksQuery
Creates a media query that matches audio book items and that groups and sorts collections by audio book name.
+ (MPMediaQuery *)audiobooksQuery

Return Value A media query that matches media items of type MPMediaTypeAudioBook (page 17) and that uses the default grouping type of MPMediaGroupingTitle (page 66). Discussion A media item can have more than one media type; for example, an item could be of types music and podcast. An audiobooksQuery query matches all MPMediaTypeAudioBook (page 17) items, whether or not they are also of other media types. Availability Available in iOS 3.0 and later. Declared in
MPMediaQuery.h

compilationsQuery
Creates a media query that matches compilation items and that groups and sorts collections by album name.
+ (MPMediaQuery *)compilationsQuery

2011-10-12 | 2011 Apple Inc. All Rights Reserved.

61

MPMediaQuery Class Reference Class Methods

Return Value A media query that matches any media item that has the MPMediaItemPropertyIsCompilation (page 23) property; the returned query has a grouping type of MPMediaGroupingAlbum (page 66). Discussion A media item can have more than one media type; for example, an item could be of types music and podcast. A compilationsQuery query matches all media items that have the MPMediaItemPropertyIsCompilation property, irrespective of their media types. Availability Available in iOS 3.0 and later. Declared in
MPMediaQuery.h

composersQuery
Creates a media query that matches all media items and that groups and sorts collections by composer name.
+ (MPMediaQuery *)composersQuery

Return Value A media query that matches all media items and that has a grouping type of MPMediaGroupingComposer (page 67). Availability Available in iOS 3.0 and later. Declared in
MPMediaQuery.h

genresQuery
Creates a media query that matches all media items and that groups and sorts collections by genre name.
+ (MPMediaQuery *)genresQuery

Return Value A media query that matches all media items and that has a grouping type of MPMediaGroupingGenre (page 67).

2011-10-12 | 2011 Apple Inc. All Rights Reserved.

62

MPMediaQuery Class Reference Class Methods

Availability Available in iOS 3.0 and later. Declared in

MPMediaQuery.h

playlistsQuery
Creates a media query that matches the entire iPod library and that groups and sorts collections by playlist name.
+ (MPMediaQuery *)playlistsQuery

Return Value A media query that matches all media items and that has a grouping type of MPMediaGroupingPlaylist (page 67). Availability Available in iOS 3.0 and later. Declared in
MPMediaQuery.h

podcastsQuery
Creates a media query that matches podcast items and that groups and sorts collections by podcast name.
+ (MPMediaQuery *)podcastsQuery

Return Value A media query that matches media items of type MPMediaTypePodcast (page 17) and that has a grouping type of MPMediaGroupingPodcastTitle (page 67). Discussion A media item can have more than one media type; for example, an item could be of types music and podcast. A podcastsQuery query matches all MPMediaTypePodcast (page 17) items, whether or not they are also of other media types. Availability Available in iOS 3.0 and later. Declared in
MPMediaQuery.h

2011-10-12 | 2011 Apple Inc. All Rights Reserved.

63

MPMediaQuery Class Reference Instance Methods

songsQuery
Creates a media query that matches music items and that groups and sorts collections by song name.
+ (MPMediaQuery *)songsQuery

Return Value A media query that matches media items of type MPMediaTypeMusic (page 17) and has a grouping type of MPMediaGroupingTitle (page 66). Discussion A media item can have more than one media type; for example, an item could be of types music and podcast. A songsQuery query matches all MPMediaTypeMusic items, whether or not they are also of other media types. Availability Available in iOS 3.0 and later. Declared in
MPMediaQuery.h

Instance Methods
addFilterPredicate:
Adds a media property predicate to a query.
- (void)addFilterPredicate:(MPMediaPredicate *)predicate

Parameters
predicate

The media predicate to add to the set of predicates for the query. Availability Available in iOS 3.0 and later. Declared in
MPMediaQuery.h

2011-10-12 | 2011 Apple Inc. All Rights Reserved.

64

MPMediaQuery Class Reference Instance Methods

init
Initializes a generic media query.
- (id)init

Discussion A generic media query has no filter predicates and no grouping configuration. It matches everything in the iPod library and provides no grouping or sorting. Availability Available in iOS 3.0 and later. Declared in
MPMediaQuery.h

initWithFilterPredicates:
Initializes a media query with a set of media property predicates.
- (id)initWithFilterPredicates:(NSSet *)filterPredicates

Parameters
filterPredicates

The set of media property predicates to use as a filter on the iPod library. Return Value An initialized media query. Discussion MPMediaPropertyPredicate Class Reference describes how to create media property predicates. The General Media Item Property Keys (page 18) and Podcast Item Property Keys (page 24) enumerations in MPMediaItem Class Reference contain the keys you can use to construct predicates. Availability Available in iOS 3.0 and later. Declared in
MPMediaQuery.h

removeFilterPredicate:
Removes a filter predicate from a query.

2011-10-12 | 2011 Apple Inc. All Rights Reserved.

65

MPMediaQuery Class Reference Constants

- (void)removeFilterPredicate:(MPMediaPredicate *)predicate

Parameters
predicate

The media predicate to remove from the set of predicates for the query. Availability Available in iOS 3.0 and later. Declared in
MPMediaQuery.h

Constants
Media Item Collection Grouping Keys
Keys used with the groupingType property to configure a media query.
enum { MPMediaGroupingTitle, MPMediaGroupingAlbum, MPMediaGroupingArtist, MPMediaGroupingAlbumArtist, MPMediaGroupingComposer, MPMediaGroupingGenre, MPMediaGroupingPlaylist, MPMediaGroupingPodcastTitle, }; typedef NSInteger MPMediaGrouping;

Constants
MPMediaGroupingTitle

Groups and sorts media item collections by title. For songs, for example, the title is the song name. This is the default grouping key. Available in iOS 3.0 and later. Declared in MPMediaQuery.h.
MPMediaGroupingAlbum

Groups and sorts media item collections by album, and sorts songs within an album by track order. Available in iOS 3.0 and later. Declared in MPMediaQuery.h.

2011-10-12 | 2011 Apple Inc. All Rights Reserved.

66

MPMediaQuery Class Reference Constants

MPMediaGroupingArtist

Groups and sorts media item collections by performing artist. Available in iOS 3.0 and later. Declared in MPMediaQuery.h.
MPMediaGroupingAlbumArtist

Groups and sorts media item collections by album artist (the primary performing artist for an album as a whole). Available in iOS 3.0 and later. Declared in MPMediaQuery.h.
MPMediaGroupingComposer

Groups and sorts media item collections by composer. Available in iOS 3.0 and later. Declared in MPMediaQuery.h.
MPMediaGroupingGenre

Groups and sorts media item collections by musical or film genre. Available in iOS 3.0 and later. Declared in MPMediaQuery.h.
MPMediaGroupingPlaylist

Groups and sorts media item collections by playlist. Available in iOS 3.0 and later. Declared in MPMediaQuery.h.
MPMediaGroupingPodcastTitle

Groups and sorts media item collections by podcast title. Available in iOS 3.0 and later. Declared in MPMediaQuery.h. Discussion The following code snippet shows how to apply a grouping key:
MPMediaQuery *everything = [[MPMediaQuery alloc] init]; [everything setGroupingType: MPMediaGroupingAlbum]; NSArray *collections = [everything collections];

After running these code lines, the collections array contains all the matched media items grouped and sorted according to album name.

2011-10-12 | 2011 Apple Inc. All Rights Reserved.

67

MPMediaQuery Class Reference Constants

To obtain a sorted list of songs, configure a media query with the MPMediaGroupingTitle key, or take advantage of the title key being the default for a media query. In either case, each obtained media item is, in effect, its own collection. Collections sort according to the same rules used by iTunes on the desktop. This includes respecting the primary system language chosen by the user. Leading articles, including A, An, and The when using English, or L, La, and Le when using French, are ignored during sorting. If you need precise control over sorting, implement it in your application.

2011-10-12 | 2011 Apple Inc. All Rights Reserved.

68

MPMediaQuerySection Class Reference

Inherits from Conforms to

NSObject NSCoding NSCopying NSObject (NSObject)

Framework Availability Declared in Companion guide

/System/Library/Frameworks/MediaPlayer.framework Available in iOS 4.2 and later.

iPod Library Access Programming Guide

Overview
A media query section represents a range of media items or media item collections from within an iPod library media query. You can use sections when displaying a querys items or collections in your apps user interface. You obtain an array of media query sections by using the itemSections or collectionSections properties of a media query (an instance of the MPMediaQuery class). The property values of a media query section are read-only.

Tasks
Working with Media Query Sections
title (page 70)

property

The localized title of the media query section.

range (page 70)

property

The range in the media query's items or collections array that is represented by the media query section.

2011-10-12 | 2011 Apple Inc. All Rights Reserved.

69

MPMediaQuerySection Class Reference Properties

Properties
For more about Objective-C properties, see Properties in The Objective-C Programming Language .

range
The range in the media query's items or collections array that is represented by the media query section.
@property (nonatomic, assign, readonly) NSRange range

Availability Available in iOS 4.2 and later. Declared in

MPMediaQuerySection.h

title
The localized title of the media query section.
@property (nonatomic, copy, readonly) NSString *title

Availability Available in iOS 4.2 and later. Declared in

MPMediaQuerySection.h

2011-10-12 | 2011 Apple Inc. All Rights Reserved.

70

MPMovieAccessLog Class Reference

Inherits from Conforms to

NSObject NSCopying NSObject (NSObject)

Framework Availability Declared in

/System/Library/Frameworks/MediaPlayer.framework Available in iOS 4.3 and later.

Overview
A movie access log accumulates key metrics about network playback for an associated movie player that is playing streamed content. The log presents these metrics as a collection of MPMovieAccessLogEvent instances and also makes it available in a textual format. A movie access log describes one uninterrupted period of playback. A movie player (an instance of the MPMoviePlayerController class) can access this log from its setAccessLog: property. All movie access log properties are read-only.

Tasks
Movie Access Log Properties
extendedLogData (page 72)

property

A textual version of the web server access log for the associated movie player.
extendedLogDataStringEncoding (page 72)

property

The string encoding for the

events (page 72)

extendedLogData (page 72) property.

property

The events in the movie access log.

2011-10-12 | 2011 Apple Inc. All Rights Reserved.

71

MPMovieAccessLog Class Reference Properties

Properties
For more about Objective-C properties, see Properties in The Objective-C Programming Language .

events
The events in the movie access log.
@property (nonatomic, readonly) NSArray *events;

Discussion An ordered collection of MPMovieAccessLogEvent instances that represent the chronological sequence of events in the movie access log. Availability Available in iOS 4.3 and later. Declared in
MPMoviePlayerController.h

extendedLogData
A textual version of the web server access log for the associated movie player.
@property (nonatomic, readonly) NSData *extendedLogData;

Discussion The web server access log in a textual format that conforms to the W3C Extended Log File Format for web server log files. For more information, see http://www.w3.org/pub/WWW/TR/WD-logfile.html. Availability Available in iOS 4.3 and later. Declared in
MPMoviePlayerController.h

extendedLogDataStringEncoding
The string encoding for the extendedLogData (page 72) property.
@property (nonatomic, readonly) NSStringEncoding extendedLogDataStringEncoding;

2011-10-12 | 2011 Apple Inc. All Rights Reserved.

72

MPMovieAccessLog Class Reference Properties

Discussion For possible string encodings, see String_Encodings. Availability Available in iOS 4.3 and later. Declared in
MPMoviePlayerController.h

2011-10-12 | 2011 Apple Inc. All Rights Reserved.

73

MPMovieAccessLogEvent Class Reference

Inherits from Conforms to

NSObject NSCopying NSObject (NSObject)

Framework Availability Declared in

/System/Library/Frameworks/MediaPlayer.framework Available in iOS 4.3 and later.

Overview
A movie access log event represents a single piece of information for a movie access log. For a description of movie access logs, see MPMovieAccessLog Class Reference .

Tasks
Movie Access Log Event Properties
numberOfSegmentsDownloaded (page 76)

property

A count of media segments downloaded from the web server to your app.
playbackStartDate (page 78)

property

The timestamp for when playback began for the movie log access event.
URI (page 79)

property

The URI of the playback item.

serverAddress (page 79)

property

The IP address of the web server that was the source of the last delivered media segment. Can be either an IPv4 or an IPv6 address.

2011-10-12 | 2011 Apple Inc. All Rights Reserved.

74

MPMovieAccessLogEvent Class Reference Properties

numberOfServerAddressChanges (page 77)

property

A count of changes to the playback.

playbackSessionID (page 78)

serverAddress (page 79) property over the last uninterrupted period of

property

A GUID that identifies the playback session. This value is used in HTTP requests.
playbackStartOffset (page 78)

property

An offset into the playlist where the last uninterrupted period of playback began, in seconds.
segmentsDownloadedDuration (page 79)

property

The accumulated duration of the media downloaded, in seconds.

durationWatched (page 75)

property

The accumulated duration of the media played, in seconds.

numberOfStalls (page 77)

property

The total number of playback stalls encountered.

numberOfBytesTransferred (page 76)

property

The accumulated number of bytes transferred.

observedBitrate (page 77)

property

The empirical throughput across all media downloaded for the movie player, in bits per second.
indicatedBitrate (page 76)

property

The throughput required to play the stream, as advertised by the web server, in bits per second.
numberOfDroppedVideoFrames (page 76)

property

The total number of dropped video frames.

Properties
For more about Objective-C properties, see Properties in The Objective-C Programming Language .

durationWatched
The accumulated duration of the media played, in seconds.
@property (nonatomic, readonly) NSTimeInterval durationWatched;

Availability Available in iOS 4.3 and later. Declared in

MPMoviePlayerController.h

2011-10-12 | 2011 Apple Inc. All Rights Reserved.

75

MPMovieAccessLogEvent Class Reference Properties

indicatedBitrate
The throughput required to play the stream, as advertised by the web server, in bits per second.
@property (nonatomic, readonly) double indicatedBitrate;

Availability Available in iOS 4.3 and later. Declared in

MPMoviePlayerController.h

numberOfBytesTransferred
The accumulated number of bytes transferred.
@property (nonatomic, readonly) int64_t numberOfBytesTransferred;

Discussion If the number of bytes transferred is unknown, this propertys value is negative. Availability Available in iOS 4.3 and later. Declared in
MPMoviePlayerController.h

numberOfDroppedVideoFrames
The total number of dropped video frames.
@property (nonatomic, readonly) NSInteger numberOfDroppedVideoFrames;

Availability Available in iOS 4.3 and later. Declared in

MPMoviePlayerController.h

numberOfSegmentsDownloaded
A count of media segments downloaded from the web server to your app.

2011-10-12 | 2011 Apple Inc. All Rights Reserved.

76

MPMovieAccessLogEvent Class Reference Properties

@property (nonatomic, readonly) NSUInteger numberOfSegmentsDownloaded;

Availability Available in iOS 4.3 and later. Declared in

MPMoviePlayerController.h

numberOfServerAddressChanges
A count of changes to the serverAddress (page 79) property over the last uninterrupted period of playback.
@property (nonatomic, readonly) NSUInteger numberOfServerAddressChanges;

Availability Available in iOS 4.3 and later. Declared in

MPMoviePlayerController.h

numberOfStalls
The total number of playback stalls encountered.
@property (nonatomic, readonly) NSInteger numberOfStalls;

Discussion If the number of playback stalls is unknown, this propertys value is negative. Availability Available in iOS 4.3 and later. Declared in
MPMoviePlayerController.h

observedBitrate
The empirical throughput across all media downloaded for the movie player, in bits per second.
@property (nonatomic, readonly) double observedBitrate;

Availability Available in iOS 4.3 and later.

2011-10-12 | 2011 Apple Inc. All Rights Reserved.

77

MPMovieAccessLogEvent Class Reference Properties

Declared in
MPMoviePlayerController.h

playbackSessionID
A GUID that identifies the playback session. This value is used in HTTP requests.
@property (nonatomic, readonly) NSString *playbackSessionID;

Availability Available in iOS 4.3 and later. Declared in

MPMoviePlayerController.h

playbackStartDate
The timestamp for when playback began for the movie log access event.
@property (nonatomic, readonly) NSDate *playbackStartDate;

Availability Available in iOS 4.3 and later. Declared in

MPMoviePlayerController.h

playbackStartOffset
An offset into the playlist where the last uninterrupted period of playback began, in seconds.
@property (nonatomic, readonly) NSTimeInterval playbackStartOffset;

Discussion If the playback start offset is unknown, this propertys value is negative. Availability Available in iOS 4.3 and later. Declared in
MPMoviePlayerController.h

2011-10-12 | 2011 Apple Inc. All Rights Reserved.

78

MPMovieAccessLogEvent Class Reference Properties

segmentsDownloadedDuration
The accumulated duration of the media downloaded, in seconds.
@property (nonatomic, readonly) NSTimeInterval segmentsDownloadedDuration;

Discussion If the accumulated media duration is unknown, this propertys value is negative. Availability Available in iOS 4.3 and later. Declared in
MPMoviePlayerController.h

serverAddress
The IP address of the web server that was the source of the last delivered media segment. Can be either an IPv4 or an IPv6 address.
@property (nonatomic, readonly) NSString *serverAddress;

Availability Available in iOS 4.3 and later. Declared in

MPMoviePlayerController.h

URI
The URI of the playback item.
@property (nonatomic, readonly) NSString *URI;

Availability Available in iOS 4.3 and later. Declared in

MPMoviePlayerController.h

2011-10-12 | 2011 Apple Inc. All Rights Reserved.

79

MPMovieErrorLog Class Reference

Inherits from Conforms to

NSObject NSCopying NSObject (NSObject)

Framework Availability Declared in

/System/Library/Frameworks/MediaPlayer.framework Available in iOS 4.3 and later.

Overview
A movie error log contains data describing network resource playback failures for the associated movie player. The data includes timestamps indicating when each failure occurred. All movie error log properties are read-only.

Tasks
Movie Error Log Properties
extendedLogData (page 81)

property

A textual version of the web server error log.

extendedLogDataStringEncoding (page 81)

property

The string encoding for the

events (page 81)

extendedLogData (page 81) property.

property

The events in the movie error log.

2011-10-12 | 2011 Apple Inc. All Rights Reserved.

80

MPMovieErrorLog Class Reference Properties

Properties
For more about Objective-C properties, see Properties in The Objective-C Programming Language .

events
The events in the movie error log.
@property (nonatomic, readonly) NSArray *events;

Discussion An ordered collection of MPMovieErrorLogEvent instances that represent the chronological sequence of events in the movie error log. Availability Available in iOS 4.3 and later. Declared in
MPMoviePlayerController.h

extendedLogData
A textual version of the web server error log.
@property (nonatomic, readonly) NSData *extendedLogData;

Discussion The web server error log in a textual format that conforms to the W3C Extended Log File Format for web server log files. For more information, see http://www.w3.org/pub/WWW/TR/WD-logfile.html. Availability Available in iOS 4.3 and later. Declared in
MPMoviePlayerController.h

extendedLogDataStringEncoding
The string encoding for the extendedLogData (page 81) property.
@property (nonatomic, readonly) NSStringEncoding extendedLogDataStringEncoding;

Availability Available in iOS 4.3 and later.

2011-10-12 | 2011 Apple Inc. All Rights Reserved.

81

MPMovieErrorLog Class Reference Properties

Declared in
MPMoviePlayerController.h

2011-10-12 | 2011 Apple Inc. All Rights Reserved.

82

MPMovieErrorLogEvent Class Reference

Inherits from Conforms to

NSObject NSCopying NSObject (NSObject)

Framework Availability Declared in

/System/Library/Frameworks/MediaPlayer.framework Available in iOS 4.3 and later.

Overview
A movie error log event represents a single piece of information for a movie error log. For a description of movie error logs, see MPMovieErrorLog Class Reference . All movie error log event properties are read-only.

Tasks
Movie Error Log Event Properties
date (page 84)

property

The date and time when the error occurred.

URI (page 86)

property

The URI of the item being played when the error occurred.
serverAddress (page 85)

property

The IP address of the web server that was the source of the error.
playbackSessionID (page 85)

property

A GUID (globally unique identifier) for the playback session.

2011-10-12 | 2011 Apple Inc. All Rights Reserved.

83

MPMovieErrorLogEvent Class Reference Properties

errorStatusCode (page 85)

property

A unique error code identifier.

errorDomain (page 84)

property

The network domain of the error.

errorComment (page 84)

property

A description of the error.

Properties
For more about Objective-C properties, see Properties in The Objective-C Programming Language .

date
The date and time when the error occurred.
@property (nonatomic, readonly) NSDate *date;

Availability Available in iOS 4.3 and later. Declared in

MPMoviePlayerController.h

errorComment
A description of the error.
@property (nonatomic, readonly) NSString *errorComment;

Availability Available in iOS 4.3 and later. Declared in

MPMoviePlayerController.h

errorDomain
The network domain of the error.
@property (nonatomic, readonly) NSString *errorDomain;

2011-10-12 | 2011 Apple Inc. All Rights Reserved.

84

MPMovieErrorLogEvent Class Reference Properties

Availability Available in iOS 4.3 and later. Declared in

MPMoviePlayerController.h

errorStatusCode
A unique error code identifier.
@property (nonatomic, readonly) NSInteger errorStatusCode;

Discussion If the error is unknown, the value of this property is negative. Availability Available in iOS 4.3 and later. Declared in
MPMoviePlayerController.h

playbackSessionID
A GUID (globally unique identifier) for the playback session.
@property (nonatomic, readonly) NSString *playbackSessionID;

Discussion The GUID is used in HTTP requests. Availability Available in iOS 4.3 and later. Declared in
MPMoviePlayerController.h

serverAddress
The IP address of the web server that was the source of the error.
@property (nonatomic, readonly) NSString *serverAddress;

2011-10-12 | 2011 Apple Inc. All Rights Reserved.

85

MPMovieErrorLogEvent Class Reference Properties

Availability Available in iOS 4.3 and later. Declared in

MPMoviePlayerController.h

URI
The URI of the item being played when the error occurred.
@property (nonatomic, readonly) NSString *URI;

Availability Available in iOS 4.3 and later. Declared in

MPMoviePlayerController.h

2011-10-12 | 2011 Apple Inc. All Rights Reserved.

86

MPMoviePlayerController Class Reference

Inherits from Conforms to

NSObject MPMediaPlayback NSObject (NSObject)

Framework Availability Declared in Companion guide

/System/Library/Frameworks/MediaPlayer.framework Available in iOS 2.0 and later.

Multimedia Programming Guide

Overview
A movie player (of type MPMoviePlayerController) manages the playback of a movie from a file or a network stream. Playback occurs in a view owned by the movie player and takes place either fullscreen or inline. You can incorporate a movie players view into a view hierarchy owned by your app, or use an MPMoviePlayerViewController object to manage the presentation for you. Starting in iOS 4.3, movie players support wireless movie playback to AirPlay-enabled hardware such as Apple TV. To enable AirPlay playback, set the allowsAirPlay (page 94) property to YES. The movie player then presents a control that allows the user to choose AirPlay-enabled hardware for playback when such hardware is in range. When you add a movie players view to your apps view hierarchy, be sure to size the frame correctly, as shown here:
MPMoviePlayerController *player = [[MPMoviePlayerController alloc] initWithContentURL: myURL]; [player prepareToPlay]; [player.view setFrame: myView.bounds]; [myView addSubview: player.view]; // ... // player's frame must match parent's

2011-10-12 | 2011 Apple Inc. All Rights Reserved.

87

MPMoviePlayerController Class Reference Overview

[player play];

Consider a movie player view to be an opaque structure. You can add your own custom subviews to layer content on top of the movie but you must never modify any of its existing subviews. In addition to layering content on top of a movie, you can provide custom background content by adding subviews to the view in the backgroundView (page 95) property. Custom subviews are supported in both inline and fullscreen playback modes but you must adjust the positions of your views when entering or exiting fullscreen mode. Use the MPMoviePlayerWillEnterFullscreenNotification and MPMoviePlayerWillExitFullscreenNotification notifications to detect changes to and from fullscreen mode. This class supports programmatic control of movie playback, and user-based control via buttons supplied by the movie player. You can control most aspects of playback programmatically using the methods and properties of the MPMediaPlayback protocol, to which this class conforms. The methods and properties of that protocol let you start and stop playback, seek forward and backward through the movies content, and even change the playback rate. In addition, the controlStyle (page 96) property of this class lets you display a set of standard system controls that allow the user to manipulate playback. You can also set the shouldAutoplay (page 103) property for network-based content to start automatically. You typically specify the movie you want to play when you create a new MPMoviePlayerController object. However, you can also change the currently playing movie by changing the value in the contentURL (page 96) property. Changing this property lets you reuse the same movie player controller object in multiple places. For performance reasons you may want to play movies as local files. Do this by first downloading them to a local directory. Note Although you can create multiple MPMoviePlayerController objects and present their views in your interface, only one movie player at a time can play its movie.

To facilitate the creation of video bookmarks or chapter links for a long movie, the MPMoviePlayerController class defines methods for generating thumbnail images at specific times within a movie. You can request a single thumbnail image using the thumbnailImageAtTime:timeOption: (page 107) method or request multiple thumbnail images using the requestThumbnailImagesAtTimes:timeOption: (page 106) method. To play a network stream whose URL requires access credentials, first create an appropriate NSURLCredential object. Do this by calling, for example, the initWithUser:password:persistence: method, as shown here:
NSURLCredential *credential = [[NSURLCredential alloc]

2011-10-12 | 2011 Apple Inc. All Rights Reserved.

88

MPMoviePlayerController Class Reference Overview

initWithUser: @"userName" password: @"password" persistence: NSURLCredentialPersistenceForSession];

self.credential = credential; [credential release];

In addition, create an appropriate NSURLProtectionSpace object, as shown here. Make appropriate modifications for the realm you are accessing:
NSURLProtectionSpace *protectionSpace = [[NSURLProtectionSpace alloc] initWithHost: "@streams.mydomain.com" port: 80 protocol: @"http" realm: @"mydomain.com" authenticationMethod: NSURLAuthenticationMethodDefault];

self.protectionSpace = protectionSpace; [protectionSpace release];

Add the URL credential and the protection space to the Singleton NSURLCredentialStorage object. Do this by calling, for example, the setCredential:forProtectionSpace: method, as shown here:
[[NSURLCredentialStorage sharedCredentialStorage] setDefaultCredential: credential forProtectionSpace: protectionSpace];

With the credential and protection space information in place, you can then play the protected stream.

Movie Player Notifications

A movie player generates notifications to keep your app informed about the state of movie playback. In addition to being notified when playback finishes, your app can be notified in the following situations:

When the movie player begins playing, is paused, or begins seeking forward or backward When AirPlay playback starts or ends When the scaling mode of the movie changes

2011-10-12 | 2011 Apple Inc. All Rights Reserved.

89

MPMoviePlayerController Class Reference Overview

When the movie enters or exits fullscreen mode When the load state for network-based movies changes When metainformation about the movie itself becomes available

For more information, see the Notifications section in this document.

Supported Formats
This class plays any movie or audio file supported in iOS. This includes both streamed content and fixed-length files. For movie files, this typically means files with the extensions .mov, .mp4, .mpv, and .3gp and using one of the following compression standards:

H.264 Baseline Profile Level 3.0 video, up to 640 x 480 at 30 fps. (The Baseline profile does not support B frames.) MPEG-4 Part 2 video (Simple Profile)

If you use this class to play audio files, it displays a white screen with a QuickTime logo while the audio plays. For audio files, this class supports AAC-LC audio at up to 48 kHz, and MP3 (MPEG-1 Audio Layer 3) up to 48 kHz, stereo audio.

Behavior in iOS 4.3 and Earlier

In iOS 4.3 and earlier, a new movie player was automatically prepared to play. Starting in iOS 5.0, in order to facilitate finer-grained playback control, a new movie player is not automatically prepared to play. See the discussion for the initWithContentURL: (page 105) instance method.

Behavior in iOS 3.1 and Earlier

In iOS 3.1 and earlier, this class implemented a full-screen movie player only. After creating the movie player and initializing it with a single movie file, you called the play method to present the movie. (The definition of the play method has since moved out of this class and into the MPMediaPlayback protocol.) The movie player object itself handled the actual presentation of the movie content.

2011-10-12 | 2011 Apple Inc. All Rights Reserved.

90

MPMoviePlayerController Class Reference Tasks

Tasks
Creating and Initializing the Object
initWithContentURL:

(page 105)

Returns a MPMoviePlayerController object initialized with the movie at the specified URL.

Accessing Movie Properties

contentURL (page 96)

property

The URL that points to the movie file.

movieSourceType (page 100)

property

The playback type of the movie.

movieMediaTypes (page 100)

property

The types of media available in the movie. (read-only)

allowsAirPlay (page 94)

property

Specifies whether the movie player allows AirPlay movie playback.

airPlayVideoActive (page 94)

property

Indicates whether the movie player is currently playing video via AirPlay.
naturalSize (page 101)

property

The width and height of the movie frame. (read-only)

fullscreen (page 98)

property

A Boolean that indicates whether the movie player is in full-screen mode.

setFullscreen:animated:

(page 107) Causes the movie player to enter or exit full-screen mode. property

scalingMode (page 102)

The scaling mode to use when displaying the movie.

controlStyle (page 96)

property

The style of the playback controls.

useApplicationAudioSession (page 103)

property

A Boolean value that indicates whether the movie player should use the apps audio session.

2011-10-12 | 2011 Apple Inc. All Rights Reserved.

91

MPMoviePlayerController Class Reference Tasks

Accessing the Movie Duration

duration (page 96)

property

The duration of the movie, measured in seconds. (read-only)

playableDuration (page 101)

property

The amount of currently playable content. (read-only)

Accessing the View

view (page 104)

property

The view containing the movie content and controls. (read-only)

backgroundView (page 95)

property

A customizable view that is displayed behind the movie content. (read-only)

Controlling and Monitoring Playback

See also the methods of the MPMediaPlayback protocol.
loadState (page 99)

property

The network load state of the movie player. (read-only)

playbackState (page 101)

property

The current playback state of the movie player. (read-only)

initialPlaybackTime (page 98)

property

The time, specified in seconds within the video timeline, when playback should start.
endPlaybackTime (page 97)

property

The end time (measured in seconds) for playback of the movie.

shouldAutoplay (page 103)

property

A Boolean that indicates whether a movie should begin playback automatically.

repeatMode (page 102)

property

Determines how the movie player repeats the playback of the movie.
timedMetadata

(page 108) Obtains the most recent time-based metadata provided by the streamed movie.

2011-10-12 | 2011 Apple Inc. All Rights Reserved.

92

MPMoviePlayerController Class Reference Properties

Generating Thumbnail Images

thumbnailImageAtTime:timeOption:

(page 107) Captures and returns a thumbnail image from the current movie. (page 106) Captures one or more thumbnail images asynchronously from the current movie. (page 105) Cancels all pending asynchronous thumbnail image requests.

requestThumbnailImagesAtTimes:timeOption:

cancelAllThumbnailImageRequests

Retrieving Movie Logs

accessLog (page 93)

property

A snapshot of the network playback log for the movie player if it is playing a network stream.
errorLog (page 97)

property

A snapshot of the playback failure error log for the movie player if it is playing a network stream.

Unavailable Methods and Properties

The following methods and properties are no longer available as of iOS 3.2 and must not be used.
backgroundColor (page 95)

property

The color of the background area behind the movie. (Deprecated. Get the view from the backgroundView (page 95) property and set its color directly.)
movieControlMode (page 99)

property Available in iOS 2.0 through iOS 3.1

controlStyle (page 96) property instead.)

The user controls to display. (Deprecated. Use the

Properties
For more about Objective-C properties, see Properties in The Objective-C Programming Language .

accessLog
A snapshot of the network playback log for the movie player if it is playing a network stream.
@property (nonatomic, readonly) MPMovieAccessLog *accessLog

2011-10-12 | 2011 Apple Inc. All Rights Reserved.

93

MPMoviePlayerController Class Reference Properties

Discussion Can be nil. For information about movie access logs, refer to MPMovieAccessLog Class Reference . Availability Available in iOS 4.3 and later. Declared in
MPMoviePlayerController.h

airPlayVideoActive
Indicates whether the movie player is currently playing video via AirPlay.
@property (nonatomic, readonly, getter=isAirPlayVideoActive) BOOL airPlayVideoActive

Discussion You can query this property after receiving an

MPMoviePlayerIsAirPlayVideoActiveDidChangeNotification (page 119) notification to find out whether the

AirPlay video started or stopped. Availability Available in iOS 5.0 and later. Declared in
MPMoviePlayerController.h

allowsAirPlay
Specifies whether the movie player allows AirPlay movie playback.
@property (nonatomic) BOOL allowsAirPlay

Discussion A movie player supports wireless movie playback to AirPlay-enabled hardware. By default, this propertys value is NO. To enable AirPlay movie playback, set this propertys value to YES. The movie player then presents a control that allows the user to choose AirPlay-enabled hardware for playback when such hardware is in range. Availability Available in iOS 4.3 and later.

2011-10-12 | 2011 Apple Inc. All Rights Reserved.

94

MPMoviePlayerController Class Reference Properties

Declared in
MPMoviePlayerController.h

backgroundColor
The color of the background area behind the movie. (Available in iOS 2.0 through iOS 3.1. Get the view from the backgroundView (page 95) property and set its color directly.)
@property (nonatomic, retain) UIColor *backgroundColor

Discussion You should avoid using this property. It is available only when you use the initWithContentURL: (page 105) method to initialize the movie player controller object. The receiver fades to and from the background color when transitioning to and from playback. Whenever the movie does not fill the screen exactly, this color is used to fill the area between the movies frame and the edges of the screen. The default color for this property is black. You can change this to other colors (including clear) to provide a more appropriate transition from your apps content to the movie content. Availability Available in iOS 2.0 through iOS 3.1. Declared in
MPMoviePlayerController.h

backgroundView
A customizable view that is displayed behind the movie content. (read-only)
@property (nonatomic, readonly) UIView *backgroundView

Discussion This view provides the backing content, on top of which the movie content is displayed. You can add subviews to the background view if you want to display custom background content. This view is part of the view hierarchy returned by the view (page 104) property. Availability Available in iOS 3.2 and later.

2011-10-12 | 2011 Apple Inc. All Rights Reserved.

95

MPMoviePlayerController Class Reference Properties

Declared in
MPMoviePlayerController.h

contentURL
The URL that points to the movie file.
@property (nonatomic, copy) NSURL *contentURL

Discussion If you set this property while a movie is playing, that movie pauses and the new movie begins loading. The new movie starts playing at the beginning. Availability Available in iOS 2.0 and later. Declared in
MPMoviePlayerController.h

controlStyle
The style of the playback controls.
@property (nonatomic) MPMovieControlStyle controlStyle

Discussion The default value of this property is MPMovieControlStyleDefault (page 110). You can change the value of this property to change the style of the controls or to hide the controls altogether. For a list of available control styles, see MPMovieControlStyle (page 109). Availability Available in iOS 3.2 and later. Declared in
MPMoviePlayerController.h

duration
The duration of the movie, measured in seconds. (read-only)
@property (nonatomic, readonly) NSTimeInterval duration

2011-10-12 | 2011 Apple Inc. All Rights Reserved.

96

MPMoviePlayerController Class Reference Properties

Discussion If the duration of the movie is not known, the value in this property is 0.0. If the duration is subsequently determined, this property is updated and a MPMovieDurationAvailableNotification (page 117) notification is posted. Availability Available in iOS 3.2 and later. Declared in
MPMoviePlayerController.h

endPlaybackTime
The end time (measured in seconds) for playback of the movie.
@property (nonatomic) NSTimeInterval endPlaybackTime

Discussion The default value of this property is -1, which indicates the natural end time of the movie. This property is not applicable for streamed content. Availability Available in iOS 3.2 and later. Declared in
MPMoviePlayerController.h

errorLog
A snapshot of the playback failure error log for the movie player if it is playing a network stream.
@property (nonatomic, readonly) MPMovieErrorLog *errorLog

Discussion Can be nil. For information about movie error logs, refer to MPMovieErrorLog Class Reference . Availability Available in iOS 4.3 and later. Declared in
MPMoviePlayerController.h

2011-10-12 | 2011 Apple Inc. All Rights Reserved.

97

MPMoviePlayerController Class Reference Properties

fullscreen
A Boolean that indicates whether the movie player is in full-screen mode.
@property (nonatomic, getter=isFullscreen) BOOL fullscreen

Discussion The default value of this property is NO. Changing the value of this property causes the movie player to enter or exit full-screen mode immediately. If you want to animate the transition to full-screen mode, use the setFullscreen:animated: method instead. Whenever the movie player enters or exits full-screen mode, it posts appropriate notifications to reflect the change. For example, upon entering full-screen mode, it posts MPMoviePlayerWillEnterFullscreenNotification (page 122) and MPMoviePlayerDidEnterFullscreenNotification (page 119) notifications. Upon exiting from full-screen mode, it posts MPMoviePlayerWillExitFullscreenNotification (page 122) and MPMoviePlayerDidExitFullscreenNotification (page 119) notifications. The value of this property may also change as a result of the user interacting with the movie player controls. Availability Available in iOS 3.2 and later. See Also
setFullscreen:animated:

(page 107)

Declared in
MPMoviePlayerController.h

initialPlaybackTime
The time, specified in seconds within the video timeline, when playback should start.
@property (nonatomic) NSTimeInterval initialPlaybackTime

Discussion For progressively downloaded content, playback starts at the closest key frame prior to the provided time. For video-on-demand content, playback starts at the nearest segment boundary to the provided time. For live video streams, the playback start time is measured from the start of the current playlist and is rounded to the nearest segment boundary. The default value of this property is -1, which indicates the natural start time of the movie.

2011-10-12 | 2011 Apple Inc. All Rights Reserved.

98

MPMoviePlayerController Class Reference Properties

Availability Available in iOS 3.0 and later. Declared in

MPMoviePlayerController.h

loadState
The network load state of the movie player. (read-only)
@property (nonatomic, readonly) MPMovieLoadState loadState

Discussion See the MPMovieLoadState (page 108) enumeration for possible values of this property. To be notified of changes to the load state of a movie player, register for the MPMoviePlayerLoadStateDidChangeNotification (page 120) notification. Availability Available in iOS 3.2 and later. Declared in
MPMoviePlayerController.h

movieControlMode
The user controls to display. (Available in iOS 2.0 through iOS 3.1. Use the controlStyle (page 96) property instead.)
@property (nonatomic) MPMovieControlMode movieControlMode

Discussion Avoid using this property. It is available only when you use the initWithContentURL: (page 105) method to initialize the movie player controller object. Determines the control (if any) the user has over movie playback. Different modes give the user access to different sets of playback controls, some of which allow the user to pause and resume playback and some of which do not. This property is set to MPMovieControlModeDefault by default. See the MPMovieControlMode (page 117) enumeration for the available control modes. Availability Available in iOS 2.0 through iOS 3.1.

2011-10-12 | 2011 Apple Inc. All Rights Reserved.

99

MPMoviePlayerController Class Reference Properties

Declared in
MPMoviePlayerController.h

movieMediaTypes
The types of media available in the movie. (read-only)
@property (nonatomic, readonly) MPMovieMediaTypeMask movieMediaTypes

Discussion Movies can contain a combination of audio, video, or a combination of the two. The default value of this property is MPMovieMediaTypeMaskNone (page 114). See the MPMovieMediaTypeMask (page 114) enumeration for possible values of this property. Availability Available in iOS 3.2 and later. Declared in
MPMoviePlayerController.h

movieSourceType
The playback type of the movie.
@property (nonatomic) MPMovieSourceType movieSourceType

Discussion The default value of this property is MPMovieSourceTypeUnknown (page 115). This property provides a clue to the playback system as to how it should download and buffer the movie content. If you know the source type of the movie, setting the value of this property before playback begins can improve the load times for the movie content. If you do not set the source type explicitly before playback, the movie player controller must gather this information, which might delay playback. Availability Available in iOS 3.2 and later. Declared in
MPMoviePlayerController.h

2011-10-12 | 2011 Apple Inc. All Rights Reserved.

100

MPMoviePlayerController Class Reference Properties

naturalSize
The width and height of the movie frame. (read-only)
@property (nonatomic, readonly) CGSize naturalSize

Discussion This property reports the clean aperture of the video in square pixels. Thus, the reported dimensions take into account anamorphic content and aperture modes. It is possible for the natural size of a movie to change during playback. This typically happens when the bit-rate of streaming content changes or when playback toggles between audio-only and a combination of audio and video. Availability Available in iOS 3.2 and later. Declared in
MPMoviePlayerController.h

playableDuration
The amount of currently playable content. (read-only)
@property (nonatomic, readonly) NSTimeInterval playableDuration

Discussion For progressively downloaded network content, this property reflects the amount of content that can be played now. Availability Available in iOS 3.2 and later. Declared in
MPMoviePlayerController.h

playbackState
The current playback state of the movie player. (read-only)
@property (nonatomic, readonly) MPMoviePlaybackState playbackState

2011-10-12 | 2011 Apple Inc. All Rights Reserved.

101

MPMoviePlayerController Class Reference Properties

Discussion The playback state is affected by programmatic calls to play, pause, or stop the movie player. It can also be affected by user interactions or by the network, in cases where streaming content cannot be buffered fast enough. See the MPMoviePlaybackState (page 111) enumeration for possible values of this property. To be notified of changes to the playback state of a movie player, register for the MPMoviePlayerPlaybackStateDidChangeNotification (page 121) notification. Availability Available in iOS 3.2 and later. Declared in
MPMoviePlayerController.h

repeatMode
Determines how the movie player repeats the playback of the movie.
@property (nonatomic) MPMovieRepeatMode repeatMode

Discussion The default value of this property is MPMovieRepeatModeNone (page 112). For a list of available repeat modes, see MPMovieRepeatMode (page 112). Availability Available in iOS 3.2 and later. Declared in
MPMoviePlayerController.h

scalingMode
The scaling mode to use when displaying the movie.
@property (nonatomic) MPMovieScalingMode scalingMode

Discussion Changing this property while the movie player is visible causes the current movie to animate to the new scaling mode.

2011-10-12 | 2011 Apple Inc. All Rights Reserved.

102

MPMoviePlayerController Class Reference Properties

The default value of this property is MPMovieScalingModeAspectFit. For a list of available scaling modes, see MPMovieScalingMode (page 112). Availability Available in iOS 2.0 and later. Declared in
MPMoviePlayerController.h

shouldAutoplay
A Boolean that indicates whether a movie should begin playback automatically.
@property (nonatomic) BOOL shouldAutoplay

Discussion The default value of this property is YES. This property determines whether the playback of network-based content begins automatically when there is enough buffered data to ensure uninterrupted playback. Availability Available in iOS 3.2 and later. Declared in
MPMoviePlayerController.h

useApplicationAudioSession
A Boolean value that indicates whether the movie player should use the apps audio session.
@property (nonatomic) BOOL useApplicationAudioSession

Discussion The default value of this property is YES. Setting this property to NO causes the movie player to use a system-supplied audio session with a nonmixable playback category. Important In iOS 3.1 and earlier, a movie player always uses a system-supplied audio session. To obtain that same behavior in iOS 3.2 and newer, you must set this propertys value to NO. When this property is YES, the movie player shares the apps audio session. This give you control over how the movie player content interacts with your audio and with audio from other apps, such as the iPod. For important guidance on using this feature, see Working with Movies and iPod Music in Audio Session Programming Guide .

2011-10-12 | 2011 Apple Inc. All Rights Reserved.

103

MPMoviePlayerController Class Reference Properties

Changing the value of this property does not affect the currently playing movie. For the new setting to take effect, you must stop playback and then start it again. Availability Available in iOS 3.2 and later. Declared in
MPMoviePlayerController.h

view
The view containing the movie content and controls. (read-only)
@property (nonatomic, readonly) UIView *view

Discussion This property contains the view used for presenting the video content. This view incorporates all the background, content, and controls needed to display movies. You can incorporate this view into your own view hierarchies or present it by itself using a view controller. To embed the view into your own view hierarchies, add it as a subview to one of your existing views. A good place to do this is in the loadView or viewDidLoad method of the custom view controller that presents your view hierarchy. You are free to change the views frame rectangle to accommodate the space available in your view hierarchy. The movie player uses the value in the scalingMode (page 102) property to scale the movie content to match the frame you specify. If you want to present the view by itselfthat is, without embedding it in an existing view hierarchyyou can use an instance of the MPMoviePlayerViewController class to manage the presentation of the view. That class works directly with the movie player controller to present the view by itself. You can add subviews to the view in this property. You might do this in cases where you want to display custom playback controls or add other custom content that is relevant to your app. Availability Available in iOS 3.2 and later. See Also
@property backgroundView (page 95)

Declared in
MPMoviePlayerController.h

2011-10-12 | 2011 Apple Inc. All Rights Reserved.

104

MPMoviePlayerController Class Reference Instance Methods

Instance Methods
cancelAllThumbnailImageRequests
Cancels all pending asynchronous thumbnail image requests.
- (void)cancelAllThumbnailImageRequests

Discussion This method cancels only requests made using the requestThumbnailImagesAtTimes:timeOption: (page 106) method. It does not cancel requests made synchronously using the thumbnailImageAtTime:timeOption: (page 107) method. Availability Available in iOS 3.2 and later. Declared in
MPMoviePlayerController.h

initWithContentURL:
Returns a MPMoviePlayerController object initialized with the movie at the specified URL.
- (id)initWithContentURL:(NSURL *)url

Parameters
url

The location of the movie file. This file must be located either in your app directory or on a remote server. Return Value The movie player object. Discussion This method initializes a movie player in full-screen mode, but does not prepare it for playback. To prepare a new movie player for playback, call the prepareToPlay (page 169) method, described in MPMediaPlayback Protocol Reference . To be notified when a new movie player is ready to play, register for the MPMoviePlayerLoadStateDidChangeNotification (page 120) notification. You can then check load state by accessing the loadState (page 99) property.

2011-10-12 | 2011 Apple Inc. All Rights Reserved.

105

MPMoviePlayerController Class Reference Instance Methods

To check for errors in URL loading, register for the MPMoviePlayerPlaybackDidFinishNotification (page 120) notification. On error, this notification contains an NSError object available using the @"error" key in the notifications userInfo dictionary. If you pass nil in the url parameter of this method, or call the init method on a movie player, the system throws an exception. Availability Available in iOS 2.0 and later. Declared in
MPMoviePlayerController.h

requestThumbnailImagesAtTimes:timeOption:
Captures one or more thumbnail images asynchronously from the current movie.
- (void)requestThumbnailImagesAtTimes:(NSArray *)playbackTimes

timeOption:(MPMovieTimeOption)option

Parameters
playbackTimes

An array of NSNumber objects containing the times at which to capture the thumbnail images. Each time value represents the number of seconds from the beginning of the current movie.
option

The option to use when determining which specific frame to use for each thumbnail image. For a list of possible values, see MPMovieTimeOption (page 113). Discussion This method processes each thumbnail request separately and asynchronously. When the results for a single image arrive, the movie player posts a MPMoviePlayerThumbnailImageRequestDidFinishNotification (page 121) notification with the results for that image. Notifications are posted regardless of whether the image capture was successful or failed. You should register for this notification prior to calling this method. Availability Available in iOS 3.2 and later. Declared in
MPMoviePlayerController.h

2011-10-12 | 2011 Apple Inc. All Rights Reserved.

106

MPMoviePlayerController Class Reference Instance Methods

setFullscreen:animated:
Causes the movie player to enter or exit full-screen mode.
- (void)setFullscreen:(BOOL)fullscreen

animated:(BOOL)animated

Parameters
fullscreen

Specify YES to enter full-screen mode or NO to exit full-screen mode.

animated

Specify YES to animate the transition between modes or NO to switch immediately to the new mode. Availability Available in iOS 3.2 and later. See Also
@property fullscreen (page 98)

Declared in
MPMoviePlayerController.h

thumbnailImageAtTime:timeOption:
Captures and returns a thumbnail image from the current movie.
- (UIImage *)thumbnailImageAtTime:(NSTimeInterval)playbackTime

timeOption:(MPMovieTimeOption)option

Parameters
playbackTime

The time at which to capture the thumbnail image. The time value represents the number of seconds from the beginning of the current movie.
option

The option to use when determining which specific frame to use for the thumbnail image. For a list of possible values, see MPMovieTimeOption (page 113). Return Value An image object containing the image from the movie or nil if the thumbnail could not be captured. Discussion This method captures the thumbnail image synchronously from the current movie (which is accessible from the MPMovieSourceTypeUnknown (page 115) property).

2011-10-12 | 2011 Apple Inc. All Rights Reserved.

107

MPMoviePlayerController Class Reference Constants

Availability Available in iOS 3.2 and later. Declared in

MPMoviePlayerController.h

timedMetadata
Obtains the most recent time-based metadata provided by the streamed movie.
- (NSArray *)timedMetadata

Return Value An array of the most recent MPTimedMetadata objects provided by the streamed movie. Availability Available in iOS 4.0 and later. Declared in
MPMoviePlayerController.h

Constants
MPMovieLoadState
Constants describing the network load state of the movie player.
enum { MPMovieLoadStateUnknown = MPMovieLoadStatePlayable = MPMovieLoadStatePlaythroughOK = MPMovieLoadStateStalled = }; typedef NSInteger MPMovieLoadState;

0, 1 << 0, 1 << 1, 1 << 2,

Constants
MPMovieLoadStateUnknown

The load state is not known. Available in iOS 3.2 and later. Declared in MPMoviePlayerController.h.

2011-10-12 | 2011 Apple Inc. All Rights Reserved.

108

MPMoviePlayerController Class Reference Constants

MPMovieLoadStatePlayable

The buffer has enough data that playback can begin, but it may run out of data before playback finishes. Available in iOS 3.2 and later. Declared in MPMoviePlayerController.h.
MPMovieLoadStatePlaythroughOK

Enough data has been buffered for playback to continue uninterrupted. Available in iOS 3.2 and later. Declared in MPMoviePlayerController.h.
MPMovieLoadStateStalled

The buffering of data has stalled. If started now, playback may pause automatically if the player runs out of buffered data. Available in iOS 3.2 and later. Declared in MPMoviePlayerController.h.

MPMovieControlStyle
Constants describing the style of the playback controls.
enum { MPMovieControlStyleNone, MPMovieControlStyleEmbedded, MPMovieControlStyleFullscreen, MPMovieControlStyleDefault = MPMovieControlStyleFullscreen }; typedef NSInteger MPMovieControlStyle;

Constants
MPMovieControlStyleNone

No controls are displayed. Available in iOS 3.2 and later. Declared in MPMoviePlayerController.h.
MPMovieControlStyleEmbedded

Controls for an embedded view are displayed. The controls include a start/pause button, a scrubber bar, and a button for toggling between fullscreen and embedded display modes. Available in iOS 3.2 and later. Declared in MPMoviePlayerController.h.

2011-10-12 | 2011 Apple Inc. All Rights Reserved.

109

MPMoviePlayerController Class Reference Constants

MPMovieControlStyleFullscreen

Controls for fullscreen playback are displayed. The controls include a start/pause button, a scrubber bar, forward and reverse seeking buttons, a button for toggling between fullscreen and embedded display modes, a button for toggling the aspect fill mode, and a Done button. Tapping the done button pauses the video and exits fullscreen mode. Available in iOS 3.2 and later. Declared in MPMoviePlayerController.h.
MPMovieControlStyleDefault

Fullscreen controls are displayed by default. Available in iOS 3.2 and later. Declared in MPMoviePlayerController.h.

MPMovieFinishReason
Constants describing the reason that playback ended.
enum { MPMovieFinishReasonPlaybackEnded, MPMovieFinishReasonPlaybackError, MPMovieFinishReasonUserExited }; typedef NSInteger MPMovieFinishReason;

Constants
MPMovieFinishReasonPlaybackEnded

The end of the movie was reached. Available in iOS 3.2 and later. Declared in MPMoviePlayerController.h.
MPMovieFinishReasonPlaybackError

There was an error during playback. Available in iOS 3.2 and later. Declared in MPMoviePlayerController.h.
MPMovieFinishReasonUserExited

The user stopped playback. Available in iOS 3.2 and later. Declared in MPMoviePlayerController.h.

2011-10-12 | 2011 Apple Inc. All Rights Reserved.

110

MPMoviePlayerController Class Reference Constants

MPMoviePlaybackState
Constants describing the current playback state of the movie player.
enum { MPMoviePlaybackStateStopped, MPMoviePlaybackStatePlaying, MPMoviePlaybackStatePaused, MPMoviePlaybackStateInterrupted, MPMoviePlaybackStateSeekingForward, MPMoviePlaybackStateSeekingBackward }; typedef NSInteger MPMoviePlaybackState;

Constants
MPMoviePlaybackStateStopped

Playback is currently stopped. Playback will commence from the beginning of the movie. Available in iOS 3.2 and later. Declared in MPMoviePlayerController.h.
MPMoviePlaybackStatePlaying

Playback is currently under way. Available in iOS 3.2 and later. Declared in MPMoviePlayerController.h.
MPMoviePlaybackStatePaused

Playback is currently paused. Playback will resume from the point where it was paused. Available in iOS 3.2 and later. Declared in MPMoviePlayerController.h.
MPMoviePlaybackStateInterrupted

Playback is temporarily interrupted, perhaps because the buffer ran out of content. Available in iOS 3.2 and later. Declared in MPMoviePlayerController.h.
MPMoviePlaybackStateSeekingForward

The movie player is currently seeking towards the end of the movie. Available in iOS 3.2 and later. Declared in MPMoviePlayerController.h.
MPMoviePlaybackStateSeekingBackward

The movie player is currently seeking towards the beginning of the movie. Available in iOS 3.2 and later. Declared in MPMoviePlayerController.h.

2011-10-12 | 2011 Apple Inc. All Rights Reserved.

111

MPMoviePlayerController Class Reference Constants

MPMovieRepeatMode
Constants describing how the movie player repeats content at the end of playback.
enum { MPMovieRepeatModeNone, MPMovieRepeatModeOne }; typedef NSInteger MPMovieRepeatMode;

Constants
MPMovieRepeatModeNone

Content is not repeated when playback finishes Available in iOS 3.2 and later. Declared in MPMoviePlayerController.h.
MPMovieRepeatModeOne

The current movie is repeated when it finishes. Available in iOS 3.2 and later. Declared in MPMoviePlayerController.h.

MPMovieScalingMode
Constants describing how the movie content is scaled to fit the frame of its view.
typedef enum { MPMovieScalingModeNone, MPMovieScalingModeAspectFit, MPMovieScalingModeAspectFill, MPMovieScalingModeFill } MPMovieScalingMode;

Constants
MPMovieScalingModeNone

Do not scale the movie. Available in iOS 2.0 and later. Declared in MPMoviePlayerController.h.

2011-10-12 | 2011 Apple Inc. All Rights Reserved.

112

MPMoviePlayerController Class Reference Constants

MPMovieScalingModeAspectFit

Scale the movie uniformly until one dimension fits the visible bounds of the view exactly. In the other dimension, the region between the edge of the movie and the edge of the view is filled with a black bar. The aspect ratio of the movie is preserved. Available in iOS 2.0 and later. Declared in MPMoviePlayerController.h.
MPMovieScalingModeAspectFill

Scale the movie uniformly until the movie fills the visible bounds of the view. Content at the edges of the larger of the two dimensions is clipped so that the other dimension fits the view exactly. The aspect ratio of the movie is preserved. Available in iOS 2.0 and later. Declared in MPMoviePlayerController.h.
MPMovieScalingModeFill

Scale the movie until both dimensions fit the visible bounds of the view exactly. The aspect ratio of the movie is not preserved. Available in iOS 2.0 and later. Declared in MPMoviePlayerController.h.

MPMovieTimeOption
Constants describing which frame to use when generating thumbnail images.
enum { MPMovieTimeOptionNearestKeyFrame, MPMovieTimeOptionExact }; typedef NSInteger MPMovieTimeOption;

Constants
MPMovieTimeOptionNearestKeyFrame

Generate a thumbnail image using the nearest key frame. This frame could be several frames away from the current frame. This option generally offers better performance than trying to find the exact frame. Available in iOS 3.2 and later. Declared in MPMoviePlayerController.h.
MPMovieTimeOptionExact

Use the exact current frame. Available in iOS 3.2 and later. Declared in MPMoviePlayerController.h.

2011-10-12 | 2011 Apple Inc. All Rights Reserved.

113

MPMoviePlayerController Class Reference Constants

MPMovieMediaTypeMask
Specifies the types of content available in the movie file.
enum { MPMovieMediaTypeMaskNone = 0, MPMovieMediaTypeMaskVideo = 1 << 0, MPMovieMediaTypeMaskAudio = 1 << 1 }; typedef NSInteger MPMovieMediaTypeMask;

Constants
MPMovieMediaTypeMaskNone

The types of media available in the media are not yet known. Available in iOS 3.2 and later. Declared in MPMoviePlayerController.h.
MPMovieMediaTypeMaskVideo

The movie file contains video media. Available in iOS 3.2 and later. Declared in MPMoviePlayerController.h.
MPMovieMediaTypeMaskAudio

The movie file contains audio media. Available in iOS 3.2 and later. Declared in MPMoviePlayerController.h. Discussion You can OR the specified constants together to specify a movie

MPMovieSourceType
Specifies the type of the movie file.

2011-10-12 | 2011 Apple Inc. All Rights Reserved.

114

MPMoviePlayerController Class Reference Constants

enum { MPMovieSourceTypeUnknown, MPMovieSourceTypeFile, MPMovieSourceTypeStreaming }; typedef NSInteger MPMovieSourceType;

Constants
MPMovieSourceTypeUnknown

The movie type is not yet known. Available in iOS 3.2 and later. Declared in MPMoviePlayerController.h.
MPMovieSourceTypeFile

The movie is a local file or is a file that can be downloaded from the network. Available in iOS 3.2 and later. Declared in MPMoviePlayerController.h.
MPMovieSourceTypeStreaming

The movie is a live or on-demand stream. Available in iOS 3.2 and later. Declared in MPMoviePlayerController.h.

Thumbnail Notification User Info Keys

The following keys may be found in the userInfo dictionary of a
MPMoviePlayerThumbnailImageRequestDidFinishNotification (page 121) notification. NSString *const MPMoviePlayerThumbnailImageKey; NSString *const MPMoviePlayerThumbnailTimeKey; NSString *const MPMoviePlayerThumbnailErrorKey;

Constants
MPMoviePlayerThumbnailImageKey

The value of this key is a UIImage object containing the image that was obtained for the desired frame. Available in iOS 3.2 and later. Declared in MPMoviePlayerController.h.
MPMoviePlayerThumbnailTimeKey

The value of this key is a NSNumber object containing a double value. This value represents the actual time (measured in seconds) from the beginning of the movie at which the image was captured. Available in iOS 3.2 and later. Declared in MPMoviePlayerController.h.

2011-10-12 | 2011 Apple Inc. All Rights Reserved.

115

MPMoviePlayerController Class Reference Constants

MPMoviePlayerThumbnailErrorKey

The value of this key is an NSError object identifying the error that occurred, if any. Available in iOS 3.2 and later. Declared in MPMoviePlayerController.h.

Fullscreen Notification Keys

The following keys may be found in the userInfo dictionary of notifications for transitioning in or out of full-screen mode.
NSString *const MPMoviePlayerFullscreenAnimationDurationUserInfoKey; NSString *const MPMoviePlayerFullscreenAnimationCurveUserInfoKey;

Constants
MPMoviePlayerFullscreenAnimationDurationUserInfoKey

The value of this key is an NSNumber containing a double value. This value represents the duration (measured in seconds) of the animation used to transition in or out of full-screen mode. Available in iOS 3.2 and later. Declared in MPMoviePlayerController.h.
MPMoviePlayerFullscreenAnimationCurveUserInfoKey

The value of this key is an NSNumber containing an integer value that represents one of the UIViewAnimationCurve constants. Available in iOS 3.2 and later. Declared in MPMoviePlayerController.h.

Playback Finished Notification Key

The following key may be found in the userInfo dictionary of a
MPMoviePlayerPlaybackDidFinishNotification (page 120) notification. NSString *const MPMoviePlayerPlaybackDidFinishReasonUserInfoKey;

Constants
MPMoviePlayerPlaybackDidFinishReasonUserInfoKey

The value of this key is an NSNumber containing an integer value that represents one of the MPMovieFinishReason (page 110) constants. Available in iOS 3.2 and later. Declared in MPMoviePlayerController.h.

2011-10-12 | 2011 Apple Inc. All Rights Reserved.

116

MPMoviePlayerController Class Reference Notifications

MPMovieControlMode
Optionsfordisplayingmovieplaybackcontrols.(Deprecated.Usethe MPMovieControlStyle (page 109) constants in conjunction with the controlStyle (page 96) property instead.)
typedef enum { MPMovieControlModeDefault, MPMovieControlModeVolumeOnly, MPMovieControlModeHidden } MPMovieControlMode;

Constants
MPMovieControlModeDefault

Display the standard controls for controlling playback. This includes play/pause controls, a volume slider, and a timeline control. Available in iOS 2.0 and later. Declared in MPMoviePlayerController.h.
MPMovieControlModeVolumeOnly

Display volume controls only. Available in iOS 2.0 and later. Declared in MPMoviePlayerController.h.
MPMovieControlModeHidden

Do not display any controls. This mode prevents the user from controlling playback. Available in iOS 2.0 and later. Declared in MPMoviePlayerController.h.

Notifications
To be notified of changes in movie player state such as playability, or changes in the availability of movie information such as duration, register for the appropriate notification. For all movie player notifications, the movie player whose state has changed is available as the object associated with the notification.

MPMovieDurationAvailableNotification
Posted when the duration of a movie has been determined. There is no userInfo dictionary. To retrieve the duration of a movie, access the movie players duration (page 96) property. The movie player whose state has changed is available as the object associated with the notification. Availability Available in iOS 3.2 and later.

2011-10-12 | 2011 Apple Inc. All Rights Reserved.

117

MPMoviePlayerController Class Reference Notifications

Declared in
MPMoviePlayerController.h

MPMovieMediaTypesAvailableNotification
Posted when the available media types in a movie are determined. There is no userInfo dictionary. To retrieve the available media types in a movieaudio, video, or bothaccess the movie players movieMediaTypes (page 100) property. The movie player whose state has changed is available as the object associated with the notification. Availability Available in iOS 3.2 and later. Declared in
MPMoviePlayerController.h

MPMovieNaturalSizeAvailableNotification
Posted when the natural frame size of a movie is first determined or subsequently changes. There is no userInfo dictionary. To retrieve the natural frame size for a movie, access the movie players naturalSize (page 101) property. The movie player whose state has changed is available as the object associated with the notification. Availability Available in iOS 3.2 and later. Declared in
MPMoviePlayerController.h

MPMoviePlayerContentPreloadDidFinishNotification
Posted when a movie is in memory and ready to play. The movie player whose state has changed is available as the object associated with the notification. If an error occurred during loading, the userInfo dictionary of this notification contains a key with the name error whose value is the NSError object describing the problem. (#Deprecated. Use the MPMoviePlayerLoadStateDidChangeNotification (page 120) notification to determine the readiness of the player.) Availability Available in iOS 2.0 and later.

2011-10-12 | 2011 Apple Inc. All Rights Reserved.

118

MPMoviePlayerController Class Reference Notifications

Deprecated in iOS 3.2. Declared in

MPMoviePlayerController.h

MPMoviePlayerDidEnterFullscreenNotification
Posted when a movie player has entered full-screen mode. There is no userInfo dictionary. A movie player can enter full screen mode programmatically (see the setFullscreen:animated: (page 107) method) or by user interaction. The movie player whose state has changed is available as the object associated with the notification. Availability Available in iOS 3.2 and later. Declared in
MPMoviePlayerController.h

MPMoviePlayerDidExitFullscreenNotification
Posted when a movie player has exited full-screen mode. There is no userInfo dictionary. A movie player can exit full screen mode programmatically (see the setFullscreen:animated: (page 107) method) or by user interaction. The movie player whose state has changed is available as the object associated with the notification. Availability Available in iOS 3.2 and later. Declared in
MPMoviePlayerController.h

MPMoviePlayerIsAirPlayVideoActiveDidChangeNotification
Posted when a movie player has started or ended playing a movie via AirPlay. There is no userInfo dictionary. To find out whether AirPlay playback started or stopped, query the airPlayVideoActive (page 94) property. The movie player whose state has changed is available as the object associated with the notification. Availability Available in iOS 5.0 and later.

2011-10-12 | 2011 Apple Inc. All Rights Reserved.

119

MPMoviePlayerController Class Reference Notifications

Declared in
MPMoviePlayerController.h

MPMoviePlayerLoadStateDidChangeNotification
Posted when a movie players network buffering state has changed. There is no userInfo dictionary. To retrieve the current load state of a movie player, access its loadState (page 99) property. The movie player whose state has changed is available as the object associated with the notification. Availability Available in iOS 3.2 and later. Declared in
MPMoviePlayerController.h

MPMoviePlayerNowPlayingMovieDidChangeNotification
Posted when the currently playing movie has changed. There is no userInfo dictionary. To retrieve the URL for currently playing movie, access the movie players contentURL (page 96) property. The movie player whose state has changed is available as the object associated with the notification. Availability Available in iOS 3.2 and later. Declared in
MPMoviePlayerController.h

MPMoviePlayerPlaybackDidFinishNotification
Posted when a movie has finished playing. The userInfo dictionary of this notification contains the MPMoviePlayerPlaybackDidFinishReasonUserInfoKey (page 116) key,whichindicatesthereasonthatplayback finished. This notification is also sent when playback fails because of an error. The movie player whose state has changed is available as the object associated with the notification. This notification is not sent when a movie is displaying in fullscreen mode and the user taps Done. The Done button pauses playback and causes the movie player to exit fullscreen mode. To detect this scenario, register for other notifications such as MPMoviePlayerDidExitFullscreenNotification (page 119).

2011-10-12 | 2011 Apple Inc. All Rights Reserved.

120

MPMoviePlayerController Class Reference Notifications

Availability Available in iOS 2.0 and later. Declared in

MPMoviePlayerController.h

MPMoviePlayerPlaybackStateDidChangeNotification
Posted when a movie players playback state has changed. There is no userInfo dictionary. Playback state can change programmatically (see MPMediaPlayback Protocol Reference ) or by user interaction. To retrieve the playback state of a movie player, access its playbackState (page 101) property. The movie player whose state has changed is available as the object associated with the notification. Availability Available in iOS 3.2 and later. Declared in
MPMoviePlayerController.h

MPMoviePlayerScalingModeDidChangeNotification
Posted when the scaling mode of a movie player has changed. There is no userInfo dictionary. Scaling mode can change programmatically or by user interaction. To set or retrieve the scaling mode of a movie player, access its scalingMode (page 102) property. The movie player whose state has changed is available as the object associated with the notification. Availability Available in iOS 2.0 and later. Declared in
MPMoviePlayerController.h

MPMoviePlayerThumbnailImageRequestDidFinishNotification
Posted when a request to capture a thumbnail from a movie has finished whether the request succeeded or failed. Upon successful capture of a thumbnail, the userInfo dictionary contains values for the following keys:

MPMoviePlayerThumbnailImageKey (page 115) MPMoviePlayerThumbnailTimeKey (page 115)

2011-10-12 | 2011 Apple Inc. All Rights Reserved.

121

MPMoviePlayerController Class Reference Notifications

If the capture request finished with an error, the userInfo dictionary contains values for the following two keys:

MPMoviePlayerThumbnailErrorKey (page 116) MPMoviePlayerThumbnailTimeKey (page 115)

The movie player whose state has changed is available as the object associated with the notification. The methods to use for capturing movie thumbnails are described in Generating Thumbnail Images (page 93). Availability Available in iOS 3.2 and later. Declared in
MPMoviePlayerController.h

MPMoviePlayerWillEnterFullscreenNotification
Posted when a movie player is about to enter full-screen mode. The userInfo dictionary contains keys whose values describe the transition animation used to enter full-screen mode. See Fullscreen Notification Keys (page 116). A movie player can enter full screen mode programmatically (see the setFullscreen:animated: (page 107) method) or by user interaction. The movie player whose state has changed is available as the object associated with the notification. Availability Available in iOS 3.2 and later. Declared in
MPMoviePlayerController.h

MPMoviePlayerWillExitFullscreenNotification
Posted when a movie player is about to exit full-screen mode. The userInfo dictionary contains keys whose values describe the transition animation used to exit full-screen mode. See Fullscreen Notification Keys (page 116). A movie player can exit full screen mode programmatically (see the setFullscreen:animated: (page 107) method) or by user interaction. The movie player whose state has changed is available as the object associated with the notification.

2011-10-12 | 2011 Apple Inc. All Rights Reserved.

122

MPMoviePlayerController Class Reference Notifications

Availability Available in iOS 3.2 and later. Declared in

MPMoviePlayerController.h

MPMovieSourceTypeAvailableNotification
Posted when the source type of a movie was previously unknown and is newly available. There is no userInfo dictionary. To retrieve the source type of the movie, access the movie players movieSourceType (page 100) property. The movie player whose state has changed is available as the object associated with the notification. Availability Available in iOS 3.2 and later. Declared in
MPMoviePlayerController.h

2011-10-12 | 2011 Apple Inc. All Rights Reserved.

123

MPMoviePlayerViewController Class Reference

Inherits from Conforms to

UIViewController : UIResponder : NSObject NSCoding (UIViewController) UIAppearanceContainer (UIViewController) NSObject (NSObject)

Framework Availability Declared in

/System/Library/Frameworks/MediaPlayer.framework Available in iOS 3.2 and later.

Overview
The MPMoviePlayerViewController class implements a simple view controller for displaying full-screen movies. Unlike using an MPMoviePlayerController object on its own to present a movie immediately, you can incorporate a movie player view controller wherever you would normally use a view controller. For example, you can present it using a tab bar or navigation bar-based interface, taking advantage of the transitions offered by those interfaces. To present a movie player view controller modally, you typically use the presentMoviePlayerViewControllerAnimated: (page 160) method. This method is part of a category on the UIViewController class and is implemented by the Media Player framework. The presentMoviePlayerViewControllerAnimated: method presents a movie player view controller using the standard transition animations for presenting video content. To dismiss a modally presented movie player view controller, call the dismissMoviePlayerViewControllerAnimated (page 159) method.

2011-10-12 | 2011 Apple Inc. All Rights Reserved.

124

MPMoviePlayerViewController Class Reference Tasks

Tasks
New Methods
initWithContentURL:

(page 125) Returns a movie player view controller initialized with the specified movie. property

moviePlayer (page 125)

The movie player controller object used to present the movie. (read-only)
shouldAutorotateToInterfaceOrientation:

(page 126) Returns a Boolean value indicating whether the view controller supports the specified orientation.

Properties
For more about Objective-C properties, see Properties in The Objective-C Programming Language .

moviePlayer
The movie player controller object used to present the movie. (read-only)
@property(nonatomic, readonly) MPMoviePlayerController *moviePlayer

Discussion The MPMoviePlayerController object in this property is created automatically by the receiver and cannot be changed. However, you can use the object to manage the presentation and configuration of the movie playback. Availability Available in iOS 3.2 and later. Declared in
MPMoviePlayerViewController.h

Instance Methods
initWithContentURL:
Returns a movie player view controller initialized with the specified movie.
- (id)initWithContentURL:(NSURL *)contentURL

2011-10-12 | 2011 Apple Inc. All Rights Reserved.

125

MPMoviePlayerViewController Class Reference Instance Methods

Parameters
contentURL

The URL that points to the content to be played. Return Value A movie player view controller initialized with the specified URL. Availability Available in iOS 3.2 and later. Declared in
MPMoviePlayerViewController.h

shouldAutorotateToInterfaceOrientation:
Returns a Boolean value indicating whether the view controller supports the specified orientation.
(BOOL)shouldAutorotateToInterfaceOrientation:(UIInterfaceOrientation)toInterfaceOrientation

Parameters
toInterfaceOrientation

The orientation of the applications user interface after the rotation. The possible values are described in UIInterfaceOrientation. Return Value YES if the view controller supports the specified orientation or NO if it does not. Discussion This method is an override that replaces the default behavior by returning YES for the UIInterfaceOrientationPortrait, UIInterfaceOrientationLandscapeLeft, and UIInterfaceOrientationLandscapeRight orientations. Availability Available in iOS 3.2 and later. Declared in
MPMoviePlayerViewController.h

2011-10-12 | 2011 Apple Inc. All Rights Reserved.

126

MPMusicPlayerController Class Reference

Inherits from Conforms to Framework Availability Declared in Companion guide Related sample code

NSObject NSObject (NSObject) /System/Library/Frameworks/MediaPlayer.framework Available in iOS 3.0 and later.

iPod Library Access Programming Guide AddMusic

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 application. It is not aware of the iPod apps 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 application 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 players most recently-set repeat mode, shuffle mode, playback state, and now-playing item.

Important You must use a music player only on your apps main thread.

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

2011-10-12 | 2011 Apple Inc. All Rights Reserved.

127

MPMusicPlayerController Class Reference Tasks

nowPlayingItem (page 131) property of your music player is nil. Other playback information is available,

however, when playing shared media. For example, the system does update the values of the playbackState (page 131) and currentPlaybackTime (page 130) properties when an iPod music player is playing a shared item.

Tasks
Getting a Music Player
+ applicationMusicPlayer

(page 133) Returns the application music player. (page 134) Returns the iPod music player, which controls the iPod applications state.

+ iPodMusicPlayer

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.
setQueueWithQuery:

(page 138) Sets a music players playback queue based on a media query. (page 138) Sets a music players playback queue using a media item collection.

setQueueWithItemCollection:

Managing Playback Mode and State

currentPlaybackTime (page 130)

property

The current playback time, in seconds, measured from the start of the now-playing media items timeline.
nowPlayingItem (page 131)

property

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

property

The index of the now playing item in the current playback queue.
playbackState (page 131)

property

The current playback state of the music player.

2011-10-12 | 2011 Apple Inc. All Rights Reserved.

128

MPMusicPlayerController Class Reference Tasks

repeatMode (page 132)

property

The current repeat mode of the music player.

shuffleMode (page 133)

property

The current shuffle mode of the music player.

volume (page 133)

property

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

Controlling Playback
play

(page 137) Plays media items from the current playback queue, resuming paused playback if possible. (page 137) Pauses playback if the music player is playing. (page 140) Ends playback. (page 136) Moves the playback point forward in the media item (for example, toward the end of a song) faster than the normal playback rate. (page 135) Moves the playback point backward in the media item (for example, toward the start of a song). (page 136) Stops additional movement of the playback point, returning the playback state to what it was prior to seeking. (page 139) 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. (page 140) 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. (page 139) Available in iOS 2.0 through iOS 3.1 Restarts playback at the beginning of the currently playing media item.

pause

stop

beginSeekingForward

beginSeekingBackward

endSeeking

skipToNextItem

skipToPreviousItem

skipToBeginning

2011-10-12 | 2011 Apple Inc. All Rights Reserved.

129

MPMusicPlayerController Class Reference Properties

Using Music Player Notifications

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

(page 135) Starts the generation of playback notifications. (page 136) Ends the generation of playback notifications.

endGeneratingPlaybackNotifications

Properties
For more about Objective-C properties, see Properties in The Objective-C Programming Language .

currentPlaybackTime
The current playback time, in seconds, measured from the start of the now-playing media items timeline.
@property (nonatomic) NSTimeInterval currentPlaybackTime

Discussion Because this propertys access is read/write, you can use it to:

Acquire data to present current playback time to the user Seek to a particular point in a media item

If a music player is configured as an iPod music player and the built-in iPod app is using a home shared library, the value of this property is nil and you cannot change it. Availability Available in iOS 3.0 and later. See Also
@property nowPlayingItem (page 131)

Related Sample Code AddMusic

Declared in
MPMusicPlayerController.h

2011-10-12 | 2011 Apple Inc. All Rights Reserved.

130

MPMusicPlayerController Class Reference Properties

indexOfNowPlayingItem
The index of the now playing item in the current playback queue.
@property (nonatomic, readonly) NSUInteger indexOfNowPlayingItem

Discussion This propertys value is NSNotFound if the index is not validfor 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 propertys 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 AddMusic

Declared in
MPMusicPlayerController.h

playbackState
The current playback state of the music player.

2011-10-12 | 2011 Apple Inc. All Rights Reserved.

131

MPMusicPlayerController Class Reference Properties

@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 players nowPlayingItem (page 131) property is nil. For the available playback states, see Playback States (page 141). Availability Available in iOS 3.0 and later. See Also
@property repeatMode (page 132) @property shuffleMode (page 133)

Related Sample Code AddMusic

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 (page 142). If not explicitly set, repeatMode defaults to MPMusicRepeatModeDefault (page 142). Availability Available in iOS 3.0 and later. See Also
@property playbackState (page 131) @property shuffleMode (page 133)

Declared in
MPMusicPlayerController.h

2011-10-12 | 2011 Apple Inc. All Rights Reserved.

132

MPMusicPlayerController Class Reference Class Methods

shuffleMode
The current shuffle mode of the music player.
@property (nonatomic) MPMusicShuffleMode shuffleMode

Discussion For the available shuffle modes, see Shuffle Modes (page 143). If not explicitly set, shuffleMode defaults to MPMusicShuffleModeDefault (page 143). Availability Available in iOS 3.0 and later. See Also
@property playbackState (page 131) @property repeatMode (page 132)

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 players 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

2011-10-12 | 2011 Apple Inc. All Rights Reserved.

133

MPMusicPlayerController Class Reference Class Methods

Return Value The application music player. Discussion The application music player plays music locally within your application. 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 AddMusic

Declared in
MPMusicPlayerController.h

iPodMusicPlayer
Returns the iPod music player, which controls the iPod applications state.
+ (MPMusicPlayerController *)iPodMusicPlayer

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

Repeat mode (see Repeat Modes (page 142)) Shuffle mode (see Shuffle Modes (page 143) Now-playing item (see nowPlayingItem (page 131)) Playback state (see playbackState (page 131))

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 AddMusic

2011-10-12 | 2011 Apple Inc. All Rights Reserved.

134

MPMusicPlayerController Class Reference Instance Methods

Declared in
MPMusicPlayerController.h

Instance Methods
beginGeneratingPlaybackNotifications
Starts the generation of playback notifications.
- (void)beginGeneratingPlaybackNotifications

Availability Available in iOS 3.0 and later. See Also

MPMusicPlayerControllerPlaybackStateDidChangeNotification (page 143) MPMusicPlayerControllerNowPlayingItemDidChangeNotification (page 144)

Declared in
MPMusicPlayerController.h

beginSeekingBackward
Moves the playback point backward in the media item (for example, toward the start of a song).
- (void)beginSeekingBackward

Discussion Seeking rate increases while seeking is active. Availability Available in iOS 3.0 and later. See Also
beginSeekingForward endSeeking

(page 136)

(page 136)

Declared in
MPMusicPlayerController.h

2011-10-12 | 2011 Apple Inc. All Rights Reserved.

135

MPMusicPlayerController Class Reference Instance Methods

beginSeekingForward
Moves the playback point forward in the media item (for example, toward the end of a song) faster than the normal playback rate.
- (void)beginSeekingForward

Discussion Seeking rate increases while seeking is active. Availability Available in iOS 3.0 and later. See Also
beginSeekingBackward endSeeking

(page 135)

(page 136)

Declared in
MPMusicPlayerController.h

endGeneratingPlaybackNotifications
Ends the generation of playback notifications.
- (void)endGeneratingPlaybackNotifications

Availability Available in iOS 3.0 and later. See Also

MPMusicPlayerControllerPlaybackStateDidChangeNotification (page 143) MPMusicPlayerControllerNowPlayingItemDidChangeNotification (page 144)

Declared in
MPMusicPlayerController.h

endSeeking
Stops additional movement of the playback point, returning the playback state to what it was prior to seeking.
- (void)endSeeking

2011-10-12 | 2011 Apple Inc. All Rights Reserved.

136

MPMusicPlayerController Class Reference Instance Methods

Availability Available in iOS 3.0 and later. See Also (page 136) beginSeekingBackward (page 135)
beginSeekingForward

Declared in
MPMusicPlayerController.h

pause
Pauses playback if the music player is playing.
- (void)pause

Discussion Calling play (page 137) again starts playback from the spot where playback was paused. Availability Available in iOS 3.0 and later. See Also play (page 137) stop (page 140)
Related Sample Code AddMusic

Declared in
MPMusicPlayerController.h

play
Plays media items from the current playback queue, resuming paused playback if possible.
- (void)play

Availability Available in iOS 3.0 and later. See Also pause (page 137) stop (page 140)

2011-10-12 | 2011 Apple Inc. All Rights Reserved.

137

MPMusicPlayerController Class Reference Instance Methods

Related Sample Code AddMusic

Declared in
MPMusicPlayerController.h

setQueueWithItemCollection:
Sets a music players 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 (page 137). Availability Available in iOS 3.0 and later. See Also
setQueueWithQuery:

(page 138)

Declared in
MPMusicPlayerController.h

setQueueWithQuery:
Sets a music players 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 (page 137).

2011-10-12 | 2011 Apple Inc. All Rights Reserved.

138

MPMusicPlayerController Class Reference Instance Methods

Availability Available in iOS 3.0 and later. See Also

setQueueWithItemCollection:

(page 138)

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. See Also (page 139) skipToPreviousItem (page 140)
skipToNextItem

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. See Also
@property nowPlayingItem (page 131)

(page 139) skipToPreviousItem (page 140)

skipToBeginning

2011-10-12 | 2011 Apple Inc. All Rights Reserved.

139

MPMusicPlayerController Class Reference Instance Methods

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. See Also
@property nowPlayingItem (page 131)

(page 139) skipToNextItem (page 139)

skipToBeginning

Declared in
MPMusicPlayerController.h

stop
Ends playback.
- (void)stop

Discussion Calling play (page 137) again starts playback from the beginning of the queue. Availability Available in iOS 3.0 and later. See Also play (page 137) stop (page 140) Declared in
MPMusicPlayerController.h

2011-10-12 | 2011 Apple Inc. All Rights Reserved.

140

MPMusicPlayerController Class Reference Constants

Constants
Playback States
Values for the playbackState (page 131) 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.

2011-10-12 | 2011 Apple Inc. All Rights Reserved.

141

MPMusicPlayerController Class Reference Constants

MPMusicPlaybackStateSeekingBackward

The music player is seeking backward. Available in iOS 3.0 and later. Declared in MPMusicPlayerController.h. Discussion You determine a music players state by checking the playbackState (page 131) property. Depending on the propertys value, you can update your applications user interface or take other appropriate action.

Repeat Modes
Values for the repeatMode (page 132) property.
enum { MPMusicRepeatModeDefault, MPMusicRepeatModeNone, MPMusicRepeatModeOne, MPMusicRepeatModeAll }; typedef NSInteger MPMusicRepeatMode;

Constants
MPMusicRepeatModeDefault

The users 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.

2011-10-12 | 2011 Apple Inc. All Rights Reserved.

142

MPMusicPlayerController Class Reference Notifications

Shuffle Modes
Values for the shuffleMode (page 133) property.
enum { MPMusicShuffleModeDefault, MPMusicShuffleModeOff, MPMusicShuffleModeSongs, MPMusicShuffleModeAlbums }; typedef NSInteger MPMusicShuffleMode;

Constants
MPMusicShuffleModeDefault

The users 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 Available in iOS 3.0 and later.

2011-10-12 | 2011 Apple Inc. All Rights Reserved.

143

MPMusicPlayerController Class Reference Notifications

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 Available in iOS 3.0 and later. 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 Available in iOS 3.0 and later. Declared in
MPMusicPlayerController.h

2011-10-12 | 2011 Apple Inc. All Rights Reserved.

144

MPNowPlayingInfoCenter Class Reference

Inherits from Conforms to Framework Availability Declared in

NSObject NSObject (NSObject) /System/Library/Frameworks/MediaPlayer.framework Available in iOS 5.0 and later.

Overview
Use a now playing info center to set now-playing information for media being played by your app. The system displays now-playing information on the device lock screen and in the multimedia controls in the multitasking UI. If the user directs playback of your media to Apple TV via AirPlay, the now-playing information appears on the television screen. If the user connects a device to an iPod accessory, such as in a car, the accessory may display now-playing information. Important To ensure that your app interacts successfully with the widest possible range of accessories, provide values for as many information properties as you can in the nowPlayingInfo (page 146) dictionary. The information you can specify includes a subset of the properties available in the media item class (MPMediaItem), as well as some properties specific to this class. In iOS 5.0, the now playing info center supports the following media item property keys:

MPMediaItemPropertyAlbumTitle (page 22) MPMediaItemPropertyAlbumTrackCount (page 23) MPMediaItemPropertyAlbumTrackNumber (page 23) MPMediaItemPropertyArtist (page 22) MPMediaItemPropertyArtwork (page 23) MPMediaItemPropertyComposer (page 22) MPMediaItemPropertyDiscCount (page 23)

2011-10-12 | 2011 Apple Inc. All Rights Reserved.

145

MPNowPlayingInfoCenter Class Reference Tasks

MPMediaItemPropertyDiscNumber (page 23) MPMediaItemPropertyGenre (page 22) MPMediaItemPropertyPersistentID (page 19) MPMediaItemPropertyPlaybackDuration (page 22) MPMediaItemPropertyTitle (page 21)

Additional properties you can set are described in this document in Additional Metadata Properties (page 147). You do not have direct control over which information is displayed, or its formatting. You set the values of the now playing info center dictionary according to the information you want to provide to the system. The system, or the connected accessory, handles the informations display in a consistent manner for all apps.

Tasks
Working with the Default Now Playing Info Center
+ defaultCenter

(page 147) Returns the singleton now playing info center. property

nowPlayingInfo (page 146)

The current now-playing information for the default now playing info center.

Properties
For more about Objective-C properties, see Properties in The Objective-C Programming Language .

nowPlayingInfo
The current now-playing information for the default now playing info center.
@property (copy) NSDictionary *nowPlayingInfo

Discussion To clear the now playing info center dictionary, set it to nil. Availability Available in iOS 5.0 and later.

2011-10-12 | 2011 Apple Inc. All Rights Reserved.

146

MPNowPlayingInfoCenter Class Reference Class Methods

Declared in
MPNowPlayingInfoCenter.h

Class Methods
defaultCenter
Returns the singleton now playing info center.
+ (MPNowPlayingInfoCenter *)defaultCenter

Discussion The default now playing info center holds now-playing information for the app that is designated as the receiver for remote-control events. For information on how to configure your app to receive remote-control events, see Remote Control of Multimedia. Availability Available in iOS 5.0 and later. Declared in
MPNowPlayingInfoCenter.h

Constants
Additional Metadata Properties
These properties for the now playing info center dictionary supplement the available media item properties, as described in the Overview in this document.

2011-10-12 | 2011 Apple Inc. All Rights Reserved.

147

MPNowPlayingInfoCenter Class Reference Constants

NSString NSString NSString NSString NSString NSString

*const *const *const *const *const *const

MPNowPlayingInfoPropertyElapsedPlaybackTime MPNowPlayingInfoPropertyPlaybackRate; MPNowPlayingInfoPropertyPlaybackQueueIndex; MPNowPlayingInfoPropertyPlaybackQueueCount; MPNowPlayingInfoPropertyChapterNumber; MPNowPlayingInfoPropertyChapterCount;

Constants
MPNowPlayingInfoPropertyElapsedPlaybackTime

The elapsed time of the now playing item, in seconds. Value is an NSNumber object configured as a double. Elapsed time is automatically calculated, by the system, from the previously provided elapsed time and the playback rate. Do not update this property frequentlyit is not necessary. Available in iOS 5.0 and later. Declared in MPNowPlayingInfoCenter.h.
MPNowPlayingInfoPropertyPlaybackRate

The playback rate of the now-playing item, with a value of 1.0 indicating the normal playback rate. Value is an NSNumber object configured as a double. The default value is 1.0. A playback rate value of 2.0 means twice the normal playback rate; a piece of media played at this rate would take half as long to play to completion. A value of 0.5 means half the normal playback rate; a piece of media played at this rate would take twice as long to play to completion. Available in iOS 5.0 and later. Declared in MPNowPlayingInfoCenter.h.
MPNowPlayingInfoPropertyPlaybackQueueIndex

The index of the now-playing item in the apps playback queue. Value is an NSNumber object configured as an NSUInteger. The playback queue uses zero-based indexing. If you want the first item in the queue to be displayed as item 1 of 10, for example, set the items index to 0. Available in iOS 5.0 and later. Declared in MPNowPlayingInfoCenter.h.
MPNowPlayingInfoPropertyPlaybackQueueCount

The total number of items in the apps playback queue. Value is an NSNumber object configured as an NSUInteger. Available in iOS 5.0 and later. Declared in MPNowPlayingInfoCenter.h.

2011-10-12 | 2011 Apple Inc. All Rights Reserved.

148

MPNowPlayingInfoCenter Class Reference Constants

MPNowPlayingInfoPropertyChapterNumber

The number corresponding to the chapter currently being played. Value is an NSNumber object configured as an NSUInteger. Chapter numbering uses zero-based indexing. If you want the first chapter in the now-playing item to be displayed as Chapter 1, for example, set the chapter number to 0. Available in iOS 5.0 and later. Declared in MPNowPlayingInfoCenter.h.
MPNowPlayingInfoPropertyChapterCount

The total number of chapters in the now-playing item. Value is an NSNumber object configured as an NSUInteger. Available in iOS 5.0 and later. Declared in MPNowPlayingInfoCenter.h.

2011-10-12 | 2011 Apple Inc. All Rights Reserved.

149

MPTimedMetadata Class Reference

Inherits from Conforms to Framework Availability Declared in

NSObject NSObject (NSObject) /System/Library/Frameworks/MediaPlayer.framework Available in iOS 4.0 and later.

Overview
An instance of the MPTimedMetadata class, called a timed metadata object , carries time-based information within HTTP streamed media. Content providers can embed such objects when creating a stream. The properties and constants in this class let you extract the metadata as you play the stream using an MPMoviePlayerController object. For example, the provider of a live sports video stream could use MPTimedMetadata instances to embed game scores, with timestamps, in the stream. On the client sidethat is, on the users devicetheir application could employ the properties of this class to update their apps user interface in real time during the game. A Javascript implementation of this class is also available for use by web-based applications.

Tasks
Extracting Timed Metadata from a Stream
allMetadata (page 151)

property

A dictionary containing all the metadata in the object. (read-only)

key (page 151)

property

A key that identifies a piece of timed metadata. (read-only)

2011-10-12 | 2011 Apple Inc. All Rights Reserved.

150

MPTimedMetadata Class Reference Properties

keyspace (page 152)

property

The namespace of the identifying key. (read-only)

timestamp (page 152)

property

The timestamp of the metadata, in the timebase of the media stream. (read-only)
value (page 152)

property

The timed metadata. (read-only)

Properties
For more about Objective-C properties, see Properties in The Objective-C Programming Language .

allMetadata
A dictionary containing all the metadata in the object. (read-only)
@property (nonatomic, readonly) NSDictionary *allMetadata

Discussion To retrieve metadata from the dictionary, use the keys described in Timed Metadata Dictionary Keys (page 152). Availability Available in iOS 4.0 and later. Declared in
MPMoviePlayerController.h

key
A key that identifies a piece of timed metadata. (read-only)
@property (nonatomic, readonly) NSString *key

Availability Available in iOS 4.0 and later. Declared in

MPMoviePlayerController.h

2011-10-12 | 2011 Apple Inc. All Rights Reserved.

151

MPTimedMetadata Class Reference Constants

keyspace
The namespace of the identifying key. (read-only)
@property (nonatomic, readonly) NSString *keyspace

Availability Available in iOS 4.0 and later. Declared in

MPMoviePlayerController.h

timestamp
The timestamp of the metadata, in the timebase of the media stream. (read-only)
@property (nonatomic, readonly) NSTimeInterval timestamp

Availability Available in iOS 4.0 and later. Declared in

MPMoviePlayerController.h

value
The timed metadata. (read-only)
@property (nonatomic, readonly) id value

Availability Available in iOS 4.0 and later. Declared in

MPMoviePlayerController.h

Constants
Timed Metadata Dictionary Keys
Dictionary keys for use with the allMetadata (page 151) property. All keys are optional.

2011-10-12 | 2011 Apple Inc. All Rights Reserved.

152

MPTimedMetadata Class Reference Notifications

NSString NSString NSString NSString NSString

*const *const *const *const *const

MPMoviePlayerTimedMetadataKeyName; MPMoviePlayerTimedMetadataKeyInfo; MPMoviePlayerTimedMetadataKeyMIMEType; MPMoviePlayerTimedMetadataKeyDataType; MPMoviePlayerTimedMetadataKeyLanguageCode;

Constants
MPMoviePlayerTimedMetadataKeyName

The name of the timed metadata key. Available in iOS 4.0 and later. Declared in MPMoviePlayerController.h.
MPMoviePlayerTimedMetadataKeyInfo

Arbitrary information about the timed metadata. Available in iOS 4.0 and later. Declared in MPMoviePlayerController.h.
MPMoviePlayerTimedMetadataKeyMIMEType

The MIME type for the timed metadata. Available in iOS 4.0 and later. Declared in MPMoviePlayerController.h.
MPMoviePlayerTimedMetadataKeyDataType

The data type of the timed metadata. Available in iOS 4.0 and later. Declared in MPMoviePlayerController.h.
MPMoviePlayerTimedMetadataKeyLanguageCode

The metadata language, expressed using ISO 639-2, in a string object. Available in iOS 4.0 and later. Declared in MPMoviePlayerController.h.

Notifications
MPMoviePlayerTimedMetadataUpdatedNotification
Posted when new timed metadata arrives. Availability Available in iOS 4.0 and later. Declared in
MPMoviePlayerController.h

2011-10-12 | 2011 Apple Inc. All Rights Reserved.

153

MPTimedMetadata Class Reference Notifications

MPMoviePlayerTimedMetadataUserInfoKey
An NSArray object containing the most recent MPTimedMetadata objects. Availability Available in iOS 4.0 and later. Declared in
MPMoviePlayerController.h

2011-10-12 | 2011 Apple Inc. All Rights Reserved.

154

MPVolumeView Class Reference

Inherits from Conforms to

UIView : UIResponder : NSObject NSCoding NSCoding (UIView) UIAppearance (UIView) UIAppearanceContainer (UIView) NSObject (NSObject)

Framework Availability Declared in

/System/Library/Frameworks/MediaPlayer.framework Available in iOS 2.0 and later.

Overview
Use a volume view to present the user with a slider control for setting the system audio output volume, and a button for choosing the audio output route. When first displayed, the sliders position reflects the current system audio output volume. As the user drags the slider, the changes update the volume. If the user presses the device volume buttons while sound is playing, the slider moves to reflect the new volume. If there is an Apple TV or other AirPlay-enabled device in range, the route button allows the user to choose it. If there is only one audio output route available, the route button is not displayed. Use this class by embedding an instance of it in your view hierarchy. The following code snippet assumes you have placed an instance of the UIView class on a view using Interface Builder, sizing and positioning it as desired to contain the volume view. Point to the UIView instance with an outlet variablenamed, in the case of this example, mpVolumeViewParentView. You would typically place code like that shown in Listing 21-1 in your viewDidLoad method.
Listing 21-1 Adding a volume view to your view hierarchy
mpVolumeViewParentView.backgroundColor = [UIColor clearColor]; MPVolumeView *myVolumeView =

2011-10-12 | 2011 Apple Inc. All Rights Reserved.

155

MPVolumeView Class Reference Tasks

[[MPVolumeView alloc] initWithFrame: mpVolumeViewParentView.bounds]; [mpVolumeViewParentView addSubview: myVolumeView]; [myVolumeView release];

When an audio output route that does not support volume control, such as A2DP, is active, the volume slider is replaced with the route name. To instead display a volume slider as an alert, use the functions described in Media Player Functions Reference .

Tasks
Resizing Subviews
sizeThatFits:

(page 157) Calculates and returns a size that best fits the receivers subviews.

Managing Visibility of Controls

showsVolumeSlider (page 157)

property

Determines whether or not the volume slider is visible in the volume view.
showsRouteButton (page 156)

property

Determines whether or not the route button is visible in the volume view.

Properties
For more about Objective-C properties, see Properties in The Objective-C Programming Language .

showsRouteButton
Determines whether or not the route button is visible in the volume view.
@property (nonatomic) BOOL showsRouteButton;

Discussion The route button is visible by default when there is more than one audio output route available. To hide the route button, set this propertys value to NO.

2011-10-12 | 2011 Apple Inc. All Rights Reserved.

156

MPVolumeView Class Reference Instance Methods

Availability Available in iOS 4.2 and later. Declared in

MPVolumeView.h

showsVolumeSlider
Determines whether or not the volume slider is visible in the volume view.
@property (nonatomic) BOOL showsVolumeSlider;

Discussion The volume slider is visible by default. To hide the volume slider, set this propertys value to NO. Availability Available in iOS 4.2 and later. Declared in
MPVolumeView.h

Instance Methods
sizeThatFits:
Calculates and returns a size that best fits the receivers subviews.
- (CGSize)sizeThatFits:(CGSize)size

Parameters
size

The preferred size of the receiver. Return Value A new size that fits the receivers subviews. Discussion This method overrides the like-named method from the UIView class. It returns the preferred size the volume view needs to display the contained slider. You should not need to override this method. Availability Available in iOS 2.0 and later.

2011-10-12 | 2011 Apple Inc. All Rights Reserved.

157

MPVolumeView Class Reference Instance Methods

Declared in
MPVolumeView.h

2011-10-12 | 2011 Apple Inc. All Rights Reserved.

158

UIViewController MediaPlayer Additions Reference

Inherits from Framework Availability Declared in

UIResponder : NSObject /System/Library/Frameworks/MediaPlayer.framework Available in iOS 3.2 and later. MPMoviePlayerViewController.h

Overview
This category adds methods to the UIViewController class for presenting and dismissing a movie player using a specific set of animations. The transitions used by these methods are the same ones used by the YouTube and iPod applications to display video content.

Tasks
Presenting and Dismissing the Movie Player
presentMoviePlayerViewControllerAnimated:

(page 160) Presents the movie player view controller using the standard movie player transition. (page 159) Dismisses a movie player view controller using the standard movie player transition.

dismissMoviePlayerViewControllerAnimated

Instance Methods
dismissMoviePlayerViewControllerAnimated
Dismisses a movie player view controller using the standard movie player transition.
- (void)dismissMoviePlayerViewControllerAnimated

2011-10-12 | 2011 Apple Inc. All Rights Reserved.

159

UIViewController MediaPlayer Additions Reference Instance Methods

Discussion If the receivers modalViewController property does not contain a movie player view controller, this method does nothing. Availability Available in iOS 3.2 and later. Declared in
MPMoviePlayerViewController.h

presentMoviePlayerViewControllerAnimated:
Presents the movie player view controller using the standard movie player transition.
- (void)presentMoviePlayerViewControllerAnimated:(MPMoviePlayerViewController

*)moviePlayerViewController

Parameters
moviePlayerViewController

The movie player view controller to present. Availability Available in iOS 3.2 and later. Declared in
MPMoviePlayerViewController.h

2011-10-12 | 2011 Apple Inc. All Rights Reserved.

160

Protocols

2011-10-12 | 2011 Apple Inc. All Rights Reserved.

161

MPMediaPickerControllerDelegate Protocol Reference

Conforms to Framework Availability Declared in Companion guide Related sample code iPod Library Access Programming Guide AddMusic NSObject /System/Library/Frameworks/MediaPlayer.framework Available in iOS 3.0 and later.

Overview
The delegate for a media item picker can respond to a user making media item selections. The delegate is also responsible for dismissing the media item picker from the parent view controller. The methods in this protocol are optional. Media items are described in MPMediaItem Class Reference . Media item pickers are described in MPMediaPickerController Class Reference .

Tasks
Responding to User Actions
mediaPicker:didPickMediaItems:

(page 163) Called when a user has selected a set of media items. (page 163) Called when a user dismisses a media item picker by tapping Cancel.

mediaPickerDidCancel:

2011-10-12 | 2011 Apple Inc. All Rights Reserved.

162

MPMediaPickerControllerDelegate Protocol Reference Instance Methods

Instance Methods
mediaPicker:didPickMediaItems:
Called when a user has selected a set of media items.
- (void)mediaPicker: (MPMediaPickerController *)mediaPicker

didPickMediaItems:(MPMediaItemCollection *)mediaItemCollection

Parameters
mediaPicker

The media item picker to dismiss.

mediaItemCollection

The selected media items. Availability Available in iOS 3.0 and later. Declared in
MPMediaPickerController.h

mediaPickerDidCancel:
Called when a user dismisses a media item picker by tapping Cancel.
- (void)mediaPickerDidCancel:(MPMediaPickerController *)mediaPicker

Parameters
mediaPicker

The media item picker to dismiss. Availability Available in iOS 3.0 and later. Declared in
MPMediaPickerController.h

2011-10-12 | 2011 Apple Inc. All Rights Reserved.

163

MPMediaPlayback Protocol Reference

Framework Availability Declared in

/System/Library/Frameworks/MediaPlayer.framework Available in iOS 3.2 and later.

Overview
The MPMediaPlayback protocol defines the interface adopted by the MPMoviePlayerController class for controlling media playback. This protocol supports basic transport operations including start, stop, and pause, and also lets you seek forward and back through a movie or to a specific point in its timeline.

Tasks
Starting and Stopping Playback
play (page 168)

required method

Initiates playback of the current item. (required)

pause (page 168)

required method

Pauses playback of the current item. (required)

stop (page 169)

required method

Ends playback of the current item. (required)

prepareToPlay (page 169)

required method

Prepares a movie player for playback. (required)

isPreparedToPlay (page 166)

required property

A Boolean value indicating whether a movie player is ready to play. (required) (read-only)

2011-10-12 | 2011 Apple Inc. All Rights Reserved.

164

MPMediaPlayback Protocol Reference Properties

Seeking Within Media

beginSeekingBackward (page 166)

required method

Begins seeking backward through the media content. (required)

beginSeekingForward (page 167)

required method

Begins seeking forward through the media content. (required)

endSeeking (page 167)

required method

Ends forward and backward seeking through the media content. (required)

Accessing Playback Attributes

currentPlaybackRate (page 165)

required property

The current playback rate for the player. (required)

currentPlaybackTime (page 166)

required property

The current position of the playhead. (required)

Properties
For more about Objective-C properties, see Properties in The Objective-C Programming Language .

currentPlaybackRate
The current playback rate for the player. (required)
@property(nonatomic) float currentPlaybackRate

Discussion This value represents a multiplier for the default playback rate of the current item. A value of 0.0 indicates that playback is stopped while a value of 1.0 indicates that playback is occurring at normal speed. Positive values indicate forward playback while negative values indicate reverse playback. Setting the value of this property changes the playback rate accordingly. Availability Available in iOS 3.2 and later. Declared in
MPMediaPlayback.h

2011-10-12 | 2011 Apple Inc. All Rights Reserved.

165

MPMediaPlayback Protocol Reference Instance Methods

currentPlaybackTime
The current position of the playhead. (required)
@property(nonatomic) NSTimeInterval currentPlaybackTime

Discussion For video-on-demand or progressively downloaded content, this value is measured in seconds from the beginning of the current item. Changing the value of this property moves the playhead to the new location. For content streamed live from a server, this value represents the time from the beginning of the playlist when it was first loaded. Availability Available in iOS 3.2 and later. Declared in
MPMediaPlayback.h

isPreparedToPlay
A Boolean value indicating whether a movie player is ready to play. (required) (read-only)
@property(nonatomic, readonly) BOOL isPreparedToPlay

Availability Available in iOS 3.2 and later. See Also

prepareToPlay

(page 169)

Declared in
MPMediaPlayback.h

Instance Methods
beginSeekingBackward
Begins seeking backward through the media content. (required)
- (void)beginSeekingBackward

2011-10-12 | 2011 Apple Inc. All Rights Reserved.

166

MPMediaPlayback Protocol Reference Instance Methods

Discussion Use this method to move the current playback position backward in time at an accelerated rate. Seeking begins when you call this method and continues until you call the endSeeking (page 167) method. If the underlying content is streamed, this method has no effect. Availability Available in iOS 3.2 and later. Declared in
MPMediaPlayback.h

beginSeekingForward
Begins seeking forward through the media content. (required)
- (void)beginSeekingForward

Discussion Use this method to move the current playback position forward in time at an accelerated rate. Seeking begins when you call this method and continues until you call the endSeeking (page 167) method. If the underlying content is streamed, this method has no effect. Availability Available in iOS 3.2 and later. Declared in
MPMediaPlayback.h

endSeeking
Ends forward and backward seeking through the media content. (required)
- (void)endSeeking

Discussion You must call this method to end a seeking operation begun by calling either the beginSeekingBackward (page 166) or beginSeekingForward (page 167) method. After calling this method, the player returns to the same state it was in prior to seeking. In other words, if the item was playing before seeking began, it continues playing from the new playhead position after calling this method. If the underlying content is streamed, this method has no effect.

2011-10-12 | 2011 Apple Inc. All Rights Reserved.

167

MPMediaPlayback Protocol Reference Instance Methods

Availability Available in iOS 3.2 and later. Declared in

MPMediaPlayback.h

pause
Pauses playback of the current item. (required)
- (void)pause

Discussion If playback is not currently underway, this method has no effect. To resume playback of the current item from the pause point, call the play (page 168) method. Availability Available in iOS 3.2 and later. Declared in
MPMediaPlayback.h

play
Initiates playback of the current item. (required)
- (void)play

Discussion If playback was previously paused, this method resumes playback where it left off; otherwise, this method plays the first available item, from the beginning. If a movie player is not prepared for playback when you call this method, this method first prepares the movie player and then starts playback. To minimize playback delay, call the prepareToPlay (page 169) method before you call this method. To be notified when a movie player is ready to play, register for the MPMoviePlayerLoadStateDidChangeNotification (page 120) notification. You can then check load state by accessing the movie players loadState property. Availability Available in iOS 3.2 and later.

2011-10-12 | 2011 Apple Inc. All Rights Reserved.

168

MPMediaPlayback Protocol Reference Instance Methods

Declared in
MPMediaPlayback.h

prepareToPlay
Prepares a movie player for playback. (required)
- (void)prepareToPlay

Discussion If a movie player is not already prepared to play when you call the play (page 168) method, that method automatically calls this method. However, to minimize playback delay, call this method before you call play. Calling this method may interrupt the movie players audio session. For information on interruptions and how to resond to them, see Audio Session Programming Guide . Availability Available in iOS 3.2 and later. Declared in
MPMediaPlayback.h

stop
Ends playback of the current item. (required)
- (void)stop

Discussion This method stops playback of the current item and resets the playhead to the start of the item. Calling the play (page 168) method again initiates playback from the beginning of the item. Availability Available in iOS 3.2 and later. Declared in
MPMediaPlayback.h

2011-10-12 | 2011 Apple Inc. All Rights Reserved.

169

MPMediaPlayback Protocol Reference Notifications

Notifications
MPMediaPlaybackIsPreparedToPlayDidChangeNotification
Posted upon change in the prepared-to-play state of an object conforming to the MPMediaPlayback protocol. The object whose state has changed is available as the object associated with the notification. Availability Available in iOS 3.2 and later. Declared in
MPMediaPlayback.h

2011-10-12 | 2011 Apple Inc. All Rights Reserved.

170

Functions

2011-10-12 | 2011 Apple Inc. All Rights Reserved.

171

Media Player Functions Reference

Framework Declared in

MediaPlayer/MediaPlayer.h MPVolumeSettings.h

Overview
The Media Player framework defines several functions for use in displaying and hiding volume controls.

Functions
MPVolumeSettingsAlertHide
Hides the alert panel that controls the system volume.
void MPVolumeSettingsAlertHide();

Availability Available in iOS 2.0 and later. See Also

MPVolumeSettingsAlertShow (page 173)

Declared in
MPVolumeSettings.h

MPVolumeSettingsAlertIsVisible
Returns a Boolean value indicating whether the volume alert panel is currently visible.
BOOL MPVolumeSettingsAlertIsVisible();

Return Value YES if the volume alert is visible; otherwise, NO.

2011-10-12 | 2011 Apple Inc. All Rights Reserved.

172

Media Player Functions Reference Functions

Availability Available in iOS 2.0 and later. See Also

MPVolumeSettingsAlertShow (page 173)

Declared in
MPVolumeSettings.h

MPVolumeSettingsAlertShow
Displays an alert panel for controlling the system volume.
void MPVolumeSettingsAlertShow();

Discussion The alert panel displayed by this function floats above the contents of the current window. It contains a slider for adjusting the system volume setting and a Done button so that the user can dismiss the panel. You can also dismiss the panel programmatically using the MPVolumeSettingsAlertHide function. Availability Available in iOS 2.0 and later. See Also
MPVolumeSettingsAlertHide (page 172)

Declared in
MPVolumeSettings.h

2011-10-12 | 2011 Apple Inc. All Rights Reserved.

173

Document Revision History

This table describes the changes to Media Player Framework Reference .

Date 2011-10-12

Notes Added a link to MPNowPlayingInfoCenter Class Reference .

2010-12-09

AddedlinkstoMPMovieAccessLogClassReference ,MPMovieAccessLogEvent Class Reference , MPMovieErrorLog Class Reference , and MPMovieErrorLogEvent Class Reference .

2010-10-12

Added links to MPMediaEntity Class Reference and to MPMediaQuerySection Class Reference .

2010-09-01

Added links to MPMoviePlayerViewController Class Reference , MPMediaPlayback Protocol Reference , and UIViewController MediaPlayer Additions Reference .

2010-04-10

Added link to MPTimedMetadata Class Reference .

2010-03-02 2009-11-24

Added new classes that were introduced in iOS 3.2. Minor changes.

2009-04-14

Updated for iPhone OS 3.0.

2008-04-18

New collection that describes the classes and functions that provide basic facilities for playing movie files.

2011-10-12 | 2011 Apple Inc. All Rights Reserved.

174

Apple Inc. 2011 Apple Inc. All rights reserved. No part of this publication may be reproduced, stored in a retrieval system, or transmitted, in any form or by any means, mechanical, electronic, photocopying, recording, or otherwise, without prior written permission of Apple Inc., with the following exceptions: Any person is hereby authorized to store documentation on a single computer for personal use only and to print copies of documentation for personal use provided that the documentation contains Apples copyright notice. The Apple logo is a trademark of Apple Inc. No licenses, express or implied, are granted with respect to any of the technology described in this document. Apple retains all intellectual property rights associated with the technology described in this document. This document is intended to assist application developers to develop applications only for Apple-labeled computers. Apple Inc. 1 Infinite Loop Cupertino, CA 95014 408-996-1010 Apple, the Apple logo, AirPlay, Apple TV, iPhone, iPod, iTunes, Logic, Objective-C, QuickTime, and Xcode are trademarks of Apple Inc., registered in the United States and other countries. IOS is a trademark or registered trademark of Cisco in the U.S. and other countries and is used under license. Java is a registered trademark of Oracle and/or its affiliates. Times is a registered trademark of Heidelberger Druckmaschinen AG, available from Linotype Library GmbH.
Even though Apple has reviewed this document, APPLE MAKES NO WARRANTY OR REPRESENTATION, EITHER EXPRESS OR IMPLIED, WITH RESPECT TO THIS DOCUMENT, ITS QUALITY, ACCURACY, MERCHANTABILITY, OR FITNESS FOR A PARTICULAR PURPOSE. AS A RESULT, THIS DOCUMENT IS PROVIDED AS IS, AND YOU, THE READER, ARE ASSUMING THE ENTIRE RISK AS TO ITS QUALITY AND ACCURACY. IN NO EVENT WILL APPLE BE LIABLE FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES RESULTING FROM ANY DEFECT OR INACCURACY IN THIS DOCUMENT, even if advised of the possibility of such damages. THE WARRANTY AND REMEDIES SET FORTH ABOVE ARE EXCLUSIVE AND IN LIEU OF ALL OTHERS, ORAL OR WRITTEN, EXPRESS OR IMPLIED. No Apple dealer, agent, or employee is authorized to make any modification, extension, or addition to this warranty. Some states do not allow the exclusion or limitation of implied warranties or liability for incidental or consequential damages, so the above limitation or exclusion may not apply to you. This warranty gives you specific legal rights, and you may also have other rights which vary from state to state.