feat(react): Video Call moderation for React SDK (#2007)

### 💡 Overview

Adds automatic full-screen blur when a moderation event is received,
with optional auto-removal after a set duration. Also adds a lightweight
warning notification when moderation warnings are triggered.

### 📝 Implementation notes

- Introduced `useModeration` hook which applies full-screen blur when
moderation event is submitted
- If full-screen blur is unsupported on the device fallback is turning
off the camera
- Implement ModerationNotification when warning event is emitted


🎫 Ticket:
https://linear.app/stream/issue/REACT-625/video-call-moderation-for-react

📑 Docs: GetStream/docs-content#773

Author: jdimovska

packages/react-sdk/index.ts

@@ -14,6 +14,7 @@ export {
   useRequestPermission,
   usePersistedDevicePreferences,
   useDeviceList,
+  useModeration,
 } from './src/hooks';
 export { applyFilter, type Filter } from './src/utilities/filter';
 

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

@@ -3,3 +3,4 @@ export * from './usePersistedDevicePreferences';
 export * from './useScrollPosition';
 export * from './useRequestPermission';
 export * from './useDeviceList';
+export * from './useModeration';

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

@@ -0,0 +1,167 @@
+import { useCallback, useEffect, useRef } from 'react';
+import { useCall } from '@stream-io/video-react-bindings';
+
+type FullScreenBlurType =
+  typeof import('@stream-io/video-filters-web').FullScreenBlur;
+
+const isFullScreenBlurPlatformSupported = (): boolean => {
+  if (
+    typeof window === 'undefined' ||
+    typeof OffscreenCanvas === 'undefined' ||
+    typeof VideoFrame === 'undefined' ||
+    !window.WebGL2RenderingContext
+  ) {
+    return false;
+  }
+
+  try {
+    const canvas = new OffscreenCanvas(1, 1);
+    return !!canvas.getContext('webgl2', {
+      alpha: false,
+      antialias: false,
+      desynchronized: true,
+    });
+  } catch {
+    return false;
+  }
+};
+
+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();
+
+  const timeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const processorRef = useRef<InstanceType<FullScreenBlurType> | null>(null);
+  const unregisterRef = useRef<(() => Promise<void>) | null>(null);
+
+  const blurModulePromise = useRef<Promise<FullScreenBlurType> | null>(null);
+
+  /**
+   * Lazily loads and caches the video-filters-web module.
+   */
+  const loadVideoFiltersWebModule = useCallback(() => {
+    if (!blurModulePromise.current) {
+      blurModulePromise.current = import('@stream-io/video-filters-web')
+        .then((module) => module.FullScreenBlur)
+        .catch((error) => {
+          console.error('[moderation] Failed to import blur module:', error);
+          throw error;
+        });
+    }
+
+    return blurModulePromise.current;
+  }, []);
+
+  const disableBlur = useCallback(() => {
+    if (timeoutRef.current) {
+      clearTimeout(timeoutRef.current);
+      timeoutRef.current = null;
+    }
+
+    unregisterRef
+      .current?.()
+      .catch((err) => console.error('[moderation] unregister error:', err));
+
+    unregisterRef.current = null;
+  }, []);
+
+  const handleFallback = useCallback(async () => {
+    try {
+      await call?.camera.disable();
+    } catch (error) {
+      console.error('[moderation] Failed to disable camera:', error);
+    }
+  }, [call]);
+
+  useEffect(() => {
+    if (!call) return;
+
+    return call.on('call.moderation_warning', async () => {
+      try {
+        await loadVideoFiltersWebModule();
+      } catch (importErr) {
+        console.error('[moderation] Failed to import blur module:', importErr);
+      }
+    });
+  }, [call, loadVideoFiltersWebModule]);
+
+  useEffect(() => {
+    if (!call) return;
+
+    return call.on('call.moderation_blur', async () => {
+      if (unregisterRef.current) return;
+
+      let FullScreenBlurClass: FullScreenBlurType;
+
+      try {
+        FullScreenBlurClass = await loadVideoFiltersWebModule();
+      } catch (importErr) {
+        console.error('[moderation] Failed to import blur module:', importErr);
+        await handleFallback();
+        return;
+      }
+
+      if (!isFullScreenBlurPlatformSupported()) {
+        console.warn('[moderation] Blur not supported on this platform');
+        await handleFallback();
+        return;
+      }
+
+      const { unregister } = call.camera.registerFilter((inputStream) => {
+        unregisterRef.current = unregister;
+
+        const outputPromise = new Promise<MediaStream>(
+          async (resolve, reject) => {
+            const [track] = inputStream.getVideoTracks();
+
+            let processor: InstanceType<FullScreenBlurType>;
+
+            try {
+              processor = new FullScreenBlurClass(track);
+              processorRef.current = processor;
+
+              const result = await processor.start();
+              const output = new MediaStream([result]);
+              resolve(output);
+
+              if (duration > 0) {
+                timeoutRef.current = setTimeout(disableBlur, duration);
+              }
+            } catch (error) {
+              reject(error);
+              console.error('[moderation] Processor init failed:', error);
+
+              await unregisterRef.current?.();
+              unregisterRef.current = null;
+              processorRef.current = null;
+
+              await handleFallback();
+              return;
+            }
+          },
+        );
+
+        return {
+          output: outputPromise,
+          stop: () => {
+            if (processorRef.current) {
+              processorRef.current.stop();
+              processorRef.current = null;
+            }
+          },
+        };
+      });
+    });
+  }, [call, loadVideoFiltersWebModule, disableBlur, handleFallback, duration]);
+
+  useEffect(() => disableBlur, [disableBlur]);
+};

packages/video-filters-web/index.ts

@@ -5,3 +5,4 @@ export * from './src/legacy/tflite';
 export * from './src/mediapipe';
 export * from './src/types';
 export * from './src/VirtualBackground';
+export * from './src/FullScreenBlur';

packages/video-filters-web/src/BaseVideoProcessor.ts

@@ -0,0 +1,132 @@
+import { VideoTrackProcessorHooks } from './types';
+import { TrackGenerator, MediaStreamTrackGenerator } from './FallbackGenerator';
+import { MediaStreamTrackProcessor, TrackProcessor } from './FallbackProcessor';
+
+/**
+ * Base class for real-time video filters.
+ *
+ * It sets up the full pipeline that reads frames from the input track,
+ * processes them, and outputs a new track with your effect applied. Subclasses
+ * only need to implement `initialize` (run once before processing starts) and
+ * `transform` (called for every frame).
+ *
+ * Everything else—canvas setup, performance tracking, error handling, and
+ * clean shutdown is handled for you. Calling `start()` returns a processed
+ * `MediaStreamTrack` ready to use.
+ */
+export abstract class BaseVideoProcessor {
+  protected readonly processor: MediaStreamTrackProcessor<VideoFrame>;
+  protected readonly generator: MediaStreamTrackGenerator<VideoFrame>;
+
+  protected readonly hooks: VideoTrackProcessorHooks;
+
+  protected readonly abortController = new AbortController();
+  protected canvas!: OffscreenCanvas;
+
+  private frames = 0;
+  private delayTotal = 0;
+  private lastStatsTime = 0;
+
+  /**
+   * Constructs a new instance.
+   */
+  protected constructor(
+    protected readonly track: MediaStreamVideoTrack,
+    hooks: VideoTrackProcessorHooks = {},
+  ) {
+    this.processor = new TrackProcessor({ track });
+    this.generator = new TrackGenerator({
+      kind: 'video',
+      signalTarget: track,
+    });
+    this.hooks = hooks;
+  }
+
+  public async start(): Promise<MediaStreamTrack> {
+    const { readable } = this.processor;
+    const { writable } = this.generator;
+
+    const { width = 1280, height = 720 } = this.track.getSettings();
+    this.canvas = new OffscreenCanvas(width, height);
+
+    await this.initialize();
+
+    const transformStream = new TransformStream<VideoFrame, VideoFrame>({
+      transform: async (frame, controller) => {
+        try {
+          if (this.abortController.signal.aborted) return frame.close();
+
+          if (
+            this.canvas.width !== frame.displayWidth ||
+            this.canvas.height !== frame.displayHeight
+          ) {
+            this.canvas.width = frame.displayWidth;
+            this.canvas.height = frame.displayHeight;
+          }
+
+          const start = performance.now();
+          const processed = await this.transform(frame);
+          const delay = performance.now() - start;
+
+          this.updateStats(delay);
+          controller.enqueue(processed);
+        } catch (e) {
+          this.hooks.onError?.(e);
+        } finally {
+          frame.close();
+        }
+      },
+      flush: () => this.onFlush(),
+    });
+
+    readable
+      .pipeThrough(transformStream, { signal: this.abortController.signal })
+      .pipeTo(writable, { signal: this.abortController.signal })
+      .catch((e) => {
+        if (e.name !== 'AbortError' && e.name !== 'InvalidStateError') {
+          console.error(`[${this.processorName}] Error processing track:`, e);
+          this.hooks.onError?.(e);
+        }
+      });
+
+    return this.generator;
+  }
+
+  public stop(): void {
+    this.abortController.abort();
+    this.generator.stop();
+    this.onStop();
+  }
+
+  private updateStats(delay: number): void {
+    this.frames++;
+    this.delayTotal += delay;
+
+    const now = performance.now();
+    if (this.lastStatsTime === 0) {
+      this.lastStatsTime = now;
+      return;
+    }
+
+    if (now - this.lastStatsTime >= 1000) {
+      const avgDelay = Math.round((this.delayTotal / this.frames) * 100) / 100;
+      const fps = Math.round((1000 * this.frames) / (now - this.lastStatsTime));
+
+      this.hooks.onStats?.({ delay: avgDelay, fps, timestamp: now });
+
+      this.frames = 0;
+      this.delayTotal = 0;
+      this.lastStatsTime = now;
+    }
+  }
+
+  protected abstract initialize(): Promise<void>;
+  protected abstract transform(frame: VideoFrame): Promise<VideoFrame>;
+
+  protected onFlush(): void {}
+  protected onStop(): void {}
+
+  protected get processorName(): string {
+    return 'base-processor';
+  }
+}

packages/video-filters-web/src/FallbackProcessor.ts

@@ -90,6 +90,7 @@ class FallbackProcessor implements MediaStreamTrackProcessor<VideoFrame> {
           const frame = new VideoFrame(canvas, {
             timestamp: Math.round(this.video.currentTime * 1000000),
           });
+
           controller.enqueue(frame);
         } catch (err) {
           running = false;

packages/video-filters-web/src/FullScreenBlur.ts

@@ -0,0 +1,52 @@
+import { VideoTrackProcessorHooks } from './types';
+import { BaseVideoProcessor } from './BaseVideoProcessor';
+import { FullScreenBlurRenderer } from './FullScreenBlurRenderer';
+
+export interface FullScreenBlurOptions {
+  blurRadius?: number;
+}
+
+/**
+ * A video filter that applies a full-screen blur to each frame.
+ *
+ * It uses a WebGL renderer to blur the incoming camera track and outputs
+ * a new track with the effect applied. Setup and frame handling are managed
+ * by the base processor.
+ */
+export class FullScreenBlur extends BaseVideoProcessor {
+  private blurRenderer!: FullScreenBlurRenderer;
+  private readonly blurRadius: number;
+
+  /**
+   * Creates a new full-screen blur processor for the given video track.
+   *
+   * @param track - The input camera track to blur.
+   * @param options - Optional settings such as the blur radius.
+   * @param hooks - Optional callbacks for stats and error reporting.
+   */
+  constructor(
+    track: MediaStreamVideoTrack,
+    options: FullScreenBlurOptions = {},
+    hooks: VideoTrackProcessorHooks = {},
+  ) {
+    super(track, hooks);
+    this.blurRadius = options.blurRadius ?? 6;
+  }
+
+  protected async initialize(): Promise<void> {
+    this.blurRenderer = new FullScreenBlurRenderer(this.canvas);
+  }
+
+  protected async transform(frame: VideoFrame): Promise<VideoFrame> {
+    this.blurRenderer.render(frame, this.blurRadius);
+    return new VideoFrame(this.canvas, { timestamp: frame.timestamp });
+  }
+
+  protected onStop(): void {
+    this.blurRenderer?.close();
+  }
+
+  protected get processorName(): string {
+    return 'fullscreen-blur';
+  }
+}