Merge pull request #36 from MongooseMoo/feat/media-session-spatial-overlays

feat(audio): Media Session controls + spatial overlay scaffolding

Author: ctoth

src/audio/MediaSessionController.test.ts

@@ -0,0 +1,170 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { MediaSessionController } from './MediaSessionController';
+
+type ActionHandlers = Record<string, MediaSessionActionHandler>;
+
+function installMockSession() {
+  const handlers: ActionHandlers = {};
+  const session = {
+    metadata: null as MediaMetadata | null,
+    playbackState: 'none' as MediaSessionPlaybackState,
+    setActionHandler: vi.fn((action: string, handler: MediaSessionActionHandler | null) => {
+      if (handler) {
+        handlers[action] = handler;
+      } else {
+        delete handlers[action];
+      }
+    }),
+    setPositionState: vi.fn(),
+  };
+  Object.defineProperty(navigator, 'mediaSession', {
+    value: session,
+    configurable: true,
+    writable: true,
+  });
+  // jsdom has no MediaMetadata constructor — provide a minimal stand-in.
+  (globalThis as unknown as { MediaMetadata: unknown }).MediaMetadata = class {
+    title?: string;
+    artist?: string;
+    album?: string;
+    artwork?: MediaImage[];
+    constructor(init: MediaMetadataInit = {}) {
+      this.title = init.title;
+      this.artist = init.artist;
+      this.album = init.album;
+      this.artwork = init.artwork as MediaImage[] | undefined;
+    }
+  };
+  return { session, handlers };
+}
+
+function removeMockSession() {
+  Reflect.deleteProperty(navigator, 'mediaSession');
+  Reflect.deleteProperty(globalThis as object, 'MediaMetadata');
+}
+
+function makeActions() {
+  return {
+    play: vi.fn(),
+    pause: vi.fn(),
+    stop: vi.fn(),
+    seekTo: vi.fn(),
+    seekBackward: vi.fn(),
+    seekForward: vi.fn(),
+  };
+}
+
+describe('MediaSessionController', () => {
+  afterEach(() => {
+    removeMockSession();
+    vi.restoreAllMocks();
+  });
+
+  describe('with a Media Session available', () => {
+    let session: ReturnType<typeof installMockSession>['session'];
+    let handlers: ActionHandlers;
+    let controller: MediaSessionController;
+    let actions: ReturnType<typeof makeActions>;
+
+    beforeEach(() => {
+      ({ session, handlers } = installMockSession());
+      controller = new MediaSessionController();
+      actions = makeActions();
+    });
+
+    it('publishes track metadata and a playing state on setNowPlaying', () => {
+      controller.setNowPlaying(
+        { title: 'Cantina Band', artist: 'Figrin D’an', album: 'Mos Eisley' },
+        actions,
+      );
+      expect(session.metadata?.title).toBe('Cantina Band');
+      expect(session.metadata?.artist).toBe('Figrin D’an');
+      expect(session.playbackState).toBe('playing');
+    });
+
+    it('routes OS transport actions to the supplied callbacks', () => {
+      controller.setNowPlaying({ title: 'Track' }, actions);
+
+      handlers.play?.({ action: 'play' });
+      handlers.pause?.({ action: 'pause' });
+      handlers.stop?.({ action: 'stop' });
+      expect(actions.play).toHaveBeenCalledOnce();
+      expect(actions.pause).toHaveBeenCalledOnce();
+      expect(actions.stop).toHaveBeenCalledOnce();
+    });
+
+    it('forwards seekto with the OS-supplied time', () => {
+      controller.setNowPlaying({ title: 'Track' }, actions);
+      handlers.seekto?.({ action: 'seekto', seekTime: 42 });
+      expect(actions.seekTo).toHaveBeenCalledWith(42);
+    });
+
+    it('falls back to a default offset for seekforward/backward', () => {
+      controller.setNowPlaying({ title: 'Track' }, actions);
+      handlers.seekforward?.({ action: 'seekforward' });
+      handlers.seekbackward?.({ action: 'seekbackward', seekOffset: 5 });
+      expect(actions.seekForward).toHaveBeenCalledWith(10);
+      expect(actions.seekBackward).toHaveBeenCalledWith(5);
+    });
+
+    it('re-targets the once-registered handlers to the latest track', () => {
+      controller.setNowPlaying({ title: 'First' }, actions);
+      const second = makeActions();
+      controller.setNowPlaying({ title: 'Second' }, second);
+
+      // Handlers are registered exactly once per action (6 actions total).
+      expect(session.setActionHandler).toHaveBeenCalledTimes(6);
+
+      handlers.pause?.({ action: 'pause' });
+      expect(second.pause).toHaveBeenCalledOnce();
+      expect(actions.pause).not.toHaveBeenCalled();
+    });
+
+    it('reports a finite position to the scrubber', () => {
+      controller.setPositionState(120, 30, 1);
+      expect(session.setPositionState).toHaveBeenCalledWith({
+        duration: 120,
+        position: 30,
+        playbackRate: 1,
+      });
+    });
+
+    it('clamps position into [0, duration]', () => {
+      controller.setPositionState(100, 250, 1);
+      expect(session.setPositionState).toHaveBeenCalledWith({
+        duration: 100,
+        position: 100,
+        playbackRate: 1,
+      });
+    });
+
+    it('skips position reporting when the duration is unknown', () => {
+      controller.setPositionState(NaN, 10);
+      controller.setPositionState(0, 10);
+      expect(session.setPositionState).not.toHaveBeenCalled();
+    });
+
+    it('clears metadata, state, and position on clear', () => {
+      controller.setNowPlaying({ title: 'Track' }, actions);
+      controller.clear();
+      expect(session.metadata).toBeNull();
+      expect(session.playbackState).toBe('none');
+      expect(session.setPositionState).toHaveBeenLastCalledWith();
+    });
+  });
+
+  describe('without a Media Session (unsupported browser / SSR)', () => {
+    it('no-ops on every method instead of throwing', () => {
+      // No installMockSession(): navigator.mediaSession is undefined.
+      const controller = new MediaSessionController();
+      const actions = makeActions();
+      expect(() => {
+        controller.setNowPlaying({ title: 'Track' }, actions);
+        controller.setPlaybackState('paused');
+        controller.setPositionState(100, 10);
+        controller.clear();
+      }).not.toThrow();
+    });
+  });
+});

src/audio/MediaSessionController.ts

@@ -0,0 +1,149 @@
+/**
+ * Bridges playing media to the browser's Media Session API
+ * (`navigator.mediaSession`), which is what drives OS-level "now playing"
+ * surfaces: the lock screen, notification-shade transport controls, hardware
+ * media keys, smartwatch remotes, and car head units.
+ *
+ * The controller owns NO audio. It is a presentation surface: callers tell it
+ * what is playing and supply callbacks the OS controls invoke, and it relays
+ * those to the platform. Everything is feature-detected, so on a browser (or
+ * test environment) without the API every method is a silent no-op.
+ */
+
+/** Lock-screen track info. `title` is the only required field. */
+export interface MediaSessionTrack {
+  title: string;
+  artist?: string;
+  album?: string;
+  artwork?: MediaImage[];
+}
+
+/**
+ * Callbacks the OS transport controls invoke. The controller never decides what
+ * these do — it forwards the user's lock-screen gesture to the owner, which acts
+ * on whatever it currently considers "now playing".
+ */
+export interface MediaSessionActions {
+  play(): void;
+  pause(): void;
+  stop(): void;
+  seekTo(time: number): void;
+  seekBackward(offset: number): void;
+  seekForward(offset: number): void;
+}
+
+/** Default jump (seconds) for seek-forward/backward when the OS omits an offset. */
+const DEFAULT_SEEK_OFFSET_SECONDS = 10;
+
+export class MediaSessionController {
+  /** Active forwarding target; null when nothing is playing. */
+  private actions: MediaSessionActions | null = null;
+  /** Platform action handlers are registered once, then re-target via `actions`. */
+  private handlersBound = false;
+
+  /** The live MediaSession, or null where the API is unavailable. */
+  private get session(): MediaSession | null {
+    if (typeof navigator === 'undefined') {
+      return null;
+    }
+    return navigator.mediaSession ?? null;
+  }
+
+  /**
+   * Announce a new now-playing track and bind the OS controls to `actions`.
+   * Re-targets the (once-registered) platform handlers so the controls always
+   * drive the most recently started track.
+   */
+  setNowPlaying(track: MediaSessionTrack, actions: MediaSessionActions): void {
+    const session = this.session;
+    if (!session) {
+      return;
+    }
+    this.actions = actions;
+    this.bindHandlers(session);
+    session.metadata = this.buildMetadata(track);
+    session.playbackState = 'playing';
+  }
+
+  /** Reflect play/pause state so the OS shows the right transport icon. */
+  setPlaybackState(state: MediaSessionPlaybackState): void {
+    const session = this.session;
+    if (session) {
+      session.playbackState = state;
+    }
+  }
+
+  /**
+   * Report the scrubber position. The OS extrapolates position from
+   * `playbackRate`, so this only needs calling on play/pause/seek — not on a
+   * timer. Skipped entirely when the duration is unknown (NaN/0), which is the
+   * common case for open-ended streams.
+   */
+  setPositionState(duration: number, position: number, playbackRate = 1): void {
+    const session = this.session;
+    if (!session || typeof session.setPositionState !== 'function') {
+      return;
+    }
+    if (!Number.isFinite(duration) || duration <= 0) {
+      return;
+    }
+    const clamped = Math.min(Math.max(position, 0), duration);
+    session.setPositionState({ duration, position: clamped, playbackRate: playbackRate || 1 });
+  }
+
+  /** Tear down the now-playing surface (track ended/stopped). */
+  clear(): void {
+    const session = this.session;
+    if (!session) {
+      return;
+    }
+    this.actions = null;
+    session.metadata = null;
+    session.playbackState = 'none';
+    if (typeof session.setPositionState === 'function') {
+      session.setPositionState();
+    }
+  }
+
+  private buildMetadata(track: MediaSessionTrack): MediaMetadata | null {
+    if (typeof MediaMetadata === 'undefined') {
+      return null;
+    }
+    return new MediaMetadata({
+      title: track.title,
+      artist: track.artist ?? '',
+      album: track.album ?? '',
+      artwork: track.artwork ?? [],
+    });
+  }
+
+  private bindHandlers(session: MediaSession): void {
+    if (this.handlersBound) {
+      return;
+    }
+    this.handlersBound = true;
+
+    const set = (action: MediaSessionAction, handler: MediaSessionActionHandler): void => {
+      try {
+        session.setActionHandler(action, handler);
+      } catch {
+        // The browser doesn't support this action — expected; nothing to do.
+      }
+    };
+
+    set('play', () => this.actions?.play());
+    set('pause', () => this.actions?.pause());
+    set('stop', () => this.actions?.stop());
+    set('seekto', (details) => {
+      if (typeof details.seekTime === 'number') {
+        this.actions?.seekTo(details.seekTime);
+      }
+    });
+    set('seekbackward', (details) => {
+      this.actions?.seekBackward(details.seekOffset ?? DEFAULT_SEEK_OFFSET_SECONDS);
+    });
+    set('seekforward', (details) => {
+      this.actions?.seekForward(details.seekOffset ?? DEFAULT_SEEK_OFFSET_SECONDS);
+    });
+  }
+}