<!--
{
  "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/AVPlayerItem",
  "metadataVersion" : "0.1.0",
  "role" : "Class",
  "symbol" : {
    "kind" : "Class",
    "modules" : [
      "AVFoundation"
    ],
    "preciseIdentifier" : "c:objc(cs)AVPlayerItem"
  },
  "title" : "AVPlayerItem"
}
-->

# AVPlayerItem

An object that models the timing and presentation state of an asset during playback.

```
@MainActor class AVPlayerItem
```

## Overview

A player item stores a reference to an [`AVAsset`](/documentation/AVFoundation/AVAsset) object, which represents the media to play. If you require inspecting an asset before you enqueue it for playback, call its [`load(_:isolation:)`](/documentation/AVFoundation/AVAsynchronousKeyValueLoading/load(_:isolation:)) method to retrieve the values of one or more properties. Alternatively, you can tell the player item to automatically load the required properties by passing them to its [`init(asset:automaticallyLoadedAssetKeys:)`](/documentation/AVFoundation/AVPlayerItem/init(asset:automaticallyLoadedAssetKeys:)-5czjh) initializer. When the player item is ready to play, the asset properties you request are ready to use.

## Topics

### Creating a player item

[`playerItemWithURL:`](/documentation/AVFoundation/AVPlayerItem/playerItemWithURL:)

Returns a new player item with a specified URL.

[`init(url:)`](/documentation/AVFoundation/AVPlayerItem/init(url:)-1xrtk)

Creates a player item with a specified URL.

[`playerItemWithAsset:`](/documentation/AVFoundation/AVPlayerItem/playerItemWithAsset:)

Returns a new player item for a specified asset.

[`init(asset:)`](/documentation/AVFoundation/AVPlayerItem/init(asset:)-87rjl)

Creates a player item for a specified asset.

[`init(asset:)`](/documentation/AVFoundation/AVPlayerItem/init(asset:)-1nme9)

[`init(asset:automaticallyLoadedAssetKeys:)`](/documentation/AVFoundation/AVPlayerItem/init(asset:automaticallyLoadedAssetKeys:)-5czjh)

Creates a player item for the asset, and automatically loads values for the specified properties.

[`init(asset:automaticallyLoadedAssetKeys:)`](/documentation/AVFoundation/AVPlayerItem/init(asset:automaticallyLoadedAssetKeys:)-85hal)

[`playerItemWithAsset:automaticallyLoadedAssetKeys:`](/documentation/AVFoundation/AVPlayerItem/playerItemWithAsset:automaticallyLoadedAssetKeys:)

Creates a player item with the specified asset and the asset keys to automatically load.

[`init(asset:automaticallyLoadedAssetKeys:)`](/documentation/AVFoundation/AVPlayerItem/init(asset:automaticallyLoadedAssetKeys:)-8x4)

Creates a player item with the specified asset and the asset keys to automatically load.

### Accessing tracks

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

An array of player item track objects.

### Accessing metadata

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

An array of additional metadata for the player item to supplement or replace an asset’s embedded metadata.

### Determining readiness

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

The status of the player item.

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

The statuses for a player item.

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

The error that caused the player item to fail.

### Determining playback capabilities

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

A Boolean value that indicates whether the item can play in reverse.

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

A Boolean value that indicates whether the item can be fast forwarded.

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

A Boolean value that indicates whether the item can be quickly reversed.

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

A Boolean value that indicates whether the item can play slower than normal.

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

A Boolean value that indicates whether the item can play slowly backward.

### Setting playback boundaries

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

The time at which forward playback ends.

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

The time at which reverse playback ends.

### Stepping through media

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

A Boolean value that indicates whether the item supports stepping forward.

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

A Boolean value that indicates whether the item supports stepping backward.

[`step(byCount:)`](/documentation/AVFoundation/AVPlayerItem/step(byCount:))

Moves the player item’s current time forward or backward by a specified number of steps.

### Seeking through media

[`seek(to:completionHandler:)`](/documentation/AVFoundation/AVPlayerItem/seek(to:completionHandler:)-91gnw)

Sets the current playback time to the specified time.

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

[`seek(to:completionHandler:)`](/documentation/AVFoundation/AVPlayerItem/seek(to:completionHandler:)-1dibq)

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

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

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

### Selecting media options

[`select(_:for:)`](/documentation/AVFoundation/AVPlayerItem/select(_:for:))

When the associated AVPlayer’s appliesMediaSelectionCriteriaAutomatically property is set to YES, configures the player item to prefer a particular presentation setting, replacing any previous preference for settings of the same media presentation selector.

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

Indicates the AVCustomMediaSelectionSchemes of AVMediaSelectionGroups of the receiver’s asset with which an associated UI implementation should configure its interface for media selection.

[`effectiveMediaPresentationSettings(for:)`](/documentation/AVFoundation/AVPlayerItem/effectiveMediaPresentationSettings(for:))

Indicates the media presentation settings with media characteristics that are possessed by the currently selected AVMediaSelectionOption in the specified AVMediaSelectionGroup.

[`selectMediaPresentationLanguage(_:for:)`](/documentation/AVFoundation/AVPlayerItem/selectMediaPresentationLanguage(_:for:))

When the associated AVPlayer’s appliesMediaSelectionCriteriaAutomatically property is set to YES, configures the player item to prefer a particular language, replacing any previous preference for available languages of the specified group’s custom media selection scheme.

[`selectedMediaPresentationLanguage(for:)`](/documentation/AVFoundation/AVPlayerItem/selectedMediaPresentationLanguage(for:))

Returns the selected media presentation language for the specified media selection group, if any language has previously been selected via use of -selectMediaPresentationLanguages:forMediaSelectionGroup:.

[`selectedMediaPresentationSettings(for:)`](/documentation/AVFoundation/AVPlayerItem/selectedMediaPresentationSettings(for:))

Indicates the media presentation settings that have most recently been selected for each AVMediaPresentationSelector of the AVCustomMediaSelectionScheme of the specified AVMediaSelectionGroup.

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

The current media selections for each of the receiver’s media selection groups.

[`select(_:in:)`](/documentation/AVFoundation/AVPlayerItem/select(_:in:))

Selects a media option in a given media selection group and deselects all other options in that group.

[`selectMediaOptionAutomatically(in:)`](/documentation/AVFoundation/AVPlayerItem/selectMediaOptionAutomatically(in:))

Selects the media option in the specified media selection group that best matches the receiver’s automatic selection criteria.

### Setting variant behavior

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

The preferences the player item uses when selecting variant playlists.

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

Defines the preferences the player item uses when selecting variant playlists.

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

A Boolean value that indicates whether playback starts with the first eligible variant that appears in the stream’s main playlist.

### Configuring interstitial events

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

An integrated timeline that represents the player item timing including its scheduled interstitial events.

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

A Boolean value that indicates whether the player item automatically plays interstitial events according to server-side directives.

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

A Boolean value that indicates whether the player translates interstitial events to interstitial time ranges.

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

An array of time ranges that identify interstitial content.

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

The template player item that initializes this instance.

### Accessing timing information

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

Returns the current time of the item.

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

Returns the current time of the item as a date.

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

The duration of the item.

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

The timebase information for the item.

### Determining available time ranges

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

An array of time ranges indicating media data that is readily available.

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

An array of time ranges within which it is possible to seek.

### Determining buffering status

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

A Boolean value that indicates whether the item will likely play through without stalling.

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

A Boolean value that indicates whether the internal media buffer is full and that further I/O is suspended.

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

A Boolean value that indicates whether playback has consumed all buffered media and that playback will stall or end.

### Configuring expensive network behavior

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

A limit of network bandwidth consumption by the item when connecting over expensive networks.

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

An upper limit on the resolution of video to download when connecting over expensive networks.

### Accessing text style rules

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

An array of text style rules that specify the formatting and presentation of Web Video Text Tracks (WebVTT) subtitles.

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

An object that represents the text styling rules to apply to a media item’s textual content.

### Accessing logging information

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

Returns an object that represents a snapshot of the network access log.

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

An object used to retrieve the access log associated with a player item.

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

A single entry in a player item’s access log.

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

Returns an object that represents a snapshot of the error log.

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

The error log associated with a player item.

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

A single item in a player item’s error log.

### Observing notifications

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

A notification the system posts when a player item plays to its end time.

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

A notification that the system posts when a player item fails to play to its end time.

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

A notification the system posts when a player item’s time changes discontinuously.

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

A notification the system posts when a player item media doesn’t arrive in time to continue playback.

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

A notification the player item posts when its media selection changes.

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

A notification the player item posts when its offset from the live time changes.

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

A notification the system posts when a player item adds a new entry to its access log.

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

A notification the system posts when a player item adds a new entry to its error log.

### Managing time offsets

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

A Boolean value that indicates whether the player preserves its time offset from the live time after a buffering operation.

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

A recommended time offset from the live time based on observed network conditions.

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

A time value that indicates the offset from the live time to start playback, or resume playback after a seek to positive infinity.

### Configuring presentation

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

The size at which the visual portion of the item is presented by the player.

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

The desired maximum resolution of a video that is to be downloaded.

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

The video aperture mode to apply during playback.

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

A value that describes how a video is scaled or cropped.

### Accessing Now Playing information

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

The current now playing information for the player item.

### Configuring HDR settings

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

A Boolean value that indicates whether the player item applies per-frame HDR display metadata during playback.

### Configuring video compositing

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

The video composition settings to be applied during playback.

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

The custom video compositor.

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

A Boolean value that indicates whether the item’s timing follows the displayed video frame when seeking with a video composition.

### Configuring audio

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

The audio mix parameters to be applied during playback.

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

The processing algorithm used to manage audio pitch for scaled audio edits.

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

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

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

A structure that defines the spatialization formats that a player item supports.

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

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

### Managing player item outputs

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

An array of outputs associated with the player item.

[`add(_:)`](/documentation/AVFoundation/AVPlayerItem/add(_:)-16ctk)

Adds the specified player item output object to the receiver.

[`remove(_:)`](/documentation/AVFoundation/AVPlayerItem/remove(_:)-46b1r)

Removes the specified player item output object from the receiver.

### Managing player item data collectors

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

The collection of associated media data collectors.

[`add(_:)`](/documentation/AVFoundation/AVPlayerItem/add(_:)-9l3to)

Adds the specified media data collector to the player item’s collection of media collectors.

[`remove(_:)`](/documentation/AVFoundation/AVPlayerItem/remove(_:)-29iuz)

Removes the specified media data collector from the player item’s collection of media collectors.

### Configuring network behavior

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

The desired limit, in bits per second, of network bandwidth consumption for this item.

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

The duration the player should buffer media from the network ahead of the playhead to guard against playback disruption.

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

A Boolean value that indicates whether the player item can use network resources to keep the playback state up to date while paused.

### Configuring player items for AVKit

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

The time marker groups that provide ways to navigate the player item’s content.

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

The item proposed to follow the current content.

### Requesting playback authorization in tvOS

[`requestPlaybackRestrictionsAuthorization(_:)`](/documentation/AVFoundation/AVPlayerItem/requestPlaybackRestrictionsAuthorization(_:))

Determines whether this item is subject to parental restrictions, and, if so, prompts the user to enter the restrictions passcode.

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

Cancels a pending authorization request and dismisses the passcode entry, if displayed.

### Managing playback authorization in macOS

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

A Boolean value that indicates whether the content has been authorized by the user.

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

A Boolean value that indicates whether authorization is required to play the content.

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

A Boolean value that indicates whether the application can be used to play the content.

[`requestContentAuthorizationAsynchronously(withTimeoutInterval:completionHandler:)`](/documentation/AVFoundation/AVPlayerItem/requestContentAuthorizationAsynchronously(withTimeoutInterval:completionHandler:))

Presents the user the opportunity to authorize the content for playback.

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

The status of the most recent content authorization request.

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

A value representing the status of a content authorization request.

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

Cancels the currently outstanding content authorization request.

### Accessing initialization parameters

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

The asset provided during initialization.

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

The array of asset keys to be automatically loaded before the player item is ready to play.

### Copying an player item

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

Creates a copy of the object.

[`copy(with:)`](/documentation/AVFoundation/AVPlayerItem/copy(with:))

Creates a copy of the object with the specified zone.

### Deprecated

[Deprecated symbols](/documentation/AVFoundation/avplayeritem-deprecated-symbols)

Review unsupported symbols and their replacements.


---

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)