145 lines
4.5 KiB
Markdown
145 lines
4.5 KiB
Markdown
# Harmony — A Shared Spotify Experience for Two 💕
|
|
|
|
A beautiful, romantic web application that allows two Spotify users to share their musical journey together. Built with Next.js, TypeScript, and Tailwind CSS.
|
|
|
|
## Features
|
|
|
|
### 🎵 Shared Timeline
|
|
- View recently played songs from both users in a beautiful timeline
|
|
- See which songs you both have listened to with special heart markers 💕
|
|
- Track your musical journey together over time
|
|
|
|
### 🎧 Mix Generator
|
|
- AI-powered playlist creation based on both users' musical tastes
|
|
- Uses Spotify's Recommendations API to find perfect songs for both of you
|
|
- One-click playlist creation and saving to Spotify
|
|
|
|
### 📊 Live Dashboard
|
|
- Real-time display of what both users are currently listening to
|
|
- Harmony percentage calculation based on audio features (BPM, energy, valence)
|
|
- Beautiful animated progress bars and album covers
|
|
|
|
### ⚙️ Settings
|
|
- Customize display names and profile pictures
|
|
- Theme selection (Rose, Purple, Blue)
|
|
- Secure user authentication with Spotify OAuth
|
|
|
|
## Tech Stack
|
|
|
|
- **Frontend**: Next.js 15, React 19, TypeScript, Tailwind CSS
|
|
- **Animations**: Framer Motion
|
|
- **Icons**: Lucide React
|
|
- **Backend**: Next.js API Routes
|
|
- **Database**: PostgreSQL with Prisma ORM
|
|
- **Authentication**: NextAuth.js with Spotify OAuth
|
|
- **Music API**: Spotify Web API
|
|
|
|
## Setup Instructions
|
|
|
|
### 1. Prerequisites
|
|
- Node.js 18+
|
|
- PostgreSQL database
|
|
- Spotify Developer Account
|
|
|
|
### 2. Database Setup
|
|
```bash
|
|
# Create PostgreSQL database
|
|
createdb spotify_app
|
|
|
|
# Set up database user (optional, can use default)
|
|
psql -c "CREATE USER iu WITH PASSWORD 'iu';"
|
|
psql -c "GRANT ALL PRIVILEGES ON DATABASE spotify_app TO iu;"
|
|
```
|
|
|
|
### 3. Environment Configuration
|
|
Copy `.env.local` and update with your credentials:
|
|
|
|
```env
|
|
# Database
|
|
DATABASE_URL="postgresql://iu:iu@localhost:5432/spotify_app?schema=public"
|
|
|
|
# NextAuth
|
|
NEXTAUTH_URL="http://localhost:3000"
|
|
NEXTAUTH_SECRET="your-secret-key-here"
|
|
|
|
# Spotify OAuth
|
|
SPOTIFY_CLIENT_ID="your-spotify-client-id"
|
|
SPOTIFY_CLIENT_SECRET="your-spotify-client-secret"
|
|
|
|
# Allowed Spotify Users (comma-separated Spotify user IDs)
|
|
ALLOWED_SPOTIFY_USERS="your-spotify-user-id,partner-spotify-user-id"
|
|
```
|
|
|
|
### 4. Spotify App Setup
|
|
1. Go to [Spotify Developer Dashboard](https://developer.spotify.com/dashboard)
|
|
2. Create a new app
|
|
3. Add `http://localhost:3000/api/auth/callback/spotify` to Redirect URIs
|
|
4. Copy Client ID and Client Secret to your `.env.local`
|
|
|
|
### 5. Installation & Setup
|
|
```bash
|
|
# Install dependencies
|
|
npm install
|
|
|
|
# Generate Prisma client
|
|
npm run db:generate
|
|
|
|
# Push database schema
|
|
npm run db:push
|
|
|
|
# Start development server
|
|
npm run dev
|
|
```
|
|
|
|
### 6. Get Spotify User IDs
|
|
To find your Spotify user IDs:
|
|
1. Go to your Spotify profile
|
|
2. Click "Share" → "Copy link to profile"
|
|
3. The user ID is in the URL: `https://open.spotify.com/user/{USER_ID}`
|
|
|
|
## Usage
|
|
|
|
1. **Sign In**: Both users need to sign in with their Spotify accounts
|
|
2. **Dashboard**: View overview of both users' activity
|
|
3. **Timeline**: See shared listening history with heart markers for mutual songs
|
|
4. **Mix Generator**: Create AI-powered playlists based on both users' tastes
|
|
5. **Live Dashboard**: Real-time view of current listening activity and harmony matching
|
|
6. **Settings**: Customize your experience
|
|
|
|
## API Endpoints
|
|
|
|
- `GET /api/users` - Get all connected users
|
|
- `GET /api/timeline` - Get shared listening timeline
|
|
- `GET /api/spotify/recently-played` - Get user's recently played tracks
|
|
- `GET /api/spotify/currently-playing` - Get real-time listening data
|
|
- `POST /api/spotify/recommendations` - Generate music recommendations
|
|
- `POST /api/spotify/create-playlist` - Create Spotify playlist
|
|
- `POST /api/spotify/harmony` - Calculate harmony percentage
|
|
|
|
## Security Features
|
|
|
|
- User whitelist: Only specified Spotify users can access the app
|
|
- Secure token storage in PostgreSQL database
|
|
- Automatic token refresh handling
|
|
- Protected API routes with NextAuth session validation
|
|
|
|
## Design Philosophy
|
|
|
|
Harmony is designed with romance and elegance in mind:
|
|
- **Pastel color palette**: Rose, pink, and purple tones
|
|
- **Glassmorphism effects**: Beautiful frosted glass cards
|
|
- **Smooth animations**: Framer Motion for fluid interactions
|
|
- **Romantic touches**: Heart animations, floating elements, gradient text
|
|
- **Responsive design**: Works perfectly on all devices
|
|
|
|
## Contributing
|
|
|
|
This is a personal project, but feel free to fork and customize for your own use!
|
|
|
|
## License
|
|
|
|
MIT License - feel free to use this for your own romantic musical adventures! 💕
|
|
|
|
---
|
|
|
|
Made with 💕 for couples who love music together |