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

package/src/features/errors.ts

@@ -0,0 +1,196 @@
+import { nativeBrowser } from '../native'
+import type { FormattedNavigationError } from '../types/browser'
+import { NativeUpdatedValue } from '../utils/NativeUpdatedValue'
+import { useNativeUpdatedValue } from '../utils/useNativeUpdatedValue'
+
+// Re-export for Nitro spec
+export type { FormattedNavigationError } from '../types/browser'
+
+export type PlaybackError = {
+  code: string
+  message: string
+}
+
+/**
+ * Emitted when a playback error occurs.
+ */
+export interface PlaybackErrorEvent {
+  error?: PlaybackError
+}
+
+/**
+ * Type of navigation error that occurred.
+ *
+ * - `'content-not-found'` - No route configured for the requested path, or route resolution
+ *   returned no content. This is a configuration issue, not an HTTP 404 from the server.
+ * - `'network-error'` - Network request failed (connection error, timeout, no internet).
+ * - `'http-error'` - Server returned a non-2xx HTTP status code, or returned 2xx but response
+ *   parsing failed. Check `statusCode` and `statusCodeSuccess` for details.
+ * - `'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).
+ */
+export type NavigationErrorType =
+  | 'content-not-found'
+  | 'network-error'
+  | 'http-error'
+  | 'callback-error'
+  | 'unknown-error'
+
+export type NavigationError = {
+  code: NavigationErrorType
+  message: string
+  /** HTTP status code when code is 'http-error' */
+  statusCode?: number
+  /** True if HTTP status code was 2xx (success), useful when error is due to response parsing */
+  statusCodeSuccess?: boolean
+}
+
+/**
+ * Emitted when a navigation error occurs.
+ */
+export interface NavigationErrorEvent {
+  error?: NavigationError
+}
+
+// MARK: - Getters
+
+/**
+ * Gets the current playback error, if any.
+ * @returns The current error or undefined if there is no error
+ */
+export function getPlaybackError(): PlaybackError | undefined {
+  return nativeBrowser.getPlaybackError()
+}
+
+// MARK: - Event Callbacks
+
+/**
+ * Subscribes to playback error events.
+ * @param callback - Called when a playback error occurs
+ * @returns Cleanup function to unsubscribe
+ */
+export const onPlaybackError =
+  NativeUpdatedValue.emitterize<PlaybackErrorEvent>(
+    (cb) => (nativeBrowser.onPlaybackError = cb)
+  )
+
+// MARK: - Hooks
+
+/**
+ * Hook that returns the current playback error and updates when it changes.
+ * @returns The current playback error or undefined
+ */
+export function usePlaybackError(): PlaybackError | undefined {
+  return useNativeUpdatedValue(getPlaybackError, onPlaybackError, 'error')
+}
+
+// MARK: - Navigation Error
+
+/**
+ * Gets the current navigation error, if any.
+ * @returns The current navigation error or undefined if there is no error
+ */
+export function getNavigationError(): NavigationError | undefined {
+  const error = nativeBrowser.getNavigationError()
+  return error ?? undefined
+}
+
+/**
+ * Subscribes to navigation error events.
+ * @param callback - Called when a navigation error occurs
+ * @returns Cleanup function to unsubscribe
+ */
+export const onNavigationError =
+  NativeUpdatedValue.emitterize<NavigationErrorEvent>(
+    (cb) => (nativeBrowser.onNavigationError = cb)
+  )
+
+/**
+ * Hook that returns the current navigation error and updates when it changes.
+ * @returns The current navigation error or undefined
+ */
+export function useNavigationError(): NavigationError | undefined {
+  return useNativeUpdatedValue(getNavigationError, onNavigationError, 'error')
+}
+
+// MARK: - Formatted Navigation Error
+
+/**
+ * Gets the current navigation error formatted for display.
+ * Native formats the error using the configured `formatNavigationError` callback,
+ * or falls back to default formatting.
+ *
+ * @returns Formatted error with title and message, or undefined if no error
+ */
+export function getFormattedNavigationError():
+  | FormattedNavigationError
+  | undefined {
+  return nativeBrowser.getFormattedNavigationError() ?? undefined
+}
+
+/**
+ * Subscribes to formatted navigation error changes.
+ * @param callback - Called when the formatted navigation error changes
+ * @returns Cleanup function to unsubscribe
+ */
+export const onFormattedNavigationError = NativeUpdatedValue.emitterize<
+  FormattedNavigationError | undefined
+>((cb) => (nativeBrowser.onFormattedNavigationError = cb))
+
+/**
+ * Hook that returns the current navigation error formatted for display.
+ *
+ * Native formats the error using the `formatNavigationError` callback configured
+ * 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.
+ *
+ * @returns Formatted error with title and message, or undefined if no error
+ *
+ * @example
+ * ```tsx
+ * // Basic usage
+ * const error = useFormattedNavigationError()
+ *
+ * if (error) {
+ *   return <ErrorView title={error.title} message={error.message} />
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Configure custom formatting - override only specific errors or routes
+ * configureBrowser({
+ *   formatNavigationError: ({ error, defaultFormatted, path }) => {
+ *     // Custom message for specific routes
+ *     if (error.code === 'network-error' && path.startsWith('/json-api')) {
+ *       return {
+ *         title: 'API Server Not Running',
+ *         message: 'Start the API server first'
+ *       }
+ *     }
+ *     if (error.code === 'http-error') {
+ *       return {
+ *         title: t('error.serverError'),
+ *         message: t('error.httpMessage', { status: error.statusCode })
+ *       }
+ *     }
+ *     // Use default for other error types
+ *     return defaultFormatted
+ *   }
+ * })
+ * ```
+ *
+ * @see {@link BrowserConfiguration.formatNavigationError} - Configure custom error formatting
+ * @see {@link useNavigationError} - Access the raw error with code and status details
+ */
+export function useFormattedNavigationError():
+  | FormattedNavigationError
+  | undefined {
+  return useNativeUpdatedValue(
+    getFormattedNavigationError,
+    onFormattedNavigationError
+  )
+}

package/src/features/favorites.ts

@@ -0,0 +1,102 @@
+import { nativeBrowser } from '../native'
+import type { Track } from '../types'
+import { NativeUpdatedValue } from '../utils/NativeUpdatedValue'
+
+// MARK: - Setters
+
+/**
+ * Sets the favorited state of the currently playing track.
+ * Updates the heart icon in media controllers (notification, Android Auto).
+ *
+ * Use this for programmatic favorite changes (e.g., from a favorite button in your app).
+ * For heart button taps from media controllers, use `onFavoriteChanged` instead -
+ * the native side handles those automatically.
+ *
+ * @param favorited - Whether the track is favorited
+ *
+ * @example
+ * ```ts
+ * setActiveTrackFavorited(true)
+ * ```
+ */
+export function setActiveTrackFavorited(favorited: boolean): void {
+  nativeBrowser.setActiveTrackFavorited(favorited)
+}
+
+/**
+ * Toggles the favorited state of the currently playing track.
+ *
+ * @example
+ * ```ts
+ * // In a button handler
+ * toggleActiveTrackFavorited()
+ * ```
+ */
+export function toggleActiveTrackFavorited(): void {
+  nativeBrowser.toggleActiveTrackFavorited()
+}
+
+/**
+ * Sets the list of favorited track source identifiers.
+ *
+ * This syncs your app's favorites with the native favorites cache, enabling
+ * the heart button in media controllers (notification, Android Auto, CarPlay)
+ * to show the correct state.
+ *
+ * Note: This is only needed if the tracks provided to AudioBrowser do not
+ * include the `favorited` field. If your API already includes favorite state in
+ * track responses, the native favorites cache is populated automatically during browsing.
+ *
+ * When the heart button is tapped in media controllers or when you call
+ * `setActiveTrackFavorited()`, the native favorites cache is automatically
+ * updated. You only need to call this on app launch to hydrate the cache.
+ *
+ * @param favorites - Array of favorited track `src` values
+ *
+ * @example
+ * ```ts
+ * const favoriteSrcs = await loadFavoritesFromStorage()
+ * setFavorites(favoriteSrcs)
+ * ```
+ */
+export function setFavorites(favorites: string[]): void {
+  nativeBrowser.setFavorites(favorites)
+}
+
+// MARK: - Event Callbacks
+
+/**
+ * Event data for when the favorite state of the active track changes.
+ * Emitted when the user taps the heart button in a media controller (notification, Android Auto, CarPlay).
+ */
+export interface FavoriteChangedEvent {
+  /** The track whose favorite state changed. */
+  track: Track
+  /** The new favorite state. */
+  favorited: boolean
+}
+
+/**
+ * Subscribes to favorite state change events.
+ * Called when the user taps the heart button in a media controller.
+ * 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 Cleanup function to unsubscribe
+ *
+ * @example
+ * ```ts
+ * const unsubscribe = onFavoriteChanged.addListener(({ track, favorited }) => {
+ *   // Persist the change to your backend/storage
+ *   if (favorited) {
+ *     addToFavorites(track)
+ *   } else {
+ *     removeFromFavorites(track)
+ *   }
+ * })
+ * ```
+ */
+export const onFavoriteChanged =
+  NativeUpdatedValue.emitterize<FavoriteChangedEvent>(
+    (cb) => (nativeBrowser.onFavoriteChanged = cb)
+  )

package/src/features/index.ts

@@ -0,0 +1,23 @@
+/**
+ * Feature-based exports - each feature includes:
+ * - Event types
+ * - Getters (get*)
+ * - Setters (set*)
+ * - Event callbacks (on*)
+ * - React hooks (use*)
+ */
+
+export * from './output'
+export * from './playback'
+export * from './player'
+export * from './queue'
+export * from './battery'
+export * from './browser'
+export * from './equalizer'
+export * from './errors'
+export * from './favorites'
+export * from './metadata'
+export * from './network'
+export * from './nowPlaying'
+export * from './remoteControls'
+export * from './sleepTimer'

package/src/features/metadata.ts

@@ -0,0 +1,130 @@
+import { nativeBrowser } from '../native'
+import { NativeUpdatedValue } from '../utils/NativeUpdatedValue'
+import type { Rating } from './rating'
+
+// 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
+  /** The track album */
+  album?: string
+  /** The track artist */
+  artist?: string
+  /** The track duration in seconds */
+  duration?: number
+  /** The track artwork */
+  artwork?: string
+  /** track description */
+  description?: string
+  /** track mediaId */
+  mediaId?: string
+  /** The track genre */
+  genre?: string
+  /** The track rating */
+  rating?: Rating
+}
+
+export interface NowPlayingMetadata extends TrackMetadataBase {
+  elapsedTime?: number
+}
+
+/**
+ * Metadata update for the now playing notification.
+ * Pass to `updateNowPlaying()` to override what's shown in the notification/lock screen.
+ * Pass `null` to clear overrides and revert to track metadata.
+ */
+export type NowPlayingUpdate = {
+  /** Title shown in notification */
+  title?: string
+  /** Artist shown in notification */
+  artist?: string
+}
+
+/**
+ * Timed metadata received during playback.
+ * Contains metadata from ICY streams (radio) or ID3 frames.
+ */
+export interface TimedMetadata {
+  title?: string
+  artist?: string
+  album?: string
+  date?: string
+  genre?: string
+}
+
+/**
+ * Static track metadata from the media file.
+ * Contains standardized metadata fields.
+ */
+export interface TrackMetadata {
+  title?: string
+  artist?: string
+  albumTitle?: string
+  subtitle?: string
+  description?: string
+  artworkUri?: string
+  trackNumber?: string
+  composer?: string
+  conductor?: string
+  genre?: string
+  compilation?: string
+  station?: string
+  mediaType?: string
+  creationDate?: string
+  creationYear?: string
+  url?: string
+}
+
+/**
+ * Chapter metadata with time range.
+ * Used for podcast chapters, audiobook chapters, etc.
+ */
+export interface ChapterMetadata {
+  /** Chapter start time in seconds */
+  startTime: number
+  /** Chapter end time in seconds */
+  endTime: number
+  /** Chapter title */
+  title?: string
+  /** URL associated with the chapter */
+  url?: string
+}
+
+// MARK: - Event Callbacks
+
+/**
+ * Subscribes to chapter metadata events.
+ * @param callback - Called when chapter metadata is received
+ * @returns Cleanup function to unsubscribe
+ */
+export const onChapterMetadata = NativeUpdatedValue.emitterize<
+  ChapterMetadata[]
+>((cb) => (nativeBrowser.onChapterMetadata = cb))
+
+/**
+ * Subscribes to track metadata events.
+ * @param callback - Called when static track metadata is received
+ * @returns Cleanup function to unsubscribe
+ */
+export const onTrackMetadata = NativeUpdatedValue.emitterize<TrackMetadata>(
+  (cb) => (nativeBrowser.onTrackMetadata = cb)
+)
+
+/**
+ * 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 Cleanup function to unsubscribe
+ */
+export const onTimedMetadata = NativeUpdatedValue.emitterize<TimedMetadata>(
+  (cb) => (nativeBrowser.onTimedMetadata = cb)
+)

package/src/features/network.ts

@@ -0,0 +1,34 @@
+import { nativeBrowser } from '../native'
+import { NativeUpdatedValue } from '../utils/NativeUpdatedValue'
+import { useNativeUpdatedValue } from '../utils/useNativeUpdatedValue'
+
+// MARK: - Getters
+
+/**
+ * Gets the current network connectivity state.
+ * @returns true if the device is online, false otherwise
+ */
+export function getOnline(): boolean {
+  return nativeBrowser.getOnline()
+}
+
+// MARK: - Event Callbacks
+
+/**
+ * Subscribes to network connectivity changes.
+ * @param callback - Called when network state changes
+ * @returns Cleanup function to unsubscribe
+ */
+export const onOnlineChanged = NativeUpdatedValue.emitterize<boolean>(
+  (cb) => (nativeBrowser.onOnlineChanged = cb)
+)
+
+// MARK: - Hooks
+
+/**
+ * Hook that returns the current network connectivity state and updates when it changes.
+ * @returns true if the device is online, false otherwise
+ */
+export function useOnline(): boolean {
+  return useNativeUpdatedValue(getOnline, onOnlineChanged)
+}

package/src/features/nowPlaying.ts

@@ -0,0 +1,56 @@
+import { nativeBrowser } from '../native'
+import { NativeUpdatedValue } from '../utils/NativeUpdatedValue'
+import { useNativeUpdatedValue } from '../utils/useNativeUpdatedValue'
+import type { NowPlayingMetadata, NowPlayingUpdate } from './metadata'
+
+// MARK: - Functions
+
+/**
+ * Updates the now playing notification metadata.
+ * Pass null/undefined to clear overrides and revert to track metadata.
+ *
+ * @example
+ * ```ts
+ * // Override notification with stream metadata
+ * updateNowPlaying({
+ *   title: streamMetadata.title,
+ *   artist: streamMetadata.artist,
+ * })
+ *
+ * // Clear overrides, revert to track metadata
+ * updateNowPlaying(null)
+ * ```
+ */
+export function updateNowPlaying(update: NowPlayingUpdate | null): void {
+  nativeBrowser.updateNowPlaying(update ?? undefined)
+}
+
+/**
+ * Gets the current now playing metadata (override if set, else track metadata).
+ */
+export function getNowPlaying(): NowPlayingMetadata | undefined {
+  return nativeBrowser.getNowPlaying() ?? undefined
+}
+
+// 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 Cleanup function to unsubscribe
+ */
+export const onNowPlayingChanged =
+  NativeUpdatedValue.emitterize<NowPlayingMetadata>(
+    (cb) => (nativeBrowser.onNowPlayingChanged = cb)
+  )
+
+// MARK: - Hooks
+
+/**
+ * Hook that returns the current now playing metadata and updates when it changes.
+ * @returns The current now playing metadata or undefined
+ */
+export function useNowPlaying(): NowPlayingMetadata | undefined {
+  return useNativeUpdatedValue(getNowPlaying, onNowPlayingChanged)
+}

package/src/features/output.ts

@@ -0,0 +1,50 @@
+import { nativeBrowser } from '../native'
+import type { IosOutput, IosOutputType } from '../specs/audio-browser.nitro'
+import { NativeUpdatedValue } from '../utils/NativeUpdatedValue'
+import { useNativeUpdatedValue } from '../utils/useNativeUpdatedValue'
+
+export type { IosOutput, IosOutputType }
+
+// MARK: - Actions
+
+/**
+ * Opens the system output picker (iOS only).
+ * Allows users to select output device (speaker, AirPlay, Bluetooth, etc.).
+ * No-op on Android.
+ */
+export function openIosOutputPicker(): void {
+  nativeBrowser.openIosOutputPicker()
+}
+
+// MARK: - Getters
+
+/**
+ * Gets the current audio output info.
+ * Always returns a value on iOS, undefined on Android.
+ */
+export function getIosOutput(): IosOutput | undefined {
+  return nativeBrowser.getIosOutput()
+}
+
+// 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
+ */
+export const onIosOutputChanged = NativeUpdatedValue.emitterize<IosOutput>(
+  (cb) => (nativeBrowser.onIosOutputChanged = 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.
+ */
+export function useIosOutput(): IosOutput | undefined {
+  return useNativeUpdatedValue(getIosOutput, onIosOutputChanged)
+}

package/src/features/playback/controls.ts

@@ -0,0 +1,66 @@
+// MARK: - Playback Controls
+
+import { nativeBrowser } from '../../native'
+
+/**
+ * Resets the player stopping the current track and clearing the queue.
+ */
+export function reset(): void {
+  nativeBrowser.reset()
+}
+
+/**
+ * Plays or resumes the current track.
+ */
+export function play(): void {
+  nativeBrowser.play()
+}
+
+/**
+ * Pauses the current track.
+ */
+export function pause(): void {
+  nativeBrowser.pause()
+}
+
+/**
+ * Toggles playback between play and pause.
+ */
+export function togglePlayback(): void {
+  nativeBrowser.togglePlayback()
+}
+
+/**
+ * Stops playback and resets position to the beginning.
+ * The track remains loaded and can be resumed with play().
+ * For live streams, position is not reset.
+ */
+export function stop(): void {
+  nativeBrowser.stop()
+}
+
+/**
+ * Retries playing the current item when the playback state is `'error'`.
+ *
+ * @see {@link PlaybackState}
+ * @see {@link usePlayback}
+ */
+export function retry(): void {
+  nativeBrowser.retry()
+}
+
+/**
+ * Seeks to a specified time position in the current track.
+ * @param position - The position to seek to in seconds.
+ */
+export function seekTo(position: number): void {
+  nativeBrowser.seekTo(position)
+}
+
+/**
+ * Seeks by a relative time offset in the current track.
+ * @param offset - The time offset to seek by in seconds.
+ */
+export function seekBy(offset: number): void {
+  nativeBrowser.seekBy(offset)
+}

package/src/features/playback/index.ts

@@ -0,0 +1,7 @@
+export * from './controls'
+export * from './state'
+export * from './playing'
+export * from './playWhenReady'
+export * from './progress'
+export * from './rate'
+export * from './volume'