Providing an integrated view of your timeline when playing HLS interstitials

At a glance

Project structure

HLSInterstitialDemo/HLSInterstitialDemo/
├── HLSInterstitialDemoApp.swift
├── Menu/
│   ├── Models/Menu.swift
│   ├── ViewModels/
│   └── Views/
├── IntegratedTimeline/
│   ├── Controls/
│   ├── Occupancy/
│   └── IntegratedTimelinePlayerView.swift
├── PlayerState.swift
├── SharePlay/
└── Helpers/

The folders follow features first, then roles within the larger Menu feature. PlayerState.swift sits at the app-feature root because both the custom player UI and SharePlay coordination use it.

Overall architecture

flowchart LR
    App["HLSInterstitialDemoApp"] --> MenuUI["MenuView"]
    MenuUI --> MenuVM["Menu view-model tree"]
    MenuVM --> ItemVM["MenuItemViewModel"]
    ItemVM --> PlayerState
    PlayerState --> AVPlayer
    PlayerState --> Timeline["Integrated timeline"]
    PlayerState --> SharePlay["SharePlayCoordinator"]
    PlayerUI["IntegratedTimelinePlayerView"] --> PlayerState

Reference code

HLSInterstitialDemo/HLSInterstitialDemo/PlayerState.swift:64 — PlayerState builds and retains the playback components (abridged).

private lazy var playerItem: AVPlayerItem = {
    let asset = AVURLAsset(url: menuItem.url)
    let playerItem = AVPlayerItem(asset: asset)
    return playerItem
}()

lazy var player: AVPlayer = {
    let player = AVPlayer(playerItem: self.playerItem)
    player.playbackCoordinator.delegate = playbackCoordinatorDelegate
    return player
}()

PlayerState is an observable presentation model and the AVFoundation boundary. This is directly observed. Calling the structure MVVM is an interpretation supported by the source’s ViewModels folders and view-model names.

Ownership and state

classDiagram
    HLSInterstitialDemoApp *-- MenuViewModel
    MenuViewModel *-- MenuSectionViewModel
    MenuSectionViewModel *-- MenuItemViewModel
    MenuItemViewModel *-- PlayerState : while presented
    PlayerState *-- AVPlayer
    PlayerState *-- AVPlayerInterstitialEventController
    PlayerState --> SharePlayCoordinator : shared

Ownership evidence

HLSInterstitialDemo/HLSInterstitialDemo/Menu/ViewModels/MenuItemViewModel.swift:65 — the selected item creates, retains, and explicitly invalidates its player state (abridged).

func presentPlayer(with videoMetadata: VideoMetadata) {
    Task { @MainActor in
        let playerState = PlayerState(menuItem: self.item, videoMetadata: videoMetadata)
        unsafeSelf.wrappedValue.currentPlayerState = playerState
        let playerView = IntegratedTimelinePlayerView(playerState: playerState)
        ModalPresentationCoordinator.shared.requestPresentation { playerView } onDismiss: {
            playerState.invalidate()
            unsafeSelf.wrappedValue.currentPlayerState = nil
        }
    }
}

Class and protocol design

classDiagram
    class MenuItemViewModelDelegate {
        <<protocol>>
        menuItemViewModelWantsToBePlayed()
    }
    MenuSectionViewModel ..|> MenuItemViewModelDelegate
    MenuItemViewModel --> MenuItemViewModelDelegate : weak delegate
    PlayerCoordinatorDelegate ..|> AVPlayerPlaybackCoordinatorDelegate

Reference code

HLSInterstitialDemo/HLSInterstitialDemo/Menu/ViewModels/MenuItemViewModel.swift:12 — child-to-parent intent is a small class-only protocol.

protocol MenuItemViewModelDelegate: AnyObject {
    func menuItemViewModelWantsToBePlayed(_ itemViewModel: MenuItemViewModel)
}

weak var delegate: MenuItemViewModelDelegate?

The delegate chain keeps selection intent out of SwiftUI views and avoids retaining the parent view-model node.

Access control

HLSInterstitialDemo/HLSInterstitialDemo/Helpers/ModalPresentationCoordinator.swift:18:

@Observable
class ModalPresentationCoordinator {
    static var shared = ModalPresentationCoordinator()
    fileprivate var presentation: ModalPresentation?
}

Logic ownership and placement

Design patterns

Naming conventions

• Types use role suffixes: View, ViewModel, Coordinator, Delegate, and State.
• Methods use commands for intent (presentPlayer, dismissActiveContent, scheduleInterstitialEvents) and make for construction.
• Boolean names use is/should; private sections are grouped with MARK comments.
• Extensions use Type+Additions.swift; feature view files generally match their primary type.

Architecture takeaways

• One PlayerState centralizes AVPlayer, interstitial scheduling, timeline snapshots, and observation lifetimes.
• Menu view models form an ownership tree; weak delegate links carry intent back upward.
• Shared coordinators are reserved for genuinely cross-feature lifecycles: SharePlay and modal presentation.
• The custom timeline UI reads state but does not own AVFoundation configuration.

Source map

• Official Apple documentation