MPMediaItem Class Reference

Inherits from	MPMediaEntity : NSObject
Conforms to	NSCoding (MPMediaEntity) NSObject (NSObject)
Framework	/System/Library/Frameworks/MediaPlayer.framework
Availability	Available in iOS 3.0 and later.
Companion guide	iPod Library Access Programming Guide
Declared in	MPMediaItem.h MPMediaQuery.h
Related sample code	AddMusic AVMovieExporter AVPlayerDemo

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

Tasks

Obtaining Group Properties

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

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

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 property. A media item can have more than one media item type.

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

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.

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.

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

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.

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.

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

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

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.

Declared in MPMediaItem.h.

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.

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.

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.

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.

MPMediaItemPropertyIsCloudItem

A Boolean value indicating whether the media item is an iCloud item (YES), or not (NO). 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.

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.

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 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: method with these property keys. User-defined properties cannot be used to build media property predicates.

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

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.

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.

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.

Declared in MPMediaItem.h.

Did this document help you?

Shop the Apple Online Store (1-800-MY-APPLE), visit an Apple Retail Store, or find a reseller.