# 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