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

package/src/features/sleepTimer.ts

@@ -0,0 +1,186 @@
+import { useEffect, useState } from 'react'
+import { nativeBrowser } from '../native'
+import { NativeUpdatedValue } from '../utils/NativeUpdatedValue'
+
+// MARK: - Types
+
+/**
+ * Time-based sleep timer that stops playback after a specific time.
+ */
+export type SleepTimerTime = {
+  /** Time when playback should stop (milliseconds since epoch) */
+  time: number
+}
+
+/**
+ * End-of-track sleep timer that stops playback when current track finishes.
+ */
+export type SleepTimerEndOfTrack = {
+  /** Whether to sleep when current track finishes playing */
+  sleepWhenPlayedToEnd: boolean
+}
+
+/**
+ * Sleep timer configuration:
+ * - `SleepTimerTime`: Stop playback after a specific time
+ * - `SleepTimerEndOfTrack`: Stop playback after current track finishes
+ * - `null`: No sleep timer active
+ */
+export type SleepTimer = SleepTimerTime | SleepTimerEndOfTrack | null
+
+export type SleepTimerChangedEvent = SleepTimer
+
+// MARK: - Getters and Setters
+
+/**
+ * Gets the current sleep timer state.
+ */
+export function getSleepTimer(): SleepTimer {
+  return nativeBrowser.getSleepTimer()
+}
+
+/**
+ * Sets a sleep timer to stop playback after the specified duration.
+ * @param seconds - Number of seconds until playback stops
+ */
+export function setSleepTimer(seconds: number): void {
+  nativeBrowser.setSleepTimer(seconds)
+}
+
+/**
+ * Sets a sleep timer to stop playback when the current track finishes playing.
+ */
+export function setSleepTimerToEndOfTrack(): void {
+  nativeBrowser.setSleepTimerToEndOfTrack()
+}
+
+/**
+ * Clears the active sleep timer.
+ * @returns true if a timer was cleared, false if no timer was active
+ */
+export function clearSleepTimer(): boolean {
+  return nativeBrowser.clearSleepTimer()
+}
+
+// MARK: - Event Callbacks
+
+/**
+ * Subscribes to sleep timer changes.
+ * @param callback - Called when the sleep timer state changes
+ * @returns Cleanup function to unsubscribe
+ */
+export const onSleepTimerChanged = NativeUpdatedValue.emitterize<SleepTimer>(
+  (cb) => (nativeBrowser.onSleepTimerChanged = cb)
+)
+
+// MARK: - Hooks
+
+/**
+ * Hook that returns whether a sleep timer is currently active.
+ * This is a lightweight alternative to useSleepTimer when you only need to know if a timer is set.
+ *
+ * @returns true if any sleep timer is active, false otherwise
+ */
+export function useSleepTimerActive(): boolean {
+  const [isActive, setIsActive] = useState(() => getSleepTimer() !== null)
+
+  useEffect(() => {
+    return onSleepTimerChanged.addListener((timer) => {
+      setIsActive(timer !== null)
+    })
+  }, [])
+
+  return isActive
+}
+
+/**
+ * Hook that returns the current sleep timer state and time left.
+ *
+ * Note that time left is not updated when the app is in the background.
+ *
+ * @param params - Optional configuration object
+ * @param params.updateInterval - ms interval at which the time left is updated. Defaults to 1000 (1 second).
+ * @param params.inactive - Whether the app is in the background. If true, time left updates are paused.
+ * @returns The current sleep timer state with secondsLeft calculated
+ */
+export function useSleepTimer(params?: {
+  updateInterval?: number
+  inactive?: boolean
+}): SleepTimerState | undefined {
+  const updateInterval = params?.updateInterval ?? 1000
+  const inactive = params?.inactive ?? false
+
+  const [state, setState] = useState<SleepTimerState | undefined>(() => {
+    const timerState = getSleepTimer()
+    return addSecondsLeft(timerState)
+  })
+
+  const time = state && 'time' in state ? state.time : undefined
+
+  useEffect(() => {
+    return onSleepTimerChanged.addListener((event) => {
+      setState(addSecondsLeft(event))
+    })
+  }, [])
+
+  useEffect(() => {
+    if (inactive || time === undefined) return
+
+    const update = () => {
+      setState((sleepTimer) => {
+        const result = addSecondsLeft(
+          sleepTimer
+            ? 'time' in sleepTimer
+              ? { time: sleepTimer.time }
+              : sleepTimer
+            : null
+        )
+        if (result && 'secondsLeft' in result && result.secondsLeft === 0) {
+          clear()
+        }
+        return result
+      })
+    }
+
+    // In order to make time update reaching 0 sync with firing of completion,
+    // first wait for the next interval to start before starting update loop
+    const initialTimeoutId = setTimeout(
+      () => {
+        update()
+        intervalId = setInterval(update, updateInterval)
+      },
+      updateInterval - (time % updateInterval)
+    )
+    let intervalId: ReturnType<typeof setInterval> | undefined
+    const clear = () => {
+      clearTimeout(initialTimeoutId)
+      if (intervalId) clearInterval(intervalId)
+    }
+    update()
+    return clear
+  }, [inactive, time, updateInterval])
+
+  return state
+}
+
+// MARK: - Private Helpers
+
+/**
+ * State returned by `useSleepTimer` hook.
+ * - Time-based timer includes `secondsLeft` countdown
+ * - End-of-track timer includes `sleepWhenPlayedToEnd` flag
+ */
+export type SleepTimerState =
+  | { time: number; secondsLeft: number }
+  | { sleepWhenPlayedToEnd: boolean }
+
+function addSecondsLeft(state: SleepTimer): SleepTimerState | undefined {
+  if (!state) return undefined
+  if ('time' in state) {
+    return {
+      ...state,
+      secondsLeft: Math.max(0, Math.round((state.time - Date.now()) / 1000))
+    }
+  }
+  return state
+}

package/src/index.ts

@@ -0,0 +1,5 @@
+import * as AudioBrowser from './AudioBrowser'
+
+export * from './AudioBrowser'
+
+export default AudioBrowser

package/src/native.ts

@@ -0,0 +1,5 @@
+import { NitroModules } from 'react-native-nitro-modules'
+import type { AudioBrowser as AudioBrowserSpec } from './specs/audio-browser.nitro.ts'
+
+export const nativeBrowser =
+  NitroModules.createHybridObject<AudioBrowserSpec>('AudioBrowser')

package/src/native.web.ts

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

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

@@ -0,0 +1,326 @@
+import { type HybridObject } from 'react-native-nitro-modules'
+
+import type {
+  BatteryOptimizationStatus,
+  BatteryOptimizationStatusChangedEvent,
+  BatteryWarningPendingChangedEvent,
+  FavoriteChangedEvent
+} from '../features'
+import type {
+  NavigationError,
+  NavigationErrorEvent,
+  FormattedNavigationError,
+  PlaybackError,
+  PlaybackErrorEvent
+} from '../features/errors'
+import type {
+  ChapterMetadata,
+  NowPlayingMetadata,
+  NowPlayingUpdate,
+  TimedMetadata,
+  TrackMetadata
+} from '../features/metadata'
+import type { PlayingState } from '../features/playback/playing'
+import type { PlaybackPlayWhenReadyChangedEvent } from '../features/playback/playWhenReady'
+import type {
+  PlaybackProgressUpdatedEvent,
+  Progress
+} from '../features/playback/progress'
+import type { Playback } from '../features/playback/state'
+import type {
+  NativeUpdateOptions,
+  Options,
+  PartialSetupPlayerOptions,
+  UpdateOptions
+} from '../features/player'
+import type { PlaybackActiveTrackChangedEvent } from '../features/queue/activeTrack'
+import type { PlaybackQueueEndedEvent } from '../features/queue/queue'
+import type {
+  RepeatMode,
+  RepeatModeChangedEvent
+} from '../features/queue/repeatMode'
+import type {
+  RemoteJumpBackwardEvent,
+  RemoteJumpForwardEvent,
+  RemotePlayIdEvent,
+  RemotePlaySearchEvent,
+  RemoteSeekEvent,
+  RemoteSetRatingEvent,
+  RemoteSkipEvent
+} from '../features/remoteControls'
+import type { SleepTimer, SleepTimerChangedEvent } from '../features/sleepTimer'
+import type { ResolvedTrack, Track } from '../types'
+import type { NativeBrowserConfiguration } from '../types/browser-native'
+
+export type EqualizerSettings = {
+  activePreset?: string
+  bandCount: number
+  bandLevels: number[]
+  centerBandFrequencies: number[]
+  enabled: boolean
+  lowerBandLevelLimit: number
+  presets: string[]
+  upperBandLevelLimit: number
+}
+
+export type IosOutputType =
+  | 'built-in-speaker'
+  | 'built-in-receiver'
+  | 'airplay'
+  | 'bluetooth-a2dp'
+  | 'bluetooth-hfp'
+  | 'bluetooth-le'
+  | 'headphones'
+  | 'car-audio'
+  | 'hdmi'
+  | 'usb-audio'
+  | 'other'
+
+/**
+ * Audio output information (iOS only).
+ */
+export type IosOutput = {
+  /** The output port type */
+  type: IosOutputType
+  /** Human-readable device name (e.g., "AirPods Pro", "iPhone Speaker") */
+  name: string
+  /** Whether this is an external output (false for built-in speaker/receiver) */
+  external: boolean
+}
+
+export interface AudioBrowser extends HybridObject<{
+  ios: 'swift'
+  android: 'kotlin'
+}> {
+  // MARK: browser api
+  path: string | undefined
+  tabs: Track[] | undefined
+  navigatePath(path: string): void
+  navigateTrack(track: Track): void
+  onSearch(query: string): Promise<Track[]>
+  getContent(): ResolvedTrack | undefined
+  onPathChanged: (path: string) => void
+  onContentChanged: (content: ResolvedTrack | undefined) => void
+  onTabsChanged: (tabs: Track[]) => void
+  onNavigationError: (data: NavigationErrorEvent) => void
+  getNavigationError(): NavigationError | undefined
+  onFormattedNavigationError: (
+    formattedError: FormattedNavigationError | undefined
+  ) => void
+  getFormattedNavigationError(): FormattedNavigationError | undefined
+  notifyContentChanged(path: string): void
+  setFavorites(favorites: string[]): void
+  configuration: NativeBrowserConfiguration
+
+  // MARK: player init and config
+  setupPlayer(options: PartialSetupPlayerOptions): Promise<void>
+  updateOptions(options: NativeUpdateOptions): void
+  getOptions(): UpdateOptions
+
+  // // MARK: player events
+  onChapterMetadata: (chapters: ChapterMetadata[]) => void
+  onTrackMetadata: (metadata: TrackMetadata) => void
+  onTimedMetadata: (metadata: TimedMetadata) => void
+  onPlaybackActiveTrackChanged: (data: PlaybackActiveTrackChangedEvent) => void
+  onPlaybackError: (data: PlaybackErrorEvent) => void
+  onPlaybackPlayWhenReadyChanged: (
+    data: PlaybackPlayWhenReadyChangedEvent
+  ) => void
+  onPlaybackPlayingState: (data: PlayingState) => void
+  onPlaybackProgressUpdated: (data: PlaybackProgressUpdatedEvent) => 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
+  onRemotePlayId: (event: RemotePlayIdEvent) => void
+  onRemotePlaySearch: (event: RemotePlaySearchEvent) => void
+  onRemotePrevious: () => void
+  onRemoteSeek: (event: RemoteSeekEvent) => void
+  onRemoteSetRating: (event: RemoteSetRatingEvent) => void
+  onRemoteSkip: (event: RemoteSkipEvent) => void
+  onRemoteStop: () => void
+  onOptionsChanged: (event: Options) => void
+  onFavoriteChanged: (event: FavoriteChangedEvent) => void
+  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
+  handleRemotePlayId: ((event: RemotePlayIdEvent) => void) | undefined
+  handleRemotePlaySearch: ((event: RemotePlaySearchEvent) => void) | undefined
+  handleRemotePrevious: (() => void) | undefined
+  handleRemoteSeek: ((event: RemoteSeekEvent) => void) | undefined
+  handleRemoteSkip: (() => void) | undefined
+  handleRemoteStop: (() => void) | undefined
+
+  // MARK: player api
+  load(track: Track): void
+  reset(): void
+  play(): void
+  pause(): void
+  togglePlayback(): void
+  stop(): void
+  setPlayWhenReady(playWhenReady: boolean): void
+  getPlayWhenReady(): boolean
+  seekTo(position: number): void
+  seekBy(offset: number): void
+  setVolume(level: number): void
+  getVolume(): number
+  setRate(rate: number): void
+  getRate(): number
+  getProgress(): Progress
+  getPlayback(): Playback
+  getPlayingState(): PlayingState
+  getRepeatMode(): RepeatMode
+  setRepeatMode(mode: RepeatMode): void
+  getShuffleEnabled(): boolean
+  setShuffleEnabled(enabled: boolean): void
+  getPlaybackError(): PlaybackError | undefined
+  retry(): void
+  getSleepTimer(): SleepTimer
+  setSleepTimer(seconds: number): void
+  setSleepTimerToEndOfTrack(): void
+  clearSleepTimer(): boolean
+
+  // MARK: queue management
+  add(tracks: Track[], insertBeforeIndex?: number): void
+  move(fromIndex: number, toIndex: number): void
+  remove(indexes: number[]): void
+  removeUpcomingTracks(): void
+  skip(index: number, initialPosition?: number): void
+  skipToNext(initialPosition?: number): void
+  skipToPrevious(initialPosition?: number): void
+  /**
+   * Sets the favorited state of the currently playing track.
+   * Updates the heart icon in media controllers (notification, Android Auto, CarPlay).
+   */
+  setActiveTrackFavorited(favorited: boolean): void
+  /**
+   * Toggles the favorited state of the currently playing track.
+   */
+  toggleActiveTrackFavorited(): void
+  setQueue(tracks: Track[], startIndex?: number, startPositionMs?: number): void
+  getQueue(): Track[]
+  getTrack(index: number): Track | undefined
+  getActiveTrackIndex(): number | undefined
+  getActiveTrack(): Track | undefined
+
+  // MARK: now playing metadata
+  /**
+   * Updates the now playing notification metadata.
+   * Pass null to clear overrides and revert to track metadata.
+   */
+  updateNowPlaying(update: NowPlayingUpdate | undefined): void
+  /**
+   * Gets the current now playing metadata (override if set, else track metadata).
+   */
+  getNowPlaying(): NowPlayingMetadata | undefined
+
+  // MARK: network connectivity
+  getOnline(): boolean
+  onOnlineChanged: (online: boolean) => void
+
+  // MARK: system volume
+  /**
+   * Gets the current system volume (0.0 to 1.0).
+   */
+  getSystemVolume(): number
+  /**
+   * Sets the system volume (0.0 to 1.0).
+   * Note: On iOS this is a no-op as Apple doesn't provide a public API to set system volume.
+   */
+  setSystemVolume(volume: number): void
+  /**
+   * Called when the system volume changes.
+   */
+  onSystemVolumeChanged: (volume: number) => void
+
+  // MARK: external audio output (iOS only)
+  /**
+   * Gets the current audio output info.
+   * Always returns a value on iOS, undefined on Android.
+   */
+  getIosOutput(): IosOutput | undefined
+  /**
+   * Called when audio output changes (iOS only).
+   * Never fires on Android.
+   */
+  onIosOutputChanged: (output: IosOutput) => void
+  /**
+   * Opens the system output picker (iOS only).
+   * Allows users to select output device (speaker, AirPlay, Bluetooth, etc.).
+   * No-op on Android.
+   */
+  openIosOutputPicker(): void
+
+  // MARK: equalizer (Android only)
+  getEqualizerSettings(): EqualizerSettings | undefined
+  setEqualizerEnabled(enabled: boolean): void
+  setEqualizerPreset(preset: string): void
+  setEqualizerLevels(levels: number[]): void
+  onEqualizerChanged: (settings: EqualizerSettings) => void
+
+  // MARK: battery optimization (Android only)
+  /**
+   * Check if a battery warning is pending.
+   * Returns true if a foreground service start was blocked and the user hasn't dismissed
+   * the warning or fixed their battery settings.
+   * Auto-clears when battery status becomes unrestricted.
+   * Always returns false on iOS.
+   */
+  getBatteryWarningPending(): boolean
+  /**
+   * Get the current battery optimization status.
+   * - `unrestricted`: App can run freely in background
+   * - `optimized`: System may limit background work (default)
+   * - `restricted`: Background services blocked
+   * Always returns `unrestricted` on iOS.
+   */
+  getBatteryOptimizationStatus(): BatteryOptimizationStatus
+  /**
+   * Dismiss the battery warning without fixing settings.
+   * Call this when the user chooses to ignore the warning.
+   * No-op on iOS.
+   */
+  dismissBatteryWarning(): void
+  /**
+   * Open the system battery settings for this app.
+   * No-op on iOS.
+   */
+  openBatterySettings(): void
+  /**
+   * Called when battery warning pending state changes.
+   * Fires when: failure occurs (true), dismissBatteryWarning() called (false),
+   * or status becomes unrestricted (false).
+   * Never fires on iOS.
+   */
+  onBatteryWarningPendingChanged: (
+    event: BatteryWarningPendingChangedEvent
+  ) => void
+  /**
+   * Called when battery optimization status changes.
+   * Fires when user returns from settings with a different status.
+   * Never fires on iOS.
+   */
+  onBatteryOptimizationStatusChanged: (
+    event: BatteryOptimizationStatusChangedEvent
+  ) => void
+}

package/src/types/browser-native.ts

@@ -0,0 +1,66 @@
+/**
+ * Native Configuration Types
+ *
+ * These types are used internally by the native bridge. They flatten union types
+ * into separate optional properties to reduce generated code complexity.
+ * Users should use BrowserConfiguration, not these types directly.
+ */
+
+import type {
+  ArtworkRequestConfig,
+  BrowserSourceCallback,
+  CarPlayNowPlayingButton,
+  FormatNavigationErrorCallback,
+  MediaRequestConfig,
+  SearchSourceCallback,
+  TransformableRequestConfig
+} from './browser'
+import type { ResolvedTrack } from './browser-nodes'
+
+/**
+ * Flattened route entry for native bridge.
+ */
+export interface NativeRouteEntry {
+  path: string
+  // Browse source (flattened)
+  browseCallback?: BrowserSourceCallback
+  browseConfig?: TransformableRequestConfig
+  browseStatic?: ResolvedTrack
+  // Search source (only used for __search__ route)
+  searchCallback?: SearchSourceCallback
+  searchConfig?: TransformableRequestConfig
+  // Per-route media/artwork config
+  media?: MediaRequestConfig
+  artwork?: ArtworkRequestConfig
+}
+
+/**
+ * Flattened browser configuration for native bridge.
+ * Converts union types to separate optional properties for simpler native code generation.
+ */
+export interface NativeBrowserConfiguration {
+  path?: string
+
+  // Request defaults
+  request?: TransformableRequestConfig
+
+  // Global media/artwork config (applied when route doesn't override)
+  media?: MediaRequestConfig
+  artwork?: ArtworkRequestConfig
+
+  // Routes as array - includes:
+  // - Explicit routes from config.routes
+  // - Root browse as __default__ entry
+  // - Tabs as __tabs__ entry (returns ResolvedTrack with children for navigation tabs)
+  // - Search as __search__ entry (has searchCallback or searchConfig)
+  routes?: NativeRouteEntry[]
+
+  // Behavior
+  singleTrack?: boolean
+  androidControllerOfflineError?: boolean
+
+  // CarPlay options
+  carPlayUpNextButton?: boolean
+  carPlayNowPlayingButtons?: CarPlayNowPlayingButton[]
+  formatNavigationError?: FormatNavigationErrorCallback
+}