Turn your typing rhythm into personalized focus music
An AI-powered focus music generator that creates adaptive, real-time ambient soundscapes based on your typing rhythm and mouse movements. Built for developers, writers, and knowledge workers who want dynamic background music that responds to their work patterns.
- 🎹 Real-time Audio Synthesis - Pure Web Audio API synthesis (no pre-recorded samples)
- 🎯 Rhythm Detection - Tracks keyboard and mouse activity to calculate BPM and tempo
- 🧠 AI Song Recommendations - Intelligent insights via Gemini API based on your focus patterns
- 🎨 Live Waveform Visualization - 60fps Canvas animation synced with your typing
- 🎼 Piano Song Moods - A Thousand Years (Christina Perri), Kiss The Rain (Yiruma), River Flows In You (Yiruma), Gurenge (LiSA)
- 🎹 MIDI-Based Melodies - Real piano pieces that adapt to your typing rhythm
- 🎵 Adaptive Instruments - Piano, Flute, Xylophone, and Kalimba that respond to your rhythm
- 🔐 Secure Authentication - OAuth2 PKCE flow with Auth0
- 💾 Session History - Automatic tracking with 90-day data retention
- ♿ Accessibility Mode - WCAG 2.1 AA compliant with sensory-friendly options
- 📊 Session Statistics - Real-time metrics: duration, keystrokes, clicks, mouse moves, scrolls
- Node.js 18+ and npm (for manual development)
- Docker + Docker Compose (recommended for full development environment)
- MongoDB Atlas account (sign up free)
- Auth0 account (sign up free)
- Gemini API key (get key)
# Clone the repository
git clone https://github.com/juxtaduo/pulseplay.git
cd pulseplay
# Start development environment
make up-dev
# Or with MongoDB Atlas
make up-atlas# Clone the repository
git clone https://github.com/juxtaduo/pulseplay.git
cd pulseplay
# Install dependencies
npm install
# Install backend dependencies
cd backend && npm install && cd ..Create a .env file in the project root:
# Frontend Environment Variables
VITE_AUTH0_DOMAIN=your-domain.auth0.com
VITE_AUTH0_CLIENT_ID=your_client_id
VITE_AUTH0_AUDIENCE=https://api.pulseplay.ai
VITE_API_URL=http://localhost:3001Create a backend/.env file:
# MongoDB Configuration
MONGODB_URI=mongodb+srv://username:[email protected]/pulseplay
# Auth0 Configuration
AUTH0_DOMAIN=your-domain.auth0.com
AUTH0_CLIENT_ID=your_client_id
AUTH0_CLIENT_SECRET=your_client_secret
AUTH0_AUDIENCE=https://api.pulseplay.ai
AUTH0_ISSUER_BASE_URL=https://your-domain.auth0.com
# Gemini API
GEMINI_API_KEY=your_gemini_api_key
# Server Configuration
PORT=3001
NODE_ENV=development
FRONTEND_URL=http://localhost:5173# Start all services
make up-dev
# View logs
make logs
# Stop services
make down# Terminal 1: Start backend server
cd backend
npm run dev
# Terminal 2: Start frontend (in new terminal)
npm run devVisit http://localhost:5173 (manual) or http://localhost:3000 (Docker) in your browser.
- Quick Start Guide - Get up and running
- Background Audio Guide - How audio works when tab is inactive
- Contributing - How to contribute to the project
- Vercel Deployment Guide - Complete Vercel serverless deployment
- Vercel Quick Reference - Quick Vercel commands and setup
- Vercel vs Others - Compare Vercel with other deployment methods
- Docker README - Complete Docker deployment guide
- Docker Quick Reference - Quick Docker commands
- Docker Files Summary - Docker file inventory
- MongoDB Atlas Setup - Complete Atlas setup guide
- MongoDB Atlas Quick Start - 5-minute setup guide
- Developer Guide - Comprehensive development guide
- API Reference - Complete API documentation
- Architecture - System architecture and design
- Quick Reference - Code snippets and patterns
- Deployment Guide - Production deployment instructions
- Technical Documentation - In-depth technical details
- Select a Piano Song - Choose from 4 beautiful piano pieces:
- A Thousand Years - Christina Perri's calm, romantic piano ballad
- Kiss The Rain - Yiruma's gentle, contemplative melody
- River Flows In You - Yiruma's smooth, flowing piece
- Gurenge - LiSA's energetic anime theme song
- Pick Instruments - Select up to 4 instruments (Piano, Flute, Xylophone, Kalimba)
- Start Your Session - Click play and start typing/working
- Adjust Volume - Use the slider to set your preferred volume level
- Your Rhythm Creates Music - The app adapts to your typing and mouse patterns
- React 18.3 - UI framework with hooks and concurrent features
- TypeScript 5.5 - Type safety and enhanced developer experience
- Vite - Fast build tool and development server
- TailwindCSS - Utility-first CSS framework
- Web Audio API - Native browser audio synthesis engine
- Canvas API - Real-time waveform visualization
- Lucide React - Beautiful, consistent icon library
- Node.js + Express - RESTful API server with middleware
- TypeScript - Type-safe backend development
- MongoDB Atlas - Cloud database with global clusters
- Mongoose - ODM for schema validation and data modeling
- Auth0 - OAuth2 authentication and JWT validation
- Google Gemini AI - AI-powered mood analysis and recommendations
- Docker + Docker Compose - Containerized development and deployment
- Biome - Fast linting and code formatting
- Makefile - Development workflow automation
- Nginx - Reverse proxy for production deployment
- GitHub Actions - CI/CD pipeline (planned)
- Web Audio API - Real-time audio synthesis and processing
- MIDI Parser - Custom MIDI file parsing for piano songs
- Audio Worklets - Background audio processing
- OscillatorNode - Waveform generation
- BiquadFilterNode - Audio filtering and effects
# Clone repository
git clone https://github.com/juxtaduo/pulseplay.git
cd pulseplay
# Start development environment
make up-dev
# Or run manually:
# Terminal 1: Backend
cd backend && npm install && npm run dev
# Terminal 2: Frontend
npm install && npm run dev# Development
npm run dev # Start frontend dev server (port 5173)
npm run dev:all # Start both frontend and backend
npm run build # Build for production
npm run preview # Preview production build
# Code Quality
npm run lint # Run Biome linter
npm run typecheck # Check TypeScript errors
# Backend Scripts (in backend/ directory)
npm run dev # Start backend dev server (port 3001)
npm run build # Build backend
npm run start # Start production server# Full development environment
make up-dev # Start all services with hot reload
# With local MongoDB
make up-local # Local database for development
# With MongoDB Atlas
make up-atlas # Cloud database for production-like setup
# Development workflow
make logs # Monitor all services
make rebuild # Rebuild after dependency changes
make down # Stop all servicesSee the Developer Guide for complete environment setup instructions.
pulseplay/
├── src/ # Frontend source code
│ ├── components/ # React components
│ ├── hooks/ # Custom React hooks
│ ├── lib/ # Utilities and helpers
│ ├── pages/ # Page components
│ ├── services/ # API services
│ ├── types/ # TypeScript type definitions
│ ├── utils/ # Utility functions
│ └── assets/ # Static assets
├── backend/ # Backend API server
│ └── src/
│ ├── models/ # MongoDB models
│ ├── routes/ # Express routes
│ ├── services/ # Business logic
│ ├── middleware/ # Express middleware
│ ├── config/ # Configuration files
│ ├── types/ # TypeScript types
│ └── utils/ # Backend utilities
├── docs/ # Documentation
│ ├── public/ # User-facing documentation
│ ├── developer/ # Developer technical docs
│ ├── docker/ # Docker deployment guides
│ ├── mongodb/ # MongoDB Atlas setup guides
│ ├── vercel/ # Vercel deployment guides
│ └── archive/ # Historical documentation
├── specs/ # Project specifications
├── scripts/ # Utility scripts
├── public/ # Static files served by Vite
├── docker/ # Docker-related files
│ ├── docker-compose.dev.yml
│ ├── docker-compose.atlas.yml
│ ├── docker-compose.yml
│ ├── Dockerfile
│ ├── Dockerfile.dev
│ └── Dockerfile.frontend
└── Makefile # Development and deployment commands
1. Track keystroke timestamps (last 50 keystrokes)
2. Filter to recent events (5-second window)
3. Calculate intervals between consecutive keystrokes
4. Average interval: sum(intervals) / count(intervals)
5. Rhythm score: min(100, 1000 / max(avgInterval, 50))
6. BPM: (60000 / avgInterval) * 0.25
7. Classify intensity: high (>70), medium (>40), low1. Normalize rhythm score (0-1 range)
2. Modulate oscillator frequencies:
- targetFreq = baseFreq * (1 + normalizedScore * 0.3)
3. Adjust filter cutoff:
- filterFreq = 1500 + (normalizedScore * 1500) Hz
4. Modulate gain:
- gain = baseGain * (0.7 + normalizedScore * 0.3)
5. Use linearRampToValueAtTime for smooth transitions# Type checking
npm run typecheckPulsePlay can be deployed as a full-stack serverless application using Vercel with MongoDB Atlas.
# Clone and setup
git clone https://github.com/juxtaduo/pulseplay.git
cd pulseplay
# Install Vercel CLI
npm i -g vercel
vercel login
# Deploy
vercel --prodConfigure environment variables in Vercel dashboard or CLI:
- MongoDB Atlas connection string
- Auth0 credentials
- Google Gemini API key
# Development
vercel --dev # Local development server
vercel env add # Add environment variables
# Production
vercel --prod # Deploy to production
vercel logs # View function logs
vercel analytics # View analyticsSee the Vercel Deployment Guide for complete setup instructions.
PulsePlay is fully containerized and ready for production deployment with Docker.
# Clone and setup
git clone https://github.com/juxtaduo/pulseplay.git
cd pulseplay
# Start all services (MongoDB Atlas)
make up-atlas
# Or start with local MongoDB
make up-local
# View application
open http://localhost:3000# Build and deploy
make build-prod
make deploy-prod
# Monitor logs
make logs
# Update deployment
make update-prodCreate .env files as described in the Docker README.
# Development
make up-dev # Start development environment
make up-local # Start with local MongoDB
make up-atlas # Start with MongoDB Atlas
# Production
make build-prod # Build production images
make deploy-prod # Deploy to production
make update-prod # Update running deployment
# Management
make logs # View all service logs
make logs-backend # View backend logs only
make logs-frontend # View frontend logs only
make down # Stop all services
make clean # Remove containers and volumes
make rebuild # Rebuild and restart all servicesSee the Docker README for complete deployment instructions.
npm install -g vercel
vercel login
vercel --prodnpm install -g netlify-cli
netlify login
netlify deploy --prodNote: Traditional hosting requires separate backend deployment. Vercel serverless or Docker deployment is recommended for full-stack deployment.
Contributions are welcome! Please follow these steps:
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'feat: add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
- Follow the existing code style
- Use TypeScript for type safety
- Write meaningful commit messages
- Add comments for complex logic
- Update documentation as needed
This project is licensed under the MIT License - see the LICENSE file for details.
- Web Audio API - For enabling real-time audio synthesis
- Google Gemini AI - For intelligent mood recommendations
- Auth0 - For secure authentication
- MongoDB Atlas - For reliable cloud database
- React Community - For amazing open-source tools
- GitHub Issues - Report bugs or request features
- Discussions - Join the conversation
Built with ❤️ for productivity and creativity