soundwave/docs/PLAYLIST_CONTROLS.md

Playlist Controls Feature

Overview

Enhanced playlist detail page with comprehensive controls for playing, shuffling, and downloading tracks.

Features

Top-Level Controls

Located at the top of the playlist detail page:

1. Play All Button

   • Plays all downloaded tracks in order
   • Disabled if no tracks are downloaded
   • Sets the first track to play and queues the rest

2. Shuffle Button

   • Randomizes and plays all downloaded tracks
   • Uses Fisher-Yates algorithm for true random shuffle
   • Disabled if no tracks are downloaded
   • Visual feedback with snackbar notification

3. Download All Button

   • Triggers playlist sync to download all tracks
   • Disabled while sync is in progress
   • Uses existing playlist download API endpoint

Individual Track Controls

In the tracks table, each row includes:

1. Play Button

   • Available for downloaded tracks only
   • Instantly starts playback
   • Disabled/grayed out for non-downloaded tracks

2. Download Button (NEW)

   • Appears only for non-downloaded tracks
   • Downloads individual tracks on demand
   • Shows loading spinner while downloading
   • Automatically refreshes playlist after download completes
   • Uses new individual audio download API endpoint

Implementation Details

Backend Changes

New API Endpoint

POST /api/audio/<youtube_id>/

• Action: download
• Creates DownloadQueue entry
• Triggers Celery task download_audio_task
• Returns:
  • 200 OK: Already downloaded or download in progress
  • 202 Accepted: Download started successfully
  • 400 Bad Request: Invalid action
  • 404 Not Found: Audio not found or not owned by user

Security:

• Owner filtering: get_object_or_404(Audio, youtube_id=youtube_id, owner=request.user)
• Checks for existing downloads before creating new queue entries
• Integrates with existing Celery task system

Frontend Changes

New Components

• Play All Button: Material-UI Button with PlayIcon
• Shuffle Button: Material-UI Button with ShuffleIcon
• Download All Button: Material-UI Button with CloudDownloadIcon
• Individual Download Button: IconButton with DownloadIcon or CircularProgress

State Management

const [downloadingTracks, setDownloadingTracks] = useState<Set<string>>(new Set());
const [snackbarOpen, setSnackbarOpen] = useState(false);
const [snackbarMessage, setSnackbarMessage] = useState('');

API Client Update

Added download method to audioAPI:

download: (youtubeId: string) => api.post(`/audio/${youtubeId}/`, { action: 'download' })

User Experience

Visual Feedback

• Snackbar Notifications: User-friendly messages for all actions
• Loading States: CircularProgress indicators during downloads
• Disabled States: Buttons properly disabled when actions aren't available
• Mobile Responsive: Touch-friendly 48px+ button sizes
• Hide/Show Labels: Text hidden on mobile, icons remain visible

PWA Optimization

• No page reloads - all actions use React state
• Touch-friendly button sizes (minimum 48px)
• Proper color contrast for accessibility
• Loading feedback for async operations

Usage

For Users

1. Navigate to any playlist from the Playlists page

2. Use top controls to:

   • Play All: Start playing the entire playlist
   • Shuffle: Play tracks in random order
   • Download All: Download the entire playlist

3. Use track-level controls to:

   • Click Play icon to play individual tracks
   • Click Download icon to download specific tracks

For Developers

Testing Individual Downloads

# Test download endpoint
curl -X POST http://localhost:8889/api/audio/VIDEO_ID/ \
  -H "Authorization: Token YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"action": "download"}'

Monitoring Downloads

• Check Celery logs for task execution
• Monitor DownloadQueue table for status
• View updated playlist after completion

Security Considerations

✅ Implemented Safeguards:

• User authentication required for all endpoints
• Owner filtering on all queries
• Duplicate download prevention
• Rate limiting via Celery task queue
• Input validation on action parameter

Files Modified

Backend

• /backend/audio/views.py: Added POST method to AudioDetailView
• /backend/config/urls.py: Existing routes work with new endpoint

Frontend

• /frontend/src/api/client.ts: Added audioAPI.download() method
• /frontend/src/pages/PlaylistDetailPage.tsx: Added all control buttons and handlers
• /frontend/src/types/index.ts: No changes needed (youtube_id already optional)

Performance Notes

• Shuffle Algorithm: O(n) Fisher-Yates shuffle, efficient for any playlist size
• State Management: Uses Set for O(1) download tracking lookups
• Auto-refresh: 2-second delay after download to allow backend processing
• Loading States: Prevents duplicate download requests via disabled buttons

Known Limitations

1. Queue Visualization: Download queue not visible in UI (backend only)
2. Playlist Queue: Play All/Shuffle only starts first track (no queue implementation yet)
3. Progress Tracking: No real-time download progress for individual tracks
4. Batch Downloads: Individual downloads don't batch (each triggers separate task)

Future Enhancements

• Real-time download progress tracking (WebSockets/SSE)
• Play queue implementation for continuous playback
• Batch download optimization for multiple tracks
• Download queue visibility in UI
• Cancel download functionality
• Retry failed downloads from UI

Related Documentation

• Playlist Browsing Feature
• Audio Seeking Fix
• PWA Implementation