Supporting remote interactions in tvOS

At a glance

Project structure

DirectionalRemotes/
├── MenuViewController.swift
├── System Player/
├── Custom Player/
│   ├── CustomPlayer.swift
│   ├── CustomPlayerViewController.swift
│   └── CustomPlayerView.swift
├── Remote Events/
├── Guide/
└── Shared/
    ├── Data/
    ├── RemoteCommand.swift
    ├── RemoteEvent.swift
    └── Extensions/

The archive is a suite of alternative examples, not one unified playback stack. Shared TVSchedule, RemoteCommand, and RemoteEvent types provide common vocabulary.

Overall architecture

flowchart LR
    Menu["MenuViewController"] --> System["SystemPlayerViewController"]
    Menu --> CustomVC["CustomPlayerViewController"]
    Menu --> EventsVC["RemoteEventsViewController"]
    Menu --> Guide["GuideViewController"]
    CustomVC --> Custom["CustomPlayer"]
    EventsVC --> Events["RemoteEventsPlayer"]
    System --> AVKit["AVPlayerViewController"]
    Custom --> Queue["AVQueuePlayer"]
    Events --> Commands["MPRemoteCommandCenter"]
    System --> Schedule["TVSchedule.shared"]
    Custom --> Schedule

Reference code

DirectionalRemotes/Custom Player/CustomPlayerViewController.swift:118 — the controller normalizes input before handing it to playback logic (abridged).

@objc private func playPausePressed() {
    customPlayer.remoteEventReceived(.playPause)
}

@objc private func channelUpPressed() {
    customPlayer.remoteEventReceived(.channelUp)
}

@objc private func dPadLeftPressed() {
    customPlayer.remoteEventReceived(.dPadLeft)
}

This controller-to-player command boundary is clearest in the custom scenario. The system scenario delegates most behavior to AVPlayerViewController; the remote-events scenario exposes command delivery instead.

Ownership and state

classDiagram
    CustomPlayerViewController *-- CustomPlayer
    CustomPlayer *-- AVQueuePlayer
    CustomPlayer --> TVSchedule : shared data
    RemoteEventsViewController *-- RemoteEventsPlayer
    RemoteEventsPlayer *-- AVQueuePlayer
    SystemPlayerViewController *-- AVQueuePlayer
    SystemPlayerViewController *-- AVPlayerViewController
    GuideViewController --> TVSchedule : shared data

Ownership evidence

DirectionalRemotes/Custom Player/CustomPlayerViewController.swift:10 — the scenario controller owns and tears down its player (abridged).

class CustomPlayerViewController: UIViewController {
    private lazy var customPlayer = CustomPlayer()

    deinit {
        customPlayer.tearDown()
    }

    override func viewDidLoad() {
        super.viewDidLoad()
        customPlayer.delegate = self
    }
}

Class and protocol design

classDiagram
    class CustomPlayerReporting {
        <<protocol>>
        reportFeedback()
    }
    CustomPlayerViewController ..|> CustomPlayerReporting
    CustomPlayer --> CustomPlayerReporting : weak delegate
    class RemoteEventsPlayerReporting {
        <<protocol>>
        playerReceived()
    }
    RemoteEventsViewController ..|> RemoteEventsPlayerReporting
    RemoteEventsPlayer --> RemoteEventsPlayerReporting : weak delegate

Reference code

DirectionalRemotes/Custom Player/CustomPlayer.swift:10 — a narrow class-only delegate reports player results back to UI (abridged).

protocol CustomPlayerReporting: AnyObject {
    func reportFeedback(_ feedback: String,
                        withFeedbackType feedbackType: CustomPlayerFeedbackType)
}

class CustomPlayer {
    weak var delegate: CustomPlayerReporting?
}

The player does not know its concrete view controller. Similar RemoteEventsPlayerReporting and GuideReporting protocols keep other feature callbacks local.

Access control

DirectionalRemotes/Custom Player/CustomPlayer.swift:25:

class CustomPlayer {
    private var playerState: CustomPlayerState = .stopped
    let player: AVQueuePlayer
    weak var delegate: CustomPlayerReporting?
    private var rateObserver: NSKeyValueObservation?
    private var statusObserver: NSKeyValueObservation?
}

Logic ownership and placement

Design patterns

Naming conventions

• Feature prefixes (CustomPlayer, RemoteEvents, Guide) keep scenario types distinct.
• Reporting protocols describe callback direction: CustomPlayerReporting, GuideReporting.
• Event/command enums separate physical input (RemoteEvent) from MediaPlayer command objects (RemoteCommand).
• Setup/teardown methods are paired; target-action handlers end in Pressed or Action.

Architecture takeaways

• Normalize physical input into small enums before applying playback rules.
• Let scenario controllers own lifecycle while player objects own transport and command registration.
• Use weak reporting protocols for playback-to-UI feedback.
• Treat the four feature folders as alternatives; combining them into one architecture would misrepresent the sample.

Source map

• Official Apple documentation