A real-time web application that monitors user attention during video consumption using computer vision and eye-gaze tracking. Built with MediaPipe Face Landmark detection, this tool helps researchers and individuals understand distraction patterns while watching content.

The Distraction Detector uses advanced face landmark detection to track when users look away from the screen during video consumption. It provides real-time monitoring with a non-intrusive interface and comprehensive data logging for analysis.

• Real-time Face Tracking: Uses MediaPipe's Face Landmarker for accurate facial landmark detection
• Gaze Detection: Monitors eye movements to detect when users look away from the screen
• Non-intrusive Design: Webcam preview automatically hides after initial detection
• YouTube Integration: Embedded fullscreen YouTube video for testing scenarios
• Real-time Dashboard: Live monitoring interface for researchers/experimenters
• Data Export: CSV export functionality with customizable filenames
• WebSocket Communication: Real-time data streaming between components

┌─────────────────┐    WebSocket    ┌─────────────────┐
│   Main App      │◄──────────────►│   Dashboard     │
│  (index.html)   │                 │ (dashboard.html)│
│                 │                 │                 │
│ • Face tracking │                 │ • Event logging │
│ • Gaze detection│                 │ • Data export   │
│ • Timer logic   │                 │ • Live monitor  │
└─────────────────┘                 └─────────────────┘
         │
         ▼
┌────────────────���┐
│  WebSocket      │
│   Server        │
│ (server.js)     │
└─────────────────┘

• Node.js (v16 or higher)
• Modern web browser with WebRTC support
• Webcam access

1. Clone the repository

   git clone https://github.com/Samu01Tech/distraction-detector.git
   cd distraction-detector

2. Install dependencies

   npm install

3. Start the development server

   npm run dev

4. Access the application

   • Main application: http://localhost:5173
   • Dashboard: http://localhost:5173/dashboard

npm run build
npm run start

1. Initial Setup

   • Open the main application URL
   • Allow webcam access when prompted
   • Wait for face detection to initialize

2. During the Session

   • The webcam preview appears briefly for setup
   • Preview automatically hides after 3 seconds of successful detection
   • Watch the embedded YouTube video
   • A small toggle button appears in the bottom-left corner to show/hide webcam preview if needed

3. Gaze Detection

   • The system continuously monitors your face
   • Looking away triggers are based on specific eye movement thresholds:
     • eyeLookDownRight > 0.3
     • eyeLookInLeft > 0.4
     • eyeLookOutRight > 0.4

1. Monitoring

   • Open the dashboard in a separate browser window/tab
   • View real-time events and connection status
   • Monitor distraction events with duration and total time

2. Data Collection

   • Events are logged automatically with timestamps
   • View duration of each distraction event
   • Track cumulative distraction time

3. Data Export

   • Enter a custom filename in the dashboard
   • Click "Download CSV" to export all collected data
   • CSV includes: timestamp, event type, duration, total time, and details

Timestamp,Type,Event,Duration_ms,Total_Time_ms,Details
"10:30:45 AM","Application","Looking Away Detected","1250.50","3847.25","Looking away detected"
"10:30:47 AM","Application","Webcam Started","","","Camera stream initiated"

Edit the threshold values in src/main.ts:

const targetCategories = [
  { name: "eyeLookDownRight", threshold: 0.3 },
  { name: "eyeLookInLeft", threshold: 0.4 },
  { name: "eyeLookOutRight", threshold: 0.4 },
];

Change the embedded video by editing the iframe src in index.html:

<iframe 
  id="youtube-video"
  src="https://www.youtube.com/embed/YOUR_VIDEO_ID?autoplay=1&mute=1&controls=1"
  ...>
</iframe>

The WebSocket server runs on port 3000 by default. To change:

1. Update server/server.js:

   const port = 3000; // Change this value

2. Update client connections in src/main.ts and src/dashboard.ts:

   const ws = new WebSocket('ws://localhost:3000'); // Update port

distraction-detector/
├── src/
│   ├── main.ts          # Main application logic
│   ├── dashboard.ts     # Dashboard functionality
│   └── vite-env.d.ts   # TypeScript declarations
├── server/
│   ├── server.js        # WebSocket server
│   └── package.json     # Server dependencies
├── public/              # Static assets
├── index.html          # Main application page
├── dashboard.html      # Dashboard interface
├── package.json        # Project configuration
├── tsconfig.json       # TypeScript configuration
└── vite.config.ts      # Vite configuration

• npm run dev - Start development server with hot reload
• npm run build - Build for production
• npm run start - Start production server
• npm test - Run tests (placeholder)

• Frontend: TypeScript, Vite, HTML5, CSS3
• Computer Vision: MediaPipe Tasks Vision
• Real-time Communication: WebSockets
• Backend: Node.js, Express.js
• Build Tool: Vite
• Package Manager: npm

This tool is designed for research in:

• Human-Computer Interaction: Understanding attention patterns during digital media consumption
• Cognitive Load Studies: Measuring distraction in different content types
• UX Research: Evaluating interface designs and content engagement
• Educational Research: Analyzing attention during e-learning sessions
• Accessibility Studies: Understanding attention patterns in different user groups

• Distraction Frequency: Number of times user looks away
• Distraction Duration: Individual and cumulative time spent looking away
• Attention Patterns: Temporal analysis of engagement
• Session Analytics: Complete session data with timestamps

• Local Processing: All face detection happens locally in the browser
• No Data Storage: Facial data is not stored or transmitted
• Consent Required: Always obtain proper consent before data collection
• Anonymization: Consider anonymizing exported data for research
• GDPR Compliance: Ensure compliance with relevant data protection regulations

1. Webcam Not Working

   • Ensure browser has camera permissions
   • Check if camera is being used by another application
   • Try refreshing the page

2. Face Detection Not Loading

   • Check internet connection (MediaPipe models are loaded from CDN)
   • Verify browser compatibility
   • Check browser console for errors

3. WebSocket Connection Failed

   • Ensure server is running (npm run dev)
   • Check if port 3000 is available
   • Verify firewall settings

4. Dashboard Not Updating

   • Refresh dashboard page
   • Check WebSocket connection status
   • Verify both main app and dashboard are connected

• Recommended: Chrome 90+, Firefox 88+, Safari 14+
• Required Features: WebRTC, WebSockets, ES6 modules
• Not Supported: Internet Explorer

This project is licensed under the MIT License. See the LICENSE file for details.

1. Fork the repository
2. Create a feature branch (git checkout -b feature/new-feature)
3. Commit changes (git commit -am 'Add new feature')
4. Push to branch (git push origin feature/new-feature)
5. Create a Pull Request

Author: Samuele Mazzei
Email: samuele.mazzei@studenti.unitn.it
GitHub: @Samu01Tech

• MediaPipe for face landmark detection
• Vite for the build system
• WebSocket API for real-time communication

Note: This tool is intended for research and educational purposes. Always ensure proper consent and ethical guidelines are followed when collecting user data.