react-native-audio-browser 0.0.1 → 0.1.0-next.2

package/ios/TrackPlayerCallbacks.swift

@@ -0,0 +1,92 @@
+import AVFoundation
+import MediaPlayer
+import NitroModules
+
+/// Callbacks for all player events.
+///
+/// This protocol defines the interface for receiving events from TrackPlayer.
+/// HybridAudioBrowser implements this protocol to bridge events to JavaScript.
+/// Note: Method names are prefixed to avoid conflicts with JS callback property names.
+/// All callbacks are called from the main actor since TrackPlayer is @MainActor.
+///
+/// Extends PlaybackCoordinatorCallbacks for the state machine / coordinator callbacks,
+/// then adds metadata, seek, remote, and configuration callbacks that are TrackPlayer-specific.
+@MainActor
+protocol TrackPlayerCallbacks: PlaybackCoordinatorCallbacks {
+  // MARK: - Metadata Events
+
+  /// Called when common metadata is received.
+  func playerDidReceiveCommonMetadata(_ metadata: [AVMetadataItem])
+
+  /// Called when timed metadata is received.
+  func playerDidReceiveTimedMetadata(_ metadata: [AVTimedMetadataGroup])
+
+  /// Called when chapter metadata is received.
+  func playerDidReceiveChapterMetadata(_ metadata: [AVTimedMetadataGroup])
+
+  // MARK: - Playback Events
+
+  /// Called when a seek operation completes.
+  func playerDidCompleteSeek(position: Double, didFinish: Bool)
+
+  /// Called when the duration is updated.
+  func playerDidUpdateDuration(_ duration: Double)
+
+  // MARK: - Remote Control Events
+
+  /// Called when play is triggered remotely.
+  func remotePlay()
+
+  /// Called when pause is triggered remotely.
+  func remotePause()
+
+  /// Called when stop is triggered remotely.
+  func remoteStop()
+
+  /// Called when toggle play/pause is triggered remotely.
+  func remotePlayPause()
+
+  /// Called when next is triggered remotely.
+  func remoteNext()
+
+  /// Called when previous is triggered remotely.
+  func remotePrevious()
+
+  /// Called when jump forward is triggered remotely.
+  func remoteJumpForward(interval: Double)
+
+  /// Called when jump backward is triggered remotely.
+  func remoteJumpBackward(interval: Double)
+
+  /// Called when seek is triggered remotely.
+  func remoteSeek(position: Double)
+
+  /// Called when change playback position is triggered remotely.
+  func remoteChangePlaybackPosition(position: Double)
+
+  /// Called when set rating is triggered remotely.
+  func remoteSetRating(rating: Any)
+
+  /// Called when play from ID is triggered remotely.
+  func remotePlayId(id: String, index: Int?)
+
+  /// Called when play from search is triggered remotely.
+  func remotePlaySearch(query: String)
+
+  /// Called when like is triggered remotely.
+  func remoteLike()
+
+  /// Called when repeat mode change is triggered remotely (CarPlay/lock screen).
+  func remoteChangeRepeatMode(mode: RepeatMode)
+
+  /// Called when shuffle mode change is triggered remotely (CarPlay/lock screen).
+  func remoteChangeShuffleMode(enabled: Bool)
+
+  /// Called when playback rate change is triggered remotely (CarPlay/lock screen).
+  func remoteChangePlaybackRate(rate: Float)
+
+  // MARK: - Configuration Events
+
+  /// Called when options are changed.
+  func playerDidChangeOptions(_ options: PlayerUpdateOptions)
+}

package/ios/TrackSelector.swift

@@ -0,0 +1,141 @@
+import Foundation
+import os.log
+
+// MARK: - Protocols for testability
+
+@MainActor protocol TrackSelectionBrowser {
+  func awaitTrackLoadHandler(event: TrackLoadEvent) async -> Bool
+  func expandQueueFromContextualUrl(_ url: String) async throws -> (tracks: [Track], selectedIndex: Int)?
+}
+
+@MainActor protocol TrackSelectionPlayer {
+  var tracks: [Track] { get }
+  var queueSourcePath: String? { get }
+}
+
+/// Encapsulates the shared track selection decision tree used by both
+/// HybridAudioBrowser and CarPlayController.
+///
+/// Resolves a track selection to a concrete `SelectionResult` describing
+/// what the caller should do. Each caller then executes the action in its
+/// own way (CarPlay: showNowPlaying + completion; HybridAudioBrowser:
+/// direct player calls).
+@MainActor
+class TrackSelector {
+  private let logger = Logger(subsystem: "com.audiobrowser", category: "TrackSelector")
+  nonisolated(unsafe) private let browserManager: any TrackSelectionBrowser
+
+  nonisolated init(browserManager: any TrackSelectionBrowser) {
+    self.browserManager = browserManager
+  }
+
+  // MARK: - Result Types
+
+  enum SelectionResult {
+    /// Playback action determined and not intercepted by JS handler.
+    case play(PlaybackIntent)
+    /// JS handleTrackLoad handler intercepted — caller should not play.
+    case intercepted
+    /// Track is browsable — caller should navigate to this URL.
+    case browse(url: String)
+    /// Nothing to do (no src, no url).
+    case none
+  }
+
+  enum PlaybackIntent {
+    /// Skip to an index in the existing queue.
+    case skipTo(index: Int)
+    /// Replace queue with new tracks.
+    case setQueue(tracks: [Track], startIndex: Int, sourcePath: String?)
+    /// Load a single track.
+    case loadTrack(Track)
+  }
+
+  // MARK: - Selection
+
+  /// Resolves a track selection to a concrete action.
+  /// Handles contextual URL expansion, queue reuse, and handler interception.
+  func select(
+    track: Track,
+    player: some TrackSelectionPlayer
+  ) async -> SelectionResult {
+    let url = track.url
+
+    // 1. Contextual URL (playable-only track with queue context)
+    if let url, BrowserPathHelper.isContextual(url) {
+      return await handleContextualUrl(url, track: track, player: player)
+    }
+
+    // 2. Has src — single playable track
+    if track.src != nil {
+      return await handlePlayableTrack(track, player: player)
+    }
+
+    // 3. Has url — browsable
+    if let url {
+      return .browse(url: url)
+    }
+
+    // 4. Neither
+    return .none
+  }
+
+  // MARK: - Private Helpers
+
+  private func handleContextualUrl(
+    _ url: String,
+    track: Track,
+    player: some TrackSelectionPlayer
+  ) async -> SelectionResult {
+    let parentPath = BrowserPathHelper.stripTrackId(url)
+    let trackId = BrowserPathHelper.extractTrackId(url)
+
+    // Check if queue already came from this parent path — just skip to the track
+    if let trackId,
+       parentPath == player.queueSourcePath,
+       let index = player.tracks.firstIndex(where: { $0.src == trackId })
+    {
+      logger.debug("Queue already from \(parentPath), skipping to index \(index)")
+      let queue = player.tracks
+      let event = TrackLoadEvent(track: track, queue: queue, startIndex: Double(index))
+      if await browserManager.awaitTrackLoadHandler(event: event) {
+        return .intercepted
+      }
+      return .play(.skipTo(index: index))
+    }
+
+    // Expand the queue from the contextual URL
+    do {
+      if let expanded = try await browserManager.expandQueueFromContextualUrl(url) {
+        let (tracks, startIndex) = expanded
+        let event = TrackLoadEvent(track: track, queue: tracks, startIndex: Double(startIndex))
+        if await browserManager.awaitTrackLoadHandler(event: event) {
+          return .intercepted
+        }
+        return .play(.setQueue(tracks: tracks, startIndex: startIndex, sourcePath: parentPath))
+      } else {
+        // Fallback: single track
+        return await singleTrackResult(track)
+      }
+    } catch {
+      logger.error("Error expanding queue: \(error.localizedDescription)")
+      // Fallback to single track
+      return await singleTrackResult(track)
+    }
+  }
+
+  private func handlePlayableTrack(
+    _ track: Track,
+    player: some TrackSelectionPlayer
+  ) async -> SelectionResult {
+    return await singleTrackResult(track)
+  }
+
+  private func singleTrackResult(_ track: Track) async -> SelectionResult {
+    let event = TrackLoadEvent(track: track, queue: [track], startIndex: 0)
+    if await browserManager.awaitTrackLoadHandler(event: event) {
+      return .intercepted
+    }
+    return .play(.loadTrack(track))
+  }
+}

package/ios/Util/ArtworkImageFetcher.swift

@@ -0,0 +1,35 @@
+import Kingfisher
+import NitroModules
+import UIKit
+import os.log
+
+/// Single entry point for loading artwork images from URLs via Kingfisher.
+enum ArtworkImageFetcher {
+  private static let logger = Logger(subsystem: "com.audiobrowser", category: "ArtworkImageFetcher")
+
+  @MainActor
+  static func fetchImage(from source: ImageSource, svgScale: CGFloat? = nil) async -> UIImage? {
+    guard let url = URL(string: source.uri) else { return nil }
+
+    var options: KingfisherOptionsInfo = []
+    if let headers = source.headers, !headers.isEmpty {
+      let modifier = AnyModifier { request in
+        var request = request
+        for (key, value) in headers { request.setValue(value, forHTTPHeaderField: key) }
+        return request
+      }
+      options.append(.requestModifier(modifier))
+    }
+    if let svgScale {
+      options.append(.processor(SVGProcessor(size: nil, scale: svgScale)))
+    }
+
+    do {
+      let result = try await KingfisherManager.shared.retrieveImage(with: url, options: options)
+      return result.image
+    } catch {
+      logger.error("Failed to load artwork from \(source.uri): \(error.localizedDescription)")
+      return nil
+    }
+  }
+}

package/ios/Util/Emitter.swift

@@ -0,0 +1,68 @@
+import Foundation
+
+/// Opaque token returned by `addListener` for targeted removal.
+public struct EmitterToken: Sendable {
+  fileprivate let id: Int
+}
+
+/// Generic event emitter that allows multiple listeners for a single event type
+public final class Emitter<T>: @unchecked Sendable {
+  private let lock = NSLock()
+  private var nextId = 0
+  private var snapshot: [(id: Int, handler: (T) -> Void)] = []
+
+  public init() {}
+
+  /// Adds a listener to this emitter
+  /// - Parameter listener: The callback to invoke when an event is emitted
+  /// - Returns: A token that can be passed to `removeListener` for targeted removal
+  @discardableResult
+  public func addListener(_ listener: @escaping (T) -> Void) -> EmitterToken {
+    lock.lock()
+    defer { lock.unlock() }
+
+    let id = nextId
+    nextId += 1
+    var next = snapshot
+    next.append((id: id, handler: listener))
+    snapshot = next
+    return EmitterToken(id: id)
+  }
+
+  /// Removes a specific listener by its token
+  /// - Parameter token: The token returned by `addListener`
+  public func removeListener(_ token: EmitterToken) {
+    lock.lock()
+    defer { lock.unlock() }
+
+    var next = snapshot
+    next.removeAll { $0.id == token.id }
+    snapshot = next
+  }
+
+  /// Removes all listeners
+  public func removeAllListeners() {
+    lock.lock()
+    defer { lock.unlock() }
+    snapshot = []
+  }
+
+  /// Emits an event to all registered listeners
+  /// - Parameter event: The event data to emit
+  public func emit(_ event: T) {
+    lock.lock()
+    let current = snapshot // O(1) reference bump; no array copy here
+    lock.unlock()
+
+    for entry in current {
+      entry.handler(event)
+    }
+  }
+
+  /// Returns the number of registered listeners
+  public var listenerCount: Int {
+    lock.lock()
+    defer { lock.unlock() }
+    return snapshot.count
+  }
+}

package/ios/Util/LRUCache.swift

@@ -0,0 +1,182 @@
+import Foundation
+
+/// A thread-safe Least Recently Used (LRU) cache with O(1) operations.
+///
+/// When the cache exceeds its maximum size, the least recently accessed
+/// items are evicted to make room for new entries.
+///
+/// Uses a doubly-linked list + dictionary for O(1) get/set/remove operations.
+final class LRUCache<Key: Hashable, Value> {
+  /// Doubly-linked list node for O(1) removal and reordering.
+  private final class Node {
+    let key: Key
+    var value: Value
+    var prev: Node?
+    var next: Node?
+
+    init(key: Key, value: Value) {
+      self.key = key
+      self.value = value
+    }
+  }
+
+  private let maxSize: Int
+  private var cache: [Key: Node] = [:]
+  private var head: Node? // Most recently used
+  private var tail: Node? // Least recently used
+  private let lock = NSLock()
+
+  /// Creates a new LRU cache with the specified maximum size.
+  ///
+  /// - Parameter maxSize: The maximum number of items the cache can hold
+  init(maxSize: Int) {
+    self.maxSize = maxSize
+  }
+
+  /// Moves a node to the head (most recently used position).
+  private func moveToHead(_ node: Node) {
+    guard node !== head else { return }
+
+    // Remove from current position
+    node.prev?.next = node.next
+    node.next?.prev = node.prev
+
+    if node === tail {
+      tail = node.prev
+    }
+
+    // Insert at head
+    node.prev = nil
+    node.next = head
+    head?.prev = node
+    head = node
+
+    if tail == nil {
+      tail = node
+    }
+  }
+
+  /// Removes a node from the list.
+  private func removeNode(_ node: Node) {
+    node.prev?.next = node.next
+    node.next?.prev = node.prev
+
+    if node === head {
+      head = node.next
+    }
+    if node === tail {
+      tail = node.prev
+    }
+
+    node.prev = nil
+    node.next = nil
+  }
+
+  /// Adds a node at the head (most recently used position).
+  private func addToHead(_ node: Node) {
+    node.prev = nil
+    node.next = head
+    head?.prev = node
+    head = node
+
+    if tail == nil {
+      tail = node
+    }
+  }
+
+  /// Removes and returns the tail node (least recently used).
+  private func removeTail() -> Node? {
+    guard let tailNode = tail else { return nil }
+    removeNode(tailNode)
+    return tailNode
+  }
+
+  /// Gets a value from the cache, updating its access order.
+  ///
+  /// - Parameter key: The key to look up
+  /// - Returns: The cached value, or nil if not found
+  func get(_ key: Key) -> Value? {
+    lock.lock()
+    defer { lock.unlock() }
+
+    guard let node = cache[key] else {
+      return nil
+    }
+
+    // Move to head (most recently used)
+    moveToHead(node)
+    return node.value
+  }
+
+  /// Sets a value in the cache.
+  ///
+  /// If the cache is full, the least recently used item is evicted.
+  ///
+  /// - Parameters:
+  ///   - key: The key to store
+  ///   - value: The value to store
+  func set(_ key: Key, value: Value) {
+    lock.lock()
+    defer { lock.unlock() }
+
+    // If key exists, update value and move to head
+    if let existingNode = cache[key] {
+      existingNode.value = value
+      moveToHead(existingNode)
+      return
+    }
+
+    // Evict oldest if at capacity
+    if cache.count >= maxSize, let evicted = removeTail() {
+      cache.removeValue(forKey: evicted.key)
+    }
+
+    // Add new entry at head
+    let newNode = Node(key: key, value: value)
+    cache[key] = newNode
+    addToHead(newNode)
+  }
+
+  /// Removes a value from the cache.
+  ///
+  /// - Parameter key: The key to remove
+  func remove(_ key: Key) {
+    lock.lock()
+    defer { lock.unlock() }
+
+    guard let node = cache[key] else { return }
+    removeNode(node)
+    cache.removeValue(forKey: key)
+  }
+
+  /// Clears all entries from the cache.
+  func clear() {
+    lock.lock()
+    defer { lock.unlock() }
+
+    cache.removeAll()
+    head = nil
+    tail = nil
+  }
+
+  /// The current number of items in the cache.
+  var count: Int {
+    lock.lock()
+    defer { lock.unlock() }
+    return cache.count
+  }
+
+  /// Returns all values in the cache (no particular order guaranteed).
+  var values: [Value] {
+    lock.lock()
+    defer { lock.unlock() }
+    return cache.values.map(\.value)
+  }
+
+  /// Returns all keys in the cache (no particular order guaranteed).
+  var keys: [Key] {
+    lock.lock()
+    defer { lock.unlock() }
+    return Array(cache.keys)
+  }
+}

package/ios/Util/MetadataAdapter.swift

@@ -0,0 +1,131 @@
+import AVFoundation
+import Foundation
+
+typealias RawMetadataGroup = [[String: Any]]
+
+class MetadataAdapter {
+  private static func getMetadataItem(
+    metadata: [AVMetadataItem],
+    forIdentifier: AVMetadataIdentifier,
+  ) -> String? {
+    AVMetadataItem.metadataItems(from: metadata, filteredByIdentifier: forIdentifier).first?
+      .stringValue
+  }
+
+  private static func convertToSerializableItems(items: [AVMetadataItem]) -> RawMetadataGroup {
+    var rawGroup: RawMetadataGroup = []
+
+    for metadataItem in items {
+      var rawMetadataItem: [String: Any] = [:]
+
+      if CMTIME_IS_VALID(metadataItem.time), CMTIME_IS_NUMERIC(metadataItem.time) {
+        rawMetadataItem["time"] = metadataItem.time.seconds
+      }
+
+      rawMetadataItem["value"] = metadataItem.value
+      rawMetadataItem["key"] = metadataItem.key
+      if let commonKey = metadataItem.commonKey?.rawValue {
+        rawMetadataItem["commonKey"] = commonKey
+      }
+      if let keySpace = metadataItem.keySpace?.rawValue {
+        rawMetadataItem["keySpace"] = keySpace
+      }
+
+      rawGroup.append(rawMetadataItem)
+    }
+
+    return rawGroup
+  }
+
+  // MARK: - Public
+
+  static func convertToGroupedMetadata(metadataGroups: [AVTimedMetadataGroup]) -> RawMetadataGroup {
+    var ret: RawMetadataGroup = []
+
+    for metadataGroup in metadataGroups {
+      let entry = convertToCommonMetadata(metadata: metadataGroup.items)
+      ret.append(entry)
+    }
+
+    return ret
+  }
+
+  static func convertToCommonMetadata(
+    metadata: [AVMetadataItem],
+    skipRaw: Bool = false,
+  ) -> [String: Any] {
+    var rawMetadataItem: [String: Any] = [:]
+    rawMetadataItem["title"] = getMetadataItem(
+      metadata: metadata,
+      forIdentifier: .commonIdentifierTitle,
+    )
+    rawMetadataItem["artist"] = getMetadataItem(
+      metadata: metadata,
+      forIdentifier: .commonIdentifierArtist,
+    )
+    rawMetadataItem["albumName"] = getMetadataItem(
+      metadata: metadata,
+      forIdentifier: .commonIdentifierAlbumName,
+    )
+    rawMetadataItem["subtitle"] = getMetadataItem(
+      metadata: metadata,
+      forIdentifier: .id3MetadataSetSubtitle,
+    )
+      ?? getMetadataItem(metadata: metadata, forIdentifier: .iTunesMetadataTrackSubTitle)
+    rawMetadataItem["description"] = getMetadataItem(
+      metadata: metadata,
+      forIdentifier: .commonIdentifierDescription,
+    )
+    rawMetadataItem["artworkUri"] = getMetadataItem(
+      metadata: metadata,
+      forIdentifier: .commonIdentifierArtwork,
+    )
+    rawMetadataItem["trackNumber"] = getMetadataItem(
+      metadata: metadata,
+      forIdentifier: .id3MetadataTrackNumber,
+    )
+      ?? getMetadataItem(metadata: metadata, forIdentifier: .iTunesMetadataTrackNumber)
+    rawMetadataItem["composer"] = getMetadataItem(
+      metadata: metadata,
+      forIdentifier: .id3MetadataComposer,
+    )
+      ?? getMetadataItem(metadata: metadata, forIdentifier: .iTunesMetadataComposer)
+      ?? getMetadataItem(metadata: metadata, forIdentifier: .quickTimeMetadataComposer)
+    rawMetadataItem["conductor"] = getMetadataItem(
+      metadata: metadata,
+      forIdentifier: .id3MetadataConductor,
+    )
+      ?? getMetadataItem(metadata: metadata, forIdentifier: .iTunesMetadataConductor)
+    rawMetadataItem["genre"] = getMetadataItem(
+      metadata: metadata,
+      forIdentifier: .quickTimeMetadataGenre,
+    )
+    rawMetadataItem["compilation"] = getMetadataItem(
+      metadata: metadata,
+      forIdentifier: .iTunesMetadataDiscCompilation,
+    )
+    rawMetadataItem["station"] = getMetadataItem(
+      metadata: metadata,
+      forIdentifier: .id3MetadataInternetRadioStationName,
+    )
+    rawMetadataItem["mediaType"] = getMetadataItem(
+      metadata: metadata,
+      forIdentifier: .id3MetadataMediaType,
+    )
+    rawMetadataItem["creationDate"] = getMetadataItem(
+      metadata: metadata,
+      forIdentifier: .commonIdentifierCreationDate,
+    )
+    rawMetadataItem["creationYear"] = getMetadataItem(
+      metadata: metadata,
+      forIdentifier: .id3MetadataYear,
+    )
+      ?? getMetadataItem(metadata: metadata, forIdentifier: .quickTimeMetadataYear)
+
+    if !skipRaw {
+      rawMetadataItem["raw"] = convertToSerializableItems(items: metadata)
+    }
+
+    return rawMetadataItem
+  }
+}