MPMediaQuery Class Reference

Inherits from
Conforms to
Framework
/System/Library/Frameworks/MediaPlayer.framework
Availability
Available in iOS 3.0 and later.
Companion guide
Declared in
MPMediaQuery.h
Related sample code

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 query’s 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 and collectionSections 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 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” for descriptions of the entries in the Grouping type column.

Table 1  Convenience constructors from the MPMediaQuery class

Constructor name

Matches entire iPod library

Filter

Grouping type

albumsQuery

-

MPMediaTypeMusic

MPMediaGroupingAlbum

artistsQuery

-

MPMediaTypeMusic

MPMediaGroupingArtist

audiobooksQuery

-

MPMediaTypeAudioBook

MPMediaGroupingTitle

compilationsQuery

-

MPMediaTypeAny with MPMediaItemPropertyIsCompilation

MPMediaGroupingAlbum

composersQuery

Yes

MPMediaTypeAny

MPMediaGroupingComposer

genresQuery

Yes

MPMediaTypeAny

MPMediaGroupingGenre

playlistsQuery

Yes

MPMediaTypeAny

MPMediaGroupingPlaylist

podcastsQuery

-

MPMediaTypePodcast

MPMediaGroupingPodcastTitle

songsQuery

-

MPMediaTypeMusic

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.” For each class method, the query’s groupingType 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.

Configuring Media Queries

Performing Media Queries

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

Properties

collections

An array of media item collections whose contained items match the query’s 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];
 
// 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.”

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 and Podcast Item Property Keys 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

groupingType

The grouping for collections retrieved with the media query.

@property (nonatomic) MPMediaGrouping groupingType;
Discussion

The default grouping type is MPMediaGroupingTitle. See “Media Item Collection Grouping Keys” 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 query’s 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.
Related Sample Code
Declared In
MPMediaQuery.h

itemSections

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

@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 and has a grouping type of MPMediaGroupingAlbum.

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
Return Value

A media query that matches media items of type MPMediaTypeMusic and has a grouping type of MPMediaGroupingArtist.

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 and that uses the default grouping type of MPMediaGroupingTitle.

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 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
Return Value

A media query that matches any media item that has the MPMediaItemPropertyIsCompilation property; the returned query has a grouping type of MPMediaGroupingAlbum.

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.

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.

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.

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 and that has a grouping type of MPMediaGroupingPodcastTitle.

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 items, whether or not they are also of other media types.

Availability
  • Available in iOS 3.0 and later.
Declared In
MPMediaQuery.h

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 and has a grouping type of MPMediaGroupingTitle.

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.
Related Sample Code
Declared In
MPMediaQuery.h

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 and Podcast Item Property Keys 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.

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

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.

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.