@stream-io/video-client 1.49.0 → 1.50.0

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

@@ -1,36 +1,30 @@
+import type { CallState } from '../store';
+import { VideoTrackType } from '../types';
 export type EntryHandler = (entry: IntersectionObserverEntry) => void;
 export type Unobserve = () => void;
 export type Observe = (element: HTMLElement, entryHandler: EntryHandler) => Unobserve;
 export declare class ViewportTracker {
-    /**
-     * @private
-     */
+    private callState;
     private elementHandlerMap;
-    /**
-     * @private
-     */
     private observer;
-    /**
-     * @private
-     */
     private queueSet;
+    constructor(callState: CallState);
     /**
      * Method to set scrollable viewport as root for the IntersectionObserver, returns
      * cleanup function to be invoked upon disposing of the DOM element to prevent memory leaks
-     *
-     * @param viewportElement
-     * @param options
-     * @returns Unobserve
      */
     setViewport: (viewportElement: HTMLElement, options?: Pick<IntersectionObserverInit, "threshold" | "rootMargin">) => () => void;
     /**
      * Method to set element to observe and handler to be triggered whenever IntersectionObserver
      * detects a possible change in element's visibility within specified viewport, returns
      * cleanup function to be invoked upon disposing of the DOM element to prevent memory leaks
-     *
-     * @param element
-     * @param handler
-     * @returns Unobserve
      */
     observe: Observe;
+    /**
+     * Tracks the given element for visibility changes and mirrors the result
+     * into `participant.viewportVisibilityState[trackType]` in `CallState`.
+     * Returns a function that unobserves the element and resets the visibility
+     * state back to `UNKNOWN`.
+     */
+    trackElementVisibility: <T extends HTMLElement>(element: T, sessionId: string, trackType: VideoTrackType) => () => void;
 }

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

@@ -2,6 +2,19 @@
  * Checks whether the current browser is Safari.
  */
 export declare const isSafari: () => boolean;
+/**
+ * Checks whether the current runtime is a WebKit-engine browser.
+ *
+ * Returns true for desktop Safari, iOS Safari, bare iOS WKWebView hosts
+ * (in-app browsers, React Native WebView, Tauri-on-macOS, etc.), and for
+ * Chromium / Gecko-branded iOS browsers (`CriOS`, `EdgiOS`, `OPiOS`,
+ * `FxiOS`) since Apple forces every iOS browser onto WKWebView and they
+ * share the underlying WebKit quirks.
+ *
+ * Returns false for desktop Chromium-based browsers (which reuse the
+ * `AppleWebKit/` token in their UA) and Android.
+ */
+export declare const isWebKit: () => boolean;
 /**
  * Checks whether the current browser is Firefox.
  */

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

@@ -1,3 +1,4 @@
+type TagKey = string | symbol | object;
 /**
  * Runs async functions serially. Useful for wrapping async actions that
  * should never run simultaneously: if marked with the same tag, functions
@@ -8,7 +9,7 @@
  * @param cb Async function to run.
  * @returns Promise that resolves when async functions returns.
  */
-export declare const withoutConcurrency: <T>(tag: string | symbol, cb: () => Promise<T>) => Promise<T>;
+export declare const withoutConcurrency: <T>(tag: TagKey, cb: () => Promise<T>) => Promise<T>;
 /**
  * Runs async functions serially, and cancels all other actions with the same tag
  * when a new action is scheduled. Useful for wrapping async actions that override
@@ -25,6 +26,7 @@ export declare const withoutConcurrency: <T>(tag: string | symbol, cb: () => Pro
  * start and was canceled, will resolve with 'canceled'. If the function started to run,
  * it's up to the function to decide how to react to cancelation.
  */
-export declare const withCancellation: <T>(tag: string | symbol, cb: (signal: AbortSignal) => Promise<T | "canceled">) => Promise<T | "canceled">;
-export declare function hasPending(tag: string | symbol): boolean;
-export declare function settled(tag: string | symbol): Promise<void>;
+export declare const withCancellation: <T>(tag: TagKey, cb: (signal: AbortSignal) => Promise<T | "canceled">) => Promise<T | "canceled">;
+export declare function hasPending(tag: TagKey): boolean;
+export declare function settled(tag: TagKey): Promise<void>;
+export {};

package/dist/src/rtc/Publisher.d.ts

@@ -51,6 +51,23 @@ export declare class Publisher extends BasePeerConnection {
      * @param trackType the track type to check. If omitted, checks if any track is being published.
      */
     isPublishing: (trackType?: TrackType) => boolean;
+    /**
+     * Re-arms the encoder for the given track type by detaching and
+     * reattaching the currently published track on each matching sender.
+     *
+     * Workaround for a WebKit / iOS Safari quirk: after a system audio
+     * session interruption (Siri, PSTN call), the `RTCRtpSender` encoder
+     * can stop producing RTP packets even though the underlying
+     * `MediaStreamTrack` is `live` and `track.muted === false`.
+     * `replaceTrack(null)` followed by `replaceTrack(track)` resets the
+     * sender's encoder pipeline without renegotiation, restoring packet
+     * flow with the same SSRC.
+     *
+     * No-op when nothing is published for the given track type.
+     *
+     * @param trackType the track type to refresh.
+     */
+    refreshTrack: (trackType: TrackType) => Promise<void>;
     /**
      * Stops the cloned track that is being published to the SFU.
      */

package/dist/src/rtc/Subscriber.d.ts

@@ -22,5 +22,6 @@ export declare class Subscriber extends BasePeerConnection {
      */
     restartIce: () => Promise<void>;
     private handleOnTrack;
+    private setRemoteTrackInterrupted;
     private negotiate;
 }

package/dist/src/rtc/helpers/degradationPreference.d.ts

@@ -0,0 +1,2 @@
+import { DegradationPreference } from '../../gen/video/sfu/models/models';
+export declare const toRTCDegradationPreference: (preference: DegradationPreference) => RTCDegradationPreference | undefined;

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

@@ -1,5 +1,5 @@
 import type { PerformanceStats } from '../../gen/video/sfu/models/models';
-export type RTCStatsDataType = RTCConfiguration | RTCIceCandidate | RTCSignalingState | RTCIceConnectionState | RTCIceGatheringState | RTCPeerConnectionState | [number | null | string] | string | boolean | RTCOfferOptions | [string | RTCDataChannelInit | undefined] | (RTCOfferOptions | undefined) | RTCSessionDescriptionInit | (RTCIceCandidateInit | RTCIceCandidate) | object | null | undefined;
+export type RTCStatsDataType = RTCConfiguration | RTCIceCandidate | RTCSignalingState | RTCIceConnectionState | RTCIceGatheringState | RTCPeerConnectionState | [number | null | string] | string | boolean | RTCOfferOptions | [string | RTCDataChannelInit | undefined] | (RTCOfferOptions | undefined) | RTCSessionDescriptionInit | (RTCIceCandidateInit | RTCIceCandidate) | object | number | null | undefined;
 export type TraceKey = 'device-enumeration' | (string & {});
 export type Trace = (tag: string, data: RTCStatsDataType) => void;
 export type TraceRecord = [

package/dist/src/store/rxUtils.d.ts

@@ -1,5 +1,6 @@
 import { BehaviorSubject, Observable, Subject } from 'rxjs';
 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.
  */
@@ -21,6 +22,14 @@ export declare const getCurrentValue: <T>(observable$: Observable<T>) => T;
  * @return the updated value.
  */
 export declare const setCurrentValue: <T>(subject: Subject<T>, update: Patch<T>) => T;
+/**
+ * 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 declare const setCurrentValueAsync: <T>(subject: Subject<T>, update: AsyncFunctionPatch<T>) => Promise<T>;
 /**
  * Updates the value of the provided Subject and returns the previous value
  * and a function to roll back the update.

package/dist/src/types.d.ts

@@ -58,6 +58,24 @@ export interface StreamVideoParticipant extends Participant {
      * This is useful to avoid any unwanted video and audio artifacts.
      */
     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.
      */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stream-io/video-client",
-  "version": "1.49.0",
+  "version": "1.50.0",
   "main": "dist/index.cjs.js",
   "module": "dist/index.es.js",
   "browser": "dist/index.browser.es.js",
@@ -46,7 +46,7 @@
     "@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.7.3",
+    "@stream-io/audio-filters-web": "^0.8.0",
     "@stream-io/node-sdk": "^0.7.28",
     "@total-typescript/shoehorn": "^0.1.2",
     "@types/sdp-transform": "^2.15.0",

package/src/Call.ts

@@ -145,7 +145,11 @@ import {
   StatsReporter,
   Tracer,
 } from './stats';
+import { AudioBindingsWatchdog } from './helpers/AudioBindingsWatchdog';
+import { BlockedAudioTracker } from './helpers/BlockedAudioTracker';
+import { TrackSubscriptionManager } from './helpers/TrackSubscriptionManager';
 import { DynascaleManager } from './helpers/DynascaleManager';
+import { ViewportTracker } from './helpers/ViewportTracker';
 import { PermissionsContext } from './permissions';
 import { CallTypes } from './CallType';
 import { StreamClient } from './coordinator/connection/client';
@@ -230,7 +234,32 @@ export class Call {
   /**
    * The DynascaleManager instance.
    */
-  readonly dynascaleManager: DynascaleManager;
+  readonly dynascaleManager: DynascaleManager | undefined;
+
+  /**
+   * Tracks viewport visibility for participant video elements.
+   * Available only in DOM environments.
+   */
+  readonly viewportTracker: ViewportTracker | undefined;
+
+  /**
+   * Owns the SFU-side video-subscription state (per-session and global overrides).
+   */
+  readonly trackSubscriptionManager: TrackSubscriptionManager;
+
+  /**
+   * Warns periodically when a remote participant is publishing audio, but no
+   * `<audio>` element has been bound for them.
+   */
+  readonly audioBindingsWatchdog: AudioBindingsWatchdog | undefined;
+
+  /**
+   * Tracks audio elements blocked by the browser's autoplay policy.
+   * Subscribe to `blockedAudioTracker.autoplayBlocked$` to react to the
+   * blocked state, and call {@link Call.resumeAudio} inside a user gesture
+   * to retry playback.
+   */
+  readonly blockedAudioTracker: BlockedAudioTracker;
 
   subscriber?: Subscriber;
   publisher?: Publisher;
@@ -362,11 +391,26 @@ export class Call {
     this.microphone = new MicrophoneManager(this, preferences);
     this.speaker = new SpeakerManager(this, preferences);
     this.screenShare = new ScreenShareManager(this);
-    this.dynascaleManager = new DynascaleManager(
+    this.trackSubscriptionManager = new TrackSubscriptionManager(
       this.state,
-      this.speaker,
       this.tracer,
     );
+    this.blockedAudioTracker = new BlockedAudioTracker(this.tracer);
+
+    if (typeof document !== 'undefined') {
+      this.audioBindingsWatchdog = new AudioBindingsWatchdog(
+        this.state,
+        this.tracer,
+      );
+      this.viewportTracker = new ViewportTracker(this.state);
+      this.dynascaleManager = new DynascaleManager(
+        this.state,
+        this.speaker,
+        this.tracer,
+        this.trackSubscriptionManager,
+        this.blockedAudioTracker,
+      );
+    }
   }
 
   /**
@@ -701,8 +745,10 @@ export class Call {
 
       await this.sfuClient?.leaveAndClose(leaveReason);
       this.sfuClient = undefined;
-      this.dynascaleManager.setSfuClient(undefined);
-      await this.dynascaleManager.dispose();
+      this.trackSubscriptionManager.setSfuClient(undefined);
+      this.trackSubscriptionManager.dispose();
+      this.audioBindingsWatchdog?.dispose();
+      await this.dynascaleManager?.dispose();
 
       this.state.setCallingState(CallingState.LEFT);
       this.state.setParticipants([]);
@@ -1126,7 +1172,7 @@ export class Call {
         : previousSfuClient;
     this.sfuClient = sfuClient;
     this.unifiedSessionId ??= sfuClient.sessionId;
-    this.dynascaleManager.setSfuClient(sfuClient);
+    this.trackSubscriptionManager.setSfuClient(sfuClient);
 
     const clientDetails = await getClientDetails();
     // we don't need to send JoinRequest if we are re-using an existing healthy SFU client
@@ -1293,7 +1339,7 @@ export class Call {
     return {
       strategy,
       announcedTracks,
-      subscriptions: this.dynascaleManager.trackSubscriptions,
+      subscriptions: this.trackSubscriptionManager.subscriptions,
       reconnectAttempt: this.reconnectAttempts,
       fromSfuId: migratingFromSfuId || '',
       previousSessionId: performingRejoin ? previousSessionId || '' : '',
@@ -1976,7 +2022,7 @@ export class Call {
   private restoreSubscribedTracks = () => {
     const { remoteParticipants } = this.state;
     if (remoteParticipants.length <= 0) return;
-    this.dynascaleManager.applyTrackSubscriptions(undefined);
+    this.trackSubscriptionManager.apply(undefined);
   };
 
   /**
@@ -2097,6 +2143,20 @@ export class Call {
     }
   };
 
+  /**
+   * Re-arms the encoder for a currently published track type. Useful for
+   * working around WebKit's stalled sender bug after an iOS audio session
+   * interruption (Siri, PSTN call).
+   *
+   * @internal
+   *
+   * @param trackType the track type to refresh.
+   */
+  refreshPublishedTrack = async (trackType: TrackType) => {
+    if (!this.publisher) return;
+    await this.publisher.refreshTrack(trackType);
+  };
+
   /**
    * Updates the preferred publishing options
    *
@@ -3010,7 +3070,7 @@ export class Call {
     sessionId: string,
     trackType: VideoTrackType,
   ) => {
-    return this.dynascaleManager.trackElementVisibility(
+    return this.viewportTracker?.trackElementVisibility(
       element,
       sessionId,
       trackType,
@@ -3023,7 +3083,7 @@ export class Call {
    * @param element the viewport element.
    */
   setViewport = <T extends HTMLElement>(element: T) => {
-    return this.dynascaleManager.setViewport(element);
+    return this.viewportTracker?.setViewport(element);
   };
 
   /**
@@ -3046,7 +3106,7 @@ export class Call {
     sessionId: string,
     trackType: VideoTrackType,
   ) => {
-    const unbind = this.dynascaleManager.bindVideoElement(
+    const unbind = this.dynascaleManager?.bindVideoElement(
       videoElement,
       sessionId,
       trackType,
@@ -3075,26 +3135,33 @@ export class Call {
     sessionId: string,
     trackType: AudioTrackType = 'audioTrack',
   ) => {
-    const unbind = this.dynascaleManager.bindAudioElement(
+    const unbind = this.dynascaleManager?.bindAudioElement(
       audioElement,
       sessionId,
       trackType,
     );
 
     if (!unbind) return;
-    this.leaveCallHooks.add(unbind);
-    return () => {
-      this.leaveCallHooks.delete(unbind);
+    this.audioBindingsWatchdog?.register(audioElement, sessionId, trackType);
+    const cleanup = () => {
       unbind();
+      this.audioBindingsWatchdog?.unregister(sessionId, trackType);
+    };
+    this.leaveCallHooks.add(cleanup);
+    return () => {
+      this.leaveCallHooks.delete(cleanup);
+      cleanup();
     };
   };
 
   /**
    * Plays all audio elements blocked by the browser's autoplay policy.
+   * Must be called from within a user gesture (e.g., click handler).
+   *
+   * Subscribe to `call.blockedAudioTracker.autoplayBlocked$` to know when a
+   * gesture is required.
    */
-  resumeAudio = () => {
-    return this.dynascaleManager.resumeAudio();
-  };
+  resumeAudio = () => this.blockedAudioTracker.resumeAudio();
 
   /**
    * Binds a DOM <img> element to this call's thumbnail (if enabled in settings).
@@ -3148,7 +3215,7 @@ export class Call {
     resolution: VideoDimension | undefined,
     sessionIds?: string[],
   ) => {
-    this.dynascaleManager.setVideoTrackSubscriptionOverrides(
+    this.trackSubscriptionManager.setOverrides(
       resolution
         ? {
             enabled: true,
@@ -3157,7 +3224,7 @@ export class Call {
         : undefined,
       sessionIds,
     );
-    this.dynascaleManager.applyTrackSubscriptions();
+    this.trackSubscriptionManager.apply();
   };
 
   /**
@@ -3165,10 +3232,10 @@ export class Call {
    * and removes any preference for preferred resolution.
    */
   setIncomingVideoEnabled = (enabled: boolean) => {
-    this.dynascaleManager.setVideoTrackSubscriptionOverrides(
+    this.trackSubscriptionManager.setOverrides(
       enabled ? undefined : { enabled: false },
     );
-    this.dynascaleManager.applyTrackSubscriptions();
+    this.trackSubscriptionManager.apply();
   };
 
   /**

package/src/__tests__/Call.lifecycle.test.ts

@@ -0,0 +1,67 @@
+/**
+ * @vitest-environment happy-dom
+ */
+
+import '../rtc/__tests__/mocks/webrtc.mocks';
+
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { Call } from '../Call';
+import { StreamClient } from '../coordinator/connection/client';
+import { generateUUIDv4 } from '../coordinator/connection/utils';
+import { StreamVideoWriteableStateStore } from '../store';
+
+describe('Call lifecycle wiring', () => {
+  let call: Call;
+
+  beforeEach(() => {
+    call = new Call({
+      type: 'test',
+      id: generateUUIDv4(),
+      streamClient: new StreamClient('abc'),
+      clientStore: new StreamVideoWriteableStateStore(),
+    });
+  });
+
+  // Regression guard for the Call-owned helper teardown chain. Each of
+  // these helpers holds a resource (timer, listener, AudioContext) that
+  // leaks across calls if teardown is dropped during a refactor.
+  // Covers trackSubscriptionManager, audioBindingsWatchdog, and
+  // dynascaleManager. SFU-lifecycle disposables (publisher/subscriber/
+  // sfuStatsReporter) require a real join and are out of scope.
+  it('call.leave() tears down all Call-owned helpers exactly once', async () => {
+    const trackSubDispose = vi.spyOn(call.trackSubscriptionManager, 'dispose');
+    const audioBindingsDispose = vi.spyOn(
+      call.audioBindingsWatchdog!,
+      'dispose',
+    );
+    const dynascaleDispose = vi.spyOn(call.dynascaleManager!, 'dispose');
+
+    await call.leave();
+
+    expect(trackSubDispose).toHaveBeenCalledTimes(1);
+    expect(audioBindingsDispose).toHaveBeenCalledTimes(1);
+    expect(dynascaleDispose).toHaveBeenCalledTimes(1);
+  });
+
+  // Order matters: the SFU subscription pump must finish tearing down
+  // before DynascaleManager closes its AudioContext, otherwise helpers
+  // can run on a closed context (logged as warnings or thrown by
+  // happy-dom). This is the contract the leave() teardown chain encodes.
+  it('call.leave() tears down helpers in the documented order', async () => {
+    const trackSubDispose = vi.spyOn(call.trackSubscriptionManager, 'dispose');
+    const audioBindingsDispose = vi.spyOn(
+      call.audioBindingsWatchdog!,
+      'dispose',
+    );
+    const dynascaleDispose = vi.spyOn(call.dynascaleManager!, 'dispose');
+
+    await call.leave();
+
+    const trackSubOrder = trackSubDispose.mock.invocationCallOrder[0];
+    const audioBindingsOrder = audioBindingsDispose.mock.invocationCallOrder[0];
+    const dynascaleOrder = dynascaleDispose.mock.invocationCallOrder[0];
+
+    expect(trackSubOrder).toBeLessThan(audioBindingsOrder);
+    expect(audioBindingsOrder).toBeLessThan(dynascaleOrder);
+  });
+});