<!--
{
  "availability" : [
    "iOS: 4.0.0 -",
    "iPadOS: 4.0.0 -",
    "macCatalyst: 13.1.0 -",
    "macOS: 10.7.0 -",
    "tvOS: 9.0.0 -",
    "visionOS: 1.0.0 -",
    "watchOS: 1.0.0 -"
  ],
  "documentType" : "symbol",
  "framework" : "AVFoundation",
  "identifier" : "/documentation/AVFoundation/AVPlayer",
  "metadataVersion" : "0.1.0",
  "role" : "Class",
  "symbol" : {
    "kind" : "Class",
    "modules" : [
      "AVFoundation"
    ],
    "preciseIdentifier" : "c:objc(cs)AVPlayer"
  },
  "title" : "AVPlayer"
}
-->

# 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 <doc://com.apple.documentation/documentation/AVKit/AVPlayerViewController> class in iOS and tvOS, or the <doc://com.apple.documentation/documentation/AVKit/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`](/documentation/AVFoundation/AVPlayerLayer). You can set this layer a view’s backing layer or add it directly to the layer hierarchy. Unlike <doc://com.apple.documentation/documentation/AVKit/AVPlayerView> and <doc://com.apple.documentation/documentation/AVKit/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`](/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

[`playerWithURL:`](/documentation/AVFoundation/AVPlayer/playerWithURL:)

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

[`init(url:)`](/documentation/AVFoundation/AVPlayer/init(url:)-87cxx)

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

[`playerWithPlayerItem:`](/documentation/AVFoundation/AVPlayer/playerWithPlayerItem:)

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

[`init(playerItem:)`](/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

[`currentItem`](/documentation/AVFoundation/AVPlayer/currentItem)

The item for which the player is currently controlling playback.

[`replaceCurrentItem(with:)`](/documentation/AVFoundation/AVPlayer/replaceCurrentItem(with:))

Replaces the current item with a new item.

### Determining player readiness

[`status`](/documentation/AVFoundation/AVPlayer/status-swift.property)

A value that indicates the readiness of a player object for playback.

[`AVPlayer.Status`](/documentation/AVFoundation/AVPlayer/Status-swift.enum)

Status values that indicate whether a player can successfully play media.

[`error`](/documentation/AVFoundation/AVPlayer/error)

An error that caused a failure.

### Controlling playback

[`defaultRate`](/documentation/AVFoundation/AVPlayer/defaultRate)

A default rate at which to begin playback.

[`play()`](/documentation/AVFoundation/AVPlayer/play())

Begins playback of the current item.

[`pause()`](/documentation/AVFoundation/AVPlayer/pause())

Pauses playback of the current item.

[`rate`](/documentation/AVFoundation/AVPlayer/rate)

The current playback rate.

[`rateDidChangeNotification`](/documentation/AVFoundation/AVPlayer/rateDidChangeNotification)

A notification that a player posts when its rate changes.

[`playheadReachedLiveEdge`](/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.

[`reversePlaybackReachedStartOfSeekableRange`](/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

[`currentTime()`](/documentation/AVFoundation/AVPlayer/currentTime())

Returns the current time of the current player item.

[`addPeriodicTimeObserver(forInterval:queue:using:)`](/documentation/AVFoundation/AVPlayer/addPeriodicTimeObserver(forInterval:queue:using:))

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

[`addBoundaryTimeObserver(forTimes:queue:using:)`](/documentation/AVFoundation/AVPlayer/addBoundaryTimeObserver(forTimes:queue:using:))

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

[`removeTimeObserver(_:)`](/documentation/AVFoundation/AVPlayer/removeTimeObserver(_:))

Cancels a previously registered periodic or boundary time observer.

### Seeking through media

[`seek(to:)`](/documentation/AVFoundation/AVPlayer/seek(to:)-87h2r)

Requests that the player seek to a specified time.

[`seek(to:completionHandler:)`](/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.

[`seek(to:toleranceBefore:toleranceAfter:)`](/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.

[`seek(to:toleranceBefore:toleranceAfter:completionHandler:)`](/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.

[`seek(to:)`](/documentation/AVFoundation/AVPlayer/seek(to:)-9h9qr)

Requests that the player seek to a specified date.

[`seek(to:completionHandler:)`](/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

[`automaticallyWaitsToMinimizeStalling`](/documentation/AVFoundation/AVPlayer/automaticallyWaitsToMinimizeStalling)

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

[`reasonForWaitingToPlay`](/documentation/AVFoundation/AVPlayer/reasonForWaitingToPlay)

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

[`AVPlayer.WaitingReason`](/documentation/AVFoundation/AVPlayer/WaitingReason)

The reasons a player is waiting to begin or resume playback.

[`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.

[`AVPlayer.TimeControlStatus`](/documentation/AVFoundation/AVPlayer/TimeControlStatus-swift.enum)

Constants that indicate the state of playback control.

[`playImmediately(atRate:)`](/documentation/AVFoundation/AVPlayer/playImmediately(atRate:))

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

### Responding when playback ends

[`actionAtItemEnd`](/documentation/AVFoundation/AVPlayer/actionAtItemEnd-swift.property)

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

[`AVPlayer.ActionAtItemEnd`](/documentation/AVFoundation/AVPlayer/ActionAtItemEnd-swift.enum)

The actions a player can take when it finishes playing.

### Configuring media selection criteria

[`appliesMediaSelectionCriteriaAutomatically`](/documentation/AVFoundation/AVPlayer/appliesMediaSelectionCriteriaAutomatically)

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

[`mediaSelectionCriteria(forMediaCharacteristic:)`](/documentation/AVFoundation/AVPlayer/mediaSelectionCriteria(forMediaCharacteristic:))

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

[`setMediaSelectionCriteria(_:forMediaCharacteristic:)`](/documentation/AVFoundation/AVPlayer/setMediaSelectionCriteria(_:forMediaCharacteristic:))

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

### Accessing player output

[`videoOutput`](/documentation/AVFoundation/AVPlayer/videoOutput)

The video output for this player.

### Configuring audio behavior

[`volume`](/documentation/AVFoundation/AVPlayer/volume)

The audio playback volume for the player.

[`isMuted`](/documentation/AVFoundation/AVPlayer/isMuted)

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

[`allowedAudioSpatializationFormats`](/documentation/AVFoundation/AVPlayerItem/allowedAudioSpatializationFormats)

The source audio channel layouts the player item supports for spatialization.

[`isAudioSpatializationAllowed`](/documentation/AVFoundation/AVPlayerItem/isAudioSpatializationAllowed)

A Boolean value that indicates whether the player item allows spatialized audio playback.

[`audioOutputSuppressedDueToNonMixableAudioRoute`](/documentation/AVFoundation/AVPlayer/audioOutputSuppressedDueToNonMixableAudioRoute)

Whether the player’s audio output is suppressed due to being on a non-mixable audio route.

[`intendedSpatialAudioExperience`](/documentation/AVFoundation/AVPlayer/intendedSpatialAudioExperience-1bd87)

The player’s intended Spatial Audio experience.             

[`intendedSpatialAudioExperience`](/documentation/AVFoundation/AVPlayer/intendedSpatialAudioExperience-3uy8g)

The AVPlayer’s intended spatial audio experience.             

### Configuring background playback

[`audiovisualBackgroundPlaybackPolicy`](/documentation/AVFoundation/AVPlayer/audiovisualBackgroundPlaybackPolicy)

A policy that determines how playback of audiovisual media continues when the app transitions to the background.

[`AVPlayerAudiovisualBackgroundPlaybackPolicy`](/documentation/AVFoundation/AVPlayerAudiovisualBackgroundPlaybackPolicy)

Policies that describe playback behavior when an app transitions to the background while playing video.

### Managing external playback

[`allowsExternalPlayback`](/documentation/AVFoundation/AVPlayer/allowsExternalPlayback)

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

[`isExternalPlaybackActive`](/documentation/AVFoundation/AVPlayer/isExternalPlaybackActive)

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

[`usesExternalPlaybackWhileExternalScreenIsActive`](/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.

[`externalPlaybackVideoGravity`](/documentation/AVFoundation/AVPlayer/externalPlaybackVideoGravity)

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

### Determining HDR playback eligibility

[`eligibleForHDRPlayback`](/documentation/AVFoundation/AVPlayer/eligibleForHDRPlayback)

A Boolean value that indicates whether the current device can present content to an HDR display.

[`availableHDRModes`](/documentation/AVFoundation/AVPlayer/availableHDRModes)

The HDR modes that are available for playback.

[`AVPlayer.HDRMode`](/documentation/AVFoundation/AVPlayer/HDRMode)

A bitfield type that specifies an HDR mode.

[`eligibleForHDRPlaybackDidChangeNotification`](/documentation/AVFoundation/AVPlayer/eligibleForHDRPlaybackDidChangeNotification)

A notification that’s posted whenever HDR playback eligibility changes.

[`AVPlayerAvailableHDRModesDidChangeNotification`](/documentation/AVFoundation/AVPlayerAvailableHDRModesDidChangeNotification)

A notification that fires whenever availableHDRModes changes.

### Coordinating playback

[`playbackCoordinator`](/documentation/AVFoundation/AVPlayer/playbackCoordinator)

The playback coordinator for the player.

### Synchronizing multiple players

[`setRate(_:time:atHostTime:)`](/documentation/AVFoundation/AVPlayer/setRate(_:time:atHostTime:))

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

[`preroll(atRate:completionHandler:)`](/documentation/AVFoundation/AVPlayer/preroll(atRate:completionHandler:))

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

[`cancelPendingPrerolls()`](/documentation/AVFoundation/AVPlayer/cancelPendingPrerolls())

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

[`sourceClock`](/documentation/AVFoundation/AVPlayer/sourceClock)

A clock the player uses for item time bases.

[`masterClock`](/documentation/AVFoundation/AVPlayer/masterClock)

The host clock for item time bases.

### Preventing sleep and backgrounding

[`preventsDisplaySleepDuringVideoPlayback`](/documentation/AVFoundation/AVPlayer/preventsDisplaySleepDuringVideoPlayback)

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

[`preventsAutomaticBackgroundingDuringVideoPlayback`](/documentation/AVFoundation/AVPlayer/preventsAutomaticBackgroundingDuringVideoPlayback)

A Boolean value that indicates whether video playback prevents the system from automatically backgrounding the app.

### Determining content protections

[`isOutputObscuredDueToInsufficientExternalProtection`](/documentation/AVFoundation/AVPlayer/isOutputObscuredDueToInsufficientExternalProtection)

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

### Configuring audio and video devices

[`audioOutputDeviceUniqueID`](/documentation/AVFoundation/AVPlayer/audioOutputDeviceUniqueID)

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

[`preferredVideoDecoderGPURegistryID`](/documentation/AVFoundation/AVPlayer/preferredVideoDecoderGPURegistryID)

The registry identifier for the GPU used for video decoding.

### Configuring the network resource priority

[`networkResourcePriority`](/documentation/AVFoundation/AVPlayer/networkResourcePriority-swift.property)

Indicates the priority of this player for network bandwidth resource distribution.

[`AVPlayer.NetworkResourcePriority`](/documentation/AVFoundation/AVPlayer/NetworkResourcePriority-swift.enum)

This defines the network resource priority for a player.

### Configuring observation

[`isObservationEnabled`](/documentation/AVFoundation/AVPlayer/isObservationEnabled)

AVPlayer and other AVFoundation types can optionally be observed using Swift Observation.

### Configuring AirPlay behavior

[`allowsAirPlayVideo`](/documentation/AVFoundation/AVPlayer/allowsAirPlayVideo)

A Boolean value that indicates whether the player allows AirPlay video playback.

[`isAirPlayVideoActive`](/documentation/AVFoundation/AVPlayer/isAirPlayVideoActive)

A Boolean value that indicates whether the player is playing video through AirPlay.

[`usesAirPlayVideoWhileAirPlayScreenIsActive`](/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

[`isClosedCaptionDisplayEnabled`](/documentation/AVFoundation/AVPlayer/isClosedCaptionDisplayEnabled)

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


---

Copyright &copy; 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)