react-native-audio-browser 0.1.1 → 0.2.0-next.10

package/src/features/queue/activeTrack.ts

@@ -41,7 +41,7 @@ export function getActiveTrackIndex(): number | undefined {
 /**
  * Subscribes to active track change events.
  * @param callback - Called when the active track changes
- * @returns Cleanup function to unsubscribe
+ * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
  */
 export const onActiveTrackChanged =
   NativeUpdatedValue.emitterize<PlaybackActiveTrackChangedEvent>(

package/src/features/queue/queue.test.ts

@@ -0,0 +1,36 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+
+const calls: any[] = []
+vi.mock('../../native', () => ({
+  nativeBrowser: {
+    setQueue: (...a: any[]) => calls.push(['setQueue', ...a]),
+    play: () => calls.push(['play'])
+  }
+}))
+
+import { setQueue } from './queue'
+
+describe('setQueue wrapper', () => {
+  beforeEach(() => {
+    calls.length = 0
+  })
+
+  it('threads startIndex and startPosition to native', () => {
+    const tracks = [{ src: 'a' }, { src: 'b' }] as any
+    setQueue(tracks, 1, 5)
+    expect(calls).toContainEqual(['setQueue', tracks, 1, 5])
+  })
+
+  it('forwards startIndex even when startPosition is omitted', () => {
+    const tracks = [{ src: 'a' }, { src: 'b' }] as any
+    setQueue(tracks, 1)
+    expect(calls[0]).toEqual(['setQueue', tracks, 1, undefined])
+  })
+
+  it('only sets the queue and does not start playback', () => {
+    setQueue([{ src: 'a' }] as any, 0)
+    // setQueue no longer auto-plays — it preserves the current play/pause
+    // state; callers start playback explicitly with play().
+    expect(calls.map((c) => c[0])).toEqual(['setQueue'])
+  })
+})

package/src/features/queue/queue.ts

@@ -115,11 +115,22 @@ export function skipToPrevious(initialPosition?: number): void {
 }
 
 /**
- * Sets the queue.
+ * Sets (replaces) the queue.
+ *
+ * This does not change the play/pause state: the player keeps playing if it was
+ * playing and stays paused if it was paused. Call `play` explicitly to
+ * start playback.
+ *
  * @param tracks - The tracks to set as the queue.
- */
-export function setQueue(tracks: Track[]): void {
-  nativeBrowser.setQueue(tracks)
+ * @param startIndex - (Optional) The index of the track to make active.
+ * @param startPosition - (Optional) The position in seconds to start the active track from.
+ */
+export function setQueue(
+  tracks: Track[],
+  startIndex?: number,
+  startPosition?: number
+): void {
+  nativeBrowser.setQueue(tracks, startIndex, startPosition)
 }
 
 // MARK: - Getters
@@ -145,7 +156,7 @@ export function getQueue(): Track[] {
 /**
  * Subscribes to playback queue ended events.
  * @param callback - Called when playback has paused due to reaching the end of the queue
- * @returns Cleanup function to unsubscribe
+ * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
  */
 export const onQueueEnded =
   NativeUpdatedValue.emitterize<PlaybackQueueEndedEvent>(
@@ -156,7 +167,7 @@ export const onQueueEnded =
  * Subscribes to queue change events.
  * Called when tracks are added, removed, reordered, or when track metadata changes.
  * @param callback - Called with the updated queue
- * @returns Cleanup function to unsubscribe
+ * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
  */
 export const onQueueChanged = NativeUpdatedValue.emitterize<Track[]>(
   (cb) => (nativeBrowser.onPlaybackQueueChanged = cb)

package/src/features/queue/repeatMode.ts

@@ -40,7 +40,7 @@ export interface RepeatModeChangedEvent {
 /**
  * Subscribes to repeat mode changes.
  * @param callback - Called when repeat mode changes
- * @returns Cleanup function to unsubscribe
+ * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
  */
 export const onRepeatModeChanged =
   NativeUpdatedValue.emitterize<RepeatModeChangedEvent>(

package/src/features/queue/shuffle.ts

@@ -32,7 +32,7 @@ export function toggleShuffle(): void {
 /**
  * Subscribes to shuffle mode changes.
  * @param callback - Called when shuffle mode changes
- * @returns Cleanup function to unsubscribe
+ * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
  */
 export const onShuffleChanged = NativeUpdatedValue.emitterize<boolean>(
   (cb) => (nativeBrowser.onPlaybackShuffleModeChanged = cb)

package/src/features/remoteControls.ts

@@ -1,9 +1,3 @@
-import type {
-  HeartRating,
-  PercentageRating,
-  StarRating,
-  ThumbsRating
-} from './rating'
 import { nativeBrowser } from '../native'
 import { LazyNativeEmitter } from '../utils/LazyNativeEmitter'
 
@@ -51,13 +45,6 @@ export interface RemoteSeekEvent {
   position: number
 }
 
-/**
- * Remote set rating event.
- */
-export interface RemoteSetRatingEvent {
-  rating: HeartRating | ThumbsRating | StarRating | PercentageRating
-}
-
 /**
  * Remote skip event (Android only).
  */
@@ -66,90 +53,11 @@ export interface RemoteSkipEvent {
   index: number
 }
 
-// MARK: - Default Handlers
-
-// Install remote control handlers with default behavior immediately when module loads
-// Custom handlers can override the defaults using handleRemote* functions
-
-// Basic playback controls
-// AudioBrowser.onRemotePlay(() => {
-//   const customHandler = customHandlers.get('play')
-//   if (customHandler) {
-//     customHandler()
-//   } else {
-//     play()
-//   }
-// })
-
-// AudioBrowser.onRemotePause(() => {
-//   const customHandler = customHandlers.get('pause')
-//   if (customHandler) {
-//     customHandler()
-//   } else {
-//     pause()
-//   }
-// })
-
-// AudioBrowser.onRemoteNext(() => {
-//   const customHandler = customHandlers.get('next')
-//   if (customHandler) {
-//     customHandler()
-//   } else {
-//     skipToNext()
-//   }
-// })
-
-// AudioBrowser.onRemotePrevious(() => {
-//   const customHandler = customHandlers.get('previous')
-//   if (customHandler) {
-//     customHandler()
-//   } else {
-//     skipToPrevious()
-//   }
-// })
-
-// AudioBrowser.onRemoteStop(() => {
-//   const customHandler = customHandlers.get('stop')
-//   if (customHandler) {
-//     customHandler()
-//   } else {
-//     stop()
-//   }
-// })
-
-// // Seek controls
-// AudioBrowser.onRemoteSeek((event: any) => {
-//   const customHandler = customHandlers.get('seek')
-//   if (customHandler) {
-//     customHandler(event)
-//   } else {
-//     seekTo(event.position)
-//   }
-// })
-
-// AudioBrowser.onRemoteJumpForward((event: any) => {
-//   const customHandler = customHandlers.get('jumpForward')
-//   if (customHandler) {
-//     customHandler(event)
-//   } else {
-//     seekBy(event.interval)
-//   }
-// })
-
-// AudioBrowser.onRemoteJumpBackward((event: any) => {
-//   const customHandler = customHandlers.get('jumpBackward')
-//   if (customHandler) {
-//     customHandler(event)
-//   } else {
-//     seekBy(-event.interval)
-//   }
-// })
-
 // MARK: - Handler Override Functions
 //
 // Use these functions when you want to OVERRIDE the default remote control behavior.
 // These will replace the default handlers with your custom logic.
-// If you just want to listen to events for debugging/logging, use the onRemote* functions below.
+// If you just want to listen to events for debugging/logging, use the onRemote* emitters below.
 
 /**
  * Sets a custom handler for remote play events, overriding the default behavior.
@@ -223,7 +131,7 @@ export function handleRemoteJumpBackward(
 
 // MARK: - Event Callbacks (for listening/debugging only)
 //
-// Use these functions when you want to LISTEN to remote control events without overriding
+// Use these emitters when you want to LISTEN to remote control events without overriding
 // the default behavior. These are perfect for logging, analytics, or debugging.
 // Multiple listeners can be registered for the same event.
 // To override the default behavior, use the handleRemote* functions above.
@@ -231,7 +139,7 @@ export function handleRemoteJumpBackward(
 /**
  * Subscribes to remote jump backward events.
  * @param callback - Called when the user presses the jump backward button
- * @returns Cleanup function to unsubscribe
+ * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
  */
 export const onRemoteJumpBackward =
   LazyNativeEmitter.emitterize<RemoteJumpBackwardEvent>(
@@ -241,7 +149,7 @@ export const onRemoteJumpBackward =
 /**
  * Subscribes to remote jump forward events.
  * @param callback - Called when the user presses the jump forward button
- * @returns Cleanup function to unsubscribe
+ * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
  */
 export const onRemoteJumpForward =
   LazyNativeEmitter.emitterize<RemoteJumpForwardEvent>(
@@ -251,7 +159,7 @@ export const onRemoteJumpForward =
 /**
  * Subscribes to remote next events.
  * @param callback - Called when the user presses the next track button
- * @returns Cleanup function to unsubscribe
+ * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
  */
 export const onRemoteNext = LazyNativeEmitter.emitterize<void>(
   (cb) => (nativeBrowser.onRemoteNext = cb)
@@ -260,7 +168,7 @@ export const onRemoteNext = LazyNativeEmitter.emitterize<void>(
 /**
  * Subscribes to remote pause events.
  * @param callback - Called when the user presses the pause button
- * @returns Cleanup function to unsubscribe
+ * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
  */
 export const onRemotePause = LazyNativeEmitter.emitterize<void>(
   (cb) => (nativeBrowser.onRemotePause = cb)
@@ -269,7 +177,7 @@ export const onRemotePause = LazyNativeEmitter.emitterize<void>(
 /**
  * Subscribes to remote play events.
  * @param callback - Called when the user presses the play button
- * @returns Cleanup function to unsubscribe
+ * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
  */
 export const onRemotePlay = LazyNativeEmitter.emitterize<void>(
   (cb) => (nativeBrowser.onRemotePlay = cb)
@@ -278,7 +186,7 @@ export const onRemotePlay = LazyNativeEmitter.emitterize<void>(
 /**
  * Subscribes to remote play ID events (Android only).
  * @param callback - Called when the user selects a track from an external device
- * @returns Cleanup function to unsubscribe
+ * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
  */
 export const onRemotePlayId = LazyNativeEmitter.emitterize<RemotePlayIdEvent>(
   (cb) => (nativeBrowser.onRemotePlayId = cb)
@@ -287,7 +195,7 @@ export const onRemotePlayId = LazyNativeEmitter.emitterize<RemotePlayIdEvent>(
 /**
  * Subscribes to remote play search events (Android only).
  * @param callback - Called when the user searches for a track (usually voice search)
- * @returns Cleanup function to unsubscribe
+ * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
  */
 export const onRemotePlaySearch =
   LazyNativeEmitter.emitterize<RemotePlaySearchEvent>(
@@ -297,7 +205,7 @@ export const onRemotePlaySearch =
 /**
  * Subscribes to remote previous events.
  * @param callback - Called when the user presses the previous track button
- * @returns Cleanup function to unsubscribe
+ * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
  */
 export const onRemotePrevious = LazyNativeEmitter.emitterize<void>(
   (cb) => (nativeBrowser.onRemotePrevious = cb)
@@ -306,26 +214,16 @@ export const onRemotePrevious = LazyNativeEmitter.emitterize<void>(
 /**
  * Subscribes to remote seek events.
  * @param callback - Called when the user changes the position of the timeline
- * @returns Cleanup function to unsubscribe
+ * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
  */
 export const onRemoteSeek = LazyNativeEmitter.emitterize<RemoteSeekEvent>(
   (cb) => (nativeBrowser.onRemoteSeek = cb)
 )
 
-/**
- * Subscribes to remote set rating events.
- * @param callback - Called when the user changes the rating for the track remotely
- * @returns Cleanup function to unsubscribe
- */
-export const onRemoteSetRating =
-  LazyNativeEmitter.emitterize<RemoteSetRatingEvent>(
-    (cb) => (nativeBrowser.onRemoteSetRating = cb)
-  )
-
 /**
  * Subscribes to remote skip events (Android only).
  * @param callback - Called when the user presses the skip button
- * @returns Cleanup function to unsubscribe
+ * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
  */
 export const onRemoteSkip = LazyNativeEmitter.emitterize<RemoteSkipEvent>(
   (cb) => (nativeBrowser.onRemoteSkip = cb)
@@ -334,7 +232,7 @@ export const onRemoteSkip = LazyNativeEmitter.emitterize<RemoteSkipEvent>(
 /**
  * Subscribes to remote stop events.
  * @param callback - Called when the user presses the stop button
- * @returns Cleanup function to unsubscribe
+ * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
  */
 export const onRemoteStop = LazyNativeEmitter.emitterize<void>(
   (cb) => (nativeBrowser.onRemoteStop = cb)

package/src/features/sleepTimer.test.ts

@@ -0,0 +1,172 @@
+/** @vitest-environment happy-dom */
+
+import { renderHook, act, cleanup } from '@testing-library/react'
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest'
+import type { SleepTimer } from './sleepTimer'
+
+const native = vi.hoisted(() => ({
+  getSleepTimer: vi.fn<() => SleepTimer>(() => null),
+  // The single callback slot `NativeUpdatedValue` claims at module load.
+  onSleepTimerChanged: undefined as ((timer: SleepTimer) => void) | undefined
+}))
+
+vi.mock('../native', () => ({ nativeBrowser: native }))
+
+const { onSleepTimerChanged, useSleepTimer, useSleepTimerActive } =
+  await import('./sleepTimer')
+
+/** Push a value the way native would. */
+const fire = (timer: SleepTimer) =>
+  act(() => native.onSleepTimerChanged?.(timer))
+
+/**
+ * The emitter is a module-level singleton, so `lastValue` outlives each test.
+ * `undefined` is its pre-native state and distinct from `null`, which is a real
+ * value meaning "no timer" — the distinction the re-sync gate turns on.
+ */
+beforeEach(() => {
+  onSleepTimerChanged.lastValue = undefined
+  native.getSleepTimer.mockReturnValue(null)
+})
+afterEach(cleanup)
+
+describe('useSleepTimerActive', () => {
+  it('reads the getter when nothing has fired yet', () => {
+    native.getSleepTimer.mockReturnValue({ time: Date.now() + 60_000 })
+    const { result } = renderHook(() => useSleepTimerActive())
+    expect(result.current).toBe(true)
+  })
+
+  it('tracks timers being set and cleared', () => {
+    const { result } = renderHook(() => useSleepTimerActive())
+    expect(result.current).toBe(false)
+    fire({ time: Date.now() + 60_000 })
+    expect(result.current).toBe(true)
+    fire(null)
+    expect(result.current).toBe(false)
+  })
+
+  it('treats an end-of-track timer as active', () => {
+    const { result } = renderHook(() => useSleepTimerActive())
+    fire({ sleepWhenPlayedToEnd: true })
+    expect(result.current).toBe(true)
+  })
+
+  // The regression from f7a25040. The getter ran during render and saw a live
+  // timer; the clear landed before the effect subscribed. Without the re-sync
+  // the UI shows a running timer that is already gone — permanently, since
+  // nothing reads it again until the next native event.
+  it('re-syncs a clear that landed between the render read and the effect', () => {
+    native.getSleepTimer.mockReturnValue({ time: Date.now() + 60_000 })
+    onSleepTimerChanged.lastValue = null
+    const { result } = renderHook(() => useSleepTimerActive())
+    expect(result.current).toBe(false)
+  })
+
+  // The gate is `!== undefined`, not truthiness: `undefined` means native has
+  // never spoken, so the getter's answer must stand.
+  it('keeps the getter value when native has not fired at all', () => {
+    native.getSleepTimer.mockReturnValue({ time: Date.now() + 60_000 })
+    const { result } = renderHook(() => useSleepTimerActive())
+    expect(result.current).toBe(true)
+  })
+
+  it('stops tracking after unmount', () => {
+    const { result, unmount } = renderHook(() => useSleepTimerActive())
+    unmount()
+    fire({ time: Date.now() + 60_000 })
+    expect(result.current).toBe(false)
+  })
+})
+
+describe('useSleepTimer', () => {
+  it('is undefined when no timer is set', () => {
+    const { result } = renderHook(() => useSleepTimer())
+    expect(result.current).toBeUndefined()
+  })
+
+  it('reports secondsLeft for a time-based timer', () => {
+    vi.useFakeTimers()
+    try {
+      vi.setSystemTime(1_000_000_000_000)
+      native.getSleepTimer.mockReturnValue({ time: Date.now() + 30_000 })
+      const { result } = renderHook(() => useSleepTimer())
+      expect(result.current).toEqual({
+        time: 1_000_000_030_000,
+        secondsLeft: 30
+      })
+    } finally {
+      vi.useRealTimers()
+    }
+  })
+
+  it('passes an end-of-track timer through without secondsLeft', () => {
+    const { result } = renderHook(() => useSleepTimer())
+    fire({ sleepWhenPlayedToEnd: true })
+    expect(result.current).toEqual({ sleepWhenPlayedToEnd: true })
+  })
+
+  it('counts down as time passes', () => {
+    vi.useFakeTimers()
+    try {
+      vi.setSystemTime(1_000_000_000_000)
+      native.getSleepTimer.mockReturnValue({ time: Date.now() + 5_000 })
+      const { result } = renderHook(() => useSleepTimer())
+      expect(result.current).toMatchObject({ secondsLeft: 5 })
+      act(() => {
+        vi.advanceTimersByTime(2_000)
+      })
+      expect(result.current).toMatchObject({ secondsLeft: 3 })
+      act(() => {
+        vi.advanceTimersByTime(3_000)
+      })
+      expect(result.current).toMatchObject({ secondsLeft: 0 })
+    } finally {
+      vi.useRealTimers()
+    }
+  })
+
+  it('stops the countdown once it reaches zero', () => {
+    vi.useFakeTimers()
+    try {
+      vi.setSystemTime(1_000_000_000_000)
+      native.getSleepTimer.mockReturnValue({ time: Date.now() + 2_000 })
+      const { result } = renderHook(() => useSleepTimer())
+      act(() => {
+        vi.advanceTimersByTime(2_000)
+      })
+      expect(result.current).toMatchObject({ secondsLeft: 0 })
+      // Clamped at zero rather than running negative.
+      act(() => {
+        vi.advanceTimersByTime(10_000)
+      })
+      expect(result.current).toMatchObject({ secondsLeft: 0 })
+    } finally {
+      vi.useRealTimers()
+    }
+  })
+
+  it('does not tick while inactive', () => {
+    vi.useFakeTimers()
+    try {
+      vi.setSystemTime(1_000_000_000_000)
+      native.getSleepTimer.mockReturnValue({ time: Date.now() + 60_000 })
+      const { result } = renderHook(() => useSleepTimer({ inactive: true }))
+      expect(result.current).toMatchObject({ secondsLeft: 60 })
+      act(() => {
+        vi.advanceTimersByTime(10_000)
+      })
+      expect(result.current).toMatchObject({ secondsLeft: 60 })
+    } finally {
+      vi.useRealTimers()
+    }
+  })
+
+  // Same race as useSleepTimerActive, and the reason both hooks carry the gate.
+  it('re-syncs a clear that landed between the render read and the effect', () => {
+    native.getSleepTimer.mockReturnValue({ time: Date.now() + 60_000 })
+    onSleepTimerChanged.lastValue = null
+    const { result } = renderHook(() => useSleepTimer())
+    expect(result.current).toBeUndefined()
+  })
+})

package/src/features/sleepTimer.ts

@@ -40,11 +40,30 @@ export function getSleepTimer(): SleepTimer {
 }
 
 /**
- * Sets a sleep timer to stop playback after the specified duration.
- * @param seconds - Number of seconds until playback stops
+ * Options for `setSleepTimer`.
  */
-export function setSleepTimer(seconds: number): void {
-  nativeBrowser.setSleepTimer(seconds)
+export type SleepTimerOptions = {
+  /**
+   * Seconds over which to fade the volume out before the timer completes.
+   * The fade ends exactly at the deadline (clamped to the timer duration if
+   * longer), playback is paused, and the pre-fade volume is restored so the
+   * next play starts at normal loudness. During the fade the timer wins:
+   * skips and seeks play into the remaining ramp; only pausing or
+   * clearing/replacing the timer cancels it.
+   */
+  fadeDuration?: number
+}
+
+/**
+ * Sets a sleep timer to pause playback after the specified duration.
+ * @param seconds - Number of seconds until playback pauses
+ * @param options - Optional fade-out configuration
+ */
+export function setSleepTimer(
+  seconds: number,
+  options?: SleepTimerOptions
+): void {
+  nativeBrowser.setSleepTimer(seconds, options?.fadeDuration)
 }
 
 /**
@@ -67,7 +86,7 @@ export function clearSleepTimer(): boolean {
 /**
  * Subscribes to sleep timer changes.
  * @param callback - Called when the sleep timer state changes
- * @returns Cleanup function to unsubscribe
+ * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
  */
 export const onSleepTimerChanged = NativeUpdatedValue.emitterize<SleepTimer>(
   (cb) => (nativeBrowser.onSleepTimerChanged = cb)
@@ -85,6 +104,11 @@ export function useSleepTimerActive(): boolean {
   const [isActive, setIsActive] = useState(() => getSleepTimer() !== null)
 
   useEffect(() => {
+    // Re-sync before subscribing: a change between the initial read above and this effect would
+    // otherwise be missed for good. `undefined` means nothing has fired yet, whereas `null` is a
+    // real value — the timer being cleared — so it has to re-sync too.
+    const { lastValue } = onSleepTimerChanged
+    if (lastValue !== undefined) setIsActive(lastValue !== null)
     return onSleepTimerChanged.addListener((timer) => {
       setIsActive(timer !== null)
     })
@@ -118,6 +142,9 @@ export function useSleepTimer(params?: {
   const time = state && 'time' in state ? state.time : undefined
 
   useEffect(() => {
+    // Re-sync before subscribing — see useSleepTimerActive.
+    const { lastValue } = onSleepTimerChanged
+    if (lastValue !== undefined) setState(addSecondsLeft(lastValue))
     return onSleepTimerChanged.addListener((event) => {
       setState(addSecondsLeft(event))
     })

package/src/native.ts

@@ -1,5 +1,10 @@
 import { NitroModules } from 'react-native-nitro-modules'
 import type { AudioBrowser as AudioBrowserSpec } from './specs/audio-browser.nitro.ts'
 
+/**
+ * The raw Nitro hybrid object — the bridge itself. Feature modules wrap it;
+ * consumers use those wrappers.
+ * @internal
+ */
 export const nativeBrowser =
   NitroModules.createHybridObject<AudioBrowserSpec>('AudioBrowser')

package/src/native.web.ts

@@ -1,4 +1,7 @@
 import { NativeAudioBrowser } from './web/NativeAudioBrowser'
 
-// Web implementation: AudioBrowser is a unified browser + player
+/**
+ * Web implementation: AudioBrowser is a unified browser + player.
+ * @internal
+ */
 export const nativeBrowser = new NativeAudioBrowser()