@stream-io/video-client 1.61.1 → 1.62.0

package/src/helpers/__tests__/DynascaleManager.test.ts

@@ -29,6 +29,7 @@ vi.mock(import('../browsers'), async (importOriginal) => {
   return {
     ...module,
     isSafari: () => globalThis._isSafari ?? false,
+    isWebKit: () => false,
   };
 });
 
@@ -191,6 +192,9 @@ describe('DynascaleManager', () => {
     it('audio: Safari should use AudioContext for audio playback', () => {
       globalThis._isSafari = true;
       dynascaleManager.setUseWebAudio(true); // enabled by default on Safari
+      Object.defineProperty(call.speaker.state, 'isDeviceSelectionSupported', {
+        value: false,
+      });
 
       vi.useFakeTimers();
       const audioElement = document.createElement('audio');
@@ -257,11 +261,9 @@ describe('DynascaleManager', () => {
       expect(gainNode.connect).toHaveBeenCalledWith(audioContext.destination);
 
       call.speaker.select('different-device-id');
-      expect(audioElement.setSinkId).toHaveBeenCalledWith(
-        'different-device-id',
-      );
+      expect(audioElement.setSinkId).not.toHaveBeenCalled();
       // @ts-expect-error sinkId isn't available in the TS definition
-      expect(audioContext.sinkId).toBe('different-device-id');
+      expect(audioContext.sinkId).not.toBe('different-device-id');
 
       call.speaker.setVolume(0.5);
       expect(audioElement.volume).toBe(0.5);
@@ -812,6 +814,247 @@ describe('DynascaleManager', () => {
       cleanup?.();
     });
 
+    describe('audio: playback recovery', () => {
+      const bindPausedAudioElement = (
+        opts: { blockedByAutoplay?: boolean } = {},
+      ) => {
+        const audioElement = document.createElement('audio');
+        Object.defineProperties(audioElement, {
+          srcObject: { writable: true },
+          paused: { writable: true, configurable: true },
+          readyState: { writable: true, configurable: true },
+        });
+        // @ts-expect-error simulate paused, ready-to-play element
+        audioElement.paused = true;
+        // @ts-expect-error simulate paused, ready-to-play element
+        audioElement.readyState = 4;
+        const play = vi.spyOn(audioElement, 'play');
+        if (opts.blockedByAutoplay) {
+          play.mockRejectedValue(new DOMException('', 'NotAllowedError'));
+        }
+
+        // @ts-expect-error incomplete data
+        call.state.updateOrAddParticipant('session-id', {
+          userId: 'user-id',
+          sessionId: 'session-id',
+          publishedTracks: [],
+        });
+        const cleanup = dynascaleManager.bindAudioElement(
+          audioElement,
+          'session-id',
+          'audioTrack',
+        );
+        call.state.updateParticipant('session-id', {
+          audioStream: new MediaStream(),
+        });
+        vi.runAllTimers();
+        return { audioElement, play, cleanup };
+      };
+
+      const setVisibility = (state: DocumentVisibilityState) => {
+        Object.defineProperty(document, 'visibilityState', {
+          configurable: true,
+          get: () => state,
+        });
+        document.dispatchEvent(new Event('visibilitychange'));
+      };
+
+      afterEach(() => {
+        // @ts-expect-error restore the prototype getter
+        delete document.visibilityState;
+      });
+
+      it('marks the element as blocked once recovery gives up', async () => {
+        vi.useFakeTimers();
+        setVisibility('visible');
+        const { audioElement, play, cleanup } = bindPausedAudioElement();
+        play.mockRejectedValue(new Error('playback failed'));
+        await vi.advanceTimersByTimeAsync(0);
+        expect(call.blockedAudioTracker.isBlocked(audioElement)).toBe(false);
+
+        audioElement.dispatchEvent(new Event('pause'));
+        for (let i = 0; i < 20; i++) {
+          await vi.advanceTimersByTimeAsync(6000);
+        }
+
+        expect(call.blockedAudioTracker.isBlocked(audioElement)).toBe(true);
+        expect(
+          getCurrentValue(call.blockedAudioTracker.blockedSessionIds$),
+        ).toEqual(['session-id']);
+
+        cleanup?.();
+      });
+
+      it('keeps retrying when the first re-armed attempt after a give-up fails', async () => {
+        vi.useFakeTimers();
+        setVisibility('visible');
+        const { audioElement, play, cleanup } = bindPausedAudioElement();
+        play.mockRejectedValue(new Error('playback failed'));
+        await vi.advanceTimersByTimeAsync(0);
+        audioElement.dispatchEvent(new Event('pause'));
+        for (let i = 0; i < 20; i++) {
+          await vi.advanceTimersByTimeAsync(6000);
+        }
+        expect(call.blockedAudioTracker.isBlocked(audioElement)).toBe(true);
+        const callsBeforeRearm = play.mock.calls.length;
+
+        play.mockRejectedValueOnce(new Error('still interrupted'));
+        play.mockResolvedValue();
+        setVisibility('hidden');
+        setVisibility('visible');
+        await vi.advanceTimersByTimeAsync(6000);
+
+        expect(play.mock.calls.length).toBe(callsBeforeRearm + 2);
+        // the prompt stays up until audio actually plays
+        expect(call.blockedAudioTracker.isBlocked(audioElement)).toBe(true);
+        audioElement.dispatchEvent(new Event('playing'));
+        expect(call.blockedAudioTracker.isBlocked(audioElement)).toBe(false);
+
+        cleanup?.();
+      });
+
+      it('tries an autoplay-blocked element only once per re-arm', async () => {
+        vi.useFakeTimers();
+        setVisibility('visible');
+        const { audioElement, play, cleanup } = bindPausedAudioElement({
+          blockedByAutoplay: true,
+        });
+        await vi.advanceTimersByTimeAsync(0);
+        expect(call.blockedAudioTracker.isBlocked(audioElement)).toBe(true);
+        const callsBeforeRearm = play.mock.calls.length;
+
+        setVisibility('hidden');
+        setVisibility('visible');
+        for (let i = 0; i < 20; i++) {
+          await vi.advanceTimersByTimeAsync(6000);
+        }
+
+        expect(play.mock.calls.length).toBe(callsBeforeRearm + 1);
+        expect(call.blockedAudioTracker.isBlocked(audioElement)).toBe(true);
+
+        cleanup?.();
+      });
+
+      it('re-plays a paused element when the page becomes visible again', async () => {
+        vi.useFakeTimers();
+        setVisibility('visible');
+        const { play, cleanup } = bindPausedAudioElement();
+        play.mockResolvedValue();
+        await vi.advanceTimersByTimeAsync(0);
+
+        setVisibility('hidden');
+        await vi.advanceTimersByTimeAsync(0);
+        const callsWhileHidden = play.mock.calls.length;
+
+        setVisibility('visible');
+        await vi.advanceTimersByTimeAsync(0);
+
+        expect(play.mock.calls.length).toBe(callsWhileHidden + 1);
+
+        cleanup?.();
+      });
+
+      it('does not apply a queued source change after the element is unbound', async () => {
+        vi.useFakeTimers();
+        setVisibility('visible');
+        const audioElement = document.createElement('audio');
+        Object.defineProperties(audioElement, {
+          srcObject: { writable: true },
+          paused: { writable: true, configurable: true },
+          readyState: { writable: true, configurable: true },
+        });
+        // @ts-expect-error simulate paused, ready-to-play element
+        audioElement.paused = true;
+        // @ts-expect-error simulate paused, ready-to-play element
+        audioElement.readyState = 4;
+        const play = vi.spyOn(audioElement, 'play').mockResolvedValue();
+
+        // @ts-expect-error incomplete data
+        call.state.updateOrAddParticipant('session-id', {
+          userId: 'user-id',
+          sessionId: 'session-id',
+          publishedTracks: [],
+        });
+        const cleanup = dynascaleManager.bindAudioElement(
+          audioElement,
+          'session-id',
+          'audioTrack',
+        );
+        call.state.updateParticipant('session-id', {
+          audioStream: new MediaStream(),
+        });
+        cleanup?.();
+        await vi.runAllTimersAsync();
+
+        expect(audioElement.srcObject).toBeNull();
+        expect(play).not.toHaveBeenCalled();
+
+        setVisibility('hidden');
+        setVisibility('visible');
+        await vi.advanceTimersByTimeAsync(0);
+        expect(play).not.toHaveBeenCalled();
+      });
+
+      it('stops re-arming after the element is unbound', async () => {
+        vi.useFakeTimers();
+        setVisibility('visible');
+        const { play, cleanup } = bindPausedAudioElement();
+        play.mockResolvedValue();
+        await vi.advanceTimersByTimeAsync(0);
+        cleanup?.();
+        const callsAfterCleanup = play.mock.calls.length;
+
+        setVisibility('hidden');
+        setVisibility('visible');
+        await vi.advanceTimersByTimeAsync(0);
+
+        expect(play.mock.calls.length).toBe(callsAfterCleanup);
+      });
+    });
+
+    it('audio: registers one audioSession listener and removes it on dispose', async () => {
+      vi.useFakeTimers();
+      const session = new EventTarget();
+      Object.defineProperty(session, 'state', { value: 'active' });
+      Object.defineProperty(navigator, 'audioSession', {
+        configurable: true,
+        value: session,
+      });
+      const addListener = vi.spyOn(session, 'addEventListener');
+      const removeListener = vi.spyOn(session, 'removeEventListener');
+
+      try {
+        // @ts-expect-error incomplete data
+        call.state.updateOrAddParticipant('session-id', {
+          userId: 'user-id',
+          sessionId: 'session-id',
+          publishedTracks: [],
+        });
+        const cleanups = [
+          dynascaleManager.bindAudioElement(
+            document.createElement('audio'),
+            'session-id',
+            'audioTrack',
+          ),
+          dynascaleManager.bindAudioElement(
+            document.createElement('audio'),
+            'session-id',
+            'screenShareAudioTrack',
+          ),
+        ];
+        expect(addListener).toHaveBeenCalledTimes(1);
+        const [, listener] = addListener.mock.calls[0];
+
+        await dynascaleManager.dispose();
+        expect(removeListener).toHaveBeenCalledWith('statechange', listener);
+
+        cleanups.forEach((cleanup) => cleanup?.());
+      } finally {
+        // @ts-expect-error remove the test double
+        delete navigator.audioSession;
+      }
+    });
+
     it('audio: no watchdog attached when useWebAudio is true', async () => {
       globalThis._isSafari = true;
       dynascaleManager.setUseWebAudio(true);
@@ -867,9 +1110,9 @@ describe('DynascaleManager', () => {
       audioElement.paused = true;
       // @ts-expect-error simulate paused, ready-to-play element
       audioElement.readyState = 4;
-      vi.spyOn(audioElement, 'play').mockRejectedValue(
-        new DOMException('', 'NotAllowedError'),
-      );
+      const play = vi
+        .spyOn(audioElement, 'play')
+        .mockRejectedValue(new DOMException('', 'NotAllowedError'));
 
       // @ts-expect-error incomplete data
       call.state.updateOrAddParticipant('session-id', {
@@ -892,14 +1135,11 @@ describe('DynascaleManager', () => {
 
       expect(call.blockedAudioTracker.isBlocked(audioElement)).toBe(true);
 
-      const traceSpy = vi.spyOn(call.tracer, 'trace');
+      play.mockClear();
       audioElement.dispatchEvent(new Event('pause'));
-      await vi.advanceTimersByTimeAsync(0);
+      await vi.advanceTimersByTimeAsync(60_000);
 
-      expect(traceSpy).toHaveBeenCalledWith('mediaPlayback.recover.skipped', {
-        kind: 'audio',
-        reason: 'blocked',
-      });
+      expect(play).not.toHaveBeenCalled();
 
       cleanup?.();
     });

package/src/helpers/__tests__/MediaPlaybackWatchdog.test.ts

@@ -59,6 +59,7 @@ type SetupOpts = {
   kind?: 'audio' | 'video';
   state?: FakeMediaState;
   isBlocked?: () => boolean;
+  onGiveUp?: () => void;
 };
 
 describe('MediaPlaybackWatchdog', () => {
@@ -77,6 +78,7 @@ describe('MediaPlaybackWatchdog', () => {
       kind,
       tracer,
       isBlocked: opts.isBlocked,
+      onGiveUp: opts.onGiveUp,
     });
   };
 
@@ -164,6 +166,24 @@ describe('MediaPlaybackWatchdog', () => {
     expect(play).toHaveBeenCalledTimes(2);
   });
 
+  it('keeps the settle window running through a routine suspend', async () => {
+    el.dispatchEvent(new Event('pause'));
+    await vi.advanceTimersByTimeAsync(0);
+    expect(play).toHaveBeenCalledTimes(1);
+
+    setPaused(el, false);
+    el.dispatchEvent(new Event('playing'));
+    await vi.advanceTimersByTimeAsync(500);
+    el.dispatchEvent(new Event('suspend'));
+    await vi.advanceTimersByTimeAsync(500);
+
+    // settled, so the next pause recovers immediately instead of backing off
+    setPaused(el, true);
+    el.dispatchEvent(new Event('pause'));
+    await vi.advanceTimersByTimeAsync(0);
+    expect(play).toHaveBeenCalledTimes(2);
+  });
+
   it('stops fighting an element that re-pauses after every successful play', async () => {
     setup({ kind: 'video' });
     // Safari re-pauses the element right after play() resolves. This used to
@@ -297,6 +317,126 @@ describe('MediaPlaybackWatchdog', () => {
     expect(play).not.toHaveBeenCalled();
   });
 
+  it('calls onGiveUp once when the attempts are exhausted', async () => {
+    const onGiveUp = vi.fn();
+    setup({ onGiveUp });
+    play.mockRejectedValue(new Error('nope'));
+
+    el.dispatchEvent(new Event('pause'));
+    for (let i = 0; i < 20; i++) {
+      await vi.advanceTimersByTimeAsync(6000);
+    }
+    el.dispatchEvent(new Event('pause'));
+    await vi.advanceTimersByTimeAsync(6000);
+
+    expect(play).toHaveBeenCalledTimes(10);
+    expect(onGiveUp).toHaveBeenCalledTimes(1);
+  });
+
+  it('does not call onGiveUp when playback recovers', async () => {
+    const onGiveUp = vi.fn();
+    setup({ onGiveUp });
+
+    el.dispatchEvent(new Event('pause'));
+    for (let i = 0; i < 20; i++) {
+      await vi.advanceTimersByTimeAsync(6000);
+    }
+
+    expect(play).toHaveBeenCalledTimes(1);
+    expect(onGiveUp).not.toHaveBeenCalled();
+  });
+
+  describe('rearm', () => {
+    it('restarts recovery with a fresh budget after giving up', async () => {
+      play.mockRejectedValue(new Error('nope'));
+      el.dispatchEvent(new Event('pause'));
+      for (let i = 0; i < 20; i++) {
+        await vi.advanceTimersByTimeAsync(6000);
+      }
+      expect(play).toHaveBeenCalledTimes(10);
+
+      watchdog.rearm();
+      await vi.advanceTimersByTimeAsync(0);
+      expect(play).toHaveBeenCalledTimes(11);
+
+      for (let i = 0; i < 20; i++) {
+        await vi.advanceTimersByTimeAsync(6000);
+      }
+      expect(play).toHaveBeenCalledTimes(20);
+    });
+
+    it('tries an element that regular recovery skips as blocked', async () => {
+      setup({ isBlocked: () => true });
+
+      el.dispatchEvent(new Event('pause'));
+      await vi.advanceTimersByTimeAsync(6000);
+      expect(play).not.toHaveBeenCalled();
+
+      watchdog.rearm();
+      await vi.advanceTimersByTimeAsync(0);
+      expect(play).toHaveBeenCalledTimes(1);
+    });
+
+    it('tries an element that regular recovery skips as not ready', async () => {
+      setup({ state: { readyState: 0 } });
+
+      watchdog.rearm();
+      await vi.advanceTimersByTimeAsync(0);
+
+      expect(play).toHaveBeenCalledTimes(1);
+    });
+
+    it('replaces a pending backoff retry with an immediate attempt', async () => {
+      play.mockRejectedValueOnce(new Error('fail-1'));
+      el.dispatchEvent(new Event('pause'));
+      await vi.advanceTimersByTimeAsync(0);
+      expect(play).toHaveBeenCalledTimes(1);
+
+      watchdog.rearm();
+      await vi.advanceTimersByTimeAsync(0);
+      expect(play).toHaveBeenCalledTimes(2);
+
+      await vi.advanceTimersByTimeAsync(6000);
+      expect(play).toHaveBeenCalledTimes(2);
+    });
+
+    it('does nothing when the element is playing', async () => {
+      setup({ state: { paused: false } });
+
+      watchdog.rearm();
+      await vi.advanceTimersByTimeAsync(6000);
+
+      expect(play).not.toHaveBeenCalled();
+    });
+
+    it('does nothing when the element has no source', async () => {
+      setup({ state: { srcObject: null } });
+
+      watchdog.rearm();
+      await vi.advanceTimersByTimeAsync(6000);
+
+      expect(play).not.toHaveBeenCalled();
+    });
+
+    it('does nothing when the element has ended', async () => {
+      setup({ state: { ended: true } });
+
+      watchdog.rearm();
+      await vi.advanceTimersByTimeAsync(6000);
+
+      expect(play).not.toHaveBeenCalled();
+    });
+
+    it('does nothing after dispose', async () => {
+      watchdog.dispose();
+
+      watchdog.rearm();
+      await vi.advanceTimersByTimeAsync(6000);
+
+      expect(play).not.toHaveBeenCalled();
+    });
+  });
+
   it('does not stack timers when pause fires multiple times before the first attempt', async () => {
     el.dispatchEvent(new Event('pause'));
     el.dispatchEvent(new Event('pause'));

package/src/helpers/__tests__/mediaInterruptions.test.ts

@@ -0,0 +1,131 @@
+/**
+ * @vitest-environment happy-dom
+ */
+
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import {
+  isMediaInterrupted,
+  watchMediaInterruptions,
+} from '../mediaInterruptions';
+import type { AudioSessionState } from '../types';
+
+const setVisibility = (state: DocumentVisibilityState) => {
+  Object.defineProperty(document, 'visibilityState', {
+    configurable: true,
+    get: () => state,
+  });
+  document.dispatchEvent(new Event('visibilitychange'));
+};
+
+const installAudioSession = (initial: AudioSessionState) => {
+  const session = Object.assign(new EventTarget(), {
+    type: 'auto',
+    state: initial,
+  });
+  Object.defineProperty(navigator, 'audioSession', {
+    configurable: true,
+    value: session,
+  });
+  return {
+    setState: (state: AudioSessionState) => {
+      session.state = state;
+      session.dispatchEvent(new Event('statechange'));
+    },
+  };
+};
+
+describe('mediaInterruptions', () => {
+  afterEach(() => {
+    // @ts-expect-error restore the prototype getter
+    delete document.visibilityState;
+    // @ts-expect-error remove the test double
+    delete navigator.audioSession;
+  });
+
+  describe('isMediaInterrupted', () => {
+    it('is false while visible without an interrupted audio session', () => {
+      setVisibility('visible');
+      expect(isMediaInterrupted()).toBe(false);
+
+      installAudioSession('active');
+      expect(isMediaInterrupted()).toBe(false);
+    });
+
+    it('is true while the page is hidden', () => {
+      setVisibility('hidden');
+      expect(isMediaInterrupted()).toBe(true);
+    });
+
+    it('is true while the audio session is interrupted', () => {
+      setVisibility('visible');
+      installAudioSession('interrupted');
+      expect(isMediaInterrupted()).toBe(true);
+    });
+  });
+
+  describe('watchMediaInterruptions', () => {
+    it('fires when the page becomes visible again', () => {
+      setVisibility('visible');
+      const onResumed = vi.fn();
+      const stop = watchMediaInterruptions(onResumed);
+
+      setVisibility('hidden');
+      expect(onResumed).not.toHaveBeenCalled();
+      setVisibility('visible');
+      expect(onResumed).toHaveBeenCalledTimes(1);
+
+      stop();
+    });
+
+    it('does not fire on events that do not end an interruption', () => {
+      setVisibility('visible');
+      const onResumed = vi.fn();
+      const stop = watchMediaInterruptions(onResumed);
+
+      setVisibility('visible');
+      setVisibility('visible');
+
+      expect(onResumed).not.toHaveBeenCalled();
+      stop();
+    });
+
+    it('fires when the audio session leaves the interrupted state', () => {
+      setVisibility('visible');
+      const session = installAudioSession('active');
+      const onResumed = vi.fn();
+      const stop = watchMediaInterruptions(onResumed);
+
+      session.setState('interrupted');
+      expect(onResumed).not.toHaveBeenCalled();
+      session.setState('active');
+      expect(onResumed).toHaveBeenCalledTimes(1);
+
+      stop();
+    });
+
+    it('waits until both the page is visible and the session is no longer interrupted', () => {
+      setVisibility('hidden');
+      const session = installAudioSession('interrupted');
+      const onResumed = vi.fn();
+      const stop = watchMediaInterruptions(onResumed);
+
+      session.setState('active');
+      expect(onResumed).not.toHaveBeenCalled();
+      setVisibility('visible');
+      expect(onResumed).toHaveBeenCalledTimes(1);
+
+      stop();
+    });
+
+    it('stops firing once the returned cleanup is called', () => {
+      setVisibility('hidden');
+      const onResumed = vi.fn();
+      const stop = watchMediaInterruptions(onResumed);
+
+      stop();
+      setVisibility('visible');
+
+      expect(onResumed).not.toHaveBeenCalled();
+    });
+  });
+});

package/src/helpers/mediaInterruptions.ts

@@ -0,0 +1,37 @@
+/**
+ * Checks whether media playback and capture are likely interrupted: the page
+ * is hidden, or WebKit reports the audio session as interrupted (a phone
+ * call, Siri, or another app taking over audio).
+ */
+export const isMediaInterrupted = (): boolean => {
+  if (typeof document === 'undefined') return false;
+  return (
+    document.visibilityState === 'hidden' ||
+    navigator.audioSession?.state === 'interrupted'
+  );
+};
+
+/**
+ * Invokes `onResumed` every time the page leaves a media interruption,
+ * as defined by {@link isMediaInterrupted}.
+ *
+ * @param onResumed the callback to invoke.
+ * @returns a function that stops watching.
+ */
+export const watchMediaInterruptions = (
+  onResumed: () => void,
+): (() => void) => {
+  if (typeof document === 'undefined') return () => {};
+  let interrupted = isMediaInterrupted();
+  const check = () => {
+    const wasInterrupted = interrupted;
+    interrupted = isMediaInterrupted();
+    if (wasInterrupted && !interrupted) onResumed();
+  };
+
+  const controller = new AbortController();
+  const { signal } = controller;
+  document.addEventListener('visibilitychange', check, { signal });
+  navigator.audioSession?.addEventListener('statechange', check, { signal });
+  return () => controller.abort();
+};

package/src/reporting/ClientEventReporter.ts

@@ -48,7 +48,7 @@ export type JoinReason =
 /**
  * What triggered an automatic join, reported as `source` on the call's
  * CoordinatorJoin events. `ring-ws` is a ring WebSocket event, `ring-poll-api`
- * is the ring state poller.
+ * is the ring state poller, or the call refresh after a WS reconnect.
  */
 export type JoinSource = 'ring-ws' | 'ring-poll-api';
 

package/src/ringing/RingStatePoller.ts

@@ -39,7 +39,7 @@ export class RingStatePoller {
 
   constructor(call: Call, options: RingStatePollingOptions = {}) {
     this.call = call;
-    this.startAfterMs = options.startAfterMs ?? 15_000;
+    this.startAfterMs = options.startAfterMs ?? 9_000;
     this.intervalMs = options.intervalMs ?? 5_000;
   }
 

package/src/ringing/__tests__/RingStatePoller.test.ts

@@ -15,7 +15,7 @@ import {
 import type { GetCallRingStateResponse } from '../../gen/coordinator';
 
 const SESSION_ID = 'session-1';
-const START_AFTER_MS = 15_000;
+const START_AFTER_MS = 9_000;
 const INTERVAL_MS = 5_000;
 
 const ringState = (