Instance Property

location

The location of this media item if available.

Declaration

@property(readonly, nonatomic, retain) NSURL *location;

Discussion

If the location of this media item is not available, this property returns ITLibMediaItemLocationTypeUnknown.

This method returns URLs that are outside of the default sandbox. In order to use the iTunesLibrary framework, a sandboxed application must have the com.apple.security.assets.music.read-write or com.apple.security.assets.music.read-only entitlement.

To access the media item file in a sandboxed app, call the startAccessingSecurityScopedResource function.

Listing 1

Accessing a media file from a sandboxed application

#import <iTunesLibrary/ITLibrary.h>
#import <iTunesLibrary/ITLibMediaItem.h>
 
// Initialize
    NSError * error = nil;
    ITLibrary* library =
        [[ITLibrary alloc] initWithAPIVersion:@"1.0" error:&error];
    if (library)
    {
        // Get first media item in the library
        NSArray * mediaItems = library.allMediaItems;
        if (mediaItems.count > 0)
        {
            // Get the location (URL) of the first media item and
            // prepare it for file read/write access.
            ITLibMediaItem * mediaItem =
                (ITLibMediaItem*)[mediaItems objectAtIndex:0];
            NSURL * mediaItemLocation = mediaItem.location;
 
            if (mediaItemLocation &&
                [mediaItemLocation startAccessingSecurityScopedResource])
            {
                // mediaItemLocation can be now used to read/write
                // the media file
                [mediaItemLocation stopAccessingSecurityScopedResource];
            }
        }
    }

For more information about using URLs that are outside the default sandbox from a sandboxed app, see Security-Scoped Bookmarks and Persistent Resource Access.

In non-sandboxed applications, you can use the returned location URL to access the media item file directly.

See Also

Obtaining Information About This Media Item

title

The title of this media item.

sortTitle

The title that iTunes uses when it sorts media items by title.

artist

Information about the artist associated with this media item.

composer

The name of the composer associated with this media item.

sortComposer

The name that iTunes uses when sorting by composer.

rating

The rating of this media item. See ratingComputed for more information.

ratingComputed

Whether this media item's rating is computed (calculated from its album rating).

startTime

If this media item is a podcast, this property contains the podcast start time.

stopTime

If this media item is a podcast, this property contains the podcast stop time.

album

If this media item is an audio track, this property contains information about the corresponding album.

genre

The genre associated with this media item as specified in the metadata of the file or by the user in iTunes.

kind

The iTunes-specific string representation of the kind of this media item; for example, "MPEG audio file" or "Book".

mediaKind

This media item's media kind. See the ITLibMediaItemMediaKind enum for a list of possible media kind values.

size

The size in bytes of this media item.

Deprecated
totalTime

The length of this media item in milliseconds.

trackNumber

The track number of this media item within its album.

category

If this media item is a podcast, this property contains the category of the podcast.

description

If this media item is a podcast, this property contains the description of the podcast.

contentRating

The rating of the content of this media item.

lyricsContentRating

If this media item has associated lyrics, this property specifies the content rating for those lyrics. See the ITLibMediaItemLyricsContentRating enum for a list of possible lyric content ratings.

addedDate

The date when this media item was added to iTunes.

modifiedDate

The date and time this media item was last modified in iTunes.

bitrate

The bitrate of this media item in kbps.

sampleRate

The sample rate of this media item in samples per second.

beatsPerMinute

If this media item is an audio track, this property contains the Beats Per Minute (BPM) of the audio.

playCount

The number of times this media item has been played in iTunes.

lastPlayedDate

The date and time this media item was last played in iTunes, or nil if this media item has not been played.

locationType

The kind of location of this media item.

artworkAvailable

Whether this media item has artwork.

artwork

The artwork of this media item.

comments

Any comments associated with this media item.

purchased

Whether this media item was purchased from the iTunes store.

drmProtected

Whether this media item is DRM protected.

video

Whether this media item is a video such as a TV show, video podcast, or movie.

videoInfo

Video information (such as width and height) about this media item, if it is a video media item.

releaseDate

The date this media item was released.

year

The year when this media item was released.

fileType

The Mac OS file type of this media item (deprecated).

Deprecated
skipCount

The number of times the user has skipped this media item in iTunes.

skipDate

The most recent date and time when this media item was skipped in iTunes.

voiceOverLanguage

The voice-over language of this media item if applicable.

volumeAdjustment

The volume adjustment used for this media item, if any.

volumeNormalizationEnergy

The volume normalization energy applied by iTunes to this media item in order to bring the average or peak amplitude to a target level.

userDisabled

Whether the user has disabled this media item in iTunes.

grouping

The grouping of this media item as specified in the metadata of the file or by the user in iTunes.