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.

Inheritance


Not Applicable

Conforms To


Not Applicable

Import Statement


Not Applicable Not Applicable
  • title title Property

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

    Declaration

    Objective-C

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

  • sortTitle sortTitle Property

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

    Declaration

    Objective-C

    @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 artist Property

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

    Declaration

    Objective-C

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

  • composer composer Property

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

    Declaration

    Objective-C

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

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

    Declaration

    Objective-C

    @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 rating Property

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

    Declaration

    Objective-C

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

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

    Declaration

    Objective-C

    @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 startTime Property

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

    Declaration

    Objective-C

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

    Discussion

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

  • stopTime stopTime Property

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

    Declaration

    Objective-C

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

    Discussion

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

  • album album Property

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

    Declaration

    Objective-C

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

    Discussion

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

  • genre 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

    Objective-C

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

  • kind kind Property

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

    Declaration

    Objective-C

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

  • mediaKind mediaKind Property

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

    Declaration

    Objective-C

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

  • size size Property

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

    Declaration

    Objective-C

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

  • totalTime totalTime Property

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

    Declaration

    Objective-C

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

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

    Declaration

    Objective-C

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

  • category category Property

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

    Declaration

    Objective-C

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

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

    Declaration

    Objective-C

    @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

    Objective-C

    @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

    Objective-C

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

    Discussion

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

  • addedDate addedDate Property

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

    Declaration

    Objective-C

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

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

    Declaration

    Objective-C

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

  • bitrate bitrate Property

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

    Declaration

    Objective-C

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

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

    Declaration

    Objective-C

    @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

    Objective-C

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

  • playCount playCount Property

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

    Declaration

    Objective-C

    @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

    Objective-C

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

  • location location Property

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

    Declaration

    Objective-C

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

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

    Declaration

    Objective-C

    @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

    Objective-C

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

  • artwork artwork Property

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

    Declaration

    Objective-C

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

  • comments comments Property

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

    Declaration

    Objective-C

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

  • purchased purchased Property

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

    Declaration

    Objective-C

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

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

    Declaration

    Objective-C

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

  • video video Property

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

    Declaration

    Objective-C

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

  • videoInfo videoInfo Property

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

    Declaration

    Objective-C

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

    Discussion

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

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

    Declaration

    Objective-C

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

  • year year Property

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

    Declaration

    Objective-C

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

  • fileType fileType Property

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

    Declaration

    Objective-C

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

    Discussion

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

  • skipCount skipCount Property

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

    Declaration

    Objective-C

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

  • skipDate skipDate Property

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

    Declaration

    Objective-C

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

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

    Declaration

    Objective-C

    @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

    Objective-C

    @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

    Objective-C

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

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

    Declaration

    Objective-C

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

    Discussion

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

  • grouping 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

    Objective-C

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

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

    Declaration

    Objective-C

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

    Constants

    • ITLibMediaItemLocationTypeUnknown

      ITLibMediaItemLocationTypeUnknown

      The media item’s location is not known.

    • ITLibMediaItemLocationTypeFile

      ITLibMediaItemLocationTypeFile

      The media item is in a local file.

    • ITLibMediaItemLocationTypeURL

      ITLibMediaItemLocationTypeURL

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

    • ITLibMediaItemLocationTypeRemote

      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

    Objective-C

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

    Constants

    • ITLibMediaItemLyricsContentRatingNone

      ITLibMediaItemLyricsContentRatingNone

      No rating information for the media item lyrics is available.

    • ITLibMediaItemLyricsContentRatingExplicit

      ITLibMediaItemLyricsContentRatingExplicit

      The media item lyrics contain explicit language.

    • ITLibMediaItemLyricsContentRatingClean

      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

    Objective-C

    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

      ITLibMediaItemMediaKindUnknown

      The type of media item is not known.

    • ITLibMediaItemMediaKindSong

      ITLibMediaItemMediaKindSong

      The media item is a song.

    • ITLibMediaItemMediaKindMovie

      ITLibMediaItemMediaKindMovie

      The media item is a movie.

    • ITLibMediaItemMediaKindPodcast

      ITLibMediaItemMediaKindPodcast

      The media item is an audio or video podcast.

    • ITLibMediaItemMediaKindAudiobook

      ITLibMediaItemMediaKindAudiobook

      The media item is an audiobook.

    • ITLibMediaItemMediaKindPDFBooklet

      ITLibMediaItemMediaKindPDFBooklet

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

    • ITLibMediaItemMediaKindMusicVideo

      ITLibMediaItemMediaKindMusicVideo

      The media item is a music video.

    • ITLibMediaItemMediaKindTVShow

      ITLibMediaItemMediaKindTVShow

      The media item is a TV show.

    • ITLibMediaItemMediaKindInteractiveBooklet

      ITLibMediaItemMediaKindInteractiveBooklet

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

    • ITLibMediaItemMediaKindVideoPass

      ITLibMediaItemMediaKindVideoPass

      The media item is an iTunes Pass with video.

    • ITLibMediaItemMediaKindHomeVideo

      ITLibMediaItemMediaKindHomeVideo

      The media item is a non-iTunes store movie.

    • ITLibMediaItemMediaKindRingtone

      ITLibMediaItemMediaKindRingtone

      The media item is a ringtone.

    • ITLibMediaItemMediaKindDigitalBooklet

      ITLibMediaItemMediaKindDigitalBooklet

      The media item is an iTunes Extra or iTunes LP.

    • ITLibMediaItemMediaKindIOSApplication

      ITLibMediaItemMediaKindIOSApplication

      The media item is an iOS application.

    • ITLibMediaItemMediaKindVoiceMemo

      ITLibMediaItemMediaKindVoiceMemo

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

    • ITLibMediaItemMediaKindiTunesU

      ITLibMediaItemMediaKindiTunesU

      The media item is an iTunesU feed.

    • ITLibMediaItemMediaKindBook

      ITLibMediaItemMediaKindBook

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

    • ITLibMediaItemMediaKindPDFBook

      ITLibMediaItemMediaKindPDFBook

      The media item is a generic PDF file.

    • ITLibMediaItemMediaKindAlertTone

      ITLibMediaItemMediaKindAlertTone

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