framefields 2.11.0 → 2.13.0

package/dist/{preview-BToKUTtZ.mjs → preview-PDz7o2xg.mjs}

@@ -1,5 +1,7 @@
-import { t as encodeStereoWav } from "./audio-KHBadECb.mjs";
-import { s as HeadlessMediaRenderer } from "./renderer-Bbxh4N8Y.mjs";
+import { z as inputStore } from "./dist-D3BeAZ7X.mjs";
+import { t as encodeStereoWav } from "./audio-DS9Jg2ls.mjs";
+import { s as HeadlessMediaRenderer } from "./renderer-S9tVGneU.mjs";
+import { h as openAssetLocator } from "./dist-CiTgmfUw.mjs";
 import { createRequire, isBuiltin } from "node:module";
 import fs from "node:fs";
 import path from "node:path";
@@ -154,9 +156,10 @@ async function bundleProject(options) {
 					namespace: "framefields-preview"
 				}, () => ({
 					contents: [
-						`import { startPlayer } from ${JSON.stringify(`${ENGINE_URL}/player.mjs`)};`,
+						`import { startAudioMixer, startPlayer } from ${JSON.stringify(`${ENGINE_URL}/player.mjs`)};`,
 						`import * as mod from ${JSON.stringify(entry)};`,
-						`startPlayer(mod, ${JSON.stringify(options.exportName)}, ${JSON.stringify(settings)});`
+						`if (typeof document === "undefined") startAudioMixer(mod, ${JSON.stringify(options.exportName)});`,
+						`else startPlayer(mod, ${JSON.stringify(options.exportName)}, ${JSON.stringify(settings)});`
 					].join("\n"),
 					resolveDir: path.dirname(entry),
 					loader: "js"
@@ -880,7 +883,7 @@ const previewPage = `<!doctype html>
   }
 
   // ── Audio ──
-  var audio = { state: "mixing", error: "", buffer: null, peaks: null, ctx: null, gain: null, src: null, muted: false, volume: 0.9 };
+  var audio = { mode: "browser", state: "mixing", error: "", buffer: null, peaks: null, ctx: null, gain: null, src: null, muted: false, volume: 0.9 };
   var AUDIO_LABEL = { mixing: "Mixing audio", loading: "Loading audio", ready: "Audio ready", none: "No audio", error: "Audio failed" };
   var offline = false;
 
@@ -901,26 +904,252 @@ const previewPage = `<!doctype html>
     ws.replaceChildren();
     if (busy) ws.append(el("span", "spinner"));
     ws.append(document.createTextNode(state === "none" ? "No audio in this composition" : state === "error" ? "Audio could not be mixed" : AUDIO_LABEL[state]));
-    var usable = state === "ready" && !!audio.buffer;
+    var usable = state === "ready" && (!!audio.buffer || !!stream);
     $("mute").disabled = !usable;
     $("volume").disabled = !usable;
     renderChip();
     drawWave();
   }
+  function ensureAudioContext() {
+    if (audio.ctx) return;
+    var Ctx = window.AudioContext || window.webkitAudioContext;
+    audio.ctx = new Ctx();
+    audio.gain = audio.ctx.createGain();
+    audio.gain.connect(audio.ctx.destination);
+    applyVolume();
+  }
+  // ── Soundtrack, streamed. The page mixes it with the export's mixer in
+  // BLOCK_SEC blocks: the ones at the playhead first, as it plays, the rest
+  // in the background (which draws the waveform and finds the film's loudest
+  // sample for the master gain). Blocks play back to back on the
+  // AudioContext clock. Sources stream straight from where they live, pinned
+  // assets from their bucket. The mixing runs in a worker with its own GPU
+  // device, so it never holds up drawing; if the worker can't, the page mixes,
+  // and if that fails too, the server does. ──
+  var BLOCK_SEC = 2, AHEAD_SEC = 4, KEEP_BLOCKS = 64, PEAK_BINS = 1200, SILENT = 0.001;
+  var stream = null, playback = null;
+  function filmSec() { return meta.frameCount / meta.fps; }
+  // The project's bundle, loaded as a worker, runs the mixer instead of a player.
+  function mixerWorker() {
+    var worker;
+    try { worker = new Worker("/@framefields/player.js", { type: "module" }); } catch (e) { return null; }
+    var calls = new Map(), next = 0, failed = null;
+    var fail = function (err) {
+      failed = failed || err;
+      calls.forEach(function (c) { c.reject(failed); });
+      calls.clear();
+    };
+    var ready = new Promise(function (resolve, reject) {
+      worker.onmessage = function (e) {
+        var d = e.data;
+        if ("ready" in d) { if (d.ready) resolve(); else { reject(new Error(d.error)); fail(new Error(d.error)); } return; }
+        var call = calls.get(d.id);
+        if (!call) return;
+        calls.delete(d.id);
+        if (d.error) call.reject(new Error(d.error)); else call.resolve(d.mix);
+      };
+      worker.onerror = function (e) {
+        var err = new Error(e.message || "the mixing worker failed");
+        reject(err);
+        fail(err);
+      };
+    });
+    return {
+      mix: function (range, chain) {
+        return ready.then(function () {
+          if (failed) throw failed;
+          return new Promise(function (resolve, reject) {
+            var id = ++next;
+            calls.set(id, { resolve: resolve, reject: reject });
+            worker.postMessage({ id: id, range: range, chain: chain });
+          });
+        });
+      },
+      stop: function () { worker.terminate(); fail(new Error("stopped")); }
+    };
+  }
+  function beginStream(p) {
+    if (stream && stream.worker) stream.worker.stop();
+    stopClock();
+    audio.buffer = null;
+    audio.peaks = new Array(PEAK_BINS).fill(0);
+    stream = { player: p, worker: mixerWorker(), blocks: new Map(), order: [], pending: new Map(), queue: [], busy: false,
+      seen: new Set(), peak: 0, gain: 1, fill: 0, filling: false, total: Math.max(1, Math.ceil(filmSec() / BLOCK_SEC)) };
+    ensureAudioContext();
+    setAudioStatus("mixing");
+    var s = stream;
+    streamBlock(s, Math.floor(frame / meta.fps / BLOCK_SEC), true).then(function () {
+      if (stream === s && audio.state === "mixing") setAudioStatus("ready");
+    }, function () {});
+  }
+  // Blocks mix on two chains, each continuing its own effect state from the
+  // block before: "fill" runs through the film from its start, so its blocks
+  // are exactly the export's; "play" starts at a seek with a lead-in and
+  // carries on from there. An exact block is never replaced by a lead-in one.
+  function streamBlock(s, i, urgent) {
+    var have = s.blocks.get(i);
+    if (have) return Promise.resolve(have);
+    var waiting = s.pending.get(i);
+    if (waiting) {
+      if (urgent) promote(s, i);
+      return waiting;
+    }
+    waiting = enqueue(s, i, i === s.fill ? "fill" : "play", urgent, true);
+    pumpStream(s);
+    return waiting;
+  }
+  function enqueue(s, i, chain, urgent, own) {
+    if (chain === "fill") s.filling = true;
+    var waiting = new Promise(function (resolve, reject) {
+      var job = { i: i, chain: chain, own: own, resolve: resolve, reject: reject };
+      if (urgent) s.queue.unshift(job); else s.queue.push(job);
+    });
+    if (own) s.pending.set(i, waiting);
+    else waiting.catch(function () {});
+    return waiting;
+  }
+  function promote(s, i) {
+    var at = s.queue.findIndex(function (j) { return j.i === i; });
+    if (at > 0) s.queue.unshift(s.queue.splice(at, 1)[0]);
+  }
+  function pumpStream(s) {
+    if (s.busy || stream !== s) return;
+    if (!s.queue.length) { fillStream(s); if (!s.queue.length) return; }
+    s.busy = true;
+    var job = s.queue.shift();
+    var range = { startSec: job.i * BLOCK_SEC, endSec: Math.min(filmSec(), (job.i + 1) * BLOCK_SEC) };
+    mixBlock(s, range, job.chain).then(function (mix) {
+      if (stream === s) keepBlock(s, job.i, { left: mix.left, right: mix.right, sampleRate: mix.sampleRate, exact: mix.exact }, mix.peak);
+      if (job.chain === "fill") { s.fill = job.i + 1; s.filling = false; }
+      job.resolve(s.blocks.get(job.i));
+    }, function (err) {
+      if (job.chain === "fill") s.filling = false;
+      job.reject(err);
+      streamFailed(s, err);
+    }).then(function () {
+      if (job.own) s.pending.delete(job.i);
+      s.busy = false;
+      pumpStream(s);
+    });
+  }
+  // In the worker; on the page itself once the worker has failed.
+  function mixBlock(s, range, chain) {
+    if (!s.worker) return s.player.mixAudio(range, chain);
+    return s.worker.mix(range, chain).catch(function (err) {
+      if (s.worker) {
+        console.warn("The soundtrack's mixing worker failed, so the page mixes it:", err);
+        s.worker.stop();
+        s.worker = null;
+      }
+      return s.player.mixAudio(range, chain);
+    });
+  }
+  // Idle: the fill chain mixes its next block, every block in order, so
+  // its effect state runs on unbroken from the film's start.
+  function fillStream(s) {
+    if (s.filling || s.fill >= s.total) return;
+    enqueue(s, s.fill, "fill", false, !s.pending.has(s.fill));
+  }
+  function keepBlock(s, i, block, peak) {
+    var had = s.blocks.get(i);
+    if (!had || !had.exact || block.exact) {
+      s.blocks.set(i, block);
+      s.order.push(i);
+      while (s.order.length > KEEP_BLOCKS) s.blocks.delete(s.order.shift());
+    }
+    if (s.seen.has(i)) return;
+    s.seen.add(i);
+    s.peak = Math.max(s.peak, peak);
+    var dur = filmSec(), from = Math.floor((i * BLOCK_SEC / dur) * PEAK_BINS);
+    var to = Math.min(PEAK_BINS, Math.ceil((Math.min(dur, (i + 1) * BLOCK_SEC) / dur) * PEAK_BINS));
+    var perBin = (dur / PEAK_BINS) * block.sampleRate, origin = i * BLOCK_SEC * block.sampleRate;
+    for (var b = from; b < to; b++) {
+      var lo = Math.max(0, Math.floor(b * perBin - origin)), hi = Math.min(block.left.length, Math.floor((b + 1) * perBin - origin));
+      var m = audio.peaks[b];
+      for (var k = lo; k < hi; k++) m = Math.max(m, Math.abs(block.left[k]), Math.abs(block.right[k]));
+      audio.peaks[b] = Math.min(1, m);
+    }
+    drawWave();
+    if (s.seen.size < s.total) return;
+    // The whole film is mixed: master as the export does, or say it's silent.
+    s.gain = s.peak > 0.95 ? 0.92 / s.peak : 1;
+    if (s.peak < SILENT) setAudioStatus("none");
+  }
+  function streamFailed(s, err) {
+    if (stream !== s) return;
+    if (s.worker) s.worker.stop();
+    stream = null;
+    stopClock();
+    console.warn("Mixing the soundtrack in the browser failed, so the preview server mixes it:", err);
+    audio.mode = "server";
+    setAudioStatus("mixing");
+    fetch("/audio/mix", { method: "POST" }).catch(function () {});
+  }
+  // The master stage on a block: the film's gain, then the export's soft limiter.
+  function mastered(channel, gain) {
+    var out = new Float32Array(channel.length);
+    for (var k = 0; k < channel.length; k++) {
+      var v = Math.tanh(channel[k] * gain);
+      out[k] = v === v ? v : 0;
+    }
+    return out;
+  }
+  function startStream(f0) {
+    var s = stream, ctx = audio.ctx;
+    ctx.resume();
+    var pb = { t0: f0 / meta.fps, startAt: ctx.currentTime + 0.08, next: Math.floor(f0 / meta.fps / BLOCK_SEC), sources: [], timer: 0 };
+    playback = pb;
+    function tick() {
+      if (playback !== pb || stream !== s) return;
+      var now = ctx.currentTime - pb.startAt + pb.t0;
+      while (pb.next < s.total && pb.next * BLOCK_SEC < now + AHEAD_SEC) {
+        var have = s.blocks.get(pb.next);
+        if (!have) { streamBlock(s, pb.next, true).then(tick, function () {}); return; }
+        scheduleBlock(pb, pb.next, have, s.gain);
+        pb.next++;
+      }
+    }
+    pb.timer = setInterval(tick, 250);
+    tick();
+    return function () { return Math.max(0, ctx.currentTime - pb.startAt); };
+  }
+  // Block i starts at film second i * BLOCK_SEC: on the clock, that is
+  // startAt + (i * BLOCK_SEC - t0). A block that comes late starts part way
+  // in, so sound and picture stay on the same clock.
+  function scheduleBlock(pb, i, block, gain) {
+    var ctx = audio.ctx, buf = ctx.createBuffer(2, block.left.length, block.sampleRate);
+    buf.copyToChannel(mastered(block.left, gain), 0);
+    buf.copyToChannel(mastered(block.right, gain), 1);
+    var src = ctx.createBufferSource();
+    src.buffer = buf;
+    src.connect(audio.gain);
+    var when = pb.startAt + (i * BLOCK_SEC - pb.t0), at = Math.max(when, ctx.currentTime + 0.02), offset = at - when;
+    if (offset >= buf.duration) return;
+    src.start(at, offset);
+    pb.sources.push(src);
+    src.onended = function () { pb.sources = pb.sources.filter(function (x) { return x !== src; }); };
+  }
+  function stopStream() {
+    var pb = playback;
+    playback = null;
+    if (!pb) return;
+    clearInterval(pb.timer);
+    pb.sources.forEach(function (src) { try { src.stop(); } catch (e) {} src.disconnect(); });
+  }
   function loadAudio(status) {
+    if (status && status.state === "browser") {
+      audio.mode = "browser";
+      setAudioStatus("mixing");
+      if (player) beginStream(player);
+      return;
+    }
     stopClock();
     audio.buffer = null;
     audio.peaks = null;
     if (!status || status.state !== "ready") { setAudioStatus(status ? status.state : "none", status && status.error); return; }
     audio.peaks = status.peaks;
     setAudioStatus("loading");
-    if (!audio.ctx) {
-      var Ctx = window.AudioContext || window.webkitAudioContext;
-      audio.ctx = new Ctx();
-      audio.gain = audio.ctx.createGain();
-      audio.gain.connect(audio.ctx.destination);
-      applyVolume();
-    }
+    ensureAudioContext();
     fetch("/audio")
       .then(function (r) { if (!r.ok) throw new Error("HTTP " + r.status); return r.arrayBuffer(); })
       .then(function (data) { return audio.ctx.decodeAudioData(data); })
@@ -937,6 +1166,7 @@ const previewPage = `<!doctype html>
   // The clock for real-time playback: the soundtrack when there is one,
   // otherwise the wall clock. Audio as master keeps picture and sound in sync.
   function startClock(f0) {
+    if (stream && audio.ctx && audio.state === "ready") return startStream(f0);
     if (audio.buffer && audio.ctx) {
       audio.ctx.resume();
       var src = audio.ctx.createBufferSource();
@@ -951,6 +1181,7 @@ const previewPage = `<!doctype html>
     return function () { return (performance.now() - t0) / 1000; };
   }
   function stopClock() {
+    stopStream();
     if (!audio.src) return;
     try { audio.src.stop(); } catch (e) {}
     audio.src.disconnect();
@@ -1043,6 +1274,14 @@ const previewPage = `<!doctype html>
   async function playFrames(alive) {
     meter.start();
     renderFps();
+    // Sound starts with picture: wait for the block at the playhead.
+    if (stream && audio.state !== "none") {
+      setStalled(true);
+      await streamBlock(stream, Math.floor(frame / meta.fps / BLOCK_SEC), true).catch(function () {});
+      if (!alive()) return;
+      setStalled(false);
+      if (stream && audio.state === "mixing") setAudioStatus("ready");
+    }
     // A soundtrack still downloading would start late: wait for it.
     if (audio.state === "loading") {
       setStalled(true);
@@ -1532,6 +1771,10 @@ const previewPage = `<!doctype html>
         playing: playing,
         buffering: stalled,
         audio: audio.state,
+        // Soundtrack blocks mixed in this page so far, of the film's.
+        audioMixed: stream ? { blocks: stream.seen.size, of: stream.total, exact: Array.from(stream.blocks.values()).filter(function (b) { return b.exact; }).length } : null,
+        // Where the soundtrack mixes: "worker" (off the page's thread), "page", or "server".
+        audioMixer: stream ? (stream.worker ? "worker" : "page") : audio.mode === "server" ? "server" : null,
         connected: !offline,
         // Frames shown per second over the last 2 s of playback (the last
         // playback's while paused), and how long the last frame took to draw.
@@ -1611,6 +1854,7 @@ const previewPage = `<!doctype html>
     if (!window.framefieldsPlayer) return;
     window.framefieldsPlayer.then(function (p) {
       player = p;
+      if (audio.mode === "browser") beginStream(p);
       $("play").disabled = false;
       show(frame).then(function () {
         pageState = "ready";
@@ -1639,8 +1883,31 @@ const previewPage = `<!doctype html>
 `;
 
 //#endregion
-//#region src/preview/index.ts
+//#region src/preview/peaks.ts
+/** Waveform peaks of a stereo mix: the loudest sample of either channel per bin, 0–1. */
+function computePeaks(left, right, bins) {
+	const peaks = new Array(bins).fill(0);
+	if (left.length === 0) return peaks;
+	const per = left.length / bins;
+	for (let b = 0; b < bins; b++) {
+		const start = Math.floor(b * per);
+		const end = Math.min(left.length, Math.floor((b + 1) * per));
+		let max = 0;
+		for (let i = start; i < end; i++) {
+			const v = Math.max(Math.abs(left[i] ?? 0), Math.abs(right[i] ?? 0));
+			if (v > max) max = v;
+		}
+		peaks[b] = Math.min(1, max);
+	}
+	return peaks;
+}
+/** Bins the page's waveform draws. */
 const PEAK_BINS = 1200;
+/** A mix counts as silent below this peak. */
+const SILENT_PEAK = .001;
+
+//#endregion
+//#region src/preview/index.ts
 /** Requests carrying this header come from another preview process, not a page. */
 const TAKEOVER_HEADER = "x-framefields-preview";
 const PLAYER_PATH = "/@framefields/player.js";
@@ -1676,6 +1943,11 @@ async function startPreview(source, options = {}) {
 	let pageOpened = false;
 	const notes = options.notesDir === false ? void 0 : new NoteStore(path.resolve(options.notesDir ?? path.join(process.cwd(), ".framefields", "preview-notes")));
 	let noteQueue = Promise.resolve();
+	const assets = await openAssetLocator(path.dirname(entry)).catch((err) => {
+		say(`pinned assets are off: ${err.message}`);
+	});
+	if (assets) inputStore.setMissingMediaResolver((file) => assets.url(file));
+	const unreadable = /* @__PURE__ */ new Set();
 	const target = await loadTarget(entry, exportName);
 	const meta = await resolveMeta(target, title, session, notes?.dir ?? null);
 	let bundle;
@@ -1697,7 +1969,7 @@ async function startPreview(source, options = {}) {
 	};
 	const engine = engineDir();
 	engine.catch(() => {});
-	let audio = { state: options.audio === false ? "none" : "mixing" };
+	let audio = { state: options.audio === false ? "none" : "browser" };
 	let audioWav;
 	function broadcast(event, data) {
 		for (const client of sseClients) client.write(`event: ${event}\ndata: ${JSON.stringify(data)}\n\n`);
@@ -1721,7 +1993,7 @@ async function startPreview(source, options = {}) {
 			const left = channels[0] ?? new Float32Array(0);
 			const right = channels[1] ?? left;
 			const peaks = computePeaks(left, right, PEAK_BINS);
-			if (left.length === 0 || Math.max(...peaks) < .001) {
+			if (left.length === 0 || Math.max(...peaks) < SILENT_PEAK) {
 				setAudio({ state: "none" });
 				return;
 			}
@@ -1750,6 +2022,7 @@ async function startPreview(source, options = {}) {
 			if (reason === "replaced") say("stopped: a newer preview took over");
 			for (const client of sseClients) client.end();
 			sseClients.clear();
+			if (assets) inputStore.setMissingMediaResolver();
 			server.close(() => {
 				resolve$1();
 				resolveClosed(reason);
@@ -1807,7 +2080,7 @@ async function startPreview(source, options = {}) {
 			if (req.method === "GET" && url$1.pathname === "/@framefields/stat") {
 				const file = path.resolve(url$1.searchParams.get("path") ?? "");
 				let size = -1;
-				if (roots.some((r) => isInside(r, file))) size = await fs.promises.stat(file).then((st) => st.isFile() ? st.size : -1, () => -1);
+				if (roots.some((r) => isInside(r, file))) size = await fs.promises.stat(file).then((st) => st.isFile() ? st.size : -1, () => assets?.entry(file)?.size ?? -1);
 				sendJson(res, 200, {
 					exists: size >= 0,
 					size: Math.max(0, size)
@@ -1868,6 +2141,14 @@ async function startPreview(source, options = {}) {
 					return;
 				}
 			}
+			if (req.method === "POST" && url$1.pathname === "/audio/mix") {
+				if (audio.state === "browser" || audio.state === "error") {
+					audio = { state: "mixing" };
+					startAudio();
+				}
+				sendJson(res, 202, audio);
+				return;
+			}
 			if (req.method === "GET" && url$1.pathname === "/audio") {
 				if (audio.state !== "ready" || !audioWav) {
 					sendJson(res, 404, { error: `audio is ${audio.state}` });
@@ -1895,6 +2176,7 @@ async function startPreview(source, options = {}) {
 					await sendFile(req, res, file);
 					return;
 				}
+				if (assets && await redirectToBucket(res, assets, file, unreadable, say)) return;
 			}
 			sendJson(res, 404, { error: "not found" });
 		} catch (err) {
@@ -1929,7 +2211,6 @@ async function startPreview(source, options = {}) {
 	const { port: actualPort } = server.address();
 	const url = `http://${host.includes(":") ? `[${host}]` : host}:${actualPort}/`;
 	playerBundle().catch(() => {});
-	startAudio();
 	if (options.open === true) {
 		const reconnected = await new Promise((resolve$1) => {
 			const timer = setTimeout(() => resolve$1(false), 2e3);
@@ -2041,6 +2322,29 @@ const CONTENT_TYPES = {
 	".srt": "text/plain; charset=utf-8",
 	".txt": "text/plain; charset=utf-8"
 };
+/**
+* Sends the page to the bucket for a pinned asset that isn't on disk. The
+* bucket must allow this page's origin (CORS): the engine reads media with
+* `fetch`. True when it answered.
+*/
+async function redirectToBucket(res, assets, file, unreadable, say) {
+	if (!assets.entry(file)) return false;
+	const url = await assets.url(file);
+	if (url) {
+		res.writeHead(302, {
+			location: url,
+			"cache-control": "no-store"
+		});
+		res.end();
+		return true;
+	}
+	const rel = path.relative(assets.root, file);
+	if (!unreadable.has(rel)) {
+		unreadable.add(rel);
+		say(`${rel} is pinned on a private remote and there are no keys here: set its FRAMEFIELDS_STORAGE_* keys, give the remote a publicUrl, or \`npx framefields assets pull\``);
+	}
+	return false;
+}
 /** Serves a file, with byte ranges so video can seek without loading it whole. */
 async function sendFile(req, res, file) {
 	const { size } = await fs.promises.stat(file);
@@ -2115,22 +2419,6 @@ async function requestTakeover(host, port) {
 	return ok;
 }
 /** Max absolute amplitude of both channels per bin, 0..1. */
-function computePeaks(left, right, bins) {
-	const peaks = new Array(bins).fill(0);
-	if (left.length === 0) return peaks;
-	const per = left.length / bins;
-	for (let b = 0; b < bins; b++) {
-		const start = Math.floor(b * per);
-		const end = Math.min(left.length, Math.floor((b + 1) * per));
-		let max = 0;
-		for (let i = start; i < end; i++) {
-			const v = Math.max(Math.abs(left[i] ?? 0), Math.abs(right[i] ?? 0));
-			if (v > max) max = v;
-		}
-		peaks[b] = Math.min(1, max);
-	}
-	return peaks;
-}
 function sendJson(res, status, body) {
 	res.writeHead(status, {
 		"content-type": "application/json",
@@ -2155,4 +2443,4 @@ function openBrowser(url) {
 
 //#endregion
 export { startPreview as t };
-//# sourceMappingURL=preview-BToKUTtZ.mjs.map
+//# sourceMappingURL=preview-PDz7o2xg.mjs.map