Inspiration

As students, we experience firsthand how difficult it is to stay focused while studying or working for long periods of time. Many of us rely on music to help us concentrate, but choosing the right kind of music often comes down to trial and error. What helps one person focus might completely distract another.
At the same time, our generation is constantly exposed to short-form content and social media., which has significantly shortened our attention spans. We wanted to explore whether technology could help us better understand when we lose focus, and more importantly, why. This project was inspired by a simple question : what if we could measure focus instead of guessing it?

What it does

FocusFlow is an EEG-powered music player that adapts to your brain in real time. By connecting a Muse EEG headset, FocusFlow measures your live focus using a Theta/Beta Ratio (TBR) and classifies your mental state as Focused, Neutral, or Distracted while you work. When you play music, FocusFlow continuously tracks how your brain reacts to each track and automatically logs:

the song you listened to
your live EEG focus data over time
your average focus score for that song These sessions are stored in a database and used to train a recommendation system that learns what kind of music genuinely improves your focus, instead of relying on generic playlists or mood labels.

FocusFlow combines: 1) real brain data 2) machine learning 3) music playback (Apple Music integration) to create a personalized focus soundtrack built from your own performance, not your preferences.

How we built it

We built FocusFlow as a full end-to-end system that connects real-time EEG brain signals to music playback + machine learning recommendations.

Frontend (FocusFlow UI)

Built a sleek desktop-style interface using React + TailwindCSS Designed a minimalist “focus workspace” UI featuring:

live focus state indicator (Focused / Neutral / Distracted)
real-time EEG chart visualizations using Recharts
a Pomodoro-style timer
a floating Apple Music player + queue UI
EEG Data Pipeline (Muse Headset) Connected a Muse EEG headset to stream live brain signals Built a custom EEG hook (useEEG) that continuously computes a Theta/Beta Ratio (TBR) in real-time Used that value to classify the user’s focus state dynamically and update the UI instantly Music Playback + Apple Music Integration Integrated Apple Music using MusicKit JS Built custom playback controls (play/pause/skip/queue) Synced track changes + playback time to the UI so we could track song behavior live Machine Learning + Data Collection Every song session captures EEG-based responses while listening:
live TBR samples across the track
average TBR for the session
detected focus state
whether the user skipped or completed the song These are saved to MongoDB through a backend API so the model can learn the user’s focus patterns over time #Backend (FastAPI) Built a lightweight backend in FastAPI Added endpoints to:
store listening sessions + EEG feedback
check whether a track has available audio features
serve future recommendation results #Audio Feature Validation We used AcousticBrainz audio feature data to ensure we only learn from songs that have real feature vectors available (tempo, energy, etc.) This avoids training the model on tracks without reliable metadata

Challenges we ran into

Apple Music playback limitations (MusicKit browser restrictions) One of the biggest roadblocks was realizing that Apple Music playback through MusicKit is not universally supported across browsers. Even after getting MusicKit authentication working, we discovered that actual music playback is essentially restricted to Safari, which forced us to rethink our testing workflow and development setup. This limitation heavily impacted debugging speed and required us to build around platform constraints while still delivering a smooth user experience.

Using MongoDB for the first time This project was also our first time working with MongoDB, and it introduced a new set of challenges like:

designing a clean schema for EEG + listening-session data
figuring out the best way to store time-series samples (ex: TBR samples per song)
building reliable API routes that save data without breaking mid-session We had to learn quickly how to structure data in a way that would actually be useful for machine learning later. Building the ML pipeline with no regression background Our biggest technical learning curve was building the machine learning logic without having prior experience in regression or predictive modeling. We wanted the system to learn what type of music improves focus based on EEG responses, but turning that idea into something trainable was hard. We had to teach ourselves:
how to transform brain signals into numeric labels (focus score)
how to connect audio features to EEG-based outcomes
how to build a simple training loop that improves over time Even though we started with almost zero ML knowledge, we managed to design a model pipeline that learns directly from real user brain data.

Accomplishments that we're proud of

The biggest thing we’re proud of is building a real personalized recommendation system powered by EEG + machine learning, not just a random playlist shuffle. Instead of recommending songs based on general popularity or genre, our system learns what types of music increase your focus by analyzing your brain activity while you listen. We collect EEG-derived focus metrics (like Theta/Beta Ratio) during each song, store the results, and use them to train a model that understands your unique focus profile. From there, the recommendation engine can predict which songs are most likely to help you concentrate, and continuously improves over time as it gathers more data. Seeing the system adapt to the user and recommend “high-focus” music based on real brain signals was one of the most rewarding moments of the entire hackathon.

What we learned

First, we learned how hard it is to build a real product when you’re dealing with multiple systems at once (frontend UI, Apple Music playback, EEG streaming, backend storage, and ML training). Even when each part works individually, making everything communicate smoothly is a whole different challenge. We also learned a ton about data pipelines. It was our first time using MongoDB, and we had to understand how to store “real-time” EEG samples, track song sessions, and structure the data in a way that could actually be used for machine learning later. Finally, we learned how to build a machine learning model from scratch with almost no prior experience. We had to figure out how regression works, what features matter, and how to turn raw EEG signals into something meaningful. The coolest part was realizing that even with a small dataset, we could still build a system that learns patterns and improves recommendations over time. Overall, we came out of this hackathon with way stronger skills in full-stack integration, ML thinking, and problem-solving under pressure.

What's next for Focus Flow

Right now FocusFlow depends on an EEG headset, but the next big step is making it accessible to everyone by eliminating the hardware barrier. Our goal is to turn FocusFlow into a phone-only experience by using signals people already generate naturally, like:

Camera-based focus detection (eye movement, blink rate, head pose, posture)
Microphone-based context sensing (noise level, distraction detection)
Touch + usage behavior (typing speed, scrolling patterns, app switching)
Apple Health / smartwatch integration (heart rate + stress as a proxy for focus) With these inputs, FocusFlow could still learn your “focus profile” and recommend songs that improve concentration, without requiring an EEG headset at all. Eventually, FocusFlow becomes a plug-and-play focus assistant: open the app → start working → it adapts your music automatically.