Using AVFoundation to play and persist HTTP live streams

At a glance

Project structure

HLSCatalog/
├── AssetListTableViewController.swift
├── AssetListTableViewCell.swift
├── Managers/
│   ├── AssetListManager.swift
│   ├── AssetPersistenceManager.swift
│   ├── AssetPlaybackManager.swift
│   └── StreamListManager.swift
├── Model/
│   ├── Asset.swift
│   └── Stream.swift
├── PerfMeasurements.swift
├── Streams.plist
└── Base.lproj/Main.storyboard

The architecture is singleton-centric and event-driven. It is an observed source characteristic, not a recommendation to make all playback services global.

Overall architecture

flowchart LR
    UI["AssetListTableViewController"] --> List["AssetListManager.shared"]
    UI --> Playback["AssetPlaybackManager.shared"]
    UI --> Persist["AssetPersistenceManager.shared"]
    List --> Catalog["StreamListManager.shared"]
    List --> Persist
    Persist --> Download["AVAssetDownloadURLSession"]
    Playback --> Player["AVPlayer"]
    Persist --> Events["NotificationCenter"]
    Events --> UI
    Playback --> UI

Reference code

HLSCatalog/AssetListTableViewController.swift:87 — the controller dispatches download state transitions to the persistence manager (abridged).

let downloadState = AssetPersistenceManager.sharedManager.downloadState(for: asset)

switch downloadState {
case .notDownloaded:
    try await AssetPersistenceManager.sharedManager.downloadStream(for: asset)
case .downloading:
    AssetPersistenceManager.sharedManager.cancelDownload(for: asset)
case .downloaded:
    AssetPersistenceManager.sharedManager.deleteAsset(asset)
}

The controller handles presentation and user choice. The persistence manager owns the actual background tasks, maps, bookmarks, and notifications.

Ownership and state

classDiagram
    AssetPersistenceManager *-- AVAssetDownloadURLSession
    AssetPersistenceManager *-- AVAssetDownloadTask : active map
    AssetPlaybackManager *-- AVPlayer
    AssetPlaybackManager *-- AVPlayerItem
    AssetListManager *-- Asset : catalog list
    AssetListTableViewController --> AssetPlaybackManager : weak delegate target
    AssetListTableViewController --> AssetPersistenceManager : shared use

Ownership evidence

HLSCatalog/Managers/AssetPersistenceManager.swift:17 — singleton and task-state ownership.

class AssetPersistenceManager: NSObject {
    static let sharedManager = AssetPersistenceManager()
    private var didRestorePersistenceManager = false
    fileprivate var assetDownloadURLSession: AVAssetDownloadURLSession!
    fileprivate var activeDownloadsMap = [AVAssetDownloadTask: Asset]()
    fileprivate var willDownloadToUrlMap = [AVAssetDownloadTask: URL]()
    fileprivate var progressObservers: [NSKeyValueObservation] = []
    override private init() { /* background session setup */ }
}

Class and protocol design

classDiagram
    class AssetPlaybackDelegate {
        <<protocol>>
        playerReadyToPlay()
        playerCurrentItemDidChange()
    }
    AssetListTableViewController ..|> AssetPlaybackDelegate
    AssetPlaybackManager --> AssetPlaybackDelegate : weak delegate
    AssetPersistenceManager ..|> AVAssetDownloadDelegate

Reference code

HLSCatalog/Managers/AssetPlaybackManager.swift:165 — a narrow player-to-presentation protocol.

protocol AssetPlaybackDelegate: AnyObject {
    func streamPlaybackManager(_ streamPlaybackManager: AssetPlaybackManager,
                               playerReadyToPlay player: AVPlayer)
    func streamPlaybackManager(_ streamPlaybackManager: AssetPlaybackManager,
                               playerCurrentItemDidChange player: AVPlayer)
}

Delegate callbacks are used for directed playback events. Broadcast download/list changes use named notifications because several cells/controllers may observe them.

Access control

HLSCatalog/Managers/AssetPersistenceManager.swift:255 shows why fileprivate is used:

extension AssetPersistenceManager: AVAssetDownloadDelegate {
    func urlSession(_ session: URLSession,
                    assetDownloadTask: AVAssetDownloadTask,
                    willDownloadTo location: URL) {
        willDownloadToUrlMap[assetDownloadTask] = location
    }
}

Logic ownership and placement

Design patterns

Naming conventions

• Singleton types use Manager and instances use sharedManager or shared.
• Event names describe completed state changes (DidRestoreState, DidLoad, StateChanged).
• Delegate methods include the source manager as their first argument.
• Asset and Stream are domain nouns; AVFoundation implementation types stay in managers.

Architecture takeaways

• Match background-download session lifetime with a stable owner that can restore tasks.
• Use fileprivate when a same-file protocol extension genuinely needs internal state.
• Separate asset catalog construction, persistence, and playback even in a small UIKit app.
• The source mixes weak delegates, notifications, and KVO based on event cardinality and framework API style.

Source map

• Official Apple documentation