Playing video content in a standard user interface

At a glance

Project structure

Using AVKit in iOS/
├── ViewController.swift
├── PlaybackController.swift
├── PlayerViewControllerCoordinator.swift
├── VideoBrowserViewController.swift
├── VideoBrowserCell.swift
├── Video.swift
├── DebugHUD.swift
├── VideoBrowserFlowLayout.swift
└── Base.lproj/Main.storyboard

Structure observations

• Global playback coordination is separate from collection-view presentation.
• The coordinator and its AVKit delegate conformance share one file because they participate in the same lifecycle.
• Small UI collaborators such as the cell, layout, and debug HUD remain separate primary-type files.

Overall architecture

flowchart LR
    Root["ViewController"] --> Playback["PlaybackController"]
    Root --> Browser["VideoBrowserViewController"]
    Browser --> Playback
    Playback --> Registry["Video to coordinator registry"]
    Registry --> Coordinator["PlayerViewControllerCoordinator"]
    Coordinator --> PVC["AVPlayerViewController"]
    PVC --> Player["AVPlayer"]
    Coordinator -. weak delegate .-> Root
    Browser --> Cell["VideoBrowserCell"]

Reference code

Using AVKit in iOS/PlaybackController.swift:30 — the façade reuses the coordinator for a video or creates and registers it once.

func coordinator(for indexPath: IndexPath) -> PlayerViewControllerCoordinator {
    let video = videos[indexPath.row]
    if let playbackItem = playbackItems[video] {
        return playbackItem
    } else {
        let playbackItem = PlayerViewControllerCoordinator(video: video)
        playbackItem.delegate = videoItemDelegate
        playbackItems[video] = playbackItem
        return playbackItem
    }
}

Interpretation

The browser sends presentation requests through PlaybackController rather than constructing players. The registry preserves playback context for each Video, while the coordinator isolates AVKit and UIKit containment rules.

Ownership and state

classDiagram
    ViewController *-- PlaybackController : owns
    PlaybackController *-- PlayerViewControllerCoordinator : caches per Video
    PlayerViewControllerCoordinator *-- AVPlayerViewController : owns while visible
    AVPlayerViewController *-- AVPlayer : retains
    PlayerViewControllerCoordinator *-- Status : mutates
    PlayerViewControllerCoordinator o-- UIViewController : weak fullscreen reference
    PlaybackController o-- CoordinatorDelegate : weak delegate
    VideoBrowserCell --> PlayerViewControllerCoordinator : references while displayed

Ownership evidence

Using AVKit in iOS/PlayerViewControllerCoordinator.swift:27 — the coordinator owns observable playback state but avoids retaining its delegate and full-screen presenter.

weak var delegate: PlayerViewControllerCoordinatorDelegate?
var video: Video
private(set) var status: Status = []
private(set) var playerViewControllerIfLoaded: AVPlayerViewController?
private weak var fullScreenViewController: UIViewController?

Class and protocol design

PlayerViewControllerCoordinatorDelegate is app-defined because the coordinator cannot restore global navigation by itself. AVKit’s own delegate remains implemented directly by the coordinator.

Access control

Reference code

Using AVKit in iOS/PlayerViewControllerCoordinator.swift:243 — private helpers keep resource creation behind coordinator operations.

extension PlayerViewControllerCoordinator {
    private func loadPlayerViewControllerIfNeeded() {
        if playerViewControllerIfLoaded == nil {
            playerViewControllerIfLoaded = AVPlayerViewController()
        }
    }
}

Logic ownership and placement

Design patterns

Main application flow

sequenceDiagram
    actor User
    participant Browser as Video browser
    participant Playback as PlaybackController
    participant Coord as Coordinator
    participant AVKit as AVPlayerViewController
    User->>Browser: Select video
    Browser->>Playback: present or embed index path
    Playback->>Playback: find or create coordinator
    Playback->>Coord: presentFullScreen or embedInline
    Coord->>AVKit: lazily create and attach player
    AVKit-->>Coord: delegate lifecycle events
    Coord-->>Browser: status-visible playback UI

Reference code

Using AVKit in iOS/PlaybackController.swift:49 — public façade methods translate index-path requests into coordinator commands.

func embed(contentForIndexPath indexPath: IndexPath,
           in parentViewController: UIViewController,
           containerView: UIView) {
    coordinator(for: indexPath).embedInline(in: parentViewController,
                                            container: containerView)
}

func present(contentForIndexPath indexPath: IndexPath,
             from presentingViewController: UIViewController) {
    coordinator(for: indexPath).presentFullScreen(from: presentingViewController)
}

Naming conventions

• Role suffixes are explicit: Controller, Coordinator, Delegate, Cell, and FlowLayout.
• Commands describe UI transitions: presentFullScreen, embedInline, restoreFullScreen, and removeFromParentIfNeeded.
• Optional-resource names expose lifecycle: playerViewControllerIfLoaded and loadPlayerViewControllerIfNeeded.
• Boolean-like state uses adjective phrases such as isBeingShown; Status cases name concrete conditions.
• Files generally match their primary type; framework conformances and small private helpers stay beside the coordinated type.

Architecture takeaways

• Give one coordinator sole authority over a framework controller that moves between multiple view hierarchies.
• Cache by domain identity when playback state must survive cell reuse and presentation changes.
• Expose lifecycle state as read-only with private(set) while keeping mutation local.
• Use a weak app delegate only for decisions requiring navigation context outside the coordinator.
• Model overlapping playback conditions with an OptionSet instead of forcing them into one exclusive enum state.

Source map

• Official Apple documentation