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

package/src/types/index.ts

@@ -0,0 +1,2 @@
+export * from './browser'
+export * from './browser-nodes'

package/src/types/player.ts

@@ -0,0 +1,69 @@
+export type PlayerContentType = 'music' | 'speech'
+
+export interface PlayerConfig {
+  contentType?: PlayerContentType
+  debug?: boolean
+  autoPlay?: boolean
+}
+
+export interface MediaSessionConfig {
+  /**
+   * When true, activates next/previous track controls in the media notification / lock screen.
+   * Default is false.
+   */
+  skipItemControls?: boolean
+  /**
+   * When true, activates skip forward/backward controls in the media notification / lock screen.
+   * Default is false. By default these controls skip 15000ms (15s), but a number value can be provided to customize the skip interval in milliseconds.
+   */
+  skipTimeControls?: boolean | number
+  /**
+   * Configures whether to show a pause or stop button in the media notification / lock screen.
+   * - 'pause': Shows pause button (default behavior)
+   * - 'stop': Shows stop button that stops playback / loading and resets position to 0
+   *
+   * Note: On iOS, stop button only shows for live streams.
+   */
+  stopControl?: 'pause' | 'stop'
+}
+
+export interface PlaybackError {
+  error: string
+  errorCode?: number
+}
+
+/**
+ * Represents the current playback state of the audio player.
+ */
+export type PlaybackState =
+  /** Empty queue */
+  | 'idle'
+  /**
+   * Playback is stopped but the track remains loaded. Position is reset to 0.
+   * Media session controls remain visible.
+   */
+  | 'stopped'
+  /**
+   * The track is being loaded or buffered and is not yet ready for playback.
+   */
+  | 'loading'
+  /**
+   * The track is currently playing.
+   */
+  | 'playing'
+  /**
+   * Playback is paused and can be resumed or started by calling play().
+   */
+  | 'paused'
+  /**
+   * An error occurred during playback. Check getError() for details.
+   */
+  | 'error'
+
+export type RepeatMode = 'off' | 'queue' | 'track'
+
+export interface PlaybackProgress {
+  position: number
+  duration: number
+  buffered: number
+}

package/src/utils/LazyNativeEmitter.ts

@@ -0,0 +1,58 @@
+/** @internal */
+type Callback<T> = (arg: T) => void
+
+/**
+ * @internal
+ * A lightweight event emitter that lazily bridges native callbacks to multiple JavaScript listeners.
+ *
+ * The native callback is only assigned when the first listener is added, making the emitter
+ * creation lightweight with no side effects until actually used.
+ *
+ * Use this for optional/rare events like remote controls where most apps won't need to listen.
+ * For critical state changes (playback, progress, etc.), use NativeEmitter instead to ensure
+ * no events are missed.
+ *
+ * @example
+ * ```typescript
+ * export const onRemotePlay = LazyEmitter.emitterize<void>(
+ *   (cb) => (nativeBrowser.onRemotePlay = cb)
+ * )
+ * ```
+ */
+export class LazyNativeEmitter<T> {
+  private setter: (callback: (data: T) => void) => void
+  private listeners: Set<(arg: T) => void> | undefined
+
+  constructor(setter: (callback: (data: T) => void) => void) {
+    this.setter = setter
+  }
+
+  private getListeners(): Set<Callback<T>> {
+    if (this.listeners) return this.listeners
+    const listeners = (this.listeners = new Set())
+    this.setter((data: T) => {
+      for (const listener of listeners) {
+        listener(data)
+      }
+    })
+    return listeners
+  }
+
+  addListener(callback: Callback<T>): () => void {
+    const listeners = this.getListeners()
+    listeners.add(callback)
+    return () => listeners.delete(callback)
+  }
+
+  /**
+   * Creates a lazy emitter subscription function for a native callback.
+   * @param setter - Function that sets the native callback property
+   * @returns A subscription function that returns an unsubscribe function
+   */
+  static emitterize<T>(
+    setter: (callback: (data: T) => void) => void
+  ): (callback: Callback<T>) => () => void {
+    const emitter = new LazyNativeEmitter(setter)
+    return (callback: Callback<T>) => emitter.addListener(callback)
+  }
+}

package/src/utils/NativeUpdatedValue.ts

@@ -0,0 +1,56 @@
+/** @internal */
+type Callback<T> = (arg: T) => void
+
+/**
+ * @internal
+ * Bridges native value changes to JavaScript, storing the latest value for immediate access.
+ *
+ * Subscribes to native changes immediately at module load to ensure no updates are missed.
+ * The `lastValue` property caches the most recent value, allowing hooks to read the current
+ * state synchronously without calling a separate getter function.
+ *
+ * Use this for state-based values that have a "current value" (playback state, options, progress).
+ * For discrete events without a current value (remote controls), use LazyNativeEmitter instead.
+ *
+ * @example
+ * ```typescript
+ * export const onPlaybackChanged = NativeUpdatedValue.emitterize<Playback>(
+ *   (cb) => (nativeBrowser.onPlaybackChanged = cb)
+ * )
+ *
+ * export function usePlayback(): Playback {
+ *   return useUpdatedNativeValue(getPlayback, onPlaybackChanged)
+ * }
+ * ```
+ */
+export class NativeUpdatedValue<T> {
+  private listeners = new Set<Callback<T>>()
+  lastValue: T | undefined = undefined
+
+  constructor(setter: (callback: (data: T) => void) => void) {
+    // Install native callback immediately at module load
+    setter((data: T) => {
+      this.lastValue = data
+      for (const listener of this.listeners) {
+        listener(data)
+      }
+    })
+  }
+
+  addListener(callback: Callback<T>): () => void {
+    this.listeners.add(callback)
+    return () => this.listeners.delete(callback)
+  }
+
+  /**
+   * Creates a native value subscription.
+   *
+   * @param setter - Function that sets the native callback property
+   * @returns The subscription instance with lastValue and addListener
+   */
+  static emitterize<T>(
+    setter: (callback: (data: T) => void) => void
+  ): NativeUpdatedValue<T> {
+    return new NativeUpdatedValue(setter)
+  }
+}

package/src/utils/resolveAssetSource.ts

@@ -0,0 +1,4 @@
+import { Image } from 'react-native'
+// eslint-disable-next-line @typescript-eslint/unbound-method
+const resolve = Image.resolveAssetSource
+export default resolve

package/src/utils/useDebug.ts

@@ -0,0 +1,283 @@
+import { useEffect, useRef, useSyncExternalStore } from 'react'
+import { useContent, usePath } from '../features/browser'
+import { useNavigationError, usePlaybackError } from '../features/errors'
+import {
+  onChapterMetadata,
+  onTimedMetadata,
+  onTrackMetadata
+} from '../features/metadata'
+import { useOnline } from '../features/network'
+import { useNowPlaying } from '../features/nowPlaying'
+import type { PlayingState } from '../features/playback/playing'
+import { usePlayingState } from '../features/playback/playing'
+import { usePlayWhenReady } from '../features/playback/playWhenReady'
+import { useProgress } from '../features/playback/progress'
+import type { PlaybackState } from '../features/playback/state'
+import { usePlayback } from '../features/playback/state'
+import type { Options } from '../features/player/options'
+import { useOptions } from '../features/player/options'
+import { useActiveTrack } from '../features/queue/activeTrack'
+import { useQueue } from '../features/queue/queue'
+import type { RepeatMode } from '../features/queue/repeatMode'
+import { useRepeatMode } from '../features/queue/repeatMode'
+import { useShuffle } from '../features/queue/shuffle'
+import type { NowPlayingMetadata } from '../features/metadata'
+import type { Track } from '../types'
+
+// MARK: - Types
+
+interface DebugLogEntry {
+  timestamp: number
+  elapsed: number | null
+  type: 'initial' | 'change' | 'metadata'
+  message: string
+}
+
+interface DebugState {
+  activeTrack: Track | undefined
+  state: PlaybackState
+  playingState: PlayingState
+  playWhenReady: boolean
+  position: number
+  duration: number
+  queue: string
+  repeatMode: RepeatMode
+  shuffle: boolean
+  options: Options
+  online: boolean
+  nowPlaying: NowPlayingMetadata | undefined
+  playbackError: string | null
+  navigationError: string | null
+  path: string | null
+  content: string | null
+}
+
+interface DebugOptions {
+  /** Whether logging is enabled (default: __DEV__) */
+  enabled?: boolean
+  /** Whether to log stream metadata events (default: false) */
+  metadata?: boolean
+}
+
+// MARK: - Log Store
+
+const MAX_LOG_ENTRIES = 100
+let debugLogs: DebugLogEntry[] = []
+const debugLogListeners = new Set<() => void>()
+
+function addDebugLog(entry: DebugLogEntry) {
+  debugLogs = [...debugLogs.slice(-(MAX_LOG_ENTRIES - 1)), entry]
+  debugLogListeners.forEach((listener) => listener())
+}
+
+function clearDebugLogs() {
+  debugLogs = []
+  debugLogListeners.forEach((listener) => listener())
+}
+
+function subscribeToDebugLogs(listener: () => void) {
+  debugLogListeners.add(listener)
+  return () => debugLogListeners.delete(listener)
+}
+
+function getDebugLogs() {
+  return debugLogs
+}
+
+// MARK: - State Hook
+
+function useDebugState(): DebugState {
+  const activeTrack = useActiveTrack()
+  const playback = usePlayback()
+  const playingState = usePlayingState()
+  const playWhenReady = usePlayWhenReady()
+  const progress = useProgress()
+  const queue = useQueue()
+  const repeatMode = useRepeatMode()
+  const shuffle = useShuffle()
+  const options = useOptions()
+  const playbackError = usePlaybackError()
+  const navigationError = useNavigationError()
+  const online = useOnline()
+  const nowPlaying = useNowPlaying()
+  const path = usePath()
+  const content = useContent()
+
+  return {
+    activeTrack,
+    state: playback.state,
+    playingState,
+    playWhenReady,
+    position: Math.round(progress.position),
+    duration: Math.round(progress.duration),
+    queue: queue.map((t) => t.src).join(', '),
+    repeatMode,
+    shuffle,
+    options,
+    online,
+    nowPlaying,
+    playbackError: playbackError?.message ?? null,
+    navigationError: navigationError?.message ?? null,
+    path: path ?? null,
+    content: content?.title ?? null
+  }
+}
+
+// MARK: - Main Hook
+
+/**
+ * Debug hook that provides state inspection and change logging.
+ *
+ * @param options - Configuration options
+ * @returns Debug object with state, logs, and clear function
+ *
+ * @example
+ * ```tsx
+ * function MyScreen() {
+ *   const debug = useDebug()
+ *   // debug.state - current state
+ *   // debug.logs - log history
+ *   // debug.clear() - clear logs
+ * }
+ *
+ * // With metadata logging for live streams
+ * function RadioScreen() {
+ *   const debug = useDebug({ metadata: true })
+ * }
+ * ```
+ */
+export function useDebug(options: DebugOptions = {}) {
+  const { enabled = __DEV__, metadata = false } = options
+
+  const state = useDebugState()
+  const logs = useSyncExternalStore(
+    subscribeToDebugLogs,
+    getDebugLogs,
+    getDebugLogs
+  )
+
+  const prevRef = useRef<DebugState | null>(null)
+  const lastChangeRef = useRef(Date.now())
+  const isFirstRender = useRef(true)
+
+  // State change logging
+  useEffect(() => {
+    if (!enabled) return
+
+    const now = Date.now()
+    const elapsed = now - lastChangeRef.current
+    const prev = prevRef.current
+    const changes: string[] = []
+
+    for (const key of Object.keys(state) as (keyof DebugState)[]) {
+      // Skip small position changes to reduce noise
+      if (key === 'position') {
+        const prevPos = prev?.[key]
+        const currPos = state[key]
+        if (prevPos !== undefined && Math.abs(prevPos - currPos) < 2) {
+          continue
+        }
+      }
+      if (!Object.is(prev?.[key], state[key])) {
+        changes.push(`${key}:
+    old → ${formatIndented(prev?.[key])}
+    new → ${formatIndented(state[key])}\n`)
+      }
+    }
+
+    if (isFirstRender.current) {
+      const message = Object.entries(state)
+        .map(([k, v]) => `${k}: ${format(v)}`)
+        .join('\n')
+      console.log(
+        `[useDebug] initial state:\n  ${message.split('\n').join('\n  ')}`
+      )
+      addDebugLog({ timestamp: now, elapsed: null, type: 'initial', message })
+      isFirstRender.current = false
+      lastChangeRef.current = now
+    } else if (changes.length > 0) {
+      const message = changes.join('\n')
+      console.log(
+        `[useDebug] (+${elapsed}ms)\n  ${message.split('\n').join('\n  ')}`
+      )
+      addDebugLog({ timestamp: now, elapsed, type: 'change', message })
+      lastChangeRef.current = now
+    }
+
+    prevRef.current = state
+  })
+
+  // Metadata logging
+  useEffect(() => {
+    if (!enabled || !metadata) return
+
+    const logMetadata = (type: string, message: string) => {
+      const now = Date.now()
+      const elapsed = now - lastChangeRef.current
+      console.log(
+        `[useDebug:metadata] ${type} (+${elapsed}ms)\n  ${message.split('\n').join('\n  ')}`
+      )
+      addDebugLog({
+        timestamp: now,
+        elapsed,
+        type: 'metadata',
+        message: `[${type}] ${message}`
+      })
+      lastChangeRef.current = now
+    }
+
+    const unsubscribeTrack = onTrackMetadata.addListener((metadata) => {
+      const fields = Object.entries(metadata)
+        .filter(([, v]) => v != null)
+        .map(([k, v]) => `${k}: "${v}"`)
+      logMetadata('track', fields.join('\n'))
+    })
+
+    const unsubscribeTimed = onTimedMetadata.addListener((metadata) => {
+      const fields = Object.entries(metadata)
+        .filter(([, v]) => v != null)
+        .map(([k, v]) => `${k}: "${v}"`)
+      logMetadata('timed', fields.join('\n'))
+    })
+
+    const unsubscribeChapter = onChapterMetadata.addListener((chapters) => {
+      logMetadata('chapter', `${chapters.length} chapters`)
+    })
+
+    return () => {
+      unsubscribeTrack()
+      unsubscribeTimed()
+      unsubscribeChapter()
+    }
+  }, [enabled, metadata])
+
+  return {
+    state,
+    logs,
+    clear: clearDebugLogs
+  }
+}
+
+// MARK: - Formatters
+
+function format(value: unknown): string {
+  if (value === undefined) return 'undefined'
+  if (value === null) return 'null'
+  if (typeof value === 'string') return `"${value}"`
+  if (Array.isArray(value)) return `[${value.map((v) => format(v)).join(', ')}]`
+  if (typeof value === 'object') return JSON.stringify(value, null, 2)
+  // eslint-disable-next-line @typescript-eslint/no-base-to-string
+  return String(value)
+}
+
+function indent(str: string, spaces: number): string {
+  const pad = ' '.repeat(spaces)
+  return str
+    .split('\n')
+    .map((line, index) => (index === 0 ? line : pad + line))
+    .join('\n')
+}
+
+function formatIndented(value: unknown): string {
+  return indent(format(value), 4)
+}

package/src/utils/useNativeUpdatedValue.ts

@@ -0,0 +1,41 @@
+import { useEffect, useState } from 'react'
+import { NativeUpdatedValue } from './NativeUpdatedValue'
+
+/**
+ * Generic hook for values that are fetched from native and updated via callbacks.
+ *
+ * Reads the initial value from emitter.lastValue to avoid race conditions between
+ * initial getter() call and subscription setup.
+ *
+ * @param getter - Fallback synchronous function to get the current value if emitter has no lastValue yet
+ * @param emitter - NativeUpdatedValue that stores lastValue and provides subscription
+ * @param eventKey - Optional key to extract from the event object passed to the callback
+ * @returns The current value, updated when the callback fires
+ */
+export function useNativeUpdatedValue<T, E = T>(
+  getter: () => T,
+  emitter: NativeUpdatedValue<E>,
+  eventKey?: keyof E
+): T {
+  const [value, setValue] = useState(() => {
+    const { lastValue } = emitter
+    if (lastValue != null) {
+      return (eventKey !== undefined ? lastValue[eventKey] : lastValue) as T
+    }
+    return getter()
+  })
+
+  useEffect(() => {
+    const { lastValue } = emitter
+    if (lastValue != null) {
+      const newValue = eventKey !== undefined ? lastValue[eventKey] : lastValue
+      setValue(newValue as T)
+    }
+    return emitter.addListener((event) => {
+      const newValue = eventKey !== undefined ? event[eventKey] : event
+      setValue(newValue as T)
+    })
+  }, [emitter, eventKey])
+
+  return value
+}