soundwave/docs/OFFLINE_QUICK_START.md

🚀 Quick Start: Offline Playlists

For Users

Download Playlist for Offline Use:

1. Navigate to any playlist
2. Scroll to "Cache for Offline" card
3. Tap "Make Available Offline"
4. Wait for download to complete
5. Green checkmark = Ready! 🎉

Play Offline:

1. Enable airplane mode
2. Open SoundWave
3. Navigate to cached playlist
4. Tap Play - Works instantly! 📱

Manage Storage:

1. Tap "Offline" in sidebar (PWA badge)
2. View all cached playlists
3. Remove individual playlists or clear all
4. See storage usage at a glance

---

For Developers

Check if Playlist is Cached:

import { offlineStorage } from '../utils/offlineStorage';

const playlist = await offlineStorage.getPlaylist(id);
if (playlist?.offline) {
  console.log('Available offline!');
}

Cache a Playlist:

import { usePWA } from '../context/PWAContext';

const { cachePlaylist } = usePWA();
const audioUrls = tracks.map(t => `/api/audio/${t.youtube_id}/download/`);

await cachePlaylist(playlistId, audioUrls);
await offlineStorage.savePlaylist({...playlist, offline: true});

Remove from Cache:

const { removePlaylistCache } = usePWA();

await removePlaylistCache(playlistId, audioUrls);
await offlineStorage.removePlaylist(id);

---

New Routes

• /offline - Offline storage management page
• All existing routes unchanged

---

Security ✅

• ✅ Authentication required for all endpoints
• ✅ User isolation enforced (owner-based filtering)
• ✅ No cross-user data access
• ✅ Service Worker respects authentication
• ✅ No route conflicts

---

Testing

Online:

# Navigate to playlist, click "Make Available Offline"
# Check sidebar badge shows "Offline" menu
# Visit /offline to see cached playlists

Offline:

# Enable airplane mode in browser DevTools
# Navigate to cached playlist
# Verify playback works
# Check offline warning appears for uncached content

---

Browser DevTools Testing

Service Worker:

Application → Service Workers → soundwave-v1 (Active)

Cache Storage:

Application → Cache Storage
- soundwave-audio-v1 (audio files)
- soundwave-api-v1 (API responses)

IndexedDB:

Application → IndexedDB → soundwave-offline
- playlists (cached metadata)

---

Storage Limits

• Desktop: ~50% of available disk space
• Mobile: ~50% of available storage
• Minimum: 10 MB per origin
• Typical: Several GB available

---

Known Behaviors

1. Storage is per-browser - Not synced across devices
2. Caching requires network - Must be online to download
3. Authentication required - Token must be valid
4. Browser may evict - On low storage, browser clears cache
5. HTTPS required - Service Workers need secure context

---

Files Changed

New:

• frontend/src/pages/OfflineManagerPage.tsx
• docs/OFFLINE_FEATURE_COMPLETE.md

Modified:

• frontend/src/pages/PlaylistDetailPage.tsx
• frontend/src/pages/PlaylistsPage.tsx
• frontend/src/App.tsx
• frontend/src/components/Sidebar.tsx
• frontend/public/service-worker.js

---

No Breaking Changes

✅ All existing features work as before
✅ Backward compatible
✅ Progressive enhancement
✅ Graceful degradation

---

Ready to use! 🎉