🎵 Spotify Music Selector

A collaborative music voting application where users can join sessions, search for songs using the Spotify API, and vote for their favorites in real-time.

✨ Features

• Session-based voting: Create sessions that others can join with a shareable URL
• Spotify integration: Search for songs using mock Spotify API (ready for real integration)
• Real-time updates: See vote counts update automatically every 5 seconds
• Rate limiting: Users can vote once every 5 minutes
• Song cooldown: Removed songs can't be re-added for 20 minutes
• Responsive design: Works on desktop and mobile devices

🚀 Getting Started

Prerequisites

• Node.js (v18 or later)
• npm or yarn

Installation

1. Clone the repository:

git clone <your-repo-url>
cd SpotifyMusicSelector

2. Install dependencies:

npm install

3. Start the development server:

npm run dev

4. Open your browser and navigate to http://localhost:3000 (or the port shown in terminal)

Building for Production

npm run build
npm start

🎮 How to Use

1. Create a Session: Enter a session name on the home page and click "Create Session"
2. Share the URL: Copy the session URL and share it with friends
3. Search for Songs: Use the search box to find songs (currently using mock data)
4. Vote for Songs: Click the vote button on songs you like
5. Watch Rankings: Songs are automatically sorted by vote count
6. Remove Songs: Click the ✕ button to remove songs (20-minute cooldown applies)

🏗️ Architecture

Frontend (Next.js App Router)

• /: Home page for creating sessions
• /session/[sessionId]: Session page for voting and managing songs
• Components: Reusable UI components for search, song lists, and session info

Backend (Next.js API Routes)

• /api/sessions: Create and list sessions
• /api/sessions/[sessionId]: Get session data
• /api/sessions/[sessionId]/songs: Add/remove songs
• /api/sessions/[sessionId]/vote: Vote for songs
• /api/spotify: Mock Spotify search (ready for real API)

Data Storage

Currently uses in-memory storage for demo purposes. For production, replace with:

• Database (PostgreSQL, MongoDB, etc.)
• Redis for session management
• WebSocket connections for real-time updates

🔧 Configuration

Spotify API Integration

To integrate with the real Spotify Web API:

1. Register your app at Spotify Developer Dashboard
2. Get your Client ID and Client Secret
3. Create a .env.local file:

SPOTIFY_CLIENT_ID=your_client_id
SPOTIFY_CLIENT_SECRET=your_client_secret

4. Update /src/app/api/spotify/route.ts with the real implementation (code template included)

Environment Variables

Create a .env.local file in the root directory:

# Spotify API (when implementing real integration)
SPOTIFY_CLIENT_ID=your_spotify_client_id
SPOTIFY_CLIENT_SECRET=your_spotify_client_secret

# Database (for production)
DATABASE_URL=your_database_url

# Session Configuration
VOTE_COOLDOWN_MINUTES=5
SONG_REMOVAL_COOLDOWN_MINUTES=20

🎨 Technologies Used

• Frontend: Next.js 15, React, TypeScript, Tailwind CSS
• Backend: Next.js API Routes
• Styling: Tailwind CSS with custom Spotify-themed design
• State Management: React hooks
• Real-time Updates: Polling (can be upgraded to WebSockets)

📁 Project Structure

src/
├── app/
│   ├── api/                 # API routes
│   │   ├── sessions/        # Session management
│   │   └── spotify/         # Spotify search
│   ├── session/[sessionId]/ # Session page
│   ├── globals.css          # Global styles
│   ├── layout.tsx           # Root layout
│   └── page.tsx             # Home page
├── components/              # React components
│   ├── SpotifySearch.tsx    # Song search component
│   ├── SongList.tsx         # Vote/ranking component
│   └── SessionInfo.tsx      # Session details
└── lib/
    └── sessions.ts          # Shared session storage

🚀 Deployment

Vercel (Recommended)

1. Push your code to GitHub
2. Import project on Vercel
3. Add environment variables
4. Deploy

Other Platforms

The app can be deployed on any platform that supports Next.js:

• Railway
• Heroku
• DigitalOcean
• AWS
• Google Cloud

🔮 Future Enhancements

• Real Spotify Integration: Replace mock API with real Spotify Web API
• WebSocket Support: Real-time updates without polling
• User Authentication: Login with Spotify accounts
• Playlist Export: Export voted songs to Spotify playlists
• Advanced Voting: Multiple vote types, weighted voting
• Session Management: Password-protected sessions, admin controls
• Mobile App: React Native version
• Analytics: Vote history, popular songs tracking

🐛 Troubleshooting

Common Issues

Port already in use:

# Kill process on port 3000
lsof -ti:3000 | xargs kill -9

Build errors:

# Clear Next.js cache
rm -rf .next
npm run build

TypeScript errors:

# Check TypeScript configuration
npx tsc --noEmit

📄 License

This project is licensed under the MIT License.

🤝 Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature/new-feature
3. Commit changes: git commit -am 'Add new feature'
4. Push to branch: git push origin feature/new-feature
5. Submit a pull request

📧 Support

For questions or support, please open an issue on GitHub or contact the development team.

---

Built with ❤️ using Next.js and the Spotify Web API