@stream-io/video-client 1.49.0 → 1.51.0

package/src/rtc/__tests__/Subscriber.test.ts

@@ -28,10 +28,11 @@ vi.mock('../../StreamSfuClient', () => {
 describe('Subscriber', () => {
   let sfuClient: StreamSfuClient;
   let subscriber: Subscriber;
-  const state = new CallState();
+  let state: CallState;
   let dispatcher: Dispatcher;
 
   beforeEach(() => {
+    state = new CallState();
     dispatcher = new Dispatcher();
     sfuClient = new StreamSfuClient({
       dispatcher,
@@ -63,11 +64,11 @@ describe('Subscriber', () => {
     });
   });
 
-  afterEach(() => {
+  afterEach(async () => {
     vi.useRealTimers();
     vi.clearAllMocks();
     vi.resetModules();
-    subscriber.dispose();
+    await subscriber.dispose();
   });
 
   describe('Subscriber ICE restart', () => {
@@ -272,6 +273,150 @@ describe('Subscriber', () => {
     });
   });
 
+  describe('interruptedTracks', () => {
+    const setup = ({ muted = false }: { muted?: boolean } = {}) => {
+      const mediaStream = new MediaStream();
+      const track = new MediaStreamTrack();
+      // @ts-expect-error - mock
+      mediaStream.id = 'lookup:TRACK_TYPE_AUDIO';
+      // @ts-expect-error - mock
+      track.kind = 'audio';
+      Object.defineProperty(track, 'muted', {
+        configurable: true,
+        get: () => muted,
+      });
+      // @ts-expect-error - incomplete mock
+      state.updateOrAddParticipant('session-id', {
+        sessionId: 'session-id',
+        trackLookupPrefix: 'lookup',
+      });
+
+      const onTrack = subscriber['handleOnTrack'];
+      // @ts-expect-error - incomplete mock
+      onTrack({ streams: [mediaStream], track });
+
+      const calls = (track.addEventListener as ReturnType<typeof vi.fn>).mock
+        .calls;
+      const handlers: Record<string, () => void> = {};
+      for (const [event, handler] of calls) {
+        handlers[event] = handler as () => void;
+      }
+      return { track, handlers };
+    };
+
+    const interruptedFor = (sessionId: string) =>
+      state.participants.find((p) => p.sessionId === sessionId)
+        ?.interruptedTracks ?? [];
+
+    it('adds the track type when the mute handler fires', () => {
+      const { handlers } = setup();
+      expect(interruptedFor('session-id')).toEqual([]);
+
+      handlers['mute']();
+
+      expect(interruptedFor('session-id')).toEqual([TrackType.AUDIO]);
+    });
+
+    it('removes the track type when the unmute handler fires', () => {
+      const { handlers } = setup();
+      handlers['mute']();
+      expect(interruptedFor('session-id')).toEqual([TrackType.AUDIO]);
+
+      handlers['unmute']();
+
+      expect(interruptedFor('session-id')).toEqual([]);
+    });
+
+    it('seeds the track type when the track arrives already muted', () => {
+      setup({ muted: true });
+
+      expect(interruptedFor('session-id')).toEqual([TrackType.AUDIO]);
+    });
+
+    it('clears the track type when the track ends', () => {
+      const { handlers } = setup();
+      handlers['mute']();
+      expect(interruptedFor('session-id')).toEqual([TrackType.AUDIO]);
+
+      handlers['ended']();
+
+      expect(interruptedFor('session-id')).toEqual([]);
+    });
+
+    it('ignores non-audio remote tracks to avoid Dynascale false positives', () => {
+      // Remote video track.muted is dominated by viewport-driven
+      // SFU unsubscriptions, so we deliberately only track audio
+      // interruption on remote participants.
+      const mediaStream = new MediaStream();
+      const track = new MediaStreamTrack();
+      // @ts-expect-error - mock
+      mediaStream.id = 'video-lookup:TRACK_TYPE_VIDEO';
+      // @ts-expect-error - mock
+      track.kind = 'video';
+      Object.defineProperty(track, 'muted', {
+        configurable: true,
+        get: () => true,
+      });
+      // @ts-expect-error - incomplete mock
+      state.updateOrAddParticipant('video-session', {
+        sessionId: 'video-session',
+        trackLookupPrefix: 'video-lookup',
+      });
+
+      const onTrack = subscriber['handleOnTrack'];
+      // @ts-expect-error - incomplete mock
+      onTrack({ streams: [mediaStream], track });
+
+      // Seeded muted track is ignored.
+      expect(interruptedFor('video-session')).toEqual([]);
+
+      // Subsequent mute / unmute events are ignored too.
+      const calls = (track.addEventListener as ReturnType<typeof vi.fn>).mock
+        .calls;
+      const handlers: Record<string, () => void> = {};
+      for (const [event, handler] of calls) {
+        handlers[event] = handler as () => void;
+      }
+      handlers['mute']();
+      handlers['unmute']();
+      expect(interruptedFor('video-session')).toEqual([]);
+    });
+
+    it('does not mutate state for orphaned tracks until associated', () => {
+      const mediaStream = new MediaStream();
+      const track = new MediaStreamTrack();
+      // @ts-expect-error - mock
+      mediaStream.id = 'orphan:TRACK_TYPE_AUDIO';
+      // @ts-expect-error - mock
+      track.kind = 'audio';
+
+      const onTrack = subscriber['handleOnTrack'];
+      // @ts-expect-error - incomplete mock
+      onTrack({ streams: [mediaStream], track });
+
+      const calls = (track.addEventListener as ReturnType<typeof vi.fn>).mock
+        .calls;
+      const handlers: Record<string, () => void> = {};
+      for (const [event, handler] of calls) {
+        handlers[event] = handler as () => void;
+      }
+
+      // Orphan: handler fires before the participant exists.
+      handlers['mute']();
+      expect(state.participants).toEqual([]);
+
+      // Once the participant is registered, the next event lands.
+      // @ts-expect-error - incomplete mock
+      state.updateOrAddParticipant('orphan-session', {
+        sessionId: 'orphan-session',
+        trackLookupPrefix: 'orphan',
+      });
+      handlers['mute']();
+
+      expect(interruptedFor('orphan-session')).toEqual([TrackType.AUDIO]);
+    });
+  });
+
   describe('Negotiation', () => {
     it('negotiates with the SFU', async () => {
       sfuClient.sendAnswer = vi.fn();

package/src/rtc/__tests__/mocks/webrtc.mocks.ts

@@ -16,8 +16,8 @@ const RTCPeerConnectionMock = vi.fn((): Partial<RTCPeerConnection> => {
     close: vi.fn(),
     connectionState: 'connected',
     signalingState: 'stable',
-    getReceivers: vi.fn(),
-    getSenders: vi.fn(),
+    getReceivers: vi.fn().mockReturnValue([]),
+    getSenders: vi.fn().mockReturnValue([]),
     removeTrack: vi.fn(),
   };
 });
@@ -109,6 +109,16 @@ const AudioContextMock = vi.fn((): Partial<AudioContext> => {
         gain: { value: 1 },
       } as unknown as GainNode;
     }),
+    // Silent keep-alive node used by DynascaleManager's probe AudioContext.
+    createConstantSource: vi.fn(() => {
+      return {
+        offset: { value: 0 },
+        connect: vi.fn((v) => v),
+        disconnect: vi.fn(),
+        start: vi.fn(),
+        stop: vi.fn(),
+      } as unknown as ConstantSourceNode;
+    }),
     close: vi.fn(async function () {
       this.state = 'closed';
     }),
@@ -119,6 +129,7 @@ const AudioContextMock = vi.fn((): Partial<AudioContext> => {
       this.sinkId = sinkId;
     }),
     addEventListener: vi.fn(),
+    removeEventListener: vi.fn(),
   };
 });
 vi.stubGlobal('AudioContext', AudioContextMock);

package/src/rtc/helpers/__tests__/degradationPreference.test.ts

@@ -0,0 +1,55 @@
+import { describe, expect, it } from 'vitest';
+import { DegradationPreference } from '../../../gen/video/sfu/models/models';
+import {
+  fromRTCDegradationPreference,
+  toRTCDegradationPreference,
+} from '../degradationPreference';
+
+describe('toRTCDegradationPreference', () => {
+  it.each([
+    [DegradationPreference.BALANCED, 'balanced'],
+    [DegradationPreference.MAINTAIN_FRAMERATE, 'maintain-framerate'],
+    [DegradationPreference.MAINTAIN_RESOLUTION, 'maintain-resolution'],
+    [
+      DegradationPreference.MAINTAIN_FRAMERATE_AND_RESOLUTION,
+      'maintain-framerate-and-resolution',
+    ],
+  ])('maps %s to "%s"', (preference, expected) => {
+    expect(toRTCDegradationPreference(preference)).toBe(expected);
+  });
+
+  it('returns undefined for UNSPECIFIED', () => {
+    expect(
+      toRTCDegradationPreference(DegradationPreference.UNSPECIFIED),
+    ).toBeUndefined();
+  });
+});
+
+describe('fromRTCDegradationPreference', () => {
+  it.each([
+    ['balanced', DegradationPreference.BALANCED],
+    ['maintain-framerate', DegradationPreference.MAINTAIN_FRAMERATE],
+    ['maintain-resolution', DegradationPreference.MAINTAIN_RESOLUTION],
+    [
+      'maintain-framerate-and-resolution',
+      DegradationPreference.MAINTAIN_FRAMERATE_AND_RESOLUTION,
+    ],
+  ] as const)('maps "%s" to %s', (preference, expected) => {
+    // @ts-expect-error not in the lib types yet
+    expect(fromRTCDegradationPreference(preference)).toBe(expected);
+  });
+
+  it('returns UNSPECIFIED for undefined', () => {
+    expect(fromRTCDegradationPreference(undefined)).toBe(
+      DegradationPreference.UNSPECIFIED,
+    );
+  });
+
+  it('returns UNSPECIFIED for an unknown value', () => {
+    expect(
+      fromRTCDegradationPreference(
+        'something-else' as unknown as RTCDegradationPreference,
+      ),
+    ).toBe(DegradationPreference.UNSPECIFIED);
+  });
+});

package/src/rtc/helpers/degradationPreference.ts

@@ -0,0 +1,40 @@
+import { DegradationPreference } from '../../gen/video/sfu/models/models';
+import { ensureExhausted } from '../../helpers/ensureExhausted';
+
+export const toRTCDegradationPreference = (
+  preference: DegradationPreference,
+): RTCDegradationPreference | undefined => {
+  switch (preference) {
+    case DegradationPreference.BALANCED:
+      return 'balanced';
+    case DegradationPreference.MAINTAIN_FRAMERATE:
+      return 'maintain-framerate';
+    case DegradationPreference.MAINTAIN_RESOLUTION:
+      return 'maintain-resolution';
+    case DegradationPreference.MAINTAIN_FRAMERATE_AND_RESOLUTION:
+      // @ts-expect-error not in the typedefs yet
+      return 'maintain-framerate-and-resolution';
+    case DegradationPreference.UNSPECIFIED:
+      return undefined;
+    default:
+      ensureExhausted(preference, 'Unknown degradation preference');
+  }
+};
+
+export const fromRTCDegradationPreference = (
+  preference: RTCDegradationPreference | undefined,
+): DegradationPreference => {
+  switch (preference) {
+    case 'balanced':
+      return DegradationPreference.BALANCED;
+    case 'maintain-framerate':
+      return DegradationPreference.MAINTAIN_FRAMERATE;
+    case 'maintain-resolution':
+      return DegradationPreference.MAINTAIN_RESOLUTION;
+    // @ts-expect-error not in the typedefs yet
+    case 'maintain-framerate-and-resolution':
+      return DegradationPreference.MAINTAIN_FRAMERATE_AND_RESOLUTION;
+    default:
+      return DegradationPreference.UNSPECIFIED;
+  }
+};

package/src/rtc/types.ts

@@ -9,6 +9,7 @@ import { CallState } from '../store';
 import { Dispatcher } from './Dispatcher';
 import type { OptimalVideoLayer } from './layers';
 import type { ClientPublishOptions } from '../types';
+import type { VideoSender } from '../gen/video/sfu/event/events';
 
 /**
  * Canonical reasons the SDK uses to trigger a reconnection. Free-form strings
@@ -73,6 +74,7 @@ export type PublishBundle = {
   publishOption: PublishOption;
   transceiver: RTCRtpTransceiver;
   options: TrackPublishOptions;
+  videoSender?: VideoSender;
 };
 
 export type TrackLayersCache = {

package/src/stats/rtc/types.ts

@@ -16,6 +16,7 @@ export type RTCStatsDataType =
   | RTCSessionDescriptionInit
   | (RTCIceCandidateInit | RTCIceCandidate) // addIceCandidate
   | object
+  | number
   | null
   | undefined;
 

package/src/store/__tests__/rxUtils.test.ts

@@ -0,0 +1,276 @@
+import { describe, expect, it, vi } from 'vitest';
+import { BehaviorSubject, Subject, throwError } from 'rxjs';
+import { promiseWithResolvers } from '../../helpers/promise';
+import {
+  createSafeAsyncSubscription,
+  createSubscription,
+  getCurrentValue,
+  setCurrentValue,
+  setCurrentValueAsync,
+  updateValue,
+} from '../rxUtils';
+
+describe('getCurrentValue', () => {
+  it('returns the current value of a BehaviorSubject', () => {
+    const subject = new BehaviorSubject(42);
+    expect(getCurrentValue(subject)).toBe(42);
+  });
+
+  it('reflects subsequent emissions', () => {
+    const subject = new BehaviorSubject('a');
+    subject.next('b');
+    expect(getCurrentValue(subject)).toBe('b');
+  });
+
+  it('rethrows errors emitted by the observable', () => {
+    const err = new Error('observable failed');
+    expect(() => getCurrentValue(throwError(() => err))).toThrow(err);
+  });
+});
+
+describe('setCurrentValue', () => {
+  it('sets a plain value and returns it', () => {
+    const subject = new BehaviorSubject(1);
+    const result = setCurrentValue(subject, 5);
+    expect(result).toBe(5);
+    expect(subject.getValue()).toBe(5);
+  });
+
+  it('applies a function patch using the current value', () => {
+    const subject = new BehaviorSubject(10);
+    const result = setCurrentValue(subject, (n) => n * 2);
+    expect(result).toBe(20);
+    expect(subject.getValue()).toBe(20);
+  });
+
+  it('emits the new value to subscribers', () => {
+    const subject = new BehaviorSubject(0);
+    const seen: number[] = [];
+    const sub = subject.subscribe((v) => seen.push(v));
+    setCurrentValue(subject, 1);
+    setCurrentValue(subject, (n) => n + 1);
+    sub.unsubscribe();
+    expect(seen).toEqual([0, 1, 2]);
+  });
+});
+
+describe('setCurrentValueAsync', () => {
+  it('passes the current value to the update fn and emits the resolved value', async () => {
+    const subject = new BehaviorSubject(1);
+    const update = vi.fn(async (n: number) => n + 1);
+
+    const result = await setCurrentValueAsync(subject, update);
+
+    expect(update).toHaveBeenCalledWith(1);
+    expect(result).toBe(2);
+    expect(subject.getValue()).toBe(2);
+  });
+
+  it('serializes concurrent calls on the same subject so each sees the previous result', async () => {
+    const subject = new BehaviorSubject(0);
+    const observed: number[] = [];
+
+    const append = (delay: number) =>
+      setCurrentValueAsync(subject, async (n) => {
+        observed.push(n);
+        await new Promise((r) => setTimeout(r, delay));
+        return n + 1;
+      });
+
+    const [a, b, c] = await Promise.all([append(10), append(0), append(0)]);
+
+    expect(observed).toEqual([0, 1, 2]);
+    expect([a, b, c]).toEqual([1, 2, 3]);
+    expect(subject.getValue()).toBe(3);
+  });
+
+  it('does not block updates on a different subject', async () => {
+    const a = new BehaviorSubject('a-0');
+    const b = new BehaviorSubject('b-0');
+
+    const gate = promiseWithResolvers();
+
+    const aPending = setCurrentValueAsync(a, async (v) => {
+      await gate.promise;
+      return `${v}-done`;
+    });
+    const bDone = await setCurrentValueAsync(b, async (v) => `${v}-done`);
+
+    expect(bDone).toBe('b-0-done');
+    expect(b.getValue()).toBe('b-0-done');
+
+    gate.resolve();
+    await expect(aPending).resolves.toBe('a-0-done');
+    expect(a.getValue()).toBe('a-0-done');
+  });
+
+  it('propagates rejections without emitting and keeps the prior value', async () => {
+    const subject = new BehaviorSubject(7);
+    const emitted: number[] = [];
+    const sub = subject.subscribe((v) => emitted.push(v));
+
+    const boom = new Error('boom');
+    await expect(
+      setCurrentValueAsync(subject, async () => {
+        throw boom;
+      }),
+    ).rejects.toBe(boom);
+
+    expect(subject.getValue()).toBe(7);
+    // Only the initial replay from the BehaviorSubject, no second emission.
+    expect(emitted).toEqual([7]);
+    sub.unsubscribe();
+  });
+
+  it('continues to process queued updates after a rejection', async () => {
+    const subject = new BehaviorSubject(0);
+
+    const failing = setCurrentValueAsync(subject, async () => {
+      throw new Error('nope');
+    });
+    const succeeding = setCurrentValueAsync(subject, async (n) => n + 5);
+
+    await expect(failing).rejects.toThrow('nope');
+    await expect(succeeding).resolves.toBe(5);
+    expect(subject.getValue()).toBe(5);
+  });
+});
+
+describe('updateValue', () => {
+  it('returns the previous and new values', () => {
+    const subject = new BehaviorSubject(1);
+    const { lastValue, value } = updateValue(subject, 2);
+    expect(lastValue).toBe(1);
+    expect(value).toBe(2);
+    expect(subject.getValue()).toBe(2);
+  });
+
+  it('rollback restores the previous value', () => {
+    const subject = new BehaviorSubject({ count: 3 });
+    const prior = subject.getValue();
+
+    const { rollback } = updateValue(subject, { count: 99 });
+    expect(subject.getValue()).toEqual({ count: 99 });
+
+    rollback();
+    expect(subject.getValue()).toBe(prior);
+  });
+
+  it('accepts a function patch', () => {
+    const subject = new BehaviorSubject(10);
+    const { value } = updateValue(subject, (n) => n + 5);
+    expect(value).toBe(15);
+    expect(subject.getValue()).toBe(15);
+  });
+});
+
+describe('createSubscription', () => {
+  it('invokes the handler with every emitted value', () => {
+    const subject = new Subject<number>();
+    const handler = vi.fn();
+    const unsubscribe = createSubscription(subject, handler);
+
+    subject.next(1);
+    subject.next(2);
+    unsubscribe();
+
+    expect(handler).toHaveBeenCalledTimes(2);
+    expect(handler).toHaveBeenNthCalledWith(1, 1);
+    expect(handler).toHaveBeenNthCalledWith(2, 2);
+  });
+
+  it('stops receiving values after unsubscribe is called', () => {
+    const subject = new Subject<number>();
+    const handler = vi.fn();
+    const unsubscribe = createSubscription(subject, handler);
+
+    subject.next(1);
+    unsubscribe();
+    subject.next(2);
+
+    expect(handler).toHaveBeenCalledTimes(1);
+    expect(handler).toHaveBeenCalledWith(1);
+  });
+
+  it('routes errors to the provided onError handler', () => {
+    const err = new Error('observable failed');
+    const onError = vi.fn();
+    createSubscription(
+      throwError(() => err),
+      vi.fn(),
+      onError,
+    );
+    expect(onError).toHaveBeenCalledWith(err);
+  });
+
+  it('swallows errors via the default onError when none is provided', () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+
+    expect(() =>
+      createSubscription(
+        throwError(() => new Error('boom')),
+        vi.fn(),
+      ),
+    ).not.toThrow();
+    expect(warn).toHaveBeenCalled();
+
+    warn.mockRestore();
+  });
+});
+
+describe('createSafeAsyncSubscription', () => {
+  it('runs the async handler for each emission', async () => {
+    const subject = new Subject<number>();
+    const handler = vi.fn(async () => {});
+    const unsubscribe = createSafeAsyncSubscription(subject, handler);
+
+    subject.next(1);
+    subject.next(2);
+    await new Promise((r) => setTimeout(r, 0));
+
+    expect(handler).toHaveBeenCalledTimes(2);
+    expect(handler).toHaveBeenNthCalledWith(1, 1);
+    expect(handler).toHaveBeenNthCalledWith(2, 2);
+    unsubscribe();
+  });
+
+  it('serializes handlers so a slow one blocks the next', async () => {
+    const subject = new Subject<number>();
+    const events: string[] = [];
+    const gate = promiseWithResolvers();
+
+    const unsubscribe = createSafeAsyncSubscription(subject, async (v) => {
+      events.push(`start:${v}`);
+      if (v === 1) await gate.promise;
+      events.push(`end:${v}`);
+    });
+
+    subject.next(1);
+    subject.next(2);
+    await new Promise((r) => setTimeout(r, 0));
+
+    // Second handler hasn't started yet because the first is still in-flight.
+    expect(events).toEqual(['start:1']);
+
+    gate.resolve();
+    await new Promise((r) => setTimeout(r, 0));
+    await new Promise((r) => setTimeout(r, 0));
+
+    expect(events).toEqual(['start:1', 'end:1', 'start:2', 'end:2']);
+    unsubscribe();
+  });
+
+  it('stops invoking the handler after unsubscribe', async () => {
+    const subject = new Subject<number>();
+    const handler = vi.fn(async () => {});
+    const unsubscribe = createSafeAsyncSubscription(subject, handler);
+
+    subject.next(1);
+    unsubscribe();
+    subject.next(2);
+    await new Promise((r) => setTimeout(r, 0));
+
+    expect(handler).toHaveBeenCalledTimes(1);
+    expect(handler).toHaveBeenCalledWith(1);
+  });
+});

package/src/store/rxUtils.ts

@@ -3,6 +3,7 @@ import { withoutConcurrency } from '../helpers/concurrency';
 import { videoLoggerSystem } from '../logger';
 
 type FunctionPatch<T> = (currentValue: T) => T;
+type AsyncFunctionPatch<T> = (currentValue: T) => Promise<T>;
 
 /**
  * A value or a function which takes the current value and returns a new value.
@@ -59,6 +60,24 @@ export const setCurrentValue = <T>(subject: Subject<T>, update: Patch<T>) => {
   return next;
 };
 
+/**
+ * Updates the value of the provided Subject asynchronously.
+ * Locks the subject to prevent concurrent updates.
+ *
+ * @param subject the subject to update.
+ * @param update the update to apply to the subject.
+ */
+export const setCurrentValueAsync = async <T>(
+  subject: Subject<T>,
+  update: AsyncFunctionPatch<T>,
+) => {
+  return withoutConcurrency(subject, async () => {
+    const next = await update(getCurrentValue(subject));
+    subject.next(next);
+    return next;
+  });
+};
+
 /**
  * Updates the value of the provided Subject and returns the previous value
  * and a function to roll back the update.

package/src/types.ts

@@ -90,6 +90,25 @@ export interface StreamVideoParticipant extends Participant {
    */
   pausedTracks?: TrackType[];
 
+  /**
+   * The list of tracks that are currently not producing media.
+   *
+   * For remote participants this is currently surfaced for `TrackType.AUDIO`
+   * only and reflects the receiver-side `RTCRtpReceiver` track `mute`/`unmute`
+   * state, so it covers system mute on the sender (OS audio session
+   * interruption, etc.), the sender pausing its track, sustained RTP stalls,
+   * and SFU drops. Remote video and screen-share interruption is not tracked.
+   *
+   * For the local participant it reflects the local track `mute`/`unmute`
+   * events surfaced by the browser (e.g. bluetooth disconnect, OS-level
+   * mic/camera kill switch, iOS audio session interruption).
+   *
+   * Orthogonal to `publishedTracks`: a track can be in `publishedTracks`
+   * AND in `interruptedTracks` (the participant intends to publish, but
+   * no media is flowing right now).
+   */
+  interruptedTracks?: TrackType[];
+
   /**
    * True if the participant is the local participant.
    */