A high-performance, offline-capable Progressive Web App for streaming music playlists with lock screen media controls and seamless background playback.
- Playlist Management: Load and switch between multiple playlists (
Gym,Driving,Songs) seamlessly, with horizontal swipe navigation scoped to the playlist selector on mobile. - Playback Controls: Play, pause, skip forward/backward, and seek within tracks.
- Dual Playback Engines: Switch between Standard Battery Saver (Mode 1) and Car & Bluetooth Mode (Mode 2) with auto-kill inactivity watchdog.
- Full Offline Downloads: One-click download of full playlists (audio tracks, thumbnails, and lyrics) with automated retry and verification.
- Shuffle & Repeat: Single-playlist and global cross-playlist shuffle modes; repeat one, repeat all, or linear playback.
- Lock Screen Integration: Native media controls on mobile lock screens with artwork, title, artist, and seekbar sync.
- Lyrics Display: Synchronized
.lrclyrics with auto-scroll during playback. - Virtual Scrolling: Fast, smooth rendering of playlists with thousands of tracks using a recycled DOM pool.
- Zero-GPU Architecture: 0.0% GPU load on desktop, flat opaque mobile overlays with zero compositor blur overhead.
- Theme Colors: Dynamic accent colors extracted from album artwork.
- Header: Album artwork, track title, artist name, and duration.
- Playback Controls: Play/pause button, skip buttons, and seek bar.
- Playlist View: Virtual scrolling list of tracks with duration and current play position indicator.
- Lyrics Drawer: Synchronized lyrics that auto-scroll during playback; toggle via button or swipe gestures.
- Settings Modal: Audio engine selection (Mode 1 vs Mode 2), inactivity auto-kill timeout configuration, and app install/reload actions.
- Download Overlay: Real-time progress tracker (
Gym - 14 / 213) with verification and retry status.
- Space: Play/pause
-
→ / ←: Seek forward / backward (
$\pm 5\text{s}$ ) - : / ;: Previous track
- " / ': Next track
- r / R: Cycle repeat mode (Off -> All -> One)
- s / S: Cycle shuffle mode (Off -> Global -> Playlist)
- L: Toggle lyrics panel
- Escape: Close settings modal
- A-Z / 0-9: Automatically focus search input
- Standard (Battery Saver / Mode 1): Minimal battery consumption. When paused, media session is marked paused with rate
1.0. - Car & Bluetooth Mode (Mode 2): Prevents vehicle infotainment and Bluetooth headphone disconnects when paused by maintaining an active media session state and running a silent audio anchor loop on mobile.
- Media Session Stability (Baseline 05eae74): Strict Zero Metadata Churn invariant prevents Android SystemUI SquigglyProgress wave freezes. Direct homescreen unlock safely resumes wave animation via background 1Hz timeupdate anchors.
- Inactivity Auto-Kill Watchdog: Configurable sleep timer (15m, 30m, 1h, 2h, custom 1-1440m, or never) that automatically disarms Mode 2 and pauses all playback after sustained pause inactivity.
- Hardware Button Combo: Rapid double-tap of Next ↔ Prev within 1200ms on Bluetooth earbud/steering wheel controls toggles between Mode 1 and Mode 2.
- Shuffle Off: Play tracks in playlist order.
- Global Shuffle (Mode 1): Randomize across all loaded playlists with persistent history navigation.
- Playlist Shuffle (Mode 2): Randomize within the current playlist only.
- Repeat Off / All / One: Standard repeat cycle modes.
- Bypass Service Worker (
?bypass=true): Direct streaming to page memory andCacheStorage(yt-player-media), eliminating duplicate buffering and out-of-memory crashes insw.js. - Complete Asset Ingestion: Downloads audio (
.webm), album thumbnails (.webpintoyt-player-thumbs), and lyrics (.lrcintoyt-player-media) unconditionally. - Exponential Backoff Retries: Up to 3 retries per asset (300ms, 600ms, 1200ms) to resolve network glitches and CDN rate limits.
- Post-Download Verification: Automatically verifies cache contents and performs a targeted recovery pass for missing tracks before finalizing status.
- Zero-GPU Progress Toast: High-contrast, flat notification with
contain: layout paint(0% GPU compositor cost, nobackdrop-filter).
- Dedicated Persistent Cache (
yt-player-databases): Service worker activation cleanup preserves database caches, preventing cache version bumps (v149->v150) from wiping offline catalogues. - Dual-Tier Persistent Storage: Combines Cache API with an IndexedDB mirror (
yt-player-offline-db), maintaining offline catalogue availability even if browser cache quotas undergo eviction. - Timeout Racing: Network fetches race against a 6.0s - 6.5s timeout, guaranteeing immediate fallback to cached data in dead zones or flaky network conditions.
- Startup Pre-Seeding: Background pre-seeding (
seedOfflineDatabases) populates in-memory databases from IndexedDB on startup, enabling instantaneous offline tab switches and cross-shuffle queue generation. - Actionable Offline Empty State: Uncached playlists in offline conditions display an explicit offline indicator with a Retry action rather than an indefinite loading state.
- Chrome/Edge: 80+
- Firefox: 78+
- Safari: 14+
- Mobile: iOS Safari 14+, Android Chrome 80+
The app works completely offline after downloading playlists.
Desktop playback uses native <audio>.volume control to maintain 0.0% GPU load. The AudioContext and Web Audio graphs are disabled on desktop to prevent Chromium's Direct3D compositor process from staying active.
Mobile uses Media Source Extensions (MSE) with a permanent <audio>.src bound to URL.createObjectURL(mediaSource). This approach keeps the Android lock screen notification pinned during track switches and prevents audio drops when changing tracks.
Every release is audited against simulated mobile slow 4G (1.6 Mbps / 150ms RTT):
| Metric | Target | Status |
|---|---|---|
| Performance Score | 95–100 | Passed |
| First Contentful Paint (FCP) | < 1.2s | Passed |
| Largest Contentful Paint (LCP) | < 2.3s | Passed |
| Total Blocking Time (TBT) | < 150ms | Passed |
| Cumulative Layout Shift (CLS) | 0.00 | Passed |
.
├── index.html # Main HTML layout and modal containers
├── manifest.json # PWA manifest
├── robots.txt # Crawler directives
├── sw.js # Service Worker caching & whitelist rules
├── css/
│ └── style.css # Application styles, zero-GPU rules, media queries
├── js/
│ ├── main.js # App entry point, gesture wiring, keyboard shortcuts
│ ├── playback.js # Playback queue, shuffle logic, offline download manager
│ ├── dom.js # DualAudioPingPong MSE player, audio engine
│ ├── mediaSession.js # MediaSession, live audio anchor, auto-kill watchdog
│ ├── ui.js # Virtual scroller (48px DOM recycling)
│ ├── lyrics.js # Synchronized LRC lyrics parser and auto-scroll
│ ├── state.js # State registry and settings persistence
│ └── utils.js # Fuzzy search, duration parser, URL generators
└── tests/
├── test_download_engine.py # Offline download & zero-GPU overlay tests
├── test_media_session_engine.py # Audio engine, honest-state, and watchdog tests
├── test_settings_state.py # State and persistence tests
├── test_settings_ui.py # UI wiring and shortcut tests
├── test_settings_markup.py # HTML validation and accessibility tests
└── test_settings_css.py # CSS rules and touch target tests
No build step is required. Open index.html in a modern browser (Chrome 80+, Safari 14+, Firefox 78+).
To run unit tests:
python -m unittest discover -s tests -p "test_*.py"See repository for license information.