FocusBuddy

UI displaying biometric data and current music being played based on user's mood

Inspiration

A common problem we students have all faced is tiresome study sessions that often lead to stress and mental fatigue. Long hours of staring at the screens, tight deadlines, and pressure to perform can slowly drain energy without students even realizing it. We don’t notice fatigue until our productivity collapses. Most productivity tools require self-reporting or fixed timers, which require the user to assess their own state of well-being. This results in students pushing themselves way too far, ignoring early signs of fatigue and stress until their productivity drops. This does not truly reflect how a person is actually feeling in the moment, as it is not always accurate.

What it does

Many physiological signals, such as blink rate and heart rate, are commonly used as indicators of focus, stress, and fatigue. We created FocusBuddy, a system that automatically monitors a student’s wellness through a laptop camera by tracking heart rate and blink rate to assess their focus level and mood. Based on the detected emotional state, FocusBuddy outputs music tailored to the user’s needs. For example, if a student is feeling low, FocusBuddy will play upbeat music to help motivate them.

Additionally, the system includes an AI-powered chatbot that alerts users to take a break whenever their heart rate or blink rate exceeds normal thresholds for extended periods of time. This feature helps notify students when their fatigue levels are increasing, encouraging timely breaks and preventing overexertion. Overall, FocusBuddy aims to support students worldwide by promoting a healthier learning environment, helping them better understand their limits, improving well-being, and boosting productivity through personalized music.

How we built it

FocusBuddy continuously monitors the user through a webcam. We use MediaPipe Face Mesh to track eye landmarks and calculate blink rate over time. Heart rate is estimated using the yarPPG library, which applies remote photoplethysmography by detecting subtle changes in skin color caused by blood flow. These physiological signals are processed in real time and fed into a simple state-based logic system. When blink rate and heart rate indicate stress or loss of focus, FocusBuddy dynamically adapts the music selection. If both signals remain in a stressed or fatigued state beyond a defined threshold, the system displays a break warning.

Music recommendations are generated using the Last.fm API to retrieve songs based on mood tags. Since Last.fm does not provide audio files, the iTunes Search API is used to obtain playable music. Audio playback is managed using the VLC Python module. To prevent music playback from blocking the application, multithreading is implemented using Python’s threading library, allowing the VLC player and focus monitoring to run concurrently.

Challenges we ran into

One of the main challenges was ensuring real-time responsiveness while simultaneously processing video for blink detection, estimating heart rate, and playing audio. To address this, we implemented multithreading to prevent these tasks from blocking the main application. Another significant challenge was sourcing a reliable and accessible music API. Many popular platforms, such as Spotify and Apple Music, require paid subscriptions or impose strict playback and licensing restrictions, making them unsuitable for our project. After further research, we selected Last.fm, a free and public music discovery API that provides access to a large music database. To overcome the lack of direct audio playback support, we used the iTunes Search API to retrieve free 30-second preview clips, allowing us to bypass cost and licensing barriers for this hackathon.

Accomplishments that we're proud of

Designed and implemented a real-time, state-based logic system that infers student focus and fatigue using physiological signals (blink rate and heart rate), eliminating reliance on self-reporting or timer-based heuristics
Achieved concurrent video processing, physiological signal estimation, and audio playback through Python multithreading to maintain low-latency system performance
Integrated multiple computer vision, signal processing, and media APIs (MediaPipe Face Mesh, yarPPG, Last.fm, iTunes Search API, and VLC) into a unified end-to-end pipeline
Developed a scalable software solution addressing a real-world problem by improving student productivity and supporting wellness through adaptive feedback mechanisms

What we learned

Throughout this project, we learned how physiological signals such as blink rate and heart rate can serve as indicators of focus, stress, and fatigue. We gained hands-on experience with facial landmark detection and remote heart rate estimation using video input. Additionally, we developed practical skills in API integration, real-time data processing, and Python multithreading to maintain application responsiveness while concurrently handling camera input and audio playback.

What's next for FocusBuddy?

Moving Forward: Features to Implement

Music Platform Integration (Spotify / Apple Music)

Replace iTunes preview clips with full-length tracks from the user’s personal music library
Generate auto-updating playlists that adapt in real time based on biometric feedback

Fatigue Scoring System

Compute a composite fatigue score using heart rate variability, blink rate, and session duration
Example output: “You’ve been working for 2.5 hours — Fatigue Score: 78%”

Smart Break Recommendations (Powered by Gemini)

Perform real-time analysis of current biometric state combined with recent activity history
Suggest breaks at optimal times to reduce cognitive overload and prevent burnout

Mood & Productivity Insights

Persist biometric data in a SQLite database for longitudinal analysis
Use Google Gemini to generate personalized summaries and actionable insights, such as:
- “Your heart rate consistently peaks around 3 PM — consider scheduling breaks during this time.”
- “You exhibit lower blink rates when listening to instrumental music, indicating improved focus.”
Identify correlations between music genres and biometric stability

Biometric Journal with AI Analysis

Allow users to log the task they are working on (e.g., coding, writing, studying)
Use Gemini to correlate task types with biometric responses, such as:
- “Coding tasks increase your heart rate by an average of 15% compared to writing tasks.”

Ambient Lighting Integration

Control smart lighting systems (e.g., Philips Hue) to match biometric state
Apply cool lighting when energized and warm lighting during stress or fatigue

Biometric Challenges & Gamification

Introduce focus-based challenges, such as maintaining deep focus for a set duration
Enable anonymized social comparison and friendly competition to encourage sustained productivity