face_overlay 0.1.0

Real-time AR face overlay for Flutter. Uses CameraX (Android) and AVFoundation (iOS) with Google MediaPipe Face Landmarker to detect 478 facial landmarks and render any PNG image as an overlay on dete [...]

face_overlay

A Flutter plugin that detects faces in real time using Google MediaPipe Face Landmarker and renders any PNG image as an AR overlay on every detected face — works on both Android and iOS.

Features

• Real-time face detection using MediaPipe's 478-point face landmark model
• Overlays any PNG asset on detected faces, scaled to cover the face bounding box
• Overlay top aligns with the forehead and bottom with the chin in portrait orientation
• Supports multiple faces simultaneously
• Front camera
• Debug mode to visualise all 478 landmarks
• Built-in model bundled with the plugin — no extra downloads required

Platform support

Android	iOS
API 24+	14.0+

Installation

Add the dependency to your pubspec.yaml:

dependencies:
  face_overlay: ^0.0.1

Declare the camera permission:

Android — android/app/src/main/AndroidManifest.xml:

<uses-permission android:name="android.permission.CAMERA" />

iOS — ios/Runner/Info.plist:

<key>NSCameraUsageDescription</key>
<string>Camera is used to detect your face and display an AR overlay.</string>

iOS Podfile — required for MediaPipe static linking and permission_handler v11+:

platform :ios, '14.0'

target 'Runner' do
  use_frameworks! :linkage => :static
  # ...
end

post_install do |installer|
  installer.pods_project.targets.each do |target|
    flutter_additional_ios_build_settings(target)
    target.build_configurations.each do |config|
      config.build_settings['GCC_PREPROCESSOR_DEFINITIONS'] ||= ['$(inherited)']
      config.build_settings['GCC_PREPROCESSOR_DEFINITIONS'] << 'PERMISSION_CAMERA=1'
    end
  end
end

Usage

1. Request camera permission

Use permission_handler or any preferred package to request Permission.camera before initialising the controller.

2. Create a controller

final controller = FaceOverlayController(
  config: const FaceOverlayConfig(
    maxFaces: 1,
    minFaceDetectionConfidence: 0.5,
    minTrackingConfidence: 0.5,
  ),
  overlays: const [
    OverlayAsset(assetPath: 'assets/my_overlay.png'),
  ],
);

await controller.initialize();

3. Show the camera view

FaceOverlayView(
  controller: controller,
  isFrontCamera: true, // plugin always uses the front camera
  debugLandmarks: false,
)

4. Dispose when done

@override
void dispose() {
  controller.dispose();
  super.dispose();
}

OverlayAsset options

Parameter	Type	Default	Description
assetPath	String	required	Flutter asset path declared in pubspec.yaml
widthScale	double	1.5	Extra size multiplier — 1.0 fills the face box exactly
anchorOffset	Offset	Offset.zero	Fine-tunes the centre in fractions of face height (x right, y down)

How face detection works

The plugin uses MediaPipe Face Landmarker in LIVE_STREAM mode to detect up to N faces per frame and produce 478 normalised 3-D landmarks. On Android the camera feed comes from CameraX; on iOS from AVFoundation. Each frame is passed to the landmarker on a background thread, and the resulting landmark coordinates are sent to Flutter via an EventChannel.

The Dart side converts normalised coordinates to canvas pixels and passes them to a CustomPainter (FacePainter). The painter picks four key landmarks — forehead top, chin bottom, face left, and face right — to compute the face centre, bounding box size, and head tilt angle. The overlay image is scaled and rotated so its top faces the forehead and its bottom faces the chin in portrait orientation.