🤖 Botzface - Real-Time Face Tracking Android App

An interactive Android application featuring a bot character whose eyes follow your face in real-time using on-device ML Kit face detection.

Features • Architecture • Setup • Usage • Technologies

📱 Overview

Botzface is a fun and interactive Android application that demonstrates real-time face tracking using Google's ML Kit. The app displays an animated bot character that tracks human faces through the device's front camera, with eyes that follow your position and expressions that respond to your facial features.

Key Highlights

🎯 Real-time face tracking with smooth animations
👁️ Eye movement follows detected face position
😊 Expression recognition (smiling, eyes open/closed)
📱 On-device processing - no internet required
⚡ Optimized performance for smooth experience
🔒 Privacy-focused - no data storage or transmission

✨ Features

Core Functionality

Live Camera Preview: Uses front-facing camera with CameraX
Face Detection: Powered by Google ML Kit for accurate tracking
Animated Bot Character: Custom-drawn bot face with reactive expressions
Eye Tracking: Bot eyes follow the detected face position
Facial Expression Response: Reacts to smiling and eye states
Multiple Face Support: Detects and tracks multiple faces (focuses on primary face)
Bounding Box Overlay: Visual feedback showing detected face regions

Technical Features

MVVM Architecture: Clean separation of concerns
Dependency Injection: Using Hilt for scalable code
Lifecycle-Aware: Proper resource management
Permission Handling: Modern runtime permission requests
Smooth Animations: ValueAnimator with interpolators

🏗️ Architecture

The app follows Clean Architecture principles with MVVM pattern:

┌─────────────────────────────────────────┐
│ Presentation Layer │
│ (Activities, Fragments, ViewModels) │
│ CameraFragment.kt │
│ FaceDetectionViewModel.kt │
│ PetbotFaceView.kt (Custom View) │
└─────────────┬───────────────────────────┘
│
┌─────────────▼───────────────────────────┐
│ Domain Layer │
│ (Use Cases, Models) │
│ DetectFacesUseCase.kt │
│ DetectedFace.kt (Model) │
└─────────────┬───────────────────────────┘
│
┌─────────────▼───────────────────────────┐
│ Data Layer │
│ (Repository, Data Sources) │
│ FaceDetectionRepository.kt │
│ FaceData.kt (Model) │
│ ML Kit Face Detection API │
└─────────────────────────────────────────┘

Project Structure

app/
├── data/
│ ├── model/
│ │ └── FaceData.kt
│ └── repository/
│ └── FaceDetectionRepository.kt
├── domain/
│ ├── model/
│ │ └── DetectedFace.kt
│ └── usecase/
│ └── DetectFacesUseCase.kt
├── presentation/
│ ├── ui/
│ │ ├── CameraFragment.kt
│ │ └── custom/
│ │ ├── PetbotFaceView.kt
│ │ └── FaceOverlayView.kt
│ ├── viewmodel/
│ │ └── FaceDetectionViewModel.kt
│ └── util/
│ └── PermissionUtils.kt
├── di/
│ └── AppModule.kt
└── PetbotApplication.kt

🚀 Setup

Prerequisites

Android Studio: Ladybug (2024.2.2) or higher
Minimum SDK: API 24 (Android 7.0 Nougat)
Target SDK: API 35 (Android 15)
Kotlin: 2.0.21
Gradle: 8.9

Installation

Clone the repository

git clone https://github.com/Ravindu56/botzface.git
cd botzface

Open in Android Studio

Open Android Studio
Select "Open an Existing Project"
Navigate to the cloned directory

Sync Gradle

Wait for Gradle sync to complete
Download dependencies (first sync may take a few minutes)

Build the project

./gradlew build

Run on device/emulator

Connect an Android device with USB debugging enabled, or
Start an Android emulator (API 24+)
Click Run ▶️ in Android Studio

📖 Usage

First Launch

Grant Camera Permission: The app will request camera access on first launch
Position Your Face: Place your face in front of the camera
Watch the Bot: The bot's eyes will follow your face position
Try Expressions: Smile or close your eyes to see the bot react

Controls

Eyes: Follow your face position across the screen
Smile: Bot smiles when you smile
Eyes Closed: Bot closes eyes when you close yours

🛠️ Technologies

Core Libraries

Technology	Version	Purpose
Kotlin	2.0.21	Primary language
CameraX	1.3.1	Camera preview and image analysis
ML Kit Face Detection	16.1.7	On-device face detection
Hilt	2.50	Dependency injection
Coroutines	1.8.1	Asynchronous programming
LiveData	2.8.6	Reactive data observation
ViewBinding	-	Type-safe view access

Android Jetpack Components

ViewModel: UI state management
LiveData: Observable data holder
Lifecycle: Lifecycle-aware components
Activity/Fragment KTX: Kotlin extensions

ML & Vision

Google ML Kit: Face detection and landmark tracking
Face Classification: Smile probability, eye open probability
Face Tracking: Persistent tracking across frames

📐 Key Components

1. Face Detection Pipeline

CameraX Frame → YUV to Bitmap → ML Kit Detection → Domain Model Mapping → ViewModel → UI Update

2. Custom Views

PetbotFaceView: Draws animated bot face with moving eyes
FaceOverlayView: Renders bounding boxes around detected faces

3. Animation System

ValueAnimator: Smooth eye movement interpolation
DecelerateInterpolator: Natural-feeling animations
Target-based tracking: Eyes gradually move to target position

⚙️ Configuration

Face Detection Settings

Located in FaceDetectionRepository.kt:

val options = FaceDetectorOptions.Builder()
.setPerformanceMode(FaceDetectorOptions.PERFORMANCE_MODE_FAST)
.setLandmarkMode(FaceDetectorOptions.LANDMARK_MODE_ALL)
.setClassificationMode(FaceDetectorOptions.CLASSIFICATION_MODE_ALL)
.setMinFaceSize(0.15f) // Adjust minimum face size (0.1f - 1.0f)
.enableTracking() // Enable persistent tracking
.build()

Performance Tuning

Adjust frame processing rate in CameraFragment.kt:

private val analysisInterval = 100L // Process every 100ms (10 FPS)

Lower values = smoother tracking but higher CPU usage

🔧 Troubleshooting

Camera Not Starting

Check permissions: Ensure camera permission is granted in Settings
Restart app: Force stop and relaunch the app
Check device: Verify device has front-facing camera

Face Not Detected

Lighting: Ensure adequate lighting conditions
Distance: Position face 30-100cm from camera
Angle: Face camera directly (avoid extreme angles)

Performance Issues

Close background apps: Free up system resources
Reduce frame rate: Increase analysisInterval value
Check device specs: App optimized for Snapdragon 835 or better

🎯 Future Enhancements

Face Recognition - Identify and remember specific users
Photo Capture - Save screenshots of interactions
Multiple Bot Characters - Choose different bot designs
Expression Filters - Add AR effects and filters
Voice Interaction - Add speech recognition
Cloud Sync - Optional cloud backup of preferences
Settings UI - Customize sensitivity, appearance
Multi-language Support - Localization

📱 Device Requirements

Tested Devices

Sony Xperia XZ1 Compact (Primary)
Android Emulator (API 24-35)

🤝 Contributing

Contributions are welcome! Please follow these steps:

Fork the repository
Create a 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

Coding Standards

Follow Kotlin Coding Conventions
Add KDoc comments for public APIs
Write unit tests for business logic
Ensure code passes Lint checks

📄 License

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

MIT License

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

👨‍💻 Author

Ravindu

GitHub: @Ravindu56
Project Link: https://github.com/Ravindu56/botzface

🙏 Acknowledgments

Google ML Kit - For providing excellent on-device ML APIs
Android Team - For CameraX and Jetpack libraries
Kotlin Team - For the amazing programming language
Stack Overflow Community - For countless solutions

📊 Stats

Made with ❤️ and Kotlin

If you found this project helpful, please consider giving it a ⭐!

Name		Name	Last commit message	Last commit date
.idea		.idea
.kotlin/errors		.kotlin/errors
app		app
gradle		gradle
.gitignore		.gitignore
README.md		README.md
build.gradle.kts		build.gradle.kts
gradle.properties		gradle.properties
gradlew		gradlew
gradlew.bat		gradlew.bat
settings.gradle.kts		settings.gradle.kts

Latest commit

History

Folders and files

Repository files navigation