--- title: AVPlayer framework: avfoundation role: symbol role_heading: Class path: avfoundation/avplayer --- # AVPlayer An object that provides the interface to control the player’s transport behavior. ## Declaration ```swift @MainActor class AVPlayer ``` ## Mentioned in Controlling the transport behavior of a player Observing playback state in SwiftUI Supporting AirPlay in your app Implementing simple enhanced buffering for your content Monitoring playback progress in your app Presenting chapter markers Selecting subtitles and alternative audio tracks ## Overview 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 - [init(url:)](avfoundation/avplayer/init(url:)-87cxx.md) - [init(playerItem:)](avfoundation/avplayer/init(playeritem:).md) - [init()](avfoundation/avplayer/init().md) ### Managing the player item - [currentItem](avfoundation/avplayer/currentitem.md) - [replaceCurrentItem(with:)](avfoundation/avplayer/replacecurrentitem(with:).md) ### Determining player readiness - [status](avfoundation/avplayer/status-swift.property.md) - [AVPlayer.Status](avfoundation/avplayer/status-swift.enum.md) - [error](avfoundation/avplayer/error.md) ### Controlling playback - [defaultRate](avfoundation/avplayer/defaultrate.md) - [play()](avfoundation/avplayer/play().md) - [pause()](avfoundation/avplayer/pause().md) - [rate](avfoundation/avplayer/rate.md) - [rateDidChangeNotification](avfoundation/avplayer/ratedidchangenotification.md) - [playheadReachedLiveEdge](avfoundation/avplayer/ratedidchangereason/playheadreachedliveedge.md) - [reversePlaybackReachedStartOfSeekableRange](avfoundation/avplayer/ratedidchangereason/reverseplaybackreachedstartofseekablerange.md) ### Observing playback time - [currentTime()](avfoundation/avplayer/currenttime().md) - [addPeriodicTimeObserver(forInterval:queue:using:)](avfoundation/avplayer/addperiodictimeobserver(forinterval:queue:using:).md) - [addBoundaryTimeObserver(forTimes:queue:using:)](avfoundation/avplayer/addboundarytimeobserver(fortimes:queue:using:).md) - [removeTimeObserver(_:)](avfoundation/avplayer/removetimeobserver(_:).md) ### Seeking through media - [seek(to:)](avfoundation/avplayer/seek(to:)-87h2r.md) - [seek(to:completionHandler:)](avfoundation/avplayer/seek(to:completionhandler:)-75bls.md) - [seek(to:toleranceBefore:toleranceAfter:)](avfoundation/avplayer/seek(to:tolerancebefore:toleranceafter:).md) - [seek(to:toleranceBefore:toleranceAfter:completionHandler:)](avfoundation/avplayer/seek(to:tolerancebefore:toleranceafter:completionhandler:).md) - [seek(to:)](avfoundation/avplayer/seek(to:)-9h9qr.md) - [seek(to:completionHandler:)](avfoundation/avplayer/seek(to:completionhandler:)-wr1l.md) ### Configuring waiting behavior - [automaticallyWaitsToMinimizeStalling](avfoundation/avplayer/automaticallywaitstominimizestalling.md) - [reasonForWaitingToPlay](avfoundation/avplayer/reasonforwaitingtoplay.md) - [AVPlayer.WaitingReason](avfoundation/avplayer/waitingreason.md) - [timeControlStatus](avfoundation/avplayer/timecontrolstatus-swift.property.md) - [AVPlayer.TimeControlStatus](avfoundation/avplayer/timecontrolstatus-swift.enum.md) - [playImmediately(atRate:)](avfoundation/avplayer/playimmediately(atrate:).md) ### Responding when playback ends - [actionAtItemEnd](avfoundation/avplayer/actionatitemend-swift.property.md) - [AVPlayer.ActionAtItemEnd](avfoundation/avplayer/actionatitemend-swift.enum.md) ### Configuring media selection criteria - [appliesMediaSelectionCriteriaAutomatically](avfoundation/avplayer/appliesmediaselectioncriteriaautomatically.md) - [mediaSelectionCriteria(forMediaCharacteristic:)](avfoundation/avplayer/mediaselectioncriteria(formediacharacteristic:).md) - [setMediaSelectionCriteria(_:forMediaCharacteristic:)](avfoundation/avplayer/setmediaselectioncriteria(_:formediacharacteristic:).md) ### Accessing player output - [videoOutput](avfoundation/avplayer/videooutput.md) ### Configuring audio behavior - [volume](avfoundation/avplayer/volume.md) - [isMuted](avfoundation/avplayer/ismuted.md) - [allowedAudioSpatializationFormats](avfoundation/avplayeritem/allowedaudiospatializationformats.md) - [isAudioSpatializationAllowed](avfoundation/avplayeritem/isaudiospatializationallowed.md) - [audioOutputSuppressedDueToNonMixableAudioRoute](avfoundation/avplayer/audiooutputsuppressedduetononmixableaudioroute.md) - [intendedSpatialAudioExperience](avfoundation/avplayer/intendedspatialaudioexperience-1bd87.md) ### Configuring background playback - [audiovisualBackgroundPlaybackPolicy](avfoundation/avplayer/audiovisualbackgroundplaybackpolicy.md) - [AVPlayerAudiovisualBackgroundPlaybackPolicy](avfoundation/avplayeraudiovisualbackgroundplaybackpolicy.md) ### Managing external playback - [allowsExternalPlayback](avfoundation/avplayer/allowsexternalplayback.md) - [isExternalPlaybackActive](avfoundation/avplayer/isexternalplaybackactive.md) - [usesExternalPlaybackWhileExternalScreenIsActive](avfoundation/avplayer/usesexternalplaybackwhileexternalscreenisactive.md) - [externalPlaybackVideoGravity](avfoundation/avplayer/externalplaybackvideogravity.md) ### Determining HDR playback eligibility - [eligibleForHDRPlayback](avfoundation/avplayer/eligibleforhdrplayback.md) - [availableHDRModes](avfoundation/avplayer/availablehdrmodes.md) - [AVPlayer.HDRMode](avfoundation/avplayer/hdrmode.md) - [eligibleForHDRPlaybackDidChangeNotification](avfoundation/avplayer/eligibleforhdrplaybackdidchangenotification.md) ### Coordinating playback - [playbackCoordinator](avfoundation/avplayer/playbackcoordinator.md) ### Synchronizing multiple players - [setRate(_:time:atHostTime:)](avfoundation/avplayer/setrate(_:time:athosttime:).md) - [preroll(atRate:completionHandler:)](avfoundation/avplayer/preroll(atrate:completionhandler:).md) - [cancelPendingPrerolls()](avfoundation/avplayer/cancelpendingprerolls().md) - [sourceClock](avfoundation/avplayer/sourceclock.md) - [masterClock](avfoundation/avplayer/masterclock.md) ### Preventing sleep and backgrounding - [preventsDisplaySleepDuringVideoPlayback](avfoundation/avplayer/preventsdisplaysleepduringvideoplayback.md) - [preventsAutomaticBackgroundingDuringVideoPlayback](avfoundation/avplayer/preventsautomaticbackgroundingduringvideoplayback.md) ### Determining content protections - [isOutputObscuredDueToInsufficientExternalProtection](avfoundation/avplayer/isoutputobscuredduetoinsufficientexternalprotection.md) ### Configuring audio and video devices - [audioOutputDeviceUniqueID](avfoundation/avplayer/audiooutputdeviceuniqueid.md) - [preferredVideoDecoderGPURegistryID](avfoundation/avplayer/preferredvideodecodergpuregistryid.md) ### Configuring the network resource priority - [networkResourcePriority](avfoundation/avplayer/networkresourcepriority-swift.property.md) - [AVPlayer.NetworkResourcePriority](avfoundation/avplayer/networkresourcepriority-swift.enum.md) ### Configuring observation - [isObservationEnabled](avfoundation/avplayer/isobservationenabled.md) ### Configuring AirPlay behavior - [allowsAirPlayVideo](avfoundation/avplayer/allowsairplayvideo.md) - [isAirPlayVideoActive](avfoundation/avplayer/isairplayvideoactive.md) - [usesAirPlayVideoWhileAirPlayScreenIsActive](avfoundation/avplayer/usesairplayvideowhileairplayscreenisactive.md) ### Displaying closed captions - [isClosedCaptionDisplayEnabled](avfoundation/avplayer/isclosedcaptiondisplayenabled.md) ### Initializers - [init(URL:)](avfoundation/avplayer/init(url:)-8aqw0.md) - [init(URL:)](avfoundation/avplayer/init(url:)-9cqj1.md) ### Instance Properties - [allowsCaptureOfClearKeyVideo](avfoundation/avplayer/allowscaptureofclearkeyvideo.md) - [disconnectedFromSystemAudio](avfoundation/avplayer/disconnectedfromsystemaudio.md) ### Instance Methods - [setDisconnectedFromSystemAudio(_:completionHandler:)](avfoundation/avplayer/setdisconnectedfromsystemaudio(_:completionhandler:).md) ## Relationships ### Inherits From - [NSObject](objectivec/nsobject-swift.class.md) ### Inherited By - [AVQueuePlayer](avfoundation/avqueueplayer.md) ### Conforms To - [AVRoutingPlaybackParticipant](avrouting/avroutingplaybackparticipant.md) - [CVarArg](swift/cvararg.md) - [Copyable](swift/copyable.md) - [CustomDebugStringConvertible](swift/customdebugstringconvertible.md) - [CustomStringConvertible](swift/customstringconvertible.md) - [Equatable](swift/equatable.md) - [Escapable](swift/escapable.md) - [Hashable](swift/hashable.md) - [NSObjectProtocol](objectivec/nsobjectprotocol.md) - [Observable](observation/observable.md) - [Sendable](swift/sendable.md) ## See Also ### Playback control - [Observing playback state in SwiftUI](avfoundation/observing-playback-state-in-swiftui.md) - [Controlling the transport behavior of a player](avfoundation/controlling-the-transport-behavior-of-a-player.md) - [Creating a seamless multiview playback experience](avfoundation/creating-a-seamless-multiview-playback-experience.md) - [AVPlayerItem](avfoundation/avplayeritem.md) - [AVPlayerItemTrack](avfoundation/avplayeritemtrack.md) - [AVQueuePlayer](avfoundation/avqueueplayer.md) - [AVPlayerLooper](avfoundation/avplayerlooper.md)