# AVPlayer An object that provides the interface to control the player’s transport behavior. ``` @MainActor class AVPlayer ``` ## Overview A player is a controller object that manages the playback and timing of a media asset. Use an instance of [`AVPlayer`](/documentation/AVFoundation/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:)`](/documentation/AVFoundation/AVPlayer/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`](/documentation/AVFoundation/AVQueuePlayer) that you can use to manage the playback of a queue of media assets. You use an [`AVPlayer`](/documentation/AVFoundation/AVPlayer) to play media assets, which AVFoundation represents using the [`AVAsset`](/documentation/AVFoundation/AVAsset) class. [`AVAsset`](/documentation/AVFoundation/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`](/documentation/AVFoundation/AVPlayer). To play an asset, you create an instance of its *dynamic* counterpart found in [`AVPlayerItem`](/documentation/AVFoundation/AVPlayerItem). This object models the timing and presentation state of an asset played by an instance of [`AVPlayer`](/documentation/AVFoundation/AVPlayer). See the [`AVPlayerItem`](/documentation/AVFoundation/AVPlayerItem) reference for more details. [`AVPlayer`](/documentation/AVFoundation/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`](/documentation/AVFoundation/AVPlayer/currentItem) or its playback [`rate`](/documentation/AVFoundation/AVPlayer/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`](/documentation/AVFoundation/AVPlayer) provides two methods to observe time changes: - [`addPeriodicTimeObserver(forInterval:queue:using:)`](/documentation/AVFoundation/AVPlayer/addPeriodicTimeObserver(forInterval:queue:using:)) - [`addBoundaryTimeObserver(forTimes:queue:using:)`](/documentation/AVFoundation/AVPlayer/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`](/documentation/AVFoundation/AVPlayer) and [`AVPlayerItem`](/documentation/AVFoundation/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 class in iOS and tvOS, or the 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`](/documentation/AVFoundation/AVPlayerLayer). You can set this layer a view’s backing layer or add it directly to the layer hierarchy. Unlike and , 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`](/documentation/AVFoundation/AVPlayerLayer), you can also present animated content synchronized with the player’s timing using [`AVSynchronizedLayer`](/documentation/AVFoundation/AVSynchronizedLayer). Use a synchronized layer pass along player timing to its layer subtree. You can use [`AVSynchronizedLayer`](/documentation/AVFoundation/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`](/documentation/AVFoundation/AVPlayerItem). ## Topics ### Creating a player [`+ (instancetype) playerWithURL:(NSURL *) URL;`](/documentation/AVFoundation/AVPlayer/playerWithURL:) Returns a new player to play a single audiovisual resource referenced by a given URL. [`init(url: URL)`](/documentation/AVFoundation/AVPlayer/init(url:)-87cxx) Creates a new player to play a single audiovisual resource referenced by a given URL. [`+ (instancetype) playerWithPlayerItem:(AVPlayerItem *) item;`](/documentation/AVFoundation/AVPlayer/playerWithPlayerItem:) Returns a new player initialized to play the specified player item. [`init(playerItem: AVPlayerItem?)`](/documentation/AVFoundation/AVPlayer/init(playerItem:)) Creates a new player to play the specified player item. [`init()`](/documentation/AVFoundation/AVPlayer/init()) Creates a player object. ### Managing the player item [`var currentItem: AVPlayerItem?`](/documentation/AVFoundation/AVPlayer/currentItem) The item for which the player is currently controlling playback. [`func replaceCurrentItem(with: AVPlayerItem?)`](/documentation/AVFoundation/AVPlayer/replaceCurrentItem(with:)) Replaces the current item with a new item. ### Determining player readiness [`var status: AVPlayer.Status`](/documentation/AVFoundation/AVPlayer/status-swift.property) A value that indicates the readiness of a player object for playback. [`enum Status`](/documentation/AVFoundation/AVPlayer/Status-swift.enum) Status values that indicate whether a player can successfully play media. [`var error: (any Error)?`](/documentation/AVFoundation/AVPlayer/error) An error that caused a failure. ### Controlling playback [`var defaultRate: Float`](/documentation/AVFoundation/AVPlayer/defaultRate) A default rate at which to begin playback. [`func play()`](/documentation/AVFoundation/AVPlayer/play()) Begins playback of the current item. [`func pause()`](/documentation/AVFoundation/AVPlayer/pause()) Pauses playback of the current item. [`var rate: Float`](/documentation/AVFoundation/AVPlayer/rate) The current playback rate. [`class let rateDidChangeNotification: NSNotification.Name`](/documentation/AVFoundation/AVPlayer/rateDidChangeNotification) A notification that a player posts when its rate changes. [`static let playheadReachedLiveEdge: AVPlayer.RateDidChangeReason`](/documentation/AVFoundation/AVPlayer/RateDidChangeReason/playheadReachedLiveEdge) Indicates that the player automatically switched the playback rate from > 1.0 back to 1.0 when the playhead reached the live edge during live streaming. [`static let reversePlaybackReachedStartOfSeekableRange: AVPlayer.RateDidChangeReason`](/documentation/AVFoundation/AVPlayer/RateDidChangeReason/reversePlaybackReachedStartOfSeekableRange) Indicates that the player automatically switched rate to 1.0 when the reverse playback reached start of seekable range. only for live. ### Observing playback time [`func currentTime() -> CMTime`](/documentation/AVFoundation/AVPlayer/currentTime()) Returns the current time of the current player item. [`func addPeriodicTimeObserver(forInterval: CMTime, queue: dispatch_queue_t?, using: (CMTime) -> Void) -> Any`](/documentation/AVFoundation/AVPlayer/addPeriodicTimeObserver(forInterval:queue:using:)) Requests the periodic invocation of a given block during playback to report changing time. [`func addBoundaryTimeObserver(forTimes: [NSValue], queue: dispatch_queue_t?, using: () -> Void) -> Any`](/documentation/AVFoundation/AVPlayer/addBoundaryTimeObserver(forTimes:queue:using:)) Requests the invocation of a block when specified times are traversed during normal playback. [`func removeTimeObserver(Any)`](/documentation/AVFoundation/AVPlayer/removeTimeObserver(_:)) Cancels a previously registered periodic or boundary time observer. ### Seeking through media [`func seek(to: CMTime)`](/documentation/AVFoundation/AVPlayer/seek(to:)-87h2r) Requests that the player seek to a specified time. [`func seek(to: CMTime, completionHandler: (Bool) -> Void)`](/documentation/AVFoundation/AVPlayer/seek(to:completionHandler:)-75bls) Requests that the player seek to a specified time, and to notify you when the seek is complete. [`func seek(to: CMTime, toleranceBefore: CMTime, toleranceAfter: CMTime)`](/documentation/AVFoundation/AVPlayer/seek(to:toleranceBefore:toleranceAfter:)) Requests that the player seek to a specified time with the amount of accuracy specified by the time tolerance values. [`func seek(to: CMTime, toleranceBefore: CMTime, toleranceAfter: CMTime, completionHandler: (Bool) -> Void)`](/documentation/AVFoundation/AVPlayer/seek(to:toleranceBefore:toleranceAfter:completionHandler:)) Requests that the player seek to a specified time with the amount of accuracy specified by the time tolerance values, and to notify you when the seek is complete. [`func seek(to: Date)`](/documentation/AVFoundation/AVPlayer/seek(to:)-9h9qr) Requests that the player seek to a specified date. [`func seek(to: Date, completionHandler: (Bool) -> Void)`](/documentation/AVFoundation/AVPlayer/seek(to:completionHandler:)-wr1l) Requests that the player seek to a specified date, and to notify you when the seek is complete. ### Configuring waiting behavior [`var automaticallyWaitsToMinimizeStalling: Bool`](/documentation/AVFoundation/AVPlayer/automaticallyWaitsToMinimizeStalling) A Boolean value that indicates whether the player should automatically delay playback in order to minimize stalling. [`var reasonForWaitingToPlay: AVPlayer.WaitingReason?`](/documentation/AVFoundation/AVPlayer/reasonForWaitingToPlay) The reason the player is currently waiting for playback to begin or resume. [`struct WaitingReason`](/documentation/AVFoundation/AVPlayer/WaitingReason) The reasons a player is waiting to begin or resume playback. [`var timeControlStatus: AVPlayer.TimeControlStatus`](/documentation/AVFoundation/AVPlayer/timeControlStatus-swift.property) A value that indicates whether playback is in progress, paused indefinitely, or waiting for network conditions to improve. [`enum TimeControlStatus`](/documentation/AVFoundation/AVPlayer/TimeControlStatus-swift.enum) Constants that indicate the state of playback control. [`func playImmediately(atRate: Float)`](/documentation/AVFoundation/AVPlayer/playImmediately(atRate:)) Plays the available media data immediately, at the specified rate. ### Responding when playback ends [`var actionAtItemEnd: AVPlayer.ActionAtItemEnd`](/documentation/AVFoundation/AVPlayer/actionAtItemEnd-swift.property) The action to perform when the current player item has finished playing. [`enum ActionAtItemEnd`](/documentation/AVFoundation/AVPlayer/ActionAtItemEnd-swift.enum) The actions a player can take when it finishes playing. ### Configuring media selection criteria [`var appliesMediaSelectionCriteriaAutomatically: Bool`](/documentation/AVFoundation/AVPlayer/appliesMediaSelectionCriteriaAutomatically) A Boolean value that indicates whether the receiver should apply the current selection criteria automatically to player items. [`func mediaSelectionCriteria(forMediaCharacteristic: AVMediaCharacteristic) -> AVPlayerMediaSelectionCriteria?`](/documentation/AVFoundation/AVPlayer/mediaSelectionCriteria(forMediaCharacteristic:)) Returns the automatic selection criteria for media items with the specified media characteristic. [`func setMediaSelectionCriteria(AVPlayerMediaSelectionCriteria?, forMediaCharacteristic: AVMediaCharacteristic)`](/documentation/AVFoundation/AVPlayer/setMediaSelectionCriteria(_:forMediaCharacteristic:)) Applies automatic selection criteria for media that has the specified media characteristic. ### Accessing player output [`var videoOutput: AVPlayerVideoOutput?`](/documentation/AVFoundation/AVPlayer/videoOutput) The video output for this player. ### Configuring audio behavior [`var volume: Float`](/documentation/AVFoundation/AVPlayer/volume) The audio playback volume for the player. [`var isMuted: Bool`](/documentation/AVFoundation/AVPlayer/isMuted) A Boolean value that indicates whether the audio output of the player is muted. [`var allowedAudioSpatializationFormats: AVAudioSpatializationFormats`](/documentation/AVFoundation/AVPlayerItem/allowedAudioSpatializationFormats) The source audio channel layouts the player item supports for spatialization. [`var isAudioSpatializationAllowed: Bool`](/documentation/AVFoundation/AVPlayerItem/isAudioSpatializationAllowed) A Boolean value that indicates whether the player item allows spatialized audio playback. [`var audioOutputSuppressedDueToNonMixableAudioRoute: Bool`](/documentation/AVFoundation/AVPlayer/audioOutputSuppressedDueToNonMixableAudioRoute) Whether the player’s audio output is suppressed due to being on a non-mixable audio route. [`var intendedSpatialAudioExperience: any SpatialAudioExperience`](/documentation/AVFoundation/AVPlayer/intendedSpatialAudioExperience-1bd87) The player’s intended Spatial Audio experience. [`@property (nonatomic, copy) CASpatialAudioExperience * intendedSpatialAudioExperience;`](/documentation/AVFoundation/AVPlayer/intendedSpatialAudioExperience-3uy8g) The AVPlayer’s intended spatial audio experience. ### Configuring background playback [`var audiovisualBackgroundPlaybackPolicy: AVPlayerAudiovisualBackgroundPlaybackPolicy`](/documentation/AVFoundation/AVPlayer/audiovisualBackgroundPlaybackPolicy) A policy that determines how playback of audiovisual media continues when the app transitions to the background. [`enum AVPlayerAudiovisualBackgroundPlaybackPolicy`](/documentation/AVFoundation/AVPlayerAudiovisualBackgroundPlaybackPolicy) Policies that describe playback behavior when an app transitions to the background while playing video. ### Managing external playback [`var allowsExternalPlayback: Bool`](/documentation/AVFoundation/AVPlayer/allowsExternalPlayback) A Boolean value that indicates whether the player allows switching to external playback mode. [`var isExternalPlaybackActive: Bool`](/documentation/AVFoundation/AVPlayer/isExternalPlaybackActive) A Boolean value that indicates whether the player is currently playing video in external playback mode. [`var usesExternalPlaybackWhileExternalScreenIsActive: Bool`](/documentation/AVFoundation/AVPlayer/usesExternalPlaybackWhileExternalScreenIsActive) A Boolean value that indicates whether the player should automatically switch to external playback mode while the external screen mode is active. [`var externalPlaybackVideoGravity: AVLayerVideoGravity`](/documentation/AVFoundation/AVPlayer/externalPlaybackVideoGravity) The video gravity of the player for external playback mode only. ### Determining HDR playback eligibility [`class var eligibleForHDRPlayback: Bool`](/documentation/AVFoundation/AVPlayer/eligibleForHDRPlayback) A Boolean value that indicates whether the current device can present content to an HDR display. [`class var availableHDRModes: AVPlayer.HDRMode`](/documentation/AVFoundation/AVPlayer/availableHDRModes) The HDR modes that are available for playback. [`struct HDRMode`](/documentation/AVFoundation/AVPlayer/HDRMode) A bitfield type that specifies an HDR mode. [`class let eligibleForHDRPlaybackDidChangeNotification: NSNotification.Name`](/documentation/AVFoundation/AVPlayer/eligibleForHDRPlaybackDidChangeNotification) A notification that’s posted whenever HDR playback eligibility changes. [`extern NSNotificationName const AVPlayerAvailableHDRModesDidChangeNotification;`](/documentation/AVFoundation/AVPlayerAvailableHDRModesDidChangeNotification) A notification that fires whenever availableHDRModes changes. ### Coordinating playback [`var playbackCoordinator: AVPlayerPlaybackCoordinator`](/documentation/AVFoundation/AVPlayer/playbackCoordinator) The playback coordinator for the player. ### Synchronizing multiple players [`func setRate(Float, time: CMTime, atHostTime: CMTime)`](/documentation/AVFoundation/AVPlayer/setRate(_:time:atHostTime:)) Synchronizes the playback rate and time of the current item with an external source. [`func preroll(atRate: Float, completionHandler: ((Bool) -> Void)?)`](/documentation/AVFoundation/AVPlayer/preroll(atRate:completionHandler:)) Begins loading media data to prime the media pipelines for playback. [`func cancelPendingPrerolls()`](/documentation/AVFoundation/AVPlayer/cancelPendingPrerolls()) Cancels any pending preroll requests and invokes the corresponding completion handlers, if present. [`var sourceClock: CMClock?`](/documentation/AVFoundation/AVPlayer/sourceClock) A clock the player uses for item time bases. [`var masterClock: CMClock?`](/documentation/AVFoundation/AVPlayer/masterClock) The host clock for item time bases. ### Preventing sleep and backgrounding [`var preventsDisplaySleepDuringVideoPlayback: Bool`](/documentation/AVFoundation/AVPlayer/preventsDisplaySleepDuringVideoPlayback) A Boolean value that indicates whether video playback prevents display and device sleep. [`var preventsAutomaticBackgroundingDuringVideoPlayback: Bool`](/documentation/AVFoundation/AVPlayer/preventsAutomaticBackgroundingDuringVideoPlayback) A Boolean value that indicates whether video playback prevents the system from automatically backgrounding the app. ### Determining content protections [`var isOutputObscuredDueToInsufficientExternalProtection: Bool`](/documentation/AVFoundation/AVPlayer/isOutputObscuredDueToInsufficientExternalProtection) A Boolean value that indicates whether output is being obscured because of insufficient external protection. ### Configuring audio and video devices [`var audioOutputDeviceUniqueID: String?`](/documentation/AVFoundation/AVPlayer/audioOutputDeviceUniqueID) Specifies the unique ID of the Core Audio output device used to play audio. [`var preferredVideoDecoderGPURegistryID: UInt64`](/documentation/AVFoundation/AVPlayer/preferredVideoDecoderGPURegistryID) The registry identifier for the GPU used for video decoding. ### Configuring the network resource priority [`var networkResourcePriority: AVPlayer.NetworkResourcePriority`](/documentation/AVFoundation/AVPlayer/networkResourcePriority-swift.property) Indicates the priority of this player for network bandwidth resource distribution. [`enum NetworkResourcePriority`](/documentation/AVFoundation/AVPlayer/NetworkResourcePriority-swift.enum) This defines the network resource priority for a player. ### Configuring observation [`class var isObservationEnabled: Bool`](/documentation/AVFoundation/AVPlayer/isObservationEnabled) AVPlayer and other AVFoundation types can optionally be observed using Swift Observation. ### Configuring AirPlay behavior [`var allowsAirPlayVideo: Bool`](/documentation/AVFoundation/AVPlayer/allowsAirPlayVideo) A Boolean value that indicates whether the player allows AirPlay video playback. [`var isAirPlayVideoActive: Bool`](/documentation/AVFoundation/AVPlayer/isAirPlayVideoActive) A Boolean value that indicates whether the player is playing video through AirPlay. [`var usesAirPlayVideoWhileAirPlayScreenIsActive: Bool`](/documentation/AVFoundation/AVPlayer/usesAirPlayVideoWhileAirPlayScreenIsActive) A Boolean value that indicates whether the player automatically switches to AirPlay Video while AirPlay Screen is active. ### Displaying closed captions [`var isClosedCaptionDisplayEnabled: Bool`](/documentation/AVFoundation/AVPlayer/isClosedCaptionDisplayEnabled) A Boolean value that indicates whether the player uses closed captioning. ### Initializers [`convenience init(URL: URL)`](/documentation/AVFoundation/AVPlayer/init(URL:)-8aqw0) [`init(URL: URL)`](/documentation/AVFoundation/AVPlayer/init(URL:)-9cqj1) ### Instance Properties [`var allowsCaptureOfClearKeyVideo: Bool`](/documentation/AVFoundation/AVPlayer/allowsCaptureOfClearKeyVideo) Indicates whether the video output of ClearKey Encrypted Video can be captured [`var disconnectedFromSystemAudio: Bool`](/documentation/AVFoundation/AVPlayer/disconnectedFromSystemAudio) Indicates whether the player is disconnected from system audio. ### Instance Methods [`func setDisconnectedFromSystemAudio(Bool, completionHandler: (() -> Void)?)`](/documentation/AVFoundation/AVPlayer/setDisconnectedFromSystemAudio(_:completionHandler:)) Changes whether the player is disconnected from system audio. This method allows you to dynamically change the player’s system audio connection. The operation is asynchronous. Each call to this method will invoke its own completion handler when the operation completes. When changing from `false` to `true`, you should typically call this method first, then deactivate the `AVAudioSession` to allow other audio to resume. ## Relationships ### Conforms To [`Sendable`](/documentation/Swift/Sendable) [`CustomDebugStringConvertible`](/documentation/Swift/CustomDebugStringConvertible) [`NSObjectProtocol`](/documentation/ObjectiveC/NSObjectProtocol) [`Observable`](/documentation/Observation/Observable) [`Copyable`](/documentation/Swift/Copyable) [`AVRoutingPlaybackParticipant`](/documentation/AVRouting/AVRoutingPlaybackParticipant) [`Escapable`](/documentation/Swift/Escapable) [`Hashable`](/documentation/Swift/Hashable) [`CVarArg`](/documentation/Swift/CVarArg) [`Equatable`](/documentation/Swift/Equatable) [`CustomStringConvertible`](/documentation/Swift/CustomStringConvertible) ### Inherited By [`AVQueuePlayer`](/documentation/AVFoundation/AVQueuePlayer) ### Inherits From [`NSObject-swift.class`](/documentation/ObjectiveC/NSObject-swift.class) --- Copyright © 2026 Apple Inc. All rights reserved. | [Terms of Use](https://www.apple.com/legal/internet-services/terms/site.html) | [Privacy Policy](https://www.apple.com/privacy/privacy-policy)