AVPlayerViewController displays the video content of an AVPlayer object along with system-supplied playback controls.


Using AVPlayerViewController makes it easy for you to add media playback capabilities to your application matching the styling and features of the native system players. Since AVPlayerViewController is a system framework class, your playback applications automatically adopt the new aesthetics and features of future operating system updates without any additional work from you.

Supporting AirPlay

AirPlay lets users play your video content on an Apple TV and stream audio content to third-party AirPlay speakers and receivers. AVPlayerViewController automatically supports AirPlay, but you need to perform some project and audio session configuration before it can be enabled in your application. See Configuring Audio Settings for iOS and tvOS in Media Playback Programming Guide for more on how to perform this configuration.

See AirPlay Overview for more information about the features and capabilities of AirPlay.

Adopting Picture in Picture Playback

Starting in iOS 9, you can use AVPlayerViewController to provide Picture in Picture (PiP) playback on supported iPad models. PiP playback lets users minimize your video player to a small floating window so they can perform other activities in the primary application or even in another application. This brings a new level of multitasking capabilities to the iPad allowing users to continue playback while performing other activities on their devices. To learn more about how to support PiP playback in your iPad applications, see AVKit for iOS in Media Playback Programming Guide.

Using AVPlayerViewController in tvOS

AVPlayerViewController in tvOS brings advanced Siri Remote control features to your application. This lets users easily play and navigate your content and access supporting features such as subtitles and alternate audio tracks. AVPlayerViewController also provides support for using Siri Remote voice commands such as “Skip ahead 15 seconds” and “What did she say?” to control playback of your content.

AVKit for tvOS extends the features of AVPlayerViewController and AVPlayerItem to provide additional ways of navigating and presenting content.

  • External Metadata. If you use the externalMetadata property to associate additional metadata with the AVPlayerItem object presented in the player view controller, the AVPlayerViewController UI can display that information.

  • Navigation Marker Groups. A group of navigation markers allows the user to jump between significant events in a media presentation. The most common form of navigation marker group is a chapter list, but you can also create additional or alternative means of navigation—for example, to allow the user to quickly jump between key moments in a recorded sporting event. The player view controller lets the user choose between multiple marker groups for navigating through the media content it presents.

    Use the AVNavigationMarkersGroup class to create and describe navigation markers, then use the navigationMarkerGroups property to associate marker groups with the AVPlayerItem object presented in the player view controller.

  • Interstitial Content. Some content might be unrelated to the main content presented in your player view controller, or have different presentation requirements. For example, you might not allow the user to skip over advertisements when scrubbing through the playback timeline, or require that the user not skip mandatory legal notices.

    Use the AVInterstitialTimeRange class to describe interstitial content, and the interstitialTimeRanges property to associate those time ranges with the AVPlayerItem object presented in the player view controller. Then, you can use the player view controller’s delegate object to be notified when interstitial content plays, and change playback options such as the requiresLinearPlayback property accordingly.

  • Content Proposals. When presenting serialized content, such as a TV show, you often want to propose additional content for the user to watch when the current episode ends. Starting with tvOS 10, it’s easy to add this functionality to your app using AVKit content proposals.

    Use the AVContentProposal class to describe the proposed content, and set it as the nextContentProposal property of the AVPlayerItem object presented in the player view controller. You can implement the methods of the player view controller’s delegate object to prepare to present a content proposal and perform actions in response to a user accepting, rejecting, or deferring the proposal.

See AVKit for tvOS in Media Playback Programming Guide for more information on how to use these features.


Accessing the Player Object

var player: AVPlayer?

The player that provides the media content for the player view controller.

Accessing the Delegate Object

var delegate: AVPlayerViewControllerDelegate?

The delegate object for the player view controller.

Accessing Player View Controller Attributes

var showsPlaybackControls: Bool

A Boolean value that indicates whether the player view controller shows playback controls.

var allowsPictureInPicturePlayback: Bool

Specifies whether the player view controller allows Picture in Picture playback on iPad.

var contentOverlayView: UIView?

A view displayed between the video content and the playback controls.

var isReadyForDisplay: Bool

A Boolean value indicating that the first video frame, of the current item of the associated AVPlayer object, is ready for display.

var videoBounds: CGRect

The current size and position of the video image as displayed within the bounds of the player view controller’s view.

var videoGravity: String

A string that specifies how the video is displayed within the bounds of the player view controller’s view.

var requiresLinearPlayback: Bool

A Boolean value that determines whether the user is allowed to skip media content.

var updatesNowPlayingInfoCenter: Bool

A Boolean value that indicates whether the player view controller updates the now playing info center.

Managing Content Proposals

var contentProposalViewController: AVContentProposalViewController!

The view controller responsible for the presentation of content proposals.

Managing Skipping Behavior

var skippingBehavior: AVPlayerViewControllerSkippingBehavior

Specifies the behavior triggered by skipping gestures.

var isSkipBackwardEnabled: Bool

Indicates whether backward-skipping is available.

var isSkipForwardEnabled: Bool

Indicates whether forward-skipping is available.

Managing Subtitles

var allowedSubtitleOptionLanguages: [String]?

An optional array of language codes restricting the set of subtitle languages available to the user.

var requiresFullSubtitles: Bool

A Boolean value that determines whether the user is allowed to disable display of subtitles.

Playing a Pre-Roll Video Ad

class func preparePrerollAds()

Informs iAd that the application intends to play a pre-roll ad.

func playPrerollAd(completionHandler: (Error?) -> Void)

Requests playback of a pre-roll video iAd.

func cancelPreroll()

Cancels the playback of a pre-roll video ad.


enum AVPlayerViewControllerSkippingBehavior

Constants that represent the player view controller’s skipping behavior.

Beta Software

This documentation contains preliminary information about an API or technology in development. This information is subject to change, and software implemented according to this documentation should be tested with final operating system software.

Learn more about using Apple's beta software