@hypit/hypit 0.0.1 → 0.1.1

package/packages/media-execution/src/toolchain.ts

@@ -0,0 +1,81 @@
+import { execFile } from "node:child_process";
+
+export type MediaToolchainState =
+  | { readonly state: "ready"; readonly ffprobeVersion: string; readonly ffmpegVersion?: string }
+  | { readonly state: "down" | "mismatch"; readonly detail: string };
+
+const REQUIRED_ENCODERS = ["aac", "libx264", "pcm_s16le"] as const;
+const REQUIRED_FILTERS = [
+  "aformat", "amix", "aresample", "asetpts", "atempo", "atrim",
+  "loop", "pad", "scale", "select", "setpts", "setsar", "trim",
+] as const;
+
+function run(executable: string, args: readonly string[]): Promise<{ ok: boolean; output: string }> {
+  return new Promise((resolve) => {
+    execFile(executable, [...args], {
+      timeout: 15_000,
+      shell: false,
+      windowsHide: true,
+      maxBuffer: 4 * 1024 * 1024,
+    }, (error, stdout, stderr) => {
+      resolve(error === null
+        ? { ok: true, output: stdout.trim() }
+        : { ok: false, output: (stderr.trim() || error.message).split("\n").at(-1) ?? "" });
+    });
+  });
+}
+
+function firstLine(value: string): string {
+  return value.split(/\r?\n/u, 1)[0]?.trim() ?? "";
+}
+
+function missingNames(output: string, required: readonly string[]): readonly string[] {
+  return required.filter((name) => !new RegExp(`(?:^|\\s)${name.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&")}(?:\\s|$)`, "mu")
+    .test(output));
+}
+
+/**
+ * Compatibility probe for a deployment-owned FFmpeg toolchain. It deliberately
+ * checks the commands the shared execution body uses instead of requiring one
+ * blessed version number. A managed distribution may pin binaries separately;
+ * a custom installation remains valid when it supplies the same capability.
+ */
+export async function probeMediaToolchain(options: {
+  readonly ffprobePath: string;
+  readonly ffmpegPath?: string;
+}): Promise<MediaToolchainState> {
+  const probeVersion = await run(options.ffprobePath, ["-version"]);
+  if (!probeVersion.ok) {
+    return { state: "down", detail: `${options.ffprobePath} is unavailable: ${probeVersion.output}` };
+  }
+  const ffprobeVersion = firstLine(probeVersion.output);
+  if (ffprobeVersion.length === 0) return { state: "mismatch", detail: "ffprobe returned no version" };
+  if (options.ffmpegPath === undefined) return { state: "ready", ffprobeVersion };
+
+  const [ffmpegVersionResult, encoders, filters] = await Promise.all([
+    run(options.ffmpegPath, ["-version"]),
+    run(options.ffmpegPath, ["-hide_banner", "-encoders"]),
+    run(options.ffmpegPath, ["-hide_banner", "-filters"]),
+  ]);
+  if (!ffmpegVersionResult.ok) {
+    return { state: "down", detail: `${options.ffmpegPath} is unavailable: ${ffmpegVersionResult.output}` };
+  }
+  if (!encoders.ok || !filters.ok) {
+    return { state: "mismatch", detail: "ffmpeg could not enumerate its encoders and filters" };
+  }
+  const missingEncoders = missingNames(encoders.output, REQUIRED_ENCODERS);
+  const missingFilters = missingNames(filters.output, REQUIRED_FILTERS);
+  if (missingEncoders.length > 0 || missingFilters.length > 0) {
+    return {
+      state: "mismatch",
+      detail: [
+        missingEncoders.length === 0 ? "" : `missing encoders ${missingEncoders.join(", ")}`,
+        missingFilters.length === 0 ? "" : `missing filters ${missingFilters.join(", ")}`,
+      ].filter(Boolean).join("; "),
+    };
+  }
+  const ffmpegVersion = firstLine(ffmpegVersionResult.output);
+  return ffmpegVersion.length === 0
+    ? { state: "mismatch", detail: "ffmpeg returned no version" }
+    : { state: "ready", ffprobeVersion, ffmpegVersion };
+}

package/packages/media-execution/src/webp.ts

@@ -0,0 +1,200 @@
+export type AnimatedWebpFrame = {
+  readonly x: number;
+  readonly y: number;
+  readonly width: number;
+  readonly height: number;
+  readonly durationMs: number;
+  readonly disposeToBackground: boolean;
+  readonly blend: boolean;
+  readonly image: Uint8Array;
+};
+
+export type AnimatedWebp = {
+  readonly width: number;
+  readonly height: number;
+  readonly background: readonly [number, number, number, number];
+  readonly loopCount: number;
+  readonly frames: readonly AnimatedWebpFrame[];
+};
+
+function ascii(bytes: Uint8Array, start: number, length: number): string {
+  return String.fromCharCode(...bytes.subarray(start, start + length));
+}
+
+function u24(bytes: Uint8Array, offset: number): number {
+  return bytes[offset]! | bytes[offset + 1]! << 8 | bytes[offset + 2]! << 16;
+}
+
+function u32(bytes: Uint8Array, offset: number): number {
+  return new DataView(bytes.buffer, bytes.byteOffset + offset, 4).getUint32(0, true);
+}
+
+function chunk(id: string, payload: Uint8Array): Uint8Array {
+  const result = new Uint8Array(8 + payload.byteLength + (payload.byteLength & 1));
+  for (let index = 0; index < 4; index += 1) result[index] = id.charCodeAt(index);
+  new DataView(result.buffer).setUint32(4, payload.byteLength, true);
+  result.set(payload, 8);
+  return result;
+}
+
+function riff(chunks: readonly Uint8Array[]): Uint8Array {
+  const payloadBytes = chunks.reduce((sum, value) => sum + value.byteLength, 0);
+  const result = new Uint8Array(12 + payloadBytes);
+  result.set([0x52, 0x49, 0x46, 0x46], 0);
+  new DataView(result.buffer).setUint32(4, 4 + payloadBytes, true);
+  result.set([0x57, 0x45, 0x42, 0x50], 8);
+  let offset = 12;
+  for (const value of chunks) {
+    result.set(value, offset);
+    offset += value.byteLength;
+  }
+  return result;
+}
+
+function frameImage(payload: Uint8Array, width: number, height: number): Uint8Array {
+  const chunks: Uint8Array[] = [];
+  let offset = 0;
+  let hasAlpha = false;
+  while (offset + 8 <= payload.byteLength) {
+    const id = ascii(payload, offset, 4);
+    const size = u32(payload, offset + 4);
+    const end = offset + 8 + size;
+    if (end > payload.byteLength) throw new Error("Animated WebP frame chunk is truncated");
+    if (id === "ALPH") hasAlpha = true;
+    if (id === "ALPH" || id === "VP8 " || id === "VP8L") {
+      chunks.push(chunk(id, payload.subarray(offset + 8, end)));
+    }
+    offset = end + (size & 1);
+  }
+  if (!chunks.some((value) => ascii(value, 0, 4) === "VP8 " || ascii(value, 0, 4) === "VP8L")) {
+    throw new Error("Animated WebP frame has no image payload");
+  }
+  if (hasAlpha && chunks.some((value) => ascii(value, 0, 4) === "VP8 ")) {
+    const extended = new Uint8Array(10);
+    extended[0] = 0x10;
+    const widthMinusOne = width - 1;
+    const heightMinusOne = height - 1;
+    extended[4] = widthMinusOne & 0xff;
+    extended[5] = widthMinusOne >> 8 & 0xff;
+    extended[6] = widthMinusOne >> 16 & 0xff;
+    extended[7] = heightMinusOne & 0xff;
+    extended[8] = heightMinusOne >> 8 & 0xff;
+    extended[9] = heightMinusOne >> 16 & 0xff;
+    chunks.unshift(chunk("VP8X", extended));
+  }
+  return riff(chunks);
+}
+
+/** Parse only the animated WebP container facts FFmpeg currently cannot expose. */
+export function parseAnimatedWebp(bytes: Uint8Array): AnimatedWebp | undefined {
+  if (bytes.byteLength < 12 || ascii(bytes, 0, 4) !== "RIFF" || ascii(bytes, 8, 4) !== "WEBP") return undefined;
+  const declaredEnd = 8 + u32(bytes, 4);
+  if (declaredEnd > bytes.byteLength || declaredEnd < 12) throw new Error("WebP RIFF size is invalid");
+  let width: number | undefined;
+  let height: number | undefined;
+  let background: readonly [number, number, number, number] = [0, 0, 0, 0];
+  let loopCount = 0;
+  const frames: AnimatedWebpFrame[] = [];
+  let offset = 12;
+  while (offset + 8 <= declaredEnd) {
+    const id = ascii(bytes, offset, 4);
+    const size = u32(bytes, offset + 4);
+    const start = offset + 8;
+    const end = start + size;
+    if (end > declaredEnd) throw new Error(`WebP ${id} chunk is truncated`);
+    const payload = bytes.subarray(start, end);
+    if (id === "VP8X") {
+      if (size !== 10) throw new Error("WebP VP8X chunk is invalid");
+      width = u24(payload, 4) + 1;
+      height = u24(payload, 7) + 1;
+    } else if (id === "ANIM") {
+      if (size !== 6) throw new Error("WebP ANIM chunk is invalid");
+      background = [payload[2]!, payload[1]!, payload[0]!, payload[3]!];
+      loopCount = payload[4]! | payload[5]! << 8;
+    } else if (id === "ANMF") {
+      if (size < 16) throw new Error("WebP ANMF chunk is invalid");
+      const frameWidth = u24(payload, 6) + 1;
+      const frameHeight = u24(payload, 9) + 1;
+      const durationMs = u24(payload, 12);
+      if (durationMs < 1) throw new Error("Animated WebP frame duration must be positive");
+      frames.push({
+        x: u24(payload, 0) * 2,
+        y: u24(payload, 3) * 2,
+        width: frameWidth,
+        height: frameHeight,
+        durationMs,
+        disposeToBackground: (payload[15]! & 1) !== 0,
+        blend: (payload[15]! & 2) === 0,
+        image: frameImage(payload.subarray(16), frameWidth, frameHeight),
+      });
+    }
+    offset = end + (size & 1);
+  }
+  if (frames.length === 0) return undefined;
+  if (width === undefined || height === undefined) throw new Error("Animated WebP has no canvas size");
+  if (frames.some((frame) => frame.x + frame.width > width! || frame.y + frame.height > height!)) {
+    throw new Error("Animated WebP frame escapes its canvas");
+  }
+  return { width, height, background, loopCount, frames };
+}
+
+function clear(canvas: Uint8Array, animation: AnimatedWebp, frame: AnimatedWebpFrame): void {
+  for (let y = frame.y; y < frame.y + frame.height; y += 1) {
+    for (let x = frame.x; x < frame.x + frame.width; x += 1) {
+      const target = (y * animation.width + x) * 4;
+      canvas.set(animation.background, target);
+    }
+  }
+}
+
+function blendPixel(canvas: Uint8Array, target: number, source: Uint8Array, sourceOffset: number): void {
+  const sourceAlpha = source[sourceOffset + 3]!;
+  if (sourceAlpha === 255) {
+    canvas.set(source.subarray(sourceOffset, sourceOffset + 4), target);
+    return;
+  }
+  if (sourceAlpha === 0) return;
+  const destinationAlpha = canvas[target + 3]!;
+  const inverse = 255 - sourceAlpha;
+  const outputAlpha255 = sourceAlpha * 255 + destinationAlpha * inverse;
+  for (let channel = 0; channel < 3; channel += 1) {
+    const numerator = source[sourceOffset + channel]! * sourceAlpha * 255
+      + canvas[target + channel]! * destinationAlpha * inverse;
+    canvas[target + channel] = Math.round(numerator / outputAlpha255);
+  }
+  canvas[target + 3] = Math.round(outputAlpha255 / 255);
+}
+
+export function compositeAnimatedWebpFrame(
+  canvas: Uint8Array,
+  animation: AnimatedWebp,
+  frame: AnimatedWebpFrame,
+  decoded: Uint8Array,
+): Uint8Array {
+  if (decoded.byteLength !== frame.width * frame.height * 4) {
+    throw new Error("Decoded WebP frame dimensions differ from the container");
+  }
+  for (let y = 0; y < frame.height; y += 1) {
+    for (let x = 0; x < frame.width; x += 1) {
+      const source = (y * frame.width + x) * 4;
+      const target = ((frame.y + y) * animation.width + frame.x + x) * 4;
+      if (frame.blend) blendPixel(canvas, target, decoded, source);
+      else canvas.set(decoded.subarray(source, source + 4), target);
+    }
+  }
+  const snapshot = canvas.slice();
+  if (frame.disposeToBackground) clear(canvas, animation, frame);
+  return snapshot;
+}
+
+export function createAnimatedWebpCanvas(animation: AnimatedWebp): Uint8Array {
+  const canvas = new Uint8Array(animation.width * animation.height * 4);
+  for (let offset = 0; offset < canvas.byteLength; offset += 4) canvas.set(animation.background, offset);
+  return canvas;
+}
+
+export function pamRgba(width: number, height: number, rgba: Uint8Array): Uint8Array {
+  if (rgba.byteLength !== width * height * 4) throw new Error("PAM frame byte count is invalid");
+  const header = Buffer.from(`P7\nWIDTH ${width}\nHEIGHT ${height}\nDEPTH 4\nMAXVAL 255\nTUPLTYPE RGB_ALPHA\nENDHDR\n`, "ascii");
+  return Buffer.concat([header, rgba]);
+}

package/packages/media-pipeline/README.md

@@ -0,0 +1,113 @@
+# `@hypit/media-pipeline`
+
+Provider-neutral media execution vocabulary. Ingestion contributes one ordinary finite Fragment:
+
+```text
+BlobArtifact
+  -> inspect-media Need
+  -> MediaInspection
+  -> deterministic stream selection
+  -> MediaStreamSelection
+  -> normalize-media Need
+  -> SynchronizedMedia
+```
+
+`MediaInspection` enumerates every container stream. The default moving-video policy excludes
+`attached_pic` streams, prefers one declared default, accepts one unambiguous remaining candidate,
+and otherwise fails closed. An explicit stream index is available when the author module genuinely
+knows which alternate stream it wants.
+
+Selecting embedded audio is a media fact only. This package never assigns Script meaning. A later
+speech alignment component binds one normalized Take to one authored Segment.
+
+The current normalization profile uses one source presentation origin, a requested rational video frame
+rate, and a 48 kHz stereo PCM render stem. It preserves input level: loudness/mastering remains a
+separate author policy. Its public `SynchronizedMedia` waist carries only the common frame domain,
+optional visual Artifact plus intrinsic extent, and optional audio Artifact. Stream indexes,
+authority choice and the trim/pad ledger remain in Selection and execution instead of travelling
+through every consumer.
+
+Normalization preserves transparency in the selected visual stream. The executing Provider owns
+the intermediate encoding; both opaque and transparent pictures use the same SynchronizedMedia
+value. A later SemanticTake adds Script timing while retaining that prepared media. A visual
+overlay can instead enter Media Track directly.
+
+This package is the shared execution vocabulary. Speech authoring makes the boundary explicit:
+`<pipeline:Normalize>` produces one `SynchronizedMedia`, then a speech provider and deterministic
+alignment produce one `SemanticTake`. Media Track consumes that prepared value; it never owns an
+implicit visual-only normalization policy.
+
+The frame clock is a separate program fact and can be shared by every Normalize and Speech Track:
+
+```svml
+<program:Clock id="clock" frame-rate="30"/>
+<pipeline:Normalize id="shot-media" source={shot.video}
+  recipe={recipes.media.aroll} clock={clock}/>
+```
+
+An SVS recipe may centralize the stream policy (`video`, `audio` and `span-authority`); it does not
+hide the Normalize graph node or turn multiple sources into one opaque batch operation.
+
+A still image becomes ordinary video before it enters that waist:
+
+```svml
+<media:StillVideo id="opening-still" source={opening-head.image}
+  duration="6" clock={clock}/>
+<pipeline:Normalize id="opening-media" source={opening-still.video}
+  video="primary-moving" audio="none" span-authority="video" clock={clock}/>
+```
+
+Several images spread over one literal duration the same way, each held for its share of the frames:
+
+```svml
+<media:StillVideo id="kitchen-stills" duration="6" clock={clock}>
+  <media:Still source={counter.image}/>
+  <media:Still source={basil.image} weight="2"/>
+  <media:Still source={board.image}/>
+</media:StillVideo>
+```
+
+`StillVideo` returns a video-only MP4 `BlobArtifact`, not `SynchronizedMedia`. The Surface publishes the
+duration and the weights as Records; `plan-still-video` divides the whole frame count among the
+pictures (every picture holds at least one frame, the rest go by weight with leftovers to the largest
+remainders, earlier first), `bind-still-video-source` attaches each picture in authored order, and
+encoding is one `render-still-video` Need. Pictures of different sizes are fitted into the first one's
+frame and letterboxed. Inspection and normalization remain the same explicit steps used by imported
+or generated moving video. The resulting Blob is ordinary time-bearing visual media. Its later role
+comes entirely from the downstream Source relationships; StillVideo itself owns only the authored
+images, duration and frame clock.
+
+The package also exposes the one-picture Run Fragment `still-video`. It takes `duration`, `clock`,
+`layout` and `source-0`. A Run can select its `video` export as a Candidate through `satisfy`.
+
+Four ordinary author operations reuse that same inspection/execution boundary:
+
+```xml
+<pipeline:Normalize id="shot-media" source={shot.video}
+  video="primary-moving" audio="default" span-authority="video" clock={clock}/>
+<media:Transform id="prepared" source={shot-media.media}>
+  <media:Trim tail="0.25s"/>
+  <media:Retime rate="1.05" pitch="preserve"/>
+</media:Transform>
+
+<media:ExtractAudio id="voice-reference" source={prepared.video} audio="default"/>
+<media:ExtractFrame id="continuity" source={prepared.video} video="primary-moving" at="last"/>
+```
+
+Every result is an ordinary `BlobArtifact`. Audio extraction emits a deterministic 48 kHz stereo PCM
+WAV but makes no `SemanticTake`, speaker or alignment claim; it can therefore feed a later model
+reference port directly. Frame extraction supports `first`, `last`, `frame:<index>` and
+`time:<seconds>`. Transform operations are ordered author meaning and never an arbitrary FFmpeg string.
+
+The same package also owns two provider-neutral media completion plans/capabilities:
+
+```text
+Composition -> pure AudioProgramPlan -> render-timeline-audio Need -> TimelineAudio
+RenderedVisual + TimelineAudio -> mux-program-media Need -> MuxedMedia
+```
+
+Compiling an `AudioProgramPlan` is ordinary deterministic code. Reading Artifact bytes, decoding,
+resampling, mixing, encoding or muxing is never a Producer shortcut: it is an explicit Provider
+Need. The plan fixes exact 48 kHz sample boundaries, gain/fade/playback parameters and the absence
+of hidden normalization/limiting. The local FFmpeg and AWS Lambda Providers consume the same shared
+execution body and return the same public contracts.

package/packages/media-pipeline/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@hypit/media-pipeline",
+  "version": "0.0.0-dev",
+  "license": "SEE LICENSE IN LICENSE",
+  "private": true,
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "hypit": {
+    "activation": "./src/activation.ts"
+  },
+  "dependencies": {
+    "@hypit/artifact": "workspace:*",
+    "@hypit/component-kit": "workspace:*",
+    "@hypit/composition": "workspace:*",
+    "@hypit/elaborator": "workspace:*",
+    "@hypit/media": "workspace:*",
+    "@hypit/narrative": "workspace:*",
+    "@hypit/program-space": "workspace:*",
+    "@hypit/protocol": "workspace:*",
+    "@hypit/run": "workspace:*",
+    "@hypit/speech": "workspace:*",
+    "@hypit/svs": "workspace:*",
+    "@hypit/markup": "workspace:*"
+  }
+}

package/packages/media-pipeline/src/activation.ts

@@ -0,0 +1,47 @@
+import { createMarkupSurfaceHostFacet } from "@hypit/markup";
+import { createRunFragmentHostFacet } from "@hypit/run";
+import {
+  decodeSynchronizedMediaSurface,
+  decodeStillVideoSurface,
+  decodeExtractAudioSurface,
+  decodeExtractFrameSurface,
+  decodeTransformMediaSurface,
+  mediaPipelineComponent,
+  mediaPipelineManifest,
+  mediaPipelineModuleRef,
+  mediaPipelineMarkupSurfaces,
+  stillVideoFragment,
+} from "./index.js";
+
+export const hypitPackage = {
+  format: "hypit.node-package@1" as const,
+  modules: [{ manifest: mediaPipelineManifest }],
+  components: [mediaPipelineComponent],
+  hostFacets: [createRunFragmentHostFacet({
+    name: "@hypit/media-pipeline@1",
+    fragments: {
+      "still-video": stillVideoFragment,
+    },
+  }), createMarkupSurfaceHostFacet({
+    module: mediaPipelineModuleRef,
+    declaration: mediaPipelineMarkupSurfaces.find((item) => item.name === "synchronized-media")!,
+    handler: decodeSynchronizedMediaSurface,
+  }), createMarkupSurfaceHostFacet({
+    module: mediaPipelineModuleRef,
+    declaration: mediaPipelineMarkupSurfaces.find((item) => item.name === "still-video")!,
+    handler: decodeStillVideoSurface,
+  }), createMarkupSurfaceHostFacet({
+    module: mediaPipelineModuleRef,
+    declaration: mediaPipelineMarkupSurfaces.find((item) => item.name === "transform-media")!,
+    handler: decodeTransformMediaSurface,
+  }), createMarkupSurfaceHostFacet({
+    module: mediaPipelineModuleRef,
+    declaration: mediaPipelineMarkupSurfaces.find((item) => item.name === "extract-audio")!,
+    handler: decodeExtractAudioSurface,
+  }), createMarkupSurfaceHostFacet({
+    module: mediaPipelineModuleRef,
+    declaration: mediaPipelineMarkupSurfaces.find((item) => item.name === "extract-frame")!,
+    handler: decodeExtractFrameSurface,
+  })],
+};
+export default hypitPackage;

package/packages/media-pipeline/src/audio-plan.ts

@@ -0,0 +1,113 @@
+import { programFrameSampleBoundary, programSpaceFrameCount } from "@hypit/program-space";
+import type { ProgramSpace } from "@hypit/program-space";
+import { assertCompositionIdentity } from "@hypit/composition";
+import type { Composition } from "@hypit/composition";
+import { canonicalize, isResourceId } from "@hypit/protocol";
+
+import type { AudioProgramPlan } from "./types.js";
+
+function assert(condition: unknown, message: string): asserts condition {
+  if (!condition) throw new Error(message);
+}
+
+export function sealAudioProgramPlan(value: AudioProgramPlan): AudioProgramPlan {
+  return canonicalize(value) as unknown as AudioProgramPlan;
+}
+
+export function verifyAudioProgramPlan(value: unknown): asserts value is AudioProgramPlan {
+  assert(value !== null && typeof value === "object" && !Array.isArray(value), "AudioProgramPlan must be an object");
+  const item = value as AudioProgramPlan;
+  assert(Number.isSafeInteger(item.frameRate?.numerator) && item.frameRate.numerator > 0
+    && Number.isSafeInteger(item.frameRate?.denominator) && item.frameRate.denominator > 0,
+  "AudioProgramPlan frame rate is invalid");
+  assert(Number.isSafeInteger(item.frameCount) && item.frameCount > 0, "AudioProgramPlan frame count is invalid");
+  assert(item.sampleRate === 48_000, "AudioProgramPlan sample rate must be 48000");
+  const planSpace = {
+    id: "audio-program-plan",
+    durationSec: item.frameCount * item.frameRate.denominator / item.frameRate.numerator,
+    frameRate: item.frameRate,
+  };
+  assert(item.sampleFrames === programFrameSampleBoundary(planSpace, item.frameCount, 48_000),
+    "AudioProgramPlan sample count differs from its frame domain");
+  assert(Array.isArray(item.clips), "AudioProgramPlan clips are invalid");
+  const ids = new Set<string>();
+  for (const clip of item.clips) {
+    assert(typeof clip.id === "string" && clip.id.length > 0 && !ids.has(clip.id),
+      "AudioProgramPlan clip id is empty or repeated");
+    ids.add(clip.id);
+    assert(clip.artifact?.kind === "blob" && isResourceId(clip.artifact.resource)
+      && Number.isSafeInteger(clip.artifact.size) && clip.artifact.size >= 0
+      && clip.artifact.mediaType === "audio/wav",
+    `AudioProgramPlan clip ${clip.id} must reference canonical WAV`);
+    assert(Number.isSafeInteger(clip.targetStartSample) && clip.targetStartSample >= 0
+      && Number.isSafeInteger(clip.targetEndSampleExclusive)
+      && clip.targetEndSampleExclusive > clip.targetStartSample
+      && clip.targetEndSampleExclusive <= item.sampleFrames,
+    `AudioProgramPlan clip ${clip.id} target interval is invalid`);
+    assert(Number.isSafeInteger(clip.sourceStartSample) && clip.sourceStartSample >= 0,
+      `AudioProgramPlan clip ${clip.id} source start is invalid`);
+    assert(Number.isSafeInteger(clip.sourceSampleFrames) && clip.sourceSampleFrames > 0
+      && Number.isSafeInteger(clip.sourceEndSampleExclusive)
+      && clip.sourceEndSampleExclusive > clip.sourceStartSample
+      && clip.sourceEndSampleExclusive <= clip.sourceSampleFrames,
+    `AudioProgramPlan clip ${clip.id} source interval is invalid`);
+    const sourceLength = clip.sourceEndSampleExclusive - clip.sourceStartSample;
+    assert(typeof clip.sourceLoop === "boolean"
+      && Number.isSafeInteger(clip.sourcePhaseSample) && clip.sourcePhaseSample >= 0
+      && clip.sourcePhaseSample < sourceLength
+      && (clip.sourceLoop || clip.sourcePhaseSample === 0),
+    `AudioProgramPlan clip ${clip.id} loop phase is invalid`);
+    assert(Number.isFinite(clip.playbackRate) && clip.playbackRate > 0 && clip.playbackRate <= 100,
+      `AudioProgramPlan clip ${clip.id} playback rate is invalid`);
+    assert(clip.pitch === "preserve", `AudioProgramPlan clip ${clip.id} pitch policy is invalid`);
+    assert(Number.isFinite(clip.gain) && clip.gain >= 0 && clip.gain <= 64,
+      `AudioProgramPlan clip ${clip.id} gain is invalid`);
+    const length = clip.targetEndSampleExclusive - clip.targetStartSample;
+    assert(Number.isSafeInteger(clip.fadeInSamples) && clip.fadeInSamples >= 0 && clip.fadeInSamples <= length
+      && Number.isSafeInteger(clip.fadeOutSamples) && clip.fadeOutSamples >= 0 && clip.fadeOutSamples <= length,
+    `AudioProgramPlan clip ${clip.id} fade is invalid`);
+  }
+  assert(item.mix?.normalize === false && item.mix?.limiter === "none",
+    "AudioProgramPlan cannot hide normalization or limiting");
+}
+
+export function compileAudioProgramPlan(composition: Composition, programSpace: ProgramSpace): AudioProgramPlan {
+  assertCompositionIdentity(composition, programSpace);
+  const frameCount = programSpaceFrameCount(programSpace);
+  const clips = composition.tracks
+    .filter((track) => track.kind === "audio")
+    .flatMap((track) => track.clips.map((clip) => {
+      if (clip.artifact.mediaType !== "audio/wav") {
+        throw new Error(`Audio clip ${track.id}.${clip.id} must be normalized to canonical WAV before mixing`);
+      }
+      return {
+        id: `${track.id}:${clip.id}`,
+        artifact: {
+          kind: "blob" as const,
+          resource: clip.artifact.resource,
+          size: clip.artifact.size,
+          mediaType: clip.artifact.mediaType,
+        },
+        targetStartSample: clip.target.startSample,
+        targetEndSampleExclusive: clip.target.endSampleExclusive,
+        sourceSampleFrames: clip.source.sampleFrames,
+        sourceStartSample: clip.source.startSample,
+        sourceEndSampleExclusive: clip.source.endSampleExclusive,
+        sourceLoop: clip.source.loop,
+        sourcePhaseSample: clip.source.phaseSample,
+        playbackRate: clip.playbackRate,
+        pitch: clip.pitch,
+        gain: clip.gain,
+        fadeInSamples: clip.fadeInSamples,
+        fadeOutSamples: clip.fadeOutSamples,
+      };
+    }));
+  return sealAudioProgramPlan({
+    frameRate: { ...programSpace.frameRate },
+    frameCount,
+    sampleRate: 48_000,
+    sampleFrames: programFrameSampleBoundary(programSpace, frameCount, 48_000),
+    clips,
+    mix: { normalize: false, limiter: "none" },
+  });
+}