@hypit/hypit 0.1.4 → 0.1.5

package/packages/interview-emoji-reveal/src/program.ts

@@ -1,7 +1,7 @@
+import type { Timeline } from "@hypit/timeline";
 import { assertVisualTrackIdentity, sealVisualTrack } from "@hypit/composition";
 import type { VisualAnimation, VisualElement, VisualTrack } from "@hypit/composition";
 import { assertProgramSpaceIdentity } from "@hypit/program-space";
-import type { ProgramSpace } from "@hypit/program-space";
 import { canonicalize } from "@hypit/protocol";
 import type { BlobRef } from "@hypit/protocol";
 import { assertCanvasSpace } from "@hypit/spatial";
@@ -67,11 +67,11 @@ export function assertEmojiRevealSet(value: EmojiRevealSet): void {
   }
 }
 
-export function appendEmojiRevealItem(set: EmojiRevealSet, space: ProgramSpace, spec: EmojiRevealItemSpec, icon: BlobRef, activation: TemporalInstant): EmojiRevealSet {
-  assertEmojiRevealSet(set); assertProgramSpaceIdentity(space); assertEmojiRevealItemSpec(spec);
+export function appendEmojiRevealItem(set: EmojiRevealSet, timeline: Timeline, spec: EmojiRevealItemSpec, icon: BlobRef, activation: TemporalInstant): EmojiRevealSet {
+  assertEmojiRevealSet(set); assertProgramSpaceIdentity(timeline); assertEmojiRevealItemSpec(spec);
   assert(!spec.preset, `Emoji Reveal Item ${spec.id} with preset=true cannot have an activation.`);
   assertIconImage(icon, `Emoji Reveal Item ${spec.id} icon`);
-  assertTemporalInstantFor(activation, { subjectId: spec.id, space });
+  assertTemporalInstantFor(activation, { subjectId: spec.id, space: timeline });
   assert(!set.items.some((item) => item.spec.id === spec.id), `Duplicate Emoji Reveal Item ${spec.id}.`);
   return { items: [...set.items, { spec: structuredClone(spec), icon: structuredClone(icon), activation: structuredClone(activation) }] };
 }
@@ -85,11 +85,11 @@ export function appendPresetEmojiRevealItem(set: EmojiRevealSet, spec: EmojiReve
 }
 
 export function finalizeEmojiReveal(
-  header: EmojiRevealHeader, space: ProgramSpace, outer: TemporalWindow, style: EmojiRevealStyle, placeholder: BlobRef, set: EmojiRevealSet,
+  header: EmojiRevealHeader, timeline: Timeline, outer: TemporalWindow, style: EmojiRevealStyle, placeholder: BlobRef, set: EmojiRevealSet,
 ): EmojiRevealProgram {
-  assertEmojiRevealHeader(header); assertProgramSpaceIdentity(space); assertEmojiRevealStyle(style); assertEmojiRevealSet(set);
+  assertEmojiRevealHeader(header); assertProgramSpaceIdentity(timeline); assertEmojiRevealStyle(style); assertEmojiRevealSet(set);
   assertIconImage(placeholder, "Emoji Reveal placeholder");
-  assertTemporalWindowFor(outer, { subjectId: header.id, space });
+  assertTemporalWindowFor(outer, { subjectId: header.id, space: timeline });
   assert(set.items.length > 0, "Emoji Reveal requires at least one Item.");
   let previous = outer.span.startFrame - 1;
   let revealStarted = false;
@@ -106,7 +106,7 @@ export function finalizeEmojiReveal(
     previous = frame;
   }
   const program: EmojiRevealProgram = {
-    id: header.id, programSpaceId: space.id, outer: structuredClone(outer), style: structuredClone(style),
+    id: header.id, programSpaceId: timeline.id, outer: structuredClone(outer), style: structuredClone(style),
     placeholder: structuredClone(placeholder), items: structuredClone(set.items),
   };
   assertEmojiRevealProgram(program);
@@ -183,10 +183,10 @@ function iconElement(input: {
   };
 }
 
-export function renderEmojiReveal(canvas: CanvasSpace, space: ProgramSpace, program: EmojiRevealProgram): VisualTrack {
-  assertCanvasSpace(canvas); assertProgramSpaceIdentity(space); assertEmojiRevealProgram(program);
-  assert(program.programSpaceId === space.id, "EmojiRevealProgram belongs to another ProgramSpace.");
-  assertTemporalWindowFor(program.outer, { subjectId: program.id, space });
+export function renderEmojiReveal(canvas: CanvasSpace, timeline: Timeline, program: EmojiRevealProgram): VisualTrack {
+  assertCanvasSpace(canvas); assertProgramSpaceIdentity(timeline); assertEmojiRevealProgram(program);
+  assert(program.programSpaceId === timeline.id, "EmojiRevealProgram belongs to another Timeline.");
+  assertTemporalWindowFor(program.outer, { subjectId: program.id, space: timeline });
   const { style } = program;
   const count = program.items.length;
   const width = style.paddingXPx * 2 + style.slotSizePx * count + style.gapPx * (count - 1);
@@ -234,9 +234,9 @@ export function renderEmojiReveal(canvas: CanvasSpace, space: ProgramSpace, prog
     );
   });
   const track = sealVisualTrack({
-    programSpaceId: space.id, visualIr: "hypit.visual-ir@1", id: program.id,
+    programSpaceId: timeline.id, visualIr: "hypit.visual-ir@1", id: program.id,
     presents: [{ id: program.id, subjectId: program.id, span: { ...program.outer.span },
       stacking: { order: style.stackingOrder, tieBreak: program.id }, elements }],
   });
-  assertVisualTrackIdentity(track, space); return track;
+  assertVisualTrackIdentity(track, timeline); return track;
 }

package/packages/interview-emoji-reveal/src/surface.ts

@@ -1,4 +1,4 @@
-import { createTemporalSpace, resolveTemporalContext } from "@hypit/temporal-markup";
+import { resolveTemporalContext } from "@hypit/temporal-markup";
 import {
   assertAttributes, assertEmptyElement, optionalTextAttribute, textAttribute, type MarkupAttributeValue, type StructuredSurfaceHandler,
   type SurfaceComponentDraft, type SurfaceRecordDraft, type SurfaceResolvedReference,
@@ -48,24 +48,23 @@ export const decodeEmojiRevealStyleSurface: StructuredSurfaceHandler = ({ elemen
 };
 
 export const decodeEmojiRevealTrackSurface: StructuredSurfaceHandler = ({ element, resolveReference }) => {
-  assertAttributes(element, ["id", "semantic", "space", "canvas", "style", "placeholder", ...temporalWindowAttributeNames]);
+  assertAttributes(element, ["id", "timeline", "canvas", "style", "placeholder", ...temporalWindowAttributeNames]);
   const id = textAttribute(element, "id");
   const context = resolveTemporalContext({ element, resolveReference });
-  const time = createTemporalSpace({ id: id, element, ...context });
   const canvas = reference(element.attributes.canvas, `${element.name}.canvas`, spatialTypes.canvas, resolveReference);
   const style = reference(element.attributes.style, `${element.name}.style`, emojiRevealTypes.style, resolveReference);
   const placeholder = reference(element.attributes.placeholder, `${element.name}.placeholder`, artifactTypes.blob, resolveReference);
-  const outer = createTemporalWindowProjection({ id, subjectId: id, element, ...context, space: time.space, resolveReference });
+  const outer = createTemporalWindowProjection({ id, subjectId: id, element, ...context, resolveReference });
   const headerId = `${id}.header`;
   const records: SurfaceRecordDraft[] = [...outer.records, {
     id: headerId, type: emojiRevealTypes.header,
     value: { kind: "inline", value: sealEmojiRevealHeader({ id }) as unknown as CanonicalValue }, range: element.range,
   }];
-  const temporalComponents: SurfaceComponentDraft[] = [...time.components, ...outer.components];
-  const temporalFragments = [...time.fragments, ...outer.fragments];
+  const temporalComponents: SurfaceComponentDraft[] = [...outer.components];
+  const temporalFragments = [...outer.fragments];
   const items: { specName: string; iconName: string; activationName?: string }[] = [];
-  const inputs: Record<string, typeof time.space.ref> = {
-    header: { kind: "record", id: headerId }, space: time.space.ref, canvas: canvas.ref, style: style.ref,
+  const inputs: Record<string, typeof context.timeline.ref> = {
+    header: { kind: "record", id: headerId }, timeline: context.timeline.ref, canvas: canvas.ref, style: style.ref,
     placeholder: placeholder.ref, outer: outer.ref,
   };
   const ids = new Set<string>();
@@ -92,7 +91,7 @@ export const decodeEmojiRevealTrackSurface: StructuredSurfaceHandler = ({ elemen
     else {
       const activation = createTemporalInstantProjection({
         id: `${id}.item.${suffix}.activation`, subjectId: itemId,
-        element: child, ...context, space: time.space, resolveReference, semanticAttribute: "at", projectedAttribute: false,
+        element: child, ...context, resolveReference, semanticAttribute: "at", projectedAttribute: false,
       });
       records.push(...activation.records); temporalComponents.push(...activation.components); temporalFragments.push(...activation.fragments);
       const activationName = `item-${suffix}-activation`;

package/packages/media-execution/README.md

@@ -20,9 +20,13 @@ owns the byte-level implementations of the eight current operations:
 - render an exact sample-domain audio program;
 - mux rendered visual and audio products.
 
-Local and AWS Lambda Providers call these same functions with different Artifact I/O and FFmpeg
-launch environments. They therefore share stream selection, timing, codec and validation behavior
-instead of reimplementing media semantics per deployment.
+The local Provider calls these functions with its Artifact I/O and FFmpeg launch environment. Other
+deployments can reuse the same functions to preserve stream selection, timing, codec and validation behavior.
 
 This is not an author package, Provider, queue or Core extension. It performs no endpoint selection,
 credential lookup or SVML parsing.
+
+Audio gain envelopes and audible subranges are evaluated per sample after tempo/looping and Clip
+fades, before the requested range is cropped. Original source and envelope progress therefore survive
+local silence and range rendering. This is generic AudioProgramPlan execution, independent of author
+component or Style names.

package/packages/media-execution/src/audio-presentation.ts

@@ -0,0 +1,23 @@
+import type { AudioProgramClip } from "@hypit/media-pipeline";
+
+/** Per-sample gain after source playback/fades, before any requested render-range crop. */
+export function audioPresentationFilter(clip: AudioProgramClip): string[] {
+  if (clip.gainEnvelope === undefined && clip.audibility === undefined) return [];
+  const sample = `(n+${clip.targetStartSample})`;
+  let gain = "1";
+  const points = clip.gainEnvelope;
+  if (points !== undefined) {
+    gain = String(points.at(-1)!.gain);
+    for (let index = points.length - 1; index > 0; index--) {
+      const left = points[index - 1]!, right = points[index]!;
+      const line = `(${left.gain}+(${right.gain}-${left.gain})*(${sample}-${left.sample})/${right.sample-left.sample})`;
+      gain = `if(lt(${sample},${right.sample}),${line},${gain})`;
+    }
+    gain = `if(lt(${sample},${points[0]!.sample}),${points[0]!.gain},${gain})`;
+  }
+  if (clip.audibility !== undefined) {
+    const active = clip.audibility.map(span => `(gte(${sample},${span.startSample})*lt(${sample},${span.endSampleExclusive}))`).join("+") || "0";
+    gain = `(${gain})*(${active})`;
+  }
+  return [`aeval=exprs='val(0)*(${gain})|val(1)*(${gain})'`];
+}

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

@@ -1,3 +1,4 @@
+import { audioPresentationFilter } from "./audio-presentation.js";
 import { spawn } from "node:child_process";
 import { randomUUID } from "node:crypto";
 import { createReadStream } from "node:fs";
@@ -556,6 +557,7 @@ function audioClipFilter(clip: AudioProgramClip, inputIndex: number, outputIndex
     ...(clip.fadeOutSamples === 0 ? [] : [
       `afade=t=out:start_sample=${length - clip.fadeOutSamples}:nb_samples=${clip.fadeOutSamples}`,
     ]),
+    ...audioPresentationFilter(clip),
     // Crop after tempo, looping and envelopes, keeping their original phase.
     `atrim=start_sample=${left - clip.targetStartSample}:end_sample=${right - clip.targetStartSample}`,
     "asetpts=N/SR/TB",

package/packages/media-pipeline/README.md

@@ -37,7 +37,7 @@ This package is the shared execution vocabulary. Speech authoring makes the boun
 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:
+The frame clock is a separate program fact and can be shared by every Normalize and Timeline assembly:
 
 ```svml
 <program:Clock id="clock" frame-rate="30"/>
@@ -109,5 +109,9 @@ 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.
+of hidden normalization/limiting. The local FFmpeg Provider consumes the shared execution body. Other Providers implement the same
+public request and result semantics.
+
+AudioProgramPlan preserves AudioClip `gainEnvelope` and `audibility` on the full program sample
+clock. The [Composition definition](../composition/README.md#audio-presentation-on-the-program-clock)
+owns their semantics; the plan does not reinterpret source choice or presentation precedence.

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

@@ -1,6 +1,6 @@
 import { programFrameSampleBoundary, programSpaceFrameCount } from "@hypit/program-space";
 import type { ProgramSpace } from "@hypit/program-space";
-import { assertCompositionIdentity } from "@hypit/composition";
+import { assertCompositionIdentity, assertAudioPresentation } from "@hypit/composition";
 import type { Composition } from "@hypit/composition";
 import { canonicalize, isResourceId } from "@hypit/protocol";
 
@@ -62,6 +62,7 @@ export function verifyAudioProgramPlan(value: unknown): asserts value is AudioPr
     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`);
+    assertAudioPresentation(clip, { startSample: clip.targetStartSample, endSampleExclusive: clip.targetEndSampleExclusive }, item.sampleFrames);
     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,
@@ -100,6 +101,8 @@ export function compileAudioProgramPlan(composition: Composition, programSpace:
         gain: clip.gain,
         fadeInSamples: clip.fadeInSamples,
         fadeOutSamples: clip.fadeOutSamples,
+        ...(clip.gainEnvelope === undefined ? {} : { gainEnvelope: clip.gainEnvelope }),
+        ...(clip.audibility === undefined ? {} : { audibility: clip.audibility }),
       };
     }));
   return sealAudioProgramPlan({

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

@@ -66,6 +66,7 @@ function plannedMediaNeed(
   port: string,
   capability: CapabilityRef,
   roles: Readonly<Record<string, string>> = {},
+  present?: PlannedNeedFacet["present"],
 ): PlannedNeedFacet {
   return {
     producer,
@@ -75,6 +76,7 @@ function plannedMediaNeed(
       return { constraints: {}, pendingInputs: plannedNeedInputs(state, step, roles) };
     },
     present(specification) {
+      if (present !== undefined) return present(specification);
       const references: Record<string, number> = {};
       for (const item of specification.pendingInputs) {
         const role = item.role;
@@ -86,6 +88,18 @@ function plannedMediaNeed(
   };
 }
 
+const presentAudioRender: NonNullable<PlannedNeedFacet["present"]> = (specification) => {
+  const request = specification.constraints as Partial<RenderAudioNeed>;
+  if (request.plan === undefined) return { fields: {}, references: {} };
+  const { plan, range } = request;
+  return { fields: {
+    startFrame: [range?.startFrame ?? 0],
+    endFrameExclusive: [range?.endFrameExclusive ?? plan.frameCount],
+    frameRate: [`${plan.frameRate.numerator}/${plan.frameRate.denominator}`],
+    sampleRate: [plan.sampleRate],
+  }, references: {} };
+};
+
 export const mediaPipelineComponent = {
   validators: [
     {
@@ -363,8 +377,8 @@ export const mediaPipelineComponent = {
       mediaPipelineCapabilities.projectSpeechEvidenceAudio,
       { media: "audio" },
     ),
-    plannedMediaNeed(mediaPipelineProducers.renderAudio, "audio", mediaPipelineCapabilities.renderAudio, { plan: "audio" }),
-    plannedMediaNeed(mediaPipelineProducers.renderAudioRange, "audio", mediaPipelineCapabilities.renderAudio, { plan: "audio" }),
+    plannedMediaNeed(mediaPipelineProducers.renderAudio, "audio", mediaPipelineCapabilities.renderAudio, {}, presentAudioRender),
+    plannedMediaNeed(mediaPipelineProducers.renderAudioRange, "audio", mediaPipelineCapabilities.renderAudio, {}, presentAudioRender),
     plannedMediaNeed(mediaPipelineProducers.mux, "media", mediaPipelineCapabilities.mux, { visual: "video", audio: "audio" }),
   ],
 } satisfies ComponentPackage;

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

@@ -3,7 +3,7 @@ import { mediaDependency, mediaTypes } from "@hypit/media";
 import { programSpaceDependency, programSpaceTypes } from "@hypit/program-space";
 import { svsModuleRef, svsRecipeType } from "@hypit/svs";
 import { speechDependency, speechTypes } from "@hypit/speech";
-import { compositionDependency, compositionTypes } from "@hypit/composition";
+import { compositionDependency, compositionTypes, audioSampleSpanSchema, audioGainEnvelopeSchema } from "@hypit/composition";
 import { artifactTypes } from "@hypit/artifact";
 import type {
   CapabilityRef,
@@ -237,6 +237,8 @@ export const audioProgramPlanSchema: ValueSchema = {
         gain: { schema: { kind: "number", minimum: 0, maximum: 64 } },
         fadeInSamples: { schema: integer },
         fadeOutSamples: { schema: integer },
+        gainEnvelope: { schema: audioGainEnvelopeSchema, optional: true },
+        audibility: { schema: { kind: "array", items: audioSampleSpanSchema }, optional: true },
       },
     } } },
     mix: { schema: {

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

@@ -1,3 +1,4 @@
+import type { AudioPresentation } from "@hypit/composition";
 import type { BlobRef } from "@hypit/protocol";
 import type { MediaFrameRange, MediaInspection, MediaRational, MediaStreamSelection, RenderedVisual, TimelineAudio } from "@hypit/media";
 
@@ -134,7 +135,7 @@ export type ProjectSpeechEvidenceAudioNeed = {
   readonly evidenceSampleFrames: number;
 };
 
-export type AudioProgramClip = {
+export type AudioProgramClip = AudioPresentation & {
   readonly id: string;
   readonly artifact: BlobRef;
   readonly targetStartSample: number;

package/packages/media-track/README.md

@@ -1,61 +1,28 @@
 # `@hypit/media-track`
 
-The Track Surface accepts `semantic={speech.semantic}` or `space={animation}`. Semantic context
-resolves Script Selections and Moments; authored space supports clock-based animation. Shared `at`
+The Track Surface accepts `timeline={program.timeline}`. The same Timeline supports authored
+positions and, where prepared Takes supply evidence, Script Selections and Moments. Shared `at`
 inputs accept a Moment or a time such as `2s`; `at` with `for` produces a Window where required.
-`Performance` still needs `semantic`, which supplies its ordered prepared footage.
+[Performance](../performance/README.md) separately obtains existing footage and source positions from Timeline.
 
 Place images, prepared video or compositable surfaces over the semantic timeline. B-roll is a common
-use: the picture can illustrate a phrase while the A-roll's speech continues. Performance presents the semantic material as a full picture, inset or cutout.
+use: the picture can illustrate a phrase while the A-roll's speech continues.
 Media Items own independently timed pictures;
 a Sequence owns one visual slot whose Members replace each other through Handoffs.
 
-The Markup Track takes `canvas` and a time source (`semantic` or `space`). Its Surface projects
+The Markup Track takes `canvas` and `timeline`. Its Surface projects
 authored Selections, Moments, Segments or clock expressions into Windows and Instants. The component
-consumes those projected times with Frames, media and appearance; its Fragment receives ProgramSpace.
+consumes those projected times with Frames, media and appearance; its Fragment receives the same Timeline.
 
 Moving media enters after [normalization](../media-pipeline/README.md), with the intended streams and
 frame clock already selected. Still images use their actual intrinsic Extent. Placement, fitting,
 sampling and motion remain separate authored choices.
 
-## Display a semantic performance
+## Present existing Timeline footage
 
-```svml
-<media:Track id="performance" semantic={speech.semantic} canvas={canvas}>
-  <media:Performance during="program" frame={layout.full}
-    appearance={look.performance}/>
-</media:Track>
-```
-
-`Performance` displays the prepared material in its enclosing Track's `semantic` input. `during`
-selects the whole program, a Segment or a Selection; the other Window forms work as usual. One
-Performance can span any number of Takes. Each plays at its original program position: if a Take
-begins at program second 5, a Window from seconds 7 to 10 shows source seconds 2 to 5. An audio-only
-interval contributes no picture. The presentation shares one frame, appearance and lifecycle across
-Take boundaries.
-
-Its appearance Recipe needs `stack-order` and can set fit, crop anchors, opacity, filters, clipping,
-padding, border, shadow and frame paint. `motion` moves the framed presentation, and `Sampling`
-children transform the fitted picture over the complete selected Window, without restarting at
-Take boundaries. `Sound` children attach prepared effects to its entrance or exit. Its original
-sound is independently available as `speech.audio` for Film. Use an Item with direct `media` for
-independent playback or source trim; Performance preserves the semantic assembly's source timing.
-
-```svml
-<media:Performance during={story.segment.explanation} frame={layout.full}
-  appearance={look.performance}>
-  <media:Sampling at="start" zoom="1"/>
-  <media:Sampling at="end" zoom="1.08"/>
-</media:Performance>
-```
-
-This excerpt belongs inside the same Media Track. Its selected passage determines the appearance
-interval, while the two Sampling keys direct a gradual push-in inside the unchanged Frame.
-
-For a fixed card, full picture, circle or cutout this is ordinary Media presentation. If video and
-graphics must resize, mask or move together, write a project component that owns that relationship.
-`projectSemanticMedia` supplies the same material spans to its drawing function. The component can
-use a browser program from `@hypit/hypit/hyperframes` while Caption and independent overlays remain peers.
+[Performance](../performance/README.md) obtains existing footage from Timeline and applies broad
+and local Use rules. Use Media Items here for independently supplied assets and playback choices.
+Both reuse the same geometry and fitting capabilities.
 
 ## Place the frame, then fit its contents
 
@@ -115,10 +82,10 @@ a deliberate pan or rotation may reveal the backing or lower layers.
 ## Author Items and replacement Sequences
 
 These excerpts assume the imports, named assets, normalized media, Frames, Extents, Script,
-SemanticTrack and Recipes are already declared:
+Timeline and Recipes are already declared:
 
 ```svml
-<media-track:Track id="coverage" semantic={speech.semantic} canvas={vertical}>
+<media-track:Track id="coverage" timeline={speech.timeline} canvas={vertical}>
   <media-track:Item image={photo} extent={photo-extent} frame={full-frame}
     during={story.selection.example} appearance={recipes.media.still}/>
   <media-track:Item media={clip-media.media} frame={full-frame}
@@ -132,7 +99,7 @@ Appearance owns stack order, fit, clipping and source sampling; a `motion` Recip
 movement. `Sampling` children can move the sampled content inside the Frame independently.
 
 ```svml
-<media-track:Track id="cards" semantic={speech.semantic} canvas={vertical}>
+<media-track:Track id="cards" timeline={speech.timeline} canvas={vertical}>
   <media-track:Sequence id="steps" frame={card-frame} appearance={recipes.media.card}
     until={story.selection.demo} until-boundary="end">
     <media-track:Member id="one" image={first} extent={card-extent}
@@ -177,7 +144,7 @@ separately controls which source frames it occupies there. `playback` defaults t
 `trim-start` and `trim-end` are a pair of integer source-frame boundaries, with an exclusive end.
 Omit both to use the full source. The playback rules apply to the trimmed range when present.
 For `stretch`, the source-frame advance is `sourceLength / targetLength`. For native playback, moving
-media has already been normalized to ProgramSpace's frame rate, so one program frame advances one
+media has already been normalized to Timeline's frame rate, so one program frame advances one
 source frame. These are source sampling choices; they do not move a Selection's semantic boundaries.
 
 A two-second Item can use the beginning of a four-second generated clip without requesting a

package/packages/media-track/package.json

@@ -19,7 +19,7 @@
     "@hypit/narrative": "workspace:*",
     "@hypit/program-space": "workspace:*",
     "@hypit/protocol": "workspace:*",
-    "@hypit/semantic-track": "workspace:*",
+    "@hypit/timeline": "workspace:*",
     "@hypit/spatial": "workspace:*",
     "@hypit/svs": "workspace:*",
     "@hypit/markup": "workspace:*",

package/packages/media-track/preview/preview.svml

@@ -6,7 +6,7 @@
   <import from="@hypit/script@1"/>
   <import as="media" from="@hypit/media@1"/>
   <import as="pipeline" from="@hypit/media-pipeline@1"/>
-  <import as="speech" from="@hypit/speech-track@1"/>
+  <import as="time" from="@hypit/timeline-author@1"/>
   <import as="whisperx" from="@hypit/whisperx@1"/>
   <import as="media-track" from="@hypit/media-track@1"/>
   <import as="space" from="@hypit/spatial@1"/>
@@ -32,16 +32,16 @@
     video="primary-moving" audio="none" span-authority="video"/>
   <whisperx:SemanticTake id="showcase-time" narrative={story}
     segment={story.segment.empty} media={duration-media.media}/>
-  <speech:Track id="speech"><speech:Take source={showcase-time.take}/></speech:Track>
+  <time:Timeline id="speech" clock={clock}><time:Take source={showcase-time.take}/></time:Timeline>
 
-  <media-track:Track id="showcase" semantic={speech.semantic} canvas={vertical}>
+  <media-track:Track id="showcase" timeline={speech.timeline} canvas={vertical}>
     <media-track:Item id="rounded-card" image={picture-a} extent={picture-size} during="program"
       frame={card-a} appearance={recipes.media.card} motion={recipes.motion.card}/>
     <media-track:Item id="flush-card" image={picture-b} extent={picture-size} during="program"
       frame={card-b} appearance={recipes.media.wide} motion={recipes.motion.card}/>
   </media-track:Track>
-  <film:Film id="main" canvas={vertical} semantic={speech.semantic} appearance={recipes.film.vertical}>
+  <film:Film id="main" canvas={vertical} timeline={speech.timeline} appearance={recipes.film.vertical}>
     <film:Track source={showcase.visual}/>
   </film:Film>
-  <render:Video id="final" composition={main.composition} semantic={speech.semantic}/>
+  <render:Video id="final" composition={main.composition} timeline={speech.timeline}/>
 </svml>

package/packages/media-track/src/author.ts

@@ -182,12 +182,18 @@ export function decodeMediaSampleSpec(
 }
 
 /** Decode visual-only sample styling without choosing playback or source trim. */
+/** Public authored defaults shared by decoding and optional editor fields. */
+export const mediaAppearanceDefaults = {
+  opacity: 1, blur: 0, brightness: 1, contrast: 1, saturation: 1,
+  clip: "frame", radius: 0,
+} as const;
+
 export function decodeMediaSampleAppearance(recipe: SvsRecipe): MediaSampleAppearance {
   return {
-    opacity: number(recipe, "opacity", 1),
+    opacity: number(recipe, "opacity", mediaAppearanceDefaults.opacity),
     filter: {
-      blurPx: number(recipe, "blur", 0), brightness: number(recipe, "brightness", 1),
-      contrast: number(recipe, "contrast", 1), saturation: number(recipe, "saturation", 1),
+      blurPx: number(recipe, "blur", mediaAppearanceDefaults.blur), brightness: number(recipe, "brightness", mediaAppearanceDefaults.brightness),
+      contrast: number(recipe, "contrast", mediaAppearanceDefaults.contrast), saturation: number(recipe, "saturation", mediaAppearanceDefaults.saturation),
     },
   };
 }
@@ -236,10 +242,10 @@ export function decodeMediaMotion(recipe: SvsRecipe | undefined): MediaLifecycle
 }
 
 export function decodeMediaPresentation(recipe: SvsRecipe): MediaFramePresentation {
-  const clip = oneOf(recipe, "clip", ["none", "frame", "rounded"] as const, "frame");
+  const clip = oneOf(recipe, "clip", ["none", "frame", "rounded"] as const, mediaAppearanceDefaults.clip);
   const borderWidth = number(recipe, "border-width", 0);
   return {
-    clip: clip === "rounded" ? { kind: "rounded", radiusPx: number(recipe, "radius", 0) } : { kind: clip },
+    clip: clip === "rounded" ? { kind: "rounded", radiusPx: number(recipe, "radius", mediaAppearanceDefaults.radius) } : { kind: clip },
     padding: padding(recipe),
     ...(borderWidth === 0 ? {} : { border: {
       widthPx: borderWidth,
@@ -278,7 +284,7 @@ export function decodeMediaFramePaint(recipe: SvsRecipe, id: string): MediaPaint
 export function decodeMediaPaintSpec(recipe: SvsRecipe, id: string): MediaPaintLayerSpec {
   assertKeys(recipe, ["paint", "opacity"]);
   return sealMediaPaintLayerSpec({
-    id, paint: paint(recipe), opacity: number(recipe, "opacity", 1),
+    id, paint: paint(recipe), opacity: number(recipe, "opacity", mediaAppearanceDefaults.opacity),
   });
 }
 

package/packages/media-track/src/component.ts

@@ -1,10 +1,8 @@
-import { appendMediaPerformance } from "./performance.js";
-import type { SemanticTrack } from "@hypit/semantic-track";
+import type { Timeline } from "@hypit/timeline";
 import type { ComponentPackage, ProducerHandlerContext } from "@hypit/component-kit";
 import type { CompositableSurfaceRef, SynchronizedMedia } from "@hypit/media";
 import { canonicalize } from "@hypit/protocol";
 import type { BlobRef, StoredValue } from "@hypit/protocol";
-import type { ProgramSpace } from "@hypit/program-space";
 import type { CanvasSpace, ContentFit, IntrinsicExtent, SpatialFrame, SpatialPath } from "@hypit/spatial";
 import type { TemporalInstant, TemporalWindow } from "@hypit/temporal";
 
@@ -54,7 +52,7 @@ function itemInputs(inputs: ProducerHandlerContext["inputs"]) {
   return {
     set: inline<MediaTrackSet>(inputs.set?.value, "MediaTrackSet"),
     header: inline<MediaTrackHeader>(inputs.header?.value, "MediaTrackHeader"),
-    space: inline<ProgramSpace>(inputs.space?.value, "ProgramSpace"),
+    timeline: inline<Timeline>(inputs.timeline?.value, "Timeline"),
     canvas: inline<CanvasSpace>(inputs.canvas?.value, "CanvasSpace"),
     layers: inline<MediaLayerSet>(inputs.layers?.value, "MediaLayerSet"),
     frame: inline<SpatialFrame>(inputs.frame?.value, "SpatialFrame"),
@@ -67,7 +65,7 @@ function itemInputs(inputs: ProducerHandlerContext["inputs"]) {
 function memberInputs(inputs: ProducerHandlerContext["inputs"]) {
   return {
     members: inline<MediaSequenceMemberSet>(inputs.members?.value, "MediaSequenceMemberSet"),
-    space: inline<ProgramSpace>(inputs.space?.value, "ProgramSpace"),
+    timeline: inline<Timeline>(inputs.timeline?.value, "Timeline"),
     layers: inline<MediaLayerSet>(inputs.layers?.value, "MediaLayerSet"),
     spec: inline<MediaSequenceMemberSpec>(inputs.spec?.value, "MediaSequenceMemberSpec"),
     activation: inline<TemporalInstant>(inputs.activation?.value, "TemporalInstant"),
@@ -78,7 +76,7 @@ function sequenceInputs(inputs: ProducerHandlerContext["inputs"]) {
   return {
     set: inline<MediaTrackSet>(inputs.set?.value, "MediaTrackSet"),
     header: inline<MediaTrackHeader>(inputs.header?.value, "MediaTrackHeader"),
-    space: inline<ProgramSpace>(inputs.space?.value, "ProgramSpace"),
+    timeline: inline<Timeline>(inputs.timeline?.value, "Timeline"),
     canvas: inline<CanvasSpace>(inputs.canvas?.value, "CanvasSpace"),
     members: inline<MediaSequenceMemberSet>(inputs.members?.value, "MediaSequenceMemberSet"),
     frame: inline<SpatialFrame>(inputs.frame?.value, "SpatialFrame"),
@@ -90,10 +88,6 @@ function sequenceInputs(inputs: ProducerHandlerContext["inputs"]) {
 
 export const mediaTrackComponent = {
   producers: [
-    { producer: mediaTrackProducers.appendPerformance, handler: ({ inputs }) => ({ outputs: { set: output(appendMediaPerformance(
-      itemInputs(inputs), inline<SemanticTrack>(inputs.semantic?.value, "SemanticTrack"),
-      inline<ContentFit>(inputs.fit?.value, "ContentFit"), inline<MediaSampleLayerSpec>(inputs.sampleSpec?.value, "MediaSampleLayerSpec"),
-    )) }, needs: {} }) },
     { producer: mediaTrackProducers.createLayers, handler: () => ({ outputs: { layers: output(createMediaLayerSet()) }, needs: {} }) },
     { producer: mediaTrackProducers.appendPaintLayer, handler: ({ inputs }) => ({ outputs: { layers: output(appendMediaPaintLayer(
       inline<MediaLayerSet>(inputs.layers?.value, "MediaLayerSet"),
@@ -121,7 +115,7 @@ export const mediaTrackComponent = {
     { producer: mediaTrackProducers.createSet, handler: () => ({ outputs: { set: output(createMediaTrackSet()) }, needs: {} }) },
     { producer: mediaTrackProducers.appendItem, handler: ({ inputs }) => {
       const value = itemInputs(inputs);
-      return { outputs: { set: output(appendMediaItem(value.set, value.header, value.space, value.canvas, value.layers, value.frame, value.spec, value.sounds, value.window)) }, needs: {} };
+      return { outputs: { set: output(appendMediaItem(value.set, value.header, value.timeline, value.canvas, value.layers, value.frame, value.spec, value.sounds, value.window)) }, needs: {} };
     } },
     { producer: mediaTrackProducers.bindItemClipPath, handler: ({ inputs }) => ({ outputs: { spec: output(bindMediaItemClipPath(
       inline<MediaItemSpec>(inputs.spec?.value, "MediaItemSpec"),
@@ -135,24 +129,24 @@ export const mediaTrackComponent = {
     { producer: mediaTrackProducers.appendMember, handler: ({ inputs }) => {
       const value = memberInputs(inputs);
       return { outputs: { members: output(appendMediaSequenceMember(
-        value.members, value.space, value.layers, value.spec, value.activation,
+        value.members, value.timeline, value.layers, value.spec, value.activation,
       )) }, needs: {} };
     } },
     { producer: mediaTrackProducers.appendSequence, handler: ({ inputs }) => {
       const value = sequenceInputs(inputs);
       return { outputs: { set: output(appendMediaSequence(
-        value.set, value.header, value.space, value.canvas, value.members, value.frame, value.spec, value.sounds, value.terminal,
+        value.set, value.header, value.timeline, value.canvas, value.members, value.frame, value.spec, value.sounds, value.terminal,
       )) }, needs: {} };
     } },
     { producer: mediaTrackProducers.finalize, handler: ({ inputs }) => ({ outputs: { program: output(finalizeMediaTrack(
       inline<MediaTrackSet>(inputs.set?.value, "MediaTrackSet"), inline<MediaTrackHeader>(inputs.header?.value, "MediaTrackHeader"),
-      inline<ProgramSpace>(inputs.space?.value, "ProgramSpace"),
+      inline<Timeline>(inputs.timeline?.value, "Timeline"),
     )) }, needs: {} }) },
     { producer: mediaTrackProducers.projectVisual, handler: ({ inputs }) => ({ outputs: { track: output(projectMediaVisualTrack(
-      inline<ProgramSpace>(inputs.space?.value, "ProgramSpace"), inline<MediaTrackProgram>(inputs.program?.value, "MediaTrackProgram"),
+      inline<Timeline>(inputs.timeline?.value, "Timeline"), inline<MediaTrackProgram>(inputs.program?.value, "MediaTrackProgram"),
     )) }, needs: {} }) },
     { producer: mediaTrackProducers.projectAudio, handler: ({ inputs }) => ({ outputs: { track: output(projectMediaAudioTrack(
-      inline<ProgramSpace>(inputs.space?.value, "ProgramSpace"), inline<MediaTrackProgram>(inputs.program?.value, "MediaTrackProgram"),
+      inline<Timeline>(inputs.timeline?.value, "Timeline"), inline<MediaTrackProgram>(inputs.program?.value, "MediaTrackProgram"),
     )) }, needs: {} }) },
   ],
   validators: [{