Adopting Picture in Picture Playback in tvOS

At a glance

Project structure

PictureInPictureSample/
├── ViewController.swift
├── PlaybackItem.swift
├── ButtonGridView.swift
├── CustomPlayerViewController.swift
├── CustomPlayerControlsView.swift
└── AppDelegate.swift

Structure observations

• PlaybackItem combines video choice and player kind, letting one menu exercise both implementations.
• The custom player separates playback/PiP ownership from transient control rendering.

Overall architecture

flowchart LR
    User["Button grid"] --> Root["ViewController"]
    Root --> Item["PlaybackItem"]
    Item --> Queue["AVQueuePlayer"]
    Root --> Choice{"PlayerKind"}
    Choice --> System["AVPlayerViewController"]
    Choice --> Custom["CustomPlayerViewController"]
    Custom --> Layer["AVPlayerLayer"]
    Custom --> PiP["AVPictureInPictureController"]
    Custom --> Controls["CustomPlayerControlsView"]
    System -. delegate .-> Root
    Custom -. delegate .-> Root

Reference code

PictureInPictureSample/ViewController.swift:32 — the root selects a system or custom player behind the same presentation flow.

func play(item: PlaybackItem) {
    let player = AVQueuePlayer(playerItem: item.video.playerItem)
    let playerViewController: UIViewController
    switch item.playerKind {
    case .avPlayerViewController:
        let controller = AVPlayerViewController()
        controller.player = player
        controller.delegate = self
        playerViewController = controller
    case .customPlayerViewController:
        let controller = CustomPlayerViewController()
        controller.player = player
        controller.delegate = self
        playerViewController = controller
    }
}

Interpretation

The root owns navigation policy, while each player owns its presentation technology. Both report PiP dismissal/restoration through delegate APIs, allowing common restoration logic.

Ownership and state

classDiagram
    ViewController *-- AVQueuePlayer : creates per selection
    ViewController --> AVPlayerViewController : presents
    ViewController --> CustomPlayerViewController : presents
    CustomPlayerViewController *-- AVPlayerLayer : creates from player
    CustomPlayerViewController *-- AVPictureInPictureController : creates
    CustomPlayerViewController *-- CustomPlayerControlsView : owns while visible
    CustomPlayerViewController o-- CustomPlayerViewControllerDelegate : weak
    ActiveSet o-- CustomPlayerViewController : retains during PiP

Ownership evidence

PictureInPictureSample/CustomPlayerViewController.swift:23 — the custom controller owns PiP infrastructure but delegates navigation policy.

class CustomPlayerViewController: UIViewController {
    weak var delegate: CustomPlayerViewControllerDelegate?
    var player: AVPlayer? {
        didSet { playerLayer = AVPlayerLayer(player: player) }
    }
    private var playerLayer: AVPlayerLayer?
    private var pictureInPictureController: AVPictureInPictureController?
    private var controlsView: CustomPlayerControlsView?
}

Class and protocol design

Access control

Reference code

PictureInPictureSample/CustomPlayerViewController.swift:154 — lifecycle callbacks are the sole mutation path for the private retention set.

func pictureInPictureControllerWillStartPictureInPicture(_ controller: AVPictureInPictureController) {
    activeCustomPlayerViewControllers.insert(self)
}

func pictureInPictureControllerDidStopPictureInPicture(_ controller: AVPictureInPictureController) {
    activeCustomPlayerViewControllers.remove(self)
}

Logic ownership and placement

Design patterns

Naming conventions

• Custom prefixes distinguish app-owned player/control implementations from AVKit types.
• Delegate callbacks use event/intent phrasing: DidRequest, ShouldAutomaticallyDismiss, restoreUserInterface.
• PlayerKind, PlaybackItem, and Video name domain choices rather than UI widgets.
• Files match their principal type and responsibility.

Architecture takeaways

• Centralize restoration policy when multiple player implementations support the same lifecycle.
• A custom PiP player must own both the player layer and PiP controller as a coordinated unit.
• Weak delegates solve cycles, but an active PiP flow may still require deliberate temporary retention.
• Use a value model to select implementation strategies without spreading conditionals across views.

Source map

• Official Apple documentation