@stream-io/video-react-sdk 1.32.3 → 1.33.0

package/src/embedded/hooks/useInitializeCall.ts

@@ -0,0 +1,51 @@
+import { useEffect, useState } from 'react';
+import { Call, CallingState, StreamVideoClient } from '@stream-io/video-client';
+
+export interface UseInitializeCallProps {
+  client?: StreamVideoClient;
+  callType: string;
+  callId: string;
+  handleError: (error: any) => void;
+}
+
+/**
+ * Hook to initialize and manage a Call instance.
+ */
+export const useInitializeCall = ({
+  client,
+  callType,
+  callId,
+  handleError,
+}: UseInitializeCallProps): Call | undefined => {
+  const [call, setCall] = useState<Call>();
+
+  useEffect(() => {
+    if (!client || !callId) return;
+
+    let cancelled = false;
+    const _call = client.call(callType, callId);
+
+    _call
+      .get()
+      .then(() => {
+        if (!cancelled) setCall(_call);
+      })
+      .catch((err) => {
+        if (cancelled) return;
+
+        handleError(err);
+      });
+
+    return () => {
+      cancelled = true;
+      setCall(undefined);
+      if (_call.state.callingState !== CallingState.LEFT) {
+        _call
+          .leave()
+          .catch((err) => console.error('Failed to leave call:', err));
+      }
+    };
+  }, [client, callType, callId, handleError]);
+
+  return call;
+};

package/src/embedded/hooks/useInitializeVideoClient.ts

@@ -0,0 +1,118 @@
+import { useEffect, useRef, useState } from 'react';
+import {
+  LogLevel,
+  StreamVideoClient,
+  TokenProvider,
+  User,
+} from '@stream-io/video-client';
+import type { EmbeddedUser } from '../types';
+
+export interface UseInitializeVideoClientProps {
+  apiKey: string;
+  user: EmbeddedUser;
+  token?: string;
+  tokenProvider?: TokenProvider;
+  logLevel?: LogLevel;
+  handleError: (error: any) => void;
+}
+
+/**
+ * Hook that creates a StreamVideoClient and connects the user.
+ * Disconnects and cleans up on unmount or when props change.
+ *
+ */
+export const useInitializeVideoClient = ({
+  apiKey,
+  user,
+  token,
+  tokenProvider,
+  logLevel,
+  handleError,
+}: UseInitializeVideoClientProps): StreamVideoClient | undefined => {
+  const [client, setClient] = useState<StreamVideoClient | undefined>();
+
+  const tokenProviderRef = useRef(tokenProvider);
+  tokenProviderRef.current = tokenProvider;
+
+  useEffect(() => {
+    if (!apiKey) return;
+
+    const options = logLevel ? { logLevel } : undefined;
+    let _client: StreamVideoClient | undefined;
+    try {
+      if (user?.type === 'guest') {
+        const streamUser: User = {
+          id: user.id,
+          type: 'guest',
+          name: user.name,
+          image: user.image,
+        };
+
+        _client = new StreamVideoClient({
+          apiKey,
+          user: streamUser,
+          options,
+        });
+      } else if (user?.type === 'anonymous') {
+        const streamUser: User = {
+          id: '!anon',
+          type: 'anonymous',
+          name: user.name,
+          image: user.image,
+        };
+
+        _client = new StreamVideoClient({
+          apiKey,
+          user: streamUser,
+          token,
+          tokenProvider: tokenProviderRef.current,
+          options,
+        });
+      } else {
+        const streamUser: User = {
+          id: user.id,
+          name: user.name,
+          image: user.image,
+        };
+
+        const currentTokenProvider = tokenProviderRef.current;
+        _client = new StreamVideoClient({
+          apiKey,
+          user: streamUser,
+          ...(token
+            ? {
+                token,
+                ...(currentTokenProvider
+                  ? { tokenProvider: currentTokenProvider }
+                  : {}),
+              }
+            : { tokenProvider: currentTokenProvider! }),
+          options,
+        });
+      }
+
+      setClient(_client);
+    } catch (err) {
+      handleError(err);
+    }
+
+    return () => {
+      _client
+        ?.disconnectUser()
+        .catch((err) => console.error('Failed to disconnect user:', err));
+
+      setClient(undefined);
+    };
+  }, [
+    apiKey,
+    user.id,
+    user.type,
+    user.name,
+    user.image,
+    token,
+    logLevel,
+    handleError,
+  ]);
+
+  return client;
+};

package/src/embedded/hooks/useIsLivestreamPaused.ts

@@ -0,0 +1,44 @@
+import { useEffect, useState } from 'react';
+import { CallingState, SfuModels } from '@stream-io/video-client';
+import { useCall, useCallStateHooks } from '@stream-io/video-react-bindings';
+
+/**
+ * Distinguishes a temporary live pause (host went backstage) from a real
+ * call end. Returns `true` when the viewer was kicked because the host
+ * paused the livestream — not because the call was fully terminated.
+ *
+ * Resets to `false` on rejoin or when `call.ended` (real end) arrives.
+ */
+export const useIsLivestreamPaused = () => {
+  const call = useCall();
+  const { useCallCallingState } = useCallStateHooks();
+  const callingState = useCallCallingState();
+  const [isPaused, setIsPaused] = useState(false);
+
+  useEffect(() => {
+    if (!call) return;
+
+    const unsubSfu = call.on('callEnded', (e) => {
+      if (e.reason === SfuModels.CallEndedReason.LIVE_ENDED) {
+        setIsPaused(true);
+      }
+    });
+
+    const unsubEnded = call.on('call.ended', () => {
+      setIsPaused(false);
+    });
+
+    return () => {
+      unsubSfu();
+      unsubEnded();
+    };
+  }, [call]);
+
+  useEffect(() => {
+    if (callingState === CallingState.JOINED) {
+      setIsPaused(false);
+    }
+  }, [callingState]);
+
+  return isPaused;
+};

package/src/embedded/hooks/useLayout.ts

@@ -0,0 +1,100 @@
+import type { ComponentType } from 'react';
+import { useEffect, useState } from 'react';
+import { useCallStateHooks } from '@stream-io/video-react-bindings';
+import {
+  LivestreamLayout,
+  PaginatedGridLayout,
+  SpeakerLayout,
+} from '../../core';
+import type { LayoutOption } from '../types';
+import { useEmbeddedConfiguration } from '../context';
+import { EmbeddedParticipantViewUI } from '../shared';
+
+interface LayoutConfig {
+  Component: ComponentType<Record<string, unknown>>;
+  props?: Record<string, unknown>;
+}
+
+const Layouts: Record<LayoutOption, LayoutConfig> = {
+  Livestream: {
+    Component: LivestreamLayout,
+    props: {
+      showLiveBadge: false,
+      showParticipantCount: false,
+      showDuration: false,
+    },
+  },
+  PaginatedGrid: {
+    Component: PaginatedGridLayout,
+    props: { groupSize: 16, ParticipantViewUI: EmbeddedParticipantViewUI },
+  },
+  SpeakerLeft: {
+    Component: SpeakerLayout,
+    props: {
+      participantsBarPosition: 'left',
+      ParticipantViewUISpotlight: EmbeddedParticipantViewUI,
+      ParticipantViewUIBar: EmbeddedParticipantViewUI,
+    },
+  },
+  SpeakerRight: {
+    Component: SpeakerLayout,
+    props: {
+      participantsBarPosition: 'right',
+      ParticipantViewUISpotlight: EmbeddedParticipantViewUI,
+      ParticipantViewUIBar: EmbeddedParticipantViewUI,
+    },
+  },
+  SpeakerTop: {
+    Component: SpeakerLayout,
+    props: {
+      participantsBarPosition: 'top',
+      ParticipantViewUISpotlight: EmbeddedParticipantViewUI,
+      ParticipantViewUIBar: EmbeddedParticipantViewUI,
+    },
+  },
+  SpeakerBottom: {
+    Component: SpeakerLayout,
+    props: {
+      participantsBarPosition: 'bottom',
+      ParticipantViewUISpotlight: EmbeddedParticipantViewUI,
+      ParticipantViewUIBar: EmbeddedParticipantViewUI,
+    },
+  },
+};
+
+const EMPTY_PROPS: Record<string, unknown> = {};
+const VALID_LAYOUTS = Object.keys(Layouts) as LayoutOption[];
+
+const isValidLayout = (layout: string): layout is LayoutOption =>
+  VALID_LAYOUTS.includes(layout as LayoutOption);
+
+/**
+ * Hook to manage layout selection.
+ * Returns the layout Component and its props.
+ */
+export const useLayout = () => {
+  const { layout: configuredLayout } = useEmbeddedConfiguration();
+  const { useHasOngoingScreenShare } = useCallStateHooks();
+  const hasScreenShare = useHasOngoingScreenShare();
+
+  const defaultLayout = isValidLayout(configuredLayout ?? '')
+    ? configuredLayout!
+    : 'SpeakerTop';
+
+  const [layout, setLayout] = useState<LayoutOption>(defaultLayout);
+
+  useEffect(() => {
+    if (hasScreenShare) {
+      setLayout((currentLayout) => {
+        if (currentLayout.startsWith('Speaker')) return currentLayout;
+        return 'SpeakerRight';
+      });
+    } else {
+      setLayout(defaultLayout);
+    }
+  }, [hasScreenShare, defaultLayout]);
+
+  const { Component, props = EMPTY_PROPS } = Layouts[layout];
+
+  return { Component, props };
+};

package/src/embedded/hooks/useNoiseCancellationLoader.ts

@@ -0,0 +1,62 @@
+import { useEffect, useRef, useState } from 'react';
+import {
+  NoiseCancellationSettingsModeEnum,
+  type Call,
+} from '@stream-io/video-client';
+
+type INoiseCancellation =
+  import('@stream-io/audio-filters-web').INoiseCancellation;
+
+/**
+ * Hook that lazily loads the noise cancellation module from @stream-io/audio-filters-web.
+ * Skips loading if the server-side noise cancellation setting is disabled.
+ * Returns the NoiseCancellation instance when loaded, or undefined if unavailable.
+ * The `ready` flag becomes `true` once loading completes (even on failure),
+ * or immediately if noise cancellation is disabled by server settings.
+ */
+export const useNoiseCancellationLoader = (call?: Call) => {
+  const [noiseCancellation, setNoiseCancellation] =
+    useState<INoiseCancellation>();
+  const [ready, setReady] = useState(false);
+  const ncLoader = useRef<Promise<void> | undefined>(undefined);
+
+  const ncSettings = call?.state.settings?.audio?.noise_cancellation;
+  const isNoiseCancellationEnabled = !!(
+    ncSettings && ncSettings.mode !== NoiseCancellationSettingsModeEnum.DISABLED
+  );
+
+  useEffect(() => {
+    if (!call) return;
+
+    if (!isNoiseCancellationEnabled) {
+      setReady(true);
+      return;
+    }
+
+    const load = (ncLoader.current || Promise.resolve())
+      .then(() => import('@stream-io/audio-filters-web'))
+      .then(({ NoiseCancellation }) => {
+        const nc = new NoiseCancellation({});
+        setNoiseCancellation(nc);
+      })
+      .catch((err) => {
+        console.warn(
+          '[EmbeddedStreamClient] Failed to load noise cancellation. ' +
+            'Make sure @stream-io/audio-filters-web is installed.',
+          err,
+        );
+      })
+      .finally(() => {
+        setReady(true);
+      });
+
+    return () => {
+      ncLoader.current = load.then(() => {
+        setNoiseCancellation(undefined);
+        setReady(false);
+      });
+    };
+  }, [call, isNoiseCancellationEnabled]);
+
+  return { noiseCancellation, ready };
+};

package/src/embedded/hooks/useWakeLock.ts

@@ -0,0 +1,33 @@
+import { useEffect } from 'react';
+import { CallingState } from '@stream-io/video-client';
+import { useCallStateHooks } from '@stream-io/video-react-bindings';
+
+/**
+ * Hook to prevent screen from going to sleep during active calls.
+ * Uses the Screen Wake Lock API when available.
+ */
+export const useWakeLock = () => {
+  const { useCallCallingState } = useCallStateHooks();
+  const callState = useCallCallingState();
+
+  useEffect(() => {
+    if (callState !== CallingState.JOINED || !('wakeLock' in navigator)) return;
+
+    let interrupted = false;
+    let wakeLockSentinel: null | WakeLockSentinel = null;
+    navigator.wakeLock
+      .request('screen')
+      .then((wls: WakeLockSentinel) => {
+        if (interrupted) return wls.release();
+        wakeLockSentinel = wls;
+      })
+      .catch((error: unknown) =>
+        console.debug(`Couldn't setup WakeLock due to: ${error}`),
+      );
+
+    return () => {
+      interrupted = true;
+      wakeLockSentinel?.release();
+    };
+  }, [callState]);
+};

package/src/embedded/index.ts

@@ -0,0 +1,12 @@
+export { EmbeddedCall } from './call';
+export { EmbeddedLivestream } from './livestream';
+
+export type {
+  EmbeddedMeetingProps,
+  EmbeddedLivestreamProps,
+  EmbeddedUser,
+  EmbeddedAuthenticatedUser,
+  EmbeddedGuestUser,
+  EmbeddedAnonymousUser,
+  LayoutOption,
+} from './types';

package/src/embedded/livestream/EmbeddedLivestream.tsx

@@ -0,0 +1,16 @@
+import type { EmbeddedLivestreamProps } from '../types';
+import { EmbeddedClientProvider } from '../EmbeddedClientProvider';
+import { LivestreamUI } from './LivestreamUI';
+
+/**
+ * Drop-in livestream component. Renders host or viewer UI based on permissions.
+ */
+export const EmbeddedLivestream = ({
+  children,
+  ...props
+}: EmbeddedLivestreamProps) => (
+  <EmbeddedClientProvider {...props}>
+    <LivestreamUI />
+    {children}
+  </EmbeddedClientProvider>
+);

package/src/embedded/livestream/LivestreamUI.tsx

@@ -0,0 +1,17 @@
+import { OwnCapability } from '@stream-io/video-client';
+import { useCallStateHooks } from '@stream-io/video-react-bindings';
+
+import { HostStateRouter } from './host/HostStateRouter';
+import { ViewerStateRouter } from './viewer/ViewerStateRouter';
+
+export const LivestreamUI = () => {
+  const { useHasPermissions } = useCallStateHooks();
+
+  const isHost = useHasPermissions(OwnCapability.JOIN_BACKSTAGE);
+
+  if (isHost) {
+    return <HostStateRouter />;
+  }
+
+  return <ViewerStateRouter />;
+};

package/src/embedded/livestream/host/HostLayout.tsx

@@ -0,0 +1,210 @@
+import { useCallback, useState } from 'react';
+import clsx from 'clsx';
+import { OwnCapability } from '@stream-io/video-client';
+import {
+  Restricted,
+  useCallStateHooks,
+  useI18n,
+} from '@stream-io/video-react-bindings';
+import { useLayout } from '../../hooks';
+import {
+  CallParticipantsList,
+  CancelCallConfirmButton,
+  CompositeButton,
+  DeviceSelectorAudioInput,
+  DeviceSelectorAudioOutput,
+  Icon,
+  MicCaptureErrorNotification,
+  PermissionRequests,
+  ReactionsButton,
+  RecordCallConfirmationButton,
+  ScreenShareButton,
+  ToggleAudioPublishingButton,
+  ToggleVideoPublishingButton,
+  WithTooltip,
+} from '../../../components';
+import { useCallDuration } from '../../hooks';
+import {
+  CameraMenuWithBlur,
+  ConnectionNotification,
+  ViewersCount,
+} from '../../shared';
+
+export type HostViewProps = {
+  isLive: boolean;
+  isBackstageEnabled: boolean;
+  onGoLive: () => void;
+  onStopLive: () => void;
+};
+
+export const HostLayout = ({
+  isLive,
+  isBackstageEnabled,
+  onGoLive,
+  onStopLive,
+}: HostViewProps) => {
+  const { t } = useI18n();
+  const { useParticipantCount, useCallSession } = useCallStateHooks();
+  const participantCount = useParticipantCount();
+  const session = useCallSession();
+  const { elapsed } = useCallDuration(session?.live_started_at);
+  const { Component: LayoutComponent, props: layoutProps } = useLayout();
+  const [showParticipants, setShowParticipants] = useState(false);
+
+  const handleCloseParticipants = useCallback(() => {
+    setShowParticipants(false);
+  }, []);
+
+  const handleToggleParticipants = useCallback(() => {
+    setShowParticipants((prev) => !prev);
+  }, []);
+
+  const livestreamStatus = (
+    <div
+      className="str-video__embedded-livestream-duration"
+      aria-live="polite"
+      aria-atomic="true"
+    >
+      <span
+        className={
+          isLive
+            ? 'str-video__embedded-livestream-duration__live-badge'
+            : 'str-video__embedded-livestream-duration__backstage-badge'
+        }
+      >
+        {isLive ? t('Live') : t('Backstage')}
+      </span>
+      <ViewersCount count={participantCount} />
+      {isLive && elapsed && (
+        <span className="str-video__embedded-livestream-duration__elapsed">
+          {elapsed}
+        </span>
+      )}
+    </div>
+  );
+
+  return (
+    <div className="str-video__embedded-call str-video__embedded-livestream">
+      <ConnectionNotification />
+      <PermissionRequests />
+      <div className="str-video__embedded-call-header">
+        {livestreamStatus}
+        <CancelCallConfirmButton />
+      </div>
+      <div className="str-video__embedded-layout">
+        <div className="str-video__embedded-layout__stage">
+          <LayoutComponent {...layoutProps} />
+        </div>
+
+        <div
+          className={clsx(
+            'str-video__embedded-sidebar',
+            showParticipants && 'str-video__embedded-sidebar--open',
+          )}
+        >
+          {showParticipants && (
+            <div className="str-video__embedded-participants">
+              <CallParticipantsList onClose={handleCloseParticipants} />
+            </div>
+          )}
+        </div>
+      </div>
+      <div className="str-video__embedded-call-controls str-video__call-controls">
+        <div className="str-video__call-controls--group str-video__call-controls--options">
+          <Restricted requiredGrants={[OwnCapability.CREATE_REACTION]}>
+            <div className="str-video__embedded-mobile">
+              <ReactionsButton />
+            </div>
+          </Restricted>
+          <div className="str-video__embedded-desktop">{livestreamStatus}</div>
+        </div>
+        <div className="str-video__call-controls--group str-video__call-controls--media">
+          <Restricted
+            requiredGrants={[OwnCapability.SEND_AUDIO]}
+            hasPermissionsOnly
+          >
+            <MicCaptureErrorNotification>
+              <ToggleAudioPublishingButton
+                Menu={
+                  <>
+                    <DeviceSelectorAudioOutput
+                      visualType="list"
+                      title={t('Speaker')}
+                    />
+                    <DeviceSelectorAudioInput
+                      visualType="list"
+                      title={t('Microphone')}
+                    />
+                  </>
+                }
+                menuPlacement="top"
+              />
+            </MicCaptureErrorNotification>
+          </Restricted>
+          <Restricted
+            requiredGrants={[OwnCapability.SEND_VIDEO]}
+            hasPermissionsOnly
+          >
+            <ToggleVideoPublishingButton
+              Menu={<CameraMenuWithBlur />}
+              menuPlacement="top"
+            />
+          </Restricted>
+          <Restricted requiredGrants={[OwnCapability.CREATE_REACTION]}>
+            <div className="str-video__embedded-desktop">
+              <ReactionsButton />
+            </div>
+          </Restricted>
+          <Restricted requiredGrants={[OwnCapability.SCREENSHARE]}>
+            <div className="str-video__embedded-desktop">
+              <ScreenShareButton />
+            </div>
+          </Restricted>
+          <RecordCallConfirmationButton />
+          {isBackstageEnabled && (
+            <Restricted requiredGrants={[OwnCapability.UPDATE_CALL]}>
+              {isLive ? (
+                <WithTooltip title={t('End Stream')}>
+                  <button
+                    type="button"
+                    className="str-video__embedded-end-stream-button"
+                    onClick={onStopLive}
+                  >
+                    <Icon icon="call-end" />
+                    <span>{t('Stop Live')}</span>
+                  </button>
+                </WithTooltip>
+              ) : (
+                <WithTooltip title={t('Start Stream')}>
+                  <button
+                    type="button"
+                    className="str-video__embedded-go-live-button"
+                    onClick={onGoLive}
+                  >
+                    <Icon icon="streaming" />
+                    <span>{t('Go Live')}</span>
+                  </button>
+                </WithTooltip>
+              )}
+            </Restricted>
+          )}
+          <div className="str-video__embedded-desktop">
+            <CancelCallConfirmButton />
+          </div>
+        </div>
+        <div className="str-video__call-controls--group str-video__call-controls--sidebar">
+          <WithTooltip title={t('Participants')}>
+            <CompositeButton
+              active={showParticipants}
+              aria-label={t('Participants')}
+              aria-pressed={showParticipants}
+              onClick={handleToggleParticipants}
+            >
+              <Icon icon="participants" />
+            </CompositeButton>
+          </WithTooltip>
+        </div>
+      </div>
+    </div>
+  );
+};