Music that moves with your heartbeat
Argo Player reads your heart rate and HRV from a wearable (Garmin, Apple Watch, Whoop, Oura) and builds music sequences that guide you toward flow state. Not generative ambient noise. Your actual music, from Apple Music, ordered by tempo progression curves grounded in psychoacoustic research.
The core idea: a 4-6 song sequence with 10-15 BPM steps between tracks can shift your physiological state in about 15 minutes. Stressed at 95 BPM resting heart rate? The algorithm walks you down: 85, 75, 68 BPM. Your heart rate follows the music. Peer-reviewed, not hand-wavy.
Explore Mode (free, no wearable needed)
- Analyze any song's BPM
- Discover music through tempo, not just genre
- Learn why certain songs make you feel a certain way
Optimize Mode (paid, wearable required)
- Real-time HR/HRV monitoring during sessions
- Automatic state detection (stressed, calm, energized, flow, fatigued, resting)
- Playlist generation with gradual tempo progression toward your target state
- Post-session feedback that improves personalization over time
The algorithm draws from:
- Flow state theory (Csikszentmihalyi) - optimal engagement happens in a specific physiological window
- Tempo-emotion coupling (Nature Scientific Reports, 2025) - music tempo modulates emotional arousal
- Heart rate synchronization - rhythmic auditory stimulation influences HR and respiration
- HRV as state proxy - high HRV correlates with parasympathetic dominance (relaxed, flow-ready); low HRV signals stress or fatigue
Key constraints the algorithm respects:
- Gradual tempo steps only (10-15 BPM per song). Sudden jumps break immersion.
- Flow zone sits at 60-80 BPM, near resting heart rate for most people.
- Full state transitions take 4-6 songs, roughly 15-20 minutes.
- Individual variation is real. The system learns what works for you.
| Layer | Technology |
|---|---|
| Framework | Flutter 3.x / Dart 3.x |
| State management | Riverpod 2.x |
| UI | Material Design 3 + custom Bauhaus theme |
| Music | Apple Music (MusicKit) + GetSongBPM API |
| Biometrics | Terra SDK (Garmin, Apple Watch, Google Fit, Oura, Whoop) |
| Local storage | Drift (SQL), Hive (cache), flutter_secure_storage |
| Platform | iOS (MVP) |
Bauhaus-inspired. Geometric shapes represent your biometric state: circle when calm, square in flow, triangle when energized. The shapes pulse with your heart rate and morph smoothly as your state changes. Dark theme, minimal chrome, no unnecessary UI between you and the music.
First time:
- Connect Apple Music
- Connect wearable via Terra SDK
- Sit still for 30-60 seconds to measure resting heart rate
- Quick music taste quiz
- Guided 5-minute demo session
Every time after:
- Open app. State detected automatically.
- Tap "Start Session"
- Music plays, shape pulses, tempo shifts gradually
- Target state reached. Rate the session.
This repo is currently documentation-only (planning phase complete, implementation in progress):
| Document | What's in it |
|---|---|
| biometric_music_research.md | Flow state theory, psychoacoustics, tempo progression algorithm design, competitive analysis |
| system_architecture.md | Layered architecture, data models, API integrations, code samples |
| ux_design.md | Bauhaus + Material 3 design system, screen mockups, component library, accessibility |
| product_requirements.md | MVP scope, user stories, success metrics, go-to-market |
| DECISIONS.md | All 28 architectural and product decisions with rationale |
| ROADMAP.md | 50 GitHub issues across 5 phases, estimated at ~500 hours |
| EXPLORE_VS_OPTIMIZE.md | Side-by-side comparison of the two product modes |
SVG diagrams in diagrams/: state machine, tempo progression curves, architecture overview, screen mockups, onboarding flow, session flow.
| Product | What it does | What Argo does differently |
|---|---|---|
| Endel | Generative soundscapes from biometric input | Uses real music you already know and love |
| Brain.fm | AI-composed focus music | Uses your actual library, not generated audio |
| Calm/Headspace | Guided meditation | Music-first, teaches tempo awareness |
| SongBPM/Tunebat | BPM lookup databases | Mobile app with education, discovery, and state optimization |
- Explore Mode: Free forever. BPM analysis, tempo-based discovery.
- Optimize Mode: $8/month or $70/year. Requires Apple Music subscription + wearable.
- Beta: Free for early testers.
git clone https://github.com/amilovidov/argo-player.git
cd argo-player
flutter pub get
flutter run- Apple Developer Account - MusicKit requires iOS
- Terra SDK - Sign up at https://tryterra.co for biometric integration
- Flutter 3.x SDK + Xcode
Phase 0 (research, architecture, UX design) is complete. Implementation is underway.
MIT License. See LICENSE.
Alexander Milovidov - https://linkedin.com/in/milovidov
Built on research from Mihaly Csikszentmihalyi (flow theory), Nature Scientific Reports (tempo-emotion research), and the open-source Flutter, Terra SDK, and MusicKit ecosystems.