Here\u2019s a bug you might recognise. A user taps \u201cNext episode\u201d while the current one is still loading, and a second later an error screen pops up over the new episode. The error actually belongs to the previous one, which failed late.<\/p>\n
Bugs like this are easy to blame on AVFoundation, but they\u2019re really ordering problems: events arriving after the thing they belong to is gone. Working on OTT apps for iPhone and Apple TV, I\u2019ve settled on a player structure that makes most of them go away, and Swift Concurrency is what makes it practical. Let me walk you through it.<\/p>\n
Because a lot is happening at the same time. During a single playback session, your code is hearing from:<\/p>\n
AVPlayerItem.status<\/code> and AVPlayer.timeControlStatus<\/code><\/li>\n- the periodic time observer<\/li>\n
- asset loading, plus network calls for entitlements, DRM and resume positions<\/li>\n
- the user (play, pause, seek, next episode) and the app lifecycle<\/li>\n<\/ul>\n
None of these wait for each other. That\u2019s how you end up with late errors from the previous item, resume positions saved twice, or a buffering spinner that just never disappears. Which one has bitten you?<\/p>\n
How I split the responsibilities<\/h2>\n
The idea is simple. AVPlayer<\/code> stays on the main actor. Playback state lives in actors. Loading happens off the main thread. Each piece has one isolation domain, so the compiler checks every hop between them for you.<\/p>\n\n\n\nComponent<\/th>\n Isolation<\/th>\n Owns<\/th>\n<\/tr>\n<\/thead>\n \n\nPlayerController<\/code><\/td>\n@MainActor<\/code> class<\/td>\nAVPlayer<\/code> and observer tasks<\/td>\n<\/tr>\n\nAssetLoader<\/code><\/td>\nnonisolated struct<\/td>\n Nothing; returns Sendable results<\/td>\n<\/tr>\n \nPlaybackStateStore<\/code><\/td>\nactor<\/code><\/td>\nThe playback state machine<\/td>\n<\/tr>\n \nResumePositionStore<\/code><\/td>\nactor<\/code><\/td>\nPending resume positions<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\nWhy not put AVPlayer<\/code> in an actor too? It isn\u2019t Sendable<\/code>, AVPlayerLayer<\/code> wants the main thread anyway, and every play()<\/code> would become an await<\/code>.<\/p>\n1. A state actor that ignores stale events<\/h2>\n
This is the piece that fixes the \u201clate error from the previous episode\u201d bug. All state changes go through one actor, and every event carries the ID of the item it belongs to. If the ID doesn\u2019t match the item that\u2019s currently active, the event is simply dropped.<\/p>\n
enum PlaybackState: Equatable, Sendable {\r\n case idle\r\n case loading(itemID: String), playing(itemID: String), paused(itemID: String)\r\n case buffering(itemID: String), ended(itemID: String)\r\n case ready(itemID: String, isLive: Bool)\r\n case failed(itemID: String, message: String)\r\n}\r\n\r\nactor PlaybackStateStore {\r\n private(set) var state: PlaybackState = .idle\r\n private var activeItemID: String?\r\n private var continuations: [UUID: AsyncStream<PlaybackState>.Continuation] = [:]\r\n\r\n func begin(itemID: String) {\r\n activeItemID = itemID\r\n publish(.loading(itemID: itemID))\r\n }\r\n\r\n func apply(_ newState: PlaybackState, for itemID: String) {\r\n guard itemID == activeItemID else { return } \/\/ stale event, drop it\r\n guard newState != state else { return } \/\/ de-duplicate KVO noise\r\n publish(newState)\r\n }\r\n\r\n func updates() -> AsyncStream<PlaybackState> {\r\n let id = UUID()\r\n let (stream, continuation) = AsyncStream.makeStream(\r\n of: PlaybackState.self, bufferingPolicy: .bufferingNewest(1))\r\n continuation.yield(state)\r\n continuations[id] = continuation\r\n continuation.onTermination = { [weak self] _ in\r\n Task { await self?.removeSubscriber(id) }\r\n }\r\n return stream\r\n }\r\n\r\n private func publish(_ newState: PlaybackState) {\r\n state = newState\r\n continuations.values.forEach { $0.yield(newState) }\r\n }\r\n\r\n private func removeSubscriber(_ id: UUID) { continuations[id] = nil }\r\n}<\/pre>\nI use .bufferingNewest(1)<\/code> because the UI only ever cares about the latest state, not a backlog. And there\u2019s no await<\/code> anywhere inside the actor, so a state change can\u2019t be interrupted halfway through.<\/p>\n2. Loading assets (and actually cancelling them)<\/h2>\n
If you\u2019re still using loadValuesAsynchronously(forKeys:)<\/code>, the async AVAsset.load(_:)<\/code> API that arrived in iOS 15 is much nicer. You can load several properties in one call, and you get real errors back.<\/p>\nstruct LoadedAsset: @unchecked Sendable {\r\n let asset: AVURLAsset \/\/ not mutated after loading\r\n let isLive: Bool\r\n}\r\n\r\nenum AssetLoadError: Error { case notPlayable }\r\n\r\nstruct AssetLoader {\r\n func load(url: URL) async throws -> LoadedAsset {\r\n let asset = AVURLAsset(url: url)\r\n return try await withTaskCancellationHandler {\r\n let (isPlayable, duration) = try await asset.load(.isPlayable, .duration)\r\n try Task.checkCancellation()\r\n guard isPlayable else { throw AssetLoadError.notPlayable }\r\n return LoadedAsset(asset: asset, isLive: duration.isIndefinite)\r\n } onCancel: {\r\n asset.cancelLoading()\r\n }\r\n }\r\n}<\/pre>\nThe part I like most is the cancellation handler. When the user switches episodes, the task gets cancelled, cancelLoading()<\/code> runs, and the old playlist stops downloading in the background. Also, an indefinite duration<\/code> means the stream is live, so you know early whether to show a seek bar or a LIVE badge.<\/p>\n3. Putting it together in the controller<\/h2>\n
The controller is a @MainActor<\/code> class that owns the player. Every call to load<\/code> cancels whatever was loading before it.<\/p>\n@MainActor\r\nfinal class PlayerController {\r\n let player = AVPlayer()\r\n private let loader = AssetLoader()\r\n private let stateStore: PlaybackStateStore\r\n private var loadTask: Task<Void, Never>?\r\n private var observers: [Task<Void, Never>] = []\r\n\r\n init(stateStore: PlaybackStateStore) { self.stateStore = stateStore }\r\n\r\n func load(itemID: String, url: URL) {\r\n loadTask?.cancel()\r\n observers.forEach { $0.cancel() }\r\n observers.removeAll()\r\n\r\n loadTask = Task {\r\n await stateStore.begin(itemID: itemID)\r\n do {\r\n let loaded = try await loader.load(url: url)\r\n try Task.checkCancellation() \/\/ a newer load() may have started\r\n player.replaceCurrentItem(with: AVPlayerItem(asset: loaded.asset))\r\n observeTimeControlStatus(itemID: itemID)\r\n await stateStore.apply(.ready(itemID: itemID, isLive: loaded.isLive), for: itemID)\r\n player.play()\r\n } catch is CancellationError {\r\n \/\/ Superseded by a newer load. Nothing to report.\r\n } catch {\r\n await stateStore.apply(.failed(itemID: itemID,\r\n message: error.localizedDescription), for: itemID)\r\n }\r\n }\r\n }\r\n\r\n private func observeTimeControlStatus(itemID: String) {\r\n let store = stateStore\r\n observers.append(Task { [player] in\r\n for await status in player.publisher(for: .timeControlStatus).values {\r\n let state: PlaybackState = switch status {\r\n case .playing: .playing(itemID: itemID)\r\n case .waitingToPlayAtSpecifiedRate: .buffering(itemID: itemID)\r\n default: .paused(itemID: itemID)\r\n }\r\n await store.apply(state, for: itemID)\r\n }\r\n })\r\n }\r\n}<\/pre>\nBecause the Task<\/code> inherits main-actor isolation from the class, I can touch player<\/code> after each await<\/code> without any DispatchQueue.main.async<\/code>. The checkCancellation()<\/code> after loading stops an outdated load from replacing the item the user actually wants. If you\u2019re using SwiftUI, call load<\/code> from .task(id: episode.id)<\/code> and the \u201cnext episode while loading\u201d case is handled for you.<\/p>\n4. The bug actors don\u2019t protect you from<\/h2>\n
This one took me a while to properly understand. An actor makes sure only one call touches its state at a time, but it can\u2019t make sure your assumptions still hold after an await<\/code>. Every await<\/code> inside an actor is a point where other calls can sneak in. Here\u2019s a flush function for saving resume positions that looks perfectly fine:<\/p>\nfunc flush() async { \/\/ BUGGY\r\n guard !pending.isEmpty else { return }\r\n try? await api.save(pending) \/\/ suspends here\r\n pending.removeAll() \/\/ wipes positions recorded during the await\r\n}<\/pre>\nThe trouble starts while api.save<\/code> is waiting on the network. New positions keep coming in, and a second flush can start and send the same batch again. Then, when the first save finally returns, removeAll()<\/code> wipes positions that were never sent. On office Wi-Fi you\u2019ll never see it, which is exactly why it gets past QA.<\/p>\nThe fix is to finish changing state before<\/em> you suspend, and be careful about what you assume after<\/em>:<\/p>\nactor ResumePositionStore {\r\n private var pending: [String: Double] = [:]\r\n private var isFlushing = false\r\n private let api: ProgressAPI\r\n\r\n init(api: ProgressAPI) { self.api = api }\r\n\r\n func record(_ seconds: Double, for itemID: String) {\r\n pending[itemID] = seconds\r\n }\r\n\r\n func flush() async {\r\n guard !isFlushing, !pending.isEmpty else { return }\r\n let batch = pending \/\/ 1. update state before suspending\r\n pending.removeAll()\r\n isFlushing = true\r\n defer { isFlushing = false }\r\n do {\r\n try await api.save(batch) \/\/ 2. suspend\r\n } catch {\r\n pending.merge(batch) { newer, _ in newer } \/\/ 3. keep newer positions\r\n }\r\n }\r\n}<\/pre>\nThese days I read every await<\/code> inside an actor as \u201cstate might be different after this line\u201d. Take a snapshot before, and don\u2019t assume anything after.<\/p>\nA few mistakes to avoid<\/h2>\n\n- Don\u2019t hop into an actor on every frame. Half a second to a second is plenty for a scrubber, and 5\u201310 seconds is fine for resume positions.<\/li>\n
- Swift won\u2019t stop a cancelled task for you. After an
await<\/code>, check for cancellation yourself before you touch the player.<\/li>\n- Cancel your observer tasks when the item changes. Waiting for
deinit<\/code> usually means waiting forever.<\/li>\n- If you move to Swift 6.2 with
NonisolatedNonsendingByDefault<\/code> on, mark AssetLoader.load<\/code> as @concurrent<\/code> (SE-0461<\/a>), otherwise loading will quietly start running on the main actor.<\/li>\n<\/ul>\nConclusion<\/h2>\n
Swift Concurrency won\u2019t make a video player simple. What it does is make the rules something the compiler can check instead of something you have to remember. If you take only three things from this post: keep AVPlayer<\/code> on the main actor, tag every event with its item ID, and be suspicious of every await<\/code> inside an actor. That alone gets rid of most \u201cthis should never happen\u201d bugs.<\/p>\n","protected":false},"excerpt":{"rendered":"Introduction Here\u2019s a bug you might recognise. A user taps \u201cNext episode\u201d while the current one is still loading, and a second later an error screen pops up over the new episode. The error actually belongs to the previous one, which failed late. Bugs like this are easy to blame on AVFoundation, but they\u2019re really […]<\/p>\n","protected":false},"author":2138,"featured_media":0,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"iawp_total_views":2,"footnotes":""},"categories":[3477],"tags":[9078,9074,9076,7521,9077,7964,5963,3116,2715,9075,9073,5460,3531,5534],"class_list":["post-83790","post","type-post","status-publish","format-standard","hentry","category-media-entertainment","tag-actorreentrancy","tag-asyncawait","tag-avfoundation","tag-avplayer","tag-hlsstreaming","tag-iosdevelopment","tag-mobileappdevelopment","tag-ott","tag-swift","tag-swiftactors","tag-swiftconcurrency","tag-swiftui","tag-tvos","tag-videostreaming"],"aioseo_notices":[],"aioseo_head":"\n\t\t\n\t\n\t\n\t\n\t\n\t\n\t\t\n\t\t\n\t\t\n\t\t\n\t\t\n\t\t\n\t\t\n\t\t\n\t\t\n\t\t\n\t\t\n\t\t\n\t\t\n\t\t