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

package/src/features/metadata.ts

@@ -1,18 +1,8 @@
-import type { Rating } from './rating'
 import { nativeBrowser } from '../native'
 import { NativeUpdatedValue } from '../utils/NativeUpdatedValue'
 
 // MARK: - Types
 
-export type RatingType =
-  | 'heart'
-  | 'thumbs-up-down'
-  | 'three-stars'
-  | 'four-stars'
-  | 'five-stars'
-  | 'percentage'
-  | 'none'
-
 export interface TrackMetadataBase {
   /** The track title */
   title?: string
@@ -30,8 +20,6 @@ export interface TrackMetadataBase {
   mediaId?: string
   /** The track genre */
   genre?: string
-  /** The track rating */
-  rating?: Rating
 }
 
 export interface NowPlayingMetadata extends TrackMetadataBase {
@@ -48,6 +36,12 @@ export type NowPlayingUpdate = {
   title?: string
   /** Artist shown in notification */
   artist?: string
+  /**
+   * Album line, on surfaces that render one (CarPlay's third line, some
+   * Bluetooth head units). Never shown on the iOS lock screen or the Android
+   * notification.
+   */
+  album?: string
 }
 
 /**

package/src/features/nowPlaying.ts

@@ -32,6 +32,42 @@ export function getNowPlaying(): NowPlayingMetadata | undefined {
   return nativeBrowser.getNowPlaying() ?? undefined
 }
 
+/**
+ * Temporarily replaces now-playing fields for `durationMs`, then reverts to
+ * the live metadata. The flash outranks the now-playing formatter and the
+ * `updateNowPlaying` override while active (live metadata can't stomp it),
+ * and the revert runs on a native timer — JS timers pause in a backgrounded
+ * host (the lock screen case) — so it fires reliably. A track change clears
+ * the flash early; repeated calls restart the window.
+ *
+ * The feedback channel for refused remote commands: external surfaces have
+ * no toast primitive, so a transient metadata swap is the only way to talk
+ * to the user there.
+ *
+ * @example
+ * ```ts
+ * // A radio product with an hourly skip allowance:
+ * handleRemoteNext(() => {
+ *   if (skipsRemaining() > 0) skipToNext()
+ *   else flashNowPlaying({ artist: 'Skip limit reached' }, 3000)
+ * })
+ * ```
+ */
+export function flashNowPlaying(
+  update: NowPlayingUpdate,
+  durationMs: number
+): void {
+  nativeBrowser.flashNowPlaying(update, durationMs)
+}
+
+/**
+ * Clears an active flash immediately, reverting to the live metadata.
+ * No-op when no flash is active.
+ */
+export function clearNowPlayingFlash(): void {
+  nativeBrowser.clearNowPlayingFlash()
+}
+
 // MARK: - Event Callbacks
 
 /**

package/src/features/output.ts

@@ -1,50 +1,63 @@
-import type { IosOutput, IosOutputType } from '../specs/audio-browser.nitro'
+import type { Output, OutputType } from '../specs/audio-browser.nitro'
 import { nativeBrowser } from '../native'
 import { NativeUpdatedValue } from '../utils/NativeUpdatedValue'
 import { useNativeUpdatedValue } from '../utils/useNativeUpdatedValue'
 
-export type { IosOutput, IosOutputType }
+export type { Output, OutputType }
 
 // MARK: - Actions
 
 /**
- * Opens the system output picker (iOS only).
- * Allows users to select output device (speaker, AirPlay, Bluetooth, etc.).
- * No-op on Android.
+ * Presents the system audio output switcher so the listener can move playback to
+ * another output. Cross-platform:
+ * - **iOS** — the system route picker (Bluetooth, AirPlay / Sonos-via-AirPlay,
+ *   speaker). Always available.
+ * - **Android** — the system Output Switcher (Bluetooth / speaker / Cast list) on
+ *   Android 11+. No-op on older Android — gate on {@link supportsOutputSwitcher}.
+ * - **Web** — no-op.
  */
-export function openIosOutputPicker(): void {
-  nativeBrowser.openIosOutputPicker()
+export function openOutputPicker(): void {
+  nativeBrowser.openOutputPicker()
+}
+
+/**
+ * Whether {@link openOutputPicker} can present a switcher on this device — use it
+ * to decide whether to surface the output control in your UI.
+ * `true` on iOS and Android 11+ (API 30); `false` on older Android and web.
+ */
+export function supportsOutputSwitcher(): boolean {
+  return nativeBrowser.supportsOutputSwitcher()
 }
 
 // MARK: - Getters
 
 /**
- * Gets the current audio output info.
- * Always returns a value on iOS, undefined on Android.
+ * The current audio output, or `undefined` when unknown. iOS reports one while a
+ * session is active; Android reports the active output route via AudioManager
+ * (the `type` is coarse — e.g. wired headphones may report as `speaker`). Guard
+ * for `undefined`.
  */
-export function getIosOutput(): IosOutput | undefined {
-  return nativeBrowser.getIosOutput()
+export function getOutput(): Output | undefined {
+  return nativeBrowser.getOutput()
 }
 
 // MARK: - Event Callbacks
 
 /**
- * Subscribes to output state changes (iOS only).
- * Never fires on Android.
- * @param callback - Called with output info when output changes
- * @returns Cleanup function to unsubscribe
+ * Subscribes to current-output changes (headphones unplugged, Bluetooth speaker
+ * connected, AirPlay/route selected). Fires on iOS and Android 11+; never below.
+ * @returns Cleanup function to unsubscribe.
  */
-export const onIosOutputChanged = NativeUpdatedValue.emitterize<IosOutput>(
-  (cb) => (nativeBrowser.onIosOutputChanged = cb)
+export const onOutputChanged = NativeUpdatedValue.emitterize<Output>(
+  (cb) => (nativeBrowser.onOutputChanged = cb)
 )
 
 // MARK: - Hooks
 
 /**
- * Hook that returns the current audio output info.
- * Updates when the output changes (e.g., AirPods connected/disconnected).
- * Always returns a value on iOS, undefined on Android.
+ * Reactive current audio output; re-renders when it changes (e.g. AirPods
+ * connect, a Bluetooth speaker is selected). `undefined` when unknown.
  */
-export function useIosOutput(): IosOutput | undefined {
-  return useNativeUpdatedValue(getIosOutput, onIosOutputChanged)
+export function useOutput(): Output | undefined {
+  return useNativeUpdatedValue(getOutput, onOutputChanged)
 }

package/src/features/playback/controls.ts

@@ -57,6 +57,14 @@ export function seekTo(position: number): void {
   nativeBrowser.seekTo(position)
 }
 
+/**
+ * Jump to the live edge of the current track. No-op for non-live tracks; for
+ * live, seeks to the window end (HLS) or reconnects (non-seekable streams).
+ */
+export function seekToLiveEdge(): void {
+  nativeBrowser.seekToLiveEdge()
+}
+
 /**
  * Seeks by a relative time offset in the current track.
  * @param offset - The time offset to seek by in seconds.

package/src/features/playback/index.ts

@@ -3,5 +3,6 @@ export * from './state'
 export * from './playing'
 export * from './playWhenReady'
 export * from './progress'
+export * from './trackPlaybackTime'
 export * from './rate'
 export * from './volume'

package/src/features/playback/progress.ts

@@ -1,4 +1,5 @@
 import { useEffect, useState } from 'react'
+import { AppState } from 'react-native'
 import { nativeBrowser } from '../../native'
 import { NativeUpdatedValue } from '../../utils/NativeUpdatedValue'
 import { useNativeUpdatedValue } from '../../utils/useNativeUpdatedValue'
@@ -69,6 +70,9 @@ export function useProgress(): Progress {
  *
  * Use this when you need custom polling behavior instead of event-based updates.
  *
+ * Skips updates while the app is backgrounded and refreshes once it becomes
+ * active again.
+ *
  * @param updateInterval - Update interval in milliseconds (default: 1000)
  * @returns The current playback progress
  */
@@ -80,12 +84,12 @@ export function usePolledProgress(updateInterval = 1000): Progress {
   })
 
   useEffect(() => {
-    let mounted = true
+    let timer: ReturnType<typeof setTimeout> | undefined
+    let unsubscribeState: (() => void) | undefined
 
     const update = () => {
       try {
         const { position, duration, buffered } = getProgress()
-        if (!mounted) return
 
         setState((currentState) =>
           position === currentState.position &&
@@ -99,22 +103,37 @@ export function usePolledProgress(updateInterval = 1000): Progress {
       }
     }
 
-    // Update immediately on playback state changes
-    const unsubscribeState = onPlaybackChanged.addListener(update)
-
     const poll = () => {
       update()
-      if (!mounted) return
-      setTimeout(() => {
-        if (mounted) poll()
-      }, updateInterval)
+      timer = setTimeout(poll, updateInterval)
+    }
+
+    // We only poll and listen for playback changes while the app is active. On
+    // return to the foreground we update once and restart the loop so the
+    // interval timing stays correct.
+    const start = () => {
+      if (timer !== undefined) return
+      unsubscribeState = onPlaybackChanged.addListener(update)
+      poll()
     }
 
-    poll()
+    const stop = () => {
+      clearTimeout(timer)
+      timer = undefined
+      unsubscribeState?.()
+      unsubscribeState = undefined
+    }
+
+    const appStateSub = AppState.addEventListener('change', (next) => {
+      if (next === 'active') start()
+      else stop()
+    })
+
+    if (AppState.currentState === 'active') start()
 
     return () => {
-      mounted = false
-      unsubscribeState()
+      stop()
+      appStateSub.remove()
     }
   }, [updateInterval])
 

package/src/features/playback/trackPlaybackTime.test.ts

@@ -0,0 +1,66 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+
+const nativeMock = {
+  onPlaybackInterval: undefined as undefined | (() => void),
+  setPlaybackIntervalEnabled: vi.fn()
+}
+vi.mock('../../native', () => ({
+  get nativeBrowser() {
+    return nativeMock
+  }
+}))
+vi.mock('../queue/activeTrack', () => ({
+  onActiveTrackChanged: { addListener: vi.fn(() => () => {}) }
+}))
+
+import { trackPlaybackTime, __emitTickForTests } from './trackPlaybackTime'
+
+beforeEach(() => {
+  nativeMock.setPlaybackIntervalEnabled.mockClear()
+})
+
+describe('trackPlaybackTime', () => {
+  it('enables native tick on first subscriber, disables on last', () => {
+    const a = trackPlaybackTime(() => {}, 5)
+    expect(nativeMock.setPlaybackIntervalEnabled).toHaveBeenLastCalledWith(true)
+    const b = trackPlaybackTime(() => {}, 5)
+    a()
+    expect(nativeMock.setPlaybackIntervalEnabled).toHaveBeenLastCalledWith(true) // b still active
+    b()
+    expect(nativeMock.setPlaybackIntervalEnabled).toHaveBeenLastCalledWith(
+      false
+    )
+  })
+
+  it('fires every `period` seconds with cumulative total', () => {
+    const calls: { total: number; sinceLast: number }[] = []
+    const cancel = trackPlaybackTime(
+      (e) => calls.push({ total: e.total, sinceLast: e.sinceLast }),
+      3
+    )
+    __emitTickForTests(2)
+    expect(calls).toEqual([])
+    __emitTickForTests(1) // total now 3 → fires
+    expect(calls).toEqual([{ total: 3, sinceLast: 3 }])
+    __emitTickForTests(3) // total now 6 → fires again
+    expect(calls).toEqual([
+      { total: 3, sinceLast: 3 },
+      { total: 6, sinceLast: 3 }
+    ])
+    cancel()
+    __emitTickForTests(3)
+    expect(calls).toHaveLength(2) // cancelled
+  })
+
+  it('runs multiple subscribers at independent periods', () => {
+    const fast: number[] = []
+    const slow: number[] = []
+    const cancelFast = trackPlaybackTime((e) => fast.push(e.total), 1)
+    const cancelSlow = trackPlaybackTime((e) => slow.push(e.total), 2)
+    __emitTickForTests(2)
+    expect(fast).toEqual([1, 2])
+    expect(slow).toEqual([2])
+    cancelFast()
+    cancelSlow()
+  })
+})

package/src/features/playback/trackPlaybackTime.ts

@@ -0,0 +1,106 @@
+import type { Track } from '../../types/browser-nodes'
+import { nativeBrowser } from '../../native'
+import { onActiveTrackChanged } from '../queue/activeTrack'
+
+// MARK: - Types
+
+export interface PlaybackElapsed {
+  /** Cumulative seconds spent `playing` since this subscription started. */
+  total: number
+  /** Seconds played since the previous callback (≈ `period`). */
+  sinceLast: number
+  /** The currently playing track (id / src / url / title …), if any. */
+  track?: Track
+}
+
+interface Handle {
+  period: number
+  totalSeconds: number
+  lastFireSeconds: number
+  callback: (elapsed: PlaybackElapsed) => void
+}
+
+// MARK: - State
+
+const handles = new Set<Handle>()
+let installed = false
+let currentTrack: Track | undefined
+
+// The native tick fires once per second while playback is `playing` (and stops
+// while paused/buffering/stopped), so advancing each handle by one second per
+// tick yields cumulative *playback* time that freezes on interruption.
+function onTick() {
+  for (const handle of handles) {
+    handle.totalSeconds += 1
+    const sinceLast = handle.totalSeconds - handle.lastFireSeconds
+    if (sinceLast >= handle.period) {
+      handle.lastFireSeconds = handle.totalSeconds
+      handle.callback({
+        total: handle.totalSeconds,
+        sinceLast,
+        track: currentTrack
+      })
+    }
+  }
+}
+
+function install() {
+  if (installed) return
+  installed = true
+  nativeBrowser.onPlaybackInterval = onTick
+  onActiveTrackChanged.addListener((event) => {
+    currentTrack = event.track
+  })
+}
+
+// MARK: - Public API
+
+/**
+ * Calls `callback` every `period` seconds of cumulative playback — time spent in
+ * the `playing` state. The clock advances only while playing and freezes on
+ * pause/buffering/stop, resuming where it left off; it is never reset (cancel and
+ * re-subscribe for a fresh `total`). Coarse, best-effort cadence (~1s resolution),
+ * not a precise timer.
+ *
+ * Typical use is a periodic "still listening" signal: fire an analytics ping, a
+ * listen-check, or a heartbeat every N seconds of *actual* listening, so paused
+ * time doesn't inflate the count.
+ *
+ * Note this counts cumulative play time across the whole session, NOT per track:
+ * `total` keeps climbing through track changes, and `track` only tells you what
+ * was playing at the moment each callback fired. To measure playtime per track,
+ * subscribe to {@link onActiveTrackChanged} and cancel + re-subscribe here on each
+ * change, so every track gets a fresh `total` starting at zero.
+ *
+ * @param callback Invoked once per elapsed `period`, with cumulative play time
+ *                 and the currently playing track.
+ * @param period  Seconds of playback between calls. Must be >= 1.
+ * @returns A function that cancels this subscription (idempotent — safe to call
+ *          more than once).
+ */
+export function trackPlaybackTime(
+  callback: (elapsed: PlaybackElapsed) => void,
+  period: number
+): () => void {
+  if (!(period >= 1)) {
+    throw new Error('trackPlaybackTime: period must be >= 1')
+  }
+  install()
+  const handle: Handle = {
+    period,
+    totalSeconds: 0,
+    lastFireSeconds: 0,
+    callback
+  }
+  handles.add(handle)
+  if (handles.size === 1) nativeBrowser.setPlaybackIntervalEnabled(true)
+  return () => {
+    if (!handles.delete(handle)) return
+    if (handles.size === 0) nativeBrowser.setPlaybackIntervalEnabled(false)
+  }
+}
+
+/** @internal test hook — drives the fan-out without a native tick. */
+export function __emitTickForTests(ticks = 1) {
+  for (let i = 0; i < ticks; i++) onTick()
+}

package/src/features/playback/volume.ts

@@ -31,7 +31,7 @@ export function setVolume(level: number): void {
 /**
  * Sets the system volume.
  * @param level - The volume as a number between 0 and 1.
- * @note On iOS this is a no-op as Apple doesn't provide a public API to set system volume.
+ * @remarks On iOS this is a no-op as Apple doesn't provide a public API to set system volume.
  */
 export function setSystemVolume(level: number): void {
   nativeBrowser.setSystemVolume(level)

package/src/features/player/options.test.ts

@@ -0,0 +1,38 @@
+import { describe, expect, it, vi, beforeEach, afterEach } from 'vitest'
+import { nativeBrowser } from '../../native'
+import { updateOptions } from './options'
+
+vi.mock('../../native', () => ({
+  nativeBrowser: { updateOptions: vi.fn() }
+}))
+
+describe('updateOptions', () => {
+  beforeEach(() => vi.clearAllMocks())
+  afterEach(() => vi.restoreAllMocks())
+
+  it('forwards a nested ios bag to the native layer unchanged', () => {
+    updateOptions({ ios: { carPlayNowPlayingButtons: ['favorite'] } })
+    expect(nativeBrowser.updateOptions).toHaveBeenCalledWith({
+      ios: { carPlayNowPlayingButtons: ['favorite'] }
+    })
+  })
+
+  it('warns on more than 5 CarPlay now-playing buttons', () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {})
+    updateOptions({
+      ios: {
+        carPlayNowPlayingButtons: [
+          'shuffle',
+          'repeat',
+          'favorite',
+          'playback-rate',
+          'shuffle',
+          'repeat'
+        ]
+      }
+    })
+    expect(warn.mock.calls.some(([m]) => String(m).includes('at most 5'))).toBe(
+      true
+    )
+  })
+})