@stream-io/video-client 1.61.1 → 1.62.0

package/src/Call.ts

@@ -183,6 +183,7 @@ import {
 import { normalize } from './devices/devicePersistence';
 import {
   hasPending,
+  settled,
   singleFlight,
   withoutConcurrency,
 } from './helpers/concurrency';
@@ -325,6 +326,15 @@ export class Call {
 
   // (10 attempts per rolling 120 s window).
   private readonly rejoinRateLimiter = new SlidingWindowRateLimiter(10, 120000);
+  // Backstop for slow REJOIN loops that stay under the short window
+  // (20 attempts per rolling 30 min window). Dropped once the integrator
+  // takes over the budget through `setRejoinAttemptLimit`.
+  private rejoinLongWindowRateLimiter?: SlidingWindowRateLimiter =
+    new SlidingWindowRateLimiter(20, 30 * 60 * 1000);
+  // In-flight `doJoin` runs, awaited before acting on peer connections that
+  // gathered no local ICE candidates.
+  private readonly joinTasks = new Set<Promise<void>>();
+  private noLocalCandidatesCheckScheduled = false;
   // "Network doesn't support WebRTC" detector: counts peer-connection
   // failures where ICE never reached `connected`/`completed`.
   private maxIceFailuresWithoutConnect = 2;
@@ -810,6 +820,7 @@ export class Call {
       // `joinFlow` never runs, leaving stale values that would make the next
       // fresh `join()` send a stale `ReconnectDetails` to the SFU.
       this.rejoinRateLimiter.reset();
+      this.rejoinLongWindowRateLimiter?.reset();
       this.iceFailuresWithoutConnect = 0;
       this.consecutiveNegotiationFailures = 0;
       this.reconnectStrategy = WebsocketReconnectStrategy.UNSPECIFIED;
@@ -1313,6 +1324,16 @@ export class Call {
    * @returns a promise which resolves once the call join-flow has finished.
    */
   private doJoin = async (data?: JoinCallData): Promise<void> => {
+    const task = this.performJoin(data);
+    this.joinTasks.add(task);
+    try {
+      await task;
+    } finally {
+      this.joinTasks.delete(task);
+    }
+  };
+
+  private performJoin = async (data?: JoinCallData): Promise<void> => {
     const connectStartTime = Date.now();
     const callingState = this.state.callingState;
     const joinLeaveGeneration = this.leaveGeneration;
@@ -1761,6 +1782,9 @@ export class Call {
         // "ICE never connected" failure budget can be cleared.
         this.iceFailuresWithoutConnect = 0;
       },
+      onNoLocalCandidates: () => {
+        this.checkNoLocalCandidates();
+      },
       onPeerConnectionStateChange: (event) => {
         this.clientEventReporter.onPeerConnectionStateChange(this.cid, event);
       },
@@ -1812,9 +1836,6 @@ export class Call {
         options: statsOptions,
         subscriber: this.subscriber,
         publisher: this.publisher,
-        microphone: this.microphone,
-        camera: this.camera,
-        state: this.state,
         tracer: this.tracer,
         unifiedSessionId,
       });
@@ -1822,6 +1843,62 @@ export class Call {
     }
   };
 
+  /**
+   * Escalates to REJOIN with `ICE_NEVER_CONNECTED` when the current peer
+   * connections never connected and one of them completed ICE gathering
+   * without a single local candidate, which means WebRTC networking is
+   * blocked on this device.
+   *
+   * `reconnect` ignores requests while a join or another reconnect is in
+   * flight, so the check is postponed until those settle and then re-run
+   * against the peer connections current at that time.
+   */
+  private checkNoLocalCandidates = () => {
+    if (this.noLocalCandidatesCheckScheduled) return;
+    if (this.joinTasks.size > 0 || hasPending(this.reconnectConcurrencyTag)) {
+      this.noLocalCandidatesCheckScheduled = true;
+      const leaveGeneration = this.leaveGeneration;
+      this.waitForJoinsAndReconnects()
+        .then(() => {
+          this.noLocalCandidatesCheckScheduled = false;
+          if (this.leaveGeneration !== leaveGeneration) return;
+          this.checkNoLocalCandidates();
+        })
+        .catch((err) => {
+          this.noLocalCandidatesCheckScheduled = false;
+          this.logger.warn('[Reconnect] No-candidates check failed', err);
+        });
+      return;
+    }
+
+    if (this.state.callingState !== CallingState.JOINED) return;
+    // without network, gathering legitimately yields no candidates
+    if (typeof navigator !== 'undefined' && navigator.onLine === false) return;
+    const peerConnections = [this.publisher, this.subscriber];
+    if (peerConnections.some((pc) => pc?.hasIceEverConnected())) return;
+    if (!peerConnections.some((pc) => pc?.hasNoLocalCandidates())) return;
+
+    this.reconnect(
+      WebsocketReconnectStrategy.REJOIN,
+      ReconnectReason.ICE_NEVER_CONNECTED,
+    ).catch((err) => {
+      this.logger.warn('[Reconnect] Error reconnecting', err);
+    });
+  };
+
+  /**
+   * Resolves once no `doJoin` run and no reconnect is in flight.
+   */
+  private waitForJoinsAndReconnects = async () => {
+    while (
+      this.joinTasks.size > 0 ||
+      hasPending(this.reconnectConcurrencyTag)
+    ) {
+      await Promise.allSettled(this.joinTasks);
+      await settled(this.reconnectConcurrencyTag);
+    }
+  };
+
   /**
    * Retrieves credentials for joining the call.
    *
@@ -2063,6 +2140,16 @@ export class Call {
             return;
           }
         }
+        // MIGRATE is server-driven (e.g. SFU drains), so it doesn't count
+        // toward the long-window backstop.
+        if (
+          this.reconnectStrategy === WebsocketReconnectStrategy.REJOIN &&
+          this.rejoinLongWindowRateLimiter &&
+          !this.rejoinLongWindowRateLimiter.tryRegister()
+        ) {
+          await giveUpAndLeave('rejoin_attempt_limit_exceeded');
+          return;
+        }
 
         // we don't increment reconnect attempts for the FAST strategy.
         if (this.reconnectStrategy !== WebsocketReconnectStrategy.FAST) {
@@ -2343,7 +2430,12 @@ export class Call {
     });
 
     // handles the "error" event, through which the SFU can request a reconnect
-    const unregisterOnError = this.on('error', (e) => {
+    // Only the active SFU client may drive a reconnect: a superseded one can
+    // still report errors about its own (replaced) session, and none may
+    // while `leave()` tears the call down.
+    const activeSfuTag = () => this.sfuClient?.tag ?? '*';
+    const unregisterOnError = this.dispatcher.on('error', activeSfuTag, (e) => {
+      if (!this.sfuClient) return;
       const { reconnectStrategy: strategy, error } = e;
       if (!SfuJoinError.isJoinErrorCode(e)) {
         const code = error?.code ? ErrorCode[error.code] : undefined;
@@ -2363,10 +2455,17 @@ export class Call {
           this.logger.warn(`Can't leave call after disconnect request`, err);
         });
       } else {
-        this.reconnect(
-          strategy,
-          error?.message || ReconnectReason.SFU_ERROR,
-        ).catch((err) => {
+        // A media transport failure on a session whose peer connections
+        // never connected is an "ICE never connected" failure, and must
+        // count toward the unsupported-network budget.
+        const neverConnected =
+          error?.code === ErrorCode.PARTICIPANT_MEDIA_TRANSPORT_FAILURE &&
+          !this.publisher?.hasIceEverConnected() &&
+          !this.subscriber?.hasIceEverConnected();
+        const reason = neverConnected
+          ? ReconnectReason.ICE_NEVER_CONNECTED
+          : error?.message || ReconnectReason.SFU_ERROR;
+        this.reconnect(strategy, reason).catch((err) => {
           this.logger.warn('[Reconnect] Error reconnecting', err);
         });
       }
@@ -3804,9 +3903,11 @@ export class Call {
    * `rejoin_attempt_limit_exceeded` leave message.
    *
    * Defaults: 10 attempts per 120 seconds (aligned with the Swift SDK).
-   * Both arguments are clamped to a minimum of 1.
+   * Both arguments are clamped to a minimum of 1. Unless this method is
+   * called, an additional cap of 20 REJOIN attempts per 30 minutes applies.
    */
   setRejoinAttemptLimit = (maxAttempts: number, windowSeconds: number) => {
+    this.rejoinLongWindowRateLimiter = undefined;
     this.rejoinRateLimiter.setLimits(
       Math.max(1, maxAttempts),
       Math.max(1, windowSeconds) * 1000,

package/src/StreamVideoClient.ts

@@ -42,6 +42,7 @@ import { logToConsole, ScopedLogger, videoLoggerSystem } from './logger';
 import { withoutConcurrency } from './helpers/concurrency';
 import { enableTimerWorker } from './timers';
 import { ClientEventReporter } from './reporting';
+import { reconcileRingState } from './ringing';
 
 /**
  * A `StreamVideoClient` instance lets you communicate with our API, and authenticate users.
@@ -285,6 +286,13 @@ export class StreamVideoClient {
 
           if (call) {
             call.updateFromCallStateResponse(c);
+            // ring events missed while the WS was down aren't replayed
+            reconcileRingState(call, 'ring-poll-api').catch((err) => {
+              call.logger.error(
+                'Failed to reconcile the ring state after rewatch',
+                err,
+              );
+            });
           }
         }
 

package/src/__tests__/StreamVideoClient.rewatch.test.ts

@@ -12,7 +12,9 @@ import type {
   CallResponse,
   ConnectedEvent,
   GetCallResponse,
+  MemberResponse,
   QueryCallsResponse,
+  UserResponse,
 } from '../gen/coordinator';
 
 const apiKey = 'mock-api-key';
@@ -126,6 +128,140 @@ describe('StreamVideoClient re-watching calls on reconnect', () => {
     await vi.waitFor(() => expect(leave).toHaveBeenCalled());
   });
 
+  describe('ring reconciliation after a rewatch', () => {
+    const rewatchWith = async (
+      call: Call,
+      rejected_by: Record<string, string>,
+      extra: {
+        accepted_by?: Record<string, string>;
+        members?: MemberResponse[];
+        ended_at?: string;
+      } = {},
+    ) => {
+      const leave = vi.spyOn(call, 'leave').mockResolvedValue(undefined);
+      const session = CallRingPayload.call.session!;
+      const response = queryCallsResponse({
+        ...CallRingPayload.call,
+        // keep the creator the call was set up with
+        created_by: call.state.createdBy as UserResponse,
+        ended_at: extra.ended_at,
+        session: {
+          ...session,
+          rejected_by,
+          accepted_by: extra.accepted_by ?? session.accepted_by,
+        },
+      });
+      if (extra.members) response.calls[0].members = extra.members;
+      const post = vi
+        .spyOn(client.streamClient, 'doAxiosRequest')
+        .mockResolvedValue(response as never);
+      const updated = vi.spyOn(call, 'updateFromCallStateResponse');
+      reconnect();
+      await vi.waitFor(() => expect(post).toHaveBeenCalled());
+      await vi.waitFor(() => expect(updated).toHaveBeenCalled());
+      for (let i = 0; i < 5; i++) await Promise.resolve();
+      return leave;
+    };
+    const rejectedAt = () => '2025-08-14T14:49:00Z';
+
+    it('callee leaves when the creator cancelled while offline', async () => {
+      const call = await setupRingingCall();
+      const leave = await rewatchWith(call, { oliver_1: rejectedAt() });
+      expect(leave).toHaveBeenCalledWith({
+        reason: 'ended',
+        message: 'ring: creator rejected',
+      });
+    });
+
+    it('callee keeps ringing without a rejection', async () => {
+      const call = await setupRingingCall();
+      const leave = await rewatchWith(call, {});
+      expect(leave).not.toHaveBeenCalled();
+    });
+
+    it('callee keeps ringing when only another member rejected', async () => {
+      const call = await setupRingingCall();
+      const leave = await rewatchWith(call, { someone_else: rejectedAt() });
+      expect(leave).not.toHaveBeenCalled();
+    });
+
+    it('callee leaves when the call ended while offline', async () => {
+      const call = await setupRingingCall();
+      const leave = await rewatchWith(call, {}, { ended_at: rejectedAt() });
+      expect(leave).toHaveBeenCalledWith({
+        reason: 'ended',
+        message: 'ring: call ended',
+      });
+    });
+
+    it('does not reconcile a call that is not in RINGING state', async () => {
+      const call = await setupRingingCall();
+      call.state.setCallingState(CallingState.JOINED);
+      const leave = await rewatchWith(call, { oliver_1: rejectedAt() });
+      expect(leave).not.toHaveBeenCalled();
+    });
+
+    describe('as the caller', () => {
+      const callee = CallRingPayload.members[0];
+      const members = [
+        callee,
+        {
+          ...callee,
+          user_id: 'oliver_1',
+          user: { ...callee.user, id: 'oliver_1' },
+        },
+      ];
+
+      const setupOwnRingingCall = async () => {
+        const payload = {
+          ...CallRingPayload,
+          call: {
+            ...CallRingPayload.call,
+            created_by: { ...CallRingPayload.call.created_by, id: userId },
+          },
+          members,
+        };
+        vi.spyOn(client.streamClient, 'doAxiosRequest').mockResolvedValue({
+          duration: '1ms',
+          call: payload.call,
+          members,
+          own_capabilities: [],
+        } as GetCallResponse as never);
+        client.streamClient.dispatchEvent(payload as StreamVideoEvent);
+        await settled(getCallInitConcurrencyTag(payload.call_cid));
+        const [call] = client.state.calls;
+        expect(call.isCreatedByMe).toBeTruthy();
+        expect(call.state.callingState).toBe(CallingState.RINGING);
+        return call;
+      };
+
+      it('leaves when every other member rejected while offline', async () => {
+        const call = await setupOwnRingingCall();
+        const leave = await rewatchWith(
+          call,
+          { oliver_1: rejectedAt() },
+          { members },
+        );
+        expect(leave).toHaveBeenCalledWith({
+          reject: true,
+          reason: 'cancel',
+          message: 'ring: everyone rejected',
+        });
+      });
+
+      it('joins when another member accepted while offline', async () => {
+        const call = await setupOwnRingingCall();
+        const join = vi.spyOn(call, 'join').mockResolvedValue(undefined);
+        await rewatchWith(
+          call,
+          {},
+          { members, accepted_by: { oliver_1: rejectedAt() } },
+        );
+        expect(join).toHaveBeenCalledWith({ joinSource: 'ring-poll-api' });
+      });
+    });
+  });
+
   it('queryCalls returns an independent instance for registered calls', async () => {
     // e.g. being on a call while watching a dashboard of calls:
     // leaving the joined instance must not silence the dashboard instance

package/src/coordinator/connection/types.ts

@@ -202,7 +202,7 @@ export type Logger = (
 
 export type RingStatePollingOptions = {
   /**
-   * Quiet time after the ring starts, before the first poll. Defaults to 15_000.
+   * Quiet time after the ring starts, before the first poll. Defaults to 9_000.
    */
   startAfterMs?: number;
 

package/src/devices/DeviceManager.ts

@@ -298,6 +298,7 @@ export abstract class DeviceManager<
         : (forceStopOrOptions?.forceStop ?? false);
 
     this.state.prevStatus = this.state.optimisticStatus;
+    this.state.setError(undefined);
     if (!forceStop && this.state.optimisticStatus === 'disabled') {
       return;
     }
@@ -310,6 +311,7 @@ export abstract class DeviceManager<
           forceStop || this.state.disableMode === 'stop-tracks';
         await this.muteStream(stopTracks);
         this.state.setStatus('disabled');
+        this.state.setError(undefined);
       } finally {
         if (!signal.aborted) {
           this.state.setPendingStatus(this.state.status);
@@ -638,7 +640,11 @@ export abstract class DeviceManager<
 
       // the rootStream represents the stream coming from the actual device
       // e.g. camera or microphone stream
+      this.state.setError(undefined);
       rootStreamPromise = this.getSelectedStream(constraints as C);
+      rootStreamPromise.catch((error) => {
+        this.state.setError(error);
+      });
       // we publish the last MediaStream of the chain
       stream = await this.filters.reduce(
         (parent, entry) =>
@@ -837,11 +843,30 @@ export abstract class DeviceManager<
     const devices = getCurrentValue(this.listDevices()) || [];
     const currentDevice =
       this.findDevice(devices, selectedDevice) ??
-      createSyntheticDevice(selectedDevice, deviceKind);
+      createSyntheticDevice(
+        selectedDevice,
+        deviceKind,
+        this.getActiveTrackLabel(selectedDevice),
+      );
 
     writePreferences(currentDevice, deviceKey, muted, storageKey);
   }
 
+  /**
+   * Returns the label of the active track if it was captured from the given
+   * device. Used as a fallback when the device list hasn't been enumerated yet,
+   * so the persisted preference still carries the device label.
+   */
+  private getActiveTrackLabel = (deviceId: string) => {
+    const stream = this.state.rootMediaStream;
+    const tracks =
+      this.trackType === TrackType.AUDIO
+        ? stream?.getAudioTracks()
+        : stream?.getVideoTracks();
+    const track = tracks?.find((t) => t.getSettings().deviceId === deviceId);
+    return track?.label;
+  };
+
   protected async applyPersistedPreferences(
     enabledInCallType: boolean,
     forceDisabled = false,

package/src/devices/DeviceManagerState.ts

@@ -28,6 +28,7 @@ export abstract class DeviceManagerState<C = MediaTrackConstraints> {
   protected defaultConstraintsSubject = new BehaviorSubject<C | undefined>(
     undefined,
   );
+  protected errorSubject = new BehaviorSubject<Error | undefined>(undefined);
 
   /**
    * @internal
@@ -70,6 +71,14 @@ export abstract class DeviceManagerState<C = MediaTrackConstraints> {
    */
   defaultConstraints$ = this.defaultConstraintsSubject.asObservable();
 
+  /**
+   * An Observable that emits the error of the last failed attempt to start
+   * the device (e.g. the device is in use by another app), or `undefined`.
+   * For screen share, this includes the user dismissing the picker.
+   * Cleared when the device is started again or disabled.
+   */
+  error$ = this.errorSubject.asObservable().pipe(distinctUntilChanged());
+
   /**
    * An observable that will emit `true` if browser/system permission
    * is granted (or at least hasn't been denied), `false` otherwise.
@@ -152,6 +161,21 @@ export abstract class DeviceManagerState<C = MediaTrackConstraints> {
     return RxUtils.getCurrentValue(this.rootMediaStream$);
   }
 
+  /**
+   * The error of the last failed attempt to start the device, or `undefined`.
+   */
+  get error() {
+    return RxUtils.getCurrentValue(this.error$);
+  }
+
+  /**
+   * @internal
+   * @param error the error to set.
+   */
+  setError(error: Error | undefined) {
+    RxUtils.setCurrentValue(this.errorSubject, error);
+  }
+
   /**
    * @internal
    * @param status

package/src/devices/MicrophoneManager.ts

@@ -8,7 +8,7 @@ import {
 import { type BrowserPermissionState } from './BrowserPermission';
 import { MicrophoneManagerState } from './MicrophoneManagerState';
 import { TrackDisableMode } from './DeviceManagerState';
-import { getAudioDevices, getAudioStream } from './devices';
+import { getAudioDevices, getAudioStream, resolveDeviceId } from './devices';
 import { AudioBitrateProfile, TrackType } from '../gen/video/sfu/models/models';
 import { createSoundDetector } from '../helpers/sound-detector';
 import { createNoAudioDetector } from '../helpers/no-audio-detector';
@@ -64,16 +64,12 @@ export class MicrophoneManager extends AudioDeviceManager<MicrophoneManagerState
           this.call.state.callingState$,
           this.call.state.ownCapabilities$,
           this.state.selectedDevice$,
-          this.state.status$,
           this.state.browserPermissionState$,
+          // only a trigger: queued handlers can run after the status changed
+          // again, so the live status is read below
+          this.state.status$,
         ]),
-        async ([
-          callingState,
-          ownCapabilities,
-          deviceId,
-          status,
-          permissionState,
-        ]) => {
+        async ([callingState, ownCapabilities, deviceId, permissionState]) => {
           try {
             if (callingState === CallingState.LEFT) {
               // The muted-recording-prepared mode is reset in `callManager.stop()`
@@ -87,7 +83,7 @@ export class MicrophoneManager extends AudioDeviceManager<MicrophoneManagerState
 
             if (ownCapabilities.includes(OwnCapability.SEND_AUDIO)) {
               const hasPermission = await this.hasPermission(permissionState);
-              if (hasPermission && status !== 'enabled') {
+              if (hasPermission && this.state.status !== 'enabled') {
                 this.setMutedRecordingPrepared(true);
                 await this.startSpeakingWhileMutedDetection(deviceId);
               } else {
@@ -450,6 +446,61 @@ export class MicrophoneManager extends AudioDeviceManager<MicrophoneManagerState
     return getAudioStream(constraints, this.call.tracer);
   }
 
+  /**
+   * On mute, hands a clone of the live mic track to the speaking while muted
+   * detection, so the device stays captured after the mic tracks are stopped.
+   * Releasing and re-acquiring the mic flips Bluetooth headsets between audio
+   * profiles.
+   */
+  protected override async muteStream(stopTracks: boolean = true) {
+    const [track] = this.state.rootMediaStream?.getAudioTracks() ?? [];
+    const clone =
+      track?.readyState === 'live' &&
+      this.state.optimisticStatus === 'disabled' &&
+      this.canHandOffMic()
+        ? track.clone()
+        : undefined;
+    try {
+      await super.muteStream(stopTracks);
+    } catch (err) {
+      clone?.stop();
+      throw err;
+    }
+    if (!clone) return;
+
+    // the mic, the call, or the selected device may have changed while
+    // unpublishing
+    const deviceId = resolveDeviceId(
+      clone.getSettings().deviceId,
+      'audioinput',
+    );
+    if (
+      clone.readyState !== 'live' ||
+      !this.canHandOffMic() ||
+      deviceId !== this.state.selectedDevice
+    ) {
+      clone.stop();
+      return;
+    }
+    this.startSpeakingWhileMutedDetection(deviceId, clone).catch((err) => {
+      clone.stop();
+      this.logger.warn('Could not hand off mic to speaking while muted', err);
+    });
+  }
+
+  /**
+   * Whether a mute can hand the mic over to the speaking while muted detection.
+   */
+  private canHandOffMic = () => {
+    const { callingState, ownCapabilities } = this.call.state;
+    return (
+      !isReactNative() &&
+      this.speakingWhileMutedNotificationEnabled &&
+      callingState === CallingState.JOINED &&
+      ownCapabilities.includes(OwnCapability.SEND_AUDIO)
+    );
+  };
+
   protected override doSetAudioBitrateProfile(profile: AudioBitrateProfile) {
     this.setDefaultConstraints({
       ...this.state.defaultConstraints,
@@ -474,10 +525,18 @@ export class MicrophoneManager extends AudioDeviceManager<MicrophoneManagerState
     }
   }
 
-  private async startSpeakingWhileMutedDetection(deviceId?: string) {
+  private async startSpeakingWhileMutedDetection(
+    deviceId?: string,
+    track?: MediaStreamTrack,
+  ) {
     await withoutConcurrency(this.soundDetectorConcurrencyTag, async () => {
-      if (this.soundDetectorCleanup && this.soundDetectorDeviceId === deviceId)
+      if (
+        this.soundDetectorCleanup &&
+        this.soundDetectorDeviceId === deviceId
+      ) {
+        track?.stop();
         return;
+      }
 
       await this.teardownSpeakingWhileMutedDetection();
 
@@ -497,11 +556,14 @@ export class MicrophoneManager extends AudioDeviceManager<MicrophoneManagerState
           unsubscribe();
         };
       } else {
-        // Need to start a new stream that's not connected to publisher
-        const stream = await this.getStream({
-          ...this.state.defaultConstraints,
-          deviceId: { exact: deviceId },
-        });
+        // Use the handed-off mic track, or start a new stream that's not
+        // connected to publisher
+        const stream = track
+          ? new MediaStream([track])
+          : await this.getStream({
+              ...this.state.defaultConstraints,
+              deviceId: { exact: deviceId },
+            });
         this.soundDetectorCleanup = createSoundDetector(stream, (event) => {
           this.state.setSpeakingWhileMuted(event.isSoundDetected);
         });

package/src/devices/SpeakerManager.ts

@@ -49,7 +49,7 @@ export class SpeakerManager {
 
   private async applyWeb() {
     const { enabled, storageKey } = this.devicePersistence;
-    if (!enabled) return;
+    if (!enabled || !this.state.isDeviceSelectionSupported) return;
 
     const preferences = readPreferences(storageKey);
     const preferenceList = toPreferenceList(preferences.speaker);