NativeVirtualBackground class

Native virtual background helper for Android, iOS, and macOS.

This class communicates with platform-specific native code that:

  1. Intercepts video frames from the camera track
  2. Runs segmentation to create a person mask
  3. Composites the person over the background image
  4. Sends processed frames through WebRTC to remote participants

Platform Support:

  • Android: ✅ Supported via LocalVideoTrack.ExternalVideoFrameProcessing + MediaPipe
  • iOS: ✅ Supported via VideoProcessingAdapter + Vision framework
  • macOS: ✅ Supported via VideoProcessingAdapter + Vision framework (requires macOS 12.0+)
  • Windows/Linux: ❌ Not supported - flutter_webrtc C++ layer lacks video processing hooks
  • Web: ❌ Not supported - would need different approach (canvas-based)

For unsupported platforms, the fallback is local-only background replacement which only affects the local preview but not what remote participants see.

Usage:

final helper = NativeVirtualBackground();

// Initialize the native segmentation engine
await helper.initialize();

// Enable with a video track and background image
await helper.enable(
  trackId: localVideoTrack.id!,
  backgroundImage: imageBytes,
);

// Update background
await helper.updateBackground(newImageBytes);

// Disable
await helper.disable();

// Cleanup
await helper.dispose();

Constructors

NativeVirtualBackground()

Properties

hashCode → int
The hash code for this object.
no setterinherited
isEnabled → bool
Whether virtual background is currently enabled.
no setter
isInitialized → bool
Whether the native virtual background is initialized.
no setter
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited

Methods

checkEnabled() → Future<bool>
Check if virtual background is currently enabled (from native side).
disable() → Future<bool>
Disable virtual background processing.
dispose() → Future<void>
Release all resources.
enable({required String trackId, required Uint8List backgroundImage, double confidence = 0.7}) → Future<bool>
Enable virtual background for a video track.
initialize({bool useGpu = true}) → Future<bool>
Initialize the native virtual background engine.
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
toString() → String
A string representation of this object.
inherited
updateBackground(Uint8List backgroundImage) → Future<bool>
Update the background image.

Operators

operator ==(Object other) → bool
The equality operator.
inherited

Static Properties

isSupported → bool
Check if native virtual background is supported on this platform.
no setter