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.