react-native-audio-browser 0.1.1 → 0.2.0-next.2

package/src/web/player/MediaSessionManager.test.ts

@@ -0,0 +1,220 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import type { MediaSessionActions } from './MediaSessionManager'
+import { MediaSessionManager } from './MediaSessionManager'
+
+type Handler = ((details: any) => void) | null
+
+class FakeMediaMetadata {
+  title?: string
+  artist?: string
+  album?: string
+  artwork: { src: string }[]
+  constructor(init: {
+    title?: string
+    artist?: string
+    album?: string
+    artwork?: { src: string }[]
+  }) {
+    this.title = init.title
+    this.artist = init.artist
+    this.album = init.album
+    this.artwork = init.artwork ?? []
+  }
+}
+
+function makeFakeSession() {
+  const handlers = new Map<string, Handler>()
+  const setPositionState = vi.fn()
+  const session = {
+    metadata: null as FakeMediaMetadata | null,
+    playbackState: 'none' as 'none' | 'paused' | 'playing',
+    setActionHandler: vi.fn((action: string, handler: Handler) => {
+      handlers.set(action, handler)
+    }),
+    setPositionState
+  }
+  return { session, handlers, setPositionState }
+}
+
+function makeActions(): MediaSessionActions {
+  return {
+    play: vi.fn(),
+    pause: vi.fn(),
+    stop: vi.fn(),
+    next: vi.fn(),
+    previous: vi.fn(),
+    seek: vi.fn(),
+    jumpForward: vi.fn(),
+    jumpBackward: vi.fn()
+  }
+}
+
+describe('MediaSessionManager', () => {
+  let fake: ReturnType<typeof makeFakeSession>
+
+  beforeEach(() => {
+    fake = makeFakeSession()
+    vi.stubGlobal('navigator', { mediaSession: fake.session })
+    vi.stubGlobal('MediaMetadata', FakeMediaMetadata)
+  })
+
+  afterEach(() => {
+    vi.unstubAllGlobals()
+  })
+
+  it('registers action handlers that route to the provided actions', () => {
+    const actions = makeActions()
+    new MediaSessionManager(actions)
+
+    fake.handlers.get('play')?.(undefined)
+    fake.handlers.get('pause')?.(undefined)
+    fake.handlers.get('stop')?.(undefined)
+    fake.handlers.get('nexttrack')?.(undefined)
+    fake.handlers.get('previoustrack')?.(undefined)
+
+    expect(actions.play).toHaveBeenCalledOnce()
+    expect(actions.pause).toHaveBeenCalledOnce()
+    expect(actions.stop).toHaveBeenCalledOnce()
+    expect(actions.next).toHaveBeenCalledOnce()
+    expect(actions.previous).toHaveBeenCalledOnce()
+  })
+
+  it('routes seekto with the requested seek time', () => {
+    const actions = makeActions()
+    new MediaSessionManager(actions)
+
+    fake.handlers.get('seekto')?.({ seekTime: 42 })
+
+    expect(actions.seek).toHaveBeenCalledWith(42)
+  })
+
+  it('ignores seekto without a seek time', () => {
+    const actions = makeActions()
+    new MediaSessionManager(actions)
+
+    fake.handlers.get('seekto')?.({})
+
+    expect(actions.seek).not.toHaveBeenCalled()
+  })
+
+  it('uses the seek offset for seekforward/seekbackward, falling back to a default', () => {
+    const actions = makeActions()
+    new MediaSessionManager(actions)
+
+    fake.handlers.get('seekforward')?.({ seekOffset: 30 })
+    fake.handlers.get('seekbackward')?.({})
+
+    expect(actions.jumpForward).toHaveBeenCalledWith(30)
+    expect(actions.jumpBackward).toHaveBeenCalledWith(10)
+  })
+
+  it('publishes metadata to the session', () => {
+    new MediaSessionManager(makeActions()).setMetadata({
+      title: 'Live Set',
+      artist: 'Station FM',
+      album: 'Radio',
+      artwork: 'https://api.example.com/art.png'
+    })
+
+    const metadata = fake.session.metadata as FakeMediaMetadata
+    expect(metadata.title).toBe('Live Set')
+    expect(metadata.artist).toBe('Station FM')
+    expect(metadata.album).toBe('Radio')
+    expect(metadata.artwork).toEqual([
+      { src: 'https://api.example.com/art.png' }
+    ])
+  })
+
+  it('omits artwork when none is provided', () => {
+    new MediaSessionManager(makeActions()).setMetadata({ title: 'No Art' })
+    const metadata = fake.session.metadata as FakeMediaMetadata
+    expect(metadata.artwork).toEqual([])
+  })
+
+  it('reflects playback state', () => {
+    const manager = new MediaSessionManager(makeActions())
+    manager.setPlaybackState('playing')
+    expect(fake.session.playbackState).toBe('playing')
+    manager.setPlaybackState('paused')
+    expect(fake.session.playbackState).toBe('paused')
+  })
+
+  it('reports position state for finite, seekable durations', () => {
+    const manager = new MediaSessionManager(makeActions())
+    manager.setPositionState({ duration: 180, position: 30, playbackRate: 1 })
+    expect(fake.setPositionState).toHaveBeenCalledWith({
+      duration: 180,
+      position: 30,
+      playbackRate: 1
+    })
+  })
+
+  it('clears position state for live streams (infinite/zero duration)', () => {
+    const manager = new MediaSessionManager(makeActions())
+    manager.setPositionState({
+      duration: Infinity,
+      position: 30,
+      playbackRate: 1
+    })
+    manager.setPositionState({ duration: 0, position: 0, playbackRate: 1 })
+    // Called with no argument resets the position state.
+    expect(fake.setPositionState).toHaveBeenCalledTimes(2)
+    expect(fake.setPositionState).toHaveBeenNthCalledWith(1)
+    expect(fake.setPositionState).toHaveBeenNthCalledWith(2)
+  })
+
+  it('clamps position to within the duration', () => {
+    const manager = new MediaSessionManager(makeActions())
+    manager.setPositionState({ duration: 100, position: 150, playbackRate: 1 })
+    expect(fake.setPositionState).toHaveBeenCalledWith({
+      duration: 100,
+      position: 100,
+      playbackRate: 1
+    })
+  })
+
+  it('clamps a negative position up to zero', () => {
+    const manager = new MediaSessionManager(makeActions())
+    manager.setPositionState({ duration: 100, position: -5, playbackRate: 1 })
+    expect(fake.setPositionState).toHaveBeenCalledWith({
+      duration: 100,
+      position: 0,
+      playbackRate: 1
+    })
+  })
+
+  it('coerces a non-positive playback rate to 1 (the API rejects rate 0)', () => {
+    const manager = new MediaSessionManager(makeActions())
+    manager.setPositionState({ duration: 100, position: 10, playbackRate: 0 })
+    expect(fake.setPositionState).toHaveBeenCalledWith({
+      duration: 100,
+      position: 10,
+      playbackRate: 1
+    })
+  })
+
+  it('dispose clears handlers, metadata and playback state', () => {
+    const manager = new MediaSessionManager(makeActions())
+    manager.setMetadata({ title: 'x' })
+    manager.setPlaybackState('playing')
+
+    manager.dispose()
+
+    expect(fake.session.metadata).toBeNull()
+    expect(fake.session.playbackState).toBe('none')
+    // Every registered action gets cleared back to null.
+    expect(fake.handlers.get('play')).toBeNull()
+  })
+
+  it('is a no-op when the Media Session API is unavailable', () => {
+    vi.stubGlobal('navigator', {})
+    const actions = makeActions()
+    expect(() => {
+      const manager = new MediaSessionManager(actions)
+      manager.setMetadata({ title: 'x' })
+      manager.setPlaybackState('playing')
+      manager.setPositionState({ duration: 1, position: 0, playbackRate: 1 })
+      manager.dispose()
+    }).not.toThrow()
+  })
+})

package/src/web/player/MediaSessionManager.ts

@@ -0,0 +1,151 @@
+import type { NowPlayingMetadata } from '../../features'
+
+/**
+ * Player actions a Media Session command routes into. The host wires these to
+ * its remote-dispatch methods (handle-or-default, then emit) so browser media
+ * controls behave exactly like the native lockscreen/CarPlay/Android Auto path.
+ */
+export interface MediaSessionActions {
+  play(): void
+  pause(): void
+  stop(): void
+  next(): void
+  previous(): void
+  /** Absolute seek, in seconds. */
+  seek(position: number): void
+  /** Relative seek forward, in seconds. */
+  jumpForward(interval: number): void
+  /** Relative seek backward, in seconds. */
+  jumpBackward(interval: number): void
+}
+
+/** Fallback skip interval (seconds) when the browser omits a seek offset. */
+const DEFAULT_SEEK_INTERVAL = 10
+
+/**
+ * Bridges the web player to the browser's Media Session API, so the OS media
+ * controls (lockscreen, notification shade, hardware media keys, Bluetooth
+ * controls) show the current track and route their commands back into the
+ * player.
+ *
+ * The native platforms publish now-playing metadata and handle remote commands
+ * via MPNowPlayingInfoCenter / MediaSession; this is the web equivalent. It is a
+ * no-op when the API is unavailable (server-side rendering, older browsers).
+ */
+export class MediaSessionManager {
+  private readonly session: MediaSession | undefined
+
+  /** Actions registered as handlers — tracked so dispose() can clear them. */
+  private static readonly ACTIONS: MediaSessionAction[] = [
+    'play',
+    'pause',
+    'stop',
+    'nexttrack',
+    'previoustrack',
+    'seekto',
+    'seekforward',
+    'seekbackward'
+  ]
+
+  constructor(actions: MediaSessionActions) {
+    this.session =
+      typeof navigator !== 'undefined' &&
+      'mediaSession' in navigator &&
+      typeof MediaMetadata !== 'undefined'
+        ? navigator.mediaSession
+        : undefined
+    if (this.session) this.registerHandlers(this.session, actions)
+  }
+
+  /**
+   * Publishes now-playing metadata to the OS media controls.
+   */
+  setMetadata(metadata: NowPlayingMetadata): void {
+    if (!this.session) return
+    this.session.metadata = new MediaMetadata({
+      title: metadata.title ?? '',
+      artist: metadata.artist ?? '',
+      album: metadata.album ?? '',
+      artwork: metadata.artwork ? [{ src: metadata.artwork }] : []
+    })
+  }
+
+  /**
+   * Reflects whether the player is playing/paused/stopped in the OS controls.
+   */
+  setPlaybackState(state: MediaSessionPlaybackState): void {
+    if (!this.session) return
+    this.session.playbackState = state
+  }
+
+  /**
+   * Reports the scrubber position. Live streams (infinite or unknown duration)
+   * have no meaningful position, so the state is cleared instead.
+   */
+  setPositionState(state: {
+    duration: number
+    position: number
+    playbackRate: number
+  }): void {
+    if (!this.session?.setPositionState) return
+    const { duration, position, playbackRate } = state
+    if (!Number.isFinite(duration) || duration <= 0) {
+      // No seekable timeline (live radio) — clear any stale position.
+      this.session.setPositionState()
+      return
+    }
+    this.session.setPositionState({
+      duration,
+      position: Math.max(0, Math.min(position, duration)),
+      playbackRate: playbackRate > 0 ? playbackRate : 1
+    })
+  }
+
+  /**
+   * Removes handlers and clears metadata/state. Call when tearing down.
+   */
+  dispose(): void {
+    if (!this.session) return
+    for (const action of MediaSessionManager.ACTIONS) {
+      try {
+        this.session.setActionHandler(action, null)
+      } catch {
+        // Browser doesn't support this action — nothing to clear.
+      }
+    }
+    this.session.metadata = null
+    this.session.playbackState = 'none'
+  }
+
+  private registerHandlers(
+    session: MediaSession,
+    actions: MediaSessionActions
+  ): void {
+    const set = (
+      action: MediaSessionAction,
+      handler: MediaSessionActionHandler
+    ) => {
+      // Not every browser supports every action; ignore the ones it rejects.
+      try {
+        session.setActionHandler(action, handler)
+      } catch {
+        // Unsupported action — skip it.
+      }
+    }
+
+    set('play', () => actions.play())
+    set('pause', () => actions.pause())
+    set('stop', () => actions.stop())
+    set('nexttrack', () => actions.next())
+    set('previoustrack', () => actions.previous())
+    set('seekto', (details) => {
+      if (details.seekTime != null) actions.seek(details.seekTime)
+    })
+    set('seekforward', (details) => {
+      actions.jumpForward(details.seekOffset ?? DEFAULT_SEEK_INTERVAL)
+    })
+    set('seekbackward', (details) => {
+      actions.jumpBackward(details.seekOffset ?? DEFAULT_SEEK_INTERVAL)
+    })
+  }
+}

package/src/web/player/NowPlayingManager.test.ts

@@ -0,0 +1,46 @@
+import { describe, expect, it } from 'vitest'
+import type { Track } from '../../types'
+import { NowPlayingManager } from './NowPlayingManager'
+
+const track = {
+  src: 'https://example.com/stream',
+  title: 'Track Title',
+  artist: 'Track Artist',
+  album: 'Track Album'
+} as Track
+
+describe('NowPlayingManager', () => {
+  it('applies the same override fields on push and pull', () => {
+    const manager = new NowPlayingManager()
+    let pushed
+    manager.onNowPlayingChanged = (metadata) => {
+      pushed = metadata
+    }
+
+    manager.updateNowPlaying(
+      { title: 'Live Title', artist: 'Live Artist', album: 'Live Album' },
+      track,
+      0
+    )
+    const pulled = manager.getNowPlaying(track, 0)
+
+    // The pull path used to drop the album override while push applied it.
+    expect(pulled).toMatchObject({
+      title: 'Live Title',
+      artist: 'Live Artist',
+      album: 'Live Album'
+    })
+    expect(pulled).toMatchObject(pushed!)
+  })
+
+  it('falls back to track metadata for unset override fields', () => {
+    const manager = new NowPlayingManager()
+    manager.updateNowPlaying({ title: 'Live Title' }, track, 0)
+
+    expect(manager.getNowPlaying(track, 0)).toMatchObject({
+      title: 'Live Title',
+      artist: 'Track Artist',
+      album: 'Track Album'
+    })
+  })
+})

package/src/web/player/NowPlayingManager.ts

@@ -1,5 +1,6 @@
 import type { NowPlayingUpdate, NowPlayingMetadata } from '../../features'
 import type { Track } from '../../types'
+import { artworkUrl } from '../../utils/artwork'
 
 /**
  * Manages now playing metadata overrides.
@@ -33,8 +34,8 @@ export class NowPlayingManager {
       ? {
           title: update.title ?? currentTrack.title,
           artist: update.artist ?? currentTrack.artist,
-          album: currentTrack.album,
-          artwork: currentTrack.artwork,
+          album: update.album ?? currentTrack.album,
+          artwork: artworkUrl(currentTrack.artwork),
           description: currentTrack.description,
           mediaId: currentTrack.src ?? currentTrack.url,
           genre: currentTrack.genre,
@@ -44,7 +45,7 @@ export class NowPlayingManager {
           title: currentTrack.title,
           artist: currentTrack.artist,
           album: currentTrack.album,
-          artwork: currentTrack.artwork,
+          artwork: artworkUrl(currentTrack.artwork),
           description: currentTrack.description,
           mediaId: currentTrack.src ?? currentTrack.url,
           genre: currentTrack.genre,
@@ -70,8 +71,8 @@ export class NowPlayingManager {
     return {
       title: this.override?.title ?? currentTrack.title,
       artist: this.override?.artist ?? currentTrack.artist,
-      album: currentTrack.album,
-      artwork: currentTrack.artwork,
+      album: this.override?.album ?? currentTrack.album,
+      artwork: artworkUrl(currentTrack.artwork),
       description: currentTrack.description,
       mediaId: currentTrack.src ?? currentTrack.url,
       genre: currentTrack.genre,

package/src/web/player/OptionsManager.ts

@@ -59,27 +59,21 @@ export class OptionsManager {
     // 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)
+    this.onOptionsChanged(this.toOptions())
   }
 
-  /**
-   * Gets current player options (excluding repeatMode).
-   */
-  getOptions(): UpdateOptions {
+  /** The current options in their resolved shape. */
+  getOptions(): Options {
+    return this.toOptions()
+  }
+
+  private toOptions(): Options {
     return {
-      forwardJumpInterval: this.options.forwardJumpInterval,
-      backwardJumpInterval: this.options.backwardJumpInterval,
-      progressUpdateEventInterval: this.options.progressUpdateEventInterval,
-      capabilities: this.options.capabilities
+      forwardJumpInterval: this.options.forwardJumpInterval ?? 15,
+      backwardJumpInterval: this.options.backwardJumpInterval ?? 15,
+      progressUpdateEventInterval:
+        this.options.progressUpdateEventInterval ?? null,
+      capabilities: this.options.capabilities ?? {}
     }
   }
 

package/src/web/player/RemoteCommandController.test.ts

@@ -0,0 +1,171 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import type { RemoteCommandHost } from './RemoteCommandController'
+import { RemoteCommandController } from './RemoteCommandController'
+
+type Handler = ((details: any) => void) | null
+
+class FakeMediaMetadata {
+  constructor(public init: Record<string, unknown>) {}
+}
+
+/** Captures the action handlers the controller registers on the session. */
+function stubMediaSession() {
+  const handlers = new Map<string, Handler>()
+  const session = {
+    metadata: null as unknown,
+    playbackState: 'none' as 'none' | 'paused' | 'playing',
+    setActionHandler: (action: string, handler: Handler) =>
+      handlers.set(action, handler),
+    setPositionState: vi.fn()
+  }
+  vi.stubGlobal('navigator', { mediaSession: session })
+  vi.stubGlobal('MediaMetadata', FakeMediaMetadata)
+  return { session, handlers }
+}
+
+function makeHost(
+  overrides: Partial<RemoteCommandHost> = {}
+): RemoteCommandHost {
+  return {
+    play: vi.fn(),
+    pause: vi.fn(),
+    stop: vi.fn(),
+    skipToNext: vi.fn(),
+    skipToPrevious: vi.fn(),
+    seekTo: vi.fn(),
+    seekBy: vi.fn(),
+    handleRemotePlay: undefined,
+    handleRemotePause: undefined,
+    handleRemoteStop: undefined,
+    handleRemoteNext: undefined,
+    handleRemotePrevious: undefined,
+    handleRemoteSeek: undefined,
+    handleRemoteJumpForward: undefined,
+    handleRemoteJumpBackward: undefined,
+    onRemotePlay: vi.fn(),
+    onRemotePause: vi.fn(),
+    onRemoteStop: vi.fn(),
+    onRemoteNext: vi.fn(),
+    onRemotePrevious: vi.fn(),
+    onRemoteSeek: vi.fn(),
+    onRemoteJumpForward: vi.fn(),
+    onRemoteJumpBackward: vi.fn(),
+    getPlayback: vi.fn(() => ({ state: 'playing' })) as any,
+    getPlayingState: vi.fn(() => ({ playing: true, buffering: false })),
+    getProgress: vi.fn(() => ({ position: 0, duration: 0, buffered: 0 })),
+    ...overrides
+  }
+}
+
+describe('RemoteCommandController', () => {
+  let session: ReturnType<typeof stubMediaSession>['session']
+  let handlers: ReturnType<typeof stubMediaSession>['handlers']
+
+  beforeEach(() => {
+    ;({ session, handlers } = stubMediaSession())
+  })
+
+  afterEach(() => {
+    vi.unstubAllGlobals()
+  })
+
+  // Each media-session action → its default transport method + emitted event.
+  const VOID_COMMANDS = [
+    { action: 'play', transport: 'play', emit: 'onRemotePlay' },
+    { action: 'pause', transport: 'pause', emit: 'onRemotePause' },
+    { action: 'stop', transport: 'stop', emit: 'onRemoteStop' },
+    { action: 'nexttrack', transport: 'skipToNext', emit: 'onRemoteNext' },
+    {
+      action: 'previoustrack',
+      transport: 'skipToPrevious',
+      emit: 'onRemotePrevious'
+    }
+  ] as const
+
+  it.each(VOID_COMMANDS)(
+    '$action runs $transport and emits $emit by default',
+    ({ action, transport, emit }) => {
+      const host = makeHost()
+      new RemoteCommandController(host)
+
+      handlers.get(action)?.(undefined)
+
+      expect(host[transport]).toHaveBeenCalledOnce()
+      expect(host[emit]).toHaveBeenCalledOnce()
+    }
+  )
+
+  it('prefers a consumer handler over the default action, still emitting', () => {
+    const handleRemotePlay = vi.fn()
+    const host = makeHost({ handleRemotePlay })
+    new RemoteCommandController(host)
+
+    handlers.get('play')?.(undefined)
+
+    expect(handleRemotePlay).toHaveBeenCalledOnce()
+    expect(host.play).not.toHaveBeenCalled()
+    expect(host.onRemotePlay).toHaveBeenCalledOnce()
+  })
+
+  it('reads handlers live, honouring ones assigned after construction', () => {
+    const host = makeHost()
+    new RemoteCommandController(host)
+
+    const lateHandler = vi.fn()
+    host.handleRemotePause = lateHandler
+    handlers.get('pause')?.(undefined)
+
+    expect(lateHandler).toHaveBeenCalledOnce()
+    expect(host.pause).not.toHaveBeenCalled()
+  })
+
+  it('passes seek/jump payloads to default actions and events', () => {
+    const host = makeHost()
+    new RemoteCommandController(host)
+
+    handlers.get('seekto')?.({ seekTime: 12 })
+    handlers.get('seekforward')?.({ seekOffset: 25 })
+    handlers.get('seekbackward')?.({})
+
+    expect(host.seekTo).toHaveBeenCalledWith(12)
+    expect(host.onRemoteSeek).toHaveBeenCalledWith({ position: 12 })
+    expect(host.seekBy).toHaveBeenCalledWith(25)
+    expect(host.onRemoteJumpForward).toHaveBeenCalledWith({ interval: 25 })
+    expect(host.seekBy).toHaveBeenCalledWith(-10)
+    expect(host.onRemoteJumpBackward).toHaveBeenCalledWith({ interval: 10 })
+  })
+
+  it('mirrors playback state from the host', () => {
+    const playback = { state: 'ready' as const }
+    const playingState = { playing: false, buffering: false }
+    const host = makeHost({
+      getPlayback: vi.fn(() => playback) as any,
+      getPlayingState: vi.fn(() => playingState)
+    })
+    const controller = new RemoteCommandController(host)
+
+    controller.syncPlaybackState()
+    expect(session.playbackState).toBe('paused')
+
+    playingState.playing = true
+    controller.syncPlaybackState()
+    expect(session.playbackState).toBe('playing')
+
+    ;(playback as { state: string }).state = 'none'
+    controller.syncPlaybackState()
+    expect(session.playbackState).toBe('none')
+  })
+
+  it('pushes scrubber position from host progress', () => {
+    const host = makeHost({
+      getProgress: vi.fn(() => ({ position: 30, duration: 180, buffered: 0 }))
+    })
+    new RemoteCommandController(host).updateProgress()
+
+    expect(session.setPositionState).toHaveBeenCalledWith({
+      duration: 180,
+      position: 30,
+      playbackRate: 1
+    })
+  })
+})