Mac Developer Library

Developer

ITLibMediaItem Class Reference

Options
Deployment Target:

On This Page

ITLibMediaItem

The ITLibMediaItem class describes a media item (a track) in the iTunes library such as a song, a video, or a podcast. Like all media entities, each media item has a unique identifier and a set of properties.

  • title Property

    The title of this media item. (read-only)

    Declaration

    @property (readonly, nonatomic, copy) NSString * title;

  • sortTitle Property

    The title that iTunes uses when it sorts media items by title. (read-only)

    Declaration

    @property (readonly, nonatomic, copy) NSString * sortTitle;

    Discussion

    If, for example, the title of a media item is The Sound Of Music and sort title is Sound Of Music, when iTunes sorts media items by title, this media item would be grouped with other media items whose titles begin with "S".

    If no sort title is specified, this property is nil and iTunes uses the value of the title property when it sorts media items.

  • artist Property

    Information about the artist associated with this media item. (read-only)

    Declaration

    @property (readonly, nonatomic, retain) ITLibArtist * artist;

  • composer Property

    The name of the composer associated with this media item. (read-only)

    Declaration

    @property (readonly, nonatomic, copy) NSString * composer;

  • The name that iTunes uses when sorting by composer. (read-only)

    Declaration

    @property (readonly, nonatomic, copy) NSString * sortComposer;

    Discussion

    If, for example, a media items's composer is "Ludwig van Beethoven" and the sort composer is "Beethoven Ludwig van", when iTunes sorts media items by composer, this media item would be grouped with other media items whose composers begin with "B".

    If no sort composer is specified, this property is nil and iTunes uses the value of the composer property when it sorts media items by composer.

  • rating Property

    The rating of this media item. See ratingComputed for more information. (read-only)

    Declaration

    @property (readonly, nonatomic, assign) NSInteger rating;

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

    Declaration

    @property (readonly, nonatomic, assign, getter = isRatingComputer) BOOL ratingComputed;

    Discussion

    If the user has rated an album, all tracks within that album that have no rating will receive the album rating by default. The user can override the ratings by supplying actual ratings for each track.

  • startTime Property

    If this media item is a podcast, this property contains the podcast start time. (read-only)

    Declaration

    @property (readonly, nonatomic, assign) NSUInteger startTime;

    Discussion

    If this media item is not a podcast, this property is 0.

  • stopTime Property

    If this media item is a podcast, this property contains the podcast stop time. (read-only)

    Declaration

    @property (readonly, nonatomic, assign) NSUInteger stopTime;

    Discussion

    If this media item is not a podcast, this property is 0.

  • album Property

    If this media item is an audio track, this property contains information about the corresponding album. (read-only)

    Declaration

    @property (readonly, nonatomic, retain) ITLibAlbum * album;

    Discussion

    If this media item is not an audio track, this property is nil.

  • genre Property

    The genre associated with this media item as specified in the metadata of the file or by the user in iTunes. (read-only)

    Declaration

    @property (readonly, nonatomic, copy) NSString * genre;

  • kind Property

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

    Declaration

    @property (readonly, nonatomic, copy) NSString * kind;

  • mediaKind Property

    This media item's media kind. See the ITLibMediaItemMediaKind enum for a list of possible media kind values. (read-only)

    Declaration

    @property (readonly, nonatomic, assign) ITLibMediaItemMediaKind mediaKind;

  • size Property

    The size in bytes of this media item. (read-only)

    Declaration

    @property (readonly, nonatomic, assign) NSUInteger size;

  • totalTime Property

    The length of this media item in seconds. (read-only)

    Declaration

    @property (readonly, nonatomic, assign) NSUInteger totalTime;

  • trackNumber Property

    The track number of this media item within its album. (read-only)

    Declaration

    @property (readonly, nonatomic, assign) NSUInteger trackNumber;

  • category Property

    If this media item is a podcast, this property contains the category of the podcast. (read-only)

    Declaration

    @property (readonly, nonatomic, copy) NSString * category;

    Discussion

    If the media item is not a podcast, this property is nil.

    The person who creates the podcast specifies the category.

  • description Property

    If this media item is a podcast, this property contains the description of the podcast. (read-only)

    Declaration

    @property (readonly, nonatomic, copy) NSString * description;

    Discussion

    If the media item is not a podcast, this property is nil.

  • The rating of the content of this media item. (read-only)

    Declaration

    @property (readonly, nonatomic, copy) NSString * contentRating;

  • 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. (read-only)

    Declaration

    @property (readonly, nonatomic, assign) ITLibMediaItemLyricsContentRating lyricsContentRating;

    Discussion

    If this media item does not have associated lyrics, this property is ITLibMediaItemLyricsContentRatingNone.

  • addedDate Property

    The date when this media item was added to iTunes. (read-only)

    Declaration

    @property (readonly, nonatomic, retain) NSDate * addedDate;

  • The date and time this media item was last modified in iTunes. (read-only)

    Declaration

    @property (readonly, nonatomic, retain) NSDate * modifiedDate;

  • bitrate Property

    The bitrate of this media item in kbps. (read-only)

    Declaration

    @property (readonly, nonatomic, assign) NSUInteger bitrate;

  • sampleRate Property

    The sample rate of this media item in samples per second. (read-only)

    Declaration

    @property (readonly, nonatomic, assign) NSUInteger sampleRate;

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

    Declaration

    @property (readonly, nonatomic, assign) NSUInteger beatsPerMinute;

  • playCount Property

    The number of times this media item has been played in iTunes. (read-only)

    Declaration

    @property (readonly, nonatomic, assign) NSUInteger playCount;

  • The date and time this media item was last played in iTunes, or nil if this media item has not been played. (read-only)

    Declaration

    @property (readonly, nonatomic, retain) NSDate * lastPlayedDate;

  • location Property

    The location of this media item if available. (read-only)

    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 1Accessing a media file from a sandboxed application
    1. #import <iTunesLibrary/ITLibrary.h>
    2. #import <iTunesLibrary/ITLibMediaItem.h>
    3. // Initialize
    4. NSError * error = nil;
    5. ITLibrary* library =
    6. [[ITLibrary alloc] initWithAPIVersion:@"1.0" error:&error];
    7. if (library)
    8. {
    9. // Get first media item in the library
    10. NSArray * mediaItems = library.allMediaItems;
    11. if (mediaItems.count > 0)
    12. {
    13. // Get the location (URL) of the first media item and
    14. // prepare it for file read/write access.
    15. ITLibMediaItem * mediaItem =
    16. (ITLibMediaItem*)[mediaItems objectAtIndex:0];
    17. NSURL * mediaItemLocation = mediaItem.location;
    18. if (mediaItemLocation &&
    19. [mediaItemLocation startAccessingSecurityScopedResource])
    20. {
    21. // mediaItemLocation can be now used to read/write
    22. // the media file
    23. [mediaItemLocation stopAccessingSecurityScopedResource];
    24. }
    25. }
    26. }

    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.

  • The kind of location of this media item. (read-only)

    Declaration

    @property (readonly, nonatomic, assign) ITLibMediaItemLocationType locationType;

    Discussion

    See the ITLibMediaItemLocationType enum for a list of possible location types.

  • Whether this media item has artwork. (read-only)

    Declaration

    @property (readonly, nonatomic, assign, getter=hasArtworkAvailable) BOOL artworkAvailable;

  • artwork Property

    The artwork of this media item. (read-only)

    Declaration

    @property (readonly, nonatomic, retain) ITLibArtwork * artwork;

  • comments Property

    Any comments associated with this media item. (read-only)

    Declaration

    @property (readonly, nonatomic, copy) NSString * comments;

  • purchased Property

    Whether this media item was purchased from the iTunes store. (read-only)

    Declaration

    @property (readonly, nonatomic, assign, getter=isPurchased) BOOL purchased;

  • Whether this media item is DRM protected. (read-only)

    Declaration

    @property (readonly, nonatomic, assign, getter=isDRMProtected) BOOL drmProtected;

  • video Property

    Whether this media item is a video such as a TV show, video podcast, or movie. (read-only)

    Declaration

    @property (readonly, nonatomic, assign, getter=isVideo) BOOL video;

  • videoInfo Property

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

    Declaration

    @property (readonly, nonatomic, retain) ITLibMediaItemVideoInfo * videoInfo;

    Discussion

    If this media item is not a video media item, this property is nil.

  • releaseDate Property

    The date this media item was released. (read-only)

    Declaration

    @property (readonly, nonatomic, retain) NSDate * releaseDate;

  • year Property

    The year when this media item was released. (read-only)

    Declaration

    @property (readonly, nonatomic, assign) NSUInteger year;

  • fileType Property

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

    Declaration

    @property (readonly, nonatomic, assign) NSUInteger fileType;

    Discussion

    This property will be removed in future versions of the iTunesLibrary framework.

  • skipCount Property

    The number of times the user has skipped this media item in iTunes. (read-only)

    Declaration

    @property (readonly, nonatomic, assign) NSUInteger skipCount;

  • skipDate Property

    The most recent date and time when this media item was skipped in iTunes. (read-only)

    Declaration

    @property (readonly, nonatomic, retain) NSDate * skipDate;

  • The voice-over language of this media item if applicable. (read-only)

    Declaration

    @property (readonly, nonatomic, copy) NSString * voiceOverLanguage;

    Discussion

    If the voice-over language of this media item is not applicable, this property is nil.

  • The volume adjustment used for this media item, if any. (read-only)

    Declaration

    @property (readonly, nonatomic, assign) NSInteger volumeAdjustment;

  • The volume normalization energy applied by iTunes to this media item in order to bring the average or peak amplitude to a target level. (read-only)

    Declaration

    @property (readonly, nonatomic, assign) NSUInteger volumeNormalizationEnergy;

  • Whether the user has disabled this media item in iTunes. (read-only)

    Declaration

    @property (readonly, nonatomic, assign, getter = isUserDisabled) BOOL userDisabled;

    Discussion

    Disabled tracks won't be played or synched by iTunes.

  • grouping Property

    The grouping of this media item as specified in the metadata of the file or by the user in iTunes. (read-only)

    Declaration

    @property (readonly, nonatomic, copy) NSString * grouping;

  • These constants specify the possible location types of media items. See the locationType property.

    Declaration

    enum { ITLibMediaItemLocationTypeUnknown = 0, ITLibMediaItemLocationTypeFile = 1, ITLibMediaItemLocationTypeURL = 2, ITLibMediaItemLocationTypeRemote = 3 };

    Constants

    • ITLibMediaItemLocationTypeUnknown

      The media item’s location is not known.

    • ITLibMediaItemLocationTypeFile

      The media item is in a local file.

    • ITLibMediaItemLocationTypeURL

      The media item is a remote file with a known URL.

    • ITLibMediaItemLocationTypeRemote

      The media item is in a remote file such as a network drive.

  • These constants specify the possible ratings of media item lyrics. See lyricsContentRating.

    Declaration

    enum { ITLibMediaItemLyricsContentRatingNone = 0, ITLibMediaItemLyricsContentRatingExplicit = 1, ITLibMediaItemLyricsContentRatingClean = 2 };

    Constants

    • ITLibMediaItemLyricsContentRatingNone

      No rating information for the media item lyrics is available.

    • ITLibMediaItemLyricsContentRatingExplicit

      The media item lyrics contain explicit language.

    • ITLibMediaItemLyricsContentRatingClean

      The media item lyrics do not contain explicit language.

  • These constants specify the possible media kinds of a media item. See the mediaKind property.

    Declaration

    enum { ITLibMediaItemMediaKindUnknown = 1, ITLibMediaItemMediaKindSong = 2, ITLibMediaItemMediaKindMovie = 3, ITLibMediaItemMediaKindPodcast = 4, ITLibMediaItemMediaKindAudiobook = 5, ITLibMediaItemMediaKindPDFBooklet = 6, ITLibMediaItemMediaKindMusicVideo = 7, ITLibMediaItemMediaKindTVShow = 8, ITLibMediaItemMediaKindInteractiveBooklet = 9, ITLibMediaItemMediaKindVideoPass = 11, ITLibMediaItemMediaKindHomeVideo = 12, ITLibMediaItemMediaKindRingtone = 14, ITLibMediaItemMediaKindDigitalBooklet = 15, ITLibMediaItemMediaKindIOSApplication = 16, ITLibMediaItemMediaKindVoiceMemo = 17, ITLibMediaItemMediaKindiTunesU = 18, ITLibMediaItemMediaKindBook = 19, ITLibMediaItemMediaKindPDFBook = 20, ITLibMediaItemMediaKindAlertTone = 21 };

    Constants

    • ITLibMediaItemMediaKindUnknown

      The type of media item is not known.

    • ITLibMediaItemMediaKindSong

      The media item is a song.

    • ITLibMediaItemMediaKindMovie

      The media item is a movie.

    • ITLibMediaItemMediaKindPodcast

      The media item is an audio or video podcast.

    • ITLibMediaItemMediaKindAudiobook

      The media item is an audiobook.

    • ITLibMediaItemMediaKindPDFBooklet

      The media item is an unwrapped PDF file that is part of a music album.

    • ITLibMediaItemMediaKindMusicVideo

      The media item is a music video.

    • ITLibMediaItemMediaKindTVShow

      The media item is a TV show.

    • ITLibMediaItemMediaKindInteractiveBooklet

      The media item is a QuickTIme movie with embedded Flash (deprecated).

    • ITLibMediaItemMediaKindVideoPass

      The media item is an iTunes Pass with video.

    • ITLibMediaItemMediaKindHomeVideo

      The media item is a non-iTunes store movie.

    • ITLibMediaItemMediaKindRingtone

      The media item is a ringtone.

    • ITLibMediaItemMediaKindDigitalBooklet

      The media item is an iTunes Extra or iTunes LP.

    • ITLibMediaItemMediaKindIOSApplication

      The media item is an iOS application.

    • ITLibMediaItemMediaKindVoiceMemo

      The media item is a voice memo recorded on iPod/iPhone or iPad.

    • ITLibMediaItemMediaKindiTunesU

      The media item is an iTunesU feed.

    • ITLibMediaItemMediaKindBook

      The media item is an electronic book such as an EPUB.

    • ITLibMediaItemMediaKindPDFBook

      The media item is a generic PDF file.

    • ITLibMediaItemMediaKindAlertTone

      The media item is an audio tone on an iOS device.