Merge feat/sw-background-audio: SW-path background audio (iOS)

Keep audio playing when the iOS app backgrounds during software-decoded
(VP9 / AV1-without-HW / etc.) playback. The combined demux loop drops video
and paces on the audio renderer while backgroundAudioOnly is set; the engine
routes the SW host to audio-only on background-enter and resumes video on
foreground. Verified headless via aetherctl bgaudio + unit tests + iOS/tvOS builds.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: superuser404notfound

Sources/AetherEngine/AetherEngine+BackgroundAudioTestHooks.swift

@@ -0,0 +1,26 @@
+#if DEBUG
+import Foundation
+
+// Test-only hooks for the aetherctl `bgaudio` harness. The SW-path background-audio keepalive is normally
+// driven by the iOS app lifecycle (UIApplication.didEnterBackground), which does not exist on macOS, so the
+// CLI toggles it directly. DEBUG-gated: absent from Release builds, so this is never shipped API.
+extension AetherEngine {
+
+    /// Enter / leave SW-path background-audio-only. No-op when the active backend is not the software host.
+    @MainActor
+    public func setSoftwareBackgroundAudioOnlyForTesting(_ on: Bool) {
+        if on {
+            softwareHost?.enterBackgroundAudioOnly()
+        } else {
+            softwareHost?.exitBackgroundAudioOnly()
+        }
+    }
+
+    /// Count of video frames the SW host has enqueued. Flat while background-audio-only drops video; rises
+    /// again on foreground return. nil when the active backend is not the software host.
+    @MainActor
+    public var softwareVideoFramesEnqueuedForTesting: Int? {
+        softwareHost?.framesEnqueued
+    }
+}
+#endif

Sources/AetherEngine/AetherEngine.swift

@@ -174,6 +174,27 @@ public final class AetherEngine: ObservableObject {
         enabled && (pipActive || state == .playing)
     }
 
+    /// What to do with the active video pipeline when the app enters the background. Pure so the lifecycle
+    /// policy is unit-testable. Mirrors the spirit of the native keepalive onto the software path.
+    enum BackgroundAction: Equatable {
+        case doNothing               // audio backend, or native keepalive: leave the running session alone
+        case enterSoftwareAudioOnly  // SW host kept alive: drop video in the demux loop, keep feeding audio
+        case teardownVideo           // release the video pipeline before idle suspension
+    }
+
+    /// - keepVideoAlive: result of shouldKeepVideoAlive. Pass false on tvOS (the wedge-safe unconditional teardown).
+    nonisolated static func backgroundAction(
+        isAudioBackend: Bool,
+        hasSoftwareHost: Bool,
+        keepVideoAlive: Bool,
+        state: PlaybackState
+    ) -> BackgroundAction {
+        if isAudioBackend { return .doNothing }
+        if keepVideoAlive { return hasSoftwareHost ? .enterSoftwareAudioOnly : .doNothing }
+        guard state == .playing || state == .paused else { return .doNothing }
+        return .teardownVideo
+    }
+
     /// 1 Hz diagnostics sampler. Separate ObservableObject for the same reason as `clock`: per-sample
     /// objectWillChange would re-render every engine-observing view (AetherEngine#29 follow-up).
     /// Observe only in stats overlays.
@@ -1229,7 +1250,7 @@ public final class AetherEngine: ObservableObject {
         #if os(iOS)
         // Paused while backgrounded with no PiP: the app will idle-suspend, so release the video pipeline
         // now (wedge-safe, mirrors the unconditional background teardown). Audio backends are already spared.
-        if isBackgrounded && !pictureInPictureActive && !audioAVPlayerActive && audioHost == nil {
+        if isBackgrounded && !pictureInPictureActive && !audioAVPlayerActive && audioHost == nil && softwareHost == nil {
             Task { @MainActor in await self.teardownVideoForBackground() }
         }
         #endif
@@ -1913,18 +1934,28 @@ public final class AetherEngine: ObservableObject {
                 guard let self = self else { return }
                 #if os(iOS)
                 self.isBackgrounded = true
-                #endif
-                if self.audioAVPlayerActive || self.audioHost != nil { return }
-                #if os(iOS)
                 // Keep the video pipeline alive for PiP / background audio while the app stays running.
                 // Wedge-safe: a pause while backgrounded tears down via pause() below, so nothing crosses
                 // an idle suspension. tvOS keeps the unconditional teardown.
-                if Self.shouldKeepVideoAlive(enabled: self.backgroundPlaybackEnabled,
-                                             pipActive: self.pictureInPictureActive,
-                                             state: self.state) { return }
+                let keepAlive = Self.shouldKeepVideoAlive(enabled: self.backgroundPlaybackEnabled,
+                                                          pipActive: self.pictureInPictureActive,
+                                                          state: self.state)
+                #else
+                let keepAlive = false  // tvOS: wedge-safe unconditional teardown
                 #endif
-                guard self.state == .playing || self.state == .paused else { return }
-                await self.teardownVideoForBackground()
+                switch Self.backgroundAction(
+                    isAudioBackend: self.audioAVPlayerActive || self.audioHost != nil,
+                    hasSoftwareHost: self.softwareHost != nil,
+                    keepVideoAlive: keepAlive,
+                    state: self.state
+                ) {
+                case .doNothing:
+                    return
+                case .enterSoftwareAudioOnly:
+                    self.softwareHost?.enterBackgroundAudioOnly()
+                case .teardownVideo:
+                    await self.teardownVideoForBackground()
+                }
             }
         }
         lifecycleObservers.append(bgObserver)
@@ -1933,7 +1964,11 @@ public final class AetherEngine: ObservableObject {
             forName: UIApplication.didBecomeActiveNotification,
             object: nil, queue: .main
         ) { [weak self] _ in
-            Task { @MainActor in self?.isBackgrounded = false }
+            Task { @MainActor in
+                guard let self else { return }
+                self.softwareHost?.exitBackgroundAudioOnly()
+                self.isBackgrounded = false
+            }
         }
         lifecycleObservers.append(fgObserver)
         #endif

Sources/AetherEngine/Audio/AudioOutput.swift

@@ -109,6 +109,13 @@ final class AudioOutput: @unchecked Sendable {
         return t.isFinite ? t : 0
     }
 
+    /// Whether the audio renderer can accept more samples. The combined demux loop normally paces on the
+    /// video renderer; in background-audio-only mode (video dropped) it paces on this instead, so it does
+    /// not buffer the rest of the file unbounded.
+    var isReadyForMoreMediaData: Bool {
+        renderer.isReadyForMoreMediaData
+    }
+
     /// Flush the audio renderer (call on seek).
     func flush() {
         lock.lock()

Sources/AetherEngine/Native/SoftwarePlaybackHost.swift

@@ -220,6 +220,20 @@ final class SoftwarePlaybackHost {
         }
     }
 
+    /// Set by the engine on background-enter (iOS keepalive) and cleared on foreground. While true the
+    /// combined demux loop drops video packets and paces on the audio renderer, so audio keeps playing in
+    /// the background. The setter broadcasts the demux condition so a parked loop re-evaluates immediately.
+    nonisolated(unsafe) private var _backgroundAudioOnly = false
+    nonisolated var backgroundAudioOnly: Bool {
+        get { flagsLock.lock(); defer { flagsLock.unlock() }; return _backgroundAudioOnly }
+        set {
+            flagsLock.lock(); _backgroundAudioOnly = newValue; flagsLock.unlock()
+            demuxCondition.lock()
+            demuxCondition.broadcast()
+            demuxCondition.unlock()
+        }
+    }
+
     // MARK: - Init
 
     init() {
@@ -391,6 +405,22 @@ final class SoftwarePlaybackHost {
         isPlaying = false
     }
 
+    /// Background-enter (iOS keepalive): keep audio flowing, stop feeding video. The demux loop reads the flag.
+    func enterBackgroundAudioOnly() {
+        backgroundAudioOnly = true
+    }
+
+    /// Foreground return: resume video. Flush the video decoder + renderer (NOT audio) so video resyncs at the
+    /// next keyframe; the synchronizer is already at the audio time, so the keyframe presents promptly. Order
+    /// matters: while backgroundAudioOnly is still true the loop drops video and never touches videoDecoder /
+    /// renderer, so flushing here from the main actor cannot race the demux queue. Clear the flag last.
+    func exitBackgroundAudioOnly() {
+        guard backgroundAudioOnly else { return }
+        videoDecoder.flush()
+        renderer.flush()
+        backgroundAudioOnly = false
+    }
+
     func setRate(_ newRate: Float) {
         lastRate = newRate
         audioOutput?.setRate(newRate)
@@ -602,6 +632,9 @@ final class SoftwarePlaybackHost {
         let getSeekGeneration: @Sendable () -> UInt64 = { [weak self] in
             self?.seekGeneration ?? 0
         }
+        let getBackgroundAudioOnly: @Sendable () -> Bool = { [weak self] in
+            self?.backgroundAudioOnly ?? false
+        }
 
         if liveSession, let ring {
             let readCursor: @Sendable () -> Int = { [weak self] in
@@ -683,6 +716,7 @@ final class SoftwarePlaybackHost {
                 clockArmed: getClockArmed,
                 markClockArmed: setClockArmed,
                 seekGeneration: getSeekGeneration,
+                backgroundAudioOnly: getBackgroundAudioOnly,
                 onError: onError,
                 onEnd: onEnd
             )
@@ -963,6 +997,7 @@ final class SoftwarePlaybackHost {
         clockArmed: @Sendable () -> Bool,
         markClockArmed: @Sendable () -> Void,
         seekGeneration: @Sendable () -> UInt64,
+        backgroundAudioOnly: @Sendable () -> Bool,
         onError: @Sendable (String) -> Void,
         onEnd: @Sendable () -> Void
     ) {
@@ -1089,8 +1124,14 @@ final class SoftwarePlaybackHost {
             }
 
             if streamIdx == videoStreamIndex {
+                // Background audio-only: drop video, don't gate on the non-draining display layer.
+                if backgroundAudioOnly() {
+                    av_packet_unref(packet)
+                    av_packet_free_safe(packet)
+                    continue
+                }
                 // Back-pressure via SampleBufferRenderer.isReadyForMoreMediaData (not the deprecated layer property). Park on condition while paused to avoid 200 Hz CPU spin.
-                while !renderer.isReadyForMoreMediaData && !stopRequested() {
+                while !renderer.isReadyForMoreMediaData && !stopRequested() && !backgroundAudioOnly() {
                     if !isPlaying() {
                         condition.lock()
                         while !isPlaying() && !stopRequested() {
@@ -1101,6 +1142,12 @@ final class SoftwarePlaybackHost {
                         Thread.sleep(forTimeInterval: 0.005)
                     }
                 }
+                // Entered background while parked on back-pressure: drop this frame.
+                if backgroundAudioOnly() {
+                    av_packet_unref(packet)
+                    av_packet_free_safe(packet)
+                    continue
+                }
                 if stopRequested() {
                     av_packet_unref(packet)
                     av_packet_free_safe(packet)
@@ -1120,6 +1167,26 @@ final class SoftwarePlaybackHost {
                     markClockArmed()
                 }
             } else if streamIdx == audioStreamIndex, let aDec = audioDecoder, let aOut = audioOutput {
+                // Background audio-only: the video gate is bypassed, so pace on the audio renderer to avoid
+                // buffering the rest of the file. Park on condition while paused (same shape as the video gate).
+                if backgroundAudioOnly() {
+                    while !aOut.isReadyForMoreMediaData && !stopRequested() && backgroundAudioOnly() {
+                        if !isPlaying() {
+                            condition.lock()
+                            while !isPlaying() && !stopRequested() {
+                                _ = condition.wait(until: Date(timeIntervalSinceNow: 0.5))
+                            }
+                            condition.unlock()
+                        } else {
+                            Thread.sleep(forTimeInterval: 0.005)
+                        }
+                    }
+                    if stopRequested() {
+                        av_packet_unref(packet)
+                        av_packet_free_safe(packet)
+                        break
+                    }
+                }
                 audioPacketsSeen += 1
                 let buffers = aDec.decode(packet: packet)
                 if !buffers.isEmpty { audioBuffersProduced = true }

Sources/aetherctl/BackgroundAudioCmd.swift

@@ -0,0 +1,111 @@
+import Foundation
+import AetherEngine
+
+// MARK: - bgaudio
+
+/// Drive a software-path source through the full engine, then toggle the SW-path background-audio-only flag
+/// (the macOS stand-in for the iOS background lifecycle) and verify audio keeps advancing while video is
+/// dropped, then resumes on foreground return. Exercises the real runDemuxLoop background branch headless.
+func runBackgroundAudio(url: URL, fgSeconds: Double, bgSeconds: Double) -> Int32 {
+    print("aetherctl bgaudio: \(url.absoluteString) (fg=\(fgSeconds)s bg=\(bgSeconds)s)")
+    // Must use CFRunLoopRun, not a blocking semaphore: AetherEngine is @MainActor, so parking the main thread
+    // would deadlock the executor. The run loop also lets the host's time timer + Combine sinks fire.
+    let box = UncheckedBox<Int32?>(nil)
+    Task { @MainActor in
+        box.value = await backgroundAudioTest(url: url, fgSeconds: fgSeconds, bgSeconds: bgSeconds)
+        CFRunLoopStop(CFRunLoopGetMain())
+    }
+    CFRunLoopRun()
+    return box.value ?? 1
+}
+
+@MainActor
+private func backgroundAudioTest(url: URL, fgSeconds: Double, bgSeconds: Double) async -> Int32 {
+    let engine: AetherEngine
+    do {
+        engine = try AetherEngine()
+    } catch {
+        print("engine init failed: \(error.localizedDescription)")
+        return 1
+    }
+    do {
+        try await engine.load(url: url)
+    } catch {
+        print("load failed: \(error.localizedDescription)")
+        return 1
+    }
+    let backend = engine.playbackBackend
+    print("backend=\(backend.rawValue) duration=\(String(format: "%.1f", engine.duration))s")
+    guard backend == .software else {
+        print("FAIL: expected backend .software, got \(backend.rawValue) (source did not route to the SW path)")
+        return 1
+    }
+    engine.play()
+
+    func vframes() -> Int { engine.softwareVideoFramesEnqueuedForTesting ?? 0 }
+    func sample(_ phase: String) {
+        let fp = physFootprintBytes()
+        print(String(format: "  [%@] clock=%.2fs vframes=%d footprint=%.1fMB",
+                     phase, engine.currentTime, vframes(), Double(fp) / 1_048_576))
+    }
+    func tickFor(_ seconds: Double, phase: String) async {
+        let ticks = max(1, Int(seconds * 2))
+        for _ in 0..<ticks {
+            try? await Task.sleep(nanoseconds: 500_000_000)
+            sample(phase)
+        }
+    }
+
+    // Phase 1: foreground baseline (video gate active).
+    print("--- foreground (video-gated) ---")
+    await tickFor(fgSeconds, phase: "FG")
+    let clockBeforeBg = engine.currentTime
+    let vfBeforeBg = vframes()
+    let fpBeforeBg = physFootprintBytes()
+
+    // Phase 2: background-audio-only (video dropped, pace on audio renderer).
+    print("--- background-audio-only (video dropped, pace on audio) ---")
+    engine.setSoftwareBackgroundAudioOnlyForTesting(true)
+    await tickFor(bgSeconds, phase: "BG")
+    let clockAfterBg = engine.currentTime
+    let vfAfterBg = vframes()
+    let fpAfterBg = physFootprintBytes()
+
+    // Phase 3: foreground again (video resumes at next keyframe).
+    print("--- foreground again (video resumes) ---")
+    engine.setSoftwareBackgroundAudioOnlyForTesting(false)
+    await tickFor(fgSeconds, phase: "FG2")
+    let vfAfterFg2 = vframes()
+
+    engine.stop()
+
+    let bgClockDelta = clockAfterBg - clockBeforeBg
+    let bgVideoDelta = vfAfterBg - vfBeforeBg
+    let bgFootprintDeltaMB = Double(fpAfterBg - fpBeforeBg) / 1_048_576
+    let fg2VideoDelta = vfAfterFg2 - vfAfterBg
+
+    print("")
+    print("=== BACKGROUND AUDIO PROBE RESULT ===")
+    print(String(format: "Background clock advance:    %.2fs over %.1fs wall (expect ~wall, audio alive)", bgClockDelta, bgSeconds))
+    print("Background video frames:     +\(bgVideoDelta) (expect ~0, video dropped)")
+    print(String(format: "Background footprint delta:  %+.1fMB (expect small, audio-paced not unbounded)", bgFootprintDeltaMB))
+    print("Foreground-2 video frames:   +\(fg2VideoDelta) (expect > 0, video resumed)")
+    print("=====================================")
+
+    var ok = true
+    if bgClockDelta < bgSeconds * 0.5 {
+        print("FAIL: audio clock did not advance during background (\(String(format: "%.2f", bgClockDelta))s); the loop starved audio")
+        ok = false
+    }
+    if bgVideoDelta > 2 {
+        print("WARN: video frames advanced during background (+\(bgVideoDelta)); video should be dropped")
+    }
+    if fg2VideoDelta <= 0 {
+        print("WARN: video did not resume after foreground return (+\(fg2VideoDelta))")
+    }
+    if ok {
+        print("OK: background-audio-only kept audio advancing while video was dropped, and video resumed on return.")
+        return 0
+    }
+    return 1
+}

Sources/aetherctl/main.swift

@@ -240,6 +240,21 @@ if first == "seektest" {
     exit(runSeekTest(url: parseSourceURL(urlArg), seeks: seeks, gapMs: gapMs, settleSeconds: settle))
 }
 
+// SW-path background-audio keepalive harness (iOS background audio on the software decode path).
+if first == "bgaudio" {
+    var rest = Array(args.dropFirst(2))
+    let fg = takeDoubleFlag("--fg", from: &rest) ?? 3.0
+    let bg = takeDoubleFlag("--bg", from: &rest) ?? 6.0
+    guard let urlArg = rest.first(where: { !$0.hasPrefix("--") }) else {
+        print("ERROR: bgaudio requires a <url> argument")
+        print("Usage: aetherctl bgaudio [--fg N] [--bg N] <url>")
+        exit(64)
+    }
+    rest.removeAll { $0 == urlArg }
+    rejectStrayFlags(rest, subcommand: "bgaudio")
+    exit(runBackgroundAudio(url: parseSourceURL(urlArg), fgSeconds: fg, bgSeconds: bg))
+}
+
 if first == "smbtest" {
     var rest = Array(args.dropFirst(2))
     let reads = takeIntFlag("--reads", from: &rest) ?? 64