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

package/src/features/playback/playWhenReady.ts

@@ -0,0 +1,57 @@
+import { nativeBrowser } from '../../native'
+import { NativeUpdatedValue } from '../../utils/NativeUpdatedValue'
+import { useNativeUpdatedValue } from '../../utils/useNativeUpdatedValue'
+
+/**
+ * Event data for when playWhenReady changes.
+ */
+export interface PlaybackPlayWhenReadyChangedEvent {
+  /** Whether the player will play when ready */
+  playWhenReady: boolean
+}
+
+// MARK: - Getters
+
+/**
+ * Gets whether the player will play automatically when it is ready to do so.
+ */
+export function getPlayWhenReady(): boolean {
+  return nativeBrowser.getPlayWhenReady()
+}
+
+// MARK: - Setters
+
+/**
+ * Sets whether the player will play automatically when it is ready to do so.
+ * This is the equivalent of calling `play()` when `playWhenReady = true`
+ * or `pause()` when `playWhenReady = false`.
+ */
+export function setPlayWhenReady(playWhenReady: boolean): void {
+  nativeBrowser.setPlayWhenReady(playWhenReady)
+}
+
+// MARK: - Event Callbacks
+
+/**
+ * Subscribes to play when ready changes.
+ * @param callback - Called when playWhenReady changes
+ * @returns Cleanup function to unsubscribe
+ */
+export const onPlayWhenReadyChanged =
+  NativeUpdatedValue.emitterize<PlaybackPlayWhenReadyChangedEvent>(
+    (cb) => (nativeBrowser.onPlaybackPlayWhenReadyChanged = cb)
+  )
+
+// MARK: - Hooks
+
+/**
+ * Hook that returns the current playWhenReady state and updates when it changes.
+ * @returns The current playWhenReady state
+ */
+export function usePlayWhenReady(): boolean {
+  return useNativeUpdatedValue(
+    getPlayWhenReady,
+    onPlayWhenReadyChanged,
+    'playWhenReady'
+  )
+}

package/src/features/playback/playing.ts

@@ -0,0 +1,40 @@
+import { nativeBrowser } from '../../native'
+import { NativeUpdatedValue } from '../../utils/NativeUpdatedValue'
+import { useNativeUpdatedValue } from '../../utils/useNativeUpdatedValue'
+
+// MARK: - Types
+
+export type PlayingState = {
+  playing: boolean
+  buffering: boolean
+}
+
+// MARK: - Getters
+
+/**
+ * Gets the playing state (playing and buffering flags).
+ */
+export function getPlayingState(): PlayingState {
+  return nativeBrowser.getPlayingState()
+}
+
+// MARK: - Event Callbacks
+
+/**
+ * Subscribes to playing state changes.
+ * @param callback - Called when playing or buffering state changes
+ * @returns Cleanup function to unsubscribe
+ */
+export const onPlayingState = NativeUpdatedValue.emitterize<PlayingState>(
+  (cb) => (nativeBrowser.onPlaybackPlayingState = cb)
+)
+
+// MARK: - Hooks
+
+/**
+ * Hook that returns the current playing state and updates when it changes.
+ * @returns The current playing state (playing and buffering flags)
+ */
+export function usePlayingState(): PlayingState {
+  return useNativeUpdatedValue(getPlayingState, onPlayingState)
+}

package/src/features/playback/progress.ts

@@ -0,0 +1,122 @@
+import { useEffect, useState } from 'react'
+import { nativeBrowser } from '../../native'
+import { NativeUpdatedValue } from '../../utils/NativeUpdatedValue'
+import { useNativeUpdatedValue } from '../../utils/useNativeUpdatedValue'
+import { onPlaybackChanged } from './state'
+
+// MARK: - Types
+
+export interface Progress {
+  /**
+   * The playback position of the current track in seconds.
+   **/
+  position: number
+  /**
+   * The duration of the current track in seconds.
+   **/
+  duration: number
+  /**
+   * The buffered position of the current track in seconds.
+   **/
+  buffered: number
+}
+
+/**
+ * Event data for playback progress updates.
+ */
+export interface PlaybackProgressUpdatedEvent extends Progress {
+  /** The current track index */
+  track: number
+}
+
+// MARK: - Getters
+
+/**
+ * Gets information on the progress of the currently active track, including its
+ * current playback position in seconds, buffered position in seconds and
+ * duration in seconds.
+ */
+export function getProgress(): Progress {
+  return nativeBrowser.getProgress()
+}
+
+// MARK: - Event Callbacks
+
+/**
+ * Subscribes to playback progress updates.
+ * @param callback - Called periodically with playback progress updates
+ * @returns Cleanup function to unsubscribe
+ */
+export const onProgressUpdated =
+  NativeUpdatedValue.emitterize<PlaybackProgressUpdatedEvent>(
+    (cb) => (nativeBrowser.onPlaybackProgressUpdated = cb)
+  )
+
+// MARK: - Hooks
+
+/**
+ * Hook that returns the current playback progress and updates when it changes.
+ *
+ * Progress update frequency is controlled globally via `updateOptions({ progressUpdateEventInterval })`.
+ * @returns The current playback progress
+ */
+export function useProgress(): Progress {
+  return useNativeUpdatedValue(getProgress, onProgressUpdated)
+}
+
+/**
+ * Hook that returns the current playback progress and updates via polling.
+ *
+ * Use this when you need custom polling behavior instead of event-based updates.
+ *
+ * @param updateInterval - Update interval in milliseconds (default: 1000)
+ * @returns The current playback progress
+ */
+export function usePolledProgress(updateInterval = 1000): Progress {
+  const [state, setState] = useState<Progress>({
+    position: 0,
+    duration: 0,
+    buffered: 0
+  })
+
+  useEffect(() => {
+    let mounted = true
+
+    const update = () => {
+      try {
+        const { position, duration, buffered } = getProgress()
+        if (!mounted) return
+
+        setState((currentState) =>
+          position === currentState.position &&
+          duration === currentState.duration &&
+          buffered === currentState.buffered
+            ? currentState
+            : { position, duration, buffered }
+        )
+      } catch {
+        // Ignore failures (e.g., before setup)
+      }
+    }
+
+    // Update immediately on playback state changes
+    const unsubscribeState = onPlaybackChanged.addListener(update)
+
+    const poll = () => {
+      update()
+      if (!mounted) return
+      setTimeout(() => {
+        if (mounted) poll()
+      }, updateInterval)
+    }
+
+    poll()
+
+    return () => {
+      mounted = false
+      unsubscribeState()
+    }
+  }, [updateInterval])
+
+  return state
+}

package/src/features/playback/rate.ts

@@ -0,0 +1,22 @@
+// MARK: - Getters
+
+import { nativeBrowser } from '../../native'
+
+/**
+ * Gets the playback rate where 0.5 would be half speed, 1 would be
+ * regular speed and 2 would be double speed etc.
+ */
+export function getRate(): number {
+  return nativeBrowser.getRate()
+}
+
+// MARK: - Setters
+
+/**
+ * Sets the playback rate.
+ * @param rate - The playback rate to change to, where 0.5 would be half speed,
+ * 1 would be regular speed, 2 would be double speed etc.
+ */
+export function setRate(rate: number): void {
+  nativeBrowser.setRate(rate)
+}

package/src/features/playback/state.ts

@@ -0,0 +1,72 @@
+import { nativeBrowser } from '../../native'
+import { NativeUpdatedValue } from '../../utils/NativeUpdatedValue'
+import { useNativeUpdatedValue } from '../../utils/useNativeUpdatedValue'
+import type { PlaybackError } from '../errors'
+
+// MARK: - Types
+
+/**
+ * PlaybackState options:
+ * - `'none'`: Indicates that the player is idle (initial state, or no track
+ *   loaded)
+ * - `'ready'`: Indicates that the player has loaded a track and is ready to
+ *   play (but paused)
+ * - `'playing'`: Indicates that the player is currently playing
+ * - `'paused'`: Indicates that the player is currently paused
+ * - `'stopped'`: Indicates that the player is currently stopped
+ * - `'loading'`: Indicates that the initial load of the item is occurring.
+ * - `'buffering'`: Indicates that the player is currently loading more data
+ *   before it can continue playing or is ready to start playing.
+ * - `'error'`: Indicates that playback of the current item failed. Call
+ *   `AudioBrowser.getError()` to get more information on the type of error that
+ *   occurred. Call `AudioBrowser.retry()` or `AudioBrowser.play()` to try to play
+ *   the item again.
+ * - `'ended'`: Indicates that playback stopped due to the end of the queue
+ *   being reached.
+ */
+export type PlaybackState =
+  | 'none'
+  | 'ready'
+  | 'playing'
+  | 'paused'
+  | 'stopped'
+  | 'loading'
+  | 'buffering'
+  | 'error'
+  | 'ended'
+
+export type Playback = {
+  state: PlaybackState
+  error?: PlaybackError
+}
+
+// MARK: - Getters
+
+/**
+ * Gets the playback state and error (if any) of the player.
+ * @see {@link PlaybackState} for possible state values
+ */
+export function getPlayback(): Playback {
+  return nativeBrowser.getPlayback()
+}
+
+// MARK: - Event Callbacks
+
+/**
+ * Subscribes to playback state changes.
+ * @param callback - Called when the playback state changes
+ * @returns Cleanup function to unsubscribe
+ */
+export const onPlaybackChanged = NativeUpdatedValue.emitterize<Playback>(
+  (cb) => (nativeBrowser.onPlaybackChanged = cb)
+)
+
+// MARK: - Hooks
+
+/**
+ * Hook that returns the current playback state and updates when it changes.
+ * @returns The current playback state
+ */
+export function usePlayback(): Playback {
+  return useNativeUpdatedValue(getPlayback, onPlaybackChanged)
+}

package/src/features/playback/volume.ts

@@ -0,0 +1,59 @@
+// MARK: - Getters
+
+import { nativeBrowser } from '../../native'
+import { NativeUpdatedValue } from '../../utils/NativeUpdatedValue'
+import { useNativeUpdatedValue } from '../../utils/useNativeUpdatedValue'
+
+/**
+ * Gets the volume of the player as a number between 0 and 1.
+ */
+export function getVolume(): number {
+  return nativeBrowser.getVolume()
+}
+
+/**
+ * Gets the current system volume as a number between 0 and 1.
+ */
+export function getSystemVolume(): number {
+  return nativeBrowser.getSystemVolume()
+}
+
+// MARK: - Setters
+
+/**
+ * Sets the volume of the player.
+ * @param level - The volume as a number between 0 and 1.
+ */
+export function setVolume(level: number): void {
+  nativeBrowser.setVolume(level)
+}
+
+/**
+ * Sets the system volume.
+ * @param level - The volume as a number between 0 and 1.
+ * @note On iOS this is a no-op as Apple doesn't provide a public API to set system volume.
+ */
+export function setSystemVolume(level: number): void {
+  nativeBrowser.setSystemVolume(level)
+}
+
+// MARK: - Event Callbacks
+
+/**
+ * Subscribes to system volume changes.
+ * @param callback - Called when the system volume changes
+ * @returns Cleanup function to unsubscribe
+ */
+export const onSystemVolumeChanged = NativeUpdatedValue.emitterize<number>(
+  (cb) => (nativeBrowser.onSystemVolumeChanged = cb)
+)
+
+// MARK: - Hooks
+
+/**
+ * Hook that returns the current system volume and updates when it changes.
+ * @returns The current system volume (0 to 1)
+ */
+export function useSystemVolume(): number {
+  return useNativeUpdatedValue(getSystemVolume, onSystemVolumeChanged)
+}

package/src/features/player/index.ts

@@ -0,0 +1,2 @@
+export * from './setup'
+export * from './options'