@stream-io/video-client 1.56.0 → 1.57.0

package/dist/src/helpers/MediaPlaybackWatchdog.d.ts

@@ -18,12 +18,16 @@ export declare class MediaPlaybackWatchdog {
     private tracer;
     private controller;
     private pendingTimer;
+    private settleTimer;
     private attempt;
     private disposed;
+    private stopped;
     constructor(opts: MediaPlaybackWatchdogOptions);
     private attach;
     dispose: () => void;
+    private clearTimers;
     private onPlaying;
+    private onSettled;
     private onPauseOrSuspend;
     private scheduleRecovery;
     private computeSkipReason;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stream-io/video-client",
-  "version": "1.56.0",
+  "version": "1.57.0",
   "main": "dist/index.cjs.js",
   "module": "dist/index.es.js",
   "browser": "dist/index.browser.es.js",
@@ -36,31 +36,31 @@
     "@protobuf-ts/twirp-transport": "^2.11.1",
     "@stream-io/logger": "^2.0.0",
     "@stream-io/worker-timer": "^1.2.5",
-    "axios": "^1.16.1",
+    "axios": "^1.19.0",
     "rxjs": "~7.8.2",
     "sdp-transform": "^2.15.0",
     "ua-parser-js": "^1.0.41",
     "webrtc-adapter": "^8.2.4"
   },
   "devDependencies": {
-    "@openapitools/openapi-generator-cli": "^2.34.0",
+    "@openapitools/openapi-generator-cli": "^2.40.1",
     "@rollup/plugin-replace": "^6.0.3",
     "@rollup/plugin-typescript": "^12.3.0",
-    "@stream-io/audio-filters-web": "^0.10.2",
-    "@stream-io/node-sdk": "^0.7.59",
+    "@stream-io/audio-filters-web": "^0.10.4",
+    "@stream-io/node-sdk": "^0.7.63",
     "@stream-io/typescript-config": "^0.0.0",
     "@total-typescript/shoehorn": "^0.1.2",
-    "@types/node": "^25.9.3",
+    "@types/node": "^25.9.5",
     "@types/sdp-transform": "^2.15.0",
     "@types/ua-parser-js": "^0.7.39",
-    "@vitest/coverage-v8": "^4.1.7",
+    "@vitest/coverage-v8": "^4.1.10",
     "dotenv": "^16.6.1",
-    "happy-dom": "^20.9.0",
-    "prettier": "^3.8.3",
+    "happy-dom": "^20.11.1",
+    "prettier": "^3.9.6",
     "rimraf": "^6.1.3",
-    "rollup": "^4.60.4",
+    "rollup": "^4.62.4",
     "typescript": "^6.0.3",
-    "vitest": "^4.1.7",
+    "vitest": "^4.1.10",
     "vitest-mock-extended": "^4.0.0"
   }
 }

package/src/devices/__tests__/MicrophoneManagerRN.test.ts

@@ -16,8 +16,7 @@ import { settled, withoutConcurrency } from '../../helpers/concurrency';
 import { ClientEventReporter } from '../../reporting';
 
 let speechActivityCallback:
-  | ((state: { isSoundDetected: boolean }) => void)
-  | null = null;
+  ((state: { isSoundDetected: boolean }) => void) | null = null;
 let unsubscribeMocks: ReturnType<typeof vi.fn>[] = [];
 
 vi.mock('../../helpers/platforms.ts', () => {

package/src/devices/devicePersistence.ts

@@ -24,8 +24,7 @@ export type LocalDevicePreference = {
 
 export type LocalDevicePreferences = {
   [type in DevicePreferenceKey]?:
-    | LocalDevicePreference
-    | LocalDevicePreference[];
+    LocalDevicePreference | LocalDevicePreference[];
 };
 
 export const defaultDeviceId = 'default';

package/src/helpers/MediaPlaybackWatchdog.ts

@@ -23,8 +23,10 @@ export class MediaPlaybackWatchdog {
   private tracer: Tracer;
   private controller = new AbortController();
   private pendingTimer: ReturnType<typeof setTimeout> | undefined;
+  private settleTimer: ReturnType<typeof setTimeout> | undefined;
   private attempt = 0;
   private disposed = false;
+  private stopped = false;
 
   constructor(opts: MediaPlaybackWatchdogOptions) {
     this.element = opts.element;
@@ -46,33 +48,47 @@ export class MediaPlaybackWatchdog {
     if (this.disposed) return;
     this.disposed = true;
     this.controller.abort();
+    this.clearTimers();
+  };
+
+  private clearTimers = () => {
     if (this.pendingTimer) clearTimeout(this.pendingTimer);
     this.pendingTimer = undefined;
+    if (this.settleTimer) clearTimeout(this.settleTimer);
+    this.settleTimer = undefined;
   };
 
   private onPlaying = () => {
-    if (this.attempt > 0) {
-      this.tracer.trace('mediaPlayback.recover.success', {
-        kind: this.kind,
-        attempts: this.attempt,
-      });
-    }
-    this.attempt = 0;
     if (this.pendingTimer) clearTimeout(this.pendingTimer);
     this.pendingTimer = undefined;
+    if (this.attempt === 0 || this.settleTimer) return;
+    this.settleTimer ??= setTimeout(this.onSettled, 1000);
+  };
+
+  private onSettled = () => {
+    this.settleTimer = undefined;
+    if (this.element.paused) return;
+    this.tracer.trace('mediaPlayback.recover.success', {
+      kind: this.kind,
+      attempts: this.attempt,
+    });
+    this.attempt = 0;
+    this.stopped = false;
   };
 
   private onPauseOrSuspend = (event: Event) => {
-    if (this.disposed) return;
+    if (this.disposed || this.stopped) return;
     this.tracer.trace('mediaPlayback.paused', {
       kind: this.kind,
       reason: event.type,
     });
+    if (this.settleTimer) clearTimeout(this.settleTimer);
+    this.settleTimer = undefined;
     this.scheduleRecovery();
   };
 
   private scheduleRecovery = () => {
-    if (this.disposed || this.pendingTimer) return;
+    if (this.disposed || this.stopped || this.pendingTimer) return;
     const skipReason = this.computeSkipReason();
     if (skipReason) {
       this.tracer.trace('mediaPlayback.recover.skipped', {
@@ -81,6 +97,16 @@ export class MediaPlaybackWatchdog {
       });
       return;
     }
+
+    if (this.attempt >= 10) {
+      this.stopped = true;
+      this.clearTimers();
+      this.tracer.trace('mediaPlayback.recover.giveUp', {
+        kind: this.kind,
+        attempts: this.attempt,
+      });
+      return;
+    }
     const delay = this.attempt === 0 ? 0 : retryInterval(this.attempt);
     this.pendingTimer = setTimeout(this.attemptPlay, delay);
   };
@@ -109,13 +135,6 @@ export class MediaPlaybackWatchdog {
     } catch (err) {
       if (this.disposed) return;
       this.logger.warn(`Failed to recover ${this.kind} playback`, err);
-      if (this.attempt >= 10) {
-        this.tracer.trace('mediaPlayback.recover.giveUp', {
-          kind: this.kind,
-          attempts: this.attempt,
-        });
-        return;
-      }
       this.scheduleRecovery();
     }
   };

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

@@ -28,20 +28,33 @@ const createMediaElement = (
   state: FakeMediaState = {},
 ) => {
   const el = document.createElement(kind) as HTMLMediaElement;
-  Object.defineProperty(el, 'srcObject', { writable: true });
+  Object.defineProperty(el, 'srcObject', {
+    value: 'srcObject' in state ? state.srcObject : new MediaStream(),
+    writable: true,
+  });
   Object.defineProperty(el, 'paused', { writable: true, configurable: true });
   Object.defineProperty(el, 'readyState', {
+    value: state.readyState ?? 4,
+    writable: true,
+    configurable: true,
+  });
+  Object.defineProperty(el, 'ended', {
+    value: state.ended ?? false,
     writable: true,
     configurable: true,
   });
-  Object.defineProperty(el, 'ended', { writable: true, configurable: true });
-  el.srcObject = 'srcObject' in state ? state.srcObject : new MediaStream();
-  el.paused = state.paused ?? true;
-  el.readyState = state.readyState ?? 4;
-  el.ended = state.ended ?? false;
+  setPaused(el, state.paused ?? true);
   return el;
 };
 
+const setPaused = (el: HTMLMediaElement, paused: boolean) => {
+  Object.defineProperty(el, 'paused', {
+    value: paused,
+    writable: true,
+    configurable: true,
+  });
+};
+
 type SetupOpts = {
   kind?: 'audio' | 'video';
   state?: FakeMediaState;
@@ -111,15 +124,131 @@ describe('MediaPlaybackWatchdog', () => {
     await vi.advanceTimersByTimeAsync(6000);
     expect(play).toHaveBeenCalledTimes(2);
 
-    // Simulate the element actually starting to play.
+    // Simulate the element actually starting to play, and staying up long
+    // enough for the recovery to count as settled.
+    setPaused(el, false);
     el.dispatchEvent(new Event('playing'));
+    await vi.advanceTimersByTimeAsync(1000);
 
-    // A subsequent pause should still trigger a fresh recovery attempt.
+    // A subsequent pause should trigger a fresh, immediate recovery attempt.
+    setPaused(el, true);
     el.dispatchEvent(new Event('pause'));
     await vi.advanceTimersByTimeAsync(0);
     expect(play).toHaveBeenCalledTimes(3);
   });
 
+  it('backs off instead of retrying immediately when playback has not settled', async () => {
+    el.dispatchEvent(new Event('pause'));
+    await vi.advanceTimersByTimeAsync(0);
+    expect(play).toHaveBeenCalledTimes(1);
+
+    // resumed, but re-paused before the settle delay elapsed
+    setPaused(el, false);
+    el.dispatchEvent(new Event('playing'));
+    expect(tracer.trace).not.toHaveBeenCalledWith(
+      'mediaPlayback.recover.success',
+      {
+        kind: 'audio',
+        attempts: 1,
+      },
+    );
+    await vi.advanceTimersByTimeAsync(500);
+    setPaused(el, true);
+    el.dispatchEvent(new Event('pause'));
+
+    // the next attempt is subject to backoff, not scheduled on the next tick
+    await vi.advanceTimersByTimeAsync(0);
+    expect(play).toHaveBeenCalledTimes(1);
+
+    await vi.advanceTimersByTimeAsync(6000);
+    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
+    // reset the attempt counter, so the loop spun with a zero delay forever.
+    play.mockImplementation(async () => {
+      setPaused(el, false);
+      el.dispatchEvent(new Event('playing'));
+      setPaused(el, true);
+      el.dispatchEvent(new Event('pause'));
+    });
+
+    el.dispatchEvent(new Event('pause'));
+    for (let i = 0; i < 20; i++) {
+      await vi.advanceTimersByTimeAsync(6000);
+    }
+
+    expect(play).toHaveBeenCalledTimes(10);
+    expect(tracer.trace).toHaveBeenCalledWith('mediaPlayback.recover.giveUp', {
+      kind: 'video',
+      attempts: 10,
+    });
+
+    // External playback can still emit `playing` after the watchdog gave up
+    // (for example from a user gesture or another playback helper). If it
+    // re-pauses before settling, it must not revive the watchdog or trace a
+    // false recovery success.
+    setPaused(el, false);
+    el.dispatchEvent(new Event('playing'));
+    setPaused(el, true);
+    el.dispatchEvent(new Event('pause'));
+    await vi.advanceTimersByTimeAsync(1000);
+
+    expect(tracer.trace).not.toHaveBeenCalledWith(
+      'mediaPlayback.recover.success',
+      {
+        kind: 'video',
+        attempts: 10,
+      },
+    );
+
+    // and it stays stopped, without tracing the pause storm
+    const traceMock = tracer.trace as unknown as MockInstance;
+    const tracesBefore = traceMock.mock.calls.length;
+    for (let i = 0; i < 100; i++) {
+      el.dispatchEvent(new Event('pause'));
+    }
+    await vi.advanceTimersByTimeAsync(6000);
+
+    expect(play).toHaveBeenCalledTimes(10);
+    expect(traceMock.mock.calls.length).toBe(tracesBefore);
+  });
+
+  it('revives once playback genuinely holds for the settle window', async () => {
+    setup({ kind: 'video' });
+    play.mockImplementation(async () => {
+      setPaused(el, false);
+      el.dispatchEvent(new Event('playing'));
+      setPaused(el, true);
+      el.dispatchEvent(new Event('pause'));
+    });
+
+    el.dispatchEvent(new Event('pause'));
+    for (let i = 0; i < 20; i++) {
+      await vi.advanceTimersByTimeAsync(6000);
+    }
+    expect(play).toHaveBeenCalledTimes(10); // gave up
+
+    play.mockResolvedValue(undefined);
+    setPaused(el, false);
+    el.dispatchEvent(new Event('playing'));
+    await vi.advanceTimersByTimeAsync(1500);
+
+    expect(tracer.trace).toHaveBeenCalledWith('mediaPlayback.recover.success', {
+      kind: 'video',
+      attempts: 10,
+    });
+
+    // recovery is live again: the attempt counter was reset, so a fresh pause
+    // gets an immediate attempt rather than being ignored
+    setPaused(el, true);
+    el.dispatchEvent(new Event('pause'));
+    await vi.advanceTimersByTimeAsync(0);
+    expect(play).toHaveBeenCalledTimes(11);
+  });
+
   it('does not attempt recovery when srcObject is null', async () => {
     setup({ state: { srcObject: null } });
 

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

@@ -38,8 +38,7 @@ describe('ViewportTracker', () => {
 
   it('updates participant viewportVisibilityState as visibility changes', () => {
     let visibilityHandler:
-      | ((entry: IntersectionObserverEntry) => void)
-      | undefined;
+      ((entry: IntersectionObserverEntry) => void) | undefined;
     vi.spyOn(viewportTracker, 'observe').mockImplementation((_el, handler) => {
       visibilityHandler = handler;
       return vi.fn();

package/src/reporting/ClientEventReporter.ts

@@ -33,18 +33,12 @@ export type ClientEventStage =
   | 'FirstAudioFrame';
 
 export type MediaPermissionState =
-  | 'INITIATED'
-  | 'FAILED'
-  | 'GRANTED'
-  | 'NOT_INITIATED';
+  'INITIATED' | 'FAILED' | 'GRANTED' | 'NOT_INITIATED';
 
 export type ReportedIceState = 'CONNECTED' | 'FAILED' | 'NOT_CONNECTED';
 
 export type JoinReason =
-  | 'first-attempt'
-  | 'network-available'
-  | 'migration'
-  | 'full-rejoin';
+  'first-attempt' | 'network-available' | 'migration' | 'full-rejoin';
 
 export type ClientEventStandardCode =
   | 'CLIENT_ABORTED'

package/src/rtc/types.ts

@@ -39,8 +39,7 @@ export const ReconnectReason = {
 } as const;
 
 export type ReconnectReason =
-  | (typeof ReconnectReason)[keyof typeof ReconnectReason]
-  | (string & {});
+  (typeof ReconnectReason)[keyof typeof ReconnectReason] | (string & {});
 
 export type OnReconnectionNeeded = (
   kind: WebsocketReconnectStrategy,

package/src/stats/rtc/types.ts

@@ -12,9 +12,15 @@ export type RTCStatsDataType =
   | boolean
   | RTCOfferOptions
   | [string | RTCDataChannelInit | undefined] // createDataChannel
-  | (RTCOfferOptions | undefined) // createOffer | createAnswer
+  | (
+      | RTCOfferOptions
+      | undefined // createOffer | createAnswer
+    )
   | RTCSessionDescriptionInit
-  | (RTCIceCandidateInit | RTCIceCandidate) // addIceCandidate
+  | (
+      | RTCIceCandidateInit
+      | RTCIceCandidate // addIceCandidate
+    )
   | object
   | number
   | null

package/src/store/CallState.ts

@@ -341,8 +341,7 @@ export class CallState {
 
   private readonly eventHandlers: {
     [EventType in VideoEvent['type']]:
-      | ((event: Extract<VideoEvent, { type: EventType }>) => void)
-      | undefined;
+      ((event: Extract<VideoEvent, { type: EventType }>) => void) | undefined;
   };
 
   /**

package/src/types.ts

@@ -143,10 +143,7 @@ export interface StreamVideoParticipant extends Participant {
 export type VideoTrackType = 'videoTrack' | 'screenShareTrack';
 export type AudioTrackType = 'audioTrack' | 'screenShareAudioTrack';
 export type TrackMuteType =
-  | 'audio'
-  | 'video'
-  | 'screenshare'
-  | 'screenshare_audio';
+  'audio' | 'video' | 'screenshare' | 'screenshare_audio';
 
 /**
  * Represents a participant's pin state.