0.20.0 - Host-only audio-session ownership

CHANGELOG.md

@@ -2,7 +2,63 @@
 
 All notable changes to PlayolaPlayer are documented here. This project follows
 [Semantic Versioning](https://semver.org/). Versions correspond to git tags,
-which Swift Package Manager consumers pin to.
+which Swift Package Manager consumers pin to. Pre-1.0, breaking changes bump the
+minor version.
+
+## 0.20.0
+
+This release makes the **host app the sole owner of the `AVAudioSession`.** The
+SDK previously configured/activated the session and self-handled interruptions
+and route changes; it no longer touches `AVAudioSession` at all. This lets the
+SDK coexist cleanly with other audio subsystems in your app (URL streaming,
+recording, VoIP) instead of fighting them for the process-global session.
+
+### Removed
+
+- **The SDK no longer manages the `AVAudioSession`.** `AudioSessionManager` is
+  gone, `PlayolaMainMixer` no longer exposes `configureAudioSession()` /
+  `ensureAudioSessionConfigured()` / `deactivateAudioSession()`, and
+  `PlayolaStationPlayer` no longer registers `AVAudioSession.interruptionNotification`
+  / `routeChangeNotification` observers. The `handleAudioSessionInterruption(_:)`
+  and `handleAudioRouteChange(_:)` methods are removed.
+
+  **Source-breaking — required host changes:**
+
+  1. **Own the session.** Configure and activate it before `play(stationId:)`:
+     `try AVAudioSession.sharedInstance().setCategory(.playback, mode: .default, policy: .longFormAudio, options: [])`
+     then `setActive(true)`. The SDK no longer does this; without it,
+     `play(stationId:)` fails when the engine starts (surfaced as `.error`).
+
+  2. **Drive interruptions yourself.** Observe `AVAudioSession.interruptionNotification`
+     (and route changes as needed) and call the new `pauseForInterruption()` /
+     `resumeAfterInterruption()` (below). Reactivate the session before calling
+     resume.
+
+  See the [Audio session](README.md#audio-session) and migration sections of the
+  README for copy-paste host setup and a full interruption-handling example.
+
+### Added
+
+- **Host-driven interruption transport.**
+  - `PlayolaStationPlayer.pauseForInterruption()` — silences playback,
+    cancels scheduling/downloads, and is generation-fenced so in-flight work
+    from before the pause can't publish state afterward. Preserves only the
+    station identity (wall-clock radio has no frozen position). Idempotent
+    across a double-pause.
+  - `PlayolaStationPlayer.resumeAfterInterruption() async throws` — restarts the
+    engine and replays the interrupted station re-synced to the live wall clock.
+    Disarms only on success, so a failed resume (e.g. the host hasn't
+    reactivated the session yet) stays retryable.
+
+- **`PlayolaStationPlayer.State` gained a `.paused(Spin)` case.** Published while
+  paused for an interruption; the `Spin` carries display metadata (title,
+  artist, artwork URL) for the track that was playing. **Source-breaking for
+  consumers** that `switch` exhaustively over `State`: add a `case .paused` arm.
+
+- **Engine self-recovery.** The SDK now restarts and re-syncs its own engine
+  graph on `AVAudioEngineConfigurationChange` (scoped to the SDK's own engine,
+  so a host running a separate `AVAudioEngine` is unaffected). This is engine
+  ownership, not session ownership — it touches no `AVAudioSession` API.
 
 ## 0.19.0
 

PlayolaPlayerExample/PlayolaPlayerExample/ContentView.swift

@@ -129,6 +129,16 @@ struct ContentView: View {
                   .font(.caption)
                   .foregroundColor(.white.opacity(0.6))
               }
+            } else if case .paused(let spin) = player.state {
+              Text(spin.audioBlock.title)
+                .font(.title2)
+                .fontWeight(.semibold)
+                .foregroundColor(.white.opacity(0.7))
+                .lineLimit(1)
+
+              Text("Paused")
+                .font(.headline)
+                .foregroundColor(.white.opacity(0.5))
             } else if case .error(let error) = player.state {
               VStack(spacing: 8) {
                 Image(systemName: "exclamationmark.triangle.fill")
@@ -249,8 +259,9 @@ struct ContentView: View {
       case .playing:
         // Stop playing
         await player.stop()
-      case .idle, .error:
-        // Start (or retry after a failed start)
+      case .idle, .error, .paused:
+        // Start (or retry after a failed start / resume after a pause —
+        // play() re-fetches the schedule and re-syncs to now)
         do {
           try await player.play(stationId: selectedStationId)
         } catch {
@@ -508,6 +519,8 @@ func buttonColor(for state: PlayolaStationPlayer.State) -> Color {
     return Color.green
   case .error:
     return Color.green
+  case .paused:
+    return Color.green
   }
 }
 
@@ -521,14 +534,19 @@ func buttonIcon(for state: PlayolaStationPlayer.State) -> String {
     return "play.fill"
   case .error:
     return "arrow.clockwise"
+  case .paused:
+    return "play.fill"
   }
 }
 
 func shouldOffsetIcon(for state: PlayolaStationPlayer.State) -> Bool {
-  if case .idle = state {
+  // Offset centers the play triangle; .paused shows play.fill like .idle.
+  switch state {
+  case .idle, .paused:
     return true
+  default:
+    return false
   }
-  return false
 }
 
 // Custom button style for offset buttons

PlayolaPlayerExample/PlayolaPlayerExample/PlayolaPlayerExampleApp.swift

@@ -5,13 +5,77 @@
 //  Created by Brian D Keane on 12/29/24.
 //
 
+import AVFoundation
+import PlayolaPlayer
 import SwiftUI
 
 @main
 struct PlayolaPlayerExampleApp: App {
+  private let audioSession = HostAudioSession()
+
   var body: some Scene {
     WindowGroup {
       ContentView()
     }
   }
 }
+
+/// PlayolaPlayer does not manage the `AVAudioSession` — the host app owns it.
+/// This demonstrates the full host contract: configure + activate the session,
+/// and drive `pauseForInterruption()` / `resumeAfterInterruption()` from the
+/// interruption notifications. A production app would also handle route changes.
+@MainActor
+final class HostAudioSession {
+  /// Retained so the block observer can be removed in deinit and its lifetime
+  /// is explicit (NotificationCenter holds the token until removal).
+  private var interruptionObserver: (any NSObjectProtocol)?
+
+  init() {
+    do {
+      let session = AVAudioSession.sharedInstance()
+      try session.setCategory(.playback, mode: .default, policy: .longFormAudio, options: [])
+      try session.setActive(true)
+    } catch {
+      print("Failed to configure AVAudioSession: \(error)")
+    }
+
+    interruptionObserver = NotificationCenter.default.addObserver(
+      forName: AVAudioSession.interruptionNotification, object: nil, queue: .main
+    ) { notification in
+      MainActor.assumeIsolated {
+        Self.handleInterruption(notification)
+      }
+    }
+  }
+
+  deinit {
+    if let interruptionObserver {
+      NotificationCenter.default.removeObserver(interruptionObserver)
+    }
+  }
+
+  private static func handleInterruption(_ notification: Notification) {
+    guard let typeValue = notification.userInfo?[AVAudioSessionInterruptionTypeKey] as? UInt,
+      let type = AVAudioSession.InterruptionType(rawValue: typeValue)
+    else { return }
+
+    switch type {
+    case .began:
+      PlayolaStationPlayer.shared.pauseForInterruption()
+    case .ended:
+      guard let optionsValue = notification.userInfo?[AVAudioSessionInterruptionOptionKey] as? UInt,
+        AVAudioSession.InterruptionOptions(rawValue: optionsValue).contains(.shouldResume)
+      else { return }
+      Task {
+        do {
+          try AVAudioSession.sharedInstance().setActive(true)
+          try await PlayolaStationPlayer.shared.resumeAfterInterruption()
+        } catch {
+          print("Resume failed: \(error)")
+        }
+      }
+    @unknown default:
+      break
+    }
+  }
+}