AI Radio - Complete Setup Guide

Project Structure

raidio/
├── backend/          # Node.js/Express API server
├── frontend/         # Web test harness (React/Vite)
└── mobile/           # iOS/Android app (Expo/React Native)

Prerequisites

• Node.js (v18+)
• Supabase Account
• Spotify Developer Account
• OpenAI API Key
• ElevenLabs API Key
• Xcode (for iOS Simulator)

---

Part 1: Supabase Setup

1. Create a new Supabase Project at supabase.com
2. Go to SQL Editor and run the contents of backend/src/db/schema.sql
3. Go to Storage and create a new public bucket named segments
4. Get your Project URL and Service Role Key from Project Settings → API

---

Part 2: Spotify Setup

1. Create an app at developer.spotify.com
2. Add Redirect URIs:
   • http://localhost:3000/auth/callback (for web testing)
   • airadio://auth (for mobile app)
3. Get your Client ID and Client Secret

---

Part 3: Backend Configuration

Edit backend/.env:

PORT=3000
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_SERVICE_KEY=eyJ...your-service-key
SPOTIFY_CLIENT_ID=your-spotify-client-id
SPOTIFY_CLIENT_SECRET=your-spotify-client-secret
SPOTIFY_REDIRECT_URI=http://localhost:3000/auth/callback
OPENAI_API_KEY=sk-...your-openai-key
ELEVENLABS_API_KEY=...your-elevenlabs-key

---

Part 4: Running the Backend

cd backend
npm install
npm run dev

Server will start on http://localhost:3000

---

Part 5: Testing Options

Option A: Web Frontend (Quick Test)

cd frontend
npm install
npm run dev

Open http://localhost:5173 and test:

• Login with Spotify
• Refresh playback status
• Generate AI segments

Option B: iOS Simulator (Full Experience)

cd mobile
npm install
npx expo start

Press i to launch iOS Simulator.

Testing Flow:

1. Tap "Login with Spotify"
2. Complete authentication in Safari
3. Deep link back to app
4. Play music on Spotify (desktop/mobile)
5. Tap "Refresh Status"
6. Tap "Trigger AI Break" → Music pauses → AI plays → Music resumes

---

API Endpoints

Authentication

• GET /auth/login - Initiates Spotify OAuth
• GET /auth/callback - OAuth callback handler
• POST /auth/swap - Token swap for iOS SDK
• POST /auth/refresh - Refresh tokens

Playback

• GET /playback/now - Current playback state
• POST /playback/pause - Pause Spotify
• POST /playback/resume - Resume Spotify

User

• GET /user/prefs - Get user preferences
• POST /user/prefs - Update preferences

Segments

• POST /segment/next - Generate AI segment
• GET /segment/history - Get segment history

---

Architecture Notes

Mobile App Flow

1. Auth: Mobile app uses ?mobile=true flag → Backend redirects to airadio:// deep link
2. Playback: Currently uses backend API (can be upgraded to native Spotify SDK)
3. AI Segments: Generated on backend → Audio stored in Supabase Storage → Played via expo-av

Backend AI Pipeline

1. Fetch news based on user preferences
2. Summarize with OpenAI (GPT-3.5)
3. Check vector similarity (avoid duplicates)
4. Generate TTS with ElevenLabs
5. Upload MP3 to Supabase Storage
6. Store metadata + embedding in Postgres

---

Troubleshooting

iOS Simulator can't reach backend

• Make sure backend is running on localhost:3000
• iOS Simulator can access localhost directly

Physical iOS device can't reach backend

• Get your Mac's IP: ifconfig | grep "inet "
• Update mobile/config.ts to use your IP (e.g., 192.168.1.100:3000)

Deep linking not working

• Make sure app.json has "scheme": "airadio"
• Rebuild the app after changing config

---

Next Steps

• Integrate native Spotify iOS SDK for zero-latency playback
• Add user preferences UI in mobile app
• Implement segment history view
• Add news source selection
• Deploy backend to production (Railway, Fly.io, etc.)