# siddhesh1108/smart-video-attention-controller architecture

> Architecture diagram of the GitHub repository siddhesh1108/smart-video-attention-controller, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/siddhesh1108/smart-video-attention-controller
- Repository: https://github.com/siddhesh1108/smart-video-attention-controller

## Overview

Smart Video Attention Controller combines webcam-based attention detection with local playback controls. The main workflow captures frames, estimates eye state and head pose, then calls the local Flask API to pause, resume, or rewind after distraction thresholds. Separately, the Chrome extension provides popup-driven controls for HTML5 video. The README describes the server as triggering the extension, but the sampled server code uses PyAutoGUI keyboard presses instead; the graph keeps these paths distinct. Source excerpts do not establish a connection from the Python workflow to the extension.

Main entry points: [`main.py`](https://github.com/siddhesh1108/smart-video-attention-controller/blob/main/main.py) (Attention loop), [`youtube_attention_extension/content.js`](https://github.com/siddhesh1108/smart-video-attention-controller/blob/main/youtube_attention_extension/content.js) (Video controller), [`detector.py`](https://github.com/siddhesh1108/smart-video-attention-controller/blob/main/detector.py) (Eye detector), [`server.py`](https://github.com/siddhesh1108/smart-video-attention-controller/blob/main/server.py) (Flask API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_vision["Attention sensing"]
  node_main["Attention loop<br/>[main.py]"]
  node_eye["Eye detector<br/>[detector.py]"]
  node_ear["Eye ratio<br/>[utils.py]"]
  node_pose["Head pose<br/>[head_pose.py]"]
  node_tracker["Attention tracker<br/>[attention.py]"]
end

subgraph group_backend["Python control"]
  node_api["Flask API<br/>[server.py]"]
  node_input["Keyboard control"]
end

subgraph group_extension["Browser extension"]
  node_popup["Extension popup<br/>[popup.js]"]
  node_manifest["Extension config<br/>[manifest.json]"]
  node_content["Video controller<br/>[content.js]"]
  node_background["Install listener<br/>[background.js]"]
end

node_viewer(("Viewer"))
node_webcam["Webcam"]
node_player["HTML5 player"]

node_viewer -->|"faces"| node_webcam
node_webcam -->|"frames"| node_main
node_main -->|"detects eyes"| node_eye
node_eye -->|"calculates ratio"| node_ear
node_main -->|"estimates pose"| node_pose
node_main -->|"requests controls"| node_api
node_api -->|"presses keys"| node_input
node_input -.->|"controls playback"| node_player
node_popup -->|"sends commands"| node_content
node_content -->|"controls video"| node_player
node_manifest -.->|"registers script"| node_content
node_background -.->|"installation event"| node_manifest

click node_main "https://github.com/siddhesh1108/smart-video-attention-controller/blob/main/main.py"
click node_eye "https://github.com/siddhesh1108/smart-video-attention-controller/blob/main/detector.py"
click node_ear "https://github.com/siddhesh1108/smart-video-attention-controller/blob/main/utils.py"
click node_pose "https://github.com/siddhesh1108/smart-video-attention-controller/blob/main/head_pose.py"
click node_tracker "https://github.com/siddhesh1108/smart-video-attention-controller/blob/main/attention.py"
click node_api "https://github.com/siddhesh1108/smart-video-attention-controller/blob/main/server.py"
click node_popup "https://github.com/siddhesh1108/smart-video-attention-controller/blob/main/youtube_attention_extension/popup.js"
click node_manifest "https://github.com/siddhesh1108/smart-video-attention-controller/blob/main/youtube_attention_extension/manifest.json"
click node_content "https://github.com/siddhesh1108/smart-video-attention-controller/blob/main/youtube_attention_extension/content.js"
click node_background "https://github.com/siddhesh1108/smart-video-attention-controller/blob/main/youtube_attention_extension/background.js"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_main,node_eye,node_ear,node_pose,node_tracker,node_viewer toneBlue
class node_api,node_input toneAmber
class node_popup,node_manifest,node_content,node_background toneMint
class node_webcam,node_player toneIndigo
```

## Components

### Attention sensing

- [Attention loop](https://github.com/siddhesh1108/smart-video-attention-controller/blob/main/main.py): `main.py`
- [Eye detector](https://github.com/siddhesh1108/smart-video-attention-controller/blob/main/detector.py): `detector.py`
- [Eye ratio](https://github.com/siddhesh1108/smart-video-attention-controller/blob/main/utils.py): `utils.py`
- [Head pose](https://github.com/siddhesh1108/smart-video-attention-controller/blob/main/head_pose.py): `head_pose.py`
- [Attention tracker](https://github.com/siddhesh1108/smart-video-attention-controller/blob/main/attention.py): `attention.py`

### Python control

- [Flask API](https://github.com/siddhesh1108/smart-video-attention-controller/blob/main/server.py): `server.py`
- **Keyboard control**

### Browser extension

- [Extension popup](https://github.com/siddhesh1108/smart-video-attention-controller/blob/main/youtube_attention_extension/popup.js): `youtube_attention_extension/popup.js`
- [Extension config](https://github.com/siddhesh1108/smart-video-attention-controller/blob/main/youtube_attention_extension/manifest.json): `youtube_attention_extension/manifest.json`
- [Video controller](https://github.com/siddhesh1108/smart-video-attention-controller/blob/main/youtube_attention_extension/content.js): `youtube_attention_extension/content.js`
- [Install listener](https://github.com/siddhesh1108/smart-video-attention-controller/blob/main/youtube_attention_extension/background.js): `youtube_attention_extension/background.js`

### Other components

- **Viewer**
- **Webcam**
- **HTML5 player**

## Connections

- Viewer → Webcam: faces (evidence: `README.md`)
- Webcam → Attention loop: frames (evidence: `main.py`)
- Attention loop → Eye detector: detects eyes (evidence: `main.py`)
- Eye detector → Eye ratio: calculates ratio (evidence: `detector.py`)
- Attention loop → Head pose: estimates pose (evidence: `main.py`)
- Attention loop → Flask API: requests controls (evidence: `main.py`)
- Flask API → Keyboard control: presses keys (evidence: `server.py`)
- Keyboard control → HTML5 player: controls playback
- Extension popup → Video controller: sends commands (evidence: `youtube_attention_extension/popup.js`)
- Video controller → HTML5 player: controls video (evidence: `youtube_attention_extension/content.js`)
- Extension config → Video controller: registers script
- Install listener → Extension config: installation event
