Class

AVPlayerViewController

A view controller that displays the video content from a player object along with system-supplied playback controls.

Declaration

class AVPlayerViewController : UIViewController

Overview

Using AVPlayerViewController simplifies adding media playback capabilities to your app that matches the styling and features of the native system players. Because AVPlayerViewController is a system framework class, your playback apps 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 to enable it you need to perform some project and audio session configuration. 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.

Providing Custom Metadata

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.

Adopting Picture in Picture Playback

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.

Using AVPlayerViewController in tvOS

AVPlayerViewController in tvOS brings advanced Siri Remote control features to your app. This lets users 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.

  • 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.

Topics

Accessing the Player Object

var player: AVPlayer?

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

Accessing the Delegate Object

var delegate: AVPlayerViewControllerDelegate?

The player view controller’s delegate object.

protocol AVPlayerViewControllerDelegate

A protocol that defines the methods to implement to respond to media playback events associated with a player view controller.

Configuring the Player View Controller

var showsPlaybackControls: Bool

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

var playbackControlsIncludeInfoViews: Bool

A Boolean value that indicates whether the player shows information views when requested by the user.

var playbackControlsIncludeTransportBar: Bool

A Boolean value that indicates whether the player shows the transport bar and related controls.

var allowsPictureInPicturePlayback: Bool

A Boolean value that indicates whether the player allows Picture in Picture playback.

var contentOverlayView: UIView?

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

var entersFullScreenWhenPlaybackBegins: Bool

A Boolean value that determines whether the player automatically displays in full screen when the user taps the play button.

var exitsFullScreenWhenPlaybackEnds: Bool

A Boolean value that indicates whether the player exits full-screen mode when playback ends.

var isReadyForDisplay: Bool

A Boolean value that indicates that the player item’s first video frame 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: AVLayerVideoGravity

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

var requiresLinearPlayback: Bool

A Boolean value that determines whether the player allows the user to skip media content.

var unobscuredContentGuide: UILayoutGuide

A layout guide representing an area that won’t be permanently obscured by fixed-position playback controls when they’re visible.

var updatesNowPlayingInfoCenter: Bool

A Boolean value that indicates whether the player view controller updates the Now Playing info center.

var appliesPreferredDisplayCriteriaAutomatically: Bool

A Boolean value that indicates whether the player view controller automatically sets the screen’s display criteria to match that of the currently playing asset.

var customInfoViewController: UIViewController?

A view controller that provides client-specific content and controls alongside system-provided information and settings panels.

var customOverlayViewController: UIViewController?

A view controller that presents custom content over the player view controller’s view.

var pixelBufferAttributes: [String : Any]?

The pixel buffer attributes of the video frames presented during playback.

Managing Content Proposals

var contentProposalViewController: AVContentProposalViewController!

The view controller responsible for the presentation of content proposals.

Managing Skipping Behavior

var isSkipForwardEnabled: Bool

A Boolean value that indicates whether forward-skipping is available.

var isSkipBackwardEnabled: Bool

A Boolean value indicating whether backward-skipping is available.

var skippingBehavior: AVPlayerViewControllerSkippingBehavior

The behavior triggered by skipping gestures.

enum AVPlayerViewControllerSkippingBehavior

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

Managing Subtitles

var allowedSubtitleOptionLanguages: [String]?

An 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 can disable display of subtitles.

Playing a Preroll Video Ad

class func preparePrerollAds()

Informs iAd that the app intends to play a preroll ad.

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

Requests playback of a preroll video iAd.

func cancelPreroll()

Cancels the playback of a preroll video ad.

See Also

Media Playback

Adopting Picture in Picture in a Standard Player

Add Picture in Picture (PiP) playback to your app using a player view controller.

Adopting Picture in Picture in a Custom Player

Add controls to your custom player user interface to invoke Picture in Picture (PiP) playback.

Working with Interstitial Content in tvOS

Present additional content such as legal text, content warnings, or advertisements alongside your main media presentation.

Using AVKit in iOS

This sample code project demonstrates techniques for tracking AVPlayerViewController presentation state across multiple application scenarios, including being displayed fullscreen, embedded inline, or as Picture in Picture.

Adopting Custom Interactive Overlays, Channel Flipping, and Parental Controls in tvOS Video Playback

This sample demonstrates support for custom interactive overlays, and parental controls, using AVPlayerViewController.

Adding Information to the Info Panel (tvOS)

Add metadata information and navigation markers to the Info panel in Apple TV.

class AVPlayerView

A macOS-only object that displays the video content from a player object along with system-supplied playback controls.

class AVPictureInPictureController

A controller that responds to user-initiated Picture in Picture playback of video in a floating, resizable window.

class AVInterstitialTimeRange

A time range in an audiovisual presentation designated as interstitial content, such as advertisements or legal notices.

class AVNavigationMarkersGroup

A set of markers for navigating playback of an audiovisual presentation.