HawkEye is a real-time threat monitoring system that detects dangerous human activity from CCTV footage. Built with Flask, YOLOv8, and Google Gemini Vision, it automatically analyzes human movement in video files and sends email and phone alerts when suspicious behavior is detected.
HawkEye focuses primarily on backend technology — combining real-time object detection, contextual AI analysis, and intelligent alerting — to build a meaningful safety solution. While a basic frontend dashboard is included for demonstration purposes, the core innovation lies in the detection and analysis pipeline.
- 📂 Uses YOLOv8 to detect humans and movements in CCTV-like footage (runs locally)
- 🎥 Live camera monitoring with real-time threat detection
- 🤖 Uses Google Gemini Vision to analyze screenshots for dangerous behavior (cloud API)
- ✉️ Sends detailed email alerts with images and structured threat logs
- 📞 Makes automated phone calls for critical threats (Twilio)
- 🔒 Supports privacy masking and multi-level threat detection
- 🧍♂️ Tracks people across multiple frames for consistency
- 📈 Provides advanced analytics and visual logs
- 📢 Supports external alarm system triggers
- 📁 Stores logs and reports for post-event investigation
- ⚙️ Backend-driven — minimal dependencies and frontend bloat
HawkEye is designed to run locally on systems such as:
- Schools
- Retail environments
- Residential security systems
- Live monitoring scenarios (using built-in or external cameras)
It currently processes local video files and live camera feeds, and requires internet for AI-based analysis, but future versions will support offline AI models for complete local operation.
- Select a video file (placed in
/static/videos/) - Optionally enable email alerts
- Click Start Monitoring
- The system processes the video file for threats
- Go to the Live Camera Monitoring section
- Select your camera from the dropdown
- Optionally enable email alerts and privacy blur
- Click Start Live Monitoring
- The system monitors your camera feed in real-time
The system:
- Detects human movement and extracts frames (YOLOv8, local)
- Applies AI for scene interpretation and threat assessment (Gemini Vision, cloud)
- Sends email and phone alerts for threats (if enabled)
- Logs activity with timestamps, labels, and screenshots
Logs are accessible at:
/logs: General activity logs/logs/action-required: Only critical or high-risk events
Below is a flowchart illustrating the end-to-end workflow of HawkEye, from video input to threat detection and alerting:
flowchart TD
A1["User uploads video via web interface"] --> B["Video saved to server"]
A2["User starts live camera monitoring"] --> B
B --> C["YOLOv8 (local) processes video frames"]
C -->|"Person detected?"| D{Yes}
C -->|"No"| E["Continue monitoring"]
D --> F["Save frame with detected person"]
F --> G["Send frame to Gemini (Google API)"]
G --> H["Gemini analyzes for threats (weapons, danger, etc.)"]
H -->|"Threat detected?"| I{Yes}
H -->|"No"| J["Log as safe, continue monitoring"]
I --> K["Send email alert"]
I --> L["Make phone call alert (Twilio)"]
I --> M["Log incident and analytics"]
J --> N["Log incident and analytics"]
K --> O["Analytics dashboard updated"]
L --> O
M --> O
N --> O
O["User views analytics dashboard"]
- Backend: Python (Flask)
- Frontend: HTML/CSS/JavaScript (lightweight dashboard)
- Detection: Computer vision with YOLOv8 (local)
- AI Analysis: Gemini Vision via Google Generative AI API (cloud)
- Tracking: Person ID consistency across frames
- Data Handling: Structured logs and visual evidence
- Connectivity: External alarm integration (configurable)
- Optimize detector for more efficient frame sampling
- Reduce false positives with custom ML models
- Integrate real-time CCTV stream monitoring
- Build mobile app for remote alerts and control
- Implement user accounts and role-based access control
- Support fully offline AI models for private deployments
HawkEye/
├── app.py # Flask routes and control logic
├── detector.py # Movement + frame capture + alert trigger
├── processor.py # Google Gemini Vision analysis
├── call_service.py # Phone call alert system (Twilio + Gemini)
├── emailer.py # Email alert system
├── templates/
│ ├── index.html # Demo UI for hackathon
│ └── analytics.html # Threat analytics dashboard
├── static/
│ ├── saves/ # Captured screenshots + logs
│ ├── videos/ # Uploaded video files
│ ├── style.css # Custom CSS styles
│ └── script.js # JavaScript for UI interactions
├── .env # Environment variables
git clone https://github.com/extremecoder-rgb/HawkEye.git
cd HawkEye
python -m venv venv
source venv/bin/activate # Windows: .\venv\Scripts\activatepip install -r requirements.txtGEMINI_API_KEY=your-gemini-api-key
SMTP_SERVER=smtp.gmail.com
SMTP_PORT=587
SMTP_USER=[email protected]
SMTP_PASSWORD=your-app-password
TWILIO_ACCOUNT_SID=your-twilio-sid
TWILIO_AUTH_TOKEN=your-twilio-auth-token
TWILIO_PHONE_NUMBER=your-twilio-phone
ALERT_PHONE_NUMBER=recipient-phonepython app.pyThen open:
http://localhost:8080
Before using live camera monitoring, you can test if your camera is accessible:
python test_live_camera.pyThis script will:
- Test camera access for multiple camera indices (0-4)
- Verify that the detector can work with live camera input
- Provide feedback on camera availability and functionality
Note: Make sure your camera is connected and not being used by other applications.
Apache License 2.0
- YOLOv8 by Ultralytics
- Gemini Vision by Google
- Twilio for phone call alerts