A high-performance, AI-powered video anomaly detection system designed for CCTV surveillance. Leverages YOLOv11 with OpenVINO optimization for real-time detection on standard CPUs, featuring a modern web interface and comprehensive alerting capabilities.
- Multi-Object Detection: Persons, Vehicles, and Weapons (Knives, Baseball Bats, Scissors)
- Robust Tracking: ByteTrack multi-object tracking with persistent IDs
- High Accuracy: 85-95% detection accuracy on test datasets
- Real-time Processing: 15-30 FPS on standard CPU hardware
- Crowd Detection: Configurable threshold for group gatherings
- Loitering Detection: Time-based stationary person identification
- Fast Movement: Panic/running situation detection
- Conflict Detection: Close-proximity group flagging
- Weapon Alerts: High-priority notifications for dangerous objects
- OpenVINO Acceleration: 2-3x speedup on Intel CPUs
- Async Processing: Non-blocking background task execution
- Progress Tracking: Real-time progress monitoring
- Auto-Optimization: Automatic model conversion on first run
- Responsive Design: Works on desktop, tablet, and mobile
- Dark Theme: Eye-friendly glassmorphism UI
- Real-time Updates: Live stream monitoring with SSE
- Intuitive Dashboard: Easy-to-use video upload and analysis
- Email Notifications: Automated SMTP alerts for anomalies
- Customizable Triggers: Configure which events trigger alerts
- Detailed Reports: HTML-formatted email with statistics
- SQLite Database: Store analysis results and video metadata
- Search Functionality: Find videos by name, date, or anomaly type
- Statistics Dashboard: View aggregate analytics across all videos
Comprehensive documentation is available in the /docs folder:
| Document | Description | Link |
|---|---|---|
| 📖 User Manual | Complete guide for end users | USER_MANUAL.md |
| 🔧 Configuration Guide | System configuration and tuning | CONFIGURATION_GUIDE.md |
| 🚀 Deployment Guide | Production deployment instructions | DEPLOYMENT_GUIDE.md |
| 🔌 API Documentation | REST API reference | API_DOCUMENTATION.md |
| 💻 Developer Guide | Contributing and development setup | DEVELOPER_GUIDE.md |
| 🧪 Testing Documentation | Test strategy and procedures | TESTING_DOCUMENTATION.md |
| 🛠️ Maintenance Guide | Operational maintenance procedures | MAINTENANCE_GUIDE.md |
| ✅ Project Closure | Project completion summary | PROJECT_CLOSURE.md |
- Python: 3.10 or higher
- Operating System: Ubuntu 22.04 / Windows 10+ / macOS 12+
- RAM: 8 GB minimum (16 GB recommended)
- Storage: 10 GB free space
-
Clone the repository
git clone https://github.com/yourusername/cctv-anomaly-detection.git cd cctv-anomaly-detection -
Create virtual environment (recommended)
python3 -m venv venv source venv/bin/activate # On Windows: venv\Scripts\activate
-
Install dependencies
pip install -r requirements.txt
Note: First installation may take 5-10 minutes to download all dependencies.
-
Start the application
python app.py
First run will automatically download YOLOv11 model (~50MB) and convert to OpenVINO format (~1-2 minutes).
-
Access the dashboard
Open your browser: http://localhost:8000 -
Upload and analyze a video
- Navigate to "Analyze" tab
- Upload video file (MP4, AVI, MOV, MKV)
- Set crowd threshold (default: 5)
- Click "Start Analysis"
- Monitor progress and view results
Step 1: Upload Video
- Drag & drop or click to select video file
- Supported formats: MP4, AVI, MOV, MKV
- Max file size: 500 MB (configurable)
Step 2: Configure Settings
- Crowd Threshold: Number of people to trigger alert (default: 5)
- Confidence: Detection confidence level 0.0-1.0 (default: 0.6)
Step 3: Start Analysis
- Click "Start Analysis"
- Monitor real-time progress
- View results when complete
Step 4: Review Results
- Anomaly statistics and breakdown
- Download annotated video
- View frame-by-frame analysis
Webcam:
- Go to "Live" tab
- Select "Webcam" from dropdown
- Click "Start Monitoring"
IP Camera (RTSP):
- Go to "Live" tab
- Select "RTSP Stream"
- Enter URL:
rtsp://username:password@ip:port/path - Click "Start Monitoring"
Example RTSP URLs:
Hikvision: rtsp://admin:password@192.168.1.100:554/Streaming/Channels/101
Dahua: rtsp://admin:password@192.168.1.101:554/cam/realmonitor?channel=1&subtype=0
Generic: rtsp://admin:password@192.168.1.102:554/stream1
Create a .env file in the project root:
# Model Configuration
MODEL_SIZE=s # n, s, m, l, x (s recommended)
DEVICE=cpu # cpu, cuda, mps
CONFIDENCE_THRESHOLD=0.5
# Anomaly Thresholds
CROWD_THRESHOLD=5
LOITER_THRESHOLD=10.0
# Server Configuration
HOST=0.0.0.0
PORT=8000
DEBUG=falseCreate email_config.json:
{
"smtp_server": "smtp.gmail.com",
"smtp_port": 587,
"sender_email": "security@company.com",
"sender_password": "your-app-password",
"receiver_emails": ["admin@example.com", "security@example.com"]
}Gmail Setup:
- Enable 2-Step Verification
- Generate App Password: Google Account Settings
- Use App Password in config (not your regular password)
For detailed configuration options, see CONFIGURATION_GUIDE.md.
cctv-anomaly-detection/
├── app.py # FastAPI application entry point
├── requirements.txt # Python dependencies
├── run.sh # Launch script
├── .env # Environment configuration
├── email_config.json # Email alert settings
│
├── src/ # Source code
│ ├── detection/ # Detection and tracking
│ │ ├── yolo_detector.py # YOLO detection logic
│ │ ├── visualization.py # Bounding box drawing
│ │ └── live_stream.py # Live stream processing
│ ├── storage/ # Data persistence
│ │ └── database.py # SQLite operations
│ └── alerts/ # Alert system
│ └── email_alerts.py # Email notifications
│
├── static/ # Static web assets
│ ├── style.css # UI styles (glassmorphism)
│ └── videos/ # Processed output videos
│
├── templates/ # HTML templates
│ ├── index.html # Main dashboard
│ └── live.html # Live stream page
│
├── docs/ # Documentation
│ ├── API_DOCUMENTATION.md
│ ├── USER_MANUAL.md
│ ├── CONFIGURATION_GUIDE.md
│ ├── DEPLOYMENT_GUIDE.md
│ ├── DEVELOPER_GUIDE.md
│ ├── TESTING_DOCUMENTATION.md
│ ├── MAINTENANCE_GUIDE.md
│ └── PROJECT_CLOSURE.md
│
├── tests/ # Test suite
│ ├── test_detection.py
│ ├── test_database.py
│ ├── test_api.py
│ └── test_email_alerts.py
│
└── yolo11*.pt # YOLO model files
The system provides a RESTful API for integration with other applications.
# Health check
GET /api/health
# Upload and analyze video
POST /api/analyze
- file: video file
- crowd_threshold: int
- confidence: float
# Get task status
GET /api/task/{task_id}
# Get all videos
GET /api/videos
# Get specific video
GET /api/videos/{video_id}
# Search videos
GET /api/search?query=...
# Get statistics
GET /api/statistics
# Live stream
GET /api/live-stream?source=...For complete API documentation, see API_DOCUMENTATION.md.
# Install test dependencies
pip install pytest pytest-asyncio pytest-cov httpx
# Run all tests
pytest tests/
# Run with coverage
pytest --cov=src tests/
# Run specific test
pytest tests/test_detection.pyCurrent test coverage: 85%
For detailed testing information, see TESTING_DOCUMENTATION.md.
Using Systemd (Linux):
# Create systemd service
sudo nano /etc/systemd/system/cctv-detection.service
# Enable and start
sudo systemctl enable cctv-detection
sudo systemctl start cctv-detectionUsing Docker:
# Build image
docker build -t cctv-detection .
# Run container
docker run -d -p 8000:8000 --name cctv cctv-detectionUsing Nginx Reverse Proxy:
server {
listen 80;
server_name cctv.company.com;
location / {
proxy_pass http://localhost:8000;
proxy_set_header Host $host;
}
}For complete deployment instructions, see DEPLOYMENT_GUIDE.md.
Issue: Application won't start
# Check Python version
python --version # Should be 3.10+
# Reinstall dependencies
pip install -r requirements.txt --force-reinstallIssue: Slow detection speed
# Verify OpenVINO is being used
# Check logs for "Using OpenVINO" message
# Try smaller model
MODEL_SIZE=n python app.pyIssue: Camera connection fails
# Test RTSP URL with VLC
vlc rtsp://admin:password@192.168.1.100:554/stream1
# Check network connectivity
ping 192.168.1.100For more troubleshooting, see USER_MANUAL.md.
| Metric | Value | Notes |
|---|---|---|
| Detection Speed | 15-30 FPS | On Intel i5 CPU with OpenVINO |
| Detection Accuracy | 85-95% | On standard test datasets |
| Memory Usage | <2 GB | During typical operation |
| Startup Time | 10-15 seconds | Includes model loading |
| API Response Time | <2 seconds | For most endpoints |
We welcome contributions! Please see our DEVELOPER_GUIDE.md for:
- Development environment setup
- Code style guidelines
- Testing requirements
- Pull request process
- Fork the repository
- Create feature branch:
git checkout -b feature/amazing-feature - Write tests for new functionality
- Ensure tests pass:
pytest tests/ - Format code:
black src/ tests/ - Commit changes:
git commit -m 'Add amazing feature' - Push to branch:
git push origin feature/amazing-feature - Open Pull Request
This project is licensed under the MIT License - see the LICENSE file for details.
- YOLOv11: AGPL-3.0 (Ultralytics)
- OpenVINO: Apache 2.0 (Intel)
- FastAPI: MIT
- Other dependencies: See individual package licenses
- Ultralytics for YOLOv11 model
- Intel for OpenVINO toolkit
- FastAPI team for excellent web framework
- ByteTrack for tracking algorithm
- All open-source contributors
- 📖 Documentation: Check
/docsfolder - 🐛 Bug Reports: GitHub Issues
- 💬 Discussions: GitHub Discussions
- 📧 Email: support@yourcompany.com
For enterprise support, custom development, or consulting:
- Email: enterprise@yourcompany.com
- Website: https://yourcompany.com
- User authentication and authorization
- Multi-camera simultaneous monitoring
- Zone-based detection rules
- Advanced analytics dashboard
- Mobile app (iOS/Android)
- PostgreSQL support
- VMS integration
- Custom model training UI
- SMS/Push notifications
See PROJECT_CLOSURE.md for complete roadmap.
Status: ✅ Production Ready
Version: 3.0.0
Last Updated: March 3, 2026
Maintained: Yes
Test Coverage: 85%
If you find this project useful, please consider giving it a star! ⭐
Built with ❤️ for smarter, safer surveillance