flutter_face_guide

flutter_face_guide is a Flutter package for building guided face-capture flows for onboarding and KYC-style experiences.

The package provides state orchestration and quality gating. It does not handle biometric identity verification or anti-fraud decisions.

Purpose

This package exists to solve a common product gap in selfie capture UX:

• inconsistent guidance behavior across screens and apps
• weak capture validation before users submit an image
• UI and state logic tightly coupled and hard to test

flutter_face_guide separates these concerns into composable primitives:

• capture flow state machine via FaceGuideController
• quality policies via FaceGuideConfig
• quality evaluation via FaceQualityChecker
• standardized result model via FaceCaptureResult

Features

• lifecycle API: start, pause, resume, stop, capture
• explicit status transitions (idle, aligning, ready, capturing, etc.)
• configurable quality thresholds (brightness, sharpness, faceCenterRatio)
• optional challenge hold step before capture
• stream-based state updates for UI synchronization

Non-goals

• biometric identity matching
• enterprise liveness detection
• replacing server-side fraud and compliance systems

Getting Started

Add the dependency:

dependencies:
  flutter_face_guide: ^0.1.0

Install packages:

flutter pub get

Usage

import 'package:flutter_face_guide/flutter_face_guide.dart';

final controller = FaceGuideController(
  config: const FaceGuideConfig(
    enableChallenge: true,
    minBrightness: 0.20,
    minSharpness: 0.03,
    minFaceCenterRatio: 0.20,
  ),
);

await controller.start();

controller.updateQuality(
  const QualityInput(
    brightness: 0.82,
    sharpness: 0.79,
    faceCenterRatio: 0.90,
  ),
);

final result = await controller.capture();
if (result.ok) {
  // Continue your flow.
}

See the runnable integration in example/lib/main.dart.

Optional Detector Adapter

This package is intentionally detector-agnostic. If you want built-in ML Kit face detection integration, use the optional adapter package:

• adapters/flutter_face_guide_mlkit

Adapter dependency example:

dependencies:
  flutter_face_guide: ^0.1.0
  flutter_face_guide_mlkit:
    path: ../adapters/flutter_face_guide_mlkit

Adapter usage example:

import 'package:flutter_face_guide/flutter_face_guide.dart';
import 'package:flutter_face_guide_mlkit/flutter_face_guide_mlkit.dart';

final adapter = MlKitFaceGuideAdapter();

final analysis = await adapter.analyze(
  image: inputImage,
  frameWidth: frameWidth,
  frameHeight: frameHeight,
);

controller.updateQuality(
  analysis.toQualityInput(
    brightness: brightnessScore,
    sharpness: sharpnessScore,
  ),
);

Architecture

Core flow:

1. App calls start() to enter alignment mode.
2. App feeds metrics to updateQuality(QualityInput).
3. Controller emits FaceGuideState updates on state stream.
4. When quality passes, status becomes ready.
5. App calls capture() and receives FaceCaptureResult.

Quality contract:

• brightness: normalized 0.0 to 1.0
• sharpness: normalized 0.0 to 1.0
• faceCenterRatio: normalized 0.0 to 1.0 (higher means more centered)

API Reference

• FaceGuideController: state and capture orchestrator
• FaceGuideConfig: threshold and challenge policy
• QualityInput: input metrics model
• FaceQualityReport: evaluation output and issue list
• FaceCaptureResult: final capture outcome model

Operational Notes

• Thresholds are product and device dependent. Tune in your own environment.
• For real-time camera use, compute brightness and sharpness externally and pass them through QualityInput.
• The optional ML Kit adapter computes face-center ratio from detected face boxes.
• Keep user messaging clear: this package provides guidance, not identity proof.

Development Checklist

• dart format .
• flutter analyze
• flutter test
• dart pub publish --dry-run