From 06d5dac2f8467e49481059f01ff31b28dfe11776 Mon Sep 17 00:00:00 2001
From: Thales Pereira <31625914+thcp@users.noreply.github.com>
Date: Mon, 13 Jul 2026 16:52:38 +0100
Subject: [PATCH 1/3] feat(player): stream stems on desktop via the 5s-chunk
 engine (#261)

Desktop previously decoded every stem in full before playback (~420 MB / slow
preload). The Range-based chunked engine (chunkedAudioEngine.js) already streams
glitch-free on mobile: 5s HTTP-Range windows scheduled on AudioBufferSourceNodes,
first audio after ~1 chunk, ~28 MB RAM, no length cap. This promotes it to the
desktop player as the default, closing its three feature stubs so there's no
regression vs the full-decode engine:

- chunkedAudioEngine: implement setLoop (scheduler jumps to loop.start on
  crossing loop.end, and caps lookahead at loop.end); add a per-stem AnalyserNode
  (gain -> analyser -> master) + getAnalyser for live VU.
- player.js: engineMode() selects chunked by default; "fulldecode" and "0"
  (legacy <audio>) remain opt-in via the stemdeck.audioEngine flag. The RAM cap
  now only gates the full-decode engine. On the chunked path, drive lane
  mini-waves + the energy baseline from peaks.json and VU meters from the
  engine's live analysers (overview waveforms already come from peaks.json).
- mixer.js: renderRealMiniWaveFromPeaks (peaks-based lane mini-wave).

The original "buffering issue" was the N-<audio>-element multitrack path
(HTTP/1.1 6-connection-cap underruns on Safari/WKWebView); the chunked engine
avoids it by construction. Full-decode stays as a fallback.
---
 static/js/chunkedAudioEngine.js |  25 +++-
 static/js/mixer.js              |  35 +++++
 static/js/player.js             | 228 ++++++++++++++++++++++++++------
 3 files changed, 240 insertions(+), 48 deletions(-)

diff --git a/static/js/chunkedAudioEngine.js b/static/js/chunkedAudioEngine.js
index 7ae4b51c..6dc6aeb5 100644
--- a/static/js/chunkedAudioEngine.js
+++ b/static/js/chunkedAudioEngine.js
@@ -132,13 +132,18 @@ export function createChunkedAudioEngine(stems, { onTime, onEnded, context } = {
       })
     : Promise.resolve().then(() => { master.connect(ctx.destination); }));
 
-  // Per-stem state: url, parsed WAV header, gain node, currently playing nodes
+  // Per-stem state: url, parsed WAV header, gain node, analyser (VU tap), and
+  // currently playing nodes. Graph per stem: sources -> gain -> analyser -> master.
+  // The analyser sits post-gain so VU meters reflect volume/mute/solo.
   const stemMap = new Map();
   for (const s of stems) {
     if (!s?.url) continue;
     const gain = ctx.createGain();
-    gain.connect(master);
-    stemMap.set(s.name, { url: s.url, header: null, gain, activeNodes: [] });
+    const analyser = ctx.createAnalyser();
+    analyser.fftSize = 1024;
+    gain.connect(analyser);
+    analyser.connect(master);
+    stemMap.set(s.name, { url: s.url, header: null, gain, analyser, activeNodes: [] });
   }
 
   let _duration = 0;
@@ -156,6 +161,7 @@ export function createChunkedAudioEngine(stems, { onTime, onEnded, context } = {
   // getCurrentTime() from advancing during an async chunk fetch.
   let _audioStarted = false;
   let _filling = false; // prevents concurrent _scheduleNext() calls
+  let loop = { enabled: false, start: 0, end: 0 };
 
   // Chunk cache: chunkIdx -> { promise: Promise<Map>, result: Map|null }
   // result is set synchronously once the promise resolves so play() can
@@ -283,7 +289,10 @@ export function createChunkedAudioEngine(stems, { onTime, onEnded, context } = {
 
   function _maybeSchedule() {
     if (_filling || !playing || destroyed) return;
-    if (_scheduledTo >= _duration) return;
+    // While looping, don't schedule past loop.end — _tick jumps back to
+    // loop.start when the playhead crosses it (bounded by one rAF frame).
+    const limit = (loop.enabled && loop.end > loop.start) ? loop.end : _duration;
+    if (_scheduledTo >= limit) return;
     if (_scheduledTo - _getCurrentTime() < LOOKAHEAD_SEC) {
       _filling = true;
       _scheduleNext().finally(() => { _filling = false; });
@@ -293,6 +302,10 @@ export function createChunkedAudioEngine(stems, { onTime, onEnded, context } = {
   function _tick() {
     if (!playing) return;
     const t = _getCurrentTime();
+    if (loop.enabled && loop.end > loop.start && t >= loop.end) {
+      seek(loop.start); // re-arms playback + tick from the loop start
+      return;
+    }
     if (t >= _duration) {
       playing = false;
       _audioStarted = false;
@@ -408,7 +421,7 @@ export function createChunkedAudioEngine(stems, { onTime, onEnded, context } = {
     isPlaying: () => playing,
     getCurrentTime: _getCurrentTime,
     getDuration: () => _duration,
-    setLoop: () => {},
+    setLoop: (enabled, start, end) => { loop = { enabled, start, end }; },
     setGain(name, v) {
       const stem = stemMap.get(name);
       if (stem) stem.gain.gain.setTargetAtTime(Math.max(0, v), ctx.currentTime, 0.01);
@@ -427,7 +440,7 @@ export function createChunkedAudioEngine(stems, { onTime, onEnded, context } = {
         seek(t);
       }
     },
-    getAnalyser: () => null,
+    getAnalyser: (name) => stemMap.get(name)?.analyser ?? null,
     getBuffers: () => new Map(),
     destroy() {
       destroyed = true;
diff --git a/static/js/mixer.js b/static/js/mixer.js
index c12f376b..f3b373fb 100644
--- a/static/js/mixer.js
+++ b/static/js/mixer.js
@@ -241,6 +241,41 @@ export function renderRealMiniWave(stemName, audioBuffer, color) {
   }
 }
 
+// Peaks-based mini-wave for the streaming/chunked engine path, where no full
+// decoded buffer is available. `pts` is the backend peaks.json array for the
+// stem: [[min,max], ...] (1500 points). Mirrors renderRealMiniWave's bar layout.
+export function renderRealMiniWaveFromPeaks(stemName, pts, color) {
+  const svg = mixerEl.querySelector(`.lane-mini-wave[data-stem="${stemName}"]`);
+  if (!svg || !pts?.length) return;
+  const binSize = Math.max(1, Math.floor(pts.length / MINI_WAVE_BARS));
+  const peaks = new Array(MINI_WAVE_BARS);
+  let max = 0;
+  for (let i = 0; i < MINI_WAVE_BARS; i++) {
+    const start = i * binSize;
+    const end = i === MINI_WAVE_BARS - 1 ? pts.length : start + binSize;
+    let p = 0;
+    for (let j = start; j < end; j++) {
+      const v = Math.max(Math.abs(pts[j][0]), Math.abs(pts[j][1]));
+      if (v > p) p = v;
+    }
+    peaks[i] = p;
+    if (p > max) max = p;
+  }
+  const norm = max > 0 ? 1 / max : 0;
+  while (svg.firstChild) svg.removeChild(svg.firstChild);
+  for (let i = 0; i < MINI_WAVE_BARS; i++) {
+    const h = Math.max(1.5, peaks[i] * norm * MINI_WAVE_VIEWBOX_H);
+    const rect = document.createElementNS("http://www.w3.org/2000/svg", "rect");
+    rect.setAttribute("x", `${i * 2}`);
+    rect.setAttribute("y", `${(MINI_WAVE_VIEWBOX_H - h) / 2}`);
+    rect.setAttribute("width", "1");
+    rect.setAttribute("height", `${h}`);
+    rect.setAttribute("fill", color);
+    rect.setAttribute("opacity", "0.95");
+    svg.appendChild(rect);
+  }
+}
+
 function downloadIcon() {
   const svg = document.createElementNS("http://www.w3.org/2000/svg", "svg");
   svg.setAttribute("viewBox", "0 0 24 24");
diff --git a/static/js/player.js b/static/js/player.js
index 4407ee1c..5fe36675 100644
--- a/static/js/player.js
+++ b/static/js/player.js
@@ -19,10 +19,11 @@ import {
   setFooterWaveDrawFn,
 } from "./state.js";
 import { createAudioEngine, estimateDecodedBytes } from "./audioEngine.js";
+import { createChunkedAudioEngine } from "./chunkedAudioEngine.js";
 import {
   loadMixIntoState, resetMixerState, refreshMixerVisuals,
   setLaneControlsEnabled, ensureMixerStateDefaults, applyMix,
-  renderRealMiniWave, renderMixerRow,
+  renderRealMiniWave, renderRealMiniWaveFromPeaks, renderMixerRow,
 } from "./mixer.js";
 import {
   buildRuler, updatePlayheadMarker, updateLoopRegionVisual,
@@ -32,32 +33,34 @@ import {
 import { stopVuLoop } from "./audio.js";
 import { destroySections } from "./sections.js";
 
-// Feature flag for the Web Audio decode-and-mix engine (audioEngine.js).
-// Playback runs off decoded AudioBuffers on a single AudioContext clock instead
-// of N streaming <audio> elements — fixes Safari/WKWebView choppiness.
+// Playback-engine selection. All engines play decoded AudioBuffers off a single
+// AudioContext clock (no N streaming <audio> elements — that was the source of
+// Safari/WKWebView choppiness). Two Web Audio engines exist:
+//   - "chunked"    streams WAV in 5s HTTP-Range windows (chunkedAudioEngine.js):
+//                  first audio after ~1 chunk, ~28 MB RAM, no length cap. DEFAULT.
+//   - "fulldecode" decodes every stem up front (audioEngine.js): higher RAM and a
+//                  slow preload, but was the previous desktop default.
+// The multitrack stays mounted with null URLs as the visuals shell when an engine
+// owns playback, so the engine has exclusive HTTP access (the old Windows
+// connection-competition regression is avoided).
 //
-// Default ON everywhere. The prior Windows regression (waveform stuck, no audio)
-// was caused by connection competition: both the multitrack and the engine
-// fetched the same 6 stem WAVs concurrently, saturating the 6-connection
-// HTTP/1.1 limit on WebView2/WKWebView and stalling multitrack's blob fetches
-// so `canplay` never fired. Fixed by passing null URLs to the multitrack when
-// the engine is active (wireUpAudio), giving the engine exclusive HTTP access.
-// An explicit localStorage "stemdeck.audioEngine" = "0" forces the streaming
-// path; "1" forces the engine (useful for debugging).
-function audioEngineEnabled() {
+// localStorage "stemdeck.audioEngine": "0" = legacy streaming <audio> multitrack
+// (debug), "fulldecode" = full-decode engine, anything else / unset = chunked.
+function engineMode() {
   try {
     const pref = localStorage.getItem("stemdeck.audioEngine");
-    if (pref === "1") return true;
-    if (pref === "0") return false;
+    if (pref === "0") return "streaming";
+    if (pref === "fulldecode") return "fulldecode";
   } catch (e) {
     console.warn("[player] audioEngine flag read failed:", e);
   }
-  return true; // default ON — smooth audio everywhere
+  return "chunked"; // default — stream in 5s chunks, fast start, low RAM
 }
 
-// Above this estimated decoded-PCM size the engine is skipped and playback
-// falls back to streaming, so a long full-stem track can't exhaust WKWebView's
-// memory. ~1.2 GB ≈ 6 stems × ~10 min (or 4 stems × ~15 min) at 44.1 kHz/Float32.
+// Only the full-decode engine holds all PCM in RAM, so only it needs a size cap.
+// Above this estimated decoded-PCM size it falls back to streaming. The chunked
+// engine has no such cap (it never holds more than ~2 chunks). ~1.2 GB ≈ 6 stems
+// × ~10 min (or 4 stems × ~15 min) at 44.1 kHz/Float32.
 const MAX_ENGINE_DECODED_BYTES = 1.2e9;
 
 // Stem-selection filter: the import-page stem-choice toggles set
@@ -465,6 +468,39 @@ function renderStemEnergyBaseline(stems, decodedMap) {
   }
 }
 
+// Energy baseline for the streaming/chunked path, derived from peaks.json
+// instead of decoded PCM. Uses the RMS of each stem's bin peak-amplitudes as a
+// loudness proxy; all stems use the same measure and are normalized to the
+// loudest, so the relative balance ("drums dominate, piano quiet") is faithful
+// even though the absolute value differs from a true PCM RMS. Live playback
+// pulsing then comes from startAnalyserVuLoop.
+function renderStemEnergyBaselineFromPeaks(stems, peaks) {
+  const valByStem = new Map();
+  let maxV = 0;
+  for (const stem of stems) {
+    const pts = peaks[stem.name];
+    if (!pts?.length) continue;
+    let sum = 0;
+    for (const [mn, mx] of pts) {
+      const a = Math.max(Math.abs(mn), Math.abs(mx));
+      sum += a * a;
+    }
+    const v = Math.sqrt(sum / pts.length);
+    valByStem.set(stem.name, v);
+    if (v > maxV) maxV = v;
+  }
+  if (maxV <= 0) return;
+  for (const [name, v] of valByStem) {
+    const pct = Math.round((v / maxV) * 100);
+    const row = document.querySelector(`.energy-row[data-stem="${name}"]`);
+    if (!row) continue;
+    const bar = row.querySelector("b");
+    const txt = row.querySelector("em");
+    if (bar) bar.style.setProperty("--v", `${pct}%`);
+    if (txt) txt.textContent = `${pct}%`;
+  }
+}
+
 function buildStemVuEnvelope(audioBuffer) {
   if (!isAudioBufferLike(audioBuffer)) return [];
   const ch = audioBuffer.getChannelData(0);
@@ -576,6 +612,90 @@ function startStemVuLoop(stems, decodedMap, token) {
   stemVuRafId = requestAnimationFrame(tick);
 }
 
+// Real-time VU for the chunked/streaming path, driven by the engine's live
+// per-stem AnalyserNodes (post-gain, so volume/mute/solo are reflected in the
+// signal). Mirrors startStemVuLoop's peak-hold + CSS-var output; only the level
+// source differs (live RMS vs a precomputed envelope). stemVuGain gates to 0 for
+// an instant drop on mute/solo rather than waiting for the gain ramp.
+function startAnalyserVuLoop(stems, engine, token) {
+  stopStemVuLoop();
+  const meters = stems.map((stem) => {
+    const analyser = engine.getAnalyser?.(stem.name);
+    if (!analyser) return null;
+    return {
+      name: stem.name,
+      analyser,
+      data: new Uint8Array(analyser.fftSize),
+      miniMeterEl: document.querySelector(`.stem-list [data-stem="${stem.name}"] .mini-meter`),
+      vuEl: mixerEl.querySelector(`.lane-vu[data-stem="${stem.name}"]`),
+      peak: 0,
+      peakHold: 0,
+      holdFrames: 0,
+      lastPeakPct: -1,
+      lastHoldPct: -1,
+      lastLevelPct: -1,
+    };
+  }).filter((m) => m && (m.miniMeterEl || m.vuEl));
+
+  if (!meters.length) return;
+  const tick = () => {
+    if (token !== visualRenderToken || !multitrack) return;
+    const src = audioEngine ?? multitrack;
+    const playing = src.isPlaying?.() ?? false;
+    for (const m of meters) {
+      const gain = stemVuGain(m.name);
+      let input = 0;
+      if (playing && gain > 0) {
+        m.analyser.getByteTimeDomainData(m.data);
+        let sum = 0;
+        for (let i = 0; i < m.data.length; i++) {
+          const v = (m.data[i] - 128) / 128;
+          sum += v * v;
+        }
+        input = Math.min(1, Math.sqrt(sum / m.data.length) * 2.5);
+      } else {
+        m.peak = 0;
+        m.peakHold = 0;
+        m.holdFrames = 0;
+      }
+      const nextPeak = input > m.peak ? input : Math.max(0, m.peak - 0.018);
+      m.peak = nextPeak;
+
+      if (input > m.peakHold) {
+        m.peakHold = input;
+        m.holdFrames = 28;
+      } else if (m.holdFrames > 0) {
+        m.holdFrames -= 1;
+      } else {
+        m.peakHold = Math.max(0, m.peakHold - 0.025);
+      }
+
+      const lvlPct = Math.round(input * 100);
+      const peakPct = Math.round(nextPeak * 100);
+      const holdPct = Math.round(m.peakHold * 100);
+
+      if (m.miniMeterEl) {
+        if (peakPct !== m.lastPeakPct) {
+          m.miniMeterEl.style.setProperty("--vu-scale", nextPeak.toFixed(3));
+        }
+        if (holdPct !== m.lastHoldPct) {
+          m.miniMeterEl.style.setProperty("--vu-peak-pct", String(holdPct));
+          m.miniMeterEl.style.setProperty("--vu-peak-opacity", m.peakHold > 0.04 ? "1" : "0");
+        }
+      }
+      if (m.vuEl) {
+        if (lvlPct !== m.lastLevelPct) m.vuEl.style.setProperty("--vu-level", `${lvlPct}%`);
+        if (holdPct !== m.lastHoldPct) m.vuEl.style.setProperty("--vu-peak", `${holdPct}%`);
+      }
+      m.lastLevelPct = lvlPct;
+      m.lastPeakPct = peakPct;
+      m.lastHoldPct = holdPct;
+    }
+    stemVuRafId = requestAnimationFrame(tick);
+  };
+  stemVuRafId = requestAnimationFrame(tick);
+}
+
 export function destroyPlayer() {
   document.querySelector(".app")?.classList.remove("is-import");
   document.querySelector(".app")?.classList.remove("engine-waveforms");
@@ -880,9 +1000,13 @@ export function wireUpAudio(jobId, stems, duration, thumbnail, mixUrl = null, ti
   // the 6-connection HTTP/1.1 limit and `canplay` stalls (the WebView2/WKWebView
   // freeze). Null URLs make the multitrack's <audio> elements ready instantly.
   const engineStemCount = stems.filter((s) => s.url).length;
+  const mode = engineMode();
+  // Only the full-decode engine holds all PCM in RAM, so only it is size-capped;
+  // the chunked engine streams and is never "too large".
   const engineTooLarge =
+    mode === "fulldecode" &&
     estimateDecodedBytes(totalDuration, engineStemCount) > MAX_ENGINE_DECODED_BYTES;
-  const useEngine = audioEngineEnabled() && !engineTooLarge;
+  const useEngine = mode !== "streaming" && !engineTooLarge;
   // The null-URL multitrack (engine path) has no WaveSurfer canvas, so reveal the
   // SVG overview layer as the visible waveform (CSS hides it on the streaming path).
   document.querySelector(".app")?.classList.toggle("engine-waveforms", useEngine);
@@ -1083,45 +1207,65 @@ export function wireUpAudio(jobId, stems, duration, thumbnail, mixUrl = null, ti
         updateStopVisual();
       };
       if (audioEngine) { audioEngine.destroy(); setAudioEngine(null); }
-      const eng = createAudioEngine(stems, {
-        onTime: driveTransportUi,
-        onEnded: () => { playBtn.classList.remove("playing"); updateStopVisual(); },
-      });
+      const onEnded = () => { playBtn.classList.remove("playing"); updateStopVisual(); };
+      // Default: chunked streaming engine (fast start, low RAM). "fulldecode"
+      // opts into the legacy decode-everything engine.
+      const eng = mode === "chunked"
+        ? createChunkedAudioEngine(stems, { onTime: driveTransportUi, onEnded })
+        : createAudioEngine(stems, { onTime: driveTransportUi, onEnded });
       setAudioEngine(eng);
       eng.ready.then((ok) => {
-        // Bail if the user switched tracks while we were decoding.
+        // Bail if the user switched tracks while we were initialising.
         if (token !== visualRenderToken || multitrack !== mt) {
           eng.destroy();
           if (audioEngine === eng) setAudioEngine(null);
           return;
         }
         if (!ok) {
-          // No decodable stems — fall back to the streaming path transparently.
-          console.warn("[player] audio engine had no decodable stems; using streaming path");
+          // No usable stems — drop the engine (null-URL multitrack stays mounted).
+          console.warn("[player] audio engine had no usable stems; playback disabled");
           eng.destroy();
           setAudioEngine(null);
           return;
         }
         eng.setLoop(loopEnabled, loopStart, loopEnd);
         applyMix(); // push per-stem gains (incl. >1.0 boost) into the engine
-        // Drive the decode-dependent visuals from the engine's own decoded
-        // buffers (the null-URL multitrack has none): overview waveforms (when
-        // no precomputed peaks), energy bars, VU envelopes, and lane mini-waves.
-        const decoded = eng.getBuffers();
-        if (!Object.keys(precomputedPeaks).length) {
-          clearOverviewWaveforms();
-          renderAllOverviewWaveforms(stems, decoded);
-        }
-        renderStemEnergyBaseline(stems, decoded);
-        startStemVuLoop(stems, decoded, token);
-        for (const stem of stems) {
-          const buf = decoded.get(stem.name);
-          if (isAudioBufferLike(buf)) {
-            renderDecodedStemVisuals(stem.name, buf, STEM_COLORS[stem.name] || "#a0a0a0");
+        if (mode === "chunked") {
+          // Streaming path: the engine holds no full buffers. Overview waveforms
+          // come from peaks.json (rendered by the _peaksPromise handler above);
+          // drive lane mini-waves + the energy baseline from those same peaks,
+          // and the VU meters from the engine's live per-stem analysers.
+          _peaksPromise.then((peaks) => {
+            if (token !== visualRenderToken || multitrack !== mt) return;
+            const p = peaks || {};
+            for (const stem of stems) {
+              const pts = p[stem.name];
+              if (pts?.length) {
+                renderRealMiniWaveFromPeaks(stem.name, pts, STEM_COLORS[stem.name] || "#a0a0a0");
+              }
+            }
+            renderStemEnergyBaselineFromPeaks(stems, p);
+          });
+          startAnalyserVuLoop(stems, eng, token);
+        } else {
+          // Full-decode path: drive the decode-dependent visuals from the
+          // engine's own buffers (the null-URL multitrack has none).
+          const decoded = eng.getBuffers();
+          if (!Object.keys(precomputedPeaks).length) {
+            clearOverviewWaveforms();
+            renderAllOverviewWaveforms(stems, decoded);
+          }
+          renderStemEnergyBaseline(stems, decoded);
+          startStemVuLoop(stems, decoded, token);
+          for (const stem of stems) {
+            const buf = decoded.get(stem.name);
+            if (isAudioBufferLike(buf)) {
+              renderDecodedStemVisuals(stem.name, buf, STEM_COLORS[stem.name] || "#a0a0a0");
+            }
           }
         }
       }).catch((e) => {
-        console.warn("[player] audio engine init failed; using streaming path:", e);
+        console.warn("[player] audio engine init failed; playback disabled:", e);
         eng.destroy();
         if (audioEngine === eng) setAudioEngine(null);
       });

From 455fab85c3eefeb434f05947ce514534b9610586 Mon Sep 17 00:00:00 2001
From: Thales Pereira <31625914+thcp@users.noreply.github.com>
Date: Mon, 13 Jul 2026 17:17:42 +0100
Subject: [PATCH 2/3] fix(player): harden chunked streaming (loop cache
 pinning, retry, peaks fallback)

Self-review of the chunked-engine promotion found four gaps:

- Loop-start chunk was evicted as playback advanced, so every loop pass paid a
  refetch gap. Pin it against both eviction sites while a loop is active, and
  warm it as the playhead approaches loop.end (deduped by the chunk cache).
- A transient all-stems fetch failure cached an empty chunk forever, leaving
  playback permanently silent past that point. Drop empty results so the
  scheduler retries.
- Loop jumps scheduled with the cold-start 50 ms lead. Cached (sync) starts now
  use 10 ms, making loop wraps near-seamless; the async path keeps 50 ms.
- Legacy jobs without peaks.json lost all waveform visuals on the streaming
  path. The chunked branch now falls back to the full-decode engine in that
  case (honoring the backend's documented "degrades to client-side decode"
  contract), unless the track exceeds the decode RAM cap - then it keeps
  streaming audio with placeholder waveforms.
---
 static/js/chunkedAudioEngine.js |  42 +++++++---
 static/js/player.js             | 136 +++++++++++++++++++-------------
 2 files changed, 111 insertions(+), 67 deletions(-)

diff --git a/static/js/chunkedAudioEngine.js b/static/js/chunkedAudioEngine.js
index 6dc6aeb5..acfd3dbe 100644
--- a/static/js/chunkedAudioEngine.js
+++ b/static/js/chunkedAudioEngine.js
@@ -162,6 +162,10 @@ export function createChunkedAudioEngine(stems, { onTime, onEnded, context } = {
   let _audioStarted = false;
   let _filling = false; // prevents concurrent _scheduleNext() calls
   let loop = { enabled: false, start: 0, end: 0 };
+  // Chunk index that must survive cache eviction while looping (the loop-start
+  // chunk), so every pass around the loop replays from cache with no refetch.
+  const _loopPinChunk = () =>
+    (loop.enabled && loop.end > loop.start) ? Math.floor(loop.start / CHUNK_SEC) : -1;
 
   // Chunk cache: chunkIdx -> { promise: Promise<Map>, result: Map|null }
   // result is set synchronously once the promise resolves so play() can
@@ -218,9 +222,16 @@ export function createChunkedAudioEngine(stems, { onTime, onEnded, context } = {
       const map = new Map(pairs.filter(([, b]) => b));
       entry.result = map;
       // Keep at most the previous chunk + current in cache to bound memory.
+      // The loop-start chunk is pinned so loop passes replay from cache.
+      const pin = _loopPinChunk();
       for (const k of _cache.keys()) {
-        if (k < chunkIdx - 1) _cache.delete(k);
+        if (k < chunkIdx - 1 && k !== pin) _cache.delete(k);
       }
+      // An all-stems-empty result means every fetch failed (e.g. a transient
+      // network drop) — drop the entry so a later scheduler pass retries
+      // instead of caching permanent silence. Past-EOF chunks are never
+      // re-requested: _maybeSchedule stops at duration.
+      if (map.size === 0) _cache.delete(chunkIdx);
       return map;
     })();
 
@@ -302,9 +313,15 @@ export function createChunkedAudioEngine(stems, { onTime, onEnded, context } = {
   function _tick() {
     if (!playing) return;
     const t = _getCurrentTime();
-    if (loop.enabled && loop.end > loop.start && t >= loop.end) {
-      seek(loop.start); // re-arms playback + tick from the loop start
-      return;
+    if (loop.enabled && loop.end > loop.start) {
+      // Warm the loop-start chunk while approaching the end so the jump back
+      // schedules from cache instead of paying a fetch (deduped by _cache and
+      // pinned against eviction while the loop stays active).
+      if (loop.end - t < LOOKAHEAD_SEC) _fetchChunk(_loopPinChunk());
+      if (t >= loop.end) {
+        seek(loop.start); // re-arms playback + tick from the loop start
+        return;
+      }
     }
     if (t >= _duration) {
       playing = false;
@@ -330,9 +347,12 @@ export function createChunkedAudioEngine(stems, { onTime, onEnded, context } = {
     const chunkIdx = Math.floor(_startOffset / CHUNK_SEC);
     const offsetWithin = _startOffset - chunkIdx * CHUNK_SEC;
 
-    const startWith = (buffers) => {
+    // `lead` = scheduling safety margin. The cached (sync) path uses 10 ms —
+    // tight enough that loop jumps are near-seamless — while the async path
+    // keeps 50 ms headroom since a fetch/decode just finished.
+    const startWith = (buffers, lead) => {
       if (!playing || destroyed) return;
-      const when = ctx.currentTime + 0.05;
+      const when = ctx.currentTime + lead;
       _startCtxTime = when;
       const dur = _scheduleChunk(buffers, when, offsetWithin);
       _scheduledTo = _startOffset + dur;
@@ -344,10 +364,10 @@ export function createChunkedAudioEngine(stems, { onTime, onEnded, context } = {
     // chunk 0 is pre-decoded during ready(), so the sync path is the hot path.
     const hit = _cache.get(chunkIdx);
     if (hit?.result) {
-      startWith(hit.result);
+      startWith(hit.result, 0.01);
     } else {
       _fetchChunk(chunkIdx)
-        .then(startWith)
+        .then((buffers) => startWith(buffers, 0.05))
         .catch((e) => {
           console.warn("[chunked] play fetch failed:", e);
           playing = false;
@@ -377,10 +397,12 @@ export function createChunkedAudioEngine(stems, { onTime, onEnded, context } = {
     }
     _startOffset = clamped;
     _scheduledTo = clamped;
-    // Evict cache for chunks before the new position.
+    // Evict cache for chunks before the new position (except the pinned
+    // loop-start chunk — a loop jump seeks backward *to* that chunk).
     const newIdx = Math.floor(clamped / CHUNK_SEC);
+    const pin = _loopPinChunk();
     for (const k of _cache.keys()) {
-      if (k < newIdx) _cache.delete(k);
+      if (k < newIdx && k !== pin) _cache.delete(k);
     }
     onTime?.(clamped);
     if (wasPlaying) play();
diff --git a/static/js/player.js b/static/js/player.js
index 5fe36675..3ad0aa2a 100644
--- a/static/js/player.js
+++ b/static/js/player.js
@@ -1208,67 +1208,89 @@ export function wireUpAudio(jobId, stems, duration, thumbnail, mixUrl = null, ti
       };
       if (audioEngine) { audioEngine.destroy(); setAudioEngine(null); }
       const onEnded = () => { playBtn.classList.remove("playing"); updateStopVisual(); };
-      // Default: chunked streaming engine (fast start, low RAM). "fulldecode"
-      // opts into the legacy decode-everything engine.
-      const eng = mode === "chunked"
-        ? createChunkedAudioEngine(stems, { onTime: driveTransportUi, onEnded })
-        : createAudioEngine(stems, { onTime: driveTransportUi, onEnded });
-      setAudioEngine(eng);
-      eng.ready.then((ok) => {
-        // Bail if the user switched tracks while we were initialising.
-        if (token !== visualRenderToken || multitrack !== mt) {
-          eng.destroy();
-          if (audioEngine === eng) setAudioEngine(null);
-          return;
-        }
-        if (!ok) {
-          // No usable stems — drop the engine (null-URL multitrack stays mounted).
-          console.warn("[player] audio engine had no usable stems; playback disabled");
-          eng.destroy();
-          setAudioEngine(null);
-          return;
-        }
-        eng.setLoop(loopEnabled, loopStart, loopEnd);
-        applyMix(); // push per-stem gains (incl. >1.0 boost) into the engine
-        if (mode === "chunked") {
-          // Streaming path: the engine holds no full buffers. Overview waveforms
-          // come from peaks.json (rendered by the _peaksPromise handler above);
-          // drive lane mini-waves + the energy baseline from those same peaks,
-          // and the VU meters from the engine's live per-stem analysers.
-          _peaksPromise.then((peaks) => {
-            if (token !== visualRenderToken || multitrack !== mt) return;
-            const p = peaks || {};
-            for (const stem of stems) {
-              const pts = p[stem.name];
-              if (pts?.length) {
-                renderRealMiniWaveFromPeaks(stem.name, pts, STEM_COLORS[stem.name] || "#a0a0a0");
+      // Engine bring-up, callable twice: the chunked path falls back to
+      // "fulldecode" when peaks.json is missing (legacy jobs), because the
+      // backend's documented degradation for missing peaks is client-side
+      // decode — which only the full-decode engine can provide.
+      const startEngine = (kind) => {
+        const eng = kind === "chunked"
+          ? createChunkedAudioEngine(stems, { onTime: driveTransportUi, onEnded })
+          : createAudioEngine(stems, { onTime: driveTransportUi, onEnded });
+        setAudioEngine(eng);
+        eng.ready.then((ok) => {
+          // Bail if the user switched tracks while we were initialising.
+          if (token !== visualRenderToken || multitrack !== mt) {
+            eng.destroy();
+            if (audioEngine === eng) setAudioEngine(null);
+            return;
+          }
+          if (!ok) {
+            // No usable stems — drop the engine (null-URL multitrack stays mounted).
+            console.warn("[player] audio engine had no usable stems; playback disabled");
+            eng.destroy();
+            setAudioEngine(null);
+            return;
+          }
+          eng.setLoop(loopEnabled, loopStart, loopEnd);
+          applyMix(); // push per-stem gains (incl. >1.0 boost) into the engine
+          if (kind === "chunked") {
+            // Streaming path: the engine holds no full buffers. Overview waveforms
+            // come from peaks.json (rendered by the _peaksPromise handler above);
+            // drive lane mini-waves + the energy baseline from those same peaks,
+            // and the VU meters from the engine's live per-stem analysers.
+            _peaksPromise.then((peaks) => {
+              if (token !== visualRenderToken || multitrack !== mt || audioEngine !== eng) return;
+              const p = peaks || {};
+              if (!Object.keys(p).length) {
+                // Legacy job with no peaks.json: no waveform source on the
+                // streaming path. Swap to the full-decode engine (unless the
+                // track is too big to decode in RAM — then keep streaming
+                // audio and accept placeholder waveforms).
+                if (estimateDecodedBytes(totalDuration, engineStemCount) <= MAX_ENGINE_DECODED_BYTES) {
+                  console.warn("[player] no peaks.json; using full-decode engine for visuals");
+                  eng.destroy();
+                  if (audioEngine === eng) setAudioEngine(null);
+                  startEngine("fulldecode");
+                } else {
+                  console.warn("[player] no peaks.json and track too large to decode; waveforms unavailable");
+                }
+                return;
+              }
+              for (const stem of stems) {
+                const pts = p[stem.name];
+                if (pts?.length) {
+                  renderRealMiniWaveFromPeaks(stem.name, pts, STEM_COLORS[stem.name] || "#a0a0a0");
+                }
               }
+              renderStemEnergyBaselineFromPeaks(stems, p);
+            });
+            startAnalyserVuLoop(stems, eng, token);
+          } else {
+            // Full-decode path: drive the decode-dependent visuals from the
+            // engine's own buffers (the null-URL multitrack has none).
+            const decoded = eng.getBuffers();
+            if (!Object.keys(precomputedPeaks).length) {
+              clearOverviewWaveforms();
+              renderAllOverviewWaveforms(stems, decoded);
             }
-            renderStemEnergyBaselineFromPeaks(stems, p);
-          });
-          startAnalyserVuLoop(stems, eng, token);
-        } else {
-          // Full-decode path: drive the decode-dependent visuals from the
-          // engine's own buffers (the null-URL multitrack has none).
-          const decoded = eng.getBuffers();
-          if (!Object.keys(precomputedPeaks).length) {
-            clearOverviewWaveforms();
-            renderAllOverviewWaveforms(stems, decoded);
-          }
-          renderStemEnergyBaseline(stems, decoded);
-          startStemVuLoop(stems, decoded, token);
-          for (const stem of stems) {
-            const buf = decoded.get(stem.name);
-            if (isAudioBufferLike(buf)) {
-              renderDecodedStemVisuals(stem.name, buf, STEM_COLORS[stem.name] || "#a0a0a0");
+            renderStemEnergyBaseline(stems, decoded);
+            startStemVuLoop(stems, decoded, token);
+            for (const stem of stems) {
+              const buf = decoded.get(stem.name);
+              if (isAudioBufferLike(buf)) {
+                renderDecodedStemVisuals(stem.name, buf, STEM_COLORS[stem.name] || "#a0a0a0");
+              }
             }
           }
-        }
-      }).catch((e) => {
-        console.warn("[player] audio engine init failed; playback disabled:", e);
-        eng.destroy();
-        if (audioEngine === eng) setAudioEngine(null);
-      });
+        }).catch((e) => {
+          console.warn("[player] audio engine init failed; playback disabled:", e);
+          eng.destroy();
+          if (audioEngine === eng) setAudioEngine(null);
+        });
+      };
+      // Default: chunked streaming engine (fast start, low RAM). "fulldecode"
+      // opts into the legacy decode-everything engine.
+      startEngine(mode === "chunked" ? "chunked" : "fulldecode");
     }
   });
 }

From a47cc69bcf6be0f7058d37cea5805604d7ca6297 Mon Sep 17 00:00:00 2001
From: Thales Pereira <31625914+thcp@users.noreply.github.com>
Date: Mon, 13 Jul 2026 17:59:44 +0100
Subject: [PATCH 3/3] ci(deps-audit): ignore torch PYSEC-2026-2286 (torch.load
 ACE, no adoptable fix)

pip-audit newly flags torch 2.6.0 for PYSEC-2026-2286 (torch.load weights_only
deserialization -> arbitrary code execution, HIGH; fixed in 2.10.0). The exploit
requires an attacker-controlled .pth checkpoint. StemDeck never calls torch.load
on untrusted input: demucs loads only its official model weights from the
trusted torch-hub source, and users submit audio, not checkpoints. torch is
pinned <2.7 (torchaudio 2.7+ dropped the writer demucs needs), so 2.10.0 is not
adoptable yet. Documented alongside the existing ignored torch advisories.
---
 .github/workflows/ci.yml | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 435fc626..62871373 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -75,6 +75,13 @@ jobs:
       # local-only, single-user app is negligible. Re-evaluate once demucs
       # supports torch 2.7+ without torchcodec.
       #
+      # torch PYSEC-2026-2286 (torch.load weights_only deserialization -> ACE,
+      # HIGH; fix 2.10.0) -- the exploit needs an attacker-controlled .pth.
+      # StemDeck never calls torch.load on untrusted input: demucs loads only its
+      # official model weights from the trusted torch-hub source, and users
+      # submit audio, not checkpoints. The same <2.7 pin blocks the 2.10.0 fix;
+      # re-evaluate with the torch upgrade noted above.
+      #
       # joblib PYSEC-2024-277 -- no fix version available as of 2026-05-21
       # (1.5.3 is latest). joblib is a transitive dep via demucs/librosa;
       # StemDeck does not directly invoke joblib serialization. Drop once
@@ -105,6 +112,7 @@ jobs:
             --ignore-vuln PYSEC-2025-209 \
             --ignore-vuln PYSEC-2025-210 \
             --ignore-vuln PYSEC-2026-139 \
+            --ignore-vuln PYSEC-2026-2286 \
             --ignore-vuln PYSEC-2024-277 \
             --ignore-vuln CVE-2025-2148 \
             --ignore-vuln CVE-2025-2149 \