Screen Aware

A Flutter plugin that detects user presence in front of the device screen using face detection. Perfect for screen time tracking, auto-pause features, and attention monitoring.

Features

✅ Real-time face presence detection using device's front camera
✅ 100% on-device processing - no data sent to servers
✅ Privacy-first design - all processing happens locally
✅ Battery optimized - efficient frame processing and smart detection
✅ Configurable sensitivity - adjust detection responsiveness
✅ Cross-platform support - Android and iOS

Platform Implementation

Platform	Face Detection Technology	Min Version
Android	Google ML Kit Vision API	API 21+ (Android 5.0)
iOS	Apple Vision Framework	iOS 11.0+

Privacy & Security

• All face detection happens on-device
• No network requests are made
• No data is stored or transmitted
• No cloud processing involved
• Camera frames are processed in memory only

Installation

Add screen_aware to your pubspec.yaml:

dependencies:
  screen_aware: ^1.0.0

Android Setup

Step 1: Add camera permission to android/app/src/main/AndroidManifest.xml

Step 2: Set minSdkVersion to 21 in android/app/build.gradle

Step 3: Install permission_handler package for camera permission

iOS Setup

Step 1: Add camera usage description to ios/Runner/Info.plist

Step 2: Set minimum iOS version to 11.0 in ios/Podfile

Note: iOS handles permissions natively - no additional packages required!

Quick Start

1. Request camera permission
2. Initialize the plugin with optional sensitivity (0.0 to 1.0)
3. Listen to the face presence stream
4. Dispose when done

Check the example folder for a complete working demo.

Sensitivity Configuration

The sensitivity parameter controls how quickly the plugin reports face absence:

Sensitivity	Threshold	Best For
0.0 - 0.3 (Low)	1.0s	Screen time tracking, strict monitoring
0.4 - 0.6 (Medium)	2.0s	Video players, content apps
0.7 - 1.0 (High)	2.4-3.0s	Reading apps, tolerates distractions

Default: 0.7 (recommended for most use cases)

Use Cases

Screen Time Tracking

Track only the time when users are actively looking at the screen, not just when the app is open.

Video Auto-Pause

Automatically pause videos when the user looks away and resume when they return.

Attention Monitoring

Measure user engagement and focus during educational content or presentations.

Presence Detection

Detect when someone is in front of the device for security or automation purposes.

Performance

The plugin is optimized for battery efficiency:

• Frame Rate: 10-15 FPS
• Resolution: 640x480 pixels
• Processing: Hardware accelerated, on-device only
• Battery Impact: Minimal (comparable to video calling)

Troubleshooting

Android

Permission denied:
Request camera permission using permission_handler package before initializing.

ML Kit not working:
Ensure Google Play Services is installed and updated on the device.

iOS

Camera not starting:
Verify camera usage description is added to Info.plist.

Permission dialog not showing:
Call requestPermission() method explicitly.

General

Face not detected:

• Ensure adequate lighting
• Face the camera directly
• Check no other app is using the camera

High battery usage:
Call dispose() when the plugin is not needed.

Limitations

• Requires device with front camera
• Works best in good lighting conditions
• May not detect faces at extreme angles
• Android requires Google Play Services for ML Kit

Platform Notes

Android

• Requires permission_handler package
• Needs Google Play Services (ML Kit)
• Min SDK: API 21 (Android 5.0+)

iOS

• No additional packages required
• iOS 11.0+
• Best performance on iOS 15.0+

Example App

Run the example app to see the plugin in action:

cd example
flutter run

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch
3. Commit your changes
4. Push to the branch
5. Open a Pull Request

License

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

Author

Muhammad Saad Shafqat
GitHub: @saadshafqat

Support

⭐ If you find this plugin helpful, please give it a star on GitHub!

📝 For issues and feature requests, visit the issue tracker.

Changelog

See CHANGELOG.md for version history.

---

Made with ❤️ for the Flutter community