Class

MPMediaQuery

A query that specifies a set of media items from the device's media library by way of a filter and a grouping type.

Declaration

@interface MPMediaQuery : NSObject

Overview

Filter and grouping types 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 MPMediaPropertyPredicate objects, based on property keys described in MPMediaItem.

After creating and configuring a query, you use it to retrieve media items or media item collections. 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 library. Table 1 summarizes the features of these constructors. See MPMediaItem for descriptions of the entries in the Filter column. See MPMediaGrouping for descriptions of the entries in the Grouping type column.

Table 1

Convenience constructors from the MPMediaQuery class

Topics

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 Music library while others match a subset, as described in the Discussion sections for each method.

+ albumsQuery

Creates a media query that matches music items and that groups and sorts collections by album name.

+ artistsQuery

Creates a media query that matches music items and that groups and sorts collections by artist name.

+ songsQuery

Creates a media query that matches music items and that groups and sorts collections by song name.

+ playlistsQuery

Creates a media query that matches the entire library and that groups and sorts collections by playlist name.

+ podcastsQuery

Creates a media query that matches podcast items and that groups and sorts collections by podcast name.

+ audiobooksQuery

Creates a media query that matches audio book items and that groups and sorts collections by audio book name.

+ compilationsQuery

Creates a media query that matches compilation items and that groups and sorts collections by album name.

+ composersQuery

Creates a media query that matches all media items and that groups and sorts collections by composer name.

+ genresQuery

Creates a media query that matches all media items and that groups and sorts collections by genre name.

- init

Initializes a generic media query.

- initWithFilterPredicates:

Initializes a media query with a set of media property predicates.

Configuring Media Queries

filterPredicates

The media property predicates of the media query.

- addFilterPredicate:

Adds a media property predicate to a query.

- removeFilterPredicate:

Removes a filter predicate from a query.

groupingType

The grouping for collections retrieved with the media query.

itemSections

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

collectionSections

An array representing the section grouping of the query's specified media item collections.

MPMediaGrouping

Keys used to configure a media query.

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.

items

An array of media items that match the media query’s predicate.

collections

An array of media item collections whose contained items match the query’s media property predicate.

Relationships

Inherits From

See Also

Media Item Queries

Using Filters to Create Specialized Queries

Add a filter set to a query before populating a music player queue.

MPMediaQuerySection

A range of media items or media item collections from within a media query.

MPMediaPropertyPredicate

A set of predicates that define a filter used in a media query.

MPMediaPredicate

An abstract class that defines classes for filtering media in a media query.