AVPlayer

Important

This is a preliminary document for an API or technology in development. Apple is supplying this information to help you plan for the adoption of the technologies and programming interfaces described herein for use on Apple-branded products. This information is subject to change, and software implemented according to this document should be tested with final operating system software and final documentation. Newer versions of this document may be provided with future betas of the API or technology.

You can observe the status of a player using key-value observing. So that you can add and remove observers safely, AVPlayer serializes notifications of changes that occur dynamically during playback on a dispatch queue. By default, this queue is the main queue (see dispatch_get_main_queue). To ensure safe access to a player’s nonatomic properties while dynamic changes in playback state may be reported, you must serialize access with the receiver’s notification queue. In the common case, such serialization is naturally achieved by invoking AVPlayer’s various methods on the main thread or queue.

External Playback Mode

External playback mode is when video data is sent to an external device such as Apple TV via AirPlay and the mini-connector-based HDMI/VGA adapters for full screen playback at its original fidelity. AirPlay Video playback is also considered as an "external playback" mode.

In "external screen" mode (also known as mirroring and second display), video data is rendered on the host device (e.g. iPhone), rendered video is recompressed and transferred to the external device, and the external device decompresses and displays the video.

External playback properties affect AirPlay Video playback and are the replacement for the deprecated AirPlay support properties.

Note

External playback properties do not apply to 30-pin-connector-based video output cables and adapters.

Parameters

rate

The playback rate to use when determining how much data to load.

completionHandler

A block to execute when the player finishes the load attempt. This block takes a single Boolean parameter that contains YEStrue if the data was loaded or NOfalse if there was a problem. For example, the value might be NOfalse if the preroll was interrupted by a time change or incompatible rate change.

Discussion

This method loads data starting at the item’s current playback time. The current rate for the playback item should always be 0 prior to calling this method. After the method calls the completion handler, you can change the item’s playback rate to begin playback.

Parameters

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 for the current player 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 YEStrue.

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

Parameters

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 for the current player 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 YEStrue.

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

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.

Parameters

The block to invoke when the seek operation has either been completed or been interrupted.

The block takes one argument:

finished

Indicated whether the seek operation completed.

Discussion

Use this method to seek to a specified time for the current player item and to be notified when the seek operation is complete.

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.

The completion handler for any prior seek request that is still in process will be invoked immediately with the finished parameter set to NOfalse. If the new request completes without being interrupted by another seek request or by any other operation the specified completion handler will be invoked with the finished parameter set to YEStrue.

Declaration

Discussion

The player will automatically switch back to the external screen mode once video playback concludes. A brief transition may be visible on the external display when automatically switching between the two modes. The default value of this property is NOfalse. The value of this property has no effect if allowsExternalPlayback is NOfalse.

Parameters

The precise time at which to match playback of the item. To use the current item’s current time, specify kCMTimeInvalid.

hostClockTime

The host time at which to synchronize playback. If you specify kCMTimeInvalid, the rate and time are set together without any external synchronization.

Discussion

This method adjusts the current item’s timebase so that the time in itemTime is in sync with the time in hostClockTime. Thus, if hostClockTime specifies a time in the past, the item’s timebase is adjusted to make it appear as if the item has been running at the specified rate since itemTime. And if hostClockTime specifies a time in the future, playback is adjusted backward (if possible) so that the value in itemTime occurs at the precise moment the host’s clock reaches the value in hostClockTime. If there is no content to play before the time specified by itemTime, playback holds until the two times come into sync.

This method does not ensure that media data is loaded before the timebase starts moving. However, if you specify a host time in the near future, that would give you some time to load the media data and prepare for playback.

Declaration

Discussion

The default value of this property is NULL, which means that the master clock is automatically chosen. When non-NULL, this property overrides the automatic choice of master clock for item timebases. This is most useful when you are synchronizing video-only movies with audio played by another source.

Important

If you specify a master clock other than the appropriate audio device’s clock, the audio may drift out of sync.

Return Value

Discussion

You must retain the returned value as long as you want the time observer to be invoked by the player. Each invocation of this method should be paired with a corresponding call to removeTimeObserver:.

The block is invoked periodically at the interval specified, interpreted according to the timeline of the current item. The block is also invoked whenever time jumps and whenever playback starts or stops. If the interval corresponds to a very short interval in real time, the player may invoke the block less frequently than requested. Even so, the player will invoke the block sufficiently often for the client to update indications of the current time appropriately in its end-user interface.

Special Considerations

Releasing the observer object without invoking removeTimeObserver: will result in undefined behavior.

Parameters

Discussion

Upon return, the caller is guaranteed that no new time observer blocks will begin executing. Depending on the calling thread and the queue used to add the time observer, an in-flight block may continue to execute after this method returns. You can guarantee synchronous time observer removal by enqueuing the call to removeTimeObserver on that queue. Alternatively, call dispatch_sync(queue, ^{}) after removeTimeObserver to wait for any in-flight blocks to finish executing.

Declaration

Discussion

When the value of this property is AVPlayerStatusFailed, you can no longer use the player for playback and you need to create a new instance to replace it. If this happens, you can check the value of the error property to determine the nature of the failure.

Declaration

Discussion

The value of this property is an error object that describes what caused the receiver to no longer be able to play items. If the receiver's status is not AVPlayerStatusFailed, the value of this property is nil.

Declaration

Discussion

Items that incorporate copy protection or other forms of security might have their visual content obscured by the player object if the current device configuration does not meet the requirements for protecting the item. This property reports whether the player is currently obscuring the item. If the current item does not require external protection or if the device configuration sufficiently protects the item, the value of this property is set to NOfalse.

You can use this property to determine whether to change your app’s user interface to reflect the change in visibility. You can observe changes to the value of this property using Key-value observing.