@5stones/react-native-audio-browser 0.1.6 → 0.3.0

package/ios/CarPlay/RNABMediaIntentHandler.swift

@@ -0,0 +1,60 @@
+import Foundation
+import Intents
+import os.log
+
+/// Handles INPlayMediaIntent for Siri voice search (e.g. from CarPlay).
+///
+/// The class is internal (not public) to avoid exposing Intents types in the
+/// generated AudioBrowser-Swift.h header, but is registered with the ObjC
+/// runtime via `@objc(RNABMediaIntentHandler)` for NSClassFromString lookup.
+///
+/// Host apps call the static method from `application(_:handle:completionHandler:)`:
+/// ```swift
+/// @objc private protocol RNABMediaIntentHandling {
+///   static func handleMediaIntent(_ intent: INIntent, completionHandler: @escaping (INIntentResponse) -> Void)
+/// }
+///
+/// func application(_ application: UIApplication, handle intent: INIntent, completionHandler: @escaping (INIntentResponse) -> Void) {
+///   (NSClassFromString("RNABMediaIntentHandler") as? RNABMediaIntentHandling.Type)?
+///     .handleMediaIntent(intent, completionHandler: completionHandler)
+/// }
+/// ```
+@objc(RNABMediaIntentHandler)
+class RNABMediaIntentHandler: NSObject, INPlayMediaIntentHandling {
+  private static let logger = Logger(subsystem: "com.audiobrowser", category: "MediaIntentHandler")
+
+  // MARK: - Static Entry Point
+
+  /// Convenience entry point for host apps. Handles the full INPlayMediaIntent flow:
+  /// type checking, search, queue, and playback.
+  @objc static func handleMediaIntent(_ intent: INIntent, completionHandler: @escaping @Sendable (INIntentResponse) -> Void) {
+    guard let playIntent = intent as? INPlayMediaIntent else {
+      completionHandler(INPlayMediaIntentResponse(code: .failure, userActivity: nil))
+      return
+    }
+    let handler = RNABMediaIntentHandler()
+    handler.handle(intent: playIntent) { response in
+      completionHandler(response)
+    }
+  }
+
+  // MARK: - INPlayMediaIntentHandling
+
+  func handle(intent: INPlayMediaIntent, completion: @escaping @Sendable (INPlayMediaIntentResponse) -> Void) {
+    let searchTerm = intent.mediaSearch?.mediaName ?? ""
+    Self.logger.info("Handling play media intent with search term: \(searchTerm)")
+
+    guard let browser = HybridAudioBrowser.shared else {
+      Self.logger.error("HybridAudioBrowser.shared is nil — app may not be initialized yet")
+      completion(INPlayMediaIntentResponse(code: .failureRequiringAppLaunch, userActivity: nil))
+      return
+    }
+
+    browser.handlePlayMediaIntent(searchTerm: searchTerm) { success in
+      completion(INPlayMediaIntentResponse(
+        code: success ? .success : .failure,
+        userActivity: nil,
+      ))
+    }
+  }
+}

package/ios/Extension/ChapterMetadata+AVFoundation.swift

@@ -30,7 +30,7 @@ extension ChapterMetadata {
         startTime: startTime,
         endTime: endTime,
         title: title,
-        url: url
+        url: url,
       )
     }
   }

package/ios/Extension/CxxVectorConformances.swift

@@ -0,0 +1,20 @@
+import NitroModules
+
+// Workaround for a Nitro Modules upstream issue.
+//
+// Nitrogen-generated Swift code (e.g. Func_void_std__vector_Track_.swift) calls
+// .map() on std::vector<T>, which requires CxxRandomAccessCollection conformance.
+// Swift's C++ interop synthesizes this conformance lazily, but in incremental
+// builds the conformance may not be available in the compilation batch that needs
+// it, causing: "Value of type 'std::vector<T>' has no member 'map'"
+//
+// This should be fixed upstream in Nitro Modules. Until then, explicitly
+// declaring the conformance here guarantees it's available regardless of
+// compilation order.
+//
+// To identify which types need conformance, search the generated Swift files for
+// .map() calls on bridge.std__vector_<T>_ types:
+//
+//   grep -r '\.map(' nitrogen/generated/ios/swift/ | grep std__vector
+
+extension margelo.nitro.audiobrowser.bridge.swift.std__vector_Track_: @retroactive CxxRandomAccessCollection {}

package/ios/Extension/TimedMetadata+AVFoundation.swift

@@ -36,7 +36,7 @@ extension TimedMetadata {
       artist: nil,
       album: nil,
       date: nil,
-      genre: nil
+      genre: nil,
     )
   }
 
@@ -57,9 +57,9 @@ extension TimedMetadata {
       case .id3MetadataAlbumTitle, .id3MetadataOriginalAlbumTitle:
         album = item.stringValue
       case .id3MetadataRecordingTime:
-        date = item.stringValue  // TDRC takes precedence (ID3v2.4, more precise)
+        date = item.stringValue // TDRC takes precedence (ID3v2.4, more precise)
       case .id3MetadataYear:
-        date = date ?? item.stringValue  // TYER only if TDRC not found (ID3v2.3)
+        date = date ?? item.stringValue // TYER only if TDRC not found (ID3v2.3)
       case .id3MetadataContentType:
         genre = item.stringValue
       default:
@@ -73,7 +73,7 @@ extension TimedMetadata {
       artist: artist,
       album: album,
       date: date,
-      genre: genre
+      genre: genre,
     )
   }
 
@@ -120,7 +120,7 @@ extension TimedMetadata {
       artist: artist,
       album: album,
       date: date,
-      genre: genre
+      genre: genre,
     )
   }
 }

package/ios/Extension/Track+AVPlayer.swift

@@ -26,26 +26,25 @@ extension Track {
   /// Uses Kingfisher for caching and efficient image loading
   func loadArtwork() async -> UIImage? {
     // Try artworkSource first (has more detailed config), then fall back to artwork string
+    // Skip SF Symbol strings - those require SFSymbolRenderer and can't be loaded as URLs
     let artworkUrlString: String?
     let artworkHeaders: [String: String]?
 
     if let source = artworkSource {
       artworkUrlString = source.uri
       artworkHeaders = source.headers
-    } else {
+    } else if let artwork, !SFSymbolRenderer.isSFSymbol(artwork) {
       artworkUrlString = artwork
       artworkHeaders = nil
+    } else {
+      artworkUrlString = nil
+      artworkHeaders = nil
     }
 
     guard let urlString = artworkUrlString, let url = URL(string: urlString) else {
       return nil
     }
 
-    if url.isFileURL {
-      return UIImage(contentsOfFile: url.path)
-    }
-
-    // Build Kingfisher options with headers if provided
     var options: KingfisherOptionsInfo = []
     if let headers = artworkHeaders, !headers.isEmpty {
       let modifier = AnyModifier { request in

package/ios/Extension/TrackMetadata+AVFoundation.swift

@@ -122,7 +122,7 @@ extension TrackMetadata {
       mediaType: nil,
       creationDate: creationDate,
       creationYear: creationYear,
-      url: nil
+      url: nil,
     )
   }
 }

package/ios/HybridAudioBrowser.swift

@@ -48,12 +48,6 @@ public class HybridAudioBrowser: HybridAudioBrowserSpec, @unchecked Sendable {
     }
   }
 
-  // MARK: - Internal Callbacks (for CarPlay/external controllers)
-
-  /// Called when notifyContentChanged is invoked, allowing CarPlay to refresh its templates.
-  /// Set by CarPlayController during setup.
-  var onExternalContentChanged: ((String) -> Void)?
-
   // MARK: - Multi-Listener Emitters
 
   /// Emitters allow multiple listeners for each event type, avoiding callback hijacking
@@ -114,8 +108,8 @@ public class HybridAudioBrowser: HybridAudioBrowserSpec, @unchecked Sendable {
 
   public var configuration: NativeBrowserConfiguration = .init(
     path: nil, request: nil, media: nil, artwork: nil, routes: nil,
-    singleTrack: nil, androidControllerOfflineError: nil, carPlayUpNextButton: nil,
-    carPlayNowPlayingButtons: nil, formatNavigationError: nil,
+    singleTrack: nil, handleTrackLoad: nil, androidControllerOfflineError: nil,
+    carPlayUpNextButton: nil, carPlayNowPlayingButtons: nil, formatNavigationError: nil,
   ) {
     didSet {
       browserManager.config = BrowserConfig(from: configuration)
@@ -226,6 +220,7 @@ public class HybridAudioBrowser: HybridAudioBrowserSpec, @unchecked Sendable {
       setupVolumeObserver()
     }
   }
+
   public var onIosOutputChanged: (IosOutput) -> Void = { _ in } {
     didSet {
       setupRouteChangeObserver()
@@ -236,11 +231,30 @@ public class HybridAudioBrowser: HybridAudioBrowserSpec, @unchecked Sendable {
 
   override public init() {
     super.init()
-    HybridAudioBrowser.shared = self
+
+    // Clean up the previous instance (e.g., on JS runtime reload).
+    // The old HybridAudioBrowser may still be retained by the global
+    // playerAndConfiguredBrowser OnceValue, so we must explicitly stop
+    // its player to prevent two audio streams running simultaneously.
+    onMainActor {
+      HybridAudioBrowser.shared?.player?.destroy()
+      playerAndConfiguredBrowser.reset()
+      HybridAudioBrowser.shared = self
+    }
     setupEmitterToNitroForwarding()
     setupBrowserCallbacks()
   }
 
+  deinit {
+    // Safety net: ensure the AVPlayer is stopped if this instance is deallocated.
+    let player = self.player
+    if Thread.isMainThread {
+      MainActor.assumeIsolated { player?.destroy() }
+    } else {
+      DispatchQueue.main.async { MainActor.assumeIsolated { player?.destroy() } }
+    }
+  }
+
   /// Returns the TrackPlayer instance, if setup has been called.
   func getPlayer() -> TrackPlayer? {
     player
@@ -325,13 +339,16 @@ public class HybridAudioBrowser: HybridAudioBrowserSpec, @unchecked Sendable {
     let defaultFormatted = defaultFormattedError(navError)
     if let formatter = browserManager.config.formatNavigationError {
       let params = FormatNavigationErrorParams(error: navError, defaultFormatted: defaultFormatted, path: path)
-      formatter(params)
-        .then { [weak self] customDisplay in
-          self?.lastFormattedNavigationError = customDisplay ?? defaultFormatted
-        }
-        .catch { [weak self] _ in
-          self?.lastFormattedNavigationError = defaultFormatted
-        }
+      // Dispatch to main thread for the Nitro bridge call to avoid C++ noexcept crashes
+      DispatchQueue.main.async { [weak self] in
+        formatter(params)
+          .then { customDisplay in
+            self?.lastFormattedNavigationError = customDisplay ?? defaultFormatted
+          }
+          .catch { _ in
+            self?.lastFormattedNavigationError = defaultFormatted
+          }
+      }
     } else {
       lastFormattedNavigationError = defaultFormatted
     }
@@ -373,6 +390,18 @@ public class HybridAudioBrowser: HybridAudioBrowserSpec, @unchecked Sendable {
     }
   }
 
+  /// Centralizes handleTrackLoad interception logic.
+  /// If handleTrackLoad is set on config, awaits it (intercepted). Otherwise runs defaultBehavior.
+  ///
+  /// - Returns: true if the handler intercepted, false if defaultBehavior ran
+  @discardableResult
+  private func handleLoadAsync(track: Track, queue: [Track], startIndex: Double, defaultBehavior: () async -> Void) async -> Bool {
+    let event = TrackLoadEvent(track: track, queue: queue, startIndex: startIndex)
+    if await browserManager.config.awaitTrackLoadHandler(event: event) { return true }
+    await defaultBehavior()
+    return false
+  }
+
   public func navigateTrack(track: Track) throws {
     let url = track.url
 
@@ -391,8 +420,19 @@ public class HybridAudioBrowser: HybridAudioBrowserSpec, @unchecked Sendable {
       }
       if let index = existingIndex {
         logger.debug("Queue already from \(parentPath), skipping to index \(index)")
-        onMainActor {
-          try? player?.skipTo(index, playWhenReady: true)
+        let queue: [Track] = onMainActor { player?.tracks ?? [] }
+        Task {
+          await handleLoadAsync(track: track, queue: queue, startIndex: Double(index)) {
+            do {
+              try onMainActor {
+                try player?.skipTo(index, playWhenReady: true)
+              }
+            } catch {
+              // NOTE: because we have a throwing closure here, the thrown error
+              // can't be propogated up. Log it out instead.
+              logger.error("Failed to skip to track at index \(index): \(error)")
+            }
+          }
         }
         return
       }
@@ -402,30 +442,39 @@ public class HybridAudioBrowser: HybridAudioBrowserSpec, @unchecked Sendable {
           // Expand the queue from the contextual URL
           if let expanded = try await browserManager.expandQueueFromContextualUrl(url) {
             let (tracks, startIndex) = expanded
-
-            // Replace queue and start at the selected track (auto-play)
-            await MainActor.run {
-              player?.setQueue(tracks, initialIndex: startIndex, playWhenReady: true, sourcePath: parentPath)
+            await handleLoadAsync(track: track, queue: tracks, startIndex: Double(startIndex)) {
+              // Replace queue and start at the selected track (auto-play)
+              onMainActor {
+                player?.setQueue(tracks, initialIndex: startIndex, playWhenReady: true, sourcePath: parentPath)
+              }
             }
           } else {
             // Fallback: just load the single track (auto-play)
-            await MainActor.run {
-              player?.load(track, playWhenReady: true)
+            await handleLoadAsync(track: track, queue: [track], startIndex: 0) {
+              onMainActor {
+                player?.load(track, playWhenReady: true)
+              }
             }
           }
         } catch {
           logger.error("Error expanding queue: \(error.localizedDescription)")
           // Fallback to single track (auto-play) - playback errors reported via TrackPlayer callbacks
-          await MainActor.run {
-            player?.load(track, playWhenReady: true)
+          await handleLoadAsync(track: track, queue: [track], startIndex: 0) {
+            onMainActor {
+              player?.load(track, playWhenReady: true)
+            }
           }
         }
       }
     }
     // If track has src, it's playable - load and auto-play
     else if track.src != nil {
-      onMainActor {
-        player?.load(track, playWhenReady: true)
+      Task {
+        await handleLoadAsync(track: track, queue: [track], startIndex: 0) {
+          onMainActor {
+            player?.load(track, playWhenReady: true)
+          }
+        }
       }
     }
     // If track has url, it's browsable - navigate to it
@@ -467,7 +516,6 @@ public class HybridAudioBrowser: HybridAudioBrowserSpec, @unchecked Sendable {
     browserManager.invalidateContentCache(path)
 
     // Notify external controllers (CarPlay) that content changed
-    onExternalContentChanged?(path)
     externalContentChangedEmitter.emit(path)
 
     // Re-resolve the path if it's the current browser path
@@ -798,9 +846,10 @@ public class HybridAudioBrowser: HybridAudioBrowserSpec, @unchecked Sendable {
         favorited: favorited,
         groupTitle: track.groupTitle,
         live: track.live,
+        imageRow: track.imageRow,
       )
       // Update the track in the player's queue so getActiveTrack() returns correct state
-      player?.setTrack(at: index, updatedTrack)
+      player?.replace(index, updatedTrack)
       favoriteChangedEmitter.emit(FavoriteChangedEvent(track: updatedTrack, favorited: favorited))
       // Fire active track changed so useActiveTrack() hook updates UI
       let position = player?.currentTime ?? 0
@@ -881,7 +930,7 @@ public class HybridAudioBrowser: HybridAudioBrowserSpec, @unchecked Sendable {
         album: track.album,
         artist: override?.artist ?? track.artist,
         duration: track.duration,
-        artwork: track.artwork,
+        artwork: nowPlayingArtwork(for: track),
         description: track.description,
         mediaId: track.src ?? track.url,
         genre: track.genre,
@@ -890,6 +939,15 @@ public class HybridAudioBrowser: HybridAudioBrowserSpec, @unchecked Sendable {
     }
   }
 
+  /// Returns the artwork URI suitable for JS consumption.
+  /// Prefers the resolved artworkSource URI (e.g. file:// for rendered SF Symbols).
+  /// Falls back to the raw artwork string only if it's not an SF Symbol (which JS can't load).
+  private func nowPlayingArtwork(for track: Track) -> String? {
+    if let uri = track.artworkSource?.uri { return uri }
+    guard let artwork = track.artwork else { return nil }
+    return SFSymbolRenderer.isSFSymbol(artwork) ? nil : artwork
+  }
+
   /// Applies the current now playing metadata (with override if set) to NowPlayingInfoCenter and notifies JS.
   @MainActor
   private func applyNowPlayingMetadata() {
@@ -902,7 +960,7 @@ public class HybridAudioBrowser: HybridAudioBrowserSpec, @unchecked Sendable {
       album: track.album,
       artist: override?.artist ?? track.artist,
       duration: track.duration,
-      artwork: track.artwork,
+      artwork: nowPlayingArtwork(for: track),
       description: track.description,
       mediaId: track.src ?? track.url,
       genre: track.genre,
@@ -959,7 +1017,7 @@ public class HybridAudioBrowser: HybridAudioBrowserSpec, @unchecked Sendable {
     routeChangeObserver = NotificationCenter.default.addObserver(
       forName: AVAudioSession.routeChangeNotification,
       object: nil,
-      queue: .main
+      queue: .main,
     ) { [weak self] _ in
       guard let self, let output = self.getCurrentOutput() else { return }
       self.onIosOutputChanged(output)
@@ -1008,15 +1066,21 @@ public class HybridAudioBrowser: HybridAudioBrowserSpec, @unchecked Sendable {
       guard let windowScene = UIApplication.shared.connectedScenes
         .compactMap({ $0 as? UIWindowScene })
         .first(where: { $0.activationState == .foregroundActive }),
-        let window = windowScene.windows.first(where: { $0.isKeyWindow })
+        let window = windowScene.windows.first(where: { $0.isKeyWindow }),
+        var topController = window.rootViewController
       else {
         self?.logger.debug("openIosOutputPicker: Could not find active window scene")
         return
       }
 
+      // Walk up to the topmost presented view controller
+      while let presented = topController.presentedViewController {
+        topController = presented
+      }
+
       let routePicker = AVRoutePickerView(frame: .zero)
       routePicker.isHidden = true
-      window.addSubview(routePicker)
+      topController.view.addSubview(routePicker)
 
       // Find the button inside AVRoutePickerView and trigger it
       for subview in routePicker.subviews {
@@ -1266,6 +1330,33 @@ extension HybridAudioBrowser: TrackPlayerCallbacks {
     }
   }
 
+  /// Handles an INPlayMediaIntent by searching for the given term and starting playback.
+  ///
+  /// Host apps should call this from their `INPlayMediaIntentHandling` implementation.
+  /// Uses the browser's search route to find tracks, then queues and plays them.
+  ///
+  /// - Parameters:
+  ///   - searchTerm: The search query from Siri.
+  ///   - completion: Called with `true` if tracks were found and queued, `false` otherwise.
+  public func handlePlayMediaIntent(searchTerm: String, completion: @escaping @Sendable (Bool) -> Void) {
+    Task {
+      do {
+        let resolved = try await self.browserManager.search(searchTerm)
+        guard let tracks = resolved.children, !tracks.isEmpty else {
+          completion(false)
+          return
+        }
+        await MainActor.run {
+          self.getPlayer()?.setQueue(tracks, initialIndex: 0, playWhenReady: true)
+        }
+        completion(true)
+      } catch {
+        self.logger.error("handlePlayMediaIntent failed: \(error.localizedDescription)")
+        completion(false)
+      }
+    }
+  }
+
   public func remoteLike() {
     if let handler = handleRemoteLike {
       handler()

package/ios/Model/MediaURL.swift

@@ -45,7 +45,8 @@ struct MediaURL {
       allowed.formUnion(.urlQueryAllowed)
       allowed.formUnion(.urlFragmentAllowed)
       if let encoded = string.addingPercentEncoding(withAllowedCharacters: allowed),
-         let url = URL(string: encoded) {
+         let url = URL(string: encoded)
+      {
         return url
       }
     }

package/ios/Player/PlayingStateManager.swift

@@ -2,6 +2,7 @@ import Foundation
 import NitroModules
 
 /// Manages the playing state (playing and buffering flags) and notifies when they change.
+@MainActor
 class PlayingStateManager {
   private(set) var playing: Bool = false
   private(set) var buffering: Bool = false