@5stones/react-native-audio-browser 0.1.0

package/ios/TrackPlayerCallbacks.swift

@@ -0,0 +1,121 @@
+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.
+@MainActor
+protocol TrackPlayerCallbacks: AnyObject {
+  // MARK: - Playback State Events
+
+  /// Called when the playback state changes (state + error).
+  func playerDidChangePlayback(_ playback: Playback)
+
+  /// Called when the active track changes.
+  func playerDidChangeActiveTrack(_ event: PlaybackActiveTrackChangedEvent)
+
+  /// Called periodically with playback progress updates.
+  func playerDidUpdateProgress(_ event: PlaybackProgressUpdatedEvent)
+
+  /// Called when playWhenReady changes.
+  func playerDidChangePlayWhenReady(_ playWhenReady: Bool)
+
+  /// Called when the playing state changes (playing or buffering flags).
+  func playerDidChangePlayingState(_ state: PlayingState)
+
+  /// Called when the playback queue ends (player reaches the end of the last track).
+  func playerDidEndQueue(_ event: PlaybackQueueEndedEvent)
+
+  /// Called when the queue changes (tracks added, removed, or replaced).
+  func playerDidChangeQueue(_ tracks: [Track])
+
+  /// Called when the repeat mode changes.
+  func playerDidChangeRepeatMode(_ event: RepeatModeChangedEvent)
+
+  /// Called when shuffle mode changes.
+  func playerDidChangeShuffleEnabled(_ enabled: Bool)
+
+  /// Called when the player encounters an error.
+  func playerDidError(_ event: PlaybackErrorEvent)
+
+  // 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/Util/Emitter.swift

@@ -0,0 +1,46 @@
+import Foundation
+
+/// 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 snapshot: [(T) -> Void] = []
+
+  public init() {}
+
+  /// Adds a listener to this emitter
+  /// - Parameter listener: The callback to invoke when an event is emitted
+  public func addListener(_ listener: @escaping (T) -> Void) {
+    lock.lock()
+    defer { lock.unlock() }
+
+    var next = snapshot
+    next.append(listener)
+    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 listener in current {
+      listener(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
+  }
+}

package/ios/Util/NetworkMonitor.swift

@@ -0,0 +1,68 @@
+import Foundation
+import Network
+import os.log
+
+/// Monitors network connectivity state using NWPathMonitor.
+/// Notifies listeners when the connection state changes.
+final class NetworkMonitor: @unchecked Sendable {
+  // MARK: - Properties
+
+  private let logger = Logger(subsystem: "com.audiobrowser", category: "NetworkMonitor")
+  private let monitor: NWPathMonitor
+  private let queue = DispatchQueue(label: "com.audiobrowser.networkmonitor")
+
+  /// Current network connectivity state
+  private(set) var isOnline: Bool = false {
+    didSet {
+      if oldValue != isOnline {
+        logger.info("Network status changed: \(oldValue) -> \(self.isOnline)")
+        DispatchQueue.main.async { [weak self] in
+          guard let self else { return }
+          onChanged?(isOnline)
+        }
+      }
+    }
+  }
+
+  /// Callback invoked when network state changes
+  var onChanged: ((Bool) -> Void)?
+
+  // MARK: - Initialization
+
+  init() {
+    monitor = NWPathMonitor()
+
+    // Set up handler before starting
+    monitor.pathUpdateHandler = { [weak self] path in
+      let newStatus = path.status == .satisfied
+      DispatchQueue.main.async {
+        self?.isOnline = newStatus
+      }
+    }
+
+    // Start monitoring
+    monitor.start(queue: queue)
+
+    // Read initial state after starting (currentPath is now valid)
+    let initialStatus = monitor.currentPath.status == .satisfied
+    logger.info("NetworkMonitor initialized, initial isOnline=\(initialStatus)")
+    isOnline = initialStatus
+  }
+
+  // MARK: - Public Methods
+
+  /// Gets the current network connectivity state.
+  /// - Returns: true if device is online, false otherwise
+  func getOnline() -> Bool {
+    isOnline
+  }
+
+  /// Stops monitoring and cleans up resources.
+  func destroy() {
+    monitor.cancel()
+  }
+
+  deinit {
+    destroy()
+  }
+}

package/ios/Util/OnceValue.swift

@@ -0,0 +1,70 @@
+import Foundation
+
+/// A thread-safe primitive that resolves to a value once, allowing multiple waiters.
+/// Once resolved, all current and future `wait()` calls return immediately with the value.
+final class OnceValue<T: Sendable>: @unchecked Sendable {
+  private var continuations: [CheckedContinuation<T, Never>] = []
+  private var value: T?
+  private let lock = NSLock()
+  private let provider: (() -> T?)?
+
+  /// Creates a OnceValue with a provider closure that returns the value when ready.
+  /// Call `check()` to attempt resolution using the provider.
+  init(provider: @escaping () -> T?) {
+    self.provider = provider
+  }
+
+  /// Creates a OnceValue without a provider. Use `resolve(_:)` to set the value manually.
+  init() {
+    self.provider = nil
+  }
+
+  /// Checks if the value is ready using the provider closure.
+  /// If the provider returns a value, resolves and resumes all waiters.
+  func check() {
+    guard let provider, let value = provider() else { return }
+    resolve(value)
+  }
+
+  /// Resolves the value, resuming all waiting continuations.
+  /// Subsequent calls are ignored if already resolved.
+  func resolve(_ value: T) {
+    lock.lock()
+    guard self.value == nil else {
+      lock.unlock()
+      return
+    }
+    self.value = value
+    let pending = continuations
+    continuations.removeAll()
+    lock.unlock()
+
+    for continuation in pending {
+      continuation.resume(returning: value)
+    }
+  }
+
+  /// Waits for the value to be resolved. Returns immediately if already resolved.
+  func wait() async -> T {
+    // All lock operations happen inside the synchronous continuation closure
+    // to avoid Swift concurrency warnings about locks in async contexts
+    await withCheckedContinuation { continuation in
+      lock.lock()
+      if let value {
+        lock.unlock()
+        continuation.resume(returning: value)
+      } else {
+        continuations.append(continuation)
+        lock.unlock()
+      }
+    }
+  }
+
+  /// Resets the value, allowing it to be resolved again.
+  /// Any pending waiters will continue waiting for the next resolve.
+  func reset() {
+    lock.lock()
+    value = nil
+    lock.unlock()
+  }
+}

package/ios/Util/SVGProcessor.swift

@@ -0,0 +1,56 @@
+import Kingfisher
+import SwiftDraw
+import UIKit
+
+/// Kingfisher processor that renders SVG data to UIImage using SwiftDraw.
+struct SVGProcessor: ImageProcessor {
+  let identifier = "com.audiobrowser.svgprocessor"
+
+  /// Target size for rendering (in points). If nil, uses SVG's intrinsic size.
+  let size: CGSize?
+
+  /// Scale factor for rendering. Resolved at init time to avoid MainActor issues.
+  let scale: CGFloat
+
+  @MainActor
+  init(size: CGSize? = nil, scale: CGFloat? = nil) {
+    self.size = size
+    self.scale = scale ?? UIScreen.main.scale
+  }
+
+  func process(item: ImageProcessItem, options _: KingfisherParsedOptionsInfo) -> KFCrossPlatformImage? {
+    switch item {
+    case let .data(data):
+      return renderSVG(from: data)
+    case let .image(image):
+      // Already an image, return as-is
+      return image
+    @unknown default:
+      return nil
+    }
+  }
+
+  private func renderSVG(from data: Data) -> UIImage? {
+    guard let svg = SVG(data: data) else {
+      return nil
+    }
+
+    let renderSize: CGSize = if let size {
+      size
+    } else {
+      svg.size
+    }
+
+    return svg.rasterize(size: renderSize, scale: scale)
+  }
+}
+
+// MARK: - Kingfisher Options Extension
+
+extension KingfisherOptionsInfoItem {
+  /// Returns an SVG processor option for Kingfisher.
+  @MainActor
+  static func svgProcessor(size: CGSize? = nil, scale: CGFloat? = nil) -> KingfisherOptionsInfoItem {
+    .processor(SVGProcessor(size: size, scale: scale))
+  }
+}