iOS Developer Library

Developer

MediaPlayer Framework Reference MPMediaQuery Class Reference

Options
Deployment Target:

On This Page
Language:

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

Inheritance


Import Statement


import MediaPlayer @import MediaPlayer;

Availability


Available in iOS 3.0 and later.
  • Creates a media query that matches music items and that groups and sorts collections by album name.

    Declaration

    Swift

    class func albumsQuery() -> MPMediaQuery!

    Objective-C

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

    Import Statement

    import MediaPlayer

    Availability

    Available in iOS 3.0 and later.

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

    Declaration

    Swift

    class func artistsQuery() -> MPMediaQuery!

    Objective-C

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

    Import Statement

    import MediaPlayer

    Availability

    Available in iOS 3.0 and later.

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

    Declaration

    Swift

    class func songsQuery() -> MPMediaQuery!

    Objective-C

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

    Import Statement

    import MediaPlayer

    Availability

    Available in iOS 3.0 and later.

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

    Declaration

    Swift

    class func playlistsQuery() -> MPMediaQuery!

    Objective-C

    + (MPMediaQuery *)playlistsQuery

    Return Value

    A media query that matches all media items and that has a grouping type of MPMediaGroupingPlaylist.

    Import Statement

    import MediaPlayer

    Availability

    Available in iOS 3.0 and later.

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

    Declaration

    Swift

    class func podcastsQuery() -> MPMediaQuery!

    Objective-C

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

    Import Statement

    import MediaPlayer

    Availability

    Available in iOS 3.0 and later.

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

    Declaration

    Swift

    class func audiobooksQuery() -> MPMediaQuery!

    Objective-C

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

    Import Statement

    import MediaPlayer

    Availability

    Available in iOS 3.0 and later.

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

    Declaration

    Swift

    class func compilationsQuery() -> MPMediaQuery!

    Objective-C

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

    Import Statement

    import MediaPlayer

    Availability

    Available in iOS 3.0 and later.

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

    Declaration

    Swift

    class func composersQuery() -> MPMediaQuery!

    Objective-C

    + (MPMediaQuery *)composersQuery

    Return Value

    A media query that matches all media items and that has a grouping type of MPMediaGroupingComposer.

    Import Statement

    import MediaPlayer

    Availability

    Available in iOS 3.0 and later.

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

    Declaration

    Swift

    class func genresQuery() -> MPMediaQuery!

    Objective-C

    + (MPMediaQuery *)genresQuery

    Return Value

    A media query that matches all media items and that has a grouping type of MPMediaGroupingGenre.

    Import Statement

    import MediaPlayer

    Availability

    Available in iOS 3.0 and later.

  • init init Available in iOS 3.0 through iOS 7.1

    Initializes a generic media query.

    Declaration

    Objective-C

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

    Import Statement

    Availability

    Available in iOS 3.0 through iOS 7.1.

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

    Declaration

    Swift

    init!(filterPredicates filterPredicates: NSSet!)

    Objective-C

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

    Import Statement

    import MediaPlayer

    Availability

    Available in iOS 3.0 and later.

  • The media property predicates of the media query.

    Declaration

    Swift

    var filterPredicates: NSSet!

    Objective-C

    @property(nonatomic, strong) 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.

    Import Statement

    import MediaPlayer

    Availability

    Available in iOS 3.0 and later.

  • The grouping for collections retrieved with the media query.

    Declaration

    Swift

    var groupingType: MPMediaGrouping

    Objective-C

    @property(nonatomic) MPMediaGrouping groupingType

    Discussion

    The default grouping type is MPMediaGroupingTitle. See Media Item Collection Grouping Keys for the list of available grouping types.

    Import Statement

    import MediaPlayer

    Availability

    Available in iOS 3.0 and later.

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

    Declaration

    Swift

    var itemSections: [AnyObject]! { get }

    Objective-C

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

    Import Statement

    import MediaPlayer

    Availability

    Available in iOS 4.2 and later.

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

    Declaration

    Swift

    var collectionSections: [AnyObject]! { get }

    Objective-C

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

    Import Statement

    import MediaPlayer

    Availability

    Available in iOS 4.2 and later.

  • Adds a media property predicate to a query.

    Declaration

    Swift

    func addFilterPredicate(_ predicate: MPMediaPredicate!)

    Objective-C

    - (void)addFilterPredicate:(MPMediaPredicate *)predicate

    Parameters

    predicate

    The media predicate to add to the set of predicates for the query.

    Import Statement

    import MediaPlayer

    Availability

    Available in iOS 3.0 and later.

  • Removes a filter predicate from a query.

    Declaration

    Swift

    func removeFilterPredicate(_ predicate: MPMediaPredicate!)

    Objective-C

    - (void)removeFilterPredicate:(MPMediaPredicate *)predicate

    Parameters

    predicate

    The media predicate to remove from the set of predicates for the query.

    Import Statement

    import MediaPlayer

    Availability

    Available in iOS 3.0 and later.

  • items items Property

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

    Declaration

    Swift

    var items: [AnyObject]! { get }

    Objective-C

    @property(nonatomic, readonly) NSArray *items

    Discussion

    If no items match the predicate, this method returns an empty array. On error, returns nil.

    Import Statement

    import MediaPlayer

    Availability

    Available in iOS 3.0 and later.

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

    Declaration

    Swift

    var collections: [AnyObject]! { get }

    Objective-C

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

    Import Statement

    import MediaPlayer

    Availability

    Available in iOS 3.0 and later.

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

    Declaration

    Swift

    enum MPMediaGrouping : Int { case Title case Album case Artist case AlbumArtist case Composer case Genre case Playlist case PodcastTitle }

    Objective-C

    enum { MPMediaGroupingTitle, MPMediaGroupingAlbum, MPMediaGroupingArtist, MPMediaGroupingAlbumArtist, MPMediaGroupingComposer, MPMediaGroupingGenre, MPMediaGroupingPlaylist, MPMediaGroupingPodcastTitle, }; typedef NSInteger MPMediaGrouping;

    Constants

    • Title

      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.

    • Album

      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.

    • Artist

      MPMediaGroupingArtist

      Groups and sorts media item collections by performing artist.

      Available in iOS 3.0 and later.

    • AlbumArtist

      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.

    • Composer

      MPMediaGroupingComposer

      Groups and sorts media item collections by composer.

      Available in iOS 3.0 and later.

    • Genre

      MPMediaGroupingGenre

      Groups and sorts media item collections by musical or film genre.

      Available in iOS 3.0 and later.

    • Playlist

      MPMediaGroupingPlaylist

      Groups and sorts media item collections by playlist.

      Available in iOS 3.0 and later.

    • PodcastTitle

      MPMediaGroupingPodcastTitle

      Groups and sorts media item collections by podcast title.

      Available in iOS 3.0 and later.

    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.

    Import Statement

    import MediaPlayer

    Availability

    Available in iOS 3.0 and later.