react-native-audio-browser 0.2.0-next.33 → 0.2.0-next.34

package/ios/HybridAudioBrowser+PlayerCallbacks.swift

@@ -10,8 +10,6 @@ import os.log
 extension HybridAudioBrowser: PlayerCallbacks, AVPlayerEngineCallbacks {
   public func playerDidChangePlayback(_ playback: Playback) {
     onPlaybackChanged(playback)
-    // The Player sets the error before this fires, so the error line renders.
-    engine?.nowPlayingUpdater.render()
   }
 
   public func playerDidChangeActiveTrack(_ event: PlaybackActiveTrackChangedEvent) {
@@ -25,8 +23,8 @@ extension HybridAudioBrowser: PlayerCallbacks, AVPlayerEngineCallbacks {
       index: event.index,
       track: event.track.map(browserManager.hydrateFavorite),
     )
+    onPlaybackActiveTrackChanged(hydrated)
     activeTrackChangedEmitter.emit(hydrated)
-    engine?.nowPlayingUpdater.trackChanged()
   }
 
   public func playerDidUpdateProgress(_ event: PlaybackProgressUpdatedEvent) {
@@ -38,32 +36,11 @@ extension HybridAudioBrowser: PlayerCallbacks, AVPlayerEngineCallbacks {
   }
 
   public func playerDidChangePlayWhenReady(_ playWhenReady: Bool) {
-    // Intent to play again is the earliest cancel signal for a pending session release.
-    if playWhenReady { audioSession.cancelRelease() }
     onPlaybackPlayWhenReadyChanged(PlaybackPlayWhenReadyChangedEvent(playWhenReady: playWhenReady))
   }
 
   public func playerDidChangePlayingState(_ state: PlayingState) {
     onPlaybackPlayingState(state)
-    // Lazily activate the audio session the moment playback actually produces — or is buffering to
-    // produce — output. This (not setup) is where we grab the session, so launching the app never
-    // interrupts other apps' audio; the interruption only happens when the user truly starts
-    // playback, which is correct. Keyed off play *state*, not `playWhenReady`, because the intent
-    // can be set at setup (before any track) while output only begins here. Idempotent:
-    // `setActive(true)` is a no-op when the session is already active.
-    if state.playing || state.buffering {
-      // The now-playing session's activation request at link time predates this
-      // (the audio session was still inactive, and the system may have declined);
-      // re-request once the audio session is active, so the surface can appear even if
-      // playback never produces audio (first-ever load failing on a dead stream).
-      audioSession.activate { [weak self] in self?.engine?.reactivateNowPlayingSession() }
-    }
-    // A stall starting or recovering may not change the Player state.
-    engine?.nowPlayingUpdater.render()
-  }
-
-  public func playerShouldReleaseSession() {
-    audioSession.scheduleRelease()
   }
 
   public func playerDidEndQueue(_ event: PlaybackQueueEndedEvent) {
@@ -71,16 +48,18 @@ extension HybridAudioBrowser: PlayerCallbacks, AVPlayerEngineCallbacks {
   }
 
   public func playerDidChangeQueue(_ tracks: [Track]) {
+    onPlaybackQueueChanged(tracks)
     queueChangedEmitter.emit(tracks)
   }
 
   public func playerDidChangeRepeatMode(_ event: RepeatModeChangedEvent) {
+    onPlaybackRepeatModeChanged(event)
     repeatModeChangedEmitter.emit(event)
   }
 
   public func playerDidChangeShuffleEnabled(_ enabled: Bool) {
-    shuffleChangedEmitter.emit(enabled)
     onPlaybackShuffleModeChanged(enabled)
+    shuffleChangedEmitter.emit(enabled)
   }
 
   public func playerDidError(_ event: PlaybackErrorEvent) {
@@ -100,13 +79,8 @@ extension HybridAudioBrowser: PlayerCallbacks, AVPlayerEngineCallbacks {
     onTrackMetadata(metadata)
   }
 
-  public func playerDidReceiveTimedMetadata(_ groups: [AVTimedMetadataGroup]) {
-    for group in groups {
-      if let metadata = TimedMetadata.from(items: group.items, icyCharset: player?.currentTrack?.icyCharset) {
-        onTimedMetadata(metadata)
-        engine?.nowPlayingUpdater.receivedTimedMetadata(metadata)
-      }
-    }
+  public func playerDidReceiveTimedMetadata(_ metadata: TimedMetadata) {
+    onTimedMetadata(metadata)
   }
 
   public func playerDidReceiveChapterMetadata(_ groups: [AVTimedMetadataGroup]) {
@@ -126,10 +100,6 @@ extension HybridAudioBrowser: PlayerCallbacks, AVPlayerEngineCallbacks {
     dispatchRemote(handler: handleRemoteStop, report: onRemoteStop) { player?.stop() }
   }
 
-  public func remotePlayPause() {
-    if player?.playWhenReady == true { remotePause() } else { remotePlay() }
-  }
-
   public func remoteNext() {
     dispatchRemote(handler: handleRemoteNext, report: onRemoteNext) { player?.next() }
   }
@@ -174,12 +144,10 @@ extension HybridAudioBrowser: PlayerCallbacks, AVPlayerEngineCallbacks {
   }
 
   public func remoteChangeRepeatMode(mode: RepeatMode) {
-    // Apply the repeat mode change from CarPlay/lock screen
     try? setRepeatMode(mode: mode)
   }
 
   public func remoteChangeShuffleMode(enabled: Bool) {
-    // Apply the shuffle mode change from CarPlay/lock screen
     try? setShuffleEnabled(enabled: enabled)
   }
 

package/ios/HybridAudioBrowser.swift

@@ -8,7 +8,7 @@ import os.log
 @MainActor let playerAndConfiguredBrowser = ReadyValue<(HybridAudioBrowser, Player)> {
   guard let browser = HybridAudioBrowser.shared,
         browser.browserManager.isConfigured,
-        let player = browser.getPlayer() else { return nil }
+        let player = browser.player else { return nil }
   return (browser, player)
 }
 
@@ -34,14 +34,10 @@ public class HybridAudioBrowser: HybridAudioBrowserSpec, @unchecked Sendable {
   /// silent.
   static let instanceChangedEmitter = Emitter<Void>()
 
-  /// Installed once, on first instance creation. React Native posts this
-  /// notification (from `RCTReloadCommand`) when a JS reload — dev or
-  /// OTA-update restart — is triggered, *before* the old runtime is destroyed:
-  /// the earliest signal that this instance's JS callbacks are about to go
-  /// stale. `init` of the replacement instance drops them too, but only after
-  /// the new runtime is up; this observer closes the window in between.
-  /// Observed by name so the library needs no React-Core dependency (and
-  /// stays inert under SPM tests, where nothing posts it).
+  /// React Native posts this notification when a JS reload is triggered, before the old runtime
+  /// is destroyed: the earliest sign this instance's JS callbacks go stale. The replacement's
+  /// `init` drops them too, but only once the new runtime is up. Observed by name, so the library
+  /// needs no React-Core dependency.
   @MainActor private static let reloadObserver: NSObjectProtocol = NotificationCenter.default.addObserver(
     forName: Notification.Name("RCTTriggerReloadCommandNotification"),
     object: nil,
@@ -71,29 +67,16 @@ public class HybridAudioBrowser: HybridAudioBrowserSpec, @unchecked Sendable {
   @MainActor var pendingRepeatMode: RepeatMode?
   @MainActor let playerOptions = PlayerUpdateOptions()
 
-  /// Configured playback rates for the playback-rate capability (for CarPlay rate cycling)
-  @MainActor var playbackRates: [Double] { playerOptions.playbackRates }
-  @MainActor var carPlayUpNextButton: Bool { playerOptions.carPlayUpNextButton }
-  @MainActor var carPlayNowPlayingButtons: [CarPlayNowPlayingButton] {
-    playerOptions.carPlayNowPlayingButtons
-  }
-
-  @MainActor var carPlayPlayingIndicatorLocation: CarPlayPlayingIndicatorLocation {
-    playerOptions.carPlayPlayingIndicatorLocation
-  }
-
   @MainActor lazy var navigationError = NavigationErrorState(
-    onErrorChanged: { [weak self] in self?.navigationErrorEmitter.emit(NavigationErrorEvent(error: $0)) },
+    onErrorChanged: { [weak self] in self?.onNavigationError(NavigationErrorEvent(error: $0)) },
     onFormattedChanged: { [weak self] in self?.onFormattedNavigationError($0) },
   )
 
-  // MARK: - Multi-Listener Emitters
+  // MARK: - Emitters for Native Listeners
 
-  /// Emitters allow multiple listeners for each event type, avoiding callback hijacking
   public let favoriteChangedEmitter = Emitter<FavoriteChangedEvent>()
   public let activeTrackChangedEmitter = Emitter<PlaybackActiveTrackChangedEvent>()
   public let queueChangedEmitter = Emitter<[Track]>()
-  public let navigationErrorEmitter = Emitter<NavigationErrorEvent>()
   public let repeatModeChangedEmitter = Emitter<RepeatModeChangedEvent>()
   public let shuffleChangedEmitter = Emitter<Bool>()
   public let externalContentChangedEmitter = Emitter<String>()
@@ -111,17 +94,7 @@ public class HybridAudioBrowser: HybridAudioBrowserSpec, @unchecked Sendable {
 
   /// Runs a closure on MainActor synchronously. Safe for non-Sendable return types
   /// because DispatchQueue.main.sync blocks the caller — no concurrent access window.
-  func onMainActor<T>(_ work: @MainActor () -> T) -> T {
-    if Thread.isMainThread {
-      MainActor.assumeIsolated { UncheckedSendableBox(value: work()) }.value
-    } else {
-      DispatchQueue.main.sync {
-        MainActor.assumeIsolated { UncheckedSendableBox(value: work()) }.value
-      }
-    }
-  }
-
-  func onMainActor<T>(_ work: @MainActor () throws -> T) throws -> T {
+  func onMainActor<T>(_ work: @MainActor () throws -> T) rethrows -> T {
     if Thread.isMainThread {
       try MainActor.assumeIsolated { try UncheckedSendableBox(value: work()) }.value
     } else {
@@ -159,14 +132,11 @@ public class HybridAudioBrowser: HybridAudioBrowserSpec, @unchecked Sendable {
       let configuredPath = configuration.path
       onMainActor { browserManager.config = BrowserConfig(from: configuration) }
 
-      // Query tabs and navigate to initial path after config is set (matches Kotlin behavior)
       Task { @MainActor in
-        // Notify waiting listeners (e.g., CarPlay cold start)
         playerAndConfiguredBrowser.check()
       }
       Task {
         let tabs = try? await browserManager.queryTabs()
-        // Navigate to configured path, first tab, or "/"
         navigate(configuredPath ?? tabs?.first?.path ?? "/", clearError: true)
       }
     }
@@ -258,9 +228,7 @@ public class HybridAudioBrowser: HybridAudioBrowserSpec, @unchecked Sendable {
   public var onNowPlayingChanged: (NowPlayingMetadata) -> Void = { _ in }
   public var onOnlineChanged: (Bool) -> Void = { _ in } {
     didSet {
-      // The monitor->JS bridge is wired centrally in setupPlayer (so it doesn't depend on a JS
-      // subscription and can also drive the now-playing re-render + player reconnect). Here we only
-      // push the current state to a newly-attached subscriber.
+      // A new subscriber hears the current state at once.
       onOnlineChanged(networkMonitor.isOnline)
     }
   }
@@ -280,11 +248,6 @@ public class HybridAudioBrowser: HybridAudioBrowserSpec, @unchecked Sendable {
     }
   }
 
-  /// Stored so a re-setup can re-apply it: unlike the other runtime options this
-  /// one has no home in `playerOptions`, and the player it was pushed to does not
-  /// survive `setupPlayer`.
-  @MainActor var playbackIntervalEnabled = false
-
   // MARK: - Initialization
 
   override public init() {
@@ -302,6 +265,15 @@ public class HybridAudioBrowser: HybridAudioBrowserSpec, @unchecked Sendable {
       HybridAudioBrowser.shared = self
       audioSession.outputChanged.addListener { [weak self] in self?.onOutputChanged($0) }
       audioSession.volumeChanged.addListener { [weak self] in self?.onSystemVolumeChanged($0) }
+      // From the first setup on, whether or not JS subscribes: JS, then the player.
+      networkMonitor.changed.addListener { [weak self] isOnline in
+        guard let self else { return }
+        MainActor.assumeIsolated {
+          guard let player = self.player else { return }
+          self.onOnlineChanged(isOnline)
+          player.networkStatusDidChange(isOnline: isOnline)
+        }
+      }
       browseGate.resolve = { [weak self] request in
         guard let self else { throw CancellationError() }
         return try await resolveGate(request).await().await()
@@ -312,24 +284,18 @@ public class HybridAudioBrowser: HybridAudioBrowserSpec, @unchecked Sendable {
       // controller is subscribed to a dead instance's emitters.
       HybridAudioBrowser.instanceChangedEmitter.emit(())
     }
-    setupEmitterToNitroForwarding()
+    forwardBrowserEventsToJS()
   }
 
   /// Drops every JS-provided callback that native code can invoke on its own
   /// initiative (browse resolvers, `handleTrackLoad`, `resolveAlbumPath`,
   /// `formatNavigationError`, `resolveGate`, the now-playing formatter).
   ///
-  /// Called on the *previous* instance when a new one takes over: its JS runtime
-  /// is gone, and invoking a callback from a dead runtime aborts the process —
-  /// Nitro's `AsyncJSCallback` throws on a destroyed Dispatcher, and the throw
-  /// crosses the generated bridge wrapper's `noexcept` boundary. Native code
-  /// (e.g. a CarPlay controller still bound to this instance mid-reload) keeps
-  /// working off the data-only config with built-in fallbacks; `resolveGate`
-  /// reverts to the fail-closed default it documents for exactly this window.
-  /// One-shot: on a normal reload both triggers hit the same dying instance
-  /// (the reload notification, then the replacement's `init`), and the second
-  /// strip would re-fire the config-setter cascade — another `configChanged`
-  /// → CarPlay now-playing button rebuild — for nothing.
+  /// Called on the previous instance when a new one takes over: invoking a callback of a dead
+  /// runtime aborts the process (Nitro throws across a `noexcept` boundary). Native code still
+  /// bound to this instance (CarPlay mid-reload) keeps working off the data-only config;
+  /// `resolveGate` reverts to its fail-closed default. One-shot: both triggers reach the same
+  /// dying instance, and a second strip would re-run the config setter's cascade.
   @MainActor private var didDropJSCallbacks = false
 
   @MainActor
@@ -348,61 +314,32 @@ public class HybridAudioBrowser: HybridAudioBrowserSpec, @unchecked Sendable {
   }
 
   deinit {
-    // Safety net: ensure the AVPlayer is stopped if this instance is deallocated.
+    // Safety net: the AVPlayer must not outlive this instance. `self` can't reach the main
+    // actor from here, so the teardown takes what it releases.
     let player = self.player, engine = self.engine
-    if Thread.isMainThread {
-      MainActor.assumeIsolated {
-        player?.clear()
-        engine?.destroy()
-      }
-    } else {
-      DispatchQueue.main.async {
-        MainActor.assumeIsolated {
-          player?.clear()
-          engine?.destroy()
-        }
-      }
-    }
-  }
-
-  /// Returns the player, if setup has been called.
-  func getPlayer() -> Player? {
-    player
+    let tearDown: @Sendable () -> Void = { MainActor.assumeIsolated { Self.destroy(player, engine) } }
+    if Thread.isMainThread { tearDown() } else { DispatchQueue.main.async(execute: tearDown) }
   }
 
   /// Stops the player and releases its media stack: the AVPlayer and the now-playing session
   /// outlive a dropped reference otherwise.
   @MainActor
   func destroyPlayer() {
+    Self.destroy(player, engine)
+  }
+
+  @MainActor
+  private static func destroy(_ player: Player?, _ engine: AVPlayerEngine?) {
     player?.clear()
     engine?.destroy()
   }
 
-  /// Sets up automatic forwarding from emitters to Nitro callbacks
-  private func setupEmitterToNitroForwarding() {
+  /// Forwards the browser's events to JS. The bridge's own events call JS where they are
+  /// emitted; their emitters are for native listeners (CarPlay).
+  private func forwardBrowserEventsToJS() {
     browserManager.pathChanged.addListener { [weak self] in self?.onPathChanged($0) }
     browserManager.tabsChanged.addListener { [weak self] in self?.onTabsChanged($0) }
     browserManager.contentChanged.addListener { [weak self] in self?.onContentChanged($0) }
-
-    favoriteChangedEmitter.addListener { [weak self] event in
-      self?.onFavoriteChanged(event)
-    }
-
-    activeTrackChangedEmitter.addListener { [weak self] event in
-      self?.onPlaybackActiveTrackChanged(event)
-    }
-
-    queueChangedEmitter.addListener { [weak self] tracks in
-      self?.onPlaybackQueueChanged(tracks)
-    }
-
-    navigationErrorEmitter.addListener { [weak self] event in
-      self?.onNavigationError(event)
-    }
-
-    repeatModeChangedEmitter.addListener { [weak self] event in
-      self?.onPlaybackRepeatModeChanged(event)
-    }
   }
 }
 

package/ios/Model/NitroTypeStubs.swift

@@ -58,6 +58,21 @@
     var album: String?
   }
 
+  struct PlayerCapabilities: Equatable {
+    var play: Bool?
+    var pause: Bool?
+    var stop: Bool?
+    var seekTo: Bool?
+    var skipToNext: Bool?
+    var skipToPrevious: Bool?
+    var jumpForward: Bool?
+    var jumpBackward: Bool?
+    var favorite: Bool?
+    var shuffleMode: Bool?
+    var repeatMode: Bool?
+    var playbackRate: Bool?
+  }
+
   struct TrackLoadEvent {
     var track: Track
     var queue: [Track]

package/ios/Model/PlayerUpdateOptions.swift

@@ -12,6 +12,8 @@ class PlayerUpdateOptions {
   var forwardJumpInterval: Double = 15.0
   var backwardJumpInterval: Double = 15.0
   var progressUpdateEventInterval: Double?
+  /// Set by `setPlaybackIntervalEnabled`, not by `update(from:)`; not reported in `toOptions()`.
+  var playbackIntervalEnabled = false
 
   /// Player capabilities - most enabled by default, only false values disable
   /// Exceptions: jumpForward, jumpBackward default to false

package/ios/Model/RemoteCommand.swift

@@ -1,89 +1,17 @@
 import Foundation
 
-// Internal on purpose: nothing outside the module uses this, and a public
-// declaration gets printed into the generated -Swift.h C++ interop section,
-// where the [NSNumber] associated values don't compile for plain-C++
-// consumers of the header (Xcode 26.2 / Swift 6.2).
-enum RemoteCommand: CustomStringConvertible, Equatable {
+/// A system remote command (lock screen, Control Center, CarPlay, headset). The skip intervals
+/// and the playback rates the commands offer go to `RemoteCommandController.enable` beside them.
+enum RemoteCommand: CaseIterable, Hashable {
   case play
-
   case pause
-
   case stop
-
-  case togglePlayPause
-
   case next
-
   case previous
-
   case changePlaybackPosition
-
-  case skipForward(preferredIntervals: [NSNumber])
-
-  case skipBackward(preferredIntervals: [NSNumber])
-
+  case skipForward
+  case skipBackward
   case changeRepeatMode
-
   case changeShuffleMode
-
-  case changePlaybackRate(supportedPlaybackRates: [NSNumber])
-
-  var description: String {
-    switch self {
-    case .play: "play"
-    case .pause: "pause"
-    case .stop: "stop"
-    case .togglePlayPause: "togglePlayPause"
-    case .next: "nextTrack"
-    case .previous: "previousTrack"
-    case .changePlaybackPosition: "changePlaybackPosition"
-    case .skipForward: "skipForward"
-    case .skipBackward: "skipBackward"
-    case .changeRepeatMode: "changeRepeatMode"
-    case .changeShuffleMode: "changeShuffleMode"
-    case .changePlaybackRate: "changePlaybackRate"
-    }
-  }
-
-  var key: String { description }
-
-  /**
-   Commands in `self` that are absent from `next` and so should be disabled.
-
-   Compared by `key`, not by `==`. `RemoteCommand` is `Equatable` including its
-   associated values, but every case with associated values maps onto a single
-   `MPRemoteCommand` addressed by `key`: `.skipForward([15])` and
-   `.skipForward([30])` are two different values of one command. Diffing by `==`
-   would report the old interval as removed and disable the command that the new
-   interval had just re-enabled.
-   */
-  static func commandsToDisable(
-    enabled: [RemoteCommand],
-    replacedBy next: [RemoteCommand],
-  ) -> [RemoteCommand] {
-    let nextKeys = Set(next.map(\.key))
-    return enabled.filter { !nextKeys.contains($0.key) }
-  }
-
-  /**
-   All values in an array for convenience.
-   Don't use for associated values.
-   */
-  static func all() -> [RemoteCommand] {
-    [
-      .play,
-      .pause,
-      .stop,
-      .togglePlayPause,
-      .next,
-      .previous,
-      .changePlaybackPosition,
-      .skipForward(preferredIntervals: []),
-      .skipBackward(preferredIntervals: []),
-      .changeRepeatMode,
-      .changeShuffleMode,
-      .changePlaybackRate(supportedPlaybackRates: []),
-    ]
-  }
+  case changePlaybackRate
 }

package/ios/Player/NowPlayingUpdater.swift

@@ -18,13 +18,11 @@ final class NowPlayingUpdater {
   var onChanged: ((NowPlayingMetadata) -> Void)?
 
   /// When false the surface shows the track's own fields: the override and formatter are ignored.
-  var enabled = true
+  private let enabled: Bool
   var formatter: ((_ params: FormatNowPlayingParams) -> Promise<NowPlayingUpdate?>)?
 
-  /// Whether the device is online, which tells a stall apart: offline or buffering.
-  var isOnline = true {
-    didSet { if isOnline != oldValue { render() } }
-  }
+  /// Tells a stall apart: offline or buffering.
+  private weak var networkStatus: (any NetworkStatusProviding)?
 
   private var override: NowPlayingUpdate?
   private var timedMetadata: TimedMetadata?
@@ -103,8 +101,16 @@ final class NowPlayingUpdater {
   /// formatter result (a flash overwrites it, `clearNowPlaying` empties it).
   private var formattedTrackId: String?
 
-  init(nowPlayingInfoController: NowPlayingInfoController) {
+  init(
+    nowPlayingInfoController: NowPlayingInfoController,
+    networkStatus: (any NetworkStatusProviding)?,
+    enabled: Bool,
+    formatter: ((_ params: FormatNowPlayingParams) -> Promise<NowPlayingUpdate?>)?,
+  ) {
     self.nowPlayingInfoController = nowPlayingInfoController
+    self.networkStatus = networkStatus
+    self.enabled = enabled
+    self.formatter = formatter
   }
 
   /// Pixel width to request now-playing artwork at: the active scene's screen
@@ -169,7 +175,7 @@ final class NowPlayingUpdater {
       track: track,
       timedMetadata: timedMetadata,
       playWhenReady: source.playWhenReady,
-      stalled: source.isStalled ? (isOnline ? .buffering : .offline) : nil,
+      stalled: source.isStalled ? ((networkStatus?.isOnline ?? true) ? .buffering : .offline) : nil,
       error: source.nitroPlaybackError,
     )
     // `@Sendable` breaks the @MainActor isolation inheritance: Nitro resolves the promise on the JS

package/ios/Player/Player.swift

@@ -216,12 +216,14 @@ final class Player {
   ///   - persistenceSaveInterval: How often the snapshot is saved while the play intent is active.
   init(
     engine: any PlayerEngine,
+    callbacks: PlayerCallbacks? = nil,
     retry: RetryLoop = RetryLoop(),
     sleepTimerScheduler: any SleepTimerScheduling = MainQueueSleepTimerScheduler(),
     persistenceDefaults: UserDefaults = PlaybackPersistence.standardDefaults,
     persistenceSaveInterval: Duration = .seconds(5),
   ) {
     self.engine = engine
+    self.callbacks = callbacks
     self.retry = retry
     sleepTimerManager = SleepTimerManager(
       fader: VolumeFader(
@@ -290,7 +292,8 @@ final class Player {
 
   /// Emits what changed since the last publish, in order: the play intent, the playing state,
   /// the playback (state and error), the terminal error, the active play intent. The one place
-  /// these leave the Player, so each goes out once per change.
+  /// these leave the Player, so each goes out once per change, with the audio-session and
+  /// now-playing effects it drives.
   private func publish() {
     let playing = playingState
     let now = Published(
@@ -302,13 +305,19 @@ final class Player {
     guard now != old else { return }
     published = now
     if now.playWhenReady != old.playWhenReady {
+      if now.playWhenReady { engine.cancelAudioSessionRelease() }
       callbacks?.playerDidChangePlayWhenReady(now.playWhenReady)
     }
     if now.playing != old.playing || now.buffering != old.buffering {
       callbacks?.playerDidChangePlayingState(playing)
+      // Activated on output, not at setup: activating at launch interrupts other apps' audio.
+      if playing.playing || playing.buffering { engine.activateAudioSession() }
+      // A stall starting or recovering may leave the state as it was.
+      engine.renderNowPlaying()
     }
     if now.state != old.state || now.errorStatus != old.errorStatus {
       callbacks?.playerDidChangePlayback(Playback(state: now.state, error: now.errorStatus.nitroError))
+      engine.renderNowPlaying()
     }
     let erred = now.state == .error, wasErred = old.state == .error
     if erred != wasErred || (erred && now.errorStatus != old.errorStatus) {
@@ -399,13 +408,14 @@ final class Player {
   }
 
   /// Requests a session release once playback is deliberately stopped: no intent, no
-  /// interruption to resume from, no retry pending. The host debounces it.
+  /// interruption to resume from, and no retry pending, whose reconnect needs the session. The
+  /// engine debounces it.
   private func evaluateSessionRelease() {
     guard !playWhenReady,
           !shouldResumeAfterInterruption,
           retry.pendingTask == nil
     else { return }
-    callbacks?.playerShouldReleaseSession()
+    engine.scheduleAudioSessionRelease()
   }
 
   func getPlayback() -> Playback {
@@ -599,6 +609,7 @@ final class Player {
       track: currentTrack,
     )
     callbacks?.playerDidChangeActiveTrack(eventData)
+    engine.nowPlayingTrackChanged()
     lastTrack = currentTrack
     lastIndex = queue.currentIndex
   }
@@ -755,6 +766,9 @@ final class Player {
     case .stalled:
       // Nudge, don't reconnect: a genuine drop is recovered by the retry and network paths.
       recoverFromStall(reconnectIfLive: false)
+    case let .timedMetadata(metadata):
+      callbacks?.playerDidReceiveTimedMetadata(metadata)
+      engine.applyTimedMetadata(metadata)
     }
   }
 
@@ -839,13 +853,15 @@ final class Player {
 
   // MARK: - Connectivity
 
-  /// Re-establishes a stalled stream when connectivity returns. AVPlayer doesn't reliably report
-  /// a live stream's mid-stream drop as a failure: it waits with no error, so the retry loop
-  /// never engages. Only while stalled (.buffering) with play intent, so a pause or a retry that
-  /// gave up isn't resumed; and not while the retry loop is itself waiting for the network,
-  /// which owns that reload.
-  func networkDidReturn() {
-    guard playWhenReady, state == .buffering, !retry.isWaitingForNetwork else { return }
+  /// Re-renders the now-playing lines, whose stall line tells offline from buffering, and when
+  /// connectivity returns re-establishes a stalled stream. AVPlayer doesn't reliably report a
+  /// live stream's mid-stream drop as a failure: it waits with no error, so the retry loop never
+  /// engages. Only while stalled (.buffering) with play intent, so a pause or a retry that gave up
+  /// isn't resumed; and not while the retry loop is itself waiting for the network, which owns
+  /// that reload.
+  func networkStatusDidChange(isOnline: Bool) {
+    engine.renderNowPlaying()
+    guard isOnline, playWhenReady, state == .buffering, !retry.isWaitingForNetwork else { return }
     logger.info("Connectivity restored while stalled — re-resolving to reconnect")
     reloadResolving(startFromCurrentTime: true)
   }

package/ios/Player/PlayerCallbacks.swift

@@ -15,9 +15,6 @@
   func playerDidChangeRepeatMode(_ event: RepeatModeChangedEvent)
   func playerDidChangeShuffleEnabled(_ enabled: Bool)
   func playerDidError(_ event: PlaybackErrorEvent)
-  /// Playback is deliberately stopped — play intent is off, it isn't an interruption-driven pause
-  /// (those resume), and no retry is pending (a live-stream reconnect must keep the session). The
-  /// host may release the audio session (debounced) so other apps' audio can resume.
-  func playerShouldReleaseSession()
+  func playerDidReceiveTimedMetadata(_ metadata: TimedMetadata)
   func playerDidChangeSleepTimer(_ state: SleepTimerState?)
 }

package/ios/Player/PlayerEngine.swift

@@ -24,6 +24,9 @@ enum EngineEvent {
   case playedToEnd
   /// The buffer emptied mid-playback.
   case stalled
+  /// A timed-metadata group (a live stream's song line), decoded with the loaded track's ICY
+  /// charset.
+  case timedMetadata(TimedMetadata)
 }
 
 /// The media stack under the Player: the AVPlayer and its items, media loading, now playing and
@@ -80,8 +83,22 @@ enum EngineEvent {
   func primeNowPlaying()
   func loadNowPlayingMetadata(for track: Track)
   func clearNowPlaying()
+  /// Re-renders the now-playing lines from the Player's state.
+  func renderNowPlaying()
+  /// Drops the previous track's override, flash and timed metadata, and re-renders.
+  func nowPlayingTrackChanged()
+  func applyTimedMetadata(_ metadata: TimedMetadata)
   func updateRemoteRepeatMode(_ mode: RepeatMode)
   func updateRemoteShuffleMode(_ enabled: Bool)
   /// Greys out next/previous on the remote surfaces when the queue has nowhere to skip.
   func updateSkipAvailability(canNext: Bool, canPrevious: Bool)
+
+  // MARK: Audio session
+
+  /// Activates the audio session off the main thread, then re-requests the now-playing session,
+  /// which the system may have declined while the audio session was inactive.
+  func activateAudioSession()
+  func cancelAudioSessionRelease()
+  /// Releases the audio session after a debounce, unless playback resumes first.
+  func scheduleAudioSessionRelease()
 }