feat(llc): video moderation (#1178)

* Regenerated open API models

* fix

* fix

* video moderation blur

* tweaks

* blur fix

Author: Brazol

packages/stream_video/CHANGELOG.md

@@ -3,7 +3,9 @@
 ### 🐞 Fixed
 * Added handling for SFU `iceRestart` event — the client now correctly performs ICE restart and renegotiation when instructed by the SFU, improving fast reconnect reliability.
 * Added PeerConnection SDP rollback on failed remote answer to prevent the publisher from getting stuck in an inconsistent signaling state.
+
 ### ✅ Added
+* Added video moderation support by providing `VideoModerationConfig` in `CallPreferences`. Check [cookbook](https://getstream.io/video/docs/flutter/ui-cookbook/call-moderation/) for more details.
 * Added HiFi audio mode for high-fidelity scenarios such as live music, podcasts, and professional streaming. Use `SfuAudioBitrateProfile` to select an audio quality profile before joining a call:
   * `SfuAudioBitrateProfile.voiceStandard` – Standard voice (64 kbps, default)
   * `SfuAudioBitrateProfile.voiceHighQuality` – High-quality voice (128 kbps)

packages/stream_video/lib/src/call/call.dart

@@ -297,6 +297,9 @@ class Call {
 
   final Map<String, Timer> _reactionTimers = {};
   final Map<String, Timer> _captionsTimers = {};
+  Timer? _videoModerationTimer;
+  void Function()? _onModerationBlurApply;
+  void Function()? _onModerationBlurClear;
   final List<CancelableOperation<void>> _sfuStatsTimers = [];
   final Set<SfuClientCapability> _sfuClientCapabilities = {
     SfuClientCapability.subscriberVideoPause, // on by default
@@ -624,11 +627,79 @@ class Call {
           event.metadata,
           updateMembers: false,
         );
+      case StreamCallModerationWarningEvent _:
+        return _handleModerationWarningEvent(event);
+      case StreamCallModerationBlurEvent _:
+        return _handleModerationBlurEvent(event);
       default:
         break;
     }
   }
 
+  void _handleModerationWarningEvent(
+    StreamCallModerationWarningEvent event,
+  ) {
+    final config = state.value.preferences.videoModerationConfig;
+    if (config.isDisabled || event.userId != _streamVideo.currentUser.id) {
+      return;
+    }
+
+    config.onWarning?.call(event.message);
+  }
+
+  Future<void> _handleModerationBlurEvent(
+    StreamCallModerationBlurEvent event,
+  ) async {
+    final config = state.value.preferences.videoModerationConfig;
+    if (config.isDisabled || event.userId != _streamVideo.currentUser.id) {
+      return;
+    }
+
+    _stateManager.coordinatorCallModerationBlur(event.userId);
+
+    _videoModerationTimer?.cancel();
+    _videoModerationTimer = null;
+    if (config.duration != null) {
+      _videoModerationTimer = Timer(config.duration!, clearModerationBlur);
+    }
+
+    if (config.muteAudio) await setMicrophoneEnabled(enabled: false);
+    if (config.muteVideo) await setCameraEnabled(enabled: false);
+    if (config.applyBlur) _onModerationBlurApply?.call();
+    config.onApply?.call();
+  }
+
+  /// Clears the moderation action, restoring normal operation.
+  ///
+  /// When [VideoModerationConfig.muteAudio] / [VideoModerationConfig.muteVideo]
+  /// were active, re-enabling mic/camera is allowed again but they stay off
+  /// until the user manually re-enables them.
+  void clearModerationBlur() {
+    _videoModerationTimer?.cancel();
+    _videoModerationTimer = null;
+
+    if (!state.value.isVideoModerated) return;
+
+    final config = state.value.preferences.videoModerationConfig;
+    _stateManager.clearModerationBlur();
+
+    if (config.applyBlur) _onModerationBlurClear?.call();
+    config.onClear?.call();
+  }
+
+  /// Registers handlers for the native blur effect pipeline.
+  ///
+  /// Called automatically by `StreamVideoEffectsManager` from
+  /// `stream_video_filters` when [VideoModerationConfig.applyBlur] is true.
+  @internal
+  void setModerationBlurEffectHandlers({
+    required void Function() onApply,
+    required void Function() onClear,
+  }) {
+    _onModerationBlurApply = onApply;
+    _onModerationBlurClear = onClear;
+  }
+
   @internal
   void traceSessionLog(String tag, dynamic data) {
     _session?.trace(tag, data);
@@ -1852,6 +1923,8 @@ class Call {
     ]) {
       timer.cancel();
     }
+    _videoModerationTimer?.cancel();
+    _videoModerationTimer = null;
 
     for (final operation in _sfuStatsTimers) {
       await operation.cancel();
@@ -2932,6 +3005,12 @@ class Call {
     required bool enabled,
     CameraConstraints? constraints,
   }) async {
+    if (enabled &&
+        state.value.isVideoModerated &&
+        state.value.preferences.videoModerationConfig.muteVideo) {
+      _logger.w(() => '[setCameraEnabled] blocked by video moderation');
+      return Result.error('Blocked by video moderation');
+    }
     if (enabled && !hasPermission(CallPermission.sendVideo)) {
       return Result.error('Missing permission to send video');
     }
@@ -3008,6 +3087,12 @@ class Call {
     required bool enabled,
     AudioConstraints? constraints,
   }) async {
+    if (enabled &&
+        state.value.isVideoModerated &&
+        state.value.preferences.videoModerationConfig.muteAudio) {
+      _logger.w(() => '[setMicrophoneEnabled] blocked by video moderation');
+      return Result.error('Blocked by video moderation');
+    }
     if (enabled && !hasPermission(CallPermission.sendAudio)) {
       return Result.error('Missing permission to send audio');
     }

packages/stream_video/lib/src/call/state/mixins/state_coordinator_mixin.dart

@@ -518,4 +518,26 @@ mixin StateCoordinatorMixin on StateNotifier<CallState> {
           .toList(),
     );
   }
+
+  void coordinatorCallModerationBlur(
+    String userId,
+  ) {
+    if (userId != state.currentUserId) {
+      _logger.i(
+        () => '[coordinatorCallModeration] rejected (not current user)',
+      );
+      return;
+    }
+
+    state = state.copyWith(
+      isVideoModerated: true,
+    );
+  }
+
+  void clearModerationBlur() {
+    _logger.i(() => '[clearModerationBlur]');
+    state = state.copyWith(
+      isVideoModerated: false,
+    );
+  }
 }

packages/stream_video/lib/src/call_state.dart

@@ -54,6 +54,7 @@ class CallState extends Equatable {
       anonymousParticipantCount: 0,
       iOSMultitaskingCameraAccessEnabled: false,
       custom: const {},
+      isVideoModerated: false,
     );
   }
 
@@ -95,6 +96,7 @@ class CallState extends Equatable {
     required this.anonymousParticipantCount,
     required this.iOSMultitaskingCameraAccessEnabled,
     required this.custom,
+    required this.isVideoModerated,
   });
 
   final CallPreferences preferences;
@@ -135,6 +137,9 @@ class CallState extends Equatable {
   final bool iOSMultitaskingCameraAccessEnabled;
   final Map<String, Object> custom;
 
+  /// Whether the local user's video is currently blurred by moderation.
+  final bool isVideoModerated;
+
   String get callId => callCid.id;
 
   StreamCallType get callType => callCid.type;
@@ -206,6 +211,7 @@ class CallState extends Equatable {
     int? anonymousParticipantCount,
     bool? iOSMultitaskingCameraAccessEnabled,
     Map<String, Object>? custom,
+    bool? isVideoModerated,
   }) {
     return CallState._(
       preferences: preferences ?? this.preferences,
@@ -248,6 +254,7 @@ class CallState extends Equatable {
           iOSMultitaskingCameraAccessEnabled ??
           this.iOSMultitaskingCameraAccessEnabled,
       custom: custom ?? this.custom,
+      isVideoModerated: isVideoModerated ?? this.isVideoModerated,
     );
   }
 
@@ -321,13 +328,15 @@ class CallState extends Equatable {
     anonymousParticipantCount,
     iOSMultitaskingCameraAccessEnabled,
     custom,
+    isVideoModerated,
   ];
 
   @override
   String toString() {
     return 'CallState(status: $status, currentUserId: $currentUserId,'
         ' callCid: $callCid, createdByUser: $createdByUser,'
         ' sessionId: $sessionId, isRecording: $isRecording,'
+        ' isVideoModerated: $isVideoModerated,'
         ' settings: $settings, egress: $egress, '
         ' videoInputDevice: $videoInputDevice,'
         ' audioInputDevice: $audioInputDevice,'

packages/stream_video/lib/src/models/call_preferences.dart

@@ -1,4 +1,5 @@
 import 'call_client_publish_options.dart';
+import 'moderation_blur_config.dart';
 
 abstract class CallPreferences {
   /// The maximum duration to wait when establishing a connection to the call.
@@ -49,6 +50,10 @@ abstract class CallPreferences {
   /// The maximum number of closed caption lines that can be visible
   /// simultaneously on screen.
   int get closedCaptionsVisibleCaptions;
+
+  /// Configuration for how the SDK handles call moderation events.
+  /// Defaults to [VideoModerationConfig.disabled].
+  VideoModerationConfig get videoModerationConfig;
 }
 
 class DefaultCallPreferences implements CallPreferences {
@@ -62,6 +67,7 @@ class DefaultCallPreferences implements CallPreferences {
     this.clientPublishOptions,
     this.closedCaptionsVisibilityDurationMs = 2700,
     this.closedCaptionsVisibleCaptions = 2,
+    this.videoModerationConfig = const VideoModerationConfig.disabled(),
   });
 
   /// The maximum duration to wait when establishing a connection to the call.
@@ -137,4 +143,10 @@ class DefaultCallPreferences implements CallPreferences {
   /// Defaults to 2 lines.
   @override
   final int closedCaptionsVisibleCaptions;
+
+  /// Configuration for how the SDK handles call moderation events.
+  ///
+  /// Defaults to [VideoModerationConfig.disabled].
+  @override
+  final VideoModerationConfig videoModerationConfig;
 }

packages/stream_video/lib/src/models/models.dart

@@ -19,6 +19,7 @@ export 'call_status.dart';
 export 'call_track_state.dart';
 export 'disconnect_reason.dart';
 export 'guest_created_data.dart';
+export 'moderation_blur_config.dart';
 export 'push_device.dart';
 export 'push_provider.dart';
 export 'queried_calls.dart';

packages/stream_video/lib/src/models/moderation_blur_config.dart

@@ -0,0 +1,71 @@
+import 'dart:ui';
+
+/// Configures how the SDK handles `call.moderation` events.
+///
+/// Convenience constructors [VideoModerationConfig.disabled],
+/// [VideoModerationConfig.mute], and [VideoModerationConfig.blur] cover
+/// the most common presets.
+class VideoModerationConfig {
+  const VideoModerationConfig({
+    this.muteAudio = false,
+    this.muteVideo = false,
+    this.applyBlur = false,
+    this.duration,
+    this.onApply,
+    this.onWarning,
+    this.onClear,
+  });
+
+  /// No automatic action. The event is still emitted on the call's event
+  /// stream for manual handling via `call.callEvents`.
+  const VideoModerationConfig.disabled()
+    : muteAudio = false,
+      muteVideo = false,
+      applyBlur = false,
+      duration = null,
+      onApply = null,
+      onWarning = null,
+      onClear = null;
+
+  /// Mutes the local user's microphone and camera, and prevents re-enabling
+  /// them for the configured [duration]. If [duration] is null, the mute
+  /// persists until `call.clearModerationBlur()` is called.
+  const VideoModerationConfig.mute({this.duration})
+    : muteAudio = true,
+      muteVideo = true,
+      applyBlur = false,
+      onApply = null,
+      onWarning = null,
+      onClear = null;
+
+  /// Applies a full-frame native blur on the camera track via
+  /// `StreamVideoEffectsManager` from the `stream_video_filters` package.
+  /// The blur is visible to ALL participants because it modifies frames
+  /// before encoding. Requires the `stream_video_filters` package.
+  const VideoModerationConfig.blur({this.duration})
+    : muteAudio = false,
+      muteVideo = false,
+      applyBlur = true,
+      onApply = null,
+      onWarning = null,
+      onClear = null;
+
+  final bool muteAudio;
+  final bool muteVideo;
+  final bool applyBlur;
+
+  final Duration? duration;
+
+  final VoidCallback? onApply;
+  final void Function(String)? onWarning;
+  final VoidCallback? onClear;
+
+  /// Whether this config takes no automatic action.
+  bool get isDisabled =>
+      !muteAudio &&
+      !muteVideo &&
+      !applyBlur &&
+      onApply == null &&
+      onWarning == null &&
+      onClear == null;
+}

packages/stream_video/lib/src/retry/retry_manager.dart

@@ -1,3 +1,4 @@
+import '../../open_api/video/coordinator/api.dart';
 import '../errors/video_error.dart';
 import '../utils/result.dart';
 import 'retry_policy.dart';
@@ -30,8 +31,30 @@ class RpcRetryManager {
         delegate,
       );
       retryAttempt++;
-    } while (result.isFailure && retryAttempt < policy.config.rpcMaxRetries);
+    } while (result.isFailure &&
+        retryAttempt < policy.config.rpcMaxRetries &&
+        _isRetryable(result));
 
     return result;
   }
+
+  /// Returns false for permanent client errors (4xx except 408/429)
+  /// that should not be retried.
+  bool _isRetryable(Result<dynamic> result) {
+    if (result is! Failure) return true;
+
+    final error = result.error;
+    if (error is! VideoErrorWithCause) return true;
+
+    final cause = error.cause;
+    if (cause is! ApiException) return true;
+
+    final statusCode = cause.code;
+    if (statusCode >= 400 && statusCode < 500) {
+      // 408 Request Timeout and 429 Too Many Requests are retryable
+      return statusCode == 408 || statusCode == 429;
+    }
+
+    return true;
+  }
 }

packages/stream_video/lib/src/webrtc/peer_connection.dart

@@ -219,14 +219,14 @@ class StreamPeerConnection extends Disposable {
       final modifiedSdp = sdp != null
           ? sdpEditor.edit(Sdp.localAnswer(sdp, offerSdp: offerSdp))
           : null;
-      
+
       if (modifiedSdp == null || modifiedSdp.isEmpty) {
         _logger.w(
           () => '[createLocalAnswer] #$type; rejected (SDP is null/empty)',
         );
         return Result.error('createAnswer produced null/empty SDP');
       }
-      
+
       final modifiedAnswer = localAnswer.copyWith(sdp: modifiedSdp);
 
       _logger.v(

packages/stream_video/lib/src/webrtc/sdp/sdp.dart

@@ -10,8 +10,7 @@ sealed class Sdp {
   static LocalAnswerSdp localAnswer(
     String sdp, {
     String? offerSdp,
-  }) =>
-      LocalAnswerSdp(sdp, offerSdp: offerSdp);
+  }) => LocalAnswerSdp(sdp, offerSdp: offerSdp);
 
   static RemoteOfferSdp remoteOffer(String sdp) => RemoteOfferSdp(sdp);