Repository Public
1// SP Music iOS2// File: Core/Sources/SPMusicCore/Audio/AudioPlayer.swift3// Description: Audio engine on AVQueuePlayer: streaming, local files, queue, preloading, error recovery.4//5// Author: Simon-Pierre Boucher6// Contact: contact@spboucher.ai78import AVFoundation9import Foundation10import Observation1112/// The audio engine. One AVQueuePlayer plays local files and HTTP streams alike (original files: FLAC, ALAC, AAC,13/// MP3, WAV, AIFF are decoded by the system; nothing is re-encoded by the app). The next track is prepared while the14/// current one plays, so the change of track has no loading pause — and no gap when the system can chain the two.15@MainActor @Observable16public final class AudioPlayer {17 public private(set) var queue = PlaybackQueue()18 /// What the listener asked for (true while buffering before the sound starts).19 public private(set) var isPlaying = false20 public private(set) var isBuffering = false21 public private(set) var position: TimeInterval = 022 public private(set) var duration: TimeInterval = 023 public private(set) var error: PlayerError?24 public private(set) var source: ResolvedSource?25 public var current: Track? { queue.current }2627 @ObservationIgnored public let session: AudioSessionManager28 @ObservationIgnored public let nowPlaying = NowPlayingCenter()29 @ObservationIgnored private let resolver: any AudioSourceResolving30 @ObservationIgnored public let player = AVQueuePlayer()3132 /// A listening session of one track ended (≥ 30 s heard, or played to its end).33 @ObservationIgnored public var onPlayed: (@MainActor (PlayEvent) -> Void)?34 /// Queue, position or modes changed: time to save the playback state.35 @ObservationIgnored public var onStateChanged: (@MainActor () -> Void)?36 @ObservationIgnored public var onToggleFavorite: (@MainActor (Track) -> Void)?37 @ObservationIgnored public var artworkProvider: (@MainActor (String) async -> PlatformImage?)?3839 @ObservationIgnored private var generation = 040 @ObservationIgnored private var currentItem: AVPlayerItem?41 @ObservationIgnored private var preloaded: (item: AVPlayerItem, trackId: String, source: ResolvedSource)?42 @ObservationIgnored private var preloadTask: Task<Void, Never>?43 @ObservationIgnored private var itemObservations: [ObjectIdentifier: NSKeyValueObservation] = [:]44 @ObservationIgnored private var playerObservations: [NSKeyValueObservation] = []45 @ObservationIgnored private var notificationTokens: [any NSObjectProtocol] = []46 @ObservationIgnored private var timeObserver: Any?47 @ObservationIgnored private var pendingSeek: TimeInterval?48 @ObservationIgnored private var triedCompat = false49 @ObservationIgnored private var consecutiveErrors = 050 @ObservationIgnored private var interrupted = false51 @ObservationIgnored private var listened: TimeInterval = 052 @ObservationIgnored private var lastTick: TimeInterval?53 @ObservationIgnored private var startedAt = Date()54 @ObservationIgnored private var lastInfoPush = Date.distantPast5556 public init(resolver: any AudioSourceResolving, session: AudioSessionManager) {57 self.resolver = resolver; self.session = session58 player.automaticallyWaitsToMinimizeStalling = true59 player.actionAtItemEnd = .advance60 #if os(iOS)61 player.allowsExternalPlayback = true62 player.audiovisualBackgroundPlaybackPolicy = .continuesIfPossible63 #endif64 wire()65 }6667 private func wire() {68 playerObservations.append(player.observe(\.timeControlStatus, options: [.new]) { [weak self] _, _ in Task { @MainActor in self?.statusChanged() } })69 timeObserver = player.addPeriodicTimeObserver(forInterval: CMTime(value: 1, timescale: 2), queue: .main) { [weak self] t in70 MainActor.assumeIsolated { self?.tick(t.seconds) }71 }72 let nc = NotificationCenter.default73 notificationTokens.append(nc.addObserver(forName: AVPlayerItem.didPlayToEndTimeNotification, object: nil, queue: .main) { [weak self] n in74 let id = (n.object as? AVPlayerItem).map(ObjectIdentifier.init)75 MainActor.assumeIsolated { self?.itemEnded(id) }76 })77 notificationTokens.append(nc.addObserver(forName: AVPlayerItem.failedToPlayToEndTimeNotification, object: nil, queue: .main) { [weak self] n in78 let id = (n.object as? AVPlayerItem).map(ObjectIdentifier.init)79 MainActor.assumeIsolated { self?.itemFailed(id) }80 })81 session.onInterruptionBegan = { [weak self] in self?.interruptionBegan() }82 session.onInterruptionEnded = { [weak self] resume in self?.interruptionEnded(shouldResume: resume) }83 session.onOutputLost = { [weak self] in self?.pause() }84 session.onMediaServicesReset = { [weak self] in self?.mediaServicesReset() }85 nowPlaying.register(.init(play: { [weak self] in self?.play() }, pause: { [weak self] in self?.pause() }, toggle: { [weak self] in self?.toggle() },86 next: { [weak self] in self?.next() }, previous: { [weak self] in self?.previous() }, seek: { [weak self] t in self?.seek(to: t) },87 toggleFavorite: { [weak self] in if let s = self, let t = s.current { s.onToggleFavorite?(t) } }))88 }8990 // MARK: Commands9192 public func play(_ tracks: [Track], startAt index: Int = 0, shuffle: Bool? = nil, pickRandomStart: Bool = false) {93 guard !tracks.isEmpty else { return }94 finishListening(completed: false)95 consecutiveErrors = 096 queue.replace(tracks, startAt: index, shuffle: shuffle, pickRandomStart: pickRandomStart)97 load(play: true)98 }99100 /// Puts a saved queue back, paused at its position: nothing is fetched until the listener presses play.101 public func restore(tracks: [Track], index: Int, position: TimeInterval, shuffle: Bool, repeatMode: RepeatMode) {102 guard queue.isEmpty, !tracks.isEmpty else { return }103 queue.restore(tracks, index: index, shuffle: shuffle, repeatMode: repeatMode)104 self.position = position; duration = queue.current?.duration ?? 0; pendingSeek = position > 1 ? position : nil105 publishTrack()106 }107108 public func toggle() { isPlaying ? pause() : play() }109110 public func play() {111 guard queue.current != nil else { return }112 if currentItem == nil { load(play: true, at: pendingSeek ?? position); return }113 if error != nil { retry(); return }114 isPlaying = true; interrupted = false115 session.activate()116 player.play()117 pushProgress(force: true)118 onStateChanged?()119 }120121 public func pause() {122 isPlaying = false; isBuffering = false123 player.pause()124 pushProgress(force: true)125 onStateChanged?()126 }127128 public func next() {129 consecutiveErrors = 0130 finishListening(completed: false)131 if queue.advance(auto: false) == .moved { load(play: true) }132 }133134 public func previous() {135 switch queue.previous(position: position) {136 case .moved: finishListening(completed: false); load(play: true)137 case .restartCurrent: seek(to: 0)138 default: break139 }140 }141142 public func jump(to index: Int) {143 consecutiveErrors = 0144 finishListening(completed: false)145 if queue.jump(to: index) == .moved { load(play: true) }146 }147148 public func seek(to seconds: TimeInterval) {149 let t = max(0, min(seconds, duration > 0 ? duration - 0.25 : seconds))150 position = t151 lastTick = nil152 guard let item = currentItem, item.status == .readyToPlay else { pendingSeek = t; pushProgress(force: true); return }153 player.seek(to: CMTime(seconds: t, preferredTimescale: 1000), toleranceBefore: .zero, toleranceAfter: .zero) { [weak self] _ in154 Task { @MainActor in self?.pushProgress(force: true) }155 }156 }157158 public func playNext(_ tracks: [Track]) {159 let wasEmpty = queue.isEmpty160 queue.playNext(tracks)161 if wasEmpty { load(play: true) } else { queueEdited() }162 }163 public func addToQueue(_ tracks: [Track]) {164 let wasEmpty = queue.isEmpty165 queue.append(tracks)166 if wasEmpty { load(play: false) } else { queueEdited() }167 }168 public func remove(at index: Int) {169 if queue.remove(at: index) { finishListening(completed: false); if queue.isEmpty { stop() } else { load(play: isPlaying) } } else { queueEdited() }170 }171 public func move(from: Int, to: Int) { queue.move(from: from, to: to); queueEdited() }172 public func clearUpcoming() { queue.clearUpcoming(); queueEdited() }173 public func setShuffle(_ on: Bool) { queue.setShuffle(on); queueEdited() }174 public func cycleRepeat() { queue.cycleRepeat(); queueEdited() }175 public func setRepeat(_ mode: RepeatMode) { queue.repeatMode = mode; queueEdited() }176177 public func retry() {178 consecutiveErrors = 0; triedCompat = false179 load(play: true, at: position)180 }181182 /// The network came back: a stream that broke resumes where it stopped.183 public func networkBecameAvailable() { if error == .network || error == .offline, isPlaying || error == .network { retry() } }184185 /// Favourite toggled or tags changed elsewhere.186 public func refreshTracks(_ fresh: [String: Track]) {187 queue.refresh(with: fresh)188 publishTrack()189 }190191 public func stop() {192 generation += 1193 finishListening(completed: false)194 player.pause(); player.removeAllItems()195 currentItem = nil; dropPreload(); itemObservations.removeAll()196 queue = PlaybackQueue(); isPlaying = false; isBuffering = false; position = 0; duration = 0; error = nil; source = nil197 nowPlaying.setTrack(nil, artwork: nil)198 onStateChanged?()199 }200201 public func snapshot() -> UserSync.Playback {202 UserSync.Playback(queue: queue.tracks.map(\.id), index: queue.index, positionMs: Int(position * 1000), shuffle: queue.shuffle, repeat: queue.repeatMode.rawValue)203 }204205 // MARK: Loading206207 private func load(play: Bool, at offset: TimeInterval = 0, forcing: AudioVariant? = nil) {208 generation += 1209 let gen = generation210 preloadTask?.cancel(); dropPreload()211 guard let track = queue.current else { stop(); return }212 if forcing == nil { triedCompat = false }213 isPlaying = play; isBuffering = play; error = nil214 position = offset; duration = track.duration; pendingSeek = offset > 0.5 ? offset : nil215 listened = 0; lastTick = nil; startedAt = Date()216 player.pause(); player.removeAllItems(); currentItem = nil217 publishTrack()218 onStateChanged?()219 Task {220 let result = await resolver.resolve(track, forcing: forcing)221 guard gen == generation else { return }222 switch result {223 case .failure(let e): fail(e, skip: e == .unavailable)224 case .success(let src): start(track, src, play: play)225 }226 }227 }228229 private func makeItem(_ src: ResolvedSource) -> AVPlayerItem {230 let options: [String: Any] = src.isLocal ? [AVURLAssetPreferPreciseDurationAndTimingKey: true] : [AVURLAssetHTTPCookiesKey: src.cookies]231 let item = AVPlayerItem(asset: AVURLAsset(url: src.url, options: options))232 item.audioTimePitchAlgorithm = .timeDomain233 let id = ObjectIdentifier(item)234 itemObservations[id] = item.observe(\.status, options: [.new]) { [weak self] item, _ in235 let status = item.status236 Task { @MainActor in self?.itemStatusChanged(id, status) }237 }238 return item239 }240241 private func start(_ track: Track, _ src: ResolvedSource, play: Bool) {242 let item = makeItem(src)243 itemObservations = itemObservations.filter { $0.key == ObjectIdentifier(item) }244 currentItem = item; source = src245 player.insert(item, after: nil)246 if play {247 interrupted = false248 if session.activate() { player.play() } else { isPlaying = false; isBuffering = false }249 }250 Log.audio.info("playing \(track.id, privacy: .public) from \(src.isLocal ? "device" : "stream", privacy: .public) (\(src.variant.rawValue, privacy: .public))")251 schedulePreload()252 }253254 /// Prepares the track that follows, so AVQueuePlayer can chain into it.255 private func schedulePreload() {256 preloadTask?.cancel(); dropPreload()257 guard let i = queue.indexAfterCurrent, queue.tracks.count > 1 || queue.repeatMode == .all, let current = currentItem else { return }258 let track = queue.tracks[i]259 let gen = generation260 preloadTask = Task {261 guard case .success(let src) = await resolver.resolve(track, forcing: nil), gen == generation, !Task.isCancelled, currentItem === current else { return }262 let item = makeItem(src)263 guard player.canInsert(item, after: current) else { itemObservations[ObjectIdentifier(item)] = nil; return }264 player.insert(item, after: current)265 preloaded = (item, track.id, src)266 }267 }268269 private func dropPreload() {270 if let p = preloaded { player.remove(p.item); itemObservations[ObjectIdentifier(p.item)] = nil }271 preloaded = nil272 }273274 private func queueEdited() {275 schedulePreload()276 nowPlaying.setQueue(index: queue.index, count: queue.tracks.count)277 onStateChanged?()278 }279280 // MARK: Player events281282 private func itemStatusChanged(_ id: ObjectIdentifier, _ status: AVPlayerItem.Status) {283 guard let item = currentItem, ObjectIdentifier(item) == id else {284 if status == .failed, let p = preloaded, ObjectIdentifier(p.item) == id { dropPreload() } // it will be loaded the normal way when its turn comes285 return286 }287 switch status {288 case .readyToPlay:289 let d = item.duration.seconds290 if d.isFinite, d > 0 { duration = d }291 if let t = pendingSeek {292 pendingSeek = nil293 player.seek(to: CMTime(seconds: t, preferredTimescale: 1000), toleranceBefore: .zero, toleranceAfter: .zero) { [weak self] _ in Task { @MainActor in self?.pushProgress(force: true) } }294 }295 consecutiveErrors = 0296 pushProgress(force: true)297 case .failed: itemFailed(id)298 default: break299 }300 }301302 private func statusChanged() {303 switch player.timeControlStatus {304 case .playing: isBuffering = false; if error == .network { error = nil }305 case .waitingToPlayAtSpecifiedRate: isBuffering = isPlaying306 case .paused:307 isBuffering = false308 // The system paused us (route lost, another app took the output): reflect it, unless a track is loading.309 if isPlaying, !interrupted, currentItem != nil, currentItem?.status == .readyToPlay, player.currentItem != nil, player.rate == 0, !isAtEnd { isPlaying = false; onStateChanged?() }310 @unknown default: break311 }312 pushProgress(force: true)313 }314 private var isAtEnd: Bool { duration > 0 && position >= duration - 1 }315316 private func tick(_ seconds: TimeInterval) {317 guard seconds.isFinite, currentItem != nil, player.currentItem === currentItem else { return }318 if player.timeControlStatus == .playing {319 if let last = lastTick, seconds > last, seconds - last < 2 { listened += seconds - last }320 lastTick = seconds321 } else { lastTick = nil }322 if pendingSeek == nil { position = seconds }323 pushProgress(force: false)324 }325326 private func itemEnded(_ id: ObjectIdentifier?) {327 guard let item = currentItem, ObjectIdentifier(item) == id else { return }328 finishListening(completed: true)329 consecutiveErrors = 0330 switch queue.advance(auto: true) {331 case .restartCurrent: load(play: true)332 case .moved:333 if let p = preloaded, p.trackId == queue.current?.id, player.currentItem === p.item {334 // AVQueuePlayer already moved into the prepared item: adopt it, nothing to load.335 generation += 1336 itemObservations[ObjectIdentifier(item)] = nil337 currentItem = p.item; source = p.source; preloaded = nil338 position = 0; duration = queue.current?.duration ?? 0; listened = 0; lastTick = nil; startedAt = Date(); error = nil; triedCompat = false339 if p.item.status == .readyToPlay, p.item.duration.seconds.isFinite, p.item.duration.seconds > 0 { duration = p.item.duration.seconds }340 publishTrack()341 onStateChanged?()342 schedulePreload()343 } else { load(play: true) }344 case .ended:345 isPlaying = false; isBuffering = false346 pushProgress(force: true); onStateChanged?()347 case .none: break348 }349 }350351 private func itemFailed(_ id: ObjectIdentifier?) {352 guard let item = currentItem, ObjectIdentifier(item) == id, let src = source, let track = queue.current else { return }353 let ns = item.error as NSError?354 Log.audio.error("item failed (\(ns?.domain ?? "?", privacy: .public) \(ns?.code ?? 0))")355 let at = position356 let networkCodes = [NSURLErrorNotConnectedToInternet, NSURLErrorNetworkConnectionLost, NSURLErrorTimedOut, NSURLErrorCannotConnectToHost, NSURLErrorCannotFindHost, NSURLErrorDataNotAllowed, NSURLErrorInternationalRoamingOff]357 if !src.isLocal, ns?.domain == NSURLErrorDomain, networkCodes.contains(ns?.code ?? 0) { fail(.network, skip: false); position = at; return }358 if !src.isLocal, src.variant == .original, !triedCompat, track.compatState != "disabled" {359 // The original could not be read here: fall back to the server's AAC rendition, once, at the same place.360 triedCompat = true361 load(play: isPlaying, at: at, forcing: .compat)362 return363 }364 fail(.unavailable, skip: true)365 }366367 private func fail(_ e: PlayerError, skip: Bool) {368 error = e; isBuffering = false369 player.pause()370 let wanted = isPlaying371 if e != .network { isPlaying = false }372 pushProgress(force: true)373 // Unattended playback steps over a broken track, but never loops through a broken queue.374 consecutiveErrors += 1375 if skip, wanted, consecutiveErrors <= 2, queue.indexAfterCurrent != nil, let id = queue.current?.id {376 Task { [weak self] in377 try? await Task.sleep(for: .seconds(1.5))378 guard let self, self.queue.current?.id == id, self.error != nil else { return }379 if self.queue.advance(auto: false) == .moved { self.load(play: true) }380 }381 }382 onStateChanged?()383 }384385 // MARK: Interruptions386387 private func interruptionBegan() {388 // A phone call, an alarm, Siri: the system has already silenced us. Remember whether to come back.389 interrupted = isPlaying390 isBuffering = false391 pushProgress(force: true)392 }393 private func interruptionEnded(shouldResume: Bool) {394 guard interrupted else { return }395 interrupted = false396 if shouldResume, isPlaying, session.activate() { player.play() } else { isPlaying = false }397 pushProgress(force: true)398 onStateChanged?()399 }400 private func mediaServicesReset() {401 let was = isPlaying, at = position402 session.configure()403 if queue.current != nil { load(play: was, at: at) }404 }405406 // MARK: History, system info407408 private func finishListening(completed: Bool) {409 defer { listened = 0; lastTick = nil }410 guard let t = queue.current, let src = source, completed || listened >= 30 else { return }411 onPlayed?(PlayEvent(id: UUID().uuidString.lowercased(), trackId: t.id, playedAt: startedAt, listenedMs: Int(listened * 1000), completed: completed, source: src.isLocal ? "local" : "stream"))412 }413414 private func publishTrack() {415 let t = queue.current416 nowPlaying.setTrack(t, artwork: nil)417 nowPlaying.setQueue(index: queue.index, count: queue.tracks.count)418 pushProgress(force: true)419 guard let t, let art = t.artworkId, let provider = artworkProvider else { return }420 Task {421 guard let image = await provider(art), queue.current?.id == t.id else { return }422 nowPlaying.setTrack(queue.current, artwork: image)423 }424 }425426 private func pushProgress(force: Bool) {427 // The system extrapolates the elapsed time from the rate: it only needs corrections now and then.428 guard force || Date().timeIntervalSince(lastInfoPush) > 5 else { return }429 lastInfoPush = Date()430 nowPlaying.setProgress(position: position, duration: duration, playing: isPlaying && !isBuffering && error == nil && !interrupted)431 }432}433