Video

The system-provided video player offers two viewing modes: full-screen (aspect fill) and fit-to-screen (aspect). By default, the system selects a viewing mode based on a video's aspect ratio, and the user can switch modes during playback. For developer guidance, see AVPlayerViewController.

  • Full-screen (aspect-fill) viewing mode. The video scales to fill the display. Some edge cropping may occur. This is the default viewing mode for wide video (2:1 through 2.40:1). For developer guidance, see resizeAspectFill.

  • Fit-to-screen (aspect) viewing mode. The entire video is visible onscreen. Letterboxing or pillarboxing will occur. This is the default viewing mode for standard video (4:3, 16:9, and anything up to 2:1) and ultra-wide video (anything above 2.40:1). For developer guidance, see resizeAspect.

Examples of Viewing Modes on iPhone XS

Make sure custom video players behave as expected. The objective is to fill the display by default when playing video content on full-screen devices. However, if filling the display results in too much cropping, the video should be scaled to fit the screen. You should also allow people to switch between full-screen and fit-to-screen viewing based on their individual preferences. For developer guidance, see AVPlayerLayer.

Examples of Padding on iPhone XS

Always display video content at its original aspect ratio. When video content uses embedded letterbox or pillarbox padding to conform to a specific aspect ratio, iOS is unable to correctly scale the video based on the user's choice of viewing modes. Padding embedded within the video frame can cause videos to appear smaller in full-screen mode and fit-to-screen mode. It also prevents videos from displaying correctly in edge-to-edge, non-full-screen contexts, like Picture in Picture mode on iPad.