react-native-audio-browser 0.2.0-next.8 → 0.2.0

package/src/features/browser.ts

@@ -1,14 +1,207 @@
-import type { BrowserConfiguration, ResolvedTrack, Track } from '../types'
+import type {
+  BrowserConfiguration,
+  BrowserSource,
+  BrowserSourceCallback,
+  ResolvedTrack,
+  RouteConfig,
+  SearchSource,
+  SearchSourceCallback,
+  TabsSource,
+  Track,
+  TransformableRequestConfig
+} from '../types'
+import type {
+  NativeBrowserConfiguration,
+  NativeRouteEntry
+} from '../types/browser-native'
 import { nativeBrowser } from '../native'
 import { NativeUpdatedValue } from '../utils/NativeUpdatedValue'
 import { useNativeUpdatedValue } from '../utils/useNativeUpdatedValue'
-import {
-  SEARCH_ROUTE_PATH,
-  toNativeConfig,
-  validateBrowserConfiguration
-} from './browser-config'
 
-let currentConfiguration: BrowserConfiguration | undefined
+// ─────────────────────────────────────────────────────────────────────────────
+// Configuration Transformation
+// ─────────────────────────────────────────────────────────────────────────────
+
+function isCallback(
+  source: unknown
+): source is (...args: unknown[]) => unknown {
+  return typeof source === 'function'
+}
+
+function isTransformableRequestConfig(
+  source: unknown
+): source is TransformableRequestConfig {
+  if (typeof source !== 'object' || source === null) return false
+  const obj = source as Record<string, unknown>
+  // Has request config properties (not a ResolvedTrack which has 'title')
+  return (
+    'baseUrl' in obj ||
+    'path' in obj ||
+    'headers' in obj ||
+    'query' in obj ||
+    'transform' in obj
+  )
+}
+
+function isRouteConfig(source: unknown): source is RouteConfig {
+  if (typeof source !== 'object' || source === null) return false
+  const obj = source as Record<string, unknown>
+  // RouteConfig has browse/media/artwork properties at the top level
+  return 'browse' in obj || ('media' in obj && !('baseUrl' in obj))
+}
+
+function flattenBrowseSource(source: BrowserSource | undefined): {
+  browseCallback?: NativeRouteEntry['browseCallback']
+  browseConfig?: NativeRouteEntry['browseConfig']
+  browseStatic?: NativeRouteEntry['browseStatic']
+} {
+  if (!source) return {}
+  if (isCallback(source))
+    return { browseCallback: source as NativeRouteEntry['browseCallback'] }
+  if (isTransformableRequestConfig(source))
+    return { browseConfig: source as NativeRouteEntry['browseConfig'] }
+  return { browseStatic: source as NativeRouteEntry['browseStatic'] }
+}
+
+/**
+ * Converts a SearchSource to a NativeRouteEntry for the __search__ path.
+ */
+function searchSourceToRouteEntry(source: SearchSource): NativeRouteEntry {
+  if (isCallback(source)) {
+    return {
+      path: SEARCH_ROUTE_PATH,
+      searchCallback: source as SearchSourceCallback
+    }
+  }
+  return {
+    path: SEARCH_ROUTE_PATH,
+    searchConfig: source as TransformableRequestConfig
+  }
+}
+
+/**
+ * Wraps a Track[] into a ResolvedTrack for tabs.
+ * Tabs are represented as a special route that returns children.
+ */
+function wrapTracksAsResolvedTrack(tracks: Track[]): ResolvedTrack {
+  return {
+    url: TABS_ROUTE_PATH,
+    title: 'Tabs',
+    children: tracks
+  }
+}
+
+/**
+ * Converts a TabsSource to a NativeRouteEntry for the __tabs__ path.
+ * Track[] is wrapped in ResolvedTrack, callbacks are wrapped to return ResolvedTrack.
+ */
+function tabsSourceToRouteEntry(source: TabsSource): NativeRouteEntry {
+  if (Array.isArray(source)) {
+    // Static Track[] - wrap as ResolvedTrack
+    return {
+      path: TABS_ROUTE_PATH,
+      browseStatic: wrapTracksAsResolvedTrack(source)
+    }
+  }
+
+  if (isCallback(source)) {
+    // Callback returning Track[] - wrap to return ResolvedTrack
+    const wrappedCallback: BrowserSourceCallback = async () => {
+      const tracks = await source()
+      return wrapTracksAsResolvedTrack(tracks)
+    }
+    return {
+      path: TABS_ROUTE_PATH,
+      browseCallback: wrappedCallback
+    }
+  }
+
+  // TransformableRequestConfig - native will handle wrapping the response
+  return {
+    path: TABS_ROUTE_PATH,
+    browseConfig: source
+  }
+}
+
+function flattenRouteEntry(
+  path: string,
+  source: BrowserSource | RouteConfig
+): NativeRouteEntry {
+  if (isRouteConfig(source)) {
+    return {
+      path,
+      ...flattenBrowseSource(source.browse),
+      media: source.media,
+      artwork: source.artwork
+    }
+  }
+  return { path, ...flattenBrowseSource(source) }
+}
+
+/** Internal path used for the default/root browse source */
+const DEFAULT_ROUTE_PATH = '__default__'
+
+/** Internal path used for navigation tabs */
+const TABS_ROUTE_PATH = '__tabs__'
+
+/** Internal path used for search */
+const SEARCH_ROUTE_PATH = '__search__'
+
+function flattenRoutes(
+  routes: Record<string, BrowserSource | RouteConfig> | undefined,
+  rootBrowse: BrowserSource | undefined,
+  tabs: TabsSource | undefined,
+  search: SearchSource | undefined
+): NativeRouteEntry[] | undefined {
+  const entries: NativeRouteEntry[] = []
+
+  // Add explicit routes
+  if (routes) {
+    for (const [path, source] of Object.entries(routes)) {
+      entries.push(flattenRouteEntry(path, source))
+    }
+  }
+
+  // Add root browse as default fallback
+  if (rootBrowse) {
+    entries.push(flattenRouteEntry(DEFAULT_ROUTE_PATH, rootBrowse))
+  }
+
+  // Add tabs as special route
+  if (tabs) {
+    entries.push(tabsSourceToRouteEntry(tabs))
+  }
+
+  // Add search as special route
+  if (search) {
+    entries.push(searchSourceToRouteEntry(search))
+  }
+
+  return entries.length > 0 ? entries : undefined
+}
+
+function toNativeConfig(
+  config: BrowserConfiguration
+): NativeBrowserConfiguration {
+  return {
+    path: config.path,
+    request: config.request,
+    media: config.media,
+    artwork: config.artwork,
+    routes: flattenRoutes(
+      config.routes,
+      config.browse,
+      config.tabs,
+      config.search
+    ),
+    singleTrack: config.singleTrack,
+    handleTrackLoad: config.handleTrackLoad,
+    androidControllerOfflineError: config.androidControllerOfflineError,
+    carPlayUpNextButton: config.carPlayUpNextButton,
+    carPlayNowPlayingButtons: config.carPlayNowPlayingButtons,
+    formatNavigationError: config.formatNavigationError
+  }
+}
 
 /**
  * Configures the browser with routes, tabs, and other settings.
@@ -17,30 +210,13 @@ let currentConfiguration: BrowserConfiguration | undefined
  * - Android Auto / CarPlay browsing integration
  * - Playback of browsable tracks via navigate()
  *
- * Calling this again REPLACES the entire configuration (no merging) and
- * re-runs initial navigation — external browse UIs such as CarPlay reset to
- * the first tab. For values that change at runtime (base URL, locale, auth
- * token), don't reconfigure: read them inside a `request`/`browse` resolver
- * or a `transform`, and call {@link invalidateAllContent} so every surface
- * re-fetches in place.
- *
  * @param configuration - Browser configuration including routes, tabs, media config, etc.
  *
  * @example
  * ```ts
  * configureBrowser({
- *   request: { baseUrl: 'https://api.example.com' },
  *   routes: {
- *     // `{id}` is a route parameter — see the `routes` docs for matching rules.
- *     '/albums/{id}': async ({ routeParams }) => fetchAlbumPage(routeParams?.id),
- *     // Remapping a browse path to a different API path requires a transform;
- *     // a static `path` on a request config does NOT rewrite the path.
- *     '/artists/{id}': {
- *       transformSync: (request, routeParams) => ({
- *         ...request,
- *         path: `/api/v2/artists/${routeParams?.id}`
- *       })
- *     }
+ *     '/albums/:id': { path: '/api/albums/:id' }
  *   },
  *   tabs: [
  *     { title: 'Home', url: '/' },
@@ -50,26 +226,9 @@ let currentConfiguration: BrowserConfiguration | undefined
  * ```
  */
 export function configureBrowser(configuration: BrowserConfiguration): void {
-  // __DEV__ is a React Native global; absent under plain node (vitest).
-  if (typeof __DEV__ !== 'undefined' && __DEV__) {
-    validateBrowserConfiguration(configuration)
-  }
-  currentConfiguration = configuration
   nativeBrowser.configuration = toNativeConfig(configuration)
 }
 
-/**
- * Returns the configuration last passed to {@link configureBrowser}, in its
- * original public shape (the native getter exposes only the lowered internal
- * form). `undefined` until the browser is configured.
- *
- * Treat the returned object as read-only: it is the live reference, and
- * mutating it does NOT reconfigure the browser — call configureBrowser again.
- */
-export function getBrowserConfiguration(): BrowserConfiguration | undefined {
-  return currentConfiguration
-}
-
 export function navigate(pathOrTrack: string | Track) {
   if (typeof pathOrTrack === 'string') {
     return nativeBrowser.navigatePath(pathOrTrack)
@@ -129,22 +288,6 @@ export const notifyContentChanged = (path: string): void => {
   nativeBrowser.notifyContentChanged(path)
 }
 
-/**
- * Invalidates all cached browse content and refreshes every currently-displayed
- * browse surface. Use when something app-wide changed (locale switch, sign-out,
- * etc.) and every browse path should re-fetch from its route handler — unlike
- * {@link notifyContentChanged}, which targets a single path.
- *
- * @example
- * ```ts
- * // After the user changes the app language
- * invalidateAllContent()
- * ```
- */
-export const invalidateAllContent = (): void => {
-  nativeBrowser.invalidateAllContent()
-}
-
 /**
  * Returns whether search functionality is configured via `configureBrowser({ search: ... })`.
  */

package/src/features/equalizer.ts

@@ -46,7 +46,7 @@ export function setEqualizerLevels(levels: number[]): void {
 /**
  * Subscribes to equalizer settings changes (Android only).
  * @param callback - Called when equalizer settings change
- * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
+ * @returns Cleanup function to unsubscribe
  */
 export const onEqualizerChanged =
   NativeUpdatedValue.emitterize<EqualizerSettings>(

package/src/features/errors.ts

@@ -6,73 +6,13 @@ import { useNativeUpdatedValue } from '../utils/useNativeUpdatedValue'
 // Re-export for Nitro spec
 export type { FormattedNavigationError } from '../types/browser'
 
-/**
- * Normalized, cross-platform classification of a playback failure.
- *
- * Both platforms map their native failure onto this set, so consumers can
- * branch on it without knowing whether the error came from AVFoundation or
- * ExoPlayer. Use this — not `code` — for anything user-visible.
- *
- * - `'offline'` - The device had no network connection at the moment of
- *   failure. The stream itself may be fine.
- * - `'unreachable'` - The stream host could not be reached: DNS failure,
- *   connection refused, timed out, or the connection dropped while loading.
- * - `'not-found'` - The server said this stream is gone (HTTP 404 / 410).
- *   Retrying will not help; the station is dead.
- * - `'rejected'` - The server refused the request (HTTP 401 / 403), e.g.
- *   geo-blocking or an expired token.
- * - `'server-error'` - The server responded with 5xx. Usually transient.
- * - `'unplayable'` - The stream was fetched but cannot be played: unknown
- *   container, unsupported codec, or a decoder failure.
- * - `'stalled'` - Playback had started and then stopped, and the player
- *   exhausted its recovery budget without recovering.
- * - `'unknown'` - The failure could not be classified. Inspect `code`.
- */
-export type PlaybackErrorKind =
-  | 'offline'
-  | 'unreachable'
-  | 'not-found'
-  | 'rejected'
-  | 'server-error'
-  | 'unplayable'
-  | 'stalled'
-  | 'unknown'
-
 export type PlaybackError = {
-  /** Normalized classification. Branch on this, not on `code`. */
-  kind: PlaybackErrorKind
-  /**
-   * The raw native failure identifier, for diagnostics and telemetry only.
-   * Platform-specific and unstable: loader cases on iOS
-   * (`failed-to-load`, `playback-failed`, …), lower-cased ExoPlayer error
-   * names on Android (`io-bad-http-status`, `parsing-container-malformed`, …).
-   */
   code: string
   message: string
-  /** HTTP status code, when the failure came from an HTTP response. */
-  statusCode?: number
-  /**
-   * True while the player is still retrying this failure in the background.
-   *
-   * A retrying error arrives via `onPlaybackChanged` with the playback state
-   * still `loading`/`buffering` (or `paused`) — show it as advisory ("Stream
-   * unreachable" over a spinner), because playback may yet recover. It clears
-   * (the next `Playback` carries no error) once data flows again, and hardens
-   * into a terminal error (state `error`, `retrying` absent) when the retry
-   * budget runs out. Absent when retry is disabled: every error is then
-   * terminal. Native platforms only — the web implementation has no automatic
-   * retry, so its errors are always terminal.
-   */
-  retrying?: boolean
 }
 
 /**
  * Emitted when a playback error occurs.
- *
- * Terminal errors only: this fires on both edges of the `error` state —
- * entering it (with the error) and leaving it (with `error` undefined).
- * Errors the player is still retrying (`retrying: true`) are surfaced through
- * `onPlaybackChanged` instead, attached to the `loading`/`buffering` state.
  */
 export interface PlaybackErrorEvent {
   error?: PlaybackError
@@ -89,10 +29,6 @@ export interface PlaybackErrorEvent {
  * - `'callback-error'` - The browse callback returned an error (e.g., `{ error: 'message' }`).
  *   Use this for business logic errors like authentication failures or subscription requirements.
  * - `'unknown-error'` - An unexpected error occurred (e.g., invalid configuration).
- * - `'empty-content'` - The path resolved successfully but the container has no children (e.g. an
- *   empty Favorites tab, a search with no results).
- * - `'timeout'` - The resolve did not complete within the allotted time (a stalled request or
- *   unresponsive bridge). Surfaced on External surfaces that render their own browse list.
  */
 export type NavigationErrorType =
   | 'content-not-found'
@@ -100,8 +36,6 @@ export type NavigationErrorType =
   | 'http-error'
   | 'callback-error'
   | 'unknown-error'
-  | 'empty-content'
-  | 'timeout'
 
 export type NavigationError = {
   code: NavigationErrorType
@@ -134,7 +68,7 @@ export function getPlaybackError(): PlaybackError | undefined {
 /**
  * Subscribes to playback error events.
  * @param callback - Called when a playback error occurs
- * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
+ * @returns Cleanup function to unsubscribe
  */
 export const onPlaybackError =
   NativeUpdatedValue.emitterize<PlaybackErrorEvent>(
@@ -165,7 +99,7 @@ export function getNavigationError(): NavigationError | undefined {
 /**
  * Subscribes to navigation error events.
  * @param callback - Called when a navigation error occurs
- * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
+ * @returns Cleanup function to unsubscribe
  */
 export const onNavigationError =
   NativeUpdatedValue.emitterize<NavigationErrorEvent>(
@@ -198,7 +132,7 @@ export function getFormattedNavigationError():
 /**
  * Subscribes to formatted navigation error changes.
  * @param callback - Called when the formatted navigation error changes
- * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
+ * @returns Cleanup function to unsubscribe
  */
 export const onFormattedNavigationError = NativeUpdatedValue.emitterize<
   FormattedNavigationError | undefined
@@ -208,7 +142,7 @@ export const onFormattedNavigationError = NativeUpdatedValue.emitterize<
  * Hook that returns the current navigation error formatted for display.
  *
  * Native formats the error using the `formatNavigationError` callback configured
- * in `BrowserConfiguration`, or falls back to default English messages.
+ * in {@link BrowserConfiguration}, or falls back to default English messages.
  *
  * The same formatted error is used by CarPlay and Android Auto error dialogs,
  * ensuring consistent error presentation across your app and external controllers.
@@ -249,7 +183,7 @@ export const onFormattedNavigationError = NativeUpdatedValue.emitterize<
  * })
  * ```
  *
- * @see `BrowserConfiguration.formatNavigationError` - Configure custom error formatting
+ * @see {@link BrowserConfiguration.formatNavigationError} - Configure custom error formatting
  * @see {@link useNavigationError} - Access the raw error with code and status details
  */
 export function useFormattedNavigationError():

package/src/features/favorites.ts

@@ -82,7 +82,7 @@ export interface FavoriteChangedEvent {
  * The native side has already updated the track's favorite state and UI.
  *
  * @param callback - Called with the track and its new favorite state
- * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
+ * @returns Cleanup function to unsubscribe
  *
  * @example
  * ```ts

package/src/features/index.ts

@@ -12,9 +12,7 @@ export * from './playback'
 export * from './player'
 export * from './queue'
 export * from './battery'
-export * from './gate'
 export * from './browser'
-export * from './carConnection'
 export * from './equalizer'
 export * from './errors'
 export * from './favorites'

package/src/features/metadata.ts

@@ -1,8 +1,18 @@
+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
@@ -20,6 +30,8 @@ export interface TrackMetadataBase {
   mediaId?: string
   /** The track genre */
   genre?: string
+  /** The track rating */
+  rating?: Rating
 }
 
 export interface NowPlayingMetadata extends TrackMetadataBase {
@@ -36,12 +48,6 @@ 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
 }
 
 /**
@@ -99,7 +105,7 @@ export interface ChapterMetadata {
 /**
  * Subscribes to chapter metadata events.
  * @param callback - Called when chapter metadata is received
- * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
+ * @returns Cleanup function to unsubscribe
  */
 export const onChapterMetadata = NativeUpdatedValue.emitterize<
   ChapterMetadata[]
@@ -108,7 +114,7 @@ export const onChapterMetadata = NativeUpdatedValue.emitterize<
 /**
  * Subscribes to track metadata events.
  * @param callback - Called when static track metadata is received
- * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
+ * @returns Cleanup function to unsubscribe
  */
 export const onTrackMetadata = NativeUpdatedValue.emitterize<TrackMetadata>(
   (cb) => (nativeBrowser.onTrackMetadata = cb)
@@ -117,7 +123,7 @@ export const onTrackMetadata = NativeUpdatedValue.emitterize<TrackMetadata>(
 /**
  * Subscribes to timed metadata events (ICY/ID3 from live streams).
  * @param callback - Called when stream metadata is received (title, artist from ICY/ID3 tags)
- * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
+ * @returns Cleanup function to unsubscribe
  */
 export const onTimedMetadata = NativeUpdatedValue.emitterize<TimedMetadata>(
   (cb) => (nativeBrowser.onTimedMetadata = cb)

package/src/features/network.ts

@@ -17,7 +17,7 @@ export function getOnline(): boolean {
 /**
  * Subscribes to network connectivity changes.
  * @param callback - Called when network state changes
- * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
+ * @returns Cleanup function to unsubscribe
  */
 export const onOnlineChanged = NativeUpdatedValue.emitterize<boolean>(
   (cb) => (nativeBrowser.onOnlineChanged = cb)

package/src/features/nowPlaying.ts

@@ -32,49 +32,13 @@ 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
 
 /**
  * Subscribes to now playing metadata change events.
  * Fires when updateNowPlaying is called or when the track changes.
  * @param callback - Called when now playing metadata changes
- * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
+ * @returns Cleanup function to unsubscribe
  */
 export const onNowPlayingChanged =
   NativeUpdatedValue.emitterize<NowPlayingMetadata>(

package/src/features/output.ts

@@ -1,63 +1,50 @@
-import type { Output, OutputType } from '../specs/audio-browser.nitro'
+import type { IosOutput, IosOutputType } from '../specs/audio-browser.nitro'
 import { nativeBrowser } from '../native'
 import { NativeUpdatedValue } from '../utils/NativeUpdatedValue'
 import { useNativeUpdatedValue } from '../utils/useNativeUpdatedValue'
 
-export type { Output, OutputType }
+export type { IosOutput, IosOutputType }
 
 // MARK: - Actions
 
 /**
- * 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.
+ * Opens the system output picker (iOS only).
+ * Allows users to select output device (speaker, AirPlay, Bluetooth, etc.).
+ * No-op on Android.
  */
-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()
+export function openIosOutputPicker(): void {
+  nativeBrowser.openIosOutputPicker()
 }
 
 // MARK: - Getters
 
 /**
- * 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`.
+ * Gets the current audio output info.
+ * Always returns a value on iOS, undefined on Android.
  */
-export function getOutput(): Output | undefined {
-  return nativeBrowser.getOutput()
+export function getIosOutput(): IosOutput | undefined {
+  return nativeBrowser.getIosOutput()
 }
 
 // MARK: - Event Callbacks
 
 /**
- * Subscribes to current-output changes (headphones unplugged, Bluetooth speaker
- * connected, AirPlay/route selected). Fires on iOS and Android 11+; never below.
- * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
+ * 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
  */
-export const onOutputChanged = NativeUpdatedValue.emitterize<Output>(
-  (cb) => (nativeBrowser.onOutputChanged = cb)
+export const onIosOutputChanged = NativeUpdatedValue.emitterize<IosOutput>(
+  (cb) => (nativeBrowser.onIosOutputChanged = cb)
 )
 
 // MARK: - Hooks
 
 /**
- * Reactive current audio output; re-renders when it changes (e.g. AirPods
- * connect, a Bluetooth speaker is selected). `undefined` when unknown.
+ * 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.
  */
-export function useOutput(): Output | undefined {
-  return useNativeUpdatedValue(getOutput, onOutputChanged)
+export function useIosOutput(): IosOutput | undefined {
+  return useNativeUpdatedValue(getIosOutput, onIosOutputChanged)
 }