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

🚀 Quick Start

Installation

Add to your pubspec.yaml:

dependencies:
  smart_selfie_capture: ^0.0.1

Then run:

flutter pub get

Platform-Specific Setup

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

platform :ios, '15.5'

cd ios && pod install

android {
    defaultConfig {
        minSdkVersion 21
        compileSdkVersion 34
    }
}

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

💡 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:

Example:

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

⚙️ Configuration Options

SelfieConfig

ValidationRules

Fine-tune face validation behavior:

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:

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

🎯 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

🚀 How It Works

Process Flow

1. 🎬 Initialization - Camera and ML Kit face detectors start
2. 👁️ Face Detection - Real-time detection on camera stream (30 FPS)
3. ✅ Validation - Face checked against configured rules:
   • Face size 30-80% of frame (distance check)
   • Head pose within ±15° (frontal face)
   • Eyes open detection
   • Optional smile detection
4. 🔴 Liveness Check - Blink or mouth open to prevent photo spoofing
5. ⏱️ Countdown - 3-second countdown with visual feedback
6. 📸 Capture - High-resolution image captured and saved
7. 📦 Result - Returns SelfieResult with validation data

Visual Feedback Features

• ✨ Real-time face overlay with corner brackets
• 🎨 Color-coded status messages (green = good, red = error)
• ⏰ Countdown timer animation
• 📊 Scanning animation during detection

📜 License

This project is licensed under the MIT License - see the LICENSE file for details.

🤝 Contributing

Contributions are welcome! Please read CONTRIBUTING.md for guidelines on:

• Code standards and style
• Testing requirements
• Pull request process
• Issue reporting

📝 Changelog

See CHANGELOG.md for version history and release notes.

🐛 Issues & Support

• Bug Reports: Open an issue
• Feature Requests: Request a feature
• Questions: Ask a question

🙏 Acknowledgments

This package is built on top of excellent open-source projects:

• Google ML Kit - Face detection and classification
• Camera Plugin - Flutter camera integration
• Flutter Community - For continuous support and feedback

⭐ Show Your Support

If this package helped your project, please:

• ⭐ Star the repository on GitHub
• 👍 Like it on pub.dev
• 📢 Share it with other developers

Made with ❤️ for the Flutter community