@100mslive/react-sdk 0.0.16 → 0.0.18-alpha.0

package/src/hooks/useAutoplayError.ts

@@ -0,0 +1,41 @@
+import { useCallback, useEffect, useState } from 'react';
+import { HMSNotificationTypes } from '@100mslive/hms-video-store';
+import { useHMSActions, useHMSNotifications } from '../primitives/HmsRoomProvider';
+
+export interface useAutoplayErrorResult {
+  /*
+   * Autoplay error message
+   */
+  error: string;
+  /**
+   * call this method on a UI element click to unblock the blocked audio autoplay.
+   */
+  unblockAudio: () => Promise<void>;
+  /**
+   * Call this method to reset(hide) the UI that is rendered when there was an error
+   */
+  resetError: () => void;
+}
+
+/**
+ * Use this hook to show a UI(modal or a toast) when autoplay is blocked by browser and allow the user to
+ * unblock the browser autoplay block
+ * @returns {useAutoplayErrorResult}
+ */
+export const useAutoplayError = (): useAutoplayErrorResult => {
+  const notification = useHMSNotifications(HMSNotificationTypes.ERROR);
+  const [error, setError] = useState('');
+  const actions = useHMSActions();
+
+  const unblockAudio = useCallback(async () => {
+    await actions.unblockAudio();
+  }, [actions]);
+
+  useEffect(() => {
+    if (notification?.data.code === 3008) {
+      setError(notification?.data.message);
+    }
+  }, [notification]);
+
+  return { error, unblockAudio, resetError: () => setError('') };
+};

package/src/hooks/useCustomEvent.ts

@@ -0,0 +1,85 @@
+import { useHMSActions, useHMSVanillaNotifications } from '../primitives/HmsRoomProvider';
+import { useCallback, useEffect } from 'react';
+import { HMSNotificationTypes } from '@100mslive/hms-video-store';
+import { hooksErrHandler } from './types';
+import { logErrorHandler } from '../utils/commons';
+
+export interface useCustomEventInput<T> {
+  /**
+   * type of the event, e.g. MODERATOR_EVENT, EMOJI_REACTIONS etc.
+   */
+  type: string;
+  /**
+   * the handler function for when the custom event comes. It's recommended
+   * to use `useCallback` for the function passed in here for performance
+   * reasons.
+   * The callback is optional in case you want to decouple sending event and
+   * handling event in the UI.
+   */
+  onEvent?: (data: T) => void;
+  /**
+   * function to handle errors happening during sending the event
+   */
+  handleError?: hooksErrHandler;
+}
+
+export interface useCustomEventResult<T> {
+  /**
+   * sends the event data to others in the room who will receive it in onEvent
+   */
+  sendEvent: (data: T) => void;
+}
+
+/**
+ * A generic function to implement [custom events](https://www.100ms.live/docs/javascript/v2/features/chat#custom-events) in your UI.
+ * The data to be sent to remote is expected to be a serializable JSON. The serialization
+ * and deserialization is taken care of by the hook.
+ */
+export const useCustomEvent = <T>({
+  type,
+  onEvent,
+  handleError = logErrorHandler,
+}: useCustomEventInput<T>): useCustomEventResult<T> => {
+  const actions = useHMSActions();
+  const notifications = useHMSVanillaNotifications();
+
+  useEffect(() => {
+    // we don't want these messages to be stored in store reserving that for chat messages
+    actions.ignoreMessageTypes([type]);
+  }, [actions, type]);
+
+  // this is to handle messages from remote peers
+  useEffect(() => {
+    if (!notifications) {
+      return;
+    }
+    const unsubscribe = notifications.onNotification(notification => {
+      const msg = notification.data;
+      if (msg && msg.type === type) {
+        try {
+          const data = JSON.parse(msg.message);
+          onEvent?.(data as T);
+        } catch (err) {
+          handleError(err as Error, 'handleCustomEvent');
+        }
+      }
+    }, HMSNotificationTypes.NEW_MESSAGE);
+    return unsubscribe;
+  }, [notifications, type, onEvent, handleError]);
+
+  // this is to send message to remote peers and call onEvent
+  const sendEvent = useCallback(
+    async (data: T) => {
+      try {
+        const dataStr = JSON.stringify(data || '');
+        await actions.sendBroadcastMessage(dataStr, type);
+        onEvent?.(data);
+      } catch (err) {
+        handleError(err as Error, 'sendCustomEvent');
+      }
+    },
+    [actions, handleError, onEvent, type],
+  );
+
+  return { sendEvent };
+};

package/src/hooks/useDevices.ts

@@ -0,0 +1,93 @@
+import { selectDevices, selectIsAllowedToPublish, selectLocalMediaSettings } from '@100mslive/hms-video-store';
+import { useCallback } from 'react';
+import { useHMSActions, useHMSStore } from '../primitives/HmsRoomProvider';
+import { logErrorHandler } from '../utils/commons';
+import { hooksErrHandler } from '../hooks/types';
+
+export enum DeviceType {
+  videoInput = 'videoInput',
+  audioInput = 'audioInput',
+  audioOutput = 'audioOutput',
+}
+
+export type DeviceTypeAndInfo<T> = {
+  [key in DeviceType]?: T;
+};
+
+export interface useDevicesResult {
+  /**
+   * list of all devices by type
+   */
+  allDevices: DeviceTypeAndInfo<MediaDeviceInfo[]>;
+  /**
+   * selected device ids for all types
+   */
+  selectedDeviceIDs: DeviceTypeAndInfo<string>;
+  /**
+   * function to call to update device
+   */
+  updateDevice: ({ deviceType, deviceId }: { deviceType: DeviceType; deviceId: string }) => Promise<void>;
+}
+
+/**
+ * This hook can be used to implement a UI component which allows the user to manually change their
+ * audio/video device. It returns the list of all devices as well as the currently selected one. The input
+ * devices will be returned based on what the user is allowed to publish, so a audio only user won't get
+ * the audioInput field. This can be used to show the UI dropdowns properly.
+ *
+ * Note:
+ * - Browsers give access to the list of devices only if the user has given permission to access them
+ * - Changing devices manually work best in combination with remembering the user's selection for the next time, do
+ *   pass the rememberDeviceSelection flag at time of join for this to happen.
+ *
+ * @param handleError error handler for any errors during device change
+ */
+export const useDevices = (handleError: hooksErrHandler = logErrorHandler): useDevicesResult => {
+  const actions = useHMSActions();
+  const sdkAllDevices: DeviceTypeAndInfo<MediaDeviceInfo[]> = useHMSStore(selectDevices);
+  const sdkSelectedDevices = useHMSStore(selectLocalMediaSettings);
+  const isAllowedToPublish = useHMSStore(selectIsAllowedToPublish);
+
+  const selectedDeviceIDs: DeviceTypeAndInfo<string> = {
+    [DeviceType.audioOutput]: sdkSelectedDevices.audioOutputDeviceId,
+  };
+  const allDevices: DeviceTypeAndInfo<MediaDeviceInfo[]> = {
+    [DeviceType.audioOutput]: sdkAllDevices.audioOutput,
+  };
+
+  if (isAllowedToPublish.video) {
+    allDevices[DeviceType.videoInput] = sdkAllDevices.videoInput;
+    selectedDeviceIDs[DeviceType.videoInput] = sdkSelectedDevices.videoInputDeviceId;
+  }
+  if (isAllowedToPublish.audio) {
+    allDevices[DeviceType.audioInput] = sdkAllDevices.audioInput;
+    selectedDeviceIDs[DeviceType.audioInput] = sdkSelectedDevices.audioInputDeviceId;
+  }
+
+  const updateDevice = useCallback(
+    async ({ deviceType, deviceId }: { deviceType: DeviceType; deviceId: string }) => {
+      try {
+        switch (deviceType) {
+          case DeviceType.audioInput:
+            await actions.setAudioSettings({ deviceId });
+            break;
+          case DeviceType.videoInput:
+            await actions.setVideoSettings({ deviceId });
+            break;
+          case DeviceType.audioOutput:
+            actions.setAudioOutputDevice(deviceId);
+            break;
+        }
+      } catch (err) {
+        handleError(err as Error, 'updateDevices');
+      }
+    },
+    [handleError, actions],
+  );
+
+  return {
+    allDevices,
+    selectedDeviceIDs,
+    updateDevice,
+  };
+};

package/src/hooks/useParticipantList.ts

@@ -0,0 +1,27 @@
+import { useMemo } from 'react';
+import {
+  HMSPeer,
+  HMSRoleName,
+  selectIsConnectedToRoom,
+  selectPeerCount,
+  selectPeers,
+  selectRemotePeers,
+} from '@100mslive/hms-video-store';
+import { useHMSStore } from '../primitives/HmsRoomProvider';
+import { groupByRoles } from '../utils/groupBy';
+
+export interface useParticipantListResult {
+  roles: HMSRoleName[];
+  participantsByRoles: Record<string, HMSPeer[]>;
+  peerCount: number;
+  isConnected: boolean;
+}
+
+export const useParticipantList = () => {
+  const isConnected = useHMSStore(selectIsConnectedToRoom);
+  const participantList = useHMSStore(isConnected ? selectPeers : selectRemotePeers);
+  const peerCount = useHMSStore(selectPeerCount);
+  const participantsByRoles = useMemo(() => groupByRoles(participantList), [participantList]);
+  const roles = Object.keys(participantsByRoles);
+  return { roles, participantsByRoles, peerCount, isConnected };
+};

package/src/hooks/usePreviewJoin.ts

@@ -0,0 +1,132 @@
+import {
+  HMSRoomState,
+  selectIsConnectedToRoom,
+  selectRoomState,
+  HMSConfigInitialSettings,
+} from '@100mslive/hms-video-store';
+import { useCallback, useMemo } from 'react';
+import { useHMSActions, useHMSStore } from '../primitives/HmsRoomProvider';
+import { hooksErrHandler } from './types';
+import { logErrorHandler } from '../utils/commons';
+import { HMSConfig } from '@100mslive/hms-video';
+
+export interface usePreviewInput {
+  /**
+   * name of user who is joining, this is only required if join is called
+   */
+  name?: string;
+  /**
+   * app side authentication token
+   */
+  token: string;
+  /**
+   * any extra metadata info for the peer
+   */
+  metadata?: string;
+  /**
+   * function to handle errors happening during preview
+   */
+  handleError?: hooksErrHandler;
+  initEndpoint?: string;
+  /**
+   * initial settings for audio/video and device to be used.
+   */
+  initialSettings?: HMSConfigInitialSettings;
+  /**
+   * Enable to get a network quality score while in preview. The score ranges from -1 to 5.
+   * -1 when we are not able to connect to 100ms servers within an expected time limit
+   * 0 when there is a timeout/failure when measuring the quality
+   * 1-5 ranges from poor to good quality.
+   */
+  captureNetworkQualityInPreview?: boolean;
+}
+
+export interface usePreviewResult {
+  /**
+   * enable the join button for the user only when this is true
+   */
+  enableJoin: boolean;
+  /**
+   * call this function to join the room
+   */
+  join: () => void;
+  /**
+   * once the user has joined the room, till leave happens this flag will be true. It can be used
+   * to decide to show between preview form and conferencing component/video tiles.
+   */
+  isConnected: boolean;
+  /**
+   * call this function to join the room
+   */
+  preview: () => void;
+}
+
+/**
+ * This hook can be used to build a preview UI component, this lets you call preview everytime the passed in
+ * token changes. This hook is best used in combination with useDevices for changing devices, useAVToggle for
+ * muting/unmuting and useAudioLevelStyles for showing mic audio level to the user.
+ * Any device change or mute/unmute will be carried across to join.
+ */
+export const usePreviewJoin = ({
+  name = '',
+  token,
+  metadata,
+  handleError = logErrorHandler,
+  initEndpoint,
+  initialSettings,
+  captureNetworkQualityInPreview,
+}: usePreviewInput): usePreviewResult => {
+  const actions = useHMSActions();
+  const roomState = useHMSStore(selectRoomState);
+  const isConnected = useHMSStore(selectIsConnectedToRoom) || false;
+  const enableJoin = roomState === HMSRoomState.Preview;
+
+  const config: HMSConfig = useMemo(() => {
+    return {
+      userName: name,
+      authToken: token,
+      metaData: metadata,
+      rememberDeviceSelection: true,
+      settings: initialSettings,
+      initEndpoint: initEndpoint,
+      captureNetworkQualityInPreview,
+    };
+  }, [name, token, metadata, initEndpoint, initialSettings, captureNetworkQualityInPreview]);
+
+  const preview = useCallback(() => {
+    (async () => {
+      if (!token) {
+        return;
+      }
+      if (roomState !== HMSRoomState.Disconnected) {
+        return;
+      }
+      if (isConnected) {
+        await actions.leave();
+      }
+      try {
+        await actions.preview(config);
+      } catch (err) {
+        handleError(err as Error, 'preview');
+      }
+    })();
+  }, [actions, handleError, token, roomState, config, isConnected]);
+
+  const join = useCallback(() => {
+    if (!token) {
+      return;
+    }
+    try {
+      actions.join(config);
+    } catch (err) {
+      handleError(err as Error, 'join');
+    }
+  }, [actions, config, handleError, token]);
+
+  return {
+    enableJoin,
+    join,
+    isConnected,
+    preview,
+  };
+};

package/src/hooks/useRecordingStreaming.ts

@@ -0,0 +1,34 @@
+import { selectHLSState, selectRecordingState, selectRTMPState } from '@100mslive/hms-video-store';
+import { useHMSStore } from '../primitives/HmsRoomProvider';
+
+export interface useRecordingStreamingResult {
+  isServerRecordingOn: boolean;
+  isBrowserRecordingOn: boolean;
+  isHLSRecordingOn: boolean;
+  isStreamingOn: boolean;
+  isHLSRunning: boolean;
+  isRTMPRunning: boolean;
+  isRecordingOn: boolean;
+}
+
+export const useRecordingStreaming = (): useRecordingStreamingResult => {
+  const recording = useHMSStore(selectRecordingState);
+  const rtmp = useHMSStore(selectRTMPState);
+  const hls = useHMSStore(selectHLSState);
+
+  const isServerRecordingOn = recording.server.running;
+  const isBrowserRecordingOn = recording.browser.running;
+  const isHLSRecordingOn = recording.hls.running;
+  const isStreamingOn = hls.running || rtmp.running;
+  const isRecordingOn = isServerRecordingOn || isBrowserRecordingOn || isHLSRecordingOn;
+
+  return {
+    isServerRecordingOn,
+    isBrowserRecordingOn,
+    isHLSRecordingOn,
+    isStreamingOn,
+    isHLSRunning: hls.running,
+    isRTMPRunning: rtmp.running,
+    isRecordingOn,
+  };
+};

package/src/hooks/useRemoteAVToggle.ts

@@ -0,0 +1,101 @@
+/* eslint-disable complexity */
+import {
+  HMSActions,
+  HMSTrack,
+  HMSTrackID,
+  selectAudioTrackVolume,
+  selectPermissions,
+  selectTrackByID,
+} from '@100mslive/hms-video-store';
+import { useHMSActions, useHMSStore } from '../primitives/HmsRoomProvider';
+import { useCallback } from 'react';
+import { hooksErrHandler } from './types';
+import { logErrorHandler } from '../utils/commons';
+
+export interface useRemoteAVToggleResult {
+  /**
+   * true if unmuted and vice versa
+   */
+  isAudioEnabled: boolean;
+  isVideoEnabled: boolean;
+  /**
+   * current volume of the audio track
+   */
+  volume?: number;
+  /**
+   * use this function to toggle audio state, the function will only be present if the user
+   * has permission to mute/unmute remote audio
+   */
+  toggleAudio?: () => void;
+  /**
+   * use this function to toggle video state, the function will only be present if the user
+   * has permission to mute/unmute remote video
+   */
+  toggleVideo?: () => void;
+  /**
+   * use this function to set the volume of peer's audio track for the local user, the function will
+   * only be present if the remote peer has an audio track to change volume for
+   */
+  setVolume?: (volume: number) => void;
+}
+
+const toggleTrackEnabled = async (
+  actions: HMSActions,
+  track: HMSTrack | undefined | null,
+  handleError: hooksErrHandler,
+) => {
+  if (track) {
+    try {
+      await actions.setRemoteTrackEnabled(track.id, !track.enabled);
+    } catch (err) {
+      handleError(err as Error, 'remoteToggle');
+    }
+  }
+};
+
+/**
+ * This hook can be used to implement remote mute/unmute + audio volume changer on tile level.
+ * @param peerId of the peer whose tracks need to be managed
+ * @param audioTrackId of the peer whose tracks need to be managed
+ * @param videoTrackId of the peer whose tracks need to be managed
+ * @param handleError to handle any error during toggle of audio/video
+ */
+export const useRemoteAVToggle = (
+  audioTrackId: HMSTrackID,
+  videoTrackId: HMSTrackID,
+  handleError: hooksErrHandler = logErrorHandler,
+): useRemoteAVToggleResult => {
+  const actions = useHMSActions();
+  const audioTrack = useHMSStore(selectTrackByID(audioTrackId));
+  const videoTrack = useHMSStore(selectTrackByID(videoTrackId));
+  const volume = useHMSStore(selectAudioTrackVolume(audioTrack?.id));
+  const permissions = useHMSStore(selectPermissions);
+  const canToggleVideo = videoTrack?.enabled ? permissions?.mute : permissions?.unmute;
+  const canToggleAudio = audioTrack?.enabled ? permissions?.mute : permissions?.unmute;
+
+  const toggleAudio = useCallback(async () => {
+    await toggleTrackEnabled(actions, audioTrack, handleError);
+  }, [actions, audioTrack, handleError]);
+
+  const toggleVideo = useCallback(async () => {
+    await toggleTrackEnabled(actions, videoTrack, handleError);
+  }, [actions, handleError, videoTrack]);
+
+  const setVolume = useCallback(
+    (volume: number) => {
+      if (audioTrack) {
+        actions.setVolume(volume, audioTrack.id);
+      }
+    },
+    [actions, audioTrack],
+  );
+
+  return {
+    isAudioEnabled: !!audioTrack?.enabled,
+    isVideoEnabled: !!videoTrack?.enabled,
+    volume,
+    toggleAudio: audioTrack && canToggleAudio ? toggleAudio : undefined,
+    toggleVideo: videoTrack?.source === 'regular' && canToggleVideo ? toggleVideo : undefined,
+    setVolume: audioTrack ? setVolume : undefined,
+  };
+};

package/src/hooks/useScreenShare.ts

@@ -0,0 +1,76 @@
+import { hooksErrHandler } from '../hooks/types';
+import {
+  HMSPeerID,
+  HMSTrackID,
+  selectIsLocalScreenShared,
+  selectPeerScreenSharing,
+  selectScreenSharesByPeerId,
+} from '@100mslive/hms-video-store';
+import { useHMSActions, useHMSStore } from '../primitives/HmsRoomProvider';
+import { useCallback } from 'react';
+import { logErrorHandler } from '../utils/commons';
+
+export interface useScreenShareResult {
+  /**
+   * true if the local user is screensharing, false otherwise
+   */
+  amIScreenSharing: boolean;
+  /**
+   * toggle screenshare for the local user, will only be present if the user has the permission to toggle
+   */
+  toggleScreenShare?: () => void;
+  /**
+   * the id of the peer who is currently screensharing, will only be present if there is a screenshare in the room.
+   * In case of multiple screenshares, the behaviour of which one is picked is not defined.
+   */
+  screenSharingPeerId?: HMSPeerID;
+  /**
+   * the name of the peer who is currently screensharing. Will be undefined if no one is sharing the screen.
+   * In case of multiple screenshares, the behavior of which one is picked is not defined.
+   */
+  screenSharingPeerName?: string;
+  /**
+   * screenShare audio track id, will only be present if there is a screenshare with video track
+   */
+  screenShareVideoTrackId?: HMSTrackID;
+  /**
+   * screenShare audio track id, will only be present if there is a screenshare with audio track
+   */
+  screenShareAudioTrackId?: HMSTrackID;
+}
+
+/**
+ * This hook can be used to implement a screenshare toggle button as well as know about the screenshare in the room.
+ * This works best if your application only needs to show one screenshare in large view at a time with other screenshares
+ * similar to normal user tiles.
+ * For any complicated requirement with multiple screenshares it's best to use the store directly.
+ * For viewing the screenshare this hook is best used in combination with useVideo.
+ * For implementing control bar for local peer, this is used based with useAVToggle.
+ * @param handleError to handle any errors during screenshare toggle
+ */
+export const useScreenShare = (handleError: hooksErrHandler = logErrorHandler): useScreenShareResult => {
+  const actions = useHMSActions();
+  const amIScreenSharing = useHMSStore(selectIsLocalScreenShared);
+  const screenSharePeer = useHMSStore(selectPeerScreenSharing);
+  const screenShare = useHMSStore(selectScreenSharesByPeerId(screenSharePeer?.id));
+
+  const toggleScreenShare = useCallback(
+    async (audioOnly = false) => {
+      try {
+        await actions.setScreenShareEnabled(!amIScreenSharing, audioOnly);
+      } catch (err) {
+        handleError(err as Error, 'toggleScreenShare');
+      }
+    },
+    [actions, amIScreenSharing, handleError],
+  );
+
+  return {
+    amIScreenSharing,
+    screenSharingPeerId: screenSharePeer?.id,
+    screenSharingPeerName: screenSharePeer?.name,
+    screenShareVideoTrackId: screenShare?.video?.id,
+    screenShareAudioTrackId: screenShare?.audio?.id,
+    toggleScreenShare,
+  };
+};

package/src/hooks/useVideo.ts

@@ -0,0 +1,77 @@
+import { selectTrackByID, HMSTrackID } from '@100mslive/hms-video-store';
+import React, { useCallback, useEffect, useRef } from 'react';
+import { useInView } from 'react-intersection-observer';
+import { useHMSActions, useHMSStore } from '../primitives/HmsRoomProvider';
+import HMSLogger from '../utils/logger';
+
+export interface useVideoInput {
+  /**
+   * TrackId that is to be rendered
+   */
+  trackId?: HMSTrackID;
+  /**
+   * Boolean stating whether to override the internal behaviour.
+   * when attach is false, even if tile is inView or enabled, it won't be rendered
+   */
+  attach?: boolean;
+}
+
+export interface useVideoOutput {
+  videoRef: React.RefCallback<HTMLVideoElement>;
+}
+/**
+ * This hooks can be used to implement a video tile component. Given a track id it will return a ref.
+ * The returned ref can be used to set on a video element meant to display the video.
+ * The hook will take care of attaching and detaching video, and will automatically detach when the video
+ * goes out of view to save on bandwidth.
+ */
+export const useVideo = ({ trackId, attach }: useVideoInput): useVideoOutput => {
+  const actions = useHMSActions();
+  const videoRef = useRef<HTMLVideoElement | null>(null);
+  const track = useHMSStore(selectTrackByID(trackId));
+
+  const { ref: inViewRef, inView } = useInView({ threshold: 0.5 });
+
+  const setRefs = useCallback(
+    (node: HTMLVideoElement) => {
+      if (node) {
+        videoRef.current = node;
+        inViewRef(node);
+      }
+    },
+    [inViewRef],
+  );
+
+  useEffect(() => {
+    (async () => {
+      if (videoRef.current && track?.id) {
+        if (inView && track.enabled && attach !== false) {
+          // attach when in view and enabled
+          await actions.attachVideo(track.id, videoRef.current);
+        } else {
+          // detach when not in view
+          await actions.detachVideo(track.id, videoRef.current);
+        }
+      }
+    })();
+  }, [actions, inView, videoRef, track?.id, track?.enabled, track?.deviceID, track?.plugins, attach]);
+
+  // detach on unmount
+  useEffect(() => {
+    return () => {
+      (async () => {
+        if (videoRef.current && track) {
+          try {
+            // detach on unmount
+            await actions.detachVideo(track.id, videoRef.current);
+          } catch (err) {
+            HMSLogger.w('detach video error for track', track.id, err);
+          }
+        }
+      })();
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+
+  return { videoRef: setRefs };
+};