AVPlayer

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

Declaration

@MainActor class AVPlayer

Mentioned in

Overview

A player is a controller object that manages the playback and timing of a media asset. Use an instance of 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.

Use a player object to play a single media asset. You can reuse the player instance to play additional media assets using its replaceCurrentItem(with:) method, but it manages the playback of only a single media asset at a time. The framework also provides a subclass called AVQueuePlayer that you can use to manage the playback of a queue of media assets.

You use an AVPlayer to play media assets, which AVFoundation represents using the AVAsset class. AVAsset only models the static aspects of the media, such as its duration or creation date, and on its own, isn’t suitable for playback with an AVPlayer. To play an asset, you 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.
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:
addPeriodicTimeObserver(forInterval:queue:using:)
addBoundaryTimeObserver(forTimes:queue:using:)

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’re unable to present an asset’s video onscreen. There are two primary approaches you 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. You can set this layer a view’s backing layer or add it directly to the layer hierarchy. Unlike AVPlayerView and AVPlayerViewController, a player layer doesn’t present any playback controls—it only 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 a synchronized layer pass along player timing to 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.

Topics

Creating a player

Managing the player item

Determining player readiness

Controlling playback

Observing playback time

Seeking through media

Configuring waiting behavior

Responding when playback ends

Configuring media selection criteria

Accessing player output

videoOutput

Configuring audio behavior

Configuring background playback

Managing external playback

Determining HDR playback eligibility

Coordinating playback

playbackCoordinator

Synchronizing multiple players

Preventing sleep and backgrounding

Determining content protections

isOutputObscuredDueToInsufficientExternalProtection

Configuring audio and video devices

Configuring the network resource priority

Configuring observation

isObservationEnabled

Configuring AirPlay behavior

Displaying closed captions

isClosedCaptionDisplayEnabled

Initializers

Instance Properties

allowsCaptureOfClearKeyVideo