@100mslive/hms-video-store 0.14.6 → 0.14.7

package/dist/interfaces/index.d.ts

@@ -12,6 +12,7 @@ export type { HMSSimulcastLayerDefinition, SimulcastLayer, RID, HMSPreferredSimu
 export { HMSSimulcastLayer, simulcastMapping } from './simulcast-layers';
 export * from './track-settings';
 export * from './devices';
+export * from './track-interruption';
 export * from './playlist';
 export * from './rtmp-recording-config';
 export * from './hls-config';

package/dist/interfaces/preview-listener.d.ts

@@ -1,10 +1,11 @@
 import { DeviceChangeListener } from './devices';
 import { HMSPeer } from './peer';
 import { HMSRoom } from './room';
+import { TrackInterruptionListener } from './track-interruption';
 import { HMSPeerUpdate, HMSRoomUpdate, HMSTrackUpdate } from './update-listener';
 import { HMSException } from '../error/HMSException';
 import { HMSTrack } from '../media/tracks/HMSTrack';
-export interface HMSPreviewListener extends DeviceChangeListener {
+export interface HMSPreviewListener extends DeviceChangeListener, TrackInterruptionListener {
     onPreview(room: HMSRoom, localTracks: HMSTrack[]): void;
     onError(exception: HMSException): void;
     onReconnecting(error: HMSException): void;

package/dist/interfaces/track-interruption.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Emitted when a local track stops/starts producing media because the OS or another app took over
+ * the device - a phone call or a native voip app.
+ *
+ * Only raised for a device the user can do something about: the page is visible and the device is
+ * really not capturing. Backgrounding the tab on mobile stops the device too, but it is handed back
+ * on return, so that on its own is not reported - if it does not come back, the interruption is
+ * raised once the page is visible again.
+ */
+export interface HMSTrackInterruption {
+    /** true when the interruption starts, false when it ends */
+    started: boolean;
+    /** what triggered the interruption, eg. track-muted-natively, visibility-change */
+    reason: string;
+    type: 'audio' | 'video';
+    trackId: string;
+}
+export interface TrackInterruptionListener {
+    onTrackInterruption?(interruption: HMSTrackInterruption): void;
+}

package/dist/interfaces/update-listener.d.ts

@@ -6,6 +6,7 @@ import { HMSRoleChangeRequest } from './role-change-request';
 import { HMSRoom } from './room';
 import { HMSPoll, HMSWhiteboard, SessionStoreUpdate } from './session-store';
 import { HMSSpeaker } from './speaker';
+import { TrackInterruptionListener } from './track-interruption';
 import { HMSException } from '../error/HMSException';
 import { HMSTrack } from '../media/tracks/HMSTrack';
 import { MessageNotification } from '../notification-manager';
@@ -65,7 +66,7 @@ export interface InteractivityListener {
     onPollsUpdate(type: HMSPollsUpdate, polls: HMSPoll[]): void;
     onWhiteboardUpdate(whiteboard: HMSWhiteboard): void;
 }
-export interface HMSUpdateListener extends DeviceChangeListener, SessionStoreListener, InteractivityListener {
+export interface HMSUpdateListener extends DeviceChangeListener, SessionStoreListener, InteractivityListener, TrackInterruptionListener {
     onJoin(room: HMSRoom): void;
     onRoomUpdate(type: HMSRoomUpdate, room: HMSRoom): void;
     onPeerUpdate(type: HMSPeerUpdate, peer: HMSPeer | HMSPeer[] | null): void;

package/dist/media/tracks/HMSAudioTrack.d.ts

@@ -17,5 +17,6 @@ export declare class HMSAudioTrack extends HMSTrack {
     getOutputDevice(): MediaDeviceInfo | undefined;
     cleanup(): void;
     setOutputDevice(device?: MediaDeviceInfo): Promise<void>;
+    private logSetSinkIdSkipped;
     protected subscribeToAudio(value: boolean): Promise<void>;
 }

package/dist/media/tracks/HMSLocalAudioTrack.d.ts

@@ -21,6 +21,17 @@ export declare class HMSLocalAudioTrack extends HMSAudioTrack {
      */
     private tracksCreated;
     private permissionState?;
+    /**
+     * Set when the OS or another app takes the mic - an incoming call, a native voip app, or safari
+     * being backgrounded on iOS. The native track flags cannot be trusted once that has happened:
+     * iOS hands back a track that reports live and unmuted while its capture unit stays stopped, so
+     * recovery is driven off this instead of shouldReacquireTrack alone.
+     */
+    private interrupted;
+    /** whether the app has been told about an interruption, keeps the start/end pair intact */
+    private interruptionNotified;
+    /** in flight interruption recovery, see endInterruption */
+    private recovery?;
     audioLevelMonitor?: TrackAudioLevelMonitor;
     /**
      * see the doc in HMSLocalVideoTrack
@@ -36,6 +47,33 @@ export declare class HMSLocalAudioTrack extends HMSAudioTrack {
     getManuallySelectedDeviceId(): string | undefined;
     resetManuallySelectedDeviceId(): void;
     private handleVisibilityChange;
+    private handleForegrounded;
+    /**
+     * The mic cannot come back while the permission is not granted, so an interruption that is still
+     * open is raised now, on a visible page. Only one that was actually recorded: reaching here does
+     * not mean anything was taken away, since a peer that joined muted holds an empty track that
+     * reports itself as needing reacquisition for the whole session and never granted the permission.
+     */
+    private handlePermissionNotGranted;
+    /**
+     * The mic did not come back, and the user is now here to see it. Either signal is enough: the
+     * flags lie after an iOS interruption, where only `interrupted` - cleared once the track has
+     * actually been replaced - says whether recovery worked, and a mic that died without ever firing
+     * mute was never recorded as interrupted but does report it.
+     */
+    private notifyIfStillInterrupted;
+    private handleBackgrounded;
+    /**
+     * Interruption end. Both triggers - the native unmute and coming back to the foreground - have to
+     * do the same three things:
+     * 1. get a track that actually captures. Only a fresh getUserMedia is reliable here, the
+     *    interrupted track can report live and unmuted and still produce nothing.
+     * 2. re-publish the enabled state. On interruption start biz is told mute=true, on which every
+     *    remote peer unsubscribes from this peer's audio - they resubscribe only on the next update.
+     * 3. resume the remote playback the OS paused along with capture.
+     */
+    private endInterruption;
+    private restoreCapture;
     /**
      * Replace the new track in stream and update native track
      * @param track
@@ -83,9 +121,30 @@ export declare class HMSLocalAudioTrack extends HMSAudioTrack {
     private addTrackEventListeners;
     private removeTrackEventListeners;
     private trackPermissions;
+    private sendInterruptionAnalytics;
+    /**
+     * app facing interruption event, for a mic that is actually not capturing and a user who is there
+     * to see it. Two things it deliberately stays quiet about:
+     *
+     * - a hidden page. Backgrounding is not an interruption to prompt about even when the OS does stop
+     *   the mic, because the mic is reacquired on the way back. If it does not come back,
+     *   handleForegrounded raises it once the page is visible, which is the first moment a prompt is
+     *   worth anything.
+     * - an unpaired event. An end is only published after the mic has actually recovered, so a prompt
+     *   stays up while the mic is still unusable, and never for a start that was never published.
+     *
+     * The analytics events are not gated with it - interruption.start/stop record every interruption,
+     * including the ones the user never had to hear about.
+     */
+    private notifyInterruption;
     private handleTrackMute;
     /** @internal */
     handleTrackUnmute: () => Promise<void>;
+    /**
+     * A track that went through an interruption has to be replaced even when it reports live and
+     * unmuted - see `interrupted`.
+     */
+    private reacquireStaleTrack;
     private replaceSenderTrack;
     private shouldReacquireTrack;
     private buildNewSettings;

package/dist/media/tracks/HMSLocalVideoTrack.d.ts

@@ -16,6 +16,19 @@ export declare class HMSLocalVideoTrack extends HMSVideoTrack {
     private _layerDefinitions;
     private TAG;
     private enabledStateBeforeBackground;
+    /**
+     * Set when the OS or another app takes the camera - a video call, a native app, or safari being
+     * backgrounded on iOS. The native track flags cannot be trusted once that has happened, the
+     * resumed track can report live and unmuted while producing frozen frames, so recovery is driven
+     * off this.
+     */
+    private interrupted;
+    /** whether the app has been told about an interruption, keeps the start/end pair intact */
+    private interruptionNotified;
+    /** in flight interruption recovery, see endInterruption */
+    private recovery?;
+    /** the visibilitychange handler is only attached on mobile, see the constructor */
+    private recoversOnForeground;
     private permissionState?;
     /**
      * true if it's screenshare and current tab is what is being shared. Browser dependent, Chromium only
@@ -51,7 +64,7 @@ export declare class HMSLocalVideoTrack extends HMSVideoTrack {
      * use this function to set the enabled state of a track. If true the track will be unmuted and muted otherwise.
      * @param value
      */
-    setEnabled(value: boolean): Promise<void>;
+    setEnabled(value: boolean, skipcheck?: boolean, reason?: string): Promise<void>;
     private processPlugins;
     addStreamPlugins(plugins: HMSMediaStreamPlugin[]): Promise<void>;
     removeStreamPlugins(plugins: HMSMediaStreamPlugin[]): Promise<void>;
@@ -153,6 +166,34 @@ export declare class HMSLocalVideoTrack extends HMSVideoTrack {
     private addTrackEventListeners;
     private removeTrackEventListeners;
     private trackPermissions;
+    private sendInterruptionAnalytics;
+    /**
+     * app facing interruption event, for a camera that is actually not capturing and a user who is
+     * there to see it. Two things it deliberately stays quiet about:
+     *
+     * - a hidden page. The camera is released on the way out - by us, in handleBackgrounded - and
+     *   reacquired on the way back, so backgrounding on its own is nothing to prompt about. If the
+     *   camera does not come back, handleForegrounded raises it once the page is visible, which is the
+     *   first moment a prompt is worth anything.
+     * - an unpaired event. An end is only published after the camera has actually been reacquired, so
+     *   a prompt stays up while the tile is still frozen, and never for a start that was never
+     *   published.
+     *
+     * The analytics events are not gated with it - interruption.start/stop record every interruption,
+     * including the ones the user never had to see.
+     */
+    private notifyInterruption;
+    /**
+     * Interruption end, from either trigger - the native unmute or coming back to the foreground.
+     * The camera is reacquired only when it has to be, ie. the background path turned it off or the
+     * track reports it is not publishing; when the OS restarts capture itself, replaying the sinks is
+     * enough and a getUserMedia would only add a few hundred ms of frozen tile. Either way the enabled
+     * state is re-published, because interruption start published mute=true and remote peers stop
+     * rendering this peer's video until they see an update.
+     * @param enable the state to restore the camera to
+     */
+    private endInterruption;
+    private restoreCapture;
     private handleTrackMute;
     /** @internal */
     handleTrackUnmuteNatively: () => Promise<void>;
@@ -163,4 +204,14 @@ export declare class HMSLocalVideoTrack extends HMSVideoTrack {
      */
     private removeOrReplaceProcessedTrack;
     private handleVisibilityChange;
+    private handleForegrounded;
+    /**
+     * The camera did not come back, and the user is now here to see it. Either signal is enough.
+     * `interrupted` - cleared only once the camera is actually back - carries what the flags cannot:
+     * both failure paths leave a track that looks healthy, backgrounding swaps in a blank canvas track
+     * and a failed reacquire installs one too, so isTrackNotPublishing() is false in exactly the case
+     * worth prompting about. The flags carry the rest, a reacquire that handed back a muted camera.
+     */
+    private notifyIfStillInterrupted;
+    private handleBackgrounded;
 }

package/dist/playlist-manager/AudioContextManager.d.ts

@@ -5,9 +5,11 @@ export declare class AudioContextManager {
     private readonly TAG;
     constructor(element: HTMLMediaElement);
     /**
-     * Resume AudioContext if it is suspended
+     * Resume AudioContext if it is not running
      * Note: when the browser tab is muted by default, AudioContext will be in suspended state
      * It has to be resumed for the video/audio to be played.
+     * Safari also reports a non standard 'interrupted' state after an OS audio interruption - an
+     * incoming call or another app taking the audio session - which a check for 'suspended' misses.
      */
     resumeContext(): Promise<void>;
     getAudioTrack(): MediaStreamTrack;

package/dist/reactive-store/HMSNotifications.d.ts

@@ -23,6 +23,7 @@ export declare class HMSNotifications<T extends HMSGenericTypes = {
     sendChangeTrackStateRequest(request: HMSChangeTrackStateRequest): void;
     sendChangeMultiTrackStateRequest(request: HMSChangeMultiTrackStateRequest): void;
     sendPollUpdate(type: sdkTypes.HMSPollsUpdate, pollID: string): void;
+    sendTrackInterruption(interruption: sdkTypes.HMSTrackInterruption): void;
     sendTranscriptionUpdate(transcriptions?: sdkTypes.HMSTranscriptionInfo[]): void;
     private emitEvent;
     private createNotification;

package/dist/reactive-store/HMSSDKActions.d.ts

@@ -3,7 +3,7 @@ import { Diagnostics } from '../diagnostics';
 import { HMSSessionFeedback } from '../end-call-feedback';
 import { IHMSActions } from '../IHMSActions';
 import { IHMSStore } from '../IHMSStore';
-import { HMSAudioPlugin, HMSChangeMultiTrackStateRequest as SDKHMSChangeMultiTrackStateRequest, HMSChangeTrackStateRequest as SDKHMSChangeTrackStateRequest, HMSException as SDKHMSException, HMSLocalAudioTrack as SDKHMSLocalAudioTrack, HMSLocalTrack as SDKHMSLocalTrack, HMSLogLevel, HMSMediaStreamPlugin, HMSPluginSupportResult, HMSScreenShareConfig, HMSTrack as SDKHMSTrack, HMSVideoPlugin } from '../internal';
+import { HMSAudioPlugin, HMSChangeMultiTrackStateRequest as SDKHMSChangeMultiTrackStateRequest, HMSChangeTrackStateRequest as SDKHMSChangeTrackStateRequest, HMSException as SDKHMSException, HMSLocalAudioTrack as SDKHMSLocalAudioTrack, HMSLocalTrack as SDKHMSLocalTrack, HMSLocalVideoTrack as SDKHMSLocalVideoTrack, HMSLogLevel, HMSMediaStreamPlugin, HMSPluginSupportResult, HMSScreenShareConfig, HMSTrack as SDKHMSTrack, HMSVideoPlugin } from '../internal';
 import * as sdkTypes from '../internal';
 import { MessageNotification } from '../notification-manager';
 import { HMSChangeMultiTrackStateParams, HMSGenericTypes, HMSMessage, HMSPeer, HMSPeerListIteratorOptions, HMSRoleName, HMSTrackID, HMSTrackSource, IHMSPlaylistActions, IHMSSessionStoreActions } from '../schema';
@@ -55,7 +55,7 @@ export declare class HMSSDKActions<T extends HMSGenericTypes = {
     setAudioOutputDevice(deviceId: string): Promise<void>;
     setPreferredLayer(trackId: string, layer: sdkTypes.HMSPreferredSimulcastLayer): Promise<void>;
     getNativeTrackById(trackId: string): MediaStreamTrack | undefined;
-    getTrackById(trackId: string): SDKHMSTrack | SDKHMSLocalAudioTrack | undefined;
+    getTrackById(trackId: string): SDKHMSTrack | SDKHMSLocalAudioTrack | SDKHMSLocalVideoTrack | undefined;
     getAuthTokenByRoomCode(tokenRequest: sdkTypes.TokenRequest, tokenRequestOptions?: sdkTypes.TokenRequestOptions): Promise<string>;
     preview(config: sdkTypes.HMSPreviewConfig): Promise<void>;
     cancelMidCallPreview(): Promise<void>;
@@ -141,6 +141,7 @@ export declare class HMSSDKActions<T extends HMSGenericTypes = {
     private sdkJoinWithListeners;
     private onSFUMigration;
     private onRemovedFromRoom;
+    private onTrackInterruption;
     private onDeviceChange;
     private sdkPreviewWithListeners;
     private onNetworkQuality;

package/dist/schema/notification.d.ts

@@ -4,7 +4,7 @@ import { HMSMessage } from './message';
 import { HMSPeer, HMSTrack } from './peer';
 import { HMSPlaylistItem } from './playlist';
 import { HMSChangeMultiTrackStateRequest, HMSChangeTrackStateRequest, HMSLeaveRoomRequest } from './requests';
-import { HMSPoll, HMSTranscriptionInfo } from '../internal';
+import { HMSPoll, HMSTrackInterruption, HMSTranscriptionInfo } from '../internal';
 interface BaseNotification {
     id: number;
     type: string;
@@ -59,11 +59,15 @@ export interface HMSPollNotification extends BaseNotification {
     type: HMSNotificationTypes.POLL_STARTED | HMSNotificationTypes.POLL_STOPPED | HMSNotificationTypes.POLL_VOTES_UPDATED;
     data: HMSPoll;
 }
+export interface HMSTrackInterruptionNotification extends BaseNotification {
+    type: HMSNotificationTypes.TRACK_INTERRUPTION_START | HMSNotificationTypes.TRACK_INTERRUPTION_END;
+    data: HMSTrackInterruption;
+}
 export interface HMSTranscriptionNotification extends BaseNotification {
     type: HMSNotificationTypes.TRANSCRIPTION_STATE_UPDATED;
     data: HMSTranscriptionInfo[];
 }
-export declare type HMSNotification = HMSPeerNotification | HMSPeerListNotification | HMSTrackNotification | HMSMessageNotification | HMSExceptionNotification | HMSChangeTrackStateRequestNotification | HMSChangeMultiTrackStateRequestNotification | HMSLeaveRoomRequestNotification | HMSDeviceChangeEventNotification | HMSReconnectionNotification | HMSTranscriptionNotification | HMSPlaylistItemNotification<any>;
+export declare type HMSNotification = HMSPeerNotification | HMSPeerListNotification | HMSTrackNotification | HMSMessageNotification | HMSExceptionNotification | HMSChangeTrackStateRequestNotification | HMSChangeMultiTrackStateRequestNotification | HMSLeaveRoomRequestNotification | HMSDeviceChangeEventNotification | HMSReconnectionNotification | HMSTrackInterruptionNotification | HMSTranscriptionNotification | HMSPlaylistItemNotification<any>;
 export declare enum HMSNotificationSeverity {
     INFO = "info",
     ERROR = "error"
@@ -98,7 +102,9 @@ export declare enum HMSNotificationTypes {
     POLL_VOTES_UPDATED = "POLL_VOTES_UPDATED",
     POLLS_LIST = "POLLS_LIST",
     HAND_RAISE_CHANGED = "HAND_RAISE_CHANGED",
-    TRANSCRIPTION_STATE_UPDATED = "TRANSCRIPTION_STATE_UPDATED"
+    TRANSCRIPTION_STATE_UPDATED = "TRANSCRIPTION_STATE_UPDATED",
+    TRACK_INTERRUPTION_START = "TRACK_INTERRUPTION_START",
+    TRACK_INTERRUPTION_END = "TRACK_INTERRUPTION_END"
 }
 export declare type HMSNotificationMapping<T extends HMSNotificationTypes, C = any> = {
     [HMSNotificationTypes.PEER_JOINED]: HMSPeerNotification;
@@ -132,6 +138,8 @@ export declare type HMSNotificationMapping<T extends HMSNotificationTypes, C = a
     [HMSNotificationTypes.POLL_CREATED]: HMSPollNotification;
     [HMSNotificationTypes.HAND_RAISE_CHANGED]: HMSPeerNotification;
     [HMSNotificationTypes.TRANSCRIPTION_STATE_UPDATED]: HMSTranscriptionNotification;
+    [HMSNotificationTypes.TRACK_INTERRUPTION_START]: HMSTrackInterruptionNotification;
+    [HMSNotificationTypes.TRACK_INTERRUPTION_END]: HMSTrackInterruptionNotification;
 }[T];
 export declare type MappedNotifications<Type extends HMSNotificationTypes[]> = {
     [index in keyof Type]: HMSNotificationMapping<Type[index]>;

package/dist/schema/peer.d.ts

@@ -61,6 +61,14 @@ interface BaseTrack {
      * false for preview tracks
      */
     isPublished?: boolean;
+    /**
+     * only applicable for local tracks - true while the OS or another app has taken the device, eg.
+     * an incoming call. Cleared once capture is back, however it came back.
+     *
+     * Backgrounding the tab on mobile is not reported here: the device is handed back on return. It
+     * is set on return if the device did not come back.
+     */
+    interrupted?: boolean;
 }
 export interface HMSAudioTrack extends BaseTrack {
     source: 'regular' | 'audioplaylist' | string;

package/dist/sdk/index.d.ts

@@ -85,6 +85,7 @@ export declare class HMSSdk implements HMSInterface {
     private handlePreviewError;
     private midCallPreview;
     cancelMidCallPreview(): Promise<void>;
+    private handleTrackInterruption;
     private handleDeviceChange;
     private handleAudioPluginError;
     /**

package/dist/sdk/store/Store.d.ts

@@ -48,7 +48,7 @@ declare class Store {
     getPeerTracks(peerId?: string): HMSTrack[];
     getLocalPeerTracks(): HMSLocalTrack[];
     hasTrack(track: HMSTrack): boolean;
-    getTrackById(trackId: string): HMSTrack | import("../../media/tracks").HMSLocalAudioTrack | undefined;
+    getTrackById(trackId: string): HMSTrack | import("../../media/tracks").HMSLocalAudioTrack | import("../../media/tracks").HMSLocalVideoTrack | undefined;
     getPeerByTrackId(trackId: string): HMSPeer | undefined;
     getSpeakers(): HMSSpeaker[];
     getSpeakerPeers(): HMSPeer[];

package/dist/selectors/selectors.d.ts

@@ -192,6 +192,19 @@ export declare const selectIsLocalAudioEnabled: (store: HMSStore) => boolean;
  * and the video from your camera is shared to remote peers
  */
 export declare const selectIsLocalVideoEnabled: (store: HMSStore) => boolean;
+/**
+ * Select a boolean denoting whether the OS or another app has taken your microphone, eg. an
+ * incoming call. Cleared once capture is back, however it came back.
+ *
+ * Backgrounding the tab on mobile does not set this - the mic is handed back on return. It is set
+ * on return if the mic did not come back.
+ */
+export declare const selectIsLocalAudioInterrupted: (store: HMSStore) => boolean;
+/**
+ * Select a boolean denoting whether the OS or another app has taken your camera.
+ * @see selectIsLocalAudioInterrupted
+ */
+export declare const selectIsLocalVideoInterrupted: (store: HMSStore) => boolean;
 /**
  * Select a boolean denoting whether you've chosen to unmute and share your local video.
  *

package/dist/utils/constants.d.ts

@@ -36,6 +36,7 @@ export declare const HMSEvents: {
     TRACK_RESTORED: string;
     TRACK_AUDIO_LEVEL_UPDATE: string;
     LOCAL_AUDIO_SILENCE: string;
+    TRACK_INTERRUPTION: string;
     ANALYTICS: string;
     AUDIO_PLUGIN_FAILED: string;
     POLICY_CHANGE: string;

package/dist/utils/support.d.ts

@@ -18,6 +18,12 @@ export declare enum ENV {
 }
 export declare const isSupported: boolean;
 export declare const isMobile: () => boolean;
+/**
+ * Handheld platforms do not hand capture back to a backgrounded page, so anything that reacquires a
+ * device has to wait for the foreground there. Tablets behave like phones for this and iPads are the
+ * common case, so neither the tablet device type nor iPadOS can be left out.
+ */
+export declare const isMobileOrTablet: () => boolean;
 export declare const isPageHidden: () => boolean;
 export declare const isIOS: () => boolean;
 export declare const isSafari: boolean | undefined;

package/package.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.14.6",
+  "version": "0.14.7",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -72,5 +72,5 @@
     "conferencing",
     "100ms"
   ],
-  "gitHead": "df44d2da0bf8bca9434b00f0f1021559bd2f45d7"
+  "gitHead": "0bea9e63f6501bae6109370f02b97e493e0c84c7"
 }