iOS Developer Library

Developer

MediaPlayer Framework Reference MPMediaItem Class Reference

Options
Deployment Target:

On This Page
Language:

MPMediaItem

Inheritance


Conforms To


Import Statement


Swift

import MediaPlayer

Objective-C

@import MediaPlayer;

Availability


Available in iOS 3.0 and later.

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 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: method along with the property keys described in this document. You can also access metadata in a batch fashion using the enumerateValuesForProperties:usingBlock: 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, General Media Item Property Keys, and Podcast Item Property Keys. In addition, the MPMediaEntityPropertyPersistentID property is described in Media Entity Property Keys. Media queries are described in MPMediaQuery Class Reference.

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.

  • Obtains the persistent identifier key for a specified grouping type.

    Declaration

    Swift

    class func persistentIDPropertyForGroupingType(_ groupingType: MPMediaGrouping) -> String!

    Objective-C

    + (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:method. Grouping keys are described in Media Item Collection Grouping Keys.

    Import Statement

    Objective-C

    @import MediaPlayer;

    Swift

    import MediaPlayer

    Availability

    Available in iOS 4.2 and later.

  • Obtains the title key for a specified grouping type.

    Declaration

    Swift

    class func titlePropertyForGroupingType(_ groupingType: MPMediaGrouping) -> String!

    Objective-C

    + (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: method. Grouping keys are described in Media Item Collection Grouping Keys.

    Import Statement

    Objective-C

    @import MediaPlayer;

    Swift

    import MediaPlayer

    Availability

    Available in iOS 4.2 and later.

  • Media item types, used as possible values for the MPMediaItemPropertyMediaType property. A media item can have more than one media item type.

    Declaration

    Swift

    struct MPMediaType : RawOptionSetType { init(_ rawValue: UInt) init(rawValue rawValue: UInt) static var Music: MPMediaType { get } static var Podcast: MPMediaType { get } static var AudioBook: MPMediaType { get } static var AudioITunesU: MPMediaType { get } static var AnyAudio: MPMediaType { get } static var Movie: MPMediaType { get } static var TVShow: MPMediaType { get } static var VideoPodcast: MPMediaType { get } static var MusicVideo: MPMediaType { get } static var VideoITunesU: MPMediaType { get } static var HomeVideo: MPMediaType { get } static var AnyVideo: MPMediaType { get } static var Any: MPMediaType { get } }

    Objective-C

    enum { // audio media types MPMediaTypeMusic = 1 << 0, MPMediaTypePodcast = 1 << 1, MPMediaTypeAudioBook = 1 << 2, MPMediaTypeAudioITunesU = 1 << 3, // available in iOS 5.0 MPMediaTypeAnyAudio = 0x00ff, // video media types MPMediaTypeMovie = 1 << 8, MPMediaTypeTVShow = 1 << 9, MPMediaTypeVideoPodcast = 1 << 10, MPMediaTypeMusicVideo = 1 << 11, MPMediaTypeVideoITunesU = 1 << 12, MPMediaTypeAnyVideo = 0xff00, // generic media type MPMediaTypeAny = ~0 }; typedef NSInteger MPMediaType;

    Constants

    • Music

      MPMediaTypeMusic

      If set, the media item contains music.

      Available in iOS 3.0 and later.

    • Podcast

      MPMediaTypePodcast

      If set, the media item contains a podcast.

      Available in iOS 3.0 and later.

    • AudioBook

      MPMediaTypeAudioBook

      If set, the media item contains an audio book.

      Available in iOS 3.0 and later.

    • AnyAudio

      MPMediaTypeAnyAudio

      If set, the media item contains an unspecified type of audio content.

      Available in iOS 3.0 and later.

    • Movie

      MPMediaTypeMovie

      If set, the media item contains a movie.

      Available in iOS 5.0 and later.

    • TVShow

      MPMediaTypeTVShow

      If set, the media item contains a TV show.

      Available in iOS 5.0 and later.

    • VideoPodcast

      MPMediaTypeVideoPodcast

      If set, the media item contains a video podcast.

      Available in iOS 5.0 and later.

    • MusicVideo

      MPMediaTypeMusicVideo

      If set, the media item contains a music video.

      Available in iOS 5.0 and later.

    • VideoITunesU

      MPMediaTypeVideoITunesU

      If set, the media item contains an iTunes U video.

      Available in iOS 5.0 and later.

    • AnyVideo

      MPMediaTypeAnyVideo

      If set, the media item contains an unspecified type of video content.

      Available in iOS 5.0 and later.

    • Any

      MPMediaTypeAny

      If set, the media item contains an unspecified type of audio.

      Available in iOS 3.0 and later.

    Import Statement

    Objective-C

    @import MediaPlayer;

    Swift

    import MediaPlayer

    Availability

    Available in iOS 3.0 and later.

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

    Declaration

    Swift

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

    Objective-C

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

    Constants

    • MPMediaItemPropertyPersistentID

      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 4.2 and later.

    • MPMediaItemPropertyAlbumPersistentID

      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.

    • MPMediaItemPropertyArtistPersistentID

      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.

    • MPMediaItemPropertyAlbumArtistPersistentID

      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.

    • MPMediaItemPropertyGenrePersistentID

      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.

    • MPMediaItemPropertyComposerPersistentID

      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.

    • MPMediaItemPropertyPodcastPersistentID

      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.

    • MPMediaItemPropertyMediaType

      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.

      Can be used to build a media property predicate as described in MPMediaPropertyPredicate Class Reference.

      Available in iOS 3.0 and later.

    • MPMediaItemPropertyTitle

      MPMediaItemPropertyTitle

      The title (or name) of the media item. This property is unrelated to the MPMediaItemPropertyAlbumTitle 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.

    • MPMediaItemPropertyAlbumTitle

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

    • MPMediaItemPropertyArtist

      MPMediaItemPropertyArtist

      The performing artist(s) for a media item—which 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.

    • MPMediaItemPropertyAlbumArtist

      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.

    • MPMediaItemPropertyGenre

      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.

    • MPMediaItemPropertyComposer

      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.

    • MPMediaItemPropertyPlaybackDuration

      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.

    • MPMediaItemPropertyAlbumTrackNumber

      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.

    • MPMediaItemPropertyAlbumTrackCount

      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.

    • MPMediaItemPropertyDiscNumber

      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.

    • MPMediaItemPropertyDiscCount

      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.

    • MPMediaItemPropertyArtwork

      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.

    • MPMediaItemPropertyLyrics

      MPMediaItemPropertyLyrics

      The lyrics for the media item. Value is an NSString object.

      Available in iOS 3.0 and later.

    • MPMediaItemPropertyIsCompilation

      MPMediaItemPropertyIsCompilation

      A Boolean value indicating whether the media item is part of a compilation (YEStrue), or not (NOfalse). 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.

    • MPMediaItemPropertyReleaseDate

      MPMediaItemPropertyReleaseDate

      The date on which the media item was first publicly released. Value is an NSDate object.

      Available in iOS 4.0 and later.

    • MPMediaItemPropertyBeatsPerMinute

      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.

    • MPMediaItemPropertyComments

      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.

    • MPMediaItemPropertyAssetURL

      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.

    • MPMediaItemPropertyIsCloudItem

      MPMediaItemPropertyIsCloudItem

      A Boolean value indicating whether the media item is an iCloud item (YEStrue), or not (NOfalse). A media item is considered an iCloud item if it is available via iTunes Match and is not already stored on the device. Value is an NSNumber object representing a BOOL data type.

      Available in iOS 6.0 and later.

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

    Declaration

    Swift

    let MPMediaItemPropertyPodcastTitle: String

    Objective-C

    NSString *const MPMediaItemPropertyPodcastTitle ; // filterable

    Constants

    • MPMediaItemPropertyPodcastTitle

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

  • You obtain user-defined metadata for a media item by calling the valueForProperty: method with these property keys. User-defined properties cannot be used to build media property predicates.

    Declaration

    Swift

    let MPMediaItemPropertyPlayCount: String let MPMediaItemPropertySkipCount: String let MPMediaItemPropertyRating: String let MPMediaItemPropertyLastPlayedDate: String let MPMediaItemPropertyUserGrouping: String let MPMediaItemPropertyBookmarkTime: String

    Objective-C

    NSString *const MPMediaItemPropertyPlayCount; NSString *const MPMediaItemPropertySkipCount; NSString *const MPMediaItemPropertyRating; NSString *const MPMediaItemPropertyLastPlayedDate; NSString *const MPMediaItemPropertyUserGrouping; NSString *const MPMediaItemPropertyBookmarkTime;

    Constants

    • MPMediaItemPropertyPlayCount

      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.

    • MPMediaItemPropertySkipCount

      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.

    • MPMediaItemPropertyRating

      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.

    • MPMediaItemPropertyLastPlayedDate

      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.

    • MPMediaItemPropertyUserGrouping

      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.

    • MPMediaItemPropertyBookmarkTime

      MPMediaItemPropertyBookmarkTime

      The user’s place in the media item the most recent time it was played. Value is an NSNumber object representing a duration in seconds as an NSTimeInterval.

      Available in iOS 6.0 and later.