2025-08-02 13:28:10 +02:00
|
|
|
# 🎵 Supa Tunes
|
2025-08-01 15:31:37 +00:00
|
|
|
|
2025-08-02 13:28:10 +02:00
|
|
|
**A collaborative music queue app built by Supa Duo**
|
|
|
|
|
|
|
|
|
|
Turn any space into a shared music experience! Supa Tunes lets people vote on songs, add their favorites, and enjoy music together in real-time.
|
|
|
|
|
|
|
|
|
|
## ✨ Features
|
|
|
|
|
|
|
|
|
|
- 🎧 **Real-time collaborative queue** - Everyone can add songs and vote
|
|
|
|
|
- 🎵 **Spotify integration** - Play music directly through Spotify
|
|
|
|
|
- 🤖 **AI-powered suggestions** - Get song recommendations based on vibes and room themes
|
|
|
|
|
- 📱 **QR code sharing** - Easy room access via QR codes
|
|
|
|
|
- ⚡ **Live updates** - Real-time sync across all devices
|
|
|
|
|
- 🗳️ **Smart voting system** - Rate-limited voting to keep things fair
|
|
|
|
|
- 🎯 **Room rules** - Set the vibe with custom music rules
|
|
|
|
|
|
|
|
|
|
## 🚀 Quick Start
|
|
|
|
|
|
|
|
|
|
### Prerequisites
|
|
|
|
|
|
|
|
|
|
- [Deno](https://deno.land/) (for backend)
|
|
|
|
|
- [Node.js](https://nodejs.org/) (for frontend)
|
|
|
|
|
- Spotify Premium account
|
|
|
|
|
- API keys for Spotify, YouTube, and Google Gemini
|
|
|
|
|
|
|
|
|
|
### Backend Setup
|
|
|
|
|
|
|
|
|
|
1. Navigate to the backend directory:
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
cd backend
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
2. Create a `.env` file with your API keys:
|
|
|
|
|
|
|
|
|
|
```env
|
|
|
|
|
PORT=8000
|
|
|
|
|
GEMINI_API_KEY=your_gemini_api_key
|
|
|
|
|
SPOTIFY_CLIENT_ID=your_spotify_client_id
|
|
|
|
|
SPOTIFY_CLIENT_SECRET=your_spotify_client_secret
|
|
|
|
|
YT_API_KEY=your_youtube_api_key
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
3. Run with Docker:
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
docker build -f Dockerfile -t supa-tunes-backend .
|
|
|
|
|
docker run --rm -p 8000:8000 supa-tunes-backend
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
Or run directly with Deno:
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
deno run --allow-net --allow-env main.ts
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
### Frontend Setup
|
|
|
|
|
|
|
|
|
|
1. Navigate to the frontend directory:
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
cd frontend
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
2. Install dependencies:
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
npm install
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
3. Start the development server:
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
npm run dev
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
## 🎮 How to Use
|
|
|
|
|
|
|
|
|
|
1. **Create a Room**: Connect your Spotify account and create a new music space
|
|
|
|
|
2. **Share the QR Code**: Others can scan to join your room
|
|
|
|
|
3. **Add Songs**: Search for music using natural language (e.g., "upbeat 80s vibes")
|
|
|
|
|
4. **Vote**: Everyone gets votes to influence what plays next
|
|
|
|
|
5. **Enjoy**: Music plays automatically based on the queue and votes!
|
|
|
|
|
|
|
|
|
|
## 🛠️ Tech Stack
|
|
|
|
|
|
|
|
|
|
**Backend (Deno/TypeScript)**
|
|
|
|
|
|
|
|
|
|
- Deno runtime with TypeScript
|
|
|
|
|
- Google Gemini AI for music suggestions
|
|
|
|
|
- Spotify Web API integration
|
|
|
|
|
- YouTube API for video content
|
|
|
|
|
- RESTful API design
|
|
|
|
|
|
|
|
|
|
**Frontend (SvelteKit)**
|
|
|
|
|
|
|
|
|
|
- SvelteKit with TypeScript
|
|
|
|
|
- Supabase for real-time database
|
|
|
|
|
- Tailwind CSS for styling
|
|
|
|
|
- Real-time subscriptions for live updates
|
|
|
|
|
|
|
|
|
|
**Infrastructure**
|
|
|
|
|
|
|
|
|
|
- Docker containerization
|
|
|
|
|
- Supabase for database and real-time features
|
|
|
|
|
- Railway for deployment
|
|
|
|
|
|
|
|
|
|
## 🎵 API Endpoints
|
|
|
|
|
|
|
|
|
|
- `POST /music` - Search for songs with AI
|
|
|
|
|
- `POST /newSuggestions` - Get AI-powered room suggestions
|
|
|
|
|
- `POST /track` - Get track details by ID
|
|
|
|
|
- `POST /video` - Find YouTube videos for tracks
|
|
|
|
|
- `GET /health` - Health check
|
|
|
|
|
|
|
|
|
|
## 🚀 Deployment
|
|
|
|
|
|
|
|
|
|
The app is containerized and ready for deployment on Railway or any Docker-compatible platform.
|
|
|
|
|
|
|
|
|
|
## 👥 Team Supa Duo
|
|
|
|
|
|
|
|
|
|
Built with ❤️ by the Supa Duo team!
|
|
|
|
|
|
|
|
|
|
## Thanks
|
|
|
|
|
|
|
|
|
|
Special thanks to Konverto Lab for providing this challenge!
|
