Face Recognition Authentication

A powerful Flutter package that provides secure, reliable face recognition authentication using TensorFlow Lite and Google ML Kit. Implement face-based authentication in your Flutter apps with real-time face detection, quality assessment, and a clean, customizable UI.

✨ Features

🔐 Secure Face Authentication

TensorFlow Lite Integration: Powered by MobileFaceNet for accurate face recognition
Real-time Face Detection: Google ML Kit integration for robust face detection
Quality Assessment: Intelligent face quality scoring to prevent poor registrations
Stable Detection: Requires consecutive stable frames for reliable authentication
Embedding Validation: Ensures consistency between face embeddings
User ID Management: Custom user ID support with duplicate checking and validation

🎨 Clean & Customizable UI

Face Detection Visualization: Visual feedback with customizable face detection boxes
Real-time Camera Preview: Live camera feed with face detection overlay
Customizable Styling: Easy to customize colors, sizes, and visual elements
Responsive Design: Works seamlessly across different screen sizes
Clean Interface: Minimal, focused UI for optimal user experience

🚀 Enhanced User Experience

Real-time Face Detection: Instant feedback when faces are detected
Progress Tracking: Clear status updates during authentication process
Error Handling: Comprehensive error handling and timeout management
Cross-platform Support: Works on both iOS and Android
Easy Integration: Simple API for quick implementation

🔧 Developer Friendly

Simple API: Easy-to-use controller-based architecture
Customizable: Configurable face detection parameters and UI styling
State Management: Built-in state management with progress callbacks
Error Handling: Comprehensive error handling and timeout management
Cross-platform: Works on both iOS and Android

📱 Screenshots

Screenshots will be added here showing the face detection UI and authentication flow

🚀 Getting Started

Prerequisites

Flutter 3.0+
Dart 2.17+
Camera permissions
Google ML Kit Face Detection
TensorFlow Lite

Installation

Add this to your package's pubspec.yaml file:

dependencies:
  face_recognition_auth: ^1.0.0

Setup

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

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

Add camera permissions to your ios/Runner/Info.plist:

<key>NSCameraUsageDescription</key>
<string>This app needs camera access for face recognition authentication</string>

Initialize the package in your app:

import 'package:face_recognition_auth/face_recognition_auth.dart';

void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await setupServices(); // If using the example setup
  runApp(MyApp());
}

💻 Usage

Basic Face Registration

import 'package:face_recognition_auth/face_recognition_auth.dart';

class FaceRegistrationScreen extends StatefulWidget {
  @override
  _FaceRegistrationScreenState createState() => _FaceRegistrationScreenState();
}

class _FaceRegistrationScreenState extends State<FaceRegistrationScreen> {
  final FaceAuthController _controller = FaceAuthController();
  String _status = "Initializing...";

  @override
  void initState() {
    super.initState();
    _startRegistration();
  }

  Future<void> _startRegistration() async {
    await _controller.initialize();

    _controller.register(
      samples: 4,
      userId: "user_123", // Unique user identifier
      onProgress: (state) {
        setState(() {
          switch (state) {
            case FaceAuthState.cameraOpened:
              _status = "Camera Ready";
              break;
            case FaceAuthState.detectingFace:
              _status = "Looking for Face";
              break;
            case FaceAuthState.collectingSamples:
              _status = "Registering Face Data";
              break;
            case FaceAuthState.success:
              _status = "Registration Complete!";
              break;
            case FaceAuthState.failed:
              _status = "Registration Failed";
              break;
          }
        });
      },
      onDone: (user) {
        if (user != null) {
          print("User registered: ${user.id}");
        }
      },
    );
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      body: Stack(
        children: [
          FaceAuthView(controller: _controller),
          Align(
            alignment: Alignment.bottomCenter,
            child: Container(
              color: Colors.black54,
              padding: EdgeInsets.all(16),
              child: Text(
                _status,
                style: TextStyle(color: Colors.white, fontSize: 18),
              ),
            ),
          ),
        ],
      ),
    );
  }

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

Face Authentication

class FaceLoginScreen extends StatefulWidget {
  @override
  _FaceLoginScreenState createState() => _FaceLoginScreenState();
}

class _FaceLoginScreenState extends State<FaceLoginScreen> {
  final FaceAuthController _controller = FaceAuthController();

  @override
  void initState() {
    super.initState();
    _startLogin();
  }

  Future<void> _startLogin() async {
    await _controller.initialize();

    _controller.login(
      onProgress: (state) {
        // Handle progress updates
      },
      onDone: (user) {
        if (user != null) {
          print("Login successful: ${user.id}");
          // Navigate to main app
        } else {
          print("Login failed");
        }
      },
    );
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      body: FaceAuthView(controller: _controller),
    );
  }

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

Custom Configuration

// Customize quality thresholds
_controller.register(
  samples: 6, // More samples for higher accuracy
  userId: "custom_user_id", // Unique user identifier
  onProgress: (state) {
    // Custom progress handling
  },
  onDone: (user) {
    // Custom completion handling
  },
);

🎯 Advanced Features

Face Detection Features

The package provides robust face detection capabilities:

Real-time Detection: Instant face detection using Google ML Kit
Multiple Face Support: Can detect and track multiple faces
Bounding Box Visualization: Visual feedback with customizable face boxes
Camera Integration: Seamless integration with device cameras

UI Customization

// Customize face detection box styling
class CustomFaceBoxPainter extends CustomPainter {
  @override
  void paint(Canvas canvas, Size size) {
    final paint = Paint()
      ..color = Colors.blue // Custom color
      ..strokeWidth = 4     // Custom stroke width
      ..style = PaintingStyle.stroke;

    // Custom drawing logic
  }
}

State Management

enum FaceAuthState {
  cameraOpened,
  detectingFace,
  collectingSamples,
  matching,
  success,
  failed,
  timeout,
}

📊 Performance

Fast Detection: Real-time face detection with Google ML Kit
Efficient Processing: TensorFlow Lite for optimized inference
Memory Optimized: Smart memory management and resource disposal
Battery Friendly: Optimized camera usage and processing

🔒 Security

Local Processing: All face recognition happens locally on device
No Cloud Dependencies: Face data never leaves the device
Secure Storage: Encrypted local database for face embeddings
Privacy Focused: No external API calls or data transmission

🛠️ API Reference

FaceAuthController

Main controller for face authentication operations.

class FaceAuthController extends ChangeNotifier {
  Future<void> initialize();
  Future<void> initializeDatabaseOnly(); // New: Lightweight DB-only initialization
  Future<void> register({int samples, String userId, Function onProgress, Function onDone});
  Future<void> login({Function onProgress, Function onDone});
  Future<bool> userExists(String userId);
  Future<User?> getUserById(String userId);
  Future<int> deleteUser(String userId);
  Future<List<User>> getAllUsers();
  Future<void> deleteAllUsers(); // New: Delete all users
  void dispose();
}

Database Operations

The package uses SQLite for local storage of face embeddings and user data.

// Get database helper instance
final db = DatabaseHelper.instance;

// Check if a user exists
final exists = await db.userExists('user_123');
if (exists) {
  print('User already exists');
}

// Get user by ID
final user = await db.getUserById('user_123');
if (user != null) {
  print('Found user: ${user.id}');
}

// Delete specific user
await db.deleteUser('user_123');

// Query all registered users
final users = await db.queryAllUsers();

// Delete all users
await db.deleteAll();

Using FaceAuthController for Database Operations

final controller = FaceAuthController();
await controller.initialize();

// Check if user exists
final exists = await controller.userExists('user_123');
if (exists) {
  print('User exists');
}

// Get user details
final user = await controller.getUserById('user_123');
if (user != null) {
  print('User: ${user.id} with ${user.modelData.length} embeddings');
}

// Delete specific user
await controller.deleteUser('user_123');

// Get all users
final allUsers = await controller.getAllUsers();
print('Total users: ${allUsers.length}');

Database-Only Operations (No Camera Initialization)

For lightweight database operations without camera setup, you can use the database-only methods:

final controller = FaceAuthController();

// These methods automatically initialize only the database
// No camera, ML models, or face detection services are loaded

// Check if user exists (fast, no camera init)
final exists = await controller.userExists('user_123');

// Get user details (fast, no camera init)
final user = await controller.getUserById('user_123');

// Delete user (fast, no camera init)
await controller.deleteUser('user_123');

// Get all users (fast, no camera init)
final allUsers = await controller.getAllUsers();

// Delete all users (database cleanup)
await controller.deleteAllUsers();

// Clean up when done
controller.dispose();

Benefits of Database-Only Operations:

⚡ 10-50x faster initialization than full camera setup
💾 Lower memory usage (no ML models loaded)
🔋 Minimal battery impact
🚫 No camera permissions required
🔒 Safe for background operations

FaceAuthView

UI component for displaying the camera feed and face detection.

class FaceAuthView extends StatelessWidget {
  final FaceAuthController controller;
  // ... other properties
}

FaceAuthState

Enum representing different states of the authentication process.

enum FaceAuthState {
  cameraOpened,
  detectingFace,
  collectingSamples,
  matching,
  success,
  failed,
  timeout,
}

🤝 Contributing

We welcome contributions! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

Development Setup

Fork the repository
Create your feature branch (git checkout -b feature/AmazingFeature)
Commit your changes (git commit -m 'Add some AmazingFeature')
Push to the branch (git push origin feature/AmazingFeature)
Open a Pull Request

📄 License

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

👥 Contributors

Core Contributors

_{Mohamed Adel}
_{Lead Developer}
_{Flutter Developer}

_{Mahmoud Saad}
_{Core Developer}
_{Flutter Developer}

Team Expertise

Mohamed Adel - Lead Developer

Package architecture and core implementation
Face recognition integration and algorithms
Documentation and technical writing
Project management and coordination

Mahmoud Saad - Core Developer

Flutter development and UI implementation
Camera integration and state management
Testing and performance optimization
Cross-platform development

Contributing

We welcome contributions! Please see our Contributing Guidelines for details.

🙏 Acknowledgments

Google ML Kit for face detection capabilities
TensorFlow Lite for efficient face recognition
Flutter Team for the amazing framework

📞 Support

Issues: GitHub Issues
Discussions: GitHub Discussions
Repository: GitHub Repository

🔄 Changelog

See CHANGELOG.md for a list of changes and version history.

Made with ❤️ for the Flutter community

Transform your app's authentication with reliable face recognition that's easy to implement and customize!

📦 Repository

This package is available on pub.flutter-io.cn and the source code is hosted on GitHub.

📋 Requirements

Flutter 3.0+
Dart 2.17+
Android API level 21+
iOS 11.0+