# Phase 7: Music & DJ Features - Implementation Guide  

**Duration**: Weeks 30-33 | **Complexity**: Medium | **Team Size**: 2-3 devs

## Executive Summary

Phase 7 enables music creators and DJs with specialized tools: DJ layout, music visualization, queue management, and Spotify integration.

---

## Phase 7 Goals

- DJ-specific UI mode (different layout)
- Audio-reactive visualizations
- Music queue management
- Spotify/music platform integration
- High-bitrate audio support

---

## Key Features

### 1. DJ Mode Layout (25%)
```
Normal stream:           DJ Mode:
┌─────────────┐         ┌───────────────┐
│   Player    │         │ Visualizer    │
│             │         │ (full screen) │
├─────────────┤         ├───────────────┤
│    Chat     │         │ Now Playing   │
└─────────────┘         │ Next Track    │
                        │ Queue (compact)
                        └───────────────┘
```

### 2. Audio Visualization (40%)
```
Libraries:
- Three.js (3D)
- PixiJS (2D)
- Babylon.js

Visualization types:
- Classic waveform
- Particle system
- Audio spectrum
- Equalizer bars
- Custom animations

Real-time data:
- Audio frequency analysis (Web Audio API)
- Peak detection
- Beat detection
- BPM extraction
```

### 3. Queue Management (20%)
```
Features:
- Display current track
- Queue list with drag-reorder
- Next up indication
- Request system (chat: !songrequest)
- Auto-queue next track

Database:
- StreamQueue
- QueueItem
- SongRequest
- SongLibrary
```

### 4. Spotify Integration (15%)
```
Setup:
- Creator links Spotify account
- OAuth flow
- Scopes: playlist-read, playlist-modify-private

Features:
- Import playlists
- Show Spotify player widget
- Link to Spotify album
- Playlist history

API Integration:
- Now playing info
- Preview playback
- Album artwork
```

---

## Implementation

### Database
```prisma
model StreamQueue {
  id String @id
  streamId String @unique
  stream Stream @relation(fields: [streamId])
  
  currentTrack Int? // Index in queue
  items QueueItem[]
}

model QueueItem {
  id String @id
  queueId String
  queue StreamQueue @relation(fields: [queueId])
  
  trackId String // e.g., Spotify track ID
  title String
  artist String
  album String?
  cover String? // Album art URL
  duration Int // Seconds
  
  requestedBy String? // User ID
  position Int
  
  playedAt DateTime?
  
  createdAt DateTime
  updatedAt DateTime
}

model SongRequest {
  id String @id
  userId String
  user User @relation(fields: [userId])
  
  streamId String
  stream Stream @relation(fields: [streamId])
  
  trackId String
  title String
  artist String
  
  status String // PENDING, PLAYING, SKIPPED, REJECTED
  
  createdAt DateTime
}

model DJProfile {
  id String @id
  channelId String @unique
  channel Channel @relation(fields: [channelId])
  
  isDJMode Boolean @default(false)
  visualizationType String @default("spectrum") // spectrum, waveform, particles
  
  spotifyConnected Boolean @default(false)
  spotifyId String? // OAuth ID
  spotifyAccessToken String? // Encrypted
  
  bitrate Int @default(256) // kbps, up to 320
  audioFormat String @default("AAC") // AAC, FLAC, etc
  
  updatedAt DateTime
}
```

### Key Components
```
components/dj/
├── DJMode.tsx (layout wrapper)
├── Visualizer.tsx (audio-reactive)
├── NowPlaying.tsx (track info)
├── QueueList.tsx (manage tracks)
├── SpotifyWidget.tsx (Spotify player)
└── SongRequestModeration.tsx
```

### APIs
```
Queue:
- GET /api/streams/:id/queue
- POST /api/queue/:queueId/add
- PUT /api/queue/:queueId/reorder
- DELETE /api/queue/:queueId/items/:id
- POST /api/queue/:queueId/skip

Requests:
- POST /api/song-requests (viewer requests)
- GET /api/streams/:id/requests
- PUT /api/requests/:id (approve/reject)

DJ Settings:
- PUT /api/dj-profile (update settings)
- POST /api/spotify/connect (OAuth)
- GET /api/spotify/playlists
```

---

## Success Metrics

- 100+ music creators active
- 80%+ DJ streams use visualizations
- <50ms visualization latency
- 10k+ Spotify playlists linked
- 50k+ song requests per month

---

## Technical Stack

- **Audio Analysis**: Web Audio API
- **Visualization**: Three.js or PixiJS
- **Spotify API**: Official SDK
- **High-bitrate codec**: AAC-LC (256kbps) or FLAC

---

## Timeline

| Week | Focus |
|------|-------|
| 30 | DJ mode layout, visualizer setup |
| 31 | Audio visualization, beat detection |
| 32 | Spotify integration, queue management |
| 33 | Song requests, testing, deployment |

---

**Completion**: Week 33 (by August 15, 2025)  
**Next**: Phase 8 - Enterprise & Education

See [PHASE_8_ENTERPRISE.md](PHASE_8_ENTERPRISE.md)