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

package/src/features/queue/queue.ts

@@ -0,0 +1,173 @@
+import { nativeBrowser } from '../../native'
+import type { Track } from '../../types'
+import { NativeUpdatedValue } from '../../utils/NativeUpdatedValue'
+import { useNativeUpdatedValue } from '../../utils/useNativeUpdatedValue'
+
+// MARK: - Types
+
+/**
+ * Event data for when the playback queue has ended.
+ */
+export interface PlaybackQueueEndedEvent {
+  /** The index of the active track when the playback queue ended. */
+  track: number
+  /** The playback position in seconds of the active track when the playback queue ended. */
+  position: number
+}
+
+// MARK: - Queue Management
+
+/**
+ * Adds one or more tracks to the queue.
+ * @param tracks - The tracks to add to the queue.
+ * @param insertBeforeIndex - (Optional) The index to insert the tracks before.
+ * By default the tracks will be added to the end of the queue.
+ */
+export function add(tracks: Track[], insertBeforeIndex?: number): void
+/**
+ * Adds a track to the queue.
+ * @param track - The track to add to the queue.
+ * @param insertBeforeIndex - (Optional) The index to insert the track before.
+ * By default the track will be added to the end of the queue.
+ */
+export function add(track: Track, insertBeforeIndex?: number): void
+export function add(tracks: Track | Track[], insertBeforeIndex = -1): void {
+  const addTracks = Array.isArray(tracks) ? tracks : [tracks]
+  if (addTracks.length > 0) {
+    nativeBrowser.add(addTracks, insertBeforeIndex)
+  }
+}
+
+/**
+ * Replaces the current track or loads the track as the first in the queue.
+ * @param track - The track to load.
+ */
+export function load(track: Track): void {
+  nativeBrowser.load(track)
+}
+
+/**
+ * Move a track within the queue.
+ * @param fromIndex - The index of the track to be moved.
+ * @param toIndex - The index to move the track to. If the index is larger than
+ * the size of the queue, then the track is moved to the end of the queue.
+ */
+export function move(fromIndex: number, toIndex: number): void {
+  nativeBrowser.move(fromIndex, toIndex)
+}
+
+/**
+ * Removes multiple tracks from the queue by their indexes.
+ *
+ * If the current track is removed, the next track will activated. If the
+ * current track was the last track in the queue, the first track will be
+ * activated.
+ *
+ * @param indexes - The indexes of the tracks to be removed.
+ */
+export function remove(indexes: number[]): void
+/**
+ * Removes a track from the queue by its index.
+ *
+ * If the current track is removed, the next track will activated. If the
+ * current track was the last track in the queue, the first track will be
+ * activated.
+ *
+ * @param index - The index of the track to be removed.
+ */
+export function remove(index: number): void
+export function remove(indexOrIndexes: number | number[]): void {
+  nativeBrowser.remove(
+    Array.isArray(indexOrIndexes) ? indexOrIndexes : [indexOrIndexes]
+  )
+}
+
+/**
+ * Clears any upcoming tracks from the queue.
+ */
+export function removeUpcomingTracks(): void {
+  nativeBrowser.removeUpcomingTracks()
+}
+
+/**
+ * Skips to a track in the queue.
+ * @param index - The index of the track to skip to.
+ * @param initialPosition - (Optional) The initial position to seek to in seconds.
+ */
+export function skip(index: number, initialPosition?: number): void {
+  nativeBrowser.skip(index, initialPosition)
+}
+
+/**
+ * Skips to the next track in the queue.
+ * @param initialPosition - (Optional) The initial position to seek to in seconds.
+ */
+export function skipToNext(initialPosition?: number): void {
+  nativeBrowser.skipToNext(initialPosition)
+}
+
+/**
+ * Skips to the previous track in the queue.
+ * @param initialPosition - (Optional) The initial position to seek to in seconds.
+ */
+export function skipToPrevious(initialPosition?: number): void {
+  nativeBrowser.skipToPrevious(initialPosition)
+}
+
+/**
+ * Sets the queue.
+ * @param tracks - The tracks to set as the queue.
+ */
+export function setQueue(tracks: Track[]): void {
+  nativeBrowser.setQueue(tracks)
+}
+
+// MARK: - Getters
+
+/**
+ * Gets a track object from the queue.
+ * @param index - The index of the track.
+ * @returns The track object or undefined if there isn't a track object at that index.
+ */
+export function getTrack(index: number): Track | undefined {
+  return nativeBrowser.getTrack(index) as unknown as Track
+}
+
+/**
+ * Gets the whole queue.
+ */
+export function getQueue(): Track[] {
+  return nativeBrowser.getQueue() as unknown as Track[]
+}
+
+// MARK: - Event Callbacks
+
+/**
+ * Subscribes to playback queue ended events.
+ * @param callback - Called when playback has paused due to reaching the end of the queue
+ * @returns Cleanup function to unsubscribe
+ */
+export const onQueueEnded =
+  NativeUpdatedValue.emitterize<PlaybackQueueEndedEvent>(
+    (cb) => (nativeBrowser.onPlaybackQueueEnded = cb)
+  )
+
+/**
+ * Subscribes to queue change events.
+ * Called when tracks are added, removed, reordered, or when track metadata changes.
+ * @param callback - Called with the updated queue
+ * @returns Cleanup function to unsubscribe
+ */
+export const onQueueChanged = NativeUpdatedValue.emitterize<Track[]>(
+  (cb) => (nativeBrowser.onPlaybackQueueChanged = cb)
+)
+
+// MARK: - Hooks
+
+/**
+ * Hook that returns the current queue and updates when it changes.
+ * @returns The current queue
+ */
+export function useQueue(): Track[] {
+  return useNativeUpdatedValue(getQueue, onQueueChanged)
+}

package/src/features/queue/repeatMode.ts

@@ -0,0 +1,58 @@
+import { nativeBrowser } from '../../native'
+import { NativeUpdatedValue } from '../../utils/NativeUpdatedValue'
+import { useNativeUpdatedValue } from '../../utils/useNativeUpdatedValue'
+
+// MARK: - Types
+
+/**
+ * RepeatMode options:
+ * - `'off'`: Playback stops when the last track in the queue has finished
+ *   playing.
+ * - `'track'`: Repeats the current track infinitely during ongoing playback.
+ * - `'queue'`: Repeats the entire queue infinitely.
+ */
+export type RepeatMode = 'off' | 'track' | 'queue'
+
+// MARK: - Getters
+
+/**
+ * Gets the current repeat mode.
+ */
+export function getRepeatMode(): RepeatMode {
+  return nativeBrowser.getRepeatMode()
+}
+
+/**
+ * Sets the repeat mode.
+ * @param repeatMode - The repeat mode to set
+ */
+export function setRepeatMode(repeatMode: RepeatMode) {
+  nativeBrowser.setRepeatMode(repeatMode)
+}
+
+// MARK: - Event Callbacks
+
+export interface RepeatModeChangedEvent {
+  /** The new repeat mode */
+  repeatMode: RepeatMode
+}
+
+/**
+ * Subscribes to repeat mode changes.
+ * @param callback - Called when repeat mode changes
+ * @returns Cleanup function to unsubscribe
+ */
+export const onRepeatModeChanged =
+  NativeUpdatedValue.emitterize<RepeatModeChangedEvent>(
+    (cb) => (nativeBrowser.onPlaybackRepeatModeChanged = cb)
+  )
+
+// MARK: - Hooks
+
+/**
+ * Hook that returns the current repeat mode and updates when it changes.
+ * @returns The current repeat mode
+ */
+export function useRepeatMode(): RepeatMode {
+  return useNativeUpdatedValue(getRepeatMode, onRepeatModeChanged, 'repeatMode')
+}

package/src/features/queue/shuffle.ts

@@ -0,0 +1,49 @@
+import { nativeBrowser } from '../../native'
+import { NativeUpdatedValue } from '../../utils/NativeUpdatedValue'
+import { useNativeUpdatedValue } from '../../utils/useNativeUpdatedValue'
+
+// MARK: - Getters
+
+/**
+ * Gets whether shuffle mode is enabled.
+ */
+export function getShuffle(): boolean {
+  return nativeBrowser.getShuffleEnabled()
+}
+
+/**
+ * Sets whether shuffle mode is enabled.
+ * When enabled, tracks play in a randomized order.
+ * @param enabled - Whether to enable shuffle mode
+ */
+export function setShuffle(enabled: boolean): void {
+  nativeBrowser.setShuffleEnabled(enabled)
+}
+
+/**
+ * Toggles shuffle mode on/off.
+ */
+export function toggleShuffle(): void {
+  setShuffle(!getShuffle())
+}
+
+// MARK: - Event Callbacks
+
+/**
+ * Subscribes to shuffle mode changes.
+ * @param callback - Called when shuffle mode changes
+ * @returns Cleanup function to unsubscribe
+ */
+export const onShuffleChanged = NativeUpdatedValue.emitterize<boolean>(
+  (cb) => (nativeBrowser.onPlaybackShuffleModeChanged = cb)
+)
+
+// MARK: - Hooks
+
+/**
+ * Hook that returns whether shuffle mode is enabled and updates when it changes.
+ * @returns Whether shuffle mode is enabled
+ */
+export function useShuffle(): boolean {
+  return useNativeUpdatedValue(getShuffle, onShuffleChanged)
+}

package/src/features/rating.ts

@@ -0,0 +1,17 @@
+export interface HeartRating {
+  hasHeart: boolean
+}
+
+export interface ThumbsRating {
+  isThumbsUp: boolean
+}
+
+export interface StarRating {
+  stars: number
+}
+
+export interface PercentageRating {
+  percentage: number
+}
+
+export type Rating = HeartRating | ThumbsRating | StarRating | PercentageRating

package/src/features/remoteControls.ts

@@ -0,0 +1,341 @@
+import { nativeBrowser } from '../native'
+import { LazyNativeEmitter } from '../utils/LazyNativeEmitter'
+import type {
+  HeartRating,
+  PercentageRating,
+  StarRating,
+  ThumbsRating
+} from './rating'
+
+// MARK: - Event Interfaces
+
+/**
+ * Remote jump backward event.
+ */
+export interface RemoteJumpBackwardEvent {
+  /** Jump interval in seconds */
+  interval: number
+}
+
+/**
+ * Remote jump forward event.
+ */
+export interface RemoteJumpForwardEvent {
+  /** Jump interval in seconds */
+  interval: number
+}
+
+/**
+ * Remote play ID event (Android only).
+ */
+export interface RemotePlayIdEvent {
+  /** The ID of the track to play */
+  id: string
+  /** Optional index in the queue */
+  index?: number
+}
+
+/**
+ * Remote play search event (Android only).
+ */
+export interface RemotePlaySearchEvent {
+  /** The search query */
+  query: string
+}
+
+/**
+ * Remote seek event.
+ */
+export interface RemoteSeekEvent {
+  /** The position to seek to in seconds */
+  position: number
+}
+
+/**
+ * Remote set rating event.
+ */
+export interface RemoteSetRatingEvent {
+  rating: HeartRating | ThumbsRating | StarRating | PercentageRating
+}
+
+/**
+ * Remote skip event (Android only).
+ */
+export interface RemoteSkipEvent {
+  /** The index to skip to */
+  index: number
+}
+
+// MARK: - Default Handlers
+
+// Install remote control handlers with default behavior immediately when module loads
+// Custom handlers can override the defaults using handleRemote* functions
+
+// Basic playback controls
+// AudioBrowser.onRemotePlay(() => {
+//   const customHandler = customHandlers.get('play')
+//   if (customHandler) {
+//     customHandler()
+//   } else {
+//     play()
+//   }
+// })
+
+// AudioBrowser.onRemotePause(() => {
+//   const customHandler = customHandlers.get('pause')
+//   if (customHandler) {
+//     customHandler()
+//   } else {
+//     pause()
+//   }
+// })
+
+// AudioBrowser.onRemoteNext(() => {
+//   const customHandler = customHandlers.get('next')
+//   if (customHandler) {
+//     customHandler()
+//   } else {
+//     skipToNext()
+//   }
+// })
+
+// AudioBrowser.onRemotePrevious(() => {
+//   const customHandler = customHandlers.get('previous')
+//   if (customHandler) {
+//     customHandler()
+//   } else {
+//     skipToPrevious()
+//   }
+// })
+
+// AudioBrowser.onRemoteStop(() => {
+//   const customHandler = customHandlers.get('stop')
+//   if (customHandler) {
+//     customHandler()
+//   } else {
+//     stop()
+//   }
+// })
+
+// // Seek controls
+// AudioBrowser.onRemoteSeek((event: any) => {
+//   const customHandler = customHandlers.get('seek')
+//   if (customHandler) {
+//     customHandler(event)
+//   } else {
+//     seekTo(event.position)
+//   }
+// })
+
+// AudioBrowser.onRemoteJumpForward((event: any) => {
+//   const customHandler = customHandlers.get('jumpForward')
+//   if (customHandler) {
+//     customHandler(event)
+//   } else {
+//     seekBy(event.interval)
+//   }
+// })
+
+// AudioBrowser.onRemoteJumpBackward((event: any) => {
+//   const customHandler = customHandlers.get('jumpBackward')
+//   if (customHandler) {
+//     customHandler(event)
+//   } else {
+//     seekBy(-event.interval)
+//   }
+// })
+
+// MARK: - Handler Override Functions
+//
+// Use these functions when you want to OVERRIDE the default remote control behavior.
+// These will replace the default handlers with your custom logic.
+// If you just want to listen to events for debugging/logging, use the onRemote* functions below.
+
+/**
+ * Sets a custom handler for remote play events, overriding the default behavior.
+ * @param callback - Called when the user presses the play button. Pass undefined to disable.
+ */
+export function handleRemotePlay(callback: (() => void) | undefined) {
+  nativeBrowser.handleRemotePlay = callback
+}
+
+/**
+ * Sets a custom handler for remote pause events, overriding the default behavior.
+ * @param callback - Called when the user presses the pause button. Pass undefined to disable.
+ */
+export function handleRemotePause(callback: (() => void) | undefined) {
+  nativeBrowser.handleRemotePause = callback
+}
+
+/**
+ * Sets a custom handler for remote next events, overriding the default behavior.
+ * @param callback - Called when the user presses the next track button. Pass undefined to disable.
+ */
+export function handleRemoteNext(callback: (() => void) | undefined) {
+  nativeBrowser.handleRemoteNext = callback
+}
+
+/**
+ * Sets a custom handler for remote previous events, overriding the default behavior.
+ * @param callback - Called when the user presses the previous track button. Pass undefined to disable.
+ */
+export function handleRemotePrevious(callback: (() => void) | undefined) {
+  nativeBrowser.handleRemotePrevious = callback
+}
+
+/**
+ * Sets a custom handler for remote stop events, overriding the default behavior.
+ * @param callback - Called when the user presses the stop button. Pass undefined to disable.
+ */
+export function handleRemoteStop(callback: (() => void) | undefined) {
+  nativeBrowser.handleRemoteStop = callback
+}
+
+/**
+ * Sets a custom handler for remote seek events, overriding the default behavior.
+ * @param callback - Called when the user changes the position of the timeline. Pass undefined to disable.
+ */
+export function handleRemoteSeek(
+  callback: ((event: RemoteSeekEvent) => void) | undefined
+) {
+  nativeBrowser.handleRemoteSeek = callback
+}
+
+/**
+ * Sets a custom handler for remote jump forward events, overriding the default behavior.
+ * @param callback - Called when the user presses the jump forward button. Pass undefined to disable.
+ */
+export function handleRemoteJumpForward(
+  callback: ((event: RemoteJumpForwardEvent) => void) | undefined
+) {
+  nativeBrowser.handleRemoteJumpForward = callback
+}
+
+/**
+ * Sets a custom handler for remote jump backward events, overriding the default behavior.
+ * @param callback - Called when the user presses the jump backward button. Pass undefined to disable.
+ */
+export function handleRemoteJumpBackward(
+  callback: ((event: RemoteJumpBackwardEvent) => void) | undefined
+) {
+  nativeBrowser.handleRemoteJumpBackward = callback
+}
+
+// MARK: - Event Callbacks (for listening/debugging only)
+//
+// Use these functions when you want to LISTEN to remote control events without overriding
+// the default behavior. These are perfect for logging, analytics, or debugging.
+// Multiple listeners can be registered for the same event.
+// To override the default behavior, use the handleRemote* functions above.
+
+/**
+ * Subscribes to remote jump backward events.
+ * @param callback - Called when the user presses the jump backward button
+ * @returns Cleanup function to unsubscribe
+ */
+export const onRemoteJumpBackward =
+  LazyNativeEmitter.emitterize<RemoteJumpBackwardEvent>(
+    (cb) => (nativeBrowser.onRemoteJumpBackward = cb)
+  )
+
+/**
+ * Subscribes to remote jump forward events.
+ * @param callback - Called when the user presses the jump forward button
+ * @returns Cleanup function to unsubscribe
+ */
+export const onRemoteJumpForward =
+  LazyNativeEmitter.emitterize<RemoteJumpForwardEvent>(
+    (cb) => (nativeBrowser.onRemoteJumpForward = cb)
+  )
+
+/**
+ * Subscribes to remote next events.
+ * @param callback - Called when the user presses the next track button
+ * @returns Cleanup function to unsubscribe
+ */
+export const onRemoteNext = LazyNativeEmitter.emitterize<void>(
+  (cb) => (nativeBrowser.onRemoteNext = cb)
+)
+
+/**
+ * Subscribes to remote pause events.
+ * @param callback - Called when the user presses the pause button
+ * @returns Cleanup function to unsubscribe
+ */
+export const onRemotePause = LazyNativeEmitter.emitterize<void>(
+  (cb) => (nativeBrowser.onRemotePause = cb)
+)
+
+/**
+ * Subscribes to remote play events.
+ * @param callback - Called when the user presses the play button
+ * @returns Cleanup function to unsubscribe
+ */
+export const onRemotePlay = LazyNativeEmitter.emitterize<void>(
+  (cb) => (nativeBrowser.onRemotePlay = cb)
+)
+
+/**
+ * Subscribes to remote play ID events (Android only).
+ * @param callback - Called when the user selects a track from an external device
+ * @returns Cleanup function to unsubscribe
+ */
+export const onRemotePlayId = LazyNativeEmitter.emitterize<RemotePlayIdEvent>(
+  (cb) => (nativeBrowser.onRemotePlayId = cb)
+)
+
+/**
+ * Subscribes to remote play search events (Android only).
+ * @param callback - Called when the user searches for a track (usually voice search)
+ * @returns Cleanup function to unsubscribe
+ */
+export const onRemotePlaySearch =
+  LazyNativeEmitter.emitterize<RemotePlaySearchEvent>(
+    (cb) => (nativeBrowser.onRemotePlaySearch = cb)
+  )
+
+/**
+ * Subscribes to remote previous events.
+ * @param callback - Called when the user presses the previous track button
+ * @returns Cleanup function to unsubscribe
+ */
+export const onRemotePrevious = LazyNativeEmitter.emitterize<void>(
+  (cb) => (nativeBrowser.onRemotePrevious = cb)
+)
+
+/**
+ * Subscribes to remote seek events.
+ * @param callback - Called when the user changes the position of the timeline
+ * @returns Cleanup function to unsubscribe
+ */
+export const onRemoteSeek = LazyNativeEmitter.emitterize<RemoteSeekEvent>(
+  (cb) => (nativeBrowser.onRemoteSeek = cb)
+)
+
+/**
+ * Subscribes to remote set rating events.
+ * @param callback - Called when the user changes the rating for the track remotely
+ * @returns Cleanup function to unsubscribe
+ */
+export const onRemoteSetRating =
+  LazyNativeEmitter.emitterize<RemoteSetRatingEvent>(
+    (cb) => (nativeBrowser.onRemoteSetRating = cb)
+  )
+
+/**
+ * Subscribes to remote skip events (Android only).
+ * @param callback - Called when the user presses the skip button
+ * @returns Cleanup function to unsubscribe
+ */
+export const onRemoteSkip = LazyNativeEmitter.emitterize<RemoteSkipEvent>(
+  (cb) => (nativeBrowser.onRemoteSkip = cb)
+)
+
+/**
+ * Subscribes to remote stop events.
+ * @param callback - Called when the user presses the stop button
+ * @returns Cleanup function to unsubscribe
+ */
+export const onRemoteStop = LazyNativeEmitter.emitterize<void>(
+  (cb) => (nativeBrowser.onRemoteStop = cb)
+)