Class

MPMediaQuery

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.

Overview

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, based on property keys described in MPMediaItem.

After creating and configuring a query, you use it to retrieve media items or media item collections. Collections are described in MPMediaItemCollection. 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 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

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

Symbols

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 albums() method assigns a grouping type of album. 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.

class func albums()

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

class func artists()

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

class func songs()

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

class func playlists()

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

class func podcasts()

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

class func audiobooks()

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

class func compilations()

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

class func composers()

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

class func genres()

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

init(filterPredicates: Set<MPMediaPredicate>?)

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

Configuring Media Queries

var filterPredicates: Set<MPMediaPredicate>?

The media property predicates of the media query.

var groupingType: MPMediaGrouping

The grouping for collections retrieved with the media query.

var itemSections: [MPMediaQuerySection]?

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

var collectionSections: [MPMediaQuerySection]?

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

func addFilterPredicate(MPMediaPredicate)

Adds a media property predicate to a query.

func removeFilterPredicate(MPMediaPredicate)

Removes a filter predicate from a 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.

var items: [MPMediaItem]?

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

var collections: [MPMediaItemCollection]?

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

Constants

MPMediaGrouping

Keys used with the groupingType property to configure a media query.

Relationships

Inherits From