MemeFocus

MemeFocus is a productivity tool for students that gamifies focus by using real-time gaze tracking to detect when a user looks away from their screen. Unlike traditional site-blockers, MemeFocus uses "positive disruption," instantly playing user-selected "brainrot" clips, satisfying videos, or high-intensity memes as a humorous punishment. This breaks the procrastination loop and conditions the user to return to their work.

Presentation Summary

• Project name: MemeFocus
• High-level functionality: Calibrates gaze, detects distraction, shows a warning grace period, and triggers a meme overlay with media playback.
• How it is different/better: Instead of blocking content, it interrupts with humor and keeps all processing local for privacy.
• Motivation: Help students break short distraction loops without heavy-handed blocking.

Demo Overview (Recording Flow)

1. Open the app and add media files in the Settings window.
2. Enable Chaos Mode (optional) and start the session.
3. Complete calibration by looking at the center of the screen.
4. Look away to trigger the warning countdown.
5. Let punishment trigger and show the overlay + media playback.
6. Pause/resume and end the session from the Control Panel.

Team & Roles

• Krishna: Gaze Detection & CV Pipeline
• Aakash: Frontend (PyQt6) & Media Integration
• Jason: Session Logic, Timers, & Integration
• Toby: Data Visualization, Testing Infrastructure, & Whitelisting

Features

Implemented (Current Demo)

• Calibration (Center Baseline): Builds a focused gaze baseline for detection.
• Custom Media Library: Users upload local clips or audio for playback.
• Grace-Period Warning: Countdown overlay before punishment triggers.
• Punishment Overlay + Media Playback: Full-screen overlay and clips on distraction.
• Chaos Mode: Layers multiple clips at once for high-intensity feedback.
• Session Control: Start, pause/resume, and end from a floating control panel.
• Adjustable Sensitivity: Environment-variable tuning for thresholds and timers.

Planned / Stretch Goals

• Productivity Dashboard: Visual summary of focus time and distractions.
• Goal Setting: Work/break targets and progress tracking.

Technical Architecture

flowchart LR
   Main["main.py<br>Orchestrator"] --> Camera["OpenCV<br>Camera Feed"]
   Camera --> Tracker["Gaze Tracker<br>MediaPipe + OpenCV"]
   Tracker --> Session["Session Manager<br>grace period timer"]
   Session --> Overlay["Overlay Window<br>PyQt6"]
   Session --> Media["Media Controller<br>VLC or Qt Multimedia"]
   Settings["Settings Window<br>MediaLibrary JSON"] --> Media
   Control["Control Panel"] --> Session
   Control --> Overlay

Loading

Component	Role	Interactions	Tech
Gaze Tracker	Calibrates and classifies focused vs. distracted gaze	Emits status to Session Manager	Python, OpenCV, MediaPipe
Session Manager	Enforces grace period and punishment states	Triggers overlay/media events	Python threading
Overlay Window	Shows warnings and punishment overlay	Driven by Session Manager	PyQt6
Media Controller	Plays media (single or chaos mode)	Triggered by Session Manager	python-vlc, PyQt6 multimedia
Settings Window + MediaLibrary	Stores selected media and chaos settings	Feeds Media Controller	PyQt6, JSON
Control Panel	Pause/resume/end session	Updates Session Manager and overlay	PyQt6

Data Storage

• media_library.json stores media file paths and Chaos Mode settings locally.

Local Environment Setup

1. Ensure Python 3.9 is installed (Python 3.12+ is currently unsupported by MediaPipe).
2. Clone the repository:

git clone https://github.com/SP26-UIUC-CS222/Team-26.100.git
cd Team-26.100

3. Create a virtual environment and install dependencies:

python3.9 -m venv venv
source venv/bin/activate  # On Windows use `venv\Scripts\activate`
pip install -r requirements.txt

4. Run the app:

python main.py

Optional Environment Variables

• CAMERA_INDEX (default 0)
• GRACE_PERIOD (seconds, default 3.0)
• FOCUS_THRESHOLD (default 0.05)
• DISTRACTED_PERSISTENCE (frames, default 30)
• SHOW_OPENCV_WINDOW (1 to show OpenCV debug window)

Testing

Run tests with pytest (requirements already include pytest and pytest-cov):

source venv/bin/activate
pip install -r requirements.txt
pytest -q

What the tests check (high-level):

• test_camera.py — camera initialization and basic frame capture handling.
• test_overlay.py — overlay state transitions and basic UI show/hide semantics.
• test_session.py — session state machine, grace-period behavior, and pause/resume.
• test_settings.py — media library read/write and Settings persistence.
• test_media_library.py — media indexing and chaos mode selection logic.
• test_integration.py — a small smoke integration that simulates a session run (fast path).

If a test fails locally, run with pytest -q -k <test_name_substring> to focus on a single suite. For coverage, use pytest --cov=..

Development Notes & Lessons Learned

• Lesson 1 — Camera variability: low-quality webcams and lighting created noisy landmark estimates. We implemented adaptive smoothing and a per-session calibration baseline to stabilize the focus score.
• Lesson 2 — Media/Overlay Race: media startup could lag the overlay leading to a poor UX. We solved this by initializing the media controller on a worker thread and pre-buffering small clips when possible.

Privacy & Disclaimer

All webcam processing is local-only. Camera index and optimal distance will vary with hardware, and calibration is required per session.