@hypit/hypit 0.0.1 → 0.1.0

package/packages/audio-track/src/manifest.ts

@@ -0,0 +1,151 @@
+import { temporalContextAttributeVocabulary } from "@hypit/temporal-markup";
+import { compositionDependency, compositionTypes } from "@hypit/composition";
+import { mediaDependency, mediaTypes } from "@hypit/media";
+import { narrativeDependency } from "@hypit/narrative";
+import { programSpaceDependency, programSpaceTypes } from "@hypit/program-space";
+import { blobRefObjectSchema } from "@hypit/protocol";
+import type { ModuleManifest, ProducerRef, TypeRef, ValueSchema } from "@hypit/protocol";
+import { semanticTrackDependency } from "@hypit/semantic-track";
+import { temporalDependency, temporalTypes } from "@hypit/temporal";
+import { temporalWindowAttributeVocabulary } from "@hypit/temporal-markup";
+
+export const audioTrackModuleRef = { name: "@hypit/audio-track", version: "1" } as const;
+export const audioTrackTypes = {
+  header: { module: audioTrackModuleRef, name: "AudioTrackHeader" },
+  clipSpec: { module: audioTrackModuleRef, name: "AudioClipSpec" },
+  set: { module: audioTrackModuleRef, name: "AudioTrackSet" },
+  program: { module: audioTrackModuleRef, name: "AudioTrackProgram" },
+} satisfies Record<string, TypeRef>;
+export const audioTrackProducers = {
+  createSet: { module: audioTrackModuleRef, name: "create-audio-track-set" },
+  appendItem: { module: audioTrackModuleRef, name: "append-audio-item" },
+  finalize: { module: audioTrackModuleRef, name: "finalize-audio-track" },
+  render: { module: audioTrackModuleRef, name: "render-audio-track" },
+} satisfies Record<string, ProducerRef>;
+
+const string = { kind: "string", minLength: 1 } as const;
+const number = { kind: "number", minimum: 0 } as const;
+const integer = { kind: "number", integer: true, minimum: 0 } as const;
+const signedInteger = { kind: "number", integer: true } as const;
+const object = (fields: Readonly<Record<string, { readonly schema: ValueSchema; readonly optional?: boolean }>>): ValueSchema => ({ kind: "object", fields });
+const duration: ValueSchema = { kind: "oneOf", variants: [
+  object({ unit: { schema: { kind: "literal", value: "frames" } }, value: { schema: integer } }),
+  object({ unit: { schema: { kind: "literal", value: "milliseconds" } }, value: { schema: integer } }),
+  object({ unit: { schema: { kind: "literal", value: "seconds" } }, numerator: { schema: integer }, denominator: { schema: { kind: "number", integer: true, minimum: 1 } } }),
+] };
+const occupancy: ValueSchema = { kind: "oneOf", variants: [
+  object({ mode: { schema: { kind: "literal", value: "once" } }, align: { schema: { kind: "string", enum: ["start", "end"] } } }),
+  object({ mode: { schema: { kind: "literal", value: "loop" } }, align: { schema: { kind: "string", enum: ["start", "end"] } } }),
+  object({ mode: { schema: { kind: "literal", value: "stretch" } }, minRate: { schema: { kind: "number", minimum: 0.000001, maximum: 100 } }, maxRate: { schema: { kind: "number", minimum: 0.000001, maximum: 100 } }, pitch: { schema: { kind: "literal", value: "preserve" } } }),
+] };
+const clipSpec = object({
+
+  id: { schema: string },
+  trim: { schema: object({ start: { schema: duration, optional: true }, end: { schema: duration, optional: true } }) },
+  occupancy: { schema: occupancy },
+  mix: { schema: object({ gain: { schema: number }, fadeIn: { schema: duration }, fadeOut: { schema: duration } }) },
+});
+const frameSpan = object({ startFrame: { schema: integer }, endFrameExclusive: { schema: integer } });
+const resolvedOccupancy = occupancy;
+const item = object({
+  id: { schema: string }, window: { schema: frameSpan },
+  source: { schema: object({ artifact: { schema: blobRefObjectSchema(["audio/wav"]) }, sampleFrames: { schema: { kind: "number", integer: true, minimum: 1 } } }) },
+  trim: { schema: object({ startSample: { schema: integer }, endSampleExclusive: { schema: { kind: "number", integer: true, minimum: 1 } } }) },
+  occupancy: { schema: resolvedOccupancy },
+  mix: { schema: object({ gain: { schema: number }, fadeInSamples: { schema: integer }, fadeOutSamples: { schema: integer } }) },
+});
+export const audioTrackHeaderSchema: ValueSchema = object({
+  id: { schema: string },
+});
+export const audioClipSpecSchema: ValueSchema = clipSpec;
+export const audioTrackSetSchema: ValueSchema = object({
+  items: { schema: { kind: "array", items: item } },
+});
+export const audioTrackProgramSchema: ValueSchema = object({
+  id: { schema: string },
+  items: { schema: { kind: "array", minItems: 1, items: item } },
+});
+
+const baseInputs = [
+  { name: "set", type: audioTrackTypes.set }, { name: "header", type: audioTrackTypes.header },
+  { name: "space", type: programSpaceTypes.programSpace }, { name: "media", type: mediaTypes.synchronized },
+  { name: "spec", type: audioTrackTypes.clipSpec }, { name: "window", type: temporalTypes.window },
+] as const;
+
+export const audioTrackMarkupSurfaces = [{
+    name: "track", tag: "Track", mode: "structured",
+    outputs: [audioTrackTypes.header, audioTrackTypes.clipSpec, temporalTypes.instantSpec, temporalTypes.windowSpec, temporalTypes.instant, temporalTypes.window, audioTrackTypes.program, compositionTypes.audioTrack],
+    vocabulary: {
+      summary: "One Audio Track: explicitly prepared audio Clips placed on the selected film time axis and lowered to one ordinary peer AudioTrack.",
+      attributes: [
+        { name: "id", kind: "identifier", required: true, summary: "Names this Audio Track and prefixes the identity of every Clip that does not name itself." },
+        ...temporalContextAttributeVocabulary,
+      ],
+      children: [
+        { tag: "Clip", cardinality: "many",
+          summary: "Places one SynchronizedMedia source on an exact program window with its own trim, occupancy and mix.",
+          attributes: [
+            { name: "id", kind: "identifier", required: false,
+              summary: "Names this Clip; the Track derives `<track>.clip.<index>` when it is absent." },
+            { name: "source", kind: "reference", required: true,
+              accepts: [mediaTypes.synchronized],
+              summary: "Selects the explicitly prepared audio this Clip plays." },
+            ...temporalWindowAttributeVocabulary,
+            { name: "trim-start", kind: "literal", required: false,
+              summary: "Sets the source start position; defaults to the source beginning." },
+            { name: "trim-end", kind: "literal", required: false,
+              summary: "Sets the exclusive source end position; defaults to the source end, not a duration subtracted from its tail." },
+            { name: "playback", kind: "literal", required: false,
+              values: ["once", "once-start", "once-end", "loop", "loop-start", "loop-end", "stretch"],
+              summary: "Decides how the source occupies a window longer or shorter than itself; defaults to `once`." },
+            { name: "min-rate", kind: "literal", required: false,
+              summary: "Bounds the slowest rate bounded stretch may use." },
+            { name: "max-rate", kind: "literal", required: false,
+              summary: "Bounds the fastest rate bounded stretch may use." },
+            { name: "gain", kind: "literal", required: false,
+              summary: "Scales this Clip by a linear gain; defaults to `1`." },
+            { name: "fade-in", kind: "literal", required: false,
+              summary: "Fixes the exact fade-in length; defaults to `0f`." },
+            { name: "fade-out", kind: "literal", required: false,
+              summary: "Fixes the exact fade-out length; defaults to `0f`." },
+          ] },
+      ],
+      ports: [
+        { name: "program", type: audioTrackTypes.program, summary: "The resolved sample-exact item list this Track renders from." },
+        { name: "track", type: compositionTypes.audioTrack, summary: "The rendered AudioTrack that Film composes with its peers." },
+      ],
+      example: `<audio:Track id="music-bed" semantic={speech.semantic}>
+  <audio:Clip source={music-media.media} during="program"
+    playback="loop-end" gain="0.28" fade-in="600ms" fade-out="800ms"/>
+</audio:Track>`,
+      notes: [
+        "A Track requires at least one Clip, and neither a Track nor a Clip accepts text content.",
+        "A Clip states exactly one window form: `during`, `at` with `for`, `until` with `for`, or `start` with `end`.",
+        "A point expression is `program.start`, `program.end`, `selection.start`, `selection.end`, `segment.start`, `segment.end` or `moment.cue`, each optionally offset by `+` or `-` and a duration, or a bare duration read as an absolute position.",
+        "Bind selection, segment and/or moment only when the start/end expressions use them; different endpoints can use different bindings.",
+        "`min-rate` and `max-rate` are rejected unless `playback` is `stretch`.",
+      ],
+    },
+  }] as const;
+
+
+export const audioTrackManifest: ModuleManifest = {
+  format: "hypit.module@1",
+  name: audioTrackModuleRef.name,
+  version: audioTrackModuleRef.version,
+  dependencies: [mediaDependency, narrativeDependency, programSpaceDependency, semanticTrackDependency, temporalDependency, compositionDependency],
+  types: [
+    { name: audioTrackTypes.header.name },
+    { name: audioTrackTypes.clipSpec.name },
+    { name: audioTrackTypes.set.name },
+    { name: audioTrackTypes.program.name },
+  ],
+  capabilities: [],
+  producers: [
+    { name: audioTrackProducers.createSet.name, inputs: [], outputs: [{ name: "set", type: audioTrackTypes.set }], needs: [] },
+    { name: audioTrackProducers.appendItem.name, inputs: [...baseInputs], outputs: [{ name: "set", type: audioTrackTypes.set }], needs: [] },
+    { name: audioTrackProducers.finalize.name, inputs: [{ name: "set", type: audioTrackTypes.set }, { name: "header", type: audioTrackTypes.header }], outputs: [{ name: "program", type: audioTrackTypes.program }], needs: [] },
+    { name: audioTrackProducers.render.name, inputs: [{ name: "space", type: programSpaceTypes.programSpace }, { name: "program", type: audioTrackTypes.program }], outputs: [{ name: "track", type: compositionTypes.audioTrack }], needs: [] },
+  ],
+};
+export const audioTrackDependency = { module: audioTrackModuleRef } as const;

package/packages/audio-track/src/program.ts

@@ -0,0 +1,254 @@
+import { assertAudioTrackIdentity, sealAudioTrack } from "@hypit/composition";
+import type { AudioClip, AudioTrack } from "@hypit/composition";
+import { synchronizedMediaSampleFrames, verifySynchronizedMedia } from "@hypit/media";
+import type { SynchronizedMedia } from "@hypit/media";
+import {
+  assertProgramSpaceIdentity,
+  programFrameSampleBoundary,
+  programSpaceSampleFrames,
+} from "@hypit/program-space";
+import type { ProgramSpace } from "@hypit/program-space";
+import { canonicalize, isResourceId } from "@hypit/protocol";
+import { assertTemporalWindowFor, temporalDurationInSamples } from "@hypit/temporal";
+import type { ProjectedWindow, TemporalDuration } from "@hypit/temporal";
+
+import type {
+  AudioClipSpec,
+  AudioItemProgram,
+  AudioOccupancy,
+  AudioTrackHeader,
+  AudioTrackProgram,
+  AudioTrackSet,
+} from "./types.js";
+
+function assert(condition: unknown, message: string): asserts condition {
+  if (!condition) throw new Error(message);
+}
+
+function assertIdentity(value: string, label: string): void {
+  assert(/^[A-Za-z][A-Za-z0-9_.:#-]{0,191}$/u.test(value), `${label} is invalid.`);
+}
+
+function assertDuration(value: TemporalDuration, label: string, signed = false): void {
+  if (value.unit === "seconds") {
+    assert(Number.isSafeInteger(value.numerator) && (signed || value.numerator >= 0)
+      && Number.isSafeInteger(value.denominator) && value.denominator > 0, `${label} is invalid.`);
+  } else {
+    assert(Number.isSafeInteger(value.value) && (signed || value.value >= 0), `${label} is invalid.`);
+  }
+}
+
+function assertOccupancy(value: AudioOccupancy, label: string): void {
+  if (value.mode === "once" || value.mode === "loop") {
+    assert(value.align === "start" || value.align === "end", `${label} alignment is invalid.`);
+    return;
+  }
+  assert(value.mode === "stretch" && value.pitch === "preserve"
+    && Number.isFinite(value.minRate) && value.minRate > 0
+    && Number.isFinite(value.maxRate) && value.maxRate >= value.minRate && value.maxRate <= 100,
+  `${label} stretch bounds are invalid.`);
+}
+
+export function sealAudioTrackHeader(value: AudioTrackHeader): AudioTrackHeader {
+  assertAudioTrackHeader(value);
+  return canonicalize(value) as unknown as AudioTrackHeader;
+}
+
+export function assertAudioTrackHeader(value: AudioTrackHeader): void {
+  assertIdentity(value.id, "AudioTrackHeader.id");
+}
+
+export function sealAudioClipSpec(value: AudioClipSpec): AudioClipSpec {
+  assertAudioClipSpec(value);
+  return canonicalize(value) as unknown as AudioClipSpec;
+}
+
+export function assertAudioClipSpec(value: AudioClipSpec): void {
+  assertIdentity(value.id, "AudioClipSpec.id");
+  if (value.trim.start !== undefined) assertDuration(value.trim.start, "AudioClipSpec trim start");
+  if (value.trim.end !== undefined) assertDuration(value.trim.end, "AudioClipSpec trim end");
+  assertOccupancy(value.occupancy, "AudioClipSpec occupancy");
+  assert(Number.isFinite(value.mix.gain) && value.mix.gain >= 0 && value.mix.gain <= 64,
+    "AudioClipSpec gain is invalid.");
+  assertDuration(value.mix.fadeIn, "AudioClipSpec fade in");
+  assertDuration(value.mix.fadeOut, "AudioClipSpec fade out");
+}
+
+export function createAudioTrackSet(): AudioTrackSet {
+  return { items: [] };
+}
+
+export function assertAudioTrackSet(value: AudioTrackSet): void {
+  assert(Array.isArray(value.items), "AudioTrackSet is invalid.");
+}
+
+function sourceFacts(media: SynchronizedMedia): AudioItemProgram["source"] {
+  verifySynchronizedMedia(media);
+  assert(media.audio !== undefined, "Audio Track source has no explicitly normalized audio member.");
+  return {
+    artifact: structuredClone(media.audio.artifact),
+    sampleFrames: synchronizedMediaSampleFrames(media),
+  };
+}
+
+function realizedItems(
+  set: AudioTrackSet,
+  header: AudioTrackHeader,
+  space: ProgramSpace,
+  media: SynchronizedMedia,
+  spec: AudioClipSpec,
+  window: ProjectedWindow,
+): AudioTrackSet {
+  assertAudioTrackSet(set);
+  assertAudioTrackHeader(header);
+  assertProgramSpaceIdentity(space);
+  assertAudioClipSpec(spec);
+  assertTemporalWindowFor(window, { subjectId: spec.id, space });
+  const source = sourceFacts(media);
+  const trimStart = spec.trim.start === undefined ? 0 : temporalDurationInSamples(spec.trim.start, space);
+  const trimEnd = spec.trim.end === undefined ? source.sampleFrames : temporalDurationInSamples(spec.trim.end, space);
+  assert(trimStart >= 0 && trimStart < source.sampleFrames, `Audio Clip ${spec.id} trim start is outside its source.`);
+  assert(trimEnd > trimStart && trimEnd <= source.sampleFrames, `Audio Clip ${spec.id} trim end is outside its source.`);
+  const fadeInSamples = temporalDurationInSamples(spec.mix.fadeIn, space);
+  const fadeOutSamples = temporalDurationInSamples(spec.mix.fadeOut, space);
+  const addition = {
+    id: window.id,
+    subjectId: spec.id,
+    window: { ...window.span },
+    source: structuredClone(source),
+    trim: { startSample: trimStart, endSampleExclusive: trimEnd },
+    occupancy: structuredClone(spec.occupancy),
+    mix: { gain: spec.mix.gain, fadeInSamples, fadeOutSamples },
+  } satisfies AudioItemProgram;
+  const ids = new Set(set.items.map((item) => item.id));
+  assert(!ids.has(addition.id), `Audio Track ${header.id} already contains Item ${addition.id}.`);
+  return { items: [...set.items, addition] };
+}
+
+/** Component entry point: the Temporal module has already resolved the target window. */
+export function appendProjectedAudioItem(
+  set: AudioTrackSet,
+  header: AudioTrackHeader,
+  space: ProgramSpace,
+  media: SynchronizedMedia,
+  spec: AudioClipSpec,
+  window: ProjectedWindow,
+): AudioTrackSet {
+  return realizedItems(set, header, space, media, spec, window);
+}
+
+function normalizeProgram(value: AudioTrackProgram): AudioTrackProgram {
+  return {
+
+    id: value.id,
+    items: [...value.items].map((item) => structuredClone(item)).sort((left, right) => left.id.localeCompare(right.id)),
+  };
+}
+
+export function sealAudioTrackProgram(value: AudioTrackProgram): AudioTrackProgram {
+  const normalized = normalizeProgram(value);
+  assertAudioTrackProgram(normalized);
+  return canonicalize(normalized) as unknown as AudioTrackProgram;
+}
+
+export function finalizeAudioTrack(set: AudioTrackSet, header: AudioTrackHeader): AudioTrackProgram {
+  assertAudioTrackSet(set);
+  assertAudioTrackHeader(header);
+  assert(set.items.length > 0, "Audio Track requires at least one Item.");
+  return sealAudioTrackProgram({ id: header.id, items: set.items });
+}
+
+export function assertAudioTrackProgram(value: AudioTrackProgram): void {
+  assertIdentity(value.id, "AudioTrackProgram.id");
+  assert(value.items.length > 0, "AudioTrackProgram requires at least one Item.");
+  const ids = new Set<string>();
+  for (const item of value.items) {
+    assertIdentity(item.id, "AudioItemProgram.id");
+    assertIdentity(item.subjectId, "AudioItemProgram.subjectId");
+    assert(!ids.has(item.id), `AudioTrackProgram contains duplicate Item ${item.id}.`);
+    ids.add(item.id);
+    assert(Number.isSafeInteger(item.window.startFrame) && item.window.startFrame >= 0
+      && Number.isSafeInteger(item.window.endFrameExclusive)
+      && item.window.endFrameExclusive > item.window.startFrame, `Audio Item ${item.id} window is invalid.`);
+    assert(isResourceId(item.source.artifact.resource) && item.source.artifact.mediaType === "audio/wav"
+      && Number.isSafeInteger(item.source.sampleFrames) && item.source.sampleFrames > 0,
+    `Audio Item ${item.id} source is invalid.`);
+    assert(item.trim.startSample >= 0 && item.trim.endSampleExclusive > item.trim.startSample
+      && item.trim.endSampleExclusive <= item.source.sampleFrames, `Audio Item ${item.id} trim is invalid.`);
+    assertOccupancy(item.occupancy, `Audio Item ${item.id} occupancy`);
+    assert(Number.isFinite(item.mix.gain) && item.mix.gain >= 0 && item.mix.gain <= 64
+      && Number.isSafeInteger(item.mix.fadeInSamples) && item.mix.fadeInSamples >= 0
+      && Number.isSafeInteger(item.mix.fadeOutSamples) && item.mix.fadeOutSamples >= 0,
+    `Audio Item ${item.id} mix is invalid.`);
+  }
+}
+
+function terminalClip(item: AudioItemProgram, space: ProgramSpace): AudioClip {
+  const windowStart = programFrameSampleBoundary(space, item.window.startFrame, 48_000);
+  const windowEnd = programFrameSampleBoundary(space, item.window.endFrameExclusive, 48_000);
+  const windowLength = windowEnd - windowStart;
+  const effectiveLength = item.trim.endSampleExclusive - item.trim.startSample;
+  let targetStart = windowStart;
+  let targetEnd = windowEnd;
+  let sourceStart = item.trim.startSample;
+  let sourceEnd = item.trim.endSampleExclusive;
+  let loop = false;
+  let phaseSample = 0;
+  let playbackRate = 1;
+  if (item.occupancy.mode === "once") {
+    const audibleLength = Math.min(windowLength, effectiveLength);
+    if (item.occupancy.align === "start") {
+      targetEnd = targetStart + audibleLength;
+      sourceEnd = sourceStart + audibleLength;
+    } else {
+      targetStart = targetEnd - audibleLength;
+      sourceStart = sourceEnd - audibleLength;
+    }
+  } else if (item.occupancy.mode === "loop") {
+    loop = true;
+    phaseSample = item.occupancy.align === "start"
+      ? 0
+      : (effectiveLength - (windowLength % effectiveLength)) % effectiveLength;
+  } else {
+    playbackRate = effectiveLength / windowLength;
+    assert(playbackRate >= item.occupancy.minRate && playbackRate <= item.occupancy.maxRate,
+      `Audio Item ${item.id} requires playback rate ${playbackRate}, outside authored bounds.`);
+  }
+  const audibleLength = targetEnd - targetStart;
+  assert(item.mix.fadeInSamples <= audibleLength && item.mix.fadeOutSamples <= audibleLength,
+    `Audio Item ${item.id} fade exceeds its audible interval.`);
+  return {
+    id: item.id,
+    subjectId: item.subjectId,
+    artifact: structuredClone(item.source.artifact),
+    target: { startSample: targetStart, endSampleExclusive: targetEnd },
+    source: {
+      sampleFrames: item.source.sampleFrames,
+      startSample: sourceStart,
+      endSampleExclusive: sourceEnd,
+      loop,
+      phaseSample,
+    },
+    playbackRate,
+    pitch: "preserve",
+    gain: item.mix.gain,
+    fadeInSamples: item.mix.fadeInSamples,
+    fadeOutSamples: item.mix.fadeOutSamples,
+  };
+}
+
+export function renderAudioTrack(space: ProgramSpace, program: AudioTrackProgram): AudioTrack {
+  assertProgramSpaceIdentity(space);
+  assertAudioTrackProgram(program);
+  const totalSamples = programSpaceSampleFrames(space, 48_000);
+  const track = sealAudioTrack({
+    programSpaceId: space.id,
+    id: program.id,
+    clips: program.items.map((item) => terminalClip(item, space)),
+  });
+  for (const clip of track.clips) {
+    assert(clip.target.endSampleExclusive <= totalSamples, `Audio Clip ${clip.id} is outside ProgramSpace.`);
+  }
+  assertAudioTrackIdentity(track, space);
+  return track;
+}

package/packages/audio-track/src/surface.ts

@@ -0,0 +1,187 @@
+import { createTemporalSpace, resolveTemporalContext } from "@hypit/temporal-markup";
+import { mediaTypes } from "@hypit/media";
+import type {
+  StructuredElement,
+  StructuredSurfaceHandler,
+  SurfaceComponentDraft,
+  SurfaceRecordDraft,
+  SurfaceResolvedReference,
+  MarkupAttributeValue,
+} from "@hypit/markup";
+import type { TemporalDuration } from "@hypit/temporal";
+import { createTemporalWindowProjection, temporalWindowAttributeNames } from "@hypit/temporal-markup";
+
+import { createAudioTrackFragment } from "./fragment.js";
+import { audioTrackTypes } from "./manifest.js";
+import { sealAudioClipSpec, sealAudioTrackHeader } from "./program.js";
+import type { AudioOccupancy } from "./types.js";
+
+function sameType(left: SurfaceResolvedReference["type"], right: SurfaceResolvedReference["type"]): boolean {
+  return left.module.name === right.module.name && left.module.version === right.module.version && left.name === right.name;
+}
+
+function allowed(element: StructuredElement, names: readonly string[]): void {
+  const permit = new Set(names);
+  const unexpected = Object.keys(element.attributes).filter((name) => !permit.has(name));
+  if (unexpected.length > 0) throw new Error(`${element.name} has unsupported attributes ${unexpected.join(", ")}.`);
+}
+
+function text(element: StructuredElement, name: string, fallback?: string): string {
+  const value = element.attributes[name];
+  if (value === undefined && fallback !== undefined) return fallback;
+  if (typeof value !== "string" || !value.trim()) throw new Error(`${element.name}.${name} must be text.`);
+  return value.trim();
+}
+
+function optionalText(element: StructuredElement, name: string): string | undefined {
+  const value = element.attributes[name];
+  if (value === undefined) return undefined;
+  if (typeof value !== "string" || !value.trim()) throw new Error(`${element.name}.${name} must be text.`);
+  return value.trim();
+}
+
+function resolved(
+  raw: MarkupAttributeValue | undefined,
+  label: string,
+  expected: SurfaceResolvedReference["type"],
+  resolve: (path: string) => SurfaceResolvedReference | undefined,
+): SurfaceResolvedReference {
+  if (typeof raw !== "object" || raw.kind !== "reference") throw new Error(`${label} must be a reference.`);
+  const value = resolve(raw.path);
+  if (value === undefined || !sameType(value.type, expected)) throw new Error(`${label} has the wrong Type.`);
+  return value;
+}
+
+function divisor(left: number, right: number): number {
+  let a = Math.abs(left);
+  let b = Math.abs(right);
+  while (b !== 0) [a, b] = [b, a % b];
+  return a;
+}
+
+function duration(value: string, label: string): TemporalDuration {
+  const match = /^(\d+)(?:\.(\d+))?(f|ms|s)$/u.exec(value.trim());
+  if (!match) throw new Error(`${label} must be an exact duration such as 12f, 250ms or 1.5s.`);
+  const whole = Number(match[1]);
+  const fraction = match[2] ?? "";
+  const unit = match[3];
+  if (!Number.isSafeInteger(whole)) throw new Error(`${label} is outside safe arithmetic.`);
+  if (unit === "f" || unit === "ms") {
+    if (fraction.length > 0) throw new Error(`${label} ${unit} duration must be an integer.`);
+    return { unit: unit === "f" ? "frames" : "milliseconds", value: whole };
+  }
+  const scale = 10 ** fraction.length;
+  const numerator = whole * scale + (fraction.length === 0 ? 0 : Number(fraction));
+  if (!Number.isSafeInteger(numerator) || !Number.isSafeInteger(scale)) throw new Error(`${label} is outside safe arithmetic.`);
+  const gcd = divisor(numerator, scale);
+  return { unit: "seconds", numerator: numerator / gcd, denominator: scale / gcd };
+}
+
+function numeric(element: StructuredElement, name: string, fallback?: number): number {
+  const raw = optionalText(element, name);
+  if (raw === undefined && fallback !== undefined) return fallback;
+  const value = Number(raw);
+  if (!Number.isFinite(value)) throw new Error(`${element.name}.${name} must be a finite number.`);
+  return value;
+}
+
+function occupancy(element: StructuredElement): AudioOccupancy {
+  switch (text(element, "playback", "once")) {
+    case "once":
+    case "once-start": return { mode: "once", align: "start" };
+    case "once-end": return { mode: "once", align: "end" };
+    case "loop":
+    case "loop-start": return { mode: "loop", align: "start" };
+    case "loop-end": return { mode: "loop", align: "end" };
+    case "stretch": return {
+      mode: "stretch",
+      minRate: numeric(element, "min-rate"),
+      maxRate: numeric(element, "max-rate"),
+      pitch: "preserve",
+    };
+    default: throw new Error(`${element.name}.playback is unsupported.`);
+  }
+}
+
+export const decodeAudioTrackSurface: StructuredSurfaceHandler = ({ element, resolveReference }) => {
+  allowed(element, ["id", "semantic", "space"]);
+  const id = text(element, "id");
+  const context = resolveTemporalContext({ element, resolveReference });
+  const time = createTemporalSpace({ id: id, element, ...context });
+  const headerId = `${id}.header`;
+  const records: SurfaceRecordDraft[] = [{
+    id: headerId,
+    type: audioTrackTypes.header,
+    value: { kind: "inline", value: sealAudioTrackHeader({ id }) },
+    range: element.range,
+  }];
+  const temporalComponents: SurfaceComponentDraft[] = [...time.components];
+  const temporalFragments: ReturnType<typeof createTemporalWindowProjection>["fragments"][number][] = [...time.fragments];
+  const fragmentItems: Parameters<typeof createAudioTrackFragment>[0][number][] = [];
+  const inputs: Record<string, { kind: "record"; id: string } | { kind: "component-output"; component: string; output: string }> = {
+    header: { kind: "record", id: headerId },
+    space: time.space.ref,
+  };
+  let itemIndex = 0;
+  for (const child of element.children) {
+    if (child.kind === "text") {
+      if (child.value.trim()) throw new Error(`${element.name} accepts only Clip children.`);
+      continue;
+    }
+    if (!child.name.endsWith(":Clip") && child.name !== "Clip") throw new Error(`${element.name} accepts only Clip children.`);
+    if (child.children.some((node) => node.kind === "element" || node.value.trim())) throw new Error(`${child.name} must be empty.`);
+    allowed(child, [
+      "id", "source", ...temporalWindowAttributeNames,
+      "trim-start", "trim-end", "playback", "min-rate", "max-rate", "gain", "fade-in", "fade-out",
+    ]);
+    itemIndex += 1;
+    const suffix = String(itemIndex).padStart(4, "0");
+    const clipId = optionalText(child, "id") ?? `${id}.clip.${suffix}`;
+    const source = resolved(child.attributes.source, `${child.name}.source`, mediaTypes.synchronized, resolveReference);
+    const temporal = createTemporalWindowProjection({ id: clipId, element: child, ...context, space: time.space, resolveReference });
+    records.push(...temporal.records);
+    temporalComponents.push(...temporal.components);
+    temporalFragments.push(...temporal.fragments);
+    const playback = occupancy(child);
+    if (playback.mode !== "stretch" && (child.attributes["min-rate"] !== undefined || child.attributes["max-rate"] !== undefined)) {
+      throw new Error(`${child.name} rate bounds require stretch playback.`);
+    }
+    const clipSpec = sealAudioClipSpec({
+
+      id: clipId,
+      trim: {
+        ...(optionalText(child, "trim-start") === undefined ? {} : { start: duration(optionalText(child, "trim-start")!, `${child.name}.trim-start`) }),
+        ...(optionalText(child, "trim-end") === undefined ? {} : { end: duration(optionalText(child, "trim-end")!, `${child.name}.trim-end`) }),
+      },
+      occupancy: playback,
+      mix: {
+        gain: numeric(child, "gain", 1),
+        fadeIn: duration(text(child, "fade-in", "0f"), `${child.name}.fade-in`),
+        fadeOut: duration(text(child, "fade-out", "0f"), `${child.name}.fade-out`),
+      },
+    });
+    const windowName = `item-${suffix}-window`;
+    inputs[windowName] = temporal.ref;
+    const mediaName = `item-${suffix}-media`;
+    const specName = `item-${suffix}-spec`;
+    const specId = `${id}.clip.${suffix}.spec`;
+    records.push({ id: specId, type: audioTrackTypes.clipSpec, value: { kind: "inline", value: clipSpec }, range: child.range });
+    inputs[mediaName] = source.ref;
+    inputs[specName] = { kind: "record", id: specId };
+    fragmentItems.push({ mediaName, specName, windowName });
+  }
+  if (fragmentItems.length === 0) throw new Error(`${element.name} requires at least one Clip.`);
+  const fragment = createAudioTrackFragment(fragmentItems);
+  return {
+    records,
+    components: [...temporalComponents, {
+      id,
+      fragment: fragment.id,
+      inputs,
+      outputs: { program: `${id}.program`, track: `${id}.track` },
+      range: element.range,
+    }],
+    fragments: [...temporalFragments, fragment],
+    exports: [`${id}.program`, `${id}.track`],
+  };
+};

package/packages/audio-track/src/types.ts

@@ -0,0 +1,62 @@
+import type { FrameSpan } from "@hypit/composition";
+import type { BlobRef } from "@hypit/protocol";
+import type {
+  TemporalDuration,
+} from "@hypit/temporal";
+
+export type AudioOccupancy =
+  | { readonly mode: "once"; readonly align: "start" | "end" }
+  | { readonly mode: "loop"; readonly align: "start" | "end" }
+  | { readonly mode: "stretch"; readonly minRate: number; readonly maxRate: number; readonly pitch: "preserve" };
+
+export type AudioSourceTrim = {
+  readonly start?: TemporalDuration;
+  readonly end?: TemporalDuration;
+};
+
+export type AudioItemMix = {
+  readonly gain: number;
+  readonly fadeIn: TemporalDuration;
+  readonly fadeOut: TemporalDuration;
+};
+
+export type AudioClipSpec = {
+  readonly id: string;
+  readonly trim: AudioSourceTrim;
+  readonly occupancy: AudioOccupancy;
+  readonly mix: AudioItemMix;
+};
+
+export type AudioTrackHeader = {
+  readonly id: string;
+};
+
+export type AudioItemProgram = {
+  readonly id: string;
+  /** Author-owned Item realized by this externally projected window. */
+  readonly subjectId: string;
+  readonly window: FrameSpan;
+  readonly source: {
+    readonly artifact: BlobRef;
+    readonly sampleFrames: number;
+  };
+  readonly trim: {
+    readonly startSample: number;
+    readonly endSampleExclusive: number;
+  };
+  readonly occupancy: AudioOccupancy;
+  readonly mix: {
+    readonly gain: number;
+    readonly fadeInSamples: number;
+    readonly fadeOutSamples: number;
+  };
+};
+
+export type AudioTrackProgram = {
+  readonly id: string;
+  readonly items: readonly AudioItemProgram[];
+};
+
+export type AudioTrackSet = {
+  readonly items: readonly AudioItemProgram[];
+};

package/packages/audio-track-studio/README.md

@@ -0,0 +1,3 @@
+# `@hypit/audio-track-studio`
+
+Hypit Studio Companion for `@hypit/audio-track`. The domain package does not depend on this package.

package/packages/audio-track-studio/package.json

@@ -0,0 +1,14 @@
+{
+  "name": "@hypit/audio-track-studio",
+  "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/audio-track": "workspace:*",
+    "@hypit/composition": "workspace:*",
+    "@hypit/studio-adapter": "workspace:*"
+  }
+}