AVPlayerItem Class Reference

Inherits from
NSObject
Conforms to
NSCopying
NSObject (NSObject)
Framework
/System/Library/Frameworks/AVFoundation.framework
Availability
Available in iOS 4.0 and later.
Companion guide
AV Foundation Programming Guide
Declared in
AVPlayerItem.h
Related sample code

Overview

An AVPlayerItem represents the presentation state of an asset that’s played by an AVPlayer object, and lets you observe that state.

A object carries a reference to an AVAsset object and presentation settings for that asset, including track enabled state. If you need to inspect the media assets themselves, you should message the AVAsset object itself.

You can initialize a player item using an URL (playerItemWithURL: and initWithURL:); the resource types referenced by the URL may include, but aren't necessarily limited to, those with the following corresponding UTIs:

If you want to play an asset more than once within a sequence of items, you must create independent instances of AVPlayerItem for each placement in the player's queue.

Tasks

Creating a Player Item

Getting Information About an Item

Moving the Playhead

Information About Playback

Timing Information

Settings

Accessing Logs

Selecting Media Options

Accessing the Text Style Rules

Managing the Item’s Outputs

Properties

asset

The underlying asset provided during initialization. (read-only)

@property(nonatomic, readonly) AVAsset *asset
Availability
  • Available in iOS 4.0 and later.
Related Sample Code
Declared In
AVPlayerItem.h

audioMix

The audio mix parameters to be applied during playback.

@property(nonatomic, copy) AVAudioMix *audioMix
Availability
  • Available in iOS 4.0 and later.
Related Sample Code
Declared In
AVPlayerItem.h

canPlayFastForward

A Boolean value indicating whether the item can be played at rates greater than 1.0. (read-only)

@property(nonatomic, readonly) BOOL canPlayFastForward
Availability
  • Available in iOS 5.0 and later.
See Also
Declared In
AVPlayerItem.h

canPlayFastReverse

A Boolean value indicating whether the item can be played at rates less than –1.0. (read-only)

@property(nonatomic, readonly) BOOL canPlayFastReverse
Availability
  • Available in iOS 5.0 and later.
See Also
Declared In
AVPlayerItem.h

canPlayReverse

A Boolean value indicating whether the item can be played with a rate of -1.0. (read-only)

@property (nonatomic, readonly) BOOL canPlayReverse
Availability
  • Available in iOS 6.0 and later.
Declared In
AVPlayerItem.h

canPlaySlowForward

A Boolean value indicating whether the item can be played at a rate between 0.0 and 1.0. (read-only)

@property (nonatomic, readonly) BOOL canPlaySlowForward
Availability
  • Available in iOS 6.0 and later.
See Also
Declared In
AVPlayerItem.h

canPlaySlowReverse

A Boolean value indicating whether the item can be played at a rate between -1.0 and 0.0. (read-only)

@property (nonatomic, readonly) BOOL canPlaySlowReverse
Availability
  • Available in iOS 6.0 and later.
See Also
Declared In
AVPlayerItem.h

canStepBackward

A Boolean value indicating whether the item supports stepping backward. (read-only)

@property (nonatomic, readonly) BOOL canStepBackward
Discussion

Once the item becomes ready to play, the value of this property does not change. This behavior applies even when boundary conditions, such as when the item’s current time is kCMTimeZero, have been reached.

Availability
  • Available in iOS 6.0 and later.
See Also
Declared In
AVPlayerItem.h

canStepForward

A Boolean value indicating whether the item supports stepping forward. (read-only)

@property (nonatomic, readonly) BOOL canStepForward
Discussion

Once the item becomes ready to play, the value of this property does not change. This behavior applies even when boundary conditions, such as when the item’s current time is equal to its end time, have been reached.

Availability
  • Available in iOS 6.0 and later.
See Also
Declared In
AVPlayerItem.h

duration

Indicates the duration of the item. (read-only)

@property(nonatomic, readonly) CMTime duration
Discussion

Indicates the duration of the item, not considering either its forwardPlaybackEndTime or reversePlaybackEndTime.

Availability
  • Available in iOS 4.3 and later.
Declared In
AVPlayerItem.h

error

If the receiver's status is AVPlayerItemStatusFailed, this describes the error that caused the failure. (read-only)

@property(nonatomic, readonly) NSError *error
Discussion

The value of this property is an error that describes what caused the receiver to no longer be able to be played.

If the receiver's status is not AVPlayerItemStatusFailed, the value of this property is nil.

Availability
  • Available in iOS 4.0 and later.
Declared In
AVPlayerItem.h

forwardPlaybackEndTime

The time at which forward playback ends.

@property(nonatomic) CMTime forwardPlaybackEndTime
Discussion

The value indicated the time at which playback should end when the playback rate is positive (see AVPlayer’s rate property).

The default value is kCMTimeInvalid, which indicates that no end time for forward playback is specified. In this case, the effective end time for forward playback is the item’s duration.

The value of this property has no effect on playback when the rate is negative.

Availability
  • Available in iOS 4.0 and later.
Declared In
AVPlayerItem.h

loadedTimeRanges

The time ranges of the item that have been loaded. (read-only)

@property(nonatomic, readonly) NSArray *loadedTimeRanges
Discussion

The array contains NSValue objects containing a CMTimeRange value.

Availability
  • Available in iOS 4.0 and later.
Declared In
AVPlayerItem.h

outputs

The outputs associated with the item. (read-only)

@property (nonatomic, readonly) NSArray *outputs
Discussion

This property contains the collection of AVPlayerItemOutput objects used to transfer media data to the player object.

Availability
  • Available in iOS 6.0 and later.
Declared In
AVPlayerItem.h

playbackBufferEmpty

Indicates whether playback has consumed all buffered media and that playback will stall or end. (read-only)

@property(nonatomic, readonly, getter=isPlaybackBufferEmpty) BOOL playbackBufferEmpty
Availability
  • Available in iOS 4.0 and later.
See Also
Declared In
AVPlayerItem.h

playbackBufferFull

Indicates whether the internal media buffer is full and that further I/O is suspended. (read-only)

@property(nonatomic, readonly, getter=isPlaybackBufferFull) BOOL playbackBufferFull
Discussion

Despite the playback buffer reaching capacity there might not exist sufficient statistical data to support a playbackLikelyToKeepUp prediction of YES.

Availability
  • Available in iOS 4.0 and later.
See Also
Declared In
AVPlayerItem.h

playbackLikelyToKeepUp

Indicates whether the item will likely play through without stalling (read-only)

@property(nonatomic, readonly, getter=isPlaybackLikelyToKeepUp) BOOL playbackLikelyToKeepUp
Discussion

This property communicates a prediction of playability. Factors considered in this prediction include I/O throughput and media decode performance. It is possible for playbackLikelyToKeepUp to indicate NO while the property playbackBufferFull indicates YES. In this event the playback buffer has reached capacity but there isn't the statistical data to support a prediction that playback is likely to keep up in the future. It is up to you to decide whether to continue media playback.

Availability
  • Available in iOS 4.0 and later.
See Also
Declared In
AVPlayerItem.h

presentationSize

The size at which the visual portion of the item is presented by the player. (read-only)

@property(nonatomic, readonly) CGSize presentationSize
Discussion

You can scale the presentation size to fit within the bounds of a player layer using its videoGravity property. You can also scale the presentation size arbitrarily using the frame property of an AVPlayerLayer object.

Availability
  • Available in iOS 4.0 and later.
Declared In
AVPlayerItem.h

reversePlaybackEndTime

The time at which reverse playback ends.

@property(nonatomic) CMTime reversePlaybackEndTime
Discussion

The value indicated the time at which playback should end when the playback rate is negative (see AVPlayer’s rate property).

The default value is kCMTimeInvalid, which indicates that no end time for reverse playback is specified. In this case, the effective end time for reverse playback is kCMTimeZero.

The value of this property has no effect on playback when the rate is positive.

Availability
  • Available in iOS 4.0 and later.
Declared In
AVPlayerItem.h

seekableTimeRanges

An array of time ranges within which it is possible to seek. (read-only)

@property(nonatomic, readonly) NSArray *seekableTimeRanges
Discussion

The array contains NSValue objects containing a CMTimeRange value.

Availability
  • Available in iOS 4.0 and later.
Declared In
AVPlayerItem.h

seekingWaitsForVideoCompositionRendering

A Boolean value indicating whether the item’s timing follows the displayed video frame when seeking with a video composition.

@property (nonatomic) BOOL seekingWaitsForVideoCompositionRendering
Discussion

By default, item timing is updated as quickly as possible during seeking. Specifically, the item does not wait for new frames to be rendered when seeking during normal playback. In most situations, the latency between the completion of a seek operation and the display of a video frame at the new time is negligible. However, when video compositions are in use, the processing of video may introduce noticeable latency. Setting the value of this property to YES causes the item’s timing to be updated only after the corresponding video frame has been displayed. For example, this allows an AVSynchronizedLayer object associated with the item to remain in sync with the displayed video.

This property has no effect on items whose videoComposition property is nil.

Availability
  • Available in iOS 6.0 and later.
Declared In
AVPlayerItem.h

status

The status of the player item. (read-only)

@property(nonatomic, readonly) AVPlayerItemStatus status
Discussion

For example, whether the item is playable. For possible values, see “AVPlayerItemStatus.”

Availability
  • Available in iOS 4.0 and later.
Related Sample Code
Declared In
AVPlayerItem.h

textStyleRules

An array of text style rules to apply to subtitles and other legible text.

@property (nonatomic, copy) NSArray *textStyleRules
Discussion

You can use this property to assign an array of AVTextStyleRule objects to the item. Each rule specifies both the style information and the range of text to which that styling should apply.

Availability
  • Available in iOS 6.0 and later.
Declared In
AVPlayerItem.h

timebase

The timebase information for the item. (read-only)

@property (nonatomic, readonly) __attribute__((NSObject)) CMTimebaseRef timebase
Discussion

Timebase information is used to synchronize playback of the current item with the master clock. You can use this property to access the timebase information, but you cannot use it to set the time or rate of playback.

Availability
  • Available in iOS 6.0 and later.
Declared In
AVPlayerItem.h

timedMetadata

The timed metadata played most recently by the media stream. (read-only)

@property(nonatomic, readonly) NSArray *timedMetadata
Discussion

The array contains instances of AVMetadataItem.

Availability
  • Available in iOS 4.0 and later.
Declared In
AVPlayerItem.h

tracks

An array of AVPlayerItemTrack objects. (read-only)

@property(nonatomic, readonly) NSArray *tracks
Discussion

This property can change dynamically during playback.

You can observe this property using key-value observing.

Availability
  • Available in iOS 4.0 and later.
Declared In
AVPlayerItem.h

videoComposition

The video composition settings to be applied during playback.

@property(nonatomic, copy) AVVideoComposition *videoComposition
Availability
  • Available in iOS 4.0 and later.
Related Sample Code
Declared In
AVPlayerItem.h

Class Methods

playerItemWithAsset:

Returns a new player item for a given asset.

+ (AVPlayerItem *)playerItemWithAsset:(AVAsset *)asset
Parameters
asset

An asset to play.

Return Value

A new player item, initialized to play asset.

Availability
  • Available in iOS 4.0 and later.
Related Sample Code
Declared In
AVPlayerItem.h

playerItemWithURL:

Returns a new player item, prepared to use a given URL.

+ (AVPlayerItem *)playerItemWithURL:(NSURL *)URL
Parameters
URL

An URL.

Return Value

A new player item, prepared to use URL.

Special Considerations

This method immediately returns the item, but with the status AVPlayerItemStatusUnknown.

If the URL contains valid data that can be used by the player item, the status later changes to AVPlayerItemStatusReadyToPlay.

If the URL contains no valid data or otherwise can't be used by the player item, the status later changes to AVPlayerItemStatusFailed.

Availability
  • Available in iOS 4.0 and later.
See Also
Related Sample Code
Declared In
AVPlayerItem.h

Instance Methods

accessLog

Returns an object that represents a snapshot of the network access log.

- (AVPlayerItemAccessLog *)accessLog
Return Value

An object that represents a snapshot of the network access log. The returned value can be nil.

Discussion

If the method returns nil, there is no logging information currently available for the player item.

Availability
  • Available in iOS 4.3 and later.
Declared In
AVPlayerItem.h

addOutput:

Adds the specified player item output object to the receiver.

- (void)addOutput:(AVPlayerItemOutput *)output
Parameters
output

The player item output object to associate with the item.

Discussion

When you add an AVPlayerItemOutput object to an item, the samples associated with that output object are processed according to the rules for mixing, composing, or excluding content that the AVPlayer object honors for the specific media type. For example, video media is composed according to the instructions provided by the player item’s video composition object and audio media is mixed according to the parameters of its audio mix object.

Availability
  • Available in iOS 6.0 and later.
See Also
Related Sample Code
Declared In
AVPlayerItem.h

cancelPendingSeeks

Cancel any pending seek requests and invoke the corresponding completion handlers if present.

- (void)cancelPendingSeeks
Discussion

Use this method to cancel and release the completion handlers of pending seeks.

The finished parameter of the completion handlers will be set to NO.

Availability
  • Available in iOS 5.0 and later.
Declared In
AVPlayerItem.h

currentDate

Returns the current time of the item as an NSDate object.

- (NSDate *)currentDate
Return Value

The current time of the item as an NSDate object, or nil if playback is not mapped to any date.

Availability
  • Available in iOS 4.3 and later.
See Also
Declared In
AVPlayerItem.h

currentTime

Returns the current time of the item.

- (CMTime)currentTime
Return Value

The current time of the item.

Availability
  • Available in iOS 4.0 and later.
See Also
Declared In
AVPlayerItem.h

errorLog

Returns an object that represents a snapshot of the error log.

- (AVPlayerItemErrorLog *)errorLog
Return Value

An object that represents a snapshot of the error log. The returned value can be nil.

Discussion

If the method returns nil, there is no logging information currently available for the player item.

Availability
  • Available in iOS 4.3 and later.
Declared In
AVPlayerItem.h

initWithAsset:

Initializes a new player item for a given asset.

- (id)initWithAsset:(AVAsset *)asset
Parameters
asset

An asset to play.

Return Value

The receiver, initialized to play asset.

Availability
  • Available in iOS 4.0 and later.
Declared In
AVPlayerItem.h

initWithURL:

Prepares a player item with a given URL.

- (id)initWithURL:(NSURL *)URL
Parameters
URL

An URL.

Return Value

The receiver, prepared to use URL.

Special Considerations

This method immediately returns the item, but with the status AVPlayerItemStatusUnknown.

If the URL contains valid data that can be used by the player item, the status later changes to AVPlayerItemStatusReadyToPlay.

If the URL contains no valid data or otherwise can't be used by the player item, the status later changes to AVPlayerItemStatusFailed.

Availability
  • Available in iOS 4.0 and later.
See Also
Declared In
AVPlayerItem.h

removeOutput:

Removes the specified player item output object from the receiver.

- (void)removeOutput:(AVPlayerItemOutput *)output
Parameters
output

The player item output object to remove.

Availability
  • Available in iOS 6.0 and later.
Declared In
AVPlayerItem.h

seekToDate:

Moves the playback cursor to a given date.

- (BOOL)seekToDate:(NSDate *)date
Parameters
date

The date to which to move the playback cursor.

Return Value

YES if the playhead was moved to date, otherwise NO.

Discussion

For playback content that is associated with a range of dates, this method moves the playhead to point within that range. This method will fail (return NO) if date is outside the range or if the content is not associated with a range of dates.

Availability
  • Available in iOS 4.0 and later.
See Also
Declared In
AVPlayerItem.h

seekToDate:completionHandler:

Moves the playback cursor to the time given by the specified date object.

- (BOOL)seekToDate:(NSDate *)date completionHandler:(void (^)(BOOL finished))completionHandler
Parameters
date

The time to which to seek.

completionHandler

The block to invoke when the seek operation has either been completed or been interrupted. The block takes one argument:

finished

Indicates whether the seek operation completed.

Return Value

YES if the playhead moved to the specified date or NO if it did not.

Discussion

Use this method to seek to a specified time in the item item and be notified when the operation completes. If the seek request completes without being interrupted (either by another seek request or by any other operation), the completion handler you provide is executed with the finished parameter set to YES.

If another seek request is already in progress when you call this method, the completion handler for the in-progress seek request is executed immediately with the finished parameter set to NO.

Availability
  • Available in iOS 6.0 and later.
Declared In
AVPlayerItem.h

seekToTime:

Moves the playback cursor to a given time.

- (void)seekToTime:(CMTime)time
Parameters
time

The time to which to move the playback cursor.

Discussion

The time seeked to may differ from the specified time for efficiency. For sample accurate seeking see seekToTime:toleranceBefore:toleranceAfter:.

Availability
  • Available in iOS 4.0 and later.
See Also
Declared In
AVPlayerItem.h

seekToTime:completionHandler:

Moves the playback cursor to a given time.

- (void)seekToTime:(CMTime)time completionHandler:(void (^)(BOOL finished))completionHandler
Parameters
time

The time to which to seek.

completionHandler

The block to invoke when the seek operation has either been completed or been interrupted. The block takes one argument:

finished

Indicates whether the seek operation completed.

Discussion

Use this method to seek to a specified time in the item item and be notified when the operation completes. If the seek request completes without being interrupted (either by another seek request or by any other operation), the completion handler you provide is executed with the finished parameter set to YES.

If another seek request is already in progress when you call this method, the completion handler for the in-progress seek request is executed immediately with the finished parameter set to NO.

Availability
  • Available in iOS 5.0 and later.
See Also
Declared In
AVPlayerItem.h

seekToTime:toleranceBefore:toleranceAfter:

Moves the playback cursor within a specified time bound.

- (void)seekToTime:(CMTime)time toleranceBefore:(CMTime)toleranceBefore toleranceAfter:(CMTime)toleranceAfter
Parameters
time

The time to which you would like to move the playback cursor.

toleranceBefore

The tolerance allowed before time.

toleranceAfter

The tolerance allowed after time.

Discussion

The time seeked to will be within the range [time-beforeTolerance, time+afterTolerance], and may differ from the specified time for efficiency. If you pass kCMTimeZero for both toleranceBefore and toleranceAfter (to request sample accurate seeking), you may incur additional decoding delay.

Passing kCMTimePositiveInfinity for both toleranceBefore and toleranceAfter is the same as messaging seekToTime: directly.

Availability
  • Available in iOS 4.0 and later.
See Also
Declared In
AVPlayerItem.h

seekToTime:toleranceBefore:toleranceAfter:completionHandler:

Moves the playback cursor within a specified time bound.

- (void)seekToTime:(CMTime)time toleranceBefore:(CMTime)toleranceBefore toleranceAfter:(CMTime)toleranceAfter completionHandler:(void (^)(BOOL finished))completionHandler
Parameters
time

The time to which to seek.

toleranceBefore

The temporal tolerance before time.

Pass kCMTimeZero to request sample accurate seeking (this may incur additional decoding delay).

toleranceAfter

The temporal tolerance after time.

Pass kCMTimeZero to request sample accurate seeking (this may incur additional decoding delay).

completionHandler

The block to invoke when the seek operation has finished.

Discussion

Use this method to seek to a specified time for the item.

The time seeked to will be within the range [time-toleranceBefore, time+toleranceAfter] and may differ from time for efficiency.

Invoking this method with kCMTimePositiveInfinity for toleranceBefore and toleranceAfter is the same as invoking seekToTime:completionHandler: directly.

Seeking is constrained by the collection of seekable time ranges. If you seek to a time outside all of the seekable ranges the seek will result in a currentTime within the seekable ranges.

Availability
  • Available in iOS 5.0 and later.
Declared In
AVPlayerItem.h

selectedMediaOptionInMediaSelectionGroup:

Indicates the media selection option that's currently selected from the specified group.

- (AVMediaSelectionOption *)selectedMediaOptionInMediaSelectionGroup:(AVMediaSelectionGroup *)mediaSelectionGroup
Parameters
mediaSelectionGroup

A media selection group obtained from the player item’s asset.

Return Value

An instance of AVMediaSelectionOption that describes the currently selection option in the group.

Discussion

If the value of the allowsEmptySelection property of mediaSelectionGroup is YES, the currently selected option in the group may be nil.

Availability
  • Available in iOS 5.0 and later.
Declared In
AVPlayerItem.h

selectMediaOption:inMediaSelectionGroup:

Selects the media option described by a specified instance of AVMediaSelectionOption in a given media selection group and deselects all other options in that group.

- (void)selectMediaOption:(AVMediaSelectionOption *)mediaSelectionOption inMediaSelectionGroup:(AVMediaSelectionGroup *)mediaSelectionGroup
Parameters
mediaSelectionOption

The option to select.

If the value of the allowsEmptySelection property of mediaSelectionGroup is YES, you can pass nil to deselect all media selection options in the group.

mediaSelectionGroup

The media selection group, obtained from the receiver's asset, that contains mediaSelectionOption.

Discussion

If mediaSelectionOption isn’t a member of the mediaSelectionGroup, no change in presentation state will result.

If multiple options within a group meet your criteria for selection according to locale or other considerations, and if these options are otherwise indistinguishable to you according to media characteristics that are meaningful for your application, content is typically authored so that the first available option that meets your criteria is appropriate for selection.

Availability
  • Available in iOS 5.0 and later.
Declared In
AVPlayerItem.h

stepByCount:

Moves the player’s current item’s current time forward or backward by a specified number of steps.

- (void)stepByCount:(NSInteger)stepCount
Parameters
stepCount

The number of steps by which to move.

A positive number steps forward, a negative number steps backward.

Discussion

The size of each step depends on the receiver’s enabled AVPlayerItemTrack objects (see tracks).

Availability
  • Available in iOS 4.0 and later.
Declared In
AVPlayerItem.h

Constants

AVPlayerItemStatus

Constants that represent the status of an item

enum {
   AVPlayerItemStatusUnknown,
   AVPlayerItemStatusReadyToPlay,
   AVPlayerItemStatusFailed
};
typedef NSInteger AVPlayerItemStatus;
Constants
AVPlayerItemStatusUnknown

The item’s status is unknown.

Available in iOS 4.0 and later.

Declared in AVPlayerItem.h.

AVPlayerItemStatusReadyToPlay

The item is ready to play.

Available in iOS 4.0 and later.

Declared in AVPlayerItem.h.

AVPlayerItemStatusFailed

The item cannot be played.

Available in iOS 4.0 and later.

Declared in AVPlayerItem.h.

Notification Key

Key to retrieve information from a notification’s user info dictionary.

extern NSString *const AVPlayerItemFailedToPlayToEndTimeErrorKey
Constants
AVPlayerItemFailedToPlayToEndTimeErrorKey

The key to retrieve an error object (NSError) from the user info dictionary of an AVPlayerItemTimeJumpedNotification notification.

Available in iOS 4.3 and later.

Declared in AVPlayerItem.h.

Notifications

AVPlayerItemDidPlayToEndTimeNotification

Posted when the item has played to its end time.

The notification’s object is the item that finished playing.

Availability
Declared In
AVPlayerItem.h

AVPlayerItemFailedToPlayToEndTimeNotification

Posted when the item failed to play to its end time.

The notification’s object is the item that finished playing.

The user info dictionary contains an error object that describes the problem—seeAVPlayerItemFailedToPlayToEndTimeErrorKey.

Availability
Declared In
AVPlayerItem.h

AVPlayerItemTimeJumpedNotification

Posted when the item’s current time has changed discontinuously.

The notification’s object is the item.

Availability
Declared In
AVPlayerItem.h

AVPlayerItemPlaybackStalledNotification

Posted when some media did not arrive in time to continue playback.

The notification’s object is the AVPlayerItem instance whose playback was not allowed to continue.

Availability
Declared In
AVPlayerItem.h

AVPlayerItemNewAccessLogEntryNotification

Posted when a new access log entry has been added.

The notification’s object is the access log entry that was added.

Availability
Declared In
AVPlayerItem.h

AVPlayerItemNewErrorLogEntryNotification

Posted when a new error log entry has been added.

The notification’s object is the error log entry that was added.

Availability
Declared In
AVPlayerItem.h


© 2012 Apple Inc. All Rights Reserved. (Last updated: 2012-09-19)

Did this document help you? Yes It's good, but... Not helpful...