An object used to model the timing and presentation state of an asset played by the player.
SDKs
- iOS 4.0+
- macOS 10.7+
- Mac Catalyst 13.0+
- tvOS 9.0+
- watchOS 2.0+
Framework
- AVFoundation
Declaration
@interface AVPlayerItem : NSObject
Overview
An AVPlayer stores a reference to an AVAsset object, which represents the media to be played. If you need to access information about the asset before you enqueue it for playback, you can use the methods of the AVAsynchronous protocol to load the values you need. Alternatively, AVPlayer can automatically load the needed asset data for you by passing the desired set of keys to its init initializer. When the player item is ready to play, those asset properties will have been loaded and are ready for use.
AVPlayer is a dynamic object. In addition to its property values that can be changed by you, many of its read-only property values can be changed by the associated AVPlayer during the item’s preparation and playback. You can use Key-value observing to observe these state changes as they occur. One of the most important player item properties to observe is its status. The status indicates if the item is ready for playback and generally available for use. When you first create a player item, its status has a value of AVPlayer, meaning its media hasn’t been loaded and has not yet been enqueued for playback. Associating a player item with an AVPlayer immediately begins enqueuing the item’s media and preparing it for playback, but you need to wait until its status changes to AVPlayer before it’s ready for use. The following code example illustrates how to register and be notified of status changes:
- (void)prepareToPlay {
NSURL *url = <#Asset URL#>
// Create asset to be played
asset = [AVAsset assetWithURL:url];
NSArray *assetKeys = @[@"playable", @"hasProtectedContent"];
// Create a new AVPlayerItem with the asset and an
// array of asset keys to be automatically loaded
playerItem = [AVPlayerItem playerItemWithAsset:asset
automaticallyLoadedAssetKeys:assetKeys];
NSKeyValueObservingOptions options =
NSKeyValueObservingOptionOld | NSKeyValueObservingOptionNew;
// Register as an observer of the player item's status property
[playerItem addObserver:self
forKeyPath:@"status"
options:options
context:&PlayerItemContext];
// Associate the player item with the player
player = [AVPlayer playerWithPlayerItem:playerItem];
}
The prepare method registers to observe the player item’s status property using the add method. You should call this method before associating the player item with the player to make sure you capture all state changes to the item’s status.
To be notified of changes to the status, you need to implement the observe method. This method is invoked whenever the status changes giving you the chance to take some action in response (see example).
- (void)observeValueForKeyPath:(NSString *)keyPath
ofObject:(id)object
change:(NSDictionary<NSString *,id> *)change
context:(void *)context {
// Only handle observations for the PlayerItemContext
if (context != &PlayerItemContext) {
[super observeValueForKeyPath:keyPath ofObject:object change:change context:context];
return;
}
if ([keyPath isEqualToString:@"status"]) {
AVPlayerItemStatus status = AVPlayerItemStatusUnknown;
// Get the status change from the change dictionary
NSNumber *statusNumber = change[NSKeyValueChangeNewKey];
if ([statusNumber isKindOfClass:[NSNumber class]]) {
status = statusNumber.integerValue;
}
// Switch over the status
switch (status) {
case AVPlayerItemStatusReadyToPlay:
// Ready to Play
break;
case AVPlayerItemStatusFailed:
// Failed. Examine AVPlayerItem.error
break;
case AVPlayerItemStatusUnknown:
// Not ready
break;
}
}
}
The example retrieves the new status from the change dictionary and switches over its value. If the player item’s status is AVPlayer, then it’s ready for use. If a problem was encountered while attempting to load the player item’s media, the status will be AVPlayer. You can get the NSError providing the details of the failure by querying the player item’s error property.