133 lines
3.8 KiB
Markdown
133 lines
3.8 KiB
Markdown
# 🎵 SleepySound - Spotify Integration Setup
|
|
|
|
## Quick Start
|
|
|
|
The app now loads Spotify credentials from `lib/services/SPOTIFY_SECRET.dart`. You have two options:
|
|
|
|
### Option 1: Demo Mode (Works Immediately)
|
|
- The app works perfectly with realistic demo data
|
|
- No setup required - just run the app!
|
|
- All features work: search, voting, queue management
|
|
|
|
### Option 2: Real Spotify Integration
|
|
|
|
1. **Get Spotify API Credentials:**
|
|
- Go to [Spotify Developer Dashboard](https://developer.spotify.com/dashboard)
|
|
- Create a new app called "SleepySound"
|
|
- Copy your Client ID and Client Secret
|
|
|
|
2. **Update the Secret File:**
|
|
```dart
|
|
// In lib/services/SPOTIFY_SECRET.dart
|
|
class SpotifyCredentials {
|
|
static const String clientId = 'your_actual_client_id_here';
|
|
static const String clientSecret = 'your_actual_client_secret_here';
|
|
}
|
|
```
|
|
|
|
3. **Run the App:**
|
|
- The app automatically detects valid credentials
|
|
- Real Spotify search will be enabled
|
|
- You'll see "🎵 Spotify" instead of "🎮 Demo" in the UI
|
|
|
|
## How It Works
|
|
|
|
### 🔄 Automatic Credential Detection
|
|
```dart
|
|
// The service automatically checks for valid credentials
|
|
bool get _hasValidCredentials =>
|
|
_clientId != 'YOUR_SPOTIFY_CLIENT_ID' &&
|
|
_clientSecret != 'YOUR_SPOTIFY_CLIENT_SECRET';
|
|
```
|
|
|
|
### 🎮 Graceful Fallback
|
|
- **Invalid/Missing Credentials** → Demo data
|
|
- **Valid Credentials** → Real Spotify API
|
|
- **API Errors** → Falls back to demo data
|
|
|
|
### 🎯 Visual Indicators
|
|
- **"🎵 Spotify"** badge = Real API active
|
|
- **"🎮 Demo"** badge = Using demo data
|
|
- Console logs show configuration status
|
|
|
|
## Features
|
|
|
|
### ✅ Working Now (Demo Mode)
|
|
- Song search with realistic results
|
|
- Upvote/downvote queue management
|
|
- Real-time queue reordering
|
|
- Album artwork simulation
|
|
- Location-based group features
|
|
|
|
### ✅ Enhanced with Real Spotify
|
|
- Actual Spotify track search
|
|
- Real album artwork
|
|
- Accurate track metadata
|
|
- External Spotify links
|
|
- Preview URLs (where available)
|
|
|
|
## Security Notes
|
|
|
|
⚠️ **Important:** Never commit real credentials to version control!
|
|
|
|
```bash
|
|
# Add this to .gitignore
|
|
lib/services/SPOTIFY_SECRET.dart
|
|
```
|
|
|
|
For production apps:
|
|
- Use environment variables
|
|
- Use secure credential storage
|
|
- Implement proper OAuth flows
|
|
|
|
## File Structure
|
|
|
|
```
|
|
lib/
|
|
├── services/
|
|
│ ├── spotify_service.dart # Main Spotify API service
|
|
│ └── SPOTIFY_SECRET.dart # Your credentials (gitignored)
|
|
├── models/
|
|
│ └── spotify_track.dart # Spotify data models
|
|
└── pages/
|
|
├── voting_page.dart # Search & voting interface
|
|
├── now_playing_page.dart # Current queue display
|
|
└── group_page.dart # Location & group features
|
|
```
|
|
|
|
## API Integration Details
|
|
|
|
### Client Credentials Flow
|
|
- Used for public track search (no user login required)
|
|
- Perfect for the collaborative jukebox use case
|
|
- Handles token refresh automatically
|
|
|
|
### Search Functionality
|
|
```dart
|
|
// Real Spotify search
|
|
final tracks = await _spotifyService.searchTracks('summer vibes', limit: 10);
|
|
|
|
// Automatic fallback to demo data if API unavailable
|
|
```
|
|
|
|
### Error Handling
|
|
- Network errors → Demo data
|
|
- Invalid credentials → Demo data
|
|
- Rate limiting → Demo data
|
|
- Token expiration → Automatic refresh
|
|
|
|
## Challenge Requirements ✅
|
|
|
|
- ✅ **Music streaming API integration** - Spotify Web API
|
|
- ✅ **Track metadata retrieval** - Full track info + artwork
|
|
- ✅ **Demo-ready functionality** - Works without setup
|
|
- ✅ **Real-world usability** - Graceful fallbacks
|
|
|
|
## Development Tips
|
|
|
|
1. **Start with Demo Mode** - Get familiar with the app
|
|
2. **Add Real Credentials** - See the enhanced experience
|
|
3. **Test Both Modes** - Ensure fallbacks work
|
|
4. **Check Console Logs** - See API status messages
|
|
|
|
Enjoy building your collaborative music experience! 🎶
|