Merge feat/unified-playback-phase-85: unified playbackPhase enum (#85)

Author: superuser404notfound

README.md

@@ -112,6 +112,10 @@ player.$duration
 player.$videoFormat    // .sdr, .hdr10, .hdr10Plus, .dolbyVision, .hlg
 player.$isSeeking      // true until a seek physically lands (programmatic + native scrubs)
 player.$seekTarget     // in-flight seek destination (source-PTS), nil otherwise
+player.$playbackPhase  // unified: .idle/.loading/.playing/.paused/.seeking/.rebuffering/
+                       // .stalled(reconnecting:)/.ended/.error. One source of truth for a status
+                       // spinner; derived from state + isBuffering + isSeeking + source reconnect.
+                       // Prefer this over stitching the raw signals or matching EngineLog text.
 player.$currentAVPlayer // active AVPlayer, re-emitted on every reload (MPNowPlayingSession)
 
 // Time lives on player.clock, a SEPARATE ObservableObject, so the ~10 Hz

Sources/AetherEngine/AetherEngine+Loading.swift

@@ -209,6 +209,9 @@ extension AetherEngine {
                 self.setNativeScrubSeek(inFlight: inFlight, target: target)
             }
         }
+        session.onNetworkPhaseChanged = { [weak self] phase in
+            Task { @MainActor in self?.setReaderNetworkPhase(phase) }
+        }
         // #65: let the producer read AVPlayer's real position off-main when it re-anchors on a backpressure wedge.
         session.currentPlaybackPositionProvider = { [renderedPositionMirror] in renderedPositionMirror.get() }
         // #65 pause false-positive: let the producer read AVPlayer's play intent off-main so its backpressure
@@ -472,15 +475,20 @@ extension AetherEngine {
         // Capture the caller's probe budget (#68) before the detach: loadedOptions is @MainActor-isolated and unreachable inside the closure. Only used on the fallback open (probe absent).
         let probesize = loadedOptions.probesize
         let maxAnalyzeDuration = loadedOptions.maxAnalyzeDuration
+        // Built on the main actor, captured into the detach: surfaces source stall/reconnect to playbackPhase (#85).
+        let networkPhaseSink: @Sendable (ReaderNetworkPhase) -> Void = { [weak self] phase in
+            Task { @MainActor in self?.setReaderNetworkPhase(phase) }
+        }
         try await Task.detached(priority: .userInitiated) {
-            [host, preopenedDemuxer, url, sourceHTTPHeaders, isLive, dvrWindowSeconds, probesize, maxAnalyzeDuration] in
+            [host, preopenedDemuxer, url, sourceHTTPHeaders, isLive, dvrWindowSeconds, probesize, maxAnalyzeDuration, networkPhaseSink] in
             let dem: Demuxer
             if let pre = preopenedDemuxer {
                 dem = pre
             } else {
                 dem = Demuxer()
                 try dem.open(url: url, extraHeaders: sourceHTTPHeaders, profile: .playback.withProbeBudget(probesize: probesize, maxAnalyzeDuration: maxAnalyzeDuration), isLive: isLive)
             }
+            dem.onNetworkPhaseChanged = networkPhaseSink
             try await host.load(
                 demuxer: dem,
                 startPosition: startPosition,
@@ -534,15 +542,20 @@ extension AetherEngine {
         // Caller's probe budget (#68) captured before the detach; only used on the fallback open (probe absent).
         let probesize = loadedOptions.probesize
         let maxAnalyzeDuration = loadedOptions.maxAnalyzeDuration
+        // Built on the main actor, captured into the detach: surfaces source stall/reconnect to playbackPhase (#85).
+        let networkPhaseSink: @Sendable (ReaderNetworkPhase) -> Void = { [weak self] phase in
+            Task { @MainActor in self?.setReaderNetworkPhase(phase) }
+        }
         try await Task.detached(priority: .userInitiated) {
-            [host, preopenedDemuxer, url, sourceHTTPHeaders, probesize, maxAnalyzeDuration] in
+            [host, preopenedDemuxer, url, sourceHTTPHeaders, probesize, maxAnalyzeDuration, networkPhaseSink] in
             let dem: Demuxer
             if let pre = preopenedDemuxer {
                 dem = pre
             } else {
                 dem = Demuxer()
                 try dem.open(url: url, extraHeaders: sourceHTTPHeaders, profile: .playback.withProbeBudget(probesize: probesize, maxAnalyzeDuration: maxAnalyzeDuration))
             }
+            dem.onNetworkPhaseChanged = networkPhaseSink
             try await host.load(
                 demuxer: dem,
                 startPosition: startPosition,

Sources/AetherEngine/AetherEngine.swift

@@ -54,22 +54,55 @@ public final class AetherEngine: ObservableObject {
 
     // MARK: - Public State
 
-    @Published public internal(set) var state: PlaybackState = .idle
+    @Published public internal(set) var state: PlaybackState = .idle {
+        didSet { recomputePlaybackPhase() }
+    }
 
     /// Mid-playback rebuffer flag. `state` stays `.playing` across a rebuffer to avoid icon flicker;
     /// gate on this when you need to distinguish a stall from real playback (AetherEngine#35).
     /// Always false during initial load spin-up (`state == .loading`).
-    @Published public internal(set) var isBuffering: Bool = false
+    @Published public internal(set) var isBuffering: Bool = false {
+        didSet { recomputePlaybackPhase() }
+    }
 
     /// True from seek entry until physical landing, covering both programmatic and native AVKit scrubs.
     /// Unlike `state == .seeking` (optimistically flipped to `.playing`), this spans the real
     /// loopback-HLS landing, which resolves seconds after the call (AetherEngine#38). Paired with `seekTarget`.
-    @Published public internal(set) var isSeeking: Bool = false
+    @Published public internal(set) var isSeeking: Bool = false {
+        didSet { recomputePlaybackPhase() }
+    }
 
     /// Source-PTS seek destination, or nil when idle. Cleared on landing. For native scrubs, set to the
     /// out-of-range segment time AVPlayer requested (AetherEngine#38).
     @Published public internal(set) var seekTarget: Double? = nil
 
+    /// Single source of truth for what playback is doing right now (#85), derived from
+    /// `state` / `isBuffering` / `isSeeking` / the reader network phase. Recomputed on every input change;
+    /// never a parallel state machine. Hosts should observe this instead of stitching the raw signals or
+    /// regex-matching `EngineLog`.
+    @Published public internal(set) var playbackPhase: PlaybackPhase = .idle
+
+    /// Reader source-fetch axis feeding `playbackPhase`. Updated off the demux thread via
+    /// `setReaderNetworkPhase`. `didSet` keeps `playbackPhase` in sync (#85).
+    private var readerStall: ReaderNetworkPhase = .flowing {
+        didSet { recomputePlaybackPhase() }
+    }
+
+    /// Idempotent: assigns `playbackPhase` only when the derived value actually changes, so a flapping
+    /// origin or redundant input write never fires a spurious `objectWillChange`.
+    private func recomputePlaybackPhase() {
+        let next = PlaybackPhase.derive(state: state,
+                                        isBuffering: isBuffering,
+                                        isSeeking: isSeeking,
+                                        stall: readerStall)
+        if playbackPhase != next { playbackPhase = next }
+    }
+
+    /// Main-actor entry point for the demuxer's `@Sendable onNetworkPhaseChanged` callback (#85).
+    func setReaderNetworkPhase(_ phase: ReaderNetworkPhase) {
+        if readerStall != phase { readerStall = phase }
+    }
+
     /// Bumped at every `seek(to:)` entry; a seek finalizes isSeeking only when its generation still matches,
     /// preventing a superseded seek from clobbering a newer one.
     private var seekGeneration: UInt64 = 0
@@ -796,6 +829,7 @@ public final class AetherEngine: ObservableObject {
             : nil
         state = .loading
         isBuffering = false
+        readerStall = .flowing
         clock.currentTime = 0
         clock.bufferedPosition = 0
         nativeClockSeconds = 0
@@ -1873,6 +1907,7 @@ public final class AetherEngine: ObservableObject {
         clock.sourceTime = 0
         clock.bufferedPosition = 0
         isBuffering = false
+        readerStall = .flowing
         // Hard-clear in-flight seek state: late callbacks are dropped by generation guards, but isSeeking
         // must not strand (#38).
         programmaticSeekInFlight = false

Sources/AetherEngine/Demuxer/AVIOReader.swift

@@ -13,6 +13,18 @@ import Libavutil
 ///
 /// AVIO callbacks run on the demux queue; prefetch/delivery on background queues.
 /// Shared state protected by locks.
+
+/// Dedupes `ReaderNetworkPhase` emissions so a flapping origin does not spam the callback (#85).
+/// Mutated only on the demux thread (the read loop), so it needs no locking.
+struct NetworkPhaseGate {
+    private var last: ReaderNetworkPhase = .flowing
+    mutating func shouldEmit(_ next: ReaderNetworkPhase) -> Bool {
+        guard next != last else { return false }
+        last = next
+        return true
+    }
+}
+
 final class AVIOReader: AVIOProvider, @unchecked Sendable {
 
     private let url: URL
@@ -36,6 +48,21 @@ final class AVIOReader: AVIOProvider, @unchecked Sendable {
     private var position: Int64 = 0
     private var fileSize: Int64 = -1
 
+    /// Typed source-fetch network phase, pushed on every stall/reconnect/recovery transition (#85).
+    /// Mirrors `HLSVideoEngine.onSeekStateChanged`. `@Sendable`: invoked from the demux thread, the
+    /// consumer hops to the main actor. Set only on the MAIN playback reader, never the subtitle side reader.
+    var onNetworkPhaseChanged: (@Sendable (ReaderNetworkPhase) -> Void)?
+
+    /// Demux-thread-only dedupe for `onNetworkPhaseChanged`.
+    private var networkPhaseGate = NetworkPhaseGate()
+
+    /// Emit a phase transition through the gate (demux thread only).
+    private func emitNetworkPhase(_ phase: ReaderNetworkPhase) {
+        if networkPhaseGate.shouldEmit(phase) {
+            onNetworkPhaseChanged?(phase)
+        }
+    }
+
     /// Cached CDN URL after redirect resolution; skips proxy hop on subsequent chunks.
     /// Auth-expiry statuses (401/403/404/410) against it invalidate and fall back to
     /// the source URL. See AetherEngine#12.
@@ -710,6 +737,7 @@ final class AVIOReader: AVIOProvider, @unchecked Sendable {
                         totalRead += n
                         unproductiveReconnects = 0
                         rateLimitStreak = 0
+                        emitNetworkPhase(.flowing)   // detour cache served: not stalled (#85)
                         detourTrackSequential(at: curPosition, length: n)
                         continue
                     case .rateLimited(let retryAfter):
@@ -748,6 +776,7 @@ final class AVIOReader: AVIOProvider, @unchecked Sendable {
                 trimWindowLocked()
                 unproductiveReconnects = 0      // real progress
                 rateLimitStreak = 0             // real progress clears the 429 give-up streak (#71)
+                emitNetworkPhase(.flowing)      // recovered: source delivering again (#85)
                 winCond.broadcast()              // window may have shrunk: wake backpressure
                 winCond.unlock()
                 continue
@@ -779,6 +808,7 @@ final class AVIOReader: AVIOProvider, @unchecked Sendable {
                         totalRead += n
                         unproductiveReconnects = 0
                         rateLimitStreak = 0
+                        emitNetworkPhase(.flowing)   // detour cache served: not stalled (#85)
                         detourTrackSequential(at: curPosition, length: n)
                         continue
                     case .rateLimited, .miss:
@@ -800,13 +830,15 @@ final class AVIOReader: AVIOProvider, @unchecked Sendable {
                 if !signaled {
                     if recordReconnectAndShouldGiveUp() {
                         EngineLog.emit("[AVIOReader] Persistent stall gave up at offset \(frontier) (\(unproductiveReconnects) unproductive)\(isLive ? " [live source lost]" : "")", category: .demux)
+                        emitNetworkPhase(.flowing)   // reader is exiting; let state carry the terminal outcome (#85)
                         if isLive {
                             return totalRead > 0 ? Int32(totalRead) : AVERROR_EIO_VALUE
                         }
                         return totalRead > 0 ? Int32(totalRead) : -1
                     }
                     EngineLog.emit("[AVIOReader] Persistent stall at offset \(frontier), reconnecting", category: .demux)
                     lastUnplannedReconnectAt = Date()
+                    emitNetworkPhase(.reconnecting)   // unplanned reconnect now in flight (#85)
                     backoffBeforeReconnect(streak: unproductiveReconnects, retryAfter: 0)
                     startPersistentConnection(at: frontier)
                 }
@@ -824,6 +856,7 @@ final class AVIOReader: AVIOProvider, @unchecked Sendable {
             if giveUp {
                 let streakDesc = isRateLimited ? "\(rateLimitStreak) consecutive 429/503" : "\(unproductiveReconnects) unproductive"
                 EngineLog.emit("[AVIOReader] Persistent reconnect exhausted at offset \(frontier) status=\(status) (\(streakDesc))\(isLive ? " [live source lost]" : "")", category: .demux)
+                emitNetworkPhase(.flowing)   // reader is exiting; let state carry the terminal outcome (#85)
                 if isLive {
                     return totalRead > 0 ? Int32(totalRead) : AVERROR_EIO_VALUE
                 }
@@ -832,6 +865,7 @@ final class AVIOReader: AVIOProvider, @unchecked Sendable {
             let backoffStreak = isRateLimited ? rateLimitStreak : unproductiveReconnects
             EngineLog.emit("[AVIOReader] Persistent conn ended at offset \(frontier) status=\(status), reconnecting (streak=\(backoffStreak) retryAfter=\(retryAfter)s)", category: .demux)
             lastUnplannedReconnectAt = Date()
+            emitNetworkPhase(.reconnecting)   // unplanned reconnect now in flight (#85)
             backoffBeforeReconnect(streak: backoffStreak, retryAfter: retryAfter)
             startPersistentConnection(at: frontier)
         }

Sources/AetherEngine/Demuxer/Demuxer.swift

@@ -105,6 +105,14 @@ public final class Demuxer: @unchecked Sendable {
         (avioProvider as? AVIOReader)?.lastUnplannedReconnectAt
     }
 
+    /// Forwarded to the playback `AVIOReader` so source stall/reconnect transitions reach the engine (#85).
+    /// `didSet` re-forwards so it works whether set before or after `open()`. Set only on the playback
+    /// demuxer; the subtitle side-demuxer leaves it nil so its stalls never move `playbackPhase`. Disc /
+    /// custom providers without an `AVIOReader` simply never emit.
+    var onNetworkPhaseChanged: (@Sendable (ReaderNetworkPhase) -> Void)? {
+        didSet { (avioProvider as? AVIOReader)?.onNetworkPhaseChanged = onNetworkPhaseChanged }
+    }
+
     // MARK: - Disc titles / chapters (#67)
 
     private(set) var discTitles: [DiscTitle] = []
@@ -225,6 +233,7 @@ public final class Demuxer: @unchecked Sendable {
             chunkRequestTimeout: openProfile.avioRequestTimeout,
             chunkMaxRetries: openProfile.avioMaxRetries
         )
+        reader.onNetworkPhaseChanged = onNetworkPhaseChanged
         try openWithProvider(reader, isLive: isLive)
     }
 

Sources/AetherEngine/PlayerState.swift

@@ -31,6 +31,56 @@ public enum PlaybackBackend: String, Sendable, Equatable {
     case audio
 }
 
+/// What playback is doing right now, as one observable (#85). Derived from `state`, `isBuffering`,
+/// `isSeeking`, and the reader network phase, so it can never desync from them. Observe `$playbackPhase`
+/// instead of stitching `state == .loading` + `$isBuffering` + `$isSeeking` together, and instead of
+/// regex-matching `EngineLog` for stall/reconnect, which is no longer necessary.
+///
+/// `.stalled(reconnecting:)` reports a source-connection problem (drop / 429 / 503 backoff) distinct from
+/// `.rebuffering` (a healthy-connection buffer underrun). The associated value is `true` whenever the
+/// reader is retrying; a future "stalled, retries paused" distinction will surface as `false` without
+/// changing the case. Not available on the direct AVPlayer-HLS live path (no demuxer / reader): a reconnect
+/// there reads as `.rebuffering`.
+public enum PlaybackPhase: Sendable, Equatable {
+    case idle
+    case loading
+    case playing
+    case paused
+    case seeking
+    case rebuffering
+    case stalled(reconnecting: Bool)
+    case ended
+    case error(String)
+}
+
+/// Source-fetch network axis feeding `PlaybackPhase` (#85). Binary today; `.reconnecting` covers the
+/// `AVIOReader` stall / drop / backoff loop, `.flowing` covers normal delivery.
+enum ReaderNetworkPhase: Sendable, Equatable {
+    case flowing
+    case reconnecting
+}
+
+extension PlaybackPhase {
+    /// Pure fold of the four playback axes into one phase, with fixed precedence
+    /// (highest first): error > ended > idle > loading > seeking > stalled > rebuffering > playing/paused.
+    static func derive(state: PlaybackState,
+                       isBuffering: Bool,
+                       isSeeking: Bool,
+                       stall: ReaderNetworkPhase) -> PlaybackPhase {
+        switch state {
+        case .error(let message): return .error(message)
+        case .ended:              return .ended
+        case .idle:               return .idle
+        case .loading:            return .loading
+        case .playing, .paused, .seeking:
+            if isSeeking { return .seeking }
+            if stall == .reconnecting { return .stalled(reconnecting: true) }
+            if isBuffering { return .rebuffering }
+            return state == .paused ? .paused : .playing
+        }
+    }
+}
+
 /// Static snapshot of what the current display can present. Single source of truth shared with the host.
 public struct DisplayCapabilities: Sendable, Equatable {
     public let supportsHDR: Bool

Sources/AetherEngine/Video/HLSVideoEngine.swift

@@ -190,6 +190,10 @@ public final class HLSVideoEngine: @unchecked Sendable {
     /// `playlistShiftSeconds` onto the source-PTS `seekTarget`.
     var onSeekStateChanged: (@Sendable (Bool, Double?) -> Void)?
 
+    /// Source stall/reconnect transitions from the main demuxer's `AVIOReader` (#85). Forwarded to
+    /// `demuxer` at every install site (start + live/restart reopen); the side-audio demuxer stays unwired.
+    var onNetworkPhaseChanged: (@Sendable (ReaderNetworkPhase) -> Void)?
+
     /// AVPlayer's rendered (playlist-axis) position, readable off the main actor. Wired by AetherEngine
     /// to a thread-safe mirror of the host clock. Used to re-anchor the producer on AVPlayer's REAL
     /// position when a VOD backpressure wedge breaks (#65).
@@ -392,6 +396,7 @@ public final class HLSVideoEngine: @unchecked Sendable {
             }
         }
         demuxer = dem
+        dem.onNetworkPhaseChanged = onNetworkPhaseChanged   // surface source stall/reconnect to playbackPhase (#85)
 
         let videoIndex = dem.videoStreamIndex
         guard videoIndex >= 0, let videoStream = dem.stream(at: videoIndex) else {
@@ -1443,7 +1448,10 @@ public final class HLSVideoEngine: @unchecked Sendable {
         }
         // #79: install the reopened demuxer only inside the validated section so makeProducer reads it and a
         // concurrent teardown can't race a resurrected demuxer into a torn-down session.
-        if let freshDemuxer { demuxer = freshDemuxer }
+        if let freshDemuxer {
+            demuxer = freshDemuxer
+            freshDemuxer.onNetworkPhaseChanged = onNetworkPhaseChanged   // re-wire stall signal onto the reopened demuxer (#85)
+        }
         do {
             let newProd = try makeProducer(baseIndex: idx)
             producer = newProd