Article

Guidelines for Apple TV 4K Development

Follow these guidelines when developing for Apple TV 4K.

Overview

General development for Apple TV 4K is the same as developing for Apple TV. However, when streaming 4K content, take the following guidelines into account:

Avoid negative impact on video playback, particularly at 4K, by limiting additional work that your app contributes to the GPU. On Apple TV 4K, the GPU is involved in the playback pipeline when the TV mode is Dolby Vision or HDR10, whether or not 4K content is playing. Playback of Dolby Vision and HDR10 content further increases the GPU load.

Only a single Dolby Vision or HDR10 video can be played at a time. Any other video streams playing at the same time must be SDR.

Know the maximum allowable frame rate for your content. Dolby Vision and HDR10 content can play at up to 30 fps. SDR content can play at up to 60 fps.

When providing Dolby Vision and HDR10 content, you must also include SDR variants in your master playlist. SDR variants may be activated when, for example, the TV mode is SDR, when a Dolby Vision or HDR10 stream is already playing, or when scrubbing the UI.

Video apps should ensure that they're on the fast path for compositing video. HDR video quality and performance are significantly degraded if not on the fast path. Use the Core Animation instrument template and verify that the Color Compositing Fast-Path Blue debug option tints the video blue during playback. Only a single stream can be on the fast path at a given time. When streaming multiple videos, ensure that the streams not on the fast path have no offscreen passes. Use the Color Offscreen-Rendered Yellow debug option and verify that videos aren't tinted yellow.

Don't try to use the AVPlayerItemVideoOutput class to do custom video processing or rendering with HDR video. This class doesn't work with HDR video.

Before submitting your app, test it on an Apple TV 4K device in Dolby Vision 60 Hz mode. Doing so maximizes your chances of finding any GPU-related performance issues.

For a complete list of requirements for steaming on Apple TV 4K, see the HLS Authoring Specification for Apple Devices.

See Also

First Steps

Creating a Basic Video Player (iOS and tvOS)

Create a simple video playback app with built-in controls.

Creating a Basic Video Player (macOS)

Create a simple video playback app with built-in controls.