Working with Overlays and Parental Controls in tvOS

At a glance

Project structure

TVAVPlayerViewControllerDemo/
└── TVAVPlayerViewControllerDemo/
    ├── AppDelegate.swift
    ├── MenuViewController.swift
    ├── VideoPlaybackViewController.swift
    ├── CustomInteractiveVideoOverlayViewController.swift
    └── Base.lproj/
        ├── Main.storyboard
        └── CustomInteractiveVideoOverlay.xib

Structure observations

• Screen controllers map directly to the menu, playback, and interactive-overlay responsibilities.
• The overlay’s visual hierarchy lives in a XIB; playback navigation lives in the main storyboard.
• All player lifecycle and policy logic stays in the playback controller rather than the menu or overlay.

Overall architecture

flowchart LR
    Menu["MenuViewController"] --> Playback["VideoPlaybackViewController"]
    Menu --> Metadata["URL, title, description, rating"]
    Metadata --> Playback
    Playback --> PVC["AVPlayerViewController"]
    Playback --> Player["AVQueuePlayer"]
    Playback --> Pending["Pending AVPlayerItem"]
    Playback --> Overlay["CustomInteractiveVideoOverlay"]
    PVC --> Overlay
    Playback -. delegate .-> PVC
    Pending --> Policy["Playback restrictions authorization"]

Reference code

TVAVPlayerViewControllerDemo/TVAVPlayerViewControllerDemo/VideoPlaybackViewController.swift:100 — the playback screen replaces the AVKit controller and attaches its owned overlay before playback begins.

private func loadNewPlayerViewController() {
    let newPlayerViewController = AVPlayerViewController()
    newPlayerViewController.delegate = self
    newPlayerViewController.customOverlayViewController = customInteractiveVideoOverlay
    if let oldPlayerViewController = self.playerViewController {
        oldPlayerViewController.removeFromParent()
        oldPlayerViewController.viewIfLoaded?.removeFromSuperview()
    }
    self.playerViewController = newPlayerViewController
    player = AVQueuePlayer()
    addChild(newPlayerViewController)
}

Interpretation

The menu supplies content facts and presents one playback owner. The playback controller turns those facts into AV metadata, gates the pending item through parental authorization, and composes the AVKit UI with a custom overlay.

Ownership and state

classDiagram
    MenuViewController *-- VideoPlaybackViewController : creates in both initializers
    VideoPlaybackViewController *-- CustomInteractiveVideoOverlay : owns
    VideoPlaybackViewController *-- AVPlayerViewController : owns current child
    VideoPlaybackViewController *-- AVQueuePlayer : owns current player
    VideoPlaybackViewController *-- NSKeyValueObservation : owns tokens
    VideoPlaybackViewController *-- AVPlayerItem : holds pending item
    AVQueuePlayer o-- AVPlayerItem : current item
    AVPlayerViewController o-- AVQueuePlayer : receives after authorization
    AVPlayerViewController o-- CustomInteractiveVideoOverlay : presents

Ownership evidence

TVAVPlayerViewControllerDemo/TVAVPlayerViewControllerDemo/VideoPlaybackViewController.swift:18 — one controller retains all mutable playback collaborators and policy-observation state.

@objc dynamic var playerViewController: AVPlayerViewController?
let customInteractiveVideoOverlay = CustomInteractiveVideoOverlay(
    nibName: "CustomInteractiveVideoOverlay", bundle: nil)
var player: AVQueuePlayer?
@objc dynamic var pendingPlayerItem: AVPlayerItem?
var playerItemStatusObservation: NSKeyValueObservation?
var currentItemErrorObservation: NSKeyValueObservation?
var isPlaybackActive = false

Class and protocol design

There is no app-defined protocol layer. The sample uses AVKit’s delegate directly because one playback controller is both the framework adapter and lifecycle owner.

Access control

Reference code

TVAVPlayerViewControllerDemo/TVAVPlayerViewControllerDemo/VideoPlaybackViewController.swift:88 — metadata and controller-construction primitives are private; callers receive the higher-level loadAndPlay command.

private func metadataItem(_ identifier: AVMetadataIdentifier,
                          stringValue value: String) -> AVMutableMetadataItem {
    let metadataItem = AVMutableMetadataItem()
    metadataItem.value = value as NSString
    metadataItem.identifier = identifier
    return metadataItem
}

private func loadNewPlayerViewController() {
    let newPlayerViewController = AVPlayerViewController()
    // setup remains inside the playback owner
}

Logic ownership and placement

Design patterns

Main application flow

sequenceDiagram
    actor User
    participant Menu
    participant Playback as Playback controller
    participant Item as Pending player item
    participant Policy as Restriction authorization
    participant AVKit as AVPlayerViewController
    User->>Menu: Select poster
    Menu->>Playback: loadAndPlay metadata
    Playback->>Item: create item and external metadata
    Item-->>Playback: status readyToPlay via KVO
    Playback->>Policy: request authorization
    alt authorized
        Playback->>AVKit: attach queue player
        Playback->>AVKit: start playback
    else denied or failed
        Playback->>Playback: dismiss
    end

Reference code

TVAVPlayerViewControllerDemo/TVAVPlayerViewControllerDemo/VideoPlaybackViewController.swift:31 — the observer attaches the player to AVKit only after the pending item is ready and authorization succeeds.

playerItemStatusObservation = observe(\.pendingPlayerItem?.status) { object, _ in
    DispatchQueue.main.async {
        if object.pendingPlayerItem?.status == .readyToPlay {
            object.pendingPlayerItem?.requestPlaybackRestrictionsAuthorization { success, _ in
                if success {
                    object.pendingPlayerItem = nil
                    object.playerViewController?.player = object.player
                    object.player?.rate = 1.0
                } else {
                    _ = object._dismiss()
                }
            }
        }
    }
}

Naming conventions

• Screen types use descriptive controller names: MenuViewController, VideoPlaybackViewController, and CustomInteractiveVideoOverlay.
• Commands state intent: presentVideo, loadAndPlay, and loadNewPlayerViewController.
• Observation tokens name the key path they protect: playerItemStatusObservation and currentItemErrorObservation.
• pendingPlayerItem distinguishes gated content from the player’s authorized current item.
• _dismiss is a private helper whose leading underscore separates its Boolean-returning cleanup operation from the AVKit delegate callback.

Architecture takeaways

• Keep the player item pending until both readiness and policy checks succeed.
• Put rating metadata on the item before exposing the player to system playback UI.
• Let one playback owner create, embed, replace, and dismantle the AVKit controller.
• Retain KVO tokens alongside the state they observe and marshal observed mutations to the main queue.
• Use the system delegate directly when there is only one concrete playback implementation and no substitutable app capability.

Source map

• Official Apple documentation