react-native-audio-browser 0.1.0 → 0.2.0-next.1

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

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).
  */
@@ -312,16 +299,6 @@ 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

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)
 }
 
 /**

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()

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

@@ -12,6 +12,12 @@ import type {
   PlaybackError,
   PlaybackErrorEvent
 } from '../features/errors'
+import type {
+  NativeGate,
+  NativeGateRequest,
+  GateDecision,
+  GateEvent
+} from '../features/gate'
 import type {
   ChapterMetadata,
   NowPlayingMetadata,
@@ -27,10 +33,9 @@ import type {
 } from '../features/playback/progress'
 import type { Playback } from '../features/playback/state'
 import type {
+  NativeSetupPlayerOptions,
   NativeUpdateOptions,
-  Options,
-  PartialSetupPlayerOptions,
-  UpdateOptions
+  Options
 } from '../features/player'
 import type { PlaybackActiveTrackChangedEvent } from '../features/queue/activeTrack'
 import type { PlaybackQueueEndedEvent } from '../features/queue/queue'
@@ -44,7 +49,6 @@ import type {
   RemotePlayIdEvent,
   RemotePlaySearchEvent,
   RemoteSeekEvent,
-  RemoteSetRatingEvent,
   RemoteSkipEvent
 } from '../features/remoteControls'
 import type { SleepTimer, SleepTimerChangedEvent } from '../features/sleepTimer'
@@ -62,31 +66,46 @@ export type EqualizerSettings = {
   upperBandLevelLimit: number
 }
 
-export type IosOutputType =
-  | 'built-in-speaker'
-  | 'built-in-receiver'
-  | 'airplay'
-  | 'bluetooth-a2dp'
-  | 'bluetooth-hfp'
-  | 'bluetooth-le'
-  | 'headphones'
-  | 'car-audio'
+/**
+ * Cross-platform audio output kind. Each platform maps its native ports into
+ * this shared set: iOS's granular Bluetooth ports (`bluetoothA2DP`/`HFP`/`LE`)
+ * all collapse to `'bluetooth'`. Note Android's *reading* (`getOutput`) reports
+ * the active local route only — `'airplay'`/`'cast'` come from iOS / are
+ * reserved for remote destinations and don't appear from Android reads.
+ */
+export type OutputType =
+  | 'speaker' // built-in loudspeaker
+  | 'receiver' // built-in earpiece (iOS)
+  | 'headphones' // wired headphones / headset
+  | 'bluetooth' // any Bluetooth audio
+  | 'airplay' // AirPlay (iOS)
+  | 'car' // car audio (CarPlay / Android Auto / car Bluetooth)
   | 'hdmi'
-  | 'usb-audio'
+  | 'usb'
+  | 'cast' // remote speaker / TV (reserved)
   | 'other'
 
 /**
- * Audio output information (iOS only).
+ * The current audio output. Read via `getOutput()` / `useOutput()` on every
+ * platform: iOS always reports one while a session is active; Android reports the
+ * actively-routed device on all versions (the `type` is accurate on API 33+ and
+ * coarse below that). Only the output *switcher* (`openOutputPicker`) is gated to
+ * Android 11+ — check `supportsOutputSwitcher()`.
  */
-export type IosOutput = {
-  /** The output port type */
-  type: IosOutputType
-  /** Human-readable device name (e.g., "AirPods Pro", "iPhone Speaker") */
+export type Output = {
+  /** The output kind */
+  type: OutputType
+  /** Human-readable device name (e.g., "AirPods Pro", "Kitchen speaker") */
   name: string
   /** Whether this is an external output (false for built-in speaker/receiver) */
   external: boolean
 }
 
+/**
+ * The Nitro hybrid-object spec — the bridge surface itself. Not consumer API;
+ * feature modules wrap every method.
+ * @internal
+ */
 export interface AudioBrowser extends HybridObject<{
   ios: 'swift'
   android: 'kotlin'
@@ -108,13 +127,41 @@ export interface AudioBrowser extends HybridObject<{
   ) => void
   getFormattedNavigationError(): FormattedNavigationError | undefined
   notifyContentChanged(path: string): void
+  invalidateAllContent(): void
   setFavorites(favorites: string[]): void
   configuration: NativeBrowserConfiguration
 
+  // MARK: gate
+  /**
+   * Records the gate's default chrome (undefined for resolver-only) and whether
+   * a per-request resolver is active. While a gate is set, the four car
+   * enforcement sites consult `resolveGate` per request (skipping the JS hop
+   * when `hasResolver` is false — every request is gated with the default).
+   */
+  setGate(gate: NativeGate | undefined, hasResolver: boolean): void
+  /** Clears the gate, restoring tab content and keeping selection. */
+  clearGate(): void
+  /** Per-request decision, set by JS; native awaits it at a serve site. */
+  resolveGate: (request: NativeGateRequest) => Promise<GateDecision>
+  /** Fired when a request is gated (the gate was served). */
+  onGate: (event: GateEvent) => void
+
+  // MARK: car connection
+  /**
+   * Whether a car is currently connected: a CarPlay scene on iOS, an
+   * Android Auto / Android Automotive connection on Android (via the
+   * androidx.car.app CarConnection provider).
+   */
+  isCarConnected(): boolean
+  /**
+   * Called when the car connects or disconnects.
+   */
+  onCarConnectedChanged: (connected: boolean) => void
+
   // MARK: player init and config
-  setupPlayer(options: PartialSetupPlayerOptions): Promise<void>
+  setupPlayer(options: NativeSetupPlayerOptions): Promise<void>
   updateOptions(options: NativeUpdateOptions): void
-  getOptions(): UpdateOptions
+  getOptions(): Options
 
   // // MARK: player events
   onChapterMetadata: (chapters: ChapterMetadata[]) => void
@@ -127,17 +174,21 @@ export interface AudioBrowser extends HybridObject<{
   ) => void
   onPlaybackPlayingState: (data: PlayingState) => void
   onPlaybackProgressUpdated: (data: PlaybackProgressUpdatedEvent) => void
+  /**
+   * Fired on a fixed internal cadence while playback is `playing`, once enabled
+   * via `setPlaybackIntervalEnabled`. Carries no payload — it is a tick, not a
+   * progress/position update. Independent of `onPlaybackProgressUpdated` and the
+   * `progressUpdateEventInterval` option.
+   */
+  onPlaybackInterval: () => void
   onPlaybackQueueEnded: (data: PlaybackQueueEndedEvent) => void
   onPlaybackQueueChanged: (queue: Track[]) => void
   onPlaybackRepeatModeChanged: (data: RepeatModeChangedEvent) => void
   onPlaybackShuffleModeChanged: (enabled: boolean) => void
   onSleepTimerChanged: (data: SleepTimerChangedEvent) => void
   onPlaybackChanged: (data: Playback) => void
-  onRemoteBookmark: () => void
-  onRemoteDislike: () => void
   onRemoteJumpBackward: (event: RemoteJumpBackwardEvent) => void
   onRemoteJumpForward: (event: RemoteJumpForwardEvent) => void
-  onRemoteLike: () => void
   onRemoteNext: () => void
   onRemotePause: () => void
   onRemotePlay: () => void
@@ -145,7 +196,6 @@ export interface AudioBrowser extends HybridObject<{
   onRemotePlaySearch: (event: RemotePlaySearchEvent) => void
   onRemotePrevious: () => void
   onRemoteSeek: (event: RemoteSeekEvent) => void
-  onRemoteSetRating: (event: RemoteSetRatingEvent) => void
   onRemoteSkip: (event: RemoteSkipEvent) => void
   onRemoteStop: () => void
   onOptionsChanged: (event: Options) => void
@@ -153,13 +203,10 @@ export interface AudioBrowser extends HybridObject<{
   onNowPlayingChanged: (metadata: NowPlayingMetadata) => void
 
   // MARK: remote handlers
-  handleRemoteBookmark: (() => void) | undefined
-  handleRemoteDislike: (() => void) | undefined
   handleRemoteJumpBackward:
     | ((event: RemoteJumpBackwardEvent) => void)
     | undefined
   handleRemoteJumpForward: ((event: RemoteJumpForwardEvent) => void) | undefined
-  handleRemoteLike: (() => void) | undefined
   handleRemoteNext: (() => void) | undefined
   handleRemotePause: (() => void) | undefined
   handleRemotePlay: (() => void) | undefined
@@ -181,11 +228,22 @@ export interface AudioBrowser extends HybridObject<{
   getPlayWhenReady(): boolean
   seekTo(position: number): void
   seekBy(offset: number): void
+  /**
+   * Jump to the live edge of the current track. No-op for non-live tracks.
+   * Live with a seekable window (HLS): seeks to the window end. Live without a
+   * window (non-seekable, e.g. ICY): reconnects to rejoin live.
+   */
+  seekToLiveEdge(): void
   setVolume(level: number): void
   getVolume(): number
   setRate(rate: number): void
   getRate(): number
   getProgress(): Progress
+  /**
+   * Enables or disables the internal playback tick that drives
+   * `onPlaybackInterval`. When disabled (default), no tick is emitted.
+   */
+  setPlaybackIntervalEnabled(enabled: boolean): void
   getPlayback(): Playback
   getPlayingState(): PlayingState
   getRepeatMode(): RepeatMode
@@ -195,7 +253,12 @@ export interface AudioBrowser extends HybridObject<{
   getPlaybackError(): PlaybackError | undefined
   retry(): void
   getSleepTimer(): SleepTimer
-  setSleepTimer(seconds: number): void
+  /**
+   * Stops playback after `seconds`. When `fadeDuration` is given, the volume
+   * ramps down over the final `fadeDuration` seconds so silence lands exactly
+   * at the deadline; the pre-fade volume is restored after pausing.
+   */
+  setSleepTimer(seconds: number, fadeDuration?: number): void
   setSleepTimerToEndOfTrack(): void
   clearSleepTimer(): boolean
 
@@ -216,7 +279,7 @@ export interface AudioBrowser extends HybridObject<{
    * Toggles the favorited state of the currently playing track.
    */
   toggleActiveTrackFavorited(): void
-  setQueue(tracks: Track[], startIndex?: number, startPositionMs?: number): void
+  setQueue(tracks: Track[], startIndex?: number, startPosition?: number): void
   getQueue(): Track[]
   getTrack(index: number): Track | undefined
   getActiveTrackIndex(): number | undefined
@@ -228,6 +291,18 @@ export interface AudioBrowser extends HybridObject<{
    * Pass null to clear overrides and revert to track metadata.
    */
   updateNowPlaying(update: NowPlayingUpdate | undefined): void
+  /**
+   * Temporarily replaces now-playing fields for `durationMs`, then reverts.
+   * Outranks the formatter and the `updateNowPlaying` override while active,
+   * and is reverted by a native timer (JS timers pause in a backgrounded
+   * host). Cleared early on track change. Repeated calls restart the window.
+   */
+  flashNowPlaying(update: NowPlayingUpdate, durationMs: number): void
+  /**
+   * Clears an active flash immediately, reverting to the live metadata.
+   * No-op when no flash is active.
+   */
+  clearNowPlayingFlash(): void
   /**
    * Gets the current now playing metadata (override if set, else track metadata).
    */
@@ -252,23 +327,38 @@ export interface AudioBrowser extends HybridObject<{
    */
   onSystemVolumeChanged: (volume: number) => void
 
-  // MARK: external audio output (iOS only)
+  // MARK: external audio output
+  /**
+   * The current audio output, or undefined when unknown. iOS reports one while a
+   * session is active; Android reports the actively-routed media device via
+   * AudioManager — accurate on API 33+ (reflects manual reroutes); on older
+   * Android the `type` is coarse and can't detect a reroute while a device stays
+   * connected.
+   */
+  getOutput(): Output | undefined
   /**
-   * Gets the current audio output info.
-   * Always returns a value on iOS, undefined on Android.
+   * Called when the current audio output changes (headphones unplugged, a
+   * Bluetooth speaker connected, AirPlay/route selected). Fires on iOS and
+   * Android; never on web.
    */
-  getIosOutput(): IosOutput | undefined
+  onOutputChanged: (output: Output) => void
   /**
-   * Called when audio output changes (iOS only).
-   * Never fires on Android.
+   * Presents the system audio output switcher so the listener can move playback
+   * to another output — Bluetooth, AirPlay/Sonos-via-AirPlay, speaker (iOS), or
+   * the Bluetooth / speaker / Cast device list (Android). Cross-platform.
+   *
+   * iOS: the system route picker (always available).
+   * Android: the system Output Switcher (Android 11+); no-op below that — gate
+   * on `supportsOutputSwitcher()`.
+   * Web: no-op.
    */
-  onIosOutputChanged: (output: IosOutput) => void
+  openOutputPicker(): void
   /**
-   * Opens the system output picker (iOS only).
-   * Allows users to select output device (speaker, AirPlay, Bluetooth, etc.).
-   * No-op on Android.
+   * Whether `openOutputPicker()` can present a system output switcher on this
+   * device — surface the output control in the UI only when this is true.
+   * iOS: true. Android: true on Android 11+ (API 30). Web: false.
    */
-  openIosOutputPicker(): void
+  supportsOutputSwitcher(): boolean
 
   // MARK: equalizer (Android only)
   getEqualizerSettings(): EqualizerSettings | undefined

package/src/types/browser-native.ts

@@ -9,7 +9,7 @@
 import type {
   ArtworkRequestConfig,
   BrowserSourceCallback,
-  CarPlayNowPlayingButton,
+  ResolveAlbumUrlCallback,
   FormatNavigationErrorCallback,
   HandleTrackLoadCallback,
   MediaRequestConfig,
@@ -18,6 +18,12 @@ import type {
 } from './browser'
 import type { ResolvedTrack } from './browser-nodes'
 
+// Native resolvers are Promise-only. The public `request`/`browse` resolver may
+// return its config sync OR async; `toNativeConfig` wraps it in Promise.resolve so
+// the bridge never sees a `T | Promise<T>` variant (which would misread the async
+// case). Resolvers run once per content generation, so the wrap is free.
+type NativeRequestConfigResolver = () => Promise<TransformableRequestConfig>
+
 /**
  * Flattened route entry for native bridge.
  */
@@ -42,18 +48,25 @@ export interface NativeRouteEntry {
 export interface NativeBrowserConfiguration {
   path?: string
 
-  // Request defaults
+  // Request defaults (applied to every request: browse, search, media, artwork).
+  // The union `TransformableRequestConfig | RequestConfigResolver` from the public
+  // API is lowered here into two sibling fields (mirrors browseCallback/browseConfig).
   request?: TransformableRequestConfig
+  requestResolver?: NativeRequestConfigResolver
 
-  // Global media/artwork config (applied when route doesn't override)
+  // Per-kind request config, layered request → <kind> → route.
+  browse?: TransformableRequestConfig
+  browseResolver?: NativeRequestConfigResolver
   media?: MediaRequestConfig
   artwork?: ArtworkRequestConfig
+  nowPlayingArtwork?: ArtworkRequestConfig
 
   // Routes as array - includes:
   // - Explicit routes from config.routes
-  // - Root browse as __default__ entry
+  // - The '*' route (if any) as the __default__ entry (custom default override)
   // - Tabs as __tabs__ entry (returns ResolvedTrack with children for navigation tabs)
   // - Search as __search__ entry (has searchCallback or searchConfig)
+  // A browse path matching none of these is fetched via request + browse + path.
   routes?: NativeRouteEntry[]
 
   // Behavior
@@ -62,7 +75,7 @@ export interface NativeBrowserConfiguration {
   androidControllerOfflineError?: boolean
 
   // CarPlay options
-  carPlayUpNextButton?: boolean
-  carPlayNowPlayingButtons?: CarPlayNowPlayingButton[]
+  carPlayLoadingTitle?: string
+  resolveAlbumUrl?: ResolveAlbumUrlCallback
   formatNavigationError?: FormatNavigationErrorCallback
 }