Class

AVPlayer

An object that provides the interface to control the player’s transport behavior.

Declaration

@interface AVPlayer : NSObject

Overview

An AVPlayer is a controller object used to manage the playback and timing of a media asset. You can use an AVPlayer to play local and remote file-based media, such as QuickTime movies and MP3 audio files, as well as audiovisual media served using HTTP Live Streaming.

AVPlayer is for playing a single media asset at a time. You can reuse the player instance to play additional media assets using its replaceCurrentItemWithPlayerItem: method, but it manages the playback of only a single media asset at a time. The framework also provides a subclass of AVPlayer, called AVQueuePlayer, you use to create and manage the queuing of media assets played sequentially.

You use an AVPlayer to play media assets, which AVFoundation models using the AVAsset class. AVAsset only models the static aspects of the media, such as its duration or creation date, and on its own, is unsuitable for playback with an AVPlayer. To play an asset, you need to create an instance of its dynamic counterpart found in AVPlayerItem. This object models the timing and presentation state of an asset played by an instance of AVPlayer. See the AVPlayerItem reference for more details.

AVPlayer is a dynamic object whose state continuously changes. There are two approaches you can use to observe a player’s state:

  • General State Observations: You can use Key-value observing (KVO) to observe state changes to many of the player’s dynamic properties, such as its currentItem or its playback rate. You should register and unregister for KVO change notifications on the main thread. This avoids the possibility of receiving a partial notification when making a change on another thread. AVFoundation invokes observeValueForKeyPath:ofObject:change:context: on the main thread, even when making the change operation on another thread.

  • Timed State Observations: KVO works well for general state observations, but isn’t intended for observing continuously changing state like the player’s time. AVPlayer provides two methods to observe time changes:

    These methods let you observe time changes either periodically or by boundary, respectively. As changes occur, invoke the callback block or closure you supply to these methods to give you the opportunity to take some action such as updating the state of your player’s user interface.

AVPlayer and AVPlayerItem are nonvisual objects, meaning that on their own they are unable to present an asset’s video onscreen. You have two primary approaches you can use to present your video content onscreen:

  • AVKit: The best way to present your video content is with the AVKit framework’s AVPlayerViewController class in iOS and tvOS, or the AVPlayerView class in macOS. These classes present the video content, along with playback controls and other media features giving you a full-featured playback experience.

  • AVPlayerLayer: When building a custom interface for your player, use AVPlayerLayer. The player layer can be set as a view’s backing layer or can be added directly to the layer hierarchy. Unlike AVPlayerView and AVPlayerViewController, a player layer doesn’t present any playback controls—it presents the visual content onscreen. It’s up to you to build the playback transport controls to play, pause, and seek through the media.

Alongside the visual content presented with AVKit or AVPlayerLayer, you can also present animated content synchronized with the player’s timing using AVSynchronizedLayer. Use the synchronized layer to confer the current player timing onto its layer subtree. You can use AVSynchronizedLayer to build custom effects in Core Animation, such as animated lower thirds or video transitions, and have them play in sync with the timing of the player’s current AVPlayerItem.

External Playback Mode

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

In "external screen" mode (also known as mirroring and second display), the host device renders the video data. The host device recompresses and transfers the rendered video 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.

Topics

Creating a Player

- initWithURL:

Creates a new player to play a single audiovisual resource referenced by a given URL.

+ playerWithURL:

Returns a new player to play a single audiovisual resource referenced by a given URL.

- initWithPlayerItem:

Creates a new player to play the specified player item.

+ playerWithPlayerItem:

Returns a new player initialized to play the specified player item.

Managing Playback

- play

Begins playback of the current item.

- pause

Pauses playback of the current item.

rate

The current playback rate.

actionAtItemEnd

The action to perform when the current player item has finished playing.

AVPlayerActionAtItemEnd

The actions a player should take when it finishes playing.

- replaceCurrentItemWithPlayerItem:

Replaces the current player item with a new player item.

preventsDisplaySleepDuringVideoPlayback

A Boolean value that indicates whether video playback prevents display and device sleep.

Managing Automatic Waiting Behavior

automaticallyWaitsToMinimizeStalling

A Boolean value that indicates whether the player should automatically delay playback in order to minimize stalling.

reasonForWaitingToPlay

The reason the player is currently waiting for playback to begin or resume.

AVPlayerWaitingReason

The reasons the player is waiting begin or resume playback.

timeControlStatus

A status that indicates whether playback is currently in progress, paused indefinitely, or suspended while waiting for appropriate network conditions.

AVPlayerTimeControlStatus

The player statuses indicating a playback rate change.

- playImmediatelyAtRate:

Plays the available media data immediately, at the specified rate.

Managing Time

- currentTime

Returns the current time of the current player item.

- seekToTime:

Sets the current playback time to the specified time.

- seekToDate:

Sets the current playback time to the time specified by the date object.

- seekToTime:completionHandler:

Sets the current playback time to the specified time and executes the specified block when the seek operation completes or is interrupted.

- seekToDate:completionHandler:

Sets the current playback time to the specified time and executes the specified block when the seek operation completes or is interrupted.

- seekToTime:toleranceBefore:toleranceAfter:

Sets the current playback time within a specified time bound.

- seekToTime:toleranceBefore:toleranceAfter:completionHandler:

Sets the current playback time within a specified time bound and invokes the specified block when the seek operation completes or is interrupted.

Observing Time

- addPeriodicTimeObserverForInterval:queue:usingBlock:

Requests the periodic invocation of a given block during playback to report changing time.

- addBoundaryTimeObserverForTimes:queue:usingBlock:

Requests the invocation of a block when specified times are traversed during normal playback.

- removeTimeObserver:

Cancels a previously registered periodic or boundary time observer.

Configuring Media Selection Criteria Settings

appliesMediaSelectionCriteriaAutomatically

A Boolean value that indicates whether the receiver should apply the current selection criteria automatically to player items.

- mediaSelectionCriteriaForMediaCharacteristic:

Returns the automatic selection criteria for media items with the specified media characteristic.

- setMediaSelectionCriteria:forMediaCharacteristic:

Applies automatic selection criteria for media that has the specified media characteristic.

Managing External Playback

allowsExternalPlayback

A Boolean value that indicates whether the player allows switching to external playback mode.

externalPlaybackActive

A Boolean value that indicates whether the player is currently playing video in external playback mode.

usesExternalPlaybackWhileExternalScreenIsActive

A Boolean value that indicates whether the player should automatically switch to external playback mode while the external screen mode is active.

externalPlaybackVideoGravity

The video gravity of the player for external playback mode only.

AVLayerVideoGravity

A value that defines how the video is displayed within a layer’s bounds rectangle.

Synchronizing Playback to an External Source

The advanced synchronization and rate control methods in this section are currently only supported for file-based media and are not supported for media served using HTTP Live Streaming.

- setRate:time:atHostTime:

Synchronizes the playback rate and time of the current item with an external source.

- prerollAtRate:completionHandler:

Begins loading media data to prime the media pipelines for playback.

- cancelPendingPrerolls

Cancels any pending preroll requests and invokes the corresponding completion handlers if present.

masterClock

The master clock used for item time bases.

Managing Audio Output

muted

A Boolean value that indicates whether the audio output of the player is muted.

volume

The audio playback volume for the player.

audioOutputDeviceUniqueID

Specifies the unique ID of the Core Audio output device used to play audio.

Getting Player Properties

status

A status that indicates whether the player can be used for playback.

AVPlayerStatus

The statuses that indicate whether a player can successfully play items.

error

The error that caused the failure.

currentItem

The player’s current player item.

outputObscuredDueToInsufficientExternalProtection

A Boolean value that indicates whether output is being obscured because of insufficient external protection.

Managing AirPlay

airPlayVideoActive

Indicates whether the player is currently playing video through AirPlay.

Deprecated
allowsAirPlayVideo

Indicates whether the player allows AirPlay video playback.

Deprecated
usesAirPlayVideoWhileAirPlayScreenIsActive

Indicates whether the player should automatically switch to AirPlay Video while AirPlay Screen is active in order to play video content, switching back to AirPlay Screen as soon as playback is done.

Deprecated

Managing Closed Caption Display

closedCaptionDisplayEnabled

A Boolean value that indicates whether the player uses closed captioning.

Deprecated

Determining HDR Playback

availableHDRModes

The HDR modes that are available for playback.

AVPlayerHDRMode

A bitfield type that specifies an HDR mode.

Setting The GPU

preferredVideoDecoderGPURegistryID

The registry identifier for the GPU used for video decoding.

Type Properties

Relationships

Inherits From

See Also

Media Playback

AVQueuePlayer

A player used to play a number of items in sequence.

AVPlayerLayer

An object that manages a player's visual output.

AVPlayerItem

An object used to model the timing and presentation state of an asset played by the player.

AVPlayerItemMetadataCollector

An object used to capture the date range metadata defined for an HTTP Live Streaming asset.

AVPlayerItemTrack

An object used to modify the presentation state of an asset track being presented by a player.

AVSynchronizedLayer

An object used to synchronize with a specific player item.

AVPlayerMediaSelectionCriteria

An object that specifies the preferred languages and media characteristics for a player.

AVSampleBufferAudioRenderer

An object used to decompress audio and play compressed or uncompressed audio.

AVSampleBufferDisplayLayer

An object that displays compressed or uncompressed video frames.

AVSampleBufferRenderSynchronizer

An object used to synchronize multiple queued sample buffers to a single timeline.

AVRouteDetector

An object that detects the presences of media playback routes.