@stream-io/video-client 0.3.8 → 0.3.10

package/dist/src/Call.d.ts

@@ -2,21 +2,16 @@ import { SfuEventKinds, SfuEventListener } from './rtc';
 import { TrackType } from './gen/video/sfu/models/models';
 import { CallState } from './store';
 import { AcceptCallResponse, BlockUserResponse, EndCallResponse, GetCallResponse, GetOrCreateCallRequest, GetOrCreateCallResponse, GoLiveRequest, GoLiveResponse, ListRecordingsResponse, MuteUsersResponse, PinRequest, PinResponse, QueryMembersRequest, QueryMembersResponse, RejectCallResponse, RequestPermissionRequest, RequestPermissionResponse, SendEventResponse, SendReactionRequest, SendReactionResponse, StartBroadcastingResponse, StartRecordingResponse, StopBroadcastingResponse, StopLiveResponse, StopRecordingResponse, UnblockUserResponse, UnpinRequest, UnpinResponse, UpdateCallMembersRequest, UpdateCallMembersResponse, UpdateCallRequest, UpdateCallResponse, UpdateUserPermissionsRequest, UpdateUserPermissionsResponse } from './gen/coordinator';
-import { CallConstructor, CallLeaveOptions, DebounceType, JoinCallData, PublishOptions, SubscriptionChanges } from './types';
-import { ViewportTracker } from './helpers/ViewportTracker';
+import { CallConstructor, CallLeaveOptions, DebounceType, JoinCallData, PublishOptions, SubscriptionChanges, VideoTrackType } from './types';
+import { DynascaleManager } from './helpers/DynascaleManager';
 import { PermissionsContext } from './permissions';
 import { StreamClient } from './coordinator/connection/client';
 import { CallEventHandler, CallEventTypes, EventTypes, Logger } from './coordinator/connection/types';
-import { CameraManager } from './devices/CameraManager';
-import { MicrophoneManager } from './devices/MicrophoneManager';
+import { CameraManager, MicrophoneManager } from './devices';
 /**
  * An object representation of a `Call`.
  */
 export declare class Call {
-    /**
-     * ViewportTracker instance
-     */
-    readonly viewportTracker: ViewportTracker;
     /**
      * The type of the call.
      */
@@ -46,6 +41,10 @@ export declare class Call {
      * Device manager for the microhpone
      */
     readonly microphone: MicrophoneManager;
+    /**
+     * The DynascaleManager instance.
+     */
+    readonly dynascaleManager: DynascaleManager;
     /**
      * Flag telling whether this call is a "ringing" call.
      */
@@ -225,11 +224,11 @@ export declare class Call {
      * You have to create a subscription for each participant for all the different kinds of tracks you want to receive.
      * You can only subscribe for tracks after the participant started publishing the given kind of track.
      *
-     * @param kind the kind of subscription to update.
+     * @param trackType the kind of subscription to update.
      * @param changes the list of subscription changes to do.
      * @param type the debounce type to use for the update.
      */
-    updateSubscriptionsPartial: (kind: 'video' | 'screen', changes: SubscriptionChanges, type?: DebounceType) => void;
+    updateSubscriptionsPartial: (trackType: VideoTrackType | 'video' | 'screen', changes: SubscriptionChanges, type?: DebounceType) => void;
     private updateSubscriptions;
     /**
      * Will enhance the reported stats with additional participant-specific information (`callStatsReport$` state [store variable](./StreamVideoClient.md/#readonlystatestore)).
@@ -477,4 +476,45 @@ export declare class Call {
     }) => Promise<SendEventResponse>;
     private initCamera;
     private initMic;
+    /**
+     * Will begin tracking the given element for visibility changes within the
+     * configured viewport element (`call.setViewport`).
+     *
+     * @param element the element to track.
+     * @param sessionId the session id.
+     * @param trackType the video mode.
+     */
+    trackElementVisibility: <T extends HTMLElement>(element: T, sessionId: string, trackType: VideoTrackType) => () => void;
+    /**
+     * Sets the viewport element to track bound video elements for visibility.
+     *
+     * @param element the viewport element.
+     */
+    setViewport: <T extends HTMLElement>(element: T) => () => void;
+    /**
+     * Binds a DOM <video> element to the given session id.
+     * This method will make sure that the video element will play
+     * the correct video stream for the given session id.
+     *
+     * Under the hood, it would also keep track of the video element dimensions
+     * and update the subscription accordingly in order to optimize the bandwidth.
+     *
+     * If a "viewport" is configured, the video element will be automatically
+     * tracked for visibility and the subscription will be updated accordingly.
+     *
+     * @param videoElement the video element to bind to.
+     * @param sessionId the session id.
+     * @param trackType the kind of video.
+     */
+    bindVideoElement: (videoElement: HTMLVideoElement, sessionId: string, trackType: VideoTrackType) => (() => void) | undefined;
+    /**
+     * Binds a DOM <audio> element to the given session id.
+     *
+     * This method will make sure that the audio element will
+     * play the correct audio stream for the given session id.
+     *
+     * @param audioElement the audio element to bind to.
+     * @param sessionId the session id.
+     */
+    bindAudioElement: (audioElement: HTMLAudioElement, sessionId: string) => (() => void) | undefined;
 }

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

@@ -0,0 +1,70 @@
+import { Call } from '../Call';
+import { VideoTrackType } from '../types';
+import { ViewportTracker } from './ViewportTracker';
+/**
+ * A manager class that handles dynascale related tasks like:
+ *
+ * - binding video elements to session ids
+ * - binding audio elements to session ids
+ * - tracking element visibility
+ * - updating subscriptions based on viewport visibility
+ * - updating subscriptions based on video element dimensions
+ * - updating subscriptions based on published tracks
+ */
+export declare class DynascaleManager {
+    /**
+     * The viewport tracker instance.
+     */
+    readonly viewportTracker: ViewportTracker;
+    private logger;
+    private call;
+    /**
+     * Creates a new DynascaleManager instance.
+     *
+     * @param call the call to manage.
+     */
+    constructor(call: Call);
+    /**
+     * Will begin tracking the given element for visibility changes within the
+     * configured viewport element (`call.setViewport`).
+     *
+     * @param element the element to track.
+     * @param sessionId the session id.
+     * @param trackType the kind of video.
+     * @returns Untrack.
+     */
+    trackElementVisibility: <T extends HTMLElement>(element: T, sessionId: string, trackType: VideoTrackType) => () => void;
+    /**
+     * Sets the viewport element to track bound video elements for visibility.
+     *
+     * @param element the viewport element.
+     */
+    setViewport: <T extends HTMLElement>(element: T) => () => void;
+    /**
+     * Binds a DOM <video> element to the given session id.
+     * This method will make sure that the video element will play
+     * the correct video stream for the given session id.
+     *
+     * Under the hood, it would also keep track of the video element dimensions
+     * and update the subscription accordingly in order to optimize the bandwidth.
+     *
+     * If a "viewport" is configured, the video element will be automatically
+     * tracked for visibility and the subscription will be updated accordingly.
+     *
+     * @param videoElement the video element to bind to.
+     * @param sessionId the session id.
+     * @param trackType the kind of video.
+     */
+    bindVideoElement: (videoElement: HTMLVideoElement, sessionId: string, trackType: VideoTrackType) => (() => void) | undefined;
+    /**
+     * Binds a DOM <audio> element to the given session id.
+     *
+     * This method will make sure that the audio element will
+     * play the correct audio stream for the given session id.
+     *
+     * @param audioElement the audio element to bind to.
+     * @param sessionId the session id.
+     * @returns a cleanup function that will unbind the audio element.
+     */
+    bindAudioElement: (audioElement: HTMLAudioElement, sessionId: string) => (() => void) | undefined;
+}

package/dist/src/helpers/__tests__/DynascaleManager.test.d.ts

@@ -0,0 +1,4 @@
+/**
+ * @vitest-environment happy-dom
+ */
+import '../../rtc/__tests__/mocks/webrtc.mocks';

package/dist/src/types.d.ts

@@ -11,7 +11,7 @@ export declare enum VisibilityState {
     INVISIBLE = "INVISIBLE"
 }
 export declare enum DebounceType {
-    IMMEDIATE = 0,
+    IMMEDIATE = 20,
     FAST = 100,
     MEDIUM = 600,
     SLOW = 1200
@@ -56,11 +56,9 @@ export interface StreamVideoParticipant extends Participant {
      */
     reaction?: StreamReaction;
     /**
-     * The visibility state of the participant's video element
-     * within the pre-configured viewport.
-     * @default VisibilityState.UNKNOWN
+     * The visibility state of the participant's tracks within a defined viewport.
      */
-    viewportVisibilityState?: VisibilityState;
+    viewportVisibilityState?: Record<VideoTrackType, VisibilityState>;
 }
 export interface StreamVideoLocalParticipant extends StreamVideoParticipant {
     /**
@@ -82,6 +80,7 @@ export interface StreamVideoLocalParticipant extends StreamVideoParticipant {
      */
     audioOutputDeviceId?: string;
 }
+export type VideoTrackType = 'videoTrack' | 'screenShareTrack';
 /**
  * Represents a participant's pin state.
  */

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const version = "0.3.8";
+export declare const version = "0.3.10";

package/index.ts

@@ -18,9 +18,10 @@ export * from './src/StreamSfuClient';
 export * from './src/devices';
 export * from './src/store';
 export * from './src/sorting';
+export * from './src/helpers/DynascaleManager';
 export * from './src/helpers/ViewportTracker';
-
 export * from './src/helpers/sound-detector';
 export * as Browsers from './src/helpers/browsers';
+
 export * from './src/client-details';
 export * from './src/logger';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stream-io/video-client",
-  "version": "0.3.8",
+  "version": "0.3.10",
   "packageManager": "yarn@3.2.4",
   "main": "dist/index.cjs.js",
   "module": "dist/index.es.js",
@@ -46,20 +46,21 @@
   "devDependencies": {
     "@openapitools/openapi-generator-cli": "^2.6.0",
     "@rollup/plugin-replace": "^5.0.2",
-    "@rollup/plugin-typescript": "^11.1.0",
+    "@rollup/plugin-typescript": "^11.1.2",
     "@types/jsonwebtoken": "^9.0.1",
     "@types/rimraf": "^3.0.2",
     "@types/sdp-transform": "^2.4.6",
     "@types/ua-parser-js": "^0.7.36",
     "@types/ws": "^8.5.4",
-    "@vitest/coverage-c8": "^0.31.0",
+    "@vitest/coverage-v8": "^0.34.2",
     "dotenv": "^16.3.1",
+    "happy-dom": "^10.11.0",
     "prettier": "^2.8.4",
     "rimraf": "^3.0.2",
-    "rollup": "^3.25.1",
+    "rollup": "^3.28.1",
     "typescript": "^4.9.5",
-    "vite": "^4.3.9",
-    "vitest": "^0.30.1",
-    "vitest-mock-extended": "^1.1.3"
+    "vite": "^4.4.9",
+    "vitest": "^0.34.3",
+    "vitest-mock-extended": "^1.2.0"
   }
 }

package/src/Call.ts

@@ -76,6 +76,7 @@ import {
   StreamVideoParticipant,
   StreamVideoParticipantPatches,
   SubscriptionChanges,
+  VideoTrackType,
   VisibilityState,
 } from './types';
 import {
@@ -96,7 +97,7 @@ import {
   createStatsReporter,
   StatsReporter,
 } from './stats/state-store-stats-reporter';
-import { ViewportTracker } from './helpers/ViewportTracker';
+import { DynascaleManager } from './helpers/DynascaleManager';
 import { PermissionsContext } from './permissions';
 import { CallTypes } from './CallType';
 import { StreamClient } from './coordinator/connection/client';
@@ -115,19 +116,12 @@ import {
 } from './coordinator/connection/types';
 import { getClientDetails, getSdkInfo } from './client-details';
 import { getLogger } from './logger';
-import { CameraManager } from './devices/CameraManager';
-import { MicrophoneManager } from './devices/MicrophoneManager';
-import { CameraDirection } from './devices/CameraManagerState';
+import { CameraDirection, CameraManager, MicrophoneManager } from './devices';
 
 /**
  * An object representation of a `Call`.
  */
 export class Call {
-  /**
-   * ViewportTracker instance
-   */
-  readonly viewportTracker = new ViewportTracker();
-
   /**
    * The type of the call.
    */
@@ -164,6 +158,11 @@ export class Call {
    */
   readonly microphone: MicrophoneManager;
 
+  /**
+   * The DynascaleManager instance.
+   */
+  readonly dynascaleManager = new DynascaleManager(this);
+
   /**
    * Flag telling whether this call is a "ringing" call.
    */
@@ -202,7 +201,7 @@ export class Call {
    * A typical use case is to clean up some global event handlers.
    * @private
    */
-  private readonly leaveCallHooks: Function[] = [];
+  private readonly leaveCallHooks: Set<Function> = new Set();
 
   private readonly streamClientBasePath: string;
   private streamClientEventHandlers = new Map<Function, CallEventHandler>();
@@ -253,12 +252,12 @@ export class Call {
       this.state.updateFromEvent(event);
     });
 
-    this.leaveCallHooks.push(
+    this.leaveCallHooks.add(
       registerEventHandlers(this, this.state, this.dispatcher),
     );
     this.registerEffects();
 
-    this.leaveCallHooks.push(
+    this.leaveCallHooks.add(
       createSubscription(
         this.trackSubscriptionsSubject.pipe(
           debounce((v) => timer(v.type)),
@@ -273,13 +272,15 @@ export class Call {
   }
 
   private registerEffects() {
-    this.leaveCallHooks.push(
+    this.leaveCallHooks.add(
       // handles updating the permissions context when the settings change.
       createSubscription(this.state.settings$, (settings) => {
         if (!settings) return;
         this.permissionsContext.setCallSettings(settings);
       }),
+    );
 
+    this.leaveCallHooks.add(
       // handle the case when the user permissions are modified.
       createSubscription(this.state.ownCapabilities$, (ownCapabilities) => {
         // update the permission context.
@@ -306,7 +307,9 @@ export class Call {
           }
         }
       }),
+    );
 
+    this.leaveCallHooks.add(
       // handles the case when the user is blocked by the call owner.
       createSubscription(this.state.blockedUserIds$, async (blockedUserIds) => {
         if (!blockedUserIds) return;
@@ -316,7 +319,9 @@ export class Call {
           await this.leave();
         }
       }),
+    );
 
+    this.leaveCallHooks.add(
       // watch for auto drop cancellation
       createSubscription(this.state.callingState$, (callingState) => {
         if (!this.ringing) return;
@@ -329,7 +334,9 @@ export class Call {
           this.dropTimeout = undefined;
         }
       }),
+    );
 
+    this.leaveCallHooks.add(
       // "ringing" mode effects and event handlers
       createSubscription(this.ringingSubject, (isRinging) => {
         if (!isRinging) return;
@@ -337,7 +344,7 @@ export class Call {
         if (this.state.callingState === CallingState.IDLE) {
           this.state.setCallingState(CallingState.RINGING);
         }
-        this.leaveCallHooks.push(registerRingingCallEventHandlers(this));
+        this.leaveCallHooks.add(registerRingingCallEventHandlers(this));
       }),
     );
   }
@@ -815,7 +822,7 @@ export class Call {
       },
     );
 
-    this.leaveCallHooks.push(() => {
+    this.leaveCallHooks.add(() => {
       unsubscribeOnlineEvent();
       unsubscribeOfflineEvent();
     });
@@ -904,7 +911,10 @@ export class Call {
         return currentParticipants.map((p) => {
           const participant: StreamVideoParticipant = Object.assign(p, {
             isLocalParticipant: p.sessionId === sfuClient.sessionId,
-            viewportVisibilityState: VisibilityState.UNKNOWN,
+            viewportVisibilityState: {
+              videoTrack: VisibilityState.UNKNOWN,
+              screenShareTrack: VisibilityState.UNKNOWN,
+            },
           });
           // We need to preserve the local state of the participant
           // (e.g. videoDimension, visibilityState, pinnedAt, etc.)
@@ -1108,22 +1118,42 @@ export class Call {
    * You have to create a subscription for each participant for all the different kinds of tracks you want to receive.
    * You can only subscribe for tracks after the participant started publishing the given kind of track.
    *
-   * @param kind the kind of subscription to update.
+   * @param trackType the kind of subscription to update.
    * @param changes the list of subscription changes to do.
    * @param type the debounce type to use for the update.
    */
   updateSubscriptionsPartial = (
-    kind: 'video' | 'screen',
+    trackType: VideoTrackType | 'video' | 'screen',
     changes: SubscriptionChanges,
     type: DebounceType = DebounceType.SLOW,
   ) => {
+    if (trackType === 'video') {
+      this.logger(
+        'warn',
+        `updateSubscriptionsPartial: ${trackType} is deprecated. Please switch to 'videoTrack'`,
+      );
+      trackType = 'videoTrack';
+    } else if (trackType === 'screen') {
+      this.logger(
+        'warn',
+        `updateSubscriptionsPartial: ${trackType} is deprecated. Please switch to 'screenShareTrack'`,
+      );
+      trackType = 'screenShareTrack';
+    }
+
     const participants = this.state.updateParticipants(
       Object.entries(changes).reduce<StreamVideoParticipantPatches>(
         (acc, [sessionId, change]) => {
+          if (change.dimension?.height) {
+            change.dimension.height = Math.ceil(change.dimension.height);
+          }
+          if (change.dimension?.width) {
+            change.dimension.width = Math.ceil(change.dimension.width);
+          }
           const prop: keyof StreamVideoParticipant | undefined =
-            kind === 'video'
+            trackType === 'videoTrack'
               ? 'videoDimension'
-              : kind === 'screen'
+              : trackType === 'screenShareTrack'
               ? 'screenShareDimension'
               : undefined;
           if (prop) {
@@ -1147,9 +1177,9 @@ export class Call {
     type: DebounceType = DebounceType.SLOW,
   ) => {
     const subscriptions: TrackSubscriptionDetails[] = [];
-    participants.forEach((p) => {
+    for (const p of participants) {
       // we don't want to subscribe to our own tracks
-      if (p.isLocalParticipant) return;
+      if (p.isLocalParticipant) continue;
 
       // NOTE: audio tracks don't have to be requested explicitly
       // as the SFU will implicitly subscribe us to all of them,
@@ -1174,7 +1204,7 @@ export class Call {
           dimension: p.screenShareDimension,
         });
       }
-    });
+    }
     // schedule update
     this.trackSubscriptionsSubject.next({ type, data: subscriptions });
   };
@@ -1680,7 +1710,7 @@ export class Call {
       )
       .subscribe();
 
-    this.leaveCallHooks.push(() => {
+    this.leaveCallHooks.add(() => {
       !subscription.closed && subscription.unsubscribe();
     });
   };
@@ -1800,4 +1830,90 @@ export class Call {
       await this.microphone.enable();
     }
   }
+
+  /**
+   * Will begin tracking the given element for visibility changes within the
+   * configured viewport element (`call.setViewport`).
+   *
+   * @param element the element to track.
+   * @param sessionId the session id.
+   * @param trackType the video mode.
+   */
+  trackElementVisibility = <T extends HTMLElement>(
+    element: T,
+    sessionId: string,
+    trackType: VideoTrackType,
+  ) => {
+    return this.dynascaleManager.trackElementVisibility(
+      element,
+      sessionId,
+      trackType,
+    );
+  };
+
+  /**
+   * Sets the viewport element to track bound video elements for visibility.
+   *
+   * @param element the viewport element.
+   */
+  setViewport = <T extends HTMLElement>(element: T) => {
+    return this.dynascaleManager.setViewport(element);
+  };
+
+  /**
+   * Binds a DOM <video> element to the given session id.
+   * This method will make sure that the video element will play
+   * the correct video stream for the given session id.
+   *
+   * Under the hood, it would also keep track of the video element dimensions
+   * and update the subscription accordingly in order to optimize the bandwidth.
+   *
+   * If a "viewport" is configured, the video element will be automatically
+   * tracked for visibility and the subscription will be updated accordingly.
+   *
+   * @param videoElement the video element to bind to.
+   * @param sessionId the session id.
+   * @param trackType the kind of video.
+   */
+  bindVideoElement = (
+    videoElement: HTMLVideoElement,
+    sessionId: string,
+    trackType: VideoTrackType,
+  ) => {
+    const unbind = this.dynascaleManager.bindVideoElement(
+      videoElement,
+      sessionId,
+      trackType,
+    );
+
+    if (!unbind) return;
+    this.leaveCallHooks.add(unbind);
+    return () => {
+      this.leaveCallHooks.delete(unbind);
+      unbind();
+    };
+  };
+
+  /**
+   * Binds a DOM <audio> element to the given session id.
+   *
+   * This method will make sure that the audio element will
+   * play the correct audio stream for the given session id.
+   *
+   * @param audioElement the audio element to bind to.
+   * @param sessionId the session id.
+   */
+  bindAudioElement = (audioElement: HTMLAudioElement, sessionId: string) => {
+    const unbind = this.dynascaleManager.bindAudioElement(
+      audioElement,
+      sessionId,
+    );
+
+    if (!unbind) return;
+    this.leaveCallHooks.add(unbind);
+    return () => {
+      this.leaveCallHooks.delete(unbind);
+      unbind();
+    };
+  };
 }

package/src/events/__tests__/participant.test.ts

@@ -34,7 +34,10 @@ describe('Participant events', () => {
         {
           userId: 'user-id',
           sessionId: 'session-id',
-          viewportVisibilityState: VisibilityState.UNKNOWN,
+          viewportVisibilityState: {
+            videoTrack: VisibilityState.UNKNOWN,
+            screenShareTrack: VisibilityState.UNKNOWN,
+          },
         },
       ]);
 

package/src/events/participant.ts

@@ -23,7 +23,10 @@ export const watchParticipantJoined = (state: CallState) => {
       Object.assign<StreamVideoParticipant, Partial<StreamVideoParticipant>>(
         participant,
         {
-          viewportVisibilityState: VisibilityState.UNKNOWN,
+          viewportVisibilityState: {
+            videoTrack: VisibilityState.UNKNOWN,
+            screenShareTrack: VisibilityState.UNKNOWN,
+          },
         },
       ),
     );