feat(react-native): expose useModeration hook (#2073)

Introduces new `useModeration` hook that handles the `call.moderation_blur` event.
Follow-up of: #1822

🎫 Ticket: https://linear.app/stream/issue/RN-329/moderation-video-blurring
📑 Docs: GetStream/docs-content#373

Author: oliverlaz

packages/react-native-sdk/src/contexts/BackgroundFilters.tsx

@@ -1,5 +1,4 @@
 import React, {
-  createContext,
   type PropsWithChildren,
   useCallback,
   useContext,
@@ -10,15 +9,19 @@ import React, {
 import { MediaStream } from '@stream-io/react-native-webrtc';
 import { useCall } from '@stream-io/video-react-bindings';
 import { Image, Platform } from 'react-native';
-
-const isSupported = (function () {
-  if (Platform.OS === 'ios') {
-    // only supported on ios 15 and above
-    const currentVersion = parseInt(Platform.Version, 10);
-    return currentVersion >= 15;
-  }
-  return Platform.OS === 'android';
-})();
+import {
+  BackgroundFiltersContext,
+  type BlurIntensity,
+  type CurrentBackgroundFilter,
+  type ImageSourceType,
+} from './internal/BackgroundFiltersContext';
+
+// for maintaining backwards compatibility
+export type {
+  BlurIntensity,
+  CurrentBackgroundFilter,
+  BackgroundFiltersAPI,
+} from './internal/BackgroundFiltersContext';
 
 type VideoFiltersModuleType =
   typeof import('@stream-io/video-filters-react-native');
@@ -29,62 +32,15 @@ try {
   videoFiltersModule = require('@stream-io/video-filters-react-native');
 } catch {}
 
-const resolveAssetSourceFunc = Image.resolveAssetSource;
-
-// excluding array of images and only allow one image
-type ImageSourceType = Exclude<
-  Parameters<typeof resolveAssetSourceFunc>[0],
-  Array<any>
->;
-
-export type BlurIntensity = 'light' | 'medium' | 'heavy';
-
-export type BackgroundFilterType = 'blur' | 'image';
-
-export type CurrentBackgroundFilter = {
-  blur?: BlurIntensity;
-  image?: ImageSourceType;
-};
-
-export type BackgroundFiltersAPI = {
-  /**
-   * The currently applied background filter. Undefined value indicates that no filter is applied.
-   */
-  currentBackgroundFilter: CurrentBackgroundFilter | undefined;
-  /**
-   * Whether the current device supports the background filters.
-   */
-  isSupported: boolean;
-  /**
-   * Applies a background image filter to the video.
-   *
-   * @param imageSource the URL of the image to use as the background.
-   */
-  applyBackgroundImageFilter: (imageSource: ImageSourceType) => void;
-  /**
-   * Applies a background blur filter to the video.
-   *
-   * @param blurLevel the level of blur to apply to the background.
-   */
-  applyBackgroundBlurFilter: (blurIntensity: BlurIntensity) => void;
-  /**
-   * Applies a video blur filter to the video.
-   *
-   * @param blurIntensity the level of blur to apply to the video.
-   */
-  applyVideoBlurFilter: (blurIntensity: BlurIntensity) => void;
-  /**
-   * Disables all filters applied to the video.
-   */
-  disableAllFilters: () => void;
-};
-
-/**
- * The context for the background filters.
- */
-const BackgroundFiltersContext = createContext<
-  BackgroundFiltersAPI | undefined
->(undefined);
+const isSupported = (function () {
+  if (!videoFiltersModule) return false;
+  if (Platform.OS === 'ios') {
+    // only supported on ios 15 and above
+    const currentVersion = parseInt(Platform.Version, 10);
+    return currentVersion >= 15;
+  }
+  return Platform.OS === 'android';
+})();
 
 /**
  * A hook to access the background filters context API.
@@ -165,7 +121,7 @@ export const BackgroundFiltersProvider = ({ children }: PropsWithChildren) => {
       } else if (blurIntensity === 'light') {
         filterName = 'BlurLight';
       }
-      call?.tracer.trace('backgroundFilters.apply', filterName);
+      call?.tracer.trace('videoFilters.apply', filterName);
       (call?.camera.state.mediaStream as MediaStream | undefined)
         ?.getVideoTracks()
         .forEach((track) => {
@@ -181,7 +137,7 @@ export const BackgroundFiltersProvider = ({ children }: PropsWithChildren) => {
       if (!isSupported) {
         return;
       }
-      const source = resolveAssetSourceFunc(imageSource);
+      const source = Image.resolveAssetSource(imageSource);
       const imageUri = source.uri;
       const registeredImageFiltersSet = registeredImageFiltersSetRef.current;
       if (!registeredImageFiltersSet.has(imageUri)) {

packages/react-native-sdk/src/contexts/internal/BackgroundFiltersContext.tsx

@@ -0,0 +1,52 @@
+import { createContext } from 'react';
+import { type ImageSourcePropType } from 'react-native';
+
+// excluding array of images and only allow one image
+export type ImageSourceType = Exclude<ImageSourcePropType, Array<any>>;
+
+export type BlurIntensity = 'light' | 'medium' | 'heavy';
+
+export type CurrentBackgroundFilter = {
+  blur?: BlurIntensity;
+  image?: ImageSourceType;
+};
+
+export type BackgroundFiltersAPI = {
+  /**
+   * The currently applied background filter. Undefined value indicates that no filter is applied.
+   */
+  currentBackgroundFilter: CurrentBackgroundFilter | undefined;
+  /**
+   * Whether the current device supports the background filters.
+   */
+  isSupported: boolean;
+  /**
+   * Applies a background image filter to the video.
+   *
+   * @param imageSource the URL of the image to use as the background.
+   */
+  applyBackgroundImageFilter: (imageSource: ImageSourceType) => Promise<void>;
+  /**
+   * Applies a background blur filter to the video.
+   *
+   * @param blurLevel the level of blur to apply to the background.
+   */
+  applyBackgroundBlurFilter: (blurIntensity: BlurIntensity) => Promise<void>;
+  /**
+   * Applies a video blur filter to the video.
+   *
+   * @param blurIntensity the level of blur to apply to the video.
+   */
+  applyVideoBlurFilter: (blurIntensity: BlurIntensity) => Promise<void>;
+  /**
+   * Disables all filters applied to the video.
+   */
+  disableAllFilters: () => void;
+};
+
+/**
+ * The context for the background filters.
+ */
+export const BackgroundFiltersContext = createContext<
+  BackgroundFiltersAPI | undefined
+>(undefined);

packages/react-native-sdk/src/hooks/index.ts

@@ -9,3 +9,4 @@ export * from './useScreenShareButton';
 export * from './useTrackDimensions';
 export * from './useScreenshot';
 export * from './useSpeechDetection';
+export * from './useModeration';

packages/react-native-sdk/src/hooks/useModeration.ts

@@ -0,0 +1,83 @@
+import { useContext, useEffect, useRef } from 'react';
+import { useCall } from '@stream-io/video-react-bindings';
+import { BackgroundFiltersContext } from '../contexts/internal/BackgroundFiltersContext';
+
+export interface ModerationOptions {
+  /**
+   * How long the moderation effect should stay active before being disabled.
+   * Set to `0` to keep it active indefinitely. Defaults to 5000 ms.
+   */
+  duration?: number;
+}
+
+export const useModeration = (options?: ModerationOptions) => {
+  const { duration = 5000 } = options || {};
+  const call = useCall();
+
+  // accessing the filters context directly, as it is optional, but our
+  // useBackgroundFilters() throws an error if used outside the provider
+  const filtersApi = useContext(BackgroundFiltersContext);
+  const {
+    isSupported = false,
+    currentBackgroundFilter,
+    applyBackgroundBlurFilter,
+    applyBackgroundImageFilter,
+    applyVideoBlurFilter,
+    disableAllFilters,
+  } = filtersApi || {};
+  const blurTimeoutRef = useRef<ReturnType<typeof setTimeout>>(undefined);
+  const restoreRef = useRef<Promise<void>>(undefined);
+  useEffect(() => {
+    if (!call) return;
+    const unsubscribe = call.on('call.moderation_blur', () => {
+      const turnCameraOff = () =>
+        call.camera.disable().catch((err) => {
+          console.error(`Failed to disable camera`, err);
+        });
+
+      // not scheduling a timeout to enable the camera
+      clearTimeout(blurTimeoutRef.current);
+      if (!isSupported) return turnCameraOff();
+
+      restoreRef.current = (restoreRef.current || Promise.resolve()).then(() =>
+        applyVideoBlurFilter?.('heavy').then(() => {
+          if (duration <= 0) return;
+
+          const restore = () => {
+            const { blur, image } = currentBackgroundFilter || {};
+            const action = blur
+              ? applyVideoBlurFilter?.(blur)
+              : image
+                ? applyBackgroundImageFilter?.(image)
+                : Promise.resolve(disableAllFilters?.());
+
+            action?.catch((err) => {
+              console.error(`Failed to restore pre-moderation effect`, err);
+            });
+          };
+
+          blurTimeoutRef.current = setTimeout(restore, duration);
+        }, turnCameraOff),
+      );
+    });
+    return () => {
+      unsubscribe();
+    };
+  }, [
+    applyBackgroundBlurFilter,
+    applyBackgroundImageFilter,
+    applyVideoBlurFilter,
+    call,
+    currentBackgroundFilter,
+    disableAllFilters,
+    duration,
+    isSupported,
+  ]);
+
+  useEffect(
+    () => () => {
+      restoreRef.current?.then(() => clearTimeout(blurTimeoutRef.current));
+    },
+    [],
+  );
+};

sample-apps/react-native/dogfood/ios/Podfile.lock

@@ -2937,7 +2937,7 @@ PODS:
     - SocketRocket
     - Yoga
   - SocketRocket (0.7.1)
-  - stream-chat-react-native (8.9.1):
+  - stream-chat-react-native (8.12.0):
     - boost
     - DoubleConversion
     - fast_float
@@ -2966,7 +2966,7 @@ PODS:
     - ReactCommon/turbomodule/core
     - SocketRocket
     - Yoga
-  - stream-io-noise-cancellation-react-native (0.4.2):
+  - stream-io-noise-cancellation-react-native (0.4.4):
     - boost
     - DoubleConversion
     - fast_float
@@ -2996,7 +2996,7 @@ PODS:
     - stream-react-native-webrtc
     - StreamVideoNoiseCancellation
     - Yoga
-  - stream-io-video-filters-react-native (0.9.2):
+  - stream-io-video-filters-react-native (0.9.3):
     - boost
     - DoubleConversion
     - fast_float
@@ -3028,7 +3028,7 @@ PODS:
   - stream-react-native-webrtc (137.0.2):
     - React-Core
     - StreamWebRTC (~> 137.0.52)
-  - stream-video-react-native (1.26.1):
+  - stream-video-react-native (1.26.5):
     - boost
     - DoubleConversion
     - fast_float
@@ -3461,11 +3461,11 @@ SPEC CHECKSUMS:
   RNVoipPushNotification: 4998fe6724d421da616dca765da7dc421ff54c4e
   RNWorklets: ad0606bee2a8103c14adb412149789c60b72bfb2
   SocketRocket: d4aabe649be1e368d1318fdf28a022d714d65748
-  stream-chat-react-native: 2138656043846cd04d5d284605ef07af9a5309bc
-  stream-io-noise-cancellation-react-native: 17dfc185dc9b2552f70a1510cf818228dcd2e436
-  stream-io-video-filters-react-native: 5f24440c96fda08d50d7e33910a60d354c9771fe
+  stream-chat-react-native: 2ad28c26fbc0b8cb20d675c6b2674871d78f914f
+  stream-io-noise-cancellation-react-native: 208e38e34b4bc2922b7f2837cdb2e477e2202784
+  stream-io-video-filters-react-native: 3f44cffc89a66b2c6216ab11f3ac4bd3ac725d0f
   stream-react-native-webrtc: 1bef09475caf435abbbd8aec8f8c3a9b1ee1fdf0
-  stream-video-react-native: e4023430bda1d702a1ce83355db70515ace3f727
+  stream-video-react-native: f52d912ce960a221ea43fce73771973c7b93ea12
   StreamVideoNoiseCancellation: 41f5a712aba288f9636b64b17ebfbdff52c61490
   StreamWebRTC: 57bd35729bcc46b008de4e741a5b23ac28b8854d
   VisionCamera: 891edb31806dd3a239c8a9d6090d6ec78e11ee80

sample-apps/react-native/dogfood/src/components/ActiveCall.tsx

@@ -1,17 +1,11 @@
-import React, {
-  useCallback,
-  useEffect,
-  useMemo,
-  useRef,
-  useState,
-} from 'react';
+import React, { useCallback, useEffect, useMemo, useState } from 'react';
 import {
   CallContent,
   callManager,
   NoiseCancellationProvider,
-  useBackgroundFilters,
   useCall,
   useIsInPiPMode,
+  useModeration,
   useTheme,
   useToggleCallRecording,
 } from '@stream-io/video-react-native-sdk';
@@ -55,8 +49,6 @@ export const ActiveCall = ({
   const currentOrientation = useOrientation();
   const isTablet = DeviceInfo.isTablet();
   const isLandscape = !isTablet && currentOrientation === 'landscape';
-  const { applyVideoBlurFilter, disableAllFilters } = useBackgroundFilters();
-  const blurTimeoutRef = useRef<ReturnType<typeof setTimeout>>(undefined);
 
   const onOpenCallParticipantsInfo = useCallback(() => {
     setIsCallParticipantsVisible(true);
@@ -82,25 +74,7 @@ export const ActiveCall = ({
     };
   }, []);
 
-  useEffect(() => {
-    const unsub = call?.on('call.moderation_blur', () => {
-      applyVideoBlurFilter('heavy');
-      clearTimeout(blurTimeoutRef.current);
-
-      blurTimeoutRef.current = setTimeout(() => {
-        disableAllFilters();
-        blurTimeoutRef.current = undefined;
-      }, 10000);
-    });
-    return () => {
-      unsub?.();
-      if (blurTimeoutRef.current) {
-        clearTimeout(blurTimeoutRef.current);
-        blurTimeoutRef.current = undefined;
-      }
-      disableAllFilters();
-    };
-  }, [call, applyVideoBlurFilter, disableAllFilters]);
+  useModeration({ duration: 10000 });
 
   useEffect(() => {
     return call?.on('call.ended', (event) => {