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

package/src/web/http/RequestConfigBuilder.ts

@@ -0,0 +1,347 @@
+import type {
+  RequestConfig,
+  TransformableRequestConfig,
+  MediaRequestConfig,
+  ArtworkRequestConfig,
+  ImageSource,
+  Track,
+  ImageContext,
+  ImageQueryParams,
+} from '../../types'
+import { BrowserPathHelper } from '../util/BrowserPathHelper'
+
+/**
+ * Appends query parameters to a URL, handling existing query strings.
+ */
+function appendQueryParams(
+  url: string,
+  query: Record<string, string | undefined> | undefined
+): string {
+  if (!query || Object.keys(query).length === 0) return url
+
+  const params = new URLSearchParams()
+  for (const [key, value] of Object.entries(query)) {
+    if (value !== undefined && value !== null) {
+      params.append(key, String(value))
+    }
+  }
+  const queryString = params.toString()
+  if (!queryString) return url
+
+  const separator = url.includes('?') ? '&' : '?'
+  return url + separator + queryString
+}
+
+/**
+ * Applies image dimension query parameters to a request config.
+ * Maps ImageContext dimensions to query params using the configured param names.
+ */
+function applyImageQueryParams(
+  config: RequestConfig,
+  imgParams: ImageQueryParams | undefined,
+  context: ImageContext | undefined
+): RequestConfig {
+  if (!imgParams || !context) return config
+
+  const query: Record<string, string> = { ...config.query }
+
+  if (imgParams.width && context.width) {
+    query[imgParams.width] = String(context.width)
+  }
+  if (imgParams.height && context.height) {
+    query[imgParams.height] = String(context.height)
+  }
+
+  return { ...config, query }
+}
+
+/**
+ * Builds and merges request configurations.
+ * Mirrors Android's RequestConfigBuilder.kt
+ */
+export const RequestConfigBuilder = {
+  /**
+   * Builds a complete URL from a request config.
+   * Uses BrowserPathHelper for consistent URL building.
+   */
+  buildUrl(config: RequestConfig): string {
+    const path = config.path ?? ''
+    const baseUrl = config.baseUrl
+
+    // Use BrowserPathHelper for consistent URL building
+    const url = BrowserPathHelper.buildUrl(baseUrl, path)
+
+    // Add query parameters if any
+    return appendQueryParams(url, config.query)
+  },
+
+  /**
+   * Merges two RequestConfigs, with override values taking precedence.
+   * Headers and query params are merged (not replaced).
+   */
+  mergeConfig(base: RequestConfig, override: RequestConfig): RequestConfig {
+    return {
+      path: override.path ?? base.path,
+      method: override.method ?? base.method,
+      baseUrl: override.baseUrl ?? base.baseUrl,
+      headers: this.mergeHeaders(base.headers, override.headers),
+      query: this.mergeQuery(base.query, override.query),
+      body: override.body ?? base.body,
+      contentType: override.contentType ?? base.contentType,
+      userAgent: override.userAgent ?? base.userAgent,
+    }
+  },
+
+  /**
+   * Merges a base RequestConfig with a MediaRequestConfig.
+   * Returns the merged config for use in media URL resolution.
+   * Supports the transform callback like Android's RequestConfigBuilder.
+   *
+   * Note: MediaRequestConfig inherits transform from TransformableRequestConfig,
+   * which takes (request, routeParams?) directly, not MediaTransformParams.
+   */
+  async mergeMediaConfig(
+    base: RequestConfig,
+    override: MediaRequestConfig
+  ): Promise<RequestConfig> {
+    // Apply transform function if provided - transform result wins completely
+    if (override.transform) {
+      try {
+        // TransformableRequestConfig.transform takes (request, routeParams?) directly
+        const transformed = await override.transform(base)
+        return transformed
+      } catch (e) {
+        console.error('Failed to apply media transform function, using base config', e)
+        return base
+      }
+    }
+
+    // No transform - merge static config
+    return this.mergeConfig(base, this.toRequestConfig(override))
+  },
+
+  /**
+   * Merges a base RequestConfig with an ArtworkRequestConfig.
+   * Returns the merged config for use in artwork URL resolution.
+   */
+  mergeArtworkConfig(
+    base: RequestConfig,
+    override: ArtworkRequestConfig
+  ): RequestConfig {
+    // On web, we don't support resolve/transform callbacks - just merge the static config
+    return this.mergeConfig(base, this.toRequestConfig(override))
+  },
+
+  /**
+   * Converts a TransformableRequestConfig to a plain RequestConfig.
+   */
+  toRequestConfig(config: TransformableRequestConfig | MediaRequestConfig | ArtworkRequestConfig): RequestConfig {
+    return {
+      path: config.path,
+      method: config.method,
+      baseUrl: config.baseUrl,
+      headers: config.headers,
+      query: config.query,
+      body: config.body,
+      contentType: config.contentType,
+      userAgent: config.userAgent,
+    }
+  },
+
+  /**
+   * Resolves a media URL using the media configuration.
+   * Creates a RequestConfig with the track's src as the path, then builds the URL.
+   * Supports the transform callback for URL manipulation.
+   *
+   * @param src The track's src value (may be relative or absolute)
+   * @param mediaConfig The media request configuration
+   * @returns The resolved absolute URL
+   */
+  async resolveMediaUrl(
+    src: string,
+    mediaConfig: MediaRequestConfig | undefined
+  ): Promise<string> {
+    if (!mediaConfig) {
+      return BrowserPathHelper.buildUrl(undefined, src)
+    }
+
+    const config = await this.mergeMediaConfig({ path: src }, mediaConfig)
+    return BrowserPathHelper.buildUrl(config.baseUrl, config.path ?? src)
+  },
+
+  /**
+   * Resolves an artwork URL and creates an ImageSource.
+   * Matches Android's artwork URL transformation behavior.
+   *
+   * @param artworkUrl The artwork URL (may be relative or absolute)
+   * @param artworkConfig The artwork request configuration
+   * @returns ImageSource with resolved URI, or undefined if no artwork
+   */
+  resolveArtworkSource(
+    artworkUrl: string | undefined,
+    artworkConfig: ArtworkRequestConfig | undefined
+  ): ImageSource | undefined {
+    if (!artworkUrl) return undefined
+
+    const config = artworkConfig
+      ? this.mergeArtworkConfig({ path: artworkUrl }, artworkConfig)
+      : { path: artworkUrl }
+
+    const resolvedUri = BrowserPathHelper.buildUrl(config.baseUrl, config.path ?? artworkUrl)
+
+    return {
+      uri: resolvedUri,
+      method: config.method ?? 'GET',
+      headers: config.headers,
+    }
+  },
+
+  /**
+   * Resolves an artwork URL asynchronously with full Track access.
+   * Supports resolve and transform callbacks from ArtworkRequestConfig.
+   * Matches Android's CoilBitmapLoader.transformArtworkUrlForTrack() behavior.
+   *
+   * The resolution order is:
+   * 1. If resolve callback exists, call it with the track to get per-track config
+   * 2. Merge base config + resolved config
+   * 3. Apply imageQueryParams if context has dimensions
+   * 4. Apply transform callback if present
+   *
+   * @param track The track to resolve artwork for (full Track object)
+   * @param artworkConfig The artwork request configuration
+   * @param imageContext Optional image context with size hints (width/height)
+   * @returns ImageSource with resolved URI, or undefined if no artwork
+   */
+  async resolveArtworkSourceAsync(
+    track: Track,
+    artworkConfig: ArtworkRequestConfig | undefined,
+    imageContext?: ImageContext
+  ): Promise<ImageSource | undefined> {
+    const artworkUrl = track.artwork
+
+    // If no config and no track.artwork, nothing to transform
+    if (!artworkConfig && !artworkUrl) {
+      return undefined
+    }
+
+    // If no artwork config, just return the original artwork URL
+    if (!artworkConfig) {
+      return artworkUrl ? { uri: artworkUrl, method: 'GET' } : undefined
+    }
+
+    try {
+      // Step 1: Call resolve callback if provided to get per-track config
+      let resolvedConfig: RequestConfig | undefined
+      if (artworkConfig.resolve) {
+        resolvedConfig = await artworkConfig.resolve(track)
+        // If resolve callback returned null/undefined, that means no artwork
+        if (!resolvedConfig && artworkUrl === undefined) {
+          return undefined
+        }
+      }
+
+      // Step 2: Merge base config + resolved per-track config
+      const baseConfig: RequestConfig = { path: artworkUrl }
+      let mergedConfig = this.mergeConfig(
+        this.mergeConfig(baseConfig, this.toRequestConfig(artworkConfig)),
+        resolvedConfig ?? {}
+      )
+
+      // Step 3: Apply imageQueryParams if context has dimensions
+      mergedConfig = applyImageQueryParams(
+        mergedConfig,
+        artworkConfig.imageQueryParams,
+        imageContext
+      )
+
+      // Step 4: Apply transform callback if present
+      if (artworkConfig.transform) {
+        mergedConfig = await artworkConfig.transform({
+          request: mergedConfig,
+          context: imageContext,
+        })
+      }
+
+      // Build final URL
+      const resolvedUri = BrowserPathHelper.buildUrl(
+        mergedConfig.baseUrl,
+        mergedConfig.path ?? artworkUrl ?? ''
+      )
+      const finalUri = appendQueryParams(resolvedUri, mergedConfig.query)
+
+      return {
+        uri: finalUri,
+        method: mergedConfig.method ?? 'GET',
+        headers: mergedConfig.headers,
+        body: mergedConfig.body,
+      }
+    } catch (error) {
+      // resolve/transform threw - log error, return undefined to avoid broken images
+      console.error('Failed to resolve artwork URL:', error)
+      return undefined
+    }
+  },
+
+  /**
+   * Transforms a track's artwork URL and populates artworkSource.
+   * Leaves the original artwork property unchanged.
+   * Matches Android's transformArtworkUrl behavior.
+   *
+   * @param track The track to transform
+   * @param artworkConfig The artwork request configuration
+   * @returns Track with artworkSource populated
+   */
+  transformTrackArtwork(
+    track: Track,
+    artworkConfig: ArtworkRequestConfig | undefined
+  ): Track {
+    // If artworkSource is already set, don't override it
+    if (track.artworkSource) return track
+
+    const artworkSource = this.resolveArtworkSource(track.artwork, artworkConfig)
+    if (!artworkSource) return track
+
+    return {
+      ...track,
+      artworkSource,
+    }
+  },
+
+  /**
+   * Transforms artwork URLs for an array of tracks.
+   *
+   * @param tracks Array of tracks to transform
+   * @param artworkConfig The artwork request configuration
+   * @returns Tracks with artworkSource populated
+   */
+  transformTracksArtwork(
+    tracks: Track[],
+    artworkConfig: ArtworkRequestConfig | undefined
+  ): Track[] {
+    return tracks.map(track => this.transformTrackArtwork(track, artworkConfig))
+  },
+
+  /**
+   * Merges header maps, with override values taking precedence.
+   */
+  mergeHeaders(
+    base: Record<string, string> | undefined,
+    override: Record<string, string> | undefined
+  ): Record<string, string> | undefined {
+    if (!base) return override
+    if (!override) return base
+    return { ...base, ...override }
+  },
+
+  /**
+   * Merges query parameter maps, with override values taking precedence.
+   */
+  mergeQuery(
+    base: Record<string, string> | undefined,
+    override: Record<string, string> | undefined
+  ): Record<string, string> | undefined {
+    if (!base) return override
+    if (!override) return base
+    return { ...base, ...override }
+  },
+} as const

package/src/web/player/NowPlayingManager.ts

@@ -0,0 +1,83 @@
+import type {
+  NowPlayingUpdate,
+  NowPlayingMetadata,
+} from '../../features'
+import type { Track } from '../../types'
+
+/**
+ * Manages now playing metadata overrides.
+ * Allows temporary metadata changes for the currently playing track
+ * (e.g., updating stream metadata for live radio).
+ */
+export class NowPlayingManager {
+  private override: NowPlayingUpdate | undefined
+
+  // Event callback
+  onNowPlayingChanged: (metadata: NowPlayingMetadata) => void = () => {}
+
+  /**
+   * Updates the now playing metadata with an override.
+   * Pass null or undefined to clear overrides and revert to track metadata.
+   *
+   * @param update Metadata override or null/undefined to clear
+   * @param currentTrack Current track for base metadata
+   * @param duration Current track duration
+   */
+  updateNowPlaying(
+    update: NowPlayingUpdate | undefined,
+    currentTrack: Track | undefined,
+    duration: number
+  ): void {
+    this.override = update
+
+    if (!currentTrack) return
+
+    const metadata: NowPlayingMetadata = update
+      ? {
+          title: update.title ?? currentTrack.title,
+          artist: update.artist ?? currentTrack.artist,
+          album: currentTrack.album,
+          artwork: currentTrack.artwork,
+          duration,
+        }
+      : {
+          title: currentTrack.title,
+          artist: currentTrack.artist,
+          album: currentTrack.album,
+          artwork: currentTrack.artwork,
+          duration,
+        }
+
+    this.onNowPlayingChanged(metadata)
+  }
+
+  /**
+   * Gets the current now playing metadata (with override applied if set).
+   *
+   * @param currentTrack Current track for base metadata
+   * @param duration Current track duration
+   * @returns Now playing metadata or undefined if no track
+   */
+  getNowPlaying(
+    currentTrack: Track | undefined,
+    duration: number
+  ): NowPlayingMetadata | undefined {
+    if (!currentTrack) return undefined
+
+    return {
+      title: this.override?.title ?? currentTrack.title,
+      artist: this.override?.artist ?? currentTrack.artist,
+      album: currentTrack.album,
+      artwork: currentTrack.artwork,
+      duration,
+    }
+  }
+
+  /**
+   * Clears the current metadata override.
+   * Should be called when the track changes.
+   */
+  clearNowPlayingOverride(): void {
+    this.override = undefined
+  }
+}

package/src/web/player/OptionsManager.ts

@@ -0,0 +1,101 @@
+import type {
+  NativeUpdateOptions,
+  UpdateOptions,
+  Options,
+  RepeatMode as RepeatModeType,
+} from '../../features'
+import { RepeatMode } from '../TrackPlayer'
+
+type InternalOptions = UpdateOptions & {
+  repeatMode: RepeatModeType
+}
+
+/**
+ * Manages player options and configuration.
+ * Handles option updates and change detection.
+ */
+export class OptionsManager {
+  private options: InternalOptions = {
+    forwardJumpInterval: 15,
+    backwardJumpInterval: 15,
+    progressUpdateEventInterval: null,
+    repeatMode: RepeatMode.Off,
+    capabilities: {},
+  }
+
+  // Event callback
+  onOptionsChanged: (options: Options) => void = () => {}
+
+  /**
+   * Updates player options with change detection.
+   * Emits onOptionsChanged event after updating.
+   *
+   * @param options Partial options to update
+   */
+  updateOptions(options: NativeUpdateOptions): void {
+    if (
+      options.progressUpdateEventInterval !== null &&
+      options.progressUpdateEventInterval !== undefined &&
+      typeof options.progressUpdateEventInterval !== 'number'
+    ) {
+      throw new Error('NullSentinal type is not valid on web.')
+    }
+
+    // Merge platform-agnostic options
+    const mergedOptions: InternalOptions = {
+      ...this.options,
+      forwardJumpInterval:
+        options.forwardJumpInterval ?? this.options.forwardJumpInterval,
+      backwardJumpInterval:
+        options.backwardJumpInterval ?? this.options.backwardJumpInterval,
+      capabilities: options.capabilities ?? this.options.capabilities,
+      progressUpdateEventInterval:
+        options.progressUpdateEventInterval === null
+          ? null
+          : (options.progressUpdateEventInterval ?? this.options.progressUpdateEventInterval),
+    }
+
+    // Store merged options
+    this.options = mergedOptions
+
+    // Call callback with full Options type (including repeatMode)
+    const fullOptions: Options = {
+      forwardJumpInterval: mergedOptions.forwardJumpInterval ?? 15,
+      backwardJumpInterval: mergedOptions.backwardJumpInterval ?? 15,
+      progressUpdateEventInterval:
+        mergedOptions.progressUpdateEventInterval ?? 15,
+      capabilities: mergedOptions.capabilities ?? {},
+      repeatMode: mergedOptions.repeatMode,
+    }
+    this.onOptionsChanged(fullOptions)
+  }
+
+  /**
+   * Gets current player options (excluding repeatMode).
+   */
+  getOptions(): UpdateOptions {
+    return {
+      forwardJumpInterval: this.options.forwardJumpInterval,
+      backwardJumpInterval: this.options.backwardJumpInterval,
+      progressUpdateEventInterval: this.options.progressUpdateEventInterval,
+      capabilities: this.options.capabilities,
+    }
+  }
+
+  /**
+   * Gets the current repeat mode.
+   */
+  getRepeatMode(): RepeatModeType {
+    return this.options.repeatMode
+  }
+
+  /**
+   * Sets the repeat mode.
+   * Updates internal state but does not emit events - caller should handle that.
+   *
+   * @param mode New repeat mode
+   */
+  setRepeatMode(mode: RepeatModeType): void {
+    this.options.repeatMode = mode
+  }
+}

package/src/web/util/BrowserPathHelper.ts

@@ -0,0 +1,147 @@
+/**
+ * Utility for handling browser paths and contextual URLs in the media browser system.
+ * Mirrors Android's BrowserPathHelper.kt
+ *
+ * Handles two types of special paths:
+ * 1. System paths (prefixed with `/__`): Root, recent, and search paths
+ * 2. Contextual URLs: Embed parent context in track identifiers for Media3 integration
+ *
+ * Contextual URL format: `{parentPath}?__trackId={trackSrc}`
+ * Example: "/library/radio?__trackId=song.mp3"
+ *
+ * This allows:
+ * - Media3 to reference playable-only tracks (tracks with `src` but no `url`)
+ * - Cache lookup to work consistently
+ * - Parent context to be preserved for queue restoration
+ */
+export const BrowserPathHelper = {
+  /** Search path prefix (full path is /__search?q=query) */
+  SEARCH_PATH_PREFIX: '/__search',
+
+  /** Query parameter name for contextual track identifiers */
+  CONTEXTUAL_TRACK_PARAM: '__trackId',
+
+  /**
+   * Create a search path for a given query
+   */
+  createSearchPath(query: string): string {
+    const encodedQuery = encodeURIComponent(query)
+    return `${this.SEARCH_PATH_PREFIX}?q=${encodedQuery}`
+  },
+
+  /**
+   * Checks if a path contains a contextual track identifier.
+   *
+   * @param path The URL path to check
+   * @returns true if the path contains the contextual track parameter
+   */
+  isContextual(path: string): boolean {
+    return (
+      path.includes(`?${this.CONTEXTUAL_TRACK_PARAM}=`) ||
+      path.includes(`&${this.CONTEXTUAL_TRACK_PARAM}=`)
+    )
+  },
+
+  /**
+   * Strips the __trackId parameter from a contextual URL to get the parent path.
+   * If the URL is not contextual, returns it unchanged.
+   *
+   * @param url The URL to process
+   * @returns The URL without the __trackId parameter
+   *
+   * Example: "/library/radio?__trackId=song.mp3" → "/library/radio"
+   * Example: "/search?q=jazz&__trackId=song.mp3" → "/search?q=jazz"
+   */
+  stripTrackId(url: string): string {
+    if (!this.isContextual(url)) {
+      return url
+    }
+
+    try {
+      // Parse the URL - handle both full URLs and paths
+      const isFullUrl = url.startsWith('http://') || url.startsWith('https://')
+      const urlObj = new URL(url, isFullUrl ? undefined : 'http://placeholder')
+
+      // Remove the __trackId parameter
+      urlObj.searchParams.delete(this.CONTEXTUAL_TRACK_PARAM)
+
+      // Return the appropriate format
+      if (isFullUrl) {
+        return urlObj.toString()
+      } else {
+        const search = urlObj.searchParams.toString()
+        return search ? `${urlObj.pathname}?${search}` : urlObj.pathname
+      }
+    } catch {
+      // Fallback: simple string manipulation
+      const paramPattern = new RegExp(
+        `[?&]${this.CONTEXTUAL_TRACK_PARAM}=[^&]*`,
+        'g'
+      )
+      let result = url.replace(paramPattern, '')
+      // Clean up any trailing ? or &
+      result = result.replace(/[?&]$/, '')
+      // Fix double && or ?&
+      result = result.replace(/[?&]{2,}/g, '&').replace(/\?&/, '?')
+      return result
+    }
+  },
+
+  /**
+   * Extracts the track ID from a contextual URL.
+   * Returns undefined if the URL is not contextual or doesn't contain the track ID parameter.
+   *
+   * @param path The contextual URL to parse
+   * @returns The extracted track ID, or undefined if not found
+   *
+   * Example: "/library/radio?__trackId=song.mp3" → "song.mp3"
+   */
+  extractTrackId(path: string): string | undefined {
+    if (!this.isContextual(path)) {
+      return undefined
+    }
+
+    try {
+      // Parse the URL - handle both full URLs and paths
+      const isFullUrl = path.startsWith('http://') || path.startsWith('https://')
+      const urlObj = new URL(path, isFullUrl ? undefined : 'http://placeholder')
+      return urlObj.searchParams.get(this.CONTEXTUAL_TRACK_PARAM) ?? undefined
+    } catch {
+      // Fallback: regex extraction
+      const match = path.match(
+        new RegExp(`[?&]${this.CONTEXTUAL_TRACK_PARAM}=([^&]*)`)
+      )
+      return match?.[1] ? decodeURIComponent(match[1]) : undefined
+    }
+  },
+
+  /**
+   * Combines a base URL with a path, ensuring proper slash handling.
+   *
+   * @param baseUrl The base URL (can be undefined)
+   * @param path The path to append
+   * @returns The combined URL with proper slash handling
+   *
+   * Examples:
+   * - buildUrl("http://example.com", "api/test") → "http://example.com/api/test"
+   * - buildUrl("http://example.com/", "/api/test") → "http://example.com/api/test"
+   * - buildUrl(undefined, "/api/test") → "/api/test"
+   * - buildUrl(undefined, "http://full.url") → "http://full.url"
+   */
+  buildUrl(baseUrl: string | undefined, path: string): string {
+    // If path is already a full URL, return it as-is
+    if (path.startsWith('http://') || path.startsWith('https://')) {
+      return path
+    }
+
+    // If no baseUrl, return path as-is
+    if (!baseUrl) {
+      return path
+    }
+
+    // Ensure baseUrl ends with / and path doesn't start with /
+    const normalizedBase = baseUrl.replace(/\/+$/, '') + '/'
+    const normalizedPath = path.replace(/^\/+/, '')
+    return `${normalizedBase}${normalizedPath}`
+  },
+} as const

package/src/web/util/shuffle.ts

@@ -0,0 +1,14 @@
+/**
+ * Shuffles an array in place using the Fisher-Yates algorithm.
+ * https://en.wikipedia.org/wiki/Fisher%E2%80%93Yates_shuffle
+ *
+ * @param array The array to shuffle (mutated in place)
+ */
+export function fisherYatesShuffle<T>(array: T[]): void {
+  for (let i = array.length - 1; i > 0; i--) {
+    const j = Math.floor(Math.random() * (i + 1))
+    const temp = array[i]!
+    array[i] = array[j]!
+    array[j] = temp
+  }
+}