team-2/CHALLENGE_2/sleepysound/README_SPOTIFY.md
2025-08-02 04:48:34 +02:00

3.8 KiB

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

  2. Update the Secret File:

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

// 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!

# 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

// 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! 🎶