smart_selfie_capture 0.0.1

A Flutter package for capturing selfies with face validation, object detection, and liveness checks. Includes customizable messages and real-time feedback.

Smart Selfie Capture

A comprehensive Flutter package for capturing selfies with advanced features including face validation, liveness checks, and real-time feedback. Perfect for KYC, identity verification, and secure photo capture applications.

✨ Features

• 🎯 Real-time Face Detection - Powered by Google ML Kit
• 🔒 Three Liveness Check Modes - Blink, mouth open, or both
• 📏 Advanced Face Validation - Size, orientation, eyes, and smile detection
• 🎨 Fully Customizable UI - Colors, messages, instructions, and themes
• ⚡ Instant Visual Feedback - Face overlay with corner brackets
• 🌐 Cross-platform - iOS 15.5+ and Android 21+
• 🧪 Well Tested - 26 unit tests with comprehensive coverage
• 📚 Complete Documentation - API reference and examples included

📸 Screenshots

Basic Selfie	Liveness Check	Smile Detection
Face detection with overlay	Blink or mouth open	Smile validation

🚀 Quick Start

🚀 Quick Start

Installation

Add to your pubspec.yaml:

dependencies:
  smart_selfie_capture: ^0.0.1

Then run:

flutter pub get

Platform-Specific Setup

📱 iOS Setup

1. Add camera permission to ios/Runner/Info.plist:

<key>NSCameraUsageDescription</key>
<string>Camera access is required to capture your selfie</string>

2. Set minimum iOS version in ios/Podfile:

platform :ios, '15.5'

3. Run pod install:

cd ios && pod install

🤖 Android Setup

1. Update minimum SDK in android/app/build.gradle:

android {
    defaultConfig {
        minSdkVersion 21
        compileSdkVersion 34
    }
}

2. Add permissions to android/app/src/main/AndroidManifest.xml:

<uses-permission android:name="android.permission.CAMERA" />
<uses-feature android:name="android.hardware.camera" android:required="true" />

3. Handle camera permissions in your app before opening the capture screen.

💡 Usage Examples

Basic Selfie Capture

Simple selfie capture with default settings:

import 'package:smart_selfie_capture/smart_selfie_capture.dart';

SelfieCaptureScreen(
  config: const SelfieConfig(
    title: 'Take a Selfie',
    enableLivenessCheck: false,
  ),
  onCaptureComplete: (SelfieResult result) {
    print('Image saved: ${result.imagePath}');
    print('Validated: ${result.isValidated}');
    Navigator.pop(context);
  },
)

Identity Verification with Liveness

Complete verification with mouth opening detection:

SelfieCaptureScreen(
  config: const SelfieConfig(
    title: 'Verify Your Identity',
    subtitle: 'Position your face in the frame',
    enableLivenessCheck: true,
    livenessCheckType: LivenessCheckType.mouthOpen,
    livenessBlinkCount: 1,
    customMessage: 'Please ensure you are in a well-lit area',
    instructions: [
      'Look directly at the camera',
      'Open your mouth when prompted',
      'Hold still during capture',
    ],
    validationRules: ValidationRules(
      requireFrontalFace: true,
      requireEyesOpen: true,
      minFaceSize: 0.4,
      maxFaceSize: 0.7,
    ),
    primaryColor: Colors.blue,
  ),
  onCaptureComplete: (result) {
    if (result.isValidated && result.livenessCheckPassed) {
      // Process verified selfie
      uploadToServer(result.imagePath);
    }
  },
  onCancel: () {
    Navigator.pop(context);
  },
)

Smile Detection

Capture a selfie with smile requirement:

SelfieCaptureScreen(
  config: SelfieConfig(
    title: 'Smile Please! 😊',
    subtitle: 'Show us your best smile',
    validationRules: const ValidationRules(
      requireSmile: true,
      requireEyesOpen: true,
      minFaceSize: 0.35,
    ),
    enableLivenessCheck: false,
    primaryColor: Colors.orange,
  ),
  onCaptureComplete: (result) {
    showDialog(
      context: context,
      builder: (_) => AlertDialog(
        title: Text('Perfect!'),
        content: Image.file(File(result.imagePath)),
      ),
    );
  },
)

🎯 Liveness Check Types

The package supports three liveness detection modes:

Type	Description	Use Case
LivenessCheckType.blink	Detects eye blinks	Traditional liveness check
LivenessCheckType.mouthOpen	Detects mouth opening	Alternative liveness method
LivenessCheckType.both	Requires both actions	Maximum security

Example:

SelfieConfig(
  enableLivenessCheck: true,
  livenessCheckType: LivenessCheckType.mouthOpen,
  livenessBlinkCount: 1,  // Number of times to perform action
)

⚙️ Configuration Options

SelfieConfig

Property	Type	Default	Description
title	String	'Capture Selfie'	Screen title
subtitle	String	'Position your face...'	Subtitle text
instructions	List<String>	[...]	List of instructions
validationRules	ValidationRules	ValidationRules()	Face validation criteria
enableLivenessCheck	bool	true	Enable liveness detection
livenessCheckType	LivenessCheckType	mouthOpen	Type of liveness check
livenessBlinkCount	int	2	Required action count
enableObjectDetection	bool	true	Enable object detection
primaryColor	Color	Colors.blue	Primary UI color
backgroundColor	Color	Colors.black	Background color
captureDelay	Duration	3 seconds	Countdown duration
customMessage	String?	null	Custom banner message

ValidationRules

Fine-tune face validation behavior:

Property	Type	Default	Description
requireFrontalFace	bool	true	Face must look at camera
requireEyesOpen	bool	true	Eyes must be open
requireSmile	bool	false	Smile detection
minFaceSize	double	0.3	Min face size (0.0-1.0)
maxFaceSize	double	0.8	Max face size (0.0-1.0)
minEulerAngleX/Y/Z	double	-15.0	Head angle tolerance
maxEulerAngleX/Y/Z	double	15.0	Head angle tolerance
allowMultipleFaces	bool	false	Allow multiple faces

Example:

ValidationRules(
  requireFrontalFace: true,
  requireEyesOpen: true,
  minFaceSize: 0.4,      // Face should be 40%+ of frame
  maxFaceSize: 0.7,      // Face should be max 70% of frame
  minEulerAngleY: -15.0, // Allow 15° left/right turn
  maxEulerAngleY: 15.0,
)

SelfieResult

The capture result contains:

Property	Type	Description
imagePath	String	Absolute path to saved image
isValidated	bool	Face validation status
livenessCheckPassed	bool	Liveness check status
validationDetails	Map	Detailed validation data
capturedAt	DateTime	Capture timestamp

Example:

onCaptureComplete: (SelfieResult result) {
  print('Image: ${result.imagePath}');
  print('Valid: ${result.isValidated}');
  print('Live: ${result.livenessCheckPassed}');
  print('Blinks: ${result.validationDetails['blinkCount']}');
  print('Time: ${result.capturedAt}');
}

📖 Documentation

• API Reference - Complete API documentation
• Contributing Guide - How to contribute
• Changelog - Version history
• Example App - Working examples

🔧 Troubleshooting

Camera not initializing

• Verify camera permissions are granted
• Check platform-specific setup is complete
• Ensure device has a working camera
• Test on physical device (emulators may have issues)

Face not detected

• Improve lighting conditions
• Position face in center of frame
• Remove obstructions (glasses, masks, hats)
• Ensure face is within size range (30-80% of frame)
• Check that face is looking at camera

Liveness check not working

• Ensure good lighting for eye/mouth detection
• Try different liveness types (blink vs mouth open)
• Increase livenessBlinkCount threshold
• Check that eyes/mouth are clearly visible

Performance issues

• Use ResolutionPreset.medium for older devices
• Disable enableObjectDetection if not needed
• Reduce validation strictness
• Test on physical device (emulators are slower)

ML Kit errors

• Verify Google Play Services (Android)
• Check minimum platform requirements
• Ensure internet connection for first-time ML Kit download
• Clear app cache and reinstall

🎯 Use Cases

• 👤 KYC Verification - Know Your Customer identity checks
• 🏦 Banking Apps - Secure customer onboarding
• 🎫 Event Check-in - Photo-based attendance
• 🆔 ID Verification - Government ID matching
• 👨‍⚕️ Healthcare - Patient identification
• 🚗 Ride Sharing - Driver verification
• 🏢 Access Control - Building entry systems

⚡ Performance Tips

1. Resolution: Use medium for faster processing on older devices
2. Validation: Relax angle tolerances for easier capture
3. Liveness: Single action is faster than multiple
4. Object Detection: Disable if not needed for security

📋 Requirements

Requirement	Minimum Version
Flutter SDK	3.3.0+
Dart SDK	3.9.2+
iOS	15.5+
Android	API 21+ (5.0)

Features in Detail

Face Validation

• Ensures face is properly positioned
• Checks head pose angles
• Validates eye state
• Optional smile detection

Liveness Detection

• Blink detection to prevent photo spoofing
• Configurable number of required blinks
• Real-time feedback

Object Detection

• Can detect objects in the scene
• Useful for preventing fake photos
• Optional feature

Visual Feedback

• Real-time face overlay with corner brackets
• Color-coded status messages
• Countdown timer
• Scanning animation

Example App

See the /example folder for a complete working example.

Requirements

• Flutter SDK: >=3.0.0
• Dart SDK: >=3.0.0
• iOS: >=15.5
• Android: >=21 (Android 5.0)

Permissions

The package requires camera permission. Make sure to:

1. Request permission before using the package
2. Handle permission denial gracefully
3. Add platform-specific permission declarations

Troubleshooting

Camera not initializing

• Check camera permissions are granted
• Verify platform-specific setup is complete
• Ensure device has a camera

Face not detected

• Improve lighting conditions
• Position face in center of frame
• Remove obstructions (glasses, masks)

ML Kit errors

• Ensure Google ML Kit dependencies are properly installed
• Check that device supports ML Kit
• Verify minimum platform requirements

Contributing

Contributions are welcome! Please read our contributing guidelines and submit pull requests.

License

MIT License - see LICENSE file for details

Support

For issues and feature requests, please file an issue on GitHub.

Credits

Built with:

• Google ML Kit for face and object detection
• Camera plugin for Flutter
• Path Provider for file management