proveface

A Flutter package for real-time face liveness detection.

Challenges users with randomised blink, smile, and head-turn checks powered by Google ML Kit, plus passive anti-spoofing to reject printed photos, screens, and video replay attacks. Camera permission is requested automatically — no setup needed in the consuming app.

Features

✅ Blink detection (eyes-closed → eyes-open confirmation)
✅ Smile detection (geometry-verified, multi-frame)
✅ Head turn — left, right, up, down (with ghost-face guide overlay)
✅ Passive anti-spoofing via ML model
✅ Screen / video replay detection via pixel texture analysis
✅ Distance, centering, lighting, sunglasses, mask checks
✅ Camera permission handled internally
✅ Fully configurable challenges and timeouts
✅ Returns typed ProveFaceResult with base64 JPEG on success

Platform support

Android	iOS
✅ API 23+	✅ iOS 12.0+

Installation

dependencies:
  proveface: ^1.0.0

flutter pub get

Setup

Android

In android/app/build.gradle:

android {
  defaultConfig {
    minSdkVersion 23
  }
}

iOS

In ios/Runner/Info.plist:

<key>NSCameraUsageDescription</key>
<string>Used for face liveness verification.</string>

In ios/Podfile:

platform :ios, '12.0'

Usage

import 'package:proveface/proveface.dart';

final result = await Navigator.push<ProveFaceResult>(
  context,
  MaterialPageRoute(
    builder: (_) => ProveFaceDetector(
      appBarColor: const Color(0xFF0D4582),
      config: const ProveFaceConfig(
        enableBlink:     true,
        enableSmile:     true,
        enableTurnLeft:  true,
        enableTurnRight: true,
        enableTurnUp:    false,
        enableTurnDown:  false,
      ),
    ),
  ),
);

if (result?.success == true) {
  final base64Image = result!.capturedImageBase64!;
  // upload to your server
}

Configuration

ProveFaceConfig

Parameter	Type	Default	Description
`enableBlink`	`bool`	`true`	Include blink challenge
`enableSmile`	`bool`	`true`	Include smile challenge
`enableTurnLeft`	`bool`	`true`	Include turn-left challenge
`enableTurnRight`	`bool`	`true`	Include turn-right challenge
`enableTurnUp`	`bool`	`true`	Include turn-up challenge
`enableTurnDown`	`bool`	`true`	Include turn-down challenge
`blinkTimeoutSeconds`	`int`	`7`	Seconds allowed for blink
`smileTimeoutSeconds`	`int`	`7`	Seconds allowed for smile
`turnTimeoutSeconds`	`int`	`7`	Seconds allowed per turn
`sessionTimeoutSeconds`	`int`	`0`	`0` = auto (sum of all enabled timeouts)

Parameter	Type	Default	Description
`config`	`ProveFaceConfig`	all enabled	Challenge configuration
`appBarColor`	`Color`	`Color(0xFF0D4582)`	AppBar background colour
`title`	`String`	`'Face Verification'`	AppBar title
`onResult`	`Function(ProveFaceResult)?`	`null`	Callback fired before route pops

Result

class ProveFaceResult {
  final bool    success;
  final String? capturedImageBase64; // non-null on success
  final String? errorMessage;        // non-null on failure
}

Result scenarios

Scenario	`success`	`errorMessage`
All challenges passed	`true`	`null`
User pressed back	`false`	`'User cancelled'`
Camera permission denied	`false`	`'Camera permission denied'`
Session timed out	Restarts automatically	—

How anti-spoofing works

Three independent layers run simultaneously:

Active challenges — Randomised sequence a static photo or looped video cannot pass.
Passive ML model — Scores every 6th frame; rejects if rolling average falls below threshold.
Screen texture analysis — Pixel variance and banding checks flag phone screens or printed photos.

License

MIT — see LICENSE