{"id":31690314,"url":"https://github.com/zntb/mail_webcam_detection","last_synced_at":"2025-10-08T12:54:28.905Z","repository":{"id":306361728,"uuid":"1025350999","full_name":"zntb/mail_webcam_detection","owner":"zntb","description":"Python course project","archived":false,"fork":false,"pushed_at":"2025-07-25T04:32:00.000Z","size":2527,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-07-25T08:28:17.039Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/zntb.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-07-24T06:05:14.000Z","updated_at":"2025-07-25T04:32:04.000Z","dependencies_parsed_at":"2025-07-25T08:28:51.172Z","dependency_job_id":"bf3f5829-61af-437e-abbe-dadc20772872","html_url":"https://github.com/zntb/mail_webcam_detection","commit_stats":null,"previous_names":["zntb/mail_webcam_detection"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/zntb/mail_webcam_detection","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zntb%2Fmail_webcam_detection","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zntb%2Fmail_webcam_detection/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zntb%2Fmail_webcam_detection/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zntb%2Fmail_webcam_detection/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zntb","download_url":"https://codeload.github.com/zntb/mail_webcam_detection/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zntb%2Fmail_webcam_detection/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":278948022,"owners_count":26073748,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-08T02:00:06.501Z","response_time":56,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-10-08T12:54:21.351Z","updated_at":"2025-10-08T12:54:28.900Z","avatar_url":"https://github.com/zntb.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Professional Motion Detector\n\nA robust, professional-grade motion detection system with email alerts, comprehensive error handling, and configurable settings.\n\n## Features\n\n### ✨ Improvements from Original\n\n- **Professional Architecture**: Object-oriented design with proper separation of concerns\n- **Robust Error Handling**: Comprehensive exception handling for all operations\n- **Advanced Motion Detection**: Uses OpenCV's MOG2 background subtractor for better accuracy\n- **Configurable Settings**: YAML-based configuration with sensible defaults\n- **Smart Image Management**: Automatic cleanup to prevent disk space issues\n- **Professional Logging**: Detailed logging with configurable levels\n- **Thread Safety**: Proper synchronization for multi-threaded operations\n- **Email Service**: Robust email service with proper MIME handling\n- **Motion Cooldown**: Prevents spam alerts with configurable cooldown periods\n\n### 🔧 Core Features\n\n- Real-time motion detection using computer vision\n- Email alerts with image attachments\n- Configurable sensitivity and detection parameters\n- Automatic image cleanup and management\n- Professional logging and error handling\n- Easy configuration via YAML files\n\n## Installation\n\n1. **Clone or download the files**\n\n2. **Install dependencies**:\n\n   ```bash\n   pip install -r requirements.txt\n   ```\n\n3. **Set up environment variables**:\n\n   - Copy `.env.template` to `.env`\n   - Fill in your email credentials:\n\n   ```bash\n   cp .env.template .env\n   # Edit .env with your actual values\n   ```\n\n4. **Configure the system** (optional):\n   - Edit `config.yaml` to adjust detection parameters\n   - The system will create a default config if none exists\n\n## Configuration\n\n### Email Setup (Gmail)\n\n1. Enable 2-factor authentication on your Gmail account\n2. Generate an App Password:\n   - Go to Google Account Settings → Security → App passwords\n   - Generate a new app password for this application\n3. Use the app password (not your regular password) in `.env`\n\n### Detection Parameters\n\nEdit `config.yaml` to adjust:\n\n- **Sensitivity**: Lower values = more sensitive detection\n- **Min Contour Area**: Minimum size of motion to trigger alert\n- **Motion Cooldown**: Time between email alerts (prevents spam)\n\n## Usage\n\n### Basic Usage\n\n```bash\npython main.py\n```\n\n### Test Email Configuration\n\n```bash\npython email_service.py\n```\n\n### Controls\n\n- **'q' key**: Quit the application\n- **Ctrl+C**: Graceful shutdown\n\n## File Structure\n\n```text\nmotion-detector/\n├── main.py              # Main application\n├── email_service.py     # Email functionality\n├── config.py           # Configuration management\n├── config.yaml         # Configuration file\n├── .env.template       # Environment variables template\n├── .env               # Your actual environment variables (create this)\n├── requirements.txt   # Python dependencies\n├── images/           # Motion detection images (auto-created)\n└── motion_detector.log # Application logs\n```\n\n## Configuration Options\n\n### Camera Settings\n\n- `camera_index`: Camera device index (0 for default)\n- `frame_width/height`: Video resolution\n- `fps`: Frames per second\n\n### Motion Detection\n\n- `sensitivity`: MOG2 background subtractor sensitivity (20-100)\n- `motion_threshold`: Threshold for motion detection\n- `min_contour_area`: Minimum area to consider as motion\n- `motion_cooldown`: Seconds between email alerts\n\n### File Management\n\n- `images_dir`: Directory for storing motion images\n- `max_images`: Maximum images to keep (automatic cleanup)\n\n### Display Options\n\n- `show_video`: Show live video feed\n- `show_debug`: Show debug windows (motion mask)\n\n### Email Settings\n\n- `enabled`: Enable/disable email notifications\n\n### Logging\n\n- `level`: Logging level (DEBUG, INFO, WARNING, ERROR)\n\n## Troubleshooting\n\n### Common Issues\n\n#### Camera Access\n\n```bash\nError: Cannot access camera\n```\n\n**Solution**:\n\n- Check if camera is being used by another application\n- Try different camera index values (0, 1, 2...)\n- Ensure camera permissions are granted\n\n#### Email Authentication\n\n```bash\nError: SMTP authentication failed\n```\n\n**Solution**:\n\n- Use App Password instead of regular Gmail password\n- Enable 2-factor authentication first\n- Check SMTP server settings\n\n#### Permission Errors\n\n```bash\nError: Permission denied creating images directory\n```\n\n**Solution**:\n\n- Run with appropriate permissions\n- Check disk space availability\n- Ensure write permissions in application directory\n\n### Performance Optimization\n\n#### For Better Detection\n\n- Adjust `sensitivity` (lower = more sensitive)\n- Modify `min_contour_area` based on your environment\n- Enable debug mode to see motion mask\n\n#### For Resource Management\n\n- Reduce `max_images` if disk space is limited\n- Lower `frame_width` and `frame_height` for better performance\n- Adjust `fps` based on your needs\n\n## Advanced Usage\n\n### Running as Service (Linux)\n\nCreate a systemd service file:\n\n```ini\n[Unit]\nDescription=Motion Detector Service\nAfter=network.target\n\n[Service]\nType=simple\nUser=your_username\nWorkingDirectory=/path/to/motion-detector\nExecStart=/usr/bin/python3 main.py\nRestart=always\nRestartSec=10\n\n[Install]\nWantedBy=multi-user.target\n```\n\n### Custom Email Templates\n\nModify the `create_motion_alert_message` method in `email_service.py` to customize email content.\n\n### Integration with Home Automation\n\nThe system can be extended to integrate with:\n\n- Home Assistant\n- MQTT brokers\n- Webhook notifications\n- SMS alerts\n\n## Security Considerations\n\n1. **Environment Variables**: Never commit `.env` file to version control\n2. **Camera Access**: Ensure physical security of camera feed\n3. **Email Credentials**: Use app passwords, not main account passwords\n4. **Network Security**: Consider running on isolated network if needed\n\n## Development\n\n### Adding New Features\n\nThe modular design makes it easy to extend:\n\n```python\n# Example: Add webhook notifications\nclass WebhookService:\n    def send_motion_alert(self, image_path):\n        # Implementation here\n        pass\n\n# In main.py MotionDetector class:\nself.webhook_service = WebhookService()\n```\n\n### Testing\n\n```bash\n# Test email service\npython email_service.py\n\n# Test configuration loading\npython -c \"from config import Config; print(Config())\"\n```\n\n## Changelog\n\n### v2.0 (Current)\n\n- Complete rewrite with professional architecture\n- Added robust error handling and logging\n- Implemented configurable YAML settings\n- Added automatic image cleanup\n- Enhanced email service with proper MIME handling\n- Added motion detection cooldown\n- Improved thread safety\n\n### v1.0 (Original)\n\n- Basic motion detection\n- Simple email alerts\n- Minimal error handling\n\n## License\n\nThis project is provided as-is for educational and personal use.\n\n## Support\n\nFor issues and questions:\n\n1. Check the troubleshooting section\n2. Review log files for error details\n3. Ensure all dependencies are installed correctly\n4. Verify configuration settings match your environment\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzntb%2Fmail_webcam_detection","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzntb%2Fmail_webcam_detection","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzntb%2Fmail_webcam_detection/lists"}