Skip to content

Code-first video & image, rendered natively on WebGPU.

perf(preview): mix the soundtrack in a worker

okanasl97d9aad21186
diff --git a/.changeset/preview-streamed-audio.md b/.changeset/preview-streamed-audio.md
index e085bd6b..44a629db 100644
--- a/.changeset/preview-streamed-audio.md
+++ b/.changeset/preview-streamed-audio.md
@@ -2,4 +2,4 @@
"framefields": minor
---
-The preview mixes its soundtrack in the browser, around the playhead. The page runs the export's mixer (same decoders, audio effects on its GPU, signals) on 2-second blocks as it plays, each mixed from 2 s earlier so reverbs, delays and compressors are warmed up, and plays them back to back on the AudioContext clock; the rest of the film mixes in the background for the waveform and the master gain. Sources are read in byte ranges, so pinned assets stream from their bucket and the server sends no WAV. The server mixes only when the browser can't. `mixAudioTracks` and `renderAudio` take a `window` (the same samples as that stretch of a full mix) and `master: false`.
+The preview mixes its soundtrack in the browser, around the playhead. The page runs the export's mixer (same decoders, audio effects on its GPU, signals) on 2-second blocks as it plays, each mixed from 2 s earlier so reverbs, delays and compressors are warmed up, and plays them back to back on the AudioContext clock; the rest of the film mixes in the background for the waveform and the master gain. Sources are read in byte ranges, so pinned assets stream from their bucket and the server sends no WAV. The mixing runs in a module worker (the project's bundle, loaded as one) with its own GPU device, so it never stalls the picture; the page mixes if the worker can't, and the server only if neither can. `mixAudioTracks` and `renderAudio` take a `window` (the same samples as that stretch of a full mix) and `master: false`.
diff --git a/packages/compositions/src/utils/audio-extractor.ts b/packages/compositions/src/utils/audio-extractor.ts
index 8991a6c6..6780485b 100644
--- a/packages/compositions/src/utils/audio-extractor.ts
+++ b/packages/compositions/src/utils/audio-extractor.ts
@@ -150,6 +150,15 @@ interface DecodedAudioRange {
validToSec: number;
}
+/**
+ * A source this runtime can't decode at all (a codec WebCodecs lacks, in a
+ * worker without AudioContext). Thrown, not mixed as silence, so the caller
+ * can mix where it can be decoded.
+ */
+export class AudioDecodeUnavailable extends Error {
+ override name = "AudioDecodeUnavailable";
+}
+
/**
* The browser's whole-file decoder, for codecs WebCodecs can't decode
* (mediabunny reads byte ranges and decodes with WebCodecs first).
@@ -160,7 +169,9 @@ async function decodeWithAudioContext(url: string): Promise<DecodedAudioRange> {
(window as Window & { webkitAudioContext?: typeof AudioContext })
.webkitAudioContext;
if (!AudioContextClass) {
- throw new Error("AudioContext is not supported in this browser");
+ throw new AudioDecodeUnavailable(
+ `No decoder here for ${url}: WebCodecs can't decode it and there is no AudioContext (a worker).`,
+ );
}
const audioCtx = new AudioContextClass();
try {
@@ -211,14 +222,10 @@ async function decodeAudioRange(
`[AudioExtractor] decodeAudioSource started for url: ${url}`,
);
try {
- const isBrowser =
- typeof window !== "undefined" &&
- typeof window.document !== "undefined" &&
- !(
- typeof process !== "undefined" &&
- process.versions &&
- process.versions.node
- );
+ // A page or a worker: anything but Node.
+ const isBrowser = !(
+ typeof process !== "undefined" && process.versions?.node
+ );
let inputAcquired = false;
try {
mediaLogger.debug(
@@ -438,8 +445,9 @@ async function decodeAudioRange(
}
} catch (err) {
if (
- err instanceof Error &&
- err.message.includes("Cannot open local media file")
+ err instanceof AudioDecodeUnavailable ||
+ (err instanceof Error &&
+ err.message.includes("Cannot open local media file"))
) {
throw err;
}
diff --git a/packages/framefields/src/preview/audio-mixer.ts b/packages/framefields/src/preview/audio-mixer.ts
new file mode 100644
index 00000000..505c9ae1
--- /dev/null
+++ b/packages/framefields/src/preview/audio-mixer.ts
@@ -0,0 +1,151 @@
+/// <reference lib="webworker" />
+/**
+ * The preview's soundtrack: the export's mixer run in the browser, a stretch
+ * at a time. The page asks a worker running this (with its own GPU device)
+ * for the blocks around its playhead, so mixing never holds up drawing; it
+ * mixes on the page itself only if the worker can't.
+ */
+import { BUILTIN_NODE_RENDERERS } from "framefields-preview:renderers";
+import { mixAudioTracks, preflightMediaTime } from "@framefields/compositions";
+import type { VirtualMediaData } from "@framefields/core";
+import { ensureDevice } from "@framefields/webgpu-renderers";
+import { registerRenderers } from "./register.js";
+
+/** A stretch of the soundtrack, before the master stage. */
+export interface PreviewMix {
+ left: Float32Array;
+ right: Float32Array;
+ sampleRate: number;
+ /** Its loudest sample: the page masters with the film's loudest. */
+ peak: number;
+}
+
+export interface MixRange {
+ startSec: number;
+ endSec: number;
+}
+
+/** What a composition export gives the mixer. */
+export interface AudioTarget {
+ toVirtualMediaAsync?: () => Promise<VirtualMediaData>;
+ toVirtualMedia?: () => VirtualMediaData;
+ /** Finishes live signal time, recorded frame by frame, before a mix. */
+ prepareMediaTime?: () => Promise<void>;
+}
+
+/**
+ * Seconds mixed before a window and dropped, so effects that carry state
+ * (reverb tails, delays, compressors) enter it warmed up, as in a full mix.
+ */
+const AUDIO_LEAD_IN_SEC = 2;
+
+/**
+ * Mixes [startSec, endSec) of the target's soundtrack with the export's
+ * mixer: the same decoders (reading only the stretch it plays, so pinned
+ * assets stream from their bucket), audio effects on `device` and signals.
+ */
+export function createAudioMixer(
+ target: AudioTarget,
+ fps: number,
+ device: GPUDevice,
+ renderId: string,
+): (range: MixRange) => Promise<PreviewMix> {
+ // Prepared once, as the export prepares it: a fresh tree, live signal
+ // time finished, media timing preflighted.
+ let prepared: Promise<VirtualMediaData> | undefined;
+ const prepare = async () => {
+ const tree = target.toVirtualMediaAsync
+ ? await target.toVirtualMediaAsync()
+ : target.toVirtualMedia?.();
+ if (!tree) throw new Error("The export is not a composition.");
+ await target.prepareMediaTime?.();
+ await preflightMediaTime(tree, fps);
+ return tree;
+ };
+ return async (range) => {
+ prepared ??= prepare();
+ const tree = await prepared;
+ const from = Math.max(0, range.startSec - AUDIO_LEAD_IN_SEC);
+ const { channels, sampleRate } = await mixAudioTracks(
+ tree,
+ fps,
+ 48_000,
+ device,
+ renderId,
+ { window: { startSec: from, endSec: range.endSec }, master: false },
+ );
+ const drop = Math.round((range.startSec - from) * sampleRate);
+ const left = (channels[0] ?? new Float32Array(0)).slice(drop);
+ const right = (channels[1] ?? channels[0] ?? left).slice(drop);
+ let peak = 0;
+ for (let i = 0; i < left.length; i++)
+ peak = Math.max(peak, Math.abs(left[i]), Math.abs(right[i]));
+ return { left, right, sampleRate, peak };
+ };
+}
+
+export interface MixRequest {
+ id: number;
+ range: MixRange;
+}
+
+export type MixReply =
+ | { ready: true }
+ | { ready: false; error: string }
+ | { id: number; mix: PreviewMix }
+ | { id: number; error: string };
+
+/**
+ * The worker side: the project's bundle calls this instead of starting a
+ * player when it runs in a worker. It builds the composition, then answers
+ * each `MixRequest` with the stretch mixed (its buffers transferred).
+ */
+export function startAudioMixer(
+ mod: Record<string, unknown>,
+ exportName: string,
+): void {
+ const scope = self as unknown as DedicatedWorkerGlobalScope;
+ const ready = (async () => {
+ await registerRenderers(BUILTIN_NODE_RENDERERS);
+ const exported = mod[exportName];
+ const target = (
+ typeof exported === "function"
+ ? await (exported as () => unknown)()
+ : exported
+ ) as AudioTarget & { fps?: number };
+ const vm = target.toVirtualMediaAsync
+ ? await target.toVirtualMediaAsync()
+ : target.toVirtualMedia?.();
+ const fps =
+ target.fps ?? (vm?.operation as { fps?: number } | undefined)?.fps ?? 30;
+ return createAudioMixer(target, fps, await ensureDevice(), "worker-audio");
+ })();
+ ready.then(
+ () => scope.postMessage({ ready: true } satisfies MixReply),
+ (err: unknown) =>
+ scope.postMessage({
+ ready: false,
+ error: errorText(err),
+ } satisfies MixReply),
+ );
+ // One stretch at a time, in the order asked: the page queues them.
+ let queue: Promise<void> = Promise.resolve();
+ scope.onmessage = (event: MessageEvent<MixRequest>) => {
+ const { id, range } = event.data;
+ queue = queue.then(async () => {
+ try {
+ const mix = await (await ready)(range);
+ scope.postMessage({ id, mix } satisfies MixReply, [
+ mix.left.buffer,
+ mix.right.buffer,
+ ]);
+ } catch (err) {
+ scope.postMessage({ id, error: errorText(err) } satisfies MixReply);
+ }
+ });
+ };
+}
+
+function errorText(err: unknown): string {
+ return err instanceof Error ? err.message : String(err);
+}
diff --git a/packages/framefields/src/preview/bundle.ts b/packages/framefields/src/preview/bundle.ts
index fa30af1c..818d39ed 100644
--- a/packages/framefields/src/preview/bundle.ts
+++ b/packages/framefields/src/preview/bundle.ts
@@ -167,9 +167,11 @@ export async function bundleProject(options: {
}));
b.onLoad({ filter: /.*/, 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)});`,
+ // The page loads it as the player; a worker it starts, as the soundtrack's mixer.
+ `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",
diff --git a/packages/framefields/src/preview/page.ts b/packages/framefields/src/preview/page.ts
index 3733acdb..5954457e 100644
--- a/packages/framefields/src/preview/page.ts
+++ b/packages/framefields/src/preview/page.ts
@@ -524,15 +524,57 @@ export const previewPage = /* html */ `<!doctype html>
// 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. If mixing fails here, the server mixes it. ──
+ // 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) {
+ 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 });
+ });
+ });
+ },
+ 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, blocks: new Map(), order: [], pending: new Map(), queue: [], busy: false,
+ stream = { player: p, worker: mixerWorker(), blocks: new Map(), order: [], pending: new Map(), queue: [], busy: false,
seen: new Set(), peak: 0, gain: 1, fill: 0, total: Math.max(1, Math.ceil(filmSec() / BLOCK_SEC)) };
ensureAudioContext();
setAudioStatus("mixing");
@@ -566,7 +608,7 @@ export const previewPage = /* html */ `<!doctype html>
s.busy = true;
var job = s.queue.shift();
var range = { startSec: job.i * BLOCK_SEC, endSec: Math.min(filmSec(), (job.i + 1) * BLOCK_SEC) };
- s.player.mixAudio(range).then(function (mix) {
+ mixBlock(s, range).then(function (mix) {
var block = { left: mix.left, right: mix.right, sampleRate: mix.sampleRate };
if (stream === s) keepBlock(s, job.i, block, mix.peak);
job.resolve(block);
@@ -579,6 +621,18 @@ export const previewPage = /* html */ `<!doctype html>
pumpStream(s);
});
}
+ // In the worker; on the page itself once the worker has failed.
+ function mixBlock(s, range) {
+ if (!s.worker) return s.player.mixAudio(range);
+ return s.worker.mix(range).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);
+ });
+ }
// Idle: mix the next block not mixed yet, for the waveform and the gain.
function fillStream(s) {
while (s.fill < s.total && s.seen.has(s.fill)) s.fill++;
@@ -608,6 +662,7 @@ export const previewPage = /* html */ `<!doctype html>
}
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);
@@ -1303,6 +1358,8 @@ export const previewPage = /* html */ `<!doctype html>
audio: audio.state,
// Soundtrack blocks mixed in this page so far, of the film's.
audioMixed: stream ? { blocks: stream.seen.size, of: stream.total } : 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.
diff --git a/packages/framefields/src/preview/player.ts b/packages/framefields/src/preview/player.ts
index 7ab0423a..d33b57d2 100644
--- a/packages/framefields/src/preview/player.ts
+++ b/packages/framefields/src/preview/player.ts
@@ -10,15 +10,8 @@ import { BUILTIN_NODE_RENDERERS } from "framefields-preview:renderers";
import {
compositionStateStore,
drawCompositionTree,
- mixAudioTracks,
- preflightMediaTime,
} from "@framefields/compositions";
import { updateClockSignals, type VirtualMediaData } from "@framefields/core";
-import {
- audioRegistry,
- type NodeRendererPlugin,
- registerWebGPURenderer,
-} from "@framefields/node-sdk";
import { preloadCompositionFonts } from "@framefields/renderers";
import {
type OrtWebModule,
@@ -33,12 +26,16 @@ import {
type RenderContextValue,
SlugFontCache,
} from "@framefields/webgpu-renderers";
+import {
+ type AudioTarget,
+ createAudioMixer,
+ type PreviewMix,
+} from "./audio-mixer.js";
import { Blitter } from "./blit.js";
+import { type BuiltinRenderer, registerRenderers } from "./register.js";
-export interface BuiltinRenderer {
- ops: readonly string[];
- load: () => Promise<{ default?: NodeRendererPlugin }>;
-}
+export { startAudioMixer } from "./audio-mixer.js";
+export type { BuiltinRenderer, PreviewMix };
export interface PlayerMeta {
width: number;
@@ -48,21 +45,6 @@ export interface PlayerMeta {
durationMs: number;
}
-/** A stretch of the soundtrack, before the master stage. */
-export interface PreviewMix {
- left: Float32Array;
- right: Float32Array;
- sampleRate: number;
- /** Its loudest sample: the page masters with the film's loudest. */
- peak: number;
-}
-
-/**
- * Seconds mixed before a window and dropped, so effects that carry state
- * (reverb tails, delays, compressors) enter it warmed up, as in a full mix.
- */
-const AUDIO_LEAD_IN_SEC = 2;
-
export interface PreviewPlayer {
meta: PlayerMeta;
canvas: HTMLCanvasElement;
@@ -100,13 +82,7 @@ export interface PreviewPlayer {
dispose(): Promise<void>;
}
-type Renderable = {
- toVirtualMediaAsync?: () => Promise<VirtualMediaData>;
- toVirtualMedia?: () => VirtualMediaData;
- /** Finishes live signal time, recorded frame by frame, before a mix. */
- prepareMediaTime?: () => Promise<void>;
- fps?: number;
-};
+type Renderable = AudioTarget & { fps?: number };
declare global {
interface Window {
@@ -416,17 +392,7 @@ async function createPlayer(
})();
}
- // The tree the soundtrack mixes from, prepared once as the export prepares
- // it: a fresh tree, live signal time finished, media timing preflighted.
- let audioTree: Promise<VirtualMediaData> | undefined;
- async function prepareAudioTree(): Promise<VirtualMediaData> {
- const tree = target.toVirtualMediaAsync
- ? await target.toVirtualMediaAsync()
- : (target.toVirtualMedia?.() ?? (vm as VirtualMediaData));
- await target.prepareMediaTime?.();
- await preflightMediaTime(tree, fps);
- return tree;
- }
+ const mixAudio = createAudioMixer(target, fps, device, `${renderId}-audio`);
const blitter = new Blitter(device, surface.colorFormat);
@@ -453,26 +419,7 @@ async function createPlayer(
pump();
return true;
},
- async mixAudio(range) {
- audioTree ??= prepareAudioTree();
- const tree = await audioTree;
- const from = Math.max(0, range.startSec - AUDIO_LEAD_IN_SEC);
- const { channels, sampleRate } = await mixAudioTracks(
- tree,
- fps,
- 48_000,
- device,
- `${renderId}-audio`,
- { window: { startSec: from, endSec: range.endSec }, master: false },
- );
- const drop = Math.round((range.startSec - from) * sampleRate);
- const left = (channels[0] ?? new Float32Array(0)).subarray(drop);
- const right = (channels[1] ?? channels[0] ?? left).subarray(drop);
- let peak = 0;
- for (let i = 0; i < left.length; i++)
- peak = Math.max(peak, Math.abs(left[i]), Math.abs(right[i]));
- return { left, right, sampleRate, peak };
- },
+ mixAudio,
async snapshot(frame) {
if (disposed) throw new Error("the player was disposed");
while (drawing) await drawing;
@@ -550,26 +497,3 @@ function containsOp(node: VirtualMediaData, op: string): boolean {
if ((node.operation as { op?: string } | undefined)?.op === op) return true;
return (node.children ?? []).some((child) => containsOp(child, op));
}
-
-async function registerRenderers(renderers: readonly BuiltinRenderer[]) {
- await Promise.all(
- renderers.map(async ({ ops, load }) => {
- try {
- const plugin = (await load()).default;
- for (const op of ops) {
- if (plugin?.WebGPURenderer)
- registerWebGPURenderer(op, plugin.WebGPURenderer);
- if (plugin?.audioProcessor)
- audioRegistry.register(op, plugin.audioProcessor);
- }
- } catch (err) {
- console.warn(
- "[framefields] renderer for",
- ops[0],
- "failed to load",
- err,
- );
- }
- }),
- );
-}
diff --git a/packages/framefields/src/preview/register.ts b/packages/framefields/src/preview/register.ts
new file mode 100644
index 00000000..1d40a05b
--- /dev/null
+++ b/packages/framefields/src/preview/register.ts
@@ -0,0 +1,37 @@
+/**
+ * Registers the built-in node renderers (their WebGPU renderers and audio
+ * processors) in a page or worker, as the export engine registers them.
+ */
+import {
+ audioRegistry,
+ type NodeRendererPlugin,
+ registerWebGPURenderer,
+} from "@framefields/node-sdk";
+
+export interface BuiltinRenderer {
+ ops: readonly string[];
+ load: () => Promise<{ default?: NodeRendererPlugin }>;
+}
+
+export async function registerRenderers(renderers: readonly BuiltinRenderer[]) {
+ await Promise.all(
+ renderers.map(async ({ ops, load }) => {
+ try {
+ const plugin = (await load()).default;
+ for (const op of ops) {
+ if (plugin?.WebGPURenderer)
+ registerWebGPURenderer(op, plugin.WebGPURenderer);
+ if (plugin?.audioProcessor)
+ audioRegistry.register(op, plugin.audioProcessor);
+ }
+ } catch (err) {
+ console.warn(
+ "[framefields] renderer for",
+ ops[0],
+ "failed to load",
+ err,
+ );
+ }
+ }),
+ );
+}
diff --git a/packages/framefields/src/preview/virtual.d.ts b/packages/framefields/src/preview/virtual.d.ts
index 40ed0a8c..58b9cd6f 100644
--- a/packages/framefields/src/preview/virtual.d.ts
+++ b/packages/framefields/src/preview/virtual.d.ts
@@ -1,6 +1,6 @@
// Resolved when the browser engine is built (bundle.ts): the generated list of
// built-in node renderers from @framefields/renderer.
declare module "framefields-preview:renderers" {
- import type { BuiltinRenderer } from "./player.js";
+ import type { BuiltinRenderer } from "./register.js";
export const BUILTIN_NODE_RENDERERS: readonly BuiltinRenderer[];
}
diff --git a/packages/webgpu-renderers/src/input-store.ts b/packages/webgpu-renderers/src/input-store.ts
index 092e9ed9..547ac0cb 100644
--- a/packages/webgpu-renderers/src/input-store.ts
+++ b/packages/webgpu-renderers/src/input-store.ts
@@ -1,10 +1,13 @@
import { ALL_FORMATS, FilePathSource, Input, UrlSource } from "mediabunny";
import { isNodeRuntime, toLocalPath } from "./local-path.js";
-/** In the browser, local paths are served through the dev server's `/@fs`. */
+/**
+ * In the browser (a page or a worker), local paths are served through the
+ * dev server's `/@fs`.
+ */
export function resolveInputUrl(url: string, isNode: boolean): string {
let resolvedUrl = url;
- if (!isNode && typeof window !== "undefined") {
+ if (!isNode && typeof location !== "undefined") {
if (resolvedUrl.startsWith("file://")) {
resolvedUrl = resolvedUrl.slice(7);
}
diff --git a/plugins/framefields/skills/framefields-render/SKILL.md b/plugins/framefields/skills/framefields-render/SKILL.md
index 011b8bda..64fa80e4 100644
--- a/plugins/framefields/skills/framefields-render/SKILL.md
+++ b/plugins/framefields/skills/framefields-render/SKILL.md
@@ -123,7 +123,7 @@ describe("Hero Scene Conformance", () => {
---
### Step 4.5: Show the User Before Exporting (`preview`)
-When a person is in the loop, let them watch the composition before you spend time on the final render. `startPreview` serves a localhost player with the soundtrack, a timeline with the waveform, and frame stepping. The page loads the composition's own code and renders it with WebGPU in the browser, in real time: a device that can't draw every frame in time skips some, and the sound keeps its speed; the server only serves that code and the project's files. The page mixes the soundtrack itself with the export's mixer, in 2-second blocks around the playhead (each mixed from 2 s earlier so effects with memory are warmed up), so sound starts at once; the rest mixes in the background for the waveform and the master gain. `framefieldsPreview.state().audioMixed` reports how many blocks are mixed. If the browser can't mix, the server mixes the whole soundtrack. Point it at the module that builds the composition:
+When a person is in the loop, let them watch the composition before you spend time on the final render. `startPreview` serves a localhost player with the soundtrack, a timeline with the waveform, and frame stepping. The page loads the composition's own code and renders it with WebGPU in the browser, in real time: a device that can't draw every frame in time skips some, and the sound keeps its speed; the server only serves that code and the project's files. The page mixes the soundtrack itself with the export's mixer, in 2-second blocks around the playhead (each mixed from 2 s earlier so effects with memory are warmed up), so sound starts at once; the rest mixes in the background for the waveform and the master gain. It mixes in a background worker with its own GPU device, so it doesn't stall drawing. `framefieldsPreview.state()` reports `audioMixed` (blocks mixed) and `audioMixer` (`worker`, `page` or `server`, the fallbacks in order). Point it at the module that builds the composition:
```typescript
import { startPreview } from "framefields";