@vgai/engine 0.2.0 → 0.4.0-canary.20260715.0

package/src/audio/tone-offline-render.ts

@@ -0,0 +1,167 @@
+import { Offline } from 'tone';
+
+/**
+ * G2 — Integrate Tone with the Canonical Clock, OFFLINE-render half (spec
+ * §13 G2, and the G4/I6 seam it is deliberately shaped for). This module
+ * renders a Tone composition over an exact `[start, end)` time range to a
+ * real `AudioBuffer` via `Tone.Offline` — i.e. `OfflineAudioContext`, NOT a
+ * live real-time `AudioContext` — such that identical inputs produce
+ * bit-identical output samples on every call. This is what makes offline
+ * Tone audio safe to mux into a deterministically-rendered video (G4/I6):
+ * the video side already re-renders frame-by-frame from an exact clock
+ * position, and this is the audio side's equivalent — an exact re-render
+ * from an exact time range, not a live capture of whatever happened to play.
+ *
+ * ## Why this can't run in plain Node (documented, not assumed)
+ *
+ * `Tone.Offline` ultimately constructs a real `OfflineAudioContext`
+ * (via `standardized-audio-context`, Tone's own dependency). Node has no
+ * native Web Audio implementation, so `standardized-audio-context` throws
+ * `"Missing the native OfflineAudioContext constructor."` the moment
+ * `Tone.Offline(...)` is actually invoked — confirmed empirically against
+ * this repo's installed `tone@15.1.22` before writing this module (plain
+ * `import * as Tone from 'tone'` succeeds; calling `Tone.Offline(...)` in a
+ * Node process throws immediately). There is no lightweight polyfill in this
+ * repo's dependency tree, and installing a native Node Web Audio addon is
+ * out of scope for this unit (build-box constraints). The determinism proof
+ * for this module therefore runs in a REAL headless-Chromium page via
+ * Playwright — see `packages/engine/e2e/tests/tone-audio-g1-g2.spec.ts`
+ * — mirroring how I0 proved video-frame determinism. This module's own
+ * `packages/engine/test/audio/tone-offline-render.test.ts` covers everything
+ * that does NOT require a real `OfflineAudioContext` (range validation,
+ * synchronous pre-render cancellation) directly in Node.
+ *
+ * ## Composition contract
+ *
+ * `compose` is called by `Tone.Offline` itself, inside the offline context —
+ * build the SAME graph you would in real-time Tone code
+ * (`new Tone.Synth().toDestination()`, `context.transport.schedule(...)`,
+ * etc; see Tone's own `Offline` docs). Nothing about this wrapper changes
+ * Tone's native API surface — `compose`'s parameter is `Tone.Offline`'s own
+ * callback type, re-derived structurally (`Parameters<typeof Offline>[0]`)
+ * rather than duplicated, so this module can never drift from Tone's actual
+ * signature.
+ *
+ * ## Cancellation — cooperative, not a true mid-render abort
+ *
+ * The Web Audio spec gives `OfflineAudioContext` no `.close()`/cancel API
+ * once `startRendering()` is in flight, and neither does Tone. `signal`
+ * therefore provides COOPERATIVE cancellation only: if `signal` is already
+ * aborted before this function calls `Tone.Offline`, the render never
+ * starts at all (checked synchronously, before any `OfflineAudioContext` is
+ * created). If `signal` aborts WHILE a render is in flight, this function's
+ * returned promise rejects immediately with an `AbortError` — so a caller
+ * (e.g. a render-cancellation UI action) sees the render "stop" from its own
+ * perspective and never receives/uses the resulting buffer — even though
+ * the underlying browser-native render may keep running in the background
+ * until it would have finished anyway. This is an honest, documented
+ * limitation, not a gap: no browser API makes a stronger guarantee possible.
+ */
+
+/** Tone's own `Offline` callback signature, re-derived (not re-typed) so
+ *  this module can never drift from the real function it wraps. */
+export type ToneOfflineComposeFn = Parameters<typeof Offline>[0];
+
+export interface ToneOfflineRenderRequest {
+  /** Canonical/Theatre-time range start, in seconds. */
+  readonly start: number;
+  /** Canonical/Theatre-time range end, in seconds. Must be `> start`. */
+  readonly end: number;
+  /** Output sample rate. Default 44100 (CD-quality, FFmpeg's usual default). */
+  readonly sampleRate?: number;
+  /** Output channel count. Default 2 (stereo). */
+  readonly channels?: number;
+  /** Builds the Tone graph inside the offline context — Tone's native
+   *  `Offline` callback, unmodified. Receives local time `0` at `start`. */
+  readonly compose: ToneOfflineComposeFn;
+  /** Optional cooperative-cancellation signal — see module doc above. */
+  readonly signal?: AbortSignal;
+}
+
+export interface ToneOfflineRenderResult {
+  /** The rendered PCM, as a real (native) `AudioBuffer` — `.getChannelData(n)`
+   *  gives the Float32 samples for channel `n`, ready for a digest/RMS
+   *  computation or (eventually, G4/I6) FFmpeg muxing. */
+  readonly buffer: AudioBuffer;
+  readonly durationSeconds: number;
+  readonly sampleRate: number;
+  readonly channels: number;
+}
+
+const DEFAULT_SAMPLE_RATE = 44100;
+const DEFAULT_CHANNELS = 2;
+
+/** Render `request.compose`'s Tone graph offline over `[start, end)`,
+ *  producing a deterministic `AudioBuffer`. See module doc for the
+ *  determinism/cancellation contract. */
+export async function renderToneOffline(
+  request: ToneOfflineRenderRequest,
+): Promise<ToneOfflineRenderResult> {
+  const {
+    start,
+    end,
+    sampleRate = DEFAULT_SAMPLE_RATE,
+    channels = DEFAULT_CHANNELS,
+    compose,
+    signal,
+  } = request;
+
+  if (!Number.isFinite(start) || !Number.isFinite(end) || end <= start) {
+    throw new Error(
+      `[tone-offline-render] invalid range [${start}, ${end}) — end must be a finite number > start`,
+    );
+  }
+  if (!Number.isFinite(sampleRate) || sampleRate <= 0) {
+    throw new Error(
+      `[tone-offline-render] sampleRate must be a finite number > 0, got ${sampleRate}`,
+    );
+  }
+  if (!Number.isInteger(channels) || channels <= 0) {
+    throw new Error(`[tone-offline-render] channels must be a positive integer, got ${channels}`);
+  }
+  // Cooperative cancellation, checked BEFORE ever constructing an
+  // OfflineAudioContext — an already-aborted signal must never start a
+  // render at all (see module doc).
+  if (signal?.aborted) {
+    throw createAbortError();
+  }
+
+  const durationSeconds = end - start;
+  const renderPromise = Offline(compose, durationSeconds, channels, sampleRate);
+  const toneBuffer = signal ? await raceAbort(renderPromise, signal) : await renderPromise;
+  const buffer = toneBuffer.get();
+  if (!buffer) {
+    throw new Error('[tone-offline-render] Tone.Offline resolved without a decoded AudioBuffer');
+  }
+
+  return {
+    buffer,
+    durationSeconds,
+    sampleRate: buffer.sampleRate,
+    channels: buffer.numberOfChannels,
+  };
+}
+
+function createAbortError(): DOMException {
+  return new DOMException('[tone-offline-render] render canceled', 'AbortError');
+}
+
+/** Race `promise` against `signal` firing — resolves/rejects with whichever
+ *  happens first, without altering the underlying Web Audio render (see
+ *  module doc's "cooperative, not a true mid-render abort" section). */
+function raceAbort<T>(promise: Promise<T>, signal: AbortSignal): Promise<T> {
+  return new Promise<T>((resolve, reject) => {
+    const onAbort = () => reject(createAbortError());
+    signal.addEventListener('abort', onAbort, { once: true });
+    promise.then(
+      (value) => {
+        signal.removeEventListener('abort', onAbort);
+        resolve(value);
+      },
+      (err: unknown) => {
+        signal.removeEventListener('abort', onAbort);
+        reject(err);
+      },
+    );
+  });
+}

package/src/audio/wav-encode.ts

@@ -0,0 +1,119 @@
+/**
+ * Pure PCM -> 16-bit WAV encoder (spec §15 I6 "Encode and Mux", audio half —
+ * `docs/AI-NATIVE-AUTHORING-IMPLEMENTATION-SPEC.md`). This module takes
+ * already-rendered Float32 channel data (e.g. `AudioBuffer.getChannelData(n)`
+ * from a `Tone.Offline` render, `audio/tone-offline-render.ts`) and produces
+ * a standard little-endian, 16-bit-PCM, interleaved RIFF/WAVE file as raw
+ * bytes — no `AudioBuffer`/`AudioContext` dependency, so this runs equally in
+ * a browser render-mode page (`runtime/render-audio-control.ts`) and in
+ * plain Node (this module's own `packages/engine/test/audio/wav-encode.test.ts`,
+ * no Playwright needed).
+ *
+ * 16-bit PCM (not 32-bit float) is the deliberate choice named by the I6 AC
+ * ("16-bit PCM WAV is fine") — it is universally decodable by every FFmpeg
+ * build without an extra format flag, keeping the video-mux step's ffmpeg
+ * invocation ordinary and portable.
+ */
+
+export interface PcmToWavInput {
+  /** One `Float32Array` per channel, each sample in `[-1, 1]` (values outside
+   *  that range are clamped, not thrown on — real synthesis can transiently
+   *  clip). All channels must have equal length. */
+  readonly channelData: readonly Float32Array[];
+  readonly sampleRate: number;
+}
+
+const BYTES_PER_SAMPLE = 2; // 16-bit PCM
+const WAV_HEADER_BYTES = 44;
+
+function clamp(value: number, lo: number, hi: number): number {
+  return Math.min(hi, Math.max(lo, value));
+}
+
+function writeAsciiString(view: DataView, offset: number, text: string): void {
+  for (let i = 0; i < text.length; i++) {
+    view.setUint8(offset + i, text.charCodeAt(i));
+  }
+}
+
+/** Encode `input` as a complete little-endian, 16-bit-PCM, interleaved
+ *  RIFF/WAVE file (44-byte canonical header + data chunk). Throws on an
+ *  empty/mismatched channel set rather than silently producing a malformed
+ *  file — this module's own contribution to the "fail loudly, never a
+ *  silent no-op" convention `runtime/render-control.ts` documents. */
+export function encodeWav16(input: PcmToWavInput): Uint8Array {
+  const { channelData, sampleRate } = input;
+  const numChannels = channelData.length;
+  if (numChannels === 0) {
+    throw new Error('[wav-encode] channelData must contain at least one channel');
+  }
+  if (!Number.isFinite(sampleRate) || sampleRate <= 0) {
+    throw new Error(`[wav-encode] sampleRate must be a finite number > 0, got ${sampleRate}`);
+  }
+  const numFrames = channelData[0]?.length ?? 0;
+  for (let ch = 0; ch < numChannels; ch++) {
+    const len = channelData[ch]?.length ?? -1;
+    if (len !== numFrames) {
+      throw new Error(
+        `[wav-encode] channel ${ch} has length ${len}, expected ${numFrames} (all channels must match)`,
+      );
+    }
+  }
+
+  const blockAlign = numChannels * BYTES_PER_SAMPLE;
+  const byteRate = sampleRate * blockAlign;
+  const dataSize = numFrames * blockAlign;
+
+  const buffer = new ArrayBuffer(WAV_HEADER_BYTES + dataSize);
+  const view = new DataView(buffer);
+
+  // RIFF chunk descriptor
+  writeAsciiString(view, 0, 'RIFF');
+  view.setUint32(4, 36 + dataSize, true);
+  writeAsciiString(view, 8, 'WAVE');
+
+  // fmt subchunk (PCM)
+  writeAsciiString(view, 12, 'fmt ');
+  view.setUint32(16, 16, true); // subchunk size for PCM
+  view.setUint16(20, 1, true); // audio format 1 = PCM
+  view.setUint16(22, numChannels, true);
+  view.setUint32(24, sampleRate, true);
+  view.setUint32(28, byteRate, true);
+  view.setUint16(32, blockAlign, true);
+  view.setUint16(34, BYTES_PER_SAMPLE * 8, true); // bits per sample
+
+  // data subchunk
+  writeAsciiString(view, 36, 'data');
+  view.setUint32(40, dataSize, true);
+
+  let offset = WAV_HEADER_BYTES;
+  for (let i = 0; i < numFrames; i++) {
+    for (let ch = 0; ch < numChannels; ch++) {
+      const sample = clamp(channelData[ch]?.[i] ?? 0, -1, 1);
+      const intSample = Math.round(sample < 0 ? sample * 0x8000 : sample * 0x7fff);
+      view.setInt16(offset, intSample, true);
+      offset += BYTES_PER_SAMPLE;
+    }
+  }
+
+  return new Uint8Array(buffer);
+}
+
+/** RMS + peak over all channels/samples — the same "non-trivial audio, not
+ *  an all-zero buffer" sanity check `tone-audio-main.ts`'s fixture computes,
+ *  factored out here so both that fixture and the render-audio harness can
+ *  share one implementation instead of drifting copies. */
+export function pcmStats(channelData: readonly Float32Array[]): { rms: number; peak: number } {
+  let sumSquares = 0;
+  let peak = 0;
+  let count = 0;
+  for (const data of channelData) {
+    for (let i = 0; i < data.length; i++) {
+      const v = data[i] ?? 0;
+      sumSquares += v * v;
+      peak = Math.max(peak, Math.abs(v));
+      count++;
+    }
+  }
+  return { rms: count > 0 ? Math.sqrt(sumSquares / count) : 0, peak };
+}