Skip to main content

PWA (installable radio player)

The primary radio player is an installable Progressive Web App served statically by the Go server (:8093) at api.mediahubnetwork.net (source html/index.html on the production node). It plays the HLS stream with OGG fallback, shows an artist backdrop, supports push notifications, works offline, and adds live chat + listener presence on top.

What it is​

A single-page player (client-side JS + hls.js) that:

  • Loads the HLS stream with hls.js 1.5.15 (fallback: native HLS on iOS, then the OGG master files.mediahubnetwork.net/main if HLS auth fails).
  • Counts listeners from HTTPS https://api.mediahubnetwork.net/v3/paths/list (the Go server forwards /v3/* to the read-only MediaMTX listener proxy :19353), polled by a race-guarded pollListeners() every 5s with an Icecast STATUS_URL fallback; metadata polled by a guarded pollMetadata().
  • Renders now-playing from the engine proxy (/api/next, /api/status, /api/station/state, /api/content/status, push registration via /api/push/register — all forwarded to the control plane http://10.40.3.174:5000).
  • Paints a large artist-image backdrop (fetchBackdrop(artist, title)) that dims over the page at ~20% opacity.
  • Uses an inline SVG favicon (no extra request).
  • Registers a service worker for installability + offline shell, and web-push for notifications (VAPID_KEY filled from server.js).
  • Live chat + presence: stacked avatars in the header LIVE badge (max 5 + +N), a "Sara and 3 others" presence line, auto-rejoin via localStorage (loklok.chatName/loklok.chatToken), history poll 4s / presence 10s / heartbeat 30s, 120-msg DOM cap, and a #chatOff offline fallback. The chat itself is served by the long-poll companion chat-server.js:8094 (see Chat server).

PWA assets (served alongside the page)​

AssetPurpose
manifest.jsonInstall manifest: name "LOKLOK", icons, start URL /
sw.jsService worker — cache shell, offline handling, push listener
icons/App icons (e.g. path848.png)
offline.htmlOffline fallback page

Service worker behaviour​

  • Install: pre-caches the player shell (page, CSS, JS, icons).
  • Fetch: serves cached assets first (offline-capable), falling back to the network and populating the cache.
  • Push: listens for push events → shows a notification (web-push path from Notifications).
  • Activate: cleans old cache versions when a new service worker activates.

Bumping the cache version​

When the app shell changes, bump the service worker's cache name so clients download the new shell instead of serving stale files. The old caches are purged automatically on activation.

Install flow​

  1. Visit https://api.mediahubnetwork.net/ on a supporting browser.
  2. The page registers sw.js and the manifest is detected.
  3. Users can Add to Home Screen / install for a native-like app.

Offline behaviour​

The player shell is pre-cached, so the app opens offline; live audio obviously needs the network. Offline mode shows the cached shell until the socket and stream reconnect.