@5stones/react-native-audio-browser 0.1.5 → 0.2.0

package/src/features/remoteControls.ts

@@ -4,6 +4,7 @@ import type {
   StarRating,
   ThumbsRating
 } from './rating'
+import type { Track } from '../types'
 import { nativeBrowser } from '../native'
 import { LazyNativeEmitter } from '../utils/LazyNativeEmitter'
 
@@ -66,6 +67,18 @@ export interface RemoteSkipEvent {
   index: number
 }
 
+/**
+ * Remote load event, fired when a track is about to be loaded via navigateTrack.
+ */
+export interface RemoteLoadEvent {
+  /** The track that will be loaded */
+  track: Track
+  /** The resolved queue of tracks */
+  queue: Track[]
+  /** The index of the track in the queue */
+  startIndex: number
+}
+
 // MARK: - Default Handlers
 
 // Install remote control handlers with default behavior immediately when module loads
@@ -221,6 +234,17 @@ export function handleRemoteJumpBackward(
   nativeBrowser.handleRemoteJumpBackward = callback
 }
 
+/**
+ * Sets a custom handler for remote load events, overriding the default track loading behavior.
+ * When set, navigateTrack() will call this handler instead of auto-loading/playing the track.
+ * @param callback - Called with the track, queue, and startIndex. Pass undefined to restore default behavior.
+ */
+export function handleRemoteLoad(
+  callback: ((event: RemoteLoadEvent) => void) | undefined
+) {
+  nativeBrowser.handleRemoteLoad = callback
+}
+
 // MARK: - Event Callbacks (for listening/debugging only)
 //
 // Use these functions when you want to LISTEN to remote control events without overriding
@@ -248,6 +272,17 @@ export const onRemoteJumpForward =
     (cb) => (nativeBrowser.onRemoteJumpForward = cb)
   )
 
+/**
+ * Subscribes to remote load events.
+ * Fires whenever a track is about to be loaded via navigateTrack(),
+ * regardless of whether handleRemoteLoad is set.
+ * @param callback - Called with the track, queue, and startIndex
+ * @returns Cleanup function to unsubscribe
+ */
+export const onRemoteLoad = LazyNativeEmitter.emitterize<RemoteLoadEvent>(
+  (cb) => (nativeBrowser.onRemoteLoad = cb)
+)
+
 /**
  * Subscribes to remote next events.
  * @param callback - Called when the user presses the next track button

package/src/specs/audio-browser.nitro.ts

@@ -43,6 +43,7 @@ import type {
   RemoteJumpForwardEvent,
   RemotePlayIdEvent,
   RemotePlaySearchEvent,
+  RemoteLoadEvent,
   RemoteSeekEvent,
   RemoteSetRatingEvent,
   RemoteSkipEvent
@@ -138,6 +139,7 @@ export interface AudioBrowser extends HybridObject<{
   onRemoteJumpBackward: (event: RemoteJumpBackwardEvent) => void
   onRemoteJumpForward: (event: RemoteJumpForwardEvent) => void
   onRemoteLike: () => void
+  onRemoteLoad: (event: RemoteLoadEvent) => void
   onRemoteNext: () => void
   onRemotePause: () => void
   onRemotePlay: () => void
@@ -160,6 +162,7 @@ export interface AudioBrowser extends HybridObject<{
     | undefined
   handleRemoteJumpForward: ((event: RemoteJumpForwardEvent) => void) | undefined
   handleRemoteLike: (() => void) | undefined
+  handleRemoteLoad: ((event: RemoteLoadEvent) => void) | undefined
   handleRemoteNext: (() => void) | undefined
   handleRemotePause: (() => void) | undefined
   handleRemotePlay: (() => void) | undefined

package/src/web/NativeAudioBrowser.ts

@@ -17,6 +17,7 @@ import type {
   PlaybackPlayWhenReadyChangedEvent,
   RemoteJumpBackwardEvent,
   RemoteJumpForwardEvent,
+  RemoteLoadEvent,
   RemotePlayIdEvent,
   RemotePlaySearchEvent,
   RemoteSeekEvent,
@@ -162,6 +163,7 @@ export class NativeAudioBrowser
   onRemoteJumpBackward: (event: RemoteJumpBackwardEvent) => void = () => {}
   onRemoteJumpForward: (event: RemoteJumpForwardEvent) => void = () => {}
   onRemoteLike: () => void = () => {}
+  onRemoteLoad: (event: RemoteLoadEvent) => void = () => {}
   onRemoteNext: () => void = () => {}
   onRemotePause: () => void = () => {}
   onRemotePlay: () => void = () => {}
@@ -196,6 +198,7 @@ export class NativeAudioBrowser
     | ((event: RemoteJumpForwardEvent) => void)
     | undefined = undefined
   handleRemoteLike: (() => void) | undefined = undefined
+  handleRemoteLoad: ((event: RemoteLoadEvent) => void) | undefined = undefined
   handleRemoteNext: (() => void) | undefined = undefined
   handleRemotePause: (() => void) | undefined = undefined
   handleRemotePlay: (() => void) | undefined = undefined
@@ -349,6 +352,28 @@ export class NativeAudioBrowser
     void this.navigateTrackAsync(track, url)
   }
 
+  /**
+   * Centralizes handleRemoteLoad interception logic.
+   * If handleRemoteLoad is set, calls it (intercepted). Otherwise runs defaultBehavior.
+   * Always fires onRemoteLoad afterward.
+   *
+   * @returns true if the handler intercepted, false if defaultBehavior ran
+   */
+  private handleLoad(
+    track: Track, queue: Track[], startIndex: number,
+    defaultBehavior: () => void
+  ): boolean {
+    const event: RemoteLoadEvent = { track, queue, startIndex }
+    const handled = !!this.handleRemoteLoad
+    if (this.handleRemoteLoad) {
+      this.handleRemoteLoad(event)
+    } else {
+      defaultBehavior()
+    }
+    this.onRemoteLoad(event)
+    return handled
+  }
+
   /**
    * Attempts to skip to a track already in the current queue.
    * Used as an optimization to avoid re-expanding the queue.
@@ -372,8 +397,10 @@ export class NativeAudioBrowser
       return false
     }
 
-    this.skip(index)
-    this.play()
+    this.handleLoad(queue[index]!, queue, index, () => {
+      this.skip(index)
+      this.play()
+    })
     return true
   }
 
@@ -394,7 +421,9 @@ export class NativeAudioBrowser
       return false
     }
 
-    this.setQueue(result.tracks, result.startIndex)
+    this.handleLoad(track, result.tracks, result.startIndex, () => {
+      this.setQueue(result.tracks, result.startIndex)
+    })
     return true
   }
 
@@ -423,7 +452,7 @@ export class NativeAudioBrowser
         }
 
         // Fallback: load single track if expansion fails
-        this.load(track)
+        this.handleLoad(track, [track], 0, () => this.load(track))
         return
       }
 
@@ -437,7 +466,7 @@ export class NativeAudioBrowser
 
       // Handle playable track (has src but no URL)
       if (track.src) {
-        this.load(track)
+        this.handleLoad(track, [track], 0, () => this.load(track))
         return
       }