iPod Library Access Programming Guide 1

Here are just a few ideas for what you can do:

• Let a user assemble and play a soundtrack for your game or exercise app
• Let a user retrieve the names of their favorite artists, songs, and albums from their iPod library to send to a friend
• Provide a recommendation service for new music or artist touring schedules based on the content of a user’s iPod library

About iPod Library Access

Note: iPod library access applies only to audio-based media items. You cannot play video podcasts, movies, or television shows from the iPod library.

Music Players

Music Player Basics and Terminology

A music player is the object you use for playing media items. 

It has a playback queue, which is a list of media items to play. 

A media item is a song, audio podcast, or audio book.

On the device, the complete set of media items is called theiPod library.

Attributes you could get from the music player.

You can obtain two flavors of music player, depending on the goals of your application.

• The application music player plays music locally within your application. It is not influenced by, nor does it affect, the state of the built-in iPod application. Specifically, your music player has a different now-playing item, playback state, and modes. When a user quits your application, music that you are playing stops.
• The iPod music player, in effect, employs the built-in iPod app on your behalf; it shares the iPod’s state. When a user quits an app that is using this player, the music continues to play.

Finally, keep in mind the following two important points about using music players:

• Only one music player can play audio at a time.
• A music player can be used only on the main thread of your app.

Hello Music Player

Listing 1-1  A very bare-bones music player
// instantiate a music player
MPMusicPlayerController *myPlayer =
    [MPMusicPlayerController applicationMusicPlayer];
 
// assign a playback queue containing all media items on the device
[myPlayer setQueueWithQuery: [MPMediaQuery songsQuery]];
 
// start playing from the beginning of the queue
[myPlayer play];
           

About Music Player Change Notifications

To keep track of what a music player is doing, you register for music player change notifications. This is essential for ensuring that your application’s state and the music player’s state are well coordinated.

For example, here is the sequence of events for correctly starting up music playback. 

1. A user taps Play.
2. Your application invokes playback on the music player.
3. The music player starts playing and issues a playback-state-change notification.
4. Your application receives the notification and queries the music player’s state, confirming that it is indeed playing.
5. Your application updates its user interface accordingly—perhaps changing the Play button to say Pause.

Music player change notifications support keeping track of playback state, the now-playing item, and the music player’s playback volume.“Using Media Playback” explains how to use them.

About Media Items and the iPod Library

Media items can have a wide range of metadata.

All media item metadata is read-only. 

The Media Item Picker

When the user taps Done, a delegate method that you implement receives the list of chosen media items and then dismisses the picker’s view.

Getting Media Items Programmatically

Using programmatic access is a two step process:

1. Configure a query.
2. Ask the query to retrieve its matching media items.

A media query is a description of what to retrieve from the device iPod library and how those retrieved items should be arranged. It has two properties to configure:

• The filter is the description of what to retrieve. The filter is optional; a filterless query matches the entire iPod library.
• The grouping type is an optional key that specifies the arrangement to use for retrieved collections of media items.

Zooming in a bit more, the filter can be as simple or complex as your application demands. It consists of one or more instances of a media property predicate. Amedia property predicate is a statement of a logical condition to test each media item against. The items that satisfy the filter are retrieved from the iPod library when you invoke the query.

As the figure shows, a query can fetch items or collections.

• When you ask for items, the query returns a collection containing all the items that match the filter. The items are in “natural” order, meaning that they are ordered as iTunes shows them on the desktop.
• When you ask for collections, the media query employs not only its filter but also its grouping type.

About Collections and Playlists

A media item collection is an array of media items. You obtain collections from the device iPod library by accessing a media query’scollections property. The returned value is a sorted array of collections where each collection is an instance of the query’s grouping type.

For example, say you specify an “album” grouping type by assigning theMPMediaGroupingAlbum key to a media query—and say that query has no filter. The value of thecollections property is then the entire audio content of the iPod library arranged as albums, one album per collection. The collections (albums in this case) are sorted alphabetically. The songs (each a media item) within each collection are sorted by track number. Figure 1-6 illustrates this.

A playlist is special sort of media item collection. It has properties that regular collections do not have, such as a name and a persistent ID. Playlists are created by users on the desktop; on the device they are read-only.

MPMediaQuery *myPlaylistsQuery = [MPMediaQuery playlistsQuery];
NSArray *playlists = [myPlaylistsQuery collections];
 
for (MPMediaPlaylist *playlist in playlists) {
    NSLog (@"%@", [playlist valueForProperty: MPMediaPlaylistPropertyName]);
 
    NSArray *songs = [playlist items];
    for (MPMediaItem *song in songs) {
        NSString *songTitle =
            [song valueForProperty: MPMediaItemPropertyTitle];
        NSLog (@"\t\t%@", songTitle);
    }
}
           

Using iPod Library Change Notifications

The MPMediaLibrary object represents the state of the device iPod library. You can use it to ensure that your cache of the library contents is up to date. This is useful because a user may sync their device, changing the content of the iPod library, while your application is running.

Mixing Your Own Sounds with iPod Library Sounds