Fokus 👀

Video control application using gaze direction detection. Fokus automatically pauses your QuickTime video when you look away from the screen.

📋 Prerequisites

• macOS (tested on Mac with Apple Silicon M1/M2/M3)
• Python 3.11 (important: Python 3.14 is not compatible)
• Homebrew (macOS package manager)
• QuickTime Player (pre-installed on macOS)
• Working webcam

🚀 Installation

1. Install Python 3.11

If you don't have Python 3.11, install it with Homebrew:

brew install python@3.11

Verify the installation:

python3.11 --version

2. Clone or download the project

cd ~/Desktop
mkdir Fokus
cd Fokus

Place the main_improved.py file in this folder.

3. Create a virtual environment

# Create the virtual environment with Python 3.11
python3.11 -m venv venv

# Activate the virtual environment
source venv/bin/activate

You should see (venv) appear at the beginning of your command line.

4. Install dependencies

pip install mediapipe opencv-python

🎬 Usage

Starting the App

1. Open QuickTime Player and load a video (Cmd+O)
2. Pause the video
3. Activate the virtual environment (if not already done):

   cd ~/Desktop/Fokus
   source venv/bin/activate

4. Launch Fokus:

   python main_improved.py

How It Works

• 🟢 Look at the screen → Video plays automatically
• 🔴 Turn your head (>20°) → Video pauses
• ⎋ Press Escape → Quit the application

Control Window

A "Fokus - Head Control" window opens and displays:

• Your face captured by the webcam
• The rotation angle of your head in degrees
• Current status (FOCUS ✓ or DETOURNE ✗)

⚙️ Configuration

Adjust Sensitivity

In the main_improved.py file, lines 93 and 101, you can modify the detection threshold:

if abs(yaw) < 20:  # Change 20 to another value

• Smaller value (e.g., 15) → More sensitive, detects small movements
• Larger value (e.g., 30) → Less sensitive, requires turning your head more

Change Video Player

The code is configured for QuickTime Player. To use another player (VLC, IINA, etc.), modify the AppleScript commands in the control_quicktime() function.

🐛 Troubleshooting

Camera doesn't activate

• Check camera permissions in System Preferences → Privacy & Security
• Make sure no other application is using the camera

QuickTime commands don't work

• QuickTime Player must be open with a video loaded
• Verify that QuickTime has the necessary permissions
• Test manually:

  osascript -e 'tell application "QuickTime Player" to play document 1'

Error "module 'mediapipe' has no attribute 'solutions'"

• You're probably using Python 3.14 which is not compatible
• Delete the venv and recreate it with Python 3.11:

  deactivate
  rm -rf venv
  python3.11 -m venv venv
  source venv/bin/activate
  pip install mediapipe opencv-python

Detection is unstable

• Make sure you have good lighting
• Position yourself facing the camera
• Adjust the sensitivity threshold (see Configuration)

📝 Technical Notes

• Detection library: MediaPipe Face Mesh
• Detection method: Yaw angle calculation (left/right rotation) based on facial landmarks
• Video control: AppleScript to communicate with QuickTime Player
• Cooldown: 30 frames between each command to avoid spam

🔄 Updates

To update dependencies:

source venv/bin/activate
pip install --upgrade mediapipe opencv-python

📄 License

Personal project - Free to use

🤝 Contributing

Feel free to suggest improvements or report bugs!

---

Developed with ❤️ to stay focused 🎯