Introduction to AVDisplayManager

Starting with tvOS 11.2, Apple TV 4K can automatically switch video display modes to match the native frame rate and dynamic range of video content. The Video and Audio section of the Settings app allows the matching frame rate and dynamic range behavior to be set independently, and enables viewing of content it its original frame rate and dynamic range. By default, these options are disabled. When enabled, and video content is played back in a compatible app, tvOS will automatically switch the video display settings to match that of the content. For instance, if the content is in 24 frames per second and standard dynamic range, the device will switch from its system mode to 24 frame per second, standard dynamic range mode. Once the media playback session is over, the device will then switch back to its system mode.

The first step in supporting frame rate matching for your content is to ensure that your HLS master playlists are fully annotated with the native frame rate of the variants using the FRAME-RATE attribute. If a playlist does not include the FRAME-RATE attribute, frame rate mode switching will not be supported for that asset. Furthermore, only playlists that declare either a single frame rate for all variants or only have frame rates that are integer multiples of the smallest frame rate are supported. For example, 29.97 and 59.94.

Dynamic range mode matching does not typically require any changes to your playlists, as content is assumed to be SDR unless the VIDEO-RANGE attribute specifies otherwise, as all non-SDR content must include the VIDEO-RANGE attribute already.

Apps that use AVPlayerViewController will automatically support mode matching, unless the appliesPreferred DisplayCriteriaAutomatically property is changed to false.

When content is played back in full screen using AVPlayerViewController, tvOS will automatically switch to the appropriate display mode for that content. Then, when AVPlayerViewController leaves full-screen mode or is dismissed, tvOS will switch back to its system display mode.

For apps that play back full-screen content using AVPlayerViewController or TVMLKit, no additional work is required. However, for other scenarios where your video might not always be played back in full screen, if you are playing multiple videos simultaneously, switching between different short videos frequently, or you aren't using AVPlayerViewController for your video playback, you may need to directly specify the AVDisplayManager preferredDisplayCriteria to ensure that the mode switch occurs at the right time and reflects the characteristics of the appropriate media content.

If you are using AVPlayerViewController and wish to opt out of mode switching entirely or need to manage the display mode manually, begin by setting the appliesPreferredDisplay CriteriaAutomatically property of AVPlayerViewController to false. This will disable the automatic AVKit matching behavior. Then, to trigger tvOS to switch modes to match a specific piece of content, retrieve the AVDisplayCriteria object vended by the preferredDisplayCriteria property of the AVAsset. Assign that AVDisplayCriteria object to the preferredDisplayCriteria property of the AVDisplayManager vended by the key UIWindow. The mode switch will occur upon setting this property, assuming that matching was enabled in settings and that the attached device supports the preferred mode. You should perform this switch before assigning the AVPlayerItem to the AVPlayer object so that AVPlayer configures itself based on the targeted display mode.

To switch back to the system's default mode, simply set the preferredDisplayCriteria property to nil.

To know when the mode switch begins and ends, you can key-value observe the displayModeSwitchInProgress property of the AVDisplayManager object. To help you determine the best way to make use of this new feature in your media application, here are some guidelines to keep in mind: Switch modes only as often as necessary. All televisions respond to mode switching a little differently, but it will generally cause the screen to flash or temporarily black out, and may take a few seconds to complete. This can be disruptive if it occurs more often than necessary. Typically, mode switching is only appropriate for full-screen playback. Matching frame rate and dynamic range for content that plays in the background, as a thumbnail, or as an interstitial as part of a game, can be quite disruptive and is generally unnecessary. The primary user interface of your app, outside of the video viewing experience, should be run in the system's frame rate so that UI and animations are smooth and fluid. When the television is in a lower frame rate mode, those animations and movements will also render at that frame rate, and may appear less smooth as a result.

There are also several circumstances where leaving the device in its system mode will yield an improved user experience. If your app plays shorter clips, displays multiple video tiles simultaneously, or frequently switches between content with disparate characteristics, it would be preferred to avoid mode switching entirely to ensure the viewing experience is not disrupted unnecessarily.

tvOS 11.2 enables video content frame rate and dynamic range matching on Apple TV 4K. AVPlayerViewController can manage this behavior automatically, but some apps will want more control by utilizing AVDisplayManager and AVDisplayCriteria.

Please visit developer.apple.com for more information.