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

package/package.json

@@ -4,11 +4,12 @@
   "main": "dist/index.cjs.js",
   "module": "dist/index.js",
   "typings": "dist/index.d.ts",
-  "version": "0.0.17",
+  "version": "0.0.18-alpha.0",
   "author": "100ms",
   "license": "MIT",
   "files": [
-    "dist"
+    "dist",
+    "src"
   ],
   "sideEffects": false,
   "scripts": {
@@ -34,10 +35,10 @@
     "react": ">=17.0.2 <19.0.0"
   },
   "dependencies": {
-    "@100mslive/hms-video-store": "0.2.100",
+    "@100mslive/hms-video-store": "0.2.101-alpha.0",
     "react-intersection-observer": "^8.33.1",
     "react-resize-detector": "^7.0.0",
     "zustand": "^3.6.2"
   },
-  "gitHead": "6b6b3be2d74caec735d00f01fe331253dd34a500"
+  "gitHead": "6dd5786abc0d9e2faa7f88554e56ebc61ef6d685"
 }

package/src/hooks/types.ts

@@ -0,0 +1,6 @@
+/**
+ * use this to control how errors are handled within a function exposed by a hook. By default this
+ * only logs the error to the console, and can be overridden for any other behaviour. For e.g.
+ * `(err) => throw err;` will ensure that any error is thrown back to the caller when the function is called.
+ */
+export type hooksErrHandler = (err: Error, method?: string) => void;

package/src/hooks/useAVToggle.ts

@@ -0,0 +1,62 @@
+import {
+  selectIsAllowedToPublish,
+  selectIsLocalAudioEnabled,
+  selectIsLocalVideoEnabled,
+} 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 interface useAVToggleResult {
+  /**
+   * true if unmuted and vice versa
+   */
+  isLocalAudioEnabled: boolean;
+  isLocalVideoEnabled: boolean;
+  /**
+   * use this function to toggle audio state, the function will only be present if the user
+   * has permission to unmute audio
+   */
+  toggleAudio?: () => void;
+  /**
+   * use this function to toggle video state, the function will only be present if the user
+   * has permission to unmute video
+   */
+  toggleVideo?: () => void;
+}
+
+/**
+ * Use this hook to implement mute/unmute for audio and video.
+ * isAllowedToPublish can be used to decide whether to show the toggle buttons in the UI.
+ * @param handleError to handle any error during toggle of audio/video
+ */
+export const useAVToggle = (handleError: hooksErrHandler = logErrorHandler): useAVToggleResult => {
+  const isLocalAudioEnabled = useHMSStore(selectIsLocalAudioEnabled);
+  const isLocalVideoEnabled = useHMSStore(selectIsLocalVideoEnabled);
+  const isAllowedToPublish = useHMSStore(selectIsAllowedToPublish);
+  const actions = useHMSActions();
+
+  const toggleAudio = useCallback(async () => {
+    try {
+      await actions.setLocalAudioEnabled(!isLocalAudioEnabled);
+    } catch (err) {
+      handleError(err as Error, 'toggleAudio');
+    }
+  }, [actions, isLocalAudioEnabled, handleError]);
+
+  const toggleVideo = useCallback(async () => {
+    try {
+      await actions.setLocalVideoEnabled(!isLocalVideoEnabled);
+    } catch (err) {
+      handleError(err as Error, 'toggleVideo');
+    }
+  }, [actions, isLocalVideoEnabled, handleError]);
+
+  return {
+    isLocalAudioEnabled,
+    isLocalVideoEnabled,
+    toggleAudio: isAllowedToPublish?.audio ? toggleAudio : undefined,
+    toggleVideo: isAllowedToPublish?.video ? toggleVideo : undefined,
+  };
+};

package/src/hooks/useAudioLevelStyles.ts

@@ -0,0 +1,37 @@
+import React, { useEffect } from 'react';
+import { selectTrackAudioByID } from '@100mslive/hms-video-store';
+import { useHMSVanillaStore } from '../primitives/HmsRoomProvider';
+
+/**
+ * This hook can be used to apply css properties on an element based on the current audio level for the passed in track.
+ * It doesn't return the audio level as it's optimised for performance. As audio level could be changing frequently we
+ * want to minimise the number of components an audio level change causes to re render.
+ * An e.g. use of this hook will be to apply box-shadow on parent tile based on audio level.
+ * @param trackId is the audio track id for which audio level needs to be used
+ * @param getStyle is a function which can take in current audio level and return the style to apply for the ref
+ * @param ref is the ref of the element on which you want the css to apply
+ */
+export function useAudioLevelStyles({
+  trackId,
+  getStyle,
+  ref,
+}: {
+  trackId?: string;
+  getStyle: (level: number) => Record<string, string>;
+  ref: React.RefObject<any>;
+}) {
+  const store = useHMSVanillaStore();
+  useEffect(
+    () =>
+      store.subscribe(level => {
+        if (!ref.current) {
+          return;
+        }
+        const styles = getStyle(level);
+        for (const key in styles) {
+          ref.current.style[key] = styles[key];
+        }
+      }, selectTrackAudioByID(trackId)),
+    [getStyle, ref, store, trackId],
+  );
+}

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,
+  };
+};