docs: record desktop media-tile flicker as a known limitation

The two-element gapless handoff was reverted (switching <audio> elements
still ends/starts the OS media session, so Windows rebuilds the tile).
Correct the changelog claim and add a Known Bugs entry; the real fix is MSE.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

CHANGELOG.md

@@ -74,7 +74,7 @@ Versioning: two-part `MAJOR.MINOR` — each release bumps the minor (features an
 - **Android** — Offline detail screen flashed open then immediately returned: its initial empty state (before Room emitted) was mistaken for "deleted". Now shows a brief spinner until loaded, and only leaves when the last song is actually removed
 - **Android** — Lyrics autoscroll: rewrote centering to use the active line's *measured* position in a `LazyColumn` instead of a fixed line-height estimate. Eliminates the stutter and the downward drift on wrapped (multi-line) lyrics — the active line now tracks smoothly and sits at a natural ~40 %-from-top reading anchor
 - **Web** — Home now refreshes on an explicit Home click (matching Android): the album rows re-fetch and the random row re-randomizes instead of serving the 5-minute cache. Back/forward navigation still keeps the cached state
-- **Web (PWA)** — OS media tile no longer disappears/reappears when skipping tracks on desktop. Two fixes: (1) the Media Session metadata is mutated in place instead of replaced with a new `MediaMetadata` each track, and (2) gapless handoff — playback is handed to a second, pre-buffered `<audio>` element on skip so the active element never empties (the source-swap gap is what made Windows hide the tile). Falls back to the classic source swap when the next track isn't preloaded
+- **Web (PWA)** — Media Session metadata is now mutated in place instead of replaced with a new `MediaMetadata` each track (reduces churn). Note: this alone does not stop the Windows media tile from briefly closing/reopening on skip — see Known Bugs
 
 ### Internal
 - **Android** — Offline system: `Room` DB (`novasonic_offline.db`) with `downloaded_tracks`, `download_groups`, `group_track_cross_refs`; `OfflineRepository` holds hot `StateFlow` maps for O(1) local-path lookups; `DownloadWorker` streams audio + cover art via `HttpURLConnection` to `context.filesDir/offline/{audio|covers}/`. `MusicRepository.streamUrl()` checks local files first, so playback uses the `file://` URI on every entry point
@@ -309,6 +309,7 @@ Primary causes identified:
 - **Web + Android** — yt-dlp backend update / maintenance
 
 ### Known Bugs
+- **Web (PWA, desktop)** — The Windows media tile (SMTC) briefly closes and reopens when skipping tracks. Swapping the `<audio>` element's source leaves a momentary gap with no active media output, so Windows tears down and rebuilds the tile. A real fix needs one continuous source (MSE), which requires streaming an MSE-compatible format. The native Android app is unaffected. (A two-element gapless handoff was tried and reverted — switching elements still ends/starts the OS session.)
 - **Backend (download)** — The duplicate check requires at least a `firstArtist` folder match. If the same song was previously stored under a very different artist name (e.g. before an iTunes-name fix), it will not be detected as a duplicate and will be re-downloaded.
 - **Backend (metadata/sorting)** — MusicBrainz `release['artist-credit']` is often absent in the standard recording search response (requires `inc=artist-credits` which can slow the endpoint). The albumArtist field from MusicBrainz autofill may fall back to the recording artist rather than the release artist.
 - **Backend (metadata/sorting)** — MBIDs are not embedded in downloaded tracks; Navidrome cannot use them for authoritative album grouping (low priority — album splitting is mostly solved via consistent `album_artist`). 

index.html

@@ -742,7 +742,6 @@
 
 <div class="toast-container" id="toast-container"></div>
 <audio id="audio-element" preload="auto" playsinline crossorigin="anonymous"></audio>
-<audio id="audio-element-b" preload="auto" playsinline crossorigin="anonymous"></audio>
 <audio id="preview-audio"></audio>
 <audio id="abs-audio"></audio>
 

src/main.js

@@ -122,9 +122,6 @@ window.addEventListener('load', () => {
 
   // Wire up audio elements from DOM
   S.audio        = document.getElementById('audio-element');
-  const _audioB  = document.getElementById('audio-element-b');
-  // Two fixed audio elements for gapless handoff — S.audio always points at the active one.
-  S._audioEls    = _audioB ? [S.audio, _audioB] : [S.audio];
   S.previewAudio = document.getElementById('preview-audio');
 
   const saved = localStorage.getItem('ns_cfg');
@@ -137,13 +134,9 @@ window.addEventListener('load', () => {
   if(window.NS_SERVER_URL?.trim()) { const el=document.getElementById('srv-url'); if(el&&!el.value) el.value=window.NS_SERVER_URL.trim(); }
 
   document.getElementById('srv-pass').addEventListener('keydown', e => { if(e.key==='Enter') doConnect(); });
-  // Listeners are bound to BOTH audio elements so a gapless handoff needs no rebinding.
-  // Handlers that only make sense for the playing element guard with `el !== S.audio`.
-  let _errRetries = 0, _errTimer = null;
-  function bindAudioEl(el) {
-    el.addEventListener('timeupdate', updateProgress);
-    el.addEventListener('ended', onEnded);
-    el.addEventListener('play', () => {
+  S.audio.addEventListener('timeupdate', updateProgress);
+  S.audio.addEventListener('ended', onEnded);
+  S.audio.addEventListener('play', () => {
     S._trackChanging = false;
     absInterrupt();
     if (S.previewCurrent) stopPreview(false);
@@ -151,17 +144,20 @@ window.addEventListener('load', () => {
     document.getElementById('player-art').classList.add('spinning');
     if(navigator.mediaSession) navigator.mediaSession.playbackState = 'playing';
   });
-    el.addEventListener('pause', () => {
-      if (el !== S.audio) return;   // ignore the idle standby element during a handoff
+  S.audio.addEventListener('pause', () => {
     setPlayIcon(false);
     document.getElementById('player-art').classList.remove('spinning');
     // Suppress during track change — src swap fires pause before the new track starts
     if(!S._trackChanging && navigator.mediaSession) navigator.mediaSession.playbackState = 'paused';
   });
+  S.previewAudio.addEventListener('timeupdate', updatePreviewProgress);
+  S.previewAudio.addEventListener('ended', stopPreview);
+
   // stalled = browser buffer ran out briefly; let the browser retry naturally.
-    el.addEventListener('play', () => { _errRetries = 0; clearTimeout(_errTimer); }, { capture: true });
-    el.addEventListener('error', () => {
-      if (el !== S.audio) return;   // standby/preload errors must not disrupt active playback
+  // The watchdog below catches genuine long freezes.
+  let _errRetries = 0, _errTimer = null;
+  S.audio.addEventListener('play', () => { _errRetries = 0; clearTimeout(_errTimer); }, { capture: true });
+  S.audio.addEventListener('error', () => {
     // Skip if playCurrent() is already handling recovery (_trackChanging = true means
     // we're mid-transition or waiting for canplay — don't conflict with that)
     if(!S.queue[S.qIdx] || S._trackChanging) return;
@@ -175,11 +171,6 @@ window.addEventListener('load', () => {
       S.audio.play().catch(() => { S._trackChanging = false; });
     }, delay);
   });
-  }
-  S._audioEls.forEach(bindAudioEl);
-
-  S.previewAudio.addEventListener('timeupdate', updatePreviewProgress);
-  S.previewAudio.addEventListener('ended', stopPreview);
 
   const _savedVol = parseInt(localStorage.getItem('ns_volume') ?? '', 10);
   setVolume(isNaN(_savedVol) ? 55 : _savedVol);

src/player/player.js

@@ -276,19 +276,10 @@ function _setAudioSession() {
   try { if(navigator.audioSession) navigator.audioSession.type = 'playback'; } catch {}
 }
 
-// ─── PRELOAD — the standby audio element buffers the next track ──────────────
-// Buffering into the *standby* element (not a throwaway) lets playCurrent() hand
-// playback over to it gaplessly: the active element never empties, so the OS media
-// tile doesn't flicker on skip. Falls back to a source-swap when not preloaded.
+// ─── PRELOAD — shadow Audio element actually buffers the next track ──────────
 let _preUrl   = '';
 let _preId    = '';
-
-/** The audio element that is NOT currently active (or null if there's only one). */
-function _standbyEl() {
-  const els = S._audioEls;
-  if (!els || els.length < 2) return null;
-  return els.find(e => e !== S.audio) || null;
-}
+let _preAudio = null;
 
 function _nextIdx() {
   if(S.repeat === 'one') return S.qIdx;
@@ -303,12 +294,13 @@ function _preloadNext() {
   if(ni < 0) return;
   const next = S.queue[ni];
   if(!next || _preId === next.id) return;
-  const standby = _standbyEl();
-  if(!standby) return;
   _preId  = next.id;
   _preUrl = streamUrl(next.id);
-  standby.src = _preUrl;          // preload="auto" → the element buffers it for a gapless handoff
-  try { standby.load(); } catch {}
+  // Real Audio preload — actually buffers the stream so canplay fires instantly
+  if(_preAudio) { _preAudio.src = ''; _preAudio = null; }
+  _preAudio = new Audio();
+  _preAudio.preload = 'auto';
+  _preAudio.src = _preUrl;
   if(next.coverArt) {
     [256, 512, 1024].forEach(size => {
       const img = new Image();
@@ -319,8 +311,7 @@ function _preloadNext() {
 
 function _clearPreload() {
   _preId = ''; _preUrl = '';
-  const standby = _standbyEl();
-  if(standby) { try { standby.pause(); standby.removeAttribute('src'); standby.load(); } catch {} }
+  if(_preAudio) { _preAudio.src = ''; _preAudio = null; }
 }
 
 // ─── PLAY HISTORY (for prev-in-shuffle) ──────────────────────────────────────
@@ -406,6 +397,10 @@ export function playCurrent() {
   renderQueue();
   _scheduleScrobble(s.id, s.duration);
 
+  const src = (_preId === s.id && _preUrl) ? _preUrl : streamUrl(s.id);
+  _clearPreload();
+  S.audio.src = src;
+
   const _resetFlag = () => { if (_playGen === gen) S._trackChanging = false; };
 
   const _applySession = () => {
@@ -414,35 +409,6 @@ export function playCurrent() {
     setTimeout(_preloadNext, 2000);
   };
 
-  // ── Gapless handoff: if the standby element already buffered THIS track, switch
-  // playback to it instead of reloading the source. The active element never empties,
-  // so the OS media tile stays put (and the skip is instant). ──
-  const standby = _standbyEl();
-  if (standby && _preId === s.id && standby.readyState >= 2) {
-    const old = S.audio;
-    standby.currentTime = 0;
-    standby.volume = old.volume; standby.muted = old.muted; standby.playbackRate = old.playbackRate || 1;
-    S.audio = standby;                 // the active element is now the preloaded one
-    _preId = ''; _preUrl = '';
-    try { old.pause(); } catch {}      // 'pause' is ignored for the now-inactive element
-    _setAudioSession();
-    S.audio.play()
-      .then(() => { S._trackChanging = false; _applySession(); })
-      .catch(() => {
-        // Handoff playback failed — recover with a fresh source load on this element.
-        if (_playGen !== gen) return;
-        S.audio.src = streamUrl(s.id);
-        try { S.audio.load(); } catch {}
-        S.audio.play().then(() => { S._trackChanging = false; _applySession(); }).catch(_resetFlag);
-      });
-    return;
-  }
-
-  // ── Fallback: classic source swap on the current element (unchanged) ──
-  const src = (_preId === s.id && _preUrl) ? _preUrl : streamUrl(s.id);
-  _clearPreload();
-  S.audio.src = src;
-
   let _guardTimer = null;
   let _canplayFn  = null;