@glissade/export-web 0.2.0 → 0.3.0

package/README.md

@@ -0,0 +1,22 @@
+# @glissade/export-web
+
+In-browser export: WebCodecs encoding + Mediabunny muxing, frame-accurate and faster than realtime, with sample-accurate audio via OfflineAudioContext. Ships the **worker protocol** (`serveExportRequest` / `requestWorkerExport`) so encoding runs off the main thread — audio premixes main-side and transfers as raw PCM. Codec support is feature-detected; PNG frames are the unconditional fallback.
+
+```sh
+npm i @glissade/export-web
+```
+
+```ts
+import { exportVideo } from '@glissade/export-web';
+
+const { blob, format } = await exportVideo(scene, doc, { fps: 60, format: 'auto' });
+```
+
+## Part of glissade
+
+*(glide & slide)* — programmatic motion graphics for TypeScript: realtime-first in any web page, deterministic headless video export from the same code, a visual studio over the same document. No generator functions.
+
+- [Repository & full README](https://github.com/tyevco/glissade)
+- [Getting started](https://github.com/tyevco/glissade/blob/main/docs/getting-started.md) · [Concepts](https://github.com/tyevco/glissade/blob/main/docs/concepts.md) · [Interactivity](https://github.com/tyevco/glissade/blob/main/docs/interactivity.md)
+
+Apache-2.0.

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import { AudioCodec, VideoCodec } from "mediabunny";
-import { Timeline } from "@glissade/core";
+import { AudioClip, Timeline } from "@glissade/core";
 import { Scene, VideoFrameSource } from "@glissade/scene";
 
 //#region src/videoSource.d.ts
@@ -18,6 +18,46 @@ declare class MediabunnyVideoFrameSource implements VideoFrameSource {
   close(): void;
 }
 //#endregion
+//#region src/workerProtocol.d.ts
+interface ExportWorkerRequest {
+  /** Registry key the worker's loadScene resolves (e.g. a module glob key). */
+  sceneKey: string;
+  /** The document to render — e.g. the studio's sidecar-merged timeline. */
+  timeline: Timeline;
+  options?: Omit<WebExportOptions, 'onProgress' | 'premixedAudio'>;
+  /** Premixed on the main thread; channels arrive transferred. */
+  premixedAudio?: PremixedAudio;
+}
+type ExportWorkerResponse = {
+  kind: 'progress';
+  frame: number;
+  total: number;
+} | {
+  kind: 'done';
+  buffer: ArrayBuffer;
+  format: 'mp4' | 'webm';
+  videoCodec: string;
+  audioCodec: string | null;
+  frames: number;
+} | {
+  kind: 'error';
+  message: string;
+};
+/** The entire worker body: resolve the scene, export, stream progress, transfer the result. */
+declare function serveExportRequest(req: ExportWorkerRequest, loadScene: (key: string) => Promise<Scene>, post: (msg: ExportWorkerResponse, transfer?: Transferable[]) => void): Promise<void>;
+interface WorkerExportHandle {
+  result: Promise<WebExportResult>;
+  /** Terminates the worker; the result promise rejects. */
+  cancel(): void;
+}
+/** Main-thread side: premix audio if the document carries any, post, collect. */
+declare function requestWorkerExport(worker: Worker, args: {
+  sceneKey: string;
+  timeline: Timeline;
+  options?: ExportWorkerRequest['options'];
+  onProgress?: (frame: number, total: number) => void;
+}): WorkerExportHandle;
+//#endregion
 //#region src/index.d.ts
 interface WebExportOptions {
   fps?: number;
@@ -25,8 +65,19 @@ interface WebExportOptions {
   format?: 'mp4' | 'webm' | 'auto';
   videoBitrate?: number;
   audioBitrate?: number;
+  /**
+   * Pre-mixed PCM from the main thread (raw planar f32 channels). Workers
+   * have no OfflineAudioContext, so the worker path premixes there and
+   * transfers the channels (§5.1 worker posture).
+   */
+  premixedAudio?: PremixedAudio;
   onProgress?: (frame: number, total: number) => void;
 }
+/** Raw mixed audio: one Float32Array per channel, transferable to a Worker. */
+interface PremixedAudio {
+  sampleRate: number;
+  channelData: Float32Array[];
+}
 interface WebExportResult {
   blob: Blob;
   format: 'mp4' | 'webm';
@@ -37,6 +88,10 @@ interface WebExportResult {
 declare class ExportUnsupportedError extends Error {
   constructor(detail: string);
 }
+/** Mix timeline audio clips sample-accurately (§5.3 browser path). Window-only (OfflineAudioContext). */
+declare function mixAudio(clips: AudioClip[], duration: number, sampleRate?: number): Promise<AudioBuffer>;
+/** Main-thread premix for the worker path: mixAudio flattened to transferable channels. */
+declare function premixTimelineAudio(clips: AudioClip[], duration: number): Promise<PremixedAudio>;
 /** Export a scene + timeline to a video Blob, entirely in the browser. */
 declare function exportVideo(scene: Scene, doc: Timeline, opts?: WebExportOptions): Promise<WebExportResult>;
 /** Unconditional fallback (§5.2): per-frame PNG blobs via a callback — works wherever canvas does. */
@@ -46,4 +101,4 @@ declare function exportPngFrames(scene: Scene, doc: Timeline, onFrame: (frame: n
   frames: number;
 }>;
 //#endregion
-export { ExportUnsupportedError, MediabunnyVideoFrameSource, WebExportOptions, WebExportResult, exportPngFrames, exportVideo };
+export { ExportUnsupportedError, type ExportWorkerRequest, type ExportWorkerResponse, MediabunnyVideoFrameSource, PremixedAudio, WebExportOptions, WebExportResult, type WorkerExportHandle, exportPngFrames, exportVideo, mixAudio, premixTimelineAudio, requestWorkerExport, serveExportRequest };

package/dist/index.js

@@ -1,4 +1,4 @@
-import { ALL_FORMATS, AudioBufferSource, BlobSource, BufferTarget, CanvasSink, CanvasSource, Input, Mp4OutputFormat, Output, UrlSource, WebMOutputFormat, getFirstEncodableAudioCodec, getFirstEncodableVideoCodec } from "mediabunny";
+import { ALL_FORMATS, AudioBufferSource, AudioSample, AudioSampleSource, BlobSource, BufferTarget, CanvasSink, CanvasSource, Input, Mp4OutputFormat, Output, UrlSource, WebMOutputFormat, getFirstEncodableAudioCodec, getFirstEncodableVideoCodec } from "mediabunny";
 import { compileTimeline, sampleTrack } from "@glissade/core";
 import { ColdAssetError, evaluate } from "@glissade/scene";
 import { Canvas2DBackend } from "@glissade/backend-canvas2d";
@@ -71,6 +71,98 @@ var MediabunnyVideoFrameSource = class MediabunnyVideoFrameSource {
 	}
 };
 //#endregion
+//#region src/workerProtocol.ts
+/**
+* Worker export protocol (DESIGN.md §3.4/§5.1: export always runs in a Worker
+* so the main thread stays interactive). The worker re-creates the scene from
+* a host-provided registry key and evaluates + encodes there; the main side
+* premixes audio (OfflineAudioContext is Window-only) and transfers raw PCM.
+* Host apps own the Worker file (bundlers handle `new Worker(new URL(...))`):
+* the worker body is one call to serveExportRequest, the main side one call
+* to requestWorkerExport.
+*/
+/** The entire worker body: resolve the scene, export, stream progress, transfer the result. */
+async function serveExportRequest(req, loadScene, post) {
+	try {
+		const scene = await loadScene(req.sceneKey);
+		if ([...scene.nodes.values()].some((n) => n.constructor.isLayoutNode === true)) {
+			const { loadYogaLayoutEngine } = await import("@glissade/scene/layout");
+			await loadYogaLayoutEngine();
+		}
+		const result = await exportVideo(scene, req.timeline, {
+			...req.options,
+			...req.premixedAudio ? { premixedAudio: req.premixedAudio } : {},
+			onProgress: (frame, total) => post({
+				kind: "progress",
+				frame,
+				total
+			})
+		});
+		const buffer = await result.blob.arrayBuffer();
+		post({
+			kind: "done",
+			buffer,
+			format: result.format,
+			videoCodec: result.videoCodec,
+			audioCodec: result.audioCodec,
+			frames: result.frames
+		}, [buffer]);
+	} catch (err) {
+		post({
+			kind: "error",
+			message: err instanceof Error ? err.message : String(err)
+		});
+	}
+}
+/** Main-thread side: premix audio if the document carries any, post, collect. */
+function requestWorkerExport(worker, args) {
+	let cancelled = false;
+	let rejectResult = null;
+	return {
+		result: (async () => {
+			const compiled = compileTimeline(args.timeline);
+			const transfer = [];
+			let premixedAudio;
+			if (compiled.audio.length > 0) {
+				premixedAudio = await premixTimelineAudio(compiled.audio, compiled.duration);
+				for (const ch of premixedAudio.channelData) transfer.push(ch.buffer);
+			}
+			return await new Promise((resolve, reject) => {
+				rejectResult = reject;
+				if (cancelled) {
+					reject(/* @__PURE__ */ new Error("export cancelled"));
+					return;
+				}
+				worker.onmessage = (e) => {
+					const msg = e.data;
+					if (msg.kind === "progress") args.onProgress?.(msg.frame, msg.total);
+					else if (msg.kind === "done") resolve({
+						blob: new Blob([msg.buffer], { type: msg.format === "mp4" ? "video/mp4" : "video/webm" }),
+						format: msg.format,
+						videoCodec: msg.videoCodec,
+						audioCodec: msg.audioCodec,
+						frames: msg.frames
+					});
+					else reject(new Error(msg.message));
+				};
+				worker.onerror = (e) => reject(new Error(e.message || "export worker crashed"));
+				const req = {
+					sceneKey: args.sceneKey,
+					timeline: args.timeline,
+					...args.options ? { options: args.options } : {},
+					...premixedAudio ? { premixedAudio } : {}
+				};
+				worker.postMessage(req, transfer);
+			});
+		})(),
+		cancel: () => {
+			cancelled = true;
+			worker.terminate();
+			rejectResult?.(/* @__PURE__ */ new Error("export cancelled"));
+		}
+	};
+}
+//#endregion
 //#region src/index.ts
 /**
 * @glissade/export-web — in-browser export (DESIGN.md §5.1b/§5.2/§5.3):
@@ -119,7 +211,7 @@ async function pickCodecs(format, width, height, bitrate, needAudio) {
 	}
 	throw new ExportUnsupportedError(`format '${format}'${needAudio ? " with audio" : ""}`);
 }
-/** Mix timeline audio clips sample-accurately (§5.3 browser path). */
+/** Mix timeline audio clips sample-accurately (§5.3 browser path). Window-only (OfflineAudioContext). */
 async function mixAudio(clips, duration, sampleRate = 48e3) {
 	const ctx = new OfflineAudioContext(2, Math.ceil(duration * sampleRate), sampleRate);
 	for (const clip of clips) {
@@ -147,6 +239,16 @@ async function mixAudio(clips, duration, sampleRate = 48e3) {
 	}
 	return ctx.startRendering();
 }
+/** Main-thread premix for the worker path: mixAudio flattened to transferable channels. */
+async function premixTimelineAudio(clips, duration) {
+	const buf = await mixAudio(clips, duration);
+	const channelData = [];
+	for (let i = 0; i < buf.numberOfChannels; i++) channelData.push(buf.getChannelData(i).slice());
+	return {
+		sampleRate: buf.sampleRate,
+		channelData
+	};
+}
 /** Export a scene + timeline to a video Blob, entirely in the browser. */
 async function exportVideo(scene, doc, opts = {}) {
 	const compiled = compileTimeline(doc);
@@ -199,19 +301,43 @@ async function exportVideo(scene, doc, opts = {}) {
 		bitrate: videoBitrate
 	});
 	output.addVideoTrack(videoSource, { frameRate: fps });
-	let audioSource = null;
+	let feedAudio = null;
 	if (picked.audio) {
-		audioSource = new AudioBufferSource({
-			codec: picked.audio,
-			bitrate: opts.audioBitrate ?? 192e3
-		});
-		output.addAudioTrack(audioSource);
+		const bitrate = opts.audioBitrate ?? 192e3;
+		const premixed = opts.premixedAudio;
+		if (premixed) {
+			const source = new AudioSampleSource({
+				codec: picked.audio,
+				bitrate
+			});
+			output.addAudioTrack(source);
+			feedAudio = async () => {
+				const frames = premixed.channelData[0]?.length ?? 0;
+				const data = new Float32Array(frames * premixed.channelData.length);
+				premixed.channelData.forEach((ch, i) => data.set(ch, i * frames));
+				await source.add(new AudioSample({
+					data,
+					format: "f32-planar",
+					numberOfChannels: premixed.channelData.length,
+					sampleRate: premixed.sampleRate,
+					timestamp: 0
+				}));
+				source.close();
+			};
+		} else {
+			const source = new AudioBufferSource({
+				codec: picked.audio,
+				bitrate
+			});
+			output.addAudioTrack(source);
+			feedAudio = async () => {
+				await source.add(await mixAudio(compiled.audio, duration));
+				source.close();
+			};
+		}
 	}
 	await output.start();
-	if (audioSource) {
-		await audioSource.add(await mixAudio(compiled.audio, duration));
-		audioSource.close();
-	}
+	if (feedAudio) await feedAudio();
 	for (let f = 0; f < total; f++) {
 		await renderFrame(f / fps);
 		await videoSource.add(f / fps, 1 / fps);
@@ -244,4 +370,4 @@ async function exportPngFrames(scene, doc, onFrame, opts = {}) {
 	return { frames: total };
 }
 //#endregion
-export { ExportUnsupportedError, MediabunnyVideoFrameSource, exportPngFrames, exportVideo };
+export { ExportUnsupportedError, MediabunnyVideoFrameSource, exportPngFrames, exportVideo, mixAudio, premixTimelineAudio, requestWorkerExport, serveExportRequest };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@glissade/export-web",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "glissade in-browser export: WebCodecs VideoEncoder + Mediabunny muxing, OfflineAudioContext audio mix. Frame-accurate, faster than realtime, no server.",
   "license": "Apache-2.0",
   "type": "module",
@@ -16,9 +16,9 @@
   ],
   "dependencies": {
     "mediabunny": "^1.0.0",
-    "@glissade/backend-canvas2d": "0.2.0",
-    "@glissade/core": "0.2.0",
-    "@glissade/scene": "0.2.0"
+    "@glissade/backend-canvas2d": "0.3.0",
+    "@glissade/core": "0.3.0",
+    "@glissade/scene": "0.3.0"
   },
   "repository": {
     "type": "git",