🚫📱 Anti-Doomscroll Trap

An AI-powered real-time focus monitor that detects phone use, tracks your attention, and sounds an alarm when you lose focus — all from your webcam.

---

📖 Description

Anti-Doomscroll Trap uses your webcam, state-of-the-art YOLOv8 object detection, and Haar cascade face/eye tracking to monitor whether you are focused on your work or distracted by your phone.

When you pick up your phone or look away too long, a focus health bar drains. If it stays low for more than 5 seconds (configurable), an audio alarm fires to snap you back to reality.

Everything runs locally on your PC — no cloud, no subscription, no data collection.

---

✨ Features

Feature	Description
📱 Phone Detection	YOLOv8 identifies a phone in your hand in real-time
📖 Book Detection	Detects reading and rewards it with health regeneration
👁️ Eye Tracking	Haar cascades verify your eyes are on the screen
💚 Focus Health Bar	Visual health bar that drains when you're distracted
🔔 Audio Alarm	Plays your chosen MP3 alarm when focus stays low
⚡ High FPS	Multi-threaded design keeps camera feed smooth (~30 FPS)
⚙️ Configurable	All thresholds editable via config/settings.yaml
📝 Logging	Full session logs written to logs/app.log

---

🗂 Folder Structure

anti-doomscroll-trap/
│
├── main.py                   ← Entry point — run this to start
│
├── src/                      ← Core application modules
│   ├── __init__.py
│   ├── detector.py           ← DetectionEngine (YOLO + face/eye)
│   ├── focus_state.py        ← FocusState machine (health, alarm logic)
│   ├── audio_manager.py      ← AudioManager (pygame alarm control)
│   ├── hud.py                ← HUD renderer (all on-screen overlays)
│   └── config_loader.py      ← YAML config loader with defaults
│
├── config/
│   └── settings.yaml         ← All user-configurable settings
│
├── assets/
│   ├── README.md             ← Instructions for adding alarm.mp3
│   └── alarm.mp3             ← Your alarm sound (add this yourself!)
│
├── logs/
│   └── app.log               ← Auto-generated session log
│
├── requirements.txt          ← Python dependencies
├── .gitignore
└── README.md                 ← You are here

---

🚀 Installation (Step-by-Step)

Prerequisites

• Python 3.9 or newer — Download here
• A working webcam
• An MP3 or WAV alarm sound file

---

Step 1 — Clone or Download the Project

Option A: Git clone (recommended)

git clone https://github.com/YOUR_USERNAME/anti-doomscroll-trap.git
cd anti-doomscroll-trap

Option B: Download ZIP

1. Click the green Code button on GitHub → Download ZIP
2. Extract the ZIP
3. Open a terminal and cd into the folder

---

Step 2 — Create a Virtual Environment

This keeps dependencies isolated from your system Python.

Windows:

python -m venv venv
venv\Scripts\activate

macOS / Linux:

python3 -m venv venv
source venv/bin/activate

You should see (venv) at the start of your terminal prompt.

---

Step 3 — Install Dependencies

pip install -r requirements.txt

⏳ This may take 2–5 minutes the first time (ultralytics + opencv are large).

---

Step 4 — Add Your Alarm Sound

1. Find a free alarm MP3 from freesound.org or mixkit.co
2. Rename it to alarm.mp3
3. Place it in the assets/ folder

---

Step 5 — Run the App

python main.py

The YOLOv8 model (yolov8n.pt) will auto-download (~6 MB) on the first run.

Optional: custom config or camera

python main.py --config config/settings.yaml
python main.py --camera 1   # use second webcam

Press q to quit at any time.

---

⚙️ Configuration

All settings are in config/settings.yaml. Open it with any text editor:

alarm_file:       "assets/alarm.mp3"   # path to your alarm sound
alarm_threshold:  50                    # health % that starts the timer
alarm_delay:      5.0                   # seconds before alarm fires
yolo_interval:    0.5                   # YOLO check frequency (seconds)
camera_index:     0                     # 0 = default webcam
model_path:       "yolov8n.pt"          # YOLO model size
log_level:        "INFO"                # DEBUG | INFO | WARNING | ERROR

---

🎮 How It Works

Camera Frame
    │
    ├─▶ [YOLO Thread]  ← runs every 0.5s in background
    │       └── Detects: phone, book
    │
    ├─▶ [Face Cascade] ← runs every frame (fast)
    │       └── Detects: face + eyes
    │
    └─▶ [Focus State Machine]
            │
            ├── Eyes found?        → Health +20, status = Focused
            ├── Phone detected?    → Health = 0,  status = DOOMSCROLLING
            ├── Book detected?     → Health +10,  status = Reading
            └── None?              → Health -5,   status = Looking away
                    │
                    └── Health < 50 for > 5s? → 🔔 ALARM!

---

🛠 Troubleshooting

Problem	Solution
[ERROR] Alarm file not found	Add alarm.mp3 to the assets/ folder
Camera won't open	Try python main.py --camera 1 (or 2, 3…)
Very slow / low FPS	Lower frame_width/frame_height in settings.yaml, or use yolov8n.pt
Phone not detected	Ensure good lighting; hold the phone clearly facing the camera
Eyes not detected	Make sure your face is well-lit and not at extreme angles
ModuleNotFoundError	Run pip install -r requirements.txt inside your virtual environment
Alarm won't stop	Press q to quit, or cover your eyes and look back at screen

---

🔮 Future Improvements

• Web Dashboard — React frontend showing session stats and charts
• Session History — SQLite database logging daily focus scores
• Multiple Faces — Track focus for several people simultaneously
• Screen Time Reports — PDF/CSV export of weekly focus analytics
• Posture Detection — Mediapipe-based bad-posture alert
• Custom Wake Words — Voice command to temporarily pause alarm
• Tray Icon — Run minimised in the system tray (Windows/Mac)
• Mobile App — React Native companion for phone-side notifications

---

📦 Dependencies

Package	Version	Purpose
opencv-python	≥ 4.8	Camera capture, Haar cascades, display
ultralytics	≥ 8.0	YOLOv8 object detection
pygame	≥ 2.5	Alarm audio playback
PyYAML	≥ 6.0	YAML config file parsing

---

📄 License

MIT License — free to use, modify, and distribute.

---

🙏 Credits

• Ultralytics YOLOv8 — Object detection backbone
• OpenCV — Computer vision framework
• pygame — Audio playback

---

Built with ❤️ to help you stay focused and off your phone.