@stream-io/video-client 1.50.0 → 1.52.0

package/dist/src/stats/rtc/StatsTracer.d.ts

@@ -12,6 +12,7 @@ export declare class StatsTracer {
     private readonly pc;
     private readonly peerType;
     private readonly trackIdToTrackType;
+    private readonly driftThresholdMs;
     private costOverrides?;
     private previousStats;
     private frameTimeHistory;
@@ -19,7 +20,7 @@ export declare class StatsTracer {
     /**
      * Creates a new StatsTracer instance.
      */
-    constructor(pc: RTCPeerConnection, peerType: PeerType, trackIdToTrackType: Map<string, TrackType>);
+    constructor(pc: RTCPeerConnection, peerType: PeerType, trackIdToTrackType: Map<string, TrackType>, statsTimestampDriftThresholdMs?: number);
     /**
      * Get the stats from the RTCPeerConnection.
      * When called, it will return the stats for the current connection.

package/dist/src/stats/utils.d.ts

@@ -23,6 +23,7 @@ export declare const getSdkSignature: (clientDetails: ClientDetails) => {
     os?: import("../gen/video/sfu/models/models").OS;
     browser?: import("../gen/video/sfu/models/models").Browser;
     device?: import("../gen/video/sfu/models/models").Device;
+    webrtcVersion: string;
     sdkName: string;
     sdkVersion: string;
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stream-io/video-client",
-  "version": "1.50.0",
+  "version": "1.52.0",
   "main": "dist/index.cjs.js",
   "module": "dist/index.es.js",
   "browser": "dist/index.browser.es.js",
@@ -36,29 +36,29 @@
     "@protobuf-ts/twirp-transport": "^2.11.1",
     "@stream-io/logger": "^2.0.0",
     "@stream-io/worker-timer": "^1.2.5",
-    "axios": "^1.12.2",
+    "axios": "^1.16.1",
     "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.25.0",
-    "@rollup/plugin-replace": "^6.0.2",
-    "@rollup/plugin-typescript": "^12.1.4",
-    "@stream-io/audio-filters-web": "^0.8.0",
-    "@stream-io/node-sdk": "^0.7.28",
+    "@openapitools/openapi-generator-cli": "^2.34.0",
+    "@rollup/plugin-replace": "^6.0.3",
+    "@rollup/plugin-typescript": "^12.3.0",
+    "@stream-io/audio-filters-web": "^0.8.2",
+    "@stream-io/node-sdk": "^0.7.59",
     "@total-typescript/shoehorn": "^0.1.2",
     "@types/sdp-transform": "^2.15.0",
     "@types/ua-parser-js": "^0.7.39",
-    "@vitest/coverage-v8": "^3.2.4",
+    "@vitest/coverage-v8": "^4.1.7",
     "dotenv": "^16.6.1",
-    "happy-dom": "^20.0.2",
-    "prettier": "^3.6.2",
-    "rimraf": "^6.0.1",
-    "rollup": "^4.52.4",
+    "happy-dom": "^20.9.0",
+    "prettier": "^3.8.3",
+    "rimraf": "^6.1.3",
+    "rollup": "^4.60.4",
     "typescript": "^5.9.3",
-    "vitest": "^3.2.4",
-    "vitest-mock-extended": "^3.1.0"
+    "vitest": "^4.1.7",
+    "vitest-mock-extended": "^4.0.0"
   }
 }

package/src/Call.ts

@@ -287,6 +287,7 @@ export class Call {
   private statsReportingIntervalInMs: number = 2000;
   private statsReporter?: StatsReporter;
   private sfuStatsReporter?: SfuStatsReporter;
+  private lastStatsOptions?: StatsOptions;
   private dropTimeout: ReturnType<typeof setTimeout> | undefined;
 
   private readonly clientStore: StreamVideoWriteableStateStore;
@@ -736,11 +737,12 @@ export class Call {
       this.sfuStatsReporter?.flush();
       this.sfuStatsReporter?.stop();
       this.sfuStatsReporter = undefined;
+      this.lastStatsOptions = undefined;
 
-      this.subscriber?.dispose();
+      await this.subscriber?.dispose();
       this.subscriber = undefined;
 
-      this.publisher?.dispose();
+      await this.publisher?.dispose();
       this.publisher = undefined;
 
       await this.sfuClient?.leaveAndClose(leaveReason);
@@ -1125,17 +1127,19 @@ export class Call {
     const performingFastReconnect =
       this.reconnectStrategy === WebsocketReconnectStrategy.FAST;
 
-    let statsOptions = this.sfuStatsReporter?.options;
+    let statsOptions = this.lastStatsOptions;
     if (
       !this.credentials ||
       !statsOptions ||
       performingRejoin ||
-      performingMigration
+      performingMigration ||
+      data?.migrating_from
     ) {
       try {
         const joinResponse = await this.doJoinRequest(data);
         this.credentials = joinResponse.credentials;
         statsOptions = joinResponse.stats_options;
+        this.lastStatsOptions = statsOptions;
       } catch (error) {
         // prevent triggering reconnect flow if the state is OFFLINE
         const avoidRestoreState =
@@ -1262,7 +1266,7 @@ export class Call {
       });
     } else {
       const connectionConfig = toRtcConfiguration(this.credentials.ice_servers);
-      this.initPublisherAndSubscriber({
+      await this.initPublisherAndSubscriber({
         sfuClient,
         connectionConfig,
         clientDetails,
@@ -1436,7 +1440,7 @@ export class Call {
    * Initializes the Publisher and Subscriber Peer Connections.
    * @internal
    */
-  private initPublisherAndSubscriber = (opts: {
+  private initPublisherAndSubscriber = async (opts: {
     sfuClient: StreamSfuClient;
     connectionConfig: RTCConfiguration;
     statsOptions: StatsOptions;
@@ -1454,9 +1458,12 @@ export class Call {
       closePreviousInstances,
       unifiedSessionId,
     } = opts;
-    const { enable_rtc_stats: enableTracing } = statsOptions;
+    const {
+      enable_rtc_stats: enableTracing,
+      reporting_interval_ms: reportingIntervalMs,
+    } = statsOptions;
     if (closePreviousInstances && this.subscriber) {
-      this.subscriber.dispose();
+      await this.subscriber.dispose();
     }
     const basePeerConnectionOptions: BasePeerConnectionOpts = {
       sfuClient,
@@ -1465,6 +1472,7 @@ export class Call {
       connectionConfig,
       tag: sfuClient.tag,
       enableTracing,
+      statsTimestampDriftThresholdMs: reportingIntervalMs / 2,
       clientPublishOptions: this.clientPublishOptions,
       onReconnectionNeeded: (kind, reason, peerType) => {
         this.reconnect(kind, reason).catch((err) => {
@@ -1487,7 +1495,7 @@ export class Call {
     const isAnonymous = this.streamClient.user?.type === 'anonymous';
     if (!isAnonymous) {
       if (closePreviousInstances && this.publisher) {
-        this.publisher.dispose();
+        await this.publisher.dispose();
       }
       this.publisher = new Publisher(basePeerConnectionOptions, publishOptions);
     }
@@ -1613,12 +1621,19 @@ export class Call {
     reason: ReconnectReason,
   ): Promise<void> => {
     if (
+      this.state.callingState === CallingState.JOINING ||
       this.state.callingState === CallingState.RECONNECTING ||
       this.state.callingState === CallingState.MIGRATING ||
       this.state.callingState === CallingState.RECONNECTING_FAILED
     )
       return;
 
+    // Drop redundant reconnect calls. If a reconnect is already queued or
+    // running for this Call, that entry will resolve whatever broke;
+    // queueing more entries just replays the full REJOIN cycle (one extra
+    // `POST /join` per entry) once the call is already healthy again.
+    if (hasPending(this.reconnectConcurrencyTag)) return;
+
     return withoutConcurrency(this.reconnectConcurrencyTag, async () => {
       const reconnectStartTime = Date.now();
       this.reconnectStrategy = strategy;
@@ -1881,8 +1896,8 @@ export class Call {
       // the `migrationTask`
       this.state.setCallingState(CallingState.JOINED);
     } finally {
-      currentSubscriber?.dispose();
-      currentPublisher?.dispose();
+      await currentSubscriber?.dispose();
+      await currentPublisher?.dispose();
 
       // and close the previous SFU client, without specifying close code
       currentSfuClient.close(StreamSfuClient.NORMAL_CLOSURE, 'Migrating away');
@@ -2109,7 +2124,7 @@ export class Call {
    */
   stopPublish = async (...trackTypes: TrackType[]) => {
     if (!this.sfuClient || !this.publisher) return;
-    this.publisher.stopTracks(...trackTypes);
+    await this.publisher.stopTracks(...trackTypes);
     await this.updateLocalStreamState(undefined, ...trackTypes);
   };
 

package/src/devices/CameraManager.ts

@@ -176,9 +176,9 @@ export class CameraManager extends DeviceManager<CameraManagerState> {
     return getVideoDevices(this.call.tracer);
   }
 
-  protected override getStream(
+  protected override getResolvedConstraints(
     constraints: MediaTrackConstraints,
-  ): Promise<MediaStream> {
+  ): MediaTrackConstraints {
     constraints.width = this.targetResolution.width;
     constraints.height = this.targetResolution.height;
     // We can't set both device id and facing mode
@@ -192,6 +192,13 @@ export class CameraManager extends DeviceManager<CameraManagerState> {
       constraints.facingMode =
         this.state.direction === 'front' ? 'user' : 'environment';
     }
+
+    return constraints;
+  }
+
+  protected override getStream(
+    constraints: MediaTrackConstraints,
+  ): Promise<MediaStream> {
     return getVideoStream(constraints, this.call.tracer);
   }
 }

package/src/devices/DeviceManager.ts

@@ -1,9 +1,20 @@
-import { combineLatest, firstValueFrom, Observable, pairwise } from 'rxjs';
+import {
+  BehaviorSubject,
+  combineLatest,
+  firstValueFrom,
+  map,
+  Observable,
+  pairwise,
+} from 'rxjs';
 import { Call } from '../Call';
 import type { DeviceDisconnectedEvent } from '../coordinator/connection/types';
 import { TrackPublishOptions } from '../rtc';
 import { CallingState } from '../store';
-import { createSubscription, getCurrentValue } from '../store/rxUtils';
+import {
+  createSubscription,
+  getCurrentValue,
+  setCurrentValue,
+} from '../store/rxUtils';
 import {
   DeviceManagerState,
   type InputDeviceStatus,
@@ -35,6 +46,13 @@ import {
   toPreferenceList,
   writePreferences,
 } from './devicePersistence';
+import {
+  ActiveVirtualSession,
+  VirtualDevice,
+  VirtualDeviceEntry,
+  VirtualDeviceHandle,
+} from './VirtualDevice';
+import { generateUUIDv4 } from '../coordinator/connection/utils';
 
 export abstract class DeviceManager<
   S extends DeviceManagerState<C>,
@@ -56,6 +74,11 @@ export abstract class DeviceManager<
   protected areSubscriptionsSetUp = false;
   private isTrackStoppedDueToTrackEnd = false;
   private filters: MediaStreamFilterEntry[] = [];
+  private virtualDevicesSubject = new BehaviorSubject<VirtualDeviceEntry<C>[]>(
+    [],
+  );
+  private activeVirtualSession: ActiveVirtualSession | undefined;
+  private virtualDeviceConcurrencyTag = Symbol('virtualDeviceConcurrencyTag');
   private statusChangeConcurrencyTag = Symbol('statusChangeConcurrencyTag');
   private filterRegistrationConcurrencyTag = Symbol(
     'filterRegistrationConcurrencyTag',
@@ -119,8 +142,119 @@ export abstract class DeviceManager<
    *
    * @returns an Observable that will be updated if a device is connected or disconnected
    */
-  listDevices() {
-    return this.getDevices();
+  listDevices(): Observable<MediaDeviceInfo[]> {
+    return combineLatest([this.getDevices(), this.virtualDevicesSubject]).pipe(
+      map(([real, virtual]) => [
+        ...real,
+        ...virtual.map((d) =>
+          createSyntheticDevice(d.deviceId, d.kind, d.label),
+        ),
+      ]),
+    );
+  }
+
+  /**
+   * Registers a virtual camera or microphone backed by a caller-supplied
+   * stream factory. The device appears in `listDevices()` and can be selected
+   * via `select()` like any real device.
+   *
+   * Web only. React Native is not supported.
+   *
+   * Only supported for camera and microphone managers; calling on any other
+   * manager throws.
+   */
+  registerVirtualDevice(virtualDevice: VirtualDevice<C>): VirtualDeviceHandle {
+    if (isReactNative()) {
+      throw new Error('Virtual devices are not supported on React Native.');
+    }
+    if (
+      this.trackType !== TrackType.AUDIO &&
+      this.trackType !== TrackType.VIDEO
+    ) {
+      throw new Error(
+        'Virtual devices are only supported for camera and microphone.',
+      );
+    }
+
+    const deviceId = `stream-virtual:${generateUUIDv4()}`;
+    const entry: VirtualDeviceEntry<C> = {
+      deviceId,
+      kind: this.mediaDeviceKind,
+      ...virtualDevice,
+    };
+
+    setCurrentValue(this.virtualDevicesSubject, (current) => [
+      ...current,
+      entry,
+    ]);
+
+    return {
+      deviceId: entry.deviceId,
+      unregister: async () => {
+        await withoutConcurrency(this.virtualDeviceConcurrencyTag, async () => {
+          setCurrentValue(this.virtualDevicesSubject, (current) =>
+            current.filter((d) => d !== entry),
+          );
+          if (this.activeVirtualSession?.deviceId === deviceId) {
+            await this.stopActiveVirtualSession();
+          }
+        });
+
+        if (this.state.selectedDevice === deviceId) {
+          await this.statusChangeSettled();
+
+          await this.disable({ forceStop: true });
+          await this.select(undefined);
+        }
+      },
+    };
+  }
+
+  protected sanitizeVirtualStream(stream: MediaStream): MediaStream {
+    stream.getTracks().forEach((track) => {
+      const originalGetSettings = track.getSettings.bind(track);
+      track.getSettings = () => {
+        const settings = originalGetSettings();
+        // eslint-disable-next-line @typescript-eslint/no-unused-vars
+        const { deviceId, ...rest } = settings;
+        return rest;
+      };
+    });
+
+    return stream;
+  }
+
+  protected findVirtualDevice(deviceId: string | undefined) {
+    if (!deviceId) return undefined;
+    return getCurrentValue(this.virtualDevicesSubject).find(
+      (d) => d.deviceId === deviceId,
+    );
+  }
+
+  private async stopActiveVirtualSession() {
+    const session = this.activeVirtualSession;
+    this.activeVirtualSession = undefined;
+    await session?.stop?.();
+  }
+
+  protected async getSelectedStream(constraints: C): Promise<MediaStream> {
+    const deviceId = this.state.selectedDevice;
+    if (!deviceId?.startsWith('stream-virtual')) {
+      return this.getStream(constraints);
+    }
+
+    return withoutConcurrency(this.virtualDeviceConcurrencyTag, async () => {
+      const virtualDevice = this.findVirtualDevice(deviceId);
+      if (!virtualDevice) {
+        throw new Error(`Virtual device is not registered: ${deviceId}`);
+      }
+
+      await this.stopActiveVirtualSession();
+      const { stream, stop } = await virtualDevice.getUserMedia(constraints);
+      this.activeVirtualSession = { deviceId, stop };
+
+      return this.sanitizeVirtualStream(stream);
+    });
   }
 
   /**
@@ -299,6 +433,7 @@ export abstract class DeviceManager<
     this.subscriptions.forEach((s) => s());
     this.subscriptions = [];
     this.areSubscriptionsSetUp = false;
+    this.virtualDevicesSubject.next([]);
   };
 
   private runCurrentStreamCleanups = () => {
@@ -330,6 +465,10 @@ export abstract class DeviceManager<
 
   protected abstract getDevices(): Observable<MediaDeviceInfo[]>;
 
+  protected getResolvedConstraints(constraints: C): C {
+    return constraints;
+  }
+
   protected abstract getStream(constraints: C): Promise<MediaStream>;
 
   protected publishStream(
@@ -357,6 +496,7 @@ export abstract class DeviceManager<
     this.muteLocalStream(stopTracks);
     const allEnded = this.getTracks().every((t) => t.readyState === 'ended');
     if (allEnded) {
+      await this.stopActiveVirtualSession();
       // @ts-expect-error release() is present in react-native-webrtc
       if (typeof mediaStream.release === 'function') {
         // @ts-expect-error called to dispose the stream in RN
@@ -415,12 +555,12 @@ export abstract class DeviceManager<
       this.runCurrentStreamCleanups();
 
       const defaultConstraints = this.state.defaultConstraints;
-      const constraints: MediaTrackConstraints = {
+      const constraints = this.getResolvedConstraints({
         ...defaultConstraints,
         deviceId: this.state.selectedDevice
           ? { exact: this.state.selectedDevice }
           : undefined,
-      };
+      } as C);
 
       /**
        * Chains two media streams together.
@@ -481,7 +621,7 @@ export abstract class DeviceManager<
 
       // the rootStream represents the stream coming from the actual device
       // e.g. camera or microphone stream
-      rootStreamPromise = this.getStream(constraints as C);
+      rootStreamPromise = this.getSelectedStream(constraints as C);
       // we publish the last MediaStream of the chain
       stream = await this.filters.reduce(
         (parent, entry) =>
@@ -581,7 +721,7 @@ export abstract class DeviceManager<
     });
   };
 
-  private get mediaDeviceKind(): MediaDeviceKind {
+  private get mediaDeviceKind(): 'audioinput' | 'videoinput' {
     if (this.trackType === TrackType.AUDIO) return 'audioinput';
     if (this.trackType === TrackType.VIDEO) return 'videoinput';
     throw new Error('Invalid track type');

package/src/devices/DeviceManagerState.ts

@@ -183,7 +183,10 @@ export abstract class DeviceManagerState<C = MediaTrackConstraints> {
     RxUtils.setCurrentValue(this.mediaStreamSubject, stream);
     RxUtils.setCurrentValue(this.rootMediaStreamSubject, rootStream);
     if (rootStream) {
-      this.setDevice(this.getDeviceIdFromStream(rootStream));
+      const derived = this.getDeviceIdFromStream(rootStream);
+      if (derived) {
+        this.setDevice(derived);
+      }
     }
   }
 

package/src/devices/VirtualDevice.ts

@@ -0,0 +1,69 @@
+/**
+ * A MediaStream produced for a virtual device session, along with an optional
+ * cleanup callback. Returned by {@link VirtualDevice.getUserMedia}.
+ */
+export interface VirtualDeviceSession {
+  readonly stream: MediaStream;
+  readonly stop?: () => void | Promise<void>;
+}
+
+/**
+ * A virtual camera or microphone definition supplied by the integrator.
+ *
+ * Pass this to `camera.registerVirtualDevice()` /
+ * `microphone.registerVirtualDevice()` to make it appear in the device list
+ * and become selectable.
+ */
+export interface VirtualDevice<C = MediaTrackConstraints> {
+  /**
+   * Human-readable label shown in device dropdowns.
+   */
+  label: string;
+
+  /**
+   * Called when the virtual device is selected and the SDK needs media.
+   * Returns the MediaStream to publish along with an optional `stop`
+   * callback that runs when the session is replaced, the tracks end, or
+   * the device is unregistered.
+   *
+   * `constraints` is the resolved set the SDK would otherwise pass to
+   * `getUserMedia` for a real device.
+   */
+  getUserMedia: (
+    constraints: C,
+  ) => VirtualDeviceSession | Promise<VirtualDeviceSession>;
+}
+
+/**
+ * @internal Internal entry stored in the device manager's registry.
+ */
+export interface VirtualDeviceEntry<
+  C = MediaTrackConstraints,
+> extends VirtualDevice<C> {
+  readonly deviceId: string;
+  readonly kind: 'audioinput' | 'videoinput';
+}
+
+/**
+ * @internal Tracks the currently active virtual device session inside the
+ * device manager so its `stop` callback can be invoked when the session is
+ * replaced or torn down.
+ */
+export interface ActiveVirtualSession {
+  deviceId: string;
+  stop?: () => void | Promise<void>;
+}
+
+export interface VirtualDeviceHandle {
+  /**
+   * The device id under which the virtual device was registered. Pass this
+   * to `camera.select()` / `microphone.select()` to switch to it.
+   */
+  readonly deviceId: string;
+
+  /**
+   * Removes the virtual device from the manager. If it is currently selected,
+   * the selection is reset so the SDK falls back to the default device.
+   */
+  unregister: () => Promise<void>;
+}

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

@@ -50,7 +50,9 @@ vi.mock('../devices.ts', () => {
 vi.mock('../../Call.ts', () => {
   console.log('MOCKING Call');
   return {
-    Call: vi.fn(() => mockCall()),
+    Call: vi.fn(function () {
+      return mockCall();
+    }),
   };
 });
 
@@ -210,6 +212,25 @@ describe('CameraManager', () => {
     });
   });
 
+  it('should pass resolved camera constraints to virtual devices', async () => {
+    const virtualStream = mockVideoStream();
+    const getUserMedia = vi.fn(() => ({ stream: virtualStream }));
+
+    const { deviceId } = manager.registerVirtualDevice({
+      label: 'Virtual camera',
+      getUserMedia,
+    });
+
+    await manager.select(deviceId);
+    await manager.enable();
+
+    expect(getUserMedia).toHaveBeenCalledWith({
+      deviceId: { exact: deviceId },
+      width: 1280,
+      height: 720,
+    });
+  });
+
   it(`should set target resolution, but shouldn't change device status`, async () => {
     manager['targetResolution'] = { width: 640, height: 480 };