spotify/README.md

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

# 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:

# 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
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

# 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