Repository Public
1// Author: Simon-Pierre Boucher — contact@spboucher.ai2// File: Core/Audio/PlaybackController.swift3// Description: Observable playback state and transport: queue, source resolution, next-track preparation, history.4import Foundation5import Observation67public struct PlaybackSnapshot: Codable, Sendable, Equatable {8 public var trackIDs: [String]9 public var index: Int10 public var position: Double11 public var shuffle: Bool12 public var repeatMode: String13}1415/// What the interface talks to: the queue, the transport, and the state to display. It turns tracks into byte16/// sources (through the resolver it is given), drives the engine, keeps the next track prepared, skips what cannot17/// be played offline, and reports each play for the listening history.18@MainActor19@Observable20public final class PlaybackController {21 public typealias Resolver = @Sendable (Track) async throws -> ResolvedSource2223 public private(set) var queue = AudioQueue()24 public private(set) var isPlaying = false25 public private(set) var isBuffering = false26 public private(set) var position: Double = 027 public private(set) var duration: Double = 028 public private(set) var bufferedFraction: Double = 029 public private(set) var info: DecoderInfo?30 public private(set) var sourceKind: SourceKind?31 public private(set) var isRendition = false32 public private(set) var outputSampleRate: Double = 033 public private(set) var message: String?34 public private(set) var settings = EngineSettings()35 /// Bumped whenever the queue or the current item changes (for persistence and Now Playing updates).36 public private(set) var revision = 03738 public var current: QueueItem? { queue.current }39 public var currentTrack: Track? { queue.current?.track }4041 @ObservationIgnored public let engine: AudioEngine42 @ObservationIgnored private var resolver: Resolver43 @ObservationIgnored private var isAvailableOffline: @Sendable (Track) -> Bool44 @ObservationIgnored private var isOnline: @Sendable () -> Bool45 @ObservationIgnored public var onPlayed: (@MainActor (Track, _ listenedMs: Int, _ completed: Bool, SourceKind) -> Void)?46 @ObservationIgnored public var onTrackChanged: (@MainActor () -> Void)?47 @ObservationIgnored private var tokens: [UUID: UUID] = [:] // engine token → queue item id48 @ObservationIgnored private var currentToken: UUID?49 @ObservationIgnored private var preparedToken: UUID?50 @ObservationIgnored private var preparedKind: SourceKind?51 @ObservationIgnored private var preparedRendition = false52 @ObservationIgnored private var loadGeneration = 053 @ObservationIgnored private var listened: Double = 054 @ObservationIgnored private var lastPoll = Date()55 @ObservationIgnored private var consecutiveFailures = 056 @ObservationIgnored private var pollTask: Task<Void, Never>?57 @ObservationIgnored private var eventTask: Task<Void, Never>?5859 public init(engine: AudioEngine = AudioEngine(), resolver: @escaping Resolver = { _ in throw PlaybackError.noFile },60 isAvailableOffline: @escaping @Sendable (Track) -> Bool = { _ in false }, isOnline: @escaping @Sendable () -> Bool = { true }) {61 self.engine = engine; self.resolver = resolver; self.isAvailableOffline = isAvailableOffline; self.isOnline = isOnline62 let events = engine.events()63 eventTask = Task { [weak self] in for await e in events { self?.handle(e) } }64 pollTask = Task { [weak self] in65 while !Task.isCancelled { try? await Task.sleep(nanoseconds: 200_000_000); self?.poll() }66 }67 }6869 /// Points the controller at an account's library (called when a session opens or changes).70 public func configure(resolver: @escaping Resolver, isAvailableOffline: @escaping @Sendable (Track) -> Bool, isOnline: @escaping @Sendable () -> Bool) {71 self.resolver = resolver; self.isAvailableOffline = isAvailableOffline; self.isOnline = isOnline72 }7374 // MARK: Settings7576 public func apply(_ s: EngineSettings) {77 let crossfadeChanged = s.crossfade != settings.crossfade || s.directMode != settings.directMode78 settings = s; engine.apply(s)79 if crossfadeChanged { prepareNext() }80 }81 public func setVolume(_ v: Float) { settings.volume = max(0, min(1, v)); engine.apply(settings) }8283 // MARK: Queue commands8485 public func play(_ tracks: [Track], startAt index: Int = 0, shuffle: Bool? = nil) {86 guard !tracks.isEmpty else { return }87 finishCurrent(completed: false)88 var start = index89 if shuffle == true { start = Int.random(in: 0..<tracks.count) }90 queue.set(tracks, startAt: start, shuffle: shuffle ?? queue.shuffle)91 consecutiveFailures = 092 startCurrent(autoplay: true)93 }94 public func playNext(_ tracks: [Track]) {95 let wasEmpty = queue.isEmpty96 queue.playNext(tracks); bump()97 if wasEmpty { startCurrent(autoplay: true) } else { prepareNext() }98 }99 public func addToQueue(_ tracks: [Track]) {100 let wasEmpty = queue.isEmpty101 queue.append(tracks); bump()102 if wasEmpty { startCurrent(autoplay: true) } else { prepareNext() }103 }104 public func removeFromQueue(_ id: UUID) { queue.remove(id); bump(); prepareNext() }105 public func moveInQueue(from: Int, to: Int) { queue.move(from: from, to: to); bump(); prepareNext() }106 public func clearUpcoming() { queue.clearUpcoming(); bump(); prepareNext() }107 public func jump(to id: UUID) {108 guard id != queue.current?.id else { return }109 finishCurrent(completed: false)110 queue.jump(toItem: id); consecutiveFailures = 0111 startCurrent(autoplay: true)112 }113 public func setShuffle(_ on: Bool) { queue.setShuffle(on); bump(); prepareNext() }114 public func toggleShuffle() { setShuffle(!queue.shuffle) }115 public func setRepeat(_ m: RepeatMode) { queue.repeatMode = m; bump(); prepareNext() }116 public func cycleRepeat() { setRepeat(queue.repeatMode == .off ? .all : queue.repeatMode == .all ? .one : .off) }117 public func refreshTracks(_ tracks: [Track]) { queue.refresh(tracks) }118119 // MARK: Transport120121 public func togglePlay() { isPlaying ? pause() : resume() }122 public func resume() {123 guard queue.current != nil else { return }124 message = nil125 if currentToken == nil { startCurrent(autoplay: true, at: position); return }126 engine.play(); isPlaying = true127 }128 public func pause() { engine.pause(); isPlaying = false }129 public func stop() { finishCurrent(completed: false); engine.stop(); isPlaying = false; currentToken = nil; position = 0 }130131 public func next() {132 guard let i = queue.nextIndex(auto: false) else { return }133 finishCurrent(completed: false)134 queue.jump(to: i); consecutiveFailures = 0135 startCurrent(autoplay: true)136 }137 public func previous() {138 // Like every player: back to the start of the track first, to the previous track when already near the start.139 if position > 3 || queue.previousIndex() == nil { seek(to: 0); return }140 finishCurrent(completed: false)141 queue.jump(to: queue.previousIndex()!); consecutiveFailures = 0142 startCurrent(autoplay: true)143 }144 public func seek(to seconds: Double) {145 let t = max(0, min(seconds, duration > 0 ? duration : seconds))146 position = t147 if currentToken != nil { engine.seek(to: t) }148 }149 public func skip(by delta: Double) { seek(to: position + delta) }150151 // MARK: Persistence152153 public func snapshot() -> PlaybackSnapshot {154 PlaybackSnapshot(trackIDs: queue.items.filter { $0.track.externalFileURL == nil }.map(\.track.id), index: queue.index, position: position, shuffle: queue.shuffle, repeatMode: queue.repeatMode.rawValue)155 }156 /// Restores a saved queue, paused at the saved position. Nothing is fetched until the listener presses play.157 public func restore(_ s: PlaybackSnapshot, tracks: [Track]) {158 guard !tracks.isEmpty else { return }159 queue.set(tracks, startAt: min(s.index, tracks.count - 1), shuffle: false)160 queue.repeatMode = RepeatMode(rawValue: s.repeatMode) ?? .off161 position = s.position; duration = Double(queue.current?.track.durationMs ?? 0) / 1000162 currentToken = nil; isPlaying = false163 bump(); onTrackChanged?()164 }165166 // MARK: Internals167168 private func bump() { revision &+= 1 }169170 private func startCurrent(autoplay: Bool, at start: Double = 0) {171 guard let item = queue.current else { return }172 loadGeneration += 1173 let gen = loadGeneration174 let token = UUID()175 tokens = [token: item.id]; currentToken = token; preparedToken = nil176 engine.cancelNext()177 position = start; duration = Double(item.track.durationMs) / 1000; info = nil; listened = 0; bufferedFraction = 0178 isPlaying = autoplay; isBuffering = autoplay; message = nil179 bump(); onTrackChanged?()180 let resolver = self.resolver181 Task {182 do {183 let r = try await resolver(item.track)184 guard gen == self.loadGeneration else { r.source.cancel(); return }185 self.sourceKind = r.kind; self.isRendition = r.isRendition186 self.engine.load(token: token, source: r.source, typeHint: r.typeHint, gainDB: r.gainDB, startAt: start, autoplay: autoplay)187 } catch {188 guard gen == self.loadGeneration else { return }189 self.failed(describe(error), offline: (error as? PlaybackError) == .notAvailableOffline || APIClient.isOffline(error))190 }191 }192 }193194 private func describe(_ error: Error) -> String {195 switch error {196 case PlaybackError.notAvailableOffline: "Ce titre n’est pas téléchargé : il sera lisible au retour de la connexion."197 case PlaybackError.libraryFolderMissing: "Le dossier de la bibliothèque est indisponible (disque externe débranché ?)."198 case PlaybackError.noFile: "Ce titre n’a pas de fichier lisible."199 case APIError.unauthenticated: "Session expirée : reconnectez-vous pour écouter en continu."200 case APIError.offline: "Serveur injoignable."201 default: AudioEngine.describe(error)202 }203 }204205 /// The first item after the current one that can actually play now (everything when online, downloads only otherwise).206 private func nextPlayableIndex(auto: Bool) -> Int? {207 guard var i = queue.nextIndex(auto: auto) else { return nil }208 if isOnline() { return i }209 var hops = 0210 while hops < queue.items.count {211 if let item = queue.item(at: i), isAvailableOffline(item.track) { return i }212 guard i + 1 < queue.items.count || queue.repeatMode != .off else { return nil }213 i = (i + 1) % queue.items.count214 if i == queue.index { return isAvailableOffline(queue.current!.track) && queue.repeatMode != .off ? i : nil }215 hops += 1216 }217 return nil218 }219220 private func prepareNext() {221 engine.cancelNext(); preparedToken = nil222 guard currentToken != nil, let i = nextPlayableIndex(auto: true), let item = queue.item(at: i) else { return }223 let gen = loadGeneration224 let token = UUID()225 let resolver = self.resolver226 Task {227 guard let r = try? await resolver(item.track) else { return }228 guard gen == self.loadGeneration, self.preparedToken == nil, self.queue.item(at: i)?.id == item.id else { r.source.cancel(); return }229 self.tokens[token] = item.id; self.preparedToken = token; self.preparedKind = r.kind; self.preparedRendition = r.isRendition230 self.engine.prepareNext(token: token, source: r.source, typeHint: r.typeHint, gainDB: r.gainDB)231 }232 }233234 private func finishCurrent(completed: Bool) {235 guard let track = queue.current?.track, currentToken != nil else { return }236 let total = Double(track.durationMs) / 1000237 if listened >= 30 || (total > 0 && listened >= total * 0.5) || completed && listened > 5 {238 onPlayed?(track, Int(listened * 1000), completed, sourceKind ?? .stream)239 }240 listened = 0241 }242243 private func failed(_ text: String, offline: Bool) {244 consecutiveFailures += 1245 message = text246 // Try what follows, as long as something in the queue might play; never loop forever on a dead queue.247 if consecutiveFailures <= min(queue.items.count, 25), let i = nextPlayableIndex(auto: false), i != queue.index {248 queue.jump(to: i)249 startCurrent(autoplay: true)250 message = text251 } else {252 engine.stop(); isPlaying = false; isBuffering = false; currentToken = nil253 }254 }255256 private func handle(_ e: EngineEvent) {257 switch e {258 case .ready(let token, let i):259 guard token == currentToken else { return }260 info = i; duration = i.duration > 0 ? i.duration : duration261 consecutiveFailures = 0262 prepareNext()263 case .advanced(let token):264 guard token == preparedToken, let id = tokens[token] else { return }265 finishCurrent(completed: true)266 queue.jump(toItem: id)267 tokens = [token: id]; currentToken = token; preparedToken = nil268 loadGeneration += 1269 sourceKind = preparedKind; isRendition = preparedRendition270 position = 0; listened = 0; info = nil271 duration = Double(queue.current?.track.durationMs ?? 0) / 1000272 bump(); onTrackChanged?()273 prepareNext()274 case .finished(let token):275 guard token == currentToken else { return }276 finishCurrent(completed: true)277 if let i = nextPlayableIndex(auto: true) {278 queue.jump(to: i); startCurrent(autoplay: true)279 } else {280 // End of the queue: stay on the last track, stopped at its start.281 isPlaying = false; isBuffering = false; currentToken = nil; position = 0282 bump(); onTrackChanged?()283 }284 case .failed(let token, let error, let offline):285 guard token == currentToken else { return }286 failed(error, offline: offline)287 case .outputChanged:288 outputSampleRate = engine.outputSampleRate289 }290 }291292 private func poll() {293 let now = Date(), dt = now.timeIntervalSince(lastPoll); lastPoll = now294 guard currentToken != nil else { return }295 let s = engine.status()296 guard s.token == currentToken else { return }297 if s.info != nil, abs(s.position - position) > 0.05 { position = s.position }298 if s.duration > 0, s.duration != duration { duration = s.duration }299 if s.isBuffering != isBuffering { isBuffering = s.isBuffering }300 if abs(s.bufferedFraction - bufferedFraction) > 0.005 { bufferedFraction = s.bufferedFraction }301 if s.outputSampleRate != outputSampleRate { outputSampleRate = s.outputSampleRate }302 if let i = s.info, i != info { info = i }303 if isPlaying, !s.isBuffering, dt < 1 { listened += dt }304 }305}306