Skip to content

armgit / hypit

Public Imported from GitHub
0

Clone any viral video with AI agents. Not just a script, the whole workflow: swap the face, the words, the B-roll, ship 100 variants in one command, and get your 100M views.

refactor: establish the adaptive composition model

kashorin205bfeb98d75
diff --git a/examples/complex-explainer/packages/launch-scenes/package.json b/examples/complex-explainer/packages/launch-scenes/package.json
index 674bf3a1..63fbd1e6 100644
--- a/examples/complex-explainer/packages/launch-scenes/package.json
+++ b/examples/complex-explainer/packages/launch-scenes/package.json
@@ -12,5 +12,8 @@
"files": [
"src",
"README.md"
- ]
+ ],
+ "dependencies": {
+ "@hypit/hypit": "workspace:*"
+ }
}
diff --git a/examples/complex-explainer/packages/launch-scenes/src/activation.js b/examples/complex-explainer/packages/launch-scenes/src/activation.js
index be87acbc..4f2bb06b 100644
--- a/examples/complex-explainer/packages/launch-scenes/src/activation.js
+++ b/examples/complex-explainer/packages/launch-scenes/src/activation.js
@@ -16,8 +16,8 @@ import { spatialTypes } from "@hypit/hypit/spatial";
import { temporalTypes, assertTemporalInstantFor } from "@hypit/hypit/temporal";
import {
resolveTemporalContext,
- createTemporalWindowProjection,
- createTemporalInstantProjection,
+ createTemporalWindowConstruction,
+ createTemporalInstantConstruction,
temporalWindowAttributeNames,
temporalWindowAttributeVocabulary,
temporalContextAttributeVocabulary,
@@ -33,7 +33,7 @@ const options = type("Options"),
events = type("Events");
const common = [
port("timeline", timelineTypes.track),
- port("canvas", spatialTypes.canvas),
+ port("within", spatialTypes.frame),
port("window", temporalTypes.window),
port("font", mediaTypes.fontArtifact),
port("options", options),
@@ -66,9 +66,10 @@ export const manifest = {
mediaTypes.fontArtifact,
mediaTypes.blobArtifact,
timelineTypes.track,
- spatialTypes.canvas,
+ spatialTypes.frame,
temporalTypes.window,
temporalTypes.instant,
+ temporalTypes.duration, temporalTypes.extent, temporalTypes.shiftSpec,
].map((t) => [t.module.name, { module: t.module }]),
).values(),
],
@@ -125,7 +126,7 @@ const component = {
"track",
tags[tag].render(
inline(i.timeline),
- inline(i.canvas),
+ inline(i.within),
inline(i.window),
inline(i.font),
inline(i.options),
@@ -142,7 +143,7 @@ function decode(tag) {
assertAttributes(element, [
"id",
"timeline",
- "canvas",
+ "within",
"font",
...spec.assets,
...Object.keys(spec.defaults),
@@ -150,7 +151,7 @@ function decode(tag) {
]);
const id = textAttribute(element, "id"),
context = resolveTemporalContext({ element, resolveReference }),
- window = createTemporalWindowProjection({
+ window = createTemporalWindowConstruction({
id: id + ".window",
subjectId: id,
element,
@@ -186,7 +187,7 @@ function decode(tag) {
const inputs = ins(tag).filter((p) => p.name !== "events"),
bindings = {
timeline: context.timeline.ref,
- canvas: ref(element, "canvas", spatialTypes.canvas),
+ within: ref(element, "within", spatialTypes.frame),
window: window.ref,
font: ref(element, "font", mediaTypes.fontArtifact),
options: { kind: "record", id: id + ".options" },
@@ -215,7 +216,7 @@ function decode(tag) {
const name = textAttribute(ch, "name"),
key = "beat" + ++count,
eid = id + "." + key,
- at = createTemporalInstantProjection({
+ at = createTemporalInstantConstruction({
id: eid,
subjectId: eid,
element: ch,
@@ -264,7 +265,7 @@ function decode(tag) {
operations,
exports: [
{
- name: "track",
+ name: "visual",
type: compositionTypes.visualTrack,
root: op("render"),
},
@@ -279,11 +280,11 @@ function decode(tag) {
id,
fragment: fragment.id,
inputs: bindings,
- outputs: { track: id + ".track" },
+ outputs: { visual: id + ".visual" },
range: element.range,
},
],
- exports: [id + ".track"],
+ exports: [id + ".visual"],
};
};
}
@@ -308,13 +309,14 @@ export const hypitPackage = {
temporalTypes.instant,
temporalTypes.windowSpec,
temporalTypes.instantSpec,
+ temporalTypes.duration, temporalTypes.extent, temporalTypes.shiftSpec,
],
vocabulary: {
summary: "Project launch scene with phrase-driven visual beats.",
attributes: [
...temporalContextAttributeVocabulary,
...temporalWindowAttributeVocabulary,
- ...["id", "canvas", "font", ...tags[tag].assets].map((name) => ({
+ ...["id", "within", "font", ...tags[tag].assets].map((name) => ({
name,
kind: "expression",
required: true,
@@ -345,7 +347,7 @@ export const hypitPackage = {
],
ports: [
{
- name: "track",
+ name: "visual",
type: compositionTypes.visualTrack,
summary: "Visual contribution",
},
diff --git a/examples/complex-explainer/packages/launch-scenes/src/render.js b/examples/complex-explainer/packages/launch-scenes/src/render.js
index 265e59af..744d3a9f 100644
--- a/examples/complex-explainer/packages/launch-scenes/src/render.js
+++ b/examples/complex-explainer/packages/launch-scenes/src/render.js
@@ -7,17 +7,18 @@ const esc = (s) =>
/[&<>"']/g,
(c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[c],
);
-function seal(t, c, w, o, html, css, setup, data, children = []) {
- assertTemporalWindowFor(w, { subjectId: o.id, space: t });
+function seal(t, within, w, o, html, css, setup, data, children = []) {
+ assertTemporalWindowFor(w, { subjectId: o.id, timeline: t });
return sealVisualTrack({
id: o.id,
- programSpaceId: t.id,
+ timelineId: t.id,
visualIr: "hypit.visual-ir@1",
presents: [
{
id: o.id,
+ order: 0,
+ z: o.z,
span: w.span,
- stacking: { order: o.z, tieBreak: o.id },
elements: [
{
id: "scene",
@@ -35,9 +36,10 @@ function seal(t, c, w, o, html, css, setup, data, children = []) {
}),
style: sty({
position: "absolute",
- inset: 0,
- width: c.widthPx + "px",
- height: c.heightPx + "px",
+ left: within.xPx + "px",
+ top: within.yPx + "px",
+ width: within.widthPx + "px",
+ height: within.heightPx + "px",
}),
},
{
@@ -55,10 +57,10 @@ function seal(t, c, w, o, html, css, setup, data, children = []) {
],
});
}
-export function renderPoster(t, c, w, font, o) {
+export function renderPoster(t, within, w, font, o) {
return seal(
t,
- c,
+ within,
w,
o,
`<div class="poster"><div class="poster-title">${esc(o.text)}</div><div class="poster-subtitle">${esc(o.subtitle)}</div></div>`,
diff --git a/examples/complex-explainer/packages/opening-system/README.md b/examples/complex-explainer/packages/opening-system/README.md
index 07b0c302..2faaf95c 100644
--- a/examples/complex-explainer/packages/opening-system/README.md
+++ b/examples/complex-explainer/packages/opening-system/README.md
@@ -1,23 +1,26 @@
# Opening system
-Project components and Performance Styles for an explanation-led video. They share the film's Timeline and Canvas but own independent visual behavior. Connect each `.track` to Film explicitly. They produce no audio.
+Project components for an explanation-led video. They share the film's Timeline and Canvas but own independent visual behavior. Connect each visual output to Film explicitly. They produce no audio.
- **Title**: opening clock and a two-level headline in a pink window card. Existing presenter footage continues beneath it at its original brightness. Its outer Window ends on the authored “开始” Moment in this production. `seconds` is the promise printed on the title, not the estimated duration of the film.
- **Timer**: a persistent topic plaque, pennant and dot-matrix timer. Its Window's first frame starts the countdown; zero is followed by coral overtime counting upward. `title`, `subtitle`, `seconds`, `flag-color`, `x`, `y`, `width`, `flag-amplitude`, `flag-speed`, `entrance-frames` and `z` are author choices. It does not infer pauses from speech or stop when a Take is absent.
- **Flag**: an independent low-angle pixel flag. It uses the same deterministic pixel texture treatment as Timer, with its own Window, placement, dimensions and color. No relationship to the opposition boards is inferred. The current Source places it below captions during the first-road explanation. `flag-amplitude` and `flag-speed` keep the folds slow and the logo readable.
- **Stage**: independent images or normalized videos in a clear foreground viewport, with the same material enlarged, blurred and dimmed behind it. Each Item has its own projected Window. Foreground and background share exact video sampling. An image is held during its Window. Later declared Items paint above earlier ones if they overlap. Empty intervals stay empty. `fit="contain"` preserves the supplied screenshot; `cover` fills and crops. `x`, `y`, `width`, `height` are fractions of Canvas dimensions. `blur` is specified at a reference width of 1080 and scales with Canvas width. `brightness`, `zoom`, `radius` and `z` finish the treatment.
-The visual components accept the shared temporal Window forms: `during`, `at` plus `for`, `until` plus `for`, and `start`/`end` with semantic references. Stage Items use the same forms. The Surface projects those values; drawing code consumes the resolved Windows. Literal time is useful for a rapid montage, while the complete montage can follow a Segment end.
+The visual components accept the shared absolute Window forms: `during`, or exactly two of `from`,
+`until` and `for`. Stage Items use the same forms. Domain projection happens upstream; drawing code
+consumes only resolved Windows. Literal time is useful for a rapid montage, while a projected Window
+can follow a Segment.
```svml
<import as="gfx" from="@explainer/opening-system@1"/>
-<gfx:Title id="opening-title" timeline={program.timeline} canvas={canvas} font={display-font}
- start="program.start" end="moment.cue" moment={story.moment.begin}
+<gfx:Title id="opening-title" timeline={program.timeline} within={canvas.bounds} font={display-font}
+ from="timeline.start" until={story-time.begin}
title="Hypit" subtitle="一分钟了解" seconds="60"/>
-<gfx:Timer id="series-timer" timeline={program.timeline} canvas={canvas} font={display-font} logo={flag-logo}
- start="moment.cue" end="program.end" moment={story.moment.begin} title="Hypit"/>
-<gfx:Stage id="coverage" timeline={program.timeline} canvas={canvas} during={story.selection.example}>
- <gfx:Item id="demo" video={prepared-demo.media} during={story.selection.example}/>
+<gfx:Timer id="series-timer" timeline={program.timeline} within={canvas.bounds} font={display-font} logo={flag-logo}
+ from={story-time.begin} until="timeline.end" title="Hypit"/>
+<gfx:Stage id="coverage" timeline={program.timeline} within={canvas.bounds} during={story-time.example}>
+ <gfx:Item id="demo" video={prepared-demo.media} during={story-time.example}/>
</gfx:Stage>
```
@@ -25,7 +28,7 @@ The visual components accept the shared temporal Window forms: `during`, `at` pl
The current 1.5-second four-image montage uses 5 / 4 / 5 / 31 frames at 30fps, boundaries 0 / 5 / 9 / 14 / 45. The supplied images live in the production's assets, not in this package. The exact font is also supplied by Source.
-`src/activation.js` owns Manifest, Surface and finite graph wiring. `src/render.js` owns visuals and frame-seekable browser programs. The package uses Hypit's public authoring and domain APIs; it changes no framework, Studio or Core code. `src/studio.js` contributes the public Studio Companion facet. Defaults live once in `src/definition.js`, shared by Surface decoding and the Inspector. Title, Timer and Veil expose their own text, position and appearance choices. Stage has a parent for shared framing and slow-push settings, with independently timed media Items in its attached lane. Pullback, PortraitInset and Reframe expose the referenced Style/Frame parameters through Performance Uses. The Inspector uses Studio’s standard controls and writes existing author attributes; no Studio or Core component dispatch is added.
+`src/activation.js` owns Manifest, Surface and finite graph wiring. `src/render.js` owns visuals and frame-seekable browser programs. The package uses Hypit's public authoring and domain APIs; it changes no framework, Studio or Core code. `src/studio.js` contributes the public Studio Companion facet. Defaults live once in `src/definition.js`, shared by Surface decoding and the Inspector. Title, Timer and Veil expose their own text, position and appearance choices. Stage has a parent for shared framing and slow-push settings, with independently timed component-local Items in its attached lane. Presenter owns its Source/Use vocabulary because it is the one continuing creative role that needs it; Visual Track itself contains only Clips. The Inspector uses Studio’s standard controls and writes existing author attributes; no Studio or Core component dispatch is added.
The actual montage and semantic title/timer bindings live in `authors/main.svml`. Earlier component studies are archived privately.
@@ -44,13 +47,13 @@ Stage `push-rate` is the foreground scale increase per second, default zero. For
Earlier texture studies are retained in private production history. The active Source shows the selected treatment.
-### Opening pullback as a Performance Use
+### Opening pullback as a Presenter Use
-`<gfx:Pullback id="opening-pullback" scale="1.5"/>` defines a project-owned Performance Style. Apply it with `<performance:Use start="0f" end="1s" style={opening-pullback}/>` after the broad full-frame Use. Its original Use Window drives a quartic ease-out from 1.5× to 1×, centered at 50%/35%; Timeline footage keeps its source clock. At the end it meets ordinary full-frame geometry. Titles and other contributions stay independent. This changes framing, not playback speed or generated material.
+`<gfx:Pullback id="opening-pullback" scale="1.5"/>` defines one project-owned Presenter treatment. Apply it with `<gfx:Use from="0f" until="1s" style={opening-pullback}/>` inside `<gfx:Presenter>`, after the broad full-frame Use. Its original Use Window drives a quartic ease-out from 1.5× to 1×, centered at 50%/35%; footage keeps its source clock. At the end it meets ordinary full-frame geometry. Titles and other contributions stay independent. This changes framing, not playback speed or generated material.
## Portrait inset
-`<gfx:PortraitInset id="host-small" frame={host-inset}/>` is a project Performance Style for a circular presenter viewport with a closer inner crop. It uses Timeline media/source spans, clips each interval, and presents the current visual source at its placed playback time. The external Frame controls position and size; this work uses 330px. An inner 1.23× magnification, anchored at 50%/28%, increases face presence independently from viewport size. Its vivid-pink rim, dark outline and solid offset shadow match the supplied pink interface reference. This is independent from full-frame and Reframe Uses.
+`<gfx:PortraitInset id="host-small" frame={host-inset}/>` is a project Presenter treatment for a circular viewport with a closer inner crop. It receives the Presenter component's explicit Sources, clips each interval, and preserves playback from each Source Window. The external Frame controls position and size; this work uses 330px. An inner 1.23× magnification, anchored at 50%/28%, increases face presence independently from viewport size. Its vivid-pink rim, dark outline and solid offset shadow match the supplied pink interface reference. This is independent from full-frame and Reframe Uses.
The spoken opening Title is currently a pale-pink window card with a dark outline, a vivid-pink headline and a solid lower-right shadow. Timer plaque/readout follow the same palette while preserving the animated pixel flag and existing time behavior.
-`performance-media.js` owns prepared Timeline media projection and sampling shared by Pullback, Reframe and PortraitInset. The private `@explainer/visual-language` dependency owns the current pink palette; each Style owns its framing behavior.
+`presenter.js` owns explicit Source collection, Use precedence and Presenter lowering. Pullback, Reframe and PortraitInset are treatments of that project component, not generic Visual Track modes. The private `@explainer/visual-language` dependency owns the current pink palette; each treatment owns its framing behavior.
diff --git a/examples/complex-explainer/packages/opening-system/package.json b/examples/complex-explainer/packages/opening-system/package.json
index 67f14df5..ac9eb6f4 100644
--- a/examples/complex-explainer/packages/opening-system/package.json
+++ b/examples/complex-explainer/packages/opening-system/package.json
@@ -14,6 +14,7 @@
"README.md"
],
"dependencies": {
- "@explainer/visual-language": "file:../visual-language"
+ "@explainer/visual-language": "file:../visual-language",
+ "@hypit/hypit": "workspace:*"
}
}
diff --git a/examples/complex-explainer/packages/opening-system/src/activation.js b/examples/complex-explainer/packages/opening-system/src/activation.js
index b9ab4c0c..946b873d 100644
--- a/examples/complex-explainer/packages/opening-system/src/activation.js
+++ b/examples/complex-explainer/packages/opening-system/src/activation.js
@@ -2,6 +2,7 @@ import { installPortraitTransition } from "./portrait-transition.js";
import { installPortraitInset } from "./portrait-inset.js";
import { installReframe } from "./reframe.js";
import { installPullback } from "./pullback.js";
+import { installPresenter } from "./presenter.js";
import {
assertAttributes,
assertEmptyElement,
@@ -16,9 +17,10 @@ import { mediaTypes } from "@hypit/hypit/media";
import { timelineTypes } from "@hypit/hypit/timeline";
import { spatialTypes } from "@hypit/hypit/spatial";
import { temporalTypes } from "@hypit/hypit/temporal";
+import { visualTrackModuleRef } from "@hypit/hypit/visual-track";
import {
- createTemporalWindowProjection,
- createTemporalInstantProjection,
+ createTemporalWindowConstruction,
+ createTemporalInstantConstruction,
resolveTemporalContext,
temporalWindowAttributeNames,
temporalWindowAttributeVocabulary,
@@ -34,7 +36,7 @@ const producer = (name) => ({ module, name });
const port = (name, type) => ({ name, type });
const common = [
port("timeline", timelineTypes.track),
- port("canvas", spatialTypes.canvas),
+ port("within", spatialTypes.frame),
port("window", temporalTypes.window),
port("options", optionsType),
];
@@ -49,8 +51,10 @@ export const manifest = {
mediaTypes.synchronized,
mediaTypes.blobArtifact,
timelineTypes.track,
- spatialTypes.canvas,
+ spatialTypes.frame,
temporalTypes.window,
+ temporalTypes.duration, temporalTypes.extent, temporalTypes.shiftSpec,
+ { module: visualTrackModuleRef, name: "VisualTrackProgram" },
].map((t) => [t.module.name, { module: t.module }]),
).values(),
],
@@ -118,7 +122,7 @@ const val = (v) => ({ kind: "inline", value: canonicalize(v) });
const output = (name, v) => ({ outputs: { [name]: val(v) }, needs: {} });
const component = {
producers: [
- { producer: producer("flag"), handler: ({inputs: i}) => output("track", renderFlag(inline(i.timeline), inline(i.canvas), inline(i.window), inline(i.options), i.logo.value)) },
+ { producer: producer("flag"), handler: ({inputs: i}) => output("track", renderFlag(inline(i.timeline), inline(i.within), inline(i.window), inline(i.options), i.logo.value)) },
...[
["title", renderTitle],
["timer", renderTimer],
@@ -129,7 +133,7 @@ const component = {
"track",
fn(
inline(i.timeline),
- inline(i.canvas),
+ inline(i.within),
inline(i.window),
inline(i.font),
inline(i.options),
@@ -145,7 +149,7 @@ const component = {
"track",
renderVeil(
inline(i.timeline),
- inline(i.canvas),
+ inline(i.within),
inline(i.window),
inline(i.options),
),
@@ -172,7 +176,7 @@ const component = {
"track",
renderStage(
inline(i.timeline),
- inline(i.canvas),
+ inline(i.within),
inline(i.window),
inline(i.items),
inline(i.options),
@@ -188,7 +192,7 @@ function decode(kind) {
assertAttributes(element, [
"id",
"timeline",
- "canvas",
+ "within",
...(kind === "Title" ? ["bounce-at"] : []),
...(kind === "Timer" ? ["stop-at"] : []),
...(["Title", "Timer"].includes(kind) ? ["font"] : []),
@@ -198,7 +202,7 @@ function decode(kind) {
]);
const id = textAttribute(element, "id"),
context = resolveTemporalContext({ element, resolveReference });
- const win = createTemporalWindowProjection({
+ const win = createTemporalWindowConstruction({
id: id + ".window",
subjectId: id,
element,
@@ -275,21 +279,21 @@ function decode(kind) {
const inputs = [...common],
bindings = {
timeline: context.timeline.ref,
- canvas: ref(element, "canvas", spatialTypes.canvas),
+ within: ref(element, "within", spatialTypes.frame),
window: win.ref,
options: { kind: "record", id: id + ".options" },
};
if (kind === "Title") {
- const bounce = createTemporalInstantProjection({
+ const bounce = createTemporalInstantConstruction({
id: id + ".bounce", subjectId: id + ".bounce",
- element: { ...element, attributes: { at: element.attributes["bounce-at"] ?? "program.start" } },
+ element: { ...element, attributes: { at: element.attributes["bounce-at"] ?? "timeline.start" } },
...context, resolveReference,
});
records.push(...bounce.records); components.push(...bounce.components); fragments.push(...bounce.fragments);
inputs.push(port("bounce", temporalTypes.instant)); bindings.bounce = bounce.ref;
}
if (kind === "Timer") {
- const stop = createTemporalInstantProjection({id:id+".stop",subjectId:id+".stop",element:{...element,attributes:{at:element.attributes["stop-at"]??"program.end"}},...context,resolveReference});
+ const stop = createTemporalInstantConstruction({id:id+".stop",subjectId:id+".stop",element:{...element,attributes:{at:element.attributes["stop-at"]??"timeline.end"}},...context,resolveReference});
records.push(...stop.records);components.push(...stop.components);fragments.push(...stop.fragments);
inputs.push(port("stop",temporalTypes.instant));bindings.stop=stop.ref;
}
@@ -324,7 +328,7 @@ function decode(kind) {
isImage = child.attributes.image !== undefined;
if (isImage === (child.attributes.video !== undefined))
throw Error("Item needs exactly one image or normalized video");
- const iw = createTemporalWindowProjection({
+ const iw = createTemporalWindowConstruction({
id: `${id}.${cid}.window`,
subjectId: cid,
element: child,
@@ -406,7 +410,7 @@ function decode(kind) {
operations,
exports: [
{
- name: "track",
+ name: "visual",
type: compositionTypes.visualTrack,
root: operation("render"),
},
@@ -421,11 +425,11 @@ function decode(kind) {
id,
fragment: fragment.id,
inputs: bindings,
- outputs: { track: id + ".track" },
+ outputs: { visual: id + ".visual" },
range: element.range,
},
],
- exports: [id + ".track"],
+ exports: [id + ".visual"],
};
};
}
@@ -442,6 +446,7 @@ const declarations = Object.keys(defaults).map((tag) => ({
temporalTypes.instant,
temporalTypes.windowSpec,
temporalTypes.instantSpec,
+ temporalTypes.duration, temporalTypes.extent, temporalTypes.shiftSpec,
],
vocabulary: {
summary: {
@@ -461,7 +466,7 @@ const declarations = Object.keys(defaults).map((tag) => ({
...temporalWindowAttributeVocabulary,
...[
"id",
- "canvas",
+ "within",
...(["Title", "Timer"].includes(tag) ? ["font"] : []),
...(["Timer", "Flag"].includes(tag) ? ["logo"] : []),
].map((name) => ({
@@ -517,7 +522,7 @@ const declarations = Object.keys(defaults).map((tag) => ({
: [],
ports: [
{
- name: "track",
+ name: "visual",
type: compositionTypes.visualTrack,
summary: "Visual contribution, explicitly connected to Film",
},
@@ -529,6 +534,7 @@ const fadeOut = installPullback(module, manifest, component, optionsType, "fade-
const reframe = installReframe(module, manifest, component);
const portraitTransition = installPortraitTransition(module, manifest, component);
const portraitInset = installPortraitInset(module, manifest, component);
+const presenter = installPresenter(module, manifest, component);
export const hypitPackage = {
format: "hypit.node-package@1",
modules: [{ manifest }],
@@ -546,6 +552,8 @@ export const hypitPackage = {
reframe,
portraitTransition,
portraitInset,
+ presenter.styleFacet,
+ presenter.presenterFacet,
studioFacet,
],
};
diff --git a/examples/complex-explainer/packages/opening-system/src/performance-media.js b/examples/complex-explainer/packages/opening-system/src/performance-media.js
deleted file mode 100644
index aa30cbbb..00000000
--- a/examples/complex-explainer/packages/opening-system/src/performance-media.js
+++ /dev/null
@@ -1,37 +0,0 @@
-import { projectTimelineMedia } from "@hypit/hypit/timeline";
-export function performanceMedia(timeline, window, parent = "scene") {
- const clips = projectTimelineMedia(timeline, window.span).filter(
- (clip) => clip.media.visual,
- );
- const children = clips.map((clip, index) => ({
- id: "clip" + index,
- parent,
- kind: "video",
- order: index + 1,
- muted: true,
- artifact: clip.media.visual.artifact,
- style: Object.entries({
- position: "absolute",
- inset: 0,
- width: "100%",
- height: "100%",
- "object-fit": "cover",
- }).map(([name, value]) => ({ name, value })),
- sampling: {
- sourceFrameRate: clip.media.timeline.frameRate,
- sourceFrameCount: clip.media.timeline.frameCount,
- segments: [
- {
- target: {
- startFrame: clip.span.startFrame - window.span.startFrame,
- endFrameExclusive:
- clip.span.endFrameExclusive - window.span.startFrame,
- },
- sourceFrame: { numerator: clip.source.startFrame, denominator: 1 },
- rate: { numerator: 1, denominator: 1 },
- },
- ],
- },
- }));
- return { clips, children };
-}
diff --git a/examples/complex-explainer/packages/opening-system/src/placed-visual-media.js b/examples/complex-explainer/packages/opening-system/src/placed-visual-media.js
new file mode 100644
index 00000000..4e9162b9
--- /dev/null
+++ b/examples/complex-explainer/packages/opening-system/src/placed-visual-media.js
@@ -0,0 +1,48 @@
+export function placedVisualMedia(timeline, window, sources, parent = "scene") {
+ const clips = sources.flatMap((source) => {
+ if (source.window.start.timelineId !== timeline.id || source.window.end.timelineId !== timeline.id)
+ throw Error(`Visual source ${source.id} belongs to another Timeline.`);
+ const placed = source.window.span;
+ const startFrame = Math.max(placed.startFrame, window.span.startFrame);
+ const endFrameExclusive = Math.min(
+ placed.endFrameExclusive,
+ window.span.endFrameExclusive,
+ placed.startFrame + source.media.frameDomain.frameCount,
+ );
+ if (endFrameExclusive <= startFrame) return [];
+ return [{
+ source,
+ span: { startFrame, endFrameExclusive },
+ sourceStartFrame: startFrame - placed.startFrame,
+ }];
+ });
+ const children = clips.map((clip, index) => ({
+ id: "source-" + index,
+ parent,
+ kind: "video",
+ order: index + 1,
+ muted: true,
+ artifact: clip.source.media.visual.artifact,
+ style: Object.entries({
+ position: "absolute",
+ inset: 0,
+ width: "100%",
+ height: "100%",
+ "object-fit": "cover",
+ }).map(([name, value]) => ({ name, value })),
+ sourceTime: {
+ sourceFrameRate: clip.source.media.frameDomain.frameRate,
+ sourceFrameCount: clip.source.media.frameDomain.frameCount,
+ pieces: [{
+ target: {
+ startFrame: clip.span.startFrame - window.span.startFrame,
+ endFrameExclusive:
+ clip.span.endFrameExclusive - window.span.startFrame,
+ },
+ sourceAtStart: { numerator: clip.sourceStartFrame, denominator: 1 },
+ rate: { numerator: 1, denominator: 1 },
+ }],
+ },
+ }));
+ return { clips, children };
+}
diff --git a/examples/complex-explainer/packages/opening-system/src/portrait-inset.js b/examples/complex-explainer/packages/opening-system/src/portrait-inset.js
index c3451699..bbf70202 100644
--- a/examples/complex-explainer/packages/opening-system/src/portrait-inset.js
+++ b/examples/complex-explainer/packages/opening-system/src/portrait-inset.js
@@ -1,5 +1,5 @@
import { palette } from "@explainer/visual-language";
-import { performanceMedia } from "./performance-media.js";
+import { placedVisualMedia } from "./placed-visual-media.js";
import {
assertAttributes,
assertEmptyElement,
@@ -9,7 +9,7 @@ import {
createMarkupSurfaceHostFacet,
sameType,
} from "@hypit/hypit/author-kit";
-import { performanceStyle, performanceTypes } from "@hypit/hypit/performance";
+import { presenterStyle, presenterTypes } from "./presenter.js";
import { sealVisualTrack, compositionTypes } from "@hypit/hypit/composition";
import { timelineTypes } from "@hypit/hypit/timeline";
import { spatialTypes } from "@hypit/hypit/spatial";
@@ -18,10 +18,12 @@ import { browserProgram } from "@hypit/hypit/hyperframes";
const styles = (o) =>
Object.entries(o).map(([name, value]) => ({ name, value }));
export function installPortraitInset(module, manifest, component) {
+ const types = presenterTypes(module);
const inputs = [
{ name: "timeline", type: timelineTypes.track },
- { name: "canvas", type: spatialTypes.canvas },
+ { name: "within", type: spatialTypes.frame },
{ name: "window", type: temporalTypes.window },
+ { name: "sources", type: types.sources },
{ name: "frame", type: spatialTypes.frame },
],
producer = { module, name: "portrait-inset" };
@@ -54,10 +56,10 @@ export function installPortraitInset(module, manifest, component) {
component.producers.push({
producer,
handler: ({ inputs }) => {
- const { timeline, canvas, window, frame } = Object.fromEntries(
+ const { timeline, within, window, sources, frame } = Object.fromEntries(
Object.entries(inputs).map(([k, r]) => [k, r.value.value]),
),
- { clips, children } = performanceMedia(timeline, window);
+ { clips, children } = placedVisualMedia(timeline, window, sources.sources);
const program = browserProgram({
html:
'<div class="viewport"><div class="inner">' +
@@ -76,14 +78,15 @@ export function installPortraitInset(module, manifest, component) {
const id = window.subjectId,
visual = sealVisualTrack({
id,
- programSpaceId: timeline.id,
+ timelineId: timeline.id,
visualIr: "hypit.visual-ir@1",
presents: children.length
? [
{
id,
+ order: 0,
+ z: 60,
span: window.span,
- stacking: { order: 60, tieBreak: id },
elements: [
{
id: "scene",
@@ -92,9 +95,10 @@ export function installPortraitInset(module, manifest, component) {
program,
style: styles({
position: "absolute",
- inset: 0,
- width: canvas.widthPx + "px",
- height: canvas.heightPx + "px",
+ left: within.xPx + "px",
+ top: within.yPx + "px",
+ width: within.widthPx + "px",
+ height: within.heightPx + "px",
}),
},
...children,
@@ -115,7 +119,7 @@ export function installPortraitInset(module, manifest, component) {
name: "portrait-inset",
tag: "PortraitInset",
mode: "structured",
- outputs: [performanceTypes.style],
+ outputs: [types.style],
vocabulary: {
summary: "Round speaking portrait with a tighter inner crop.",
attributes: [
@@ -151,10 +155,10 @@ export function installPortraitInset(module, manifest, component) {
records: [
{
id: textAttribute(element, "id"),
- type: performanceTypes.style,
+ type: types.style,
value: {
kind: "inline",
- value: canonicalize(performanceStyle(fragment, bindings)),
+ value: canonicalize(presenterStyle(fragment, bindings)),
},
range: element.range,
},
diff --git a/examples/complex-explainer/packages/opening-system/src/portrait-transition.js b/examples/complex-explainer/packages/opening-system/src/portrait-transition.js
index 41a1b687..ee2ebbd5 100644
--- a/examples/complex-explainer/packages/opening-system/src/portrait-transition.js
+++ b/examples/complex-explainer/packages/opening-system/src/portrait-transition.js
@@ -1,5 +1,5 @@
import { palette } from "@explainer/visual-language";
-import { performanceMedia } from "./performance-media.js";
+import { placedVisualMedia } from "./placed-visual-media.js";
import {
assertAttributes,
assertEmptyElement,
@@ -9,7 +9,7 @@ import {
createMarkupSurfaceHostFacet,
sameType,
} from "@hypit/hypit/author-kit";
-import { performanceStyle, performanceTypes } from "@hypit/hypit/performance";
+import { presenterStyle, presenterTypes } from "./presenter.js";
import { sealVisualTrack, compositionTypes } from "@hypit/hypit/composition";
import { timelineTypes } from "@hypit/hypit/timeline";
import { spatialTypes } from "@hypit/hypit/spatial";
@@ -18,10 +18,12 @@ import { browserProgram } from "@hypit/hypit/hyperframes";
const styles = (o) =>
Object.entries(o).map(([name, value]) => ({ name, value }));
export function installPortraitTransition(module, manifest, component) {
+ const types = presenterTypes(module);
const inputs = [
{ name: "timeline", type: timelineTypes.track },
- { name: "canvas", type: spatialTypes.canvas },
+ { name: "within", type: spatialTypes.frame },
{ name: "window", type: temporalTypes.window },
+ { name: "sources", type: types.sources },
{ name: "from", type: spatialTypes.frame },
{ name: "to", type: spatialTypes.frame },
],
@@ -55,10 +57,10 @@ export function installPortraitTransition(module, manifest, component) {
component.producers.push({
producer,
handler: ({ inputs }) => {
- const { timeline, canvas, window, from, to } = Object.fromEntries(
+ const { timeline, within, window, sources, from, to } = Object.fromEntries(
Object.entries(inputs).map(([k, r]) => [k, r.value.value]),
),
- { clips, children } = performanceMedia(timeline, window);
+ { clips, children } = placedVisualMedia(timeline, window, sources.sources);
const program = browserProgram({
html:
'<div class="viewport"><div class="inner">' +
@@ -82,14 +84,15 @@ export function installPortraitTransition(module, manifest, component) {
const id = window.subjectId,
visual = sealVisualTrack({
id,
- programSpaceId: timeline.id,
+ timelineId: timeline.id,
visualIr: "hypit.visual-ir@1",
presents: children.length
? [
{
id,
+ order: 0,
+ z: 60,
span: window.span,
- stacking: { order: 60, tieBreak: id },
elements: [
{
id: "scene",
@@ -98,9 +101,10 @@ export function installPortraitTransition(module, manifest, component) {
program,
style: styles({
position: "absolute",
- inset: 0,
- width: canvas.widthPx + "px",
- height: canvas.heightPx + "px",
+ left: within.xPx + "px",
+ top: within.yPx + "px",
+ width: within.widthPx + "px",
+ height: within.heightPx + "px",
}),
},
...children,
@@ -121,7 +125,7 @@ export function installPortraitTransition(module, manifest, component) {
name: "portrait-transition",
tag: "PortraitTransition",
mode: "structured",
- outputs: [performanceTypes.style],
+ outputs: [types.style],
vocabulary: {
summary:
"A continuous full-frame performance move into the project's circular presenter inset.",
@@ -158,10 +162,10 @@ export function installPortraitTransition(module, manifest, component) {
records: [
{
id: textAttribute(element, "id"),
- type: performanceTypes.style,
+ type: types.style,
value: {
kind: "inline",
- value: canonicalize(performanceStyle(fragment, bindings)),
+ value: canonicalize(presenterStyle(fragment, bindings)),
},
range: element.range,
},
diff --git a/examples/complex-explainer/packages/opening-system/src/presenter.js b/examples/complex-explainer/packages/opening-system/src/presenter.js
new file mode 100644
index 00000000..904b64ea
--- /dev/null
+++ b/examples/complex-explainer/packages/opening-system/src/presenter.js
@@ -0,0 +1,357 @@
+import {
+ assertAttributes,
+ assertEmptyElement,
+ canonicalize,
+ createMarkupSurfaceHostFacet,
+ optionalTextAttribute,
+ sameType,
+ sealGraphFragment,
+ textAttribute,
+} from "@hypit/hypit/author-kit";
+import { compositionTypes, sealVisualTrack } from "@hypit/hypit/composition";
+import { mediaTypes, verifySynchronizedMedia } from "@hypit/hypit/media";
+import { spatialTypes } from "@hypit/hypit/spatial";
+import { svsRecipeType } from "@hypit/hypit/svs";
+import { temporalTypes, assertTemporalWindowFor } from "@hypit/hypit/temporal";
+import {
+ createTemporalWindowConstruction,
+ resolveTemporalContext,
+ temporalWindowAttributeNames,
+ temporalWindowAttributeVocabulary,
+} from "@hypit/hypit/temporal-markup";
+import { timelineTypes } from "@hypit/hypit/timeline";
+import {
+ appendVisualClip,
+ appendTimedMediaLayer,
+ createMediaLayerSet,
+ createVisualTrackSet,
+ decodeMediaFit,
+ decodeVisualClipSpec,
+ decodeMediaSampleSpec,
+ finalizeVisualTrack,
+ visualMaterialKeys,
+ projectVisualTrack,
+ visualTrackTypes,
+} from "@hypit/hypit/visual-track";
+
+const input = (name) => ({ kind: "fragment-input", name });
+const operation = (id) => ({ kind: "fragment-operation", operation: id });
+const inline = (record, label) => {
+ if (record?.value.kind !== "inline") throw Error(`${label} must be inline.`);
+ return record.value.value;
+};
+const stored = (value) => ({ kind: "inline", value: canonicalize(value) });
+
+export function presenterTypes(module) {
+ return {
+ style: { module, name: "PresenterStyle" },
+ sourceSpec: { module, name: "PresenterSourceSpec" },
+ sources: { module, name: "PresenterSources" },
+ program: { module, name: "PresenterProgram" },
+ header: { module, name: "PresenterHeader" },
+ };
+}
+
+export function presenterStyle(fragment, bindings = {}) {
+ return { fragment: sealGraphFragment(fragment), bindings };
+}
+
+function sourceValue(spec, media, window, timeline) {
+ verifySynchronizedMedia(media);
+ assertTemporalWindowFor(window, { timeline });
+ if (media.visual === undefined) throw Error(`Presenter Source ${spec.id} has no visual stream.`);
+ return { id: spec.id, media: structuredClone(media), window: structuredClone(window) };
+}
+
+function sourcesValue(sources) {
+ const ids = new Set();
+ for (const source of sources) {
+ if (ids.has(source.id)) throw Error(`Presenter repeats Source ${source.id}.`);
+ ids.add(source.id);
+ }
+ return { sources: structuredClone(sources) };
+}
+
+function intersect(left, right) {
+ return left.flatMap((a) => right.flatMap((b) => {
+ const startFrame = Math.max(a.startFrame, b.startFrame);
+ const endFrameExclusive = Math.min(a.endFrameExclusive, b.endFrameExclusive);
+ return endFrameExclusive > startFrame ? [{ startFrame, endFrameExclusive }] : [];
+ }));
+}
+
+function resolvePresenter(timeline, id, program) {
+ const presents = [];
+ for (const [index, use] of program.uses.entries()) {
+ assertTemporalWindowFor(use.window, { timeline });
+ let visible = [use.window.span];
+ for (const later of program.uses.slice(index + 1)) {
+ visible = visible.flatMap((span) => {
+ const cut = later.window.span;
+ if (cut.endFrameExclusive <= span.startFrame || cut.startFrame >= span.endFrameExclusive) return [span];
+ return [
+ ...(cut.startFrame > span.startFrame ? [{ startFrame: span.startFrame, endFrameExclusive: cut.startFrame }] : []),
+ ...(cut.endFrameExclusive < span.endFrameExclusive ? [{ startFrame: cut.endFrameExclusive, endFrameExclusive: span.endFrameExclusive }] : []),
+ ];
+ });
+ }
+ for (const present of use.visual.presents) {
+ const visibility = intersect(visible, present.visibility ?? [present.span]);
+ if (visibility.length > 0) presents.push({
+ ...present,
+ id: `${id}:${use.window.subjectId}:${present.id}`,
+ visibility,
+ });
+ }
+ }
+ return sealVisualTrack({ id, timelineId: timeline.id, visualIr: "hypit.visual-ir@1", presents });
+}
+
+function ordinaryPresenter(timeline, window, frame, sources, fit, sample, spec) {
+ const layers = [];
+ for (const source of sources.sources) {
+ const startFrame = Math.max(source.window.span.startFrame, window.span.startFrame);
+ const availableEndFrameExclusive = source.window.span.startFrame + source.media.frameDomain.frameCount;
+ const endFrameExclusive = Math.min(
+ source.window.span.endFrameExclusive,
+ window.span.endFrameExclusive,
+ availableEndFrameExclusive,
+ );
+ if (endFrameExclusive <= startFrame) continue;
+ const sourceStartFrame = startFrame - source.window.span.startFrame;
+ const [layer] = appendTimedMediaLayer(createMediaLayerSet(), source.media, fit, {
+ ...sample,
+ id: `${window.subjectId}:${source.id}`,
+ }).layers;
+ layers.push({
+ ...layer,
+ sourceTime: { kind: "map", value: {
+ sourceFrameRate: source.media.frameDomain.frameRate,
+ sourceFrameCount: source.media.frameDomain.frameCount,
+ pieces: [{
+ target: { startFrame: startFrame - window.span.startFrame, endFrameExclusive: endFrameExclusive - window.span.startFrame },
+ sourceAtStart: { numerator: sourceStartFrame, denominator: 1 },
+ rate: { numerator: 1, denominator: 1 },
+ }],
+ } },
+ });
+ }
+ if (layers.length === 0) return sealVisualTrack({ id: window.subjectId, timelineId: timeline.id, visualIr: "hypit.visual-ir@1", presents: [] });
+ const header = { id: window.subjectId };
+ const set = appendVisualClip(createVisualTrackSet(), header, timeline, { layers }, frame, { ...spec, id: window.subjectId }, window);
+ return projectVisualTrack(timeline, finalizeVisualTrack(set, header, timeline));
+}
+
+function ref(element, name, type, resolveReference) {
+ const raw = element.attributes[name];
+ if (raw?.kind !== "reference") throw Error(`${element.name}.${name} must be a reference.`);
+ const value = resolveReference(raw.path);
+ if (!value || !sameType(value.type, type)) throw Error(`${element.name}.${name} has the wrong Type.`);
+ return value;
+}
+
+function authored(value, label) {
+ if (value.record?.value.kind !== "inline") throw Error(`${label} must be an authored inline value.`);
+ return value.record.value.value;
+}
+
+export function installPresenter(module, manifest, component) {
+ const types = presenterTypes(module);
+ manifest.types.push(...Object.values(types).map((type) => ({ name: type.name })));
+ const producers = {
+ source: { module, name: "presenter-source" },
+ combineSources: { module, name: "combine-presenter-sources" },
+ create: { module, name: "create-presenter-program" },
+ append: { module, name: "append-presenter-use" },
+ resolve: { module, name: "resolve-presenter" },
+ ordinary: { module, name: "ordinary-presenter" },
+ };
+ const common = [
+ { name: "timeline", type: timelineTypes.track },
+ { name: "window", type: temporalTypes.window },
+ { name: "sources", type: types.sources },
+ ];
+ manifest.producers.push(
+ { name: producers.source.name, inputs: [
+ { name: "spec", type: types.sourceSpec }, { name: "media", type: mediaTypes.synchronized },
+ { name: "window", type: temporalTypes.window }, { name: "timeline", type: timelineTypes.track },
+ ], outputs: [{ name: "sources", type: types.sources }], needs: [] },
+ { name: producers.combineSources.name, inputs: [{ name: "left", type: types.sources }, { name: "right", type: types.sources }], outputs: [{ name: "sources", type: types.sources }], needs: [] },
+ { name: producers.create.name, inputs: [], outputs: [{ name: "program", type: types.program }], needs: [] },
+ { name: producers.append.name, inputs: [{ name: "program", type: types.program }, { name: "window", type: temporalTypes.window }, { name: "visual", type: compositionTypes.visualTrack }], outputs: [{ name: "program", type: types.program }], needs: [] },
+ { name: producers.resolve.name, inputs: [{ name: "program", type: types.program }, { name: "timeline", type: timelineTypes.track }, { name: "header", type: types.header }], outputs: [{ name: "visual", type: compositionTypes.visualTrack }], needs: [] },
+ );
+ component.producers.push(
+ { producer: producers.source, handler: ({ inputs }) => ({ outputs: { sources: stored(sourcesValue([sourceValue(inline(inputs.spec, "PresenterSourceSpec"), inline(inputs.media, "SynchronizedMedia"), inline(inputs.window, "TemporalWindow"), inline(inputs.timeline, "Timeline"))])) }, needs: {} }) },
+ { producer: producers.combineSources, handler: ({ inputs }) => ({ outputs: { sources: stored(sourcesValue([...inline(inputs.left, "PresenterSources").sources, ...inline(inputs.right, "PresenterSources").sources])) }, needs: {} }) },
+ { producer: producers.create, handler: () => ({ outputs: { program: stored({ uses: [] }) }, needs: {} }) },
+ { producer: producers.append, handler: ({ inputs }) => ({ outputs: { program: stored({ uses: [...inline(inputs.program, "PresenterProgram").uses, { window: inline(inputs.window, "TemporalWindow"), visual: inline(inputs.visual, "VisualTrack") }] }) }, needs: {} }) },
+ { producer: producers.resolve, handler: ({ inputs }) => ({ outputs: { visual: stored(resolvePresenter(inline(inputs.timeline, "Timeline"), inline(inputs.header, "PresenterHeader").id, inline(inputs.program, "PresenterProgram"))) }, needs: {} }) },
+ );
+
+ const ordinaryInputs = [...common, { name: "frame", type: spatialTypes.frame }, { name: "fit", type: spatialTypes.fit },
+ { name: "sample", type: visualTrackTypes.sampleLayerSpec },
+ { name: "spec", type: visualTrackTypes.clipSpec }];
+ manifest.producers.push({ name: producers.ordinary.name, inputs: ordinaryInputs, outputs: [{ name: "visual", type: compositionTypes.visualTrack }], needs: [] });
+ component.producers.push({ producer: producers.ordinary, handler: ({ inputs }) => ({ outputs: { visual: stored(ordinaryPresenter(
+ inline(inputs.timeline, "Timeline"), inline(inputs.window, "TemporalWindow"),
+ inline(inputs.frame, "SpatialFrame"), inline(inputs.sources, "PresenterSources"), inline(inputs.fit, "ContentFit"),
+ inline(inputs.sample, "MediaSampleLayerSpec"), inline(inputs.spec, "VisualClipSpec"),
+ )) }, needs: {} }) });
+ const ordinaryFragment = sealGraphFragment({ inputs: ordinaryInputs, operations: [{ id: "render", producer: producers.ordinary,
+ inputs: Object.fromEntries(ordinaryInputs.map((port) => [port.name, input(port.name)])), result: { kind: "output", name: "visual" } }],
+ exports: [{ name: "visual", type: compositionTypes.visualTrack, root: operation("render") }] });
+
+ const styleFacet = createMarkupSurfaceHostFacet({ module, declaration: {
+ name: "presenter-frame-style", tag: "PresenterFrame", mode: "structured", outputs: [
+ types.style,
+ spatialTypes.fit,
+ visualTrackTypes.sampleLayerSpec,
+ visualTrackTypes.clipSpec,
+ ],
+ vocabulary: { summary: "Project presenter framing treatment.", attributes: [
+ { name: "id", kind: "identifier", required: true, summary: "Treatment identity." },
+ { name: "frame", kind: "reference", required: true, accepts: [spatialTypes.frame], summary: "Presenter viewport." },
+ { name: "appearance", kind: "reference", required: true, accepts: [svsRecipeType], summary: "Presenter media appearance." },
+ ] },
+ }, handler: ({ element, resolveReference }) => {
+ assertAttributes(element, ["id", "frame", "appearance"]); assertEmptyElement(element);
+ const id = textAttribute(element, "id");
+ const frame = ref(element, "frame", spatialTypes.frame, resolveReference);
+ const recipeValue = authored(ref(element, "appearance", svsRecipeType, resolveReference), "Presenter appearance");
+ const records = [];
+ const bind = (name, type, value) => {
+ const recordId = `${id}.${name}`;
+ records.push({ id: recordId, type, value: stored(value), range: element.range });
+ return { ref: { kind: "record", id: recordId }, type };
+ };
+ const sampleType = ordinaryInputs.find((port) => port.name === "sample").type;
+ const specType = ordinaryInputs.find((port) => port.name === "spec").type;
+ const selectedRecipe = (keys) => ({
+ ...recipeValue,
+ properties: Object.fromEntries(Object.entries(recipeValue.properties).filter(([name]) => keys.includes(name))),
+ });
+ const stackingOrder = recipeValue.properties["stack-order"];
+ if (!Number.isSafeInteger(stackingOrder)) throw Error(`Presenter appearance ${recipeValue.path} requires integer stack-order.`);
+ const sampleKeys = [...visualMaterialKeys.fit, ...visualMaterialKeys.sample, ...visualMaterialKeys.sourceTime, ...visualMaterialKeys.frame];
+ const treatmentKeys = [...visualMaterialKeys.sample, ...visualMaterialKeys.frame];
+ const style = presenterStyle(ordinaryFragment, {
+ frame,
+ fit: bind("fit", spatialTypes.fit, decodeMediaFit(selectedRecipe(visualMaterialKeys.fit))),
+ sample: bind("sample", sampleType, decodeMediaSampleSpec(selectedRecipe(sampleKeys), "content", "timed", undefined, true)),
+ spec: bind("spec", specType, decodeVisualClipSpec(selectedRecipe(treatmentKeys), { id, z: stackingOrder })),
+ });
+ records.push({ id, type: types.style, value: stored(style), range: element.range });
+ return { records, components: [], fragments: [] };
+ } });
+
+ const presenterFacet = createMarkupSurfaceHostFacet({ module, declaration: {
+ name: "presenter", tag: "Presenter", mode: "structured", outputs: [
+ types.header,
+ types.sourceSpec,
+ types.sources,
+ types.program,
+ temporalTypes.duration,
+ temporalTypes.extent,
+ temporalTypes.shiftSpec,
+ temporalTypes.instantSpec,
+ temporalTypes.windowSpec,
+ temporalTypes.instant,
+ temporalTypes.window,
+ compositionTypes.visualTrack,
+ ],
+ vocabulary: { summary: "Continuing presenter role owned by the explainer project.", attributes: [
+ { name: "id", kind: "identifier", required: true, summary: "Presenter identity." },
+ { name: "timeline", kind: "reference", required: true, accepts: [timelineTypes.track], summary: "Completed Timeline." },
+ { name: "within", kind: "reference", required: true, accepts: [spatialTypes.frame], summary: "Picture plane available to Presenter treatments that move beyond their local Frame." },
+ ], children: [
+ { tag: "Source", cardinality: "many", summary: "One native presenter media occurrence.", attributes: [
+ { name: "id", kind: "identifier", required: true, summary: "Source identity." },
+ { name: "media", kind: "reference", required: true, accepts: [mediaTypes.synchronized], summary: "Normalized media." },
+ { name: "window", kind: "reference", required: true, accepts: [temporalTypes.window], summary: "Exact native Window." },
+ ] },
+ { tag: "Use", cardinality: "many", summary: "Selects presenter treatment over a Window; later Uses replace earlier ones.", attributes: [
+ { name: "id", kind: "identifier", required: false, summary: "Use identity." },
+ { name: "style", kind: "reference", required: true, accepts: [types.style], summary: "Presenter treatment." },
+ ...temporalWindowAttributeVocabulary,
+ ] },
+ ], ports: [{ name: "visual", type: compositionTypes.visualTrack, summary: "Presenter visual contribution." }] },
+ }, handler: ({ element, resolveReference }) => {
+ assertAttributes(element, ["id", "timeline", "within"]);
+ const id = textAttribute(element, "id");
+ const context = resolveTemporalContext({ element, resolveReference });
+ const within = ref(element, "within", spatialTypes.frame, resolveReference);
+ const records = [{ id: `${id}.header`, type: types.header, value: stored({ id }), range: element.range }];
+ const components = [], fragments = [], sourceDeclarations = [], uses = [];
+ for (const child of element.children) {
+ if (child.kind === "text") { if (child.value.trim()) throw Error("Presenter accepts only Source and Use children."); continue; }
+ const tag = child.name.split(":").at(-1);
+ if (tag === "Source") {
+ assertAttributes(child, ["id", "media", "window"]); assertEmptyElement(child);
+ const sourceId = textAttribute(child, "id"), specId = `${id}.source.${sourceDeclarations.length + 1}`;
+ records.push({ id: specId, type: types.sourceSpec, value: stored({ id: sourceId }), range: child.range });
+ sourceDeclarations.push({ specId, media: ref(child, "media", mediaTypes.synchronized, resolveReference), window: ref(child, "window", temporalTypes.window, resolveReference) });
+ } else if (tag === "Use") uses.push(child);
+ else throw Error("Presenter accepts only Source and Use children.");
+ }
+ if (!sourceDeclarations.length || !uses.length) throw Error("Presenter requires at least one Source and one Use.");
+ const sourceInputs = [{ name: "timeline", type: timelineTypes.track }, ...sourceDeclarations.flatMap((_, index) => [
+ { name: `spec-${index}`, type: types.sourceSpec }, { name: `media-${index}`, type: mediaTypes.synchronized }, { name: `window-${index}`, type: temporalTypes.window },
+ ])];
+ const sourceOps = sourceDeclarations.map((_, index) => ({ id: `source-${index}`, producer: producers.source, inputs: {
+ spec: input(`spec-${index}`), media: input(`media-${index}`), window: input(`window-${index}`), timeline: input("timeline"),
+ }, result: { kind: "output", name: "sources" } }));
+ let sourceRoots = sourceDeclarations.map((_, index) => `source-${index}`);
+ let combineIndex = 0;
+ while (sourceRoots.length > 1) {
+ const nextRoots = [];
+ for (let index = 0; index < sourceRoots.length; index += 2) {
+ const left = sourceRoots[index], right = sourceRoots[index + 1];
+ if (right === undefined) { nextRoots.push(left); continue; }
+ const combineId = `combine-source-${++combineIndex}`;
+ sourceOps.push({ id: combineId, producer: producers.combineSources, inputs: { left: operation(left), right: operation(right) }, result: { kind: "output", name: "sources" } });
+ nextRoots.push(combineId);
+ }
+ sourceRoots = nextRoots;
+ }
+ const [sourceRoot] = sourceRoots;
+ const sourceFragment = sealGraphFragment({ inputs: sourceInputs, operations: sourceOps, exports: [{ name: "sources", type: types.sources, root: operation(sourceRoot) }] });
+ fragments.push(sourceFragment);
+ components.push({ id: `${id}.__sources`, fragment: sourceFragment.id, inputs: { timeline: context.timeline.ref, ...Object.fromEntries(sourceDeclarations.flatMap((source, index) => [
+ [`spec-${index}`, { kind: "record", id: source.specId }], [`media-${index}`, source.media.ref], [`window-${index}`, source.window.ref],
+ ])) }, outputs: { sources: `${id}.__sources.value` }, range: element.range });
+ const collectorInputs = [{ name: "timeline", type: timelineTypes.track }, { name: "header", type: types.header }];
+ const bindings = { timeline: context.timeline.ref, header: { kind: "record", id: `${id}.header` } };
+ const ops = [{ id: "empty", producer: producers.create, inputs: {}, result: { kind: "output", name: "program" } }];
+ let previous = "empty";
+ for (const [index, child] of uses.entries()) {
+ assertAttributes(child, ["id", "style", ...temporalWindowAttributeNames]); assertEmptyElement(child);
+ const useId = optionalTextAttribute(child, "id") ?? `${id}.use.${index + 1}`;
+ const hasTime = temporalWindowAttributeNames.some((name) => child.attributes[name] !== undefined);
+ const temporal = createTemporalWindowConstruction({ id: useId, ...context, resolveReference,
+ element: hasTime ? child : { ...child, attributes: { ...child.attributes, during: "timeline" } } });
+ records.push(...temporal.records); components.push(...temporal.components); fragments.push(...temporal.fragments);
+ const style = authored(ref(child, "style", types.style, resolveReference), "Presenter Style");
+ fragments.push(style.fragment);
+ const needsWithin = style.fragment.inputs.some((port) => port.name === "within");
+ components.push({ id: `${useId}.__style`, fragment: style.fragment.id, inputs: {
+ ...Object.fromEntries(Object.entries(style.bindings).map(([name, value]) => [name, value.ref])),
+ timeline: context.timeline.ref,
+ ...(needsWithin ? { within: within.ref } : {}),
+ sources: { kind: "component-output", component: `${id}.__sources`, output: "sources" }, window: temporal.ref,
+ }, outputs: { visual: `${useId}.visual` }, range: child.range });
+ collectorInputs.push({ name: `window-${index}`, type: temporalTypes.window }, { name: `visual-${index}`, type: compositionTypes.visualTrack });
+ bindings[`window-${index}`] = temporal.ref;
+ bindings[`visual-${index}`] = { kind: "component-output", component: `${useId}.__style`, output: "visual" };
+ const appendId = `append-${index}`;
+ ops.push({ id: appendId, producer: producers.append, inputs: { program: operation(previous), window: input(`window-${index}`), visual: input(`visual-${index}`) }, result: { kind: "output", name: "program" } });
+ previous = appendId;
+ }
+ ops.push({ id: "resolve", producer: producers.resolve, inputs: { program: operation(previous), timeline: input("timeline"), header: input("header") }, result: { kind: "output", name: "visual" } });
+ const collector = sealGraphFragment({ inputs: collectorInputs, operations: ops, exports: [{ name: "program", type: types.program, root: operation(previous) }, { name: "visual", type: compositionTypes.visualTrack, root: operation("resolve") }] });
+ fragments.push(collector);
+ components.push({ id, fragment: collector.id, inputs: bindings, outputs: { program: `${id}.program`, visual: `${id}.visual` }, range: element.range });
+ return { records, components, fragments, exports: [`${id}.program`, `${id}.visual`] };
+ } });
+ return { types, styleFacet, presenterFacet };
+}
diff --git a/examples/complex-explainer/packages/opening-system/src/pullback.js b/examples/complex-explainer/packages/opening-system/src/pullback.js
index 9d8d3dba..36338e5a 100644
--- a/examples/complex-explainer/packages/opening-system/src/pullback.js
+++ b/examples/complex-explainer/packages/opening-system/src/pullback.js
@@ -1,4 +1,4 @@
-import { performanceMedia } from "./performance-media.js";
+import { placedVisualMedia } from "./placed-visual-media.js";
import {
assertAttributes,
assertEmptyElement,
@@ -7,11 +7,7 @@ import {
sealGraphFragment,
createMarkupSurfaceHostFacet,
} from "@hypit/hypit/author-kit";
-import {
- performanceStyle,
- performanceTypes,
- performanceModuleRef,
-} from "@hypit/hypit/performance";
+import { presenterStyle, presenterTypes } from "./presenter.js";
import { sealVisualTrack, compositionTypes } from "@hypit/hypit/composition";
import { timelineTypes } from "@hypit/hypit/timeline";
import { spatialTypes } from "@hypit/hypit/spatial";
@@ -19,17 +15,18 @@ import { temporalTypes } from "@hypit/hypit/temporal";
import { browserProgram } from "@hypit/hypit/hyperframes";
const styles = (o) =>
Object.entries(o).map(([name, value]) => ({ name, value }));
-// A local Use owns the pullback's clock; media continues at its placed source time.
+// A local Use owns the pullback's clock; media continues from its Source Window.
export function installPullback(module, manifest, component, optionsType, mode="pullback") {
+ const types = presenterTypes(module);
const isFade=mode==="fade-out",tag=isFade?"FadeOut":"Pullback";
const inputs = [
{ name: "timeline", type: timelineTypes.track },
- { name: "canvas", type: spatialTypes.canvas },
+ { name: "within", type: spatialTypes.frame },
{ name: "window", type: temporalTypes.window },
+ { name: "sources", type: types.sources },
{ name: "options", type: optionsType },
];
const producer = { module, name: mode };
- if (!manifest.dependencies.some(d=>d.module.name===performanceModuleRef.name)) manifest.dependencies.push({ module: performanceModuleRef });
manifest.producers.push({
name: mode,
inputs,
@@ -59,14 +56,14 @@ export function installPullback(module, manifest, component, optionsType, mode="
component.producers.push({
producer,
handler: ({ inputs }) => {
- const { timeline, canvas, window, options } = Object.fromEntries(
+ const { timeline, within, window, sources, options } = Object.fromEntries(
Object.entries(inputs).map(([k, r]) => {
if (r.value.kind !== "inline")
throw Error("Pullback needs inline inputs");
return [k, r.value.value];
}),
);
- const { clips, children } = performanceMedia(timeline, window);
+ const { clips, children } = placedVisualMedia(timeline, window, sources.sources);
const duration = window.span.endFrameExclusive - window.span.startFrame;
const program = browserProgram({
html:
@@ -88,14 +85,15 @@ export function installPullback(module, manifest, component, optionsType, mode="
const id = window.subjectId,
visual = sealVisualTrack({
id,
- programSpaceId: timeline.id,
+ timelineId: timeline.id,
visualIr: "hypit.visual-ir@1",
presents: children.length
? [
{
id,
+ order: 0,
+ z: 0,
span: window.span,
- stacking: { order: 0, tieBreak: id },
elements: [
{
id: "scene",
@@ -104,9 +102,10 @@ export function installPullback(module, manifest, component, optionsType, mode="
program,
style: styles({
position: "absolute",
- inset: 0,
- width: canvas.widthPx + "px",
- height: canvas.heightPx + "px",
+ left: within.xPx + "px",
+ top: within.yPx + "px",
+ width: within.widthPx + "px",
+ height: within.heightPx + "px",
}),
},
...children,
@@ -127,7 +126,7 @@ export function installPullback(module, manifest, component, optionsType, mode="
name: mode,
tag,
mode: "structured",
- outputs: [performanceTypes.style, optionsType],
+ outputs: [types.style, optionsType],
vocabulary: {
summary:
isFade?"Fade placed footage to transparent across this Use.":"Fast-to-slow pullback of placed footage, settling at ordinary full-frame geometry.",
@@ -168,10 +167,10 @@ export function installPullback(module, manifest, component, optionsType, mode="
},
{
id,
- type: performanceTypes.style,
+ type: types.style,
value: {
kind: "inline",
- value: canonicalize(performanceStyle(fragment, { options })),
+ value: canonicalize(presenterStyle(fragment, { options })),
},
range: element.range,
},
diff --git a/examples/complex-explainer/packages/opening-system/src/reframe.js b/examples/complex-explainer/packages/opening-system/src/reframe.js
index c6bac29e..9ac55c32 100644
--- a/examples/complex-explainer/packages/opening-system/src/reframe.js
+++ b/examples/complex-explainer/packages/opening-system/src/reframe.js
@@ -1,4 +1,4 @@
-import { performanceMedia } from "./performance-media.js";
+import { placedVisualMedia } from "./placed-visual-media.js";
import {
assertAttributes,
assertEmptyElement,
@@ -8,7 +8,7 @@ import {
createMarkupSurfaceHostFacet,
sameType,
} from "@hypit/hypit/author-kit";
-import { performanceStyle, performanceTypes } from "@hypit/hypit/performance";
+import { presenterStyle, presenterTypes } from "./presenter.js";
import { sealVisualTrack, compositionTypes } from "@hypit/hypit/composition";
import { timelineTypes } from "@hypit/hypit/timeline";
import { spatialTypes } from "@hypit/hypit/spatial";
@@ -17,10 +17,12 @@ import { browserProgram } from "@hypit/hypit/hyperframes";
const styles = (o) =>
Object.entries(o).map(([name, value]) => ({ name, value }));
export function installReframe(module, manifest, component) {
+ const types = presenterTypes(module);
const inputs = [
{ name: "timeline", type: timelineTypes.track },
- { name: "canvas", type: spatialTypes.canvas },
+ { name: "within", type: spatialTypes.frame },
{ name: "window", type: temporalTypes.window },
+ { name: "sources", type: types.sources },
{ name: "from", type: spatialTypes.frame },
{ name: "to", type: spatialTypes.frame },
],
@@ -54,10 +56,10 @@ export function installReframe(module, manifest, component) {
component.producers.push({
producer,
handler: ({ inputs }) => {
- const { timeline, canvas, window, from, to } = Object.fromEntries(
+ const { timeline, within, window, sources, from, to } = Object.fromEntries(
Object.entries(inputs).map(([k, r]) => [k, r.value.value]),
),
- { clips, children } = performanceMedia(timeline, window);
+ { clips, children } = placedVisualMedia(timeline, window, sources.sources);
const program = browserProgram({
html:
'<div class="viewport">' +
@@ -74,14 +76,15 @@ export function installReframe(module, manifest, component) {
const id = window.subjectId,
visual = sealVisualTrack({
id,
- programSpaceId: timeline.id,
+ timelineId: timeline.id,
visualIr: "hypit.visual-ir@1",
presents: children.length
? [
{
id,
+ order: 0,
+ z: 60,
span: window.span,
- stacking: { order: 60, tieBreak: id },
elements: [
{
id: "scene",
@@ -90,9 +93,10 @@ export function installReframe(module, manifest, component) {
program,
style: styles({
position: "absolute",
- inset: 0,
- width: canvas.widthPx + "px",
- height: canvas.heightPx + "px",
+ left: within.xPx + "px",
+ top: within.yPx + "px",
+ width: within.widthPx + "px",
+ height: within.heightPx + "px",
}),
},
...children,
@@ -113,7 +117,7 @@ export function installReframe(module, manifest, component) {
name: "reframe",
tag: "Reframe",
mode: "structured",
- outputs: [performanceTypes.style],
+ outputs: [types.style],
vocabulary: {
summary:
"Continuous prepared-performance viewport change between two Frames.",
@@ -150,10 +154,10 @@ export function installReframe(module, manifest, component) {
records: [
{
id: textAttribute(element, "id"),
- type: performanceTypes.style,
+ type: types.style,
value: {
kind: "inline",
- value: canonicalize(performanceStyle(fragment, bindings)),
+ value: canonicalize(presenterStyle(fragment, bindings)),
},
range: element.range,
},
diff --git a/examples/complex-explainer/packages/opening-system/src/render.js b/examples/complex-explainer/packages/opening-system/src/render.js
index 43f5e07b..e9f8ed53 100644
--- a/examples/complex-explainer/packages/opening-system/src/render.js
+++ b/examples/complex-explainer/packages/opening-system/src/render.js
@@ -38,17 +38,18 @@ function text(id, parent, value, font, size, color) {
}),
};
}
-function track(timeline, canvas, window, o, program, children = [], presents) {
- assertTemporalWindowFor(window, { subjectId: o.id, space: timeline });
+function track(timeline, within, window, o, program, children = [], presents) {
+ assertTemporalWindowFor(window, { subjectId: o.id, timeline: timeline });
return sealVisualTrack({
id: o.id,
- programSpaceId: timeline.id,
+ timelineId: timeline.id,
visualIr: "hypit.visual-ir@1",
presents: presents ?? [
{
id: o.id,
+ order: 0,
+ z: o.z,
span: window.span,
- stacking: { order: o.z, tieBreak: o.id },
elements: [
{
id: "scene",
@@ -57,9 +58,10 @@ function track(timeline, canvas, window, o, program, children = [], presents) {
program,
style: style({
position: "absolute",
- inset: 0,
- width: canvas.widthPx + "px",
- height: canvas.heightPx + "px",
+ left: within.xPx + "px",
+ top: within.yPx + "px",
+ width: within.widthPx + "px",
+ height: within.heightPx + "px",
}),
},
...children,
@@ -68,12 +70,12 @@ function track(timeline, canvas, window, o, program, children = [], presents) {
],
});
}
-export function renderTitle(timeline, canvas, window, font, o, bounce) {
- const w = canvas.widthPx;
+export function renderTitle(timeline, within, window, font, o, bounce) {
+ const w = within.widthPx;
const letters = Array.from(o.title);
return track(
timeline,
- canvas,
+ within,
window,
o,
browserProgram({
@@ -130,11 +132,11 @@ return frame=>{
);
}
-export function renderTimer(timeline, canvas, window, font, o, logo, stop) {
+export function renderTimer(timeline, within, window, font, o, logo, stop) {
const fps = timeline.frameRate.numerator / timeline.frameRate.denominator;
return track(
timeline,
- canvas,
+ within,
window,
o,
browserProgram({
@@ -167,7 +169,7 @@ export function renderTimer(timeline, canvas, window, font, o, logo, stop) {
"scene",
o.title,
font,
- canvas.widthPx * o.width * 0.16,
+ within.widthPx * o.width * 0.16,
`${palette.ink}`,
),
text(
@@ -175,7 +177,7 @@ export function renderTimer(timeline, canvas, window, font, o, logo, stop) {
"scene",
o.subtitle,
font,
- canvas.widthPx * o.width * 0.067,
+ within.widthPx * o.width * 0.067,
`${palette.ink}`,
),
{
@@ -189,7 +191,7 @@ export function renderTimer(timeline, canvas, window, font, o, logo, stop) {
],
);
}
-export function renderStage(timeline, canvas, window, items, o) {
+export function renderStage(timeline, within, window, items, o) {
const presents = [];
for (const [index, item] of items.entries()) {
const start = Math.max(window.span.startFrame, item.window.span.startFrame),
@@ -198,13 +200,13 @@ export function renderStage(timeline, canvas, window, items, o) {
item.window.span.endFrameExclusive,
);
if (end <= start) continue;
- const w = canvas.widthPx,
- h = canvas.heightPx;
+ const w = within.widthPx,
+ h = within.heightPx;
const artifact = item.media?.visual?.artifact ?? item.image;
if (!artifact) throw Error("Stage video needs prepared visual media.");
- let sampling;
+ let sourceTime;
if (item.media) {
- const sourceRate = item.media.timeline.frameRate,
+ const sourceRate = item.media.frameDomain.frameRate,
rate = {
numerator: sourceRate.numerator * timeline.frameRate.denominator,
denominator: sourceRate.denominator * timeline.frameRate.numerator,
@@ -215,17 +217,17 @@ export function renderStage(timeline, canvas, window, items, o) {
rate.denominator;
const last =
offset + ((end - start - 1) * rate.numerator) / rate.denominator;
- if (last >= item.media.timeline.frameCount)
+ if (last >= item.media.frameDomain.frameCount)
throw Error(
"Stage window exceeds the supplied video. Shorten its window or supply longer media.",
);
- sampling = {
+ sourceTime = {
sourceFrameRate: sourceRate,
- sourceFrameCount: item.media.timeline.frameCount,
- segments: [
+ sourceFrameCount: item.media.frameDomain.frameCount,
+ pieces: [
{
target: { startFrame: 0, endFrameExclusive: end - start },
- sourceFrame: {
+ sourceAtStart: {
numerator: Math.round(offset * rate.denominator),
denominator: rate.denominator,
},
@@ -241,7 +243,7 @@ export function renderStage(timeline, canvas, window, items, o) {
kind: item.media ? "video" : "image",
artifact,
muted: true,
- ...(sampling ? { sampling } : {}),
+ ...(sourceTime ? { sourceTime } : {}),
style: style({
position: "absolute",
inset: 0,
@@ -268,9 +270,10 @@ export function renderStage(timeline, canvas, window, items, o) {
});
presents.push({
id: `${o.id}.${item.id}`,
+ order: index,
+ z: o.z,
subjectId: item.id,
span: { startFrame: start, endFrameExclusive: end },
- stacking: { order: o.z, tieBreak: String(index).padStart(6, "0") },
elements: [
{
id: "scene",
@@ -288,12 +291,12 @@ export function renderStage(timeline, canvas, window, items, o) {
],
});
}
- return track(timeline, canvas, window, o, undefined, [], presents);
+ return track(timeline, within, window, o, undefined, [], presents);
}
// An independent screen texture: the author's stack places it above picture and below graphics.
-export function renderVeil(timeline, canvas, window, o) {
- const cell = (o.cell * canvas.widthPx) / 1080;
+export function renderVeil(timeline, within, window, o) {
+ const cell = (o.cell * within.widthPx) / 1080;
const patterns = {
mesh: `repeating-conic-gradient(from 45deg,rgba(255,255,255,.52) 0% 25%,rgba(0,0,0,.55) 0% 50%)`,
dots: `radial-gradient(circle,rgba(0,0,0,.8) 0 22%,transparent 26%)`,
@@ -301,7 +304,7 @@ export function renderVeil(timeline, canvas, window, o) {
};
return track(
timeline,
- canvas,
+ within,
window,
o,
browserProgram({
@@ -316,8 +319,8 @@ export function renderVeil(timeline, canvas, window, o) {
);
}
-export function renderFlag(timeline, canvas, window, o, logo) {
- return track(timeline, canvas, window, o, browserProgram({
+export function renderFlag(timeline, within, window, o, logo) {
+ return track(timeline, within, window, o, browserProgram({
html: '<div class="floor-cloth"><canvas class="flag-canvas"></canvas></div><div class="logo-resource">{{flag-logo}}</div>',
css: `:scope{pointer-events:none}.floor-cloth{position:absolute;left:${o.x*100}%;top:${o.y*100}%;width:${o.width*100}%;height:${o.height*100}%;filter:none}.flag-canvas{display:block;width:100%;height:100%;image-rendering:pixelated}.logo-resource{position:absolute;opacity:0;width:1px;height:1px}`,
data: {fps:timeline.frameRate.numerator/timeline.frameRate.denominator,flagPose:'floor',flagColor:o.flagColor,flagAmplitude:o.flagAmplitude,flagSpeed:o.flagSpeed},
diff --git a/examples/complex-explainer/packages/single-line-captions/package.json b/examples/complex-explainer/packages/single-line-captions/package.json
index 34b023dd..053d1e42 100644
--- a/examples/complex-explainer/packages/single-line-captions/package.json
+++ b/examples/complex-explainer/packages/single-line-captions/package.json
@@ -5,5 +5,10 @@
"type": "module",
"hypit": {
"activation": "./src/activation.js"
+ },
+ "dependencies": {
+ "@hypit/caption-fine": "workspace:*",
+ "@hypit/caption-fine-studio": "workspace:*",
+ "@hypit/hypit": "workspace:*"
}
-}
\ No newline at end of file
+}
diff --git a/examples/complex-explainer/packages/web-scenes/package.json b/examples/complex-explainer/packages/web-scenes/package.json
index af37d59b..b782715e 100644
--- a/examples/complex-explainer/packages/web-scenes/package.json
+++ b/examples/complex-explainer/packages/web-scenes/package.json
@@ -10,6 +10,7 @@
".": "./src/render.js"
},
"dependencies": {
- "@explainer/visual-language": "file:../visual-language"
+ "@explainer/visual-language": "file:../visual-language",
+ "@hypit/hypit": "workspace:*"
}
}
diff --git a/examples/complex-explainer/packages/web-scenes/src/activation.js b/examples/complex-explainer/packages/web-scenes/src/activation.js
index 8785c9e9..176e9ed9 100644
--- a/examples/complex-explainer/packages/web-scenes/src/activation.js
+++ b/examples/complex-explainer/packages/web-scenes/src/activation.js
@@ -22,8 +22,8 @@ import { spatialTypes } from "@hypit/hypit/spatial";
import { temporalTypes, assertTemporalInstantFor } from "@hypit/hypit/temporal";
import {
resolveTemporalContext,
- createTemporalWindowProjection,
- createTemporalInstantProjection,
+ createTemporalWindowConstruction,
+ createTemporalInstantConstruction,
temporalWindowAttributeNames,
temporalWindowAttributeVocabulary,
temporalContextAttributeVocabulary,
@@ -39,7 +39,7 @@ const options = type("Options"),
events = type("Events");
const common = [
port("timeline", timelineTypes.track),
- port("canvas", spatialTypes.canvas),
+ port("within", spatialTypes.frame),
port("window", temporalTypes.window),
port("font", mediaTypes.fontArtifact),
port("options", options),
@@ -187,9 +187,10 @@ export const manifest = {
mediaTypes.fontArtifact,
mediaTypes.synchronized,
timelineTypes.track,
- spatialTypes.canvas,
+ spatialTypes.frame,
temporalTypes.window,
temporalTypes.instant,
+ temporalTypes.duration, temporalTypes.extent, temporalTypes.shiftSpec,
].map((t) => [t.module.name, { module: t.module }]),
).values(),
],
@@ -246,7 +247,7 @@ const component = {
"track",
tags[tag].render(
inline(i.timeline),
- inline(i.canvas),
+ inline(i.within),
inline(i.window),
inline(i.font),
inline(i.options),
@@ -265,7 +266,7 @@ function decode(tag) {
assertAttributes(element, [
"id",
"timeline",
- "canvas",
+ "within",
"font",
...spec.assets,
...Object.keys(spec.defaults),
@@ -273,7 +274,7 @@ function decode(tag) {
]);
const id = textAttribute(element, "id"),
context = resolveTemporalContext({ element, resolveReference }),
- window = createTemporalWindowProjection({
+ window = createTemporalWindowConstruction({
id: id + ".window",
subjectId: id,
element,
@@ -309,7 +310,7 @@ function decode(tag) {
const inputs = ins(tag).filter((p) => p.name !== "events"),
bindings = {
timeline: context.timeline.ref,
- canvas: ref(element, "canvas", spatialTypes.canvas),
+ within: ref(element, "within", spatialTypes.frame),
window: window.ref,
font: ref(element, "font", mediaTypes.fontArtifact),
options: { kind: "record", id: id + ".options" },
@@ -338,7 +339,7 @@ function decode(tag) {
const name = textAttribute(ch, "name"),
key = "beat" + ++count,
eid = id + "." + key,
- at = createTemporalInstantProjection({
+ at = createTemporalInstantConstruction({
id: eid,
subjectId: eid,
element: ch,
@@ -387,7 +388,7 @@ function decode(tag) {
operations,
exports: [
{
- name: "track",
+ name: "visual",
type: compositionTypes.visualTrack,
root: op("render"),
},
@@ -402,11 +403,11 @@ function decode(tag) {
id,
fragment: fragment.id,
inputs: bindings,
- outputs: { track: id + ".track" },
+ outputs: { visual: id + ".visual" },
range: element.range,
},
],
- exports: [id + ".track"],
+ exports: [id + ".visual"],
};
};
}
@@ -431,13 +432,14 @@ export const hypitPackage = {
temporalTypes.instant,
temporalTypes.windowSpec,
temporalTypes.instantSpec,
+ temporalTypes.duration, temporalTypes.extent, temporalTypes.shiftSpec,
],
vocabulary: {
summary: "Project launch scene with phrase-driven visual beats.",
attributes: [
...temporalContextAttributeVocabulary,
...temporalWindowAttributeVocabulary,
- ...["id", "canvas", "font", ...tags[tag].assets].map((name) => ({
+ ...["id", "within", "font", ...tags[tag].assets].map((name) => ({
name,
kind: "expression",
required: true,
@@ -468,7 +470,7 @@ export const hypitPackage = {
],
ports: [
{
- name: "track",
+ name: "visual",
type: compositionTypes.visualTrack,
summary: "Visual contribution",
},
diff --git a/examples/complex-explainer/packages/web-scenes/src/scenes/introduction/index.js b/examples/complex-explainer/packages/web-scenes/src/scenes/introduction/index.js
index b5e01403..6dddfe58 100644
--- a/examples/complex-explainer/packages/web-scenes/src/scenes/introduction/index.js
+++ b/examples/complex-explainer/packages/web-scenes/src/scenes/introduction/index.js
@@ -46,13 +46,14 @@ export function renderIntro(t, c, w, font, o, events, m) {
)
.join("");
const terminal = `
-<time:Timeline id="program" clock="{clock}">
- <time:Take source="{host.take}" />
+<time:Timeline id="program" clock="{clock}" end="host.end">
+ <time:Window id="host" from="start" for="{host.extent}" />
</time:Timeline>
-<performance:Track timeline="{program.timeline}">
- <performance:Use style="{portrait}" />
-</performance:Track>
+<visual:Track timeline="{program.timeline}">
+ <visual:Clip id="host" media="{host.media}" during="{program.host}"
+ frame="{portrait.frame}" z="10" fit="cover" />
+</visual:Track>
<ranking:Board timeline="{program.timeline}">
<ranking:Reveal at="{story.moment.first}" image="{product}" tier="S" />
@@ -64,7 +65,7 @@ export function renderIntro(t, c, w, font, o, events, m) {
<film:Film timeline="{program.timeline}">
<film:Track source="{presenter.visual}" />
- <film:Track source="{board.track}" />
+ <film:Track source="{board.visual}" />
</film:Film>`;
return scene(
t,
diff --git a/examples/complex-explainer/packages/web-scenes/src/scenes/semantic-time/index.js b/examples/complex-explainer/packages/web-scenes/src/scenes/semantic-time/index.js
index 166abb46..225df1cd 100644
--- a/examples/complex-explainer/packages/web-scenes/src/scenes/semantic-time/index.js
+++ b/examples/complex-explainer/packages/web-scenes/src/scenes/semantic-time/index.js
@@ -58,7 +58,7 @@ export function renderSemanticWorkshop(t, c, w, font, o, events, m) {
><div class="voice-shape">${Array.from({ length: 85 }, (_, i) => `<i style="--i:${i}"></i>`).join("")}</div><div class="voice-chip">♫ 新的配音</div></div
>
<div class="script-source work-window"
- >${bar("main.svml")}<pre><span>&lt;script id="story"&gt;</span><br> &lt;intro&gt;<br> &lt;HOST&gt; 今天的 <em>@winner</em> 第一名<em>@/winner</em>,<br> 就是 <em>@product!</em> Hypit。<br> &lt;/intro&gt;<br><span>&lt;/script&gt;</span><br><br><span>&lt;media:Track</span> timeline={program.timeline}<br> canvas={canvas}<span>&gt;</span><br> <span>&lt;media:Item</span> media={product.media}<br> frame={layout.product}<br> at=<em>{story.moment.product}</em> for="2s"<br> appearance={styles.product}<span>/&gt;</span><br><span>&lt;/media:Track&gt;</span></pre></div
+ >${bar("main.svml")}<pre><span>&lt;script id="story"&gt;</span><br> &lt;intro&gt;<br> &lt;HOST&gt; 今天的 <em>@winner</em> 第一名<em>@/winner</em>,<br> 就是 <em>@product!</em> Hypit。<br> &lt;/intro&gt;<br><span>&lt;/script&gt;</span><br><br><span>&lt;visual:Track</span> timeline={program.timeline}<span>&gt;</span><br> <span>&lt;visual:Clip</span> media={product.media}<br> frame={layout.product} z="20" fit="cover"<br> at=<em>{story.moment.product}</em> for="2s"<span>/&gt;</span><br><span>&lt;/visual:Track&gt;</span></pre></div
>${pointer}`;
return scene(t, c, w, font, o, html, workCss + studioCss + css, workSetup + animation, events, {
creatify: { image: m.creatify },
diff --git a/examples/complex-explainer/packages/web-scenes/src/shared/scene.js b/examples/complex-explainer/packages/web-scenes/src/shared/scene.js
index 115ca505..5829922d 100644
--- a/examples/complex-explainer/packages/web-scenes/src/shared/scene.js
+++ b/examples/complex-explainer/packages/web-scenes/src/shared/scene.js
@@ -4,8 +4,8 @@ import { sealVisualTrack } from "@hypit/hypit/composition";
import { browserProgram } from "@hypit/hypit/hyperframes";
import { assertTemporalWindowFor } from "@hypit/hypit/temporal";
const styles = (o) => Object.entries(o).map(([name, value]) => ({ name, value }));
-export function scene(t, c, w, font, o, html, css, setup, events, entries, extra = {}) {
- assertTemporalWindowFor(w, { subjectId: o.id, space: t });
+export function scene(t, within, w, font, o, html, css, setup, events, entries, extra = {}) {
+ assertTemporalWindowFor(w, { subjectId: o.id, timeline: t });
const beats = Object.fromEntries(events.map((e) => [e.name, e.at.frame - w.span.startFrame]));
const count = w.span.endFrameExclusive - w.span.startFrame;
const backgrounds = [];
@@ -59,10 +59,10 @@ export function scene(t, c, w, font, o, html, css, setup, events, entries, extra
kind: "video",
artifact: m.visual.artifact,
muted: true,
- sampling: {
+ sourceTime: {
sourceFrameRate: src,
sourceFrameCount: m.timeline.frameCount,
- segments: v.holdLast
+ pieces: v.holdLast
? (() => {
const played = Math.min(
end - start,
@@ -71,14 +71,14 @@ export function scene(t, c, w, font, o, html, css, setup, events, entries, extra
segments = [
{
target: { startFrame: start, endFrameExclusive: start + played },
- sourceFrame: { numerator: 0, denominator: 1 },
+ sourceAtStart: { numerator: 0, denominator: 1 },
rate,
},
];
if (start + played < end)
segments.push({
target: { startFrame: start + played, endFrameExclusive: end },
- sourceFrame: { numerator: m.timeline.frameCount - 1, denominator: 1 },
+ sourceAtStart: { numerator: m.timeline.frameCount - 1, denominator: 1 },
rate: { numerator: 0, denominator: 1 },
});
return segments;
@@ -96,7 +96,7 @@ export function scene(t, c, w, font, o, html, css, setup, events, entries, extra
a = start + i * n;
return {
target: { startFrame: a, endFrameExclusive: Math.min(end, a + n) },
- sourceFrame: { numerator: 0, denominator: 1 },
+ sourceAtStart: { numerator: 0, denominator: 1 },
rate,
};
},
@@ -104,7 +104,7 @@ export function scene(t, c, w, font, o, html, css, setup, events, entries, extra
: [
{
target: { startFrame: start, endFrameExclusive: end },
- sourceFrame: { numerator: 0, denominator: 1 },
+ sourceAtStart: { numerator: 0, denominator: 1 },
rate,
},
],
@@ -113,13 +113,14 @@ export function scene(t, c, w, font, o, html, css, setup, events, entries, extra
});
return sealVisualTrack({
id: o.id,
- programSpaceId: t.id,
+ timelineId: t.id,
visualIr: "hypit.visual-ir@1",
presents: [
{
id: o.id,
+ order: 0,
+ z: o.z,
span: w.span,
- stacking: { order: o.z, tieBreak: o.id },
elements: [
{
id: "scene",
@@ -142,9 +143,10 @@ export function scene(t, c, w, font, o, html, css, setup, events, entries, extra
}),
style: styles({
position: "absolute",
- inset: 0,
- width: c.widthPx + "px",
- height: c.heightPx + "px",
+ left: within.xPx + "px",
+ top: within.yPx + "px",
+ width: within.widthPx + "px",
+ height: within.heightPx + "px",
}),
},
{
diff --git a/examples/complex-explainer/productions/explainer/CRAFT-NOTES.md b/examples/complex-explainer/productions/explainer/CRAFT-NOTES.md
index 99c34f38..ae7236f8 100644
--- a/examples/complex-explainer/productions/explainer/CRAFT-NOTES.md
+++ b/examples/complex-explainer/productions/explainer/CRAFT-NOTES.md
@@ -43,7 +43,7 @@ For one concrete trace, [Script](authors/script.svml) places `road-fail` at the
is difficult. [Main Source](authors/main.svml) connects that meaning to the editor scene:
```svml
-<webscene:Beat name="fail" at={copy.story.moment.road-fail}/>
+<webscene:Beat name="fail" at={story-time.moment-road-fail-cue}/>
```
The scene projects the event to a frame. Its
diff --git a/examples/complex-explainer/productions/explainer/authors/main.svml b/examples/complex-explainer/productions/explainer/authors/main.svml
index 123bd3fe..adf19a02 100644
--- a/examples/complex-explainer/productions/explainer/authors/main.svml
+++ b/examples/complex-explainer/productions/explainer/authors/main.svml
@@ -1,18 +1,21 @@
<?svml using="@hypit/markup@1"?>
<svml>
+
+ <import as="media" from="@hypit/media@1"/>
<import as="copy" source="./script.svml"/>
<import as="assets" source="./assets.svml"/>
<import as="direction" source="./direction.svml"/>
<import as="seedance" from="@hypit/seedance@1"/>
<import as="pipeline" from="@hypit/media-pipeline@1"/>
<import as="whisperx" from="@hypit/whisperx@1"/>
+ <import as="semantic" from="@hypit/narrative-temporal@1"/>
<import as="time" from="@hypit/timeline-author@1"/>
<import as="webscene" from="@explainer/web-scenes@1"/>
<import as="launch" from="@explainer/launch-scenes@1"/>
- <import as="performance" from="@hypit/performance@1"/>
- <import as="sound" from="@hypit/sound@1"/>
+ <import as="visual" from="@hypit/visual-track@1"/>
<import as="audio" from="@hypit/audio-track@1"/>
<import as="caption" from="@hypit/caption@1"/>
+ <import as="narrative-caption" from="@hypit/narrative-caption@1"/>
<import as="linecaption" from="@explainer/single-line-captions@1"/>
<import as="caption-fine" from="@hypit/caption-fine@1"/>
<import as="film" from="@hypit/film@1"/>
@@ -31,103 +34,120 @@
<seedance:Reference audio={assets.voice-reference}/>
</seedance:ReferenceVideo>
<pipeline:Normalize id="opening-media" source={opening-generation.video} clock={assets.clock} video="primary-moving" audio="default" span-authority="video"/>
- <whisperx:SemanticTake id="opening" narrative={copy.story} segment={copy.story.segment.opening} media={opening-media.media} language="zh"/>
+ <whisperx:Alignment id="opening" narrative={copy.story}
+ segment={copy.story.segment.opening} media={opening-media.media} domain={opening-media.domain} language="zh"/>
<seedance:ReferenceVideo id="introduction-generation" model="mini" prompt={direction.introduction-prompt} duration="11" resolution="720p" aspect-ratio="9:16" generate-audio="true">
<seedance:Reference image={assets.presenter-reference} person-reference="true"/>
<seedance:Reference audio={assets.voice-reference}/>
</seedance:ReferenceVideo>
<pipeline:Normalize id="introduction-media" source={introduction-generation.video} clock={assets.clock} video="primary-moving" audio="default" span-authority="video"/>
- <whisperx:SemanticTake id="introduction" narrative={copy.story} segment={copy.story.segment.introduction} media={introduction-media.media} language="zh"/>
+ <whisperx:Alignment id="introduction" narrative={copy.story}
+ segment={copy.story.segment.introduction} media={introduction-media.media} domain={introduction-media.domain} language="zh"/>
<seedance:ReferenceVideo id="competitors-generation" model="mini" prompt={direction.competitors-prompt} duration="8" resolution="720p" aspect-ratio="9:16" generate-audio="true">
<seedance:Reference image={assets.presenter-reference} person-reference="true"/>
<seedance:Reference audio={assets.voice-reference}/>
</seedance:ReferenceVideo>
<pipeline:Normalize id="competitors-media" source={competitors-generation.video} clock={assets.clock} video="primary-moving" audio="default" span-authority="video"/>
- <whisperx:SemanticTake id="competitors" narrative={copy.story} segment={copy.story.segment.competitors} media={competitors-media.media} language="zh"/>
+ <whisperx:Alignment id="competitors" narrative={copy.story}
+ segment={copy.story.segment.competitors} media={competitors-media.media} domain={competitors-media.domain} language="zh"/>
<seedance:ReferenceVideo id="two-roads-generation" model="mini" prompt={direction.two-roads-prompt} duration="6" resolution="720p" aspect-ratio="9:16" generate-audio="true">
<seedance:Reference image={assets.presenter-reference} person-reference="true"/>
<seedance:Reference audio={assets.voice-reference}/>
</seedance:ReferenceVideo>
<pipeline:Normalize id="two-roads-media" source={two-roads-generation.video} clock={assets.clock} video="primary-moving" audio="default" span-authority="video"/>
- <whisperx:SemanticTake id="two-roads" narrative={copy.story} segment={copy.story.segment.two-roads} media={two-roads-media.media} language="zh"/>
+ <whisperx:Alignment id="two-roads" narrative={copy.story}
+ segment={copy.story.segment.two-roads} media={two-roads-media.media} domain={two-roads-media.domain} language="zh"/>
<seedance:ReferenceVideo id="editor-road-generation" model="mini" prompt={direction.editor-road-prompt} duration="8" resolution="720p" aspect-ratio="9:16" generate-audio="true">
<seedance:Reference image={assets.presenter-reference} person-reference="true"/>
<seedance:Reference audio={assets.voice-reference}/>
</seedance:ReferenceVideo>
<pipeline:Normalize id="editor-road-media" source={editor-road-generation.video} clock={assets.clock} video="primary-moving" audio="default" span-authority="video"/>
- <whisperx:SemanticTake id="editor-road" narrative={copy.story} segment={copy.story.segment.editor-road} media={editor-road-media.media} language="zh"/>
+ <whisperx:Alignment id="editor-road" narrative={copy.story}
+ segment={copy.story.segment.editor-road} media={editor-road-media.media} domain={editor-road-media.domain} language="zh"/>
<seedance:ReferenceVideo id="keyframe-cost-generation" model="mini" prompt={direction.keyframe-cost-prompt} duration="13" resolution="720p" aspect-ratio="9:16" generate-audio="true">
<seedance:Reference image={assets.presenter-reference} person-reference="true"/>
<seedance:Reference audio={assets.voice-reference}/>
</seedance:ReferenceVideo>
<pipeline:Normalize id="keyframe-cost-media" source={keyframe-cost-generation.video} clock={assets.clock} video="primary-moving" audio="default" span-authority="video"/>
- <whisperx:SemanticTake id="keyframe-cost" narrative={copy.story} segment={copy.story.segment.keyframe-cost} media={keyframe-cost-media.media} language="zh"/>
+ <whisperx:Alignment id="keyframe-cost" narrative={copy.story}
+ segment={copy.story.segment.keyframe-cost} media={keyframe-cost-media.media} domain={keyframe-cost-media.domain} language="zh"/>
<seedance:ReferenceVideo id="code-road-generation" model="mini" prompt={direction.code-road-prompt} duration="6" resolution="720p" aspect-ratio="9:16" generate-audio="true">
<seedance:Reference image={assets.presenter-reference} person-reference="true"/>
<seedance:Reference audio={assets.voice-reference}/>
</seedance:ReferenceVideo>
<pipeline:Normalize id="code-road-media" source={code-road-generation.video} clock={assets.clock} video="primary-moving" audio="default" span-authority="video"/>
- <whisperx:SemanticTake id="code-road" narrative={copy.story} segment={copy.story.segment.code-road} media={code-road-media.media} language="zh"/>
+ <whisperx:Alignment id="code-road" narrative={copy.story}
+ segment={copy.story.segment.code-road} media={code-road-media.media} domain={code-road-media.domain} language="zh"/>
<seedance:ReferenceVideo id="reuse-cost-generation" model="mini" prompt={direction.reuse-cost-prompt} duration="8" resolution="720p" aspect-ratio="9:16" generate-audio="true">
<seedance:Reference image={assets.presenter-reference} person-reference="true"/>
<seedance:Reference audio={assets.voice-reference}/>
</seedance:ReferenceVideo>
<pipeline:Normalize id="reuse-cost-media" source={reuse-cost-generation.video} clock={assets.clock} video="primary-moving" audio="default" span-authority="video"/>
- <whisperx:SemanticTake id="reuse-cost" narrative={copy.story} segment={copy.story.segment.reuse-cost} media={reuse-cost-media.media} language="zh"/>
+ <whisperx:Alignment id="reuse-cost" narrative={copy.story}
+ segment={copy.story.segment.reuse-cost} media={reuse-cost-media.media} domain={reuse-cost-media.domain} language="zh"/>
<seedance:ReferenceVideo id="timing-cost-generation" model="mini" prompt={direction.timing-cost-prompt} duration="8" resolution="720p" aspect-ratio="9:16" generate-audio="true">
<seedance:Reference image={assets.presenter-reference} person-reference="true"/>
<seedance:Reference audio={assets.voice-reference}/>
</seedance:ReferenceVideo>
<pipeline:Normalize id="timing-cost-media" source={timing-cost-generation.video} clock={assets.clock} video="primary-moving" audio="default" span-authority="video"/>
- <whisperx:SemanticTake id="timing-cost" narrative={copy.story} segment={copy.story.segment.timing-cost} media={timing-cost-media.media} language="zh"/>
+ <whisperx:Alignment id="timing-cost" narrative={copy.story}
+ segment={copy.story.segment.timing-cost} media={timing-cost-media.media} domain={timing-cost-media.domain} language="zh"/>
<seedance:ReferenceVideo id="water-break-generation" model="mini" prompt={direction.water-break-prompt} duration="4" resolution="720p" aspect-ratio="9:16" generate-audio="true">
<seedance:Reference image={assets.presenter-reference} person-reference="true"/>
<seedance:Reference audio={assets.voice-reference}/>
</seedance:ReferenceVideo>
<pipeline:Normalize id="water-break-media" source={water-break-generation.video} clock={assets.clock} video="primary-moving" audio="default" span-authority="video"/>
- <whisperx:SemanticTake id="water-break" narrative={copy.story} segment={copy.story.segment.water-break} media={water-break-media.media} language="zh"/>
+ <whisperx:Alignment id="water-break" narrative={copy.story}
+ segment={copy.story.segment.water-break} media={water-break-media.media} domain={water-break-media.domain} language="zh"/>
<seedance:ReferenceVideo id="synthesis-generation" model="mini" prompt={direction.synthesis-prompt} duration="5" resolution="720p" aspect-ratio="9:16" generate-audio="true">
<seedance:Reference image={assets.presenter-reference} person-reference="true"/>
<seedance:Reference audio={assets.voice-reference}/>
</seedance:ReferenceVideo>
<pipeline:Normalize id="synthesis-media" source={synthesis-generation.video} clock={assets.clock} video="primary-moving" audio="default" span-authority="video"/>
- <whisperx:SemanticTake id="synthesis" narrative={copy.story} segment={copy.story.segment.synthesis} media={synthesis-media.media} language="zh"/>
+ <whisperx:Alignment id="synthesis" narrative={copy.story}
+ segment={copy.story.segment.synthesis} media={synthesis-media.media} domain={synthesis-media.domain} language="zh"/>
<seedance:ReferenceVideo id="components-generation" model="mini" prompt={direction.components-prompt} duration="12" resolution="720p" aspect-ratio="9:16" generate-audio="true">
<seedance:Reference image={assets.presenter-reference} person-reference="true"/>
<seedance:Reference audio={assets.voice-reference}/>
</seedance:ReferenceVideo>
<pipeline:Normalize id="components-media" source={components-generation.video} clock={assets.clock} video="primary-moving" audio="default" span-authority="video"/>
- <whisperx:SemanticTake id="components" narrative={copy.story} segment={copy.story.segment.components} media={components-media.media} language="zh"/>
+ <whisperx:Alignment id="components" narrative={copy.story}
+ segment={copy.story.segment.components} media={components-media.media} domain={components-media.domain} language="zh"/>
<seedance:ReferenceVideo id="semantic-time-generation" model="mini" prompt={direction.semantic-time-prompt} duration="5" resolution="720p" aspect-ratio="9:16" generate-audio="true">
<seedance:Reference image={assets.presenter-reference} person-reference="true"/>
<seedance:Reference audio={assets.voice-reference}/>
</seedance:ReferenceVideo>
<pipeline:Normalize id="semantic-time-media" source={semantic-time-generation.video} clock={assets.clock} video="primary-moving" audio="default" span-authority="video"/>
- <whisperx:SemanticTake id="semantic-time" narrative={copy.story} segment={copy.story.segment.semantic-time} media={semantic-time-media.media} language="zh"/>
+ <whisperx:Alignment id="semantic-time" narrative={copy.story}
+ segment={copy.story.segment.semantic-time} media={semantic-time-media.media} domain={semantic-time-media.domain} language="zh"/>
<seedance:ReferenceVideo id="semantic-demo-generation" model="mini" prompt={direction.semantic-demo-prompt} duration="10" resolution="720p" aspect-ratio="9:16" generate-audio="true">
<seedance:Reference image={assets.presenter-reference} person-reference="true"/>
<seedance:Reference audio={assets.voice-reference}/>
</seedance:ReferenceVideo>
<pipeline:Normalize id="semantic-demo-media" source={semantic-demo-generation.video} clock={assets.clock} video="primary-moving" audio="default" span-authority="video"/>
- <whisperx:SemanticTake id="semantic-demo" narrative={copy.story} segment={copy.story.segment.semantic-demo} media={semantic-demo-media.media} language="zh"/>
+ <whisperx:Alignment id="semantic-demo" narrative={copy.story}
+ segment={copy.story.segment.semantic-demo} media={semantic-demo-media.media} domain={semantic-demo-media.domain} language="zh"/>
<seedance:ReferenceVideo id="result-generation" model="mini" prompt={direction.result-prompt} duration="8" resolution="720p" aspect-ratio="9:16" generate-audio="true">
<seedance:Reference image={assets.presenter-reference} person-reference="true"/>
<seedance:Reference audio={assets.voice-reference}/>
</seedance:ReferenceVideo>
<pipeline:Normalize id="result-media" source={result-generation.video} clock={assets.clock} video="primary-moving" audio="default" span-authority="video"/>
- <whisperx:SemanticTake id="result" narrative={copy.story} segment={copy.story.segment.result} media={result-media.media} language="zh"/>
+ <whisperx:Alignment id="result" narrative={copy.story}
+ segment={copy.story.segment.result} media={result-media.media} domain={result-media.domain} language="zh"/>
<seedance:ReferenceVideo id="reference-reveal-generation" model="mini" prompt={direction.reference-reveal-prompt} duration="5" resolution="720p" aspect-ratio="9:16" generate-audio="true">
<seedance:Reference image={assets.presenter-reference} person-reference="true"/>
<seedance:Reference audio={assets.voice-reference}/>
</seedance:ReferenceVideo>
<pipeline:Normalize id="reference-reveal-media" source={reference-reveal-generation.video} clock={assets.clock} video="primary-moving" audio="default" span-authority="video"/>
- <whisperx:SemanticTake id="reference-reveal" narrative={copy.story} segment={copy.story.segment.reference-reveal} media={reference-reveal-media.media} language="zh"/>
+ <whisperx:Alignment id="reference-reveal" narrative={copy.story}
+ segment={copy.story.segment.reference-reveal} media={reference-reveal-media.media} domain={reference-reveal-media.domain} language="zh"/>
<seedance:ReferenceVideo id="closing-generation" model="mini" prompt={direction.closing-prompt} duration="11" resolution="720p" aspect-ratio="9:16" generate-audio="true">
<seedance:Reference image={assets.presenter-reference} person-reference="true"/>
<seedance:Reference audio={assets.voice-reference}/>
</seedance:ReferenceVideo>
<pipeline:Normalize id="closing-media" source={closing-generation.video} clock={assets.clock} video="primary-moving" audio="default" span-authority="video"/>
- <whisperx:SemanticTake id="closing" narrative={copy.story} segment={copy.story.segment.closing} media={closing-media.media} language="zh"/>
+ <whisperx:Alignment id="closing" narrative={copy.story}
+ segment={copy.story.segment.closing} media={closing-media.media} domain={closing-media.domain} language="zh"/>
<pipeline:Normalize id="code-demo-media" source={assets.code-demo} clock={assets.clock} video="primary-moving" audio="none" span-authority="video"/>
<pipeline:Normalize id="readme-demo-media" source={assets.readme-demo} clock={assets.clock} video="primary-moving" audio="none" span-authority="video"/>
<pipeline:Normalize id="price-creatify-media" source={assets.price-creatify} clock={assets.clock} video="primary-moving" audio="none" span-authority="video"/>
@@ -144,25 +164,169 @@
<pipeline:Normalize id="hypit-interview-media" source={assets.hypit-interview} clock={assets.clock} video="primary-moving" audio="none" span-authority="video"/>
<!-- One Timeline: placed Takes, opening gap and silent ending -->
- <time:Timeline id="program" clock={assets.clock} end="content.end+2s">
- <time:Take source={opening.take}/>
- <time:Take source={introduction.take} at="previous.end+1.5s"/>
- <time:Take source={competitors.take}/>
- <time:Take source={two-roads.take}/>
- <time:Take source={editor-road.take}/>
- <time:Take source={keyframe-cost.take}/>
- <time:Take source={code-road.take}/>
- <time:Take source={reuse-cost.take}/>
- <time:Take source={timing-cost.take}/>
- <time:Take source={water-break.take}/>
- <time:Take source={synthesis.take}/>
- <time:Take source={components.take}/>
- <time:Take source={semantic-time.take}/>
- <time:Take source={semantic-demo.take}/>
- <time:Take source={result.take}/>
- <time:Take source={reference-reveal.take}/>
- <time:Take source={closing.take}/>
+ <time:Timeline id="program" clock={assets.clock} end="closing.end+2s">
+ <time:Window id="opening" from="start" for={opening-media.extent}/>
+ <time:Window id="introduction" from="opening.end+1.5s" for={introduction-media.extent}/>
+ <time:Window id="competitors" from="introduction.end" for={competitors-media.extent}/>
+ <time:Window id="two-roads" from="competitors.end" for={two-roads-media.extent}/>
+ <time:Window id="editor-road" from="two-roads.end" for={editor-road-media.extent}/>
+ <time:Window id="keyframe-cost" from="editor-road.end" for={keyframe-cost-media.extent}/>
+ <time:Window id="code-road" from="keyframe-cost.end" for={code-road-media.extent}/>
+ <time:Window id="reuse-cost" from="code-road.end" for={reuse-cost-media.extent}/>
+ <time:Window id="timing-cost" from="reuse-cost.end" for={timing-cost-media.extent}/>
+ <time:Window id="water-break" from="timing-cost.end" for={water-break-media.extent}/>
+ <time:Window id="synthesis" from="water-break.end" for={synthesis-media.extent}/>
+ <time:Window id="components" from="synthesis.end" for={components-media.extent}/>
+ <time:Window id="semantic-time" from="components.end" for={semantic-time-media.extent}/>
+ <time:Window id="semantic-demo" from="semantic-time.end" for={semantic-demo-media.extent}/>
+ <time:Window id="result" from="semantic-demo.end" for={result-media.extent}/>
+ <time:Window id="reference-reveal" from="result.end" for={reference-reveal-media.extent}/>
+ <time:Window id="closing" from="reference-reveal.end" for={closing-media.extent}/>
</time:Timeline>
+
+
+ <semantic:Projection id="story-time" narrative={copy.story} timeline={program.timeline}>
+ <semantic:Map alignment={opening.alignment} domain={opening-media.domain} window={program.opening}/>
+ <semantic:Map alignment={introduction.alignment} domain={introduction-media.domain} window={program.introduction}/>
+ <semantic:Map alignment={competitors.alignment} domain={competitors-media.domain} window={program.competitors}/>
+ <semantic:Map alignment={two-roads.alignment} domain={two-roads-media.domain} window={program.two-roads}/>
+ <semantic:Map alignment={editor-road.alignment} domain={editor-road-media.domain} window={program.editor-road}/>
+ <semantic:Map alignment={keyframe-cost.alignment} domain={keyframe-cost-media.domain} window={program.keyframe-cost}/>
+ <semantic:Map alignment={code-road.alignment} domain={code-road-media.domain} window={program.code-road}/>
+ <semantic:Map alignment={reuse-cost.alignment} domain={reuse-cost-media.domain} window={program.reuse-cost}/>
+ <semantic:Map alignment={timing-cost.alignment} domain={timing-cost-media.domain} window={program.timing-cost}/>
+ <semantic:Map alignment={water-break.alignment} domain={water-break-media.domain} window={program.water-break}/>
+ <semantic:Map alignment={synthesis.alignment} domain={synthesis-media.domain} window={program.synthesis}/>
+ <semantic:Map alignment={components.alignment} domain={components-media.domain} window={program.components}/>
+ <semantic:Map alignment={semantic-time.alignment} domain={semantic-time-media.domain} window={program.semantic-time}/>
+ <semantic:Map alignment={semantic-demo.alignment} domain={semantic-demo-media.domain} window={program.semantic-demo}/>
+ <semantic:Map alignment={result.alignment} domain={result-media.domain} window={program.result}/>
+ <semantic:Map alignment={reference-reveal.alignment} domain={reference-reveal-media.domain} window={program.reference-reveal}/>
+ <semantic:Map alignment={closing.alignment} domain={closing-media.domain} window={program.closing}/>
+ <semantic:Instant id="moment-begin-cue" moment={copy.story.moment.begin}/>
+ <semantic:Instant id="moment-opening-brand-cue" moment={copy.story.moment.opening-brand}/>
+ <semantic:Instant id="moment-road-overview-cue" moment={copy.story.moment.road-overview}/>
+ <semantic:Instant id="segment-timing-cost-end" segment={copy.story.segment.timing-cost} boundary="end"/>
+ <semantic:Instant id="segment-synthesis-start" segment={copy.story.segment.synthesis} boundary="start"/>
+ <semantic:Instant id="segment-closing-start" segment={copy.story.segment.closing} boundary="start"/>
+ <semantic:Instant id="moment-outro-overtime-cue" moment={copy.story.moment.outro-overtime}/>
+ <semantic:Instant id="segment-opening-end" segment={copy.story.segment.opening} boundary="end"/>
+ <semantic:Instant id="segment-opening-end-plus-1-5s" segment={copy.story.segment.opening} boundary="end" offset="+1.5s"/>
+ <semantic:Instant id="segment-opening-end-plus-0f" segment={copy.story.segment.opening} boundary="end" offset="+0f"/>
+ <semantic:Instant id="segment-opening-end-plus-5f" segment={copy.story.segment.opening} boundary="end" offset="+5f"/>
+ <semantic:Instant id="segment-opening-end-plus-9f" segment={copy.story.segment.opening} boundary="end" offset="+9f"/>
+ <semantic:Instant id="segment-opening-end-plus-14f" segment={copy.story.segment.opening} boundary="end" offset="+14f"/>
+ <semantic:Instant id="segment-opening-end-plus-45f" segment={copy.story.segment.opening} boundary="end" offset="+45f"/>
+ <semantic:Instant id="segment-introduction-start" segment={copy.story.segment.introduction} boundary="start"/>
+ <semantic:Window id="segment-opening" segment={copy.story.segment.opening}/>
+ <semantic:Window id="segment-two-roads" segment={copy.story.segment.two-roads}/>
+ <semantic:Instant id="segment-two-roads-start" segment={copy.story.segment.two-roads} boundary="start"/>
+ <semantic:Instant id="segment-two-roads-start-plus-1s" segment={copy.story.segment.two-roads} boundary="start" offset="+1s"/>
+ <semantic:Instant id="moment-road-half-cue" moment={copy.story.moment.road-half}/>
+ <semantic:Instant id="segment-two-roads-end" segment={copy.story.segment.two-roads} boundary="end"/>
+ <semantic:Window id="segment-water-break" segment={copy.story.segment.water-break}/>
+ <semantic:Instant id="moment-resume-cue" moment={copy.story.moment.resume}/>
+ <semantic:Window id="segment-closing" segment={copy.story.segment.closing}/>
+ <semantic:Instant id="segment-closing-start-plus-1s" segment={copy.story.segment.closing} boundary="start" offset="+1s"/>
+ <semantic:Instant id="moment-outro-github-cue" moment={copy.story.moment.outro-github}/>
+ <semantic:Instant id="moment-outro-bye-cue" moment={copy.story.moment.outro-bye}/>
+ <semantic:Window id="segment-timing-cost" segment={copy.story.segment.timing-cost}/>
+ <semantic:Instant id="moment-result-guess-cue" moment={copy.story.moment.result-guess}/>
+ <semantic:Instant id="segment-reference-reveal-end" segment={copy.story.segment.reference-reveal} boundary="end"/>
+ <semantic:Instant id="segment-closing-end-minus-12f" segment={copy.story.segment.closing} boundary="end" offset="-12f"/>
+ <semantic:Instant id="segment-closing-end" segment={copy.story.segment.closing} boundary="end"/>
+ <semantic:Instant id="moment-intro-codex-cue" moment={copy.story.moment.intro-codex}/>
+ <semantic:Instant id="moment-intro-claude-cue" moment={copy.story.moment.intro-claude}/>
+ <semantic:Instant id="moment-intro-examples-cue" moment={copy.story.moment.intro-examples}/>
+ <semantic:Instant id="moment-intro-face-cue" moment={copy.story.moment.intro-face}/>
+ <semantic:Instant id="moment-competitor-monthly-cue" moment={copy.story.moment.competitor-monthly}/>
+ <semantic:Instant id="moment-competitor-watermark-cue" moment={copy.story.moment.competitor-watermark}/>
+ <semantic:Instant id="moment-roads-cue" moment={copy.story.moment.roads}/>
+ <semantic:Instant id="moment-road-assets-cue" moment={copy.story.moment.road-assets}/>
+ <semantic:Instant id="moment-road-drag-cue" moment={copy.story.moment.road-drag}/>
+ <semantic:Instant id="moment-road-fail-cue" moment={copy.story.moment.road-fail}/>
+ <semantic:Instant id="moment-road-number-cue" moment={copy.story.moment.road-number}/>
+ <semantic:Instant id="moment-road-image-cue" moment={copy.story.moment.road-image}/>
+ <semantic:Instant id="moment-road-keys-cue" moment={copy.story.moment.road-keys}/>
+ <semantic:Instant id="moment-road-tokens-cue" moment={copy.story.moment.road-tokens}/>
+ <semantic:Instant id="moment-code-play-cue" moment={copy.story.moment.code-play}/>
+ <semantic:Instant id="moment-code-duplicate-cue" moment={copy.story.moment.code-duplicate}/>
+ <semantic:Instant id="moment-solution-keep-cue" moment={copy.story.moment.solution-keep}/>
+ <semantic:Instant id="moment-solution-drop-cue" moment={copy.story.moment.solution-drop}/>
+ <semantic:Instant id="moment-part-caption-cue" moment={copy.story.moment.part-caption}/>
+ <semantic:Instant id="moment-part-ranking-cue" moment={copy.story.moment.part-ranking}/>
+ <semantic:Instant id="moment-part-chart-cue" moment={copy.story.moment.part-chart}/>
+ <semantic:Instant id="moment-part-card-cue" moment={copy.story.moment.part-card}/>
+ <semantic:Instant id="moment-parts-library-cue" moment={copy.story.moment.parts-library}/>
+ <semantic:Instant id="moment-parts-reuse-cue" moment={copy.story.moment.parts-reuse}/>
+ <semantic:Instant id="moment-parts-swap-cue" moment={copy.story.moment.parts-swap}/>
+ <semantic:Instant id="moment-rank-reveal-cue" moment={copy.story.moment.rank-reveal}/>
+ <semantic:Instant id="moment-product-reveal-cue" moment={copy.story.moment.product-reveal}/>
+ <semantic:Instant id="moment-sem-voice-cue" moment={copy.story.moment.sem-voice}/>
+ <semantic:Instant id="moment-sem-adapt-cue" moment={copy.story.moment.sem-adapt}/>
+ <semantic:Instant id="moment-result-assets-cue" moment={copy.story.moment.result-assets}/>
+ <semantic:Instant id="moment-result-meta-cue" moment={copy.story.moment.result-meta}/>
+ <semantic:Instant id="moment-outro-install-cue" moment={copy.story.moment.outro-install}/>
+ <semantic:Instant id="moment-outro-gift-cue" moment={copy.story.moment.outro-gift}/>
+ <semantic:Instant id="segment-opening-end-plus-4f" segment={copy.story.segment.opening} boundary="end" offset="+4f"/>
+ <semantic:Instant id="segment-opening-end-plus-13f" segment={copy.story.segment.opening} boundary="end" offset="+13f"/>
+ <semantic:Instant id="segment-opening-end-plus-28f" segment={copy.story.segment.opening} boundary="end" offset="+28f"/>
+ <semantic:Window id="segment-introduction" segment={copy.story.segment.introduction}/>
+ <semantic:Instant id="moment-intro-language-cue" moment={copy.story.moment.intro-language}/>
+ <semantic:Instant id="moment-intro-install-cue" moment={copy.story.moment.intro-install}/>
+ <semantic:Instant id="moment-intro-thirty-cue" moment={copy.story.moment.intro-thirty}/>
+ <semantic:Instant id="moment-intro-product-cue" moment={copy.story.moment.intro-product}/>
+ <semantic:Window id="segment-competitors" segment={copy.story.segment.competitors}/>
+ <semantic:Instant id="moment-competitor-other-cue" moment={copy.story.moment.competitor-other}/>
+ <semantic:Instant id="moment-competitor-templates-cue" moment={copy.story.moment.competitor-templates}/>
+ <semantic:Instant id="moment-competitor-cases-cue" moment={copy.story.moment.competitor-cases}/>
+ <semantic:Instant id="segment-keyframe-cost-end" segment={copy.story.segment.keyframe-cost} boundary="end"/>
+ <semantic:Instant id="moment-road-editor-cue" moment={copy.story.moment.road-editor}/>
+ <semantic:Instant id="moment-road-operate-cue" moment={copy.story.moment.road-operate}/>
+ <semantic:Instant id="moment-road-capcut-cue" moment={copy.story.moment.road-capcut}/>
+ <semantic:Instant id="moment-road-premiere-cue" moment={copy.story.moment.road-premiere}/>
+ <semantic:Instant id="moment-road-resolve-cue" moment={copy.story.moment.road-resolve}/>
+ <semantic:Instant id="moment-road-same-cue" moment={copy.story.moment.road-same}/>
+ <semantic:Instant id="moment-road-place-cue" moment={copy.story.moment.road-place}/>
+ <semantic:Instant id="moment-road-generated-cue" moment={copy.story.moment.road-generated}/>
+ <semantic:Instant id="moment-road-unstable-cue" moment={copy.story.moment.road-unstable}/>
+ <semantic:Instant id="moment-road-styles-cue" moment={copy.story.moment.road-styles}/>
+ <semantic:Instant id="segment-code-road-start" segment={copy.story.segment.code-road} boundary="start"/>
+ <semantic:Instant id="segment-synthesis-end" segment={copy.story.segment.synthesis} boundary="end"/>
+ <semantic:Instant id="moment-code-remotion-cue" moment={copy.story.moment.code-remotion}/>
+ <semantic:Instant id="moment-code-hyperframes-cue" moment={copy.story.moment.code-hyperframes}/>
+ <semantic:Instant id="moment-code-html-cue" moment={copy.story.moment.code-html}/>
+ <semantic:Instant id="moment-code-once-cue" moment={copy.story.moment.code-once}/>
+ <semantic:Instant id="moment-code-variant-cue" moment={copy.story.moment.code-variant}/>
+ <semantic:Instant id="moment-code-copy-cue" moment={copy.story.moment.code-copy}/>
+ <semantic:Instant id="moment-code-tokens-cue" moment={copy.story.moment.code-tokens}/>
+ <semantic:Instant id="moment-code-time-cue" moment={copy.story.moment.code-time}/>
+ <semantic:Instant id="moment-code-different-cue" moment={copy.story.moment.code-different}/>
+ <semantic:Instant id="moment-code-match-cue" moment={copy.story.moment.code-match}/>
+ <semantic:Instant id="moment-code-retime-cue" moment={copy.story.moment.code-retime}/>
+ <semantic:Instant id="segment-water-break-start" segment={copy.story.segment.water-break} boundary="start"/>
+ <semantic:Instant id="moment-solution-cue" moment={copy.story.moment.solution}/>
+ <semantic:Instant id="moment-solution-roads-cue" moment={copy.story.moment.solution-roads}/>
+ <semantic:Window id="segment-components" segment={copy.story.segment.components}/>
+ <semantic:Instant id="moment-parts-all-cue" moment={copy.story.moment.parts-all}/>
+ <semantic:Instant id="moment-parts-word-cue" moment={copy.story.moment.parts-word}/>
+ <semantic:Instant id="moment-parts-picture-cue" moment={copy.story.moment.parts-picture}/>
+ <semantic:Instant id="moment-parts-color-cue" moment={copy.story.moment.parts-color}/>
+ <semantic:Instant id="segment-semantic-time-start" segment={copy.story.segment.semantic-time} boundary="start"/>
+ <semantic:Instant id="segment-semantic-demo-end" segment={copy.story.segment.semantic-demo} boundary="end"/>
+ <semantic:Instant id="moment-sem-bind-cue" moment={copy.story.moment.sem-bind}/>
+ <semantic:Instant id="moment-sem-examples-cue" moment={copy.story.moment.sem-examples}/>
+ <semantic:Instant id="moment-sem-rewrite-scene-cue" moment={copy.story.moment.sem-rewrite-scene}/>
+ <semantic:Instant id="moment-sem-rewrite-cue" moment={copy.story.moment.sem-rewrite}/>
+ <semantic:Instant id="moment-sem-syntax-cue" moment={copy.story.moment.sem-syntax}/>
+ <semantic:Instant id="segment-result-start" segment={copy.story.segment.result} boundary="start"/>
+ <semantic:Instant id="moment-result-upload-cue" moment={copy.story.moment.result-upload}/>
+ <semantic:Instant id="moment-result-compare-cue" moment={copy.story.moment.result-compare}/>
+ <semantic:Instant id="moment-result-brand-cue" moment={copy.story.moment.result-brand}/>
+ <semantic:Instant id="moment-outro-copy-cue" moment={copy.story.moment.outro-copy}/>
+ </semantic:Projection>
+ <narrative-caption:Timing id="caption-timing" document={copy.story.caption}
+ binding={copy.story.caption-binding} projection={story-time.projection}/>
<pipeline:Normalize id="ranking-clone-media" source={assets.ranking-clone} clock={assets.clock} video="primary-moving" audio="none" span-authority="video"/>
<pipeline:Normalize id="swap-virtual-media" source={assets.swap-virtual} clock={assets.clock} video="primary-moving" audio="none" span-authority="video"/>
<pipeline:Normalize id="swap-language-media" source={assets.swap-language} clock={assets.clock} video="primary-moving" audio="none" span-authority="video"/>
@@ -171,57 +335,88 @@
<pipeline:Normalize id="swap-vehicle-media" source={assets.swap-vehicle} clock={assets.clock} video="primary-moving" audio="none" span-authority="video"/>
<!-- Opening chrome and independent montage -->
- <gfx:Title id="opening-title" timeline={program.timeline} canvas={assets.canvas} font={assets.display-font} start="program.start" end="moment.cue" moment={copy.story.moment.begin} bounce-at={copy.story.moment.opening-brand} color="#fa67aa" title-y="0.58" title="Hypit" subtitle="一分钟了解" seconds="60"/>
- <gfx:Flag id="road-flag" x="0.035" width="0.93" height="0.21" y="0.752" timeline={program.timeline} canvas={assets.canvas} logo={assets.flag-logo} start="moment.cue" moment={copy.story.moment.road-overview} end-source={copy.story.segment.timing-cost} end="segment.end"/>
- <gfx:Flag id="closing-road-flag" x="0.035" width="0.93" height="0.21" y="0.752" timeline={program.timeline} canvas={assets.canvas} logo={assets.flag-logo} start-source={copy.story.segment.synthesis} start="segment.start" end-source={copy.story.segment.closing} end="segment.start"/>
- <gfx:Timer flag-amplitude="0.06" logo={assets.flag-logo} id="series-timer" timeline={program.timeline} canvas={assets.canvas} font={assets.display-font} start="moment.cue" end="program.end" moment={copy.story.moment.begin} stop-at={copy.story.moment.outro-overtime} flag-color="#fa67aa" title="Hypit" subtitle="VIDEO FRAMEWORK" seconds="60"/>
- <gfx:Stage id="opening-montage" push-rate="0.025" timeline={program.timeline} canvas={assets.canvas} start="segment.end" end="segment.end+1.5s" segment={copy.story.segment.opening}>
- <gfx:Item id="image-1" image={assets.montage-1} segment={copy.story.segment.opening} start="segment.end+0f" end="segment.end+5f"/>
- <gfx:Item id="image-2" image={assets.montage-2} segment={copy.story.segment.opening} start="segment.end+5f" end="segment.end+9f"/>
- <gfx:Item id="image-3" image={assets.montage-3} segment={copy.story.segment.opening} start="segment.end+9f" end="segment.end+14f"/>
- <gfx:Item id="image-4" image={assets.montage-4} segment={copy.story.segment.opening} start="segment.end+14f" end="segment.end+45f"/>
+ <gfx:Title id="opening-title" timeline={program.timeline} within={assets.canvas.bounds} font={assets.display-font} from="start" until={story-time.moment-begin-cue} bounce-at={story-time.moment-opening-brand-cue} color="#fa67aa" title-y="0.58" title="Hypit" subtitle="一分钟了解" seconds="60"/>
+ <gfx:Flag id="road-flag" x="0.035" width="0.93" height="0.21" y="0.752" timeline={program.timeline} within={assets.canvas.bounds} logo={assets.flag-logo} from={story-time.moment-road-overview-cue} until={story-time.segment-timing-cost-end}/>
+ <gfx:Flag id="closing-road-flag" x="0.035" width="0.93" height="0.21" y="0.752" timeline={program.timeline} within={assets.canvas.bounds} logo={assets.flag-logo} from={story-time.segment-synthesis-start} until={story-time.segment-closing-start}/>
+ <gfx:Timer flag-amplitude="0.06" logo={assets.flag-logo} id="series-timer" timeline={program.timeline} within={assets.canvas.bounds} font={assets.display-font} from={story-time.moment-begin-cue} until="end" stop-at={story-time.moment-outro-overtime-cue} flag-color="#fa67aa" title="Hypit" subtitle="VIDEO FRAMEWORK" seconds="60"/>
+ <gfx:Stage id="opening-montage" push-rate="0.025" timeline={program.timeline} within={assets.canvas.bounds} from={story-time.segment-opening-end} until={story-time.segment-opening-end-plus-1-5s}>
+ <gfx:Item id="image-1" image={assets.montage-1} from={story-time.segment-opening-end-plus-0f} until={story-time.segment-opening-end-plus-5f}/>
+ <gfx:Item id="image-2" image={assets.montage-2} from={story-time.segment-opening-end-plus-5f} until={story-time.segment-opening-end-plus-9f}/>
+ <gfx:Item id="image-3" image={assets.montage-3} from={story-time.segment-opening-end-plus-9f} until={story-time.segment-opening-end-plus-14f}/>
+ <gfx:Item id="image-4" image={assets.montage-4} from={story-time.segment-opening-end-plus-14f} until={story-time.segment-opening-end-plus-45f}/>
</gfx:Stage>
- <!-- Presenter presentation: Uses select framing without changing playback -->
- <spatial:Frame id="full-frame" within={assets.canvas} left="0%" top="0%" right="100%" bottom="100%"/>
- <spatial:AnchoredFrame id="host-inset" within={assets.canvas} x="93%" y="13.5%" width="330px" height="330px" anchor="top-right"/>
- <performance:Style id="host-hidden" frame={full-frame} appearance={look.media.hidden}/>
- <performance:Style id="host-full" frame={full-frame} appearance={look.media.full}/>
+ <!-- Project Presenter: component-local Uses select framing without changing playback -->
+ <spatial:Frame id="full-frame" within={assets.canvas.bounds} left="0%" top="0%" right="100%" bottom="100%"/>
+ <spatial:AnchoredFrame id="host-inset" within={assets.canvas.bounds} x="93%" y="13.5%" width="330px" height="330px" anchor="top-right"/>
+ <gfx:PresenterFrame id="host-hidden" frame={full-frame} appearance={look.media.hidden}/>
+ <gfx:PresenterFrame id="host-full" frame={full-frame} appearance={look.media.full}/>
<gfx:PortraitInset id="host-small" frame={host-inset}/>
<gfx:Pullback id="opening-pullback" scale="1.5"/>
<gfx:FadeOut id="host-fade"/>
- <spatial:Frame id="upper-frame" within={assets.canvas} left="0%" top="0%" right="100%" bottom="48%"/>
- <performance:Style id="host-upper" frame={upper-frame} appearance={look.media.upper}/>
+ <spatial:Frame id="upper-frame" within={assets.canvas.bounds} left="0%" top="0%" right="100%" bottom="48%"/>
+ <gfx:PresenterFrame id="host-upper" frame={upper-frame} appearance={look.media.upper}/>
<gfx:Reframe id="host-rise" from={full-frame} to={upper-frame}/>
<gfx:PortraitTransition id="host-resume" from={full-frame} to={host-inset}/>
- <performance:Track id="presenter" timeline={program.timeline} canvas={assets.canvas}>
- <performance:Use style={host-small} segment={copy.story.segment.introduction} start="segment.start" end="program.end"/>
- <performance:Use during={copy.story.segment.opening} style={host-full}/>
- <performance:Use start="0f" end="1s" style={opening-pullback}/>
- <performance:Use during={copy.story.segment.two-roads} style={host-full}/>
- <performance:Use segment={copy.story.segment.two-roads} start="segment.start" end="segment.start+1s" style={opening-pullback}/>
- <performance:Use start-source={copy.story.moment.road-half} start="moment.cue" end-source={copy.story.moment.road-overview} end="moment.cue" style={host-upper}/>
- <performance:Use at={copy.story.moment.road-half} for="14f" style={host-rise}/>
- <performance:Use segment={copy.story.segment.two-roads} moment={copy.story.moment.road-overview} start="moment.cue" end="segment.end" style={host-small}/>
- <performance:Use during={copy.story.segment.water-break} style={host-full}/>
- <performance:Use moment={copy.story.moment.resume} start="moment.cue" end="program.end" style={host-small}/>
- <performance:Use at={copy.story.moment.resume} for="18f" style={host-resume}/>
- <performance:Use during={copy.story.segment.closing} style={host-full}/>
- <performance:Use segment={copy.story.segment.closing} start="segment.start" end="segment.start+1s" style={opening-pullback}/>
- <performance:Use start-source={copy.story.moment.outro-github} start="moment.cue" end-source={copy.story.moment.outro-bye} end="moment.cue" style={host-small}/>
- <performance:Use during={copy.story.segment.timing-cost} style={host-hidden}/>
- <performance:Use start-source={copy.story.moment.result-guess} start="moment.cue" end-source={copy.story.segment.reference-reveal} end="segment.end" style={host-hidden}/>
- <performance:Use segment={copy.story.segment.closing} start="segment.end-12f" end="segment.end" style={host-fade}/>
- <performance:Use segment={copy.story.segment.closing} start="segment.end" end="program.end" style={host-hidden}/>
- </performance:Track>
- <sound:Style id="normal-voice"/>
-
+ <gfx:Presenter id="presenter" timeline={program.timeline} within={assets.canvas.bounds}>
+ <gfx:Source id="opening-source" media={opening-media.media} window={program.opening}/>
+ <gfx:Source id="introduction-source" media={introduction-media.media} window={program.introduction}/>
+ <gfx:Source id="competitors-source" media={competitors-media.media} window={program.competitors}/>
+ <gfx:Source id="two-roads-source" media={two-roads-media.media} window={program.two-roads}/>
+ <gfx:Source id="editor-road-source" media={editor-road-media.media} window={program.editor-road}/>
+ <gfx:Source id="keyframe-cost-source" media={keyframe-cost-media.media} window={program.keyframe-cost}/>
+ <gfx:Source id="code-road-source" media={code-road-media.media} window={program.code-road}/>
+ <gfx:Source id="reuse-cost-source" media={reuse-cost-media.media} window={program.reuse-cost}/>
+ <gfx:Source id="timing-cost-source" media={timing-cost-media.media} window={program.timing-cost}/>
+ <gfx:Source id="water-break-source" media={water-break-media.media} window={program.water-break}/>
+ <gfx:Source id="synthesis-source" media={synthesis-media.media} window={program.synthesis}/>
+ <gfx:Source id="components-source" media={components-media.media} window={program.components}/>
+ <gfx:Source id="semantic-time-source" media={semantic-time-media.media} window={program.semantic-time}/>
+ <gfx:Source id="semantic-demo-source" media={semantic-demo-media.media} window={program.semantic-demo}/>
+ <gfx:Source id="result-source" media={result-media.media} window={program.result}/>
+ <gfx:Source id="reference-reveal-source" media={reference-reveal-media.media} window={program.reference-reveal}/>
+ <gfx:Source id="closing-source" media={closing-media.media} window={program.closing}/>
+ <gfx:Use style={host-small} from={story-time.segment-introduction-start} until="end"/>
+ <gfx:Use during={story-time.segment-opening} style={host-full}/>
+ <gfx:Use from="0f" until="1s" style={opening-pullback}/>
+ <gfx:Use during={story-time.segment-two-roads} style={host-full}/>
+ <gfx:Use from={story-time.segment-two-roads-start} until={story-time.segment-two-roads-start-plus-1s} style={opening-pullback}/>
+ <gfx:Use from={story-time.moment-road-half-cue} until={story-time.moment-road-overview-cue} style={host-upper}/>
+ <gfx:Use from={story-time.moment-road-half-cue} for="14f" style={host-rise}/>
+ <gfx:Use from={story-time.moment-road-overview-cue} until={story-time.segment-two-roads-end} style={host-small}/>
+ <gfx:Use during={story-time.segment-water-break} style={host-full}/>
+ <gfx:Use from={story-time.moment-resume-cue} until="end" style={host-small}/>
+ <gfx:Use from={story-time.moment-resume-cue} for="18f" style={host-resume}/>
+ <gfx:Use during={story-time.segment-closing} style={host-full}/>
+ <gfx:Use from={story-time.segment-closing-start} until={story-time.segment-closing-start-plus-1s} style={opening-pullback}/>
+ <gfx:Use from={story-time.moment-outro-github-cue} until={story-time.moment-outro-bye-cue} style={host-small}/>
+ <gfx:Use during={story-time.segment-timing-cost} style={host-hidden}/>
+ <gfx:Use from={story-time.moment-result-guess-cue} until={story-time.segment-reference-reveal-end} style={host-hidden}/>
+ <gfx:Use from={story-time.segment-closing-end-minus-12f} until={story-time.segment-closing-end} style={host-fade}/>
+ <gfx:Use from={story-time.segment-closing-end} until="end" style={host-hidden}/>
+ </gfx:Presenter>
<!-- Voice, music and independently authored effects -->
- <sound:Track id="voice" timeline={program.timeline}>
- <sound:Use style={normal-voice}/>
- </sound:Track>
+ <audio:Track id="voice" timeline={program.timeline}>
+ <audio:Clip id="opening-source" source={opening-media.media} during={program.opening}/>
+ <audio:Clip id="introduction-source" source={introduction-media.media} during={program.introduction}/>
+ <audio:Clip id="competitors-source" source={competitors-media.media} during={program.competitors}/>
+ <audio:Clip id="two-roads-source" source={two-roads-media.media} during={program.two-roads}/>
+ <audio:Clip id="editor-road-source" source={editor-road-media.media} during={program.editor-road}/>
+ <audio:Clip id="keyframe-cost-source" source={keyframe-cost-media.media} during={program.keyframe-cost}/>
+ <audio:Clip id="code-road-source" source={code-road-media.media} during={program.code-road}/>
+ <audio:Clip id="reuse-cost-source" source={reuse-cost-media.media} during={program.reuse-cost}/>
+ <audio:Clip id="timing-cost-source" source={timing-cost-media.media} during={program.timing-cost}/>
+ <audio:Clip id="water-break-source" source={water-break-media.media} during={program.water-break}/>
+ <audio:Clip id="synthesis-source" source={synthesis-media.media} during={program.synthesis}/>
+ <audio:Clip id="components-source" source={components-media.media} during={program.components}/>
+ <audio:Clip id="semantic-time-source" source={semantic-time-media.media} during={program.semantic-time}/>
+ <audio:Clip id="semantic-demo-source" source={semantic-demo-media.media} during={program.semantic-demo}/>
+ <audio:Clip id="result-source" source={result-media.media} during={program.result}/>
+ <audio:Clip id="reference-reveal-source" source={reference-reveal-media.media} during={program.reference-reveal}/>
+ <audio:Clip id="closing-source" source={closing-media.media} during={program.closing}/>
+ </audio:Track>
<audio:Track id="music" timeline={program.timeline}>
- <audio:Item id="bgm" source={bgm-media.media} during="program" playback="once" gain="0.09" fade-in="6f" fade-out="2s"/>
+ <audio:Clip id="bgm" source={bgm-media.media} during="timeline" gain="0.09" fade-in="6f" fade-out="2s"/>
</audio:Track>
<pipeline:Normalize id="sfx-tap-media" source={assets.sfx-tap} clock={assets.clock} video="none" audio="default" span-authority="audio"/>
<pipeline:Normalize id="sfx-pop-media" source={assets.sfx-pop} clock={assets.clock} video="none" audio="default" span-authority="audio"/>
@@ -232,179 +427,180 @@
<pipeline:Normalize id="sfx-spark-media" source={assets.sfx-spark} clock={assets.clock} video="none" audio="default" span-authority="audio"/>
<pipeline:Normalize id="sfx-finish-media" source={assets.sfx-finish} clock={assets.clock} video="none" audio="default" span-authority="audio"/>
<audio:Track id="pixel-effects" timeline={program.timeline}>
- <audio:Item id="sfx-intro-codex" source={sfx-pop-media.media} at={copy.story.moment.intro-codex} for="0.24s" playback="once" gain="0.16" fade-out="1f"/>
- <audio:Item id="sfx-intro-claude" source={sfx-pop-media.media} at={copy.story.moment.intro-claude} for="0.24s" playback="once" gain="0.16" fade-out="1f"/>
- <audio:Item id="sfx-intro-examples" source={sfx-swipe-media.media} at={copy.story.moment.intro-examples} for="0.36s" playback="once" gain="0.2" fade-out="1f"/>
- <audio:Item id="sfx-intro-face" source={sfx-spark-media.media} at={copy.story.moment.intro-face} for="0.48s" playback="once" gain="0.13" fade-out="1f"/>
- <audio:Item id="sfx-competitor-monthly" source={sfx-tap-media.media} at={copy.story.moment.competitor-monthly} for="0.12s" playback="once" gain="0.16" fade-out="1f"/>
- <audio:Item id="sfx-competitor-watermark" source={sfx-ticks-media.media} at={copy.story.moment.competitor-watermark} for="0.65s" playback="once" gain="0.13" fade-out="1f"/>
- <audio:Item id="sfx-roads" source={sfx-land-media.media} at={copy.story.moment.roads} for="0.26s" playback="once" gain="0.22" fade-out="1f"/>
- <audio:Item id="sfx-road-assets" source={sfx-pop-media.media} at={copy.story.moment.road-assets} for="0.24s" playback="once" gain="0.15" fade-out="1f"/>
- <audio:Item id="sfx-road-drag" source={sfx-tap-media.media} at={copy.story.moment.road-drag} for="0.12s" playback="once" gain="0.13" fade-out="1f"/>
- <audio:Item id="sfx-road-fail" source={sfx-reject-media.media} at={copy.story.moment.road-fail} for="0.4s" playback="once" gain="0.19" fade-out="1f"/>
- <audio:Item id="sfx-road-number" source={sfx-pop-media.media} at={copy.story.moment.road-number} for="0.24s" playback="once" gain="0.2" fade-out="1f"/>
- <audio:Item id="sfx-road-image" source={sfx-swipe-media.media} at={copy.story.moment.road-image} for="0.36s" playback="once" gain="0.18" fade-out="1f"/>
- <audio:Item id="sfx-road-keys" source={sfx-ticks-media.media} at={copy.story.moment.road-keys} for="0.65s" playback="once" gain="0.13" fade-out="1f"/>
- <audio:Item id="sfx-road-tokens" source={sfx-ticks-media.media} at={copy.story.moment.road-tokens} for="0.65s" playback="once" gain="0.12" fade-out="1f"/>
- <audio:Item id="sfx-code-play" source={sfx-pop-media.media} at={copy.story.moment.code-play} for="0.24s" playback="once" gain="0.16" fade-out="1f"/>
- <audio:Item id="sfx-code-duplicate" source={sfx-ticks-media.media} at={copy.story.moment.code-duplicate} for="0.65s" playback="once" gain="0.12" fade-out="1f"/>
- <audio:Item id="sfx-solution-keep" source={sfx-spark-media.media} at={copy.story.moment.solution-keep} for="0.48s" playback="once" gain="0.19" fade-out="1f"/>
- <audio:Item id="sfx-solution-drop" source={sfx-swipe-media.media} at={copy.story.moment.solution-drop} for="0.36s" playback="once" gain="0.18" fade-out="1f"/>
- <audio:Item id="sfx-part-caption" source={sfx-tap-media.media} at={copy.story.moment.part-caption} for="0.12s" playback="once" gain="0.13" fade-out="1f"/>
- <audio:Item id="sfx-part-ranking" source={sfx-tap-media.media} at={copy.story.moment.part-ranking} for="0.12s" playback="once" gain="0.13" fade-out="1f"/>
- <audio:Item id="sfx-part-chart" source={sfx-tap-media.media} at={copy.story.moment.part-chart} for="0.12s" playback="once" gain="0.13" fade-out="1f"/>
- <audio:Item id="sfx-part-card" source={sfx-tap-media.media} at={copy.story.moment.part-card} for="0.12s" playback="once" gain="0.13" fade-out="1f"/>
- <audio:Item id="sfx-parts-library" source={sfx-land-media.media} at={copy.story.moment.parts-library} for="0.26s" playback="once" gain="0.18" fade-out="1f"/>
- <audio:Item id="sfx-parts-reuse" source={sfx-spark-media.media} at={copy.story.moment.parts-reuse} for="0.48s" playback="once" gain="0.14" fade-out="1f"/>
- <audio:Item id="sfx-parts-swap" source={sfx-swipe-media.media} at={copy.story.moment.parts-swap} for="0.36s" playback="once" gain="0.19" fade-out="1f"/>
- <audio:Item id="sfx-rank-reveal" source={sfx-land-media.media} at={copy.story.moment.rank-reveal} for="0.26s" playback="once" gain="0.2" fade-out="1f"/>
- <audio:Item id="sfx-product-reveal" source={sfx-pop-media.media} at={copy.story.moment.product-reveal} for="0.24s" playback="once" gain="0.2" fade-out="1f"/>
- <audio:Item id="sfx-sem-voice" source={sfx-tap-media.media} at={copy.story.moment.sem-voice} for="0.12s" playback="once" gain="0.13" fade-out="1f"/>
- <audio:Item id="sfx-sem-adapt" source={sfx-spark-media.media} at={copy.story.moment.sem-adapt} for="0.48s" playback="once" gain="0.14" fade-out="1f"/>
- <audio:Item id="sfx-result-assets" source={sfx-finish-media.media} at={copy.story.moment.result-assets} for="0.72s" playback="once" gain="0.16" fade-out="1f"/>
- <audio:Item id="sfx-result-meta" source={sfx-swipe-media.media} at={copy.story.moment.result-meta} for="0.36s" playback="once" gain="0.17" fade-out="1f"/>
- <audio:Item id="sfx-outro-install" source={sfx-tap-media.media} at={copy.story.moment.outro-install} for="0.12s" playback="once" gain="0.15" fade-out="1f"/>
- <audio:Item id="sfx-outro-gift" source={sfx-spark-media.media} at={copy.story.moment.outro-gift} for="0.48s" playback="once" gain="0.18" fade-out="1f"/>
- <audio:Item id="sfx-outro-bye" source={sfx-finish-media.media} at={copy.story.moment.outro-bye} for="0.72s" playback="once" gain="0.18" fade-out="1f"/>
- <audio:Item id="sfx-montage-1" source={sfx-tap-media.media} segment={copy.story.segment.opening} start="segment.end+0f" end="segment.end+4f" playback="once" gain="0.21"/>
- <audio:Item id="sfx-montage-2" source={sfx-tap-media.media} segment={copy.story.segment.opening} start="segment.end+5f" end="segment.end+9f" playback="once" gain="0.21"/>
- <audio:Item id="sfx-montage-3" source={sfx-tap-media.media} segment={copy.story.segment.opening} start="segment.end+9f" end="segment.end+13f" playback="once" gain="0.21"/>
- <audio:Item id="sfx-montage-4" source={sfx-spark-media.media} segment={copy.story.segment.opening} start="segment.end+14f" end="segment.end+28f" playback="once" gain="0.27"/>
+ <audio:Clip id="sfx-intro-codex" source={sfx-pop-media.media} from={story-time.moment-intro-codex-cue} for="0.24s" gain="0.16" fade-out="1f"/>
+ <audio:Clip id="sfx-intro-claude" source={sfx-pop-media.media} from={story-time.moment-intro-claude-cue} for="0.24s" gain="0.16" fade-out="1f"/>
+ <audio:Clip id="sfx-intro-examples" source={sfx-swipe-media.media} from={story-time.moment-intro-examples-cue} for="0.36s" gain="0.2" fade-out="1f"/>
+ <audio:Clip id="sfx-intro-face" source={sfx-spark-media.media} from={story-time.moment-intro-face-cue} for="0.48s" gain="0.13" fade-out="1f"/>
+ <audio:Clip id="sfx-competitor-monthly" source={sfx-tap-media.media} from={story-time.moment-competitor-monthly-cue} for="0.12s" gain="0.16" fade-out="1f"/>
+ <audio:Clip id="sfx-competitor-watermark" source={sfx-ticks-media.media} from={story-time.moment-competitor-watermark-cue} for="0.65s" gain="0.13" fade-out="1f"/>
+ <audio:Clip id="sfx-roads" source={sfx-land-media.media} from={story-time.moment-roads-cue} for="0.26s" gain="0.22" fade-out="1f"/>
+ <audio:Clip id="sfx-road-assets" source={sfx-pop-media.media} from={story-time.moment-road-assets-cue} for="0.24s" gain="0.15" fade-out="1f"/>
+ <audio:Clip id="sfx-road-drag" source={sfx-tap-media.media} from={story-time.moment-road-drag-cue} for="0.12s" gain="0.13" fade-out="1f"/>
+ <audio:Clip id="sfx-road-fail" source={sfx-reject-media.media} from={story-time.moment-road-fail-cue} for="0.4s" gain="0.19" fade-out="1f"/>
+ <audio:Clip id="sfx-road-number" source={sfx-pop-media.media} from={story-time.moment-road-number-cue} for="0.24s" gain="0.2" fade-out="1f"/>
+ <audio:Clip id="sfx-road-image" source={sfx-swipe-media.media} from={story-time.moment-road-image-cue} for="0.36s" gain="0.18" fade-out="1f"/>
+ <audio:Clip id="sfx-road-keys" source={sfx-ticks-media.media} from={story-time.moment-road-keys-cue} for="0.65s" gain="0.13" fade-out="1f"/>
+ <audio:Clip id="sfx-road-tokens" source={sfx-ticks-media.media} from={story-time.moment-road-tokens-cue} for="0.65s" gain="0.12" fade-out="1f"/>
+ <audio:Clip id="sfx-code-play" source={sfx-pop-media.media} from={story-time.moment-code-play-cue} for="0.24s" gain="0.16" fade-out="1f"/>
+ <audio:Clip id="sfx-code-duplicate" source={sfx-ticks-media.media} from={story-time.moment-code-duplicate-cue} for="0.65s" gain="0.12" fade-out="1f"/>
+ <audio:Clip id="sfx-solution-keep" source={sfx-spark-media.media} from={story-time.moment-solution-keep-cue} for="0.48s" gain="0.19" fade-out="1f"/>
+ <audio:Clip id="sfx-solution-drop" source={sfx-swipe-media.media} from={story-time.moment-solution-drop-cue} for="0.36s" gain="0.18" fade-out="1f"/>
+ <audio:Clip id="sfx-part-caption" source={sfx-tap-media.media} from={story-time.moment-part-caption-cue} for="0.12s" gain="0.13" fade-out="1f"/>
+ <audio:Clip id="sfx-part-ranking" source={sfx-tap-media.media} from={story-time.moment-part-ranking-cue} for="0.12s" gain="0.13" fade-out="1f"/>
+ <audio:Clip id="sfx-part-chart" source={sfx-tap-media.media} from={story-time.moment-part-chart-cue} for="0.12s" gain="0.13" fade-out="1f"/>
+ <audio:Clip id="sfx-part-card" source={sfx-tap-media.media} from={story-time.moment-part-card-cue} for="0.12s" gain="0.13" fade-out="1f"/>
+ <audio:Clip id="sfx-parts-library" source={sfx-land-media.media} from={story-time.moment-parts-library-cue} for="0.26s" gain="0.18" fade-out="1f"/>
+ <audio:Clip id="sfx-parts-reuse" source={sfx-spark-media.media} from={story-time.moment-parts-reuse-cue} for="0.48s" gain="0.14" fade-out="1f"/>
+ <audio:Clip id="sfx-parts-swap" source={sfx-swipe-media.media} from={story-time.moment-parts-swap-cue} for="0.36s" gain="0.19" fade-out="1f"/>
+ <audio:Clip id="sfx-rank-reveal" source={sfx-land-media.media} from={story-time.moment-rank-reveal-cue} for="0.26s" gain="0.2" fade-out="1f"/>
+ <audio:Clip id="sfx-product-reveal" source={sfx-pop-media.media} from={story-time.moment-product-reveal-cue} for="0.24s" gain="0.2" fade-out="1f"/>
+ <audio:Clip id="sfx-sem-voice" source={sfx-tap-media.media} from={story-time.moment-sem-voice-cue} for="0.12s" gain="0.13" fade-out="1f"/>
+ <audio:Clip id="sfx-sem-adapt" source={sfx-spark-media.media} from={story-time.moment-sem-adapt-cue} for="0.48s" gain="0.14" fade-out="1f"/>
+ <audio:Clip id="sfx-result-assets" source={sfx-finish-media.media} from={story-time.moment-result-assets-cue} for="0.72s" gain="0.16" fade-out="1f"/>
+ <audio:Clip id="sfx-result-meta" source={sfx-swipe-media.media} from={story-time.moment-result-meta-cue} for="0.36s" gain="0.17" fade-out="1f"/>
+ <audio:Clip id="sfx-outro-install" source={sfx-tap-media.media} from={story-time.moment-outro-install-cue} for="0.12s" gain="0.15" fade-out="1f"/>
+ <audio:Clip id="sfx-outro-gift" source={sfx-spark-media.media} from={story-time.moment-outro-gift-cue} for="0.48s" gain="0.18" fade-out="1f"/>
+ <audio:Clip id="sfx-outro-bye" source={sfx-finish-media.media} from={story-time.moment-outro-bye-cue} for="0.72s" gain="0.18" fade-out="1f"/>
+ <audio:Clip id="sfx-montage-1" source={sfx-tap-media.media} from={story-time.segment-opening-end-plus-0f} until={story-time.segment-opening-end-plus-4f} gain="0.21"/>
+ <audio:Clip id="sfx-montage-2" source={sfx-tap-media.media} from={story-time.segment-opening-end-plus-5f} until={story-time.segment-opening-end-plus-9f} gain="0.21"/>
+ <audio:Clip id="sfx-montage-3" source={sfx-tap-media.media} from={story-time.segment-opening-end-plus-9f} until={story-time.segment-opening-end-plus-13f} gain="0.21"/>
+ <audio:Clip id="sfx-montage-4" source={sfx-spark-media.media} from={story-time.segment-opening-end-plus-14f} until={story-time.segment-opening-end-plus-28f} gain="0.27"/>
</audio:Track>
<!-- Caption: Script text, authored cues and presentation -->
<caption:Hidden id="hidden-captions"/>
<caption-fine:Style id="caption-base" recipe={look.caption.primary} font={assets.display-font}/>
- <linecaption:Track id="captions" timeline={program.timeline} document={copy.story.caption}>
+ <linecaption:Track id="captions" timeline={program.timeline}
+ document={copy.story.caption} timing={caption-timing} within={assets.canvas.bounds}>
<linecaption:Use style={caption-base}/>
- <linecaption:Use during={copy.story.segment.opening} style={hidden-captions}/>
+ <linecaption:Use during={story-time.segment-opening} style={hidden-captions}/>
</linecaption:Track>
- <launch:PosterTitle id="montage-label" timeline={program.timeline} canvas={assets.canvas} font={assets.display-font} segment={copy.story.segment.opening} start="segment.end+14f" end="segment.end+45f" text="Hypit" subtitle="复刻任何爆款视频" y="0.165" size="180" subtitle-size="46" subtitle-gap="35"/>
+ <launch:PosterTitle id="montage-label" timeline={program.timeline} within={assets.canvas.bounds} font={assets.display-font} from={story-time.segment-opening-end-plus-14f} until={story-time.segment-opening-end-plus-45f} text="Hypit" subtitle="复刻任何爆款视频" y="0.165" size="180" subtitle-size="46" subtitle-gap="35"/>
<!-- Coordinated scenes: supplied media plus semantic events -->
- <webscene:Introduction id="intro-scene" timeline={program.timeline} canvas={assets.canvas} font={assets.display-font} during={copy.story.segment.introduction} page={web-hypit-media.media} code={code-demo-media.media} readme={readme-demo-media.media} codex={assets.icon-codex} claude={assets.icon-claude} reference-ranking={reference-ranking-media.media} reference-podcast={reference-podcast-media.media} reference-interview={reference-interview-media.media} hypit-ranking={hypit-ranking-media.media} hypit-podcast={hypit-podcast-media.media} hypit-interview={hypit-interview-media.media}>
- <webscene:Beat name="language" at={copy.story.moment.intro-language}/>
- <webscene:Beat name="install" at={copy.story.moment.intro-install}/>
- <webscene:Beat name="codex" at={copy.story.moment.intro-codex}/>
- <webscene:Beat name="claude" at={copy.story.moment.intro-claude}/>
- <webscene:Beat name="examples" at={copy.story.moment.intro-examples}/>
- <webscene:Beat name="thirty" at={copy.story.moment.intro-thirty}/>
- <webscene:Beat name="face" at={copy.story.moment.intro-face}/>
- <webscene:Beat name="product" at={copy.story.moment.intro-product}/>
+ <webscene:Introduction id="intro-scene" timeline={program.timeline} within={assets.canvas.bounds} font={assets.display-font} during={story-time.segment-introduction} page={web-hypit-media.media} code={code-demo-media.media} readme={readme-demo-media.media} codex={assets.icon-codex} claude={assets.icon-claude} reference-ranking={reference-ranking-media.media} reference-podcast={reference-podcast-media.media} reference-interview={reference-interview-media.media} hypit-ranking={hypit-ranking-media.media} hypit-podcast={hypit-podcast-media.media} hypit-interview={hypit-interview-media.media}>
+ <webscene:Beat name="language" at={story-time.moment-intro-language-cue}/>
+ <webscene:Beat name="install" at={story-time.moment-intro-install-cue}/>
+ <webscene:Beat name="codex" at={story-time.moment-intro-codex-cue}/>
+ <webscene:Beat name="claude" at={story-time.moment-intro-claude-cue}/>
+ <webscene:Beat name="examples" at={story-time.moment-intro-examples-cue}/>
+ <webscene:Beat name="thirty" at={story-time.moment-intro-thirty-cue}/>
+ <webscene:Beat name="face" at={story-time.moment-intro-face-cue}/>
+ <webscene:Beat name="product" at={story-time.moment-intro-product-cue}/>
</webscene:Introduction>
- <webscene:Comparison id="competitor-scene" timeline={program.timeline} canvas={assets.canvas} font={assets.display-font} during={copy.story.segment.competitors} left={web-creatify-media.media} right={web-higgsfield-media.media} price-a={price-creatify-media.media} price-b={price-higgsfield-media.media} templates-a={templates-creatify-media.media} templates-b={templates-higgsfield-media.media} case-a={case-creatify-media.media} case-b={case-higgsfield-media.media} logo-a={assets.logo-creatify} logo-b={assets.logo-higgsfield}>
- <webscene:Beat name="other" at={copy.story.moment.competitor-other}/>
- <webscene:Beat name="monthly" at={copy.story.moment.competitor-monthly}/>
- <webscene:Beat name="templates" at={copy.story.moment.competitor-templates}/>
- <webscene:Beat name="cases" at={copy.story.moment.competitor-cases}/>
- <webscene:Beat name="watermark" at={copy.story.moment.competitor-watermark}/>
+ <webscene:Comparison id="competitor-scene" timeline={program.timeline} within={assets.canvas.bounds} font={assets.display-font} during={story-time.segment-competitors} left={web-creatify-media.media} right={web-higgsfield-media.media} price-a={price-creatify-media.media} price-b={price-higgsfield-media.media} templates-a={templates-creatify-media.media} templates-b={templates-higgsfield-media.media} case-a={case-creatify-media.media} case-b={case-higgsfield-media.media} logo-a={assets.logo-creatify} logo-b={assets.logo-higgsfield}>
+ <webscene:Beat name="other" at={story-time.moment-competitor-other-cue}/>
+ <webscene:Beat name="monthly" at={story-time.moment-competitor-monthly-cue}/>
+ <webscene:Beat name="templates" at={story-time.moment-competitor-templates-cue}/>
+ <webscene:Beat name="cases" at={story-time.moment-competitor-cases-cue}/>
+ <webscene:Beat name="watermark" at={story-time.moment-competitor-watermark-cue}/>
</webscene:Comparison>
- <webscene:Road id="editor-journey" timeline={program.timeline} canvas={assets.canvas} font={assets.display-font} start-source={copy.story.segment.two-roads} start="segment.start" end-source={copy.story.segment.keyframe-cost} end="segment.end" page={web-hypit-media.media} sample={case-higgsfield-media.media} codex={assets.icon-codex} capcut={assets.icon-capcut} premiere={assets.icon-premiere} resolve={assets.icon-resolve} logo={assets.road-logo} portrait={assets.presenter-reference} thumb-a={assets.gallery-ranking} thumb-b={assets.gallery-podcast} thumb-c={assets.gallery-interview} thumb-d={assets.gallery-original-ranking} thumb-e={assets.gallery-original-interview} thumb-f={assets.gallery-homepage} thumb-g={assets.gallery-code}>
- <webscene:Beat name="half" at={copy.story.moment.road-half}/>
- <webscene:Beat name="overview" at={copy.story.moment.road-overview}/>
- <webscene:Beat name="editor" at={copy.story.moment.road-editor}/>
- <webscene:Beat name="operate" at={copy.story.moment.road-operate}/>
- <webscene:Beat name="capcut" at={copy.story.moment.road-capcut}/>
- <webscene:Beat name="premiere" at={copy.story.moment.road-premiere}/>
- <webscene:Beat name="resolve" at={copy.story.moment.road-resolve}/>
- <webscene:Beat name="same" at={copy.story.moment.road-same}/>
- <webscene:Beat name="assets" at={copy.story.moment.road-assets}/>
- <webscene:Beat name="drag" at={copy.story.moment.road-drag}/>
- <webscene:Beat name="place" at={copy.story.moment.road-place}/>
- <webscene:Beat name="fail" at={copy.story.moment.road-fail}/>
- <webscene:Beat name="number" at={copy.story.moment.road-number}/>
- <webscene:Beat name="image" at={copy.story.moment.road-image}/>
- <webscene:Beat name="keys" at={copy.story.moment.road-keys}/>
- <webscene:Beat name="tokens" at={copy.story.moment.road-tokens}/>
- <webscene:Beat name="generated" at={copy.story.moment.road-generated}/>
- <webscene:Beat name="unstable" at={copy.story.moment.road-unstable}/>
- <webscene:Beat name="styles" at={copy.story.moment.road-styles}/>
+ <webscene:Road id="editor-journey" timeline={program.timeline} within={assets.canvas.bounds} font={assets.display-font} from={story-time.segment-two-roads-start} until={story-time.segment-keyframe-cost-end} page={web-hypit-media.media} sample={case-higgsfield-media.media} codex={assets.icon-codex} capcut={assets.icon-capcut} premiere={assets.icon-premiere} resolve={assets.icon-resolve} logo={assets.road-logo} portrait={assets.presenter-reference} thumb-a={assets.gallery-ranking} thumb-b={assets.gallery-podcast} thumb-c={assets.gallery-interview} thumb-d={assets.gallery-original-ranking} thumb-e={assets.gallery-original-interview} thumb-f={assets.gallery-homepage} thumb-g={assets.gallery-code}>
+ <webscene:Beat name="half" at={story-time.moment-road-half-cue}/>
+ <webscene:Beat name="overview" at={story-time.moment-road-overview-cue}/>
+ <webscene:Beat name="editor" at={story-time.moment-road-editor-cue}/>
+ <webscene:Beat name="operate" at={story-time.moment-road-operate-cue}/>
+ <webscene:Beat name="capcut" at={story-time.moment-road-capcut-cue}/>
+ <webscene:Beat name="premiere" at={story-time.moment-road-premiere-cue}/>
+ <webscene:Beat name="resolve" at={story-time.moment-road-resolve-cue}/>
+ <webscene:Beat name="same" at={story-time.moment-road-same-cue}/>
+ <webscene:Beat name="assets" at={story-time.moment-road-assets-cue}/>
+ <webscene:Beat name="drag" at={story-time.moment-road-drag-cue}/>
+ <webscene:Beat name="place" at={story-time.moment-road-place-cue}/>
+ <webscene:Beat name="fail" at={story-time.moment-road-fail-cue}/>
+ <webscene:Beat name="number" at={story-time.moment-road-number-cue}/>
+ <webscene:Beat name="image" at={story-time.moment-road-image-cue}/>
+ <webscene:Beat name="keys" at={story-time.moment-road-keys-cue}/>
+ <webscene:Beat name="tokens" at={story-time.moment-road-tokens-cue}/>
+ <webscene:Beat name="generated" at={story-time.moment-road-generated-cue}/>
+ <webscene:Beat name="unstable" at={story-time.moment-road-unstable-cue}/>
+ <webscene:Beat name="styles" at={story-time.moment-road-styles-cue}/>
</webscene:Road>
- <webscene:CodeJourney id="code-journey" timeline={program.timeline} canvas={assets.canvas} font={assets.display-font} start-source={copy.story.segment.code-road} start="segment.start" end-source={copy.story.segment.synthesis} end="segment.end" codex={assets.icon-codex} remotion={assets.icon-remotion} hyperframes={assets.icon-hyperframes} ranking={reference-ranking-media.media} podcast={reference-podcast-media.media} interview={reference-interview-media.media} target={hypit-ranking-media.media}>
- <webscene:Beat name="remotion" at={copy.story.moment.code-remotion}/>
- <webscene:Beat name="hyperframes" at={copy.story.moment.code-hyperframes}/>
- <webscene:Beat name="html" at={copy.story.moment.code-html}/>
- <webscene:Beat name="play" at={copy.story.moment.code-play}/>
- <webscene:Beat name="once" at={copy.story.moment.code-once}/>
- <webscene:Beat name="variant" at={copy.story.moment.code-variant}/>
- <webscene:Beat name="copy" at={copy.story.moment.code-copy}/>
- <webscene:Beat name="duplicate" at={copy.story.moment.code-duplicate}/>
- <webscene:Beat name="tokens" at={copy.story.moment.code-tokens}/>
- <webscene:Beat name="time" at={copy.story.moment.code-time}/>
- <webscene:Beat name="different" at={copy.story.moment.code-different}/>
- <webscene:Beat name="match" at={copy.story.moment.code-match}/>
- <webscene:Beat name="retime" at={copy.story.moment.code-retime}/>
- <webscene:Beat name="water" at={copy.story.segment.water-break} boundary="start"/>
- <webscene:Beat name="resume" at={copy.story.moment.resume}/>
- <webscene:Beat name="solution" at={copy.story.moment.solution}/>
- <webscene:Beat name="parts" at={copy.story.moment.solution-roads}/>
- <webscene:Beat name="keep" at={copy.story.moment.solution-keep}/>
- <webscene:Beat name="drop" at={copy.story.moment.solution-drop}/>
+ <webscene:CodeJourney id="code-journey" timeline={program.timeline} within={assets.canvas.bounds} font={assets.display-font} from={story-time.segment-code-road-start} until={story-time.segment-synthesis-end} codex={assets.icon-codex} remotion={assets.icon-remotion} hyperframes={assets.icon-hyperframes} ranking={reference-ranking-media.media} podcast={reference-podcast-media.media} interview={reference-interview-media.media} target={hypit-ranking-media.media}>
+ <webscene:Beat name="remotion" at={story-time.moment-code-remotion-cue}/>
+ <webscene:Beat name="hyperframes" at={story-time.moment-code-hyperframes-cue}/>
+ <webscene:Beat name="html" at={story-time.moment-code-html-cue}/>
+ <webscene:Beat name="play" at={story-time.moment-code-play-cue}/>
+ <webscene:Beat name="once" at={story-time.moment-code-once-cue}/>
+ <webscene:Beat name="variant" at={story-time.moment-code-variant-cue}/>
+ <webscene:Beat name="copy" at={story-time.moment-code-copy-cue}/>
+ <webscene:Beat name="duplicate" at={story-time.moment-code-duplicate-cue}/>
+ <webscene:Beat name="tokens" at={story-time.moment-code-tokens-cue}/>
+ <webscene:Beat name="time" at={story-time.moment-code-time-cue}/>
+ <webscene:Beat name="different" at={story-time.moment-code-different-cue}/>
+ <webscene:Beat name="match" at={story-time.moment-code-match-cue}/>
+ <webscene:Beat name="retime" at={story-time.moment-code-retime-cue}/>
+ <webscene:Beat name="water" at={story-time.segment-water-break-start}/>
+ <webscene:Beat name="resume" at={story-time.moment-resume-cue}/>
+ <webscene:Beat name="solution" at={story-time.moment-solution-cue}/>
+ <webscene:Beat name="parts" at={story-time.moment-solution-roads-cue}/>
+ <webscene:Beat name="keep" at={story-time.moment-solution-keep-cue}/>
+ <webscene:Beat name="drop" at={story-time.moment-solution-drop-cue}/>
</webscene:CodeJourney>
- <webscene:ComponentWorkshop id="component-workshop" timeline={program.timeline} canvas={assets.canvas} font={assets.display-font} during={copy.story.segment.components} v0={ranking-clone-media.media} v1={swap-virtual-media.media} v2={swap-language-media.media} v3={swap-topic-media.media} v4={swap-product-media.media} v5={swap-vehicle-media.media}>
- <webscene:Beat name="all" at={copy.story.moment.parts-all}/>
- <webscene:Beat name="caption" at={copy.story.moment.part-caption}/>
- <webscene:Beat name="ranking" at={copy.story.moment.part-ranking}/>
- <webscene:Beat name="chart" at={copy.story.moment.part-chart}/>
- <webscene:Beat name="card" at={copy.story.moment.part-card}/>
- <webscene:Beat name="library" at={copy.story.moment.parts-library}/>
- <webscene:Beat name="reuse" at={copy.story.moment.parts-reuse}/>
- <webscene:Beat name="variants" at={copy.story.moment.parts-word}/>
- <webscene:Beat name="word" at={copy.story.moment.parts-word}/>
- <webscene:Beat name="picture" at={copy.story.moment.parts-picture}/>
- <webscene:Beat name="color" at={copy.story.moment.parts-color}/>
- <webscene:Beat name="swap" at={copy.story.moment.parts-swap}/>
+ <webscene:ComponentWorkshop id="component-workshop" timeline={program.timeline} within={assets.canvas.bounds} font={assets.display-font} during={story-time.segment-components} v0={ranking-clone-media.media} v1={swap-virtual-media.media} v2={swap-language-media.media} v3={swap-topic-media.media} v4={swap-product-media.media} v5={swap-vehicle-media.media}>
+ <webscene:Beat name="all" at={story-time.moment-parts-all-cue}/>
+ <webscene:Beat name="caption" at={story-time.moment-part-caption-cue}/>
+ <webscene:Beat name="ranking" at={story-time.moment-part-ranking-cue}/>
+ <webscene:Beat name="chart" at={story-time.moment-part-chart-cue}/>
+ <webscene:Beat name="card" at={story-time.moment-part-card-cue}/>
+ <webscene:Beat name="library" at={story-time.moment-parts-library-cue}/>
+ <webscene:Beat name="reuse" at={story-time.moment-parts-reuse-cue}/>
+ <webscene:Beat name="variants" at={story-time.moment-parts-word-cue}/>
+ <webscene:Beat name="word" at={story-time.moment-parts-word-cue}/>
+ <webscene:Beat name="picture" at={story-time.moment-parts-picture-cue}/>
+ <webscene:Beat name="color" at={story-time.moment-parts-color-cue}/>
+ <webscene:Beat name="swap" at={story-time.moment-parts-swap-cue}/>
</webscene:ComponentWorkshop>
- <webscene:SemanticWorkshop id="semantic-workshop" timeline={program.timeline} canvas={assets.canvas} font={assets.display-font} creatify={assets.ranking-creatify} higgsfield={assets.ranking-higgsfield} start-source={copy.story.segment.semantic-time} start="segment.start" end-source={copy.story.segment.semantic-demo} end="segment.end">
- <webscene:Beat name="bind" at={copy.story.moment.sem-bind}/>
- <webscene:Beat name="examples" at={copy.story.moment.sem-examples}/>
- <webscene:Beat name="rank" at={copy.story.moment.rank-reveal}/>
- <webscene:Beat name="product" at={copy.story.moment.product-reveal}/>
- <webscene:Beat name="rewrite-scene" at={copy.story.moment.sem-rewrite-scene}/>
- <webscene:Beat name="rewrite" at={copy.story.moment.sem-rewrite}/>
- <webscene:Beat name="voice" at={copy.story.moment.sem-voice}/>
- <webscene:Beat name="adapt" at={copy.story.moment.sem-adapt}/>
- <webscene:Beat name="syntax" at={copy.story.moment.sem-syntax}/>
+ <webscene:SemanticWorkshop id="semantic-workshop" timeline={program.timeline} within={assets.canvas.bounds} font={assets.display-font} creatify={assets.ranking-creatify} higgsfield={assets.ranking-higgsfield} from={story-time.segment-semantic-time-start} until={story-time.segment-semantic-demo-end}>
+ <webscene:Beat name="bind" at={story-time.moment-sem-bind-cue}/>
+ <webscene:Beat name="examples" at={story-time.moment-sem-examples-cue}/>
+ <webscene:Beat name="rank" at={story-time.moment-rank-reveal-cue}/>
+ <webscene:Beat name="product" at={story-time.moment-product-reveal-cue}/>
+ <webscene:Beat name="rewrite-scene" at={story-time.moment-sem-rewrite-scene-cue}/>
+ <webscene:Beat name="rewrite" at={story-time.moment-sem-rewrite-cue}/>
+ <webscene:Beat name="voice" at={story-time.moment-sem-voice-cue}/>
+ <webscene:Beat name="adapt" at={story-time.moment-sem-adapt-cue}/>
+ <webscene:Beat name="syntax" at={story-time.moment-sem-syntax-cue}/>
</webscene:SemanticWorkshop>
- <webscene:DeliveryWorkshop id="delivery-workshop" timeline={program.timeline} canvas={assets.canvas} font={assets.display-font} start-source={copy.story.segment.result} start="segment.start" end-source={copy.story.segment.reference-reveal} end="segment.end" film={hypit-ranking-media.media} clone={ranking-clone-media.media} water={water-break-media.media} reference={assets.reference-drink-illustration} host={assets.ranking-host} thumb1={assets.ranking-icon} thumb2={assets.ranking-creatify} thumb3={assets.ranking-higgsfield}>
- <webscene:Beat name="assets" at={copy.story.moment.result-assets}/>
- <webscene:Beat name="upload" at={copy.story.moment.result-upload}/>
- <webscene:Beat name="compare" at={copy.story.moment.result-compare}/>
- <webscene:Beat name="meta" at={copy.story.moment.result-meta}/>
- <webscene:Beat name="brand" at={copy.story.moment.result-brand}/>
- <webscene:Beat name="guess" at={copy.story.moment.result-guess}/>
+ <webscene:DeliveryWorkshop id="delivery-workshop" timeline={program.timeline} within={assets.canvas.bounds} font={assets.display-font} from={story-time.segment-result-start} until={story-time.segment-reference-reveal-end} film={hypit-ranking-media.media} clone={ranking-clone-media.media} water={water-break-media.media} reference={assets.reference-drink-illustration} host={assets.ranking-host} thumb1={assets.ranking-icon} thumb2={assets.ranking-creatify} thumb3={assets.ranking-higgsfield}>
+ <webscene:Beat name="assets" at={story-time.moment-result-assets-cue}/>
+ <webscene:Beat name="upload" at={story-time.moment-result-upload-cue}/>
+ <webscene:Beat name="compare" at={story-time.moment-result-compare-cue}/>
+ <webscene:Beat name="meta" at={story-time.moment-result-meta-cue}/>
+ <webscene:Beat name="brand" at={story-time.moment-result-brand-cue}/>
+ <webscene:Beat name="guess" at={story-time.moment-result-guess-cue}/>
</webscene:DeliveryWorkshop>
- <webscene:Outro id="outro-scene" timeline={program.timeline} canvas={assets.canvas} font={assets.display-font} segment={copy.story.segment.closing} start="segment.start" end="program.end" page={readme-demo-media.media} codex={assets.icon-codex} portraits-0={assets.portraits-0} portraits-1={assets.portraits-1} portraits-2={assets.portraits-2} portraits-3={assets.portraits-3} portraits-4={assets.portraits-4}>
- <webscene:Beat name="overtime" at={copy.story.moment.outro-overtime}/>
- <webscene:Beat name="github" at={copy.story.moment.outro-github}/>
- <webscene:Beat name="copy" at={copy.story.moment.outro-copy}/>
- <webscene:Beat name="install" at={copy.story.moment.outro-install}/>
- <webscene:Beat name="gift" at={copy.story.moment.outro-gift}/>
- <webscene:Beat name="bye" at={copy.story.moment.outro-bye}/>
- <webscene:Beat name="end" at={copy.story.segment.closing} boundary="end"/>
+ <webscene:Outro id="outro-scene" timeline={program.timeline} within={assets.canvas.bounds} font={assets.display-font} from={story-time.segment-closing-start} until="end" page={readme-demo-media.media} codex={assets.icon-codex} portraits-0={assets.portraits-0} portraits-1={assets.portraits-1} portraits-2={assets.portraits-2} portraits-3={assets.portraits-3} portraits-4={assets.portraits-4}>
+ <webscene:Beat name="overtime" at={story-time.moment-outro-overtime-cue}/>
+ <webscene:Beat name="github" at={story-time.moment-outro-github-cue}/>
+ <webscene:Beat name="copy" at={story-time.moment-outro-copy-cue}/>
+ <webscene:Beat name="install" at={story-time.moment-outro-install-cue}/>
+ <webscene:Beat name="gift" at={story-time.moment-outro-gift-cue}/>
+ <webscene:Beat name="bye" at={story-time.moment-outro-bye-cue}/>
+ <webscene:Beat name="end" at={story-time.segment-closing-end}/>
</webscene:Outro>
<!-- Final assembly: contributions and render targets -->
- <film:Film id="main" canvas={assets.canvas} timeline={program.timeline} appearance={look.film.main}>
+ <film:Film id="main" canvas={assets.canvas.canvas} timeline={program.timeline} appearance={look.film.main}>
<film:Track source={presenter.visual}/>
<film:Track source={voice.audio}/>
<film:Track source={music.audio}/>
<film:Track source={pixel-effects.audio}/>
- <film:Track source={captions.track}/>
- <film:Track source={opening-title.track}/>
- <film:Track source={series-timer.track}/>
- <film:Track source={road-flag.track}/>
- <film:Track source={closing-road-flag.track}/>
- <film:Track source={opening-montage.track}/>
- <film:Track source={montage-label.track}/>
- <film:Track source={intro-scene.track}/>
- <film:Track source={competitor-scene.track}/>
- <film:Track source={editor-journey.track}/>
- <film:Track source={code-journey.track}/>
- <film:Track source={component-workshop.track}/>
- <film:Track source={semantic-workshop.track}/>
- <film:Track source={delivery-workshop.track}/>
- <film:Track source={outro-scene.track}/>
+ <film:Track source={captions.visual}/>
+ <film:Track source={opening-title.visual}/>
+ <film:Track source={series-timer.visual}/>
+ <film:Track source={road-flag.visual}/>
+ <film:Track source={closing-road-flag.visual}/>
+ <film:Track source={opening-montage.visual}/>
+ <film:Track source={montage-label.visual}/>
+ <film:Track source={intro-scene.visual}/>
+ <film:Track source={competitor-scene.visual}/>
+ <film:Track source={editor-journey.visual}/>
+ <film:Track source={code-journey.visual}/>
+ <film:Track source={component-workshop.visual}/>
+ <film:Track source={semantic-workshop.visual}/>
+ <film:Track source={delivery-workshop.visual}/>
+ <film:Track source={outro-scene.visual}/>
</film:Film>
<render:Video id="complete-film" composition={main.composition} timeline={program.timeline}/>
<!-- Consecutive export ranges for limited temporary disk space. -->
diff --git a/examples/complex-explainer/productions/explainer/runs/export-parts.svrun b/examples/complex-explainer/productions/explainer/runs/export-parts.svrun
index 74f590a7..28bd9e7c 100644
--- a/examples/complex-explainer/productions/explainer/runs/export-parts.svrun
+++ b/examples/complex-explainer/productions/explainer/runs/export-parts.svrun
@@ -6,40 +6,6 @@
<target output="export-part-3.video"/>
<target output="export-part-4.video"/>
<target output="export-part-5.video"/>
- <build-record id="opening-kept" build="bld_20260914T043459227Z_E0B178D4A9" output="opening.take"/>
- <satisfy output="opening.take" candidate="opening-kept"/>
- <build-record id="introduction-kept" build="bld_20260914T043459227Z_E0B178D4A9" output="introduction.take"/>
- <satisfy output="introduction.take" candidate="introduction-kept"/>
- <build-record id="competitors-kept" build="bld_20260914T043459227Z_E0B178D4A9" output="competitors.take"/>
- <satisfy output="competitors.take" candidate="competitors-kept"/>
- <build-record id="two-roads-kept" build="bld_20260914T043459227Z_E0B178D4A9" output="two-roads.take"/>
- <satisfy output="two-roads.take" candidate="two-roads-kept"/>
- <build-record id="editor-road-kept" build="bld_20260914T043459227Z_E0B178D4A9" output="editor-road.take"/>
- <satisfy output="editor-road.take" candidate="editor-road-kept"/>
- <build-record id="keyframe-cost-kept" build="bld_20260914T043459227Z_E0B178D4A9" output="keyframe-cost.take"/>
- <satisfy output="keyframe-cost.take" candidate="keyframe-cost-kept"/>
- <build-record id="code-road-kept" build="bld_20260914T043459227Z_E0B178D4A9" output="code-road.take"/>
- <satisfy output="code-road.take" candidate="code-road-kept"/>
- <build-record id="reuse-cost-kept" build="bld_20260914T043459227Z_E0B178D4A9" output="reuse-cost.take"/>
- <satisfy output="reuse-cost.take" candidate="reuse-cost-kept"/>
- <build-record id="timing-cost-kept" build="bld_20260914T043459227Z_E0B178D4A9" output="timing-cost.take"/>
- <satisfy output="timing-cost.take" candidate="timing-cost-kept"/>
- <build-record id="water-break-kept" build="bld_20260914T043459227Z_E0B178D4A9" output="water-break.take"/>
- <satisfy output="water-break.take" candidate="water-break-kept"/>
- <build-record id="synthesis-kept" build="bld_20260914T043459227Z_E0B178D4A9" output="synthesis.take"/>
- <satisfy output="synthesis.take" candidate="synthesis-kept"/>
- <build-record id="components-kept" build="bld_20260914T043459227Z_E0B178D4A9" output="components.take"/>
- <satisfy output="components.take" candidate="components-kept"/>
- <build-record id="semantic-time-kept" build="bld_20260914T043459227Z_E0B178D4A9" output="semantic-time.take"/>
- <satisfy output="semantic-time.take" candidate="semantic-time-kept"/>
- <build-record id="semantic-demo-kept" build="bld_20260914T043459227Z_E0B178D4A9" output="semantic-demo.take"/>
- <satisfy output="semantic-demo.take" candidate="semantic-demo-kept"/>
- <build-record id="result-kept" build="bld_20260914T043459227Z_E0B178D4A9" output="result.take"/>
- <satisfy output="result.take" candidate="result-kept"/>
- <build-record id="reference-reveal-kept" build="bld_20260914T043459227Z_E0B178D4A9" output="reference-reveal.take"/>
- <satisfy output="reference-reveal.take" candidate="reference-reveal-kept"/>
- <build-record id="closing-kept" build="bld_20260914T043459227Z_E0B178D4A9" output="closing.take"/>
- <satisfy output="closing.take" candidate="closing-kept"/>
<build-record id="prepared-0" build="bld_20260914T043459227Z_E0B178D4A9" output="bgm-media.media"/>
<satisfy output="bgm-media.media" candidate="prepared-0"/>
<build-record id="prepared-1" build="bld_20260914T043459227Z_E0B178D4A9" output="case-creatify-media.media"/>
diff --git a/examples/complex-explainer/productions/explainer/runs/prepare-example.svrun b/examples/complex-explainer/productions/explainer/runs/prepare-example.svrun
index 0b2cd66c..1801f9c9 100644
--- a/examples/complex-explainer/productions/explainer/runs/prepare-example.svrun
+++ b/examples/complex-explainer/productions/explainer/runs/prepare-example.svrun
@@ -1,23 +1,40 @@
<?svml using="@hypit/run-markup@1"?>
<svrun version="1">
<author source="../authors/main.svml"/>
- <target output="opening.take"/>
- <target output="introduction.take"/>
- <target output="competitors.take"/>
- <target output="two-roads.take"/>
- <target output="editor-road.take"/>
- <target output="keyframe-cost.take"/>
- <target output="code-road.take"/>
- <target output="reuse-cost.take"/>
- <target output="timing-cost.take"/>
- <target output="water-break.take"/>
- <target output="synthesis.take"/>
- <target output="components.take"/>
- <target output="semantic-time.take"/>
- <target output="semantic-demo.take"/>
- <target output="result.take"/>
- <target output="reference-reveal.take"/>
- <target output="closing.take"/>
+ <target output="opening-media.media"/>
+ <target output="opening.alignment"/>
+ <target output="introduction-media.media"/>
+ <target output="introduction.alignment"/>
+ <target output="competitors-media.media"/>
+ <target output="competitors.alignment"/>
+ <target output="two-roads-media.media"/>
+ <target output="two-roads.alignment"/>
+ <target output="editor-road-media.media"/>
+ <target output="editor-road.alignment"/>
+ <target output="keyframe-cost-media.media"/>
+ <target output="keyframe-cost.alignment"/>
+ <target output="code-road-media.media"/>
+ <target output="code-road.alignment"/>
+ <target output="reuse-cost-media.media"/>
+ <target output="reuse-cost.alignment"/>
+ <target output="timing-cost-media.media"/>
+ <target output="timing-cost.alignment"/>
+ <target output="water-break-media.media"/>
+ <target output="water-break.alignment"/>
+ <target output="synthesis-media.media"/>
+ <target output="synthesis.alignment"/>
+ <target output="components-media.media"/>
+ <target output="components.alignment"/>
+ <target output="semantic-time-media.media"/>
+ <target output="semantic-time.alignment"/>
+ <target output="semantic-demo-media.media"/>
+ <target output="semantic-demo.alignment"/>
+ <target output="result-media.media"/>
+ <target output="result.alignment"/>
+ <target output="reference-reveal-media.media"/>
+ <target output="reference-reveal.alignment"/>
+ <target output="closing-media.media"/>
+ <target output="closing.alignment"/>
<target output="bgm-media.media"/>
<target output="case-creatify-media.media"/>
<target output="case-higgsfield-media.media"/>
@@ -42,7 +59,6 @@
<target output="swap-topic-media.media"/>
<target output="swap-product-media.media"/>
<target output="swap-vehicle-media.media"/>
- <target output="water-break-media.media"/>
<target output="sfx-tap-media.media"/>
<target output="sfx-pop-media.media"/>
<target output="sfx-swipe-media.media"/>
@@ -51,40 +67,6 @@
<target output="sfx-ticks-media.media"/>
<target output="sfx-spark-media.media"/>
<target output="sfx-finish-media.media"/>
- <build-record id="opening-kept" build="bld_20260914T043459227Z_E0B178D4A9" output="opening.take"/>
- <satisfy output="opening.take" candidate="opening-kept"/>
- <build-record id="introduction-kept" build="bld_20260914T043459227Z_E0B178D4A9" output="introduction.take"/>
- <satisfy output="introduction.take" candidate="introduction-kept"/>
- <build-record id="competitors-kept" build="bld_20260914T043459227Z_E0B178D4A9" output="competitors.take"/>
- <satisfy output="competitors.take" candidate="competitors-kept"/>
- <build-record id="two-roads-kept" build="bld_20260914T043459227Z_E0B178D4A9" output="two-roads.take"/>
- <satisfy output="two-roads.take" candidate="two-roads-kept"/>
- <build-record id="editor-road-kept" build="bld_20260914T043459227Z_E0B178D4A9" output="editor-road.take"/>
- <satisfy output="editor-road.take" candidate="editor-road-kept"/>
- <build-record id="keyframe-cost-kept" build="bld_20260914T043459227Z_E0B178D4A9" output="keyframe-cost.take"/>
- <satisfy output="keyframe-cost.take" candidate="keyframe-cost-kept"/>
- <build-record id="code-road-kept" build="bld_20260914T043459227Z_E0B178D4A9" output="code-road.take"/>
- <satisfy output="code-road.take" candidate="code-road-kept"/>
- <build-record id="reuse-cost-kept" build="bld_20260914T043459227Z_E0B178D4A9" output="reuse-cost.take"/>
- <satisfy output="reuse-cost.take" candidate="reuse-cost-kept"/>
- <build-record id="timing-cost-kept" build="bld_20260914T043459227Z_E0B178D4A9" output="timing-cost.take"/>
- <satisfy output="timing-cost.take" candidate="timing-cost-kept"/>
- <build-record id="water-break-kept" build="bld_20260914T043459227Z_E0B178D4A9" output="water-break.take"/>
- <satisfy output="water-break.take" candidate="water-break-kept"/>
- <build-record id="synthesis-kept" build="bld_20260914T043459227Z_E0B178D4A9" output="synthesis.take"/>
- <satisfy output="synthesis.take" candidate="synthesis-kept"/>
- <build-record id="components-kept" build="bld_20260914T043459227Z_E0B178D4A9" output="components.take"/>
- <satisfy output="components.take" candidate="components-kept"/>
- <build-record id="semantic-time-kept" build="bld_20260914T043459227Z_E0B178D4A9" output="semantic-time.take"/>
- <satisfy output="semantic-time.take" candidate="semantic-time-kept"/>
- <build-record id="semantic-demo-kept" build="bld_20260914T043459227Z_E0B178D4A9" output="semantic-demo.take"/>
- <satisfy output="semantic-demo.take" candidate="semantic-demo-kept"/>
- <build-record id="result-kept" build="bld_20260914T043459227Z_E0B178D4A9" output="result.take"/>
- <satisfy output="result.take" candidate="result-kept"/>
- <build-record id="reference-reveal-kept" build="bld_20260914T043459227Z_E0B178D4A9" output="reference-reveal.take"/>
- <satisfy output="reference-reveal.take" candidate="reference-reveal-kept"/>
- <build-record id="closing-kept" build="bld_20260914T043459227Z_E0B178D4A9" output="closing.take"/>
- <satisfy output="closing.take" candidate="closing-kept"/>
<build-record id="prepared-0" build="bld_20260914T043459227Z_E0B178D4A9" output="bgm-media.media"/>
<satisfy output="bgm-media.media" candidate="prepared-0"/>
<build-record id="prepared-1" build="bld_20260914T043459227Z_E0B178D4A9" output="case-creatify-media.media"/>
diff --git a/examples/complex-explainer/productions/explainer/runs/render.svrun b/examples/complex-explainer/productions/explainer/runs/render.svrun
index 1c9614d8..f48584cf 100644
--- a/examples/complex-explainer/productions/explainer/runs/render.svrun
+++ b/examples/complex-explainer/productions/explainer/runs/render.svrun
@@ -2,40 +2,6 @@
<svrun version="1">
<author source="../authors/main.svml"/>
<target output="complete-film.video"/>
- <build-record id="opening-kept" build="bld_20260914T043459227Z_E0B178D4A9" output="opening.take"/>
- <satisfy output="opening.take" candidate="opening-kept"/>
- <build-record id="introduction-kept" build="bld_20260914T043459227Z_E0B178D4A9" output="introduction.take"/>
- <satisfy output="introduction.take" candidate="introduction-kept"/>
- <build-record id="competitors-kept" build="bld_20260914T043459227Z_E0B178D4A9" output="competitors.take"/>
- <satisfy output="competitors.take" candidate="competitors-kept"/>
- <build-record id="two-roads-kept" build="bld_20260914T043459227Z_E0B178D4A9" output="two-roads.take"/>
- <satisfy output="two-roads.take" candidate="two-roads-kept"/>
- <build-record id="editor-road-kept" build="bld_20260914T043459227Z_E0B178D4A9" output="editor-road.take"/>
- <satisfy output="editor-road.take" candidate="editor-road-kept"/>
- <build-record id="keyframe-cost-kept" build="bld_20260914T043459227Z_E0B178D4A9" output="keyframe-cost.take"/>
- <satisfy output="keyframe-cost.take" candidate="keyframe-cost-kept"/>
- <build-record id="code-road-kept" build="bld_20260914T043459227Z_E0B178D4A9" output="code-road.take"/>
- <satisfy output="code-road.take" candidate="code-road-kept"/>
- <build-record id="reuse-cost-kept" build="bld_20260914T043459227Z_E0B178D4A9" output="reuse-cost.take"/>
- <satisfy output="reuse-cost.take" candidate="reuse-cost-kept"/>
- <build-record id="timing-cost-kept" build="bld_20260914T043459227Z_E0B178D4A9" output="timing-cost.take"/>
- <satisfy output="timing-cost.take" candidate="timing-cost-kept"/>
- <build-record id="water-break-kept" build="bld_20260914T043459227Z_E0B178D4A9" output="water-break.take"/>
- <satisfy output="water-break.take" candidate="water-break-kept"/>
- <build-record id="synthesis-kept" build="bld_20260914T043459227Z_E0B178D4A9" output="synthesis.take"/>
- <satisfy output="synthesis.take" candidate="synthesis-kept"/>
- <build-record id="components-kept" build="bld_20260914T043459227Z_E0B178D4A9" output="components.take"/>
- <satisfy output="components.take" candidate="components-kept"/>
- <build-record id="semantic-time-kept" build="bld_20260914T043459227Z_E0B178D4A9" output="semantic-time.take"/>
- <satisfy output="semantic-time.take" candidate="semantic-time-kept"/>
- <build-record id="semantic-demo-kept" build="bld_20260914T043459227Z_E0B178D4A9" output="semantic-demo.take"/>
- <satisfy output="semantic-demo.take" candidate="semantic-demo-kept"/>
- <build-record id="result-kept" build="bld_20260914T043459227Z_E0B178D4A9" output="result.take"/>
- <satisfy output="result.take" candidate="result-kept"/>
- <build-record id="reference-reveal-kept" build="bld_20260914T043459227Z_E0B178D4A9" output="reference-reveal.take"/>
- <satisfy output="reference-reveal.take" candidate="reference-reveal-kept"/>
- <build-record id="closing-kept" build="bld_20260914T043459227Z_E0B178D4A9" output="closing.take"/>
- <satisfy output="closing.take" candidate="closing-kept"/>
<build-record id="prepared-0" build="bld_20260914T043459227Z_E0B178D4A9" output="bgm-media.media"/>
<satisfy output="bgm-media.media" candidate="prepared-0"/>
<build-record id="prepared-1" build="bld_20260914T043459227Z_E0B178D4A9" output="case-creatify-media.media"/>
diff --git a/examples/interview/README.md b/examples/interview/README.md
index f5c035b6..7a638e69 100644
--- a/examples/interview/README.md
+++ b/examples/interview/README.md
@@ -63,12 +63,13 @@ Once that real Recipe exists, add its import to the Source's opening prologue:
After `vertical` is declared, add its measured timeline and connect it to the existing Caption Track:
```svml
-<space:RegionTimeline id="wife-heads" within={vertical} recipe={heads.heads.wife}/>
-<caption-fine:Track id="captions" document={story.caption}
- timeline={speech.timeline} regions={wife-heads}>
+<region:Track id="wife-heads" within={vertical.bounds} timeline={speech.timeline}
+ recipe={heads.heads.wife}/>
+<caption-fine:Caption id="captions" document={story.caption} timing={caption-timing}
+ timeline={speech.timeline} within={vertical.bounds} regions={wife-heads}>
<caption-fine:Use style={caption-boy-style}/>
<caption-fine:Use role="WIFE" style={caption-wife-style}/>
-</caption-fine:Track>
+</caption-fine:Caption>
```
Replace the existing `captions` declaration with the connected one. The Recipe contains a WIFE Role
@@ -76,16 +77,20 @@ track; `caption.wife` already uses center/bottom anchoring so its text sits abov
The untracked BOY continues to use his fixed Style position. A null WIFE region hides her Caption
on that frame; it does not guess a new location.
-In the Run, select the first Build's `manifest-rule-semantic.take`, `real-estate-rule-semantic.take`
-and `bitcoin-rule-semantic.take` outputs as Candidates. For example, fill the actual Build id in:
+In the Run, select the first Build's normalized media, local domains and alignment Outputs as
+Candidates. For example, fill the actual Build id in:
```svml
-<build-record id="reuse-manifest" build="ACTUAL_BUILD_ID" output="manifest-rule-semantic.take"/>
-<satisfy output="manifest-rule-semantic.take" candidate="reuse-manifest"/>
+<build-record id="reuse-manifest-media" build="ACTUAL_BUILD_ID" output="manifest-rule-media.media"/>
+<build-record id="reuse-manifest-domain" build="ACTUAL_BUILD_ID" output="manifest-rule-media.domain"/>
+<build-record id="reuse-manifest-alignment" build="ACTUAL_BUILD_ID" output="manifest-rule-semantic.alignment"/>
+<satisfy output="manifest-rule-media.media" candidate="reuse-manifest-media"/>
+<satisfy output="manifest-rule-media.domain" candidate="reuse-manifest-domain"/>
+<satisfy output="manifest-rule-semantic.alignment" candidate="reuse-manifest-alignment"/>
```
-Apply the same explicit selection to the other two SemanticTakes, which already contain their media
-and alignment. Check `hypit plan` to confirm that the second render contains no new image, voice,
+Apply the same explicit selection to the other two passages. Media, duration and alignment remain
+independent reusable facts. Check `hypit plan` to confirm that the second render contains no new image, voice,
video or alignment requests. Inspect camera cuts and moving head placement in the result. Changing
only Caption or MG needs no repeat generation; changing the footage requires matching measurements.
diff --git a/examples/interview/ada-tracking.svs b/examples/interview/ada-tracking.svs
index dd497bcd..f9f58f02 100644
--- a/examples/interview/ada-tracking.svs
+++ b/examples/interview/ada-tracking.svs
@@ -1,7 +1,6 @@
<?svml using="@hypit/svs@1"?>
<sheet version="1">
heads.ada {
- frame-count: 783;
- tracks: [{"id":"ADA","regions":[[0.1014,0.223305,0.261,0.20678],[0.100895,0.223223,0.262044,0.207107],[0.100389,0.223142,0.263088,0.207433],[0.099884,0.22306,0.264132,0.20776],[0.100352,0.223327,0.263629,0.20776],[0.10082,0.223593,0.263127,0.20776],[0.101288,0.22386,0.262624,0.20776],[0.101792,0.224535,0.262083,0.20706],[0.102296,0.22521,0.261541,0.20636],[0.1028,0.225885,0.261,0.20566],[0.104237,0.225478,0.260459,0.205287],[0.105675,0.225072,0.259917,0.204913],[0.107112,0.224665,0.259376,0.20454],[0.108907,0.222378,0.26042,0.205287],[0.110701,0.220092,0.261464,0.206033],[0.112496,0.217805,0.262508,0.20678],[0.115655,0.21503,0.263591,0.20748],[0.118813,0.212255,0.264673,0.20818],[0.121972,0.20948,0.265756,0.20888],[0.125131,0.206427,0.266839,0.209627],[0.128289,0.203373,0.267921,0.210373],[0.131448,0.20032,0.269004,0.21112],[0.132232,0.197265,0.271169,0.21294],[0.133016,0.19421,0.273335,0.21476],[0.1338,0.191155,0.2755,0.21658],[0.132755,0.189493,0.277124,0.218027],[0.131709,0.187832,0.278748,0.219473],[0.130664,0.18617,0.280372,0.22092],[0.129227,0.18581,0.280913,0.221293],[0.127789,0.18545,0.281455,0.221667],[0.126352,0.18509,0.281996,0.22204],[0.125455,0.185623,0.281957,0.22204],[0.124557,0.186157,0.281919,0.22204],[0.12366,0.18669,0.28188,0.22204],[0.124595,0.187235,0.281377,0.221993],[0.125529,0.18778,0.280875,0.221947],[0.126464,0.188325,0.280372,0.2219],[0.128405,0.189267,0.279289,0.2212],[0.130347,0.190208,0.278207,0.2205],[0.132288,0.19115,0.277124,0.2198],[0.134193,0.192092,0.27608,0.2191],[0.136099,0.193033,0.275036,0.2184],[0.138004,0.193975,0.273992,0.2177],[0.139369,0.194335,0.274495,0.217327],[0.140735,0.194695,0.274997,0.216953],[0.1421,0.195055,0.2755,0.21658],[0.144004,0.195322,0.274959,0.21658],[0.145908,0.195588,0.274417,0.21658],[0.147812,0.195855,0.273876,0.21658],[0.149213,0.195948,0.273373,0.216207],[0.150615,0.196042,0.272871,0.215833],[0.152016,0.196135,0.272368,0.21546],null,null,[0.284812,0.095835,0.360876,0.28546],[0.28582,0.097043,0.359793,0.28476],[0.286828,0.098252,0.358711,0.28406],[0.287836,0.09946,0.357628,0.28336],[0.288769,0.100098,0.357628,0.28294],[0.289703,0.100737,0.357628,0.28252],[0.290636,0.101375,0.357628,0.2821],[0.290561,0.099888,0.358711,0.282847],[0.290487,0.098402,0.359793,0.283593],[0.290412,0.096915,0.360876,0.28434],[0.290375,0.095522,0.361417,0.284713],[0.290337,0.094128,0.361959,0.285087],[0.2903,0.092735,0.3625,0.28546],[0.289796,0.092015,0.363041,0.286207],[0.289292,0.091295,0.363583,0.286953],[0.288788,0.090575,0.364124,0.2877],[0.288825,0.090575,0.363583,0.2877],[0.288863,0.090575,0.363041,0.2877],[0.2889,0.090575,0.3625,0.2877],null,null,[0.154088,0.201125,0.262624,0.2079],[0.153584,0.201125,0.263165,0.2079],[0.15308,0.201125,0.263707,0.2079],[0.152576,0.201125,0.264248,0.2079],[0.152576,0.201125,0.264248,0.2079],[0.152576,0.201125,0.264248,0.2079],[0.152576,0.201125,0.264248,0.2079],[0.152072,0.200683,0.264789,0.2086],[0.151568,0.200242,0.265331,0.2093],[0.151064,0.1998,0.265872,0.21],[0.151064,0.1998,0.265872,0.21],[0.151064,0.1998,0.265872,0.21],[0.151064,0.1998,0.265872,0.21],[0.150633,0.1998,0.265833,0.21],[0.150203,0.1998,0.265795,0.21],[0.149772,0.1998,0.265756,0.21],[0.149268,0.199485,0.266297,0.210327],[0.148764,0.19917,0.266839,0.210653],[0.14826,0.198855,0.26738,0.21098],[0.148727,0.198855,0.26738,0.21098],[0.149193,0.198855,0.26738,0.21098],[0.14966,0.198855,0.26738,0.21098],[0.150091,0.198855,0.267419,0.21098],[0.150521,0.198855,0.267457,0.21098],[0.150952,0.198855,0.267496,0.21098],[0.151419,0.198855,0.267496,0.21098],[0.151885,0.198855,0.267496,0.21098],[0.152352,0.198855,0.267496,0.21098],[0.152819,0.198402,0.267496,0.211727],[0.153285,0.197948,0.267496,0.212473],[0.153752,0.197495,0.267496,0.21322],[0.154147,0.197495,0.26854,0.21322],[0.154541,0.197495,0.269584,0.21322],[0.154936,0.197495,0.270628,0.21322],[0.155907,0.197495,0.270087,0.21322],[0.156877,0.197495,0.269545,0.21322],[0.157848,0.197495,0.269004,0.21322],[0.158856,0.197948,0.267921,0.212473],[0.159864,0.198402,0.266839,0.211727],[0.160872,0.198855,0.265756,0.21098],[0.161844,0.199612,0.264712,0.209953],[0.162816,0.200368,0.263668,0.208927],[0.163788,0.201125,0.262624,0.2079],[0.164292,0.201485,0.262083,0.207527],[0.164796,0.201845,0.261541,0.207153],[0.1653,0.202205,0.261,0.20678],[0.164291,0.20167,0.262585,0.207853],[0.163281,0.201135,0.264171,0.208927],[0.162272,0.2006,0.265756,0.21],[0.161693,0.199832,0.26738,0.211073],[0.161115,0.199063,0.269004,0.212147],[0.160536,0.198295,0.270628,0.21322],[0.159995,0.197482,0.271711,0.21434],[0.159453,0.196668,0.272793,0.21546],[0.158912,0.195855,0.273876,0.21658],[0.158875,0.195495,0.274417,0.216953],[0.158837,0.195135,0.274959,0.217327],[0.1588,0.194775,0.2755,0.2177],[0.1588,0.194508,0.2755,0.2177],[0.1588,0.194242,0.2755,0.2177],[0.1588,0.193975,0.2755,0.2177],[0.159808,0.144428,0.274417,0.216953],[0.160816,0.144882,0.273335,0.216207],[0.161824,0.145335,0.272252,0.21546],[0.162833,0.14623,0.270667,0.214013],[0.163843,0.147125,0.269081,0.212567],[0.164852,0.14802,0.267496,0.21112],[0.164852,0.14802,0.267496,0.21112],[0.164852,0.14802,0.267496,0.21112],[0.164852,0.14802,0.267496,0.21112],[0.16388,0.1473,0.26854,0.211867],[0.162908,0.14658,0.269584,0.212613],[0.161936,0.14586,0.270628,0.21336],[0.160928,0.145185,0.271711,0.21406],[0.15992,0.14451,0.272793,0.21476],[0.158912,0.143835,0.273876,0.21546],[0.158949,0.143568,0.273335,0.21546],[0.158987,0.143302,0.272793,0.21546],[0.159024,0.143035,0.272252,0.21546],[0.15852,0.142675,0.272793,0.215833],[0.158016,0.142315,0.273335,0.216207],[0.157512,0.141955,0.273876,0.21658],[0.157475,0.141862,0.274417,0.216953],[0.157437,0.141768,0.274959,0.217327],[0.1574,0.141675,0.2755,0.2177],[0.157867,0.14222,0.2755,0.217653],[0.158333,0.142765,0.2755,0.217607],[0.1588,0.14331,0.2755,0.21756],[0.1588,0.144158,0.2755,0.217233],[0.1588,0.145007,0.2755,0.216907],[0.1588,0.145855,0.2755,0.21658],[0.159304,0.146215,0.274959,0.216207],[0.159808,0.146575,0.274417,0.215833],[0.160312,0.146935,0.273876,0.21546],[0.160853,0.147028,0.272793,0.215087],[0.161395,0.147122,0.271711,0.214713],[0.161936,0.147215,0.270628,0.21434],[0.162404,0.147308,0.270125,0.213967],[0.162872,0.147402,0.269623,0.213593],[0.16334,0.197495,0.26912,0.21322],null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,[0.274,0.087325,0.377,0.2975],[0.274467,0.086965,0.377,0.297873],[0.274933,0.086605,0.377,0.298247],[0.2754,0.086245,0.377,0.29862],[0.275325,0.085663,0.378083,0.298947],[0.275251,0.085082,0.379165,0.299273],[0.275176,0.0845,0.380248,0.2996],[0.274205,0.083862,0.380789,0.30002],[0.273235,0.083223,0.381331,0.30044],[0.272264,0.082585,0.381872,0.30086],[0.271797,0.082503,0.381872,0.301187],[0.271331,0.082422,0.381872,0.301513],[0.270864,0.08234,0.381872,0.30184],[0.270864,0.08234,0.381872,0.30184],[0.270864,0.08234,0.381872,0.30184],[0.270864,0.08234,0.381872,0.30184],[0.271405,0.082515,0.380789,0.30114],[0.271947,0.08269,0.379707,0.30044],[0.272488,0.082865,0.378624,0.29974],[0.273459,0.083052,0.378083,0.298993],[0.274429,0.083238,0.377541,0.298247],[0.2754,0.083425,0.377,0.2975],[0.276296,0.082972,0.377541,0.298247],[0.277192,0.082518,0.378083,0.298993],[0.278088,0.082065,0.378624,0.29974],[0.278016,0.081878,0.379668,0.300487],[0.277944,0.081692,0.380712,0.301233],[0.277872,0.081505,0.381756,0.30198],[0.276901,0.08169,0.382297,0.302307],[0.275931,0.081875,0.382839,0.302633],[0.27496,0.08206,0.38338,0.30296],[0.273987,0.08206,0.38396,0.30296],[0.273013,0.08206,0.38454,0.30296],[0.27204,0.08206,0.38512,0.30296],[0.272115,0.082235,0.384037,0.30226],[0.272189,0.08241,0.382955,0.30156],[0.272264,0.082585,0.381872,0.30086],[0.272264,0.082318,0.381872,0.30086],[0.272264,0.082052,0.381872,0.30086],[0.272264,0.081785,0.381872,0.30086],[0.272227,0.081203,0.382413,0.301187],[0.272189,0.080622,0.382955,0.301513],[0.272152,0.08004,0.383496,0.30184],[0.272115,0.07968,0.384037,0.302213],[0.272077,0.07932,0.384579,0.302587],[0.27204,0.07896,0.38512,0.30296],[0.272544,0.079053,0.384579,0.302587],[0.273048,0.079147,0.384037,0.302213],[0.273552,0.07924,0.383496,0.30184],[0.274597,0.079915,0.381872,0.30114],[0.275643,0.08059,0.380248,0.30044],[0.276688,0.081265,0.378624,0.29974],[0.277155,0.081718,0.378624,0.298993],[0.277621,0.082172,0.378624,0.298247],[0.278088,0.082625,0.378624,0.2975],[0.277584,0.082172,0.379165,0.298247],[0.27708,0.081718,0.379707,0.298993],[0.276576,0.081265,0.380248,0.29974],[0.275533,0.080763,0.381833,0.300813],[0.274491,0.080262,0.383419,0.301887],[0.273448,0.07976,0.385004,0.30296],[0.27244,0.078865,0.386087,0.304407],[0.271432,0.07797,0.387169,0.305853],[0.270424,0.077075,0.388252,0.3073],[0.270387,0.076715,0.388793,0.307673],[0.270349,0.076355,0.389335,0.308047],[0.270312,0.075995,0.389876,0.30842],[0.270816,0.076437,0.389335,0.30772],[0.27132,0.076878,0.388793,0.30702],[0.271824,0.07732,0.388252,0.30632],[0.272365,0.077507,0.387169,0.305573],[0.272907,0.077693,0.386087,0.304827],[0.273448,0.07788,0.385004,0.30408],null,null,[0.134648,0.18533,0.283504,0.22428],[0.134611,0.18533,0.284045,0.22428],[0.134573,0.18533,0.284587,0.22428],[0.134536,0.18533,0.285128,0.22428],[0.134536,0.184888,0.285128,0.22498],[0.134536,0.184447,0.285128,0.22568],[0.134536,0.184005,0.285128,0.22638],[0.134499,0.183912,0.285669,0.226753],[0.134461,0.183818,0.286211,0.227127],[0.134424,0.183725,0.286752,0.2275],[0.134424,0.184085,0.286752,0.227127],[0.134424,0.184445,0.286752,0.226753],[0.134424,0.184805,0.286752,0.22638],[0.134424,0.184805,0.286752,0.22638],[0.134424,0.184805,0.286752,0.22638],[0.134424,0.184805,0.286752,0.22638],[0.134928,0.185258,0.286211,0.225633],[0.135432,0.185712,0.285669,0.224887],[0.135936,0.186165,0.285128,0.22414],[0.135973,0.186165,0.284587,0.22414],[0.136011,0.186165,0.284045,0.22414],[0.136048,0.186165,0.283504,0.22414],[0.136085,0.186607,0.282963,0.22344],[0.136123,0.187048,0.282421,0.22274],[0.13616,0.18749,0.28188,0.22204],[0.135656,0.187408,0.282421,0.222367],[0.135152,0.187327,0.282963,0.222693],[0.134648,0.187245,0.283504,0.22302],null,null,[0.257412,0.097805,0.375376,0.29638],[0.255971,0.097085,0.376459,0.297127],[0.254529,0.096365,0.377541,0.297873],[0.253088,0.095645,0.378624,0.29862],[0.25208,0.09497,0.379707,0.29932],[0.251072,0.094295,0.380789,0.30002],[0.250064,0.09362,0.381872,0.30072],[0.251072,0.094028,0.380789,0.30002],[0.25208,0.094437,0.379707,0.29932],[0.253088,0.094845,0.378624,0.29862],[0.253592,0.095205,0.378083,0.298247],[0.254096,0.095565,0.377541,0.297873],[0.2546,0.095925,0.377,0.2975],[0.2546,0.095658,0.377,0.2975],[0.2546,0.095392,0.377,0.2975],[0.2546,0.095125,0.377,0.2975],[0.254565,0.09481,0.377503,0.297827],[0.254531,0.094495,0.378005,0.298153],[0.254496,0.09418,0.378508,0.29848],[0.254496,0.094308,0.378508,0.2989],[0.254496,0.094437,0.378508,0.29932],[0.254496,0.094565,0.378508,0.29974],[0.254999,0.095818,0.377503,0.298993],[0.255501,0.097072,0.376497,0.298247],[0.256004,0.098325,0.375492,0.2975],[0.256508,0.099545,0.374951,0.296753],[0.257012,0.100765,0.374409,0.296007],[0.257516,0.101985,0.373868,0.29526],[0.257553,0.102345,0.373327,0.294887],[0.257591,0.102705,0.372785,0.294513],[0.257628,0.103065,0.372244,0.29414],[0.256693,0.101718,0.372747,0.29526],[0.255759,0.100372,0.373249,0.29638],[0.254824,0.099025,0.373752,0.2975],[0.253816,0.098258,0.374835,0.2975],[0.252808,0.097492,0.375917,0.2975],[0.2518,0.096725,0.377,0.2975],[0.252341,0.097178,0.375917,0.296753],[0.252883,0.097632,0.374835,0.296007],[0.253424,0.098085,0.373752,0.29526],[0.254396,0.098445,0.372708,0.294887],[0.255368,0.098805,0.371664,0.294513],[0.25634,0.099165,0.37062,0.29414],[0.256807,0.099165,0.37062,0.29414],[0.257273,0.099165,0.37062,0.29414],[0.25774,0.099165,0.37062,0.29414],null,null,[0.143276,0.18725,0.278748,0.2198],[0.143276,0.18761,0.278748,0.219427],[0.143276,0.18797,0.278748,0.219053],[0.143276,0.18833,0.278748,0.21868],[0.143276,0.18833,0.278748,0.21868],[0.143276,0.18833,0.278748,0.21868],[0.143276,0.18833,0.278748,0.21868],[0.143276,0.18833,0.278748,0.21868],[0.143276,0.18833,0.278748,0.21868],[0.143276,0.18833,0.278748,0.21868],[0.142268,0.18725,0.279831,0.2198],[0.14126,0.18617,0.280913,0.22092],[0.140252,0.18509,0.281996,0.22204],[0.139169,0.183602,0.284161,0.22386],[0.138087,0.182113,0.286327,0.22568],[0.137004,0.180625,0.288492,0.2275],[0.136969,0.180172,0.288995,0.228247],[0.136935,0.179718,0.289497,0.228993],[0.1369,0.179265,0.29,0.22974],[0.137871,0.180567,0.289459,0.228667],[0.138841,0.181868,0.288917,0.227593],[0.139812,0.18317,0.288376,0.22652],[0.141791,0.184435,0.286752,0.225727],[0.143769,0.1857,0.285128,0.224933],[0.145748,0.186965,0.283504,0.22414],[0.146719,0.137547,0.282963,0.223813],[0.147689,0.138128,0.282421,0.223487],[0.14866,0.13871,0.28188,0.22316],[0.149053,0.138488,0.28246,0.223113],[0.149447,0.138267,0.28304,0.223067],[0.14984,0.138045,0.28362,0.22302],[0.150307,0.137418,0.28362,0.223393],[0.150773,0.136792,0.28362,0.223767],[0.15124,0.136165,0.28362,0.22414],[0.151744,0.136525,0.283079,0.223767],[0.152248,0.136885,0.282537,0.223393],[0.152752,0.137245,0.281996,0.22302],[0.153797,0.138362,0.280372,0.22162],[0.154843,0.139478,0.278748,0.22022],[0.155888,0.140595,0.277124,0.21882],[0.156467,0.141048,0.2755,0.218073],[0.157045,0.141502,0.273876,0.217327],[0.157624,0.141955,0.272252,0.21658],[0.157157,0.142048,0.272252,0.216207],[0.156691,0.142142,0.272252,0.215833],[0.156224,0.192235,0.272252,0.21546],[0.15572,0.191608,0.272793,0.215833],[0.155216,0.190982,0.273335,0.216207],[0.154712,0.190355,0.273876,0.21658],null,null,[0.270464,0.10283,0.367372,0.28868],[0.270931,0.102377,0.367372,0.289427],[0.271397,0.101923,0.367372,0.290173],[0.271864,0.10147,0.367372,0.29092],[0.271789,0.101377,0.368455,0.291293],[0.271715,0.101283,0.369537,0.291667],[0.27164,0.10119,0.37062,0.29204],[0.271568,0.101003,0.371664,0.292787],[0.271496,0.100817,0.372708,0.293533],[0.271424,0.10063,0.373752,0.29428],[0.272,0.101617,0.372167,0.293533],[0.272576,0.102603,0.370581,0.292787],[0.273152,0.10359,0.368996,0.29204],[0.273227,0.104625,0.367913,0.290967],[0.273301,0.10566,0.366831,0.289893],[0.273376,0.106695,0.365748,0.28882],[0.272947,0.107415,0.365207,0.288073],[0.272517,0.108135,0.364665,0.287327],[0.272088,0.108855,0.364124,0.28658],[0.271192,0.108773,0.363583,0.286907],[0.270296,0.108692,0.363041,0.287233],[0.2694,0.10861,0.3625,0.28756],[0.26742,0.107797,0.364627,0.28868],[0.26544,0.106983,0.366753,0.2898],[0.26346,0.10617,0.36888,0.29092],[0.261948,0.104948,0.370504,0.29274],[0.260436,0.103727,0.372128,0.29456],[0.258924,0.102505,0.373752,0.29638],[0.257916,0.102505,0.374835,0.29638],[0.256908,0.102505,0.375917,0.29638],[0.2559,0.102505,0.377,0.29638],[0.256439,0.10282,0.375956,0.296053],[0.256977,0.103135,0.374912,0.295727],[0.257516,0.10345,0.373868,0.2954],[0.257553,0.10381,0.373327,0.295027],[0.257591,0.10417,0.372785,0.294653],[0.257628,0.10453,0.372244,0.29428],null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,[0.270688,0.101755,0.364124,0.28658],[0.270651,0.101662,0.364665,0.286953],[0.270613,0.101568,0.365207,0.287327],[0.270576,0.101475,0.365748,0.2877],[0.269641,0.101207,0.366251,0.288773],[0.268707,0.100938,0.366753,0.289847],[0.267772,0.10067,0.367256,0.29092],[0.265361,0.10075,0.368377,0.291667],[0.262951,0.10083,0.369499,0.292413],[0.26054,0.10091,0.37062,0.29316],[0.258672,0.100817,0.371123,0.293533],[0.256804,0.100723,0.371625,0.293907],[0.254936,0.10063,0.372128,0.29428],[0.252957,0.100177,0.373752,0.295027],[0.250979,0.099723,0.375376,0.295773],[0.249,0.09927,0.377,0.29652],[0.247992,0.09878,0.378083,0.297547],[0.246984,0.09829,0.379165,0.298573],[0.245976,0.0978,0.380248,0.2996],[0.245976,0.098288,0.380248,0.299647],[0.245976,0.098777,0.380248,0.299693],[0.245976,0.099265,0.380248,0.29974],[0.247021,0.10066,0.378624,0.298293],[0.248067,0.102055,0.377,0.296847],[0.249112,0.10345,0.375376,0.2954],[0.251165,0.104983,0.372669,0.293533],[0.253219,0.106517,0.369963,0.291667],[0.255272,0.10805,0.367256,0.2898],[0.255777,0.108552,0.366212,0.288727],[0.256283,0.109053,0.365168,0.287653],[0.256788,0.109555,0.364124,0.28658],[0.256751,0.10852,0.364665,0.287653],[0.256713,0.107485,0.365207,0.288727],[0.256676,0.10645,0.365748,0.2898],[0.256096,0.10451,0.367875,0.291293],[0.255516,0.10257,0.370001,0.292787],[0.254936,0.10063,0.372128,0.29428],[0.256191,0.098795,0.373752,0.295353],[0.257445,0.09696,0.375376,0.296427],[0.2587,0.095125,0.377,0.2975],[0.262005,0.095172,0.375956,0.29638],[0.265311,0.095218,0.374912,0.29526],[0.268616,0.095265,0.373868,0.29414],[0.271027,0.095452,0.372747,0.293393],[0.273437,0.095638,0.371625,0.292647],[0.275848,0.095825,0.370504,0.2919],[0.277323,0.095825,0.369421,0.2919],[0.278797,0.095825,0.368339,0.2919],[0.280272,0.095825,0.367256,0.2919],[0.279731,0.095732,0.368339,0.292273],[0.279189,0.095638,0.369421,0.292647],[0.278648,0.095545,0.370504,0.29302],[0.277677,0.095673,0.371045,0.29344],[0.276707,0.095802,0.371587,0.29386],[0.275736,0.09593,0.372128,0.29428],[0.273829,0.096382,0.372708,0.294607],[0.271923,0.096833,0.373288,0.294933],[0.270016,0.097285,0.373868,0.29526],[0.268111,0.097458,0.374912,0.295633],[0.266205,0.097632,0.375956,0.296007],[0.2643,0.097805,0.377,0.29638],[0.2629,0.097712,0.377,0.296753],[0.2615,0.097618,0.377,0.297127],[0.2601,0.097525,0.377,0.2975],[0.258663,0.097432,0.377541,0.297873],[0.257225,0.097338,0.378083,0.298247],[0.255788,0.097245,0.378624,0.29862],[0.255825,0.097523,0.378083,0.298573],[0.255863,0.097802,0.377541,0.298527],[0.2559,0.09808,0.377,0.29848],[0.255935,0.099288,0.376497,0.29778],[0.255969,0.100497,0.375995,0.29708],[0.256004,0.101705,0.375492,0.29638],[0.256583,0.10274,0.373868,0.295307],[0.257161,0.103775,0.372244,0.294233],[0.25774,0.10481,0.37062,0.29316],[0.257236,0.10481,0.371161,0.29316],[0.256732,0.10481,0.371703,0.29316],[0.256228,0.10481,0.372244,0.29316],[0.256695,0.104543,0.372244,0.29316],[0.257161,0.104277,0.372244,0.29316],[0.257628,0.10401,0.372244,0.29316],[0.258599,0.103428,0.371703,0.293487],[0.259569,0.102847,0.371161,0.293813],[0.26054,0.102265,0.37062,0.29414],null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,[0.260436,0.090845,0.372128,0.29302],[0.259932,0.091507,0.372669,0.29344],[0.259428,0.092168,0.373211,0.29386],[0.258924,0.09283,0.373752,0.29428],[0.258959,0.093548,0.373249,0.294607],[0.258993,0.094267,0.372747,0.294933],[0.259028,0.094985,0.372244,0.29526],[0.259028,0.095845,0.372244,0.294887],[0.259028,0.096705,0.372244,0.294513],[0.259028,0.097565,0.372244,0.29414],[0.258524,0.097378,0.372785,0.294887],[0.25802,0.097192,0.373327,0.295633],[0.257516,0.097005,0.373868,0.29638],[0.257012,0.097853,0.374409,0.296053],[0.256508,0.098702,0.374951,0.295727],[0.256004,0.09955,0.375492,0.2954],[0.256583,0.100815,0.373868,0.294607],[0.257161,0.10208,0.372244,0.293813],[0.25774,0.103345,0.37062,0.29302],[0.258281,0.10438,0.369537,0.291947],[0.258823,0.105415,0.368455,0.290873],[0.259364,0.10645,0.367372,0.2898],null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,[0.281004,0.092305,0.375492,0.29638],[0.281508,0.093385,0.374951,0.29526],[0.282012,0.094465,0.374409,0.29414],[0.282516,0.095545,0.373868,0.29302],[0.283561,0.09622,0.372244,0.29232],[0.284607,0.096895,0.37062,0.29162],[0.285652,0.09757,0.368996,0.29092],[0.286193,0.098023,0.367913,0.290173],[0.286735,0.098477,0.366831,0.289427],[0.287276,0.09893,0.365748,0.28868],[0.286809,0.098385,0.365748,0.288727],[0.286343,0.09784,0.365748,0.288773],[0.285876,0.097295,0.365748,0.28882],[0.284831,0.09554,0.367372,0.29064],[0.283785,0.093785,0.368996,0.29246],[0.28274,0.09203,0.37062,0.29428],[0.281693,0.090728,0.372747,0.295353],[0.280647,0.089427,0.374873,0.296427],[0.2796,0.088125,0.377,0.2975],[0.279565,0.088125,0.377503,0.2975],[0.279531,0.088125,0.378005,0.2975],[0.279496,0.088125,0.378508,0.2975],[0.280393,0.087938,0.378547,0.298247],[0.281291,0.087752,0.378585,0.298993],[0.282188,0.087565,0.378624,0.29974],[0.283084,0.087565,0.379165,0.29974],[0.28398,0.087565,0.379707,0.29974],[0.284876,0.087565,0.380248,0.29974],[0.286351,0.087392,0.379165,0.299367],[0.287825,0.087218,0.378083,0.298993],[0.2893,0.087045,0.377,0.29862],[0.289729,0.086197,0.377541,0.298947],[0.290159,0.085348,0.378083,0.299273],[0.290588,0.0845,0.378624,0.2996],[0.290983,0.08342,0.379668,0.30072],[0.291377,0.08234,0.380712,0.30184],[0.291772,0.08126,0.381756,0.30296],[0.292557,0.080713,0.383419,0.30408],[0.293343,0.080167,0.385081,0.3052],[0.294128,0.07962,0.386744,0.30632],[0.295456,0.079793,0.387788,0.306693],[0.296784,0.079967,0.388832,0.307067],[0.298112,0.08014,0.389876,0.30744],[0.300016,0.080778,0.389335,0.30702],[0.30192,0.081417,0.388793,0.3066],[0.303824,0.082055,0.388252,0.30618],[0.305225,0.081777,0.387749,0.306227],[0.306627,0.081498,0.387247,0.306273],[0.308028,0.08122,0.386744,0.30632],[0.307993,0.080953,0.387247,0.30632],[0.307959,0.080687,0.387749,0.30632],[0.307924,0.08042,0.388252,0.30632],null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,[0.2907,0.073605,0.377,0.29638],[0.294045,0.074013,0.375376,0.29568],[0.297391,0.074422,0.373752,0.29498],[0.300736,0.07483,0.372128,0.29428],[0.304977,0.075643,0.371045,0.29316],[0.309219,0.076457,0.369963,0.29204],[0.31346,0.07727,0.36888,0.29092],[0.316691,0.077443,0.368919,0.291293],[0.319921,0.077617,0.368957,0.291667],[0.323152,0.07779,0.368996,0.29204],[0.325769,0.077522,0.371161,0.293113],[0.328387,0.077253,0.373327,0.294187],[0.331004,0.076985,0.375492,0.29526],[0.334164,0.076705,0.377039,0.29638],[0.337324,0.076425,0.378585,0.2975],[0.340484,0.076145,0.380132,0.29862],[0.343715,0.07597,0.380171,0.29932],[0.346945,0.075795,0.380209,0.30002],[0.350176,0.07562,0.380248,0.30072],[0.351651,0.076295,0.379165,0.30002],[0.353125,0.07697,0.378083,0.29932],[0.3546,0.077645,0.377,0.29862],[0.352771,0.078098,0.376459,0.297873],[0.350941,0.078552,0.375917,0.297127],[0.349112,0.079005,0.375376,0.29638],[0.344516,0.079272,0.374835,0.29638],[0.33992,0.079538,0.374293,0.29638],[0.335324,0.079805,0.373752,0.29638],[0.327495,0.080747,0.373211,0.29568],[0.319665,0.081688,0.372669,0.29498],[0.311836,0.08263,0.372128,0.29428],[0.303145,0.08407,0.370543,0.292787],[0.294455,0.08551,0.368957,0.291293],[0.285764,0.08695,0.367372,0.2898],[0.278084,0.088705,0.364665,0.28798],[0.270404,0.09046,0.361959,0.28616],[0.262724,0.092215,0.359252,0.28434],[0.257304,0.093797,0.357125,0.282147],[0.251884,0.095378,0.354999,0.279953],[0.246464,0.09696,0.352872,0.27776],null,null]}];
+ series: [{"id":"ADA","regions":[[0.1014,0.223305,0.261,0.20678],[0.100895,0.223223,0.262044,0.207107],[0.100389,0.223142,0.263088,0.207433],[0.099884,0.22306,0.264132,0.20776],[0.100352,0.223327,0.263629,0.20776],[0.10082,0.223593,0.263127,0.20776],[0.101288,0.22386,0.262624,0.20776],[0.101792,0.224535,0.262083,0.20706],[0.102296,0.22521,0.261541,0.20636],[0.1028,0.225885,0.261,0.20566],[0.104237,0.225478,0.260459,0.205287],[0.105675,0.225072,0.259917,0.204913],[0.107112,0.224665,0.259376,0.20454],[0.108907,0.222378,0.26042,0.205287],[0.110701,0.220092,0.261464,0.206033],[0.112496,0.217805,0.262508,0.20678],[0.115655,0.21503,0.263591,0.20748],[0.118813,0.212255,0.264673,0.20818],[0.121972,0.20948,0.265756,0.20888],[0.125131,0.206427,0.266839,0.209627],[0.128289,0.203373,0.267921,0.210373],[0.131448,0.20032,0.269004,0.21112],[0.132232,0.197265,0.271169,0.21294],[0.133016,0.19421,0.273335,0.21476],[0.1338,0.191155,0.2755,0.21658],[0.132755,0.189493,0.277124,0.218027],[0.131709,0.187832,0.278748,0.219473],[0.130664,0.18617,0.280372,0.22092],[0.129227,0.18581,0.280913,0.221293],[0.127789,0.18545,0.281455,0.221667],[0.126352,0.18509,0.281996,0.22204],[0.125455,0.185623,0.281957,0.22204],[0.124557,0.186157,0.281919,0.22204],[0.12366,0.18669,0.28188,0.22204],[0.124595,0.187235,0.281377,0.221993],[0.125529,0.18778,0.280875,0.221947],[0.126464,0.188325,0.280372,0.2219],[0.128405,0.189267,0.279289,0.2212],[0.130347,0.190208,0.278207,0.2205],[0.132288,0.19115,0.277124,0.2198],[0.134193,0.192092,0.27608,0.2191],[0.136099,0.193033,0.275036,0.2184],[0.138004,0.193975,0.273992,0.2177],[0.139369,0.194335,0.274495,0.217327],[0.140735,0.194695,0.274997,0.216953],[0.1421,0.195055,0.2755,0.21658],[0.144004,0.195322,0.274959,0.21658],[0.145908,0.195588,0.274417,0.21658],[0.147812,0.195855,0.273876,0.21658],[0.149213,0.195948,0.273373,0.216207],[0.150615,0.196042,0.272871,0.215833],[0.152016,0.196135,0.272368,0.21546],null,null,[0.284812,0.095835,0.360876,0.28546],[0.28582,0.097043,0.359793,0.28476],[0.286828,0.098252,0.358711,0.28406],[0.287836,0.09946,0.357628,0.28336],[0.288769,0.100098,0.357628,0.28294],[0.289703,0.100737,0.357628,0.28252],[0.290636,0.101375,0.357628,0.2821],[0.290561,0.099888,0.358711,0.282847],[0.290487,0.098402,0.359793,0.283593],[0.290412,0.096915,0.360876,0.28434],[0.290375,0.095522,0.361417,0.284713],[0.290337,0.094128,0.361959,0.285087],[0.2903,0.092735,0.3625,0.28546],[0.289796,0.092015,0.363041,0.286207],[0.289292,0.091295,0.363583,0.286953],[0.288788,0.090575,0.364124,0.2877],[0.288825,0.090575,0.363583,0.2877],[0.288863,0.090575,0.363041,0.2877],[0.2889,0.090575,0.3625,0.2877],null,null,[0.154088,0.201125,0.262624,0.2079],[0.153584,0.201125,0.263165,0.2079],[0.15308,0.201125,0.263707,0.2079],[0.152576,0.201125,0.264248,0.2079],[0.152576,0.201125,0.264248,0.2079],[0.152576,0.201125,0.264248,0.2079],[0.152576,0.201125,0.264248,0.2079],[0.152072,0.200683,0.264789,0.2086],[0.151568,0.200242,0.265331,0.2093],[0.151064,0.1998,0.265872,0.21],[0.151064,0.1998,0.265872,0.21],[0.151064,0.1998,0.265872,0.21],[0.151064,0.1998,0.265872,0.21],[0.150633,0.1998,0.265833,0.21],[0.150203,0.1998,0.265795,0.21],[0.149772,0.1998,0.265756,0.21],[0.149268,0.199485,0.266297,0.210327],[0.148764,0.19917,0.266839,0.210653],[0.14826,0.198855,0.26738,0.21098],[0.148727,0.198855,0.26738,0.21098],[0.149193,0.198855,0.26738,0.21098],[0.14966,0.198855,0.26738,0.21098],[0.150091,0.198855,0.267419,0.21098],[0.150521,0.198855,0.267457,0.21098],[0.150952,0.198855,0.267496,0.21098],[0.151419,0.198855,0.267496,0.21098],[0.151885,0.198855,0.267496,0.21098],[0.152352,0.198855,0.267496,0.21098],[0.152819,0.198402,0.267496,0.211727],[0.153285,0.197948,0.267496,0.212473],[0.153752,0.197495,0.267496,0.21322],[0.154147,0.197495,0.26854,0.21322],[0.154541,0.197495,0.269584,0.21322],[0.154936,0.197495,0.270628,0.21322],[0.155907,0.197495,0.270087,0.21322],[0.156877,0.197495,0.269545,0.21322],[0.157848,0.197495,0.269004,0.21322],[0.158856,0.197948,0.267921,0.212473],[0.159864,0.198402,0.266839,0.211727],[0.160872,0.198855,0.265756,0.21098],[0.161844,0.199612,0.264712,0.209953],[0.162816,0.200368,0.263668,0.208927],[0.163788,0.201125,0.262624,0.2079],[0.164292,0.201485,0.262083,0.207527],[0.164796,0.201845,0.261541,0.207153],[0.1653,0.202205,0.261,0.20678],[0.164291,0.20167,0.262585,0.207853],[0.163281,0.201135,0.264171,0.208927],[0.162272,0.2006,0.265756,0.21],[0.161693,0.199832,0.26738,0.211073],[0.161115,0.199063,0.269004,0.212147],[0.160536,0.198295,0.270628,0.21322],[0.159995,0.197482,0.271711,0.21434],[0.159453,0.196668,0.272793,0.21546],[0.158912,0.195855,0.273876,0.21658],[0.158875,0.195495,0.274417,0.216953],[0.158837,0.195135,0.274959,0.217327],[0.1588,0.194775,0.2755,0.2177],[0.1588,0.194508,0.2755,0.2177],[0.1588,0.194242,0.2755,0.2177],[0.1588,0.193975,0.2755,0.2177],[0.159808,0.144428,0.274417,0.216953],[0.160816,0.144882,0.273335,0.216207],[0.161824,0.145335,0.272252,0.21546],[0.162833,0.14623,0.270667,0.214013],[0.163843,0.147125,0.269081,0.212567],[0.164852,0.14802,0.267496,0.21112],[0.164852,0.14802,0.267496,0.21112],[0.164852,0.14802,0.267496,0.21112],[0.164852,0.14802,0.267496,0.21112],[0.16388,0.1473,0.26854,0.211867],[0.162908,0.14658,0.269584,0.212613],[0.161936,0.14586,0.270628,0.21336],[0.160928,0.145185,0.271711,0.21406],[0.15992,0.14451,0.272793,0.21476],[0.158912,0.143835,0.273876,0.21546],[0.158949,0.143568,0.273335,0.21546],[0.158987,0.143302,0.272793,0.21546],[0.159024,0.143035,0.272252,0.21546],[0.15852,0.142675,0.272793,0.215833],[0.158016,0.142315,0.273335,0.216207],[0.157512,0.141955,0.273876,0.21658],[0.157475,0.141862,0.274417,0.216953],[0.157437,0.141768,0.274959,0.217327],[0.1574,0.141675,0.2755,0.2177],[0.157867,0.14222,0.2755,0.217653],[0.158333,0.142765,0.2755,0.217607],[0.1588,0.14331,0.2755,0.21756],[0.1588,0.144158,0.2755,0.217233],[0.1588,0.145007,0.2755,0.216907],[0.1588,0.145855,0.2755,0.21658],[0.159304,0.146215,0.274959,0.216207],[0.159808,0.146575,0.274417,0.215833],[0.160312,0.146935,0.273876,0.21546],[0.160853,0.147028,0.272793,0.215087],[0.161395,0.147122,0.271711,0.214713],[0.161936,0.147215,0.270628,0.21434],[0.162404,0.147308,0.270125,0.213967],[0.162872,0.147402,0.269623,0.213593],[0.16334,0.197495,0.26912,0.21322],null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,[0.274,0.087325,0.377,0.2975],[0.274467,0.086965,0.377,0.297873],[0.274933,0.086605,0.377,0.298247],[0.2754,0.086245,0.377,0.29862],[0.275325,0.085663,0.378083,0.298947],[0.275251,0.085082,0.379165,0.299273],[0.275176,0.0845,0.380248,0.2996],[0.274205,0.083862,0.380789,0.30002],[0.273235,0.083223,0.381331,0.30044],[0.272264,0.082585,0.381872,0.30086],[0.271797,0.082503,0.381872,0.301187],[0.271331,0.082422,0.381872,0.301513],[0.270864,0.08234,0.381872,0.30184],[0.270864,0.08234,0.381872,0.30184],[0.270864,0.08234,0.381872,0.30184],[0.270864,0.08234,0.381872,0.30184],[0.271405,0.082515,0.380789,0.30114],[0.271947,0.08269,0.379707,0.30044],[0.272488,0.082865,0.378624,0.29974],[0.273459,0.083052,0.378083,0.298993],[0.274429,0.083238,0.377541,0.298247],[0.2754,0.083425,0.377,0.2975],[0.276296,0.082972,0.377541,0.298247],[0.277192,0.082518,0.378083,0.298993],[0.278088,0.082065,0.378624,0.29974],[0.278016,0.081878,0.379668,0.300487],[0.277944,0.081692,0.380712,0.301233],[0.277872,0.081505,0.381756,0.30198],[0.276901,0.08169,0.382297,0.302307],[0.275931,0.081875,0.382839,0.302633],[0.27496,0.08206,0.38338,0.30296],[0.273987,0.08206,0.38396,0.30296],[0.273013,0.08206,0.38454,0.30296],[0.27204,0.08206,0.38512,0.30296],[0.272115,0.082235,0.384037,0.30226],[0.272189,0.08241,0.382955,0.30156],[0.272264,0.082585,0.381872,0.30086],[0.272264,0.082318,0.381872,0.30086],[0.272264,0.082052,0.381872,0.30086],[0.272264,0.081785,0.381872,0.30086],[0.272227,0.081203,0.382413,0.301187],[0.272189,0.080622,0.382955,0.301513],[0.272152,0.08004,0.383496,0.30184],[0.272115,0.07968,0.384037,0.302213],[0.272077,0.07932,0.384579,0.302587],[0.27204,0.07896,0.38512,0.30296],[0.272544,0.079053,0.384579,0.302587],[0.273048,0.079147,0.384037,0.302213],[0.273552,0.07924,0.383496,0.30184],[0.274597,0.079915,0.381872,0.30114],[0.275643,0.08059,0.380248,0.30044],[0.276688,0.081265,0.378624,0.29974],[0.277155,0.081718,0.378624,0.298993],[0.277621,0.082172,0.378624,0.298247],[0.278088,0.082625,0.378624,0.2975],[0.277584,0.082172,0.379165,0.298247],[0.27708,0.081718,0.379707,0.298993],[0.276576,0.081265,0.380248,0.29974],[0.275533,0.080763,0.381833,0.300813],[0.274491,0.080262,0.383419,0.301887],[0.273448,0.07976,0.385004,0.30296],[0.27244,0.078865,0.386087,0.304407],[0.271432,0.07797,0.387169,0.305853],[0.270424,0.077075,0.388252,0.3073],[0.270387,0.076715,0.388793,0.307673],[0.270349,0.076355,0.389335,0.308047],[0.270312,0.075995,0.389876,0.30842],[0.270816,0.076437,0.389335,0.30772],[0.27132,0.076878,0.388793,0.30702],[0.271824,0.07732,0.388252,0.30632],[0.272365,0.077507,0.387169,0.305573],[0.272907,0.077693,0.386087,0.304827],[0.273448,0.07788,0.385004,0.30408],null,null,[0.134648,0.18533,0.283504,0.22428],[0.134611,0.18533,0.284045,0.22428],[0.134573,0.18533,0.284587,0.22428],[0.134536,0.18533,0.285128,0.22428],[0.134536,0.184888,0.285128,0.22498],[0.134536,0.184447,0.285128,0.22568],[0.134536,0.184005,0.285128,0.22638],[0.134499,0.183912,0.285669,0.226753],[0.134461,0.183818,0.286211,0.227127],[0.134424,0.183725,0.286752,0.2275],[0.134424,0.184085,0.286752,0.227127],[0.134424,0.184445,0.286752,0.226753],[0.134424,0.184805,0.286752,0.22638],[0.134424,0.184805,0.286752,0.22638],[0.134424,0.184805,0.286752,0.22638],[0.134424,0.184805,0.286752,0.22638],[0.134928,0.185258,0.286211,0.225633],[0.135432,0.185712,0.285669,0.224887],[0.135936,0.186165,0.285128,0.22414],[0.135973,0.186165,0.284587,0.22414],[0.136011,0.186165,0.284045,0.22414],[0.136048,0.186165,0.283504,0.22414],[0.136085,0.186607,0.282963,0.22344],[0.136123,0.187048,0.282421,0.22274],[0.13616,0.18749,0.28188,0.22204],[0.135656,0.187408,0.282421,0.222367],[0.135152,0.187327,0.282963,0.222693],[0.134648,0.187245,0.283504,0.22302],null,null,[0.257412,0.097805,0.375376,0.29638],[0.255971,0.097085,0.376459,0.297127],[0.254529,0.096365,0.377541,0.297873],[0.253088,0.095645,0.378624,0.29862],[0.25208,0.09497,0.379707,0.29932],[0.251072,0.094295,0.380789,0.30002],[0.250064,0.09362,0.381872,0.30072],[0.251072,0.094028,0.380789,0.30002],[0.25208,0.094437,0.379707,0.29932],[0.253088,0.094845,0.378624,0.29862],[0.253592,0.095205,0.378083,0.298247],[0.254096,0.095565,0.377541,0.297873],[0.2546,0.095925,0.377,0.2975],[0.2546,0.095658,0.377,0.2975],[0.2546,0.095392,0.377,0.2975],[0.2546,0.095125,0.377,0.2975],[0.254565,0.09481,0.377503,0.297827],[0.254531,0.094495,0.378005,0.298153],[0.254496,0.09418,0.378508,0.29848],[0.254496,0.094308,0.378508,0.2989],[0.254496,0.094437,0.378508,0.29932],[0.254496,0.094565,0.378508,0.29974],[0.254999,0.095818,0.377503,0.298993],[0.255501,0.097072,0.376497,0.298247],[0.256004,0.098325,0.375492,0.2975],[0.256508,0.099545,0.374951,0.296753],[0.257012,0.100765,0.374409,0.296007],[0.257516,0.101985,0.373868,0.29526],[0.257553,0.102345,0.373327,0.294887],[0.257591,0.102705,0.372785,0.294513],[0.257628,0.103065,0.372244,0.29414],[0.256693,0.101718,0.372747,0.29526],[0.255759,0.100372,0.373249,0.29638],[0.254824,0.099025,0.373752,0.2975],[0.253816,0.098258,0.374835,0.2975],[0.252808,0.097492,0.375917,0.2975],[0.2518,0.096725,0.377,0.2975],[0.252341,0.097178,0.375917,0.296753],[0.252883,0.097632,0.374835,0.296007],[0.253424,0.098085,0.373752,0.29526],[0.254396,0.098445,0.372708,0.294887],[0.255368,0.098805,0.371664,0.294513],[0.25634,0.099165,0.37062,0.29414],[0.256807,0.099165,0.37062,0.29414],[0.257273,0.099165,0.37062,0.29414],[0.25774,0.099165,0.37062,0.29414],null,null,[0.143276,0.18725,0.278748,0.2198],[0.143276,0.18761,0.278748,0.219427],[0.143276,0.18797,0.278748,0.219053],[0.143276,0.18833,0.278748,0.21868],[0.143276,0.18833,0.278748,0.21868],[0.143276,0.18833,0.278748,0.21868],[0.143276,0.18833,0.278748,0.21868],[0.143276,0.18833,0.278748,0.21868],[0.143276,0.18833,0.278748,0.21868],[0.143276,0.18833,0.278748,0.21868],[0.142268,0.18725,0.279831,0.2198],[0.14126,0.18617,0.280913,0.22092],[0.140252,0.18509,0.281996,0.22204],[0.139169,0.183602,0.284161,0.22386],[0.138087,0.182113,0.286327,0.22568],[0.137004,0.180625,0.288492,0.2275],[0.136969,0.180172,0.288995,0.228247],[0.136935,0.179718,0.289497,0.228993],[0.1369,0.179265,0.29,0.22974],[0.137871,0.180567,0.289459,0.228667],[0.138841,0.181868,0.288917,0.227593],[0.139812,0.18317,0.288376,0.22652],[0.141791,0.184435,0.286752,0.225727],[0.143769,0.1857,0.285128,0.224933],[0.145748,0.186965,0.283504,0.22414],[0.146719,0.137547,0.282963,0.223813],[0.147689,0.138128,0.282421,0.223487],[0.14866,0.13871,0.28188,0.22316],[0.149053,0.138488,0.28246,0.223113],[0.149447,0.138267,0.28304,0.223067],[0.14984,0.138045,0.28362,0.22302],[0.150307,0.137418,0.28362,0.223393],[0.150773,0.136792,0.28362,0.223767],[0.15124,0.136165,0.28362,0.22414],[0.151744,0.136525,0.283079,0.223767],[0.152248,0.136885,0.282537,0.223393],[0.152752,0.137245,0.281996,0.22302],[0.153797,0.138362,0.280372,0.22162],[0.154843,0.139478,0.278748,0.22022],[0.155888,0.140595,0.277124,0.21882],[0.156467,0.141048,0.2755,0.218073],[0.157045,0.141502,0.273876,0.217327],[0.157624,0.141955,0.272252,0.21658],[0.157157,0.142048,0.272252,0.216207],[0.156691,0.142142,0.272252,0.215833],[0.156224,0.192235,0.272252,0.21546],[0.15572,0.191608,0.272793,0.215833],[0.155216,0.190982,0.273335,0.216207],[0.154712,0.190355,0.273876,0.21658],null,null,[0.270464,0.10283,0.367372,0.28868],[0.270931,0.102377,0.367372,0.289427],[0.271397,0.101923,0.367372,0.290173],[0.271864,0.10147,0.367372,0.29092],[0.271789,0.101377,0.368455,0.291293],[0.271715,0.101283,0.369537,0.291667],[0.27164,0.10119,0.37062,0.29204],[0.271568,0.101003,0.371664,0.292787],[0.271496,0.100817,0.372708,0.293533],[0.271424,0.10063,0.373752,0.29428],[0.272,0.101617,0.372167,0.293533],[0.272576,0.102603,0.370581,0.292787],[0.273152,0.10359,0.368996,0.29204],[0.273227,0.104625,0.367913,0.290967],[0.273301,0.10566,0.366831,0.289893],[0.273376,0.106695,0.365748,0.28882],[0.272947,0.107415,0.365207,0.288073],[0.272517,0.108135,0.364665,0.287327],[0.272088,0.108855,0.364124,0.28658],[0.271192,0.108773,0.363583,0.286907],[0.270296,0.108692,0.363041,0.287233],[0.2694,0.10861,0.3625,0.28756],[0.26742,0.107797,0.364627,0.28868],[0.26544,0.106983,0.366753,0.2898],[0.26346,0.10617,0.36888,0.29092],[0.261948,0.104948,0.370504,0.29274],[0.260436,0.103727,0.372128,0.29456],[0.258924,0.102505,0.373752,0.29638],[0.257916,0.102505,0.374835,0.29638],[0.256908,0.102505,0.375917,0.29638],[0.2559,0.102505,0.377,0.29638],[0.256439,0.10282,0.375956,0.296053],[0.256977,0.103135,0.374912,0.295727],[0.257516,0.10345,0.373868,0.2954],[0.257553,0.10381,0.373327,0.295027],[0.257591,0.10417,0.372785,0.294653],[0.257628,0.10453,0.372244,0.29428],null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,[0.270688,0.101755,0.364124,0.28658],[0.270651,0.101662,0.364665,0.286953],[0.270613,0.101568,0.365207,0.287327],[0.270576,0.101475,0.365748,0.2877],[0.269641,0.101207,0.366251,0.288773],[0.268707,0.100938,0.366753,0.289847],[0.267772,0.10067,0.367256,0.29092],[0.265361,0.10075,0.368377,0.291667],[0.262951,0.10083,0.369499,0.292413],[0.26054,0.10091,0.37062,0.29316],[0.258672,0.100817,0.371123,0.293533],[0.256804,0.100723,0.371625,0.293907],[0.254936,0.10063,0.372128,0.29428],[0.252957,0.100177,0.373752,0.295027],[0.250979,0.099723,0.375376,0.295773],[0.249,0.09927,0.377,0.29652],[0.247992,0.09878,0.378083,0.297547],[0.246984,0.09829,0.379165,0.298573],[0.245976,0.0978,0.380248,0.2996],[0.245976,0.098288,0.380248,0.299647],[0.245976,0.098777,0.380248,0.299693],[0.245976,0.099265,0.380248,0.29974],[0.247021,0.10066,0.378624,0.298293],[0.248067,0.102055,0.377,0.296847],[0.249112,0.10345,0.375376,0.2954],[0.251165,0.104983,0.372669,0.293533],[0.253219,0.106517,0.369963,0.291667],[0.255272,0.10805,0.367256,0.2898],[0.255777,0.108552,0.366212,0.288727],[0.256283,0.109053,0.365168,0.287653],[0.256788,0.109555,0.364124,0.28658],[0.256751,0.10852,0.364665,0.287653],[0.256713,0.107485,0.365207,0.288727],[0.256676,0.10645,0.365748,0.2898],[0.256096,0.10451,0.367875,0.291293],[0.255516,0.10257,0.370001,0.292787],[0.254936,0.10063,0.372128,0.29428],[0.256191,0.098795,0.373752,0.295353],[0.257445,0.09696,0.375376,0.296427],[0.2587,0.095125,0.377,0.2975],[0.262005,0.095172,0.375956,0.29638],[0.265311,0.095218,0.374912,0.29526],[0.268616,0.095265,0.373868,0.29414],[0.271027,0.095452,0.372747,0.293393],[0.273437,0.095638,0.371625,0.292647],[0.275848,0.095825,0.370504,0.2919],[0.277323,0.095825,0.369421,0.2919],[0.278797,0.095825,0.368339,0.2919],[0.280272,0.095825,0.367256,0.2919],[0.279731,0.095732,0.368339,0.292273],[0.279189,0.095638,0.369421,0.292647],[0.278648,0.095545,0.370504,0.29302],[0.277677,0.095673,0.371045,0.29344],[0.276707,0.095802,0.371587,0.29386],[0.275736,0.09593,0.372128,0.29428],[0.273829,0.096382,0.372708,0.294607],[0.271923,0.096833,0.373288,0.294933],[0.270016,0.097285,0.373868,0.29526],[0.268111,0.097458,0.374912,0.295633],[0.266205,0.097632,0.375956,0.296007],[0.2643,0.097805,0.377,0.29638],[0.2629,0.097712,0.377,0.296753],[0.2615,0.097618,0.377,0.297127],[0.2601,0.097525,0.377,0.2975],[0.258663,0.097432,0.377541,0.297873],[0.257225,0.097338,0.378083,0.298247],[0.255788,0.097245,0.378624,0.29862],[0.255825,0.097523,0.378083,0.298573],[0.255863,0.097802,0.377541,0.298527],[0.2559,0.09808,0.377,0.29848],[0.255935,0.099288,0.376497,0.29778],[0.255969,0.100497,0.375995,0.29708],[0.256004,0.101705,0.375492,0.29638],[0.256583,0.10274,0.373868,0.295307],[0.257161,0.103775,0.372244,0.294233],[0.25774,0.10481,0.37062,0.29316],[0.257236,0.10481,0.371161,0.29316],[0.256732,0.10481,0.371703,0.29316],[0.256228,0.10481,0.372244,0.29316],[0.256695,0.104543,0.372244,0.29316],[0.257161,0.104277,0.372244,0.29316],[0.257628,0.10401,0.372244,0.29316],[0.258599,0.103428,0.371703,0.293487],[0.259569,0.102847,0.371161,0.293813],[0.26054,0.102265,0.37062,0.29414],null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,[0.260436,0.090845,0.372128,0.29302],[0.259932,0.091507,0.372669,0.29344],[0.259428,0.092168,0.373211,0.29386],[0.258924,0.09283,0.373752,0.29428],[0.258959,0.093548,0.373249,0.294607],[0.258993,0.094267,0.372747,0.294933],[0.259028,0.094985,0.372244,0.29526],[0.259028,0.095845,0.372244,0.294887],[0.259028,0.096705,0.372244,0.294513],[0.259028,0.097565,0.372244,0.29414],[0.258524,0.097378,0.372785,0.294887],[0.25802,0.097192,0.373327,0.295633],[0.257516,0.097005,0.373868,0.29638],[0.257012,0.097853,0.374409,0.296053],[0.256508,0.098702,0.374951,0.295727],[0.256004,0.09955,0.375492,0.2954],[0.256583,0.100815,0.373868,0.294607],[0.257161,0.10208,0.372244,0.293813],[0.25774,0.103345,0.37062,0.29302],[0.258281,0.10438,0.369537,0.291947],[0.258823,0.105415,0.368455,0.290873],[0.259364,0.10645,0.367372,0.2898],null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,[0.281004,0.092305,0.375492,0.29638],[0.281508,0.093385,0.374951,0.29526],[0.282012,0.094465,0.374409,0.29414],[0.282516,0.095545,0.373868,0.29302],[0.283561,0.09622,0.372244,0.29232],[0.284607,0.096895,0.37062,0.29162],[0.285652,0.09757,0.368996,0.29092],[0.286193,0.098023,0.367913,0.290173],[0.286735,0.098477,0.366831,0.289427],[0.287276,0.09893,0.365748,0.28868],[0.286809,0.098385,0.365748,0.288727],[0.286343,0.09784,0.365748,0.288773],[0.285876,0.097295,0.365748,0.28882],[0.284831,0.09554,0.367372,0.29064],[0.283785,0.093785,0.368996,0.29246],[0.28274,0.09203,0.37062,0.29428],[0.281693,0.090728,0.372747,0.295353],[0.280647,0.089427,0.374873,0.296427],[0.2796,0.088125,0.377,0.2975],[0.279565,0.088125,0.377503,0.2975],[0.279531,0.088125,0.378005,0.2975],[0.279496,0.088125,0.378508,0.2975],[0.280393,0.087938,0.378547,0.298247],[0.281291,0.087752,0.378585,0.298993],[0.282188,0.087565,0.378624,0.29974],[0.283084,0.087565,0.379165,0.29974],[0.28398,0.087565,0.379707,0.29974],[0.284876,0.087565,0.380248,0.29974],[0.286351,0.087392,0.379165,0.299367],[0.287825,0.087218,0.378083,0.298993],[0.2893,0.087045,0.377,0.29862],[0.289729,0.086197,0.377541,0.298947],[0.290159,0.085348,0.378083,0.299273],[0.290588,0.0845,0.378624,0.2996],[0.290983,0.08342,0.379668,0.30072],[0.291377,0.08234,0.380712,0.30184],[0.291772,0.08126,0.381756,0.30296],[0.292557,0.080713,0.383419,0.30408],[0.293343,0.080167,0.385081,0.3052],[0.294128,0.07962,0.386744,0.30632],[0.295456,0.079793,0.387788,0.306693],[0.296784,0.079967,0.388832,0.307067],[0.298112,0.08014,0.389876,0.30744],[0.300016,0.080778,0.389335,0.30702],[0.30192,0.081417,0.388793,0.3066],[0.303824,0.082055,0.388252,0.30618],[0.305225,0.081777,0.387749,0.306227],[0.306627,0.081498,0.387247,0.306273],[0.308028,0.08122,0.386744,0.30632],[0.307993,0.080953,0.387247,0.30632],[0.307959,0.080687,0.387749,0.30632],[0.307924,0.08042,0.388252,0.30632],null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,[0.2907,0.073605,0.377,0.29638],[0.294045,0.074013,0.375376,0.29568],[0.297391,0.074422,0.373752,0.29498],[0.300736,0.07483,0.372128,0.29428],[0.304977,0.075643,0.371045,0.29316],[0.309219,0.076457,0.369963,0.29204],[0.31346,0.07727,0.36888,0.29092],[0.316691,0.077443,0.368919,0.291293],[0.319921,0.077617,0.368957,0.291667],[0.323152,0.07779,0.368996,0.29204],[0.325769,0.077522,0.371161,0.293113],[0.328387,0.077253,0.373327,0.294187],[0.331004,0.076985,0.375492,0.29526],[0.334164,0.076705,0.377039,0.29638],[0.337324,0.076425,0.378585,0.2975],[0.340484,0.076145,0.380132,0.29862],[0.343715,0.07597,0.380171,0.29932],[0.346945,0.075795,0.380209,0.30002],[0.350176,0.07562,0.380248,0.30072],[0.351651,0.076295,0.379165,0.30002],[0.353125,0.07697,0.378083,0.29932],[0.3546,0.077645,0.377,0.29862],[0.352771,0.078098,0.376459,0.297873],[0.350941,0.078552,0.375917,0.297127],[0.349112,0.079005,0.375376,0.29638],[0.344516,0.079272,0.374835,0.29638],[0.33992,0.079538,0.374293,0.29638],[0.335324,0.079805,0.373752,0.29638],[0.327495,0.080747,0.373211,0.29568],[0.319665,0.081688,0.372669,0.29498],[0.311836,0.08263,0.372128,0.29428],[0.303145,0.08407,0.370543,0.292787],[0.294455,0.08551,0.368957,0.291293],[0.285764,0.08695,0.367372,0.2898],[0.278084,0.088705,0.364665,0.28798],[0.270404,0.09046,0.361959,0.28616],[0.262724,0.092215,0.359252,0.28434],[0.257304,0.093797,0.357125,0.282147],[0.251884,0.095378,0.354999,0.279953],[0.246464,0.09696,0.352872,0.27776],null,null]}];
}
</sheet>
diff --git a/examples/interview/recipes.svs b/examples/interview/recipes.svs
index b968207d..88dd3334 100644
--- a/examples/interview/recipes.svs
+++ b/examples/interview/recipes.svs
@@ -9,10 +9,6 @@
gesture: expressive;
}
- media.performance { stack-order: 10;
- fit: cover;
- }
-
caption.boy {
stack-order: 70;
x: 0.5;
diff --git a/examples/interview/reference.svml b/examples/interview/reference.svml
index ef019f94..2391e7a3 100644
--- a/examples/interview/reference.svml
+++ b/examples/interview/reference.svml
@@ -1,18 +1,18 @@
<?svml using="@hypit/markup@1"?>
<svml>
- <import as="media-track" from="@hypit/media-track@1"/>
- <import as="sound" from="@hypit/sound@1"/>
- <import as="performance" from="@hypit/performance@1"/>
+ <import as="audio" from="@hypit/audio-track@1"/>
+ <import as="visual" from="@hypit/visual-track@1"/>
<import from="@hypit/script@1"/>
<import as="text" from="@hypit/text@1"/>
<import as="media" from="@hypit/media@1"/>
<import as="fish" from="@hypit/fishaudio-speech@1"/>
<import as="seedance" from="@hypit/seedance@1"/>
<import as="gpt" from="@hypit/gpt-image@1"/>
- <import as="program" from="@hypit/program-space@1"/>
<import as="pipeline" from="@hypit/media-pipeline@1"/>
<import as="whisperx" from="@hypit/whisperx@1"/>
+ <import as="semantic" from="@hypit/narrative-temporal@1"/>
+ <import as="narrative-caption" from="@hypit/narrative-caption@1"/>
<import as="time" from="@hypit/timeline-author@1"/>
<import as="audio-track" from="@hypit/audio-track@1"/>
<import as="caption" from="@hypit/caption@1"/>
@@ -227,9 +227,9 @@
</seedance:ReferenceVideo>
<space:Canvas id="vertical" width="720" height="1280"/>
- <space:Frame id="full-frame" within={vertical}
+ <space:Frame id="full-frame" within={vertical.bounds}
left="0%" top="0%" right="100%" bottom="100%"/>
- <program:Clock id="clock" frame-rate="30"/>
+ <time:Clock id="clock" frame-rate="30"/>
<pipeline:Normalize id="soundtrack-media" source={soundtrack}
video="none" audio="default" span-authority="audio" clock={clock}/>
@@ -243,40 +243,48 @@
<pipeline:Normalize id="bitcoin-rule-media" source={bitcoin-rule-take.video}
video="primary-moving" audio="default" span-authority="video" clock={clock}/>
- <whisperx:SemanticTake id="manifest-rule-semantic" narrative={story}
- segment={story.segment.manifest-rule} media={manifest-rule-media.media} language="en"/>
- <whisperx:SemanticTake id="real-estate-rule-semantic" narrative={story}
- segment={story.segment.real-estate-rule} media={real-estate-rule-media.media} language="en"/>
- <whisperx:SemanticTake id="bitcoin-rule-semantic" narrative={story}
- segment={story.segment.bitcoin-rule} media={bitcoin-rule-media.media} language="en"/>
+ <whisperx:Alignment id="manifest-rule-semantic" narrative={story}
+ segment={story.segment.manifest-rule} media={manifest-rule-media.media} domain={manifest-rule-media.domain} language="en"/>
+ <whisperx:Alignment id="real-estate-rule-semantic" narrative={story}
+ segment={story.segment.real-estate-rule} media={real-estate-rule-media.media} domain={real-estate-rule-media.domain} language="en"/>
+ <whisperx:Alignment id="bitcoin-rule-semantic" narrative={story}
+ segment={story.segment.bitcoin-rule} media={bitcoin-rule-media.media} domain={bitcoin-rule-media.domain} language="en"/>
- <time:Timeline id="speech" clock={clock}>
- <time:Take source={manifest-rule-semantic.take}/>
- <time:Take source={real-estate-rule-semantic.take}/>
- <time:Take source={bitcoin-rule-semantic.take}/>
+ <time:Timeline id="speech" clock={clock} end="bitcoin-rule-semantic.end">
+ <time:Window id="manifest-rule-semantic" from="start" for={manifest-rule-media.extent}/>
+ <time:Window id="real-estate-rule-semantic" from="manifest-rule-semantic.end" for={real-estate-rule-media.extent}/>
+ <time:Window id="bitcoin-rule-semantic" from="real-estate-rule-semantic.end" for={bitcoin-rule-media.extent}/>
</time:Timeline>
- <sound:Style id="speech-sound-style"/>
- <sound:Track id="speech-sound" timeline={speech.timeline}>
- <sound:Use style={speech-sound-style}/>
- </sound:Track>
- <performance:Style id="speech-picture-style" frame={full-frame} appearance={recipes.media.performance}/>
- <performance:Track id="speech-picture" timeline={speech.timeline} canvas={vertical}>
- <performance:Use style={speech-picture-style} during="program"/>
- </performance:Track>
+
+ <semantic:Projection id="story-time" narrative={story} timeline={speech.timeline}>
+ <semantic:Map alignment={manifest-rule-semantic.alignment} domain={manifest-rule-media.domain} window={speech.manifest-rule-semantic}/>
+ <semantic:Map alignment={real-estate-rule-semantic.alignment} domain={real-estate-rule-media.domain} window={speech.real-estate-rule-semantic}/>
+ <semantic:Map alignment={bitcoin-rule-semantic.alignment} domain={bitcoin-rule-media.domain} window={speech.bitcoin-rule-semantic}/>
+ <semantic:Instant id="moment-manifest-cue" moment={story.moment.manifest}/>
+ <semantic:Instant id="moment-real-estate-cue" moment={story.moment.real-estate}/>
+ <semantic:Instant id="moment-bitcoin-cue" moment={story.moment.bitcoin}/>
+ </semantic:Projection>
+ <audio:Track id="speech-sound" timeline={speech.timeline}>
+ <audio:Clip id="manifest-rule-semantic-source" source={manifest-rule-media.media} during={speech.manifest-rule-semantic}/>
+ <audio:Clip id="real-estate-rule-semantic-source" source={real-estate-rule-media.media} during={speech.real-estate-rule-semantic}/>
+ <audio:Clip id="bitcoin-rule-semantic-source" source={bitcoin-rule-media.media} during={speech.bitcoin-rule-semantic}/>
+ </audio:Track>
+ <visual:Track id="speech-picture" timeline={speech.timeline}>
+ <visual:Clip id="manifest-rule-semantic-source" media={manifest-rule-media.media} during={speech.manifest-rule-semantic} frame={full-frame} z="10" fit="cover"/>
+ <visual:Clip id="real-estate-rule-semantic-source" media={real-estate-rule-media.media} during={speech.real-estate-rule-semantic} frame={full-frame} z="10" fit="cover"/>
+ <visual:Clip id="bitcoin-rule-semantic-source" media={bitcoin-rule-media.media} during={speech.bitcoin-rule-semantic} frame={full-frame} z="10" fit="cover"/>
+ </visual:Track>
<audio-track:Track id="music-bed" timeline={speech.timeline}>
- <audio-track:Item source={soundtrack-media.media} during="program"
- playback="once-start" gain="0.12" fade-in="300ms" fade-out="600ms"/>
+ <audio-track:Clip source={soundtrack-media.media} during="timeline"
+ gain="0.12" fade-in="300ms" fade-out="600ms"/>
</audio-track:Track>
<audio-track:Track id="rule-reveal-sfx" timeline={speech.timeline}>
- <audio-track:Item id="manifest-reveal-sfx" source={rule-reveal-sound-media.media}
- at={story.moment.manifest} for="20f" playback="once-start" gain="0.20"/>
- <audio-track:Item id="real-estate-reveal-sfx" source={rule-reveal-sound-media.media}
- at={story.moment.real-estate} for="20f" playback="once-start" gain="0.20"/>
- <audio-track:Item id="bitcoin-reveal-sfx" source={rule-reveal-sound-media.media}
- at={story.moment.bitcoin} for="20f" playback="once-start" gain="0.20"/>
+ <audio-track:Clip id="manifest-reveal-sfx" source={rule-reveal-sound-media.media} from={story-time.moment-manifest-cue} for="20f" gain="0.20"/>
+ <audio-track:Clip id="real-estate-reveal-sfx" source={rule-reveal-sound-media.media} from={story-time.moment-real-estate-cue} for="20f" gain="0.20"/>
+ <audio-track:Clip id="bitcoin-reveal-sfx" source={rule-reveal-sound-media.media} from={story-time.moment-bitcoin-cue} for="20f" gain="0.20"/>
</audio-track:Track>
<fonts:Stack id="caption-font" family="league-spartan" weight="900" style="normal"/>
@@ -285,36 +293,37 @@
<caption-fine:Style id="caption-wife-style" recipe={recipes.caption.wife}
font={caption-font}/>
- <caption-fine:Track id="captions" document={story.caption}
- timeline={speech.timeline}>
+ <narrative-caption:Timing id="caption-timing" document={story.caption} binding={story.caption-binding} projection={story-time.projection}/>
+ <caption-fine:Caption id="captions" document={story.caption} timing={caption-timing}
+ timeline={speech.timeline} within={vertical.bounds}>
<caption-fine:Use style={caption-boy-style}/>
<caption-fine:Use role="WIFE" style={caption-wife-style}/>
- </caption-fine:Track>
+ </caption-fine:Caption>
<emoji:Style id="rule-reveal-style" recipe={recipes.emoji.strip}/>
- <emoji:Track id="rule-reveal" timeline={speech.timeline} canvas={vertical}
- style={rule-reveal-style} placeholder={rule-placeholder} during="program">
- <emoji:Item id="manifest" icon={manifest-icon} at={story.moment.manifest}/>
- <emoji:Item id="real-estate" icon={real-estate-icon} at={story.moment.real-estate}/>
- <emoji:Item id="bitcoin" icon={bitcoin-icon} at={story.moment.bitcoin}/>
- </emoji:Track>
+ <emoji:EmojiReveal id="rule-reveal" timeline={speech.timeline} within={vertical.bounds}
+ style={rule-reveal-style} placeholder={rule-placeholder} during="timeline">
+ <emoji:Item id="manifest" icon={manifest-icon} at={story-time.moment-manifest-cue}/>
+ <emoji:Item id="real-estate" icon={real-estate-icon} at={story-time.moment-real-estate-cue}/>
+ <emoji:Item id="bitcoin" icon={bitcoin-icon} at={story-time.moment-bitcoin-cue}/>
+ </emoji:EmojiReveal>
- <screen:Track id="rule-reveal-flashes" timeline={speech.timeline} canvas={vertical}>
- <screen:Flash id="manifest-flash" at={story.moment.manifest} for="8f" z="80"
+ <screen:Track id="rule-reveal-flashes" timeline={speech.timeline} within={vertical.bounds}>
+ <screen:Flash id="manifest-flash" from={story-time.moment-manifest-cue} for="8f" z="80"
color="#FF4D6D" intensity="0.28" attack="2" hold="1" decay="5"/>
- <screen:Flash id="real-estate-flash" at={story.moment.real-estate} for="8f" z="80"
+ <screen:Flash id="real-estate-flash" from={story-time.moment-real-estate-cue} for="8f" z="80"
color="#14A68A" intensity="0.28" attack="2" hold="1" decay="5"/>
- <screen:Flash id="bitcoin-flash" at={story.moment.bitcoin} for="8f" z="80"
+ <screen:Flash id="bitcoin-flash" from={story-time.moment-bitcoin-cue} for="8f" z="80"
color="#F59E0B" intensity="0.28" attack="2" hold="1" decay="5"/>
</screen:Track>
- <film:Film id="main" canvas={vertical} timeline={speech.timeline}
+ <film:Film id="main" canvas={vertical.canvas} timeline={speech.timeline}
appearance={recipes.film.vertical}>
<film:Track source={speech-picture.visual}/>
<film:Track source={speech-sound.audio}/>
- <film:Track source={captions.track}/>
- <film:Track source={rule-reveal.track}/>
- <film:Track source={rule-reveal-flashes.track}/>
+ <film:Track source={captions.visual}/>
+ <film:Track source={rule-reveal.visual}/>
+ <film:Track source={rule-reveal-flashes.visual}/>
<film:Track source={music-bed.audio}/>
<film:Track source={rule-reveal-sfx.audio}/>
</film:Film>
diff --git a/examples/interview/reference.svs b/examples/interview/reference.svs
index e7f3b703..892668f8 100644
--- a/examples/interview/reference.svs
+++ b/examples/interview/reference.svs
@@ -9,10 +9,6 @@
gesture: compact;
}
- media.performance { stack-order: 10;
- fit: cover;
- }
-
caption.boy {
stack-order: 70;
x: 0.5;
diff --git a/examples/interview/spanish-tracking.svs b/examples/interview/spanish-tracking.svs
index 7f848ef7..dc643264 100644
--- a/examples/interview/spanish-tracking.svs
+++ b/examples/interview/spanish-tracking.svs
@@ -1,7 +1,6 @@
<?svml using="@hypit/svs@1"?>
<sheet version="1">
heads.wife {
- frame-count: 783;
- tracks: [{"id":"WIFE","regions":[[0.117212,0.207835,0.273876,0.21546],[0.118183,0.208368,0.273335,0.21546],[0.119153,0.208902,0.272793,0.21546],[0.120124,0.209435,0.272252,0.21546],[0.120591,0.209923,0.272252,0.215507],[0.121057,0.210412,0.272252,0.215553],[0.121524,0.2109,0.272252,0.2156],[0.122495,0.210993,0.271711,0.215227],[0.123465,0.211087,0.271169,0.214853],[0.124436,0.21118,0.270628,0.21448],[0.125371,0.21024,0.270125,0.214107],[0.126305,0.2093,0.269623,0.213733],[0.12724,0.20836,0.26912,0.21336],[0.129109,0.206398,0.269081,0.21294],[0.130979,0.204437,0.269043,0.21252],[0.132848,0.202475,0.269004,0.2121],[0.133632,0.198608,0.271169,0.213967],[0.134416,0.194742,0.273335,0.215833],[0.1352,0.190875,0.2755,0.2177],[0.134549,0.187553,0.278168,0.21952],[0.133899,0.184232,0.280836,0.22134],[0.133248,0.18091,0.283504,0.22316],[0.133211,0.179783,0.284045,0.223533],[0.133173,0.178657,0.284587,0.223907],[0.133136,0.17753,0.285128,0.22428],[0.132744,0.177357,0.284045,0.223907],[0.132352,0.177183,0.282963,0.223533],[0.13196,0.17701,0.28188,0.22316],[0.13052,0.17701,0.28246,0.22316],[0.12908,0.17701,0.28304,0.22316],[0.12764,0.17701,0.28362,0.22316],[0.126239,0.177183,0.284123,0.223533],[0.124837,0.177357,0.284625,0.223907],[0.123436,0.17753,0.285128,0.22428],[0.122503,0.177715,0.285128,0.224607],[0.121569,0.1779,0.285128,0.224933],[0.120636,0.178085,0.285128,0.22526],[0.119665,0.178352,0.285669,0.22526],[0.118695,0.178618,0.286211,0.22526],[0.117724,0.178885,0.286752,0.22526],[0.117761,0.1792,0.286211,0.224933],[0.117799,0.179515,0.285669,0.224607],[0.117836,0.17983,0.285128,0.22428],[0.118881,0.180377,0.283504,0.22316],[0.119927,0.180923,0.28188,0.22204],[0.120972,0.18147,0.280256,0.22092],[0.121476,0.181912,0.279715,0.22022],[0.12198,0.182353,0.279173,0.21952],[0.122484,0.182795,0.278632,0.21882],[0.122988,0.182622,0.278091,0.218447],[0.123492,0.182448,0.277549,0.218073],[0.123996,0.182275,0.277008,0.2177],[0.124427,0.181915,0.277047,0.218073],[0.124857,0.181555,0.277085,0.218447],[0.125288,0.181195,0.277124,0.21882],[0.125251,0.181195,0.277665,0.21882],[0.125213,0.181195,0.278207,0.21882],[0.125176,0.181195,0.278748,0.21882],null,null,[0.276312,0.10711,0.404376,0.31836],[0.276816,0.10877,0.403835,0.317987],[0.27732,0.11043,0.403293,0.317613],[0.277824,0.11209,0.402752,0.31724],[0.278759,0.114017,0.402249,0.316867],[0.279693,0.115943,0.401747,0.316493],[0.280628,0.11787,0.401244,0.31612],[0.281599,0.11837,0.400703,0.31612],[0.282569,0.11887,0.400161,0.31612],[0.28354,0.11937,0.39962,0.31612],[0.28354,0.118603,0.39962,0.31612],[0.28354,0.117837,0.39962,0.31612],[0.28354,0.11707,0.39962,0.31612],[0.284044,0.116712,0.399079,0.31542],[0.284548,0.116353,0.398537,0.31472],[0.285052,0.115995,0.397996,0.31402],[0.284585,0.115413,0.397996,0.314347],[0.284119,0.114832,0.397996,0.314673],[0.283652,0.11425,0.397996,0.315],null,null,[0.125728,0.189695,0.270744,0.21322],[0.126269,0.190055,0.269661,0.212847],[0.126811,0.190415,0.268579,0.212473],[0.127352,0.190775,0.267496,0.2121],[0.127352,0.190775,0.267496,0.2121],[0.127352,0.190775,0.267496,0.2121],[0.127352,0.190775,0.267496,0.2121],[0.127315,0.190682,0.268037,0.212473],[0.127277,0.190588,0.268579,0.212847],[0.12724,0.190495,0.26912,0.21322],[0.127707,0.190903,0.26912,0.21252],[0.128173,0.191312,0.26912,0.21182],[0.12864,0.19172,0.26912,0.21112],[0.129611,0.191405,0.268579,0.211447],[0.130581,0.19109,0.268037,0.211773],[0.131552,0.190775,0.267496,0.2121],[0.131517,0.190508,0.267999,0.2121],[0.131483,0.190242,0.268501,0.2121],[0.131448,0.189975,0.269004,0.2121],[0.131877,0.189882,0.269545,0.212473],[0.132307,0.189788,0.270087,0.212847],[0.132736,0.189695,0.270628,0.21322],[0.132699,0.189335,0.271169,0.213593],[0.132661,0.188975,0.271711,0.213967],[0.132624,0.188615,0.272252,0.21434],[0.133091,0.188162,0.272252,0.215087],[0.133557,0.187708,0.272252,0.215833],[0.134024,0.187255,0.272252,0.21658],[0.133987,0.186895,0.272793,0.216953],[0.133949,0.186535,0.273335,0.217327],[0.133912,0.186175,0.273876,0.2177],[0.133837,0.185815,0.274959,0.218073],[0.133763,0.185455,0.276041,0.218447],[0.133688,0.185095,0.277124,0.21882],[0.134155,0.185095,0.277124,0.21882],[0.134621,0.185095,0.277124,0.21882],[0.135088,0.185095,0.277124,0.21882],[0.135557,0.185095,0.277085,0.21882],[0.136027,0.185095,0.277047,0.21882],[0.136496,0.185095,0.277008,0.21882],[0.136889,0.18478,0.277588,0.219147],[0.137283,0.184465,0.278168,0.219473],[0.137676,0.18415,0.278748,0.2198],[0.138143,0.18415,0.278748,0.2198],[0.138609,0.18415,0.278748,0.2198],[0.139076,0.18415,0.278748,0.2198],[0.139505,0.18379,0.279289,0.220173],[0.139935,0.18343,0.279831,0.220547],[0.140364,0.18307,0.280372,0.22092],[0.140364,0.18307,0.280372,0.22092],[0.140364,0.18307,0.280372,0.22092],[0.140364,0.18307,0.280372,0.22092],[0.141335,0.183163,0.279831,0.220547],[0.142305,0.183257,0.279289,0.220173],[0.143276,0.18335,0.278748,0.2198],[0.14378,0.183083,0.278207,0.2198],[0.144284,0.182817,0.277665,0.2198],[0.144788,0.18255,0.277124,0.2198],[0.145255,0.182365,0.277124,0.219473],[0.145721,0.18218,0.277124,0.219147],[0.146188,0.181995,0.277124,0.21882],[0.146188,0.181507,0.277124,0.218773],[0.146188,0.181018,0.277124,0.218727],[0.146188,0.18053,0.277124,0.21868],[0.147159,0.180623,0.276583,0.218307],[0.148129,0.180717,0.276041,0.217933],[0.1491,0.18081,0.2755,0.21756],[0.149137,0.181125,0.274959,0.217233],[0.149175,0.18144,0.274417,0.216907],[0.149212,0.181755,0.273876,0.21658],null,null,[0.292616,0.108375,0.388368,0.3073],[0.292616,0.10869,0.388368,0.306973],[0.292616,0.109005,0.388368,0.306647],[0.292616,0.10932,0.388368,0.30632],[0.292185,0.109227,0.388329,0.306693],[0.291755,0.109133,0.388291,0.307067],[0.291324,0.10904,0.388252,0.30744],[0.290316,0.108865,0.389335,0.30814],[0.289308,0.10869,0.390417,0.30884],[0.2883,0.108515,0.3915,0.30954],[0.287367,0.108782,0.3915,0.30954],[0.286433,0.109048,0.3915,0.30954],[0.2855,0.109315,0.3915,0.30954],[0.285537,0.110035,0.390959,0.308793],[0.285575,0.110755,0.390417,0.308047],[0.285612,0.111475,0.389876,0.3073],[0.286116,0.111835,0.389335,0.306927],[0.28662,0.112195,0.388793,0.306553],[0.287124,0.112555,0.388252,0.30618],[0.287628,0.11287,0.387711,0.305853],[0.288132,0.113185,0.387169,0.305527],[0.288636,0.1135,0.386628,0.3052],[0.289569,0.1135,0.386628,0.3052],[0.290503,0.1135,0.386628,0.3052],[0.291436,0.1135,0.386628,0.3052],[0.292371,0.113593,0.386125,0.304827],[0.293305,0.113687,0.385623,0.304453],[0.29424,0.11378,0.38512,0.30408],[0.294707,0.113558,0.38512,0.304033],[0.295173,0.113337,0.38512,0.303987],[0.29564,0.113115,0.38512,0.30394],[0.296144,0.113197,0.384579,0.303613],[0.296648,0.113278,0.384037,0.303287],[0.297152,0.11336,0.383496,0.30296],[0.297656,0.113453,0.382955,0.302587],[0.29816,0.113547,0.382413,0.302213],[0.298664,0.11364,0.381872,0.30184],[0.299635,0.113107,0.381331,0.30184],[0.300605,0.112573,0.380789,0.30184],[0.301576,0.11204,0.380248,0.30184],[0.301971,0.111495,0.381292,0.301887],[0.302365,0.11095,0.382336,0.301933],[0.30276,0.110405,0.38338,0.30198],[0.30362,0.109823,0.38396,0.302307],[0.30448,0.109242,0.38454,0.302633],[0.30534,0.10866,0.38512,0.30296],[0.305732,0.108207,0.386203,0.303707],[0.306124,0.107753,0.387285,0.304453],[0.306516,0.1073,0.388368,0.3052],[0.306444,0.106938,0.389412,0.306647],[0.306372,0.106577,0.390456,0.308093],[0.3063,0.106215,0.3915,0.30954],[0.305759,0.106795,0.392583,0.310287],[0.305217,0.107375,0.393665,0.311033],[0.304676,0.107955,0.394748,0.31178],[0.303741,0.109162,0.395251,0.312153],[0.302807,0.110368,0.395753,0.312527],[0.301872,0.111575,0.396256,0.3129],[0.301405,0.112653,0.396256,0.312853],[0.300939,0.113732,0.396256,0.312807],[0.300472,0.11481,0.396256,0.31276],[0.300544,0.115485,0.395212,0.31206],[0.300616,0.11616,0.394168,0.31136],[0.300688,0.116835,0.393124,0.31066],[0.300725,0.116835,0.392583,0.31066],[0.300763,0.116835,0.392041,0.31066],[0.3008,0.116835,0.3915,0.31066],null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,[0.303048,0.10485,0.399504,0.315],[0.303983,0.105037,0.399001,0.314253],[0.304917,0.105223,0.398499,0.313507],[0.305852,0.10541,0.397996,0.31276],[0.307327,0.105503,0.396913,0.312387],[0.308801,0.105597,0.395831,0.312013],[0.310276,0.10569,0.394748,0.31164],[0.311209,0.105772,0.394748,0.311313],[0.312143,0.105853,0.394748,0.310987],[0.313076,0.105935,0.394748,0.31066],[0.313975,0.105215,0.395251,0.311407],[0.314873,0.104495,0.395753,0.312153],[0.315772,0.103775,0.396256,0.3129],[0.315697,0.103333,0.397339,0.3136],[0.315623,0.102892,0.398421,0.3143],[0.315548,0.10245,0.399504,0.315],[0.315548,0.102717,0.399504,0.315],[0.315548,0.102983,0.399504,0.315],[0.315548,0.10325,0.399504,0.315],[0.314577,0.103423,0.400045,0.315373],[0.313607,0.103597,0.400587,0.315747],[0.312636,0.10377,0.401128,0.31612],[0.311199,0.103677,0.401669,0.316493],[0.309761,0.103583,0.402211,0.316867],[0.308324,0.10349,0.402752,0.31724],[0.30552,0.103942,0.403293,0.317567],[0.302716,0.104393,0.403835,0.317893],[0.299912,0.104845,0.404376,0.31822],[0.297541,0.105425,0.404917,0.318967],[0.295171,0.106005,0.405459,0.319713],[0.2928,0.106585,0.406,0.32046],[0.291361,0.106665,0.407044,0.321207],[0.289923,0.106745,0.408088,0.321953],[0.288484,0.106825,0.409132,0.3227],[0.287511,0.10665,0.409712,0.3234],[0.286537,0.106475,0.410292,0.3241],[0.285564,0.1063,0.410872,0.3248],[0.284521,0.105847,0.412457,0.325547],[0.283479,0.105393,0.414043,0.326293],[0.282436,0.10494,0.415628,0.32704],null,null,[0.147636,0.228845,0.256128,0.20342],[0.147599,0.228485,0.256669,0.203793],[0.147561,0.228125,0.257211,0.204167],[0.147524,0.227765,0.257752,0.20454],[0.147487,0.227312,0.258293,0.205287],[0.147449,0.226858,0.258835,0.206033],[0.147412,0.226405,0.259376,0.20678],[0.147449,0.226858,0.258835,0.206033],[0.147487,0.227312,0.258293,0.205287],[0.147524,0.227765,0.257752,0.20454],[0.147524,0.228218,0.257752,0.203793],[0.147524,0.228672,0.257752,0.203047],[0.147524,0.229125,0.257752,0.2023],[0.148028,0.229392,0.257211,0.2023],[0.148532,0.229658,0.256669,0.2023],[0.149036,0.229925,0.256128,0.2023],[0.149036,0.229565,0.256128,0.202673],[0.149036,0.229205,0.256128,0.203047],[0.149036,0.228845,0.256128,0.20342],null,null,[0.317588,0.14912,0.349624,0.27552],[0.316151,0.1484,0.350165,0.276267],[0.314713,0.14768,0.350707,0.277013],[0.313276,0.14696,0.351248,0.27776],[0.310829,0.145925,0.353375,0.278833],[0.308383,0.14489,0.355501,0.279907],[0.305936,0.143855,0.357628,0.28098],[0.305469,0.143495,0.357628,0.281353],[0.305003,0.143135,0.357628,0.281727],[0.304536,0.142775,0.357628,0.2821],[0.305508,0.143532,0.356584,0.281073],[0.30648,0.144288,0.35554,0.280047],[0.307452,0.145045,0.354496,0.27902],[0.308964,0.145765,0.352872,0.278273],[0.310476,0.146485,0.351248,0.277527],[0.311988,0.147205,0.349624,0.27678],[0.312492,0.147658,0.349083,0.276033],[0.312996,0.148112,0.348541,0.275287],[0.3135,0.148565,0.348,0.27454],[0.314004,0.148658,0.347459,0.274167],[0.314508,0.148752,0.346917,0.273793],[0.315012,0.148845,0.346376,0.27342],[0.314359,0.146997,0.349083,0.275613],[0.313705,0.145148,0.351789,0.277807],[0.313052,0.1433,0.354496,0.28],[0.312364,0.141452,0.357705,0.282193],[0.311676,0.139603,0.360915,0.284387],[0.310988,0.137755,0.364124,0.28658],[0.311343,0.136593,0.365748,0.288027],[0.311697,0.135432,0.367372,0.289473],[0.312052,0.13427,0.368996,0.29092],[0.312951,0.134083,0.369499,0.291667],[0.313849,0.133897,0.370001,0.292413],[0.314748,0.13371,0.370504,0.29316],[0.315177,0.13407,0.371045,0.292787],[0.315607,0.13443,0.371587,0.292413],[0.316036,0.13479,0.372128,0.29204],[0.316971,0.13515,0.371625,0.291667],[0.317905,0.13551,0.371123,0.291293],[0.31884,0.13587,0.37062,0.29092],[0.319344,0.13587,0.370079,0.29092],[0.319848,0.13587,0.369537,0.29092],[0.320352,0.13587,0.368996,0.29092],[0.320352,0.135603,0.368996,0.29092],[0.320352,0.135337,0.368996,0.29092],[0.320352,0.13507,0.368996,0.29092],[0.319885,0.13471,0.368996,0.291293],[0.319419,0.13435,0.368996,0.291667],[0.318952,0.13399,0.368996,0.29204],null,null,null,null,null,[0.146348,0.23059,0.254504,0.20244],[0.146348,0.23059,0.254504,0.20244],[0.146348,0.23059,0.254504,0.20244],[0.146348,0.23059,0.254504,0.20244],[0.145844,0.23059,0.255045,0.20244],[0.14534,0.23059,0.255587,0.20244],[0.144836,0.23059,0.256128,0.20244],[0.144369,0.230497,0.256128,0.202813],[0.143903,0.230403,0.256128,0.203187],[0.143436,0.23031,0.256128,0.20356],[0.143436,0.23067,0.256128,0.203187],[0.33846,0.124725,0.36888,0.2919],[0.33846,0.124725,0.36888,0.2919],[0.33846,0.124725,0.36888,0.2919],[0.33846,0.124725,0.36888,0.2919],[0.33846,0.124725,0.36888,0.2919],[0.33846,0.124725,0.36888,0.2919],[0.33846,0.124725,0.36888,0.2919],[0.33846,0.124725,0.36888,0.2919],[0.338852,0.125213,0.369963,0.291947],[0.339244,0.125702,0.371045,0.291993],[0.339636,0.12619,0.372128,0.29204],[0.341,0.126548,0.372167,0.29274],[0.342364,0.126907,0.372205,0.29344],[0.343728,0.127265,0.372244,0.29414],[0.344627,0.127753,0.372747,0.294187],[0.345525,0.128242,0.373249,0.294233],[0.346424,0.12873,0.373752,0.29428],[0.346387,0.128415,0.374293,0.294607],[0.346349,0.1281,0.374835,0.294933],[0.346312,0.127785,0.375376,0.29526],[0.346312,0.127692,0.375376,0.295633],[0.346312,0.127598,0.375376,0.296007],[0.346312,0.127505,0.375376,0.29638],[0.346312,0.127238,0.375376,0.29638],[0.346312,0.126972,0.375376,0.29638],[0.346312,0.126705,0.375376,0.29638],[0.346312,0.125893,0.375376,0.296427],[0.346312,0.125082,0.375376,0.296473],[0.346312,0.12427,0.375376,0.29652],[0.345771,0.123422,0.376459,0.296847],[0.345229,0.122573,0.377541,0.297173],[0.344688,0.121725,0.378624,0.2975],[0.344688,0.121005,0.378624,0.298247],[0.344688,0.120285,0.378624,0.298993],[0.344688,0.119565,0.378624,0.29974],[0.345117,0.119832,0.379165,0.29974],[0.345547,0.120098,0.379707,0.29974],[0.345976,0.120365,0.380248,0.29974],[0.346947,0.12127,0.379707,0.29932],[0.347917,0.122175,0.379165,0.2989],[0.348888,0.12308,0.378624,0.29848],[0.349392,0.123755,0.378083,0.29778],[0.349896,0.12443,0.377541,0.29708],[0.3504,0.125105,0.377,0.29638],[0.349896,0.124745,0.377541,0.296753],[0.349392,0.124385,0.378083,0.297127],[0.348888,0.124025,0.378624,0.2975],[0.348421,0.12371,0.378624,0.297827],[0.347955,0.123395,0.378624,0.298153],[0.347488,0.12308,0.378624,0.29848],[0.347563,0.123255,0.377541,0.29778],[0.347637,0.12343,0.376459,0.29708],[0.347712,0.123605,0.375376,0.29638],[0.347859,0.123978,0.373249,0.294887],[0.348005,0.124352,0.371123,0.293393],[0.348152,0.124725,0.368996,0.2919],[0.347293,0.125575,0.367913,0.2905],[0.346435,0.126425,0.366831,0.2891],[0.345576,0.127275,0.365748,0.2877],[0.345688,0.127995,0.364124,0.286953],[0.3458,0.128715,0.3625,0.286207],[0.345912,0.129435,0.360876,0.28546],[0.346341,0.129342,0.361417,0.285833],[0.346771,0.129248,0.361959,0.286207],[0.3472,0.129155,0.3625,0.28658],[0.346547,0.127807,0.365207,0.288773],[0.345893,0.126458,0.367913,0.290967],[0.34524,0.12511,0.37062,0.29316],[0.344231,0.124075,0.372205,0.294233],[0.343221,0.12304,0.373791,0.295307],[0.342212,0.122005,0.375376,0.29638],[0.341783,0.121738,0.374835,0.29638],[0.341353,0.121472,0.374293,0.29638],[0.340924,0.121205,0.373752,0.29638],[0.340924,0.121565,0.373752,0.296007],[0.340924,0.121925,0.373752,0.295633],[0.340924,0.122285,0.373752,0.29526],[0.340849,0.121832,0.374835,0.296007],[0.340775,0.121378,0.375917,0.296753],[0.3407,0.120925,0.377,0.2975],[0.341167,0.120832,0.377,0.297873],[0.341633,0.120738,0.377,0.298247],[0.3421,0.120645,0.377,0.29862],[0.3421,0.121005,0.377,0.298247],[0.3421,0.121365,0.377,0.297873],[0.3421,0.121725,0.377,0.2975],null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,[0.322976,0.137805,0.351248,0.27678],[0.322939,0.13763,0.351789,0.27748],[0.322901,0.137455,0.352331,0.27818],[0.322864,0.13728,0.352872,0.27888],[0.321781,0.137533,0.355037,0.28],[0.320699,0.137787,0.357203,0.28112],[0.319616,0.13804,0.359368,0.28224],[0.318103,0.13741,0.361495,0.28476],[0.316589,0.13678,0.363621,0.28728],[0.315076,0.13615,0.365748,0.2898],[0.314572,0.136057,0.366289,0.290173],[0.314068,0.135963,0.366831,0.290547],[0.313564,0.13587,0.367372,0.29092],[0.314572,0.136138,0.366289,0.289847],[0.31558,0.136407,0.365207,0.288773],[0.316588,0.136675,0.364124,0.2877],[0.316625,0.137035,0.363583,0.287327],[0.316663,0.137395,0.363041,0.286953],[0.3167,0.137755,0.3625,0.28658],[0.315225,0.137847,0.363583,0.28728],[0.313751,0.137938,0.364665,0.28798],[0.312276,0.13803,0.365748,0.28868],[0.311809,0.137843,0.365748,0.289427],[0.311343,0.137657,0.365748,0.290173],[0.310876,0.13747,0.365748,0.29092],[0.310913,0.137657,0.365207,0.290173],[0.310951,0.137843,0.364665,0.289427],[0.310988,0.13803,0.364124,0.28868],null,null,[0.126176,0.222225,0.264248,0.2079],[0.126176,0.222585,0.264248,0.207527],[0.126176,0.222945,0.264248,0.207153],[0.126176,0.223305,0.264248,0.20678],[0.126717,0.223665,0.263165,0.206407],[0.127259,0.224025,0.262083,0.206033],[0.1278,0.224385,0.261,0.20566],[0.128304,0.22506,0.260459,0.20496],[0.128808,0.225735,0.259917,0.20426],[0.129312,0.22641,0.259376,0.20356],[0.129816,0.22677,0.258835,0.203187],[0.13032,0.22713,0.258293,0.202813],[0.130824,0.22749,0.257752,0.20244],[0.131291,0.227768,0.257752,0.202393],[0.131757,0.228047,0.257752,0.202347],[0.132224,0.228325,0.257752,0.2023],[0.132691,0.227965,0.257752,0.202673],[0.133157,0.227605,0.257752,0.203047],[0.133624,0.227245,0.257752,0.20342],[0.133587,0.227245,0.258293,0.20342],[0.133549,0.227245,0.258835,0.20342],[0.133512,0.227245,0.259376,0.20342],null,null,[0.273248,0.11551,0.428504,0.33796],[0.273715,0.116043,0.428504,0.33796],[0.274181,0.116577,0.428504,0.33796],[0.274648,0.11711,0.428504,0.33796],[0.276124,0.118145,0.426919,0.336887],[0.2776,0.11918,0.425333,0.335813],[0.279076,0.120215,0.423748,0.33474],[0.280588,0.121028,0.422124,0.33362],[0.2821,0.121842,0.4205,0.3325],[0.283612,0.122655,0.418876,0.33138],[0.284583,0.123423,0.418335,0.330307],[0.285553,0.124192,0.417793,0.329233],[0.286524,0.12496,0.417252,0.32816],[0.287495,0.125053,0.416711,0.327787],[0.288465,0.125147,0.416169,0.327413],[0.289436,0.12524,0.415628,0.32704],[0.289829,0.124298,0.416208,0.32774],[0.290223,0.123357,0.416788,0.32844],[0.290616,0.122415,0.417368,0.32914],[0.290148,0.121417,0.417871,0.329933],[0.28968,0.120418,0.418373,0.330727],[0.289212,0.11942,0.418876,0.33152],[0.289212,0.118932,0.418876,0.331473],[0.289212,0.118443,0.418876,0.331427],[0.289212,0.117955,0.418876,0.33138],[0.290259,0.118583,0.416749,0.329933],[0.291305,0.119212,0.414623,0.328487],[0.292352,0.11984,0.412496,0.32704],[0.293864,0.120702,0.410872,0.325593],[0.295376,0.121563,0.409248,0.324147],[0.296888,0.122425,0.407624,0.3227],[0.297896,0.123238,0.406541,0.32158],[0.298904,0.124052,0.405459,0.32046],[0.299912,0.124865,0.404376,0.31934],[0.299875,0.124505,0.404917,0.319713],[0.299837,0.124145,0.405459,0.320087],[0.2998,0.123785,0.406,0.32046],[0.299259,0.123598,0.407083,0.321207],[0.298717,0.123412,0.408165,0.321953],[0.298176,0.123225,0.409248,0.3227],[0.2976,0.12305,0.410833,0.3234],[0.297024,0.122875,0.412419,0.3241],[0.296448,0.1227,0.414004,0.3248],[0.296877,0.122153,0.414545,0.32592],[0.297307,0.121607,0.415087,0.32704],[0.297736,0.12106,0.415628,0.32816],[0.298128,0.120873,0.416711,0.328907],[0.29852,0.120687,0.417793,0.329653],[0.298912,0.1205,0.418876,0.3304],[0.298837,0.119465,0.419959,0.331473],[0.298763,0.11843,0.421041,0.332547],[0.298688,0.117395,0.422124,0.33362],[0.298651,0.117128,0.422665,0.33362],[0.298613,0.116862,0.423207,0.33362],[0.298576,0.116595,0.423748,0.33362],[0.29908,0.116595,0.423207,0.33362],[0.299584,0.116595,0.422665,0.33362],[0.300088,0.116595,0.422124,0.33362],[0.299584,0.116862,0.422665,0.33362],[0.29908,0.117128,0.423207,0.33362],[0.298576,0.117395,0.423748,0.33362],[0.297605,0.11722,0.424289,0.33432],[0.296635,0.117045,0.424831,0.33502],[0.295664,0.11687,0.425372,0.33572],[0.295197,0.11687,0.425372,0.33572],[0.294731,0.11687,0.425372,0.33572],[0.294264,0.11687,0.425372,0.33572],[0.294301,0.117452,0.424831,0.335393],[0.294339,0.118033,0.424289,0.335067],[0.294376,0.118615,0.423748,0.33474],[0.294917,0.119068,0.422665,0.333993],[0.295459,0.119522,0.421583,0.333247],[0.296,0.119975,0.4205,0.3325],[0.296075,0.120243,0.419417,0.331427],[0.296149,0.120512,0.418335,0.330353],[0.296224,0.12078,0.417252,0.32928],[0.295795,0.120385,0.416711,0.32886],[0.295365,0.11999,0.416169,0.32844],[0.294936,0.119595,0.415628,0.32802],[0.294,0.11941,0.415667,0.327693],[0.293064,0.119225,0.415705,0.327367],[0.292128,0.11904,0.415744,0.32704],[0.292203,0.119133,0.414661,0.326667],[0.292277,0.119227,0.413579,0.326293],[0.292352,0.11932,0.412496,0.32592],[0.293397,0.120355,0.410872,0.324847],[0.294443,0.12139,0.409248,0.323773],[0.295488,0.122425,0.407624,0.3227],[0.295488,0.122958,0.407624,0.3227],[0.295488,0.123492,0.407624,0.3227],[0.295488,0.124025,0.407624,0.3227],[0.294984,0.12421,0.408165,0.323027],[0.29448,0.124395,0.408707,0.323353],[0.293976,0.12458,0.409248,0.32368],[0.294051,0.125615,0.408165,0.322607],[0.294125,0.12665,0.407083,0.321533],[0.2942,0.127685,0.406,0.32046],[0.294275,0.128672,0.404917,0.319713],[0.294349,0.129658,0.403835,0.318967],[0.294424,0.130645,0.402752,0.31822],[0.294928,0.13096,0.402211,0.317893],[0.295432,0.131275,0.401669,0.317567],[0.295936,0.13159,0.401128,0.31724],[0.296907,0.131683,0.400587,0.316867],[0.297877,0.131777,0.400045,0.316493],[0.298848,0.13187,0.399504,0.31612],[0.299315,0.131963,0.399504,0.315747],[0.299781,0.132057,0.399504,0.315373],[0.300248,0.13215,0.399504,0.315],null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,[0.30854,0.12745,0.39962,0.315],[0.309513,0.127217,0.39904,0.315],[0.310487,0.126983,0.39846,0.315],[0.31146,0.12675,0.39788,0.315],[0.312356,0.126983,0.398421,0.315],[0.313252,0.127217,0.398963,0.315],[0.314148,0.12745,0.399504,0.315],[0.313999,0.126983,0.401669,0.316867],[0.313849,0.126517,0.403835,0.318733],[0.3137,0.12605,0.406,0.3206],[0.313087,0.125513,0.408127,0.322747],[0.312473,0.124977,0.410253,0.324893],[0.31186,0.12444,0.41238,0.32704],[0.312327,0.125333,0.41238,0.326667],[0.312793,0.126227,0.41238,0.326293],[0.31326,0.12712,0.41238,0.32592],[0.314269,0.128155,0.410795,0.324847],[0.315279,0.12919,0.409209,0.323773],[0.316288,0.130225,0.407624,0.3227],[0.316288,0.130852,0.407624,0.322327],[0.316288,0.131478,0.407624,0.321953],[0.316288,0.132105,0.407624,0.32158],[0.316251,0.132278,0.408165,0.321953],[0.316213,0.132452,0.408707,0.322327],[0.316176,0.132625,0.409248,0.3227],[0.317072,0.131905,0.409789,0.323447],[0.317968,0.131185,0.410331,0.324193],[0.318864,0.130465,0.410872,0.32494],[0.321088,0.128897,0.412457,0.326013],[0.323312,0.127328,0.414043,0.327087],[0.325536,0.12576,0.415628,0.32816],[0.328228,0.124007,0.416711,0.328907],[0.33092,0.122253,0.417793,0.329653],[0.333612,0.1205,0.418876,0.3304],[0.337421,0.11984,0.417291,0.328907],[0.341231,0.11918,0.415705,0.327413],[0.34504,0.11852,0.41412,0.32592],[0.347956,0.117848,0.411955,0.324473],[0.350872,0.117177,0.409789,0.323027],[0.353788,0.116505,0.407624,0.32158],[0.352533,0.115973,0.406,0.320507],[0.351279,0.115442,0.404376,0.319433],[0.350024,0.11491,0.402752,0.31836],[0.345108,0.115237,0.400084,0.31612],[0.340192,0.115563,0.397416,0.31388],[0.335276,0.11589,0.394748,0.31164],[0.329893,0.11666,0.39208,0.309493],[0.324511,0.11743,0.389412,0.307347],[0.319128,0.1182,0.386744,0.3052],null,null]}];
+ series: [{"id":"WIFE","regions":[[0.117212,0.207835,0.273876,0.21546],[0.118183,0.208368,0.273335,0.21546],[0.119153,0.208902,0.272793,0.21546],[0.120124,0.209435,0.272252,0.21546],[0.120591,0.209923,0.272252,0.215507],[0.121057,0.210412,0.272252,0.215553],[0.121524,0.2109,0.272252,0.2156],[0.122495,0.210993,0.271711,0.215227],[0.123465,0.211087,0.271169,0.214853],[0.124436,0.21118,0.270628,0.21448],[0.125371,0.21024,0.270125,0.214107],[0.126305,0.2093,0.269623,0.213733],[0.12724,0.20836,0.26912,0.21336],[0.129109,0.206398,0.269081,0.21294],[0.130979,0.204437,0.269043,0.21252],[0.132848,0.202475,0.269004,0.2121],[0.133632,0.198608,0.271169,0.213967],[0.134416,0.194742,0.273335,0.215833],[0.1352,0.190875,0.2755,0.2177],[0.134549,0.187553,0.278168,0.21952],[0.133899,0.184232,0.280836,0.22134],[0.133248,0.18091,0.283504,0.22316],[0.133211,0.179783,0.284045,0.223533],[0.133173,0.178657,0.284587,0.223907],[0.133136,0.17753,0.285128,0.22428],[0.132744,0.177357,0.284045,0.223907],[0.132352,0.177183,0.282963,0.223533],[0.13196,0.17701,0.28188,0.22316],[0.13052,0.17701,0.28246,0.22316],[0.12908,0.17701,0.28304,0.22316],[0.12764,0.17701,0.28362,0.22316],[0.126239,0.177183,0.284123,0.223533],[0.124837,0.177357,0.284625,0.223907],[0.123436,0.17753,0.285128,0.22428],[0.122503,0.177715,0.285128,0.224607],[0.121569,0.1779,0.285128,0.224933],[0.120636,0.178085,0.285128,0.22526],[0.119665,0.178352,0.285669,0.22526],[0.118695,0.178618,0.286211,0.22526],[0.117724,0.178885,0.286752,0.22526],[0.117761,0.1792,0.286211,0.224933],[0.117799,0.179515,0.285669,0.224607],[0.117836,0.17983,0.285128,0.22428],[0.118881,0.180377,0.283504,0.22316],[0.119927,0.180923,0.28188,0.22204],[0.120972,0.18147,0.280256,0.22092],[0.121476,0.181912,0.279715,0.22022],[0.12198,0.182353,0.279173,0.21952],[0.122484,0.182795,0.278632,0.21882],[0.122988,0.182622,0.278091,0.218447],[0.123492,0.182448,0.277549,0.218073],[0.123996,0.182275,0.277008,0.2177],[0.124427,0.181915,0.277047,0.218073],[0.124857,0.181555,0.277085,0.218447],[0.125288,0.181195,0.277124,0.21882],[0.125251,0.181195,0.277665,0.21882],[0.125213,0.181195,0.278207,0.21882],[0.125176,0.181195,0.278748,0.21882],null,null,[0.276312,0.10711,0.404376,0.31836],[0.276816,0.10877,0.403835,0.317987],[0.27732,0.11043,0.403293,0.317613],[0.277824,0.11209,0.402752,0.31724],[0.278759,0.114017,0.402249,0.316867],[0.279693,0.115943,0.401747,0.316493],[0.280628,0.11787,0.401244,0.31612],[0.281599,0.11837,0.400703,0.31612],[0.282569,0.11887,0.400161,0.31612],[0.28354,0.11937,0.39962,0.31612],[0.28354,0.118603,0.39962,0.31612],[0.28354,0.117837,0.39962,0.31612],[0.28354,0.11707,0.39962,0.31612],[0.284044,0.116712,0.399079,0.31542],[0.284548,0.116353,0.398537,0.31472],[0.285052,0.115995,0.397996,0.31402],[0.284585,0.115413,0.397996,0.314347],[0.284119,0.114832,0.397996,0.314673],[0.283652,0.11425,0.397996,0.315],null,null,[0.125728,0.189695,0.270744,0.21322],[0.126269,0.190055,0.269661,0.212847],[0.126811,0.190415,0.268579,0.212473],[0.127352,0.190775,0.267496,0.2121],[0.127352,0.190775,0.267496,0.2121],[0.127352,0.190775,0.267496,0.2121],[0.127352,0.190775,0.267496,0.2121],[0.127315,0.190682,0.268037,0.212473],[0.127277,0.190588,0.268579,0.212847],[0.12724,0.190495,0.26912,0.21322],[0.127707,0.190903,0.26912,0.21252],[0.128173,0.191312,0.26912,0.21182],[0.12864,0.19172,0.26912,0.21112],[0.129611,0.191405,0.268579,0.211447],[0.130581,0.19109,0.268037,0.211773],[0.131552,0.190775,0.267496,0.2121],[0.131517,0.190508,0.267999,0.2121],[0.131483,0.190242,0.268501,0.2121],[0.131448,0.189975,0.269004,0.2121],[0.131877,0.189882,0.269545,0.212473],[0.132307,0.189788,0.270087,0.212847],[0.132736,0.189695,0.270628,0.21322],[0.132699,0.189335,0.271169,0.213593],[0.132661,0.188975,0.271711,0.213967],[0.132624,0.188615,0.272252,0.21434],[0.133091,0.188162,0.272252,0.215087],[0.133557,0.187708,0.272252,0.215833],[0.134024,0.187255,0.272252,0.21658],[0.133987,0.186895,0.272793,0.216953],[0.133949,0.186535,0.273335,0.217327],[0.133912,0.186175,0.273876,0.2177],[0.133837,0.185815,0.274959,0.218073],[0.133763,0.185455,0.276041,0.218447],[0.133688,0.185095,0.277124,0.21882],[0.134155,0.185095,0.277124,0.21882],[0.134621,0.185095,0.277124,0.21882],[0.135088,0.185095,0.277124,0.21882],[0.135557,0.185095,0.277085,0.21882],[0.136027,0.185095,0.277047,0.21882],[0.136496,0.185095,0.277008,0.21882],[0.136889,0.18478,0.277588,0.219147],[0.137283,0.184465,0.278168,0.219473],[0.137676,0.18415,0.278748,0.2198],[0.138143,0.18415,0.278748,0.2198],[0.138609,0.18415,0.278748,0.2198],[0.139076,0.18415,0.278748,0.2198],[0.139505,0.18379,0.279289,0.220173],[0.139935,0.18343,0.279831,0.220547],[0.140364,0.18307,0.280372,0.22092],[0.140364,0.18307,0.280372,0.22092],[0.140364,0.18307,0.280372,0.22092],[0.140364,0.18307,0.280372,0.22092],[0.141335,0.183163,0.279831,0.220547],[0.142305,0.183257,0.279289,0.220173],[0.143276,0.18335,0.278748,0.2198],[0.14378,0.183083,0.278207,0.2198],[0.144284,0.182817,0.277665,0.2198],[0.144788,0.18255,0.277124,0.2198],[0.145255,0.182365,0.277124,0.219473],[0.145721,0.18218,0.277124,0.219147],[0.146188,0.181995,0.277124,0.21882],[0.146188,0.181507,0.277124,0.218773],[0.146188,0.181018,0.277124,0.218727],[0.146188,0.18053,0.277124,0.21868],[0.147159,0.180623,0.276583,0.218307],[0.148129,0.180717,0.276041,0.217933],[0.1491,0.18081,0.2755,0.21756],[0.149137,0.181125,0.274959,0.217233],[0.149175,0.18144,0.274417,0.216907],[0.149212,0.181755,0.273876,0.21658],null,null,[0.292616,0.108375,0.388368,0.3073],[0.292616,0.10869,0.388368,0.306973],[0.292616,0.109005,0.388368,0.306647],[0.292616,0.10932,0.388368,0.30632],[0.292185,0.109227,0.388329,0.306693],[0.291755,0.109133,0.388291,0.307067],[0.291324,0.10904,0.388252,0.30744],[0.290316,0.108865,0.389335,0.30814],[0.289308,0.10869,0.390417,0.30884],[0.2883,0.108515,0.3915,0.30954],[0.287367,0.108782,0.3915,0.30954],[0.286433,0.109048,0.3915,0.30954],[0.2855,0.109315,0.3915,0.30954],[0.285537,0.110035,0.390959,0.308793],[0.285575,0.110755,0.390417,0.308047],[0.285612,0.111475,0.389876,0.3073],[0.286116,0.111835,0.389335,0.306927],[0.28662,0.112195,0.388793,0.306553],[0.287124,0.112555,0.388252,0.30618],[0.287628,0.11287,0.387711,0.305853],[0.288132,0.113185,0.387169,0.305527],[0.288636,0.1135,0.386628,0.3052],[0.289569,0.1135,0.386628,0.3052],[0.290503,0.1135,0.386628,0.3052],[0.291436,0.1135,0.386628,0.3052],[0.292371,0.113593,0.386125,0.304827],[0.293305,0.113687,0.385623,0.304453],[0.29424,0.11378,0.38512,0.30408],[0.294707,0.113558,0.38512,0.304033],[0.295173,0.113337,0.38512,0.303987],[0.29564,0.113115,0.38512,0.30394],[0.296144,0.113197,0.384579,0.303613],[0.296648,0.113278,0.384037,0.303287],[0.297152,0.11336,0.383496,0.30296],[0.297656,0.113453,0.382955,0.302587],[0.29816,0.113547,0.382413,0.302213],[0.298664,0.11364,0.381872,0.30184],[0.299635,0.113107,0.381331,0.30184],[0.300605,0.112573,0.380789,0.30184],[0.301576,0.11204,0.380248,0.30184],[0.301971,0.111495,0.381292,0.301887],[0.302365,0.11095,0.382336,0.301933],[0.30276,0.110405,0.38338,0.30198],[0.30362,0.109823,0.38396,0.302307],[0.30448,0.109242,0.38454,0.302633],[0.30534,0.10866,0.38512,0.30296],[0.305732,0.108207,0.386203,0.303707],[0.306124,0.107753,0.387285,0.304453],[0.306516,0.1073,0.388368,0.3052],[0.306444,0.106938,0.389412,0.306647],[0.306372,0.106577,0.390456,0.308093],[0.3063,0.106215,0.3915,0.30954],[0.305759,0.106795,0.392583,0.310287],[0.305217,0.107375,0.393665,0.311033],[0.304676,0.107955,0.394748,0.31178],[0.303741,0.109162,0.395251,0.312153],[0.302807,0.110368,0.395753,0.312527],[0.301872,0.111575,0.396256,0.3129],[0.301405,0.112653,0.396256,0.312853],[0.300939,0.113732,0.396256,0.312807],[0.300472,0.11481,0.396256,0.31276],[0.300544,0.115485,0.395212,0.31206],[0.300616,0.11616,0.394168,0.31136],[0.300688,0.116835,0.393124,0.31066],[0.300725,0.116835,0.392583,0.31066],[0.300763,0.116835,0.392041,0.31066],[0.3008,0.116835,0.3915,0.31066],null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,[0.303048,0.10485,0.399504,0.315],[0.303983,0.105037,0.399001,0.314253],[0.304917,0.105223,0.398499,0.313507],[0.305852,0.10541,0.397996,0.31276],[0.307327,0.105503,0.396913,0.312387],[0.308801,0.105597,0.395831,0.312013],[0.310276,0.10569,0.394748,0.31164],[0.311209,0.105772,0.394748,0.311313],[0.312143,0.105853,0.394748,0.310987],[0.313076,0.105935,0.394748,0.31066],[0.313975,0.105215,0.395251,0.311407],[0.314873,0.104495,0.395753,0.312153],[0.315772,0.103775,0.396256,0.3129],[0.315697,0.103333,0.397339,0.3136],[0.315623,0.102892,0.398421,0.3143],[0.315548,0.10245,0.399504,0.315],[0.315548,0.102717,0.399504,0.315],[0.315548,0.102983,0.399504,0.315],[0.315548,0.10325,0.399504,0.315],[0.314577,0.103423,0.400045,0.315373],[0.313607,0.103597,0.400587,0.315747],[0.312636,0.10377,0.401128,0.31612],[0.311199,0.103677,0.401669,0.316493],[0.309761,0.103583,0.402211,0.316867],[0.308324,0.10349,0.402752,0.31724],[0.30552,0.103942,0.403293,0.317567],[0.302716,0.104393,0.403835,0.317893],[0.299912,0.104845,0.404376,0.31822],[0.297541,0.105425,0.404917,0.318967],[0.295171,0.106005,0.405459,0.319713],[0.2928,0.106585,0.406,0.32046],[0.291361,0.106665,0.407044,0.321207],[0.289923,0.106745,0.408088,0.321953],[0.288484,0.106825,0.409132,0.3227],[0.287511,0.10665,0.409712,0.3234],[0.286537,0.106475,0.410292,0.3241],[0.285564,0.1063,0.410872,0.3248],[0.284521,0.105847,0.412457,0.325547],[0.283479,0.105393,0.414043,0.326293],[0.282436,0.10494,0.415628,0.32704],null,null,[0.147636,0.228845,0.256128,0.20342],[0.147599,0.228485,0.256669,0.203793],[0.147561,0.228125,0.257211,0.204167],[0.147524,0.227765,0.257752,0.20454],[0.147487,0.227312,0.258293,0.205287],[0.147449,0.226858,0.258835,0.206033],[0.147412,0.226405,0.259376,0.20678],[0.147449,0.226858,0.258835,0.206033],[0.147487,0.227312,0.258293,0.205287],[0.147524,0.227765,0.257752,0.20454],[0.147524,0.228218,0.257752,0.203793],[0.147524,0.228672,0.257752,0.203047],[0.147524,0.229125,0.257752,0.2023],[0.148028,0.229392,0.257211,0.2023],[0.148532,0.229658,0.256669,0.2023],[0.149036,0.229925,0.256128,0.2023],[0.149036,0.229565,0.256128,0.202673],[0.149036,0.229205,0.256128,0.203047],[0.149036,0.228845,0.256128,0.20342],null,null,[0.317588,0.14912,0.349624,0.27552],[0.316151,0.1484,0.350165,0.276267],[0.314713,0.14768,0.350707,0.277013],[0.313276,0.14696,0.351248,0.27776],[0.310829,0.145925,0.353375,0.278833],[0.308383,0.14489,0.355501,0.279907],[0.305936,0.143855,0.357628,0.28098],[0.305469,0.143495,0.357628,0.281353],[0.305003,0.143135,0.357628,0.281727],[0.304536,0.142775,0.357628,0.2821],[0.305508,0.143532,0.356584,0.281073],[0.30648,0.144288,0.35554,0.280047],[0.307452,0.145045,0.354496,0.27902],[0.308964,0.145765,0.352872,0.278273],[0.310476,0.146485,0.351248,0.277527],[0.311988,0.147205,0.349624,0.27678],[0.312492,0.147658,0.349083,0.276033],[0.312996,0.148112,0.348541,0.275287],[0.3135,0.148565,0.348,0.27454],[0.314004,0.148658,0.347459,0.274167],[0.314508,0.148752,0.346917,0.273793],[0.315012,0.148845,0.346376,0.27342],[0.314359,0.146997,0.349083,0.275613],[0.313705,0.145148,0.351789,0.277807],[0.313052,0.1433,0.354496,0.28],[0.312364,0.141452,0.357705,0.282193],[0.311676,0.139603,0.360915,0.284387],[0.310988,0.137755,0.364124,0.28658],[0.311343,0.136593,0.365748,0.288027],[0.311697,0.135432,0.367372,0.289473],[0.312052,0.13427,0.368996,0.29092],[0.312951,0.134083,0.369499,0.291667],[0.313849,0.133897,0.370001,0.292413],[0.314748,0.13371,0.370504,0.29316],[0.315177,0.13407,0.371045,0.292787],[0.315607,0.13443,0.371587,0.292413],[0.316036,0.13479,0.372128,0.29204],[0.316971,0.13515,0.371625,0.291667],[0.317905,0.13551,0.371123,0.291293],[0.31884,0.13587,0.37062,0.29092],[0.319344,0.13587,0.370079,0.29092],[0.319848,0.13587,0.369537,0.29092],[0.320352,0.13587,0.368996,0.29092],[0.320352,0.135603,0.368996,0.29092],[0.320352,0.135337,0.368996,0.29092],[0.320352,0.13507,0.368996,0.29092],[0.319885,0.13471,0.368996,0.291293],[0.319419,0.13435,0.368996,0.291667],[0.318952,0.13399,0.368996,0.29204],null,null,null,null,null,[0.146348,0.23059,0.254504,0.20244],[0.146348,0.23059,0.254504,0.20244],[0.146348,0.23059,0.254504,0.20244],[0.146348,0.23059,0.254504,0.20244],[0.145844,0.23059,0.255045,0.20244],[0.14534,0.23059,0.255587,0.20244],[0.144836,0.23059,0.256128,0.20244],[0.144369,0.230497,0.256128,0.202813],[0.143903,0.230403,0.256128,0.203187],[0.143436,0.23031,0.256128,0.20356],[0.143436,0.23067,0.256128,0.203187],[0.33846,0.124725,0.36888,0.2919],[0.33846,0.124725,0.36888,0.2919],[0.33846,0.124725,0.36888,0.2919],[0.33846,0.124725,0.36888,0.2919],[0.33846,0.124725,0.36888,0.2919],[0.33846,0.124725,0.36888,0.2919],[0.33846,0.124725,0.36888,0.2919],[0.33846,0.124725,0.36888,0.2919],[0.338852,0.125213,0.369963,0.291947],[0.339244,0.125702,0.371045,0.291993],[0.339636,0.12619,0.372128,0.29204],[0.341,0.126548,0.372167,0.29274],[0.342364,0.126907,0.372205,0.29344],[0.343728,0.127265,0.372244,0.29414],[0.344627,0.127753,0.372747,0.294187],[0.345525,0.128242,0.373249,0.294233],[0.346424,0.12873,0.373752,0.29428],[0.346387,0.128415,0.374293,0.294607],[0.346349,0.1281,0.374835,0.294933],[0.346312,0.127785,0.375376,0.29526],[0.346312,0.127692,0.375376,0.295633],[0.346312,0.127598,0.375376,0.296007],[0.346312,0.127505,0.375376,0.29638],[0.346312,0.127238,0.375376,0.29638],[0.346312,0.126972,0.375376,0.29638],[0.346312,0.126705,0.375376,0.29638],[0.346312,0.125893,0.375376,0.296427],[0.346312,0.125082,0.375376,0.296473],[0.346312,0.12427,0.375376,0.29652],[0.345771,0.123422,0.376459,0.296847],[0.345229,0.122573,0.377541,0.297173],[0.344688,0.121725,0.378624,0.2975],[0.344688,0.121005,0.378624,0.298247],[0.344688,0.120285,0.378624,0.298993],[0.344688,0.119565,0.378624,0.29974],[0.345117,0.119832,0.379165,0.29974],[0.345547,0.120098,0.379707,0.29974],[0.345976,0.120365,0.380248,0.29974],[0.346947,0.12127,0.379707,0.29932],[0.347917,0.122175,0.379165,0.2989],[0.348888,0.12308,0.378624,0.29848],[0.349392,0.123755,0.378083,0.29778],[0.349896,0.12443,0.377541,0.29708],[0.3504,0.125105,0.377,0.29638],[0.349896,0.124745,0.377541,0.296753],[0.349392,0.124385,0.378083,0.297127],[0.348888,0.124025,0.378624,0.2975],[0.348421,0.12371,0.378624,0.297827],[0.347955,0.123395,0.378624,0.298153],[0.347488,0.12308,0.378624,0.29848],[0.347563,0.123255,0.377541,0.29778],[0.347637,0.12343,0.376459,0.29708],[0.347712,0.123605,0.375376,0.29638],[0.347859,0.123978,0.373249,0.294887],[0.348005,0.124352,0.371123,0.293393],[0.348152,0.124725,0.368996,0.2919],[0.347293,0.125575,0.367913,0.2905],[0.346435,0.126425,0.366831,0.2891],[0.345576,0.127275,0.365748,0.2877],[0.345688,0.127995,0.364124,0.286953],[0.3458,0.128715,0.3625,0.286207],[0.345912,0.129435,0.360876,0.28546],[0.346341,0.129342,0.361417,0.285833],[0.346771,0.129248,0.361959,0.286207],[0.3472,0.129155,0.3625,0.28658],[0.346547,0.127807,0.365207,0.288773],[0.345893,0.126458,0.367913,0.290967],[0.34524,0.12511,0.37062,0.29316],[0.344231,0.124075,0.372205,0.294233],[0.343221,0.12304,0.373791,0.295307],[0.342212,0.122005,0.375376,0.29638],[0.341783,0.121738,0.374835,0.29638],[0.341353,0.121472,0.374293,0.29638],[0.340924,0.121205,0.373752,0.29638],[0.340924,0.121565,0.373752,0.296007],[0.340924,0.121925,0.373752,0.295633],[0.340924,0.122285,0.373752,0.29526],[0.340849,0.121832,0.374835,0.296007],[0.340775,0.121378,0.375917,0.296753],[0.3407,0.120925,0.377,0.2975],[0.341167,0.120832,0.377,0.297873],[0.341633,0.120738,0.377,0.298247],[0.3421,0.120645,0.377,0.29862],[0.3421,0.121005,0.377,0.298247],[0.3421,0.121365,0.377,0.297873],[0.3421,0.121725,0.377,0.2975],null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,[0.322976,0.137805,0.351248,0.27678],[0.322939,0.13763,0.351789,0.27748],[0.322901,0.137455,0.352331,0.27818],[0.322864,0.13728,0.352872,0.27888],[0.321781,0.137533,0.355037,0.28],[0.320699,0.137787,0.357203,0.28112],[0.319616,0.13804,0.359368,0.28224],[0.318103,0.13741,0.361495,0.28476],[0.316589,0.13678,0.363621,0.28728],[0.315076,0.13615,0.365748,0.2898],[0.314572,0.136057,0.366289,0.290173],[0.314068,0.135963,0.366831,0.290547],[0.313564,0.13587,0.367372,0.29092],[0.314572,0.136138,0.366289,0.289847],[0.31558,0.136407,0.365207,0.288773],[0.316588,0.136675,0.364124,0.2877],[0.316625,0.137035,0.363583,0.287327],[0.316663,0.137395,0.363041,0.286953],[0.3167,0.137755,0.3625,0.28658],[0.315225,0.137847,0.363583,0.28728],[0.313751,0.137938,0.364665,0.28798],[0.312276,0.13803,0.365748,0.28868],[0.311809,0.137843,0.365748,0.289427],[0.311343,0.137657,0.365748,0.290173],[0.310876,0.13747,0.365748,0.29092],[0.310913,0.137657,0.365207,0.290173],[0.310951,0.137843,0.364665,0.289427],[0.310988,0.13803,0.364124,0.28868],null,null,[0.126176,0.222225,0.264248,0.2079],[0.126176,0.222585,0.264248,0.207527],[0.126176,0.222945,0.264248,0.207153],[0.126176,0.223305,0.264248,0.20678],[0.126717,0.223665,0.263165,0.206407],[0.127259,0.224025,0.262083,0.206033],[0.1278,0.224385,0.261,0.20566],[0.128304,0.22506,0.260459,0.20496],[0.128808,0.225735,0.259917,0.20426],[0.129312,0.22641,0.259376,0.20356],[0.129816,0.22677,0.258835,0.203187],[0.13032,0.22713,0.258293,0.202813],[0.130824,0.22749,0.257752,0.20244],[0.131291,0.227768,0.257752,0.202393],[0.131757,0.228047,0.257752,0.202347],[0.132224,0.228325,0.257752,0.2023],[0.132691,0.227965,0.257752,0.202673],[0.133157,0.227605,0.257752,0.203047],[0.133624,0.227245,0.257752,0.20342],[0.133587,0.227245,0.258293,0.20342],[0.133549,0.227245,0.258835,0.20342],[0.133512,0.227245,0.259376,0.20342],null,null,[0.273248,0.11551,0.428504,0.33796],[0.273715,0.116043,0.428504,0.33796],[0.274181,0.116577,0.428504,0.33796],[0.274648,0.11711,0.428504,0.33796],[0.276124,0.118145,0.426919,0.336887],[0.2776,0.11918,0.425333,0.335813],[0.279076,0.120215,0.423748,0.33474],[0.280588,0.121028,0.422124,0.33362],[0.2821,0.121842,0.4205,0.3325],[0.283612,0.122655,0.418876,0.33138],[0.284583,0.123423,0.418335,0.330307],[0.285553,0.124192,0.417793,0.329233],[0.286524,0.12496,0.417252,0.32816],[0.287495,0.125053,0.416711,0.327787],[0.288465,0.125147,0.416169,0.327413],[0.289436,0.12524,0.415628,0.32704],[0.289829,0.124298,0.416208,0.32774],[0.290223,0.123357,0.416788,0.32844],[0.290616,0.122415,0.417368,0.32914],[0.290148,0.121417,0.417871,0.329933],[0.28968,0.120418,0.418373,0.330727],[0.289212,0.11942,0.418876,0.33152],[0.289212,0.118932,0.418876,0.331473],[0.289212,0.118443,0.418876,0.331427],[0.289212,0.117955,0.418876,0.33138],[0.290259,0.118583,0.416749,0.329933],[0.291305,0.119212,0.414623,0.328487],[0.292352,0.11984,0.412496,0.32704],[0.293864,0.120702,0.410872,0.325593],[0.295376,0.121563,0.409248,0.324147],[0.296888,0.122425,0.407624,0.3227],[0.297896,0.123238,0.406541,0.32158],[0.298904,0.124052,0.405459,0.32046],[0.299912,0.124865,0.404376,0.31934],[0.299875,0.124505,0.404917,0.319713],[0.299837,0.124145,0.405459,0.320087],[0.2998,0.123785,0.406,0.32046],[0.299259,0.123598,0.407083,0.321207],[0.298717,0.123412,0.408165,0.321953],[0.298176,0.123225,0.409248,0.3227],[0.2976,0.12305,0.410833,0.3234],[0.297024,0.122875,0.412419,0.3241],[0.296448,0.1227,0.414004,0.3248],[0.296877,0.122153,0.414545,0.32592],[0.297307,0.121607,0.415087,0.32704],[0.297736,0.12106,0.415628,0.32816],[0.298128,0.120873,0.416711,0.328907],[0.29852,0.120687,0.417793,0.329653],[0.298912,0.1205,0.418876,0.3304],[0.298837,0.119465,0.419959,0.331473],[0.298763,0.11843,0.421041,0.332547],[0.298688,0.117395,0.422124,0.33362],[0.298651,0.117128,0.422665,0.33362],[0.298613,0.116862,0.423207,0.33362],[0.298576,0.116595,0.423748,0.33362],[0.29908,0.116595,0.423207,0.33362],[0.299584,0.116595,0.422665,0.33362],[0.300088,0.116595,0.422124,0.33362],[0.299584,0.116862,0.422665,0.33362],[0.29908,0.117128,0.423207,0.33362],[0.298576,0.117395,0.423748,0.33362],[0.297605,0.11722,0.424289,0.33432],[0.296635,0.117045,0.424831,0.33502],[0.295664,0.11687,0.425372,0.33572],[0.295197,0.11687,0.425372,0.33572],[0.294731,0.11687,0.425372,0.33572],[0.294264,0.11687,0.425372,0.33572],[0.294301,0.117452,0.424831,0.335393],[0.294339,0.118033,0.424289,0.335067],[0.294376,0.118615,0.423748,0.33474],[0.294917,0.119068,0.422665,0.333993],[0.295459,0.119522,0.421583,0.333247],[0.296,0.119975,0.4205,0.3325],[0.296075,0.120243,0.419417,0.331427],[0.296149,0.120512,0.418335,0.330353],[0.296224,0.12078,0.417252,0.32928],[0.295795,0.120385,0.416711,0.32886],[0.295365,0.11999,0.416169,0.32844],[0.294936,0.119595,0.415628,0.32802],[0.294,0.11941,0.415667,0.327693],[0.293064,0.119225,0.415705,0.327367],[0.292128,0.11904,0.415744,0.32704],[0.292203,0.119133,0.414661,0.326667],[0.292277,0.119227,0.413579,0.326293],[0.292352,0.11932,0.412496,0.32592],[0.293397,0.120355,0.410872,0.324847],[0.294443,0.12139,0.409248,0.323773],[0.295488,0.122425,0.407624,0.3227],[0.295488,0.122958,0.407624,0.3227],[0.295488,0.123492,0.407624,0.3227],[0.295488,0.124025,0.407624,0.3227],[0.294984,0.12421,0.408165,0.323027],[0.29448,0.124395,0.408707,0.323353],[0.293976,0.12458,0.409248,0.32368],[0.294051,0.125615,0.408165,0.322607],[0.294125,0.12665,0.407083,0.321533],[0.2942,0.127685,0.406,0.32046],[0.294275,0.128672,0.404917,0.319713],[0.294349,0.129658,0.403835,0.318967],[0.294424,0.130645,0.402752,0.31822],[0.294928,0.13096,0.402211,0.317893],[0.295432,0.131275,0.401669,0.317567],[0.295936,0.13159,0.401128,0.31724],[0.296907,0.131683,0.400587,0.316867],[0.297877,0.131777,0.400045,0.316493],[0.298848,0.13187,0.399504,0.31612],[0.299315,0.131963,0.399504,0.315747],[0.299781,0.132057,0.399504,0.315373],[0.300248,0.13215,0.399504,0.315],null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,[0.30854,0.12745,0.39962,0.315],[0.309513,0.127217,0.39904,0.315],[0.310487,0.126983,0.39846,0.315],[0.31146,0.12675,0.39788,0.315],[0.312356,0.126983,0.398421,0.315],[0.313252,0.127217,0.398963,0.315],[0.314148,0.12745,0.399504,0.315],[0.313999,0.126983,0.401669,0.316867],[0.313849,0.126517,0.403835,0.318733],[0.3137,0.12605,0.406,0.3206],[0.313087,0.125513,0.408127,0.322747],[0.312473,0.124977,0.410253,0.324893],[0.31186,0.12444,0.41238,0.32704],[0.312327,0.125333,0.41238,0.326667],[0.312793,0.126227,0.41238,0.326293],[0.31326,0.12712,0.41238,0.32592],[0.314269,0.128155,0.410795,0.324847],[0.315279,0.12919,0.409209,0.323773],[0.316288,0.130225,0.407624,0.3227],[0.316288,0.130852,0.407624,0.322327],[0.316288,0.131478,0.407624,0.321953],[0.316288,0.132105,0.407624,0.32158],[0.316251,0.132278,0.408165,0.321953],[0.316213,0.132452,0.408707,0.322327],[0.316176,0.132625,0.409248,0.3227],[0.317072,0.131905,0.409789,0.323447],[0.317968,0.131185,0.410331,0.324193],[0.318864,0.130465,0.410872,0.32494],[0.321088,0.128897,0.412457,0.326013],[0.323312,0.127328,0.414043,0.327087],[0.325536,0.12576,0.415628,0.32816],[0.328228,0.124007,0.416711,0.328907],[0.33092,0.122253,0.417793,0.329653],[0.333612,0.1205,0.418876,0.3304],[0.337421,0.11984,0.417291,0.328907],[0.341231,0.11918,0.415705,0.327413],[0.34504,0.11852,0.41412,0.32592],[0.347956,0.117848,0.411955,0.324473],[0.350872,0.117177,0.409789,0.323027],[0.353788,0.116505,0.407624,0.32158],[0.352533,0.115973,0.406,0.320507],[0.351279,0.115442,0.404376,0.319433],[0.350024,0.11491,0.402752,0.31836],[0.345108,0.115237,0.400084,0.31612],[0.340192,0.115563,0.397416,0.31388],[0.335276,0.11589,0.394748,0.31164],[0.329893,0.11666,0.39208,0.309493],[0.324511,0.11743,0.389412,0.307347],[0.319128,0.1182,0.386744,0.3052],null,null]}];
}
</sheet>
diff --git a/examples/interview/swap-host.svml b/examples/interview/swap-host.svml
index 4160e276..35dc0e48 100644
--- a/examples/interview/swap-host.svml
+++ b/examples/interview/swap-host.svml
@@ -1,23 +1,24 @@
<?svml using="@hypit/markup@1"?>
<svml>
- <import as="media-track" from="@hypit/media-track@1"/>
- <import as="sound" from="@hypit/sound@1"/>
- <import as="performance" from="@hypit/performance@1"/>
+ <import as="audio" from="@hypit/audio-track@1"/>
+ <import as="visual" from="@hypit/visual-track@1"/>
<import from="@hypit/script@1"/>
<import as="text" from="@hypit/text@1"/>
<import as="media" from="@hypit/media@1"/>
<import as="seedance" from="@hypit/seedance@1"/>
<import as="gpt" from="@hypit/gpt-image@1"/>
- <import as="program" from="@hypit/program-space@1"/>
<import as="pipeline" from="@hypit/media-pipeline@1"/>
<import as="whisperx" from="@hypit/whisperx@1"/>
+ <import as="semantic" from="@hypit/narrative-temporal@1"/>
+ <import as="narrative-caption" from="@hypit/narrative-caption@1"/>
<import as="time" from="@hypit/timeline-author@1"/>
<import as="audio-track" from="@hypit/audio-track@1"/>
<import as="caption" from="@hypit/caption@1"/>
<import as="caption-fine" from="@hypit/caption-fine@1"/>
<import as="fonts" from="@hypit/fonts-open@1"/>
<import as="space" from="@hypit/spatial@1"/>
+ <import as="region" from="@hypit/region-track@1"/>
<import as="screen" from="@hypit/screen-overlay@1"/>
<import as="film" from="@hypit/film@1"/>
<import as="render" from="@hypit/render-hyperframes@1"/>
@@ -156,11 +157,9 @@
</seedance:ReferenceVideo>
<space:Canvas id="vertical" width="720" height="1280"/>
- <space:RegionTimeline id="wojak-heads" within={vertical}
- recipe={wojak-tracking.heads.wojak}/>
- <space:Frame id="full-frame" within={vertical}
+ <space:Frame id="full-frame" within={vertical.bounds}
left="0%" top="0%" right="100%" bottom="100%"/>
- <program:Clock id="clock" frame-rate="30"/>
+ <time:Clock id="clock" frame-rate="30"/>
<pipeline:Normalize id="soundtrack-media" source={soundtrack}
video="none" audio="default" span-authority="audio" clock={clock}/>
@@ -174,40 +173,51 @@
<pipeline:Normalize id="bitcoin-rule-media" source={bitcoin-rule-take.video}
video="primary-moving" audio="default" span-authority="video" clock={clock}/>
- <whisperx:SemanticTake id="manifest-rule-semantic" narrative={story}
- segment={story.segment.manifest-rule} media={manifest-rule-media.media} language="en"/>
- <whisperx:SemanticTake id="real-estate-rule-semantic" narrative={story}
- segment={story.segment.real-estate-rule} media={real-estate-rule-media.media} language="en"/>
- <whisperx:SemanticTake id="bitcoin-rule-semantic" narrative={story}
- segment={story.segment.bitcoin-rule} media={bitcoin-rule-media.media} language="en"/>
-
- <time:Timeline id="speech" clock={clock}>
- <time:Take source={manifest-rule-semantic.take}/>
- <time:Take source={real-estate-rule-semantic.take}/>
- <time:Take source={bitcoin-rule-semantic.take}/>
+ <whisperx:Alignment id="manifest-rule-semantic" narrative={story}
+ segment={story.segment.manifest-rule} media={manifest-rule-media.media} domain={manifest-rule-media.domain} language="en"/>
+ <whisperx:Alignment id="real-estate-rule-semantic" narrative={story}
+ segment={story.segment.real-estate-rule} media={real-estate-rule-media.media} domain={real-estate-rule-media.domain} language="en"/>
+ <whisperx:Alignment id="bitcoin-rule-semantic" narrative={story}
+ segment={story.segment.bitcoin-rule} media={bitcoin-rule-media.media} domain={bitcoin-rule-media.domain} language="en"/>
+
+ <time:Timeline id="speech" clock={clock} end="bitcoin-rule-semantic.end">
+ <time:Window id="manifest-rule-semantic" from="start" for={manifest-rule-media.extent}/>
+ <time:Window id="real-estate-rule-semantic" from="manifest-rule-semantic.end" for={real-estate-rule-media.extent}/>
+ <time:Window id="bitcoin-rule-semantic" from="real-estate-rule-semantic.end" for={bitcoin-rule-media.extent}/>
</time:Timeline>
- <sound:Style id="speech-sound-style"/>
- <sound:Track id="speech-sound" timeline={speech.timeline}>
- <sound:Use style={speech-sound-style}/>
- </sound:Track>
- <performance:Style id="speech-picture-style" frame={full-frame} appearance={recipes.media.performance}/>
- <performance:Track id="speech-picture" timeline={speech.timeline} canvas={vertical}>
- <performance:Use style={speech-picture-style} during="program"/>
- </performance:Track>
+
+ <semantic:Projection id="story-time" narrative={story} timeline={speech.timeline}>
+ <semantic:Map alignment={manifest-rule-semantic.alignment} domain={manifest-rule-media.domain} window={speech.manifest-rule-semantic}/>
+ <semantic:Map alignment={real-estate-rule-semantic.alignment} domain={real-estate-rule-media.domain} window={speech.real-estate-rule-semantic}/>
+ <semantic:Map alignment={bitcoin-rule-semantic.alignment} domain={bitcoin-rule-media.domain} window={speech.bitcoin-rule-semantic}/>
+ <semantic:Instant id="moment-manifest-cue" moment={story.moment.manifest}/>
+ <semantic:Instant id="moment-real-estate-cue" moment={story.moment.real-estate}/>
+ <semantic:Instant id="moment-bitcoin-cue" moment={story.moment.bitcoin}/>
+ </semantic:Projection>
+
+ <region:Track id="wojak-heads" within={vertical.bounds} timeline={speech.timeline}
+ recipe={wojak-tracking.heads.wojak}/>
+ <audio:Track id="speech-sound" timeline={speech.timeline}>
+ <audio:Clip id="manifest-rule-semantic-source" source={manifest-rule-media.media} during={speech.manifest-rule-semantic}/>
+ <audio:Clip id="real-estate-rule-semantic-source" source={real-estate-rule-media.media} during={speech.real-estate-rule-semantic}/>
+ <audio:Clip id="bitcoin-rule-semantic-source" source={bitcoin-rule-media.media} during={speech.bitcoin-rule-semantic}/>
+ </audio:Track>
+ <visual:Track id="speech-picture" timeline={speech.timeline}>
+ <visual:Clip id="manifest-rule-semantic-source" media={manifest-rule-media.media} during={speech.manifest-rule-semantic} frame={full-frame} z="10" fit="cover"/>
+ <visual:Clip id="real-estate-rule-semantic-source" media={real-estate-rule-media.media} during={speech.real-estate-rule-semantic} frame={full-frame} z="10" fit="cover"/>
+ <visual:Clip id="bitcoin-rule-semantic-source" media={bitcoin-rule-media.media} during={speech.bitcoin-rule-semantic} frame={full-frame} z="10" fit="cover"/>
+ </visual:Track>
<audio-track:Track id="music-bed" timeline={speech.timeline}>
- <audio-track:Item source={soundtrack-media.media} during="program"
- playback="once-start" gain="0.12" fade-in="300ms" fade-out="600ms"/>
+ <audio-track:Clip source={soundtrack-media.media} during="timeline"
+ gain="0.12" fade-in="300ms" fade-out="600ms"/>
</audio-track:Track>
<audio-track:Track id="rule-reveal-sfx" timeline={speech.timeline}>
- <audio-track:Item id="manifest-reveal-sfx" source={rule-reveal-sound-media.media}
- at={story.moment.manifest} for="20f" playback="once-start" gain="0.20"/>
- <audio-track:Item id="real-estate-reveal-sfx" source={rule-reveal-sound-media.media}
- at={story.moment.real-estate} for="20f" playback="once-start" gain="0.20"/>
- <audio-track:Item id="bitcoin-reveal-sfx" source={rule-reveal-sound-media.media}
- at={story.moment.bitcoin} for="20f" playback="once-start" gain="0.20"/>
+ <audio-track:Clip id="manifest-reveal-sfx" source={rule-reveal-sound-media.media} from={story-time.moment-manifest-cue} for="20f" gain="0.20"/>
+ <audio-track:Clip id="real-estate-reveal-sfx" source={rule-reveal-sound-media.media} from={story-time.moment-real-estate-cue} for="20f" gain="0.20"/>
+ <audio-track:Clip id="bitcoin-reveal-sfx" source={rule-reveal-sound-media.media} from={story-time.moment-bitcoin-cue} for="20f" gain="0.20"/>
</audio-track:Track>
<fonts:Stack id="caption-font" family="league-spartan" weight="900" style="normal"/>
@@ -216,36 +226,37 @@
<caption-fine:Style id="caption-wojak-style" recipe={recipes.caption.wojak}
font={caption-font}/>
- <caption-fine:Track id="captions" document={story.caption}
- timeline={speech.timeline} regions={wojak-heads}>
+ <narrative-caption:Timing id="caption-timing" document={story.caption} binding={story.caption-binding} projection={story-time.projection}/>
+ <caption-fine:Caption id="captions" document={story.caption} timing={caption-timing}
+ timeline={speech.timeline} within={vertical.bounds} regions={wojak-heads}>
<caption-fine:Use style={caption-chad-style}/>
<caption-fine:Use role="WOJAK" style={caption-wojak-style}/>
- </caption-fine:Track>
+ </caption-fine:Caption>
<emoji:Style id="rule-reveal-style" recipe={recipes.emoji.strip}/>
- <emoji:Track id="rule-reveal" timeline={speech.timeline} canvas={vertical}
- style={rule-reveal-style} placeholder={rule-placeholder.image} during="program">
- <emoji:Item id="manifest" icon={manifest-icon.image} at={story.moment.manifest}/>
- <emoji:Item id="real-estate" icon={real-estate-icon.image} at={story.moment.real-estate}/>
- <emoji:Item id="bitcoin" icon={bitcoin-icon.image} at={story.moment.bitcoin}/>
- </emoji:Track>
-
- <screen:Track id="rule-reveal-flashes" timeline={speech.timeline} canvas={vertical}>
- <screen:Flash id="manifest-flash" at={story.moment.manifest} for="8f" z="80"
+ <emoji:EmojiReveal id="rule-reveal" timeline={speech.timeline} within={vertical.bounds}
+ style={rule-reveal-style} placeholder={rule-placeholder.image} during="timeline">
+ <emoji:Item id="manifest" icon={manifest-icon.image} at={story-time.moment-manifest-cue}/>
+ <emoji:Item id="real-estate" icon={real-estate-icon.image} at={story-time.moment-real-estate-cue}/>
+ <emoji:Item id="bitcoin" icon={bitcoin-icon.image} at={story-time.moment-bitcoin-cue}/>
+ </emoji:EmojiReveal>
+
+ <screen:Track id="rule-reveal-flashes" timeline={speech.timeline} within={vertical.bounds}>
+ <screen:Flash id="manifest-flash" from={story-time.moment-manifest-cue} for="8f" z="80"
color="#FF4D6D" intensity="0.28" attack="2" hold="1" decay="5"/>
- <screen:Flash id="real-estate-flash" at={story.moment.real-estate} for="8f" z="80"
+ <screen:Flash id="real-estate-flash" from={story-time.moment-real-estate-cue} for="8f" z="80"
color="#14A68A" intensity="0.28" attack="2" hold="1" decay="5"/>
- <screen:Flash id="bitcoin-flash" at={story.moment.bitcoin} for="8f" z="80"
+ <screen:Flash id="bitcoin-flash" from={story-time.moment-bitcoin-cue} for="8f" z="80"
color="#F59E0B" intensity="0.28" attack="2" hold="1" decay="5"/>
</screen:Track>
- <film:Film id="main" canvas={vertical} timeline={speech.timeline}
+ <film:Film id="main" canvas={vertical.canvas} timeline={speech.timeline}
appearance={recipes.film.vertical}>
<film:Track source={speech-picture.visual}/>
<film:Track source={speech-sound.audio}/>
- <film:Track source={captions.track}/>
- <film:Track source={rule-reveal.track}/>
- <film:Track source={rule-reveal-flashes.track}/>
+ <film:Track source={captions.visual}/>
+ <film:Track source={rule-reveal.visual}/>
+ <film:Track source={rule-reveal-flashes.visual}/>
<film:Track source={music-bed.audio}/>
<film:Track source={rule-reveal-sfx.audio}/>
</film:Film>
diff --git a/examples/interview/swap-lang.svml b/examples/interview/swap-lang.svml
index df7c8bac..596a6dbc 100644
--- a/examples/interview/swap-lang.svml
+++ b/examples/interview/swap-lang.svml
@@ -1,24 +1,25 @@
<?svml using="@hypit/markup@1"?>
<svml>
- <import as="media-track" from="@hypit/media-track@1"/>
- <import as="sound" from="@hypit/sound@1"/>
- <import as="performance" from="@hypit/performance@1"/>
+ <import as="audio" from="@hypit/audio-track@1"/>
+ <import as="visual" from="@hypit/visual-track@1"/>
<import from="@hypit/script@1"/>
<import as="text" from="@hypit/text@1"/>
<import as="media" from="@hypit/media@1"/>
<import as="seedance" from="@hypit/seedance@1"/>
<import as="gpt" from="@hypit/gpt-image@1"/>
- <import as="program" from="@hypit/program-space@1"/>
<import as="pipeline" from="@hypit/media-pipeline@1"/>
<import as="whisperx" from="@hypit/whisperx@1"/>
- <import as="adjust" from="@hypit/semantic-take-adjust@1"/>
+ <import as="semantic" from="@hypit/narrative-temporal@1"/>
+ <import as="narrative-caption" from="@hypit/narrative-caption@1"/>
+ <import as="adjust" from="@hypit/narrative-alignment-adjust@1"/>
<import as="time" from="@hypit/timeline-author@1"/>
<import as="audio-track" from="@hypit/audio-track@1"/>
<import as="caption" from="@hypit/caption@1"/>
<import as="caption-fine" from="@hypit/caption-fine@1"/>
<import as="fonts" from="@hypit/fonts-open@1"/>
<import as="space" from="@hypit/spatial@1"/>
+ <import as="region" from="@hypit/region-track@1"/>
<import as="screen" from="@hypit/screen-overlay@1"/>
<import as="film" from="@hypit/film@1"/>
<import as="render" from="@hypit/render-hyperframes@1"/>
@@ -156,11 +157,9 @@
</seedance:ReferenceVideo>
<space:Canvas id="vertical" width="720" height="1280"/>
- <space:RegionTimeline id="wife-heads" within={vertical}
- recipe={tracking.heads.wife}/>
- <space:Frame id="full-frame" within={vertical}
+ <space:Frame id="full-frame" within={vertical.bounds}
left="0%" top="0%" right="100%" bottom="100%"/>
- <program:Clock id="clock" frame-rate="30"/>
+ <time:Clock id="clock" frame-rate="30"/>
<pipeline:Normalize id="soundtrack-media" source={soundtrack}
video="none" audio="default" span-authority="audio" clock={clock}/>
@@ -174,44 +173,56 @@
<pipeline:Normalize id="bitcoin-rule-media" source={bitcoin-rule-take.video}
video="primary-moving" audio="default" span-authority="video" clock={clock}/>
- <whisperx:SemanticTake id="manifest-rule-semantic" narrative={story}
- segment={story.segment.manifest-rule} media={manifest-rule-media.media} language="es"/>
- <whisperx:SemanticTake id="real-estate-rule-semantic" narrative={story}
- segment={story.segment.real-estate-rule} media={real-estate-rule-media.media} language="es"/>
- <whisperx:SemanticTake id="bitcoin-rule-semantic" narrative={story}
- segment={story.segment.bitcoin-rule} media={bitcoin-rule-media.media} language="es"/>
+ <whisperx:Alignment id="manifest-rule-semantic" narrative={story}
+ segment={story.segment.manifest-rule} media={manifest-rule-media.media} domain={manifest-rule-media.domain} language="es"/>
+ <whisperx:Alignment id="real-estate-rule-semantic" narrative={story}
+ segment={story.segment.real-estate-rule} media={real-estate-rule-media.media} domain={real-estate-rule-media.domain} language="es"/>
+ <whisperx:Alignment id="bitcoin-rule-semantic" narrative={story}
+ segment={story.segment.bitcoin-rule} media={bitcoin-rule-media.media} domain={bitcoin-rule-media.domain} language="es"/>
- <adjust:SemanticTake id="manifest-rule-corrected" source={manifest-rule-semantic.take}>
- <adjust:Anchor at={story.moment.aja} frame="63"/>
- </adjust:SemanticTake>
+ <adjust:NarrativeAlignment id="manifest-rule-corrected"
+ source={manifest-rule-semantic.alignment} domain={manifest-rule-media.domain}>
+ <adjust:Boundary at={story.moment.aja} frame="63"/>
+ </adjust:NarrativeAlignment>
- <time:Timeline id="speech" clock={clock}>
- <time:Take source={manifest-rule-corrected.take}/>
- <time:Take source={real-estate-rule-semantic.take}/>
- <time:Take source={bitcoin-rule-semantic.take}/>
+ <time:Timeline id="speech" clock={clock} end="bitcoin-rule-semantic.end">
+ <time:Window id="manifest-rule-corrected" from="start" for={manifest-rule-media.extent}/>
+ <time:Window id="real-estate-rule-semantic" from="manifest-rule-corrected.end" for={real-estate-rule-media.extent}/>
+ <time:Window id="bitcoin-rule-semantic" from="real-estate-rule-semantic.end" for={bitcoin-rule-media.extent}/>
</time:Timeline>
- <sound:Style id="speech-sound-style"/>
- <sound:Track id="speech-sound" timeline={speech.timeline}>
- <sound:Use style={speech-sound-style}/>
- </sound:Track>
- <performance:Style id="speech-picture-style" frame={full-frame} appearance={recipes.media.performance}/>
- <performance:Track id="speech-picture" timeline={speech.timeline} canvas={vertical}>
- <performance:Use style={speech-picture-style} during="program"/>
- </performance:Track>
+
+ <semantic:Projection id="story-time" narrative={story} timeline={speech.timeline}>
+ <semantic:Map alignment={manifest-rule-corrected.alignment} domain={manifest-rule-media.domain} window={speech.manifest-rule-corrected}/>
+ <semantic:Map alignment={real-estate-rule-semantic.alignment} domain={real-estate-rule-media.domain} window={speech.real-estate-rule-semantic}/>
+ <semantic:Map alignment={bitcoin-rule-semantic.alignment} domain={bitcoin-rule-media.domain} window={speech.bitcoin-rule-semantic}/>
+ <semantic:Instant id="moment-manifest-cue" moment={story.moment.manifest}/>
+ <semantic:Instant id="moment-real-estate-cue" moment={story.moment.real-estate}/>
+ <semantic:Instant id="moment-bitcoin-cue" moment={story.moment.bitcoin}/>
+ </semantic:Projection>
+
+ <region:Track id="wife-heads" within={vertical.bounds} timeline={speech.timeline}
+ recipe={tracking.heads.wife}/>
+ <audio:Track id="speech-sound" timeline={speech.timeline}>
+ <audio:Clip id="manifest-rule-source" source={manifest-rule-media.media} during={speech.manifest-rule-corrected}/>
+ <audio:Clip id="real-estate-rule-source" source={real-estate-rule-media.media} during={speech.real-estate-rule-semantic}/>
+ <audio:Clip id="bitcoin-rule-source" source={bitcoin-rule-media.media} during={speech.bitcoin-rule-semantic}/>
+ </audio:Track>
+ <visual:Track id="speech-picture" timeline={speech.timeline}>
+ <visual:Clip id="manifest-rule-source" media={manifest-rule-media.media} during={speech.manifest-rule-corrected} frame={full-frame} z="10" fit="cover"/>
+ <visual:Clip id="real-estate-rule-source" media={real-estate-rule-media.media} during={speech.real-estate-rule-semantic} frame={full-frame} z="10" fit="cover"/>
+ <visual:Clip id="bitcoin-rule-source" media={bitcoin-rule-media.media} during={speech.bitcoin-rule-semantic} frame={full-frame} z="10" fit="cover"/>
+ </visual:Track>
<audio-track:Track id="music-bed" timeline={speech.timeline}>
- <audio-track:Item source={soundtrack-media.media} during="program"
- playback="once-start" gain="0.12" fade-in="300ms" fade-out="600ms"/>
+ <audio-track:Clip source={soundtrack-media.media} during="timeline"
+ gain="0.12" fade-in="300ms" fade-out="600ms"/>
</audio-track:Track>
<audio-track:Track id="rule-reveal-sfx" timeline={speech.timeline}>
- <audio-track:Item id="manifest-reveal-sfx" source={rule-reveal-sound-media.media}
- at={story.moment.manifest} for="20f" playback="once-start" gain="0.20"/>
- <audio-track:Item id="real-estate-reveal-sfx" source={rule-reveal-sound-media.media}
- at={story.moment.real-estate} for="20f" playback="once-start" gain="0.20"/>
- <audio-track:Item id="bitcoin-reveal-sfx" source={rule-reveal-sound-media.media}
- at={story.moment.bitcoin} for="20f" playback="once-start" gain="0.20"/>
+ <audio-track:Clip id="manifest-reveal-sfx" source={rule-reveal-sound-media.media} from={story-time.moment-manifest-cue} for="20f" gain="0.20"/>
+ <audio-track:Clip id="real-estate-reveal-sfx" source={rule-reveal-sound-media.media} from={story-time.moment-real-estate-cue} for="20f" gain="0.20"/>
+ <audio-track:Clip id="bitcoin-reveal-sfx" source={rule-reveal-sound-media.media} from={story-time.moment-bitcoin-cue} for="20f" gain="0.20"/>
</audio-track:Track>
<fonts:Stack id="caption-font" family="league-spartan" weight="900" style="normal"/>
@@ -220,36 +231,37 @@
<caption-fine:Style id="caption-wife-style" recipe={recipes.caption.wife}
font={caption-font}/>
- <caption-fine:Track id="captions" document={story.caption}
- timeline={speech.timeline} regions={wife-heads}>
+ <narrative-caption:Timing id="caption-timing" document={story.caption} binding={story.caption-binding} projection={story-time.projection}/>
+ <caption-fine:Caption id="captions" document={story.caption} timing={caption-timing}
+ timeline={speech.timeline} within={vertical.bounds} regions={wife-heads}>
<caption-fine:Use style={caption-boy-style}/>
<caption-fine:Use role="WIFE" style={caption-wife-style}/>
- </caption-fine:Track>
+ </caption-fine:Caption>
<emoji:Style id="rule-reveal-style" recipe={recipes.emoji.strip}/>
- <emoji:Track id="rule-reveal" timeline={speech.timeline} canvas={vertical}
- style={rule-reveal-style} placeholder={rule-placeholder.image} during="program">
- <emoji:Item id="manifest" icon={manifest-icon.image} at={story.moment.manifest}/>
- <emoji:Item id="real-estate" icon={real-estate-icon.image} at={story.moment.real-estate}/>
- <emoji:Item id="bitcoin" icon={bitcoin-icon.image} at={story.moment.bitcoin}/>
- </emoji:Track>
+ <emoji:EmojiReveal id="rule-reveal" timeline={speech.timeline} within={vertical.bounds}
+ style={rule-reveal-style} placeholder={rule-placeholder.image} during="timeline">
+ <emoji:Item id="manifest" icon={manifest-icon.image} at={story-time.moment-manifest-cue}/>
+ <emoji:Item id="real-estate" icon={real-estate-icon.image} at={story-time.moment-real-estate-cue}/>
+ <emoji:Item id="bitcoin" icon={bitcoin-icon.image} at={story-time.moment-bitcoin-cue}/>
+ </emoji:EmojiReveal>
- <screen:Track id="rule-reveal-flashes" timeline={speech.timeline} canvas={vertical}>
- <screen:Flash id="manifest-flash" at={story.moment.manifest} for="8f" z="80"
+ <screen:Track id="rule-reveal-flashes" timeline={speech.timeline} within={vertical.bounds}>
+ <screen:Flash id="manifest-flash" from={story-time.moment-manifest-cue} for="8f" z="80"
color="#FF4D6D" intensity="0.28" attack="2" hold="1" decay="5"/>
- <screen:Flash id="real-estate-flash" at={story.moment.real-estate} for="8f" z="80"
+ <screen:Flash id="real-estate-flash" from={story-time.moment-real-estate-cue} for="8f" z="80"
color="#14A68A" intensity="0.28" attack="2" hold="1" decay="5"/>
- <screen:Flash id="bitcoin-flash" at={story.moment.bitcoin} for="8f" z="80"
+ <screen:Flash id="bitcoin-flash" from={story-time.moment-bitcoin-cue} for="8f" z="80"
color="#F59E0B" intensity="0.28" attack="2" hold="1" decay="5"/>
</screen:Track>
- <film:Film id="main" canvas={vertical} timeline={speech.timeline}
+ <film:Film id="main" canvas={vertical.canvas} timeline={speech.timeline}
appearance={recipes.film.vertical}>
<film:Track source={speech-picture.visual}/>
<film:Track source={speech-sound.audio}/>
- <film:Track source={captions.track}/>
- <film:Track source={rule-reveal.track}/>
- <film:Track source={rule-reveal-flashes.track}/>
+ <film:Track source={captions.visual}/>
+ <film:Track source={rule-reveal.visual}/>
+ <film:Track source={rule-reveal-flashes.visual}/>
<film:Track source={music-bed.audio}/>
<film:Track source={rule-reveal-sfx.audio}/>
</film:Film>
diff --git a/examples/interview/swap-ride.svml b/examples/interview/swap-ride.svml
index 5d3485bd..c9252ce9 100644
--- a/examples/interview/swap-ride.svml
+++ b/examples/interview/swap-ride.svml
@@ -1,23 +1,24 @@
<?svml using="@hypit/markup@1"?>
<svml>
- <import as="media-track" from="@hypit/media-track@1"/>
- <import as="sound" from="@hypit/sound@1"/>
- <import as="performance" from="@hypit/performance@1"/>
+ <import as="audio" from="@hypit/audio-track@1"/>
+ <import as="visual" from="@hypit/visual-track@1"/>
<import from="@hypit/script@1"/>
<import as="text" from="@hypit/text@1"/>
<import as="media" from="@hypit/media@1"/>
<import as="seedance" from="@hypit/seedance@1"/>
<import as="gpt" from="@hypit/gpt-image@1"/>
- <import as="program" from="@hypit/program-space@1"/>
<import as="pipeline" from="@hypit/media-pipeline@1"/>
<import as="whisperx" from="@hypit/whisperx@1"/>
+ <import as="semantic" from="@hypit/narrative-temporal@1"/>
+ <import as="narrative-caption" from="@hypit/narrative-caption@1"/>
<import as="time" from="@hypit/timeline-author@1"/>
<import as="audio-track" from="@hypit/audio-track@1"/>
<import as="caption" from="@hypit/caption@1"/>
<import as="caption-fine" from="@hypit/caption-fine@1"/>
<import as="fonts" from="@hypit/fonts-open@1"/>
<import as="space" from="@hypit/spatial@1"/>
+ <import as="region" from="@hypit/region-track@1"/>
<import as="screen" from="@hypit/screen-overlay@1"/>
<import as="film" from="@hypit/film@1"/>
<import as="render" from="@hypit/render-hyperframes@1"/>
@@ -163,9 +164,9 @@
</seedance:ReferenceVideo>
<space:Canvas id="vertical" width="720" height="1280"/>
- <space:Frame id="full-frame" within={vertical}
+ <space:Frame id="full-frame" within={vertical.bounds}
left="0%" top="0%" right="100%" bottom="100%"/>
- <program:Clock id="clock" frame-rate="30"/>
+ <time:Clock id="clock" frame-rate="30"/>
<pipeline:Normalize id="soundtrack-media" source={soundtrack}
video="none" audio="default" span-authority="audio" clock={clock}/>
@@ -179,40 +180,48 @@
<pipeline:Normalize id="first-place-rule-media" source={first-place-rule-take.video}
video="primary-moving" audio="default" span-authority="video" clock={clock}/>
- <whisperx:SemanticTake id="uber-rule-semantic" narrative={story}
- segment={story.segment.uber-rule} media={uber-rule-media.media} language="en"/>
- <whisperx:SemanticTake id="shortcuts-rule-semantic" narrative={story}
- segment={story.segment.shortcuts-rule} media={shortcuts-rule-media.media} language="en"/>
- <whisperx:SemanticTake id="first-place-rule-semantic" narrative={story}
- segment={story.segment.first-place-rule} media={first-place-rule-media.media} language="en"/>
+ <whisperx:Alignment id="uber-rule-semantic" narrative={story}
+ segment={story.segment.uber-rule} media={uber-rule-media.media} domain={uber-rule-media.domain} language="en"/>
+ <whisperx:Alignment id="shortcuts-rule-semantic" narrative={story}
+ segment={story.segment.shortcuts-rule} media={shortcuts-rule-media.media} domain={shortcuts-rule-media.domain} language="en"/>
+ <whisperx:Alignment id="first-place-rule-semantic" narrative={story}
+ segment={story.segment.first-place-rule} media={first-place-rule-media.media} domain={first-place-rule-media.domain} language="en"/>
- <time:Timeline id="speech" clock={clock}>
- <time:Take source={uber-rule-semantic.take}/>
- <time:Take source={shortcuts-rule-semantic.take}/>
- <time:Take source={first-place-rule-semantic.take}/>
+ <time:Timeline id="speech" clock={clock} end="first-place-rule-semantic.end">
+ <time:Window id="uber-rule-semantic" from="start" for={uber-rule-media.extent}/>
+ <time:Window id="shortcuts-rule-semantic" from="uber-rule-semantic.end" for={shortcuts-rule-media.extent}/>
+ <time:Window id="first-place-rule-semantic" from="shortcuts-rule-semantic.end" for={first-place-rule-media.extent}/>
</time:Timeline>
- <sound:Style id="speech-sound-style"/>
- <sound:Track id="speech-sound" timeline={speech.timeline}>
- <sound:Use style={speech-sound-style}/>
- </sound:Track>
- <performance:Style id="speech-picture-style" frame={full-frame} appearance={recipes.media.performance}/>
- <performance:Track id="speech-picture" timeline={speech.timeline} canvas={vertical}>
- <performance:Use style={speech-picture-style} during="program"/>
- </performance:Track>
+
+ <semantic:Projection id="story-time" narrative={story} timeline={speech.timeline}>
+ <semantic:Map alignment={uber-rule-semantic.alignment} domain={uber-rule-media.domain} window={speech.uber-rule-semantic}/>
+ <semantic:Map alignment={shortcuts-rule-semantic.alignment} domain={shortcuts-rule-media.domain} window={speech.shortcuts-rule-semantic}/>
+ <semantic:Map alignment={first-place-rule-semantic.alignment} domain={first-place-rule-media.domain} window={speech.first-place-rule-semantic}/>
+ <semantic:Instant id="moment-uber-cue" moment={story.moment.uber}/>
+ <semantic:Instant id="moment-shortcuts-cue" moment={story.moment.shortcuts}/>
+ <semantic:Instant id="moment-first-place-cue" moment={story.moment.first-place}/>
+ </semantic:Projection>
+ <audio:Track id="speech-sound" timeline={speech.timeline}>
+ <audio:Clip id="uber-rule-semantic-source" source={uber-rule-media.media} during={speech.uber-rule-semantic}/>
+ <audio:Clip id="shortcuts-rule-semantic-source" source={shortcuts-rule-media.media} during={speech.shortcuts-rule-semantic}/>
+ <audio:Clip id="first-place-rule-semantic-source" source={first-place-rule-media.media} during={speech.first-place-rule-semantic}/>
+ </audio:Track>
+ <visual:Track id="speech-picture" timeline={speech.timeline}>
+ <visual:Clip id="uber-rule-semantic-source" media={uber-rule-media.media} during={speech.uber-rule-semantic} frame={full-frame} z="10" fit="cover"/>
+ <visual:Clip id="shortcuts-rule-semantic-source" media={shortcuts-rule-media.media} during={speech.shortcuts-rule-semantic} frame={full-frame} z="10" fit="cover"/>
+ <visual:Clip id="first-place-rule-semantic-source" media={first-place-rule-media.media} during={speech.first-place-rule-semantic} frame={full-frame} z="10" fit="cover"/>
+ </visual:Track>
<audio-track:Track id="music-bed" timeline={speech.timeline}>
- <audio-track:Item source={soundtrack-media.media} during="program"
- playback="once-start" gain="0.12" fade-in="300ms" fade-out="600ms"/>
+ <audio-track:Clip source={soundtrack-media.media} during="timeline"
+ gain="0.12" fade-in="300ms" fade-out="600ms"/>
</audio-track:Track>
<audio-track:Track id="rule-reveal-sfx" timeline={speech.timeline}>
- <audio-track:Item id="uber-reveal-sfx" source={rule-reveal-sound-media.media}
- at={story.moment.uber} for="20f" playback="once-start" gain="0.20"/>
- <audio-track:Item id="shortcuts-reveal-sfx" source={rule-reveal-sound-media.media}
- at={story.moment.shortcuts} for="20f" playback="once-start" gain="0.20"/>
- <audio-track:Item id="first-place-reveal-sfx" source={rule-reveal-sound-media.media}
- at={story.moment.first-place} for="20f" playback="once-start" gain="0.20"/>
+ <audio-track:Clip id="uber-reveal-sfx" source={rule-reveal-sound-media.media} from={story-time.moment-uber-cue} for="20f" gain="0.20"/>
+ <audio-track:Clip id="shortcuts-reveal-sfx" source={rule-reveal-sound-media.media} from={story-time.moment-shortcuts-cue} for="20f" gain="0.20"/>
+ <audio-track:Clip id="first-place-reveal-sfx" source={rule-reveal-sound-media.media} from={story-time.moment-first-place-cue} for="20f" gain="0.20"/>
</audio-track:Track>
<fonts:Stack id="caption-font" family="league-spartan" weight="900" style="normal"/>
@@ -221,38 +230,39 @@
<caption-fine:Style id="caption-ada-style" recipe={recipes.caption.ada}
font={caption-font}/>
- <space:RegionTimeline id="ada-heads" within={vertical}
+ <region:Track id="ada-heads" within={vertical.bounds} timeline={speech.timeline}
recipe={tracking.heads.ada}/>
- <caption-fine:Track id="captions" document={story.caption}
- timeline={speech.timeline} regions={ada-heads}>
+ <narrative-caption:Timing id="caption-timing" document={story.caption} binding={story.caption-binding} projection={story-time.projection}/>
+ <caption-fine:Caption id="captions" document={story.caption} timing={caption-timing}
+ timeline={speech.timeline} within={vertical.bounds} regions={ada-heads}>
<caption-fine:Use style={caption-leon-style}/>
<caption-fine:Use role="ADA" style={caption-ada-style}/>
- </caption-fine:Track>
+ </caption-fine:Caption>
<emoji:Style id="rule-reveal-style" recipe={recipes.emoji.strip}/>
- <emoji:Track id="rule-reveal" timeline={speech.timeline} canvas={vertical}
- style={rule-reveal-style} placeholder={rule-placeholder.image} during="program">
- <emoji:Item id="uber" icon={uber-icon.image} at={story.moment.uber}/>
- <emoji:Item id="shortcuts" icon={shortcuts-icon.image} at={story.moment.shortcuts}/>
- <emoji:Item id="first-place" icon={first-place-icon.image} at={story.moment.first-place}/>
- </emoji:Track>
+ <emoji:EmojiReveal id="rule-reveal" timeline={speech.timeline} within={vertical.bounds}
+ style={rule-reveal-style} placeholder={rule-placeholder.image} during="timeline">
+ <emoji:Item id="uber" icon={uber-icon.image} at={story-time.moment-uber-cue}/>
+ <emoji:Item id="shortcuts" icon={shortcuts-icon.image} at={story-time.moment-shortcuts-cue}/>
+ <emoji:Item id="first-place" icon={first-place-icon.image} at={story-time.moment-first-place-cue}/>
+ </emoji:EmojiReveal>
- <screen:Track id="rule-reveal-flashes" timeline={speech.timeline} canvas={vertical}>
- <screen:Flash id="uber-flash" at={story.moment.uber} for="8f" z="80"
+ <screen:Track id="rule-reveal-flashes" timeline={speech.timeline} within={vertical.bounds}>
+ <screen:Flash id="uber-flash" from={story-time.moment-uber-cue} for="8f" z="80"
color="#2A9DFF" intensity="0.28" attack="2" hold="1" decay="5"/>
- <screen:Flash id="shortcuts-flash" at={story.moment.shortcuts} for="8f" z="80"
+ <screen:Flash id="shortcuts-flash" from={story-time.moment-shortcuts-cue} for="8f" z="80"
color="#A855F7" intensity="0.28" attack="2" hold="1" decay="5"/>
- <screen:Flash id="first-place-flash" at={story.moment.first-place} for="8f" z="80"
+ <screen:Flash id="first-place-flash" from={story-time.moment-first-place-cue} for="8f" z="80"
color="#F2B832" intensity="0.28" attack="2" hold="1" decay="5"/>
</screen:Track>
- <film:Film id="main" canvas={vertical} timeline={speech.timeline}
+ <film:Film id="main" canvas={vertical.canvas} timeline={speech.timeline}
appearance={recipes.film.vertical}>
<film:Track source={speech-picture.visual}/>
<film:Track source={speech-sound.audio}/>
- <film:Track source={captions.track}/>
- <film:Track source={rule-reveal.track}/>
- <film:Track source={rule-reveal-flashes.track}/>
+ <film:Track source={captions.visual}/>
+ <film:Track source={rule-reveal.visual}/>
+ <film:Track source={rule-reveal-flashes.visual}/>
<film:Track source={music-bed.audio}/>
<film:Track source={rule-reveal-sfx.audio}/>
</film:Film>
diff --git a/examples/interview/tracking.svs b/examples/interview/tracking.svs
index 087daa46..032484ce 100644
--- a/examples/interview/tracking.svs
+++ b/examples/interview/tracking.svs
@@ -1,8 +1,7 @@
<?svml using="@hypit/svs@1"?>
<sheet version="1">
heads.wife {
- frame-count: 783;
- tracks: [{"id":"WIFE","regions":[[0.119388,0.25276,0.262624,0.20776],[0.118884,0.252667,0.263165,0.208133],[0.11838,0.252573,0.263707,0.208507],[0.117876,0.25248,0.264248,0.20888],[0.117372,0.252747,0.264789,0.20888],[0.116868,0.253013,0.265331,0.20888],[0.116364,0.25328,0.265872,0.20888],[0.116868,0.253502,0.265331,0.208927],[0.117372,0.253723,0.264789,0.208973],[0.117876,0.253945,0.264248,0.20902],[0.118343,0.254223,0.264248,0.208973],[0.118809,0.254502,0.264248,0.208927],[0.119276,0.25478,0.264248,0.20888],[0.120713,0.254107,0.263707,0.208507],[0.122151,0.253433,0.263165,0.208133],[0.123588,0.25276,0.262624,0.20776],[0.125925,0.251275,0.262083,0.207433],[0.128263,0.24979,0.261541,0.207107],[0.1306,0.248305,0.261,0.20678],[0.132429,0.24625,0.261541,0.206733],[0.134259,0.244195,0.262083,0.206687],[0.136088,0.24214,0.262624,0.20664],[0.136951,0.239853,0.263165,0.207387],[0.137813,0.237567,0.263707,0.208133],[0.138676,0.23528,0.264248,0.20888],[0.138639,0.233887,0.264789,0.209253],[0.138601,0.232493,0.265331,0.209627],[0.138564,0.2311,0.265872,0.21],[0.139068,0.23066,0.265331,0.209627],[0.139572,0.23022,0.264789,0.209253],[0.140076,0.22978,0.264248,0.20888],[0.140113,0.229955,0.263707,0.20818],[0.140151,0.23013,0.263165,0.20748],[0.140188,0.230305,0.262624,0.20678],[0.140188,0.230398,0.262624,0.206407],[0.140188,0.230492,0.262624,0.206033],[0.140188,0.230585,0.262624,0.20566],[0.140692,0.230585,0.262083,0.20566],[0.141196,0.230585,0.261541,0.20566],[0.1417,0.230585,0.261,0.20566],[0.141196,0.230492,0.261541,0.206033],[0.140692,0.230398,0.262083,0.206407],[0.140188,0.230305,0.262624,0.20678],[0.140225,0.230665,0.262083,0.206407],[0.140263,0.231025,0.261541,0.206033],[0.1403,0.231385,0.261,0.20566],[0.140337,0.231385,0.260459,0.20566],[0.140375,0.231385,0.259917,0.20566],[0.140412,0.231385,0.259376,0.20566],[0.140447,0.231838,0.258873,0.204913],[0.140481,0.232292,0.258371,0.204167],[0.140516,0.232745,0.257868,0.20342],[0.140516,0.232745,0.257868,0.20342],[0.140516,0.232745,0.257868,0.20342],[0.140516,0.232745,0.257868,0.20342],[0.140516,0.233105,0.257868,0.203047],[0.140516,0.233465,0.257868,0.202673],[0.140516,0.233825,0.257868,0.2023],[0.14102,0.233918,0.257327,0.201927],[0.141524,0.234012,0.256785,0.201553],[0.142028,0.234105,0.256244,0.20118],null,null,[0.262884,0.111985,0.438132,0.34566],[0.262921,0.113145,0.437591,0.345287],[0.262959,0.114305,0.437049,0.344913],[0.262996,0.115465,0.436508,0.34454],[0.263968,0.116952,0.435464,0.343793],[0.26494,0.118438,0.43442,0.343047],[0.265912,0.119925,0.433376,0.3423],[0.266451,0.120333,0.432332,0.3416],[0.266989,0.120742,0.431288,0.3409],[0.267528,0.12115,0.430244,0.3402],[0.267997,0.11985,0.430205,0.3402],[0.268467,0.11855,0.430167,0.3402],[0.268936,0.11725,0.430128,0.3402],[0.268824,0.116123,0.431752,0.340573],[0.268712,0.114997,0.433376,0.340947],[0.2686,0.11387,0.435,0.34132],[0.269067,0.113417,0.435,0.342067],[0.269533,0.112963,0.435,0.342813],[0.27,0.11251,0.435,0.34356],[0.269496,0.112428,0.435541,0.343887],[0.268992,0.112347,0.436083,0.344213],[0.268488,0.112265,0.436624,0.34454],null,null,[0.145164,0.23721,0.251372,0.19796],[0.145164,0.237117,0.251372,0.198333],[0.145164,0.237023,0.251372,0.198707],[0.145164,0.23693,0.251372,0.19908],[0.145164,0.23693,0.251372,0.19908],[0.145164,0.23693,0.251372,0.19908],[0.145164,0.23693,0.251372,0.19908],[0.145631,0.237023,0.251372,0.198707],[0.146097,0.237117,0.251372,0.198333],[0.146564,0.23721,0.251372,0.19796],[0.146529,0.23685,0.251875,0.198333],[0.146495,0.23649,0.252377,0.198707],[0.14646,0.23613,0.25288,0.19908],[0.14646,0.235722,0.25288,0.19978],[0.14646,0.235313,0.25288,0.20048],[0.14646,0.234905,0.25288,0.20118],[0.145919,0.234905,0.253963,0.20118],[0.145377,0.234905,0.255045,0.20118],[0.144836,0.234905,0.256128,0.20118],[0.144873,0.235127,0.255587,0.201227],[0.144911,0.235348,0.255045,0.201273],[0.144948,0.23557,0.254504,0.20132],[0.144948,0.23593,0.254504,0.200947],[0.144948,0.23629,0.254504,0.200573],[0.144948,0.23665,0.254504,0.2002],[0.144983,0.236917,0.254001,0.2002],[0.145017,0.237183,0.253499,0.2002],[0.145052,0.23745,0.252996,0.2002],[0.144585,0.23709,0.252996,0.200573],[0.144119,0.23673,0.252996,0.200947],[0.143652,0.23637,0.252996,0.20132],[0.142644,0.23601,0.254079,0.201693],[0.141636,0.23565,0.255161,0.202067],[0.140628,0.23529,0.256244,0.20244],[0.140665,0.23529,0.255703,0.20244],[0.140703,0.23529,0.255161,0.20244],[0.14074,0.23529,0.25462,0.20244],[0.140236,0.23529,0.255161,0.20244],[0.139732,0.23529,0.255703,0.20244],[0.139228,0.23529,0.256244,0.20244],[0.139228,0.23529,0.256244,0.20244],[0.139228,0.23529,0.256244,0.20244],[0.139228,0.23529,0.256244,0.20244],[0.139191,0.234975,0.256785,0.202767],[0.139153,0.23466,0.257327,0.203093],[0.139116,0.234345,0.257868,0.20342],[0.13962,0.234438,0.257327,0.203047],[0.140124,0.234532,0.256785,0.202673],[0.140628,0.234625,0.256244,0.2023],[0.140628,0.234625,0.256244,0.2023],[0.140628,0.234625,0.256244,0.2023],[0.140628,0.234625,0.256244,0.2023],[0.140591,0.234625,0.256785,0.2023],[0.140553,0.234625,0.257327,0.2023],[0.140516,0.234625,0.257868,0.2023],[0.140516,0.234358,0.257868,0.2023],[0.140516,0.234092,0.257868,0.2023],[0.140516,0.233825,0.257868,0.2023],null,null,[0.267352,0.11302,0.412496,0.32592],[0.267352,0.112927,0.412496,0.326293],[0.267352,0.112833,0.412496,0.326667],[0.267352,0.11274,0.412496,0.32704],[0.267856,0.113553,0.411955,0.32592],[0.26836,0.114367,0.411413,0.3248],[0.268864,0.11518,0.410872,0.32368],[0.269872,0.115715,0.409789,0.322607],[0.27088,0.11625,0.408707,0.321533],[0.271888,0.116785,0.407624,0.32046],[0.272933,0.11746,0.406,0.31976],[0.273979,0.118135,0.404376,0.31906],[0.275024,0.11881,0.402752,0.31836],[0.275528,0.119797,0.402211,0.317613],[0.276032,0.120783,0.401669,0.316867],[0.276536,0.12177,0.401128,0.31612],[0.276499,0.122177,0.401669,0.316493],[0.276461,0.122583,0.402211,0.316867],[0.276424,0.12299,0.402752,0.31724],[0.276928,0.123257,0.402211,0.31724],[0.277432,0.123523,0.401669,0.31724],[0.277936,0.12379,0.401128,0.31724],[0.277507,0.124243,0.400587,0.316493],[0.277077,0.124697,0.400045,0.315747],[0.276648,0.12515,0.399504,0.315],[0.276181,0.124523,0.399504,0.315373],[0.275715,0.123897,0.399504,0.315747],[0.275248,0.12327,0.399504,0.31612],[0.273699,0.122235,0.401669,0.317193],[0.272149,0.1212,0.403835,0.318267],[0.2706,0.120165,0.406,0.31934],[0.270059,0.119258,0.407083,0.320833],[0.269517,0.118352,0.408165,0.322327],[0.268976,0.117445,0.409248,0.32382],[0.268509,0.11799,0.409248,0.323773],[0.268043,0.118535,0.409248,0.323727],[0.267576,0.11908,0.409248,0.32368],[0.267147,0.120555,0.408707,0.32298],[0.266717,0.12203,0.408165,0.32228],[0.266288,0.123505,0.407624,0.32158],[0.266325,0.124353,0.407083,0.321253],[0.266363,0.125202,0.406541,0.320927],[0.2664,0.12605,0.406,0.3206],[0.2664,0.126328,0.406,0.320553],[0.2664,0.126607,0.406,0.320507],[0.2664,0.126885,0.406,0.32046],[0.266363,0.126885,0.406541,0.32046],[0.266325,0.126885,0.407083,0.32046],[0.266288,0.126885,0.407624,0.32046],[0.266792,0.126607,0.407083,0.320507],[0.267296,0.126328,0.406541,0.320553],[0.2678,0.12605,0.406,0.3206],[0.2678,0.12605,0.406,0.3206],[0.2678,0.12605,0.406,0.3206],[0.2678,0.12605,0.406,0.3206],null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,[0.27104,0.11787,0.39962,0.31612],[0.272984,0.118417,0.398499,0.315],[0.274928,0.118963,0.397377,0.31388],[0.276872,0.11951,0.396256,0.31276],[0.279207,0.11951,0.395753,0.31276],[0.281541,0.11951,0.395251,0.31276],[0.283876,0.11951,0.394748,0.31276],[0.284737,0.11915,0.395792,0.313133],[0.285599,0.11879,0.396836,0.313507],[0.28646,0.11843,0.39788,0.31388],[0.286815,0.117523,0.399504,0.315373],[0.287169,0.116617,0.401128,0.316867],[0.287524,0.11571,0.402752,0.31836],[0.286945,0.115175,0.404376,0.319433],[0.286367,0.11464,0.406,0.320507],[0.285788,0.114105,0.407624,0.32158],[0.286217,0.114278,0.408165,0.321953],[0.286647,0.114452,0.408707,0.322327],[0.287076,0.114625,0.409248,0.3227],[0.288012,0.114892,0.409209,0.3227],[0.288948,0.115158,0.409171,0.3227],[0.289884,0.115425,0.409132,0.3227],[0.289809,0.11489,0.410215,0.323773],[0.289735,0.114355,0.411297,0.324847],[0.28966,0.11382,0.41238,0.32592],[0.289585,0.113273,0.413463,0.32704],[0.289511,0.112727,0.414545,0.32816],[0.289436,0.11218,0.415628,0.32928],[0.289867,0.11254,0.415667,0.328907],[0.290297,0.1129,0.415705,0.328533],[0.290728,0.11326,0.415744,0.32816],[0.290297,0.11362,0.415705,0.327787],[0.289867,0.11398,0.415667,0.327413],[0.289436,0.11434,0.415628,0.32704],[0.287999,0.113805,0.416169,0.328113],[0.286561,0.11327,0.416711,0.329187],[0.285124,0.112735,0.417252,0.33026],[0.283687,0.112908,0.417793,0.330633],[0.282249,0.113082,0.418335,0.331007],[0.280812,0.113255,0.418876,0.33138],[0.280345,0.113788,0.418876,0.33138],[0.279879,0.114322,0.418876,0.33138],[0.279412,0.114855,0.418876,0.33138],[0.27898,0.11517,0.418373,0.331053],[0.278548,0.115485,0.417871,0.330727],[0.278116,0.1158,0.417368,0.3304],[0.278153,0.116253,0.416827,0.329653],[0.278191,0.116707,0.416285,0.328907],[0.278228,0.11716,0.415744,0.32816],[0.27776,0.1168,0.416247,0.328533],[0.277292,0.11644,0.416749,0.328907],[0.276824,0.11608,0.417252,0.32928],null,null,[0.147636,0.228845,0.256128,0.20342],[0.147599,0.228485,0.256669,0.203793],[0.147561,0.228125,0.257211,0.204167],[0.147524,0.227765,0.257752,0.20454],[0.147487,0.227312,0.258293,0.205287],[0.147449,0.226858,0.258835,0.206033],[0.147412,0.226405,0.259376,0.20678],[0.147449,0.226858,0.258835,0.206033],[0.147487,0.227312,0.258293,0.205287],[0.147524,0.227765,0.257752,0.20454],[0.147524,0.228218,0.257752,0.203793],[0.147524,0.228672,0.257752,0.203047],[0.147524,0.229125,0.257752,0.2023],[0.148028,0.229392,0.257211,0.2023],[0.148532,0.229658,0.256669,0.2023],[0.149036,0.229925,0.256128,0.2023],[0.149036,0.229565,0.256128,0.202673],[0.149036,0.229205,0.256128,0.203047],[0.149036,0.228845,0.256128,0.20342],null,null,[0.317588,0.14912,0.349624,0.27552],[0.316151,0.1484,0.350165,0.276267],[0.314713,0.14768,0.350707,0.277013],[0.313276,0.14696,0.351248,0.27776],[0.310829,0.145925,0.353375,0.278833],[0.308383,0.14489,0.355501,0.279907],[0.305936,0.143855,0.357628,0.28098],[0.305469,0.143495,0.357628,0.281353],[0.305003,0.143135,0.357628,0.281727],[0.304536,0.142775,0.357628,0.2821],[0.305508,0.143532,0.356584,0.281073],[0.30648,0.144288,0.35554,0.280047],[0.307452,0.145045,0.354496,0.27902],[0.308964,0.145765,0.352872,0.278273],[0.310476,0.146485,0.351248,0.277527],[0.311988,0.147205,0.349624,0.27678],[0.312492,0.147658,0.349083,0.276033],[0.312996,0.148112,0.348541,0.275287],[0.3135,0.148565,0.348,0.27454],[0.314004,0.148658,0.347459,0.274167],[0.314508,0.148752,0.346917,0.273793],[0.315012,0.148845,0.346376,0.27342],[0.314359,0.146997,0.349083,0.275613],[0.313705,0.145148,0.351789,0.277807],[0.313052,0.1433,0.354496,0.28],[0.312364,0.141452,0.357705,0.282193],[0.311676,0.139603,0.360915,0.284387],[0.310988,0.137755,0.364124,0.28658],[0.311343,0.136593,0.365748,0.288027],[0.311697,0.135432,0.367372,0.289473],[0.312052,0.13427,0.368996,0.29092],[0.312951,0.134083,0.369499,0.291667],[0.313849,0.133897,0.370001,0.292413],[0.314748,0.13371,0.370504,0.29316],[0.315177,0.13407,0.371045,0.292787],[0.315607,0.13443,0.371587,0.292413],[0.316036,0.13479,0.372128,0.29204],[0.316971,0.13515,0.371625,0.291667],[0.317905,0.13551,0.371123,0.291293],[0.31884,0.13587,0.37062,0.29092],[0.319344,0.13587,0.370079,0.29092],[0.319848,0.13587,0.369537,0.29092],[0.320352,0.13587,0.368996,0.29092],[0.320352,0.135603,0.368996,0.29092],[0.320352,0.135337,0.368996,0.29092],[0.320352,0.13507,0.368996,0.29092],[0.319885,0.13471,0.368996,0.291293],[0.319419,0.13435,0.368996,0.291667],[0.318952,0.13399,0.368996,0.29204],null,null,null,null,null,[0.146348,0.23059,0.254504,0.20244],[0.146348,0.23059,0.254504,0.20244],[0.146348,0.23059,0.254504,0.20244],[0.146348,0.23059,0.254504,0.20244],[0.145844,0.23059,0.255045,0.20244],[0.14534,0.23059,0.255587,0.20244],[0.144836,0.23059,0.256128,0.20244],[0.144369,0.230497,0.256128,0.202813],[0.143903,0.230403,0.256128,0.203187],[0.143436,0.23031,0.256128,0.20356],[0.143436,0.23067,0.256128,0.203187],[0.33846,0.124725,0.36888,0.2919],[0.33846,0.124725,0.36888,0.2919],[0.33846,0.124725,0.36888,0.2919],[0.33846,0.124725,0.36888,0.2919],[0.33846,0.124725,0.36888,0.2919],[0.33846,0.124725,0.36888,0.2919],[0.33846,0.124725,0.36888,0.2919],[0.33846,0.124725,0.36888,0.2919],[0.338852,0.125213,0.369963,0.291947],[0.339244,0.125702,0.371045,0.291993],[0.339636,0.12619,0.372128,0.29204],[0.341,0.126548,0.372167,0.29274],[0.342364,0.126907,0.372205,0.29344],[0.343728,0.127265,0.372244,0.29414],[0.344627,0.127753,0.372747,0.294187],[0.345525,0.128242,0.373249,0.294233],[0.346424,0.12873,0.373752,0.29428],[0.346387,0.128415,0.374293,0.294607],[0.346349,0.1281,0.374835,0.294933],[0.346312,0.127785,0.375376,0.29526],[0.346312,0.127692,0.375376,0.295633],[0.346312,0.127598,0.375376,0.296007],[0.346312,0.127505,0.375376,0.29638],[0.346312,0.127238,0.375376,0.29638],[0.346312,0.126972,0.375376,0.29638],[0.346312,0.126705,0.375376,0.29638],[0.346312,0.125893,0.375376,0.296427],[0.346312,0.125082,0.375376,0.296473],[0.346312,0.12427,0.375376,0.29652],[0.345771,0.123422,0.376459,0.296847],[0.345229,0.122573,0.377541,0.297173],[0.344688,0.121725,0.378624,0.2975],[0.344688,0.121005,0.378624,0.298247],[0.344688,0.120285,0.378624,0.298993],[0.344688,0.119565,0.378624,0.29974],[0.345117,0.119832,0.379165,0.29974],[0.345547,0.120098,0.379707,0.29974],[0.345976,0.120365,0.380248,0.29974],[0.346947,0.12127,0.379707,0.29932],[0.347917,0.122175,0.379165,0.2989],[0.348888,0.12308,0.378624,0.29848],[0.349392,0.123755,0.378083,0.29778],[0.349896,0.12443,0.377541,0.29708],[0.3504,0.125105,0.377,0.29638],[0.349896,0.124745,0.377541,0.296753],[0.349392,0.124385,0.378083,0.297127],[0.348888,0.124025,0.378624,0.2975],[0.348421,0.12371,0.378624,0.297827],[0.347955,0.123395,0.378624,0.298153],[0.347488,0.12308,0.378624,0.29848],[0.347563,0.123255,0.377541,0.29778],[0.347637,0.12343,0.376459,0.29708],[0.347712,0.123605,0.375376,0.29638],[0.347859,0.123978,0.373249,0.294887],[0.348005,0.124352,0.371123,0.293393],[0.348152,0.124725,0.368996,0.2919],[0.347293,0.125575,0.367913,0.2905],[0.346435,0.126425,0.366831,0.2891],[0.345576,0.127275,0.365748,0.2877],[0.345688,0.127995,0.364124,0.286953],[0.3458,0.128715,0.3625,0.286207],[0.345912,0.129435,0.360876,0.28546],[0.346341,0.129342,0.361417,0.285833],[0.346771,0.129248,0.361959,0.286207],[0.3472,0.129155,0.3625,0.28658],[0.346547,0.127807,0.365207,0.288773],[0.345893,0.126458,0.367913,0.290967],[0.34524,0.12511,0.37062,0.29316],[0.344231,0.124075,0.372205,0.294233],[0.343221,0.12304,0.373791,0.295307],[0.342212,0.122005,0.375376,0.29638],[0.341783,0.121738,0.374835,0.29638],[0.341353,0.121472,0.374293,0.29638],[0.340924,0.121205,0.373752,0.29638],[0.340924,0.121565,0.373752,0.296007],[0.340924,0.121925,0.373752,0.295633],[0.340924,0.122285,0.373752,0.29526],[0.340849,0.121832,0.374835,0.296007],[0.340775,0.121378,0.375917,0.296753],[0.3407,0.120925,0.377,0.2975],[0.341167,0.120832,0.377,0.297873],[0.341633,0.120738,0.377,0.298247],[0.3421,0.120645,0.377,0.29862],[0.3421,0.121005,0.377,0.298247],[0.3421,0.121365,0.377,0.297873],[0.3421,0.121725,0.377,0.2975],null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,[0.322976,0.137805,0.351248,0.27678],[0.322939,0.13763,0.351789,0.27748],[0.322901,0.137455,0.352331,0.27818],[0.322864,0.13728,0.352872,0.27888],[0.321781,0.137533,0.355037,0.28],[0.320699,0.137787,0.357203,0.28112],[0.319616,0.13804,0.359368,0.28224],[0.318103,0.13741,0.361495,0.28476],[0.316589,0.13678,0.363621,0.28728],[0.315076,0.13615,0.365748,0.2898],[0.314572,0.136057,0.366289,0.290173],[0.314068,0.135963,0.366831,0.290547],[0.313564,0.13587,0.367372,0.29092],[0.314572,0.136138,0.366289,0.289847],[0.31558,0.136407,0.365207,0.288773],[0.316588,0.136675,0.364124,0.2877],[0.316625,0.137035,0.363583,0.287327],[0.316663,0.137395,0.363041,0.286953],[0.3167,0.137755,0.3625,0.28658],[0.315225,0.137847,0.363583,0.28728],[0.313751,0.137938,0.364665,0.28798],[0.312276,0.13803,0.365748,0.28868],[0.311809,0.137843,0.365748,0.289427],[0.311343,0.137657,0.365748,0.290173],[0.310876,0.13747,0.365748,0.29092],[0.310913,0.137657,0.365207,0.290173],[0.310951,0.137843,0.364665,0.289427],[0.310988,0.13803,0.364124,0.28868],null,null,[0.126176,0.222225,0.264248,0.2079],[0.126176,0.222585,0.264248,0.207527],[0.126176,0.222945,0.264248,0.207153],[0.126176,0.223305,0.264248,0.20678],[0.126717,0.223665,0.263165,0.206407],[0.127259,0.224025,0.262083,0.206033],[0.1278,0.224385,0.261,0.20566],[0.128304,0.22506,0.260459,0.20496],[0.128808,0.225735,0.259917,0.20426],[0.129312,0.22641,0.259376,0.20356],[0.129816,0.22677,0.258835,0.203187],[0.13032,0.22713,0.258293,0.202813],[0.130824,0.22749,0.257752,0.20244],[0.131291,0.227768,0.257752,0.202393],[0.131757,0.228047,0.257752,0.202347],[0.132224,0.228325,0.257752,0.2023],[0.132691,0.227965,0.257752,0.202673],[0.133157,0.227605,0.257752,0.203047],[0.133624,0.227245,0.257752,0.20342],[0.133587,0.227245,0.258293,0.20342],[0.133549,0.227245,0.258835,0.20342],[0.133512,0.227245,0.259376,0.20342],null,null,[0.273248,0.11551,0.428504,0.33796],[0.273715,0.116043,0.428504,0.33796],[0.274181,0.116577,0.428504,0.33796],[0.274648,0.11711,0.428504,0.33796],[0.276124,0.118145,0.426919,0.336887],[0.2776,0.11918,0.425333,0.335813],[0.279076,0.120215,0.423748,0.33474],[0.280588,0.121028,0.422124,0.33362],[0.2821,0.121842,0.4205,0.3325],[0.283612,0.122655,0.418876,0.33138],[0.284583,0.123423,0.418335,0.330307],[0.285553,0.124192,0.417793,0.329233],[0.286524,0.12496,0.417252,0.32816],[0.287495,0.125053,0.416711,0.327787],[0.288465,0.125147,0.416169,0.327413],[0.289436,0.12524,0.415628,0.32704],[0.289829,0.124298,0.416208,0.32774],[0.290223,0.123357,0.416788,0.32844],[0.290616,0.122415,0.417368,0.32914],[0.290148,0.121417,0.417871,0.329933],[0.28968,0.120418,0.418373,0.330727],[0.289212,0.11942,0.418876,0.33152],[0.289212,0.118932,0.418876,0.331473],[0.289212,0.118443,0.418876,0.331427],[0.289212,0.117955,0.418876,0.33138],[0.290259,0.118583,0.416749,0.329933],[0.291305,0.119212,0.414623,0.328487],[0.292352,0.11984,0.412496,0.32704],[0.293864,0.120702,0.410872,0.325593],[0.295376,0.121563,0.409248,0.324147],[0.296888,0.122425,0.407624,0.3227],[0.297896,0.123238,0.406541,0.32158],[0.298904,0.124052,0.405459,0.32046],[0.299912,0.124865,0.404376,0.31934],[0.299875,0.124505,0.404917,0.319713],[0.299837,0.124145,0.405459,0.320087],[0.2998,0.123785,0.406,0.32046],[0.299259,0.123598,0.407083,0.321207],[0.298717,0.123412,0.408165,0.321953],[0.298176,0.123225,0.409248,0.3227],[0.2976,0.12305,0.410833,0.3234],[0.297024,0.122875,0.412419,0.3241],[0.296448,0.1227,0.414004,0.3248],[0.296877,0.122153,0.414545,0.32592],[0.297307,0.121607,0.415087,0.32704],[0.297736,0.12106,0.415628,0.32816],[0.298128,0.120873,0.416711,0.328907],[0.29852,0.120687,0.417793,0.329653],[0.298912,0.1205,0.418876,0.3304],[0.298837,0.119465,0.419959,0.331473],[0.298763,0.11843,0.421041,0.332547],[0.298688,0.117395,0.422124,0.33362],[0.298651,0.117128,0.422665,0.33362],[0.298613,0.116862,0.423207,0.33362],[0.298576,0.116595,0.423748,0.33362],[0.29908,0.116595,0.423207,0.33362],[0.299584,0.116595,0.422665,0.33362],[0.300088,0.116595,0.422124,0.33362],[0.299584,0.116862,0.422665,0.33362],[0.29908,0.117128,0.423207,0.33362],[0.298576,0.117395,0.423748,0.33362],[0.297605,0.11722,0.424289,0.33432],[0.296635,0.117045,0.424831,0.33502],[0.295664,0.11687,0.425372,0.33572],[0.295197,0.11687,0.425372,0.33572],[0.294731,0.11687,0.425372,0.33572],[0.294264,0.11687,0.425372,0.33572],[0.294301,0.117452,0.424831,0.335393],[0.294339,0.118033,0.424289,0.335067],[0.294376,0.118615,0.423748,0.33474],[0.294917,0.119068,0.422665,0.333993],[0.295459,0.119522,0.421583,0.333247],[0.296,0.119975,0.4205,0.3325],[0.296075,0.120243,0.419417,0.331427],[0.296149,0.120512,0.418335,0.330353],[0.296224,0.12078,0.417252,0.32928],[0.295795,0.120385,0.416711,0.32886],[0.295365,0.11999,0.416169,0.32844],[0.294936,0.119595,0.415628,0.32802],[0.294,0.11941,0.415667,0.327693],[0.293064,0.119225,0.415705,0.327367],[0.292128,0.11904,0.415744,0.32704],[0.292203,0.119133,0.414661,0.326667],[0.292277,0.119227,0.413579,0.326293],[0.292352,0.11932,0.412496,0.32592],[0.293397,0.120355,0.410872,0.324847],[0.294443,0.12139,0.409248,0.323773],[0.295488,0.122425,0.407624,0.3227],[0.295488,0.122958,0.407624,0.3227],[0.295488,0.123492,0.407624,0.3227],[0.295488,0.124025,0.407624,0.3227],[0.294984,0.12421,0.408165,0.323027],[0.29448,0.124395,0.408707,0.323353],[0.293976,0.12458,0.409248,0.32368],[0.294051,0.125615,0.408165,0.322607],[0.294125,0.12665,0.407083,0.321533],[0.2942,0.127685,0.406,0.32046],[0.294275,0.128672,0.404917,0.319713],[0.294349,0.129658,0.403835,0.318967],[0.294424,0.130645,0.402752,0.31822],[0.294928,0.13096,0.402211,0.317893],[0.295432,0.131275,0.401669,0.317567],[0.295936,0.13159,0.401128,0.31724],[0.296907,0.131683,0.400587,0.316867],[0.297877,0.131777,0.400045,0.316493],[0.298848,0.13187,0.399504,0.31612],[0.299315,0.131963,0.399504,0.315747],[0.299781,0.132057,0.399504,0.315373],[0.300248,0.13215,0.399504,0.315],null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,[0.30854,0.12745,0.39962,0.315],[0.309513,0.127217,0.39904,0.315],[0.310487,0.126983,0.39846,0.315],[0.31146,0.12675,0.39788,0.315],[0.312356,0.126983,0.398421,0.315],[0.313252,0.127217,0.398963,0.315],[0.314148,0.12745,0.399504,0.315],[0.313999,0.126983,0.401669,0.316867],[0.313849,0.126517,0.403835,0.318733],[0.3137,0.12605,0.406,0.3206],[0.313087,0.125513,0.408127,0.322747],[0.312473,0.124977,0.410253,0.324893],[0.31186,0.12444,0.41238,0.32704],[0.312327,0.125333,0.41238,0.326667],[0.312793,0.126227,0.41238,0.326293],[0.31326,0.12712,0.41238,0.32592],[0.314269,0.128155,0.410795,0.324847],[0.315279,0.12919,0.409209,0.323773],[0.316288,0.130225,0.407624,0.3227],[0.316288,0.130852,0.407624,0.322327],[0.316288,0.131478,0.407624,0.321953],[0.316288,0.132105,0.407624,0.32158],[0.316251,0.132278,0.408165,0.321953],[0.316213,0.132452,0.408707,0.322327],[0.316176,0.132625,0.409248,0.3227],[0.317072,0.131905,0.409789,0.323447],[0.317968,0.131185,0.410331,0.324193],[0.318864,0.130465,0.410872,0.32494],[0.321088,0.128897,0.412457,0.326013],[0.323312,0.127328,0.414043,0.327087],[0.325536,0.12576,0.415628,0.32816],[0.328228,0.124007,0.416711,0.328907],[0.33092,0.122253,0.417793,0.329653],[0.333612,0.1205,0.418876,0.3304],[0.337421,0.11984,0.417291,0.328907],[0.341231,0.11918,0.415705,0.327413],[0.34504,0.11852,0.41412,0.32592],[0.347956,0.117848,0.411955,0.324473],[0.350872,0.117177,0.409789,0.323027],[0.353788,0.116505,0.407624,0.32158],[0.352533,0.115973,0.406,0.320507],[0.351279,0.115442,0.404376,0.319433],[0.350024,0.11491,0.402752,0.31836],[0.345108,0.115237,0.400084,0.31612],[0.340192,0.115563,0.397416,0.31388],[0.335276,0.11589,0.394748,0.31164],[0.329893,0.11666,0.39208,0.309493],[0.324511,0.11743,0.389412,0.307347],[0.319128,0.1182,0.386744,0.3052],null,null]}];
+ series: [{"id":"WIFE","regions":[[0.119388,0.25276,0.262624,0.20776],[0.118884,0.252667,0.263165,0.208133],[0.11838,0.252573,0.263707,0.208507],[0.117876,0.25248,0.264248,0.20888],[0.117372,0.252747,0.264789,0.20888],[0.116868,0.253013,0.265331,0.20888],[0.116364,0.25328,0.265872,0.20888],[0.116868,0.253502,0.265331,0.208927],[0.117372,0.253723,0.264789,0.208973],[0.117876,0.253945,0.264248,0.20902],[0.118343,0.254223,0.264248,0.208973],[0.118809,0.254502,0.264248,0.208927],[0.119276,0.25478,0.264248,0.20888],[0.120713,0.254107,0.263707,0.208507],[0.122151,0.253433,0.263165,0.208133],[0.123588,0.25276,0.262624,0.20776],[0.125925,0.251275,0.262083,0.207433],[0.128263,0.24979,0.261541,0.207107],[0.1306,0.248305,0.261,0.20678],[0.132429,0.24625,0.261541,0.206733],[0.134259,0.244195,0.262083,0.206687],[0.136088,0.24214,0.262624,0.20664],[0.136951,0.239853,0.263165,0.207387],[0.137813,0.237567,0.263707,0.208133],[0.138676,0.23528,0.264248,0.20888],[0.138639,0.233887,0.264789,0.209253],[0.138601,0.232493,0.265331,0.209627],[0.138564,0.2311,0.265872,0.21],[0.139068,0.23066,0.265331,0.209627],[0.139572,0.23022,0.264789,0.209253],[0.140076,0.22978,0.264248,0.20888],[0.140113,0.229955,0.263707,0.20818],[0.140151,0.23013,0.263165,0.20748],[0.140188,0.230305,0.262624,0.20678],[0.140188,0.230398,0.262624,0.206407],[0.140188,0.230492,0.262624,0.206033],[0.140188,0.230585,0.262624,0.20566],[0.140692,0.230585,0.262083,0.20566],[0.141196,0.230585,0.261541,0.20566],[0.1417,0.230585,0.261,0.20566],[0.141196,0.230492,0.261541,0.206033],[0.140692,0.230398,0.262083,0.206407],[0.140188,0.230305,0.262624,0.20678],[0.140225,0.230665,0.262083,0.206407],[0.140263,0.231025,0.261541,0.206033],[0.1403,0.231385,0.261,0.20566],[0.140337,0.231385,0.260459,0.20566],[0.140375,0.231385,0.259917,0.20566],[0.140412,0.231385,0.259376,0.20566],[0.140447,0.231838,0.258873,0.204913],[0.140481,0.232292,0.258371,0.204167],[0.140516,0.232745,0.257868,0.20342],[0.140516,0.232745,0.257868,0.20342],[0.140516,0.232745,0.257868,0.20342],[0.140516,0.232745,0.257868,0.20342],[0.140516,0.233105,0.257868,0.203047],[0.140516,0.233465,0.257868,0.202673],[0.140516,0.233825,0.257868,0.2023],[0.14102,0.233918,0.257327,0.201927],[0.141524,0.234012,0.256785,0.201553],[0.142028,0.234105,0.256244,0.20118],null,null,[0.262884,0.111985,0.438132,0.34566],[0.262921,0.113145,0.437591,0.345287],[0.262959,0.114305,0.437049,0.344913],[0.262996,0.115465,0.436508,0.34454],[0.263968,0.116952,0.435464,0.343793],[0.26494,0.118438,0.43442,0.343047],[0.265912,0.119925,0.433376,0.3423],[0.266451,0.120333,0.432332,0.3416],[0.266989,0.120742,0.431288,0.3409],[0.267528,0.12115,0.430244,0.3402],[0.267997,0.11985,0.430205,0.3402],[0.268467,0.11855,0.430167,0.3402],[0.268936,0.11725,0.430128,0.3402],[0.268824,0.116123,0.431752,0.340573],[0.268712,0.114997,0.433376,0.340947],[0.2686,0.11387,0.435,0.34132],[0.269067,0.113417,0.435,0.342067],[0.269533,0.112963,0.435,0.342813],[0.27,0.11251,0.435,0.34356],[0.269496,0.112428,0.435541,0.343887],[0.268992,0.112347,0.436083,0.344213],[0.268488,0.112265,0.436624,0.34454],null,null,[0.145164,0.23721,0.251372,0.19796],[0.145164,0.237117,0.251372,0.198333],[0.145164,0.237023,0.251372,0.198707],[0.145164,0.23693,0.251372,0.19908],[0.145164,0.23693,0.251372,0.19908],[0.145164,0.23693,0.251372,0.19908],[0.145164,0.23693,0.251372,0.19908],[0.145631,0.237023,0.251372,0.198707],[0.146097,0.237117,0.251372,0.198333],[0.146564,0.23721,0.251372,0.19796],[0.146529,0.23685,0.251875,0.198333],[0.146495,0.23649,0.252377,0.198707],[0.14646,0.23613,0.25288,0.19908],[0.14646,0.235722,0.25288,0.19978],[0.14646,0.235313,0.25288,0.20048],[0.14646,0.234905,0.25288,0.20118],[0.145919,0.234905,0.253963,0.20118],[0.145377,0.234905,0.255045,0.20118],[0.144836,0.234905,0.256128,0.20118],[0.144873,0.235127,0.255587,0.201227],[0.144911,0.235348,0.255045,0.201273],[0.144948,0.23557,0.254504,0.20132],[0.144948,0.23593,0.254504,0.200947],[0.144948,0.23629,0.254504,0.200573],[0.144948,0.23665,0.254504,0.2002],[0.144983,0.236917,0.254001,0.2002],[0.145017,0.237183,0.253499,0.2002],[0.145052,0.23745,0.252996,0.2002],[0.144585,0.23709,0.252996,0.200573],[0.144119,0.23673,0.252996,0.200947],[0.143652,0.23637,0.252996,0.20132],[0.142644,0.23601,0.254079,0.201693],[0.141636,0.23565,0.255161,0.202067],[0.140628,0.23529,0.256244,0.20244],[0.140665,0.23529,0.255703,0.20244],[0.140703,0.23529,0.255161,0.20244],[0.14074,0.23529,0.25462,0.20244],[0.140236,0.23529,0.255161,0.20244],[0.139732,0.23529,0.255703,0.20244],[0.139228,0.23529,0.256244,0.20244],[0.139228,0.23529,0.256244,0.20244],[0.139228,0.23529,0.256244,0.20244],[0.139228,0.23529,0.256244,0.20244],[0.139191,0.234975,0.256785,0.202767],[0.139153,0.23466,0.257327,0.203093],[0.139116,0.234345,0.257868,0.20342],[0.13962,0.234438,0.257327,0.203047],[0.140124,0.234532,0.256785,0.202673],[0.140628,0.234625,0.256244,0.2023],[0.140628,0.234625,0.256244,0.2023],[0.140628,0.234625,0.256244,0.2023],[0.140628,0.234625,0.256244,0.2023],[0.140591,0.234625,0.256785,0.2023],[0.140553,0.234625,0.257327,0.2023],[0.140516,0.234625,0.257868,0.2023],[0.140516,0.234358,0.257868,0.2023],[0.140516,0.234092,0.257868,0.2023],[0.140516,0.233825,0.257868,0.2023],null,null,[0.267352,0.11302,0.412496,0.32592],[0.267352,0.112927,0.412496,0.326293],[0.267352,0.112833,0.412496,0.326667],[0.267352,0.11274,0.412496,0.32704],[0.267856,0.113553,0.411955,0.32592],[0.26836,0.114367,0.411413,0.3248],[0.268864,0.11518,0.410872,0.32368],[0.269872,0.115715,0.409789,0.322607],[0.27088,0.11625,0.408707,0.321533],[0.271888,0.116785,0.407624,0.32046],[0.272933,0.11746,0.406,0.31976],[0.273979,0.118135,0.404376,0.31906],[0.275024,0.11881,0.402752,0.31836],[0.275528,0.119797,0.402211,0.317613],[0.276032,0.120783,0.401669,0.316867],[0.276536,0.12177,0.401128,0.31612],[0.276499,0.122177,0.401669,0.316493],[0.276461,0.122583,0.402211,0.316867],[0.276424,0.12299,0.402752,0.31724],[0.276928,0.123257,0.402211,0.31724],[0.277432,0.123523,0.401669,0.31724],[0.277936,0.12379,0.401128,0.31724],[0.277507,0.124243,0.400587,0.316493],[0.277077,0.124697,0.400045,0.315747],[0.276648,0.12515,0.399504,0.315],[0.276181,0.124523,0.399504,0.315373],[0.275715,0.123897,0.399504,0.315747],[0.275248,0.12327,0.399504,0.31612],[0.273699,0.122235,0.401669,0.317193],[0.272149,0.1212,0.403835,0.318267],[0.2706,0.120165,0.406,0.31934],[0.270059,0.119258,0.407083,0.320833],[0.269517,0.118352,0.408165,0.322327],[0.268976,0.117445,0.409248,0.32382],[0.268509,0.11799,0.409248,0.323773],[0.268043,0.118535,0.409248,0.323727],[0.267576,0.11908,0.409248,0.32368],[0.267147,0.120555,0.408707,0.32298],[0.266717,0.12203,0.408165,0.32228],[0.266288,0.123505,0.407624,0.32158],[0.266325,0.124353,0.407083,0.321253],[0.266363,0.125202,0.406541,0.320927],[0.2664,0.12605,0.406,0.3206],[0.2664,0.126328,0.406,0.320553],[0.2664,0.126607,0.406,0.320507],[0.2664,0.126885,0.406,0.32046],[0.266363,0.126885,0.406541,0.32046],[0.266325,0.126885,0.407083,0.32046],[0.266288,0.126885,0.407624,0.32046],[0.266792,0.126607,0.407083,0.320507],[0.267296,0.126328,0.406541,0.320553],[0.2678,0.12605,0.406,0.3206],[0.2678,0.12605,0.406,0.3206],[0.2678,0.12605,0.406,0.3206],[0.2678,0.12605,0.406,0.3206],null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,[0.27104,0.11787,0.39962,0.31612],[0.272984,0.118417,0.398499,0.315],[0.274928,0.118963,0.397377,0.31388],[0.276872,0.11951,0.396256,0.31276],[0.279207,0.11951,0.395753,0.31276],[0.281541,0.11951,0.395251,0.31276],[0.283876,0.11951,0.394748,0.31276],[0.284737,0.11915,0.395792,0.313133],[0.285599,0.11879,0.396836,0.313507],[0.28646,0.11843,0.39788,0.31388],[0.286815,0.117523,0.399504,0.315373],[0.287169,0.116617,0.401128,0.316867],[0.287524,0.11571,0.402752,0.31836],[0.286945,0.115175,0.404376,0.319433],[0.286367,0.11464,0.406,0.320507],[0.285788,0.114105,0.407624,0.32158],[0.286217,0.114278,0.408165,0.321953],[0.286647,0.114452,0.408707,0.322327],[0.287076,0.114625,0.409248,0.3227],[0.288012,0.114892,0.409209,0.3227],[0.288948,0.115158,0.409171,0.3227],[0.289884,0.115425,0.409132,0.3227],[0.289809,0.11489,0.410215,0.323773],[0.289735,0.114355,0.411297,0.324847],[0.28966,0.11382,0.41238,0.32592],[0.289585,0.113273,0.413463,0.32704],[0.289511,0.112727,0.414545,0.32816],[0.289436,0.11218,0.415628,0.32928],[0.289867,0.11254,0.415667,0.328907],[0.290297,0.1129,0.415705,0.328533],[0.290728,0.11326,0.415744,0.32816],[0.290297,0.11362,0.415705,0.327787],[0.289867,0.11398,0.415667,0.327413],[0.289436,0.11434,0.415628,0.32704],[0.287999,0.113805,0.416169,0.328113],[0.286561,0.11327,0.416711,0.329187],[0.285124,0.112735,0.417252,0.33026],[0.283687,0.112908,0.417793,0.330633],[0.282249,0.113082,0.418335,0.331007],[0.280812,0.113255,0.418876,0.33138],[0.280345,0.113788,0.418876,0.33138],[0.279879,0.114322,0.418876,0.33138],[0.279412,0.114855,0.418876,0.33138],[0.27898,0.11517,0.418373,0.331053],[0.278548,0.115485,0.417871,0.330727],[0.278116,0.1158,0.417368,0.3304],[0.278153,0.116253,0.416827,0.329653],[0.278191,0.116707,0.416285,0.328907],[0.278228,0.11716,0.415744,0.32816],[0.27776,0.1168,0.416247,0.328533],[0.277292,0.11644,0.416749,0.328907],[0.276824,0.11608,0.417252,0.32928],null,null,[0.147636,0.228845,0.256128,0.20342],[0.147599,0.228485,0.256669,0.203793],[0.147561,0.228125,0.257211,0.204167],[0.147524,0.227765,0.257752,0.20454],[0.147487,0.227312,0.258293,0.205287],[0.147449,0.226858,0.258835,0.206033],[0.147412,0.226405,0.259376,0.20678],[0.147449,0.226858,0.258835,0.206033],[0.147487,0.227312,0.258293,0.205287],[0.147524,0.227765,0.257752,0.20454],[0.147524,0.228218,0.257752,0.203793],[0.147524,0.228672,0.257752,0.203047],[0.147524,0.229125,0.257752,0.2023],[0.148028,0.229392,0.257211,0.2023],[0.148532,0.229658,0.256669,0.2023],[0.149036,0.229925,0.256128,0.2023],[0.149036,0.229565,0.256128,0.202673],[0.149036,0.229205,0.256128,0.203047],[0.149036,0.228845,0.256128,0.20342],null,null,[0.317588,0.14912,0.349624,0.27552],[0.316151,0.1484,0.350165,0.276267],[0.314713,0.14768,0.350707,0.277013],[0.313276,0.14696,0.351248,0.27776],[0.310829,0.145925,0.353375,0.278833],[0.308383,0.14489,0.355501,0.279907],[0.305936,0.143855,0.357628,0.28098],[0.305469,0.143495,0.357628,0.281353],[0.305003,0.143135,0.357628,0.281727],[0.304536,0.142775,0.357628,0.2821],[0.305508,0.143532,0.356584,0.281073],[0.30648,0.144288,0.35554,0.280047],[0.307452,0.145045,0.354496,0.27902],[0.308964,0.145765,0.352872,0.278273],[0.310476,0.146485,0.351248,0.277527],[0.311988,0.147205,0.349624,0.27678],[0.312492,0.147658,0.349083,0.276033],[0.312996,0.148112,0.348541,0.275287],[0.3135,0.148565,0.348,0.27454],[0.314004,0.148658,0.347459,0.274167],[0.314508,0.148752,0.346917,0.273793],[0.315012,0.148845,0.346376,0.27342],[0.314359,0.146997,0.349083,0.275613],[0.313705,0.145148,0.351789,0.277807],[0.313052,0.1433,0.354496,0.28],[0.312364,0.141452,0.357705,0.282193],[0.311676,0.139603,0.360915,0.284387],[0.310988,0.137755,0.364124,0.28658],[0.311343,0.136593,0.365748,0.288027],[0.311697,0.135432,0.367372,0.289473],[0.312052,0.13427,0.368996,0.29092],[0.312951,0.134083,0.369499,0.291667],[0.313849,0.133897,0.370001,0.292413],[0.314748,0.13371,0.370504,0.29316],[0.315177,0.13407,0.371045,0.292787],[0.315607,0.13443,0.371587,0.292413],[0.316036,0.13479,0.372128,0.29204],[0.316971,0.13515,0.371625,0.291667],[0.317905,0.13551,0.371123,0.291293],[0.31884,0.13587,0.37062,0.29092],[0.319344,0.13587,0.370079,0.29092],[0.319848,0.13587,0.369537,0.29092],[0.320352,0.13587,0.368996,0.29092],[0.320352,0.135603,0.368996,0.29092],[0.320352,0.135337,0.368996,0.29092],[0.320352,0.13507,0.368996,0.29092],[0.319885,0.13471,0.368996,0.291293],[0.319419,0.13435,0.368996,0.291667],[0.318952,0.13399,0.368996,0.29204],null,null,null,null,null,[0.146348,0.23059,0.254504,0.20244],[0.146348,0.23059,0.254504,0.20244],[0.146348,0.23059,0.254504,0.20244],[0.146348,0.23059,0.254504,0.20244],[0.145844,0.23059,0.255045,0.20244],[0.14534,0.23059,0.255587,0.20244],[0.144836,0.23059,0.256128,0.20244],[0.144369,0.230497,0.256128,0.202813],[0.143903,0.230403,0.256128,0.203187],[0.143436,0.23031,0.256128,0.20356],[0.143436,0.23067,0.256128,0.203187],[0.33846,0.124725,0.36888,0.2919],[0.33846,0.124725,0.36888,0.2919],[0.33846,0.124725,0.36888,0.2919],[0.33846,0.124725,0.36888,0.2919],[0.33846,0.124725,0.36888,0.2919],[0.33846,0.124725,0.36888,0.2919],[0.33846,0.124725,0.36888,0.2919],[0.33846,0.124725,0.36888,0.2919],[0.338852,0.125213,0.369963,0.291947],[0.339244,0.125702,0.371045,0.291993],[0.339636,0.12619,0.372128,0.29204],[0.341,0.126548,0.372167,0.29274],[0.342364,0.126907,0.372205,0.29344],[0.343728,0.127265,0.372244,0.29414],[0.344627,0.127753,0.372747,0.294187],[0.345525,0.128242,0.373249,0.294233],[0.346424,0.12873,0.373752,0.29428],[0.346387,0.128415,0.374293,0.294607],[0.346349,0.1281,0.374835,0.294933],[0.346312,0.127785,0.375376,0.29526],[0.346312,0.127692,0.375376,0.295633],[0.346312,0.127598,0.375376,0.296007],[0.346312,0.127505,0.375376,0.29638],[0.346312,0.127238,0.375376,0.29638],[0.346312,0.126972,0.375376,0.29638],[0.346312,0.126705,0.375376,0.29638],[0.346312,0.125893,0.375376,0.296427],[0.346312,0.125082,0.375376,0.296473],[0.346312,0.12427,0.375376,0.29652],[0.345771,0.123422,0.376459,0.296847],[0.345229,0.122573,0.377541,0.297173],[0.344688,0.121725,0.378624,0.2975],[0.344688,0.121005,0.378624,0.298247],[0.344688,0.120285,0.378624,0.298993],[0.344688,0.119565,0.378624,0.29974],[0.345117,0.119832,0.379165,0.29974],[0.345547,0.120098,0.379707,0.29974],[0.345976,0.120365,0.380248,0.29974],[0.346947,0.12127,0.379707,0.29932],[0.347917,0.122175,0.379165,0.2989],[0.348888,0.12308,0.378624,0.29848],[0.349392,0.123755,0.378083,0.29778],[0.349896,0.12443,0.377541,0.29708],[0.3504,0.125105,0.377,0.29638],[0.349896,0.124745,0.377541,0.296753],[0.349392,0.124385,0.378083,0.297127],[0.348888,0.124025,0.378624,0.2975],[0.348421,0.12371,0.378624,0.297827],[0.347955,0.123395,0.378624,0.298153],[0.347488,0.12308,0.378624,0.29848],[0.347563,0.123255,0.377541,0.29778],[0.347637,0.12343,0.376459,0.29708],[0.347712,0.123605,0.375376,0.29638],[0.347859,0.123978,0.373249,0.294887],[0.348005,0.124352,0.371123,0.293393],[0.348152,0.124725,0.368996,0.2919],[0.347293,0.125575,0.367913,0.2905],[0.346435,0.126425,0.366831,0.2891],[0.345576,0.127275,0.365748,0.2877],[0.345688,0.127995,0.364124,0.286953],[0.3458,0.128715,0.3625,0.286207],[0.345912,0.129435,0.360876,0.28546],[0.346341,0.129342,0.361417,0.285833],[0.346771,0.129248,0.361959,0.286207],[0.3472,0.129155,0.3625,0.28658],[0.346547,0.127807,0.365207,0.288773],[0.345893,0.126458,0.367913,0.290967],[0.34524,0.12511,0.37062,0.29316],[0.344231,0.124075,0.372205,0.294233],[0.343221,0.12304,0.373791,0.295307],[0.342212,0.122005,0.375376,0.29638],[0.341783,0.121738,0.374835,0.29638],[0.341353,0.121472,0.374293,0.29638],[0.340924,0.121205,0.373752,0.29638],[0.340924,0.121565,0.373752,0.296007],[0.340924,0.121925,0.373752,0.295633],[0.340924,0.122285,0.373752,0.29526],[0.340849,0.121832,0.374835,0.296007],[0.340775,0.121378,0.375917,0.296753],[0.3407,0.120925,0.377,0.2975],[0.341167,0.120832,0.377,0.297873],[0.341633,0.120738,0.377,0.298247],[0.3421,0.120645,0.377,0.29862],[0.3421,0.121005,0.377,0.298247],[0.3421,0.121365,0.377,0.297873],[0.3421,0.121725,0.377,0.2975],null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,[0.322976,0.137805,0.351248,0.27678],[0.322939,0.13763,0.351789,0.27748],[0.322901,0.137455,0.352331,0.27818],[0.322864,0.13728,0.352872,0.27888],[0.321781,0.137533,0.355037,0.28],[0.320699,0.137787,0.357203,0.28112],[0.319616,0.13804,0.359368,0.28224],[0.318103,0.13741,0.361495,0.28476],[0.316589,0.13678,0.363621,0.28728],[0.315076,0.13615,0.365748,0.2898],[0.314572,0.136057,0.366289,0.290173],[0.314068,0.135963,0.366831,0.290547],[0.313564,0.13587,0.367372,0.29092],[0.314572,0.136138,0.366289,0.289847],[0.31558,0.136407,0.365207,0.288773],[0.316588,0.136675,0.364124,0.2877],[0.316625,0.137035,0.363583,0.287327],[0.316663,0.137395,0.363041,0.286953],[0.3167,0.137755,0.3625,0.28658],[0.315225,0.137847,0.363583,0.28728],[0.313751,0.137938,0.364665,0.28798],[0.312276,0.13803,0.365748,0.28868],[0.311809,0.137843,0.365748,0.289427],[0.311343,0.137657,0.365748,0.290173],[0.310876,0.13747,0.365748,0.29092],[0.310913,0.137657,0.365207,0.290173],[0.310951,0.137843,0.364665,0.289427],[0.310988,0.13803,0.364124,0.28868],null,null,[0.126176,0.222225,0.264248,0.2079],[0.126176,0.222585,0.264248,0.207527],[0.126176,0.222945,0.264248,0.207153],[0.126176,0.223305,0.264248,0.20678],[0.126717,0.223665,0.263165,0.206407],[0.127259,0.224025,0.262083,0.206033],[0.1278,0.224385,0.261,0.20566],[0.128304,0.22506,0.260459,0.20496],[0.128808,0.225735,0.259917,0.20426],[0.129312,0.22641,0.259376,0.20356],[0.129816,0.22677,0.258835,0.203187],[0.13032,0.22713,0.258293,0.202813],[0.130824,0.22749,0.257752,0.20244],[0.131291,0.227768,0.257752,0.202393],[0.131757,0.228047,0.257752,0.202347],[0.132224,0.228325,0.257752,0.2023],[0.132691,0.227965,0.257752,0.202673],[0.133157,0.227605,0.257752,0.203047],[0.133624,0.227245,0.257752,0.20342],[0.133587,0.227245,0.258293,0.20342],[0.133549,0.227245,0.258835,0.20342],[0.133512,0.227245,0.259376,0.20342],null,null,[0.273248,0.11551,0.428504,0.33796],[0.273715,0.116043,0.428504,0.33796],[0.274181,0.116577,0.428504,0.33796],[0.274648,0.11711,0.428504,0.33796],[0.276124,0.118145,0.426919,0.336887],[0.2776,0.11918,0.425333,0.335813],[0.279076,0.120215,0.423748,0.33474],[0.280588,0.121028,0.422124,0.33362],[0.2821,0.121842,0.4205,0.3325],[0.283612,0.122655,0.418876,0.33138],[0.284583,0.123423,0.418335,0.330307],[0.285553,0.124192,0.417793,0.329233],[0.286524,0.12496,0.417252,0.32816],[0.287495,0.125053,0.416711,0.327787],[0.288465,0.125147,0.416169,0.327413],[0.289436,0.12524,0.415628,0.32704],[0.289829,0.124298,0.416208,0.32774],[0.290223,0.123357,0.416788,0.32844],[0.290616,0.122415,0.417368,0.32914],[0.290148,0.121417,0.417871,0.329933],[0.28968,0.120418,0.418373,0.330727],[0.289212,0.11942,0.418876,0.33152],[0.289212,0.118932,0.418876,0.331473],[0.289212,0.118443,0.418876,0.331427],[0.289212,0.117955,0.418876,0.33138],[0.290259,0.118583,0.416749,0.329933],[0.291305,0.119212,0.414623,0.328487],[0.292352,0.11984,0.412496,0.32704],[0.293864,0.120702,0.410872,0.325593],[0.295376,0.121563,0.409248,0.324147],[0.296888,0.122425,0.407624,0.3227],[0.297896,0.123238,0.406541,0.32158],[0.298904,0.124052,0.405459,0.32046],[0.299912,0.124865,0.404376,0.31934],[0.299875,0.124505,0.404917,0.319713],[0.299837,0.124145,0.405459,0.320087],[0.2998,0.123785,0.406,0.32046],[0.299259,0.123598,0.407083,0.321207],[0.298717,0.123412,0.408165,0.321953],[0.298176,0.123225,0.409248,0.3227],[0.2976,0.12305,0.410833,0.3234],[0.297024,0.122875,0.412419,0.3241],[0.296448,0.1227,0.414004,0.3248],[0.296877,0.122153,0.414545,0.32592],[0.297307,0.121607,0.415087,0.32704],[0.297736,0.12106,0.415628,0.32816],[0.298128,0.120873,0.416711,0.328907],[0.29852,0.120687,0.417793,0.329653],[0.298912,0.1205,0.418876,0.3304],[0.298837,0.119465,0.419959,0.331473],[0.298763,0.11843,0.421041,0.332547],[0.298688,0.117395,0.422124,0.33362],[0.298651,0.117128,0.422665,0.33362],[0.298613,0.116862,0.423207,0.33362],[0.298576,0.116595,0.423748,0.33362],[0.29908,0.116595,0.423207,0.33362],[0.299584,0.116595,0.422665,0.33362],[0.300088,0.116595,0.422124,0.33362],[0.299584,0.116862,0.422665,0.33362],[0.29908,0.117128,0.423207,0.33362],[0.298576,0.117395,0.423748,0.33362],[0.297605,0.11722,0.424289,0.33432],[0.296635,0.117045,0.424831,0.33502],[0.295664,0.11687,0.425372,0.33572],[0.295197,0.11687,0.425372,0.33572],[0.294731,0.11687,0.425372,0.33572],[0.294264,0.11687,0.425372,0.33572],[0.294301,0.117452,0.424831,0.335393],[0.294339,0.118033,0.424289,0.335067],[0.294376,0.118615,0.423748,0.33474],[0.294917,0.119068,0.422665,0.333993],[0.295459,0.119522,0.421583,0.333247],[0.296,0.119975,0.4205,0.3325],[0.296075,0.120243,0.419417,0.331427],[0.296149,0.120512,0.418335,0.330353],[0.296224,0.12078,0.417252,0.32928],[0.295795,0.120385,0.416711,0.32886],[0.295365,0.11999,0.416169,0.32844],[0.294936,0.119595,0.415628,0.32802],[0.294,0.11941,0.415667,0.327693],[0.293064,0.119225,0.415705,0.327367],[0.292128,0.11904,0.415744,0.32704],[0.292203,0.119133,0.414661,0.326667],[0.292277,0.119227,0.413579,0.326293],[0.292352,0.11932,0.412496,0.32592],[0.293397,0.120355,0.410872,0.324847],[0.294443,0.12139,0.409248,0.323773],[0.295488,0.122425,0.407624,0.3227],[0.295488,0.122958,0.407624,0.3227],[0.295488,0.123492,0.407624,0.3227],[0.295488,0.124025,0.407624,0.3227],[0.294984,0.12421,0.408165,0.323027],[0.29448,0.124395,0.408707,0.323353],[0.293976,0.12458,0.409248,0.32368],[0.294051,0.125615,0.408165,0.322607],[0.294125,0.12665,0.407083,0.321533],[0.2942,0.127685,0.406,0.32046],[0.294275,0.128672,0.404917,0.319713],[0.294349,0.129658,0.403835,0.318967],[0.294424,0.130645,0.402752,0.31822],[0.294928,0.13096,0.402211,0.317893],[0.295432,0.131275,0.401669,0.317567],[0.295936,0.13159,0.401128,0.31724],[0.296907,0.131683,0.400587,0.316867],[0.297877,0.131777,0.400045,0.316493],[0.298848,0.13187,0.399504,0.31612],[0.299315,0.131963,0.399504,0.315747],[0.299781,0.132057,0.399504,0.315373],[0.300248,0.13215,0.399504,0.315],null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,[0.30854,0.12745,0.39962,0.315],[0.309513,0.127217,0.39904,0.315],[0.310487,0.126983,0.39846,0.315],[0.31146,0.12675,0.39788,0.315],[0.312356,0.126983,0.398421,0.315],[0.313252,0.127217,0.398963,0.315],[0.314148,0.12745,0.399504,0.315],[0.313999,0.126983,0.401669,0.316867],[0.313849,0.126517,0.403835,0.318733],[0.3137,0.12605,0.406,0.3206],[0.313087,0.125513,0.408127,0.322747],[0.312473,0.124977,0.410253,0.324893],[0.31186,0.12444,0.41238,0.32704],[0.312327,0.125333,0.41238,0.326667],[0.312793,0.126227,0.41238,0.326293],[0.31326,0.12712,0.41238,0.32592],[0.314269,0.128155,0.410795,0.324847],[0.315279,0.12919,0.409209,0.323773],[0.316288,0.130225,0.407624,0.3227],[0.316288,0.130852,0.407624,0.322327],[0.316288,0.131478,0.407624,0.321953],[0.316288,0.132105,0.407624,0.32158],[0.316251,0.132278,0.408165,0.321953],[0.316213,0.132452,0.408707,0.322327],[0.316176,0.132625,0.409248,0.3227],[0.317072,0.131905,0.409789,0.323447],[0.317968,0.131185,0.410331,0.324193],[0.318864,0.130465,0.410872,0.32494],[0.321088,0.128897,0.412457,0.326013],[0.323312,0.127328,0.414043,0.327087],[0.325536,0.12576,0.415628,0.32816],[0.328228,0.124007,0.416711,0.328907],[0.33092,0.122253,0.417793,0.329653],[0.333612,0.1205,0.418876,0.3304],[0.337421,0.11984,0.417291,0.328907],[0.341231,0.11918,0.415705,0.327413],[0.34504,0.11852,0.41412,0.32592],[0.347956,0.117848,0.411955,0.324473],[0.350872,0.117177,0.409789,0.323027],[0.353788,0.116505,0.407624,0.32158],[0.352533,0.115973,0.406,0.320507],[0.351279,0.115442,0.404376,0.319433],[0.350024,0.11491,0.402752,0.31836],[0.345108,0.115237,0.400084,0.31612],[0.340192,0.115563,0.397416,0.31388],[0.335276,0.11589,0.394748,0.31164],[0.329893,0.11666,0.39208,0.309493],[0.324511,0.11743,0.389412,0.307347],[0.319128,0.1182,0.386744,0.3052],null,null]}];
}
</sheet>
diff --git a/examples/interview/wojak-tracking.svs b/examples/interview/wojak-tracking.svs
index c119dd90..d16afb7f 100644
--- a/examples/interview/wojak-tracking.svs
+++ b/examples/interview/wojak-tracking.svs
@@ -1,7 +1,6 @@
<?svml using="@hypit/svs@1"?>
<sheet version="1">
heads.wojak {
- frame-count: 783;
- tracks: [{"id":"WOJAK","regions":[[0.091014,0.270142,0.311582,0.268186],[0.092949,0.270639,0.313034,0.26889],[0.095175,0.27117,0.314465,0.269494],[0.098532,0.272119,0.315956,0.269737],[0.102426,0.273197,0.31737,0.26973],[0.106575,0.274415,0.317578,0.268767],[0.110768,0.275768,0.31718,0.267262],[0.113933,0.276658,0.316578,0.266039],[0.116563,0.277249,0.316179,0.265229],[0.118286,0.277476,0.31638,0.265096],[0.119113,0.277408,0.316982,0.265369],[0.119579,0.27734,0.317788,0.265642],[0.11971,0.27734,0.318393,0.265642],[0.119681,0.277408,0.318798,0.265369],[0.119667,0.277476,0.319,0.265096],[0.11932,0.277544,0.319,0.264823],[0.118278,0.277413,0.319,0.264958],[0.115995,0.276919,0.319399,0.26577],[0.112701,0.276132,0.319391,0.266584],[0.109089,0.27505,0.318976,0.2674],[0.104985,0.273919,0.318155,0.26725],[0.101117,0.272924,0.316343,0.266153],[0.097057,0.272095,0.314739,0.264785],[0.092115,0.27133,0.31334,0.26315],[0.087679,0.27065,0.312143,0.262342],[0.083582,0.270107,0.311136,0.261389],[0.079803,0.269493,0.310534,0.260711],[0.077038,0.26894,0.310335,0.260577],[0.074232,0.268355,0.310737,0.260577],[0.07172,0.267726,0.311943,0.26153],[0.069914,0.26719,0.31295,0.262896],[0.068468,0.266817,0.313758,0.263994],[0.067759,0.266678,0.313961,0.264544],[0.067439,0.266679,0.313559,0.264543],[0.067293,0.266851,0.313157,0.263858],[0.06732,0.267021,0.312755,0.263175],[0.067333,0.267123,0.312555,0.262767],[0.067333,0.267225,0.312555,0.262358],[0.067333,0.267259,0.312555,0.262221],[0.067333,0.267327,0.312555,0.261948],[0.067333,0.267361,0.312555,0.261812],[0.067333,0.267326,0.312555,0.26195],[0.067333,0.267291,0.312555,0.262089],[0.067333,0.267189,0.312555,0.262499],[0.067333,0.267086,0.312555,0.262909],[0.067333,0.26695,0.312555,0.263454],[0.067333,0.266982,0.312555,0.263722],[0.067333,0.267082,0.312555,0.263718],[0.067333,0.267216,0.312555,0.263576],[0.067333,0.267451,0.312555,0.263028],[0.067333,0.267362,0.312555,0.263068],[0.067333,0.267224,0.312555,0.263329],[0.067333,0.267075,0.312555,0.263586],[0.22119,0.163172,0.445952,0.347344],[0.221138,0.162728,0.446399,0.349124],[0.221766,0.162259,0.447023,0.350992],[0.222735,0.161928,0.44828,0.352305],[0.224175,0.161649,0.450087,0.353411],[0.226293,0.161647,0.452101,0.353414],[0.228262,0.161821,0.453719,0.352726],[0.229726,0.162096,0.455131,0.351628],[0.230698,0.162507,0.456139,0.349986],[0.230991,0.162848,0.456943,0.348621],[0.230733,0.163153,0.458151,0.347396],[0.230503,0.16339,0.458958,0.346444],[0.229652,0.163424,0.458751,0.346306],[0.228009,0.163425,0.457524,0.346305],[0.225959,0.163426,0.454679,0.346304],[0.22329,0.163427,0.450643,0.346301],[0.221277,0.163598,0.44703,0.345617],[0.220069,0.163803,0.444238,0.344798],[0.219609,0.163838,0.443248,0.344658],[0.219903,0.16377,0.444048,0.345332],[0.22029,0.163338,0.446053,0.347885],[0.220804,0.162591,0.448671,0.352084],[0.221168,0.161793,0.450893,0.356454],[0.221386,0.16088,0.452715,0.360857],[0.2213,0.160205,0.453928,0.363906],[0.221071,0.15979,0.454734,0.365158],[0.220842,0.15955,0.455539,0.365714],[0.220599,0.159424,0.456545,0.365439],[0.220683,0.159343,0.457337,0.36472],[0.220762,0.159289,0.458048,0.364295],[0.220857,0.159214,0.458841,0.363776],[0.067333,0.266552,0.312555,0.265084],[0.067333,0.266957,0.312555,0.263467],[0.067333,0.26728,0.312555,0.26217],[0.067333,0.267443,0.312555,0.261513],[0.067333,0.267506,0.312555,0.261248],[0.067333,0.267437,0.312555,0.261524],[0.067333,0.267468,0.312555,0.261393],[0.067333,0.2675,0.312555,0.261261],[0.067333,0.267533,0.312555,0.261128],[0.067333,0.2676,0.312555,0.260857],[0.067333,0.267601,0.312555,0.260854],[0.067333,0.26774,0.312555,0.260303],[0.067333,0.268014,0.312555,0.259207],[0.067333,0.268185,0.312555,0.258523],[0.067333,0.268356,0.312555,0.25784],[0.067333,0.268425,0.312555,0.257566],[0.067333,0.268392,0.312555,0.257699],[0.067333,0.268493,0.312555,0.257292],[0.067333,0.268526,0.312555,0.257158],[0.067333,0.268524,0.312555,0.257162],[0.067333,0.268488,0.312555,0.257302],[0.067333,0.268351,0.312555,0.257849],[0.067333,0.268148,0.312555,0.258666],[0.067146,0.267845,0.312755,0.259887],[0.066772,0.267539,0.313157,0.261114],[0.06621,0.267266,0.31376,0.262207],[0.065648,0.267128,0.314364,0.262757],[0.06546,0.267194,0.314565,0.262488],[0.06546,0.267227,0.314565,0.262354],[0.065835,0.267225,0.314162,0.262357],[0.06621,0.26719,0.31376,0.262497],[0.066397,0.267087,0.313559,0.262908],[0.066772,0.267191,0.313157,0.262493],[0.066959,0.267435,0.312956,0.261528],[0.067146,0.267745,0.312755,0.260293],[0.067333,0.26812,0.312555,0.258791],[0.067333,0.268356,0.312555,0.25784],[0.067333,0.26849,0.312555,0.257299],[0.067333,0.268557,0.312555,0.257029],[0.067333,0.268626,0.312555,0.256754],[0.067333,0.268729,0.312555,0.256343],[0.067333,0.268798,0.312555,0.256068],[0.067333,0.268867,0.312555,0.255793],[0.067333,0.268799,0.312555,0.256065],[0.067333,0.268662,0.312555,0.256613],[0.067333,0.268593,0.312555,0.256889],[0.067333,0.268523,0.312555,0.257164],[0.067333,0.268557,0.312555,0.257029],[0.067333,0.268625,0.312555,0.256755],[0.067333,0.268659,0.312555,0.256619],[0.067333,0.268727,0.312555,0.256346],[0.067333,0.268727,0.312555,0.256346],[0.067333,0.268693,0.312555,0.256482],[0.067333,0.268625,0.312555,0.256755],[0.067333,0.268557,0.312555,0.257028],[0.067333,0.268593,0.312555,0.256889],[0.067333,0.268662,0.312555,0.256613],[0.067146,0.268667,0.312755,0.256604],[0.066772,0.268436,0.313157,0.257543],[0.066397,0.26803,0.313559,0.259175],[0.066023,0.267585,0.313961,0.260955],[0.065935,0.267276,0.314055,0.262179],[0.066181,0.267239,0.313791,0.262315],[0.066435,0.267304,0.313518,0.262049],[0.222173,0.156815,0.463989,0.360902],[0.222296,0.157021,0.463741,0.360898],[0.221404,0.157607,0.463119,0.360026],[0.219394,0.158473,0.461732,0.358718],[0.215942,0.15906,0.459088,0.358716],[0.210291,0.159573,0.455459,0.359399],[0.203892,0.159853,0.452458,0.360625],[0.196333,0.160099,0.451084,0.361989],[0.187979,0.160815,0.451299,0.361856],[0.180045,0.161539,0.453105,0.361308],[0.171359,0.162229,0.455721,0.361294],[0.163713,0.162411,0.458338,0.362924],[0.157294,0.162571,0.46076,0.364262],[0.151756,0.16305,0.462982,0.364349],[0.14817,0.163916,0.464598,0.36211],[0.145669,0.165451,0.465607,0.356764],[0.144425,0.166683,0.466011,0.352174],[0.144078,0.167595,0.466011,0.348434],[0.144092,0.168147,0.46581,0.346169],[0.144092,0.168283,0.46581,0.345622],[0.143717,0.168386,0.466213,0.345213],[0.143341,0.168385,0.466616,0.345214],[0.143154,0.168385,0.466818,0.345214],[0.143341,0.168419,0.466616,0.345077],[0.143904,0.168488,0.466011,0.344803],[0.144467,0.168625,0.465407,0.344256],[0.144654,0.168727,0.465206,0.343846],[0.144467,0.168795,0.465407,0.343573],[0.143904,0.168829,0.466011,0.343437],[0.143529,0.168829,0.466414,0.343437],[0.143168,0.168863,0.466616,0.3433],[0.14282,0.168932,0.466616,0.343026],[0.142127,0.169007,0.466615,0.342339],[0.140724,0.169087,0.466815,0.341242],[0.139336,0.169102,0.466814,0.34001],[0.137774,0.169087,0.466813,0.338506],[0.13676,0.1691,0.46641,0.337279],[0.135706,0.169142,0.466609,0.336324],[0.134436,0.169249,0.467413,0.335506],[0.133499,0.169317,0.46842,0.335233],[0.132159,0.169283,0.470231,0.335369],[0.131367,0.169148,0.471642,0.335914],[0.131297,0.168875,0.472649,0.337005],[0.131777,0.168665,0.473252,0.338236],[0.133557,0.168586,0.472644,0.339331],[0.136071,0.168576,0.471435,0.340154],[0.138409,0.168702,0.47023,0.340428],[0.139837,0.168736,0.469631,0.340291],[0.140195,0.168662,0.469795,0.339936],[0.13978,0.168594,0.470439,0.339566],[0.13888,0.168461,0.471407,0.339281],null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,[0.779503,0.42461,0.220495,0.457184],[0.779387,0.424322,0.22061,0.45752],[0.779403,0.423991,0.220595,0.458205],[0.779503,0.423673,0.220495,0.458825],[0.779503,0.42337,0.220495,0.459645],[0.779503,0.423297,0.220495,0.46033],[0.77969,0.423292,0.220307,0.460739],[0.780065,0.423356,0.219933,0.460875],[0.780439,0.423653,0.219559,0.460466],[0.780813,0.423721,0.219186,0.460193],[0.781,0.423658,0.219,0.460057],[0.781,0.423428,0.219,0.460194],[0.780813,0.422803,0.219186,0.460741],[0.780439,0.422344,0.219559,0.461015],[0.780065,0.422051,0.219933,0.461015],[0.779603,0.421875,0.220395,0.460833],[0.779387,0.422043,0.22061,0.460384],[0.779503,0.42218,0.220495,0.46003],[0.197991,0.149644,0.492352,0.38082],[0.201401,0.148874,0.491001,0.382924],[0.20689,0.14816,0.488443,0.38493],[0.213307,0.147885,0.484672,0.38588],[0.222091,0.147473,0.480645,0.387926],[0.232026,0.147931,0.477442,0.387252],[0.241474,0.148558,0.476255,0.386303],[0.251497,0.148948,0.476868,0.385902],[0.259598,0.149577,0.47768,0.384146],[0.265615,0.149636,0.478493,0.384292],[0.270113,0.149398,0.478699,0.384847],[0.272183,0.149125,0.478899,0.385537],[0.273356,0.14865,0.479503,0.387045],[0.273662,0.148278,0.480107,0.388141],[0.273273,0.148106,0.480712,0.388826],[0.272925,0.148002,0.480714,0.389238],[0.272591,0.148002,0.480513,0.389238],[0.272244,0.148169,0.480513,0.388964],[0.271883,0.148467,0.480714,0.388553],[0.271321,0.148765,0.481317,0.388143],[0.270571,0.148961,0.482123,0.388142],[0.270008,0.148893,0.482728,0.388415],[0.269633,0.148595,0.483132,0.388824],[0.269445,0.148332,0.483334,0.389098],[0.269445,0.148204,0.483334,0.388824],[0.269445,0.148243,0.483334,0.388278],[0.269445,0.148414,0.483334,0.387595],[0.269459,0.148418,0.483132,0.387186],[0.269487,0.148223,0.482728,0.387185],[0.269718,0.148029,0.48192,0.387183],[0.270149,0.147766,0.48071,0.387456],[0.270739,0.147731,0.479703,0.387593],[0.271302,0.147927,0.479099,0.387593],[0.271462,0.148019,0.4793,0.388004],[0.271219,0.148111,0.480305,0.388415],[0.270817,0.14814,0.481111,0.388689],[0.270441,0.148105,0.481515,0.388827],[0.270268,0.148306,0.481515,0.388416],[0.270296,0.148707,0.481111,0.387594],[0.270108,0.149039,0.481313,0.387047],[0.269718,0.149303,0.481919,0.386773],[0.269155,0.149269,0.482525,0.386909],[0.268417,0.148903,0.483132,0.387593],[0.267709,0.148571,0.483334,0.388141],[0.267188,0.148272,0.483334,0.388552],[0.266841,0.148037,0.483334,0.3891],[0.266667,0.147901,0.483334,0.389645],[0.266306,0.148014,0.483535,0.389214],[0.265584,0.148375,0.483936,0.38781],[0.26398,0.148767,0.484539,0.386274],[0.261508,0.14906,0.485143,0.384742],[0.258731,0.148734,0.485142,0.385276],[0.25601,0.147913,0.484831,0.387643],[0.254012,0.147013,0.48407,0.38994],[0.252526,0.146193,0.483004,0.392161],[0.073111,0.266338,0.309334,0.259653],[0.073111,0.266174,0.309334,0.260309],[0.073111,0.265993,0.309334,0.261036],[0.073111,0.265765,0.309334,0.261947],[0.073111,0.265525,0.309334,0.262905],[0.073111,0.265353,0.309334,0.26359],[0.073111,0.265319,0.309334,0.263727],[0.073111,0.26532,0.309334,0.263725],[0.073111,0.26539,0.309334,0.263449],[0.073111,0.265459,0.309334,0.263174],[0.073111,0.265391,0.309334,0.263447],[0.073111,0.265529,0.309334,0.262896],[0.073111,0.265668,0.309334,0.262345],[0.073111,0.265875,0.309334,0.261521],[0.073111,0.26625,0.309334,0.26002],[0.073111,0.266384,0.309334,0.259479],[0.073111,0.266518,0.309334,0.258937],[0.073111,0.26655,0.309334,0.258806],[0.073111,0.266481,0.309334,0.25908],[0.073111,0.266515,0.309334,0.258943],[0.073111,0.266501,0.309334,0.258998],[0.073111,0.266552,0.309334,0.258796],[0.073111,0.26661,0.309334,0.258561],[0.234654,0.166408,0.440139,0.347544],[0.236231,0.167296,0.438436,0.344856],[0.239679,0.168313,0.434903,0.341865],[0.244917,0.169525,0.42961,0.338411],[0.251073,0.170511,0.423547,0.33599],[0.25756,0.171157,0.417344,0.334933],[0.261796,0.171675,0.413387,0.334404],[0.262509,0.171966,0.413176,0.334408],[0.260445,0.172131,0.415743,0.334137],[0.255957,0.172067,0.420726,0.334001],[0.250106,0.17174,0.427566,0.334138],[0.245538,0.171413,0.433056,0.334274],[0.24209,0.171117,0.437347,0.334681],[0.239573,0.170919,0.440819,0.335086],[0.238258,0.170618,0.442234,0.336304],[0.236969,0.170043,0.443249,0.338616],[0.236043,0.169395,0.44406,0.341211],[0.235522,0.168774,0.44406,0.343685],[0.235724,0.16839,0.443655,0.345204],[0.236302,0.16832,0.442847,0.345481],[0.23711,0.168422,0.441232,0.345072],[0.238103,0.168523,0.439419,0.344663],[0.238719,0.168591,0.438013,0.344392],[0.239108,0.168598,0.437408,0.343978],[0.239416,0.168541,0.438007,0.343426],[0.240376,0.168489,0.439212,0.342466],[0.242203,0.168371,0.44042,0.341373],[0.245328,0.168078,0.440418,0.341774],[0.24961,0.167618,0.438799,0.34365],[0.2536,0.166948,0.436375,0.347158],[0.257263,0.166178,0.433563,0.351805],[0.259826,0.165534,0.431562,0.355524],[0.261108,0.165278,0.430562,0.356915],[0.261828,0.165453,0.430163,0.355823],[0.261828,0.165816,0.430163,0.353213],[0.261668,0.166309,0.429962,0.349667],[0.261508,0.166618,0.429761,0.347234],[0.261161,0.16679,0.429761,0.345746],[0.261175,0.167064,0.42956,0.344251],[0.261175,0.167235,0.42956,0.343567],[0.260987,0.167372,0.429761,0.34302],[0.260987,0.167441,0.429761,0.342746],[0.2608,0.167141,0.429962,0.344361],[0.260425,0.166735,0.430365,0.346394],[0.260425,0.166223,0.430365,0.349244],[0.260425,0.16577,0.430365,0.351839],[0.260237,0.165736,0.430567,0.351976],[0.260237,0.165912,0.430567,0.351281],[0.26005,0.166541,0.430768,0.347993],[0.259912,0.16711,0.430916,0.344968],[0.260035,0.167584,0.430784,0.342706],[0.260312,0.168154,0.430486,0.33991],null,null,null,null,[0.071013,0.266423,0.311585,0.26556],[0.071036,0.266558,0.31156,0.265021],[0.070913,0.266716,0.311693,0.264391],[0.07105,0.266883,0.311545,0.263725],[0.071426,0.267088,0.311142,0.262905],[0.071988,0.267224,0.310538,0.262359],[0.072363,0.26719,0.310136,0.262496],[0.072363,0.267055,0.310136,0.26304],[0.071988,0.266851,0.310538,0.263858],[0.071426,0.266716,0.311142,0.264402],[0.071238,0.266822,0.311343,0.263984],[0.071238,0.266963,0.311343,0.263428],[0.071426,0.267071,0.311142,0.263008],[0.071426,0.266938,0.311142,0.263546],[0.07105,0.266703,0.311545,0.264496],[0.070675,0.266708,0.311949,0.264485],[0.070312,0.266861,0.312339,0.263883],[0.070111,0.267355,0.312555,0.261914],[0.070111,0.267879,0.312555,0.259806],[0.237056,0.1709,0.441445,0.331404],[0.237505,0.170614,0.441445,0.331488],[0.237875,0.170501,0.441659,0.331331],[0.237931,0.170475,0.441846,0.330994],[0.237918,0.170445,0.442047,0.330721],[0.237557,0.170479,0.442248,0.330585],[0.237223,0.170445,0.442047,0.330721],[0.237251,0.170343,0.441644,0.331131],[0.237106,0.170172,0.441241,0.331814],[0.237321,0.170035,0.440637,0.332361],[0.23771,0.169967,0.440032,0.332635],[0.237911,0.169967,0.439629,0.332634],[0.238423,0.170075,0.439079,0.332205],[0.238761,0.170212,0.438716,0.331655],[0.238923,0.17033,0.438543,0.331184],null,null,null,null,null,[0.230954,0.170997,0.433369,0.332913],[0.2307,0.171957,0.431761,0.330954],[0.230132,0.172656,0.430476,0.329407],[0.229232,0.173254,0.429555,0.328502],[0.228056,0.173256,0.428957,0.329298],[0.227029,0.172689,0.428754,0.331194],[0.226523,0.172117,0.428551,0.333101],[0.226364,0.171719,0.428347,0.333917],[0.226753,0.172025,0.427743,0.332289],[0.22694,0.172495,0.427543,0.330392],[0.226766,0.172891,0.427544,0.328779],[0.226606,0.172951,0.427344,0.328122],[0.226276,0.172757,0.427264,0.328559],[0.226122,0.172526,0.426818,0.329131],[0.226157,0.172275,0.426298,0.329654],null,[0.226223,0.172822,0.425334,0.327467],[0.226223,0.172785,0.425334,0.327616],[0.226209,0.172662,0.425548,0.328114],[0.226182,0.172426,0.425936,0.329065],[0.226328,0.172017,0.426338,0.330704],[0.226648,0.171639,0.42674,0.332212],[0.227328,0.171264,0.426941,0.333313],[0.228356,0.171098,0.427141,0.333587],[0.229357,0.17121,0.427743,0.332757],[0.230517,0.171458,0.428548,0.331382],[0.231503,0.172,0.429354,0.329605],[0.232342,0.172333,0.429759,0.328655],[0.233223,0.172462,0.42956,0.328525],[0.233771,0.172489,0.429157,0.328802],[0.234146,0.172318,0.428756,0.329486],[0.234333,0.172317,0.428555,0.329488],[0.234333,0.172419,0.428555,0.329078],[0.234146,0.172556,0.428756,0.328532],[0.233771,0.172726,0.429157,0.32785],[0.233196,0.172795,0.429961,0.327576],[0.23242,0.172795,0.431167,0.327574],[0.231815,0.172694,0.432376,0.327982],[0.231398,0.172489,0.433384,0.328802],[0.231196,0.172317,0.433789,0.329487],[0.23121,0.172214,0.433587,0.3299],[0.231251,0.172213,0.432983,0.329901],[0.23148,0.172316,0.432178,0.32949],[0.231695,0.172254,0.431574,0.329351],[0.231896,0.172089,0.431172,0.329621],[0.232272,0.171891,0.430768,0.330028],[0.232459,0.171657,0.430567,0.330574],[0.232634,0.171823,0.430565,0.3303],[0.232808,0.172125,0.430563,0.329481],[0.232607,0.172461,0.430965,0.328526],[0.232205,0.17283,0.43177,0.327437],[0.231815,0.172965,0.432376,0.326893],[0.231412,0.173067,0.433183,0.326483],[0.231182,0.173135,0.433991,0.326211],[0.231156,0.173167,0.434354,0.326083],[0.231129,0.173203,0.434751,0.325938],[0.231111,0.173203,0.435,0.325938],null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,[0.223222,0.171566,0.428555,0.338743],[0.223222,0.171409,0.428555,0.339368],null,[0.232157,0.170974,0.435964,0.338614],[0.236583,0.170324,0.436236,0.339387],[0.24291,0.169459,0.435847,0.34051],[0.249207,0.168695,0.434572,0.341242],[0.255789,0.167933,0.432346,0.342337],[0.261191,0.1673,0.429527,0.343701],[0.264288,0.166863,0.427327,0.345064],[0.266288,0.166418,0.425932,0.346842],[0.267368,0.16604,0.425334,0.34835],[0.267715,0.165832,0.425334,0.349176],[0.267903,0.165797,0.425132,0.349314],[0.267917,0.1659,0.42493,0.348903],[0.267946,0.166071,0.424526,0.348219],[0.267988,0.166208,0.423921,0.347673],[0.268002,0.166276,0.423719,0.347401],[0.268203,0.166511,0.423317,0.346851],[0.268564,0.166914,0.423116,0.346027],[0.268711,0.167316,0.423516,0.345204],[0.268684,0.167683,0.423916,0.344518],[0.268095,0.167717,0.42492,0.344382],[0.267143,0.16735,0.426129,0.345066],[0.266392,0.167052,0.426936,0.345478],[0.265828,0.166821,0.427544,0.345617],[0.265639,0.166688,0.427747,0.345756],[0.265452,0.166789,0.427949,0.345347],[0.265278,0.166955,0.427949,0.345074],[0.264917,0.167054,0.42815,0.345073],[0.264535,0.167217,0.428337,0.34489],[0.264268,0.167415,0.428301,0.344775],[0.263759,0.167303,0.42887,0.345177],[0.071913,0.265684,0.310618,0.262273],[0.07242,0.265714,0.310074,0.262154],[0.072712,0.26556,0.309762,0.262776],[0.072924,0.265361,0.309534,0.263576],[0.073111,0.265156,0.309334,0.264395],[0.073111,0.265088,0.309334,0.264669],[0.073111,0.265257,0.309334,0.263987],[0.073111,0.265495,0.309334,0.263033],[0.073111,0.265766,0.309334,0.261945],[0.073111,0.265934,0.309334,0.261268],[0.073111,0.266002,0.309334,0.260994],[0.073111,0.266036,0.309334,0.260858],[0.073111,0.266002,0.309334,0.260994],[0.073111,0.265934,0.309334,0.261268],[0.073111,0.265865,0.309334,0.261541],[0.073111,0.265832,0.309334,0.261677],[0.073111,0.265832,0.309334,0.261675],[0.073111,0.265965,0.309334,0.261537],[0.073111,0.266264,0.309334,0.261125],[0.073111,0.266626,0.309334,0.260851],[0.073111,0.267224,0.309334,0.260025],[0.073111,0.267758,0.309334,0.258984],[0.073111,0.26817,0.309334,0.258108],[0.073111,0.268618,0.309334,0.256797],[0.234942,0.163511,0.444004,0.34601],[0.236342,0.163748,0.442914,0.345064],[0.238237,0.163691,0.441858,0.345284],[0.240221,0.163855,0.441433,0.344625],[0.242837,0.164225,0.441235,0.343131],[0.245121,0.164389,0.440834,0.342461],[0.247059,0.164522,0.440432,0.341923],[0.248663,0.164321,0.439829,0.342734],[0.249571,0.163785,0.439227,0.3445],[0.250106,0.163175,0.439026,0.34655],[0.25028,0.162665,0.439026,0.348196],[0.25028,0.162599,0.439026,0.348064],[0.250266,0.162973,0.439227,0.346965],[0.250238,0.163586,0.439629,0.344908],[0.250197,0.164329,0.440234,0.342318],[0.250155,0.164832,0.440839,0.340687],[0.250126,0.165101,0.441243,0.339603],[0.249925,0.1652,0.441646,0.339199],[0.24955,0.165065,0.442047,0.339742],[0.249175,0.164862,0.442449,0.340559],[0.248801,0.164589,0.442851,0.341651],[0.248627,0.164315,0.442851,0.342746],[0.248467,0.164177,0.44265,0.343297],[0.24776,0.164107,0.44285,0.343573],[0.246121,0.164006,0.444044,0.34398],[0.243706,0.163838,0.446442,0.344658],[0.240549,0.1636,0.449457,0.345612],[0.237212,0.163397,0.452486,0.34643],[0.234677,0.16353,0.453911,0.346291],[0.232402,0.163832,0.45412,0.345471],[0.230866,0.164168,0.453719,0.344516],[0.230072,0.164453,0.45282,0.343865],[0.22903,0.164378,0.452839,0.343936],[0.228481,0.164237,0.453038,0.344307],null,[0.229353,0.163664,0.448515,0.349752],[0.229212,0.163828,0.449215,0.34888],[0.22946,0.16391,0.448951,0.34907],[0.229604,0.163976,0.448846,0.349111],null,[0.231823,0.164941,0.448853,0.346494],[0.232275,0.165118,0.449125,0.345786],[0.232527,0.165342,0.44939,0.34489],[0.232731,0.16557,0.449296,0.343978],[0.232918,0.165746,0.449095,0.342884],[0.232918,0.165824,0.449095,0.34179],[0.232731,0.165834,0.449296,0.34097],[0.232342,0.165478,0.4499,0.341233],[0.231779,0.165015,0.450505,0.342315],[0.231244,0.164712,0.450707,0.343536],[0.231084,0.164512,0.450505,0.344346],[0.231126,0.164679,0.4499,0.344071],[0.231342,0.164982,0.449296,0.343249],[0.231355,0.16485,0.449095,0.343387],[0.230994,0.164309,0.449296,0.344762],[0.230605,0.163664,0.4499,0.346549],[0.230216,0.16305,0.450505,0.348208],[0.230202,0.162908,0.450707,0.348765],[0.23039,0.163178,0.450505,0.348078],[0.230794,0.163682,0.449697,0.346846],[0.231399,0.164282,0.448487,0.345617],[0.231736,0.164685,0.447453,0.344599],[0.23225,0.165097,0.446397,0.343941],[0.232601,0.165337,0.44563,0.343655],null,null,null,[0.233222,0.164517,0.444666,0.342559],[0.233008,0.16472,0.444666,0.342087],[0.232837,0.165107,0.44488,0.341244],[0.23266,0.165614,0.445269,0.340286],[0.232459,0.16598,0.445671,0.339603],[0.23262,0.166409,0.445871,0.339056],[0.232823,0.16644,0.445466,0.339328],[0.233052,0.166269,0.444659,0.340012],[0.233281,0.166166,0.443855,0.340423],[0.233295,0.166069,0.443654,0.340421],[0.233253,0.166338,0.444258,0.339737],[0.232997,0.166641,0.445464,0.338917],[0.232726,0.166811,0.446875,0.338235],[0.232481,0.166711,0.447884,0.338238],[0.232092,0.166315,0.44849,0.338649],[0.232091,0.165852,0.448491,0.339332],[0.232119,0.165617,0.448088,0.339879],[0.232335,0.165585,0.447483,0.340013],[0.233085,0.165752,0.446678,0.339736],[0.233661,0.165923,0.445872,0.339052],[0.234036,0.165864,0.44547,0.338506],[0.233876,0.165571,0.445269,0.338907],[0.232994,0.165106,0.44547,0.339992],[0.231911,0.16467,0.446073,0.341352],[0.230855,0.164124,0.446275,0.343538],[0.230177,0.163846,0.446069,0.344642],[0.2297,0.16357,0.445461,0.345741],[0.229235,0.163327,0.444653,0.346706],[0.228917,0.163395,0.444248,0.346433],[0.228382,0.163429,0.444451,0.346296],[0.228209,0.163738,0.44445,0.345064],[0.228237,0.164078,0.444046,0.343699],[0.228479,0.164589,0.443041,0.342052],[0.229082,0.165334,0.441836,0.33986],[0.229468,0.165976,0.441238,0.338078],[0.230001,0.166681,0.441041,0.336032],[0.23032,0.167018,0.441443,0.334674],[0.230466,0.166957,0.441846,0.334134],[0.230626,0.166827,0.442047,0.333866],[0.230612,0.166597,0.442248,0.334003],[0.230626,0.166431,0.442047,0.334277],[0.230626,0.166397,0.442047,0.334414],[0.230612,0.166494,0.442248,0.334414],[0.230585,0.166724,0.44265,0.334277],[0.230535,0.167032,0.443375,0.333957],[0.230497,0.167465,0.443921,0.333508],[0.230467,0.167806,0.444343,0.333155],null,null,null,[0.064333,0.26708,0.315778,0.262934],[0.064333,0.26698,0.315778,0.263336],[0.064333,0.266791,0.315778,0.264095],[0.064333,0.26651,0.315778,0.265223],[0.064333,0.266237,0.315778,0.266316],[0.064333,0.265996,0.315778,0.267276],[0.064333,0.265858,0.315778,0.267826],[0.064333,0.265757,0.315778,0.268232],[0.064333,0.265623,0.315778,0.268774],[0.064333,0.265385,0.315778,0.269729],[0.064333,0.265216,0.315778,0.27041],[0.064333,0.265252,0.315778,0.270269],[0.064333,0.265564,0.315778,0.269029],[0.064333,0.266149,0.315778,0.266697],[0.064333,0.266656,0.315778,0.264657],[0.064333,0.267059,0.315778,0.263031],[0.064333,0.267295,0.315778,0.262081],[0.064333,0.26733,0.315778,0.261943],[0.064333,0.267398,0.315778,0.261671],[0.064333,0.267466,0.315778,0.261397],[0.064333,0.267465,0.315778,0.261399],[0.064333,0.267532,0.315778,0.261129],[0.064333,0.2676,0.315778,0.260857],[0.064333,0.267633,0.315778,0.260722],[0.064333,0.267771,0.315778,0.260173],[0.064333,0.267943,0.315778,0.259487],[0.064333,0.268081,0.315778,0.258938],[0.064333,0.268287,0.315778,0.258116],[0.064333,0.268423,0.315778,0.257569],[0.064333,0.268393,0.315778,0.257297],[0.064333,0.268368,0.315778,0.256614],[0.064333,0.268208,0.315778,0.256477],[0.064333,0.268081,0.315778,0.256202],[0.064333,0.268185,0.315778,0.25579],[0.064333,0.268382,0.315778,0.255786],[0.064333,0.268679,0.315778,0.255377],[0.064333,0.268874,0.315778,0.255378],[0.064333,0.268903,0.315778,0.255654],[0.064333,0.268799,0.315778,0.256067],[0.064333,0.268695,0.315778,0.256479],[0.064333,0.268694,0.315778,0.256481],[0.064333,0.268762,0.315778,0.256208],[0.064333,0.268797,0.315778,0.25607],[0.064333,0.268731,0.315778,0.256339],[0.064333,0.268562,0.315778,0.257017],[0.064333,0.268222,0.315778,0.258382],[0.064333,0.267981,0.315778,0.259343],[0.064333,0.267948,0.315778,0.259476],[0.064333,0.268125,0.315778,0.258781],[0.064333,0.26851,0.315778,0.256858],[0.064333,0.269029,0.315778,0.254393],[0.064333,0.269369,0.315778,0.252554],[0.064333,0.269575,0.315778,0.251043],[0.064333,0.269895,0.315778,0.249804],[0.24197,0.162064,0.443005,0.348014],[0.246993,0.162021,0.440844,0.347125],[0.252708,0.161883,0.436991,0.347069],[0.260441,0.161791,0.431201,0.347387],[0.268626,0.161648,0.425595,0.348345],[0.27552,0.161666,0.420834,0.349442],[0.281082,0.161849,0.417871,0.350267],[0.284086,0.161902,0.417071,0.351225],[0.285461,0.161796,0.417273,0.352042],[0.285219,0.161425,0.418278,0.353135],[0.283399,0.160961,0.419486,0.35382],[0.280884,0.160604,0.420697,0.353684],[0.278585,0.160518,0.421303,0.352861],[0.276675,0.160699,0.421303,0.351356],[0.275835,0.160942,0.4209,0.349993],[0.276064,0.161346,0.420094,0.348765],[0.276814,0.161745,0.419289,0.347947],[0.278085,0.16214,0.418483,0.347538],[0.279341,0.162633,0.417879,0.347128],[0.280237,0.16296,0.417476,0.346991],[0.280237,0.163224,0.417476,0.346717],[0.279341,0.163458,0.417879,0.34617],[0.277737,0.163463,0.418483,0.34576],[0.275786,0.163405,0.419088,0.345213],[0.274369,0.163248,0.419491,0.344666],[0.2733,0.162926,0.419893,0.344393],[0.272765,0.162736,0.420094,0.343983],[0.272391,0.162575,0.420497,0.343846],[0.272015,0.162477,0.4209,0.343846],[0.272015,0.162477,0.4209,0.343846],[0.272203,0.162409,0.420698,0.344119],[0.272765,0.162341,0.420094,0.344392],[0.273327,0.162172,0.419491,0.345072],[0.273688,0.161899,0.41929,0.346164],[0.273848,0.161592,0.419491,0.347394],[0.273821,0.161317,0.419893,0.34849],[0.273793,0.161213,0.420296,0.348903],[0.273793,0.161282,0.420296,0.348629],[0.273821,0.161558,0.419893,0.347531],[0.273848,0.161935,0.419491,0.346024],[0.273688,0.162242,0.41929,0.344794],[0.273327,0.162514,0.419491,0.343703],[0.272765,0.162616,0.420094,0.343295],[0.27209,0.162581,0.420819,0.343433],[0.271582,0.16258,0.421365,0.343434],[0.27119,0.162525,0.421788,0.343654]]}];
+ series: [{"id":"WOJAK","regions":[[0.091014,0.270142,0.311582,0.268186],[0.092949,0.270639,0.313034,0.26889],[0.095175,0.27117,0.314465,0.269494],[0.098532,0.272119,0.315956,0.269737],[0.102426,0.273197,0.31737,0.26973],[0.106575,0.274415,0.317578,0.268767],[0.110768,0.275768,0.31718,0.267262],[0.113933,0.276658,0.316578,0.266039],[0.116563,0.277249,0.316179,0.265229],[0.118286,0.277476,0.31638,0.265096],[0.119113,0.277408,0.316982,0.265369],[0.119579,0.27734,0.317788,0.265642],[0.11971,0.27734,0.318393,0.265642],[0.119681,0.277408,0.318798,0.265369],[0.119667,0.277476,0.319,0.265096],[0.11932,0.277544,0.319,0.264823],[0.118278,0.277413,0.319,0.264958],[0.115995,0.276919,0.319399,0.26577],[0.112701,0.276132,0.319391,0.266584],[0.109089,0.27505,0.318976,0.2674],[0.104985,0.273919,0.318155,0.26725],[0.101117,0.272924,0.316343,0.266153],[0.097057,0.272095,0.314739,0.264785],[0.092115,0.27133,0.31334,0.26315],[0.087679,0.27065,0.312143,0.262342],[0.083582,0.270107,0.311136,0.261389],[0.079803,0.269493,0.310534,0.260711],[0.077038,0.26894,0.310335,0.260577],[0.074232,0.268355,0.310737,0.260577],[0.07172,0.267726,0.311943,0.26153],[0.069914,0.26719,0.31295,0.262896],[0.068468,0.266817,0.313758,0.263994],[0.067759,0.266678,0.313961,0.264544],[0.067439,0.266679,0.313559,0.264543],[0.067293,0.266851,0.313157,0.263858],[0.06732,0.267021,0.312755,0.263175],[0.067333,0.267123,0.312555,0.262767],[0.067333,0.267225,0.312555,0.262358],[0.067333,0.267259,0.312555,0.262221],[0.067333,0.267327,0.312555,0.261948],[0.067333,0.267361,0.312555,0.261812],[0.067333,0.267326,0.312555,0.26195],[0.067333,0.267291,0.312555,0.262089],[0.067333,0.267189,0.312555,0.262499],[0.067333,0.267086,0.312555,0.262909],[0.067333,0.26695,0.312555,0.263454],[0.067333,0.266982,0.312555,0.263722],[0.067333,0.267082,0.312555,0.263718],[0.067333,0.267216,0.312555,0.263576],[0.067333,0.267451,0.312555,0.263028],[0.067333,0.267362,0.312555,0.263068],[0.067333,0.267224,0.312555,0.263329],[0.067333,0.267075,0.312555,0.263586],[0.22119,0.163172,0.445952,0.347344],[0.221138,0.162728,0.446399,0.349124],[0.221766,0.162259,0.447023,0.350992],[0.222735,0.161928,0.44828,0.352305],[0.224175,0.161649,0.450087,0.353411],[0.226293,0.161647,0.452101,0.353414],[0.228262,0.161821,0.453719,0.352726],[0.229726,0.162096,0.455131,0.351628],[0.230698,0.162507,0.456139,0.349986],[0.230991,0.162848,0.456943,0.348621],[0.230733,0.163153,0.458151,0.347396],[0.230503,0.16339,0.458958,0.346444],[0.229652,0.163424,0.458751,0.346306],[0.228009,0.163425,0.457524,0.346305],[0.225959,0.163426,0.454679,0.346304],[0.22329,0.163427,0.450643,0.346301],[0.221277,0.163598,0.44703,0.345617],[0.220069,0.163803,0.444238,0.344798],[0.219609,0.163838,0.443248,0.344658],[0.219903,0.16377,0.444048,0.345332],[0.22029,0.163338,0.446053,0.347885],[0.220804,0.162591,0.448671,0.352084],[0.221168,0.161793,0.450893,0.356454],[0.221386,0.16088,0.452715,0.360857],[0.2213,0.160205,0.453928,0.363906],[0.221071,0.15979,0.454734,0.365158],[0.220842,0.15955,0.455539,0.365714],[0.220599,0.159424,0.456545,0.365439],[0.220683,0.159343,0.457337,0.36472],[0.220762,0.159289,0.458048,0.364295],[0.220857,0.159214,0.458841,0.363776],[0.067333,0.266552,0.312555,0.265084],[0.067333,0.266957,0.312555,0.263467],[0.067333,0.26728,0.312555,0.26217],[0.067333,0.267443,0.312555,0.261513],[0.067333,0.267506,0.312555,0.261248],[0.067333,0.267437,0.312555,0.261524],[0.067333,0.267468,0.312555,0.261393],[0.067333,0.2675,0.312555,0.261261],[0.067333,0.267533,0.312555,0.261128],[0.067333,0.2676,0.312555,0.260857],[0.067333,0.267601,0.312555,0.260854],[0.067333,0.26774,0.312555,0.260303],[0.067333,0.268014,0.312555,0.259207],[0.067333,0.268185,0.312555,0.258523],[0.067333,0.268356,0.312555,0.25784],[0.067333,0.268425,0.312555,0.257566],[0.067333,0.268392,0.312555,0.257699],[0.067333,0.268493,0.312555,0.257292],[0.067333,0.268526,0.312555,0.257158],[0.067333,0.268524,0.312555,0.257162],[0.067333,0.268488,0.312555,0.257302],[0.067333,0.268351,0.312555,0.257849],[0.067333,0.268148,0.312555,0.258666],[0.067146,0.267845,0.312755,0.259887],[0.066772,0.267539,0.313157,0.261114],[0.06621,0.267266,0.31376,0.262207],[0.065648,0.267128,0.314364,0.262757],[0.06546,0.267194,0.314565,0.262488],[0.06546,0.267227,0.314565,0.262354],[0.065835,0.267225,0.314162,0.262357],[0.06621,0.26719,0.31376,0.262497],[0.066397,0.267087,0.313559,0.262908],[0.066772,0.267191,0.313157,0.262493],[0.066959,0.267435,0.312956,0.261528],[0.067146,0.267745,0.312755,0.260293],[0.067333,0.26812,0.312555,0.258791],[0.067333,0.268356,0.312555,0.25784],[0.067333,0.26849,0.312555,0.257299],[0.067333,0.268557,0.312555,0.257029],[0.067333,0.268626,0.312555,0.256754],[0.067333,0.268729,0.312555,0.256343],[0.067333,0.268798,0.312555,0.256068],[0.067333,0.268867,0.312555,0.255793],[0.067333,0.268799,0.312555,0.256065],[0.067333,0.268662,0.312555,0.256613],[0.067333,0.268593,0.312555,0.256889],[0.067333,0.268523,0.312555,0.257164],[0.067333,0.268557,0.312555,0.257029],[0.067333,0.268625,0.312555,0.256755],[0.067333,0.268659,0.312555,0.256619],[0.067333,0.268727,0.312555,0.256346],[0.067333,0.268727,0.312555,0.256346],[0.067333,0.268693,0.312555,0.256482],[0.067333,0.268625,0.312555,0.256755],[0.067333,0.268557,0.312555,0.257028],[0.067333,0.268593,0.312555,0.256889],[0.067333,0.268662,0.312555,0.256613],[0.067146,0.268667,0.312755,0.256604],[0.066772,0.268436,0.313157,0.257543],[0.066397,0.26803,0.313559,0.259175],[0.066023,0.267585,0.313961,0.260955],[0.065935,0.267276,0.314055,0.262179],[0.066181,0.267239,0.313791,0.262315],[0.066435,0.267304,0.313518,0.262049],[0.222173,0.156815,0.463989,0.360902],[0.222296,0.157021,0.463741,0.360898],[0.221404,0.157607,0.463119,0.360026],[0.219394,0.158473,0.461732,0.358718],[0.215942,0.15906,0.459088,0.358716],[0.210291,0.159573,0.455459,0.359399],[0.203892,0.159853,0.452458,0.360625],[0.196333,0.160099,0.451084,0.361989],[0.187979,0.160815,0.451299,0.361856],[0.180045,0.161539,0.453105,0.361308],[0.171359,0.162229,0.455721,0.361294],[0.163713,0.162411,0.458338,0.362924],[0.157294,0.162571,0.46076,0.364262],[0.151756,0.16305,0.462982,0.364349],[0.14817,0.163916,0.464598,0.36211],[0.145669,0.165451,0.465607,0.356764],[0.144425,0.166683,0.466011,0.352174],[0.144078,0.167595,0.466011,0.348434],[0.144092,0.168147,0.46581,0.346169],[0.144092,0.168283,0.46581,0.345622],[0.143717,0.168386,0.466213,0.345213],[0.143341,0.168385,0.466616,0.345214],[0.143154,0.168385,0.466818,0.345214],[0.143341,0.168419,0.466616,0.345077],[0.143904,0.168488,0.466011,0.344803],[0.144467,0.168625,0.465407,0.344256],[0.144654,0.168727,0.465206,0.343846],[0.144467,0.168795,0.465407,0.343573],[0.143904,0.168829,0.466011,0.343437],[0.143529,0.168829,0.466414,0.343437],[0.143168,0.168863,0.466616,0.3433],[0.14282,0.168932,0.466616,0.343026],[0.142127,0.169007,0.466615,0.342339],[0.140724,0.169087,0.466815,0.341242],[0.139336,0.169102,0.466814,0.34001],[0.137774,0.169087,0.466813,0.338506],[0.13676,0.1691,0.46641,0.337279],[0.135706,0.169142,0.466609,0.336324],[0.134436,0.169249,0.467413,0.335506],[0.133499,0.169317,0.46842,0.335233],[0.132159,0.169283,0.470231,0.335369],[0.131367,0.169148,0.471642,0.335914],[0.131297,0.168875,0.472649,0.337005],[0.131777,0.168665,0.473252,0.338236],[0.133557,0.168586,0.472644,0.339331],[0.136071,0.168576,0.471435,0.340154],[0.138409,0.168702,0.47023,0.340428],[0.139837,0.168736,0.469631,0.340291],[0.140195,0.168662,0.469795,0.339936],[0.13978,0.168594,0.470439,0.339566],[0.13888,0.168461,0.471407,0.339281],null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,[0.779503,0.42461,0.220495,0.457184],[0.779387,0.424322,0.22061,0.45752],[0.779403,0.423991,0.220595,0.458205],[0.779503,0.423673,0.220495,0.458825],[0.779503,0.42337,0.220495,0.459645],[0.779503,0.423297,0.220495,0.46033],[0.77969,0.423292,0.220307,0.460739],[0.780065,0.423356,0.219933,0.460875],[0.780439,0.423653,0.219559,0.460466],[0.780813,0.423721,0.219186,0.460193],[0.781,0.423658,0.219,0.460057],[0.781,0.423428,0.219,0.460194],[0.780813,0.422803,0.219186,0.460741],[0.780439,0.422344,0.219559,0.461015],[0.780065,0.422051,0.219933,0.461015],[0.779603,0.421875,0.220395,0.460833],[0.779387,0.422043,0.22061,0.460384],[0.779503,0.42218,0.220495,0.46003],[0.197991,0.149644,0.492352,0.38082],[0.201401,0.148874,0.491001,0.382924],[0.20689,0.14816,0.488443,0.38493],[0.213307,0.147885,0.484672,0.38588],[0.222091,0.147473,0.480645,0.387926],[0.232026,0.147931,0.477442,0.387252],[0.241474,0.148558,0.476255,0.386303],[0.251497,0.148948,0.476868,0.385902],[0.259598,0.149577,0.47768,0.384146],[0.265615,0.149636,0.478493,0.384292],[0.270113,0.149398,0.478699,0.384847],[0.272183,0.149125,0.478899,0.385537],[0.273356,0.14865,0.479503,0.387045],[0.273662,0.148278,0.480107,0.388141],[0.273273,0.148106,0.480712,0.388826],[0.272925,0.148002,0.480714,0.389238],[0.272591,0.148002,0.480513,0.389238],[0.272244,0.148169,0.480513,0.388964],[0.271883,0.148467,0.480714,0.388553],[0.271321,0.148765,0.481317,0.388143],[0.270571,0.148961,0.482123,0.388142],[0.270008,0.148893,0.482728,0.388415],[0.269633,0.148595,0.483132,0.388824],[0.269445,0.148332,0.483334,0.389098],[0.269445,0.148204,0.483334,0.388824],[0.269445,0.148243,0.483334,0.388278],[0.269445,0.148414,0.483334,0.387595],[0.269459,0.148418,0.483132,0.387186],[0.269487,0.148223,0.482728,0.387185],[0.269718,0.148029,0.48192,0.387183],[0.270149,0.147766,0.48071,0.387456],[0.270739,0.147731,0.479703,0.387593],[0.271302,0.147927,0.479099,0.387593],[0.271462,0.148019,0.4793,0.388004],[0.271219,0.148111,0.480305,0.388415],[0.270817,0.14814,0.481111,0.388689],[0.270441,0.148105,0.481515,0.388827],[0.270268,0.148306,0.481515,0.388416],[0.270296,0.148707,0.481111,0.387594],[0.270108,0.149039,0.481313,0.387047],[0.269718,0.149303,0.481919,0.386773],[0.269155,0.149269,0.482525,0.386909],[0.268417,0.148903,0.483132,0.387593],[0.267709,0.148571,0.483334,0.388141],[0.267188,0.148272,0.483334,0.388552],[0.266841,0.148037,0.483334,0.3891],[0.266667,0.147901,0.483334,0.389645],[0.266306,0.148014,0.483535,0.389214],[0.265584,0.148375,0.483936,0.38781],[0.26398,0.148767,0.484539,0.386274],[0.261508,0.14906,0.485143,0.384742],[0.258731,0.148734,0.485142,0.385276],[0.25601,0.147913,0.484831,0.387643],[0.254012,0.147013,0.48407,0.38994],[0.252526,0.146193,0.483004,0.392161],[0.073111,0.266338,0.309334,0.259653],[0.073111,0.266174,0.309334,0.260309],[0.073111,0.265993,0.309334,0.261036],[0.073111,0.265765,0.309334,0.261947],[0.073111,0.265525,0.309334,0.262905],[0.073111,0.265353,0.309334,0.26359],[0.073111,0.265319,0.309334,0.263727],[0.073111,0.26532,0.309334,0.263725],[0.073111,0.26539,0.309334,0.263449],[0.073111,0.265459,0.309334,0.263174],[0.073111,0.265391,0.309334,0.263447],[0.073111,0.265529,0.309334,0.262896],[0.073111,0.265668,0.309334,0.262345],[0.073111,0.265875,0.309334,0.261521],[0.073111,0.26625,0.309334,0.26002],[0.073111,0.266384,0.309334,0.259479],[0.073111,0.266518,0.309334,0.258937],[0.073111,0.26655,0.309334,0.258806],[0.073111,0.266481,0.309334,0.25908],[0.073111,0.266515,0.309334,0.258943],[0.073111,0.266501,0.309334,0.258998],[0.073111,0.266552,0.309334,0.258796],[0.073111,0.26661,0.309334,0.258561],[0.234654,0.166408,0.440139,0.347544],[0.236231,0.167296,0.438436,0.344856],[0.239679,0.168313,0.434903,0.341865],[0.244917,0.169525,0.42961,0.338411],[0.251073,0.170511,0.423547,0.33599],[0.25756,0.171157,0.417344,0.334933],[0.261796,0.171675,0.413387,0.334404],[0.262509,0.171966,0.413176,0.334408],[0.260445,0.172131,0.415743,0.334137],[0.255957,0.172067,0.420726,0.334001],[0.250106,0.17174,0.427566,0.334138],[0.245538,0.171413,0.433056,0.334274],[0.24209,0.171117,0.437347,0.334681],[0.239573,0.170919,0.440819,0.335086],[0.238258,0.170618,0.442234,0.336304],[0.236969,0.170043,0.443249,0.338616],[0.236043,0.169395,0.44406,0.341211],[0.235522,0.168774,0.44406,0.343685],[0.235724,0.16839,0.443655,0.345204],[0.236302,0.16832,0.442847,0.345481],[0.23711,0.168422,0.441232,0.345072],[0.238103,0.168523,0.439419,0.344663],[0.238719,0.168591,0.438013,0.344392],[0.239108,0.168598,0.437408,0.343978],[0.239416,0.168541,0.438007,0.343426],[0.240376,0.168489,0.439212,0.342466],[0.242203,0.168371,0.44042,0.341373],[0.245328,0.168078,0.440418,0.341774],[0.24961,0.167618,0.438799,0.34365],[0.2536,0.166948,0.436375,0.347158],[0.257263,0.166178,0.433563,0.351805],[0.259826,0.165534,0.431562,0.355524],[0.261108,0.165278,0.430562,0.356915],[0.261828,0.165453,0.430163,0.355823],[0.261828,0.165816,0.430163,0.353213],[0.261668,0.166309,0.429962,0.349667],[0.261508,0.166618,0.429761,0.347234],[0.261161,0.16679,0.429761,0.345746],[0.261175,0.167064,0.42956,0.344251],[0.261175,0.167235,0.42956,0.343567],[0.260987,0.167372,0.429761,0.34302],[0.260987,0.167441,0.429761,0.342746],[0.2608,0.167141,0.429962,0.344361],[0.260425,0.166735,0.430365,0.346394],[0.260425,0.166223,0.430365,0.349244],[0.260425,0.16577,0.430365,0.351839],[0.260237,0.165736,0.430567,0.351976],[0.260237,0.165912,0.430567,0.351281],[0.26005,0.166541,0.430768,0.347993],[0.259912,0.16711,0.430916,0.344968],[0.260035,0.167584,0.430784,0.342706],[0.260312,0.168154,0.430486,0.33991],null,null,null,null,[0.071013,0.266423,0.311585,0.26556],[0.071036,0.266558,0.31156,0.265021],[0.070913,0.266716,0.311693,0.264391],[0.07105,0.266883,0.311545,0.263725],[0.071426,0.267088,0.311142,0.262905],[0.071988,0.267224,0.310538,0.262359],[0.072363,0.26719,0.310136,0.262496],[0.072363,0.267055,0.310136,0.26304],[0.071988,0.266851,0.310538,0.263858],[0.071426,0.266716,0.311142,0.264402],[0.071238,0.266822,0.311343,0.263984],[0.071238,0.266963,0.311343,0.263428],[0.071426,0.267071,0.311142,0.263008],[0.071426,0.266938,0.311142,0.263546],[0.07105,0.266703,0.311545,0.264496],[0.070675,0.266708,0.311949,0.264485],[0.070312,0.266861,0.312339,0.263883],[0.070111,0.267355,0.312555,0.261914],[0.070111,0.267879,0.312555,0.259806],[0.237056,0.1709,0.441445,0.331404],[0.237505,0.170614,0.441445,0.331488],[0.237875,0.170501,0.441659,0.331331],[0.237931,0.170475,0.441846,0.330994],[0.237918,0.170445,0.442047,0.330721],[0.237557,0.170479,0.442248,0.330585],[0.237223,0.170445,0.442047,0.330721],[0.237251,0.170343,0.441644,0.331131],[0.237106,0.170172,0.441241,0.331814],[0.237321,0.170035,0.440637,0.332361],[0.23771,0.169967,0.440032,0.332635],[0.237911,0.169967,0.439629,0.332634],[0.238423,0.170075,0.439079,0.332205],[0.238761,0.170212,0.438716,0.331655],[0.238923,0.17033,0.438543,0.331184],null,null,null,null,null,[0.230954,0.170997,0.433369,0.332913],[0.2307,0.171957,0.431761,0.330954],[0.230132,0.172656,0.430476,0.329407],[0.229232,0.173254,0.429555,0.328502],[0.228056,0.173256,0.428957,0.329298],[0.227029,0.172689,0.428754,0.331194],[0.226523,0.172117,0.428551,0.333101],[0.226364,0.171719,0.428347,0.333917],[0.226753,0.172025,0.427743,0.332289],[0.22694,0.172495,0.427543,0.330392],[0.226766,0.172891,0.427544,0.328779],[0.226606,0.172951,0.427344,0.328122],[0.226276,0.172757,0.427264,0.328559],[0.226122,0.172526,0.426818,0.329131],[0.226157,0.172275,0.426298,0.329654],null,[0.226223,0.172822,0.425334,0.327467],[0.226223,0.172785,0.425334,0.327616],[0.226209,0.172662,0.425548,0.328114],[0.226182,0.172426,0.425936,0.329065],[0.226328,0.172017,0.426338,0.330704],[0.226648,0.171639,0.42674,0.332212],[0.227328,0.171264,0.426941,0.333313],[0.228356,0.171098,0.427141,0.333587],[0.229357,0.17121,0.427743,0.332757],[0.230517,0.171458,0.428548,0.331382],[0.231503,0.172,0.429354,0.329605],[0.232342,0.172333,0.429759,0.328655],[0.233223,0.172462,0.42956,0.328525],[0.233771,0.172489,0.429157,0.328802],[0.234146,0.172318,0.428756,0.329486],[0.234333,0.172317,0.428555,0.329488],[0.234333,0.172419,0.428555,0.329078],[0.234146,0.172556,0.428756,0.328532],[0.233771,0.172726,0.429157,0.32785],[0.233196,0.172795,0.429961,0.327576],[0.23242,0.172795,0.431167,0.327574],[0.231815,0.172694,0.432376,0.327982],[0.231398,0.172489,0.433384,0.328802],[0.231196,0.172317,0.433789,0.329487],[0.23121,0.172214,0.433587,0.3299],[0.231251,0.172213,0.432983,0.329901],[0.23148,0.172316,0.432178,0.32949],[0.231695,0.172254,0.431574,0.329351],[0.231896,0.172089,0.431172,0.329621],[0.232272,0.171891,0.430768,0.330028],[0.232459,0.171657,0.430567,0.330574],[0.232634,0.171823,0.430565,0.3303],[0.232808,0.172125,0.430563,0.329481],[0.232607,0.172461,0.430965,0.328526],[0.232205,0.17283,0.43177,0.327437],[0.231815,0.172965,0.432376,0.326893],[0.231412,0.173067,0.433183,0.326483],[0.231182,0.173135,0.433991,0.326211],[0.231156,0.173167,0.434354,0.326083],[0.231129,0.173203,0.434751,0.325938],[0.231111,0.173203,0.435,0.325938],null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,null,[0.223222,0.171566,0.428555,0.338743],[0.223222,0.171409,0.428555,0.339368],null,[0.232157,0.170974,0.435964,0.338614],[0.236583,0.170324,0.436236,0.339387],[0.24291,0.169459,0.435847,0.34051],[0.249207,0.168695,0.434572,0.341242],[0.255789,0.167933,0.432346,0.342337],[0.261191,0.1673,0.429527,0.343701],[0.264288,0.166863,0.427327,0.345064],[0.266288,0.166418,0.425932,0.346842],[0.267368,0.16604,0.425334,0.34835],[0.267715,0.165832,0.425334,0.349176],[0.267903,0.165797,0.425132,0.349314],[0.267917,0.1659,0.42493,0.348903],[0.267946,0.166071,0.424526,0.348219],[0.267988,0.166208,0.423921,0.347673],[0.268002,0.166276,0.423719,0.347401],[0.268203,0.166511,0.423317,0.346851],[0.268564,0.166914,0.423116,0.346027],[0.268711,0.167316,0.423516,0.345204],[0.268684,0.167683,0.423916,0.344518],[0.268095,0.167717,0.42492,0.344382],[0.267143,0.16735,0.426129,0.345066],[0.266392,0.167052,0.426936,0.345478],[0.265828,0.166821,0.427544,0.345617],[0.265639,0.166688,0.427747,0.345756],[0.265452,0.166789,0.427949,0.345347],[0.265278,0.166955,0.427949,0.345074],[0.264917,0.167054,0.42815,0.345073],[0.264535,0.167217,0.428337,0.34489],[0.264268,0.167415,0.428301,0.344775],[0.263759,0.167303,0.42887,0.345177],[0.071913,0.265684,0.310618,0.262273],[0.07242,0.265714,0.310074,0.262154],[0.072712,0.26556,0.309762,0.262776],[0.072924,0.265361,0.309534,0.263576],[0.073111,0.265156,0.309334,0.264395],[0.073111,0.265088,0.309334,0.264669],[0.073111,0.265257,0.309334,0.263987],[0.073111,0.265495,0.309334,0.263033],[0.073111,0.265766,0.309334,0.261945],[0.073111,0.265934,0.309334,0.261268],[0.073111,0.266002,0.309334,0.260994],[0.073111,0.266036,0.309334,0.260858],[0.073111,0.266002,0.309334,0.260994],[0.073111,0.265934,0.309334,0.261268],[0.073111,0.265865,0.309334,0.261541],[0.073111,0.265832,0.309334,0.261677],[0.073111,0.265832,0.309334,0.261675],[0.073111,0.265965,0.309334,0.261537],[0.073111,0.266264,0.309334,0.261125],[0.073111,0.266626,0.309334,0.260851],[0.073111,0.267224,0.309334,0.260025],[0.073111,0.267758,0.309334,0.258984],[0.073111,0.26817,0.309334,0.258108],[0.073111,0.268618,0.309334,0.256797],[0.234942,0.163511,0.444004,0.34601],[0.236342,0.163748,0.442914,0.345064],[0.238237,0.163691,0.441858,0.345284],[0.240221,0.163855,0.441433,0.344625],[0.242837,0.164225,0.441235,0.343131],[0.245121,0.164389,0.440834,0.342461],[0.247059,0.164522,0.440432,0.341923],[0.248663,0.164321,0.439829,0.342734],[0.249571,0.163785,0.439227,0.3445],[0.250106,0.163175,0.439026,0.34655],[0.25028,0.162665,0.439026,0.348196],[0.25028,0.162599,0.439026,0.348064],[0.250266,0.162973,0.439227,0.346965],[0.250238,0.163586,0.439629,0.344908],[0.250197,0.164329,0.440234,0.342318],[0.250155,0.164832,0.440839,0.340687],[0.250126,0.165101,0.441243,0.339603],[0.249925,0.1652,0.441646,0.339199],[0.24955,0.165065,0.442047,0.339742],[0.249175,0.164862,0.442449,0.340559],[0.248801,0.164589,0.442851,0.341651],[0.248627,0.164315,0.442851,0.342746],[0.248467,0.164177,0.44265,0.343297],[0.24776,0.164107,0.44285,0.343573],[0.246121,0.164006,0.444044,0.34398],[0.243706,0.163838,0.446442,0.344658],[0.240549,0.1636,0.449457,0.345612],[0.237212,0.163397,0.452486,0.34643],[0.234677,0.16353,0.453911,0.346291],[0.232402,0.163832,0.45412,0.345471],[0.230866,0.164168,0.453719,0.344516],[0.230072,0.164453,0.45282,0.343865],[0.22903,0.164378,0.452839,0.343936],[0.228481,0.164237,0.453038,0.344307],null,[0.229353,0.163664,0.448515,0.349752],[0.229212,0.163828,0.449215,0.34888],[0.22946,0.16391,0.448951,0.34907],[0.229604,0.163976,0.448846,0.349111],null,[0.231823,0.164941,0.448853,0.346494],[0.232275,0.165118,0.449125,0.345786],[0.232527,0.165342,0.44939,0.34489],[0.232731,0.16557,0.449296,0.343978],[0.232918,0.165746,0.449095,0.342884],[0.232918,0.165824,0.449095,0.34179],[0.232731,0.165834,0.449296,0.34097],[0.232342,0.165478,0.4499,0.341233],[0.231779,0.165015,0.450505,0.342315],[0.231244,0.164712,0.450707,0.343536],[0.231084,0.164512,0.450505,0.344346],[0.231126,0.164679,0.4499,0.344071],[0.231342,0.164982,0.449296,0.343249],[0.231355,0.16485,0.449095,0.343387],[0.230994,0.164309,0.449296,0.344762],[0.230605,0.163664,0.4499,0.346549],[0.230216,0.16305,0.450505,0.348208],[0.230202,0.162908,0.450707,0.348765],[0.23039,0.163178,0.450505,0.348078],[0.230794,0.163682,0.449697,0.346846],[0.231399,0.164282,0.448487,0.345617],[0.231736,0.164685,0.447453,0.344599],[0.23225,0.165097,0.446397,0.343941],[0.232601,0.165337,0.44563,0.343655],null,null,null,[0.233222,0.164517,0.444666,0.342559],[0.233008,0.16472,0.444666,0.342087],[0.232837,0.165107,0.44488,0.341244],[0.23266,0.165614,0.445269,0.340286],[0.232459,0.16598,0.445671,0.339603],[0.23262,0.166409,0.445871,0.339056],[0.232823,0.16644,0.445466,0.339328],[0.233052,0.166269,0.444659,0.340012],[0.233281,0.166166,0.443855,0.340423],[0.233295,0.166069,0.443654,0.340421],[0.233253,0.166338,0.444258,0.339737],[0.232997,0.166641,0.445464,0.338917],[0.232726,0.166811,0.446875,0.338235],[0.232481,0.166711,0.447884,0.338238],[0.232092,0.166315,0.44849,0.338649],[0.232091,0.165852,0.448491,0.339332],[0.232119,0.165617,0.448088,0.339879],[0.232335,0.165585,0.447483,0.340013],[0.233085,0.165752,0.446678,0.339736],[0.233661,0.165923,0.445872,0.339052],[0.234036,0.165864,0.44547,0.338506],[0.233876,0.165571,0.445269,0.338907],[0.232994,0.165106,0.44547,0.339992],[0.231911,0.16467,0.446073,0.341352],[0.230855,0.164124,0.446275,0.343538],[0.230177,0.163846,0.446069,0.344642],[0.2297,0.16357,0.445461,0.345741],[0.229235,0.163327,0.444653,0.346706],[0.228917,0.163395,0.444248,0.346433],[0.228382,0.163429,0.444451,0.346296],[0.228209,0.163738,0.44445,0.345064],[0.228237,0.164078,0.444046,0.343699],[0.228479,0.164589,0.443041,0.342052],[0.229082,0.165334,0.441836,0.33986],[0.229468,0.165976,0.441238,0.338078],[0.230001,0.166681,0.441041,0.336032],[0.23032,0.167018,0.441443,0.334674],[0.230466,0.166957,0.441846,0.334134],[0.230626,0.166827,0.442047,0.333866],[0.230612,0.166597,0.442248,0.334003],[0.230626,0.166431,0.442047,0.334277],[0.230626,0.166397,0.442047,0.334414],[0.230612,0.166494,0.442248,0.334414],[0.230585,0.166724,0.44265,0.334277],[0.230535,0.167032,0.443375,0.333957],[0.230497,0.167465,0.443921,0.333508],[0.230467,0.167806,0.444343,0.333155],null,null,null,[0.064333,0.26708,0.315778,0.262934],[0.064333,0.26698,0.315778,0.263336],[0.064333,0.266791,0.315778,0.264095],[0.064333,0.26651,0.315778,0.265223],[0.064333,0.266237,0.315778,0.266316],[0.064333,0.265996,0.315778,0.267276],[0.064333,0.265858,0.315778,0.267826],[0.064333,0.265757,0.315778,0.268232],[0.064333,0.265623,0.315778,0.268774],[0.064333,0.265385,0.315778,0.269729],[0.064333,0.265216,0.315778,0.27041],[0.064333,0.265252,0.315778,0.270269],[0.064333,0.265564,0.315778,0.269029],[0.064333,0.266149,0.315778,0.266697],[0.064333,0.266656,0.315778,0.264657],[0.064333,0.267059,0.315778,0.263031],[0.064333,0.267295,0.315778,0.262081],[0.064333,0.26733,0.315778,0.261943],[0.064333,0.267398,0.315778,0.261671],[0.064333,0.267466,0.315778,0.261397],[0.064333,0.267465,0.315778,0.261399],[0.064333,0.267532,0.315778,0.261129],[0.064333,0.2676,0.315778,0.260857],[0.064333,0.267633,0.315778,0.260722],[0.064333,0.267771,0.315778,0.260173],[0.064333,0.267943,0.315778,0.259487],[0.064333,0.268081,0.315778,0.258938],[0.064333,0.268287,0.315778,0.258116],[0.064333,0.268423,0.315778,0.257569],[0.064333,0.268393,0.315778,0.257297],[0.064333,0.268368,0.315778,0.256614],[0.064333,0.268208,0.315778,0.256477],[0.064333,0.268081,0.315778,0.256202],[0.064333,0.268185,0.315778,0.25579],[0.064333,0.268382,0.315778,0.255786],[0.064333,0.268679,0.315778,0.255377],[0.064333,0.268874,0.315778,0.255378],[0.064333,0.268903,0.315778,0.255654],[0.064333,0.268799,0.315778,0.256067],[0.064333,0.268695,0.315778,0.256479],[0.064333,0.268694,0.315778,0.256481],[0.064333,0.268762,0.315778,0.256208],[0.064333,0.268797,0.315778,0.25607],[0.064333,0.268731,0.315778,0.256339],[0.064333,0.268562,0.315778,0.257017],[0.064333,0.268222,0.315778,0.258382],[0.064333,0.267981,0.315778,0.259343],[0.064333,0.267948,0.315778,0.259476],[0.064333,0.268125,0.315778,0.258781],[0.064333,0.26851,0.315778,0.256858],[0.064333,0.269029,0.315778,0.254393],[0.064333,0.269369,0.315778,0.252554],[0.064333,0.269575,0.315778,0.251043],[0.064333,0.269895,0.315778,0.249804],[0.24197,0.162064,0.443005,0.348014],[0.246993,0.162021,0.440844,0.347125],[0.252708,0.161883,0.436991,0.347069],[0.260441,0.161791,0.431201,0.347387],[0.268626,0.161648,0.425595,0.348345],[0.27552,0.161666,0.420834,0.349442],[0.281082,0.161849,0.417871,0.350267],[0.284086,0.161902,0.417071,0.351225],[0.285461,0.161796,0.417273,0.352042],[0.285219,0.161425,0.418278,0.353135],[0.283399,0.160961,0.419486,0.35382],[0.280884,0.160604,0.420697,0.353684],[0.278585,0.160518,0.421303,0.352861],[0.276675,0.160699,0.421303,0.351356],[0.275835,0.160942,0.4209,0.349993],[0.276064,0.161346,0.420094,0.348765],[0.276814,0.161745,0.419289,0.347947],[0.278085,0.16214,0.418483,0.347538],[0.279341,0.162633,0.417879,0.347128],[0.280237,0.16296,0.417476,0.346991],[0.280237,0.163224,0.417476,0.346717],[0.279341,0.163458,0.417879,0.34617],[0.277737,0.163463,0.418483,0.34576],[0.275786,0.163405,0.419088,0.345213],[0.274369,0.163248,0.419491,0.344666],[0.2733,0.162926,0.419893,0.344393],[0.272765,0.162736,0.420094,0.343983],[0.272391,0.162575,0.420497,0.343846],[0.272015,0.162477,0.4209,0.343846],[0.272015,0.162477,0.4209,0.343846],[0.272203,0.162409,0.420698,0.344119],[0.272765,0.162341,0.420094,0.344392],[0.273327,0.162172,0.419491,0.345072],[0.273688,0.161899,0.41929,0.346164],[0.273848,0.161592,0.419491,0.347394],[0.273821,0.161317,0.419893,0.34849],[0.273793,0.161213,0.420296,0.348903],[0.273793,0.161282,0.420296,0.348629],[0.273821,0.161558,0.419893,0.347531],[0.273848,0.161935,0.419491,0.346024],[0.273688,0.162242,0.41929,0.344794],[0.273327,0.162514,0.419491,0.343703],[0.272765,0.162616,0.420094,0.343295],[0.27209,0.162581,0.420819,0.343433],[0.271582,0.16258,0.421365,0.343434],[0.27119,0.162525,0.421788,0.343654]]}];
}
</sheet>
diff --git a/examples/minimal-author-package/README.md b/examples/minimal-author-package/README.md
index adb1cc93..59dc2538 100644
--- a/examples/minimal-author-package/README.md
+++ b/examples/minimal-author-package/README.md
@@ -7,8 +7,9 @@ selecting a released Hypit development dependency, compiling it and sharing its
The fixture's Surface decoder also demonstrates the public value boundary: Style-like values consume
a decoded recipe shaped as `{ path, properties }`, exact `FontStackRef` records and inline values
-only after checking `record.value.kind === "inline"`. Media slots remain graph inputs rather than
-package files.
+only after checking `record.value.kind === "inline"`. Image slots remain graph inputs rather than
+package files. Its visual Surfaces also receive an explicit `within` Frame; the example never relies
+on a renderer root implicitly meaning the whole Canvas.
The package builds against one public Hypit framework dependency, `hypit`, and emits JavaScript.
`pnpm --dir packages/example-component pack` produces a tarball with no Runtime dependencies of its
diff --git a/examples/minimal-author-package/packages/example-component/README.md b/examples/minimal-author-package/packages/example-component/README.md
index 8628d3b0..3cad46ad 100644
--- a/examples/minimal-author-package/packages/example-component/README.md
+++ b/examples/minimal-author-package/packages/example-component/README.md
@@ -11,11 +11,16 @@ literal `fragment-input`, `fragment-operation` and `output` references. `src/tem
Surface-side `@hypit/hypit/temporal-markup` Window/Moment projections; that package is distinct from the
graph-side `@hypit/hypit/temporal` Producers.
-The Surfaces demonstrate a box, a text surface, a media slot and a Style decoder. The slot is a graph
+The Surfaces demonstrate a box, a text surface, an image slot and a Style decoder. The slot is a graph
input; it is not a file bundled by the package. `preview/Box.png` is a real catalogue frame supplied
by the package's vocabulary. `exampleAppendFragment` and `append-example-items` show a fixed-port
append that can be chained once per child.
+`ImageSlot` deliberately accepts only an image Blob. A raw video Blob does not carry the frame
+domain or target-to-source sampling relation required by a Visual video element; a component that
+needs timed footage should consume normalized media or a typed Surface and author that relation
+explicitly. The fixture stays small by not pretending those facts can be inferred from a MIME type.
+
While the component belongs to one project, keep this directory under that project's `packages/`
and use its owner-scoped package name. If the owner chooses to share it, compile and publish the same
package through npm or a private registry. Consumers install a chosen release with their ordinary
diff --git a/examples/minimal-author-package/packages/example-component/preview/preview.svml b/examples/minimal-author-package/packages/example-component/preview/preview.svml
index 34f1e212..2d03df4f 100644
--- a/examples/minimal-author-package/packages/example-component/preview/preview.svml
+++ b/examples/minimal-author-package/packages/example-component/preview/preview.svml
@@ -3,17 +3,18 @@
<!-- A complete catalogue Source. Its Run is ordinary: Studio can open it once the required media
Candidates are supplied, and a normal Build of the same Run can regenerate the catalogue frame. -->
<svml>
- <import as="media-track" from="@hypit/media-track@1"/>
- <import as="sound" from="@hypit/sound@1"/>
- <import as="performance" from="@hypit/performance@1"/>
+
+ <import as="media" from="@hypit/media@1"/>
+ <import as="visual" from="@hypit/visual-track@1"/>
+ <import as="audio" from="@hypit/audio-track@1"/>
<import from="@hypit/script@1"/>
<import as="wording" from="@hypit/text@1"/>
<import as="seedance" from="@hypit/seedance@1"/>
<import as="pipeline" from="@hypit/media-pipeline@1"/>
<import as="time" from="@hypit/timeline-author@1"/>
<import as="whisperx" from="@hypit/whisperx@1"/>
+ <import as="semantic" from="@hypit/narrative-temporal@1"/>
<import as="space" from="@hypit/spatial@1"/>
- <import as="program" from="@hypit/program-space@1"/>
<import as="film" from="@hypit/film@1"/>
<import as="render" from="@hypit/render-hyperframes@1"/>
<import as="example" from="@example/example-component@1"/>
@@ -24,31 +25,34 @@
</script>
<space:Canvas id="vertical" width="720" height="1280"/>
- <program:Clock id="clock" frame-rate="30"/>
- <space:Frame id="speech-frame" within={vertical} left="0%" top="0%" right="100%" bottom="100%"/>
+ <time:Clock id="clock" frame-rate="30"/>
+ <space:Frame id="speech-frame" within={vertical.bounds} left="0%" top="0%" right="100%" bottom="100%"/>
<wording:Value id="direction">A neutral catalogue card in a quiet studio.</wording:Value>
<seedance:TextVideo id="take" model="mini" prompt={direction} duration="4" generate-audio="true"/>
<pipeline:Normalize id="take-media" source={take.video} recipe={recipes.media.aroll} clock={clock}/>
- <whisperx:SemanticTake id="showcase-semantic" narrative={story} segment={story.segment.showcase} media={take-media.media} language="en"/>
- <time:Timeline id="speech" clock={clock}>
- <time:Take source={showcase-semantic.take}/>
+ <whisperx:Alignment id="showcase-semantic" narrative={story}
+ segment={story.segment.showcase} media={take-media.media} domain={take-media.domain} language="en"/>
+ <time:Timeline id="speech" clock={clock} end="showcase-semantic.end">
+ <time:Window id="showcase-semantic" from="start" for={take-media.extent}/>
</time:Timeline>
- <sound:Style id="speech-sound-style"/>
- <sound:Track id="speech-sound" timeline={speech.timeline}>
- <sound:Use style={speech-sound-style}/>
- </sound:Track>
- <performance:Style id="speech-picture-style" frame={speech-frame} appearance={recipes.media.performance}/>
- <performance:Track id="speech-picture" timeline={speech.timeline} canvas={vertical}>
- <performance:Use style={speech-picture-style} during="program"/>
- </performance:Track>
-
- <example:Box id="box" timeline={speech.timeline}/>
- <film:Film id="main" canvas={vertical} timeline={speech.timeline} appearance={recipes.film.vertical}>
+
+ <semantic:Projection id="story-time" narrative={story} timeline={speech.timeline}>
+ <semantic:Map alignment={showcase-semantic.alignment} domain={take-media.domain} window={speech.showcase-semantic}/>
+ </semantic:Projection>
+ <audio:Track id="speech-sound" timeline={speech.timeline}>
+ <audio:Clip id="showcase-semantic-source" source={take-media.media} during={speech.showcase-semantic}/>
+ </audio:Track>
+ <visual:Track id="speech-picture" timeline={speech.timeline}>
+ <visual:Clip id="showcase-semantic-source" media={take-media.media} during={speech.showcase-semantic} frame={speech-frame} z="0" fit="cover"/>
+ </visual:Track>
+
+ <example:Box id="box" timeline={speech.timeline} within={vertical.bounds}/>
+ <film:Film id="main" canvas={vertical.canvas} timeline={speech.timeline} appearance={recipes.film.vertical}>
<film:Track source={speech-picture.visual}/>
<film:Track source={speech-sound.audio}/>
- <film:Track source={box.track}/>
+ <film:Track source={box.visual}/>
</film:Film>
<render:Video id="final" composition={main.composition} timeline={speech.timeline}/>
</svml>
diff --git a/examples/minimal-author-package/packages/example-component/preview/recipes.svs b/examples/minimal-author-package/packages/example-component/preview/recipes.svs
index a2ebf8cc..06b60c66 100644
--- a/examples/minimal-author-package/packages/example-component/preview/recipes.svs
+++ b/examples/minimal-author-package/packages/example-component/preview/recipes.svs
@@ -2,7 +2,6 @@
<sheet version="1">
film.vertical { background: #09090B; }
- media.performance { stack-order: 0; fit: cover; }
speech.normal { language: en; pace: normal; rounding: round; }
media.aroll { video: primary-moving; audio: default; span-authority: video; }
</sheet>
diff --git a/examples/minimal-author-package/packages/example-component/src/component.ts b/examples/minimal-author-package/packages/example-component/src/component.ts
index a8261d87..c2a8d7f7 100644
--- a/examples/minimal-author-package/packages/example-component/src/component.ts
+++ b/examples/minimal-author-package/packages/example-component/src/component.ts
@@ -1,5 +1,6 @@
import { sealVisualTrack } from "@hypit/hypit/composition";
import type { Timeline } from "@hypit/hypit/timeline";
+import type { SpatialFrame } from "@hypit/hypit/spatial";
import { canonicalize } from "@hypit/hypit/author-kit";
import type { BlobRef, ComponentPackage, ProducerHandler, TypedRecord } from "@hypit/hypit/author-kit";
import { VISUAL_IR_V1 } from "@hypit/hypit/visual-ir";
@@ -10,35 +11,42 @@ const inline = <T>(record: { readonly value: { readonly kind: string; readonly v
return record.value.value as T;
};
const output = (value: unknown) => ({ kind: "inline" as const, value: canonicalize(value) });
-function blob(record: TypedRecord | undefined): BlobRef | undefined {
- return record?.value.kind === "blob" ? record.value : undefined;
+function image(record: TypedRecord | undefined): BlobRef | undefined {
+ if (record === undefined) return undefined;
+ if (record.value.kind !== "blob" || !record.value.mediaType.startsWith("image/")) {
+ throw new Error("example ImageSlot input must be an image Blob Artifact");
+ }
+ return record.value;
}
-function render(kind: string, timeline: Timeline, media?: BlobRef) {
- const frames = Math.max(1, Math.round(timeline.durationSec * timeline.frameRate.numerator / timeline.frameRate.denominator));
+function render(kind: string, timeline: Timeline, within: SpatialFrame, image?: BlobRef) {
+ const frames = timeline.frameCount;
return sealVisualTrack({
- programSpaceId: timeline.id,
+ timelineId: timeline.id,
visualIr: VISUAL_IR_V1,
id: `example-${kind}`,
- presents: [{ id: `present-${kind}`, span: { startFrame: 0, endFrameExclusive: frames }, stacking: { order: 0, tieBreak: kind }, elements: [{
+ presents: [{ id: `present-${kind}`, order: 0, z: 0, span: { startFrame: 0, endFrameExclusive: frames }, elements: [{
id: `${kind}-root`, kind: "box", order: 0,
- style: [{ name: "background-color", value: "#6b7280" }],
- }, ...(kind === "media" && media !== undefined ? [{ id: `${kind}-content`, parent: `${kind}-root`, kind: media.mediaType.startsWith("video/") ? "video" as const : "image" as const, artifact: media, order: 1, style: [{ name: "position", value: "absolute" }, { name: "left", value: 0 }, { name: "top", value: 0 }, { name: "width", value: "100%" }, { name: "height", value: "100%" }, { name: "object-fit", value: "contain" }] }] : []),
+ style: [{ name: "position", value: "absolute" }, { name: "left", value: `${within.xPx}px` },
+ { name: "top", value: `${within.yPx}px` }, { name: "width", value: `${within.widthPx}px` },
+ { name: "height", value: `${within.heightPx}px` }, { name: "background-color", value: "#6b7280" }],
+ }, ...(kind === "image" && image !== undefined ? [{ id: `${kind}-content`, parent: `${kind}-root`, kind: "image" as const, artifact: image, order: 1, style: [{ name: "position", value: "absolute" }, { name: "left", value: 0 }, { name: "top", value: 0 }, { name: "width", value: "100%" }, { name: "height", value: "100%" }, { name: "object-fit", value: "contain" }] }] : []),
] }],
});
}
-const producer = (kind: string): { readonly handler: ProducerHandler } => ({ handler: ({ inputs }) => ({ outputs: { track: output(render(kind, inline<Timeline>(inputs.timeline), blob(inputs.media))) }, needs: {} }) });
+const producer = (kind: string): { readonly handler: ProducerHandler } => ({ handler: ({ inputs }) => ({ outputs: { visual: output(render(kind,
+ inline<Timeline>(inputs.timeline), inline<SpatialFrame>(inputs.within), image(inputs.image))) }, needs: {} }) });
const appendItems: { readonly handler: ProducerHandler } = { handler: ({ inputs }) => ({ outputs: { set: output({ items: [inline<{ items: readonly unknown[] }>(inputs.previous).items, inline<{ items: readonly unknown[] }>(inputs.item).items].flat() }) }, needs: {} }) };
export const exampleComponent = {
producers: [
{ producer: exampleProducers.renderBox, ...producer("box") },
{ producer: exampleProducers.renderText, ...producer("text") },
- { producer: exampleProducers.renderMedia, ...producer("media") },
+ { producer: exampleProducers.renderImage, ...producer("image") },
{ producer: exampleProducers.appendItems, ...appendItems },
],
validators: [
{ type: exampleTypes.box, handler: () => {} },
{ type: exampleTypes.text, handler: () => {} },
- { type: exampleTypes.mediaSlot, handler: () => {} },
+ { type: exampleTypes.imageSlot, handler: () => {} },
],
} satisfies ComponentPackage;
diff --git a/examples/minimal-author-package/packages/example-component/src/fragment.ts b/examples/minimal-author-package/packages/example-component/src/fragment.ts
index 4047ccfe..bc2120ba 100644
--- a/examples/minimal-author-package/packages/example-component/src/fragment.ts
+++ b/examples/minimal-author-package/packages/example-component/src/fragment.ts
@@ -2,27 +2,29 @@ import { compositionTypes } from "@hypit/hypit/composition";
import { artifactTypes } from "@hypit/hypit/artifact";
import { sealGraphFragment } from "@hypit/hypit/author-kit";
import { timelineTypes } from "@hypit/hypit/timeline";
+import { spatialTypes } from "@hypit/hypit/spatial";
import { exampleProducers } from "./manifest.js";
import { exampleTypes } from "./manifest.js";
const input = (name: string) => ({ kind: "fragment-input" as const, name });
const operation = (id: string) => ({ kind: "fragment-operation" as const, operation: id });
-export function createExampleFragment(producer: typeof exampleProducers[keyof typeof exampleProducers], id: string, media = false) {
- const inputs = [{ name: "timeline", type: timelineTypes.track }, ...(media ? [{ name: "media", type: artifactTypes.blob }] : [])];
- const renderInputs = { timeline: input("timeline"), ...(media ? { media: input("media") } : {}) };
+export function createExampleFragment(producer: typeof exampleProducers[keyof typeof exampleProducers], id: string, image = false) {
+ const inputs = [{ name: "timeline", type: timelineTypes.track }, { name: "within", type: spatialTypes.frame },
+ ...(image ? [{ name: "image", type: artifactTypes.blob }] : [])];
+ const renderInputs = { timeline: input("timeline"), within: input("within"), ...(image ? { image: input("image") } : {}) };
return sealGraphFragment({
inputs,
operations: [
- { id, producer, inputs: renderInputs, result: { kind: "output", name: "track" } },
+ { id, producer, inputs: renderInputs, result: { kind: "output", name: "visual" } },
],
- exports: [{ name: "track", type: compositionTypes.visualTrack, root: operation(id) }],
+ exports: [{ name: "visual", type: compositionTypes.visualTrack, root: operation(id) }],
});
}
export const exampleBoxFragment = createExampleFragment(exampleProducers.renderBox, "render-box");
export const exampleTextFragment = createExampleFragment(exampleProducers.renderText, "render-text");
-export const exampleMediaFragment = createExampleFragment(exampleProducers.renderMedia, "render-media-slot", true);
+export const exampleImageFragment = createExampleFragment(exampleProducers.renderImage, "render-image-slot", true);
export const exampleAppendFragment = sealGraphFragment({
inputs: [{ name: "previous", type: exampleTypes.itemSet }, { name: "item", type: exampleTypes.itemSet }],
operations: [{ id: "append-items", producer: exampleProducers.appendItems, inputs: { previous: input("previous"), item: input("item") }, result: { kind: "output", name: "set" } }],
diff --git a/examples/minimal-author-package/packages/example-component/src/index.ts b/examples/minimal-author-package/packages/example-component/src/index.ts
index e9504e75..d717ce2a 100644
--- a/examples/minimal-author-package/packages/example-component/src/index.ts
+++ b/examples/minimal-author-package/packages/example-component/src/index.ts
@@ -1,5 +1,5 @@
export { exampleComponent } from "./component.js";
-export { exampleAppendFragment, exampleBoxFragment, exampleMediaFragment, exampleTextFragment } from "./fragment.js";
+export { exampleAppendFragment, exampleBoxFragment, exampleImageFragment, exampleTextFragment } from "./fragment.js";
export { exampleManifest, exampleMarkupSurfaces, exampleModuleRef, exampleProducers, exampleTypes } from "./manifest.js";
export { decodeExampleSurface } from "./surface.js";
export { decodeExampleStyle } from "./style.js";
diff --git a/examples/minimal-author-package/packages/example-component/src/manifest.ts b/examples/minimal-author-package/packages/example-component/src/manifest.ts
index dc4520ff..8f1d4af1 100644
--- a/examples/minimal-author-package/packages/example-component/src/manifest.ts
+++ b/examples/minimal-author-package/packages/example-component/src/manifest.ts
@@ -6,6 +6,7 @@ import { temporalTypes } from "@hypit/hypit/temporal";
import { mediaTypes } from "@hypit/hypit/media";
import { svsRecipeType } from "@hypit/hypit/svs";
import { artifactTypes } from "@hypit/hypit/artifact";
+import { spatialTypes } from "@hypit/hypit/spatial";
const previewImage = (file: string) => ({
mediaType: "image/png",
@@ -17,14 +18,14 @@ export const exampleModuleRef = { name: "@example/example-component", version: "
export const exampleTypes = {
box: { module: exampleModuleRef, name: "ExampleBox" },
text: { module: exampleModuleRef, name: "ExampleText" },
- mediaSlot: { module: exampleModuleRef, name: "ExampleMediaSlot" },
+ imageSlot: { module: exampleModuleRef, name: "ExampleImageSlot" },
style: { module: exampleModuleRef, name: "ExampleStyle" },
itemSet: { module: exampleModuleRef, name: "ExampleItemSet" },
} satisfies Record<string, TypeRef>;
export const exampleProducers = {
renderBox: { module: exampleModuleRef, name: "render-example-box" },
renderText: { module: exampleModuleRef, name: "render-example-text" },
- renderMedia: { module: exampleModuleRef, name: "render-example-media-slot" },
+ renderImage: { module: exampleModuleRef, name: "render-example-image-slot" },
appendItems: { module: exampleModuleRef, name: "append-example-items" },
} satisfies Record<string, ProducerRef>;
@@ -34,6 +35,7 @@ export const exampleManifest: ModuleManifest = {
{ module: artifactTypes.blob.module },
{ module: compositionTypes.visualTrack.module },
{ module: mediaTypes.fontStack.module },
+ { module: spatialTypes.frame.module },
{ module: timelineTypes.track.module },
{ module: svsRecipeType.module },
{ module: temporalTypes.window.module },
@@ -44,10 +46,11 @@ export const exampleManifest: ModuleManifest = {
name: producer.name,
inputs: producer === exampleProducers.appendItems
? [{ name: "previous", type: exampleTypes.itemSet }, { name: "item", type: exampleTypes.itemSet }]
- : [{ name: "timeline", type: timelineTypes.track }, ...(producer === exampleProducers.renderMedia ? [{ name: "media", type: artifactTypes.blob }] : [])],
+ : [{ name: "timeline", type: timelineTypes.track }, { name: "within", type: spatialTypes.frame },
+ ...(producer === exampleProducers.renderImage ? [{ name: "image", type: artifactTypes.blob }] : [])],
outputs: producer === exampleProducers.appendItems
? [{ name: "set", type: exampleTypes.itemSet }]
- : [{ name: "track", type: compositionTypes.visualTrack }],
+ : [{ name: "visual", type: compositionTypes.visualTrack }],
needs: [],
})),
};
@@ -59,16 +62,17 @@ const vocabulary = (summary: string, example: string) => ({
attributes: [
{ name: "id", kind: "identifier" as const, required: true, summary: "Names this instance." },
{ name: "timeline", kind: "reference" as const, required: true, accepts: [timelineTypes.track], summary: "Selects the complete Timeline." },
+ { name: "within", kind: "reference" as const, required: true, accepts: [spatialTypes.frame], summary: "Places the complete surface in this picture-plane Frame." },
],
- ports: [{ name: "track", type: compositionTypes.visualTrack, summary: "The terminal VisualTrack." }],
+ ports: [{ name: "visual", type: compositionTypes.visualTrack, summary: "The terminal visual contribution." }],
example,
- notes: ["The same shape is used for box, text and media-slot surfaces; only the terminal Producer changes."],
+ notes: ["The same shape is used for box, text and image-slot surfaces; only the terminal Producer changes."],
});
export const exampleMarkupSurfaces = [
- { name: "box", tag: "Box", mode: "structured", outputs: [exampleTypes.box, compositionTypes.visualTrack], vocabulary: { ...vocabulary("A framed box surface.", "<example:Box id=\"box\" timeline={speech.timeline}/>") , preview: previewImage("Box.png") } },
- { name: "text", tag: "Text", mode: "structured", outputs: [exampleTypes.text, temporalTypes.instantSpec, temporalTypes.windowSpec, temporalTypes.instant, temporalTypes.window, compositionTypes.visualTrack], vocabulary: { ...vocabulary("A text-bearing surface.", "<example:Text id=\"title\" timeline={speech.timeline}>Hello</example:Text>"), preview: previewImage("Box.png") } },
- { name: "media-slot", tag: "MediaSlot", mode: "structured", outputs: [exampleTypes.mediaSlot, compositionTypes.visualTrack], vocabulary: { ...vocabulary("A media slot whose content is a graph input.", "<example:MediaSlot id=\"shot\" timeline={speech.timeline} media={shot-media}/>") , attributes: [...vocabulary("", "").attributes, { name: "media", kind: "reference" as const, required: false, accepts: [artifactTypes.blob], summary: "Optional image or video Blob Artifact." }], preview: previewImage("Box.png") } },
+ { name: "box", tag: "Box", mode: "structured", outputs: [exampleTypes.box, compositionTypes.visualTrack], vocabulary: { ...vocabulary("A framed box surface.", "<example:Box id=\"box\" timeline={speech.timeline} within={layout.card}/>") , preview: previewImage("Box.png") } },
+ { name: "text", tag: "Text", mode: "structured", outputs: [exampleTypes.text, temporalTypes.instantSpec, temporalTypes.windowSpec, temporalTypes.instant, temporalTypes.window, compositionTypes.visualTrack], vocabulary: { ...vocabulary("A text-bearing surface.", "<example:Text id=\"title\" timeline={speech.timeline} within={layout.title}>Hello</example:Text>"), preview: previewImage("Box.png") } },
+ { name: "image-slot", tag: "ImageSlot", mode: "structured", outputs: [exampleTypes.imageSlot, compositionTypes.visualTrack], vocabulary: { ...vocabulary("An image slot whose content is a graph input.", "<example:ImageSlot id=\"shot\" timeline={speech.timeline} within={layout.shot} image={shot-image}/>") , attributes: [...vocabulary("", "").attributes, { name: "image", kind: "reference" as const, required: false, accepts: [artifactTypes.blob], summary: "Optional image Blob Artifact." }], preview: previewImage("Box.png") } },
{ name: "style", tag: "Style", mode: "structured", outputs: [exampleTypes.style], vocabulary: {
summary: "Decodes one SVS Recipe and exact FontStackRef into a Style value.",
attributes: [
diff --git a/examples/minimal-author-package/packages/example-component/src/surface.ts b/examples/minimal-author-package/packages/example-component/src/surface.ts
index 150eec26..afb29018 100644
--- a/examples/minimal-author-package/packages/example-component/src/surface.ts
+++ b/examples/minimal-author-package/packages/example-component/src/surface.ts
@@ -1,9 +1,10 @@
import type { StructuredElement, StructuredSurfaceHandler, SurfaceComponentDraft, SurfaceRecordDraft, SurfaceResolvedReference } from "@hypit/hypit/author-kit";
-import { exampleBoxFragment, exampleMediaFragment, exampleTextFragment } from "./fragment.js";
+import { exampleBoxFragment, exampleImageFragment, exampleTextFragment } from "./fragment.js";
import { exampleMarkupSurfaces, exampleTypes } from "./manifest.js";
import { mediaTypes } from "@hypit/hypit/media";
import { svsRecipeType } from "@hypit/hypit/svs";
import { artifactTypes } from "@hypit/hypit/artifact";
+import { spatialTypes } from "@hypit/hypit/spatial";
function text(element: StructuredElement, name: string): string {
const value = element.attributes[name];
@@ -29,13 +30,18 @@ export const decodeExampleSurface: StructuredSurfaceHandler = ({ element, resolv
return { records: [{ id, type: exampleTypes.style, value: { kind: "inline", value: { recipe: recipe.record.value.value, fonts: font.record.value.value } }, range: element.range }], components: [], fragments: [], exports: [id] };
}
const timeline = reference(element, "timeline", resolveReference);
+ const within = reference(element, "within", resolveReference);
+ if (within.type.module.name !== spatialTypes.frame.module.name || within.type.name !== spatialTypes.frame.name) {
+ throw new Error(`${element.name}.within must be a SpatialFrame.`);
+ }
const surface = exampleMarkupSurfaces.find((item) => item.tag === element.name.split(":").at(-1));
if (surface === undefined) throw new Error(`Unknown example surface ${element.name}`);
- const fragment = surface.name === "box" ? exampleBoxFragment : surface.name === "text" ? exampleTextFragment : exampleMediaFragment;
- const type = surface.name === "box" ? exampleTypes.box : surface.name === "text" ? exampleTypes.text : exampleTypes.mediaSlot;
+ const fragment = surface.name === "box" ? exampleBoxFragment : surface.name === "text" ? exampleTextFragment : exampleImageFragment;
+ const type = surface.name === "box" ? exampleTypes.box : surface.name === "text" ? exampleTypes.text : exampleTypes.imageSlot;
const record: SurfaceRecordDraft = { id: `${id}.value`, type, value: { kind: "inline", value: { id } }, range: element.range };
- const media = element.attributes.media === undefined ? undefined : reference(element, "media", resolveReference);
- if (media !== undefined && (media.type.module.name !== artifactTypes.blob.module.name || media.type.name !== artifactTypes.blob.name)) throw new Error(`${element.name}.media must be a Blob Artifact.`);
- const component: SurfaceComponentDraft = { id, fragment: fragment.id, inputs: { timeline: timeline.ref, ...(media === undefined ? {} : { media: media.ref }) }, outputs: { track: `${id}.track` }, range: element.range };
- return { records: [record], components: [component], fragments: [fragment], exports: [`${id}.value`, `${id}.track`] };
+ const image = element.attributes.image === undefined ? undefined : reference(element, "image", resolveReference);
+ if (image !== undefined && (image.type.module.name !== artifactTypes.blob.module.name || image.type.name !== artifactTypes.blob.name)) throw new Error(`${element.name}.image must be a Blob Artifact.`);
+ const component: SurfaceComponentDraft = { id, fragment: fragment.id, inputs: { timeline: timeline.ref,
+ within: within.ref, ...(image === undefined ? {} : { image: image.ref }) }, outputs: { visual: `${id}.visual` }, range: element.range };
+ return { records: [record], components: [component], fragments: [fragment], exports: [`${id}.value`, `${id}.visual`] };
};
diff --git a/examples/minimal-author-package/packages/example-component/src/temporal.ts b/examples/minimal-author-package/packages/example-component/src/temporal.ts
index 2e6794db..01148138 100644
--- a/examples/minimal-author-package/packages/example-component/src/temporal.ts
+++ b/examples/minimal-author-package/packages/example-component/src/temporal.ts
@@ -1,6 +1,6 @@
-import { createTemporalInstantProjection, createTemporalWindowProjection, temporalInstantAttributeNames, temporalWindowAttributeNames } from "@hypit/hypit/temporal-markup";
+import { createTemporalInstantConstruction, createTemporalWindowConstruction, temporalInstantAttributeNames, temporalWindowAttributeNames } from "@hypit/hypit/temporal-markup";
/** The fixture intentionally exposes both projection helpers and their vocabularies. */
export { temporalInstantAttributeNames, temporalWindowAttributeNames };
-export const projectExampleWindow = createTemporalWindowProjection;
-export const projectExampleMoment = createTemporalInstantProjection;
+export const projectExampleWindow = createTemporalWindowConstruction;
+export const projectExampleMoment = createTemporalInstantConstruction;
diff --git a/examples/podcast/README.md b/examples/podcast/README.md
index 2108dd93..ecf95f75 100644
--- a/examples/podcast/README.md
+++ b/examples/podcast/README.md
@@ -43,11 +43,11 @@ The tub passes across a cut; the woman is empty-handed on the later return to he
One five-second silent B-roll request combines the three lifestyle pictures into a montage. The
second scene is strawberry bingsu, not a literal smoothie demonstration: the montage illustrates the
whole routine. It covers part of the incoming man's response, creating a J-cut and giving the final
-cooking scene time to read. Its Recipe uses `once-start`: native-speed playback, truncation when the
-Selection is shorter, and an end to coverage when the clip finishes. It does not freeze the last
-frame or retime to fill the window. Inspect the newly aligned endpoint and adjust the Selection if
-the actual montage needs more reading time. Exact word-to-scene reconstruction would use separate
-media Items and adjoining Selections instead.
+cooking scene time to read. Its Clip omits `Map`, so the bounded partial identity plays at native
+speed, truncates when the Selection is shorter, and ends coverage when the source finishes. It does
+not freeze the last frame or retime to fill the Window. Inspect the newly aligned endpoint and adjust
+the Selection if the actual montage needs more reading time. Exact word-to-scene reconstruction
+would use separate Clips and adjoining Selections instead.
`shared-soundtrack.m4a` is the only supplied media asset on the final route. Images, voices and Takes
are generated; normalization, alignment, Caption and Film composition are explicit downstream work.
diff --git a/examples/podcast/recipes.svs b/examples/podcast/recipes.svs
index 759d740c..382cf3c4 100644
--- a/examples/podcast/recipes.svs
+++ b/examples/podcast/recipes.svs
@@ -63,18 +63,6 @@
gesture: natural;
}
-
- media.performance { stack-order: 10;
- fit: cover;
- }
-
- media.lifestyle {
- stack-order: 40;
- fit: cover;
- playback: stretch;
- clip: frame;
- }
-
caption.original-girl {
stack-order: 70;
x: 0.5;
diff --git a/examples/podcast/reference.svml b/examples/podcast/reference.svml
index 96acbd15..ceee8b45 100644
--- a/examples/podcast/reference.svml
+++ b/examples/podcast/reference.svml
@@ -2,22 +2,22 @@
<svml>
<import from="@hypit/script@1"/>
- <import as="sound" from="@hypit/sound@1"/>
+ <import as="audio" from="@hypit/audio-track@1"/>
<import as="asset" from="@hypit/media@1"/>
<import as="fish" from="@hypit/fishaudio-speech@1"/>
<import as="text" from="@hypit/text@1"/>
<import as="gpt" from="@hypit/gpt-image@1"/>
<import as="seedance" from="@hypit/seedance@1"/>
- <import as="program" from="@hypit/program-space@1"/>
<import as="pipeline" from="@hypit/media-pipeline@1"/>
<import as="whisperx" from="@hypit/whisperx@1"/>
+ <import as="semantic" from="@hypit/narrative-temporal@1"/>
+ <import as="narrative-caption" from="@hypit/narrative-caption@1"/>
<import as="time" from="@hypit/timeline-author@1"/>
<import as="audio-track" from="@hypit/audio-track@1"/>
<import as="caption" from="@hypit/caption@1"/>
<import as="caption-fine" from="@hypit/caption-fine@1"/>
<import as="fonts" from="@hypit/fonts-open@1"/>
- <import as="media-track" from="@hypit/media-track@1"/>
- <import as="performance" from="@hypit/performance@1"/>
+ <import as="visual" from="@hypit/visual-track@1"/>
<import as="space" from="@hypit/spatial@1"/>
<import as="film" from="@hypit/film@1"/>
<import as="render" from="@hypit/render-hyperframes@1"/>
@@ -351,9 +351,9 @@
</seedance:ReferenceVideo>
<space:Canvas id="vertical" width="720" height="1280"/>
- <space:Frame id="full-frame" within={vertical}
+ <space:Frame id="full-frame" within={vertical.bounds}
left="0%" top="0%" right="100%" bottom="100%"/>
- <program:Clock id="clock" frame-rate="30"/>
+ <time:Clock id="clock" frame-rate="30"/>
<pipeline:Normalize id="soundtrack-media" source={soundtrack}
video="none" audio="default" span-authority="audio" clock={clock}/>
@@ -367,39 +367,48 @@
<pipeline:Normalize id="lifestyle-media" source={lifestyle-montage.video}
video="primary-moving" audio="none" span-authority="video" clock={clock}/>
- <whisperx:SemanticTake id="opening-semantic" narrative={story}
- segment={story.segment.opening-question} media={opening-media.media} language="en"/>
- <whisperx:SemanticTake id="daily-creatine-semantic" narrative={story}
- segment={story.segment.daily-creatine} media={daily-creatine-media.media} language="en"/>
- <whisperx:SemanticTake id="arms-are-asking-semantic" narrative={story}
- segment={story.segment.arms-are-asking} media={arms-are-asking-media.media} language="en"/>
+ <whisperx:Alignment id="opening-semantic" narrative={story}
+ segment={story.segment.opening-question} media={opening-media.media} domain={opening-media.domain} language="en"/>
+ <whisperx:Alignment id="daily-creatine-semantic" narrative={story}
+ segment={story.segment.daily-creatine} media={daily-creatine-media.media} domain={daily-creatine-media.domain} language="en"/>
+ <whisperx:Alignment id="arms-are-asking-semantic" narrative={story}
+ segment={story.segment.arms-are-asking} media={arms-are-asking-media.media} domain={arms-are-asking-media.domain} language="en"/>
- <time:Timeline id="speech" clock={clock}>
- <time:Take source={opening-semantic.take}/>
- <time:Take source={daily-creatine-semantic.take}/>
- <time:Take source={arms-are-asking-semantic.take}/>
+ <time:Timeline id="speech" clock={clock} end="arms-are-asking-semantic.end">
+ <time:Window id="opening-semantic" from="start" for={opening-media.extent}/>
+ <time:Window id="daily-creatine-semantic" from="opening-semantic.end" for={daily-creatine-media.extent}/>
+ <time:Window id="arms-are-asking-semantic" from="daily-creatine-semantic.end" for={arms-are-asking-media.extent}/>
</time:Timeline>
- <sound:Style id="speech-sound-style"/>
- <sound:Track id="speech-sound" timeline={speech.timeline}>
- <sound:Use style={speech-sound-style}/>
- </sound:Track>
- <performance:Style id="speech-picture-style" frame={full-frame} appearance={recipes.media.performance}/>
- <performance:Track id="speech-picture" timeline={speech.timeline} canvas={vertical}>
- <performance:Use style={speech-picture-style} during="program"/>
- </performance:Track>
+
+ <semantic:Projection id="story-time" narrative={story} timeline={speech.timeline}>
+ <semantic:Map alignment={opening-semantic.alignment} domain={opening-media.domain} window={speech.opening-semantic}/>
+ <semantic:Map alignment={daily-creatine-semantic.alignment} domain={daily-creatine-media.domain} window={speech.daily-creatine-semantic}/>
+ <semantic:Map alignment={arms-are-asking-semantic.alignment} domain={arms-are-asking-media.domain} window={speech.arms-are-asking-semantic}/>
+ <semantic:Window id="selection-lifestyle" selection={story.selection.lifestyle}/>
+ </semantic:Projection>
+ <audio:Track id="speech-sound" timeline={speech.timeline}>
+ <audio:Clip id="opening-semantic-source" source={opening-media.media} during={speech.opening-semantic}/>
+ <audio:Clip id="daily-creatine-semantic-source" source={daily-creatine-media.media} during={speech.daily-creatine-semantic}/>
+ <audio:Clip id="arms-are-asking-semantic-source" source={arms-are-asking-media.media} during={speech.arms-are-asking-semantic}/>
+ </audio:Track>
+ <visual:Track id="speech-picture" timeline={speech.timeline}>
+ <visual:Clip id="opening-semantic-source" media={opening-media.media} during={speech.opening-semantic} frame={full-frame} z="10" fit="cover"/>
+ <visual:Clip id="daily-creatine-semantic-source" media={daily-creatine-media.media} during={speech.daily-creatine-semantic} frame={full-frame} z="10" fit="cover"/>
+ <visual:Clip id="arms-are-asking-semantic-source" media={arms-are-asking-media.media} during={speech.arms-are-asking-semantic} frame={full-frame} z="10" fit="cover"/>
+ </visual:Track>
<audio-track:Track id="music-bed" timeline={speech.timeline}>
- <audio-track:Item source={soundtrack-media.media} during="program"
- playback="once-start" gain="0.12" fade-in="300ms" fade-out="600ms"/>
+ <audio-track:Clip source={soundtrack-media.media} during="timeline"
+ gain="0.12" fade-in="300ms" fade-out="600ms"/>
</audio-track:Track>
- <media-track:Track id="lifestyle" timeline={speech.timeline} canvas={vertical}>
- <media-track:Item id="lifestyle-cutaway" media={lifestyle-media.media}
- frame={full-frame} during={story.selection.lifestyle}
- appearance={recipes.media.lifestyle}/>
- </media-track:Track>
+ <visual:Track id="lifestyle" timeline={speech.timeline}>
+ <visual:Clip id="lifestyle-cutaway" media={lifestyle-media.media}
+ frame={full-frame} during={story-time.selection-lifestyle}
+ z="40" fit="cover"/>
+ </visual:Track>
<fonts:Stack id="caption-font" family="montserrat" weight="900" style="normal"/>
<caption-fine:Style id="caption-style" recipe={recipes.caption.original-girl}
@@ -407,18 +416,19 @@
<caption-fine:Style id="caption-guy-style" recipe={recipes.caption.original-guy}
font={caption-font}/>
- <caption-fine:Track id="captions" document={story.caption}
- timeline={speech.timeline}>
+ <narrative-caption:Timing id="caption-timing" document={story.caption} binding={story.caption-binding} projection={story-time.projection}/>
+ <caption-fine:Caption id="captions" document={story.caption} timing={caption-timing}
+ timeline={speech.timeline} within={vertical.bounds}>
<caption-fine:Use style={caption-style}/>
<caption-fine:Use role="GUY" style={caption-guy-style}/>
- </caption-fine:Track>
+ </caption-fine:Caption>
- <film:Film id="main" canvas={vertical} timeline={speech.timeline}
+ <film:Film id="main" canvas={vertical.canvas} timeline={speech.timeline}
appearance={recipes.film.vertical}>
<film:Track source={speech-picture.visual}/>
<film:Track source={speech-sound.audio}/>
<film:Track source={lifestyle.visual}/>
- <film:Track source={captions.track}/>
+ <film:Track source={captions.visual}/>
<film:Track source={music-bed.audio}/>
</film:Film>
diff --git a/examples/podcast/reference.svs b/examples/podcast/reference.svs
index 74774e9c..1e2628bd 100644
--- a/examples/podcast/reference.svs
+++ b/examples/podcast/reference.svs
@@ -27,17 +27,6 @@
gesture: natural;
}
- media.performance { stack-order: 10;
- fit: cover;
- }
-
- media.lifestyle {
- stack-order: 40;
- fit: cover;
- playback: once-start;
- clip: frame;
- }
-
caption.original-girl {
stack-order: 70;
x: 0.5;
diff --git a/examples/podcast/swap-app.svml b/examples/podcast/swap-app.svml
index 49edce07..e62d3a1b 100644
--- a/examples/podcast/swap-app.svml
+++ b/examples/podcast/swap-app.svml
@@ -2,21 +2,21 @@
<svml>
<import from="@hypit/script@1"/>
- <import as="sound" from="@hypit/sound@1"/>
+ <import as="audio" from="@hypit/audio-track@1"/>
<import as="asset" from="@hypit/media@1"/>
<import as="text" from="@hypit/text@1"/>
<import as="gpt" from="@hypit/gpt-image@1"/>
<import as="seedance" from="@hypit/seedance@1"/>
- <import as="program" from="@hypit/program-space@1"/>
<import as="pipeline" from="@hypit/media-pipeline@1"/>
<import as="whisperx" from="@hypit/whisperx@1"/>
+ <import as="semantic" from="@hypit/narrative-temporal@1"/>
+ <import as="narrative-caption" from="@hypit/narrative-caption@1"/>
<import as="time" from="@hypit/timeline-author@1"/>
<import as="audio-track" from="@hypit/audio-track@1"/>
<import as="caption" from="@hypit/caption@1"/>
<import as="caption-fine" from="@hypit/caption-fine@1"/>
<import as="fonts" from="@hypit/fonts-open@1"/>
- <import as="media-track" from="@hypit/media-track@1"/>
- <import as="performance" from="@hypit/performance@1"/>
+ <import as="visual" from="@hypit/visual-track@1"/>
<import as="space" from="@hypit/spatial@1"/>
<import as="film" from="@hypit/film@1"/>
<import as="render" from="@hypit/render-hyperframes@1"/>
@@ -167,9 +167,9 @@
</seedance:ReferenceVideo>
<space:Canvas id="vertical" width="720" height="1280"/>
- <space:Frame id="full-frame" within={vertical}
+ <space:Frame id="full-frame" within={vertical.bounds}
left="0%" top="0%" right="100%" bottom="100%"/>
- <program:Clock id="clock" frame-rate="30"/>
+ <time:Clock id="clock" frame-rate="30"/>
<pipeline:Normalize id="soundtrack-media" source={soundtrack}
video="none" audio="default" span-authority="audio" clock={clock}/>
@@ -182,38 +182,49 @@
<pipeline:Normalize id="lifestyle-media" source={lifestyle-montage.video}
video="primary-moving" audio="none" span-authority="video" clock={clock}/>
- <whisperx:SemanticTake id="opening-semantic" narrative={story}
- segment={story.segment.opening-question} media={opening-media.media} language="en"/>
- <whisperx:SemanticTake id="daily-cheatgpt-semantic" narrative={story}
- segment={story.segment.daily-cheatgpt} media={daily-cheatgpt-media.media} language="en"/>
- <whisperx:SemanticTake id="brain-is-asking-semantic" narrative={story}
- segment={story.segment.brain-is-asking} media={brain-is-asking-media.media} language="en"/>
-
- <time:Timeline id="speech" clock={clock}>
- <time:Take source={opening-semantic.take}/>
- <time:Take source={daily-cheatgpt-semantic.take}/>
- <time:Take source={brain-is-asking-semantic.take}/>
+ <whisperx:Alignment id="opening-semantic" narrative={story}
+ segment={story.segment.opening-question} media={opening-media.media} domain={opening-media.domain} language="en"/>
+ <whisperx:Alignment id="daily-cheatgpt-semantic" narrative={story}
+ segment={story.segment.daily-cheatgpt} media={daily-cheatgpt-media.media} domain={daily-cheatgpt-media.domain} language="en"/>
+ <whisperx:Alignment id="brain-is-asking-semantic" narrative={story}
+ segment={story.segment.brain-is-asking} media={brain-is-asking-media.media} domain={brain-is-asking-media.domain} language="en"/>
+
+ <time:Timeline id="speech" clock={clock} end="brain-is-asking-semantic.end">
+ <time:Window id="opening-semantic" from="start" for={opening-media.extent}/>
+ <time:Window id="daily-cheatgpt-semantic" from="opening-semantic.end" for={daily-cheatgpt-media.extent}/>
+ <time:Window id="brain-is-asking-semantic" from="daily-cheatgpt-semantic.end" for={brain-is-asking-media.extent}/>
</time:Timeline>
- <sound:Style id="speech-sound-style"/>
- <sound:Track id="speech-sound" timeline={speech.timeline}>
- <sound:Use style={speech-sound-style}/>
- </sound:Track>
- <performance:Style id="speech-picture-style" frame={full-frame} appearance={recipes.media.performance}/>
- <performance:Track id="speech-picture" timeline={speech.timeline} canvas={vertical}>
- <performance:Use style={speech-picture-style} during="program"/>
- </performance:Track>
+
+ <semantic:Projection id="story-time" narrative={story} timeline={speech.timeline}>
+ <semantic:Map alignment={opening-semantic.alignment} domain={opening-media.domain} window={speech.opening-semantic}/>
+ <semantic:Map alignment={daily-cheatgpt-semantic.alignment} domain={daily-cheatgpt-media.domain} window={speech.daily-cheatgpt-semantic}/>
+ <semantic:Map alignment={brain-is-asking-semantic.alignment} domain={brain-is-asking-media.domain} window={speech.brain-is-asking-semantic}/>
+ <semantic:Window id="selection-lifestyle" selection={story.selection.lifestyle}/>
+ </semantic:Projection>
+ <audio:Track id="speech-sound" timeline={speech.timeline}>
+ <audio:Clip id="opening-semantic-source" source={opening-media.media} during={speech.opening-semantic}/>
+ <audio:Clip id="daily-cheatgpt-semantic-source" source={daily-cheatgpt-media.media} during={speech.daily-cheatgpt-semantic}/>
+ <audio:Clip id="brain-is-asking-semantic-source" source={brain-is-asking-media.media} during={speech.brain-is-asking-semantic}/>
+ </audio:Track>
+ <visual:Track id="speech-picture" timeline={speech.timeline}>
+ <visual:Clip id="opening-semantic-source" media={opening-media.media} during={speech.opening-semantic} frame={full-frame} z="10" fit="cover"/>
+ <visual:Clip id="daily-cheatgpt-semantic-source" media={daily-cheatgpt-media.media} during={speech.daily-cheatgpt-semantic} frame={full-frame} z="10" fit="cover"/>
+ <visual:Clip id="brain-is-asking-semantic-source" media={brain-is-asking-media.media} during={speech.brain-is-asking-semantic} frame={full-frame} z="10" fit="cover"/>
+ </visual:Track>
<audio-track:Track id="music-bed" timeline={speech.timeline}>
- <audio-track:Item source={soundtrack-media.media} during="program"
- playback="once-start" gain="0.12" fade-in="300ms" fade-out="600ms"/>
+ <audio-track:Clip source={soundtrack-media.media} during="timeline"
+ gain="0.12" fade-in="300ms" fade-out="600ms"/>
</audio-track:Track>
- <media-track:Track id="lifestyle" timeline={speech.timeline} canvas={vertical}>
- <media-track:Item id="lifestyle-cutaway" media={lifestyle-media.media}
- frame={full-frame} during={story.selection.lifestyle}
- appearance={recipes.media.lifestyle}/>
- </media-track:Track>
+ <visual:Track id="lifestyle" timeline={speech.timeline}>
+ <visual:Clip id="lifestyle-cutaway" media={lifestyle-media.media}
+ frame={full-frame} during={story-time.selection-lifestyle}
+ z="40" fit="cover">
+ <visual:Map/>
+ </visual:Clip>
+ </visual:Track>
<fonts:Stack id="caption-font" family="montserrat" weight="900" style="normal"/>
<caption-fine:Style id="caption-jock-style" recipe={recipes.caption.jock}
@@ -221,18 +232,19 @@
<caption-fine:Style id="caption-nerd-style" recipe={recipes.caption.nerd}
font={caption-font}/>
- <caption-fine:Track id="captions" document={story.caption}
- timeline={speech.timeline}>
+ <narrative-caption:Timing id="caption-timing" document={story.caption} binding={story.caption-binding} projection={story-time.projection}/>
+ <caption-fine:Caption id="captions" document={story.caption} timing={caption-timing}
+ timeline={speech.timeline} within={vertical.bounds}>
<caption-fine:Use style={caption-jock-style}/>
<caption-fine:Use role="NERD" style={caption-nerd-style}/>
- </caption-fine:Track>
+ </caption-fine:Caption>
- <film:Film id="main" canvas={vertical} timeline={speech.timeline}
+ <film:Film id="main" canvas={vertical.canvas} timeline={speech.timeline}
appearance={recipes.film.vertical}>
<film:Track source={speech-picture.visual}/>
<film:Track source={speech-sound.audio}/>
<film:Track source={lifestyle.visual}/>
- <film:Track source={captions.track}/>
+ <film:Track source={captions.visual}/>
<film:Track source={music-bed.audio}/>
</film:Film>
diff --git a/examples/podcast/swap-host.svml b/examples/podcast/swap-host.svml
index b204a98d..949d38d8 100644
--- a/examples/podcast/swap-host.svml
+++ b/examples/podcast/swap-host.svml
@@ -2,21 +2,21 @@
<svml>
<import from="@hypit/script@1"/>
- <import as="sound" from="@hypit/sound@1"/>
+ <import as="audio" from="@hypit/audio-track@1"/>
<import as="asset" from="@hypit/media@1"/>
<import as="text" from="@hypit/text@1"/>
<import as="gpt" from="@hypit/gpt-image@1"/>
<import as="seedance" from="@hypit/seedance@1"/>
- <import as="program" from="@hypit/program-space@1"/>
<import as="pipeline" from="@hypit/media-pipeline@1"/>
<import as="whisperx" from="@hypit/whisperx@1"/>
+ <import as="semantic" from="@hypit/narrative-temporal@1"/>
+ <import as="narrative-caption" from="@hypit/narrative-caption@1"/>
<import as="time" from="@hypit/timeline-author@1"/>
<import as="audio-track" from="@hypit/audio-track@1"/>
<import as="caption" from="@hypit/caption@1"/>
<import as="caption-fine" from="@hypit/caption-fine@1"/>
<import as="fonts" from="@hypit/fonts-open@1"/>
- <import as="media-track" from="@hypit/media-track@1"/>
- <import as="performance" from="@hypit/performance@1"/>
+ <import as="visual" from="@hypit/visual-track@1"/>
<import as="space" from="@hypit/spatial@1"/>
<import as="film" from="@hypit/film@1"/>
<import as="render" from="@hypit/render-hyperframes@1"/>
@@ -174,9 +174,9 @@
</seedance:ReferenceVideo>
<space:Canvas id="vertical" width="720" height="1280"/>
- <space:Frame id="full-frame" within={vertical}
+ <space:Frame id="full-frame" within={vertical.bounds}
left="0%" top="0%" right="100%" bottom="100%"/>
- <program:Clock id="clock" frame-rate="30"/>
+ <time:Clock id="clock" frame-rate="30"/>
<pipeline:Normalize id="soundtrack-media" source={soundtrack}
video="none" audio="default" span-authority="audio" clock={clock}/>
@@ -190,38 +190,49 @@
<pipeline:Normalize id="lifestyle-media" source={lifestyle-montage.video}
video="primary-moving" audio="none" span-authority="video" clock={clock}/>
- <whisperx:SemanticTake id="opening-semantic" narrative={story}
- segment={story.segment.opening-question} media={opening-media.media} language="en"/>
- <whisperx:SemanticTake id="daily-creatine-semantic" narrative={story}
- segment={story.segment.daily-creatine} media={daily-creatine-media.media} language="en"/>
- <whisperx:SemanticTake id="arms-are-asking-semantic" narrative={story}
- segment={story.segment.arms-are-asking} media={arms-are-asking-media.media} language="en"/>
-
- <time:Timeline id="speech" clock={clock}>
- <time:Take source={opening-semantic.take}/>
- <time:Take source={daily-creatine-semantic.take}/>
- <time:Take source={arms-are-asking-semantic.take}/>
+ <whisperx:Alignment id="opening-semantic" narrative={story}
+ segment={story.segment.opening-question} media={opening-media.media} domain={opening-media.domain} language="en"/>
+ <whisperx:Alignment id="daily-creatine-semantic" narrative={story}
+ segment={story.segment.daily-creatine} media={daily-creatine-media.media} domain={daily-creatine-media.domain} language="en"/>
+ <whisperx:Alignment id="arms-are-asking-semantic" narrative={story}
+ segment={story.segment.arms-are-asking} media={arms-are-asking-media.media} domain={arms-are-asking-media.domain} language="en"/>
+
+ <time:Timeline id="speech" clock={clock} end="arms-are-asking-semantic.end">
+ <time:Window id="opening-semantic" from="start" for={opening-media.extent}/>
+ <time:Window id="daily-creatine-semantic" from="opening-semantic.end" for={daily-creatine-media.extent}/>
+ <time:Window id="arms-are-asking-semantic" from="daily-creatine-semantic.end" for={arms-are-asking-media.extent}/>
</time:Timeline>
- <sound:Style id="speech-sound-style"/>
- <sound:Track id="speech-sound" timeline={speech.timeline}>
- <sound:Use style={speech-sound-style}/>
- </sound:Track>
- <performance:Style id="speech-picture-style" frame={full-frame} appearance={recipes.media.performance}/>
- <performance:Track id="speech-picture" timeline={speech.timeline} canvas={vertical}>
- <performance:Use style={speech-picture-style} during="program"/>
- </performance:Track>
+
+ <semantic:Projection id="story-time" narrative={story} timeline={speech.timeline}>
+ <semantic:Map alignment={opening-semantic.alignment} domain={opening-media.domain} window={speech.opening-semantic}/>
+ <semantic:Map alignment={daily-creatine-semantic.alignment} domain={daily-creatine-media.domain} window={speech.daily-creatine-semantic}/>
+ <semantic:Map alignment={arms-are-asking-semantic.alignment} domain={arms-are-asking-media.domain} window={speech.arms-are-asking-semantic}/>
+ <semantic:Window id="selection-lifestyle" selection={story.selection.lifestyle}/>
+ </semantic:Projection>
+ <audio:Track id="speech-sound" timeline={speech.timeline}>
+ <audio:Clip id="opening-semantic-source" source={opening-media.media} during={speech.opening-semantic}/>
+ <audio:Clip id="daily-creatine-semantic-source" source={daily-creatine-media.media} during={speech.daily-creatine-semantic}/>
+ <audio:Clip id="arms-are-asking-semantic-source" source={arms-are-asking-media.media} during={speech.arms-are-asking-semantic}/>
+ </audio:Track>
+ <visual:Track id="speech-picture" timeline={speech.timeline}>
+ <visual:Clip id="opening-semantic-source" media={opening-media.media} during={speech.opening-semantic} frame={full-frame} z="10" fit="cover"/>
+ <visual:Clip id="daily-creatine-semantic-source" media={daily-creatine-media.media} during={speech.daily-creatine-semantic} frame={full-frame} z="10" fit="cover"/>
+ <visual:Clip id="arms-are-asking-semantic-source" media={arms-are-asking-media.media} during={speech.arms-are-asking-semantic} frame={full-frame} z="10" fit="cover"/>
+ </visual:Track>
<audio-track:Track id="music-bed" timeline={speech.timeline}>
- <audio-track:Item source={soundtrack-media.media} during="program"
- playback="once-start" gain="0.12" fade-in="300ms" fade-out="600ms"/>
+ <audio-track:Clip source={soundtrack-media.media} during="timeline"
+ gain="0.12" fade-in="300ms" fade-out="600ms"/>
</audio-track:Track>
- <media-track:Track id="lifestyle" timeline={speech.timeline} canvas={vertical}>
- <media-track:Item id="lifestyle-cutaway" media={lifestyle-media.media}
- frame={full-frame} during={story.selection.lifestyle}
- appearance={recipes.media.lifestyle}/>
- </media-track:Track>
+ <visual:Track id="lifestyle" timeline={speech.timeline}>
+ <visual:Clip id="lifestyle-cutaway" media={lifestyle-media.media}
+ frame={full-frame} during={story-time.selection-lifestyle}
+ z="40" fit="cover">
+ <visual:Map/>
+ </visual:Clip>
+ </visual:Track>
<fonts:Stack id="caption-font" family="montserrat" weight="900" style="normal"/>
<caption-fine:Style id="caption-style" recipe={recipes.caption.pepe}
@@ -229,18 +240,19 @@
<caption-fine:Style id="caption-doge-style" recipe={recipes.caption.doge}
font={caption-font}/>
- <caption-fine:Track id="captions" document={story.caption}
- timeline={speech.timeline}>
+ <narrative-caption:Timing id="caption-timing" document={story.caption} binding={story.caption-binding} projection={story-time.projection}/>
+ <caption-fine:Caption id="captions" document={story.caption} timing={caption-timing}
+ timeline={speech.timeline} within={vertical.bounds}>
<caption-fine:Use style={caption-style}/>
<caption-fine:Use role="DOGE" style={caption-doge-style}/>
- </caption-fine:Track>
+ </caption-fine:Caption>
- <film:Film id="main" canvas={vertical} timeline={speech.timeline}
+ <film:Film id="main" canvas={vertical.canvas} timeline={speech.timeline}
appearance={recipes.film.vertical}>
<film:Track source={speech-picture.visual}/>
<film:Track source={speech-sound.audio}/>
<film:Track source={lifestyle.visual}/>
- <film:Track source={captions.track}/>
+ <film:Track source={captions.visual}/>
<film:Track source={music-bed.audio}/>
</film:Film>
diff --git a/examples/podcast/swap-item.svml b/examples/podcast/swap-item.svml
index d5281d68..18b1dbe9 100644
--- a/examples/podcast/swap-item.svml
+++ b/examples/podcast/swap-item.svml
@@ -2,21 +2,21 @@
<svml>
<import from="@hypit/script@1"/>
- <import as="sound" from="@hypit/sound@1"/>
+ <import as="audio" from="@hypit/audio-track@1"/>
<import as="asset" from="@hypit/media@1"/>
<import as="text" from="@hypit/text@1"/>
<import as="gpt" from="@hypit/gpt-image@1"/>
<import as="seedance" from="@hypit/seedance@1"/>
- <import as="program" from="@hypit/program-space@1"/>
<import as="pipeline" from="@hypit/media-pipeline@1"/>
<import as="whisperx" from="@hypit/whisperx@1"/>
+ <import as="semantic" from="@hypit/narrative-temporal@1"/>
+ <import as="narrative-caption" from="@hypit/narrative-caption@1"/>
<import as="time" from="@hypit/timeline-author@1"/>
<import as="audio-track" from="@hypit/audio-track@1"/>
<import as="caption" from="@hypit/caption@1"/>
<import as="caption-fine" from="@hypit/caption-fine@1"/>
<import as="fonts" from="@hypit/fonts-open@1"/>
- <import as="media-track" from="@hypit/media-track@1"/>
- <import as="performance" from="@hypit/performance@1"/>
+ <import as="visual" from="@hypit/visual-track@1"/>
<import as="space" from="@hypit/spatial@1"/>
<import as="film" from="@hypit/film@1"/>
<import as="render" from="@hypit/render-hyperframes@1"/>
@@ -174,9 +174,9 @@
</seedance:ReferenceVideo>
<space:Canvas id="vertical" width="720" height="1280"/>
- <space:Frame id="full-frame" within={vertical}
+ <space:Frame id="full-frame" within={vertical.bounds}
left="0%" top="0%" right="100%" bottom="100%"/>
- <program:Clock id="clock" frame-rate="30"/>
+ <time:Clock id="clock" frame-rate="30"/>
<pipeline:Normalize id="soundtrack-media" source={soundtrack}
video="none" audio="default" span-authority="audio" clock={clock}/>
@@ -190,38 +190,49 @@
<pipeline:Normalize id="lifestyle-media" source={lifestyle-montage.video}
video="primary-moving" audio="none" span-authority="video" clock={clock}/>
- <whisperx:SemanticTake id="opening-semantic" narrative={story}
- segment={story.segment.opening-question} media={opening-media.media} language="en"/>
- <whisperx:SemanticTake id="daily-retinol-semantic" narrative={story}
- segment={story.segment.daily-retinol} media={daily-retinol-media.media} language="en"/>
- <whisperx:SemanticTake id="skin-is-asking-semantic" narrative={story}
- segment={story.segment.skin-is-asking} media={skin-is-asking-media.media} language="en"/>
-
- <time:Timeline id="speech" clock={clock}>
- <time:Take source={opening-semantic.take}/>
- <time:Take source={daily-retinol-semantic.take}/>
- <time:Take source={skin-is-asking-semantic.take}/>
+ <whisperx:Alignment id="opening-semantic" narrative={story}
+ segment={story.segment.opening-question} media={opening-media.media} domain={opening-media.domain} language="en"/>
+ <whisperx:Alignment id="daily-retinol-semantic" narrative={story}
+ segment={story.segment.daily-retinol} media={daily-retinol-media.media} domain={daily-retinol-media.domain} language="en"/>
+ <whisperx:Alignment id="skin-is-asking-semantic" narrative={story}
+ segment={story.segment.skin-is-asking} media={skin-is-asking-media.media} domain={skin-is-asking-media.domain} language="en"/>
+
+ <time:Timeline id="speech" clock={clock} end="skin-is-asking-semantic.end">
+ <time:Window id="opening-semantic" from="start" for={opening-media.extent}/>
+ <time:Window id="daily-retinol-semantic" from="opening-semantic.end" for={daily-retinol-media.extent}/>
+ <time:Window id="skin-is-asking-semantic" from="daily-retinol-semantic.end" for={skin-is-asking-media.extent}/>
</time:Timeline>
- <sound:Style id="speech-sound-style"/>
- <sound:Track id="speech-sound" timeline={speech.timeline}>
- <sound:Use style={speech-sound-style}/>
- </sound:Track>
- <performance:Style id="speech-picture-style" frame={full-frame} appearance={recipes.media.performance}/>
- <performance:Track id="speech-picture" timeline={speech.timeline} canvas={vertical}>
- <performance:Use style={speech-picture-style} during="program"/>
- </performance:Track>
+
+ <semantic:Projection id="story-time" narrative={story} timeline={speech.timeline}>
+ <semantic:Map alignment={opening-semantic.alignment} domain={opening-media.domain} window={speech.opening-semantic}/>
+ <semantic:Map alignment={daily-retinol-semantic.alignment} domain={daily-retinol-media.domain} window={speech.daily-retinol-semantic}/>
+ <semantic:Map alignment={skin-is-asking-semantic.alignment} domain={skin-is-asking-media.domain} window={speech.skin-is-asking-semantic}/>
+ <semantic:Window id="selection-lifestyle" selection={story.selection.lifestyle}/>
+ </semantic:Projection>
+ <audio:Track id="speech-sound" timeline={speech.timeline}>
+ <audio:Clip id="opening-semantic-source" source={opening-media.media} during={speech.opening-semantic}/>
+ <audio:Clip id="daily-retinol-semantic-source" source={daily-retinol-media.media} during={speech.daily-retinol-semantic}/>
+ <audio:Clip id="skin-is-asking-semantic-source" source={skin-is-asking-media.media} during={speech.skin-is-asking-semantic}/>
+ </audio:Track>
+ <visual:Track id="speech-picture" timeline={speech.timeline}>
+ <visual:Clip id="opening-semantic-source" media={opening-media.media} during={speech.opening-semantic} frame={full-frame} z="10" fit="cover"/>
+ <visual:Clip id="daily-retinol-semantic-source" media={daily-retinol-media.media} during={speech.daily-retinol-semantic} frame={full-frame} z="10" fit="cover"/>
+ <visual:Clip id="skin-is-asking-semantic-source" media={skin-is-asking-media.media} during={speech.skin-is-asking-semantic} frame={full-frame} z="10" fit="cover"/>
+ </visual:Track>
<audio-track:Track id="music-bed" timeline={speech.timeline}>
- <audio-track:Item source={soundtrack-media.media} during="program"
- playback="once-start" gain="0.12" fade-in="300ms" fade-out="600ms"/>
+ <audio-track:Clip source={soundtrack-media.media} during="timeline"
+ gain="0.12" fade-in="300ms" fade-out="600ms"/>
</audio-track:Track>
- <media-track:Track id="lifestyle" timeline={speech.timeline} canvas={vertical}>
- <media-track:Item id="lifestyle-cutaway" media={lifestyle-media.media}
- frame={full-frame} during={story.selection.lifestyle}
- appearance={recipes.media.lifestyle}/>
- </media-track:Track>
+ <visual:Track id="lifestyle" timeline={speech.timeline}>
+ <visual:Clip id="lifestyle-cutaway" media={lifestyle-media.media}
+ frame={full-frame} during={story-time.selection-lifestyle}
+ z="40" fit="cover">
+ <visual:Map/>
+ </visual:Clip>
+ </visual:Track>
<fonts:Stack id="caption-font" family="montserrat" weight="900" style="normal"/>
<caption-fine:Style id="caption-idol-style" recipe={recipes.caption.retinol-idol}
@@ -229,18 +240,19 @@
<caption-fine:Style id="caption-tboy-style" recipe={recipes.caption.retinol-tboy}
font={caption-font}/>
- <caption-fine:Track id="captions" document={story.caption}
- timeline={speech.timeline}>
+ <narrative-caption:Timing id="caption-timing" document={story.caption} binding={story.caption-binding} projection={story-time.projection}/>
+ <caption-fine:Caption id="captions" document={story.caption} timing={caption-timing}
+ timeline={speech.timeline} within={vertical.bounds}>
<caption-fine:Use style={caption-idol-style}/>
<caption-fine:Use role="TBOY" style={caption-tboy-style}/>
- </caption-fine:Track>
+ </caption-fine:Caption>
- <film:Film id="main" canvas={vertical} timeline={speech.timeline}
+ <film:Film id="main" canvas={vertical.canvas} timeline={speech.timeline}
appearance={recipes.film.vertical}>
<film:Track source={speech-picture.visual}/>
<film:Track source={speech-sound.audio}/>
<film:Track source={lifestyle.visual}/>
- <film:Track source={captions.track}/>
+ <film:Track source={captions.visual}/>
<film:Track source={music-bed.audio}/>
</film:Film>
diff --git a/examples/ranking-football/column-recipes.svs b/examples/ranking-football/column-recipes.svs
index fb45e3d0..69db8666 100644
--- a/examples/ranking-football/column-recipes.svs
+++ b/examples/ranking-football/column-recipes.svs
@@ -11,14 +11,6 @@
film.vertical { background: #090A0F; }
- media.performance { stack-order: 0;
- fit: cover;
- frame-x: 0.5;
- frame-y: 0.5;
- content-x: 0.5;
- content-y: 0.5;
- }
-
/* Ten perceptually separated hues, balanced for the dark video background. */
ranking.football-column {
rank-colors: [
@@ -66,22 +58,13 @@
item-stack: 30;
}
- media.pitch-pov { stack-order: 40; fit: cover; shadows: 0 16 32 -8 #000000D9; }
- media.ikea-sign { stack-order: 41; fit: cover; shadows: 0 16 32 -8 #000000D9; }
- media.retirement-room { stack-order: 42; fit: cover; shadows: 0 16 32 -8 #000000D9; }
- media.rent-jump { stack-order: 43; fit: cover; shadows: 0 16 32 -8 #000000D9; }
- media.nine-hundred { stack-order: 44; fit: cover; shadows: 0 16 32 -8 #000000D9; }
- media.laboratory-body { stack-order: 45; fit: cover; shadows: 0 16 32 -8 #000000D9; }
- media.museum-jawline { stack-order: 46; fit: cover; shadows: 0 16 32 -8 #000000D9; }
-
- motion.broll {
- enter: pop;
- enter-frames: 6;
- enter-easing: ease-out;
- exit: fade;
- exit-frames: 4;
- exit-easing: ease-in;
- }
+ media.pitch-pov { shadows: 0 16 32 -8 #000000D9; }
+ media.ikea-sign { shadows: 0 16 32 -8 #000000D9; }
+ media.retirement-room { shadows: 0 16 32 -8 #000000D9; }
+ media.rent-jump { shadows: 0 16 32 -8 #000000D9; }
+ media.nine-hundred { shadows: 0 16 32 -8 #000000D9; }
+ media.laboratory-body { shadows: 0 16 32 -8 #000000D9; }
+ media.museum-jawline { shadows: 0 16 32 -8 #000000D9; }
/* Caption and stage share one horizontal center line. The caption remains
above the lower stage and wins every occasional overlap through z-order. */
diff --git a/examples/ranking-football/recipes.svs b/examples/ranking-football/recipes.svs
index 84f798ff..408e910b 100644
--- a/examples/ranking-football/recipes.svs
+++ b/examples/ranking-football/recipes.svs
@@ -11,14 +11,6 @@
film.vertical { background: #090A0F; }
- media.performance { stack-order: 0;
- fit: cover;
- frame-x: 0.5;
- frame-y: 0.5;
- content-x: 0.5;
- content-y: 0.5;
- }
-
ranking.football {
rows: [
{ "id": "s", "label": "S", "color": "#EE5F52" },
@@ -51,49 +43,36 @@
/* B-roll cards sit above the Ranking board and below captions. The later
member of every overlapping joke pair receives the higher stack order. */
media.hair-gel {
- stack-order: 40; fit: cover;
+
shadows: 0 18 34 -8 #000000D9;
}
media.trophy {
- stack-order: 41; fit: cover;
+
shadows: 0 18 34 -8 #000000D9;
}
media.greek-god {
- stack-order: 42; fit: cover;
+
shadows: 0 18 34 -8 #000000D9;
}
media.greek-tragedy {
- stack-order: 43; fit: cover;
+
shadows: 0 18 34 -8 #000000D9;
}
media.penaldo-social {
- stack-order: 44; fit: cover;
+
shadows: 0 18 34 -8 #000000D9;
}
media.tired-dad {
- stack-order: 45; fit: cover;
+
shadows: 0 18 34 -8 #000000D9;
}
media.walks-around {
- stack-order: 46; fit: cover;
+
shadows: 0 18 34 -8 #000000D9;
}
media.hat-trick {
- stack-order: 47; fit: cover;
- shadows: 0 18 34 -8 #000000E6;
- }
- motion.broll-left {
- enter: pop; enter-frames: 6; enter-easing: ease-out;
- exit: fade; exit-frames: 4; exit-easing: ease-in;
- }
- motion.broll-right {
- enter: bounce; enter-frames: 7; enter-easing: ease-out;
- exit: scale; exit-frames: 4; exit-amount: 0.94; exit-easing: ease-in;
- }
- motion.broll-wide {
- enter: scale; enter-frames: 6; enter-amount: 0.9; enter-easing: ease-out;
- exit: fade; exit-frames: 4; exit-easing: ease-in;
+ shadows: 0 18 34 -8 #000000E6;
}
caption.primary {
diff --git a/examples/ranking-football/reference-banana-from-swap/recipes.svs b/examples/ranking-football/reference-banana-from-swap/recipes.svs
index 84f798ff..408e910b 100644
--- a/examples/ranking-football/reference-banana-from-swap/recipes.svs
+++ b/examples/ranking-football/reference-banana-from-swap/recipes.svs
@@ -11,14 +11,6 @@
film.vertical { background: #090A0F; }
- media.performance { stack-order: 0;
- fit: cover;
- frame-x: 0.5;
- frame-y: 0.5;
- content-x: 0.5;
- content-y: 0.5;
- }
-
ranking.football {
rows: [
{ "id": "s", "label": "S", "color": "#EE5F52" },
@@ -51,49 +43,36 @@
/* B-roll cards sit above the Ranking board and below captions. The later
member of every overlapping joke pair receives the higher stack order. */
media.hair-gel {
- stack-order: 40; fit: cover;
+
shadows: 0 18 34 -8 #000000D9;
}
media.trophy {
- stack-order: 41; fit: cover;
+
shadows: 0 18 34 -8 #000000D9;
}
media.greek-god {
- stack-order: 42; fit: cover;
+
shadows: 0 18 34 -8 #000000D9;
}
media.greek-tragedy {
- stack-order: 43; fit: cover;
+
shadows: 0 18 34 -8 #000000D9;
}
media.penaldo-social {
- stack-order: 44; fit: cover;
+
shadows: 0 18 34 -8 #000000D9;
}
media.tired-dad {
- stack-order: 45; fit: cover;
+
shadows: 0 18 34 -8 #000000D9;
}
media.walks-around {
- stack-order: 46; fit: cover;
+
shadows: 0 18 34 -8 #000000D9;
}
media.hat-trick {
- stack-order: 47; fit: cover;
- shadows: 0 18 34 -8 #000000E6;
- }
- motion.broll-left {
- enter: pop; enter-frames: 6; enter-easing: ease-out;
- exit: fade; exit-frames: 4; exit-easing: ease-in;
- }
- motion.broll-right {
- enter: bounce; enter-frames: 7; enter-easing: ease-out;
- exit: scale; exit-frames: 4; exit-amount: 0.94; exit-easing: ease-in;
- }
- motion.broll-wide {
- enter: scale; enter-frames: 6; enter-amount: 0.9; enter-easing: ease-out;
- exit: fade; exit-frames: 4; exit-easing: ease-in;
+ shadows: 0 18 34 -8 #000000E6;
}
caption.primary {
diff --git a/examples/ranking-football/reference-banana-from-swap/reference-banana-from-swap.svml b/examples/ranking-football/reference-banana-from-swap/reference-banana-from-swap.svml
index bb753a45..44a4a33b 100644
--- a/examples/ranking-football/reference-banana-from-swap/reference-banana-from-swap.svml
+++ b/examples/ranking-football/reference-banana-from-swap/reference-banana-from-swap.svml
@@ -2,22 +2,22 @@
<svml>
<import from="@hypit/script@1"/>
- <import as="sound" from="@hypit/sound@1"/>
+ <import as="audio" from="@hypit/audio-track@1"/>
<import as="text" from="@hypit/text@1"/>
<import as="asset" from="@hypit/media@1"/>
<import as="gpt" from="@hypit/gpt-image@1"/>
<import as="seedance" from="@hypit/seedance@1"/>
<import as="pipeline" from="@hypit/media-pipeline@1"/>
<import as="whisperx" from="@hypit/whisperx@1"/>
+ <import as="semantic" from="@hypit/narrative-temporal@1"/>
+ <import as="narrative-caption" from="@hypit/narrative-caption@1"/>
<import as="time" from="@hypit/timeline-author@1"/>
- <import as="media-track" from="@hypit/media-track@1"/>
- <import as="performance" from="@hypit/performance@1"/>
+ <import as="visual" from="@hypit/visual-track@1"/>
<import as="audio-track" from="@hypit/audio-track@1"/>
<import as="caption" from="@hypit/caption@1"/>
<import as="caption-fine" from="@hypit/caption-fine@1"/>
<import as="fonts" from="@hypit/fonts-open@1"/>
<import as="space" from="@hypit/spatial@1"/>
- <import as="program" from="@hypit/program-space@1"/>
<import as="ranking" from="@hypit/ranking@1"/>
<import as="film" from="@hypit/film@1"/>
<import as="render" from="@hypit/render-hyperframes@1"/>
@@ -144,16 +144,16 @@
</seedance:ReferenceVideo>
<space:Canvas id="vertical" width="720" height="1280"/>
- <program:Clock id="clock" frame-rate="30"/>
+ <time:Clock id="clock" frame-rate="30"/>
<pipeline:Normalize id="soundtrack-media" source={soundtrack}
video="none" audio="default" span-authority="audio" clock={clock}/>
<pipeline:Normalize id="ranking-appear-media" source={ranking-appear-sfx}
video="none" audio="default" span-authority="audio" clock={clock}/>
<pipeline:Normalize id="ranking-move-media" source={ranking-move-sfx}
video="none" audio="default" span-authority="audio" clock={clock}/>
- <space:Frame id="speech-frame" within={vertical}
+ <space:Frame id="speech-frame" within={vertical.bounds}
left="0%" top="0%" right="100%" bottom="100%"/>
- <space:Frame id="tier-frame" within={vertical}
+ <space:Frame id="tier-frame" within={vertical.bounds}
left="0%" top="55%" right="100%" bottom="100%"/>
<!-- B-roll lives inside the lower board region. Deliberately varied card
@@ -168,21 +168,21 @@
<space:Extent id="walks-around-extent" width="2688" height="2016"/>
<space:Extent id="hat-trick-extent" width="2048" height="2048"/>
- <space:AspectFrame id="hair-gel-frame" within={vertical}
+ <space:AspectFrame id="hair-gel-frame" within={vertical.bounds}
x="34%" y="78%" width="58%" aspect={hair-gel-extent} anchor="center"/>
- <space:AspectFrame id="trophy-frame" within={vertical}
+ <space:AspectFrame id="trophy-frame" within={vertical.bounds}
x="73%" y="82%" width="42%" aspect={trophy-extent} anchor="center"/>
- <space:AspectFrame id="greek-god-frame" within={vertical}
+ <space:AspectFrame id="greek-god-frame" within={vertical.bounds}
x="24%" y="78%" width="38%" aspect={greek-god-extent} anchor="center"/>
- <space:AspectFrame id="greek-tragedy-frame" within={vertical}
+ <space:AspectFrame id="greek-tragedy-frame" within={vertical.bounds}
x="63%" y="79%" width="66%" aspect={greek-tragedy-extent} anchor="center"/>
- <space:AspectFrame id="penaldo-social-frame" within={vertical}
+ <space:AspectFrame id="penaldo-social-frame" within={vertical.bounds}
x="50%" y="78%" width="94%" aspect={penaldo-social-extent} anchor="center"/>
- <space:AspectFrame id="tired-dad-frame" within={vertical}
+ <space:AspectFrame id="tired-dad-frame" within={vertical.bounds}
x="58%" y="79%" width="62%" aspect={tired-dad-extent} anchor="center"/>
- <space:AspectFrame id="walks-around-frame" within={vertical}
+ <space:AspectFrame id="walks-around-frame" within={vertical.bounds}
x="38%" y="79%" width="68%" aspect={walks-around-extent} anchor="center"/>
- <space:AspectFrame id="hat-trick-frame" within={vertical}
+ <space:AspectFrame id="hat-trick-frame" within={vertical.bounds}
x="72%" y="80%" width="46%" aspect={hat-trick-extent} anchor="center"/>
<!-- Real Build path: generated video -> one shared normalization waist ->
@@ -191,27 +191,61 @@
video="primary-moving" audio="default" span-authority="video" clock={clock}/>
<pipeline:Normalize id="messi-media" source={messi-take.video}
video="primary-moving" audio="default" span-authority="video" clock={clock}/>
- <whisperx:SemanticTake id="ronaldo-semantic" narrative={story}
- segment={story.segment.ronaldo} media={ronaldo-media.media} language="en"/>
- <whisperx:SemanticTake id="messi-semantic" narrative={story}
- segment={story.segment.messi} media={messi-media.media} language="en"/>
+ <whisperx:Alignment id="ronaldo-semantic" narrative={story}
+ segment={story.segment.ronaldo} media={ronaldo-media.media} domain={ronaldo-media.domain} language="en"/>
+ <whisperx:Alignment id="messi-semantic" narrative={story}
+ segment={story.segment.messi} media={messi-media.media} domain={messi-media.domain} language="en"/>
- <time:Timeline id="speech" clock={clock}>
- <time:Take source={ronaldo-semantic.take}/>
- <time:Take source={messi-semantic.take}/>
+ <time:Timeline id="speech" clock={clock} end="messi-semantic.end">
+ <time:Window id="ronaldo-semantic" from="start" for={ronaldo-media.extent}/>
+ <time:Window id="messi-semantic" from="ronaldo-semantic.end" for={messi-media.extent}/>
</time:Timeline>
- <sound:Style id="speech-sound-style"/>
- <sound:Track id="speech-sound" timeline={speech.timeline}>
- <sound:Use style={speech-sound-style}/>
- </sound:Track>
- <performance:Style id="speech-picture-style" frame={speech-frame} appearance={recipes.media.performance}/>
- <performance:Track id="speech-picture" timeline={speech.timeline} canvas={vertical}>
- <performance:Use style={speech-picture-style} during="program"/>
- </performance:Track>
+
+ <semantic:Projection id="story-time" narrative={story} timeline={speech.timeline}>
+ <semantic:Map alignment={ronaldo-semantic.alignment} domain={ronaldo-media.domain} window={speech.ronaldo-semantic}/>
+ <semantic:Map alignment={messi-semantic.alignment} domain={messi-media.domain} window={speech.messi-semantic}/>
+ <semantic:Window id="segment-ronaldo" segment={story.segment.ronaldo}/>
+ <semantic:Window id="segment-messi" segment={story.segment.messi}/>
+ <semantic:Window id="selection-hair-gel" selection={story.selection.hair-gel}/>
+ <semantic:Window id="selection-trophy" selection={story.selection.trophy}/>
+ <semantic:Window id="selection-greek-god" selection={story.selection.greek-god}/>
+ <semantic:Window id="selection-greek-tragedy" selection={story.selection.greek-tragedy}/>
+ <semantic:Window id="selection-penaldo-social" selection={story.selection.penaldo-social}/>
+ <semantic:Window id="selection-tired-dad" selection={story.selection.tired-dad}/>
+ <semantic:Window id="selection-walks-around" selection={story.selection.walks-around}/>
+ <semantic:Window id="selection-hat-trick" selection={story.selection.hat-trick}/>
+ </semantic:Projection>
+ <audio:Track id="speech-sound" timeline={speech.timeline}>
+ <audio:Clip id="ronaldo-semantic-source" source={ronaldo-media.media} during={speech.ronaldo-semantic}/>
+ <audio:Clip id="messi-semantic-source" source={messi-media.media} during={speech.messi-semantic}/>
+ </audio:Track>
+ <visual:Motion id="broll-left">
+ <visual:Pose at="start" scale="0.7" opacity="0" easing="ease-out"/>
+ <visual:Pose at="6f" scale="1" opacity="1"/>
+ <visual:Pose at="end-4f" scale="1" opacity="1" easing="ease-in"/>
+ <visual:Pose at="end" scale="1" opacity="0"/>
+ </visual:Motion>
+ <visual:Motion id="broll-right">
+ <visual:Pose at="start" y="80" scale="0.92" opacity="0" easing="ease-out"/>
+ <visual:Pose at="7f" y="0" scale="1" opacity="1"/>
+ <visual:Pose at="end-4f" y="0" scale="1" opacity="1" easing="ease-in"/>
+ <visual:Pose at="end" y="0" scale="0.94" opacity="1"/>
+ </visual:Motion>
+ <visual:Motion id="broll-wide">
+ <visual:Pose at="start" scale="0.9" opacity="1" easing="ease-out"/>
+ <visual:Pose at="6f" scale="1" opacity="1"/>
+ <visual:Pose at="end-4f" scale="1" opacity="1" easing="ease-in"/>
+ <visual:Pose at="end" scale="1" opacity="0"/>
+ </visual:Motion>
+
+ <visual:Track id="speech-picture" timeline={speech.timeline}>
+ <visual:Clip id="ronaldo-semantic-source" media={ronaldo-media.media} during={speech.ronaldo-semantic} frame={speech-frame} z="0" fit="cover"/>
+ <visual:Clip id="messi-semantic-source" media={messi-media.media} during={speech.messi-semantic} frame={speech-frame} z="0" fit="cover"/>
+ </visual:Track>
<audio-track:Track id="music-bed" timeline={speech.timeline}>
- <audio-track:Item source={soundtrack-media.media} during="program"
- playback="once-start" gain="0.12" fade-in="300ms" fade-out="600ms"/>
+ <audio-track:Clip source={soundtrack-media.media} during="timeline"
+ gain="0.12" fade-in="300ms" fade-out="600ms"/>
</audio-track:Track>
<fonts:Stack id="display-font" family="montserrat" weight="900" style="normal"/>
@@ -219,8 +253,8 @@
<ranking:TierBoardStyle id="tier-style" recipe={recipes.ranking.football}
font={tier-font}/>
<ranking:TierBoard id="football-tiers" timeline={speech.timeline}
- canvas={vertical} frame={tier-frame}
- during="program" style={tier-style}
+ within={vertical.bounds} frame={tier-frame}
+ during="timeline" style={tier-style}
appear-sound={ranking-appear-media.media}
move-sound={ranking-move-media.media}>
<ranking:TierItem id="yamal" tier="s" preset="true" icon={yamal-icon.image}/>
@@ -233,64 +267,65 @@
<ranking:TierItem id="neymar" tier="d" preset="true" icon={neymar-icon.image}/>
<ranking:TierItem id="benzema" tier="d" preset="true" icon={benzema-icon.image}/>
<ranking:TierItem id="ronaldo" tier="d" entry="drop"
- icon={ronaldo-icon.image} during={story.segment.ronaldo}/>
+ icon={ronaldo-icon.image} during={story-time.segment-ronaldo}/>
<ranking:TierItem id="messi" tier="s" entry="drop"
- icon={messi-icon.image} during={story.segment.messi}/>
+ icon={messi-icon.image} during={story-time.segment-messi}/>
</ranking:TierBoard>
<!-- Every Item consumes a projected Selection window. Later overlapping
- jokes use a higher stack order through their appearance Recipe. -->
- <media-track:Track id="broll" timeline={speech.timeline} canvas={vertical}>
- <media-track:Item id="hair-gel" image={broll-hair-gel.image}
- extent={hair-gel-extent} during={story.selection.hair-gel}
- frame={hair-gel-frame} appearance={recipes.media.hair-gel}
- motion={recipes.motion.broll-left}/>
- <media-track:Item id="trophy" image={broll-trophy.image}
- extent={trophy-extent} during={story.selection.trophy}
- frame={trophy-frame} appearance={recipes.media.trophy}
- motion={recipes.motion.broll-right}/>
- <media-track:Item id="greek-god" image={broll-greek-god.image}
- extent={greek-god-extent} during={story.selection.greek-god}
- frame={greek-god-frame} appearance={recipes.media.greek-god}
- motion={recipes.motion.broll-left}/>
- <media-track:Item id="greek-tragedy" image={broll-greek-tragedy.image}
- extent={greek-tragedy-extent} during={story.selection.greek-tragedy}
- frame={greek-tragedy-frame} appearance={recipes.media.greek-tragedy}
- motion={recipes.motion.broll-right}/>
- <media-track:Item id="penaldo-social" image={broll-penaldo-social.image}
- extent={penaldo-social-extent} during={story.selection.penaldo-social}
- frame={penaldo-social-frame} appearance={recipes.media.penaldo-social}
- motion={recipes.motion.broll-wide}/>
- <media-track:Item id="tired-dad" image={broll-tired-dad-trophy.image}
- extent={tired-dad-extent} during={story.selection.tired-dad}
- frame={tired-dad-frame} appearance={recipes.media.tired-dad}
- motion={recipes.motion.broll-right}/>
- <media-track:Item id="walks-around" image={broll-walks-around.image}
- extent={walks-around-extent} during={story.selection.walks-around}
- frame={walks-around-frame} appearance={recipes.media.walks-around}
- motion={recipes.motion.broll-left}/>
- <media-track:Item id="hat-trick" image={broll-hat-trick.image}
- extent={hat-trick-extent} during={story.selection.hat-trick}
- frame={hat-trick-frame} appearance={recipes.media.hat-trick}
- motion={recipes.motion.broll-right}/>
- </media-track:Track>
+ jokes use a higher explicit z on their own Clip occurrence. -->
+ <visual:Track id="broll" timeline={speech.timeline}>
+ <visual:Clip id="hair-gel" image={broll-hair-gel.image}
+ extent={hair-gel-extent} during={story-time.selection-hair-gel}
+ frame={hair-gel-frame} z="40" fit="cover" treatment={recipes.media.hair-gel}
+ motion={broll-left}/>
+ <visual:Clip id="trophy" image={broll-trophy.image}
+ extent={trophy-extent} during={story-time.selection-trophy}
+ frame={trophy-frame} z="41" fit="cover" treatment={recipes.media.trophy}
+ motion={broll-right}/>
+ <visual:Clip id="greek-god" image={broll-greek-god.image}
+ extent={greek-god-extent} during={story-time.selection-greek-god}
+ frame={greek-god-frame} z="42" fit="cover" treatment={recipes.media.greek-god}
+ motion={broll-left}/>
+ <visual:Clip id="greek-tragedy" image={broll-greek-tragedy.image}
+ extent={greek-tragedy-extent} during={story-time.selection-greek-tragedy}
+ frame={greek-tragedy-frame} z="43" fit="cover" treatment={recipes.media.greek-tragedy}
+ motion={broll-right}/>
+ <visual:Clip id="penaldo-social" image={broll-penaldo-social.image}
+ extent={penaldo-social-extent} during={story-time.selection-penaldo-social}
+ frame={penaldo-social-frame} z="44" fit="cover" treatment={recipes.media.penaldo-social}
+ motion={broll-wide}/>
+ <visual:Clip id="tired-dad" image={broll-tired-dad-trophy.image}
+ extent={tired-dad-extent} during={story-time.selection-tired-dad}
+ frame={tired-dad-frame} z="45" fit="cover" treatment={recipes.media.tired-dad}
+ motion={broll-right}/>
+ <visual:Clip id="walks-around" image={broll-walks-around.image}
+ extent={walks-around-extent} during={story-time.selection-walks-around}
+ frame={walks-around-frame} z="46" fit="cover" treatment={recipes.media.walks-around}
+ motion={broll-left}/>
+ <visual:Clip id="hat-trick" image={broll-hat-trick.image}
+ extent={hat-trick-extent} during={story-time.selection-hat-trick}
+ frame={hat-trick-frame} z="47" fit="cover" treatment={recipes.media.hat-trick}
+ motion={broll-right}/>
+ </visual:Track>
<caption-fine:Style id="caption-style" recipe={recipes.caption.primary}
font={display-font}/>
- <caption-fine:Track id="captions" document={story.caption}
- timeline={speech.timeline}>
+ <narrative-caption:Timing id="caption-timing" document={story.caption} binding={story.caption-binding} projection={story-time.projection}/>
+ <caption-fine:Caption id="captions" document={story.caption} timing={caption-timing}
+ timeline={speech.timeline} within={vertical.bounds}>
<caption-fine:Use style={caption-style}/>
- </caption-fine:Track>
+ </caption-fine:Caption>
- <film:Film id="main" canvas={vertical} timeline={speech.timeline}
+ <film:Film id="main" canvas={vertical.canvas} timeline={speech.timeline}
appearance={recipes.film.vertical}>
<film:Track source={speech-picture.visual}/>
<film:Track source={speech-sound.audio}/>
<film:Track source={football-tiers.visual}/>
<film:Track source={football-tiers.audio}/>
<film:Track source={broll.visual}/>
- <film:Track source={captions.track}/>
+ <film:Track source={captions.visual}/>
<film:Track source={music-bed.audio}/>
</film:Film>
<render:Video id="final" composition={main.composition}
diff --git a/examples/ranking-football/reference-banana/recipes.svs b/examples/ranking-football/reference-banana/recipes.svs
index 84f798ff..408e910b 100644
--- a/examples/ranking-football/reference-banana/recipes.svs
+++ b/examples/ranking-football/reference-banana/recipes.svs
@@ -11,14 +11,6 @@
film.vertical { background: #090A0F; }
- media.performance { stack-order: 0;
- fit: cover;
- frame-x: 0.5;
- frame-y: 0.5;
- content-x: 0.5;
- content-y: 0.5;
- }
-
ranking.football {
rows: [
{ "id": "s", "label": "S", "color": "#EE5F52" },
@@ -51,49 +43,36 @@
/* B-roll cards sit above the Ranking board and below captions. The later
member of every overlapping joke pair receives the higher stack order. */
media.hair-gel {
- stack-order: 40; fit: cover;
+
shadows: 0 18 34 -8 #000000D9;
}
media.trophy {
- stack-order: 41; fit: cover;
+
shadows: 0 18 34 -8 #000000D9;
}
media.greek-god {
- stack-order: 42; fit: cover;
+
shadows: 0 18 34 -8 #000000D9;
}
media.greek-tragedy {
- stack-order: 43; fit: cover;
+
shadows: 0 18 34 -8 #000000D9;
}
media.penaldo-social {
- stack-order: 44; fit: cover;
+
shadows: 0 18 34 -8 #000000D9;
}
media.tired-dad {
- stack-order: 45; fit: cover;
+
shadows: 0 18 34 -8 #000000D9;
}
media.walks-around {
- stack-order: 46; fit: cover;
+
shadows: 0 18 34 -8 #000000D9;
}
media.hat-trick {
- stack-order: 47; fit: cover;
- shadows: 0 18 34 -8 #000000E6;
- }
- motion.broll-left {
- enter: pop; enter-frames: 6; enter-easing: ease-out;
- exit: fade; exit-frames: 4; exit-easing: ease-in;
- }
- motion.broll-right {
- enter: bounce; enter-frames: 7; enter-easing: ease-out;
- exit: scale; exit-frames: 4; exit-amount: 0.94; exit-easing: ease-in;
- }
- motion.broll-wide {
- enter: scale; enter-frames: 6; enter-amount: 0.9; enter-easing: ease-out;
- exit: fade; exit-frames: 4; exit-easing: ease-in;
+ shadows: 0 18 34 -8 #000000E6;
}
caption.primary {
diff --git a/examples/ranking-football/reference-banana/reference-banana.svml b/examples/ranking-football/reference-banana/reference-banana.svml
index bb753a45..44a4a33b 100644
--- a/examples/ranking-football/reference-banana/reference-banana.svml
+++ b/examples/ranking-football/reference-banana/reference-banana.svml
@@ -2,22 +2,22 @@
<svml>
<import from="@hypit/script@1"/>
- <import as="sound" from="@hypit/sound@1"/>
+ <import as="audio" from="@hypit/audio-track@1"/>
<import as="text" from="@hypit/text@1"/>
<import as="asset" from="@hypit/media@1"/>
<import as="gpt" from="@hypit/gpt-image@1"/>
<import as="seedance" from="@hypit/seedance@1"/>
<import as="pipeline" from="@hypit/media-pipeline@1"/>
<import as="whisperx" from="@hypit/whisperx@1"/>
+ <import as="semantic" from="@hypit/narrative-temporal@1"/>
+ <import as="narrative-caption" from="@hypit/narrative-caption@1"/>
<import as="time" from="@hypit/timeline-author@1"/>
- <import as="media-track" from="@hypit/media-track@1"/>
- <import as="performance" from="@hypit/performance@1"/>
+ <import as="visual" from="@hypit/visual-track@1"/>
<import as="audio-track" from="@hypit/audio-track@1"/>
<import as="caption" from="@hypit/caption@1"/>
<import as="caption-fine" from="@hypit/caption-fine@1"/>
<import as="fonts" from="@hypit/fonts-open@1"/>
<import as="space" from="@hypit/spatial@1"/>
- <import as="program" from="@hypit/program-space@1"/>
<import as="ranking" from="@hypit/ranking@1"/>
<import as="film" from="@hypit/film@1"/>
<import as="render" from="@hypit/render-hyperframes@1"/>
@@ -144,16 +144,16 @@
</seedance:ReferenceVideo>
<space:Canvas id="vertical" width="720" height="1280"/>
- <program:Clock id="clock" frame-rate="30"/>
+ <time:Clock id="clock" frame-rate="30"/>
<pipeline:Normalize id="soundtrack-media" source={soundtrack}
video="none" audio="default" span-authority="audio" clock={clock}/>
<pipeline:Normalize id="ranking-appear-media" source={ranking-appear-sfx}
video="none" audio="default" span-authority="audio" clock={clock}/>
<pipeline:Normalize id="ranking-move-media" source={ranking-move-sfx}
video="none" audio="default" span-authority="audio" clock={clock}/>
- <space:Frame id="speech-frame" within={vertical}
+ <space:Frame id="speech-frame" within={vertical.bounds}
left="0%" top="0%" right="100%" bottom="100%"/>
- <space:Frame id="tier-frame" within={vertical}
+ <space:Frame id="tier-frame" within={vertical.bounds}
left="0%" top="55%" right="100%" bottom="100%"/>
<!-- B-roll lives inside the lower board region. Deliberately varied card
@@ -168,21 +168,21 @@
<space:Extent id="walks-around-extent" width="2688" height="2016"/>
<space:Extent id="hat-trick-extent" width="2048" height="2048"/>
- <space:AspectFrame id="hair-gel-frame" within={vertical}
+ <space:AspectFrame id="hair-gel-frame" within={vertical.bounds}
x="34%" y="78%" width="58%" aspect={hair-gel-extent} anchor="center"/>
- <space:AspectFrame id="trophy-frame" within={vertical}
+ <space:AspectFrame id="trophy-frame" within={vertical.bounds}
x="73%" y="82%" width="42%" aspect={trophy-extent} anchor="center"/>
- <space:AspectFrame id="greek-god-frame" within={vertical}
+ <space:AspectFrame id="greek-god-frame" within={vertical.bounds}
x="24%" y="78%" width="38%" aspect={greek-god-extent} anchor="center"/>
- <space:AspectFrame id="greek-tragedy-frame" within={vertical}
+ <space:AspectFrame id="greek-tragedy-frame" within={vertical.bounds}
x="63%" y="79%" width="66%" aspect={greek-tragedy-extent} anchor="center"/>
- <space:AspectFrame id="penaldo-social-frame" within={vertical}
+ <space:AspectFrame id="penaldo-social-frame" within={vertical.bounds}
x="50%" y="78%" width="94%" aspect={penaldo-social-extent} anchor="center"/>
- <space:AspectFrame id="tired-dad-frame" within={vertical}
+ <space:AspectFrame id="tired-dad-frame" within={vertical.bounds}
x="58%" y="79%" width="62%" aspect={tired-dad-extent} anchor="center"/>
- <space:AspectFrame id="walks-around-frame" within={vertical}
+ <space:AspectFrame id="walks-around-frame" within={vertical.bounds}
x="38%" y="79%" width="68%" aspect={walks-around-extent} anchor="center"/>
- <space:AspectFrame id="hat-trick-frame" within={vertical}
+ <space:AspectFrame id="hat-trick-frame" within={vertical.bounds}
x="72%" y="80%" width="46%" aspect={hat-trick-extent} anchor="center"/>
<!-- Real Build path: generated video -> one shared normalization waist ->
@@ -191,27 +191,61 @@
video="primary-moving" audio="default" span-authority="video" clock={clock}/>
<pipeline:Normalize id="messi-media" source={messi-take.video}
video="primary-moving" audio="default" span-authority="video" clock={clock}/>
- <whisperx:SemanticTake id="ronaldo-semantic" narrative={story}
- segment={story.segment.ronaldo} media={ronaldo-media.media} language="en"/>
- <whisperx:SemanticTake id="messi-semantic" narrative={story}
- segment={story.segment.messi} media={messi-media.media} language="en"/>
+ <whisperx:Alignment id="ronaldo-semantic" narrative={story}
+ segment={story.segment.ronaldo} media={ronaldo-media.media} domain={ronaldo-media.domain} language="en"/>
+ <whisperx:Alignment id="messi-semantic" narrative={story}
+ segment={story.segment.messi} media={messi-media.media} domain={messi-media.domain} language="en"/>
- <time:Timeline id="speech" clock={clock}>
- <time:Take source={ronaldo-semantic.take}/>
- <time:Take source={messi-semantic.take}/>
+ <time:Timeline id="speech" clock={clock} end="messi-semantic.end">
+ <time:Window id="ronaldo-semantic" from="start" for={ronaldo-media.extent}/>
+ <time:Window id="messi-semantic" from="ronaldo-semantic.end" for={messi-media.extent}/>
</time:Timeline>
- <sound:Style id="speech-sound-style"/>
- <sound:Track id="speech-sound" timeline={speech.timeline}>
- <sound:Use style={speech-sound-style}/>
- </sound:Track>
- <performance:Style id="speech-picture-style" frame={speech-frame} appearance={recipes.media.performance}/>
- <performance:Track id="speech-picture" timeline={speech.timeline} canvas={vertical}>
- <performance:Use style={speech-picture-style} during="program"/>
- </performance:Track>
+
+ <semantic:Projection id="story-time" narrative={story} timeline={speech.timeline}>
+ <semantic:Map alignment={ronaldo-semantic.alignment} domain={ronaldo-media.domain} window={speech.ronaldo-semantic}/>
+ <semantic:Map alignment={messi-semantic.alignment} domain={messi-media.domain} window={speech.messi-semantic}/>
+ <semantic:Window id="segment-ronaldo" segment={story.segment.ronaldo}/>
+ <semantic:Window id="segment-messi" segment={story.segment.messi}/>
+ <semantic:Window id="selection-hair-gel" selection={story.selection.hair-gel}/>
+ <semantic:Window id="selection-trophy" selection={story.selection.trophy}/>
+ <semantic:Window id="selection-greek-god" selection={story.selection.greek-god}/>
+ <semantic:Window id="selection-greek-tragedy" selection={story.selection.greek-tragedy}/>
+ <semantic:Window id="selection-penaldo-social" selection={story.selection.penaldo-social}/>
+ <semantic:Window id="selection-tired-dad" selection={story.selection.tired-dad}/>
+ <semantic:Window id="selection-walks-around" selection={story.selection.walks-around}/>
+ <semantic:Window id="selection-hat-trick" selection={story.selection.hat-trick}/>
+ </semantic:Projection>
+ <audio:Track id="speech-sound" timeline={speech.timeline}>
+ <audio:Clip id="ronaldo-semantic-source" source={ronaldo-media.media} during={speech.ronaldo-semantic}/>
+ <audio:Clip id="messi-semantic-source" source={messi-media.media} during={speech.messi-semantic}/>
+ </audio:Track>
+ <visual:Motion id="broll-left">
+ <visual:Pose at="start" scale="0.7" opacity="0" easing="ease-out"/>
+ <visual:Pose at="6f" scale="1" opacity="1"/>
+ <visual:Pose at="end-4f" scale="1" opacity="1" easing="ease-in"/>
+ <visual:Pose at="end" scale="1" opacity="0"/>
+ </visual:Motion>
+ <visual:Motion id="broll-right">
+ <visual:Pose at="start" y="80" scale="0.92" opacity="0" easing="ease-out"/>
+ <visual:Pose at="7f" y="0" scale="1" opacity="1"/>
+ <visual:Pose at="end-4f" y="0" scale="1" opacity="1" easing="ease-in"/>
+ <visual:Pose at="end" y="0" scale="0.94" opacity="1"/>
+ </visual:Motion>
+ <visual:Motion id="broll-wide">
+ <visual:Pose at="start" scale="0.9" opacity="1" easing="ease-out"/>
+ <visual:Pose at="6f" scale="1" opacity="1"/>
+ <visual:Pose at="end-4f" scale="1" opacity="1" easing="ease-in"/>
+ <visual:Pose at="end" scale="1" opacity="0"/>
+ </visual:Motion>
+
+ <visual:Track id="speech-picture" timeline={speech.timeline}>
+ <visual:Clip id="ronaldo-semantic-source" media={ronaldo-media.media} during={speech.ronaldo-semantic} frame={speech-frame} z="0" fit="cover"/>
+ <visual:Clip id="messi-semantic-source" media={messi-media.media} during={speech.messi-semantic} frame={speech-frame} z="0" fit="cover"/>
+ </visual:Track>
<audio-track:Track id="music-bed" timeline={speech.timeline}>
- <audio-track:Item source={soundtrack-media.media} during="program"
- playback="once-start" gain="0.12" fade-in="300ms" fade-out="600ms"/>
+ <audio-track:Clip source={soundtrack-media.media} during="timeline"
+ gain="0.12" fade-in="300ms" fade-out="600ms"/>
</audio-track:Track>
<fonts:Stack id="display-font" family="montserrat" weight="900" style="normal"/>
@@ -219,8 +253,8 @@
<ranking:TierBoardStyle id="tier-style" recipe={recipes.ranking.football}
font={tier-font}/>
<ranking:TierBoard id="football-tiers" timeline={speech.timeline}
- canvas={vertical} frame={tier-frame}
- during="program" style={tier-style}
+ within={vertical.bounds} frame={tier-frame}
+ during="timeline" style={tier-style}
appear-sound={ranking-appear-media.media}
move-sound={ranking-move-media.media}>
<ranking:TierItem id="yamal" tier="s" preset="true" icon={yamal-icon.image}/>
@@ -233,64 +267,65 @@
<ranking:TierItem id="neymar" tier="d" preset="true" icon={neymar-icon.image}/>
<ranking:TierItem id="benzema" tier="d" preset="true" icon={benzema-icon.image}/>
<ranking:TierItem id="ronaldo" tier="d" entry="drop"
- icon={ronaldo-icon.image} during={story.segment.ronaldo}/>
+ icon={ronaldo-icon.image} during={story-time.segment-ronaldo}/>
<ranking:TierItem id="messi" tier="s" entry="drop"
- icon={messi-icon.image} during={story.segment.messi}/>
+ icon={messi-icon.image} during={story-time.segment-messi}/>
</ranking:TierBoard>
<!-- Every Item consumes a projected Selection window. Later overlapping
- jokes use a higher stack order through their appearance Recipe. -->
- <media-track:Track id="broll" timeline={speech.timeline} canvas={vertical}>
- <media-track:Item id="hair-gel" image={broll-hair-gel.image}
- extent={hair-gel-extent} during={story.selection.hair-gel}
- frame={hair-gel-frame} appearance={recipes.media.hair-gel}
- motion={recipes.motion.broll-left}/>
- <media-track:Item id="trophy" image={broll-trophy.image}
- extent={trophy-extent} during={story.selection.trophy}
- frame={trophy-frame} appearance={recipes.media.trophy}
- motion={recipes.motion.broll-right}/>
- <media-track:Item id="greek-god" image={broll-greek-god.image}
- extent={greek-god-extent} during={story.selection.greek-god}
- frame={greek-god-frame} appearance={recipes.media.greek-god}
- motion={recipes.motion.broll-left}/>
- <media-track:Item id="greek-tragedy" image={broll-greek-tragedy.image}
- extent={greek-tragedy-extent} during={story.selection.greek-tragedy}
- frame={greek-tragedy-frame} appearance={recipes.media.greek-tragedy}
- motion={recipes.motion.broll-right}/>
- <media-track:Item id="penaldo-social" image={broll-penaldo-social.image}
- extent={penaldo-social-extent} during={story.selection.penaldo-social}
- frame={penaldo-social-frame} appearance={recipes.media.penaldo-social}
- motion={recipes.motion.broll-wide}/>
- <media-track:Item id="tired-dad" image={broll-tired-dad-trophy.image}
- extent={tired-dad-extent} during={story.selection.tired-dad}
- frame={tired-dad-frame} appearance={recipes.media.tired-dad}
- motion={recipes.motion.broll-right}/>
- <media-track:Item id="walks-around" image={broll-walks-around.image}
- extent={walks-around-extent} during={story.selection.walks-around}
- frame={walks-around-frame} appearance={recipes.media.walks-around}
- motion={recipes.motion.broll-left}/>
- <media-track:Item id="hat-trick" image={broll-hat-trick.image}
- extent={hat-trick-extent} during={story.selection.hat-trick}
- frame={hat-trick-frame} appearance={recipes.media.hat-trick}
- motion={recipes.motion.broll-right}/>
- </media-track:Track>
+ jokes use a higher explicit z on their own Clip occurrence. -->
+ <visual:Track id="broll" timeline={speech.timeline}>
+ <visual:Clip id="hair-gel" image={broll-hair-gel.image}
+ extent={hair-gel-extent} during={story-time.selection-hair-gel}
+ frame={hair-gel-frame} z="40" fit="cover" treatment={recipes.media.hair-gel}
+ motion={broll-left}/>
+ <visual:Clip id="trophy" image={broll-trophy.image}
+ extent={trophy-extent} during={story-time.selection-trophy}
+ frame={trophy-frame} z="41" fit="cover" treatment={recipes.media.trophy}
+ motion={broll-right}/>
+ <visual:Clip id="greek-god" image={broll-greek-god.image}
+ extent={greek-god-extent} during={story-time.selection-greek-god}
+ frame={greek-god-frame} z="42" fit="cover" treatment={recipes.media.greek-god}
+ motion={broll-left}/>
+ <visual:Clip id="greek-tragedy" image={broll-greek-tragedy.image}
+ extent={greek-tragedy-extent} during={story-time.selection-greek-tragedy}
+ frame={greek-tragedy-frame} z="43" fit="cover" treatment={recipes.media.greek-tragedy}
+ motion={broll-right}/>
+ <visual:Clip id="penaldo-social" image={broll-penaldo-social.image}
+ extent={penaldo-social-extent} during={story-time.selection-penaldo-social}
+ frame={penaldo-social-frame} z="44" fit="cover" treatment={recipes.media.penaldo-social}
+ motion={broll-wide}/>
+ <visual:Clip id="tired-dad" image={broll-tired-dad-trophy.image}
+ extent={tired-dad-extent} during={story-time.selection-tired-dad}
+ frame={tired-dad-frame} z="45" fit="cover" treatment={recipes.media.tired-dad}
+ motion={broll-right}/>
+ <visual:Clip id="walks-around" image={broll-walks-around.image}
+ extent={walks-around-extent} during={story-time.selection-walks-around}
+ frame={walks-around-frame} z="46" fit="cover" treatment={recipes.media.walks-around}
+ motion={broll-left}/>
+ <visual:Clip id="hat-trick" image={broll-hat-trick.image}
+ extent={hat-trick-extent} during={story-time.selection-hat-trick}
+ frame={hat-trick-frame} z="47" fit="cover" treatment={recipes.media.hat-trick}
+ motion={broll-right}/>
+ </visual:Track>
<caption-fine:Style id="caption-style" recipe={recipes.caption.primary}
font={display-font}/>
- <caption-fine:Track id="captions" document={story.caption}
- timeline={speech.timeline}>
+ <narrative-caption:Timing id="caption-timing" document={story.caption} binding={story.caption-binding} projection={story-time.projection}/>
+ <caption-fine:Caption id="captions" document={story.caption} timing={caption-timing}
+ timeline={speech.timeline} within={vertical.bounds}>
<caption-fine:Use style={caption-style}/>
- </caption-fine:Track>
+ </caption-fine:Caption>
- <film:Film id="main" canvas={vertical} timeline={speech.timeline}
+ <film:Film id="main" canvas={vertical.canvas} timeline={speech.timeline}
appearance={recipes.film.vertical}>
<film:Track source={speech-picture.visual}/>
<film:Track source={speech-sound.audio}/>
<film:Track source={football-tiers.visual}/>
<film:Track source={football-tiers.audio}/>
<film:Track source={broll.visual}/>
- <film:Track source={captions.track}/>
+ <film:Track source={captions.visual}/>
<film:Track source={music-bed.audio}/>
</film:Film>
<render:Video id="final" composition={main.composition}
diff --git a/examples/ranking-football/reference-gpt.svml b/examples/ranking-football/reference-gpt.svml
index 72e72617..ebf8bcfd 100644
--- a/examples/ranking-football/reference-gpt.svml
+++ b/examples/ranking-football/reference-gpt.svml
@@ -2,22 +2,22 @@
<svml>
<import from="@hypit/script@1"/>
- <import as="sound" from="@hypit/sound@1"/>
+ <import as="audio" from="@hypit/audio-track@1"/>
<import as="text" from="@hypit/text@1"/>
<import as="asset" from="@hypit/media@1"/>
<import as="gpt" from="@hypit/gpt-image@1"/>
<import as="seedance" from="@hypit/seedance@1"/>
<import as="pipeline" from="@hypit/media-pipeline@1"/>
<import as="whisperx" from="@hypit/whisperx@1"/>
+ <import as="semantic" from="@hypit/narrative-temporal@1"/>
+ <import as="narrative-caption" from="@hypit/narrative-caption@1"/>
<import as="time" from="@hypit/timeline-author@1"/>
- <import as="media-track" from="@hypit/media-track@1"/>
- <import as="performance" from="@hypit/performance@1"/>
+ <import as="visual" from="@hypit/visual-track@1"/>
<import as="audio-track" from="@hypit/audio-track@1"/>
<import as="caption" from="@hypit/caption@1"/>
<import as="caption-fine" from="@hypit/caption-fine@1"/>
<import as="fonts" from="@hypit/fonts-open@1"/>
<import as="space" from="@hypit/spatial@1"/>
- <import as="program" from="@hypit/program-space@1"/>
<import as="ranking" from="@hypit/ranking@1"/>
<import as="film" from="@hypit/film@1"/>
<import as="render" from="@hypit/render-hyperframes@1"/>
@@ -144,16 +144,16 @@
</seedance:ReferenceVideo>
<space:Canvas id="vertical" width="720" height="1280"/>
- <program:Clock id="clock" frame-rate="30"/>
+ <time:Clock id="clock" frame-rate="30"/>
<pipeline:Normalize id="soundtrack-media" source={soundtrack}
video="none" audio="default" span-authority="audio" clock={clock}/>
<pipeline:Normalize id="ranking-appear-media" source={ranking-appear-sfx}
video="none" audio="default" span-authority="audio" clock={clock}/>
<pipeline:Normalize id="ranking-move-media" source={ranking-move-sfx}
video="none" audio="default" span-authority="audio" clock={clock}/>
- <space:Frame id="speech-frame" within={vertical}
+ <space:Frame id="speech-frame" within={vertical.bounds}
left="0%" top="0%" right="100%" bottom="100%"/>
- <space:Frame id="tier-frame" within={vertical}
+ <space:Frame id="tier-frame" within={vertical.bounds}
left="0%" top="55%" right="100%" bottom="100%"/>
<!-- B-roll lives inside the lower board region. Deliberately varied card
@@ -168,21 +168,21 @@
<space:Extent id="walks-around-extent" width="2688" height="2016"/>
<space:Extent id="hat-trick-extent" width="2048" height="2048"/>
- <space:AspectFrame id="hair-gel-frame" within={vertical}
+ <space:AspectFrame id="hair-gel-frame" within={vertical.bounds}
x="34%" y="78%" width="58%" aspect={hair-gel-extent} anchor="center"/>
- <space:AspectFrame id="trophy-frame" within={vertical}
+ <space:AspectFrame id="trophy-frame" within={vertical.bounds}
x="73%" y="82%" width="42%" aspect={trophy-extent} anchor="center"/>
- <space:AspectFrame id="greek-god-frame" within={vertical}
+ <space:AspectFrame id="greek-god-frame" within={vertical.bounds}
x="24%" y="78%" width="38%" aspect={greek-god-extent} anchor="center"/>
- <space:AspectFrame id="greek-tragedy-frame" within={vertical}
+ <space:AspectFrame id="greek-tragedy-frame" within={vertical.bounds}
x="63%" y="79%" width="66%" aspect={greek-tragedy-extent} anchor="center"/>
- <space:AspectFrame id="penaldo-social-frame" within={vertical}
+ <space:AspectFrame id="penaldo-social-frame" within={vertical.bounds}
x="50%" y="78%" width="94%" aspect={penaldo-social-extent} anchor="center"/>
- <space:AspectFrame id="tired-dad-frame" within={vertical}
+ <space:AspectFrame id="tired-dad-frame" within={vertical.bounds}
x="58%" y="79%" width="62%" aspect={tired-dad-extent} anchor="center"/>
- <space:AspectFrame id="walks-around-frame" within={vertical}
+ <space:AspectFrame id="walks-around-frame" within={vertical.bounds}
x="38%" y="79%" width="68%" aspect={walks-around-extent} anchor="center"/>
- <space:AspectFrame id="hat-trick-frame" within={vertical}
+ <space:AspectFrame id="hat-trick-frame" within={vertical.bounds}
x="72%" y="80%" width="46%" aspect={hat-trick-extent} anchor="center"/>
<!-- Real Build path: generated video -> one shared normalization waist ->
@@ -191,27 +191,61 @@
video="primary-moving" audio="default" span-authority="video" clock={clock}/>
<pipeline:Normalize id="messi-media" source={messi-take.video}
video="primary-moving" audio="default" span-authority="video" clock={clock}/>
- <whisperx:SemanticTake id="ronaldo-semantic" narrative={story}
- segment={story.segment.ronaldo} media={ronaldo-media.media} language="en"/>
- <whisperx:SemanticTake id="messi-semantic" narrative={story}
- segment={story.segment.messi} media={messi-media.media} language="en"/>
+ <whisperx:Alignment id="ronaldo-semantic" narrative={story}
+ segment={story.segment.ronaldo} media={ronaldo-media.media} domain={ronaldo-media.domain} language="en"/>
+ <whisperx:Alignment id="messi-semantic" narrative={story}
+ segment={story.segment.messi} media={messi-media.media} domain={messi-media.domain} language="en"/>
- <time:Timeline id="speech" clock={clock}>
- <time:Take source={ronaldo-semantic.take}/>
- <time:Take source={messi-semantic.take}/>
+ <time:Timeline id="speech" clock={clock} end="messi-semantic.end">
+ <time:Window id="ronaldo-semantic" from="start" for={ronaldo-media.extent}/>
+ <time:Window id="messi-semantic" from="ronaldo-semantic.end" for={messi-media.extent}/>
</time:Timeline>
- <sound:Style id="speech-sound-style"/>
- <sound:Track id="speech-sound" timeline={speech.timeline}>
- <sound:Use style={speech-sound-style}/>
- </sound:Track>
- <performance:Style id="speech-picture-style" frame={speech-frame} appearance={recipes.media.performance}/>
- <performance:Track id="speech-picture" timeline={speech.timeline} canvas={vertical}>
- <performance:Use style={speech-picture-style} during="program"/>
- </performance:Track>
+
+ <semantic:Projection id="story-time" narrative={story} timeline={speech.timeline}>
+ <semantic:Map alignment={ronaldo-semantic.alignment} domain={ronaldo-media.domain} window={speech.ronaldo-semantic}/>
+ <semantic:Map alignment={messi-semantic.alignment} domain={messi-media.domain} window={speech.messi-semantic}/>
+ <semantic:Window id="segment-ronaldo" segment={story.segment.ronaldo}/>
+ <semantic:Window id="segment-messi" segment={story.segment.messi}/>
+ <semantic:Window id="selection-hair-gel" selection={story.selection.hair-gel}/>
+ <semantic:Window id="selection-trophy" selection={story.selection.trophy}/>
+ <semantic:Window id="selection-greek-god" selection={story.selection.greek-god}/>
+ <semantic:Window id="selection-greek-tragedy" selection={story.selection.greek-tragedy}/>
+ <semantic:Window id="selection-penaldo-social" selection={story.selection.penaldo-social}/>
+ <semantic:Window id="selection-tired-dad" selection={story.selection.tired-dad}/>
+ <semantic:Window id="selection-walks-around" selection={story.selection.walks-around}/>
+ <semantic:Window id="selection-hat-trick" selection={story.selection.hat-trick}/>
+ </semantic:Projection>
+ <audio:Track id="speech-sound" timeline={speech.timeline}>
+ <audio:Clip id="ronaldo-semantic-source" source={ronaldo-media.media} during={speech.ronaldo-semantic}/>
+ <audio:Clip id="messi-semantic-source" source={messi-media.media} during={speech.messi-semantic}/>
+ </audio:Track>
+ <visual:Motion id="broll-left">
+ <visual:Pose at="start" scale="0.7" opacity="0" easing="ease-out"/>
+ <visual:Pose at="6f" scale="1" opacity="1"/>
+ <visual:Pose at="end-4f" scale="1" opacity="1" easing="ease-in"/>
+ <visual:Pose at="end" scale="1" opacity="0"/>
+ </visual:Motion>
+ <visual:Motion id="broll-right">
+ <visual:Pose at="start" y="80" scale="0.92" opacity="0" easing="ease-out"/>
+ <visual:Pose at="7f" y="0" scale="1" opacity="1"/>
+ <visual:Pose at="end-4f" y="0" scale="1" opacity="1" easing="ease-in"/>
+ <visual:Pose at="end" y="0" scale="0.94" opacity="1"/>
+ </visual:Motion>
+ <visual:Motion id="broll-wide">
+ <visual:Pose at="start" scale="0.9" opacity="1" easing="ease-out"/>
+ <visual:Pose at="6f" scale="1" opacity="1"/>
+ <visual:Pose at="end-4f" scale="1" opacity="1" easing="ease-in"/>
+ <visual:Pose at="end" scale="1" opacity="0"/>
+ </visual:Motion>
+
+ <visual:Track id="speech-picture" timeline={speech.timeline}>
+ <visual:Clip id="ronaldo-semantic-source" media={ronaldo-media.media} during={speech.ronaldo-semantic} frame={speech-frame} z="0" fit="cover"/>
+ <visual:Clip id="messi-semantic-source" media={messi-media.media} during={speech.messi-semantic} frame={speech-frame} z="0" fit="cover"/>
+ </visual:Track>
<audio-track:Track id="music-bed" timeline={speech.timeline}>
- <audio-track:Item source={soundtrack-media.media} during="program"
- playback="once-start" gain="0.12" fade-in="300ms" fade-out="600ms"/>
+ <audio-track:Clip source={soundtrack-media.media} during="timeline"
+ gain="0.12" fade-in="300ms" fade-out="600ms"/>
</audio-track:Track>
<fonts:Stack id="display-font" family="montserrat" weight="900" style="normal"/>
@@ -219,8 +253,8 @@
<ranking:TierBoardStyle id="tier-style" recipe={recipes.ranking.football}
font={tier-font}/>
<ranking:TierBoard id="football-tiers" timeline={speech.timeline}
- canvas={vertical} frame={tier-frame}
- during="program" style={tier-style}
+ within={vertical.bounds} frame={tier-frame}
+ during="timeline" style={tier-style}
appear-sound={ranking-appear-media.media}
move-sound={ranking-move-media.media}>
<ranking:TierItem id="yamal" tier="s" preset="true" icon={yamal-icon.image}/>
@@ -233,64 +267,65 @@
<ranking:TierItem id="neymar" tier="d" preset="true" icon={neymar-icon.image}/>
<ranking:TierItem id="benzema" tier="d" preset="true" icon={benzema-icon.image}/>
<ranking:TierItem id="ronaldo" tier="d" entry="drop"
- icon={ronaldo-icon.image} during={story.segment.ronaldo}/>
+ icon={ronaldo-icon.image} during={story-time.segment-ronaldo}/>
<ranking:TierItem id="messi" tier="s" entry="drop"
- icon={messi-icon.image} during={story.segment.messi}/>
+ icon={messi-icon.image} during={story-time.segment-messi}/>
</ranking:TierBoard>
<!-- Every Item consumes a projected Selection window. Later overlapping
- jokes use a higher stack order through their appearance Recipe. -->
- <media-track:Track id="broll" timeline={speech.timeline} canvas={vertical}>
- <media-track:Item id="hair-gel" image={broll-hair-gel.image}
- extent={hair-gel-extent} during={story.selection.hair-gel}
- frame={hair-gel-frame} appearance={recipes.media.hair-gel}
- motion={recipes.motion.broll-left}/>
- <media-track:Item id="trophy" image={broll-trophy.image}
- extent={trophy-extent} during={story.selection.trophy}
- frame={trophy-frame} appearance={recipes.media.trophy}
- motion={recipes.motion.broll-right}/>
- <media-track:Item id="greek-god" image={broll-greek-god.image}
- extent={greek-god-extent} during={story.selection.greek-god}
- frame={greek-god-frame} appearance={recipes.media.greek-god}
- motion={recipes.motion.broll-left}/>
- <media-track:Item id="greek-tragedy" image={broll-greek-tragedy.image}
- extent={greek-tragedy-extent} during={story.selection.greek-tragedy}
- frame={greek-tragedy-frame} appearance={recipes.media.greek-tragedy}
- motion={recipes.motion.broll-right}/>
- <media-track:Item id="penaldo-social" image={broll-penaldo-social.image}
- extent={penaldo-social-extent} during={story.selection.penaldo-social}
- frame={penaldo-social-frame} appearance={recipes.media.penaldo-social}
- motion={recipes.motion.broll-wide}/>
- <media-track:Item id="tired-dad" image={broll-tired-dad-trophy.image}
- extent={tired-dad-extent} during={story.selection.tired-dad}
- frame={tired-dad-frame} appearance={recipes.media.tired-dad}
- motion={recipes.motion.broll-right}/>
- <media-track:Item id="walks-around" image={broll-walks-around.image}
- extent={walks-around-extent} during={story.selection.walks-around}
- frame={walks-around-frame} appearance={recipes.media.walks-around}
- motion={recipes.motion.broll-left}/>
- <media-track:Item id="hat-trick" image={broll-hat-trick.image}
- extent={hat-trick-extent} during={story.selection.hat-trick}
- frame={hat-trick-frame} appearance={recipes.media.hat-trick}
- motion={recipes.motion.broll-right}/>
- </media-track:Track>
+ jokes use a higher explicit z on their own Clip occurrence. -->
+ <visual:Track id="broll" timeline={speech.timeline}>
+ <visual:Clip id="hair-gel" image={broll-hair-gel.image}
+ extent={hair-gel-extent} during={story-time.selection-hair-gel}
+ frame={hair-gel-frame} z="40" fit="cover" treatment={recipes.media.hair-gel}
+ motion={broll-left}/>
+ <visual:Clip id="trophy" image={broll-trophy.image}
+ extent={trophy-extent} during={story-time.selection-trophy}
+ frame={trophy-frame} z="41" fit="cover" treatment={recipes.media.trophy}
+ motion={broll-right}/>
+ <visual:Clip id="greek-god" image={broll-greek-god.image}
+ extent={greek-god-extent} during={story-time.selection-greek-god}
+ frame={greek-god-frame} z="42" fit="cover" treatment={recipes.media.greek-god}
+ motion={broll-left}/>
+ <visual:Clip id="greek-tragedy" image={broll-greek-tragedy.image}
+ extent={greek-tragedy-extent} during={story-time.selection-greek-tragedy}
+ frame={greek-tragedy-frame} z="43" fit="cover" treatment={recipes.media.greek-tragedy}
+ motion={broll-right}/>
+ <visual:Clip id="penaldo-social" image={broll-penaldo-social.image}
+ extent={penaldo-social-extent} during={story-time.selection-penaldo-social}
+ frame={penaldo-social-frame} z="44" fit="cover" treatment={recipes.media.penaldo-social}
+ motion={broll-wide}/>
+ <visual:Clip id="tired-dad" image={broll-tired-dad-trophy.image}
+ extent={tired-dad-extent} during={story-time.selection-tired-dad}
+ frame={tired-dad-frame} z="45" fit="cover" treatment={recipes.media.tired-dad}
+ motion={broll-right}/>
+ <visual:Clip id="walks-around" image={broll-walks-around.image}
+ extent={walks-around-extent} during={story-time.selection-walks-around}
+ frame={walks-around-frame} z="46" fit="cover" treatment={recipes.media.walks-around}
+ motion={broll-left}/>
+ <visual:Clip id="hat-trick" image={broll-hat-trick.image}
+ extent={hat-trick-extent} during={story-time.selection-hat-trick}
+ frame={hat-trick-frame} z="47" fit="cover" treatment={recipes.media.hat-trick}
+ motion={broll-right}/>
+ </visual:Track>
<caption-fine:Style id="caption-style" recipe={recipes.caption.primary}
font={display-font}/>
- <caption-fine:Track id="captions" document={story.caption}
- timeline={speech.timeline}>
+ <narrative-caption:Timing id="caption-timing" document={story.caption} binding={story.caption-binding} projection={story-time.projection}/>
+ <caption-fine:Caption id="captions" document={story.caption} timing={caption-timing}
+ timeline={speech.timeline} within={vertical.bounds}>
<caption-fine:Use style={caption-style}/>
- </caption-fine:Track>
+ </caption-fine:Caption>
- <film:Film id="main" canvas={vertical} timeline={speech.timeline}
+ <film:Film id="main" canvas={vertical.canvas} timeline={speech.timeline}
appearance={recipes.film.vertical}>
<film:Track source={speech-picture.visual}/>
<film:Track source={speech-sound.audio}/>
<film:Track source={football-tiers.visual}/>
<film:Track source={football-tiers.audio}/>
<film:Track source={broll.visual}/>
- <film:Track source={captions.track}/>
+ <film:Track source={captions.visual}/>
<film:Track source={music-bed.audio}/>
</film:Film>
<render:Video id="final" composition={main.composition}
diff --git a/examples/ranking-football/reference.svml b/examples/ranking-football/reference.svml
index 64756c4c..e92e0e50 100644
--- a/examples/ranking-football/reference.svml
+++ b/examples/ranking-football/reference.svml
@@ -2,7 +2,6 @@
<svml>
<import from="@hypit/script@1"/>
- <import as="sound" from="@hypit/sound@1"/>
<import as="text" from="@hypit/text@1"/>
<import as="asset" from="@hypit/media@1"/>
<import as="fish" from="@hypit/fishaudio-speech@1"/>
@@ -10,15 +9,15 @@
<import as="seedance" from="@hypit/seedance@1"/>
<import as="pipeline" from="@hypit/media-pipeline@1"/>
<import as="whisperx" from="@hypit/whisperx@1"/>
+ <import as="semantic" from="@hypit/narrative-temporal@1"/>
+ <import as="narrative-caption" from="@hypit/narrative-caption@1"/>
<import as="time" from="@hypit/timeline-author@1"/>
- <import as="media-track" from="@hypit/media-track@1"/>
- <import as="performance" from="@hypit/performance@1"/>
- <import as="audio-track" from="@hypit/audio-track@1"/>
+ <import as="visual" from="@hypit/visual-track@1"/>
+ <import as="audio" from="@hypit/audio-track@1"/>
<import as="caption" from="@hypit/caption@1"/>
<import as="caption-fine" from="@hypit/caption-fine@1"/>
<import as="fonts" from="@hypit/fonts-open@1"/>
<import as="space" from="@hypit/spatial@1"/>
- <import as="program" from="@hypit/program-space@1"/>
<import as="ranking" from="@hypit/ranking@1"/>
<import as="film" from="@hypit/film@1"/>
<import as="render" from="@hypit/render-hyperframes@1"/>
@@ -175,16 +174,16 @@
</seedance:ReferenceVideo>
<space:Canvas id="vertical" width="720" height="1280"/>
- <program:Clock id="clock" frame-rate="30"/>
+ <time:Clock id="clock" frame-rate="30"/>
<pipeline:Normalize id="soundtrack-media" source={soundtrack}
video="none" audio="default" span-authority="audio" clock={clock}/>
<pipeline:Normalize id="ranking-appear-media" source={ranking-appear-sfx}
video="none" audio="default" span-authority="audio" clock={clock}/>
<pipeline:Normalize id="ranking-move-media" source={ranking-move-sfx}
video="none" audio="default" span-authority="audio" clock={clock}/>
- <space:Frame id="speech-frame" within={vertical}
+ <space:Frame id="speech-frame" within={vertical.bounds}
left="0%" top="0%" right="100%" bottom="100%"/>
- <space:Frame id="tier-frame" within={vertical}
+ <space:Frame id="tier-frame" within={vertical.bounds}
left="0%" top="55%" right="100%" bottom="100%"/>
<!-- B-roll lives inside the lower board region. Deliberately varied card
@@ -199,21 +198,21 @@
<space:Extent id="walks-around-extent" width="2688" height="2016"/>
<space:Extent id="hat-trick-extent" width="2048" height="2048"/>
- <space:AspectFrame id="hair-gel-frame" within={vertical}
+ <space:AspectFrame id="hair-gel-frame" within={vertical.bounds}
x="34%" y="78%" width="58%" aspect={hair-gel-extent} anchor="center"/>
- <space:AspectFrame id="trophy-frame" within={vertical}
+ <space:AspectFrame id="trophy-frame" within={vertical.bounds}
x="73%" y="82%" width="42%" aspect={trophy-extent} anchor="center"/>
- <space:AspectFrame id="greek-god-frame" within={vertical}
+ <space:AspectFrame id="greek-god-frame" within={vertical.bounds}
x="24%" y="78%" width="38%" aspect={greek-god-extent} anchor="center"/>
- <space:AspectFrame id="greek-tragedy-frame" within={vertical}
+ <space:AspectFrame id="greek-tragedy-frame" within={vertical.bounds}
x="63%" y="79%" width="66%" aspect={greek-tragedy-extent} anchor="center"/>
- <space:AspectFrame id="penaldo-social-frame" within={vertical}
+ <space:AspectFrame id="penaldo-social-frame" within={vertical.bounds}
x="50%" y="78%" width="94%" aspect={penaldo-social-extent} anchor="center"/>
- <space:AspectFrame id="tired-dad-frame" within={vertical}
+ <space:AspectFrame id="tired-dad-frame" within={vertical.bounds}
x="58%" y="79%" width="62%" aspect={tired-dad-extent} anchor="center"/>
- <space:AspectFrame id="walks-around-frame" within={vertical}
+ <space:AspectFrame id="walks-around-frame" within={vertical.bounds}
x="38%" y="79%" width="68%" aspect={walks-around-extent} anchor="center"/>
- <space:AspectFrame id="hat-trick-frame" within={vertical}
+ <space:AspectFrame id="hat-trick-frame" within={vertical.bounds}
x="72%" y="80%" width="46%" aspect={hat-trick-extent} anchor="center"/>
<!-- Real Build path: generated video -> one shared normalization waist ->
@@ -222,36 +221,44 @@
video="primary-moving" audio="default" span-authority="video" clock={clock}/>
<pipeline:Normalize id="messi-media" source={messi-take.video}
video="primary-moving" audio="default" span-authority="video" clock={clock}/>
- <whisperx:SemanticTake id="ronaldo-semantic" narrative={story}
- segment={story.segment.ronaldo} media={ronaldo-media.media} language="en"/>
- <whisperx:SemanticTake id="messi-semantic" narrative={story}
- segment={story.segment.messi} media={messi-media.media} language="en"/>
+ <whisperx:Alignment id="ronaldo-semantic" narrative={story}
+ segment={story.segment.ronaldo} media={ronaldo-media.media} domain={ronaldo-media.domain} language="en"/>
+ <whisperx:Alignment id="messi-semantic" narrative={story}
+ segment={story.segment.messi} media={messi-media.media} domain={messi-media.domain} language="en"/>
- <time:Timeline id="speech" clock={clock}>
- <time:Take source={ronaldo-semantic.take}/>
- <time:Take source={messi-semantic.take}/>
+ <time:Timeline id="speech" clock={clock} end="messi-semantic.end">
+ <time:Window id="ronaldo-semantic" from="start" for={ronaldo-media.extent}/>
+ <time:Window id="messi-semantic" from="ronaldo-semantic.end" for={messi-media.extent}/>
</time:Timeline>
- <sound:Style id="speech-sound-style"/>
- <sound:Track id="speech-sound" timeline={speech.timeline}>
- <sound:Use style={speech-sound-style}/>
- </sound:Track>
- <performance:Style id="speech-picture-style" frame={speech-frame} appearance={recipes.media.performance}/>
- <performance:Track id="speech-picture" timeline={speech.timeline} canvas={vertical}>
- <performance:Use style={speech-picture-style} during="program"/>
- </performance:Track>
- <audio-track:Track id="music-bed" timeline={speech.timeline}>
- <audio-track:Item source={soundtrack-media.media} during="program"
- playback="once-start" gain="0.12" fade-in="300ms" fade-out="600ms"/>
- </audio-track:Track>
+ <semantic:Projection id="story-time" narrative={story} timeline={speech.timeline}>
+ <semantic:Map alignment={ronaldo-semantic.alignment} domain={ronaldo-media.domain} window={speech.ronaldo-semantic}/>
+ <semantic:Map alignment={messi-semantic.alignment} domain={messi-media.domain} window={speech.messi-semantic}/>
+ <semantic:Window id="segment-ronaldo" segment={story.segment.ronaldo}/>
+ <semantic:Window id="segment-messi" segment={story.segment.messi}/>
+ <semantic:Window id="selection-hair-gel" selection={story.selection.hair-gel}/>
+ <semantic:Window id="selection-trophy" selection={story.selection.trophy}/>
+ <semantic:Window id="selection-greek-god" selection={story.selection.greek-god}/>
+ <semantic:Window id="selection-greek-tragedy" selection={story.selection.greek-tragedy}/>
+ <semantic:Window id="selection-penaldo-social" selection={story.selection.penaldo-social}/>
+ <semantic:Window id="selection-tired-dad" selection={story.selection.tired-dad}/>
+ <semantic:Window id="selection-walks-around" selection={story.selection.walks-around}/>
+ <semantic:Window id="selection-hat-trick" selection={story.selection.hat-trick}/>
+ </semantic:Projection>
+ <audio:Track id="mix" timeline={speech.timeline}>
+ <audio:Clip id="ronaldo-semantic-source" source={ronaldo-media.media} during={speech.ronaldo-semantic}/>
+ <audio:Clip id="messi-semantic-source" source={messi-media.media} during={speech.messi-semantic}/>
+ <audio:Clip id="music-bed" source={soundtrack-media.media} during="timeline"
+ gain="0.12" fade-in="300ms" fade-out="600ms"/>
+ </audio:Track>
<fonts:Stack id="display-font" family="montserrat" weight="900" style="normal"/>
<fonts:Stack id="tier-font" family="inter" weight="400" style="normal"/>
<ranking:TierBoardStyle id="tier-style" recipe={recipes.ranking.football}
font={tier-font}/>
<ranking:TierBoard id="football-tiers" timeline={speech.timeline}
- canvas={vertical} frame={tier-frame}
- during="program" style={tier-style}
+ within={vertical.bounds} frame={tier-frame}
+ during="timeline" style={tier-style}
appear-sound={ranking-appear-media.media}
move-sound={ranking-move-media.media}>
<ranking:TierItem id="yamal" tier="s" preset="true" icon={yamal-icon}/>
@@ -264,65 +271,85 @@
<ranking:TierItem id="neymar" tier="d" preset="true" icon={neymar-icon}/>
<ranking:TierItem id="benzema" tier="d" preset="true" icon={benzema-icon}/>
<ranking:TierItem id="ronaldo" tier="d" entry="drop"
- icon={ronaldo-icon} during={story.segment.ronaldo}/>
+ icon={ronaldo-icon} during={story-time.segment-ronaldo}/>
<ranking:TierItem id="messi" tier="s" entry="drop"
- icon={messi-icon} during={story.segment.messi}/>
+ icon={messi-icon} during={story-time.segment-messi}/>
</ranking:TierBoard>
<!-- Every Item consumes a projected Selection window. Later overlapping
- jokes use a higher stack order through their appearance Recipe. -->
- <media-track:Track id="broll" timeline={speech.timeline} canvas={vertical}>
- <media-track:Item id="hair-gel" image={broll-hair-gel.image}
- extent={hair-gel-extent} during={story.selection.hair-gel}
- frame={hair-gel-frame} appearance={recipes.media.hair-gel}
- motion={recipes.motion.broll-left}/>
- <media-track:Item id="trophy" image={broll-trophy.image}
- extent={trophy-extent} during={story.selection.trophy}
- frame={trophy-frame} appearance={recipes.media.trophy}
- motion={recipes.motion.broll-right}/>
- <media-track:Item id="greek-god" image={broll-greek-god.image}
- extent={greek-god-extent} during={story.selection.greek-god}
- frame={greek-god-frame} appearance={recipes.media.greek-god}
- motion={recipes.motion.broll-left}/>
- <media-track:Item id="greek-tragedy" image={broll-greek-tragedy.image}
- extent={greek-tragedy-extent} during={story.selection.greek-tragedy}
- frame={greek-tragedy-frame} appearance={recipes.media.greek-tragedy}
- motion={recipes.motion.broll-right}/>
- <media-track:Item id="penaldo-social" image={broll-penaldo-social.image}
- extent={penaldo-social-extent} during={story.selection.penaldo-social}
- frame={penaldo-social-frame} appearance={recipes.media.penaldo-social}
- motion={recipes.motion.broll-wide}/>
- <media-track:Item id="tired-dad" image={broll-tired-dad-trophy.image}
- extent={tired-dad-extent} during={story.selection.tired-dad}
- frame={tired-dad-frame} appearance={recipes.media.tired-dad}
- motion={recipes.motion.broll-right}/>
- <media-track:Item id="walks-around" image={broll-walks-around.image}
- extent={walks-around-extent} during={story.selection.walks-around}
- frame={walks-around-frame} appearance={recipes.media.walks-around}
- motion={recipes.motion.broll-left}/>
- <media-track:Item id="hat-trick" image={broll-hat-trick.image}
- extent={hat-trick-extent} during={story.selection.hat-trick}
- frame={hat-trick-frame} appearance={recipes.media.hat-trick}
- motion={recipes.motion.broll-right}/>
- </media-track:Track>
+ jokes use a higher explicit z on their own Clip occurrence. -->
+ <visual:Motion id="broll-left">
+ <visual:Pose at="start" scale="0.7" opacity="0" easing="ease-out"/>
+ <visual:Pose at="6f" scale="1" opacity="1"/>
+ <visual:Pose at="end-4f" scale="1" opacity="1" easing="ease-in"/>
+ <visual:Pose at="end" scale="1" opacity="0"/>
+ </visual:Motion>
+ <visual:Motion id="broll-right">
+ <visual:Pose at="start" y="80" scale="0.92" opacity="0" easing="ease-out"/>
+ <visual:Pose at="7f" y="0" scale="1" opacity="1"/>
+ <visual:Pose at="end-4f" y="0" scale="1" opacity="1" easing="ease-in"/>
+ <visual:Pose at="end" y="0" scale="0.94" opacity="1"/>
+ </visual:Motion>
+ <visual:Motion id="broll-wide">
+ <visual:Pose at="start" scale="0.9" opacity="1" easing="ease-out"/>
+ <visual:Pose at="6f" scale="1" opacity="1"/>
+ <visual:Pose at="end-4f" scale="1" opacity="1" easing="ease-in"/>
+ <visual:Pose at="end" scale="1" opacity="0"/>
+ </visual:Motion>
+
+ <visual:Track id="picture" timeline={speech.timeline}>
+ <visual:Clip id="ronaldo-semantic-source" media={ronaldo-media.media} during={speech.ronaldo-semantic} frame={speech-frame} z="0" fit="cover"/>
+ <visual:Clip id="messi-semantic-source" media={messi-media.media} during={speech.messi-semantic} frame={speech-frame} z="0" fit="cover"/>
+ <visual:Clip id="hair-gel" image={broll-hair-gel.image}
+ extent={hair-gel-extent} during={story-time.selection-hair-gel}
+ frame={hair-gel-frame} z="40" fit="cover" treatment={recipes.media.hair-gel}
+ motion={broll-left}/>
+ <visual:Clip id="trophy" image={broll-trophy.image}
+ extent={trophy-extent} during={story-time.selection-trophy}
+ frame={trophy-frame} z="41" fit="cover" treatment={recipes.media.trophy}
+ motion={broll-right}/>
+ <visual:Clip id="greek-god" image={broll-greek-god.image}
+ extent={greek-god-extent} during={story-time.selection-greek-god}
+ frame={greek-god-frame} z="42" fit="cover" treatment={recipes.media.greek-god}
+ motion={broll-left}/>
+ <visual:Clip id="greek-tragedy" image={broll-greek-tragedy.image}
+ extent={greek-tragedy-extent} during={story-time.selection-greek-tragedy}
+ frame={greek-tragedy-frame} z="43" fit="cover" treatment={recipes.media.greek-tragedy}
+ motion={broll-right}/>
+ <visual:Clip id="penaldo-social" image={broll-penaldo-social.image}
+ extent={penaldo-social-extent} during={story-time.selection-penaldo-social}
+ frame={penaldo-social-frame} z="44" fit="cover" treatment={recipes.media.penaldo-social}
+ motion={broll-wide}/>
+ <visual:Clip id="tired-dad" image={broll-tired-dad-trophy.image}
+ extent={tired-dad-extent} during={story-time.selection-tired-dad}
+ frame={tired-dad-frame} z="45" fit="cover" treatment={recipes.media.tired-dad}
+ motion={broll-right}/>
+ <visual:Clip id="walks-around" image={broll-walks-around.image}
+ extent={walks-around-extent} during={story-time.selection-walks-around}
+ frame={walks-around-frame} z="46" fit="cover" treatment={recipes.media.walks-around}
+ motion={broll-left}/>
+ <visual:Clip id="hat-trick" image={broll-hat-trick.image}
+ extent={hat-trick-extent} during={story-time.selection-hat-trick}
+ frame={hat-trick-frame} z="47" fit="cover" treatment={recipes.media.hat-trick}
+ motion={broll-right}/>
+ </visual:Track>
<caption-fine:Style id="caption-style" recipe={recipes.caption.primary}
font={display-font}/>
- <caption-fine:Track id="captions" document={story.caption}
- timeline={speech.timeline}>
+ <narrative-caption:Timing id="caption-timing" document={story.caption} binding={story.caption-binding} projection={story-time.projection}/>
+ <caption-fine:Caption id="captions" document={story.caption} timing={caption-timing}
+ timeline={speech.timeline} within={vertical.bounds}>
<caption-fine:Use style={caption-style}/>
- </caption-fine:Track>
+ </caption-fine:Caption>
- <film:Film id="main" canvas={vertical} timeline={speech.timeline}
+ <film:Film id="main" canvas={vertical.canvas} timeline={speech.timeline}
appearance={recipes.film.vertical}>
- <film:Track source={speech-picture.visual}/>
- <film:Track source={speech-sound.audio}/>
+ <film:Track source={picture.visual}/>
+ <film:Track source={mix.audio}/>
<film:Track source={football-tiers.visual}/>
<film:Track source={football-tiers.audio}/>
- <film:Track source={broll.visual}/>
- <film:Track source={captions.track}/>
- <film:Track source={music-bed.audio}/>
+ <film:Track source={captions.visual}/>
</film:Film>
<render:Video id="final" composition={main.composition}
timeline={speech.timeline}/>
diff --git a/examples/ranking-football/swap-effect-banana-reference-sync/column-recipes.svs b/examples/ranking-football/swap-effect-banana-reference-sync/column-recipes.svs
index fb45e3d0..69db8666 100644
--- a/examples/ranking-football/swap-effect-banana-reference-sync/column-recipes.svs
+++ b/examples/ranking-football/swap-effect-banana-reference-sync/column-recipes.svs
@@ -11,14 +11,6 @@
film.vertical { background: #090A0F; }
- media.performance { stack-order: 0;
- fit: cover;
- frame-x: 0.5;
- frame-y: 0.5;
- content-x: 0.5;
- content-y: 0.5;
- }
-
/* Ten perceptually separated hues, balanced for the dark video background. */
ranking.football-column {
rank-colors: [
@@ -66,22 +58,13 @@
item-stack: 30;
}
- media.pitch-pov { stack-order: 40; fit: cover; shadows: 0 16 32 -8 #000000D9; }
- media.ikea-sign { stack-order: 41; fit: cover; shadows: 0 16 32 -8 #000000D9; }
- media.retirement-room { stack-order: 42; fit: cover; shadows: 0 16 32 -8 #000000D9; }
- media.rent-jump { stack-order: 43; fit: cover; shadows: 0 16 32 -8 #000000D9; }
- media.nine-hundred { stack-order: 44; fit: cover; shadows: 0 16 32 -8 #000000D9; }
- media.laboratory-body { stack-order: 45; fit: cover; shadows: 0 16 32 -8 #000000D9; }
- media.museum-jawline { stack-order: 46; fit: cover; shadows: 0 16 32 -8 #000000D9; }
-
- motion.broll {
- enter: pop;
- enter-frames: 6;
- enter-easing: ease-out;
- exit: fade;
- exit-frames: 4;
- exit-easing: ease-in;
- }
+ media.pitch-pov { shadows: 0 16 32 -8 #000000D9; }
+ media.ikea-sign { shadows: 0 16 32 -8 #000000D9; }
+ media.retirement-room { shadows: 0 16 32 -8 #000000D9; }
+ media.rent-jump { shadows: 0 16 32 -8 #000000D9; }
+ media.nine-hundred { shadows: 0 16 32 -8 #000000D9; }
+ media.laboratory-body { shadows: 0 16 32 -8 #000000D9; }
+ media.museum-jawline { shadows: 0 16 32 -8 #000000D9; }
/* Caption and stage share one horizontal center line. The caption remains
above the lower stage and wins every occasional overlap through z-order. */
diff --git a/examples/ranking-football/swap-effect-banana-reference-sync/hybrid-recipes.svs b/examples/ranking-football/swap-effect-banana-reference-sync/hybrid-recipes.svs
index 72106b70..02c4cef5 100644
--- a/examples/ranking-football/swap-effect-banana-reference-sync/hybrid-recipes.svs
+++ b/examples/ranking-football/swap-effect-banana-reference-sync/hybrid-recipes.svs
@@ -11,14 +11,6 @@
film.vertical { background: #090A0F; }
- media.performance { stack-order: 0;
- fit: cover;
- frame-x: 0.5;
- frame-y: 0.5;
- content-x: 0.5;
- content-y: 0.5;
- }
-
ranking.football {
rows: [
{ "id": "s", "label": "S", "color": "#EE5F52" },
@@ -89,49 +81,36 @@
/* B-roll cards sit above the Ranking board and below captions. The later
member of every overlapping joke pair receives the higher stack order. */
media.hair-gel {
- stack-order: 40; fit: cover;
+
shadows: 0 18 34 -8 #000000D9;
}
media.trophy {
- stack-order: 41; fit: cover;
+
shadows: 0 18 34 -8 #000000D9;
}
media.greek-god {
- stack-order: 42; fit: cover;
+
shadows: 0 18 34 -8 #000000D9;
}
media.greek-tragedy {
- stack-order: 43; fit: cover;
+
shadows: 0 18 34 -8 #000000D9;
}
media.penaldo-social {
- stack-order: 44; fit: cover;
+
shadows: 0 18 34 -8 #000000D9;
}
media.tired-dad {
- stack-order: 45; fit: cover;
+
shadows: 0 18 34 -8 #000000D9;
}
media.walks-around {
- stack-order: 46; fit: cover;
+
shadows: 0 18 34 -8 #000000D9;
}
media.hat-trick {
- stack-order: 47; fit: cover;
- shadows: 0 18 34 -8 #000000E6;
- }
- motion.broll-left {
- enter: pop; enter-frames: 6; enter-easing: ease-out;
- exit: fade; exit-frames: 4; exit-easing: ease-in;
- }
- motion.broll-right {
- enter: bounce; enter-frames: 7; enter-easing: ease-out;
- exit: scale; exit-frames: 4; exit-amount: 0.94; exit-easing: ease-in;
- }
- motion.broll-wide {
- enter: scale; enter-frames: 6; enter-amount: 0.9; enter-easing: ease-out;
- exit: fade; exit-frames: 4; exit-easing: ease-in;
+ shadows: 0 18 34 -8 #000000E6;
}
caption.primary {
diff --git a/examples/ranking-football/swap-effect-banana-reference-sync/swap-effect-banana-reference-sync.svml b/examples/ranking-football/swap-effect-banana-reference-sync/swap-effect-banana-reference-sync.svml
index 88b9b3a3..59835747 100644
--- a/examples/ranking-football/swap-effect-banana-reference-sync/swap-effect-banana-reference-sync.svml
+++ b/examples/ranking-football/swap-effect-banana-reference-sync/swap-effect-banana-reference-sync.svml
@@ -2,22 +2,22 @@
<svml>
<import from="@hypit/script@1"/>
- <import as="sound" from="@hypit/sound@1"/>
+ <import as="audio" from="@hypit/audio-track@1"/>
<import as="text" from="@hypit/text@1"/>
<import as="asset" from="@hypit/media@1"/>
<import as="gpt" from="@hypit/gpt-image@1"/>
<import as="seedance" from="@hypit/seedance@1"/>
<import as="pipeline" from="@hypit/media-pipeline@1"/>
<import as="whisperx" from="@hypit/whisperx@1"/>
+ <import as="semantic" from="@hypit/narrative-temporal@1"/>
+ <import as="narrative-caption" from="@hypit/narrative-caption@1"/>
<import as="time" from="@hypit/timeline-author@1"/>
- <import as="media-track" from="@hypit/media-track@1"/>
- <import as="performance" from="@hypit/performance@1"/>
+ <import as="visual" from="@hypit/visual-track@1"/>
<import as="audio-track" from="@hypit/audio-track@1"/>
<import as="caption" from="@hypit/caption@1"/>
<import as="caption-fine" from="@hypit/caption-fine@1"/>
<import as="fonts" from="@hypit/fonts-open@1"/>
<import as="space" from="@hypit/spatial@1"/>
- <import as="program" from="@hypit/program-space@1"/>
<import as="ranking" from="@hypit/ranking@1"/>
<import as="film" from="@hypit/film@1"/>
<import as="render" from="@hypit/render-hyperframes@1"/>
@@ -144,16 +144,16 @@
</seedance:ReferenceVideo>
<space:Canvas id="vertical" width="720" height="1280"/>
- <program:Clock id="clock" frame-rate="30"/>
+ <time:Clock id="clock" frame-rate="30"/>
<pipeline:Normalize id="soundtrack-media" source={soundtrack}
video="none" audio="default" span-authority="audio" clock={clock}/>
<pipeline:Normalize id="ranking-appear-media" source={ranking-appear-sfx}
video="none" audio="default" span-authority="audio" clock={clock}/>
<pipeline:Normalize id="ranking-move-media" source={ranking-move-sfx}
video="none" audio="default" span-authority="audio" clock={clock}/>
- <space:Frame id="speech-frame" within={vertical}
+ <space:Frame id="speech-frame" within={vertical.bounds}
left="0%" top="0%" right="100%" bottom="100%"/>
- <space:Frame id="column-frame" within={vertical}
+ <space:Frame id="column-frame" within={vertical.bounds}
left="0%" top="10%" right="26%" bottom="67.5%"/>
<!-- B-roll lives inside the lower board region. Deliberately varied card
@@ -168,21 +168,21 @@
<space:Extent id="walks-around-extent" width="2688" height="2016"/>
<space:Extent id="hat-trick-extent" width="2048" height="2048"/>
- <space:AspectFrame id="hair-gel-frame" within={vertical}
+ <space:AspectFrame id="hair-gel-frame" within={vertical.bounds}
x="34%" y="78%" width="58%" aspect={hair-gel-extent} anchor="center"/>
- <space:AspectFrame id="trophy-frame" within={vertical}
+ <space:AspectFrame id="trophy-frame" within={vertical.bounds}
x="73%" y="82%" width="42%" aspect={trophy-extent} anchor="center"/>
- <space:AspectFrame id="greek-god-frame" within={vertical}
+ <space:AspectFrame id="greek-god-frame" within={vertical.bounds}
x="24%" y="78%" width="38%" aspect={greek-god-extent} anchor="center"/>
- <space:AspectFrame id="greek-tragedy-frame" within={vertical}
+ <space:AspectFrame id="greek-tragedy-frame" within={vertical.bounds}
x="63%" y="79%" width="66%" aspect={greek-tragedy-extent} anchor="center"/>
- <space:AspectFrame id="penaldo-social-frame" within={vertical}
+ <space:AspectFrame id="penaldo-social-frame" within={vertical.bounds}
x="50%" y="78%" width="94%" aspect={penaldo-social-extent} anchor="center"/>
- <space:AspectFrame id="tired-dad-frame" within={vertical}
+ <space:AspectFrame id="tired-dad-frame" within={vertical.bounds}
x="58%" y="79%" width="62%" aspect={tired-dad-extent} anchor="center"/>
- <space:AspectFrame id="walks-around-frame" within={vertical}
+ <space:AspectFrame id="walks-around-frame" within={vertical.bounds}
x="38%" y="79%" width="68%" aspect={walks-around-extent} anchor="center"/>
- <space:AspectFrame id="hat-trick-frame" within={vertical}
+ <space:AspectFrame id="hat-trick-frame" within={vertical.bounds}
x="72%" y="80%" width="46%" aspect={hat-trick-extent} anchor="center"/>
<!-- Real Build path: generated video -> one shared normalization waist ->
@@ -191,27 +191,61 @@
video="primary-moving" audio="default" span-authority="video" clock={clock}/>
<pipeline:Normalize id="messi-media" source={messi-take.video}
video="primary-moving" audio="default" span-authority="video" clock={clock}/>
- <whisperx:SemanticTake id="ronaldo-semantic" narrative={story}
- segment={story.segment.ronaldo} media={ronaldo-media.media} language="en"/>
- <whisperx:SemanticTake id="messi-semantic" narrative={story}
- segment={story.segment.messi} media={messi-media.media} language="en"/>
+ <whisperx:Alignment id="ronaldo-semantic" narrative={story}
+ segment={story.segment.ronaldo} media={ronaldo-media.media} domain={ronaldo-media.domain} language="en"/>
+ <whisperx:Alignment id="messi-semantic" narrative={story}
+ segment={story.segment.messi} media={messi-media.media} domain={messi-media.domain} language="en"/>
- <time:Timeline id="speech" clock={clock}>
- <time:Take source={ronaldo-semantic.take}/>
- <time:Take source={messi-semantic.take}/>
+ <time:Timeline id="speech" clock={clock} end="messi-semantic.end">
+ <time:Window id="ronaldo-semantic" from="start" for={ronaldo-media.extent}/>
+ <time:Window id="messi-semantic" from="ronaldo-semantic.end" for={messi-media.extent}/>
</time:Timeline>
- <sound:Style id="speech-sound-style"/>
- <sound:Track id="speech-sound" timeline={speech.timeline}>
- <sound:Use style={speech-sound-style}/>
- </sound:Track>
- <performance:Style id="speech-picture-style" frame={speech-frame} appearance={recipes.media.performance}/>
- <performance:Track id="speech-picture" timeline={speech.timeline} canvas={vertical}>
- <performance:Use style={speech-picture-style} during="program"/>
- </performance:Track>
+
+ <semantic:Projection id="story-time" narrative={story} timeline={speech.timeline}>
+ <semantic:Map alignment={ronaldo-semantic.alignment} domain={ronaldo-media.domain} window={speech.ronaldo-semantic}/>
+ <semantic:Map alignment={messi-semantic.alignment} domain={messi-media.domain} window={speech.messi-semantic}/>
+ <semantic:Window id="segment-ronaldo" segment={story.segment.ronaldo}/>
+ <semantic:Window id="segment-messi" segment={story.segment.messi}/>
+ <semantic:Window id="selection-hair-gel" selection={story.selection.hair-gel}/>
+ <semantic:Window id="selection-trophy" selection={story.selection.trophy}/>
+ <semantic:Window id="selection-greek-god" selection={story.selection.greek-god}/>
+ <semantic:Window id="selection-greek-tragedy" selection={story.selection.greek-tragedy}/>
+ <semantic:Window id="selection-penaldo-social" selection={story.selection.penaldo-social}/>
+ <semantic:Window id="selection-tired-dad" selection={story.selection.tired-dad}/>
+ <semantic:Window id="selection-walks-around" selection={story.selection.walks-around}/>
+ <semantic:Window id="selection-hat-trick" selection={story.selection.hat-trick}/>
+ </semantic:Projection>
+ <audio:Track id="speech-sound" timeline={speech.timeline}>
+ <audio:Clip id="ronaldo-semantic-source" source={ronaldo-media.media} during={speech.ronaldo-semantic}/>
+ <audio:Clip id="messi-semantic-source" source={messi-media.media} during={speech.messi-semantic}/>
+ </audio:Track>
+ <visual:Motion id="broll-left">
+ <visual:Pose at="start" scale="0.7" opacity="0" easing="ease-out"/>
+ <visual:Pose at="6f" scale="1" opacity="1"/>
+ <visual:Pose at="end-4f" scale="1" opacity="1" easing="ease-in"/>
+ <visual:Pose at="end" scale="1" opacity="0"/>
+ </visual:Motion>
+ <visual:Motion id="broll-right">
+ <visual:Pose at="start" y="80" scale="0.92" opacity="0" easing="ease-out"/>
+ <visual:Pose at="7f" y="0" scale="1" opacity="1"/>
+ <visual:Pose at="end-4f" y="0" scale="1" opacity="1" easing="ease-in"/>
+ <visual:Pose at="end" y="0" scale="0.94" opacity="1"/>
+ </visual:Motion>
+ <visual:Motion id="broll-wide">
+ <visual:Pose at="start" scale="0.9" opacity="1" easing="ease-out"/>
+ <visual:Pose at="6f" scale="1" opacity="1"/>
+ <visual:Pose at="end-4f" scale="1" opacity="1" easing="ease-in"/>
+ <visual:Pose at="end" scale="1" opacity="0"/>
+ </visual:Motion>
+
+ <visual:Track id="speech-picture" timeline={speech.timeline}>
+ <visual:Clip id="ronaldo-semantic-source" media={ronaldo-media.media} during={speech.ronaldo-semantic} frame={speech-frame} z="0" fit="cover"/>
+ <visual:Clip id="messi-semantic-source" media={messi-media.media} during={speech.messi-semantic} frame={speech-frame} z="0" fit="cover"/>
+ </visual:Track>
<audio-track:Track id="music-bed" timeline={speech.timeline}>
- <audio-track:Item source={soundtrack-media.media} during="program"
- playback="once-start" gain="0.12" fade-in="300ms" fade-out="600ms"/>
+ <audio-track:Clip source={soundtrack-media.media} during="timeline"
+ gain="0.12" fade-in="300ms" fade-out="600ms"/>
</audio-track:Track>
<fonts:Stack id="display-font" family="montserrat" weight="900" style="normal"/>
@@ -219,13 +253,13 @@
<ranking:ColumnStyle id="column-style" recipe={recipes.ranking.football-column}
font={column-font}/>
<ranking:Column id="football-column" timeline={speech.timeline}
- canvas={vertical} frame={column-frame} during="program" style={column-style}
+ within={vertical.bounds} frame={column-frame} during="timeline" style={column-style}
appear-sound={ranking-appear-media.media}
move-sound={ranking-move-media.media}>
<ranking:ColumnItem id="ronaldo" rank="1" label="Ronaldo"
- icon={ronaldo-icon.image} during={story.segment.ronaldo}/>
+ icon={ronaldo-icon.image} during={story-time.segment-ronaldo}/>
<ranking:ColumnItem id="messi" rank="2" label="Messi"
- icon={messi-icon.image} during={story.segment.messi}/>
+ icon={messi-icon.image} during={story-time.segment-messi}/>
<ranking:ColumnItem id="yamal" rank="3" label="Yamal" preset="true" icon={yamal-icon.image}/>
<ranking:ColumnItem id="haaland" rank="4" label="Haaland" preset="true" icon={haaland-icon.image}/>
<ranking:ColumnItem id="de-bruyne" rank="5" label="De Bruyne" preset="true" icon={de-bruyne-icon.image}/>
@@ -238,58 +272,59 @@
</ranking:Column>
<!-- Every Item consumes a projected Selection window. Later overlapping
- jokes use a higher stack order through their appearance Recipe. -->
- <media-track:Track id="broll" timeline={speech.timeline} canvas={vertical}>
- <media-track:Item id="hair-gel" image={broll-hair-gel.image}
- extent={hair-gel-extent} during={story.selection.hair-gel}
- frame={hair-gel-frame} appearance={recipes.media.hair-gel}
- motion={recipes.motion.broll-left}/>
- <media-track:Item id="trophy" image={broll-trophy.image}
- extent={trophy-extent} during={story.selection.trophy}
- frame={trophy-frame} appearance={recipes.media.trophy}
- motion={recipes.motion.broll-right}/>
- <media-track:Item id="greek-god" image={broll-greek-god.image}
- extent={greek-god-extent} during={story.selection.greek-god}
- frame={greek-god-frame} appearance={recipes.media.greek-god}
- motion={recipes.motion.broll-left}/>
- <media-track:Item id="greek-tragedy" image={broll-greek-tragedy.image}
- extent={greek-tragedy-extent} during={story.selection.greek-tragedy}
- frame={greek-tragedy-frame} appearance={recipes.media.greek-tragedy}
- motion={recipes.motion.broll-right}/>
- <media-track:Item id="penaldo-social" image={broll-penaldo-social.image}
- extent={penaldo-social-extent} during={story.selection.penaldo-social}
- frame={penaldo-social-frame} appearance={recipes.media.penaldo-social}
- motion={recipes.motion.broll-wide}/>
- <media-track:Item id="tired-dad" image={broll-tired-dad-trophy.image}
- extent={tired-dad-extent} during={story.selection.tired-dad}
- frame={tired-dad-frame} appearance={recipes.media.tired-dad}
- motion={recipes.motion.broll-right}/>
- <media-track:Item id="walks-around" image={broll-walks-around.image}
- extent={walks-around-extent} during={story.selection.walks-around}
- frame={walks-around-frame} appearance={recipes.media.walks-around}
- motion={recipes.motion.broll-left}/>
- <media-track:Item id="hat-trick" image={broll-hat-trick.image}
- extent={hat-trick-extent} during={story.selection.hat-trick}
- frame={hat-trick-frame} appearance={recipes.media.hat-trick}
- motion={recipes.motion.broll-right}/>
- </media-track:Track>
+ jokes use a higher explicit z on their own Clip occurrence. -->
+ <visual:Track id="broll" timeline={speech.timeline}>
+ <visual:Clip id="hair-gel" image={broll-hair-gel.image}
+ extent={hair-gel-extent} during={story-time.selection-hair-gel}
+ frame={hair-gel-frame} z="40" fit="cover" treatment={recipes.media.hair-gel}
+ motion={broll-left}/>
+ <visual:Clip id="trophy" image={broll-trophy.image}
+ extent={trophy-extent} during={story-time.selection-trophy}
+ frame={trophy-frame} z="41" fit="cover" treatment={recipes.media.trophy}
+ motion={broll-right}/>
+ <visual:Clip id="greek-god" image={broll-greek-god.image}
+ extent={greek-god-extent} during={story-time.selection-greek-god}
+ frame={greek-god-frame} z="42" fit="cover" treatment={recipes.media.greek-god}
+ motion={broll-left}/>
+ <visual:Clip id="greek-tragedy" image={broll-greek-tragedy.image}
+ extent={greek-tragedy-extent} during={story-time.selection-greek-tragedy}
+ frame={greek-tragedy-frame} z="43" fit="cover" treatment={recipes.media.greek-tragedy}
+ motion={broll-right}/>
+ <visual:Clip id="penaldo-social" image={broll-penaldo-social.image}
+ extent={penaldo-social-extent} during={story-time.selection-penaldo-social}
+ frame={penaldo-social-frame} z="44" fit="cover" treatment={recipes.media.penaldo-social}
+ motion={broll-wide}/>
+ <visual:Clip id="tired-dad" image={broll-tired-dad-trophy.image}
+ extent={tired-dad-extent} during={story-time.selection-tired-dad}
+ frame={tired-dad-frame} z="45" fit="cover" treatment={recipes.media.tired-dad}
+ motion={broll-right}/>
+ <visual:Clip id="walks-around" image={broll-walks-around.image}
+ extent={walks-around-extent} during={story-time.selection-walks-around}
+ frame={walks-around-frame} z="46" fit="cover" treatment={recipes.media.walks-around}
+ motion={broll-left}/>
+ <visual:Clip id="hat-trick" image={broll-hat-trick.image}
+ extent={hat-trick-extent} during={story-time.selection-hat-trick}
+ frame={hat-trick-frame} z="47" fit="cover" treatment={recipes.media.hat-trick}
+ motion={broll-right}/>
+ </visual:Track>
<caption-fine:Style id="caption-style" recipe={recipes.caption.primary}
font={display-font}/>
- <caption-fine:Track id="captions" document={story.caption}
- timeline={speech.timeline}>
+ <narrative-caption:Timing id="caption-timing" document={story.caption} binding={story.caption-binding} projection={story-time.projection}/>
+ <caption-fine:Caption id="captions" document={story.caption} timing={caption-timing}
+ timeline={speech.timeline} within={vertical.bounds}>
<caption-fine:Use style={caption-style}/>
- </caption-fine:Track>
+ </caption-fine:Caption>
- <film:Film id="main" canvas={vertical} timeline={speech.timeline}
+ <film:Film id="main" canvas={vertical.canvas} timeline={speech.timeline}
appearance={recipes.film.vertical}>
<film:Track source={speech-picture.visual}/>
<film:Track source={speech-sound.audio}/>
<film:Track source={football-column.visual}/>
<film:Track source={football-column.audio}/>
<film:Track source={broll.visual}/>
- <film:Track source={captions.track}/>
+ <film:Track source={captions.visual}/>
<film:Track source={music-bed.audio}/>
</film:Film>
<render:Video id="final" composition={main.composition}
diff --git a/examples/ranking-football/swap-effect-banana/column-recipes.svs b/examples/ranking-football/swap-effect-banana/column-recipes.svs
index fb45e3d0..69db8666 100644
--- a/examples/ranking-football/swap-effect-banana/column-recipes.svs
+++ b/examples/ranking-football/swap-effect-banana/column-recipes.svs
@@ -11,14 +11,6 @@
film.vertical { background: #090A0F; }
- media.performance { stack-order: 0;
- fit: cover;
- frame-x: 0.5;
- frame-y: 0.5;
- content-x: 0.5;
- content-y: 0.5;
- }
-
/* Ten perceptually separated hues, balanced for the dark video background. */
ranking.football-column {
rank-colors: [
@@ -66,22 +58,13 @@
item-stack: 30;
}
- media.pitch-pov { stack-order: 40; fit: cover; shadows: 0 16 32 -8 #000000D9; }
- media.ikea-sign { stack-order: 41; fit: cover; shadows: 0 16 32 -8 #000000D9; }
- media.retirement-room { stack-order: 42; fit: cover; shadows: 0 16 32 -8 #000000D9; }
- media.rent-jump { stack-order: 43; fit: cover; shadows: 0 16 32 -8 #000000D9; }
- media.nine-hundred { stack-order: 44; fit: cover; shadows: 0 16 32 -8 #000000D9; }
- media.laboratory-body { stack-order: 45; fit: cover; shadows: 0 16 32 -8 #000000D9; }
- media.museum-jawline { stack-order: 46; fit: cover; shadows: 0 16 32 -8 #000000D9; }
-
- motion.broll {
- enter: pop;
- enter-frames: 6;
- enter-easing: ease-out;
- exit: fade;
- exit-frames: 4;
- exit-easing: ease-in;
- }
+ media.pitch-pov { shadows: 0 16 32 -8 #000000D9; }
+ media.ikea-sign { shadows: 0 16 32 -8 #000000D9; }
+ media.retirement-room { shadows: 0 16 32 -8 #000000D9; }
+ media.rent-jump { shadows: 0 16 32 -8 #000000D9; }
+ media.nine-hundred { shadows: 0 16 32 -8 #000000D9; }
+ media.laboratory-body { shadows: 0 16 32 -8 #000000D9; }
+ media.museum-jawline { shadows: 0 16 32 -8 #000000D9; }
/* Caption and stage share one horizontal center line. The caption remains
above the lower stage and wins every occasional overlap through z-order. */
diff --git a/examples/ranking-football/swap-effect-banana/swap-effect-banana.svml b/examples/ranking-football/swap-effect-banana/swap-effect-banana.svml
index da3ab81b..893fcdb2 100644
--- a/examples/ranking-football/swap-effect-banana/swap-effect-banana.svml
+++ b/examples/ranking-football/swap-effect-banana/swap-effect-banana.svml
@@ -2,22 +2,22 @@
<svml>
<import from="@hypit/script@1"/>
- <import as="sound" from="@hypit/sound@1"/>
+ <import as="audio" from="@hypit/audio-track@1"/>
<import as="text" from="@hypit/text@1"/>
<import as="asset" from="@hypit/media@1"/>
<import as="gpt" from="@hypit/gpt-image@1"/>
<import as="seedance" from="@hypit/seedance@1"/>
<import as="pipeline" from="@hypit/media-pipeline@1"/>
<import as="whisperx" from="@hypit/whisperx@1"/>
+ <import as="semantic" from="@hypit/narrative-temporal@1"/>
+ <import as="narrative-caption" from="@hypit/narrative-caption@1"/>
<import as="time" from="@hypit/timeline-author@1"/>
- <import as="media-track" from="@hypit/media-track@1"/>
- <import as="performance" from="@hypit/performance@1"/>
+ <import as="visual" from="@hypit/visual-track@1"/>
<import as="audio-track" from="@hypit/audio-track@1"/>
<import as="caption" from="@hypit/caption@1"/>
<import as="caption-fine" from="@hypit/caption-fine@1"/>
<import as="fonts" from="@hypit/fonts-open@1"/>
<import as="space" from="@hypit/spatial@1"/>
- <import as="program" from="@hypit/program-space@1"/>
<import as="ranking" from="@hypit/ranking@1"/>
<import as="film" from="@hypit/film@1"/>
<import as="render" from="@hypit/render-hyperframes@1"/>
@@ -132,16 +132,16 @@
</seedance:ReferenceVideo>
<space:Canvas id="vertical" width="720" height="1280"/>
- <program:Clock id="clock" frame-rate="30"/>
+ <time:Clock id="clock" frame-rate="30"/>
<pipeline:Normalize id="soundtrack-media" source={soundtrack}
video="none" audio="default" span-authority="audio" clock={clock}/>
<pipeline:Normalize id="ranking-appear-media" source={ranking-appear-sfx}
video="none" audio="default" span-authority="audio" clock={clock}/>
<pipeline:Normalize id="ranking-move-media" source={ranking-move-sfx}
video="none" audio="default" span-authority="audio" clock={clock}/>
- <space:Frame id="speech-frame" within={vertical}
+ <space:Frame id="speech-frame" within={vertical.bounds}
left="0%" top="0%" right="100%" bottom="100%"/>
- <space:Frame id="column-frame" within={vertical}
+ <space:Frame id="column-frame" within={vertical.bounds}
left="0%" top="10%" right="26%" bottom="67.5%"/>
<space:Extent id="pitch-pov-extent" width="2688" height="2016"/>
@@ -154,46 +154,67 @@
<!-- These straight-edged cards occupy the same right-side stage as the
active Column item. They have no border, rounded mask or sustain motion. -->
- <space:AspectFrame id="pitch-pov-frame" within={vertical}
+ <space:AspectFrame id="pitch-pov-frame" within={vertical.bounds}
x="50%" y="72%" width="74%" aspect={pitch-pov-extent} anchor="center"/>
- <space:AspectFrame id="ikea-sign-frame" within={vertical}
+ <space:AspectFrame id="ikea-sign-frame" within={vertical.bounds}
x="75%" y="79%" width="50%" aspect={ikea-sign-extent} anchor="center"/>
- <space:AspectFrame id="retirement-room-frame" within={vertical}
+ <space:AspectFrame id="retirement-room-frame" within={vertical.bounds}
x="52%" y="75%" width="88%" aspect={retirement-room-extent} anchor="center"/>
- <space:AspectFrame id="rent-jump-frame" within={vertical}
+ <space:AspectFrame id="rent-jump-frame" within={vertical.bounds}
x="52%" y="75%" width="78%" aspect={rent-jump-extent} anchor="center"/>
- <space:AspectFrame id="nine-hundred-frame" within={vertical}
+ <space:AspectFrame id="nine-hundred-frame" within={vertical.bounds}
x="25%" y="72%" width="50%" aspect={nine-hundred-extent} anchor="center"/>
- <space:AspectFrame id="laboratory-body-frame" within={vertical}
+ <space:AspectFrame id="laboratory-body-frame" within={vertical.bounds}
x="50%" y="68%" width="46%" aspect={laboratory-body-extent} anchor="center"/>
- <space:AspectFrame id="museum-jawline-frame" within={vertical}
+ <space:AspectFrame id="museum-jawline-frame" within={vertical.bounds}
x="75%" y="78%" width="50%" aspect={museum-jawline-extent} anchor="center"/>
<pipeline:Normalize id="messi-media" source={messi-take.video}
video="primary-moving" audio="default" span-authority="video" clock={clock}/>
<pipeline:Normalize id="ronaldo-media" source={ronaldo-take.video}
video="primary-moving" audio="default" span-authority="video" clock={clock}/>
- <whisperx:SemanticTake id="messi-semantic" narrative={story}
- segment={story.segment.messi} media={messi-media.media} language="en"/>
- <whisperx:SemanticTake id="ronaldo-semantic" narrative={story}
- segment={story.segment.ronaldo} media={ronaldo-media.media} language="en"/>
+ <whisperx:Alignment id="messi-semantic" narrative={story}
+ segment={story.segment.messi} media={messi-media.media} domain={messi-media.domain} language="en"/>
+ <whisperx:Alignment id="ronaldo-semantic" narrative={story}
+ segment={story.segment.ronaldo} media={ronaldo-media.media} domain={ronaldo-media.domain} language="en"/>
- <time:Timeline id="speech" clock={clock}>
- <time:Take source={messi-semantic.take}/>
- <time:Take source={ronaldo-semantic.take}/>
+ <time:Timeline id="speech" clock={clock} end="ronaldo-semantic.end">
+ <time:Window id="messi-semantic" from="start" for={messi-media.extent}/>
+ <time:Window id="ronaldo-semantic" from="messi-semantic.end" for={ronaldo-media.extent}/>
</time:Timeline>
- <sound:Style id="speech-sound-style"/>
- <sound:Track id="speech-sound" timeline={speech.timeline}>
- <sound:Use style={speech-sound-style}/>
- </sound:Track>
- <performance:Style id="speech-picture-style" frame={speech-frame} appearance={recipes.media.performance}/>
- <performance:Track id="speech-picture" timeline={speech.timeline} canvas={vertical}>
- <performance:Use style={speech-picture-style} during="program"/>
- </performance:Track>
+
+ <semantic:Projection id="story-time" narrative={story} timeline={speech.timeline}>
+ <semantic:Map alignment={messi-semantic.alignment} domain={messi-media.domain} window={speech.messi-semantic}/>
+ <semantic:Map alignment={ronaldo-semantic.alignment} domain={ronaldo-media.domain} window={speech.ronaldo-semantic}/>
+ <semantic:Window id="segment-ronaldo" segment={story.segment.ronaldo}/>
+ <semantic:Window id="segment-messi" segment={story.segment.messi}/>
+ <semantic:Window id="selection-pitch-pov" selection={story.selection.pitch-pov}/>
+ <semantic:Window id="selection-ikea-sign" selection={story.selection.ikea-sign}/>
+ <semantic:Window id="selection-retirement-room" selection={story.selection.retirement-room}/>
+ <semantic:Window id="selection-rent-jump" selection={story.selection.rent-jump}/>
+ <semantic:Window id="selection-nine-hundred-goals" selection={story.selection.nine-hundred-goals}/>
+ <semantic:Window id="selection-laboratory-body" selection={story.selection.laboratory-body}/>
+ <semantic:Window id="selection-museum-jawline" selection={story.selection.museum-jawline}/>
+ </semantic:Projection>
+ <audio:Track id="speech-sound" timeline={speech.timeline}>
+ <audio:Clip id="messi-semantic-source" source={messi-media.media} during={speech.messi-semantic}/>
+ <audio:Clip id="ronaldo-semantic-source" source={ronaldo-media.media} during={speech.ronaldo-semantic}/>
+ </audio:Track>
+ <visual:Motion id="broll-motion">
+ <visual:Pose at="start" scale="0.7" opacity="0" easing="ease-out"/>
+ <visual:Pose at="6f" scale="1" opacity="1"/>
+ <visual:Pose at="end-4f" scale="1" opacity="1" easing="ease-in"/>
+ <visual:Pose at="end" scale="1" opacity="0"/>
+ </visual:Motion>
+
+ <visual:Track id="speech-picture" timeline={speech.timeline}>
+ <visual:Clip id="messi-semantic-source" media={messi-media.media} during={speech.messi-semantic} frame={speech-frame} z="0" fit="cover"/>
+ <visual:Clip id="ronaldo-semantic-source" media={ronaldo-media.media} during={speech.ronaldo-semantic} frame={speech-frame} z="0" fit="cover"/>
+ </visual:Track>
<audio-track:Track id="music-bed" timeline={speech.timeline}>
- <audio-track:Item source={soundtrack-media.media} during="program"
- playback="once-start" gain="0.12" fade-in="300ms" fade-out="600ms"/>
+ <audio-track:Clip source={soundtrack-media.media} during="timeline"
+ gain="0.12" fade-in="300ms" fade-out="600ms"/>
</audio-track:Track>
<fonts:Stack id="display-font" family="montserrat" weight="900" style="normal"/>
@@ -201,11 +222,11 @@
<ranking:ColumnStyle id="column-style" recipe={recipes.ranking.football-column}
font={column-font}/>
<ranking:Column id="football-column" timeline={speech.timeline}
- canvas={vertical} frame={column-frame} during="program" style={column-style}
+ within={vertical.bounds} frame={column-frame} during="timeline" style={column-style}
appear-sound={ranking-appear-media.media}
move-sound={ranking-move-media.media}>
<ranking:ColumnItem id="ronaldo" rank="1" label="Ronaldo"
- icon={ronaldo-icon.image} during={story.segment.ronaldo}/>
+ icon={ronaldo-icon.image} during={story-time.segment-ronaldo}/>
<ranking:ColumnItem id="mbappe" rank="2" label="Mbappe"
preset="true" icon={mbappe-icon.image}/>
<ranking:ColumnItem id="haaland" rank="3" label="Haaland"
@@ -223,56 +244,57 @@
<ranking:ColumnItem id="neymar" rank="9" label="Neymar"
preset="true" icon={neymar-icon.image}/>
<ranking:ColumnItem id="messi" rank="10" label="Messi"
- icon={messi-icon.image} during={story.segment.messi}/>
+ icon={messi-icon.image} during={story-time.segment-messi}/>
</ranking:Column>
- <media-track:Track id="broll" timeline={speech.timeline} canvas={vertical}>
- <media-track:Item id="pitch-pov" image={broll-pitch-pov.image}
- extent={pitch-pov-extent} during={story.selection.pitch-pov}
- frame={pitch-pov-frame} appearance={recipes.media.pitch-pov}
- motion={recipes.motion.broll}/>
- <media-track:Item id="ikea-sign" image={broll-ikea-sign.image}
- extent={ikea-sign-extent} during={story.selection.ikea-sign}
- frame={ikea-sign-frame} appearance={recipes.media.ikea-sign}
- motion={recipes.motion.broll}/>
- <media-track:Item id="retirement-room" image={broll-retirement-room.image}
- extent={retirement-room-extent} during={story.selection.retirement-room}
- frame={retirement-room-frame} appearance={recipes.media.retirement-room}
- motion={recipes.motion.broll}/>
- <media-track:Item id="rent-jump" image={broll-rent-jump.image}
- extent={rent-jump-extent} during={story.selection.rent-jump}
- frame={rent-jump-frame} appearance={recipes.media.rent-jump}
- motion={recipes.motion.broll}/>
- <media-track:Item id="nine-hundred-goals" image={broll-nine-hundred.image}
- extent={nine-hundred-extent} during={story.selection.nine-hundred-goals}
- frame={nine-hundred-frame} appearance={recipes.media.nine-hundred}
- motion={recipes.motion.broll}/>
- <media-track:Item id="laboratory-body" image={broll-laboratory-body.image}
- extent={laboratory-body-extent} during={story.selection.laboratory-body}
- frame={laboratory-body-frame} appearance={recipes.media.laboratory-body}
- motion={recipes.motion.broll}/>
- <media-track:Item id="museum-jawline" image={broll-museum-jawline.image}
- extent={museum-jawline-extent} during={story.selection.museum-jawline}
- frame={museum-jawline-frame} appearance={recipes.media.museum-jawline}
- motion={recipes.motion.broll}/>
- </media-track:Track>
+ <visual:Track id="broll" timeline={speech.timeline}>
+ <visual:Clip id="pitch-pov" image={broll-pitch-pov.image}
+ extent={pitch-pov-extent} during={story-time.selection-pitch-pov}
+ frame={pitch-pov-frame} z="40" fit="cover" treatment={recipes.media.pitch-pov}
+ motion={broll-motion}/>
+ <visual:Clip id="ikea-sign" image={broll-ikea-sign.image}
+ extent={ikea-sign-extent} during={story-time.selection-ikea-sign}
+ frame={ikea-sign-frame} z="41" fit="cover" treatment={recipes.media.ikea-sign}
+ motion={broll-motion}/>
+ <visual:Clip id="retirement-room" image={broll-retirement-room.image}
+ extent={retirement-room-extent} during={story-time.selection-retirement-room}
+ frame={retirement-room-frame} z="42" fit="cover" treatment={recipes.media.retirement-room}
+ motion={broll-motion}/>
+ <visual:Clip id="rent-jump" image={broll-rent-jump.image}
+ extent={rent-jump-extent} during={story-time.selection-rent-jump}
+ frame={rent-jump-frame} z="43" fit="cover" treatment={recipes.media.rent-jump}
+ motion={broll-motion}/>
+ <visual:Clip id="nine-hundred-goals" image={broll-nine-hundred.image}
+ extent={nine-hundred-extent} during={story-time.selection-nine-hundred-goals}
+ frame={nine-hundred-frame} z="44" fit="cover" treatment={recipes.media.nine-hundred}
+ motion={broll-motion}/>
+ <visual:Clip id="laboratory-body" image={broll-laboratory-body.image}
+ extent={laboratory-body-extent} during={story-time.selection-laboratory-body}
+ frame={laboratory-body-frame} z="45" fit="cover" treatment={recipes.media.laboratory-body}
+ motion={broll-motion}/>
+ <visual:Clip id="museum-jawline" image={broll-museum-jawline.image}
+ extent={museum-jawline-extent} during={story-time.selection-museum-jawline}
+ frame={museum-jawline-frame} z="46" fit="cover" treatment={recipes.media.museum-jawline}
+ motion={broll-motion}/>
+ </visual:Track>
<caption-fine:Style id="caption-style" recipe={recipes.caption.primary}
font={display-font}/>
- <caption-fine:Track id="captions" document={story.caption}
- timeline={speech.timeline}>
+ <narrative-caption:Timing id="caption-timing" document={story.caption} binding={story.caption-binding} projection={story-time.projection}/>
+ <caption-fine:Caption id="captions" document={story.caption} timing={caption-timing}
+ timeline={speech.timeline} within={vertical.bounds}>
<caption-fine:Use style={caption-style}/>
- </caption-fine:Track>
+ </caption-fine:Caption>
- <film:Film id="main" canvas={vertical} timeline={speech.timeline}
+ <film:Film id="main" canvas={vertical.canvas} timeline={speech.timeline}
appearance={recipes.film.vertical}>
<film:Track source={speech-picture.visual}/>
<film:Track source={speech-sound.audio}/>
<film:Track source={football-column.visual}/>
<film:Track source={football-column.audio}/>
<film:Track source={broll.visual}/>
- <film:Track source={captions.track}/>
+ <film:Track source={captions.visual}/>
<film:Track source={music-bed.audio}/>
</film:Film>
<render:Video id="final" composition={main.composition}
diff --git a/examples/ranking-football/swap-effect.svml b/examples/ranking-football/swap-effect.svml
index 590c704d..d8e3c7ad 100644
--- a/examples/ranking-football/swap-effect.svml
+++ b/examples/ranking-football/swap-effect.svml
@@ -2,22 +2,22 @@
<svml>
<import from="@hypit/script@1"/>
- <import as="sound" from="@hypit/sound@1"/>
+ <import as="audio" from="@hypit/audio-track@1"/>
<import as="text" from="@hypit/text@1"/>
<import as="asset" from="@hypit/media@1"/>
<import as="gpt" from="@hypit/gpt-image@1"/>
<import as="seedance" from="@hypit/seedance@1"/>
<import as="pipeline" from="@hypit/media-pipeline@1"/>
<import as="whisperx" from="@hypit/whisperx@1"/>
+ <import as="semantic" from="@hypit/narrative-temporal@1"/>
+ <import as="narrative-caption" from="@hypit/narrative-caption@1"/>
<import as="time" from="@hypit/timeline-author@1"/>
- <import as="media-track" from="@hypit/media-track@1"/>
- <import as="performance" from="@hypit/performance@1"/>
+ <import as="visual" from="@hypit/visual-track@1"/>
<import as="audio-track" from="@hypit/audio-track@1"/>
<import as="caption" from="@hypit/caption@1"/>
<import as="caption-fine" from="@hypit/caption-fine@1"/>
<import as="fonts" from="@hypit/fonts-open@1"/>
<import as="space" from="@hypit/spatial@1"/>
- <import as="program" from="@hypit/program-space@1"/>
<import as="ranking" from="@hypit/ranking@1"/>
<import as="film" from="@hypit/film@1"/>
<import as="render" from="@hypit/render-hyperframes@1"/>
@@ -132,16 +132,16 @@
</seedance:ReferenceVideo>
<space:Canvas id="vertical" width="720" height="1280"/>
- <program:Clock id="clock" frame-rate="30"/>
+ <time:Clock id="clock" frame-rate="30"/>
<pipeline:Normalize id="soundtrack-media" source={soundtrack}
video="none" audio="default" span-authority="audio" clock={clock}/>
<pipeline:Normalize id="ranking-appear-media" source={ranking-appear-sfx}
video="none" audio="default" span-authority="audio" clock={clock}/>
<pipeline:Normalize id="ranking-move-media" source={ranking-move-sfx}
video="none" audio="default" span-authority="audio" clock={clock}/>
- <space:Frame id="speech-frame" within={vertical}
+ <space:Frame id="speech-frame" within={vertical.bounds}
left="0%" top="0%" right="100%" bottom="100%"/>
- <space:Frame id="column-frame" within={vertical}
+ <space:Frame id="column-frame" within={vertical.bounds}
left="0%" top="10%" right="26%" bottom="67.5%"/>
<space:Extent id="pitch-pov-extent" width="2688" height="2016"/>
@@ -154,46 +154,67 @@
<!-- These straight-edged cards occupy the same right-side stage as the
active Column item. They have no border, rounded mask or sustain motion. -->
- <space:AspectFrame id="pitch-pov-frame" within={vertical}
+ <space:AspectFrame id="pitch-pov-frame" within={vertical.bounds}
x="50%" y="72%" width="74%" aspect={pitch-pov-extent} anchor="center"/>
- <space:AspectFrame id="ikea-sign-frame" within={vertical}
+ <space:AspectFrame id="ikea-sign-frame" within={vertical.bounds}
x="75%" y="79%" width="50%" aspect={ikea-sign-extent} anchor="center"/>
- <space:AspectFrame id="retirement-room-frame" within={vertical}
+ <space:AspectFrame id="retirement-room-frame" within={vertical.bounds}
x="52%" y="75%" width="88%" aspect={retirement-room-extent} anchor="center"/>
- <space:AspectFrame id="rent-jump-frame" within={vertical}
+ <space:AspectFrame id="rent-jump-frame" within={vertical.bounds}
x="52%" y="75%" width="78%" aspect={rent-jump-extent} anchor="center"/>
- <space:AspectFrame id="nine-hundred-frame" within={vertical}
+ <space:AspectFrame id="nine-hundred-frame" within={vertical.bounds}
x="25%" y="72%" width="50%" aspect={nine-hundred-extent} anchor="center"/>
- <space:AspectFrame id="laboratory-body-frame" within={vertical}
+ <space:AspectFrame id="laboratory-body-frame" within={vertical.bounds}
x="50%" y="68%" width="46%" aspect={laboratory-body-extent} anchor="center"/>
- <space:AspectFrame id="museum-jawline-frame" within={vertical}
+ <space:AspectFrame id="museum-jawline-frame" within={vertical.bounds}
x="75%" y="78%" width="50%" aspect={museum-jawline-extent} anchor="center"/>
<pipeline:Normalize id="messi-media" source={messi-take.video}
video="primary-moving" audio="default" span-authority="video" clock={clock}/>
<pipeline:Normalize id="ronaldo-media" source={ronaldo-take.video}
video="primary-moving" audio="default" span-authority="video" clock={clock}/>
- <whisperx:SemanticTake id="messi-semantic" narrative={story}
- segment={story.segment.messi} media={messi-media.media} language="en"/>
- <whisperx:SemanticTake id="ronaldo-semantic" narrative={story}
- segment={story.segment.ronaldo} media={ronaldo-media.media} language="en"/>
+ <whisperx:Alignment id="messi-semantic" narrative={story}
+ segment={story.segment.messi} media={messi-media.media} domain={messi-media.domain} language="en"/>
+ <whisperx:Alignment id="ronaldo-semantic" narrative={story}
+ segment={story.segment.ronaldo} media={ronaldo-media.media} domain={ronaldo-media.domain} language="en"/>
- <time:Timeline id="speech" clock={clock}>
- <time:Take source={messi-semantic.take}/>
- <time:Take source={ronaldo-semantic.take}/>
+ <time:Timeline id="speech" clock={clock} end="ronaldo-semantic.end">
+ <time:Window id="messi-semantic" from="start" for={messi-media.extent}/>
+ <time:Window id="ronaldo-semantic" from="messi-semantic.end" for={ronaldo-media.extent}/>
</time:Timeline>
- <sound:Style id="speech-sound-style"/>
- <sound:Track id="speech-sound" timeline={speech.timeline}>
- <sound:Use style={speech-sound-style}/>
- </sound:Track>
- <performance:Style id="speech-picture-style" frame={speech-frame} appearance={recipes.media.performance}/>
- <performance:Track id="speech-picture" timeline={speech.timeline} canvas={vertical}>
- <performance:Use style={speech-picture-style} during="program"/>
- </performance:Track>
+
+ <semantic:Projection id="story-time" narrative={story} timeline={speech.timeline}>
+ <semantic:Map alignment={messi-semantic.alignment} domain={messi-media.domain} window={speech.messi-semantic}/>
+ <semantic:Map alignment={ronaldo-semantic.alignment} domain={ronaldo-media.domain} window={speech.ronaldo-semantic}/>
+ <semantic:Window id="segment-ronaldo" segment={story.segment.ronaldo}/>
+ <semantic:Window id="segment-messi" segment={story.segment.messi}/>
+ <semantic:Window id="selection-pitch-pov" selection={story.selection.pitch-pov}/>
+ <semantic:Window id="selection-ikea-sign" selection={story.selection.ikea-sign}/>
+ <semantic:Window id="selection-retirement-room" selection={story.selection.retirement-room}/>
+ <semantic:Window id="selection-rent-jump" selection={story.selection.rent-jump}/>
+ <semantic:Window id="selection-nine-hundred-goals" selection={story.selection.nine-hundred-goals}/>
+ <semantic:Window id="selection-laboratory-body" selection={story.selection.laboratory-body}/>
+ <semantic:Window id="selection-museum-jawline" selection={story.selection.museum-jawline}/>
+ </semantic:Projection>
+ <audio:Track id="speech-sound" timeline={speech.timeline}>
+ <audio:Clip id="messi-semantic-source" source={messi-media.media} during={speech.messi-semantic}/>
+ <audio:Clip id="ronaldo-semantic-source" source={ronaldo-media.media} during={speech.ronaldo-semantic}/>
+ </audio:Track>
+ <visual:Motion id="broll-motion">
+ <visual:Pose at="start" scale="0.7" opacity="0" easing="ease-out"/>
+ <visual:Pose at="6f" scale="1" opacity="1"/>
+ <visual:Pose at="end-4f" scale="1" opacity="1" easing="ease-in"/>
+ <visual:Pose at="end" scale="1" opacity="0"/>
+ </visual:Motion>
+
+ <visual:Track id="speech-picture" timeline={speech.timeline}>
+ <visual:Clip id="messi-semantic-source" media={messi-media.media} during={speech.messi-semantic} frame={speech-frame} z="0" fit="cover"/>
+ <visual:Clip id="ronaldo-semantic-source" media={ronaldo-media.media} during={speech.ronaldo-semantic} frame={speech-frame} z="0" fit="cover"/>
+ </visual:Track>
<audio-track:Track id="music-bed" timeline={speech.timeline}>
- <audio-track:Item source={soundtrack-media.media} during="program"
- playback="once-start" gain="0.12" fade-in="300ms" fade-out="600ms"/>
+ <audio-track:Clip source={soundtrack-media.media} during="timeline"
+ gain="0.12" fade-in="300ms" fade-out="600ms"/>
</audio-track:Track>
<fonts:Stack id="display-font" family="montserrat" weight="900" style="normal"/>
@@ -201,11 +222,11 @@
<ranking:ColumnStyle id="column-style" recipe={recipes.ranking.football-column}
font={column-font}/>
<ranking:Column id="football-column" timeline={speech.timeline}
- canvas={vertical} frame={column-frame} during="program" style={column-style}
+ within={vertical.bounds} frame={column-frame} during="timeline" style={column-style}
appear-sound={ranking-appear-media.media}
move-sound={ranking-move-media.media}>
<ranking:ColumnItem id="ronaldo" rank="1" label="Ronaldo"
- icon={ronaldo-icon.image} during={story.segment.ronaldo}/>
+ icon={ronaldo-icon.image} during={story-time.segment-ronaldo}/>
<ranking:ColumnItem id="mbappe" rank="2" label="Mbappe"
preset="true" icon={mbappe-icon.image}/>
<ranking:ColumnItem id="haaland" rank="3" label="Haaland"
@@ -223,56 +244,57 @@
<ranking:ColumnItem id="neymar" rank="9" label="Neymar"
preset="true" icon={neymar-icon.image}/>
<ranking:ColumnItem id="messi" rank="10" label="Messi"
- icon={messi-icon.image} during={story.segment.messi}/>
+ icon={messi-icon.image} during={story-time.segment-messi}/>
</ranking:Column>
- <media-track:Track id="broll" timeline={speech.timeline} canvas={vertical}>
- <media-track:Item id="pitch-pov" image={broll-pitch-pov.image}
- extent={pitch-pov-extent} during={story.selection.pitch-pov}
- frame={pitch-pov-frame} appearance={recipes.media.pitch-pov}
- motion={recipes.motion.broll}/>
- <media-track:Item id="ikea-sign" image={broll-ikea-sign.image}
- extent={ikea-sign-extent} during={story.selection.ikea-sign}
- frame={ikea-sign-frame} appearance={recipes.media.ikea-sign}
- motion={recipes.motion.broll}/>
- <media-track:Item id="retirement-room" image={broll-retirement-room.image}
- extent={retirement-room-extent} during={story.selection.retirement-room}
- frame={retirement-room-frame} appearance={recipes.media.retirement-room}
- motion={recipes.motion.broll}/>
- <media-track:Item id="rent-jump" image={broll-rent-jump.image}
- extent={rent-jump-extent} during={story.selection.rent-jump}
- frame={rent-jump-frame} appearance={recipes.media.rent-jump}
- motion={recipes.motion.broll}/>
- <media-track:Item id="nine-hundred-goals" image={broll-nine-hundred.image}
- extent={nine-hundred-extent} during={story.selection.nine-hundred-goals}
- frame={nine-hundred-frame} appearance={recipes.media.nine-hundred}
- motion={recipes.motion.broll}/>
- <media-track:Item id="laboratory-body" image={broll-laboratory-body.image}
- extent={laboratory-body-extent} during={story.selection.laboratory-body}
- frame={laboratory-body-frame} appearance={recipes.media.laboratory-body}
- motion={recipes.motion.broll}/>
- <media-track:Item id="museum-jawline" image={broll-museum-jawline.image}
- extent={museum-jawline-extent} during={story.selection.museum-jawline}
- frame={museum-jawline-frame} appearance={recipes.media.museum-jawline}
- motion={recipes.motion.broll}/>
- </media-track:Track>
+ <visual:Track id="broll" timeline={speech.timeline}>
+ <visual:Clip id="pitch-pov" image={broll-pitch-pov.image}
+ extent={pitch-pov-extent} during={story-time.selection-pitch-pov}
+ frame={pitch-pov-frame} z="40" fit="cover" treatment={recipes.media.pitch-pov}
+ motion={broll-motion}/>
+ <visual:Clip id="ikea-sign" image={broll-ikea-sign.image}
+ extent={ikea-sign-extent} during={story-time.selection-ikea-sign}
+ frame={ikea-sign-frame} z="41" fit="cover" treatment={recipes.media.ikea-sign}
+ motion={broll-motion}/>
+ <visual:Clip id="retirement-room" image={broll-retirement-room.image}
+ extent={retirement-room-extent} during={story-time.selection-retirement-room}
+ frame={retirement-room-frame} z="42" fit="cover" treatment={recipes.media.retirement-room}
+ motion={broll-motion}/>
+ <visual:Clip id="rent-jump" image={broll-rent-jump.image}
+ extent={rent-jump-extent} during={story-time.selection-rent-jump}
+ frame={rent-jump-frame} z="43" fit="cover" treatment={recipes.media.rent-jump}
+ motion={broll-motion}/>
+ <visual:Clip id="nine-hundred-goals" image={broll-nine-hundred.image}
+ extent={nine-hundred-extent} during={story-time.selection-nine-hundred-goals}
+ frame={nine-hundred-frame} z="44" fit="cover" treatment={recipes.media.nine-hundred}
+ motion={broll-motion}/>
+ <visual:Clip id="laboratory-body" image={broll-laboratory-body.image}
+ extent={laboratory-body-extent} during={story-time.selection-laboratory-body}
+ frame={laboratory-body-frame} z="45" fit="cover" treatment={recipes.media.laboratory-body}
+ motion={broll-motion}/>
+ <visual:Clip id="museum-jawline" image={broll-museum-jawline.image}
+ extent={museum-jawline-extent} during={story-time.selection-museum-jawline}
+ frame={museum-jawline-frame} z="46" fit="cover" treatment={recipes.media.museum-jawline}
+ motion={broll-motion}/>
+ </visual:Track>
<caption-fine:Style id="caption-style" recipe={recipes.caption.primary}
font={display-font}/>
- <caption-fine:Track id="captions" document={story.caption}
- timeline={speech.timeline}>
+ <narrative-caption:Timing id="caption-timing" document={story.caption} binding={story.caption-binding} projection={story-time.projection}/>
+ <caption-fine:Caption id="captions" document={story.caption} timing={caption-timing}
+ timeline={speech.timeline} within={vertical.bounds}>
<caption-fine:Use style={caption-style}/>
- </caption-fine:Track>
+ </caption-fine:Caption>
- <film:Film id="main" canvas={vertical} timeline={speech.timeline}
+ <film:Film id="main" canvas={vertical.canvas} timeline={speech.timeline}
appearance={recipes.film.vertical}>
<film:Track source={speech-picture.visual}/>
<film:Track source={speech-sound.audio}/>
<film:Track source={football-column.visual}/>
<film:Track source={football-column.audio}/>
<film:Track source={broll.visual}/>
- <film:Track source={captions.track}/>
+ <film:Track source={captions.visual}/>
<film:Track source={music-bed.audio}/>
</film:Film>
<render:Video id="final" composition={main.composition}
diff --git a/examples/ranking-football/swap-host.svml b/examples/ranking-football/swap-host.svml
index db5afafb..6656e148 100644
--- a/examples/ranking-football/swap-host.svml
+++ b/examples/ranking-football/swap-host.svml
@@ -2,22 +2,22 @@
<svml>
<import from="@hypit/script@1"/>
- <import as="sound" from="@hypit/sound@1"/>
+ <import as="audio" from="@hypit/audio-track@1"/>
<import as="text" from="@hypit/text@1"/>
<import as="asset" from="@hypit/media@1"/>
<import as="gpt" from="@hypit/gpt-image@1"/>
<import as="seedance" from="@hypit/seedance@1"/>
<import as="pipeline" from="@hypit/media-pipeline@1"/>
<import as="whisperx" from="@hypit/whisperx@1"/>
+ <import as="semantic" from="@hypit/narrative-temporal@1"/>
+ <import as="narrative-caption" from="@hypit/narrative-caption@1"/>
<import as="time" from="@hypit/timeline-author@1"/>
- <import as="media-track" from="@hypit/media-track@1"/>
- <import as="performance" from="@hypit/performance@1"/>
+ <import as="visual" from="@hypit/visual-track@1"/>
<import as="audio-track" from="@hypit/audio-track@1"/>
<import as="caption" from="@hypit/caption@1"/>
<import as="caption-fine" from="@hypit/caption-fine@1"/>
<import as="fonts" from="@hypit/fonts-open@1"/>
<import as="space" from="@hypit/spatial@1"/>
- <import as="program" from="@hypit/program-space@1"/>
<import as="ranking" from="@hypit/ranking@1"/>
<import as="film" from="@hypit/film@1"/>
<import as="render" from="@hypit/render-hyperframes@1"/>
@@ -144,16 +144,16 @@
</seedance:ReferenceVideo>
<space:Canvas id="vertical" width="720" height="1280"/>
- <program:Clock id="clock" frame-rate="30"/>
+ <time:Clock id="clock" frame-rate="30"/>
<pipeline:Normalize id="soundtrack-media" source={soundtrack}
video="none" audio="default" span-authority="audio" clock={clock}/>
<pipeline:Normalize id="ranking-appear-media" source={ranking-appear-sfx}
video="none" audio="default" span-authority="audio" clock={clock}/>
<pipeline:Normalize id="ranking-move-media" source={ranking-move-sfx}
video="none" audio="default" span-authority="audio" clock={clock}/>
- <space:Frame id="speech-frame" within={vertical}
+ <space:Frame id="speech-frame" within={vertical.bounds}
left="0%" top="0%" right="100%" bottom="100%"/>
- <space:Frame id="tier-frame" within={vertical}
+ <space:Frame id="tier-frame" within={vertical.bounds}
left="0%" top="55%" right="100%" bottom="100%"/>
<!-- B-roll lives inside the lower board region. Deliberately varied card
@@ -168,21 +168,21 @@
<space:Extent id="walks-around-extent" width="2688" height="2016"/>
<space:Extent id="hat-trick-extent" width="2048" height="2048"/>
- <space:AspectFrame id="hair-gel-frame" within={vertical}
+ <space:AspectFrame id="hair-gel-frame" within={vertical.bounds}
x="34%" y="78%" width="58%" aspect={hair-gel-extent} anchor="center"/>
- <space:AspectFrame id="trophy-frame" within={vertical}
+ <space:AspectFrame id="trophy-frame" within={vertical.bounds}
x="73%" y="82%" width="42%" aspect={trophy-extent} anchor="center"/>
- <space:AspectFrame id="greek-god-frame" within={vertical}
+ <space:AspectFrame id="greek-god-frame" within={vertical.bounds}
x="24%" y="78%" width="38%" aspect={greek-god-extent} anchor="center"/>
- <space:AspectFrame id="greek-tragedy-frame" within={vertical}
+ <space:AspectFrame id="greek-tragedy-frame" within={vertical.bounds}
x="63%" y="79%" width="66%" aspect={greek-tragedy-extent} anchor="center"/>
- <space:AspectFrame id="penaldo-social-frame" within={vertical}
+ <space:AspectFrame id="penaldo-social-frame" within={vertical.bounds}
x="50%" y="78%" width="94%" aspect={penaldo-social-extent} anchor="center"/>
- <space:AspectFrame id="tired-dad-frame" within={vertical}
+ <space:AspectFrame id="tired-dad-frame" within={vertical.bounds}
x="58%" y="79%" width="62%" aspect={tired-dad-extent} anchor="center"/>
- <space:AspectFrame id="walks-around-frame" within={vertical}
+ <space:AspectFrame id="walks-around-frame" within={vertical.bounds}
x="38%" y="79%" width="68%" aspect={walks-around-extent} anchor="center"/>
- <space:AspectFrame id="hat-trick-frame" within={vertical}
+ <space:AspectFrame id="hat-trick-frame" within={vertical.bounds}
x="72%" y="80%" width="46%" aspect={hat-trick-extent} anchor="center"/>
<!-- Real Build path: generated video -> one shared normalization waist ->
@@ -191,27 +191,61 @@
video="primary-moving" audio="default" span-authority="video" clock={clock}/>
<pipeline:Normalize id="messi-media" source={messi-take.video}
video="primary-moving" audio="default" span-authority="video" clock={clock}/>
- <whisperx:SemanticTake id="ronaldo-semantic" narrative={story}
- segment={story.segment.ronaldo} media={ronaldo-media.media} language="en"/>
- <whisperx:SemanticTake id="messi-semantic" narrative={story}
- segment={story.segment.messi} media={messi-media.media} language="en"/>
+ <whisperx:Alignment id="ronaldo-semantic" narrative={story}
+ segment={story.segment.ronaldo} media={ronaldo-media.media} domain={ronaldo-media.domain} language="en"/>
+ <whisperx:Alignment id="messi-semantic" narrative={story}
+ segment={story.segment.messi} media={messi-media.media} domain={messi-media.domain} language="en"/>
- <time:Timeline id="speech" clock={clock}>
- <time:Take source={ronaldo-semantic.take}/>
- <time:Take source={messi-semantic.take}/>
+ <time:Timeline id="speech" clock={clock} end="messi-semantic.end">
+ <time:Window id="ronaldo-semantic" from="start" for={ronaldo-media.extent}/>
+ <time:Window id="messi-semantic" from="ronaldo-semantic.end" for={messi-media.extent}/>
</time:Timeline>
- <sound:Style id="speech-sound-style"/>
- <sound:Track id="speech-sound" timeline={speech.timeline}>
- <sound:Use style={speech-sound-style}/>
- </sound:Track>
- <performance:Style id="speech-picture-style" frame={speech-frame} appearance={recipes.media.performance}/>
- <performance:Track id="speech-picture" timeline={speech.timeline} canvas={vertical}>
- <performance:Use style={speech-picture-style} during="program"/>
- </performance:Track>
+
+ <semantic:Projection id="story-time" narrative={story} timeline={speech.timeline}>
+ <semantic:Map alignment={ronaldo-semantic.alignment} domain={ronaldo-media.domain} window={speech.ronaldo-semantic}/>
+ <semantic:Map alignment={messi-semantic.alignment} domain={messi-media.domain} window={speech.messi-semantic}/>
+ <semantic:Window id="segment-ronaldo" segment={story.segment.ronaldo}/>
+ <semantic:Window id="segment-messi" segment={story.segment.messi}/>
+ <semantic:Window id="selection-hair-gel" selection={story.selection.hair-gel}/>
+ <semantic:Window id="selection-trophy" selection={story.selection.trophy}/>
+ <semantic:Window id="selection-greek-god" selection={story.selection.greek-god}/>
+ <semantic:Window id="selection-greek-tragedy" selection={story.selection.greek-tragedy}/>
+ <semantic:Window id="selection-penaldo-social" selection={story.selection.penaldo-social}/>
+ <semantic:Window id="selection-tired-dad" selection={story.selection.tired-dad}/>
+ <semantic:Window id="selection-walks-around" selection={story.selection.walks-around}/>
+ <semantic:Window id="selection-hat-trick" selection={story.selection.hat-trick}/>
+ </semantic:Projection>
+ <audio:Track id="speech-sound" timeline={speech.timeline}>
+ <audio:Clip id="ronaldo-semantic-source" source={ronaldo-media.media} during={speech.ronaldo-semantic}/>
+ <audio:Clip id="messi-semantic-source" source={messi-media.media} during={speech.messi-semantic}/>
+ </audio:Track>
+ <visual:Motion id="broll-left">
+ <visual:Pose at="start" scale="0.7" opacity="0" easing="ease-out"/>
+ <visual:Pose at="6f" scale="1" opacity="1"/>
+ <visual:Pose at="end-4f" scale="1" opacity="1" easing="ease-in"/>
+ <visual:Pose at="end" scale="1" opacity="0"/>
+ </visual:Motion>
+ <visual:Motion id="broll-right">
+ <visual:Pose at="start" y="80" scale="0.92" opacity="0" easing="ease-out"/>
+ <visual:Pose at="7f" y="0" scale="1" opacity="1"/>
+ <visual:Pose at="end-4f" y="0" scale="1" opacity="1" easing="ease-in"/>
+ <visual:Pose at="end" y="0" scale="0.94" opacity="1"/>
+ </visual:Motion>
+ <visual:Motion id="broll-wide">
+ <visual:Pose at="start" scale="0.9" opacity="1" easing="ease-out"/>
+ <visual:Pose at="6f" scale="1" opacity="1"/>
+ <visual:Pose at="end-4f" scale="1" opacity="1" easing="ease-in"/>
+ <visual:Pose at="end" scale="1" opacity="0"/>
+ </visual:Motion>
+
+ <visual:Track id="speech-picture" timeline={speech.timeline}>
+ <visual:Clip id="ronaldo-semantic-source" media={ronaldo-media.media} during={speech.ronaldo-semantic} frame={speech-frame} z="0" fit="cover"/>
+ <visual:Clip id="messi-semantic-source" media={messi-media.media} during={speech.messi-semantic} frame={speech-frame} z="0" fit="cover"/>
+ </visual:Track>
<audio-track:Track id="music-bed" timeline={speech.timeline}>
- <audio-track:Item source={soundtrack-media.media} during="program"
- playback="once-start" gain="0.12" fade-in="300ms" fade-out="600ms"/>
+ <audio-track:Clip source={soundtrack-media.media} during="timeline"
+ gain="0.12" fade-in="300ms" fade-out="600ms"/>
</audio-track:Track>
<fonts:Stack id="display-font" family="montserrat" weight="900" style="normal"/>
@@ -219,8 +253,8 @@
<ranking:TierBoardStyle id="tier-style" recipe={recipes.ranking.football}
font={tier-font}/>
<ranking:TierBoard id="football-tiers" timeline={speech.timeline}
- canvas={vertical} frame={tier-frame}
- during="program" style={tier-style}
+ within={vertical.bounds} frame={tier-frame}
+ during="timeline" style={tier-style}
appear-sound={ranking-appear-media.media}
move-sound={ranking-move-media.media}>
<ranking:TierItem id="yamal" tier="s" preset="true" icon={yamal-icon.image}/>
@@ -233,64 +267,65 @@
<ranking:TierItem id="neymar" tier="d" preset="true" icon={neymar-icon.image}/>
<ranking:TierItem id="benzema" tier="d" preset="true" icon={benzema-icon.image}/>
<ranking:TierItem id="ronaldo" tier="d" entry="drop"
- icon={ronaldo-icon.image} during={story.segment.ronaldo}/>
+ icon={ronaldo-icon.image} during={story-time.segment-ronaldo}/>
<ranking:TierItem id="messi" tier="s" entry="drop"
- icon={messi-icon.image} during={story.segment.messi}/>
+ icon={messi-icon.image} during={story-time.segment-messi}/>
</ranking:TierBoard>
<!-- Every Item consumes a projected Selection window. Later overlapping
- jokes use a higher stack order through their appearance Recipe. -->
- <media-track:Track id="broll" timeline={speech.timeline} canvas={vertical}>
- <media-track:Item id="hair-gel" image={broll-hair-gel.image}
- extent={hair-gel-extent} during={story.selection.hair-gel}
- frame={hair-gel-frame} appearance={recipes.media.hair-gel}
- motion={recipes.motion.broll-left}/>
- <media-track:Item id="trophy" image={broll-trophy.image}
- extent={trophy-extent} during={story.selection.trophy}
- frame={trophy-frame} appearance={recipes.media.trophy}
- motion={recipes.motion.broll-right}/>
- <media-track:Item id="greek-god" image={broll-greek-god.image}
- extent={greek-god-extent} during={story.selection.greek-god}
- frame={greek-god-frame} appearance={recipes.media.greek-god}
- motion={recipes.motion.broll-left}/>
- <media-track:Item id="greek-tragedy" image={broll-greek-tragedy.image}
- extent={greek-tragedy-extent} during={story.selection.greek-tragedy}
- frame={greek-tragedy-frame} appearance={recipes.media.greek-tragedy}
- motion={recipes.motion.broll-right}/>
- <media-track:Item id="penaldo-social" image={broll-penaldo-social.image}
- extent={penaldo-social-extent} during={story.selection.penaldo-social}
- frame={penaldo-social-frame} appearance={recipes.media.penaldo-social}
- motion={recipes.motion.broll-wide}/>
- <media-track:Item id="tired-dad" image={broll-tired-dad-trophy.image}
- extent={tired-dad-extent} during={story.selection.tired-dad}
- frame={tired-dad-frame} appearance={recipes.media.tired-dad}
- motion={recipes.motion.broll-right}/>
- <media-track:Item id="walks-around" image={broll-walks-around.image}
- extent={walks-around-extent} during={story.selection.walks-around}
- frame={walks-around-frame} appearance={recipes.media.walks-around}
- motion={recipes.motion.broll-left}/>
- <media-track:Item id="hat-trick" image={broll-hat-trick.image}
- extent={hat-trick-extent} during={story.selection.hat-trick}
- frame={hat-trick-frame} appearance={recipes.media.hat-trick}
- motion={recipes.motion.broll-right}/>
- </media-track:Track>
+ jokes use a higher explicit z on their own Clip occurrence. -->
+ <visual:Track id="broll" timeline={speech.timeline}>
+ <visual:Clip id="hair-gel" image={broll-hair-gel.image}
+ extent={hair-gel-extent} during={story-time.selection-hair-gel}
+ frame={hair-gel-frame} z="40" fit="cover" treatment={recipes.media.hair-gel}
+ motion={broll-left}/>
+ <visual:Clip id="trophy" image={broll-trophy.image}
+ extent={trophy-extent} during={story-time.selection-trophy}
+ frame={trophy-frame} z="41" fit="cover" treatment={recipes.media.trophy}
+ motion={broll-right}/>
+ <visual:Clip id="greek-god" image={broll-greek-god.image}
+ extent={greek-god-extent} during={story-time.selection-greek-god}
+ frame={greek-god-frame} z="42" fit="cover" treatment={recipes.media.greek-god}
+ motion={broll-left}/>
+ <visual:Clip id="greek-tragedy" image={broll-greek-tragedy.image}
+ extent={greek-tragedy-extent} during={story-time.selection-greek-tragedy}
+ frame={greek-tragedy-frame} z="43" fit="cover" treatment={recipes.media.greek-tragedy}
+ motion={broll-right}/>
+ <visual:Clip id="penaldo-social" image={broll-penaldo-social.image}
+ extent={penaldo-social-extent} during={story-time.selection-penaldo-social}
+ frame={penaldo-social-frame} z="44" fit="cover" treatment={recipes.media.penaldo-social}
+ motion={broll-wide}/>
+ <visual:Clip id="tired-dad" image={broll-tired-dad-trophy.image}
+ extent={tired-dad-extent} during={story-time.selection-tired-dad}
+ frame={tired-dad-frame} z="45" fit="cover" treatment={recipes.media.tired-dad}
+ motion={broll-right}/>
+ <visual:Clip id="walks-around" image={broll-walks-around.image}
+ extent={walks-around-extent} during={story-time.selection-walks-around}
+ frame={walks-around-frame} z="46" fit="cover" treatment={recipes.media.walks-around}
+ motion={broll-left}/>
+ <visual:Clip id="hat-trick" image={broll-hat-trick.image}
+ extent={hat-trick-extent} during={story-time.selection-hat-trick}
+ frame={hat-trick-frame} z="47" fit="cover" treatment={recipes.media.hat-trick}
+ motion={broll-right}/>
+ </visual:Track>
<caption-fine:Style id="caption-style" recipe={recipes.caption.primary}
font={display-font}/>
- <caption-fine:Track id="captions" document={story.caption}
- timeline={speech.timeline}>
+ <narrative-caption:Timing id="caption-timing" document={story.caption} binding={story.caption-binding} projection={story-time.projection}/>
+ <caption-fine:Caption id="captions" document={story.caption} timing={caption-timing}
+ timeline={speech.timeline} within={vertical.bounds}>
<caption-fine:Use style={caption-style}/>
- </caption-fine:Track>
+ </caption-fine:Caption>
- <film:Film id="main" canvas={vertical} timeline={speech.timeline}
+ <film:Film id="main" canvas={vertical.canvas} timeline={speech.timeline}
appearance={recipes.film.vertical}>
<film:Track source={speech-picture.visual}/>
<film:Track source={speech-sound.audio}/>
<film:Track source={football-tiers.visual}/>
<film:Track source={football-tiers.audio}/>
<film:Track source={broll.visual}/>
- <film:Track source={captions.track}/>
+ <film:Track source={captions.visual}/>
<film:Track source={music-bed.audio}/>
</film:Film>
<render:Video id="final" composition={main.composition}
diff --git a/examples/ranking-football/swap-topic.svml b/examples/ranking-football/swap-topic.svml
index abcea8ed..953e2bf2 100644
--- a/examples/ranking-football/swap-topic.svml
+++ b/examples/ranking-football/swap-topic.svml
@@ -2,22 +2,22 @@
<svml>
<import from="@hypit/script@1"/>
- <import as="sound" from="@hypit/sound@1"/>
+ <import as="audio" from="@hypit/audio-track@1"/>
<import as="text" from="@hypit/text@1"/>
<import as="asset" from="@hypit/media@1"/>
<import as="gpt" from="@hypit/gpt-image@1"/>
<import as="seedance" from="@hypit/seedance@1"/>
<import as="pipeline" from="@hypit/media-pipeline@1"/>
<import as="whisperx" from="@hypit/whisperx@1"/>
+ <import as="semantic" from="@hypit/narrative-temporal@1"/>
+ <import as="narrative-caption" from="@hypit/narrative-caption@1"/>
<import as="time" from="@hypit/timeline-author@1"/>
- <import as="media-track" from="@hypit/media-track@1"/>
- <import as="performance" from="@hypit/performance@1"/>
+ <import as="visual" from="@hypit/visual-track@1"/>
<import as="audio-track" from="@hypit/audio-track@1"/>
<import as="caption" from="@hypit/caption@1"/>
<import as="caption-fine" from="@hypit/caption-fine@1"/>
<import as="fonts" from="@hypit/fonts-open@1"/>
<import as="space" from="@hypit/spatial@1"/>
- <import as="program" from="@hypit/program-space@1"/>
<import as="ranking" from="@hypit/ranking@1"/>
<import as="film" from="@hypit/film@1"/>
<import as="render" from="@hypit/render-hyperframes@1"/>
@@ -159,16 +159,16 @@
</seedance:ReferenceVideo>
<space:Canvas id="vertical" width="720" height="1280"/>
- <program:Clock id="clock" frame-rate="30"/>
+ <time:Clock id="clock" frame-rate="30"/>
<pipeline:Normalize id="soundtrack-media" source={soundtrack}
video="none" audio="default" span-authority="audio" clock={clock}/>
<pipeline:Normalize id="ranking-appear-media" source={ranking-appear-sfx}
video="none" audio="default" span-authority="audio" clock={clock}/>
<pipeline:Normalize id="ranking-move-media" source={ranking-move-sfx}
video="none" audio="default" span-authority="audio" clock={clock}/>
- <space:Frame id="speech-frame" within={vertical}
+ <space:Frame id="speech-frame" within={vertical.bounds}
left="0%" top="0%" right="100%" bottom="100%"/>
- <space:Frame id="tier-frame" within={vertical}
+ <space:Frame id="tier-frame" within={vertical.bounds}
left="0%" top="55%" right="100%" bottom="100%"/>
<space:Extent id="money-rain-extent" width="2048" height="2048"/>
@@ -185,58 +185,97 @@
<space:Extent id="congress-grilled-extent" width="2048" height="2048"/>
<space:Extent id="still-here-extent" width="2688" height="2016"/>
- <space:AspectFrame id="money-rain-frame" within={vertical}
+ <space:AspectFrame id="money-rain-frame" within={vertical.bounds}
x="30%" y="82%" width="58%" aspect={money-rain-extent} anchor="center"/>
- <space:AspectFrame id="twitter-x-frame" within={vertical}
+ <space:AspectFrame id="twitter-x-frame" within={vertical.bounds}
x="66%" y="82%" width="68%" aspect={twitter-x-extent} anchor="center"/>
- <space:AspectFrame id="mars-rocket-frame" within={vertical}
+ <space:AspectFrame id="mars-rocket-frame" within={vertical.bounds}
x="24%" y="81%" width="42%" aspect={mars-rocket-extent} anchor="center"/>
- <space:AspectFrame id="market-crash-frame" within={vertical}
+ <space:AspectFrame id="market-crash-frame" within={vertical.bounds}
x="62%" y="82%" width="84%" aspect={market-crash-extent} anchor="center"/>
- <space:AspectFrame id="richest-chair-frame" within={vertical}
+ <space:AspectFrame id="richest-chair-frame" within={vertical.bounds}
x="30%" y="82%" width="58%" aspect={richest-chair-extent} anchor="center"/>
- <space:AspectFrame id="haircut-x-frame" within={vertical}
+ <space:AspectFrame id="haircut-x-frame" within={vertical.bounds}
x="66%" y="82%" width="68%" aspect={haircut-x-extent} anchor="center"/>
- <space:AspectFrame id="fired-friday-frame" within={vertical}
+ <space:AspectFrame id="fired-friday-frame" within={vertical.bounds}
x="24%" y="81%" width="42%" aspect={fired-friday-extent} anchor="center"/>
- <space:AspectFrame id="company-quit-frame" within={vertical}
+ <space:AspectFrame id="company-quit-frame" within={vertical.bounds}
x="76%" y="83%" width="52%" aspect={company-quit-extent} anchor="center"/>
- <space:AspectFrame id="back-monday-frame" within={vertical}
+ <space:AspectFrame id="back-monday-frame" within={vertical.bounds}
x="52%" y="82%" width="72%" aspect={back-monday-extent} anchor="center"/>
- <space:AspectFrame id="elon-lawsuit-frame" within={vertical}
+ <space:AspectFrame id="elon-lawsuit-frame" within={vertical.bounds}
x="27%" y="84%" width="42%" aspect={elon-lawsuit-extent} anchor="center"/>
- <space:AspectFrame id="google-fears-frame" within={vertical}
+ <space:AspectFrame id="google-fears-frame" within={vertical.bounds}
x="50%" y="84%" width="42%" aspect={google-fears-extent} anchor="center"/>
- <space:AspectFrame id="congress-grilled-frame" within={vertical}
+ <space:AspectFrame id="congress-grilled-frame" within={vertical.bounds}
x="73%" y="84%" width="42%" aspect={congress-grilled-extent} anchor="center"/>
- <space:AspectFrame id="still-here-frame" within={vertical}
+ <space:AspectFrame id="still-here-frame" within={vertical.bounds}
x="50%" y="70%" width="64%" aspect={still-here-extent} anchor="center"/>
<pipeline:Normalize id="elon-media" source={elon-take.video}
video="primary-moving" audio="default" span-authority="video" clock={clock}/>
<pipeline:Normalize id="sam-media" source={sam-take.video}
video="primary-moving" audio="default" span-authority="video" clock={clock}/>
- <whisperx:SemanticTake id="elon-semantic" narrative={story}
- segment={story.segment.elon} media={elon-media.media} language="en"/>
- <whisperx:SemanticTake id="sam-semantic" narrative={story}
- segment={story.segment.sam} media={sam-media.media} language="en"/>
+ <whisperx:Alignment id="elon-semantic" narrative={story}
+ segment={story.segment.elon} media={elon-media.media} domain={elon-media.domain} language="en"/>
+ <whisperx:Alignment id="sam-semantic" narrative={story}
+ segment={story.segment.sam} media={sam-media.media} domain={sam-media.domain} language="en"/>
- <time:Timeline id="speech" clock={clock}>
- <time:Take source={elon-semantic.take}/>
- <time:Take source={sam-semantic.take}/>
+ <time:Timeline id="speech" clock={clock} end="sam-semantic.end">
+ <time:Window id="elon-semantic" from="start" for={elon-media.extent}/>
+ <time:Window id="sam-semantic" from="elon-semantic.end" for={sam-media.extent}/>
</time:Timeline>
- <sound:Style id="speech-sound-style"/>
- <sound:Track id="speech-sound" timeline={speech.timeline}>
- <sound:Use style={speech-sound-style}/>
- </sound:Track>
- <performance:Style id="speech-picture-style" frame={speech-frame} appearance={recipes.media.performance}/>
- <performance:Track id="speech-picture" timeline={speech.timeline} canvas={vertical}>
- <performance:Use style={speech-picture-style} during="program"/>
- </performance:Track>
+
+ <semantic:Projection id="story-time" narrative={story} timeline={speech.timeline}>
+ <semantic:Map alignment={elon-semantic.alignment} domain={elon-media.domain} window={speech.elon-semantic}/>
+ <semantic:Map alignment={sam-semantic.alignment} domain={sam-media.domain} window={speech.sam-semantic}/>
+ <semantic:Window id="segment-elon" segment={story.segment.elon}/>
+ <semantic:Window id="segment-sam" segment={story.segment.sam}/>
+ <semantic:Window id="selection-money-rain" selection={story.selection.money-rain}/>
+ <semantic:Window id="selection-twitter-x" selection={story.selection.twitter-x}/>
+ <semantic:Window id="selection-mars-rocket" selection={story.selection.mars-rocket}/>
+ <semantic:Window id="selection-market-crash" selection={story.selection.market-crash}/>
+ <semantic:Window id="selection-richest-chair" selection={story.selection.richest-chair}/>
+ <semantic:Window id="selection-haircut-x" selection={story.selection.haircut-x}/>
+ <semantic:Window id="selection-fired-friday" selection={story.selection.fired-friday}/>
+ <semantic:Window id="selection-company-quit" selection={story.selection.company-quit}/>
+ <semantic:Window id="selection-back-monday" selection={story.selection.back-monday}/>
+ <semantic:Window id="selection-elon-lawsuit" selection={story.selection.elon-lawsuit}/>
+ <semantic:Window id="selection-google-fears" selection={story.selection.google-fears}/>
+ <semantic:Window id="selection-congress-grilled" selection={story.selection.congress-grilled}/>
+ <semantic:Window id="selection-still-here" selection={story.selection.still-here}/>
+ </semantic:Projection>
+ <audio:Track id="speech-sound" timeline={speech.timeline}>
+ <audio:Clip id="elon-semantic-source" source={elon-media.media} during={speech.elon-semantic}/>
+ <audio:Clip id="sam-semantic-source" source={sam-media.media} during={speech.sam-semantic}/>
+ </audio:Track>
+ <visual:Motion id="broll-left">
+ <visual:Pose at="start" scale="0.7" opacity="0" easing="ease-out"/>
+ <visual:Pose at="6f" scale="1" opacity="1"/>
+ <visual:Pose at="end-4f" scale="1" opacity="1" easing="ease-in"/>
+ <visual:Pose at="end" scale="1" opacity="0"/>
+ </visual:Motion>
+ <visual:Motion id="broll-right">
+ <visual:Pose at="start" y="80" scale="0.92" opacity="0" easing="ease-out"/>
+ <visual:Pose at="7f" y="0" scale="1" opacity="1"/>
+ <visual:Pose at="end-4f" y="0" scale="1" opacity="1" easing="ease-in"/>
+ <visual:Pose at="end" y="0" scale="0.94" opacity="1"/>
+ </visual:Motion>
+ <visual:Motion id="broll-wide">
+ <visual:Pose at="start" scale="0.9" opacity="1" easing="ease-out"/>
+ <visual:Pose at="6f" scale="1" opacity="1"/>
+ <visual:Pose at="end-4f" scale="1" opacity="1" easing="ease-in"/>
+ <visual:Pose at="end" scale="1" opacity="0"/>
+ </visual:Motion>
+
+ <visual:Track id="speech-picture" timeline={speech.timeline}>
+ <visual:Clip id="elon-semantic-source" media={elon-media.media} during={speech.elon-semantic} frame={speech-frame} z="0" fit="cover"/>
+ <visual:Clip id="sam-semantic-source" media={sam-media.media} during={speech.sam-semantic} frame={speech-frame} z="0" fit="cover"/>
+ </visual:Track>
<audio-track:Track id="music-bed" timeline={speech.timeline}>
- <audio-track:Item source={soundtrack-media.media} during="program"
- playback="once-start" gain="0.12" fade-in="300ms" fade-out="600ms"/>
+ <audio-track:Clip source={soundtrack-media.media} during="timeline"
+ gain="0.12" fade-in="300ms" fade-out="600ms"/>
</audio-track:Track>
<fonts:Stack id="display-font" family="montserrat" weight="900" style="normal"/>
@@ -244,8 +283,8 @@
<ranking:TierBoardStyle id="tier-style" recipe={recipes.ranking.tech}
font={tier-font}/>
<ranking:TierBoard id="tech-tiers" timeline={speech.timeline}
- canvas={vertical} frame={tier-frame}
- during="program" style={tier-style}
+ within={vertical.bounds} frame={tier-frame}
+ during="timeline" style={tier-style}
appear-sound={ranking-appear-media.media}
move-sound={ranking-move-media.media}>
<ranking:TierItem id="jensen" tier="s" preset="true" icon={jensen-icon.image}/>
@@ -256,82 +295,83 @@
<ranking:TierItem id="tim" tier="c" preset="true" icon={tim-icon.image}/>
<ranking:TierItem id="mark" tier="d" preset="true" icon={mark-icon.image}/>
<ranking:TierItem id="elon" tier="d" entry="drop"
- icon={elon-icon.image} during={story.segment.elon}/>
+ icon={elon-icon.image} during={story-time.segment-elon}/>
<ranking:TierItem id="sam" tier="s" entry="drop"
- icon={sam-icon.image} during={story.segment.sam}/>
+ icon={sam-icon.image} during={story-time.segment-sam}/>
</ranking:TierBoard>
- <media-track:Track id="broll" timeline={speech.timeline} canvas={vertical}>
- <media-track:Item id="money-rain" image={broll-money-rain.image}
- extent={money-rain-extent} during={story.selection.money-rain}
- frame={money-rain-frame} appearance={recipes.media.money-rain}
- motion={recipes.motion.broll-left}/>
- <media-track:Item id="twitter-x" image={broll-twitter-x.image}
- extent={twitter-x-extent} during={story.selection.twitter-x}
- frame={twitter-x-frame} appearance={recipes.media.twitter-x}
- motion={recipes.motion.broll-right}/>
- <media-track:Item id="mars-rocket" image={broll-mars-rocket.image}
- extent={mars-rocket-extent} during={story.selection.mars-rocket}
- frame={mars-rocket-frame} appearance={recipes.media.mars-rocket}
- motion={recipes.motion.broll-left}/>
- <media-track:Item id="market-crash" image={broll-market-crash.image}
- extent={market-crash-extent} during={story.selection.market-crash}
- frame={market-crash-frame} appearance={recipes.media.market-crash}
- motion={recipes.motion.broll-wide}/>
- <media-track:Item id="richest-chair" image={broll-richest-chair.image}
- extent={richest-chair-extent} during={story.selection.richest-chair}
- frame={richest-chair-frame} appearance={recipes.media.richest-chair}
- motion={recipes.motion.broll-right}/>
- <media-track:Item id="haircut-x" image={broll-haircut-x.image}
- extent={haircut-x-extent} during={story.selection.haircut-x}
- frame={haircut-x-frame} appearance={recipes.media.haircut-x}
- motion={recipes.motion.broll-wide}/>
- <media-track:Item id="fired-friday" image={broll-fired-friday.image}
- extent={fired-friday-extent} during={story.selection.fired-friday}
- frame={fired-friday-frame} appearance={recipes.media.fired-friday}
- motion={recipes.motion.broll-left}/>
- <media-track:Item id="company-quit" image={broll-company-quit.image}
- extent={company-quit-extent} during={story.selection.company-quit}
- frame={company-quit-frame} appearance={recipes.media.company-quit}
- motion={recipes.motion.broll-right}/>
- <media-track:Item id="back-monday" image={broll-back-monday.image}
- extent={back-monday-extent} during={story.selection.back-monday}
- frame={back-monday-frame} appearance={recipes.media.back-monday}
- motion={recipes.motion.broll-wide}/>
- <media-track:Item id="elon-lawsuit" image={broll-elon-lawsuit.image}
- extent={elon-lawsuit-extent} during={story.selection.elon-lawsuit}
- frame={elon-lawsuit-frame} appearance={recipes.media.elon-lawsuit}
- motion={recipes.motion.broll-left}/>
- <media-track:Item id="google-fears" image={broll-google-fears.image}
- extent={google-fears-extent} during={story.selection.google-fears}
- frame={google-fears-frame} appearance={recipes.media.google-fears}
- motion={recipes.motion.broll-right}/>
- <media-track:Item id="congress-grilled" image={broll-congress-grilled.image}
- extent={congress-grilled-extent} during={story.selection.congress-grilled}
- frame={congress-grilled-frame} appearance={recipes.media.congress-grilled}
- motion={recipes.motion.broll-left}/>
- <media-track:Item id="still-here" image={broll-still-here.image}
- extent={still-here-extent} during={story.selection.still-here}
- frame={still-here-frame} appearance={recipes.media.still-here}
- motion={recipes.motion.broll-wide}/>
- </media-track:Track>
+ <visual:Track id="broll" timeline={speech.timeline}>
+ <visual:Clip id="money-rain" image={broll-money-rain.image}
+ extent={money-rain-extent} during={story-time.selection-money-rain}
+ frame={money-rain-frame} z="40" fit="cover" treatment={recipes.media.money-rain}
+ motion={broll-left}/>
+ <visual:Clip id="twitter-x" image={broll-twitter-x.image}
+ extent={twitter-x-extent} during={story-time.selection-twitter-x}
+ frame={twitter-x-frame} z="41" fit="cover" treatment={recipes.media.twitter-x}
+ motion={broll-right}/>
+ <visual:Clip id="mars-rocket" image={broll-mars-rocket.image}
+ extent={mars-rocket-extent} during={story-time.selection-mars-rocket}
+ frame={mars-rocket-frame} z="42" fit="cover" treatment={recipes.media.mars-rocket}
+ motion={broll-left}/>
+ <visual:Clip id="market-crash" image={broll-market-crash.image}
+ extent={market-crash-extent} during={story-time.selection-market-crash}
+ frame={market-crash-frame} z="43" fit="cover" treatment={recipes.media.market-crash}
+ motion={broll-wide}/>
+ <visual:Clip id="richest-chair" image={broll-richest-chair.image}
+ extent={richest-chair-extent} during={story-time.selection-richest-chair}
+ frame={richest-chair-frame} z="44" fit="cover" treatment={recipes.media.richest-chair}
+ motion={broll-right}/>
+ <visual:Clip id="haircut-x" image={broll-haircut-x.image}
+ extent={haircut-x-extent} during={story-time.selection-haircut-x}
+ frame={haircut-x-frame} z="45" fit="cover" treatment={recipes.media.haircut-x}
+ motion={broll-wide}/>
+ <visual:Clip id="fired-friday" image={broll-fired-friday.image}
+ extent={fired-friday-extent} during={story-time.selection-fired-friday}
+ frame={fired-friday-frame} z="46" fit="cover" treatment={recipes.media.fired-friday}
+ motion={broll-left}/>
+ <visual:Clip id="company-quit" image={broll-company-quit.image}
+ extent={company-quit-extent} during={story-time.selection-company-quit}
+ frame={company-quit-frame} z="47" fit="cover" treatment={recipes.media.company-quit}
+ motion={broll-right}/>
+ <visual:Clip id="back-monday" image={broll-back-monday.image}
+ extent={back-monday-extent} during={story-time.selection-back-monday}
+ frame={back-monday-frame} z="48" fit="cover" treatment={recipes.media.back-monday}
+ motion={broll-wide}/>
+ <visual:Clip id="elon-lawsuit" image={broll-elon-lawsuit.image}
+ extent={elon-lawsuit-extent} during={story-time.selection-elon-lawsuit}
+ frame={elon-lawsuit-frame} z="49" fit="cover" treatment={recipes.media.elon-lawsuit}
+ motion={broll-left}/>
+ <visual:Clip id="google-fears" image={broll-google-fears.image}
+ extent={google-fears-extent} during={story-time.selection-google-fears}
+ frame={google-fears-frame} z="50" fit="cover" treatment={recipes.media.google-fears}
+ motion={broll-right}/>
+ <visual:Clip id="congress-grilled" image={broll-congress-grilled.image}
+ extent={congress-grilled-extent} during={story-time.selection-congress-grilled}
+ frame={congress-grilled-frame} z="51" fit="cover" treatment={recipes.media.congress-grilled}
+ motion={broll-left}/>
+ <visual:Clip id="still-here" image={broll-still-here.image}
+ extent={still-here-extent} during={story-time.selection-still-here}
+ frame={still-here-frame} z="52" fit="cover" treatment={recipes.media.still-here}
+ motion={broll-wide}/>
+ </visual:Track>
<caption-fine:Style id="caption-style" recipe={recipes.caption.primary}
font={display-font}/>
- <caption-fine:Track id="captions" document={story.caption}
- timeline={speech.timeline}>
+ <narrative-caption:Timing id="caption-timing" document={story.caption} binding={story.caption-binding} projection={story-time.projection}/>
+ <caption-fine:Caption id="captions" document={story.caption} timing={caption-timing}
+ timeline={speech.timeline} within={vertical.bounds}>
<caption-fine:Use style={caption-style}/>
- </caption-fine:Track>
+ </caption-fine:Caption>
- <film:Film id="main" canvas={vertical} timeline={speech.timeline}
+ <film:Film id="main" canvas={vertical.canvas} timeline={speech.timeline}
appearance={recipes.film.vertical}>
<film:Track source={speech-picture.visual}/>
<film:Track source={speech-sound.audio}/>
<film:Track source={tech-tiers.visual}/>
<film:Track source={tech-tiers.audio}/>
<film:Track source={broll.visual}/>
- <film:Track source={captions.track}/>
+ <film:Track source={captions.visual}/>
<film:Track source={music-bed.audio}/>
</film:Film>
<render:Video id="final" composition={main.composition}
diff --git a/examples/ranking-football/tech-tier-recipes.svs b/examples/ranking-football/tech-tier-recipes.svs
index a4930eba..fb3b7576 100644
--- a/examples/ranking-football/tech-tier-recipes.svs
+++ b/examples/ranking-football/tech-tier-recipes.svs
@@ -11,14 +11,6 @@
film.vertical { background: #090A0F; }
- media.performance { stack-order: 0;
- fit: cover;
- frame-x: 0.5;
- frame-y: 0.5;
- content-x: 0.5;
- content-y: 0.5;
- }
-
ranking.tech {
rows: [
{ "id": "s", "label": "S", "color": "#EE5F52" },
@@ -48,32 +40,19 @@
item-stack: 30;
}
- media.money-rain { stack-order: 40; fit: cover; shadows: 0 18 34 -8 #000000D9; }
- media.twitter-x { stack-order: 41; fit: cover; shadows: 0 18 34 -8 #000000D9; }
- media.mars-rocket { stack-order: 42; fit: cover; shadows: 0 18 34 -8 #000000D9; }
- media.market-crash { stack-order: 43; fit: cover; shadows: 0 18 34 -8 #000000D9; }
- media.richest-chair { stack-order: 44; fit: cover; shadows: 0 18 34 -8 #000000D9; }
- media.haircut-x { stack-order: 45; fit: cover; shadows: 0 18 34 -8 #000000D9; }
- media.fired-friday { stack-order: 46; fit: cover; shadows: 0 18 34 -8 #000000D9; }
- media.company-quit { stack-order: 47; fit: cover; shadows: 0 18 34 -8 #000000D9; }
- media.back-monday { stack-order: 48; fit: cover; shadows: 0 18 34 -8 #000000D9; }
- media.elon-lawsuit { stack-order: 49; fit: cover; shadows: 0 18 34 -8 #000000D9; }
- media.google-fears { stack-order: 50; fit: cover; shadows: 0 18 34 -8 #000000D9; }
- media.congress-grilled { stack-order: 51; fit: cover; shadows: 0 18 34 -8 #000000D9; }
- media.still-here { stack-order: 52; fit: cover; shadows: 0 18 34 -8 #000000E6; }
-
- motion.broll-left {
- enter: pop; enter-frames: 6; enter-easing: ease-out;
- exit: fade; exit-frames: 4; exit-easing: ease-in;
- }
- motion.broll-right {
- enter: bounce; enter-frames: 7; enter-easing: ease-out;
- exit: scale; exit-frames: 4; exit-amount: 0.94; exit-easing: ease-in;
- }
- motion.broll-wide {
- enter: scale; enter-frames: 6; enter-amount: 0.9; enter-easing: ease-out;
- exit: fade; exit-frames: 4; exit-easing: ease-in;
- }
+ media.money-rain { shadows: 0 18 34 -8 #000000D9; }
+ media.twitter-x { shadows: 0 18 34 -8 #000000D9; }
+ media.mars-rocket { shadows: 0 18 34 -8 #000000D9; }
+ media.market-crash { shadows: 0 18 34 -8 #000000D9; }
+ media.richest-chair { shadows: 0 18 34 -8 #000000D9; }
+ media.haircut-x { shadows: 0 18 34 -8 #000000D9; }
+ media.fired-friday { shadows: 0 18 34 -8 #000000D9; }
+ media.company-quit { shadows: 0 18 34 -8 #000000D9; }
+ media.back-monday { shadows: 0 18 34 -8 #000000D9; }
+ media.elon-lawsuit { shadows: 0 18 34 -8 #000000D9; }
+ media.google-fears { shadows: 0 18 34 -8 #000000D9; }
+ media.congress-grilled { shadows: 0 18 34 -8 #000000D9; }
+ media.still-here { shadows: 0 18 34 -8 #000000E6; }
caption.primary {
stack-order: 70;
diff --git a/examples/ranking-football/tier-banana-recipes.svs b/examples/ranking-football/tier-banana-recipes.svs
index 84f798ff..408e910b 100644
--- a/examples/ranking-football/tier-banana-recipes.svs
+++ b/examples/ranking-football/tier-banana-recipes.svs
@@ -11,14 +11,6 @@
film.vertical { background: #090A0F; }
- media.performance { stack-order: 0;
- fit: cover;
- frame-x: 0.5;
- frame-y: 0.5;
- content-x: 0.5;
- content-y: 0.5;
- }
-
ranking.football {
rows: [
{ "id": "s", "label": "S", "color": "#EE5F52" },
@@ -51,49 +43,36 @@
/* B-roll cards sit above the Ranking board and below captions. The later
member of every overlapping joke pair receives the higher stack order. */
media.hair-gel {
- stack-order: 40; fit: cover;
+
shadows: 0 18 34 -8 #000000D9;
}
media.trophy {
- stack-order: 41; fit: cover;
+
shadows: 0 18 34 -8 #000000D9;
}
media.greek-god {
- stack-order: 42; fit: cover;
+
shadows: 0 18 34 -8 #000000D9;
}
media.greek-tragedy {
- stack-order: 43; fit: cover;
+
shadows: 0 18 34 -8 #000000D9;
}
media.penaldo-social {
- stack-order: 44; fit: cover;
+
shadows: 0 18 34 -8 #000000D9;
}
media.tired-dad {
- stack-order: 45; fit: cover;
+
shadows: 0 18 34 -8 #000000D9;
}
media.walks-around {
- stack-order: 46; fit: cover;
+
shadows: 0 18 34 -8 #000000D9;
}
media.hat-trick {
- stack-order: 47; fit: cover;
- shadows: 0 18 34 -8 #000000E6;
- }
- motion.broll-left {
- enter: pop; enter-frames: 6; enter-easing: ease-out;
- exit: fade; exit-frames: 4; exit-easing: ease-in;
- }
- motion.broll-right {
- enter: bounce; enter-frames: 7; enter-easing: ease-out;
- exit: scale; exit-frames: 4; exit-amount: 0.94; exit-easing: ease-in;
- }
- motion.broll-wide {
- enter: scale; enter-frames: 6; enter-amount: 0.9; enter-easing: ease-out;
- exit: fade; exit-frames: 4; exit-easing: ease-in;
+ shadows: 0 18 34 -8 #000000E6;
}
caption.primary {
diff --git a/examples/semantic-composition/README.md b/examples/semantic-composition/README.md
index 0235b77c..1689da52 100644
--- a/examples/semantic-composition/README.md
+++ b/examples/semantic-composition/README.md
@@ -17,7 +17,7 @@ README shows its Source use and explains the timing and material boundaries.
`chat.svml` is an eight-second composition drawn entirely in a project component. It needs no Script,
WhisperX, image generation or source video. Four messages arrive on authored times; the same
-`@example/chat-scene` component accepts Script Moments when used beside a speaking performance.
+`@example/chat-scene` component accepts Script Moments when used beside ordinary speaking Clips.
From the repository after installing its dependencies:
@@ -34,9 +34,3 @@ there is no hosted generation account in this example. The final Output is `fina
Run can be opened in Studio, where its component lane and physical clock work without a Script lane.
For an independent project, install `@hypit/hypit`, copy the component into `packages/`, replace its workspace
dependency with the installed Hypit version, and build the package normally.
-
-## Sound presentation Styles
-
-`packages/sound-styles` defines a project crossfade with explicit outgoing and incoming Segments.
-It uses Sound Uses over the same Timeline and preserves original source playback through the blend.
-Its README explains authoring and the public fragment interface.
diff --git a/examples/semantic-composition/chat.svml b/examples/semantic-composition/chat.svml
index adb386df..fbb9f85c 100644
--- a/examples/semantic-composition/chat.svml
+++ b/examples/semantic-composition/chat.svml
@@ -12,15 +12,15 @@
<time:Timeline id="animation" clock={animation-clock} end="8s"/>
<spatial:Canvas id="canvas" width="540" height="960"/>
<fonts:Stack id="font" family="inter" weight="600" style="normal"/>
- <chat:Scene id="conversation" timeline={animation.timeline} canvas={canvas} font={font}
- during="program" title="Launch crew">
+ <chat:Scene id="conversation" timeline={animation.timeline} within={canvas.bounds} font={font}
+ during="timeline" title="Launch crew">
<chat:Message id="question" sender="Maya" side="left" at="0.5s" text="Are we ready to launch?"/>
<chat:Message id="reply" sender="Leo" side="right" at="2s" text="The video is ready."/>
<chat:Message id="turn" sender="Maya" side="left" at="3.5s" text="Great. One tiny change..."/>
<chat:Message id="reveal" sender="Leo" side="right" at="5.2s" text="I left the whole scene editable."/>
</chat:Scene>
- <film:Film id="main" canvas={canvas} timeline={animation.timeline} appearance={style.film.main}>
- <film:Track source={conversation.track}/>
+ <film:Film id="main" canvas={canvas.canvas} timeline={animation.timeline} appearance={style.film.main}>
+ <film:Track source={conversation.visual}/>
</film:Film>
<render:Video id="final" composition={main.composition} timeline={animation.timeline}/>
</svml>
diff --git a/examples/semantic-composition/packages/chat-scene/README.md b/examples/semantic-composition/packages/chat-scene/README.md
index b753f925..4679c253 100644
--- a/examples/semantic-composition/packages/chat-scene/README.md
+++ b/examples/semantic-composition/packages/chat-scene/README.md
@@ -6,10 +6,10 @@ Content lives in Source. Every Message has its own `at`; there is no fixed messa
For speech-led work, bind the message to the words that introduce it:
```svml
-<chat:Scene id="conversation" timeline={speech.timeline} canvas={canvas} font={font}
- during={story.selection.demo} title="Conversation">
+<chat:Scene id="conversation" timeline={speech.timeline} within={canvas.bounds} font={font}
+ during={story-time.demo} title="Conversation">
<chat:Message id="answer" sender="Maya" side="left" text="Here it is."
- at={story.moment.answer}/>
+ at={story-time.answer}/>
</chat:Scene>
```
@@ -19,7 +19,7 @@ and scrolling duration independently of those triggers (default 10). Messages st
up as the conversation develops. Message times are on the film clock and must fall inside the Scene.
The Surface uses the shared temporal helpers and expands children to a finite create/append/render
-graph. The rendering function receives Timeline, Window and Instants, so it knows nothing about
+graph. The rendering function receives Timeline, an explicit picture-plane Frame, Window and Instants, so it knows nothing about
Script parsing, speech models or Runtime. The browser program evaluates any requested frame directly,
including frames reached by scrubbing, range rendering or concurrent workers.
diff --git a/examples/semantic-composition/packages/chat-scene/src/activation.ts b/examples/semantic-composition/packages/chat-scene/src/activation.ts
index cd8bb506..38a18ee5 100644
--- a/examples/semantic-composition/packages/chat-scene/src/activation.ts
+++ b/examples/semantic-composition/packages/chat-scene/src/activation.ts
@@ -6,10 +6,10 @@ import type { FontStackRef } from "@hypit/hypit/media";
import type { Timeline } from "@hypit/hypit/timeline";
import { timelineTypes } from "@hypit/hypit/timeline";
import { spatialTypes } from "@hypit/hypit/spatial";
-import type { CanvasSpace } from "@hypit/hypit/spatial";
+import type { SpatialFrame } from "@hypit/hypit/spatial";
import { assertTemporalInstantFor, temporalTypes } from "@hypit/hypit/temporal";
import type { TemporalInstant, TemporalWindow } from "@hypit/hypit/temporal";
-import { createTemporalInstantProjection, createTemporalWindowProjection, resolveTemporalContext,
+import { createTemporalInstantConstruction, createTemporalWindowConstruction, resolveTemporalContext,
temporalContextAttributeVocabulary, temporalInstantAttributeNames, temporalInstantAttributeVocabulary,
temporalWindowAttributeNames, temporalWindowAttributeVocabulary } from "@hypit/hypit/temporal-markup";
import { renderChat } from "./render.js";
@@ -19,14 +19,14 @@ const module = { name: "@example/chat-scene", version: "1" } as const;
const types = Object.fromEntries(["Options", "Message", "Messages"].map(name => [name, { module, name }])) as Record<"Options" | "Message" | "Messages", TypeRef>;
const producers = Object.fromEntries(["empty", "append", "render"].map(name => [name, { module, name }])) as Record<"empty" | "append" | "render", { module: typeof module; name: string }>;
export const manifest: ModuleManifest = { format: "hypit.module@1", ...module,
- dependencies: [compositionTypes.visualTrack, mediaTypes.fontStack, timelineTypes.track, spatialTypes.canvas, temporalTypes.instant].map(type => ({ module: type.module })),
+ dependencies: [compositionTypes.visualTrack, mediaTypes.fontStack, timelineTypes.track, spatialTypes.frame, temporalTypes.instant].map(type => ({ module: type.module })),
types: Object.values(types).map(type => ({ name: type.name })), capabilities: [], producers: [
{ name: "empty", inputs: [], outputs: [{ name: "messages", type: types.Messages }], needs: [] },
{ name: "append", inputs: [{ name: "messages", type: types.Messages }, { name: "message", type: types.Message },
{ name: "at", type: temporalTypes.instant }, { name: "timeline", type: timelineTypes.track }], outputs: [{ name: "messages", type: types.Messages }], needs: [] },
{ name: "render", inputs: [{ name: "messages", type: types.Messages }, { name: "options", type: types.Options },
- { name: "timeline", type: timelineTypes.track }, { name: "canvas", type: spatialTypes.canvas },
- { name: "window", type: temporalTypes.window }, { name: "font", type: mediaTypes.fontStack }], outputs: [{ name: "track", type: compositionTypes.visualTrack }], needs: [] },
+ { name: "timeline", type: timelineTypes.track }, { name: "within", type: spatialTypes.frame },
+ { name: "window", type: temporalTypes.window }, { name: "font", type: mediaTypes.fontStack }], outputs: [{ name: "visual", type: compositionTypes.visualTrack }], needs: [] },
],
};
const inline = <T>(record: { value: { kind: string; value?: unknown } } | undefined): T => {
@@ -39,19 +39,19 @@ const component: ComponentPackage = { producers: [
{ producer: producers.append, handler: ({ inputs }) => {
const message = inline<Omit<Message, "at">>(inputs.message), at = inline<TemporalInstant>(inputs.at);
const messages = inline<Message[]>(inputs.messages);
- assertTemporalInstantFor(at, { subjectId: message.id, space: inline<Timeline>(inputs.timeline) });
+ assertTemporalInstantFor(at, { subjectId: message.id, timeline: inline<Timeline>(inputs.timeline) });
if (messages.some(item => item.id === message.id) || (messages.at(-1)?.at.frame ?? -1) > at.frame) throw new Error("Chat messages need unique ids and chronological arrival times.");
return { outputs: { messages: value([...messages, { ...message, at }]) }, needs: {} };
} },
- { producer: producers.render, handler: ({ inputs }) => ({ outputs: { track: value(renderChat(inline<Timeline>(inputs.timeline),
- inline<CanvasSpace>(inputs.canvas), inline<TemporalWindow>(inputs.window), inline<FontStackRef>(inputs.font),
+ { producer: producers.render, handler: ({ inputs }) => ({ outputs: { visual: value(renderChat(inline<Timeline>(inputs.timeline),
+ inline<SpatialFrame>(inputs.within), inline<TemporalWindow>(inputs.window), inline<FontStackRef>(inputs.font),
inline<Message[]>(inputs.messages), inline<ChatOptions>(inputs.options))) }, needs: {} }) },
] };
export const decodeSurface: StructuredSurfaceHandler = ({ element, resolveReference }) => {
- assertAttributes(element, ["id", "timeline", "canvas", "font", "title", "entrance-frames", ...temporalWindowAttributeNames]);
+ assertAttributes(element, ["id", "timeline", "within", "font", "title", "entrance-frames", ...temporalWindowAttributeNames]);
const id = textAttribute(element, "id"), context = resolveTemporalContext({ element, resolveReference });
- const window = createTemporalWindowProjection({ id: `${id}.window`, subjectId: id, element, ...context, resolveReference });
+ const window = createTemporalWindowConstruction({ id: `${id}.window`, subjectId: id, element, ...context, resolveReference });
const reference = (name: string, type: TypeRef): SurfaceResolvedReference => {
const raw = element.attributes[name];
if (typeof raw !== "object" || raw.kind !== "reference") throw new Error(`${name} must be a reference.`);
@@ -62,9 +62,9 @@ export const decodeSurface: StructuredSurfaceHandler = ({ element, resolveRefere
const options: ChatOptions = { id, title: textAttribute(element, "title"), entranceFrames: Number(element.attributes["entrance-frames"] ?? "10") };
const records = [...window.records, { id: `${id}.options`, type: types.Options, value: value(options), range: element.range }];
const components = [...window.components], fragments = [...window.fragments];
- const inputs = [{ name: "timeline", type: timelineTypes.track }, { name: "canvas", type: spatialTypes.canvas },
+ const inputs = [{ name: "timeline", type: timelineTypes.track }, { name: "within", type: spatialTypes.frame },
{ name: "font", type: mediaTypes.fontStack }, { name: "window", type: temporalTypes.window }, { name: "options", type: types.Options }];
- const bindings: Record<string, SurfaceResolvedReference["ref"]> = { timeline: context.timeline.ref, canvas: reference("canvas", spatialTypes.canvas).ref,
+ const bindings: Record<string, SurfaceResolvedReference["ref"]> = { timeline: context.timeline.ref, within: reference("within", spatialTypes.frame).ref,
font: reference("font", mediaTypes.fontStack).ref, window: window.ref, options: { kind: "record", id: `${id}.options` } };
const input = (name: string) => ({ kind: "fragment-input" as const, name });
const operation = (name: string) => ({ kind: "fragment-operation" as const, operation: name });
@@ -76,7 +76,7 @@ export const decodeSurface: StructuredSurfaceHandler = ({ element, resolveRefere
assertAttributes(child, ["id", "sender", "text", "side", ...temporalInstantAttributeNames]); assertEmptyElement(child);
const messageId = textAttribute(child, "id"), side = textAttribute(child, "side");
if (side !== "left" && side !== "right") throw new Error("Message side must be left or right.");
- const at = createTemporalInstantProjection({ id: `${id}.${messageId}`, subjectId: messageId, element: child, ...context, resolveReference });
+ const at = createTemporalInstantConstruction({ id: `${id}.${messageId}`, subjectId: messageId, element: child, ...context, resolveReference });
records.push(...at.records); components.push(...at.components); fragments.push(...at.fragments);
const key = `message-${++index}`;
records.push({ id: `${id}.${key}`, type: types.Message, value: value({ id: messageId, sender: textAttribute(child, "sender"), text: textAttribute(child, "text"), side }), range: child.range });
@@ -87,21 +87,21 @@ export const decodeSurface: StructuredSurfaceHandler = ({ element, resolveRefere
}
if (!index) throw new Error("Chat Scene requires a Message.");
operations.push({ id: "render", producer: producers.render, inputs: { messages: operation(previous), options: input("options"),
- timeline: input("timeline"), canvas: input("canvas"), font: input("font"), window: input("window") }, result: { kind: "output", name: "track" } });
- const fragment = sealGraphFragment({ inputs, operations, exports: [{ name: "track", type: compositionTypes.visualTrack, root: operation("render") }] });
+ timeline: input("timeline"), within: input("within"), font: input("font"), window: input("window") }, result: { kind: "output", name: "visual" } });
+ const fragment = sealGraphFragment({ inputs, operations, exports: [{ name: "visual", type: compositionTypes.visualTrack, root: operation("render") }] });
return { records, fragments: [...fragments, fragment], components: [...components,
- { id, fragment: fragment.id, inputs: bindings, outputs: { track: `${id}.track` }, range: element.range }], exports: [`${id}.track`] };
+ { id, fragment: fragment.id, inputs: bindings, outputs: { visual: `${id}.visual` }, range: element.range }], exports: [`${id}.visual`] };
};
const declaration = { name: "scene", tag: "Scene", mode: "structured" as const,
outputs: [compositionTypes.visualTrack, timelineTypes.track, temporalTypes.window, temporalTypes.instant, temporalTypes.windowSpec, temporalTypes.instantSpec, ...Object.values(types)],
vocabulary: { summary: "A conversation whose message arrivals and scrolling form one visual scene.", attributes: [
...temporalContextAttributeVocabulary, ...temporalWindowAttributeVocabulary,
- ...["id", "title", "canvas", "font"].map(name => ({ name, kind: "expression" as const, required: true, summary: name })),
+ ...["id", "title", "within", "font"].map(name => ({ name, kind: "expression" as const, required: true, summary: name })),
{ name: "entrance-frames", kind: "literal" as const, required: false, summary: "Arrival and scrolling duration; defaults to 10 frames." },
], children: [{ tag: "Message", cardinality: "many" as const, summary: "One authored message and the event that reveals it.", attributes: [
...["id", "sender", "text", "side"].map(name => ({ name, kind: "literal" as const, required: true, summary: name })), ...temporalInstantAttributeVocabulary,
- ] }], ports: [{ name: "track", type: compositionTypes.visualTrack, summary: "The complete conversation scene." }],
- example: '<chat:Scene id="chat" timeline={speech.timeline} canvas={canvas} font={font} during="program" title="Conversation"><chat:Message id="answer" sender="Maya" side="left" text="Here it is." at={story.moment.answer}/></chat:Scene>',
+ ] }], ports: [{ name: "visual", type: compositionTypes.visualTrack, summary: "The complete conversation scene." }],
+ example: '<chat:Scene id="chat" timeline={speech.timeline} within={within} font={font} during="timeline" title="Conversation"><chat:Message id="answer" sender="Maya" side="left" text="Here it is." at={story-time.answer}/></chat:Scene>',
},
};
export const hypitPackage = { format: "hypit.node-package@1" as const, modules: [{ manifest }], components: [component],
diff --git a/examples/semantic-composition/packages/chat-scene/src/render.ts b/examples/semantic-composition/packages/chat-scene/src/render.ts
index cf62ae0e..41df56a4 100644
--- a/examples/semantic-composition/packages/chat-scene/src/render.ts
+++ b/examples/semantic-composition/packages/chat-scene/src/render.ts
@@ -3,7 +3,7 @@ import type { VisualElement } from "@hypit/hypit/composition";
import { browserProgram } from "@hypit/hypit/hyperframes";
import type { FontStackRef } from "@hypit/hypit/media";
import type { Timeline } from "@hypit/hypit/timeline";
-import type { CanvasSpace } from "@hypit/hypit/spatial";
+import type { SpatialFrame } from "@hypit/hypit/spatial";
import { assertTemporalWindowFor } from "@hypit/hypit/temporal";
import type { TemporalInstant, TemporalWindow } from "@hypit/hypit/temporal";
@@ -11,9 +11,9 @@ export type Message = { id: string; sender: string; text: string; side: "left" |
export type ChatOptions = { id: string; title: string; entranceFrames: number };
/** Layout, arrival and scrolling share one visual component; timing is already resolved. */
-export function renderChat(timeline: Timeline, canvas: CanvasSpace, window: TemporalWindow,
+export function renderChat(timeline: Timeline, within: SpatialFrame, window: TemporalWindow,
font: FontStackRef, messages: readonly Message[], options: ChatOptions) {
- assertTemporalWindowFor(window, { subjectId: options.id, space: timeline });
+ assertTemporalWindowFor(window, { subjectId: options.id, timeline: timeline });
if (!Number.isSafeInteger(options.entranceFrames) || options.entranceFrames < 1) throw new Error("Chat entrance-frames must be a positive integer.");
if (messages.some(message => message.at.frame < window.span.startFrame || message.at.frame >= window.span.endFrameExclusive)) throw new Error("Chat messages must appear inside the scene's window.");
let order = 0;
@@ -56,9 +56,10 @@ export function renderChat(timeline: Timeline, canvas: CanvasSpace, window: Temp
[...dots.children].forEach((dot,i)=>dot.style.transform='translateY('+(-3*(1+Math.sin(frame*.18-i)))+'px)');
};`,
});
- return sealVisualTrack({ id: options.id, programSpaceId: timeline.id, visualIr: "hypit.visual-ir@1",
- presents: [{ id: options.id, span: window.span, stacking: { order: 0, tieBreak: options.id },
+ return sealVisualTrack({ id: options.id, timelineId: timeline.id, visualIr: "hypit.visual-ir@1",
+ presents: [{ id: options.id, order: 0, z: 0, span: window.span,
elements: [{ id: "chat", kind: "program", order: 0, program,
- style: [{ name: "position", value: "absolute" }, { name: "inset", value: 0 },
- { name: "width", value: `${canvas.widthPx}px` }, { name: "height", value: `${canvas.heightPx}px` }] }, ...children] }] });
+ style: [{ name: "position", value: "absolute" }, { name: "left", value: `${within.xPx}px` },
+ { name: "top", value: `${within.yPx}px` },
+ { name: "width", value: `${within.widthPx}px` }, { name: "height", value: `${within.heightPx}px` }] }, ...children] }] });
}
diff --git a/examples/semantic-composition/packages/chat-scene/test/render.test.ts b/examples/semantic-composition/packages/chat-scene/test/render.test.ts
index 55eec771..a5417204 100644
--- a/examples/semantic-composition/packages/chat-scene/test/render.test.ts
+++ b/examples/semantic-composition/packages/chat-scene/test/render.test.ts
@@ -2,25 +2,27 @@ import assert from "node:assert/strict";
import test from "node:test";
import type { BrowserProgram } from "@hypit/hypit/hyperframes";
import type { FontStackRef } from "@hypit/media";
-import type { ProgramSpace } from "@hypit/program-space";
-import { composeTemporalWindow, projectMomentInstant, projectProgramInstant } from "@hypit/temporal";
-import { timelineFixture } from "../../../../../test/timeline-fixture.js";
+import type { Timeline } from "@hypit/timeline";
+import { composeTemporalWindow, projectProgramInstant } from "@hypit/temporal";
+import { narrativeProjectionFixture, timelineFixture } from "../../../../../test/timeline-fixture.js";
+import { projectMomentInstantFixture } from "../../../../../test/temporal-fixture.js";
import { fixtureResource } from "../../../../../test/fixture-resource.js";
import { renderChat } from "../src/render.js";
-const space: ProgramSpace = { id: "animation", durationSec: 8, frameRate: { numerator: 30, denominator: 1 } };
+const space: Timeline = { id: "animation", frameCount: 240, frameRate: { numerator: 30, denominator: 1 } };
const font: FontStackRef = { faces: [{ sources: [{ artifact: { kind: "blob", resource: fixtureResource("chat-font"), size: 32, mediaType: "font/woff2" } }], weight: 600, style: "normal" }] };
-const point = (id: string, frame: number) => projectProgramInstant({ itemId: id, subjectId: id, timeline: { ...space, items: [] },
- projection: { ref: "absolute", at: { unit: "frames", value: frame } }, authority: { kind: "fixed" } });
+const point = (id: string, frame: number) => projectProgramInstant({ itemId: id, subjectId: id, timeline: { ...space },
+ projection: { ref: "absolute", at: { unit: "frames", value: frame } } });
const window = composeTemporalWindow({ id: "chat", subjectId: "chat" }, point("chat", 0), point("chat", 240));
test("the same chat renderer consumes authored and word-bound events; changing performance moves only the word-bound message", () => {
const scene = (wordFrame: number) => {
- const semantic = timelineFixture(space, { anchors: [{ identity: "answer", frame: wordFrame }] });
- const at = projectMomentInstant({ itemId: "reply", subjectId: "reply", timeline: semantic,
- moment: { narrativeId: semantic.narrativeId, id: "answer", anchorId: "answer" },
- projection: { ref: "moment.cue" }, authority: { kind: "semantic", boundary: "cue" } });
- return renderChat(semantic, { widthPx: 540, heightPx: 960, origin: "top-left", xDirection: "right", yDirection: "down", pixelAspect: "square" }, window, font, [
+ const timeline = timelineFixture(space);
+ const narrative = narrativeProjectionFixture(timeline, { segments: [{ id: "dialogue", frameCount: 240 }],
+ anchors: [{ identity: "answer", frame: wordFrame }] });
+ const at = projectMomentInstantFixture({ itemId: "reply", subjectId: "reply", semantic: timeline, narrative,
+ moment: { narrativeId: narrative.narrativeId, id: "answer", anchorId: "answer" }, projection: { ref: "moment.cue" } });
+ return renderChat(timeline, { xPx: 0, yPx: 0, widthPx: 540, heightPx: 960 }, window, font, [
{ id: "opening", sender: "Maya", text: "Ready?", side: "left", at: point("opening", 15) },
{ id: "reply", sender: "Leo", text: "Ready.", side: "right", at },
], { id: "chat", title: "Launch", entranceFrames: 10 });
diff --git a/examples/semantic-composition/packages/performance-styles/README.md b/examples/semantic-composition/packages/performance-styles/README.md
deleted file mode 100644
index 851a8526..00000000
--- a/examples/semantic-composition/packages/performance-styles/README.md
+++ /dev/null
@@ -1,42 +0,0 @@
-# Project-authored Performance Styles
-
-This package demonstrates two ordinary project families: a viewport moving between Frames and a
-crossfade between explicitly selected Segments. Both export the common PerformanceStyle, so they
-work alongside the ordinary fixed Style inside one Performance Track.
-
-```svml
-<import as="performance" from="@hypit/performance@1"/>
-<import as="styles" from="@example/performance-styles@1"/>
-<performance:Style id="full" frame={layout.full} appearance={recipes.media.presenter}/>
-<performance:Style id="side" frame={layout.side} appearance={recipes.media.presenter}/>
-<styles:Move id="full-to-side" from={layout.full} to={layout.side}/>
-<styles:Crossfade id="mix" outgoing={story.segment.previous}
- incoming={story.segment.next} frame={layout.side}/>
-<performance:Track id="presenter" timeline={program.timeline} canvas={canvas}>
- <performance:Use style={full}/>
- <performance:Use moment={story.moment.explain}
- start="moment.cue" end="program.end" style={side}/>
- <performance:Use at={story.moment.explain} for="2s" style={full-to-side}/>
- <performance:Use start-source={story.segment.next} start="segment.start"
- end-source={story.segment.previous} end="segment.end" style={mix}/>
-</performance:Track>
-```
-
-The two-second movement overrides the beginning of the already declared side treatment. Changing
-its duration requires no reference to a Use id. Shared endpoint Frames keep the fixed and moving
-layouts aligned. All timing belongs to Uses; each Style is independently reusable.
-
-Crossfade requires known outgoing/incoming Segment identities. A known audio-only source supplies
-transparent picture, giving a fade in or out; an unknown reference reports the actual error. This
-example uses isolated additive blending of weighted pictures. `projectTimelineMedia` preserves the
-original source positions; animation progress comes from the original Use Window.
-
-Read `activation.ts` for the complete author Surface, bound fragment and Producer wiring, and
-`render.ts` for the browser program. A project can add its own parameters or additional events without
-changing Performance. Compile with `npm run build`; install the package in the video project's
-ordinary package dependencies. The rendering test exercises these same functions with actual video.
-
-The package also includes `src/studio.ts`. Move exposes its `from` and `to` Frame coordinates;
-Crossfade exposes its Frame and read-only source references. These parameter Companions match the
-project's own Style Surfaces and are composed into any consuming Performance Use. The Track
-Companion and Studio require no knowledge of these Style names.
diff --git a/examples/semantic-composition/packages/performance-styles/package.json b/examples/semantic-composition/packages/performance-styles/package.json
deleted file mode 100644
index 844505d9..00000000
--- a/examples/semantic-composition/packages/performance-styles/package.json
+++ /dev/null
@@ -1,25 +0,0 @@
-{
- "name": "@example/performance-styles",
- "version": "0.0.0-dev",
- "private": true,
- "type": "module",
- "hypit": {
- "activation": "./dist/activation.js"
- },
- "exports": {
- ".": "./dist/render.js"
- },
- "files": [
- "dist",
- "README.md"
- ],
- "scripts": {
- "build": "tsc -p tsconfig.json",
- "prepack": "npm run build"
- },
- "devDependencies": {
- "@hypit/hypit": "workspace:*",
- "typescript": "5.9.3",
- "@types/node": "24.10.1"
- }
-}
diff --git a/examples/semantic-composition/packages/performance-styles/src/activation.ts b/examples/semantic-composition/packages/performance-styles/src/activation.ts
deleted file mode 100644
index 1f2c8d56..00000000
--- a/examples/semantic-composition/packages/performance-styles/src/activation.ts
+++ /dev/null
@@ -1,57 +0,0 @@
-import { styleStudioFacet } from "./studio.js";
-import { assertAttributes, assertEmptyElement, canonicalize, createMarkupSurfaceHostFacet, sameType, sealGraphFragment, textAttribute } from "@hypit/hypit/author-kit";
-import type { ComponentPackage, ModuleManifest, StructuredSurfaceHandler, SurfaceResolvedReference } from "@hypit/hypit/author-kit";
-import { compositionTypes } from "@hypit/hypit/composition";
-import { performanceStyle, performanceTypes, performanceModuleRef } from "@hypit/hypit/performance";
-import { timelineTypes } from "@hypit/hypit/timeline";
-import type { Timeline } from "@hypit/hypit/timeline";
-import { spatialTypes } from "@hypit/hypit/spatial";
-import type { SpatialFrame } from "@hypit/hypit/spatial";
-import { temporalTypes } from "@hypit/hypit/temporal";
-import type { TemporalWindow } from "@hypit/hypit/temporal";
-import { narrativeTypes } from "@hypit/hypit/narrative";
-import type { NarrativeExcerpt } from "@hypit/hypit/narrative";
-import { movingFrame, crossfade } from "./render.js";
-
-const module = { name: "@example/performance-styles", version: "1" } as const;
-const common = [{ name: "timeline", type: timelineTypes.track }, { name: "canvas", type: spatialTypes.canvas }, { name: "window", type: temporalTypes.window }];
-const moveInputs = [...common, { name: "from", type: spatialTypes.frame }, { name: "to", type: spatialTypes.frame }];
-const mixInputs = [...common, { name: "outgoing", type: narrativeTypes.excerpt }, { name: "incoming", type: narrativeTypes.excerpt }, { name: "frame", type: spatialTypes.frame }];
-const families = [{ name: "move", tag: "Move", ports: moveInputs }, { name: "crossfade", tag: "Crossfade", ports: mixInputs }];
-export const manifest: ModuleManifest = { format: "hypit.module@1", ...module,
- dependencies: [performanceModuleRef, compositionTypes.visualTrack.module, timelineTypes.track.module, spatialTypes.canvas.module, temporalTypes.window.module, narrativeTypes.excerpt.module].map(module => ({ module })),
- types: [], capabilities: [], producers: families.map(family => ({ name: family.name, inputs: family.ports, outputs: [{ name: "visual", type: compositionTypes.visualTrack }], needs: [] })) };
-const fragments = families.map(family => sealGraphFragment({ inputs: family.ports,
- operations: [{ id: "render", producer: { module, name: family.name }, inputs: Object.fromEntries(family.ports.map(port => [port.name, { kind: "fragment-input" as const, name: port.name }])), result: { kind: "output", name: "visual" } }],
- exports: [{ name: "visual", type: compositionTypes.visualTrack, root: { kind: "fragment-operation", operation: "render" } }] }));
-const component: ComponentPackage = { producers: families.map(family => ({ producer: { module, name: family.name }, handler: ({ inputs }) => {
- const values = Object.fromEntries(Object.entries(inputs).map(([key, record]) => {
- if (record.value.kind !== "inline") throw new Error(`${key} must be inline`);
- return [key, record.value.value];
- }));
- const visual = family.name === "move" ? movingFrame(values.timeline as unknown as Timeline, values.window as unknown as TemporalWindow, values.from as unknown as SpatialFrame, values.to as unknown as SpatialFrame)
- : crossfade(values.timeline as unknown as Timeline, values.window as unknown as TemporalWindow, values.outgoing as unknown as NarrativeExcerpt, values.incoming as unknown as NarrativeExcerpt, values.frame as unknown as SpatialFrame);
- return { outputs: { visual: { kind: "inline", value: canonicalize(visual) } }, needs: {} };
-} })) };
-const hostFacets = families.map((family,index) => {
- const params = family.ports.slice(common.length);
- const handler: StructuredSurfaceHandler = ({ element, resolveReference }) => {
- assertAttributes(element, ["id", ...params.map(port => port.name)]); assertEmptyElement(element);
- const bindings: Record<string, SurfaceResolvedReference> = {};
- for (const param of params) {
- const raw = element.attributes[param.name];
- if (typeof raw !== "object" || raw.kind !== "reference") throw new Error(`${param.name} must be a reference`);
- const value = resolveReference(raw.path);
- if (value === undefined || !sameType(value.type,param.type)) throw new Error(`${param.name} has the wrong Type`);
- bindings[param.name] = value;
- }
- return { records: [{ id: textAttribute(element,"id"), type: performanceTypes.style,
- value: { kind: "inline", value: canonicalize(performanceStyle(fragments[index]!,bindings)) }, range: element.range }], components: [], fragments: [] };
- };
- return createMarkupSurfaceHostFacet({ module, declaration: { name: family.name, tag: family.tag, mode: "structured", outputs: [performanceTypes.style], vocabulary: {
- summary: `Project-owned ${family.name} presentation Style.`, example: `<styles:${family.tag} id="look" ${params.map(port => `${port.name}={${port.name}}`).join(' ')}/>`,
- attributes: [{ name: "id", kind: "identifier", required: true, summary: "Style identity." }, ...params.map(port => ({ name: port.name, kind: "reference" as const, required: true, accepts: [port.type], summary: `Explicit ${port.name} input.` }))],
- } }, handler });
-});
-export const hypitPackage = { format: "hypit.node-package@1" as const, modules: [{ manifest }], components: [component], hostFacets: [...hostFacets, styleStudioFacet(module)] };
-export default hypitPackage;
diff --git a/examples/semantic-composition/packages/performance-styles/src/render.ts b/examples/semantic-composition/packages/performance-styles/src/render.ts
deleted file mode 100644
index 32daf180..00000000
--- a/examples/semantic-composition/packages/performance-styles/src/render.ts
+++ /dev/null
@@ -1,54 +0,0 @@
-import { sealVisualTrack } from "@hypit/hypit/composition";
-import type { VisualElement } from "@hypit/hypit/composition";
-import { browserProgram } from "@hypit/hypit/hyperframes";
-import { projectTimelineMedia } from "@hypit/hypit/timeline";
-import type { Timeline } from "@hypit/hypit/timeline";
-import type { TemporalWindow } from "@hypit/hypit/temporal";
-import type { SpatialFrame } from "@hypit/hypit/spatial";
-import type { NarrativeExcerpt } from "@hypit/hypit/narrative";
-
-/** Project behavior, not a registered special effect: the original Use window owns progress. */
-export function movingFrame(timeline: Timeline, window: TemporalWindow, from: SpatialFrame, to: SpatialFrame) {
- return render(timeline, window, { from, to });
-}
-export function crossfade(timeline: Timeline, window: TemporalWindow, outgoing: NarrativeExcerpt, incoming: NarrativeExcerpt, frame: SpatialFrame) {
- for (const ref of [outgoing, incoming]) {
- if (ref.narrativeId !== timeline.narrativeId || !timeline.items.some(item => item.take.segment.segmentId === ref.id)) {
- throw new Error(`Unknown crossfade source ${ref.id}.`);
- }
- }
- return render(timeline, window, { outgoing: outgoing.id, incoming: incoming.id, from: frame, to: frame });
-}
-function render(timeline: Timeline, window: TemporalWindow, options: { from: SpatialFrame; to: SpatialFrame; outgoing?: string; incoming?: string }) {
- const id = window.subjectId;
- const clips = projectTimelineMedia(timeline, window.span).filter(clip => clip.media.visual !== undefined
- && (options.outgoing === undefined || clip.segmentId === options.outgoing || clip.segmentId === options.incoming));
- const videos: VisualElement[] = clips.map((clip, index) => ({
- id: `source-${index}`, parent: "scene", order: index + 1, kind: "video", muted: true,
- artifact: clip.media.visual!.artifact,
- attributes: [{ name: "data-source-role", value: options.incoming === clip.segmentId ? "incoming" : "outgoing" }],
- style: [{ name: "position", value: "absolute" }, { name: "inset", value: 0 }, { name: "width", value: "100%" }, { name: "height", value: "100%" }, { name: "object-fit", value: "cover" }],
- sampling: { sourceFrameRate: clip.media.timeline.frameRate, sourceFrameCount: clip.media.timeline.frameCount, segments: [{
- target: { startFrame: clip.span.startFrame - window.span.startFrame, endFrameExclusive: clip.span.endFrameExclusive - window.span.startFrame },
- sourceFrame: { numerator: clip.source.startFrame, denominator: 1 }, rate: { numerator: 1, denominator: 1 },
- }] },
- }));
- const program = browserProgram({
- html: `<div class="viewport">${videos.map((video,index) => `<div class="source" data-role="${clips[index]!.segmentId === options.incoming ? "incoming" : "outgoing"}">{{${video.id}}}</div>`).join("")}</div>`,
- css: `.viewport{position:absolute;overflow:hidden;isolation:isolate}.source{position:absolute;inset:0;${options.outgoing === undefined ? '' : 'mix-blend-mode:plus-lighter'}}`,
- data: { from: options.from, to: options.to, mixing: options.outgoing !== undefined, duration: window.span.endFrameExclusive - window.span.startFrame },
- setup: `const view=root.querySelector('.viewport'), sources=view.querySelectorAll('.source');
- return frame => {
- const p=Math.max(0,Math.min(1,frame/Math.max(1,data.duration-1)));
- const q=p*p*(3-2*p), a=data.from, b=data.to;
- Object.assign(view.style,{left:(a.xPx+(b.xPx-a.xPx)*q)+'px',top:(a.yPx+(b.yPx-a.yPx)*q)+'px',
- width:(a.widthPx+(b.widthPx-a.widthPx)*q)+'px',height:(a.heightPx+(b.heightPx-a.heightPx)*q)+'px'});
- if(data.mixing) for(const child of sources) {
- const role=child.dataset.role;
- child.style.opacity=String(role==='incoming'?p:1-p);
- }
- };`,
- });
- return sealVisualTrack({ id, programSpaceId: timeline.id, visualIr: "hypit.visual-ir@1", presents: videos.length ? [{ id, span: window.span,
- stacking: { order: 0, tieBreak: id }, elements: [{ id: "scene", kind: "program", order: 0, style: [{ name: "position", value: "absolute" }, { name: "inset", value: 0 }], program }, ...videos] }] : [] });
-}
diff --git a/examples/semantic-composition/packages/performance-styles/src/studio.ts b/examples/semantic-composition/packages/performance-styles/src/studio.ts
deleted file mode 100644
index 99cd0b9a..00000000
--- a/examples/semantic-composition/packages/performance-styles/src/studio.ts
+++ /dev/null
@@ -1,28 +0,0 @@
-import { createStudioCompanionHostFacet } from "@hypit/hypit/studio-adapter";
-import type { StudioParameterCompanion } from "@hypit/hypit/studio-adapter";
-
-/** The project Style owns its inputs; Performance only owns its Use interval. */
-export function styleStudioFacet(module: { readonly name: string; readonly version: string }) {
- const coordinates = ["left", "top", "right", "bottom", "x", "y", "width", "height"];
- const definitions = [
- { surface: "move", frames: ["from", "to"], sources: [] },
- { surface: "crossfade", frames: ["frame"], sources: ["outgoing", "incoming"] },
- ];
- const parameters: StudioParameterCompanion[] = definitions.map(({ surface, frames, sources }) => ({
- id: surface, match: { module, surface },
- bindings: [
- ...frames.map(name => ({ name, referenced: coordinates.map(name => ({ name, writable: true })) })),
- ...sources.map(name => ({ name })),
- ],
- inspector: [
- ...frames.flatMap(frame => coordinates.map(name => ({
- binding: `${frame}.${name}`, label: name, domain: "where" as const,
- page: { id: frame, label: frame }, section: { id: "frame", label: "Frame" },
- control: "number" as const, number: { suffixes: ["%", "px"], step: 1 },
- }))),
- ...sources.map(name => ({ binding: name, label: name, domain: "how" as const,
- section: { id: "sources", label: "Sources" }, control: "text" as const })),
- ],
- }));
- return createStudioCompanionHostFacet({ parameters });
-}
diff --git a/examples/semantic-composition/packages/performance-styles/tsconfig.json b/examples/semantic-composition/packages/performance-styles/tsconfig.json
deleted file mode 100644
index 6d5a18e7..00000000
--- a/examples/semantic-composition/packages/performance-styles/tsconfig.json
+++ /dev/null
@@ -1,18 +0,0 @@
-{
- "compilerOptions": {
- "target": "ES2023",
- "module": "NodeNext",
- "moduleResolution": "NodeNext",
- "lib": ["ES2023"],
- "strict": true,
- "noUncheckedIndexedAccess": true,
- "exactOptionalPropertyTypes": true,
- "verbatimModuleSyntax": true,
- "declaration": true,
- "sourceMap": true,
- "rootDir": "src",
- "outDir": "dist",
- "skipLibCheck": true
- },
- "include": ["src/**/*.ts"]
-}
diff --git a/examples/semantic-composition/packages/responsive-explainer/README.md b/examples/semantic-composition/packages/responsive-explainer/README.md
index 300d19f8..9e22c7dc 100644
--- a/examples/semantic-composition/packages/responsive-explainer/README.md
+++ b/examples/semantic-composition/packages/responsive-explainer/README.md
@@ -3,45 +3,39 @@
One scene coordinates a playing performance and the diagram it makes room for. This intentionally
small example can be adapted to the video's own visual idea; its HTML and motion live in `src/render.ts`.
-With prepared Takes, a Canvas and an exact FontStack already available:
+With normalized media, its exact source Window, a projected Instant, Canvas and exact FontStack
+already available:
```svml
<import as="explainer" from="@example/responsive-explainer@1"/>
-<time:Clock id="clock" frame-rate="30"/>
-<time:Timeline id="speech" clock={clock}>
- <time:Take source={opening.take}/>
- <time:Take source={explanation.take}/>
-</time:Timeline>
-<explainer:Scene id="scene" timeline={speech.timeline} canvas={canvas} font={font}
- during="program" reveal={story.moment.demonstrate} title="Make room for meaning"
+<explainer:Scene id="scene" timeline={speech.timeline}
+ within={canvas.bounds} font={font} media={speaker-media.media} source-window={speech.speaker}
+ during="timeline" reveal={story-time.demonstrate} title="Make room for meaning"
transition-frames="24" stack-order="0"/>
-<import as="sound" from="@hypit/sound@1"/>
-<sound:Style id="voice-style"/>
-<sound:Track id="voice" timeline={speech.timeline}>
- <sound:Use style={voice-style}/>
-</sound:Track>
-<film:Film id="main" canvas={canvas} timeline={speech.timeline} appearance={look.film}>
+<film:Film id="main" canvas={canvas.canvas} timeline={speech.timeline} appearance={look.film}>
<film:Track source={scene.visual}/>
- <film:Track source={voice.audio}/>
- <film:Track source={captions.track}/>
+ <film:Track source={mix.audio}/>
+ <film:Track source={captions.visual}/>
</film:Film>
```
-`during` also accepts a Script Selection or Segment; the shared Window syntax supports other authored
-intervals. `reveal` selects a Script Moment, such as `@{demonstrate!}` before the relevant word. Rewriting
-the Script or using another delivery changes the projected frame while retaining the layout behavior.
+`during` also accepts a resolved Window; the shared Window syntax supports authored absolute
+intervals. `reveal` accepts an absolute Instant, such as the output projected from
+`@{demonstrate!}` before the relevant word. Rewriting the Script or using another delivery changes
+the upstream projected frame while retaining the layout behavior.
`transition-frames` is the duration of that change, separate from the scene's lifetime. `stack-order`
places this scene among other contributions. The caller supplies its title and exact fonts.
-`projectTimelineMedia` selects all intersecting prepared Takes. Each video's target interval is
-Present-local and its source offset is preserved. The parent viewport changes size and position;
-playback is never restarted by the layout change. The component owns the diagram and the viewport,
-so its internal overlap, rounded clipping and backdrop blur are ordinary HTML/CSS relationships.
-Sound independently presents the existing audio as `voice.audio`.
+The explicit source Window exactly matches the media length. The component intersects that Window
+with its own lifetime and preserves the corresponding source offset. The
+parent viewport changes size and position; playback is never restarted by the layout change. The
+component owns the diagram and the viewport, so its internal overlap, rounded clipping and backdrop
+blur are ordinary HTML/CSS relationships. A peer Audio Clip independently publishes
+`mix.audio` using the same media and Window.
-`src/activation.ts` declares the Module, Surface, semantic projections and Producer Fragment.
+`src/activation.ts` declares the Module, Surface, absolute time construction and Producer Fragment.
`src/render.ts` emits a browser program with HTML slots for typed video and text children. Its render
function computes state directly from local frame time, supporting direct seeking, range renders
and independent workers.
diff --git a/examples/semantic-composition/packages/responsive-explainer/src/activation.ts b/examples/semantic-composition/packages/responsive-explainer/src/activation.ts
index 254cbf90..6b1b5fd2 100644
--- a/examples/semantic-composition/packages/responsive-explainer/src/activation.ts
+++ b/examples/semantic-composition/packages/responsive-explainer/src/activation.ts
@@ -4,15 +4,16 @@ import type { ComponentPackage, ModuleManifest, StructuredSurfaceHandler, Surfac
import { compositionTypes } from "@hypit/hypit/composition";
import { mediaTypes } from "@hypit/hypit/media";
import type { FontStackRef } from "@hypit/hypit/media";
-import { narrativeTypes } from "@hypit/hypit/narrative";
+import type { SynchronizedMedia } from "@hypit/hypit/media";
import { timelineTypes } from "@hypit/hypit/timeline";
import type { Timeline } from "@hypit/hypit/timeline";
import { spatialTypes } from "@hypit/hypit/spatial";
-import type { CanvasSpace } from "@hypit/hypit/spatial";
+import type { SpatialFrame } from "@hypit/hypit/spatial";
import { temporalTypes } from "@hypit/hypit/temporal";
import type { TemporalInstant, TemporalWindow } from "@hypit/hypit/temporal";
-import { createTemporalInstantProjection, createTemporalWindowProjection, temporalWindowAttributeNames,
- temporalWindowAttributeVocabulary } from "@hypit/hypit/temporal-markup";
+import { createTemporalInstantConstruction, createTemporalWindowConstruction, temporalWindowAttributeNames,
+ temporalWindowAttributeVocabulary, resolveTemporalContext } from "@hypit/hypit/temporal-markup";
+import { temporalContextAttributeVocabulary } from "@hypit/hypit/temporal-markup";
import { renderExplainer } from "./render.js";
import type { ExplainerOptions } from "./render.js";
@@ -20,13 +21,15 @@ const module = { name: "@example/responsive-explainer", version: "1" } as const;
const optionsType = { module, name: "ExplainerOptions" };
const producer = { module, name: "compose" };
const inputs = [
- { name: "timeline", type: timelineTypes.track }, { name: "canvas", type: spatialTypes.canvas },
+ { name: "timeline", type: timelineTypes.track }, { name: "within", type: spatialTypes.frame },
{ name: "window", type: temporalTypes.window }, { name: "reveal", type: temporalTypes.instant },
+ { name: "media", type: mediaTypes.synchronized }, { name: "sourceWindow", type: temporalTypes.window },
{ name: "font", type: mediaTypes.fontStack }, { name: "options", type: optionsType },
];
export const manifest: ModuleManifest = { format: "hypit.module@1", ...module,
dependencies: [compositionTypes.visualTrack, mediaTypes.fontStack, timelineTypes.track,
- spatialTypes.canvas, temporalTypes.window].map(type => ({ module: type.module })),
+ spatialTypes.frame, temporalTypes.window, temporalTypes.instant]
+ .map(type => ({ module: type.module })),
types: [{ name: optionsType.name }], capabilities: [],
producers: [{ name: producer.name, inputs, outputs: [{ name: "visual", type: compositionTypes.visualTrack }], needs: [] }],
};
@@ -41,11 +44,12 @@ const inline = <T>(record: { value: { kind: string; value?: unknown } } | undefi
};
const component: ComponentPackage = { producers: [{ producer, handler: ({ inputs }) => ({ needs: {}, outputs: {
visual: { kind: "inline", value: canonicalize(renderExplainer(inline<Timeline>(inputs.timeline),
- inline<CanvasSpace>(inputs.canvas), inline<TemporalWindow>(inputs.window), inline<TemporalInstant>(inputs.reveal),
+ inline<SpatialFrame>(inputs.within), inline<TemporalWindow>(inputs.window), inline<TemporalInstant>(inputs.reveal),
+ inline<SynchronizedMedia>(inputs.media), inline<TemporalWindow>(inputs.sourceWindow),
inline<FontStackRef>(inputs.font).faces, inline<ExplainerOptions>(inputs.options))) },
} }) }] };
export const decodeSurface: StructuredSurfaceHandler = ({ element, resolveReference }) => {
- assertAttributes(element, ["id", "timeline", "canvas", "font", "reveal", "title", "transition-frames", "stack-order", ...temporalWindowAttributeNames]);
+ assertAttributes(element, ["id", "timeline", "within", "font", "media", "source-window", "reveal", "title", "transition-frames", "stack-order", ...temporalWindowAttributeNames]);
assertEmptyElement(element);
const id = textAttribute(element, "id");
const reference = (name: string, type: TypeRef): SurfaceResolvedReference => {
@@ -55,34 +59,41 @@ export const decodeSurface: StructuredSurfaceHandler = ({ element, resolveRefere
if (value === undefined || !sameType(type, value.type)) throw new Error(`${name} has the wrong type.`);
return value;
};
- const timeline = reference("timeline", timelineTypes.track);
- const window = createTemporalWindowProjection({ id: `${id}.window`, element, timeline, resolveReference });
- // Reveal has its own Moment; the outer Window independently controls this scene's lifetime.
- reference("reveal", narrativeTypes.moment);
- const reveal = createTemporalInstantProjection({ id: `${id}.reveal`,
- element: { ...element, attributes: { at: element.attributes.reveal! } }, timeline, resolveReference });
+ const context = resolveTemporalContext({ element, resolveReference });
+ const timeline = context.timeline;
+ const window = createTemporalWindowConstruction({ id: `${id}.window`, element, ...context, resolveReference });
+ // Reveal is already absolute; the outer Window independently controls this scene's lifetime.
+ reference("reveal", temporalTypes.instant);
+ const reveal = createTemporalInstantConstruction({ id: `${id}.reveal`,
+ element: { ...element, attributes: { at: element.attributes.reveal! } }, ...context, resolveReference });
const options: ExplainerOptions = { id, title: textAttribute(element, "title"),
transitionFrames: Number(textAttribute(element, "transition-frames")), stackingOrder: Number(textAttribute(element, "stack-order")) };
return { records: [...window.records, ...reveal.records, { id: `${id}.options`, type: optionsType,
value: { kind: "inline", value: canonicalize(options) }, range: element.range }],
fragments: [...window.fragments, ...reveal.fragments, fragment],
components: [...window.components, ...reveal.components, { id, fragment: fragment.id,
- inputs: { timeline: timeline.ref, canvas: reference("canvas", spatialTypes.canvas).ref,
- font: reference("font", mediaTypes.fontStack).ref, window: window.ref, reveal: reveal.ref,
+ inputs: { timeline: timeline.ref, within: reference("within", spatialTypes.frame).ref,
+ font: reference("font", mediaTypes.fontStack).ref,
+ media: reference("media", mediaTypes.synchronized).ref,
+ sourceWindow: reference("source-window", temporalTypes.window).ref,
+ window: window.ref, reveal: reveal.ref,
options: { kind: "record", id: `${id}.options` } }, outputs: { visual: `${id}.visual` }, range: element.range }],
exports: [`${id}.visual`] };
};
const declaration = { name: "scene", tag: "Scene", mode: "structured" as const,
- outputs: [compositionTypes.visualTrack, temporalTypes.window, temporalTypes.instant, temporalTypes.windowSpec, temporalTypes.instantSpec, optionsType],
+ outputs: [compositionTypes.visualTrack, temporalTypes.window, temporalTypes.instant, temporalTypes.duration,
+ temporalTypes.extent, temporalTypes.shiftSpec, temporalTypes.windowSpec, temporalTypes.instantSpec, optionsType],
vocabulary: { summary: "A continuously playing performance makes room for a diagram on a semantic Moment.",
attributes: [
...["id", "title", "transition-frames", "stack-order"].map(name => ({ name, kind: "literal" as const, required: true, summary: name })),
- ...[{ name: "timeline", type: timelineTypes.track }, { name: "canvas", type: spatialTypes.canvas },
- { name: "font", type: mediaTypes.fontStack }, { name: "reveal", type: narrativeTypes.moment }]
+ ...temporalContextAttributeVocabulary,
+ ...[{ name: "within", type: spatialTypes.frame },
+ { name: "font", type: mediaTypes.fontStack }, { name: "media", type: mediaTypes.synchronized },
+ { name: "source-window", type: temporalTypes.window }, { name: "reveal", type: temporalTypes.instant }]
.map(({ name, type }) => ({ name, kind: "reference" as const, required: true, accepts: [type], summary: name })),
...temporalWindowAttributeVocabulary,
], ports: [{ name: "visual", type: compositionTypes.visualTrack, summary: "The coordinated scene." }],
- example: '<explainer:Scene id="scene" timeline={speech.timeline} canvas={canvas} font={font} during="program" reveal={story.moment.reveal} title="How it works" transition-frames="18" stack-order="0"/>',
+ example: '<explainer:Scene id="scene" timeline={speech.timeline} within={within} font={font} media={presenter.media} source-window={speech.presenter} during="timeline" reveal={story-time.reveal} title="How it works" transition-frames="18" stack-order="0"/>',
},
};
export const hypitPackage = { format: "hypit.node-package@1" as const, modules: [{ manifest }], components: [component],
diff --git a/examples/semantic-composition/packages/responsive-explainer/src/render.ts b/examples/semantic-composition/packages/responsive-explainer/src/render.ts
index 2cd84925..088ed596 100644
--- a/examples/semantic-composition/packages/responsive-explainer/src/render.ts
+++ b/examples/semantic-composition/packages/responsive-explainer/src/render.ts
@@ -2,35 +2,45 @@ import { sealVisualTrack } from "@hypit/hypit/composition";
import type { VisualElement } from "@hypit/hypit/composition";
import { browserProgram } from "@hypit/hypit/hyperframes";
import type { FontArtifactRef } from "@hypit/hypit/media";
-import { projectTimelineMedia, projectTimelineSpace } from "@hypit/hypit/timeline";
+import type { SynchronizedMedia } from "@hypit/hypit/media";
import type { Timeline } from "@hypit/hypit/timeline";
-import type { CanvasSpace } from "@hypit/hypit/spatial";
+import type { SpatialFrame } from "@hypit/hypit/spatial";
import type { TemporalInstant, TemporalWindow } from "@hypit/hypit/temporal";
export type ExplainerOptions = { id: string; title: string; transitionFrames: number; stackingOrder: number };
/** One scene owns the moving performance viewport and the diagram it makes room for. */
-export function renderExplainer(semantic: Timeline, canvas: CanvasSpace, window: TemporalWindow,
- reveal: TemporalInstant, fonts: readonly FontArtifactRef[], options: ExplainerOptions) {
- const space = projectTimelineSpace(semantic);
- if (window.start.source.spaceId !== space.id || reveal.source.spaceId !== space.id)
- throw new Error("Explainer timing must belong to its semantic performance.");
+export function renderExplainer(timeline: Timeline, within: SpatialFrame, window: TemporalWindow,
+ reveal: TemporalInstant, media: SynchronizedMedia, sourceWindow: TemporalWindow,
+ fonts: readonly FontArtifactRef[], options: ExplainerOptions) {
+ if (window.start.timelineId !== timeline.id || reveal.timelineId !== timeline.id)
+ throw new Error("Explainer timing must belong to its Timeline.");
if (!Number.isSafeInteger(options.transitionFrames) || options.transitionFrames < 1)
throw new Error("Explainer transitionFrames must be a positive integer.");
- const clips = projectTimelineMedia(semantic, window.span).filter(clip => clip.media.visual !== undefined);
+ if (sourceWindow.start.timelineId !== timeline.id) throw new Error("Explainer source belongs to another Timeline.");
+ if (media.visual === undefined) throw new Error("Explainer media has no visual stream.");
+ if (media.frameDomain.frameCount !== sourceWindow.span.endFrameExclusive - sourceWindow.span.startFrame
+ || media.frameDomain.frameRate.numerator !== timeline.frameRate.numerator
+ || media.frameDomain.frameRate.denominator !== timeline.frameRate.denominator) {
+ throw new Error("Explainer media requires an equal-length native source Window.");
+ }
+ const clipStart = Math.max(sourceWindow.span.startFrame, window.span.startFrame);
+ const clipEnd = Math.min(sourceWindow.span.endFrameExclusive, window.span.endFrameExclusive);
+ const clips = clipEnd <= clipStart ? [] : [{ startFrame: clipStart, endFrameExclusive: clipEnd,
+ sourceStartFrame: clipStart - sourceWindow.span.startFrame }];
const videos: VisualElement[] = clips.map((clip, i) => ({
id: `take-${i}`, parent: "scene", kind: "video", order: i + 1,
- artifact: clip.media.visual!.artifact, muted: true,
+ artifact: media.visual!.artifact, muted: true,
style: [{ name: "position", value: "absolute" }, { name: "inset", value: 0 },
{ name: "width", value: "100%" }, { name: "height", value: "100%" }, { name: "object-fit", value: "cover" }],
- sampling: { sourceFrameRate: clip.media.timeline.frameRate, sourceFrameCount: clip.media.timeline.frameCount,
- segments: [{ target: { startFrame: clip.span.startFrame - window.span.startFrame,
- endFrameExclusive: clip.span.endFrameExclusive - window.span.startFrame },
- sourceFrame: { numerator: clip.source.startFrame, denominator: 1 }, rate: { numerator: 1, denominator: 1 } }] },
+ sourceTime: { sourceFrameRate: timeline.frameRate, sourceFrameCount: media.frameDomain.frameCount,
+ pieces: [{ target: { startFrame: clip.startFrame - window.span.startFrame,
+ endFrameExclusive: clip.endFrameExclusive - window.span.startFrame },
+ sourceAtStart: { numerator: clip.sourceStartFrame, denominator: 1 }, rate: { numerator: 1, denominator: 1 } }] },
}));
const labels: VisualElement[] = [options.title, "Intent", "Performance", "Composition"].map((text, i) => ({
id: `label-${i}`, parent: "scene", kind: "text", order: videos.length + i + 1, text, fonts,
- style: [{ name: "font-size", value: `${i === 0 ? Math.round(canvas.widthPx * .035) : 23}px` }, { name: "color", value: "#f5eddc" },
+ style: [{ name: "font-size", value: `${i === 0 ? Math.round(within.widthPx * .035) : 23}px` }, { name: "color", value: "#f5eddc" },
{ name: "white-space", value: "nowrap" }],
}));
// Exact fonts belong to the typed text children; the program supplies layout and behavior.
@@ -49,7 +59,7 @@ export function renderExplainer(semantic: Timeline, canvas: CanvasSpace, window:
path { fill:none; stroke:#c5e98b; stroke-width:4; stroke-linecap:round; stroke-dasharray:900; }
.step { position:absolute; padding:14px 24px; border:1px solid #91c6a2; border-radius:16px; background:#285b51; }
.first { left:2%; top:30%; } .second { right:2%; top:53%; } .third { left:2%; top:76%; }`,
- data: { width: canvas.widthPx, height: canvas.heightPx,
+ data: { width: within.widthPx, height: within.heightPx,
reveal: reveal.frame - window.span.startFrame, transition: options.transitionFrames },
setup: `const viewport=root.querySelector('.viewport'), diagram=root.querySelector('.diagram'), path=root.querySelector('path');
return frame => {
@@ -61,8 +71,10 @@ export function renderExplainer(semantic: Timeline, canvas: CanvasSpace, window:
path.style.strokeDashoffset=String(900*(1-p));
};`,
});
- return sealVisualTrack({ id: options.id, programSpaceId: space.id, visualIr: "hypit.visual-ir@1",
- presents: [{ id: options.id, span: window.span, stacking: { order: options.stackingOrder, tieBreak: options.id },
+ return sealVisualTrack({ id: options.id, timelineId: timeline.id, visualIr: "hypit.visual-ir@1",
+ presents: [{ id: options.id, order: 0, z: options.stackingOrder, span: window.span,
elements: [{ id: "scene", kind: "program", order: 0, program,
- style: [{ name: "position", value: "absolute" }, { name: "inset", value: 0 }] }, ...videos, ...labels] }] });
+ style: [{ name: "position", value: "absolute" }, { name: "left", value: `${within.xPx}px` },
+ { name: "top", value: `${within.yPx}px` }, { name: "width", value: `${within.widthPx}px` },
+ { name: "height", value: `${within.heightPx}px` }] }, ...videos, ...labels] }] });
}
diff --git a/examples/semantic-composition/packages/sound-styles/README.md b/examples/semantic-composition/packages/sound-styles/README.md
deleted file mode 100644
index 39969457..00000000
--- a/examples/semantic-composition/packages/sound-styles/README.md
+++ /dev/null
@@ -1,36 +0,0 @@
-# Project sound Style: explicit crossfade
-
-This ordinary project package demonstrates `soundStyle(fragment, bindings)`. It publishes one
-`Crossfade` Style with explicit outgoing and incoming Segment inputs. It uses public
-`@hypit/hypit/*` imports and returns ordinary AudioTrack data. Copy it into a video's `packages/`,
-select the installed Hypit version as its development dependency, build it and declare it in the
-project's ordinary package configuration.
-
-```svml
-<import as="sound" from="@hypit/sound@1"/>
-<import as="mix" from="@example/sound-styles@1"/>
-<sound:Style id="normal"/>
-<mix:Crossfade id="handoff"
- outgoing={story.segment.first} incoming={story.segment.second}/>
-<sound:Track id="voice" timeline={program.timeline}>
- <sound:Use style={normal}/>
- <sound:Use style={handoff}
- start-source={story.segment.second} start="segment.start"
- end-source={story.segment.first} end="segment.end"/>
-</sound:Track>
-```
-
-The Window describes an actual overlap, even though its endpoints are reversed in Script order.
-The two Style inputs declare roles; temporal endpoints do not infer them. Outgoing gain decreases
-from 1 to 0 and incoming gain increases from 0 to 1 across that Window. Playback stays at each
-Take's existing source position. A known source with no audio contributes nothing; an unknown source
-is an error. Both roles must name distinct Segments.
-
-Linear crossfade is this family's chosen behavior, not a universal acoustic rule. A different
-project family can use another envelope or more sources without changing Timeline or the renderer.
-For intentional simultaneous speech, a family can return both explicit `sourceSound` results at
-unity gain. Independently included Sound Tracks can also coexist.
-
-The implementation is in [render.ts](src/render.ts); [activation.ts](src/activation.ts) declares the
-Surface, typed inputs, fragment and Producer. Build with `pnpm --filter @example/sound-styles build`
-inside this repository after public declarations are available.
diff --git a/examples/semantic-composition/packages/sound-styles/package.json b/examples/semantic-composition/packages/sound-styles/package.json
deleted file mode 100644
index 66c3c125..00000000
--- a/examples/semantic-composition/packages/sound-styles/package.json
+++ /dev/null
@@ -1,25 +0,0 @@
-{
- "name": "@example/sound-styles",
- "version": "0.0.0-dev",
- "private": true,
- "type": "module",
- "hypit": {
- "activation": "./dist/activation.js"
- },
- "exports": {
- ".": "./dist/render.js"
- },
- "files": [
- "dist",
- "README.md"
- ],
- "scripts": {
- "build": "tsc -p tsconfig.json",
- "prepack": "npm run build"
- },
- "devDependencies": {
- "@hypit/hypit": "workspace:*",
- "typescript": "5.9.3",
- "@types/node": "24.10.1"
- }
-}
diff --git a/examples/semantic-composition/packages/sound-styles/src/activation.ts b/examples/semantic-composition/packages/sound-styles/src/activation.ts
deleted file mode 100644
index f4f23250..00000000
--- a/examples/semantic-composition/packages/sound-styles/src/activation.ts
+++ /dev/null
@@ -1,53 +0,0 @@
-import { assertAttributes, assertEmptyElement, canonicalize, createMarkupSurfaceHostFacet, sameType, sealGraphFragment, textAttribute } from "@hypit/hypit/author-kit";
-import type { ComponentPackage, ModuleManifest, StructuredSurfaceHandler, SurfaceResolvedReference } from "@hypit/hypit/author-kit";
-import { compositionTypes } from "@hypit/hypit/composition";
-import { soundStyle, soundTypes, soundModuleRef } from "@hypit/hypit/sound";
-import { timelineTypes } from "@hypit/hypit/timeline";
-import type { Timeline } from "@hypit/hypit/timeline";
-import { temporalTypes } from "@hypit/hypit/temporal";
-import type { TemporalWindow } from "@hypit/hypit/temporal";
-import { narrativeTypes } from "@hypit/hypit/narrative";
-import type { NarrativeExcerpt } from "@hypit/hypit/narrative";
-import { crossfadeSound } from "./render.js";
-
-const module = { name: "@example/sound-styles", version: "1" } as const;
-const common = [{ name: "timeline", type: timelineTypes.track }, { name: "window", type: temporalTypes.window }];
-const mixInputs = [...common, { name: "outgoing", type: narrativeTypes.excerpt }, { name: "incoming", type: narrativeTypes.excerpt }];
-const families = [{ name: "crossfade", tag: "Crossfade", ports: mixInputs }];
-export const manifest: ModuleManifest = { format: "hypit.module@1", ...module,
- dependencies: [soundModuleRef, compositionTypes.audioTrack.module, timelineTypes.track.module, temporalTypes.window.module, narrativeTypes.excerpt.module].map(module => ({ module })),
- types: [], capabilities: [], producers: families.map(family => ({ name: family.name, inputs: family.ports, outputs: [{ name: "audio", type: compositionTypes.audioTrack }], needs: [] })) };
-const fragments = families.map(family => sealGraphFragment({ inputs: family.ports,
- operations: [{ id: "render", producer: { module, name: family.name }, inputs: Object.fromEntries(family.ports.map(port => [port.name, { kind: "fragment-input" as const, name: port.name }])), result: { kind: "output", name: "audio" } }],
- exports: [{ name: "audio", type: compositionTypes.audioTrack, root: { kind: "fragment-operation", operation: "render" } }] }));
-const component: ComponentPackage = { producers: families.map(family => ({ producer: { module, name: family.name }, handler: ({ inputs }) => {
- const values = Object.fromEntries(Object.entries(inputs).map(([key, record]) => {
- if (record.value.kind !== "inline") throw new Error(`${key} must be inline`);
- return [key, record.value.value];
- }));
- const audio = crossfadeSound(values.timeline as unknown as Timeline, values.window as unknown as TemporalWindow,
- values.outgoing as unknown as NarrativeExcerpt, values.incoming as unknown as NarrativeExcerpt);
- return { outputs: { audio: { kind: "inline", value: canonicalize(audio) } }, needs: {} };
-} })) };
-const hostFacets = families.map((family,index) => {
- const params = family.ports.slice(common.length);
- const handler: StructuredSurfaceHandler = ({ element, resolveReference }) => {
- assertAttributes(element, ["id", ...params.map(port => port.name)]); assertEmptyElement(element);
- const bindings: Record<string, SurfaceResolvedReference> = {};
- for (const param of params) {
- const raw = element.attributes[param.name];
- if (typeof raw !== "object" || raw.kind !== "reference") throw new Error(`${param.name} must be a reference`);
- const value = resolveReference(raw.path);
- if (value === undefined || !sameType(value.type,param.type)) throw new Error(`${param.name} has the wrong Type`);
- bindings[param.name] = value;
- }
- return { records: [{ id: textAttribute(element,"id"), type: soundTypes.style,
- value: { kind: "inline", value: canonicalize(soundStyle(fragments[index]!,bindings)) }, range: element.range }], components: [], fragments: [] };
- };
- return createMarkupSurfaceHostFacet({ module, declaration: { name: family.name, tag: family.tag, mode: "structured", outputs: [soundTypes.style], vocabulary: {
- summary: `Project-owned ${family.name} presentation Style.`, example: `<styles:${family.tag} id="look" ${params.map(port => `${port.name}={${port.name}}`).join(' ')}/>`,
- attributes: [{ name: "id", kind: "identifier", required: true, summary: "Style identity." }, ...params.map(port => ({ name: port.name, kind: "reference" as const, required: true, accepts: [port.type], summary: `Explicit ${port.name} input.` }))],
- } }, handler });
-});
-export const hypitPackage = { format: "hypit.node-package@1" as const, modules: [{ manifest }], components: [component], hostFacets };
-export default hypitPackage;
diff --git a/examples/semantic-composition/packages/sound-styles/src/render.ts b/examples/semantic-composition/packages/sound-styles/src/render.ts
deleted file mode 100644
index b7ca0bc7..00000000
--- a/examples/semantic-composition/packages/sound-styles/src/render.ts
+++ /dev/null
@@ -1,14 +0,0 @@
-import { sealAudioTrack } from "@hypit/hypit/composition";
-import { sourceSound } from "@hypit/hypit/sound";
-import type { Timeline } from "@hypit/hypit/timeline";
-import type { TemporalWindow } from "@hypit/hypit/temporal";
-import type { NarrativeExcerpt } from "@hypit/hypit/narrative";
-
-/** The family explicitly chooses the two roles; the Window only controls the blend progress. */
-export function crossfadeSound(timeline: Timeline, window: TemporalWindow,
- outgoing: NarrativeExcerpt, incoming: NarrativeExcerpt) {
- if (outgoing.id === incoming.id && outgoing.narrativeId === incoming.narrativeId) throw new Error("Crossfade needs two distinct sources.");
- const left = sourceSound(timeline, window, outgoing, { gain: 1, endGain: 0 });
- const right = sourceSound(timeline, window, incoming, { gain: 0, endGain: 1 });
- return sealAudioTrack({ id: window.subjectId, programSpaceId: timeline.id, clips: [...left.clips, ...right.clips] });
-}
diff --git a/examples/semantic-composition/packages/sound-styles/tsconfig.json b/examples/semantic-composition/packages/sound-styles/tsconfig.json
deleted file mode 100644
index 6d5a18e7..00000000
--- a/examples/semantic-composition/packages/sound-styles/tsconfig.json
+++ /dev/null
@@ -1,18 +0,0 @@
-{
- "compilerOptions": {
- "target": "ES2023",
- "module": "NodeNext",
- "moduleResolution": "NodeNext",
- "lib": ["ES2023"],
- "strict": true,
- "noUncheckedIndexedAccess": true,
- "exactOptionalPropertyTypes": true,
- "verbatimModuleSyntax": true,
- "declaration": true,
- "sourceMap": true,
- "rootDir": "src",
- "outDir": "dist",
- "skipLibCheck": true
- },
- "include": ["src/**/*.ts"]
-}
diff --git a/package.json b/package.json
index 8e69580b..87555237 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
{
"name": "@hypit/hypit",
- "version": "0.2.17",
+ "version": "0.3.0",
"homepage": "https://hypit.ai",
"repository": {
"type": "git",
@@ -50,9 +50,13 @@
"types": "./dist/public/narrative.d.ts",
"import": "./packages/narrative/src/index.ts"
},
- "./program-space": {
- "types": "./dist/public/program-space.d.ts",
- "import": "./packages/program-space/src/index.ts"
+ "./narrative-caption": {
+ "types": "./dist/public/narrative-caption.d.ts",
+ "import": "./packages/narrative-caption/src/index.ts"
+ },
+ "./narrative-temporal": {
+ "types": "./dist/public/narrative-temporal.d.ts",
+ "import": "./packages/narrative-temporal/src/index.ts"
},
"./runtime-kit": {
"types": "./dist/public/runtime-kit.d.ts",
@@ -66,10 +70,22 @@
"types": "./dist/public/spatial.d.ts",
"import": "./packages/spatial/src/index.ts"
},
+ "./region-track": {
+ "types": "./dist/public/region-track.d.ts",
+ "import": "./packages/region-track/src/index.ts"
+ },
"./speech": {
"types": "./dist/public/speech.d.ts",
"import": "./packages/speech/src/index.ts"
},
+ "./speech-evidence": {
+ "types": "./dist/public/speech-evidence.d.ts",
+ "import": "./packages/speech-evidence/src/index.ts"
+ },
+ "./speech-alignment": {
+ "types": "./dist/public/speech-alignment.d.ts",
+ "import": "./packages/speech-alignment/src/index.ts"
+ },
"./studio-adapter": {
"types": "./dist/public/studio-adapter.d.ts",
"import": "./packages/studio-adapter/src/index.ts"
@@ -98,13 +114,13 @@
"types": "./dist/public/hyperframes.d.ts",
"import": "./packages/hyperframes/src/index.ts"
},
- "./performance": {
- "types": "./dist/public/performance.d.ts",
- "import": "./packages/performance/src/index.ts"
+ "./visual-track": {
+ "types": "./dist/public/visual-track.d.ts",
+ "import": "./packages/visual-track/src/index.ts"
},
- "./sound": {
- "types": "./dist/public/sound.d.ts",
- "import": "./packages/sound/src/index.ts"
+ "./audio-track": {
+ "types": "./dist/public/audio-track.d.ts",
+ "import": "./packages/audio-track/src/index.ts"
}
},
"bin": {
@@ -206,8 +222,8 @@
"@hypit/credential-store-file": "workspace:*",
"@hypit/credential-store-os": "workspace:*",
"@hypit/credential-store-platform": "workspace:*",
- "@hypit/deck-track": "workspace:*",
- "@hypit/deck-track-studio": "workspace:*",
+ "@hypit/depth-stack": "workspace:*",
+ "@hypit/depth-stack-studio": "workspace:*",
"@hypit/elevenlabs-speech": "workspace:*",
"@hypit/estimate": "workspace:*",
"@hypit/film": "workspace:*",
@@ -224,16 +240,15 @@
"@hypit/interview-emoji-reveal": "workspace:*",
"@hypit/media": "workspace:*",
"@hypit/media-pipeline": "workspace:*",
- "@hypit/media-track": "workspace:*",
- "@hypit/media-track-studio": "workspace:*",
+ "@hypit/visual-track": "workspace:*",
+ "@hypit/visual-track-studio": "workspace:*",
"@hypit/mimo-speech": "workspace:*",
"@hypit/minimax-h3": "workspace:*",
"@hypit/nano-banana": "workspace:*",
"@hypit/narrative": "workspace:*",
- "@hypit/performance": "workspace:*",
- "@hypit/performance-studio": "workspace:*",
+ "@hypit/narrative-caption": "workspace:*",
+ "@hypit/narrative-temporal": "workspace:*",
"@hypit/pixverse": "workspace:*",
- "@hypit/program-space": "workspace:*",
"@hypit/project-context-node": "workspace:*",
"@hypit/protocol": "workspace:*",
"@hypit/provider-beatapi": "workspace:*",
@@ -248,6 +263,7 @@
"@hypit/provider-whisperx-local": "workspace:*",
"@hypit/ranking": "workspace:*",
"@hypit/ranking-studio": "workspace:*",
+ "@hypit/region-track": "workspace:*",
"@hypit/raster": "workspace:*",
"@hypit/render-hyperframes": "workspace:*",
"@hypit/resource-store-fs": "workspace:*",
@@ -263,8 +279,6 @@
"@hypit/seedance": "workspace:*",
"@hypit/seedance-kits": "workspace:*",
"@hypit/seedream": "workspace:*",
- "@hypit/sound": "workspace:*",
- "@hypit/sound-studio": "workspace:*",
"@hypit/spatial": "workspace:*",
"@hypit/speech": "workspace:*",
"@hypit/speech-alignment": "workspace:*",
@@ -277,8 +291,8 @@
"@hypit/text": "workspace:*",
"@hypit/timeline": "workspace:*",
"@hypit/timeline-author": "workspace:*",
- "@hypit/typography-track": "workspace:*",
- "@hypit/typography-track-studio": "workspace:*",
+ "@hypit/text-fine": "workspace:*",
+ "@hypit/text-fine-studio": "workspace:*",
"@hypit/visual-ir": "workspace:*",
"@hypit/volcengine-matting": "workspace:*",
"@hypit/wan": "workspace:*",
diff --git a/packages/audio-track-studio/README.md b/packages/audio-track-studio/README.md
index c13735fb..dc718649 100644
--- a/packages/audio-track-studio/README.md
+++ b/packages/audio-track-studio/README.md
@@ -2,25 +2,22 @@
Hypit Studio Companion for `@hypit/audio-track`. The domain package does not depend on this package.
-Each Item has a title and waveform body. An explicit author `id` supplies its
+Each Clip has a title and waveform body. An explicit author `id` supplies its
title; otherwise the Companion displays the exact `source` reference. Display
-names do not replace the Item's identity or writeback endpoint. This is the same
-rule as Media Items. For example, `id="soundtrack" source={music.media}` shows
+names do not replace the Clip's identity or writeback endpoint. This is the same
+rule as Visual Clips. For example, `id="soundtrack" source={music.media}` shows
`soundtrack`; omitting the id shows `music.media`. Here `.media` is the source
output port, not an Audio-specific name suffix.
-When groups placement, source trim, playback rates and fades. How contains gain.
-Gain displays as a percentage (0–6400%) and writes back as a scalar; duration controls preserve their authored `f`, `ms` or `s` unit.
-Omitted gain and fade defaults remain editable; the first edit writes an explicit
-attribute. Playback uses the standard parameter controls and saves when editing ends. Stretch also
-asks for minimum and maximum rate multipliers (1 means original speed). Switching
-to once/loop removes these bounds in the same edit. The Surface retains final
-validation of positive, ordered rates. No arbitrary bounds are supplied for the author.
+When contains the absolute Clip Window and its target-relative fades. How contains gain.
+Gain displays as a percentage (0–6400%) and writes back as a scalar; duration controls preserve
+their authored `f`, `ms` or `s` unit. Omitted gain and fade defaults remain editable; the first edit
+writes an explicit attribute.
-The Companion declares a schema-described `attributes` group. Studio provides
-record alternatives, completion hints and grouped source serialization without knowing
-any Audio mode names.
+Source-time is a separate structural binding. It can be omitted for bounded partial identity or
+authored as one or more `Map` relations, but the Companion does not pretend an arbitrary piecewise
+function is one editable playback-mode dropdown. Final validation and lowering remain owned by
+Audio Track.
-Selecting an overlapping Item raises it in the editing lane while all sounds
-continue to mix. Timing gestures use the same temporal projection bindings as
-Media Track.
+Selecting an overlapping Clip raises it in the editing lane while all sounds
+continue to mix. Timing gestures follow the same absolute temporal bindings as Visual Track.
diff --git a/packages/audio-track-studio/package.json b/packages/audio-track-studio/package.json
index e1a8190a..70b73154 100644
--- a/packages/audio-track-studio/package.json
+++ b/packages/audio-track-studio/package.json
@@ -9,6 +9,7 @@
"dependencies": {
"@hypit/audio-track": "workspace:*",
"@hypit/composition": "workspace:*",
- "@hypit/studio-adapter": "workspace:*"
+ "@hypit/studio-adapter": "workspace:*",
+ "@hypit/temporal": "workspace:*"
}
}
diff --git a/packages/audio-track-studio/src/activation.ts b/packages/audio-track-studio/src/activation.ts
index 62605d0c..b3274618 100644
--- a/packages/audio-track-studio/src/activation.ts
+++ b/packages/audio-track-studio/src/activation.ts
@@ -1,7 +1,10 @@
-import { createStudioTrackCompanionHostFacet } from "@hypit/studio-adapter";
-import { audioTrackStudioTrackCompanions } from "./index.js";
+import { createStudioCompanionHostFacet } from "@hypit/studio-adapter";
+import { audioTrackStudioParameterCompanions, audioTrackStudioTrackCompanions } from "./index.js";
export default {
format: "hypit.node-package@1" as const,
- hostFacets: [createStudioTrackCompanionHostFacet(audioTrackStudioTrackCompanions)],
+ hostFacets: [createStudioCompanionHostFacet({
+ tracks: audioTrackStudioTrackCompanions,
+ parameters: audioTrackStudioParameterCompanions,
+ })],
};
diff --git a/packages/audio-track-studio/src/index.ts b/packages/audio-track-studio/src/index.ts
index 22a90c30..273c9486 100644
--- a/packages/audio-track-studio/src/index.ts
+++ b/packages/audio-track-studio/src/index.ts
@@ -1,86 +1,82 @@
-import { audioItemDefaults, audioTrackModuleRef, audioTrackTypes } from "@hypit/audio-track";
+import { audioClipDefaults, audioTrackModuleRef, audioTrackTypes } from "@hypit/audio-track";
import type { AudioTrackProgram } from "@hypit/audio-track";
import { compositionTypes } from "@hypit/composition";
-import type { StudioTrackCompanion, StudioTrackCompanionContext, StudioEntityDraft } from "@hypit/studio-adapter";
-import { artifactPreview, authoredItemTitle, childEntities, previewLayer, requiredSurfaceValue, temporalLineageFor, temporalSemanticSource } from "@hypit/studio-adapter";
+import type { StudioTrackCompanion, StudioTrackCompanionContext } from "@hypit/studio-adapter";
+import {
+ artifactPreview,
+ authoredItemTitle,
+ childEntities,
+ previewLayer,
+ requiredSurfaceValue,
+ temporalLineageFor,
+ temporalSemanticSource,
+} from "@hypit/studio-adapter";
-function projectAudio(context: StudioTrackCompanionContext): readonly StudioEntityDraft[] {
+function projectAudio(context: StudioTrackCompanionContext) {
const program = requiredSurfaceValue(context, "program") as AudioTrackProgram;
- const items = program.items.map((item) => ({
- id: item.id,
- subjectId: item.subjectId,
- startFrame: item.window.startFrame,
- endFrameExclusive: item.window.endFrameExclusive,
+ const clips = program.clips.map((clip) => ({
+ id: clip.id,
+ subjectId: clip.subjectId,
+ startFrame: clip.window.startFrame,
+ endFrameExclusive: clip.window.endFrameExclusive,
stackOrder: Number.MIN_SAFE_INTEGER,
sourceTypes: [audioTrackTypes.clipSpec],
- preview: artifactPreview("audio", item.source.artifact.resource),
+ preview: artifactPreview("audio", clip.source.artifact.resource),
}));
- return childEntities(context, items, "audio-clip", "standard").map((entity, index) => {
- const item = items[index]!;
- const temporal = temporalLineageFor(context, item.id, "window");
+ return childEntities(context, clips, "audio-clip", "standard").map((entity, index) => {
+ const clip = clips[index]!;
+ const temporal = temporalLineageFor(context, clip.id, "window");
const semanticSource = temporalSemanticSource(temporal);
return {
...entity,
display: {
- title: authoredItemTitle(context, entity.authoredId, item.sourceTypes, ["source"]),
- layers: [previewLayer(item.preview, "waveform")],
+ title: authoredItemTitle(context, entity.authoredId, clip.sourceTypes, ["source"]),
+ layers: [previewLayer(clip.preview, "waveform")],
},
- ...(semanticSource?.id === undefined
- ? {}
- : { markerId: semanticSource.id }),
+ ...(semanticSource?.id === undefined ? {} : { markerId: semanticSource.id }),
...(temporal === undefined ? {} : { temporal }),
};
});
}
-export const audioTrackStudioTrackCompanions: readonly StudioTrackCompanion[] = [
- {
- id: "track", role: "track",
- output: { type: compositionTypes.audioTrack, surface: "track", modules: [audioTrackModuleRef] },
- family: "audio", tone: "green", icon: "waveform",
- bindings: [
- { name: "source" },
- { name: "trim-start", writable: true },
- { name: "trim-end", writable: true },
- { name: "playback-settings", writable: true,
- attributes: ["playback", "min-rate", "max-rate"],
- fallback: { playback: audioItemDefaults.playback },
- schema: { kind: "oneOf", variants: ["once", "once-start", "once-end", "loop", "loop-start", "loop-end", "stretch"].map(mode => ({
- kind: "object", fields: {
- playback: { schema: { kind: "literal", value: mode } },
- ...(mode === "stretch" ? {
- "min-rate": { schema: { kind: "number", minimum: 0, maximum: 100 } },
- "max-rate": { schema: { kind: "number", minimum: 0, maximum: 100 } },
- } : {}),
- },
- })) },
- },
- { name: "gain", writable: true, fallback: audioItemDefaults.gain },
- { name: "fade-in", writable: true, fallback: audioItemDefaults["fade-in"] },
- { name: "fade-out", writable: true, fallback: audioItemDefaults["fade-out"] },
- ],
- inspector: [
- {
- binding: "playback-settings", label: "Playback", domain: "when",
- page: { id: "playback", label: "Playback" }, section: { id: "playback", label: "Playback" },
- control: "record",
- summary: "Rates are multipliers (1 = original speed). Stretch requires both rate bounds.",
- },
- ...(["trim-start", "trim-end"] as const).map((binding) => ({
- binding, label: binding === "trim-start" ? "Trim Start" : "Trim End", domain: "when" as const,
- page: { id: "playback", label: "Playback" }, section: { id: "trim", label: "Trim" }, control: "number" as const,
- number: { suffixes: ["ms", "s", "f"], minimum: 0 },
- })),
- { binding: "gain", label: "Gain", domain: "how",
- page: { id: "mix", label: "Mix" }, section: { id: "mix", label: "Mix" },
- control: "number", unit: "%", number: { scale: 100, minimum: 0, maximum: 6400, step: 1 } },
- ...(["fade-in", "fade-out"] as const).map((binding) => ({
- binding, label: binding === "fade-in" ? "Fade In" : "Fade Out", domain: "when" as const,
- page: { id: "fade", label: "Fade" }, section: { id: "fade", label: "Fade" }, control: "number" as const,
- number: { suffixes: ["ms", "s", "f"], minimum: 0 },
- })),
- ],
- requiredValues: ["program"], project: projectAudio,
- lane: { heightPx: 48 },
- },
-];
+export const audioTrackStudioTrackCompanions: readonly StudioTrackCompanion[] = [{
+ id: "track",
+ role: "track",
+ output: { type: compositionTypes.audioTrack, surface: "track", modules: [audioTrackModuleRef] },
+ family: "audio",
+ tone: "green",
+ icon: "waveform",
+ bindings: [
+ { name: "source" },
+ { name: "source-time" },
+ { name: "gain", writable: true, fallback: audioClipDefaults.gain },
+ { name: "fade-in", writable: true, fallback: audioClipDefaults["fade-in"] },
+ { name: "fade-out", writable: true, fallback: audioClipDefaults["fade-out"] },
+ ],
+ inspector: [
+ {
+ binding: "gain",
+ label: "Gain",
+ domain: "how",
+ page: { id: "mix", label: "Mix" },
+ section: { id: "mix", label: "Mix" },
+ control: "number",
+ unit: "%",
+ number: { scale: 100, minimum: 0, maximum: 6400, step: 1 },
+ },
+ ...(["fade-in", "fade-out"] as const).map((binding) => ({
+ binding,
+ label: binding === "fade-in" ? "Fade In" : "Fade Out",
+ domain: "when" as const,
+ page: { id: "fade", label: "Fade" },
+ section: { id: "fade", label: "Fade" },
+ control: "number" as const,
+ number: { suffixes: ["ms", "s", "f"], minimum: 0 },
+ })),
+ ],
+ requiredValues: ["program"],
+ project: projectAudio,
+ lane: { heightPx: 48 },
+}];
+
+export const audioTrackStudioParameterCompanions = [];
diff --git a/packages/audio-track/README.md b/packages/audio-track/README.md
index d2c39750..436ac0e1 100644
--- a/packages/audio-track/README.md
+++ b/packages/audio-track/README.md
@@ -1,50 +1,53 @@
# `@hypit/audio-track`
-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.
+Audio Track is the plain sound-placement package:
-Place music, ambience and sound effects in the assembled video. A reveal sound can follow a Script
-Moment; music can occupy a Segment or the program; an explicitly timed sound can use clock placement.
-Performance audio is presented by [Sound](../sound/README.md) from the assembled Timeline and can continue
-under these independent sounds and [Media Track](../media-track/README.md) coverage.
-
-Each Item consumes normalized audio-bearing media and a projected Window. Gain, fades, trim and
-playback express the mix. Normalization preserves the source level; choose the balance and any
-music ducking for the actual performance. The resulting `.audio` is a peer AudioTrack in Film.
-
-## Authoring items
+```text
+Audio Clip = normalized audio source + absolute Window + sampling + mix
+Audio Track = additive set of Audio Clips
+```
-The Markup Track selects `timeline`; its Fragment receives the same Timeline.
-Each Item accepts one shared temporal Window form: `during="program"`, a Selection or Segment,
-a Moment paired with `for`, or explicit `start`/`end` expressions. The source must already contain
-normalized audio. This excerpt assumes imports, Script, Timeline, Clock and source media exist:
+Timeline supplies the program clock, not hidden audio. Each Clip names its own normalized source and
+destination Window. The Track publishes `.program` for declared tooling and `.audio` as an ordinary
+peer contribution to Film.
```svml
-<pipeline:Normalize id="hit-media" source={hit-source}
- video="none" audio="default" span-authority="audio" clock={clock}/>
-<audio:Track id="effects" timeline={speech.timeline}>
- <audio:Item source={hit-media.media} at={story.moment.reveal} for="600ms"
- playback="once" gain="0.45" fade-in="0f" fade-out="3f"/>
+<audio:Track id="mix" timeline={program.timeline}>
+ <audio:Clip id="voice" source={speaker-media.media} during={program.speaker}/>
+ <audio:Clip id="music" source={music-media.media} during="timeline"
+ gain="0.18" fade-in="12f" fade-out="18f">
+ <audio:Map target-at="end" source-at="end" rate="1"
+ wrap-from="start" wrap-until="end"/>
+ </audio:Clip>
+ <audio:Clip id="reveal-hit" source={hit-media.media}
+ from={story-time.reveal} for="600ms" gain="0.45"/>
</audio:Track>
```
-The Track publishes `.program` and `.audio`; include the latter as a peer Film Track. `gain` is a
-linear multiplier, defaulting to `1`; fade durations default to `0f`. Trim boundaries are source
-durations (`f`, integer `ms`, or fractional `s`), distinct from the Item's destination Window.
-`trim-end` is the exclusive source endpoint, not an amount to subtract from the tail. For example,
-`trim-start="1s" trim-end="3s"` selects the source interval from one to three seconds.
-
-`once` / `once-start` plays once from the Window start; `once-end` aligns to its end. `loop` /
-`loop-start` and `loop-end` repeat with the corresponding alignment. `stretch` preserves pitch and
-requires authored `min-rate` and `max-rate` bounds. Other playback modes reject those rate bounds.
-Choose occupancy from the intended sound; the Track does not silently loop music or stretch a hit
-to fill a longer Window. Its source level is retained unless gain or another explicit audio operation
-changes it.
-
-Media Track and Audio Track both place independent Items on the same Timeline.
-Overlapping pictures compose by draw order; overlapping sounds mix together.
-Give an Item an `id` when it needs a recognizable author name. Studio otherwise
-displays its source reference; the generated internal identity still owns
-selection and writeback. Reusing a source in two Items keeps two independent
-placements, even when their displayed names match.
+`during` consumes a resolved Window or the whole Timeline. The alternative absolute form supplies
+exactly two of `from`, `until` and `for`. Semantic, beat or other domain coordinates are projected to
+Instants/Windows upstream; Audio Track does not recognize those domains.
+
+`gain` is a linear multiplier and fades default to zero. Omitting Map means bounded partial identity:
+target start maps to source start at native rate, and excess Window time is silent. One `Map` relates
+target and source intervals through an exact positive rate; `wrap-from`/`wrap-until` makes a selected
+source interval periodic. A Map without rate, anchors or wrap fits its source interval across its
+target interval while preserving pitch; optional `min-rate`/`max-rate` bounds make that fit fail
+instead of silently exceeding an authored safety range. Multiple non-overlapping Maps form one
+partial function, and gaps are silence.
+
+Audio deliberately does not inherit visual-only laws such as a zero-rate held frame or reverse
+picture sampling. It owns positive, pitch-preserving tempo mapping in the same small algebraic shape,
+without placing an audiovisual policy in Core.
+
+Speech, music, ambience and effects are equal Audio Clips. A source that helped determine Timeline
+duration or anchors leaves no special marker in the audio-placement path. Reusing one normalized
+source in two Clips creates two independent occurrences.
+
+Audio Track has no generic `Presentation`, `Style` or `Use`. Ducking, crossfades, continuing speaker
+roles and other relationships spanning multiple Clips are ordinary components. They may calculate
+level automation—gain envelopes and audibility regions—and publish a normal terminal `AudioTrack`;
+the base package and Core do not acquire a catalogue of sound roles or effects.
+
+Using synchronized media here does not make its picture visible. Author picture independently with
+[`@hypit/visual-track`](../visual-track/README.md).
diff --git a/packages/audio-track/package.json b/packages/audio-track/package.json
index 09d1b7d6..f8130b02 100644
--- a/packages/audio-track/package.json
+++ b/packages/audio-track/package.json
@@ -15,8 +15,6 @@
"@hypit/composition": "workspace:*",
"@hypit/elaborator": "workspace:*",
"@hypit/media": "workspace:*",
- "@hypit/narrative": "workspace:*",
- "@hypit/program-space": "workspace:*",
"@hypit/protocol": "workspace:*",
"@hypit/timeline": "workspace:*",
"@hypit/temporal": "workspace:*",
diff --git a/packages/audio-track/src/activation.ts b/packages/audio-track/src/activation.ts
index 693684b5..a111f816 100644
--- a/packages/audio-track/src/activation.ts
+++ b/packages/audio-track/src/activation.ts
@@ -4,6 +4,7 @@ import {
audioTrackManifest,
audioTrackModuleRef,
decodeAudioTrackSurface,
+ decodeAudioSourceTimeSurface,
audioTrackMarkupSurfaces,
} from "./index.js";
@@ -11,10 +12,17 @@ export const hypitPackage = {
format: "hypit.node-package@1" as const,
modules: [{ manifest: audioTrackManifest }],
components: [audioTrackComponent],
- hostFacets: [createMarkupSurfaceHostFacet({
- module: audioTrackModuleRef,
- declaration: audioTrackMarkupSurfaces.find((item) => item.name === "track")!,
- handler: decodeAudioTrackSurface,
- })],
+ hostFacets: [
+ createMarkupSurfaceHostFacet({
+ module: audioTrackModuleRef,
+ declaration: audioTrackMarkupSurfaces.find((item) => item.name === "track")!,
+ handler: decodeAudioTrackSurface,
+ }),
+ createMarkupSurfaceHostFacet({
+ module: audioTrackModuleRef,
+ declaration: audioTrackMarkupSurfaces.find((item) => item.name === "source-time")!,
+ handler: decodeAudioSourceTimeSurface,
+ }),
+ ],
};
export default hypitPackage;
diff --git a/packages/audio-track/src/component.ts b/packages/audio-track/src/component.ts
index bb2db021..573c9949 100644
--- a/packages/audio-track/src/component.ts
+++ b/packages/audio-track/src/component.ts
@@ -3,11 +3,17 @@ import type { ComponentPackage } from "@hypit/component-kit";
import type { SynchronizedMedia } from "@hypit/media";
import { canonicalize } from "@hypit/protocol";
import type { StoredValue } from "@hypit/protocol";
+import type { TemporalWindow } from "@hypit/temporal";
import { audioTrackProducers, audioTrackTypes } from "./manifest.js";
-import { appendProjectedAudioItem, assertAudioTrackProgram, createAudioTrackSet, finalizeAudioTrack, renderAudioTrack } from "./program.js";
+import {
+ appendAudioClip,
+ assertAudioTrackProgram,
+ createAudioTrackSet,
+ finalizeAudioTrack,
+ renderAudioTrack,
+} from "./program.js";
import type { AudioClipSpec, AudioTrackHeader, AudioTrackProgram, AudioTrackSet } from "./types.js";
-import type { TemporalWindow } from "@hypit/temporal";
function inline<T>(value: StoredValue | undefined, label: string): T {
if (value?.kind !== "inline") throw new Error(`${label} must be inline.`);
@@ -15,22 +21,26 @@ function inline<T>(value: StoredValue | undefined, label: string): T {
}
const output = (value: unknown) => ({ kind: "inline" as const, value: canonicalize(value) });
-const base = (inputs: [AudioTrackSet, AudioTrackHeader, Timeline, SynchronizedMedia, AudioClipSpec, TemporalWindow]) => output(appendProjectedAudioItem(...inputs));
-
export const audioTrackComponent = {
producers: [
{ producer: audioTrackProducers.createSet, handler: () => ({ outputs: { set: output(createAudioTrackSet()) }, needs: {} }) },
- { producer: audioTrackProducers.appendItem, handler: ({ inputs }) => ({ outputs: { set: base([
- inline<AudioTrackSet>(inputs.set?.value, "AudioTrackSet"), inline<AudioTrackHeader>(inputs.header?.value, "AudioTrackHeader"),
- inline<Timeline>(inputs.timeline?.value, "Timeline"), inline<SynchronizedMedia>(inputs.media?.value, "SynchronizedMedia"),
- inline<AudioClipSpec>(inputs.spec?.value, "AudioClipSpec"),
- inline<TemporalWindow>(inputs.window?.value, "TemporalWindow"),
- ]) }, needs: {} }) },
+ { producer: audioTrackProducers.appendClip, handler: ({ inputs }) => ({ outputs: { set: output(
+ appendAudioClip(
+ inline<AudioTrackSet>(inputs.set?.value, "AudioTrackSet"),
+ inline<AudioTrackHeader>(inputs.header?.value, "AudioTrackHeader"),
+ inline<Timeline>(inputs.timeline?.value, "Timeline"),
+ inline<SynchronizedMedia>(inputs.media?.value, "SynchronizedMedia"),
+ inline<AudioClipSpec>(inputs.spec?.value, "AudioClipSpec"),
+ inline<TemporalWindow>(inputs.window?.value, "TemporalWindow"),
+ ),
+ ) }, needs: {} }) },
{ producer: audioTrackProducers.finalize, handler: ({ inputs }) => ({ outputs: { program: output(finalizeAudioTrack(
- inline<AudioTrackSet>(inputs.set?.value, "AudioTrackSet"), inline<AudioTrackHeader>(inputs.header?.value, "AudioTrackHeader"),
+ inline<AudioTrackSet>(inputs.set?.value, "AudioTrackSet"),
+ inline<AudioTrackHeader>(inputs.header?.value, "AudioTrackHeader"),
)) }, needs: {} }) },
{ producer: audioTrackProducers.render, handler: ({ inputs }) => ({ outputs: { track: output(renderAudioTrack(
- inline<Timeline>(inputs.timeline?.value, "Timeline"), inline<AudioTrackProgram>(inputs.program?.value, "AudioTrackProgram"),
+ inline<Timeline>(inputs.timeline?.value, "Timeline"),
+ inline<AudioTrackProgram>(inputs.program?.value, "AudioTrackProgram"),
)) }, needs: {} }) },
],
validators: [{
diff --git a/packages/audio-track/src/fragment.ts b/packages/audio-track/src/fragment.ts
index fb71107a..2f2b33db 100644
--- a/packages/audio-track/src/fragment.ts
+++ b/packages/audio-track/src/fragment.ts
@@ -17,25 +17,25 @@ export type AudioTrackFragmentItem = {
const input = (name: string) => ({ kind: "fragment-input" as const, name });
const operation = (id: string) => ({ kind: "fragment-operation" as const, operation: id });
-export function createAudioTrackFragment(items: readonly AudioTrackFragmentItem[]) {
- if (items.length === 0) throw new Error("Audio Track Fragment requires at least one Item.");
+export function createAudioTrackFragment(clips: readonly AudioTrackFragmentItem[]) {
+ if (clips.length === 0) throw new Error("Audio Track Fragment requires at least one Clip.");
const inputTypes = new Map<string, (typeof audioTrackTypes.clipSpec | typeof mediaTypes.synchronized | typeof temporalTypes.window)>();
const operations: FragmentOperation[] = [
{ id: "audio:set:empty", producer: audioTrackProducers.createSet, inputs: {}, result: { kind: "output", name: "set" } },
];
let current = "audio:set:empty";
- items.forEach((item, index) => {
- inputTypes.set(item.mediaName, mediaTypes.synchronized);
- inputTypes.set(item.specName, audioTrackTypes.clipSpec);
- inputTypes.set(item.windowName, temporalTypes.window);
+ clips.forEach((clip, index) => {
+ inputTypes.set(clip.mediaName, mediaTypes.synchronized);
+ inputTypes.set(clip.specName, audioTrackTypes.clipSpec);
+ inputTypes.set(clip.windowName, temporalTypes.window);
const id = `audio:set:append:${String(index + 1).padStart(4, "0")}`;
operations.push({
id,
- producer: audioTrackProducers.appendItem,
+ producer: audioTrackProducers.appendClip,
inputs: {
set: operation(current), header: input("header"), timeline: input("timeline"),
- media: input(item.mediaName), spec: input(item.specName),
- window: input(item.windowName),
+ media: input(clip.mediaName), spec: input(clip.specName),
+ window: input(clip.windowName),
},
result: { kind: "output", name: "set" },
});
diff --git a/packages/audio-track/src/index.ts b/packages/audio-track/src/index.ts
index 690f48bf..1d0e22de 100644
--- a/packages/audio-track/src/index.ts
+++ b/packages/audio-track/src/index.ts
@@ -1,7 +1,8 @@
export { audioTrackComponent } from "./component.js";
export { createAudioTrackFragment, programAudioTrackFragment } from "./fragment.js";
export type { AudioTrackFragmentItem } from "./fragment.js";
-export { audioClipSpecSchema, audioTrackDependency, audioTrackHeaderSchema, audioTrackManifest, audioTrackMarkupSurfaces, audioTrackModuleRef, audioTrackProducers, audioTrackProgramSchema, audioTrackSetSchema, audioTrackTypes } from "./manifest.js";
-export { decodeAudioTrackSurface, audioItemDefaults } from "./surface.js";
-export { appendProjectedAudioItem, assertAudioClipSpec, assertAudioTrackHeader, assertAudioTrackProgram, assertAudioTrackSet, createAudioTrackSet, finalizeAudioTrack, renderAudioTrack, sealAudioClipSpec, sealAudioTrackHeader, sealAudioTrackProgram } from "./program.js";
+export { audioClipSpecSchema, audioSourceTimeSchema, audioTrackDependency, audioTrackHeaderSchema, audioTrackManifest, audioTrackMarkupSurfaces, audioTrackModuleRef, audioTrackProducers, audioTrackProgramSchema, audioTrackSetSchema, audioTrackTypes } from "./manifest.js";
+export { decodeAudioSourceTimeRelation, decodeAudioSourceTimeSurface, decodeAudioTrackSurface, audioClipDefaults } from "./surface.js";
+export { appendAudioClip, assertAudioClipSpec, assertAudioTrackHeader, assertAudioTrackProgram, assertAudioTrackSet, createAudioTrackSet, finalizeAudioTrack, renderAudioTrack, sealAudioClipSpec, sealAudioTrackHeader, sealAudioTrackProgram } from "./program.js";
+export { assertAudioSourceTimeSpec, defaultAudioSourceTimeSpec, resolveAudioSourceTime } from "./source-time.js";
export type * from "./types.js";
diff --git a/packages/audio-track/src/manifest.ts b/packages/audio-track/src/manifest.ts
index 08197648..f2c57d10 100644
--- a/packages/audio-track/src/manifest.ts
+++ b/packages/audio-track/src/manifest.ts
@@ -1,25 +1,26 @@
-import { timelineTypes } from "@hypit/timeline";
-import { temporalContextAttributeVocabulary } from "@hypit/temporal-markup";
import { compositionDependency, compositionTypes } from "@hypit/composition";
import { mediaDependency, mediaTypes } from "@hypit/media";
-import { narrativeDependency } from "@hypit/narrative";
-
import { blobRefObjectSchema } from "@hypit/protocol";
import type { ModuleManifest, ProducerRef, TypeRef, ValueSchema } from "@hypit/protocol";
-import { timelineDependency } from "@hypit/timeline";
import { temporalDependency, temporalTypes } from "@hypit/temporal";
-import { temporalWindowAttributeVocabulary } from "@hypit/temporal-markup";
+import {
+ temporalContextAttributeVocabulary,
+ temporalWindowAttributeVocabulary,
+} from "@hypit/temporal-markup";
+import { timelineDependency, timelineTypes } from "@hypit/timeline";
export const audioTrackModuleRef = { name: "@hypit/audio-track", version: "1" } as const;
export const audioTrackTypes = {
header: { module: audioTrackModuleRef, name: "AudioTrackHeader" },
+ sourceTime: { module: audioTrackModuleRef, name: "AudioSourceTime" },
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" },
+ appendClip: { module: audioTrackModuleRef, name: "append-audio-clip" },
finalize: { module: audioTrackModuleRef, name: "finalize-audio-track" },
render: { module: audioTrackModuleRef, name: "render-audio-track" },
} satisfies Record<string, ProducerRef>;
@@ -27,116 +28,130 @@ export const audioTrackProducers = {
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 sourceTimePoint = object({ edge: { schema: { kind: "string", enum: ["start", "end"] } }, offset: { schema: duration } });
+const sourceTimeBounds = object({ from: { schema: sourceTimePoint }, until: { schema: sourceTimePoint } });
+const rational = object({ numerator: { schema: { kind: "number", integer: true, minimum: 1 } }, denominator: { schema: { kind: "number", integer: true, minimum: 1 } } });
+const sourceTimeRelation: ValueSchema = { kind: "oneOf", variants: [
+ object({ kind: { schema: { kind: "literal", value: "rate" } }, target: { schema: sourceTimeBounds },
+ targetAt: { schema: sourceTimePoint }, sourceAt: { schema: sourceTimePoint }, rate: { schema: rational },
+ source: { schema: sourceTimeBounds }, wrap: { schema: sourceTimeBounds, optional: true } }),
+ object({ kind: { schema: { kind: "literal", value: "fit" } }, target: { schema: sourceTimeBounds },
+ source: { schema: sourceTimeBounds }, minRate: { schema: number, optional: true }, maxRate: { schema: number, optional: true } }),
] };
+const sourceTime = object({ relations: { schema: { kind: "array", minItems: 1, items: sourceTimeRelation } } });
const clipSpec = object({
-
id: { schema: string },
- trim: { schema: object({ start: { schema: duration, optional: true }, end: { schema: duration, optional: true } }) },
- occupancy: { schema: occupancy },
+ sourceTime: { schema: sourceTime, optional: true },
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({
+const clip = 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 },
+ sourceTime: { schema: sourceTime },
mix: { schema: object({ gain: { schema: number }, fadeInSamples: { schema: integer }, fadeOutSamples: { schema: integer } }) },
});
-export const audioTrackHeaderSchema: ValueSchema = object({
- id: { schema: string },
-});
+
+export const audioTrackHeaderSchema: ValueSchema = object({ id: { schema: string } });
+export const audioSourceTimeSchema: ValueSchema = sourceTime;
export const audioClipSpecSchema: ValueSchema = clipSpec;
-export const audioTrackSetSchema: ValueSchema = object({
- items: { schema: { kind: "array", items: item } },
-});
+export const audioTrackSetSchema: ValueSchema = object({ clips: { schema: { kind: "array", items: clip } } });
export const audioTrackProgramSchema: ValueSchema = object({
id: { schema: string },
- items: { schema: { kind: "array", minItems: 1, items: item } },
+ clips: { schema: { kind: "array", minItems: 1, items: clip } },
});
-const baseInputs = [
+const clipInputs = [
{ name: "set", type: audioTrackTypes.set }, { name: "header", type: audioTrackTypes.header },
{ name: "timeline", type: timelineTypes.track }, { 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 Items placed on the selected film time axis and lowered to one ordinary peer AudioTrack.",
+ name: "track", tag: "Track", mode: "structured",
+ outputs: [audioTrackTypes.header, audioTrackTypes.sourceTime, audioTrackTypes.clipSpec,
+ temporalTypes.duration, temporalTypes.extent, temporalTypes.shiftSpec, temporalTypes.instantSpec,
+ temporalTypes.windowSpec, temporalTypes.instant, temporalTypes.window,
+ audioTrackTypes.program, compositionTypes.audioTrack],
+ vocabulary: {
+ summary: "Places ordinary audio Clips on one completed Timeline and mixes them into one AudioTrack.",
+ attributes: [
+ { name: "id", kind: "identifier", required: true, summary: "Names this Audio Track and prefixes unnamed Clips." },
+ ...temporalContextAttributeVocabulary,
+ ],
+ children: [{
+ tag: "Clip", cardinality: "many",
+ summary: "One explicit audio source occurrence with its own Window, partial source-time relation and mix.",
attributes: [
- { name: "id", kind: "identifier", required: true, summary: "Names this Audio Track and prefixes the identity of every Item that does not name itself." },
- ...temporalContextAttributeVocabulary,
- ],
- children: [
- { tag: "Item", 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 Item; the Track derives `<track>.item.<index>` when it is absent." },
- { name: "source", kind: "reference", required: true,
- accepts: [mediaTypes.synchronized],
- summary: "Selects the explicitly prepared audio this Item 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 Item 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: "audio", type: compositionTypes.audioTrack, summary: "The rendered AudioTrack that Film composes with its peers." },
+ { name: "id", kind: "identifier", required: false, summary: "Names this Clip; the Track derives `<track>.clip.<index>` when absent." },
+ { name: "source", kind: "reference", required: true, accepts: [mediaTypes.synchronized], summary: "Selects normalized media containing the audio stream." },
+ { name: "source-time", kind: "reference", required: false, accepts: [audioTrackTypes.sourceTime], summary: "Applies one reusable partial source-time relation. Inline Map children express the same value." },
+ ...temporalWindowAttributeVocabulary,
+ { name: "gain", kind: "literal", required: false, summary: "Linear gain; defaults to `1`." },
+ { name: "fade-in", kind: "literal", required: false, summary: "Exact fade-in length; defaults to `0f`." },
+ { name: "fade-out", kind: "literal", required: false, summary: "Exact fade-out length; defaults to `0f`." },
],
- example: `<audio:Track id="music-bed" timeline={speech.timeline}>
- <audio:Item source={music-media.media} during="program"
- playback="loop-end" gain="0.28" fade-in="600ms" fade-out="800ms"/>
+ }],
+ ports: [
+ { name: "program", type: audioTrackTypes.program, summary: "Resolved authored Clips for Studio and declared consumers." },
+ { name: "audio", type: compositionTypes.audioTrack, summary: "The AudioTrack Film composes with peer contributions." },
+ ],
+ example: `<audio:Track id="mix" timeline={program.timeline}>
+ <audio:Clip source={voice-media.media} during={program.voice}/>
+ <audio:Clip source={music-media.media} during="timeline" gain="0.18">
+ <audio:Map rate="1" wrap-from="start" wrap-until="end"/>
+ </audio:Clip>
</audio:Track>`,
- notes: [
- "A Track requires at least one Item, and neither a Track nor a Item accepts text content.",
- "A Item 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;
-
+ notes: [
+ "A Track requires at least one Clip and accepts no text content.",
+ "A Clip states one Window form: `during`, or exactly two of `from`, `until` and `for`.",
+ "Project semantic, beat or other domain time upstream, then pass resolved Windows or Instants here.",
+ "Omitting Map means bounded partial identity; uncovered target samples are silent.",
+ ],
+ },
+}, {
+ name: "source-time", tag: "SourceTime", mode: "structured",
+ outputs: [audioTrackTypes.sourceTime],
+ vocabulary: {
+ summary: "Authors one reusable partial relation from Clip-local target samples to source-local samples.",
+ attributes: [{ name: "id", kind: "identifier", required: true, summary: "Names this AudioSourceTime value." }],
+ children: [{ tag: "Map", cardinality: "many", summary: "One affine piece; uncovered target samples are silent.", attributes: [
+ { name: "target-from", kind: "literal", required: false, summary: "Starts the target interval; defaults to start." },
+ { name: "target-until", kind: "literal", required: false, summary: "Ends the target interval exclusively; defaults to end." },
+ { name: "target-at", kind: "literal", required: false, summary: "Names the target anchor paired with source-at." },
+ { name: "source-at", kind: "literal", required: false, summary: "Names the source anchor paired with target-at." },
+ { name: "rate", kind: "literal", required: false, summary: "Exact positive source samples per target sample; pitch is preserved." },
+ { name: "source-from", kind: "literal", required: false, summary: "Starts the permitted or fitted source interval." },
+ { name: "source-until", kind: "literal", required: false, summary: "Ends the permitted or fitted source interval exclusively." },
+ { name: "wrap-from", kind: "literal", required: false, summary: "Starts an explicitly periodic source interval." },
+ { name: "wrap-until", kind: "literal", required: false, summary: "Ends an explicitly periodic source interval exclusively." },
+ { name: "min-rate", kind: "literal", required: false, summary: "Optional lower safety bound for a fitted Map." },
+ { name: "max-rate", kind: "literal", required: false, summary: "Optional upper safety bound for a fitted Map." },
+ ] }],
+ example: `<audio:SourceTime id="native-loop">
+ <audio:Map rate="1" wrap-from="start" wrap-until="end"/>
+</audio:SourceTime>`,
+ notes: [
+ "Without rate, anchors or wrap, a Map fits the selected source interval across its target interval.",
+ "Audio rates are positive and pitch-preserving; silence is represented by an uncovered target interval.",
+ ],
+ },
+}] as const;
export const audioTrackManifest: ModuleManifest = {
format: "hypit.module@1",
name: audioTrackModuleRef.name,
version: audioTrackModuleRef.version,
- dependencies: [mediaDependency, narrativeDependency, timelineDependency, temporalDependency, compositionDependency],
+ dependencies: [mediaDependency, timelineDependency, temporalDependency, compositionDependency],
types: [
{ name: audioTrackTypes.header.name },
+ { name: audioTrackTypes.sourceTime.name },
{ name: audioTrackTypes.clipSpec.name },
{ name: audioTrackTypes.set.name },
{ name: audioTrackTypes.program.name },
@@ -144,9 +159,10 @@ export const audioTrackManifest: ModuleManifest = {
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.appendClip.name, inputs: [...clipInputs], 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: "timeline", type: timelineTypes.track }, { name: "program", type: audioTrackTypes.program }], outputs: [{ name: "track", type: compositionTypes.audioTrack }], needs: [] },
],
};
+
export const audioTrackDependency = { module: audioTrackModuleRef } as const;
diff --git a/packages/audio-track/src/program.ts b/packages/audio-track/src/program.ts
index fbb6f2eb..c6ea4cd1 100644
--- a/packages/audio-track/src/program.ts
+++ b/packages/audio-track/src/program.ts
@@ -1,21 +1,21 @@
+import { assertTimelineIdentity, timelineFrameSampleBoundary, timelineSampleFrames } from "@hypit/timeline";
import type { Timeline } from "@hypit/timeline";
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 { canonicalize, isResourceId } from "@hypit/protocol";
import { assertTemporalWindowFor, temporalDurationInSamples } from "@hypit/temporal";
-import type { ProjectedWindow, TemporalDuration } from "@hypit/temporal";
+import type { TemporalWindow, TemporalDuration } from "@hypit/temporal";
import type {
AudioClipSpec,
- AudioItemProgram,
- AudioOccupancy,
+ AudioClipProgram,
AudioTrackHeader,
AudioTrackProgram,
AudioTrackSet,
} from "./types.js";
+import { assertAudioSourceTimeSpec, defaultAudioSourceTimeSpec, resolveAudioSourceTime } from "./source-time.js";
function assert(condition: unknown, message: string): asserts condition {
if (!condition) throw new Error(message);
@@ -34,17 +34,6 @@ function assertDuration(value: TemporalDuration, label: string, signed = false):
}
}
-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;
@@ -61,9 +50,7 @@ export function sealAudioClipSpec(value: AudioClipSpec): 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");
+ if (value.sourceTime !== undefined) assertAudioSourceTimeSpec(value.sourceTime, "AudioClipSpec.sourceTime");
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");
@@ -71,14 +58,14 @@ export function assertAudioClipSpec(value: AudioClipSpec): void {
}
export function createAudioTrackSet(): AudioTrackSet {
- return { items: [] };
+ return { clips: [] };
}
export function assertAudioTrackSet(value: AudioTrackSet): void {
- assert(Array.isArray(value.items), "AudioTrackSet is invalid.");
+ assert(Array.isArray(value.clips), "AudioTrackSet is invalid.");
}
-function sourceFacts(media: SynchronizedMedia): AudioItemProgram["source"] {
+function sourceFacts(media: SynchronizedMedia): AudioClipProgram["source"] {
verifySynchronizedMedia(media);
assert(media.audio !== undefined, "Audio Track source has no explicitly normalized audio member.");
return {
@@ -87,24 +74,20 @@ function sourceFacts(media: SynchronizedMedia): AudioItemProgram["source"] {
};
}
-function realizedItems(
+function realizedClips(
set: AudioTrackSet,
header: AudioTrackHeader,
timeline: Timeline,
media: SynchronizedMedia,
spec: AudioClipSpec,
- window: ProjectedWindow,
+ window: TemporalWindow,
): AudioTrackSet {
assertAudioTrackSet(set);
assertAudioTrackHeader(header);
- assertProgramSpaceIdentity(timeline);
+ assertTimelineIdentity(timeline);
assertAudioClipSpec(spec);
- assertTemporalWindowFor(window, { subjectId: spec.id, space: timeline });
+ assertTemporalWindowFor(window, { subjectId: spec.id, timeline: timeline });
const source = sourceFacts(media);
- const trimStart = spec.trim.start === undefined ? 0 : temporalDurationInSamples(spec.trim.start, timeline);
- const trimEnd = spec.trim.end === undefined ? source.sampleFrames : temporalDurationInSamples(spec.trim.end, timeline);
- 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, timeline);
const fadeOutSamples = temporalDurationInSamples(spec.mix.fadeOut, timeline);
const addition = {
@@ -112,32 +95,31 @@ function realizedItems(
subjectId: spec.id,
window: { ...window.span },
source: structuredClone(source),
- trim: { startSample: trimStart, endSampleExclusive: trimEnd },
- occupancy: structuredClone(spec.occupancy),
+ sourceTime: structuredClone(spec.sourceTime ?? defaultAudioSourceTimeSpec()),
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] };
+ } satisfies AudioClipProgram;
+ const ids = new Set(set.clips.map((clip) => clip.id));
+ assert(!ids.has(addition.id), `Audio Track ${header.id} already contains Clip ${addition.id}.`);
+ return { clips: [...set.clips, addition] };
}
/** Component entry point: the Temporal module has already resolved the target window. */
-export function appendProjectedAudioItem(
+export function appendAudioClip(
set: AudioTrackSet,
header: AudioTrackHeader,
timeline: Timeline,
media: SynchronizedMedia,
spec: AudioClipSpec,
- window: ProjectedWindow,
+ window: TemporalWindow,
): AudioTrackSet {
- return realizedItems(set, header, timeline, media, spec, window);
+ return realizedClips(set, header, timeline, 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)),
+ clips: [...value.clips].map((clip) => structuredClone(clip)).sort((left, right) => left.id.localeCompare(right.id)),
};
}
@@ -150,97 +132,64 @@ export function sealAudioTrackProgram(value: AudioTrackProgram): AudioTrackProgr
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 });
+ assert(set.clips.length > 0, "Audio Track requires at least one Clip.");
+ return sealAudioTrackProgram({ id: header.id, clips: set.clips });
}
export function assertAudioTrackProgram(value: AudioTrackProgram): void {
assertIdentity(value.id, "AudioTrackProgram.id");
- assert(value.items.length > 0, "AudioTrackProgram requires at least one Item.");
+ assert(value.clips.length > 0, "AudioTrackProgram requires at least one Clip.");
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.`);
+ for (const clip of value.clips) {
+ assertIdentity(clip.id, "AudioClipProgram.id");
+ assertIdentity(clip.subjectId, "AudioClipProgram.subjectId");
+ assert(!ids.has(clip.id), `AudioTrackProgram contains duplicate Clip ${clip.id}.`);
+ ids.add(clip.id);
+ assert(Number.isSafeInteger(clip.window.startFrame) && clip.window.startFrame >= 0
+ && Number.isSafeInteger(clip.window.endFrameExclusive)
+ && clip.window.endFrameExclusive > clip.window.startFrame, `Audio Clip ${clip.id} window is invalid.`);
+ assert(isResourceId(clip.source.artifact.resource) && clip.source.artifact.mediaType === "audio/wav"
+ && Number.isSafeInteger(clip.source.sampleFrames) && clip.source.sampleFrames > 0,
+ `Audio Clip ${clip.id} source is invalid.`);
+ assertAudioSourceTimeSpec(clip.sourceTime, `Audio Clip ${clip.id} source time`);
+ assert(Number.isFinite(clip.mix.gain) && clip.mix.gain >= 0 && clip.mix.gain <= 64
+ && Number.isSafeInteger(clip.mix.fadeInSamples) && clip.mix.fadeInSamples >= 0
+ && Number.isSafeInteger(clip.mix.fadeOutSamples) && clip.mix.fadeOutSamples >= 0,
+ `Audio Clip ${clip.id} mix is invalid.`);
}
}
-function terminalClip(item: AudioItemProgram, timeline: Timeline): AudioClip {
- const windowStart = programFrameSampleBoundary(timeline, item.window.startFrame, 48_000);
- const windowEnd = programFrameSampleBoundary(timeline, item.window.endFrameExclusive, 48_000);
+function terminalClip(clip: AudioClipProgram, timeline: Timeline): AudioClip {
+ const windowStart = timelineFrameSampleBoundary(timeline, clip.window.startFrame, 48_000);
+ const windowEnd = timelineFrameSampleBoundary(timeline, clip.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.`);
+ assert(clip.mix.fadeInSamples <= windowLength && clip.mix.fadeOutSamples <= windowLength,
+ `Audio Clip ${clip.id} fade exceeds its Window.`);
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,
+ id: clip.id,
+ subjectId: clip.subjectId,
+ artifact: structuredClone(clip.source.artifact),
+ target: { startSample: windowStart, endSampleExclusive: windowEnd },
+ sourceTime: resolveAudioSourceTime({
+ timeline,
+ sourceSampleFrames: clip.source.sampleFrames,
+ targetSampleFrames: windowLength,
+ spec: clip.sourceTime,
+ }),
+ gain: clip.mix.gain,
+ fadeInSamples: clip.mix.fadeInSamples,
+ fadeOutSamples: clip.mix.fadeOutSamples,
};
}
export function renderAudioTrack(timeline: Timeline, program: AudioTrackProgram): AudioTrack {
- assertProgramSpaceIdentity(timeline);
+ assertTimelineIdentity(timeline);
assertAudioTrackProgram(program);
- const totalSamples = programSpaceSampleFrames(timeline, 48_000);
+ const totalSamples = timelineSampleFrames(timeline, 48_000);
const track = sealAudioTrack({
- programSpaceId: timeline.id,
+ timelineId: timeline.id,
id: program.id,
- clips: program.items.map((item) => terminalClip(item, timeline)),
+ clips: program.clips.map((clip) => terminalClip(clip, timeline)),
});
for (const clip of track.clips) {
assert(clip.target.endSampleExclusive <= totalSamples, `Audio Clip ${clip.id} is outside Timeline.`);
diff --git a/packages/audio-track/src/source-time.ts b/packages/audio-track/src/source-time.ts
new file mode 100644
index 00000000..6b9e6653
--- /dev/null
+++ b/packages/audio-track/src/source-time.ts
@@ -0,0 +1,201 @@
+import type {
+ AudioSourceTimeMap,
+ AudioSourceTimePiece,
+ AudioSourceTimeRational,
+} from "@hypit/composition";
+import { temporalDurationInSamples } from "@hypit/temporal";
+import type { Timeline } from "@hypit/timeline";
+
+import type {
+ AudioSourceTimeBounds,
+ AudioSourceTimePoint,
+ AudioSourceTimeRelation,
+ AudioSourceTimeSpec,
+} from "./types.js";
+
+function assert(condition: unknown, message: string): asserts condition {
+ if (!condition) throw new Error(message);
+}
+
+function gcd(left: bigint, right: bigint): bigint {
+ let a = left < 0n ? -left : left;
+ let b = right < 0n ? -right : right;
+ while (b !== 0n) [a, b] = [b, a % b];
+ return a;
+}
+
+function rational(numerator: bigint, denominator = 1n): AudioSourceTimeRational {
+ assert(denominator > 0n, "Audio source-time rational is invalid.");
+ const divisor = gcd(numerator, denominator);
+ const n = numerator / divisor;
+ const d = denominator / divisor;
+ assert(n <= BigInt(Number.MAX_SAFE_INTEGER) && d <= BigInt(Number.MAX_SAFE_INTEGER),
+ "Audio source-time rational exceeds safe wire arithmetic.");
+ return { numerator: Number(n), denominator: Number(d) };
+}
+
+const ZERO = { unit: "frames", value: 0 } as const;
+const START: AudioSourceTimePoint = { edge: "start", offset: ZERO };
+const END: AudioSourceTimePoint = { edge: "end", offset: ZERO };
+const FULL: AudioSourceTimeBounds = { from: START, until: END };
+
+export function defaultAudioSourceTimeSpec(): AudioSourceTimeSpec {
+ return { relations: [{
+ kind: "rate",
+ target: FULL,
+ targetAt: START,
+ sourceAt: START,
+ rate: { numerator: 1, denominator: 1 },
+ source: FULL,
+ }] };
+}
+
+function assertPoint(value: AudioSourceTimePoint, label: string): void {
+ assert(value.edge === "start" || value.edge === "end", `${label}.edge is invalid.`);
+ if (value.offset.unit === "seconds") {
+ assert(Number.isSafeInteger(value.offset.numerator) && value.offset.numerator >= 0
+ && Number.isSafeInteger(value.offset.denominator) && value.offset.denominator > 0, `${label}.offset is invalid.`);
+ } else {
+ assert(Number.isSafeInteger(value.offset.value) && value.offset.value >= 0, `${label}.offset is invalid.`);
+ }
+}
+
+function assertBounds(value: AudioSourceTimeBounds, label: string): void {
+ assertPoint(value.from, `${label}.from`);
+ assertPoint(value.until, `${label}.until`);
+}
+
+export function assertAudioSourceTimeSpec(value: AudioSourceTimeSpec, label = "AudioSourceTimeSpec"): void {
+ assert(Array.isArray(value.relations) && value.relations.length > 0, `${label} requires at least one relation.`);
+ for (const [index, relation] of value.relations.entries()) {
+ const item = `${label}.relations.${index}`;
+ assertBounds(relation.target, `${item}.target`);
+ assertBounds(relation.source, `${item}.source`);
+ if (relation.kind === "fit") {
+ assert(relation.minRate === undefined || Number.isFinite(relation.minRate) && relation.minRate > 0,
+ `${item}.minRate is invalid.`);
+ assert(relation.maxRate === undefined || Number.isFinite(relation.maxRate) && relation.maxRate > 0,
+ `${item}.maxRate is invalid.`);
+ assert(relation.minRate === undefined || relation.maxRate === undefined || relation.maxRate >= relation.minRate,
+ `${item} rate bounds are reversed.`);
+ continue;
+ }
+ assert(relation.kind === "rate", `${item}.kind is invalid.`);
+ assertPoint(relation.targetAt, `${item}.targetAt`);
+ assertPoint(relation.sourceAt, `${item}.sourceAt`);
+ assert(Number.isSafeInteger(relation.rate.numerator) && relation.rate.numerator > 0
+ && Number.isSafeInteger(relation.rate.denominator) && relation.rate.denominator > 0,
+ `${item}.rate is invalid.`);
+ if (relation.wrap !== undefined) assertBounds(relation.wrap, `${item}.wrap`);
+ }
+}
+
+function point(value: AudioSourceTimePoint, length: number, timeline: Timeline, label: string): number {
+ const offset = temporalDurationInSamples(value.offset, timeline);
+ const result = value.edge === "start" ? offset : length - offset;
+ assert(Number.isSafeInteger(result) && result >= 0 && result <= length, `${label} is outside its domain.`);
+ return result;
+}
+
+function bounds(value: AudioSourceTimeBounds, length: number, timeline: Timeline, label: string) {
+ const startSample = point(value.from, length, timeline, `${label}.from`);
+ const endSampleExclusive = point(value.until, length, timeline, `${label}.until`);
+ assert(endSampleExclusive > startSample, `${label} is empty or reversed.`);
+ return { startSample, endSampleExclusive };
+}
+
+function sourceAt(sourceAnchor: number, targetAnchor: number, rate: AudioSourceTimeRational, target: number) {
+ return rational(BigInt(sourceAnchor) * BigInt(rate.denominator)
+ + BigInt(target - targetAnchor) * BigInt(rate.numerator), BigInt(rate.denominator));
+}
+
+function compare(value: AudioSourceTimeRational, integer: number): number {
+ const difference = BigInt(value.numerator) - BigInt(integer) * BigInt(value.denominator);
+ return difference < 0n ? -1 : difference > 0n ? 1 : 0;
+}
+
+function firstTrue(from: number, until: number, predicate: (value: number) => boolean): number {
+ let left = from;
+ let right = until;
+ while (left < right) {
+ const middle = left + Math.floor((right - left) / 2);
+ if (predicate(middle)) right = middle;
+ else left = middle + 1;
+ }
+ return left;
+}
+
+function resolveRate(
+ relation: Extract<AudioSourceTimeRelation, { readonly kind: "rate" }>,
+ targetLength: number,
+ sourceLength: number,
+ timeline: Timeline,
+ label: string,
+): AudioSourceTimePiece {
+ const authoredTarget = bounds(relation.target, targetLength, timeline, `${label}.target`);
+ const permittedSource = bounds(relation.source, sourceLength, timeline, `${label}.source`);
+ const targetAnchor = point(relation.targetAt, targetLength, timeline, `${label}.targetAt`);
+ const sourceAnchor = point(relation.sourceAt, sourceLength, timeline, `${label}.sourceAt`);
+ const wrap = relation.wrap === undefined ? undefined : bounds(relation.wrap, sourceLength, timeline, `${label}.wrap`);
+ let target = authoredTarget;
+ if (wrap === undefined) {
+ const at = (sample: number) => sourceAt(sourceAnchor, targetAnchor, relation.rate, sample);
+ const startSample = firstTrue(target.startSample, target.endSampleExclusive,
+ (sample) => compare(at(sample), permittedSource.startSample) >= 0);
+ const endSampleExclusive = firstTrue(startSample, target.endSampleExclusive,
+ (sample) => compare(at(sample), permittedSource.endSampleExclusive) >= 0);
+ assert(endSampleExclusive > startSample, `${label} does not sample any source audio.`);
+ target = { startSample, endSampleExclusive };
+ }
+ const rawStart = sourceAt(sourceAnchor, targetAnchor, relation.rate, target.startSample);
+ let sourceAtStart = rawStart;
+ if (wrap !== undefined) {
+ assert(rawStart.denominator === 1, `${label} periodic phase must resolve to an exact source sample.`);
+ const length = wrap.endSampleExclusive - wrap.startSample;
+ sourceAtStart = rational(BigInt(wrap.startSample + ((rawStart.numerator - wrap.startSample) % length + length) % length));
+ }
+ return {
+ target,
+ sourceAtStart,
+ rate: { ...relation.rate },
+ ...(wrap === undefined ? {} : { wrap }),
+ };
+}
+
+function resolveRelation(relation: AudioSourceTimeRelation, targetLength: number, sourceLength: number,
+ timeline: Timeline, label: string): AudioSourceTimePiece {
+ if (relation.kind === "rate") return resolveRate(relation, targetLength, sourceLength, timeline, label);
+ const target = bounds(relation.target, targetLength, timeline, `${label}.target`);
+ const source = bounds(relation.source, sourceLength, timeline, `${label}.source`);
+ const rate = rational(BigInt(source.endSampleExclusive - source.startSample),
+ BigInt(target.endSampleExclusive - target.startSample));
+ const numericRate = rate.numerator / rate.denominator;
+ assert(relation.minRate === undefined || numericRate >= relation.minRate,
+ `${label} requires rate ${numericRate}, below authored minimum ${relation.minRate}.`);
+ assert(relation.maxRate === undefined || numericRate <= relation.maxRate,
+ `${label} requires rate ${numericRate}, above authored maximum ${relation.maxRate}.`);
+ return { target, sourceAtStart: rational(BigInt(source.startSample)), rate };
+}
+
+export function resolveAudioSourceTime(input: {
+ readonly timeline: Timeline;
+ readonly sourceSampleFrames: number;
+ readonly targetSampleFrames: number;
+ readonly spec?: AudioSourceTimeSpec;
+}): AudioSourceTimeMap {
+ assert(Number.isSafeInteger(input.sourceSampleFrames) && input.sourceSampleFrames > 0,
+ "Audio source sample count is invalid.");
+ assert(Number.isSafeInteger(input.targetSampleFrames) && input.targetSampleFrames > 0,
+ "Audio target sample count is invalid.");
+ const spec = input.spec ?? defaultAudioSourceTimeSpec();
+ assertAudioSourceTimeSpec(spec);
+ const pieces = spec.relations.map((relation, index) => resolveRelation(relation,
+ input.targetSampleFrames, input.sourceSampleFrames, input.timeline, `AudioSourceTimeSpec.relations.${index}`))
+ .sort((left, right) => left.target.startSample - right.target.startSample);
+ let previousEnd = 0;
+ for (const [index, piece] of pieces.entries()) {
+ assert(piece.target.startSample >= previousEnd, `Audio source-time pieces ${index - 1} and ${index} overlap.`);
+ previousEnd = piece.target.endSampleExclusive;
+ }
+ return { sourceSampleFrames: input.sourceSampleFrames, pieces };
+}
diff --git a/packages/audio-track/src/surface.ts b/packages/audio-track/src/surface.ts
index c63af5d1..b1437929 100644
--- a/packages/audio-track/src/surface.ts
+++ b/packages/audio-track/src/surface.ts
@@ -1,20 +1,28 @@
-import { resolveTemporalContext } from "@hypit/temporal-markup";
import { mediaTypes } from "@hypit/media";
import type {
+ MarkupAttributeValue,
StructuredElement,
StructuredSurfaceHandler,
- SurfaceComponentDraft,
SurfaceRecordDraft,
SurfaceResolvedReference,
- MarkupAttributeValue,
} from "@hypit/markup";
import type { TemporalDuration } from "@hypit/temporal";
-import { createTemporalWindowProjection, temporalWindowAttributeNames } from "@hypit/temporal-markup";
+import {
+ createTemporalWindowConstruction,
+ resolveTemporalContext,
+ 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";
+import { assertAudioSourceTimeSpec } from "./source-time.js";
+import type {
+ AudioSourceTimeBounds,
+ AudioSourceTimePoint,
+ AudioSourceTimeRelation,
+ AudioSourceTimeSpec,
+} 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;
@@ -85,26 +93,119 @@ function numeric(element: StructuredElement, name: string, fallback?: number): n
return value;
}
-export const audioItemDefaults = { playback: "once", gain: 1, "fade-in": "0f", "fade-out": "0f" } as const;
-
-function occupancy(element: StructuredElement): AudioOccupancy {
- switch (text(element, "playback", audioItemDefaults.playback)) {
- 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 audioClipDefaults = { gain: 1, "fade-in": "0f", "fade-out": "0f" } as const;
+
+const MAP_ATTRIBUTES = [
+ "target-from", "target-until", "target-at", "source-at", "rate",
+ "source-from", "source-until", "wrap-from", "wrap-until", "min-rate", "max-rate",
+] as const;
+
+function sourceTimePoint(raw: string | undefined, fallback: "start" | "end", label: string): AudioSourceTimePoint {
+ const value = raw ?? fallback;
+ if (value === "start" || value === "end") return { edge: value, offset: duration("0f", label) };
+ const fromStart = /^(?:start\+)?(.+)$/u.exec(value);
+ if (fromStart !== null && !value.startsWith("end-")) {
+ return { edge: "start", offset: duration(fromStart[1]!, label) };
+ }
+ const fromEnd = /^end-(.+)$/u.exec(value);
+ if (fromEnd !== null) return { edge: "end", offset: duration(fromEnd[1]!, label) };
+ throw new Error(`${label} must be start, end, a duration from start, start+duration or end-duration.`);
+}
+
+function sourceTimeBounds(element: StructuredElement, prefix: "target" | "source" | "wrap", required = false): AudioSourceTimeBounds | undefined {
+ const from = optionalText(element, `${prefix}-from`);
+ const until = optionalText(element, `${prefix}-until`);
+ if (!required && from === undefined && until === undefined) return undefined;
+ return {
+ from: sourceTimePoint(from, "start", `${element.name}.${prefix}-from`),
+ until: sourceTimePoint(until, "end", `${element.name}.${prefix}-until`),
+ };
+}
+
+function rate(raw: string, label: string): { readonly numerator: number; readonly denominator: number } {
+ const fraction = /^(\d+)\/([1-9]\d*)$/u.exec(raw);
+ if (fraction !== null) {
+ const numerator = Number(fraction[1]);
+ const denominator = Number(fraction[2]);
+ if (!Number.isSafeInteger(numerator) || numerator <= 0 || !Number.isSafeInteger(denominator)) {
+ throw new Error(`${label} is outside safe arithmetic.`);
+ }
+ const common = divisor(numerator, denominator);
+ return { numerator: numerator / common, denominator: denominator / common };
+ }
+ const decimal = /^(\d+)(?:\.(\d+))?$/u.exec(raw);
+ if (decimal === null) throw new Error(`${label} must be an exact positive integer, decimal or fraction.`);
+ const fractional = decimal[2] ?? "";
+ const denominator = 10 ** fractional.length;
+ const numerator = Number(decimal[1]) * denominator + (fractional.length === 0 ? 0 : Number(fractional));
+ if (!Number.isSafeInteger(numerator) || numerator <= 0 || !Number.isSafeInteger(denominator)) {
+ throw new Error(`${label} is outside safe arithmetic.`);
}
+ const common = divisor(numerator, denominator);
+ return { numerator: numerator / common, denominator: denominator / common };
}
+export function decodeAudioSourceTimeRelation(element: StructuredElement): AudioSourceTimeRelation {
+ allowed(element, MAP_ATTRIBUTES);
+ if (element.children.some((child) => child.kind === "element" || child.value.trim())) throw new Error(`${element.name} must be empty.`);
+ const target = sourceTimeBounds(element, "target", true)!;
+ const source = sourceTimeBounds(element, "source", true)!;
+ const hasRate = element.attributes.rate !== undefined || element.attributes["target-at"] !== undefined
+ || element.attributes["source-at"] !== undefined || element.attributes["wrap-from"] !== undefined
+ || element.attributes["wrap-until"] !== undefined;
+ if (!hasRate) return {
+ kind: "fit", target, source,
+ ...(element.attributes["min-rate"] === undefined ? {} : { minRate: numeric(element, "min-rate") }),
+ ...(element.attributes["max-rate"] === undefined ? {} : { maxRate: numeric(element, "max-rate") }),
+ };
+ if (element.attributes["min-rate"] !== undefined || element.attributes["max-rate"] !== undefined) {
+ throw new Error(`${element.name} rate bounds belong to a fitted Map without rate, anchors or wrap.`);
+ }
+ const wrap = sourceTimeBounds(element, "wrap");
+ return {
+ kind: "rate",
+ target,
+ targetAt: sourceTimePoint(optionalText(element, "target-at"), "start", `${element.name}.target-at`),
+ sourceAt: sourceTimePoint(optionalText(element, "source-at"), "start", `${element.name}.source-at`),
+ rate: rate(optionalText(element, "rate") ?? "1", `${element.name}.rate`),
+ source,
+ ...(wrap === undefined ? {} : { wrap }),
+ };
+}
+
+function sourceTimeFrom(element: StructuredElement,
+ resolve: (path: string) => SurfaceResolvedReference | undefined): AudioSourceTimeSpec | undefined {
+ const relations = element.children.flatMap((child) => child.kind === "element"
+ && (child.name.endsWith(":Map") || child.name === "Map") ? [decodeAudioSourceTimeRelation(child)] : []);
+ const inline = relations.length === 0 ? undefined : { relations };
+ if (inline !== undefined) assertAudioSourceTimeSpec(inline);
+ if (element.attributes["source-time"] === undefined) return inline;
+ if (inline !== undefined) throw new Error(`${element.name} cannot combine source-time={AudioSourceTime} with inline Map children.`);
+ const value = resolved(element.attributes["source-time"], `${element.name}.source-time`, audioTrackTypes.sourceTime, resolve);
+ if (value.record?.value.kind !== "inline") throw new Error(`${element.name}.source-time must resolve to an inline value.`);
+ const spec = value.record.value.value as unknown as AudioSourceTimeSpec;
+ assertAudioSourceTimeSpec(spec);
+ return spec;
+}
+
+export const decodeAudioSourceTimeSurface: StructuredSurfaceHandler = ({ element }) => {
+ allowed(element, ["id"]);
+ const id = text(element, "id");
+ const relations: AudioSourceTimeRelation[] = [];
+ for (const child of element.children) {
+ if (child.kind === "text") {
+ if (child.value.trim()) throw new Error(`${element.name} accepts only Map children.`);
+ continue;
+ }
+ if (!child.name.endsWith(":Map") && child.name !== "Map") throw new Error(`${element.name} accepts only Map children.`);
+ relations.push(decodeAudioSourceTimeRelation(child));
+ }
+ const value = { relations };
+ assertAudioSourceTimeSpec(value);
+ return { records: [{ id, type: audioTrackTypes.sourceTime, value: { kind: "inline", value: value as never }, range: element.range }],
+ components: [], fragments: [], exports: [id] };
+};
+
export const decodeAudioTrackSurface: StructuredSurfaceHandler = ({ element, resolveReference }) => {
allowed(element, ["id", "timeline"]);
const id = text(element, "id");
@@ -116,73 +217,70 @@ export const decodeAudioTrackSurface: StructuredSurfaceHandler = ({ element, res
value: { kind: "inline", value: sealAudioTrackHeader({ id }) },
range: element.range,
}];
- const temporalComponents: SurfaceComponentDraft[] = [];
- const temporalFragments: ReturnType<typeof createTemporalWindowProjection>["fragments"][number][] = [];
- const fragmentItems: Parameters<typeof createAudioTrackFragment>[0][number][] = [];
- const inputs: Record<string, { kind: "record"; id: string } | { kind: "component-output"; component: string; output: string }> = {
+ const components = [] as ReturnType<typeof createTemporalWindowConstruction>["components"][number][];
+ const fragments = [] as ReturnType<typeof createTemporalWindowConstruction>["fragments"][number][];
+ const clips: Parameters<typeof createAudioTrackFragment>[0][number][] = [];
+ const inputs: Record<string, SurfaceResolvedReference["ref"] | { readonly kind: "record"; readonly id: string }> = {
header: { kind: "record", id: headerId },
timeline: context.timeline.ref,
};
- let itemIndex = 0;
+ let clipIndex = 0;
for (const child of element.children) {
if (child.kind === "text") {
- if (child.value.trim()) throw new Error(`${element.name} accepts only Item children.`);
+ if (child.value.trim()) throw new Error(`${element.name} accepts only Clip children.`);
continue;
}
- if (!child.name.endsWith(":Item") && child.name !== "Item") throw new Error(`${element.name} accepts only Item children.`);
- if (child.children.some((node) => node.kind === "element" || node.value.trim())) throw new Error(`${child.name} must be empty.`);
+ if (!child.name.endsWith(":Clip") && child.name !== "Clip") {
+ throw new Error(`${element.name} accepts only Clip children.`);
+ }
+ for (const node of child.children) {
+ if (node.kind === "text") {
+ if (node.value.trim()) throw new Error(`${child.name} accepts only Map children.`);
+ } else if (!node.name.endsWith(":Map") && node.name !== "Map") throw new Error(`${child.name} accepts only Map children.`);
+ }
allowed(child, [
- "id", "source", ...temporalWindowAttributeNames,
- "trim-start", "trim-end", "playback", "min-rate", "max-rate", "gain", "fade-in", "fade-out",
+ "id", "source", "source-time", ...temporalWindowAttributeNames, "gain", "fade-in", "fade-out",
]);
- itemIndex += 1;
- const suffix = String(itemIndex).padStart(4, "0");
- const clipId = optionalText(child, "id") ?? `${id}.item.${suffix}`;
+ clipIndex += 1;
+ const suffix = String(clipIndex).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, resolveReference });
+ const temporal = createTemporalWindowConstruction({ id: clipId, element: child, ...context, 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({
-
+ components.push(...temporal.components);
+ fragments.push(...temporal.fragments);
+ const sourceTime = sourceTimeFrom(child, resolveReference);
+ const spec = 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,
+ ...(sourceTime === undefined ? {} : { sourceTime }),
mix: {
- gain: numeric(child, "gain", audioItemDefaults.gain),
- fadeIn: duration(text(child, "fade-in", audioItemDefaults["fade-in"]), `${child.name}.fade-in`),
- fadeOut: duration(text(child, "fade-out", audioItemDefaults["fade-out"]), `${child.name}.fade-out`),
+ gain: numeric(child, "gain", audioClipDefaults.gain),
+ fadeIn: duration(text(child, "fade-in", audioClipDefaults["fade-in"]), `${child.name}.fade-in`),
+ fadeOut: duration(text(child, "fade-out", audioClipDefaults["fade-out"]), `${child.name}.fade-out`),
},
});
- const windowName = `item-${suffix}-window`;
+ const windowName = `clip-${suffix}-window`;
+ const mediaName = `clip-${suffix}-media`;
+ const specName = `clip-${suffix}-spec`;
+ const specId = `${id}.clip.${suffix}.spec`;
+ records.push({ id: specId, type: audioTrackTypes.clipSpec, value: { kind: "inline", value: spec }, range: child.range });
inputs[windowName] = temporal.ref;
- const mediaName = `item-${suffix}-media`;
- const specName = `item-${suffix}-spec`;
- const specId = `${id}.item.${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 });
+ clips.push({ mediaName, specName, windowName });
}
- if (fragmentItems.length === 0) throw new Error(`${element.name} requires at least one Item.`);
- const fragment = createAudioTrackFragment(fragmentItems);
+ if (clips.length === 0) throw new Error(`${element.name} requires at least one Clip.`);
+ const fragment = createAudioTrackFragment(clips);
return {
records,
- components: [...temporalComponents, {
+ components: [...components, {
id,
fragment: fragment.id,
inputs,
outputs: { program: `${id}.program`, audio: `${id}.audio` },
range: element.range,
}],
- fragments: [...temporalFragments, fragment],
- exports: [`${id}.program`, `${id}.audio`],
+ fragments: [...fragments, fragment],
+ exports: [`${id}.audio`, `${id}.program`],
};
};
diff --git a/packages/audio-track/src/types.ts b/packages/audio-track/src/types.ts
index 4650b858..4ddf5ae7 100644
--- a/packages/audio-track/src/types.ts
+++ b/packages/audio-track/src/types.ts
@@ -1,20 +1,44 @@
-import type { FrameSpan } from "@hypit/composition";
+import type { AudioSourceTimeMap, AudioSourceTimeRational, 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 AudioSourceTimePoint = {
+ readonly edge: "start" | "end";
+ /** Non-negative distance inward from the named edge. */
+ readonly offset: TemporalDuration;
+};
-export type AudioSourceTrim = {
- readonly start?: TemporalDuration;
- readonly end?: TemporalDuration;
+export type AudioSourceTimeBounds = {
+ readonly from: AudioSourceTimePoint;
+ readonly until: AudioSourceTimePoint;
};
-export type AudioItemMix = {
+export type AudioSourceTimeRelation =
+ | {
+ readonly kind: "rate";
+ readonly target: AudioSourceTimeBounds;
+ readonly targetAt: AudioSourceTimePoint;
+ readonly sourceAt: AudioSourceTimePoint;
+ readonly rate: AudioSourceTimeRational;
+ readonly source: AudioSourceTimeBounds;
+ readonly wrap?: AudioSourceTimeBounds;
+ }
+ | {
+ readonly kind: "fit";
+ readonly target: AudioSourceTimeBounds;
+ readonly source: AudioSourceTimeBounds;
+ /** Audio-specific safety bounds for the pitch-preserving tempo ratio. */
+ readonly minRate?: number;
+ readonly maxRate?: number;
+ };
+
+export type AudioSourceTimeSpec = {
+ readonly relations: readonly AudioSourceTimeRelation[];
+};
+
+export type AudioClipMix = {
readonly gain: number;
readonly fadeIn: TemporalDuration;
readonly fadeOut: TemporalDuration;
@@ -22,29 +46,25 @@ export type AudioItemMix = {
export type AudioClipSpec = {
readonly id: string;
- readonly trim: AudioSourceTrim;
- readonly occupancy: AudioOccupancy;
- readonly mix: AudioItemMix;
+ /** Omission means bounded partial identity. */
+ readonly sourceTime?: AudioSourceTimeSpec;
+ readonly mix: AudioClipMix;
};
export type AudioTrackHeader = {
readonly id: string;
};
-export type AudioItemProgram = {
+export type AudioClipProgram = {
readonly id: string;
- /** Author-owned Item realized by this externally projected window. */
+ /** Author-owned Clip realized by this absolute destination 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 sourceTime: AudioSourceTimeSpec;
readonly mix: {
readonly gain: number;
readonly fadeInSamples: number;
@@ -54,9 +74,9 @@ export type AudioItemProgram = {
export type AudioTrackProgram = {
readonly id: string;
- readonly items: readonly AudioItemProgram[];
+ readonly clips: readonly AudioClipProgram[];
};
export type AudioTrackSet = {
- readonly items: readonly AudioItemProgram[];
+ readonly clips: readonly AudioClipProgram[];
};
diff --git a/packages/audio-track/test/audio-track.test.ts b/packages/audio-track/test/audio-track.test.ts
index 54d6244f..f0dbc962 100644
--- a/packages/audio-track/test/audio-track.test.ts
+++ b/packages/audio-track/test/audio-track.test.ts
@@ -1,8 +1,8 @@
-import { sealTimeline } from "@hypit/timeline";
+import { sealTimeline, timelineDependency, timelineManifest, timelineTypes } from "@hypit/timeline";
import assert from "node:assert/strict";
import test from "node:test";
import { fixtureResource } from "../../../test/fixture-resource.js";
-import { timelineFixture } from "../../../test/timeline-fixture.js";
+import { narrativeProjectionFixture, timelineFixture } from "../../../test/timeline-fixture.js";
import { projectMomentWindow, projectProgramWindow, projectSelectionWindow } from "../../../test/temporal-fixture.js";
import type { TemporalWindowProjection } from "../../../test/temporal-fixture.js";
@@ -11,7 +11,7 @@ import {
audioTrackMarkupSurfaces,
audioTrackModuleRef,
audioTrackProducers,
- appendProjectedAudioItem,
+ appendAudioClip,
createAudioTrackSet,
createAudioTrackFragment,
finalizeAudioTrack,
@@ -20,7 +20,7 @@ import {
sealAudioTrackHeader,
decodeAudioTrackSurface,
} from "@hypit/audio-track";
-import type { AudioClipSpec, AudioTrackSet } from "@hypit/audio-track";
+import type { AudioClipSpec, AudioSourceTimeSpec, AudioTrackSet } from "@hypit/audio-track";
import { artifactManifest } from "@hypit/artifact";
import { registerTypeValidatorFacets } from "@hypit/component-kit";
import { sealComposition, compositionManifest, compositionTypes } from "@hypit/composition";
@@ -31,12 +31,12 @@ import { mediaComponent, mediaDependency, mediaManifest, mediaTypes } from "@hyp
import type { NarrativeMomentRef, NarrativeSelectionRef } from "@hypit/narrative";
import { narrativeManifest } from "@hypit/narrative";
import { compileAudioProgramPlan } from "@hypit/media-pipeline";
-import { programSpaceDependency, programSpaceManifest, programSpaceTypes, sealProgramSpace } from "@hypit/program-space";
import type { ModuleManifest } from "@hypit/protocol";
-import { projectTimelineSpace, timelineDependency, timelineManifest, timelineProducers, timelineTypes } from "@hypit/timeline";
import { temporalProducers } from "@hypit/temporal";
+import type { TemporalDuration } from "@hypit/temporal";
import { speechEvidenceManifest } from "@hypit/speech-evidence";
import { speechManifest } from "@hypit/speech";
+import { narrativeTemporalManifest } from "@hypit/narrative-temporal";
import { spatialManifest } from "@hypit/spatial";
import { svsManifest } from "@hypit/svs";
import { temporalManifest } from "@hypit/temporal";
@@ -44,19 +44,30 @@ import { MarkupSurfaceRegistry, createMarkupAuthorFrontend } from "@hypit/markup
import { createRecordAdmitter, TypeValidatorRegistry } from "@hypit/validation";
import { visualIrManifest } from "@hypit/visual-ir";
-const space = sealTimeline({ items: [], id: "test-space", durationSec: 10,
- frameRate: { numerator: 30, denominator: 1 },
+const space = sealTimeline({ id: "test-space", frameCount: 300, frameRate: { numerator: 30, denominator: 1 },
});
const header = sealAudioTrackHeader({ id: "sound" });
-const semantic = timelineFixture(space, { narrativeId: "test-narrative", anchors: [
+const semanticOptions = { narrativeId: "test-narrative", segments: [{ id: "line", frameCount: 300 }], anchors: [
{ identity: "a", frame: 30 }, { identity: "b", frame: 60 },
{ identity: "c", frame: 90 }, { identity: "d", frame: 120 },
-] });
+] } as const;
+const semantic = timelineFixture(space, semanticOptions);
+const narrativeProjection = narrativeProjectionFixture(semantic, semanticOptions);
const zero = { unit: "frames" as const, value: 0 };
+const duration = (value: number) => ({ unit: "milliseconds" as const, value });
+const startPoint = (offset: TemporalDuration = zero) => ({ edge: "start" as const, offset });
+const endPoint = (offset: TemporalDuration = zero) => ({ edge: "end" as const, offset });
+const fullBounds = () => ({ from: startPoint(), until: endPoint() });
+const rateSpec = (input: Partial<Extract<AudioSourceTimeSpec["relations"][number], { kind: "rate" }>> = {}): AudioSourceTimeSpec => ({
+ relations: [{
+ kind: "rate", target: fullBounds(), targetAt: startPoint(), sourceAt: startPoint(),
+ rate: { numerator: 1, denominator: 1 }, source: fullBounds(), ...input,
+ }],
+});
function media(id: string, sampleFrames: number): SynchronizedMedia {
return {
- timeline: {
+ frameDomain: {
frameRate: { numerator: 30, denominator: 1 },
frameCount: Math.max(1, Math.round(sampleFrames / 1_600)),
},
@@ -68,7 +79,7 @@ function media(id: string, sampleFrames: number): SynchronizedMedia {
type TestAudioClipSpec = AudioClipSpec & { readonly projection: TemporalWindowProjection };
const defaultProjection: TemporalWindowProjection = {
- start: { ref: "program.start" },
+ start: { ref: "timeline.start" },
end: { ref: "absolute", at: { unit: "seconds", numerator: 2, denominator: 1 } },
};
@@ -78,8 +89,6 @@ function spec(overrides: Partial<TestAudioClipSpec> = {}): TestAudioClipSpec {
...sealAudioClipSpec({
id: "clip",
- trim: {},
- occupancy: { mode: "once", align: "start" },
mix: { gain: 1, fadeIn: zero, fadeOut: zero },
...clipOverrides,
}),
@@ -92,7 +101,7 @@ function appendProgramAudioItem(
source: SynchronizedMedia, authored: TestAudioClipSpec,
): AudioTrackSet {
const { projection, ...clip } = authored;
- return appendProjectedAudioItem(set, trackHeader, timeline, source, clip, projectProgramWindow({
+ return appendAudioClip(set, trackHeader, timeline, source, clip, projectProgramWindow({
itemId: clip.id, semantic: timeline, projection,
}));
}
@@ -102,8 +111,9 @@ function appendSelectionAudioItem(
source: SynchronizedMedia, selection: NarrativeSelectionRef, authored: TestAudioClipSpec,
): AudioTrackSet {
const { projection, ...clip } = authored;
- return appendProjectedAudioItem(set, trackHeader, timeline, source, clip, projectSelectionWindow({
- itemId: clip.id, semantic: timeline, selection, projection,
+ return appendAudioClip(set, trackHeader, timeline, source, clip, projectSelectionWindow({
+ itemId: clip.id, semantic: timeline, narrative: narrativeProjection, selection,
+ projection: { start: { ref: "selection.start" }, end: { ref: "selection.end" } },
}));
}
@@ -112,8 +122,9 @@ function appendMomentAudioItem(
source: SynchronizedMedia, moment: NarrativeMomentRef, authored: TestAudioClipSpec,
): AudioTrackSet {
const { projection, ...clip } = authored;
- return appendProjectedAudioItem(set, trackHeader, timeline, source, clip, projectMomentWindow({
- itemId: clip.id, semantic: timeline, moment, projection,
+ return appendAudioClip(set, trackHeader, timeline, source, clip, projectMomentWindow({
+ itemId: clip.id, semantic: timeline, narrative: narrativeProjection, moment,
+ projection: { start: { ref: "moment.cue" }, end: { ref: "moment.cue", offset: { unit: "seconds", numerator: 1, denominator: 1 } } },
}));
}
@@ -122,73 +133,117 @@ function programTrack(source: SynchronizedMedia, clipSpec: TestAudioClipSpec) {
return renderAudioTrack(space, finalizeAudioTrack(set, header));
}
-test("once start/end preserve exact audible silence and source head/tail semantics", () => {
+test("partial identity and end alignment preserve exact silence and source head/tail semantics", () => {
const short = media("short", 48_000);
const start = programTrack(short, spec());
- assert.deepEqual(start.clips[0]?.target, { startSample: 0, endSampleExclusive: 48_000 });
- assert.deepEqual(start.clips[0]?.source, {
- sampleFrames: 48_000, startSample: 0, endSampleExclusive: 48_000, loop: false, phaseSample: 0,
- });
+ assert.deepEqual(start.clips[0]?.target, { startSample: 0, endSampleExclusive: 96_000 });
+ assert.deepEqual(start.clips[0]?.sourceTime, { sourceSampleFrames: 48_000, pieces: [{
+ target: { startSample: 0, endSampleExclusive: 48_000 },
+ sourceAtStart: { numerator: 0, denominator: 1 }, rate: { numerator: 1, denominator: 1 },
+ }] });
- const end = programTrack(short, spec({ occupancy: { mode: "once", align: "end" } }));
- assert.deepEqual(end.clips[0]?.target, { startSample: 48_000, endSampleExclusive: 96_000 });
+ const endAligned = rateSpec({ targetAt: endPoint(), sourceAt: endPoint() });
+ const end = programTrack(short, spec({ sourceTime: endAligned }));
+ assert.deepEqual(end.clips[0]?.sourceTime.pieces[0]?.target, { startSample: 48_000, endSampleExclusive: 96_000 });
- const long = programTrack(media("long", 144_000), spec({ occupancy: { mode: "once", align: "end" } }));
+ const long = programTrack(media("long", 144_000), spec({ sourceTime: endAligned }));
assert.deepEqual(long.clips[0]?.target, { startSample: 0, endSampleExclusive: 96_000 });
- assert.deepEqual(long.clips[0]?.source, {
- sampleFrames: 144_000, startSample: 48_000, endSampleExclusive: 144_000, loop: false, phaseSample: 0,
- });
+ assert.deepEqual(long.clips[0]?.sourceTime.pieces[0]?.sourceAtStart, { numerator: 48_000, denominator: 1 });
});
-test("loop alignment uses one source interval and an exact phase instead of duplicating clips", () => {
+test("periodic maps preserve one source interval and an exact phase", () => {
const projection = {
- start: { ref: "program.start" as const },
+ start: { ref: "timeline.start" as const },
end: { ref: "absolute" as const, at: { unit: "seconds" as const, numerator: 5, denominator: 2 } },
};
- const start = programTrack(media("loop", 48_000), spec({ projection, occupancy: { mode: "loop", align: "start" } }));
- assert.equal(start.clips[0]?.source.loop, true);
- assert.equal(start.clips[0]?.source.phaseSample, 0);
+ const start = programTrack(media("loop", 48_000), spec({ projection,
+ sourceTime: rateSpec({ wrap: fullBounds() }) }));
+ assert.deepEqual(start.clips[0]?.sourceTime.pieces[0]?.wrap, { startSample: 0, endSampleExclusive: 48_000 });
+ assert.deepEqual(start.clips[0]?.sourceTime.pieces[0]?.sourceAtStart, { numerator: 0, denominator: 1 });
assert.deepEqual(start.clips[0]?.target, { startSample: 0, endSampleExclusive: 120_000 });
- const end = programTrack(media("loop", 48_000), spec({ projection, occupancy: { mode: "loop", align: "end" } }));
- assert.equal(end.clips[0]?.source.phaseSample, 24_000);
+ const end = programTrack(media("loop", 48_000), spec({ projection,
+ sourceTime: rateSpec({ targetAt: endPoint(), sourceAt: endPoint(), wrap: fullBounds() }) }));
+ assert.deepEqual(end.clips[0]?.sourceTime.pieces[0]?.sourceAtStart, { numerator: 24_000, denominator: 1 });
});
-test("bounded pitch-preserving stretch succeeds exactly or fails without truncation", () => {
- const stretched = programTrack(media("stretch", 96_000), spec({
- projection: { start: { ref: "program.start" }, end: { ref: "absolute", at: { unit: "seconds", numerator: 4, denominator: 1 } } },
- occupancy: { mode: "stretch", minRate: 0.4, maxRate: 0.6, pitch: "preserve" },
+test("bounded pitch-preserving fit succeeds exactly or fails without truncation", () => {
+ const fitted = programTrack(media("fit", 96_000), spec({
+ projection: { start: { ref: "timeline.start" }, end: { ref: "absolute", at: { unit: "seconds", numerator: 4, denominator: 1 } } },
+ sourceTime: { relations: [{ kind: "fit", target: fullBounds(), source: fullBounds(), minRate: 0.4, maxRate: 0.6 }] },
}));
- assert.equal(stretched.clips[0]?.playbackRate, 0.5);
- assert.equal(stretched.clips[0]?.pitch, "preserve");
- assert.throws(() => programTrack(media("stretch-fail", 96_000), spec({
- projection: { start: { ref: "program.start" }, end: { ref: "absolute", at: { unit: "seconds", numerator: 4, denominator: 1 } } },
- occupancy: { mode: "stretch", minRate: 0.8, maxRate: 1.2, pitch: "preserve" },
- })), /outside authored bounds/u);
+ assert.deepEqual(fitted.clips[0]?.sourceTime.pieces[0]?.rate, { numerator: 1, denominator: 2 });
+ assert.throws(() => programTrack(media("fit-fail", 96_000), spec({
+ projection: { start: { ref: "timeline.start" }, end: { ref: "absolute", at: { unit: "seconds", numerator: 4, denominator: 1 } } },
+ sourceTime: { relations: [{ kind: "fit", target: fullBounds(), source: fullBounds(), minRate: 0.8, maxRate: 1.2 }] },
+ })), /below authored minimum/u);
});
-test("trim and fades quantize once into the same sample domain", () => {
+test("exact audio rates are not rejected by an arbitrary playback-mode ceiling", () => {
+ const track = programTrack(media("fast", 12_288_000), spec({
+ sourceTime: rateSpec({ rate: { numerator: 128, denominator: 1 } }),
+ }));
+ assert.deepEqual(track.clips[0]?.sourceTime.pieces[0]?.rate, { numerator: 128, denominator: 1 });
+ const plan = compileAudioProgramPlan(sealComposition({
+ id: "fast", canvas: { width: 1, height: 1, clearColor: "#000000" }, tracks: [track],
+ }), space);
+ assert.equal(plan.clips[0]?.playbackRate, 128);
+});
+
+test("source bounds and fades quantize once into the same sample domain", () => {
const track = programTrack(media("trim", 144_000), spec({
- trim: {
- start: { unit: "milliseconds", value: 250 },
- end: { unit: "seconds", numerator: 9, denominator: 4 },
- },
+ sourceTime: rateSpec({
+ sourceAt: startPoint(duration(250)),
+ source: { from: startPoint(duration(250)), until: startPoint({ unit: "seconds", numerator: 9, denominator: 4 }) },
+ }),
mix: {
gain: 0.25,
fadeIn: { unit: "milliseconds", value: 100 },
fadeOut: { unit: "milliseconds", value: 200 },
},
}));
- assert.equal(track.clips[0]?.source.startSample, 12_000);
- assert.equal(track.clips[0]?.source.endSampleExclusive, 108_000);
+ assert.deepEqual(track.clips[0]?.sourceTime.pieces[0]?.sourceAtStart, { numerator: 12_000, denominator: 1 });
+ assert.deepEqual(track.clips[0]?.sourceTime.pieces[0]?.target, { startSample: 0, endSampleExclusive: 96_000 });
assert.equal(track.clips[0]?.gain, 0.25);
assert.equal(track.clips[0]?.fadeInSamples, 4_800);
assert.equal(track.clips[0]?.fadeOutSamples, 9_600);
assert.throws(() => programTrack(media("fade", 24_000), spec({
- mix: { gain: 1, fadeIn: { unit: "seconds", numerator: 1, denominator: 1 }, fadeOut: zero },
- })), /fade exceeds/u);
+ mix: { gain: 1, fadeIn: { unit: "seconds", numerator: 3, denominator: 1 }, fadeOut: zero },
+ })), /fade exceeds its Window/u);
});
-test("Selection and Moment each place one independent item", () => {
+test("piecewise audio maps preserve silent gaps while execution keeps one Clip-global fade clock", () => {
+ const second = { unit: "seconds" as const, numerator: 1, denominator: 1 };
+ const seconds = (value: number): TemporalDuration => ({ unit: "seconds", numerator: value, denominator: 1 });
+ const track = programTrack(media("pieces", 96_000), spec({
+ projection: { start: { ref: "timeline.start" }, end: { ref: "absolute", at: seconds(4) } },
+ sourceTime: { relations: [
+ { kind: "rate", target: { from: startPoint(), until: startPoint(second) }, targetAt: startPoint(),
+ sourceAt: startPoint(), rate: { numerator: 1, denominator: 1 },
+ source: { from: startPoint(), until: startPoint(second) } },
+ { kind: "rate", target: { from: startPoint(seconds(2)), until: startPoint(seconds(3)) },
+ targetAt: startPoint(seconds(2)), sourceAt: startPoint(second), rate: { numerator: 1, denominator: 1 },
+ source: { from: startPoint(second), until: endPoint() } },
+ ] },
+ mix: { gain: 0.5, fadeIn: second, fadeOut: second },
+ }));
+ assert.deepEqual(track.clips[0]?.sourceTime.pieces.map((piece) => piece.target), [
+ { startSample: 0, endSampleExclusive: 48_000 },
+ { startSample: 96_000, endSampleExclusive: 144_000 },
+ ]);
+ const plan = compileAudioProgramPlan(sealComposition({
+ id: "piecewise", canvas: { width: 1, height: 1, clearColor: "#000000" }, tracks: [track],
+ }), space);
+ assert.deepEqual(plan.clips.map((clip) => ({
+ target: [clip.targetStartSample, clip.targetEndSampleExclusive],
+ mix: [clip.mixStartSample, clip.mixEndSampleExclusive],
+ fade: [clip.fadeInSamples, clip.fadeOutSamples],
+ })), [
+ { target: [0, 48_000], mix: [0, 192_000], fade: [48_000, 48_000] },
+ { target: [96_000, 144_000], mix: [0, 192_000], fade: [48_000, 48_000] },
+ ]);
+});
+
+test("resolved Windows place independent Clips regardless of their upstream source", () => {
const selection: NarrativeSelectionRef = {
narrativeId: "test-narrative",
id: "mentions",
@@ -203,11 +258,9 @@ test("Selection and Moment each place one independent item", () => {
let set: AudioTrackSet = createAudioTrackSet();
set = appendSelectionAudioItem(set, header, semantic, media("selection", 48_000), selection, spec({
id: "selected",
- projection: { start: { ref: "selection.start" }, end: { ref: "selection.end" } },
}));
set = appendMomentAudioItem(set, header, semantic, media("moment", 48_000), moment, spec({
id: "hit",
- projection: { start: { ref: "moment.cue" }, end: { ref: "moment.cue", offset: { unit: "seconds", numerator: 1, denominator: 1 } } },
}));
const track = renderAudioTrack(space, finalizeAudioTrack(set, header));
assert.equal(track.clips.length, 2);
@@ -222,7 +275,7 @@ test("one Track with overlaps and two peer Tracks compile to the same mix", () =
const combined = {
kind: "audio" as const,
id: "combined",
- programSpaceId: space.id,
+ timelineId: space.id,
clips: [
{ ...first.clips[0]!, id: "a" },
{ ...second.clips[0]!, id: "b" },
@@ -274,12 +327,12 @@ test("the self-described Audio Surface parses into the same finite Producer grap
artifactManifest,
mediaManifest,
narrativeManifest,
- programSpaceManifest,
+ timelineManifest,
speechManifest,
+ narrativeTemporalManifest,
svsManifest,
spatialManifest,
speechEvidenceManifest,
- timelineManifest,
temporalManifest,
visualIrManifest,
compositionManifest,
@@ -317,7 +370,9 @@ test("the self-described Audio Surface parses into the same finite Producer grap
<import as="audio" from="@hypit/audio-track@1"/>
<fixture:Inputs/>
<audio:Track id="sound" timeline={semantic}>
- <audio:Item source={source} during="program" playback="loop-end" gain="0.5" fade-in="2f" fade-out="3f"/>
+ <audio:Clip source={source} during="timeline" gain="0.5" fade-in="2f" fade-out="3f">
+ <audio:Map target-at="end" source-at="end" rate="1" wrap-from="start" wrap-until="end"/>
+ </audio:Clip>
</audio:Track>
</svml>`,
},
@@ -333,7 +388,7 @@ test("the self-described Audio Surface parses into the same finite Producer grap
}));
assert.deepEqual(build.plan.steps.map((step) => step.producer.name).sort(), [
audioTrackProducers.createSet.name,
- audioTrackProducers.appendItem.name,
+ audioTrackProducers.appendClip.name,
audioTrackProducers.finalize.name,
temporalProducers.projectProgramInstant.name,
temporalProducers.projectProgramInstant.name,
diff --git a/packages/background-removal/README.md b/packages/background-removal/README.md
index 3b78ebcc..fc8b468c 100644
--- a/packages/background-removal/README.md
+++ b/packages/background-removal/README.md
@@ -10,7 +10,7 @@ Use it for a product, portrait or graphic that will be composited over another p
`source` accepts an image BlobArtifact, including an ordinary image file declaration or a generated
image Output. `{cutout.image}` publishes one image BlobArtifact with transparency. Keep its actual
-dimensions when placing it in Media Track, or use Image Compose when a flattened still is wanted.
+dimensions when placing it as a Visual Clip, or use Image Compose when a flattened still is wanted.
The package declares the visual operation; a project Provider implements the capability
`@hypit/background-removal@1#remove-background`, accepting `{ source: BlobRef }` and returning one
diff --git a/packages/build-result-s3/test/repository.test.ts b/packages/build-result-s3/test/repository.test.ts
index 8831fab3..ab9ec3bf 100644
--- a/packages/build-result-s3/test/repository.test.ts
+++ b/packages/build-result-s3/test/repository.test.ts
@@ -9,9 +9,9 @@ const videoType: TypeRef = {
module: { name: "example.media", version: "1" },
name: "Video",
};
-const takeType: TypeRef = {
+const compositeType: TypeRef = {
module: { name: "example.speech", version: "1" },
- name: "SemanticTake",
+ name: "CompositeValue",
};
class MemoryS3 implements BuildResultS3Client {
@@ -164,7 +164,7 @@ test("S3 keeps the same Build Result model as the filesystem repository", async
{ id: "record:video", type: videoType, value: video },
{
id: "record:take",
- type: takeType,
+ type: compositeType,
value: {
kind: "inline",
value: { media: { visual: { artifact: video } } },
@@ -469,7 +469,7 @@ test("S3 Composite values retain external and prior-Result Resource references",
[photo.resource]: { kind: "external-file", uri: "asset://selected/photo", size: 3, mediaType: "image/png" },
[video.resource]: { ...saved.value, build: originalId },
} });
- await writer.sync({ state: state({ records: [{ id: "r", type: takeType,
+ await writer.sync({ state: state({ records: [{ id: "r", type: compositeType,
value: { kind: "inline", value: { layers: [{ parts: [photo, { clip: video, repeated: photo }] }] } } }],
bindings: [{ output: "layout", record: "r" }] }),
resources: { async open() { throw new Error("Referenced resources cannot be uploaded again"); } } });
diff --git a/packages/build-result/test/result.test.ts b/packages/build-result/test/result.test.ts
index e7430616..3f4aa6cc 100644
--- a/packages/build-result/test/result.test.ts
+++ b/packages/build-result/test/result.test.ts
@@ -12,9 +12,9 @@ const videoType: TypeRef = {
module: { name: "example.media", version: "1" },
name: "Video",
};
-const takeType: TypeRef = {
+const compositeType: TypeRef = {
module: { name: "example.speech", version: "1" },
- name: "SemanticTake",
+ name: "CompositeValue",
};
function state(input: {
@@ -108,7 +108,7 @@ test("publishing and finishing preserve open readers of the previous Result file
}
});
-test("one same-Build resource backs a public video and a SemanticTake payload", async () => {
+test("one same-Build resource backs a public video and a CompositeValue payload", async () => {
const root = await mkdtemp(join(tmpdir(), "hypit-build-result-"));
const bytes = new Uint8Array([1, 2, 3, 4]);
const video: BlobRef = {
@@ -143,7 +143,7 @@ test("one same-Build resource backs a public video and a SemanticTake payload",
{ id: "record:video", type: videoType, value: video },
{
id: "record:take",
- type: takeType,
+ type: compositeType,
value: { kind: "inline", value: { media: { visual: { artifact: video } } } },
},
],
@@ -340,7 +340,7 @@ test("describing a Composite Output reads only its manifest", async () => {
targets: ["take"],
outcome: "complete",
finishedAt: 1,
- outputs: { take: { type: takeType, value: { kind: "value", path: "values/missing.json" } } },
+ outputs: { take: { type: compositeType, value: { kind: "value", path: "values/missing.json" } } },
}));
const repository = new FileBuildResultRepository(root);
const description = await repository.describeOutput(id, "take");
diff --git a/packages/caption-fine-studio/README.md b/packages/caption-fine-studio/README.md
index 70f5fd7b..69920ce7 100644
--- a/packages/caption-fine-studio/README.md
+++ b/packages/caption-fine-studio/README.md
@@ -11,7 +11,7 @@ reads the Track's `content`, `schedule` and `program` exports; it never reconstr
from the rendered words.
Use entities retain the actual child Source range and standard Temporal lineage. Timeline gestures
-therefore use the same writeback rules as Performance and Sound. Selecting a Use exposes its
+therefore use the same writeback rules as Visual and Audio Clips. Selecting a Use exposes its
referenced Style's font and Recipe fields. Shared Styles remain shared; changing a time window
changes presentation without editing Script Cue breaks.
diff --git a/packages/caption-fine-studio/package.json b/packages/caption-fine-studio/package.json
index c52c501e..5e607c90 100644
--- a/packages/caption-fine-studio/package.json
+++ b/packages/caption-fine-studio/package.json
@@ -13,7 +13,7 @@
"dependencies": {
"@hypit/caption-fine": "workspace:*",
"@hypit/composition": "workspace:*",
- "@hypit/narrative": "workspace:*",
+ "@hypit/caption": "workspace:*",
"@hypit/studio-adapter": "workspace:*",
"@hypit/fonts-open": "workspace:*",
"@hypit/caption": "workspace:*",
diff --git a/packages/caption-fine-studio/src/index.ts b/packages/caption-fine-studio/src/index.ts
index 6f51fe88..c6ae56d4 100644
--- a/packages/caption-fine-studio/src/index.ts
+++ b/packages/caption-fine-studio/src/index.ts
@@ -1,11 +1,11 @@
import { temporalTypes } from "@hypit/temporal";
-import type { CaptionProgram, TimedCaptionProjection } from "@hypit/caption";
+import type { CaptionProgram, CaptionTiming } from "@hypit/caption";
import { openFontStudioFields } from "@hypit/fonts-open/studio";
import { fineCaptionEditableDefaults, captionFineMarkupSurfaces, captionFineModuleRef } from "@hypit/caption-fine";
import type { FineCaptionSchedule } from "@hypit/caption-fine";
import { compositionTypes } from "@hypit/composition";
-import { narrativeTypes } from "@hypit/narrative";
-import type { CaptionDocument } from "@hypit/narrative";
+import { captionTypes } from "@hypit/caption";
+import type { CaptionDocument } from "@hypit/caption";
import type {
StudioTrackCompanion,
StudioTrackCompanionContext,
@@ -119,9 +119,9 @@ function cueText(document: CaptionDocument | undefined, unitIds: readonly string
}
export function projectCaptionContents(context: StudioTrackCompanionContext): readonly StudioEntityDraft[] {
- const content = requiredSurfaceValue(context, "content") as TimedCaptionProjection;
+ const content = requiredReferencedValue(context, "timing", captionTypes.timing) as CaptionTiming;
const schedule = requiredSurfaceValue(context, "schedule") as FineCaptionSchedule;
- const document = requiredReferencedValue(context, "document", narrativeTypes.captionDocument) as CaptionDocument;
+ const document = requiredReferencedValue(context, "document", captionTypes.document) as CaptionDocument;
if (document.id !== content.documentId) throw new Error("Caption content belongs to another CaptionDocument.");
return content.cues.map((cue, index): StudioEntityDraft => ({
id: `${context.track.outputRef}:cue:${cue.id}`, authoredId: cue.id,
@@ -157,7 +157,7 @@ export function projectCaption(context: StudioTrackCompanionContext): readonly S
export const captionFineStudioTrackCompanions: readonly StudioTrackCompanion[] = [
{
id: "track", role: "track",
- output: { type: compositionTypes.visualTrack, surface: "track", modules: [captionFineModuleRef] },
+ output: { type: compositionTypes.visualTrack, surface: "caption", modules: [captionFineModuleRef] },
family: "caption", tone: "magenta", icon: "captions",
lane: { heightPx: 36 },
bands: [{
@@ -165,7 +165,7 @@ export const captionFineStudioTrackCompanions: readonly StudioTrackCompanion[] =
bindings: [{ name: "style", companion: true }],
inspector: [{ binding: "style", label: "Style", domain: "how", section: { id: "style", label: "Style" }, control: "text" }],
}],
- requiredValues: ["content", "schedule", "program"], project: projectCaption,
+ requiredValues: ["schedule", "program"], project: projectCaption,
},
];
diff --git a/packages/caption-fine-studio/test/adapter.test.ts b/packages/caption-fine-studio/test/adapter.test.ts
index e72ac7da..a101bbc8 100644
--- a/packages/caption-fine-studio/test/adapter.test.ts
+++ b/packages/caption-fine-studio/test/adapter.test.ts
@@ -2,9 +2,9 @@ import assert from "node:assert/strict";
import test from "node:test";
import type { FineCaptionSchedule } from "@hypit/caption-fine";
+import { captionTypes } from "@hypit/caption";
+import type { CaptionDocument } from "@hypit/caption";
import { compositionTypes } from "@hypit/composition";
-import { narrativeTypes } from "@hypit/narrative";
-import type { CaptionDocument } from "@hypit/narrative";
import type { StudioTrackCompanionContext, StudioEntityDraft } from "@hypit/studio-adapter";
import { captionFineInspectorFields, projectCaptionContents } from "../src/index.js";
@@ -20,14 +20,13 @@ test("Caption Companion owns Inspector grouping", () => {
test("Caption Companion projects Cue text and Style from public domain values", () => {
const schedule: FineCaptionSchedule = {
- spaceId: "speech",
- narrativeId: "story",
+ timelineId: "speech",
documentId: "story.caption",
cues: [{
id: "cue-1", cueId: "cue-1", visibility: [{startFrame:8,endFrameExclusive:24}],
styleId: "caption-alt",
- semanticStartFrame: 10,
- semanticEndFrameExclusive: 20,
+ timedStartFrame: 10,
+ timedEndFrameExclusive: 20,
visibleStartFrame: 8,
visibleEndFrameExclusive: 24,
units: [{ unitId: "unit-1", startFrame: 10, endFrameExclusive: 20 }],
@@ -35,11 +34,10 @@ test("Caption Companion projects Cue text and Style from public domain values",
};
const document: CaptionDocument = {
id: "story.caption",
- narrativeId: "story",
- units: [{ id: "unit-1", segmentId: "segment-1", turnId: "turn-1", wordIds: ["word-1", "word-2"], sourceTokenIds: ["token-1"] }],
+ units: [{ id: "unit-1", groupId: "segment-1:turn-1", wordIds: ["word-1", "word-2"] }],
words: [
- { id: "word-1", unitId: "unit-1", segmentId: "segment-1", turnId: "turn-1", text: "真实", separatorBefore: "", attributes: [] },
- { id: "word-2", unitId: "unit-1", segmentId: "segment-1", turnId: "turn-1", text: "字幕", separatorBefore: "", attributes: [] },
+ { id: "word-1", unitId: "unit-1", text: "真实", separatorBefore: "", attributes: [] },
+ { id: "word-2", unitId: "unit-1", text: "字幕", separatorBefore: "", attributes: [] },
],
cueBreaks: [],
};
@@ -53,19 +51,22 @@ test("Caption Companion projects Cue text and Style from public domain values",
name: "captions.track", type: "VisualTrack", typeRef: compositionTypes.visualTrack, outputRef: "captions.track",
candidateOrigin: "source", role: "track",
trace: {
- surface: "track", module: { name: "@hypit/caption-fine", version: "1" }, authoredId: "captions",
- outputPorts: [{ name: "schedule", ref: "captions.schedule", type: "FineCaptionSchedule" }, { name: "content", ref: "captions.content", type: "TimedCaptionProjection" }],
+ surface: "caption", module: { name: "@hypit/caption-fine", version: "1" }, authoredId: "captions",
+ outputPorts: [{ name: "schedule", ref: "captions.schedule", type: "FineCaptionSchedule" }, { name: "timing", ref: "captions.timing", type: "CaptionTiming" }],
references: [{
input: "document", name: "story.caption", ref: "story.caption", type: "CaptionDocument",
- typeRef: narrativeTypes.captionDocument,
+ typeRef: captionTypes.document,
+ }, {
+ input: "timing", name: "story-captions", ref: "captions.timing", type: "CaptionTiming",
+ typeRef: captionTypes.timing,
}],
},
value: { visualIr: "hypit.visual-ir@1", id: "captions", presents: [] },
},
spans: [{ id: "cue-1", startFrame: 8, endFrameExclusive: 24, stackOrder: 70 }],
- values: new Map<string, unknown>([["captions.schedule", schedule], ["captions.content", {documentId:document.id, cues:[{id:"cue-1",startFrame:10,endFrameExclusive:20,units:schedule.cues[0]!.units}]}], ["story.caption", document]]),
+ values: new Map<string, unknown>([["captions.schedule", schedule], ["captions.timing", {timelineId:"speech",documentId:document.id, cues:[{id:"cue-1",startFrame:10,endFrameExclusive:20,units:schedule.cues[0]!.units}]}], ["story.caption", document]]),
temporalBindings: [],
- semantic: { spaceId: "speech", narrativeId: "story", presentation: { family: "speech", tone: "teal", icon: "timeline", lane: { heightPx: 45 } }, anchors: [], segments: [], tokens: [], selections: [], moments: [], provenance: { output: "speech", outputRef: "speech", origin: "source", status: "resolved", errors: [] } },
+ semantic: { timelineId: "speech", narrativeId: "story", presentation: { family: "speech", tone: "teal", icon: "timeline", lane: { heightPx: 45 } }, anchors: [], segments: [], tokens: [], selections: [], moments: [], provenance: { output: "speech", outputRef: "speech", origin: "source", status: "resolved", errors: [] } },
generic: () => [base],
} satisfies StudioTrackCompanionContext;
const [cue] = projectCaptionContents(context);
@@ -98,12 +99,12 @@ test("Caption Uses keep authored windows and child ownership even with no render
const { temporalTypes } = await import("@hypit/temporal");
const { timelineFixture } = await import("../../../test/timeline-fixture.js");
const { projectProgramWindow } = await import("../../../test/temporal-fixture.js");
- const timeline = timelineFixture({id:"film",durationSec:6,frameRate:{numerator:30,denominator:1}}, {segments:[{id:"a",frameCount:90},{id:"b",frameCount:90}]});
- const uses = ["base", "hidden"].map(id=>({styleId:id,window:projectProgramWindow({itemId:id,semantic:timeline,projection:{start:{ref:"program.start"},end:{ref:"program.end"}}})}));
+ const timeline = timelineFixture({id:"film",frameCount: 180, frameRate: { numerator: 30, denominator: 1 }}, {segments:[{id:"a",frameCount:90},{id:"b",frameCount:90}]});
+ const uses = ["base", "hidden"].map(id=>({styleId:id,window:projectProgramWindow({itemId:id,semantic:timeline,projection:{start:{ref:"timeline.start"},end:{ref:"timeline.end"}}})}));
const context = {
- track:{outputRef:"captions.track",trace:{references:[{input:"document",typeRef:narrativeTypes.captionDocument,ref:"document"}],outputPorts:[{name:"content",ref:"content"},{name:"schedule",ref:"schedule"},{name:"program",ref:"program"}]}},
+ track:{outputRef:"captions.track",trace:{references:[{input:"document",typeRef:captionTypes.document,ref:"document"},{input:"timing",typeRef:captionTypes.timing,ref:"timing"}],outputPorts:[{name:"schedule",ref:"schedule"},{name:"program",ref:"program"}]}},
placement:{children:uses.map((use,i)=>({range:{start:i*10,end:i*10+8},referenceAttributes:{style:use.styleId},values:[{type:temporalTypes.windowSpec,value:{id:use.window.subjectId}}]}))},
- values:new Map<string,unknown>([["document",{id:"document",units:[],words:[]}],["content",{documentId:"document",cues:[]}],["schedule",{cues:[]}],["program",{uses}]]),
+ values:new Map<string,unknown>([["document",{id:"document",units:[],words:[]}],["timing",{timelineId:"film",documentId:"document",cues:[]}],["schedule",{cues:[]}],["program",{uses}]]),
spans:[],temporalBindings:[],
} as unknown as StudioTrackCompanionContext;
const entities=projectCaption(context);
diff --git a/packages/caption-fine/README.md b/packages/caption-fine/README.md
index dce404dd..c8e08473 100644
--- a/packages/caption-fine/README.md
+++ b/packages/caption-fine/README.md
@@ -8,27 +8,29 @@ does not carry a private visual role.
```xml
<caption-fine:Style id="primary" recipe={recipes.caption.primary} font={caption-font}/>
-<caption-fine:Track id="captions-track" document={story.caption}
- timeline={speech.timeline}>
+<caption-fine:Caption id="captions-track" document={story.caption} timing={story-captions}
+ timeline={speech.timeline} within={vertical.bounds}>
<caption-fine:Use style={primary}/>
- </caption-fine:Track>
+ </caption-fine:Caption>
```
-An optional Spatial Region Timeline supplies a moving placement point when the user's reference
+An optional Region Track supplies a moving placement point when the user's reference
visibly uses head-following Caption or the user asks for that treatment. Ordinary Caption uses the
-Style's placement without regions. The Region Timeline is authored numeric input mapped from available picture
+Style's placement without regions. Region Track is authored numeric input mapped from available picture
evidence to the composition that consumes it; it is not a face-tracking request:
```xml
-<space:RegionTimeline id="heads" within={vertical} recipe={tracking.heads.default}/>
-<caption-fine:Track id="captions-track" document={story.caption}
- timeline={speech.timeline} regions={heads}>
+<import as="region" from="@hypit/region-track@1"/>
+<region:Track id="heads" within={vertical.bounds} timeline={speech.timeline}
+ recipe={tracking.heads.default}/>
+<caption-fine:Caption id="captions-track" document={story.caption} timing={story-captions}
+ timeline={speech.timeline} within={vertical.bounds} regions={heads}>
<caption-fine:Use style={primary}/>
- </caption-fine:Track>
+ </caption-fine:Caption>
```
-With `regions`, every Cue must carry one Script Role. When the Region Timeline contains a measured region for that
-Role and Frame, the Track places the Cue at the region's top center. When that Role has a Track but
+With `regions`, every Cue must carry one Script Role. When Region Track contains a measured region for that
+Role and Frame, Fine places the Cue at the region's top center. When that Role has a series but
the current Frame is `null`, the Cue is not rendered: absence of evidence never becomes a guessed
position. A Role with no Track uses the Style's authored `x` and `y`, so unrelated speakers remain
ordinary fixed captions. The Style still owns its width and anchors, so `anchor-x: center;
@@ -38,7 +40,7 @@ missing Frames or invoke a Provider. Without `regions`, the ordinary Recipe `x`
unchanged.
This keeps placement inspectable and editable. If a tracked face needs padding or an above-head anchor,
-transform the measured numbers while authoring the Region Timeline, then give Caption the result. Do
+transform the measured numbers while authoring Region Track, then give Caption the result. Do
not hide that transformation in a Provider or ask the Build to rediscover the face.
One SVS Recipe freezes three public dimensions:
@@ -47,14 +49,14 @@ One SVS Recipe freezes three public dimensions:
- **How**: the exact font stack, typography, base/active glyph Paint, Cue box and decoration.
- **When**: the visible lead/tail envelope, handoff, Cue/Atom motion, reveal, Karaoke and loops.
-Caption first projects authored Script units onto semantic Word timing. Fine then produces an
-explicit visible Schedule and renders that Schedule. Lead and tail never change the semantic Word
+An upstream adapter supplies absolute Caption unit timing. Fine then produces an explicit visible
+Schedule and renders that Schedule. Lead and tail never change the source timing
times used by Karaoke. Later Uses mask earlier presentation, including Hidden. The final visibility
is clipped to the winning Use Window while the original Cue envelope and animations are preserved.
-The Fine Schedule preserves the Caption projection's ProgramSpace, Narrative and document identities.
-The renderer rejects any mismatched Space or document. Studio may expose lead, tail and handoff as
-ordinary parameter edits, but Cue rectangles remain read-only semantic evidence.
+The Fine Schedule preserves the CaptionTiming's Timeline and document identities. It contains no
+Narrative identity. The renderer rejects any mismatched Timeline or document. Studio may expose
+lead, tail and handoff as ordinary parameter edits, but Cue rectangles remain read-only timing facts.
Script segments, turns and `||` organize complete Cues. Timed Uses select presentation without
changing that grouping. Fine applies uniform rules to the words of a Cue. A caption whose Cue contains structural roles or
diff --git a/packages/caption-fine/package.json b/packages/caption-fine/package.json
index bcc0faed..7b0d86c3 100644
--- a/packages/caption-fine/package.json
+++ b/packages/caption-fine/package.json
@@ -17,9 +17,8 @@
"@hypit/elaborator": "workspace:*",
"@hypit/hyperframes": "workspace:*",
"@hypit/media": "workspace:*",
- "@hypit/narrative": "workspace:*",
- "@hypit/program-space": "workspace:*",
"@hypit/protocol": "workspace:*",
+ "@hypit/region-track": "workspace:*",
"@hypit/timeline": "workspace:*",
"@hypit/spatial": "workspace:*",
"@hypit/svs": "workspace:*",
diff --git a/packages/caption-fine/src/activation.ts b/packages/caption-fine/src/activation.ts
index f57c427a..9341d6a4 100644
--- a/packages/caption-fine/src/activation.ts
+++ b/packages/caption-fine/src/activation.ts
@@ -23,7 +23,7 @@ export const hypitPackage = {
}),
createMarkupSurfaceHostFacet({
module: captionFineModuleRef,
- declaration: captionFineMarkupSurfaces.find((item) => item.name === "track")!,
+ declaration: captionFineMarkupSurfaces.find((item) => item.name === "caption")!,
handler: decodeFineCaptionTrackSurface,
}),
],
diff --git a/packages/caption-fine/src/component.ts b/packages/caption-fine/src/component.ts
index 163745dd..c3d77459 100644
--- a/packages/caption-fine/src/component.ts
+++ b/packages/caption-fine/src/component.ts
@@ -1,10 +1,10 @@
import type { Timeline } from "@hypit/timeline";
-import type { CaptionProgram, TimedCaptionProjection } from "@hypit/caption";
+import type { CaptionDocument, CaptionProgram, CaptionTiming } from "@hypit/caption";
import type { ComponentPackage } from "@hypit/component-kit";
-import type { CaptionDocument } from "@hypit/narrative";
import type { StoredValue } from "@hypit/protocol";
import { canonicalize } from "@hypit/protocol";
-import type { SpatialRegionTimeline } from "@hypit/spatial";
+import type { RegionTrack } from "@hypit/region-track";
+import type { SpatialFrame } from "@hypit/spatial";
import { captionFineProducers } from "./manifest.js";
import { renderFineCaption } from "./render.js";
@@ -22,7 +22,7 @@ export const captionFineComponent = {
producer: captionFineProducers.schedule,
handler: ({ inputs }) => ({
outputs: { schedule: { kind: "inline", value: canonicalize(scheduleFineCaption(
- inline<TimedCaptionProjection>(inputs.caption?.value, "TimedCaptionProjection"),
+ inline<CaptionTiming>(inputs.timing?.value, "CaptionTiming"),
inline<CaptionProgram>(inputs.program?.value, "CaptionProgram"),
inline<CaptionDocument>(inputs.document?.value, "CaptionDocument"),
)) } },
@@ -37,6 +37,7 @@ export const captionFineComponent = {
inline<CaptionProgram>(inputs.program?.value, "CaptionProgram"),
inline<CaptionDocument>(inputs.document?.value, "CaptionDocument"),
inline<Timeline>(inputs.timeline?.value, "Timeline"),
+ inline<SpatialFrame>(inputs.within?.value, "SpatialFrame"),
)) } },
needs: {},
}),
@@ -49,7 +50,8 @@ export const captionFineComponent = {
inline<CaptionProgram>(inputs.program?.value, "CaptionProgram"),
inline<CaptionDocument>(inputs.document?.value, "CaptionDocument"),
inline<Timeline>(inputs.timeline?.value, "Timeline"),
- inline<SpatialRegionTimeline>(inputs.regions?.value, "SpatialRegionTimeline"),
+ inline<SpatialFrame>(inputs.within?.value, "SpatialFrame"),
+ inline<RegionTrack>(inputs.regions?.value, "RegionTrack"),
)) } },
needs: {},
}),
diff --git a/packages/caption-fine/src/fragment.ts b/packages/caption-fine/src/fragment.ts
index 2ed28db1..ab17a9a5 100644
--- a/packages/caption-fine/src/fragment.ts
+++ b/packages/caption-fine/src/fragment.ts
@@ -1,8 +1,8 @@
-import { captionProducers, captionTypes } from "@hypit/caption";
+import { captionTypes } from "@hypit/caption";
import { compositionTypes } from "@hypit/composition";
import { sealGraphFragment } from "@hypit/elaborator";
-import { narrativeTypes } from "@hypit/narrative";
import { timelineTypes } from "@hypit/timeline";
+import { regionTrackTypes } from "@hypit/region-track";
import { spatialTypes } from "@hypit/spatial";
import { captionFineProducers, captionFineTypes } from "./manifest.js";
@@ -13,24 +13,18 @@ const operation = (id: string) => ({ kind: "fragment-operation" as const, operat
/** One timing join plus one Style-family render operation, regardless of how many Styles are used. */
export const fineCaptionTrackFragment = sealGraphFragment({
inputs: [
- { name: "document", type: narrativeTypes.captionDocument },
+ { name: "document", type: captionTypes.document },
{ name: "timeline", type: timelineTypes.track },
+ { name: "within", type: spatialTypes.frame },
+ { name: "timing", type: captionTypes.timing },
{ name: "program", type: captionTypes.program },
],
operations: [
- {
- id: "caption:temporalize-document",
- producer: captionProducers.temporalizeDocument,
- inputs: {
- document: input("document"), timeline: input("timeline"),
- },
- result: { kind: "output", name: "caption" },
- },
{
id: "caption-fine:schedule",
producer: captionFineProducers.schedule,
inputs: {
- caption: operation("caption:temporalize-document"), program: input("program"), document: input("document"),
+ timing: input("timing"), program: input("program"), document: input("document"),
},
result: { kind: "output", name: "schedule" },
},
@@ -39,7 +33,7 @@ export const fineCaptionTrackFragment = sealGraphFragment({
producer: captionFineProducers.render,
inputs: {
schedule: operation("caption-fine:schedule"), program: input("program"),
- document: input("document"), timeline: input("timeline"),
+ document: input("document"), timeline: input("timeline"), within: input("within"),
},
result: { kind: "output", name: "track" },
},
@@ -51,7 +45,7 @@ export const fineCaptionTrackFragment = sealGraphFragment({
root: operation("caption-fine:schedule"),
},
{
- name: "track",
+ name: "visual",
type: compositionTypes.visualTrack,
root: operation("caption-fine:render"),
},
@@ -61,25 +55,19 @@ export const fineCaptionTrackFragment = sealGraphFragment({
/** The same Caption pipeline with one explicit, external spatial-evidence edge. */
export const fineCaptionRegionTrackFragment = sealGraphFragment({
inputs: [
- { name: "document", type: narrativeTypes.captionDocument },
+ { name: "document", type: captionTypes.document },
{ name: "timeline", type: timelineTypes.track },
+ { name: "within", type: spatialTypes.frame },
+ { name: "timing", type: captionTypes.timing },
{ name: "program", type: captionTypes.program },
- { name: "regions", type: spatialTypes.regionTimeline },
+ { name: "regions", type: regionTrackTypes.track },
],
operations: [
- {
- id: "caption:temporalize-document",
- producer: captionProducers.temporalizeDocument,
- inputs: {
- document: input("document"), timeline: input("timeline"),
- },
- result: { kind: "output", name: "caption" },
- },
{
id: "caption-fine:schedule",
producer: captionFineProducers.schedule,
inputs: {
- caption: operation("caption:temporalize-document"), program: input("program"), document: input("document"),
+ timing: input("timing"), program: input("program"), document: input("document"),
},
result: { kind: "output", name: "schedule" },
},
@@ -88,13 +76,13 @@ export const fineCaptionRegionTrackFragment = sealGraphFragment({
producer: captionFineProducers.renderWithRegions,
inputs: {
schedule: operation("caption-fine:schedule"), program: input("program"),
- document: input("document"), timeline: input("timeline"), regions: input("regions"),
+ document: input("document"), timeline: input("timeline"), within: input("within"), regions: input("regions"),
},
result: { kind: "output", name: "track" },
},
],
exports: [
{ name: "schedule", type: captionFineTypes.schedule, root: operation("caption-fine:schedule") },
- { name: "track", type: compositionTypes.visualTrack, root: operation("caption-fine:render") },
+ { name: "visual", type: compositionTypes.visualTrack, root: operation("caption-fine:render") },
],
});
diff --git a/packages/caption-fine/src/manifest.ts b/packages/caption-fine/src/manifest.ts
index 9c460d09..87ec17ad 100644
--- a/packages/caption-fine/src/manifest.ts
+++ b/packages/caption-fine/src/manifest.ts
@@ -1,15 +1,15 @@
import { temporalDependency, temporalTypes } from "@hypit/temporal";
-import { temporalWindowAttributeVocabulary } from "@hypit/temporal-markup";
+import { temporalContextAttributeVocabulary, temporalWindowAttributeVocabulary } from "@hypit/temporal-markup";
+import { timelineDependency, timelineTypes } from "@hypit/timeline";
import type { Timeline } from "@hypit/timeline";
import { readFile } from "node:fs/promises";
-import { captionManifest, captionModuleRef, captionTypes } from "@hypit/caption";
+import { captionModuleRef, captionTypes } from "@hypit/caption";
import { compositionDependency, compositionTypes } from "@hypit/composition";
import { mediaDependency, mediaTypes } from "@hypit/media";
-import { narrativeDependency, narrativeTypes } from "@hypit/narrative";
import type { ModuleManifest, ProducerRef } from "@hypit/protocol";
-import { timelineDependency, timelineTypes } from "@hypit/timeline";
+import { regionTrackDependency, regionTrackTypes } from "@hypit/region-track";
import { spatialDependency, spatialTypes } from "@hypit/spatial";
import { svsRecipeType } from "@hypit/svs";
@@ -43,15 +43,15 @@ export const captionFineMarkupSurfaces = [
summary: "Chooses the Recipe that carries Cue geometry, Paint and local motion.",
recipe: [
{ name: "stack-order", required: true,
- summary: "Places this Style's Cues in the Track's drawing order, low behind high." },
+ summary: "Places this Style's Cues in the composition drawing order, low behind high." },
{ name: "x", required: true,
- summary: "Places the Cue box horizontally as a fraction of the Canvas width." },
+ summary: "Places the Cue box horizontally as a fraction of the selected Frame's width." },
{ name: "y", required: true,
- summary: "Places the Cue box vertically as a fraction of the Canvas height." },
+ summary: "Places the Cue box vertically as a fraction of the selected Frame's height." },
{ name: "width", required: true,
- summary: "Sets the Cue box width as a fraction of the Canvas width." },
+ summary: "Sets the Cue box width as a fraction of the selected Frame's width." },
{ name: "height", required: false,
- summary: "Optionally gives the Caption Region a fixed fraction of Canvas height; without it the Region hugs its Cue." },
+ summary: "Optionally gives the Caption Region a fixed fraction of the selected Frame's height; without it the Region hugs its Cue." },
{ name: "anchor-x", required: false, values: ["left", "center", "right"], fallback: "left",
summary: "Decides which horizontal edge of the Cue box sits on the placement point." },
{ name: "anchor-y", required: false, values: ["top", "center", "bottom"], fallback: "top",
@@ -268,9 +268,9 @@ export const captionFineMarkupSurfaces = [
{ name: "loop-intensity", required: false, fallback: "1",
summary: "Scales how far the looping motion carries." },
{ name: "lead-frames", required: false, fallback: "0",
- summary: "Makes the Cue visible this many Frames before its first semantic Word without moving any Word timing." },
+ summary: "Makes the Cue visible this many Frames before its first timed unit without moving any unit timing." },
{ name: "tail-frames", required: false, fallback: "0",
- summary: "Keeps the Cue visible this many Frames after its last semantic Word without extending any Word timing." },
+ summary: "Keeps the Cue visible this many Frames after its last timed unit without extending any unit timing." },
{ name: "handoff", required: false, values: ["cut", "overlap"], fallback: "cut",
summary: "Chooses whether adjacent Cue visibility envelopes meet without overlap or may coexist." },
] },
@@ -298,19 +298,22 @@ export const captionFineMarkupSurfaces = [
},
},
{
- name: "track", tag: "Track", mode: "structured", outputs: [captionFineTypes.schedule, compositionTypes.visualTrack, captionTypes.program, captionTypes.timedProjection, captionTypes.header, captionTypes.filter, temporalTypes.instantSpec, temporalTypes.windowSpec, temporalTypes.instant, temporalTypes.window],
+ name: "caption", tag: "Caption", mode: "structured", outputs: [captionFineTypes.schedule, compositionTypes.visualTrack, captionTypes.program, captionTypes.header, captionTypes.filter, temporalTypes.duration, temporalTypes.extent, temporalTypes.shiftSpec, temporalTypes.instantSpec, temporalTypes.windowSpec, temporalTypes.instant, temporalTypes.window],
vocabulary: {
- summary: "Joins the authored CaptionDocument against the Timeline and renders it as one ordinary peer VisualTrack.",
- appearance: "One block of caption text wrapped into lines inside a rounded Cue box, placed at a Recipe-chosen point on the Canvas and spanning a fraction of its width. Cues follow the speech one after another, each arriving and leaving with its own motion, and the Words of a Cue either stand there together from its first Frame or uncover as they are spoken. As the speech advances, the Word being spoken, or every Word up to it, is repainted in the active Paint, snapping at the Word boundary or sweeping across the glyphs, and it may take a rule beneath it, a rounded highlight capsule behind it and a brief pop at the moment it becomes the spoken one. That capsule either stands alone on each Atom or grows as one continuous run over everything already read, following the Words across line breaks.\n\nEvery Cue uses the ordered exact font stack its Style names, with fallback faces supplying glyphs for other scripts. Emphasis varies by timed unit through the active Paint. Lines follow the common flow, so a line cannot be given a separate face, colour or weight of its own. A caption whose lines are set in different typefaces is outside what this Track can draw.",
+ summary: "Renders an authored CaptionDocument at its already resolved CaptionTiming as one ordinary peer VisualTrack.",
+ appearance: "One block of caption text wrapped into lines inside a rounded Cue box, placed at a Recipe-chosen point in the selected Frame and spanning a fraction of its width. Cues follow the speech one after another, each arriving and leaving with its own motion, and the Words of a Cue either stand there together from its first Frame or uncover as they are spoken. As the speech advances, the Word being spoken, or every Word up to it, is repainted in the active Paint, snapping at the Word boundary or sweeping across the glyphs, and it may take a rule beneath it, a rounded highlight capsule behind it and a brief pop at the moment it becomes the spoken one. That capsule either stands alone on each Atom or grows as one continuous run over everything already read, following the Words across line breaks.\n\nEvery Cue uses the ordered exact font stack its Style names, with fallback faces supplying glyphs for other scripts. Emphasis varies by timed unit through the active Paint. Lines follow the common flow, so a line cannot be given a separate face, colour or weight of its own. A caption whose lines are set in different typefaces is outside what this Caption can draw.",
preview: previewImage("Track.png"),
attributes: [
{ name: "id", kind: "identifier", required: true,
- summary: "Names this Track so its rendered output can be placed in a Film." },
- { name: "document", kind: "reference", required: true, accepts: [narrativeTypes.captionDocument],
- summary: "Chooses the Script-owned CaptionDocument." },
- { name: "timeline", kind: "reference", required: true, accepts: [timelineTypes.track],
- summary: "Chooses the continuous Timeline whose Word anchors give every Cue its time." },
- { name: "regions", kind: "reference", required: false, accepts: [spatialTypes.regionTimeline],
+ summary: "Names this Caption so its rendered visual contribution can be placed in a Film." },
+ { name: "document", kind: "reference", required: true, accepts: [captionTypes.document],
+ summary: "Chooses the source-neutral CaptionDocument." },
+ { name: "timing", kind: "reference", required: true, accepts: [captionTypes.timing],
+ summary: "Chooses resolved absolute timing for this CaptionDocument." },
+ ...temporalContextAttributeVocabulary,
+ { name: "within", kind: "reference", required: true, accepts: [spatialTypes.frame],
+ summary: "Chooses the resolved picture-plane Frame used by Recipe x, y, width and height." },
+ { name: "regions", kind: "reference", required: false, accepts: [regionTrackTypes.track],
summary: "Optionally follows external, frame-exact regions whose ids equal Script Roles, placing a Cue at its measured speaker region's top center and hiding it on null Frames." },
],
children: [{ tag: "Use", cardinality: "many", summary: "Presents complete Cues inside a time window. Later matching Uses replace earlier ones.", attributes: [
@@ -322,13 +325,13 @@ export const captionFineMarkupSurfaces = [
ports: [
{ name: "schedule", type: captionFineTypes.schedule,
summary: "The visible Cue schedule consumed by the renderer and other declared tools." },
- { name: "track", type: compositionTypes.visualTrack,
+ { name: "visual", type: compositionTypes.visualTrack,
summary: "The rendered Caption as one self-contained VisualTrack." },
],
- example: `<caption-fine:Track id="captions" document={story.caption} timeline={speech.timeline}>
+ example: `<caption-fine:Caption id="captions" document={story.caption} timing={story-captions} timeline={film.timeline} within={vertical.bounds}>
<caption-fine:Use style={primary-caption}/>
- <caption-fine:Use during={story.selection.answer} style={answer-caption}/>
-</caption-fine:Track>`,
+ <caption-fine:Use during={story-time.answer} style={answer-caption}/>
+</caption-fine:Caption>`,
notes: [
"Use without time attributes covers the whole Timeline. Role filters content without changing the window.",
"Script Cue breaks organize text; Use windows change presentation without cutting Cues or restarting word timing. A hidden Use still replaces earlier presentation.",
@@ -348,9 +351,9 @@ export const captionFineManifest: ModuleManifest = {
{ module: captionModuleRef },
compositionDependency,
mediaDependency,
- narrativeDependency,
+ spatialDependency,
timelineDependency,
- spatialDependency, temporalDependency,
+ regionTrackDependency, temporalDependency,
],
types: [{ name: captionFineTypes.schedule.name }],
capabilities: [],
@@ -358,9 +361,9 @@ export const captionFineManifest: ModuleManifest = {
{
name: captionFineProducers.schedule.name,
inputs: [
- { name: "caption", type: captionTypes.timedProjection },
+ { name: "timing", type: captionTypes.timing },
{ name: "program", type: captionTypes.program },
- { name: "document", type: narrativeTypes.captionDocument },
+ { name: "document", type: captionTypes.document },
],
outputs: [{ name: "schedule", type: captionFineTypes.schedule }],
needs: [],
@@ -370,8 +373,9 @@ export const captionFineManifest: ModuleManifest = {
inputs: [
{ name: "schedule", type: captionFineTypes.schedule },
{ name: "program", type: captionTypes.program },
- { name: "document", type: narrativeTypes.captionDocument },
+ { name: "document", type: captionTypes.document },
{ name: "timeline", type: timelineTypes.track },
+ { name: "within", type: spatialTypes.frame },
],
outputs: [{ name: "track", type: compositionTypes.visualTrack }],
needs: [],
@@ -381,9 +385,10 @@ export const captionFineManifest: ModuleManifest = {
inputs: [
{ name: "schedule", type: captionFineTypes.schedule },
{ name: "program", type: captionTypes.program },
- { name: "document", type: narrativeTypes.captionDocument },
+ { name: "document", type: captionTypes.document },
{ name: "timeline", type: timelineTypes.track },
- { name: "regions", type: spatialTypes.regionTimeline },
+ { name: "within", type: spatialTypes.frame },
+ { name: "regions", type: regionTrackTypes.track },
],
outputs: [{ name: "track", type: compositionTypes.visualTrack }],
needs: [],
diff --git a/packages/caption-fine/src/render.ts b/packages/caption-fine/src/render.ts
index 7a6471af..17544cff 100644
--- a/packages/caption-fine/src/render.ts
+++ b/packages/caption-fine/src/render.ts
@@ -1,3 +1,4 @@
+import { assertTimelineIdentity, timelineFrameCount } from "@hypit/timeline";
import type { Timeline } from "@hypit/timeline";
import { assertCaptionProgramForDocument } from "@hypit/caption";
import type { CaptionProgram } from "@hypit/caption";
@@ -14,10 +15,11 @@ import type {
VisualTextPaintLayer,
VisualTrack,
} from "@hypit/composition";
-import type { CaptionAlignmentUnit, CaptionDocument, CaptionDisplayWord } from "@hypit/narrative";
-import { assertProgramSpaceIdentity, programSpaceFrameCount } from "@hypit/program-space";
-import { assertSpatialRegionTimeline } from "@hypit/spatial";
-import type { CanvasSpace, SpatialFrame, SpatialRegionTimeline } from "@hypit/spatial";
+import type { CaptionDocument, CaptionDisplayWord, CaptionUnit } from "@hypit/caption";
+import { assertRegionTrack } from "@hypit/region-track";
+import type { RegionTrack } from "@hypit/region-track";
+import { assertSpatialFrame } from "@hypit/spatial";
+import type { SpatialFrame } from "@hypit/spatial";
import { assertFineCaptionParameters, FINE_CAPTION_FAMILY } from "./style.js";
import { assertFineCaptionSchedule } from "./schedule.js";
@@ -598,13 +600,12 @@ function anchorTransform(parameters: FineCaptionParameters): string | undefined
function trackedPlacementAnimation(
parameters: FineCaptionParameters,
frames: readonly (SpatialFrame | null)[],
- canvas: CanvasSpace,
): VisualAnimation {
if (frames.length === 0) throw new Error("Fine Caption tracked placement has no Frames");
const anchor = anchorTransform(parameters);
const transform = (frame: SpatialFrame | null): string => {
- const xPx = frame === null ? parameters.placement.x * canvas.widthPx : frame.xPx + frame.widthPx / 2;
- const yPx = frame === null ? parameters.placement.y * canvas.heightPx : frame.yPx;
+ const xPx = frame === null ? 0 : frame.xPx + frame.widthPx / 2;
+ const yPx = frame === null ? 0 : frame.yPx;
return `translate(${compactNumber(xPx)}px,${compactNumber(yPx)}px)${anchor === undefined ? "" : ` ${anchor}`}`;
};
const keyframes: VisualKeyframe[] = frames.map((frame, atFrame) => ({
@@ -624,7 +625,7 @@ function trackedPlacementAnimation(
return { keyframes };
}
-function structuralRowStarts(atoms: readonly CaptionAlignmentUnit[], maxWordsPerLine?: number): ReadonlySet<number> {
+function structuralRowStarts(atoms: readonly CaptionUnit[], maxWordsPerLine?: number): ReadonlySet<number> {
const starts = new Set<number>();
let wordsOnRow = 0;
for (const [index, atom] of atoms.entries()) {
@@ -643,7 +644,7 @@ function structuralRowStarts(atoms: readonly CaptionAlignmentUnit[], maxWordsPer
* owner: as soon as the next authored unit starts, the previous one stops.
*/
function exclusiveActivationFrames(
- atoms: readonly CaptionAlignmentUnit[],
+ atoms: readonly CaptionUnit[],
atomFrames: ReadonlyMap<string, { readonly start: number; readonly end: number }>,
): ReadonlyMap<string, { readonly start: number; readonly end: number }> {
return new Map(atoms.map((atom, index) => {
@@ -662,15 +663,15 @@ function exclusiveActivationFrames(
}
function cueElements(
- atoms: readonly CaptionAlignmentUnit[],
+ atoms: readonly CaptionUnit[],
atomFrames: ReadonlyMap<string, { readonly start: number; readonly end: number }>,
parameters: FineCaptionParameters,
wordText: ReadonlyMap<string, CaptionDisplayWord>,
durationFrames: number,
styleId: string,
+ within: SpatialFrame,
trackedPlacement?: {
readonly frames: readonly (SpatialFrame | null)[];
- readonly canvas: CanvasSpace;
},
): VisualElement[] {
type UnorderedVisualElement = Omit<VisualBoxElement, "order"> | Omit<VisualTextElement, "order"> | Omit<VisualProgramElement, "order">;
@@ -682,7 +683,7 @@ function cueElements(
};
const placementAnimation = trackedPlacement === undefined
? undefined
- : trackedPlacementAnimation(parameters, trackedPlacement.frames, trackedPlacement.canvas);
+ : trackedPlacementAnimation(parameters, trackedPlacement.frames);
const transform = placementAnimation === undefined
? anchorTransform(parameters)
: (() => {
@@ -730,14 +731,18 @@ function cueElements(
{ name: "display", value: "flex" },
{ name: "justify-content", value: parameters.layout.textAlign === "left" ? "flex-start"
: parameters.layout.textAlign === "right" ? "flex-end" : "center" },
- { name: "left", value: placementAnimation === undefined ? `${compactNumber(parameters.placement.x * 100)}%` : "0px" },
+ { name: "left", value: placementAnimation === undefined
+ ? `${compactNumber(within.xPx + parameters.placement.x * within.widthPx)}px`
+ : "0px" },
{ name: "position", value: "absolute" },
- { name: "top", value: placementAnimation === undefined ? `${compactNumber(parameters.placement.y * 100)}%` : "0px" },
+ { name: "top", value: placementAnimation === undefined
+ ? `${compactNumber(within.yPx + parameters.placement.y * within.heightPx)}px`
+ : "0px" },
...(parameters.placement.height === undefined ? [] : [
- { name: "height", value: `${compactNumber(parameters.placement.height * 100)}%` },
+ { name: "height", value: `${compactNumber(parameters.placement.height * within.heightPx)}px` },
] as const),
...(transform === undefined ? [] : [{ name: "transform", value: transform }] as const),
- { name: "width", value: `${compactNumber(parameters.placement.width * 100)}%` },
+ { name: "width", value: `${compactNumber(parameters.placement.width * within.widthPx)}px` },
],
...(placementAnimation === undefined ? {} : { animation: placementAnimation }),
});
@@ -1077,15 +1082,17 @@ export function renderFineCaption(
program: CaptionProgram,
document: CaptionDocument,
timeline: Timeline,
- regions?: SpatialRegionTimeline,
+ within: SpatialFrame,
+ regions?: RegionTrack,
): VisualTrack {
assertFineCaptionSchedule(schedule);
assertCaptionProgramForDocument(program, document);
if (schedule.documentId !== document.id) throw new Error("Fine Caption received another CaptionDocument");
- assertProgramSpaceIdentity(timeline);
- if (schedule.spaceId !== timeline.id || schedule.narrativeId !== document.narrativeId) {
- throw new Error("Fine Caption inputs belong to different Timelines or Narratives");
+ assertTimelineIdentity(timeline);
+ assertSpatialFrame(within);
+ if (schedule.timelineId !== timeline.id) {
+ throw new Error("Fine Caption inputs belong to different Timelines");
}
const styles = new Map(program.styles.map((style) => [style.id, style]));
const wordText = new Map(document.words.map((word) => [word.id, word]));
@@ -1097,15 +1104,16 @@ export function renderFineCaption(
}
assertFineCaptionParameters(style.rendering.parameters as unknown as FineCaptionParameters);
}
- const totalFrames = programSpaceFrameCount(timeline);
+ const totalFrames = timelineFrameCount(timeline);
const regionTracks = regions === undefined ? undefined : (() => {
- assertSpatialRegionTimeline(regions);
- if (regions.frameCount !== totalFrames) {
- throw new Error(`Fine Caption regions cover ${regions.frameCount} Frames but Timeline has ${totalFrames}`);
+ assertRegionTrack(regions);
+ const regionFrameCount = regions.series[0]!.frames.length;
+ if (regions.timelineId !== timeline.id || regionFrameCount !== totalFrames) {
+ throw new Error(`Fine Caption regions do not cover Timeline ${timeline.id}'s ${totalFrames} Frames`);
}
- return new Map(regions.tracks.map((track) => [track.id, track]));
+ return new Map(regions.series.map((series) => [series.id, series]));
})();
- const presents = schedule.cues.flatMap((cue) => {
+ const presents = schedule.cues.flatMap((cue, order) => {
const atoms = cue.units.map((timing) => atomById.get(timing.unitId));
if (atoms.some((atom) => atom === undefined)) throw new Error(`Fine Caption Cue ${cue.id} references unknown Atom`);
const resolvedAtoms = atoms.map((atom) => atom!);
@@ -1127,7 +1135,6 @@ export function renderFineCaption(
if (track === undefined) return undefined;
return {
frames: track.frames.slice(startFrame, endFrameExclusive),
- canvas: regions!.canvas,
};
})();
const atomFrames = new Map(cue.units.map((atom) => [atom.unitId, {
@@ -1136,14 +1143,15 @@ export function renderFineCaption(
}]));
return [{
id: cue.id,
+ order,
+ z: parameters.stackingOrder,
span: { startFrame, endFrameExclusive },
visibility: cue.visibility,
- stacking: { order: parameters.stackingOrder, tieBreak: `${program.id}:${cue.id}` },
- elements: cueElements(resolvedAtoms, atomFrames, parameters, wordText, durationFrames, cue.styleId, trackedPlacement),
+ elements: cueElements(resolvedAtoms, atomFrames, parameters, wordText, durationFrames, cue.styleId, within, trackedPlacement),
}];
});
const track = sealVisualTrack({
- programSpaceId: timeline.id,
+ timelineId: timeline.id,
visualIr: "hypit.visual-ir@1",
id: program.id,
presents,
diff --git a/packages/caption-fine/src/schedule.ts b/packages/caption-fine/src/schedule.ts
index c1b1af80..556dbf19 100644
--- a/packages/caption-fine/src/schedule.ts
+++ b/packages/caption-fine/src/schedule.ts
@@ -1,6 +1,6 @@
-import { assertCaptionProgramForDocument, assertTimedCaptionProjection, captionUseVisibility } from "@hypit/caption";
-import type { CaptionProgram, TimedCaptionProjection } from "@hypit/caption";
-import type { CaptionDocument } from "@hypit/narrative";
+import { assertCaptionProgramForDocument, assertCaptionTiming, captionUseVisibility } from "@hypit/caption";
+import type { CaptionProgram, CaptionTiming } from "@hypit/caption";
+import type { CaptionDocument } from "@hypit/caption";
import { assertFineCaptionParameters, FINE_CAPTION_FAMILY } from "./style.js";
import type { FineCaptionParameters, FineCaptionSchedule, FineCaptionScheduledCue } from "./types.js";
@@ -12,21 +12,18 @@ function assertIntegerFrame(value: number, label: string): void {
/**
* Resolve visible Cue envelopes before the renderer runs.
*
- * Semantic unit timing stays untouched. `leadFrames` and `tailFrames` only
+ * Resolved unit timing stays untouched. `leadFrames` and `tailFrames` only
* widen the visible envelope, and `cut` prevents adjacent Cues from competing
* for the same handoff interval without shortening either Cue's spoken time.
*/
export function scheduleFineCaption(
- projection: TimedCaptionProjection,
+ timing: CaptionTiming,
program: CaptionProgram,
document: CaptionDocument,
): FineCaptionSchedule {
- assertTimedCaptionProjection(projection);
+ assertCaptionTiming(timing);
assertCaptionProgramForDocument(program, document);
- if (projection.documentId !== document.id) throw new Error("Fine Caption Schedule received another CaptionDocument");
- if (projection.narrativeId !== document.narrativeId) {
- throw new Error("Fine Caption Schedule received a CaptionDocument from another Narrative");
- }
+ if (timing.documentId !== document.id) throw new Error("Fine Caption Schedule received another CaptionDocument");
const parameters = new Map<string, FineCaptionParameters>();
const activeStyles = new Set(program.uses.map(use => use.styleId));
for (const style of program.styles) {
@@ -43,18 +40,18 @@ export function scheduleFineCaption(
const units = new Map(document.units.map(unit => [unit.id, unit]));
const cues: FineCaptionScheduledCue[] = [];
for (const [index, use] of program.uses.entries()) {
- if (use.window.start.source.spaceId !== projection.spaceId) throw new Error("Caption Use belongs to another Timeline");
+ if (use.window.start.timelineId !== timing.timelineId) throw new Error("Caption Use belongs to another Timeline");
const style = parameters.get(use.styleId);
if (style === undefined) continue; // Hidden still participates in coverage below.
- const desired = projection.cues.filter(cue => use.role === undefined || units.get(cue.units[0]!.unitId)?.role === use.role).map((cue): FineCaptionScheduledCue => ({
+ const desired = timing.cues.filter(cue => use.role === undefined || units.get(cue.units[0]!.unitId)?.role === use.role).map((cue): FineCaptionScheduledCue => ({
id: `${use.window.subjectId}:${cue.id}`, cueId: cue.id, styleId: use.styleId,
- semanticStartFrame: cue.startFrame, semanticEndFrameExclusive: cue.endFrameExclusive,
+ timedStartFrame: cue.startFrame, timedEndFrameExclusive: cue.endFrameExclusive,
visibleStartFrame: Math.max(0, cue.startFrame - style.timing.leadFrames),
visibleEndFrameExclusive: cue.endFrameExclusive + style.timing.tailFrames,
units: cue.units, visibility: [],
}));
// Resolve each speaker's ordinary Cue handoff before masking by Use windows.
- desired.sort((a, b) => a.semanticStartFrame - b.semanticStartFrame);
+ desired.sort((a, b) => a.timedStartFrame - b.timedStartFrame);
const previousByRole = new Map<string | undefined, number>();
const envelopes: FineCaptionScheduledCue[] = [];
for (const wanted of desired) {
@@ -62,10 +59,10 @@ export function scheduleFineCaption(
const role = units.get(cue.units[0]!.unitId)?.role;
const previousIndex = previousByRole.get(role);
const previous = previousIndex === undefined ? undefined : envelopes[previousIndex];
- if (previous !== undefined && style.timing.handoff === "cut" && previous.semanticEndFrameExclusive <= cue.semanticStartFrame) {
- const previousEnd = Math.max(previous.semanticEndFrameExclusive, Math.min(previous.visibleEndFrameExclusive, cue.semanticStartFrame));
+ if (previous !== undefined && style.timing.handoff === "cut" && previous.timedEndFrameExclusive <= cue.timedStartFrame) {
+ const previousEnd = Math.max(previous.timedEndFrameExclusive, Math.min(previous.visibleEndFrameExclusive, cue.timedStartFrame));
envelopes[previousIndex!] = { ...previous, visibleEndFrameExclusive: previousEnd };
- cue = { ...cue, visibleStartFrame: Math.min(cue.semanticStartFrame, Math.max(cue.visibleStartFrame, previousEnd)) };
+ cue = { ...cue, visibleStartFrame: Math.min(cue.timedStartFrame, Math.max(cue.visibleStartFrame, previousEnd)) };
}
previousByRole.set(role, envelopes.length);
envelopes.push(cue);
@@ -81,27 +78,26 @@ export function scheduleFineCaption(
for (const cue of cues) {
if (ids.has(cue.id)) throw new Error(`Fine Caption Schedule repeats Cue ${cue.id}`);
ids.add(cue.id);
- assertIntegerFrame(cue.semanticStartFrame, `Fine Caption Cue ${cue.id} semantic start`);
- assertIntegerFrame(cue.semanticEndFrameExclusive, `Fine Caption Cue ${cue.id} semantic end`);
+ assertIntegerFrame(cue.timedStartFrame, `Fine Caption Cue ${cue.id} timed start`);
+ assertIntegerFrame(cue.timedEndFrameExclusive, `Fine Caption Cue ${cue.id} timed end`);
assertIntegerFrame(cue.visibleStartFrame, `Fine Caption Cue ${cue.id} visible start`);
assertIntegerFrame(cue.visibleEndFrameExclusive, `Fine Caption Cue ${cue.id} visible end`);
- if (cue.semanticEndFrameExclusive <= cue.semanticStartFrame
- || cue.visibleStartFrame > cue.semanticStartFrame
- || cue.visibleEndFrameExclusive < cue.semanticEndFrameExclusive
+ if (cue.timedEndFrameExclusive <= cue.timedStartFrame
+ || cue.visibleStartFrame > cue.timedStartFrame
+ || cue.visibleEndFrameExclusive < cue.timedEndFrameExclusive
|| cue.visibleEndFrameExclusive <= cue.visibleStartFrame) {
throw new Error(`Fine Caption Cue ${cue.id} has an invalid visible envelope`);
}
}
return {
- spaceId: projection.spaceId,
- narrativeId: projection.narrativeId,
+ timelineId: timing.timelineId,
documentId: document.id,
cues,
};
}
export function assertFineCaptionSchedule(value: FineCaptionSchedule): void {
- if (!value.spaceId || !value.narrativeId || !value.documentId) {
+ if (!value.timelineId || !value.documentId) {
throw new Error("Fine Caption Schedule provenance is empty");
}
const ids = new Set<string>();
@@ -115,14 +111,14 @@ export function assertFineCaptionSchedule(value: FineCaptionSchedule): void {
|| span.startFrame < cue.visibleStartFrame || span.endFrameExclusive > cue.visibleEndFrameExclusive
|| span.endFrameExclusive <= span.startFrame)) throw new Error("Fine Caption visibility is invalid");
for (const [label, frame] of [
- ["semantic start", cue.semanticStartFrame],
- ["semantic end", cue.semanticEndFrameExclusive],
+ ["timed start", cue.timedStartFrame],
+ ["timed end", cue.timedEndFrameExclusive],
["visible start", cue.visibleStartFrame],
["visible end", cue.visibleEndFrameExclusive],
] as const) assertIntegerFrame(frame, `Fine Caption Cue ${cue.id} ${label}`);
- if (cue.semanticEndFrameExclusive <= cue.semanticStartFrame
- || cue.visibleStartFrame > cue.semanticStartFrame
- || cue.visibleEndFrameExclusive < cue.semanticEndFrameExclusive
+ if (cue.timedEndFrameExclusive <= cue.timedStartFrame
+ || cue.visibleStartFrame > cue.timedStartFrame
+ || cue.visibleEndFrameExclusive < cue.timedEndFrameExclusive
|| cue.visibleEndFrameExclusive <= cue.visibleStartFrame) {
throw new Error(`Fine Caption Cue ${cue.id} has an invalid visible envelope`);
}
diff --git a/packages/caption-fine/src/spacing.ts b/packages/caption-fine/src/spacing.ts
index 98fe8c19..eefa2335 100644
--- a/packages/caption-fine/src/spacing.ts
+++ b/packages/caption-fine/src/spacing.ts
@@ -1,4 +1,4 @@
-import type { CaptionDisplayWord } from "@hypit/narrative";
+import type { CaptionDisplayWord } from "@hypit/caption";
type Surface = Pick<CaptionDisplayWord, "text" | "separatorBefore">;
diff --git a/packages/caption-fine/src/surface.ts b/packages/caption-fine/src/surface.ts
index 9303a3cb..d2dd4ea4 100644
--- a/packages/caption-fine/src/surface.ts
+++ b/packages/caption-fine/src/surface.ts
@@ -1,8 +1,8 @@
-import { captionTypes, captionProducers } from "@hypit/caption";
+import { captionProducers, captionTypes } from "@hypit/caption";
import { assertFontArtifactRef, assertFontStackRef, mediaTypes } from "@hypit/media";
import type { FontArtifactRef, FontStackRef } from "@hypit/media";
-import { narrativeTypes } from "@hypit/narrative";
import { timelineTypes } from "@hypit/timeline";
+import { regionTrackTypes } from "@hypit/region-track";
import { spatialTypes } from "@hypit/spatial";
import { svsRecipeType } from "@hypit/svs";
import type { SvsRecipe } from "@hypit/svs";
@@ -17,7 +17,7 @@ import { sealGraphFragment } from "@hypit/elaborator";
import type { FragmentOperation } from "@hypit/elaborator";
import type { SurfaceRecordDraft, SurfaceComponentDraft } from "@hypit/markup";
import { assertEmptyElement, optionalTextAttribute } from "@hypit/markup";
-import { createTemporalWindowProjection, resolveTemporalContext, temporalWindowAttributeNames } from "@hypit/temporal-markup";
+import { createTemporalWindowConstruction, resolveTemporalContext, temporalWindowAttributeNames } from "@hypit/temporal-markup";
import { temporalTypes } from "@hypit/temporal";
import { compositionTypes } from "@hypit/composition";
import { captionFineProducers, captionFineTypes } from "./manifest.js";
@@ -123,30 +123,32 @@ export const decodeFineCaptionStyleSurface: StructuredSurfaceHandler = ({ elemen
};
export const decodeFineCaptionTrackSurface: StructuredSurfaceHandler = ({ element, resolveReference }) => {
- attributes(element, ["id", "document", "timeline"], ["regions"]);
+ attributes(element, ["id", "document", "timing", "timeline", "within"], ["regions"]);
const id = stringAttribute(element, "id");
- const document = reference(element, "document", narrativeTypes.captionDocument, resolveReference);
+ const document = reference(element, "document", captionTypes.document, resolveReference);
+ const timing = reference(element, "timing", captionTypes.timing, resolveReference);
+ const within = reference(element, "within", spatialTypes.frame, resolveReference);
const context = resolveTemporalContext({ element, resolveReference });
- const regions = element.attributes.regions === undefined ? undefined : reference(element, "regions", spatialTypes.regionTimeline, resolveReference);
+ const regions = element.attributes.regions === undefined ? undefined : reference(element, "regions", regionTrackTypes.track, resolveReference);
const records: SurfaceRecordDraft[] = [{ id: `${id}.header`, type: captionTypes.header,
value: { kind: "inline", value: { id } }, range: element.range }];
const components: SurfaceComponentDraft[] = [];
const fragments: ReturnType<typeof sealGraphFragment>[] = [];
- const inputs: { name: string; type: SurfaceResolvedReference["type"] }[] = [{ name: "document", type: narrativeTypes.captionDocument }, { name: "timeline", type: timelineTypes.track }, { name: "header", type: captionTypes.header }];
- const bindings: Record<string, SurfaceResolvedReference["ref"]> = { document: document.ref, timeline: context.timeline.ref, header: { kind: "record", id: `${id}.header` } };
+ const inputs: { name: string; type: SurfaceResolvedReference["type"] }[] = [{ name: "document", type: captionTypes.document }, { name: "timing", type: captionTypes.timing }, { name: "timeline", type: timelineTypes.track }, { name: "within", type: spatialTypes.frame }, { name: "header", type: captionTypes.header }];
+ const bindings: Record<string, SurfaceResolvedReference["ref"]> = { document: document.ref, timing: timing.ref, timeline: context.timeline.ref, within: within.ref, header: { kind: "record", id: `${id}.header` } };
const operations: FragmentOperation[] = [{ id: "create", producer: captionProducers.create,
inputs: { document: input("document"), header: input("header") }, result: { kind: "output", name: "program" } }];
let previous = "create", index = 0;
for (const child of element.children) {
- if (child.kind === "text") { if (child.value.trim()) throw new Error("Caption Track accepts Use children."); continue; }
- if (localName(child.name) !== "Use") throw new Error("Caption Track accepts Use children.");
+ if (child.kind === "text") { if (child.value.trim()) throw new Error("Caption accepts Use children."); continue; }
+ if (localName(child.name) !== "Use") throw new Error("Caption accepts Use children.");
attributes(child, ["style"], ["id", "role", ...temporalWindowAttributeNames]);
assertEmptyElement(child);
index += 1;
const useId = optionalTextAttribute(child, "id") ?? `${id}.use.${index}`;
const hasTime = temporalWindowAttributeNames.some(name => child.attributes[name] !== undefined);
- const temporal = createTemporalWindowProjection({ id: useId, ...context, resolveReference,
- element: hasTime ? child : { ...child, attributes: { ...child.attributes, during: "program" } } });
+ const temporal = createTemporalWindowConstruction({ id: useId, ...context, resolveReference,
+ element: hasTime ? child : { ...child, attributes: { ...child.attributes, during: "timeline" } } });
records.push(...temporal.records); components.push(...temporal.components); fragments.push(...temporal.fragments);
const style = reference(child, "style", captionTypes.style, resolveReference);
const role = optionalTextAttribute(child, "role");
@@ -159,21 +161,18 @@ export const decodeFineCaptionTrackSurface: StructuredSurfaceHandler = ({ elemen
inputs: { program: operation(previous), window: input(`${key}-window`), style: input(`${key}-style`), filter: input(`${key}-filter`) }, result: { kind: "output", name: "program" } });
previous = key;
}
- operations.push({ id: "content", producer: captionProducers.temporalizeDocument,
- inputs: { document: input("document"), timeline: input("timeline") }, result: { kind: "output", name: "caption" } });
operations.push({ id: "schedule", producer: captionFineProducers.schedule,
- inputs: { caption: operation("content"), document: input("document"), program: operation(previous) }, result: { kind: "output", name: "schedule" } });
- if (regions !== undefined) { inputs.push({ name: "regions", type: spatialTypes.regionTimeline }); bindings.regions = regions.ref; }
+ inputs: { timing: input("timing"), document: input("document"), program: operation(previous) }, result: { kind: "output", name: "schedule" } });
+ if (regions !== undefined) { inputs.push({ name: "regions", type: regionTrackTypes.track }); bindings.regions = regions.ref; }
operations.push({ id: "render", producer: regions === undefined ? captionFineProducers.render : captionFineProducers.renderWithRegions,
- inputs: { schedule: operation("schedule"), document: input("document"), timeline: input("timeline"), program: operation(previous), ...(regions === undefined ? {} : { regions: input("regions") }) }, result: { kind: "output", name: "track" } });
+ inputs: { schedule: operation("schedule"), document: input("document"), timeline: input("timeline"), within: input("within"), program: operation(previous), ...(regions === undefined ? {} : { regions: input("regions") }) }, result: { kind: "output", name: "track" } });
const collector = sealGraphFragment({ inputs, operations, exports: [
- { name: "content", type: captionTypes.timedProjection, root: operation("content") },
{ name: "program", type: captionTypes.program, root: operation(previous) },
{ name: "schedule", type: captionFineTypes.schedule, root: operation("schedule") },
- { name: "track", type: compositionTypes.visualTrack, root: operation("render") },
+ { name: "visual", type: compositionTypes.visualTrack, root: operation("render") },
] });
fragments.push(collector);
components.push({ id, fragment: collector.id, inputs: bindings,
- outputs: { content: `${id}.content`, program: `${id}.program`, schedule: `${id}.schedule`, track: `${id}.track` }, range: element.range });
- return { records, components, fragments, exports: [`${id}.content`, `${id}.program`, `${id}.schedule`, `${id}.track`] };
+ outputs: { program: `${id}.program`, schedule: `${id}.schedule`, visual: `${id}.visual` }, range: element.range });
+ return { records, components, fragments, exports: [`${id}.program`, `${id}.schedule`, `${id}.visual`] };
};
diff --git a/packages/caption-fine/src/types.ts b/packages/caption-fine/src/types.ts
index d6eb1160..0f295bd3 100644
--- a/packages/caption-fine/src/types.ts
+++ b/packages/caption-fine/src/types.ts
@@ -1,4 +1,4 @@
-import type { TimedCaptionUnit } from "@hypit/caption";
+import type { CaptionTimingUnit } from "@hypit/caption";
import type { FontArtifactRef } from "@hypit/media";
export type FineCaptionGlyphPaint = {
@@ -161,7 +161,7 @@ export type FineCaptionParameters = {
readonly loopIntensity: number;
};
/**
- * Public rules for projecting semantic Cue time into its visible envelope.
+ * Public rules for expanding resolved Cue time into its visible envelope.
* The renderer never expands a Cue on its own; the package's schedule
* Producer resolves these rules before rendering.
*/
@@ -177,17 +177,16 @@ export type FineCaptionScheduledCue = {
readonly visibility: readonly { readonly startFrame: number; readonly endFrameExclusive: number }[];
readonly id: string;
readonly styleId: string;
- readonly semanticStartFrame: number;
- readonly semanticEndFrameExclusive: number;
+ readonly timedStartFrame: number;
+ readonly timedEndFrameExclusive: number;
readonly visibleStartFrame: number;
readonly visibleEndFrameExclusive: number;
- readonly units: readonly TimedCaptionUnit[];
+ readonly units: readonly CaptionTimingUnit[];
};
-/** Explicit projection consumed by the Fine renderer. */
+/** Explicit presentation schedule consumed by the Fine renderer. */
export type FineCaptionSchedule = {
- readonly spaceId: string;
- readonly narrativeId: string;
+ readonly timelineId: string;
readonly documentId: string;
readonly cues: readonly FineCaptionScheduledCue[];
};
diff --git a/packages/caption-fine/test/caption-fine.test.ts b/packages/caption-fine/test/caption-fine.test.ts
index d4aa4b85..c17e73c1 100644
--- a/packages/caption-fine/test/caption-fine.test.ts
+++ b/packages/caption-fine/test/caption-fine.test.ts
@@ -1,13 +1,13 @@
import { projectProgramWindow } from "../../../test/temporal-fixture.js";
import { sealTimeline } from "@hypit/timeline";
+import type { Timeline } from "@hypit/timeline";
import assert from "node:assert/strict";
import test from "node:test";
-import type { CaptionProgram, TimedCaptionProjection } from "@hypit/caption";
+import type { CaptionProgram, CaptionTiming } from "@hypit/caption";
import type { FontArtifactRef } from "@hypit/media";
-import { sealProgramSpace } from "@hypit/program-space";
import { captionDocument, parseScript } from "@hypit/script";
-import type { SpatialRegionTimeline } from "@hypit/spatial";
+import type { RegionTrack } from "@hypit/region-track";
import type { SvsRecipe } from "@hypit/svs";
import { fixtureResource } from "../../../test/fixture-resource.js";
@@ -18,6 +18,18 @@ import {
scheduleFineCaption,
} from "../src/index.js";
+const bounds = { xPx: 0, yPx: 0, widthPx: 1080, heightPx: 1920 } as const;
+
+function renderCaption(
+ schedule: Parameters<typeof renderFineCaption>[0],
+ program: CaptionProgram,
+ document: Parameters<typeof renderFineCaption>[2],
+ timeline: Timeline,
+ regions?: RegionTrack,
+) {
+ return renderFineCaption(schedule, program, document, timeline, bounds, regions);
+}
+
const font: FontArtifactRef = {
sources: [{ artifact: {
kind: "blob",
@@ -75,15 +87,14 @@ function fixture(script = "<line>one two || three four</line>") {
documentId: document.id,
styles: [style],
uses: [{ styleId: style.id, window: projectProgramWindow({ itemId: "captions.use.1",
- semantic: sealTimeline({ id: "test-space", durationSec: 3, frameRate: { numerator: 30, denominator: 1 }, items: [] }),
- projection: { start: { ref: "program.start" }, end: { ref: "program.end" } },
+ semantic: sealTimeline({ id: "test-space", frameCount: 90, frameRate: { numerator: 30, denominator: 1 } }),
+ projection: { start: { ref: "timeline.start" }, end: { ref: "timeline.end" } },
}) }],
};
const [first, second, third, fourth] = document.units;
assert.ok(first && second && third && fourth);
- const projection: TimedCaptionProjection = {
- spaceId: "test-space",
- narrativeId: "story",
+ const projection: CaptionTiming = {
+ timelineId: "test-space",
documentId: document.id,
cues: [
{
@@ -122,15 +133,15 @@ test("Fine Caption schedules visibility outside semantic Word timing and cuts on
const { document, program, projection } = fixture();
const schedule = scheduleFineCaption(projection, program, document);
assert.deepEqual(schedule.cues.map((cue) => ({
- semantic: [cue.semanticStartFrame, cue.semanticEndFrameExclusive],
+ semantic: [cue.timedStartFrame, cue.timedEndFrameExclusive],
visible: [cue.visibleStartFrame, cue.visibleEndFrameExclusive],
})), [
{ semantic: [10, 30], visible: [6, 36] },
{ semantic: [36, 56], visible: [36, 62] },
]);
- const track = renderFineCaption(schedule, program, document,
- sealTimeline({ items: [], id: "test-space", durationSec: 3, frameRate: { numerator: 30, denominator: 1 } }));
+ const track = renderCaption(schedule, program, document,
+ sealTimeline({ id: "test-space", frameCount: 90, frameRate: { numerator: 30, denominator: 1 } }));
assert.deepEqual(track.presents.map((present) => present.span), [
{ startFrame: 6, endFrameExclusive: 36 },
{ startFrame: 36, endFrameExclusive: 62 },
@@ -156,12 +167,11 @@ test("Fine Caption uniformly springs the whole Cue through exact scales", () =>
},
}, [font]);
const animatedProgram: CaptionProgram = { ...program, styles: [style] };
- const track = renderFineCaption(
+ const track = renderCaption(
scheduleFineCaption(projection, animatedProgram, document),
animatedProgram,
document,
- sealTimeline({ items: [], id: "test-space", durationSec: 3,
- frameRate: { numerator: 30, denominator: 1 } }),
+ sealTimeline({ id: "test-space", frameCount: 90, frameRate: { numerator: 30, denominator: 1 } }),
);
const cueMotion = track.presents[0]?.elements.find((element) => element.id === "cue-motion");
const cueLoop = track.presents[0]?.elements.find((element) => element.id === "cue-loop");
@@ -192,19 +202,17 @@ test("Fine Caption follows measured Role regions and hides null Frames", () => {
const { document, program, projection } = fixture(`<line>
<BOY>one two || three four
</line>`);
- const space = sealTimeline({ items: [], id: "test-space", durationSec: 3,
- frameRate: { numerator: 30, denominator: 1 } });
- const regions: SpatialRegionTimeline = {
- canvas: { widthPx: 1080, heightPx: 1920, origin: "top-left", xDirection: "right", yDirection: "down", pixelAspect: "square" },
- frameCount: 90,
- tracks: [{
+ const space = sealTimeline({ id: "test-space", frameCount: 90, frameRate: { numerator: 30, denominator: 1 } });
+ const regions: RegionTrack = {
+ timelineId: space.id,
+ series: [{
id: "BOY",
frames: Array.from({ length: 90 }, (_, frame) => frame === 7 ? null : ({
xPx: 100 + frame, yPx: 300 + frame, widthPx: 200, heightPx: 240,
})),
}],
};
- const track = renderFineCaption(scheduleFineCaption(projection, program, document), program, document, space, regions);
+ const track = renderCaption(scheduleFineCaption(projection, program, document), program, document, space, regions);
const placement = track.presents[0]?.elements.find((element) => element.id === "placement");
const declarationAt = (frame: number, name: string): string | number | undefined =>
placement?.animation?.keyframes[frame]?.style.find((declaration) => declaration.name === name)?.value;
@@ -220,20 +228,32 @@ test("Fine Caption keeps authored placement when a Cue Role has no measured trac
const { document, program, projection } = fixture(`<line>
<BOY>one two || three four
</line>`);
- const space = sealTimeline({ items: [], id: "test-space", durationSec: 3,
- frameRate: { numerator: 30, denominator: 1 } });
- const regions: SpatialRegionTimeline = {
- canvas: { widthPx: 1080, heightPx: 1920, origin: "top-left", xDirection: "right", yDirection: "down", pixelAspect: "square" },
- frameCount: 90,
- tracks: [{ id: "WIFE", frames: Array.from({ length: 90 }, () => null) }],
+ const space = sealTimeline({ id: "test-space", frameCount: 90, frameRate: { numerator: 30, denominator: 1 } });
+ const regions: RegionTrack = {
+ timelineId: space.id,
+ series: [{ id: "WIFE", frames: Array.from({ length: 90 }, () => null) }],
};
- const track = renderFineCaption(scheduleFineCaption(projection, program, document), program, document, space, regions);
+ const track = renderCaption(scheduleFineCaption(projection, program, document), program, document, space, regions);
const placement = track.presents[0]?.elements.find((element) => element.id === "placement");
- assert.equal(placement?.style.find((declaration) => declaration.name === "left")?.value, "50%");
- assert.equal(placement?.style.find((declaration) => declaration.name === "top")?.value, "90%");
+ assert.equal(placement?.style.find((declaration) => declaration.name === "left")?.value, "540px");
+ assert.equal(placement?.style.find((declaration) => declaration.name === "top")?.value, "1728px");
assert.equal(placement?.animation, undefined);
});
+test("Fine Caption resolves authored placement inside an arbitrary picture-plane Frame", () => {
+ const { document, program, projection } = fixture();
+ const timeline = sealTimeline({ id: "test-space", frameCount: 90,
+ frameRate: { numerator: 30, denominator: 1 } });
+ const track = renderFineCaption(scheduleFineCaption(projection, program, document), program, document, timeline,
+ { xPx: 100, yPx: 200, widthPx: 500, heightPx: 800 });
+ const placement = track.presents[0]?.elements.find((element) => element.id === "placement");
+ const value = (name: string) => placement?.style.find((declaration) => declaration.name === name)?.value;
+ assert.equal(value("left"), "350px");
+ assert.equal(value("top"), "920px");
+ assert.equal(value("width"), "400px");
+ assert.equal(value("height"), "192px");
+});
+
test("Fine Caption rejects a Cue that exceeds its structural row budget instead of clipping Paint", () => {
const { document, program, projection } = fixture();
const constrained = fineCaptionStyle("plain", {
@@ -243,9 +263,8 @@ test("Fine Caption rejects a Cue that exceeds its structural row budget instead
const constrainedProgram: CaptionProgram = { ...program, styles: [constrained] };
const schedule = scheduleFineCaption(projection, constrainedProgram, document);
assert.throws(
- () => renderFineCaption(schedule, constrainedProgram, document,
- sealTimeline({ items: [], id: "test-space", durationSec: 3,
- frameRate: { numerator: 30, denominator: 1 } })),
+ () => renderCaption(schedule, constrainedProgram, document,
+ sealTimeline({ id: "test-space", frameCount: 90, frameRate: { numerator: 30, denominator: 1 } })),
/constructs 2 rows.+maximum is 1/u,
);
});
@@ -257,9 +276,8 @@ test("Fine Caption gives a hidden Style no Cue, background or decoration", () =>
uses: program.uses.map(use => ({ ...use, styleId: hidden.id })) };
const hiddenProjection = { ...projection, cues: [] };
const schedule = scheduleFineCaption(hiddenProjection, hiddenProgram, document);
- const visual = renderFineCaption(schedule, hiddenProgram, document,
- sealTimeline({ items: [], id: "test-space", durationSec: 3,
- frameRate: { numerator: 30, denominator: 1 } }));
+ const visual = renderCaption(schedule, hiddenProgram, document,
+ sealTimeline({ id: "test-space", frameCount: 90, frameRate: { numerator: 30, denominator: 1 } }));
assert.deepEqual(schedule.cues, []);
assert.deepEqual(visual.presents, []);
});
@@ -272,7 +290,7 @@ test("Fine Caption gives overlapping acoustic Words one current Karaoke owner",
}, [font]);
const karaokeProgram: CaptionProgram = { ...program, styles: [style] };
const firstCue = projection.cues[0]!;
- const overlapped: TimedCaptionProjection = {
+ const overlapped: CaptionTiming = {
...projection,
cues: [{
...firstCue,
@@ -282,12 +300,11 @@ test("Fine Caption gives overlapping acoustic Words one current Karaoke owner",
],
}, projection.cues[1]!],
};
- const track = renderFineCaption(
+ const track = renderCaption(
scheduleFineCaption(overlapped, karaokeProgram, document),
karaokeProgram,
document,
- sealTimeline({ items: [], id: "test-space", durationSec: 3,
- frameRate: { numerator: 30, denominator: 1 } }),
+ sealTimeline({ id: "test-space", frameCount: 90, frameRate: { numerator: 30, denominator: 1 } }),
);
const firstActive = track.presents[0]?.elements.find((element) => element.id === "atom-1-active");
const secondActive = track.presents[0]?.elements.find((element) => element.id === "atom-2-active");
@@ -306,7 +323,7 @@ function unevenChineseCaption(properties: SvsRecipe["properties"] = {}) {
...recipe, properties: { ...flow, ...properties },
}, [font]);
const windows = [[10, 13], [13, 32], [36, 42], [42, 55]] as const;
- const timed: TimedCaptionProjection = {
+ const timed: CaptionTiming = {
...projection,
cues: [{ ...projection.cues[0]!, endFrameExclusive: 55,
units: document.units.map((unit, index) => ({ unitId: unit.id,
@@ -314,8 +331,8 @@ function unevenChineseCaption(properties: SvsRecipe["properties"] = {}) {
}],
};
const styled = { ...program, styles: [style] };
- const track = renderFineCaption(scheduleFineCaption(timed, styled, document), styled, document,
- sealTimeline({ items: [], id: "test-space", durationSec: 3, frameRate: { numerator: 30, denominator: 1 } }));
+ const track = renderCaption(scheduleFineCaption(timed, styled, document), styled, document,
+ sealTimeline({ id: "test-space", frameCount: 90, frameRate: { numerator: 30, denominator: 1 } }));
return { track, windows };
}
@@ -335,8 +352,8 @@ for (const mode of ["current", "trail"] as const) test(`shared-text groups use e
karaoke: mode, "karaoke-transition": "step", "active-box": mode, "active-underline": mode,
} }, [font]);
const styled = { ...program, styles: [style] };
- return renderFineCaption(scheduleFineCaption(projection, styled, document), styled, document,
- sealTimeline({ items: [], id: "test-space", durationSec: 3, frameRate: { numerator: 30, denominator: 1 } }));
+ return renderCaption(scheduleFineCaption(projection, styled, document), styled, document,
+ sealTimeline({ id: "test-space", frameCount: 90, frameRate: { numerator: 30, denominator: 1 } }));
};
const track = make('<line><动效|><组件化|> || <直接|><复用|></line>');
assert.deepEqual(track, make('<line><动效|动效><组件化|组件化> || <直接|直接><复用|复用></line>'));
@@ -410,8 +427,8 @@ test("Typewriter keeps combining graphemes whole and preserves unequal-width Lat
const style = fineCaptionStyle("plain", { ...recipe,
properties: { ...recipe.properties, "atom-reveal": "typewriter" } }, [font]);
const styled = { ...program, styles: [style] };
- const track = renderFineCaption(scheduleFineCaption(projection, styled, document), styled, document,
- sealTimeline({ items: [], id: "test-space", durationSec: 3, frameRate: { numerator: 30, denominator: 1 } }));
+ const track = renderCaption(scheduleFineCaption(projection, styled, document), styled, document,
+ sealTimeline({ id: "test-space", frameCount: 90, frameRate: { numerator: 30, denominator: 1 } }));
const text = track.presents[0]!.elements.filter((element) => element.kind === "text");
assert.deepEqual(text.map((element) => element.text), ["W", "i", "e\u0301"]);
assert.equal(numericStyleAt(text[0]!, 4, "opacity"), 1);
@@ -429,10 +446,10 @@ test("Caption handoff follows placed time and retains simultaneous spoken envelo
endFrameExclusive: unit.endFrameExclusive - 16 })) };
// Reverse declaration order: placement decides temporal neighbors, not Script order.
const schedule = scheduleFineCaption({ ...projection, cues: [overlapping, first] }, program, document);
- assert.deepEqual(schedule.cues.map(cue => [cue.semanticStartFrame, cue.semanticEndFrameExclusive]), [[10, 30], [20, 40]]);
+ assert.deepEqual(schedule.cues.map(cue => [cue.timedStartFrame, cue.timedEndFrameExclusive]), [[10, 30], [20, 40]]);
assert.deepEqual(schedule.cues.map(cue => [cue.visibleStartFrame, cue.visibleEndFrameExclusive]), [[6, 36], [16, 46]]);
- const track = renderFineCaption(schedule, program, document,
- sealTimeline({ items: [], id: "test-space", durationSec: 3, frameRate: { numerator: 30, denominator: 1 } }));
+ const track = renderCaption(schedule, program, document,
+ sealTimeline({ id: "test-space", frameCount: 90, frameRate: { numerator: 30, denominator: 1 } }));
assert.equal(track.presents.filter(present => present.span.startFrame <= 25 && present.span.endFrameExclusive > 25).length, 2);
});
@@ -440,17 +457,17 @@ test("Caption handoff follows placed time and retains simultaneous spoken envelo
test("Caption Surface wires one Timeline to both ordinary and tracked-region rendering", async () => {
const { decodeFineCaptionTrackSurface } = await import("../src/surface.js");
const { timelineTypes } = await import("@hypit/timeline");
- const { narrativeTypes } = await import("@hypit/narrative");
const { captionTypes } = await import("@hypit/caption");
+ const { regionTrackTypes } = await import("@hypit/region-track");
const { spatialTypes } = await import("@hypit/spatial");
- const types = { timeline: timelineTypes.track, document: narrativeTypes.captionDocument,
- program: captionTypes.program, regions: spatialTypes.regionTimeline };
+ const types = { timeline: timelineTypes.track, document: captionTypes.document,
+ timing: captionTypes.timing, within: spatialTypes.frame, program: captionTypes.program, regions: regionTrackTypes.track };
for (const tracking of [false, true]) {
- const names = tracking ? ["timeline", "document", "regions"] as const
- : ["timeline", "document"] as const;
+ const names = tracking ? ["timeline", "document", "timing", "within", "regions"] as const
+ : ["timeline", "document", "timing", "within"] as const;
const attributes = Object.fromEntries(names.map(name => [name, { kind: "reference" as const, path: name }]));
const result = await decodeFineCaptionTrackSurface({ sourceName: "caption.svml",
- element: { kind: "element", name: "fine:Track", attributes: { id: "captions", ...attributes },
+ element: { kind: "element", name: "fine:Caption", attributes: { id: "captions", ...attributes },
children: [], range: { start: 0, end: 1 } },
resolveReference(path) {
const type = types[path as keyof typeof types];
@@ -462,15 +479,14 @@ test("Caption Surface wires one Timeline to both ordinary and tracked-region ren
const fragment = result.fragments!.find(fragment => fragment.id === component.fragment)!;
assert.deepEqual(Object.keys(component.inputs).sort(), fragment.inputs.map(input => input.name).sort());
assert.deepEqual(component.inputs.timeline, { kind: "record", id: "timeline" });
- assert.equal(fragment.operations.some(operation => operation.producer.name === "project-program-space"), false);
}
});
test("a Use beginning inside a Cue changes presentation without changing words or animation time", () => {
const { document, program } = fixture("<line>test1 || test2 @{select} test3 || test4 @{/select}</line>");
- const timeline = sealTimeline({ id: "test-space", durationSec: 3, frameRate: { numerator: 30, denominator: 1 }, items: [] });
+ const timeline = sealTimeline({ id: "test-space", frameCount: 90, frameRate: { numerator: 30, denominator: 1 } });
const unit = (index: number) => ({ unitId: document.units[index]!.id, startFrame: 10 + index * 10, endFrameExclusive: 20 + index * 10 });
- const projection: TimedCaptionProjection = { spaceId: timeline.id, narrativeId: "story", documentId: document.id, cues: [
+ const projection: CaptionTiming = { timelineId: timeline.id, documentId: document.id, cues: [
{ id: "c1", startFrame: 10, endFrameExclusive: 20, units: [unit(0)] },
{ id: "c2", startFrame: 20, endFrameExclusive: 40, units: [unit(1), unit(2)] },
{ id: "c3", startFrame: 40, endFrameExclusive: 50, units: [unit(3)] },
@@ -484,13 +500,13 @@ test("a Use beginning inside a Cue changes presentation without changing words o
assert.deepEqual(parts.map(cue=>cue.units), [[unit(1),unit(2)],[unit(1),unit(2)]]);
assert.deepEqual(parts.map(cue=>cue.visibility), [[{startFrame:20,endFrameExclusive:30}],[{startFrame:30,endFrameExclusive:40}]]);
assert.deepEqual(parts.map(cue=>cue.visibleStartFrame),[20,20]);
- const track = renderFineCaption(schedule,changed,document,timeline);
+ const track = renderCaption(schedule,changed,document,timeline);
const entered = track.presents.find(present=>present.id === parts[1]!.id)!;
assert.equal(entered.span.startFrame,20);
assert.deepEqual(entered.visibility,[{startFrame:30,endFrameExclusive:40}]);
// Rendering the same Style over the whole timeline has identical animation data for this Cue.
const whole: CaptionProgram = {...changed,uses:[{styleId:emphasis.id,window:window("whole",0,90)}]};
- const original = renderFineCaption(scheduleFineCaption(projection,whole,document),whole,document,timeline).presents.find(p=>p.id.endsWith(":c2"))!;
+ const original = renderCaption(scheduleFineCaption(projection,whole,document),whole,document,timeline).presents.find(p=>p.id.endsWith(":c2"))!;
assert.deepEqual(entered.elements,original.elements);
const hidden: CaptionProgram = {...changed,styles:[...changed.styles,{id:"hidden",rendering:null}],uses:[...changed.uses,{styleId:"hidden",window:window("hide",32,35)}]};
@@ -502,13 +518,13 @@ test("a Use beginning inside a Cue changes presentation without changing words o
test("Caption time windows select presentation, while Role filters preserve simultaneous speakers", () => {
const { document, program, projection } = fixture("<line><A>one two || <B>three four</line>");
- const timeline = sealTimeline({id:"test-space",durationSec:3,frameRate:{numerator:30,denominator:1},items:[]});
- const overlap: TimedCaptionProjection = {...projection,cues:[projection.cues[0]!,{
+ const timeline = sealTimeline({id:"test-space",frameCount: 90, frameRate: { numerator: 30, denominator: 1 }});
+ const overlap: CaptionTiming = {...projection,cues:[projection.cues[0]!,{
...projection.cues[1]!,startFrame:15,endFrameExclusive:35,
units:projection.cues[1]!.units.map((u,i)=>({...u,startFrame:15+i*10,endFrameExclusive:25+i*10})),
}]};
const hidden: CaptionProgram = {...program,styles:[...program.styles,{id:"hidden",rendering:null}],uses:[...program.uses,{
- role:"A",styleId:"hidden",window:projectProgramWindow({itemId:"hideA",semantic:timeline,projection:{start:{ref:"program.start"},end:{ref:"program.end"}}}),
+ role:"A",styleId:"hidden",window:projectProgramWindow({itemId:"hideA",semantic:timeline,projection:{start:{ref:"timeline.start"},end:{ref:"timeline.end"}}}),
}]};
const schedule = scheduleFineCaption(overlap,hidden,document);
assert.equal(schedule.cues.length,1);
@@ -518,30 +534,33 @@ test("Caption time windows select presentation, while Role filters preserve simu
assert.deepEqual(scheduleFineCaption(projection,{...program,uses:[],styles:[]},document).cues,[]);
});
-test("Caption Track Uses share the temporal author language and reject the removed Program edge", async () => {
+test("Caption Uses share the temporal author language and reject the removed Program edge", async () => {
const { decodeFineCaptionTrackSurface } = await import("../src/surface.js");
const { parseStructuredElement } = await import("@hypit/markup");
const { timelineTypes } = await import("@hypit/timeline");
- const { narrativeTypes } = await import("@hypit/narrative");
const { captionTypes } = await import("@hypit/caption");
- const refs: Record<string, import("@hypit/protocol").TypeRef> = { timeline: timelineTypes.track, document: narrativeTypes.captionDocument, style: captionTypes.style, selection:narrativeTypes.selection, moment:narrativeTypes.moment };
+ const { temporalTypes } = await import("@hypit/temporal");
+ const { spatialTypes } = await import("@hypit/spatial");
+ const refs: Record<string, import("@hypit/protocol").TypeRef> = { timeline: timelineTypes.track, document: captionTypes.document,
+ timing: captionTypes.timing, within: spatialTypes.frame,
+ style: captionTypes.style, window: temporalTypes.window, instant: temporalTypes.instant };
const decode = async (body:string,extra="") => decodeFineCaptionTrackSurface({sourceName:"caption.svml",
- element:parseStructuredElement({name:"caption.svml",text:`<fine:Track id="captions" document={document} timeline={timeline} ${extra}>${body}</fine:Track>`},0).element,
+ element:parseStructuredElement({name:"caption.svml",text:`<fine:Caption id="captions" document={document} timing={timing} timeline={timeline} within={within} ${extra}>${body}</fine:Caption>`},0).element,
resolveReference(path){const type=refs[path];return type===undefined?undefined:{path,type,ref:{kind:"record" as const,id:path}};},
resolveAsset(){throw new Error("No assets");},
});
- for (const time of ['', 'during={selection}', 'at={moment} for="2s"', 'until={moment} for="12f"', 'start="2s" end="5s"']) {
+ for (const time of ['', 'during={window}', 'from="2s" for="2s"', 'until="3s" for="12f"', 'from="2s" until="5s"']) {
const result=await decode(`<fine:Use style={style} ${time}/>`);
const track=result.components.find(component=>component.id==="captions")!;
assert.ok(track.outputs.program);
- assert.ok(track.outputs.content);
const fragment=result.fragments!.find(fragment=>fragment.id===track.fragment)!;
- assert.equal(fragment.operations.find(op=>op.id==="content")?.result.name,"caption");
+ assert.equal(fragment.inputs.find(port=>port.name==="timing")?.type.name,"CaptionTiming");
assert.ok(fragment.inputs.some(port=>port.name.endsWith("-window")));
assert.equal(fragment.inputs.some(port=>port.name==="program"),false);
}
- await assert.rejects(()=>decode('', 'program={old}'),/requires id, document, timeline/);
- await assert.rejects(()=>decode('<fine:Use style={style} selection={selection}/>'),/requires exactly one/);
+ await assert.rejects(()=>decode('<fine:Use style={style}/>', 'semantic={window}'));
+ await assert.rejects(()=>decode('', 'program={old}'),/requires id, document, timing, timeline, within/);
+ await assert.rejects(()=>decode('<fine:Use style={style} selection={window}/>'),/optional id, role, during, from, until, for/);
});
test("Fine uses author separators in ordinary text, shared groups, active copies and joined boxes", () => {
@@ -553,12 +572,12 @@ test("Fine uses author separators in ordinary text, shared groups, active copies
const styled = { ...program, styles: [style] };
const render = (source: string) => {
const document = captionDocument(parseScript("spacing", `<line>${source}</line>`), "story.caption", "story");
- const timed: TimedCaptionProjection = { ...projection, cues: [{ ...projection.cues[0]!,
+ const timed: CaptionTiming = { ...projection, cues: [{ ...projection.cues[0]!,
startFrame: 10, endFrameExclusive: 70,
units: document.units.map((unit, index) => ({ unitId: unit.id, startFrame: 10 + index * 5, endFrameExclusive: 15 + index * 5 })),
}] };
- return renderFineCaption(scheduleFineCaption(timed, styled, document), styled, document,
- sealTimeline({ items: [], id: "test-space", durationSec: 3, frameRate: { numerator: 30, denominator: 1 } })).presents[0]!.elements;
+ return renderCaption(scheduleFineCaption(timed, styled, document), styled, document,
+ sealTimeline({ id: "test-space", frameCount: 90, frameRate: { numerator: 30, denominator: 1 } })).presents[0]!.elements;
};
const grouped = render("<3개월 만에|> 완료했습니다");
for (const id of ["atom-1-base-2", "atom-1-active-2", "atom-1-underline-2"]) {
diff --git a/packages/caption-fine/test/layout.browser.test.ts b/packages/caption-fine/test/layout.browser.test.ts
index 79c88f21..b71039a2 100644
--- a/packages/caption-fine/test/layout.browser.test.ts
+++ b/packages/caption-fine/test/layout.browser.test.ts
@@ -16,19 +16,21 @@ const executablePath = process.env.HYPIT_CAPTURE_TEST_BROWSER ?? await captureBr
function cueHtml(source: string, width: number, extra: SvsRecipe["properties"]): string {
const document = captionDocument(parseScript("layout", `<line>${source}</line>`), "caption", "story");
- const timeline = sealTimeline({ id: "timeline", items: [], durationSec: 4, frameRate: { numerator: 30, denominator: 1 } });
+ const timeline = sealTimeline({ id: "timeline", frameCount: 120, frameRate: { numerator: 30, denominator: 1 } });
const style = fineCaptionStyle("plain", { path: "caption", properties: {
align: "center", background: "#00000000", fill: "#000000", "line-height": 1.2,
"anchor-x": "left", "anchor-y": "top", padding: "0", radius: 0, "stack-order": 1, size: 36, width: 1, x: 0, y: 0, "word-gap": 14, "inline-size": "fixed",
karaoke: "trail", "active-box": "trail", "active-box-continuity": "joined", "active-box-padding": "0", "active-box-background": "#00800080", "active-box-radius": 0, ...extra,
} }, [{ sources: [{ artifact: { kind: "blob", resource: fixtureResource("font"), size: 1, mediaType: "font/woff2" } }], weight: 400, style: "normal" }]);
const program = { id: "p", documentId: document.id, styles: [style], uses: [{ styleId: "plain",
- window: projectProgramWindow({ itemId: "use", semantic: timeline, projection: { start: { ref: "program.start" }, end: { ref: "program.end" } } }),
+ window: projectProgramWindow({ itemId: "use", semantic: timeline, projection: { start: { ref: "timeline.start" }, end: { ref: "timeline.end" } } }),
}] };
- const timed = { spaceId: timeline.id, narrativeId: "story", documentId: document.id, cues: [{ id: "cue", startFrame: 0, endFrameExclusive: 90,
+ const timed = { timelineId: timeline.id, documentId: document.id, cues: [{ id: "cue", startFrame: 0,
+ endFrameExclusive: document.units.length * 5,
units: document.units.map((unit, index) => ({ unitId: unit.id, startFrame: index * 5, endFrameExclusive: index * 5 + 5 })),
}] };
- const track = renderFineCaption(scheduleFineCaption(timed, program, document), program, document, timeline);
+ const track = renderFineCaption(scheduleFineCaption(timed, program, document), program, document, timeline,
+ { xPx: 0, yPx: 0, widthPx: width, heightPx: 500 });
const compiled = compileHyperframesDocument(sealComposition({ id: "test",
canvas: { width, height: 500, clearColor: "#ffffff" }, tracks: [track] }), timeline);
// Both copies use the same face. Exact-font loading is exercised by renderer integration.
diff --git a/packages/caption/README.md b/packages/caption/README.md
index 6f47a526..ed6b748c 100644
--- a/packages/caption/README.md
+++ b/packages/caption/README.md
@@ -3,31 +3,36 @@
External components import `@hypit/hypit/caption`. Source uses the `@hypit/caption@1` Module
identity for shared declarations such as `Hidden`.
-Caption has two independent structures: Script organizes displayed words into Cues, and timed Uses
+Caption has independent content, timing and presentation structures: CaptionDocument organizes
+displayed words into Cues, CaptionTiming locates those units, and timed Uses
choose how those Cues appear. A Use may begin inside a Cue. It changes presentation without changing
that Cue's text or restarting its word timing.
-`CaptionDocument` owns displayed words with authored separators, display/pronunciation associations, word attributes and `||`
-breaks. `Timeline` owns placed Takes and measured word times. `temporalizeCaptionDocument(document,
-timeline)` joins their identities and returns `TimedCaptionProjection`: complete Cues with original
-unit times. Segment, speaking-turn and explicit Cue boundaries organize this content. No Style is
-needed for this operation. Unplaced material contributes no Cue.
+`CaptionDocument` owns displayed words with authored separators, display units, word attributes and
+Cue breaks. It contains no Narrative identities or time. `CaptionTiming` independently owns complete
+Cues and absolute unit windows on one Timeline. A domain adapter can produce that timing from speech,
+SRT/VTT can publish it directly, and authored absolute timing can use the same renderer.
-A rendering family's Track accepts `document`, `timeline` and ordered `Use` children. Fine provides:
+A rendering family's Track accepts `document`, `timing`, `timeline`, the spatial inputs its renderer
+actually needs and ordered `Use` children. Fine takes one placement Frame:
```svml
<caption:Hidden id="hidden"/>
-<caption-fine:Track id="captions" document={story.caption} timeline={film.timeline}>
+<narrative-caption:Timing id="story-captions" document={story.caption}
+ binding={story.caption-binding} projection={story-time.projection}/>
+<caption-fine:Caption id="captions" document={story.caption} timing={story-captions}
+ timeline={film.timeline} within={vertical.bounds}>
<caption-fine:Use style={plain}/>
<caption-fine:Use role="GUEST" style={guest}/>
- <caption-fine:Use during={story.selection.demo} style={hidden}/>
- <caption-fine:Use at={story.moment.key} for="2s" style={impact}/>
-</caption-fine:Track>
+ <caption-fine:Use during={demo-window} style={hidden}/>
+ <caption-fine:Use from="12s" for="2s" style={impact}/>
+</caption-fine:Caption>
```
-Time attributes come from `@hypit/temporal-markup`: `during`, `at`/`for`, `until`/`for`, and
-`start`/`end`, including semantic references and explicit frame/second expressions. Omitted time
-attributes mean the whole Timeline. `role` filters content independently of time. Later matching
+Time attributes come from `@hypit/temporal-markup`: `during`, or exactly two of `from`, `until`, and
+`for`, including resolved temporal references and explicit frame/second expressions. Omitted time
+attributes mean the whole Timeline. Domain adapters must resolve semantic or other domain references
+to ordinary absolute Windows/Instants before a Caption family consumes them. `role` filters content independently of time. Later matching
Uses replace earlier presentation inside their windows, including a Hidden Style. Separate Tracks
remain independent and can intentionally display simultaneous captions.
@@ -41,11 +46,11 @@ The public helpers and Types are in [index.ts](src/index.ts):
- `CaptionStyleIntent` carries a family identifier and parameters, or `rendering: null` for Hidden.
- `CaptionProgram` is the Track's internal collection of ordered, resolved Uses and referenced Styles.
It is not a separate author element. `create-caption-uses` and `append-caption-use` assemble it from
- typed Windows. The Track may export it for its Companion, like Performance and Sound.
+ typed Windows. The Track may export it for its Companion, like Visual and Audio Clips.
- `captionUseVisibility(program, index, role, envelope)` intersects a Cue envelope with a Use and
subtracts later matching windows. Hidden participates even though it renders nothing.
-- `captionProducers.temporalizeDocument` takes only `document` and `timeline`. Its output retains
- `spaceId`, `narrativeId`, `documentId`, Cue identities and measured alignment-unit boundaries.
+- `CaptionTiming` retains only `timelineId`, `documentId`, Cue identities and absolute unit windows.
+ Narrative-specific binding and projection belong to `@hypit/narrative-caption`.
Derive layout and animation from complete Cue content and original timing. Apply Use coverage as a
visibility mask. Fine keeps the original Present span and element animations, with separate
@@ -56,8 +61,8 @@ winning Use window. Empty content produces no drawing.
Word attributes remain on `CaptionDocument.words`. A structural family can interpret an explicit
attribute as a keyword role while retaining complete display/alignment units. Time selection does
not split `<display|speech>` text, and elapsed Cue progress is not a replacement for word timing.
-The content query helpers for Role, Selection and attributes remain available for components that
-actually need authored word subsets; those queries do not define the Use time language.
+The content query helpers for Role and attributes remain here. Narrative Selection-to-unit queries
+belong to `@hypit/narrative-caption`; neither defines the Use time language.
See Fine's [Surface](../caption-fine/src/surface.ts), [schedule](../caption-fine/src/schedule.ts) and
[renderer](../caption-fine/src/render.ts) for a concrete implementation. New family behavior belongs
diff --git a/packages/caption/package.json b/packages/caption/package.json
index 91987b8c..bdb39761 100644
--- a/packages/caption/package.json
+++ b/packages/caption/package.json
@@ -12,18 +12,9 @@
},
"dependencies": {
"@hypit/component-kit": "workspace:*",
- "@hypit/elaborator": "workspace:*",
- "@hypit/narrative": "workspace:*",
"@hypit/protocol": "workspace:*",
- "@hypit/timeline": "workspace:*",
"@hypit/markup": "workspace:*",
"@hypit/temporal": "workspace:*"
},
- "devDependencies": {
- "@hypit/program-space": "workspace:*",
- "@hypit/script": "workspace:*",
- "@hypit/speech": "workspace:*",
- "@hypit/speech-alignment": "workspace:*",
- "@hypit/speech-evidence": "workspace:*"
- }
+ "devDependencies": {}
}
diff --git a/packages/caption/src/component.ts b/packages/caption/src/component.ts
index 09690c72..fad0de1d 100644
--- a/packages/caption/src/component.ts
+++ b/packages/caption/src/component.ts
@@ -1,14 +1,13 @@
import type { TemporalWindow } from "@hypit/temporal";
import type { ComponentPackage } from "@hypit/component-kit";
-import type { CaptionDocument } from "@hypit/narrative";
-import type { Timeline } from "@hypit/timeline";
import type { StoredValue } from "@hypit/protocol";
import { canonicalize } from "@hypit/protocol";
import { captionProducers, captionTypes } from "./manifest.js";
import { appendCaptionUse, assertCaptionProgram, assertCaptionStyle } from "./style.js";
-import { assertTimedCaptionProjection, temporalizeCaptionDocument } from "./temporalize.js";
-import type { CaptionProgram, CaptionStyleIntent, TimedCaptionProjection } from "./types.js";
+import { assertCaptionDocumentIdentity } from "./identity.js";
+import { assertCaptionTiming } from "./temporalize.js";
+import type { CaptionDocument, CaptionProgram, CaptionStyleIntent, CaptionTiming } from "./types.js";
function inline<T>(value: StoredValue | undefined, subject: string): T {
if (value?.kind !== "inline") throw new Error(`${subject} must be inline`);
@@ -31,23 +30,15 @@ export const captionComponent = {
inline<CaptionStyleIntent>(inputs.style?.value, "CaptionStyle"),
inline<{role?:string}>(inputs.filter?.value, "CaptionContentFilter").role,
)) } }, needs: {} }),
- }, {
- producer: captionProducers.temporalizeDocument,
- handler: ({ inputs }) => ({
- outputs: { caption: { kind: "inline", value: canonicalize(temporalizeCaptionDocument(
- inline<CaptionDocument>(inputs.document?.value, "CaptionDocument"),
- inline<Timeline>(inputs.timeline?.value, "Timeline"),
- )) } },
- needs: {},
- }),
}],
validators: [
+ { type: captionTypes.document, handler: ({ value }) => assertCaptionDocumentIdentity(inline<CaptionDocument>(value, "CaptionDocument")) },
{ type: captionTypes.style, handler: ({ value }) => {
if (value.kind !== "inline") throw new Error("CaptionStyle must be inline");
const style = value.value as CaptionStyleIntent;
assertCaptionStyle(style);
} },
{ type: captionTypes.program, handler: ({ value }) => assertCaptionProgram(inline<CaptionProgram>(value, "CaptionProgram")) },
- { type: captionTypes.timedProjection, handler: ({ value }) => assertTimedCaptionProjection(inline<TimedCaptionProjection>(value, "TimedCaptionProjection")) },
+ { type: captionTypes.timing, handler: ({ value }) => assertCaptionTiming(inline<CaptionTiming>(value, "CaptionTiming")) },
],
} satisfies ComponentPackage;
diff --git a/packages/caption/src/display.ts b/packages/caption/src/display.ts
index bd479a5c..62883f70 100644
--- a/packages/caption/src/display.ts
+++ b/packages/caption/src/display.ts
@@ -1,5 +1,4 @@
-import { narrativeSelectionTokenRange } from "@hypit/narrative";
-import type { CaptionDocument, Narrative, NarrativeSelection } from "@hypit/narrative";
+import type { CaptionDocument } from "./types.js";
function assert(condition: unknown, message: string): asserts condition {
if (!condition) throw new Error(message);
@@ -16,12 +15,10 @@ export function assertCaptionDocument(value: CaptionDocument): void {
for (const unit of value.units) {
assert(unit.id.length > 0 && !units.has(unit.id), "CaptionDocument unit ids are repeated");
units.add(unit.id);
- assert(unit.wordIds.length > 0 && unit.sourceTokenIds.length > 0, `Caption unit ${unit.id} is empty`);
+ assert(unit.wordIds.length > 0, `Caption unit ${unit.id} is empty`);
for (const wordId of unit.wordIds) {
const word = words.get(wordId);
assert(word !== undefined && word.unitId === unit.id, `Caption unit ${unit.id} references a foreign word`);
- assert(word.segmentId === unit.segmentId && word.turnId === unit.turnId && word.role === unit.role,
- `Caption unit ${unit.id} disagrees with its word context`);
orderedWordIds.push(wordId);
}
}
@@ -40,32 +37,6 @@ export type CaptionUnitSubset = {
readonly unitIds: readonly string[];
};
-/** Project a semantic Selection to complete authored N:M Caption units. */
-export function captionUnitsForSelection(
- narrative: Narrative,
- selection: NarrativeSelection,
-): CaptionUnitSubset {
- const document = narrative.caption;
- assertCaptionDocument(document);
- const { tokenStart: start, tokenEndExclusive: end } = narrativeSelectionTokenRange(narrative, selection);
- const tokenPositions = new Map(narrative.tokens.map((token, index) => [token.id, index]));
- const unitIds: string[] = [];
- for (const unit of document.units) {
- const positions = unit.sourceTokenIds.map((tokenId) => tokenPositions.get(tokenId));
- assert(positions.every((position): position is number => position !== undefined),
- `Caption unit ${unit.id} references a token outside Narrative`);
- const unitStart = Math.min(...positions as number[]);
- const unitEnd = Math.max(...positions as number[]) + 1;
- if (unitStart >= end || unitEnd <= start) continue;
- if (unitStart < start || unitEnd > end) {
- throw new Error(`Caption Selection ${selection.id} partially selects Alignment Unit ${unit.id}`);
- }
- unitIds.push(unit.id);
- }
- if (unitIds.length === 0) throw new Error(`Caption Selection ${selection.id} selects no complete display unit`);
- return { documentId: document.id, unitIds };
-}
-
export function captionUnitsForRole(document: CaptionDocument, role: string): CaptionUnitSubset {
assertCaptionDocument(document);
const unitIds = document.units.filter((unit) => unit.role === role).map((unit) => unit.id);
diff --git a/packages/caption/src/error.ts b/packages/caption/src/error.ts
deleted file mode 100644
index c1fcb54c..00000000
--- a/packages/caption/src/error.ts
+++ /dev/null
@@ -1,9 +0,0 @@
-export class CaptionTimingError extends Error {
- readonly code: string;
-
- constructor(code: string, message: string) {
- super(message);
- this.name = "CaptionTimingError";
- this.code = code;
- }
-}
diff --git a/packages/caption/src/fragment.ts b/packages/caption/src/fragment.ts
deleted file mode 100644
index 2e1759fc..00000000
--- a/packages/caption/src/fragment.ts
+++ /dev/null
@@ -1,22 +0,0 @@
-import { narrativeTypes } from "@hypit/narrative";
-import { timelineTypes } from "@hypit/timeline";
-import { sealGraphFragment } from "@hypit/elaborator";
-
-import { captionProducers, captionTypes } from "./manifest.js";
-
-const input = (name: string) => ({ kind: "fragment-input" as const, name });
-const operation = (id: string) => ({ kind: "fragment-operation" as const, operation: id });
-
-export const captionTimingFragment = sealGraphFragment({
- inputs: [
- { name: "document", type: narrativeTypes.captionDocument },
- { name: "timeline", type: timelineTypes.track },
- ],
- operations: [{
- id: "temporalize-caption-document",
- producer: captionProducers.temporalizeDocument,
- inputs: { document: input("document"), timeline: input("timeline") },
- result: { kind: "output", name: "caption" },
- }],
- exports: [{ name: "caption", type: captionTypes.timedProjection, root: operation("temporalize-caption-document") }],
-});
diff --git a/packages/caption/src/identity.ts b/packages/caption/src/identity.ts
new file mode 100644
index 00000000..95262871
--- /dev/null
+++ b/packages/caption/src/identity.ts
@@ -0,0 +1,45 @@
+import type { CaptionDocument } from "./types.js";
+
+function nonempty(value: string, subject: string): void {
+ if (value.trim().length === 0) throw new Error(`${subject} must not be empty.`);
+}
+
+function unique(values: readonly string[], subject: string): Set<string> {
+ const found = new Set<string>();
+ for (const value of values) {
+ nonempty(value, subject);
+ if (found.has(value)) throw new Error(`${subject} repeats ${value}.`);
+ found.add(value);
+ }
+ return found;
+}
+
+/** Validate the source-neutral document identity, including the valid wordless document. */
+export function assertCaptionDocumentIdentity(value: CaptionDocument): void {
+ nonempty(value.id, "CaptionDocument id");
+ if ((value.units.length === 0) !== (value.words.length === 0)) {
+ throw new Error("CaptionDocument units and words must be empty together.");
+ }
+ const unitIds = unique(value.units.map((item) => item.id), "CaptionDocument unit id");
+ const wordIds = unique(value.words.map((item) => item.id), "CaptionDocument word id");
+ const words = new Map(value.words.map((word) => [word.id, word] as const));
+ const orderedWords: string[] = [];
+ for (const unit of value.units) {
+ if (unit.wordIds.length === 0) throw new Error(`Caption unit ${unit.id} is empty.`);
+ for (const wordId of unit.wordIds) {
+ const word = words.get(wordId);
+ if (word === undefined || word.unitId !== unit.id) {
+ throw new Error(`Caption unit ${unit.id} references a foreign word.`);
+ }
+ orderedWords.push(wordId);
+ }
+ }
+ if (orderedWords.length !== wordIds.size
+ || orderedWords.some((id, index) => id !== value.words[index]?.id)) {
+ throw new Error("CaptionDocument units must partition words in order.");
+ }
+ unique(value.cueBreaks.map((item) => item.afterUnitId), "CaptionDocument Cue Break");
+ if (value.cueBreaks.some((item) => !unitIds.has(item.afterUnitId))) {
+ throw new Error("CaptionDocument Cue Break names an unknown unit.");
+ }
+}
diff --git a/packages/caption/src/index.ts b/packages/caption/src/index.ts
index a76760e0..20afa094 100644
--- a/packages/caption/src/index.ts
+++ b/packages/caption/src/index.ts
@@ -1,18 +1,18 @@
-export { CaptionTimingError } from "./error.js";
export {
assertCaptionDocument,
assertCaptionUnitSubset,
captionUnitsForRole,
- captionUnitsForSelection,
} from "./display.js";
export type { CaptionUnitSubset } from "./display.js";
export { captionWordsForAttribute } from "./display.js";
+export { assertCaptionDocumentIdentity } from "./identity.js";
export { captionComponent } from "./component.js";
-export { captionTimingFragment } from "./fragment.js";
export {
+ captionDocumentSchema,
+ captionDependency,
captionProgramSchema,
captionStyleSchema,
- timedCaptionProjectionSchema,
+ captionTimingSchema,
captionManifest,
captionMarkupSurfaces,
captionModuleRef,
@@ -28,7 +28,7 @@ export {
sealCaptionProgram,
sealCaptionStyle,
} from "./style.js";
-export { assertTimedCaptionProjection, temporalizeCaptionDocument } from "./temporalize.js";
+export { assertCaptionTiming } from "./temporalize.js";
export type * from "./types.js";
export { captionUseVisibility } from "./visibility.js";
diff --git a/packages/caption/src/manifest.ts b/packages/caption/src/manifest.ts
index 21ca61b0..cecc1a64 100644
--- a/packages/caption/src/manifest.ts
+++ b/packages/caption/src/manifest.ts
@@ -1,25 +1,41 @@
import { temporalDependency, temporalTypes, temporalWindowSchema } from "@hypit/temporal";
-import { narrativeDependency, narrativeTypes } from "@hypit/narrative";
-import { timelineDependency, timelineTypes } from "@hypit/timeline";
import type { ModuleManifest, ProducerRef, TypeRef, ValueSchema } from "@hypit/protocol";
export const captionModuleRef = { name: "@hypit/caption", version: "1" } as const;
export const captionProducers = {
create: { module: captionModuleRef, name: "create-caption-uses" },
append: { module: captionModuleRef, name: "append-caption-use" },
- temporalizeDocument: { module: captionModuleRef, name: "temporalize-caption-document" },
} satisfies Record<string, ProducerRef>;
export const captionTypes = {
+ document: { module: captionModuleRef, name: "CaptionDocument" },
header: { module: captionModuleRef, name: "CaptionTrackSpec" },
filter: { module: captionModuleRef, name: "CaptionContentFilter" },
style: { module: captionModuleRef, name: "CaptionStyle" },
program: { module: captionModuleRef, name: "CaptionProgram" },
- timedProjection: { module: captionModuleRef, name: "TimedCaptionProjection" },
+ timing: { module: captionModuleRef, name: "CaptionTiming" },
} satisfies Record<string, TypeRef>;
const string = { kind: "string", minLength: 1 } as const;
const integer = { kind: "number", integer: true, minimum: 0 } as const;
const object = (fields: Readonly<Record<string, { readonly schema: ValueSchema; readonly optional?: boolean }>>): ValueSchema => ({ kind: "object", fields });
+const captionDisplayWord = object({
+ separatorBefore: { schema: { kind: "string", enum: ["", " "] } },
+ id: { schema: string }, unitId: { schema: string }, text: { schema: string },
+ attributes: { schema: { kind: "array", items: object({
+ name: { schema: string },
+ value: { schema: { kind: "oneOf", variants: [string, { kind: "number" }, { kind: "boolean" }] } },
+ }) } },
+});
+const captionUnit = object({
+ id: { schema: string }, groupId: { schema: string, optional: true }, role: { schema: string, optional: true },
+ wordIds: { schema: { kind: "array", minItems: 1, items: string } },
+});
+export const captionDocumentSchema: ValueSchema = object({
+ id: { schema: string },
+ units: { schema: { kind: "array", items: captionUnit } },
+ words: { schema: { kind: "array", items: captionDisplayWord } },
+ cueBreaks: { schema: { kind: "array", items: object({ afterUnitId: { schema: string } }) } },
+});
export const captionStyleSchema: ValueSchema = object({
id: { schema: string },
rendering: { schema: { kind: "oneOf", variants: [{ kind: "null" }, object({
@@ -35,9 +51,8 @@ export const captionProgramSchema: ValueSchema = object({
}) } },
});
const timedUnit = object({ unitId: { schema: string }, startFrame: { schema: integer }, endFrameExclusive: { schema: integer } });
-export const timedCaptionProjectionSchema: ValueSchema = object({
- spaceId: { schema: string },
- narrativeId: { schema: string },
+export const captionTimingSchema: ValueSchema = object({
+ timelineId: { schema: string },
documentId: { schema: string },
cues: { schema: { kind: "array", items: object({
id: { schema: string }, startFrame: { schema: integer }, endFrameExclusive: { schema: integer },
@@ -57,24 +72,18 @@ export const captionMarkupSurfaces = [{
export const captionManifest: ModuleManifest = {
format: "hypit.module@1", name: captionModuleRef.name, version: captionModuleRef.version,
- dependencies: [narrativeDependency, timelineDependency, temporalDependency], types: [
- { name: captionTypes.header.name }, { name: captionTypes.filter.name },
- { name: captionTypes.style.name }, { name: captionTypes.program.name }, { name: captionTypes.timedProjection.name },
+ dependencies: [temporalDependency], types: [
+ { name: captionTypes.document.name }, { name: captionTypes.header.name }, { name: captionTypes.filter.name },
+ { name: captionTypes.style.name }, { name: captionTypes.program.name }, { name: captionTypes.timing.name },
], capabilities: [], producers: [{
name: captionProducers.create.name,
- inputs: [{ name: "document", type: narrativeTypes.captionDocument }, { name: "header", type: captionTypes.header }],
+ inputs: [{ name: "document", type: captionTypes.document }, { name: "header", type: captionTypes.header }],
outputs: [{ name: "program", type: captionTypes.program }], needs: [],
}, {
name: captionProducers.append.name,
inputs: [{ name: "program", type: captionTypes.program }, { name: "window", type: temporalTypes.window },
{ name: "style", type: captionTypes.style }, { name: "filter", type: captionTypes.filter }],
outputs: [{ name: "program", type: captionTypes.program }], needs: [],
- }, {
- name: captionProducers.temporalizeDocument.name,
- inputs: [
- { name: "document", type: narrativeTypes.captionDocument },
- { name: "timeline", type: timelineTypes.track },
- ],
- outputs: [{ name: "caption", type: captionTypes.timedProjection }], needs: [],
}],
};
+export const captionDependency = { module: captionModuleRef } as const;
diff --git a/packages/caption/src/style.ts b/packages/caption/src/style.ts
index f37242c5..996c9058 100644
--- a/packages/caption/src/style.ts
+++ b/packages/caption/src/style.ts
@@ -1,10 +1,9 @@
-import type { CaptionDocument } from "@hypit/narrative";
import { canonicalStringify, canonicalize } from "@hypit/protocol";
import { assertCaptionDocument } from "./display.js";
import { assertTemporalWindowFor } from "@hypit/temporal";
import type { TemporalWindow } from "@hypit/temporal";
-import type { CaptionProgram, CaptionStyleIntent } from "./types.js";
+import type { CaptionDocument, CaptionProgram, CaptionStyleIntent } from "./types.js";
const ID = /^[A-Za-z][A-Za-z0-9_.-]{0,127}$/u;
function assert(condition: unknown, message: string): asserts condition { if (!condition) throw new Error(message); }
diff --git a/packages/caption/src/temporalize.ts b/packages/caption/src/temporalize.ts
index 81bb5be6..186bdc1b 100644
--- a/packages/caption/src/temporalize.ts
+++ b/packages/caption/src/temporalize.ts
@@ -1,97 +1,20 @@
-import type { CaptionDocument } from "@hypit/narrative";
-import { projectTimelineSpace, tokenFrameSpan } from "@hypit/timeline";
-import type { Timeline } from "@hypit/timeline";
+import type { CaptionTiming } from "./types.js";
-import { CaptionTimingError } from "./error.js";
-import { assertCaptionDocument } from "./display.js";
-import type { TimedCaptionProjection, TimedCaptionCue, TimedCaptionUnit } from "./types.js";
-
-export function temporalizeCaptionDocument(
- document: CaptionDocument,
- semantic: Timeline,
-): TimedCaptionProjection {
- assertCaptionDocument(document);
- const space = projectTimelineSpace(semantic);
- if (semantic.narrativeId !== undefined && document.narrativeId !== semantic.narrativeId) {
- throw new CaptionTimingError("CAPTION_NARRATIVE", "CaptionDocument and Timeline belong to different Narratives.");
- }
- const breaks = new Set(document.cueBreaks.map((cueBreak) => cueBreak.afterUnitId));
- const timed: Array<{ unit: CaptionDocument["units"][number]; timing: TimedCaptionUnit }> = [];
- const previousByRole = new Map<string | undefined, { timing: TimedCaptionUnit }>();
- for (const unit of document.units) {
- const window = tokenFrameSpan(semantic, unit.sourceTokenIds);
- if (window === undefined) continue;
- if (window.endFrameExclusive < window.startFrame) {
- throw new CaptionTimingError("CAPTION_SPEECH_ORDER", `Caption unit ${unit.id} references speech Tokens in reverse order.`);
- }
- const startFrame = window.startFrame;
- const endFrameExclusive = Math.max(startFrame + 1, window.endFrameExclusive);
- // Acoustic Word windows may overlap. The Timeline keeps those measurements; an authored unit
- // gets one owner: as soon as the next unit of the same Role starts, this one stops. A Cue
- // envelope ends at its last unit, so Cue boundaries are exclusive by the same rule.
- const previous = previousByRole.get(unit.role);
- if (previous !== undefined && startFrame > previous.timing.startFrame && startFrame < previous.timing.endFrameExclusive) {
- previous.timing = { ...previous.timing, endFrameExclusive: startFrame };
- }
- const entry = { unit, timing: { unitId: unit.id, startFrame, endFrameExclusive } };
- previousByRole.set(unit.role, entry);
- timed.push(entry);
- }
- const cues: TimedCaptionCue[] = [];
- let current: { units: TimedCaptionUnit[]; segmentId: string; turnId: string } | undefined;
- const flush = (): void => {
- if (current === undefined || current.units.length === 0) return;
- cues.push({
- id: `${document.id}:cue:${cues.length + 1}`,
- startFrame: current.units[0]!.startFrame,
- endFrameExclusive: current.units.at(-1)!.endFrameExclusive,
- units: current.units,
- });
- current = undefined;
- };
- const documentOrder = new Map(document.units.map((unit, index) => [unit.id, index]));
- for (const [index, entry] of timed.entries()) {
- const previousDocumentUnit = index === 0 ? undefined : timed[index - 1]!.unit;
- const mustBreak = current !== undefined && (
- current.segmentId !== entry.unit.segmentId
- || current.turnId !== entry.unit.turnId
- || (previousDocumentUnit !== undefined && (breaks.has(previousDocumentUnit.id)
- || documentOrder.get(entry.unit.id)! !== documentOrder.get(previousDocumentUnit.id)! + 1))
- );
- if (mustBreak) flush();
- if (current === undefined) current = {
- units: [],
- segmentId: entry.unit.segmentId,
- turnId: entry.unit.turnId,
- };
- current.units.push(entry.timing);
- }
- flush();
- const result: TimedCaptionProjection = {
- spaceId: space.id,
- narrativeId: document.narrativeId,
- documentId: document.id,
- cues,
- };
- assertTimedCaptionProjection(result);
- return result;
-}
-
-export function assertTimedCaptionProjection(projection: TimedCaptionProjection): void {
- if (projection.spaceId.length === 0 || projection.narrativeId.length === 0 || projection.documentId.length === 0) {
- throw new Error("TimedCaptionProjection provenance is invalid");
+export function assertCaptionTiming(timing: CaptionTiming): void {
+ if (timing.timelineId.length === 0 || timing.documentId.length === 0) {
+ throw new Error("CaptionTiming provenance is invalid");
}
const cueIds = new Set<string>();
const unitIds = new Set<string>();
- for (const cue of projection.cues) {
+ for (const cue of timing.cues) {
if (cue.id.length === 0 || cueIds.has(cue.id) || cue.units.length === 0
|| !Number.isSafeInteger(cue.startFrame) || !Number.isSafeInteger(cue.endFrameExclusive)
- || cue.startFrame < 0 || cue.endFrameExclusive <= cue.startFrame) throw new Error("TimedCaptionProjection contains an invalid Cue");
+ || cue.startFrame < 0 || cue.endFrameExclusive <= cue.startFrame) throw new Error("CaptionTiming contains an invalid Cue");
cueIds.add(cue.id);
for (const unit of cue.units) {
if (unit.unitId.length === 0 || unitIds.has(unit.unitId) || !Number.isSafeInteger(unit.startFrame)
|| !Number.isSafeInteger(unit.endFrameExclusive) || unit.startFrame < 0 || unit.endFrameExclusive <= unit.startFrame) {
- throw new Error("TimedCaptionProjection contains an invalid or repeated unit timing");
+ throw new Error("CaptionTiming contains an invalid or repeated unit timing");
}
unitIds.add(unit.unitId);
}
diff --git a/packages/caption/src/types.ts b/packages/caption/src/types.ts
index 69de4f6f..2fd0c743 100644
--- a/packages/caption/src/types.ts
+++ b/packages/caption/src/types.ts
@@ -1,5 +1,42 @@
import type { CanonicalValue } from "@hypit/protocol";
+/** One author-visible word surface. Punctuation owned by the surface is preserved. */
+export type CaptionDisplayWord = {
+ /** Authored display separator from the preceding word; ignored at a displayed line start. */
+ readonly separatorBefore: "" | " ";
+ readonly id: string;
+ readonly unitId: string;
+ readonly text: string;
+ readonly attributes: readonly CaptionWordAttribute[];
+};
+
+export type CaptionWordAttributeValue = string | number | boolean;
+
+export type CaptionWordAttribute = {
+ readonly name: string;
+ readonly value: CaptionWordAttributeValue;
+};
+
+/** The smallest author-declared N:M display unit. It owns no source-domain identity. */
+export type CaptionUnit = {
+ readonly id: string;
+ readonly groupId?: string;
+ readonly role?: string;
+ readonly wordIds: readonly string[];
+};
+
+export type CaptionCueBreak = {
+ readonly afterUnitId: string;
+};
+
+/** Complete display truth. It contains neither semantic identities nor measured time. */
+export type CaptionDocument = {
+ readonly id: string;
+ readonly units: readonly CaptionUnit[];
+ readonly words: readonly CaptionDisplayWord[];
+ readonly cueBreaks: readonly CaptionCueBreak[];
+};
+
export type CaptionStyleIntent = {
readonly id: string;
/** null selects no rendering; later Uses can select a visible Style again. */
@@ -22,23 +59,22 @@ export type CaptionProgram = {
readonly uses: readonly CaptionUse[];
};
-export type TimedCaptionUnit = {
+export type CaptionTimingUnit = {
readonly unitId: string;
readonly startFrame: number;
readonly endFrameExclusive: number;
};
-export type TimedCaptionCue = {
+export type CaptionTimingCue = {
readonly id: string;
readonly startFrame: number;
readonly endFrameExclusive: number;
- readonly units: readonly TimedCaptionUnit[];
+ readonly units: readonly CaptionTimingUnit[];
};
-export type TimedCaptionProjection = {
- /** Semantic Timeline from which every unit frame was measured. */
- readonly spaceId: string;
- readonly narrativeId: string;
+export type CaptionTiming = {
+ /** Absolute Timeline on which every unit Window is resolved. */
+ readonly timelineId: string;
readonly documentId: string;
- readonly cues: readonly TimedCaptionCue[];
+ readonly cues: readonly CaptionTimingCue[];
};
diff --git a/packages/caption/test/caption.test.ts b/packages/caption/test/caption.test.ts
deleted file mode 100644
index 4a94fe1c..00000000
--- a/packages/caption/test/caption.test.ts
+++ /dev/null
@@ -1,37 +0,0 @@
-import assert from "node:assert/strict";
-import test from "node:test";
-
-import { canonicalize } from "@hypit/protocol";
-import {
- assertCaptionProgramForDocument,
- captionUnitsForRole,
- captionUnitsForSelection,
- sealCaptionStyle,
-} from "@hypit/caption";
-import { captionDocument, narrativeValue, parseScript } from "@hypit/script";
-import type { Narrative } from "@hypit/narrative";
-
-test("Caption uses complete semantic selections and authored cue breaks", () => {
- const parsed = parseScript("caption.svml", "<line>one @{focus} two three @{/focus} || four</line>");
- const narrative = narrativeValue(parsed, "story") as unknown as Narrative;
- const document = captionDocument(parsed, "story.caption", "story");
- const selection = narrative.selections[0]!;
- const subset = captionUnitsForSelection(narrative, selection);
- assert.equal(subset.unitIds.length, 2);
- assert.equal(document.cueBreaks.length, 1);
-});
-
-test("Caption selects complete Segments and the program through structural anchors", () => {
- const parsed = parseScript("caption-ranges.svml", `@{~whole}
-@{opening} <intro><HOST>One idea.</intro> @{/opening}
-<answer><GUEST>Another view.</answer>
-@{/whole~}`);
- const narrative = narrativeValue(parsed, "story") as unknown as Narrative;
- const document = captionDocument(parsed, "story.caption", "story");
- const whole = narrative.selections.find((selection) => selection.id === "whole")!;
- const opening = narrative.selections.find((selection) => selection.id === "opening")!;
- assert.deepEqual(captionUnitsForSelection(narrative, whole).unitIds,
- document.units.map((unit) => unit.id));
- assert.deepEqual(captionUnitsForSelection(narrative, opening).unitIds,
- document.units.filter((unit) => unit.segmentId === "intro").map((unit) => unit.id));
-});
diff --git a/packages/caption/test/chinese-pipeline.test.ts b/packages/caption/test/chinese-pipeline.test.ts
deleted file mode 100644
index 4508e096..00000000
--- a/packages/caption/test/chinese-pipeline.test.ts
+++ /dev/null
@@ -1,68 +0,0 @@
-import assert from "node:assert/strict";
-import test from "node:test";
-import type { Narrative } from "@hypit/narrative";
-import { captionDocument, narrativeValue, parseScript } from "@hypit/script";
-import { alignSemanticTake } from "../../speech-alignment/src/index.js";
-import { interpretWhisperXTranscript } from "../../whisperx/src/index.js";
-import { appendTimelineAuthorTake, assembleTimelineAuthor, createTimelineAuthorSet, sealTimelineAuthorHeader } from "../../timeline-author/src/index.js";
-import { selectionFrameSpan } from "@hypit/timeline";
-import { temporalizeCaptionDocument } from "../src/index.js";
-import { fixtureResource } from "../../../test/fixture-resource.js";
-
-for (const grouped of [false, true]) test(`Chinese Script through WhisperX and Timeline preserves caption timing (shared groups: ${grouped})`, () => {
- const parsed = parseScript("mixed-zh.svml", `<opening><HOST>用@{brand} ElevenLabs @{/brand}做${grouped ? '<视频|>' : '视频'},|| 真方便。</opening>
-<answer><GUEST>今年<2026|二零二六>年,這個很好。</answer>`);
- const narrative = narrativeValue(parsed, "story") as unknown as Narrative;
- const document = captionDocument(parsed, "story.caption", "story");
- // Representative WhisperX zh wire output: Han characters and Latin letters carry separate times.
- // These fixtures test transport and mapping, not acoustic recognition accuracy.
- const phrases = ["用ElevenLabs做视频真方便", "今年二零二六年这个很好"];
- const durations = [4000, 3000];
- let set = createTimelineAuthorSet();
- const evidenceWindows: Array<Array<[number, number]>> = [];
- for (const [index, segment] of narrative.segments.entries()) {
- let cursor = 100;
- const words = [...phrases[index]!].map((word, i) => {
- const start = cursor;
- cursor += i % 3 === 0 ? 190 : 90;
- const end = cursor;
- cursor += i % 4 === 0 ? 80 : 20;
- return { word, start: start / 1000, end: end / 1000 };
- });
- evidenceWindows.push(words.map(word => [Math.round(word.start * 1000), Math.round(word.end * 1000)]));
- const sampleFrames = durations[index]! * 16;
- const take = alignSemanticTake(narrative, {
- narrativeId: narrative.id, kind: "segment", id: segment.id,
- tokenStart: segment.tokenStart, tokenEndExclusive: segment.tokenEndExclusive,
- }, {
- timeline: { frameRate: { numerator: 1000, denominator: 1 }, frameCount: durations[index]! },
- audio: { artifact: { kind: "blob", resource: fixtureResource(`zh:${index}`), size: 1, mediaType: "audio/wav" } },
- }, { passages: interpretWhisperXTranscript({ language: "zh", segments: [{ start: 0,
- end: durations[index]! / 1000, words }] }, sampleFrames) });
- set = appendTimelineAuthorTake(set, take);
- }
- const semantic = assembleTimelineAuthor(sealTimelineAuthorHeader({ id: "speech" }), set, { frameRate: { numerator: 1000, denominator: 1 } });
- const projection = temporalizeCaptionDocument(document, semantic);
- const wordText = new Map(document.words.map(word => [word.id, word.text]));
- const unitText = new Map(document.units.map(unit => [unit.id, unit.wordIds.map(id => wordText.get(id)!).join("")]));
- assert.deepEqual(projection.cues.map(cue => cue.units.map(unit => unitText.get(unit.unitId)).join("")),
- ["用ElevenLabs做视频,", "真方便。", "今年2026年,這個很好。"]);
- const units = projection.cues.flatMap(cue => cue.units);
- const windowsFor = (text: string) => units.filter(unit => unitText.get(unit.unitId) === text)
- .map(unit => [unit.startFrame, unit.endFrameExclusive]);
- const first = evidenceWindows[0]!;
- assert.deepEqual(windowsFor("用"), [first[0]]);
- assert.deepEqual(windowsFor("ElevenLabs"), [[first[1]![0], first[10]![1]]]);
- assert.deepEqual(windowsFor("做"), [first[11]]);
- if (grouped) assert.deepEqual(windowsFor("视频,"), [[first[12]![0], first[13]![1]]]);
- assert.deepEqual(semantic.items[0]!.take.tokens.filter(token => ["做", "视", "频"].includes(token.text))
- .map(token => [token.startFrame, token.endFrameExclusive]), first.slice(11, 14));
- const span = selectionFrameSpan(semantic, { ...narrative.selections[0]!, narrativeId: narrative.id });
- assert.deepEqual(span, { startFrame: first[1]![0], endFrameExclusive: first[10]![1] });
- const second = evidenceWindows[1]!;
- assert.deepEqual(windowsFor("2026"), [[4000 + second[2]![0], 4000 + second[5]![1]]]);
- assert.deepEqual(windowsFor("這"), [[4000 + second[7]![0], 4000 + second[7]![1]]]);
- assert.deepEqual(windowsFor("個"), [[4000 + second[8]![0], 4000 + second[8]![1]]]);
- assert.equal(document.units[0]!.role, "HOST");
-
-});
diff --git a/packages/cli/test/build-results.test.ts b/packages/cli/test/build-results.test.ts
index 3eaad1c5..e6417aae 100644
--- a/packages/cli/test/build-results.test.ts
+++ b/packages/cli/test/build-results.test.ts
@@ -193,7 +193,7 @@ test("get exports Resource bytes and a self-contained Composite directory", asyn
const root = await mkdtemp(join(tmpdir(), "hypit-cli-get-"));
const build = "bld_20260902T110000010Z_0000000001";
const videoType = { module: { name: "example.media", version: "1" }, name: "Video" } satisfies TypeRef;
- const takeType = { module: { name: "example.speech", version: "1" }, name: "SemanticTake" } satisfies TypeRef;
+ const compositeType = { module: { name: "example.speech", version: "1" }, name: "CompositeValue" } satisfies TypeRef;
const bytes = new TextEncoder().encode("video bytes");
const video = {
kind: "blob",
@@ -218,13 +218,13 @@ test("get exports Resource bytes and a self-contained Composite directory", asyn
{ id: "record:video", type: videoType, value: video },
{
id: "record:take",
- type: takeType,
+ type: compositeType,
value: { kind: "inline", value: { words: ["hello"], media: { artifact: video } } },
},
],
plan: { outputBindings: [
{ output: "logical:video", record: "record:video", type: videoType },
- { output: "logical:take", record: "record:take", type: takeType },
+ { output: "logical:take", record: "record:take", type: compositeType },
] },
} as unknown as BuildState,
resources: {
diff --git a/packages/comment-sticker/README.md b/packages/comment-sticker/README.md
index 0d1e6bf3..2a364b89 100644
--- a/packages/comment-sticker/README.md
+++ b/packages/comment-sticker/README.md
@@ -21,7 +21,7 @@ The author surface keeps the three independent concerns visible:
<comment:Style id="social-comment" recipe={styles.comment} font={fonts.ui}/>
-<comment:Track id="comments" canvas={video.canvas} timeline={speech.timeline}>
+<comment:Track id="comments" timeline={speech.timeline}>
<comment:Sticker
id="opening-comment"
comment={comment-copy}
@@ -29,7 +29,7 @@ The author surface keeps the three independent concerns visible:
style={social-comment}
author={comment-author}
meta="Featured comment"
- during="program"
+ during="timeline"
/>
</comment:Track>
```
diff --git a/packages/comment-sticker/package.json b/packages/comment-sticker/package.json
index 12c44b38..2a6fbb15 100644
--- a/packages/comment-sticker/package.json
+++ b/packages/comment-sticker/package.json
@@ -4,17 +4,19 @@
"license": "SEE LICENSE IN LICENSE",
"private": true,
"type": "module",
- "exports": { ".": "./src/index.ts" },
- "hypit": { "activation": "./src/activation.ts" },
+ "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/protocol": "workspace:*",
- "@hypit/program-space": "workspace:*",
"@hypit/timeline": "workspace:*",
"@hypit/spatial": "workspace:*",
"@hypit/svs": "workspace:*",
diff --git a/packages/comment-sticker/src/component.ts b/packages/comment-sticker/src/component.ts
index abb1c5a3..05a32db9 100644
--- a/packages/comment-sticker/src/component.ts
+++ b/packages/comment-sticker/src/component.ts
@@ -2,7 +2,7 @@ import type { Timeline } from "@hypit/timeline";
import type { ComponentPackage, ProducerHandlerContext } from "@hypit/component-kit";
import { canonicalize } from "@hypit/protocol";
import type { BlobRef, StoredValue } from "@hypit/protocol";
-import type { CanvasSpace, SpatialFrame } from "@hypit/spatial";
+import type { SpatialFrame } from "@hypit/spatial";
import type { Text } from "@hypit/text";
import { commentStickerProducers, commentStickerTypes } from "./manifest.js";
@@ -84,7 +84,6 @@ export const commentStickerComponent = {
{
producer: commentStickerProducers.render,
handler: ({ inputs }) => ({ outputs: { track: output(renderCommentSticker(
- inline<CanvasSpace>(inputs.canvas?.value, "CanvasSpace"),
inline<Timeline>(inputs.timeline?.value, "Timeline"),
inline<CommentStickerProgram>(inputs.program?.value, "CommentStickerProgram"),
)) }, needs: {} }),
diff --git a/packages/comment-sticker/src/fragment.ts b/packages/comment-sticker/src/fragment.ts
index 9668f17b..9294115c 100644
--- a/packages/comment-sticker/src/fragment.ts
+++ b/packages/comment-sticker/src/fragment.ts
@@ -105,13 +105,12 @@ export function createCommentStickerFragment(items: readonly CommentStickerFragm
{
id: "comment:track",
producer: commentStickerProducers.render,
- inputs: { canvas: input("canvas"), timeline: input("timeline"), program: operation("comment:program") },
+ inputs: { timeline: input("timeline"), program: operation("comment:program") },
result: { kind: "output", name: "track" },
},
);
return sealGraphFragment({
inputs: [
- { name: "canvas", type: spatialTypes.canvas },
{ name: "header", type: commentStickerTypes.header },
{ name: "timeline", type: timelineTypes.track },
...[...types].map(([inputName, type]) => ({ name: inputName, type })),
@@ -119,7 +118,7 @@ export function createCommentStickerFragment(items: readonly CommentStickerFragm
operations,
exports: [
{ name: "program", type: commentStickerTypes.program, root: operation("comment:program") },
- { name: "track", type: compositionTypes.visualTrack, root: operation("comment:track") },
+ { name: "visual", type: compositionTypes.visualTrack, root: operation("comment:track") },
],
});
}
diff --git a/packages/comment-sticker/src/manifest.ts b/packages/comment-sticker/src/manifest.ts
index 6a255f56..287e23d7 100644
--- a/packages/comment-sticker/src/manifest.ts
+++ b/packages/comment-sticker/src/manifest.ts
@@ -1,14 +1,12 @@
-import { timelineTypes } from "@hypit/timeline";
+import { timelineTypes, timelineDependency } from "@hypit/timeline";
import { temporalContextAttributeVocabulary } from "@hypit/temporal-markup";
import { readFile } from "node:fs/promises";
import { artifactDependency, artifactTypes } from "@hypit/artifact";
import { compositionDependency, compositionTypes } from "@hypit/composition";
import { fontArtifactSchema, mediaDependency, mediaTypes } from "@hypit/media";
-import { narrativeDependency } from "@hypit/narrative";
import type { ModuleManifest, ProducerRef, TypeRef, ValueSchema } from "@hypit/protocol";
-import { timelineDependency } from "@hypit/timeline";
import { spatialDependency, spatialFrameSchema, spatialTypes } from "@hypit/spatial";
import { svsRecipeType } from "@hypit/svs";
import { temporalDependency, temporalTypes } from "@hypit/temporal";
@@ -118,7 +116,7 @@ const frameSpan = object({ startFrame: { schema: unsignedInteger }, endFrameExcl
const item = object({
id: { schema: string }, span: { schema: frameSpan },
frame: { schema: spatialFrameSchema }, style: { schema: style }, content: { schema: content },
- avatar: { schema: blobRef, optional: true }, tieBreak: { schema: string },
+ avatar: { schema: blobRef, optional: true }, order: { schema: unsignedInteger },
});
export const commentStickerHeaderSchema: ValueSchema = object({
@@ -268,16 +266,14 @@ export const commentStickerMarkupSurfaces = [
],
},
},
- { name: "track", tag: "Track", mode: "structured", outputs: [textTypes.text, commentStickerTypes.header, commentStickerTypes.itemSpec, temporalTypes.instantSpec, temporalTypes.windowSpec, temporalTypes.instant, temporalTypes.window, commentStickerTypes.program, compositionTypes.visualTrack],
+ { name: "track", tag: "Track", mode: "structured", outputs: [textTypes.text, commentStickerTypes.header, commentStickerTypes.itemSpec, temporalTypes.duration, temporalTypes.extent, temporalTypes.shiftSpec, temporalTypes.instantSpec, temporalTypes.windowSpec, temporalTypes.instant, temporalTypes.window, commentStickerTypes.program, compositionTypes.visualTrack],
vocabulary: {
summary: "Places social comment cards over the Program and renders them as one self-contained VisualTrack.",
- appearance: "One rounded card per Sticker, tilted a couple of degrees and lifted on a soft drop shadow, drawn at the place and size its Frame gives it on the Canvas, with a small triangular speech tail hanging from the card's lower edge. Inside the card a circular avatar sits at the left — the supplied image Artifact, or a filled disc bearing the author's initial — and a text column runs beside it from top to bottom: a small faint header line such as `Reply to @viewer's comment`, then the comment copy in large heavy type wrapped to a few lines and ellipsized, then a small faint metadata row pinned to the card's bottom edge when one is supplied. Each card keeps its own window rather than a shared one: it pops in scaling up and unwinding its tilt, rises and rocks gently while it holds, then fades upward as it leaves. Cards are placed by their Frames alone, so several stand on screen at once and none reflows around another.",
+ appearance: "One rounded card per Sticker, tilted a couple of degrees and lifted on a soft drop shadow, drawn at the place and size its picture-plane Frame gives it, with a small triangular speech tail hanging from the card's lower edge. Inside the card a circular avatar sits at the left — the supplied image Artifact, or a filled disc bearing the author's initial — and a text column runs beside it from top to bottom: a small faint header line such as `Reply to @viewer's comment`, then the comment copy in large heavy type wrapped to a few lines and ellipsized, then a small faint metadata row pinned to the card's bottom edge when one is supplied. Each card keeps its own window rather than a shared one: it pops in scaling up and unwinding its tilt, rises and rocks gently while it holds, then fades upward as it leaves. Cards are placed by their Frames alone, so several stand on screen at once and none reflows around another.",
preview: previewImage("Track.png"),
attributes: [
{ name: "id", kind: "identifier", required: true,
summary: "Names the Track and prefixes every binding it publishes." },
- { name: "canvas", kind: "reference", required: true, accepts: [spatialTypes.canvas],
- summary: "Chooses the Canvas the cards are laid out on." },
...temporalContextAttributeVocabulary,
],
children: [
@@ -287,7 +283,7 @@ export const commentStickerMarkupSurfaces = [
{ name: "id", kind: "identifier", required: true,
summary: "Names this card among the Track's items." },
{ name: "frame", kind: "reference", required: true, accepts: [spatialTypes.frame],
- summary: "Chooses the Frame that places and sizes the card on the Canvas." },
+ summary: "Chooses the picture-plane Frame that places and sizes the card." },
{ name: "style", kind: "reference", required: true, accepts: [commentStickerTypes.style],
summary: "Chooses the Comment Sticker Style the card is drawn and animated in." },
{ name: "comment", kind: "expression", required: false, accepts: [textTypes.text],
@@ -308,20 +304,20 @@ export const commentStickerMarkupSurfaces = [
ports: [
{ name: "program", type: commentStickerTypes.program,
summary: "Every placed card, finalized as one Comment Sticker Program." },
- { name: "track", type: compositionTypes.visualTrack,
+ { name: "visual", type: compositionTypes.visualTrack,
summary: "That Program rendered as one VisualTrack." },
],
example: `
-<comment:Track id="comments" canvas={vertical} timeline={speech.timeline}>
+<comment:Track id="comments" timeline={speech.timeline}>
<comment:Sticker id="one" frame={comment-frame} style={social} avatar={viewer-avatar}
- author="@viewer" meta="Featured" during={story.selection.reaction}>
+ author="@viewer" meta="Featured" during={story-time.reaction}>
Wait, it pinned the caption to the word, not the second.
</comment:Sticker>
</comment:Track>
`,
notes: [
"A Track requires at least one Sticker.",
- "A Sticker states exactly one temporal form: `during`, `at` with `for`, or `start` with `end`.",
+ "A Sticker states one Window form: `during`, or exactly two of `from`, `until` and `for`.",
"With `start` and `end`, `selection` or `moment` binds the point of reference; both together are refused.",
"A Sticker's copy is either `comment` or the element's own text; stating both is refused, and one of the two is required.",
"Stacking order comes from the Style's Recipe, so a Sticker has no `z`.",
@@ -335,7 +331,7 @@ export const commentStickerManifest: ModuleManifest = {
format: "hypit.module@1",
name: commentStickerModuleRef.name,
version: commentStickerModuleRef.version,
- dependencies: [artifactDependency, narrativeDependency, timelineDependency, spatialDependency, temporalDependency, mediaDependency, compositionDependency, textDependency],
+ dependencies: [artifactDependency, timelineDependency, spatialDependency, temporalDependency, mediaDependency, compositionDependency, textDependency],
types: [
{ name: commentStickerTypes.header.name },
{ name: commentStickerTypes.style.name },
@@ -367,7 +363,7 @@ export const commentStickerManifest: ModuleManifest = {
needs: [],
})),
{ name: commentStickerProducers.finalize.name, inputs: [{ name: "set", type: commentStickerTypes.set }, { name: "header", type: commentStickerTypes.header }], outputs: [{ name: "program", type: commentStickerTypes.program }], needs: [] },
- { name: commentStickerProducers.render.name, inputs: [{ name: "canvas", type: spatialTypes.canvas }, { name: "timeline", type: timelineTypes.track }, { name: "program", type: commentStickerTypes.program }], outputs: [{ name: "track", type: compositionTypes.visualTrack }], needs: [] },
+ { name: commentStickerProducers.render.name, inputs: [{ name: "timeline", type: timelineTypes.track }, { name: "program", type: commentStickerTypes.program }], outputs: [{ name: "track", type: compositionTypes.visualTrack }], needs: [] },
],
};
diff --git a/packages/comment-sticker/src/program.ts b/packages/comment-sticker/src/program.ts
index 67d3320c..25509cc3 100644
--- a/packages/comment-sticker/src/program.ts
+++ b/packages/comment-sticker/src/program.ts
@@ -1,3 +1,4 @@
+import { assertTimelineIdentity } from "@hypit/timeline";
import type { Timeline } from "@hypit/timeline";
import {
assertVisualTrackIdentity,
@@ -12,13 +13,12 @@ import type {
VisualTrack,
} from "@hypit/composition";
import { assertFontArtifactRef } from "@hypit/media";
-import { assertProgramSpaceIdentity } from "@hypit/program-space";
import { canonicalize, isResourceId } from "@hypit/protocol";
import type { BlobRef } from "@hypit/protocol";
-import { assertCanvasSpace, assertSpatialFrame } from "@hypit/spatial";
-import type { CanvasSpace, SpatialFrame } from "@hypit/spatial";
+import { assertSpatialFrame } from "@hypit/spatial";
+import type { SpatialFrame } from "@hypit/spatial";
import { assertTemporalWindowFor } from "@hypit/temporal";
-import type { ProjectedWindow } from "@hypit/temporal";
+import type { TemporalWindow } from "@hypit/temporal";
import { verifyText } from "@hypit/text";
import type { Text } from "@hypit/text";
@@ -200,7 +200,7 @@ function realized(
style: CommentStickerStyle,
spec: CommentStickerItemSpec,
content: CommentStickerContent,
- window: ProjectedWindow,
+ window: TemporalWindow,
avatar?: BlobRef,
): CommentStickerSet {
assertCommentStickerSet(set);
@@ -218,7 +218,7 @@ function realized(
style: structuredClone(style),
content: structuredClone(content),
...(avatar === undefined ? {} : { avatar: structuredClone(avatar) }),
- tieBreak: `${header.id}:${spec.id}`,
+ order: set.items.length,
};
const ids = new Set(set.items.map((item) => item.id));
assert(!ids.has(addition.id), `Comment Sticker already contains Item ${addition.id}.`);
@@ -234,10 +234,10 @@ export function appendProjectedCommentSticker(
style: CommentStickerStyle,
spec: CommentStickerItemSpec,
content: CommentStickerContent,
- window: ProjectedWindow,
+ window: TemporalWindow,
avatar?: BlobRef,
): CommentStickerSet {
- assertTemporalWindowFor(window, { subjectId: spec.id, space: timeline });
+ assertTemporalWindowFor(window, { subjectId: spec.id, timeline: timeline });
return realized(set, header, timeline, frame, style, spec, content, window, avatar);
}
@@ -256,7 +256,7 @@ export function assertCommentStickerProgram(value: CommentStickerProgram): void
assertCommentStickerStyle(item.style);
assertCommentStickerContent(item.content);
if (item.avatar !== undefined) assertAvatar(item.avatar);
- assert(item.tieBreak.length > 0, `Comment Sticker Item ${item.id} tie break is empty.`);
+ assert(Number.isSafeInteger(item.order) && item.order >= 0, `Comment Sticker Item ${item.id} order is invalid.`);
}
}
@@ -589,19 +589,19 @@ function stickerElements(item: CommentStickerItemProgram): readonly VisualElemen
return elements;
}
-export function renderCommentSticker(canvas: CanvasSpace, timeline: Timeline, program: CommentStickerProgram): VisualTrack {
- assertCanvasSpace(canvas);
- assertProgramSpaceIdentity(timeline);
+export function renderCommentSticker(timeline: Timeline, program: CommentStickerProgram): VisualTrack {
+ assertTimelineIdentity(timeline);
assertCommentStickerProgram(program);
const track = sealVisualTrack({
- programSpaceId: timeline.id,
+ timelineId: timeline.id,
visualIr: "hypit.visual-ir@1",
id: program.id,
presents: program.items.map((item) => ({
id: item.id,
+ order: item.order,
+ z: item.style.stackingOrder,
subjectId: item.subjectId,
span: { ...item.span },
- stacking: { order: item.style.stackingOrder, tieBreak: item.tieBreak },
elements: stickerElements(item),
})),
});
diff --git a/packages/comment-sticker/src/surface.ts b/packages/comment-sticker/src/surface.ts
index 27fb3ebd..f248439e 100644
--- a/packages/comment-sticker/src/surface.ts
+++ b/packages/comment-sticker/src/surface.ts
@@ -14,7 +14,7 @@ import type {
SurfaceResolvedReference,
MarkupAttributeValue,
} from "@hypit/markup";
-import { createTemporalWindowProjection, temporalWindowAttributeNames } from "@hypit/temporal-markup";
+import { createTemporalWindowConstruction, temporalWindowAttributeNames } from "@hypit/temporal-markup";
import { decodeCommentStickerStyle } from "./author.js";
import { createCommentStickerFragment } from "./fragment.js";
@@ -88,9 +88,8 @@ export const decodeCommentStickerStyleSurface: StructuredSurfaceHandler = ({ ele
};
export const decodeCommentStickerTrackSurface: StructuredSurfaceHandler = ({ element, resolveReference }) => {
- allowed(element, ["id", "canvas", "timeline"], ["id", "canvas", "timeline"]);
+ allowed(element, ["id", "timeline"], ["id", "timeline"]);
const id = text(element, "id");
- const canvas = reference(element.attributes.canvas, `${element.name}.canvas`, spatialTypes.canvas, resolveReference);
const context = resolveTemporalContext({ element, resolveReference });
const headerId = `${id}.__header`;
const records: SurfaceRecordDraft[] = [{
@@ -100,8 +99,8 @@ export const decodeCommentStickerTrackSurface: StructuredSurfaceHandler = ({ ele
range: element.range,
}];
const temporalComponents: SurfaceComponentDraft[] = [];
- const temporalFragments: ReturnType<typeof createTemporalWindowProjection>["fragments"][number][] = [];
- const inputs: Record<string, typeof canvas.ref> = { canvas: canvas.ref, header: { kind: "record", id: headerId }, timeline: context.timeline.ref };
+ const temporalFragments: ReturnType<typeof createTemporalWindowConstruction>["fragments"][number][] = [];
+ const inputs: Record<string, typeof context.timeline.ref> = { header: { kind: "record", id: headerId }, timeline: context.timeline.ref };
const items: Parameters<typeof createCommentStickerFragment>[0][number][] = [];
for (const child of element.children) {
if (child.kind === "text") {
@@ -112,7 +111,7 @@ export const decodeCommentStickerTrackSurface: StructuredSurfaceHandler = ({ ele
if (child.children.some((node) => node.kind === "element")) throw new Error(`${child.name} accepts plain comment text only.`);
allowed(child, ["id", "comment", "frame", "style", "avatar", "author", "header", "meta", ...TIMING], ["id", "frame", "style"]);
const itemId = text(child, "id");
- const temporal = createTemporalWindowProjection({ id: itemId, element: child, ...context, resolveReference });
+ const temporal = createTemporalWindowConstruction({ id: itemId, element: child, ...context, resolveReference });
records.push(...temporal.records); temporalComponents.push(...temporal.components); temporalFragments.push(...temporal.fragments);
const suffix = String(items.length + 1).padStart(4, "0");
const frame = reference(child.attributes.frame, `${child.name}.frame`, spatialTypes.frame, resolveReference);
@@ -164,8 +163,8 @@ export const decodeCommentStickerTrackSurface: StructuredSurfaceHandler = ({ ele
const fragment = createCommentStickerFragment(items);
return {
records,
- components: [...temporalComponents, { id, fragment: fragment.id, inputs, outputs: { program: `${id}.program`, track: `${id}.track` }, range: element.range }],
+ components: [...temporalComponents, { id, fragment: fragment.id, inputs, outputs: { program: `${id}.program`, visual: `${id}.visual` }, range: element.range }],
fragments: [...temporalFragments, fragment],
- exports: [`${id}.program`, `${id}.track`],
+ exports: [`${id}.program`, `${id}.visual`],
};
};
diff --git a/packages/comment-sticker/src/types.ts b/packages/comment-sticker/src/types.ts
index 79d490d3..efdeacd6 100644
--- a/packages/comment-sticker/src/types.ts
+++ b/packages/comment-sticker/src/types.ts
@@ -96,7 +96,7 @@ export type CommentStickerItemProgram = {
readonly style: CommentStickerStyle;
readonly content: CommentStickerContent;
readonly avatar?: BlobRef;
- readonly tieBreak: string;
+ readonly order: number;
};
export type CommentStickerSet = {
diff --git a/packages/comment-sticker/test/comment-sticker.test.ts b/packages/comment-sticker/test/comment-sticker.test.ts
index 5cfd9ebe..6bd4dd25 100644
--- a/packages/comment-sticker/test/comment-sticker.test.ts
+++ b/packages/comment-sticker/test/comment-sticker.test.ts
@@ -1,4 +1,4 @@
-import { sealTimeline } from "@hypit/timeline";
+import { sealTimeline, timelineTypes } from "@hypit/timeline";
import assert from "node:assert/strict";
import test from "node:test";
import { fixtureResource } from "../../../test/fixture-resource.js";
@@ -9,8 +9,6 @@ import { artifactTypes } from "@hypit/artifact";
import { compileHyperframesDocument } from "@hypit/hyperframes";
import type { FontArtifactRef, FontStackRef } from "@hypit/media";
import { mediaTypes } from "@hypit/media";
-import { sealProgramSpace } from "@hypit/program-space";
-import { timelineProducers, timelineTypes } from "@hypit/timeline";
import { spatialTypes } from "@hypit/spatial";
import { svsRecipeType } from "@hypit/svs";
import type { SvsRecipe } from "@hypit/svs";
@@ -49,9 +47,8 @@ const recipe: SvsRecipe = {
};
const style = decodeCommentStickerStyle(recipe, fonts, "social-comment");
const frame = { xPx: 80, yPx: 140, widthPx: 920, heightPx: 360 };
-const canvas = { widthPx: 1080, heightPx: 1920,
- origin: "top-left" as const, xDirection: "right" as const, yDirection: "down" as const, pixelAspect: "square" as const };
-const space = sealTimeline({ items: [], id: "test-space", durationSec: 3, frameRate: { numerator: 30, denominator: 1 } });
+const canvas = { widthPx: 1080, heightPx: 1920 };
+const space = sealTimeline({ id: "test-space", frameCount: 90, frameRate: { numerator: 30, denominator: 1 } });
const header = sealCommentStickerHeader({ id: "comments" });
const semantic = timelineFixture(space);
@@ -72,9 +69,9 @@ function content(meta?: string) {
function track(meta?: string) {
const spec = item("opening");
const set = appendProjectedCommentSticker(createCommentStickerSet(), header, space, frame, style, spec, content(meta), projectProgramWindow({
- itemId: spec.id, semantic, projection: { start: { ref: "program.start" }, end: { ref: "program.end" } },
+ itemId: spec.id, semantic, projection: { start: { ref: "timeline.start" }, end: { ref: "timeline.end" } },
}));
- return renderCommentSticker(canvas, space, finalizeCommentSticker(set, header));
+ return renderCommentSticker(space, finalizeCommentSticker(set, header));
}
test("Comment Sticker is one deterministic self-contained peer VisualTrack", () => {
@@ -123,10 +120,10 @@ test("short Sticker windows compose overlapping enter and exit motion instead of
const spec = item("compressed");
const set = appendProjectedCommentSticker(
createCommentStickerSet(), header, space, frame, compressed, spec, content(), projectProgramWindow({
- itemId: spec.id, semantic, projection: { start: { ref: "program.start" }, end: { ref: "program.end" } },
+ itemId: spec.id, semantic, projection: { start: { ref: "timeline.start" }, end: { ref: "timeline.end" } },
}),
);
- const rendered = renderCommentSticker(canvas, space, finalizeCommentSticker(set, header));
+ const rendered = renderCommentSticker(space, finalizeCommentSticker(set, header));
const animation = rendered.presents[0]?.elements.find((element) => element.animation !== undefined)?.animation;
assert.ok(animation);
const overlap = animation.keyframes.find((keyframe) => keyframe.atFrame === 45)!;
@@ -167,10 +164,9 @@ test("Style Surface consumes an explicit SVS Recipe and exact Font Stack", async
assert.equal(result.components.length, 0);
});
-test("Track Surface lowers mixed program and semantic Stickers to a finite explicit graph", async () => {
+test("Track Surface lowers mixed literal and resolved-Window Stickers to a finite explicit graph", async () => {
const blob = { kind: "blob" as const, resource: fixtureResource("comment-avatar"), size: 128, mediaType: "image/png" };
const refs = new Map<string, SurfaceResolvedReference>([
- ["video.canvas", authored("video.canvas", spatialTypes.canvas, canvas)],
["video.timeline", authored("video.timeline", timelineTypes.track, semantic)],
["layout.comment", authored("layout.comment", spatialTypes.frame, frame)],
["social", authored("social", commentStickerTypes.style, style)],
@@ -179,13 +175,13 @@ test("Track Surface lowers mixed program and semantic Stickers to a finite expli
]);
const result = await decodeCommentStickerTrackSurface({
sourceName: "fixture.svml",
- element: parsed(`<comment:Track id="comments" canvas={video.canvas} timeline={video.timeline}>
- <comment:Sticker id="one" comment={copy} frame={layout.comment} style={social} avatar={avatar} author="@viewer" meta="Featured" during="program"/>
+ element: parsed(`<comment:Track id="comments" timeline={video.timeline}>
+ <comment:Sticker id="one" comment={copy} frame={layout.comment} style={social} avatar={avatar} author="@viewer" meta="Featured" during="timeline"/>
</comment:Track>`),
resolveReference: (path) => refs.get(path),
resolveAsset: noAsset,
});
- assert.equal(result.components.filter((component) => component.outputs.track !== undefined).length, 1);
+ assert.equal(result.components.filter((component) => component.outputs.visual !== undefined).length, 1);
assert.deepEqual(result.fragments.flatMap((fragment) => fragment.operations.map((operation) => operation.producer.name)).sort(), [
commentStickerProducers.createSet.name,
commentStickerProducers.createContent.name,
@@ -198,5 +194,5 @@ test("Track Surface lowers mixed program and semantic Stickers to a finite expli
temporalProducers.composeWindow.name,
commentStickerProducers.render.name,
].sort());
- assert.equal(result.components.find((component) => component.outputs.track !== undefined)?.outputs.track, "comments.track");
+ assert.equal(result.components.find((component) => component.outputs.visual !== undefined)?.outputs.visual, "comments.visual");
});
diff --git a/packages/component-kit/README.md b/packages/component-kit/README.md
index 9ebb9ba9..b135fec7 100644
--- a/packages/component-kit/README.md
+++ b/packages/component-kit/README.md
@@ -78,7 +78,7 @@ rename the Fragment port. The Manifest's Producer ports, Fragment wiring and han
must agree for that operation.
Read the closest installed implementation for the behavior being authored: Emoji Reveal for a
-persistent event-driven strip, Media Track for sampling and transitions, Caption Fine for a
+persistent event-driven strip, Visual Track for sampling and transitions, Caption Fine for a
schedule/render split. Their package-local files supply concrete patterns without requiring a
monorepo checkout. A new component owns its own mechanics, not a fork of the framework loader or
Runtime.
diff --git a/packages/composition/README.md b/packages/composition/README.md
index 30f695f0..540cbabf 100644
--- a/packages/composition/README.md
+++ b/packages/composition/README.md
@@ -4,9 +4,9 @@ Provider-neutral visual and audio Track contracts and their final Composition.
## VisualTrack
-`sealVisualTrack` accepts `id`, `programSpaceId`, `visualIr: VISUAL_IR_V1` and `presents` and returns
-a value with `kind: "visual"`. `assertVisualTrackIdentity(track, space)` also checks it against a
-specific ProgramSpace. Both functions are exported from this package.
+`sealVisualTrack` accepts `id`, `timelineId`, `visualIr: VISUAL_IR_V1` and `presents` and returns
+a value with `kind: "visual"`. `assertVisualTrackIdentity(track, timeline)` also checks it against a
+specific Timeline. Both functions are exported from this package.
Each Present supplies:
@@ -14,11 +14,13 @@ Each Present supplies:
| --- | --- |
| `id`, optional `subjectId` | Appearance identity and, when useful, the domain entity it depicts |
| `span` | `{ startFrame, endFrameExclusive }` in program frames |
-| `stacking` | `{ order, tieBreak }`, absolute paint order across Presents |
+| `order` | Stable order among Presents emitted by this owning Track |
+| `z` | Author-owned absolute picture stacking position across Tracks |
| `elements` | One rooted element tree owned by the Present |
-Higher stacking order paints later. Element `order` values are distinct within a Present and
-determine order inside its tree. A child names
+Higher `z` paints later. Equal-`z` Presents use stable Track identity, Present `order` and Present
+identity as deterministic fallbacks; authors use distinct `z` values when that relative paint order
+matters. Element `order` values are distinct within a Present and determine order inside its tree. A child names
its `parent`; its position is relative to that parent. Root positioning is relative to the Canvas.
Animation keyframes use `atFrame` offsets from the Present's start. Media sampling targets use the
same local frame origin and map to exact source frames.
@@ -36,10 +38,11 @@ relationship remains local to the Present; internal layout belongs to that progr
## AudioTrack
-An AudioTrack contributes explicit clips with source audio artifacts, source sample ranges, target
-sample ranges, gain, fades and playback. Target positions use the ProgramSpace's canonical 48 kHz
-sample domain. Use `programSpaceSampleFrames` and the temporal/media helpers when converting an
-authored event into that domain. Source timing and target timing are separate.
+An AudioTrack contributes explicit clips with source audio artifacts, target sample ranges, exact
+partial source-time maps, gain and fades. Target positions use the Timeline's canonical 48 kHz
+sample domain. Each non-overlapping affine source-time piece maps Clip-local target samples to
+source samples; uncovered target samples are silent. Use `timelineSampleFrames` and the
+temporal/media helpers when converting an authored event into that domain.
`sealAudioTrack` and `assertAudioTrackIdentity` are the corresponding public constructors/checks.
An Author Package can publish visual and audio Tracks as separate Outputs; the composition includes
@@ -48,11 +51,11 @@ each selected Output explicitly.
## Composition
A Composition carries its id, Canvas with clear color, and peer Tracks. The Tracks retain their
-ProgramSpace identity; assembly and rendering receive the corresponding time domain separately.
+Timeline identity; assembly and rendering receive the corresponding Timeline separately.
`@hypit/film` is one author-facing way to assemble it;
`@hypit/render-hyperframes` consumes it to produce a video.
-### Visibility without a new playback origin
+### Visibility without a new source-time origin
A VisualPresent may supply `visibility`, an ordered list of non-overlapping subranges in program
frames, all inside its `span`. Omission means the full span; an empty list means never visible.
@@ -60,15 +63,15 @@ frames, all inside its `span`. Omission means the full span; an empty list means
other partial visibility without cutting a program into restarted copies. HyperFrames applies the
visibility independently when seeking; custom HTML and typed media keep their original clocks.
-## Audio presentation on the program clock
+## Audio level automation on the program clock
-AudioClip optionally carries `gainEnvelope: { sample, gain }[]` and
+AudioClip optionally carries level automation as `gainEnvelope: { sample, gain }[]` and
`audibility: { startSample, endSampleExclusive }[]`. Both use absolute 48 kHz program samples.
Envelope points have strictly increasing sample positions and interpolate linearly, holding the
outer endpoint gains. They multiply the existing Clip gain and fades. Audible subranges are ordered,
disjoint and inside the original target; omission means the whole target, an empty list means silence.
-`audioEnvelopeGainAt` evaluates the envelope; `assertAudioPresentation` checks these values.
+`audioEnvelopeGainAt` evaluates the envelope; `assertAudioLevelAutomation` checks these values.
-Original target and source sampling remain intact when presentation is partially hidden. Range
+Original target and source sampling remain intact when a Clip is partially inaudible. Range
rendering applies envelopes and masks before cropping. These fields express generic sound behavior;
-source selection and Style/Use precedence belong to author components such as Sound.
+multi-Clip relationships such as ducking or crossfades belong to ordinary author components.
diff --git a/packages/composition/package.json b/packages/composition/package.json
index 12f5c4f8..d947b34e 100644
--- a/packages/composition/package.json
+++ b/packages/composition/package.json
@@ -13,9 +13,9 @@
"dependencies": {
"@hypit/component-kit": "workspace:*",
"@hypit/media": "workspace:*",
- "@hypit/program-space": "workspace:*",
"@hypit/protocol": "workspace:*",
- "@hypit/visual-ir": "workspace:*"
+ "@hypit/visual-ir": "workspace:*",
+ "@hypit/timeline": "workspace:*"
},
"devDependencies": {
"@hypit/artifact": "workspace:*",
diff --git a/packages/composition/src/audio-presentation.ts b/packages/composition/src/audio-level-automation.ts
similarity index 91%
rename from packages/composition/src/audio-presentation.ts
rename to packages/composition/src/audio-level-automation.ts
index 5f5e500f..6a7c03e8 100644
--- a/packages/composition/src/audio-presentation.ts
+++ b/packages/composition/src/audio-level-automation.ts
@@ -1,14 +1,14 @@
-/** Gain and audibility are measured on the complete 48 kHz program clock. */
+/** Level automation is measured on the complete 48 kHz program clock. */
export type AudioSampleSpan = { readonly startSample: number; readonly endSampleExclusive: number };
export type AudioGainPoint = { readonly sample: number; readonly gain: number };
-export type AudioPresentation = {
+export type AudioLevelAutomation = {
/** Linear interpolation; hold the first/last gain outside the supplied points. */
readonly gainEnvelope?: readonly AudioGainPoint[];
/** Half-open audible regions; omission means the complete target, [] means silence. */
readonly audibility?: readonly AudioSampleSpan[];
};
-export function assertAudioPresentation(value: AudioPresentation, target: AudioSampleSpan,
+export function assertAudioLevelAutomation(value: AudioLevelAutomation, target: AudioSampleSpan,
totalSamples = Number.MAX_SAFE_INTEGER): void {
if (value.gainEnvelope !== undefined) {
if (!Array.isArray(value.gainEnvelope) || value.gainEnvelope.length === 0) throw new Error("Audio gain envelope needs points.");
diff --git a/packages/composition/src/index.ts b/packages/composition/src/index.ts
index bc932704..148395c7 100644
--- a/packages/composition/src/index.ts
+++ b/packages/composition/src/index.ts
@@ -1,7 +1,7 @@
export { compositionComponent } from "./component.js";
export { compositionDependency, compositionManifest, compositionModuleRef, compositionTypes } from "./manifest.js";
export {
- audioTrackSchema, visualTimedSamplingSchema,
+ audioTrackSchema, visualSourceTimeMapSchema,
compositionSchema,
visualColorPaintSchema,
visualPathCommandSchema,
@@ -17,5 +17,5 @@ export { assertAudioTrackIdentity, assertCompositionIdentity, assertVisualTrackI
export { animatableLocalStyles } from "./track.js";
export type * from "./track.js";
-export * from "./audio-presentation.js";
+export * from "./audio-level-automation.js";
export { audioSampleSpanSchema, audioGainEnvelopeSchema } from "./schema.js";
diff --git a/packages/composition/src/manifest.ts b/packages/composition/src/manifest.ts
index a967a72d..90430c27 100644
--- a/packages/composition/src/manifest.ts
+++ b/packages/composition/src/manifest.ts
@@ -1,11 +1,11 @@
-import { mediaDependency, programSpaceDependency } from "./schema.js";
+import { mediaDependency, timelineDependency } from "./schema.js";
import { visualIrDependency } from "@hypit/visual-ir";
import type { ModuleManifest, TypeRef } from "@hypit/protocol";
import { audioTrackSchema, compositionSchema, visualTrackSchema } from "./schema.js";
export const compositionModuleRef = { name: "@hypit/composition", version: "1" } as const;
export const compositionTypes = { visualTrack: { module: compositionModuleRef, name: "VisualTrack" }, audioTrack: { module: compositionModuleRef, name: "AudioTrack" }, composition: { module: compositionModuleRef, name: "Composition" } } satisfies Record<string, TypeRef>;
export const compositionManifest: ModuleManifest = { format: "hypit.module@1", name: compositionModuleRef.name, version: compositionModuleRef.version,
- dependencies: [mediaDependency, programSpaceDependency, visualIrDependency], types: [
+ dependencies: [mediaDependency, timelineDependency, visualIrDependency], types: [
{ name: compositionTypes.visualTrack.name },
{ name: compositionTypes.audioTrack.name },
{ name: compositionTypes.composition.name },
diff --git a/packages/composition/src/schema.ts b/packages/composition/src/schema.ts
index dc0d460a..c05c4d06 100644
--- a/packages/composition/src/schema.ts
+++ b/packages/composition/src/schema.ts
@@ -1,8 +1,8 @@
import { compositableSurfaceSchema, fontArtifactSchema, mediaDependency } from "@hypit/media";
-import { programSpaceDependency } from "@hypit/program-space";
+import { timelineDependency } from "@hypit/timeline";
import type { ValueSchema } from "@hypit/protocol";
import { VISUAL_IR_V1, VISUAL_STYLE_ENUM_VALUES_V1, VISUAL_STYLE_NAMES_V1 } from "@hypit/visual-ir";
-export { mediaDependency, programSpaceDependency };
+export { mediaDependency, timelineDependency };
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 = (
@@ -22,15 +22,16 @@ const mediaBlobRef = object({
mediaType: { schema: string },
});
const positiveInteger = { kind: "number", integer: true, minimum: 1 } as const;
-const rational = object({ numerator: { schema: integer }, denominator: { schema: positiveInteger } });
-const samplingSegment = object({
+const nonNegativeRational = object({ numerator: { schema: integer }, denominator: { schema: positiveInteger } });
+const signedRational = object({ numerator: { schema: signedInteger }, denominator: { schema: positiveInteger } });
+const sourceTimePiece = object({
target: { schema: object({ startFrame: { schema: integer }, endFrameExclusive: { schema: positiveInteger } }) },
- sourceFrame: { schema: rational }, rate: { schema: rational },
- loop: { schema: object({ startFrame: { schema: integer }, endFrameExclusive: { schema: positiveInteger } }), optional: true },
+ sourceAtStart: { schema: nonNegativeRational }, rate: { schema: signedRational },
+ wrap: { schema: object({ startFrame: { schema: integer }, endFrameExclusive: { schema: positiveInteger } }), optional: true },
});
-export const visualTimedSamplingSchema = object({
- sourceFrameRate: { schema: rational }, sourceFrameCount: { schema: positiveInteger },
- segments: { schema: { kind: "array", minItems: 1, items: samplingSegment } },
+export const visualSourceTimeMapSchema = object({
+ sourceFrameRate: { schema: nonNegativeRational }, sourceFrameCount: { schema: positiveInteger },
+ pieces: { schema: { kind: "array", minItems: 1, items: sourceTimePiece } },
});
const styleDeclaration: ValueSchema = { kind: "oneOf", variants: VISUAL_STYLE_NAMES_V1.map((name) => object({
name: { schema: { kind: "literal", value: name } }, value: { schema: Object.hasOwn(VISUAL_STYLE_ENUM_VALUES_V1, name)
@@ -164,14 +165,14 @@ export const visualPathCommandSchema: ValueSchema = { kind: "oneOf", variants: [
object({ kind: { schema: { kind: "literal", value: "close" } } }),
] };
const pathTextElement = object({ ...base, kind: { schema: { kind: "literal", value: "path-text" } }, document: { schema: visualTextDocumentSchema }, typography: { schema: visualTextTypographySchema }, paints: { schema: { kind: "array", items: visualTextPaintSchema } }, path: { schema: { kind: "array", minItems: 2, items: visualPathCommandSchema } }, side: { schema: enumString(["left", "right"]) }, orientation: { schema: enumString(["follow", "upright"]) }, startMarginPx: { schema: number }, endMarginPx: { schema: number }, align: { schema: enumString(["start", "center", "end"]) }, reverse: { schema: boolean }, overflow: { schema: enumString(["visible", "clip"]) }, sequences: { schema: { kind: "array", items: visualTextSequenceSchema } }, marginAnimation: { schema: object({ keyframes: { schema: { kind: "array", minItems: 2, items: object({ atFrame: { schema: integer }, startMarginPx: { schema: number }, easing: { schema: enumString(["linear", "ease-in", "ease-out", "ease-in-out"]), optional: true } }) } } }), optional: true } });
-export const visualImageSchema: ValueSchema = object({ ...base, kind: { schema: { kind: "literal", value: "image" } }, artifact: { schema: mediaBlobRef }, sampling: { schema: visualTimedSamplingSchema, optional: true }, muted: { schema: { kind: "boolean" }, optional: true } });
-export const visualVideoSchema: ValueSchema = object({ ...base, kind: { schema: { kind: "literal", value: "video" } }, artifact: { schema: mediaBlobRef }, sampling: { schema: visualTimedSamplingSchema, optional: true }, muted: { schema: { kind: "boolean" }, optional: true } });
-export const visualSurfaceSchema: ValueSchema = object({ ...base, kind: { schema: { kind: "literal", value: "surface" } }, surface: { schema: compositableSurfaceSchema }, sampling: { schema: visualTimedSamplingSchema, optional: true } });
+export const visualImageSchema: ValueSchema = object({ ...base, kind: { schema: { kind: "literal", value: "image" } }, artifact: { schema: mediaBlobRef } });
+export const visualVideoSchema: ValueSchema = object({ ...base, kind: { schema: { kind: "literal", value: "video" } }, artifact: { schema: mediaBlobRef }, sourceTime: { schema: visualSourceTimeMapSchema }, muted: { schema: { kind: "boolean" }, optional: true } });
+export const visualSurfaceSchema: ValueSchema = object({ ...base, kind: { schema: { kind: "literal", value: "surface" } }, surface: { schema: compositableSurfaceSchema }, sourceTime: { schema: visualSourceTimeMapSchema, optional: true } });
export const visualProgramSchema: ValueSchema = object({ ...base, kind: { schema: { kind: "literal", value: "program" } }, program: { schema: object({ format: { schema: string }, payload: { schema: object({}, true) }, artifacts: { schema: { kind: "array", items: mediaBlobRef } } }) } });
export const visualElementSchema: ValueSchema = { kind: "oneOf", variants: [visualBoxSchema, visualMaskSchema, visualTextSchema, textFlowElement, pathTextElement, visualImageSchema, visualVideoSchema, visualSurfaceSchema, visualProgramSchema] };
const span = object({ startFrame: { schema: integer }, endFrameExclusive: { schema: integer } });
-const present = object({ id: { schema: string }, subjectId: { schema: string, optional: true }, span: { schema: span }, visibility: { schema: { kind: "array", items: span }, optional: true }, stacking: { schema: object({ order: { schema: signedInteger }, tieBreak: { schema: string } }) }, elements: { schema: { kind: "array", minItems: 1, items: visualElementSchema } } });
-export const visualTrackSchema: ValueSchema = object({ kind: { schema: { kind: "literal", value: "visual" } }, programSpaceId: { schema: string }, visualIr: { schema: { kind: "literal", value: VISUAL_IR_V1 } }, id: { schema: string }, presents: { schema: { kind: "array", items: present } } });
+const present = object({ id: { schema: string }, order: { schema: integer }, z: { schema: signedInteger }, subjectId: { schema: string, optional: true }, span: { schema: span }, visibility: { schema: { kind: "array", items: span }, optional: true }, elements: { schema: { kind: "array", minItems: 1, items: visualElementSchema } } });
+export const visualTrackSchema: ValueSchema = object({ kind: { schema: { kind: "literal", value: "visual" } }, timelineId: { schema: string }, visualIr: { schema: { kind: "literal", value: VISUAL_IR_V1 } }, id: { schema: string }, presents: { schema: { kind: "array", items: present } } });
export const audioSampleSpanSchema = object({ startSample: { schema: integer }, endSampleExclusive: { schema: { kind: "number", integer: true, minimum: 1 } } });
export const audioGainEnvelopeSchema: ValueSchema = { kind: "array", minItems: 1, items: object({
sample: { schema: integer }, gain: { schema: { kind: "number", minimum: 0, maximum: 64 } },
@@ -180,20 +181,20 @@ const audioClip = object({
id: { schema: string },
artifact: { schema: audioBlobRef },
target: { schema: audioSampleSpanSchema },
- source: { schema: object({
- sampleFrames: { schema: { kind: "number", integer: true, minimum: 1 } },
- startSample: { schema: integer },
- endSampleExclusive: { schema: { kind: "number", integer: true, minimum: 1 } },
- loop: { schema: { kind: "boolean" } },
- phaseSample: { schema: integer },
+ sourceTime: { schema: object({
+ sourceSampleFrames: { schema: { kind: "number", integer: true, minimum: 1 } },
+ pieces: { schema: { kind: "array", minItems: 1, items: object({
+ target: { schema: audioSampleSpanSchema },
+ sourceAtStart: { schema: object({ numerator: { schema: integer }, denominator: { schema: { kind: "number", integer: true, minimum: 1 } } }) },
+ rate: { schema: object({ numerator: { schema: { kind: "number", integer: true, minimum: 1 } }, denominator: { schema: { kind: "number", integer: true, minimum: 1 } } }) },
+ wrap: { schema: audioSampleSpanSchema, optional: true },
+ }) } },
}) },
- playbackRate: { schema: { kind: "number", minimum: 0.000001, maximum: 100 } },
- pitch: { schema: { kind: "literal", value: "preserve" } },
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 },
});
-export const audioTrackSchema: ValueSchema = object({ kind: { schema: { kind: "literal", value: "audio" } }, programSpaceId: { schema: string }, id: { schema: string }, clips: { schema: { kind: "array", items: audioClip } } });
+export const audioTrackSchema: ValueSchema = object({ kind: { schema: { kind: "literal", value: "audio" } }, timelineId: { schema: string }, id: { schema: string }, clips: { schema: { kind: "array", items: audioClip } } });
export const compositionSchema: ValueSchema = object({ id: { schema: string }, canvas: { schema: object({ width: { schema: integer }, height: { schema: integer }, clearColor: { schema: string } }) }, tracks: { schema: { kind: "array", items: { kind: "oneOf", variants: [visualTrackSchema, audioTrackSchema] } } } });
diff --git a/packages/composition/src/track.ts b/packages/composition/src/track.ts
index 214ffc67..f0290151 100644
--- a/packages/composition/src/track.ts
+++ b/packages/composition/src/track.ts
@@ -1,5 +1,5 @@
-import { assertAudioPresentation } from "./audio-presentation.js";
-import type { AudioPresentation } from "./audio-presentation.js";
+import { assertAudioLevelAutomation } from "./audio-level-automation.js";
+import type { AudioLevelAutomation, AudioSampleSpan } from "./audio-level-automation.js";
import { canonicalStringify, isResourceId } from "@hypit/protocol";
import type { BlobRef, CanonicalValue } from "@hypit/protocol";
@@ -7,12 +7,8 @@ import {
assertVisualStyleV1,
VISUAL_IR_V1,
} from "@hypit/visual-ir";
-import {
- assertProgramSpaceIdentity,
- programSpaceFrameCount,
- programSpaceSampleFrames,
-} from "@hypit/program-space";
-import type { ProgramSpace } from "@hypit/program-space";
+import { assertTimelineIdentity, timelineFrameCount, timelineSampleFrames } from "@hypit/timeline";
+import type { Timeline } from "@hypit/timeline";
import { assertCompositableSurfaceRef, assertFontArtifactRef } from "@hypit/media";
import type { CompositableSurfaceRef, FontArtifactRef } from "@hypit/media";
@@ -308,7 +304,7 @@ export type VisualPathTextElement = VisualElementBase & {
};
};
-export type VisualSamplingRational = {
+export type VisualSourceTimeRational = {
readonly numerator: number;
readonly denominator: number;
};
@@ -317,34 +313,41 @@ export type VisualSamplingRational = {
* One exact piece of a timed visual's source-time function. Target frames are
* relative to the containing Present. A gap means the material is invisible.
*/
-export type VisualSamplingSegment = {
+export type VisualSourceTimePiece = {
readonly target: FrameSpan;
/** Absolute source-frame position at target.startFrame. */
- readonly sourceFrame: VisualSamplingRational;
+ readonly sourceAtStart: VisualSourceTimeRational;
/** Source frames advanced per Program frame; zero is an exact held frame. */
- readonly rate: VisualSamplingRational;
- readonly loop?: FrameSpan;
+ readonly rate: VisualSourceTimeRational;
+ /** Half-open source interval used for periodic evaluation. */
+ readonly wrap?: FrameSpan;
};
-export type VisualTimedSampling = {
- readonly sourceFrameRate: VisualSamplingRational;
+export type VisualSourceTimeMap = {
+ readonly sourceFrameRate: VisualSourceTimeRational;
readonly sourceFrameCount: number;
- readonly segments: readonly VisualSamplingSegment[];
+ readonly pieces: readonly VisualSourceTimePiece[];
};
-export type VisualMediaElement = VisualElementBase & {
- readonly kind: "image" | "video";
- readonly artifact: BlobRef;
- /** Exact frame-domain mapping for timed media. */
- readonly sampling?: VisualTimedSampling;
- readonly muted?: boolean;
-};
+export type VisualMediaElement =
+ | (VisualElementBase & {
+ readonly kind: "image";
+ readonly artifact: BlobRef;
+ })
+ | (VisualElementBase & {
+ readonly kind: "video";
+ readonly artifact: BlobRef;
+ /** Exact partial frame-domain function for this timed source. */
+ readonly sourceTime: VisualSourceTimeMap;
+ readonly muted?: boolean;
+ });
/** A package-materialized visual surface with content-bound compositing metadata, not an untyped media guess. */
export type VisualSurfaceElement = VisualElementBase & {
readonly kind: "surface";
readonly surface: CompositableSurfaceRef;
- readonly sampling?: VisualTimedSampling;
+ /** Required exactly when surface.timing is frames; absent for a still Surface. */
+ readonly sourceTime?: VisualSourceTimeMap;
};
/**
@@ -360,23 +363,22 @@ export type VisualElement = VisualBoxElement | VisualProgramElement | VisualMask
export type VisualPresent = {
readonly id: string;
+ /** Stable order among Presents emitted by this owning Track. */
+ readonly order: number;
+ /** Author-owned absolute picture stacking position across Tracks. */
+ readonly z: number;
/** Optional domain entity implemented by this renderer Present. */
readonly subjectId?: string;
readonly span: FrameSpan;
/** Optional visible subranges in program frames; span remains the animation and sampling origin. */
readonly visibility?: readonly FrameSpan[];
- /** Absolute paint position for this Present, not for its authoring Track. */
- readonly stacking: {
- readonly order: number;
- readonly tieBreak: string;
- };
readonly elements: readonly VisualElement[];
};
export type VisualTrack = {
readonly kind: "visual";
- /** ProgramSpace identity this terminal placement was rendered against. */
- readonly programSpaceId: string;
+ /** Timeline identity this terminal placement was rendered against. */
+ readonly timelineId: string;
/** The one terminal visual language shared by official video components. */
readonly visualIr: typeof VISUAL_IR_V1;
readonly id: string;
@@ -384,28 +386,38 @@ export type VisualTrack = {
readonly presents: readonly VisualPresent[];
};
-export type AudioClip = AudioPresentation & {
+export type AudioSourceTimeRational = {
+ readonly numerator: number;
+ readonly denominator: number;
+};
+
+export type AudioSourceTimePiece = {
+ /** Clip-local target samples. Uncovered samples are silent. */
+ readonly target: AudioSampleSpan;
+ readonly sourceAtStart: AudioSourceTimeRational;
+ /** Positive source samples advanced per target sample. */
+ readonly rate: AudioSourceTimeRational;
+ readonly wrap?: AudioSampleSpan;
+};
+
+export type AudioSourceTimeMap = {
+ readonly sourceSampleFrames: number;
+ readonly pieces: readonly AudioSourceTimePiece[];
+};
+
+export type AudioClip = AudioLevelAutomation & {
readonly id: string;
/** Optional domain entity implemented by this renderer Clip. */
readonly subjectId?: string;
/** Bytes only. Exact duration belongs to source.sampleFrames, not duplicated floating metadata. */
readonly artifact: BlobRef;
- /** Exact audible placement in the canonical 48 kHz ProgramSpace sample domain. */
+ /** Exact audible placement in the canonical 48 kHz Timeline sample domain. */
readonly target: {
readonly startSample: number;
readonly endSampleExclusive: number;
};
- /** Exact sampling interval in one canonical 48 kHz stereo WAV Artifact. */
- readonly source: {
- readonly sampleFrames: number;
- readonly startSample: number;
- readonly endSampleExclusive: number;
- readonly loop: boolean;
- /** Offset inside the effective source interval used only when looping. */
- readonly phaseSample: number;
- };
- readonly playbackRate: number;
- readonly pitch: "preserve";
+ /** Partial Clip-local target-to-source relation for one canonical 48 kHz stereo WAV Artifact. */
+ readonly sourceTime: AudioSourceTimeMap;
readonly gain: number;
readonly fadeInSamples: number;
readonly fadeOutSamples: number;
@@ -413,8 +425,8 @@ export type AudioClip = AudioPresentation & {
export type AudioTrack = {
readonly kind: "audio";
- /** ProgramSpace identity this terminal placement was rendered against. */
- readonly programSpaceId: string;
+ /** Timeline identity this terminal placement was rendered against. */
+ readonly timelineId: string;
readonly id: string;
readonly clips: readonly AudioClip[];
};
@@ -464,7 +476,7 @@ function assertFrameSpan(span: FrameSpan, totalFrames: number, label: string): v
|| span.endFrameExclusive <= span.startFrame
|| span.endFrameExclusive > totalFrames
) {
- throw new Error(`${label} is outside ProgramSpace.`);
+ throw new Error(`${label} is outside Timeline.`);
}
}
@@ -480,59 +492,62 @@ function assertMediaArtifact(artifact: BlobRef, label: string): void {
}
}
-function assertRational(value: VisualSamplingRational, label: string, allowZero: boolean): void {
- if (!Number.isSafeInteger(value.numerator) || (!allowZero && value.numerator <= 0) || (allowZero && value.numerator < 0)
+function assertRational(value: VisualSourceTimeRational, label: string, sign: "positive" | "non-negative" | "signed"): void {
+ if (!Number.isSafeInteger(value.numerator)
+ || (sign === "positive" && value.numerator <= 0)
+ || (sign === "non-negative" && value.numerator < 0)
|| !Number.isSafeInteger(value.denominator) || value.denominator <= 0) {
- throw new Error(`${label} must be a non-negative safe rational.`);
+ throw new Error(`${label} is not a safe ${sign} rational.`);
}
}
-function compareRationalToInteger(value: VisualSamplingRational, integer: number): number {
+function compareRationalToInteger(value: VisualSourceTimeRational, integer: number): number {
const difference = BigInt(value.numerator) - BigInt(integer) * BigInt(value.denominator);
return difference < 0n ? -1 : difference > 0n ? 1 : 0;
}
-function sourceAt(segment: VisualSamplingSegment, targetOffset: number): VisualSamplingRational {
- const denominator = BigInt(segment.sourceFrame.denominator) * BigInt(segment.rate.denominator);
- const numerator = BigInt(segment.sourceFrame.numerator) * BigInt(segment.rate.denominator)
- + BigInt(targetOffset) * BigInt(segment.rate.numerator) * BigInt(segment.sourceFrame.denominator);
- if (numerator > BigInt(Number.MAX_SAFE_INTEGER) || denominator > BigInt(Number.MAX_SAFE_INTEGER)) {
- throw new Error("Visual sampling arithmetic exceeds the safe wire domain.");
+function sourceAt(piece: VisualSourceTimePiece, targetOffset: number): VisualSourceTimeRational {
+ const denominator = BigInt(piece.sourceAtStart.denominator) * BigInt(piece.rate.denominator);
+ const numerator = BigInt(piece.sourceAtStart.numerator) * BigInt(piece.rate.denominator)
+ + BigInt(targetOffset) * BigInt(piece.rate.numerator) * BigInt(piece.sourceAtStart.denominator);
+ if (numerator > BigInt(Number.MAX_SAFE_INTEGER) || numerator < BigInt(Number.MIN_SAFE_INTEGER)
+ || denominator > BigInt(Number.MAX_SAFE_INTEGER)) {
+ throw new Error("Visual source-time arithmetic exceeds the safe wire domain.");
}
return { numerator: Number(numerator), denominator: Number(denominator) };
}
-function assertSampling(value: VisualTimedSampling, durationFrames: number, label: string): void {
- assertRational(value.sourceFrameRate, `${label}.sourceFrameRate`, false);
- if (!Number.isSafeInteger(value.sourceFrameCount) || value.sourceFrameCount <= 0 || value.segments.length === 0) {
+function assertSourceTime(value: VisualSourceTimeMap, durationFrames: number, label: string): void {
+ assertRational(value.sourceFrameRate, `${label}.sourceFrameRate`, "positive");
+ if (!Number.isSafeInteger(value.sourceFrameCount) || value.sourceFrameCount <= 0 || value.pieces.length === 0) {
throw new Error(`${label} source frame domain is invalid.`);
}
let previousEnd = 0;
- for (const [index, segment] of value.segments.entries()) {
- const item = `${label}.segments.${index}`;
- if (!Number.isSafeInteger(segment.target.startFrame) || !Number.isSafeInteger(segment.target.endFrameExclusive)
- || segment.target.startFrame < previousEnd || segment.target.endFrameExclusive <= segment.target.startFrame
- || segment.target.endFrameExclusive > durationFrames) throw new Error(`${item} target interval is invalid.`);
- assertRational(segment.sourceFrame, `${item}.sourceFrame`, true);
- assertRational(segment.rate, `${item}.rate`, true);
- if (segment.loop !== undefined) {
- if (!Number.isSafeInteger(segment.loop.startFrame) || !Number.isSafeInteger(segment.loop.endFrameExclusive)
- || segment.loop.startFrame < 0 || segment.loop.endFrameExclusive <= segment.loop.startFrame
- || segment.loop.endFrameExclusive > value.sourceFrameCount
- || compareRationalToInteger(segment.sourceFrame, segment.loop.startFrame) < 0
- || compareRationalToInteger(segment.sourceFrame, segment.loop.endFrameExclusive) >= 0) {
- throw new Error(`${item} loop interval or phase is invalid.`);
+ for (const [index, piece] of value.pieces.entries()) {
+ const item = `${label}.pieces.${index}`;
+ if (!Number.isSafeInteger(piece.target.startFrame) || !Number.isSafeInteger(piece.target.endFrameExclusive)
+ || piece.target.startFrame < previousEnd || piece.target.endFrameExclusive <= piece.target.startFrame
+ || piece.target.endFrameExclusive > durationFrames) throw new Error(`${item} target interval is invalid.`);
+ assertRational(piece.sourceAtStart, `${item}.sourceAtStart`, "non-negative");
+ assertRational(piece.rate, `${item}.rate`, "signed");
+ if (piece.wrap !== undefined) {
+ if (!Number.isSafeInteger(piece.wrap.startFrame) || !Number.isSafeInteger(piece.wrap.endFrameExclusive)
+ || piece.wrap.startFrame < 0 || piece.wrap.endFrameExclusive <= piece.wrap.startFrame
+ || piece.wrap.endFrameExclusive > value.sourceFrameCount
+ || compareRationalToInteger(piece.sourceAtStart, piece.wrap.startFrame) < 0
+ || compareRationalToInteger(piece.sourceAtStart, piece.wrap.endFrameExclusive) >= 0) {
+ throw new Error(`${item} wrap interval or phase is invalid.`);
}
} else {
- const last = sourceAt(segment, segment.target.endFrameExclusive - segment.target.startFrame - 1);
- if (compareRationalToInteger(segment.sourceFrame, 0) < 0
- || compareRationalToInteger(segment.sourceFrame, value.sourceFrameCount) >= 0
+ const last = sourceAt(piece, piece.target.endFrameExclusive - piece.target.startFrame - 1);
+ if (compareRationalToInteger(piece.sourceAtStart, 0) < 0
+ || compareRationalToInteger(piece.sourceAtStart, value.sourceFrameCount) >= 0
|| compareRationalToInteger(last, 0) < 0
|| compareRationalToInteger(last, value.sourceFrameCount) >= 0) {
throw new Error(`${item} samples outside its source frame domain.`);
}
}
- previousEnd = segment.target.endFrameExclusive;
+ previousEnd = piece.target.endFrameExclusive;
}
}
@@ -934,8 +949,8 @@ function assertAnimation(animation: VisualAnimation | undefined, _durationFrames
}
}
-function assertPresent(present: VisualPresent, programSpace: ProgramSpace | undefined, trackId: string): void {
- const totalFrames = programSpace === undefined ? Number.MAX_SAFE_INTEGER : programSpaceFrameCount(programSpace);
+function assertPresent(present: VisualPresent, timeline: Timeline | undefined, trackId: string): void {
+ const totalFrames = timeline === undefined ? Number.MAX_SAFE_INTEGER : timelineFrameCount(timeline);
assertNonEmpty(present.id, `${trackId} Present id`);
if (present.subjectId !== undefined) assertNonEmpty(present.subjectId, `${trackId}.${present.id} subjectId`);
assertFrameSpan(present.span, totalFrames, `${trackId}.${present.id}.span`);
@@ -945,10 +960,10 @@ function assertPresent(present: VisualPresent, programSpace: ProgramSpace | unde
if (span.startFrame < previousEnd) throw new Error(`${trackId}.${present.id} visibility must be ordered within its span.`);
previousEnd = span.endFrameExclusive;
}
- assertNonEmpty(present.stacking.tieBreak, `${trackId}.${present.id} stacking tieBreak`);
- if (!Number.isSafeInteger(present.stacking.order)) {
- throw new Error(`${trackId}.${present.id} has invalid stacking order.`);
+ if (!Number.isSafeInteger(present.order) || present.order < 0) {
+ throw new Error(`${trackId}.${present.id} has invalid local order.`);
}
+ if (!Number.isSafeInteger(present.z)) throw new Error(`${trackId}.${present.id} has invalid z.`);
if (present.elements.length === 0) throw new Error(`${trackId}.${present.id} must contain an element.`);
const elements = new Map<string, VisualElement>();
const roots: VisualElement[] = [];
@@ -980,15 +995,12 @@ function assertPresent(present: VisualPresent, programSpace: ProgramSpace | unde
if (!element.artifact.mediaType.startsWith(`${element.kind}/`)) {
throw new Error(`${trackId}.${present.id}.${element.id} media kind does not match its Artifact.`);
}
- if (element.kind === "image" && element.sampling !== undefined) {
- throw new Error(`${trackId}.${present.id}.${element.id} cannot sample a durationless image.`);
- }
- if (element.sampling !== undefined) {
+ if (element.kind === "video") {
if (element.animation !== undefined) {
- throw new Error(`${trackId}.${present.id}.${element.id} sampling motion must live on an owned wrapper.`);
+ throw new Error(`${trackId}.${present.id}.${element.id} source time and animation must live on separate owned elements.`);
}
- assertSampling(element.sampling, present.span.endFrameExclusive - present.span.startFrame,
- `${trackId}.${present.id}.${element.id}.sampling`);
+ assertSourceTime(element.sourceTime, present.span.endFrameExclusive - present.span.startFrame,
+ `${trackId}.${present.id}.${element.id}.sourceTime`);
}
}
if (element.kind === "text") {
@@ -1051,31 +1063,24 @@ function assertPresent(present: VisualPresent, programSpace: ProgramSpace | unde
}
if (element.kind === "surface") {
assertCompositableSurfaceRef(element.surface, `${trackId}.${present.id}.${element.id}.surface`);
- if (element.surface.timing.kind === "still" && element.sampling !== undefined) {
- throw new Error(`${trackId}.${present.id}.${element.id} cannot sample a still Surface.`);
+ if (element.surface.timing.kind === "still" && element.sourceTime !== undefined) {
+ throw new Error(`${trackId}.${present.id}.${element.id} still Surface cannot have source time.`);
}
- if (element.sampling !== undefined) {
+ if (element.sourceTime !== undefined) {
if (element.animation !== undefined) {
- throw new Error(`${trackId}.${present.id}.${element.id} sampling motion must live on an owned wrapper.`);
+ throw new Error(`${trackId}.${present.id}.${element.id} source time and animation must live on separate owned elements.`);
}
if (element.surface.timing.kind !== "frames"
- || element.sampling.sourceFrameCount !== element.surface.timing.frameCount
- || element.sampling.sourceFrameRate.numerator !== element.surface.timing.frameRate.numerator
- || element.sampling.sourceFrameRate.denominator !== element.surface.timing.frameRate.denominator) {
- throw new Error(`${trackId}.${present.id}.${element.id} Surface sampling differs from its typed timing.`);
+ || element.sourceTime.sourceFrameCount !== element.surface.timing.frameCount
+ || element.sourceTime.sourceFrameRate.numerator !== element.surface.timing.frameRate.numerator
+ || element.sourceTime.sourceFrameRate.denominator !== element.surface.timing.frameRate.denominator) {
+ throw new Error(`${trackId}.${present.id}.${element.id} Surface source time differs from its typed timing.`);
}
- assertSampling(element.sampling, present.span.endFrameExclusive - present.span.startFrame,
- `${trackId}.${present.id}.${element.id}.sampling`);
+ assertSourceTime(element.sourceTime, present.span.endFrameExclusive - present.span.startFrame,
+ `${trackId}.${present.id}.${element.id}.sourceTime`);
}
if (element.surface.timing.kind === "frames") {
- const durationFrames = present.span.endFrameExclusive - present.span.startFrame;
- if (element.sampling === undefined && element.surface.timing.frameCount !== durationFrames) {
- throw new Error(`${trackId}.${present.id}.${element.id} Surface must exactly match its Present frame domain.`);
- }
- if (element.sampling === undefined && programSpace !== undefined && (
- element.surface.timing.frameRate.numerator !== programSpace.frameRate.numerator
- || element.surface.timing.frameRate.denominator !== programSpace.frameRate.denominator
- )) throw new Error(`${trackId}.${present.id}.${element.id} Surface must exactly match its Present frame domain.`);
+ if (element.sourceTime === undefined) throw new Error(`${trackId}.${present.id}.${element.id} timed Surface requires source time.`);
}
}
if (element.kind === "mask") {
@@ -1203,12 +1208,12 @@ function normalizeElement(element: VisualElement): VisualElement {
? { kind: "still" }
: { ...element.surface.timing, frameRate: { ...element.surface.timing.frameRate } },
},
- ...(element.sampling === undefined ? {} : { sampling: {
- sourceFrameRate: { ...element.sampling.sourceFrameRate },
- sourceFrameCount: element.sampling.sourceFrameCount,
- segments: element.sampling.segments.map((segment) => ({
- target: { ...segment.target }, sourceFrame: { ...segment.sourceFrame }, rate: { ...segment.rate },
- ...(segment.loop === undefined ? {} : { loop: { ...segment.loop } }),
+ ...(element.sourceTime === undefined ? {} : { sourceTime: {
+ sourceFrameRate: { ...element.sourceTime.sourceFrameRate },
+ sourceFrameCount: element.sourceTime.sourceFrameCount,
+ pieces: element.sourceTime.pieces.map((piece) => ({
+ target: { ...piece.target }, sourceAtStart: { ...piece.sourceAtStart }, rate: { ...piece.rate },
+ ...(piece.wrap === undefined ? {} : { wrap: { ...piece.wrap } }),
})),
} }),
};
@@ -1219,18 +1224,19 @@ function normalizeElement(element: VisualElement): VisualElement {
if (element.artifact === undefined) {
throw new Error(`${element.id} is a ${element.kind} element with no artifact.`);
}
+ if (element.kind === "image") return { ...common, kind: "image", artifact: { ...element.artifact } };
return {
...common,
- kind: element.kind,
+ kind: "video",
artifact: { ...element.artifact },
- ...(element.sampling === undefined ? {} : { sampling: {
- sourceFrameRate: { ...element.sampling.sourceFrameRate },
- sourceFrameCount: element.sampling.sourceFrameCount,
- segments: element.sampling.segments.map((segment) => ({
- target: { ...segment.target }, sourceFrame: { ...segment.sourceFrame }, rate: { ...segment.rate },
- ...(segment.loop === undefined ? {} : { loop: { ...segment.loop } }),
+ sourceTime: {
+ sourceFrameRate: { ...element.sourceTime.sourceFrameRate },
+ sourceFrameCount: element.sourceTime.sourceFrameCount,
+ pieces: element.sourceTime.pieces.map((piece) => ({
+ target: { ...piece.target }, sourceAtStart: { ...piece.sourceAtStart }, rate: { ...piece.rate },
+ ...(piece.wrap === undefined ? {} : { wrap: { ...piece.wrap } }),
})),
- } }),
+ },
...(element.muted === undefined ? {} : { muted: element.muted }),
};
}
@@ -1238,29 +1244,27 @@ function normalizeElement(element: VisualElement): VisualElement {
function visualTrackContent(value: Omit<VisualTrack, "kind">): VisualTrack {
return {
kind: "visual",
- programSpaceId: value.programSpaceId,
+ timelineId: value.timelineId,
visualIr: value.visualIr,
id: value.id,
presents: [...value.presents]
.map((present) => ({
id: present.id,
+ order: present.order,
+ z: present.z,
...(present.subjectId === undefined ? {} : { subjectId: present.subjectId }),
span: { ...present.span },
...(present.visibility === undefined ? {} : { visibility: present.visibility.map(span => ({ ...span })) }),
- stacking: { ...present.stacking },
elements: [...present.elements].map(normalizeElement).sort((a, b) => a.order - b.order || a.id.localeCompare(b.id)),
}))
- .sort((a, b) => a.span.startFrame - b.span.startFrame
- || a.stacking.order - b.stacking.order
- || a.stacking.tieBreak.localeCompare(b.stacking.tieBreak)
- || a.id.localeCompare(b.id)),
+ .sort((a, b) => a.order - b.order || a.id.localeCompare(b.id)),
};
}
function audioTrackContent(value: Omit<AudioTrack, "kind">): AudioTrack {
return {
kind: "audio",
- programSpaceId: value.programSpaceId,
+ timelineId: value.timelineId,
id: value.id,
clips: [...value.clips]
.map((clip) => ({
@@ -1268,9 +1272,15 @@ function audioTrackContent(value: Omit<AudioTrack, "kind">): AudioTrack {
...(clip.subjectId === undefined ? {} : { subjectId: clip.subjectId }),
artifact: { ...clip.artifact },
target: { ...clip.target },
- source: { ...clip.source },
- playbackRate: clip.playbackRate,
- pitch: clip.pitch,
+ sourceTime: {
+ sourceSampleFrames: clip.sourceTime.sourceSampleFrames,
+ pieces: clip.sourceTime.pieces.map((piece) => ({
+ target: { ...piece.target },
+ sourceAtStart: { ...piece.sourceAtStart },
+ rate: { ...piece.rate },
+ ...(piece.wrap === undefined ? {} : { wrap: { ...piece.wrap } }),
+ })),
+ },
gain: clip.gain,
fadeInSamples: clip.fadeInSamples,
fadeOutSamples: clip.fadeOutSamples,
@@ -1289,34 +1299,34 @@ export function sealAudioTrack(value: Omit<AudioTrack, "kind">): AudioTrack {
return audioTrackContent(value);
}
-export function assertVisualTrackIdentity(track: VisualTrack, programSpace?: ProgramSpace): void {
- if (programSpace !== undefined) assertProgramSpaceIdentity(programSpace);
+export function assertVisualTrackIdentity(track: VisualTrack, timeline?: Timeline): void {
+ if (timeline !== undefined) assertTimelineIdentity(timeline);
if (track.kind !== "visual") throw new Error("VisualTrack kind is invalid.");
if (track.visualIr !== VISUAL_IR_V1) throw new Error("Unsupported VisualTrack visual IR.");
- assertNonEmpty(track.programSpaceId, "VisualTrack programSpaceId");
- if (programSpace !== undefined && track.programSpaceId !== programSpace.id) {
- throw new Error(`VisualTrack ${track.id} belongs to ProgramSpace ${track.programSpaceId}, not ${programSpace.id}.`);
+ assertNonEmpty(track.timelineId, "VisualTrack timelineId");
+ if (timeline !== undefined && track.timelineId !== timeline.id) {
+ throw new Error(`VisualTrack ${track.id} belongs to Timeline ${track.timelineId}, not ${timeline.id}.`);
}
assertNonEmpty(track.id, "VisualTrack id");
const presentIds = new Set<string>();
for (const present of track.presents) {
if (presentIds.has(present.id)) throw new Error(`${track.id} has duplicate Present ${present.id}.`);
presentIds.add(present.id);
- assertPresent(present, programSpace, track.id);
+ assertPresent(present, timeline, track.id);
}
}
-export function assertAudioTrackIdentity(track: AudioTrack, programSpace?: ProgramSpace): void {
- if (programSpace !== undefined) assertProgramSpaceIdentity(programSpace);
+export function assertAudioTrackIdentity(track: AudioTrack, timeline?: Timeline): void {
+ if (timeline !== undefined) assertTimelineIdentity(timeline);
if (track.kind !== "audio") throw new Error("AudioTrack kind is invalid.");
- assertNonEmpty(track.programSpaceId, "AudioTrack programSpaceId");
- if (programSpace !== undefined && track.programSpaceId !== programSpace.id) {
- throw new Error(`AudioTrack ${track.id} belongs to ProgramSpace ${track.programSpaceId}, not ${programSpace.id}.`);
+ assertNonEmpty(track.timelineId, "AudioTrack timelineId");
+ if (timeline !== undefined && track.timelineId !== timeline.id) {
+ throw new Error(`AudioTrack ${track.id} belongs to Timeline ${track.timelineId}, not ${timeline.id}.`);
}
assertNonEmpty(track.id, "AudioTrack id");
- const totalSamples = programSpace === undefined
+ const totalSamples = timeline === undefined
? Number.MAX_SAFE_INTEGER
- : programSpaceSampleFrames(programSpace, 48_000);
+ : timelineSampleFrames(timeline, 48_000);
const clipIds = new Set<string>();
for (const clip of track.clips) {
if (clipIds.has(clip.id)) throw new Error(`${track.id} has duplicate clip ${clip.id}.`);
@@ -1328,29 +1338,14 @@ export function assertAudioTrackIdentity(track: AudioTrack, programSpace?: Progr
|| !Number.isSafeInteger(clip.target.endSampleExclusive)
|| clip.target.endSampleExclusive <= clip.target.startSample
|| clip.target.endSampleExclusive > totalSamples) {
- throw new Error(`${track.id}.${clip.id} target sample interval is outside ProgramSpace.`);
- }
- if (!Number.isSafeInteger(clip.source.sampleFrames) || clip.source.sampleFrames <= 0
- || !Number.isSafeInteger(clip.source.startSample) || clip.source.startSample < 0
- || !Number.isSafeInteger(clip.source.endSampleExclusive)
- || clip.source.endSampleExclusive <= clip.source.startSample
- || clip.source.endSampleExclusive > clip.source.sampleFrames) {
- throw new Error(`${track.id}.${clip.id} source sample interval is invalid.`);
- }
- const sourceLength = clip.source.endSampleExclusive - clip.source.startSample;
- if (!Number.isSafeInteger(clip.source.phaseSample) || clip.source.phaseSample < 0
- || clip.source.phaseSample >= sourceLength
- || (!clip.source.loop && clip.source.phaseSample !== 0)) {
- throw new Error(`${track.id}.${clip.id} source loop phase is invalid.`);
+ throw new Error(`${track.id}.${clip.id} target sample interval is outside Timeline.`);
}
- if (!Number.isFinite(clip.playbackRate) || clip.playbackRate <= 0 || clip.playbackRate > 100) {
- throw new Error(`${track.id}.${clip.id} has invalid playbackRate.`);
- }
- if (clip.pitch !== "preserve") throw new Error(`${track.id}.${clip.id} pitch policy is invalid.`);
+ assertAudioSourceTime(clip.sourceTime, clip.target.endSampleExclusive - clip.target.startSample,
+ `${track.id}.${clip.id}.sourceTime`);
if (!Number.isFinite(clip.gain) || clip.gain < 0 || clip.gain > 64) {
throw new Error(`${track.id}.${clip.id} gain is invalid.`);
}
- assertAudioPresentation(clip, clip.target, totalSamples);
+ assertAudioLevelAutomation(clip, clip.target, totalSamples);
const targetLength = clip.target.endSampleExclusive - clip.target.startSample;
if (!Number.isSafeInteger(clip.fadeInSamples) || clip.fadeInSamples < 0 || clip.fadeInSamples > targetLength
|| !Number.isSafeInteger(clip.fadeOutSamples) || clip.fadeOutSamples < 0
@@ -1360,6 +1355,66 @@ export function assertAudioTrackIdentity(track: AudioTrack, programSpace?: Progr
}
}
+function assertAudioSourceTimeRational(value: AudioSourceTimeRational, label: string, positive = false): void {
+ if (!Number.isSafeInteger(value.numerator) || (positive ? value.numerator <= 0 : value.numerator < 0)
+ || !Number.isSafeInteger(value.denominator) || value.denominator <= 0) {
+ throw new Error(`${label} is invalid.`);
+ }
+}
+
+function compareAudioRational(value: AudioSourceTimeRational, integer: number): number {
+ const difference = BigInt(value.numerator) - BigInt(integer) * BigInt(value.denominator);
+ return difference < 0n ? -1 : difference > 0n ? 1 : 0;
+}
+
+function compareAudioSourceAtEnd(piece: AudioSourceTimePiece, integer: number): number {
+ const length = piece.target.endSampleExclusive - piece.target.startSample;
+ const numerator = BigInt(piece.sourceAtStart.numerator) * BigInt(piece.rate.denominator)
+ + BigInt(length) * BigInt(piece.rate.numerator) * BigInt(piece.sourceAtStart.denominator);
+ const denominator = BigInt(piece.sourceAtStart.denominator) * BigInt(piece.rate.denominator);
+ const difference = numerator - BigInt(integer) * denominator;
+ return difference < 0n ? -1 : difference > 0n ? 1 : 0;
+}
+
+function assertAudioSourceTime(value: AudioSourceTimeMap, targetSamples: number, label: string): void {
+ if (!Number.isSafeInteger(value.sourceSampleFrames) || value.sourceSampleFrames <= 0
+ || !Array.isArray(value.pieces) || value.pieces.length === 0) throw new Error(`${label} is invalid.`);
+ let previousEnd = 0;
+ for (const [index, piece] of value.pieces.entries()) {
+ const item = `${label}.pieces.${index}`;
+ if (!Number.isSafeInteger(piece.target.startSample) || piece.target.startSample < previousEnd
+ || !Number.isSafeInteger(piece.target.endSampleExclusive)
+ || piece.target.endSampleExclusive <= piece.target.startSample
+ || piece.target.endSampleExclusive > targetSamples) throw new Error(`${item}.target is invalid.`);
+ assertAudioSourceTimeRational(piece.sourceAtStart, `${item}.sourceAtStart`);
+ assertAudioSourceTimeRational(piece.rate, `${item}.rate`, true);
+ if (piece.sourceAtStart.numerator % piece.sourceAtStart.denominator !== 0) {
+ throw new Error(`${item}.sourceAtStart must resolve to an exact source-sample boundary.`);
+ }
+ if (piece.wrap === undefined) {
+ const sourceEndNumerator = BigInt(piece.sourceAtStart.numerator) * BigInt(piece.rate.denominator)
+ + BigInt(piece.target.endSampleExclusive - piece.target.startSample)
+ * BigInt(piece.rate.numerator) * BigInt(piece.sourceAtStart.denominator);
+ const sourceEndDenominator = BigInt(piece.sourceAtStart.denominator) * BigInt(piece.rate.denominator);
+ if (sourceEndNumerator % sourceEndDenominator !== 0n) {
+ throw new Error(`${item} must end on an exact source-sample boundary.`);
+ }
+ if (compareAudioRational(piece.sourceAtStart, value.sourceSampleFrames) >= 0
+ || compareAudioSourceAtEnd(piece, value.sourceSampleFrames) > 0) {
+ throw new Error(`${item} leaves the source domain.`);
+ }
+ } else if (!Number.isSafeInteger(piece.wrap.startSample) || piece.wrap.startSample < 0
+ || !Number.isSafeInteger(piece.wrap.endSampleExclusive)
+ || piece.wrap.endSampleExclusive <= piece.wrap.startSample
+ || piece.wrap.endSampleExclusive > value.sourceSampleFrames
+ || compareAudioRational(piece.sourceAtStart, piece.wrap.startSample) < 0
+ || compareAudioRational(piece.sourceAtStart, piece.wrap.endSampleExclusive) >= 0) {
+ throw new Error(`${item}.wrap is invalid.`);
+ }
+ previousEnd = piece.target.endSampleExclusive;
+ }
+}
+
function trackKey(track: Track): string {
return `${track.kind}\u0000${track.id}`;
}
@@ -1376,9 +1431,9 @@ export function sealComposition(value: Composition): Composition {
return compositionContent(value);
}
-export function assertCompositionIdentity(composition: Composition, programSpace?: ProgramSpace): void {
+export function assertCompositionIdentity(composition: Composition, timeline?: Timeline): void {
assertNonEmpty(composition.id, "Composition id");
- if (programSpace !== undefined) assertProgramSpaceIdentity(programSpace);
+ if (timeline !== undefined) assertTimelineIdentity(timeline);
if (
!Number.isSafeInteger(composition.canvas.width)
|| composition.canvas.width <= 0
@@ -1389,29 +1444,13 @@ export function assertCompositionIdentity(composition: Composition, programSpace
throw new Error("Composition canvas is invalid.");
}
const ids = new Set<string>();
- const stacking = new Map<string, Array<{ readonly trackId: string; readonly present: VisualPresent }>>();
for (const track of composition.tracks) {
if (ids.has(track.id)) throw new Error(`Composition contains duplicate Track id ${track.id}.`);
ids.add(track.id);
if (track.kind === "visual") {
- assertVisualTrackIdentity(track, programSpace);
- for (const present of track.presents) {
- const key = `${present.stacking.order}\u0000${present.stacking.tieBreak}`;
- const peers = stacking.get(key) ?? [];
- for (const peer of peers) {
- const overlaps = present.span.startFrame < peer.present.span.endFrameExclusive
- && peer.present.span.startFrame < present.span.endFrameExclusive;
- if (overlaps) {
- throw new Error(
- `Composition contains overlapping visual stacking key ${key} in ${peer.trackId}.${peer.present.id} and ${track.id}.${present.id}.`,
- );
- }
- }
- peers.push({ trackId: track.id, present });
- stacking.set(key, peers);
- }
+ assertVisualTrackIdentity(track, timeline);
} else {
- assertAudioTrackIdentity(track, programSpace);
+ assertAudioTrackIdentity(track, timeline);
}
}
}
diff --git a/packages/composition/test/render.test.ts b/packages/composition/test/render.test.ts
index 1face20e..a93f756a 100644
--- a/packages/composition/test/render.test.ts
+++ b/packages/composition/test/render.test.ts
@@ -7,7 +7,7 @@ import {
assertFontArtifactRef,
} from "@hypit/media";
import type { CompositableSurfaceRef, FontArtifactRef } from "@hypit/media";
-import { sealProgramSpace } from "@hypit/program-space";
+import { sealTimeline } from "@hypit/timeline";
import {
assertCompositionIdentity,
sealComposition,
@@ -15,8 +15,7 @@ import {
} from "../src/index.js";
import type { VisualTrack } from "../src/index.js";
-const space = sealProgramSpace({ id: "test-space", durationSec: 2,
- frameRate: { numerator: 30, denominator: 1 },
+const space = sealTimeline({ id: "test-space", frameCount: 60, frameRate: { numerator: 30, denominator: 1 },
});
const font: FontArtifactRef = {
@@ -79,13 +78,13 @@ test("CompositableSurfaceRef distinguishes a typed alpha surface from an ordinar
});
test("exact fonts own font selection and cannot conflict with raw CSS font facts", () => {
- const invalid = sealVisualTrack({ programSpaceId: "test-space",
+ const invalid = sealVisualTrack({ timelineId: "test-space",
visualIr: "hypit.visual-ir@1",
id: "invalid-font-track",
presents: [{
id: "title",
span: { startFrame: 0, endFrameExclusive: 60 },
- stacking: { order: 1, tieBreak: "title" },
+ order: 0, z: 1,
elements: [{
id: "title",
order: 0,
@@ -106,15 +105,24 @@ test("exact fonts own font selection and cannot conflict with raw CSS font facts
);
});
-test("animated materialized Surfaces must exactly share the Present frame domain", () => {
- const valid = sealVisualTrack({ programSpaceId: "test-space",
+test("animated materialized Surfaces carry an explicit partial source-time function", () => {
+ const sourceTime = {
+ sourceFrameRate: { numerator: 30, denominator: 1 },
+ sourceFrameCount: 60,
+ pieces: [{
+ target: { startFrame: 0, endFrameExclusive: 60 },
+ sourceAtStart: { numerator: 0, denominator: 1 },
+ rate: { numerator: 1, denominator: 1 },
+ }],
+ } as const;
+ const valid = sealVisualTrack({ timelineId: "test-space",
visualIr: "hypit.visual-ir@1",
id: "surface-track",
presents: [{
id: "surface",
span: { startFrame: 0, endFrameExclusive: 60 },
- stacking: { order: 1, tieBreak: "surface" },
- elements: [{ id: "surface", order: 0, kind: "surface", surface: animatedSurface, style: [] }],
+ order: 0, z: 1,
+ elements: [{ id: "surface", order: 0, kind: "surface", surface: animatedSurface, sourceTime, style: [] }],
}],
});
assert.doesNotThrow(() => assertCompositionIdentity(sealComposition({
@@ -143,17 +151,17 @@ test("animated materialized Surfaces must exactly share the Present frame domain
id: "invalid-surface-composition",
canvas: { width: 1080, height: 1920, clearColor: "#000000" },
tracks: [invalid],
- }), space), /must exactly match its Present frame domain/u);
+ }), space), /target interval is invalid/u);
});
test("a local mask owns exactly one mask root and one content root inside its Present", () => {
- const track = sealVisualTrack({ programSpaceId: "test-space",
+ const track = sealVisualTrack({ timelineId: "test-space",
visualIr: "hypit.visual-ir@1",
id: "masked-text",
presents: [{
id: "mask",
span: { startFrame: 0, endFrameExclusive: 60 },
- stacking: { order: 4, tieBreak: "mask" },
+ order: 0, z: 4,
elements: [
{
id: "local-mask", kind: "mask", order: 0, mode: "alpha",
diff --git a/packages/composition/test/track.test.ts b/packages/composition/test/track.test.ts
index 7ebbf09b..79e6d0fd 100644
--- a/packages/composition/test/track.test.ts
+++ b/packages/composition/test/track.test.ts
@@ -11,7 +11,7 @@ import { artifactManifest } from "@hypit/artifact";
import type { FontArtifactRef } from "@hypit/media";
import { mediaManifest } from "@hypit/media";
import { narrativeManifest } from "@hypit/narrative";
-import { programSpaceManifest, sealProgramSpace } from "@hypit/program-space";
+import { timelineManifest, sealTimeline } from "@hypit/timeline";
import { speechManifest } from "@hypit/speech";
import { speechEvidenceManifest } from "@hypit/speech-evidence";
import { spatialManifest } from "@hypit/spatial";
@@ -30,7 +30,7 @@ import {
} from "../src/index.js";
import type { VisualTrack } from "../src/index.js";
-const videoContractManifests = [artifactManifest, narrativeManifest, mediaManifest, programSpaceManifest,
+const videoContractManifests = [artifactManifest, narrativeManifest, mediaManifest, timelineManifest,
speechManifest, speechEvidenceManifest, svsManifest, spatialManifest, visualIrManifest, compositionManifest] as const;
const font: FontArtifactRef = {
@@ -46,63 +46,64 @@ const audio: BlobRef = {
};
function fixture() {
- const programSpace = sealProgramSpace({ id: "test-space", durationSec: 4,
- frameRate: { numerator: 30, denominator: 1 },
+ const timeline = sealTimeline({ id: "test-space", frameCount: 120, frameRate: { numerator: 30, denominator: 1 },
});
- const visual = sealVisualTrack({ programSpaceId: "test-space",
+ const visual = sealVisualTrack({ timelineId: "test-space",
visualIr: "hypit.visual-ir@1",
id: "caption",
presents: [{
id: "cue-1",
+ order: 0,
+ z: 100,
span: { startFrame: 0, endFrameExclusive: 60 },
- stacking: { order: 100, tieBreak: "caption" },
elements: [
{ id: "root", order: 0, kind: "box", style: [{ name: "position", value: "absolute" }] },
{ id: "text", parent: "root", order: 1, kind: "text", text: "Hello", fonts: [font], style: [] },
],
}],
});
- const sound = sealAudioTrack({ programSpaceId: "test-space",
+ const sound = sealAudioTrack({ timelineId: "test-space",
id: "speech",
clips: [{
id: "speech",
artifact: audio,
target: { startSample: 0, endSampleExclusive: 192_000 },
- source: { sampleFrames: 192_000, startSample: 0, endSampleExclusive: 192_000, loop: false, phaseSample: 0 },
- playbackRate: 1,
- pitch: "preserve",
+ sourceTime: { sourceSampleFrames: 192_000, pieces: [{
+ target: { startSample: 0, endSampleExclusive: 192_000 },
+ sourceAtStart: { numerator: 0, denominator: 1 }, rate: { numerator: 1, denominator: 1 },
+ }] },
gain: 1,
fadeInSamples: 0,
fadeOutSamples: 0,
}],
});
- return { programSpace, visual, sound };
+ return { timeline, visual, sound };
}
test("Composition accepts self-contained peer VisualTrack and AudioTrack values", () => {
- const { programSpace, visual, sound } = fixture();
+ const { timeline, visual, sound } = fixture();
assert.equal(visual.visualIr, VISUAL_IR_V1);
const composition = sealComposition({
id: "main",
canvas: { width: 1080, height: 1920, clearColor: "#000000" },
tracks: [sound, visual],
});
- assert.doesNotThrow(() => assertCompositionIdentity(composition, programSpace));
+ assert.doesNotThrow(() => assertCompositionIdentity(composition, timeline));
assert.deepEqual(composition.tracks.map((track) => track.id), ["speech", "caption"]);
});
test("Composition accepts case-insensitive hexadecimal canvas colors", () => {
- const { programSpace, visual } = fixture();
+ const { timeline, visual } = fixture();
const composition = sealComposition({
id: "uppercase-color",
canvas: { width: 480, height: 854, clearColor: "#09090B" },
tracks: [visual],
});
- assert.doesNotThrow(() => assertCompositionIdentity(composition, programSpace));
+ assert.doesNotThrow(() => assertCompositionIdentity(composition, timeline));
});
test("VisualTrack accepts authored backdrop compositing", () => {
- const { programSpace, visual, sound } = fixture();
+ const { timeline, visual, sound } = fixture();
const content = structuredClone(visual) as VisualTrack;
const first = content.presents[0]!.elements[0]!;
const invasive = sealVisualTrack({...content,
@@ -116,11 +117,11 @@ test("VisualTrack accepts authored backdrop compositing", () => {
canvas: { width: 1080, height: 1920, clearColor: "#000000" },
tracks: [sound, invasive],
});
- assert.doesNotThrow(() => assertCompositionIdentity(composition, programSpace));
+ assert.doesNotThrow(() => assertCompositionIdentity(composition, timeline));
});
test("VisualTrack style values cannot smuggle a second declaration", () => {
- const { programSpace, visual } = fixture();
+ const { timeline, visual } = fixture();
const content = structuredClone(visual) as VisualTrack;
const first = content.presents[0]!.elements[0]!;
const smuggled = sealVisualTrack({...content,
@@ -134,13 +135,13 @@ test("VisualTrack style values cannot smuggle a second declaration", () => {
id: "smuggled",
canvas: { width: 1080, height: 1920, clearColor: "#000000" },
tracks: [smuggled],
- }), programSpace),
+ }), timeline),
/escapes its declaration/,
);
});
test("VisualTrack cannot silently extend the versioned public Visual IR", () => {
- const { programSpace, visual } = fixture();
+ const { timeline, visual } = fixture();
const first = visual.presents[0]!.elements[0]!;
const unknownStyle = sealVisualTrack({...visual,
presents: [{
@@ -153,7 +154,7 @@ test("VisualTrack cannot silently extend the versioned public Visual IR", () =>
id: "unknown-style",
canvas: { width: 1080, height: 1920, clearColor: "#000000" },
tracks: [unknownStyle],
- }), programSpace),
+ }), timeline),
/outside hypit\.visual-ir@1/u,
);
@@ -164,7 +165,7 @@ test("VisualTrack cannot silently extend the versioned public Visual IR", () =>
}],
});
assert.throws(
- () => assertVisualTrackIdentity(fixedPosition, programSpace),
+ () => assertVisualTrackIdentity(fixedPosition, timeline),
/position has unsupported value fixed/u,
);
@@ -175,18 +176,18 @@ test("VisualTrack cannot silently extend the versioned public Visual IR", () =>
}],
});
assert.throws(
- () => assertVisualTrackIdentity(environmentBound, programSpace),
+ () => assertVisualTrackIdentity(environmentBound, timeline),
/environment-dependent style value/u,
);
});
test("VisualTrack explicitly binds the visual IR instead of trusting the Runtime", () => {
- const { programSpace, visual } = fixture();
+ const { timeline, visual } = fixture();
assert.throws(
() => assertVisualTrackIdentity({
...visual,
visualIr: "third-party.browser-css@1",
- } as unknown as VisualTrack, programSpace),
+ } as unknown as VisualTrack, timeline),
/Unsupported VisualTrack visual IR/u,
);
});
@@ -217,31 +218,31 @@ test("the Type owner rejects an invalid VisualTrack at the shared admission gate
);
});
-test("Composition validates Track frame ranges against the explicitly connected ProgramSpace", () => {
- const { programSpace, visual } = fixture();
- const foreign = sealProgramSpace({ id: "test-space", durationSec: 1,
- frameRate: { numerator: 24, denominator: 1 },
+test("Composition validates Track frame ranges against the explicitly connected Timeline", () => {
+ const { timeline, visual } = fixture();
+ const foreign = sealTimeline({ id: "test-space", frameCount: 24, frameRate: { numerator: 24, denominator: 1 },
});
const composition = sealComposition({
id: "foreign",
canvas: { width: 1080, height: 1920, clearColor: "#000000" },
tracks: [visual],
});
- assert.throws(() => assertCompositionIdentity(composition, foreign), /outside ProgramSpace/);
- assert.notDeepEqual(programSpace, foreign);
+ assert.throws(() => assertCompositionIdentity(composition, foreign), /outside Timeline/);
+ assert.notDeepEqual(timeline, foreign);
});
test("one authoring Track may contribute independently stacked Presents", () => {
- const { programSpace, visual } = fixture();
+ const { timeline, visual } = fixture();
const content = structuredClone(visual) as VisualTrack;
const second = {
...structuredClone(content.presents[0]!),
id: "cue-2",
- stacking: { order: 30, tieBreak: "board" },
+ order: 0,
+ z: 30,
};
const interleaved = sealVisualTrack({...content,
presents: [
- { ...content.presents[0]!, stacking: { order: 80, tieBreak: "icon" } },
+ { ...content.presents[0]!, order: 1, z: 80 },
second,
],
});
@@ -250,12 +251,12 @@ test("one authoring Track may contribute independently stacked Presents", () =>
canvas: { width: 1080, height: 1920, clearColor: "#000000" },
tracks: [interleaved],
});
- assert.doesNotThrow(() => assertCompositionIdentity(composition, programSpace));
- assert.deepEqual(interleaved.presents.map((present) => present.stacking.order), [30, 80]);
+ assert.doesNotThrow(() => assertCompositionIdentity(composition, timeline));
+ assert.deepEqual(interleaved.presents.map((present) => present.z), [30, 80]);
});
test("Visual Present animations may finish before or after their visibility window without changing Track isolation", () => {
- const { programSpace, visual } = fixture();
+ const { timeline, visual } = fixture();
const present = visual.presents[0]!;
const root = present.elements[0]!;
const animated = sealVisualTrack({...visual,
@@ -276,7 +277,7 @@ test("Visual Present animations may finish before or after their visibility wind
id: "animated",
canvas: { width: 1080, height: 1920, clearColor: "#000000" },
tracks: [animated],
- }), programSpace));
+ }), timeline));
const clipped = sealVisualTrack({...visual,
presents: [{
...present,
@@ -295,7 +296,7 @@ test("Visual Present animations may finish before or after their visibility wind
id: "clipped-animation",
canvas: { width: 1080, height: 1920, clearColor: "#000000" },
tracks: [clipped],
- }), programSpace));
+ }), timeline));
const invasive = sealVisualTrack({...visual,
presents: [{
...present,
@@ -314,5 +315,5 @@ test("Visual Present animations may finish before or after their visibility wind
id: "animated-invasive",
canvas: { width: 1080, height: 1920, clearColor: "#000000" },
tracks: [invasive],
- }), programSpace));
+ }), timeline));
});
diff --git a/packages/deck-track-studio/README.md b/packages/deck-track-studio/README.md
deleted file mode 100644
index e581bd30..00000000
--- a/packages/deck-track-studio/README.md
+++ /dev/null
@@ -1,3 +0,0 @@
-# `@hypit/deck-track-studio`
-
-Hypit Studio Companion for `@hypit/deck-track`.
diff --git a/packages/deck-track/README.md b/packages/deck-track/README.md
deleted file mode 100644
index e6e89043..00000000
--- a/packages/deck-track/README.md
+++ /dev/null
@@ -1,52 +0,0 @@
-# `@hypit/deck-track`
-
-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.
-
-The official, deliberately narrow depth-stack Deck author package.
-
-`DepthStack` owns ordered Cards, semantic activation points, a finite visible neighborhood,
-relative-depth poses and one deterministic whole-collection reflow. Card pixels reuse the focused
-Media layer lowerer, but Deck is not a Media mode and exports only an ordinary peer `VisualTrack`.
-
-```xml
-<import as="copy" from="@hypit/text@1"/>
-
-<copy:Value id="proof-label">Evidence, not inference</copy:Value>
-<deck:Label id="proof-label-style" content={proof-label}
- font={fonts.ui} size="34" color="#ffffff"/>
-
-<deck:DepthStack
- id="proof-stack"
- timeline={speech.timeline}
- canvas={vertical}
- frame={layout.proof-stack}
- until={story.selection.proof}
- appearance={recipes.deck.proof}
->
- <deck:Card id="proof-1" source={proof1.image} extent={proof1.extent}
- at={story.moment.proof1} label={proof-label-style}/>
- <deck:Card id="proof-2" source={proof2.video} at={story.moment.proof2}/>
-</deck:DepthStack>
-```
-
-The parent Recipe owns visibility, relative-depth pose progression, frame Paint, whole-group
-motion and reflow. A Card Recipe may additionally select explicit future/past playback. Timed
-`continue` is legal only with an active `loop-start` clock, so preview and trail sampling can never
-silently depend on renderer playback history.
-
-Optional labels are separate exact-font values and are referenced by Cards. Filenames, URLs and
-media metadata are never treated as label truth.
-
-The Surface projects every Card `at` and the deck terminal to `TemporalInstant` values before the
-Deck component runs. Card append and completion consume those Instants directly; they never locate
-a Moment/Selection or manufacture a one-frame terminal Window internally.
-
-`deck:Label` accepts either literal body copy or `content={Text}`. It binds that copy to exact font
-and label appearance in a small explicit Fragment. The Deck Track receives the resulting label as
-one normal edge; it never reads filenames, URLs or hidden media metadata.
-
-The package has no Provider, Need, queue, credential, global z band or cross-Track input. Another
-Deck family can install independently and lower to the same terminal `VisualTrack` without changing
-this package, Core, Film, Composition or HyperFrames.
diff --git a/packages/depth-stack-studio/README.md b/packages/depth-stack-studio/README.md
new file mode 100644
index 00000000..85ab9a72
--- /dev/null
+++ b/packages/depth-stack-studio/README.md
@@ -0,0 +1,3 @@
+# `@hypit/depth-stack-studio`
+
+Hypit Studio Companion for `@hypit/depth-stack`.
diff --git a/packages/deck-track-studio/package.json b/packages/depth-stack-studio/package.json
similarity index 79%
rename from packages/deck-track-studio/package.json
rename to packages/depth-stack-studio/package.json
index b586c88d..a5814b0d 100644
--- a/packages/deck-track-studio/package.json
+++ b/packages/depth-stack-studio/package.json
@@ -1,5 +1,5 @@
{
- "name": "@hypit/deck-track-studio",
+ "name": "@hypit/depth-stack-studio",
"version": "0.0.0-dev",
"license": "SEE LICENSE IN LICENSE",
"private": true,
@@ -7,7 +7,7 @@
"exports": { ".": "./src/index.ts" },
"hypit": { "activation": "./src/activation.ts" },
"dependencies": {
- "@hypit/deck-track": "workspace:*",
+ "@hypit/depth-stack": "workspace:*",
"@hypit/composition": "workspace:*",
"@hypit/studio-adapter": "workspace:*"
}
diff --git a/packages/deck-track-studio/src/activation.ts b/packages/depth-stack-studio/src/activation.ts
similarity index 100%
rename from packages/deck-track-studio/src/activation.ts
rename to packages/depth-stack-studio/src/activation.ts
diff --git a/packages/deck-track-studio/src/index.ts b/packages/depth-stack-studio/src/index.ts
similarity index 97%
rename from packages/deck-track-studio/src/index.ts
rename to packages/depth-stack-studio/src/index.ts
index 26a54bb7..91fed908 100644
--- a/packages/deck-track-studio/src/index.ts
+++ b/packages/depth-stack-studio/src/index.ts
@@ -1,5 +1,5 @@
-import { depthStackMarkupSurfaces, depthStackModuleRef } from "@hypit/deck-track";
-import type { DepthStackProgram } from "@hypit/deck-track";
+import { depthStackMarkupSurfaces, depthStackModuleRef } from "@hypit/depth-stack";
+import type { DepthStackProgram } from "@hypit/depth-stack";
import { compositionTypes } from "@hypit/composition";
import type { StudioTrackCompanion, StudioTrackCompanionContext, StudioEntityDraft, StudioInspectorFieldDeclaration } from "@hypit/studio-adapter";
import { requiredSurfaceValue, temporalLineageFor, temporalSemanticSource } from "@hypit/studio-adapter";
@@ -44,7 +44,7 @@ placeDeck([
"next-opacity-step", "border-width", "border-style", "border-color", "shadows", "frame-paint", "opacity",
"blur", "brightness", "contrast", "saturation",
], "how", "Appearance", "Paint");
-placeDeck(["playback", "trim-start", "trim-end", "playback-future", "playback-past"], "how", "Appearance", "Playback");
+placeDeck(["playback-future", "playback-past"], "when", "Playback", "Card Clock");
placeDeck(["reflow-frames", "reflow-easing"], "when", "Motion", "Reflow");
placeDeck(["enter", "enter-frames", "enter-easing", "enter-direction", "enter-amount", "enter-origin"], "when", "Motion", "Enter");
placeDeck(["sustain"], "when", "Motion", "Sustain");
diff --git a/packages/depth-stack/README.md b/packages/depth-stack/README.md
new file mode 100644
index 00000000..197e385d
--- /dev/null
+++ b/packages/depth-stack/README.md
@@ -0,0 +1,51 @@
+# `@hypit/depth-stack`
+
+The DepthStack Surface accepts `timeline={program.timeline}` plus absolute reveal and terminal Instants.
+Those Instants may be authored directly or published by a domain projector upstream.
+
+The official, deliberately narrow depth-stack Deck author package.
+
+`DepthStack` owns ordered Cards, activation points, a finite visible neighborhood,
+relative-depth poses and one deterministic whole-collection reflow. Card pixels reuse Visual Track's
+focused material lowerer, but Deck is not a Visual Clip mode and exports only an ordinary peer
+`VisualTrack`.
+
+```xml
+<import as="copy" from="@hypit/text@1"/>
+
+<copy:Value id="proof-label">Evidence, not inference</copy:Value>
+<deck:Label id="proof-label-style" content={proof-label}
+ font={fonts.ui} size="34" color="#ffffff"/>
+
+<deck:DepthStack
+ id="proof-stack"
+ timeline={speech.timeline}
+ frame={layout.proof-stack}
+ until={story-time.proof-end}
+ appearance={recipes.deck.proof}
+>
+ <deck:Card id="proof-1" source={proof1.image} extent={proof1.extent}
+ at={story-time.proof1} label={proof-label-style}/>
+ <deck:Card id="proof-2" source={proof2.video} at={story-time.proof2}/>
+</deck:DepthStack>
+```
+
+The parent Recipe owns visibility, relative-depth pose progression, frame Paint and reflow. A Card
+Recipe may additionally select explicit future/past behavior. The Deck derives every held or
+continuing source-time map from the Card's declared activation and the current stage; it does not
+require a hidden looping mode on the material and never depends on renderer playback history.
+
+Optional labels are separate exact-font values and are referenced by Cards. Filenames, URLs and
+media metadata are never treated as label truth.
+
+The Surface constructs literal `at` values when needed or passes through resolved
+`TemporalInstant` references. Card append and completion consume those Instants directly; they never
+locate a Moment/Selection or manufacture a one-frame terminal Window internally.
+
+`deck:Label` accepts either literal body copy or `content={Text}`. It binds that copy to exact font
+and label appearance in a small explicit Fragment. The DepthStack receives the resulting label as
+one normal edge; it never reads filenames, URLs or hidden media metadata.
+
+The package has no Provider, Need, queue, credential, global z band or cross-Track input. Another
+Deck family can install independently and lower to the same terminal `VisualTrack` without changing
+this package, Core, Film, Composition or HyperFrames.
diff --git a/packages/deck-track/package.json b/packages/depth-stack/package.json
similarity index 84%
rename from packages/deck-track/package.json
rename to packages/depth-stack/package.json
index c4ffe019..15d7a06e 100644
--- a/packages/deck-track/package.json
+++ b/packages/depth-stack/package.json
@@ -1,5 +1,5 @@
{
- "name": "@hypit/deck-track",
+ "name": "@hypit/depth-stack",
"version": "0.0.0-dev",
"license": "SEE LICENSE IN LICENSE",
"private": true,
@@ -16,9 +16,7 @@
"@hypit/composition": "workspace:*",
"@hypit/elaborator": "workspace:*",
"@hypit/media": "workspace:*",
- "@hypit/media-track": "workspace:*",
- "@hypit/narrative": "workspace:*",
- "@hypit/program-space": "workspace:*",
+ "@hypit/visual-track": "workspace:*",
"@hypit/protocol": "workspace:*",
"@hypit/timeline": "workspace:*",
"@hypit/spatial": "workspace:*",
diff --git a/packages/deck-track/preview/DepthStack.png b/packages/depth-stack/preview/DepthStack.png
similarity index 100%
rename from packages/deck-track/preview/DepthStack.png
rename to packages/depth-stack/preview/DepthStack.png
diff --git a/packages/deck-track/src/activation.ts b/packages/depth-stack/src/activation.ts
similarity index 100%
rename from packages/deck-track/src/activation.ts
rename to packages/depth-stack/src/activation.ts
diff --git a/packages/deck-track/src/author.ts b/packages/depth-stack/src/author.ts
similarity index 90%
rename from packages/deck-track/src/author.ts
rename to packages/depth-stack/src/author.ts
index 9338171d..1ec285bb 100644
--- a/packages/deck-track/src/author.ts
+++ b/packages/depth-stack/src/author.ts
@@ -1,15 +1,14 @@
import {
decodeMediaFit,
decodeMediaFramePaint,
- decodeMediaMotion,
- decodeMediaPresentation,
+ decodeVisualFrameTreatment,
decodeMediaSampleSpec,
- mediaAppearanceKeys,
-} from "@hypit/media-track";
+ visualMaterialKeys,
+} from "@hypit/visual-track";
import type {
MediaPaintLayerSpec,
MediaSampleLayerSpec,
-} from "@hypit/media-track";
+} from "@hypit/visual-track";
import type { ContentFit } from "@hypit/spatial";
import type { SvsRecipe } from "@hypit/svs";
@@ -35,6 +34,7 @@ const DECK_KEYS = [
"next-rotation-mode", "next-opacity-step", "next-stacking-step",
"next-brightness-step", "next-contrast-step", "next-saturation-step",
"reflow-frames", "reflow-easing", "playback-future", "playback-past",
+ "stack-order",
] as const;
function fail(recipe: SvsRecipe, message: string): never {
@@ -120,10 +120,9 @@ function step(
function assertKnownKeys(recipe: SvsRecipe): void {
const allowed = new Set<string>([
...DECK_KEYS,
- ...mediaAppearanceKeys.fit,
- ...mediaAppearanceKeys.sample,
- ...mediaAppearanceKeys.frame,
- ...mediaAppearanceKeys.motion,
+ ...visualMaterialKeys.fit,
+ ...visualMaterialKeys.sample,
+ ...visualMaterialKeys.frame,
]);
const unknown = Object.keys(recipe.properties).filter((key) => !allowed.has(key));
if (unknown.length > 0) fail(recipe, `does not accept ${unknown.join(", ")}.`);
@@ -131,8 +130,7 @@ function assertKnownKeys(recipe: SvsRecipe): void {
export function decodeDepthStackSpec(recipe: SvsRecipe): DepthStackSpec {
assertKnownKeys(recipe);
- const motionRecipe = mediaRecipe(recipe, mediaAppearanceKeys.motion);
- const frameRecipe = mediaRecipe(recipe, mediaAppearanceKeys.frame);
+ const frameRecipe = mediaRecipe(recipe, visualMaterialKeys.frame);
const previousDefaults: DepthStackPoseStep = {
xPerDepthPx: 0,
yPerDepthPx: 28,
@@ -177,8 +175,7 @@ export function decodeDepthStackSpec(recipe: SvsRecipe): DepthStackSpec {
durationFrames: integer(recipe, "reflow-frames", 8),
easing: oneOf(recipe, "reflow-easing", ["linear", "ease-in", "ease-out", "ease-in-out"] as const, "ease-in-out"),
},
- presentation: decodeMediaPresentation(frameRecipe),
- motion: decodeMediaMotion(motionRecipe),
+ treatment: decodeVisualFrameTreatment(frameRecipe),
stackingOrder: integer(recipe, "stack-order", 30),
});
}
@@ -205,9 +202,9 @@ export function decodeDepthStackMaterial(
readonly sample: MediaSampleLayerSpec;
} {
assertKnownKeys(recipe);
- const fitRecipe = mediaRecipe(recipe, mediaAppearanceKeys.fit);
- const sampleRecipe = mediaRecipe(recipe, [...mediaAppearanceKeys.fit, ...mediaAppearanceKeys.sample]);
- const frameRecipe = mediaRecipe(recipe, mediaAppearanceKeys.frame);
+ const fitRecipe = mediaRecipe(recipe, visualMaterialKeys.fit);
+ const sampleRecipe = mediaRecipe(recipe, [...visualMaterialKeys.fit, ...visualMaterialKeys.sample]);
+ const frameRecipe = mediaRecipe(recipe, visualMaterialKeys.frame);
const framePaint = decodeMediaFramePaint(frameRecipe, `${id}:frame-paint`);
return {
fit: decodeMediaFit(fitRecipe),
diff --git a/packages/deck-track/src/component.ts b/packages/depth-stack/src/component.ts
similarity index 94%
rename from packages/deck-track/src/component.ts
rename to packages/depth-stack/src/component.ts
index f86ed711..a0f230d4 100644
--- a/packages/deck-track/src/component.ts
+++ b/packages/depth-stack/src/component.ts
@@ -2,9 +2,9 @@ import type { Timeline } from "@hypit/timeline";
import type { ComponentPackage, ProducerHandlerContext } from "@hypit/component-kit";
import { canonicalize } from "@hypit/protocol";
import type { StoredValue } from "@hypit/protocol";
-import type { CanvasSpace, SpatialFrame } from "@hypit/spatial";
+import type { SpatialFrame } from "@hypit/spatial";
import type { TemporalInstant } from "@hypit/temporal";
-import type { MediaLayerSet } from "@hypit/media-track";
+import type { MediaLayerSet } from "@hypit/visual-track";
import type { Text } from "@hypit/text";
import { renderDepthStack } from "./lower.js";
@@ -73,7 +73,6 @@ export const depthStackComponent = {
{
producer: depthStackProducers.render,
handler: ({ inputs }) => ({ outputs: { track: output(renderDepthStack(
- inline<CanvasSpace>(inputs.canvas?.value, "CanvasSpace"),
inline<Timeline>(inputs.timeline?.value, "Timeline"),
inline<DepthStackProgram>(inputs.program?.value, "DepthStackProgram"),
)) }, needs: {} }),
diff --git a/packages/deck-track/src/fragment.ts b/packages/depth-stack/src/fragment.ts
similarity index 86%
rename from packages/deck-track/src/fragment.ts
rename to packages/depth-stack/src/fragment.ts
index 5ecc0150..43e89657 100644
--- a/packages/deck-track/src/fragment.ts
+++ b/packages/depth-stack/src/fragment.ts
@@ -5,7 +5,7 @@ import { compositionTypes } from "@hypit/composition";
import { sealGraphFragment } from "@hypit/elaborator";
import type { FragmentOperation, GraphFragment } from "@hypit/elaborator";
import { mediaTypes } from "@hypit/media";
-import { mediaTrackProducers, mediaTrackTypes } from "@hypit/media-track";
+import { visualTrackProducers, visualTrackTypes } from "@hypit/visual-track";
import { spatialTypes } from "@hypit/spatial";
import { temporalTypes } from "@hypit/temporal";
@@ -40,7 +40,6 @@ export function createDepthStackFragment(
) {
if (cards.length === 0) throw new Error("DepthStack Fragment requires Cards.");
const inputs: Array<GraphFragment["inputs"][number]> = [
- { name: "canvas", type: spatialTypes.canvas },
{ name: "frame", type: spatialTypes.frame },
{ name: "header", type: depthStackTypes.header },
{ name: "timeline", type: timelineTypes.track },
@@ -60,18 +59,18 @@ export function createDepthStackFragment(
if (card.extentName !== undefined) inputs.push({ name: card.extentName, type: spatialTypes.extent });
inputs.push(
{ name: card.fitName, type: spatialTypes.fit },
- { name: card.sampleSpecName, type: mediaTrackTypes.sampleLayerSpec },
+ { name: card.sampleSpecName, type: visualTrackTypes.sampleLayerSpec },
{ name: card.labelName, type: depthStackTypes.cardLabel },
{ name: card.cardSpecName, type: depthStackTypes.cardSpec },
{ name: card.activationName, type: temporalTypes.instant },
);
if (card.framePaintSpecName !== undefined) {
- inputs.push({ name: card.framePaintSpecName, type: mediaTrackTypes.paintLayerSpec });
+ inputs.push({ name: card.framePaintSpecName, type: visualTrackTypes.paintLayerSpec });
}
const layersId = `layers-${card.suffix}`;
operations.push({
id: layersId,
- producer: mediaTrackProducers.createLayers,
+ producer: visualTrackProducers.createLayers,
inputs: {},
result: { kind: "output", name: "layers" },
});
@@ -80,7 +79,7 @@ export function createDepthStackFragment(
const paintId = `paint-${card.suffix}`;
operations.push({
id: paintId,
- producer: mediaTrackProducers.appendPaintLayer,
+ producer: visualTrackProducers.appendPaintLayer,
inputs: { layers, spec: input(card.framePaintSpecName) },
result: { kind: "output", name: "layers" },
});
@@ -88,8 +87,8 @@ export function createDepthStackFragment(
}
const sampleId = `sample-${card.suffix}`;
const producer = card.sourceKind === "still"
- ? mediaTrackProducers.appendStillLayer
- : card.sourceKind === "timed" ? mediaTrackProducers.appendTimedLayer : mediaTrackProducers.appendSurfaceLayer;
+ ? visualTrackProducers.appendStillLayer
+ : card.sourceKind === "timed" ? visualTrackProducers.appendTimedLayer : visualTrackProducers.appendSurfaceLayer;
operations.push({
id: sampleId,
producer,
@@ -135,7 +134,7 @@ export function createDepthStackFragment(
operations.push({
id: "track",
producer: depthStackProducers.render,
- inputs: { canvas: input("canvas"), timeline: input("timeline"), program: operation("program") },
+ inputs: { timeline: input("timeline"), program: operation("program") },
result: { kind: "output", name: "track" },
});
return sealGraphFragment({
@@ -143,7 +142,7 @@ export function createDepthStackFragment(
operations,
exports: [
{ name: "program", type: depthStackTypes.program, root: operation("program") },
- { name: "track", type: compositionTypes.visualTrack, root: operation("track") },
+ { name: "visual", type: compositionTypes.visualTrack, root: operation("track") },
],
});
}
diff --git a/packages/deck-track/src/index.ts b/packages/depth-stack/src/index.ts
similarity index 100%
rename from packages/deck-track/src/index.ts
rename to packages/depth-stack/src/index.ts
diff --git a/packages/deck-track/src/lower.ts b/packages/depth-stack/src/lower.ts
similarity index 72%
rename from packages/deck-track/src/lower.ts
rename to packages/depth-stack/src/lower.ts
index 7ec9eab9..1c4ecc7c 100644
--- a/packages/deck-track/src/lower.ts
+++ b/packages/depth-stack/src/lower.ts
@@ -6,23 +6,20 @@ import {
import type {
VisualAnimation,
VisualElement,
+ VisualSourceTimeMap,
VisualStyleDeclaration,
- VisualTimedSampling,
VisualTrack,
} from "@hypit/composition";
import {
- lifecycleAnimationWindow,
- lowerMediaItemElements,
- resolveVisualSampling,
- sustainAnimationWindow,
-} from "@hypit/media-track";
+ lowerVisualClipElements,
+ resolveMediaLayerPrograms,
+ resolveVisualSourceTime,
+} from "@hypit/visual-track";
import type {
- MediaItemProgram,
- MediaSampleLayerProgram,
- MediaVisualTrim,
-} from "@hypit/media-track";
-import { assertCanvasSpace } from "@hypit/spatial";
-import type { CanvasSpace, SpatialFrame } from "@hypit/spatial";
+ VisualClipProgram,
+ MediaSampleLayer,
+} from "@hypit/visual-track";
+import type { SpatialFrame } from "@hypit/spatial";
import {
assertDepthStackProgramIdentity,
@@ -106,7 +103,7 @@ function modulo(value: number, size: number): number {
return ((value % size) + size) % size;
}
-function sourceTiming(layer: MediaSampleLayerProgram): {
+function sourceTiming(layer: MediaSampleLayer): {
readonly frameRate: { readonly numerator: number; readonly denominator: number };
readonly frameCount: number;
} | undefined {
@@ -122,88 +119,79 @@ function sourceTiming(layer: MediaSampleLayerProgram): {
return undefined;
}
-function trimFor(layer: MediaSampleLayerProgram, frameCount: number): MediaVisualTrim {
- return layer.trim ?? { startFrame: 0, endFrameExclusive: frameCount };
-}
-
-function heldSampling(
+function heldSourceTime(
timing: NonNullable<ReturnType<typeof sourceTiming>>,
targetFrames: number,
sourceFrame: number,
-): VisualTimedSampling {
+): VisualSourceTimeMap {
return {
sourceFrameRate: { ...timing.frameRate },
sourceFrameCount: timing.frameCount,
- segments: [{
+ pieces: [{
target: { startFrame: 0, endFrameExclusive: targetFrames },
- sourceFrame: rational(sourceFrame),
+ sourceAtStart: rational(sourceFrame),
rate: rational(0),
}],
};
}
-function continuedSampling(input: {
+function continuedSourceTime(input: {
readonly timing: NonNullable<ReturnType<typeof sourceTiming>>;
- readonly trim: MediaVisualTrim;
readonly targetFrames: number;
readonly absoluteStart: number;
readonly activationFrame: number;
-}): VisualTimedSampling {
- const length = input.trim.endFrameExclusive - input.trim.startFrame;
+}): VisualSourceTimeMap {
+ const length = input.timing.frameCount;
const phase = modulo(input.absoluteStart - input.activationFrame, length);
return {
sourceFrameRate: { ...input.timing.frameRate },
sourceFrameCount: input.timing.frameCount,
- segments: [{
+ pieces: [{
target: { startFrame: 0, endFrameExclusive: input.targetFrames },
- sourceFrame: rational(input.trim.startFrame + phase),
+ sourceAtStart: rational(phase),
rate: rational(1),
- loop: { ...input.trim },
+ wrap: { startFrame: 0, endFrameExclusive: input.timing.frameCount },
}],
};
}
-function samplingFor(input: {
+function sourceTimeFor(input: {
readonly program: DepthStackProgram;
readonly card: DepthStackCard;
- readonly layer: MediaSampleLayerProgram;
+ readonly layer: MediaSampleLayer;
readonly relation: number;
readonly stageStart: number;
readonly stageDuration: number;
readonly timeline: Timeline;
-}): VisualTimedSampling | undefined {
+}): VisualSourceTimeMap | undefined {
const timing = sourceTiming(input.layer);
if (timing === undefined) return undefined;
assert(timing.frameRate.numerator === input.timeline.frameRate.numerator
&& timing.frameRate.denominator === input.timeline.frameRate.denominator,
`DepthStack Card ${input.card.id} timed material must be normalized to Timeline.`);
- const trim = trimFor(input.layer, timing.frameCount);
if (input.relation === 0) {
- return resolveVisualSampling({
+ if (input.layer.sourceTime?.kind === "map") return input.layer.sourceTime.value;
+ return resolveVisualSourceTime({
timeline: input.timeline,
sourceFrameRate: timing.frameRate,
sourceFrameCount: timing.frameCount,
targetFrameCount: input.stageDuration,
- trim,
- occupancy: input.layer.occupancy!,
+ ...(input.layer.sourceTime?.kind !== "spec" ? {} : { spec: input.layer.sourceTime.value }),
});
}
const mode = input.relation > 0 ? input.card.playback.future : input.card.playback.past;
if (mode === "continue") {
- assert(input.layer.occupancy?.mode === "loop" && input.layer.occupancy.align === "start",
- `DepthStack Card ${input.card.id} continue playback requires loop-start active occupancy.`);
- return continuedSampling({
+ return continuedSourceTime({
timing,
- trim,
targetFrames: input.stageDuration,
absoluteStart: input.stageStart,
activationFrame: input.card.activationFrame,
});
}
- return heldSampling(
+ return heldSourceTime(
timing,
input.stageDuration,
- mode === "hold-tail" ? trim.endFrameExclusive - 1 : trim.startFrame,
+ mode === "hold-tail" ? timing.frameCount - 1 : 0,
);
}
@@ -215,9 +203,6 @@ function groupElements(input: {
readonly poseAnimation?: VisualAnimation;
}): { readonly elements: VisualElement[]; readonly poseParent: string } {
const frame = input.program.frame;
- const duration = input.program.span.endFrameExclusive - input.program.span.startFrame;
- const startOffset = input.stageStart - input.program.span.startFrame;
- const endOffset = input.stageEnd - input.program.span.startFrame;
let order = 0;
const elements: VisualElement[] = [rootBox("deck-placement", undefined, order++, [
{ name: "height", value: px(frame.heightPx) },
@@ -226,26 +211,7 @@ function groupElements(input: {
{ name: "top", value: px(frame.yPx) },
{ name: "width", value: px(frame.widthPx) },
])];
- let parent = "deck-placement";
- const lifecycle = lifecycleAnimationWindow(input.program.spec.motion, duration, startOffset, endOffset);
- elements.push(rootBox("deck-lifecycle", parent, order++, [
- { name: "height", value: "100%" },
- { name: "position", value: "absolute" },
- { name: "transform-origin", value: "center center" },
- { name: "width", value: "100%" },
- ], lifecycle));
- parent = "deck-lifecycle";
- for (const [index, sustain] of input.program.spec.motion.sustain.entries()) {
- const id = `deck-sustain-${index + 1}`;
- elements.push(rootBox(id, parent, order++, [
- { name: "height", value: "100%" },
- { name: "position", value: "absolute" },
- { name: "transform-origin", value: "center center" },
- { name: "width", value: "100%" },
- ], sustainAnimationWindow(sustain, duration, startOffset, endOffset)));
- parent = id;
- }
- elements.push(rootBox("deck-pose", parent, order++, [
+ elements.push(rootBox("deck-pose", "deck-placement", order++, [
{ name: "height", value: "100%" },
{ name: "position", value: "absolute" },
{ name: "transform-origin", value: "center center" },
@@ -281,12 +247,10 @@ function labelElement(card: DepthStackCard, parent: string, order: number): Visu
}
export function renderDepthStack(
- canvas: CanvasSpace,
timeline: Timeline,
program: DepthStackProgram,
): VisualTrack {
assertDepthStackProgramIdentity(program, timeline);
- assertCanvasSpace(canvas);
const presents: VisualTrack["presents"][number][] = [];
for (let stageIndex = 0; stageIndex < program.cards.length; stageIndex += 1) {
const stageStart = program.cards[stageIndex]!.activationFrame;
@@ -318,49 +282,46 @@ export function renderDepthStack(
...(animation === undefined ? {} : { poseAnimation: animation }),
});
const relation = newDepth ?? (oldDepth === 0 ? -1 : oldDepth ?? 1);
- const samplingOverrides: Record<string, VisualTimedSampling> = {};
+ const sourceTimeOverrides: Record<string, VisualSourceTimeMap> = {};
const samplingAnimationOverrides: Record<string, VisualAnimation | null> = {};
for (const layer of card.material.layers) {
if (layer.kind !== "sample") continue;
- const sampling = samplingFor({ program, card, layer, relation, stageStart, stageDuration, timeline });
- if (sampling !== undefined) samplingOverrides[layer.id] = sampling;
+ const sourceTime = sourceTimeFor({ program, card, layer, relation, stageStart, stageDuration, timeline });
+ if (sourceTime !== undefined) sourceTimeOverrides[layer.id] = sourceTime;
if (relation !== 0 && layer.samplingMotion !== undefined) samplingAnimationOverrides[layer.id] = null;
}
- const mediaItem: MediaItemProgram = {
+ const mediaItem: VisualClipProgram = {
id: "deck-material",
subjectId: card.id,
span: { startFrame: stageStart, endFrameExclusive: stageEnd },
frame: localFrame(program.frame),
- presentation: structuredClone(program.spec.presentation),
- layers: structuredClone(card.material.layers),
- motion: { sustain: [] },
- stacking: { order: 0, tieBreak: card.id },
- sounds: [],
+ treatment: structuredClone(program.spec.treatment),
+ layers: resolveMediaLayerPrograms(card.material, localFrame(program.frame), program.spec.treatment),
+ order: 0,
+ z: 0,
};
- const material = [...lowerMediaItemElements(mediaItem, timeline, {
+ const material = [...lowerVisualClipElements(mediaItem, timeline, {
placementParent: group.poseParent,
- lifecycleAnimationOverride: null,
- samplingOverrides,
+ poseAnimationOverride: null,
+ sourceTimeOverrides,
samplingAnimationOverrides,
})].map((element) => ({ ...element, order: element.order + group.elements.length }));
const frameId = `${mediaItem.id}:frame`;
const label = labelElement(card, frameId, material.reduce((maximum, element) => Math.max(maximum, element.order), 0) + 1);
presents.push({
id: `${card.id}:stage:${stageIndex + 1}`,
+ order: presents.length,
+ z: program.spec.stackingOrder + (newDepth === undefined
+ ? resolveDepthStackPose(program.spec, oldDepth ?? 0).stacking
+ : resolveDepthStackPose(program.spec, newDepth).stacking),
subjectId: card.id,
span: { startFrame: stageStart, endFrameExclusive: stageEnd },
- stacking: {
- order: program.spec.stackingOrder + (newDepth === undefined
- ? resolveDepthStackPose(program.spec, oldDepth ?? 0).stacking
- : resolveDepthStackPose(program.spec, newDepth).stacking),
- tieBreak: `${program.id}:${String(stageIndex).padStart(4, "0")}:${card.id}`,
- },
elements: [...group.elements, ...material, ...(label === undefined ? [] : [label])],
});
}
}
const track = sealVisualTrack({
- programSpaceId: timeline.id,
+ timelineId: timeline.id,
visualIr: "hypit.visual-ir@1",
id: program.id,
presents,
diff --git a/packages/deck-track/src/manifest.ts b/packages/depth-stack/src/manifest.ts
similarity index 80%
rename from packages/deck-track/src/manifest.ts
rename to packages/depth-stack/src/manifest.ts
index 86df0925..df034466 100644
--- a/packages/deck-track/src/manifest.ts
+++ b/packages/depth-stack/src/manifest.ts
@@ -1,4 +1,4 @@
-import { timelineTypes } from "@hypit/timeline";
+import { timelineTypes, timelineDependency } from "@hypit/timeline";
import { temporalContextAttributeVocabulary } from "@hypit/temporal-markup";
import { readFile } from "node:fs/promises";
@@ -13,16 +13,13 @@ import {
} from "@hypit/composition";
import { mediaDependency, mediaTypes } from "@hypit/media";
import {
- mediaFramePresentationSchema,
+ visualFrameTreatmentSchema,
mediaLayerSetSchema,
- mediaLifecycleMotionSchema,
- mediaTrackDependency,
- mediaTrackTypes,
-} from "@hypit/media-track";
-import { narrativeDependency, narrativeTypes } from "@hypit/narrative";
+ visualTrackDependency,
+ visualTrackTypes,
+} from "@hypit/visual-track";
import type { ModuleManifest, ProducerRef, TypeRef, ValueSchema } from "@hypit/protocol";
-import { timelineDependency } from "@hypit/timeline";
import { spatialDependency, spatialFrameSchema, spatialTypes } from "@hypit/spatial";
import { svsRecipeType } from "@hypit/svs";
import { temporalDependency, temporalTypes } from "@hypit/temporal";
@@ -35,7 +32,7 @@ const previewImage = (file: string) => ({
open: async () => Uint8Array.from(await readFile(new URL(`../preview/${file}`, import.meta.url))),
});
-export const depthStackModuleRef = { name: "@hypit/deck-track", version: "1" } as const;
+export const depthStackModuleRef = { name: "@hypit/depth-stack", version: "1" } as const;
export const depthStackTypes = {
header: { module: depthStackModuleRef, name: "DepthStackHeader" },
spec: { module: depthStackModuleRef, name: "DepthStackSpec" },
@@ -82,7 +79,7 @@ export const depthStackSpecSchema: ValueSchema = object({
visibility: { schema: object({ previous: { schema: unsignedInteger }, next: { schema: unsignedInteger }, wrap: { schema: { kind: "boolean" } } }) },
poses: { schema: object({ current: { schema: pose }, previous: { schema: poseStep }, next: { schema: poseStep } }) },
reflow: { schema: object({ durationFrames: { schema: unsignedInteger }, easing: { schema: enumString(["linear", "ease-in", "ease-out", "ease-in-out"]) } }) },
- presentation: { schema: mediaFramePresentationSchema }, motion: { schema: mediaLifecycleMotionSchema }, stackingOrder: { schema: integer },
+ treatment: { schema: visualFrameTreatmentSchema }, stackingOrder: { schema: integer },
});
export const depthStackCardSpecSchema: ValueSchema = object({
id: { schema: string }, playback: { schema: playback },
@@ -158,21 +155,19 @@ export const depthStackMarkupSurfaces = [
} },
{ name: "track", tag: "DepthStack", mode: "structured", outputs: [
depthStackTypes.header, depthStackTypes.spec, depthStackTypes.cardSpec,
- spatialTypes.fit, mediaTrackTypes.sampleLayerSpec, mediaTrackTypes.paintLayerSpec,
+ spatialTypes.fit, visualTrackTypes.sampleLayerSpec, visualTrackTypes.paintLayerSpec,
depthStackTypes.cardLabel, depthStackTypes.cardLabelStyle, textTypes.text,
temporalTypes.instantSpec, temporalTypes.instant,
depthStackTypes.program, compositionTypes.visualTrack,
],
vocabulary: {
summary: "Deals ordered Cards into one Frame, each at its own Moment, and publishes the deck and the VisualTrack it renders to.",
- appearance: "One leaning pile of overlapping picture Cards inside a single Frame, every Card drawn over the same rectangle and told apart only by its pose. The Card most recently dealt sits in front, upright and at full size; each Card dealt before it stands one step further behind — shifted down, smaller, tilted, fainter and duller with every step — and each Card still to come peeks out the opposite way, with two behind and one ahead kept on screen by default, so at most four Cards share the Frame. A Card is its own still, timed or surface picture fitted into that Frame, optionally over a painted Frame, inside a rounded clip and behind a border and shadows, and may carry a line of label copy laid across it. Cards arrive one at a time in document order: at each Card's Moment the arriving Card fades in from beyond the visible neighborhood and the whole pile slides, scales and rotates into its new poses over a handful of Frames, the Card pushed off the back fading out, and the pile as a whole may arrive, drift and leave as one.",
+ appearance: "One leaning pile of overlapping picture Cards inside a single Frame, every Card drawn over the same rectangle and told apart only by its pose. The Card most recently dealt sits in front, upright and at full size; each Card dealt before it stands one step further behind — shifted down, smaller, tilted, fainter and duller with every step — and each Card still to come peeks out the opposite way. A Card is its own still, timed or surface picture fitted into that Frame, optionally over a painted Frame, inside a rounded clip and behind a border and shadows, and may carry a line of label copy. Cards arrive in document order: at each Card's Moment the whole collection deterministically reflows into its new depth poses.",
preview: previewImage("DepthStack.png"),
attributes: [
{ name: "id", kind: "identifier", required: true,
summary: "Names this deck so its Program and Track can be referenced elsewhere in the Source." },
...temporalContextAttributeVocabulary,
- { name: "canvas", kind: "reference", required: true, accepts: [spatialTypes.canvas],
- summary: "Chooses the Canvas the deck is rendered into." },
{ name: "frame", kind: "reference", required: true, accepts: [spatialTypes.frame],
summary: "Chooses the Frame the whole stack occupies." },
{ name: "appearance", kind: "reference", required: true, accepts: [svsRecipeType],
@@ -250,32 +245,6 @@ export const depthStackMarkupSurfaces = [
summary: "Colors that border, and is required whenever `border-width` is not `0`." },
{ name: "shadows", required: false, fallback: "none",
summary: "Casts shadows behind a Card, as `x y blur spread color` entries separated by semicolons." },
- { name: "enter", required: false, values: ["none", "fade", "slide", "scale", "pop", "bounce", "blur-reveal", "wipe", "flip", "spin"], fallback: "none",
- summary: "Selects how the deck arrives at the start of its span." },
- { name: "enter-frames", required: false,
- summary: "Sets how many Frames that arrival takes, and is required whenever `enter` is anything but `none`." },
- { name: "enter-easing", required: false, values: ["linear", "ease-in", "ease-out", "ease-in-out"], fallback: "ease-in-out",
- summary: "Shapes the arrival's progress over its Frames." },
- { name: "enter-direction", required: false, values: ["left", "right", "up", "down"],
- summary: "Sends the arrival in one direction, for the operators that travel." },
- { name: "enter-amount", required: false,
- summary: "Sets how far the arrival travels or scales, in the units its operator reads." },
- { name: "enter-origin", required: false, values: ["outside-canvas"],
- summary: "Starts the arrival from beyond the Canvas rather than from the deck's own Frame." },
- { name: "sustain", required: false, fallback: "none",
- summary: "Keeps the deck moving between its arrival and its departure, as `operator amount cycles [direction]` entries separated by commas, over `float`, `breathe`, `pulse`, `wobble`, `shake` and `drift`." },
- { name: "exit", required: false, values: ["none", "fade", "slide", "scale", "pop", "bounce", "blur-reveal", "wipe", "flip", "spin"], fallback: "none",
- summary: "Selects how the deck leaves at the end of its span." },
- { name: "exit-frames", required: false,
- summary: "Sets how many Frames that departure takes, and is required whenever `exit` is anything but `none`." },
- { name: "exit-easing", required: false, values: ["linear", "ease-in", "ease-out", "ease-in-out"], fallback: "ease-in-out",
- summary: "Shapes the departure's progress over its Frames." },
- { name: "exit-direction", required: false, values: ["left", "right", "up", "down"],
- summary: "Sends the departure in one direction, for the operators that travel." },
- { name: "exit-amount", required: false,
- summary: "Sets how far the departure travels or scales, in the units its operator reads." },
- { name: "exit-origin", required: false, values: ["outside-canvas"],
- summary: "Carries the departure out beyond the Canvas rather than stopping at the deck's own Frame." },
{ name: "fit", required: false, values: ["contain", "cover", "fit-width", "fit-height", "native", "scale-down", "stretch"], fallback: "contain",
summary: "Decides how a Card's picture is sized against the Card's Frame." },
{ name: "frame-x", required: false, fallback: "0.5",
@@ -304,22 +273,13 @@ export const depthStackMarkupSurfaces = [
summary: "Sets the contrast the Card's picture is sampled at, before any depth tone is applied." },
{ name: "saturation", required: false, fallback: "1",
summary: "Sets the saturation the Card's picture is sampled at, before any depth tone is applied." },
- { name: "playback", required: false, values: ["once-start", "once-end", "hold-start", "hold-end", "loop-start", "loop-end", "stretch"], fallback: "once-start",
- summary: "Decides how timed material occupies the Card's window, and is refused on a still image." },
- { name: "trim-start", required: false,
- summary: "Starts timed material at this frame of its own timeline, and must be written together with `trim-end`." },
- { name: "trim-end", required: false,
- summary: "Ends timed material before this frame of its own timeline, and must be written together with `trim-start`." },
{ name: "playback-future", required: false, values: ["hold-head", "continue"], fallback: "hold-head",
summary: "Decides what a Card shows before it is dealt: its first frame held, or its own timeline running on." },
{ name: "playback-past", required: false, values: ["hold-tail", "continue", "hide"], fallback: "hold-tail",
summary: "Decides what a Card shows once its material is spent: its last frame held, its own timeline running on, or nothing." },
] },
- { name: "until", kind: "expression", required: true,
- accepts: [narrativeTypes.moment, narrativeTypes.selection, narrativeTypes.excerpt],
- summary: "Ends the deck at a Moment, a Selection or Segment boundary, or an authored time such as 8s." },
- { name: "until-boundary", kind: "literal", required: false, values: ["start", "end"],
- summary: "Chooses which edge of the ending Selection or Segment ends the deck." },
+ { name: "until", kind: "expression", required: true, accepts: [temporalTypes.instant],
+ summary: "Ends the deck at an already resolved Instant or an authored absolute time such as 8s." },
],
children: [
{ tag: "Card", cardinality: "many",
@@ -364,12 +324,6 @@ export const depthStackMarkupSurfaces = [
summary: "Sets the contrast this Card's picture is sampled at, before any depth tone is applied." },
{ name: "saturation", required: false, fallback: "1",
summary: "Sets the saturation this Card's picture is sampled at, before any depth tone is applied." },
- { name: "playback", required: false, values: ["once-start", "once-end", "hold-start", "hold-end", "loop-start", "loop-end", "stretch"], fallback: "once-start",
- summary: "Decides how timed material occupies this Card's window, and is refused on a still image." },
- { name: "trim-start", required: false,
- summary: "Starts timed material at this frame of its own timeline, and must be written together with `trim-end`." },
- { name: "trim-end", required: false,
- summary: "Ends timed material before this frame of its own timeline, and must be written together with `trim-start`." },
{ name: "playback-future", required: false, values: ["hold-head", "continue"], fallback: "hold-head",
summary: "Decides what this Card shows before it is dealt: its first frame held, or its own timeline running on." },
{ name: "playback-past", required: false, values: ["hold-tail", "continue", "hide"], fallback: "hold-tail",
@@ -382,25 +336,24 @@ export const depthStackMarkupSurfaces = [
ports: [
{ name: "program", type: depthStackTypes.program,
summary: "The resolved deck: its span, its Frame, its spec and its ordered Cards." },
- { name: "track", type: compositionTypes.visualTrack,
+ { name: "visual", type: compositionTypes.visualTrack,
summary: "The rendered deck, an ordinary peer VisualTrack." },
],
example: `<deck:DepthStack
id="proof-stack"
timeline={speech.timeline}
- canvas={vertical}
frame={layout.proof-stack}
- until={story.selection.proof}
+ until={story-time.proof-end}
appearance={recipes.deck.proof}
>
<deck:Card id="proof-1" source={proof1.image} extent={proof1.extent}
- at={story.moment.proof1} label={proof-label-style}/>
- <deck:Card id="proof-2" source={proof2.video} at={story.moment.proof2}/>
+ at={story-time.proof1} label={proof-label-style}/>
+ <deck:Card id="proof-2" source={proof2.video} at={story-time.proof2}/>
</deck:DepthStack>`,
notes: [
"The deck requires at least one Card, and a Card is empty.",
"`extent` is required for a still image source and refused for a Synchronized Medium or a Compositable Surface.",
- "`until-boundary` defaults to `end` when `until` names a Selection or Segment.",
+ "`until` consumes an absolute Instant; domain projection is declared upstream.",
"Both Recipes are closed: any property outside the ones listed here is refused, and a Card without its own `appearance` reads the deck's Recipe for fit, sampling, frame Paint and playback.",
],
} },
@@ -409,7 +362,7 @@ export const depthStackMarkupSurfaces = [
export const depthStackManifest: ModuleManifest = {
format: "hypit.module@1", name: depthStackModuleRef.name, version: depthStackModuleRef.version,
- dependencies: [narrativeDependency, timelineDependency, spatialDependency, temporalDependency, mediaDependency, mediaTrackDependency, compositionDependency, textDependency],
+ dependencies: [timelineDependency, spatialDependency, temporalDependency, mediaDependency, visualTrackDependency, compositionDependency, textDependency],
types: [
{ name: depthStackTypes.header.name },
{ name: depthStackTypes.spec.name },
@@ -423,7 +376,7 @@ export const depthStackManifest: ModuleManifest = {
{ name: depthStackProducers.bindLabelText.name, inputs: [{ name: "style", type: depthStackTypes.cardLabelStyle }, { name: "content", type: textTypes.text }], outputs: [{ name: "label", type: depthStackTypes.cardLabel }], needs: [] },
{ name: depthStackProducers.createCards.name, inputs: [], outputs: [{ name: "set", type: depthStackTypes.cardSet }], needs: [] },
{ name: depthStackProducers.appendCard.name, inputs: [
- { name: "set", type: depthStackTypes.cardSet }, { name: "timeline", type: timelineTypes.track }, { name: "material", type: mediaTrackTypes.layerSet },
+ { name: "set", type: depthStackTypes.cardSet }, { name: "timeline", type: timelineTypes.track }, { name: "material", type: visualTrackTypes.layerSet },
{ name: "label", type: depthStackTypes.cardLabel }, { name: "spec", type: depthStackTypes.cardSpec },
{ name: "activation", type: temporalTypes.instant },
], outputs: [{ name: "set", type: depthStackTypes.cardSet }], needs: [] },
@@ -431,7 +384,7 @@ export const depthStackManifest: ModuleManifest = {
inputs: [...finalizeInputs, { name: "terminal", type: temporalTypes.instant }],
outputs: [{ name: "program", type: depthStackTypes.program }], needs: [] },
{ name: depthStackProducers.render.name, inputs: [
- { name: "canvas", type: spatialTypes.canvas }, { name: "timeline", type: timelineTypes.track },
+ { name: "timeline", type: timelineTypes.track },
{ name: "program", type: depthStackTypes.program },
], outputs: [{ name: "track", type: compositionTypes.visualTrack }], needs: [] },
],
diff --git a/packages/deck-track/src/program.ts b/packages/depth-stack/src/program.ts
similarity index 94%
rename from packages/deck-track/src/program.ts
rename to packages/depth-stack/src/program.ts
index 410a3ec9..21ff6863 100644
--- a/packages/deck-track/src/program.ts
+++ b/packages/depth-stack/src/program.ts
@@ -1,13 +1,12 @@
+import { assertTimelineIdentity, timelineFrameCount } from "@hypit/timeline";
import type { Timeline } from "@hypit/timeline";
import {
assertFontArtifactRef,
} from "@hypit/media";
import {
- assertMediaFramePresentation,
+ assertVisualFrameTreatment,
assertMediaLayerSet,
- assertMediaLifecycleMotion,
-} from "@hypit/media-track";
-import { assertProgramSpaceIdentity, programSpaceFrameCount } from "@hypit/program-space";
+} from "@hypit/visual-track";
import { canonicalize } from "@hypit/protocol";
import { verifyText } from "@hypit/text";
import type { Text } from "@hypit/text";
@@ -93,7 +92,7 @@ export function assertDepthStackSpec(value: DepthStackSpec): void {
"DepthStackSpec.reflow.durationFrames must be a non-negative integer.");
assert(["linear", "ease-in", "ease-out", "ease-in-out"].includes(value.reflow.easing),
"DepthStackSpec.reflow.easing is invalid.");
- assertMediaFramePresentation(value.presentation, "DepthStackSpec.presentation");
+ assertVisualFrameTreatment(value.treatment, "DepthStackSpec.treatment");
assert(Number.isSafeInteger(value.stackingOrder), "DepthStackSpec.stackingOrder must be an integer.");
}
@@ -232,7 +231,7 @@ export function appendDepthStackCard(
spec: DepthStackCardSpec,
activation: TemporalInstant,
): DepthStackCardSet {
- assertTemporalInstantFor(activation, { subjectId: spec.id, space: timeline });
+ assertTemporalInstantFor(activation, { subjectId: spec.id, timeline: timeline });
return appendDepthStackCardAtFrame(set, material, label, spec, activation.frame);
}
@@ -248,7 +247,7 @@ function finalizeDepthStackAtFrame(
assertDepthStackHeader(header);
assertSpatialFrame(frame);
assertDepthStackSpec(spec);
- assertProgramSpaceIdentity(timeline);
+ assertTimelineIdentity(timeline);
assert(set.cards.length > 0, "DepthStack requires at least one Card.");
const first = set.cards[0]!;
const program: DepthStackProgram = {
@@ -272,7 +271,7 @@ export function finalizeDepthStack(
terminal: TemporalInstant,
timeline: Timeline,
): DepthStackProgram {
- assertTemporalInstantFor(terminal, { subjectId: header.id, space: timeline });
+ assertTemporalInstantFor(terminal, { subjectId: header.id, timeline: timeline });
return finalizeDepthStackAtFrame(set, header, frame, spec, terminal.frame, timeline);
}
@@ -294,8 +293,6 @@ export function assertDepthStackProgram(program: DepthStackProgram): void {
assert(program.spec.visibility.previous + program.spec.visibility.next + 1 <= program.cards.length,
"Wrapped DepthStack visibility would show one Card at several relative depths.");
}
- const duration = program.terminalFrame - program.cards[0]!.activationFrame;
- assertMediaLifecycleMotion(program.spec.motion, duration, "DepthStack whole-group motion");
for (let index = 1; index < program.cards.length; index += 1) {
const stageEnd = program.cards[index + 1]?.activationFrame ?? program.terminalFrame;
const stageDuration = stageEnd - program.cards[index]!.activationFrame;
@@ -305,9 +302,9 @@ export function assertDepthStackProgram(program: DepthStackProgram): void {
}
export function assertDepthStackProgramIdentity(program: DepthStackProgram, timeline: Timeline): void {
- assertProgramSpaceIdentity(timeline);
+ assertTimelineIdentity(timeline);
assertDepthStackProgram(program);
- assert(program.terminalFrame <= programSpaceFrameCount(timeline), "DepthStack terminal is outside Timeline.");
+ assert(program.terminalFrame <= timelineFrameCount(timeline), "DepthStack terminal is outside Timeline.");
}
function modulo(value: number, size: number): number {
diff --git a/packages/deck-track/src/surface.ts b/packages/depth-stack/src/surface.ts
similarity index 91%
rename from packages/deck-track/src/surface.ts
rename to packages/depth-stack/src/surface.ts
index 7f2353db..69f9a5ff 100644
--- a/packages/deck-track/src/surface.ts
+++ b/packages/depth-stack/src/surface.ts
@@ -2,11 +2,11 @@ import { resolveTemporalContext } from "@hypit/temporal-markup";
import { artifactTypes } from "@hypit/artifact";
import { mediaTypes } from "@hypit/media";
import type { FontStackRef } from "@hypit/media";
-import { mediaTrackTypes } from "@hypit/media-track";
+import { visualTrackTypes } from "@hypit/visual-track";
import type { TypeRef } from "@hypit/protocol";
import { spatialTypes } from "@hypit/spatial";
import { svsRecipeType } from "@hypit/svs";
-import { createTemporalInstantProjection, temporalInstantAttributeNames } from "@hypit/temporal-markup";
+import { createTemporalInstantConstruction, temporalInstantAttributeNames } from "@hypit/temporal-markup";
import type { SvsRecipe } from "@hypit/svs";
import { sealText, textTypes } from "@hypit/text";
import { sealGraphFragment } from "@hypit/elaborator";
@@ -181,15 +181,14 @@ export const decodeDepthStackLabelSurface: StructuredSurfaceHandler = ({ element
};
export const decodeDepthStackSurface: StructuredSurfaceHandler = ({ element, resolveReference }) => {
- allowed(element, ["id", "timeline", "canvas", "frame", "appearance", "until", "until-boundary"]);
+ allowed(element, ["id", "timeline", "frame", "appearance", "until"]);
const id = text(element, "id");
const context = resolveTemporalContext({ element, resolveReference });
- const canvas = reference(element.attributes.canvas, `${element.name}.canvas`, spatialTypes.canvas, resolveReference);
const frame = reference(element.attributes.frame, `${element.name}.frame`, spatialTypes.frame, resolveReference);
const appearance = recipe(element.attributes.appearance, `${element.name}.appearance`, resolveReference);
- const terminal = createTemporalInstantProjection({
+ const terminal = createTemporalInstantConstruction({
id: `${id}.terminal`, subjectId: id, element, ...context, resolveReference,
- semanticAttribute: "until", boundaryAttribute: "until-boundary", boundaryFallback: "end", projectedAttribute: false,
+ attribute: "until",
});
const records: SurfaceRecordDraft[] = [...terminal.records];
const temporalComponents: SurfaceComponentDraft[] = [...terminal.components];
@@ -201,7 +200,7 @@ export const decodeDepthStackSurface: StructuredSurfaceHandler = ({ element, res
{ id: specId, type: depthStackTypes.spec, value: { kind: "inline", value: decodeDepthStackSpec(appearance) }, range: element.range },
);
const inputs: Record<string, typeof context.timeline.ref> = {
- canvas: canvas.ref, frame: frame.ref, header: { kind: "record", id: headerId }, timeline: context.timeline.ref,
+ frame: frame.ref, header: { kind: "record", id: headerId }, timeline: context.timeline.ref,
spec: { kind: "record", id: specId }, terminal: terminal.ref,
};
const cards: DepthStackFragmentCard[] = [];
@@ -224,7 +223,7 @@ export const decodeDepthStackSurface: StructuredSurfaceHandler = ({ element, res
: reference(child.attributes.extent, `${child.name}.extent`, spatialTypes.extent, resolveReference);
if (sourceKind === "still" && extent === undefined) throw new Error(`${child.name}.extent is required for a still image.`);
if (sourceKind !== "still" && extent !== undefined) throw new Error(`${child.name}.extent belongs only to a still image.`);
- const activation = createTemporalInstantProjection({ id: `${id}.${cardId}`, subjectId: cardId, element: child, ...context, resolveReference });
+ const activation = createTemporalInstantConstruction({ id: `${id}.${cardId}`, subjectId: cardId, element: child, ...context, resolveReference });
records.push(...activation.records); temporalComponents.push(...activation.components); temporalFragments.push(...activation.fragments);
const cardAppearance = child.attributes.appearance === undefined
? appearance : recipe(child.attributes.appearance, `${child.name}.appearance`, resolveReference);
@@ -234,7 +233,7 @@ export const decodeDepthStackSurface: StructuredSurfaceHandler = ({ element, res
const cardSpecId = `${id}.card.${suffix}.card-spec`;
records.push(
{ id: fitId, type: spatialTypes.fit, value: { kind: "inline", value: material.fit }, range: child.range },
- { id: sampleId, type: mediaTrackTypes.sampleLayerSpec, value: { kind: "inline", value: material.sample }, range: child.range },
+ { id: sampleId, type: visualTrackTypes.sampleLayerSpec, value: { kind: "inline", value: material.sample }, range: child.range },
{ id: cardSpecId, type: depthStackTypes.cardSpec, value: { kind: "inline", value: decodeDepthStackCardSpec(cardAppearance, cardId) }, range: child.range },
);
const sourceName = `card-${suffix}-source`;
@@ -266,7 +265,7 @@ export const decodeDepthStackSurface: StructuredSurfaceHandler = ({ element, res
if (material.framePaint !== undefined) {
framePaintSpecName = `card-${suffix}-frame-paint`;
const paintId = `${id}.card.${suffix}.frame-paint`;
- records.push({ id: paintId, type: mediaTrackTypes.paintLayerSpec, value: { kind: "inline", value: material.framePaint }, range: child.range });
+ records.push({ id: paintId, type: visualTrackTypes.paintLayerSpec, value: { kind: "inline", value: material.framePaint }, range: child.range });
inputs[framePaintSpecName] = { kind: "record", id: paintId };
}
cards.push({
@@ -278,8 +277,8 @@ export const decodeDepthStackSurface: StructuredSurfaceHandler = ({ element, res
const fragment = createDepthStackFragment(cards, "terminal");
return {
records,
- components: [...temporalComponents, { id, fragment: fragment.id, inputs, outputs: { program: `${id}.program`, track: `${id}.track` }, range: element.range }],
+ components: [...temporalComponents, { id, fragment: fragment.id, inputs, outputs: { program: `${id}.program`, visual: `${id}.visual` }, range: element.range }],
fragments: [...temporalFragments, fragment],
- exports: [`${id}.program`, `${id}.track`],
+ exports: [`${id}.program`, `${id}.visual`],
};
};
diff --git a/packages/deck-track/src/types.ts b/packages/depth-stack/src/types.ts
similarity index 94%
rename from packages/deck-track/src/types.ts
rename to packages/depth-stack/src/types.ts
index f361de29..b04eb7c6 100644
--- a/packages/deck-track/src/types.ts
+++ b/packages/depth-stack/src/types.ts
@@ -6,10 +6,9 @@ import type {
VisualTextTypography,
} from "@hypit/composition";
import type {
- MediaFramePresentation,
+ VisualFrameTreatment,
MediaLayerSet,
- MediaLifecycleMotion,
-} from "@hypit/media-track";
+} from "@hypit/visual-track";
import type { SpatialFrame } from "@hypit/spatial";
export type DepthStackVisibility = {
@@ -60,8 +59,7 @@ export type DepthStackSpec = {
readonly visibility: DepthStackVisibility;
readonly poses: DepthStackPoseModel;
readonly reflow: DepthStackReflow;
- readonly presentation: MediaFramePresentation;
- readonly motion: MediaLifecycleMotion;
+ readonly treatment: VisualFrameTreatment;
readonly stackingOrder: number;
};
diff --git a/packages/deck-track/test/deck-track.test.ts b/packages/depth-stack/test/depth-stack.test.ts
similarity index 81%
rename from packages/deck-track/test/deck-track.test.ts
rename to packages/depth-stack/test/depth-stack.test.ts
index 0945bdd1..98cb460e 100644
--- a/packages/deck-track/test/deck-track.test.ts
+++ b/packages/depth-stack/test/depth-stack.test.ts
@@ -1,4 +1,4 @@
-import { sealTimeline } from "@hypit/timeline";
+import { sealTimeline, timelineTypes } from "@hypit/timeline";
import assert from "node:assert/strict";
import test from "node:test";
import { videoContractManifests } from "../../../test/support/video-domain.js";
@@ -6,7 +6,7 @@ import { fixtureResource } from "../../../test/fixture-resource.js";
import { timelineFixture } from "../../../test/timeline-fixture.js";
import { compositionDependency, compositionTypes } from "@hypit/composition";
-import type { VisualElement, VisualTimedSampling } from "@hypit/composition";
+import type { VisualElement, VisualSourceTimeMap } from "@hypit/composition";
import { createResolvedClosure } from "@hypit/core";
import {
decodeDepthStackLabelSurface,
@@ -27,23 +27,20 @@ import {
sealDepthStackCardSpec,
sealDepthStackHeader,
sealDepthStackSpec,
-} from "@hypit/deck-track";
+} from "@hypit/depth-stack";
import type {
DepthStackCardLabel,
DepthStackProgram,
DepthStackSpec,
-} from "@hypit/deck-track";
+} from "@hypit/depth-stack";
import type { FontArtifactRef } from "@hypit/media";
import { mediaTypes } from "@hypit/media";
import { mediaPipelineManifest } from "@hypit/media-pipeline";
-import type { MediaLayerSet } from "@hypit/media-track";
-import { narrativeTypes } from "@hypit/narrative";
-import { sealProgramSpace } from "@hypit/program-space";
+import type { MediaLayerSet } from "@hypit/visual-track";
import type { ModuleManifest } from "@hypit/protocol";
-import { timelineTypes } from "@hypit/timeline";
import { temporalTypes } from "@hypit/temporal";
import type { TemporalInstant } from "@hypit/temporal";
-import { sealCanvasSpace, sealSpatialFrame, spatialTypes } from "@hypit/spatial";
+import { canvasFrame, sealCanvas, sealSpatialFrame, spatialTypes } from "@hypit/spatial";
import { svsRecipeType } from "@hypit/svs";
import { sealText, textManifest, textTypes } from "@hypit/text";
import type { SvsRecipe } from "@hypit/svs";
@@ -54,20 +51,16 @@ import type {
MarkupAttributeValue,
} from "@hypit/markup";
import { artifactTypes } from "@hypit/artifact";
-import { mediaTrackManifest, mediaTrackTypes } from "@hypit/media-track";
+import { visualTrackManifest, visualTrackTypes } from "@hypit/visual-track";
-const space = sealTimeline({ items: [], id: "test-space", durationSec: 2,
- frameRate: { numerator: 30, denominator: 1 },
+const space = sealTimeline({ id: "test-space", frameCount: 60, frameRate: { numerator: 30, denominator: 1 },
});
const semantic = timelineFixture(space);
-const canvas = sealCanvasSpace({
+const canvas = sealCanvas({
widthPx: 360,
heightPx: 640,
- origin: "top-left",
- xDirection: "right",
- yDirection: "down",
- pixelAspect: "square",
});
+const within = canvasFrame(canvas);
const frame = sealSpatialFrame({
xPx: 60,
yPx: 220,
@@ -97,8 +90,8 @@ test("DepthStack Surface declares every sealed Record it may emit", () => {
depthStackTypes.spec,
depthStackTypes.cardSpec,
spatialTypes.fit,
- mediaTrackTypes.sampleLayerSpec,
- mediaTrackTypes.paintLayerSpec,
+ visualTrackTypes.sampleLayerSpec,
+ visualTrackTypes.paintLayerSpec,
depthStackTypes.cardLabel,
depthStackTypes.cardLabelStyle,
textTypes.text,
@@ -121,19 +114,19 @@ function stillMaterial(name: string): MediaLayerSet {
artifact: image(name),
extent: { widthPx: 120, heightPx: 90 },
},
- fit: {
+ placement: { kind: "fit", fit: {
sizing: "cover",
framePoint: { x: 0.5, y: 0.5 },
contentPoint: { x: 0.5, y: 0.5 },
offsetPx: { x: 0, y: 0 },
constraint: "bounded",
- },
+ } },
appearance: { opacity: 1, filter: { blurPx: 0, brightness: 1, contrast: 1, saturation: 1 } },
}],
};
}
-function timedMaterial(name: string, occupancy: "loop" | "hold" = "loop"): MediaLayerSet {
+function timedMaterial(name: string): MediaLayerSet {
return {
layers: [{
@@ -146,14 +139,21 @@ function timedMaterial(name: string, occupancy: "loop" | "hold" = "loop"): Media
frameRate: { numerator: 30, denominator: 1 },
frameCount: 12,
},
- fit: {
+ placement: { kind: "fit", fit: {
sizing: "contain",
framePoint: { x: 0.5, y: 0.5 },
contentPoint: { x: 0.5, y: 0.5 },
offsetPx: { x: 0, y: 0 },
constraint: "bounded",
- },
- occupancy: { mode: occupancy, align: "start" },
+ } },
+ sourceTime: { kind: "spec", value: { relations: [{
+ kind: "rate",
+ target: { from: { edge: "start", offsetFrames: 0 }, until: { edge: "end", offsetFrames: 0 } },
+ targetAt: { edge: "start", offsetFrames: 0 },
+ sourceAt: { edge: "start", offsetFrames: 0 },
+ rate: { numerator: 1, denominator: 1 },
+ source: { from: { edge: "start", offsetFrames: 0 }, until: { edge: "end", offsetFrames: 0 } },
+ }] } },
appearance: { opacity: 1, filter: { blurPx: 0, brightness: 1, contrast: 1, saturation: 1 } },
}],
};
@@ -180,17 +180,12 @@ function baseSpec(input: Partial<DepthStackSpec> = {}): DepthStackSpec {
},
},
reflow: { durationFrames: 4, easing: "ease-in-out" },
- presentation: {
+ treatment: {
clip: { kind: "rounded", radiusPx: 18 },
padding: { topPx: 8, rightPx: 8, bottomPx: 8, leftPx: 8 },
border: { widthPx: 2, style: "solid", color: "#ffffff" },
shadows: [{ offsetX: 0, offsetY: 6, blurPx: 14, spreadPx: 0, color: "#00000088" }],
},
- motion: {
- enter: { operator: "fade", durationFrames: 2, easing: "linear" },
- sustain: [{ operator: "float", amount: 2, cycles: 1 }],
- exit: { operator: "fade", durationFrames: 2, easing: "linear" },
- },
stackingOrder: 30,
...input,
});
@@ -206,23 +201,19 @@ function cardSpec(id: string, past: "hold-tail" | "continue" | "hide" = "hold-ta
function momentPoint(id: string, frameValue: number): TemporalInstant {
return {
- id: `${id}::moment`,
+ id: `${id}.moment`,
subjectId: id,
- source: { spaceId: space.id, narrativeId: "script", kind: "moment", id },
- projection: { ref: "moment.cue" },
+ timelineId: space.id,
frame: frameValue,
- authority: { kind: "fixed" },
};
}
function programPoint(subjectId: string, endFrame: number): TemporalInstant {
return {
- id: "program::program",
+ id: "timeline.end",
subjectId,
- source: { spaceId: space.id, narrativeId: "script", kind: "program", id: "program" },
- projection: { ref: "program.end" },
+ timelineId: space.id,
frame: endFrame,
- authority: { kind: "fixed" },
};
}
@@ -307,7 +298,7 @@ test("relative-depth pose resolves offsets, multiplicative tone and alternating
});
test("collection reflow moves the complete old/new union while cut replaces it exactly", () => {
- const animated = renderDepthStack(canvas, space, program());
+ const animated = renderDepthStack(space, program());
const stageTwo = animated.presents.filter((present) => present.span.startFrame === 20);
assert.deepEqual(stageTwo.map((present) => present.id).sort(), [
"card-1:stage:2", "card-2:stage:2", "card-3:stage:2",
@@ -315,10 +306,9 @@ test("collection reflow moves the complete old/new union while cut replaces it e
for (const present of stageTwo) {
const pose = present.elements.find((value) => value.id === "deck-pose");
assert.deepEqual(pose?.animation?.keyframes.map((value) => value.atFrame), [0, 4, 20]);
- assert.ok(present.elements.some((value) => value.id === "deck-lifecycle"));
- assert.ok(present.elements.some((value) => value.id === "deck-sustain-1"));
+ assert.ok(present.elements.some((value) => value.id === "deck-placement"));
}
- const cut = renderDepthStack(canvas, space, program({
+ const cut = renderDepthStack(space, program({
spec: baseSpec({ reflow: { durationFrames: 0, easing: "linear" } }),
}));
assert.equal(cut.presents.filter((present) => present.span.startFrame === 20).length, 3);
@@ -330,21 +320,23 @@ test("timed Cards hold future head/current clock/past tail without renderer play
const value = program({
materials: [stillMaterial("one"), timedMaterial("two"), stillMaterial("three")],
});
- const track = renderDepthStack(canvas, space, value);
+ const track = renderDepthStack(space, value);
const future = element(track, "card-2:stage:1", (value) => value.kind === "video");
const current = element(track, "card-2:stage:2", (value) => value.kind === "video");
const past = element(track, "card-2:stage:3", (value) => value.kind === "video");
assert.equal(future.kind, "video");
assert.equal(current.kind, "video");
assert.equal(past.kind, "video");
- assert.equal((future.sampling as VisualTimedSampling).segments[0]?.rate.numerator, 0);
- assert.deepEqual((current.sampling as VisualTimedSampling).segments[0]?.loop, { startFrame: 0, endFrameExclusive: 12 });
- assert.equal((past.sampling as VisualTimedSampling).segments[0]?.sourceFrame.numerator, 11);
- assert.equal((past.sampling as VisualTimedSampling).segments[0]?.rate.numerator, 0);
+ assert.equal((future.sourceTime as VisualSourceTimeMap).pieces[0]?.rate.numerator, 0);
+ assert.deepEqual((current.sourceTime as VisualSourceTimeMap).pieces[0]?.target,
+ { startFrame: 0, endFrameExclusive: 12 });
+ assert.equal((current.sourceTime as VisualSourceTimeMap).pieces[0]?.wrap, undefined);
+ assert.equal((past.sourceTime as VisualSourceTimeMap).pieces[0]?.sourceAtStart.numerator, 11);
+ assert.equal((past.sourceTime as VisualSourceTimeMap).pieces[0]?.rate.numerator, 0);
});
-test("continue uses one explicit loop-start clock and past hide removes the retained state", () => {
- const continued = renderDepthStack(canvas, space, program({
+test("continue derives one explicit periodic clock and past hide removes the retained state", () => {
+ const continued = renderDepthStack(space, program({
materials: [timedMaterial("one"), timedMaterial("two"), stillMaterial("three")],
playbacks: [cardSpec("card-1", "continue"), cardSpec("card-2", "hold-tail", "continue"), cardSpec("card-3")],
}));
@@ -352,14 +344,17 @@ test("continue uses one explicit loop-start clock and past hide removes the reta
const past = element(continued, "card-1:stage:2", (value) => value.kind === "video");
assert.equal(future.kind, "video");
assert.equal(past.kind, "video");
- assert(future.sampling !== undefined);
- assert(past.sampling !== undefined);
- assert.deepEqual(future.sampling.segments[0]?.loop, { startFrame: 0, endFrameExclusive: 12 });
- assert.deepEqual(past.sampling.segments[0]?.loop, { startFrame: 0, endFrameExclusive: 12 });
- assert.throws(() => renderDepthStack(canvas, space, program({
- materials: [timedMaterial("one", "hold"), stillMaterial("two"), stillMaterial("three")],
+ assert(future.sourceTime !== undefined);
+ assert(past.sourceTime !== undefined);
+ assert.deepEqual(future.sourceTime.pieces[0]?.wrap, { startFrame: 0, endFrameExclusive: 12 });
+ assert.deepEqual(past.sourceTime.pieces[0]?.wrap, { startFrame: 0, endFrameExclusive: 12 });
+ const derived = renderDepthStack(space, program({
+ materials: [timedMaterial("one"), stillMaterial("two"), stillMaterial("three")],
playbacks: [cardSpec("card-1", "continue"), cardSpec("card-2"), cardSpec("card-3")],
- })), /continue playback requires loop-start/u);
+ }));
+ const derivedPast = element(derived, "card-1:stage:2", (value) => value.kind === "video");
+ assert.deepEqual(derivedPast.kind === "video" ? derivedPast.sourceTime.pieces[0]?.wrap : undefined,
+ { startFrame: 0, endFrameExclusive: 12 });
const hidden = program({ playbacks: [cardSpec("card-1", "hide"), cardSpec("card-2"), cardSpec("card-3")] });
assert.equal(resolveDepthStackState(hidden, 1).has(0), false);
});
@@ -393,7 +388,7 @@ function exactLabel(): DepthStackCardLabel {
}
test("optional labels preserve exact fonts and remain inside the Card-owned pose", () => {
- const track = renderDepthStack(canvas, space, program({ labels: [exactLabel(), noDepthStackCardLabel(), noDepthStackCardLabel()] }));
+ const track = renderDepthStack(space, program({ labels: [exactLabel(), noDepthStackCardLabel(), noDepthStackCardLabel()] }));
const label = element(track, "card-1:stage:1", (value) => value.kind === "text-flow");
assert.equal(label.kind, "text-flow");
assert.equal(label.parent, "deck-material:frame");
@@ -408,7 +403,7 @@ test("optional labels preserve exact fonts and remain inside the Card-owned pose
test("rendering is a pure absolute-frame result", () => {
const value = program({ labels: [exactLabel(), noDepthStackCardLabel(), noDepthStackCardLabel()] });
- assert.deepEqual(renderDepthStack(canvas, space, value), renderDepthStack(canvas, space, structuredClone(value)));
+ assert.deepEqual(renderDepthStack(space, value), renderDepthStack(space, structuredClone(value)));
});
test("the author Surface keeps every source, trigger, terminal, Frame and optional label as graph inputs", async () => {
@@ -421,18 +416,19 @@ test("the author Surface keeps every source, trigger, terminal, Frame and option
record: { value: { kind: "inline", value: { path, properties } } } as never,
});
const references = new Map<string, SurfaceResolvedReference>([
- ["semantic", plain("semantic", timelineTypes.track)],
- ["canvas", plain("canvas", spatialTypes.canvas)], ["frame", plain("frame", spatialTypes.frame)],
+ ["timeline", plain("timeline", timelineTypes.track)],
+ ["within", plain("within", spatialTypes.frame)],
+ ["frame", plain("frame", spatialTypes.frame)],
["first", plain("first", artifactTypes.blob)], ["first-extent", plain("first-extent", spatialTypes.extent)],
- ["second", plain("second", mediaTypes.synchronized)], ["one", plain("one", narrativeTypes.moment)],
- ["two", plain("two", narrativeTypes.moment)], ["terminal", plain("terminal", narrativeTypes.selection)],
+ ["second", plain("second", mediaTypes.synchronized)], ["one", plain("one", temporalTypes.instant)],
+ ["two", plain("two", temporalTypes.instant)], ["terminal", plain("terminal", temporalTypes.instant)],
["deck-style", appearance("deck-style", { "visible-previous": 1, "visible-next": 1, "reflow-frames": 4, fit: "cover", "stack-order": 30 })],
- ["video-style", appearance("video-style", { fit: "contain", playback: "loop-start", "playback-future": "continue" })],
+ ["video-style", appearance("video-style", { fit: "contain", "playback-future": "continue" })],
]);
const result = await decodeDepthStackSurface({
sourceName: "deck.svml",
element: node("deck:DepthStack", {
- id: "proof", timeline: ref("semantic"), canvas: ref("canvas"), frame: ref("frame"),
+ id: "proof", timeline: ref("timeline"), frame: ref("frame"),
appearance: ref("deck-style"), until: ref("terminal"),
}, [
node("deck:Card", { id: "one", source: ref("first"), extent: ref("first-extent"), at: ref("one") }),
@@ -441,26 +437,20 @@ test("the author Surface keeps every source, trigger, terminal, Frame and option
resolveReference: (path) => references.get(path),
resolveAsset: async () => { throw new Error("no asset resolution expected"); },
});
- const component = result.components.find((candidate) => candidate.outputs.track !== undefined);
+ const component = result.components.find((candidate) => candidate.outputs.visual !== undefined);
assert.ok(component !== undefined);
- assert.deepEqual(Object.keys(component.outputs).sort(), ["program", "track"]);
- const fragment = result.fragments.find((candidate) => candidate.exports.some((output) => output.name === "track"))!;
+ assert.deepEqual(Object.keys(component.outputs).sort(), ["program", "visual"]);
+ const fragment = result.fragments.find((candidate) => candidate.exports.some((output) => output.name === "visual"))!;
assert.ok(fragment.operations.some((operation) => operation.producer.name === "append-still-media-layer"));
assert.ok(fragment.operations.some((operation) => operation.producer.name === "append-timed-media-layer"));
assert.ok(fragment.operations.some((operation) => operation.producer.name === "append-depth-stack-card"));
assert.ok(fragment.operations.some((operation) => operation.producer.name === "finalize-depth-stack"));
- assert.ok(result.fragments.some((candidate) => candidate.operations.some((operation) =>
- operation.producer.name === "project-selection-instant")));
- const temporalSubjects = new Set(result.records.flatMap((record) =>
- record.value.kind === "inline"
- && typeof record.value.value === "object"
- && record.value.value !== null
- && "subjectId" in record.value.value
- ? [String((record.value.value as { readonly subjectId: unknown }).subjectId)]
- : []));
- assert.deepEqual([...temporalSubjects].sort(), ["one", "proof", "two"]);
+ assert.equal(result.fragments.some((candidate) => candidate.operations.some((operation) =>
+ operation.producer.module.name === "@hypit/narrative-temporal")), false);
assert.ok(fragment.inputs.some((input) => input.name === "frame"));
+ assert.equal(fragment.inputs.some((input) => input.name === "within"), false);
assert.ok(fragment.inputs.some((input) => input.name === "terminal"));
+ assert.equal(fragment.inputs.filter((input) => input.type.name === temporalTypes.instant.name).length, 3);
});
test("Label Surface compiles explicit exact-font text rather than media metadata", async () => {
@@ -525,17 +515,17 @@ test("another Deck family can coexist by contributing only the existing VisualTr
const closure = createResolvedClosure([
...videoContractManifests,
mediaPipelineManifest,
- mediaTrackManifest,
+ visualTrackManifest,
textManifest,
depthStackManifest,
other,
]);
- assert.ok(closure.modules.some((module) => module.manifest.name === "@hypit/deck-track"));
+ assert.ok(closure.modules.some((module) => module.manifest.name === "@hypit/depth-stack"));
assert.ok(closure.modules.some((module) => module.manifest.name === "example.carousel"));
assert.deepEqual(other.producers[0]?.outputs[0]?.type, compositionTypes.visualTrack);
});
-test("SVS decoding exposes all documented depth, frame, motion and playback axes", () => {
+test("SVS decoding exposes documented depth, frame treatment and playback axes", () => {
const value = decodeDepthStackSpec({
path: "recipes.deck.proof",
@@ -544,13 +534,12 @@ test("SVS decoding exposes all documented depth, frame, motion and playback axes
"previous-y-step": 24, "previous-scale-step": 0.93, "previous-rotation-mode": "alternate",
"next-y-step": -18, "next-opacity-step": 0.7, "reflow-frames": 6, "reflow-easing": "ease-out",
clip: "rounded", radius: 16, padding: "8 12", "border-width": 2, "border-color": "#ffffff",
- enter: "fade", "enter-frames": 3, exit: "fade", "exit-frames": 3, "stack-order": 44,
+ "stack-order": 44,
},
});
assert.deepEqual(value.visibility, { previous: 3, next: 2, wrap: false });
assert.equal(value.poses.previous.yPerDepthPx, 24);
assert.equal(value.reflow.durationFrames, 6);
- assert.equal(value.presentation.clip.kind, "rounded");
- assert.equal(value.motion.enter?.durationFrames, 3);
+ assert.equal(value.treatment.clip.kind, "rounded");
assert.equal(value.stackingOrder, 44);
});
diff --git a/packages/elaborator/test/fragment.test.ts b/packages/elaborator/test/fragment.test.ts
index 62915d2e..29ce9b51 100644
--- a/packages/elaborator/test/fragment.test.ts
+++ b/packages/elaborator/test/fragment.test.ts
@@ -1,5 +1,5 @@
import { videoContractManifests } from "../../../test/support/video-domain.js";
-import { speechDependency, speechTypes } from "@hypit/speech";
+import { narrativeTemporalDependency, narrativeTemporalTypes } from "@hypit/narrative-temporal";
import { compositionDependency, compositionTypes } from "@hypit/composition";
import { spatialTypes } from "@hypit/spatial";
import assert from "node:assert/strict";
@@ -41,7 +41,7 @@ const manifest: ModuleManifest = {
format: "hypit.module@1",
name: testModule.name,
version: testModule.version,
- dependencies: [speechDependency, compositionDependency],
+ dependencies: [narrativeTemporalDependency, compositionDependency],
types: [{ name: requestType.name }],
capabilities: [],
producers: [{
@@ -50,16 +50,16 @@ const manifest: ModuleManifest = {
{ name: "request", type: requestType },
{ name: "style", type: requestType },
],
- outputs: [{ name: "take", type: speechTypes.semanticTake }],
+ outputs: [{ name: "take", type: narrativeTemporalTypes.narrativeAlignment }],
needs: [],
}, {
name: projectVisualProducer.name,
- inputs: [{ name: "take", type: speechTypes.semanticTake }],
+ inputs: [{ name: "take", type: narrativeTemporalTypes.narrativeAlignment }],
outputs: [{ name: "visual", type: compositionTypes.visualTrack }],
needs: [],
}, {
name: projectAudioProducer.name,
- inputs: [{ name: "take", type: speechTypes.semanticTake }],
+ inputs: [{ name: "take", type: narrativeTemporalTypes.narrativeAlignment }],
outputs: [{ name: "audio", type: compositionTypes.audioTrack }],
needs: [],
}],
@@ -73,7 +73,6 @@ function program(): LinkedProgram {
type: spatialTypes.canvas,
value: { kind: "inline", value: {
widthPx: 1080, heightPx: 1920,
- origin: "top-left", xDirection: "right", yDirection: "down", pixelAspect: "square",
} },
});
const canvas = rawCanvas;
@@ -124,7 +123,7 @@ function speechFragment(): GraphFragment {
exports: [
{
name: "take",
- type: speechTypes.semanticTake,
+ type: narrativeTemporalTypes.narrativeAlignment,
root: operation("generate"),
},
{
diff --git a/packages/estimate/src/manifest.ts b/packages/estimate/src/manifest.ts
index 814e9122..ac9b60c8 100644
--- a/packages/estimate/src/manifest.ts
+++ b/packages/estimate/src/manifest.ts
@@ -3,7 +3,7 @@ import type { ModuleManifest, TypeRef, ValueSchema } from "@hypit/protocol";
export const estimateModuleRef = { name: "@hypit/estimate", version: "1" } as const;
/**
- * The one graph value this package still declares: the delivery policy an estimated SemanticTake
+ * The one graph value this package still declares: the delivery policy an estimated speech result
* weights its Tokens with. Durations themselves are author literals; measuring a script happens at
* creation time with `hypit measure`, never inside a Build.
*/
diff --git a/packages/film-studio/package.json b/packages/film-studio/package.json
index 8a059a1c..914aabf9 100644
--- a/packages/film-studio/package.json
+++ b/packages/film-studio/package.json
@@ -4,13 +4,16 @@
"license": "SEE LICENSE IN LICENSE",
"private": true,
"type": "module",
- "exports": { ".": "./src/index.ts" },
- "hypit": { "activation": "./src/activation.ts" },
+ "exports": {
+ ".": "./src/index.ts"
+ },
+ "hypit": {
+ "activation": "./src/activation.ts"
+ },
"dependencies": {
"@hypit/composition": "workspace:*",
"@hypit/film": "workspace:*",
"@hypit/timeline": "workspace:*",
- "@hypit/studio-adapter": "workspace:*",
- "@hypit/program-space": "workspace:*"
+ "@hypit/studio-adapter": "workspace:*"
}
}
diff --git a/packages/film-studio/src/index.ts b/packages/film-studio/src/index.ts
index f14f7cd6..9ebda4b1 100644
--- a/packages/film-studio/src/index.ts
+++ b/packages/film-studio/src/index.ts
@@ -1,8 +1,7 @@
-import { programSpaceTypes } from "@hypit/program-space";
+import { timelineTypes } from "@hypit/timeline";
import type { StudioFilmCompanion } from "@hypit/studio-adapter";
import { compositionTypes } from "@hypit/composition";
import { filmModuleRef } from "@hypit/film";
-import { timelineTypes } from "@hypit/timeline";
/** Film owns the author vocabulary that selects its time source and peer Tracks. */
export const filmStudioCompanions: readonly StudioFilmCompanion[] = [{
diff --git a/packages/film/README.md b/packages/film/README.md
index c9a66bb5..9d613022 100644
--- a/packages/film/README.md
+++ b/packages/film/README.md
@@ -16,12 +16,12 @@ port list and one atomic result.
receives the previous set and newly added Track through explicit graph edges. The domain value copies
no lineage metadata. Final Composition
remains order-independent because the public contract canonicalizes Tracks and visual ordering
-belongs to each Present's absolute stacking key.
+belongs to each Present's absolute `z`, Track-local `order` and stable identity fallback.
The official Structured Surface validates an imported generic SVS Recipe into a nominal
-`FilmProgram`, receives CanvasSpace and the selected time source through separate explicit edges,
+`FilmProgram`, receives Canvas and the selected time source through separate explicit edges,
passes the Timeline directly, type-checks
-each `<film:Track source={...}/>` reference and generates the finite fold. CanvasSpace is the only
+each `<film:Track source={...}/>` reference and generates the finite fold. Canvas is the only
dimension truth, Timeline is the only time-range truth, and FilmProgram owns only assembly
identity and clear color.
Child order is organizational: Track and Present identity, timing and absolute stacking remain in
@@ -30,24 +30,19 @@ their own typed values. Final rendering is a separate author package and capabil
For example, after the named inputs are declared:
```svml
-<import as="sound" from="@hypit/sound@1"/>
-<sound:Style id="voice-style"/>
-<sound:Track id="voice" timeline={speech.timeline}>
- <sound:Use style={voice-style}/>
-</sound:Track>
-
-<film:Film id="main" canvas={vertical} timeline={speech.timeline}
+<film:Film id="main" canvas={vertical.canvas} timeline={speech.timeline}
appearance={recipes.film.vertical}>
- <film:Track source={performance.visual}/>
- <film:Track source={voice.audio}/>
+ <film:Track source={picture.visual}/>
+ <film:Track source={mix.audio}/>
<film:Track source={coverage.visual}/>
- <film:Track source={captions.track}/>
- <film:Track source={music.track}/>
+ <film:Track source={captions.visual}/>
+ <film:Track source={music.audio}/>
</film:Film>
```
-The public output is `main.composition`. Including a visual output does not automatically include
-its sibling audio output. An opaque upper layer can cover a performance while its audio continues;
+The public output is `main.composition`. Including a Visual Track output does not automatically include
+an Audio Track output derived from the same media. An opaque upper layer can cover a performance while
+its separately included audio continues;
reordering these children is not how an author changes that visual stacking.
The `appearance` Recipe uses `background`, for example `film.vertical { background: #18212A; }`.
diff --git a/packages/film/package.json b/packages/film/package.json
index 94b4f8dc..e4149ece 100644
--- a/packages/film/package.json
+++ b/packages/film/package.json
@@ -14,7 +14,6 @@
"@hypit/component-kit": "workspace:*",
"@hypit/composition": "workspace:*",
"@hypit/elaborator": "workspace:*",
- "@hypit/program-space": "workspace:*",
"@hypit/protocol": "workspace:*",
"@hypit/timeline": "workspace:*",
"@hypit/spatial": "workspace:*",
@@ -28,7 +27,7 @@
"@hypit/hyperframes": "workspace:*",
"@hypit/media": "workspace:*",
"@hypit/text": "workspace:*",
- "@hypit/typography-track": "workspace:*",
+ "@hypit/text-fine": "workspace:*",
"@hypit/validation": "workspace:*"
}
}
diff --git a/packages/film/src/component.ts b/packages/film/src/component.ts
index d6b41c46..939393fc 100644
--- a/packages/film/src/component.ts
+++ b/packages/film/src/component.ts
@@ -1,6 +1,6 @@
import type { Timeline } from "@hypit/timeline";
import type { ComponentPackage } from "@hypit/component-kit";
-import type { CanvasSpace } from "@hypit/spatial";
+import type { Canvas } from "@hypit/spatial";
import type { AudioTrack, VisualTrack } from "@hypit/composition";
import type { StoredValue } from "@hypit/protocol";
import { canonicalize } from "@hypit/protocol";
@@ -50,7 +50,7 @@ export const filmComponent = {
handler: ({ inputs }) => ({
outputs: { composition: { kind: "inline", value: canonicalize(compileFilmComposition(
inline<FilmProgram>(inputs.program?.value, "FilmProgram"),
- inline<CanvasSpace>(inputs.canvas?.value, "CanvasSpace"),
+ inline<Canvas>(inputs.canvas?.value, "Canvas"),
inline<Timeline>(inputs.timeline?.value, "Timeline"),
inline<FilmTrackSet>(inputs.set?.value, "FilmTrackSet"),
)) } },
diff --git a/packages/film/src/manifest.ts b/packages/film/src/manifest.ts
index e163450a..c4257456 100644
--- a/packages/film/src/manifest.ts
+++ b/packages/film/src/manifest.ts
@@ -1,10 +1,9 @@
-import { timelineTypes } from "@hypit/timeline";
+import { timelineTypes, timelineDependency } from "@hypit/timeline";
import type { Timeline } from "@hypit/timeline";
import { temporalContextAttributeVocabulary } from "@hypit/temporal-markup";
import { audioTrackSchema, compositionDependency, compositionTypes, visualTrackSchema } from "@hypit/composition";
import type { ModuleManifest, ProducerRef, TypeRef, ValueSchema } from "@hypit/protocol";
-import { timelineDependency } from "@hypit/timeline";
import { spatialDependency, spatialTypes } from "@hypit/spatial";
import { svsManifest, svsModuleRef, svsRecipeType } from "@hypit/svs";
@@ -57,7 +56,7 @@ export const filmMarkupSurfaces = [{
summary: "Names the Film component and the Composition binding it publishes." },
{ name: "canvas", kind: "reference", required: true,
accepts: [spatialTypes.canvas],
- summary: "Selects the CanvasSpace that decides the Composition's dimensions." },
+ summary: "Selects the Canvas that decides the Composition's dimensions." },
...temporalContextAttributeVocabulary,
{ name: "appearance", kind: "reference", required: true,
accepts: [svsRecipeType],
@@ -81,10 +80,10 @@ export const filmMarkupSurfaces = [{
summary: "The assembled Composition, addressed as `<id>.composition`." },
],
example: [
- '<film:Film id="main" canvas={vertical} timeline={speech.timeline} appearance={recipes.film.vertical}>',
+ '<film:Film id="main" canvas={vertical.canvas} timeline={speech.timeline} appearance={recipes.film.vertical}>',
" <film:Track source={performance.visual}/>",
" <film:Track source={voice.audio}/>",
- " <film:Track source={captions.track}/>",
+ " <film:Track source={captions.visual}/>",
"</film:Film>",
].join("\n"),
notes: [
diff --git a/packages/film/src/program.ts b/packages/film/src/program.ts
index 148ecc3b..ef836bee 100644
--- a/packages/film/src/program.ts
+++ b/packages/film/src/program.ts
@@ -1,7 +1,7 @@
+import { assertTimelineIdentity } from "@hypit/timeline";
import type { Timeline } from "@hypit/timeline";
-import { assertProgramSpaceIdentity } from "@hypit/program-space";
-import { assertCanvasSpace } from "@hypit/spatial";
-import type { CanvasSpace } from "@hypit/spatial";
+import { assertCanvas } from "@hypit/spatial";
+import type { Canvas } from "@hypit/spatial";
import { assertAudioTrackIdentity, assertCompositionIdentity, assertVisualTrackIdentity, sealComposition } from "@hypit/composition";
import type { AudioTrack, Composition, Track, VisualTrack } from "@hypit/composition";
@@ -64,11 +64,11 @@ export function createFilmTrackSet(): FilmTrackSet {
});
}
-function appendTrack(set: FilmTrackSet, programSpace: Timeline, track: Track): FilmTrackSet {
+function appendTrack(set: FilmTrackSet, timeline: Timeline, track: Track): FilmTrackSet {
assertFilmTrackSetIdentity(set);
- assertProgramSpaceIdentity(programSpace);
- if (track.kind === "visual") assertVisualTrackIdentity(track, programSpace);
- else assertAudioTrackIdentity(track, programSpace);
+ assertTimelineIdentity(timeline);
+ if (track.kind === "visual") assertVisualTrackIdentity(track, timeline);
+ else assertAudioTrackIdentity(track, timeline);
if (set.tracks.some((existing) => existing.id === track.id)) {
throw new Error(`FilmTrackSet already contains Track id ${track.id}.`);
}
@@ -78,23 +78,23 @@ function appendTrack(set: FilmTrackSet, programSpace: Timeline, track: Track): F
});
}
-export function appendFilmVisualTrack(set: FilmTrackSet, programSpace: Timeline, track: VisualTrack): FilmTrackSet {
- return appendTrack(set, programSpace, track);
+export function appendFilmVisualTrack(set: FilmTrackSet, timeline: Timeline, track: VisualTrack): FilmTrackSet {
+ return appendTrack(set, timeline, track);
}
-export function appendFilmAudioTrack(set: FilmTrackSet, programSpace: Timeline, track: AudioTrack): FilmTrackSet {
- return appendTrack(set, programSpace, track);
+export function appendFilmAudioTrack(set: FilmTrackSet, timeline: Timeline, track: AudioTrack): FilmTrackSet {
+ return appendTrack(set, timeline, track);
}
export function compileFilmComposition(
program: FilmProgram,
- canvas: CanvasSpace,
- programSpace: Timeline,
+ canvas: Canvas,
+ timeline: Timeline,
set: FilmTrackSet,
): Composition {
assertFilmProgramIdentity(program);
- assertCanvasSpace(canvas);
- assertProgramSpaceIdentity(programSpace);
+ assertCanvas(canvas);
+ assertTimelineIdentity(timeline);
assertFilmTrackSetIdentity(set);
const composition = sealComposition({
id: program.id,
@@ -105,6 +105,6 @@ export function compileFilmComposition(
},
tracks: set.tracks,
});
- assertCompositionIdentity(composition, programSpace);
+ assertCompositionIdentity(composition, timeline);
return composition;
}
diff --git a/packages/film/src/surface.ts b/packages/film/src/surface.ts
index 2d548dc8..7ec715d3 100644
--- a/packages/film/src/surface.ts
+++ b/packages/film/src/surface.ts
@@ -97,7 +97,7 @@ export const decodeFilmSurface: StructuredSurfaceHandler = ({ element, resolveRe
const id = stringAttribute(element, "id");
const canvas = requiredReference(element, "canvas", resolveReference);
if (!sameType(canvas.type, spatialTypes.canvas)) {
- throw new Error(`${element.name}.canvas must reference CanvasSpace`);
+ throw new Error(`${element.name}.canvas must reference Canvas`);
}
const context = resolveTemporalContext({ element, resolveReference });
const appearanceReference = requiredReference(element, "appearance", resolveReference);
diff --git a/packages/film/test/film.test.ts b/packages/film/test/film.test.ts
index 0764e3b5..681c944d 100644
--- a/packages/film/test/film.test.ts
+++ b/packages/film/test/film.test.ts
@@ -1,13 +1,11 @@
-import { sealTimeline } from "@hypit/timeline";
+import { sealTimeline, timelineTypes } from "@hypit/timeline";
+import type { Timeline } from "@hypit/timeline";
import { compositionComponent, spatialComponent, videoContractManifests } from "../../../test/support/video-domain.js";
import { registerTypeValidatorFacets } from "@hypit/component-kit";
-import { programSpaceTypes, sealProgramSpace } from "@hypit/program-space";
-import { projectTimelineSpace, timelineProducers, timelineTypes } from "@hypit/timeline";
-import type { Timeline } from "@hypit/timeline";
import { compositionTypes, sealAudioTrack, sealVisualTrack } from "@hypit/composition";
import type { Composition, Track } from "@hypit/composition";
import type { FontArtifactRef } from "@hypit/media";
-import { sealCanvasSpace, spatialTypes } from "@hypit/spatial";
+import { sealCanvas, spatialTypes } from "@hypit/spatial";
import assert from "node:assert/strict";
import test from "node:test";
import { fixtureResource } from "../../../test/fixture-resource.js";
@@ -30,13 +28,11 @@ import {
import { appendFilmAudioTrack, appendFilmVisualTrack, compileFilmComposition, createFilmAssemblyFragment, createFilmTrackSet, filmManifest, filmProducers, filmTypes, sealFilmProgram } from "@hypit/film";
import { compileHyperframesDocument, hyperframesDocumentFragment, hyperframesManifest, hyperframesProducers, hyperframesTypes } from "@hypit/hyperframes";
import type { CanonicalValue, CompiledGraph, StoredValue, TypedRecord } from "@hypit/protocol";
-import { textManifest } from "@hypit/text";
-import { renderTypographyTrack, sealTypographyTrackProgram, stillTextMotion, typographyTrackFragment, typographyTrackManifest, typographyTrackProducers, typographyTrackTypes } from "@hypit/typography-track";
-import type { TextStyle } from "@hypit/typography-track";
+import { renderFineTextOccurrence, stillTextMotion } from "@hypit/text-fine";
+import type { TextStyle } from "@hypit/text-fine";
import { admitRecord, TypeValidatorRegistry } from "@hypit/validation";
-const space = sealTimeline({ items: [], id: "test-space", durationSec: 4,
- frameRate: { numerator: 30, denominator: 1 },
+const space = sealTimeline({ id: "test-space", frameCount: 120, frameRate: { numerator: 30, denominator: 1 },
});
const semantic = timelineFixture(space);
@@ -46,13 +42,9 @@ function validatorRegistry(): TypeValidatorRegistry {
registerTypeValidatorFacets(registry, spatialComponent.validators);
return registry;
}
-const canvas = sealCanvasSpace({
+const canvas = sealCanvas({
widthPx: 1080,
heightPx: 1920,
- origin: "top-left",
- xDirection: "right",
- yDirection: "down",
- pixelAspect: "square",
});
const filmProgram = sealFilmProgram({
@@ -69,7 +61,6 @@ const titleFont: FontArtifactRef = {
const titleStyle: TextStyle = {
id: "title-style",
- stackingOrder: 60,
typography: {
fonts: [titleFont], sizePx: 56, weight: 800, style: "normal",
axes: [], features: [], synthesis: "none", kerning: "auto", trackingPx: 0,
@@ -79,39 +70,36 @@ const titleStyle: TextStyle = {
cjk: { textSpacing: "normal", punctuationTrim: "none" },
},
paints: [{ kind: "fill", paint: { kind: "solid", color: "#ffffff" } }],
- area: {
- inlineSize: "fixed", blockSize: "fixed",
- paddingPx: { inlineStart: 0, inlineEnd: 0, blockStart: 0, blockEnd: 0 },
- inlineAlign: "center", blockAlign: "center", wrap: "word", overflow: "visible",
- clipToFrame: false, columns: 1, columnGapPx: 0, metricEdge: "line-box",
- },
- point: { anchorInline: "center", anchorBlock: "center" },
- path: { side: "left", orientation: "follow", startMarginPx: 0, endMarginPx: 0, align: "start", reverse: false, overflow: "visible" },
};
-const textProgram = sealTypographyTrackProgram({
-
- id: "title-track",
- items: [{
+const titleVisual = renderFineTextOccurrence(space, {
+ timelineId: space.id,
id: "title",
span: { startFrame: 10, endFrameExclusive: 100 },
- tieBreak: "title",
- geometry: { kind: "area", frame: { xPx: 86.4, yPx: 192, widthPx: 907.2, heightPx: 384 } },
+ placement: {
+ kind: "flow", z: 60, frame: { xPx: 86.4, yPx: 192, widthPx: 907.2, heightPx: 384 },
+ flow: {
+ inlineSize: "fixed", blockSize: "fixed",
+ paddingPx: { inlineStart: 0, inlineEnd: 0, blockStart: 0, blockEnd: 0 },
+ inlineAlign: "center", blockAlign: "center", wrap: "word", overflow: "visible",
+ clipToFrame: false, columns: 1, columnGapPx: 0, metricEdge: "line-box",
+ },
+ },
document: { paragraphs: [{ id: "title", inlines: [{ kind: "text", id: "title-text", text: "Semantic Video Markup Language" }] }] },
style: titleStyle,
motion: stillTextMotion(),
- }],
});
-const background = sealVisualTrack({ programSpaceId: "test-space",
+const background = sealVisualTrack({ timelineId: "test-space",
visualIr: "hypit.visual-ir@1",
id: "background-track",
presents: [{
id: "background",
+ order: 0,
+ z: 0,
span: { startFrame: 0, endFrameExclusive: 120 },
- stacking: { order: 0, tieBreak: "background" },
elements: [{ id: "root", kind: "box", order: 0, style: [{ name: "background-color", value: "#223344" }] }],
}],
});
-const audio = sealAudioTrack({ programSpaceId: "test-space",
+const audio = sealAudioTrack({ timelineId: "test-space",
id: "empty-audio-track",
clips: [],
});
@@ -129,32 +117,19 @@ function stored(value: CanonicalValue): StoredValue {
const closure = createResolvedClosure([
...videoContractManifests,
hyperframesManifest,
- textManifest,
filmManifest,
- typographyTrackManifest,
]);
const records = await Promise.all([
- sealRecord({ id: "render-space", type: programSpaceTypes.programSpace, value: stored(projectTimelineSpace(space)) }),
sealRecord({ id: "timeline", type: timelineTypes.track, value: stored(space) }),
sealRecord({ id: "semantic", type: timelineTypes.track, value: stored(semantic) }),
sealRecord({ id: "canvas", type: spatialTypes.canvas, value: stored(canvas) }),
sealRecord({ id: "film-program", type: filmTypes.program, value: stored(filmProgram) }),
- sealRecord({ id: "text-program", type: typographyTrackTypes.program, value: stored(textProgram) }),
+ sealRecord({ id: "title", type: compositionTypes.visualTrack, value: stored(titleVisual) }),
sealRecord({ id: "background", type: compositionTypes.visualTrack, value: stored(background) }),
sealRecord({ id: "audio", type: compositionTypes.audioTrack, value: stored(audio) }),
].map(async (record) => await admitRecord(closure, record, validatorRegistry())));
const linked = link(closure, records);
-const textInstance = elaborateGraphFragment(linked, typographyTrackFragment, {
- id: "title",
- fragment: typographyTrackFragment.id,
- inputs: {
- timeline: { kind: "record", id: "timeline" },
- program: { kind: "record", id: "text-program" },
- },
-});
-const textContribution = bindAuthorFragment(textInstance, { track: "title.track" });
-
const filmFragment = createFilmAssemblyFragment({
name: "example/main-film",
tracks: [
@@ -170,7 +145,7 @@ const filmInstance = elaborateGraphFragment(linked, filmFragment, {
program: { kind: "record", id: "film-program" },
canvas: { kind: "record", id: "canvas" },
timeline: { kind: "record", id: "timeline" },
- title: { kind: "logical-output", id: "title.track" },
+ title: { kind: "record", id: "title" },
background: { kind: "record", id: "background" },
audio: { kind: "record", id: "audio" },
},
@@ -183,7 +158,7 @@ const hyperframesInstance = elaborateGraphFragment(linked, hyperframesDocumentFr
fragment: hyperframesDocumentFragment.id,
inputs: {
composition: { kind: "logical-output", id: "main.composition" },
- space: { kind: "record", id: "render-space" },
+ timeline: { kind: "record", id: "timeline" },
},
});
const hyperframesContribution = bindAuthorFragment(hyperframesInstance, {
@@ -191,7 +166,6 @@ const hyperframesContribution = bindAuthorFragment(hyperframesInstance, {
});
const merged = mergeFragmentContributions(
{ outputs: [], candidates: [], operations: [] },
- textContribution,
filmContribution,
hyperframesContribution,
);
@@ -212,9 +186,6 @@ function producerModules(target: string): string[] {
}
test("Film stops at Composition and Hyperframes remains an ordinary downstream Fragment", () => {
- assert.deepEqual(producerNames("title.track"), [
- typographyTrackProducers.render.name,
- ]);
assert.equal(producerModules("main.composition").includes(hyperframesProducers.compile.module.name), false);
assert.deepEqual(producerNames("main.composition").filter((name) => name.startsWith("append-")).sort(), [
filmProducers.appendAudioTrack.name,
@@ -229,17 +200,6 @@ test("Film stops at Composition and Hyperframes remains an ordinary downstream F
test("the Driver folds peer Tracks, then independently compiles the Composition", async () => {
const registry = new ProducerRegistry();
- registry.registerProducer(timelineProducers.projectProgramSpace, ({ inputs }) => ({
- outputs: { space: stored(projectTimelineSpace(inline(inputs.track) as Timeline)) },
- needs: {},
- }));
- registry.registerProducer(typographyTrackProducers.render, ({ inputs }) => ({
- outputs: { track: stored(renderTypographyTrack(
- inline(inputs.timeline) as typeof space,
- inline(inputs.program) as typeof textProgram,
- )) },
- needs: {},
- }));
registry.registerProducer(filmProducers.createTrackSet, () => ({
outputs: { set: stored(createFilmTrackSet()) },
needs: {},
@@ -272,7 +232,7 @@ test("the Driver folds peer Tracks, then independently compiles the Composition"
registry.registerProducer(hyperframesProducers.compile, ({ inputs }) => ({
outputs: { document: stored(compileHyperframesDocument(
inline(inputs.composition) as never,
- inline(inputs.space) as typeof space,
+ inline(inputs.timeline) as typeof space,
)) },
needs: {},
}));
diff --git a/packages/film/test/surface.test.ts b/packages/film/test/surface.test.ts
index 96bbcffa..cb4fa64f 100644
--- a/packages/film/test/surface.test.ts
+++ b/packages/film/test/surface.test.ts
@@ -1,8 +1,6 @@
-import { sealTimeline } from "@hypit/timeline";
+import { sealTimeline, timelineDependency, timelineTypes } from "@hypit/timeline";
import { compositionComponent, spatialComponent, videoContractManifests } from "../../../test/support/video-domain.js";
import { registerTypeValidatorFacets } from "@hypit/component-kit";
-import { programSpaceDependency, programSpaceTypes, sealProgramSpace } from "@hypit/program-space";
-import { timelineDependency, timelineProducers, timelineTypes } from "@hypit/timeline";
import { compositionDependency, compositionTypes, sealAudioTrack, sealVisualTrack } from "@hypit/composition";
import type { Track } from "@hypit/composition";
import assert from "node:assert/strict";
@@ -60,16 +58,15 @@ const fixtureManifest: ModuleManifest = {
producers: [],
};
-const space = sealTimeline({ items: [], id: "test-space", durationSec: 2,
- frameRate: { numerator: 30, denominator: 1 },
+const space = sealTimeline({ id: "test-space", frameCount: 60, frameRate: { numerator: 30, denominator: 1 },
});
const semantic = timelineFixture(space);
-const visual = sealVisualTrack({ programSpaceId: "test-space",
+const visual = sealVisualTrack({ timelineId: "test-space",
visualIr: "hypit.visual-ir@1",
id: "visual",
presents: [],
});
-const audio = sealAudioTrack({ programSpaceId: "test-space",
+const audio = sealAudioTrack({ timelineId: "test-space",
id: "audio",
clips: [],
});
@@ -142,7 +139,7 @@ async function compileFilm(options: { readonly styles?: string; readonly tracks?
<import as="recipes" source="./recipes.svs"/>
<fixture:Inputs/>
<space:Canvas id="vertical" width="1080" height="1920"/>
- <film:Film id="main" canvas={vertical} timeline={semantic} appearance={recipes.film.vertical}>
+ <film:Film id="main" canvas={vertical.canvas} timeline={semantic} appearance={recipes.film.vertical}>
${options.tracks ?? '<film:Track source={visual}/><film:Track source={audio}/>'}
</film:Film>
</svml>`),
diff --git a/packages/fonts-open/package.json b/packages/fonts-open/package.json
index d5943d2d..dc876ff4 100644
--- a/packages/fonts-open/package.json
+++ b/packages/fonts-open/package.json
@@ -126,9 +126,7 @@
"@hypit/media": "workspace:*",
"@hypit/package-loader-node": "workspace:*",
"@hypit/protocol": "workspace:*",
- "@hypit/markup": "workspace:*"
- },
- "devDependencies": {
+ "@hypit/markup": "workspace:*",
"@hypit/studio-adapter": "workspace:*"
}
}
diff --git a/packages/gpt-image/package.json b/packages/gpt-image/package.json
index 241a5eed..dbbb2bb7 100644
--- a/packages/gpt-image/package.json
+++ b/packages/gpt-image/package.json
@@ -24,11 +24,11 @@
"@hypit/core": "workspace:*",
"@hypit/media": "workspace:*",
"@hypit/narrative": "workspace:*",
- "@hypit/program-space": "workspace:*",
"@hypit/raster": "workspace:*",
"@hypit/run": "workspace:*",
"@hypit/seedance": "workspace:*",
"@hypit/spatial": "workspace:*",
- "@hypit/speech": "workspace:*"
+ "@hypit/speech": "workspace:*",
+ "@hypit/timeline": "workspace:*"
}
}
diff --git a/packages/gpt-image/test/broll-graph.test.ts b/packages/gpt-image/test/broll-graph.test.ts
index 47d1508d..c2298fe3 100644
--- a/packages/gpt-image/test/broll-graph.test.ts
+++ b/packages/gpt-image/test/broll-graph.test.ts
@@ -29,7 +29,8 @@ import { gptImageDenoiseV1, imageTransformManifest, imageTransformTypes } from "
import { exactModelMediaInputNames } from "@hypit/model-kit";
import { mediaManifest } from "@hypit/media";
import { narrativeManifest } from "@hypit/narrative";
-import { programSpaceManifest } from "@hypit/program-space";
+import { timelineManifest } from "@hypit/timeline";
+import { temporalManifest } from "@hypit/temporal";
import type { CanonicalValue, ResourceId, ModuleManifest, StoredValue, TypeRef } from "@hypit/protocol";
import { rasterManifest } from "@hypit/raster";
import { createProvidedCandidate } from "@hypit/run";
@@ -62,7 +63,8 @@ function fixture() {
gptImageCleanManifest,
narrativeManifest,
mediaManifest,
- programSpaceManifest,
+ temporalManifest,
+ timelineManifest,
spatialManifest,
svsManifest,
speechManifest,
diff --git a/packages/hyperframes/README.md b/packages/hyperframes/README.md
index d6da7226..180fb75d 100644
--- a/packages/hyperframes/README.md
+++ b/packages/hyperframes/README.md
@@ -8,9 +8,10 @@ local programs. Structural elements cover ordinary boxes, exact-font text and fr
A browser program carries HTML, CSS and frame-driven JavaScript for a component's own composition.
Track and Composition remain owned by `@hypit/composition`; the browser format is owned here.
-This package understands only `VisualTrack`, `ProgramSpace` and canvas geometry. It
+This package understands only `VisualTrack`, `Timeline` and canvas geometry. It
does not know Caption, Speech, B-roll, Seedance or any other author-domain component. It flattens
-every Track's Presents, orders them by their own absolute stacking keys and emits frame-bound local
+every Track's Presents, orders them by absolute `z`, stable Track identity, Track-local Present
+`order` and Present identity, then emits frame-bound local
keyframes. An authoring Track never becomes an isolated render stacking surface.
Terminal text and SVG mask sources retain the same Present-relative frame animations as other
elements, including direct seeks into the middle of a Present.
@@ -55,7 +56,7 @@ usage spans query a sparse selection by binary search instead of scanning every
The document exposes its render domain directly rather than asking an Endpoint to scrape HTML:
exact rational `frameRate`, integer `frameCount`, and canvas dimensions are explicit document
-content. The ProgramSpace relationship is an input edge of the Producer and is not copied into the
+content. The Timeline relationship is an input edge of the Producer and is not copied into the
document as lineage metadata. Legal frame addresses are exactly `[0, frameCount)`. A local worker pool or a
hosted renderer may independently evaluate any legal frame or half-open chunk; partition size and
worker count are Runtime policy, not author intent and not Core graph nodes. The emitted root also
@@ -122,8 +123,9 @@ Returning a Promise from `render` reports an authoring error; frame capture neve
unbounded asynchronous drawing task or races it.
Ordinary child sampling follows the Present clock. Reframing the parent leaves source playback
-unchanged. `projectTimelineMedia` from `@hypit/hypit/timeline` gives a component selected prepared
-clips with their exact program and source spans. Speech audio is an independently selected Track.
+unchanged. Components receive ordinary normalized media, absolute Windows and explicit sampling when
+they need prepared footage; target and source spans follow that authored relation. Speech audio is an
+independently selected Audio Track.
`program.format` is explicit: this backend reports an unsupported format rather than interpreting
another renderer's program. Core and the build graph do not contain browser-specific cases.
diff --git a/packages/hyperframes/package.json b/packages/hyperframes/package.json
index d09e5091..b58cabb7 100644
--- a/packages/hyperframes/package.json
+++ b/packages/hyperframes/package.json
@@ -16,21 +16,20 @@
"@hypit/composition": "workspace:*",
"@hypit/elaborator": "workspace:*",
"@hypit/media": "workspace:*",
- "@hypit/program-space": "workspace:*",
"@hypit/protocol": "workspace:*",
- "@hypit/visual-ir": "workspace:*"
+ "@hypit/visual-ir": "workspace:*",
+ "@hypit/timeline": "workspace:*"
},
"devDependencies": {
"@hypit/caption": "workspace:*",
- "@hypit/caption-fine": "workspace:*",
- "@hypit/deck-track": "workspace:*",
+ "@hypit/depth-stack": "workspace:*",
"@hypit/fonts-open": "workspace:*",
- "@hypit/media-track": "workspace:*",
+ "@hypit/visual-track": "workspace:*",
"@hypit/ranking": "workspace:*",
"@hypit/screen-overlay": "workspace:*",
"@hypit/script": "workspace:*",
"@hypit/spatial": "workspace:*",
"@hypit/svs": "workspace:*",
- "@hypit/typography-track": "workspace:*"
+ "@hypit/text-fine": "workspace:*"
}
}
diff --git a/packages/hyperframes/src/component.ts b/packages/hyperframes/src/component.ts
index 4b51429a..9966e1ab 100644
--- a/packages/hyperframes/src/component.ts
+++ b/packages/hyperframes/src/component.ts
@@ -1,6 +1,6 @@
import type { ComponentPackage } from "@hypit/component-kit";
-import type { ProgramSpace } from "@hypit/program-space";
import type { Composition } from "@hypit/composition";
+import type { Timeline } from "@hypit/timeline";
import type { CanonicalValue, StoredValue } from "@hypit/protocol";
import { canonicalize } from "@hypit/protocol";
@@ -22,7 +22,7 @@ export const hyperframesComponent = {
kind: "inline",
value: canonicalize(compileHyperframesDocument(
inline(inputs.composition!.value, "Composition") as unknown as Composition,
- inline(inputs.space!.value, "ProgramSpace") as unknown as ProgramSpace,
+ inline(inputs.timeline!.value, "Timeline") as unknown as Timeline,
)),
},
},
diff --git a/packages/hyperframes/src/document.ts b/packages/hyperframes/src/document.ts
index b45238e3..5dacfcab 100644
--- a/packages/hyperframes/src/document.ts
+++ b/packages/hyperframes/src/document.ts
@@ -1,7 +1,7 @@
import { assertCompositableSurfaceRef } from "@hypit/media";
import type { CompositableSurfaceRef, FontArtifactRef } from "@hypit/media";
-import { programSpaceFrameCount } from "@hypit/program-space";
-import type { ProgramSpace } from "@hypit/program-space";
+import { timelineFrameCount } from "@hypit/timeline";
+import type { Timeline } from "@hypit/timeline";
import { assertCompositionIdentity } from "@hypit/composition";
import type {
Composition,
@@ -10,8 +10,8 @@ import type {
VisualAttribute,
VisualElement,
VisualPresent,
- VisualSamplingRational,
- VisualSamplingSegment,
+ VisualSourceTimeRational,
+ VisualSourceTimePiece,
VisualStyleDeclaration,
VisualTrack,
} from "@hypit/composition";
@@ -80,30 +80,30 @@ function rationalDecimal(numerator: bigint, denominator: bigint): string {
return `${whole}.${String(remainder).padStart(12, "0").replace(/0+$/u, "")}`;
}
-function sourceSeconds(frame: VisualSamplingRational, frameRate: VisualSamplingRational): string {
+function sourceSeconds(frame: VisualSourceTimeRational, frameRate: VisualSourceTimeRational): string {
return rationalDecimal(
BigInt(frame.numerator) * BigInt(frameRate.denominator),
BigInt(frame.denominator) * BigInt(frameRate.numerator),
);
}
-function sourcePosition(segment: VisualSamplingSegment, offset: number): {
- readonly position: VisualSamplingRational;
+function sourcePosition(piece: VisualSourceTimePiece, offset: number): {
+ readonly position: VisualSourceTimeRational;
readonly cycle: bigint;
} {
- const denominator = BigInt(segment.sourceFrame.denominator) * BigInt(segment.rate.denominator);
- const raw = BigInt(segment.sourceFrame.numerator) * BigInt(segment.rate.denominator)
- + BigInt(offset) * BigInt(segment.rate.numerator) * BigInt(segment.sourceFrame.denominator);
- if (segment.loop === undefined) {
+ const denominator = BigInt(piece.sourceAtStart.denominator) * BigInt(piece.rate.denominator);
+ const raw = BigInt(piece.sourceAtStart.numerator) * BigInt(piece.rate.denominator)
+ + BigInt(offset) * BigInt(piece.rate.numerator) * BigInt(piece.sourceAtStart.denominator);
+ if (piece.wrap === undefined) {
if (raw < 0n || raw > BigInt(Number.MAX_SAFE_INTEGER) || denominator > BigInt(Number.MAX_SAFE_INTEGER)) {
- throw new Error("HyperFrames visual sampling exceeds safe arithmetic.");
+ throw new Error("HyperFrames visual source time exceeds safe arithmetic.");
}
return { position: { numerator: Number(raw), denominator: Number(denominator) }, cycle: 0n };
}
- const start = BigInt(segment.loop.startFrame) * denominator;
- const length = BigInt(segment.loop.endFrameExclusive - segment.loop.startFrame) * denominator;
+ const start = BigInt(piece.wrap.startFrame) * denominator;
+ const length = BigInt(piece.wrap.endFrameExclusive - piece.wrap.startFrame) * denominator;
const delta = raw - start;
- const cycle = delta / length;
+ const cycle = delta >= 0n ? delta / length : -((-delta + length - 1n) / length);
const wrapped = ((delta % length) + length) % length;
const numerator = start + wrapped;
if (numerator > BigInt(Number.MAX_SAFE_INTEGER) || denominator > BigInt(Number.MAX_SAFE_INTEGER)) {
@@ -112,56 +112,56 @@ function sourcePosition(segment: VisualSamplingSegment, offset: number): {
return { position: { numerator: Number(numerator), denominator: Number(denominator) }, cycle };
}
-function samplingRuns(segment: VisualSamplingSegment): Array<{
+function sourceTimeRuns(piece: VisualSourceTimePiece): Array<{
readonly startFrame: number;
readonly endFrameExclusive: number;
- readonly sourceFrame: VisualSamplingRational;
+ readonly sourceFrame: VisualSourceTimeRational;
}> {
- const length = segment.target.endFrameExclusive - segment.target.startFrame;
- const runs: Array<{ startFrame: number; endFrameExclusive: number; sourceFrame: VisualSamplingRational }> = [];
+ const length = piece.target.endFrameExclusive - piece.target.startFrame;
+ const runs: Array<{ startFrame: number; endFrameExclusive: number; sourceFrame: VisualSourceTimeRational }> = [];
// Keep a hold as the interval it is. HTMLMediaElement cannot accept a zero
// playbackRate, but that browser limitation belongs to the render/preview
// adapters; expanding the shared sampling description here would turn one
// authored relation into O(target frames) DOM and Provider work.
- if (segment.rate.numerator === 0) {
+ if (piece.rate.numerator === 0 || piece.wrap === undefined) {
return [{
- startFrame: segment.target.startFrame,
- endFrameExclusive: segment.target.endFrameExclusive,
- sourceFrame: sourcePosition(segment, 0).position,
+ startFrame: piece.target.startFrame,
+ endFrameExclusive: piece.target.endFrameExclusive,
+ sourceFrame: sourcePosition(piece, 0).position,
}];
}
let runStart = 0;
- let runSource = sourcePosition(segment, 0);
- for (let offset = 1; offset < length; offset += 1) {
- const next = sourcePosition(segment, offset);
- if (next.cycle !== runSource.cycle) {
- runs.push({
- startFrame: segment.target.startFrame + runStart,
- endFrameExclusive: segment.target.startFrame + offset,
- sourceFrame: runSource.position,
- });
- runStart = offset;
- runSource = next;
+ while (runStart < length) {
+ const runSource = sourcePosition(piece, runStart);
+ let left = runStart + 1;
+ let right = length;
+ while (left < right) {
+ const middle = left + Math.floor((right - left) / 2);
+ const cycle = sourcePosition(piece, middle).cycle;
+ const crossed = piece.rate.numerator > 0 ? cycle > runSource.cycle : cycle < runSource.cycle;
+ if (crossed) right = middle;
+ else left = middle + 1;
}
+ runs.push({
+ startFrame: piece.target.startFrame + runStart,
+ endFrameExclusive: piece.target.startFrame + left,
+ sourceFrame: runSource.position,
+ });
+ runStart = left;
}
- runs.push({
- startFrame: segment.target.startFrame + runStart,
- endFrameExclusive: segment.target.endFrameExclusive,
- sourceFrame: runSource.position,
- });
return runs;
}
function sampledPlaybackRate(
- rate: VisualSamplingRational,
- sourceFrameRate: VisualSamplingRational,
+ rate: VisualSourceTimeRational,
+ sourceFrameRate: VisualSourceTimeRational,
programNumerator: number,
programDenominator: number,
): string {
// The exact zero rate remains in data-hypit-source-rate for adapters that
// place discrete frames. This positive fallback is only the legal native
// HTMLMediaElement value; preview adapters pause and seek held elements.
- if (rate.numerator === 0) return "1";
+ if (rate.numerator <= 0) return "1";
return rationalDecimal(
BigInt(rate.numerator) * BigInt(programNumerator) * BigInt(sourceFrameRate.denominator),
BigInt(rate.denominator) * BigInt(programDenominator) * BigInt(sourceFrameRate.numerator),
@@ -373,10 +373,10 @@ function renderElement(
if (element.kind === "text-flow" || element.kind === "path-text") {
return renderTerminalTextElement(element, textContext);
}
- if ((element.kind === "video" || element.kind === "surface") && element.sampling !== undefined) {
+ if ((element.kind === "video" || element.kind === "surface") && element.sourceTime !== undefined) {
const artifact = element.kind === "surface" ? element.surface.artifact : element.artifact;
let part = 0;
- return element.sampling.segments.flatMap((segment) => samplingRuns(segment).map((run) => {
+ return element.sourceTime.pieces.flatMap((piece) => sourceTimeRuns(piece).map((run) => {
part += 1;
const startFrame = context.presentStartFrame + run.startFrame;
const durationFrames = run.endFrameExclusive - run.startFrame;
@@ -388,13 +388,13 @@ function renderElement(
`data-start="${frameSeconds(startFrame, context.programNumerator, context.programDenominator)}"`,
`data-duration="${frameSeconds(durationFrames, context.programNumerator, context.programDenominator)}"`,
`data-track-index="${context.stackIndex}"`,
- `data-media-start="${sourceSeconds(run.sourceFrame, element.sampling!.sourceFrameRate)}"`,
- `data-playback-rate="${sampledPlaybackRate(segment.rate, element.sampling!.sourceFrameRate, context.programNumerator, context.programDenominator)}"`,
+ `data-media-start="${sourceSeconds(run.sourceFrame, element.sourceTime!.sourceFrameRate)}"`,
+ `data-playback-rate="${sampledPlaybackRate(piece.rate, element.sourceTime!.sourceFrameRate, context.programNumerator, context.programDenominator)}"`,
`data-hypit-source-frame="${run.sourceFrame.numerator}/${run.sourceFrame.denominator}"`,
- `data-hypit-source-rate="${segment.rate.numerator}/${segment.rate.denominator}"`,
+ `data-hypit-source-rate="${piece.rate.numerator}/${piece.rate.denominator}"`,
`data-hypit-start-frame="${startFrame}"`,
`data-hypit-end-frame="${startFrame + durationFrames}"`,
- `data-hypit-source-fps="${element.sampling!.sourceFrameRate.numerator}/${element.sampling!.sourceFrameRate.denominator}"`,
+ `data-hypit-source-fps="${element.sourceTime!.sourceFrameRate.numerator}/${element.sourceTime!.sourceFrameRate.denominator}"`,
`style="${escapeHtml(inlineStyle)}"`,
attributes(element.attributes).trim(),
"muted",
@@ -422,9 +422,7 @@ function renderElement(
`height="${element.surface.height}"`,
].join(" ");
if (element.surface.timing.kind === "still") return `<img ${common} ${surface} ${deferredResource("src", element.surface.artifact.resource)}/>`;
- const timing = element.surface.timing;
- const exact = `data-hypit-start-frame="${context.presentStartFrame}" data-hypit-end-frame="${context.presentStartFrame + timing.frameCount}" data-hypit-source-frame="0/1" data-hypit-source-rate="1/1" data-hypit-source-fps="${timing.frameRate.numerator}/${timing.frameRate.denominator}"`;
- return `<video ${common} ${surface} ${exact} muted playsinline ${deferredResource("src", element.surface.artifact.resource)}></video>`;
+ throw new Error(`Timed Surface ${element.id} has no source-time map.`);
}
const media = [
@@ -435,8 +433,7 @@ function renderElement(
element.kind === "video" ? "playsinline" : "",
].filter(Boolean).join(" ");
if (element.kind === "image") return `<img ${common} ${media} ${deferredResource("src", element.artifact.resource)}/>`;
- const exact = `data-hypit-start-frame="${context.presentStartFrame}" data-hypit-end-frame="${context.presentStartFrame + context.presentDurationFrames}" data-hypit-source-frame="0/1" data-hypit-source-rate="1/1" data-hypit-source-fps="${context.programNumerator}/${context.programDenominator}"`;
- return `<video ${common} ${media} ${exact} ${deferredResource("src", element.artifact.resource)}>${descendants}</video>`;
+ throw new Error(`Timed visual element ${element.id} has no source-time map.`);
}
function renderVisualPresent(
@@ -474,7 +471,7 @@ function renderVisualPresent(
sharedGlyphFilterDefinitions,
stableId,
});
- return `<div class="clip hypit-visual-present" data-hypit-track-id="${escapeHtml(track.id)}" data-hypit-present-id="${escapeHtml(present.id)}" data-hypit-present-start-frame="${present.span.startFrame}" data-hypit-present-end-frame="${present.span.endFrameExclusive}" data-hypit-stack-order="${present.stacking.order}" data-hypit-stack-tie="${escapeHtml(present.stacking.tieBreak)}" data-track-index="${stackIndex}" data-start="${start}" data-duration="${duration}" style="position:absolute;inset:0;z-index:${stackIndex};overflow:hidden;pointer-events:none">${present.visibility === undefined ? contents : `<div data-hypit-visibility="${escapeHtml(JSON.stringify(present.visibility))}" style="position:absolute;inset:0">${contents}</div>`}</div>`;
+ return `<div class="clip hypit-visual-present" data-hypit-track-id="${escapeHtml(track.id)}" data-hypit-present-id="${escapeHtml(present.id)}" data-hypit-present-start-frame="${present.span.startFrame}" data-hypit-present-end-frame="${present.span.endFrameExclusive}" data-hypit-present-order="${present.order}" data-hypit-z="${present.z}" data-track-index="${stackIndex}" data-start="${start}" data-duration="${duration}" style="position:absolute;inset:0;z-index:${stackIndex};overflow:hidden;pointer-events:none">${present.visibility === undefined ? contents : `<div data-hypit-visibility="${escapeHtml(JSON.stringify(present.visibility))}" style="position:absolute;inset:0">${contents}</div>`}</div>`;
}
function renderAnimationRules(track: VisualTrack, present: VisualPresent, stableId: StableDomId): string[] {
@@ -501,10 +498,9 @@ function orderedVisualPresents(tracks: readonly Track[]): Array<{ readonly track
return tracks
.filter((track): track is VisualTrack => track.kind === "visual")
.flatMap((track) => track.presents.map((present) => ({ track, present })))
- .sort((left, right) => left.present.stacking.order - right.present.stacking.order
- || left.present.stacking.tieBreak.localeCompare(right.present.stacking.tieBreak)
- || left.present.span.startFrame - right.present.span.startFrame
+ .sort((left, right) => left.present.z - right.present.z
|| left.track.id.localeCompare(right.track.id)
+ || left.present.order - right.present.order
|| left.present.id.localeCompare(right.present.id));
}
@@ -668,11 +664,18 @@ function frameAnimationRuntime(numerator: number, denominator: number): string {
void element.getBoundingClientRect();
const animation = element.getAnimations()[0];
if (animation === undefined) throw new Error("Visual IR frame animation did not materialize.");
- animation.pause();
- animation.currentTime = 0;
- // The authored keyframes are already the compact state function. Keep the
- // browser's paused evaluator instead of expanding every Present frame into
- // a second table of computed-style strings in every render Worker.
+ // The authored keyframes are already the compact state function. Keep them
+ // instead of expanding every Present frame into a second table of
+ // computed-style strings in every render Worker, but do not leave the CSS
+ // animation live: HyperFrames' css and waapi adapters seek every live
+ // document animation to absolute composition time, which replaces this
+ // Present-relative pose whenever the Present does not start at frame 0.
+ const keyframes = animation.effect.getKeyframes();
+ const timing = animation.effect.getTiming();
+ const properties = [...new Set(keyframes.flatMap((keyframe) => Object.keys(keyframe)))]
+ .filter((name) => name !== "offset" && name !== "computedOffset" && name !== "easing" && name !== "composite");
+ animation.cancel();
+ element.style.animationName = "none";
const key = start + ":" + end;
let work = groupsBySpan.get(key);
if (work === undefined) {
@@ -684,20 +687,43 @@ function frameAnimationRuntime(numerator: number, denominator: number): string {
};
groupsBySpan.set(key, work);
}
- work.payload.animations.push(animation);
+ work.payload.animations.push({ element, keyframes, timing, properties });
}
// The shared index owns only frame-span lookup. Animation materialization and
// absolute currentTime evaluation remain private to this adapter.
const workIndex = hyperframesCreateFrameWorkIndex([...groupsBySpan.values()]);
+ const read = (style, name) => name.startsWith("--") ? style.getPropertyValue(name) : style[name];
+ const write = (style, name, value) => {
+ if (name.startsWith("--")) style.setProperty(name, value);
+ else style[name] = value;
+ };
const applyFrame = (time) => {
const programFrame = Math.max(0, Math.round(Number(time || 0) * numerator / denominator));
+ const active = [];
for (const work of workIndex.at(programFrame)) {
const localTime = (programFrame - work.startFrame) * millisecondsPerFrame;
// Always derive the pose from the absolute requested frame. Worker
// partitioning, seek order and the previously rendered frame are not
// inputs to animation state.
- for (const animation of work.payload.animations) animation.currentTime = localTime;
+ for (const item of work.payload.animations) active.push({ item, localTime });
}
+ // Evaluate each pose with a transient Animation, read it and cancel it before
+ // this seek returns, so no adapter ever sees it. The Animation constructor,
+ // unlike Element.animate, is not tracked by HyperFrames' waapi adapter. Only
+ // the resulting inline style reaches the captured frame.
+ const probes = active.map(({ item, localTime }) => {
+ const probe = new Animation(new KeyframeEffect(item.element, item.keyframes, item.timing), document.timeline);
+ probe.currentTime = localTime;
+ return probe;
+ });
+ const poses = active.map(({ item }) => {
+ const style = getComputedStyle(item.element);
+ return item.properties.map((name) => read(style, name));
+ });
+ for (const probe of probes) probe.cancel();
+ active.forEach(({ item }, index) => {
+ item.properties.forEach((name, position) => write(item.element.style, name, poses[index][position]));
+ });
void document.documentElement.getBoundingClientRect();
};
void document.documentElement.getBoundingClientRect();
@@ -705,8 +731,8 @@ function frameAnimationRuntime(numerator: number, denominator: number): string {
})();`;
}
-function emitHtml(composition: Composition, programSpace: ProgramSpace): string {
- const { numerator, denominator } = programSpace.frameRate;
+function emitHtml(composition: Composition, timeline: Timeline): string {
+ const { numerator, denominator } = timeline.frameRate;
const visuals = orderedVisualPresents(composition.tracks);
// One document, one set of glyph filter definitions. Keep definitions outside
// temporal Present roots so a render can make an unrelated Present inert
@@ -730,9 +756,9 @@ function emitHtml(composition: Composition, programSpace: ProgramSpace): string
const hasVisibility = visuals.some(({ present }) => present.visibility !== undefined);
const programRuntime = programs.length === 0 ? "" : `<script>${browserProgramScript(programs, numerator, denominator)}</script>`;
const visibilityRuntime = hasVisibility ? `<script>${presentationVisibilityScript(numerator, denominator)}</script>` : "";
- const duration = frameSeconds(programSpaceFrameCount(programSpace), numerator, denominator);
+ const duration = frameSeconds(timelineFrameCount(timeline), numerator, denominator);
const fps = fpsRational(numerator, denominator);
- const frameCount = programSpaceFrameCount(programSpace);
+ const frameCount = timelineFrameCount(timeline);
const needsFrameWork = hasFrameAnimations(composition) || hasTerminalText(composition) || programs.length > 0 || hasVisibility;
const frameRuntime = `\n <script>\n ${needsFrameWork ? frameWorkIndexRuntime : frameSelectionRuntime}\n </script>
<script>${presentationCaptureScopeRuntime}</script>${hasFrameAnimations(composition) || hasTerminalText(composition)
@@ -780,19 +806,19 @@ function normalizedDocument(value: HyperframesDocument): HyperframesDocument {
};
}
-export function compileHyperframesDocument(composition: Composition, programSpace: ProgramSpace): HyperframesDocument {
- assertCompositionIdentity(composition, programSpace);
+export function compileHyperframesDocument(composition: Composition, timeline: Timeline): HyperframesDocument {
+ assertCompositionIdentity(composition, timeline);
const content = normalizedDocument({
visualIr: VISUAL_IR_V1,
- frameRate: { ...programSpace.frameRate },
- frameCount: programSpaceFrameCount(programSpace),
+ frameRate: { ...timeline.frameRate },
+ frameCount: timelineFrameCount(timeline),
canvas: {
width: composition.canvas.width,
height: composition.canvas.height,
},
artifacts: collectArtifacts(composition),
surfaces: collectSurfaces(composition),
- html: emitHtml(composition, programSpace),
+ html: emitHtml(composition, timeline),
});
return content;
}
diff --git a/packages/hyperframes/src/fragment.ts b/packages/hyperframes/src/fragment.ts
index df95cc37..27536c7e 100644
--- a/packages/hyperframes/src/fragment.ts
+++ b/packages/hyperframes/src/fragment.ts
@@ -1,7 +1,7 @@
-import { programSpaceTypes } from "@hypit/program-space";
import { compositionTypes } from "@hypit/composition";
import type { Composition } from "@hypit/composition";
import { sealGraphFragment } from "@hypit/elaborator";
+import { timelineTypes } from "@hypit/timeline";
import { hyperframesProducers, hyperframesTypes } from "./manifest.js";
@@ -16,12 +16,12 @@ const operation = (id: string) => ({ kind: "fragment-operation" as const, operat
export const hyperframesDocumentFragment = sealGraphFragment({
inputs: [
{ name: "composition", type: compositionTypes.composition },
- { name: "space", type: programSpaceTypes.programSpace },
+ { name: "timeline", type: timelineTypes.track },
],
operations: [{
id: "compile-document",
producer: hyperframesProducers.compile,
- inputs: { composition: input("composition"), space: input("space") },
+ inputs: { composition: input("composition"), timeline: input("timeline") },
result: { kind: "output", name: "document" },
}],
exports: [{
diff --git a/packages/hyperframes/src/manifest.ts b/packages/hyperframes/src/manifest.ts
index 5392cdcb..1fb10f0c 100644
--- a/packages/hyperframes/src/manifest.ts
+++ b/packages/hyperframes/src/manifest.ts
@@ -1,8 +1,8 @@
-import { programSpaceDependency, programSpaceTypes } from "@hypit/program-space";
import { compositionDependency, compositionTypes } from "@hypit/composition";
import { compositableSurfaceSchema, mediaDependency } from "@hypit/media";
import type { ModuleManifest, ProducerRef, TypeRef, ValueSchema } from "@hypit/protocol";
import { VISUAL_IR_V1 } from "@hypit/visual-ir";
+import { timelineDependency, timelineTypes } from "@hypit/timeline";
export const hyperframesModuleRef = { name: "@hypit/hyperframes", version: "1" } as const;
export const hyperframesTypes = {
@@ -64,14 +64,14 @@ export const hyperframesManifest: ModuleManifest = {
format: "hypit.module@1",
name: hyperframesModuleRef.name,
version: hyperframesModuleRef.version,
- dependencies: [compositionDependency, mediaDependency, programSpaceDependency],
+ dependencies: [compositionDependency, mediaDependency, timelineDependency],
types: [{ name: hyperframesTypes.document.name }],
capabilities: [],
producers: [{
name: hyperframesProducers.compile.name,
inputs: [
{ name: "composition", type: compositionTypes.composition },
- { name: "space", type: programSpaceTypes.programSpace },
+ { name: "timeline", type: timelineTypes.track },
],
outputs: [{ name: "document", type: hyperframesTypes.document }],
needs: [],
diff --git a/packages/hyperframes/test/document.test.ts b/packages/hyperframes/test/document.test.ts
index 9ace54a3..a1fb4134 100644
--- a/packages/hyperframes/test/document.test.ts
+++ b/packages/hyperframes/test/document.test.ts
@@ -7,7 +7,7 @@ import {
materializeHyperframesHtml,
} from "@hypit/hyperframes";
import type { FontArtifactRef } from "@hypit/media";
-import { sealProgramSpace } from "@hypit/program-space";
+import { sealTimeline } from "@hypit/timeline";
import { sealAudioTrack, sealComposition, sealVisualTrack } from "@hypit/composition";
import type { Track } from "@hypit/composition";
import { VISUAL_IR_V1 } from "@hypit/visual-ir";
@@ -22,8 +22,7 @@ const fixtureFont: FontArtifactRef = {
};
function fixture() {
- const programSpace = sealProgramSpace({ id: "test-space", durationSec: 1001 / 1000,
- frameRate: { numerator: 30_000, denominator: 1_001 },
+ const timeline = sealTimeline({ id: "test-space", frameCount: 30, frameRate: { numerator: 30_000, denominator: 1_001 },
});
const picture = {
kind: "blob" as const,
@@ -37,13 +36,14 @@ function fixture() {
size: 20,
mediaType: "audio/wav",
};
- const lower = sealVisualTrack({ programSpaceId: "test-space",
+ const lower = sealVisualTrack({ timelineId: "test-space",
visualIr: "hypit.visual-ir@1",
id: "lower",
presents: [{
id: "picture",
+ order: 0,
+ z: 10,
span: { startFrame: 0, endFrameExclusive: 30 },
- stacking: { order: 10, tieBreak: "lower" },
elements: [{
id: "media",
order: 0,
@@ -53,13 +53,14 @@ function fixture() {
}],
}],
});
- const upper = sealVisualTrack({ programSpaceId: "test-space",
+ const upper = sealVisualTrack({ timelineId: "test-space",
visualIr: "hypit.visual-ir@1",
id: "upper",
presents: [{
id: "words",
+ order: 0,
+ z: 20,
span: { startFrame: 3, endFrameExclusive: 20 },
- stacking: { order: 20, tieBreak: "upper" },
elements: [
{ id: "root", order: 0, kind: "box", style: [{ name: "position", value: "absolute" }] },
{ id: "text", parent: "root", order: 1, kind: "text", text: "Hello <world>", fonts: [fixtureFont], style: [],
@@ -72,15 +73,16 @@ function fixture() {
],
}],
});
- const audio = sealAudioTrack({ programSpaceId: "test-space",
+ const audio = sealAudioTrack({ timelineId: "test-space",
id: "sound",
clips: [{
id: "main",
artifact: sound,
target: { startSample: 0, endSampleExclusive: 48_000 },
- source: { sampleFrames: 48_000, startSample: 0, endSampleExclusive: 48_000, loop: false, phaseSample: 0 },
- playbackRate: 1,
- pitch: "preserve",
+ sourceTime: { sourceSampleFrames: 48_000, pieces: [{
+ target: { startSample: 0, endSampleExclusive: 48_000 },
+ sourceAtStart: { numerator: 0, denominator: 1 }, rate: { numerator: 1, denominator: 1 },
+ }] },
gain: 1,
fadeInSamples: 0,
fadeOutSamples: 0,
@@ -91,12 +93,12 @@ function fixture() {
canvas: { width: 1080, height: 1920, clearColor: "#000000" },
tracks: [upper, audio, lower],
});
- return { composition, picture, sound, programSpace };
+ return { composition, picture, sound, timeline };
}
test("HyperFrames flattens generic peer visual Track Presents without absorbing audio rendering", () => {
- const { composition, picture, sound, programSpace } = fixture();
- const document = compileHyperframesDocument(composition, programSpace);
+ const { composition, picture, sound, timeline } = fixture();
+ const document = compileHyperframesDocument(composition, timeline);
assert.doesNotThrow(() => assertHyperframesDocument(document));
assert.equal(document.visualIr, VISUAL_IR_V1);
assert.deepEqual(new Set(document.artifacts.map(({ artifact }) => artifact.resource)),
@@ -121,8 +123,42 @@ test("HyperFrames flattens generic peer visual Track Presents without absorbing
assert.doesNotMatch(document.html, /speech-visual-track|caption-track/u);
});
+test("equal-z Presents use stable Track identity and Track-local order", () => {
+ const timeline = sealTimeline({
+ id: "paint-order",
+ frameCount: 30,
+ frameRate: { numerator: 30, denominator: 1 },
+ });
+ const visualTrack = (id: string, presents: Array<{ id: string; order: number }>) => sealVisualTrack({
+ timelineId: timeline.id,
+ visualIr: VISUAL_IR_V1,
+ id,
+ presents: presents.map(present => ({
+ ...present,
+ z: 10,
+ span: { startFrame: 0, endFrameExclusive: 30 },
+ elements: [{ id: "root", order: 0, kind: "box", style: [] }],
+ })),
+ });
+ const composition = sealComposition({
+ id: "paint-order",
+ canvas: { width: 1920, height: 1080, clearColor: "#000000" },
+ tracks: [
+ visualTrack("track-b", [{ id: "b-second", order: 1 }, { id: "b-first", order: 0 }]),
+ visualTrack("track-a", [{ id: "a", order: 0 }]),
+ ],
+ });
+
+ const html = compileHyperframesDocument(composition, timeline).html;
+ const a = html.indexOf('data-hypit-present-id="a"');
+ const first = html.indexOf('data-hypit-present-id="b-first"');
+ const second = html.indexOf('data-hypit-present-id="b-second"');
+ assert.ok(a >= 0 && a < first && first < second);
+ assert.equal((html.match(/data-hypit-z="10"/gu) ?? []).length, 3);
+});
+
test("shared glyph filter definitions live outside temporal Present capture roots", () => {
- const { composition, programSpace } = fixture();
+ const { composition, timeline } = fixture();
const changed = structuredClone(composition);
const upper = changed.tracks.find(track => track.kind === "visual" && track.id === "upper");
assert.ok(upper?.kind === "visual");
@@ -132,7 +168,7 @@ test("shared glyph filter definitions live outside temporal Present capture root
{ kind: "glow", paint: { kind: "solid", color: "#ff00ff" }, blurPx: 4, spreadPx: 1 },
{ kind: "fill", paint: { kind: "solid", color: "#ffffff" } },
] });
- const html = compileHyperframesDocument(changed, programSpace).html;
+ const html = compileHyperframesDocument(changed, timeline).html;
const definitions = html.indexOf("data-hypit-document-definitions");
const present = html.indexOf('class="clip hypit-visual-present"');
assert.ok(definitions >= 0 && definitions < present);
@@ -141,19 +177,19 @@ test("shared glyph filter definitions live outside temporal Present capture root
});
test("Text shrink preserves authored hug sizing and trims metrics inside the content box", () => {
- const programSpace = sealProgramSpace({
+ const timeline = sealTimeline({
id: "text-space",
- durationSec: 1,
- frameRate: { numerator: 30, denominator: 1 },
+ frameCount: 30, frameRate: { numerator: 30, denominator: 1 },
});
const track = sealVisualTrack({
- programSpaceId: programSpace.id,
+ timelineId: timeline.id,
visualIr: "hypit.visual-ir@1",
id: "text",
presents: [{
id: "title",
+ order: 0,
+ z: 1,
span: { startFrame: 0, endFrameExclusive: 30 },
- stacking: { order: 1, tieBreak: "title" },
elements: [
{ id: "root", order: 0, kind: "box", style: [{ name: "position", value: "absolute" }, { name: "inset", value: 0 }] },
{
@@ -234,7 +270,7 @@ test("Text shrink preserves authored hug sizing and trims metrics inside the con
id: "text-boxes",
canvas: { width: 720, height: 1280, clearColor: "#000000" },
tracks: [track],
- }), programSpace);
+ }), timeline);
assert.match(document.html, /data-hypit-text-flow data-hypit-text-overflow="shrink" data-hypit-text-inline-size="fixed" data-hypit-text-block-size="hug"/u);
assert.match(document.html, /flex-shrink:0/u);
@@ -245,8 +281,8 @@ test("Text shrink preserves authored hug sizing and trims metrics inside the con
});
test("visual Artifact placeholders are materialized only by the Runtime boundary", () => {
- const { composition, picture, sound, programSpace } = fixture();
- const document = compileHyperframesDocument(composition, programSpace);
+ const { composition, picture, sound, timeline } = fixture();
+ const document = compileHyperframesDocument(composition, timeline);
assert.match(document.html, /hypit-resource:\/\/res_/u);
const resolved = materializeHyperframesHtml(document,
(artifact) => `https://assets.example/${artifact.resource}?x=1&y=2`);
@@ -257,8 +293,8 @@ test("visual Artifact placeholders are materialized only by the Runtime boundary
});
test("HyperframesDocument carries render facts while its Record binds integrity", () => {
- const { composition, programSpace } = fixture();
- const document = compileHyperframesDocument(composition, programSpace);
+ const { composition, timeline } = fixture();
+ const document = compileHyperframesDocument(composition, timeline);
assert.equal("digest" in document, false);
assert.deepEqual(document.frameRate, { numerator: 30_000, denominator: 1_001 });
assert.equal(document.frameCount, 30);
@@ -271,7 +307,7 @@ test("HyperframesDocument carries render facts while its Record binds integrity"
test("any legal frame and Provider-owned chunk can be addressed without traversing earlier frames", () => {
const fixtureValue = fixture();
- const document = compileHyperframesDocument(fixtureValue.composition, fixtureValue.programSpace);
+ const document = compileHyperframesDocument(fixtureValue.composition, fixtureValue.timeline);
assert.doesNotThrow(() => assertHyperframesFrameIndex(document, 0));
assert.doesNotThrow(() => assertHyperframesFrameIndex(document, 17));
assert.doesNotThrow(() => assertHyperframesFrameIndex(document, 29));
@@ -296,7 +332,7 @@ test("any legal frame and Provider-owned chunk can be addressed without traversi
});
test("HyperFrames emits compact absolute-frame animation without creating a Track stacking context", async () => {
- const { composition, programSpace } = fixture();
+ const { composition, timeline } = fixture();
const lower = composition.tracks.find((track) => track.id === "lower");
assert(lower?.kind === "visual");
const present = lower.presents[0]!;
@@ -319,14 +355,15 @@ test("HyperFrames emits compact absolute-frame animation without creating a Trac
const document = compileHyperframesDocument(sealComposition({
...composition,
tracks: composition.tracks.map((track) => track.id === "lower" ? animated : track),
- }), programSpace);
+ }), timeline);
assert.match(document.html, /@keyframes hypit-/u);
assert.match(document.html, /33\.333333333%\{opacity:1;transform:translateY\(0%\)/u);
assert.match(document.html, /animation-duration:1\.001s/u);
assert.match(document.html, /100%\{opacity:1;transform:translateY\(0%\)\}/u);
assert.match(document.html, /hyperframesCreateFrameWorkIndex/u);
- assert.match(document.html, /for \(const animation of work\.payload\.animations\) animation\.currentTime = localTime/u);
- assert.doesNotMatch(document.html, /const frames = \[\]|getComputedStyle\(element\)|animation\.cancel\(\)/u);
+ assert.match(document.html, /new Animation\(new KeyframeEffect\(/u);
+ assert.doesNotMatch(document.html, /const frames = \[\]/u, "poses are evaluated per seek, not tabulated per Present frame");
+ assert.doesNotMatch(document.html, /\.animate\(/u, "HyperFrames' waapi adapter tracks Element.animate");
assert.doesNotMatch(document.html, /isolation:isolate/u);
const marker = document.html.indexOf("const millisecondsPerFrame");
@@ -335,42 +372,102 @@ test("HyperFrames emits compact absolute-frame animation without creating a Trac
const scriptEnd = document.html.indexOf("</script>", marker);
const { frameWorkIndexRuntime, hyperframesFrameSelectionPrelude } = await import("../src/frame-work.js");
const runtime = `${frameWorkIndexRuntime}\n${document.html.slice(scriptStart, scriptEnd)}`;
+ const toFrame = (milliseconds: number) => Math.round(milliseconds * 30 / 1_001);
+ // The fake engine advances every animation that remains live after Hypit's
+ // seek handler. This is the collision which made later Presents use absolute
+ // composition time even though Hypit had first applied a local pose.
const evaluate = async (
spans: readonly { readonly start: number; readonly duration: number }[],
frames: readonly number[],
selection?: readonly { readonly startFrame: number; readonly endFrameExclusive: number }[],
) => {
const { runInNewContext } = await import("node:vm");
+ type FakeElement = { pose: number | undefined; readonly style: Record<string, unknown> };
+ type FakeAnimation = { readonly target: FakeElement; currentTime: number; pause(): void; cancel(): void };
const positions = spans.map((): number[] => []);
- let pauses = 0;
+ const live = new Set<FakeAnimation>();
+ let materialized = 0;
let seek: (event: { detail: { time: number } }) => void = () => {};
- const elements = spans.map((span, index) => ({
- getBoundingClientRect() {},
- getAnimations: () => [{
- set currentTime(value: number) { positions[index]!.push(Math.round(value * 30 / 1_001)); },
- pause() { pauses += 1; },
- }],
- getAttribute: (name: string) => String(name.endsWith("start-frame") ? span.start : span.duration),
- }));
+ const animate = (target: FakeElement, record?: number[], effect?: object): FakeAnimation => {
+ const animation = {
+ target,
+ effect,
+ set currentTime(value: number) {
+ record?.push(toFrame(value));
+ target.pose = toFrame(value);
+ },
+ pause() {},
+ cancel() {
+ live.delete(animation);
+ target.pose = undefined;
+ },
+ };
+ live.add(animation);
+ return animation;
+ };
+ const elements = spans.map((span) => {
+ const element = {
+ pose: undefined as number | undefined,
+ style: {} as Record<string, unknown>,
+ getBoundingClientRect() {},
+ getAnimations: () => [...live].filter((animation) => animation.target === element),
+ getAttribute: (name: string) => String(name.endsWith("start-frame") ? span.start : span.duration),
+ };
+ animate(element, undefined, {
+ getKeyframes: () => {
+ materialized += 1;
+ return [
+ { offset: 0, computedOffset: 0, easing: "linear", composite: "auto", opacity: "0" },
+ { offset: 1, computedOffset: 1, easing: "linear", composite: "auto", opacity: String(span.duration) },
+ ];
+ },
+ getTiming: () => ({ duration: span.duration * 1_001 / 30, fill: "both" }),
+ });
+ return element;
+ });
runInNewContext(`${selection === undefined ? "" : hyperframesFrameSelectionPrelude(selection)}\n${runtime}`, {
- document: { querySelectorAll: () => elements, documentElement: { getBoundingClientRect() {} } },
+ document: { querySelectorAll: () => elements, documentElement: { getBoundingClientRect() {} }, timeline: {} },
window: { addEventListener(_name: string, callback: typeof seek) { seek = callback; } },
+ KeyframeEffect: class {
+ readonly target: FakeElement;
+ constructor(target: FakeElement) { this.target = target; }
+ },
+ Animation: function (effect: { target: FakeElement }) {
+ return animate(effect.target, positions[elements.indexOf(effect.target as typeof elements[number])]);
+ },
+ getComputedStyle: (element: FakeElement) => ({ opacity: String(element.pose) }),
});
- for (const frame of frames) seek({ detail: { time: frame * 1_001 / 30_000 } });
- return { pauses, positions };
+ for (const frame of frames) {
+ seek({ detail: { time: frame * 1_001 / 30_000 } });
+ for (const animation of live) animation.currentTime = frame * 1_001 / 30;
+ }
+ const shown = elements.map((element) => element.pose === undefined ? element.style.opacity : String(element.pose));
+ return { materialized, live: live.size, positions, shown };
};
assert.deepEqual(await evaluate([{ start: 15, duration: 30 }], [30, 44, 15, 45, 60]), {
- pauses: 1,
- positions: [[0, 15, 29, 0]],
+ materialized: 1,
+ live: 0,
+ positions: [[15, 29, 0]],
+ shown: ["0"],
});
- assert.deepEqual(await evaluate([{ start: 15, duration: 30 }], [30]), { pauses: 1, positions: [[0, 15]] },
+ assert.deepEqual(await evaluate([{ start: 15, duration: 30 }], [30]), {
+ materialized: 1, live: 0, positions: [[15]], shown: ["15"],
+ },
"a fresh worker derives the same middle pose without visiting preceding frames");
+ assert.deepEqual(await evaluate([{ start: 30, duration: 60 }], [33, 60, 86]), {
+ materialized: 1,
+ live: 0,
+ positions: [[3, 30, 56]],
+ shown: ["56"],
+ }, "a Present starting after frame 0 keeps its Present-relative pose when HyperFrames seeks live animations");
assert.deepEqual(await evaluate([
{ start: 0, duration: 30 },
{ start: 90, duration: 30 },
], [100], [{ startFrame: 100, endFrameExclusive: 101 }]), {
- pauses: 1,
- positions: [[], [0, 10]],
+ materialized: 1,
+ live: 1,
+ positions: [[], [10]],
+ shown: ["100", "10"],
}, "a selected render does not materialize animations from unrelated Presents");
assert.deepEqual(await evaluate([
{ start: 0, duration: 5 },
@@ -378,18 +475,20 @@ test("HyperFrames emits compact absolute-frame animation without creating a Trac
{ start: 3, duration: 5 },
{ start: 100, duration: 2 },
], [0, 3, 4, 5, 7, 8, 100, 101, 102, 6]), {
- pauses: 4,
+ materialized: 4,
+ live: 0,
positions: [
- [0, 0, 3, 4],
- [0, 0, 2, 3, 1],
- [0, 0, 1, 2, 4, 3],
- [0, 0, 1],
+ [0, 3, 4],
+ [0, 2, 3, 1],
+ [0, 1, 2, 4, 3],
+ [0, 1],
],
+ shown: ["4", "1", "3", "1"],
}, "the point index preserves overlap, half-open boundaries, distant spans and reverse seeks");
});
test("HyperFrames clips a long animation by Present visibility instead of rejecting it", () => {
- const { composition, programSpace } = fixture();
+ const { composition, timeline } = fixture();
const lower = composition.tracks.find((track) => track.id === "lower");
assert(lower?.kind === "visual");
const present = lower.presents[0]!;
@@ -403,7 +502,7 @@ test("HyperFrames clips a long animation by Present visibility instead of reject
const document = compileHyperframesDocument(sealComposition({
...composition,
tracks: composition.tracks.map((track) => track.id === "lower" ? animated : track),
- }), programSpace);
+ }), timeline);
assert.match(document.html, /animation-duration:1\.5015s/u);
assert.match(document.html, /data-hypit-animation-sample-frames="30"/u);
assert.doesNotMatch(document.html, /data-hypit-animation-properties|data-hypit-animation-duration-frames/u);
@@ -411,8 +510,7 @@ test("HyperFrames clips a long animation by Present visibility instead of reject
});
test("content-bound fonts and typed compositable Surfaces cross the same Artifact boundary", () => {
- const space = sealProgramSpace({ id: "test-space", durationSec: 1,
- frameRate: { numerator: 30, denominator: 1 },
+ const space = sealTimeline({ id: "test-space", frameCount: 30, frameRate: { numerator: 30, denominator: 1 },
});
const font: FontArtifactRef = {
sources: [{ artifact: {
@@ -425,13 +523,14 @@ test("content-bound fonts and typed compositable Surfaces cross the same Artifac
style: "normal",
};
const surfaceDigest = fixtureResource("hyperframes:alpha-surface");
- const track = sealVisualTrack({ programSpaceId: "test-space",
+ const track = sealVisualTrack({ timelineId: "test-space",
visualIr: "hypit.visual-ir@1",
id: "bound-render-dependencies",
presents: [{
id: "bound",
+ order: 0,
+ z: 1,
span: { startFrame: 0, endFrameExclusive: 30 },
- stacking: { order: 1, tieBreak: "bound" },
elements: [
{ id: "root", order: 0, kind: "box", style: [] },
{
@@ -460,6 +559,15 @@ test("content-bound fonts and typed compositable Surfaces cross the same Artifac
frameCount: 30,
},
},
+ sourceTime: {
+ sourceFrameRate: { numerator: 30, denominator: 1 },
+ sourceFrameCount: 30,
+ pieces: [{
+ target: { startFrame: 0, endFrameExclusive: 30 },
+ sourceAtStart: { numerator: 0, denominator: 1 },
+ rate: { numerator: 1, denominator: 1 },
+ }],
+ },
style: [{ name: "position", value: "absolute" }, { name: "inset", value: 0 }],
},
],
@@ -489,8 +597,7 @@ test("content-bound fonts and typed compositable Surfaces cross the same Artifac
});
test("exact timed sampling keeps a held frame as one compact interval without zero-rate browser media", () => {
- const programSpace = sealProgramSpace({ id: "test-space", durationSec: 8 / 30,
- frameRate: { numerator: 30, denominator: 1 },
+ const timeline = sealTimeline({ id: "test-space", frameCount: 8, frameRate: { numerator: 30, denominator: 1 },
});
const artifact = {
kind: "blob" as const,
@@ -498,32 +605,33 @@ test("exact timed sampling keeps a held frame as one compact interval without ze
size: 1_000,
mediaType: "video/mp4",
};
- const track = sealVisualTrack({ programSpaceId: "test-space",
+ const track = sealVisualTrack({ timelineId: "test-space",
visualIr: "hypit.visual-ir@1",
id: "sampled",
presents: [{
id: "sampled",
+ order: 0,
+ z: 1,
span: { startFrame: 0, endFrameExclusive: 8 },
- stacking: { order: 1, tieBreak: "sampled" },
elements: [{
id: "video",
order: 0,
kind: "video",
artifact,
muted: true,
- sampling: {
+ sourceTime: {
sourceFrameRate: { numerator: 30, denominator: 1 },
sourceFrameCount: 4,
- segments: [
+ pieces: [
{
target: { startFrame: 0, endFrameExclusive: 6 },
- sourceFrame: { numerator: 2, denominator: 1 },
+ sourceAtStart: { numerator: 2, denominator: 1 },
rate: { numerator: 1, denominator: 1 },
- loop: { startFrame: 0, endFrameExclusive: 4 },
+ wrap: { startFrame: 0, endFrameExclusive: 4 },
},
{
target: { startFrame: 6, endFrameExclusive: 8 },
- sourceFrame: { numerator: 3, denominator: 1 },
+ sourceAtStart: { numerator: 3, denominator: 1 },
rate: { numerator: 0, denominator: 1 },
},
],
@@ -536,7 +644,7 @@ test("exact timed sampling keeps a held frame as one compact interval without ze
id: "sampled",
canvas: { width: 100, height: 100, clearColor: "#000000" },
tracks: [track],
- }), programSpace);
+ }), timeline);
assert.equal((document.html.match(/data-hypit-sampling-part=/gu) ?? []).length, 3);
assert.match(document.html, /data-media-start="0\.066666666666"/u);
assert.match(document.html, /data-media-start="0"/u);
@@ -557,16 +665,16 @@ test("a Track naming five takes still lowers to DOM identities a Windows path ca
const trackId = "speech-visual:opening-monologue-take-1+opening-monologue-take-2"
+ "+opening-monologue-take-3+opening-monologue-take-4+opening-monologue-take-5";
const presentId = `${trackId}:clip-1`;
- const programSpace = sealProgramSpace({ id: "test-space", durationSec: 8 / 30,
- frameRate: { numerator: 30, denominator: 1 },
+ const timeline = sealTimeline({ id: "test-space", frameCount: 8, frameRate: { numerator: 30, denominator: 1 },
});
- const track = sealVisualTrack({ programSpaceId: "test-space",
+ const track = sealVisualTrack({ timelineId: "test-space",
visualIr: "hypit.visual-ir@1",
id: trackId,
presents: [{
id: presentId,
+ order: 0,
+ z: 1,
span: { startFrame: 0, endFrameExclusive: 8 },
- stacking: { order: 1, tieBreak: presentId },
elements: [{
id: `${presentId}:foreground`,
order: 0,
@@ -579,18 +687,18 @@ test("a Track naming five takes still lowers to DOM identities a Windows path ca
},
muted: true,
// Sampling is what splits the element into parts, and each part appends its own suffix.
- sampling: {
+ sourceTime: {
sourceFrameRate: { numerator: 30, denominator: 1 },
sourceFrameCount: 8,
- segments: [
+ pieces: [
{
target: { startFrame: 0, endFrameExclusive: 4 },
- sourceFrame: { numerator: 0, denominator: 1 },
+ sourceAtStart: { numerator: 0, denominator: 1 },
rate: { numerator: 1, denominator: 1 },
},
{
target: { startFrame: 4, endFrameExclusive: 8 },
- sourceFrame: { numerator: 4, denominator: 1 },
+ sourceAtStart: { numerator: 4, denominator: 1 },
rate: { numerator: 1, denominator: 1 },
},
],
@@ -603,7 +711,7 @@ test("a Track naming five takes still lowers to DOM identities a Windows path ca
id: "long-identity",
canvas: { width: 100, height: 100, clearColor: "#000000" },
tracks: [track],
- }), programSpace);
+ }), timeline);
// The `id` attribute only; `data-hypit-element-id` and friends are meant to stay readable.
const identities = [...document.html.matchAll(/\sid="([^"]*)"/gu)].map((match) => match[1]!);
@@ -617,18 +725,18 @@ test("a Track naming five takes still lowers to DOM identities a Windows path ca
test("browser programs own local HTML while retaining typed child resources and format boundaries", async () => {
const { browserProgram } = await import("../src/browser-program.js");
- const { programSpace, picture } = fixture();
+ const { timeline, picture } = fixture();
const opaqueArtifact = { kind: "blob" as const, resource: fixtureResource("hyperframes:opaque-program"),
size: 12, mediaType: "image/png" };
- const visual = sealVisualTrack({ id: "scene", programSpaceId: programSpace.id, visualIr: VISUAL_IR_V1,
- presents: [{ id: "scene", span: { startFrame: 0, endFrameExclusive: 30 }, stacking: { order: 0, tieBreak: "scene" },
+ const visual = sealVisualTrack({ id: "scene", timelineId: timeline.id, visualIr: VISUAL_IR_V1,
+ presents: [{ id: "scene", order: 0, z: 0, span: { startFrame: 0, endFrameExclusive: 30 },
elements: [{ id: "root", kind: "program", order: 0, style: [], program: browserProgram({
html: `<section class="viewport">{{photo}}<img class="opaque" src="hypit-resource://${opaqueArtifact.resource}"><svg><path d="M0 0H20"/></svg></section>`,
css: '.viewport { backdrop-filter:blur(4px); display:grid; }',
setup: 'return frame => { root.dataset.frame = String(frame); };',
}, [opaqueArtifact]) }, { id: "photo", parent: "root", kind: "image", order: 1, artifact: picture, style: [] }] }] });
const composition = sealComposition({ id: "scene", canvas: { width: 200, height: 200, clearColor: "#000000" }, tracks: [visual] });
- const document = compileHyperframesDocument(composition, programSpace);
+ const document = compileHyperframesDocument(composition, timeline);
assert.equal(document.artifacts.length, 2);
assert.deepEqual(document.artifacts.find(({ artifact }) => artifact.resource === opaqueArtifact.resource)?.usage,
{ kind: "always" }, "opaque Browser Program dependencies remain conservative");
@@ -645,7 +753,7 @@ test("browser programs own local HTML while retaining typed child resources and
if (root.kind !== "visual" || root.presents[0]!.elements[0]!.kind !== "program") throw new Error("fixture");
const program = root.presents[0]!.elements[0]!.program;
(program as { format: string }).format = "another.renderer@1";
- assert.throws(() => compileHyperframesDocument(missing, programSpace), /does not support visual program format/);
+ assert.throws(() => compileHyperframesDocument(missing, timeline), /does not support visual program format/);
});
test("browser program state follows direct seeks and reports authored evaluation failures", async () => {
diff --git a/packages/hyperframes/test/project.test.ts b/packages/hyperframes/test/project.test.ts
index fee71a94..bb4acbd4 100644
--- a/packages/hyperframes/test/project.test.ts
+++ b/packages/hyperframes/test/project.test.ts
@@ -8,16 +8,15 @@ import { compileHyperframesDocument } from "../src/document.js";
import { browserProgram } from "../src/browser-program.js";
import { stageHyperframesHtmlProject, stageHyperframesProject } from "../src/project.js";
import { sealComposition, sealVisualTrack } from "@hypit/composition";
-import { sealProgramSpace } from "@hypit/program-space";
+import { sealTimeline } from "@hypit/timeline";
test("typed Surface inspection borrows the completed streamed file used by capture", async () => {
const surface = { artifact: { kind: "blob" as const, resource: "res_streamed-surface" as const,
size: 6, mediaType: "image/png" }, width: 1, height: 1, colorSpace: "srgb" as const,
alphaMode: "straight" as const, timing: { kind: "still" as const } };
- const space = sealProgramSpace({ id: "space", durationSec: 1,
- frameRate: { numerator: 30, denominator: 1 } });
- const track = sealVisualTrack({ id: "surface", visualIr: "hypit.visual-ir@1", programSpaceId: space.id,
- presents: [{ id: "surface", span: { startFrame: 0, endFrameExclusive: 30 }, stacking: { order: 0, tieBreak: "surface" },
+ const space = sealTimeline({ id: "space", frameCount: 30, frameRate: { numerator: 30, denominator: 1 } });
+ const track = sealVisualTrack({ id: "surface", visualIr: "hypit.visual-ir@1", timelineId: space.id,
+ presents: [{ id: "surface", order: 0, z: 0, span: { startFrame: 0, endFrameExclusive: 30 },
elements: [{ id: "surface", kind: "surface", surface, order: 0, style: [] }] }] });
const document = compileHyperframesDocument(sealComposition({ id: "main",
canvas: { width: 64, height: 64, clearColor: "#000000" }, tracks: [track] }), space);
@@ -46,10 +45,9 @@ test("typed Surface inspection borrows the completed streamed file used by captu
});
test("staging cancels and joins sibling reads before exposing a failure", async () => {
- const space = sealProgramSpace({ id: "space", durationSec: 1,
- frameRate: { numerator: 30, denominator: 1 } });
- const track = sealVisualTrack({ id: "images", visualIr: "hypit.visual-ir@1", programSpaceId: space.id,
- presents: ["a", "b", "c", "d"].map((id, order) => ({ id, span: { startFrame: 0, endFrameExclusive: 30 }, stacking: { order, tieBreak: id },
+ const space = sealTimeline({ id: "space", frameCount: 30, frameRate: { numerator: 30, denominator: 1 } });
+ const track = sealVisualTrack({ id: "images", visualIr: "hypit.visual-ir@1", timelineId: space.id,
+ presents: ["a", "b", "c", "d"].map((id, order) => ({ id, order, z: order, span: { startFrame: 0, endFrameExclusive: 30 },
elements: [{ id, order: 0, kind: "image" as const, style: [],
artifact: { kind: "blob" as const, resource: `res_${id}` as const, size: 1, mediaType: "image/png" } }],
})) });
@@ -73,12 +71,11 @@ test("staging cancels and joins sibling reads before exposing a failure", async
});
test("document staging bounds complete Artifact lifecycles without changing deterministic paths", async () => {
- const space = sealProgramSpace({ id: "space", durationSec: 1,
- frameRate: { numerator: 30, denominator: 1 } });
+ const space = sealTimeline({ id: "space", frameCount: 30, frameRate: { numerator: 30, denominator: 1 } });
const ids = Array.from({ length: 12 }, (_, index) => String(index).padStart(2, "0"));
- const track = sealVisualTrack({ id: "images", visualIr: "hypit.visual-ir@1", programSpaceId: space.id,
- presents: ids.map((id, order) => ({ id, span: { startFrame: 0, endFrameExclusive: 30 },
- stacking: { order, tieBreak: id }, elements: [{ id, order: 0, kind: "image" as const, style: [],
+ const track = sealVisualTrack({ id: "images", visualIr: "hypit.visual-ir@1", timelineId: space.id,
+ presents: ids.map((id, order) => ({ id, order, z: order, span: { startFrame: 0, endFrameExclusive: 30 },
+ elements: [{ id, order: 0, kind: "image" as const, style: [],
artifact: { kind: "blob" as const, resource: `res_${id}` as const, size: 1, mediaType: "image/png" } }],
})) });
const document = compileHyperframesDocument(sealComposition({ id: "main",
@@ -107,19 +104,19 @@ test("document staging bounds complete Artifact lifecycles without changing dete
});
test("document staging reads only Artifacts whose compiler usage overlaps the whole render selection", async () => {
- const space = sealProgramSpace({ id: "space", durationSec: 1, frameRate: { numerator: 30, denominator: 1 } });
+ const space = sealTimeline({ id: "space", frameCount: 30, frameRate: { numerator: 30, denominator: 1 } });
const first = { kind: "blob" as const, resource: "res_first-selection" as const, size: 1, mediaType: "image/png" };
const late = { kind: "blob" as const, resource: "res_late-selection" as const, size: 1, mediaType: "image/png" };
const always = { kind: "blob" as const, resource: "res_always-selection" as const, size: 1, mediaType: "image/png" };
- const track = sealVisualTrack({ id: "images", visualIr: "hypit.visual-ir@1", programSpaceId: space.id,
+ const track = sealVisualTrack({ id: "images", visualIr: "hypit.visual-ir@1", timelineId: space.id,
presents: [
- { id: "first-a", span: { startFrame: 0, endFrameExclusive: 5 }, stacking: { order: 0, tieBreak: "a" },
+ { id: "first-a", order: 0, z: 0, span: { startFrame: 0, endFrameExclusive: 5 },
elements: [{ id: "first-a", order: 0, kind: "image" as const, style: [], artifact: first }] },
- { id: "first-b", span: { startFrame: 5, endFrameExclusive: 10 }, stacking: { order: 1, tieBreak: "b" },
+ { id: "first-b", order: 1, z: 1, span: { startFrame: 5, endFrameExclusive: 10 },
elements: [{ id: "first-b", order: 0, kind: "image" as const, style: [], artifact: first }] },
- { id: "late", span: { startFrame: 20, endFrameExclusive: 30 }, stacking: { order: 2, tieBreak: "late" },
+ { id: "late", order: 2, z: 2, span: { startFrame: 20, endFrameExclusive: 30 },
elements: [{ id: "late", order: 0, kind: "image" as const, style: [], artifact: late }] },
- { id: "opaque", span: { startFrame: 20, endFrameExclusive: 30 }, stacking: { order: 3, tieBreak: "opaque" },
+ { id: "opaque", order: 3, z: 3, span: { startFrame: 20, endFrameExclusive: 30 },
elements: [{ id: "opaque", order: 0, kind: "program" as const, style: [],
program: browserProgram({ html: `<img src="hypit-resource://${always.resource}">` }, [always]) }] },
] });
@@ -143,25 +140,25 @@ test("document staging reads only Artifacts whose compiler usage overlaps the wh
});
test("document staging rejects an invalid concurrency bound", async () => {
- const { composition, programSpace } = (() => {
- const programSpace = sealProgramSpace({ id: "space", durationSec: 1, frameRate: { numerator: 30, denominator: 1 } });
- return { programSpace, composition: sealComposition({ id: "empty",
+ const { composition, timeline } = (() => {
+ const timeline = sealTimeline({ id: "space", frameCount: 30, frameRate: { numerator: 30, denominator: 1 } });
+ return { timeline, composition: sealComposition({ id: "empty",
canvas: { width: 64, height: 64, clearColor: "#000000" }, tracks: [] }) };
})();
const directory = await mkdtemp(join(tmpdir(), "hypit-stage-invalid-bound-"));
try {
await assert.rejects(stageHyperframesProject({
- document: compileHyperframesDocument(composition, programSpace), directory,
+ document: compileHyperframesDocument(composition, timeline), directory,
maxConcurrentArtifacts: 0, read: async () => new Uint8Array(),
}), /concurrency must be a positive safe integer/u);
} finally { await rm(directory, { recursive: true, force: true }); }
});
test("document staging drains readers and preserves an external cancellation reason", async () => {
- const space = sealProgramSpace({ id: "space", durationSec: 1, frameRate: { numerator: 30, denominator: 1 } });
- const track = sealVisualTrack({ id: "images", visualIr: "hypit.visual-ir@1", programSpaceId: space.id,
- presents: ["a", "b"].map((id, order) => ({ id, span: { startFrame: 0, endFrameExclusive: 30 },
- stacking: { order, tieBreak: id }, elements: [{ id, order: 0, kind: "image" as const, style: [],
+ const space = sealTimeline({ id: "space", frameCount: 30, frameRate: { numerator: 30, denominator: 1 } });
+ const track = sealVisualTrack({ id: "images", visualIr: "hypit.visual-ir@1", timelineId: space.id,
+ presents: ["a", "b"].map((id, order) => ({ id, order, z: order, span: { startFrame: 0, endFrameExclusive: 30 },
+ elements: [{ id, order: 0, kind: "image" as const, style: [],
artifact: { kind: "blob" as const, resource: `res_${id}` as const, size: 1, mediaType: "image/png" } }],
})) });
const document = compileHyperframesDocument(sealComposition({ id: "main",
@@ -190,9 +187,9 @@ test("document staging drains readers and preserves an external cancellation rea
test("staging gives opaque Resource identities portable local names and writes complete streams", async () => {
const resource = `res_${"x".repeat(247)}:img` as const;
- const space = sealProgramSpace({ id: "space", durationSec: 1, frameRate: { numerator: 30, denominator: 1 } });
- const track = sealVisualTrack({ id: "image", visualIr: "hypit.visual-ir@1", programSpaceId: space.id,
- presents: [{ id: "image", span: { startFrame: 0, endFrameExclusive: 30 }, stacking: { order: 0, tieBreak: "image" },
+ const space = sealTimeline({ id: "space", frameCount: 30, frameRate: { numerator: 30, denominator: 1 } });
+ const track = sealVisualTrack({ id: "image", visualIr: "hypit.visual-ir@1", timelineId: space.id,
+ presents: [{ id: "image", order: 0, z: 0, span: { startFrame: 0, endFrameExclusive: 30 },
elements: [{ id: "image", kind: "image", order: 0, style: [],
artifact: { kind: "blob", resource, size: 5, mediaType: "image/png" } }] }] });
const document = compileHyperframesDocument(sealComposition({ id: "main", canvas: { width: 64, height: 64, clearColor: "#000000" }, tracks: [track] }), space);
diff --git a/packages/image-compose/README.md b/packages/image-compose/README.md
index 2922c8e8..0d2f674c 100644
--- a/packages/image-compose/README.md
+++ b/packages/image-compose/README.md
@@ -9,12 +9,12 @@ The author graph supplies an explicit Canvas, an ordered list of image Layers, a
<import as="compose" from="@hypit/image-compose@1"/>
<space:Canvas id="comparison-canvas" width="2048" height="1024"/>
-<space:Frame id="before-panel" within={comparison-canvas}
+<space:Frame id="before-panel" within={comparison-canvas.bounds}
left="0%" top="0%" right="50%" bottom="100%"/>
-<space:Frame id="after-panel" within={comparison-canvas}
+<space:Frame id="after-panel" within={comparison-canvas.bounds}
left="50%" top="0%" right="100%" bottom="100%"/>
-<compose:Image id="comparison" canvas={comparison-canvas} background="#EEEAE2FF">
+<compose:Image id="comparison" canvas={comparison-canvas.canvas} background="#EEEAE2FF">
<compose:Layer source={before.image} frame={before-panel} fit="contain"/>
<compose:Layer source={after.image} frame={after-panel} fit="contain"/>
</compose:Image>
diff --git a/packages/image-compose/src/component.ts b/packages/image-compose/src/component.ts
index a79e0378..cf7c43dc 100644
--- a/packages/image-compose/src/component.ts
+++ b/packages/image-compose/src/component.ts
@@ -4,7 +4,7 @@ import type { BlobRef, CanonicalValue, StoredValue } from "@hypit/protocol";
import { canonicalize } from "@hypit/protocol";
import { rasterComposeRequest } from "@hypit/raster";
import { rasterCapabilities } from "@hypit/raster";
-import type { CanvasSpace, SpatialFrame } from "@hypit/spatial";
+import type { Canvas, SpatialFrame } from "@hypit/spatial";
import { imageComposeProducers, imageComposeTypes } from "./manifest.js";
import {
@@ -44,7 +44,7 @@ export const imageComposeComponent = {
}, {
producer: imageComposeProducers.request,
handler: ({ inputs }: ProducerHandlerContext) => {
- const canvas = inline<CanvasSpace>(inputs.canvas?.value, "CanvasSpace");
+ const canvas = inline<Canvas>(inputs.canvas?.value, "Canvas");
const options = inline<ImageComposeOptions>(inputs.options?.value, "ImageComposeOptions");
const set = inline<ImageComposeLayerSet>(inputs.layers?.value, "ImageComposeLayerSet");
return { outputs: {}, needs: { image: rasterComposeRequest({
diff --git a/packages/image-compose/src/manifest.ts b/packages/image-compose/src/manifest.ts
index 19a53892..2d3ba0dc 100644
--- a/packages/image-compose/src/manifest.ts
+++ b/packages/image-compose/src/manifest.ts
@@ -78,7 +78,7 @@ export const imageComposeMarkupSurfaces = [{
{ name: "image", type: artifactTypes.blob,
summary: "The composed picture, a PNG." },
],
- example: `<compose:Image id="comparison" canvas={comparison-canvas} background="#EEEAE2FF">
+ example: `<compose:Image id="comparison" canvas={comparison-canvas.canvas} background="#EEEAE2FF">
<compose:Layer source={before.image} frame={before-panel} fit="contain"/>
<compose:Layer source={after.image} frame={after-panel} fit="contain"/>
</compose:Image>`,
diff --git a/packages/image-compose/test/image-compose.test.ts b/packages/image-compose/test/image-compose.test.ts
index b8dafd74..fd904a0c 100644
--- a/packages/image-compose/test/image-compose.test.ts
+++ b/packages/image-compose/test/image-compose.test.ts
@@ -14,11 +14,10 @@ import {
} from "@hypit/image-compose";
import { rasterCapabilities } from "@hypit/raster";
import type { CanonicalValue, StoredValue, TypeRef, TypedRecord } from "@hypit/protocol";
-import { sealCanvasSpace, sealSpatialFrame, spatialTypes } from "@hypit/spatial";
+import { sealCanvas, sealSpatialFrame, spatialTypes } from "@hypit/spatial";
-const canvas = sealCanvasSpace({
+const canvas = sealCanvas({
widthPx: 1080, heightPx: 1920,
- origin: "top-left", xDirection: "right", yDirection: "down", pixelAspect: "square",
});
const frame = sealSpatialFrame({ xPx: -10, yPx: 20, widthPx: 500, heightPx: 400 });
const options = sealImageComposeOptions({ background: "#11223344" });
diff --git a/packages/interview-emoji-reveal/README.md b/packages/interview-emoji-reveal/README.md
index f800b148..3e83cd60 100644
--- a/packages/interview-emoji-reveal/README.md
+++ b/packages/interview-emoji-reveal/README.md
@@ -1,15 +1,14 @@
# Emoji Reveal
-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.
+The EmojiReveal Surface accepts one completed Timeline, an absolute outer Window and absolute reveal
+Instants. A Narrative or other domain projector may publish those values upstream.
Reusable Hypit author vocabulary for a top-of-frame icon answer strip.
The strip owns one outer projected `TemporalWindow`. An Item is either preset from the first frame or
-accepts one authored Script `Moment`, projected outside this package to a traced `TemporalInstant`.
+accepts one resolved `TemporalInstant`.
Display order is source order: preset Items come first, then revealed Items in strict chronological
-order. The Track receives one placeholder image and every Item receives one answer image: `n` answers
+order. The EmojiReveal receives one placeholder image and every Item receives one answer image: `n` answers
therefore have exactly `n + 1` explicit image inputs. A Moment replaces only its own slot, so earlier
answers remain and later slots remain unanswered.
@@ -21,17 +20,17 @@ answers remain and later slots remain unanswered.
<emoji:Style id="emoji-strip" recipe={styles.emoji-strip}/>
-<emoji:Track id="rules" timeline={speech.timeline} canvas={vertical}
- style={emoji-strip} placeholder={question-icon} during="program">
+<emoji:EmojiReveal id="rules" timeline={speech.timeline} within={vertical.bounds}
+ style={emoji-strip} placeholder={question-icon} during="timeline">
<emoji:Item id="manifest" icon={manifest-icon} preset="true"/>
- <emoji:Item id="real-estate" icon={real-estate-icon} at={story.moment.real-estate}/>
- <emoji:Item id="bitcoin" icon={bitcoin-icon} at={story.moment.bitcoin}/>
-</emoji:Track>
+ <emoji:Item id="real-estate" icon={real-estate-icon} at={story-time.real-estate}/>
+ <emoji:Item id="bitcoin" icon={bitcoin-icon} at={story-time.bitcoin}/>
+</emoji:EmojiReveal>
```
-`Selection`, `Segment`, numeric instants and a `boundary` fallback are deliberately not part of an
-Item's vocabulary. The component consumes the shared `Timeline`, the projected outer Window and the
-projected Instants; it does not interpret Script semantics itself and has no Studio dependency.
+`Selection`, `Segment` and a `boundary` fallback are deliberately not part of an Item's vocabulary.
+The component consumes the shared `Timeline`, the outer Window and resolved Instants; it does not
+interpret Script semantics itself and has no Studio dependency.
The bundled preview icons come from [Tabler Icons](https://tabler.io/icons), distributed under the
MIT license and retrieved through the Iconify API. Their SVG files are the design sources and are
diff --git a/packages/interview-emoji-reveal/package.json b/packages/interview-emoji-reveal/package.json
index 2b395123..1373c8aa 100644
--- a/packages/interview-emoji-reveal/package.json
+++ b/packages/interview-emoji-reveal/package.json
@@ -3,16 +3,18 @@
"version": "0.0.0-dev",
"private": true,
"type": "module",
- "exports": { ".": "./src/index.ts" },
- "hypit": { "activation": "./src/activation.ts" },
+ "exports": {
+ ".": "./src/index.ts"
+ },
+ "hypit": {
+ "activation": "./src/activation.ts"
+ },
"dependencies": {
"@hypit/artifact": "workspace:*",
"@hypit/component-kit": "workspace:*",
"@hypit/composition": "workspace:*",
"@hypit/elaborator": "workspace:*",
"@hypit/markup": "workspace:*",
- "@hypit/narrative": "workspace:*",
- "@hypit/program-space": "workspace:*",
"@hypit/protocol": "workspace:*",
"@hypit/timeline": "workspace:*",
"@hypit/spatial": "workspace:*",
diff --git a/packages/interview-emoji-reveal/src/activation.ts b/packages/interview-emoji-reveal/src/activation.ts
index dc0265ae..9a1caabe 100644
--- a/packages/interview-emoji-reveal/src/activation.ts
+++ b/packages/interview-emoji-reveal/src/activation.ts
@@ -8,7 +8,7 @@ export const hypitPackage = {
modules: [{ manifest: emojiRevealManifest }], components: [emojiRevealComponent],
hostFacets: [
createMarkupSurfaceHostFacet({ module: emojiRevealModuleRef, declaration: emojiRevealMarkupSurfaces.find((item) => item.name === "style")!, handler: decodeEmojiRevealStyleSurface }),
- createMarkupSurfaceHostFacet({ module: emojiRevealModuleRef, declaration: emojiRevealMarkupSurfaces.find((item) => item.name === "track")!, handler: decodeEmojiRevealTrackSurface }),
+ createMarkupSurfaceHostFacet({ module: emojiRevealModuleRef, declaration: emojiRevealMarkupSurfaces.find((item) => item.name === "emojiReveal")!, handler: decodeEmojiRevealTrackSurface }),
],
};
export default hypitPackage;
diff --git a/packages/interview-emoji-reveal/src/component.ts b/packages/interview-emoji-reveal/src/component.ts
index 7f154d00..476dfda5 100644
--- a/packages/interview-emoji-reveal/src/component.ts
+++ b/packages/interview-emoji-reveal/src/component.ts
@@ -2,7 +2,7 @@ import type { Timeline } from "@hypit/timeline";
import type { ComponentPackage } from "@hypit/component-kit";
import { canonicalize } from "@hypit/protocol";
import type { BlobRef, StoredValue } from "@hypit/protocol";
-import type { CanvasSpace } from "@hypit/spatial";
+import type { SpatialFrame } from "@hypit/spatial";
import type { TemporalInstant, TemporalWindow } from "@hypit/temporal";
import { emojiRevealProducers, emojiRevealTypes } from "./manifest.js";
@@ -37,7 +37,7 @@ export const emojiRevealComponent = {
blob(inputs.placeholder?.value, "Emoji Reveal placeholder"), inline<EmojiRevealSet>(inputs.set?.value, "EmojiRevealSet"),
)) }, needs: {} }) },
{ producer: emojiRevealProducers.render, handler: ({ inputs }) => ({ outputs: { track: output(renderEmojiReveal(
- inline<CanvasSpace>(inputs.canvas?.value, "CanvasSpace"), inline<Timeline>(inputs.timeline?.value, "Timeline"),
+ inline<SpatialFrame>(inputs.within?.value, "SpatialFrame"), inline<Timeline>(inputs.timeline?.value, "Timeline"),
inline<EmojiRevealProgram>(inputs.program?.value, "EmojiRevealProgram"),
)) }, needs: {} }) },
],
diff --git a/packages/interview-emoji-reveal/src/fragment.ts b/packages/interview-emoji-reveal/src/fragment.ts
index 8849e8b4..28631747 100644
--- a/packages/interview-emoji-reveal/src/fragment.ts
+++ b/packages/interview-emoji-reveal/src/fragment.ts
@@ -41,13 +41,13 @@ export function createEmojiRevealFragment(items: readonly EmojiRevealFragmentIte
placeholder: input("placeholder"), set: operation(current),
}, result: { kind: "output", name: "program" } },
{ id: "emoji:track", producer: emojiRevealProducers.render, inputs: {
- canvas: input("canvas"), timeline: input("timeline"), program: operation("emoji:program"),
+ within: input("within"), timeline: input("timeline"), program: operation("emoji:program"),
}, result: { kind: "output", name: "track" } },
);
return sealGraphFragment({
inputs: [
{ name: "header", type: emojiRevealTypes.header }, { name: "timeline", type: timelineTypes.track },
- { name: "canvas", type: spatialTypes.canvas }, { name: "outer", type: temporalTypes.window }, { name: "style", type: emojiRevealTypes.style },
+ { name: "within", type: spatialTypes.frame }, { name: "outer", type: temporalTypes.window }, { name: "style", type: emojiRevealTypes.style },
{ name: "placeholder", type: artifactTypes.blob },
...items.flatMap((item) => [
{ name: item.specName, type: emojiRevealTypes.itemSpec }, { name: item.iconName, type: artifactTypes.blob },
@@ -57,7 +57,7 @@ export function createEmojiRevealFragment(items: readonly EmojiRevealFragmentIte
operations,
exports: [
{ name: "program", type: emojiRevealTypes.program, root: operation("emoji:program") },
- { name: "track", type: compositionTypes.visualTrack, root: operation("emoji:track") },
+ { name: "visual", type: compositionTypes.visualTrack, root: operation("emoji:track") },
],
});
}
diff --git a/packages/interview-emoji-reveal/src/manifest.ts b/packages/interview-emoji-reveal/src/manifest.ts
index 4f163bda..7e875d90 100644
--- a/packages/interview-emoji-reveal/src/manifest.ts
+++ b/packages/interview-emoji-reveal/src/manifest.ts
@@ -1,13 +1,11 @@
-import { timelineTypes } from "@hypit/timeline";
+import { timelineTypes, timelineDependency } from "@hypit/timeline";
import { temporalContextAttributeVocabulary } from "@hypit/temporal-markup";
import { readFile } from "node:fs/promises";
import { artifactDependency, artifactTypes } from "@hypit/artifact";
import { compositionDependency, compositionTypes } from "@hypit/composition";
-import { narrativeDependency, narrativeTypes } from "@hypit/narrative";
import type { ModuleManifest, ProducerRef, TypeRef, ValueSchema } from "@hypit/protocol";
-import { timelineDependency } from "@hypit/timeline";
import { spatialDependency, spatialTypes } from "@hypit/spatial";
import { svsRecipeType } from "@hypit/svs";
import { temporalDependency, temporalInstantSchema, temporalTypes, temporalWindowSchema } from "@hypit/temporal";
@@ -71,14 +69,14 @@ export const emojiRevealSetSchema: ValueSchema = object({
items: { schema: { kind: "array", items: emojiRevealItemSchema } },
});
export const emojiRevealProgramSchema: ValueSchema = object({
- id: { schema: string }, programSpaceId: { schema: string }, outer: { schema: temporalWindowSchema },
+ id: { schema: string }, timelineId: { schema: string }, outer: { schema: temporalWindowSchema },
style: { schema: emojiRevealStyleSchema }, placeholder: { schema: blob },
items: { schema: { kind: "array", minItems: 1, items: emojiRevealItemSchema } },
});
const recipe = [
- ["center-x", "0.5", "Places the adaptive strip by its horizontal centre as a fraction of Canvas width."],
- ["top-y", "0.07", "Places the strip's top edge as a fraction of Canvas height."],
+ ["center-x", "0.5", "Places the adaptive strip by its horizontal centre as a fraction of the selected Frame's width."],
+ ["top-y", "0.07", "Places the strip's top edge as a fraction of the selected Frame's height."],
["slot-size", "72", "Sets the fixed width and height of each SVG slot in pixels."],
["slot-gap", "10", "Sets the gap between adjacent slots in pixels."],
["padding-x", "18", "Insets the first and last slots from the board's horizontal edges."],
@@ -110,16 +108,16 @@ export const emojiRevealMarkupSurfaces = [
example: `<emoji:Style id="emoji-strip" recipe={styles.emoji-strip}/>` ,
notes: ["The Style owns appearance and placement, but never event timing."],
} },
- { name: "track", tag: "Track", mode: "structured",
- outputs: [emojiRevealTypes.header, emojiRevealTypes.itemSpec, temporalTypes.instantSpec, temporalTypes.windowSpec, temporalTypes.instant, temporalTypes.window, emojiRevealTypes.program, compositionTypes.visualTrack],
+ { name: "emojiReveal", tag: "EmojiReveal", mode: "structured",
+ outputs: [emojiRevealTypes.header, emojiRevealTypes.itemSpec, temporalTypes.duration, temporalTypes.extent, temporalTypes.shiftSpec, temporalTypes.instantSpec, temporalTypes.windowSpec, temporalTypes.instant, temporalTypes.window, emojiRevealTypes.program, compositionTypes.visualTrack],
vocabulary: {
summary: "Draws one adaptive row of preset or progressively revealed icon slots.",
- appearance: "A compact rounded rectangle centered near the top of the frame, with a dark outline and a hard lower-right shadow. Its width is computed from the number of fixed-size slots. Preset slots are settled from the first frame. Every other slot starts with the same supplied placeholder icon, then its semantic Moment replaces that slot with a brief overshoot and settle while earlier answers remain visible and later slots remain unanswered.",
+ appearance: "A compact rounded rectangle centered near the top of the frame, with a dark outline and a hard lower-right shadow. Its width is computed from the number of fixed-size slots. Preset slots are settled from the first frame. Every other slot starts with the same supplied placeholder icon, then its activation Instant replaces that slot with a brief overshoot and settle while earlier answers remain visible and later slots remain unanswered.",
preview: previewImage("Track.png"),
attributes: [
- { name: "id", kind: "identifier", required: true, summary: "Names the reveal Program and Track." },
+ { name: "id", kind: "identifier", required: true, summary: "Names the reveal Program and its visual contribution." },
...temporalContextAttributeVocabulary,
- { name: "canvas", kind: "reference", required: true, accepts: [spatialTypes.canvas], summary: "Chooses the Canvas used for normalized top placement." },
+ { name: "within", kind: "reference", required: true, accepts: [spatialTypes.frame], summary: "Chooses the Frame used for normalized placement." },
{ name: "style", kind: "reference", required: true, accepts: [emojiRevealTypes.style], summary: "Chooses the strip Style." },
{ name: "placeholder", kind: "reference", required: true, accepts: [artifactTypes.blob], summary: "Supplies the one image drawn in every unrevealed slot." },
...temporalWindowAttributeVocabulary,
@@ -127,29 +125,29 @@ export const emojiRevealMarkupSurfaces = [
children: [{ tag: "Item", cardinality: "many", summary: "One answer slot, either settled from the start or revealed at one event.", attributes: [
{ name: "id", kind: "identifier", required: true, summary: "Names this answer slot and the timing subject it owns." },
{ name: "icon", kind: "reference", required: true, accepts: [artifactTypes.blob], summary: "Supplies this answer as an image Artifact from the same visual icon family as the placeholder." },
- { name: "preset", kind: "literal", required: false, values: ["true", "false"], summary: "Settles this Item from the start of the Track Window; preset Items have no at." },
- { name: "at", kind: "expression", required: false, accepts: [narrativeTypes.moment], summary: "Chooses this non-preset Item's reveal Moment or authored time, such as 2s or 12f; required unless preset is true." },
+ { name: "preset", kind: "literal", required: false, values: ["true", "false"], summary: "Settles this Item from the start of the EmojiReveal Window; preset Items have no at." },
+ { name: "at", kind: "expression", required: false, accepts: [temporalTypes.instant], summary: "Chooses this non-preset Item's resolved reveal Instant or authored absolute time; required unless preset is true." },
] }],
ports: [
- { name: "program", type: emojiRevealTypes.program, summary: "The adaptive strip with its projected outer Window and fully traced Moment activations." },
- { name: "track", type: compositionTypes.visualTrack, summary: "That Program rendered as an ordinary VisualTrack." },
+ { name: "program", type: emojiRevealTypes.program, summary: "The adaptive strip with its outer Window and fully traced activation Instants." },
+ { name: "visual", type: compositionTypes.visualTrack, summary: "That Program rendered as an ordinary VisualTrack." },
],
- example: `<emoji:Track id="rules" timeline={speech.timeline} canvas={vertical} style={emoji-strip} placeholder={question-icon} during="program">
+ example: `<emoji:EmojiReveal id="rules" timeline={speech.timeline} within={vertical.bounds} style={emoji-strip} placeholder={question-icon} during="timeline">
<emoji:Item id="manifest" icon={manifest-icon} preset="true"/>
- <emoji:Item id="real-estate" icon={real-estate-icon} at={story.moment.real-estate}/>
- <emoji:Item id="bitcoin" icon={bitcoin-icon} at={story.moment.bitcoin}/>
-</emoji:Track>`,
+ <emoji:Item id="real-estate" icon={real-estate-icon} at={story-time.real-estate}/>
+ <emoji:Item id="bitcoin" icon={bitcoin-icon} at={story-time.bitcoin}/>
+</emoji:EmojiReveal>`,
notes: [
"Item order is display order: preset Items come first, then non-preset Items in strict chronological reveal order.",
- "A non-preset Item.at chooses one reveal trigger: a Script Moment or an authored time. The answer then persists to the outer Window's end.",
- "The outer Track Window is separate from the child reveal Moments and uses the shared temporal Window protocol.",
+ "A non-preset Item.at chooses one resolved Instant or an authored absolute time. The answer then persists to the outer Window's end.",
+ "The outer EmojiReveal Window is separate from child reveal Instants and uses the shared temporal Window protocol.",
],
} },
] as const;
export const emojiRevealManifest: ModuleManifest = {
format: "hypit.module@1", name: emojiRevealModuleRef.name, version: emojiRevealModuleRef.version,
- dependencies: [artifactDependency, narrativeDependency, timelineDependency, spatialDependency, temporalDependency, compositionDependency],
+ dependencies: [artifactDependency, timelineDependency, spatialDependency, temporalDependency, compositionDependency],
types: [
{ name: emojiRevealTypes.header.name }, { name: emojiRevealTypes.style.name },
{ name: emojiRevealTypes.itemSpec.name }, { name: emojiRevealTypes.set.name }, { name: emojiRevealTypes.program.name },
@@ -167,7 +165,7 @@ export const emojiRevealManifest: ModuleManifest = {
inputs: [{ name: "header", type: emojiRevealTypes.header }, { name: "timeline", type: timelineTypes.track }, { name: "outer", type: temporalTypes.window }, { name: "style", type: emojiRevealTypes.style }, { name: "placeholder", type: artifactTypes.blob }, { name: "set", type: emojiRevealTypes.set }],
outputs: [{ name: "program", type: emojiRevealTypes.program }], needs: [] },
{ name: emojiRevealProducers.render.name,
- inputs: [{ name: "canvas", type: spatialTypes.canvas }, { name: "timeline", type: timelineTypes.track }, { name: "program", type: emojiRevealTypes.program }],
+ inputs: [{ name: "within", type: spatialTypes.frame }, { name: "timeline", type: timelineTypes.track }, { name: "program", type: emojiRevealTypes.program }],
outputs: [{ name: "track", type: compositionTypes.visualTrack }], needs: [] },
],
};
diff --git a/packages/interview-emoji-reveal/src/program.ts b/packages/interview-emoji-reveal/src/program.ts
index 77b7d901..b0f023e2 100644
--- a/packages/interview-emoji-reveal/src/program.ts
+++ b/packages/interview-emoji-reveal/src/program.ts
@@ -1,11 +1,11 @@
+import { assertTimelineIdentity } from "@hypit/timeline";
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 { canonicalize } from "@hypit/protocol";
import type { BlobRef } from "@hypit/protocol";
-import { assertCanvasSpace } from "@hypit/spatial";
-import type { CanvasSpace } from "@hypit/spatial";
+import { assertSpatialFrame } from "@hypit/spatial";
+import type { SpatialFrame } from "@hypit/spatial";
import { assertTemporalInstantFor, assertTemporalWindowFor } from "@hypit/temporal";
import type { TemporalInstant, TemporalWindow } from "@hypit/temporal";
@@ -68,10 +68,10 @@ export function assertEmojiRevealSet(value: EmojiRevealSet): void {
}
export function appendEmojiRevealItem(set: EmojiRevealSet, timeline: Timeline, spec: EmojiRevealItemSpec, icon: BlobRef, activation: TemporalInstant): EmojiRevealSet {
- assertEmojiRevealSet(set); assertProgramSpaceIdentity(timeline); assertEmojiRevealItemSpec(spec);
+ assertEmojiRevealSet(set); assertTimelineIdentity(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: timeline });
+ assertTemporalInstantFor(activation, { subjectId: spec.id, timeline: 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) }] };
}
@@ -87,9 +87,9 @@ export function appendPresetEmojiRevealItem(set: EmojiRevealSet, spec: EmojiReve
export function finalizeEmojiReveal(
header: EmojiRevealHeader, timeline: Timeline, outer: TemporalWindow, style: EmojiRevealStyle, placeholder: BlobRef, set: EmojiRevealSet,
): EmojiRevealProgram {
- assertEmojiRevealHeader(header); assertProgramSpaceIdentity(timeline); assertEmojiRevealStyle(style); assertEmojiRevealSet(set);
+ assertEmojiRevealHeader(header); assertTimelineIdentity(timeline); assertEmojiRevealStyle(style); assertEmojiRevealSet(set);
assertIconImage(placeholder, "Emoji Reveal placeholder");
- assertTemporalWindowFor(outer, { subjectId: header.id, space: timeline });
+ assertTemporalWindowFor(outer, { subjectId: header.id, timeline: timeline });
assert(set.items.length > 0, "Emoji Reveal requires at least one Item.");
let previous = outer.span.startFrame - 1;
let revealStarted = false;
@@ -101,12 +101,12 @@ export function finalizeEmojiReveal(
revealStarted = true;
const frame = item.activation.frame;
assert(frame >= outer.span.startFrame && frame < outer.span.endFrameExclusive,
- `Emoji Reveal Item ${item.spec.id} must activate inside the Track Window.`);
+ `Emoji Reveal Item ${item.spec.id} must activate inside the EmojiReveal Window.`);
assert(frame > previous, `Emoji Reveal Item ${item.spec.id} must activate after the previous Item.`);
previous = frame;
}
const program: EmojiRevealProgram = {
- id: header.id, programSpaceId: timeline.id, outer: structuredClone(outer), style: structuredClone(style),
+ id: header.id, timelineId: timeline.id, outer: structuredClone(outer), style: structuredClone(style),
placeholder: structuredClone(placeholder), items: structuredClone(set.items),
};
assertEmojiRevealProgram(program);
@@ -114,7 +114,7 @@ export function finalizeEmojiReveal(
}
export function assertEmojiRevealProgram(value: EmojiRevealProgram): void {
- identity(value.id, "EmojiRevealProgram.id"); identity(value.programSpaceId, "EmojiRevealProgram.programSpaceId");
+ identity(value.id, "EmojiRevealProgram.id"); identity(value.timelineId, "EmojiRevealProgram.timelineId");
assertEmojiRevealStyle(value.style); assertEmojiRevealSet({ items: value.items });
assertIconImage(value.placeholder, "EmojiRevealProgram.placeholder");
assert(value.items.length > 0, "EmojiRevealProgram requires Items.");
@@ -183,20 +183,20 @@ function iconElement(input: {
};
}
-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 });
+export function renderEmojiReveal(within: SpatialFrame, timeline: Timeline, program: EmojiRevealProgram): VisualTrack {
+ assertSpatialFrame(within); assertTimelineIdentity(timeline); assertEmojiRevealProgram(program);
+ assert(program.timelineId === timeline.id, "EmojiRevealProgram belongs to another Timeline.");
+ assertTemporalWindowFor(program.outer, { subjectId: program.id, timeline: timeline });
const { style } = program;
const count = program.items.length;
const width = style.paddingXPx * 2 + style.slotSizePx * count + style.gapPx * (count - 1);
const height = style.paddingYPx * 2 + style.slotSizePx;
- const left = canvas.widthPx * style.centerX - width / 2;
- const top = canvas.heightPx * style.topY;
- assert(left - Math.max(0, -style.shadowXPx) >= 0 && left + width + Math.max(0, style.shadowXPx) <= canvas.widthPx,
- "Emoji Reveal strip is wider than the Canvas at this placement.");
- assert(top >= 0 && top + height + Math.max(0, style.shadowYPx) <= canvas.heightPx,
- "Emoji Reveal strip is outside the Canvas at this placement.");
+ const left = within.xPx + within.widthPx * style.centerX - width / 2;
+ const top = within.yPx + within.heightPx * style.topY;
+ assert(left - Math.max(0, -style.shadowXPx) >= within.xPx && left + width + Math.max(0, style.shadowXPx) <= within.xPx + within.widthPx,
+ "Emoji Reveal strip is wider than its placement Frame.");
+ assert(top >= within.yPx && top + height + Math.max(0, style.shadowYPx) <= within.yPx + within.heightPx,
+ "Emoji Reveal strip is outside its placement Frame.");
const duration = program.outer.span.endFrameExclusive - program.outer.span.startFrame;
const elements: VisualElement[] = [{
id: "root", order: 0, kind: "box", style: [
@@ -234,9 +234,9 @@ export function renderEmojiReveal(canvas: CanvasSpace, timeline: Timeline, progr
);
});
const track = sealVisualTrack({
- 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 }],
+ timelineId: timeline.id, visualIr: "hypit.visual-ir@1", id: program.id,
+ presents: [{ id: program.id, order: 0, z: style.stackingOrder, subjectId: program.id,
+ span: { ...program.outer.span }, elements }],
});
assertVisualTrackIdentity(track, timeline); return track;
}
diff --git a/packages/interview-emoji-reveal/src/surface.ts b/packages/interview-emoji-reveal/src/surface.ts
index 6fc9a254..71946e30 100644
--- a/packages/interview-emoji-reveal/src/surface.ts
+++ b/packages/interview-emoji-reveal/src/surface.ts
@@ -4,12 +4,11 @@ import {
type SurfaceComponentDraft, type SurfaceRecordDraft, type SurfaceResolvedReference,
} from "@hypit/markup";
import { artifactTypes } from "@hypit/artifact";
-import { narrativeTypes } from "@hypit/narrative";
import { sameType, type CanonicalValue, type TypeRef } from "@hypit/protocol";
import { spatialTypes } from "@hypit/spatial";
import { svsRecipeType } from "@hypit/svs";
import type { SvsRecipe } from "@hypit/svs";
-import { createTemporalInstantProjection, createTemporalWindowProjection, temporalWindowAttributeNames } from "@hypit/temporal-markup";
+import { createTemporalInstantConstruction, createTemporalWindowConstruction, temporalWindowAttributeNames } from "@hypit/temporal-markup";
import { createEmojiRevealFragment } from "./fragment.js";
import { emojiRevealTypes } from "./manifest.js";
@@ -48,13 +47,13 @@ export const decodeEmojiRevealStyleSurface: StructuredSurfaceHandler = ({ elemen
};
export const decodeEmojiRevealTrackSurface: StructuredSurfaceHandler = ({ element, resolveReference }) => {
- assertAttributes(element, ["id", "timeline", "canvas", "style", "placeholder", ...temporalWindowAttributeNames]);
+ assertAttributes(element, ["id", "timeline", "within", "style", "placeholder", ...temporalWindowAttributeNames]);
const id = textAttribute(element, "id");
const context = resolveTemporalContext({ element, resolveReference });
- const canvas = reference(element.attributes.canvas, `${element.name}.canvas`, spatialTypes.canvas, resolveReference);
+ const within = reference(element.attributes.within, `${element.name}.within`, spatialTypes.frame, 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, resolveReference });
+ const outer = createTemporalWindowConstruction({ id, subjectId: id, element, ...context, resolveReference });
const headerId = `${id}.header`;
const records: SurfaceRecordDraft[] = [...outer.records, {
id: headerId, type: emojiRevealTypes.header,
@@ -64,7 +63,7 @@ export const decodeEmojiRevealTrackSurface: StructuredSurfaceHandler = ({ elemen
const temporalFragments = [...outer.fragments];
const items: { specName: string; iconName: string; activationName?: string }[] = [];
const inputs: Record<string, typeof context.timeline.ref> = {
- header: { kind: "record", id: headerId }, timeline: context.timeline.ref, canvas: canvas.ref, style: style.ref,
+ header: { kind: "record", id: headerId }, timeline: context.timeline.ref, within: within.ref, style: style.ref,
placeholder: placeholder.ref, outer: outer.ref,
};
const ids = new Set<string>();
@@ -89,9 +88,9 @@ export const decodeEmojiRevealTrackSurface: StructuredSurfaceHandler = ({ elemen
inputs[specName] = { kind: "record", id: specId }; inputs[iconName] = icon.ref;
if (preset) items.push({ specName, iconName });
else {
- const activation = createTemporalInstantProjection({
+ const activation = createTemporalInstantConstruction({
id: `${id}.item.${suffix}.activation`, subjectId: itemId,
- element: child, ...context, resolveReference, semanticAttribute: "at", projectedAttribute: false,
+ element: child, ...context, resolveReference, attribute: "at",
});
records.push(...activation.records); temporalComponents.push(...activation.components); temporalFragments.push(...activation.fragments);
const activationName = `item-${suffix}-activation`;
@@ -103,7 +102,7 @@ export const decodeEmojiRevealTrackSurface: StructuredSurfaceHandler = ({ elemen
const fragment = createEmojiRevealFragment(items);
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`],
+ components: [...temporalComponents, { id, fragment: fragment.id, inputs, outputs: { program: `${id}.program`, visual: `${id}.visual` }, range: element.range }],
+ fragments: [...temporalFragments, fragment], exports: [`${id}.program`, `${id}.visual`],
};
};
diff --git a/packages/interview-emoji-reveal/src/types.ts b/packages/interview-emoji-reveal/src/types.ts
index e3548e8b..9d2dfa98 100644
--- a/packages/interview-emoji-reveal/src/types.ts
+++ b/packages/interview-emoji-reveal/src/types.ts
@@ -44,7 +44,7 @@ export type EmojiRevealSet = { readonly items: readonly EmojiRevealItem[] };
export type EmojiRevealProgram = {
readonly id: string;
- readonly programSpaceId: string;
+ readonly timelineId: string;
readonly outer: TemporalWindow;
readonly style: EmojiRevealStyle;
readonly placeholder: BlobRef;
diff --git a/packages/media-execution/package.json b/packages/media-execution/package.json
index b55fe2c3..04d14721 100644
--- a/packages/media-execution/package.json
+++ b/packages/media-execution/package.json
@@ -10,8 +10,8 @@
"dependencies": {
"@hypit/media": "workspace:*",
"@hypit/media-pipeline": "workspace:*",
- "@hypit/program-space": "workspace:*",
"@hypit/protocol": "workspace:*",
- "@hypit/speech": "workspace:*"
+ "@hypit/speech-evidence": "workspace:*",
+ "@hypit/timeline": "workspace:*"
}
}
diff --git a/packages/media-execution/src/audio-presentation.ts b/packages/media-execution/src/audio-level-automation.ts
similarity index 58%
rename from packages/media-execution/src/audio-presentation.ts
rename to packages/media-execution/src/audio-level-automation.ts
index 4d9a9d05..4e7b7445 100644
--- a/packages/media-execution/src/audio-presentation.ts
+++ b/packages/media-execution/src/audio-level-automation.ts
@@ -1,8 +1,9 @@
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 [];
+/** Per-sample level automation after source playback/fades, before any requested render-range crop. */
+export function audioLevelAutomationFilter(clip: AudioProgramClip): string[] {
+ if (clip.gainEnvelope === undefined && clip.audibility === undefined
+ && clip.fadeInSamples === 0 && clip.fadeOutSamples === 0) return [];
const sample = `(n+${clip.targetStartSample})`;
let gain = "1";
const points = clip.gainEnvelope;
@@ -19,5 +20,13 @@ export function audioPresentationFilter(clip: AudioProgramClip): string[] {
const active = clip.audibility.map(span => `(gte(${sample},${span.startSample})*lt(${sample},${span.endSampleExclusive}))`).join("+") || "0";
gain = `(${gain})*(${active})`;
}
+ if (clip.fadeInSamples > 0) {
+ const end = clip.mixStartSample + clip.fadeInSamples;
+ gain = `(${gain})*if(lt(${sample},${end}),max(0,(${sample}-${clip.mixStartSample})/${clip.fadeInSamples}),1)`;
+ }
+ if (clip.fadeOutSamples > 0) {
+ const start = clip.mixEndSampleExclusive - clip.fadeOutSamples;
+ gain = `(${gain})*if(gte(${sample},${start}),max(0,(${clip.mixEndSampleExclusive}-${sample})/${clip.fadeOutSamples}),1)`;
+ }
return [`aeval=exprs='val(0)*(${gain})|val(1)*(${gain})'`];
}
diff --git a/packages/media-execution/src/execute.ts b/packages/media-execution/src/execute.ts
index a4d69604..74389def 100644
--- a/packages/media-execution/src/execute.ts
+++ b/packages/media-execution/src/execute.ts
@@ -1,4 +1,4 @@
-import { audioPresentationFilter } from "./audio-presentation.js";
+import { audioLevelAutomationFilter } from "./audio-level-automation.js";
import { spawn } from "node:child_process";
import { randomUUID } from "node:crypto";
import { createReadStream } from "node:fs";
@@ -7,9 +7,9 @@ import { tmpdir } from "node:os";
import { join } from "node:path";
import { verifyMediaFrameRange, mediaFrameRangeSamples, mediaTypes, sealMediaInspection, sealMuxedMedia, sealSynchronizedMedia, sealTimelineAudio, verifyMediaInspection, verifyMediaStreamSelection, verifyRenderedVisual, verifySynchronizedMedia, verifyTimelineAudio } from "@hypit/media";
import type { MediaAudioStream, MediaInspection, MediaRational, MediaStream, MediaStreamSelection, MediaTimestamp, MediaVideoStream, MuxedMedia, RenderedVisual, SynchronizedMedia, TimelineAudio } from "@hypit/media";
-import type { ProgramSpace } from "@hypit/program-space";
-import { assertSpeechEvidenceAudioIdentity, sealSpeechEvidenceAudio, speechEvidenceSampleBoundary, speechTypes } from "@hypit/speech";
-import type { SpeechEvidenceAudio } from "@hypit/speech";
+import type { Timeline } from "@hypit/timeline";
+import { assertSpeechEvidenceAudioIdentity, sealSpeechEvidenceAudio, speechEvidenceSampleBoundary } from "@hypit/speech-evidence";
+import type { SpeechEvidenceAudio } from "@hypit/speech-evidence";
import {
mediaPipelineCapabilities,
verifyAudioExtractionRequest,
@@ -489,7 +489,8 @@ function renderStillVideoNeed(value: CanonicalValue): RenderStillVideoNeed {
function evidenceAudioNeed(value: CanonicalValue): ProjectSpeechEvidenceAudioNeed {
const item = object(value, "ProjectSpeechEvidenceAudioNeed") as unknown as ProjectSpeechEvidenceAudioNeed;
- assert(item.source?.kind === "blob", "ProjectSpeechEvidenceAudioNeed is invalid");
+ assert(typeof item.domainId === "string" && item.domainId.length > 0
+ && item.source?.kind === "blob", "ProjectSpeechEvidenceAudioNeed is invalid");
assert(Number.isSafeInteger(item.sourceSampleFrames) && item.sourceSampleFrames > 0
&& Number.isSafeInteger(item.evidenceSampleFrames) && item.evidenceSampleFrames > 0
&& item.evidenceSampleFrames === speechEvidenceSampleBoundary(item.sourceSampleFrames),
@@ -551,11 +552,7 @@ function audioClipFilter(clip: AudioProgramClip, inputIndex: number, outputIndex
`apad=whole_len=${length}`,
`atrim=start_sample=0:end_sample=${length}`,
`volume=${clip.gain.toPrecision(15)}`,
- ...(clip.fadeInSamples === 0 ? [] : [`afade=t=in:start_sample=0:nb_samples=${clip.fadeInSamples}`]),
- ...(clip.fadeOutSamples === 0 ? [] : [
- `afade=t=out:start_sample=${length - clip.fadeOutSamples}:nb_samples=${clip.fadeOutSamples}`,
- ]),
- ...audioPresentationFilter(clip),
+ ...audioLevelAutomationFilter(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",
@@ -748,7 +745,7 @@ export async function executeNormalizeMedia(
audioArtifact = await env.artifacts.putFile(output, "audio/wav");
}
const media = sealSynchronizedMedia({
- timeline: {
+ frameDomain: {
frameRate: need.frameRate,
frameCount: plan.frameCount,
},
@@ -880,8 +877,8 @@ function decimal(value: number): string {
}
function compileTransformPlan(media: SynchronizedMedia, operations: readonly MediaTransformOperation[]): TransformPlan {
- const rate = media.timeline.frameRate.numerator / media.timeline.frameRate.denominator;
- let durationSec = media.timeline.frameCount / rate;
+ const rate = media.frameDomain.frameRate.numerator / media.frameDomain.frameRate.denominator;
+ let durationSec = media.frameDomain.frameCount / rate;
const videoFilters: string[] = ["setpts=PTS-STARTPTS"];
const audioFilters: string[] = ["asetpts=N/SR/TB"];
for (const [index, operation] of operations.entries()) {
@@ -907,14 +904,14 @@ function compileTransformPlan(media: SynchronizedMedia, operations: readonly Med
const frameCount = Math.max(1, Math.round(durationSec * rate));
assert(Number.isSafeInteger(frameCount), "Media transform output frame count exceeds safe arithmetic");
const sampleFrames = roundPositive(
- BigInt(frameCount) * 48_000n * BigInt(media.timeline.frameRate.denominator),
- BigInt(media.timeline.frameRate.numerator),
+ BigInt(frameCount) * 48_000n * BigInt(media.frameDomain.frameRate.denominator),
+ BigInt(media.frameDomain.frameRate.numerator),
);
- const fps = `${media.timeline.frameRate.numerator}/${media.timeline.frameRate.denominator}`;
+ const fps = `${media.frameDomain.frameRate.numerator}/${media.frameDomain.frameRate.denominator}`;
videoFilters.push(
`fps=fps=${fps}:round=near:start_time=0:eof_action=round`,
`trim=start_frame=0:end_frame=${frameCount}`,
- `setpts=N*${media.timeline.frameRate.denominator}/(${media.timeline.frameRate.numerator}*TB)`,
+ `setpts=N*${media.frameDomain.frameRate.denominator}/(${media.frameDomain.frameRate.numerator}*TB)`,
);
audioFilters.push(
`apad=whole_len=${sampleFrames}`,
@@ -953,7 +950,7 @@ export async function executeTransformMedia(
}
argv.push(
"-frames:v", String(plan.frameCount),
- "-r", `${media.timeline.frameRate.numerator}/${media.timeline.frameRate.denominator}`, "-fps_mode", "cfr",
+ "-r", `${media.frameDomain.frameRate.numerator}/${media.frameDomain.frameRate.denominator}`, "-fps_mode", "cfr",
"-c:v", "libx264", "-preset", "veryfast", "-pix_fmt", "yuv420p",
"-movflags", "+faststart", output,
);
@@ -990,7 +987,7 @@ export async function executeTransformMedia(
}
}
-/** Generic model-reference audio: no Narrative, SemanticTake or alignment claim is introduced. */
+/** Generic model-reference audio: no Narrative or alignment claim is introduced. */
export async function executeExtractAudio(
env: MediaExecutionEnvironment,
constraints: CanonicalValue,
@@ -1095,7 +1092,7 @@ export async function executeProjectSpeechEvidenceAudio(
...(env.sharedLibraryPath === undefined ? {} : { sharedLibraryPath: env.sharedLibraryPath }),
});
assert(source.decodedSampleFrames === need.sourceSampleFrames,
- "Speech master sample count differs from its ProgramSpace");
+ "Speech master sample count differs from its Timeline");
const filter = [
"asetpts=N/SR/TB",
"aresample=16000:async=0:first_pts=0",
@@ -1129,6 +1126,7 @@ export async function executeProjectSpeechEvidenceAudio(
"Alignment evidence must be exact 16 kHz mono PCM s16");
const artifact = await env.artifacts.putFile(output, "audio/wav");
const evidence: SpeechEvidenceAudio = sealSpeechEvidenceAudio({
+ domainId: need.domainId,
artifact,
sampleFrames: need.evidenceSampleFrames,
});
diff --git a/packages/media-execution/test/alpha.test.ts b/packages/media-execution/test/alpha.test.ts
index d8687683..6563aeb7 100644
--- a/packages/media-execution/test/alpha.test.ts
+++ b/packages/media-execution/test/alpha.test.ts
@@ -18,7 +18,7 @@ for (const format of ["webm", "webm-vp8", "mov"] as const) {
const source = await resources.put(fixture.bytes, fixture.mediaType);
const media = await normalizeTestVideo(resources, source, true);
assert.equal(media.visual!.artifact.mediaType, "video/webm");
- assert.equal(media.timeline.frameCount, 12);
+ assert.equal(media.frameDomain.frameCount, 12);
const visual = await writeTestArtifact(resources, media.visual!.artifact, join(directory, "normalized.webm"));
const pixels = ffmpegBytes(["-c:v", "libvpx-vp9", "-i", visual, "-an", "-pix_fmt", "rgba", "-f", "rawvideo", "pipe:1"]);
const stride = alphaSize.width * alphaSize.height * 4;
diff --git a/packages/media-pipeline/README.md b/packages/media-pipeline/README.md
index bc29dd46..379f392b 100644
--- a/packages/media-pipeline/README.md
+++ b/packages/media-pipeline/README.md
@@ -18,29 +18,33 @@ and otherwise fails closed. An explicit stream index is available when the autho
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.
+speech alignment component may bind one normalized local domain 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.
+through every consumer. The field is named `frameDomain`, not `timeline`, because it describes the
+normalized source before any program placement.
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.
+value. Normalization also publishes the media's neutral local temporal domain. Speech alignment may
+describe Narrative boundaries on that domain; Timeline authoring may consume its Extent; a domain
+projector may map its boundaries through an equal-length Window. None of those relationships is embedded
+back into SynchronizedMedia.
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.
+`<pipeline:Normalize>` produces `SynchronizedMedia + LocalTemporalDomain`; a speech provider and
+deterministic alignment produce `NarrativeAlignment`; Timeline authoring separately produces absolute
+Windows. Visual and Audio Tracks consume ordinary media plus the explicit Windows and sampling choices
+they declare; neither owns an implicit normalization policy.
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"/>
+<time:Clock id="clock" frame-rate="30"/>
<pipeline:Normalize id="shot-media" source={shot.video}
recipe={recipes.media.aroll} clock={clock}/>
```
@@ -87,7 +91,7 @@ Four ordinary author operations reuse that same inspection/execution boundary:
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:Retime rate="1.05"/>
</media:Transform>
<media:ExtractAudio id="voice-reference" source={prepared.video} audio="default"/>
@@ -95,7 +99,7 @@ Four ordinary author operations reuse that same inspection/execution boundary:
```
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
+WAV but makes no NarrativeAlignment, speaker or semantic 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.
@@ -108,7 +112,7 @@ 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
+Need. The plan fixes exact 48 kHz sample boundaries, source-time-derived piece rates, gain/fades and the absence
of hidden normalization/limiting. The local FFmpeg Provider consumes the shared execution body. Other Providers implement the same
public request and result semantics.
diff --git a/packages/media-pipeline/package.json b/packages/media-pipeline/package.json
index 0b32f752..1f4b44a9 100644
--- a/packages/media-pipeline/package.json
+++ b/packages/media-pipeline/package.json
@@ -17,11 +17,13 @@
"@hypit/elaborator": "workspace:*",
"@hypit/media": "workspace:*",
"@hypit/narrative": "workspace:*",
- "@hypit/program-space": "workspace:*",
"@hypit/protocol": "workspace:*",
"@hypit/run": "workspace:*",
"@hypit/speech": "workspace:*",
+ "@hypit/speech-evidence": "workspace:*",
"@hypit/svs": "workspace:*",
- "@hypit/markup": "workspace:*"
+ "@hypit/markup": "workspace:*",
+ "@hypit/timeline": "workspace:*",
+ "@hypit/temporal": "workspace:*"
}
}
diff --git a/packages/media-pipeline/src/audio-plan.ts b/packages/media-pipeline/src/audio-plan.ts
index 6172a5c2..b8a7825b 100644
--- a/packages/media-pipeline/src/audio-plan.ts
+++ b/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, assertAudioPresentation } from "@hypit/composition";
+import { clockFrameSampleBoundary, timelineFrameCount, timelineFrameSampleBoundary } from "@hypit/timeline";
+import type { Timeline } from "@hypit/timeline";
+import { assertAudioLevelAutomation, assertCompositionIdentity } from "@hypit/composition";
import type { Composition } from "@hypit/composition";
import { canonicalize, isResourceId } from "@hypit/protocol";
@@ -10,6 +10,25 @@ function assert(condition: unknown, message: string): asserts condition {
if (!condition) throw new Error(message);
}
+function exactInteger(value: { readonly numerator: number; readonly denominator: number }, label: string): number {
+ assert(Number.isSafeInteger(value.numerator) && Number.isSafeInteger(value.denominator) && value.denominator > 0
+ && value.numerator % value.denominator === 0, `${label} must resolve to an exact source-sample boundary`);
+ const result = value.numerator / value.denominator;
+ assert(Number.isSafeInteger(result) && result >= 0, `${label} is invalid`);
+ return result;
+}
+
+function exactSourceEnd(sourceAtStart: { readonly numerator: number; readonly denominator: number },
+ rate: { readonly numerator: number; readonly denominator: number }, targetLength: number, label: string): number {
+ const numerator = BigInt(sourceAtStart.numerator) * BigInt(rate.denominator)
+ + BigInt(targetLength) * BigInt(rate.numerator) * BigInt(sourceAtStart.denominator);
+ const denominator = BigInt(sourceAtStart.denominator) * BigInt(rate.denominator);
+ assert(numerator % denominator === 0n, `${label} must resolve to an exact source-sample boundary`);
+ const result = numerator / denominator;
+ assert(result >= 0n && result <= BigInt(Number.MAX_SAFE_INTEGER), `${label} is invalid`);
+ return Number(result);
+}
+
export function sealAudioProgramPlan(value: AudioProgramPlan): AudioProgramPlan {
return canonicalize(value) as unknown as AudioProgramPlan;
}
@@ -22,12 +41,7 @@ export function verifyAudioProgramPlan(value: unknown): asserts value is AudioPr
"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),
+ assert(item.sampleFrames === clockFrameSampleBoundary({ frameRate: item.frameRate }, 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>();
@@ -57,59 +71,75 @@ export function verifyAudioProgramPlan(value: unknown): asserts value is AudioPr
&& 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,
+ assert(Number.isFinite(clip.playbackRate) && clip.playbackRate > 0,
`AudioProgramPlan clip ${clip.id} playback rate is invalid`);
- assert(clip.pitch === "preserve", `AudioProgramPlan clip ${clip.id} pitch policy is invalid`);
+ assert(Number.isSafeInteger(clip.mixStartSample) && clip.mixStartSample >= 0
+ && Number.isSafeInteger(clip.mixEndSampleExclusive) && clip.mixEndSampleExclusive > clip.mixStartSample
+ && clip.targetStartSample >= clip.mixStartSample && clip.targetEndSampleExclusive <= clip.mixEndSampleExclusive,
+ `AudioProgramPlan clip ${clip.id} mix interval 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,
+ assertAudioLevelAutomation(clip, { startSample: clip.targetStartSample, endSampleExclusive: clip.targetEndSampleExclusive }, item.sampleFrames);
+ const mixLength = clip.mixEndSampleExclusive - clip.mixStartSample;
+ assert(Number.isSafeInteger(clip.fadeInSamples) && clip.fadeInSamples >= 0 && clip.fadeInSamples <= mixLength
+ && Number.isSafeInteger(clip.fadeOutSamples) && clip.fadeOutSamples >= 0 && clip.fadeOutSamples <= mixLength,
`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);
+export function compileAudioProgramPlan(composition: Composition, timeline: Timeline): AudioProgramPlan {
+ assertCompositionIdentity(composition, timeline);
+ const frameCount = timelineFrameCount(timeline);
const clips = composition.tracks
.filter((track) => track.kind === "audio")
- .flatMap((track) => track.clips.map((clip) => {
+ .flatMap((track) => track.clips.flatMap((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}`,
+ return clip.sourceTime.pieces.map((piece, pieceIndex) => {
+ const targetLength = piece.target.endSampleExclusive - piece.target.startSample;
+ const sourceAtStart = exactInteger(piece.sourceAtStart,
+ `${track.id}.${clip.id} piece ${pieceIndex} source start`);
+ const wrap = piece.wrap;
+ return {
+ id: `${track.id}:${clip.id}:${String(pieceIndex).padStart(4, "0")}`,
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,
+ targetStartSample: clip.target.startSample + piece.target.startSample,
+ targetEndSampleExclusive: clip.target.startSample + piece.target.endSampleExclusive,
+ sourceSampleFrames: clip.sourceTime.sourceSampleFrames,
+ sourceStartSample: wrap?.startSample ?? sourceAtStart,
+ sourceEndSampleExclusive: wrap?.endSampleExclusive
+ ?? exactSourceEnd(piece.sourceAtStart, piece.rate, targetLength,
+ `${track.id}.${clip.id} piece ${pieceIndex} source end`),
+ sourceLoop: wrap !== undefined,
+ sourcePhaseSample: wrap === undefined ? 0 : sourceAtStart - wrap.startSample,
+ playbackRate: piece.rate.numerator / piece.rate.denominator,
+ mixStartSample: clip.target.startSample,
+ mixEndSampleExclusive: clip.target.endSampleExclusive,
gain: clip.gain,
fadeInSamples: clip.fadeInSamples,
fadeOutSamples: clip.fadeOutSamples,
...(clip.gainEnvelope === undefined ? {} : { gainEnvelope: clip.gainEnvelope }),
- ...(clip.audibility === undefined ? {} : { audibility: clip.audibility }),
+ ...(clip.audibility === undefined ? {} : { audibility: clip.audibility.flatMap((span) => {
+ const startSample = Math.max(span.startSample, clip.target.startSample + piece.target.startSample);
+ const endSampleExclusive = Math.min(span.endSampleExclusive, clip.target.startSample + piece.target.endSampleExclusive);
+ return endSampleExclusive <= startSample ? [] : [{ startSample, endSampleExclusive }];
+ }) }),
};
+ });
}));
return sealAudioProgramPlan({
- frameRate: { ...programSpace.frameRate },
+ frameRate: { ...timeline.frameRate },
frameCount,
sampleRate: 48_000,
- sampleFrames: programFrameSampleBoundary(programSpace, frameCount, 48_000),
+ sampleFrames: timelineFrameSampleBoundary(timeline, frameCount, 48_000),
clips,
mix: { normalize: false, limiter: "none" },
});
diff --git a/packages/media-pipeline/src/component.ts b/packages/media-pipeline/src/component.ts
index c417f127..3f27e73d 100644
--- a/packages/media-pipeline/src/component.ts
+++ b/packages/media-pipeline/src/component.ts
@@ -4,10 +4,13 @@ import { plannedNeedInputs } from "@hypit/component-kit";
import type { ComponentPackage, PlannedNeedFacet } from "@hypit/component-kit";
import { synchronizedMediaSampleFrames, verifyMediaInspection, verifyMediaStreamSelection, verifyMuxedMedia, verifyRenderedVisual, verifySynchronizedMedia, verifyTimelineAudio } from "@hypit/media";
import type { MediaInspection, MediaStreamSelection, MuxedMedia, RenderedVisual, SynchronizedMedia, TimelineAudio } from "@hypit/media";
-import { assertProgramClockIdentity } from "@hypit/program-space";
-import type { ProgramClock, ProgramSpace } from "@hypit/program-space";
-import { assertSpeechDurationIdentity, speechEvidenceSampleBoundary } from "@hypit/speech";
+import { assertClockIdentity } from "@hypit/timeline";
+import type { Clock, Timeline } from "@hypit/timeline";
+import { assertSpeechDurationIdentity } from "@hypit/speech";
import type { SpeechDuration } from "@hypit/speech";
+import { speechEvidenceSampleBoundary } from "@hypit/speech-evidence";
+import { assertLocalTemporalDomain } from "@hypit/temporal";
+import type { LocalTemporalDomain } from "@hypit/temporal";
import type { Composition } from "@hypit/composition";
import type { BlobRef, CanonicalValue, CapabilityRef, ProducerRef, StoredValue } from "@hypit/protocol";
import { canonicalize } from "@hypit/protocol";
@@ -247,9 +250,9 @@ export const mediaPipelineComponent = {
producer: mediaPipelineProducers.planStill,
handler: ({ inputs }) => {
const duration = inline(inputs.duration!.value, "SpeechDuration") as unknown as SpeechDuration;
- const clock = inline(inputs.clock!.value, "ProgramClock") as unknown as ProgramClock;
+ const clock = inline(inputs.clock!.value, "Clock") as unknown as Clock;
assertSpeechDurationIdentity(duration);
- assertProgramClockIdentity(clock);
+ assertClockIdentity(clock);
const layout = inline(inputs.layout!.value, "StillVideoLayout") as unknown as StillVideoLayout;
verifyStillVideoLayout(layout);
const frames = Math.round(duration * clock.frameRate.numerator / clock.frameRate.denominator);
@@ -290,7 +293,14 @@ export const mediaPipelineComponent = {
producer: mediaPipelineProducers.projectSpeechEvidenceAudio,
handler: ({ inputs }) => {
const media = inline(inputs.media!.value, "SynchronizedMedia") as unknown as SynchronizedMedia;
+ const domain = inline(inputs.domain!.value, "LocalTemporalDomain") as unknown as LocalTemporalDomain;
verifySynchronizedMedia(media);
+ assertLocalTemporalDomain(domain);
+ if (domain.frameCount !== media.frameDomain.frameCount
+ || domain.frameRate.numerator !== media.frameDomain.frameRate.numerator
+ || domain.frameRate.denominator !== media.frameDomain.frameRate.denominator) {
+ throw new Error(`Speech evidence domain ${domain.id} does not describe its normalized media`);
+ }
if (media.audio === undefined) throw new Error("Speech evidence requires normalized Take audio");
const sourceSampleFrames = synchronizedMediaSampleFrames(media);
const evidenceSampleFrames = speechEvidenceSampleBoundary(sourceSampleFrames);
@@ -299,6 +309,7 @@ export const mediaPipelineComponent = {
throw new Error("Speech evidence audio sample domain is invalid");
}
const need: ProjectSpeechEvidenceAudioNeed = {
+ domainId: domain.id,
source: media.audio.artifact,
sourceSampleFrames,
evidenceSampleFrames,
@@ -310,9 +321,9 @@ export const mediaPipelineComponent = {
producer: mediaPipelineProducers.planAudio,
handler: ({ inputs }) => {
const composition = inline(inputs.composition!.value, "Composition") as unknown as Composition;
- const space = inline(inputs.space!.value, "ProgramSpace") as unknown as ProgramSpace;
+ const timeline = inline(inputs.timeline!.value, "Timeline") as unknown as Timeline;
return {
- outputs: { plan: { kind: "inline", value: canonicalize(compileAudioProgramPlan(composition, space)) } },
+ outputs: { plan: { kind: "inline", value: canonicalize(compileAudioProgramPlan(composition, timeline)) } },
needs: {},
};
},
diff --git a/packages/media-pipeline/src/fragment.ts b/packages/media-pipeline/src/fragment.ts
index 18651440..cd8d7bb2 100644
--- a/packages/media-pipeline/src/fragment.ts
+++ b/packages/media-pipeline/src/fragment.ts
@@ -1,6 +1,7 @@
-import { mediaTypes } from "@hypit/media";
+import { mediaProducers, mediaTypes } from "@hypit/media";
+import { temporalProducers, temporalTypes } from "@hypit/temporal";
import { artifactTypes } from "@hypit/artifact";
-import { programSpaceTypes } from "@hypit/program-space";
+import { timelineTypes } from "@hypit/timeline";
import { speechTypes } from "@hypit/speech";
import { sealGraphFragment } from "@hypit/elaborator";
@@ -16,6 +17,7 @@ export const synchronizedMediaFragment = sealGraphFragment({
inputs: [
{ name: "source", type: artifactTypes.blob },
{ name: "request", type: mediaPipelineTypes.selectionRequest },
+ { name: "domain", type: mediaTypes.domainSpec },
],
operations: [
{
@@ -41,11 +43,31 @@ export const synchronizedMediaFragment = sealGraphFragment({
},
result: { kind: "need", name: "media" },
},
+ {
+ id: "domain",
+ producer: mediaProducers.localDomain,
+ inputs: { media: operation("normalize"), spec: input("domain") },
+ result: { kind: "output", name: "domain" },
+ },
+ {
+ id: "extent",
+ producer: temporalProducers.extentFromDomain,
+ inputs: { domain: operation("domain") },
+ result: { kind: "output", name: "extent" },
+ },
],
exports: [{
name: "media",
type: mediaTypes.synchronized,
root: operation("normalize"),
+ }, {
+ name: "domain",
+ type: temporalTypes.localDomain,
+ root: operation("domain"),
+ }, {
+ name: "extent",
+ type: temporalTypes.extent,
+ root: operation("extent"),
}],
});
@@ -132,7 +154,7 @@ export function createStillVideoFragment(count: number) {
return sealGraphFragment({
inputs: [
{ name: "duration", type: speechTypes.duration },
- { name: "clock", type: programSpaceTypes.clock },
+ { name: "clock", type: timelineTypes.clock },
{ name: "layout", type: mediaPipelineTypes.stillVideoLayout },
...sources.map((name) => ({ name, type: artifactTypes.blob })),
],
diff --git a/packages/media-pipeline/src/manifest.ts b/packages/media-pipeline/src/manifest.ts
index 118a4c3c..908c3c24 100644
--- a/packages/media-pipeline/src/manifest.ts
+++ b/packages/media-pipeline/src/manifest.ts
@@ -1,9 +1,11 @@
import { artifactDependency } from "@hypit/artifact";
import { mediaDependency, mediaTypes } from "@hypit/media";
-import { programSpaceDependency, programSpaceTypes } from "@hypit/program-space";
+import { timelineDependency, timelineTypes } from "@hypit/timeline";
import { svsModuleRef, svsRecipeType } from "@hypit/svs";
import { speechDependency, speechTypes } from "@hypit/speech";
+import { speechEvidenceDependency, speechEvidenceTypes } from "@hypit/speech-evidence";
import { compositionDependency, compositionTypes, audioSampleSpanSchema, audioGainEnvelopeSchema } from "@hypit/composition";
+import { temporalDependency, temporalTypes } from "@hypit/temporal";
import { artifactTypes } from "@hypit/artifact";
import type {
CapabilityRef,
@@ -103,7 +105,6 @@ const retimeOperationSchema: ValueSchema = {
fields: {
kind: { schema: { kind: "literal", value: "retime" } },
rate: { schema: { kind: "number", minimum: 0.000001, maximum: 100 } },
- pitch: { schema: { kind: "literal", value: "preserve" } },
},
};
export const mediaTransformProgramSchema: ValueSchema = {
@@ -232,8 +233,9 @@ export const audioProgramPlanSchema: ValueSchema = {
sourceEndSampleExclusive: { schema: { kind: "number", integer: true, minimum: 1 } },
sourceLoop: { schema: { kind: "boolean" } },
sourcePhaseSample: { schema: integer },
- playbackRate: { schema: { kind: "number", minimum: 0.000001, maximum: 100 } },
- pitch: { schema: { kind: "literal", value: "preserve" } },
+ playbackRate: { schema: { kind: "number" } },
+ mixStartSample: { schema: integer },
+ mixEndSampleExclusive: { schema: { kind: "number", integer: true, minimum: 1 } },
gain: { schema: { kind: "number", minimum: 0, maximum: 64 } },
fadeInSamples: { schema: integer },
fadeOutSamples: { schema: integer },
@@ -254,7 +256,8 @@ export const audioProgramPlanSchema: ValueSchema = {
export const mediaPipelineMarkupSurfaces = [
{
name: "synchronized-media", tag: "Normalize", mode: "structured",
- outputs: [mediaPipelineTypes.selectionRequest, mediaTypes.synchronized],
+ outputs: [mediaPipelineTypes.selectionRequest, mediaTypes.domainSpec, mediaTypes.synchronized,
+ temporalTypes.localDomain, temporalTypes.extent],
vocabulary: {
summary:
"Inspects one BlobArtifact, selects its video and audio streams and normalizes them into SynchronizedMedia on one frame domain.",
@@ -273,21 +276,23 @@ export const mediaPipelineMarkupSurfaces = [
{ name: "span-authority", kind: "literal", required: false,
values: ["video", "audio"],
summary: "Decides which selected stream defines the extent the other is trimmed or padded to." },
- { name: "clock", kind: "reference", required: false, accepts: [programSpaceTypes.clock],
+ { name: "clock", kind: "reference", required: true, accepts: [timelineTypes.clock],
summary: "Selects the authored frame clock shared with the programme." },
- { name: "frame-rate", kind: "literal", required: false,
- summary: "Legacy inline frame rate; write exactly one of clock or frame-rate." },
],
ports: [
{ name: "media", type: mediaTypes.synchronized,
summary: "The normalized SynchronizedMedia, addressed as `<id>.media`." },
+ { name: "domain", type: temporalTypes.localDomain,
+ summary: "Its source-local frame domain, addressed as `<id>.domain`." },
+ { name: "extent", type: temporalTypes.extent,
+ summary: "Its unpositioned normalized length, addressed as `<id>.extent`." },
],
example: `<pipeline:Normalize id="music-media" source={music}
recipe={recipes.media.audio} clock={clock}/>`,
notes: [
- "Write exactly one of recipe or the direct video/audio/span-authority attributes, and exactly one of clock or frame-rate.",
+ "Write exactly one of recipe or the direct video/audio/span-authority attributes. Clock is always an explicit reference.",
"`primary-moving` excludes attached-picture streams, prefers one declared default and fails closed on an ambiguous container; `stream:<index>` is for a container the author genuinely knows.",
- "Selecting embedded audio is a media fact only and makes no SemanticTake, speaker or alignment claim.",
+ "Selecting embedded audio is a media fact only and makes no speaker or alignment claim.",
],
},
},
@@ -303,7 +308,7 @@ export const mediaPipelineMarkupSurfaces = [
summary: "Selects the one authored image held for the full video; write Still children instead for several images." },
{ name: "duration", kind: "literal", required: true,
summary: "Sets the video's length in seconds, such as 6 or 2.5s; choose it from the visual passage this held image is meant to carry." },
- { name: "clock", kind: "reference", required: true, accepts: [programSpaceTypes.clock],
+ { name: "clock", kind: "reference", required: true, accepts: [timelineTypes.clock],
summary: "Selects the frame clock used by the generated MP4." },
],
children: [
@@ -326,7 +331,7 @@ export const mediaPipelineMarkupSurfaces = [
notes: [
"Write exactly one of source or Still children. Frames are whole: each image gets the floor of its share and the leftover frames go to the largest remainders, so the split is deterministic and every image holds at least one frame.",
"Images of different sizes are fitted into the first image's frame, letterboxed on black.",
- "The result is a normal video Blob, not SynchronizedMedia and not a SemanticTake.",
+ "The result is a normal video Blob, not SynchronizedMedia or semantic evidence.",
"Use Normalize afterward exactly as for generated or imported moving video.",
"Encoding is a render-still-video Need fulfilled by the selected media Provider; this Surface never invokes FFmpeg itself.",
],
@@ -357,13 +362,10 @@ export const mediaPipelineMarkupSurfaces = [
summary: "Decides how many seconds are removed from the current end." },
] },
{ tag: "Retime", cardinality: "many",
- summary: "Changes playback speed by `rate` in the range (0, 100] while `pitch` holds the original pitch.",
+ summary: "Changes tempo by `rate` in the range (0, 100] while preserving pitch.",
attributes: [
{ name: "rate", kind: "literal", required: true,
summary: "Decides the playback speed multiplier, above `0` and at most `100`." },
- { name: "pitch", kind: "literal", required: true,
- values: ["preserve"],
- summary: "Decides how pitch follows the speed change, and the one spelling keeps the original pitch." },
] },
],
ports: [
@@ -372,7 +374,7 @@ export const mediaPipelineMarkupSurfaces = [
],
example: `<media:Transform id="prepared" source={shot-media.media}>
<media:Trim tail="0.25s"/>
- <media:Retime rate="1.05" pitch="preserve"/>
+ <media:Retime rate="1.05"/>
</media:Transform>`,
notes: [
"At least one `Trim` or `Retime` child is required, and children run in the order they are written.",
@@ -403,7 +405,7 @@ export const mediaPipelineMarkupSurfaces = [
example: '<media:ExtractAudio id="voice-reference" source={prepared.video} audio="default"/>',
notes: [
"The element accepts no children and no text content, and the output container, codec, sample rate and channel count are fixed.",
- "The result makes no SemanticTake, speaker or alignment claim, so it can feed a model reference port directly.",
+ "The result makes no speaker or alignment claim, so it can feed a model reference port directly.",
],
},
},
@@ -445,8 +447,10 @@ export const mediaPipelineManifest: ModuleManifest = {
artifactDependency,
mediaDependency,
speechDependency,
- programSpaceDependency,
+ speechEvidenceDependency,
+ timelineDependency,
compositionDependency,
+ temporalDependency,
{ module: svsModuleRef },
],
types: [
@@ -479,7 +483,7 @@ export const mediaPipelineManifest: ModuleManifest = {
{ name: mediaPipelineCapabilities.extractAudio.name, returns: artifactTypes.blob },
{ name: mediaPipelineCapabilities.extractFrame.name, returns: artifactTypes.blob },
{ name: mediaPipelineCapabilities.renderStill.name, returns: artifactTypes.blob },
- { name: mediaPipelineCapabilities.projectSpeechEvidenceAudio.name, returns: speechTypes.evidenceAudio },
+ { name: mediaPipelineCapabilities.projectSpeechEvidenceAudio.name, returns: speechEvidenceTypes.audio },
{ name: mediaPipelineCapabilities.renderAudio.name, returns: mediaTypes.timelineAudio },
{ name: mediaPipelineCapabilities.mux.name, returns: mediaTypes.muxed },
],
@@ -566,7 +570,7 @@ export const mediaPipelineManifest: ModuleManifest = {
name: mediaPipelineProducers.planStill.name,
inputs: [
{ name: "duration", type: speechTypes.duration },
- { name: "clock", type: programSpaceTypes.clock },
+ { name: "clock", type: timelineTypes.clock },
{ name: "layout", type: mediaPipelineTypes.stillVideoLayout },
],
outputs: [{ name: "request", type: mediaPipelineTypes.stillVideoRequest }],
@@ -595,19 +599,19 @@ export const mediaPipelineManifest: ModuleManifest = {
},
{
name: mediaPipelineProducers.projectSpeechEvidenceAudio.name,
- inputs: [{ name: "media", type: mediaTypes.synchronized }],
+ inputs: [{ name: "media", type: mediaTypes.synchronized }, { name: "domain", type: temporalTypes.localDomain }],
outputs: [],
needs: [{
name: "evidenceAudio",
capability: mediaPipelineCapabilities.projectSpeechEvidenceAudio,
- returns: speechTypes.evidenceAudio,
+ returns: speechEvidenceTypes.audio,
}],
},
{
name: mediaPipelineProducers.planAudio.name,
inputs: [
{ name: "composition", type: compositionTypes.composition },
- { name: "space", type: programSpaceTypes.programSpace },
+ { name: "timeline", type: timelineTypes.track },
],
outputs: [{ name: "plan", type: mediaPipelineTypes.audioProgramPlan }],
needs: [],
diff --git a/packages/media-pipeline/src/operations.ts b/packages/media-pipeline/src/operations.ts
index ad14e19c..91b0080a 100644
--- a/packages/media-pipeline/src/operations.ts
+++ b/packages/media-pipeline/src/operations.ts
@@ -61,7 +61,6 @@ export function verifyMediaTransformProgram(value: unknown): asserts value is Me
assert(typeof operation.rate === "number" && Number.isFinite(operation.rate) && operation.rate > 0
&& operation.rate <= 100,
`MediaTransformProgram retime ${index}.rate must be in (0, 100]`);
- assert(operation.pitch === "preserve", `MediaTransformProgram retime ${index}.pitch must be preserve`);
}
}
diff --git a/packages/media-pipeline/src/selection.ts b/packages/media-pipeline/src/selection.ts
index ba9ac100..ca4cb2fb 100644
--- a/packages/media-pipeline/src/selection.ts
+++ b/packages/media-pipeline/src/selection.ts
@@ -85,7 +85,7 @@ function selectedAudio(inspection: MediaInspection, request: MediaSelectionReque
/**
* Selects container streams only. Choosing an audio stream never claims that it is narrated speech;
- * SemanticTake construction remains a separate semantic Producer with an explicit Narrative edge.
+ * Narrative alignment remains a separate semantic Producer with an explicit Narrative edge.
*/
export function selectMediaStreams(
inspection: MediaInspection,
diff --git a/packages/media-pipeline/src/surface.ts b/packages/media-pipeline/src/surface.ts
index 2c99b38c..46e3f82e 100644
--- a/packages/media-pipeline/src/surface.ts
+++ b/packages/media-pipeline/src/surface.ts
@@ -11,7 +11,7 @@ import { sameType, type CanonicalValue } from "@hypit/protocol";
import { artifactTypes } from "@hypit/artifact";
import { mediaTypes } from "@hypit/media";
import { speechTypes } from "@hypit/speech";
-import { programSpaceTypes, type ProgramClock } from "@hypit/program-space";
+import { timelineTypes, type Clock } from "@hypit/timeline";
import { svsRecipeType, type SvsRecipe } from "@hypit/svs";
import {
@@ -90,17 +90,6 @@ function stream(value: string, kind: "video" | "audio"): MediaSelectionRequest["
return { mode: "stream-index", streamIndex: Number(match[1]) };
}
-function frameRate(value: string): { readonly numerator: number; readonly denominator: number } {
- const match = /^(\d+)(?:\/(\d+))?$/u.exec(value);
- if (match === null) throw new Error("Normalize.frame-rate must be a positive rational such as 30 or 30000/1001.");
- const numerator = Number(match[1]);
- const denominator = Number(match[2] ?? "1");
- if (!Number.isSafeInteger(numerator) || numerator < 1 || !Number.isSafeInteger(denominator) || denominator < 1) {
- throw new Error("Normalize.frame-rate is invalid.");
- }
- return { numerator, denominator };
-}
-
function exactAttributes(element: StructuredElement, required: readonly string[], optional: readonly string[] = []): void {
const expected = new Set([...required, ...optional]);
const unknown = Object.keys(element.attributes).filter((name) => !expected.has(name));
@@ -164,11 +153,10 @@ function transformOperations(element: StructuredElement): readonly MediaTransfor
continue;
}
if (name === "Retime") {
- exactAttributes(child, ["rate", "pitch"]);
+ exactAttributes(child, ["rate"]);
const rate = Number(text(child, "rate"));
if (!Number.isFinite(rate) || rate <= 0 || rate > 100) throw new Error(`${child.name}.rate must be in (0, 100].`);
- if (text(child, "pitch") !== "preserve") throw new Error(`${child.name}.pitch must be preserve.`);
- result.push({ kind: "retime", rate, pitch: "preserve" });
+ result.push({ kind: "retime", rate });
continue;
}
throw new Error(`${element.name} accepts only Trim and Retime children.`);
@@ -178,12 +166,9 @@ function transformOperations(element: StructuredElement): readonly MediaTransfor
}
export const decodeSynchronizedMediaSurface: StructuredSurfaceHandler = ({ element, resolveReference }) => {
- const required = ["id", "source"];
- const optional = ["audio", "clock", "frame-rate", "recipe", "span-authority", "video"];
+ const required = ["id", "source", "clock"];
+ const optional = ["audio", "recipe", "span-authority", "video"];
exactAttributes(element, required, optional);
- const hasClock = element.attributes.clock !== undefined;
- const hasFrameRate = element.attributes["frame-rate"] !== undefined;
- if (hasClock === hasFrameRate) throw new Error(`${element.name} requires exactly one of clock or frame-rate.`);
const hasRecipe = element.attributes.recipe !== undefined;
const policyCount = ["video", "audio", "span-authority"].filter((name) => element.attributes[name] !== undefined).length;
if ((hasRecipe && policyCount !== 0) || (!hasRecipe && policyCount !== 3)) {
@@ -194,13 +179,11 @@ export const decodeSynchronizedMediaSurface: StructuredSurfaceHandler = ({ eleme
}
const id = text(element, "id");
const source = ref(element.attributes.source, `${element.name}.source`, resolveReference);
- const clock = hasClock
- ? typedReference(element.attributes.clock, `${element.name}.clock`, programSpaceTypes.clock, resolveReference)
- : undefined;
- const clockValue = clock?.record?.value.kind === "inline"
- ? clock.record.value.value as unknown as ProgramClock
+ const clock = typedReference(element.attributes.clock, `${element.name}.clock`, timelineTypes.clock, resolveReference);
+ const clockValue = clock.record?.value.kind === "inline"
+ ? clock.record.value.value as unknown as Clock
: undefined;
- if (clock !== undefined && clockValue === undefined) throw new Error(`${element.name}.clock must be an authored Clock record.`);
+ if (clockValue === undefined) throw new Error(`${element.name}.clock must be an authored Clock record.`);
const normalizationRecipe = hasRecipe ? authoredRecipe(element.attributes.recipe, `${element.name}.recipe`, resolveReference) : undefined;
const video = stream(normalizationRecipe === undefined ? text(element, "video") : recipeText(normalizationRecipe, "video", `${element.name}.recipe`), "video");
const audio = stream(normalizationRecipe === undefined ? text(element, "audio") : recipeText(normalizationRecipe, "audio", `${element.name}.recipe`), "audio");
@@ -212,16 +195,20 @@ export const decodeSynchronizedMediaSurface: StructuredSurfaceHandler = ({ eleme
video,
audio,
spanAuthority,
- frameRate: clockValue?.frameRate ?? frameRate(text(element, "frame-rate")),
+ frameRate: clockValue.frameRate,
});
const requestId = `${id}.request`;
+ const domainId = `${id}.domain-spec`;
return {
- records: [{ id: requestId, type: mediaPipelineTypes.selectionRequest, value: { kind: "inline", value: request }, range: element.range }],
+ records: [
+ { id: requestId, type: mediaPipelineTypes.selectionRequest, value: { kind: "inline", value: request }, range: element.range },
+ { id: domainId, type: mediaTypes.domainSpec, value: { kind: "inline", value: { id } }, range: element.range },
+ ],
components: [{
id,
fragment: synchronizedMediaFragment.id,
- inputs: { source: source.ref, request: { kind: "record", id: requestId } },
- outputs: { media: `${id}.media` },
+ inputs: { source: source.ref, request: { kind: "record", id: requestId }, domain: { kind: "record", id: domainId } },
+ outputs: { media: `${id}.media`, domain: `${id}.domain`, extent: `${id}.extent` },
range: element.range,
}],
fragments: [synchronizedMediaFragment],
@@ -269,7 +256,7 @@ export const decodeStillVideoSurface: StructuredSurfaceHandler = ({ element, res
const clock = typedReference(
element.attributes.clock,
`${element.name}.clock`,
- programSpaceTypes.clock,
+ timelineTypes.clock,
resolveReference,
);
const fragment = createStillVideoFragment(pictures.length);
diff --git a/packages/media-pipeline/src/types.ts b/packages/media-pipeline/src/types.ts
index 21e02ca0..a8cdc794 100644
--- a/packages/media-pipeline/src/types.ts
+++ b/packages/media-pipeline/src/types.ts
@@ -1,4 +1,4 @@
-import type { AudioPresentation } from "@hypit/composition";
+import type { AudioLevelAutomation } from "@hypit/composition";
import type { BlobRef } from "@hypit/protocol";
import type { MediaFrameRange, MediaInspection, MediaRational, MediaStreamSelection, RenderedVisual, TimelineAudio } from "@hypit/media";
@@ -38,9 +38,8 @@ export type MediaTransformOperation =
}
| {
readonly kind: "retime";
- /** 2 means twice as fast and therefore half as long. */
+ /** Pitch-preserving tempo ratio; 2 means twice as fast and therefore half as long. */
readonly rate: number;
- readonly pitch: "preserve";
};
/** Ordered, deterministic A/V operations over already synchronized media. */
@@ -130,12 +129,13 @@ export type NormalizeMediaNeed = {
};
export type ProjectSpeechEvidenceAudioNeed = {
+ readonly domainId: string;
readonly source: BlobRef;
readonly sourceSampleFrames: number;
readonly evidenceSampleFrames: number;
};
-export type AudioProgramClip = AudioPresentation & {
+export type AudioProgramClip = AudioLevelAutomation & {
readonly id: string;
readonly artifact: BlobRef;
readonly targetStartSample: number;
@@ -145,8 +145,11 @@ export type AudioProgramClip = AudioPresentation & {
readonly sourceEndSampleExclusive: number;
readonly sourceLoop: boolean;
readonly sourcePhaseSample: number;
+ /** Tempo ratio; Audio execution preserves pitch. */
readonly playbackRate: number;
- readonly pitch: "preserve";
+ /** Complete owning Clip Window; fades do not restart at source-time piece boundaries. */
+ readonly mixStartSample: number;
+ readonly mixEndSampleExclusive: number;
readonly gain: number;
readonly fadeInSamples: number;
readonly fadeOutSamples: number;
diff --git a/packages/media-pipeline/test/manifest.test.ts b/packages/media-pipeline/test/manifest.test.ts
index 23b9da25..8324ee99 100644
--- a/packages/media-pipeline/test/manifest.test.ts
+++ b/packages/media-pipeline/test/manifest.test.ts
@@ -1,6 +1,6 @@
import { artifactTypes } from "@hypit/artifact";
import { mediaTypes } from "@hypit/media";
-import { programSpaceTypes } from "@hypit/program-space";
+import { timelineTypes } from "@hypit/timeline";
import { speechTypes } from "@hypit/speech";
import { svsRecipeType } from "@hypit/svs";
import { installRunFragmentHostFacets, RunFragmentRegistry } from "@hypit/run";
@@ -51,7 +51,7 @@ test("the Normalize Surface makes inspection and normalization an explicit autho
resolveReference: (path) => path === "generated"
? { path, ref: { kind: "record", id: path }, type: artifactTypes.blob }
: path === "clock"
- ? { path, ref: { kind: "record", id: path }, type: programSpaceTypes.clock,
+ ? { path, ref: { kind: "record", id: path }, type: timelineTypes.clock,
record: { value: { kind: "inline", value: { frameRate: { numerator: 30_000, denominator: 1_001 } } } } as never }
: path === "policy"
? { path, ref: { kind: "record", id: path }, type: svsRecipeType,
@@ -60,7 +60,9 @@ test("the Normalize Surface makes inspection and normalization an explicit autho
resolveAsset: async () => { throw new Error("no asset resolution expected"); },
});
assert.equal(result.fragments[0]?.id, synchronizedMediaFragment.id);
- assert.deepEqual(result.components[0]?.outputs, { media: "motion.media" });
+ assert.deepEqual(result.components[0]?.outputs, {
+ media: "motion.media", domain: "motion.domain", extent: "motion.extent",
+ });
const request = result.records[0]?.value;
assert.ok(request?.kind === "inline");
assert.deepEqual(request.value, {
@@ -89,7 +91,7 @@ test("media operations are ordinary graph branches over BlobArtifact", async ()
},
children: [
{ kind: "element", name: "media:Trim", attributes: { tail: "0.25s" }, children: [], range },
- { kind: "element", name: "media:Retime", attributes: { rate: "1.05", pitch: "preserve" }, children: [], range },
+ { kind: "element", name: "media:Retime", attributes: { rate: "1.05" }, children: [], range },
],
},
});
@@ -100,7 +102,7 @@ test("media operations are ordinary graph branches over BlobArtifact", async ()
assert.deepEqual(program.value.value, {
operations: [
{ kind: "trim", tailSec: 0.25 },
- { kind: "retime", rate: 1.05, pitch: "preserve" },
+ { kind: "retime", rate: 1.05 },
],
});
@@ -147,7 +149,7 @@ test("StillVideo stops at an ordinary MP4 branch before Normalize", async () =>
resolveReference: (path) => path === "opening-head"
? { path, ref: { kind: "record", id: path }, type: artifactTypes.blob }
: path === "clock"
- ? { path, ref: { kind: "record", id: path }, type: programSpaceTypes.clock }
+ ? { path, ref: { kind: "record", id: path }, type: timelineTypes.clock }
: undefined,
resolveAsset: async () => { throw new Error("no asset resolution expected"); },
});
@@ -165,7 +167,7 @@ test("StillVideo stops at an ordinary MP4 branch before Normalize", async () =>
test("StillVideo spreads several pictures over one literal duration by weight, in authored order", async () => {
const range = { source: "still.svml", start: 0, end: 1 };
const resolveReference = (path: string) => path === "clock"
- ? { path, ref: { kind: "record" as const, id: path }, type: programSpaceTypes.clock }
+ ? { path, ref: { kind: "record" as const, id: path }, type: timelineTypes.clock }
: { path, ref: { kind: "record" as const, id: path }, type: artifactTypes.blob };
const child = (source: string, weight?: string) => ({
kind: "element" as const, name: "media:Still",
diff --git a/packages/media-pipeline/test/presentation.test.ts b/packages/media-pipeline/test/presentation.test.ts
index f7a43a4e..80883a29 100644
--- a/packages/media-pipeline/test/presentation.test.ts
+++ b/packages/media-pipeline/test/presentation.test.ts
@@ -3,7 +3,7 @@ import test from "node:test";
import { mediaPipelineComponent } from "../src/component.js";
import { mediaPipelineProducers } from "../src/manifest.js";
-test("audio render presentation describes its own range without listing every clip", () => {
+test("audio range request describes its own range without listing every clip", () => {
const facet = mediaPipelineComponent.plannedNeeds.find((item) => item.producer.name === mediaPipelineProducers.renderAudioRange.name)!;
const plan = { frameRate: { numerator: 30, denominator: 1 }, frameCount: 600, sampleRate: 48000,
clips: Array.from({ length: 35 }, () => ({ source: "not a CLI output" })) };
diff --git a/packages/media-track-studio/README.md b/packages/media-track-studio/README.md
deleted file mode 100644
index 68c225ce..00000000
--- a/packages/media-track-studio/README.md
+++ /dev/null
@@ -1,12 +0,0 @@
-# `@hypit/media-track-studio`
-
-Hypit Studio Companion for `@hypit/media-track`.
-
-Each Item has a title and image or video body. An explicit author `id` supplies
-its title; otherwise the Companion displays its `image`, `media` or `surface`
-reference. Display names do not replace the Item's identity or writeback
-endpoint. Source-audio gain uses the same percentage display and scalar
-writeback as Audio Track.
-
-Media and Audio Track share selection and temporal editing behavior. Media
-composes pictures by draw order; Audio Track mixes overlapping sounds.
diff --git a/packages/media-track-studio/src/activation.ts b/packages/media-track-studio/src/activation.ts
deleted file mode 100644
index ccff3581..00000000
--- a/packages/media-track-studio/src/activation.ts
+++ /dev/null
@@ -1,7 +0,0 @@
-import { createStudioTrackCompanionHostFacet } from "@hypit/studio-adapter";
-import { mediaTrackStudioTrackCompanions } from "./index.js";
-
-export default {
- format: "hypit.node-package@1" as const,
- hostFacets: [createStudioTrackCompanionHostFacet(mediaTrackStudioTrackCompanions)],
-};
diff --git a/packages/media-track-studio/src/index.ts b/packages/media-track-studio/src/index.ts
deleted file mode 100644
index 8d556ac1..00000000
--- a/packages/media-track-studio/src/index.ts
+++ /dev/null
@@ -1,245 +0,0 @@
-import { mediaAppearanceDefaults, mediaTrackMarkupSurfaces, mediaTrackModuleRef, mediaTrackTypes } from "@hypit/media-track";
-import type { MediaLayerProgram, MediaTrackProgram } from "@hypit/media-track";
-import { compositionTypes } from "@hypit/composition";
-import { sameType } from "@hypit/protocol";
-import type {
- StudioTrackCompanion,
- StudioTrackCompanionContext,
- StudioEntityDraft,
- StudioInspectorFieldDeclaration,
- StudioMaterialPreview,
- StudioSourceBindingDeclaration,
-} from "@hypit/studio-adapter";
-import { artifactPreview, authoredItemTitle, childEntities, previewLayer, requiredSurfaceValue, temporalLineageFor, temporalSemanticSource } from "@hypit/studio-adapter";
-
-const frameParameters: readonly StudioSourceBindingDeclaration[] = [
- { name: "within" },
- { name: "left", writable: true },
- { name: "top", writable: true },
- { name: "right", writable: true },
- { name: "bottom", writable: true },
- { name: "x", writable: true },
- { name: "y", writable: true },
- { name: "width", writable: true },
- { name: "height", writable: true },
-];
-
-const extentParameters: readonly StudioSourceBindingDeclaration[] = [
- { name: "width", writable: true },
- { name: "height", writable: true },
-];
-
-const mediaTrackSurface = mediaTrackMarkupSurfaces.find((surface) => surface.name === "track");
-const mediaItemAttributes = mediaTrackSurface?.vocabulary.children?.find((child) => child.tag === "Item")?.attributes ?? [];
-
-function title(name: string): string {
- return name.split("-").map((part) => `${part.slice(0, 1).toUpperCase()}${part.slice(1)}`).join(" ");
-}
-
-function valuesFor(property: { readonly name: string }): readonly string[] | undefined {
- return "values" in property ? (property as { readonly values: readonly string[] }).values : undefined;
-}
-
-type MediaPlacement = Pick<StudioInspectorFieldDeclaration, "domain" | "page" | "section">;
-
-function mediaPlace(domain: "where" | "how" | "when", page: string, section: string): MediaPlacement {
- const id = section.toLowerCase().replaceAll(" ", "-");
- return { domain, page: { id: page.toLowerCase(), label: page }, section: { id, label: section } };
-}
-
-const mediaPlacement = new Map<string, MediaPlacement>();
-function placeMedia(names: readonly string[], domain: "where" | "how" | "when", page: string, section: string): void {
- for (const name of names) mediaPlacement.set(name, mediaPlace(domain, page, section));
-}
-
-placeMedia([
- "fit", "frame-x", "frame-y", "content-x", "content-y", "fit-offset-x", "fit-offset-y", "fit-constraint",
-], "where", "Fit", "Fit");
-placeMedia(["stack-order"], "where", "Frame", "Stacking");
-placeMedia(["clip", "radius", "padding"], "where", "Frame", "Geometry");
-placeMedia(["opacity", "blur", "brightness", "contrast", "saturation"], "how", "Image", "Image");
-placeMedia(["playback", "trim-start", "trim-end"], "when", "Playback", "Playback");
-placeMedia(["border-width", "border-style", "border-color", "shadows", "frame-paint"], "how", "Frame", "Paint");
-placeMedia(["enter", "enter-frames", "enter-easing", "enter-direction", "enter-amount", "enter-origin"], "when", "Enter", "Enter");
-placeMedia(["sustain"], "when", "Sustain", "Sustain");
-placeMedia(["exit", "exit-frames", "exit-easing", "exit-direction", "exit-amount", "exit-origin"], "when", "Exit", "Exit");
-
-const mediaColorProperties = new Set(["border-color"]);
-const mediaTextProperties = new Set(["padding", "shadows", "frame-paint", "sustain"]);
-const mediaPercentProperties = new Set(["frame-x", "frame-y", "content-x", "content-y", "opacity", "brightness", "contrast", "saturation"]);
-const mediaPixelProperties = new Set(["fit-offset-x", "fit-offset-y", "radius", "blur", "border-width"]);
-
-function mediaRecipe(name: "appearance" | "motion"): {
- readonly bindings: readonly import("@hypit/studio-adapter").StudioRecipeBindingDeclaration[];
- readonly inspector: readonly StudioInspectorFieldDeclaration[];
-} {
- const attribute = mediaItemAttributes.find((candidate) => candidate.name === name);
- const properties = attribute !== undefined && "recipe" in attribute ? attribute.recipe : [];
- return {
- bindings: properties.map(({ name: property }) => ({ name: property,
- ...(Object.hasOwn(mediaAppearanceDefaults, property) ? { fallback: mediaAppearanceDefaults[property as keyof typeof mediaAppearanceDefaults] } : {}),
- })),
- inspector: properties.map((property) => {
- const placement = mediaPlacement.get(property.name);
- if (placement === undefined) throw new Error(`Media Studio has no explicit Inspector declaration for ${property.name}.`);
- const options = valuesFor(property);
- const control = options !== undefined ? "select" as const
- : mediaColorProperties.has(property.name) ? "color" as const
- : mediaTextProperties.has(property.name) ? "text" as const : "number" as const;
- return {
- binding: `${name}.${property.name}`,
- label: title(property.name),
- ...placement,
- ...(property.summary === undefined ? {} : { summary: property.summary }),
- control,
- ...(mediaPercentProperties.has(property.name) ? { unit: "%", number: { scale: 100, step: 1 } } : {}),
- ...(mediaPixelProperties.has(property.name) ? { unit: "px", number: { step: 1 } } : {}),
- ...(["enter-frames", "exit-frames", "trim-start", "trim-end"].includes(property.name) ? { unit: "f", number: { step: 1 } } : {}),
- ...(options === undefined ? {} : { options }),
- };
- }),
- };
-}
-
-export const mediaAppearanceStudioFields = mediaRecipe("appearance");
-const mediaAppearanceRecipe = mediaAppearanceStudioFields;
-const mediaMotionRecipe = mediaRecipe("motion");
-
-function materialPreview(
- layers: readonly MediaLayerProgram[],
- facet: "visual" | "audio",
- audioFromLayer?: string,
-): StudioMaterialPreview | undefined {
- const layer = layers.find((candidate) => candidate.kind === "sample"
- && (facet === "visual" || audioFromLayer === undefined || candidate.id === audioFromLayer));
- if (layer?.kind !== "sample") return undefined;
- if (facet === "audio") {
- const artifact = layer.source.kind === "timed" ? layer.source.audio?.artifact : undefined;
- return artifact === undefined ? undefined : artifactPreview("audio", artifact.resource);
- }
- if (layer.source.kind === "surface") return undefined;
- return artifactPreview(layer.source.kind === "still" ? "image" : "video", layer.source.artifact.resource);
-}
-
-function projectMedia(context: StudioTrackCompanionContext): readonly StudioEntityDraft[] {
- const program = requiredSurfaceValue(context, "program") as MediaTrackProgram;
- const facet = sameType(context.track.typeRef, compositionTypes.audioTrack) ? "audio" : "visual";
- const items = [
- ...program.items.map((item) => ({
- id: item.id,
- subjectId: item.subjectId,
- startFrame: item.span.startFrame,
- endFrameExclusive: item.span.endFrameExclusive,
- stackOrder: item.stacking.order,
- preview: materialPreview(item.layers, facet, item.sourceAudio?.fromLayer),
- temporalInput: "window",
- sourceTypes: [mediaTrackTypes.itemSpec],
- })),
- ...program.sequences.map((sequence) => ({
- id: sequence.id,
- subjectId: sequence.id,
- startFrame: sequence.span.startFrame,
- endFrameExclusive: sequence.span.endFrameExclusive,
- stackOrder: sequence.stacking.order,
- preview: sequence.members[0] === undefined
- ? undefined
- : materialPreview(sequence.members[0].layers, facet, sequence.members[0].sourceAudio?.fromLayer),
- temporalInput: "terminal",
- sourceTypes: [mediaTrackTypes.sequenceSpec],
- })),
- ];
- return childEntities(context, items, "media-item", "standard")
- .map((entity, index) => {
- const item = items[index];
- if (item === undefined) return entity;
- const temporal = temporalLineageFor(context, item.id, item.temporalInput);
- const semanticSource = temporalSemanticSource(temporal);
- return {
- ...entity,
- display: {
- ...entity.display,
- title: authoredItemTitle(context, entity.authoredId, item.sourceTypes, ["image", "media", "surface"]),
- ...(item.preview === undefined ? {} : {
- layers: [previewLayer(item.preview, facet === "audio" ? "waveform" : item.preview.kind === "video" ? "storyboard" : "repeat-x")],
- }),
- },
- ...(semanticSource?.id === undefined
- ? {}
- : { markerId: semanticSource.id }),
- ...(temporal === undefined ? {} : { temporal }),
- };
- });
-}
-
-const commonBindings: readonly StudioSourceBindingDeclaration[] = [
- { name: "source-audio", writable: true },
- { name: "audio-gain", writable: true },
- { name: "until" },
- { name: "until-boundary", writable: true },
-];
-
-const commonInspector: readonly StudioInspectorFieldDeclaration[] = [
- {
- binding: "audio-gain", label: "Audio Gain", domain: "how",
- page: { id: "audio", label: "Audio" }, section: { id: "audio", label: "Audio" }, control: "number",
- unit: "%", number: { scale: 100, minimum: 0, step: 1 },
- },
- {
- binding: "until-boundary", label: "Until Boundary", domain: "when",
- page: { id: "boundary", label: "Boundary" }, section: { id: "boundary", label: "Boundary" },
- control: "select", options: ["start", "end"],
- },
-];
-
-const frameSizeParameters = new Set(["width", "height"]);
-
-export const mediaTrackStudioTrackCompanions: readonly StudioTrackCompanion[] = [
- {
- id: "visual", role: "track",
- output: { type: compositionTypes.visualTrack, surface: "track", modules: [mediaTrackModuleRef] },
- family: "media", tone: "blue", icon: "video",
- bindings: [
- ...commonBindings,
- { name: "extent", referenced: extentParameters },
- { name: "clip" },
- { name: "image" },
- { name: "media" },
- { name: "surface" },
- { name: "frame", referenced: frameParameters },
- {
- name: "appearance",
- recipe: { bindings: mediaAppearanceRecipe.bindings },
- },
- {
- name: "motion",
- recipe: { bindings: mediaMotionRecipe.bindings },
- },
- ],
- inspector: [
- ...frameParameters.filter(({ writable }) => writable === true).map(({ name }) => ({
- binding: `frame.${name}`, label: title(name), domain: "where" as const,
- page: { id: frameSizeParameters.has(name) ? "size" : "placement", label: frameSizeParameters.has(name) ? "Size" : "Placement" },
- section: { id: "frame", label: "Frame" }, control: "number" as const, number: { suffixes: ["%", "px"], step: 1 },
- })),
- ...extentParameters.map(({ name }) => ({
- binding: `extent.${name}`, label: title(name), domain: "where" as const,
- page: { id: "size", label: "Size" }, section: { id: "extent", label: "Source Extent" },
- control: "number" as const, unit: "px",
- })),
- ...mediaAppearanceRecipe.inspector,
- ...mediaMotionRecipe.inspector,
- ...commonInspector,
- ],
- requiredValues: ["program"], project: projectMedia,
- lane: { heightPx: 76 },
- },
- {
- id: "audio", role: "track",
- output: { type: compositionTypes.audioTrack, surface: "track", modules: [mediaTrackModuleRef] },
- family: "media-audio", tone: "green", icon: "waveform",
- bindings: commonBindings,
- inspector: commonInspector,
- requiredValues: ["program"], project: projectMedia,
- lane: { heightPx: 48 },
- },
-];
diff --git a/packages/media-track/README.md b/packages/media-track/README.md
deleted file mode 100644
index a83a1421..00000000
--- a/packages/media-track/README.md
+++ /dev/null
@@ -1,164 +0,0 @@
-# `@hypit/media-track`
-
-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](../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.
-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 `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 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.
-
-## Present existing Timeline footage
-
-[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
-
-An Item or Sequence owns an outer destination `frame`. Each sampled source has a fitted content
-rectangle calculated from its intrinsic extent and its fit Recipe. Border and padding reduce the
-fitting area inside the outer Frame. Source dimensions stay factual; the calculated rectangle can
-be smaller or larger than the fitting area.
-
-[Spatial](../spatial/README.md#destination-and-fitted-content) owns the seven fit modes, the two
-alignment points, pixel offsets and bounded/free placement. `frame-x` / `frame-y` are alignment
-fractions in that fitting area. Move the whole visual by changing the `frame` reference; choose
-which part of the picture is visible through the fit and content alignment.
-
-The appearance Recipe separates the outer presentation from the sampled picture:
-
-| Properties | What they affect |
-| --- | --- |
-| `stack-order` | Absolute visual stacking of the Item or Sequence; required |
-| `clip` | Outer clipping: `frame` (default), `rounded`, or `none` |
-| `radius` | Pixel radius when `clip: rounded`; half a square Frame's side gives a circle |
-| `padding` | Fitting inset, as quoted pixel values: `"12"`, `"8 12"`, or `"8 12 16 12"` |
-| `border-width`, `border-style`, `border-color` | Border inside the outer Frame; a positive width requires a color |
-| `shadows` | Frame shadows, as quoted `x y blur spread color` entries separated by semicolons |
-| `frame-paint` | Solid or gradient backing behind the content |
-| `fit`, alignment and fit offsets | The scaled source's rectangle |
-| `opacity`, `blur`, `brightness`, `contrast`, `saturation` | The sampled picture, independently of frame decoration |
-
-For example, this is a rounded card with an inset picture and a painted backing:
-
-```svs
-media.card {
- stack-order: 40;
- fit: contain;
- clip: rounded;
- radius: 24;
- padding: "12";
- border-width: 2;
- border-color: #B9A88B;
- frame-paint: #25332D;
- shadows: "0 8 20 0 #00000055";
-}
-```
-
-The outer size includes the border; border and padding both reduce the fitting area. The clip
-follows the outer Frame, so a smaller contained picture may retain square corners inside a rounded
-card. A rounded picture with a flush edge uses a Frame matching its displayed aspect. `clip: none`
-allows source overflow; fitting alone supplies no mask. An authored spatial Path can be bound to
-an Item or Sequence with `clip={path}` in place of the Recipe's clip choice. Path coordinates are in
-Canvas pixels.
-
-A `motion` Recipe transforms the framed unit, including its backing and decoration. `Sampling`
-transforms the fitted source inside it, around the source rectangle's center. It accepts `zoom`,
-pixel `x` / `y`, degree `rotate`, and `easing`, at `start`, `end`, or intermediate percentages. Supply
-keys spanning start to end. Sampling runs after fitting and is not constrained by `fit-constraint`;
-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,
-Timeline and Recipes are already declared:
-
-```svml
-<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}
- during={story.selection.proof} appearance={recipes.media.clip}/>
-</media-track:Track>
-```
-
-One Item selects exactly one direct source form (`image` + `extent`, prepared `media`, or `surface`)
-or declares ordered `Paint`/`Layer` children. The current Surface has no raw `video` attribute.
-Appearance owns stack order, fit, clipping and source sampling; a `motion` Recipe owns lifecycle
-movement. `Sampling` children can move the sampled content inside the Frame independently.
-
-```svml
-<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}
- at={story.moment.first}/>
- <media-track:Member id="two" image={second} extent={card-extent}
- at={story.moment.second}/>
- <media-track:Handoff id="one-two" from="one" transition={recipes.transition.cards}/>
- </media-track:Sequence>
-</media-track:Track>
-```
-
-Members have ordered activation Instants; the next activation ends the preceding logical phase,
-and the Sequence has an explicit terminal Instant. Each adjacent pair needs a Handoff, including
-an explicit `cut` when no blended transition is intended. `from` names the outgoing Member; its
-successor is the incoming Member. A Handoff's duration and boundary ratio place the visual transition
-around that logical boundary without moving the semantic event.
-
-For layered content, `Paint` and `Layer` children draw in Source order inside the shared Frame. Give
-each Layer its own fit/sample Recipe. A Member appearance override selects its source fit, sampling
-and frame paint; the Sequence still owns the outer Frame, clip, padding, border, shadow, motion and
-stack order. Separate Items supply independently placed Frames.
-
-An Item or Member can select audio using `source-audio`: `content` for its direct source, or a child
-Layer id for layered content. This is opt-in. `Sound` can instead attach normalized audio to Item
-`at="enter"` / `at="exit"`, or to a Sequence `handoff="one-two"`. The Track publishes `.visual` and
-`.program`, plus `.audio` when sound is present; Film must include the desired peer outputs.
-
-## Item windows and source playback
-
-The Item's projected Window determines when it is active in the program. A timed sample's Recipe
-separately controls which source frames it occupies there. `playback` defaults to `once-start`:
-
-| Value | Source occupancy inside the Window |
-| --- | --- |
-| `once-start` | Play at native rate from the source start. Truncate if the Window is shorter; draw no source after it ends if the Window is longer. |
-| `once-end` | Align native playback to the Window end. Use the source tail if the Window is shorter; leave the initial excess unoccupied if longer. |
-| `hold-start` | Play from the start, then hold the last source frame over any remaining Window. |
-| `hold-end` | Align playback to the end, holding the first source frame over any initial excess. |
-| `loop-start` / `loop-end` | Repeat at native rate, aligning the loop phase to the start or end. |
-| `stretch` | Retime the selected source range across the full Window. |
-
-`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 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
-model-invalid two-second generation. Conversely, an Item active longer than its source must choose
-whether a return to the layer below, a hold, a loop or retiming is intended. No mode is universally
-correct for B-roll. Extending a Window with `once-start` does not extend the underlying video.
-
-Durationless still images refuse `playback`, `trim-start` and `trim-end`. Their spatial placement and
-Item Window are sufficient. A static B-roll picture does not need conversion to a generated clip.
-
-Visual and source-audio projections remain separate. Selecting source audio applies the corresponding
-sampling policy to that audio; a held visual frame does not synthesize held sound. A silent B-roll
-layer can cover a speaking Track while the latter's audio continues unchanged.
-
-For adjacent semantic Items that should have no uncovered pause, author touching Selection boundaries
-using Script affinity. Also inspect opacity transitions and source exhaustion: touching Windows alone
-do not guarantee opaque visual coverage.
diff --git a/packages/media-track/src/activation.ts b/packages/media-track/src/activation.ts
deleted file mode 100644
index 23d5fb29..00000000
--- a/packages/media-track/src/activation.ts
+++ /dev/null
@@ -1,20 +0,0 @@
-import { createMarkupSurfaceHostFacet } from "@hypit/markup";
-import {
- decodeMediaTrackSurface,
- mediaTrackComponent,
- mediaTrackManifest,
- mediaTrackModuleRef,
- mediaTrackMarkupSurfaces,
-} from "./index.js";
-
-export const hypitPackage = {
- format: "hypit.node-package@1" as const,
- modules: [{ manifest: mediaTrackManifest }],
- components: [mediaTrackComponent],
- hostFacets: [createMarkupSurfaceHostFacet({
- module: mediaTrackModuleRef,
- declaration: mediaTrackMarkupSurfaces.find((item) => item.name === "track")!,
- handler: decodeMediaTrackSurface,
- })],
-};
-export default hypitPackage;
diff --git a/packages/media-track/src/author.ts b/packages/media-track/src/author.ts
deleted file mode 100644
index d58e3890..00000000
--- a/packages/media-track/src/author.ts
+++ /dev/null
@@ -1,323 +0,0 @@
-import type { SvsRecipe } from "@hypit/svs";
-import { decodeContentFitProperties } from "@hypit/spatial";
-import type { ContentFit } from "@hypit/spatial";
-
-import {
- sealMediaPaintLayerSpec,
- sealMediaSampleLayerSpec,
-} from "./layers.js";
-import { sealMediaItemSpec } from "./program.js";
-import { sealMediaHandoffSpec, sealMediaSequenceSpec } from "./sequence.js";
-import type {
- MediaFramePresentation,
- MediaHandoffSpec,
- MediaItemSpec,
- MediaLifecycleMotion,
- MediaPaint,
- MediaPaintLayerSpec,
- MediaSampleLayerSpec,
- MediaSampleAppearance,
- MediaSequenceSpec,
- MediaVisualOccupancy,
- MediaVisualTrim,
-} from "./types.js";
-
-function fail(recipe: SvsRecipe, message: string): never {
- throw new Error(`Media Recipe ${recipe.path} ${message}`);
-}
-
-function optionalNumber(recipe: SvsRecipe, name: string): number | undefined {
- const value = recipe.properties[name];
- if (value === undefined) return undefined;
- if (typeof value !== "number" || !Number.isFinite(value)) fail(recipe, `${name} must be a finite number.`);
- return value;
-}
-
-function number(recipe: SvsRecipe, name: string, fallback?: number): number {
- const value = optionalNumber(recipe, name);
- if (value === undefined && fallback !== undefined) return fallback;
- if (value === undefined) fail(recipe, `requires ${name}.`);
- return value;
-}
-
-function optionalString(recipe: SvsRecipe, name: string): string | undefined {
- const value = recipe.properties[name];
- if (value === undefined) return undefined;
- if (typeof value !== "string" || value.trim().length === 0) fail(recipe, `${name} must be text.`);
- return value.trim();
-}
-
-function string(recipe: SvsRecipe, name: string, fallback?: string): string {
- const value = optionalString(recipe, name);
- if (value === undefined && fallback !== undefined) return fallback;
- if (value === undefined) fail(recipe, `requires ${name}.`);
- return value;
-}
-
-function oneOf<T extends string>(recipe: SvsRecipe, name: string, values: readonly T[], fallback?: T): T {
- const value = optionalString(recipe, name);
- if (value === undefined && fallback !== undefined) return fallback;
- if (value === undefined || !values.includes(value as T)) fail(recipe, `${name} must be ${values.join(" | ")}.`);
- return value as T;
-}
-
-function assertKeys(recipe: SvsRecipe, allowed: readonly string[]): void {
- const unknown = Object.keys(recipe.properties).filter((name) => !allowed.includes(name));
- if (unknown.length > 0) fail(recipe, `does not accept ${unknown.join(", ")}.`);
-}
-
-function scalarList(recipe: SvsRecipe, name: string, allowed: readonly number[]): number[] {
- const source = optionalString(recipe, name);
- if (source === undefined) return [];
- const values = source.split(/\s+/u).map(Number);
- if (!allowed.includes(values.length) || values.some((value) => !Number.isFinite(value))) {
- fail(recipe, `${name} requires ${allowed.join(" or ")} finite numbers.`);
- }
- return values;
-}
-
-function padding(recipe: SvsRecipe): MediaFramePresentation["padding"] {
- const values = scalarList(recipe, "padding", [1, 2, 4]);
- if (values.length === 0) return { topPx: 0, rightPx: 0, bottomPx: 0, leftPx: 0 };
- if (values.length === 1) return { topPx: values[0]!, rightPx: values[0]!, bottomPx: values[0]!, leftPx: values[0]! };
- if (values.length === 2) return { topPx: values[0]!, rightPx: values[1]!, bottomPx: values[0]!, leftPx: values[1]! };
- return { topPx: values[0]!, rightPx: values[1]!, bottomPx: values[2]!, leftPx: values[3]! };
-}
-
-function gradientStops(recipe: SvsRecipe, source: string): readonly { readonly offset: number; readonly color: string }[] {
- const stops = source.split(",").map((entry) => {
- const match = /^(.+?)@((?:0(?:\.\d+)?)|(?:1(?:\.0+)?))$/u.exec(entry.trim());
- if (match === null) fail(recipe, "gradient stops must be color@offset inside [0,1].");
- return { color: match[1]!.trim(), offset: Number(match[2]) };
- });
- if (stops.length < 2) fail(recipe, "gradient requires at least two stops.");
- return stops;
-}
-
-function paint(recipe: SvsRecipe, property = "paint"): MediaPaint {
- const source = string(recipe, property);
- const linear = /^linear\(([-+]?\d+(?:\.\d+)?);(.+)\)$/u.exec(source);
- if (linear !== null) {
- return { kind: "linear-gradient", angleDeg: Number(linear[1]), stops: gradientStops(recipe, linear[2]!) };
- }
- const radial = /^radial\(((?:0(?:\.\d+)?)|(?:1(?:\.0+)?)),((?:0(?:\.\d+)?)|(?:1(?:\.0+)?));(.+)\)$/u.exec(source);
- if (radial !== null) {
- return { kind: "radial-gradient", center: { x: Number(radial[1]), y: Number(radial[2]) }, stops: gradientStops(recipe, radial[3]!) };
- }
- return { kind: "solid", color: source };
-}
-
-function shadows(recipe: SvsRecipe): MediaFramePresentation["shadows"] {
- const source = optionalString(recipe, "shadows");
- if (source === undefined || source === "none") return [];
- return source.split(";").map((entry) => {
- const match = /^([-+]?\d+(?:\.\d+)?)\s+([-+]?\d+(?:\.\d+)?)\s+(\d+(?:\.\d+)?)\s+([-+]?\d+(?:\.\d+)?)\s+(.+)$/u.exec(entry.trim());
- if (match === null) fail(recipe, "shadows entries require x y blur spread color.");
- return {
- offsetX: Number(match[1]), offsetY: Number(match[2]), blurPx: Number(match[3]),
- spreadPx: Number(match[4]), color: match[5]!.trim(),
- };
- });
-}
-
-const FIT_KEYS = ["fit", "frame-x", "frame-y", "content-x", "content-y", "fit-offset-x", "fit-offset-y", "fit-constraint"] as const;
-const SAMPLE_KEYS = ["opacity", "blur", "brightness", "contrast", "saturation", "playback", "trim-start", "trim-end"] as const;
-const FRAME_KEYS = ["stack-order", "clip", "radius", "padding", "border-width", "border-style", "border-color", "shadows", "frame-paint"] as const;
-const MOTION_KEYS = ["enter", "enter-frames", "enter-easing", "enter-direction", "enter-amount", "enter-origin", "sustain", "exit", "exit-frames", "exit-easing", "exit-direction", "exit-amount", "exit-origin"] as const;
-
-export function decodeMediaFit(recipe: SvsRecipe): ContentFit {
- return decodeContentFitProperties(recipe.properties, `Media Recipe ${recipe.path}`);
-}
-
-function occupancy(recipe: SvsRecipe): MediaVisualOccupancy {
- switch (oneOf(recipe, "playback", ["once-start", "once-end", "hold-start", "hold-end", "loop-start", "loop-end", "stretch"] as const, "once-start")) {
- case "once-start": return { mode: "once", align: "start" };
- case "once-end": return { mode: "once", align: "end" };
- case "hold-start": return { mode: "hold", align: "start" };
- case "hold-end": return { mode: "hold", align: "end" };
- case "loop-start": return { mode: "loop", align: "start" };
- case "loop-end": return { mode: "loop", align: "end" };
- case "stretch": return { mode: "stretch" };
- }
-}
-
-function trim(recipe: SvsRecipe): MediaVisualTrim | undefined {
- const startFrame = optionalNumber(recipe, "trim-start");
- const endFrameExclusive = optionalNumber(recipe, "trim-end");
- if (startFrame === undefined && endFrameExclusive === undefined) return undefined;
- if (
- startFrame === undefined
- || endFrameExclusive === undefined
- || !Number.isSafeInteger(startFrame)
- || !Number.isSafeInteger(endFrameExclusive)
- ) {
- fail(recipe, "trim-start and trim-end must both be integer frames.");
- }
- return { startFrame, endFrameExclusive };
-}
-
-export function decodeMediaSampleSpec(
- recipe: SvsRecipe,
- id: string,
- sourceKind: "still" | "timed" | "surface",
- samplingMotion?: MediaSampleLayerSpec["samplingMotion"],
- combinedItemAppearance = false,
-): MediaSampleLayerSpec {
- assertKeys(recipe, [...FIT_KEYS, ...SAMPLE_KEYS, ...(combinedItemAppearance ? FRAME_KEYS : [])]);
- const hasTimedProperties = recipe.properties.playback !== undefined
- || recipe.properties["trim-start"] !== undefined
- || recipe.properties["trim-end"] !== undefined;
- if (sourceKind === "still" && hasTimedProperties) {
- fail(recipe, "cannot apply playback or trim to durationless still material.");
- }
- const timed = sourceKind === "timed" || (sourceKind === "surface" && hasTimedProperties);
- const sourceTrim = timed ? trim(recipe) : undefined;
- return sealMediaSampleLayerSpec({
-
- id,
- ...(timed ? { occupancy: occupancy(recipe), ...(sourceTrim === undefined ? {} : { trim: sourceTrim }) } : {}),
- appearance: decodeMediaSampleAppearance(recipe),
- ...(samplingMotion === undefined ? {} : { samplingMotion }),
- });
-}
-
-/** 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", mediaAppearanceDefaults.opacity),
- filter: {
- blurPx: number(recipe, "blur", mediaAppearanceDefaults.blur), brightness: number(recipe, "brightness", mediaAppearanceDefaults.brightness),
- contrast: number(recipe, "contrast", mediaAppearanceDefaults.contrast), saturation: number(recipe, "saturation", mediaAppearanceDefaults.saturation),
- },
- };
-}
-
-function edge(recipe: SvsRecipe, prefix: "enter" | "exit"): MediaLifecycleMotion["enter"] {
- const operator = optionalString(recipe, prefix);
- if (operator === undefined || operator === "none") return undefined;
- const allowed = ["fade", "slide", "scale", "pop", "bounce", "blur-reveal", "wipe", "flip", "spin"] as const;
- if (!allowed.includes(operator as typeof allowed[number])) fail(recipe, `${prefix} operator is invalid.`);
- const direction = optionalString(recipe, `${prefix}-direction`);
- const origin = optionalString(recipe, `${prefix}-origin`);
- return {
- operator: operator as typeof allowed[number],
- durationFrames: number(recipe, `${prefix}-frames`),
- easing: oneOf(recipe, `${prefix}-easing`, ["linear", "ease-in", "ease-out", "ease-in-out"] as const, "ease-in-out"),
- ...(direction === undefined ? {} : { direction: oneOf(recipe, `${prefix}-direction`, ["left", "right", "up", "down"] as const) }),
- ...(origin === undefined ? {} : { origin: oneOf(recipe, `${prefix}-origin`, ["outside-canvas"] as const) }),
- ...(optionalNumber(recipe, `${prefix}-amount`) === undefined ? {} : { amount: number(recipe, `${prefix}-amount`) }),
- };
-}
-
-function sustain(recipe: SvsRecipe): MediaLifecycleMotion["sustain"] {
- const source = optionalString(recipe, "sustain");
- if (source === undefined || source === "none") return [];
- return source.split(",").map((entry) => {
- const match = /^(float|breathe|pulse|wobble|shake|drift)\s+([-+]?\d+(?:\.\d+)?)\s+([1-9]\d*)(?:\s+(left|right|up|down))?$/u.exec(entry.trim());
- if (match === null) fail(recipe, "sustain entries require operator amount cycles [direction].");
- return {
- operator: match[1] as MediaLifecycleMotion["sustain"][number]["operator"],
- amount: Number(match[2]), cycles: Number(match[3]),
- ...(match[4] === undefined ? {} : { direction: match[4] as "left" | "right" | "up" | "down" }),
- };
- });
-}
-
-export function decodeMediaMotion(recipe: SvsRecipe | undefined): MediaLifecycleMotion {
- if (recipe === undefined) return { sustain: [] };
- assertKeys(recipe, MOTION_KEYS);
- const enter = edge(recipe, "enter");
- const exit = edge(recipe, "exit");
- return {
- ...(enter === undefined ? {} : { enter }),
- sustain: sustain(recipe),
- ...(exit === undefined ? {} : { exit }),
- };
-}
-
-export function decodeMediaPresentation(recipe: SvsRecipe): MediaFramePresentation {
- 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", mediaAppearanceDefaults.radius) } : { kind: clip },
- padding: padding(recipe),
- ...(borderWidth === 0 ? {} : { border: {
- widthPx: borderWidth,
- style: oneOf(recipe, "border-style", ["solid", "dashed", "dotted"] as const, "solid"),
- color: string(recipe, "border-color"),
- } }),
- shadows: shadows(recipe),
- };
-}
-
-export function decodeMediaItemSpec(
- recipe: SvsRecipe,
- input: Pick<MediaItemSpec, "id"> & {
- readonly motion: MediaLifecycleMotion;
- readonly sourceAudio?: MediaItemSpec["sourceAudio"];
- },
-): MediaItemSpec {
- assertKeys(recipe, [...FIT_KEYS, ...SAMPLE_KEYS, ...FRAME_KEYS]);
- return sealMediaItemSpec({
-
- id: input.id,
- presentation: decodeMediaPresentation(recipe),
- motion: input.motion,
- stackingOrder: number(recipe, "stack-order"),
- ...(input.sourceAudio === undefined ? {} : { sourceAudio: input.sourceAudio }),
- });
-}
-
-export function decodeMediaFramePaint(recipe: SvsRecipe, id: string): MediaPaintLayerSpec | undefined {
- const source = optionalString(recipe, "frame-paint");
- if (source === undefined || source === "transparent") return undefined;
- const adapted: SvsRecipe = { ...recipe, properties: { paint: source } };
- return sealMediaPaintLayerSpec({ id, paint: paint(adapted), opacity: 1 });
-}
-
-export function decodeMediaPaintSpec(recipe: SvsRecipe, id: string): MediaPaintLayerSpec {
- assertKeys(recipe, ["paint", "opacity"]);
- return sealMediaPaintLayerSpec({
- id, paint: paint(recipe), opacity: number(recipe, "opacity", mediaAppearanceDefaults.opacity),
- });
-}
-
-export function decodeMediaHandoffSpec(
- recipe: SvsRecipe,
- id: string,
- fromMemberId: string,
- toMemberId: string,
-): MediaHandoffSpec {
- assertKeys(recipe, ["operator", "duration-frames", "boundary-ratio", "direction", "audio"]);
- const operator = oneOf(recipe, "operator", ["cut", "crossfade", "push", "wipe", "cover", "page-turn"] as const);
- const direction = optionalString(recipe, "direction");
- return sealMediaHandoffSpec({
- id, fromMemberId, toMemberId, operator,
- durationFrames: number(recipe, "duration-frames"),
- boundaryRatio: number(recipe, "boundary-ratio", 0.5),
- ...(direction === undefined ? {} : { direction: oneOf(recipe, "direction", ["left", "right", "up", "down"] as const) }),
- audio: oneOf(recipe, "audio", ["cut", "crossfade"] as const, "cut"),
- });
-}
-
-export function decodeMediaSequenceSpec(
- recipe: SvsRecipe,
- id: string,
- motion: MediaLifecycleMotion,
- handoffs: readonly MediaHandoffSpec[],
-): MediaSequenceSpec {
- assertKeys(recipe, [...FIT_KEYS, ...SAMPLE_KEYS, ...FRAME_KEYS]);
- return sealMediaSequenceSpec({
- id,
- presentation: decodeMediaPresentation(recipe), motion,
- stackingOrder: number(recipe, "stack-order"), handoffs,
- });
-}
-
-export const mediaAppearanceKeys = { fit: FIT_KEYS, sample: SAMPLE_KEYS, frame: FRAME_KEYS, motion: MOTION_KEYS } as const;
diff --git a/packages/media-track/src/component.ts b/packages/media-track/src/component.ts
deleted file mode 100644
index 9f379def..00000000
--- a/packages/media-track/src/component.ts
+++ /dev/null
@@ -1,156 +0,0 @@
-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 { CanvasSpace, ContentFit, IntrinsicExtent, SpatialFrame, SpatialPath } from "@hypit/spatial";
-import type { TemporalInstant, TemporalWindow } from "@hypit/temporal";
-
-import {
- appendMediaPaintLayer,
- appendStillMediaLayer,
- appendSurfaceMediaLayer,
- appendTimedMediaLayer,
- createMediaLayerSet,
-} from "./layers.js";
-import { mediaTrackProducers, mediaTrackTypes } from "./manifest.js";
-import { appendMediaItem, appendMediaSequence, bindMediaItemClipPath, bindMediaSequenceClipPath, assertMediaTrackProgram, createMediaTrackSet, finalizeMediaTrack, projectMediaAudioTrack, projectMediaVisualTrack } from "./program.js";
-import {
- appendMediaSequenceMember,
- createMediaSequenceMemberSet,
-} from "./sequence.js";
-import {
- appendMediaSound,
- createMediaSoundSet,
-} from "./sounds.js";
-import type {
- MediaItemSpec,
- MediaLayerSet,
- MediaPaintLayerSpec,
- MediaSampleLayerSpec,
- MediaSoundSet,
- MediaSoundSpec,
- MediaSequenceMemberSet,
- MediaSequenceMemberSpec,
- MediaSequenceSpec,
- MediaTrackHeader,
- MediaTrackProgram,
- MediaTrackSet,
-} from "./types.js";
-
-function inline<T>(value: StoredValue | undefined, label: string): T {
- if (value?.kind !== "inline") throw new Error(`${label} must be inline.`);
- return value.value as unknown as T;
-}
-function blob(value: StoredValue | undefined): BlobRef {
- if (value?.kind !== "blob") throw new Error("Media source must be a BlobArtifact.");
- return value;
-}
-const output = (value: unknown) => ({ kind: "inline" as const, value: canonicalize(value) });
-
-function itemInputs(inputs: ProducerHandlerContext["inputs"]) {
- return {
- set: inline<MediaTrackSet>(inputs.set?.value, "MediaTrackSet"),
- header: inline<MediaTrackHeader>(inputs.header?.value, "MediaTrackHeader"),
- 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"),
- spec: inline<MediaItemSpec>(inputs.spec?.value, "MediaItemSpec"),
- sounds: inline<MediaSoundSet>(inputs.sounds?.value, "MediaSoundSet"),
- window: inline<import("@hypit/temporal").TemporalWindow>(inputs.window?.value, "TemporalWindow"),
- };
-}
-
-function memberInputs(inputs: ProducerHandlerContext["inputs"]) {
- return {
- members: inline<MediaSequenceMemberSet>(inputs.members?.value, "MediaSequenceMemberSet"),
- 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"),
- };
-}
-
-function sequenceInputs(inputs: ProducerHandlerContext["inputs"]) {
- return {
- set: inline<MediaTrackSet>(inputs.set?.value, "MediaTrackSet"),
- header: inline<MediaTrackHeader>(inputs.header?.value, "MediaTrackHeader"),
- 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"),
- spec: inline<MediaSequenceSpec>(inputs.spec?.value, "MediaSequenceSpec"),
- sounds: inline<MediaSoundSet>(inputs.sounds?.value, "MediaSoundSet"),
- terminal: inline<TemporalInstant>(inputs.terminal?.value, "TemporalInstant"),
- };
-}
-
-export const mediaTrackComponent = {
- producers: [
- { producer: mediaTrackProducers.createLayers, handler: () => ({ outputs: { layers: output(createMediaLayerSet()) }, needs: {} }) },
- { producer: mediaTrackProducers.appendPaintLayer, handler: ({ inputs }) => ({ outputs: { layers: output(appendMediaPaintLayer(
- inline<MediaLayerSet>(inputs.layers?.value, "MediaLayerSet"),
- inline<MediaPaintLayerSpec>(inputs.spec?.value, "MediaPaintLayerSpec"),
- )) }, needs: {} }) },
- { producer: mediaTrackProducers.appendStillLayer, handler: ({ inputs }) => ({ outputs: { layers: output(appendStillMediaLayer(
- inline<MediaLayerSet>(inputs.layers?.value, "MediaLayerSet"), blob(inputs.source?.value),
- inline<IntrinsicExtent>(inputs.extent?.value, "IntrinsicExtent"), inline<ContentFit>(inputs.fit?.value, "ContentFit"),
- inline<MediaSampleLayerSpec>(inputs.spec?.value, "MediaSampleLayerSpec"),
- )) }, needs: {} }) },
- { producer: mediaTrackProducers.appendTimedLayer, handler: ({ inputs }) => ({ outputs: { layers: output(appendTimedMediaLayer(
- inline<MediaLayerSet>(inputs.layers?.value, "MediaLayerSet"), inline<SynchronizedMedia>(inputs.source?.value, "SynchronizedMedia"),
- inline<ContentFit>(inputs.fit?.value, "ContentFit"), inline<MediaSampleLayerSpec>(inputs.spec?.value, "MediaSampleLayerSpec"),
- )) }, needs: {} }) },
- { producer: mediaTrackProducers.appendSurfaceLayer, handler: ({ inputs }) => ({ outputs: { layers: output(appendSurfaceMediaLayer(
- inline<MediaLayerSet>(inputs.layers?.value, "MediaLayerSet"), inline<CompositableSurfaceRef>(inputs.source?.value, "CompositableSurfaceRef"),
- inline<ContentFit>(inputs.fit?.value, "ContentFit"), inline<MediaSampleLayerSpec>(inputs.spec?.value, "MediaSampleLayerSpec"),
- )) }, needs: {} }) },
- { producer: mediaTrackProducers.createSounds, handler: () => ({ outputs: { sounds: output(createMediaSoundSet()) }, needs: {} }) },
- { producer: mediaTrackProducers.appendSound, handler: ({ inputs }) => ({ outputs: { sounds: output(appendMediaSound(
- inline<MediaSoundSet>(inputs.sounds?.value, "MediaSoundSet"),
- inline<SynchronizedMedia>(inputs.source?.value, "SynchronizedMedia"),
- inline<MediaSoundSpec>(inputs.spec?.value, "MediaSoundSpec"),
- )) }, needs: {} }) },
- { 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.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"),
- inline<SpatialPath>(inputs.path?.value, "SpatialPath"),
- )) }, needs: {} }) },
- { producer: mediaTrackProducers.bindSequenceClipPath, handler: ({ inputs }) => ({ outputs: { spec: output(bindMediaSequenceClipPath(
- inline<MediaSequenceSpec>(inputs.spec?.value, "MediaSequenceSpec"),
- inline<SpatialPath>(inputs.path?.value, "SpatialPath"),
- )) }, needs: {} }) },
- { producer: mediaTrackProducers.createMembers, handler: () => ({ outputs: { members: output(createMediaSequenceMemberSet()) }, needs: {} }) },
- { producer: mediaTrackProducers.appendMember, handler: ({ inputs }) => {
- const value = memberInputs(inputs);
- return { outputs: { members: output(appendMediaSequenceMember(
- 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.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<Timeline>(inputs.timeline?.value, "Timeline"),
- )) }, needs: {} }) },
- { producer: mediaTrackProducers.projectVisual, handler: ({ inputs }) => ({ outputs: { track: output(projectMediaVisualTrack(
- inline<Timeline>(inputs.timeline?.value, "Timeline"), inline<MediaTrackProgram>(inputs.program?.value, "MediaTrackProgram"),
- )) }, needs: {} }) },
- { producer: mediaTrackProducers.projectAudio, handler: ({ inputs }) => ({ outputs: { track: output(projectMediaAudioTrack(
- inline<Timeline>(inputs.timeline?.value, "Timeline"), inline<MediaTrackProgram>(inputs.program?.value, "MediaTrackProgram"),
- )) }, needs: {} }) },
- ],
- validators: [{
- type: mediaTrackTypes.program,
- handler: ({ value }) => assertMediaTrackProgram(inline<MediaTrackProgram>(value, "MediaTrackProgram")),
- }],
-} satisfies ComponentPackage;
diff --git a/packages/media-track/src/fragment.ts b/packages/media-track/src/fragment.ts
deleted file mode 100644
index 1793e02f..00000000
--- a/packages/media-track/src/fragment.ts
+++ /dev/null
@@ -1,58 +0,0 @@
-import { timelineTypes } from "@hypit/timeline";
-
-import { artifactTypes } from "@hypit/artifact";
-import { compositionTypes } from "@hypit/composition";
-import { sealGraphFragment } from "@hypit/elaborator";
-import { spatialTypes } from "@hypit/spatial";
-import { temporalTypes } from "@hypit/temporal";
-
-import { mediaTrackProducers, mediaTrackTypes } from "./manifest.js";
-
-const input = (name: string) => ({ kind: "fragment-input" as const, name });
-const operation = (id: string) => ({ kind: "fragment-operation" as const, operation: id });
-
-/** Minimal complete graph witness; richer Surfaces generate the same primitive operations dynamically. */
-export const stillMediaTrackFragment = sealGraphFragment({
- inputs: [
- { name: "header", type: mediaTrackTypes.header },
- { name: "timeline", type: timelineTypes.track },
- { name: "canvas", type: spatialTypes.canvas },
- { name: "source", type: artifactTypes.blob },
- { name: "extent", type: spatialTypes.extent },
- { name: "frame", type: spatialTypes.frame },
- { name: "fit", type: spatialTypes.fit },
- { name: "sample-spec", type: mediaTrackTypes.sampleLayerSpec },
- { name: "item-spec", type: mediaTrackTypes.itemSpec },
- { name: "window", type: temporalTypes.window },
- ],
- operations: [
- { id: "layers", producer: mediaTrackProducers.createLayers, inputs: {}, result: { kind: "output", name: "layers" } },
- { id: "sample", producer: mediaTrackProducers.appendStillLayer, inputs: {
- layers: operation("layers"), source: input("source"), extent: input("extent"), fit: input("fit"), spec: input("sample-spec"),
- }, result: { kind: "output", name: "layers" } },
- { id: "set", producer: mediaTrackProducers.createSet, inputs: {}, result: { kind: "output", name: "set" } },
- { id: "sounds", producer: mediaTrackProducers.createSounds, inputs: {}, result: { kind: "output", name: "sounds" } },
- { id: "append", producer: mediaTrackProducers.appendItem, inputs: {
- set: operation("set"), header: input("header"), timeline: input("timeline"), canvas: input("canvas"), layers: operation("sample"),
- frame: input("frame"), spec: input("item-spec"), sounds: operation("sounds"), window: input("window"),
- }, result: { kind: "output", name: "set" } },
- { id: "finalize", producer: mediaTrackProducers.finalize, inputs: {
- set: operation("append"), header: input("header"), timeline: input("timeline"),
- }, result: { kind: "output", name: "program" } },
- { id: "visual", producer: mediaTrackProducers.projectVisual, inputs: {
- timeline: input("timeline"), program: operation("finalize"),
- }, result: { kind: "output", name: "track" } },
- ],
- exports: [
- { name: "program", type: mediaTrackTypes.program, root: operation("finalize") },
- { name: "track", type: compositionTypes.visualTrack, root: operation("visual") },
- ],
-});
-
-export const renderMediaTrackFragment = sealGraphFragment({
- inputs: [{ name: "timeline", type: timelineTypes.track }, { name: "program", type: mediaTrackTypes.program }],
- operations: [
- { id: "visual", producer: mediaTrackProducers.projectVisual, inputs: { timeline: input("timeline"), program: input("program") }, result: { kind: "output", name: "track" } },
- ],
- exports: [{ name: "track", type: compositionTypes.visualTrack, root: operation("visual") }],
-});
diff --git a/packages/media-track/src/index.ts b/packages/media-track/src/index.ts
deleted file mode 100644
index da0b0a56..00000000
--- a/packages/media-track/src/index.ts
+++ /dev/null
@@ -1,67 +0,0 @@
-export { mediaTrackComponent } from "./component.js";
-export {
- decodeMediaFit,
- decodeMediaItemSpec,
- decodeMediaFramePaint,
- decodeMediaMotion,
- decodeMediaPresentation,
- decodeMediaSampleAppearance,
- decodeMediaSampleSpec,
- mediaAppearanceKeys,
-} from "./author.js";
-export { renderMediaTrackFragment, stillMediaTrackFragment } from "./fragment.js";
-export {
- appendMediaPaintLayer,
- appendStillMediaLayer,
- appendSurfaceMediaLayer,
- appendTimedMediaLayer,
- assertMediaLayerSet,
- assertMediaPaintLayerSpec,
- assertMediaSampleLayerSpec,
- assertMediaVisualOccupancy,
- assertMediaVisualSource,
- createMediaLayerSet,
- sealMediaPaintLayerSpec,
- sealMediaSampleLayerSpec,
-} from "./layers.js";
-export { lowerMediaItemElements } from "./lower.js";
-export { mediaItemSpecSchema, mediaFramePresentationSchema, mediaLifecycleMotionSchema, mediaLayerSetSchema, mediaHandoffSpecSchema, mediaPaintLayerSpecSchema, mediaSampleAppearanceSchema, mediaSampleLayerSpecSchema, mediaSamplingMotionSchema, mediaSoundSetSchema, mediaSoundSpecSchema, mediaSequenceMemberSetSchema, mediaSequenceMemberSpecSchema, mediaSequenceSpecSchema, mediaTrackDependency, mediaTrackHeaderSchema, mediaTrackManifest, mediaTrackMarkupSurfaces, mediaTrackModuleRef, mediaTrackProducers, mediaTrackProgramSchema, mediaTrackSetSchema, mediaTrackTypes } from "./manifest.js";
-export {
- assertMediaEdgeMotion,
- assertMediaLifecycleMotion,
- assertMediaSustainMotion,
- lifecycleAnimation,
- samplingAnimation,
- lifecycleAnimationWindow,
- resolveMediaLifecycleMotion,
- sustainAnimation,
- sustainAnimationWindow,
-} from "./motion.js";
-export { assertMediaFramePresentation } from "./presentation.js";
-export {
- appendMediaSound,
- assertMediaSoundSet,
- assertMediaSoundSpec,
- createMediaSoundSet,
- sealMediaSoundSpec,
-} from "./sounds.js";
-export { appendMediaItem, appendMediaSequence, bindMediaItemClipPath, bindMediaSequenceClipPath, assertMediaItemSpec, assertMediaTrackHeader, assertMediaTrackProgram, assertMediaTrackProgramIdentity, assertMediaTrackSet, createMediaTrackSet, finalizeMediaTrack, projectMediaAudioTrack, projectMediaVisualTrack, sealMediaItemSpec, sealMediaTrackHeader, sealMediaTrackProgram } from "./program.js";
-export { resolveVisualSampling } from "./sampling.js";
-export { decodeMediaSamplingKeyframe, decodeMediaTrackSurface } from "./surface.js";
-export {
- appendMediaSequenceMember,
- assertMediaHandoffSpec,
- assertMediaSequenceMemberSet,
- assertMediaSequenceMemberSpec,
- assertMediaSequenceSpec,
- createMediaSequenceMemberSet,
- lowerMediaSequencePresents,
- resolveMediaSequence,
- sealMediaHandoffSpec,
- sealMediaSequenceMemberSpec,
- sealMediaSequenceSpec,
- sequenceMemberHandoffAnimation,
-} from "./sequence.js";
-export type * from "./types.js";
-
-export { mediaAppearanceDefaults } from "./author.js";
diff --git a/packages/media-track/src/manifest.ts b/packages/media-track/src/manifest.ts
deleted file mode 100644
index c0fd9cfb..00000000
--- a/packages/media-track/src/manifest.ts
+++ /dev/null
@@ -1,602 +0,0 @@
-import type { Timeline } from "@hypit/timeline";
-import { temporalContextAttributeVocabulary } from "@hypit/temporal-markup";
-import { visualTimedSamplingSchema } from "@hypit/composition";
-import { readFile } from "node:fs/promises";
-
-import { artifactDependency, artifactTypes } from "@hypit/artifact";
-import { compositionDependency, compositionTypes } from "@hypit/composition";
-import {
- compositableSurfaceSchema,
- mediaDependency,
- mediaTypes,
-} from "@hypit/media";
-import { narrativeDependency, narrativeTypes } from "@hypit/narrative";
-
-import type { ModuleManifest, ProducerRef, TypeRef, ValueSchema } from "@hypit/protocol";
-import { timelineDependency, timelineTypes } from "@hypit/timeline";
-import {
- contentFitSchema,
- intrinsicExtentSchema,
- spatialDependency,
- spatialFrameSchema,
- spatialTypes,
-} from "@hypit/spatial";
-import { svsRecipeType } from "@hypit/svs";
-import { temporalDependency, temporalTypes } from "@hypit/temporal";
-import { temporalWindowAttributeVocabulary } from "@hypit/temporal-markup";
-
-const previewImage = (file: string) => ({
- mediaType: "image/png",
- path: `preview/${file}`,
- open: async () => Uint8Array.from(await readFile(new URL(`../preview/${file}`, import.meta.url))),
-});
-
-export const mediaTrackModuleRef = { name: "@hypit/media-track", version: "1" } as const;
-export const mediaTrackTypes = {
- header: { module: mediaTrackModuleRef, name: "MediaTrackHeader" },
- paintLayerSpec: { module: mediaTrackModuleRef, name: "MediaPaintLayerSpec" },
- sampleLayerSpec: { module: mediaTrackModuleRef, name: "MediaSampleLayerSpec" },
- layerSet: { module: mediaTrackModuleRef, name: "MediaLayerSet" },
- soundSpec: { module: mediaTrackModuleRef, name: "MediaSoundSpec" },
- soundSet: { module: mediaTrackModuleRef, name: "MediaSoundSet" },
- itemSpec: { module: mediaTrackModuleRef, name: "MediaItemSpec" },
- memberSpec: { module: mediaTrackModuleRef, name: "MediaSequenceMemberSpec" },
- memberSet: { module: mediaTrackModuleRef, name: "MediaSequenceMemberSet" },
- handoffSpec: { module: mediaTrackModuleRef, name: "MediaHandoffSpec" },
- sequenceSpec: { module: mediaTrackModuleRef, name: "MediaSequenceSpec" },
- set: { module: mediaTrackModuleRef, name: "MediaTrackSet" },
- program: { module: mediaTrackModuleRef, name: "MediaTrackProgram" },
-} satisfies Record<string, TypeRef>;
-
-export const mediaTrackProducers = {
- createLayers: { module: mediaTrackModuleRef, name: "create-media-layer-set" },
- appendPaintLayer: { module: mediaTrackModuleRef, name: "append-media-paint-layer" },
- appendStillLayer: { module: mediaTrackModuleRef, name: "append-still-media-layer" },
- appendTimedLayer: { module: mediaTrackModuleRef, name: "append-timed-media-layer" },
- appendSurfaceLayer: { module: mediaTrackModuleRef, name: "append-surface-media-layer" },
- createSounds: { module: mediaTrackModuleRef, name: "create-media-sound-set" },
- appendSound: { module: mediaTrackModuleRef, name: "append-media-sound" },
- createSet: { module: mediaTrackModuleRef, name: "create-media-track-set" },
- appendItem: { module: mediaTrackModuleRef, name: "append-media-item" },
- bindItemClipPath: { module: mediaTrackModuleRef, name: "bind-media-item-clip-path" },
- bindSequenceClipPath: { module: mediaTrackModuleRef, name: "bind-media-sequence-clip-path" },
- createMembers: { module: mediaTrackModuleRef, name: "create-media-sequence-member-set" },
- appendMember: { module: mediaTrackModuleRef, name: "append-media-sequence-member" },
- appendSequence: { module: mediaTrackModuleRef, name: "append-media-sequence" },
- finalize: { module: mediaTrackModuleRef, name: "finalize-media-track" },
- projectVisual: { module: mediaTrackModuleRef, name: "project-media-visual-track" },
- projectAudio: { module: mediaTrackModuleRef, name: "project-media-audio-track" },
-} satisfies Record<string, ProducerRef>;
-
-const string = { kind: "string", minLength: 1 } as const;
-const number = { kind: "number" } as const;
-const unsigned = { kind: "number", minimum: 0 } as const;
-const integer = { kind: "number", integer: true } as const;
-const unsignedInteger = { kind: "number", integer: true, minimum: 0 } as const;
-const positiveInteger = { kind: "number", integer: true, minimum: 1 } as const;
-const object = (fields: Readonly<Record<string, { readonly schema: ValueSchema; readonly optional?: boolean }>>): ValueSchema => ({ kind: "object", fields });
-const blob = object({
- kind: { schema: { kind: "literal", value: "blob" } },
- resource: { schema: { kind: "string", minLength: 5, maxLength: 256 } },
- size: { schema: unsignedInteger },
- mediaType: { schema: string },
-});
-const rational = object({ numerator: { schema: positiveInteger }, denominator: { schema: positiveInteger } });
-const extent = intrinsicExtentSchema;
-const trim = object({ startFrame: { schema: unsignedInteger }, endFrameExclusive: { schema: positiveInteger } });
-const occupancy: ValueSchema = { kind: "oneOf", variants: [
- ...["once", "hold", "loop"].map((mode) => object({
- mode: { schema: { kind: "literal", value: mode } },
- align: { schema: { kind: "string", enum: ["start", "end"] } },
- })),
- object({ mode: { schema: { kind: "literal", value: "stretch" } } }),
-] };
-const stops = { kind: "array", minItems: 2, items: object({ offset: { schema: unsigned }, color: { schema: string } }) } as const;
-const paint: ValueSchema = { kind: "oneOf", variants: [
- object({ kind: { schema: { kind: "literal", value: "solid" } }, color: { schema: string } }),
- object({ kind: { schema: { kind: "literal", value: "linear-gradient" } }, angleDeg: { schema: number }, stops: { schema: stops } }),
- object({ kind: { schema: { kind: "literal", value: "radial-gradient" } }, center: { schema: object({ x: { schema: unsigned }, y: { schema: unsigned } }) }, stops: { schema: stops } }),
-] };
-export const mediaSampleAppearanceSchema: ValueSchema = object({
- opacity: { schema: unsigned },
- filter: { schema: object({
- blurPx: { schema: unsigned }, brightness: { schema: unsigned }, contrast: { schema: unsigned }, saturation: { schema: unsigned },
- }) },
-});
-const samplingKeyframe = object({
- atProgress: { schema: { kind: "number", minimum: 0, maximum: 1 } }, zoom: { schema: { kind: "number", minimum: 0.000001 } },
- offsetX: { schema: number }, offsetY: { schema: number }, rotationDeg: { schema: number },
- easing: { schema: { kind: "string", enum: ["linear", "ease-in", "ease-out", "ease-in-out"] }, optional: true },
-});
-export const mediaSamplingMotionSchema: ValueSchema = object({
- keyframes: { schema: { kind: "array", minItems: 2, items: samplingKeyframe } },
-});
-export const mediaPaintLayerSpecSchema: ValueSchema = object({
-
- id: { schema: string }, paint: { schema: paint }, opacity: { schema: unsigned },
-});
-export const mediaSampleLayerSpecSchema: ValueSchema = object({
-
- id: { schema: string }, trim: { schema: trim, optional: true }, occupancy: { schema: occupancy, optional: true },
- appearance: { schema: mediaSampleAppearanceSchema }, samplingMotion: { schema: mediaSamplingMotionSchema, optional: true },
-});
-const audioSource = object({ artifact: { schema: blob }, sampleFrames: { schema: positiveInteger } });
-const visualSource: ValueSchema = { kind: "oneOf", variants: [
- object({ kind: { schema: { kind: "literal", value: "still" } }, artifact: { schema: blob }, extent: { schema: extent } }),
- object({
- kind: { schema: { kind: "literal", value: "timed" } }, artifact: { schema: blob }, extent: { schema: extent },
- frameRate: { schema: rational }, frameCount: { schema: positiveInteger }, audio: { schema: audioSource, optional: true },
- }),
- object({ kind: { schema: { kind: "literal", value: "surface" } }, surface: { schema: compositableSurfaceSchema }, extent: { schema: extent } }),
-] };
-const paintLayer = object({ id: { schema: string }, kind: { schema: { kind: "literal", value: "paint" } }, paint: { schema: paint }, opacity: { schema: unsigned } });
-const sampleLayer = object({
- id: { schema: string }, kind: { schema: { kind: "literal", value: "sample" } }, source: { schema: visualSource },
- sampling: { schema: visualTimedSamplingSchema, optional: true },
- fit: { schema: contentFitSchema }, trim: { schema: trim, optional: true }, occupancy: { schema: occupancy, optional: true },
- appearance: { schema: mediaSampleAppearanceSchema }, samplingMotion: { schema: mediaSamplingMotionSchema, optional: true },
-});
-const layer = { kind: "oneOf", variants: [paintLayer, sampleLayer] } as const;
-export const mediaLayerSetSchema: ValueSchema = object({
-
- layers: { schema: { kind: "array", items: layer } },
-});
-
-const path = { kind: "object", fields: {}, allowUnknown: true } as const;
-const clip: ValueSchema = { kind: "oneOf", variants: [
- object({ kind: { schema: { kind: "literal", value: "none" } } }),
- object({ kind: { schema: { kind: "literal", value: "frame" } } }),
- object({ kind: { schema: { kind: "literal", value: "rounded" } }, radiusPx: { schema: unsigned } }),
- object({ kind: { schema: { kind: "literal", value: "path" } }, path: { schema: path } }),
-] };
-const padding = object({ topPx: { schema: unsigned }, rightPx: { schema: unsigned }, bottomPx: { schema: unsigned }, leftPx: { schema: unsigned } });
-export const mediaFramePresentationSchema: ValueSchema = object({
- clip: { schema: clip }, padding: { schema: padding },
- border: { schema: object({ widthPx: { schema: unsigned }, style: { schema: { kind: "string", enum: ["solid", "dashed", "dotted"] } }, color: { schema: string } }), optional: true },
- shadows: { schema: { kind: "array", items: object({ offsetX: { schema: number }, offsetY: { schema: number }, blurPx: { schema: unsigned }, spreadPx: { schema: number }, color: { schema: string } }) } },
-});
-const edgeMotion = object({
- operator: { schema: { kind: "string", enum: ["fade", "slide", "scale", "pop", "bounce", "blur-reveal", "wipe", "flip", "spin"] } },
- durationFrames: { schema: positiveInteger }, easing: { schema: { kind: "string", enum: ["linear", "ease-in", "ease-out", "ease-in-out"] } },
- direction: { schema: { kind: "string", enum: ["left", "right", "up", "down"] }, optional: true }, amount: { schema: number, optional: true },
- origin: { schema: { kind: "literal", value: "outside-canvas" }, optional: true },
-});
-const sustainMotion = object({
- operator: { schema: { kind: "string", enum: ["float", "breathe", "pulse", "wobble", "shake", "drift"] } },
- amount: { schema: unsigned }, cycles: { schema: positiveInteger },
- direction: { schema: { kind: "string", enum: ["left", "right", "up", "down"] }, optional: true },
-});
-export const mediaLifecycleMotionSchema: ValueSchema = object({
- enter: { schema: edgeMotion, optional: true }, sustain: { schema: { kind: "array", items: sustainMotion } },
- exit: { schema: edgeMotion, optional: true },
-});
-const soundTrigger: ValueSchema = { kind: "oneOf", variants: [
- object({ kind: { schema: { kind: "literal", value: "enter" } } }),
- object({ kind: { schema: { kind: "literal", value: "exit" } } }),
- object({ kind: { schema: { kind: "literal", value: "handoff" } }, handoffId: { schema: string } }),
-] };
-export const mediaSoundSpecSchema: ValueSchema = object({
-
- id: { schema: string }, trigger: { schema: soundTrigger }, gain: { schema: unsigned },
-});
-const soundEvent = object({ id: { schema: string }, trigger: { schema: soundTrigger }, source: { schema: audioSource }, gain: { schema: unsigned } });
-export const mediaSoundSetSchema: ValueSchema = object({
-
- sounds: { schema: { kind: "array", items: soundEvent } },
-});
-export const mediaItemSpecSchema: ValueSchema = object({
- id: { schema: string },
- presentation: { schema: mediaFramePresentationSchema }, motion: { schema: mediaLifecycleMotionSchema }, stackingOrder: { schema: integer },
- sourceAudio: { schema: object({ fromLayer: { schema: string }, gain: { schema: unsigned } }), optional: true },
-});
-const sourceAudio = object({ fromLayer: { schema: string }, gain: { schema: unsigned } });
-export const mediaSequenceMemberSpecSchema: ValueSchema = object({
-
- id: { schema: string },
- sourceAudio: { schema: sourceAudio, optional: true },
-});
-const unresolvedMember = object({
- id: { schema: string }, activationFrame: { schema: unsignedInteger },
- layers: { schema: { kind: "array", minItems: 1, items: layer } },
- sourceAudio: { schema: sourceAudio, optional: true },
-});
-export const mediaSequenceMemberSetSchema: ValueSchema = object({
-
- members: { schema: { kind: "array", items: unresolvedMember } },
-});
-const direction = { kind: "string", enum: ["left", "right", "up", "down"] } as const;
-const handoffFields = {
- id: { schema: string }, fromMemberId: { schema: string }, toMemberId: { schema: string },
- operator: { schema: { kind: "string", enum: ["cut", "crossfade", "push", "wipe", "cover", "page-turn"] } },
- durationFrames: { schema: unsignedInteger }, boundaryRatio: { schema: unsigned },
- direction: { schema: direction, optional: true }, audio: { schema: { kind: "string", enum: ["cut", "crossfade"] } },
-} as const;
-export const mediaHandoffSpecSchema: ValueSchema = object({
- ...handoffFields,
-});
-export const mediaSequenceSpecSchema: ValueSchema = object({
-
- id: { schema: string }, presentation: { schema: mediaFramePresentationSchema },
- motion: { schema: mediaLifecycleMotionSchema }, stackingOrder: { schema: integer },
- handoffs: { schema: { kind: "array", minItems: 1, items: mediaHandoffSpecSchema } },
-});
-const frameSpan = object({ startFrame: { schema: unsignedInteger }, endFrameExclusive: { schema: positiveInteger } });
-const resolvedItem = object({
- id: { schema: string }, span: { schema: frameSpan }, frame: { schema: spatialFrameSchema },
- presentation: { schema: mediaFramePresentationSchema }, layers: { schema: { kind: "array", minItems: 1, items: layer } }, motion: { schema: mediaLifecycleMotionSchema },
- stacking: { schema: object({ order: { schema: integer }, tieBreak: { schema: string } }) },
- sourceAudio: { schema: object({ fromLayer: { schema: string }, gain: { schema: unsigned } }), optional: true },
- sounds: { schema: { kind: "array", items: soundEvent } },
-});
-const resolvedMember = object({
- id: { schema: string }, activationFrame: { schema: unsignedInteger }, logicalSpan: { schema: frameSpan },
- visualSpan: { schema: frameSpan }, layers: { schema: { kind: "array", minItems: 1, items: layer } },
- sourceAudio: { schema: sourceAudio, optional: true },
-});
-const resolvedHandoff = object({ ...handoffFields, span: { schema: frameSpan } });
-const resolvedSequence = object({
- id: { schema: string }, span: { schema: frameSpan }, terminalFrame: { schema: positiveInteger },
- frame: { schema: spatialFrameSchema }, presentation: { schema: mediaFramePresentationSchema },
- members: { schema: { kind: "array", minItems: 2, items: resolvedMember } },
- handoffs: { schema: { kind: "array", minItems: 1, items: resolvedHandoff } },
- motion: { schema: mediaLifecycleMotionSchema }, stacking: { schema: object({ order: { schema: integer }, tieBreak: { schema: string } }) },
- sounds: { schema: { kind: "array", items: soundEvent } },
-});
-export const mediaTrackSetSchema: ValueSchema = object({
- items: { schema: { kind: "array", items: resolvedItem } },
- sequences: { schema: { kind: "array", items: resolvedSequence } },
-});
-export const mediaTrackProgramSchema: ValueSchema = object({
- id: { schema: string },
- items: { schema: { kind: "array", items: resolvedItem } }, sequences: { schema: { kind: "array", items: resolvedSequence } },
-});
-export const mediaTrackHeaderSchema: ValueSchema = object({
- id: { schema: string },
-});
-
-const itemInputs = [
- { name: "set", type: mediaTrackTypes.set }, { name: "header", type: mediaTrackTypes.header },
- { name: "timeline", type: timelineTypes.track }, { name: "canvas", type: spatialTypes.canvas },
- { name: "layers", type: mediaTrackTypes.layerSet },
- { name: "frame", type: spatialTypes.frame }, { name: "spec", type: mediaTrackTypes.itemSpec },
- { name: "sounds", type: mediaTrackTypes.soundSet }, { name: "window", type: temporalTypes.window },
-] as const;
-const memberInputs = [
- { name: "members", type: mediaTrackTypes.memberSet }, { name: "timeline", type: timelineTypes.track }, { name: "layers", type: mediaTrackTypes.layerSet },
- { name: "spec", type: mediaTrackTypes.memberSpec }, { name: "activation", type: temporalTypes.instant },
-] as const;
-const sequenceInputs = [
- { name: "set", type: mediaTrackTypes.set }, { name: "header", type: mediaTrackTypes.header },
- { name: "timeline", type: timelineTypes.track }, { name: "canvas", type: spatialTypes.canvas },
- { name: "members", type: mediaTrackTypes.memberSet },
- { name: "frame", type: spatialTypes.frame }, { name: "spec", type: mediaTrackTypes.sequenceSpec },
- { name: "sounds", type: mediaTrackTypes.soundSet }, { name: "terminal", type: temporalTypes.instant },
-] as const;
-
-const appearanceRecipeProperties = [
- { name: "fit", required: false, fallback: "contain",
- values: ["contain", "cover", "fit-width", "fit-height", "native", "scale-down", "stretch"],
- summary: "Scales the source into the fitting area left inside the Frame after border and padding." },
- { name: "frame-x", required: false, fallback: "0.5",
- summary: "Places the destination alignment point across the fitting area, from 0 at its left edge to 1 at its right." },
- { name: "frame-y", required: false, fallback: "0.5",
- summary: "Places the destination alignment point down the fitting area, from 0 at its top edge to 1 at its bottom." },
- { name: "content-x", required: false, fallback: "0.5",
- summary: "Places the anchor point across the scaled source, from 0 at its left edge to 1 at its right." },
- { name: "content-y", required: false, fallback: "0.5",
- summary: "Places the anchor point down the scaled source, from 0 at its top edge to 1 at its bottom." },
- { name: "fit-offset-x", required: false, fallback: "0",
- summary: "Shifts the fitted source horizontally in pixels once the two anchor points meet." },
- { name: "fit-offset-y", required: false, fallback: "0",
- summary: "Shifts the fitted source vertically in pixels once the two anchor points meet." },
- { name: "fit-constraint", required: false, values: ["bounded", "free"], fallback: "bounded",
- summary: "With bounded, large content keeps the fitting area covered on each axis and small content stays inside it; free preserves the authored alignment and offsets. Clipping is controlled separately." },
- { name: "opacity", required: false, fallback: "1",
- summary: "Sets how opaque the sampled picture is drawn." },
- { name: "blur", required: false, fallback: "0",
- summary: "Blurs the sampled picture by a pixel radius." },
- { name: "brightness", required: false, fallback: "1",
- summary: "Scales the brightness of the sampled picture." },
- { name: "contrast", required: false, fallback: "1",
- summary: "Scales the contrast of the sampled picture." },
- { name: "saturation", required: false, fallback: "1",
- summary: "Scales the saturation of the sampled picture." },
- { name: "playback", required: false, fallback: "once-start",
- values: ["once-start", "once-end", "hold-start", "hold-end", "loop-start", "loop-end", "stretch"],
- summary: "Decides how timed material occupies a window it does not match and which edge it aligns to." },
- { name: "trim-start", required: false,
- summary: "Starts timed material at this whole frame of its own timeline, and is written with `trim-end`." },
- { name: "trim-end", required: false,
- summary: "Ends timed material before this whole frame of its own timeline, and is written with `trim-start`." },
- { name: "stack-order", required: true,
- summary: "Sets this unit's absolute stacking order in the Film, higher drawing in front." },
- { name: "clip", required: false, values: ["none", "frame", "rounded"], fallback: "frame",
- summary: "Decides how the picture is clipped to the Frame." },
- { name: "radius", required: false, fallback: "0",
- summary: "Rounds the clipped corners by a pixel radius, and is read only for a `rounded` clip." },
- { name: "padding", required: false, fallback: "0",
- summary: "Insets the picture from the Frame edges. It admits one, two or four values — all sides, then vertical and horizontal, then each side — which no single number can carry, so it is written as text: `padding: \"14\"` and `padding: \"8 12\"`. A bare number is refused." },
- { name: "border-width", required: false, fallback: "0",
- summary: "Draws a border of this pixel width, and draws none at `0`." },
- { name: "border-style", required: false, values: ["solid", "dashed", "dotted"], fallback: "solid",
- summary: "Chooses how the border is stroked." },
- { name: "border-color", required: false,
- summary: "Paints the border, which a non-zero `border-width` requires." },
- { name: "shadows", required: false, fallback: "none",
- summary: "Casts shadows behind the Frame, written as `x y blur spread color` entries separated by semicolons." },
- { name: "frame-paint", required: false, fallback: "transparent",
- summary: "Fills the whole Frame behind every layer with a color, `linear(angle;stops)` or `radial(x,y;stops)`." },
-] as const;
-
-const motionRecipeProperties = [
- { name: "enter", required: false, fallback: "none",
- values: ["none", "fade", "slide", "scale", "pop", "bounce", "blur-reveal", "wipe", "flip", "spin"],
- summary: "Chooses the operator the unit enters on." },
- { name: "enter-frames", required: false,
- summary: "Sets how many frames the entrance runs, which every entrance operator requires." },
- { name: "enter-easing", required: false, values: ["linear", "ease-in", "ease-out", "ease-in-out"], fallback: "ease-in-out",
- summary: "Shapes how the entrance accelerates." },
- { name: "enter-direction", required: false, values: ["left", "right", "up", "down"],
- summary: "Points a directional entrance the way it travels." },
- { name: "enter-amount", required: false,
- summary: "Sets how far the entrance operator displaces the unit." },
- { name: "enter-origin", required: false, values: ["outside-canvas"],
- summary: "Starts the entrance beyond the Canvas rather than at the Frame." },
- { name: "sustain", required: false, fallback: "none",
- summary: "Holds the unit in continuous motion for its whole window, written as `operator amount cycles` entries, each taking an optional direction, separated by commas." },
- { name: "exit", required: false, fallback: "none",
- values: ["none", "fade", "slide", "scale", "pop", "bounce", "blur-reveal", "wipe", "flip", "spin"],
- summary: "Chooses the operator the unit leaves on." },
- { name: "exit-frames", required: false,
- summary: "Sets how many frames the exit runs, which every exit operator requires." },
- { name: "exit-easing", required: false, values: ["linear", "ease-in", "ease-out", "ease-in-out"], fallback: "ease-in-out",
- summary: "Shapes how the exit accelerates." },
- { name: "exit-direction", required: false, values: ["left", "right", "up", "down"],
- summary: "Points a directional exit the way it travels." },
- { name: "exit-amount", required: false,
- summary: "Sets how far the exit operator displaces the unit." },
- { name: "exit-origin", required: false, values: ["outside-canvas"],
- summary: "Sends the exit beyond the Canvas rather than to the Frame." },
-] as const;
-
-export const mediaTrackMarkupSurfaces = [{
- name: "track", tag: "Track", mode: "structured",
- outputs: [spatialTypes.fit, mediaTrackTypes.header, mediaTrackTypes.paintLayerSpec, mediaTrackTypes.sampleLayerSpec,
- mediaTrackTypes.layerSet, mediaTrackTypes.soundSpec, mediaTrackTypes.soundSet,
- mediaTrackTypes.itemSpec, mediaTrackTypes.memberSpec, mediaTrackTypes.memberSet,
- mediaTrackTypes.handoffSpec, mediaTrackTypes.sequenceSpec, mediaTrackTypes.set,
- temporalTypes.instantSpec, temporalTypes.windowSpec, temporalTypes.instant, temporalTypes.window, mediaTrackTypes.program,
- compositionTypes.visualTrack, compositionTypes.audioTrack],
- vocabulary: {
- summary: "Show the timeline performance, place independent media Items, and compose replacement Sequences on a shared film time axis and Canvas. Publishes a VisualTrack and, when audio is authored, an AudioTrack.",
- appearance: "Pictures and layered compositions occupy authored Frames on the Canvas. Each source is scaled and aligned inside its Frame's border and padding; a contain fit can leave space, while cover can crop. Paint and sampled Layers draw in Source order under a shared rectangular, rounded or Path clip, with optional border and shadows. Lifecycle motion moves the framed unit; Sampling pans, zooms or rotates the picture inside it. Each Item has an independent window. A Sequence shares one outer Frame while Members replace its contents through cut, crossfade, push, wipe, cover or page-turn Handoffs. Source playback determines whether moving content covers the whole assigned span. Absolute stack order decides which overlapping unit draws in front.",
- preview: previewImage("Track.png"),
- attributes: [
- { name: "id", kind: "identifier", required: true,
- summary: "Names this Track and prefixes the identity of every Item, Sequence, layer and sound that does not name itself." },
- ...temporalContextAttributeVocabulary,
- { name: "canvas", kind: "reference", required: true, accepts: [spatialTypes.canvas],
- summary: "Chooses the Canvas every Frame on this Track is measured inside." },
- ],
- children: [
- { tag: "Item", cardinality: "many",
- summary: "One independently timed picture on its own Frame, from a direct source or ordered Paint and Layer children, carrying its own Sampling and Sound children.",
- attributes: [
- { name: "id", kind: "identifier", required: false,
- summary: "Names this Item; the Track derives `<track>.item.<index>` when it is absent." },
- { name: "frame", kind: "reference", required: true, accepts: [spatialTypes.frame],
- summary: "Chooses the Frame the Item occupies on the Canvas." },
- { name: "appearance", kind: "reference", required: true, accepts: [svsRecipeType],
- summary: "Chooses the Recipe for fitting, source occupancy, frame Paint, clipping, borders and shadows, and the Recipe every sample Layer falls back to.",
- recipe: appearanceRecipeProperties },
- { name: "motion", kind: "reference", required: false, accepts: [svsRecipeType],
- summary: "Chooses the Recipe for the whole Item's enter, sustain and exit motion.",
- recipe: motionRecipeProperties },
- { name: "clip", kind: "reference", required: false, accepts: [spatialTypes.path],
- summary: "Clips the Item to an authored Path." },
- { name: "image", kind: "reference", required: false, accepts: [artifactTypes.blob],
- summary: "Shows a durationless still image as the Item's direct source." },
- { name: "media", kind: "reference", required: false, accepts: [mediaTypes.synchronized],
- summary: "Shows an explicitly prepared timed source." },
- { name: "surface", kind: "reference", required: false, accepts: [mediaTypes.compositableSurface],
- summary: "Shows an alpha-aware still or timed Surface." },
- { name: "extent", kind: "reference", required: false, accepts: [spatialTypes.extent],
- summary: "Gives the still image its authored pixel Extent. The `fit` scales this Extent into the Frame, so what it decides is the shape: its width-to-height ratio has to be the picture's, and the pixel numbers themselves only have to hold that ratio. A generated picture's own size is the generator's to choose and is not knowable when the Source is written, so write the ratio you asked that generator for." },
- { name: "source-audio", kind: "literal", required: false,
- summary: "Names the layer whose source audio this Item emits." },
- { name: "audio-gain", kind: "literal", required: false,
- summary: "Scales the selected source audio by a linear gain; defaults to `1`." },
- ...temporalWindowAttributeVocabulary,
- ] },
- { tag: "Sequence", cardinality: "many",
- summary: "One Frame whose Members replace each other at explicit activation points, written as ordered Member, Handoff and Sound children.",
- attributes: [
- { name: "id", kind: "identifier", required: false,
- summary: "Names this Sequence; the Track derives `<track>.sequence.<index>` when it is absent." },
- { name: "frame", kind: "reference", required: true, accepts: [spatialTypes.frame],
- summary: "Chooses the Frame every Member occupies." },
- { name: "appearance", kind: "reference", required: true, accepts: [svsRecipeType],
- summary: "Chooses the Recipe for fitting, frame Paint, clipping, borders and shadows, and the Recipe every Member falls back to.",
- recipe: appearanceRecipeProperties },
- { name: "motion", kind: "reference", required: false, accepts: [svsRecipeType],
- summary: "Chooses the Recipe for the whole Sequence's enter, sustain and exit motion.",
- recipe: motionRecipeProperties },
- { name: "clip", kind: "reference", required: false, accepts: [spatialTypes.path],
- summary: "Clips the Sequence to an authored Path." },
- { name: "until", kind: "expression", required: true,
- accepts: [narrativeTypes.moment, narrativeTypes.selection, narrativeTypes.excerpt],
- summary: "Ends the Sequence at a Moment, a Selection/Segment boundary, or an authored time such as 8s." },
- { name: "until-boundary", kind: "literal", required: false, values: ["start", "end"],
- summary: "Chooses which edge of the ending Selection or Segment ends the Sequence; defaults to `end` and is refused for a Moment." },
- ] },
- ],
- ports: [
- { name: "program", type: mediaTrackTypes.program,
- summary: "The resolved Item and Sequence schedule consumed by both rendered facets." },
- { name: "visual", type: compositionTypes.visualTrack,
- summary: "The rendered picture, an ordinary peer VisualTrack." },
- { name: "audio", type: compositionTypes.audioTrack,
- summary: "The rendered sound, published only when a source audio selection or a Sound is authored." },
- ],
- example: `<pipeline:Normalize id="cutaway-bags" source={bags-take.video}
- video="primary-moving" audio="none" span-authority="video" clock={clock}/>
-
-<media-track:Track id="cutaways" timeline={speech.timeline} canvas={vertical}>
- <media-track:Item media={prepared.media} during="program" frame={full} appearance={recipes.media.clip}/>
- <media-track:Item id="bags" media={cutaway-bags.media} during={story.selection.bags}
- frame={full} appearance={recipes.media.cutaway} motion={recipes.motion.cut}/>
-</media-track:Track>`,
- notes: [
- "A Track requires at least one Item or Sequence and accepts no text content.",
- "Item use one window form: `during`, `at` with `for`, `until` with `for`, or `start` with `end`. Bind `selection`, `segment` and/or `moment` only when the start/end expressions use them; different endpoints can use different bindings.",
- "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.",
- "A unit that names a direct source names exactly one of `image`, `media` or `surface`; `extent` is required with `image` and refused otherwise.",
- "`audio-gain` is refused without selected source audio.",
- "`clip` is refused on a Item or Sequence whose Recipe already states a clip.",
- "An `appearance` or `motion` Recipe is refused when it carries a property outside its own set.",
- "`playback`, `trim-start` and `trim-end` are refused on durationless still material, and `trim-start` and `trim-end` are written together or not at all.",
- "An `enter` or an `exit` operator requires its own `enter-frames` or `exit-frames`.",
- "An Item written with a direct source accepts `<Sampling>` and `<Sound>` children; an Item written without one accepts `<Paint>`, `<Layer>` and `<Sound>` children, and requires at least one Paint or Layer.",
- "A Sequence requires at least two `<Member>` children, exactly one `<Handoff>` for every adjacent Member pair, and accepts `<Sound>` children.",
- "Sequence `until` selects a Moment, a Selection or Segment boundary, or an authored time such as 8s. `until-boundary` defaults to end for a Selection or Segment.",
- "A Member is one picture in the replacement order:",
- [
- "| Attribute | Kind | Required | Meaning |",
- "|---|---|---|---|",
- "| `id` | identifier | no | Names this Member; the Sequence derives `<sequence>.member.<index>` otherwise |",
- "| `at` | reference or time | one timing form | A Moment, Selection or Segment boundary, or an authored time that activates this Member |",
- "| `boundary` | literal (start, end) | with a Selection or Segment | Which edge activates this Member; refused for a Moment |",
- "| `instant` | expression | one timing form | Explicit point expression instead of `at`; bind selection, segment or moment if the expression uses it |",
- "| `appearance` | reference (@hypit/svs@1#Recipe) | no | This Member's own Recipe in place of the Sequence's |",
- "| `image` | reference (@hypit/artifact@1#BlobArtifact) | one source form | A durationless still image, which also requires `extent` |",
- "| `media` | reference (@hypit/media@1#SynchronizedMedia) | one source form | An explicitly prepared timed source |",
- "| `surface` | reference (@hypit/media@1#CompositableSurfaceRef) | one source form | An alpha-aware still or timed Surface |",
- "| `extent` | reference (@hypit/spatial@1#IntrinsicExtent) | with `image` | The authored pixel extent of the still image |",
- "| `source-audio` | literal | no | Names the layer whose source audio this Member emits |",
- "| `audio-gain` | literal | with selected source audio | Linear gain applied to the selected source audio; defaults to `1` |",
- ].join("\n"),
- "A Member written with a direct source accepts `<Sampling>` children; a Member written without one accepts `<Paint>` and `<Layer>` children, and requires at least one of them.",
- "A Member `appearance` Recipe accepts the same properties as its Sequence's, of which the fit properties, the sample properties and `frame-paint` are read; clipping, padding, borders, shadows and `stack-order` stay with the Sequence Recipe.",
- "A Handoff is written empty and carries the transition between one Member pair:",
- [
- "| Attribute | Kind | Required | Meaning |",
- "|---|---|---|---|",
- "| `id` | identifier | no | Names this Handoff; the Sequence derives `<sequence>.handoff.<index>` otherwise |",
- "| `from` | literal | yes | The outgoing Member id; Handoffs are ordered by adjacent Member pair |",
- "| `transition` | reference (@hypit/svs@1#Recipe) | yes | The Recipe for the handoff operator, its length, its boundary and its audio treatment |",
- ].join("\n"),
- "A `transition` Recipe carries exactly these properties:",
- [
- "| Property | Required | Default | Meaning |",
- "|---|---|---|---|",
- "| `operator` | yes | — | How the outgoing Member gives way to the incoming one. One of cut, crossfade, push, wipe, cover, page-turn. |",
- "| `duration-frames` | yes | — | How many frames the handoff runs. |",
- "| `boundary-ratio` | no | `0.5` | Where the activation point sits inside the handoff, from 0 at its first frame to 1 at its last. |",
- "| `direction` | no | — | Points a directional handoff the way it travels. One of left, right, up, down. |",
- "| `audio` | no | `cut` | Decides whether source audio cuts or crossfades across the handoff. One of cut, crossfade. |",
- ].join("\n"),
- "A Paint child is written empty and paints one layer:",
- [
- "| Attribute | Kind | Required | Meaning |",
- "|---|---|---|---|",
- "| `id` | identifier | no | Names this layer; the Track derives one from the unit and the layer position otherwise |",
- "| `appearance` | reference (@hypit/svs@1#Recipe) | yes | The solid or gradient paint and the opacity this layer is filled with |",
- ].join("\n"),
- "A Paint `appearance` Recipe carries exactly these properties:",
- [
- "| Property | Required | Default | Meaning |",
- "|---|---|---|---|",
- "| `paint` | yes | — | Fills the layer with a color, `linear(angle;stops)` or `radial(x,y;stops)`, each gradient carrying at least two `color@offset` stops. |",
- "| `opacity` | no | `1` | Sets how opaque the fill is drawn. |",
- ].join("\n"),
- "A Layer child samples one source into the unit's Frame:",
- [
- "| Attribute | Kind | Required | Meaning |",
- "|---|---|---|---|",
- "| `id` | identifier | no | Names this layer, which `source-audio` selects by; the Track derives one from the unit and the layer position otherwise |",
- "| `image` | reference (@hypit/artifact@1#BlobArtifact) | one source form | A durationless still image, which also requires `extent` |",
- "| `media` | reference (@hypit/media@1#SynchronizedMedia) | one source form | An explicitly prepared timed source |",
- "| `surface` | reference (@hypit/media@1#CompositableSurfaceRef) | one source form | An alpha-aware still or timed Surface |",
- "| `extent` | reference (@hypit/spatial@1#IntrinsicExtent) | with `image` | The authored pixel extent of the still image |",
- "| `appearance` | reference (@hypit/svs@1#Recipe) | no | This layer's own Recipe in place of the unit's |",
- ].join("\n"),
- "A Layer `appearance` Recipe carries the fit properties and the sample properties and nothing else, so a Layer states its own Recipe rather than inheriting the unit's, which requires `stack-order`.",
- "A Sampling child is written empty and states one keyframe of sampling motion:",
- [
- "| Attribute | Kind | Required | Meaning |",
- "|---|---|---|---|",
- "| `at` | literal | yes | Where the keyframe sits in the unit's window, written as `start`, `end` or a percentage inside `0%`..`100%` |",
- "| `zoom` | literal | no | The sampling scale at this keyframe; defaults to `1` |",
- "| `x` | literal | no | The horizontal sampling offset at this keyframe; defaults to `0` |",
- "| `y` | literal | no | The vertical sampling offset at this keyframe; defaults to `0` |",
- "| `rotate` | literal | no | The sampling rotation in degrees at this keyframe; defaults to `0` |",
- "| `easing` | literal (linear, ease-in, ease-out, ease-in-out) | no | How the sampling moves out of this keyframe |",
- ].join("\n"),
- "A Sound child is written empty and plays one prepared source on one trigger:",
- [
- "| Attribute | Kind | Required | Meaning |",
- "|---|---|---|---|",
- "| `id` | identifier | no | Names this sound; the Track derives one from the unit and the sound position otherwise |",
- "| `source` | reference (@hypit/media@1#SynchronizedMedia) | yes | The explicitly prepared audio this sound plays |",
- "| `at` | literal (enter, exit) | one trigger form | Plays the sound as the unit enters or as it exits |",
- "| `handoff` | literal | one trigger form | Plays the sound on the named Handoff of the surrounding Sequence |",
- "| `gain` | literal | no | Linear gain applied to this sound; defaults to `1` |",
- ].join("\n"),
- "A Sound states exactly one trigger form, and `handoff` only names a Handoff of the Sequence it is written in.",
- "A direct prepared source is sampled into a layer named `content`; use `source-audio=\"content\"` to include its audio. Layered units select a Layer id. Raw `video` and `audio=\"include\"` attributes are not accepted.",
- ],
- },
- }] as const;
-
-
-export const mediaTrackManifest: ModuleManifest = {
- format: "hypit.module@1",
- name: mediaTrackModuleRef.name,
- version: mediaTrackModuleRef.version,
- dependencies: [
- artifactDependency,
- mediaDependency,
- narrativeDependency,
- timelineDependency,
- temporalDependency,
- spatialDependency,
- compositionDependency,
- ],
- types: [
- { name: mediaTrackTypes.header.name },
- { name: mediaTrackTypes.paintLayerSpec.name },
- { name: mediaTrackTypes.sampleLayerSpec.name },
- { name: mediaTrackTypes.layerSet.name },
- { name: mediaTrackTypes.soundSpec.name },
- { name: mediaTrackTypes.soundSet.name },
- { name: mediaTrackTypes.itemSpec.name },
- { name: mediaTrackTypes.memberSpec.name },
- { name: mediaTrackTypes.memberSet.name },
- { name: mediaTrackTypes.handoffSpec.name },
- { name: mediaTrackTypes.sequenceSpec.name },
- { name: mediaTrackTypes.set.name },
- { name: mediaTrackTypes.program.name },
- ],
- capabilities: [],
- producers: [
- { name: mediaTrackProducers.createLayers.name, inputs: [], outputs: [{ name: "layers", type: mediaTrackTypes.layerSet }], needs: [] },
- { name: mediaTrackProducers.appendPaintLayer.name, inputs: [{ name: "layers", type: mediaTrackTypes.layerSet }, { name: "spec", type: mediaTrackTypes.paintLayerSpec }], outputs: [{ name: "layers", type: mediaTrackTypes.layerSet }], needs: [] },
- { name: mediaTrackProducers.appendStillLayer.name, inputs: [{ name: "layers", type: mediaTrackTypes.layerSet }, { name: "source", type: artifactTypes.blob }, { name: "extent", type: spatialTypes.extent }, { name: "fit", type: spatialTypes.fit }, { name: "spec", type: mediaTrackTypes.sampleLayerSpec }], outputs: [{ name: "layers", type: mediaTrackTypes.layerSet }], needs: [] },
- { name: mediaTrackProducers.appendTimedLayer.name, inputs: [{ name: "layers", type: mediaTrackTypes.layerSet }, { name: "source", type: mediaTypes.synchronized }, { name: "fit", type: spatialTypes.fit }, { name: "spec", type: mediaTrackTypes.sampleLayerSpec }], outputs: [{ name: "layers", type: mediaTrackTypes.layerSet }], needs: [] },
- { name: mediaTrackProducers.appendSurfaceLayer.name, inputs: [{ name: "layers", type: mediaTrackTypes.layerSet }, { name: "source", type: mediaTypes.compositableSurface }, { name: "fit", type: spatialTypes.fit }, { name: "spec", type: mediaTrackTypes.sampleLayerSpec }], outputs: [{ name: "layers", type: mediaTrackTypes.layerSet }], needs: [] },
- { name: mediaTrackProducers.createSounds.name, inputs: [], outputs: [{ name: "sounds", type: mediaTrackTypes.soundSet }], needs: [] },
- { name: mediaTrackProducers.appendSound.name, inputs: [{ name: "sounds", type: mediaTrackTypes.soundSet }, { name: "source", type: mediaTypes.synchronized }, { name: "spec", type: mediaTrackTypes.soundSpec }], outputs: [{ name: "sounds", type: mediaTrackTypes.soundSet }], needs: [] },
- { name: mediaTrackProducers.createSet.name, inputs: [], outputs: [{ name: "set", type: mediaTrackTypes.set }], needs: [] },
- { name: mediaTrackProducers.appendItem.name, inputs: itemInputs, outputs: [{ name: "set", type: mediaTrackTypes.set }], needs: [] },
- { name: mediaTrackProducers.bindItemClipPath.name, inputs: [{ name: "spec", type: mediaTrackTypes.itemSpec }, { name: "path", type: spatialTypes.path }], outputs: [{ name: "spec", type: mediaTrackTypes.itemSpec }], needs: [] },
- { name: mediaTrackProducers.bindSequenceClipPath.name, inputs: [{ name: "spec", type: mediaTrackTypes.sequenceSpec }, { name: "path", type: spatialTypes.path }], outputs: [{ name: "spec", type: mediaTrackTypes.sequenceSpec }], needs: [] },
- { name: mediaTrackProducers.createMembers.name, inputs: [], outputs: [{ name: "members", type: mediaTrackTypes.memberSet }], needs: [] },
- { name: mediaTrackProducers.appendMember.name, inputs: memberInputs, outputs: [{ name: "members", type: mediaTrackTypes.memberSet }], needs: [] },
- { name: mediaTrackProducers.appendSequence.name, inputs: sequenceInputs, outputs: [{ name: "set", type: mediaTrackTypes.set }], needs: [] },
- { name: mediaTrackProducers.finalize.name, inputs: [{ name: "set", type: mediaTrackTypes.set }, { name: "header", type: mediaTrackTypes.header }, { name: "timeline", type: timelineTypes.track }], outputs: [{ name: "program", type: mediaTrackTypes.program }], needs: [] },
- { name: mediaTrackProducers.projectVisual.name, inputs: [{ name: "timeline", type: timelineTypes.track }, { name: "program", type: mediaTrackTypes.program }], outputs: [{ name: "track", type: compositionTypes.visualTrack }], needs: [] },
- { name: mediaTrackProducers.projectAudio.name, inputs: [{ name: "timeline", type: timelineTypes.track }, { name: "program", type: mediaTrackTypes.program }], outputs: [{ name: "track", type: compositionTypes.audioTrack }], needs: [] },
- ],
-};
-
-export const mediaTrackDependency = { module: mediaTrackModuleRef } as const;
diff --git a/packages/media-track/src/motion.ts b/packages/media-track/src/motion.ts
deleted file mode 100644
index 48ddf6f8..00000000
--- a/packages/media-track/src/motion.ts
+++ /dev/null
@@ -1,387 +0,0 @@
-import type {
- VisualAnimation,
- VisualEasing,
- VisualStyleDeclaration,
-} from "@hypit/composition";
-
-import type {
- MediaEdgeMotion,
- MediaLifecycleMotion,
- MediaMotionDirection,
- MediaSamplingMotion,
- MediaSustainMotion,
-} from "./types.js";
-import type { CanvasSpace, SpatialFrame } from "@hypit/spatial";
-
-function assert(condition: unknown, message: string): asserts condition {
- if (!condition) throw new Error(message);
-}
-
-function finite(value: number, label: string): void {
- assert(Number.isFinite(value), `${label} must be finite.`);
-}
-
-function direction(value: MediaMotionDirection | undefined, label: string): void {
- if (value !== undefined) assert(["left", "right", "up", "down"].includes(value), `${label} is invalid.`);
-}
-
-export function assertMediaEdgeMotion(value: MediaEdgeMotion, label: string): void {
- assert(["fade", "slide", "scale", "pop", "bounce", "blur-reveal", "wipe", "flip", "spin"].includes(value.operator),
- `${label}.operator is invalid.`);
- assert(Number.isSafeInteger(value.durationFrames) && value.durationFrames > 0,
- `${label}.durationFrames must be positive.`);
- assert(["linear", "ease-in", "ease-out", "ease-in-out"].includes(value.easing), `${label}.easing is invalid.`);
- direction(value.direction, `${label}.direction`);
- if (["slide", "wipe", "flip"].includes(value.operator)) {
- assert(value.direction !== undefined, `${label}.${value.operator} requires direction.`);
- }
- if (value.amount !== undefined) finite(value.amount, `${label}.amount`);
- if (value.origin !== undefined) {
- assert(value.origin === "outside-canvas" && value.operator === "slide",
- `${label}.origin is supported only by slide.`);
- assert(value.amount === undefined, `${label} cannot combine amount with outside-canvas.`);
- }
-}
-
-function outsideCanvasAmount(directionValue: MediaMotionDirection, frame: SpatialFrame, canvas: CanvasSpace): number {
- if (directionValue === "left") return frame.xPx + frame.widthPx;
- if (directionValue === "right") return canvas.widthPx - frame.xPx;
- if (directionValue === "up") return frame.yPx + frame.heightPx;
- return canvas.heightPx - frame.yPx;
-}
-
-export function resolveMediaLifecycleMotion(
- value: MediaLifecycleMotion,
- frame: SpatialFrame,
- canvas: CanvasSpace,
-): MediaLifecycleMotion {
- const edge = (motion: MediaEdgeMotion | undefined): MediaEdgeMotion | undefined => {
- if (motion === undefined || motion.origin === undefined) return motion === undefined ? undefined : structuredClone(motion);
- return {
- operator: motion.operator,
- durationFrames: motion.durationFrames,
- easing: motion.easing,
- ...(motion.direction === undefined ? {} : { direction: motion.direction }),
- amount: outsideCanvasAmount(motion.direction!, frame, canvas),
- };
- };
- return {
- ...(value.enter === undefined ? {} : { enter: edge(value.enter)! }),
- sustain: structuredClone(value.sustain),
- ...(value.exit === undefined ? {} : { exit: edge(value.exit)! }),
- };
-}
-
-export function assertMediaSustainMotion(value: MediaSustainMotion, label: string): void {
- assert(["float", "breathe", "pulse", "wobble", "shake", "drift"].includes(value.operator),
- `${label}.operator is invalid.`);
- finite(value.amount, `${label}.amount`);
- assert(value.amount >= 0, `${label}.amount must be non-negative.`);
- assert(Number.isSafeInteger(value.cycles) && value.cycles > 0 && value.cycles <= 100,
- `${label}.cycles must be inside [1, 100].`);
- direction(value.direction, `${label}.direction`);
- if (value.operator === "drift") assert(value.direction !== undefined, `${label}.drift requires direction.`);
-}
-
-export function assertMediaLifecycleMotion(value: MediaLifecycleMotion, durationFrames: number, label: string): void {
- assert(Number.isSafeInteger(durationFrames) && durationFrames > 0, `${label} duration is invalid.`);
- if (value.enter !== undefined) assertMediaEdgeMotion(value.enter, `${label}.enter`);
- if (value.exit !== undefined) assertMediaEdgeMotion(value.exit, `${label}.exit`);
- for (const [index, sustain] of value.sustain.entries()) assertMediaSustainMotion(sustain, `${label}.sustain.${index}`);
-}
-
-type MotionState = {
- readonly opacity: number;
- readonly transform: string;
- readonly filter: string;
- readonly clipPath: string;
-};
-
-const neutral: MotionState = {
- opacity: 1,
- transform: "none",
- filter: "none",
- clipPath: "inset(0% 0% 0% 0%)",
-};
-
-function translate(directionValue: MediaMotionDirection, amount: number): string {
- if (directionValue === "left") return `translateX(${-amount}px)`;
- if (directionValue === "right") return `translateX(${amount}px)`;
- if (directionValue === "up") return `translateY(${-amount}px)`;
- return `translateY(${amount}px)`;
-}
-
-/**
- * `clipping` is decided once per animation, not per keyframe.
- *
- * `inset(0% 0% 0% 0%)` reads as a no-op and is not one: it clips the element and its descendants to
- * the border box, which removes the Frame's own drop shadows for the whole window. So an Item given
- * any lifecycle at all — a plain fade among them — lost its shadows, while the same Item with no
- * enter or exit kept them.
- *
- * Every keyframe of one animation has to declare the same properties, so a wipe cannot drop the
- * property on the frames where it happens to be neutral: it would hold its last declared inset for
- * ever. The question is whether this animation clips anywhere.
- */
-function style(state: MotionState, clipping: boolean): VisualStyleDeclaration[] {
- return [
- ...(clipping ? [{ name: "clip-path", value: state.clipPath }] : []),
- { name: "filter", value: state.filter },
- { name: "opacity", value: state.opacity },
- { name: "transform", value: state.transform },
- ];
-}
-
-export function lifecycleAnimation(value: MediaLifecycleMotion, durationFrames: number): VisualAnimation | undefined {
- assertMediaLifecycleMotion(value, durationFrames, "Media lifecycle");
- if (value.enter === undefined && value.exit === undefined) return undefined;
- const frames = new Set<number>([0, durationFrames]);
- if (value.enter !== undefined) {
- for (let frame = 0; frame <= Math.min(durationFrames, value.enter.durationFrames); frame += 1) frames.add(frame);
- }
- if (value.exit !== undefined) {
- for (let frame = Math.max(0, durationFrames - value.exit.durationFrames); frame <= durationFrames; frame += 1) frames.add(frame);
- }
- const ordered = [...frames].sort((left, right) => left - right);
- const clipping = ordered.some((atFrame) => lifecycleStateAt(value, durationFrames, atFrame).clipPath !== neutral.clipPath);
- return {
- keyframes: ordered.map((atFrame) => ({
- atFrame,
- easing: "linear",
- style: style(lifecycleStateAt(value, durationFrames, atFrame), clipping),
- })),
- };
-}
-
-function clean(value: number): number {
- const rounded = Math.round(value * 1_000_000) / 1_000_000;
- return Object.is(rounded, -0) ? 0 : rounded;
-}
-
-function sustainTransform(value: MediaSustainMotion, phase: number): string {
- const amount = value.amount * phase;
- switch (value.operator) {
- case "float": return `translateY(${amount}px)`;
- case "breathe": return `scale(${1 + amount})`;
- case "pulse": return `scale(${1 + amount})`;
- case "wobble": return `rotate(${amount}deg)`;
- case "shake": return `translateX(${amount}px)`;
- case "drift": return translate(value.direction!, Math.abs(amount) * (phase < 0 ? -1 : 1));
- }
-}
-
-function sustainPhases(value: MediaSustainMotion, durationFrames: number): ReadonlyMap<number, number> {
- const states = new Map<number, number>([[0, 0], [durationFrames, 0]]);
- for (let cycle = 0; cycle < value.cycles; cycle += 1) {
- for (const [phaseOffset, phase] of [[0.25, 1], [0.75, -1], [1, 0]] as const) {
- states.set(Math.min(durationFrames, Math.round(
- ((cycle + phaseOffset) / value.cycles) * durationFrames,
- )), phase);
- }
- }
- return states;
-}
-
-function phaseAt(states: ReadonlyMap<number, number>, frame: number): number {
- const entries = [...states.entries()].sort(([left], [right]) => left - right);
- const exact = states.get(frame);
- if (exact !== undefined) return exact;
- const rightIndex = entries.findIndex(([atFrame]) => atFrame > frame);
- const right = entries[rightIndex]!;
- const left = entries[rightIndex - 1]!;
- const progress = (frame - left[0]) / (right[0] - left[0]);
- return clean(left[1] + ((right[1] - left[1]) * progress));
-}
-
-export function sustainAnimation(value: MediaSustainMotion, durationFrames: number): VisualAnimation {
- assertMediaSustainMotion(value, "Media sustain");
- assert(Number.isSafeInteger(durationFrames) && durationFrames > 0, "Media sustain duration is invalid.");
- const states = sustainPhases(value, durationFrames);
- return {
- keyframes: [...states.entries()].sort(([left], [right]) => left - right).map(([atFrame, phase]) => ({
- atFrame,
- easing: "linear",
- style: [{
- name: "transform",
- value: phase === 0 ? "none" : sustainTransform(value, phase),
- }],
- })),
- };
-}
-
-/** Slice one group-global sustain channel without restarting its phase for each member Present. */
-export function sustainAnimationWindow(
- value: MediaSustainMotion,
- outerDurationFrames: number,
- startOffset: number,
- endOffset: number,
-): VisualAnimation {
- assertMediaSustainMotion(value, "Media sustain");
- assert(Number.isSafeInteger(outerDurationFrames) && outerDurationFrames > 0,
- "Media sustain outer duration is invalid.");
- assert(Number.isSafeInteger(startOffset) && Number.isSafeInteger(endOffset)
- && startOffset >= 0 && endOffset > startOffset && endOffset <= outerDurationFrames,
- "Media sustain window is invalid.");
- const global = sustainPhases(value, outerDurationFrames);
- const frames = new Set<number>([startOffset, endOffset]);
- for (const frame of global.keys()) {
- if (frame > startOffset && frame < endOffset) frames.add(frame);
- }
- return {
- keyframes: [...frames].sort((left, right) => left - right).map((frame) => {
- const phase = phaseAt(global, frame);
- return {
- atFrame: frame - startOffset,
- easing: "linear" as const,
- style: [{ name: "transform", value: phase === 0 ? "none" : sustainTransform(value, phase) }],
- };
- }),
- };
-}
-
-type Cubic = readonly [number, number, number, number];
-
-function cubicCoordinate(t: number, first: number, second: number): number {
- const inverse = 1 - t;
- return (3 * inverse * inverse * t * first) + (3 * inverse * t * t * second) + (t * t * t);
-}
-
-function eased(progress: number, easing: VisualEasing): number {
- if (easing === "linear" || progress <= 0 || progress >= 1) return progress;
- const curve: Cubic = easing === "ease-in" ? [0.42, 0, 1, 1]
- : easing === "ease-out" ? [0, 0, 0.58, 1]
- : [0.42, 0, 0.58, 1];
- let low = 0;
- let high = 1;
- for (let iteration = 0; iteration < 24; iteration += 1) {
- const middle = (low + high) / 2;
- if (cubicCoordinate(middle, curve[0], curve[2]) < progress) low = middle;
- else high = middle;
- }
- return cubicCoordinate((low + high) / 2, curve[1], curve[3]);
-}
-
-function edgeStateAt(value: MediaEdgeMotion, progressToNeutral: number): MotionState {
- const progress = clean(progressToNeutral);
- const inverse = clean(1 - progress);
- const amount = value.amount ?? (value.operator === "blur-reveal" ? 16 : value.operator === "scale" ? 0.8 : 100);
- switch (value.operator) {
- case "fade": return { ...neutral, opacity: progress };
- case "slide": return { ...neutral, transform: translate(value.direction!, clean(amount * inverse)) };
- case "scale": return { ...neutral, transform: `scale(${clean(amount + ((1 - amount) * progress))})` };
- case "pop": {
- const start = value.amount ?? 0.7;
- return { ...neutral, opacity: progress, transform: `scale(${clean(start + ((1 - start) * progress))})` };
- }
- case "bounce": return {
- ...neutral,
- opacity: progress,
- transform: `translateY(${clean((value.amount ?? 80) * inverse)}px) scale(${clean(0.92 + (0.08 * progress))})`,
- };
- case "blur-reveal": return { ...neutral, opacity: progress, filter: `blur(${clean(amount * inverse)}px)` };
- case "wipe": {
- const percentage = clean(100 * inverse);
- if (value.direction === "left") return { ...neutral, clipPath: `inset(0% 0% 0% ${percentage}%)` };
- if (value.direction === "right") return { ...neutral, clipPath: `inset(0% ${percentage}% 0% 0%)` };
- if (value.direction === "up") return { ...neutral, clipPath: `inset(0% 0% ${percentage}% 0%)` };
- return { ...neutral, clipPath: `inset(${percentage}% 0% 0% 0%)` };
- }
- case "flip": {
- const axis = value.direction === "left" || value.direction === "right" ? "Y" : "X";
- const sign = value.direction === "left" || value.direction === "up" ? -1 : 1;
- return { ...neutral, opacity: progress,
- transform: `perspective(800px) rotate${axis}(${clean(sign * (value.amount ?? 90) * inverse)}deg)` };
- }
- case "spin": return { ...neutral, opacity: progress,
- transform: `rotate(${clean((value.amount ?? 180) * inverse)}deg) scale(${clean(0.8 + (0.2 * progress))})` };
- }
-}
-
-function lifecycleStateAt(value: MediaLifecycleMotion, durationFrames: number, frame: number): MotionState {
- const enter = value.enter !== undefined && frame < value.enter.durationFrames
- ? edgeStateAt(value.enter, eased(frame / value.enter.durationFrames, value.enter.easing))
- : neutral;
- let exit = neutral;
- if (value.exit !== undefined) {
- const exitStart = durationFrames - value.exit.durationFrames;
- if (frame > exitStart) {
- const progress = eased((frame - exitStart) / value.exit.durationFrames, value.exit.easing);
- exit = edgeStateAt(value.exit, 1 - progress);
- }
- }
- const transforms = [enter.transform, exit.transform].filter((item) => item !== "none");
- const filters = [enter.filter, exit.filter].filter((item) => item !== "none");
- const clip = (input: string): readonly number[] => /^inset\(([-.\d]+)% ([-.\d]+)% ([-.\d]+)% ([-.\d]+)%\)$/u
- .exec(input)?.slice(1).map(Number) ?? [0, 0, 0, 0];
- const left = clip(enter.clipPath);
- const right = clip(exit.clipPath);
- const clipped = left.map((item, index) => Math.max(item, right[index] ?? 0));
- return {
- opacity: clean(enter.opacity * exit.opacity),
- transform: transforms.join(" ") || "none",
- filter: filters.join(" ") || "none",
- clipPath: `inset(${clipped.map((item) => `${clean(item)}%`).join(" ")})`,
- };
-}
-
-/** Slice one outer lifecycle over a member Present; entry/exit never restart at member boundaries. */
-export function lifecycleAnimationWindow(
- value: MediaLifecycleMotion,
- outerDurationFrames: number,
- startOffset: number,
- endOffset: number,
-): VisualAnimation | undefined {
- assertMediaLifecycleMotion(value, outerDurationFrames, "Media lifecycle");
- assert(Number.isSafeInteger(startOffset) && Number.isSafeInteger(endOffset)
- && startOffset >= 0 && endOffset > startOffset && endOffset <= outerDurationFrames,
- "Media lifecycle window is invalid.");
- if (value.enter === undefined && value.exit === undefined) return undefined;
- const frames = new Set<number>([startOffset, endOffset]);
- if (value.enter !== undefined) {
- const end = value.enter.durationFrames;
- for (let frame = Math.max(startOffset, 0); frame <= Math.min(endOffset, end); frame += 1) frames.add(frame);
- }
- if (value.exit !== undefined) {
- const start = outerDurationFrames - value.exit.durationFrames;
- for (let frame = Math.max(startOffset, start); frame <= Math.min(endOffset, outerDurationFrames); frame += 1) frames.add(frame);
- }
- const ordered = [...frames].sort((left, right) => left - right);
- const compact = ordered.filter((frame, index) => {
- if (index === 0 || index === ordered.length - 1) return true;
- const previous = lifecycleStateAt(value, outerDurationFrames, ordered[index - 1]!);
- const current = lifecycleStateAt(value, outerDurationFrames, frame);
- const next = lifecycleStateAt(value, outerDurationFrames, ordered[index + 1]!);
- return JSON.stringify(previous) !== JSON.stringify(current) || JSON.stringify(current) !== JSON.stringify(next);
- });
- const clipping = compact.some((frame) => lifecycleStateAt(value, outerDurationFrames, frame).clipPath !== neutral.clipPath);
- return {
- keyframes: compact.map((frame) => ({
- atFrame: frame - startOffset,
- easing: "linear",
- style: style(lifecycleStateAt(value, outerDurationFrames, frame), clipping),
- })),
- };
-}
-
-export function samplingAnimation(value: MediaSamplingMotion, durationFrames: number): VisualAnimation {
- assert(value.keyframes.length >= 2, "Media sampling motion requires keyframes.");
- assert(value.keyframes[0]?.atProgress === 0 && value.keyframes.at(-1)?.atProgress === 1,
- "Media sampling motion must cover normalized progress [0, 1].");
- let previous = -1;
- return {
- keyframes: value.keyframes.map((keyframe, index) => {
- const atFrame = Math.round(keyframe.atProgress * durationFrames);
- assert(atFrame > previous,
- `Media sampling keyframe ${index + 1} collapses after frame quantization; use fewer or wider-spaced keyframes.`);
- previous = atFrame;
- return {
- atFrame,
- ...(keyframe.easing === undefined ? {} : { easing: keyframe.easing }),
- style: [{
- name: "transform",
- value: `translate(${keyframe.offsetX}px,${keyframe.offsetY}px) rotate(${keyframe.rotationDeg}deg) scale(${keyframe.zoom})`,
- }],
- };
- }),
- };
-}
diff --git a/packages/media-track/src/program.ts b/packages/media-track/src/program.ts
deleted file mode 100644
index d2c3bf0f..00000000
--- a/packages/media-track/src/program.ts
+++ /dev/null
@@ -1,560 +0,0 @@
-import type { Timeline } from "@hypit/timeline";
-import {
- assertAudioTrackIdentity,
- assertVisualTrackIdentity,
- sealAudioTrack,
- sealVisualTrack,
-} from "@hypit/composition";
-import type { AudioClip, AudioTrack, VisualTrack } from "@hypit/composition";
-import { assertProgramSpaceIdentity, programFrameSampleBoundary, programSpaceFrameCount, programSpaceSampleFrames } from "@hypit/program-space";
-import { canonicalize, isResourceId } from "@hypit/protocol";
-import { assertCanvasSpace, assertSpatialFrame } from "@hypit/spatial";
-import type { CanvasSpace } from "@hypit/spatial";
-import { assertSpatialPath } from "@hypit/spatial";
-import type { SpatialPath } from "@hypit/spatial";
-import { assertTemporalInstantFor, assertTemporalWindowFor } from "@hypit/temporal";
-import type { ProjectedWindow, TemporalInstant } from "@hypit/temporal";
-
-import {
- assertMediaIdentity,
- assertMediaLayerSet,
- assertMediaVisualOccupancy,
- assertMediaVisualSource,
- assertMediaVisualTrim,
-} from "./layers.js";
-import { lowerMediaItemElements } from "./lower.js";
-import { assertMediaLifecycleMotion, resolveMediaLifecycleMotion } from "./motion.js";
-import { assertMediaFramePresentation } from "./presentation.js";
-import { assertMediaSoundSet } from "./sounds.js";
-import {
- assertMediaHandoffSpec,
- assertMediaSequenceMemberSet,
- assertMediaSequenceSpec,
- lowerMediaSequencePresents,
- resolveMediaSequence,
- sealMediaSequenceSpec,
-} from "./sequence.js";
-import type {
- MediaFramePresentation,
- MediaItemProgram,
- MediaItemSpec,
- MediaLayerSet,
- MediaSampleLayerProgram,
- MediaSequenceProgram,
- MediaSequenceMemberSet,
- MediaSequenceSpec,
- MediaSoundSource,
- MediaSoundSet,
- MediaTrackHeader,
- MediaTrackProgram,
- MediaTrackSet,
-} from "./types.js";
-
-export function bindMediaItemClipPath(spec: MediaItemSpec, path: SpatialPath): MediaItemSpec {
- assertMediaItemSpec(spec);
- assertSpatialPath(path);
- return sealMediaItemSpec({
- ...spec,
- presentation: { ...spec.presentation, clip: { kind: "path", path: structuredClone(path) } },
- });
-}
-
-export function bindMediaSequenceClipPath(spec: MediaSequenceSpec, path: SpatialPath): MediaSequenceSpec {
- assertMediaSequenceSpec(spec);
- assertSpatialPath(path);
- return sealMediaSequenceSpec({
- ...spec,
- presentation: { ...spec.presentation, clip: { kind: "path", path: structuredClone(path) } },
- });
-}
-
-function assert(condition: unknown, message: string): asserts condition {
- if (!condition) throw new Error(message);
-}
-
-function finite(value: number, label: string): void {
- assert(Number.isFinite(value), `${label} must be finite.`);
-}
-
-function assertSound(value: MediaSoundSource, label: string): void {
- assert(value.artifact.kind === "blob" && isResourceId(value.artifact.resource)
- && value.artifact.mediaType.startsWith("audio/")
- && Number.isSafeInteger(value.artifact.size) && value.artifact.size >= 0
- && Number.isSafeInteger(value.sampleFrames) && value.sampleFrames > 0, `${label} is invalid.`);
-}
-
-export function assertMediaItemSpec(value: MediaItemSpec): void {
- assertMediaIdentity(value.id, "MediaItemSpec.id");
- assertMediaFramePresentation(value.presentation, "MediaItemSpec.presentation");
- assert(Number.isSafeInteger(value.stackingOrder), "MediaItemSpec.stackingOrder must be an integer.");
- if (value.sourceAudio !== undefined) {
- assertMediaIdentity(value.sourceAudio.fromLayer, "MediaItemSpec.sourceAudio.fromLayer");
- finite(value.sourceAudio.gain, "MediaItemSpec.sourceAudio.gain");
- assert(value.sourceAudio.gain >= 0 && value.sourceAudio.gain <= 64, "MediaItemSpec.sourceAudio.gain is invalid.");
- }
-}
-
-export function sealMediaItemSpec(value: MediaItemSpec): MediaItemSpec {
- assertMediaItemSpec(value);
- return canonicalize(value) as unknown as MediaItemSpec;
-}
-
-export function sealMediaTrackHeader(value: MediaTrackHeader): MediaTrackHeader {
- assertMediaTrackHeader(value);
- return canonicalize(value) as unknown as MediaTrackHeader;
-}
-
-export function assertMediaTrackHeader(value: MediaTrackHeader): void {
- assertMediaIdentity(value.id, "MediaTrackHeader.id");
-}
-
-export function createMediaTrackSet(): MediaTrackSet {
- return { items: [], sequences: [] };
-}
-
-export function assertMediaTrackSet(value: MediaTrackSet): void {
- assert(Array.isArray(value.items)
- && Array.isArray(value.sequences), "MediaTrackSet is invalid.");
-}
-
-function realizedItems(
- set: MediaTrackSet,
- header: MediaTrackHeader,
- timeline: Timeline,
- canvas: CanvasSpace,
- layers: MediaLayerSet,
- frame: MediaItemProgram["frame"],
- spec: MediaItemSpec,
- sounds: MediaSoundSet,
- window: ProjectedWindow,
-): MediaTrackSet {
- assertMediaTrackSet(set);
- assertMediaTrackHeader(header);
- assertProgramSpaceIdentity(timeline);
- assertCanvasSpace(canvas);
- assertMediaLayerSet(layers);
- assert(layers.layers.length > 0, `Media Item ${spec.id} requires at least one layer.`);
- assertSpatialFrame(frame);
- assertMediaItemSpec(spec);
- assertTemporalWindowFor(window, { subjectId: spec.id, space: timeline });
- assertMediaSoundSet(sounds);
- assert(!sounds.sounds.some((sound) => sound.trigger.kind === "handoff"),
- `Media Item ${spec.id} cannot own a Handoff sound.`);
- assert(frame.widthPx > spec.presentation.padding.leftPx + spec.presentation.padding.rightPx
- && frame.heightPx > spec.presentation.padding.topPx + spec.presentation.padding.bottomPx,
- `Media Item ${spec.id} padding consumes its complete Placement Frame.`);
- if (spec.sourceAudio !== undefined) {
- const selected = layers.layers.find((layer) => layer.id === spec.sourceAudio!.fromLayer);
- assert(selected?.kind === "sample" && selected.source.kind === "timed" && selected.source.audio !== undefined,
- `Media Item ${spec.id} source-audio layer is absent or has no normalized audio.`);
- }
- const duration = window.span.endFrameExclusive - window.span.startFrame;
- assertMediaLifecycleMotion(spec.motion, duration, `Media Item ${spec.id} motion`);
- const motion = resolveMediaLifecycleMotion(spec.motion, frame, canvas);
- const addition = {
- id: window.id,
- subjectId: spec.id,
- span: { ...window.span },
- frame: { ...frame },
- presentation: structuredClone(spec.presentation),
- layers: structuredClone(layers.layers),
- motion,
- stacking: { order: spec.stackingOrder, tieBreak: `${header.id}:${window.id}` },
- ...(spec.sourceAudio === undefined ? {} : { sourceAudio: { ...spec.sourceAudio } }),
- sounds: structuredClone(sounds.sounds),
- } satisfies MediaItemProgram;
- const ids = new Set([...set.items.map((item) => item.id), ...set.sequences.map((item) => item.id)]);
- assert(!ids.has(addition.id), `Media Track ${header.id} already contains ${addition.id}.`);
- return { ...set, items: [...set.items, addition] };
-}
-
-/** Component entry point: timing has already been projected by @hypit/temporal. */
-export function appendMediaItem(
- set: MediaTrackSet,
- header: MediaTrackHeader,
- timeline: Timeline,
- canvas: CanvasSpace,
- layers: MediaLayerSet,
- frame: MediaItemProgram["frame"],
- spec: MediaItemSpec,
- sounds: MediaSoundSet,
- window: ProjectedWindow,
-): MediaTrackSet {
- return realizedItems(set, header, timeline, canvas, layers, frame, spec, sounds, window);
-}
-
-function assertSampleLayerForSpace(layer: MediaSampleLayerProgram, timeline: Timeline, label: string): void {
- assertMediaVisualSource(layer.source, `${label}.source`);
- const timing = layer.source.kind === "timed" ? { frameRate: layer.source.frameRate, frameCount: layer.source.frameCount }
- : layer.source.kind === "surface" && layer.source.surface.timing.kind === "frames"
- ? layer.source.surface.timing : undefined;
- if (timing === undefined) return;
- assert(timing.frameRate.numerator === timeline.frameRate.numerator
- && timing.frameRate.denominator === timeline.frameRate.denominator,
- `${label} is not normalized to Timeline frame rate.`);
- if (layer.trim !== undefined) assertMediaVisualTrim(layer.trim, timing.frameCount, `${label}.trim`);
- assert(layer.occupancy !== undefined, `${label} requires occupancy.`);
- assertMediaVisualOccupancy(layer.occupancy, `${label}.occupancy`);
-}
-
-function assertItem(item: MediaItemProgram, timeline: Timeline, label: string): void {
- assertMediaIdentity(item.id, `${label}.id`);
- assertMediaIdentity(item.subjectId, `${label}.subjectId`);
- assert(Number.isSafeInteger(item.span.startFrame) && Number.isSafeInteger(item.span.endFrameExclusive)
- && item.span.startFrame >= 0 && item.span.endFrameExclusive > item.span.startFrame
- && item.span.endFrameExclusive <= programSpaceFrameCount(timeline), `${label}.span is invalid.`);
- assertSpatialFrame(item.frame);
- assertMediaFramePresentation(item.presentation, `${label}.presentation`);
- assertMediaLifecycleMotion(item.motion, item.span.endFrameExclusive - item.span.startFrame, `${label}.motion`);
- assert(item.motion.enter?.origin === undefined && item.motion.exit?.origin === undefined,
- `${label}.motion contains an unresolved Canvas origin.`);
- assert(Number.isSafeInteger(item.stacking.order) && item.stacking.tieBreak.length > 0, `${label}.stacking is invalid.`);
- assert(item.layers.length > 0, `${label} requires layers.`);
- const layerSet: MediaLayerSet = { layers: item.layers };
- assertMediaLayerSet(layerSet);
- for (const layer of item.layers) if (layer.kind === "sample") assertSampleLayerForSpace(layer, timeline, `${label}.${layer.id}`);
- if (item.sourceAudio !== undefined) {
- const selected = item.layers.find((layer) => layer.id === item.sourceAudio!.fromLayer);
- assert(selected?.kind === "sample" && selected.source.kind === "timed" && selected.source.audio !== undefined,
- `${label}.sourceAudio is invalid.`);
- }
- assertMediaSoundSet({ sounds: item.sounds });
- assert(!item.sounds.some((sound) => sound.trigger.kind === "handoff"), `${label} owns a Handoff sound.`);
-}
-
-function appendMediaSequenceAtFrame(
- set: MediaTrackSet,
- header: MediaTrackHeader,
- timeline: Timeline,
- canvas: CanvasSpace,
- members: MediaSequenceMemberSet,
- frame: MediaSequenceProgram["frame"],
- spec: MediaSequenceSpec,
- sounds: MediaSoundSet,
- terminalFrame: number,
-): MediaTrackSet {
- assertMediaTrackSet(set);
- assertMediaSequenceMemberSet(members);
- assertMediaSequenceSpec(spec);
- const sequence = resolveMediaSequence(header, timeline, canvas, members, frame, spec, sounds, terminalFrame);
- assert(!set.items.some((item) => item.id === sequence.id)
- && !set.sequences.some((item) => item.id === sequence.id),
- `Media Track ${header.id} already contains ${sequence.id}.`);
- return { ...set, sequences: [...set.sequences, sequence] };
-}
-
-export function appendMediaSequence(
- set: MediaTrackSet,
- header: MediaTrackHeader,
- timeline: Timeline,
- canvas: CanvasSpace,
- members: MediaSequenceMemberSet,
- frame: MediaSequenceProgram["frame"],
- spec: MediaSequenceSpec,
- sounds: MediaSoundSet,
- terminal: TemporalInstant,
-): MediaTrackSet {
- assertTemporalInstantFor(terminal, { subjectId: spec.id, space: timeline });
- return appendMediaSequenceAtFrame(set, header, timeline, canvas, members, frame, spec, sounds, terminal.frame);
-}
-
-function assertSequence(sequence: MediaSequenceProgram, timeline: Timeline, label: string): void {
- assertMediaIdentity(sequence.id, `${label}.id`);
- assert(sequence.span.startFrame >= 0 && sequence.span.endFrameExclusive <= programSpaceFrameCount(timeline)
- && sequence.span.endFrameExclusive > sequence.span.startFrame
- && sequence.terminalFrame === sequence.span.endFrameExclusive, `${label}.span is invalid.`);
- assertSpatialFrame(sequence.frame);
- assertMediaFramePresentation(sequence.presentation, `${label}.presentation`);
- assertMediaLifecycleMotion(sequence.motion, sequence.span.endFrameExclusive - sequence.span.startFrame, `${label}.motion`);
- assert(sequence.motion.enter?.origin === undefined && sequence.motion.exit?.origin === undefined,
- `${label}.motion contains an unresolved Canvas origin.`);
- assert(sequence.members.length >= 2 && sequence.handoffs.length === sequence.members.length - 1,
- `${label} topology is invalid.`);
- for (const [index, member] of sequence.members.entries()) {
- assertMediaIdentity(member.id, `${label}.members.${index}.id`);
- assert(member.activationFrame === member.logicalSpan.startFrame
- && member.logicalSpan.startFrame >= sequence.span.startFrame
- && member.logicalSpan.endFrameExclusive <= sequence.terminalFrame
- && member.logicalSpan.endFrameExclusive > member.logicalSpan.startFrame,
- `${label}.members.${index}.logicalSpan is invalid.`);
- assert(member.visualSpan.startFrame <= member.logicalSpan.startFrame
- && member.visualSpan.endFrameExclusive >= member.logicalSpan.endFrameExclusive,
- `${label}.members.${index}.visualSpan does not contain its logical phase.`);
- const layerSet: MediaLayerSet = { layers: member.layers };
- assertMediaLayerSet(layerSet);
- for (const layer of member.layers) if (layer.kind === "sample") {
- assertSampleLayerForSpace(layer, timeline, `${label}.members.${index}.${layer.id}`);
- }
- if (member.sourceAudio !== undefined) {
- const selected = member.layers.find((layer) => layer.id === member.sourceAudio!.fromLayer);
- assert(selected?.kind === "sample" && selected.source.kind === "timed" && selected.source.audio !== undefined,
- `${label}.members.${index}.sourceAudio is invalid.`);
- }
- }
- for (const [index, handoff] of sequence.handoffs.entries()) {
- assertMediaHandoffSpec(handoff);
- assert(handoff.fromMemberId === sequence.members[index]!.id
- && handoff.toMemberId === sequence.members[index + 1]!.id
- && handoff.span.startFrame <= sequence.members[index]!.logicalSpan.endFrameExclusive
- && handoff.span.endFrameExclusive >= sequence.members[index + 1]!.logicalSpan.startFrame,
- `${label}.handoffs.${index} is disconnected.`);
- }
- assertMediaSoundSet({ sounds: sequence.sounds });
- for (const sound of sequence.sounds) {
- if (sound.trigger.kind === "handoff") {
- const { handoffId } = sound.trigger;
- assert(sequence.handoffs.some((handoff) => handoff.id === handoffId),
- `${label} sound ${sound.id} targets an unknown Handoff.`);
- }
- }
-}
-
-function normalizeProgram(value: MediaTrackProgram): MediaTrackProgram {
- return {
-
- id: value.id,
- items: [...value.items].map((item) => structuredClone(item)).sort((left, right) => left.id.localeCompare(right.id)),
- sequences: [...value.sequences].map((item) => structuredClone(item)).sort((left, right) => left.id.localeCompare(right.id)),
- };
-}
-
-export function sealMediaTrackProgram(value: MediaTrackProgram, timeline: Timeline): MediaTrackProgram {
- const normalized = normalizeProgram(value);
- assertMediaTrackProgramIdentity(normalized, timeline);
- return canonicalize(normalized) as unknown as MediaTrackProgram;
-}
-
-export function finalizeMediaTrack(set: MediaTrackSet, header: MediaTrackHeader, timeline: Timeline): MediaTrackProgram {
- assertMediaTrackSet(set);
- assertMediaTrackHeader(header);
- assert(set.items.length + set.sequences.length > 0, "Media Track requires at least one Item or Sequence.");
- return sealMediaTrackProgram({
-
- id: header.id,
- items: set.items,
- sequences: set.sequences,
- }, timeline);
-}
-
-export function assertMediaTrackProgram(value: MediaTrackProgram): void {
- assertMediaIdentity(value.id, "MediaTrackProgram.id");
- assert(Array.isArray(value.items) && Array.isArray(value.sequences)
- && value.items.length + value.sequences.length > 0, "MediaTrackProgram is empty.");
-}
-
-export function assertMediaTrackProgramIdentity(value: MediaTrackProgram, timeline: Timeline): void {
- assertMediaTrackProgram(value);
- assertProgramSpaceIdentity(timeline);
- const ids = new Set<string>();
- for (const item of value.items) {
- assert(!ids.has(item.id), `MediaTrackProgram repeats ${item.id}.`);
- ids.add(item.id);
- assertItem(item, timeline, `Media Item ${item.id}`);
- }
- for (const sequence of value.sequences) {
- assert(!ids.has(sequence.id), `MediaTrackProgram repeats ${sequence.id}.`);
- ids.add(sequence.id);
- assertSequence(sequence, timeline, `Media Sequence ${sequence.id}`);
- }
-}
-
-export function projectMediaVisualTrack(timeline: Timeline, program: MediaTrackProgram): VisualTrack {
- assertMediaTrackProgramIdentity(program, timeline);
- const track = sealVisualTrack({
- programSpaceId: timeline.id,
- visualIr: "hypit.visual-ir@1",
- id: program.id,
- presents: [
- ...program.items.map((item) => ({
- id: item.id,
- subjectId: item.subjectId,
- span: { ...item.span },
- stacking: { ...item.stacking },
- elements: lowerMediaItemElements(item, timeline),
- })),
- ...program.sequences.flatMap((sequence) => lowerMediaSequencePresents(sequence, timeline)),
- ],
- });
- assertVisualTrackIdentity(track, timeline);
- return track;
-}
-
-function sourceSampleBoundary(frame: number, frameCount: number, sampleFrames: number): number {
- const numerator = BigInt(frame) * BigInt(sampleFrames);
- const denominator = BigInt(frameCount);
- const rounded = (numerator * 2n + denominator) / (denominator * 2n);
- assert(rounded <= BigInt(Number.MAX_SAFE_INTEGER), "Media source sample boundary exceeds safe arithmetic.");
- return Number(rounded);
-}
-
-function sourceAudioClip(
- value: Pick<MediaItemProgram, "id" | "subjectId" | "span" | "layers" | "sourceAudio">,
- timeline: Timeline,
- fades: { readonly inSamples: number; readonly outSamples: number } = { inSamples: 0, outSamples: 0 },
-): AudioClip | undefined {
- if (value.sourceAudio === undefined) return undefined;
- const layer = value.layers.find((candidate): candidate is MediaSampleLayerProgram =>
- candidate.kind === "sample" && candidate.id === value.sourceAudio!.fromLayer)!;
- assert(layer.source.kind === "timed" && layer.source.audio !== undefined && layer.occupancy !== undefined,
- `Media projection ${value.id} selected audio from an invalid layer.`);
- assert(layer.sampling === undefined, "Explicit visual sampling has no source-audio projection; connect the Semantic AudioTrack for performance sound.");
- const source = layer.source;
- const audio = source.audio;
- assert(audio !== undefined, `Media projection ${value.id} selected audio from an invalid layer.`);
- const trim = layer.trim ?? { startFrame: 0, endFrameExclusive: source.frameCount };
- const sourceStart = sourceSampleBoundary(trim.startFrame, source.frameCount, audio.sampleFrames);
- const sourceEnd = sourceSampleBoundary(trim.endFrameExclusive, source.frameCount, audio.sampleFrames);
- const targetWindowStart = programFrameSampleBoundary(timeline, value.span.startFrame, 48_000);
- const targetWindowEnd = programFrameSampleBoundary(timeline, value.span.endFrameExclusive, 48_000);
- const targetFrames = value.span.endFrameExclusive - value.span.startFrame;
- const sourceFrames = trim.endFrameExclusive - trim.startFrame;
- let targetStart = targetWindowStart;
- let targetEnd = targetWindowEnd;
- let clipSourceStart = sourceStart;
- let clipSourceEnd = sourceEnd;
- let loop = false;
- let phaseSample = 0;
- let playbackRate = 1;
- if (layer.occupancy.mode === "once" || layer.occupancy.mode === "hold") {
- const playedFrames = Math.min(targetFrames, sourceFrames);
- if (layer.occupancy.align === "start") {
- targetEnd = programFrameSampleBoundary(timeline, value.span.startFrame + playedFrames, 48_000);
- clipSourceEnd = sourceSampleBoundary(trim.startFrame + playedFrames, source.frameCount, audio.sampleFrames);
- } else {
- targetStart = programFrameSampleBoundary(timeline, value.span.endFrameExclusive - playedFrames, 48_000);
- clipSourceStart = sourceSampleBoundary(trim.endFrameExclusive - playedFrames, source.frameCount, audio.sampleFrames);
- }
- } else if (layer.occupancy.mode === "loop") {
- loop = true;
- if (layer.occupancy.align === "end") {
- const phaseFrames = (sourceFrames - (targetFrames % sourceFrames)) % sourceFrames;
- phaseSample = sourceSampleBoundary(trim.startFrame + phaseFrames, source.frameCount, audio.sampleFrames) - sourceStart;
- }
- } else {
- playbackRate = (sourceEnd - sourceStart) / (targetWindowEnd - targetWindowStart);
- }
- const audible = targetEnd - targetStart;
- assert(fades.inSamples <= audible && fades.outSamples <= audible,
- `Media projection ${value.id} source audio is too short for its authored crossfade.`);
- return {
- id: `${value.id}:source-audio`,
- subjectId: value.subjectId,
- artifact: structuredClone(audio.artifact),
- target: { startSample: targetStart, endSampleExclusive: targetEnd },
- source: {
- sampleFrames: audio.sampleFrames,
- startSample: clipSourceStart,
- endSampleExclusive: clipSourceEnd,
- loop,
- phaseSample,
- },
- playbackRate,
- pitch: "preserve",
- gain: value.sourceAudio.gain,
- fadeInSamples: fades.inSamples,
- fadeOutSamples: fades.outSamples,
- };
-}
-
-function soundClip(
- id: string,
- source: MediaSoundSource,
- gain: number,
- point: number,
- timeline: Timeline,
-): AudioClip {
- const total = programSpaceSampleFrames(timeline, 48_000);
- const targetStart = programFrameSampleBoundary(timeline, point, 48_000);
- const audible = Math.min(source.sampleFrames, Math.max(0, total - targetStart));
- assert(audible > 0, `Media sound ${id} begins outside Timeline.`);
- return {
- id,
- artifact: structuredClone(source.artifact),
- target: { startSample: targetStart, endSampleExclusive: targetStart + audible },
- source: {
- sampleFrames: source.sampleFrames,
- startSample: 0,
- endSampleExclusive: audible,
- loop: false,
- phaseSample: 0,
- },
- playbackRate: 1,
- pitch: "preserve",
- gain,
- fadeInSamples: 0,
- fadeOutSamples: 0,
- };
-}
-
-function edgeSoundClips(
- value: Pick<MediaItemProgram, "id" | "span" | "motion" | "sounds">,
- timeline: Timeline,
-): AudioClip[] {
- return value.sounds.flatMap((sound) => {
- if (sound.trigger.kind === "handoff") return [];
- const point = sound.trigger.kind === "enter"
- ? value.span.startFrame
- : value.span.endFrameExclusive - (value.motion.exit?.durationFrames ?? 0);
- return [soundClip(`${value.id}:${sound.id}`, sound.source, sound.gain, point, timeline)];
- });
-}
-
-function sequenceAudioClips(sequence: MediaSequenceProgram, timeline: Timeline): AudioClip[] {
- const sourceClips = sequence.members.flatMap((member, index) => {
- if (member.sourceAudio === undefined) return [];
- const incoming = sequence.handoffs[index - 1];
- const outgoing = sequence.handoffs[index];
- const span = {
- startFrame: incoming?.audio === "crossfade" ? incoming.span.startFrame : member.logicalSpan.startFrame,
- endFrameExclusive: outgoing?.audio === "crossfade"
- ? outgoing.span.endFrameExclusive : member.logicalSpan.endFrameExclusive,
- };
- const fadeInSamples = incoming?.audio === "crossfade"
- ? programFrameSampleBoundary(timeline, incoming.span.endFrameExclusive, 48_000)
- - programFrameSampleBoundary(timeline, incoming.span.startFrame, 48_000)
- : 0;
- const fadeOutSamples = outgoing?.audio === "crossfade"
- ? programFrameSampleBoundary(timeline, outgoing.span.endFrameExclusive, 48_000)
- - programFrameSampleBoundary(timeline, outgoing.span.startFrame, 48_000)
- : 0;
- const clip = sourceAudioClip({
- id: `${sequence.id}:${member.id}`,
- subjectId: sequence.id,
- span,
- layers: member.layers,
- sourceAudio: member.sourceAudio,
- }, timeline, { inSamples: fadeInSamples, outSamples: fadeOutSamples });
- return clip === undefined ? [] : [clip];
- });
- const handoffSounds = sequence.sounds.flatMap((sound) => {
- if (sound.trigger.kind !== "handoff") return [];
- const { handoffId } = sound.trigger;
- const handoff = sequence.handoffs.find((candidate) => candidate.id === handoffId)!;
- return [soundClip(
- `${sequence.id}:${sound.id}`, sound.source, sound.gain,
- sequence.members.find((member) => member.id === handoff.toMemberId)!.activationFrame, timeline,
- )];
- });
- return [
- ...sourceClips,
- ...edgeSoundClips({
- id: sequence.id,
- span: sequence.span,
- motion: sequence.motion,
- sounds: sequence.sounds,
- }, timeline),
- ...handoffSounds,
- ];
-}
-
-export function projectMediaAudioTrack(timeline: Timeline, program: MediaTrackProgram): AudioTrack {
- assertMediaTrackProgramIdentity(program, timeline);
- const clips = program.items.flatMap((item) => {
- const source = sourceAudioClip(item, timeline);
- return [...(source === undefined ? [] : [source]), ...edgeSoundClips(item, timeline)];
- }).concat(program.sequences.flatMap((sequence) => sequenceAudioClips(sequence, timeline)));
- assert(clips.length > 0, `Media Program ${program.id} has no explicitly authored audio projection.`);
- const track = sealAudioTrack({ programSpaceId: timeline.id, id: `${program.id}:audio`, clips });
- assertAudioTrackIdentity(track, timeline);
- return track;
-}
diff --git a/packages/media-track/src/sampling.ts b/packages/media-track/src/sampling.ts
deleted file mode 100644
index bd8036c5..00000000
--- a/packages/media-track/src/sampling.ts
+++ /dev/null
@@ -1,118 +0,0 @@
-import type { Timeline } from "@hypit/timeline";
-import type {
- VisualSamplingRational,
- VisualSamplingSegment,
- VisualTimedSampling,
-} from "@hypit/composition";
-import { assertProgramSpaceIdentity } from "@hypit/program-space";
-
-import type { MediaVisualOccupancy, MediaVisualTrim } from "./types.js";
-
-function assert(condition: unknown, message: string): asserts condition {
- if (!condition) throw new Error(message);
-}
-
-function gcd(left: bigint, right: bigint): bigint {
- let a = left < 0n ? -left : left;
- let b = right < 0n ? -right : right;
- while (b !== 0n) [a, b] = [b, a % b];
- return a;
-}
-
-function rational(numerator: bigint, denominator = 1n): VisualSamplingRational {
- assert(denominator > 0n && numerator >= 0n, "Media visual sampling rational is negative or undefined.");
- const divisor = gcd(numerator, denominator);
- const reducedNumerator = numerator / divisor;
- const reducedDenominator = denominator / divisor;
- assert(reducedNumerator <= BigInt(Number.MAX_SAFE_INTEGER)
- && reducedDenominator <= BigInt(Number.MAX_SAFE_INTEGER),
- "Media visual sampling rational exceeds safe wire arithmetic.");
- return { numerator: Number(reducedNumerator), denominator: Number(reducedDenominator) };
-}
-
-function segment(
- startFrame: number,
- endFrameExclusive: number,
- sourceFrame: VisualSamplingRational,
- rate: VisualSamplingRational,
- loop?: MediaVisualTrim,
-): VisualSamplingSegment {
- return {
- target: { startFrame, endFrameExclusive },
- sourceFrame,
- rate,
- ...(loop === undefined ? {} : { loop: { ...loop } }),
- };
-}
-
-function assertOccupancy(value: MediaVisualOccupancy): void {
- if (value.mode === "stretch") return;
- assert(["once", "hold", "loop"].includes(value.mode), "Media visual occupancy mode is invalid.");
- assert(value.align === "start" || value.align === "end", "Media visual occupancy alignment is invalid.");
-}
-
-/**
- * Resolve package-owned trim/occupancy intent into the renderer-neutral exact
- * source-frame function. Timed media is normalized to Program frame rate
- * upstream, so native playback advances exactly one source frame per Program
- * frame. This avoids a second, renderer-specific frame quantizer.
- */
-export function resolveVisualSampling(input: {
- readonly timeline: Timeline;
- readonly sourceFrameRate: { readonly numerator: number; readonly denominator: number };
- readonly sourceFrameCount: number;
- readonly targetFrameCount: number;
- readonly trim?: MediaVisualTrim;
- readonly occupancy: MediaVisualOccupancy;
-}): VisualTimedSampling {
- assertProgramSpaceIdentity(input.timeline);
- assert(Number.isSafeInteger(input.sourceFrameCount) && input.sourceFrameCount > 0,
- "Timed visual source frame count is invalid.");
- assert(Number.isSafeInteger(input.targetFrameCount) && input.targetFrameCount > 0,
- "Timed visual target frame count is invalid.");
- assert(input.sourceFrameRate.numerator === input.timeline.frameRate.numerator
- && input.sourceFrameRate.denominator === input.timeline.frameRate.denominator,
- "Timed visual source must be normalized to Timeline frame rate before Media authoring.");
- assertOccupancy(input.occupancy);
- const trim = input.trim ?? { startFrame: 0, endFrameExclusive: input.sourceFrameCount };
- assert(Number.isSafeInteger(trim.startFrame) && Number.isSafeInteger(trim.endFrameExclusive)
- && trim.startFrame >= 0 && trim.endFrameExclusive > trim.startFrame
- && trim.endFrameExclusive <= input.sourceFrameCount,
- "Timed visual trim is outside its source frame domain.");
- const sourceLength = trim.endFrameExclusive - trim.startFrame;
- const targetLength = input.targetFrameCount;
- const one = rational(1n);
- const zero = rational(0n);
- const segments: VisualSamplingSegment[] = [];
-
- if (input.occupancy.mode === "stretch") {
- segments.push(segment(0, targetLength, rational(BigInt(trim.startFrame)),
- rational(BigInt(sourceLength), BigInt(targetLength))));
- } else if (input.occupancy.mode === "loop") {
- const phase = input.occupancy.align === "start"
- ? 0
- : (sourceLength - (targetLength % sourceLength)) % sourceLength;
- segments.push(segment(0, targetLength, rational(BigInt(trim.startFrame + phase)), one, trim));
- } else {
- const played = Math.min(sourceLength, targetLength);
- if (input.occupancy.align === "start") {
- segments.push(segment(0, played, rational(BigInt(trim.startFrame)), one));
- if (input.occupancy.mode === "hold" && played < targetLength) {
- segments.push(segment(played, targetLength, rational(BigInt(trim.endFrameExclusive - 1)), zero));
- }
- } else {
- const targetStart = targetLength - played;
- if (input.occupancy.mode === "hold" && targetStart > 0) {
- segments.push(segment(0, targetStart, rational(BigInt(trim.startFrame)), zero));
- }
- segments.push(segment(targetStart, targetLength,
- rational(BigInt(trim.endFrameExclusive - played)), one));
- }
- }
-
- return {
- sourceFrameRate: { ...input.sourceFrameRate },
- sourceFrameCount: input.sourceFrameCount,
- segments,
- };
-}
diff --git a/packages/media-track/src/sequence.ts b/packages/media-track/src/sequence.ts
deleted file mode 100644
index ecfcdbb2..00000000
--- a/packages/media-track/src/sequence.ts
+++ /dev/null
@@ -1,403 +0,0 @@
-import type { Timeline } from "@hypit/timeline";
-import type {
- VisualAnimation,
- VisualEasing,
- VisualPresent,
- VisualStyleDeclaration,
-} from "@hypit/composition";
-import { assertProgramSpaceIdentity, programSpaceFrameCount } from "@hypit/program-space";
-import { canonicalize } from "@hypit/protocol";
-import { assertCanvasSpace, assertSpatialFrame } from "@hypit/spatial";
-import type { CanvasSpace } from "@hypit/spatial";
-import { assertTemporalInstantFor, resolveTriggeredSchedule } from "@hypit/temporal";
-import type { TemporalInstant } from "@hypit/temporal";
-
-import { assertMediaIdentity, assertMediaLayerSet } from "./layers.js";
-import { lowerMediaItemElements } from "./lower.js";
-import {
- assertMediaLifecycleMotion,
- lifecycleAnimationWindow,
- resolveMediaLifecycleMotion,
- sustainAnimationWindow,
-} from "./motion.js";
-import { assertMediaFramePresentation } from "./presentation.js";
-import { assertMediaSoundSet } from "./sounds.js";
-import type {
- MediaHandoffProgram,
- MediaHandoffSpec,
- MediaItemProgram,
- MediaLayerSet,
- MediaMotionDirection,
- MediaSequenceMemberProgram,
- MediaSequenceMemberSet,
- MediaSequenceMemberSpec,
- MediaSequenceProgram,
- MediaSequenceSpec,
- MediaSoundSet,
- MediaTrackHeader,
-} from "./types.js";
-
-function assert(condition: unknown, message: string): asserts condition {
- if (!condition) throw new Error(message);
-}
-
-function finite(value: number, label: string): void {
- assert(Number.isFinite(value), `${label} must be finite.`);
-}
-
-export function assertMediaSequenceMemberSpec(value: MediaSequenceMemberSpec): void {
- assertMediaIdentity(value.id, "MediaSequenceMemberSpec.id");
- if (value.sourceAudio !== undefined) {
- assertMediaIdentity(value.sourceAudio.fromLayer, "MediaSequenceMemberSpec.sourceAudio.fromLayer");
- finite(value.sourceAudio.gain, "MediaSequenceMemberSpec.sourceAudio.gain");
- assert(value.sourceAudio.gain >= 0 && value.sourceAudio.gain <= 64,
- "MediaSequenceMemberSpec.sourceAudio.gain is invalid.");
- }
-}
-
-export function sealMediaSequenceMemberSpec(value: MediaSequenceMemberSpec): MediaSequenceMemberSpec {
- assertMediaSequenceMemberSpec(value);
- return canonicalize(value) as unknown as MediaSequenceMemberSpec;
-}
-
-export function createMediaSequenceMemberSet(): MediaSequenceMemberSet {
- return { members: [] };
-}
-
-export function assertMediaSequenceMemberSet(value: MediaSequenceMemberSet): void {
- assert(Array.isArray(value.members),
- "MediaSequenceMemberSet is invalid.");
- const ids = new Set<string>();
- for (const member of value.members) {
- assertMediaIdentity(member.id, "Media Sequence member id");
- assert(!ids.has(member.id), `MediaSequenceMemberSet repeats ${member.id}.`);
- ids.add(member.id);
- assert(Number.isSafeInteger(member.activationFrame) && member.activationFrame >= 0,
- `Media Sequence member ${member.id} activation is invalid.`);
- assertMediaLayerSet({ layers: member.layers });
- }
-}
-
-function appendMediaSequenceMemberAtFrame(
- set: MediaSequenceMemberSet,
- layers: MediaLayerSet,
- spec: MediaSequenceMemberSpec,
- activationFrame: number,
-): MediaSequenceMemberSet {
- assertMediaSequenceMemberSet(set);
- assertMediaLayerSet(layers);
- assert(layers.layers.length > 0, `Media Sequence member ${spec.id} requires layers.`);
- assertMediaSequenceMemberSpec(spec);
- assert(Number.isSafeInteger(activationFrame) && activationFrame >= 0,
- `Media Sequence member ${spec.id} activation is invalid.`);
- assert(!set.members.some((member) => member.id === spec.id), `Media Sequence already contains ${spec.id}.`);
- if (spec.sourceAudio !== undefined) {
- const selected = layers.layers.find((layer) => layer.id === spec.sourceAudio!.fromLayer);
- assert(selected?.kind === "sample" && selected.source.kind === "timed" && selected.source.audio !== undefined,
- `Media Sequence member ${spec.id} source-audio layer is absent or silent.`);
- }
- return canonicalize({
-
- members: [...set.members, {
- id: spec.id,
- activationFrame,
- layers: structuredClone(layers.layers),
- ...(spec.sourceAudio === undefined ? {} : { sourceAudio: { ...spec.sourceAudio } }),
- }],
- }) as unknown as MediaSequenceMemberSet;
-}
-
-export function appendMediaSequenceMember(
- set: MediaSequenceMemberSet,
- timeline: Timeline,
- layers: MediaLayerSet,
- spec: MediaSequenceMemberSpec,
- activation: TemporalInstant,
-): MediaSequenceMemberSet {
- assertTemporalInstantFor(activation, { subjectId: spec.id, space: timeline });
- return appendMediaSequenceMemberAtFrame(set, layers, spec, activation.frame);
-}
-
-export function assertMediaHandoffSpec(value: MediaHandoffSpec): void {
- assertMediaIdentity(value.id, "MediaHandoffSpec.id");
- assertMediaIdentity(value.fromMemberId, "MediaHandoffSpec.fromMemberId");
- assertMediaIdentity(value.toMemberId, "MediaHandoffSpec.toMemberId");
- assert(["cut", "crossfade", "push", "wipe", "cover", "page-turn"].includes(value.operator),
- "MediaHandoffSpec.operator is invalid.");
- assert(Number.isSafeInteger(value.durationFrames) && value.durationFrames >= 0,
- "MediaHandoffSpec.durationFrames is invalid.");
- assert((value.operator === "cut") === (value.durationFrames === 0),
- "A cut must have zero duration and every visual transition must have positive duration.");
- finite(value.boundaryRatio, "MediaHandoffSpec.boundaryRatio");
- assert(value.boundaryRatio >= 0 && value.boundaryRatio <= 1,
- "MediaHandoffSpec.boundaryRatio must be inside [0, 1].");
- if (["push", "wipe", "cover", "page-turn"].includes(value.operator)) {
- assert(value.direction !== undefined && ["left", "right", "up", "down"].includes(value.direction),
- `MediaHandoffSpec ${value.operator} requires a direction.`);
- }
- assert(value.audio === "cut" || value.audio === "crossfade", "MediaHandoffSpec.audio is invalid.");
- if (value.audio === "crossfade") assert(value.durationFrames > 0, "Audio crossfade requires a non-empty handoff.");
-}
-
-export function sealMediaHandoffSpec(value: MediaHandoffSpec): MediaHandoffSpec {
- assertMediaHandoffSpec(value);
- return canonicalize(value) as unknown as MediaHandoffSpec;
-}
-
-export function assertMediaSequenceSpec(value: MediaSequenceSpec): void {
- assertMediaIdentity(value.id, "MediaSequenceSpec.id");
- assertMediaFramePresentation(value.presentation, "MediaSequenceSpec.presentation");
- assert(Number.isSafeInteger(value.stackingOrder), "MediaSequenceSpec.stackingOrder must be an integer.");
- for (const handoff of value.handoffs) assertMediaHandoffSpec(handoff);
-}
-
-export function sealMediaSequenceSpec(value: MediaSequenceSpec): MediaSequenceSpec {
- assertMediaSequenceSpec(value);
- return canonicalize(value) as unknown as MediaSequenceSpec;
-}
-
-function resolvedHandoff(
- spec: MediaHandoffSpec,
- boundary: number,
-): MediaHandoffProgram {
- const before = Math.floor(spec.durationFrames * spec.boundaryRatio);
- const span = {
- startFrame: boundary - before,
- endFrameExclusive: boundary + (spec.durationFrames - before),
- };
- return {
- id: spec.id,
- fromMemberId: spec.fromMemberId,
- toMemberId: spec.toMemberId,
- operator: spec.operator,
- durationFrames: spec.durationFrames,
- boundaryRatio: spec.boundaryRatio,
- span,
- ...(spec.direction === undefined ? {} : { direction: spec.direction }),
- audio: spec.audio,
- };
-}
-
-export function resolveMediaSequence(
- header: MediaTrackHeader,
- timeline: Timeline,
- canvas: CanvasSpace,
- memberSet: MediaSequenceMemberSet,
- frame: MediaSequenceProgram["frame"],
- spec: MediaSequenceSpec,
- sounds: MediaSoundSet,
- terminalFrame: number,
-): MediaSequenceProgram {
- assertProgramSpaceIdentity(timeline);
- assertCanvasSpace(canvas);
- assertMediaSequenceMemberSet(memberSet);
- assertMediaSequenceSpec(spec);
- assertMediaSoundSet(sounds);
- assert(Number.isSafeInteger(terminalFrame) && terminalFrame > 0,
- `Media Sequence ${spec.id} terminal frame is invalid.`);
- assertSpatialFrame(frame);
- assert(memberSet.members.length >= 2, `Media Sequence ${spec.id} requires at least two Members.`);
- assert(spec.handoffs.length === memberSet.members.length - 1,
- `Media Sequence ${spec.id} requires exactly one Handoff for every adjacent pair.`);
- const first = memberSet.members[0]!;
- const schedule = resolveTriggeredSchedule({
- outer: { startFrame: first.activationFrame, endFrameExclusive: terminalFrame },
- terminalFrame,
- triggers: memberSet.members.map((member) => ({ id: member.id, frame: member.activationFrame })),
- });
- assert(terminalFrame <= programSpaceFrameCount(timeline), `Media Sequence ${spec.id} exits Timeline.`);
- const handoffs = spec.handoffs.map((handoff, index) => {
- const from = memberSet.members[index]!;
- const to = memberSet.members[index + 1]!;
- assert(handoff.fromMemberId === from.id && handoff.toMemberId === to.id,
- `Media Handoff ${handoff.id} does not connect authored adjacent Members ${from.id} → ${to.id}.`);
- const result = resolvedHandoff(handoff, to.activationFrame);
- assert(result.span.startFrame >= first.activationFrame && result.span.endFrameExclusive <= terminalFrame,
- `Media Handoff ${handoff.id} exceeds the Sequence envelope.`);
- return result;
- });
- for (const sound of sounds.sounds) {
- if (sound.trigger.kind === "handoff") {
- const { handoffId } = sound.trigger;
- assert(handoffs.some((handoff) => handoff.id === handoffId),
- `Media Sequence ${spec.id} sound ${sound.id} targets an unknown Handoff.`);
- }
- }
- for (let index = 1; index < handoffs.length; index += 1) {
- assert(handoffs[index - 1]!.span.endFrameExclusive <= handoffs[index]!.span.startFrame,
- `Media Sequence ${spec.id} has overlapping Handoffs.`);
- }
- const members: MediaSequenceMemberProgram[] = memberSet.members.map((member, index) => {
- const logicalSpan = schedule.exclusive[index]!;
- const incoming = handoffs[index - 1];
- const outgoing = handoffs[index];
- const visualSpan = {
- startFrame: incoming?.span.startFrame ?? logicalSpan.startFrame,
- endFrameExclusive: outgoing?.span.endFrameExclusive ?? logicalSpan.endFrameExclusive,
- };
- return {
- id: member.id,
- activationFrame: member.activationFrame,
- logicalSpan: { ...logicalSpan },
- visualSpan,
- layers: structuredClone(member.layers),
- ...(member.sourceAudio === undefined ? {} : { sourceAudio: { ...member.sourceAudio } }),
- };
- });
- const span = { startFrame: first.activationFrame, endFrameExclusive: terminalFrame };
- assertMediaLifecycleMotion(spec.motion, span.endFrameExclusive - span.startFrame, `Media Sequence ${spec.id} motion`);
- const motion = resolveMediaLifecycleMotion(spec.motion, frame, canvas);
- assert(frame.widthPx > spec.presentation.padding.leftPx + spec.presentation.padding.rightPx
- && frame.heightPx > spec.presentation.padding.topPx + spec.presentation.padding.bottomPx,
- `Media Sequence ${spec.id} padding consumes its complete Placement Frame.`);
- return canonicalize({
- id: spec.id,
- span,
- terminalFrame,
- frame: { ...frame },
- presentation: structuredClone(spec.presentation),
- members,
- handoffs,
- motion,
- stacking: { order: spec.stackingOrder, tieBreak: `${header.id}:${spec.id}` },
- sounds: structuredClone(sounds.sounds),
- }) as unknown as MediaSequenceProgram;
-}
-
-type TransitionState = {
- readonly opacity: number;
- readonly transform: string;
- readonly clipPath: string;
-};
-
-const neutral: TransitionState = { opacity: 1, transform: "none", clipPath: "inset(0% 0% 0% 0%)" };
-
-function translate(direction: MediaMotionDirection, amount: number): string {
- if (direction === "left") return `translateX(${-amount}%)`;
- if (direction === "right") return `translateX(${amount}%)`;
- if (direction === "up") return `translateY(${-amount}%)`;
- return `translateY(${amount}%)`;
-}
-
-function opposite(direction: MediaMotionDirection): MediaMotionDirection {
- if (direction === "left") return "right";
- if (direction === "right") return "left";
- if (direction === "up") return "down";
- return "up";
-}
-
-function clipped(direction: MediaMotionDirection): string {
- if (direction === "left") return "inset(0% 0% 0% 100%)";
- if (direction === "right") return "inset(0% 100% 0% 0%)";
- if (direction === "up") return "inset(0% 0% 100% 0%)";
- return "inset(100% 0% 0% 0%)";
-}
-
-function incomingState(handoff: MediaHandoffProgram): TransitionState {
- if (handoff.operator === "crossfade") return { ...neutral, opacity: 0 };
- if (handoff.operator === "push" || handoff.operator === "cover") {
- return { ...neutral, transform: translate(opposite(handoff.direction!), 100) };
- }
- if (handoff.operator === "wipe") return { ...neutral, clipPath: clipped(handoff.direction!) };
- if (handoff.operator === "page-turn") {
- const axis = handoff.direction === "left" || handoff.direction === "right" ? "Y" : "X";
- const sign = handoff.direction === "left" || handoff.direction === "up" ? 1 : -1;
- return { ...neutral, opacity: 0, transform: `perspective(900px) rotate${axis}(${sign * 75}deg)` };
- }
- return neutral;
-}
-
-function outgoingState(handoff: MediaHandoffProgram): TransitionState {
- if (handoff.operator === "crossfade") return { ...neutral, opacity: 0 };
- if (handoff.operator === "push") return { ...neutral, transform: translate(handoff.direction!, 100) };
- if (handoff.operator === "page-turn") {
- const axis = handoff.direction === "left" || handoff.direction === "right" ? "Y" : "X";
- const sign = handoff.direction === "left" || handoff.direction === "up" ? -1 : 1;
- return { ...neutral, opacity: 0, transform: `perspective(900px) rotate${axis}(${sign * 75}deg)` };
- }
- return neutral;
-}
-
-function styles(value: TransitionState, clipping: boolean): VisualStyleDeclaration[] {
- return [
- ...(clipping ? [{ name: "clip-path", value: value.clipPath }] : []),
- { name: "opacity", value: value.opacity },
- { name: "transform", value: value.transform },
- ];
-}
-
-export function sequenceMemberHandoffAnimation(
- member: MediaSequenceMemberProgram,
- incoming: MediaHandoffProgram | undefined,
- outgoing: MediaHandoffProgram | undefined,
-): VisualAnimation | undefined {
- if ((incoming === undefined || incoming.operator === "cut") && (outgoing === undefined || outgoing.operator === "cut")) {
- return undefined;
- }
- const duration = member.visualSpan.endFrameExclusive - member.visualSpan.startFrame;
- const states = new Map<number, { readonly state: TransitionState; readonly easing?: VisualEasing }>();
- const add = (frame: number, state: TransitionState, easing?: VisualEasing): void => {
- const previous = states.get(frame);
- assert(previous === undefined || JSON.stringify(previous.state) === JSON.stringify(state),
- `Media Sequence member ${member.id} has conflicting Handoff states at frame ${frame}.`);
- states.set(frame, { state, ...(easing === undefined ? {} : { easing }) });
- };
- add(0, incoming === undefined || incoming.operator === "cut" ? neutral : incomingState(incoming), "ease-in-out");
- if (incoming !== undefined && incoming.operator !== "cut") {
- add(incoming.span.endFrameExclusive - member.visualSpan.startFrame, neutral);
- }
- if (outgoing !== undefined && outgoing.operator !== "cut") {
- add(outgoing.span.startFrame - member.visualSpan.startFrame, neutral, "ease-in-out");
- add(outgoing.span.endFrameExclusive - member.visualSpan.startFrame, outgoingState(outgoing));
- } else add(duration, neutral);
- const clipping = [...states.values()].some((value) => value.state.clipPath !== neutral.clipPath);
- return { keyframes: [...states.entries()].sort(([left], [right]) => left - right).map(([atFrame, value]) => ({
- atFrame,
- ...(value.easing === undefined ? {} : { easing: value.easing }),
- style: styles(value.state, clipping),
- })) };
-}
-
-export function lowerMediaSequencePresents(
- sequence: MediaSequenceProgram,
- timeline: Timeline,
-): readonly VisualPresent[] {
- return sequence.members.map((member, index) => {
- const incoming = sequence.handoffs[index - 1];
- const outgoing = sequence.handoffs[index];
- const item: MediaItemProgram = {
- id: `${sequence.id}:${member.id}`,
- subjectId: sequence.id,
- span: { ...member.visualSpan },
- frame: { ...sequence.frame },
- presentation: structuredClone(sequence.presentation),
- layers: structuredClone(member.layers),
- motion: structuredClone(sequence.motion),
- stacking: {
- order: sequence.stacking.order,
- tieBreak: `${sequence.stacking.tieBreak}:${String(index + 1).padStart(4, "0")}`,
- },
- ...(member.sourceAudio === undefined ? {} : { sourceAudio: { ...member.sourceAudio } }),
- sounds: [],
- };
- const handoffAnimation = sequenceMemberHandoffAnimation(member, incoming, outgoing);
- const outerDuration = sequence.span.endFrameExclusive - sequence.span.startFrame;
- const startOffset = member.visualSpan.startFrame - sequence.span.startFrame;
- const endOffset = member.visualSpan.endFrameExclusive - sequence.span.startFrame;
- return {
- id: item.id,
- subjectId: sequence.id,
- span: { ...item.span },
- stacking: { ...item.stacking },
- elements: lowerMediaItemElements(item, timeline, {
- includeHandoffWrapper: true,
- ...(handoffAnimation === undefined ? {} : { handoffAnimation }),
- lifecycleAnimationOverride: lifecycleAnimationWindow(
- sequence.motion, outerDuration, startOffset, endOffset,
- ) ?? null,
- sustainAnimationsOverride: sequence.motion.sustain.map((sustain) =>
- sustainAnimationWindow(sustain, outerDuration, startOffset, endOffset)),
- }),
- };
- });
-}
diff --git a/packages/media-track/src/sounds.ts b/packages/media-track/src/sounds.ts
deleted file mode 100644
index 57c9dfcd..00000000
--- a/packages/media-track/src/sounds.ts
+++ /dev/null
@@ -1,71 +0,0 @@
-import { synchronizedMediaSampleFrames, verifySynchronizedMedia } from "@hypit/media";
-import type { SynchronizedMedia } from "@hypit/media";
-import { canonicalize } from "@hypit/protocol";
-
-import { assertMediaIdentity } from "./layers.js";
-import type { MediaSoundSet, MediaSoundSpec } from "./types.js";
-
-function assert(condition: unknown, message: string): asserts condition {
- if (!condition) throw new Error(message);
-}
-
-export function assertMediaSoundSpec(value: MediaSoundSpec): void {
- assertMediaIdentity(value.id, "MediaSoundSpec.id");
- assert(value.trigger.kind === "enter" || value.trigger.kind === "exit" || value.trigger.kind === "handoff",
- "MediaSoundSpec.trigger is invalid.");
- if (value.trigger.kind === "handoff") {
- assertMediaIdentity(value.trigger.handoffId, "MediaSoundSpec.trigger.handoffId");
- }
- assert(Number.isFinite(value.gain) && value.gain >= 0 && value.gain <= 64,
- "MediaSoundSpec.gain must be inside [0, 64].");
-}
-
-export function sealMediaSoundSpec(value: MediaSoundSpec): MediaSoundSpec {
- assertMediaSoundSpec(value);
- return canonicalize(value) as unknown as MediaSoundSpec;
-}
-
-export function createMediaSoundSet(): MediaSoundSet {
- return { sounds: [] };
-}
-
-export function assertMediaSoundSet(value: MediaSoundSet): void {
- assert(Array.isArray(value.sounds),
- "MediaSoundSet is invalid.");
- const ids = new Set<string>();
- for (const sound of value.sounds) {
- assertMediaSoundSpec({ id: sound.id, trigger: sound.trigger, gain: sound.gain });
- assert(!ids.has(sound.id), `MediaSoundSet repeats ${sound.id}.`);
- ids.add(sound.id);
- assert(sound.source.artifact.kind === "blob" && sound.source.artifact.mediaType.startsWith("audio/")
- && Number.isSafeInteger(sound.source.sampleFrames) && sound.source.sampleFrames > 0,
- `MediaSoundSet ${sound.id} source is invalid.`);
- }
-}
-
-/** Bind one normalized audio source through an ordinary graph input edge. */
-export function appendMediaSound(
- set: MediaSoundSet,
- media: SynchronizedMedia,
- spec: MediaSoundSpec,
-): MediaSoundSet {
- assertMediaSoundSet(set);
- verifySynchronizedMedia(media);
- assertMediaSoundSpec(spec);
- assert(media.audio !== undefined, `Media sound ${spec.id} requires normalized audio.`);
- assert(!set.sounds.some((sound) => sound.id === spec.id), `MediaSoundSet already contains ${spec.id}.`);
- const result = {
-
- sounds: [...set.sounds, {
- id: spec.id,
- trigger: structuredClone(spec.trigger),
- source: {
- artifact: structuredClone(media.audio.artifact),
- sampleFrames: synchronizedMediaSampleFrames(media),
- },
- gain: spec.gain,
- }],
- };
- assertMediaSoundSet(result);
- return canonicalize(result) as unknown as MediaSoundSet;
-}
diff --git a/packages/media-track/src/surface.ts b/packages/media-track/src/surface.ts
deleted file mode 100644
index ffc8aa44..00000000
--- a/packages/media-track/src/surface.ts
+++ /dev/null
@@ -1,650 +0,0 @@
-import { resolveTemporalContext } from "@hypit/temporal-markup";
-import {
- assertEmptyElement as empty,
- assertAttributes as allowed,
- textAttribute as text,
- optionalTextAttribute as optionalText,
- type StructuredElement,
- type StructuredSurfaceHandler,
- type SurfaceComponentDraft,
- type SurfaceRecordDraft,
- type SurfaceResolvedReference,
- type MarkupAttributeValue,
-} from "@hypit/markup";
-import { sameType, type TypeRef } from "@hypit/protocol";
-import { artifactTypes } from "@hypit/artifact";
-import { compositionTypes } from "@hypit/composition";
-import { sealGraphFragment } from "@hypit/elaborator";
-import type { FragmentOperation } from "@hypit/elaborator";
-import { mediaTypes } from "@hypit/media";
-import { spatialTypes } from "@hypit/spatial";
-import { svsRecipeType } from "@hypit/svs";
-import type { SvsRecipe } from "@hypit/svs";
-import { temporalTypes } from "@hypit/temporal";
-import { createTemporalInstantProjection, createTemporalWindowProjection, temporalInstantAttributeNames, temporalWindowAttributeNames } from "@hypit/temporal-markup";
-
-import {
- decodeMediaFit,
- decodeMediaFramePaint,
- decodeMediaHandoffSpec,
- decodeMediaItemSpec,
- decodeMediaMotion,
- decodeMediaPaintSpec,
- decodeMediaSampleSpec,
- decodeMediaSequenceSpec,
-} from "./author.js";
-import {
- sealMediaSequenceMemberSpec,
-} from "./sequence.js";
-import { sealMediaSoundSpec } from "./sounds.js";
-import { sealMediaTrackHeader } from "./program.js";
-import { mediaTrackProducers, mediaTrackTypes } from "./manifest.js";
-import type {
- MediaHandoffSpec,
- MediaSampleLayerSpec,
- MediaSamplingMotion,
- MediaSequenceMemberSpec,
- MediaSoundSpec,
-} from "./types.js";
-
-const input = (name: string) => ({ kind: "fragment-input" as const, name });
-const operation = (id: string) => ({ kind: "fragment-operation" as const, operation: id });
-
-function numberValue(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 reference(
- raw: MarkupAttributeValue | undefined,
- label: string,
- expected: TypeRef,
- 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 recipe(value: SurfaceResolvedReference, label: string): SvsRecipe {
- if (!sameType(value.type, svsRecipeType) || value.record?.value.kind !== "inline") {
- throw new Error(`${label} must be an authored SVS Recipe.`);
- }
- return value.record.value.value as unknown as SvsRecipe;
-}
-
-type FragmentLayer =
- | { readonly kind: "paint"; readonly specName: string }
- | { readonly kind: "still"; readonly sourceName: string; readonly extentName: string; readonly fitName: string; readonly specName: string }
- | { readonly kind: "timed" | "surface"; readonly sourceName: string; readonly fitName: string; readonly specName: string };
-
-type FragmentSound = { readonly sourceName: string; readonly specName: string };
-
-type FragmentItem = {
- readonly suffix: string;
- readonly windowName: string;
- readonly frameName: string;
- readonly specName: string;
- readonly clipPathName?: string;
- readonly layers: readonly FragmentLayer[];
- readonly sounds: readonly FragmentSound[];
-};
-
-type FragmentMember = {
- readonly suffix: string;
- readonly instantName: string;
- readonly specName: string;
- readonly layers: readonly FragmentLayer[];
-};
-
-type FragmentSequence = {
- readonly suffix: string;
- readonly terminalName: string;
- readonly frameName: string;
- readonly specName: string;
- readonly clipPathName?: string;
- readonly members: readonly FragmentMember[];
- readonly sounds: readonly FragmentSound[];
-};
-
-function appendLayers(operations: FragmentOperation[], prefix: string, layers: readonly FragmentLayer[]): string {
- const emptyId = `${prefix}:layers:empty`;
- operations.push({ id: emptyId, producer: mediaTrackProducers.createLayers, inputs: {}, result: { kind: "output", name: "layers" } });
- let current = emptyId;
- for (const [index, layer] of layers.entries()) {
- const id = `${prefix}:layers:${String(index + 1).padStart(4, "0")}`;
- const common = { layers: operation(current), spec: input(layer.specName) };
- if (layer.kind === "paint") {
- operations.push({ id, producer: mediaTrackProducers.appendPaintLayer, inputs: common, result: { kind: "output", name: "layers" } });
- } else if (layer.kind === "still") {
- operations.push({ id, producer: mediaTrackProducers.appendStillLayer, inputs: {
- ...common, source: input(layer.sourceName), extent: input(layer.extentName), fit: input(layer.fitName),
- }, result: { kind: "output", name: "layers" } });
- } else {
- operations.push({ id, producer: layer.kind === "timed" ? mediaTrackProducers.appendTimedLayer : mediaTrackProducers.appendSurfaceLayer,
- inputs: { ...common, source: input(layer.sourceName), fit: input(layer.fitName) }, result: { kind: "output", name: "layers" } });
- }
- current = id;
- }
- return current;
-}
-
-function appendSounds(operations: FragmentOperation[], prefix: string, sounds: readonly FragmentSound[]): string {
- const emptyId = `${prefix}:sounds:empty`;
- operations.push({ id: emptyId, producer: mediaTrackProducers.createSounds, inputs: {}, result: { kind: "output", name: "sounds" } });
- let current = emptyId;
- for (const [index, sound] of sounds.entries()) {
- const id = `${prefix}:sounds:${String(index + 1).padStart(4, "0")}`;
- operations.push({ id, producer: mediaTrackProducers.appendSound, inputs: {
- sounds: operation(current), source: input(sound.sourceName), spec: input(sound.specName),
- }, result: { kind: "output", name: "sounds" } });
- current = id;
- }
- return current;
-}
-
-function createMediaTrackSurfaceFragment(inputTypes: readonly { readonly name: string; readonly type: TypeRef }[], items: readonly FragmentItem[], sequences: readonly FragmentSequence[], audio: boolean) {
- const operations: FragmentOperation[] = [
- { id: "track:set:empty", producer: mediaTrackProducers.createSet, inputs: {}, result: { kind: "output", name: "set" } },
- ];
- let set = "track:set:empty";
- for (const item of items) {
- const prefix = `item:${item.suffix}`;
- const layers = appendLayers(operations, prefix, item.layers);
- const sounds = appendSounds(operations, prefix, item.sounds);
- const appendId = `${prefix}:append`;
- let spec: FragmentOperation["inputs"][string] = input(item.specName);
- if (item.clipPathName !== undefined) {
- const bindId = `${prefix}:bind-clip-path`;
- operations.push({ id: bindId, producer: mediaTrackProducers.bindItemClipPath, inputs: {
- spec, path: input(item.clipPathName),
- }, result: { kind: "output", name: "spec" } });
- spec = operation(bindId);
- }
- const common = {
- set: operation(set), header: input("header"), timeline: input("timeline"), canvas: input("canvas"),
- layers: operation(layers), frame: input(item.frameName), spec, sounds: operation(sounds), window: input(item.windowName),
- };
- operations.push({ id: appendId, producer: mediaTrackProducers.appendItem,
- inputs: common, result: { kind: "output", name: "set" } });
- set = appendId;
- }
- for (const sequence of sequences) {
- const prefix = `sequence:${sequence.suffix}`;
- const emptyMembers = `${prefix}:members:empty`;
- operations.push({ id: emptyMembers, producer: mediaTrackProducers.createMembers, inputs: {}, result: { kind: "output", name: "members" } });
- let members = emptyMembers;
- for (const member of sequence.members) {
- const memberPrefix = `${prefix}:member:${member.suffix}`;
- const layers = appendLayers(operations, memberPrefix, member.layers);
- const appendId = `${memberPrefix}:append`;
- operations.push({ id: appendId, producer: mediaTrackProducers.appendMember, inputs: {
- members: operation(members), timeline: input("timeline"), layers: operation(layers), spec: input(member.specName), activation: input(member.instantName),
- }, result: { kind: "output", name: "members" } });
- members = appendId;
- }
- const sounds = appendSounds(operations, prefix, sequence.sounds);
- const appendId = `${prefix}:append`;
- let spec: FragmentOperation["inputs"][string] = input(sequence.specName);
- if (sequence.clipPathName !== undefined) {
- const bindId = `${prefix}:bind-clip-path`;
- operations.push({ id: bindId, producer: mediaTrackProducers.bindSequenceClipPath, inputs: {
- spec, path: input(sequence.clipPathName),
- }, result: { kind: "output", name: "spec" } });
- spec = operation(bindId);
- }
- const common = {
- set: operation(set), header: input("header"), timeline: input("timeline"), canvas: input("canvas"),
- members: operation(members), frame: input(sequence.frameName), spec, sounds: operation(sounds),
- };
- operations.push({ id: appendId, producer: mediaTrackProducers.appendSequence,
- inputs: { ...common, terminal: input(sequence.terminalName) }, result: { kind: "output", name: "set" } });
- set = appendId;
- }
- operations.push(
- { id: "track:finalize", producer: mediaTrackProducers.finalize, inputs: { set: operation(set), header: input("header"), timeline: input("timeline") }, result: { kind: "output", name: "program" } },
- { id: "track:visual", producer: mediaTrackProducers.projectVisual, inputs: { timeline: input("timeline"), program: operation("track:finalize") }, result: { kind: "output", name: "track" } },
- );
- if (audio) operations.push({ id: "track:audio", producer: mediaTrackProducers.projectAudio, inputs: { timeline: input("timeline"), program: operation("track:finalize") }, result: { kind: "output", name: "track" } });
- return sealGraphFragment({
- inputs: inputTypes,
- operations,
- exports: [
- { name: "program", type: mediaTrackTypes.program, root: operation("track:finalize") },
- { name: "visual", type: compositionTypes.visualTrack, root: operation("track:visual") },
- ...(audio ? [{ name: "audio" as const, type: compositionTypes.audioTrack, root: operation("track:audio") }] : []),
- ],
- });
-}
-
-type SurfaceBuilder = {
- readonly records: SurfaceRecordDraft[];
- readonly inputs: Record<string, SurfaceResolvedReference["ref"] | { readonly kind: "record"; readonly id: string }>;
- readonly inputTypes: { name: string; type: TypeRef }[];
- addReference(name: string, value: SurfaceResolvedReference): void;
- addRecord(name: string, id: string, type: TypeRef, value: unknown, range: StructuredElement["range"]): void;
- addValue(name: string, value: SurfaceResolvedReference["ref"], type: TypeRef): void;
-};
-
-function builder(): SurfaceBuilder {
- const records: SurfaceRecordDraft[] = [];
- const inputs: SurfaceBuilder["inputs"] = {};
- const inputTypes: SurfaceBuilder["inputTypes"] = [];
- return {
- records,
- inputs,
- inputTypes,
- addReference(name, value) {
- if (inputs[name] !== undefined) throw new Error(`Media Surface repeats input ${name}.`);
- inputs[name] = value.ref;
- inputTypes.push({ name, type: value.type });
- },
- addRecord(name, id, type, value, range) {
- if (inputs[name] !== undefined) throw new Error(`Media Surface repeats input ${name}.`);
- records.push({ id, type, value: { kind: "inline", value: value as never }, range });
- inputs[name] = { kind: "record", id };
- inputTypes.push({ name, type });
- },
- addValue(name, value, type) {
- if (inputs[name] !== undefined) throw new Error(`Media Surface repeats input ${name}.`);
- inputs[name] = value;
- inputTypes.push({ name, type });
- },
- };
-}
-
-function suffix(index: number): string {
- return String(index).padStart(4, "0");
-}
-
-type SourceLayerContext = {
- readonly trackId: string;
- readonly unitSuffix: string;
- readonly defaultRecipe: SvsRecipe;
- readonly sourceElement: StructuredElement;
- readonly source?: DeclaredVisualSource;
- readonly ignoreSiblingChildren?: boolean;
- readonly defaultLayerId?: string;
-};
-
-type DeclaredVisualSource =
- | { readonly kind: "image"; readonly value: SurfaceResolvedReference; readonly extent: SurfaceResolvedReference }
- | { readonly kind: "media"; readonly value: SurfaceResolvedReference }
- | { readonly kind: "surface"; readonly value: SurfaceResolvedReference };
-
-const VISUAL_SOURCE_ATTRIBUTES = ["image", "media", "surface"] as const;
-
-function declaredVisualSource(
- element: StructuredElement,
- resolve: (path: string) => SurfaceResolvedReference | undefined,
- required = false,
-): DeclaredVisualSource | undefined {
- const present = VISUAL_SOURCE_ATTRIBUTES.filter((name) => element.attributes[name] !== undefined);
- if (present.length === 0) {
- if (element.attributes.extent !== undefined) throw new Error(`${element.name}.extent requires image={Artifact}.`);
- if (element.attributes.audio !== undefined) throw new Error(`${element.name}.audio is no longer accepted; normalize the source explicitly and use media={...}.`);
- if (required) throw new Error(`${element.name} requires exactly one of image, media or surface.`);
- return undefined;
- }
- if (present.length !== 1) throw new Error(`${element.name} requires exactly one of image, media or surface.`);
- const kind = present[0]!;
- if (kind === "image") {
- if (element.attributes.audio !== undefined) throw new Error(`${element.name}.audio is no longer accepted; normalize the source explicitly and use media={...}.`);
- return {
- kind,
- value: reference(element.attributes.image, `${element.name}.image`, artifactTypes.blob, resolve),
- extent: reference(element.attributes.extent, `${element.name}.extent`, spatialTypes.extent, resolve),
- };
- }
- if (element.attributes.extent !== undefined) throw new Error(`${element.name}.extent is only valid with image={Artifact}.`);
- if (element.attributes.audio !== undefined) throw new Error(`${element.name}.audio is no longer accepted; normalize the source explicitly and use media={...}.`);
- return kind === "media"
- ? { kind, value: reference(element.attributes.media, `${element.name}.media`, mediaTypes.synchronized, resolve) }
- : { kind, value: reference(element.attributes.surface, `${element.name}.surface`, mediaTypes.compositableSurface, resolve) };
-}
-
-export function decodeMediaSamplingKeyframe(element: StructuredElement): MediaSamplingMotion["keyframes"][number] {
- allowed(element, ["at", "zoom", "x", "y", "rotate", "easing"]);
- empty(element);
- const at = text(element, "at");
- const percentage = /^(\d+(?:\.\d+)?)%$/u.exec(at);
- const atProgress = at === "start" ? 0 : at === "end" ? 1
- : percentage === null ? Number.NaN : Number(percentage[1]) / 100;
- if (!Number.isFinite(atProgress) || atProgress < 0 || atProgress > 1) {
- throw new Error(`${element.name}.at must be start, end or a percentage inside 0%..100%.`);
- }
- const easing = optionalText(element, "easing");
- if (easing !== undefined && !["linear", "ease-in", "ease-out", "ease-in-out"].includes(easing)) {
- throw new Error(`${element.name}.easing is invalid.`);
- }
- return {
- atProgress, zoom: numberValue(element, "zoom", 1), offsetX: numberValue(element, "x", 0),
- offsetY: numberValue(element, "y", 0), rotationDeg: numberValue(element, "rotate", 0),
- ...(easing === undefined ? {} : { easing: easing as "linear" | "ease-in" | "ease-out" | "ease-in-out" }),
- };
-}
-
-function decodeSamplingMotion(element: StructuredElement, ignoreSiblingChildren = false): MediaSamplingMotion | undefined {
- const keyframes = element.children.flatMap((child) => {
- if (child.kind === "text") {
- if (child.value.trim().length > 0) throw new Error(`${element.name} accepts only Sampling children.`);
- return [];
- }
- if (!child.name.endsWith(":Sampling") && child.name !== "Sampling") {
- if (ignoreSiblingChildren) return [];
- throw new Error(`${element.name} accepts only Sampling children.`);
- }
- return [decodeMediaSamplingKeyframe(child)];
- });
- return keyframes.length === 0 ? undefined : { keyframes };
-}
-
-function sourceLayer(
- state: SurfaceBuilder,
- context: SourceLayerContext,
- layerIndex: number,
- resolve: (path: string) => SurfaceResolvedReference | undefined,
-): FragmentLayer {
- const element = context.sourceElement;
- const source = context.source ?? declaredVisualSource(element, resolve, true)!;
- const appearance = element.attributes.appearance === undefined
- ? context.defaultRecipe
- : recipe(reference(element.attributes.appearance, `${element.name}.appearance`, svsRecipeType, resolve), `${element.name}.appearance`);
- const motion = decodeSamplingMotion(element, context.ignoreSiblingChildren);
- const layerSuffix = `${context.unitSuffix}-layer-${suffix(layerIndex)}`;
- const layerId = context.defaultLayerId ?? optionalText(element, "id") ?? `${context.trackId}.${layerSuffix}`;
- const fitName = `${layerSuffix}-fit`;
- const specName = `${layerSuffix}-spec`;
- state.addRecord(fitName, `${context.trackId}.${layerSuffix}.fit`, spatialTypes.fit, decodeMediaFit(appearance), element.range);
- const sourceKind = source.kind === "image" ? "still"
- : source.kind === "surface" ? "surface" : "timed";
- const spec = decodeMediaSampleSpec(appearance, layerId, sourceKind, motion, context.source !== undefined);
- state.addRecord(specName, `${context.trackId}.${layerSuffix}.spec`, mediaTrackTypes.sampleLayerSpec, spec, element.range);
- const sourceName = `${layerSuffix}-source`;
- state.addReference(sourceName, source.value);
- if (sourceKind === "still") {
- const extentName = `${layerSuffix}-extent`;
- state.addReference(extentName, (source as Extract<DeclaredVisualSource, { readonly kind: "image" }>).extent);
- return { kind: "still", sourceName, extentName, fitName, specName };
- }
- return { kind: sourceKind, sourceName, fitName, specName };
-}
-
-function unitLayers(
- state: SurfaceBuilder,
- input: {
- readonly trackId: string;
- readonly unitSuffix: string;
- readonly element: StructuredElement;
- readonly appearance: SvsRecipe;
- readonly directSource?: DeclaredVisualSource;
- readonly allowFramePaint: boolean;
- readonly allowEmpty?: boolean;
- },
- resolve: (path: string) => SurfaceResolvedReference | undefined,
-): readonly FragmentLayer[] {
- const layers: FragmentLayer[] = [];
- if (input.allowFramePaint) {
- const framePaint = decodeMediaFramePaint(input.appearance, `${input.trackId}.${input.unitSuffix}.frame-paint`);
- if (framePaint !== undefined) {
- const name = `${input.unitSuffix}-frame-paint`;
- state.addRecord(name, `${input.trackId}.${input.unitSuffix}.frame-paint`, mediaTrackTypes.paintLayerSpec, framePaint, input.element.range);
- layers.push({ kind: "paint", specName: name });
- }
- }
- const explicit = input.element.children.filter((child): child is StructuredElement => child.kind === "element"
- && (child.name.endsWith(":Paint") || child.name === "Paint" || child.name.endsWith(":Layer") || child.name === "Layer"));
- if (input.directSource !== undefined && explicit.length > 0) {
- throw new Error(`${input.element.name} cannot combine a direct source with Paint or Layer children.`);
- }
- if (input.directSource !== undefined) {
- layers.push(sourceLayer(state, {
- trackId: input.trackId, unitSuffix: input.unitSuffix, defaultRecipe: input.appearance,
- sourceElement: input.element, source: input.directSource,
- ignoreSiblingChildren: true,
- defaultLayerId: "content",
- }, 1, resolve));
- return layers;
- }
- let layerIndex = 0;
- for (const child of explicit) {
- layerIndex += 1;
- if (child.name.endsWith(":Paint") || child.name === "Paint") {
- allowed(child, ["id", "appearance"]);
- empty(child);
- const appearance = recipe(reference(child.attributes.appearance, `${child.name}.appearance`, svsRecipeType, resolve), `${child.name}.appearance`);
- const id = optionalText(child, "id") ?? `${input.trackId}.${input.unitSuffix}.paint.${suffix(layerIndex)}`;
- const name = `${input.unitSuffix}-paint-${suffix(layerIndex)}`;
- state.addRecord(name, `${input.trackId}.${input.unitSuffix}.paint.${suffix(layerIndex)}`, mediaTrackTypes.paintLayerSpec,
- decodeMediaPaintSpec(appearance, id), child.range);
- layers.push({ kind: "paint", specName: name });
- continue;
- }
- allowed(child, ["id", "image", "media", "surface", "extent", "appearance"]);
- layers.push(sourceLayer(state, {
- trackId: input.trackId, unitSuffix: input.unitSuffix, defaultRecipe: input.appearance, sourceElement: child,
- }, layerIndex, resolve));
- }
- if (layers.length === 0 && !input.allowEmpty) throw new Error(`${input.element.name} requires a direct source or at least one Paint/Layer child.`);
- return layers;
-}
-
-function validateUnitChildren(element: StructuredElement, direct: boolean, allowSound: boolean): void {
- for (const child of element.children) {
- if (child.kind === "text") {
- if (child.value.trim().length > 0) throw new Error(`${element.name} cannot contain text.`);
- continue;
- }
- const samplingChild = child.name.endsWith(":Sampling") || child.name === "Sampling";
- const layerChild = child.name.endsWith(":Layer") || child.name === "Layer";
- const paintChild = child.name.endsWith(":Paint") || child.name === "Paint";
- const soundChild = child.name.endsWith(":Sound") || child.name === "Sound";
- if ((direct && samplingChild) || (!direct && (layerChild || paintChild)) || (allowSound && soundChild)) continue;
- throw new Error(`${element.name} has unsupported child ${child.name}.`);
- }
-}
-
-function sourceAudio(
- element: StructuredElement,
-): MediaSequenceMemberSpec["sourceAudio"] {
- const fromLayer = optionalText(element, "source-audio");
- if (fromLayer === undefined) {
- if (element.attributes["audio-gain"] !== undefined) throw new Error(`${element.name}.audio-gain requires source-audio.`);
- return undefined;
- }
- return { fromLayer, gain: numberValue(element, "audio-gain", 1) };
-}
-
-function sound(
- state: SurfaceBuilder,
- element: StructuredElement,
- unitSuffix: string,
- trackId: string,
- index: number,
- handoffIds: ReadonlySet<string>,
- resolve: (path: string) => SurfaceResolvedReference | undefined,
-): FragmentSound {
- allowed(element, ["id", "source", "at", "handoff", "gain"]);
- empty(element);
- const at = optionalText(element, "at");
- const handoff = optionalText(element, "handoff");
- if (Number(at !== undefined) + Number(handoff !== undefined) !== 1) {
- throw new Error(`${element.name} requires exactly one of at or handoff.`);
- }
- let trigger: MediaSoundSpec["trigger"];
- if (handoff !== undefined) {
- if (!handoffIds.has(handoff)) throw new Error(`${element.name}.handoff does not name a Handoff in this Sequence.`);
- trigger = { kind: "handoff", handoffId: handoff };
- } else {
- if (at !== "enter" && at !== "exit") throw new Error(`${element.name}.at must be enter or exit.`);
- trigger = { kind: at };
- }
- const soundSuffix = `${unitSuffix}-sound-${suffix(index)}`;
- const specName = `${soundSuffix}-spec`;
- const sourceName = `${soundSuffix}-source`;
- const id = optionalText(element, "id") ?? `${trackId}.${soundSuffix}`;
- state.addRecord(specName, `${trackId}.${soundSuffix}.spec`, mediaTrackTypes.soundSpec,
- sealMediaSoundSpec({ id, trigger, gain: numberValue(element, "gain", 1) }), element.range);
- state.addReference(sourceName, reference(element.attributes.source, `${element.name}.source`, mediaTypes.synchronized, resolve));
- return { sourceName, specName };
-}
-
-export const decodeMediaTrackSurface: StructuredSurfaceHandler = ({ element, resolveReference }) => {
- allowed(element, ["id", "timeline", "canvas"]);
- const trackId = text(element, "id");
- const state = builder();
- const context = resolveTemporalContext({ element, resolveReference });
- state.addReference("timeline", context.timeline);
- state.addReference("canvas", reference(element.attributes.canvas, `${element.name}.canvas`, spatialTypes.canvas, resolveReference));
- const headerId = `${trackId}.header`;
- state.addRecord("header", headerId, mediaTrackTypes.header,
- sealMediaTrackHeader({ id: trackId }), element.range);
- const items: FragmentItem[] = [];
- const sequences: FragmentSequence[] = [];
- const temporalComponents: SurfaceComponentDraft[] = [];
- const temporalFragments: ReturnType<typeof createTemporalWindowProjection>["fragments"][number][] = [];
- let itemIndex = 0;
- let sequenceIndex = 0;
- let hasAudio = false;
- for (const child of element.children) {
- if (child.kind === "text") {
- if (child.value.trim().length > 0) throw new Error(`${element.name} accepts only Item and Sequence children.`);
- continue;
- }
- if (child.name.endsWith(":Item") || child.name === "Item") {
- itemIndex += 1;
- const itemSuffix = suffix(itemIndex);
- allowed(child, [
- "id", "frame", "appearance", "motion",
- "image", "media", "surface", "extent", "source-audio", "audio-gain",
- "clip", ...temporalWindowAttributeNames,
- ]);
- const id = optionalText(child, "id") ?? `${trackId}.item.${itemSuffix}`;
- const appearance = recipe(reference(child.attributes.appearance, `${child.name}.appearance`, svsRecipeType, resolveReference), `${child.name}.appearance`);
- const clipPathName = child.attributes.clip === undefined ? undefined : `item-${itemSuffix}-clip-path`;
- if (clipPathName !== undefined) {
- if (appearance.properties.clip !== undefined) throw new Error(`${child.name} cannot combine clip={Path} with Recipe clip.`);
- state.addReference(clipPathName, reference(child.attributes.clip, `${child.name}.clip`, spatialTypes.path, resolveReference));
- }
- const motionRecipe = child.attributes.motion === undefined ? undefined
- : recipe(reference(child.attributes.motion, `${child.name}.motion`, svsRecipeType, resolveReference), `${child.name}.motion`);
- const temporal = createTemporalWindowProjection({ id, element: child, ...context, resolveReference });
- state.records.push(...temporal.records); temporalComponents.push(...temporal.components); temporalFragments.push(...temporal.fragments);
- const directSource = declaredVisualSource(child, resolveReference);
- validateUnitChildren(child, directSource !== undefined, true);
- const layers = unitLayers(state, { trackId, unitSuffix: `item-${itemSuffix}`, element: child, appearance,
- ...(directSource === undefined ? {} : { directSource }), allowFramePaint: true, allowEmpty: false }, resolveReference);
- const selectedAudio = sourceAudio(child);
- const specName = `item-${itemSuffix}-spec`;
- const windowName = `item-${itemSuffix}-window`;
- state.addValue(windowName, temporal.ref, temporalTypes.window);
- state.addRecord(specName, `${trackId}.item.${itemSuffix}.spec`, mediaTrackTypes.itemSpec,
- decodeMediaItemSpec(appearance, { id,
- motion: decodeMediaMotion(motionRecipe), ...(selectedAudio === undefined ? {} : { sourceAudio: selectedAudio }) }), child.range);
- const frameName = `item-${itemSuffix}-frame`;
- state.addReference(frameName, reference(child.attributes.frame, `${child.name}.frame`, spatialTypes.frame, resolveReference));
- const fragmentSounds: FragmentSound[] = [];
- for (const soundChild of child.children) {
- if (soundChild.kind === "element" && (soundChild.name.endsWith(":Sound") || soundChild.name === "Sound")) {
- fragmentSounds.push(sound(state, soundChild, `item-${itemSuffix}`, trackId, fragmentSounds.length + 1, new Set(), resolveReference));
- }
- }
- if (selectedAudio !== undefined || fragmentSounds.length > 0) hasAudio = true;
- items.push({ suffix: itemSuffix, windowName, frameName, specName,
- ...(clipPathName === undefined ? {} : { clipPathName }), layers, sounds: fragmentSounds });
- continue;
- }
- if (!(child.name.endsWith(":Sequence") || child.name === "Sequence")) {
- throw new Error(`${element.name} accepts only Item and Sequence children.`);
- }
- sequenceIndex += 1;
- const sequenceSuffix = suffix(sequenceIndex);
- allowed(child, ["id", "frame", "clip", "appearance", "motion", "until", "until-boundary"]);
- const id = optionalText(child, "id") ?? `${trackId}.sequence.${sequenceSuffix}`;
- const appearance = recipe(reference(child.attributes.appearance, `${child.name}.appearance`, svsRecipeType, resolveReference), `${child.name}.appearance`);
- const clipPathName = child.attributes.clip === undefined ? undefined : `sequence-${sequenceSuffix}-clip-path`;
- if (clipPathName !== undefined) {
- if (appearance.properties.clip !== undefined) throw new Error(`${child.name} cannot combine clip={Path} with Recipe clip.`);
- state.addReference(clipPathName, reference(child.attributes.clip, `${child.name}.clip`, spatialTypes.path, resolveReference));
- }
- const motionRecipe = child.attributes.motion === undefined ? undefined
- : recipe(reference(child.attributes.motion, `${child.name}.motion`, svsRecipeType, resolveReference), `${child.name}.motion`);
- const memberElements = child.children.filter((node): node is StructuredElement => node.kind === "element" && (node.name.endsWith(":Member") || node.name === "Member"));
- if (memberElements.length < 2) throw new Error(`${child.name} requires at least two Member children.`);
- const memberIds = memberElements.map((member, index) => optionalText(member, "id") ?? `${id}.member.${suffix(index + 1)}`);
- const handoffElements = child.children.filter((node): node is StructuredElement => node.kind === "element" && (node.name.endsWith(":Handoff") || node.name === "Handoff"));
- if (handoffElements.length !== memberIds.length - 1) throw new Error(`${child.name} requires exactly one Handoff for every adjacent Member pair.`);
- const handoffs: MediaHandoffSpec[] = [];
- for (const [index, handoff] of handoffElements.entries()) {
- allowed(handoff, ["id", "from", "transition"]);
- empty(handoff);
- const from = text(handoff, "from");
- if (from !== memberIds[index]) throw new Error(`${handoff.name}.from must name Member ${memberIds[index]}.`);
- const handoffId = optionalText(handoff, "id") ?? `${id}.handoff.${suffix(index + 1)}`;
- const transition = recipe(reference(handoff.attributes.transition, `${handoff.name}.transition`, svsRecipeType, resolveReference), `${handoff.name}.transition`);
- handoffs.push(decodeMediaHandoffSpec(transition, handoffId, from, memberIds[index + 1]!));
- }
- const handoffIds = new Set(handoffs.map((handoff) => handoff.id));
- const members: FragmentMember[] = [];
- for (const [index, member] of memberElements.entries()) {
- const memberSuffix = suffix(index + 1);
- allowed(member, ["id", "image", "media", "surface", "extent", "appearance", ...temporalInstantAttributeNames, "source-audio", "audio-gain"]);
- const temporal = createTemporalInstantProjection({ id: `${id}.${memberIds[index]}`, subjectId: memberIds[index]!, element: member, ...context, resolveReference });
- state.records.push(...temporal.records); temporalComponents.push(...temporal.components); temporalFragments.push(...temporal.fragments);
- const memberAppearance = member.attributes.appearance === undefined ? appearance
- : recipe(reference(member.attributes.appearance, `${member.name}.appearance`, svsRecipeType, resolveReference), `${member.name}.appearance`);
- const directSource = declaredVisualSource(member, resolveReference);
- validateUnitChildren(member, directSource !== undefined, false);
- const unitSuffix = `sequence-${sequenceSuffix}-member-${memberSuffix}`;
- const layers = unitLayers(state, { trackId, unitSuffix, element: member, appearance: memberAppearance,
- ...(directSource === undefined ? {} : { directSource }), allowFramePaint: true }, resolveReference);
- const selectedAudio = sourceAudio(member);
- if (selectedAudio !== undefined) hasAudio = true;
- const specName = `${unitSuffix}-spec`;
- state.addRecord(specName, `${trackId}.${unitSuffix}.spec`, mediaTrackTypes.memberSpec,
- sealMediaSequenceMemberSpec({ id: memberIds[index]!,
- ...(selectedAudio === undefined ? {} : { sourceAudio: selectedAudio }) }), member.range);
- const instantName = `${unitSuffix}-instant`;
- state.addValue(instantName, temporal.ref, temporalTypes.instant);
- members.push({ suffix: memberSuffix, instantName, specName, layers });
- }
- const sequenceSounds: FragmentSound[] = [];
- for (const soundChild of child.children) {
- if (soundChild.kind === "element" && (soundChild.name.endsWith(":Sound") || soundChild.name === "Sound")) {
- sequenceSounds.push(sound(state, soundChild, `sequence-${sequenceSuffix}`, trackId, sequenceSounds.length + 1, handoffIds, resolveReference));
- } else if (soundChild.kind === "element" && !(
- soundChild.name.endsWith(":Member") || soundChild.name === "Member"
- || soundChild.name.endsWith(":Handoff") || soundChild.name === "Handoff"
- )) throw new Error(`${child.name} accepts only Member, Handoff and Sound children.`);
- }
- if (sequenceSounds.length > 0) hasAudio = true;
- const terminalTemporal = createTemporalInstantProjection({
- id: `${id}.terminal`, subjectId: id, element: child, ...context, resolveReference,
- semanticAttribute: "until", boundaryAttribute: "until-boundary", projectedAttribute: false,
- boundaryFallback: "end",
- });
- state.records.push(...terminalTemporal.records); temporalComponents.push(...terminalTemporal.components); temporalFragments.push(...terminalTemporal.fragments);
- const frameName = `sequence-${sequenceSuffix}-frame`;
- state.addReference(frameName, reference(child.attributes.frame, `${child.name}.frame`, spatialTypes.frame, resolveReference));
- const specName = `sequence-${sequenceSuffix}-spec`;
- state.addRecord(specName, `${trackId}.sequence.${sequenceSuffix}.spec`, mediaTrackTypes.sequenceSpec,
- decodeMediaSequenceSpec(appearance, id, decodeMediaMotion(motionRecipe), handoffs), child.range);
- const terminalName = `sequence-${sequenceSuffix}-terminal`;
- state.addValue(terminalName, terminalTemporal.ref, temporalTypes.instant);
- sequences.push({ suffix: sequenceSuffix, terminalName, frameName, specName,
- ...(clipPathName === undefined ? {} : { clipPathName }), members, sounds: sequenceSounds });
- }
- if (items.length === 0 && sequences.length === 0) throw new Error(`${element.name} requires at least one Item or Sequence.`);
- const fragment = createMediaTrackSurfaceFragment(state.inputTypes, items, sequences, hasAudio);
- return {
- records: state.records,
- components: [...temporalComponents, { id: trackId, fragment: fragment.id, inputs: state.inputs,
- outputs: { program: `${trackId}.program`, visual: `${trackId}.visual`, ...(hasAudio ? { audio: `${trackId}.audio` } : {}) }, range: element.range }],
- fragments: [...temporalFragments, fragment],
- exports: [`${trackId}.program`, `${trackId}.visual`, ...(hasAudio ? [`${trackId}.audio`] : [])],
- };
-};
diff --git a/packages/media-track/src/types.ts b/packages/media-track/src/types.ts
deleted file mode 100644
index 8536f6a1..00000000
--- a/packages/media-track/src/types.ts
+++ /dev/null
@@ -1,311 +0,0 @@
-import type { FrameSpan, VisualTimedSampling } from "@hypit/composition";
-import type { CompositableSurfaceRef, MediaRational } from "@hypit/media";
-import type { BlobRef } from "@hypit/protocol";
-import type {
- ContentFit,
- IntrinsicExtent,
- SpatialFrame,
- SpatialPath,
-} from "@hypit/spatial";
-
-/** Intrinsic visual truth resolved before Media authoring; never a Provider or lineage envelope. */
-export type MediaVisualSource =
- | {
- readonly kind: "still";
- readonly artifact: BlobRef;
- readonly extent: IntrinsicExtent;
- }
- | {
- readonly kind: "timed";
- readonly artifact: BlobRef;
- readonly extent: IntrinsicExtent;
- readonly frameRate: MediaRational;
- readonly frameCount: number;
- readonly audio?: {
- readonly artifact: BlobRef;
- readonly sampleFrames: number;
- };
- }
- | {
- readonly kind: "surface";
- readonly surface: CompositableSurfaceRef;
- readonly extent: IntrinsicExtent;
- };
-
-export type MediaVisualTrim = {
- readonly startFrame: number;
- readonly endFrameExclusive: number;
-};
-
-export type MediaVisualOccupancy =
- | { readonly mode: "once"; readonly align: "start" | "end" }
- | { readonly mode: "hold"; readonly align: "start" | "end" }
- | { readonly mode: "loop"; readonly align: "start" | "end" }
- | { readonly mode: "stretch" };
-
-export type MediaGradientStop = {
- readonly offset: number;
- readonly color: string;
-};
-
-export type MediaPaint =
- | { readonly kind: "solid"; readonly color: string }
- | {
- readonly kind: "linear-gradient";
- readonly angleDeg: number;
- readonly stops: readonly MediaGradientStop[];
- }
- | {
- readonly kind: "radial-gradient";
- readonly center: { readonly x: number; readonly y: number };
- readonly stops: readonly MediaGradientStop[];
- };
-
-export type MediaSampleAppearance = {
- readonly opacity: number;
- readonly filter: {
- readonly blurPx: number;
- readonly brightness: number;
- readonly contrast: number;
- readonly saturation: number;
- };
-};
-
-export type MediaSamplingKeyframe = {
- /** Normalized position inside the resolved Item/member envelope. */
- readonly atProgress: number;
- readonly zoom: number;
- readonly offsetX: number;
- readonly offsetY: number;
- readonly rotationDeg: number;
- readonly easing?: "linear" | "ease-in" | "ease-out" | "ease-in-out";
-};
-
-export type MediaSamplingMotion = {
- readonly keyframes: readonly MediaSamplingKeyframe[];
-};
-
-export type MediaPaintLayerProgram = {
- readonly id: string;
- readonly kind: "paint";
- readonly paint: MediaPaint;
- readonly opacity: number;
-};
-
-export type MediaSampleLayerProgram = {
- readonly id: string;
- readonly kind: "sample";
- readonly sampling?: VisualTimedSampling;
- readonly source: MediaVisualSource;
- readonly fit: ContentFit;
- readonly trim?: MediaVisualTrim;
- readonly occupancy?: MediaVisualOccupancy;
- readonly appearance: MediaSampleAppearance;
- readonly samplingMotion?: MediaSamplingMotion;
-};
-
-export type MediaLayerProgram = MediaPaintLayerProgram | MediaSampleLayerProgram;
-
-export type MediaPaintLayerSpec = {
- readonly id: string;
- readonly paint: MediaPaint;
- readonly opacity: number;
-};
-
-export type MediaSampleLayerSpec = {
- readonly id: string;
- readonly trim?: MediaVisualTrim;
- readonly occupancy?: MediaVisualOccupancy;
- readonly appearance: MediaSampleAppearance;
- readonly samplingMotion?: MediaSamplingMotion;
-};
-
-export type MediaLayerSet = {
- readonly layers: readonly MediaLayerProgram[];
-};
-
-export type MediaPadding = {
- readonly topPx: number;
- readonly rightPx: number;
- readonly bottomPx: number;
- readonly leftPx: number;
-};
-
-export type MediaFrameClip =
- | { readonly kind: "none" }
- | { readonly kind: "frame" }
- | { readonly kind: "rounded"; readonly radiusPx: number }
- | { readonly kind: "path"; readonly path: SpatialPath };
-
-export type MediaFramePresentation = {
- readonly clip: MediaFrameClip;
- readonly padding: MediaPadding;
- readonly border?: {
- readonly widthPx: number;
- readonly style: "solid" | "dashed" | "dotted";
- readonly color: string;
- };
- readonly shadows: readonly {
- readonly offsetX: number;
- readonly offsetY: number;
- readonly blurPx: number;
- readonly spreadPx: number;
- readonly color: string;
- }[];
-};
-
-export type MediaMotionDirection = "left" | "right" | "up" | "down";
-
-export type MediaEdgeMotion = {
- readonly operator: "fade" | "slide" | "scale" | "pop" | "bounce" | "blur-reveal" | "wipe" | "flip" | "spin";
- readonly durationFrames: number;
- readonly easing: "linear" | "ease-in" | "ease-out" | "ease-in-out";
- readonly direction?: MediaMotionDirection;
- readonly amount?: number;
- readonly origin?: "outside-canvas";
-};
-
-export type MediaSustainMotion = {
- readonly operator: "float" | "breathe" | "pulse" | "wobble" | "shake" | "drift";
- readonly amount: number;
- readonly cycles: number;
- readonly direction?: MediaMotionDirection;
-};
-
-export type MediaLifecycleMotion = {
- readonly enter?: MediaEdgeMotion;
- readonly sustain: readonly MediaSustainMotion[];
- readonly exit?: MediaEdgeMotion;
-};
-
-export type MediaSourceAudioProjection = {
- readonly fromLayer: string;
- readonly gain: number;
-};
-
-export type MediaSoundSource = {
- readonly artifact: BlobRef;
- readonly sampleFrames: number;
-};
-
-export type MediaSoundTrigger =
- | { readonly kind: "enter" }
- | { readonly kind: "exit" }
- | { readonly kind: "handoff"; readonly handoffId: string };
-
-export type MediaSoundSpec = {
- readonly id: string;
- readonly trigger: MediaSoundTrigger;
- readonly gain: number;
-};
-
-export type MediaSoundEvent = MediaSoundSpec & {
- readonly source: MediaSoundSource;
-};
-
-export type MediaSoundSet = {
- readonly sounds: readonly MediaSoundEvent[];
-};
-
-export type MediaAbsoluteStacking = {
- readonly order: number;
- readonly tieBreak: string;
-};
-
-export type MediaItemSpec = {
- readonly id: string;
- readonly presentation: MediaFramePresentation;
- readonly motion: MediaLifecycleMotion;
- readonly stackingOrder: number;
- readonly sourceAudio?: MediaSourceAudioProjection;
-};
-
-export type MediaItemProgram = {
- readonly id: string;
- /** Author-owned Item realized by this externally projected window. */
- readonly subjectId: string;
- readonly span: FrameSpan;
- readonly frame: SpatialFrame;
- readonly presentation: MediaFramePresentation;
- readonly layers: readonly MediaLayerProgram[];
- readonly motion: MediaLifecycleMotion;
- readonly stacking: MediaAbsoluteStacking;
- readonly sourceAudio?: MediaSourceAudioProjection;
- readonly sounds: readonly MediaSoundEvent[];
-};
-
-export type MediaHandoffOperator = "cut" | "crossfade" | "push" | "wipe" | "cover" | "page-turn";
-
-export type MediaHandoffProgram = {
- readonly id: string;
- readonly fromMemberId: string;
- readonly toMemberId: string;
- readonly operator: MediaHandoffOperator;
- readonly durationFrames: number;
- readonly boundaryRatio: number;
- readonly span: FrameSpan;
- readonly direction?: MediaMotionDirection;
- readonly audio: "cut" | "crossfade";
-};
-
-export type MediaSequenceMemberProgram = {
- readonly id: string;
- readonly activationFrame: number;
- readonly logicalSpan: FrameSpan;
- readonly visualSpan: FrameSpan;
- readonly layers: readonly MediaLayerProgram[];
- readonly sourceAudio?: MediaSourceAudioProjection;
-};
-
-export type MediaSequenceMemberSpec = {
- readonly id: string;
- readonly sourceAudio?: MediaSourceAudioProjection;
-};
-
-export type MediaSequenceMemberSet = {
- readonly members: readonly {
- readonly id: string;
- readonly activationFrame: number;
- readonly layers: readonly MediaLayerProgram[];
- readonly sourceAudio?: MediaSourceAudioProjection;
- }[];
-};
-
-export type MediaHandoffSpec = Omit<MediaHandoffProgram, "span"> & {
-};
-
-export type MediaSequenceSpec = {
- readonly id: string;
- readonly presentation: MediaFramePresentation;
- readonly motion: MediaLifecycleMotion;
- readonly stackingOrder: number;
- readonly handoffs: readonly MediaHandoffSpec[];
-};
-
-export type MediaSequenceProgram = {
- readonly id: string;
- readonly span: FrameSpan;
- readonly terminalFrame: number;
- readonly frame: SpatialFrame;
- readonly presentation: MediaFramePresentation;
- readonly members: readonly MediaSequenceMemberProgram[];
- readonly handoffs: readonly MediaHandoffProgram[];
- readonly motion: MediaLifecycleMotion;
- readonly stacking: MediaAbsoluteStacking;
- readonly sounds: readonly MediaSoundEvent[];
-};
-
-export type MediaTrackProgram = {
- readonly id: string;
- readonly items: readonly MediaItemProgram[];
- readonly sequences: readonly MediaSequenceProgram[];
-};
-
-export type MediaTrackHeader = {
- readonly id: string;
-};
-
-export type MediaTrackSet = {
- readonly items: readonly MediaItemProgram[];
- readonly sequences: readonly MediaSequenceProgram[];
-};
diff --git a/packages/media-track/test/media-track.test.ts b/packages/media-track/test/media-track.test.ts
deleted file mode 100644
index e14c10ff..00000000
--- a/packages/media-track/test/media-track.test.ts
+++ /dev/null
@@ -1,1019 +0,0 @@
-import { appendMediaPerformance } from "@hypit/performance";
-import { sealTimeline } from "@hypit/timeline";
-import assert from "node:assert/strict";
-import test from "node:test";
-import { fixtureResource } from "../../../test/fixture-resource.js";
-import { timelineFixture } from "../../../test/timeline-fixture.js";
-import { projectMomentWindow, projectProgramWindow, projectSegmentWindow, projectSelectionWindow } from "../../../test/temporal-fixture.js";
-import type { TemporalWindowProjection } from "../../../test/temporal-fixture.js";
-
-import { sealComposition } from "@hypit/composition";
-import type { AudioTrack } from "@hypit/composition";
-import { compileHyperframesDocument } from "@hypit/hyperframes";
-import { mediaTypes } from "@hypit/media";
-import type { CompositableSurfaceRef, SynchronizedMedia } from "@hypit/media";
-import { artifactTypes } from "@hypit/artifact";
-import { narrativeTypes } from "@hypit/narrative";
-import {
- appendMediaPaintLayer,
- appendMediaSound,
- appendMediaItem,
- appendMediaSequence as appendProjectedMediaSequence,
- appendMediaSequenceMember as appendProjectedMediaSequenceMember,
- appendStillMediaLayer,
- appendSurfaceMediaLayer,
- appendTimedMediaLayer,
- bindMediaItemClipPath,
- createMediaLayerSet,
- createMediaSequenceMemberSet,
- createMediaSoundSet,
- createMediaTrackSet,
- decodeMediaTrackSurface,
- finalizeMediaTrack,
- projectMediaAudioTrack,
- projectMediaVisualTrack,
- lifecycleAnimation,
- resolveMediaLifecycleMotion,
- sustainAnimation,
- resolveVisualSampling,
- sealMediaItemSpec,
- sealMediaHandoffSpec,
- sealMediaPaintLayerSpec,
- sealMediaSampleLayerSpec,
- sealMediaSoundSpec,
- sealMediaSequenceMemberSpec,
- sealMediaSequenceSpec,
- sealMediaTrackHeader,
- stillMediaTrackFragment,
- mediaTrackManifest,
- mediaTrackMarkupSurfaces,
-} from "@hypit/media-track";
-import type {
- MediaHandoffOperator,
- MediaItemSpec,
- MediaLayerSet,
- MediaSequenceSpec,
-} from "@hypit/media-track";
-import type { NarrativeMomentRef, NarrativeSelectionRef } from "@hypit/narrative";
-import { sealProgramSpace } from "@hypit/program-space";
-import { programSpaceTypes } from "@hypit/program-space";
-import type { BlobRef } from "@hypit/protocol";
-import { timelineTypes } from "@hypit/timeline";
-import { spatialTypes } from "@hypit/spatial";
-import { svsRecipeType } from "@hypit/svs";
-import type { SvsRecipe } from "@hypit/svs";
-import type { StructuredElement, StructuredNode, SurfaceResolvedReference, MarkupAttributeValue } from "@hypit/markup";
-import type { TemporalWindow } from "@hypit/temporal";
-
-const space = sealTimeline({ items: [], id: "test-space", durationSec: 4,
- frameRate: { numerator: 30, denominator: 1 },
-});
-const canvas = {
- widthPx: 1080,
- heightPx: 1920,
- origin: "top-left" as const,
- xDirection: "right" as const,
- yDirection: "down" as const,
- pixelAspect: "square" as const,
-};
-const header = sealMediaTrackHeader({ id: "proof" });
-const semantic = timelineFixture(space, {
- segments: [
- { id: "opening", frameCount: 30 },
- { id: "answer", frameCount: 60 },
- { id: "ending", frameCount: 30 },
- ],
- anchors: [
- { identity: "a", frame: 15 }, { identity: "b", frame: 45 },
- { identity: "c", frame: 60 }, { identity: "d", frame: 105 },
- ],
-});
-const source: BlobRef = {
- kind: "blob",
- resource: fixtureResource("media-track:still"),
- size: 4_096,
- mediaType: "image/png",
-};
-const extent = { widthPx: 800, heightPx: 800 };
-const frame = { xPx: 100, yPx: 200, widthPx: 400, heightPx: 300 };
-const fit = {
- sizing: "contain" as const,
- framePoint: { x: 0.5, y: 0.5 },
- contentPoint: { x: 0.5, y: 0.5 },
- offsetPx: { x: 0, y: 0 },
- constraint: "bounded" as const,
-};
-const appearance = {
- opacity: 1,
- filter: { blurPx: 0, brightness: 1, contrast: 1, saturation: 1 },
-};
-
-type TestMediaItemSpec = MediaItemSpec & { readonly projection: TemporalWindowProjection };
-const defaultItemProjection: TemporalWindowProjection = {
- start: { ref: "program.start" }, end: { ref: "program.end" },
-};
-
-function itemSpec(overrides: Partial<TestMediaItemSpec> = {}): TestMediaItemSpec {
- const { projection = defaultItemProjection, ...itemOverrides } = overrides;
- return {
- ...sealMediaItemSpec({
-
- id: "product",
- presentation: {
- clip: { kind: "rounded", radiusPx: 20 },
- padding: { topPx: 10, rightPx: 10, bottomPx: 10, leftPx: 10 },
- border: { widthPx: 2, style: "solid", color: "#ffffff" },
- shadows: [{ offsetX: 0, offsetY: 8, blurPx: 20, spreadPx: 0, color: "#00000080" }],
- },
- motion: { sustain: [] },
- stackingOrder: 40,
- ...itemOverrides,
- }),
- projection,
- };
-}
-
-function appendProgramMediaItem(
- set: ReturnType<typeof createMediaTrackSet>, trackHeader: typeof header, timeline: typeof semantic,
- canvasSpace: typeof canvas, layers: MediaLayerSet, frameValue: typeof frame, authored: MediaItemSpec | TestMediaItemSpec,
- sounds: ReturnType<typeof createMediaSoundSet>,
-) {
- const projection = "projection" in authored ? authored.projection : defaultItemProjection;
- const { projection: _ignored, ...spec } = authored as TestMediaItemSpec;
- return appendMediaItem(set, trackHeader, space, canvasSpace, layers, frameValue, spec, sounds,
- projectProgramWindow({ itemId: spec.id, semantic: timeline, projection }));
-}
-
-function appendSelectionMediaItem(
- set: ReturnType<typeof createMediaTrackSet>, trackHeader: typeof header, timeline: typeof semantic,
- canvasSpace: typeof canvas, layers: MediaLayerSet, frameValue: typeof frame, selection: NarrativeSelectionRef,
- authored: TestMediaItemSpec, sounds: ReturnType<typeof createMediaSoundSet>,
-) {
- const { projection, ...spec } = authored;
- return appendMediaItem(set, trackHeader, space, canvasSpace, layers, frameValue, spec, sounds,
- projectSelectionWindow({ itemId: spec.id, semantic: timeline, selection, projection }));
-}
-
-function appendSegmentMediaItem(
- set: ReturnType<typeof createMediaTrackSet>, trackHeader: typeof header, timeline: typeof semantic,
- canvasSpace: typeof canvas, layers: MediaLayerSet, frameValue: typeof frame, segment: { narrativeId: string; kind: "segment"; id: string; tokenStart: number; tokenEndExclusive: number },
- authored: TestMediaItemSpec, sounds: ReturnType<typeof createMediaSoundSet>,
-) {
- const { projection, ...spec } = authored;
- return appendMediaItem(set, trackHeader, space, canvasSpace, layers, frameValue, spec, sounds,
- projectSegmentWindow({ itemId: spec.id, semantic: timeline, segment, projection }));
-}
-
-function appendMomentMediaItem(
- set: ReturnType<typeof createMediaTrackSet>, trackHeader: typeof header, timeline: typeof semantic,
- canvasSpace: typeof canvas, layers: MediaLayerSet, frameValue: typeof frame, moment: NarrativeMomentRef,
- authored: TestMediaItemSpec, sounds: ReturnType<typeof createMediaSoundSet>,
-) {
- const { projection, ...spec } = authored;
- return appendMediaItem(set, trackHeader, space, canvasSpace, layers, frameValue, spec, sounds,
- projectMomentWindow({ itemId: spec.id, semantic: timeline, moment, projection }));
-}
-
-function stillLayers(): MediaLayerSet {
- let layers = createMediaLayerSet();
- layers = appendMediaPaintLayer(layers, sealMediaPaintLayerSpec({
-
- id: "backing",
- paint: { kind: "linear-gradient", angleDeg: 90, stops: [
- { offset: 0, color: "#101010" }, { offset: 1, color: "#303030" },
- ] },
- opacity: 1,
- }));
- layers = appendStillMediaLayer(layers, source, extent, fit, sealMediaSampleLayerSpec({
-
- id: "content",
- appearance,
- }));
- return layers;
-}
-
-function timed(id = "timed", withAudio = true): SynchronizedMedia {
- const sampleFrames = 96_000;
- return {
- timeline: {
- frameRate: { numerator: 30, denominator: 1 },
- frameCount: 60,
- },
- visual: {
- artifact: { kind: "blob", resource: fixtureResource(`video:${id}`), size: 10_000, mediaType: "video/mp4" },
- width: 720,
- height: 1280,
- },
- ...(withAudio ? { audio: {
- artifact: { kind: "blob" as const, resource: fixtureResource(`audio:${id}`), size: sampleFrames * 4, mediaType: "audio/wav" },
- } } : {}),
- };
-}
-
-function timedLayers(id: string, withAudio = true): MediaLayerSet {
- return appendTimedMediaLayer(createMediaLayerSet(), timed(id, withAudio), fit, sealMediaSampleLayerSpec({
-
- id: "video",
- occupancy: { mode: "loop", align: "start" },
- appearance,
- }));
-}
-
-function sequenceMembers(
- activations: readonly number[] = [0, 40, 80],
- layerFactory: (index: number) => MediaLayerSet = (index) => timedLayers(`member-${index + 1}`),
-) {
- let members = createMediaSequenceMemberSet();
- for (const [index, activationFrame] of activations.entries()) {
- const spec = sealMediaSequenceMemberSpec({
-
- id: `member-${index + 1}`,
- sourceAudio: { fromLayer: "video", gain: 1 - (index * 0.1) },
- });
- members = appendProjectedMediaSequenceMember(members, space, layerFactory(index), spec, {
- id: `${spec.id}::test`,
- subjectId: spec.id,
- source: { spaceId: space.id, narrativeId: "script", kind: "program", id: "program" },
- projection: { ref: "program.start" },
- frame: activationFrame,
- authority: { kind: "fixed" },
- });
- }
- return members;
-}
-
-function testProgramWindow(endFrameExclusive: number): TemporalWindow {
- return {
- id: "program::test",
- subjectId: "program",
- start: { id: "program::test.start", subjectId: "program", source: { spaceId: space.id, narrativeId: "script", kind: "program", id: "program" }, projection: { ref: "program.start" }, frame: 0, authority: { kind: "fixed" } },
- end: { id: "program::test.end", subjectId: "program", source: { spaceId: space.id, narrativeId: "script", kind: "program", id: "program" }, projection: { ref: "program.end" }, frame: endFrameExclusive, authority: { kind: "fixed" } },
- span: { startFrame: 0, endFrameExclusive },
- };
-}
-
-function appendMediaSequence(
- set: ReturnType<typeof createMediaTrackSet>, trackHeader: typeof header, spaceValue: typeof space, canvasValue: typeof canvas,
- members: ReturnType<typeof createMediaSequenceMemberSet>, frameValue: typeof frame, spec: MediaSequenceSpec,
- sounds: ReturnType<typeof createMediaSoundSet>, terminalFrame: number,
-) {
- return appendProjectedMediaSequence(set, trackHeader, spaceValue, canvasValue, members, frameValue, spec, sounds, {
- id: `${spec.id}::terminal`, subjectId: spec.id, source: { spaceId: space.id, narrativeId: "script", kind: "program", id: "program" },
- projection: { ref: "program.end" }, frame: terminalFrame, authority: { kind: "fixed" },
- });
-}
-
-function appendMediaSequenceMember(
- set: ReturnType<typeof createMediaSequenceMemberSet>, layers: MediaLayerSet, spec: ReturnType<typeof sealMediaSequenceMemberSpec>, activationFrame: number,
-) {
- return appendProjectedMediaSequenceMember(set, space, layers, spec, {
- id: `${spec.id}::test`,
- subjectId: spec.id,
- source: { spaceId: space.id, narrativeId: "script", kind: "program", id: "program" },
- projection: { ref: "program.start" },
- frame: activationFrame,
- authority: { kind: "fixed" },
- });
-}
-
-function sequenceSpec(overrides: Partial<MediaSequenceSpec> = {}): MediaSequenceSpec {
- return sealMediaSequenceSpec({
-
- id: "steps",
- presentation: itemSpec().presentation,
- motion: {
- enter: { operator: "fade", durationFrames: 12, easing: "ease-out" },
- sustain: [{ operator: "float", amount: 4, cycles: 2 }],
- exit: { operator: "slide", durationFrames: 10, easing: "ease-in", direction: "down", amount: 60 },
- },
- stackingOrder: 50,
- handoffs: [
- sealMediaHandoffSpec({
- id: "one-two", fromMemberId: "member-1", toMemberId: "member-2",
- operator: "crossfade", durationFrames: 20, boundaryRatio: 0.5, audio: "crossfade",
- }),
- sealMediaHandoffSpec({
- id: "two-three", fromMemberId: "member-2", toMemberId: "member-3",
- operator: "push", durationFrames: 20, boundaryRatio: 0.5, direction: "left", audio: "cut",
- }),
- ],
- ...overrides,
- });
-}
-
-function sequenceSounds() {
- let sounds = createMediaSoundSet();
- for (const [id, trigger] of [
- ["enter-sound", { kind: "enter" as const }],
- ["handoff-out-sound", { kind: "handoff" as const, handoffId: "one-two" }],
- ["handoff-in-sound", { kind: "handoff" as const, handoffId: "one-two" }],
- ["exit-sound", { kind: "exit" as const }],
- ] as const) {
- sounds = appendMediaSound(sounds, timed(`sfx-${id}`), sealMediaSoundSpec({
- id, trigger, gain: 0.5,
- }));
- }
- return sounds;
-}
-
-test("an Item keeps ordered Paint/sample layers, two-frame fit and frame presentation package-owned", () => {
- const program = finalizeMediaTrack(appendProgramMediaItem(
- createMediaTrackSet(), header, semantic, canvas, stillLayers(), frame, itemSpec(), createMediaSoundSet(),
- ), header, space);
- assert.deepEqual(program.items[0]?.span, { startFrame: 0, endFrameExclusive: 120 });
- assert.deepEqual(program.items[0]?.layers.map((layer) => layer.id), ["backing", "content"]);
- const track = projectMediaVisualTrack(space, program);
- assert.deepEqual(track.presents[0]?.stacking, { order: 40, tieBreak: "proof:product" });
- const elements = track.presents[0]!.elements;
- assert.deepEqual(elements.slice(0, 3).map((element) => element.id), [
- "product:placement", "product:lifecycle", "product:frame",
- ]);
- const media = elements.find((element) => element.id === "content");
- assert.equal(media?.kind, "image");
- const wrapper = elements.find((element) => element.id === "content:sampling");
- // The fitting box is the Frame less its 2px border and its 10px padding. `box-sizing: border-box`
- // draws the border inside the Frame, so the content starts 12px in and is 24px smaller each way.
- assert.deepEqual(wrapper?.style, [
- { name: "height", value: "276px" },
- { name: "left", value: "62px" },
- { name: "position", value: "absolute" },
- { name: "top", value: "12px" },
- { name: "transform-origin", value: "center center" },
- { name: "width", value: "276px" },
- ]);
-});
-
-test("an owned clip path is an explicit Media input and lowers only over the Item's pixels", () => {
- // A Path is drawn in Canvas pixels, which is what `spatial` declares three times over. The Frame
- // sits at 100,200, so a trapezoid filling it is written from there and arrives at the Frame's own
- // box translated back to 0,0.
- const clipped = bindMediaItemClipPath(itemSpec(), {
- commands: [
- { kind: "move", xPx: 100, yPx: 200 },
- { kind: "line", xPx: 500, yPx: 200 },
- { kind: "line", xPx: 460, yPx: 500 },
- { kind: "line", xPx: 140, yPx: 500 },
- { kind: "close" },
- ],
- });
- const track = projectMediaVisualTrack(space, finalizeMediaTrack(appendProgramMediaItem(
- createMediaTrackSet(), header, semantic, canvas, stillLayers(), frame, clipped, createMediaSoundSet(),
- ), header, space));
- const frameElement = track.presents[0]!.elements.find((element) => element.id.endsWith(":frame"));
- assert.equal(frameElement?.style.find((entry) => entry.name === "clip-path")?.value,
- 'path("M 0 0 L 400 0 L 360 300 L 40 300 Z")');
-});
-
-test("self-blur is two explicit samples of one Resource and collection keeps one reference", () => {
- let layers = createMediaLayerSet();
- layers = appendStillMediaLayer(layers, source, extent, { ...fit, sizing: "cover" }, sealMediaSampleLayerSpec({
- id: "blurred", appearance: {
- opacity: 1, filter: { blurPx: 24, brightness: 0.7, contrast: 1, saturation: 0.8 },
- },
- }));
- layers = appendStillMediaLayer(layers, source, extent, fit, sealMediaSampleLayerSpec({
- id: "foreground", appearance,
- }));
- const track = projectMediaVisualTrack(space, finalizeMediaTrack(appendProgramMediaItem(
- createMediaTrackSet(), header, semantic, canvas, layers, frame, itemSpec(), createMediaSoundSet(),
- ), header, space));
- const document = compileHyperframesDocument(sealComposition({
- id: "media",
- canvas: { width: 1080, height: 1920, clearColor: "#000000" },
- tracks: [track],
- }), space);
- assert.equal(document.artifacts.length, 1);
- assert.equal((document.html.match(new RegExp(source.resource, "gu")) ?? []).length, 2,
- "HTML names the same declared Resource at both sampling sites");
- assert.equal((document.html.match(/hypit-resource:\/\/res_/gu) ?? []).length, 2);
- const blurred = track.presents[0]!.elements.find((element) => element.id === "blurred");
- assert.equal(blurred?.style.find((entry) => entry.name === "left")?.value, "-48px");
- assert.equal(blurred?.style.find((entry) => entry.name === "top")?.value, "-48px");
-});
-
-test("timed layer trim/hold, lifecycle and sampling motion remain separate wrapper channels", () => {
- let layers = createMediaLayerSet();
- layers = appendTimedMediaLayer(layers, timed(), fit, sealMediaSampleLayerSpec({
-
- id: "video",
- trim: { startFrame: 10, endFrameExclusive: 40 },
- occupancy: { mode: "hold", align: "start" },
- appearance,
- samplingMotion: { keyframes: [
- { atProgress: 0, zoom: 1, offsetX: 0, offsetY: 0, rotationDeg: 0 },
- { atProgress: 0.5, zoom: 1.1, offsetX: 10, offsetY: -5, rotationDeg: 1 },
- { atProgress: 1, zoom: 1.2, offsetX: 20, offsetY: -10, rotationDeg: 2, easing: "ease-out" },
- ] },
- }));
- const program = finalizeMediaTrack(appendProgramMediaItem(createMediaTrackSet(), header, semantic, canvas, layers, frame, itemSpec({
- motion: {
- enter: { operator: "slide", durationFrames: 12, easing: "ease-out", direction: "down", amount: 120 },
- sustain: [{ operator: "wobble", amount: 2, cycles: 2 }],
- exit: { operator: "fade", durationFrames: 10, easing: "ease-in" },
- },
- }), createMediaSoundSet()), header, space);
- const elements = projectMediaVisualTrack(space, program).presents[0]!.elements;
- assert.ok(elements.find((element) => element.id.endsWith(":lifecycle"))?.animation);
- assert.ok(elements.find((element) => element.id.includes(":sustain:"))?.animation);
- const samplingWrapper = elements.find((element) => element.id === "video:sampling");
- assert.ok(samplingWrapper?.animation);
- assert.deepEqual(samplingWrapper?.animation?.keyframes.map((entry) => entry.atFrame), [0, 60, 120]);
- const video = elements.find((element) => element.id === "video");
- assert.equal(video?.kind, "video");
- assert.deepEqual(video.kind === "video" ? video.sampling?.segments : undefined, [
- { target: { startFrame: 0, endFrameExclusive: 30 }, sourceFrame: { numerator: 10, denominator: 1 }, rate: { numerator: 1, denominator: 1 } },
- { target: { startFrame: 30, endFrameExclusive: 120 }, sourceFrame: { numerator: 39, denominator: 1 }, rate: { numerator: 0, denominator: 1 } },
- ]);
- const overlapping = lifecycleAnimation({
- enter: { operator: "fade", durationFrames: 70, easing: "linear" },
- sustain: [],
- exit: { operator: "fade", durationFrames: 60, easing: "linear" },
- }, 120)!;
- const overlapFrame = overlapping.keyframes.find((keyframe) => keyframe.atFrame === 65)!;
- const overlapOpacity = overlapFrame.style.find((declaration) => declaration.name === "opacity")?.value;
- assert.equal(typeof overlapOpacity, "number");
- assert.ok((overlapOpacity as number) > 0 && (overlapOpacity as number) < 1);
-});
-
-test("source audio and edge SFX project separately from the visual Track", () => {
- let layers = createMediaLayerSet();
- layers = appendTimedMediaLayer(layers, timed("audio"), fit, sealMediaSampleLayerSpec({
-
- id: "video",
- trim: { startFrame: 10, endFrameExclusive: 40 },
- occupancy: { mode: "hold", align: "end" },
- appearance,
- }));
- let sounds = createMediaSoundSet();
- sounds = appendMediaSound(sounds, timed("sfx-enter"), sealMediaSoundSpec({
- id: "enter-sound", trigger: { kind: "enter" }, gain: 0.5,
- }));
- sounds = appendMediaSound(sounds, timed("sfx-exit"), sealMediaSoundSpec({
- id: "exit-sound", trigger: { kind: "exit" }, gain: 0.25,
- }));
- const program = finalizeMediaTrack(appendProgramMediaItem(createMediaTrackSet(), header, semantic, canvas, layers, frame, itemSpec({
- sourceAudio: { fromLayer: "video", gain: 0.75 },
- motion: { sustain: [], exit: { operator: "fade", durationFrames: 10, easing: "ease-in" } },
- }), sounds), header, space);
- const visual = projectMediaVisualTrack(space, program);
- const audio = projectMediaAudioTrack(space, program);
- assert.equal(visual.presents.length, 1);
- assert.equal(audio.clips.length, 3);
- const sourceClip = audio.clips.find((clip) => clip.id.endsWith(":source-audio"));
- assert.deepEqual(sourceClip?.target, { startSample: 144_000, endSampleExclusive: 192_000 });
- assert.deepEqual(sourceClip?.source, {
- sampleFrames: 96_000,
- startSample: 16_000,
- endSampleExclusive: 64_000,
- loop: false,
- phaseSample: 0,
- });
- assert.equal(sourceClip?.gain, 0.75);
- assert.throws(() => projectMediaAudioTrack(space, finalizeMediaTrack(appendProgramMediaItem(
- createMediaTrackSet(), header, semantic, canvas, stillLayers(), frame, itemSpec(), createMediaSoundSet(),
- ), header, space)), /no explicitly authored audio/u);
-
- const bgm: AudioTrack = {
- kind: "audio",
- id: "independent-bgm",
- programSpaceId: space.id,
- clips: [{
- id: "bed",
- artifact: timed("bgm").audio!.artifact,
- target: { startSample: 0, endSampleExclusive: 192_000 },
- source: {
- sampleFrames: 96_000,
- startSample: 0,
- endSampleExclusive: 96_000,
- loop: true,
- phaseSample: 0,
- },
- playbackRate: 1,
- pitch: "preserve",
- gain: 0.2,
- fadeInSamples: 0,
- fadeOutSamples: 0,
- }],
- };
- const composition = sealComposition({
- id: "media-with-peer-bgm",
- canvas: { width: 1080, height: 1920, clearColor: "#000000" },
- tracks: [visual, audio, bgm],
- });
- assert.deepEqual(composition.tracks.find((candidate) => candidate.id === bgm.id), bgm,
- "Media visual/audio projection must not rewrite an independent peer BGM Track");
-});
-
-test("still and animated typed Surfaces use the same layer law without browser format guesses", () => {
- const still: CompositableSurfaceRef = {
- artifact: { kind: "blob", resource: fixtureResource("surface:still"), size: 500, mediaType: "image/png" },
- width: 100,
- height: 100,
- colorSpace: "srgb",
- alphaMode: "straight",
- timing: { kind: "still" },
- };
- const animated: CompositableSurfaceRef = {
- ...still,
- artifact: { kind: "blob", resource: fixtureResource("surface:animated"), size: 2_000, mediaType: "video/webm" },
- timing: { kind: "frames", frameRate: { numerator: 30, denominator: 1 }, frameCount: 30 },
- };
- let layers = appendSurfaceMediaLayer(createMediaLayerSet(), still, fit, sealMediaSampleLayerSpec({
- id: "still", appearance,
- }));
- layers = appendSurfaceMediaLayer(layers, animated, fit, sealMediaSampleLayerSpec({
- id: "animated", occupancy: { mode: "loop", align: "start" }, appearance,
- }));
- const elements = projectMediaVisualTrack(space, finalizeMediaTrack(appendProgramMediaItem(
- createMediaTrackSet(), header, semantic, canvas, layers, frame, itemSpec(), createMediaSoundSet(),
- ), header, space)).presents[0]!.elements;
- assert.equal(elements.find((element) => element.id === "still")?.kind, "surface");
- const moving = elements.find((element) => element.id === "animated");
- assert.equal(moving?.kind, "surface");
- assert.ok(moving?.kind === "surface" && moving.sampling !== undefined);
- const defaulted = appendSurfaceMediaLayer(createMediaLayerSet(), animated, fit, sealMediaSampleLayerSpec({
- id: "defaulted", appearance,
- }));
- assert.deepEqual(defaulted.layers[0]?.kind === "sample" ? defaulted.layers[0].occupancy : undefined,
- { mode: "once", align: "start" });
-});
-
-test("Media Items consume singular Selection and Moment sources without becoming an exclusive lane", () => {
- const selection: NarrativeSelectionRef = {
- narrativeId: "script",
- id: "mentions",
- startAnchorId: "a",
- endAnchorId: "b",
- };
- const selected = appendSelectionMediaItem(createMediaTrackSet(), header, semantic, canvas, stillLayers(), frame,
- selection, itemSpec({
- id: "mention",
- projection: { start: { ref: "selection.start" }, end: { ref: "selection.end" } },
- }), createMediaSoundSet());
- assert.deepEqual(selected.items.map((item) => item.span), [{ startFrame: 15, endFrameExclusive: 45 }]);
- const moment: NarrativeMomentRef = {
- narrativeId: "script",
- id: "cue", anchorId: "b",
- };
- const overlapping = appendMomentMediaItem(selected, header, semantic, canvas, stillLayers(), frame,
- moment, itemSpec({
- id: "popup",
- projection: { start: { ref: "moment.cue", offset: { unit: "frames", value: -10 } }, end: { ref: "moment.cue", offset: { unit: "frames", value: 20 } } },
- stackingOrder: 41,
- }), createMediaSoundSet());
- assert.deepEqual(overlapping.items[1]?.span, { startFrame: 35, endFrameExclusive: 65 });
- const track = projectMediaVisualTrack(space, finalizeMediaTrack(overlapping, header, space));
- assert.deepEqual(track.presents.map((present) => present.stacking.order), [40, 41]);
-
- const absolute = appendProgramMediaItem(
- createMediaTrackSet(), header, semantic, canvas, stillLayers(), frame,
- itemSpec({
- id: "absolute",
- projection: {
- start: { ref: "absolute", at: { unit: "frames", value: 7 } },
- end: { ref: "absolute", at: { unit: "frames", value: 19 } },
- },
- }), createMediaSoundSet(),
- );
- assert.deepEqual(absolute.items[0]?.span, { startFrame: 7, endFrameExclusive: 19 });
-});
-
-test("a Media Item can consume one whole Narrative Segment without a synthetic Selection", () => {
- const result = appendSegmentMediaItem(
- createMediaTrackSet(), header, semantic, canvas, stillLayers(), frame,
- { narrativeId: "script", kind: "segment", id: "answer", tokenStart: 0, tokenEndExclusive: 1 },
- itemSpec({
- id: "whole-answer",
- projection: { start: { ref: "segment.start" }, end: { ref: "segment.end" } },
- }),
- createMediaSoundSet(),
- );
- assert.deepEqual(result.items.map((item) => item.span), [{ startFrame: 30, endFrameExclusive: 90 }]);
-});
-
-test("every declared lifecycle and sustain operator lowers, and outside-canvas motion resolves from explicit geometry", () => {
- for (const operator of ["fade", "slide", "scale", "pop", "bounce", "blur-reveal", "wipe", "flip", "spin"] as const) {
- const direction = ["slide", "wipe", "flip"].includes(operator) ? { direction: "up" as const } : {};
- assert.ok(lifecycleAnimation({ enter: { operator, durationFrames: 10, easing: "ease-out", ...direction }, sustain: [] }, 30));
- }
- for (const operator of ["float", "breathe", "pulse", "wobble", "shake", "drift"] as const) {
- assert.ok(sustainAnimation({ operator, amount: 2, cycles: 2, ...(operator === "drift" ? { direction: "right" as const } : {}) }, 30));
- }
- const resolved = resolveMediaLifecycleMotion({
- enter: { operator: "slide", durationFrames: 8, easing: "ease-out", direction: "up", origin: "outside-canvas" },
- sustain: [],
- exit: { operator: "slide", durationFrames: 8, easing: "ease-in", direction: "down", origin: "outside-canvas" },
- }, frame, canvas);
- assert.deepEqual(resolved.enter, { operator: "slide", durationFrames: 8, easing: "ease-out", direction: "up", amount: 500 });
- assert.deepEqual(resolved.exit, { operator: "slide", durationFrames: 8, easing: "ease-in", direction: "down", amount: 1_720 });
-});
-
-test("every documented Media frame and fit remains one ordinary Item instead of a mode", () => {
- const frames = [
- { xPx: 0, yPx: 0, widthPx: 1080, heightPx: 1920 },
- { xPx: 0, yPx: 0, widthPx: 540, heightPx: 1920 },
- { xPx: 80, yPx: 1280, widthPx: 920, heightPx: 500 },
- { xPx: 760, yPx: 80, widthPx: 260, heightPx: 360 },
- { xPx: -120, yPx: 1400, widthPx: 500, heightPx: 600 },
- ];
- const sizings = ["contain", "cover", "fit-width", "fit-height", "native", "scale-down", "stretch"] as const;
- let set = createMediaTrackSet();
- for (const [index, sizing] of sizings.entries()) {
- const localFit = { ...fit, sizing,
- framePoint: { x: index % 2 === 0 ? 0.2 : 0.8, y: 0.75 },
- contentPoint: { x: 0.65, y: 0.1 },
- constraint: index % 2 === 0 ? "bounded" as const : "free" as const,
- };
- const layers = appendStillMediaLayer(createMediaLayerSet(), source,
- { widthPx: index % 3 === 0 ? 400 : index % 3 === 1 ? 1200 : 800,
- heightPx: index % 3 === 0 ? 1200 : index % 3 === 1 ? 400 : 800 },
- localFit, sealMediaSampleLayerSpec({ id: `sample-${index}`, appearance }));
- set = appendProgramMediaItem(set, header, semantic, canvas, layers, frames[index % frames.length]!, itemSpec({
- id: `fit-${sizing}`, stackingOrder: 100 + index,
- presentation: { clip: { kind: "none" }, padding: { topPx: 0, rightPx: 0, bottomPx: 0, leftPx: 0 }, shadows: [] },
- }), createMediaSoundSet());
- }
- const track = projectMediaVisualTrack(space, finalizeMediaTrack(set, header, space));
- assert.equal(track.presents.length, sizings.length);
- for (const present of track.presents) {
- const placement = present.elements[0]!;
- assert.equal(placement.kind, "box");
- assert.ok(placement.style.some((entry) => entry.name === "width" && typeof entry.value === "string"));
- assert.ok(placement.style.some((entry) => entry.name === "height" && typeof entry.value === "string"));
- }
-});
-
-test("transparent, Paint, self-blur and alternate-source backing are only ordered owned layers", () => {
- const alternate: BlobRef = { kind: "blob", resource: fixtureResource("media-track:alternate"), size: 2_048, mediaType: "image/webp" };
- let layers = createMediaLayerSet();
- layers = appendMediaPaintLayer(layers, sealMediaPaintLayerSpec({
- id: "solid", paint: { kind: "solid", color: "#101018" }, opacity: 1,
- }));
- layers = appendStillMediaLayer(layers, source, extent, { ...fit, sizing: "cover" }, sealMediaSampleLayerSpec({
- id: "self-blur", appearance: {
- opacity: 1, filter: { blurPx: 32, brightness: 0.7, contrast: 1.1, saturation: 0.8 },
- },
- }));
- layers = appendStillMediaLayer(layers, alternate, { ...extent, widthPx: 1200, heightPx: 600 }, { ...fit, sizing: "cover" },
- sealMediaSampleLayerSpec({ id: "alternate", appearance }));
- layers = appendStillMediaLayer(layers, source, extent, fit,
- sealMediaSampleLayerSpec({ id: "foreground", appearance }));
- const track = projectMediaVisualTrack(space, finalizeMediaTrack(appendProgramMediaItem(
- createMediaTrackSet(), header, semantic, canvas, layers, frame, itemSpec(), createMediaSoundSet(),
- ), header, space));
- const document = compileHyperframesDocument(sealComposition({
- id: "layer-matrix", canvas: { width: 1080, height: 1920, clearColor: "#000000" }, tracks: [track],
- }), space);
- assert.deepEqual(track.presents[0]!.elements.filter((element) => element.kind === "image").map((element) => element.id),
- ["self-blur", "alternate", "foreground"]);
- assert.equal(document.artifacts.length, 2, "repeated samples share bytes while the alternate source remains explicit");
-
- const transparent = projectMediaVisualTrack(space, finalizeMediaTrack(appendProgramMediaItem(
- createMediaTrackSet(), header, semantic, canvas,
- appendStillMediaLayer(createMediaLayerSet(), source, extent, fit,
- sealMediaSampleLayerSpec({ id: "only", appearance })),
- frame, itemSpec(), createMediaSoundSet(),
- ), header, space));
- assert.equal(transparent.presents[0]!.elements.some((element) =>
- element.kind === "box" && element.style.some((entry) => entry.name === "background")), false);
-});
-
-test("visual-only normalized video never creates an implicit audio branch", () => {
- const silent = timedLayers("silent", false);
- const program = finalizeMediaTrack(appendProgramMediaItem(
- createMediaTrackSet(), header, semantic, canvas, silent, frame, itemSpec(), createMediaSoundSet(),
- ), header, space);
- assert.equal(projectMediaVisualTrack(space, program).presents[0]!.elements.some((element) => element.kind === "video"), true);
- assert.throws(() => projectMediaAudioTrack(space, program), /no explicitly authored audio projection/u);
- assert.throws(() => appendProgramMediaItem(
- createMediaTrackSet(), header, semantic, canvas, silent, frame,
- itemSpec({ sourceAudio: { fromLayer: "video", gain: 1 } }), createMediaSoundSet(),
- ), /has no normalized audio/u);
-});
-
-test("timed visual occupancy resolves every alignment into exact source-frame segments", () => {
- const sampling = (occupancy: Parameters<typeof resolveVisualSampling>[0]["occupancy"]) =>
- resolveVisualSampling({ timeline: space, sourceFrameRate: { numerator: 30, denominator: 1 }, sourceFrameCount: 30, targetFrameCount: 50, occupancy });
- assert.deepEqual(sampling({ mode: "once", align: "start" }).segments.map((item) => item.target), [{ startFrame: 0, endFrameExclusive: 30 }]);
- assert.deepEqual(sampling({ mode: "once", align: "end" }).segments.map((item) => item.target), [{ startFrame: 20, endFrameExclusive: 50 }]);
- assert.deepEqual(sampling({ mode: "loop", align: "end" }).segments[0]?.sourceFrame, { numerator: 10, denominator: 1 });
- assert.deepEqual(sampling({ mode: "stretch" }).segments[0]?.rate, { numerator: 3, denominator: 5 });
- assert.throws(() => resolveVisualSampling({
- timeline: space, sourceFrameRate: { numerator: 24, denominator: 1 }, sourceFrameCount: 24, targetFrameCount: 30,
- occupancy: { mode: "once", align: "start" },
- }), /normalized to Timeline frame rate/u);
-});
-
-test("the graph keeps every source, extent, fit, frame, time and appearance input explicit", () => {
- assert.deepEqual(stillMediaTrackFragment.inputs.map((input) => input.name), [
- "canvas", "extent", "fit", "frame", "header", "item-spec", "sample-spec", "source", "timeline", "window",
- ]);
-});
-
-test("the Media author Surface emits explicit graph edges for layers, semantic time, Sequence topology and sound", async () => {
- const range = { source: "media-surface.svml", start: 0, end: 1 };
- const ref = (path: string): MarkupAttributeValue => ({ kind: "reference", path });
- const node = (name: string, attributes: Record<string, MarkupAttributeValue>, children: StructuredNode[] = []): StructuredElement => ({
- kind: "element", name, attributes, children, range,
- });
- const appearance = (path: string, properties: SvsRecipe["properties"]): SurfaceResolvedReference => ({
- path,
- ref: { kind: "record", id: path },
- type: svsRecipeType,
- record: { value: { kind: "inline", value: { path, properties } } } as never,
- });
- const plain = (path: string, type: SurfaceResolvedReference["type"]): SurfaceResolvedReference => ({
- path, ref: { kind: "record", id: path }, type,
- });
- const references = new Map<string, SurfaceResolvedReference>([
- ["canvas", plain("canvas", spatialTypes.canvas)],
- ["semantic", plain("semantic", timelineTypes.track)],
- ["frame", plain("frame", spatialTypes.frame)],
- ["clip-path", plain("clip-path", spatialTypes.path)],
- ["still", plain("still", artifactTypes.blob)],
- ["extent", plain("extent", spatialTypes.extent)],
- ["video", plain("video", mediaTypes.synchronized)],
- ["surface", plain("surface", mediaTypes.compositableSurface)],
- ["sfx", plain("sfx", mediaTypes.synchronized)],
- ["selection", plain("selection", narrativeTypes.selection)],
- ["answer-segment", plain("answer-segment", narrativeTypes.excerpt)],
- ["terminal", plain("terminal", narrativeTypes.selection)],
- ["cue1", plain("cue1", narrativeTypes.moment)],
- ["cue2", plain("cue2", narrativeTypes.moment)],
- ["still-style", appearance("still-style", { "stack-order": 20, fit: "contain" })],
- ["card-style", appearance("card-style", { "stack-order": 30, clip: "frame", "frame-paint": "#111111" })],
- ["video-style", appearance("video-style", { fit: "cover", playback: "hold-start", opacity: 1 })],
- ["paint-style", appearance("paint-style", { paint: "linear(90;#111111@0,#333333@1)", opacity: 1 })],
- ["sequence-style", appearance("sequence-style", { "stack-order": 40, fit: "contain", clip: "frame" })],
- ["surface-style", appearance("surface-style", { fit: "cover", playback: "loop-start" })],
- ["motion", appearance("motion", { enter: "slide", "enter-frames": 12, "enter-easing": "ease-out", "enter-direction": "up", "enter-origin": "outside-canvas" })],
- ["handoff", appearance("handoff", { operator: "crossfade", "duration-frames": 10, "boundary-ratio": 0.5, audio: "cut" })],
- ]);
- const root = node("media:Track", { id: "editorial", timeline: ref("semantic"), canvas: ref("canvas") }, [
- node("media:Item", { id: "still-card", image: ref("still"), extent: ref("extent"), frame: ref("frame"), clip: ref("clip-path"), appearance: ref("still-style"), during: "program" }),
- node("media:Item", { id: "segment-card", image: ref("still"), extent: ref("extent"), frame: ref("frame"), appearance: ref("still-style"), during: ref("answer-segment") }),
- node("media:Item", { id: "proof", frame: ref("frame"), appearance: ref("card-style"), motion: ref("motion"), during: ref("selection"), "source-audio": "video", "audio-gain": "0.8" }, [
- node("media:Paint", { id: "backing", appearance: ref("paint-style") }),
- node("media:Layer", { id: "video", media: ref("video"), appearance: ref("video-style") }, [
- node("media:Sampling", { at: "start", zoom: "1" }),
- node("media:Sampling", { at: "end", zoom: "1.1", y: "-10", easing: "ease-out" }),
- ]),
- node("media:Sound", { id: "proof-enter", source: ref("sfx"), at: "enter", gain: "0.5" }),
- ]),
- node("media:Item", { image: ref("still"), extent: ref("extent"), id: "presenter", frame: ref("frame"), clip: ref("clip-path"), appearance: ref("still-style"), motion: ref("motion"), during: ref("answer-segment") }, [
- node("media:Sampling", { at: "start", zoom: "1" }),
- node("media:Sampling", { at: "end", zoom: "1.08", x: "6" }),
- node("media:Sound", { id: "presenter-enter", source: ref("sfx"), at: "enter" }),
- ]),
- node("media:Item", { image: ref("still"), extent: ref("extent"), id: "inset", frame: ref("frame"), appearance: ref("still-style"), at: "12f", for: "2s" }),
- node("media:Sequence", { id: "steps", frame: ref("frame"), appearance: ref("sequence-style"), until: ref("terminal"), "until-boundary": "end" }, [
- node("media:Member", { id: "one", image: ref("still"), extent: ref("extent"), at: ref("cue1") }),
- node("media:Member", { id: "two", surface: ref("surface"), appearance: ref("surface-style"), at: ref("cue2") }),
- node("media:Handoff", { id: "one-two", from: "one", transition: ref("handoff") }),
- node("media:Sound", { id: "transition", source: ref("sfx"), handoff: "one-two" }),
- ]),
- ]);
- const result = await decodeMediaTrackSurface({
- sourceName: "media-surface.svml",
- element: root,
- resolveReference: (path) => references.get(path),
- resolveAsset: async () => { throw new Error("no asset resolution expected"); },
- });
- const component = result.components.find((candidate) => candidate.outputs.visual !== undefined);
- assert.ok(component !== undefined);
- assert.deepEqual(Object.keys(component.outputs).sort(), ["audio", "program", "visual"]);
- const fragment = result.fragments.find((candidate) => candidate.exports.some((output) => output.name === "visual"))!;
- const producers = fragment.operations.map((entry) => entry.producer.name);
- assert.ok(producers.includes("append-still-media-layer"));
- assert.ok(producers.includes("append-media-item"));
- assert.ok(producers.includes("append-timed-media-layer"));
- assert.ok(producers.includes("append-surface-media-layer"));
- assert.ok(producers.includes("append-media-paint-layer"));
- assert.ok(producers.includes("bind-media-item-clip-path"));
- assert.ok(producers.includes("append-media-sequence-member"));
- assert.ok(producers.includes("append-media-sequence"));
- assert.ok(result.fragments.some((candidate) => candidate.operations.some((operation) =>
- operation.producer.name === "project-selection-instant")));
- const temporalSubjects = new Set(result.records.flatMap((record) =>
- record.value.kind === "inline"
- && typeof record.value.value === "object"
- && record.value.value !== null
- && "subjectId" in record.value.value
- ? [String((record.value.value as { readonly subjectId: unknown }).subjectId)]
- : []));
- assert.deepEqual([...temporalSubjects].sort(), ["inset", "one", "presenter", "proof", "segment-card", "steps", "still-card", "two"]);
- assert.ok(producers.includes("append-media-sound"));
- assert.ok(fragment.inputs.some((entry) => entry.type.name === artifactTypes.blob.name));
- assert.ok(fragment.inputs.some((entry) => entry.type.name === mediaTypes.synchronized.name));
- assert.ok(fragment.inputs.some((entry) => entry.type.name === spatialTypes.path.name));
- const itemSpecs = result.records.filter((entry) => entry.type.name === "MediaItemSpec");
- assert.equal(itemSpecs.length, 5);
- const selected = itemSpecs[2]!.value.kind === "inline"
- ? itemSpecs[2]!.value.value as unknown as MediaItemSpec
- : undefined;
- assert.equal(selected?.sourceAudio?.fromLayer, "video");
- assert.ok(mediaTrackMarkupSurfaces.some((surface) => surface.name === "track"));
-});
-
-test("Sequence resolves strict logical phases, expanded handoffs and one uninterrupted outer lifecycle", () => {
- const set = appendMediaSequence(
- createMediaTrackSet(), header, space, canvas, sequenceMembers(), frame, sequenceSpec(), sequenceSounds(), 120,
- );
- const program = finalizeMediaTrack(set, header, space);
- const sequence = program.sequences[0]!;
- assert.deepEqual(sequence.members.map((member) => member.logicalSpan), [
- { startFrame: 0, endFrameExclusive: 40 },
- { startFrame: 40, endFrameExclusive: 80 },
- { startFrame: 80, endFrameExclusive: 120 },
- ]);
- assert.deepEqual(sequence.members.map((member) => member.visualSpan), [
- { startFrame: 0, endFrameExclusive: 50 },
- { startFrame: 30, endFrameExclusive: 90 },
- { startFrame: 70, endFrameExclusive: 120 },
- ]);
- assert.deepEqual(sequence.handoffs.map((handoff) => handoff.span), [
- { startFrame: 30, endFrameExclusive: 50 },
- { startFrame: 70, endFrameExclusive: 90 },
- ]);
-
- const presents = projectMediaVisualTrack(space, program).presents;
- assert.equal(presents.length, 3);
- const middleLifecycle = presents[1]!.elements.find((element) => element.id.endsWith(":lifecycle"));
- assert.deepEqual(middleLifecycle?.animation?.keyframes.map((keyframe) => keyframe.style.find((item) => item.name === "opacity")?.value), [1, 1],
- "the middle member observes the neutral slice of the outer lifecycle instead of restarting entry");
- const middleSustain = presents[1]!.elements.find((element) => element.id.includes(":sustain:"));
- assert.equal(middleSustain?.animation?.keyframes.length, 5,
- "the middle member keeps only its exact boundary and group-global phase rows");
- assert.equal(middleSustain?.animation?.keyframes[1]?.atFrame, 15,
- "the middle member resumes the next group-global phase boundary instead of starting a new cycle");
- assert.notEqual(middleSustain?.animation?.keyframes[1]?.style[0]?.value, "none");
- assert.ok(presents[1]!.elements.find((element) => element.id.endsWith(":handoff"))?.animation);
- const sampled = presents[1]!.elements.find((element) => element.id === "video");
- assert.equal(sampled?.kind, "video");
- assert.deepEqual(sampled.kind === "video" ? sampled.sampling?.segments[0]?.target : undefined,
- { startFrame: 0, endFrameExclusive: 60 });
-});
-
-test("Sequence handoffs accept still, timed and alpha Surface members through one lowering path", () => {
- const alphaSurface: CompositableSurfaceRef = {
- artifact: { kind: "blob", resource: fixtureResource("surface:alpha-member"), size: 800, mediaType: "image/png" },
- width: 200, height: 300, colorSpace: "srgb", alphaMode: "straight", timing: { kind: "still" },
- };
- const surfaceLayers = () => appendSurfaceMediaLayer(createMediaLayerSet(), alphaSurface, fit, sealMediaSampleLayerSpec({
- id: "surface", appearance,
- }));
- for (const pair of [
- [stillLayers(), stillLayers()],
- [timedLayers("left"), timedLayers("right")],
- [stillLayers(), timedLayers("moving")],
- [surfaceLayers(), stillLayers()],
- ] as const) {
- let members = createMediaSequenceMemberSet();
- members = appendMediaSequenceMember(members, pair[0], sealMediaSequenceMemberSpec({ id: "a" }), 0);
- members = appendMediaSequenceMember(members, pair[1], sealMediaSequenceMemberSpec({ id: "b" }), 60);
- const spec = sequenceSpec({ motion: { sustain: [] }, handoffs: [sealMediaHandoffSpec({
- id: "a-b", fromMemberId: "a", toMemberId: "b",
- operator: "crossfade", durationFrames: 10, boundaryRatio: 0.5, audio: "cut",
- })] });
- const program = finalizeMediaTrack(appendMediaSequence(createMediaTrackSet(), header, space, canvas,
- members, frame, spec, createMediaSoundSet(), 120), header, space);
- assert.equal(projectMediaVisualTrack(space, program).presents.length, 2);
- }
-});
-
-test("Sequence projects source audio, visual-independent cut/crossfade, edge sounds and boundary sound", () => {
- const program = finalizeMediaTrack(appendMediaSequence(
- createMediaTrackSet(), header, space, canvas, sequenceMembers(), frame, sequenceSpec(), sequenceSounds(), 120,
- ), header, space);
- const track = projectMediaAudioTrack(space, program);
- const sources = track.clips.filter((clip) => clip.id.endsWith(":source-audio"));
- assert.equal(sources.length, 3);
- assert.deepEqual(sources.map((clip) => clip.target), [
- { startSample: 0, endSampleExclusive: 80_000 },
- { startSample: 48_000, endSampleExclusive: 128_000 },
- { startSample: 128_000, endSampleExclusive: 192_000 },
- ]);
- assert.deepEqual(sources.map((clip) => [clip.fadeInSamples, clip.fadeOutSamples]), [
- [0, 32_000], [32_000, 0], [0, 0],
- ]);
- assert.deepEqual(Object.fromEntries(track.clips.filter((clip) => !clip.id.endsWith(":source-audio"))
- .map((clip) => [clip.id, clip.target.startSample])), {
- "steps:enter-sound": 0,
- "steps:handoff-out-sound": 64_000,
- "steps:handoff-in-sound": 64_000,
- "steps:exit-sound": 176_000,
- });
-});
-
-test("every Sequence handoff operator and boundary ratio lowers without changing the authored boundary", () => {
- const operators: readonly MediaHandoffOperator[] = ["cut", "crossfade", "push", "wipe", "cover", "page-turn"];
- for (const operator of operators) {
- for (const boundaryRatio of [0, 0.5, 1]) {
- const durationFrames = operator === "cut" ? 0 : 20;
- const handoff = sealMediaHandoffSpec({
-
- id: `${operator}-${boundaryRatio}`,
- fromMemberId: "member-1",
- toMemberId: "member-2",
- operator,
- durationFrames,
- boundaryRatio,
- ...(["push", "wipe", "cover", "page-turn"].includes(operator) ? { direction: "right" as const } : {}),
- audio: "cut",
- });
- const spec = sequenceSpec({
- handoffs: [handoff],
- motion: { sustain: [] },
- });
- const program = finalizeMediaTrack(appendMediaSequence(
- createMediaTrackSet(), header, space, canvas, sequenceMembers([0, 60]), frame, spec, createMediaSoundSet(), 120,
- ), header, space);
- const resolved = program.sequences[0]!.handoffs[0]!;
- assert.equal(resolved.span.endFrameExclusive - resolved.span.startFrame, durationFrames);
- assert.equal(program.sequences[0]!.members[1]!.activationFrame, 60);
- assert.equal(projectMediaVisualTrack(space, program).presents.length, 2);
- }
- }
-
- for (const durationFrames of [20, 60, 80]) {
- const spec = sequenceSpec({
- motion: { sustain: [] },
- handoffs: [sealMediaHandoffSpec({
-
- id: `duration-${durationFrames}`,
- fromMemberId: "member-1",
- toMemberId: "member-2",
- operator: "crossfade",
- durationFrames,
- boundaryRatio: 0.5,
- audio: "crossfade",
- })],
- });
- const sequence = finalizeMediaTrack(appendMediaSequence(
- createMediaTrackSet(), header, space, canvas, sequenceMembers([0, 60]), frame,
- spec, createMediaSoundSet(), 120,
- ), header, space).sequences[0]!;
- assert.equal(sequence.handoffs[0]!.span.endFrameExclusive
- - sequence.handoffs[0]!.span.startFrame, durationFrames);
- }
-});
-
-test("Sequence fails atomically on malformed order, topology, envelope and three-member overlap", () => {
- assert.throws(() => appendMediaSequence(
- createMediaTrackSet(), header, space, canvas, sequenceMembers(), frame,
- sequenceSpec({ handoffs: sequenceSpec().handoffs.slice(0, 1) }), createMediaSoundSet(), 120,
- ), /exactly one Handoff/u);
- assert.throws(() => appendMediaSequence(
- createMediaTrackSet(), header, space, canvas, sequenceMembers([0, 40, 40]), frame, sequenceSpec(), createMediaSoundSet(), 120,
- ), /strictly increasing/u);
- assert.throws(() => appendMediaSequence(
- createMediaTrackSet(), header, space, canvas, sequenceMembers([0, 80, 40]), frame, sequenceSpec(), createMediaSoundSet(), 120,
- ), /authored order/u);
- assert.throws(() => appendMediaSequence(
- createMediaTrackSet(), header, space, canvas, sequenceMembers([0, 40, 70]), frame,
- sequenceSpec({ handoffs: [
- sealMediaHandoffSpec({ id: "wide-one", fromMemberId: "member-1", toMemberId: "member-2", operator: "crossfade", durationFrames: 40, boundaryRatio: 0.5, audio: "cut" }),
- sealMediaHandoffSpec({ id: "wide-two", fromMemberId: "member-2", toMemberId: "member-3", operator: "crossfade", durationFrames: 40, boundaryRatio: 0.5, audio: "cut" }),
- ] }), createMediaSoundSet(), 120,
- ), /overlapping Handoffs/u);
- assert.throws(() => appendMediaSequence(
- createMediaTrackSet(), header, space, canvas, sequenceMembers([0, 20]), frame,
- sequenceSpec({ handoffs: [
- sealMediaHandoffSpec({ id: "outside", fromMemberId: "member-1", toMemberId: "member-2", operator: "wipe", durationFrames: 60, boundaryRatio: 1, direction: "left", audio: "cut" }),
- ] }), createMediaSoundSet(), 120,
- ), /envelope/u);
-});
-
-
-test("Performance keeps source positions and continuous picture motion across Takes", () => {
- const performance = { ...semantic, items: semantic.items.map(item => ({ startFrame: item.startFrame, take: { ...item.take,
- media: { ...item.take.media, visual: { artifact: { ...source, mediaType: "video/mp4" }, width: 720, height: 1280 } },
- } })) };
- const window = projectProgramWindow({ itemId: "performance", semantic: performance,
- projection: { start: { ref: "absolute", at: { unit: "frames", value: 20 } },
- end: { ref: "absolute", at: { unit: "frames", value: 100 } } } });
- const set = appendMediaPerformance({ set: createMediaTrackSet(), header, timeline: performance, canvas, frame,
- layers: createMediaLayerSet(), spec: itemSpec({ id: "performance" }), sounds: createMediaSoundSet(), window },
- fit, sealMediaSampleLayerSpec({ id: "content", appearance, occupancy: { mode: "once", align: "start" },
- samplingMotion: { keyframes: [
- { atProgress: 0, zoom: 1, offsetX: 0, offsetY: 0, rotationDeg: 0 },
- { atProgress: 1, zoom: 1.08, offsetX: 0, offsetY: -18, rotationDeg: 0 },
- ] } }));
- const visual = projectMediaVisualTrack(space, finalizeMediaTrack(set, header, space));
- assert.equal(visual.presents.length, 1);
- assert.deepEqual(visual.presents[0]!.span, { startFrame: 20, endFrameExclusive: 100 });
- const videos = visual.presents[0]!.elements.filter(element => element.kind === "video");
- assert.deepEqual(videos.map(video => video.kind === "video" ? video.sampling?.segments : undefined), [
- [{ target: { startFrame: 0, endFrameExclusive: 10 }, sourceFrame: { numerator: 20, denominator: 1 }, rate: { numerator: 1, denominator: 1 } }],
- [{ target: { startFrame: 10, endFrameExclusive: 70 }, sourceFrame: { numerator: 0, denominator: 1 }, rate: { numerator: 1, denominator: 1 } }],
- [{ target: { startFrame: 70, endFrameExclusive: 80 }, sourceFrame: { numerator: 0, denominator: 1 }, rate: { numerator: 1, denominator: 1 } }],
- ]);
- const contentTransforms = visual.presents[0]!.elements.filter(element => element.id.endsWith(":sampling"));
- assert.equal(contentTransforms.length, 3);
- for (const element of contentTransforms) {
- assert.deepEqual(element.animation?.keyframes.map(key => [key.atFrame, key.style]), [
- [0, [{ name: "transform", value: "translate(0px,0px) rotate(0deg) scale(1)" }]],
- [80, [{ name: "transform", value: "translate(0px,-18px) rotate(0deg) scale(1.08)" }]],
- ]);
- }
-});
diff --git a/packages/media/README.md b/packages/media/README.md
index 0bc48c1e..2a764e47 100644
--- a/packages/media/README.md
+++ b/packages/media/README.md
@@ -18,6 +18,18 @@ normalization. It contains one common `frameRate`/`frameCount`, an optional visu
intrinsic pixel extent, and an optional audio Artifact. Source stream indexes, selection authority,
normalization ledgers and repeated codec/rate constants are not downstream media fields.
+## Normalized media stays neutral
+
+Normalization also publishes a complete `LocalTemporalDomain` and `TemporalExtent`. A Timeline may
+use the Extent to determine its end, and a semantic projector may use the Domain with an equal-length
+Window to publish absolute anchors. Neither operation changes the media's identity or wraps it in an
+A-roll-specific value.
+
+Visual and Audio Clips each accept the same ordinary `SynchronizedMedia` with an explicit
+absolute Window. They independently select the stream they need. A media value is therefore equally
+usable as foreground performance, B-roll, music, an effect or a model input; its earlier contribution
+to Timeline construction is not observable downstream.
+
## Font files
`Font` takes an explicit source path and the selected face's real weight and style:
diff --git a/packages/media/package.json b/packages/media/package.json
index 6543dbf4..e212f3de 100644
--- a/packages/media/package.json
+++ b/packages/media/package.json
@@ -13,7 +13,9 @@
"dependencies": {
"@hypit/artifact": "workspace:*",
"@hypit/component-kit": "workspace:*",
+ "@hypit/elaborator": "workspace:*",
"@hypit/protocol": "workspace:*",
+ "@hypit/temporal": "workspace:*",
"@hypit/markup": "workspace:*"
}
}
diff --git a/packages/media/src/component.ts b/packages/media/src/component.ts
index 38bf6694..5f9f0eab 100644
--- a/packages/media/src/component.ts
+++ b/packages/media/src/component.ts
@@ -1,5 +1,9 @@
import type { ComponentPackage } from "@hypit/component-kit";
import { verifyMediaInspection, verifyMediaStreamSelection, verifyMuxedMedia, verifyRenderedVisual, verifySynchronizedMedia, verifyTimelineAudio } from "./identity.js";
+import { mediaLocalTemporalDomain } from "./domain.js";
+import type { MediaDomainSpec, SynchronizedMedia } from "./types.js";
+import { canonicalize } from "@hypit/protocol";
+import { mediaProducers } from "./manifest.js";
import { mediaTypes } from "./manifest.js";
import { verifyMediaFrameRange } from "./frame-range.js";
function inline(value: { readonly kind: string; readonly value?: unknown }, subject: string): unknown { if (value.kind !== "inline") throw new Error(`${subject} must be inline`); return value.value; }
@@ -13,4 +17,11 @@ export const mediaComponent = {
{ type: mediaTypes.timelineAudio, handler: ({ value }) => verifyTimelineAudio(inline(value, "TimelineAudio")) },
{ type: mediaTypes.muxed, handler: ({ value }) => verifyMuxedMedia(inline(value, "MuxedMedia")) },
],
+ producers: [
+ { producer: mediaProducers.localDomain, handler: ({ inputs }) => {
+ const media = inline(inputs.media!.value, "SynchronizedMedia") as SynchronizedMedia;
+ const spec = inline(inputs.spec!.value, "MediaDomainSpec") as MediaDomainSpec;
+ return { outputs: { domain: { kind: "inline", value: canonicalize(mediaLocalTemporalDomain(spec.id, media)) } }, needs: {} };
+ } },
+ ],
} satisfies ComponentPackage;
diff --git a/packages/media/src/domain.ts b/packages/media/src/domain.ts
new file mode 100644
index 00000000..ecfee8fd
--- /dev/null
+++ b/packages/media/src/domain.ts
@@ -0,0 +1,11 @@
+import { sealLocalTemporalDomain } from "@hypit/temporal";
+import type { LocalTemporalDomain } from "@hypit/temporal";
+
+import { verifySynchronizedMedia } from "./identity.js";
+import type { SynchronizedMedia } from "./types.js";
+
+/** Give normalized media one author-visible local coordinate identity. */
+export function mediaLocalTemporalDomain(id: string, media: SynchronizedMedia): LocalTemporalDomain {
+ verifySynchronizedMedia(media);
+ return sealLocalTemporalDomain({ id, ...structuredClone(media.frameDomain) });
+}
diff --git a/packages/media/src/identity.ts b/packages/media/src/identity.ts
index dca1f04c..7e7c3a28 100644
--- a/packages/media/src/identity.ts
+++ b/packages/media/src/identity.ts
@@ -159,8 +159,8 @@ export function sealSynchronizedMedia(value: SynchronizedMedia): SynchronizedMed
/** Exact 48 kHz sample span implied by one normalized frame domain. */
export function synchronizedMediaSampleFrames(value: SynchronizedMedia): number {
- const numerator = BigInt(value.timeline.frameCount) * 48_000n * BigInt(value.timeline.frameRate.denominator);
- const denominator = BigInt(value.timeline.frameRate.numerator);
+ const numerator = BigInt(value.frameDomain.frameCount) * 48_000n * BigInt(value.frameDomain.frameRate.denominator);
+ const denominator = BigInt(value.frameDomain.frameRate.numerator);
const rounded = (numerator * 2n + denominator) / (denominator * 2n);
assert(rounded > 0n && rounded <= BigInt(Number.MAX_SAFE_INTEGER),
"SynchronizedMedia frame domain has an invalid sample span");
@@ -169,8 +169,8 @@ export function synchronizedMediaSampleFrames(value: SynchronizedMedia): number
export function verifySynchronizedMedia(value: unknown): asserts value is SynchronizedMedia {
const item = object(value, "SynchronizedMedia") as unknown as SynchronizedMedia;
- verifyRational(item.timeline.frameRate, "SynchronizedMedia.timeline.frameRate");
- positiveInteger(item.timeline.frameCount, "SynchronizedMedia.timeline.frameCount");
+ verifyRational(item.frameDomain.frameRate, "SynchronizedMedia.frameDomain.frameRate");
+ positiveInteger(item.frameDomain.frameCount, "SynchronizedMedia.frameDomain.frameCount");
synchronizedMediaSampleFrames(item);
assert(item.visual !== undefined || item.audio !== undefined, "SynchronizedMedia contains no media projection");
if (item.visual !== undefined) {
diff --git a/packages/media/src/index.ts b/packages/media/src/index.ts
index 80c120a3..01a8ca14 100644
--- a/packages/media/src/index.ts
+++ b/packages/media/src/index.ts
@@ -6,7 +6,8 @@ export {
} from "./surface.js";
export { mediaComponent } from "./component.js";
export { sealMediaInspection, sealMediaStreamSelection, sealMuxedMedia, sealRenderedVisual, sealSynchronizedMedia, sealTimelineAudio, synchronizedMediaSampleFrames, verifyMediaInspection, verifyMediaStreamSelection, verifyMuxedMedia, verifyRenderedVisual, verifySynchronizedMedia, verifyTimelineAudio } from "./identity.js";
-export { mediaDependency, mediaManifest, mediaMarkupSurfaces, mediaModuleRef, mediaTypes } from "./manifest.js";
+export { mediaLocalTemporalDomain } from "./domain.js";
+export { mediaDependency, mediaManifest, mediaMarkupSurfaces, mediaModuleRef, mediaProducers, mediaTypes } from "./manifest.js";
export { compositableSurfaceSchema, fontArtifactSchema, fontStackSchema, mediaInspectionSchema, mediaStreamSelectionSchema, muxedMediaSchema, renderedVisualSchema, synchronizedMediaSchema, timelineAudioSchema } from "./schema.js";
export { assertCompositableSurfaceRef, assertFontArtifactRef, assertFontStackRef } from "./render.js";
export type * from "./render.js";
diff --git a/packages/media/src/manifest.ts b/packages/media/src/manifest.ts
index 98f9aad6..3243d54a 100644
--- a/packages/media/src/manifest.ts
+++ b/packages/media/src/manifest.ts
@@ -1,11 +1,13 @@
import { artifactDependency, artifactTypes } from "@hypit/artifact";
-import type { ModuleManifest, TypeRef } from "@hypit/protocol";
+import type { ModuleManifest, ProducerRef, TypeRef } from "@hypit/protocol";
import { compositableSurfaceSchema, fontArtifactSchema, fontStackSchema, mediaInspectionSchema, mediaStreamSelectionSchema, muxedMediaSchema, renderedVisualSchema, synchronizedMediaSchema, timelineAudioSchema } from "./schema.js";
+import { temporalDependency, temporalTypes } from "@hypit/temporal";
export const mediaModuleRef = { name: "@hypit/media", version: "1" } as const;
export const mediaTypes = {
frameRange: { module: mediaModuleRef, name: "MediaFrameRange" },
inspection: { module: mediaModuleRef, name: "MediaInspection" },
streamSelection: { module: mediaModuleRef, name: "MediaStreamSelection" }, synchronized: { module: mediaModuleRef, name: "SynchronizedMedia" },
+ domainSpec: { module: mediaModuleRef, name: "MediaDomainSpec" },
renderedVisual: { module: mediaModuleRef, name: "RenderedVisual" }, timelineAudio: { module: mediaModuleRef, name: "TimelineAudio" },
muxed: { module: mediaModuleRef, name: "MuxedMedia" }, fontArtifact: { module: mediaModuleRef, name: "FontArtifactRef" },
fontStack: { module: mediaModuleRef, name: "FontStackRef" },
@@ -13,6 +15,9 @@ export const mediaTypes = {
/** Declared by `@hypit/artifact`. A Type is identified by the Module that owns it, not the one that re-exports it. */
blobArtifact: artifactTypes.blob,
} satisfies Record<string, TypeRef>;
+export const mediaProducers = {
+ localDomain: { module: mediaModuleRef, name: "local-domain" },
+} satisfies Record<string, ProducerRef>;
export const mediaMarkupSurfaces = [
{
@@ -106,17 +111,22 @@ export const mediaMarkupSurfaces = [
] as const;
export const mediaManifest: ModuleManifest = {
- format: "hypit.module@1", name: mediaModuleRef.name, version: mediaModuleRef.version, dependencies: [artifactDependency],
+ format: "hypit.module@1", name: mediaModuleRef.name, version: mediaModuleRef.version, dependencies: [artifactDependency, temporalDependency],
types: [
{ name: mediaTypes.frameRange.name },
{ name: mediaTypes.inspection.name },
{ name: mediaTypes.streamSelection.name },
{ name: mediaTypes.synchronized.name },
+ { name: mediaTypes.domainSpec.name },
{ name: mediaTypes.renderedVisual.name },
{ name: mediaTypes.timelineAudio.name },
{ name: mediaTypes.muxed.name },
{ name: mediaTypes.fontArtifact.name }, { name: mediaTypes.fontStack.name },
{ name: mediaTypes.compositableSurface.name },
- ], capabilities: [], producers: [],
+ ], capabilities: [], producers: [
+ { name: mediaProducers.localDomain.name,
+ inputs: [{ name: "media", type: mediaTypes.synchronized }, { name: "spec", type: mediaTypes.domainSpec }],
+ outputs: [{ name: "domain", type: temporalTypes.localDomain }], needs: [] },
+ ],
};
export const mediaDependency = { module: mediaModuleRef } as const;
diff --git a/packages/media/src/schema.ts b/packages/media/src/schema.ts
index 1c46c1ec..192f0a3d 100644
--- a/packages/media/src/schema.ts
+++ b/packages/media/src/schema.ts
@@ -38,13 +38,14 @@ export const mediaStreamSelectionSchema: ValueSchema = object({
policy: { schema: { kind: "string", enum: ["primary-moving@1", "default-audio@1", "primary-moving-default-audio@1", "explicit-streams@1"] } },
});
export const synchronizedMediaSchema: ValueSchema = object({
- timeline: { schema: object({ frameRate: { schema: rational },
+ frameDomain: { schema: object({ frameRate: { schema: rational },
frameCount: { schema: { kind: "number", integer: true, minimum: 1 } } }) },
visual: { schema: object({ artifact: { schema: blobArtifactSchema() },
width: { schema: { kind: "number", integer: true, minimum: 1 } }, height: { schema: { kind: "number", integer: true, minimum: 1 } },
}), optional: true },
audio: { schema: object({ artifact: { schema: blobArtifactSchema(["audio/wav"]) } }), optional: true },
});
+
export const renderedVisualSchema: ValueSchema = object({ frameRate: { schema: rational }, frameCount: { schema: { kind: "number", integer: true, minimum: 1 } },
canvas: { schema: object({ width: { schema: { kind: "number", integer: true, minimum: 1 } }, height: { schema: { kind: "number", integer: true, minimum: 1 } } }) },
artifact: { schema: blobArtifactSchema() } });
diff --git a/packages/media/src/surface.ts b/packages/media/src/surface.ts
index 25651998..8a40b243 100644
--- a/packages/media/src/surface.ts
+++ b/packages/media/src/surface.ts
@@ -1,9 +1,5 @@
import { artifactTypes } from "@hypit/artifact";
-import type {
- StructuredElement,
- StructuredSurfaceHandler,
-} from "@hypit/markup";
-
+import type { StructuredElement, StructuredSurfaceHandler } from "@hypit/markup";
import { assertFontArtifactRef } from "./render.js";
import { mediaTypes } from "./manifest.js";
diff --git a/packages/media/src/types.ts b/packages/media/src/types.ts
index d6fecb64..7f33e151 100644
--- a/packages/media/src/types.ts
+++ b/packages/media/src/types.ts
@@ -77,7 +77,8 @@ export type MediaStreamSelection = {
};
export type SynchronizedMedia = {
- readonly timeline: {
+ /** The normalized source-local clock and extent; this is not a film Timeline. */
+ readonly frameDomain: {
readonly frameRate: MediaRational;
readonly frameCount: number;
};
@@ -91,6 +92,9 @@ export type SynchronizedMedia = {
};
};
+/** Identity for deriving an author-visible local temporal domain from normalized media. */
+export type MediaDomainSpec = { readonly id: string };
+
/** Silent, frame-exact visual output from a renderer such as HyperFrames. */
export type RenderedVisual = {
readonly frameRate: MediaRational;
diff --git a/packages/media/test/domain.test.ts b/packages/media/test/domain.test.ts
new file mode 100644
index 00000000..da3c4fc2
--- /dev/null
+++ b/packages/media/test/domain.test.ts
@@ -0,0 +1,22 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { mediaLocalTemporalDomain } from "../src/index.js";
+import type { SynchronizedMedia } from "../src/index.js";
+import { fixtureResource } from "../../../test/fixture-resource.js";
+
+const media: SynchronizedMedia = {
+ frameDomain: { frameRate: { numerator: 30, denominator: 1 }, frameCount: 60 },
+ visual: {
+ artifact: { kind: "blob", resource: fixtureResource("domain:visual"), size: 1, mediaType: "video/mp4" },
+ width: 1920, height: 1080,
+ },
+ audio: { artifact: { kind: "blob", resource: fixtureResource("domain:audio"), size: 1, mediaType: "audio/wav" } },
+};
+
+test("normalized media publishes a factual local temporal domain without program position", () => {
+ const domain = mediaLocalTemporalDomain("opening-local", media);
+ assert.deepEqual(domain, { id: "opening-local", ...media.frameDomain });
+ assert.equal("timelineId" in domain, false);
+ assert.equal("media" in domain, false);
+});
diff --git a/packages/narrative-alignment-adjust/package.json b/packages/narrative-alignment-adjust/package.json
new file mode 100644
index 00000000..fe33975b
--- /dev/null
+++ b/packages/narrative-alignment-adjust/package.json
@@ -0,0 +1,22 @@
+{
+ "name": "@hypit/narrative-alignment-adjust",
+ "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/component-kit": "workspace:*",
+ "@hypit/elaborator": "workspace:*",
+ "@hypit/markup": "workspace:*",
+ "@hypit/narrative": "workspace:*",
+ "@hypit/protocol": "workspace:*",
+ "@hypit/narrative-temporal": "workspace:*",
+ "@hypit/temporal": "workspace:*"
+ }
+}
diff --git a/packages/narrative-alignment-adjust/src/activation.ts b/packages/narrative-alignment-adjust/src/activation.ts
new file mode 100644
index 00000000..83267b9d
--- /dev/null
+++ b/packages/narrative-alignment-adjust/src/activation.ts
@@ -0,0 +1,22 @@
+import { createMarkupSurfaceHostFacet } from "@hypit/markup";
+
+import {
+ decodeNarrativeAlignmentAdjustSurface,
+ narrativeAlignmentAdjustComponent,
+ narrativeAlignmentAdjustManifest,
+ narrativeAlignmentAdjustMarkupSurfaces,
+ narrativeAlignmentAdjustModuleRef,
+} from "./index.js";
+
+export const hypitPackage = {
+ format: "hypit.node-package@1" as const,
+ modules: [{ manifest: narrativeAlignmentAdjustManifest }],
+ components: [narrativeAlignmentAdjustComponent],
+ hostFacets: [createMarkupSurfaceHostFacet({
+ module: narrativeAlignmentAdjustModuleRef,
+ declaration: narrativeAlignmentAdjustMarkupSurfaces.find((item) => item.name === "narrative-alignment")!,
+ handler: decodeNarrativeAlignmentAdjustSurface,
+ })],
+};
+
+export default hypitPackage;
diff --git a/packages/narrative-alignment-adjust/src/component.ts b/packages/narrative-alignment-adjust/src/component.ts
new file mode 100644
index 00000000..51a03315
--- /dev/null
+++ b/packages/narrative-alignment-adjust/src/component.ts
@@ -0,0 +1,33 @@
+import type { ComponentPackage } from "@hypit/component-kit";
+import { canonicalize } from "@hypit/protocol";
+import type { StoredValue } from "@hypit/protocol";
+import type { NarrativeAlignment } from "@hypit/narrative-temporal";
+import type { LocalTemporalDomain } from "@hypit/temporal";
+
+import { narrativeAlignmentAdjustProducers } from "./manifest.js";
+import { adjustNarrativeAlignment } from "./program.js";
+import type { NarrativeAlignmentAdjustmentPlan } from "./types.js";
+
+function inline<T>(value: StoredValue | undefined, subject: string): T {
+ if (value?.kind !== "inline") throw new Error(`${subject} must be inline.`);
+ return value.value as unknown as T;
+}
+
+export const narrativeAlignmentAdjustComponent = {
+ producers: [{
+ producer: narrativeAlignmentAdjustProducers.adjust,
+ handler: ({ inputs }) => ({
+ outputs: {
+ alignment: {
+ kind: "inline",
+ value: canonicalize(adjustNarrativeAlignment(
+ inline<NarrativeAlignment>(inputs.source?.value, "NarrativeAlignment"),
+ inline<LocalTemporalDomain>(inputs.domain?.value, "LocalTemporalDomain"),
+ inline<NarrativeAlignmentAdjustmentPlan>(inputs.plan?.value, "NarrativeAlignment adjustment plan"),
+ )),
+ },
+ },
+ needs: {},
+ }),
+ }],
+} satisfies ComponentPackage;
diff --git a/packages/narrative-alignment-adjust/src/fragment.ts b/packages/narrative-alignment-adjust/src/fragment.ts
new file mode 100644
index 00000000..c5ca3dbf
--- /dev/null
+++ b/packages/narrative-alignment-adjust/src/fragment.ts
@@ -0,0 +1,26 @@
+import { sealGraphFragment } from "@hypit/elaborator";
+import { narrativeTemporalTypes } from "@hypit/narrative-temporal";
+import { temporalTypes } from "@hypit/temporal";
+
+import { narrativeAlignmentAdjustProducers, narrativeAlignmentAdjustTypes } from "./manifest.js";
+
+const input = (name: string) => ({ kind: "fragment-input" as const, name });
+
+export const narrativeAlignmentAdjustFragment = sealGraphFragment({
+ inputs: [
+ { name: "source", type: narrativeTemporalTypes.narrativeAlignment },
+ { name: "domain", type: temporalTypes.localDomain },
+ { name: "plan", type: narrativeAlignmentAdjustTypes.plan },
+ ],
+ operations: [{
+ id: "adjust",
+ producer: narrativeAlignmentAdjustProducers.adjust,
+ inputs: { source: input("source"), domain: input("domain"), plan: input("plan") },
+ result: { kind: "output", name: "alignment" },
+ }],
+ exports: [{
+ name: "alignment",
+ type: narrativeTemporalTypes.narrativeAlignment,
+ root: { kind: "fragment-operation", operation: "adjust" },
+ }],
+});
diff --git a/packages/narrative-alignment-adjust/src/index.ts b/packages/narrative-alignment-adjust/src/index.ts
new file mode 100644
index 00000000..ca93e1de
--- /dev/null
+++ b/packages/narrative-alignment-adjust/src/index.ts
@@ -0,0 +1,12 @@
+export { narrativeAlignmentAdjustComponent } from "./component.js";
+export { narrativeAlignmentAdjustFragment } from "./fragment.js";
+export {
+ narrativeAlignmentAdjustManifest,
+ narrativeAlignmentAdjustMarkupSurfaces,
+ narrativeAlignmentAdjustModuleRef,
+ narrativeAlignmentAdjustProducers,
+ narrativeAlignmentAdjustTypes,
+} from "./manifest.js";
+export { adjustNarrativeAlignment } from "./program.js";
+export { decodeNarrativeAlignmentAdjustSurface } from "./surface.js";
+export type { NarrativeAlignmentAdjustmentPlan, NarrativeBoundaryAdjustment } from "./types.js";
diff --git a/packages/narrative-alignment-adjust/src/manifest.ts b/packages/narrative-alignment-adjust/src/manifest.ts
new file mode 100644
index 00000000..6c731da5
--- /dev/null
+++ b/packages/narrative-alignment-adjust/src/manifest.ts
@@ -0,0 +1,61 @@
+import { narrativeDependency } from "@hypit/narrative";
+import type { ModuleManifest, ProducerRef, TypeRef } from "@hypit/protocol";
+import { narrativeTemporalDependency, narrativeTemporalTypes } from "@hypit/narrative-temporal";
+import { temporalDependency, temporalTypes } from "@hypit/temporal";
+
+export const narrativeAlignmentAdjustModuleRef = { name: "@hypit/narrative-alignment-adjust", version: "1" } as const;
+
+export const narrativeAlignmentAdjustTypes = {
+ plan: { module: narrativeAlignmentAdjustModuleRef, name: "NarrativeAlignmentAdjustmentPlan" },
+} satisfies Record<string, TypeRef>;
+
+export const narrativeAlignmentAdjustProducers = {
+ adjust: { module: narrativeAlignmentAdjustModuleRef, name: "adjust-narrative-alignment" },
+} satisfies Record<string, ProducerRef>;
+
+export const narrativeAlignmentAdjustMarkupSurfaces = [{
+ name: "narrative-alignment",
+ tag: "NarrativeAlignment",
+ mode: "structured",
+ outputs: [narrativeAlignmentAdjustTypes.plan, narrativeTemporalTypes.narrativeAlignment],
+ vocabulary: {
+ summary: "Applies explicit author corrections to measured NarrativeAlignment boundary frames.",
+ attributes: [
+ { name: "id", kind: "identifier", required: true,
+ summary: "Names the corrected alignment." },
+ { name: "source", kind: "reference", required: true, accepts: [narrativeTemporalTypes.narrativeAlignment],
+ summary: "Selects the measured NarrativeAlignment being corrected." },
+ { name: "domain", kind: "reference", required: true, accepts: [temporalTypes.localDomain],
+ summary: "Selects the source-local domain that bounds the corrected frames." },
+ ],
+ ports: [{ name: "alignment", type: narrativeTemporalTypes.narrativeAlignment,
+ summary: "The corrected NarrativeAlignment, addressed as `<id>.alignment`." }],
+ example: `<adjust:NarrativeAlignment id="opening-corrected" source={opening.alignment} domain={opening.domain}>
+ <adjust:Boundary at={story.moment.answer} frame="63"/>
+</adjust:NarrativeAlignment>`,
+ notes: [
+ "Each Boundary names an author-declared Script Moment and gives its exact source-local frame.",
+ "This is an explicit correction layer over measured evidence; it does not guess timing or modify media.",
+ "Segment and Token records refer to canonical boundaries, so no duplicate coordinates need synchronizing.",
+ ],
+ },
+}] as const;
+
+export const narrativeAlignmentAdjustManifest: ModuleManifest = {
+ format: "hypit.module@1",
+ name: narrativeAlignmentAdjustModuleRef.name,
+ version: narrativeAlignmentAdjustModuleRef.version,
+ dependencies: [narrativeDependency, narrativeTemporalDependency, temporalDependency],
+ types: [{ name: narrativeAlignmentAdjustTypes.plan.name }],
+ capabilities: [],
+ producers: [{
+ name: narrativeAlignmentAdjustProducers.adjust.name,
+ inputs: [
+ { name: "source", type: narrativeTemporalTypes.narrativeAlignment },
+ { name: "domain", type: temporalTypes.localDomain },
+ { name: "plan", type: narrativeAlignmentAdjustTypes.plan },
+ ],
+ outputs: [{ name: "alignment", type: narrativeTemporalTypes.narrativeAlignment }],
+ needs: [],
+ }],
+};
diff --git a/packages/narrative-alignment-adjust/src/program.ts b/packages/narrative-alignment-adjust/src/program.ts
new file mode 100644
index 00000000..3a4dc9ef
--- /dev/null
+++ b/packages/narrative-alignment-adjust/src/program.ts
@@ -0,0 +1,42 @@
+import { assertNarrativeAlignmentIdentity, sealNarrativeAlignment } from "@hypit/narrative-temporal";
+import type { NarrativeAlignment } from "@hypit/narrative-temporal";
+import { assertLocalTemporalDomain } from "@hypit/temporal";
+import type { LocalTemporalDomain } from "@hypit/temporal";
+
+import type { NarrativeAlignmentAdjustmentPlan } from "./types.js";
+
+export function adjustNarrativeAlignment(
+ source: NarrativeAlignment,
+ domain: LocalTemporalDomain,
+ plan: NarrativeAlignmentAdjustmentPlan,
+): NarrativeAlignment {
+ assertLocalTemporalDomain(domain);
+ assertNarrativeAlignmentIdentity(source, domain);
+ if (plan.narrativeId !== source.narrativeId) {
+ throw new Error(`NarrativeAlignment adjustment belongs to Narrative ${plan.narrativeId}, not ${source.narrativeId}.`);
+ }
+ if (plan.boundaries.length === 0) throw new Error("NarrativeAlignment adjustment requires at least one boundary.");
+
+ const sourceBoundaryIds = new Set(source.boundaries.map((boundary) => boundary.id));
+ const adjusted = new Map<string, number>();
+ for (const boundary of plan.boundaries) {
+ if (!sourceBoundaryIds.has(boundary.boundaryId)) {
+ throw new Error(`NarrativeAlignment does not contain boundary ${boundary.boundaryId}.`);
+ }
+ if (adjusted.has(boundary.boundaryId)) {
+ throw new Error(`NarrativeAlignment boundary ${boundary.boundaryId} is adjusted more than once.`);
+ }
+ if (!Number.isSafeInteger(boundary.frame) || boundary.frame < 0 || boundary.frame > domain.frameCount) {
+ throw new Error(`NarrativeAlignment boundary ${boundary.boundaryId} has an invalid adjusted frame.`);
+ }
+ adjusted.set(boundary.boundaryId, boundary.frame);
+ }
+
+ return sealNarrativeAlignment({
+ ...source,
+ boundaries: source.boundaries.map((boundary) => ({
+ ...boundary,
+ frame: adjusted.get(boundary.id) ?? boundary.frame,
+ })),
+ }, domain);
+}
diff --git a/packages/semantic-take-adjust/src/surface.ts b/packages/narrative-alignment-adjust/src/surface.ts
similarity index 64%
rename from packages/semantic-take-adjust/src/surface.ts
rename to packages/narrative-alignment-adjust/src/surface.ts
index b2cbfa68..f08f7e18 100644
--- a/packages/semantic-take-adjust/src/surface.ts
+++ b/packages/narrative-alignment-adjust/src/surface.ts
@@ -12,11 +12,12 @@ import type {
import { narrativeTypes } from "@hypit/narrative";
import type { NarrativeMomentRef } from "@hypit/narrative";
import { canonicalize, sameType } from "@hypit/protocol";
-import { speechTypes } from "@hypit/speech";
+import { narrativeTemporalTypes } from "@hypit/narrative-temporal";
+import { temporalTypes } from "@hypit/temporal";
-import { semanticTakeAdjustFragment } from "./fragment.js";
-import { semanticTakeAdjustTypes } from "./manifest.js";
-import type { SemanticTakeAdjustmentPlan } from "./types.js";
+import { narrativeAlignmentAdjustFragment } from "./fragment.js";
+import { narrativeAlignmentAdjustTypes } from "./manifest.js";
+import type { NarrativeAlignmentAdjustmentPlan } from "./types.js";
function reference(
element: StructuredElement,
@@ -45,19 +46,20 @@ function frameAttribute(element: StructuredElement): number {
return value;
}
-export const decodeSemanticTakeAdjustSurface: StructuredSurfaceHandler = ({ element, resolveReference }) => {
- assertExactAttributes(element, ["id", "source"]);
+export const decodeNarrativeAlignmentAdjustSurface: StructuredSurfaceHandler = ({ element, resolveReference }) => {
+ assertExactAttributes(element, ["id", "source", "domain"]);
const id = textAttribute(element, "id");
- const source = reference(element, "source", speechTypes.semanticTake, resolveReference);
+ const source = reference(element, "source", narrativeTemporalTypes.narrativeAlignment, resolveReference);
+ const domain = reference(element, "domain", temporalTypes.localDomain, resolveReference);
const moments: NarrativeMomentRef[] = [];
- const anchors: SemanticTakeAdjustmentPlan["anchors"][number][] = [];
+ const boundaries: NarrativeAlignmentAdjustmentPlan["boundaries"][number][] = [];
for (const child of element.children) {
if (child.kind === "text") {
- if (child.value.trim()) throw new Error(`${element.name} accepts only Anchor children.`);
+ if (child.value.trim()) throw new Error(`${element.name} accepts only Boundary children.`);
continue;
}
- if (localName(child.name) !== "Anchor") throw new Error(`${element.name} accepts only Anchor children.`);
+ if (localName(child.name) !== "Boundary") throw new Error(`${element.name} accepts only Boundary children.`);
assertExactAttributes(child, ["at", "frame"]);
if (child.children.some((item) => item.kind === "element" || item.value.trim())) {
throw new Error(`${child.name} must be empty.`);
@@ -67,30 +69,30 @@ export const decodeSemanticTakeAdjustSurface: StructuredSurfaceHandler = ({ elem
`${child.name}.at`,
);
moments.push(moment);
- anchors.push({ anchorId: moment.anchorId, frame: frameAttribute(child) });
+ boundaries.push({ boundaryId: moment.anchorId, frame: frameAttribute(child) });
}
- if (anchors.length === 0) throw new Error(`${element.name} requires at least one Anchor child.`);
+ if (boundaries.length === 0) throw new Error(`${element.name} requires at least one Boundary child.`);
const narrativeId = moments[0]!.narrativeId;
if (moments.some((moment) => moment.narrativeId !== narrativeId)) {
throw new Error(`${element.name} cannot mix Moments from different Narratives.`);
}
const planId = `${id}.plan`;
- const plan: SemanticTakeAdjustmentPlan = { narrativeId, anchors };
+ const plan: NarrativeAlignmentAdjustmentPlan = { narrativeId, boundaries };
return {
records: [{
id: planId,
- type: semanticTakeAdjustTypes.plan,
+ type: narrativeAlignmentAdjustTypes.plan,
value: { kind: "inline", value: canonicalize(plan) },
range: element.range,
}],
components: [{
id,
- fragment: semanticTakeAdjustFragment.id,
- inputs: { source: source.ref, plan: { kind: "record", id: planId } },
- outputs: { take: `${id}.take` },
+ fragment: narrativeAlignmentAdjustFragment.id,
+ inputs: { source: source.ref, domain: domain.ref, plan: { kind: "record", id: planId } },
+ outputs: { alignment: `${id}.alignment` },
range: element.range,
}],
- fragments: [semanticTakeAdjustFragment],
+ fragments: [narrativeAlignmentAdjustFragment],
};
};
diff --git a/packages/narrative-alignment-adjust/src/types.ts b/packages/narrative-alignment-adjust/src/types.ts
new file mode 100644
index 00000000..e2ff828a
--- /dev/null
+++ b/packages/narrative-alignment-adjust/src/types.ts
@@ -0,0 +1,9 @@
+export type NarrativeBoundaryAdjustment = {
+ readonly boundaryId: string;
+ readonly frame: number;
+};
+
+export type NarrativeAlignmentAdjustmentPlan = {
+ readonly narrativeId: string;
+ readonly boundaries: readonly NarrativeBoundaryAdjustment[];
+};
diff --git a/packages/narrative-alignment-adjust/test/narrative-alignment-adjust.test.ts b/packages/narrative-alignment-adjust/test/narrative-alignment-adjust.test.ts
new file mode 100644
index 00000000..5b05d0ba
--- /dev/null
+++ b/packages/narrative-alignment-adjust/test/narrative-alignment-adjust.test.ts
@@ -0,0 +1,36 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { adjustNarrativeAlignment } from "../src/program.js";
+
+const domain = { id: "voice", frameRate: { numerator: 30, denominator: 1 }, frameCount: 90 };
+const alignment = {
+ narrativeId: "story",
+ domainId: "voice",
+ segment: { segmentId: "opening", startBoundaryId: "opening:start", endBoundaryId: "opening:end" },
+ tokens: [{ tokenId: "hello", segmentId: "opening", text: "hello", startBoundaryId: "hello:start", endBoundaryId: "hello:end" }],
+ boundaries: [
+ { id: "opening:start", frame: 0 },
+ { id: "hello:start", frame: 10 },
+ { id: "hello:end", frame: 40 },
+ { id: "opening:end", frame: 90 },
+ ],
+};
+
+test("alignment correction changes one canonical boundary and no media", () => {
+ const adjusted = adjustNarrativeAlignment(alignment, domain, {
+ narrativeId: "story", boundaries: [{ boundaryId: "hello:end", frame: 45 }],
+ });
+ assert.equal(adjusted.boundaries.find((item) => item.id === "hello:end")?.frame, 45);
+ assert.deepEqual(adjusted.tokens, alignment.tokens);
+ assert.equal("media" in adjusted, false);
+});
+
+test("alignment correction rejects unknown and out-of-domain boundaries", () => {
+ assert.throws(() => adjustNarrativeAlignment(alignment, domain, {
+ narrativeId: "story", boundaries: [{ boundaryId: "missing", frame: 1 }],
+ }), /does not contain/);
+ assert.throws(() => adjustNarrativeAlignment(alignment, domain, {
+ narrativeId: "story", boundaries: [{ boundaryId: "hello:end", frame: 91 }],
+ }), /invalid adjusted frame/);
+});
diff --git a/packages/narrative-caption/README.md b/packages/narrative-caption/README.md
new file mode 100644
index 00000000..602a4a0f
--- /dev/null
+++ b/packages/narrative-caption/README.md
@@ -0,0 +1,16 @@
+# Narrative Caption
+
+`@hypit/narrative-caption` is the explicit adapter between source-neutral Caption content and
+Narrative time. It owns `NarrativeCaptionBinding` and projects that relation through one explicit
+`NarrativeProjection` to ordinary absolute `CaptionTiming`.
+
+Script may emit a CaptionDocument and its binding from the same parse; the author does not repeat
+display text or unit-to-Token correspondence. Caption renderers consume only CaptionDocument and
+CaptionTiming and therefore do not depend on Narrative or speech.
+
+```svml
+<narrative-caption:Timing id="story-captions"
+ document={story.caption}
+ binding={story.caption-binding}
+ projection={speech.projection}/>
+```
diff --git a/packages/semantic-take-adjust/package.json b/packages/narrative-caption/package.json
similarity index 77%
rename from packages/semantic-take-adjust/package.json
rename to packages/narrative-caption/package.json
index e88cb884..3860f125 100644
--- a/packages/semantic-take-adjust/package.json
+++ b/packages/narrative-caption/package.json
@@ -1,5 +1,5 @@
{
- "name": "@hypit/semantic-take-adjust",
+ "name": "@hypit/narrative-caption",
"version": "0.0.0-dev",
"license": "SEE LICENSE IN LICENSE",
"private": true,
@@ -11,11 +11,12 @@
"activation": "./src/activation.ts"
},
"dependencies": {
+ "@hypit/caption": "workspace:*",
"@hypit/component-kit": "workspace:*",
"@hypit/elaborator": "workspace:*",
"@hypit/markup": "workspace:*",
"@hypit/narrative": "workspace:*",
"@hypit/protocol": "workspace:*",
- "@hypit/speech": "workspace:*"
+ "@hypit/narrative-temporal": "workspace:*"
}
}
diff --git a/packages/narrative-caption/src/activation.ts b/packages/narrative-caption/src/activation.ts
new file mode 100644
index 00000000..6ddcf0a4
--- /dev/null
+++ b/packages/narrative-caption/src/activation.ts
@@ -0,0 +1,21 @@
+import { createMarkupSurfaceHostFacet } from "@hypit/markup";
+
+import {
+ decodeNarrativeCaptionTimingSurface,
+ narrativeCaptionComponent,
+ narrativeCaptionManifest,
+ narrativeCaptionModuleRef,
+ narrativeCaptionTimingMarkupSurface,
+} from "./index.js";
+
+export const hypitPackage = {
+ format: "hypit.node-package@1" as const,
+ modules: [{ manifest: narrativeCaptionManifest }],
+ components: [narrativeCaptionComponent],
+ hostFacets: [createMarkupSurfaceHostFacet({
+ module: narrativeCaptionModuleRef,
+ declaration: narrativeCaptionTimingMarkupSurface,
+ handler: decodeNarrativeCaptionTimingSurface,
+ })],
+};
+export default hypitPackage;
diff --git a/packages/narrative-caption/src/component.ts b/packages/narrative-caption/src/component.ts
new file mode 100644
index 00000000..020daee3
--- /dev/null
+++ b/packages/narrative-caption/src/component.ts
@@ -0,0 +1,33 @@
+import type { CaptionDocument, CaptionTiming } from "@hypit/caption";
+import type { ComponentPackage } from "@hypit/component-kit";
+import type { StoredValue } from "@hypit/protocol";
+import { canonicalize } from "@hypit/protocol";
+import type { NarrativeProjection } from "@hypit/narrative-temporal";
+
+import { assertNarrativeCaptionBindingIdentity } from "./identity.js";
+import { narrativeCaptionProducers, narrativeCaptionTypes } from "./manifest.js";
+import { projectNarrativeCaptionTiming } from "./project.js";
+import type { NarrativeCaptionBinding } from "./types.js";
+
+function inline<T>(value: StoredValue | undefined, subject: string): T {
+ if (value?.kind !== "inline") throw new Error(`${subject} must be inline`);
+ return value.value as T;
+}
+
+export const narrativeCaptionComponent = {
+ producers: [{
+ producer: narrativeCaptionProducers.projectTiming,
+ handler: ({ inputs }) => ({
+ outputs: { timing: { kind: "inline", value: canonicalize(projectNarrativeCaptionTiming(
+ inline<CaptionDocument>(inputs.document?.value, "CaptionDocument"),
+ inline<NarrativeCaptionBinding>(inputs.binding?.value, "NarrativeCaptionBinding"),
+ inline<NarrativeProjection>(inputs.projection?.value, "NarrativeProjection"),
+ ) as CaptionTiming) } },
+ needs: {},
+ }),
+ }],
+ validators: [{
+ type: narrativeCaptionTypes.binding,
+ handler: ({ value }) => assertNarrativeCaptionBindingIdentity(inline<NarrativeCaptionBinding>(value, "NarrativeCaptionBinding")),
+ }],
+} satisfies ComponentPackage;
diff --git a/packages/narrative-caption/src/error.ts b/packages/narrative-caption/src/error.ts
new file mode 100644
index 00000000..87bd0d5a
--- /dev/null
+++ b/packages/narrative-caption/src/error.ts
@@ -0,0 +1,9 @@
+export class NarrativeCaptionTimingError extends Error {
+ readonly code: "CAPTION_BINDING" | "CAPTION_TOKEN_ORDER";
+
+ constructor(code: NarrativeCaptionTimingError["code"], message: string) {
+ super(message);
+ this.name = "NarrativeCaptionTimingError";
+ this.code = code;
+ }
+}
diff --git a/packages/narrative-caption/src/identity.ts b/packages/narrative-caption/src/identity.ts
new file mode 100644
index 00000000..5f80c5c0
--- /dev/null
+++ b/packages/narrative-caption/src/identity.ts
@@ -0,0 +1,47 @@
+import type { CaptionDocument } from "@hypit/caption";
+import type { Narrative } from "@hypit/narrative";
+
+import type { NarrativeCaptionBinding } from "./types.js";
+
+function nonempty(value: string, subject: string): void {
+ if (value.trim().length === 0) throw new Error(`${subject} must not be empty.`);
+}
+
+function unique(values: readonly string[], subject: string): Set<string> {
+ const found = new Set<string>();
+ for (const value of values) {
+ nonempty(value, subject);
+ if (found.has(value)) throw new Error(`${subject} repeats ${value}.`);
+ found.add(value);
+ }
+ return found;
+}
+
+export function assertNarrativeCaptionBindingIdentity(value: NarrativeCaptionBinding): void {
+ nonempty(value.id, "NarrativeCaptionBinding id");
+ nonempty(value.narrativeId, "NarrativeCaptionBinding narrativeId");
+ nonempty(value.documentId, "NarrativeCaptionBinding documentId");
+ unique(value.units.map((unit) => unit.unitId), "NarrativeCaptionBinding unit id");
+ for (const unit of value.units) {
+ if (unit.sourceTokenIds.length === 0) throw new Error(`Narrative Caption unit ${unit.unitId} has no source Token.`);
+ unique(unit.sourceTokenIds, `Narrative Caption unit ${unit.unitId} Token`);
+ }
+}
+
+export function assertNarrativeCaptionBindingFor(
+ value: NarrativeCaptionBinding,
+ narrative: Narrative,
+ document: CaptionDocument,
+): void {
+ assertNarrativeCaptionBindingIdentity(value);
+ if (value.narrativeId !== narrative.id || value.documentId !== document.id) {
+ throw new Error("NarrativeCaptionBinding disagrees with its Narrative or CaptionDocument.");
+ }
+ const tokenIds = new Set(narrative.tokens.map((token) => token.id));
+ const documentUnitIds = document.units.map((unit) => unit.id);
+ if (value.units.length !== documentUnitIds.length
+ || value.units.some((unit, index) => unit.unitId !== documentUnitIds[index]
+ || unit.sourceTokenIds.some((tokenId) => !tokenIds.has(tokenId)))) {
+ throw new Error("NarrativeCaptionBinding must cover the document in order using known Narrative Tokens.");
+ }
+}
diff --git a/packages/narrative-caption/src/index.ts b/packages/narrative-caption/src/index.ts
new file mode 100644
index 00000000..b1311452
--- /dev/null
+++ b/packages/narrative-caption/src/index.ts
@@ -0,0 +1,15 @@
+export { narrativeCaptionComponent } from "./component.js";
+export { NarrativeCaptionTimingError } from "./error.js";
+export { assertNarrativeCaptionBindingFor, assertNarrativeCaptionBindingIdentity } from "./identity.js";
+export {
+ narrativeCaptionDependency,
+ narrativeCaptionManifest,
+ narrativeCaptionModuleRef,
+ narrativeCaptionProducers,
+ narrativeCaptionTypes,
+} from "./manifest.js";
+export { projectNarrativeCaptionTiming } from "./project.js";
+export { narrativeCaptionBindingSchema } from "./schema.js";
+export { captionUnitsForNarrativeSelection } from "./selection.js";
+export { decodeNarrativeCaptionTimingSurface, narrativeCaptionTimingMarkupSurface } from "./surface.js";
+export type * from "./types.js";
diff --git a/packages/narrative-caption/src/manifest.ts b/packages/narrative-caption/src/manifest.ts
new file mode 100644
index 00000000..6bdf7b32
--- /dev/null
+++ b/packages/narrative-caption/src/manifest.ts
@@ -0,0 +1,32 @@
+import { captionDependency, captionTypes } from "@hypit/caption";
+import { narrativeDependency } from "@hypit/narrative";
+import type { ModuleManifest, ProducerRef, TypeRef } from "@hypit/protocol";
+import { narrativeTemporalDependency, narrativeTemporalTypes } from "@hypit/narrative-temporal";
+
+export const narrativeCaptionModuleRef = { name: "@hypit/narrative-caption", version: "1" } as const;
+export const narrativeCaptionTypes = {
+ binding: { module: narrativeCaptionModuleRef, name: "NarrativeCaptionBinding" },
+} satisfies Record<string, TypeRef>;
+export const narrativeCaptionProducers = {
+ projectTiming: { module: narrativeCaptionModuleRef, name: "project-narrative-caption-timing" },
+} satisfies Record<string, ProducerRef>;
+
+export const narrativeCaptionManifest: ModuleManifest = {
+ format: "hypit.module@1",
+ name: narrativeCaptionModuleRef.name,
+ version: narrativeCaptionModuleRef.version,
+ dependencies: [captionDependency, narrativeDependency, narrativeTemporalDependency],
+ types: [{ name: narrativeCaptionTypes.binding.name }],
+ capabilities: [],
+ producers: [{
+ name: narrativeCaptionProducers.projectTiming.name,
+ inputs: [
+ { name: "document", type: captionTypes.document },
+ { name: "binding", type: narrativeCaptionTypes.binding },
+ { name: "projection", type: narrativeTemporalTypes.narrativeProjection },
+ ],
+ outputs: [{ name: "timing", type: captionTypes.timing }],
+ needs: [],
+ }],
+};
+export const narrativeCaptionDependency = { module: narrativeCaptionModuleRef } as const;
diff --git a/packages/narrative-caption/src/project.ts b/packages/narrative-caption/src/project.ts
new file mode 100644
index 00000000..05481dfa
--- /dev/null
+++ b/packages/narrative-caption/src/project.ts
@@ -0,0 +1,68 @@
+import { assertCaptionDocument, assertCaptionTiming } from "@hypit/caption";
+import type { CaptionDocument, CaptionTiming, CaptionTimingCue, CaptionTimingUnit } from "@hypit/caption";
+import { tokenFrameSpan } from "@hypit/narrative-temporal";
+import type { NarrativeProjection } from "@hypit/narrative-temporal";
+
+import type { NarrativeCaptionBinding } from "./types.js";
+import { NarrativeCaptionTimingError } from "./error.js";
+
+export function projectNarrativeCaptionTiming(
+ document: CaptionDocument,
+ binding: NarrativeCaptionBinding,
+ projection: NarrativeProjection,
+): CaptionTiming {
+ assertCaptionDocument(document);
+ if (binding.documentId !== document.id || binding.narrativeId !== projection.narrativeId) {
+ throw new NarrativeCaptionTimingError("CAPTION_BINDING", "Caption binding disagrees with its document or NarrativeProjection.");
+ }
+ const sourceTokens = new Map(binding.units.map((unit) => [unit.unitId, unit.sourceTokenIds] as const));
+ const breaks = new Set(document.cueBreaks.map((cueBreak) => cueBreak.afterUnitId));
+ const timed: Array<{ unit: CaptionDocument["units"][number]; timing: CaptionTimingUnit }> = [];
+ const previousByRole = new Map<string | undefined, { timing: CaptionTimingUnit }>();
+ for (const unit of document.units) {
+ const window = tokenFrameSpan(projection, sourceTokens.get(unit.id) ?? []);
+ if (window === undefined) continue;
+ if (window.endFrameExclusive < window.startFrame) {
+ throw new NarrativeCaptionTimingError("CAPTION_TOKEN_ORDER", `Caption unit ${unit.id} references Narrative Tokens in reverse order.`);
+ }
+ const startFrame = window.startFrame;
+ const endFrameExclusive = Math.max(startFrame + 1, window.endFrameExclusive);
+ const previous = previousByRole.get(unit.role);
+ if (previous !== undefined && startFrame > previous.timing.startFrame && startFrame < previous.timing.endFrameExclusive) {
+ previous.timing = { ...previous.timing, endFrameExclusive: startFrame };
+ }
+ const entry = { unit, timing: { unitId: unit.id, startFrame, endFrameExclusive } };
+ previousByRole.set(unit.role, entry);
+ timed.push(entry);
+ }
+ const cues: CaptionTimingCue[] = [];
+ let current: { units: CaptionTimingUnit[]; groupId?: string } | undefined;
+ const flush = (): void => {
+ if (current === undefined || current.units.length === 0) return;
+ cues.push({
+ id: `${document.id}:cue:${cues.length + 1}`,
+ startFrame: current.units[0]!.startFrame,
+ endFrameExclusive: current.units.at(-1)!.endFrameExclusive,
+ units: current.units,
+ });
+ current = undefined;
+ };
+ const documentOrder = new Map(document.units.map((unit, index) => [unit.id, index]));
+ for (const [index, entry] of timed.entries()) {
+ const previousDocumentUnit = index === 0 ? undefined : timed[index - 1]!.unit;
+ const mustBreak = current !== undefined && (
+ current.groupId !== entry.unit.groupId
+ || (previousDocumentUnit !== undefined && (breaks.has(previousDocumentUnit.id)
+ || documentOrder.get(entry.unit.id)! !== documentOrder.get(previousDocumentUnit.id)! + 1))
+ );
+ if (mustBreak) flush();
+ if (current === undefined) {
+ current = { units: [], ...(entry.unit.groupId === undefined ? {} : { groupId: entry.unit.groupId }) };
+ }
+ current.units.push(entry.timing);
+ }
+ flush();
+ const result: CaptionTiming = { timelineId: projection.timelineId, documentId: document.id, cues };
+ assertCaptionTiming(result);
+ return result;
+}
diff --git a/packages/narrative-caption/src/schema.ts b/packages/narrative-caption/src/schema.ts
new file mode 100644
index 00000000..341f9178
--- /dev/null
+++ b/packages/narrative-caption/src/schema.ts
@@ -0,0 +1,13 @@
+import type { ValueSchema } from "@hypit/protocol";
+
+const string = { kind: "string", minLength: 1 } as const;
+const object = (
+ fields: Readonly<Record<string, { readonly schema: ValueSchema; readonly optional?: boolean }>>,
+): ValueSchema => ({ kind: "object", fields });
+
+export const narrativeCaptionBindingSchema: ValueSchema = object({
+ id: { schema: string }, narrativeId: { schema: string }, documentId: { schema: string },
+ units: { schema: { kind: "array", items: object({
+ unitId: { schema: string }, sourceTokenIds: { schema: { kind: "array", minItems: 1, items: string } },
+ }) } },
+});
diff --git a/packages/narrative-caption/src/selection.ts b/packages/narrative-caption/src/selection.ts
new file mode 100644
index 00000000..53adb773
--- /dev/null
+++ b/packages/narrative-caption/src/selection.ts
@@ -0,0 +1,38 @@
+import { assertCaptionDocument } from "@hypit/caption";
+import type { CaptionDocument, CaptionUnitSubset } from "@hypit/caption";
+import { narrativeSelectionTokenRange } from "@hypit/narrative";
+import type { Narrative, NarrativeSelection } from "@hypit/narrative";
+
+import type { NarrativeCaptionBinding } from "./types.js";
+
+/** Project one Narrative Selection to complete authored N:M Caption units. */
+export function captionUnitsForNarrativeSelection(
+ document: CaptionDocument,
+ binding: NarrativeCaptionBinding,
+ narrative: Narrative,
+ selection: NarrativeSelection,
+): CaptionUnitSubset {
+ assertCaptionDocument(document);
+ if (binding.documentId !== document.id || binding.narrativeId !== narrative.id) {
+ throw new Error("NarrativeCaptionBinding disagrees with its document or Narrative.");
+ }
+ const { tokenStart: start, tokenEndExclusive: end } = narrativeSelectionTokenRange(narrative, selection);
+ const tokenPositions = new Map(narrative.tokens.map((token, index) => [token.id, index]));
+ const bound = new Map(binding.units.map((unit) => [unit.unitId, unit.sourceTokenIds] as const));
+ const unitIds: string[] = [];
+ for (const unit of document.units) {
+ const positions = (bound.get(unit.id) ?? []).map((tokenId) => tokenPositions.get(tokenId));
+ if (!positions.every((position): position is number => position !== undefined)) {
+ throw new Error(`Caption unit ${unit.id} references a token outside Narrative`);
+ }
+ const unitStart = Math.min(...positions);
+ const unitEnd = Math.max(...positions) + 1;
+ if (unitStart >= end || unitEnd <= start) continue;
+ if (unitStart < start || unitEnd > end) {
+ throw new Error(`Caption Selection ${selection.id} partially selects Alignment Unit ${unit.id}`);
+ }
+ unitIds.push(unit.id);
+ }
+ if (unitIds.length === 0) throw new Error(`Caption Selection ${selection.id} selects no complete display unit`);
+ return { documentId: document.id, unitIds };
+}
diff --git a/packages/narrative-caption/src/surface.ts b/packages/narrative-caption/src/surface.ts
new file mode 100644
index 00000000..da7f9869
--- /dev/null
+++ b/packages/narrative-caption/src/surface.ts
@@ -0,0 +1,80 @@
+import { captionTypes } from "@hypit/caption";
+import { sealGraphFragment } from "@hypit/elaborator";
+import {
+ assertAttributes,
+ assertEmptyElement,
+ textAttribute,
+ type StructuredSurfaceHandler,
+ type SurfaceResolvedReference,
+} from "@hypit/markup";
+import { sameType, type TypeRef } from "@hypit/protocol";
+import { narrativeTemporalTypes } from "@hypit/narrative-temporal";
+
+import { narrativeCaptionProducers, narrativeCaptionTypes } from "./manifest.js";
+
+const input = (name: string) => ({ kind: "fragment-input" as const, name });
+const operation = (id: string) => ({ kind: "fragment-operation" as const, operation: id });
+
+function reference(
+ path: unknown,
+ subject: string,
+ type: TypeRef,
+ resolve: (path: string) => SurfaceResolvedReference | undefined,
+): SurfaceResolvedReference {
+ if (typeof path !== "object" || path === null || !("kind" in path) || path.kind !== "reference"
+ || !("path" in path) || typeof path.path !== "string") throw new Error(`${subject} must be a reference.`);
+ const found = resolve(path.path);
+ if (found === undefined || !sameType(found.type, type)) throw new Error(`${subject} has the wrong Type.`);
+ return found;
+}
+
+/** Resolve one explicit Narrative-to-Caption relation into neutral absolute CaptionTiming. */
+export const decodeNarrativeCaptionTimingSurface: StructuredSurfaceHandler = ({ element, resolveReference }) => {
+ assertAttributes(element, ["id", "document", "binding", "projection"]);
+ assertEmptyElement(element);
+ const id = textAttribute(element, "id");
+ const document = reference(element.attributes.document, `${element.name}.document`, captionTypes.document, resolveReference);
+ const binding = reference(element.attributes.binding, `${element.name}.binding`, narrativeCaptionTypes.binding, resolveReference);
+ const projection = reference(element.attributes.projection, `${element.name}.projection`, narrativeTemporalTypes.narrativeProjection, resolveReference);
+ const fragment = sealGraphFragment({
+ inputs: [
+ { name: "document", type: captionTypes.document },
+ { name: "binding", type: narrativeCaptionTypes.binding },
+ { name: "projection", type: narrativeTemporalTypes.narrativeProjection },
+ ],
+ operations: [{
+ id: "project",
+ producer: narrativeCaptionProducers.projectTiming,
+ inputs: { document: input("document"), binding: input("binding"), projection: input("projection") },
+ result: { kind: "output", name: "timing" },
+ }],
+ exports: [{ name: "timing", type: captionTypes.timing, root: operation("project") }],
+ });
+ return {
+ records: [],
+ components: [{
+ id,
+ fragment: fragment.id,
+ inputs: { document: document.ref, binding: binding.ref, projection: projection.ref },
+ outputs: { timing: id },
+ range: element.range,
+ }],
+ fragments: [fragment],
+ exports: [id],
+ };
+};
+
+export const narrativeCaptionTimingMarkupSurface = {
+ name: "timing", tag: "Timing", mode: "structured", outputs: [captionTypes.timing],
+ vocabulary: {
+ summary: "Projects an explicit Narrative-to-Caption binding onto absolute CaptionTiming.",
+ attributes: [
+ { name: "id", kind: "identifier", required: true, summary: "Names the resolved CaptionTiming." },
+ { name: "document", kind: "reference", required: true, accepts: [captionTypes.document], summary: "Chooses displayed Caption content." },
+ { name: "binding", kind: "reference", required: true, accepts: [narrativeCaptionTypes.binding], summary: "Relates Caption units to Narrative Tokens." },
+ { name: "projection", kind: "reference", required: true, accepts: [narrativeTemporalTypes.narrativeProjection], summary: "Locates those Tokens on one Timeline." },
+ ],
+ ports: [{ name: "", type: captionTypes.timing, summary: "Neutral absolute timing for the selected CaptionDocument." }],
+ example: '<narrative-caption:Timing id="story-captions" document={story.caption} binding={story.caption-binding} projection={speech.projection}/>',
+ },
+} as const;
diff --git a/packages/narrative-caption/src/types.ts b/packages/narrative-caption/src/types.ts
new file mode 100644
index 00000000..66aa5aaf
--- /dev/null
+++ b/packages/narrative-caption/src/types.ts
@@ -0,0 +1,7 @@
+/** Explicit relation from source-neutral Caption units to Narrative Token identities. */
+export type NarrativeCaptionBinding = {
+ readonly id: string;
+ readonly narrativeId: string;
+ readonly documentId: string;
+ readonly units: readonly { readonly unitId: string; readonly sourceTokenIds: readonly string[] }[];
+};
diff --git a/packages/narrative-temporal/README.md b/packages/narrative-temporal/README.md
new file mode 100644
index 00000000..e7cf0119
--- /dev/null
+++ b/packages/narrative-temporal/README.md
@@ -0,0 +1,31 @@
+# Narrative Temporal
+
+`@hypit/narrative-temporal` owns the public relation between Narrative boundary identities, finite
+source-local domains and one absolute Timeline. It contains no speech, media, Caption or rendering
+policy.
+
+`NarrativeAlignment` locates Narrative boundaries on one `LocalTemporalDomain`.
+`NarrativeProjection` maps one or more explicit `NarrativeAlignment + LocalTemporalDomain + Window`
+relations onto one
+Timeline. Narrative Selections, Moments and Segments can then project to ordinary absolute
+`TemporalInstant` and `TemporalWindow` values before a general component consumes them.
+
+```svml
+<import as="semantic" from="@hypit/narrative-temporal@1"/>
+<semantic:Projection id="story-time" narrative={story} timeline={program.timeline}>
+ <semantic:Map alignment={opening.alignment} domain={opening.domain} window={program.opening}/>
+ <semantic:Window id="proof" selection={story.selection.proof}/>
+ <semantic:Instant id="claim" moment={story.moment.claim}/>
+</semantic:Projection>
+```
+
+The relation may know every located Narrative boundary, but only requested child declarations become
+public graph ports. `story-time.proof` is an ordinary `TemporalWindow`; `story-time.claim` is an
+ordinary `TemporalInstant`. General visual, audio, caption and typography components consume those
+values without receiving the Projection or learning Narrative source kinds. Selection/Segment/Moment
+dispatch remain owned here. The completed Projection stores absolute boundaries and no reusable
+local-to-absolute mapping identity.
+
+Speech Alignment is one producer of `NarrativeAlignment`; manually authored, imported or adjusted
+relations use the same Type without pretending to be speech. Timeline and common Temporal packages
+do not enumerate Narrative event kinds.
diff --git a/packages/sound/package.json b/packages/narrative-temporal/package.json
similarity index 83%
rename from packages/sound/package.json
rename to packages/narrative-temporal/package.json
index e8f39c4f..2fbaf4eb 100644
--- a/packages/sound/package.json
+++ b/packages/narrative-temporal/package.json
@@ -1,5 +1,5 @@
{
- "name": "@hypit/sound",
+ "name": "@hypit/narrative-temporal",
"version": "0.0.0-dev",
"license": "SEE LICENSE IN LICENSE",
"private": true,
@@ -12,11 +12,9 @@
},
"dependencies": {
"@hypit/component-kit": "workspace:*",
- "@hypit/composition": "workspace:*",
"@hypit/elaborator": "workspace:*",
"@hypit/markup": "workspace:*",
"@hypit/narrative": "workspace:*",
- "@hypit/program-space": "workspace:*",
"@hypit/protocol": "workspace:*",
"@hypit/temporal": "workspace:*",
"@hypit/temporal-markup": "workspace:*",
diff --git a/packages/narrative-temporal/src/activation.ts b/packages/narrative-temporal/src/activation.ts
new file mode 100644
index 00000000..dd480433
--- /dev/null
+++ b/packages/narrative-temporal/src/activation.ts
@@ -0,0 +1,12 @@
+import { createMarkupSurfaceHostFacet } from "@hypit/markup";
+import { decodeNarrativeProjectionSurface, narrativeProjectionMarkupSurface, narrativeTemporalComponent,
+ narrativeTemporalManifest, narrativeTemporalModuleRef } from "./index.js";
+
+export const hypitPackage = {
+ format: "hypit.node-package@1" as const,
+ modules: [{ manifest: narrativeTemporalManifest }],
+ components: [narrativeTemporalComponent],
+ hostFacets: [createMarkupSurfaceHostFacet({ module: narrativeTemporalModuleRef,
+ declaration: narrativeProjectionMarkupSurface, handler: decodeNarrativeProjectionSurface })],
+};
+export default hypitPackage;
diff --git a/packages/narrative-temporal/src/component.ts b/packages/narrative-temporal/src/component.ts
new file mode 100644
index 00000000..5327a013
--- /dev/null
+++ b/packages/narrative-temporal/src/component.ts
@@ -0,0 +1,75 @@
+import type { ComponentPackage } from "@hypit/component-kit";
+import type { Narrative, NarrativeExcerpt, NarrativeMomentRef, NarrativeSelectionRef } from "@hypit/narrative";
+import { canonicalize } from "@hypit/protocol";
+import type { ProducerRef, StoredValue } from "@hypit/protocol";
+import type { LocalTemporalDomain, TemporalWindow } from "@hypit/temporal";
+import type { Timeline } from "@hypit/timeline";
+
+import { assertNarrativeAlignmentIdentity } from "./identity.js";
+import { materializeSegmentBoundaryAlignment } from "./materialize.js";
+import { narrativeTemporalProducers, narrativeTemporalTypes } from "./manifest.js";
+import { createNarrativeProjection, projectNarrativeAlignment, projectNarrativeInstant } from "./projection.js";
+import type { NarrativeAlignment, NarrativeInstantSpec, NarrativeProjection, NarrativeProjectionHeader, NarrativeProjectionParts } from "./types.js";
+
+function inline<T>(value: StoredValue | undefined, subject: string): T {
+ if (value?.kind !== "inline") throw new Error(`${subject} must be inline`);
+ return value.value as T;
+}
+
+export const narrativeTemporalComponent = {
+ validators: [{ type: narrativeTemporalTypes.narrativeAlignment,
+ handler: ({ value }) => assertNarrativeAlignmentIdentity(inline<NarrativeAlignment>(value, "NarrativeAlignment")) }],
+ producers: [{
+ producer: narrativeTemporalProducers.materializeSegmentBoundaries,
+ handler: ({ inputs }) => ({ outputs: { alignment: { kind: "inline", value: canonicalize(materializeSegmentBoundaryAlignment(
+ inline<Narrative>(inputs.narrative?.value, "Narrative"),
+ inline<NarrativeExcerpt>(inputs.segment?.value, "NarrativeExcerpt"),
+ inline<LocalTemporalDomain>(inputs.domain?.value, "LocalTemporalDomain"),
+ )) } }, needs: {} }),
+ }, {
+ producer: narrativeTemporalProducers.projectAlignment,
+ handler: ({ inputs }) => ({ outputs: { parts: { kind: "inline", value: canonicalize({ parts: [
+ projectNarrativeAlignment(
+ inline<NarrativeAlignment>(inputs.alignment?.value, "NarrativeAlignment"),
+ inline<LocalTemporalDomain>(inputs.domain?.value, "LocalTemporalDomain"),
+ inline<TemporalWindow>(inputs.window?.value, "TemporalWindow"),
+ inline<Timeline>(inputs.timeline?.value, "Timeline"),
+ ),
+ ] }) } }, needs: {} }),
+ }, {
+ producer: narrativeTemporalProducers.combineProjectionParts,
+ handler: ({ inputs }) => {
+ const left = inline<NarrativeProjectionParts>(inputs.left?.value, "NarrativeProjectionParts");
+ const right = inline<NarrativeProjectionParts>(inputs.right?.value, "NarrativeProjectionParts");
+ return { outputs: { parts: { kind: "inline" as const, value: canonicalize({ parts: [...left.parts, ...right.parts] }) } }, needs: {} };
+ },
+ }, {
+ producer: narrativeTemporalProducers.finalizeProjection,
+ handler: ({ inputs }) => {
+ const header = inline<NarrativeProjectionHeader>(inputs.header?.value, "NarrativeProjectionHeader");
+ const narrative = inline<Narrative>(inputs.narrative?.value, "Narrative");
+ const timeline = inline<Timeline>(inputs.timeline?.value, "Timeline");
+ const parts = inline<NarrativeProjectionParts>(inputs.parts?.value, "NarrativeProjectionParts");
+ return { outputs: { projection: { kind: "inline" as const, value: canonicalize(
+ createNarrativeProjection(header.id, narrative.id, timeline, parts.parts),
+ ) } }, needs: {} };
+ },
+ }, ...([
+ projectionFacet(narrativeTemporalProducers.projectSelectionInstant, "selection", "selection"),
+ projectionFacet(narrativeTemporalProducers.projectSegmentInstant, "segment", "segment"),
+ projectionFacet(narrativeTemporalProducers.projectMomentInstant, "moment", "moment"),
+ ])],
+} satisfies ComponentPackage;
+
+function projectionFacet(producer: ProducerRef, inputName: "selection" | "segment" | "moment",
+ sourceKind: "selection" | "segment" | "moment"): NonNullable<ComponentPackage["producers"]>[number] {
+ return { producer, handler: ({ inputs }) => {
+ const spec = inline<NarrativeInstantSpec>(inputs.spec?.value, "NarrativeInstantSpec");
+ return { outputs: { instant: { kind: "inline" as const, value: canonicalize(projectNarrativeInstant({
+ timeline: inline<Timeline>(inputs.timeline?.value, "Timeline"),
+ narrative: inline<NarrativeProjection>(inputs.projection?.value, "NarrativeProjection"),
+ source: inline<NarrativeSelectionRef | NarrativeExcerpt | NarrativeMomentRef>(inputs[inputName]?.value, inputName),
+ sourceKind, spec,
+ })) } }, needs: {} };
+ } };
+}
diff --git a/packages/narrative-temporal/src/identity.ts b/packages/narrative-temporal/src/identity.ts
new file mode 100644
index 00000000..1d42fdd6
--- /dev/null
+++ b/packages/narrative-temporal/src/identity.ts
@@ -0,0 +1,49 @@
+import { assertLocalTemporalDomain } from "@hypit/temporal";
+import type { LocalTemporalDomain } from "@hypit/temporal";
+
+import type { NarrativeAlignment } from "./types.js";
+
+export function sealNarrativeAlignment(value: NarrativeAlignment, domain?: LocalTemporalDomain): NarrativeAlignment {
+ assertNarrativeAlignmentIdentity(value, domain);
+ return structuredClone(value);
+}
+
+export function assertNarrativeAlignmentIdentity(alignment: NarrativeAlignment, domain?: LocalTemporalDomain): void {
+ if (!alignment.narrativeId.trim() || !alignment.domainId.trim()) throw new Error("NarrativeAlignment identity is invalid.");
+ if (domain !== undefined) {
+ assertLocalTemporalDomain(domain);
+ if (alignment.domainId !== domain.id) throw new Error("NarrativeAlignment belongs to another local domain.");
+ }
+ const frameCount = domain?.frameCount;
+ const frames = new Map<string, number>();
+ for (const boundary of alignment.boundaries) {
+ if (!boundary.id || frames.has(boundary.id) || !Number.isSafeInteger(boundary.frame)
+ || boundary.frame < 0 || (frameCount !== undefined && boundary.frame > frameCount)) {
+ throw new Error(`NarrativeAlignment boundary ${boundary.id || "<unnamed>"} is invalid.`);
+ }
+ frames.set(boundary.id, boundary.frame);
+ }
+ const segment = alignment.segment;
+ if (!segment.segmentId || !segment.startBoundaryId || !segment.endBoundaryId
+ || frames.get(segment.startBoundaryId) === undefined || frames.get(segment.endBoundaryId) === undefined) {
+ throw new Error("NarrativeAlignment Segment boundaries are invalid.");
+ }
+ if (domain !== undefined
+ && (frames.get(segment.startBoundaryId) !== 0 || frames.get(segment.endBoundaryId) !== domain.frameCount)) {
+ throw new Error("NarrativeAlignment Segment must cover its local domain.");
+ }
+ const tokenIds = new Set<string>();
+ let previousStart = 0;
+ let previousEnd = 0;
+ for (const token of alignment.tokens) {
+ const start = frames.get(token.startBoundaryId);
+ const end = frames.get(token.endBoundaryId);
+ if (!token.tokenId || tokenIds.has(token.tokenId) || token.segmentId !== segment.segmentId || !token.text
+ || start === undefined || end === undefined || end <= start || start < previousStart || end < previousEnd) {
+ throw new Error(`NarrativeAlignment Token ${token.tokenId || "<unnamed>"} is invalid.`);
+ }
+ tokenIds.add(token.tokenId);
+ previousStart = start;
+ previousEnd = end;
+ }
+}
diff --git a/packages/narrative-temporal/src/index.ts b/packages/narrative-temporal/src/index.ts
new file mode 100644
index 00000000..7d44d4a7
--- /dev/null
+++ b/packages/narrative-temporal/src/index.ts
@@ -0,0 +1,10 @@
+export { narrativeTemporalComponent } from "./component.js";
+export { assertNarrativeAlignmentIdentity, sealNarrativeAlignment } from "./identity.js";
+export { materializeSegmentBoundaryAlignment } from "./materialize.js";
+export { narrativeTemporalDependency, narrativeTemporalManifest, narrativeTemporalModuleRef,
+ narrativeTemporalProducers, narrativeTemporalTypes } from "./manifest.js";
+export { createNarrativeProjection, momentFrame, narrativeBoundaryFrame, projectNarrativeAlignment, projectNarrativeInstant,
+ segmentFrameSpan, selectionFrameSpan, tokenFrameSpan } from "./projection.js";
+export { narrativeAlignmentSchema } from "./schema.js";
+export { decodeNarrativeProjectionSurface, narrativeProjectionMarkupSurface } from "./surface.js";
+export type * from "./types.js";
diff --git a/packages/narrative-temporal/src/manifest.ts b/packages/narrative-temporal/src/manifest.ts
new file mode 100644
index 00000000..d5ed278e
--- /dev/null
+++ b/packages/narrative-temporal/src/manifest.ts
@@ -0,0 +1,65 @@
+import { narrativeDependency, narrativeTypes } from "@hypit/narrative";
+import type { ModuleManifest, ProducerRef, TypeRef } from "@hypit/protocol";
+import { temporalDependency, temporalTypes } from "@hypit/temporal";
+import { timelineDependency, timelineTypes } from "@hypit/timeline";
+
+export const narrativeTemporalModuleRef = { name: "@hypit/narrative-temporal", version: "1" } as const;
+export const narrativeTemporalTypes = {
+ narrativeAlignment: { module: narrativeTemporalModuleRef, name: "NarrativeAlignment" },
+ narrativeProjection: { module: narrativeTemporalModuleRef, name: "NarrativeProjection" },
+ narrativeInstantSpec: { module: narrativeTemporalModuleRef, name: "NarrativeInstantSpec" },
+ narrativeProjectionParts: { module: narrativeTemporalModuleRef, name: "NarrativeProjectionParts" },
+ narrativeProjectionHeader: { module: narrativeTemporalModuleRef, name: "NarrativeProjectionHeader" },
+} satisfies Record<string, TypeRef>;
+export const narrativeTemporalProducers = {
+ materializeSegmentBoundaries: { module: narrativeTemporalModuleRef, name: "materialize-segment-boundaries" },
+ projectAlignment: { module: narrativeTemporalModuleRef, name: "project-narrative-alignment" },
+ combineProjectionParts: { module: narrativeTemporalModuleRef, name: "combine-narrative-projection-parts" },
+ finalizeProjection: { module: narrativeTemporalModuleRef, name: "finalize-narrative-projection" },
+ projectSelectionInstant: { module: narrativeTemporalModuleRef, name: "project-selection-instant" },
+ projectSegmentInstant: { module: narrativeTemporalModuleRef, name: "project-segment-instant" },
+ projectMomentInstant: { module: narrativeTemporalModuleRef, name: "project-moment-instant" },
+} satisfies Record<string, ProducerRef>;
+
+export const narrativeTemporalManifest: ModuleManifest = {
+ format: "hypit.module@1", name: narrativeTemporalModuleRef.name, version: narrativeTemporalModuleRef.version,
+ dependencies: [narrativeDependency, temporalDependency, timelineDependency],
+ types: Object.values(narrativeTemporalTypes).map((type) => ({ name: type.name })), capabilities: [], producers: [{
+ name: narrativeTemporalProducers.materializeSegmentBoundaries.name,
+ inputs: [{ name: "narrative", type: narrativeTypes.narrative }, { name: "segment", type: narrativeTypes.excerpt },
+ { name: "domain", type: temporalTypes.localDomain }],
+ outputs: [{ name: "alignment", type: narrativeTemporalTypes.narrativeAlignment }], needs: [],
+ }, {
+ name: narrativeTemporalProducers.projectAlignment.name,
+ inputs: [{ name: "alignment", type: narrativeTemporalTypes.narrativeAlignment },
+ { name: "domain", type: temporalTypes.localDomain }, { name: "window", type: temporalTypes.window },
+ { name: "timeline", type: timelineTypes.track }],
+ outputs: [{ name: "parts", type: narrativeTemporalTypes.narrativeProjectionParts }], needs: [],
+ }, {
+ name: narrativeTemporalProducers.combineProjectionParts.name,
+ inputs: [{ name: "left", type: narrativeTemporalTypes.narrativeProjectionParts }, { name: "right", type: narrativeTemporalTypes.narrativeProjectionParts }],
+ outputs: [{ name: "parts", type: narrativeTemporalTypes.narrativeProjectionParts }], needs: [],
+ }, {
+ name: narrativeTemporalProducers.finalizeProjection.name,
+ inputs: [{ name: "header", type: narrativeTemporalTypes.narrativeProjectionHeader },
+ { name: "narrative", type: narrativeTypes.narrative }, { name: "timeline", type: timelineTypes.track },
+ { name: "parts", type: narrativeTemporalTypes.narrativeProjectionParts }],
+ outputs: [{ name: "projection", type: narrativeTemporalTypes.narrativeProjection }], needs: [],
+ }, {
+ name: narrativeTemporalProducers.projectSelectionInstant.name,
+ inputs: [{ name: "timeline", type: timelineTypes.track }, { name: "projection", type: narrativeTemporalTypes.narrativeProjection },
+ { name: "selection", type: narrativeTypes.selection }, { name: "spec", type: narrativeTemporalTypes.narrativeInstantSpec }],
+ outputs: [{ name: "instant", type: temporalTypes.instant }], needs: [],
+ }, {
+ name: narrativeTemporalProducers.projectSegmentInstant.name,
+ inputs: [{ name: "timeline", type: timelineTypes.track }, { name: "projection", type: narrativeTemporalTypes.narrativeProjection },
+ { name: "segment", type: narrativeTypes.excerpt }, { name: "spec", type: narrativeTemporalTypes.narrativeInstantSpec }],
+ outputs: [{ name: "instant", type: temporalTypes.instant }], needs: [],
+ }, {
+ name: narrativeTemporalProducers.projectMomentInstant.name,
+ inputs: [{ name: "timeline", type: timelineTypes.track }, { name: "projection", type: narrativeTemporalTypes.narrativeProjection },
+ { name: "moment", type: narrativeTypes.moment }, { name: "spec", type: narrativeTemporalTypes.narrativeInstantSpec }],
+ outputs: [{ name: "instant", type: temporalTypes.instant }], needs: [],
+ }],
+};
+export const narrativeTemporalDependency = { module: narrativeTemporalModuleRef } as const;
diff --git a/packages/narrative-temporal/src/materialize.ts b/packages/narrative-temporal/src/materialize.ts
new file mode 100644
index 00000000..efed9970
--- /dev/null
+++ b/packages/narrative-temporal/src/materialize.ts
@@ -0,0 +1,37 @@
+import type { Narrative, NarrativeExcerpt } from "@hypit/narrative";
+import { assertLocalTemporalDomain } from "@hypit/temporal";
+import type { LocalTemporalDomain } from "@hypit/temporal";
+
+import { sealNarrativeAlignment } from "./identity.js";
+import type { NarrativeAlignment } from "./types.js";
+
+function authoredSegment(narrative: Narrative, excerpt: NarrativeExcerpt): Narrative["segments"][number] {
+ if (narrative.id !== excerpt.narrativeId) throw new Error(`NarrativeExcerpt ${excerpt.id} belongs to another Narrative.`);
+ if (excerpt.kind !== "segment") throw new Error("NarrativeAlignment materialization requires a Segment excerpt.");
+ const segment = narrative.segments.find((candidate) => candidate.id === excerpt.id);
+ if (segment === undefined) throw new Error(`Narrative does not contain Segment ${excerpt.id}.`);
+ if (excerpt.tokenStart !== segment.tokenStart || excerpt.tokenEndExclusive !== segment.tokenEndExclusive) {
+ throw new Error(`NarrativeExcerpt ${excerpt.id} does not describe its authored Segment.`);
+ }
+ return segment;
+}
+
+export function materializeSegmentBoundaryAlignment(
+ narrative: Narrative,
+ excerpt: NarrativeExcerpt,
+ domain: LocalTemporalDomain,
+): NarrativeAlignment {
+ assertLocalTemporalDomain(domain);
+ const segment = authoredSegment(narrative, excerpt);
+ if (segment.tokenStart !== segment.tokenEndExclusive) throw new Error(`Segment ${segment.id} contains Tokens and needs timing.`);
+ return sealNarrativeAlignment({
+ narrativeId: narrative.id,
+ domainId: domain.id,
+ segment: { segmentId: segment.id, startBoundaryId: segment.startAnchorId, endBoundaryId: segment.endAnchorId },
+ tokens: [],
+ boundaries: [
+ { id: segment.startAnchorId, frame: 0 },
+ { id: segment.endAnchorId, frame: domain.frameCount },
+ ],
+ }, domain);
+}
diff --git a/packages/narrative-temporal/src/projection.ts b/packages/narrative-temporal/src/projection.ts
new file mode 100644
index 00000000..9d870204
--- /dev/null
+++ b/packages/narrative-temporal/src/projection.ts
@@ -0,0 +1,130 @@
+import type { NarrativeExcerpt, NarrativeMomentRef, NarrativeSelectionRef } from "@hypit/narrative";
+import { durationInFrames, projectDomainFrame, resolvedInstant } from "@hypit/temporal";
+import type { LocalTemporalDomain, TemporalInstant, TemporalWindow } from "@hypit/temporal";
+import { assertTimelineIdentity, timelineFrameCount } from "@hypit/timeline";
+import type { Timeline } from "@hypit/timeline";
+
+import { assertNarrativeAlignmentIdentity } from "./identity.js";
+import type { NarrativeAlignment, NarrativeInstantSpec, NarrativeProjection, ProjectedNarrativeAlignment } from "./types.js";
+
+function assert(condition: unknown, message: string): asserts condition {
+ if (!condition) throw new Error(message);
+}
+
+export function projectNarrativeAlignment(
+ alignment: NarrativeAlignment,
+ domain: LocalTemporalDomain,
+ window: TemporalWindow,
+ timeline: Timeline,
+): ProjectedNarrativeAlignment {
+ assertNarrativeAlignmentIdentity(alignment);
+ assert(alignment.domainId === domain.id, "NarrativeAlignment and local temporal domain disagree.");
+ return {
+ narrativeId: alignment.narrativeId,
+ timelineId: timeline.id,
+ segment: structuredClone(alignment.segment),
+ tokens: structuredClone(alignment.tokens),
+ boundaries: alignment.boundaries.map((boundary) => ({
+ id: boundary.id,
+ frame: projectDomainFrame(domain, window, timeline, boundary.frame),
+ })),
+ };
+}
+
+export function createNarrativeProjection(id: string, narrativeId: string, timeline: Timeline,
+ parts: readonly ProjectedNarrativeAlignment[]): NarrativeProjection {
+ assertTimelineIdentity(timeline);
+ assert(id.length > 0 && narrativeId.length > 0, "NarrativeProjection identity is invalid.");
+ const boundaryIds = new Set<string>();
+ const segmentIds = new Set<string>();
+ const tokenIds = new Set<string>();
+ for (const part of parts) {
+ assert(part.narrativeId === narrativeId, "NarrativeProjection mixes Narratives.");
+ assert(part.timelineId === timeline.id, "NarrativeProjection part uses another Timeline.");
+ assert(!segmentIds.has(part.segment.segmentId), `NarrativeProjection repeats Segment ${part.segment.segmentId}.`);
+ segmentIds.add(part.segment.segmentId);
+ for (const token of part.tokens) {
+ assert(!tokenIds.has(token.tokenId), `NarrativeProjection repeats Token ${token.tokenId}.`);
+ tokenIds.add(token.tokenId);
+ }
+ for (const boundary of part.boundaries) {
+ assert(!boundaryIds.has(boundary.id), `NarrativeProjection repeats Boundary ${boundary.id}.`);
+ boundaryIds.add(boundary.id);
+ assert(Number.isSafeInteger(boundary.frame) && boundary.frame >= 0
+ && boundary.frame <= timelineFrameCount(timeline),
+ `NarrativeProjection Boundary ${boundary.id} is outside Timeline.`);
+ }
+ }
+ return {
+ id,
+ narrativeId,
+ timelineId: timeline.id,
+ segments: parts.map((part) => structuredClone(part.segment)),
+ tokens: parts.flatMap((part) => structuredClone(part.tokens)),
+ boundaries: parts.flatMap((part) => structuredClone(part.boundaries)),
+ };
+}
+
+export function narrativeBoundaryFrame(projection: NarrativeProjection, boundaryId: string): number {
+ const boundary = projection.boundaries.find((candidate) => candidate.id === boundaryId);
+ if (boundary !== undefined) return boundary.frame;
+ throw new Error(`NarrativeProjection ${projection.id} does not contain Boundary ${boundaryId}.`);
+}
+
+export function selectionFrameSpan(projection: NarrativeProjection, selection: NarrativeSelectionRef) {
+ assert(selection.narrativeId === projection.narrativeId, `Selection ${selection.id} belongs to another Narrative.`);
+ return { startFrame: narrativeBoundaryFrame(projection, selection.startAnchorId),
+ endFrameExclusive: narrativeBoundaryFrame(projection, selection.endAnchorId) };
+}
+
+export function momentFrame(projection: NarrativeProjection, moment: NarrativeMomentRef): number {
+ assert(moment.narrativeId === projection.narrativeId, `Moment ${moment.id} belongs to another Narrative.`);
+ return narrativeBoundaryFrame(projection, moment.anchorId);
+}
+
+export function segmentFrameSpan(projection: NarrativeProjection, segment: NarrativeExcerpt) {
+ assert(segment.kind === "segment" && segment.narrativeId === projection.narrativeId,
+ `Segment ${segment.id} belongs to another Narrative.`);
+ const projected = projection.segments.find((candidate) => candidate.segmentId === segment.id);
+ if (projected === undefined) throw new Error(`NarrativeProjection does not contain Segment ${segment.id}.`);
+ return { startFrame: narrativeBoundaryFrame(projection, projected.startBoundaryId),
+ endFrameExclusive: narrativeBoundaryFrame(projection, projected.endBoundaryId) };
+}
+
+export function tokenFrameSpan(projection: NarrativeProjection, tokenIds: readonly string[]) {
+ if (tokenIds.length === 0) return undefined;
+ const tokens = new Map(projection.tokens.map((token) => [token.tokenId, token] as const));
+ const first = tokens.get(tokenIds[0]!);
+ const last = tokens.get(tokenIds.at(-1)!);
+ if (first === undefined || last === undefined || tokenIds.some((id) => !tokens.has(id))) return undefined;
+ return { startFrame: narrativeBoundaryFrame(projection, first.startBoundaryId),
+ endFrameExclusive: narrativeBoundaryFrame(projection, last.endBoundaryId) };
+}
+
+function narrativeBase(boundary: NarrativeInstantSpec["boundary"], projection: NarrativeProjection,
+ source: NarrativeSelectionRef | NarrativeMomentRef | NarrativeExcerpt, sourceKind: "selection" | "moment" | "segment"): number {
+ if (sourceKind === "moment") {
+ if (boundary !== "cue") throw new Error("A Narrative Moment only has a cue boundary.");
+ return momentFrame(projection, source as NarrativeMomentRef);
+ }
+ if (boundary === "cue") throw new Error("A Narrative interval has start and end boundaries, not cue.");
+ const span = sourceKind === "selection" ? selectionFrameSpan(projection, source as NarrativeSelectionRef)
+ : segmentFrameSpan(projection, source as NarrativeExcerpt);
+ return boundary === "start" ? span.startFrame : span.endFrameExclusive;
+}
+
+export function projectNarrativeInstant(input: { readonly timeline: Timeline; readonly narrative: NarrativeProjection;
+ readonly source: NarrativeSelectionRef | NarrativeMomentRef | NarrativeExcerpt;
+ readonly sourceKind: "selection" | "moment" | "segment"; readonly spec: NarrativeInstantSpec }): TemporalInstant {
+ assertTimelineIdentity(input.timeline);
+ assert(input.narrative.timelineId === input.timeline.id, "NarrativeProjection belongs to another Timeline.");
+ const base = narrativeBase(input.spec.boundary, input.narrative, input.source, input.sourceKind);
+ const raw = input.spec.offset === undefined ? base : (() => {
+ const delta = durationInFrames(input.spec.offset, input.timeline);
+ assert(delta.denominator === 1n, "Narrative projection offset must resolve to an exact frame.");
+ return base + Number(delta.numerator);
+ })();
+ assert(Number.isSafeInteger(raw) && raw >= 0 && raw <= timelineFrameCount(input.timeline),
+ "Narrative projection falls outside Timeline.");
+ return resolvedInstant(input.spec, input.timeline, raw);
+}
diff --git a/packages/narrative-temporal/src/schema.ts b/packages/narrative-temporal/src/schema.ts
new file mode 100644
index 00000000..bb4fb7a8
--- /dev/null
+++ b/packages/narrative-temporal/src/schema.ts
@@ -0,0 +1,14 @@
+import type { ValueSchema } from "@hypit/protocol";
+
+const string = { kind: "string", minLength: 1 } as const;
+const integer = { kind: "number", integer: true, minimum: 0 } as const;
+const object = (fields: Readonly<Record<string, { readonly schema: ValueSchema; readonly optional?: boolean }>>): ValueSchema => ({ kind: "object", fields });
+const token = object({ tokenId: { schema: string }, segmentId: { schema: string }, text: { schema: string },
+ startBoundaryId: { schema: string }, endBoundaryId: { schema: string } });
+const boundary = object({ id: { schema: string }, frame: { schema: integer } });
+const segment = object({ segmentId: { schema: string }, startBoundaryId: { schema: string }, endBoundaryId: { schema: string } });
+
+export const narrativeAlignmentSchema: ValueSchema = object({
+ narrativeId: { schema: string }, domainId: { schema: string }, segment: { schema: segment },
+ tokens: { schema: { kind: "array", items: token } }, boundaries: { schema: { kind: "array", items: boundary } },
+});
diff --git a/packages/narrative-temporal/src/surface.ts b/packages/narrative-temporal/src/surface.ts
new file mode 100644
index 00000000..bd242b07
--- /dev/null
+++ b/packages/narrative-temporal/src/surface.ts
@@ -0,0 +1,271 @@
+import { sealGraphFragment } from "@hypit/elaborator";
+import type { FragmentOperation, GraphFragment } from "@hypit/elaborator";
+import {
+ assertAttributes, assertEmptyElement, localName, textAttribute,
+ type StructuredElement, type StructuredSurfaceHandler, type SurfaceComponentDraft,
+ type SurfaceRecordDraft, type SurfaceResolvedReference,
+} from "@hypit/markup";
+import { narrativeTypes } from "@hypit/narrative";
+import { canonicalize, sameType, type TypeRef } from "@hypit/protocol";
+import { temporalProducers, temporalTypes } from "@hypit/temporal";
+import type { TemporalDuration } from "@hypit/temporal";
+import { parseTemporalDuration } from "@hypit/temporal-markup";
+import { timelineTypes } from "@hypit/timeline";
+
+import { narrativeTemporalProducers, narrativeTemporalTypes } from "./manifest.js";
+
+const input = (name: string) => ({ kind: "fragment-input" as const, name });
+const operation = (id: string) => ({ kind: "fragment-operation" as const, operation: id });
+
+function reference(path: unknown, subject: string, type: TypeRef,
+ resolve: (path: string) => SurfaceResolvedReference | undefined): SurfaceResolvedReference {
+ if (typeof path !== "object" || path === null || !("kind" in path) || path.kind !== "reference" || !("path" in path)
+ || typeof path.path !== "string") throw new Error(`${subject} must be a reference.`);
+ const found = resolve(path.path);
+ if (found === undefined || !sameType(found.type, type)) throw new Error(`${subject} has the wrong Type.`);
+ return found;
+}
+
+type ProjectionMap = {
+ readonly alignment: SurfaceResolvedReference;
+ readonly domain: SurfaceResolvedReference;
+ readonly window: SurfaceResolvedReference;
+};
+type ProjectionOutput = { readonly element: StructuredElement; readonly id: string; readonly kind: "instant" | "window";
+ readonly sourceKind: "selection" | "segment" | "moment"; readonly source: SurfaceResolvedReference;
+ readonly boundary?: "start" | "end"; readonly offset?: TemporalDuration };
+
+function offset(element: StructuredElement): TemporalDuration | undefined {
+ const raw = element.attributes.offset;
+ if (raw === undefined) return undefined;
+ if (typeof raw !== "string" || !/^[+-]?\d+(?:\.\d+)?(?:f|ms|s)$/u.test(raw.trim())) {
+ throw new Error(`${element.name}.offset must be an exact signed duration.`);
+ }
+ const value = raw.trim(), negative = value.startsWith("-");
+ const parsed = parseTemporalDuration(value.replace(/^[+-]/u, ""), `${element.name}.offset`);
+ if (!negative) return parsed;
+ return parsed.unit === "seconds" ? { ...parsed, numerator: -parsed.numerator } : { ...parsed, value: -parsed.value };
+}
+
+function projectionOutput(element: StructuredElement,
+ resolveReference: (path: string) => SurfaceResolvedReference | undefined): ProjectionOutput {
+ const tag = localName(element.name);
+ if (tag === "Window") {
+ assertAttributes(element, ["id", "selection", "segment"], ["id"]); assertEmptyElement(element);
+ const selection = element.attributes.selection, segment = element.attributes.segment;
+ if (Number(selection !== undefined) + Number(segment !== undefined) !== 1) {
+ throw new Error(`${element.name} requires exactly one of selection or segment.`);
+ }
+ return selection !== undefined
+ ? { element, id: textAttribute(element, "id"), kind: "window", sourceKind: "selection",
+ source: reference(selection, `${element.name}.selection`, narrativeTypes.selection, resolveReference) }
+ : { element, id: textAttribute(element, "id"), kind: "window", sourceKind: "segment",
+ source: reference(segment, `${element.name}.segment`, narrativeTypes.excerpt, resolveReference) };
+ }
+ if (tag !== "Instant") throw new Error(`Projection accepts Map, Window and Instant children only.`);
+ assertAttributes(element, ["id", "selection", "segment", "moment", "boundary", "offset"], ["id"]); assertEmptyElement(element);
+ const sources = ["selection", "segment", "moment"].filter((name) => element.attributes[name] !== undefined);
+ if (sources.length !== 1) throw new Error(`${element.name} requires exactly one of selection, segment or moment.`);
+ const sourceKind = sources[0] as "selection" | "segment" | "moment";
+ const sourceType = sourceKind === "selection" ? narrativeTypes.selection
+ : sourceKind === "segment" ? narrativeTypes.excerpt : narrativeTypes.moment;
+ const boundaryRaw = element.attributes.boundary;
+ if (sourceKind === "moment") {
+ if (boundaryRaw !== undefined) throw new Error(`${element.name}.boundary is invalid for a Moment.`);
+ const projectedOffset = offset(element);
+ return { element, id: textAttribute(element, "id"), kind: "instant", sourceKind,
+ source: reference(element.attributes.moment, `${element.name}.moment`, sourceType, resolveReference),
+ ...(projectedOffset === undefined ? {} : { offset: projectedOffset }) };
+ }
+ if (boundaryRaw !== "start" && boundaryRaw !== "end") {
+ throw new Error(`${element.name}.boundary must be start or end.`);
+ }
+ const projectedOffset = offset(element);
+ return { element, id: textAttribute(element, "id"), kind: "instant", sourceKind,
+ source: reference(element.attributes[sourceKind], `${element.name}.${sourceKind}`, sourceType, resolveReference),
+ boundary: boundaryRaw, ...(projectedOffset === undefined ? {} : { offset: projectedOffset }) };
+}
+
+function projectionProducer(kind: ProjectionOutput["sourceKind"]) {
+ return kind === "selection" ? narrativeTemporalProducers.projectSelectionInstant
+ : kind === "segment" ? narrativeTemporalProducers.projectSegmentInstant
+ : narrativeTemporalProducers.projectMomentInstant;
+}
+
+function outputFragment(output: ProjectionOutput): GraphFragment {
+ const sourceType = output.sourceKind === "selection" ? narrativeTypes.selection
+ : output.sourceKind === "segment" ? narrativeTypes.excerpt : narrativeTypes.moment;
+ const ports: Array<{ readonly name: string; readonly type: TypeRef }> = [
+ { name: "timeline", type: timelineTypes.track },
+ { name: "projection", type: narrativeTemporalTypes.narrativeProjection },
+ { name: "source", type: sourceType },
+ { name: "start-spec", type: narrativeTemporalTypes.narrativeInstantSpec },
+ ];
+ const operations: FragmentOperation[] = [{ id: "start", producer: projectionProducer(output.sourceKind), inputs: {
+ timeline: input("timeline"), projection: input("projection"), [output.sourceKind]: input("source"), spec: input("start-spec"),
+ }, result: { kind: "output", name: "instant" } }];
+ if (output.kind === "instant") return sealGraphFragment({ inputs: ports, operations,
+ exports: [{ name: "instant", type: temporalTypes.instant, root: operation("start") }] });
+ ports.push({ name: "end-spec", type: narrativeTemporalTypes.narrativeInstantSpec },
+ { name: "window-spec", type: temporalTypes.windowSpec });
+ operations.push({ id: "end", producer: projectionProducer(output.sourceKind), inputs: {
+ timeline: input("timeline"), projection: input("projection"), [output.sourceKind]: input("source"), spec: input("end-spec"),
+ }, result: { kind: "output", name: "instant" } }, {
+ id: "window", producer: temporalProducers.composeWindow,
+ inputs: { spec: input("window-spec"), start: operation("start"), end: operation("end") },
+ result: { kind: "output", name: "window" },
+ });
+ return sealGraphFragment({ inputs: ports, operations, exports: [
+ { name: "window", type: temporalTypes.window, root: operation("window") },
+ { name: "start", type: temporalTypes.instant, root: operation("start") },
+ { name: "end", type: temporalTypes.instant, root: operation("end") },
+ ] });
+}
+
+/** Build one Narrative projection and the explicitly requested absolute values derived from it. */
+export const decodeNarrativeProjectionSurface: StructuredSurfaceHandler = ({ element, resolveReference }) => {
+ assertAttributes(element, ["id", "narrative", "timeline"]);
+ const id = textAttribute(element, "id");
+ const narrative = reference(element.attributes.narrative, `${element.name}.narrative`, narrativeTypes.narrative, resolveReference);
+ const timeline = reference(element.attributes.timeline, `${element.name}.timeline`, timelineTypes.track, resolveReference);
+ const maps: ProjectionMap[] = [], requested: ProjectionOutput[] = [];
+ const outputIds = new Set<string>();
+ for (const child of element.children) {
+ if (child.kind === "text") { if (child.value.trim()) throw new Error(`${element.name} accepts Map, Window and Instant children only.`); continue; }
+ if (localName(child.name) === "Map") {
+ assertAttributes(child, ["alignment", "domain", "window"]); assertEmptyElement(child);
+ maps.push({
+ alignment: reference(child.attributes.alignment, `${child.name}.alignment`, narrativeTemporalTypes.narrativeAlignment, resolveReference),
+ domain: reference(child.attributes.domain, `${child.name}.domain`, temporalTypes.localDomain, resolveReference),
+ window: reference(child.attributes.window, `${child.name}.window`, temporalTypes.window, resolveReference),
+ });
+ continue;
+ }
+ const output = projectionOutput(child, resolveReference);
+ if (outputIds.has(output.id)) throw new Error(`${element.name} repeats output ${output.id}.`);
+ outputIds.add(output.id); requested.push(output);
+ }
+ if (maps.length === 0) throw new Error(`${element.name} requires at least one Map.`);
+
+ const ports: Array<{ readonly name: string; readonly type: TypeRef }> = [
+ { name: "header", type: narrativeTemporalTypes.narrativeProjectionHeader },
+ { name: "narrative", type: narrativeTypes.narrative }, { name: "timeline", type: timelineTypes.track },
+ ];
+ const bindings: Record<string, SurfaceResolvedReference["ref"] | { kind: "record"; id: string }> = {
+ header: { kind: "record", id: `${id}.__header` }, narrative: narrative.ref, timeline: timeline.ref,
+ };
+ const operations: FragmentOperation[] = [], entryRoots: string[] = [];
+ for (const [index, map] of maps.entries()) {
+ const alignmentName = `alignment-${index + 1}`;
+ const domainName = `domain-${index + 1}`;
+ const windowName = `window-${index + 1}`;
+ ports.push({ name: alignmentName, type: narrativeTemporalTypes.narrativeAlignment },
+ { name: domainName, type: temporalTypes.localDomain },
+ { name: windowName, type: temporalTypes.window });
+ bindings[alignmentName] = map.alignment.ref;
+ bindings[domainName] = map.domain.ref;
+ bindings[windowName] = map.window.ref;
+ const operationId = `entry-${index + 1}`;
+ operations.push({ id: operationId, producer: narrativeTemporalProducers.projectAlignment,
+ inputs: { alignment: input(alignmentName), domain: input(domainName), window: input(windowName), timeline: input("timeline") },
+ result: { kind: "output", name: "parts" } });
+ entryRoots.push(operationId);
+ }
+ let level = entryRoots, combineIndex = 0;
+ while (level.length > 1) {
+ const next: string[] = [];
+ for (let cursor = 0; cursor < level.length; cursor += 2) {
+ const left = level[cursor]!, right = level[cursor + 1];
+ if (right === undefined) { next.push(left); continue; }
+ const operationId = `combine-${++combineIndex}`;
+ operations.push({ id: operationId, producer: narrativeTemporalProducers.combineProjectionParts,
+ inputs: { left: operation(left), right: operation(right) }, result: { kind: "output", name: "parts" } });
+ next.push(operationId);
+ }
+ level = next;
+ }
+ operations.push({ id: "finalize", producer: narrativeTemporalProducers.finalizeProjection,
+ inputs: { header: input("header"), narrative: input("narrative"), timeline: input("timeline"), parts: operation(level[0]!) },
+ result: { kind: "output", name: "projection" } });
+ const projectionFragment = sealGraphFragment({ inputs: ports, operations,
+ exports: [{ name: "projection", type: narrativeTemporalTypes.narrativeProjection, root: operation("finalize") }] });
+ const records: SurfaceRecordDraft[] = [{ id: `${id}.__header`, type: narrativeTemporalTypes.narrativeProjectionHeader,
+ value: { kind: "inline", value: canonicalize({ id }) }, range: element.range }];
+ const components: SurfaceComponentDraft[] = [{ id, fragment: projectionFragment.id, inputs: bindings,
+ outputs: { projection: `${id}.projection` }, range: element.range }];
+ const fragments: GraphFragment[] = [projectionFragment];
+ const exports = [`${id}.projection`];
+ for (const output of requested) {
+ const subjectId = `${id}.${output.id}`, fragment = outputFragment(output);
+ const startSpecId = `${subjectId}.__start`;
+ const startBoundary = output.kind === "window" ? "start"
+ : output.sourceKind === "moment" ? "cue" : output.boundary!;
+ records.push({ id: startSpecId, type: narrativeTemporalTypes.narrativeInstantSpec,
+ value: { kind: "inline", value: { id: `${subjectId}.start`, subjectId, boundary: startBoundary,
+ ...(output.offset === undefined ? {} : { offset: output.offset }) } }, range: output.element.range });
+ const childBindings: Record<string, SurfaceResolvedReference["ref"] | { kind: "record"; id: string }> = {
+ timeline: timeline.ref, projection: { kind: "component-output", component: id, output: "projection" },
+ source: output.source.ref, "start-spec": { kind: "record", id: startSpecId },
+ };
+ const outputNames = output.kind === "instant"
+ ? { instant: subjectId }
+ : { window: subjectId, start: `${subjectId}.start`, end: `${subjectId}.end` };
+ if (output.kind === "window") {
+ const endSpecId = `${subjectId}.__end`, windowSpecId = `${subjectId}.__window`;
+ records.push({ id: endSpecId, type: narrativeTemporalTypes.narrativeInstantSpec,
+ value: { kind: "inline", value: { id: `${subjectId}.end`, subjectId, boundary: "end" } }, range: output.element.range },
+ { id: windowSpecId, type: temporalTypes.windowSpec,
+ value: { kind: "inline", value: { id: subjectId, subjectId } }, range: output.element.range });
+ childBindings["end-spec"] = { kind: "record", id: endSpecId };
+ childBindings["window-spec"] = { kind: "record", id: windowSpecId };
+ }
+ components.push({ id: `${subjectId}.__projection`, fragment: fragment.id, inputs: childBindings,
+ outputs: outputNames, range: output.element.range });
+ fragments.push(fragment); exports.push(...Object.values(outputNames));
+ }
+ return { records, components, fragments, exports };
+};
+
+export const narrativeProjectionMarkupSurface = {
+ name: "narrative-projection", tag: "Projection", mode: "structured",
+ outputs: [narrativeTemporalTypes.narrativeProjectionHeader, narrativeTemporalTypes.narrativeInstantSpec,
+ narrativeTemporalTypes.narrativeProjection, temporalTypes.windowSpec, temporalTypes.instant, temporalTypes.window],
+ vocabulary: {
+ summary: "Projects explicit NarrativeAlignment values onto one Timeline and publishes requested absolute values.",
+ attributes: [
+ { name: "id", kind: "identifier", required: true, summary: "Names this projection." },
+ { name: "narrative", kind: "reference", required: true, accepts: [narrativeTypes.narrative], summary: "Selects the Narrative identity." },
+ { name: "timeline", kind: "reference", required: true, accepts: [timelineTypes.track], summary: "Selects the target Timeline." },
+ ],
+ children: [
+ { tag: "Map", cardinality: "many", summary: "Projects one local NarrativeAlignment through an exact domain-to-Window relation.", attributes: [
+ { name: "alignment", kind: "reference", required: true, accepts: [narrativeTemporalTypes.narrativeAlignment], summary: "Local Narrative timing facts." },
+ { name: "domain", kind: "reference", required: true, accepts: [temporalTypes.localDomain], summary: "The Alignment's complete local coordinate domain." },
+ { name: "window", kind: "reference", required: true, accepts: [temporalTypes.window], summary: "Equal-length absolute Window receiving that domain." },
+ ] },
+ { tag: "Window", cardinality: "many", summary: "Publishes one selected Segment or Selection as an absolute Window.", attributes: [
+ { name: "id", kind: "identifier", required: true, summary: "Scoped absolute output name." },
+ { name: "selection", kind: "reference", required: false, accepts: [narrativeTypes.selection], summary: "Selection to project." },
+ { name: "segment", kind: "reference", required: false, accepts: [narrativeTypes.excerpt], summary: "Segment to project." },
+ ] },
+ { tag: "Instant", cardinality: "many", summary: "Publishes one Narrative boundary as an absolute Instant.", attributes: [
+ { name: "id", kind: "identifier", required: true, summary: "Scoped absolute output name." },
+ { name: "moment", kind: "reference", required: false, accepts: [narrativeTypes.moment], summary: "Moment cue to project." },
+ { name: "selection", kind: "reference", required: false, accepts: [narrativeTypes.selection], summary: "Selection boundary source." },
+ { name: "segment", kind: "reference", required: false, accepts: [narrativeTypes.excerpt], summary: "Segment boundary source." },
+ { name: "boundary", kind: "literal", required: false, values: ["start", "end"], summary: "Boundary for Selection or Segment." },
+ { name: "offset", kind: "literal", required: false, summary: "Exact signed offset applied after projection." },
+ ] },
+ ],
+ ports: [
+ { name: "projection", type: narrativeTemporalTypes.narrativeProjection, summary: "The explicit Narrative-to-absolute relation." },
+ { name: "<name>", type: temporalTypes.instant, summary: "Requested scoped Instant." },
+ { name: "<name>", type: temporalTypes.window, summary: "Requested scoped Window with .start and .end Instants." },
+ ],
+ example: `<semantic:Projection id="story-time" narrative={story} timeline={film.timeline}>
+ <semantic:Map alignment={opening.alignment} domain={opening.domain} window={program.opening}/>
+ <semantic:Window id="proof" selection={story.selection.proof}/>
+ <semantic:Instant id="claim" moment={story.moment.claim}/>
+</semantic:Projection>`,
+ },
+} as const;
diff --git a/packages/narrative-temporal/src/types.ts b/packages/narrative-temporal/src/types.ts
new file mode 100644
index 00000000..c371e415
--- /dev/null
+++ b/packages/narrative-temporal/src/types.ts
@@ -0,0 +1,54 @@
+export type NarrativeAlignmentToken = {
+ readonly tokenId: string;
+ readonly segmentId: string;
+ readonly text: string;
+ readonly startBoundaryId: string;
+ readonly endBoundaryId: string;
+};
+
+/** Narrative boundary meaning located on one named source-local domain. */
+export type NarrativeAlignment = {
+ readonly narrativeId: string;
+ readonly domainId: string;
+ readonly segment: {
+ readonly segmentId: string;
+ readonly startBoundaryId: string;
+ readonly endBoundaryId: string;
+ };
+ readonly tokens: readonly NarrativeAlignmentToken[];
+ readonly boundaries: readonly { readonly id: string; readonly frame: number }[];
+};
+
+/** One alignment after its domain-owned exact projection has erased its proof inputs. */
+export type ProjectedNarrativeAlignment = {
+ readonly narrativeId: string;
+ readonly timelineId: string;
+ readonly segment: NarrativeAlignment["segment"];
+ readonly tokens: readonly NarrativeAlignmentToken[];
+ readonly boundaries: readonly { readonly id: string; readonly frame: number }[];
+};
+
+/** Internal balanced aggregation value used by the author Surface. */
+export type NarrativeProjectionParts = {
+ readonly parts: readonly ProjectedNarrativeAlignment[];
+};
+
+export type NarrativeProjectionHeader = { readonly id: string };
+
+/** Explicitly projects one Narrative's boundary facts onto one Timeline. */
+export type NarrativeProjection = {
+ readonly id: string;
+ readonly narrativeId: string;
+ readonly timelineId: string;
+ readonly segments: readonly NarrativeAlignment["segment"][];
+ readonly tokens: readonly NarrativeAlignmentToken[];
+ readonly boundaries: readonly { readonly id: string; readonly frame: number }[];
+};
+
+/** Domain-owned request for one Narrative boundary projected into Timeline. */
+export type NarrativeInstantSpec = {
+ readonly id: string;
+ readonly subjectId: string;
+ readonly boundary: "start" | "end" | "cue";
+ readonly offset?: import("@hypit/temporal").TemporalDuration;
+};
diff --git a/packages/narrative-temporal/test/identity.test.ts b/packages/narrative-temporal/test/identity.test.ts
new file mode 100644
index 00000000..61ef7dc5
--- /dev/null
+++ b/packages/narrative-temporal/test/identity.test.ts
@@ -0,0 +1,23 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { assertNarrativeAlignmentIdentity } from "@hypit/narrative-temporal";
+
+const domain = { id: "speech-domain", frameRate: { numerator: 30, denominator: 1 }, frameCount: 30 };
+
+test("NarrativeAlignment uses one canonical coordinate per named boundary", () => {
+ const alignment = {
+ narrativeId: "story", domainId: domain.id,
+ segment: { segmentId: "intro", startBoundaryId: "intro:start", endBoundaryId: "intro:end" },
+ tokens: [{ tokenId: "hello", segmentId: "intro", text: "hello", startBoundaryId: "hello:start", endBoundaryId: "hello:end" }],
+ boundaries: [
+ { id: "intro:start", frame: 0 }, { id: "hello:start", frame: 3 },
+ { id: "hello:end", frame: 10 }, { id: "intro:end", frame: 30 },
+ ],
+ };
+ assert.doesNotThrow(() => assertNarrativeAlignmentIdentity(alignment, domain));
+ assert.throws(() => assertNarrativeAlignmentIdentity({ ...alignment,
+ boundaries: [...alignment.boundaries, { id: "hello:start", frame: 4 }] }, domain), /boundary hello:start is invalid/u);
+ assert.throws(() => assertNarrativeAlignmentIdentity({ ...alignment,
+ boundaries: alignment.boundaries.filter((boundary) => boundary.id !== "hello:end") }, domain), /Token hello is invalid/u);
+});
diff --git a/packages/narrative-temporal/test/surface.test.ts b/packages/narrative-temporal/test/surface.test.ts
new file mode 100644
index 00000000..2ae909ad
--- /dev/null
+++ b/packages/narrative-temporal/test/surface.test.ts
@@ -0,0 +1,55 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { parseStructuredElement, type SurfaceResolvedReference } from "@hypit/markup";
+import { narrativeTypes } from "@hypit/narrative";
+import { decodeNarrativeProjectionSurface, narrativeProjectionMarkupSurface, narrativeTemporalTypes } from "@hypit/narrative-temporal";
+import { temporalTypes } from "@hypit/temporal";
+import { timelineTypes } from "@hypit/timeline";
+
+test("Projection Surface balances maps and publishes only requested absolute values", async () => {
+ const source = `<semantic:Projection id="story-time" narrative={story} timeline={film}>
+ <semantic:Map alignment={one.alignment} domain={one.domain} window={one.window}/>
+ <semantic:Map alignment={two.alignment} domain={two.domain} window={two.window}/>
+ <semantic:Map alignment={three.alignment} domain={three.domain} window={three.window}/>
+ <semantic:Window id="proof" selection={proof}/>
+ <semantic:Instant id="reveal" moment={reveal}/>
+ <semantic:Instant id="ending" segment={ending} boundary="end" offset="-12f"/>
+ </semantic:Projection>`;
+ const typed = (path: string, type: SurfaceResolvedReference["type"]): SurfaceResolvedReference =>
+ ({ path, type, ref: { kind: "record", id: path } });
+ const references = new Map<string, SurfaceResolvedReference>([
+ ["story", typed("story", narrativeTypes.narrative)],
+ ["film", typed("film", timelineTypes.track)],
+ ["proof", typed("proof", narrativeTypes.selection)],
+ ["reveal", typed("reveal", narrativeTypes.moment)],
+ ["ending", typed("ending", narrativeTypes.excerpt)],
+ ...["one", "two", "three"].flatMap((id): Array<[string, SurfaceResolvedReference]> => [
+ [`${id}.alignment`, typed(`${id}.alignment`, narrativeTemporalTypes.narrativeAlignment)],
+ [`${id}.domain`, typed(`${id}.domain`, temporalTypes.localDomain)],
+ [`${id}.window`, typed(`${id}.window`, temporalTypes.window)],
+ ]),
+ ]);
+ const output = await decodeNarrativeProjectionSurface({
+ sourceName: "projection.svml",
+ element: parseStructuredElement({ name: "projection.svml", text: source }, 0).element,
+ resolveReference: (path) => references.get(path),
+ resolveAsset: async () => { throw new Error("unused"); },
+ });
+ assert.deepEqual(output.exports, ["story-time.projection", "story-time.proof", "story-time.proof.start",
+ "story-time.proof.end", "story-time.reveal", "story-time.ending"]);
+ const fragment = output.fragments[0]!;
+ assert.equal(fragment.operations.filter((operation) => operation.producer.name === "project-narrative-alignment").length, 3);
+ assert.equal(fragment.operations.filter((operation) => operation.producer.name === "combine-narrative-projection-parts").length, 2);
+ assert.equal(fragment.operations.at(-1)?.producer.name, "finalize-narrative-projection");
+ assert.equal(output.fragments.some((candidate) => candidate.operations.some((operation) => operation.producer.name === "compose-window")), true);
+ assert.equal(output.records.some((record) => record.type.name === "NarrativeInstantSpec"
+ && record.value.kind === "inline" && JSON.stringify(record.value.value).includes('"value":-12')), true);
+});
+
+test("Projection Surface declares every private Record Type it emits", () => {
+ const outputNames = new Set(narrativeProjectionMarkupSurface.outputs.map((type) => type.name));
+ assert.ok(outputNames.has("NarrativeProjectionHeader"));
+ assert.ok(outputNames.has("NarrativeInstantSpec"));
+ assert.ok(outputNames.has("TemporalWindowSpec"));
+});
diff --git a/packages/narrative/README.md b/packages/narrative/README.md
index d520b3a8..10cfb5d4 100644
--- a/packages/narrative/README.md
+++ b/packages/narrative/README.md
@@ -6,11 +6,10 @@ owns the types and helpers below; Source imports retain the `@hypit/narrative@1`
Public, provider-neutral values for complete authored content and its semantic references.
-A `Narrative` owns speech Tokens, Segments, Turns, semantic Anchors, Selections and Moments, plus
-its `caption: CaptionDocument`. The document supplies display Words, speech/display correspondence
-and Cue breaks. These are authored relationships; frame timing and visual Styles belong downstream.
-Script exports the complete value as `story` and the same document as the narrow `story.caption`
-Record. A third-party author package can produce the same values without importing the Script parser.
+A `Narrative` owns speech Tokens, Segments, Turns, semantic Anchors, Selections and Moments. It owns
+no Caption document, media or Timeline. Script may publish a peer `story.caption` Record and one
+explicit Narrative-to-Caption binding from the same parse, but neither is embedded in Narrative.
+A third-party author package can produce the same values without importing the Script parser.
## Query content through semantic references
@@ -23,9 +22,9 @@ Selection retains its Narrative identity; content lookup checks that identity. S
remain distinct even when they resolve to the same token boundary, and an empty Segment can select
no Tokens. Authored order is independent of gaps, overlap or placement order in a Timeline.
-Caption uses this content query and the Narrative's display correspondence to select complete
-subtitle units. Timeline projection uses the same semantic references to locate events in physical
-time. Neither operation substitutes for the other. Token lookup returns Tokens, not reconstructed
+`@hypit/narrative-caption` combines an explicit binding with these content queries to select complete
+subtitle units or project them into absolute Caption timing. Timeline projection uses the same
+semantic references to locate events in physical time. Neither operation substitutes for the other. Token lookup returns Tokens, not reconstructed
source prose: comments and source-preserving edits remain the author language's concern. Caption
-Display Words separately carry `separatorBefore` (`""` or `" "`) so consumers can reconstruct the
-authored display spelling without guessing from Token boundaries or importing an author parser.
+Caption Display Words separately carry `separatorBefore` (`""` or `" "`) so consumers can reconstruct
+the authored display spelling without guessing from Token boundaries or importing an author parser.
diff --git a/packages/narrative/src/component.ts b/packages/narrative/src/component.ts
index 8964a756..c9d1dad7 100644
--- a/packages/narrative/src/component.ts
+++ b/packages/narrative/src/component.ts
@@ -2,7 +2,6 @@ import type { ComponentPackage } from "@hypit/component-kit";
import type { StoredValue } from "@hypit/protocol";
import {
- assertCaptionDocumentIdentity,
assertNarrativeExcerptIdentity,
assertNarrativeIdentity,
assertNarrativeMomentRefIdentity,
@@ -10,7 +9,6 @@ import {
} from "./identity.js";
import { narrativeTypes } from "./manifest.js";
import type {
- CaptionDocument,
Narrative,
NarrativeExcerpt,
NarrativeMomentRef,
@@ -28,6 +26,5 @@ export const narrativeComponent = {
{ type: narrativeTypes.excerpt, handler: ({ value }) => assertNarrativeExcerptIdentity(inline<NarrativeExcerpt>(value, "NarrativeExcerpt")) },
{ type: narrativeTypes.selection, handler: ({ value }) => assertNarrativeSelectionRefIdentity(inline<NarrativeSelectionRef>(value, "NarrativeSelection")) },
{ type: narrativeTypes.moment, handler: ({ value }) => assertNarrativeMomentRefIdentity(inline<NarrativeMomentRef>(value, "NarrativeMoment")) },
- { type: narrativeTypes.captionDocument, handler: ({ value }) => assertCaptionDocumentIdentity(inline<CaptionDocument>(value, "CaptionDocument")) },
],
} satisfies ComponentPackage;
diff --git a/packages/narrative/src/identity.ts b/packages/narrative/src/identity.ts
index bda2c6a5..d7f09fda 100644
--- a/packages/narrative/src/identity.ts
+++ b/packages/narrative/src/identity.ts
@@ -1,5 +1,4 @@
import type {
- CaptionDocument,
Narrative,
NarrativeExcerpt,
NarrativeMomentRef,
@@ -25,27 +24,13 @@ export function assertNarrativeIdentity(value: Narrative): void {
if (value.segments.length === 0) throw new Error("Narrative must contain at least one Segment.");
const segmentIds = unique(value.segments.map((item) => item.id), "Narrative Segment id");
const tokenIds = unique(value.tokens.map((item) => item.id), "Narrative Token id");
- assertCaptionDocumentIdentity(value.caption);
- if (value.caption.narrativeId !== value.id) throw new Error("Narrative CaptionDocument belongs to another Narrative.");
- const turns = new Map(value.turns.map((turn) => [turn.id, turn]));
- const tokens = new Map(value.tokens.map((token) => [token.id, token]));
- for (const unit of value.caption.units) {
- const turn = turns.get(unit.turnId);
- if (turn === undefined || turn.segmentId !== unit.segmentId || turn.role !== unit.role
- || unit.sourceTokenIds.some((id) => tokens.get(id)?.segmentId !== unit.segmentId)) {
- throw new Error(`Caption unit ${unit.id} disagrees with its authored speech.`);
- }
- }
unique(value.turns.map((item) => item.id), "Narrative Turn id");
unique(value.selections.map((item) => item.id), "Narrative Selection id");
unique(value.moments.map((item) => item.id), "Narrative Moment id");
const anchorIds = unique(value.semanticIndex.anchors.map((item) => item.id), "Narrative Anchor id");
const anchors = value.semanticIndex.anchors;
- if (anchors[0]?.id !== "program:start" || anchors[0].kind !== "program-start"
- || anchors.at(-1)?.id !== "program:end" || anchors.at(-1)?.kind !== "program-end") {
- throw new Error("Narrative semantic anchors must begin and end with the Program boundaries.");
- }
const anchorOrder = new Map(anchors.map((anchor, index) => [anchor.id, index] as const));
+ let anchorCursor = 0;
let tokenCursor = 0;
for (const segment of value.segments) {
if (!Number.isSafeInteger(segment.tokenStart) || !Number.isSafeInteger(segment.tokenEndExclusive)
@@ -54,6 +39,11 @@ export function assertNarrativeIdentity(value: Narrative): void {
|| !anchorIds.has(segment.startAnchorId) || !anchorIds.has(segment.endAnchorId)) {
throw new Error(`Narrative Segment ${segment.id} has invalid token or Anchor boundaries.`);
}
+ const segmentStart = anchors[anchorCursor++];
+ if (segmentStart?.id !== segment.startAnchorId || segmentStart.kind !== "segment-start"
+ || segmentStart.segmentId !== segment.id) {
+ throw new Error(`Narrative Segment ${segment.id} has no ordered start Anchor.`);
+ }
for (let index = segment.tokenStart; index < segment.tokenEndExclusive; index += 1) {
const token = value.tokens[index]!;
if (token.segmentId !== segment.id || !tokenIds.has(token.id)
@@ -61,10 +51,26 @@ export function assertNarrativeIdentity(value: Narrative): void {
|| token.text.length === 0 || token.normalized.length === 0) {
throw new Error(`Narrative Token ${token.id} disagrees with Segment ${segment.id}.`);
}
+ const start = anchors[anchorCursor++];
+ const end = anchors[anchorCursor++];
+ if (start?.id !== token.startAnchorId || start.kind !== "token-start"
+ || start.segmentId !== segment.id || start.tokenId !== token.id
+ || end?.id !== token.endAnchorId || end.kind !== "token-end"
+ || end.segmentId !== segment.id || end.tokenId !== token.id) {
+ throw new Error(`Narrative Token ${token.id} has no ordered Anchor pair.`);
+ }
+ }
+ const segmentEnd = anchors[anchorCursor++];
+ if (segmentEnd?.id !== segment.endAnchorId || segmentEnd.kind !== "segment-end"
+ || segmentEnd.segmentId !== segment.id) {
+ throw new Error(`Narrative Segment ${segment.id} has no ordered end Anchor.`);
}
tokenCursor = segment.tokenEndExclusive;
}
if (tokenCursor !== value.tokens.length) throw new Error("Narrative Segments must partition Tokens in order.");
+ if (anchorCursor !== anchors.length) {
+ throw new Error("Narrative semantic anchors must be exactly the Segment and Token boundaries.");
+ }
for (const turn of value.turns) {
if (!segmentIds.has(turn.segmentId) || !Number.isSafeInteger(turn.tokenStart)
|| !Number.isSafeInteger(turn.tokenEndExclusive) || turn.tokenEndExclusive <= turn.tokenStart
@@ -107,36 +113,3 @@ export function assertNarrativeMomentRefIdentity(value: NarrativeMomentRef): voi
nonempty(value.id, "NarrativeMoment id");
nonempty(value.anchorId, "NarrativeMoment anchorId");
}
-
-export function assertCaptionDocumentIdentity(value: CaptionDocument): void {
- nonempty(value.narrativeId, "CaptionDocument narrativeId");
- nonempty(value.id, "CaptionDocument id");
- if ((value.units.length === 0) !== (value.words.length === 0)) {
- throw new Error("CaptionDocument units and words must be empty together.");
- }
- const unitIds = unique(value.units.map((item) => item.id), "CaptionDocument unit id");
- const wordIds = unique(value.words.map((item) => item.id), "CaptionDocument word id");
- const words = new Map(value.words.map((word) => [word.id, word] as const));
- const orderedWords: string[] = [];
- for (const unit of value.units) {
- if (unit.wordIds.length === 0 || unit.sourceTokenIds.length === 0) {
- throw new Error(`Caption unit ${unit.id} is empty.`);
- }
- for (const wordId of unit.wordIds) {
- const word = words.get(wordId);
- if (word === undefined || word.unitId !== unit.id || word.segmentId !== unit.segmentId
- || word.turnId !== unit.turnId || word.role !== unit.role) {
- throw new Error(`Caption unit ${unit.id} references a foreign word.`);
- }
- orderedWords.push(wordId);
- }
- }
- if (orderedWords.length !== wordIds.size
- || orderedWords.some((id, index) => id !== value.words[index]?.id)) {
- throw new Error("CaptionDocument units must partition words in order.");
- }
- unique(value.cueBreaks.map((item) => item.afterUnitId), "CaptionDocument Cue Break");
- if (value.cueBreaks.some((item) => !unitIds.has(item.afterUnitId))) {
- throw new Error("CaptionDocument Cue Break names an unknown unit.");
- }
-}
diff --git a/packages/narrative/src/index.ts b/packages/narrative/src/index.ts
index 92035ad0..d0927d05 100644
--- a/packages/narrative/src/index.ts
+++ b/packages/narrative/src/index.ts
@@ -1,13 +1,12 @@
export { narrativeDependency, narrativeManifest, narrativeModuleRef, narrativeTypes } from "./manifest.js";
export { narrativeComponent } from "./component.js";
export {
- assertCaptionDocumentIdentity,
assertNarrativeExcerptIdentity,
assertNarrativeIdentity,
assertNarrativeMomentRefIdentity,
assertNarrativeSelectionRefIdentity,
} from "./identity.js";
-export { captionDocumentSchema, narrativeExcerptSchema, narrativeMomentSchema, narrativeSchema, narrativeSelectionSchema } from "./schema.js";
+export { narrativeExcerptSchema, narrativeMomentSchema, narrativeSchema, narrativeSelectionSchema } from "./schema.js";
export type * from "./types.js";
export { narrativeAnchorTokenBoundary, narrativeSelectionTokenRange, narrativeTokensForSelection } from "./selection.js";
diff --git a/packages/narrative/src/manifest.ts b/packages/narrative/src/manifest.ts
index c1c14fb6..5f25a11e 100644
--- a/packages/narrative/src/manifest.ts
+++ b/packages/narrative/src/manifest.ts
@@ -1,6 +1,5 @@
import type { ModuleManifest, TypeRef } from "@hypit/protocol";
import {
- captionDocumentSchema,
narrativeExcerptSchema,
narrativeSchema,
narrativeMomentSchema,
@@ -13,7 +12,6 @@ export const narrativeTypes = {
excerpt: { module: narrativeModuleRef, name: "NarrativeExcerpt" },
selection: { module: narrativeModuleRef, name: "NarrativeSelection" },
moment: { module: narrativeModuleRef, name: "NarrativeMoment" },
- captionDocument: { module: narrativeModuleRef, name: "CaptionDocument" },
} satisfies Record<string, TypeRef>;
export const narrativeManifest: ModuleManifest = {
format: "hypit.module@1", name: narrativeModuleRef.name, version: narrativeModuleRef.version,
@@ -23,7 +21,6 @@ export const narrativeManifest: ModuleManifest = {
{ name: narrativeTypes.excerpt.name },
{ name: narrativeTypes.selection.name },
{ name: narrativeTypes.moment.name },
- { name: narrativeTypes.captionDocument.name },
],
capabilities: [], producers: [],
};
diff --git a/packages/narrative/src/schema.ts b/packages/narrative/src/schema.ts
index 32b80d4c..8b2a4985 100644
--- a/packages/narrative/src/schema.ts
+++ b/packages/narrative/src/schema.ts
@@ -6,10 +6,6 @@ const object = (
fields: Readonly<Record<string, { readonly schema: ValueSchema; readonly optional?: boolean }>>,
): ValueSchema => ({ kind: "object", fields });
const semanticAnchor: ValueSchema = { kind: "oneOf", variants: [
- object({
- id: { schema: { kind: "literal", value: "program:start" } },
- kind: { schema: { kind: "literal", value: "program-start" } },
- }),
object({
id: { schema: string }, kind: { schema: { kind: "string", enum: ["segment-start", "segment-end"] } },
segmentId: { schema: string },
@@ -18,42 +14,14 @@ const semanticAnchor: ValueSchema = { kind: "oneOf", variants: [
id: { schema: string }, kind: { schema: { kind: "string", enum: ["token-start", "token-end"] } },
segmentId: { schema: string }, tokenId: { schema: string },
}),
- object({
- id: { schema: { kind: "literal", value: "program:end" } },
- kind: { schema: { kind: "literal", value: "program-end" } },
- }),
] };
export const narrativeExcerptSchema: ValueSchema = object({
narrativeId: { schema: string },
kind: { schema: { kind: "literal", value: "segment" } }, id: { schema: string },
tokenStart: { schema: integer }, tokenEndExclusive: { schema: integer },
});
-const captionDisplayWord = object({
- separatorBefore: { schema: { kind: "string", enum: ["", " "] } },
- id: { schema: string }, unitId: { schema: string }, segmentId: { schema: string },
- turnId: { schema: string }, role: { schema: string, optional: true }, text: { schema: string },
- attributes: { schema: { kind: "array", items: object({
- name: { schema: string },
- value: { schema: { kind: "oneOf", variants: [string, { kind: "number" }, { kind: "boolean" }] } },
- }) } },
-});
-const captionAlignmentUnit = object({
- id: { schema: string }, segmentId: { schema: string },
- turnId: { schema: string }, role: { schema: string, optional: true },
- wordIds: { schema: { kind: "array", minItems: 1, items: string } },
- sourceTokenIds: { schema: { kind: "array", minItems: 1, items: string } },
-});
-const captionCueBreak = object({ afterUnitId: { schema: string } });
-export const captionDocumentSchema: ValueSchema = object({
- narrativeId: { schema: string },
- id: { schema: string },
- units: { schema: { kind: "array", items: captionAlignmentUnit } },
- words: { schema: { kind: "array", items: captionDisplayWord } },
- cueBreaks: { schema: { kind: "array", items: captionCueBreak } },
-});
export const narrativeSchema: ValueSchema = object({
id: { schema: string },
- caption: { schema: captionDocumentSchema },
segments: { schema: { kind: "array", minItems: 1, items: object({
id: { schema: string }, startAnchorId: { schema: string },
endAnchorId: { schema: string }, tokenStart: { schema: integer }, tokenEndExclusive: { schema: integer },
diff --git a/packages/narrative/src/selection.ts b/packages/narrative/src/selection.ts
index 83057e4a..cef31c2f 100644
--- a/packages/narrative/src/selection.ts
+++ b/packages/narrative/src/selection.ts
@@ -11,8 +11,6 @@ export type NarrativeTokenRange = {
export function narrativeAnchorTokenBoundary(narrative: Narrative, anchorId: string): number {
const anchor = narrative.semanticIndex.anchors.find((item) => item.id === anchorId);
if (anchor === undefined) throw new Error(`Narrative ${narrative.id} has no anchor ${anchorId}.`);
- if (anchor.kind === "program-start") return 0;
- if (anchor.kind === "program-end") return narrative.tokens.length;
const segment = narrative.segments.find((item) => item.id === anchor.segmentId);
if (segment === undefined) throw new Error(`Anchor ${anchorId} has no authored Segment.`);
if (anchor.kind === "segment-start") return segment.tokenStart;
diff --git a/packages/narrative/src/types.ts b/packages/narrative/src/types.ts
index d0f40389..4c8d6ac8 100644
--- a/packages/narrative/src/types.ts
+++ b/packages/narrative/src/types.ts
@@ -48,71 +48,18 @@ export type NarrativeMomentRef = NarrativeMoment & {
readonly narrativeId: string;
};
-/** One author-visible word surface. Punctuation owned by the surface is preserved. */
-export type CaptionDisplayWord = {
- /** Authored display separator from the preceding word; ignored at a displayed line start. */
- readonly separatorBefore: "" | " ";
- readonly id: string;
- readonly unitId: string;
- readonly segmentId: string;
- readonly turnId: string;
- readonly role?: string;
- readonly text: string;
- /** Reserved for Script-native word attributes; empty until an inline Mark is authored. */
- readonly attributes: readonly CaptionWordAttribute[];
-};
-
-export type CaptionWordAttributeValue = string | number | boolean;
-
-export type CaptionWordAttribute = {
- readonly name: string;
- readonly value: CaptionWordAttributeValue;
-};
-
-/** The smallest author-declared N:M display-to-speech correspondence unit. */
-export type CaptionAlignmentUnit = {
- readonly id: string;
- readonly segmentId: string;
- readonly turnId: string;
- readonly role?: string;
- readonly wordIds: readonly string[];
- /** Speech tokens are retained here so Caption can project a Narrative Selection without frames. */
- readonly sourceTokenIds: readonly string[];
-};
-
-export type CaptionCueBreak = {
- /** The Cue boundary is after this complete Alignment Unit. */
- readonly afterUnitId: string;
-};
-
-/** Complete Script-owned Caption truth. It contains no frame or measured timing facts. */
-export type CaptionDocument = {
- /** Author-visible `<script id>` that owns this caption projection. */
- readonly narrativeId: string;
- readonly id: string;
- readonly units: readonly CaptionAlignmentUnit[];
- readonly words: readonly CaptionDisplayWord[];
- readonly cueBreaks: readonly CaptionCueBreak[];
-};
-
export type SemanticAnchor =
| {
- readonly id: "program:start";
- readonly kind: "program-start";
- readonly segmentId?: never;
- readonly tokenId?: never;
- }
- | {
- readonly id: "program:end";
- readonly kind: "program-end";
- readonly segmentId?: never;
+ readonly id: string;
+ readonly kind: "segment-start" | "segment-end";
+ readonly segmentId: string;
readonly tokenId?: never;
}
| {
readonly id: string;
- readonly kind: "segment-start" | "token-start" | "token-end" | "segment-end";
+ readonly kind: "token-start" | "token-end";
readonly segmentId: string;
- readonly tokenId?: string;
+ readonly tokenId: string;
};
/** Complete authored content; local views are projections of this value. */
@@ -122,7 +69,6 @@ export type Narrative = {
readonly segments: readonly NarrativeSegment[];
readonly tokens: readonly NarrativeToken[];
readonly turns: readonly NarrativeTurn[];
- readonly caption: CaptionDocument;
readonly selections: readonly NarrativeSelection[];
readonly moments: readonly NarrativeMoment[];
readonly semanticIndex: {
diff --git a/packages/performance-studio/README.md b/packages/performance-studio/README.md
deleted file mode 100644
index 958ee551..00000000
--- a/packages/performance-studio/README.md
+++ /dev/null
@@ -1,25 +0,0 @@
-# Performance Studio Companion
-
-The Companion contributes one Performance Track with a content area and an internal Uses band:
-
-- **Performance** shows the Timeline's placed picture Takes, with source thumbnails. These are available contents, independent of which Use presents or hides them. Audio-only Takes have no picture item.
-- **Uses** shows each authored Style application as a named interval in the bottom label band. Declaration order sets overlap order; selecting an item raises it for editing without changing the authored priority. Covered and empty applications remain available.
-
-`performance:Track.program` exports the ordered windows and unresolved visuals. The Companion reads that value instead of reconstructing author rules from the final visibility masks. The Timeline supplies the content lane. Typed temporal values identify each Use's exact author element even when its id was omitted.
-
-One Performance label spans the content and Uses band; selection targets a picture Take or a Use.
-A Take shows its Segment and placed frame range. A Use shows its resolved range and Style reference.
-These are small read-only facts within When and How, alongside the editable fields in the same domains.
-The displayed range uses an exclusive end frame.
-
-Selecting a Use exposes its ordinary Style's referenced Frame and Media appearance Recipe. Frame edits write to SVML; appearance edits write to SVS. A shared Style or Recipe remains shared. Temporal gestures follow the same Selection/Moment/clock projection and source-writeback path as other components.
-
-Project Styles receive the same Use interval and title. Their parameters are contributed through `createStudioCompanionHostFacet({ parameters })`, matching
-the Style's own Module and Surface. The Track opts its `style` reference into this declaration.
-Ordinary Style fields live in their own parameter Companion. See the project
-[performance Styles](../../examples/semantic-composition/packages/performance-styles/README.md) for an example.
-
-The internal `bands`, field bindings and content chrome are public Studio Companion declarations. Uses are entities in the same Track; independent child Tracks still use `attachments`. Studio does not recognize Performance names or scene-specific layouts. Caption and Sound can describe their own content and applications through the same interface.
-
-Use picture selection follows exact rendered Present ids supplied by Performance. Take content uses
-its Segment identity rather than array position, so reordering Takes preserves selection identity.
diff --git a/packages/performance-studio/package.json b/packages/performance-studio/package.json
deleted file mode 100644
index 5c086166..00000000
--- a/packages/performance-studio/package.json
+++ /dev/null
@@ -1,21 +0,0 @@
-{
- "name": "@hypit/performance-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/performance": "workspace:*",
- "@hypit/timeline": "workspace:*",
- "@hypit/temporal": "workspace:*",
- "@hypit/composition": "workspace:*",
- "@hypit/studio-adapter": "workspace:*",
- "@hypit/media-track-studio": "workspace:*"
- }
-}
diff --git a/packages/performance-studio/src/activation.ts b/packages/performance-studio/src/activation.ts
deleted file mode 100644
index 9f144954..00000000
--- a/packages/performance-studio/src/activation.ts
+++ /dev/null
@@ -1,6 +0,0 @@
-import { createStudioCompanionHostFacet } from "@hypit/studio-adapter";
-import { performanceStudioTrackCompanions, performanceStudioParameterCompanions } from "./index.js";
-export default {
- format: "hypit.node-package@1" as const,
- hostFacets: [createStudioCompanionHostFacet({ tracks: performanceStudioTrackCompanions, parameters: performanceStudioParameterCompanions })],
-};
diff --git a/packages/performance-studio/src/index.ts b/packages/performance-studio/src/index.ts
deleted file mode 100644
index 4ae1d1c8..00000000
--- a/packages/performance-studio/src/index.ts
+++ /dev/null
@@ -1,84 +0,0 @@
-import { performanceModuleRef, performancePresentId } from "@hypit/performance";
-import type { PerformanceSet } from "@hypit/performance";
-import { projectTimelineMedia, timelineTypes } from "@hypit/timeline";
-import type { Timeline } from "@hypit/timeline";
-import { temporalTypes } from "@hypit/temporal";
-import { compositionTypes } from "@hypit/composition";
-import { mediaAppearanceStudioFields } from "@hypit/media-track-studio";
-import { artifactPreview, authoredChildFor, previewLayer, requiredReferencedValue, requiredSurfaceValue, temporalLineageFor, temporalSemanticSource } from "@hypit/studio-adapter";
-import type { StudioTrackCompanion, StudioTrackCompanionContext, StudioEntityDraft, StudioSourceBindingDeclaration } from "@hypit/studio-adapter";
-
-const frameFields = ["left", "top", "right", "bottom", "x", "y", "width", "height"];
-const frameBindings: readonly StudioSourceBindingDeclaration[] = frameFields.map(name => ({ name, writable: true }));
-// Ordinary Performance uses Timeline playback. The rest is the same Media appearance vocabulary.
-const playbackFields = new Set(["playback", "trim-start", "trim-end"]);
-const appearanceBindings = mediaAppearanceStudioFields.bindings.filter(field => !playbackFields.has(field.name));
-const appearanceInspector = mediaAppearanceStudioFields.inspector.filter(field =>
- !playbackFields.has(field.binding.slice("appearance.".length)));
-
-export function projectPerformance(context: StudioTrackCompanionContext): readonly StudioEntityDraft[] {
- const timeline = requiredReferencedValue(context, "timeline", timelineTypes.track) as Timeline;
- const program = requiredSurfaceValue(context, "program") as PerformanceSet;
- // Source content keeps its own placement. A Use changes its presentation, not its media clock.
- const content: StudioEntityDraft[] = projectTimelineMedia(timeline).flatMap((clip, index) => {
- if (clip.media.visual === undefined) return [];
- return [{
- id: `${context.track.outputRef}:content:${clip.segmentId}`,
- authoredId: clip.segmentId,
- display: { title: clip.segmentId, layers: [previewLayer(artifactPreview("video", clip.media.visual.artifact.resource), "storyboard")] },
- ...clip.span, stackOrder: index,
- inspector: [
- { id: "segment", label: "Segment", domain: "how", section: { id: "content", label: "Content" }, value: clip.segmentId },
- { id: "range", label: "Range", domain: "when", section: { id: "placement", label: "Placement" }, value: `${clip.span.startFrame}–${clip.span.endFrameExclusive}`, unit: "f", summary: "Placed interval; the end frame is exclusive." },
- ],
- presentation: { entity: "performance-content", chrome: "standard" },
- }];
- });
- const uses: StudioEntityDraft[] = program.uses.map((use, index) => {
- const authoredId = use.window.subjectId;
- const child = authoredChildFor(context, authoredId, [temporalTypes.windowSpec]);
- if (child === undefined) throw new Error(`Performance Use ${authoredId} has no author provenance.`);
- const style = child.referenceAttributes.style;
- const temporal = temporalLineageFor(context, authoredId, "window");
- const semantic = temporalSemanticSource(temporal);
- return {
- id: `${context.track.outputRef}:use:${authoredId}`, authoredId,
- display: { title: style ?? authoredId, layers: [] },
- ...use.window.span, stackOrder: index,
- elementRange: child.range,
- ...(temporal === undefined ? {} : { temporal }),
- ...(semantic === undefined ? {} : { markerId: semantic.id }),
- presentation: { entity: "performance-use", chrome: "standard" },
- band: "uses",
- renderIds: use.visual.presents.map(present => performancePresentId(authoredId, present.id)),
- inspector: [{ id: "range", label: "Range", domain: "when", section: { id: "placement", label: "Placement" }, value: `${use.window.span.startFrame}–${use.window.span.endFrameExclusive}`, unit: "f", summary: "Resolved Use interval; the end frame is exclusive. Timeline gestures follow this Use's author timing." }],
- };
- });
- return [...content, ...uses];
-}
-
-export const performanceStudioTrackCompanions: readonly StudioTrackCompanion[] = [{
- id: "visual", role: "track",
- output: { type: compositionTypes.visualTrack, surface: "track", modules: [performanceModuleRef] },
- family: "performance", label: "Performance", tone: "blue", icon: "video",
- lane: { heightPx: 60 },
- requiredValues: ["program"],
- bands: [{
- id: "uses", placement: "after", heightPx: 15, display: "label",
- bindings: [{ name: "style", companion: true }],
- inspector: [{ binding: "style", label: "Style", domain: "how", section: { id: "style", label: "Style" }, control: "text", summary: "The referenced Style is shared by every Use that selects it." }],
- }],
- project: projectPerformance,
-}];
-
-export const performanceStudioParameterCompanions: readonly import("@hypit/studio-adapter").StudioParameterCompanion[] = [{
- id: "style", match: { module: performanceModuleRef, surface: "style" },
- bindings: [ { name: "frame", referenced: frameBindings },
- { name: "appearance", recipe: { bindings: appearanceBindings } } ],
- inspector: [
- ...frameFields.map(name => ({ binding: `frame.${name}`, label: name[0]!.toUpperCase() + name.slice(1),
- domain: "where" as const, page: { id: "frame", label: "Frame" }, section: { id: "placement", label: "Placement" },
- control: "number" as const, number: { suffixes: ["%", "px"], step: 1 } })),
- ...appearanceInspector,
- ],
-}];
diff --git a/packages/performance-studio/test/companion.test.ts b/packages/performance-studio/test/companion.test.ts
deleted file mode 100644
index 139d9da4..00000000
--- a/packages/performance-studio/test/companion.test.ts
+++ /dev/null
@@ -1,47 +0,0 @@
-import assert from "node:assert/strict";
-import test from "node:test";
-import { sealVisualTrack } from "@hypit/composition";
-import { temporalTypes } from "@hypit/temporal";
-import { timelineTypes } from "@hypit/timeline";
-import type { StudioTrackCompanionContext } from "@hypit/studio-adapter";
-import { projectPerformance } from "../src/index.js";
-import { timelineFixture } from "../../../test/timeline-fixture.js";
-import { projectProgramWindow } from "../../../test/temporal-fixture.js";
-
-const base = timelineFixture({ id: "film", durationSec: 6, frameRate: { numerator: 30, denominator: 1 } }, {
- segments: [{id:"first",frameCount:90},{id:"second",frameCount:90}],
-});
-function context(picture: boolean): StudioTrackCompanionContext {
- const timeline = {...base, items: base.items.map((item,index)=>({...item,startFrame:index ? 60:15,take:{...item.take,
- media:{...item.take.media,...(picture?{visual:{artifact:{kind:"blob",resource:`res_picture${index}`,mediaType:"video/mp4",size:1},width:64,height:64}}:{})},
- }}))};
- const program = {uses:["base","override","hidden"].map(id=>({
- window:projectProgramWindow({itemId:id,semantic:base,projection:{start:{ref:"absolute",at:{unit:"frames",value:0}},end:{ref:"absolute",at:{unit:"frames",value:180}}}}),
- visual:sealVisualTrack({id,programSpaceId:base.id,visualIr:"hypit.visual-ir@1",presents:[]}),
- }))};
- return {
- track:{outputRef:"p.visual",trace:{references:[{input:"timeline",typeRef:timelineTypes.track,ref:"film"}],outputPorts:[{name:"program",ref:"p.program"}]}},
- placement:{children:program.uses.map((use,index)=>({range:{start:index*10,end:index*10+5},referenceAttributes:{style:`styles.${use.window.subjectId}`},values:[{type:temporalTypes.windowSpec,value:{id:use.window.subjectId}}]}))},
- values:new Map<string,unknown>([["film",timeline],["p.program",program]]),spans:[],temporalBindings:[],
- } as unknown as StudioTrackCompanionContext;
-}
-
-test("Use band keeps fully overridden and empty rules with exact child and Style ownership",()=>{
- const uses=projectPerformance(context(false));
- assert.deepEqual(uses.map(use=>[use.display.title,use.band,use.elementRange]),[
- ["styles.base","uses",{start:0,end:5}],
- ["styles.override","uses",{start:10,end:15}],
- ["styles.hidden","uses",{start:20,end:25}],
- ]);
- assert.ok(uses.every(use=>use.presentation?.chrome==="standard"));
- assert.ok(uses.every(use=>use.inspector?.[0]?.value === "0–180"));
-});
-
-test("content follows placed picture Takes including gaps and overlaps; audio-only contributes no picture",()=>{
- const content=projectPerformance(context(true)).filter(entity=>entity.band===undefined);
- assert.deepEqual(content.map(entity=>[entity.authoredId,entity.startFrame,entity.endFrameExclusive]),[
- ["first",15,105],["second",60,150],
- ]);
- assert.deepEqual(content[0]?.inspector?.map(field=>field.value), ["first", "15–105"]);
- assert.equal(projectPerformance(context(false)).filter(entity=>entity.band===undefined).length,0);
-});
diff --git a/packages/performance/README.md b/packages/performance/README.md
deleted file mode 100644
index a3b65230..00000000
--- a/packages/performance/README.md
+++ /dev/null
@@ -1,83 +0,0 @@
-# Performance
-
-Performance presents footage already placed on a Timeline. Media Items receive independent assets;
-Performance Uses select how the existing footage appears. [Sound](../sound/README.md) presents existing audio. Include the wanted visual and audio outputs
-separately in Film.
-
-```svml
-<import as="performance" from="@hypit/performance@1"/>
-<performance:Style id="full" frame={layout.full} appearance={recipes.media.presenter}/>
-<performance:Style id="side" frame={layout.side} appearance={recipes.media.presenter}/>
-<performance:Track id="presenter" timeline={program.timeline} canvas={canvas}>
- <performance:Use style={full}/>
- <performance:Use during={story.selection.explanation} style={side}/>
-</performance:Track>
-```
-
-Select `presenter.visual` in Film. A Style's appearance uses Media fitting, clipping, radius, padding,
-border, shadows and sample appearance. `stack-order` places its Presents among Film contributions.
-A Use with no time selector covers the complete Timeline. Later Uses replace earlier rules locally;
-they do not add another copy of the picture. No matching Use means no picture. An empty winning
-Style stays empty. Separate Performance Tracks can independently show the same material.
-
-## Time, sources and visibility
-
-Use accepts shared `during`, `at` + `for`, `until` + `for`, or `start` + `end`. A Window says when a
-presentation applies. Timeline determines source positions: a Take placed at second 5 shows source
-second 2 at program second 7. Styles receive the original Use Window even when partially covered.
-Visibility does not restart playback or animation. The ordinary Style presents available videos in
-Timeline declaration order, later above earlier; no Takes, audio-only Takes and source gaps supply
-no picture. The Timeline can extend past all material without filling that time with a clip.
-
-Two independently bound endpoints can describe a physical overlap that is backwards in Script order:
-
-```svml
-<performance:Use style={mix}
- start-source={story.segment.next} start="segment.start"
- end-source={story.segment.previous} end="segment.end"/>
-```
-
-The concrete Style determines which sources are outgoing/incoming. Window endpoints do not select
-those roles implicitly. There is no automatic crossfade when source spans overlap.
-
-## Write a project Style
-
-`performanceStyle(fragment, bindings)` creates an authored Style. The fragment takes `timeline`,
-`canvas`, and `window`, plus any family-defined typed inputs, and exports `visual: VisualTrack`.
-`bindings` binds those extra inputs to resolved author references. A Style Surface returns this as
-an inline Record of `performanceTypes.style`. At each Use, the Track expands the fragment and turns
-every binding into a normal graph edge, including references to generated outputs. No family
-registry or effect-name dispatch is involved. The Style is an author-time definition, not a
-runtime-produced choice of executable code.
-
-```ts
-const style = performanceStyle(fragment, {
- from: resolveFrame("from"),
- to: resolveFrame("to"),
-});
-// Each value is a SurfaceResolvedReference; all fragment inputs except the three
-// occurrence inputs above must be bound. Your Surface owns its parameter names.
-```
-
-A family may bind Segment references, Moments, prepared assets, Frames, Recipes or computed outputs.
-Its Producers use the Timeline and shared projections to obtain exact source spans and event times.
-`projectTimelineMedia` returns zero, one or several sources with their identities and native source
-positions. Known sources without visual material differ from invalid references. Rendering can use
-ordinary structural elements, Media helpers or a browser program with HTML, CSS and frame code.
-`ordinaryPerformance` provides reusable fixed framing; a whole coordinated diagram/presenter scene
-can instead be an independent component.
-
-The [project Style example](../../examples/semantic-composition/packages/performance-styles/README.md)
-implements movement and two-source blending through these public interfaces. It demonstrates an
-extension path, not a required library of built-in transitions.
-
-## Implementation boundary
-
-`resolvePerformance` resolves last-declared Window coverage. It retains each Present's original
-`span` and intersects its optional `visibility` subranges with the winning intervals. The renderer
-uses `span` for animation and sampling and `visibility` only for display. Empty Uses still participate
-in coverage. Nothing in this package changes audio, Script, Timeline placement or generation.
-
-`Track.visual` is the resolved picture. `Track.program` retains the ordered Use windows and their
-unresolved VisualTracks, including covered and empty applications. The
-[Studio Companion](../performance-studio/README.md) uses this program to expose individual Uses.
diff --git a/packages/performance/src/activation.ts b/packages/performance/src/activation.ts
deleted file mode 100644
index 4be09bf7..00000000
--- a/packages/performance/src/activation.ts
+++ /dev/null
@@ -1,11 +0,0 @@
-import { createMarkupSurfaceHostFacet } from "@hypit/markup";
-import { performanceManifest, performanceModuleRef, performanceMarkupSurfaces } from "./manifest.js";
-import { performanceComponent } from "./component.js";
-import { decodePerformanceStyleSurface, decodePerformanceTrackSurface } from "./surface.js";
-export const hypitPackage = {
- format: "hypit.node-package@1" as const,
- modules: [{ manifest: performanceManifest }], components: [performanceComponent],
- hostFacets: performanceMarkupSurfaces.map(declaration => createMarkupSurfaceHostFacet({ module: performanceModuleRef, declaration,
- handler: declaration.name === "style" ? decodePerformanceStyleSurface : decodePerformanceTrackSurface })),
-};
-export default hypitPackage;
diff --git a/packages/performance/src/component.ts b/packages/performance/src/component.ts
deleted file mode 100644
index 64722e16..00000000
--- a/packages/performance/src/component.ts
+++ /dev/null
@@ -1,46 +0,0 @@
-import { canonicalize } from "@hypit/protocol";
-import type { StoredValue } from "@hypit/protocol";
-import type { ComponentPackage } from "@hypit/component-kit";
-import type { Timeline } from "@hypit/timeline";
-import { sealVisualTrack } from "@hypit/composition";
-import type { VisualTrack } from "@hypit/composition";
-import type { CanvasSpace, SpatialFrame, ContentFit } from "@hypit/spatial";
-import type { TemporalWindow } from "@hypit/temporal";
-import { createMediaLayerSet, createMediaSoundSet, createMediaTrackSet, finalizeMediaTrack, projectMediaVisualTrack } from "@hypit/media-track";
-import type { MediaItemSpec, MediaSampleLayerSpec } from "@hypit/media-track";
-import { appendMediaPerformance } from "./media.js";
-import { appendPerformanceUse, resolvePerformance } from "./program.js";
-import type { PerformanceSet } from "./program.js";
-import { performanceProducers } from "./manifest.js";
-
-function inline<T>(value: StoredValue | undefined): T {
- if (value?.kind !== "inline") throw new Error("Performance input must be inline.");
- return value.value as unknown as T;
-}
-const output = (value: unknown) => ({ kind: "inline" as const, value: canonicalize(value) });
-export function ordinaryPerformance(input: {
- timeline: Timeline; canvas: CanvasSpace; window: TemporalWindow; frame: SpatialFrame;
- fit: ContentFit; sample: MediaSampleLayerSpec; spec: MediaItemSpec;
-}): VisualTrack {
- const id = input.window.subjectId;
- const header = { id };
- const set = appendMediaPerformance({ ...input, header, set: createMediaTrackSet(), layers: createMediaLayerSet(),
- sounds: createMediaSoundSet(), spec: { ...input.spec, id } }, input.fit, input.sample);
- if (set.items.length === 0) return sealVisualTrack({ id, programSpaceId: input.timeline.id, visualIr: "hypit.visual-ir@1", presents: [] });
- return projectMediaVisualTrack(input.timeline, finalizeMediaTrack(set, header, input.timeline));
-}
-export const performanceComponent: ComponentPackage = {
- producers: [
- { producer: performanceProducers.create, handler: () => ({ outputs: { set: output({ uses: [] }) }, needs: {} }) },
- { producer: performanceProducers.append, handler: ({ inputs }) => ({ outputs: { set: output(appendPerformanceUse(
- inline<PerformanceSet>(inputs.set?.value), inline<TemporalWindow>(inputs.window?.value), inline<VisualTrack>(inputs.visual?.value),
- )) }, needs: {} }) },
- { producer: performanceProducers.resolve, handler: ({ inputs }) => ({ outputs: { visual: output(resolvePerformance(
- inline<Timeline>(inputs.timeline?.value), inline<{ id: string }>(inputs.header?.value).id, inline<PerformanceSet>(inputs.set?.value),
- )) }, needs: {} }) },
- { producer: performanceProducers.ordinary, handler: ({ inputs }) => ({ outputs: { visual: output(ordinaryPerformance({
- timeline: inline(inputs.timeline?.value), canvas: inline(inputs.canvas?.value), window: inline(inputs.window?.value),
- frame: inline(inputs.frame?.value), fit: inline(inputs.fit?.value), sample: inline(inputs.sample?.value), spec: inline(inputs.spec?.value),
- })) }, needs: {} }) },
- ],
-};
diff --git a/packages/performance/src/index.ts b/packages/performance/src/index.ts
deleted file mode 100644
index cae602fd..00000000
--- a/packages/performance/src/index.ts
+++ /dev/null
@@ -1,6 +0,0 @@
-export * from "./style.js";
-export * from "./program.js";
-export * from "./component.js";
-export * from "./surface.js";
-export * from "./manifest.js";
-export { appendMediaPerformance } from "./media.js";
diff --git a/packages/performance/src/manifest.ts b/packages/performance/src/manifest.ts
deleted file mode 100644
index e0018bf1..00000000
--- a/packages/performance/src/manifest.ts
+++ /dev/null
@@ -1,53 +0,0 @@
-import { compositionDependency, compositionTypes } from "@hypit/composition";
-import { timelineDependency, timelineTypes } from "@hypit/timeline";
-import { spatialDependency, spatialTypes } from "@hypit/spatial";
-import { temporalDependency, temporalTypes } from "@hypit/temporal";
-import { mediaTrackDependency, mediaTrackTypes } from "@hypit/media-track";
-import { svsRecipeType } from "@hypit/svs";
-import { temporalWindowAttributeVocabulary } from "@hypit/temporal-markup";
-import type { ModuleManifest, ProducerRef, TypeRef } from "@hypit/protocol";
-
-export const performanceModuleRef = { name: "@hypit/performance", version: "1" } as const;
-export const performanceTypes = Object.fromEntries(["Style", "Set", "Header"].map(name => [name.toLowerCase(), { module: performanceModuleRef, name: `Performance${name}` }])) as Record<"style" | "set" | "header", TypeRef>;
-export const performanceProducers = Object.fromEntries(["create", "append", "resolve", "ordinary"].map(name => [name, { module: performanceModuleRef, name }])) as Record<"create" | "append" | "resolve" | "ordinary", ProducerRef>;
-export const ordinaryInputs = [
- { name: "timeline", type: timelineTypes.track }, { name: "canvas", type: spatialTypes.canvas },
- { name: "window", type: temporalTypes.window }, { name: "frame", type: spatialTypes.frame },
- { name: "fit", type: spatialTypes.fit }, { name: "sample", type: mediaTrackTypes.sampleLayerSpec },
- { name: "spec", type: mediaTrackTypes.itemSpec },
-];
-export const performanceManifest: ModuleManifest = {
- format: "hypit.module@1", ...performanceModuleRef,
- dependencies: [compositionDependency, timelineDependency, spatialDependency, temporalDependency, mediaTrackDependency],
- types: Object.values(performanceTypes).map(type => ({ name: type.name })), capabilities: [],
- producers: [
- { name: "create", inputs: [], outputs: [{ name: "set", type: performanceTypes.set }], needs: [] },
- { name: "append", inputs: [{ name: "set", type: performanceTypes.set }, { name: "window", type: temporalTypes.window }, { name: "visual", type: compositionTypes.visualTrack }], outputs: [{ name: "set", type: performanceTypes.set }], needs: [] },
- { name: "resolve", inputs: [{ name: "set", type: performanceTypes.set }, { name: "timeline", type: timelineTypes.track }, { name: "header", type: performanceTypes.header }], outputs: [{ name: "visual", type: compositionTypes.visualTrack }], needs: [] },
- { name: "ordinary", inputs: ordinaryInputs, outputs: [{ name: "visual", type: compositionTypes.visualTrack }], needs: [] },
- ],
-};
-export const performanceMarkupSurfaces = [
- { name: "style", tag: "Style", mode: "structured", outputs: [performanceTypes.style, spatialTypes.fit, mediaTrackTypes.sampleLayerSpec, mediaTrackTypes.itemSpec], vocabulary: {
- summary: "Defines ordinary A-roll framing using Media appearance properties.",
- example: `<performance:Style id="full" frame={layout.full} appearance={recipes.media.presenter}/>`,
- attributes: [
- { name: "id", kind: "identifier", required: true, summary: "Style name." },
- { name: "frame", kind: "reference", required: true, accepts: [spatialTypes.frame], summary: "Destination Frame." },
- { name: "appearance", kind: "reference", required: true, accepts: [svsRecipeType], summary: "Media appearance Recipe: fitting, clipping, border and color." },
- ],
- } },
- { name: "track", tag: "Track", mode: "structured", outputs: [compositionTypes.visualTrack, performanceTypes.set, performanceTypes.header, temporalTypes.instantSpec, temporalTypes.windowSpec, temporalTypes.instant, temporalTypes.window], vocabulary: {
- summary: "Presents Timeline footage through ordered Use rules, retaining source playback time.",
- example: `<performance:Track id="presenter" timeline={program.timeline} canvas={canvas}><performance:Use style={full}/></performance:Track>`,
- attributes: [
- { name: "id", kind: "identifier", required: true, summary: "Presentation name." },
- { name: "timeline", kind: "reference", required: true, accepts: [timelineTypes.track], summary: "Placed material and film time." },
- { name: "canvas", kind: "reference", required: true, accepts: [spatialTypes.canvas], summary: "Composition Canvas." },
- ], children: [{ tag: "Use", cardinality: "many", summary: "Last matching Use wins. No time selector means the whole Timeline.", attributes: [
- { name: "id", kind: "identifier", required: false, summary: "Optional occurrence identity." },
- { name: "style", kind: "reference", required: true, accepts: [performanceTypes.style], summary: "Ordinary or project-authored presentation Style." },
- ...temporalWindowAttributeVocabulary,
- ] }],
- } },
-] as const;
diff --git a/packages/performance/src/media.ts b/packages/performance/src/media.ts
deleted file mode 100644
index 8cdeec1c..00000000
--- a/packages/performance/src/media.ts
+++ /dev/null
@@ -1,36 +0,0 @@
-import { projectTimelineMedia } from "@hypit/timeline";
-import type { Timeline } from "@hypit/timeline";
-import type { ContentFit } from "@hypit/spatial";
-import { appendTimedMediaLayer, createMediaLayerSet } from "@hypit/media-track";
-import { appendMediaItem } from "@hypit/media-track";
-import type { MediaSampleLayerSpec } from "@hypit/media-track";
-
-type ItemArguments = Parameters<typeof appendMediaItem>;
-type PerformanceInput = {
- set: ItemArguments[0]; header: ItemArguments[1]; timeline: ItemArguments[2]; canvas: ItemArguments[3];
- layers: ItemArguments[4]; frame: ItemArguments[5]; spec: ItemArguments[6];
- sounds: ItemArguments[7]; window: ItemArguments[8];
-};
-
-/** One framed unit and lifecycle containing all selected performance spans. */
-export function appendMediaPerformance(input: PerformanceInput, fit: ContentFit, sample: MediaSampleLayerSpec) {
- const layers = [...input.layers.layers];
- for (const clip of projectTimelineMedia(input.timeline, input.window.span)) {
- if (clip.media.visual === undefined) continue;
- const [layer] = appendTimedMediaLayer(createMediaLayerSet(), clip.media, fit, {
- ...sample, id: `${input.spec.id}:${clip.segmentId}`, trim: clip.source, occupancy: { mode: "once", align: "start" },
- }).layers;
- if (layer?.kind !== "sample") throw new Error("Performance media did not produce a sample.");
- layers.push({ ...layer, sampling: {
- sourceFrameRate: clip.media.timeline.frameRate,
- sourceFrameCount: clip.media.timeline.frameCount,
- segments: [{ target: {
- startFrame: clip.span.startFrame - input.window.span.startFrame,
- endFrameExclusive: clip.span.endFrameExclusive - input.window.span.startFrame,
- }, sourceFrame: { numerator: clip.source.startFrame, denominator: 1 }, rate: { numerator: 1, denominator: 1 } }],
- } });
- }
- if (layers.length === 0) return input.set;
- return appendMediaItem(input.set, input.header, input.timeline, input.canvas, { layers }, input.frame,
- input.spec, input.sounds, input.window);
-}
diff --git a/packages/performance/src/program.ts b/packages/performance/src/program.ts
deleted file mode 100644
index 82baf843..00000000
--- a/packages/performance/src/program.ts
+++ /dev/null
@@ -1,51 +0,0 @@
-import { sealVisualTrack, assertVisualTrackIdentity } from "@hypit/composition";
-import type { FrameSpan, VisualTrack } from "@hypit/composition";
-import { assertTemporalWindowFor } from "@hypit/temporal";
-import type { TemporalWindow } from "@hypit/temporal";
-import type { Timeline } from "@hypit/timeline";
-import { VISUAL_IR_V1 } from "@hypit/visual-ir";
-
-export type PerformanceUse = { readonly window: TemporalWindow; readonly visual: VisualTrack };
-export type PerformanceSet = { readonly uses: readonly PerformanceUse[] };
-
-export function appendPerformanceUse(set: PerformanceSet, window: TemporalWindow, visual: VisualTrack): PerformanceSet {
- assertVisualTrackIdentity(visual);
- if (visual.programSpaceId !== window.start.source.spaceId) throw new Error("Performance Use and picture belong to different Timelines.");
- return { uses: [...set.uses, { window, visual }] };
-}
-
-export function intersectVisibility(left: readonly FrameSpan[], right: readonly FrameSpan[]): FrameSpan[] {
- return left.flatMap(a => right.flatMap(b => {
- const startFrame = Math.max(a.startFrame, b.startFrame), endFrameExclusive = Math.min(a.endFrameExclusive, b.endFrameExclusive);
- return endFrameExclusive > startFrame ? [{ startFrame, endFrameExclusive }] : [];
- }));
-}
-
-export function performancePresentId(useId: string, presentId: string): string {
- return `${useId}:${presentId}`;
-}
-
-/** Keep original animation/sample origins. Only the visibility mask changes. */
-export function resolvePerformance(timeline: Timeline, id: string, set: PerformanceSet): VisualTrack {
- const presents: VisualTrack["presents"][number][] = [];
- for (const [index, use] of set.uses.entries()) {
- assertTemporalWindowFor(use.window, { subjectId: use.window.subjectId, space: timeline });
- if (use.visual.programSpaceId !== timeline.id || use.window.start.source.spaceId !== timeline.id) throw new Error("Performance uses another Timeline.");
- let visible = [use.window.span];
- for (const later of set.uses.slice(index + 1)) {
- visible = visible.flatMap(span => {
- const cut = later.window.span;
- if (cut.endFrameExclusive <= span.startFrame || cut.startFrame >= span.endFrameExclusive) return [span];
- return [
- ...(cut.startFrame > span.startFrame ? [{ startFrame: span.startFrame, endFrameExclusive: cut.startFrame }] : []),
- ...(cut.endFrameExclusive < span.endFrameExclusive ? [{ startFrame: cut.endFrameExclusive, endFrameExclusive: span.endFrameExclusive }] : []),
- ];
- });
- }
- for (const present of use.visual.presents) {
- const visibility = intersectVisibility(visible, present.visibility ?? [present.span]);
- if (visibility.length) presents.push({ ...present, id: performancePresentId(use.window.subjectId, present.id), visibility });
- }
- }
- return sealVisualTrack({ id, programSpaceId: timeline.id, visualIr: VISUAL_IR_V1, presents });
-}
diff --git a/packages/performance/src/style.ts b/packages/performance/src/style.ts
deleted file mode 100644
index cf7863cd..00000000
--- a/packages/performance/src/style.ts
+++ /dev/null
@@ -1,35 +0,0 @@
-import { sealGraphFragment } from "@hypit/elaborator";
-import type { GraphFragment } from "@hypit/elaborator";
-import { compositionTypes } from "@hypit/composition";
-import { timelineTypes } from "@hypit/timeline";
-import { spatialTypes } from "@hypit/spatial";
-import { temporalTypes } from "@hypit/temporal";
-import { sameType } from "@hypit/protocol";
-import type { SurfaceResolvedReference } from "@hypit/markup";
-
-/** Author-time closure: bound references become ordinary graph edges at each Use. */
-export type PerformanceStyle = {
- readonly fragment: GraphFragment;
- readonly bindings: Readonly<Record<string, { readonly type: SurfaceResolvedReference["type"]; readonly ref: SurfaceResolvedReference["ref"] }>>;
-};
-export function performanceStyle(fragment: GraphFragment, bindings: PerformanceStyle["bindings"] = {}): PerformanceStyle {
- fragment = sealGraphFragment(fragment);
- const common = { timeline: timelineTypes.track, canvas: spatialTypes.canvas, window: temporalTypes.window };
- for (const [name, type] of Object.entries(common)) {
- const port = fragment.inputs.find(port => port.name === name);
- if (port === undefined || !sameType(port.type, type)) throw new Error(`Performance Style requires ${name} input.`);
- if (bindings[name] !== undefined) throw new Error(`Performance supplies ${name} at each Use.`);
- }
- for (const port of fragment.inputs) {
- if (port.name in common) continue;
- const binding = bindings[port.name];
- if (binding === undefined || !sameType(port.type, binding.type)) throw new Error(`Performance Style binding ${port.name} has the wrong Type.`);
- }
- for (const name of Object.keys(bindings)) {
- if (!fragment.inputs.some(port => port.name === name)) throw new Error(`Performance Style has unknown binding ${name}.`);
- }
- if (fragment.exports.length !== 1 || fragment.exports[0]?.name !== "visual" || !sameType(fragment.exports[0].type, compositionTypes.visualTrack)) {
- throw new Error("Performance Style must export visual: VisualTrack.");
- }
- return { fragment, bindings: Object.fromEntries(Object.entries(bindings).map(([name, value]) => [name, { ref: value.ref, type: value.type }])) };
-}
diff --git a/packages/performance/src/surface.ts b/packages/performance/src/surface.ts
deleted file mode 100644
index 59545120..00000000
--- a/packages/performance/src/surface.ts
+++ /dev/null
@@ -1,99 +0,0 @@
-import { assertAttributes, assertEmptyElement, textAttribute, optionalTextAttribute } from "@hypit/markup";
-import type { StructuredSurfaceHandler, SurfaceResolvedReference, SurfaceRecordDraft, SurfaceComponentDraft, StructuredElement } from "@hypit/markup";
-import { canonicalize, sameType } from "@hypit/protocol";
-import type { TypeRef } from "@hypit/protocol";
-import { sealGraphFragment } from "@hypit/elaborator";
-import type { FragmentOperation } from "@hypit/elaborator";
-import { createTemporalWindowProjection, resolveTemporalContext, temporalWindowAttributeNames } from "@hypit/temporal-markup";
-import { temporalTypes } from "@hypit/temporal";
-import { compositionTypes } from "@hypit/composition";
-import { timelineTypes } from "@hypit/timeline";
-import { spatialTypes } from "@hypit/spatial";
-import { svsRecipeType } from "@hypit/svs";
-import type { SvsRecipe } from "@hypit/svs";
-import { decodeMediaFit, decodeMediaSampleSpec, decodeMediaItemSpec, mediaTrackTypes } from "@hypit/media-track";
-import { performanceStyle } from "./style.js";
-import type { PerformanceStyle } from "./style.js";
-import { performanceTypes, performanceProducers, ordinaryInputs } from "./manifest.js";
-
-const input = (name: string) => ({ kind: "fragment-input" as const, name });
-const operation = (id: string) => ({ kind: "fragment-operation" as const, operation: id });
-function reference(element: StructuredElement, name: string, type: TypeRef, resolve: (path: string) => SurfaceResolvedReference | undefined): SurfaceResolvedReference {
- const raw = element.attributes[name];
- if (typeof raw !== "object" || raw.kind !== "reference") throw new Error(`${element.name}.${name} must be a reference.`);
- const found = resolve(raw.path);
- if (found === undefined || !sameType(found.type, type)) throw new Error(`${element.name}.${name} has the wrong Type.`);
- return found;
-}
-function authored<T>(value: SurfaceResolvedReference): T {
- if (value.record?.value.kind !== "inline") throw new Error("A presentation Style or Recipe must be an authored inline value.");
- return value.record.value.value as unknown as T;
-}
-export const ordinaryPerformanceFragment = sealGraphFragment({
- inputs: ordinaryInputs,
- operations: [{ id: "ordinary", producer: performanceProducers.ordinary,
- inputs: Object.fromEntries(ordinaryInputs.map(port => [port.name, input(port.name)])), result: { kind: "output", name: "visual" } }],
- exports: [{ name: "visual", type: compositionTypes.visualTrack, root: operation("ordinary") }],
-});
-export const decodePerformanceStyleSurface: StructuredSurfaceHandler = ({ element, resolveReference }) => {
- assertAttributes(element, ["id", "frame", "appearance"]); assertEmptyElement(element);
- const id = textAttribute(element, "id");
- const frame = reference(element, "frame", spatialTypes.frame, resolveReference);
- const recipe = authored<SvsRecipe>(reference(element, "appearance", svsRecipeType, resolveReference));
- if (["playback", "trim-start", "trim-end"].some(key => recipe.properties[key] !== undefined)) throw new Error("Performance uses Timeline source positions; select its presentation interval on Use.");
- const records: SurfaceRecordDraft[] = [];
- const bind = (name: string, type: TypeRef, value: unknown) => {
- const recordId = `${id}.${name}`;
- records.push({ id: recordId, type, value: { kind: "inline", value: canonicalize(value) }, range: element.range });
- return { ref: { kind: "record" as const, id: recordId }, type };
- };
- const style = performanceStyle(ordinaryPerformanceFragment, {
- frame,
- fit: bind("fit", spatialTypes.fit, decodeMediaFit(recipe)),
- sample: bind("sample", mediaTrackTypes.sampleLayerSpec, decodeMediaSampleSpec(recipe, "content", "timed", undefined, true)),
- spec: bind("spec", mediaTrackTypes.itemSpec, decodeMediaItemSpec(recipe, { id, motion: { sustain: [] } })),
- });
- records.push({ id, type: performanceTypes.style, value: { kind: "inline", value: canonicalize(style) }, range: element.range });
- return { records, components: [], fragments: [] };
-};
-
-export const decodePerformanceTrackSurface: StructuredSurfaceHandler = ({ element, resolveReference }) => {
- assertAttributes(element, ["id", "timeline", "canvas"]);
- const id = textAttribute(element, "id"), context = resolveTemporalContext({ element, resolveReference });
- const canvas = reference(element, "canvas", spatialTypes.canvas, resolveReference);
- const records: SurfaceRecordDraft[] = [{ id: `${id}.header`, type: performanceTypes.header, value: { kind: "inline", value: { id } }, range: element.range }];
- const components: SurfaceComponentDraft[] = [];
- const fragments = [] as ReturnType<typeof sealGraphFragment>[];
- const collectorInputs = [{ name: "timeline", type: timelineTypes.track }, { name: "header", type: performanceTypes.header }];
- const bindings: Record<string, SurfaceResolvedReference["ref"]> = { timeline: context.timeline.ref, header: { kind: "record", id: `${id}.header` } };
- const operations: FragmentOperation[] = [{ id: "empty", producer: performanceProducers.create, inputs: {}, result: { kind: "output", name: "set" } }];
- let previous = "empty", index = 0;
- for (const child of element.children) {
- if (child.kind === "text") { if (child.value.trim()) throw new Error("Performance Track accepts Use children."); continue; }
- if (child.name.split(":").at(-1) !== "Use") throw new Error("Performance Track accepts Use children.");
- assertAttributes(child, ["id", "style", ...temporalWindowAttributeNames]); assertEmptyElement(child);
- const useId = optionalTextAttribute(child, "id") ?? `${id}.use.${index + 1}`;
- index += 1;
- const hasTime = temporalWindowAttributeNames.some(name => child.attributes[name] !== undefined);
- const temporal = createTemporalWindowProjection({ id: useId, ...context, resolveReference,
- element: hasTime ? child : { ...child, attributes: { ...child.attributes, during: "program" } } });
- records.push(...temporal.records); components.push(...temporal.components); fragments.push(...temporal.fragments);
- const value = authored<PerformanceStyle>(reference(child, "style", performanceTypes.style, resolveReference));
- const style = performanceStyle(value.fragment, value.bindings);
- fragments.push(style.fragment);
- const visualId = `${useId}.visual`;
- components.push({ id: `${useId}.__style`, fragment: style.fragment.id,
- inputs: { ...Object.fromEntries(Object.entries(style.bindings).map(([key, bound]) => [key, bound.ref])),
- timeline: context.timeline.ref, canvas: canvas.ref, window: temporal.ref }, outputs: { visual: visualId }, range: child.range });
- const suffix = `use-${operations.length}`;
- collectorInputs.push({ name: `${suffix}-window`, type: temporalTypes.window }, { name: `${suffix}-visual`, type: compositionTypes.visualTrack });
- bindings[`${suffix}-window`] = temporal.ref; bindings[`${suffix}-visual`] = { kind: "component-output", component: `${useId}.__style`, output: "visual" };
- operations.push({ id: suffix, producer: performanceProducers.append, inputs: { set: operation(previous), window: input(`${suffix}-window`), visual: input(`${suffix}-visual`) }, result: { kind: "output", name: "set" } });
- previous = suffix;
- }
- operations.push({ id: "resolve", producer: performanceProducers.resolve, inputs: { set: operation(previous), timeline: input("timeline"), header: input("header") }, result: { kind: "output", name: "visual" } });
- const collector = sealGraphFragment({ inputs: collectorInputs, operations, exports: [{ name: "visual", type: compositionTypes.visualTrack, root: operation("resolve") }, { name: "program", type: performanceTypes.set, root: operation(previous) }] });
- fragments.push(collector);
- components.push({ id, fragment: collector.id, inputs: bindings, outputs: { visual: `${id}.visual`, program: `${id}.program` }, range: element.range });
- return { records, components, fragments, exports: [`${id}.visual`, `${id}.program`] };
-};
diff --git a/packages/performance/test/performance.test.ts b/packages/performance/test/performance.test.ts
deleted file mode 100644
index fa4cabd9..00000000
--- a/packages/performance/test/performance.test.ts
+++ /dev/null
@@ -1,85 +0,0 @@
-import assert from "node:assert/strict";
-import test from "node:test";
-import { sealVisualTrack, sealComposition } from "@hypit/composition";
-import { compileHyperframesDocument } from "@hypit/hyperframes";
-import { resolvePerformance, appendPerformanceUse, ordinaryPerformance, performanceStyle, decodePerformanceTrackSurface } from "../src/index.js";
-import { timelineFixture } from "../../../test/timeline-fixture.js";
-import { projectProgramWindow } from "../../../test/temporal-fixture.js";
-import { decodeMediaItemSpec, decodeMediaSampleSpec, decodeMediaFit } from "@hypit/media-track";
-import type { Timeline } from "@hypit/timeline";
-import type { StructuredElement, SurfaceResolvedReference } from "@hypit/markup";
-import { timelineTypes } from "@hypit/timeline";
-import { spatialTypes } from "@hypit/spatial";
-import { performanceTypes } from "../src/manifest.js";
-import { ordinaryPerformanceFragment } from "../src/surface.js";
-import { mediaTrackTypes } from "@hypit/media-track";
-import { canonicalize } from "@hypit/protocol";
-import { movingFrame, crossfade } from "../../../examples/semantic-composition/packages/performance-styles/src/render.js";
-
-const timeline: Timeline = { id: "film", durationSec: 6, frameRate: { numerator: 30, denominator: 1 }, items: [] };
-const window = (id: string,start: number,end: number, source=timeline) => projectProgramWindow({ itemId: id, semantic: source,
- projection: { start: { ref: "absolute", at: { unit: "frames", value: start } }, end: { ref: "absolute", at: { unit: "frames", value: end } } } });
-const picture = (id: string,start=0,end=180) => sealVisualTrack({ id, visualIr: "hypit.visual-ir@1",programSpaceId: timeline.id,
- presents: [{ id,span: {startFrame:start,endFrameExclusive:end},stacking: {order:0,tieBreak:id},elements:[{id:"root",kind:"box",order:0,style:[{name:"background",value:"red"}]}] }] });
-const canvas = { widthPx: 64,heightPx:64, origin: "top-left", xDirection: "right", yDirection: "down", pixelAspect: "square" } as const;
-const frame = {xPx:0,yPx:0,widthPx:64,heightPx:64 };
-const recipe = { path: "look", properties: { "stack-order": 0, fit: "cover", clip:"frame" } };
-const ordinary = (source: Timeline) => ordinaryPerformance({ timeline:source,canvas,frame,window:window("use",0,180,source),
- fit:decodeMediaFit(recipe),sample:decodeMediaSampleSpec(recipe,"content","timed",undefined,true),spec:decodeMediaItemSpec(recipe,{id:"template",motion:{sustain:[]}}) });
-
-test("Use overrides preserve original spans and an empty winner does not reveal earlier content", () => {
- let set = appendPerformanceUse({uses:[]},window("base",0,180),picture("base"));
- set = appendPerformanceUse(set,window("side",60,180),picture("side",60));
- set = appendPerformanceUse(set,window("move",60,90),picture("move",60,90));
- const empty = sealVisualTrack({id:"hidden",visualIr:"hypit.visual-ir@1",programSpaceId:timeline.id,presents:[]});
- set = appendPerformanceUse(set,window("hide",120,150),empty);
- const result = resolvePerformance(timeline,"presenter",set);
- assert.deepEqual(result.presents.map(p=>[p.span,p.visibility]),[
- [{startFrame:0,endFrameExclusive:180},[{startFrame:0,endFrameExclusive:60}]],
- [{startFrame:60,endFrameExclusive:90},[{startFrame:60,endFrameExclusive:90}]],
- [{startFrame:60,endFrameExclusive:180},[{startFrame:90,endFrameExclusive:120},{startFrame:150,endFrameExclusive:180}]],
- ]);
- const document = compileHyperframesDocument(sealComposition({id:"render",canvas:{width:64,height:64,clearColor:"#000000"},tracks:[result]}),timeline);
- assert.match(document.html,/data-hypit-visibility/);
- assert.match(document.html,/hf-seek/);
-});
-
-test("ordinary Performance supports no Takes, audio-only Takes, overlap and gaps without resampling origins", () => {
- assert.equal(ordinary(timeline).presents.length,0);
- const audio = timelineFixture(timeline,{segments:[{id:"a",frameCount:90},{id:"b",frameCount:90}]});
- assert.equal(ordinary(audio).presents.length,0);
- const source = { ...audio, items: audio.items.map((item,i)=>({...item,startFrame: i===0 ? 15:60,take:{...item.take,media:{...item.take.media,visual:{ artifact:{kind:"blob" as const,resource:`res_video${i}` as const,size:1,mediaType:"video/mp4"},width:64,height:64}}}})) };
- const result=ordinary(source);
- const videos=result.presents[0]!.elements.filter(e=>e.kind==="video");
- assert.equal(videos.length,2);
- assert.deepEqual(videos.map(v=>(v.kind === "video" ? v.sampling : undefined)?.segments[0]?.target),[{startFrame:15,endFrameExclusive:105},{startFrame:60,endFrameExclusive:150}]);
- assert.deepEqual(videos.map(v=>(v.kind === "video" ? v.sampling : undefined)?.segments[0]?.sourceFrame),[{numerator:0,denominator:1},{numerator:0,denominator:1}]);
- const excerpt=(id:string)=>({kind:"segment" as const,narrativeId:source.narrativeId,id,tokenStart:0,tokenEndExclusive:0});
- const mixed=crossfade(source,window("mix",60,105,source),excerpt("a"),excerpt("b"),frame);
- assert.equal(mixed.presents[0]!.elements.filter(e=>e.kind==="video").length,2);
- const move=movingFrame(source,window("move",30,120,source),frame,{...frame,xPx:32,widthPx:32});
- const doc=compileHyperframesDocument(sealComposition({id:"movement",canvas:{width:64,height:64,clearColor:"#000000"},tracks:[move]}),source);
- assert.match(doc.html,/source-0/);
- assert.match(doc.html,/viewport/);
- const single={...source,items:[source.items[0]!,{...source.items[1]!,take:audio.items[1]!.take}]};
- assert.equal(crossfade(single,window("mix",60,105,single),excerpt("a"),excerpt("b"),frame).presents[0]!.elements.filter(e=>e.kind==="video").length,1);
- assert.throws(()=>crossfade(source,window("mix",60,105,source),excerpt("missing"),excerpt("b"),frame),/Unknown/);
-});
-
-test("Style-bound inputs become explicit graph edges at each Use; a baseline needs no temporal selector", async () => {
- const reference=(id:string,type:SurfaceResolvedReference["type"]):SurfaceResolvedReference=>({path:id,type,ref:{kind:"record",id}});
- const bindings={frame:reference("frame",spatialTypes.frame),fit:reference("fit",spatialTypes.fit),sample:reference("sample",mediaTrackTypes.sampleLayerSpec),spec:reference("spec",mediaTrackTypes.itemSpec)};
- const style=performanceStyle(ordinaryPerformanceFragment,bindings);
- const refs = new Map<string, SurfaceResolvedReference>([
- ["timeline", reference("timeline",timelineTypes.track)],
- ["canvas", reference("canvas",spatialTypes.canvas)],
- ["style", { ...reference("style",performanceTypes.style), record: { id:"style", type:performanceTypes.style,
- value:{kind:"inline",value:canonicalize(style)} } }],
- ]);
- const range={source:"test.svml",start:0,end:1};
- const root:StructuredElement={kind:"element",name:"performance:Track",attributes:{id:"p",timeline:{kind:"reference",path:"timeline"},canvas:{kind:"reference",path:"canvas"}},range,children:[{kind:"element",name:"performance:Use",attributes:{style:{kind:"reference",path:"style"}},children:[],range}]};
- const result=await decodePerformanceTrackSurface({element:root,sourceName:"test.svml",resolveReference:path=>refs.get(path),resolveAsset:async()=>{throw new Error("unexpected");}});
- assert.equal(result.components.find(c=>c.id==="p.use.1.__style")?.inputs.frame?.kind,"record");
- assert.deepEqual(result.components.find(c=>c.id==="p.use.1.__style")?.inputs.frame,bindings.frame.ref);
- assert.deepEqual(result.components.at(-1)?.outputs,{visual:"p.visual",program:"p.program"});
-});
diff --git a/packages/program-space/README.md b/packages/program-space/README.md
deleted file mode 100644
index db249aee..00000000
--- a/packages/program-space/README.md
+++ /dev/null
@@ -1,11 +0,0 @@
-# `@hypit/program-space`
-
-`ProgramClock` supplies a positive rational frame rate before material exists. The `Clock` Surface
-publishes it for normalization and Timeline assembly; the same Clock Surface is available from
-`@hypit/timeline-author`.
-
-`ProgramSpace` is the lightweight physical range consumed by rendering: `id`, `durationSec` and
-`frameRate`. Its positive duration ends on an exact frame boundary. The Timeline projects this
-view, whether it contains speaking Takes, wordless media, gaps or no Takes at all. Authors declare
-that complete work through [Timeline](../timeline-author/README.md), then components obtain the
-range and any semantic evidence they need. The range itself carries no media or word table.
diff --git a/packages/program-space/package.json b/packages/program-space/package.json
deleted file mode 100644
index 34631238..00000000
--- a/packages/program-space/package.json
+++ /dev/null
@@ -1,17 +0,0 @@
-{
- "name": "@hypit/program-space",
- "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/markup": "workspace:*",
- "@hypit/protocol": "workspace:*"
- }
-}
diff --git a/packages/program-space/src/activation.ts b/packages/program-space/src/activation.ts
deleted file mode 100644
index d7511bb7..00000000
--- a/packages/program-space/src/activation.ts
+++ /dev/null
@@ -1,15 +0,0 @@
-import { createMarkupSurfaceHostFacet } from "@hypit/markup";
-
-import { decodeClockSurface } from "./surface.js";
-import { programSpaceManifest, programSpaceMarkupSurfaces, programSpaceModuleRef } from "./index.js";
-
-export const hypitPackage = {
- format: "hypit.node-package@1" as const,
- modules: [{ manifest: programSpaceManifest }],
- hostFacets: [createMarkupSurfaceHostFacet({
- module: programSpaceModuleRef,
- declaration: programSpaceMarkupSurfaces.find((item) => item.name === "clock")!,
- handler: decodeClockSurface,
- })],
-};
-export default hypitPackage;
diff --git a/packages/program-space/src/index.ts b/packages/program-space/src/index.ts
deleted file mode 100644
index da941a3d..00000000
--- a/packages/program-space/src/index.ts
+++ /dev/null
@@ -1,98 +0,0 @@
-import type { ModuleManifest, TypeRef, ValueSchema } from "@hypit/protocol";
-
-export type ProgramClock = {
- readonly frameRate: { readonly numerator: number; readonly denominator: number };
-};
-
-export type ProgramSpace = {
- /** Author-visible identity of this film time axis. */
- readonly id: string;
- readonly durationSec: number;
- readonly frameRate: { readonly numerator: number; readonly denominator: number };
-};
-
-export const programSpaceModuleRef = { name: "@hypit/program-space", version: "1" } as const;
-export const programSpaceTypes = {
- programSpace: { module: programSpaceModuleRef, name: "ProgramSpace" },
- clock: { module: programSpaceModuleRef, name: "ProgramClock" },
-} satisfies Record<string, TypeRef>;
-const number = { kind: "number", minimum: 0 } as const;
-const integer = { kind: "number", integer: true, minimum: 0 } as const;
-const string = { kind: "string", minLength: 1 } as const;
-export const programSpaceSchema: ValueSchema = {
- kind: "object",
- fields: {
- id: { schema: string },
- durationSec: { schema: number },
- frameRate: { schema: { kind: "object", fields: {
- numerator: { schema: integer }, denominator: { schema: integer },
- } } },
- },
-};
-export const programSpaceManifest: ModuleManifest = {
- format: "hypit.module@1", name: programSpaceModuleRef.name, version: programSpaceModuleRef.version,
- dependencies: [], types: [
- { name: programSpaceTypes.programSpace.name },
- { name: programSpaceTypes.clock.name },
- ],
- capabilities: [], producers: [],
-};
-export const programSpaceDependency = { module: programSpaceModuleRef } as const;
-export const programSpaceMarkupSurfaces = [
- { name: "clock", tag: "Clock", mode: "structured", outputs: [programSpaceTypes.clock] },
-] as const;
-
-export function sealProgramClock(value: ProgramClock): ProgramClock {
- assertProgramClockIdentity(value);
- return structuredClone(value);
-}
-
-export function assertProgramClockIdentity(clock: ProgramClock): void {
- const { numerator, denominator } = clock.frameRate;
- if (!Number.isSafeInteger(numerator) || numerator <= 0
- || !Number.isSafeInteger(denominator) || denominator <= 0) {
- throw new Error("ProgramClock is invalid.");
- }
-}
-
-export function sealProgramSpace(value: ProgramSpace): ProgramSpace { return structuredClone(value); }
-
-export function programSpaceFrameCount(programSpace: ProgramSpace): number {
- const frames = programSpace.durationSec * programSpace.frameRate.numerator / programSpace.frameRate.denominator;
- const rounded = Math.round(frames);
- if (!Number.isSafeInteger(rounded) || rounded < 1 || Math.abs(frames - rounded) > 1e-7) {
- throw new Error("ProgramSpace duration must end on an exact frame boundary.");
- }
- return rounded;
-}
-export function programSpaceSampleFrames(programSpace: ProgramSpace, sampleRate: number): number {
- const frames = programSpaceFrameCount(programSpace);
- return programFrameSampleBoundary(programSpace, frames, sampleRate);
-}
-export function programFrameSampleBoundary(
- programSpace: ProgramSpace,
- frame: number,
- sampleRate: number,
-): number {
- const frames = programSpaceFrameCount(programSpace);
- if (!Number.isSafeInteger(frame) || frame < 0 || frame > frames) {
- throw new Error("ProgramSpace frame boundary is invalid.");
- }
- if (!Number.isSafeInteger(sampleRate) || sampleRate <= 0) throw new Error("ProgramSpace sample rate is invalid.");
- const numerator = BigInt(frame) * BigInt(sampleRate) * BigInt(programSpace.frameRate.denominator);
- const denominator = BigInt(programSpace.frameRate.numerator);
- const value = (numerator * 2n + denominator) / (denominator * 2n);
- if (value < 0n || value > BigInt(Number.MAX_SAFE_INTEGER)) throw new Error("ProgramSpace sample domain exceeds safe arithmetic.");
- return Number(value);
-}
-export function assertProgramSpaceIdentity(programSpace: ProgramSpace): void {
- const { numerator, denominator } = programSpace.frameRate;
- if (!programSpace.id.trim()
- || !Number.isSafeInteger(numerator) || numerator <= 0 || !Number.isSafeInteger(denominator)
- || denominator <= 0 || !Number.isFinite(programSpace.durationSec) || programSpace.durationSec <= 0) {
- throw new Error("ProgramSpace is invalid.");
- }
- programSpaceFrameCount(programSpace);
-}
-
-export { decodeClockSurface } from "./surface.js";
diff --git a/packages/program-space/src/surface.ts b/packages/program-space/src/surface.ts
deleted file mode 100644
index 3f0e3999..00000000
--- a/packages/program-space/src/surface.ts
+++ /dev/null
@@ -1,36 +0,0 @@
-import {
- assertEmptyElement as empty,
- textAttribute as text,
- type StructuredElement,
- type StructuredSurfaceHandler,
-} from "@hypit/markup";
-
-import { programSpaceTypes, sealProgramClock, type ProgramClock } from "./index.js";
-
-function frameRate(element: StructuredElement): ProgramClock["frameRate"] {
- const value = text(element, "frame-rate");
- const match = /^(\d+)(?:\/(\d+))?$/u.exec(value);
- if (match === null) throw new Error(`${element.name}.frame-rate must be a positive rational such as 30 or 30000/1001.`);
- const numerator = Number(match[1]);
- const denominator = Number(match[2] ?? "1");
- if (!Number.isSafeInteger(numerator) || numerator < 1
- || !Number.isSafeInteger(denominator) || denominator < 1) {
- throw new Error(`${element.name}.frame-rate is invalid.`);
- }
- return { numerator, denominator };
-}
-
-export const decodeClockSurface: StructuredSurfaceHandler = ({ element }) => {
- const expected = ["frame-rate", "id"];
- if (Object.keys(element.attributes).sort().join("\0") !== expected.join("\0")) {
- throw new Error(`${element.name} requires exactly id and frame-rate.`);
- }
- empty(element);
- const id = text(element, "id");
- const clock = sealProgramClock({ frameRate: frameRate(element) });
- return {
- records: [{ id, type: programSpaceTypes.clock, value: { kind: "inline", value: clock }, range: element.range }],
- components: [],
- fragments: [],
- };
-};
diff --git a/packages/provider-hyperframes-local/package.json b/packages/provider-hyperframes-local/package.json
index bc608808..e14bd8f1 100644
--- a/packages/provider-hyperframes-local/package.json
+++ b/packages/provider-hyperframes-local/package.json
@@ -39,6 +39,6 @@
"devDependencies": {
"@hypit/composition": "workspace:*",
"@hypit/driver-node": "workspace:*",
- "@hypit/program-space": "workspace:*"
+ "@hypit/timeline": "workspace:*"
}
}
diff --git a/packages/provider-hyperframes-local/src/sampling.ts b/packages/provider-hyperframes-local/src/sampling.ts
index c9ce684d..e3721fa1 100644
--- a/packages/provider-hyperframes-local/src/sampling.ts
+++ b/packages/provider-hyperframes-local/src/sampling.ts
@@ -30,8 +30,9 @@ export function requestedFrameRanges(range: MediaFrameRange, frames?: readonly n
return result;
}
-function rational(value: string, label: string): Rational {
- assert(/^\d+\/[1-9]\d*$/u.test(value), `HyperFrames ${label} must be a non-negative rational`);
+function rational(value: string, label: string, signed = false): Rational {
+ const pattern = signed ? /^-?\d+\/[1-9]\d*$/u : /^\d+\/[1-9]\d*$/u;
+ assert(pattern.test(value), `HyperFrames ${label} must be a ${signed ? "signed" : "non-negative"} rational`);
const [a, b] = value.split("/");
return { numerator: BigInt(a!), denominator: BigInt(b!) };
}
@@ -54,7 +55,7 @@ export function videoSlots(html: string): VideoSlot[] {
startFrame: Number(attribute("data-hypit-start-frame")),
endFrameExclusive: Number(attribute("data-hypit-end-frame")),
sourceFrame: rational(attribute("data-hypit-source-frame"), "source frame"),
- sourceRate: rational(attribute("data-hypit-source-rate"), "source rate"),
+ sourceRate: rational(attribute("data-hypit-source-rate"), "source rate", true),
sourceFps: { num: Number(sourceFps.numerator), den: Number(sourceFps.denominator) },
};
assert(Number.isSafeInteger(slot.startFrame) && slot.startFrame >= 0
@@ -90,7 +91,12 @@ export function sourceWindows(slots: readonly VideoSlot[], selection: MediaFrame
}
assert(source.fps.num * slot.sourceFps.den === slot.sourceFps.num * source.fps.den,
"One HyperFrames source has conflicting frame rates");
- source.windows.push({ startFrame: sourceFrameAt(slot, first), endFrameExclusive: sourceFrameAt(slot, last) + 1 });
+ const firstSource = sourceFrameAt(slot, first);
+ const lastSource = sourceFrameAt(slot, last);
+ source.windows.push({
+ startFrame: Math.min(firstSource, lastSource),
+ endFrameExclusive: Math.max(firstSource, lastSource) + 1,
+ });
}
return [...sources].map(([src, source]) => {
const windows: MediaFrameRange[] = [];
diff --git a/packages/provider-hyperframes-local/test/alpha.test.ts b/packages/provider-hyperframes-local/test/alpha.test.ts
index 8fe81f6d..c857a65b 100644
--- a/packages/provider-hyperframes-local/test/alpha.test.ts
+++ b/packages/provider-hyperframes-local/test/alpha.test.ts
@@ -1,4 +1,3 @@
-import { appendMediaPerformance } from "@hypit/performance";
import assert from "node:assert/strict";
import test from "node:test";
import { mkdir, mkdtemp, rm } from "node:fs/promises";
@@ -6,20 +5,16 @@ import { tmpdir } from "node:os";
import { join } from "node:path";
import { sealComposition } from "@hypit/composition";
import { compileHyperframesDocument } from "@hypit/hyperframes";
-import type { Narrative } from "@hypit/narrative";
-import { parseScript, narrativeValue } from "@hypit/script";
-import { materializeSemanticTake } from "@hypit/speech";
-import { appendTimelineAuthorTake, assembleTimelineAuthor, createTimelineAuthorSet,
- sealTimelineAuthorHeader } from "@hypit/timeline-author";
-import { projectTimelineSpace } from "@hypit/timeline";
-import { appendMediaItem, appendTimedMediaLayer, createMediaLayerSet, createMediaSoundSet, createMediaTrackSet,
- finalizeMediaTrack, projectMediaVisualTrack, sealMediaItemSpec, sealMediaSampleLayerSpec, sealMediaTrackHeader } from "@hypit/media-track";
+import { sealTimeline } from "@hypit/timeline";
+import { appendVisualClip, appendTimedMediaLayer, createMediaLayerSet, createVisualTrackSet,
+ finalizeVisualTrack, projectVisualTrack, sealVisualClipSpec, sealMediaSampleLayerSpec,
+ sealVisualTrackHeader } from "@hypit/visual-track";
import { projectProgramWindow } from "../../../test/temporal-fixture.js";
import { MemoryResourceStore, ffmpegBytes, normalizeTestVideo, transparentVideoFixture, writeTestArtifact } from "../../../test/alpha-video-fixture.js";
import sharp from "sharp";
import { renderHyperframesVisual, renderHyperframesFrames } from "../src/index.js";
-test("transparent normalized media composites through both SemanticTake/Timeline and Media Track in Chrome", {
+test("transparent normalized media composites through an explicit Visual Clip in Chrome", {
skip: process.env.HYPIT_BROWSER_TESTS !== "1",
}, async () => {
const directory = process.env.HYPIT_ALPHA_PROOF_DIR ?? await mkdtemp(join(tmpdir(), "hypit-alpha-render-"));
@@ -30,48 +25,33 @@ test("transparent normalized media composites through both SemanticTake/Timeline
const source = await resources.put(fixture.bytes, fixture.mediaType);
const media = await normalizeTestVideo(resources, source, true);
const broll = await normalizeTestVideo(resources, source, false);
- const narrative = narrativeValue(parseScript("alpha.svml", "<opening>Hello</opening>"), "story") as unknown as Narrative;
- const segment = narrative.segments[0]!;
- const token = narrative.tokens[0]!;
- // Known token timing isolates media preservation from remote speech recognition.
- const take = materializeSemanticTake(narrative,
- { narrativeId: narrative.id, kind: "segment", id: segment.id, tokenStart: 0, tokenEndExclusive: 1 }, media, {
- tokens: [{ tokenId: token.id, segmentId: segment.id, startFrame: 2, endFrameExclusive: 10 }],
- anchors: [
- { identity: segment.startAnchorId, frame: 0 }, { identity: segment.endAnchorId, frame: 12 },
- { identity: token.startAnchorId, frame: 2 }, { identity: token.endAnchorId, frame: 10 },
- ],
- });
- assert.deepEqual(take.media, media);
const fit = { sizing: "contain" as const, framePoint: { x: 0.5, y: 0.5 }, contentPoint: { x: 0.5, y: 0.5 },
offsetPx: { x: 0, y: 0 }, constraint: "bounded" as const };
const frame = { xPx: 0, yPx: 0, widthPx: 96, heightPx: 64 };
- const set = appendTimelineAuthorTake(createTimelineAuthorSet(), take);
- const semantic = assembleTimelineAuthor(sealTimelineAuthorHeader({ id: "speech" }), set, { frameRate: media.timeline.frameRate });
- const space = semantic;
- const header = sealMediaTrackHeader({ id: "broll" });
+ const space = sealTimeline({ id: "film", frameRate: media.frameDomain.frameRate, frameCount: media.frameDomain.frameCount });
+ const header = sealVisualTrackHeader({ id: "broll" });
const layers = appendTimedMediaLayer(createMediaLayerSet(), broll, fit, sealMediaSampleLayerSpec({ id: "cutout",
- occupancy: { mode: "once", align: "start" },
appearance: { opacity: 1, filter: { blurPx: 0, brightness: 1, contrast: 1, saturation: 1 } },
}));
- const spec = sealMediaItemSpec({ id: "broll-cutout", stackingOrder: 2, motion: { sustain: [] },
- presentation: { clip: { kind: "none" }, padding: { topPx: 0, rightPx: 0, bottomPx: 0, leftPx: 0 },
+ const spec = sealVisualClipSpec({ id: "broll-cutout", z: 2,
+ treatment: { clip: { kind: "none" }, padding: { topPx: 0, rightPx: 0, bottomPx: 0, leftPx: 0 },
border: { widthPx: 0, style: "solid", color: "#000000" }, shadows: [] } });
- const items = appendMediaItem(createMediaTrackSet(), header, space,
- { widthPx: 192, heightPx: 64, origin: "top-left", xDirection: "right", yDirection: "down", pixelAspect: "square" },
- layers, { ...frame, xPx: 96 }, spec, createMediaSoundSet(), projectProgramWindow({
- itemId: spec.id, semantic, projection: { start: { ref: "program.start" }, end: { ref: "program.end" } },
+ const items = appendVisualClip(createVisualTrackSet(), header, space,
+ layers, { ...frame, xPx: 96 }, spec, projectProgramWindow({
+ itemId: spec.id, semantic: space, projection: { start: { ref: "timeline.start" }, end: { ref: "timeline.end" } },
}));
- const performanceHeader = sealMediaTrackHeader({ id: "performance" });
- const performanceSpec = { ...spec, id: "performance", stackingOrder: 1 };
- const performance = appendMediaPerformance({ set: createMediaTrackSet(), header: performanceHeader, timeline: semantic,
- canvas: { widthPx: 192, heightPx: 64, origin: "top-left", xDirection: "right", yDirection: "down", pixelAspect: "square" },
- layers: createMediaLayerSet(), frame, spec: performanceSpec, sounds: createMediaSoundSet(),
- window: projectProgramWindow({ itemId: performanceSpec.id, semantic, projection: { start: { ref: "program.start" }, end: { ref: "program.end" } } }),
- }, fit, sealMediaSampleLayerSpec({ id: "content", occupancy: { mode: "once", align: "start" },
- appearance: { opacity: 1, filter: { blurPx: 0, brightness: 1, contrast: 1, saturation: 1 } } }));
- const speechVisual = projectMediaVisualTrack(space, finalizeMediaTrack(performance, performanceHeader, space));
- const brollVisual = projectMediaVisualTrack(space, finalizeMediaTrack(items, header, space));
+ const speechHeader = sealVisualTrackHeader({ id: "speech" });
+ const speechSpec = { ...spec, id: "speech", z: 1 };
+ const speechLayers = appendTimedMediaLayer(createMediaLayerSet(), media, fit, sealMediaSampleLayerSpec({
+ id: "content",
+ appearance: { opacity: 1, filter: { blurPx: 0, brightness: 1, contrast: 1, saturation: 1 } },
+ }));
+ const speechSet = appendVisualClip(createVisualTrackSet(), speechHeader, space,
+ speechLayers, frame, speechSpec,
+ projectProgramWindow({ itemId: speechSpec.id, semantic: space,
+ projection: { start: { ref: "timeline.start" }, end: { ref: "timeline.end" } } }));
+ const speechVisual = projectVisualTrack(space, finalizeVisualTrack(speechSet, speechHeader, space));
+ const brollVisual = projectVisualTrack(space, finalizeVisualTrack(items, header, space));
const document = compileHyperframesDocument(sealComposition({ id: "alpha-proof",
canvas: { width: 192, height: 64, clearColor: "#143cdc" }, tracks: [speechVisual, brollVisual] }), space);
const rendered = await renderHyperframesVisual({ document }, { resources, workers: 2, quality: "high", processTimeoutMs: 120_000 });
diff --git a/packages/provider-hyperframes-local/test/frames.test.ts b/packages/provider-hyperframes-local/test/frames.test.ts
index 153d608b..5e70b3f4 100644
--- a/packages/provider-hyperframes-local/test/frames.test.ts
+++ b/packages/provider-hyperframes-local/test/frames.test.ts
@@ -5,7 +5,7 @@ import { tmpdir } from "node:os";
import { join } from "node:path";
import sharp from "sharp";
import { sealComposition, sealVisualTrack } from "@hypit/composition";
-import { sealProgramSpace } from "@hypit/program-space";
+import { sealTimeline } from "@hypit/timeline";
import { browserProgram, compileHyperframesDocument, hyperframesHtmlDomain } from "@hypit/hyperframes";
import { stageHyperframesProject } from "@hypit/hyperframes/project";
import { verifyHyperframesFramesRequest } from "@hypit/render-hyperframes";
@@ -13,10 +13,10 @@ import { MemoryResourceStore } from "@hypit/driver-node";
import { renderHyperframesFrames } from "../src/index.js";
function fixture() {
- const space = sealProgramSpace({ id: "space", durationSec: 1, frameRate: { numerator: 12, denominator: 1 } });
+ const space = sealTimeline({ id: "space", frameCount: 12, frameRate: { numerator: 12, denominator: 1 } });
return compileHyperframesDocument(sealComposition({ id: "frames", canvas: { width: 96, height: 64, clearColor: "#000000" },
- tracks: [sealVisualTrack({ id: "motion", programSpaceId: space.id, visualIr: "hypit.visual-ir@1", presents: [{ id: "reveal",
- span: { startFrame: 3, endFrameExclusive: 12 }, stacking: { order: 0, tieBreak: "reveal" }, elements: [{ id: "program", order: 0,
+ tracks: [sealVisualTrack({ id: "motion", timelineId: space.id, visualIr: "hypit.visual-ir@1", presents: [{ id: "reveal",
+ order: 0, z: 0, span: { startFrame: 3, endFrameExclusive: 12 }, elements: [{ id: "program", order: 0,
kind: "program", style: [{ name: "position", value: "absolute" }, { name: "inset", value: 0 }],
program: browserProgram({ html: '<div class="box"></div>', css: '.box{position:absolute;top:0;width:8px;height:64px;background:#ff0000}',
setup: 'return frame => { root.querySelector(".box").style.left = `${frame * 8}px`; };' }),
diff --git a/packages/provider-hyperframes-local/test/performance.test.ts b/packages/provider-hyperframes-local/test/performance.test.ts
deleted file mode 100644
index 1dc8f9b4..00000000
--- a/packages/provider-hyperframes-local/test/performance.test.ts
+++ /dev/null
@@ -1,63 +0,0 @@
-import assert from "node:assert/strict";
-import test from "node:test";
-import { spawnSync } from "node:child_process";
-import { mkdtemp, readFile, writeFile, rm } from "node:fs/promises";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-import { MemoryResourceStore } from "@hypit/driver-node";
-import { sealComposition, sealVisualTrack } from "@hypit/composition";
-import { compileHyperframesDocument } from "@hypit/hyperframes";
-import { appendPerformanceUse, resolvePerformance } from "@hypit/performance";
-import { timelineFixture } from "../../../test/timeline-fixture.js";
-import { projectProgramWindow } from "../../../test/temporal-fixture.js";
-import { movingFrame, crossfade } from "../../../examples/semantic-composition/packages/performance-styles/src/render.js";
-import { renderHyperframesVisual } from "../src/index.js";
-
-test("project Performance Styles render movement, empty override, resumed playback, tail and two-source blending", {
- skip: process.env.HYPIT_BROWSER_TESTS !== "1",
-}, async () => {
- const root=await mkdtemp(join(tmpdir(),"hypit-performance-"));
- try {
- const resources=new MemoryResourceStore();
- const makeVideo=async(name:string,color:number[])=>{
- const path=join(root,`${name}.mp4`);
- const raw=Buffer.from(Array.from({length:8*64*64},()=>color).flat());
- const result=spawnSync("ffmpeg",["-v","error","-y","-f","rawvideo","-pix_fmt","rgb24","-s","64x64","-r","30","-i","pipe:0","-c:v","libx264","-crf","0","-pix_fmt","yuv420p",path],{input:raw});
- if(result.error)throw result.error;
- assert.equal(result.status,0,result.stderr?.toString());
- return resources.put(await readFile(path),"video/mp4");
- };
- const a=await makeVideo("red",[220,20,20]),b=await makeVideo("blue",[20,20,220]);
- const fixture=timelineFixture({id:"film",durationSec:16/30,frameRate:{numerator:30,denominator:1}},{segments:[{id:"a",frameCount:8},{id:"b",frameCount:8}]});
- const timeline={...fixture,durationSec:14/30,items:fixture.items.map((item,i)=>({...item,startFrame:i*4,take:{...item.take,media:{timeline:item.take.media.timeline,visual:{artifact:i===0?a:b,width:64,height:64}}}}))};
- const window=(id:string,start:number,end:number)=>projectProgramWindow({itemId:id,semantic:timeline,projection:{start:{ref:"absolute",at:{unit:"frames",value:start}},end:{ref:"absolute",at:{unit:"frames",value:end}}}});
- const full={xPx:0,yPx:0,widthPx:64,heightPx:64},side={...full,xPx:32,widthPx:32};
- const base=window("base",0,14),settled=window("side",4,14),move=window("move",4,8),hide=window("hide",8,9);
- let set=appendPerformanceUse({uses:[]},base,movingFrame(timeline,base,full,full));
- set=appendPerformanceUse(set,settled,movingFrame(timeline,settled,side,side));
- set=appendPerformanceUse(set,move,movingFrame(timeline,move,full,side));
- set=appendPerformanceUse(set,hide,sealVisualTrack({id:"hidden",programSpaceId:timeline.id,visualIr:"hypit.visual-ir@1",presents:[]}));
- const render=async(name:string,track:ReturnType<typeof resolvePerformance>)=>{
- const document=compileHyperframesDocument(sealComposition({id:name,canvas:{width:64,height:64,clearColor:"#000000"},tracks:[track]}),timeline);
- const video=await renderHyperframesVisual({document},{resources,workers:1,quality:"high",processTimeoutMs:120000});
- const file=join(root,`${name}.mp4`);await writeFile(file,(await resources.get(video.artifact.resource))!);
- const decoded=spawnSync("ffmpeg",["-v","error","-i",file,"-f","rawvideo","-pix_fmt","rgb24","pipe:1"]);
- if(decoded.error)throw decoded.error;
- assert.equal(decoded.status,0,decoded.stderr?.toString());return decoded.stdout;
- };
- const pixels=await render("move",resolvePerformance(timeline,"presenter",set));
- const pixel=(data:Buffer,f:number,x:number)=>[...data.subarray((f*64*64+32*64+x)*3,(f*64*64+32*64+x)*3+3)];
- assert.ok(pixel(pixels,2,16)[0]!>170,"initial full frame");
- assert.ok(pixel(pixels,7,16).every(c=>c<25),"moving view reaches right side");
- assert.ok(pixel(pixels,7,48)[2]!>170,"incoming footage remains visible");
- assert.ok(pixel(pixels,8,48).every(c=>c<25),"empty Use suppresses underlying rules");
- assert.ok(pixel(pixels,9,48)[2]!>170,"settled view resumes");
- assert.ok(pixel(pixels,12,48).every(c=>c<25),"tail requires no fabricated clip");
- const excerpt=(id:string)=>({kind:"segment" as const,narrativeId:fixture.narrativeId,id,tokenStart:0,tokenEndExclusive:0});
- const mix=crossfade(timeline,move,excerpt("a"),excerpt("b"),full);
- const blended=await render("mix",mix);
- assert.ok(pixel(blended,4,32)[0]!>170,"outgoing endpoint");
- assert.ok(pixel(blended,7,32)[2]!>170,"incoming endpoint");
- assert.ok(pixel(blended,5,32)[0]!>90 && pixel(blended,5,32)[2]!>40,"both sources contribute inside overlap");
- } finally { await rm(root,{recursive:true,force:true}); }
-});
diff --git a/packages/provider-hyperframes-local/test/provider.test.ts b/packages/provider-hyperframes-local/test/provider.test.ts
index 25f7d368..873e2a33 100644
--- a/packages/provider-hyperframes-local/test/provider.test.ts
+++ b/packages/provider-hyperframes-local/test/provider.test.ts
@@ -5,7 +5,7 @@ import { join } from "node:path";
import test from "node:test";
import { mediaTypes, verifyRenderedVisual } from "@hypit/media";
import type { CompositableSurfaceRef, RenderedVisual } from "@hypit/media";
-import { sealProgramSpace } from "@hypit/program-space";
+import { sealTimeline } from "@hypit/timeline";
import { sealComposition, sealVisualTrack } from "@hypit/composition";
import assert from "node:assert/strict";
import { MemoryResourceStore, EndpointRegistry } from "@hypit/driver-node";
@@ -53,16 +53,15 @@ test("an explicit browser renders without installing a managed replacement", { s
});
function documentFixture(surface?: CompositableSurfaceRef) {
- const programSpace = sealProgramSpace({ id: "test-space", durationSec: 1,
- frameRate: { numerator: 12, denominator: 1 },
+ const timeline = sealTimeline({ id: "test-space", frameCount: 12, frameRate: { numerator: 12, denominator: 1 },
});
- const track = sealVisualTrack({ programSpaceId: "test-space",
+ const track = sealVisualTrack({ timelineId: "test-space",
visualIr: "hypit.visual-ir@1",
id: "provider-fixture",
presents: [{
id: "card",
span: { startFrame: 0, endFrameExclusive: 12 },
- stacking: { order: 10, tieBreak: "card" },
+ order: 0, z: 10,
elements: [
{
id: "background",
@@ -95,7 +94,7 @@ function documentFixture(surface?: CompositableSurfaceRef) {
id: "local-hyperframes-provider-fixture",
canvas: { width: 160, height: 96, clearColor: "#000000" },
tracks: [track],
- }), programSpace);
+ }), timeline);
}
function requestNeed(document = documentFixture()): Need {
diff --git a/packages/provider-hyperframes-local/test/range.test.ts b/packages/provider-hyperframes-local/test/range.test.ts
index 467a3e55..1d966325 100644
--- a/packages/provider-hyperframes-local/test/range.test.ts
+++ b/packages/provider-hyperframes-local/test/range.test.ts
@@ -10,7 +10,7 @@ import { sealComposition, sealVisualTrack } from "@hypit/composition";
import { mediaFrameRangeSamples } from "@hypit/media";
import { EndpointRegistry, MemoryResourceStore } from "@hypit/driver-node";
import { compileHyperframesDocument } from "@hypit/hyperframes";
-import { sealProgramSpace } from "@hypit/program-space";
+import { sealTimeline } from "@hypit/timeline";
import type { BlobRef } from "@hypit/protocol";
import sharp from "sharp";
import { renderHyperframesVisual, renderHyperframesFrames } from "../src/index.js";
@@ -25,18 +25,18 @@ import type { HyperframesRenderProgress } from "../src/index.js";
import { distributeFrameRange, requestedFrameRanges, sourceFrameAt, sourceWindows, videoSlots } from "../src/sampling.js";
function documentFor(artifact: BlobRef) {
- const space = sealProgramSpace({ id: "range-space", durationSec: 12 / 30, frameRate: { numerator: 30, denominator: 1 } });
- const track = sealVisualTrack({ id: "video", visualIr: "hypit.visual-ir@1", programSpaceId: space.id,
+ const space = sealTimeline({ id: "range-space", frameCount: 12, frameRate: { numerator: 30, denominator: 1 } });
+ const track = sealVisualTrack({ id: "video", visualIr: "hypit.visual-ir@1", timelineId: space.id,
presents: [{ id: "sample", span: { startFrame: 0, endFrameExclusive: 12 },
- stacking: { order: 0, tieBreak: "sample" }, elements: [{ id: "video", order: 0, kind: "video", artifact,
+ order: 0, z: 0, elements: [{ id: "video", order: 0, kind: "video", artifact,
style: [{ name: "position", value: "absolute" }, { name: "inset", value: 0 },
{ name: "width", value: "64px" }, { name: "height", value: "64px" }],
- sampling: { sourceFrameRate: space.frameRate, sourceFrameCount: 4, segments: [
- { target: { startFrame: 0, endFrameExclusive: 6 }, sourceFrame: { numerator: 2, denominator: 1 },
- rate: { numerator: 1, denominator: 1 }, loop: { startFrame: 0, endFrameExclusive: 4 } },
- { target: { startFrame: 6, endFrameExclusive: 8 }, sourceFrame: { numerator: 3, denominator: 1 },
+ sourceTime: { sourceFrameRate: space.frameRate, sourceFrameCount: 4, pieces: [
+ { target: { startFrame: 0, endFrameExclusive: 6 }, sourceAtStart: { numerator: 2, denominator: 1 },
+ rate: { numerator: 1, denominator: 1 }, wrap: { startFrame: 0, endFrameExclusive: 4 } },
+ { target: { startFrame: 6, endFrameExclusive: 8 }, sourceAtStart: { numerator: 3, denominator: 1 },
rate: { numerator: 0, denominator: 1 } },
- { target: { startFrame: 8, endFrameExclusive: 12 }, sourceFrame: { numerator: 0, denominator: 1 },
+ { target: { startFrame: 8, endFrameExclusive: 12 }, sourceAtStart: { numerator: 0, denominator: 1 },
rate: { numerator: 1, denominator: 2 } },
] },
}] }],
@@ -88,9 +88,9 @@ test("source selection retains loop, hold and fractional-speed sampling and shar
const hold = slots.find((slot) => slot.sourceRate.numerator === 0n);
assert.ok(hold !== undefined);
assert.deepEqual({ startFrame: hold.startFrame, endFrameExclusive: hold.endFrameExclusive,
- sourceFrame: hold.sourceFrame, sourceRate: hold.sourceRate }, {
+ sourceAtStart: hold.sourceFrame, sourceRate: hold.sourceRate }, {
startFrame: 6, endFrameExclusive: 8,
- sourceFrame: { numerator: 3n, denominator: 1n }, sourceRate: { numerator: 0n, denominator: 1n },
+ sourceAtStart: { numerator: 3n, denominator: 1n }, sourceRate: { numerator: 0n, denominator: 1n },
});
const range = { startFrame: 3, endFrameExclusive: 11 };
const sampled = Array.from({ length: 8 }, (_, i) => {
@@ -118,6 +118,15 @@ test("video slot inspection accepts direct HTML sources without requiring compil
});
});
+test("reverse source time selects the same bounded decoded window without forward traversal", () => {
+ const [slot] = videoSlots('<video id="reverse" src="direct.mp4" data-hypit-start-frame="0" data-hypit-end-frame="4" data-hypit-source-frame="3/1" data-hypit-source-rate="-1/1" data-hypit-source-fps="30/1"></video>');
+ assert.ok(slot !== undefined);
+ assert.deepEqual(Array.from({ length: 4 }, (_, frame) => sourceFrameAt(slot, frame)), [3, 2, 1, 0]);
+ assert.deepEqual(sourceWindows([slot], { startFrame: 0, endFrameExclusive: 4 }), [{
+ src: "direct.mp4", fps: { num: 30, den: 1 }, windows: [{ startFrame: 0, endFrameExclusive: 4 }],
+ }]);
+});
+
test("page selection compacts arbitrary requested frames without inventing coverage across gaps", () => {
assert.deepEqual(requestedFrameRanges({ startFrame: 3, endFrameExclusive: 12 }), [
{ startFrame: 3, endFrameExclusive: 12 },
@@ -129,7 +138,7 @@ test("page selection compacts arbitrary requested frames without inventing cover
]);
});
-test("real selected renders sample video correctly across loop, hold and stretch with independent browsers", {
+test("real selected renders sample video correctly across wrap, hold and fractional rates with independent browsers", {
skip: process.env.HYPIT_BROWSER_TESTS !== "1",
}, async (t) => {
const root = await mkdtemp(join(tmpdir(), "hypit-render-range-test-"));
diff --git a/packages/provider-hyperframes-local/test/visual-readiness.test.ts b/packages/provider-hyperframes-local/test/visual-readiness.test.ts
index 2b92994f..308ba71b 100644
--- a/packages/provider-hyperframes-local/test/visual-readiness.test.ts
+++ b/packages/provider-hyperframes-local/test/visual-readiness.test.ts
@@ -8,7 +8,7 @@ import { MemoryResourceStore } from "@hypit/driver-node";
import { sealComposition, sealVisualTrack } from "@hypit/composition";
import type { VisualElement, VisualTextTypography } from "@hypit/composition";
import { compileHyperframesDocument, materializeHyperframesHtml } from "@hypit/hyperframes";
-import { sealProgramSpace } from "@hypit/program-space";
+import { sealTimeline } from "@hypit/timeline";
import { browserExecutablePath } from "../src/browser.js";
import { createOpaqueFrameCapture } from "../src/opaque-capture.js";
import { renderHyperframesFrames } from "../src/render.js";
@@ -188,15 +188,15 @@ test("compiled frame selection neither stages nor waits for unrelated image reso
const broken = await resources.put(new TextEncoder().encode("not an image"), "image/png");
const red = await resources.put(await sharp({ create: { width: 64, height: 64, channels: 3, background: "#ff0000" } })
.png().toBuffer(), "image/png");
- const space = sealProgramSpace({ id: "capture-scope", durationSec: 2, frameRate: { numerator: 30, denominator: 1 } });
- const track = sealVisualTrack({ id: "visual", programSpaceId: space.id, visualIr: "hypit.visual-ir@1", presents: [
- { id: "unavailable-early", span: { startFrame: 0, endFrameExclusive: 10 }, stacking: { order: 0, tieBreak: "unavailable" },
+ const space = sealTimeline({ id: "capture-scope", frameCount: 60, frameRate: { numerator: 30, denominator: 1 } });
+ const track = sealVisualTrack({ id: "visual", timelineId: space.id, visualIr: "hypit.visual-ir@1", presents: [
+ { id: "unavailable-early", order: 0, z: 0, span: { startFrame: 0, endFrameExclusive: 10 },
elements: [{ id: "unavailable", order: 0, kind: "image", artifact: unavailable,
style: [{ name: "width", value: "64px" }, { name: "height", value: "64px" }] }] },
- { id: "broken-early", span: { startFrame: 10, endFrameExclusive: 30 }, stacking: { order: 1, tieBreak: "early" },
+ { id: "broken-early", order: 1, z: 1, span: { startFrame: 10, endFrameExclusive: 30 },
elements: [{ id: "broken", order: 0, kind: "image", artifact: broken,
style: [{ name: "width", value: "64px" }, { name: "height", value: "64px" }] }] },
- { id: "red-late", span: { startFrame: 30, endFrameExclusive: 60 }, stacking: { order: 2, tieBreak: "late" },
+ { id: "red-late", order: 2, z: 2, span: { startFrame: 30, endFrameExclusive: 60 },
elements: [{ id: "red", order: 0, kind: "image", artifact: red,
style: [{ name: "width", value: "64px" }, { name: "height", value: "64px" }] }] },
] });
@@ -212,8 +212,46 @@ test("compiled frame selection neither stages nor waits for unrelated image reso
{ resources, workers: 1, processTimeoutMs: 120_000 }), /image could not be decoded/u);
});
+test("real capture keeps later Present animation local with picture content and independent workers", live, async () => {
+ const resources = new MemoryResourceStore();
+ const black = await resources.put(await sharp({
+ create: { width: 64, height: 64, channels: 3, background: "#000000" },
+ }).png().toBuffer(), "image/png");
+ const timeline = sealTimeline({ id: "local-animation", frameCount: 90, frameRate: { numerator: 30, denominator: 1 } });
+ const picture = sealVisualTrack({ id: "picture", timelineId: timeline.id, visualIr: "hypit.visual-ir@1", presents: [{
+ id: "picture", order: 0, z: 0, span: { startFrame: 0, endFrameExclusive: 90 },
+ elements: [{ id: "picture", order: 0, kind: "image", artifact: black,
+ style: [{ name: "position", value: "absolute" }, { name: "inset", value: 0 },
+ { name: "width", value: "64px" }, { name: "height", value: "64px" }] }],
+ }] });
+ const animated = sealVisualTrack({ id: "animated", timelineId: timeline.id, visualIr: "hypit.visual-ir@1",
+ presents: [0, 30, 60].map((startFrame, order) => ({
+ id: `pose-${order + 1}`, order, z: 1, span: { startFrame, endFrameExclusive: startFrame + 30 },
+ elements: [{ id: "pose", order: 0, kind: "box", style: [
+ { name: "position", value: "absolute" }, { name: "inset", value: 0 }, { name: "background", value: "#ffffff" },
+ ], animation: { keyframes: [
+ { atFrame: 0, style: [{ name: "opacity", value: 0 }] },
+ { atFrame: 30, style: [{ name: "opacity", value: 1 }] },
+ ] } }],
+ })),
+ });
+ const document = compileHyperframesDocument(sealComposition({ id: "local-animation", canvas: {
+ width: 64, height: 64, clearColor: "#000000",
+ }, tracks: [picture, animated] }), timeline);
+ const frames = await renderHyperframesFrames({ document, frames: [15, 45, 75] }, {
+ resources, workers: 2, processTimeoutMs: 120_000,
+ });
+ for (const [index, artifact] of frames.entries()) {
+ const pixels = await sharp((await resources.get(artifact.resource))!).removeAlpha().raw().toBuffer();
+ const center = (32 * 64 + 32) * 3;
+ const sample = [...pixels.subarray(center, center + 3)];
+ for (const channel of sample) assert.ok(Math.abs(channel - 128) <= 3,
+ `frame ${[15, 45, 75][index]} used a non-local animation pose: ${JSON.stringify(sample)}`);
+ }
+});
+
test("terminal text and SVG mask sources retain their Present frame animations across direct seeks and fresh workers", live, async () => {
- const space = sealProgramSpace({ id: "animations", durationSec: 2, frameRate: { numerator: 30, denominator: 1 } });
+ const space = sealTimeline({ id: "animations", frameCount: 60, frameRate: { numerator: 30, denominator: 1 } });
const image = { kind: "blob", resource: "res_mask", size: 1, mediaType: "image/png" } as const;
const font = { sources: [{ artifact: { kind: "blob", resource: "res_font", size: 1, mediaType: "font/woff2" } }],
weight: 400, style: "normal" } as const;
@@ -248,8 +286,8 @@ test("terminal text and SVG mask sources retain their Present frame animations a
{ id: "mask-image", parent: "mask", order: 4, kind: "image", artifact: image, style: [], animation },
{ id: "content", parent: "mask", order: 5, kind: "box", style: [{ name: "background", value: "#ffffff" }] },
];
- const track = sealVisualTrack({ id: "visual", programSpaceId: space.id, visualIr: "hypit.visual-ir@1",
- presents: [{ id: "later", span: { startFrame: 15, endFrameExclusive: 60 }, stacking: { order: 0, tieBreak: "later" }, elements }] });
+ const track = sealVisualTrack({ id: "visual", timelineId: space.id, visualIr: "hypit.visual-ir@1",
+ presents: [{ id: "later", order: 0, z: 0, span: { startFrame: 15, endFrameExclusive: 60 }, elements }] });
const compiled = compileHyperframesDocument(sealComposition({ id: "animation", canvas: { width: 128, height: 128, clearColor: "#000000" }, tracks: [track] }), space);
const html = materializeHyperframesHtml(compiled, artifact => artifact.resource === "res_font"
? "data:font/woff2;base64,AA==" : "data:image/png;base64,AA==");
diff --git a/packages/provider-hypihub/README.md b/packages/provider-hypihub/README.md
index c986cb77..cb0678fe 100644
--- a/packages/provider-hypihub/README.md
+++ b/packages/provider-hypihub/README.md
@@ -83,7 +83,7 @@ For moving portraits, [Volcengine Matting](../volcengine-matting/README.md) maps
Both formats carry transparency. The source video uses the same upload transport as other video
references; the returned job uses the same polling and asset collection lifecycle. The selected
account's `/v1/models` establishes availability. The processed video enters ordinary Normalize,
-then either semantic alignment for a Script performance or Media Track for B-roll.
+then either semantic alignment for a Script performance or a Visual Clip for independently timed footage.
[Background Removal](../background-removal/README.md) declares a separate single-image capability.
This Provider does not currently implement it; select a project Provider for that operation.
diff --git a/packages/provider-hypihub/src/provider.ts b/packages/provider-hypihub/src/provider.ts
index 298da480..fd6183a5 100644
--- a/packages/provider-hypihub/src/provider.ts
+++ b/packages/provider-hypihub/src/provider.ts
@@ -588,6 +588,8 @@ export function createHypiHubProvider(options: CreateHypiHubProviderOptions = {}
timestamp_granularities: ["segment", "word"],
}, auth, async (message) => { await context.reportDiagnostic?.({ level: "info", message }); });
const evidence = sealAlignedTranscriptEvidence({
+ domainId: request.domainId,
+ sampleFrames: request.sampleFrames,
passages: interpretWhisperXTranscript(response as WhisperXTranscriptResponse, request.sampleFrames),
});
await context.reportProgress?.({ phase: "Word timing ready" });
diff --git a/packages/provider-hypihub/test/provider.test.ts b/packages/provider-hypihub/test/provider.test.ts
index 0598cafd..4e49a91d 100644
--- a/packages/provider-hypihub/test/provider.test.ts
+++ b/packages/provider-hypihub/test/provider.test.ts
@@ -12,8 +12,7 @@ import { elevenLabsSpeechEndpoints, sealElevenLabsSpeechRequest } from "@hypit/e
import { generationTypes } from "@hypit/generation";
import { gptImageEndpoints, sealGptImage2Request } from "@hypit/gpt-image";
import { sealSeedanceRequest, seedanceEndpoints } from "@hypit/seedance";
-import { sealSpeechEvidenceAudio } from "@hypit/speech";
-import { speechEvidenceTypes } from "@hypit/speech-evidence";
+import { sealSpeechEvidenceAudio, speechEvidenceTypes } from "@hypit/speech-evidence";
import { whisperXCapabilities, whisperXRequestForEvidenceAudio } from "@hypit/whisperx";
import { portraitMattingEndpoint, sealPortraitMattingRequest } from "@hypit/volcengine-matting";
@@ -687,6 +686,7 @@ for (const language of ["en", "ko"]) test(`HypiHub forwards ${language} for the
capability: whisperXCapabilities.alignment,
returns: speechEvidenceTypes.alignedTranscript,
constraints: whisperXRequestForEvidenceAudio(sealSpeechEvidenceAudio({
+ domainId: "hypihub-test-domain",
artifact,
sampleFrames: 32_000,
}), { language }) as unknown as CanonicalValue,
@@ -756,7 +756,10 @@ for (const language of ["en", "ko"]) test(`HypiHub forwards ${language} for the
credentials: { apiKey: { secret: "test-key" } },
});
assert.equal(submitted, true);
- assert.deepEqual(result.value, { kind: "inline", value: { passages: [{
+ assert.deepEqual(result.value, { kind: "inline", value: {
+ domainId: "hypihub-test-domain",
+ sampleFrames: 32_000,
+ passages: [{
startSample: 1_600,
endSampleExclusive: 25_600,
words: [
@@ -1094,7 +1097,7 @@ for (const mode of ['success', 'error', 'body-timeout'] as const) {
const request: Need = {
id: 'need:transcription-receipt', capability: whisperXCapabilities.alignment,
returns: speechEvidenceTypes.alignedTranscript,
- constraints: whisperXRequestForEvidenceAudio(sealSpeechEvidenceAudio({ artifact, sampleFrames: 32_000 }), { language: 'en' }) as unknown as CanonicalValue,
+ constraints: whisperXRequestForEvidenceAudio(sealSpeechEvidenceAudio({ domainId: "receipt-test-domain", artifact, sampleFrames: 32_000 }), { language: 'en' }) as unknown as CanonicalValue,
result: 'record:transcription-receipt',
};
const messages: string[] = [];
diff --git a/packages/provider-image-opencv-local/test/provider.test.ts b/packages/provider-image-opencv-local/test/provider.test.ts
index f74eb174..7d55fc2d 100644
--- a/packages/provider-image-opencv-local/test/provider.test.ts
+++ b/packages/provider-image-opencv-local/test/provider.test.ts
@@ -41,7 +41,6 @@ function composeNeed(source: BlobRef): Need {
kind: "compose",
canvas: {
widthPx: 3, heightPx: 2,
- origin: "top-left", xDirection: "right", yDirection: "down", pixelAspect: "square",
},
background: "#00000000",
layers: [{
diff --git a/packages/provider-media-local/README.md b/packages/provider-media-local/README.md
index 113f39b9..05e0b838 100644
--- a/packages/provider-media-local/README.md
+++ b/packages/provider-media-local/README.md
@@ -37,9 +37,9 @@ These are this FFmpeg implementation's intermediate encodings; Source and Track
to use ordinary SynchronizedMedia. Transform currently emits opaque MP4, so perform trim/retime
before matting when the resulting clip needs transparency.
-The result is ordinary SynchronizedMedia. Timeline assembly and Media Track consume its transparent
-picture through their existing visual outputs; choosing the A-roll or B-roll role belongs to the
-Source. Local HyperFrames extracts alpha-preserving PNGs and composites them against the authored
+The result is ordinary SynchronizedMedia. Timeline construction consumes only its local domain;
+Visual Clip or a Visual Clip consumes its transparent picture according to the authored
+relationship. Local HyperFrames extracts alpha-preserving PNGs and composites them against the authored
Canvas and lower visual layers before encoding the final MP4.
The Runtime Adapter declares the selected `ffmpeg`/`ffprobe` pair as an external, non-daemon Program.
diff --git a/packages/provider-media-local/package.json b/packages/provider-media-local/package.json
index a7d6fe7f..7256fd9f 100644
--- a/packages/provider-media-local/package.json
+++ b/packages/provider-media-local/package.json
@@ -20,7 +20,7 @@
"@hypit/runtime": "workspace:*",
"@hypit/runtime-kit": "workspace:*",
"@hypit/runtime-host-node": "workspace:*",
- "@hypit/speech": "workspace:*"
+ "@hypit/speech-evidence": "workspace:*"
},
"devDependencies": {
"@hypit/driver-node": "workspace:*"
diff --git a/packages/provider-media-local/src/provider.ts b/packages/provider-media-local/src/provider.ts
index 61f0160d..1a4ba86d 100644
--- a/packages/provider-media-local/src/provider.ts
+++ b/packages/provider-media-local/src/provider.ts
@@ -14,7 +14,7 @@ import {
import type { MediaExecutionEnvironment, MediaOperationResult } from "@hypit/media-execution";
import { mediaPipelineCapabilities } from "@hypit/media-pipeline";
import { isStreamingResourceStore } from "@hypit/runtime";
-import { speechTypes } from "@hypit/speech";
+import { speechEvidenceTypes } from "@hypit/speech-evidence";
import { defineEndpointPackage } from "@hypit/endpoint-kit";
import type { EndpointFulfillment, EndpointInvocationContext } from "@hypit/endpoint-kit";
@@ -128,7 +128,7 @@ export function createLocalMediaProvider(config: CreateLocalMediaProviderOptions
{
lifecycle: "immediate" as const,
capability: mediaPipelineCapabilities.projectSpeechEvidenceAudio,
- returns: speechTypes.evidenceAudio,
+ returns: speechEvidenceTypes.audio,
handler: operation(executeProjectSpeechEvidenceAudio),
},
{
diff --git a/packages/provider-media-local/test/provider.test.ts b/packages/provider-media-local/test/provider.test.ts
index 21c31343..2808223a 100644
--- a/packages/provider-media-local/test/provider.test.ts
+++ b/packages/provider-media-local/test/provider.test.ts
@@ -6,8 +6,8 @@ import test from "node:test";
import { artifactTypes } from "@hypit/artifact";
import { mediaTypes, sealRenderedVisual, sealTimelineAudio, synchronizedMediaSampleFrames, verifyMediaInspection, verifyMuxedMedia, verifySynchronizedMedia, verifyTimelineAudio } from "@hypit/media";
import type { MediaAudioStream, MediaInspection, MuxedMedia, SynchronizedMedia, TimelineAudio } from "@hypit/media";
-import { assertSpeechEvidenceAudioIdentity, speechTypes } from "@hypit/speech";
-import type { SpeechEvidenceAudio } from "@hypit/speech";
+import { assertSpeechEvidenceAudioIdentity, speechEvidenceTypes } from "@hypit/speech-evidence";
+import type { SpeechEvidenceAudio } from "@hypit/speech-evidence";
import assert from "node:assert/strict";
import {
MemoryResourceStore,
@@ -280,7 +280,7 @@ test("local media Provider enumerates attached pictures and jointly normalizes 3
assert.equal(selection.audioStreamIndex, 1);
const typed = await normalizeArtifact({ resources, source, inspection: typedInspection,
selection, frameRate: selectionRequest.frameRate });
- assert.equal(typed.timeline.frameCount, 30);
+ assert.equal(typed.frameDomain.frameCount, 30);
assert.equal(synchronizedMediaSampleFrames(typed), 48_000);
assert.equal("basisResourceId" in typed, false);
assert.equal("narrativeDigest" in typed, false);
@@ -387,7 +387,7 @@ test("animated WebP keeps its authored frame timing before fixed-rate normalizat
});
const selection = selectMediaStreams(inspection, request);
const normalized = await normalizeArtifact({ resources, source, inspection, selection, frameRate: request.frameRate });
- assert.equal(normalized.timeline.frameCount, 10);
+ assert.equal(normalized.frameDomain.frameCount, 10);
assert.equal(normalized.visual?.width, 64);
assert.equal(normalized.visual?.height, 48);
const output = await inspectArtifact(resources, normalized.visual!.artifact);
@@ -417,7 +417,7 @@ test("animated GIF keeps its authored frame timing before fixed-rate normalizati
});
const selection = selectMediaStreams(inspection, request);
const normalized = await normalizeArtifact({ resources, source, inspection, selection, frameRate: request.frameRate });
- assert.equal(normalized.timeline.frameCount, 10);
+ assert.equal(normalized.frameDomain.frameCount, 10);
const output = await inspectArtifact(resources, normalized.visual!.artifact);
assert.equal(output.streams[0]?.decodedUnitCount, 10);
} finally {
@@ -440,6 +440,7 @@ test("local media Provider derives one exact 16 kHz mono WhisperX evidence artif
const resources = new MemoryResourceStore();
const source = await resources.put(await readFile(sourcePath), "audio/wav");
const constraints = canonicalize({
+ domainId: "provider-media-test-domain",
source,
sourceSampleFrames: 48_001,
evidenceSampleFrames: 16_000,
@@ -447,12 +448,13 @@ test("local media Provider derives one exact 16 kHz mono WhisperX evidence artif
const request = need(
"need:speech-evidence-audio",
mediaPipelineCapabilities.projectSpeechEvidenceAudio,
- speechTypes.evidenceAudio,
+ speechEvidenceTypes.audio,
constraints,
);
const value = await fulfillInline(resources, request);
assertSpeechEvidenceAudioIdentity(value as unknown as SpeechEvidenceAudio);
const evidence = value as unknown as SpeechEvidenceAudio;
+ assert.equal(evidence.domainId, "provider-media-test-domain");
assert.equal(evidence.sampleFrames, 16_000);
const inspected = await inspectArtifact(resources, evidence.artifact);
const audio = inspected.streams.find((stream) => stream.kind === "audio");
@@ -501,7 +503,7 @@ test("local media Provider preserves one source A/V origin when audio starts lat
const expectedHead = Math.round((seconds(audio.startPts) - seconds(video.startPts)) * 48_000);
const expectedEnd = Math.round((seconds(audio.endPts) - seconds(video.startPts)) * 48_000);
const expectedTail = 48_000 - Math.min(48_000, expectedEnd);
- assert.equal(normalized.timeline.frameCount, 30);
+ assert.equal(normalized.frameDomain.frameCount, 30);
const bytes = await resources.get(normalized.audio!.artifact.resource);
assert(bytes !== undefined);
const audible = pcm16StereoAudibleSpan(bytes);
@@ -536,7 +538,7 @@ test("a video-only generated MP4 remains visual-only and cannot satisfy a reques
});
const selection = selectMediaStreams(inspection, request);
const normalized = await normalizeArtifact({ resources, source, inspection, selection, frameRate: request.frameRate });
- assert.equal(normalized.timeline.frameCount, 15);
+ assert.equal(normalized.frameDomain.frameCount, 15);
assert.ok(normalized.visual);
assert.equal(normalized.audio, undefined);
@@ -592,7 +594,7 @@ test("local media Provider transforms A/V and extracts ordinary audio and frame
program: {
operations: [
{ kind: "trim", tailSec: 0.2 },
- { kind: "retime", rate: 2, pitch: "preserve" },
+ { kind: "retime", rate: 2 },
],
},
}),
@@ -704,7 +706,7 @@ test("local media Provider transforms A/V and extracts ordinary audio and frame
selection: stillSelection,
frameRate: { numerator: 30, denominator: 1 },
});
- assert.equal(stillNormalized.timeline.frameCount, 15);
+ assert.equal(stillNormalized.frameDomain.frameCount, 15);
assert.equal(stillNormalized.audio, undefined);
} finally {
await rm(root, { recursive: true, force: true }).catch(() => {});
@@ -759,7 +761,8 @@ test("local media Provider renders one frame-domain audio plan and muxes exactly
sourceLoop: false,
sourcePhaseSample: 0,
playbackRate: 1,
- pitch: "preserve",
+ mixStartSample: 0,
+ mixEndSampleExclusive: 24_000,
gain: 1,
fadeInSamples: 0,
fadeOutSamples: 0,
@@ -775,7 +778,8 @@ test("local media Provider renders one frame-domain audio plan and muxes exactly
sourceLoop: false,
sourcePhaseSample: 0,
playbackRate: 1,
- pitch: "preserve",
+ mixStartSample: 24_000,
+ mixEndSampleExclusive: 48_000,
gain: 1,
fadeInSamples: 0,
fadeOutSamples: 0,
@@ -906,7 +910,8 @@ test("local media Provider executes an end-aligned loop from the exact authored
sourceLoop: true,
sourcePhaseSample: 50,
playbackRate: 1,
- pitch: "preserve",
+ mixStartSample: 0,
+ mixEndSampleExclusive: 250,
gain: 1,
fadeInSamples: 0,
fadeOutSamples: 0,
@@ -949,7 +954,8 @@ test("audio range preserves loop phase, tempo and intersected fades from the ful
sampleRate: 48000, sampleFrames: 96000,
clips: [{ id: "loop", artifact: source, targetStartSample: 0, targetEndSampleExclusive: 96000,
sourceSampleFrames: 4800, sourceStartSample: 0, sourceEndSampleExclusive: 4800,
- sourceLoop: true, sourcePhaseSample: 1700, playbackRate: 1.25, pitch: "preserve", gain: 0.8,
+ sourceLoop: true, sourcePhaseSample: 1700, playbackRate: 1.25,
+ mixStartSample: 0, mixEndSampleExclusive: 96000, gain: 0.8,
fadeInSamples: 48000, fadeOutSamples: 30000 }], mix: { normalize: false, limiter: "none" },
});
const pcm = async (name: string, range?: { startFrame: number; endFrameExclusive: number }) => {
@@ -985,7 +991,8 @@ test("audio envelopes and audible regions preserve sample phase through gaps and
frameRate: { numerator: 30, denominator: 1 }, frameCount: 12, sampleRate: 48000, sampleFrames: 19200,
clips: [{ id: "voice", artifact: source, targetStartSample: 1600, targetEndSampleExclusive: 17600,
sourceSampleFrames: 4800, sourceStartSample: 0, sourceEndSampleExclusive: 4800,
- sourceLoop: true, sourcePhaseSample: 0, playbackRate: 1, pitch: "preserve", gain: 1,
+ sourceLoop: true, sourcePhaseSample: 0, playbackRate: 1,
+ mixStartSample: 1600, mixEndSampleExclusive: 17600, gain: 1,
fadeInSamples: 0, fadeOutSamples: 0,
gainEnvelope: [{ sample: 1600, gain: 0 }, { sample: 17600, gain: 1 }],
audibility: [{ startSample: 1600, endSampleExclusive: 4800 }, { startSample: 8000, endSampleExclusive: 17600 }],
diff --git a/packages/provider-whisperx-local/src/provider.ts b/packages/provider-whisperx-local/src/provider.ts
index 9078448e..99c37d3b 100644
--- a/packages/provider-whisperx-local/src/provider.ts
+++ b/packages/provider-whisperx-local/src/provider.ts
@@ -181,6 +181,8 @@ export function createLocalWhisperXProvider(config: CreateLocalWhisperXProviderO
const response = raw.value as WhisperXServiceResponse;
const passages = interpretWhisperXResponse(response, request.sampleFrames);
const evidence: AlignedTranscriptEvidence = sealAlignedTranscriptEvidence({
+ domainId: request.domainId,
+ sampleFrames: request.sampleFrames,
passages,
});
await context.reportProgress?.({ phase: "Word timing ready" });
diff --git a/packages/provider-whisperx-local/test/provider.test.ts b/packages/provider-whisperx-local/test/provider.test.ts
index 10ff9f99..36262212 100644
--- a/packages/provider-whisperx-local/test/provider.test.ts
+++ b/packages/provider-whisperx-local/test/provider.test.ts
@@ -1,10 +1,9 @@
import { readFile } from "node:fs/promises";
import test from "node:test";
-import { sealSpeechEvidenceAudio, speechTypes } from "@hypit/speech";
+import { sealSpeechEvidenceAudio, speechEvidenceTypes } from "@hypit/speech-evidence";
import assert from "node:assert/strict";
import { MemoryResourceStore, EndpointRegistry } from "@hypit/driver-node";
import type { Need } from "@hypit/protocol";
-import { speechEvidenceTypes } from "@hypit/speech-evidence";
import {
whisperXCapabilities,
whisperXRequestForEvidenceAudio,
@@ -107,6 +106,7 @@ for (const language of ["en", "ko"]) test(`local Provider preserves ${language}
const resources = new MemoryResourceStore();
const artifact = await resources.put(expected, "audio/wav");
const evidenceAudio = sealSpeechEvidenceAudio({
+ domainId: "provider-test-domain",
artifact,
sampleFrames: 32_000,
});
@@ -137,7 +137,9 @@ for (const language of ["en", "ko"]) test(`local Provider preserves ${language}
assert.equal(output.value.kind, "inline");
const value = output.value.kind === "inline" ? output.value.value : null;
assert.equal((value as { readonly passages?: readonly unknown[] }).passages?.length, 1);
- assert.equal(speechTypes.evidenceAudio.name, "SpeechEvidenceAudio");
+ assert.equal((value as { readonly domainId?: string }).domainId, evidenceAudio.domainId);
+ assert.equal((value as { readonly sampleFrames?: number }).sampleFrames, evidenceAudio.sampleFrames);
+ assert.equal(speechEvidenceTypes.audio.name, "SpeechEvidenceAudio");
} finally {
globalThis.fetch = originalFetch;
}
diff --git a/packages/ranking/README.md b/packages/ranking/README.md
index 146588ba..7bc0dfdb 100644
--- a/packages/ranking/README.md
+++ b/packages/ranking/README.md
@@ -1,12 +1,10 @@
# `@hypit/ranking`
-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.
+The Track Surface accepts one completed Timeline plus absolute Windows and Instants. Those values
+may be authored directly or published by a domain projector upstream.
-Ranking boards that follow the argument of a video: introduce an item, give its verdict, and retain
-its place while the next item is discussed. Its Surface binds the performance's semantic time or
-authored time; the board consumes projected timing, Frames, Styles, fonts, text and optional icons or sound.
+Ranking boards introduce an item, give its verdict, and retain its place while the next item is
+discussed. The board consumes absolute timing, Frames, Styles, fonts, text and optional icons or sound.
| Form | Temporal behavior |
| --- | --- |
@@ -18,24 +16,23 @@ The board's outer Window owns its lifetime. Item reveal Windows must fit within
where the selected schedule requires succession. Ending a reveal does not remove its settled result.
`preset` supplies initial state and needs no reveal event.
-## Bind the ranking to the target Script
+## Bind the ranking to resolved time
This excerpt assumes the Script, Timeline, Canvas, Frame and Style have been declared:
```svml
<import as="ranking" from="@hypit/ranking@1"/>
-<ranking:Column id="priorities" timeline={speech.timeline} canvas={vertical}
- frame={layout.ranking} during={story.segment.ranking} style={ranking-style}>
- <ranking:ColumnItem rank="1" label="Winner" during={story.selection.winner}/>
+<ranking:Column id="priorities" timeline={speech.timeline} within={vertical.bounds}
+ frame={layout.ranking} during={story-time.ranking} style={ranking-style}>
+ <ranking:ColumnItem rank="1" label="Winner" during={story-time.winner}/>
<ranking:ColumnItem rank="2" preset="true" label="Already placed"/>
</ranking:Column>
```
-Choose `winner` to cover the phrase whose delivery stages this reveal. When that performance changes
-length, the projected Window follows the phrase. Style defines how the reveal and settling use that
-Window. TopThree instead accepts item `at` projections and a board `terminal` projection; a Moment
-can supply the intended trigger.
+An upstream Narrative projection can publish `ranking` and `winner` from the relevant Segment and
+Selection. When the performance changes, those projected Windows follow. Style defines how reveal
+and settling use the Window. TopThree instead accepts item `at` Instants and a terminal Instant.
Each board publishes `.schedule`, `.program` and `.visual`. Optional normalized `appear-sound` or
`move-sound` inputs add `.events` and `.audio` where that form supports them.
@@ -45,13 +42,13 @@ outputs as peers in Film. Labels can be literal or graph Text; Styles are typed
exact fonts. Use `hypit vocabulary @hypit/ranking --tag Column` (or another declared tag) for its
attributes, children, outputs and configured example.
-## Read it as a semantic component example
+## Read it as a temporal component example
The following files are included in the Distribution and show how the responsibilities connect:
| File | What to learn from it |
| --- | --- |
-| [surface.ts](src/surface.ts) | `rankingSurface` resolves author inputs, projects the outer and item times through `createTemporalWindowProjection` / `createTemporalInstantProjection`, and retains the returned drafts and references. |
+| [surface.ts](src/surface.ts) | `rankingSurface` resolves author inputs, projects the outer and item times through `createTemporalWindowConstruction` / `createTemporalInstantConstruction`, and retains the returned drafts and references. |
| [fragment.ts](src/fragment.ts) | `createRankingFragment` receives Timeline and wires typed content, time, layout and Style inputs into finite operations. |
| [schedule.ts](src/schedule.ts) | Compute reveal, activation and settled spans from the projected times. |
| [component.ts](src/component.ts) and [render.ts](src/render.ts) | Build the ranking program and produce picture and optional sound from that schedule. |
diff --git a/packages/ranking/package.json b/packages/ranking/package.json
index 6a4ffcb5..2c13acc3 100644
--- a/packages/ranking/package.json
+++ b/packages/ranking/package.json
@@ -16,8 +16,6 @@
"@hypit/composition": "workspace:*",
"@hypit/elaborator": "workspace:*",
"@hypit/media": "workspace:*",
- "@hypit/narrative": "workspace:*",
- "@hypit/program-space": "workspace:*",
"@hypit/protocol": "workspace:*",
"@hypit/timeline": "workspace:*",
"@hypit/spatial": "workspace:*",
diff --git a/packages/ranking/src/component.ts b/packages/ranking/src/component.ts
index 14442f37..91f1d50b 100644
--- a/packages/ranking/src/component.ts
+++ b/packages/ranking/src/component.ts
@@ -4,7 +4,7 @@ import type { SynchronizedMedia } from "@hypit/media";
import { canonicalize } from "@hypit/protocol";
import type { BlobRef, StoredValue } from "@hypit/protocol";
import type { TemporalInstant, TemporalWindow } from "@hypit/temporal";
-import type { CanvasSpace, SpatialFrame } from "@hypit/spatial";
+import type { SpatialFrame } from "@hypit/spatial";
import type { Text } from "@hypit/text";
import { rankingProducers, rankingTypes } from "./manifest.js";
@@ -189,7 +189,7 @@ export const rankingComponent = {
handler: ({ inputs }) => {
const common = programInputs(inputs);
return { outputs: { program: output(buildTierBoardProgram(common.header,
- inline<CanvasSpace>(inputs.canvas?.value, "CanvasSpace"), common.frame, common.schedule,
+ inline<SpatialFrame>(inputs.within?.value, "SpatialFrame"), common.frame, common.schedule,
inline<TierBoardStyle>(inputs.style?.value, "TierBoardStyle"), inline<TierBoardItemSet>(inputs.set?.value, "TierBoardItemSet"))) }, needs: {} };
},
},
@@ -198,7 +198,7 @@ export const rankingComponent = {
handler: ({ inputs }) => {
const common = programInputs(inputs);
return { outputs: { program: output(buildColumnProgram(common.header,
- inline<CanvasSpace>(inputs.canvas?.value, "CanvasSpace"), common.frame, common.schedule,
+ inline<SpatialFrame>(inputs.within?.value, "SpatialFrame"), common.frame, common.schedule,
inline<ColumnStyle>(inputs.style?.value, "ColumnStyle"), inline<ColumnItemSet>(inputs.set?.value, "ColumnItemSet"))) }, needs: {} };
},
},
diff --git a/packages/ranking/src/fragment.ts b/packages/ranking/src/fragment.ts
index f9d85505..cb205707 100644
--- a/packages/ranking/src/fragment.ts
+++ b/packages/ranking/src/fragment.ts
@@ -62,7 +62,7 @@ export function createRankingFragment(
...(variant === "top-three" ? [
{ name: "terminal", type: temporalTypes.instant },
] : []),
- ...(variant === "column" || variant === "tier-board" ? [{ name: "canvas", type: spatialTypes.canvas }] : []),
+ ...(variant === "column" || variant === "tier-board" ? [{ name: "within", type: spatialTypes.frame }] : []),
{ name: "frame", type: spatialTypes.frame },
{ name: "style", type: selected.style },
];
@@ -93,14 +93,14 @@ export function createRankingFragment(
result: { kind: "output", name: "spec" },
});
const resolvedSpec = item.contentName === undefined ? input(item.specName) : operation(materializedId);
- const semanticId = `spec-${item.suffix}`;
+ const specOperationId = `spec-${item.suffix}`;
operations.push({
- id: semanticId,
+ id: specOperationId,
producer: rankingProducers.appendSpec,
inputs: { set: specs, spec: resolvedSpec },
result: { kind: "output", name: "set" },
});
- specs = operation(semanticId);
+ specs = operation(specOperationId);
const visualId = `item-${item.suffix}`;
operations.push({
id: visualId,
@@ -153,7 +153,7 @@ export function createRankingFragment(
producer: selected.build,
inputs: {
header: input("header"),
- ...(variant === "column" || variant === "tier-board" ? { canvas: input("canvas") } : {}),
+ ...(variant === "column" || variant === "tier-board" ? { within: input("within") } : {}),
frame: input("frame"), schedule: operation("schedule"), style: input("style"), set: resolved,
},
result: { kind: "output", name: "program" },
diff --git a/packages/ranking/src/manifest.ts b/packages/ranking/src/manifest.ts
index 74bab5a7..d18b7ec2 100644
--- a/packages/ranking/src/manifest.ts
+++ b/packages/ranking/src/manifest.ts
@@ -1,14 +1,12 @@
-import { timelineTypes } from "@hypit/timeline";
+import { timelineTypes, timelineDependency } from "@hypit/timeline";
import { temporalContextAttributeVocabulary } from "@hypit/temporal-markup";
import { readFile } from "node:fs/promises";
import { artifactDependency } from "@hypit/artifact";
import { compositionDependency, compositionTypes } from "@hypit/composition";
import { mediaDependency, mediaTypes } from "@hypit/media";
-import { narrativeDependency, narrativeTypes } from "@hypit/narrative";
import type { ModuleManifest, ProducerRef, TypeRef, ValueSchema } from "@hypit/protocol";
-import { timelineDependency } from "@hypit/timeline";
import { spatialDependency, spatialFrameSchema, spatialTypes } from "@hypit/spatial";
import { svsRecipeType } from "@hypit/svs";
import { temporalDependency, temporalInstantSchema, temporalTypes, temporalWindowSchema } from "@hypit/temporal";
@@ -278,11 +276,11 @@ const allRankingMarkupSurfaces = [
{ name: "label-width", required: false,
summary: "Overrides the label column width as a fraction of the board Frame width; when absent it is derived from row height." },
{ name: "stage-x", required: false, fallback: "0.2",
- summary: "Places the independent explanation stage horizontally as a fraction of the Canvas width." },
+ summary: "Places the independent explanation stage horizontally as a fraction of the placement Frame width." },
{ name: "stage-y", required: false, fallback: "0.3",
- summary: "Places the independent explanation stage vertically as a fraction of the Canvas height." },
+ summary: "Places the independent explanation stage vertically as a fraction of the placement Frame height." },
{ name: "stage-size", required: false, fallback: "168",
- summary: "Sets the staged Item size in Canvas pixels independently from its settled tier cell." },
+ summary: "Sets the staged Item size in picture-plane pixels independently from its settled tier cell." },
{ name: "icon-radius-ratio", required: false, fallback: "0.12",
summary: "Sets icon corner radius as a fraction of one tier row's height." },
{ name: "icon-fit", required: false, fallback: "cover",
@@ -488,21 +486,21 @@ const allRankingMarkupSurfaces = [
"Every other property is refused by name.",
],
} },
- { name: "tier", tag: "TierBoard", mode: "structured", outputs: [rankingTypes.header, rankingTypes.itemSpec, temporalTypes.instantSpec, temporalTypes.windowSpec, temporalTypes.instant, temporalTypes.window, rankingTypes.schedule, rankingTypes.tierProgram, compositionTypes.visualTrack, rankingTypes.soundEvents, compositionTypes.audioTrack],
+ { name: "tier", tag: "TierBoard", mode: "structured", outputs: [rankingTypes.header, rankingTypes.itemSpec, temporalTypes.duration, temporalTypes.extent, temporalTypes.shiftSpec, temporalTypes.instantSpec, temporalTypes.windowSpec, temporalTypes.instant, temporalTypes.window, rankingTypes.schedule, rankingTypes.tierProgram, compositionTypes.visualTrack, rankingTypes.soundEvents, compositionTypes.audioTrack],
vocabulary: {
summary: "Places Items into tier rows from preset state or explicit reveal Selections, and publishes the board and the Tracks it renders to.",
appearance:
- "The board occupies only its Frame: one continuous tier table with colored label cells, a dark content field and dark grid lines. An independent explanation stage is positioned in Canvas space. Preset tiles occupy the innermost cells from the first frame. Every other tile takes one explicit Segment or Selection window; sorting those disjoint windows gives the strict reveal order and fills each tier from inside to outside. Both entry modes appear in place with a quick overshoot and soft settle. A direct tile appears in its final cell. A drop tile appears on the stage, remains still while that Item is discussed, then follows an eased curved glide into its final cell during the window's last move interval. Every placed tile remains settled while later ones arrive.",
+ "The board occupies only its Frame: one continuous tier table with colored label cells, a dark content field and dark grid lines. An independent explanation stage is positioned in a separate placement Frame. Preset tiles occupy the innermost cells from the first frame. Every other tile takes one explicit Segment or Selection window; sorting those disjoint windows gives the strict reveal order and fills each tier from inside to outside. Both entry modes appear in place with a quick overshoot and soft settle. A direct tile appears in its final cell. A drop tile appears on the stage, remains still while that Item is discussed, then follows an eased curved glide into its final cell during the window's last move interval. Every placed tile remains settled while later ones arrive.",
preview: previewImage("TierBoard.svg", "image/svg+xml"),
attributes: [
{ name: "id", kind: "identifier", required: true,
summary: "Names this board so its Schedule, Program and Tracks can be referenced elsewhere in the Source." },
...temporalContextAttributeVocabulary,
- { name: "canvas", kind: "reference", required: true, accepts: [spatialTypes.canvas],
- summary: "Chooses the Canvas coordinate space used by the independent explanation stage." },
+ { name: "within", kind: "reference", required: true, accepts: [spatialTypes.frame],
+ summary: "Chooses the placement Frame used by the independent explanation stage." },
{ name: "frame", kind: "reference", required: true, accepts: [spatialTypes.frame],
summary: "Chooses the compact Frame occupied only by the tier table." },
- { name: "during", kind: "expression", required: true, values: ["program"], accepts: [narrativeTypes.selection, narrativeTypes.excerpt],
+ { name: "during", kind: "expression", required: true, values: ["program"], accepts: [temporalTypes.window],
summary: "Spans the complete film clock when written as program, or projects the referenced Segment or Selection into the board lifetime." },
{ name: "style", kind: "reference", required: true, accepts: [rankingTypes.tierStyle],
summary: "Chooses the TierBoardStyle this board is drawn in, and only that variant's." },
@@ -525,7 +523,7 @@ const allRankingMarkupSurfaces = [
summary: "Chooses an in-place entrance in the final cell or on the independent stage; a staged Item holds for the explanation, then glides into the tier at the window end. It is required for non-preset Items and forbidden for preset Items." },
{ name: "icon", kind: "reference", required: true, accepts: [mediaTypes.blobArtifact],
summary: "Chooses the image drawn beside the Item." },
- { name: "during", kind: "reference", required: false, accepts: [narrativeTypes.selection, narrativeTypes.excerpt],
+ { name: "during", kind: "reference", required: false, accepts: [temporalTypes.window],
summary: "Chooses this non-preset Item's exact Segment or Selection interval; all sibling intervals must be disjoint." },
{ name: "stack", kind: "literal", required: false,
summary: "Overrides the Style's draw order for this Item alone." },
@@ -544,11 +542,11 @@ const allRankingMarkupSurfaces = [
summary: "The rendered board sound, published only when a sound is authored." },
],
example: `<ranking:TierBoardStyle id="tier-style" recipe={recipes.ranking.tier} font={ui-font}/>
-<ranking:TierBoard id="tiers" timeline={speech.timeline} canvas={vertical} frame={board-frame}
- during="program"
+<ranking:TierBoard id="tiers" timeline={speech.timeline} within={vertical.bounds} frame={board-frame}
+ during="timeline"
style={tier-style}>
<ranking:TierItem id="row-regen" tier="s" preset="true" icon={icon-regen}/>
- <ranking:TierItem id="row-remini" tier="a" entry="drop" icon={icon-remini} during={story.selection.remini}/>
+ <ranking:TierItem id="row-remini" tier="a" entry="drop" icon={icon-remini} during={story-time.remini}/>
</ranking:TierBoard>`,
notes: [
"The board requires at least one TierItem, accepts no other child and no text of its own, and Item ids must be unique within it.",
@@ -558,21 +556,21 @@ const allRankingMarkupSurfaces = [
"Authoring either sound also connects the Style's `.sound` output, so `style` must name a TierBoardStyle written in this Source.",
],
} },
- { name: "column", tag: "Column", mode: "structured", outputs: [rankingTypes.header, rankingTypes.itemSpec, rankingTypes.textItemShell, temporalTypes.instantSpec, temporalTypes.windowSpec, temporalTypes.instant, temporalTypes.window, rankingTypes.schedule, rankingTypes.columnProgram, compositionTypes.visualTrack, rankingTypes.soundEvents, compositionTypes.audioTrack],
+ { name: "column", tag: "Column", mode: "structured", outputs: [rankingTypes.header, rankingTypes.itemSpec, rankingTypes.textItemShell, temporalTypes.duration, temporalTypes.extent, temporalTypes.shiftSpec, temporalTypes.instantSpec, temporalTypes.windowSpec, temporalTypes.instant, temporalTypes.window, rankingTypes.schedule, rankingTypes.columnProgram, compositionTypes.visualTrack, rankingTypes.soundEvents, compositionTypes.audioTrack],
vocabulary: {
summary: "Places rows by explicit rank, reveals each non-preset row in its own Segment or Selection, and publishes the board and the Tracks it renders to.",
appearance:
- "A narrow vertical rank rail occupies its Frame while a large reveal stage is positioned independently in Canvas space. Preset rows are settled from the first frame. Each other row rises into the stage during its own projected Segment or Selection, then shrinks and moves into the content slot beside its numbered rank. Rank, child order and reveal time are independent.",
+ "A narrow vertical rank rail occupies its Frame while a large reveal stage is positioned independently in a separate placement Frame. Preset rows are settled from the first frame. Each other row rises into the stage during its own projected Segment or Selection, then shrinks and moves into the content slot beside its numbered rank. Rank, child order and reveal time are independent.",
preview: previewImage("Column.svg", "image/svg+xml"),
attributes: [
{ name: "id", kind: "identifier", required: true,
summary: "Names this board so its Schedule, Program and Tracks can be referenced elsewhere in the Source." },
...temporalContextAttributeVocabulary,
- { name: "canvas", kind: "reference", required: true, accepts: [spatialTypes.canvas],
- summary: "Chooses the Canvas coordinate space used by the independent reveal stage." },
+ { name: "within", kind: "reference", required: true, accepts: [spatialTypes.frame],
+ summary: "Chooses the placement Frame used by the independent reveal stage." },
{ name: "frame", kind: "reference", required: true, accepts: [spatialTypes.frame],
summary: "Chooses the fixed Frame occupied by the vertical rank rail." },
- { name: "during", kind: "expression", required: true, values: ["program"], accepts: [narrativeTypes.selection, narrativeTypes.excerpt],
+ { name: "during", kind: "expression", required: true, values: ["program"], accepts: [temporalTypes.window],
summary: "Spans the complete film clock when written as program, or projects the referenced Segment or Selection into the Column lifetime." },
{ name: "style", kind: "reference", required: true, accepts: [rankingTypes.columnStyle],
summary: "Chooses the ColumnStyle this board is drawn in, and only that variant's." },
@@ -593,7 +591,7 @@ const allRankingMarkupSurfaces = [
summary: "Sets the positive rank number and final row position independently from reveal order." },
{ name: "preset", kind: "literal", required: false, values: ["true", "false"],
summary: "Settles the row from the start of the outer window; defaults to false." },
- { name: "during", kind: "reference", required: false, accepts: [narrativeTypes.selection, narrativeTypes.excerpt],
+ { name: "during", kind: "reference", required: false, accepts: [temporalTypes.window],
summary: "Chooses this row's Segment or Selection reveal window; required unless preset is true." },
{ name: "icon", kind: "reference", required: false, accepts: [mediaTypes.blobArtifact],
summary: "Chooses the image drawn beside the row." },
@@ -614,11 +612,11 @@ const allRankingMarkupSurfaces = [
summary: "The rendered board sound, published only when a sound is authored." },
],
example: `<ranking:ColumnStyle id="board-style" recipe={recipes.ranking.board} font={ui-font}/>
-<ranking:Column id="board" timeline={speech.timeline} canvas={vertical} frame={board-frame}
- during={story.segment.ranking}
+<ranking:Column id="board" timeline={speech.timeline} within={vertical.bounds} frame={board-frame}
+ during={story-time.ranking}
style={board-style}>
- <ranking:ColumnItem id="row-regen" rank="1" label="ReGen" icon={icon-regen} during={story.selection.regen}/>
- <ranking:ColumnItem id="row-chatgpt" rank="2" label="ChatGPT" icon={icon-chatgpt} during={story.selection.chatgpt}/>
+ <ranking:ColumnItem id="row-regen" rank="1" label="ReGen" icon={icon-regen} during={story-time.regen}/>
+ <ranking:ColumnItem id="row-chatgpt" rank="2" label="ChatGPT" icon={icon-chatgpt} during={story-time.chatgpt}/>
<ranking:ColumnItem id="row-remini" rank="5" preset="true" label="Remini" icon={icon-remini}/>
</ranking:Column>`,
notes: [
@@ -629,7 +627,7 @@ const allRankingMarkupSurfaces = [
"Authoring either sound also connects the Style's `.sound` output, so `style` must name a ColumnStyle written in this Source.",
],
} },
- { name: "top-three", tag: "TopThree", mode: "structured", outputs: [rankingTypes.header, rankingTypes.itemSpec, rankingTypes.textItemShell, temporalTypes.instantSpec, temporalTypes.windowSpec, temporalTypes.instant, temporalTypes.window, rankingTypes.schedule, rankingTypes.topThreeProgram, compositionTypes.visualTrack, rankingTypes.soundEvents, compositionTypes.audioTrack],
+ { name: "top-three", tag: "TopThree", mode: "structured", outputs: [rankingTypes.header, rankingTypes.itemSpec, rankingTypes.textItemShell, temporalTypes.duration, temporalTypes.extent, temporalTypes.shiftSpec, temporalTypes.instantSpec, temporalTypes.windowSpec, temporalTypes.instant, temporalTypes.window, rankingTypes.schedule, rankingTypes.topThreeProgram, compositionTypes.visualTrack, rankingTypes.soundEvents, compositionTypes.audioTrack],
vocabulary: {
summary: "Fills a podium one slot at a time at the Moment owned by each Item, and publishes the board and the Tracks it renders to.",
appearance:
@@ -641,9 +639,9 @@ const allRankingMarkupSurfaces = [
...temporalContextAttributeVocabulary,
{ name: "frame", kind: "reference", required: true, accepts: [spatialTypes.frame],
summary: "Chooses the Frame the whole board occupies." },
- { name: "during", kind: "expression", required: true, values: ["program"], accepts: [narrativeTypes.selection, narrativeTypes.excerpt],
+ { name: "during", kind: "expression", required: true, values: ["program"], accepts: [temporalTypes.window],
summary: "Chooses the board's whole-program, Selection or Segment lifetime." },
- { name: "terminal", kind: "expression", required: true, accepts: [narrativeTypes.moment],
+ { name: "terminal", kind: "expression", required: true, accepts: [temporalTypes.instant],
summary: "Chooses the terminal Moment or authored time, such as 8s." },
{ name: "style", kind: "reference", required: true, accepts: [rankingTypes.topThreeStyle],
summary: "Chooses the TopThreeStyle this board is drawn in, and only that variant's." },
@@ -679,11 +677,11 @@ const allRankingMarkupSurfaces = [
],
example: `<ranking:TopThreeStyle id="podium-style" recipe={recipes.ranking.podium} font={ui-font}/>
<ranking:TopThree id="podium" timeline={speech.timeline} frame={board-frame}
- during={story.selection.board} terminal={story.moment.done}
+ during={story-time.board} terminal={story-time.done}
style={podium-style}>
- <ranking:TopThreeItem id="slot-gold" label="ReGen" icon={icon-regen} at={story.moment.regen}/>
- <ranking:TopThreeItem id="slot-silver" label="ChatGPT" at={story.moment.chatgpt}/>
- <ranking:TopThreeItem id="slot-bronze" label="Remini" at={story.moment.remini}/>
+ <ranking:TopThreeItem id="slot-gold" label="ReGen" icon={icon-regen} at={story-time.regen}/>
+ <ranking:TopThreeItem id="slot-silver" label="ChatGPT" at={story-time.chatgpt}/>
+ <ranking:TopThreeItem id="slot-bronze" label="Remini" at={story-time.remini}/>
</ranking:TopThree>`,
notes: [
"The board requires at least one TopThreeItem, accepts no other child and no text of its own, and Item ids must be unique within it.",
@@ -699,7 +697,7 @@ export const rankingMarkupSurfaces = allRankingMarkupSurfaces;
export const rankingManifest: ModuleManifest = {
format: "hypit.module@1", name: rankingModuleRef.name, version: rankingModuleRef.version,
- dependencies: [artifactDependency, mediaDependency, narrativeDependency, timelineDependency, spatialDependency, temporalDependency, compositionDependency, textDependency],
+ dependencies: [artifactDependency, mediaDependency, timelineDependency, spatialDependency, temporalDependency, compositionDependency, textDependency],
types: [
{ name: rankingTypes.header.name },
{ name: rankingTypes.itemSpec.name },
@@ -788,7 +786,7 @@ export const rankingManifest: ModuleManifest = {
{ name: programProducer.name, inputs: [
{ name: "header", type: rankingTypes.header },
...(programType === rankingTypes.columnProgram || programType === rankingTypes.tierProgram
- ? [{ name: "canvas", type: spatialTypes.canvas }] : []),
+ ? [{ name: "within", type: spatialTypes.frame }] : []),
{ name: "frame", type: spatialTypes.frame }, { name: "schedule", type: rankingTypes.schedule },
{ name: "style", type: styleType }, { name: "set", type: setType },
], outputs: [{ name: "program", type: programType }], needs: [] },
diff --git a/packages/ranking/src/render.ts b/packages/ranking/src/render.ts
index 43c3ebe4..5a199c16 100644
--- a/packages/ranking/src/render.ts
+++ b/packages/ranking/src/render.ts
@@ -1,3 +1,4 @@
+import { assertTimelineIdentity, timelineFrameSampleBoundary, timelineSampleFrames } from "@hypit/timeline";
import type { Timeline } from "@hypit/timeline";
import {
assertAudioTrackIdentity,
@@ -15,7 +16,6 @@ import type {
VisualTrack,
} from "@hypit/composition";
import { synchronizedMediaSampleFrames, verifySynchronizedMedia } from "@hypit/media";
-import { assertProgramSpaceIdentity, programFrameSampleBoundary, programSpaceSampleFrames } from "@hypit/program-space";
import {
assertColumnProgram,
@@ -182,15 +182,16 @@ function present(input: {
readonly subjectId: string;
readonly start: number;
readonly end: number;
- readonly stacking: number;
- readonly tieBreak: string;
+ readonly order: number;
+ readonly z: number;
readonly elements: readonly VisualElement[];
}): VisualPresent {
return {
id: input.id,
+ order: input.order,
+ z: input.z,
subjectId: input.subjectId,
span: { startFrame: input.start, endFrameExclusive: input.end },
- stacking: { order: input.stacking, tieBreak: input.tieBreak },
elements: input.elements,
};
}
@@ -250,17 +251,18 @@ function tierItemAnimation(
}
function sealTrack(timeline: Timeline, id: string, presents: readonly VisualPresent[]): VisualTrack {
- const value = sealVisualTrack({ programSpaceId: timeline.id, visualIr: "hypit.visual-ir@1", id, presents });
+ const value = sealVisualTrack({ timelineId: timeline.id, visualIr: "hypit.visual-ir@1", id, presents });
assertVisualTrackIdentity(value, timeline);
return value;
}
export function renderTierBoard(timeline: Timeline, program: TierBoardProgram): VisualTrack {
- assertProgramSpaceIdentity(timeline);
+ assertTimelineIdentity(timeline);
assertTierBoardProgram(program);
- const { canvas, frame, style, schedule } = program;
+ const { within, frame, style, schedule } = program;
const geometry = tierBoardGeometry(frame.widthPx, frame.heightPx, style);
- const stage = tierStageGeometry(canvas.widthPx, canvas.heightPx, style);
+ const localStage = tierStageGeometry(within.widthPx, within.heightPx, style);
+ const stage = { ...localStage, centerX: within.xPx + localStage.centerX, centerY: within.yPx + localStage.centerY };
const presents: VisualPresent[] = [];
const boardElements: VisualElement[] = [absoluteBox({
id: "tier-board-root", order: 0,
@@ -306,7 +308,7 @@ export function renderTierBoard(timeline: Timeline, program: TierBoardProgram):
}
presents.push(present({
id: `${program.id}:board`, subjectId: program.id, start: schedule.outer.startFrame, end: schedule.outer.endFrameExclusive,
- stacking: style.boardStackingOrder, tieBreak: `${program.id}:0000:board`, elements: boardElements,
+ order: 0, z: style.boardStackingOrder, elements: boardElements,
}));
const entries = new Map(schedule.entries.map((entry) => [entry.itemId, entry]));
const rowCounts = new Map<string, number>();
@@ -352,8 +354,8 @@ export function renderTierBoard(timeline: Timeline, program: TierBoardProgram):
id: `${program.id}:item:${item.id}:reveal`, subjectId: item.id,
start: entry.window.startFrame,
end: entry.window.endFrameExclusive,
- stacking: item.stackingOrder ?? (item.entry === "drop" ? style.stageStackingOrder : style.itemStackingOrder),
- tieBreak: `${program.id}:item:${String(index).padStart(4, "0")}:${item.id}:reveal`,
+ order: index + 1,
+ z: item.stackingOrder ?? (item.entry === "drop" ? style.stageStackingOrder : style.itemStackingOrder),
elements: itemElements(rootAnimation),
}));
}
@@ -361,8 +363,8 @@ export function renderTierBoard(timeline: Timeline, program: TierBoardProgram):
id: `${program.id}:item:${item.id}:settled`, subjectId: item.id,
start: entry.settled.startFrame,
end: entry.settled.endFrameExclusive,
- stacking: item.stackingOrder ?? style.itemStackingOrder,
- tieBreak: `${program.id}:item:${String(index).padStart(4, "0")}:${item.id}:settled`,
+ order: index + 1,
+ z: item.stackingOrder ?? style.itemStackingOrder,
elements: itemElements(),
}));
}
@@ -460,9 +462,9 @@ function columnRevealAnimation(input: {
}
export function renderColumn(timeline: Timeline, program: ColumnProgram): VisualTrack {
- assertProgramSpaceIdentity(timeline);
+ assertTimelineIdentity(timeline);
assertColumnProgram(program);
- const { canvas, frame, style, schedule } = program;
+ const { within, frame, style, schedule } = program;
const presents: VisualPresent[] = [];
const entries = new Map(schedule.entries.map((entry) => [entry.itemId, entry]));
const cellSize = style.rowHeightPx;
@@ -505,16 +507,16 @@ export function renderColumn(timeline: Timeline, program: ColumnProgram): Visual
}));
}
presents.push(present({ id: `${program.id}:board`, subjectId: program.id, start: schedule.outer.startFrame, end: schedule.outer.endFrameExclusive,
- stacking: style.boardStackingOrder, tieBreak: `${program.id}:0000:board`, elements: boardElements }));
+ order: 0, z: style.boardStackingOrder, elements: boardElements }));
for (const [index, item] of program.items.entries()) {
const entry = entries.get(item.id)!;
const x = frame.xPx + style.paddingPx + cellSize + columnGap;
const y = frame.yPx + style.paddingPx + index * (cellSize + style.rowGapPx);
const finalCenterX = x + contentSize / 2;
const finalCenterY = y + contentSize / 2;
- const stageCenterX = Math.round(canvas.widthPx * style.stagePoint.x);
- const stageCenterY = Math.round(canvas.heightPx * style.stagePoint.y);
- const entryCenterY = canvas.heightPx + style.stageSizePx * 0.25;
+ const stageCenterX = within.xPx + Math.round(within.widthPx * style.stagePoint.x);
+ const stageCenterY = within.yPx + Math.round(within.heightPx * style.stagePoint.y);
+ const entryCenterY = within.yPx + within.heightPx + style.stageSizePx * 0.25;
const root = `column-item-${item.id}`;
const itemElements = (animationValue?: VisualAnimation): VisualElement[] => {
const iconSize = Math.min(style.iconSizePx, contentSize);
@@ -548,14 +550,12 @@ export function renderColumn(timeline: Timeline, program: ColumnProgram): Visual
});
presents.push(present({
id: `${program.id}:item:${item.id}:stage`, subjectId: item.id, start: entry.window.startFrame, end: entry.window.endFrameExclusive,
- stacking: item.stackingOrder ?? style.stageStackingOrder,
- tieBreak: `${program.id}:item:${String(item.rank).padStart(4, "0")}:${item.id}:stage`, elements: itemElements(rootAnimation),
+ order: item.rank, z: item.stackingOrder ?? style.stageStackingOrder, elements: itemElements(rootAnimation),
}));
}
if (entry.settled.endFrameExclusive > entry.settled.startFrame) presents.push(present({
id: `${program.id}:item:${item.id}:settled`, subjectId: item.id, start: entry.settled.startFrame, end: entry.settled.endFrameExclusive,
- stacking: item.stackingOrder ?? style.itemStackingOrder,
- tieBreak: `${program.id}:item:${String(item.rank).padStart(4, "0")}:${item.id}:settled`, elements: itemElements(),
+ order: item.rank, z: item.stackingOrder ?? style.itemStackingOrder, elements: itemElements(),
}));
}
return sealTrack(timeline, program.id, presents);
@@ -577,7 +577,7 @@ function activeAccentAnimation(duration: number, activeFrames: number): VisualAn
}
export function renderTopThree(timeline: Timeline, program: TopThreeProgram): VisualTrack {
- assertProgramSpaceIdentity(timeline);
+ assertTimelineIdentity(timeline);
assertTopThreeProgram(program);
const { frame, style, schedule } = program;
const boardElements: VisualElement[] = [absoluteBox({
@@ -598,7 +598,7 @@ export function renderTopThree(timeline: Timeline, program: TopThreeProgram): Vi
}
const presents: VisualPresent[] = [present({
id: `${program.id}:slots`, subjectId: program.id, start: schedule.outer.startFrame, end: schedule.outer.endFrameExclusive,
- stacking: style.boardStackingOrder, tieBreak: `${program.id}:0000:slots`, elements: boardElements,
+ order: 0, z: style.boardStackingOrder, elements: boardElements,
})];
for (const [index, item] of program.items.entries()) {
const entry = schedule.entries[index]!;
@@ -639,13 +639,11 @@ export function renderTopThree(timeline: Timeline, program: TopThreeProgram): Vi
};
presents.push(present({
id: `${program.id}:item:${item.id}:stage`, subjectId: item.id, start: entry.stage.startFrame, end: entry.stage.endFrameExclusive,
- stacking: item.stackingOrder ?? style.itemStackingOrder,
- tieBreak: `${program.id}:item:${String(index).padStart(4, "0")}:${item.id}:stage`, elements: itemElements(true),
+ order: index + 1, z: item.stackingOrder ?? style.itemStackingOrder, elements: itemElements(true),
}));
if (entry.settled.endFrameExclusive > entry.settled.startFrame) presents.push(present({
id: `${program.id}:item:${item.id}:settled`, subjectId: item.id, start: entry.settled.startFrame, end: entry.settled.endFrameExclusive,
- stacking: item.stackingOrder ?? style.itemStackingOrder,
- tieBreak: `${program.id}:item:${String(index).padStart(4, "0")}:${item.id}:settled`, elements: itemElements(false),
+ order: index + 1, z: item.stackingOrder ?? style.itemStackingOrder, elements: itemElements(false),
}));
}
return sealTrack(timeline, program.id, presents);
@@ -657,21 +655,21 @@ export function renderRankingAudio(
style: RankingSoundStyle,
sounds: RankingSoundSet,
): AudioTrack {
- assertProgramSpaceIdentity(timeline);
+ assertTimelineIdentity(timeline);
assertRankingSoundEventPlan(plan);
assertRankingSoundStyle(style);
assert(sounds.appear !== undefined || sounds.move !== undefined, "Ranking audio requires at least one authored sound.");
if (sounds.appear !== undefined) verifySynchronizedMedia(sounds.appear);
if (sounds.move !== undefined) verifySynchronizedMedia(sounds.move);
- const totalSamples = programSpaceSampleFrames(timeline, 48_000);
- const fadeSamples = programFrameSampleBoundary(timeline, style.fadeFrames, 48_000);
+ const totalSamples = timelineSampleFrames(timeline, 48_000);
+ const fadeSamples = timelineFrameSampleBoundary(timeline, style.fadeFrames, 48_000);
const clips: AudioClip[] = [];
for (const event of plan.events) {
const media = sounds[event.kind];
if (media === undefined) continue;
const audio = media.audio;
assert(audio !== undefined, `Ranking ${event.kind} sound has no normalized audio.`);
- const startSample = programFrameSampleBoundary(timeline, event.frame, 48_000);
+ const startSample = timelineFrameSampleBoundary(timeline, event.frame, 48_000);
const sourceSampleFrames = synchronizedMediaSampleFrames(media);
const length = Math.min(sourceSampleFrames, totalSamples - startSample);
assert(length > 0, `Ranking sound ${event.id} starts after Timeline.`);
@@ -680,8 +678,11 @@ export function renderRankingAudio(
id: event.id,
artifact: structuredClone(audio.artifact),
target: { startSample, endSampleExclusive: startSample + length },
- source: { sampleFrames: sourceSampleFrames, startSample: 0, endSampleExclusive: length, loop: false, phaseSample: 0 },
- playbackRate: 1, pitch: "preserve",
+ sourceTime: { sourceSampleFrames, pieces: [{
+ target: { startSample: 0, endSampleExclusive: length },
+ sourceAtStart: { numerator: 0, denominator: 1 },
+ rate: { numerator: 1, denominator: 1 },
+ }] },
gain: event.kind === "appear" ? style.appearGain : style.moveGain,
fadeInSamples: fadeSamples, fadeOutSamples: 0,
});
@@ -690,7 +691,7 @@ export function renderRankingAudio(
if (sounds[kind] !== undefined) assert(clips.some((clip) => clip.id.endsWith(`:${kind}`)),
`Ranking ${kind} sound has no matching visual event.`);
}
- const track = sealAudioTrack({ programSpaceId: timeline.id, id: `${plan.id}.audio`, clips });
+ const track = sealAudioTrack({ timelineId: timeline.id, id: `${plan.id}.audio`, clips });
assertAudioTrackIdentity(track, timeline);
return track;
}
diff --git a/packages/ranking/src/schedule.ts b/packages/ranking/src/schedule.ts
index cf628013..43ed0c0a 100644
--- a/packages/ranking/src/schedule.ts
+++ b/packages/ranking/src/schedule.ts
@@ -1,15 +1,15 @@
+import { assertTimelineIdentity, timelineFrameCount } from "@hypit/timeline";
import type { Timeline } from "@hypit/timeline";
import {
assertFontArtifactRef,
verifySynchronizedMedia,
} from "@hypit/media";
import type { SynchronizedMedia } from "@hypit/media";
-import { assertProgramSpaceIdentity, programSpaceFrameCount } from "@hypit/program-space";
import { canonicalize, isResourceId } from "@hypit/protocol";
import { verifyText } from "@hypit/text";
import type { Text } from "@hypit/text";
-import { assertCanvasSpace, assertSpatialFrame } from "@hypit/spatial";
-import type { CanvasSpace } from "@hypit/spatial";
+import { assertSpatialFrame } from "@hypit/spatial";
+import type { SpatialFrame } from "@hypit/spatial";
import {
assertTemporalInstantFor,
assertTemporalWindowFor,
@@ -342,10 +342,10 @@ export function buildTriggeredRankingSchedule(input: {
assert(input.header.variant === "top-three", "Only TopThree uses the triggered Ranking schedule.");
assert(input.items.items.length > 0, "Ranking requires at least one Item.");
assertTriggeredRankingCandidateSet(input.candidates);
- assertTemporalWindowFor(input.outer, { subjectId: input.header.id, space: input.timeline });
- assertTemporalInstantFor(input.terminal, { subjectId: input.header.id, space: input.timeline });
+ assertTemporalWindowFor(input.outer, { subjectId: input.header.id, timeline: input.timeline });
+ assertTemporalInstantFor(input.terminal, { subjectId: input.header.id, timeline: input.timeline });
for (const candidate of input.candidates.entries) {
- assertTemporalInstantFor(candidate.activation, { subjectId: candidate.itemId, space: input.timeline });
+ assertTemporalInstantFor(candidate.activation, { subjectId: candidate.itemId, timeline: input.timeline });
}
const expected = new Set(input.items.items.map((item) => item.id));
const received = new Set(input.candidates.entries.map((entry) => entry.itemId));
@@ -457,7 +457,7 @@ function buildWindowedRankingSchedule(input: {
assert(input.items.variant === input.variant, `${label} Schedule requires ${label} Items.`);
assert(input.items.items.length > 0, `${label} requires at least one Item.`);
assertRankingWindowSet(input.windows, `${label}WindowSet`);
- assertTemporalWindowFor(input.outer, { subjectId: input.header.id, space: input.timeline });
+ assertTemporalWindowFor(input.outer, { subjectId: input.header.id, timeline: input.timeline });
frame(input.outer.span.startFrame, `${label} outer window start`);
frame(input.outer.span.endFrameExclusive, `${label} outer window end`);
assert(input.outer.span.endFrameExclusive > input.outer.span.startFrame, `${label} outer window is empty.`);
@@ -471,7 +471,7 @@ function buildWindowedRankingSchedule(input: {
|| left.window.span.endFrameExclusive - right.window.span.endFrameExclusive
|| left.itemId.localeCompare(right.itemId));
for (const entry of orderedWindows) {
- assertTemporalWindowFor(entry.window, { subjectId: entry.itemId, space: input.timeline });
+ assertTemporalWindowFor(entry.window, { subjectId: entry.itemId, timeline: input.timeline });
assert(entry.window.span.startFrame >= input.outer.span.startFrame
&& entry.window.span.endFrameExclusive <= input.outer.span.endFrameExclusive,
`${label} Item ${entry.itemId} window is outside the outer window.`);
@@ -627,8 +627,8 @@ export function assertRankingSchedule(value: RankingSchedule, timeline?: Timelin
if (value.variant === "top-three") assertTriggeredRankingSchedule(value);
else assertWindowedRankingSchedule(value);
if (timeline !== undefined) {
- assertProgramSpaceIdentity(timeline);
- assert(value.outer.endFrameExclusive <= programSpaceFrameCount(timeline), "RankingSchedule exceeds Timeline.");
+ assertTimelineIdentity(timeline);
+ assert(value.outer.endFrameExclusive <= timelineFrameCount(timeline), "RankingSchedule exceeds Timeline.");
}
}
@@ -742,9 +742,9 @@ export function fitColumnRevealMotion(
return { mode: "stage", appearFrames, moveFrames: durationFrames - appearFrames };
}
-export function buildTierBoardProgram(header: RankingHeader, canvasValue: CanvasSpace, frameValue: import("@hypit/spatial").SpatialFrame, schedule: RankingSchedule, style: TierBoardStyle, set: TierBoardItemSet): TierBoardProgram {
+export function buildTierBoardProgram(header: RankingHeader, withinValue: SpatialFrame, frameValue: SpatialFrame, schedule: RankingSchedule, style: TierBoardStyle, set: TierBoardItemSet): TierBoardProgram {
assert(header.variant === "tier-board" && schedule.variant === "tier-board", "TierBoard variant is inconsistent.");
- assertCanvasSpace(canvasValue);
+ assertSpatialFrame(withinValue);
assertSpatialFrame(frameValue);
assertTierBoardStyle(style);
windowedIdsEqual(schedule, set.items);
@@ -752,19 +752,19 @@ export function buildTierBoardProgram(header: RankingHeader, canvasValue: Canvas
const items = schedule.entries.map((entry) => structuredClone(byId.get(entry.itemId)!));
const rows = new Set(style.rows.map((row) => row.id));
for (const item of items) assert(rows.has(item.tier), `TierBoard Item ${item.id} references unknown tier ${item.tier}.`);
- const result: TierBoardProgram = { id: header.id, canvas: structuredClone(canvasValue), frame: structuredClone(frameValue), schedule: structuredClone(schedule), style: structuredClone(style), items };
+ const result: TierBoardProgram = { id: header.id, within: structuredClone(withinValue), frame: structuredClone(frameValue), schedule: structuredClone(schedule), style: structuredClone(style), items };
assertTierBoardProgram(result);
return canonicalize(result) as unknown as TierBoardProgram;
}
-export function buildColumnProgram(header: RankingHeader, canvasValue: CanvasSpace, frameValue: import("@hypit/spatial").SpatialFrame, schedule: RankingSchedule, style: ColumnStyle, set: ColumnItemSet): ColumnProgram {
+export function buildColumnProgram(header: RankingHeader, withinValue: SpatialFrame, frameValue: SpatialFrame, schedule: RankingSchedule, style: ColumnStyle, set: ColumnItemSet): ColumnProgram {
assert(header.variant === "column" && schedule.variant === "column", "Column variant is inconsistent.");
- assertCanvasSpace(canvasValue);
+ assertSpatialFrame(withinValue);
assertSpatialFrame(frameValue);
assertColumnStyle(style);
windowedIdsEqual(schedule, set.items);
const items = [...set.items].map((item) => structuredClone(item)).sort((left, right) => left.rank - right.rank || left.id.localeCompare(right.id));
- const result: ColumnProgram = { id: header.id, canvas: structuredClone(canvasValue), frame: structuredClone(frameValue), schedule: structuredClone(schedule), style: structuredClone(style), items };
+ const result: ColumnProgram = { id: header.id, within: structuredClone(withinValue), frame: structuredClone(frameValue), schedule: structuredClone(schedule), style: structuredClone(style), items };
assertColumnProgram(result);
return canonicalize(result) as unknown as ColumnProgram;
}
@@ -783,7 +783,7 @@ export function buildTopThreeProgram(header: RankingHeader, frameValue: import("
export function assertTierBoardProgram(value: TierBoardProgram): void {
assertRankingSchedule(value.schedule);
assert(value.schedule.variant === "tier-board", "TierBoardProgram Schedule variant is invalid.");
- assertCanvasSpace(value.canvas);
+ assertSpatialFrame(value.within);
assertSpatialFrame(value.frame);
assertTierBoardStyle(value.style);
windowedIdsEqual(value.schedule, value.items);
@@ -793,7 +793,7 @@ export function assertTierBoardProgram(value: TierBoardProgram): void {
export function assertColumnProgram(value: ColumnProgram): void {
assertRankingSchedule(value.schedule);
assert(value.schedule.variant === "column", "ColumnProgram Schedule variant is invalid.");
- assertCanvasSpace(value.canvas);
+ assertSpatialFrame(value.within);
assertSpatialFrame(value.frame);
assertColumnStyle(value.style);
windowedIdsEqual(value.schedule, value.items);
diff --git a/packages/ranking/src/surface.ts b/packages/ranking/src/surface.ts
index 33f4628a..256ddac3 100644
--- a/packages/ranking/src/surface.ts
+++ b/packages/ranking/src/surface.ts
@@ -19,7 +19,7 @@ import { spatialTypes } from "@hypit/spatial";
import { svsRecipeType } from "@hypit/svs";
import type { SvsRecipe } from "@hypit/svs";
import { textTypes } from "@hypit/text";
-import { createTemporalInstantProjection, createTemporalWindowProjection, temporalInstantAttributeNames } from "@hypit/temporal-markup";
+import { createTemporalInstantConstruction, createTemporalWindowConstruction, temporalInstantAttributeNames } from "@hypit/temporal-markup";
import { createRankingFragment } from "./fragment.js";
import type { RankingFragmentItem, RankingFragmentSound } from "./fragment.js";
@@ -201,21 +201,21 @@ function rankingSurface(variant: RankingVariant): StructuredSurfaceHandler {
return ({ element, resolveReference }) => {
const common = ["id", "timeline", "frame", "during", "terminal", "style", "appear-sound", "move-sound"];
const attributes = variant === "column" || variant === "tier-board"
- ? [...common.filter((name) => name !== "terminal"), "canvas"]
+ ? [...common.filter((name) => name !== "terminal"), "within"]
: common;
allowed(element, attributes);
const id = text(element, "id");
const selected = variantDefinition[variant];
const context = resolveTemporalContext({ element, resolveReference });
- const canvas = variant === "column" || variant === "tier-board"
- ? reference(element.attributes.canvas, `${element.name}.canvas`, spatialTypes.canvas, resolveReference)
+ const within = variant === "column" || variant === "tier-board"
+ ? reference(element.attributes.within, `${element.name}.within`, spatialTypes.frame, resolveReference)
: undefined;
const frame = reference(element.attributes.frame, `${element.name}.frame`, spatialTypes.frame, resolveReference);
- const outerTemporal = createTemporalWindowProjection({ id: `${id}.outer`, subjectId: id, element, ...context, resolveReference });
+ const outerTemporal = createTemporalWindowConstruction({ id: `${id}.outer`, subjectId: id, element, ...context, resolveReference });
const terminalTemporal = variant === "top-three"
- ? createTemporalInstantProjection({
+ ? createTemporalInstantConstruction({
id: `${id}.terminal`, subjectId: id, element, ...context, resolveReference,
- semanticAttribute: "terminal", projectedAttribute: false,
+ attribute: "terminal",
})
: undefined;
const styleRaw = element.attributes.style;
@@ -232,7 +232,7 @@ function rankingSurface(variant: RankingVariant): StructuredSurfaceHandler {
const inputs: Record<string, typeof context.timeline.ref> = {
header: { kind: "record", id: headerId }, timeline: context.timeline.ref, frame: frame.ref,
outer: outerTemporal.ref, style: style.ref,
- ...(canvas === undefined ? {} : { canvas: canvas.ref }),
+ ...(within === undefined ? {} : { within: within.ref }),
...(terminalTemporal === undefined ? {} : { terminal: terminalTemporal.ref }),
};
const items: RankingFragmentItem[] = [];
@@ -259,8 +259,8 @@ function rankingSurface(variant: RankingVariant): StructuredSurfaceHandler {
const contentName = authored.content === undefined ? undefined : `item-${suffix}-content`;
if (authored.content !== undefined) inputs[contentName!] = authored.content.ref;
const itemTemporal = !authored.timed ? undefined : variant === "top-three"
- ? createTemporalInstantProjection({ id: `${id}.item.${suffix}`, subjectId: spec.id, element: child, ...context, resolveReference })
- : createTemporalWindowProjection({ id: `${id}.item.${suffix}`, subjectId: spec.id, element: child, ...context, resolveReference });
+ ? createTemporalInstantConstruction({ id: `${id}.item.${suffix}`, subjectId: spec.id, element: child, ...context, resolveReference })
+ : createTemporalWindowConstruction({ id: `${id}.item.${suffix}`, subjectId: spec.id, element: child, ...context, resolveReference });
if (itemTemporal !== undefined) {
records.push(...itemTemporal.records);
temporalComponents.push(...itemTemporal.components);
diff --git a/packages/ranking/src/types.ts b/packages/ranking/src/types.ts
index f29a53e9..bbc1a31b 100644
--- a/packages/ranking/src/types.ts
+++ b/packages/ranking/src/types.ts
@@ -4,7 +4,7 @@ import type {
SynchronizedMedia,
} from "@hypit/media";
import type { BlobRef } from "@hypit/protocol";
-import type { CanvasSpace, SpatialFrame } from "@hypit/spatial";
+import type { SpatialFrame } from "@hypit/spatial";
import type { TemporalInstant, TemporalWindow } from "@hypit/temporal";
export type RankingVariant = "tier-board" | "column" | "top-three";
@@ -235,7 +235,7 @@ export type TopThreeItemSet = {
export type TierBoardProgram = {
readonly id: string;
- readonly canvas: CanvasSpace;
+ readonly within: SpatialFrame;
readonly frame: SpatialFrame;
readonly schedule: TierBoardSchedule;
readonly style: TierBoardStyle;
@@ -243,7 +243,7 @@ export type TierBoardProgram = {
};
export type ColumnProgram = {
readonly id: string;
- readonly canvas: CanvasSpace;
+ readonly within: SpatialFrame;
readonly frame: SpatialFrame;
readonly schedule: ColumnSchedule;
readonly style: ColumnStyle;
diff --git a/packages/ranking/test/ranking.test.ts b/packages/ranking/test/ranking.test.ts
index 1e249d0b..6a92c43c 100644
--- a/packages/ranking/test/ranking.test.ts
+++ b/packages/ranking/test/ranking.test.ts
@@ -1,17 +1,16 @@
-import { sealTimeline } from "@hypit/timeline";
+import { sealTimeline, timelineTypes } from "@hypit/timeline";
import assert from "node:assert/strict";
import test from "node:test";
import { videoContractManifests } from "../../../test/support/video-domain.js";
import { fixtureResource } from "../../../test/fixture-resource.js";
-import { timelineFixture } from "../../../test/timeline-fixture.js";
+import { narrativeProjectionFixture, timelineFixture } from "../../../test/timeline-fixture.js";
import { projectMomentInstantFixture, projectSegmentWindow, projectSelectionWindow } from "../../../test/temporal-fixture.js";
import { createResolvedClosure } from "@hypit/core";
import type { FontArtifactRef, SynchronizedMedia } from "@hypit/media";
import { mediaTypes } from "@hypit/media";
import type { NarrativeExcerpt, NarrativeMomentRef, NarrativeSelectionRef } from "@hypit/narrative";
-import { sealProgramSpace } from "@hypit/program-space";
-import { sealCanvasSpace, sealSpatialFrame } from "@hypit/spatial";
+import { sealCanvas, sealSpatialFrame } from "@hypit/spatial";
import type { SvsRecipe } from "@hypit/svs";
import {
@@ -78,12 +77,10 @@ import type {
TierBoardItemSpec,
TopThreeItemSpec,
} from "@hypit/ranking";
-import { narrativeTypes } from "@hypit/narrative";
-import { timelineTypes } from "@hypit/timeline";
import { spatialTypes } from "@hypit/spatial";
import { svsRecipeType } from "@hypit/svs";
import { sealText, textManifest, textTypes } from "@hypit/text";
-import { temporalProducers } from "@hypit/temporal";
+import { temporalProducers, temporalTypes } from "@hypit/temporal";
import type { TemporalWindow } from "@hypit/temporal";
import type {
StructuredElement,
@@ -92,20 +89,20 @@ import type {
MarkupAttributeValue,
} from "@hypit/markup";
-const space = sealTimeline({ items: [], id: "test-space", durationSec: 8,
- frameRate: { numerator: 30, denominator: 1 },
+const space = sealTimeline({ id: "test-space", frameCount: 240, frameRate: { numerator: 30, denominator: 1 },
});
-const canvas = sealCanvasSpace({
+const canvas = sealCanvas({
widthPx: 1080, heightPx: 1920,
- origin: "top-left", xDirection: "right", yDirection: "down", pixelAspect: "square",
});
+const canvasBounds = { xPx: 0, yPx: 0, widthPx: canvas.widthPx, heightPx: canvas.heightPx };
const frame = sealSpatialFrame({
xPx: 40, yPx: 80, widthPx: 720, heightPx: 560,
});
const tierFrame = sealSpatialFrame({
xPx: 40, yPx: 360, widthPx: 720, heightPx: 280,
});
-const timeline = timelineFixture(space, {
+const semanticOptions = {
+ narrativeId: "script",
segments: [
{ id: "opening", frameCount: 10 },
{ id: "ranking", frameCount: 220 },
@@ -126,7 +123,9 @@ const timeline = timelineFixture(space, {
{ identity: "terminal", frame: 190 },
{ identity: "outer-end", frame: 230 },
],
-});
+} as const;
+const timeline = timelineFixture(space, semanticOptions);
+const narrativeProjection = narrativeProjectionFixture(timeline, semanticOptions);
const outer: NarrativeSelectionRef = {
narrativeId: "script",
id: "ranking-window",
@@ -187,7 +186,7 @@ function appendTriggeredRankingCandidate(
semantic: typeof timeline, moment: NarrativeMomentRef,
) {
return appendProjectedTriggeredRankingCandidate(set, spec, projectMomentInstantFixture({
- itemId: spec.id, semantic, moment,
+ itemId: spec.id, semantic, narrative: narrativeProjection, moment,
projection: { ref: "moment.cue" },
}));
}
@@ -205,12 +204,12 @@ function buildRankingSchedule(input: {
items: input.items,
timeline: space,
outer: projectSelectionWindow({
- itemId: input.outer.id, subjectId: input.header.id, semantic: input.semantic, selection: input.outer,
+ itemId: input.outer.id, subjectId: input.header.id, semantic: input.semantic, narrative: narrativeProjection, selection: input.outer,
projection: { start: { ref: "selection.start" }, end: { ref: "selection.end" } },
}),
candidates: input.candidates,
terminal: projectMomentInstantFixture({
- itemId: input.terminal.id, subjectId: input.header.id, semantic: input.semantic, moment: input.terminal,
+ itemId: input.terminal.id, subjectId: input.header.id, semantic: input.semantic, narrative: narrativeProjection, moment: input.terminal,
projection: { ref: "moment.cue" },
}),
});
@@ -221,7 +220,7 @@ function appendProjectedColumnWindow(
semantic: typeof timeline, selection: NarrativeSelectionRef,
) {
return appendColumnWindow(set, spec, projectSelectionWindow({
- itemId: spec.id, semantic, selection,
+ itemId: spec.id, semantic, narrative: narrativeProjection, selection,
projection: { start: { ref: "selection.start" }, end: { ref: "selection.end" } },
}));
}
@@ -231,14 +230,14 @@ function appendProjectedTierWindow(
semantic: typeof timeline, selectionValue: NarrativeSelectionRef,
) {
return appendTierBoardWindow(set, spec, projectSelectionWindow({
- itemId: spec.id, semantic, selection: selectionValue,
+ itemId: spec.id, semantic, narrative: narrativeProjection, selection: selectionValue,
projection: { start: { ref: "selection.start" }, end: { ref: "selection.end" } },
}));
}
function projectColumnSegmentOuterWindow(semantic: typeof timeline, segment: NarrativeExcerpt, subjectId: string): TemporalWindow {
return projectSegmentWindow({
- itemId: `${segment.id}:outer`, subjectId, semantic, segment,
+ itemId: `${segment.id}:outer`, subjectId, semantic, narrative: narrativeProjection, segment,
projection: { start: { ref: "segment.start" }, end: { ref: "segment.end" } },
});
}
@@ -274,7 +273,7 @@ function tierSchedule(
values: readonly TierBoardItemSpec[],
windows: Readonly<Record<string, NarrativeSelectionRef>>,
outerWindow = projectSelectionWindow({
- itemId: outer.id, subjectId: owner.id, semantic: timeline, selection: outer,
+ itemId: outer.id, subjectId: owner.id, semantic: timeline, narrative: narrativeProjection, selection: outer,
projection: { start: { ref: "selection.start" }, end: { ref: "selection.end" } },
}),
): TierBoardSchedule {
@@ -325,7 +324,7 @@ test("variant Style decoders reject unknown Recipes and keep exact fonts and ind
}), font), /exactly three/u);
});
-test("TierBoard separates its board Frame from the Canvas stage and holds drop Items until the final curved glide", () => {
+test("TierBoard separates its board Frame from the outer placement Frame and holds drop Items until the final curved glide", () => {
const owner = header("tier-board", "tiers");
const semantic = [
tierSpec("late", "s", "drop"),
@@ -338,7 +337,7 @@ test("TierBoard separates its board Frame from the Canvas stage and holds drop I
let set = createTierBoardItemSet();
for (const item of semantic) set = appendTierBoardItem(set, item, image(item.id));
const value = tierSchedule(owner, semantic, { early, late });
- const program = buildTierBoardProgram(owner, canvas, tierFrame, value, style, set);
+ const program = buildTierBoardProgram(owner, canvasBounds, tierFrame, value, style, set);
const track = renderTierBoard(space, program);
assert.deepEqual(value.entries.map((entry) => entry.itemId), ["preset", "early", "late"]);
assert.deepEqual(program.items.map((item) => item.id), ["preset", "early", "late"]);
@@ -410,7 +409,7 @@ test("Column consumes explicit disjoint reveal windows without changing them", (
"early-rank-five": early,
"overlap-rank-two": middle,
}, outerWindow);
- const program = buildColumnProgram(owner, canvas, frame, value, style, set);
+ const program = buildColumnProgram(owner, canvasBounds, frame, value, style, set);
const track = renderColumn(space, program);
assert.deepEqual(program.items.map((item) => [item.id, item.rank]), [
["late-rank-one", 1], ["overlap-rank-two", 2], ["preset-rank-three", 3], ["early-rank-five", 5],
@@ -440,7 +439,7 @@ test("Column rejects overlapping or out-of-bounds reveal windows", () => {
const outerWindow = projectColumnSegmentOuterWindow(timeline, rankingSegment, owner.id);
let windows = createColumnWindowSet();
const projected = projectSelectionWindow({
- itemId: "one", semantic: timeline, selection: early,
+ itemId: "one", semantic: timeline, narrative: narrativeProjection, selection: early,
projection: { start: { ref: "selection.start" }, end: { ref: "selection.end" } },
});
windows = appendColumnWindow(windows, values[0]!, {
@@ -476,7 +475,7 @@ test("TopThree accepts one to three optional-image Items and removes active acce
});
const sound = (id: string): SynchronizedMedia => ({
- timeline: { frameRate: { numerator: 30, denominator: 1 }, frameCount: 3 },
+ frameDomain: { frameRate: { numerator: 30, denominator: 1 }, frameCount: 3 },
audio: {
artifact: { kind: "blob", resource: fixtureResource(`ranking-sound:${id}`), size: 128, mediaType: "audio/wav" },
},
@@ -515,7 +514,7 @@ test("each component owns a distinct event law", () => {
});
-test("all three author Surfaces preserve explicit semantic, spatial, font, image and optional sound graph edges", async () => {
+test("all three author Surfaces preserve absolute temporal, spatial, font, image and optional sound graph edges", async () => {
createResolvedClosure([...videoContractManifests, textManifest, rankingManifest]);
const range = { source: "ranking.svml", start: 0, end: 1 };
const ref = (path: string): MarkupAttributeValue => ({ kind: "reference", path });
@@ -527,15 +526,14 @@ test("all three author Surfaces preserve explicit semantic, spatial, font, image
});
const references = new Map<string, SurfaceResolvedReference>([
["semantic", plain("semantic", timelineTypes.track)],
- ["canvas", plain("canvas", spatialTypes.canvas)],
["frame", plain("frame", spatialTypes.frame)],
- ["outer", plain("outer", narrativeTypes.selection)],
- ["ranking-segment", plain("ranking-segment", narrativeTypes.excerpt)],
- ["tier-reveal", plain("tier-reveal", narrativeTypes.selection)],
- ["column-reveal", plain("column-reveal", narrativeTypes.selection)],
- ["moment-one", plain("moment-one", narrativeTypes.moment)],
- ["moment-two", plain("moment-two", narrativeTypes.moment)],
- ["terminal", plain("terminal", narrativeTypes.moment)],
+ ["outer", plain("outer", temporalTypes.window)],
+ ["ranking-segment", plain("ranking-segment", temporalTypes.window)],
+ ["tier-reveal", plain("tier-reveal", temporalTypes.window)],
+ ["column-reveal", plain("column-reveal", temporalTypes.window)],
+ ["moment-one", plain("moment-one", temporalTypes.instant)],
+ ["moment-two", plain("moment-two", temporalTypes.instant)],
+ ["terminal", plain("terminal", temporalTypes.instant)],
["icon-1", plain("icon-1", mediaTypes.blobArtifact)],
["icon-2", plain("icon-2", mediaTypes.blobArtifact)],
["appear", plain("appear", mediaTypes.synchronized)],
@@ -564,11 +562,11 @@ test("all three author Surfaces preserve explicit semantic, spatial, font, image
}
const cases = [
[decodeTierBoardSurface, node("ranking:TierBoard", {
- id: "tier", timeline: ref("semantic"), canvas: ref("canvas"), frame: ref("frame"), during: "program",
+ id: "tier", timeline: ref("semantic"), within: ref("frame"), frame: ref("frame"), during: "timeline",
style: ref("tier-style"),
}, [node("ranking:TierItem", { id: "tier-one", tier: "s", entry: "drop", icon: ref("icon-1"), during: ref("ranking-segment") })])],
[decodeColumnSurface, node("ranking:Column", {
- id: "column", timeline: ref("semantic"), canvas: ref("canvas"), frame: ref("frame"), during: ref("ranking-segment"),
+ id: "column", timeline: ref("semantic"), within: ref("frame"), frame: ref("frame"), during: ref("ranking-segment"),
style: ref("column-style"),
"appear-sound": ref("appear"), "move-sound": ref("move"),
}, [
@@ -592,19 +590,8 @@ test("all three author Surfaces preserve explicit semantic, spatial, font, image
assert.ok(fragment.exports.some((output) => output.name === "program"));
assert.ok(fragment.exports.some((output) => output.name === "visual"));
assert.ok(fragment.inputs.some((input) => input.name === "frame"));
- const temporalSubjects = new Set(result.records.flatMap((record) =>
- record.value.kind === "inline"
- && typeof record.value.value === "object"
- && record.value.value !== null
- && "subjectId" in record.value.value
- ? [String((record.value.value as { readonly subjectId: unknown }).subjectId)]
- : []));
- assert.ok(temporalSubjects.has(String(element.attributes.id)));
- for (const child of element.children) {
- if (child.kind === "element" && child.attributes.id !== undefined && child.attributes.preset !== "true") {
- assert.ok(temporalSubjects.has(String(child.attributes.id)));
- }
- }
+ assert.equal(result.fragments.some((fragment) => fragment.operations.some((operation) =>
+ operation.producer.module.name === "@hypit/narrative-temporal")), false);
}
const programTier = await decodeTierBoardSurface({
sourceName: "ranking.svml", element: cases[0][1],
@@ -615,8 +602,8 @@ test("all three author Surfaces preserve explicit semantic, spatial, font, image
assert.equal(tierFragment.inputs.find((input) => input.name === "outer")?.type.name, "TemporalWindow");
assert.ok(programTier.fragments.some((fragment) => fragment.operations.some((operation) =>
operation.producer.name === temporalProducers.projectProgramInstant.name)));
- assert.ok(programTier.fragments.some((fragment) => fragment.operations.some((operation) =>
- operation.producer.name === temporalProducers.projectSegmentInstant.name)));
+ assert.equal(programTier.fragments.some((fragment) => fragment.operations.some((operation) =>
+ operation.producer.module.name === "@hypit/narrative-temporal")), false);
const column = await decodeColumnSurface({
sourceName: "ranking.svml", element: cases[1][1],
resolveReference: (path) => references.get(path),
@@ -659,23 +646,22 @@ test("Ranking author Surfaces fail closed on impossible image and sound combinat
const plain = (path: string, type: SurfaceResolvedReference["type"]): SurfaceResolvedReference => ({ path, ref: { kind: "record", id: path }, type });
const references = new Map<string, SurfaceResolvedReference>([
["semantic", plain("semantic", timelineTypes.track)],
- ["canvas", plain("canvas", spatialTypes.canvas)],
- ["frame", plain("frame", spatialTypes.frame)], ["outer", plain("outer", narrativeTypes.selection)],
+ ["frame", plain("frame", spatialTypes.frame)], ["outer", plain("outer", temporalTypes.window)],
["icon", plain("icon", mediaTypes.blobArtifact)],
["style", plain("style", rankingTypes.tierStyle)], ["style.sound", plain("style.sound", rankingTypes.soundStyle)],
["move", plain("move", mediaTypes.synchronized)],
]);
- const common = { id: "bad", timeline: ref("semantic"), canvas: ref("canvas"), frame: ref("frame"), during: ref("outer"), style: ref("style") };
+ const common = { id: "bad", timeline: ref("semantic"), within: ref("frame"), frame: ref("frame"), during: "timeline", style: ref("style") };
const context = (element: StructuredElement) => ({
sourceName: "ranking.svml", element, resolveReference: (path: string) => references.get(path),
resolveAsset: async () => { throw new Error("no asset resolution expected"); },
});
assert.throws(() => decodeTierBoardSurface(context({
kind: "element", name: "ranking:TierBoard", attributes: common,
- children: [{ kind: "element", name: "ranking:TierItem", attributes: { tier: "s", entry: "direct", during: ref("outer") }, children: [], range }], range,
+ children: [{ kind: "element", name: "ranking:TierItem", attributes: { tier: "s", entry: "direct", during: "timeline" }, children: [], range }], range,
})), /icon/u);
assert.throws(() => decodeTierBoardSurface(context({
kind: "element", name: "ranking:TierBoard", attributes: { ...common, "move-sound": ref("move") },
- children: [{ kind: "element", name: "ranking:TierItem", attributes: { tier: "s", entry: "direct", icon: ref("icon"), during: ref("outer") }, children: [], range }], range,
+ children: [{ kind: "element", name: "ranking:TierItem", attributes: { tier: "s", entry: "direct", icon: ref("icon"), during: "timeline" }, children: [], range }], range,
})), /move-sound/u);
});
diff --git a/packages/raster/src/program.ts b/packages/raster/src/program.ts
index 46722572..78a27123 100644
--- a/packages/raster/src/program.ts
+++ b/packages/raster/src/program.ts
@@ -1,5 +1,5 @@
import { canonicalize, isResourceId } from "@hypit/protocol";
-import { assertCanvasSpace, assertSpatialFrame } from "@hypit/spatial";
+import { assertCanvas, assertSpatialFrame } from "@hypit/spatial";
import type {
RasterComposeRequest, RasterEncodeOperation, RasterLayer, RasterRequest,
@@ -98,7 +98,7 @@ export function assertRasterRequest(value: RasterRequest): void {
return;
}
assert(value.kind === "compose", "RasterRequest.kind is invalid");
- assertCanvasSpace(value.canvas); color(value.background, "Raster compose background", false);
+ assertCanvas(value.canvas); color(value.background, "Raster compose background", false);
assert(value.layers.length > 0 && value.layers.length <= 64, "Raster compose requires one to 64 Layers");
value.layers.forEach((layer, index) => {
image(layer.source, `Raster Layer ${index + 1}.source`); assertSpatialFrame(layer.frame);
diff --git a/packages/raster/src/types.ts b/packages/raster/src/types.ts
index 2b362860..70dfa434 100644
--- a/packages/raster/src/types.ts
+++ b/packages/raster/src/types.ts
@@ -1,5 +1,5 @@
import type { BlobRef } from "@hypit/protocol";
-import type { CanvasSpace, SpatialFrame } from "@hypit/spatial";
+import type { Canvas, SpatialFrame } from "@hypit/spatial";
export type RasterInterpolation = "nearest" | "linear" | "cubic" | "area" | "lanczos";
export type RasterFit = "contain" | "cover" | "stretch";
@@ -54,7 +54,7 @@ export type RasterTransformRequest = {
};
export type RasterComposeRequest = {
readonly kind: "compose";
- readonly canvas: CanvasSpace;
+ readonly canvas: Canvas;
readonly background: string;
readonly layers: readonly RasterLayer[];
};
diff --git a/packages/raster/test/raster.test.ts b/packages/raster/test/raster.test.ts
index b3efc0e8..3c1c4644 100644
--- a/packages/raster/test/raster.test.ts
+++ b/packages/raster/test/raster.test.ts
@@ -18,7 +18,6 @@ test("one exact Raster capability carries both closed deterministic request vari
const compose = rasterComposeRequest({
canvas: {
widthPx: 100, heightPx: 200,
- origin: "top-left", xDirection: "right", yDirection: "down", pixelAspect: "square",
},
background: "#00000000",
layers: [{
diff --git a/packages/region-track/README.md b/packages/region-track/README.md
new file mode 100644
index 00000000..525da44d
--- /dev/null
+++ b/packages/region-track/README.md
@@ -0,0 +1,27 @@
+# `@hypit/region-track`
+
+Frame-exact external spatial evidence. The package relates prepared region observations to one
+Timeline and resolves normalized boxes inside an explicit program-picture Frame. It performs no
+detection, identity inference, interpolation or source-to-picture placement discovery.
+
+```svml
+<import as="region" from="@hypit/region-track@1"/>
+<region:Track id="heads" within={vertical.bounds} timeline={program.timeline}
+ recipe={tracking.heads.default}/>
+```
+
+```svs
+heads.default {
+ series: [
+ {"id":"GUEST","regions":[[0.12,0.09,0.20,0.26],null]}
+ ];
+}
+```
+
+Each series has exactly one normalized `[x, y, width, height]` box or `null` per Timeline Frame.
+The resulting `RegionTrack` contains resolved `SpatialFrame` values in the program picture plane.
+The chosen Frame may be the Canvas bounds, an inset or any other explicit region.
+
+Source-local observations must be projected through the actual visual presentation before they are
+written as final evidence. That adapter may use the same `SpatialMap2D` used to fit the source; it
+belongs with the presentation/evidence workflow rather than in `@hypit/spatial`.
diff --git a/packages/media-track/package.json b/packages/region-track/package.json
similarity index 57%
rename from packages/media-track/package.json
rename to packages/region-track/package.json
index 3b951db2..b8177742 100644
--- a/packages/media-track/package.json
+++ b/packages/region-track/package.json
@@ -1,5 +1,5 @@
{
- "name": "@hypit/media-track",
+ "name": "@hypit/region-track",
"version": "0.0.0-dev",
"license": "SEE LICENSE IN LICENSE",
"private": true,
@@ -11,19 +11,12 @@
"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/markup": "workspace:*",
"@hypit/protocol": "workspace:*",
- "@hypit/timeline": "workspace:*",
"@hypit/spatial": "workspace:*",
"@hypit/svs": "workspace:*",
- "@hypit/markup": "workspace:*",
- "@hypit/temporal": "workspace:*",
- "@hypit/temporal-markup": "workspace:*"
+ "@hypit/timeline": "workspace:*"
}
}
diff --git a/packages/region-track/src/activation.ts b/packages/region-track/src/activation.ts
new file mode 100644
index 00000000..b223fb06
--- /dev/null
+++ b/packages/region-track/src/activation.ts
@@ -0,0 +1,21 @@
+import { createMarkupSurfaceHostFacet } from "@hypit/markup";
+
+import {
+ decodeRegionTrackSurface,
+ regionTrackComponent,
+ regionTrackManifest,
+ regionTrackMarkupSurface,
+ regionTrackModuleRef,
+} from "./index.js";
+
+export const hypitPackage = {
+ format: "hypit.node-package@1" as const,
+ modules: [{ manifest: regionTrackManifest }],
+ components: [regionTrackComponent],
+ hostFacets: [createMarkupSurfaceHostFacet({
+ module: regionTrackModuleRef,
+ declaration: regionTrackMarkupSurface,
+ handler: decodeRegionTrackSurface,
+ })],
+};
+export default hypitPackage;
diff --git a/packages/region-track/src/component.ts b/packages/region-track/src/component.ts
new file mode 100644
index 00000000..66962a38
--- /dev/null
+++ b/packages/region-track/src/component.ts
@@ -0,0 +1,25 @@
+import type { ComponentPackage } from "@hypit/component-kit";
+import { canonicalize } from "@hypit/protocol";
+import type { StoredValue } from "@hypit/protocol";
+import type { SpatialFrame } from "@hypit/spatial";
+import type { SvsRecipe } from "@hypit/svs";
+import type { Timeline } from "@hypit/timeline";
+
+import { regionTrackProducers, regionTrackTypes } from "./manifest.js";
+import { assertRegionTrack, resolveRegionTrack } from "./region.js";
+import type { RegionTrack } from "./types.js";
+
+function inline<T>(value: StoredValue | undefined, label: string): T {
+ if (value?.kind !== "inline") throw new Error(`${label} must be inline.`);
+ return value.value as unknown as T;
+}
+const output = (value: unknown) => ({ kind: "inline" as const, value: canonicalize(value) });
+
+export const regionTrackComponent = {
+ producers: [{ producer: regionTrackProducers.resolve, handler: ({ inputs }) => ({ outputs: { track: output(resolveRegionTrack(
+ inline<SvsRecipe>(inputs.recipe?.value, "Recipe"),
+ inline<SpatialFrame>(inputs.within?.value, "SpatialFrame"),
+ inline<Timeline>(inputs.timeline?.value, "Timeline"),
+ )) }, needs: {} }) }],
+ validators: [{ type: regionTrackTypes.track, handler: ({ value }) => assertRegionTrack(inline<RegionTrack>(value, "RegionTrack")) }],
+} satisfies ComponentPackage;
diff --git a/packages/region-track/src/fragment.ts b/packages/region-track/src/fragment.ts
new file mode 100644
index 00000000..c69e1270
--- /dev/null
+++ b/packages/region-track/src/fragment.ts
@@ -0,0 +1,20 @@
+import { sealGraphFragment } from "@hypit/elaborator";
+import { spatialTypes } from "@hypit/spatial";
+import { svsRecipeType } from "@hypit/svs";
+import { timelineTypes } from "@hypit/timeline";
+
+import { regionTrackProducers, regionTrackTypes } from "./manifest.js";
+
+const input = (name: string) => ({ kind: "fragment-input" as const, name });
+
+export const regionTrackFragment = sealGraphFragment({
+ inputs: [
+ { name: "within", type: spatialTypes.frame },
+ { name: "timeline", type: timelineTypes.track },
+ { name: "recipe", type: svsRecipeType },
+ ],
+ operations: [{ id: "resolve", producer: regionTrackProducers.resolve, inputs: {
+ within: input("within"), timeline: input("timeline"), recipe: input("recipe"),
+ }, result: { kind: "output", name: "track" } }],
+ exports: [{ name: "track", type: regionTrackTypes.track, root: { kind: "fragment-operation", operation: "resolve" } }],
+});
diff --git a/packages/region-track/src/index.ts b/packages/region-track/src/index.ts
new file mode 100644
index 00000000..905d0f2d
--- /dev/null
+++ b/packages/region-track/src/index.ts
@@ -0,0 +1,14 @@
+export { regionTrackComponent } from "./component.js";
+export { regionTrackFragment } from "./fragment.js";
+export {
+ regionTrackDependency,
+ regionTrackManifest,
+ regionTrackMarkupSurface,
+ regionTrackModuleRef,
+ regionTrackProducers,
+ regionTrackTypes,
+} from "./manifest.js";
+export { assertRegionTrack, resolveRegionTrack, sealRegionTrack } from "./region.js";
+export { regionTrackSchema } from "./schema.js";
+export { decodeRegionTrackSurface } from "./surface.js";
+export type * from "./types.js";
diff --git a/packages/region-track/src/manifest.ts b/packages/region-track/src/manifest.ts
new file mode 100644
index 00000000..0854bf5b
--- /dev/null
+++ b/packages/region-track/src/manifest.ts
@@ -0,0 +1,52 @@
+import type { ModuleManifest, ProducerRef, TypeRef } from "@hypit/protocol";
+import { spatialDependency, spatialTypes } from "@hypit/spatial";
+import { svsRecipeType } from "@hypit/svs";
+import { timelineDependency, timelineTypes } from "@hypit/timeline";
+
+export const regionTrackModuleRef = { name: "@hypit/region-track", version: "1" } as const;
+export const regionTrackTypes = {
+ track: { module: regionTrackModuleRef, name: "RegionTrack" },
+} satisfies Record<string, TypeRef>;
+export const regionTrackProducers = {
+ resolve: { module: regionTrackModuleRef, name: "resolve-region-track" },
+} satisfies Record<string, ProducerRef>;
+
+export const regionTrackMarkupSurface = {
+ name: "track", tag: "Track", mode: "structured", outputs: [regionTrackTypes.track],
+ vocabulary: {
+ summary: "Resolves externally prepared normalized regions into one frame-exact Region Track.",
+ attributes: [
+ { name: "id", kind: "identifier", required: true, summary: "Names the RegionTrack value." },
+ { name: "within", kind: "reference", required: true, accepts: [spatialTypes.frame], summary: "Chooses the program-picture Frame normalized regions occupy." },
+ { name: "timeline", kind: "reference", required: true, accepts: [timelineTypes.track], summary: "Chooses the Timeline whose Frames index the evidence." },
+ { name: "recipe", kind: "reference", required: true, accepts: [svsRecipeType], summary: "Chooses a Recipe with one or more named region series.", recipe: [
+ { name: "series", required: true, summary: "Lists {id, regions}; each regions array contains one normalized [x, y, width, height] or null per Timeline Frame." },
+ ] },
+ ],
+ example: `<region:Track id="heads" within={vertical.bounds} timeline={program.timeline} recipe={tracking.heads.default}/>` ,
+ notes: [
+ "The element is empty; it accepts no children or text.",
+ "Detection, identity association, interpolation and source-to-picture projection remain explicit preparation choices.",
+ "The resolver performs no detection and never invents a missing region.",
+ ],
+ },
+} as const;
+
+export const regionTrackManifest: ModuleManifest = {
+ format: "hypit.module@1",
+ name: regionTrackModuleRef.name,
+ version: regionTrackModuleRef.version,
+ dependencies: [spatialDependency, { module: svsRecipeType.module }, timelineDependency],
+ types: [{ name: regionTrackTypes.track.name }],
+ capabilities: [],
+ producers: [{
+ name: regionTrackProducers.resolve.name,
+ inputs: [
+ { name: "within", type: spatialTypes.frame },
+ { name: "timeline", type: timelineTypes.track },
+ { name: "recipe", type: svsRecipeType },
+ ],
+ outputs: [{ name: "track", type: regionTrackTypes.track }], needs: [],
+ }],
+};
+export const regionTrackDependency = { module: regionTrackModuleRef } as const;
diff --git a/packages/region-track/src/region.ts b/packages/region-track/src/region.ts
new file mode 100644
index 00000000..70abca91
--- /dev/null
+++ b/packages/region-track/src/region.ts
@@ -0,0 +1,82 @@
+import type { CanonicalValue } from "@hypit/protocol";
+import { assertSpatialFrame } from "@hypit/spatial";
+import type { SpatialFrame } from "@hypit/spatial";
+import type { SvsRecipe } from "@hypit/svs";
+import { assertTimelineIdentity, timelineFrameCount } from "@hypit/timeline";
+import type { Timeline } from "@hypit/timeline";
+
+import type { RegionTrack } from "./types.js";
+
+type CanonicalRecord = Readonly<Record<string, CanonicalValue>>;
+
+function record(value: CanonicalValue, label: string): CanonicalRecord {
+ if (value === null || Array.isArray(value) || typeof value !== "object") throw new Error(`${label} must be a record.`);
+ return value as CanonicalRecord;
+}
+
+function exact(value: CanonicalRecord, allowed: readonly string[], label: string): void {
+ const unknown = Object.keys(value).find((name) => !allowed.includes(name));
+ if (unknown !== undefined) throw new Error(`${label} does not accept ${unknown}.`);
+}
+
+function normalizedRegion(value: CanonicalValue, within: SpatialFrame, label: string): SpatialFrame | null {
+ if (value === null) return null;
+ if (!Array.isArray(value) || value.length !== 4 || value.some((part) => typeof part !== "number" || !Number.isFinite(part))) {
+ throw new Error(`${label} must be null or [x, y, width, height].`);
+ }
+ const [x, y, width, height] = value as unknown as readonly [number, number, number, number];
+ if (x < 0 || y < 0 || width <= 0 || height <= 0 || x + width > 1 || y + height > 1) {
+ throw new Error(`${label} must be a positive normalized region inside its Frame.`);
+ }
+ return {
+ xPx: within.xPx + x * within.widthPx,
+ yPx: within.yPx + y * within.heightPx,
+ widthPx: width * within.widthPx,
+ heightPx: height * within.heightPx,
+ };
+}
+
+export function assertRegionTrack(value: RegionTrack): void {
+ if (!value.timelineId.trim() || value.series.length === 0) {
+ throw new Error("RegionTrack is empty or has no Timeline identity.");
+ }
+ const frameCount = value.series[0]?.frames.length ?? 0;
+ if (frameCount === 0) throw new Error("RegionTrack has no Frames.");
+ const ids = new Set<string>();
+ for (const series of value.series) {
+ if (!series.id.trim() || ids.has(series.id)) throw new Error(`RegionTrack repeats or omits series id ${series.id}.`);
+ ids.add(series.id);
+ if (series.frames.length !== frameCount) throw new Error(`Region series ${series.id} does not cover every Frame.`);
+ for (const frame of series.frames) if (frame !== null) assertSpatialFrame(frame);
+ }
+}
+
+export function sealRegionTrack(value: RegionTrack): RegionTrack {
+ assertRegionTrack(value);
+ return structuredClone(value);
+}
+
+/** Resolve normalized author evidence into one program-picture Frame or null per Timeline Frame. */
+export function resolveRegionTrack(recipe: SvsRecipe, within: SpatialFrame, timeline: Timeline): RegionTrack {
+ assertSpatialFrame(within);
+ assertTimelineIdentity(timeline);
+ exact(recipe.properties, ["series"], `Region Track ${recipe.path}`);
+ const frameCount = timelineFrameCount(timeline);
+ const seriesValue = recipe.properties.series;
+ if (!Array.isArray(seriesValue) || seriesValue.length === 0) throw new Error(`${recipe.path}.series must be a non-empty list.`);
+ const series = seriesValue.map((value, seriesIndex) => {
+ const item = record(value, `${recipe.path}.series.${seriesIndex + 1}`);
+ exact(item, ["id", "regions"], `${recipe.path}.series.${seriesIndex + 1}`);
+ const id = item.id;
+ if (typeof id !== "string" || !id.trim()) throw new Error(`${recipe.path}.series.${seriesIndex + 1}.id must be non-empty text.`);
+ const regions = item.regions;
+ if (!Array.isArray(regions) || regions.length !== frameCount) {
+ throw new Error(`${recipe.path}.series.${seriesIndex + 1}.regions must contain exactly ${frameCount} Frames.`);
+ }
+ return {
+ id,
+ frames: regions.map((region, frame) => normalizedRegion(region, within, `${recipe.path}.${id}.regions.${frame}`)),
+ };
+ });
+ return sealRegionTrack({ timelineId: timeline.id, series });
+}
diff --git a/packages/region-track/src/schema.ts b/packages/region-track/src/schema.ts
new file mode 100644
index 00000000..0ae90380
--- /dev/null
+++ b/packages/region-track/src/schema.ts
@@ -0,0 +1,14 @@
+import type { ValueSchema } from "@hypit/protocol";
+import { spatialFrameSchema } from "@hypit/spatial";
+
+const object = (fields: Readonly<Record<string, { readonly schema: ValueSchema; readonly optional?: boolean }>>): ValueSchema => ({ kind: "object", fields });
+
+export const regionTrackSchema = object({
+ timelineId: { schema: { kind: "string", minLength: 1 } },
+ series: { schema: { kind: "array", minItems: 1, items: object({
+ id: { schema: { kind: "string", minLength: 1 } },
+ frames: { schema: { kind: "array", minItems: 1, items: {
+ kind: "oneOf", variants: [spatialFrameSchema, { kind: "null" }],
+ } } },
+ }) } },
+});
diff --git a/packages/region-track/src/surface.ts b/packages/region-track/src/surface.ts
new file mode 100644
index 00000000..d31bc87b
--- /dev/null
+++ b/packages/region-track/src/surface.ts
@@ -0,0 +1,40 @@
+import { spatialTypes } from "@hypit/spatial";
+import { svsRecipeType } from "@hypit/svs";
+import { timelineTypes } from "@hypit/timeline";
+import type { StructuredElement, StructuredSurfaceHandler, SurfaceResolvedReference } from "@hypit/markup";
+
+import { regionTrackFragment } from "./fragment.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 text(element: StructuredElement, name: string): string {
+ const value = element.attributes[name];
+ if (typeof value !== "string" || !value.trim()) throw new Error(`${element.name}.${name} must be text.`);
+ return value.trim();
+}
+function reference(element: StructuredElement, name: string, type: SurfaceResolvedReference["type"], resolve: (path: string) => SurfaceResolvedReference | undefined): SurfaceResolvedReference {
+ const value = element.attributes[name];
+ if (typeof value !== "object" || value.kind !== "reference") throw new Error(`${element.name}.${name} must be a reference.`);
+ const result = resolve(value.path);
+ if (result === undefined || !sameType(result.type, type)) throw new Error(`${element.name}.${name} must reference ${type.name}.`);
+ return result;
+}
+
+export const decodeRegionTrackSurface: StructuredSurfaceHandler = ({ element, resolveReference }) => {
+ const allowed = ["id", "within", "timeline", "recipe"];
+ const unknown = Object.keys(element.attributes).find((name) => !allowed.includes(name));
+ if (unknown !== undefined) throw new Error(`${element.name} does not accept ${unknown}.`);
+ if (element.children.some((child) => child.kind === "element" || child.value.trim())) throw new Error(`${element.name} must be empty.`);
+ const id = text(element, "id");
+ const within = reference(element, "within", spatialTypes.frame, resolveReference);
+ const timeline = reference(element, "timeline", timelineTypes.track, resolveReference);
+ const recipe = reference(element, "recipe", svsRecipeType, resolveReference);
+ return {
+ records: [],
+ components: [{ id, fragment: regionTrackFragment.id, inputs: {
+ within: within.ref, timeline: timeline.ref, recipe: recipe.ref,
+ }, outputs: { track: id }, range: element.range }],
+ fragments: [regionTrackFragment], exports: [id],
+ };
+};
diff --git a/packages/region-track/src/types.ts b/packages/region-track/src/types.ts
new file mode 100644
index 00000000..d1655c2b
--- /dev/null
+++ b/packages/region-track/src/types.ts
@@ -0,0 +1,13 @@
+import type { SpatialFrame } from "@hypit/spatial";
+
+/** One named sequence of resolved program-picture regions. */
+export type RegionSeries = {
+ readonly id: string;
+ readonly frames: readonly (SpatialFrame | null)[];
+};
+
+/** External spatial evidence indexed directly by one Timeline's frames. */
+export type RegionTrack = {
+ readonly timelineId: string;
+ readonly series: readonly RegionSeries[];
+};
diff --git a/packages/region-track/test/region-track.test.ts b/packages/region-track/test/region-track.test.ts
new file mode 100644
index 00000000..34aa2e66
--- /dev/null
+++ b/packages/region-track/test/region-track.test.ts
@@ -0,0 +1,28 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { sealTimeline } from "@hypit/timeline";
+
+import { resolveRegionTrack } from "../src/index.js";
+
+test("Region Track resolves normalized evidence inside any explicit program Frame", () => {
+ const timeline = sealTimeline({ id: "program", frameCount: 3, frameRate: { numerator: 30, denominator: 1 } });
+ const track = resolveRegionTrack({
+ path: "/project/tracking.svs#heads.default",
+ properties: {
+ series: [{ id: "GUEST", regions: [[0.5, 0.1, 0.2, 0.3], null, [0.52, 0.11, 0.2, 0.3]] }],
+ },
+ }, { xPx: 100, yPx: 200, widthPx: 400, heightPx: 800 }, timeline);
+
+ assert.deepEqual(track.series[0]?.frames[0], { xPx: 300, yPx: 280, widthPx: 80, heightPx: 240 });
+ assert.equal(track.series[0]?.frames[1], null);
+ assert.equal(track.timelineId, timeline.id);
+});
+
+test("Region Track rejects implicit gaps and geometry outside its declared Frame", () => {
+ const timeline = sealTimeline({ id: "program", frameCount: 1, frameRate: { numerator: 30, denominator: 1 } });
+ assert.throws(() => resolveRegionTrack({
+ path: "/project/tracking.svs#heads.default",
+ properties: { series: [{ id: "GUEST", regions: [[0.9, 0.1, 0.2, 0.3]] }] },
+ }, { xPx: 0, yPx: 0, widthPx: 100, heightPx: 100 }, timeline), /inside its Frame/u);
+});
diff --git a/packages/render-hyperframes/README.md b/packages/render-hyperframes/README.md
index 47599b03..263d1ba8 100644
--- a/packages/render-hyperframes/README.md
+++ b/packages/render-hyperframes/README.md
@@ -1,7 +1,7 @@
# `@hypit/render-hyperframes`
-The Surface accepts `timeline={program.timeline}` and projects its complete ProgramSpace.
-Its Fragment receives that range as `space`; rendering works with partial, overlapping or absent
+The Surface accepts `timeline={program.timeline}` and passes that Timeline directly to rendering.
+Its Fragment receives it as `timeline`; rendering works with partial, overlapping or absent
semantic coverage through the same frame and audio pipeline.
Explicit author and capability boundary for final HyperFrames video rendering.
@@ -17,7 +17,7 @@ or video encoding in that observation path.
The package owns `<render:Video composition={...}/>` and lowers it to ordinary Operations that:
-1. obtain the `ProgramSpace` from the Timeline input and compile the referenced `Composition` into a `HyperframesDocument`;
+1. compile the referenced `Composition` against the Timeline into a `HyperframesDocument`;
2. request a silent, frame-exact `RenderedVisual`;
3. compile every peer `AudioTrack` into one `AudioProgramPlan`;
4. request an exact 48 kHz `TimelineAudio`;
@@ -28,7 +28,7 @@ The package is not a renderer and contains no queue, credentials or deployment c
HyperFrames process, a hosted endpoint or another conforming execution package may register a
Provider for the exact visual capability. Media Providers independently realize audio rendering and
mux. None parses SVML or decides which Composition to render. Every result is bound to the same
-ProgramSpace and exact frame/sample domain before it can become a final video Record.
+Timeline and exact frame/sample domain before it can become a final video Record.
The output does not carry copied duration or lineage metadata. It is an ordinary Resource-backed
Blob and can therefore be connected directly to any later component that accepts Blob bytes. A
diff --git a/packages/render-hyperframes/package.json b/packages/render-hyperframes/package.json
index fa86dccb..574d1ddb 100644
--- a/packages/render-hyperframes/package.json
+++ b/packages/render-hyperframes/package.json
@@ -18,7 +18,6 @@
"@hypit/hyperframes": "workspace:*",
"@hypit/media": "workspace:*",
"@hypit/media-pipeline": "workspace:*",
- "@hypit/program-space": "workspace:*",
"@hypit/protocol": "workspace:*",
"@hypit/timeline": "workspace:*",
"@hypit/markup": "workspace:*",
diff --git a/packages/render-hyperframes/src/fragment.ts b/packages/render-hyperframes/src/fragment.ts
index f24baf97..b6b81db5 100644
--- a/packages/render-hyperframes/src/fragment.ts
+++ b/packages/render-hyperframes/src/fragment.ts
@@ -1,4 +1,4 @@
-import { timelineProducers, timelineTypes } from "@hypit/timeline";
+import { timelineTypes } from "@hypit/timeline";
import { mediaTypes } from "@hypit/media";
import { artifactTypes } from "@hypit/artifact";
@@ -22,12 +22,10 @@ export function createRenderHyperframesFragment(selectedRange = false) {
...(selectedRange ? [{ name: "range", type: mediaTypes.frameRange }] : []),
],
operations: [
- { id: "render-range", producer: timelineProducers.projectProgramSpace,
- inputs: { track: input("timeline") }, result: { kind: "output", name: "space" } },
{
id: "compile-document",
producer: hyperframesProducers.compile,
- inputs: { composition: input("composition"), space: operation("render-range") },
+ inputs: { composition: input("composition"), timeline: input("timeline") },
result: { kind: "output", name: "document" },
},
{
@@ -39,7 +37,7 @@ export function createRenderHyperframesFragment(selectedRange = false) {
{
id: "compile-audio-program",
producer: mediaPipelineProducers.planAudio,
- inputs: { composition: input("composition"), space: operation("render-range") },
+ inputs: { composition: input("composition"), timeline: input("timeline") },
result: { kind: "output", name: "plan" },
},
{
diff --git a/packages/render-hyperframes/test/render.test.ts b/packages/render-hyperframes/test/render.test.ts
index 05ffa6f9..6b5b0d05 100644
--- a/packages/render-hyperframes/test/render.test.ts
+++ b/packages/render-hyperframes/test/render.test.ts
@@ -1,4 +1,4 @@
-import { sealTimeline } from "@hypit/timeline";
+import { sealTimeline, timelineDependency, timelineTypes, timelineComponent } from "@hypit/timeline";
import { compositionComponent, videoContractManifests } from "../../../test/support/video-domain.js";
import { artifactTypes } from "@hypit/artifact";
import {
@@ -6,7 +6,6 @@ import {
registerTypeValidatorFacets,
} from "@hypit/component-kit";
import { mediaTypes, sealMuxedMedia, sealRenderedVisual, sealTimelineAudio } from "@hypit/media";
-import { programSpaceDependency, programSpaceTypes, sealProgramSpace } from "@hypit/program-space";
import { compositionDependency, compositionTypes, sealComposition } from "@hypit/composition";
import type { Composition } from "@hypit/composition";
import assert from "node:assert/strict";
@@ -79,14 +78,8 @@ import {
createMarkupAuthorFrontend,
MarkupSurfaceRegistry,
} from "@hypit/markup";
-import {
- timelineComponent,
- timelineDependency,
- timelineTypes,
-} from "@hypit/timeline";
-const space = sealTimeline({ items: [], id: "test-space", durationSec: 2,
- frameRate: { numerator: 30, denominator: 1 },
+const space = sealTimeline({ id: "test-space", frameCount: 60, frameRate: { numerator: 30, denominator: 1 },
});
const semantic = timelineFixture(space);
const composition = sealComposition({
@@ -157,7 +150,6 @@ function validatorRegistry(): TypeValidatorRegistry {
test("HyperFrames rendering is an explicit exact Need after ordinary document compilation", async () => {
assert.deepEqual(build().plan.steps.map((step) => step.producer.name).sort(), [
hyperframesProducers.compile.name,
- "project-program-space",
renderHyperframesProducers.requestVisual.name,
mediaPipelineProducers.planAudio.name,
mediaPipelineProducers.renderAudio.name,
@@ -392,7 +384,6 @@ test(`the ${selectedRange ? "selected" : "full"} rendered video remains an ordin
targets: [{ output: target.ref.kind === "logical-output" ? target.ref.id : "" }],
}));
assert.deepEqual(state.plan.steps.map((step) => step.producer.name).sort(), [
- "project-program-space",
hyperframesProducers.compile.name,
selectedRange ? renderHyperframesProducers.requestVisualRange.name : renderHyperframesProducers.requestVisual.name,
mediaPipelineProducers.planAudio.name,
diff --git a/packages/runtime-local/package.json b/packages/runtime-local/package.json
index 2ed11984..1443d74a 100644
--- a/packages/runtime-local/package.json
+++ b/packages/runtime-local/package.json
@@ -12,6 +12,7 @@
},
"dependencies": {
"@hypit/resource-store-fs": "workspace:*",
+ "@hypit/build-result": "workspace:*",
"@hypit/build-result-fs": "workspace:*",
"@hypit/build-result-kit": "workspace:*",
"@hypit/component-kit": "workspace:*",
@@ -28,7 +29,6 @@
"koffi": "3.2.1"
},
"devDependencies": {
- "@hypit/build-result": "workspace:*",
"@hypit/credential-store-env": "workspace:*"
}
}
diff --git a/packages/screen-overlay-studio/src/index.ts b/packages/screen-overlay-studio/src/index.ts
index 7a90a3e0..3e19f113 100644
--- a/packages/screen-overlay-studio/src/index.ts
+++ b/packages/screen-overlay-studio/src/index.ts
@@ -11,7 +11,7 @@ function projectOverlays(context: StudioTrackCompanionContext): readonly StudioE
subjectId: item.subjectId,
startFrame: item.span.startFrame,
endFrameExclusive: item.span.endFrameExclusive,
- stackOrder: item.stacking.order,
+ stackOrder: item.z,
sourceTypes: [screenOverlayTypes.itemSpec],
}));
return childEntities(context, items, "screen-overlay", "standard").map((entity, index) => {
diff --git a/packages/screen-overlay/README.md b/packages/screen-overlay/README.md
index 926f67f4..c4752c98 100644
--- a/packages/screen-overlay/README.md
+++ b/packages/screen-overlay/README.md
@@ -6,7 +6,7 @@ inputs accept a Moment or a time such as `2s`; `at` with `for` produces a Window
Official provider-free self-contained screen-paint package.
-Every item consumes its typed parameters, explicit Temporal source, CanvasSpace, Timeline,
+Every item consumes its typed parameters, explicit Temporal source, placement Frame, Timeline,
seed and local frame. Flash, ColorWash, Vignette, ScanLines, DirectionalMatte, WhipVeil,
GlitchVeil, Grain, LightLeak, Bokeh and TVStatic lower to ordinary absolute-stack `VisualTrack`
Presents. These effects generate their own pixels over the selected interval.
diff --git a/packages/screen-overlay/package.json b/packages/screen-overlay/package.json
index 7846019d..9829ee03 100644
--- a/packages/screen-overlay/package.json
+++ b/packages/screen-overlay/package.json
@@ -4,15 +4,17 @@
"license": "SEE LICENSE IN LICENSE",
"private": true,
"type": "module",
- "exports": { ".": "./src/index.ts" },
- "hypit": { "activation": "./src/activation.ts" },
+ "exports": {
+ ".": "./src/index.ts"
+ },
+ "hypit": {
+ "activation": "./src/activation.ts"
+ },
"dependencies": {
"@hypit/component-kit": "workspace:*",
"@hypit/composition": "workspace:*",
"@hypit/elaborator": "workspace:*",
- "@hypit/narrative": "workspace:*",
"@hypit/protocol": "workspace:*",
- "@hypit/program-space": "workspace:*",
"@hypit/timeline": "workspace:*",
"@hypit/spatial": "workspace:*",
"@hypit/temporal": "workspace:*",
diff --git a/packages/screen-overlay/src/component.ts b/packages/screen-overlay/src/component.ts
index 783c1852..ad2ac093 100644
--- a/packages/screen-overlay/src/component.ts
+++ b/packages/screen-overlay/src/component.ts
@@ -2,7 +2,7 @@ import type { Timeline } from "@hypit/timeline";
import type { ComponentPackage } from "@hypit/component-kit";
import { canonicalize } from "@hypit/protocol";
import type { StoredValue } from "@hypit/protocol";
-import type { CanvasSpace } from "@hypit/spatial";
+import type { SpatialFrame } from "@hypit/spatial";
import { screenOverlayProducers, screenOverlayTypes } from "./manifest.js";
import { appendProjectedScreenOverlay, assertScreenOverlayProgram, createScreenOverlaySet, finalizeScreenOverlay, renderScreenOverlay } from "./program.js";
import type { ScreenOverlayHeader, ScreenOverlayItemSpec, ScreenOverlayProgram, ScreenOverlaySet } from "./types.js";
@@ -14,7 +14,7 @@ export const screenOverlayComponent = {
{ producer: screenOverlayProducers.createSet, handler: () => ({ outputs: { set: output(createScreenOverlaySet()) }, needs: {} }) },
{ producer: screenOverlayProducers.appendItem, handler: ({ inputs }) => ({ outputs: { set: output(appendProjectedScreenOverlay(inline<ScreenOverlaySet>(inputs.set?.value, "ScreenOverlaySet"), inline<ScreenOverlayHeader>(inputs.header?.value, "ScreenOverlayHeader"), inline<Timeline>(inputs.timeline?.value, "Timeline"), inline<ScreenOverlayItemSpec>(inputs.spec?.value, "ScreenOverlayItemSpec"), inline<TemporalWindow>(inputs.window?.value, "TemporalWindow"))) }, needs: {} }) },
{ producer: screenOverlayProducers.finalize, handler: ({ inputs }) => ({ outputs: { program: output(finalizeScreenOverlay(inline<ScreenOverlaySet>(inputs.set?.value, "ScreenOverlaySet"), inline<ScreenOverlayHeader>(inputs.header?.value, "ScreenOverlayHeader"))) }, needs: {} }) },
- { producer: screenOverlayProducers.render, handler: ({ inputs }) => ({ outputs: { track: output(renderScreenOverlay(inline<CanvasSpace>(inputs.canvas?.value, "CanvasSpace"), inline<Timeline>(inputs.timeline?.value, "Timeline"), inline<ScreenOverlayProgram>(inputs.program?.value, "ScreenOverlayProgram"))) }, needs: {} }) },
+ { producer: screenOverlayProducers.render, handler: ({ inputs }) => ({ outputs: { track: output(renderScreenOverlay(inline<SpatialFrame>(inputs.within?.value, "SpatialFrame"), inline<Timeline>(inputs.timeline?.value, "Timeline"), inline<ScreenOverlayProgram>(inputs.program?.value, "ScreenOverlayProgram"))) }, needs: {} }) },
],
validators: [{ type: screenOverlayTypes.program, handler: ({ value }) => assertScreenOverlayProgram(inline<ScreenOverlayProgram>(value, "ScreenOverlayProgram")) }],
} satisfies ComponentPackage;
diff --git a/packages/screen-overlay/src/fragment.ts b/packages/screen-overlay/src/fragment.ts
index c6972a30..0aa90053 100644
--- a/packages/screen-overlay/src/fragment.ts
+++ b/packages/screen-overlay/src/fragment.ts
@@ -28,14 +28,14 @@ export function createScreenOverlayFragment(items: readonly ScreenOverlayFragmen
});
operations.push(
{ id: "overlay:program", producer: screenOverlayProducers.finalize, inputs: { set: operation(current), header: input("header") }, result: { kind: "output", name: "program" } },
- { id: "overlay:track", producer: screenOverlayProducers.render, inputs: { canvas: input("canvas"), timeline: input("timeline"), program: operation("overlay:program") }, result: { kind: "output", name: "track" } },
+ { id: "overlay:track", producer: screenOverlayProducers.render, inputs: { within: input("within"), timeline: input("timeline"), program: operation("overlay:program") }, result: { kind: "output", name: "track" } },
);
return sealGraphFragment({ inputs: [
- { name: "canvas", type: spatialTypes.canvas }, { name: "header", type: screenOverlayTypes.header },
+ { name: "within", type: spatialTypes.frame }, { name: "header", type: screenOverlayTypes.header },
{ name: "timeline", type: timelineTypes.track }, ...[...types].map(([inputName, type]) => ({ name: inputName, type })),
], operations, exports: [
{ name: "program", type: screenOverlayTypes.program, root: operation("overlay:program") },
- { name: "track", type: compositionTypes.visualTrack, root: operation("overlay:track") },
+ { name: "visual", type: compositionTypes.visualTrack, root: operation("overlay:track") },
] });
}
export const programScreenOverlayFragment = createScreenOverlayFragment([{ specName: "spec", windowName: "window" }]);
diff --git a/packages/screen-overlay/src/manifest.ts b/packages/screen-overlay/src/manifest.ts
index 69db475c..f2dbedc0 100644
--- a/packages/screen-overlay/src/manifest.ts
+++ b/packages/screen-overlay/src/manifest.ts
@@ -1,12 +1,10 @@
-import { timelineTypes } from "@hypit/timeline";
+import { timelineTypes, timelineDependency } from "@hypit/timeline";
import { temporalContextAttributeVocabulary } from "@hypit/temporal-markup";
import { readFile } from "node:fs/promises";
import { compositionDependency, compositionTypes } from "@hypit/composition";
-import { narrativeDependency } from "@hypit/narrative";
import type { ModuleManifest, ProducerRef, TypeRef, ValueSchema } from "@hypit/protocol";
-import { timelineDependency } from "@hypit/timeline";
import { spatialDependency, spatialTypes } from "@hypit/spatial";
import { temporalDependency, temporalTypes } from "@hypit/temporal";
import { temporalWindowAttributeVocabulary } from "@hypit/temporal-markup";
@@ -60,7 +58,7 @@ const itemSpec = object({
const frameSpan = object({ startFrame: { schema: unsignedInteger }, endFrameExclusive: { schema: unsignedInteger } });
const item = object({
id: { schema: string }, span: { schema: frameSpan }, content: { schema: component },
- stacking: { schema: object({ order: { schema: integer }, tieBreak: { schema: string } }) },
+ order: { schema: unsignedInteger }, z: { schema: integer },
});
export const screenOverlayHeaderSchema: ValueSchema = object({ id: { schema: string } });
export const screenOverlayItemSpecSchema: ValueSchema = itemSpec;
@@ -77,25 +75,25 @@ const itemAttributes = [
] as const;
export const screenOverlayMarkupSurfaces = [
- { name: "track", tag: "Track", mode: "structured", outputs: [screenOverlayTypes.header, screenOverlayTypes.itemSpec, temporalTypes.instantSpec, temporalTypes.windowSpec, temporalTypes.instant, temporalTypes.window, screenOverlayTypes.program, compositionTypes.visualTrack],
+ { name: "track", tag: "Track", mode: "structured", outputs: [screenOverlayTypes.header, screenOverlayTypes.itemSpec, temporalTypes.duration, temporalTypes.extent, temporalTypes.shiftSpec, temporalTypes.instantSpec, temporalTypes.windowSpec, temporalTypes.instant, temporalTypes.window, screenOverlayTypes.program, compositionTypes.visualTrack],
vocabulary: {
- summary: "Paints self-contained screen treatments across the whole Canvas and publishes the overlay Program and the VisualTrack it renders to.",
- appearance: "Treatments laid edge to edge over the whole Canvas, never a panel, a card or text, each item covering the frame for its own span only and painted over its siblings in `z` order. Flash pulses one color up to full and back down across the frame, ColorWash holds that same flat color still, and Vignette leaves the middle clear and darkens outwards to one color in an ellipse around a chosen centre. Four items cross the frame as travelling geometry: ScanLines rule it with evenly spaced white stripes at an angle, DirectionalMatte sweeps a feathered wall of color over it, WhipVeil slides a single soft-edged white band left, right, up or down, and LightLeak drags a heavily blurred angled gradient of colors from one side to the other. The remaining four scatter many small shapes from a seed: GlitchVeil throws wide colored horizontal bars that jump sideways, Grain sprinkles fine specks that crawl diagonally, Bokeh floats blurred round discs of one color that drift apart, and TVStatic fills the frame with grey noise cells beneath fine horizontal scan lines.",
+ summary: "Paints self-contained screen treatments across an explicit Frame and publishes the overlay Program and the VisualTrack it renders to.",
+ appearance: "Treatments laid edge to edge over the selected Frame, never a card or text, each item covering it for its own span only and painted over its siblings in `z` order. Flash pulses one color up to full and back down across the frame, ColorWash holds that same flat color still, and Vignette leaves the middle clear and darkens outwards to one color in an ellipse around a chosen centre. Four items cross the frame as travelling geometry: ScanLines rule it with evenly spaced white stripes at an angle, DirectionalMatte sweeps a feathered wall of color over it, WhipVeil slides a single soft-edged white band left, right, up or down, and LightLeak drags a heavily blurred angled gradient of colors from one side to the other. The remaining four scatter many small shapes from a seed: GlitchVeil throws wide colored horizontal bars that jump sideways, Grain sprinkles fine specks that crawl diagonally, Bokeh floats blurred round discs of one color that drift apart, and TVStatic fills the frame with grey noise cells beneath fine horizontal scan lines.",
preview: previewImage("Track.png"),
attributes: [
{ name: "id", kind: "identifier", required: true,
summary: "Names this overlay so its Program and Track can be referenced elsewhere in the Source." },
- { name: "canvas", kind: "reference", required: true, accepts: [spatialTypes.canvas],
- summary: "Chooses the Canvas every item is painted across." },
+ { name: "within", kind: "reference", required: true, accepts: [spatialTypes.frame],
+ summary: "Chooses the Frame every item is painted across." },
...temporalContextAttributeVocabulary,
],
children: [
{ tag: "Flash", cardinality: "many",
- summary: "A full-Canvas flash of one color with its own attack, hold and decay in frames.",
+ summary: "A full-Frame flash of one color with its own attack, hold and decay in frames.",
attributes: [
...itemAttributes,
{ name: "color", kind: "literal", required: true,
- summary: "Sets the hexadecimal color the Canvas flashes." },
+ summary: "Sets the hexadecimal color the selected Frame flashes." },
{ name: "intensity", kind: "literal", required: true,
summary: "Sets how strong the flash is, from 0 to 1." },
{ name: "attack", kind: "literal", required: true,
@@ -106,11 +104,11 @@ export const screenOverlayMarkupSurfaces = [
summary: "Sets how many frames the flash takes to fade away." },
] },
{ tag: "ColorWash", cardinality: "many",
- summary: "One flat color held over the whole Canvas at a fixed opacity.",
+ summary: "One flat color held over the whole selected Frame at a fixed opacity.",
attributes: [
...itemAttributes,
{ name: "color", kind: "literal", required: true,
- summary: "Sets the hexadecimal color held over the Canvas." },
+ summary: "Sets the hexadecimal color held over the selected Frame." },
{ name: "opacity", kind: "literal", required: true,
summary: "Sets how opaque the wash is, from 0 to 1." },
] },
@@ -119,13 +117,13 @@ export const screenOverlayMarkupSurfaces = [
attributes: [
...itemAttributes,
{ name: "center-x", kind: "literal", required: true,
- summary: "Sets the horizontal centre of the falloff as a fraction of the Canvas width." },
+ summary: "Sets the horizontal centre of the falloff as a fraction of the selected Frame width." },
{ name: "center-y", kind: "literal", required: true,
- summary: "Sets the vertical centre of the falloff as a fraction of the Canvas height." },
+ summary: "Sets the vertical centre of the falloff as a fraction of the selected Frame height." },
{ name: "radius-x", kind: "literal", required: true,
- summary: "Sets the horizontal radius of the falloff as a fraction of the Canvas width." },
+ summary: "Sets the horizontal radius of the falloff as a fraction of the selected Frame width." },
{ name: "radius-y", kind: "literal", required: true,
- summary: "Sets the vertical radius of the falloff as a fraction of the Canvas height." },
+ summary: "Sets the vertical radius of the falloff as a fraction of the selected Frame height." },
{ name: "softness", kind: "literal", required: true,
summary: "Sets how gradually the falloff fades outwards, from 0 to 1." },
{ name: "color", kind: "literal", required: true,
@@ -134,7 +132,7 @@ export const screenOverlayMarkupSurfaces = [
summary: "Sets how opaque the vignette is, from 0 to 1." },
] },
{ tag: "ScanLines", cardinality: "many",
- summary: "Repeating lines at a fixed spacing, thickness and angle, travelling across the Canvas.",
+ summary: "Repeating lines at a fixed spacing, thickness and angle, travelling across the selected Frame.",
attributes: [
...itemAttributes,
{ name: "spacing", kind: "literal", required: true,
@@ -149,13 +147,13 @@ export const screenOverlayMarkupSurfaces = [
summary: "Sets how many pixels the lines travel across the item's span." },
] },
{ tag: "DirectionalMatte", cardinality: "many",
- summary: "A feathered matte of one color crossing the Canvas at an angle over an explicit progress range.",
+ summary: "A feathered matte of one color crossing the selected Frame at an angle over an explicit progress range.",
attributes: [
...itemAttributes,
{ name: "angle", kind: "literal", required: true,
- summary: "Sets the angle in degrees the matte edge crosses the Canvas at." },
+ summary: "Sets the angle in degrees the matte edge crosses the selected Frame at." },
{ name: "coverage", kind: "literal", required: true,
- summary: "Sets how much of the Canvas the matte covers, from 0 to 1." },
+ summary: "Sets how much of the selected Frame the matte covers, from 0 to 1." },
{ name: "feather", kind: "literal", required: true,
summary: "Sets how soft the matte edge is, from 0 to 1." },
{ name: "color", kind: "literal", required: true,
@@ -168,11 +166,11 @@ export const screenOverlayMarkupSurfaces = [
summary: "Sets the progress the matte ends its crossing at, from -1 to 2." },
] },
{ tag: "WhipVeil", cardinality: "many",
- summary: "A soft band that travels across the Canvas in one of four directions.",
+ summary: "A soft band that travels across the selected Frame in one of four directions.",
attributes: [
...itemAttributes,
{ name: "direction", kind: "literal", required: true, values: ["left", "right", "up", "down"],
- summary: "Chooses which way the band travels across the Canvas." },
+ summary: "Chooses which way the band travels across the selected Frame." },
{ name: "width", kind: "literal", required: true,
summary: "Sets how many pixels wide the band is." },
{ name: "softness", kind: "literal", required: true,
@@ -183,11 +181,11 @@ export const screenOverlayMarkupSurfaces = [
summary: "Sets how opaque the band is, from 0 to 1." },
] },
{ tag: "GlitchVeil", cardinality: "many",
- summary: "Colored bars laid across the Canvas and displaced from an explicit seed.",
+ summary: "Colored bars laid across the selected Frame and displaced from an explicit seed.",
attributes: [
...itemAttributes,
{ name: "bars", kind: "literal", required: true,
- summary: "Sets how many bars are laid across the Canvas, up to 256." },
+ summary: "Sets how many bars are laid across the selected Frame, up to 256." },
{ name: "colors", kind: "literal", required: true,
summary: "Lists the hexadecimal colors the bars are drawn in, separated by commas." },
{ name: "opacity", kind: "literal", required: true,
@@ -202,7 +200,7 @@ export const screenOverlayMarkupSurfaces = [
attributes: [
...itemAttributes,
{ name: "amount", kind: "literal", required: true,
- summary: "Sets how much grain is laid over the Canvas, from 0 to 1." },
+ summary: "Sets how much grain is laid over the selected Frame, from 0 to 1." },
{ name: "size", kind: "literal", required: true,
summary: "Sets how many pixels across one grain particle is." },
{ name: "chroma", kind: "literal", required: true, values: ["monochrome", "color"],
@@ -213,13 +211,13 @@ export const screenOverlayMarkupSurfaces = [
summary: "Sets the seed the grain pattern is drawn from." },
] },
{ tag: "LightLeak", cardinality: "many",
- summary: "Colored light angled across the Canvas and moving from an explicit seed.",
+ summary: "Colored light angled across the selected Frame and moving from an explicit seed.",
attributes: [
...itemAttributes,
{ name: "colors", kind: "literal", required: true,
summary: "Lists the hexadecimal colors the leak is drawn in, separated by commas." },
{ name: "angle", kind: "literal", required: true,
- summary: "Sets the angle in degrees the light crosses the Canvas at." },
+ summary: "Sets the angle in degrees the light crosses the selected Frame at." },
{ name: "softness", kind: "literal", required: true,
summary: "Sets how soft the leak's edges are, from 0 to 1." },
{ name: "travel", kind: "literal", required: true,
@@ -234,7 +232,7 @@ export const screenOverlayMarkupSurfaces = [
attributes: [
...itemAttributes,
{ name: "amount", kind: "literal", required: true,
- summary: "Sets how many highlights are scattered over the Canvas, from 0 to 1." },
+ summary: "Sets how many highlights are scattered over the selected Frame, from 0 to 1." },
{ name: "min-size", kind: "literal", required: true,
summary: "Sets how many pixels across the smallest highlight is." },
{ name: "max-size", kind: "literal", required: true,
@@ -253,7 +251,7 @@ export const screenOverlayMarkupSurfaces = [
attributes: [
...itemAttributes,
{ name: "amount", kind: "literal", required: true,
- summary: "Sets how much noise covers the Canvas, from 0 to 1." },
+ summary: "Sets how much noise covers the selected Frame, from 0 to 1." },
{ name: "size", kind: "literal", required: true,
summary: "Sets how many pixels across one noise cell is." },
{ name: "scan-lines", kind: "literal", required: true,
@@ -267,19 +265,18 @@ export const screenOverlayMarkupSurfaces = [
ports: [
{ name: "program", type: screenOverlayTypes.program,
summary: "The resolved overlay: every item with its frame span, its content and its stacking." },
- { name: "track", type: compositionTypes.visualTrack,
+ { name: "visual", type: compositionTypes.visualTrack,
summary: "The rendered overlay, an ordinary peer VisualTrack." },
],
- example: `<screen:Track id="effects" timeline={speech.timeline} canvas={vertical}>
- <screen:Flash during={story.selection.overlay} z="80"
+ example: `<screen:Track id="effects" timeline={speech.timeline} within={vertical.bounds}>
+ <screen:Flash during={story-time.overlay} z="80"
color="#ffffff" intensity="0.6" attack="2" hold="2" decay="6"/>
</screen:Track>`,
notes: [
"The overlay requires at least one component child, and a component child is empty.",
- "A component child writes exactly one temporal form, `during`, `at`, or `start` with `end`; none of them or more than one is refused.",
- "`during` takes the literal `program` for the whole programme, or a Selection reference.",
- "`at` requires `for`.",
- "`start` and `end` each take `program.start`, `program.end`, `selection.start`, `selection.end` or `moment.cue` with an optional `+` or `-` offset, or a bare duration read as an absolute point.",
+ "A component child writes `during`, or exactly two of `from`, `until` and `for`.",
+ "`during` takes `timeline` for the whole programme or an already resolved Window.",
+ "`from` and `until` accept resolved Instants or absolute Timeline expressions.",
"Explicit `start` and `end` timing binds a Selection through `selection` or a Moment through `moment`, never both.",
"A duration is written as an integral `f` or `ms` count, or as an `s` count that may carry a decimal fraction.",
],
@@ -289,7 +286,7 @@ export const screenOverlayMarkupSurfaces = [
export const screenOverlayManifest: ModuleManifest = {
format: "hypit.module@1", name: screenOverlayModuleRef.name, version: screenOverlayModuleRef.version,
- dependencies: [narrativeDependency, timelineDependency, spatialDependency, temporalDependency, compositionDependency],
+ dependencies: [timelineDependency, spatialDependency, temporalDependency, compositionDependency],
types: [
{ name: screenOverlayTypes.header.name },
{ name: screenOverlayTypes.itemSpec.name },
@@ -300,7 +297,7 @@ export const screenOverlayManifest: ModuleManifest = {
{ name: screenOverlayProducers.createSet.name, inputs: [], outputs: [{ name: "set", type: screenOverlayTypes.set }], needs: [] },
{ name: screenOverlayProducers.appendItem.name, inputs: [...appendInputs], outputs: [{ name: "set", type: screenOverlayTypes.set }], needs: [] },
{ name: screenOverlayProducers.finalize.name, inputs: [{ name: "set", type: screenOverlayTypes.set }, { name: "header", type: screenOverlayTypes.header }], outputs: [{ name: "program", type: screenOverlayTypes.program }], needs: [] },
- { name: screenOverlayProducers.render.name, inputs: [{ name: "canvas", type: spatialTypes.canvas }, { name: "timeline", type: timelineTypes.track }, { name: "program", type: screenOverlayTypes.program }], outputs: [{ name: "track", type: compositionTypes.visualTrack }], needs: [] },
+ { name: screenOverlayProducers.render.name, inputs: [{ name: "within", type: spatialTypes.frame }, { name: "timeline", type: timelineTypes.track }, { name: "program", type: screenOverlayTypes.program }], outputs: [{ name: "track", type: compositionTypes.visualTrack }], needs: [] },
],
};
export const screenOverlayDependency = { module: screenOverlayModuleRef } as const;
diff --git a/packages/screen-overlay/src/program.ts b/packages/screen-overlay/src/program.ts
index 43302769..85e503cb 100644
--- a/packages/screen-overlay/src/program.ts
+++ b/packages/screen-overlay/src/program.ts
@@ -1,12 +1,12 @@
+import { assertTimelineIdentity } from "@hypit/timeline";
import type { Timeline } from "@hypit/timeline";
import { assertVisualTrackIdentity, sealVisualTrack } from "@hypit/composition";
import type { VisualAnimation, VisualElement, VisualStyleDeclaration, VisualTrack } from "@hypit/composition";
-import { assertProgramSpaceIdentity } from "@hypit/program-space";
import { canonicalize } from "@hypit/protocol";
-import { assertCanvasSpace } from "@hypit/spatial";
-import type { CanvasSpace } from "@hypit/spatial";
+import { assertSpatialFrame } from "@hypit/spatial";
+import type { SpatialFrame } from "@hypit/spatial";
import { assertTemporalWindowFor } from "@hypit/temporal";
-import type { ProjectedWindow } from "@hypit/temporal";
+import type { TemporalWindow } from "@hypit/temporal";
import type {
ScreenOverlayComponent,
@@ -108,16 +108,17 @@ export function assertScreenOverlaySet(value: ScreenOverlaySet): void {
function realized(
set: ScreenOverlaySet, header: ScreenOverlayHeader, timeline: Timeline, spec: ScreenOverlayItemSpec,
- window: ProjectedWindow,
+ window: TemporalWindow,
): ScreenOverlaySet {
assertScreenOverlaySet(set); assertScreenOverlayHeader(header); assertScreenOverlayItemSpec(spec);
- assertTemporalWindowFor(window, { subjectId: spec.id, space: timeline });
+ assertTemporalWindowFor(window, { subjectId: spec.id, timeline: timeline });
const addition = {
id: window.id,
subjectId: spec.id,
span: { ...window.span },
content: structuredClone(spec.content),
- stacking: { order: spec.stackingOrder, tieBreak: `${header.id}:${spec.id}` },
+ order: set.items.length,
+ z: spec.stackingOrder,
} satisfies ScreenOverlayItemProgram;
const ids = new Set(set.items.map((item) => item.id));
assert(!ids.has(addition.id), `Screen Overlay already contains Item ${addition.id}.`);
@@ -130,7 +131,7 @@ export function appendProjectedScreenOverlay(
header: ScreenOverlayHeader,
timeline: Timeline,
spec: ScreenOverlayItemSpec,
- window: ProjectedWindow,
+ window: TemporalWindow,
): ScreenOverlaySet {
return realized(set, header, timeline, spec, window);
}
@@ -151,8 +152,9 @@ export function assertScreenOverlayProgram(value: ScreenOverlayProgram): void {
assert(!ids.has(item.id), `Duplicate Screen Overlay Item ${item.id}.`); ids.add(item.id);
assert(item.span.startFrame >= 0 && item.span.endFrameExclusive > item.span.startFrame,
`Screen Overlay Item ${item.id} timing is invalid.`);
- assertScreenOverlayComponent(item.content); assert(Number.isSafeInteger(item.stacking.order) && item.stacking.tieBreak.length > 0,
- `Screen Overlay Item ${item.id} stacking is invalid.`);
+ assertScreenOverlayComponent(item.content);
+ assert(Number.isSafeInteger(item.order) && item.order >= 0, `Screen Overlay Item ${item.id} order is invalid.`);
+ assert(Number.isSafeInteger(item.z), `Screen Overlay Item ${item.id} z is invalid.`);
}
}
@@ -169,8 +171,10 @@ function random(seed: number): Random {
}
function px(value: number): string { return `${Number(value.toFixed(6))}px`; }
function percent(value: number): string { return `${Number((value * 100).toFixed(6))}%`; }
-function rootStyle(): VisualStyleDeclaration[] { return [
- { name: "inset", value: "0" }, { name: "overflow", value: "hidden" }, { name: "position", value: "absolute" },
+function rootStyle(within: SpatialFrame): VisualStyleDeclaration[] { return [
+ { name: "height", value: px(within.heightPx) }, { name: "left", value: px(within.xPx) },
+ { name: "overflow", value: "hidden" }, { name: "position", value: "absolute" },
+ { name: "top", value: px(within.yPx) }, { name: "width", value: px(within.widthPx) },
]; }
function fullChild(
id: string,
@@ -188,22 +192,22 @@ function fullChild(
function animation(duration: number, start: readonly VisualStyleDeclaration[], end: readonly VisualStyleDeclaration[]): VisualAnimation {
return { keyframes: [{ atFrame: 0, style: start }, { atFrame: duration, style: end }] };
}
-function flashElements(content: Extract<ScreenOverlayComponent, { kind: "flash" }>, duration: number): readonly VisualElement[] {
+function flashElements(content: Extract<ScreenOverlayComponent, { kind: "flash" }>, within: SpatialFrame, duration: number): readonly VisualElement[] {
const total = content.attackFrames + content.holdFrames + content.decayFrames;
- if (total === 0) return [{ id: "root", order: 0, kind: "box", style: [...rootStyle(), { name: "background-color", value: content.color }, { name: "opacity", value: content.intensity }] }];
+ if (total === 0) return [{ id: "root", order: 0, kind: "box", style: [...rootStyle(within), { name: "background-color", value: content.color }, { name: "opacity", value: content.intensity }] }];
const marks = new Map<number, number>();
marks.set(0, content.attackFrames === 0 ? content.intensity : 0);
marks.set(content.attackFrames, content.intensity);
marks.set(content.attackFrames + content.holdFrames, content.intensity);
marks.set(total, 0);
marks.set(duration, 0);
- return [{ id: "root", order: 0, kind: "box", style: [...rootStyle(), { name: "background-color", value: content.color }],
+ return [{ id: "root", order: 0, kind: "box", style: [...rootStyle(within), { name: "background-color", value: content.color }],
animation: { keyframes: [...marks].sort(([a], [b]) => a - b).map(([atFrame, opacity]) => ({ atFrame, style: [{ name: "opacity", value: opacity }] })) } }];
}
-function overlayElements(content: ScreenOverlayComponent, canvas: CanvasSpace, duration: number): readonly VisualElement[] {
- if (content.kind === "flash") return flashElements(content, duration);
- const root: VisualElement = { id: "root", order: 0, kind: "box", style: rootStyle() };
+function overlayElements(content: ScreenOverlayComponent, within: SpatialFrame, duration: number): readonly VisualElement[] {
+ if (content.kind === "flash") return flashElements(content, within, duration);
+ const root: VisualElement = { id: "root", order: 0, kind: "box", style: rootStyle(within) };
switch (content.kind) {
case "color-wash": return [root, fullChild("wash", [{ name: "background-color", value: content.color }, { name: "opacity", value: content.opacity }])];
case "vignette": {
@@ -218,7 +222,7 @@ function overlayElements(content: ScreenOverlayComponent, canvas: CanvasSpace, d
], animation(duration, [{ name: "transform", value: "translate3d(0px,0px,0)" }], [{ name: "transform", value: travel }]))];
}
case "directional-matte": {
- const extent = Math.hypot(canvas.widthPx, canvas.heightPx) * 2;
+ const extent = Math.hypot(within.widthPx, within.heightPx) * 2;
const move = (progress: number) => `rotate(${content.angleDeg}deg) translate3d(${px((progress - 0.5) * extent)},0px,0)`;
const edge = Math.max(0.001, content.feather) * 100;
return [root, fullChild("matte", [
@@ -289,8 +293,8 @@ function overlayElements(content: ScreenOverlayComponent, canvas: CanvasSpace, d
})];
}
case "tv-static": {
- const rng = random(content.seed); const columns = Math.ceil(canvas.widthPx / content.noiseSizePx);
- const rows = Math.ceil(canvas.heightPx / content.noiseSizePx); const count = Math.min(512, Math.max(1, Math.round(columns * rows * content.amount)));
+ const rng = random(content.seed); const columns = Math.ceil(within.widthPx / content.noiseSizePx);
+ const rows = Math.ceil(within.heightPx / content.noiseSizePx); const count = Math.min(512, Math.max(1, Math.round(columns * rows * content.amount)));
const cells = Array.from({ length: count }, (_, index): VisualElement => {
const shade = Math.round(rng() * 255); const drift = content.motionRatePxPerFrame * duration;
return { id: `static-${index + 1}`, parent: "root", order: index + 1, kind: "box", style: [
@@ -307,13 +311,13 @@ function overlayElements(content: ScreenOverlayComponent, canvas: CanvasSpace, d
}
}
-export function renderScreenOverlay(canvas: CanvasSpace, timeline: Timeline, program: ScreenOverlayProgram): VisualTrack {
- assertCanvasSpace(canvas); assertProgramSpaceIdentity(timeline); assertScreenOverlayProgram(program);
+export function renderScreenOverlay(within: SpatialFrame, timeline: Timeline, program: ScreenOverlayProgram): VisualTrack {
+ assertSpatialFrame(within); assertTimelineIdentity(timeline); assertScreenOverlayProgram(program);
const track = sealVisualTrack({
- programSpaceId: timeline.id, visualIr: "hypit.visual-ir@1", id: program.id,
+ timelineId: timeline.id, visualIr: "hypit.visual-ir@1", id: program.id,
presents: program.items.map((item) => ({
- id: item.id, subjectId: item.subjectId, span: { ...item.span }, stacking: { ...item.stacking },
- elements: overlayElements(item.content, canvas, item.span.endFrameExclusive - item.span.startFrame),
+ id: item.id, order: item.order, z: item.z, subjectId: item.subjectId, span: { ...item.span },
+ elements: overlayElements(item.content, within, item.span.endFrameExclusive - item.span.startFrame),
})),
});
assertVisualTrackIdentity(track, timeline);
diff --git a/packages/screen-overlay/src/surface.ts b/packages/screen-overlay/src/surface.ts
index 9b686cf8..91a14fb3 100644
--- a/packages/screen-overlay/src/surface.ts
+++ b/packages/screen-overlay/src/surface.ts
@@ -1,7 +1,7 @@
import { resolveTemporalContext } from "@hypit/temporal-markup";
import { spatialTypes } from "@hypit/spatial";
import type { StructuredElement, StructuredSurfaceHandler, SurfaceComponentDraft, SurfaceRecordDraft, SurfaceResolvedReference, MarkupAttributeValue } from "@hypit/markup";
-import { createTemporalWindowProjection, temporalWindowAttributeNames } from "@hypit/temporal-markup";
+import { createTemporalWindowConstruction, temporalWindowAttributeNames } from "@hypit/temporal-markup";
import { createScreenOverlayFragment } from "./fragment.js";
import { screenOverlayTypes } from "./manifest.js";
import { sealScreenOverlayHeader, sealScreenOverlayItemSpec } from "./program.js";
@@ -57,15 +57,15 @@ function content(element: StructuredElement): { readonly value: ScreenOverlayCom
}
export const decodeScreenOverlaySurface: StructuredSurfaceHandler = ({ element, resolveReference }) => {
- allowed(element, ["id", "canvas", "timeline"]); const id = text(element, "id");
- const canvas = ref(element.attributes.canvas, `${element.name}.canvas`, spatialTypes.canvas, resolveReference);
+ allowed(element, ["id", "within", "timeline"]); const id = text(element, "id");
+ const within = ref(element.attributes.within, `${element.name}.within`, spatialTypes.frame, resolveReference);
const context = resolveTemporalContext({ element, resolveReference });
const headerId = `${id}.header`; const records: SurfaceRecordDraft[] = [{ id: headerId, type: screenOverlayTypes.header,
value: { kind: "inline", value: sealScreenOverlayHeader({ id }) }, range: element.range }];
const temporalComponents: SurfaceComponentDraft[] = [];
- const temporalFragments: ReturnType<typeof createTemporalWindowProjection>["fragments"][number][] = [];
+ const temporalFragments: ReturnType<typeof createTemporalWindowConstruction>["fragments"][number][] = [];
const fragmentItems: Parameters<typeof createScreenOverlayFragment>[0][number][] = [];
- const inputs: Record<string, typeof canvas.ref> = { canvas: canvas.ref, header: { kind: "record", id: headerId }, timeline: context.timeline.ref };
+ const inputs: Record<string, typeof within.ref> = { within: within.ref, header: { kind: "record", id: headerId }, timeline: context.timeline.ref };
let index = 0;
for (const child of element.children) {
if (child.kind === "text") { if (child.value.trim()) throw new Error(`${element.name} accepts only component children.`); continue; }
@@ -75,7 +75,7 @@ export const decodeScreenOverlaySurface: StructuredSurfaceHandler = ({ element,
const itemSpec = sealScreenOverlayItemSpec({
id: optionalText(child, "id") ?? `${id}.${decoded.value.kind}.${suffix}`, content: decoded.value,
stackingOrder: integer(child, "z") });
- const temporal = createTemporalWindowProjection({ id: itemSpec.id, element: child, ...context, resolveReference });
+ const temporal = createTemporalWindowConstruction({ id: itemSpec.id, element: child, ...context, resolveReference });
records.push(...temporal.records); temporalComponents.push(...temporal.components); temporalFragments.push(...temporal.fragments);
const specId = `${id}.item.${suffix}.spec`; const specName = `item-${suffix}-spec`;
records.push({ id: specId, type: screenOverlayTypes.itemSpec, value: { kind: "inline", value: itemSpec }, range: child.range });
@@ -85,5 +85,5 @@ export const decodeScreenOverlaySurface: StructuredSurfaceHandler = ({ element,
}
if (fragmentItems.length === 0) throw new Error(`${element.name} requires at least one component.`);
const fragment = createScreenOverlayFragment(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`] };
+ return { records, components: [...temporalComponents, { id, fragment: fragment.id, inputs, outputs: { program: `${id}.program`, visual: `${id}.visual` }, range: element.range }], fragments: [...temporalFragments, fragment], exports: [`${id}.program`, `${id}.visual`] };
};
diff --git a/packages/screen-overlay/src/types.ts b/packages/screen-overlay/src/types.ts
index 0284b918..a276885a 100644
--- a/packages/screen-overlay/src/types.ts
+++ b/packages/screen-overlay/src/types.ts
@@ -60,7 +60,8 @@ export type ScreenOverlayItemProgram = {
readonly subjectId: string;
readonly span: FrameSpan;
readonly content: ScreenOverlayComponent;
- readonly stacking: { readonly order: number; readonly tieBreak: string };
+ readonly order: number;
+ readonly z: number;
};
export type ScreenOverlaySet = { readonly items: readonly ScreenOverlayItemProgram[] };
export type ScreenOverlayProgram = {
diff --git a/packages/screen-overlay/test/screen-overlay.test.ts b/packages/screen-overlay/test/screen-overlay.test.ts
index 1ced2bc3..13fad844 100644
--- a/packages/screen-overlay/test/screen-overlay.test.ts
+++ b/packages/screen-overlay/test/screen-overlay.test.ts
@@ -1,4 +1,4 @@
-import { sealTimeline } from "@hypit/timeline";
+import { sealTimeline, timelineManifest, timelineDependency, timelineTypes } from "@hypit/timeline";
import assert from "node:assert/strict";
import test from "node:test";
import { fixtureResource } from "../../../test/fixture-resource.js";
@@ -13,7 +13,6 @@ import { AuthorFrontendRegistry, compileSourceClosure, resolveCompiledSourceExpo
import { compileHyperframesDocument } from "@hypit/hyperframes";
import { mediaManifest } from "@hypit/media";
import { narrativeManifest } from "@hypit/narrative";
-import { programSpaceManifest, sealProgramSpace } from "@hypit/program-space";
import type { ModuleManifest } from "@hypit/protocol";
import {
appendProjectedScreenOverlay,
@@ -30,21 +29,21 @@ import {
sealScreenOverlayItemSpec,
} from "@hypit/screen-overlay";
import type { ScreenOverlayComponent } from "@hypit/screen-overlay";
-import { timelineDependency, timelineManifest, timelineProducers, timelineTypes } from "@hypit/timeline";
import { speechEvidenceManifest } from "@hypit/speech-evidence";
import { speechManifest } from "@hypit/speech";
-import { sealCanvasSpace, spatialComponent, spatialDependency, spatialManifest, spatialTypes } from "@hypit/spatial";
+import { narrativeTemporalManifest } from "@hypit/narrative-temporal";
+import { sealCanvas, spatialComponent, spatialDependency, spatialManifest, spatialTypes } from "@hypit/spatial";
import { svsManifest } from "@hypit/svs";
import { temporalManifest, temporalProducers } from "@hypit/temporal";
import { MarkupSurfaceRegistry, createMarkupAuthorFrontend } from "@hypit/markup";
import { createRecordAdmitter, TypeValidatorRegistry } from "@hypit/validation";
import { visualIrManifest } from "@hypit/visual-ir";
-const canvas = sealCanvasSpace({
+const canvas = sealCanvas({
widthPx: 1080, heightPx: 1920,
- origin: "top-left", xDirection: "right", yDirection: "down", pixelAspect: "square",
});
-const space = sealTimeline({ items: [], id: "test-space", durationSec: 2, frameRate: { numerator: 30, denominator: 1 },
+const within = { xPx: 0, yPx: 0, widthPx: canvas.widthPx, heightPx: canvas.heightPx };
+const space = sealTimeline({ id: "test-space", frameCount: 60, frameRate: { numerator: 30, denominator: 1 },
});
const header = sealScreenOverlayHeader({ id: "screen" });
const semantic = timelineFixture(space);
@@ -70,9 +69,9 @@ function trackFor(content: ScreenOverlayComponent, stackingOrder = 50) {
});
const window = projectProgramWindow({
itemId: spec.id, semantic,
- projection: { start: { ref: "program.start" }, end: { ref: "program.end" } },
+ projection: { start: { ref: "timeline.start" }, end: { ref: "timeline.end" } },
});
- return renderScreenOverlay(canvas, space, finalizeScreenOverlay(
+ return renderScreenOverlay(within, space, finalizeScreenOverlay(
appendProjectedScreenOverlay(createScreenOverlaySet(), header, space, spec, window), header,
));
}
@@ -108,9 +107,9 @@ test("explicit seeds control stochastic component identity", () => {
test("overlay Tracks interleave with peer Tracks only through absolute stacking", () => {
const below = trackFor(components[1]!, 20);
const above = { ...trackFor(components[0]!, 80), id: "screen-above" };
- const middle = sealVisualTrack({ programSpaceId: "test-space",
+ const middle = sealVisualTrack({ timelineId: "test-space",
visualIr: "hypit.visual-ir@1", id: "middle",
- presents: [{ id: "middle", span: { startFrame: 0, endFrameExclusive: 60 }, stacking: { order: 50, tieBreak: "middle" },
+ presents: [{ id: "middle", order: 0, z: 50, span: { startFrame: 0, endFrameExclusive: 60 },
elements: [{ id: "root", order: 0, kind: "box", style: [{ name: "background-color", value: "#112233" }] }] }],
});
const document = compileHyperframesDocument(sealComposition({
@@ -125,10 +124,10 @@ test("overlay Tracks interleave with peer Tracks only through absolute stacking"
test("the Screen Overlay Fragment publishes its Program and peer VisualTrack", () => {
const fragment = createScreenOverlayFragment([{ specName: "spec", windowName: "window" }]);
- assert.deepEqual(fragment.inputs.map((input) => input.name), ["canvas", "header", "spec", "timeline", "window"]);
+ assert.deepEqual(fragment.inputs.map((input) => input.name), ["header", "spec", "timeline", "window", "within"]);
assert.deepEqual(fragment.exports.map((output) => [output.name, output.type.name]), [
["program", "ScreenOverlayProgram"],
- ["track", "VisualTrack"],
+ ["visual", "VisualTrack"],
]);
});
@@ -137,7 +136,7 @@ test("the self-described Screen Surface parses into a finite peer-Track graph",
const fixtureSurfaceDigest = fixtureResource("example.screen-inputs/surface@1");
const fixtureSurface = {
name: "inputs", tag: "Inputs", mode: "structured",
- outputs: [spatialTypes.canvas, timelineTypes.track],
+ outputs: [spatialTypes.frame, timelineTypes.track],
} as const;
const fixtureManifest: ModuleManifest = {
format: "hypit.module@1",
@@ -152,10 +151,10 @@ test("the self-described Screen Surface parses into a finite peer-Track graph",
artifactManifest,
mediaManifest,
narrativeManifest,
- programSpaceManifest,
+ timelineManifest,
speechManifest,
+ narrativeTemporalManifest,
speechEvidenceManifest,
- timelineManifest,
spatialManifest,
svsManifest,
temporalManifest,
@@ -167,7 +166,7 @@ test("the self-described Screen Surface parses into a finite peer-Track graph",
const registry = new MarkupSurfaceRegistry();
registry.registerStructured({ module: fixtureModule, declaration: fixtureSurface, handler: ({ element }) => ({
records: [
- { id: "canvas", type: spatialTypes.canvas, value: { kind: "inline", value: canvas }, range: element.range },
+ { id: "within", type: spatialTypes.frame, value: { kind: "inline", value: within }, range: element.range },
{ id: "semantic", type: timelineTypes.track, value: { kind: "inline", value: semantic }, range: element.range },
],
components: [],
@@ -194,8 +193,8 @@ test("the self-described Screen Surface parses into a finite peer-Track graph",
<import as="fixture" from="example.screen-inputs@1"/>
<import as="screen" from="@hypit/screen-overlay@1"/>
<fixture:Inputs/>
- <screen:Track id="screen-fx" canvas={canvas} timeline={semantic}>
- <screen:Flash during="program" z="70" color="#ffffff" intensity="0.9" attack="2" hold="3" decay="5"/>
+ <screen:Track id="screen-fx" within={within} timeline={semantic}>
+ <screen:Flash during="timeline" z="70" color="#ffffff" intensity="0.9" attack="2" hold="3" decay="5"/>
</screen:Track>
</svml>`,
},
@@ -204,7 +203,7 @@ test("the self-described Screen Surface parses into a finite peer-Track graph",
admitRecord: createRecordAdmitter(validators),
resolveSource() { throw new Error("Screen fixture has no source imports."); },
});
- const trackExport = resolveCompiledSourceExport(compiled, "screen-fx.track", compositionTypes.visualTrack);
+ const trackExport = resolveCompiledSourceExport(compiled, "screen-fx.visual", compositionTypes.visualTrack);
assert.equal(trackExport.ref.kind, "logical-output");
const build = start(compiled.program, compiled.graph, sealBuildRequest({
targets: [{ output: trackExport.ref.kind === "logical-output" ? trackExport.ref.id : "" }],
diff --git a/packages/script-studio/src/projection.ts b/packages/script-studio/src/projection.ts
index 962a56aa..a395a6e0 100644
--- a/packages/script-studio/src/projection.ts
+++ b/packages/script-studio/src/projection.ts
@@ -28,7 +28,7 @@ type NarrativeValue = {
readonly semanticIndex?: {
readonly anchors?: readonly {
readonly id: string;
- readonly kind: "program-start" | "segment-start" | "segment-end" | "token-start" | "token-end" | "program-end";
+ readonly kind: "segment-start" | "segment-end" | "token-start" | "token-end";
readonly segmentId?: string;
readonly tokenId?: string;
}[];
diff --git a/packages/script/README.md b/packages/script/README.md
index f8966655..3db4237a 100644
--- a/packages/script/README.md
+++ b/packages/script/README.md
@@ -2,8 +2,9 @@
Official raw Script Surface for the Markup Frontend. It parses prose-first named Segment blocks,
newline-independent Role Cues, Dual Text, Selection and Moment syntax, and lowers them to a
-canonical authored Narrative value with exactly `2M + 2N + 2` semantic anchor identities: both
-ends of every Token and Segment, plus the Script Program's own start and end.
+canonical authored Narrative value with exactly `2M + 2N` semantic anchor identities: both
+ends of every Token and Segment. Script adds no synthetic Narrative or program boundary anchors;
+absolute work boundaries belong to Timeline.
The package is an ordinary statically declared Surface module. Core does not import it and does not
know that Script, Segment or Narrative exist.
@@ -35,7 +36,8 @@ numbers; capitalization does not distinguish Roles from Segments.
An empty Segment such as `<empty></empty>` (or `<empty/>`) is valid. `empty` is an ordinary
author-chosen name, not a reserved keyword. It retains the Segment identity and both boundary anchors
while contributing no Tokens or spoken text. This supports wordless passages in the same semantic
-model: the associated normalized media, not the empty tag, determines the SemanticTake's duration.
+model: an associated local temporal domain determines duration, while NarrativeAlignment supplies
+the Segment boundary relation with no word units.
The package exports its Manifest, `parseScript`, semantic/source-map projection helpers, a
semantic-preserving formatter and the raw `decodeScriptSurface` handler. Source ranges and parser
@@ -45,7 +47,7 @@ components without importing Script internals.
The Surface exports one full Narrative plus narrow, immutable views:
-- `script.segment.<id>` is a narrow `NarrativeExcerpt` used to associate a generated Take with one Segment;
+- `script.segment.<id>` is a narrow `NarrativeExcerpt` used to align generated or supplied media with one Segment;
- `script.segment.<id>.dialogue` is ordinary `Text`: display-independent dialogue, including optional
Role cues and right-side Dual Text pronunciation, for a speech-video model;
- `script.segment.<id>.speech` is ordinary pronunciation-only `Text` for duration estimation or TTS;
@@ -54,8 +56,8 @@ The Surface exports one full Narrative plus narrow, immutable views:
- `script.selection.<id>` is a reusable explicit Selection;
- `script.moment.<id>` is a reusable explicit Moment.
-`@hypit/caption` projects `script.selection.<id>` or a Role onto complete Caption Alignment Units;
-it then joins those units to a Timeline for frame timing. Seedance consumes dialogue `Text`,
+`@hypit/narrative-caption` relates the separately exported Caption units to Narrative Tokens and
+projects them through explicit Narrative time. Seedance consumes dialogue `Text`,
Estimate and TTS consume speech `Text`, and semantic preparation consumes the Segment excerpt. None imports
Script's parser AST. Another authoring package may produce the same ordinary Text, Narrative and
CaptionDocument contracts.
@@ -69,7 +71,7 @@ CaptionDocument contracts.
`<display text | spoken text>`. In `<display text|>`, omitted speech inherits the displayed prose.
- **Selection marker**: a named semantic range, written `@{name} ... @{/name}`.
- **Moment marker**: a named semantic point, written `@{name!}`.
-- **CaptionDocument**: the Script-owned caption truth; it contains **Display Words**,
+- **CaptionDocument**: a Caption-owned value produced by Script; it contains **Display Words**,
**Alignment Units** and **Cue Breaks**. It contains no seconds or frames.
- **Token attribute**: a flat postfix display-word annotation such as `really{emphasis}` or
`really{emphasis,importance=2,tone=warm}`. Values may be strings, finite numbers or booleans. It
@@ -226,12 +228,12 @@ protocol identities remain `@1`. Existing rendered media is not modified by sour
## Complete authored content and narrow exports
-The root `story` Record contains the complete Narrative: speech structure, semantic references and
-its CaptionDocument. `story.caption`, `story.selection.<id>`, Segment excerpts and dialogue/speech
-Text outputs remain explicit narrow exports derived from that content. Caption rendering can read
-the document and Timeline. Timed Uses change its presentation; their semantic references are
-projected through the same Timeline as other components. Word attributes remain in the document
-for families that give those words structural visual roles.
+The root `story` Record contains only the complete Narrative: speech structure and semantic
+references. `story.caption`, `story.caption-binding`, `story.selection.<id>`, Segment excerpts and
+dialogue/speech Text are peer exports derived from the same parse. The binding relates Caption units
+to Narrative Tokens without embedding either value in the other. Caption rendering reads the
+document and already resolved CaptionTiming. Word attributes remain in the document for families
+that give those words structural visual roles.
For content lookup, use the Narrative package's `narrativeTokensForSelection` or
`narrativeSelectionTokenRange`. These query authored order; Timeline separately locates the same
diff --git a/packages/script/package.json b/packages/script/package.json
index 2cd47055..6426a35f 100644
--- a/packages/script/package.json
+++ b/packages/script/package.json
@@ -11,7 +11,9 @@
"activation": "./src/activation.ts"
},
"dependencies": {
+ "@hypit/caption": "workspace:*",
"@hypit/narrative": "workspace:*",
+ "@hypit/narrative-caption": "workspace:*",
"@hypit/protocol": "workspace:*",
"@hypit/text": "workspace:*",
"@hypit/markup": "workspace:*"
diff --git a/packages/script/src/edit.ts b/packages/script/src/edit.ts
index 2bf1c90c..9aa948b5 100644
--- a/packages/script/src/edit.ts
+++ b/packages/script/src/edit.ts
@@ -27,23 +27,11 @@ export type ScriptMomentAdjustment = {
type Edit = { readonly range: SourceRange; readonly replacement: string };
-/** Script owns the exact source inverse of every one of its 2M + 2N + 2 anchors. */
+/** Script owns the exact source inverse of every one of its 2M + 2N anchors. */
export function scriptAnchorEditSites(parsed: ParsedNarrative): readonly ScriptAnchorEditSite[] {
const segments = new Map(parsed.segments.map((segment) => [segment.id, segment] as const));
const tokens = new Map(parsed.tokens.map((token) => [token.id, token] as const));
return parsed.semanticIndex.anchors.map((anchor): ScriptAnchorEditSite => {
- if (anchor.kind === "program-start") {
- return {
- anchorId: anchor.id, kind: anchor.kind, offset: parsed.sourceRange.start,
- affinity: "left", placement: "before",
- };
- }
- if (anchor.kind === "program-end") {
- return {
- anchorId: anchor.id, kind: anchor.kind, offset: parsed.sourceRange.end,
- affinity: "right", placement: "after",
- };
- }
const segmentId = anchor.segmentId;
const segment = segments.get(segmentId);
if (segment === undefined) throw new Error(`Semantic Anchor ${anchor.id} names unknown Segment ${segmentId}.`);
diff --git a/packages/script/src/index.ts b/packages/script/src/index.ts
index f502de57..98ee2616 100644
--- a/packages/script/src/index.ts
+++ b/packages/script/src/index.ts
@@ -1,10 +1,11 @@
export { ScriptSyntaxError } from "./error.js";
export { adjustScriptMoment, adjustScriptSelection, scriptAnchorEditSites } from "./edit.js";
export { formatScript } from "./format.js";
-export { captionDocumentType, narrativeExcerptType, narrativeMomentType, narrativeSelectionType, narrativeSchema, narrativeType, scriptManifest, scriptMarkupSurfaces, scriptModuleRef } from "./manifest.js";
+export { captionDocumentType, narrativeCaptionBindingType, narrativeExcerptType, narrativeMomentType, narrativeSelectionType, narrativeSchema, narrativeType, scriptManifest, scriptMarkupSurfaces, scriptModuleRef } from "./manifest.js";
export {
captionDocument,
captionDocumentValue,
+ narrativeCaptionBinding,
narrativeDialogueTextValue,
narrativeSegmentExcerptValue,
narrativeMomentValue,
diff --git a/packages/script/src/manifest.ts b/packages/script/src/manifest.ts
index 38d03ed6..8688e942 100644
--- a/packages/script/src/manifest.ts
+++ b/packages/script/src/manifest.ts
@@ -1,4 +1,6 @@
+import { captionDependency, captionTypes } from "@hypit/caption";
import { narrativeDependency, narrativeSchema, narrativeTypes } from "@hypit/narrative";
+import { narrativeCaptionDependency, narrativeCaptionTypes } from "@hypit/narrative-caption";
import { textDependency, textTypes } from "@hypit/text";
import type { ModuleManifest, TypeRef } from "@hypit/protocol";
@@ -7,7 +9,8 @@ export const narrativeType: TypeRef = narrativeTypes.narrative;
export const narrativeExcerptType: TypeRef = narrativeTypes.excerpt;
export const narrativeSelectionType: TypeRef = narrativeTypes.selection;
export const narrativeMomentType: TypeRef = narrativeTypes.moment;
-export const captionDocumentType: TypeRef = narrativeTypes.captionDocument;
+export const captionDocumentType: TypeRef = captionTypes.document;
+export const narrativeCaptionBindingType: TypeRef = narrativeCaptionTypes.binding;
export { narrativeSchema };
export const scriptMarkupSurfaces = [
@@ -22,6 +25,7 @@ export const scriptMarkupSurfaces = [
narrativeSelectionType,
narrativeMomentType,
captionDocumentType,
+ narrativeCaptionBindingType,
],
vocabulary: {
summary: "Holds every spoken word as prose-first Segments and publishes the authored Narrative with the Selections, Moments and text projections the rest of the source reads.",
@@ -40,7 +44,9 @@ export const scriptMarkupSurfaces = [
{ name: "segment.<id>.speech", type: textTypes.text,
summary: "One Segment as pronunciation only, with Role Cue labels dropped." },
{ name: "caption", type: captionDocumentType,
- summary: "The Narrative's CaptionDocument exported as a narrow view: display Words, N:M Alignment Units, Cue breaks and speech correspondence." },
+ summary: "A source-neutral CaptionDocument: display Words, grouping units and Cue breaks." },
+ { name: "caption-binding", type: narrativeCaptionBindingType,
+ summary: "The explicit relation from Caption units to this Narrative's speech Tokens." },
{ name: "selection.<id>", type: narrativeSelectionType,
summary: "One named range over the Narrative, reusable wherever a Selection is read." },
{ name: "moment.<id>", type: narrativeMomentType,
@@ -89,7 +95,7 @@ export const scriptManifest: ModuleManifest = {
format: "hypit.module@1",
name: scriptModuleRef.name,
version: scriptModuleRef.version,
- dependencies: [narrativeDependency, textDependency],
+ dependencies: [captionDependency, narrativeDependency, narrativeCaptionDependency, textDependency],
types: [],
capabilities: [],
producers: [],
diff --git a/packages/script/src/narrative.ts b/packages/script/src/narrative.ts
index 39eab801..a5ee5170 100644
--- a/packages/script/src/narrative.ts
+++ b/packages/script/src/narrative.ts
@@ -1,6 +1,7 @@
import { canonicalize } from "@hypit/protocol";
import type { CanonicalValue } from "@hypit/protocol";
-import type { CaptionAlignmentUnit, CaptionDocument, CaptionDisplayWord } from "@hypit/narrative";
+import type { CaptionDocument, CaptionDisplayWord, CaptionUnit } from "@hypit/caption";
+import type { NarrativeCaptionBinding } from "@hypit/narrative-caption";
import { sealText } from "@hypit/text";
import type { ParsedCaptionRegion, ParsedNarrative } from "./types.js";
@@ -15,8 +16,16 @@ function turnForRegion(parsed: ParsedNarrative, region: ParsedCaptionRegion): Pa
return turn;
}
-function projectCaption(parsed: ParsedNarrative, id: string, narrativeId: string): CaptionDocument {
- const units: CaptionAlignmentUnit[] = [];
+type CaptionViews = { readonly document: CaptionDocument; readonly binding: NarrativeCaptionBinding };
+
+function projectCaption(
+ parsed: ParsedNarrative,
+ documentId: string,
+ narrativeId: string,
+ bindingId = `${documentId}.binding`,
+): CaptionViews {
+ const units: CaptionUnit[] = [];
+ const bindings: Array<{ unitId: string; sourceTokenIds: readonly string[] }> = [];
const words: CaptionDisplayWord[] = [];
for (const region of parsed.captionProjection.regions) {
if (region.kind === "hidden") continue;
@@ -36,16 +45,13 @@ function projectCaption(parsed: ParsedNarrative, id: string, narrativeId: string
}
let sourceCursor = region.startToken;
for (const group of groups) {
- const unitId = `${id}:unit:${units.length + 1}`;
+ const unitId = `${documentId}:unit:${units.length + 1}`;
const unitWordIds = group.surfaces.map((surface, groupIndex) => {
const wordId = `${unitId}:word:${groupIndex + 1}`;
const attributes = region.marks.find((mark) => mark.displayIndex === group.indices[groupIndex])?.attributes ?? [];
words.push({
id: wordId,
unitId,
- segmentId: region.segmentId,
- turnId: turn.id,
- ...(turn.role === undefined ? {} : { role: turn.role }),
text: surface,
separatorBefore: group.indices[groupIndex] === 0 ? region.separatorBefore : display[group.indices[groupIndex]!]!.separatorBefore,
attributes,
@@ -59,12 +65,11 @@ function projectCaption(parsed: ParsedNarrative, id: string, narrativeId: string
if (sourceTokenIds.length === 0) throw new Error(`Caption Unit ${unitId} has no authored speech correspondence`);
units.push({
id: unitId,
- segmentId: region.segmentId,
- turnId: turn.id,
+ groupId: `${region.segmentId}:${turn.id}`,
...(turn.role === undefined ? {} : { role: turn.role }),
wordIds: unitWordIds,
- sourceTokenIds,
});
+ bindings.push({ unitId, sourceTokenIds });
sourceCursor = sourceEnd;
}
if (sourceCursor !== region.endTokenExclusive) {
@@ -75,7 +80,8 @@ function projectCaption(parsed: ParsedNarrative, id: string, narrativeId: string
const tokenIndex = new Map(parsed.tokens.map((token) => [token.id, token.index]));
const cueBreaks = parsed.captionProjection.breaks.map((breakPoint) => {
const next = units.findIndex((unit) => {
- const indexes = unit.sourceTokenIds.map((tokenId) => tokenIndex.get(tokenId));
+ const binding = bindings.find((candidate) => candidate.unitId === unit.id)!;
+ const indexes = binding.sourceTokenIds.map((tokenId) => tokenIndex.get(tokenId));
return indexes.every((index): index is number => index !== undefined)
&& Math.min(...indexes) >= breakPoint.tokenIndex;
});
@@ -83,7 +89,8 @@ function projectCaption(parsed: ParsedNarrative, id: string, narrativeId: string
throw new Error("Caption Cue break must lie between two complete Alignment Units");
}
const previous = units[next - 1]!;
- const previousIndexes = previous.sourceTokenIds.map((tokenId) => tokenIndex.get(tokenId));
+ const previousBinding = bindings.find((candidate) => candidate.unitId === previous.id)!;
+ const previousIndexes = previousBinding.sourceTokenIds.map((tokenId) => tokenIndex.get(tokenId));
if (previousIndexes.some((index) => index === undefined)
|| Math.max(...previousIndexes as number[]) + 1 !== breakPoint.tokenIndex) {
throw new Error("Caption Cue break cannot split an Alignment Unit");
@@ -96,20 +103,27 @@ function projectCaption(parsed: ParsedNarrative, id: string, narrativeId: string
// immediately before `</segment>`.
const breaks = new Set(cueBreaks.map((item) => item.afterUnitId));
for (let index = 0; index < units.length - 1; index += 1) {
- if (units[index]!.segmentId === units[index + 1]!.segmentId) continue;
+ if (units[index]!.groupId === units[index + 1]!.groupId) continue;
breaks.add(units[index]!.id);
}
return {
- narrativeId,
- id,
- units,
- words,
- cueBreaks: units.filter((unit) => breaks.has(unit.id)).map((unit) => ({ afterUnitId: unit.id })),
+ document: { id: documentId, units, words,
+ cueBreaks: units.filter((unit) => breaks.has(unit.id)).map((unit) => ({ afterUnitId: unit.id })) },
+ binding: { id: bindingId, narrativeId, documentId, units: bindings },
};
}
export function captionDocument(parsed: ParsedNarrative, id: string, narrativeId: string): CaptionDocument {
- return projectCaption(parsed, id, narrativeId);
+ return projectCaption(parsed, id, narrativeId).document;
+}
+
+export function narrativeCaptionBinding(
+ parsed: ParsedNarrative,
+ documentId: string,
+ narrativeId: string,
+ bindingId?: string,
+): NarrativeCaptionBinding {
+ return projectCaption(parsed, documentId, narrativeId, bindingId).binding;
}
export function captionDocumentValue(parsed: ParsedNarrative, id: string, narrativeId: string): CanonicalValue {
@@ -182,7 +196,6 @@ export function narrativeMomentValue(moment: ParsedNarrative["moments"][number],
export function narrativeValue(parsed: ParsedNarrative, id: string): CanonicalValue {
return canonicalize({
id,
- caption: captionDocument(parsed, `${id}.caption`, id),
segments: parsed.segments.map((segment) => ({
id: segment.id,
startAnchorId: segment.startAnchorId,
diff --git a/packages/script/src/parser.ts b/packages/script/src/parser.ts
index 86711db3..a4ad0822 100644
--- a/packages/script/src/parser.ts
+++ b/packages/script/src/parser.ts
@@ -760,11 +760,11 @@ export function parseScript(
const segmentById = new Map(segments.map((segment) => [segment.id, segment]));
/**
- * Resolve one marker to the exact `2m + 2n + 2` anchor its affinity names. Token and
+ * Resolve one marker to the exact `2m + 2n` anchor its affinity names. Token and
* Segment cuts are equal citizens: a marker with nothing to its left inside a
* Segment snaps to that Segment's own start, never across into the previous
- * Segment, whose end may sit at a different time. At the Script body's outer
- * cuts, affinity distinguishes the Program boundary from its first/last Segment.
+ * Segment, whose end may sit at a different time. The Script body's outer cuts
+ * are the first Segment start and last Segment end; Script owns no Timeline bounds.
*/
const anchorForBoundary = (boundary: RawMarkerBoundary, affinity: Affinity): string => {
if (segments.length === 0) fail("SCRIPT_ANCHOR_UNRESOLVED", "Script declares no Segment to anchor markers to.");
@@ -782,10 +782,10 @@ export function parseScript(
// Outside or between Segments: structuralPosition counts the Segments already closed.
if (affinity === "left") {
const previous = segments[boundary.structuralPosition - 1];
- return previous ? previous.endAnchorId : "program:start";
+ return previous ? previous.endAnchorId : segments[0]!.startAnchorId;
}
const next = segments[boundary.structuralPosition];
- return next ? next.startAnchorId : "program:end";
+ return next ? next.startAnchorId : segments.at(-1)!.endAnchorId;
};
const anchored = <T extends { readonly affinity: Affinity; readonly boundary: RawMarkerBoundary }>(
edge: T,
@@ -795,7 +795,6 @@ export function parseScript(
});
const anchors: SemanticAnchor[] = [
- { id: "program:start", kind: "program-start" },
...segments.flatMap((segment) => [
{ id: segment.startAnchorId, kind: "segment-start" as const, segmentId: segment.id },
...tokens.slice(segment.tokenStart, segment.tokenEndExclusive).flatMap((token) => [
@@ -804,22 +803,19 @@ export function parseScript(
kind: "token-start" as const,
segmentId: segment.id,
tokenId: token.id,
- segmentTokenIndex: token.segmentTokenIndex,
},
{
id: token.endAnchorId,
kind: "token-end" as const,
segmentId: segment.id,
tokenId: token.id,
- segmentTokenIndex: token.segmentTokenIndex,
},
]),
{ id: segment.endAnchorId, kind: "segment-end" as const, segmentId: segment.id },
]),
- { id: "program:end", kind: "program-end" },
];
- if (anchors.length !== 2 * tokens.length + 2 * segments.length + 2) {
- fail("SCRIPT_ANCHOR_CARDINALITY", "Semantic anchor cardinality is not 2M + 2N + 2.");
+ if (anchors.length !== 2 * tokens.length + 2 * segments.length) {
+ fail("SCRIPT_ANCHOR_CARDINALITY", "Semantic anchor cardinality is not 2M + 2N.");
}
return {
diff --git a/packages/script/src/surface.ts b/packages/script/src/surface.ts
index fdc8a261..cb0b2829 100644
--- a/packages/script/src/surface.ts
+++ b/packages/script/src/surface.ts
@@ -1,5 +1,7 @@
import { ScriptSyntaxError } from "./error.js";
import {
+ captionDocumentValue,
+ narrativeCaptionBinding,
narrativeDialogueTextValue,
narrativeSegmentExcerptValue,
narrativeMomentValue,
@@ -9,11 +11,13 @@ import {
} from "./narrative.js";
import {
captionDocumentType,
+ narrativeCaptionBindingType,
narrativeExcerptType,
narrativeMomentType,
narrativeSelectionType,
narrativeType,
} from "./manifest.js";
+import { canonicalize } from "@hypit/protocol";
import { textTypes } from "@hypit/text";
import { parseScript } from "./parser.js";
import type { ScriptSurfaceInput, ScriptSurfaceOutput } from "./types.js";
@@ -75,7 +79,13 @@ export function decodeScriptSurface(input: ScriptSurfaceInput): ScriptSurfaceOut
input.contentStart,
);
const narrative = narrativeValue(parsed, rawId);
- const caption = (narrative as { readonly caption: import("@hypit/protocol").CanonicalValue }).caption;
+ const caption = captionDocumentValue(parsed, `${rawId}.caption`, rawId);
+ const captionBinding = canonicalize(narrativeCaptionBinding(
+ parsed,
+ `${rawId}.caption`,
+ rawId,
+ `${rawId}.caption-binding`,
+ ));
const captionId = `${rawId}.caption`;
return {
nextOffset: close.end,
@@ -112,6 +122,12 @@ export function decodeScriptSurface(input: ScriptSurfaceInput): ScriptSurfaceOut
value: { kind: "inline" as const, value: caption },
range: { start: input.openingStart, end: close.end },
},
+ {
+ id: `${rawId}.caption-binding`,
+ type: narrativeCaptionBindingType,
+ value: { kind: "inline" as const, value: captionBinding },
+ range: { start: input.openingStart, end: close.end },
+ },
...parsed.selections.map((selection) => ({
id: `${rawId}.selection.${selection.id}`,
type: narrativeSelectionType,
diff --git a/packages/script/src/types.ts b/packages/script/src/types.ts
index ca369d04..90b182f9 100644
--- a/packages/script/src/types.ts
+++ b/packages/script/src/types.ts
@@ -1,7 +1,9 @@
import type { CanonicalValue, SourceRange, StoredValue, TypeRef } from "@hypit/protocol";
-import type { CaptionWordAttribute, Narrative, NarrativeMoment, NarrativeSegment, NarrativeSelection, NarrativeToken, NarrativeTurn } from "@hypit/narrative";
+import type { CaptionWordAttribute } from "@hypit/caption";
+import type { Narrative, NarrativeMoment, NarrativeSegment, NarrativeSelection, NarrativeToken, NarrativeTurn } from "@hypit/narrative";
-export type { CaptionWordAttribute, Narrative, SemanticAnchor } from "@hypit/narrative";
+export type { CaptionWordAttribute } from "@hypit/caption";
+export type { Narrative, SemanticAnchor } from "@hypit/narrative";
export type Affinity = "left" | "right";
@@ -78,9 +80,9 @@ export type ParsedCaptionRegion = {
export type ParsedNarrative = Omit<
Narrative,
- "id" | "segments" | "tokens" | "turns" | "selections" | "moments" | "caption"
+ "id" | "segments" | "tokens" | "turns" | "selections" | "moments"
> & {
- /** Exact Script body range, used only for source-preserving Program-boundary edits. */
+ /** Exact Script body range, used for source-preserving edits and comparisons. */
readonly sourceRange: SourceRange;
readonly segments: readonly ParsedSegment[];
readonly tokens: readonly ParsedToken[];
diff --git a/packages/script/test/display-spacing.test.ts b/packages/script/test/display-spacing.test.ts
index ed0fd629..de464084 100644
--- a/packages/script/test/display-spacing.test.ts
+++ b/packages/script/test/display-spacing.test.ts
@@ -5,12 +5,13 @@ import { tmpdir } from "node:os";
import { join } from "node:path";
import { execFileSync } from "node:child_process";
import { fileURLToPath } from "node:url";
-import { adjustScriptSelection, captionDocument, parseScript, serializeCaption, serializeSpeech } from "@hypit/script";
+import { adjustScriptSelection, captionDocument, narrativeCaptionBinding, parseScript, serializeCaption, serializeSpeech } from "@hypit/script";
function displayed(body: string) {
const parsed = parseScript("display", `<line>${body}</line>`);
const document = captionDocument(parsed, "caption", "story");
- return { parsed, document, text: document.words.map(word => word.separatorBefore + word.text).join("") };
+ const binding = narrativeCaptionBinding(parsed, "caption", "story");
+ return { parsed, document, binding, text: document.words.map(word => word.separatorBefore + word.text).join("") };
}
for (const text of [
@@ -46,11 +47,11 @@ test("markers, properties and Dual Text boundaries never invent or discard a sep
});
test("shared groups keep punctuation, properties, internal anchors and speech correspondence", () => {
- const { parsed, document, text } = displayed("<组@{beat!}件{emphasis}化|>");
+ const { parsed, document, binding, text } = displayed("<组@{beat!}件{emphasis}化|>");
assert.equal(text, "组件化");
assert.equal(serializeSpeech(parsed), "组件化");
assert.equal(document.units.length, 1);
- assert.equal(document.units[0]!.sourceTokenIds.length, 3);
+ assert.equal(binding.units[0]!.sourceTokenIds.length, 3);
assert.equal(parsed.moments[0]!.anchorId, parsed.tokens[1]!.startAnchorId);
assert.deepEqual(document.words[1]!.attributes, [{ name: "emphasis", value: true }]);
});
diff --git a/packages/script/test/markup-integration.test.ts b/packages/script/test/markup-integration.test.ts
index 98527504..f360de30 100644
--- a/packages/script/test/markup-integration.test.ts
+++ b/packages/script/test/markup-integration.test.ts
@@ -1,4 +1,6 @@
import { narrativeManifest } from "@hypit/narrative";
+import { captionManifest } from "@hypit/caption";
+import { narrativeCaptionManifest } from "@hypit/narrative-caption";
import type { Narrative, NarrativeExcerpt } from "@hypit/narrative";
import { textManifest } from "@hypit/text";
import assert from "node:assert/strict";
@@ -22,7 +24,7 @@ import {
} from "@hypit/markup";
function scriptContext() {
- const closure = createResolvedClosure([narrativeManifest, textManifest, scriptManifest]);
+ const closure = createResolvedClosure([captionManifest, narrativeManifest, narrativeCaptionManifest, textManifest, scriptManifest]);
const registry = new MarkupSurfaceRegistry();
registry.registerRaw({
module: scriptModuleRef,
@@ -62,7 +64,7 @@ test("Script teaches Markup <script> only through its imported Manifest", async
scriptContext(),
);
- assert.equal(result.records.length, 5);
+ assert.equal(result.records.length, 6);
assert.equal(result.records[0]?.id, "story");
assert.equal(result.records[0]?.type.name, "Narrative");
assert.equal(result.records.some((record) =>
@@ -73,6 +75,12 @@ test("Script teaches Markup <script> only through its imported Manifest", async
record.id === "story.segment.opening.speech" && record.type.name === "Text"), true);
assert.equal(result.records.some((record) =>
record.id === "story.caption" && record.type.name === "CaptionDocument"), true);
+ const captionBinding = result.records.find((record) => record.id === "story.caption-binding");
+ assert.equal(captionBinding?.type.name, "NarrativeCaptionBinding");
+ assert.equal(captionBinding?.value.kind, "inline");
+ if (captionBinding?.value.kind === "inline") {
+ assert.equal((captionBinding.value.value as { readonly id?: string }).id, "story.caption-binding");
+ }
assert.deepEqual(result.identities, [{ namespace: narrativeType, id: "story" }]);
});
@@ -87,7 +95,7 @@ test("without the import, Markup has no hard-coded knowledge of Script", async (
});
test("a raw Surface cannot consume the Markup document close", async () => {
- const closure = createResolvedClosure([narrativeManifest, textManifest, scriptManifest]);
+ const closure = createResolvedClosure([captionManifest, narrativeManifest, narrativeCaptionManifest, textManifest, scriptManifest]);
const registry = new MarkupSurfaceRegistry();
registry.registerRaw({
module: scriptModuleRef,
@@ -231,6 +239,6 @@ test("a wordless Script publishes its Segment and an empty CaptionDocument", asy
assert.ok(result.records.some((record) => record.id === "story.segment.empty"));
assert.deepEqual(result.records.find((record) => record.id === "story.caption")?.value, {
kind: "inline",
- value: { narrativeId: "story", id: "story.caption", units: [], words: [], cueBreaks: [] },
+ value: { id: "story.caption", units: [], words: [], cueBreaks: [] },
});
});
diff --git a/packages/script/test/narrative-views.test.ts b/packages/script/test/narrative-views.test.ts
index d8aed433..356942a6 100644
--- a/packages/script/test/narrative-views.test.ts
+++ b/packages/script/test/narrative-views.test.ts
@@ -1,12 +1,13 @@
import assert from "node:assert/strict";
import test from "node:test";
-import { captionDocument, decodeScriptSurface, formatScript, narrativeDialogueTextValue,
+import { captionDocument, narrativeCaptionBinding, decodeScriptSurface, formatScript, narrativeDialogueTextValue,
narrativeSpeechTextValue, narrativeValue, parseScript } from "@hypit/script";
import { assertNarrativeIdentity, narrativeAnchorTokenBoundary, narrativeSelectionTokenRange,
narrativeTokensForSelection, narrativeTypes } from "@hypit/narrative";
import type { Narrative, NarrativeSelectionRef } from "@hypit/narrative";
-import { captionUnitsForSelection, captionTypes, decodeHiddenCaptionStyleSurface, sealCaptionStyle } from "@hypit/caption";
-import type { CaptionProgram } from "@hypit/caption";
+import { captionTypes, decodeHiddenCaptionStyleSurface, sealCaptionStyle } from "@hypit/caption";
+import type { CaptionDocument, CaptionProgram } from "@hypit/caption";
+import { captionUnitsForNarrativeSelection } from "@hypit/narrative-caption";
import { parseStructuredElement } from "@hypit/markup";
import type { SurfaceResolvedReference } from "@hypit/markup";
import { countSpeechEstimateUnits } from "@hypit/estimate";
@@ -62,7 +63,7 @@ test("shared text permits semantic markers without changing display; empty group
assert.equal(parsed.serializations.speech, "组件化");
assert.equal(parsed.captionProjection.text, "组件化");
assert.equal(parsed.selections[0]!.startAnchorId, parsed.tokens[1]!.startAnchorId);
- assert.equal(captionDocument(parsed, "caption", "story").units[0]!.sourceTokenIds.length, 3);
+ assert.equal(narrativeCaptionBinding(parsed, "caption", "story").units[0]!.sourceTokenIds.length, 3);
for (const body of ['<|>', '< | >', '<@{beat!}|>', '<...|>']) {
assert.throws(() => parseScript("empty", `<intro>${body}</intro>`), /omitted speech must contain spoken text/u);
}
@@ -70,7 +71,7 @@ test("shared text permits semantic markers without changing display; empty group
assert.throws(() => parseScript("explicit", '<intro><@{bad} 字|word></intro>'), /spoken text, not the Dual display side/u);
});
-test("Script exports complete author content and a caption view from that same value", () => {
+test("Script exports Narrative and CaptionDocument as independent views from one source", () => {
const source = `<script id="story">${body}</script>`;
const result = decodeScriptSurface({ sourceName: "views.svml", source, tag: "script",
attributes: { id: "story" }, openingStart: 0, contentStart: source.indexOf(">") + 1 });
@@ -80,27 +81,32 @@ test("Script exports complete author content and a caption view from that same v
assert.equal(caption.value.kind, "inline");
if (root.value.kind !== "inline" || caption.value.kind !== "inline") return;
const narrative = root.value.value as unknown as Narrative;
+ const document = caption.value.value as unknown as CaptionDocument;
assertNarrativeIdentity(narrative);
- assert.strictEqual(narrative.caption, caption.value.value);
- assert.match(narrative.caption.words.map((word) => word.text).join(""), /hypit/);
- assert.match(narrative.caption.words.map((word) => word.text).join(""), /声工坊/);
- assert.ok(!narrative.caption.words.some((word) => word.text.includes("indeed")));
+ assert.equal("caption" in narrative, false);
+ assert.match(document.words.map((word) => word.text).join(""), /hypit/);
+ assert.match(document.words.map((word) => word.text).join(""), /声工坊/);
+ assert.ok(!document.words.some((word) => word.text.includes("indeed")));
assert.ok(narrative.tokens.some((token) => token.text === "indeed"));
- assert.equal(narrative.caption.cueBreaks.length, 1);
+ assert.equal(document.cueBreaks.length, 1);
});
test("Narrative selections query authored speech while Caption preserves display correspondence", () => {
const narrative = authored();
+ const parsed = parseScript("views.svml", body);
+ const document = captionDocument(parsed, "story.caption", "story");
+ const binding = narrativeCaptionBinding(parsed, "story.caption", "story");
const brand = narrative.selections.find((selection) => selection.id === "brand")!;
assert.equal(narrativeTokensForSelection(narrative, brand).map((token) => token.text).join(" "), "Hai-Pit");
const name = narrative.selections.find((selection) => selection.id === "name")!;
- const selected = new Set(captionUnitsForSelection(narrative, name).unitIds);
- assert.equal(narrative.caption.words.filter((word) => selected.has(word.unitId)).map((word) => word.text).join(""), "声工坊");
- const unit = narrative.caption.units.find((unit) => selected.has(unit.id))!;
- const first = narrative.tokens.find((token) => token.id === unit.sourceTokenIds[0])!;
- const last = narrative.tokens.find((token) => token.id === unit.sourceTokenIds.at(-1))!;
+ const selected = new Set(captionUnitsForNarrativeSelection(document, binding, narrative, name).unitIds);
+ assert.equal(document.words.filter((word) => selected.has(word.unitId)).map((word) => word.text).join(""), "声工坊");
+ const unit = document.units.find((unit) => selected.has(unit.id))!;
+ const bound = binding.units.find((candidate) => candidate.unitId === unit.id)!;
+ const first = narrative.tokens.find((token) => token.id === bound.sourceTokenIds[0])!;
+ const last = narrative.tokens.find((token) => token.id === bound.sourceTokenIds.at(-1))!;
assert.notEqual(first.id, last.id);
- assert.throws(() => captionUnitsForSelection(narrative, {
+ assert.throws(() => captionUnitsForNarrativeSelection(document, binding, narrative, {
id: "partial", startAnchorId: first.endAnchorId, endAnchorId: last.endAnchorId,
}), /partially selects/);
const foreign: NarrativeSelectionRef = { ...brand, narrativeId: "other" };
@@ -113,5 +119,9 @@ test("Content queries preserve structural boundaries even when no words lie betw
assert.deepEqual(narrativeTokensForSelection(narrative, { id: "gap", startAnchorId: gap.startAnchorId, endAnchorId: gap.endAnchorId }), []);
assert.equal(narrativeAnchorTokenBoundary(narrative, gap.startAnchorId), narrativeAnchorTokenBoundary(narrative, gap.endAnchorId));
assert.throws(() => narrativeSelectionTokenRange(narrative, { id: "backwards", startAnchorId: gap.endAnchorId, endAnchorId: gap.startAnchorId }), /anchor order/);
- assert.deepEqual(narrativeTokensForSelection(narrative, { id: "whole", startAnchorId: "program:start", endAnchorId: "program:end" }), narrative.tokens);
+ const first = narrative.segments[0]!;
+ const last = narrative.segments.at(-1)!;
+ assert.deepEqual(narrativeTokensForSelection(narrative, {
+ id: "whole", startAnchorId: first.startAnchorId, endAnchorId: last.endAnchorId,
+ }), narrative.tokens);
});
diff --git a/packages/script/test/prose-boundaries.test.ts b/packages/script/test/prose-boundaries.test.ts
index 14828280..01e15e07 100644
--- a/packages/script/test/prose-boundaries.test.ts
+++ b/packages/script/test/prose-boundaries.test.ts
@@ -1,6 +1,6 @@
import assert from "node:assert/strict";
import test from "node:test";
-import { adjustScriptMoment, captionDocument, parseScript, serializeCaption, serializeSpeech } from "@hypit/script";
+import { adjustScriptMoment, captionDocument, narrativeCaptionBinding, parseScript, serializeCaption, serializeSpeech } from "@hypit/script";
const parse = (text: string) => parseScript("boundary", `<line>${text}</line>`);
const caption = (text: string) => {
@@ -71,7 +71,8 @@ test("explicit groups keep internal speech anchors while display separators stay
const parsed = parse('<组@{beat!}件{emphasis}化|> 3D 한글');
assert.equal(serializeCaption(parsed), '组件化 3D 한글');
const document = captionDocument(parsed, 'caption', 'story');
- assert.deepEqual(document.units[0]!.sourceTokenIds, parsed.tokens.slice(0, 3).map(token => token.id));
+ assert.deepEqual(narrativeCaptionBinding(parsed, "caption", "story").units[0]!.sourceTokenIds,
+ parsed.tokens.slice(0, 3).map(token => token.id));
assert.equal(parsed.moments[0]!.anchorId, parsed.tokens[1]!.startAnchorId);
assert.equal(document.words.map(word => word.separatorBefore + word.text).join(''), '组件化 3D 한글');
});
diff --git a/packages/script/test/script.test.ts b/packages/script/test/script.test.ts
index ee3d65fb..5e5680b7 100644
--- a/packages/script/test/script.test.ts
+++ b/packages/script/test/script.test.ts
@@ -6,6 +6,7 @@ import {
adjustScriptMoment,
adjustScriptSelection,
captionDocument,
+ narrativeCaptionBinding,
narrativeValue,
parseScript,
serializeCaption,
@@ -13,7 +14,7 @@ import {
serializeSpeech,
} from "@hypit/script";
-test("Selection source edits relocate markers by 2M + 2N + 2 Anchor identity", () => {
+test("Selection source edits relocate markers by 2M + 2N Anchor identity", () => {
const source = "<one><HOST>@{focus} alpha beta @{/focus} gamma</one>\r\n<two><HOST>delta epsilon</two>";
const parsed = parseScript("selection-adjust.svml", source);
const movedWords = adjustScriptSelection({
@@ -48,30 +49,13 @@ test("Selection source edits relocate markers by 2M + 2N + 2 Anchor identity", (
]);
});
-test("Program boundaries are distinct writable semantic Anchors", () => {
- const source = "<one>alpha</one>\n<two>beta</two>";
- const withSelection = adjustScriptSelection({
- sourceName: "program-boundaries.svml",
- source: "@{focus} <one>alpha</one>\n<two>beta @{/focus}</two>",
- parsed: parseScript("program-boundaries.svml", "@{focus} <one>alpha</one>\n<two>beta @{/focus}</two>"),
- adjustment: { id: "focus", startAnchorId: "program:start", endAnchorId: "program:end" },
- });
- const selection = parseScript("program-boundaries.svml", withSelection).selections[0]!;
- assert.deepEqual([selection.startAnchorId, selection.endAnchorId], ["program:start", "program:end"]);
- assert.match(withSelection, /^@\{~focus\}(?=[ <])/u);
- assert.match(withSelection, /@\{\/focus~\}$/u);
-
- const withMoment = adjustScriptMoment({
- sourceName: "program-boundaries.svml",
- source: `${source.slice(0, source.indexOf("beta"))}@{cue!} ${source.slice(source.indexOf("beta"))}`,
- parsed: parseScript(
- "program-boundaries.svml",
- `${source.slice(0, source.indexOf("beta"))}@{cue!} ${source.slice(source.indexOf("beta"))}`,
- ),
- adjustment: { id: "cue", anchorId: "program:end" },
- });
- assert.equal(parseScript("program-boundaries.svml", withMoment).moments[0]!.anchorId, "program:end");
- assert.match(withMoment, /@\{cue!\}$/u);
+test("Script outer cuts are the first and last Segment boundaries", () => {
+ const source = "@{focus} <one>alpha</one>\n<two>beta</two> @{/focus}";
+ const parsed = parseScript("outer-cuts.svml", source);
+ const selection = parsed.selections[0]!;
+ assert.deepEqual([selection.startAnchorId, selection.endAnchorId], ["segment:one:start", "segment:two:end"]);
+ assert.equal(parsed.semanticIndex.anchors.length, 2 * parsed.tokens.length + 2 * parsed.segments.length);
+ assert.equal(parsed.semanticIndex.anchors.some((anchor) => anchor.id.startsWith("program:")), false);
});
test("Moment source edits relocate one marker to an exact semantic Anchor", () => {
@@ -95,10 +79,10 @@ test("Script keeps speech, dialogue and CaptionDocument as separate projections"
const document = captionDocument(parsed, "story.caption", "story");
assert.equal(document.units.length, 3);
assert.equal(document.units[1]!.wordIds.length, 1);
- assert.equal(document.units[1]!.sourceTokenIds.length, 4);
+ assert.equal(narrativeCaptionBinding(parsed, "story.caption", "story").units[1]!.sourceTokenIds.length, 4);
assert.deepEqual(document.cueBreaks, []);
assert.equal((narrativeValue(parsed, "story") as { semanticIndex: { anchors: unknown[] } }).semanticIndex.anchors.length,
- 2 * parsed.tokens.length + 2 * parsed.segments.length + 2);
+ 2 * parsed.tokens.length + 2 * parsed.segments.length);
});
test("Cue breaks are authored between complete units", () => {
@@ -190,7 +174,7 @@ test("Script projects flat token attributes onto display words without changing
["hypit", [{ name: "brand", value: true }]],
["now.", []],
]);
- assert.equal(document.units[3]!.sourceTokenIds.length, 2);
+ assert.equal(narrativeCaptionBinding(parsed, "story.caption", "story").units[3]!.sourceTokenIds.length, 2);
});
test("Token attributes are flat and must follow a complete display token", () => {
diff --git a/packages/semantic-take-adjust/src/activation.ts b/packages/semantic-take-adjust/src/activation.ts
deleted file mode 100644
index add3fc5d..00000000
--- a/packages/semantic-take-adjust/src/activation.ts
+++ /dev/null
@@ -1,22 +0,0 @@
-import { createMarkupSurfaceHostFacet } from "@hypit/markup";
-
-import {
- decodeSemanticTakeAdjustSurface,
- semanticTakeAdjustComponent,
- semanticTakeAdjustManifest,
- semanticTakeAdjustMarkupSurfaces,
- semanticTakeAdjustModuleRef,
-} from "./index.js";
-
-export const hypitPackage = {
- format: "hypit.node-package@1" as const,
- modules: [{ manifest: semanticTakeAdjustManifest }],
- components: [semanticTakeAdjustComponent],
- hostFacets: [createMarkupSurfaceHostFacet({
- module: semanticTakeAdjustModuleRef,
- declaration: semanticTakeAdjustMarkupSurfaces.find((item) => item.name === "semantic-take")!,
- handler: decodeSemanticTakeAdjustSurface,
- })],
-};
-
-export default hypitPackage;
diff --git a/packages/semantic-take-adjust/src/component.ts b/packages/semantic-take-adjust/src/component.ts
deleted file mode 100644
index d175b143..00000000
--- a/packages/semantic-take-adjust/src/component.ts
+++ /dev/null
@@ -1,31 +0,0 @@
-import type { ComponentPackage } from "@hypit/component-kit";
-import { canonicalize } from "@hypit/protocol";
-import type { StoredValue } from "@hypit/protocol";
-import type { SemanticTake } from "@hypit/speech";
-
-import { semanticTakeAdjustProducers } from "./manifest.js";
-import { adjustSemanticTake } from "./program.js";
-import type { SemanticTakeAdjustmentPlan } from "./types.js";
-
-function inline<T>(value: StoredValue | undefined, subject: string): T {
- if (value?.kind !== "inline") throw new Error(`${subject} must be inline.`);
- return value.value as unknown as T;
-}
-
-export const semanticTakeAdjustComponent = {
- producers: [{
- producer: semanticTakeAdjustProducers.adjust,
- handler: ({ inputs }) => ({
- outputs: {
- take: {
- kind: "inline",
- value: canonicalize(adjustSemanticTake(
- inline<SemanticTake>(inputs.source?.value, "SemanticTake"),
- inline<SemanticTakeAdjustmentPlan>(inputs.plan?.value, "SemanticTake adjustment plan"),
- )),
- },
- },
- needs: {},
- }),
- }],
-} satisfies ComponentPackage;
diff --git a/packages/semantic-take-adjust/src/fragment.ts b/packages/semantic-take-adjust/src/fragment.ts
deleted file mode 100644
index 87aa1795..00000000
--- a/packages/semantic-take-adjust/src/fragment.ts
+++ /dev/null
@@ -1,24 +0,0 @@
-import { sealGraphFragment } from "@hypit/elaborator";
-import { speechTypes } from "@hypit/speech";
-
-import { semanticTakeAdjustProducers, semanticTakeAdjustTypes } from "./manifest.js";
-
-const input = (name: string) => ({ kind: "fragment-input" as const, name });
-
-export const semanticTakeAdjustFragment = sealGraphFragment({
- inputs: [
- { name: "source", type: speechTypes.semanticTake },
- { name: "plan", type: semanticTakeAdjustTypes.plan },
- ],
- operations: [{
- id: "adjust",
- producer: semanticTakeAdjustProducers.adjust,
- inputs: { source: input("source"), plan: input("plan") },
- result: { kind: "output", name: "take" },
- }],
- exports: [{
- name: "take",
- type: speechTypes.semanticTake,
- root: { kind: "fragment-operation", operation: "adjust" },
- }],
-});
diff --git a/packages/semantic-take-adjust/src/index.ts b/packages/semantic-take-adjust/src/index.ts
deleted file mode 100644
index 0212647a..00000000
--- a/packages/semantic-take-adjust/src/index.ts
+++ /dev/null
@@ -1,12 +0,0 @@
-export { semanticTakeAdjustComponent } from "./component.js";
-export { semanticTakeAdjustFragment } from "./fragment.js";
-export {
- semanticTakeAdjustManifest,
- semanticTakeAdjustMarkupSurfaces,
- semanticTakeAdjustModuleRef,
- semanticTakeAdjustProducers,
- semanticTakeAdjustTypes,
-} from "./manifest.js";
-export { adjustSemanticTake } from "./program.js";
-export { decodeSemanticTakeAdjustSurface } from "./surface.js";
-export type { SemanticTakeAdjustmentPlan, SemanticTakeAnchorAdjustment } from "./types.js";
diff --git a/packages/semantic-take-adjust/src/manifest.ts b/packages/semantic-take-adjust/src/manifest.ts
deleted file mode 100644
index 897811a7..00000000
--- a/packages/semantic-take-adjust/src/manifest.ts
+++ /dev/null
@@ -1,57 +0,0 @@
-import { narrativeDependency } from "@hypit/narrative";
-import type { ModuleManifest, ProducerRef, TypeRef } from "@hypit/protocol";
-import { speechDependency, speechTypes } from "@hypit/speech";
-
-export const semanticTakeAdjustModuleRef = { name: "@hypit/semantic-take-adjust", version: "1" } as const;
-
-export const semanticTakeAdjustTypes = {
- plan: { module: semanticTakeAdjustModuleRef, name: "SemanticTakeAdjustmentPlan" },
-} satisfies Record<string, TypeRef>;
-
-export const semanticTakeAdjustProducers = {
- adjust: { module: semanticTakeAdjustModuleRef, name: "adjust-semantic-take" },
-} satisfies Record<string, ProducerRef>;
-
-export const semanticTakeAdjustMarkupSurfaces = [{
- name: "semantic-take",
- tag: "SemanticTake",
- mode: "structured",
- outputs: [semanticTakeAdjustTypes.plan, speechTypes.semanticTake],
- vocabulary: {
- summary: "Applies explicit author corrections to measured SemanticTake anchor frames without changing its media or Script identities.",
- attributes: [
- { name: "id", kind: "identifier", required: true,
- summary: "Names the corrected SemanticTake." },
- { name: "source", kind: "reference", required: true, accepts: [speechTypes.semanticTake],
- summary: "Selects the measured SemanticTake being corrected." },
- ],
- ports: [{ name: "take", type: speechTypes.semanticTake,
- summary: "The corrected SemanticTake, addressed as `<id>.take`." }],
- example: `<adjust:SemanticTake id="opening-corrected" source={opening-measured.take}>
- <adjust:Anchor at={story.moment.answer} frame="63"/>
-</adjust:SemanticTake>`,
- notes: [
- "Each Anchor names an author-declared Script Moment and gives its exact Segment-local frame.",
- "This is an explicit correction layer over measured evidence; it does not guess timing or modify media.",
- "Every Token boundary that owns the corrected Anchor is updated together, preserving SemanticTake identity invariants.",
- ],
- },
-}] as const;
-
-export const semanticTakeAdjustManifest: ModuleManifest = {
- format: "hypit.module@1",
- name: semanticTakeAdjustModuleRef.name,
- version: semanticTakeAdjustModuleRef.version,
- dependencies: [narrativeDependency, speechDependency],
- types: [{ name: semanticTakeAdjustTypes.plan.name }],
- capabilities: [],
- producers: [{
- name: semanticTakeAdjustProducers.adjust.name,
- inputs: [
- { name: "source", type: speechTypes.semanticTake },
- { name: "plan", type: semanticTakeAdjustTypes.plan },
- ],
- outputs: [{ name: "take", type: speechTypes.semanticTake }],
- needs: [],
- }],
-};
diff --git a/packages/semantic-take-adjust/src/program.ts b/packages/semantic-take-adjust/src/program.ts
deleted file mode 100644
index 663ca951..00000000
--- a/packages/semantic-take-adjust/src/program.ts
+++ /dev/null
@@ -1,49 +0,0 @@
-import { assertSemanticTakeIdentity, sealSemanticTake } from "@hypit/speech";
-import type { SemanticTake } from "@hypit/speech";
-
-import type { SemanticTakeAdjustmentPlan } from "./types.js";
-
-export function adjustSemanticTake(
- source: SemanticTake,
- plan: SemanticTakeAdjustmentPlan,
-): SemanticTake {
- assertSemanticTakeIdentity(source);
- if (plan.narrativeId !== source.narrativeId) {
- throw new Error(`SemanticTake adjustment belongs to Narrative ${plan.narrativeId}, not ${source.narrativeId}.`);
- }
- if (plan.anchors.length === 0) throw new Error("SemanticTake adjustment requires at least one Anchor.");
-
- const sourceAnchorIds = new Set(source.anchors.map((anchor) => anchor.identity));
- const adjusted = new Map<string, number>();
- for (const anchor of plan.anchors) {
- if (!sourceAnchorIds.has(anchor.anchorId)) {
- throw new Error(`SemanticTake does not contain adjusted Anchor ${anchor.anchorId}.`);
- }
- if (adjusted.has(anchor.anchorId)) {
- throw new Error(`SemanticTake Anchor ${anchor.anchorId} is adjusted more than once.`);
- }
- if (!Number.isSafeInteger(anchor.frame) || anchor.frame < 0 || anchor.frame > source.media.timeline.frameCount) {
- throw new Error(`SemanticTake Anchor ${anchor.anchorId} has an invalid adjusted frame.`);
- }
- adjusted.set(anchor.anchorId, anchor.frame);
- }
-
- const frame = (anchorId: string, fallback: number): number => adjusted.get(anchorId) ?? fallback;
- return sealSemanticTake({
- ...source,
- segment: {
- ...source.segment,
- startFrame: frame(source.segment.startAnchorId, source.segment.startFrame),
- endFrameExclusive: frame(source.segment.endAnchorId, source.segment.endFrameExclusive),
- },
- anchors: source.anchors.map((anchor) => ({
- ...anchor,
- frame: frame(anchor.identity, anchor.frame),
- })),
- tokens: source.tokens.map((token) => ({
- ...token,
- startFrame: frame(token.startAnchorId, token.startFrame),
- endFrameExclusive: frame(token.endAnchorId, token.endFrameExclusive),
- })),
- });
-}
diff --git a/packages/semantic-take-adjust/src/types.ts b/packages/semantic-take-adjust/src/types.ts
deleted file mode 100644
index e74625f3..00000000
--- a/packages/semantic-take-adjust/src/types.ts
+++ /dev/null
@@ -1,9 +0,0 @@
-export type SemanticTakeAnchorAdjustment = {
- readonly anchorId: string;
- readonly frame: number;
-};
-
-export type SemanticTakeAdjustmentPlan = {
- readonly narrativeId: string;
- readonly anchors: readonly SemanticTakeAnchorAdjustment[];
-};
diff --git a/packages/semantic-take-adjust/test/semantic-take-adjust.test.ts b/packages/semantic-take-adjust/test/semantic-take-adjust.test.ts
deleted file mode 100644
index 12b14d9a..00000000
--- a/packages/semantic-take-adjust/test/semantic-take-adjust.test.ts
+++ /dev/null
@@ -1,51 +0,0 @@
-import assert from "node:assert/strict";
-import test from "node:test";
-
-import { adjustSemanticTake } from "../src/program.js";
-import type { SemanticTake } from "@hypit/speech";
-
-const source = {
- narrativeId: "story",
- media: {
- timeline: { frameRate: { numerator: 30, denominator: 1 }, frameCount: 100 },
- visual: {
- artifact: { kind: "blob", resource: "res_semantic-take-adjust", size: 1, mediaType: "video/mp4" },
- width: 720,
- height: 1280,
- },
- },
- segment: {
- segmentId: "opening",
- startAnchorId: "opening:start",
- endAnchorId: "opening:end",
- startFrame: 0,
- endFrameExclusive: 100,
- },
- tokens: [{
- tokenId: "answer",
- segmentId: "opening",
- text: "Ajá",
- startAnchorId: "answer:start",
- endAnchorId: "answer:end",
- startFrame: 58,
- endFrameExclusive: 85,
- }],
- anchors: [
- { identity: "opening:start", frame: 0 },
- { identity: "answer:start", frame: 58 },
- { identity: "answer:end", frame: 85 },
- { identity: "opening:end", frame: 100 },
- ],
-} satisfies SemanticTake;
-
-test("adjusts an authored semantic anchor without changing media", () => {
- const adjusted = adjustSemanticTake(source, {
- narrativeId: "story",
- anchors: [{ anchorId: "answer:start", frame: 63 }],
- });
-
- assert.equal(adjusted.tokens[0]?.startFrame, 63);
- assert.equal(adjusted.tokens[0]?.endFrameExclusive, 85);
- assert.equal(adjusted.anchors.find((anchor) => anchor.identity === "answer:start")?.frame, 63);
- assert.deepEqual(adjusted.media, source.media);
-});
diff --git a/packages/sound-studio/README.md b/packages/sound-studio/README.md
deleted file mode 100644
index 718597bb..00000000
--- a/packages/sound-studio/README.md
+++ /dev/null
@@ -1,22 +0,0 @@
-# Sound Studio Companion
-
-Sound contributes one Track with content and a bottom Uses band through the public Companion interface:
-
-- The content lane shows placed audio Takes with waveforms. Each Take retains its actual interval, including gaps and overlaps. Picture-only Takes contribute no sound item.
-- The Uses label band shows each authored Style application. Later declarations appear over earlier ones; selection raises an item for editing without changing that priority. Silent and fully covered Uses remain selectable.
-
-One Sound label spans the waveform content and Uses band. Selecting a Take shows its Segment and placed frame range.
-Selecting a Use shows its Style and resolved frame range, alongside the ordinary Style's authored
-`gain` and `end-gain` parameters. Gain is displayed as a percentage: 100% writes the linear value 1.
-The end gain defaults to the start gain. The parameter Companion exposes this dependent default;
-the first edit inserts an explicit attribute into the Style.
-
-The fields live in When and How. Shared Style edits affect all Uses selecting that Style.
-Temporal gestures follow the existing Selection/Moment/clock projection and exact source endpoint
-rules. Project Styles expose their own parameters through `createStudioCompanionHostFacet({ parameters })`,
-matching their own Module and Surface. The Track opts `style` into this owner with `companion: true`.
-
-`Sound Track.program` exports the already-computed ordered Use set before presentation coverage
-is resolved. `Sound Track.audio` exports the effective audio arrangement. The Companion reads the
-former to preserve editing choices even when they currently produce no sound; rendering consumes
-the latter. Studio does not reconstruct the rule set from audible output or inspect Sound internals.
diff --git a/packages/sound-studio/package.json b/packages/sound-studio/package.json
deleted file mode 100644
index e81518a1..00000000
--- a/packages/sound-studio/package.json
+++ /dev/null
@@ -1,20 +0,0 @@
-{
- "name": "@hypit/sound-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/timeline": "workspace:*",
- "@hypit/temporal": "workspace:*",
- "@hypit/composition": "workspace:*",
- "@hypit/studio-adapter": "workspace:*",
- "@hypit/sound": "workspace:*"
- }
-}
diff --git a/packages/sound-studio/src/activation.ts b/packages/sound-studio/src/activation.ts
deleted file mode 100644
index 105d10a8..00000000
--- a/packages/sound-studio/src/activation.ts
+++ /dev/null
@@ -1,6 +0,0 @@
-import { createStudioCompanionHostFacet } from "@hypit/studio-adapter";
-import { soundStudioTrackCompanions, soundStudioParameterCompanions } from "./index.js";
-export default {
- format: "hypit.node-package@1" as const,
- hostFacets: [createStudioCompanionHostFacet({ tracks: soundStudioTrackCompanions, parameters: soundStudioParameterCompanions })],
-};
diff --git a/packages/sound-studio/src/index.ts b/packages/sound-studio/src/index.ts
deleted file mode 100644
index 1674e12c..00000000
--- a/packages/sound-studio/src/index.ts
+++ /dev/null
@@ -1,74 +0,0 @@
-import { soundModuleRef } from "@hypit/sound";
-import type { SoundSet } from "@hypit/sound";
-import { projectTimelineMedia, timelineTypes } from "@hypit/timeline";
-import type { Timeline } from "@hypit/timeline";
-import { temporalTypes } from "@hypit/temporal";
-import { compositionTypes } from "@hypit/composition";
-import { artifactPreview, authoredChildFor, previewLayer, requiredReferencedValue, requiredSurfaceValue, temporalLineageFor, temporalSemanticSource } from "@hypit/studio-adapter";
-import type { StudioTrackCompanion, StudioTrackCompanionContext, StudioEntityDraft } from "@hypit/studio-adapter";
-
-export function projectSound(context: StudioTrackCompanionContext): readonly StudioEntityDraft[] {
- const timeline = requiredReferencedValue(context, "timeline", timelineTypes.track) as Timeline;
- const program = requiredSurfaceValue(context, "program") as SoundSet;
- // Source content keeps its own placement. A Use changes its presentation, not its media clock.
- const content: StudioEntityDraft[] = projectTimelineMedia(timeline).flatMap((clip, index) => {
- if (clip.media.audio === undefined) return [];
- return [{
- id: `${context.track.outputRef}:content:${clip.segmentId}`,
- authoredId: clip.segmentId,
- display: { title: clip.segmentId, layers: [previewLayer(artifactPreview("audio", clip.media.audio.artifact.resource), "waveform")] },
- ...clip.span, stackOrder: index,
- inspector: [
- { id: "segment", label: "Segment", domain: "how", section: { id: "content", label: "Content" }, value: clip.segmentId },
- { id: "range", label: "Range", domain: "when", section: { id: "placement", label: "Placement" }, value: `${clip.span.startFrame}–${clip.span.endFrameExclusive}`, unit: "f", summary: "Placed interval; the end frame is exclusive." },
- ],
- presentation: { entity: "sound-content", chrome: "standard" },
- }];
- });
- const uses: StudioEntityDraft[] = program.uses.map((use, index) => {
- const authoredId = use.window.subjectId;
- const child = authoredChildFor(context, authoredId, [temporalTypes.windowSpec]);
- if (child === undefined) throw new Error(`Sound Use ${authoredId} has no author provenance.`);
- const style = child.referenceAttributes.style;
- const temporal = temporalLineageFor(context, authoredId, "window");
- const semantic = temporalSemanticSource(temporal);
- return {
- id: `${context.track.outputRef}:use:${authoredId}`, authoredId,
- display: { title: style ?? authoredId, layers: [] },
- ...use.window.span, stackOrder: index,
- elementRange: child.range,
- ...(temporal === undefined ? {} : { temporal }),
- ...(semantic === undefined ? {} : { markerId: semantic.id }),
- presentation: { entity: "sound-use", chrome: "standard" },
- band: "uses",
- inspector: [{ id: "range", label: "Range", domain: "when", section: { id: "placement", label: "Placement" }, value: `${use.window.span.startFrame}–${use.window.span.endFrameExclusive}`, unit: "f", summary: "Resolved Use interval; the end frame is exclusive. Timeline gestures follow this Use's author timing." }],
- };
- });
- return [...content, ...uses];
-}
-
-export const soundStudioTrackCompanions: readonly StudioTrackCompanion[] = [{
- id: "audio", role: "track",
- output: { type: compositionTypes.audioTrack, surface: "track", modules: [soundModuleRef] },
- family: "sound", label: "Sound", tone: "green", icon: "waveform",
- lane: { heightPx: 48 },
- requiredValues: ["program"],
- bands: [{
- id: "uses", placement: "after", heightPx: 15, display: "label",
- bindings: [{ name: "style", companion: true }],
- inspector: [{ binding: "style", label: "Style", domain: "how", section: { id: "sound", label: "Sound" }, control: "text", summary: "This Style is shared by every Use that selects it." }],
- }],
- project: projectSound,
-}];
-
-export const soundStudioParameterCompanions: readonly import("@hypit/studio-adapter").StudioParameterCompanion[] = [{
- id: "style", match: { module: soundModuleRef, surface: "style" },
- bindings: [ { name: "gain", writable: true, fallback: 1 },
- { name: "end-gain", writable: true, fallback: authored => Number(authored.gain ?? 1) } ],
- inspector: (["gain", "end-gain"] as const).map(name => ({
- binding: name, label: name === "gain" ? "Gain" : "End Gain", domain: "how",
- section: { id: "sound", label: "Sound" }, control: "number", unit: "%",
- number: { scale: 100, minimum: 0, maximum: 6400, step: 1 },
- summary: name === "gain" ? "Linear gain at the start of each Use. 100% preserves the source level." : "Linear gain at the end of each Use. The Use interval owns the ramp.",
- })),
-}];
diff --git a/packages/sound-studio/test/companion.test.ts b/packages/sound-studio/test/companion.test.ts
deleted file mode 100644
index fbc29342..00000000
--- a/packages/sound-studio/test/companion.test.ts
+++ /dev/null
@@ -1,47 +0,0 @@
-import assert from "node:assert/strict";
-import test from "node:test";
-import { sealAudioTrack } from "@hypit/composition";
-import { temporalTypes } from "@hypit/temporal";
-import { timelineTypes } from "@hypit/timeline";
-import type { StudioTrackCompanionContext } from "@hypit/studio-adapter";
-import { projectSound } from "../src/index.js";
-import { timelineFixture } from "../../../test/timeline-fixture.js";
-import { projectProgramWindow } from "../../../test/temporal-fixture.js";
-
-const base = timelineFixture({ id: "film", durationSec: 6, frameRate: { numerator: 30, denominator: 1 } }, {
- segments: [{id:"first",frameCount:90},{id:"second",frameCount:90}],
-});
-function context(audio: boolean): StudioTrackCompanionContext {
- const timeline = {...base, items: base.items.map((item,index)=>({...item,startFrame:index ? 60:15,take:{...item.take,
- media: audio ? item.take.media : {timeline:item.take.media.timeline,visual:{artifact:{kind:"blob",resource:`res_picture${index}`,mediaType:"video/mp4",size:1},width:64,height:64}},
- }}))};
- const program = {uses:["base","override","hidden"].map(id=>({
- window:projectProgramWindow({itemId:id,semantic:base,projection:{start:{ref:"absolute",at:{unit:"frames",value:0}},end:{ref:"absolute",at:{unit:"frames",value:180}}}}),
- audio:sealAudioTrack({id,programSpaceId:base.id,clips:[]}),
- }))};
- return {
- track:{outputRef:"p.audio",trace:{references:[{input:"timeline",typeRef:timelineTypes.track,ref:"film"}],outputPorts:[{name:"program",ref:"p.program"}]}},
- placement:{children:program.uses.map((use,index)=>({range:{start:index*10,end:index*10+5},referenceAttributes:{style:`styles.${use.window.subjectId}`},values:[{type:temporalTypes.windowSpec,value:{id:use.window.subjectId}}]}))},
- values:new Map<string,unknown>([["film",timeline],["p.program",program]]),spans:[],temporalBindings:[],
- } as unknown as StudioTrackCompanionContext;
-}
-
-test("Use band keeps fully overridden and silent rules with exact child and Style ownership",()=>{
- const uses=projectSound(context(false));
- assert.deepEqual(uses.map(use=>[use.display.title,use.band,use.elementRange]),[
- ["styles.base","uses",{start:0,end:5}],
- ["styles.override","uses",{start:10,end:15}],
- ["styles.hidden","uses",{start:20,end:25}],
- ]);
- assert.ok(uses.every(use=>use.presentation?.chrome==="standard"));
- assert.ok(uses.every(use=>use.inspector?.[0]?.value === "0–180"));
-});
-
-test("content follows audio-only Takes including gaps and overlaps; picture-only contributes no sound",()=>{
- const content=projectSound(context(true)).filter(entity=>entity.band===undefined);
- assert.deepEqual(content.map(entity=>[entity.authoredId,entity.startFrame,entity.endFrameExclusive]),[
- ["first",15,105],["second",60,150],
- ]);
- assert.deepEqual(content[0]?.inspector?.map(field=>field.value), ["first", "15–105"]);
- assert.equal(projectSound(context(false)).filter(entity=>entity.band===undefined).length,0);
-});
diff --git a/packages/sound/README.md b/packages/sound/README.md
deleted file mode 100644
index 6611aaa1..00000000
--- a/packages/sound/README.md
+++ /dev/null
@@ -1,81 +0,0 @@
-# Sound
-
-Sound presents audio already placed on a Timeline. Audio Track takes independent material such as
-music and effects. Sound obtains existing sources and playback positions from Timeline and chooses
-how they are heard. Visual Performance and Caption remain independent presentations.
-
-```svml
-<import as="sound" from="@hypit/sound@1"/>
-<sound:Style id="normal"/>
-<sound:Style id="fade-in" gain="0" end-gain="1"/>
-<sound:Style id="silent" gain="0"/>
-<sound:Track id="voice" timeline={program.timeline}>
- <sound:Use style={normal}/>
- <sound:Use at="0f" for="2s" style={fade-in}/>
- <sound:Use during={story.selection.demonstration} style={silent}/>
-</sound:Track>
-```
-
-Include `voice.audio` in Film to hear this presentation. Timeline exports `.timeline`, retaining
-the material for consumers; Sound selects and presents its audio explicitly.
-
-Sound also exports `.program`: the ordered Use windows and their audio presentations before
-coverage is resolved. The Studio Companion consumes this value to keep silent and covered Uses
-available for editing. `.audio` remains the effective arrangement for Film.
-
-## Two separate choices
-
-The last declared matching Use selects the complete presentation locally. No selector means the
-whole Timeline. No matching Use contributes no sound; an empty winning Style remains silent.
-Later Uses can restore sound inside an earlier silent interval. Separate Sound Tracks can coexist.
-
-Within the ordinary Style, the last Timeline-declared active source with audio wins. Declaration
-order is independent of start-time order. A video-only Take supplies no sound candidate; a recorded
-silent audio source is still a source. Gaps and zero-Take Timelines have no sound to present. When a
-later source ends, an earlier still-active source resumes at its current source position.
-
-`gain` and `end-gain` are linear amplitude multipliers from 0 to 64. `gain` defaults to 1 and
-`end-gain` defaults to `gain`. They describe a linear ramp over the original Use Window. Equal values
-produce constant gain; zero produces silence. Changing the Window changes the ramp duration.
-The interval's right endpoint describes the gain reached at the boundary, while sample coverage is
-half-open. Matching adjacent Style endpoints is an authoring choice.
-
-## Time and continuity
-
-Use accepts shared `during`, `at` + `for`, `until` + `for`, and `start` + `end`, including independently
-bound `start-source` / `end-source`. A source role and a time endpoint are distinct inputs.
-
-A Use starting at program second 7 does not restart a Take placed at second 5: its sound is already
-at source second 2. A partially overridden Use keeps its original gain-ramp progress. Resolution
-intersects audible subranges and preserves original Clip targets, sampling and envelopes. The same
-holds for a partial audio render. Sound does not move Takes, change words or retime semantic anchors.
-
-## Write a project Style
-
-The public TypeScript entry is `@hypit/hypit/sound`.
-`soundStyle(fragment, bindings)` creates an authored Style. Its fragment takes `timeline` and
-`window`, plus explicitly bound family inputs, and exports `audio: AudioTrack`. Bound references
-become ordinary graph edges at each Use. The fragment may produce an empty Track, one source or
-multiple sources; the renderer consumes the resulting ordinary AudioTrack.
-
-`ordinarySound(timeline, window, { gain, endGain })` supplies ordinary last-source presentation.
-`sourceSound(timeline, window, segment, { gain, endGain })` selects one explicit Narrative Segment,
-retaining its existing source and target positions. A known Segment without audio returns an empty
-Track; a foreign or unknown Segment is an error. Neither helper invents sound outside source coverage.
-A family can publish richer program-sample `gainEnvelope` points through the common AudioClip data.
-
-The [project crossfade example](../../examples/semantic-composition/packages/sound-styles/README.md)
-binds `outgoing` and `incoming` independently. Its two gains move in opposite directions across the
-Use Window. There is no transition-mode registry or automatic source pairing. Other families can
-own different curves or source combinations through the same fragment interface.
-
-## Rendering boundary
-
-[Composition](../composition/README.md) owns generic AudioClip presentation fields: optional
-`gainEnvelope` points and `audibility` subranges, both on the complete 48 kHz program clock. Sound
-resolves Uses into those values. The media pipeline preserves them; the execution package applies
-them per sample after source playback and existing fades, before render-range cropping.
-
-The [Sound Companion](../sound-studio/README.md) presents placed audio content and authored Uses.
-Studio playback consumes the same gain envelopes, audible regions and fades through its generic
-AudioTrack player.
diff --git a/packages/sound/src/activation.ts b/packages/sound/src/activation.ts
deleted file mode 100644
index 3c8f57b8..00000000
--- a/packages/sound/src/activation.ts
+++ /dev/null
@@ -1,11 +0,0 @@
-import { createMarkupSurfaceHostFacet } from "@hypit/markup";
-import { soundManifest, soundModuleRef, soundMarkupSurfaces } from "./manifest.js";
-import { soundComponent } from "./component.js";
-import { decodeSoundStyleSurface, decodeSoundTrackSurface } from "./surface.js";
-export const hypitPackage = {
- format: "hypit.node-package@1" as const,
- modules: [{ manifest: soundManifest }], components: [soundComponent],
- hostFacets: soundMarkupSurfaces.map(declaration => createMarkupSurfaceHostFacet({ module: soundModuleRef, declaration,
- handler: declaration.name === "style" ? decodeSoundStyleSurface : decodeSoundTrackSurface })),
-};
-export default hypitPackage;
diff --git a/packages/sound/src/component.ts b/packages/sound/src/component.ts
deleted file mode 100644
index 88d2ae2d..00000000
--- a/packages/sound/src/component.ts
+++ /dev/null
@@ -1,28 +0,0 @@
-import { canonicalize } from "@hypit/protocol";
-import type { StoredValue } from "@hypit/protocol";
-import type { ComponentPackage } from "@hypit/component-kit";
-import type { Timeline } from "@hypit/timeline";
-import type { AudioTrack } from "@hypit/composition";
-import type { TemporalWindow } from "@hypit/temporal";
-import { ordinarySound, appendSoundUse, resolveSound } from "./program.js";
-import type { SoundSet, SoundGain } from "./program.js";
-import { soundProducers } from "./manifest.js";
-function inline<T>(value: StoredValue | undefined): T {
- if (value?.kind !== "inline") throw new Error("Sound input must be inline.");
- return value.value as unknown as T;
-}
-const output = (value: unknown) => ({ kind: "inline" as const, value: canonicalize(value) });
-export const soundComponent: ComponentPackage = {
- producers: [
- { producer: soundProducers.create, handler: () => ({ outputs: { set: output({ uses: [] }) }, needs: {} }) },
- { producer: soundProducers.append, handler: ({ inputs }) => ({ outputs: { set: output(appendSoundUse(
- inline<SoundSet>(inputs.set?.value), inline<TemporalWindow>(inputs.window?.value), inline<AudioTrack>(inputs.audio?.value),
- )) }, needs: {} }) },
- { producer: soundProducers.resolve, handler: ({ inputs }) => ({ outputs: { audio: output(resolveSound(
- inline<Timeline>(inputs.timeline?.value), inline<{ id: string }>(inputs.header?.value).id, inline<SoundSet>(inputs.set?.value),
- )) }, needs: {} }) },
- { producer: soundProducers.ordinary, handler: ({ inputs }) => ({ outputs: { audio: output(ordinarySound(
- inline<Timeline>(inputs.timeline?.value), inline<TemporalWindow>(inputs.window?.value), inline<SoundGain>(inputs.spec?.value),
- )) }, needs: {} }) },
- ],
-};
diff --git a/packages/sound/src/index.ts b/packages/sound/src/index.ts
deleted file mode 100644
index cf2c580a..00000000
--- a/packages/sound/src/index.ts
+++ /dev/null
@@ -1,5 +0,0 @@
-export * from "./style.js";
-export * from "./program.js";
-export * from "./component.js";
-export * from "./surface.js";
-export * from "./manifest.js";
diff --git a/packages/sound/src/manifest.ts b/packages/sound/src/manifest.ts
deleted file mode 100644
index 5bc01760..00000000
--- a/packages/sound/src/manifest.ts
+++ /dev/null
@@ -1,47 +0,0 @@
-import { compositionDependency, compositionTypes } from "@hypit/composition";
-import { timelineDependency, timelineTypes } from "@hypit/timeline";
-import { temporalDependency, temporalTypes } from "@hypit/temporal";
-import { temporalWindowAttributeVocabulary } from "@hypit/temporal-markup";
-import type { ModuleManifest, ProducerRef, TypeRef } from "@hypit/protocol";
-
-export const soundModuleRef = { name: "@hypit/sound", version: "1" } as const;
-export const soundTypes = Object.fromEntries(["Style", "Set", "Header", "Gain"].map(name => [name.toLowerCase(), { module: soundModuleRef, name: `Sound${name}` }])) as Record<"style" | "set" | "header" | "gain", TypeRef>;
-export const soundProducers = Object.fromEntries(["create", "append", "resolve", "ordinary"].map(name => [name, { module: soundModuleRef, name }])) as Record<"create" | "append" | "resolve" | "ordinary", ProducerRef>;
-export const ordinaryInputs = [
- { name: "timeline", type: timelineTypes.track }, { name: "window", type: temporalTypes.window },
- { name: "spec", type: soundTypes.gain },
-];
-export const soundManifest: ModuleManifest = {
- format: "hypit.module@1", ...soundModuleRef,
- dependencies: [compositionDependency, timelineDependency, temporalDependency],
- types: Object.values(soundTypes).map(type => ({ name: type.name })), capabilities: [],
- producers: [
- { name: "create", inputs: [], outputs: [{ name: "set", type: soundTypes.set }], needs: [] },
- { name: "append", inputs: [{ name: "set", type: soundTypes.set }, { name: "window", type: temporalTypes.window }, { name: "audio", type: compositionTypes.audioTrack }], outputs: [{ name: "set", type: soundTypes.set }], needs: [] },
- { name: "resolve", inputs: [{ name: "set", type: soundTypes.set }, { name: "timeline", type: timelineTypes.track }, { name: "header", type: soundTypes.header }], outputs: [{ name: "audio", type: compositionTypes.audioTrack }], needs: [] },
- { name: "ordinary", inputs: ordinaryInputs, outputs: [{ name: "audio", type: compositionTypes.audioTrack }], needs: [] },
- ],
-};
-export const soundMarkupSurfaces = [
- { name: "style", tag: "Style", mode: "structured", outputs: [soundTypes.style, soundTypes.gain], vocabulary: {
- summary: "Presents existing Timeline sound, choosing the last declared active audio source. Gain may change linearly across each Use.",
- example: `<sound:Style id="fade-in" gain="0" end-gain="1"/>`,
- attributes: [
- { name: "id", kind: "identifier", required: true, summary: "Style name." },
- { name: "gain", kind: "literal", required: false, summary: "Linear gain at the beginning of a Use; defaults to 1. Zero silences the presentation." },
- { name: "end-gain", kind: "literal", required: false, summary: "Linear gain at the end of a Use; defaults to gain. The original Use interval owns the ramp." },
- ],
- } },
- { name: "track", tag: "Track", mode: "structured", outputs: [compositionTypes.audioTrack, soundTypes.set, soundTypes.header, temporalTypes.instantSpec, temporalTypes.windowSpec, temporalTypes.instant, temporalTypes.window], vocabulary: {
- summary: "Presents Timeline sound through ordered Uses. Later Uses replace earlier presentation locally without restarting source playback or gain curves.",
- example: `<sound:Track id="voice" timeline={program.timeline}><sound:Use style={normal}/><sound:Use at="0f" for="2s" style={fade-in}/></sound:Track>`,
- attributes: [
- { name: "id", kind: "identifier", required: true, summary: "Sound presentation name." },
- { name: "timeline", kind: "reference", required: true, accepts: [timelineTypes.track], summary: "Complete film time and placed sources." },
- ], children: [{ tag: "Use", cardinality: "many", summary: "Last matching Use wins, including silence. No time selector covers the complete Timeline.", attributes: [
- { name: "id", kind: "identifier", required: false, summary: "Optional occurrence identity." },
- { name: "style", kind: "reference", required: true, accepts: [soundTypes.style], summary: "Ordinary or project-authored sound Style. Explicit source bindings belong to the Style." },
- ...temporalWindowAttributeVocabulary,
- ] }],
- } },
-] as const;
diff --git a/packages/sound/src/program.ts b/packages/sound/src/program.ts
deleted file mode 100644
index 8195b3aa..00000000
--- a/packages/sound/src/program.ts
+++ /dev/null
@@ -1,84 +0,0 @@
-import { sealAudioTrack, assertAudioTrackIdentity } from "@hypit/composition";
-import type { AudioTrack, AudioClip, AudioSampleSpan, AudioGainPoint } from "@hypit/composition";
-import { assertTemporalWindowFor } from "@hypit/temporal";
-import type { TemporalWindow } from "@hypit/temporal";
-import { projectTimelineAudio } from "@hypit/timeline";
-import type { Timeline } from "@hypit/timeline";
-import type { NarrativeExcerpt } from "@hypit/narrative";
-import { programFrameSampleBoundary } from "@hypit/program-space";
-
-export type SoundUse = { readonly window: TemporalWindow; readonly audio: AudioTrack };
-export type SoundSet = { readonly uses: readonly SoundUse[] };
-export type SoundGain = { readonly gain: number; readonly endGain: number };
-
-export function soundWindow(timeline: Timeline, window: TemporalWindow): AudioSampleSpan {
- assertTemporalWindowFor(window, { subjectId: window.subjectId, space: timeline });
- return { startSample: programFrameSampleBoundary(timeline, window.span.startFrame, 48000),
- endSampleExclusive: programFrameSampleBoundary(timeline, window.span.endFrameExclusive, 48000) };
-}
-export function intersectAudioSpans(left: readonly AudioSampleSpan[], right: readonly AudioSampleSpan[]): AudioSampleSpan[] {
- return left.flatMap(a => right.flatMap(b => {
- const startSample = Math.max(a.startSample, b.startSample), endSampleExclusive = Math.min(a.endSampleExclusive, b.endSampleExclusive);
- return endSampleExclusive > startSample ? [{ startSample, endSampleExclusive }] : [];
- }));
-}
-function subtract(spans: readonly AudioSampleSpan[], cut: AudioSampleSpan): AudioSampleSpan[] {
- return spans.flatMap(span => {
- if (cut.endSampleExclusive <= span.startSample || cut.startSample >= span.endSampleExclusive) return [span];
- return [
- ...(cut.startSample > span.startSample ? [{ startSample: span.startSample, endSampleExclusive: cut.startSample }] : []),
- ...(cut.endSampleExclusive < span.endSampleExclusive ? [{ startSample: cut.endSampleExclusive, endSampleExclusive: span.endSampleExclusive }] : []),
- ];
- });
-}
-function envelope(span: AudioSampleSpan, gain: SoundGain): readonly AudioGainPoint[] {
- if (![gain.gain, gain.endGain].every(value => Number.isFinite(value) && value >= 0 && value <= 64)) throw new Error("Sound gain must be from 0 to 64.");
- return [{ sample: span.startSample, gain: gain.gain }, { sample: span.endSampleExclusive, gain: gain.endGain }];
-}
-const unity = { gain: 1, endGain: 1 };
-
-/** Default source choice is declaration order, independently of the order of Use rules. */
-export function ordinarySound(timeline: Timeline, window: TemporalWindow, gain: SoundGain = unity): AudioTrack {
- const span = soundWindow(timeline, window), gainEnvelope = envelope(span, gain);
- const sources = new Map(projectTimelineAudio(timeline).clips.map(clip => [clip.id, clip]));
- const clips = timeline.items.flatMap(item => { const clip = sources.get(item.take.segment.segmentId); return clip ? [clip] : []; });
- const result: AudioClip[] = [];
- for (const [index, clip] of clips.entries()) {
- let audibility = intersectAudioSpans([span], [clip.target]);
- for (const later of clips.slice(index + 1)) audibility = subtract(audibility, later.target);
- if (audibility.length && (gain.gain !== 0 || gain.endGain !== 0)) result.push({ ...clip, gainEnvelope, audibility });
- }
- return sealAudioTrack({ id: window.subjectId, programSpaceId: timeline.id, clips: result });
-}
-
-/** Explicit source selection for project Styles, with its original placement/sampling retained. */
-export function sourceSound(timeline: Timeline, window: TemporalWindow, segment: NarrativeExcerpt, gain: SoundGain = unity): AudioTrack {
- if (segment.kind !== "segment" || segment.narrativeId !== timeline.narrativeId) throw new Error("Sound source must be a Segment of this Timeline's Narrative.");
- if (!timeline.items.some(item => item.take.segment.segmentId === segment.id)) throw new Error(`Unknown Sound Segment ${segment.id}.`);
- const span = soundWindow(timeline, window), gainEnvelope = envelope(span, gain);
- const clip = projectTimelineAudio(timeline).clips.find(clip => clip.id === segment.id);
- const audibility = clip ? intersectAudioSpans([span], [clip.target]) : [];
- return sealAudioTrack({ id: `${window.subjectId}:${segment.id}`, programSpaceId: timeline.id,
- clips: clip && audibility.length && (gain.gain !== 0 || gain.endGain !== 0) ? [{ ...clip, gainEnvelope, audibility }] : [] });
-}
-export function appendSoundUse(set: SoundSet, window: TemporalWindow, audio: AudioTrack): SoundSet {
- assertAudioTrackIdentity(audio);
- if (audio.programSpaceId !== window.start.source.spaceId) throw new Error("Sound Use and audio belong to different Timelines.");
- return { uses: [...set.uses, { window, audio }] };
-}
-/** Resolve presentation coverage without changing original targets, source clocks or envelopes. */
-export function resolveSound(timeline: Timeline, id: string, set: SoundSet): AudioTrack {
- const windows = set.uses.map(use => { assertAudioTrackIdentity(use.audio, timeline); return soundWindow(timeline, use.window); });
- const clips: AudioClip[] = [];
- for (const [index, use] of set.uses.entries()) {
- let active = [windows[index]!];
- for (const cut of windows.slice(index + 1)) active = subtract(active, cut);
- for (const clip of use.audio.clips) {
- const audibility = intersectAudioSpans(active, clip.audibility ?? [clip.target]);
- if (audibility.length) clips.push({ ...clip, id: `${index + 1}:${clip.id}`, audibility });
- }
- }
- const result = sealAudioTrack({ id, programSpaceId: timeline.id, clips });
- assertAudioTrackIdentity(result, timeline);
- return result;
-}
diff --git a/packages/sound/src/style.ts b/packages/sound/src/style.ts
deleted file mode 100644
index ea14991c..00000000
--- a/packages/sound/src/style.ts
+++ /dev/null
@@ -1,34 +0,0 @@
-import { sealGraphFragment } from "@hypit/elaborator";
-import type { GraphFragment } from "@hypit/elaborator";
-import { compositionTypes } from "@hypit/composition";
-import { timelineTypes } from "@hypit/timeline";
-import { temporalTypes } from "@hypit/temporal";
-import { sameType } from "@hypit/protocol";
-import type { SurfaceResolvedReference } from "@hypit/markup";
-
-/** Author-time closure: bound references become ordinary graph edges at each Use. */
-export type SoundStyle = {
- readonly fragment: GraphFragment;
- readonly bindings: Readonly<Record<string, { readonly type: SurfaceResolvedReference["type"]; readonly ref: SurfaceResolvedReference["ref"] }>>;
-};
-export function soundStyle(fragment: GraphFragment, bindings: SoundStyle["bindings"] = {}): SoundStyle {
- fragment = sealGraphFragment(fragment);
- const common = { timeline: timelineTypes.track, window: temporalTypes.window };
- for (const [name, type] of Object.entries(common)) {
- const port = fragment.inputs.find(port => port.name === name);
- if (port === undefined || !sameType(port.type, type)) throw new Error(`Sound Style requires ${name} input.`);
- if (bindings[name] !== undefined) throw new Error(`Sound supplies ${name} at each Use.`);
- }
- for (const port of fragment.inputs) {
- if (port.name in common) continue;
- const binding = bindings[port.name];
- if (binding === undefined || !sameType(port.type, binding.type)) throw new Error(`Sound Style binding ${port.name} has the wrong Type.`);
- }
- for (const name of Object.keys(bindings)) {
- if (!fragment.inputs.some(port => port.name === name)) throw new Error(`Sound Style has unknown binding ${name}.`);
- }
- if (fragment.exports.length !== 1 || fragment.exports[0]?.name !== "audio" || !sameType(fragment.exports[0].type, compositionTypes.audioTrack)) {
- throw new Error("Sound Style must export audio: AudioTrack.");
- }
- return { fragment, bindings: Object.fromEntries(Object.entries(bindings).map(([name, value]) => [name, { ref: value.ref, type: value.type }])) };
-}
diff --git a/packages/sound/src/surface.ts b/packages/sound/src/surface.ts
deleted file mode 100644
index e09d4134..00000000
--- a/packages/sound/src/surface.ts
+++ /dev/null
@@ -1,90 +0,0 @@
-import { assertAttributes, assertEmptyElement, textAttribute, optionalTextAttribute } from "@hypit/markup";
-import type { StructuredSurfaceHandler, SurfaceResolvedReference, SurfaceRecordDraft, SurfaceComponentDraft, StructuredElement } from "@hypit/markup";
-import { canonicalize, sameType } from "@hypit/protocol";
-import type { TypeRef } from "@hypit/protocol";
-import { sealGraphFragment } from "@hypit/elaborator";
-import type { FragmentOperation } from "@hypit/elaborator";
-import { createTemporalWindowProjection, resolveTemporalContext, temporalWindowAttributeNames } from "@hypit/temporal-markup";
-import { temporalTypes } from "@hypit/temporal";
-import { compositionTypes } from "@hypit/composition";
-import { timelineTypes } from "@hypit/timeline";
-import { soundStyle } from "./style.js";
-import type { SoundStyle } from "./style.js";
-import { soundTypes, soundProducers, ordinaryInputs } from "./manifest.js";
-
-const input = (name: string) => ({ kind: "fragment-input" as const, name });
-const operation = (id: string) => ({ kind: "fragment-operation" as const, operation: id });
-function reference(element: StructuredElement, name: string, type: TypeRef, resolve: (path: string) => SurfaceResolvedReference | undefined): SurfaceResolvedReference {
- const raw = element.attributes[name];
- if (typeof raw !== "object" || raw.kind !== "reference") throw new Error(`${element.name}.${name} must be a reference.`);
- const found = resolve(raw.path);
- if (found === undefined || !sameType(found.type, type)) throw new Error(`${element.name}.${name} has the wrong Type.`);
- return found;
-}
-function authored<T>(value: SurfaceResolvedReference): T {
- if (value.record?.value.kind !== "inline") throw new Error("A presentation Style or Recipe must be an authored inline value.");
- return value.record.value.value as unknown as T;
-}
-export const decodeSoundTrackSurface: StructuredSurfaceHandler = ({ element, resolveReference }) => {
- assertAttributes(element, ["id", "timeline"]);
- const id = textAttribute(element, "id"), context = resolveTemporalContext({ element, resolveReference });
- const records: SurfaceRecordDraft[] = [{ id: `${id}.header`, type: soundTypes.header, value: { kind: "inline", value: { id } }, range: element.range }];
- const components: SurfaceComponentDraft[] = [];
- const fragments = [] as ReturnType<typeof sealGraphFragment>[];
- const collectorInputs = [{ name: "timeline", type: timelineTypes.track }, { name: "header", type: soundTypes.header }];
- const bindings: Record<string, SurfaceResolvedReference["ref"]> = { timeline: context.timeline.ref, header: { kind: "record", id: `${id}.header` } };
- const operations: FragmentOperation[] = [{ id: "empty", producer: soundProducers.create, inputs: {}, result: { kind: "output", name: "set" } }];
- let previous = "empty", index = 0;
- for (const child of element.children) {
- if (child.kind === "text") { if (child.value.trim()) throw new Error("Sound Track accepts Use children."); continue; }
- if (child.name.split(":").at(-1) !== "Use") throw new Error("Sound Track accepts Use children.");
- assertAttributes(child, ["id", "style", ...temporalWindowAttributeNames]); assertEmptyElement(child);
- const useId = optionalTextAttribute(child, "id") ?? `${id}.use.${index + 1}`;
- index += 1;
- const hasTime = temporalWindowAttributeNames.some(name => child.attributes[name] !== undefined);
- const temporal = createTemporalWindowProjection({ id: useId, ...context, resolveReference,
- element: hasTime ? child : { ...child, attributes: { ...child.attributes, during: "program" } } });
- records.push(...temporal.records); components.push(...temporal.components); fragments.push(...temporal.fragments);
- const value = authored<SoundStyle>(reference(child, "style", soundTypes.style, resolveReference));
- const style = soundStyle(value.fragment, value.bindings);
- fragments.push(style.fragment);
- const audioId = `${useId}.audio`;
- components.push({ id: `${useId}.__style`, fragment: style.fragment.id,
- inputs: { ...Object.fromEntries(Object.entries(style.bindings).map(([key, bound]) => [key, bound.ref])),
- timeline: context.timeline.ref, window: temporal.ref }, outputs: { audio: audioId }, range: child.range });
- const suffix = `use-${operations.length}`;
- collectorInputs.push({ name: `${suffix}-window`, type: temporalTypes.window }, { name: `${suffix}-audio`, type: compositionTypes.audioTrack });
- bindings[`${suffix}-window`] = temporal.ref; bindings[`${suffix}-audio`] = { kind: "component-output", component: `${useId}.__style`, output: "audio" };
- operations.push({ id: suffix, producer: soundProducers.append, inputs: { set: operation(previous), window: input(`${suffix}-window`), audio: input(`${suffix}-audio`) }, result: { kind: "output", name: "set" } });
- previous = suffix;
- }
- operations.push({ id: "resolve", producer: soundProducers.resolve, inputs: { set: operation(previous), timeline: input("timeline"), header: input("header") }, result: { kind: "output", name: "audio" } });
- const collector = sealGraphFragment({ inputs: collectorInputs, operations, exports: [{ name: "audio", type: compositionTypes.audioTrack, root: operation("resolve") }, { name: "program", type: soundTypes.set, root: operation(previous) }] });
- fragments.push(collector);
- components.push({ id, fragment: collector.id, inputs: bindings, outputs: { audio: `${id}.audio`, program: `${id}.program` }, range: element.range });
- return { records, components, fragments, exports: [`${id}.audio`, `${id}.program`] };
-};
-
-export const ordinarySoundFragment = sealGraphFragment({
- inputs: ordinaryInputs,
- operations: [{ id: "ordinary", producer: soundProducers.ordinary,
- inputs: Object.fromEntries(ordinaryInputs.map(port => [port.name, input(port.name)])), result: { kind: "output", name: "audio" } }],
- exports: [{ name: "audio", type: compositionTypes.audioTrack, root: operation("ordinary") }],
-});
-export const decodeSoundStyleSurface: StructuredSurfaceHandler = ({ element }) => {
- assertAttributes(element, ["id", "gain", "end-gain"]); assertEmptyElement(element);
- const id = textAttribute(element, "id");
- const number = (name: string, fallback: number): number => {
- const raw = optionalTextAttribute(element, name);
- const value = raw === undefined ? fallback : raw.trim() === "" ? NaN : Number(raw);
- if (!Number.isFinite(value) || value < 0 || value > 64) throw new Error(`Sound Style ${name} must be a gain from 0 to 64.`);
- return value;
- };
- const gain = number("gain", 1), endGain = number("end-gain", gain);
- const specId = `${id}.gain`;
- const style = soundStyle(ordinarySoundFragment, { spec: { ref: { kind: "record", id: specId }, type: soundTypes.gain } });
- return { records: [
- { id: specId, type: soundTypes.gain, value: { kind: "inline", value: { gain, endGain } }, range: element.range },
- { id, type: soundTypes.style, value: { kind: "inline", value: canonicalize(style) }, range: element.range },
- ], components: [], fragments: [] };
-};
diff --git a/packages/sound/test/sound.test.ts b/packages/sound/test/sound.test.ts
deleted file mode 100644
index 807d2887..00000000
--- a/packages/sound/test/sound.test.ts
+++ /dev/null
@@ -1,94 +0,0 @@
-import assert from "node:assert/strict";
-import test from "node:test";
-import { assertAudioTrackIdentity, sealAudioTrack, audioEnvelopeGainAt, sealComposition } from "@hypit/composition";
-import { compileAudioProgramPlan, verifyAudioProgramPlan } from "@hypit/media-pipeline";
-import { ordinarySound, sourceSound, appendSoundUse, resolveSound, soundStyle, soundTypes, decodeSoundTrackSurface } from "../src/index.js";
-import { timelineFixture } from "../../../test/timeline-fixture.js";
-import { projectProgramWindow } from "../../../test/temporal-fixture.js";
-import type { Timeline } from "@hypit/timeline";
-import { timelineTypes } from "@hypit/timeline";
-import type { NarrativeExcerpt } from "@hypit/narrative";
-import { narrativeTypes } from "@hypit/narrative";
-import type { StructuredElement, SurfaceResolvedReference } from "@hypit/markup";
-import { canonicalize } from "@hypit/protocol";
-import { sealGraphFragment } from "@hypit/elaborator";
-import { compositionTypes } from "@hypit/composition";
-import { temporalTypes } from "@hypit/temporal";
-import { crossfadeSound } from "../../../examples/semantic-composition/packages/sound-styles/src/render.js";
-
-const clock = { id: "film", durationSec: 6, frameRate: { numerator: 30, denominator: 1 } };
-const base = timelineFixture(clock, { segments: [{ id: "a", frameCount: 90 }, { id: "b", frameCount: 90 }] });
-const timeline: Timeline = { ...base, items: base.items.map((item,index)=>({...item,startFrame:index===0 ? 15:60})) };
-const window = (id: string, start: number, end: number, source=timeline) => projectProgramWindow({ itemId: id, semantic: source,
- projection: { start: { ref: "absolute", at: { unit: "frames", value: start } }, end: { ref: "absolute", at: { unit: "frames", value: end } } } });
-const segment = (id:string):NarrativeExcerpt => ({kind:"segment",narrativeId:base.narrativeId,id,tokenStart:0,tokenEndExclusive:0});
-const at = (frame:number)=>frame*1600;
-
-test("ordinary sound chooses the last declared active audio source, with gaps and absence intact",()=>{
- const sound=ordinarySound(timeline,window("base",0,180));
- assertAudioTrackIdentity(sound,timeline);
- assert.deepEqual(sound.clips.map(c=>[c.id,c.audibility]),[
- ["a",[{startSample:at(15),endSampleExclusive:at(60)}]],
- ["b",[{startSample:at(60),endSampleExclusive:at(150)}]],
- ]);
- assert.deepEqual(sound.clips.map(c=>c.source.startSample),[0,0]);
- const reverse={...timeline,items:[timeline.items[1]!,timeline.items[0]!]};
- const reversed=ordinarySound(reverse,window("base",0,180,reverse));
- assert.deepEqual(reversed.clips.find(c=>c.id==="b")!.audibility,[{startSample:at(105),endSampleExclusive:at(150)}]);
- const noAudio={...timeline,items:timeline.items.map((item,index)=> index===0?item:{...item,take:{...item.take,media:{timeline:item.take.media.timeline,visual:{artifact:{kind:"blob" as const,resource:"res_visual" as const,size:1,mediaType:"video/mp4"},width:64,height:64}}}})};
- assert.deepEqual(ordinarySound(noAudio,window("base",0,180,noAudio)).clips[0]!.audibility,[{startSample:at(15),endSampleExclusive:at(105)}]);
- const empty={...clock,items:[]};
- assert.equal(ordinarySound(empty,window("empty",0,180,empty)).clips.length,0);
-});
-
-test("Use silence and later restoration preserve original playback and fade progress",()=>{
- const broad=window("broad",0,180), fade=window("fade",15,150), hidden=window("hidden",45,75), restore=window("restore",60,65);
- let set=appendSoundUse({uses:[]},broad,ordinarySound(timeline,broad));
- set=appendSoundUse(set,fade,ordinarySound(timeline,fade,{gain:0,endGain:1}));
- set=appendSoundUse(set,hidden,ordinarySound(timeline,hidden,{gain:0,endGain:0}));
- set=appendSoundUse(set,restore,ordinarySound(timeline,restore));
- const result=resolveSound(timeline,"voice",set);
- const resumed=result.clips.find(c=>c.id==="2:b")!;
- assert.deepEqual(resumed.target,{startSample:at(60),endSampleExclusive:at(150)});
- assert.equal(resumed.source.startSample,0);
- assert.deepEqual(resumed.audibility,[{startSample:at(75),endSampleExclusive:at(150)}]);
- assert.equal(audioEnvelopeGainAt(resumed.gainEnvelope,at(75)),60/135);
- assert.deepEqual(result.clips.find(c=>c.id==="4:b")!.audibility,[{startSample:at(60),endSampleExclusive:at(65)}]);
- const plan=compileAudioProgramPlan(sealComposition({id:"film",canvas:{width:64,height:64,clearColor:"#000000"},tracks:[result]}),timeline);
- verifyAudioProgramPlan(plan);
- assert.deepEqual(plan.clips.find(c=>c.id==="voice:2:b")!.gainEnvelope,resumed.gainEnvelope);
- assert.deepEqual(plan.clips.find(c=>c.id==="voice:2:b")!.audibility,resumed.audibility);
- assert.equal(resolveSound(timeline,"silent",{uses:[]}).clips.length,0);
-});
-
-test("a project crossfade binds source roles independently from its physical Window",()=>{
- const span=window("mix",60,105);
- const mixed=crossfadeSound(timeline,span,segment("a"),segment("b"));
- assertAudioTrackIdentity(mixed,timeline);
- assert.deepEqual(mixed.clips.map(c=>c.id),["a","b"]);
- for(const c of mixed.clips) assert.equal(audioEnvelopeGainAt(c.gainEnvelope,at(82.5)),0.5);
- assert.equal(mixed.clips.find(c=>c.id==="a")!.target.startSample,at(15));
- const swapped=crossfadeSound(timeline,span,segment("b"),segment("a"));
- assert.equal(audioEnvelopeGainAt(swapped.clips.find(c=>c.id==="a")!.gainEnvelope,at(60)),0);
- const missingSound={...timeline,items:timeline.items.map((item,index)=>index===0?item:{...item,take:{...item.take,media:{timeline:item.take.media.timeline,visual:{artifact:{kind:"blob" as const,resource:"res_visual" as const,size:1,mediaType:"video/mp4"},width:64,height:64}}}})};
- assert.equal(crossfadeSound(missingSound,window("mix",60,105,missingSound),segment("a"),segment("b")).clips.length,1);
- assert.throws(()=>sourceSound(timeline,span,segment("unknown")),/Unknown/);
- assert.throws(()=>sourceSound(timeline,span,{...segment("a"),narrativeId:"other"}),/Narrative/);
- assert.throws(()=>crossfadeSound(timeline,span,segment("a"),segment("a")),/distinct/);
-});
-
-test("Sound Style bindings expand as graph edges and broad Use needs no selector",async()=>{
- const common=[{name:"timeline",type:timelineTypes.track},{name:"window",type:temporalTypes.window}];
- const extra=[{name:"outgoing",type:narrativeTypes.excerpt},{name:"incoming",type:narrativeTypes.excerpt}];
- const fragment=sealGraphFragment({inputs:[...common,...extra],operations:[{id:"render",producer:{module:{name:"@example/test",version:"1"},name:"mix"},inputs:Object.fromEntries([...common,...extra].map(p=>[p.name,{kind:"fragment-input" as const,name:p.name}])),result:{kind:"output",name:"audio"}}],exports:[{name:"audio",type:compositionTypes.audioTrack,root:{kind:"fragment-operation",operation:"render"}}]});
- const ref=(id:string,type:SurfaceResolvedReference["type"]):SurfaceResolvedReference=>({path:id,type,ref:{kind:"record",id}});
- const bindings={outgoing:ref("outgoing",narrativeTypes.excerpt),incoming:ref("incoming",narrativeTypes.excerpt)};
- const style=soundStyle(fragment,bindings);
- const refs=new Map<string,SurfaceResolvedReference>([["timeline",ref("timeline",timelineTypes.track)],["style",{...ref("style",soundTypes.style),record:{id:"style",type:soundTypes.style,value:{kind:"inline",value:canonicalize(style)}}}]]);
- const range={source:"test.svml",start:0,end:1};
- const root:StructuredElement={kind:"element",name:"sound:Track",attributes:{id:"voice",timeline:{kind:"reference",path:"timeline"}},range,children:[{kind:"element",name:"sound:Use",attributes:{style:{kind:"reference",path:"style"}},children:[],range}]};
- const result=await decodeSoundTrackSurface({element:root,sourceName:"test.svml",resolveReference:path=>refs.get(path),resolveAsset:async()=>{throw new Error("unexpected");}});
- assert.deepEqual(result.components.find(c=>c.id==="voice.use.1.__style")!.inputs.outgoing,bindings.outgoing.ref);
- assert.deepEqual(result.components.at(-1)!.outputs,{audio:"voice.audio",program:"voice.program"});
- assert.throws(()=>soundStyle(fragment,{...bindings,window:ref("window",temporalTypes.window)}),/supplies window/);
-});
diff --git a/packages/spatial/README.md b/packages/spatial/README.md
index 81b6bad5..a85c1253 100644
--- a/packages/spatial/README.md
+++ b/packages/spatial/README.md
@@ -1,21 +1,53 @@
# `@hypit/spatial`
-Shared video-domain geometry: explicit Canvas coordinates, Points, Frames, Paths, externally measured
-Region Timelines, intrinsic extents and deterministic two-frame content fitting. It owns no semantic
-timing, Paint, motion, media decoding,
-renderer, Provider or Core behavior.
+Pure two-dimensional video geometry. The package owns the final raster viewport, resolved
+picture-plane geometry, source extents and affine mappings. It owns no layer tree, media, Paint,
+motion, Timeline, detector, Provider or renderer policy.
-The package exposes self-described `Canvas`, `Point`, `Path`, `Extent`, `RegionTimeline`, `Frame`,
-`AnchoredFrame` and `AspectFrame` author Surfaces plus pure geometry functions and fixed-port Producers.
+## The spatial values
-## Destination and fitted content
+- `Canvas` is the final raster viewport. A `<space:Canvas>` publishes `.canvas` for raster consumers
+ and `.bounds` for ordinary geometry consumers. Its runtime value contains only width and height;
+ the `@1` coordinate convention is a protocol rule rather than four repeated constants.
+- `SpatialPoint`, `SpatialFrame` and `SpatialPath` are plain resolved values in the program picture
+ plane: top-left origin, x right, y down, square pixels. They carry no Canvas id, parent pointer or
+ construction history.
+- `IntrinsicExtent` is the natural width and height of a source or local picture plane.
+- `ContentFit` is an authored mapping policy.
+- `SpatialMap2D` is an affine map from a local plane into the program picture plane.
-`SpatialFrame` is a destination rectangle in Canvas pixels. `IntrinsicExtent` supplies source
-dimensions. `fitContent(frame, extent, fit)` returns a `FittedContent.contentFrame`: the scaled
-source's rectangle in the same coordinates. The caller supplies the fitting area; Media Track
-derives that area by subtracting its border and padding from its outer Frame.
+Canvas is deliberately not a container. Visual components own clipping, Paint, draw order and
+motion. A Frame may extend outside the Canvas and may be reused anywhere its numbers mean the same
+thing.
-`ContentFit.sizing` selects the size before alignment:
+```svml
+<space:Canvas id="vertical" width="1080" height="1920"/>
+<space:Frame id="safe" within={vertical.bounds}
+ left="6%" top="5%" right="94%" bottom="92%"/>
+<space:AnchoredFrame id="portrait" within={safe}
+ x="100%" y="100%" width="320px" height="320px" anchor="bottom-right"/>
+```
+
+`Frame`, `AnchoredFrame` and `AspectFrame` are three constructors for the same runtime
+`SpatialFrame`. Other layout packages can publish that same Type without modifying this package.
+
+An author or project component that already knows an affine relation can publish it directly:
+
+```svml
+<space:Map id="turned" xx="0" xy="-0.5" yx="0.5" yy="0" tx="920" ty="180"/>
+```
+
+This is the open value below fitting conveniences, not a scene node. It carries no source, Frame,
+Canvas identity, clipping policy or time.
+
+## Content fitting resolves a mapping
+
+`resolveContentFit(frame, extent, fit)` returns a `SpatialMap2D`. It does not invent a second
+`FittedContent` model. Consumers may apply the map to source-local Points and Paths, and may derive
+the mapped source bounds when they need a rectangular optimization or diagnostic. That bounding
+rectangle is not the mapping and cannot replace it after rotation, skew or reflection.
+
+`ContentFit.sizing` selects the scale before alignment:
| Sizing | Result |
| --- | --- |
@@ -24,54 +56,20 @@ derives that area by subtracting its border and padding from its outer Frame.
| `fit-width` / `fit-height` | Preserve aspect and match the named dimension |
| `native` | Keep the source's pixel dimensions |
| `scale-down` | Use `contain` while limiting scale to at most 1 |
-| `stretch` | Use the destination width and height independently |
-
-`framePoint` and `contentPoint` are separate normalized points in `[0,1]`. The scaled source point
-is placed at the destination point, then `offsetPx` is added. Before any constraint, the horizontal
-position is `frame.xPx + frame.widthPx * framePoint.x - contentWidth * contentPoint.x + offsetPx.x`;
-the vertical position follows the same relationship.
-
-`constraint: bounded` clamps each coordinate between `frameStart` and
-`frameStart + frameSize - contentSize`, whichever is lower or higher. Large content keeps the
-destination covered on that axis, and small content stays inside it. `free` leaves the calculated
-position unchanged. Fitting calculates rectangles; the consuming component owns clipping.
-
-`decodeContentFitProperties` exposes these through Recipe keys: `fit`, `frame-x`, `frame-y`,
-`content-x`, `content-y`, `fit-offset-x`, `fit-offset-y`, and `fit-constraint`. Defaults are `contain`,
-center points (`0.5`), zero pixel offsets and `bounded`. These alignment fractions place the source
-inside the supplied destination. Canvas placement remains the job of Frame / AnchoredFrame /
-AspectFrame. Media Track uses this decoder for Items, Performances and Sequence members; project
-components can use the same fitting functions where that presentation fits their role.
-
-## Measured regions
-
-`RegionTimeline` accepts already measured data rather than running a detector. Face detection and
-tracking can observe the footage produced by an earlier Build: keep useful boxes as ordinary numbers,
-then reuse that media while rendering Caption with the finished timeline. Measurement precedes the
-composition that consumes it; it need not precede the first media-producing Build. RegionTimeline
-does not start a detector to discover its own layout. One SVS Recipe holds the exact ProgramSpace
-frame count and named tracks whose array positions are Frames:
-
-```svs
-heads.default {
- frame-count: 3;
- tracks: [
- {"id":"WIFE","regions":[[0.12,0.09,0.20,0.26],null,[0.13,0.10,0.20,0.26]]}
- ];
-}
-```
+| `stretch` | Match destination width and height independently |
-```svml
-<space:RegionTimeline id="heads" within={vertical} recipe={tracking.heads.default}/>
-```
+`framePoint` selects a normalized point in the destination and `contentPoint` selects the source
+point placed there. `offsetPx` adds an explicit displacement. `bounded` constrains the translation
+to the available placement range; `free` preserves the authored translation. Clipping is still the
+visual consumer's decision.
+
+The Recipe decoder exposes `fit`, `frame-x`, `frame-y`, `content-x`, `content-y`, `fit-offset-x`,
+`fit-offset-y` and `fit-constraint`. Visual Track uses it, and project components may use the same
+pure functions.
-Every measured region is normalized `[x, y, width, height]`; `null` says that this track has no
-measured region on that Frame. The Surface converts measured regions to the selected Canvas's pixels
-at author time; it never fills missing Frames or interprets a track id.
+## Evidence over time is a peer package
-Prepare measurements against the exact edited media, clock and Canvas used by the composition.
-Individual Take measurements need their actual frame offsets in the program; boxes measured before
-a crop, resize or inset need that placement transform. Face-to-head expansion, identity association,
-cut handling and any interpolation are explicit external preparation decisions. The resulting
-Recipe records their output. Caption consumers can assign Role meaning to track ids without making
-Spatial aware of speakers, detector APIs or generated-media Providers.
+Frame-indexed observations do not belong to static geometry. `@hypit/region-track` relates prepared
+regions to a Timeline and resolves them into picture-plane Frames. Detection, identity association,
+interpolation and source-to-picture projection remain explicit preparation or project-package work.
+This keeps Spatial reusable and prevents a central scene or evidence registry.
diff --git a/packages/spatial/package.json b/packages/spatial/package.json
index 91713327..134147e2 100644
--- a/packages/spatial/package.json
+++ b/packages/spatial/package.json
@@ -14,8 +14,7 @@
"@hypit/component-kit": "workspace:*",
"@hypit/elaborator": "workspace:*",
"@hypit/protocol": "workspace:*",
- "@hypit/markup": "workspace:*",
- "@hypit/svs": "workspace:*"
+ "@hypit/markup": "workspace:*"
},
"devDependencies": {
"@hypit/core": "workspace:*",
diff --git a/packages/spatial/src/activation.ts b/packages/spatial/src/activation.ts
index 24f107dd..21216143 100644
--- a/packages/spatial/src/activation.ts
+++ b/packages/spatial/src/activation.ts
@@ -6,9 +6,9 @@ import {
decodeCanvasSurface,
decodeExtentSurface,
decodeFrameSurface,
+ decodeMapSurface,
decodePathSurface,
decodePointSurface,
- decodeRegionTimelineSurface,
} from "./surface.js";
import {
spatialManifest,
@@ -31,7 +31,7 @@ export const hypitPackage = {
createMarkupSurfaceHostFacet({ module: spatialModuleRef,
declaration: spatialMarkupSurfaces.find((item) => item.name === "extent")!, handler: decodeExtentSurface }),
createMarkupSurfaceHostFacet({ module: spatialModuleRef,
- declaration: spatialMarkupSurfaces.find((item) => item.name === "region-timeline")!, handler: decodeRegionTimelineSurface }),
+ declaration: spatialMarkupSurfaces.find((item) => item.name === "map")!, handler: decodeMapSurface }),
createMarkupSurfaceHostFacet({ module: spatialModuleRef,
declaration: spatialMarkupSurfaces.find((item) => item.name === "frame")!, handler: decodeFrameSurface }),
createMarkupSurfaceHostFacet({ module: spatialModuleRef,
diff --git a/packages/spatial/src/component.ts b/packages/spatial/src/component.ts
index 68353c5e..7dae8de1 100644
--- a/packages/spatial/src/component.ts
+++ b/packages/spatial/src/component.ts
@@ -1,21 +1,19 @@
import type { ComponentPackage } from "@hypit/component-kit";
import { canonicalize } from "@hypit/protocol";
import type { StoredValue } from "@hypit/protocol";
-
-import { anchoredFrame, aspectFrame, assertCanvasSpace, assertContentFit, assertFittedContent, assertIntrinsicExtent, assertSpatialFrame, assertSpatialPath, assertSpatialPoint, assertSpatialRegionTimeline, canvasFrame, fitContent, frameFromEdges } from "./geometry.js";
+import { anchoredFrame, aspectFrame, assertCanvas, assertContentFit, assertIntrinsicExtent, assertSpatialFrame, assertSpatialMap2D, assertSpatialPath, assertSpatialPoint, frameFromEdges, resolveContentFit } from "./geometry.js";
import { spatialProducers, spatialTypes } from "./manifest.js";
import type {
AnchoredFrameProgram,
AspectFrameProgram,
- CanvasSpace,
+ Canvas,
ContentFit,
- FittedContent,
FrameEdgesProgram,
IntrinsicExtent,
SpatialFrame,
+ SpatialMap2D,
SpatialPath,
SpatialPoint,
- SpatialRegionTimeline,
} from "./types.js";
function inline<T>(value: StoredValue | undefined, label: string): T {
@@ -26,20 +24,18 @@ const output = (value: unknown) => ({ kind: "inline" as const, value: canonicali
export const spatialComponent = {
producers: [
- { producer: spatialProducers.canvasFrame, handler: ({ inputs }) => ({ outputs: { frame: output(canvasFrame(inline<CanvasSpace>(inputs.canvas?.value, "CanvasSpace"))) }, needs: {} }) },
{ producer: spatialProducers.frameEdges, handler: ({ inputs }) => ({ outputs: { frame: output(frameFromEdges(inline<SpatialFrame>(inputs.parent?.value, "SpatialFrame"), inline<FrameEdgesProgram>(inputs.program?.value, "FrameEdgesProgram"))) }, needs: {} }) },
{ producer: spatialProducers.anchoredFrame, handler: ({ inputs }) => ({ outputs: { frame: output(anchoredFrame(inline<SpatialFrame>(inputs.parent?.value, "SpatialFrame"), inline<AnchoredFrameProgram>(inputs.program?.value, "AnchoredFrameProgram"))) }, needs: {} }) },
{ producer: spatialProducers.aspectFrame, handler: ({ inputs }) => ({ outputs: { frame: output(aspectFrame(inline<SpatialFrame>(inputs.parent?.value, "SpatialFrame"), inline<IntrinsicExtent>(inputs.extent?.value, "IntrinsicExtent"), inline<AspectFrameProgram>(inputs.program?.value, "AspectFrameProgram"))) }, needs: {} }) },
- { producer: spatialProducers.fitContent, handler: ({ inputs }) => ({ outputs: { fitted: output(fitContent(inline<SpatialFrame>(inputs.frame?.value, "SpatialFrame"), inline<IntrinsicExtent>(inputs.extent?.value, "IntrinsicExtent"), inline<ContentFit>(inputs.fit?.value, "ContentFit"))) }, needs: {} }) },
+ { producer: spatialProducers.resolveContentFit, handler: ({ inputs }) => ({ outputs: { mapping: output(resolveContentFit(inline<SpatialFrame>(inputs.frame?.value, "SpatialFrame"), inline<IntrinsicExtent>(inputs.extent?.value, "IntrinsicExtent"), inline<ContentFit>(inputs.fit?.value, "ContentFit"))) }, needs: {} }) },
],
validators: [
- { type: spatialTypes.canvas, handler: ({ value }) => assertCanvasSpace(inline<CanvasSpace>(value, "CanvasSpace")) },
+ { type: spatialTypes.canvas, handler: ({ value }) => assertCanvas(inline<Canvas>(value, "Canvas")) },
{ type: spatialTypes.point, handler: ({ value }) => assertSpatialPoint(inline<SpatialPoint>(value, "SpatialPoint")) },
{ type: spatialTypes.frame, handler: ({ value }) => assertSpatialFrame(inline<SpatialFrame>(value, "SpatialFrame")) },
- { type: spatialTypes.regionTimeline, handler: ({ value }) => assertSpatialRegionTimeline(inline<SpatialRegionTimeline>(value, "SpatialRegionTimeline")) },
{ type: spatialTypes.path, handler: ({ value }) => assertSpatialPath(inline<SpatialPath>(value, "SpatialPath")) },
{ type: spatialTypes.extent, handler: ({ value }) => assertIntrinsicExtent(inline<IntrinsicExtent>(value, "IntrinsicExtent")) },
+ { type: spatialTypes.map2D, handler: ({ value }) => assertSpatialMap2D(inline<SpatialMap2D>(value, "SpatialMap2D")) },
{ type: spatialTypes.fit, handler: ({ value }) => assertContentFit(inline<ContentFit>(value, "ContentFit")) },
- { type: spatialTypes.fitted, handler: ({ value }) => assertFittedContent(inline<FittedContent>(value, "FittedContent")) },
],
} satisfies ComponentPackage;
diff --git a/packages/spatial/src/fragment.ts b/packages/spatial/src/fragment.ts
index 7ce84dd3..7bdb58d7 100644
--- a/packages/spatial/src/fragment.ts
+++ b/packages/spatial/src/fragment.ts
@@ -1,16 +1,9 @@
import { sealGraphFragment } from "@hypit/elaborator";
-
import { spatialProducers, spatialTypes } from "./manifest.js";
const input = (name: string) => ({ kind: "fragment-input" as const, name });
const operation = (name: string) => ({ kind: "fragment-operation" as const, operation: name });
-export const canvasFrameFragment = sealGraphFragment({
- inputs: [{ name: "canvas", type: spatialTypes.canvas }],
- operations: [{ id: "resolve", producer: spatialProducers.canvasFrame, inputs: { canvas: input("canvas") }, result: { kind: "output", name: "frame" } }],
- exports: [{ name: "frame", type: spatialTypes.frame, root: operation("resolve") }],
-});
-
export const frameEdgesFragment = sealGraphFragment({
inputs: [{ name: "parent", type: spatialTypes.frame }, { name: "program", type: spatialTypes.frameEdgesProgram }],
operations: [{ id: "resolve", producer: spatialProducers.frameEdges, inputs: { parent: input("parent"), program: input("program") }, result: { kind: "output", name: "frame" } }],
@@ -29,8 +22,8 @@ export const aspectFrameFragment = sealGraphFragment({
exports: [{ name: "frame", type: spatialTypes.frame, root: operation("resolve") }],
});
-export const fitContentFragment = sealGraphFragment({
+export const contentFitFragment = sealGraphFragment({
inputs: [{ name: "frame", type: spatialTypes.frame }, { name: "extent", type: spatialTypes.extent }, { name: "fit", type: spatialTypes.fit }],
- operations: [{ id: "resolve", producer: spatialProducers.fitContent, inputs: { frame: input("frame"), extent: input("extent"), fit: input("fit") }, result: { kind: "output", name: "fitted" } }],
- exports: [{ name: "fitted", type: spatialTypes.fitted, root: operation("resolve") }],
+ operations: [{ id: "resolve", producer: spatialProducers.resolveContentFit, inputs: { frame: input("frame"), extent: input("extent"), fit: input("fit") }, result: { kind: "output", name: "mapping" } }],
+ exports: [{ name: "mapping", type: spatialTypes.map2D, root: operation("resolve") }],
});
diff --git a/packages/spatial/src/geometry.ts b/packages/spatial/src/geometry.ts
index d0b4d0d2..d75f0f14 100644
--- a/packages/spatial/src/geometry.ts
+++ b/packages/spatial/src/geometry.ts
@@ -2,17 +2,16 @@
import type {
AnchoredFrameProgram,
AspectFrameProgram,
- CanvasSpace,
+ Canvas,
ContentFit,
- FittedContent,
FrameEdgesProgram,
IntrinsicExtent,
SpatialAnchor,
SpatialFrame,
SpatialLength,
+ SpatialMap2D,
SpatialPath,
SpatialPoint,
- SpatialRegionTimeline,
} from "./types.js";
function finite(value: number, label: string): void {
@@ -24,12 +23,10 @@ function positive(value: number, label: string): void {
if (value <= 0) throw new Error(`${label} must be positive.`);
}
-export function assertCanvasSpace(value: CanvasSpace): void {
+export function assertCanvas(value: Canvas): void {
if (!Number.isSafeInteger(value.widthPx) || value.widthPx <= 0
- || !Number.isSafeInteger(value.heightPx) || value.heightPx <= 0
- || value.origin !== "top-left" || value.xDirection !== "right"
- || value.yDirection !== "down" || value.pixelAspect !== "square") {
- throw new Error("CanvasSpace is invalid.");
+ || !Number.isSafeInteger(value.heightPx) || value.heightPx <= 0) {
+ throw new Error("Canvas is invalid.");
}
}
@@ -45,24 +42,6 @@ export function assertSpatialFrame(value: SpatialFrame): void {
positive(value.heightPx, "SpatialFrame.heightPx");
}
-export function assertSpatialRegionTimeline(value: SpatialRegionTimeline): void {
- assertCanvasSpace(value.canvas);
- if (!Number.isSafeInteger(value.frameCount) || value.frameCount <= 0 || value.tracks.length === 0) {
- throw new Error("SpatialRegionTimeline is empty or has an invalid Frame count.");
- }
- const ids = new Set<string>();
- for (const track of value.tracks) {
- if (!track.id.trim() || ids.has(track.id)) throw new Error(`SpatialRegionTimeline repeats or omits Track id ${track.id}.`);
- ids.add(track.id);
- if (track.frames.length !== value.frameCount) {
- throw new Error(`SpatialRegionTimeline Track ${track.id} does not cover every Frame.`);
- }
- for (const frame of track.frames) {
- if (frame !== null) assertSpatialFrame(frame);
- }
- }
-}
-
export function assertIntrinsicExtent(value: IntrinsicExtent): void {
positive(value.widthPx, "IntrinsicExtent.widthPx");
positive(value.heightPx, "IntrinsicExtent.heightPx");
@@ -87,8 +66,13 @@ export function assertContentFit(value: ContentFit): void {
if (value.constraint !== "bounded" && value.constraint !== "free") throw new Error("ContentFit.constraint is invalid.");
}
-export function assertFittedContent(value: FittedContent): void {
- assertSpatialFrame(value.contentFrame);
+export function assertSpatialMap2D(value: SpatialMap2D): void {
+ finite(value.xx, "SpatialMap2D.xx");
+ finite(value.xy, "SpatialMap2D.xy");
+ finite(value.yx, "SpatialMap2D.yx");
+ finite(value.yy, "SpatialMap2D.yy");
+ finite(value.tx, "SpatialMap2D.tx");
+ finite(value.ty, "SpatialMap2D.ty");
}
function commandNumbers(command: SpatialPath["commands"][number]): readonly number[] {
@@ -143,8 +127,8 @@ function sealFrame(value: SpatialFrame): SpatialFrame {
return frame;
}
-export function canvasFrame(canvas: CanvasSpace): SpatialFrame {
- assertCanvasSpace(canvas);
+export function canvasFrame(canvas: Canvas): SpatialFrame {
+ assertCanvas(canvas);
return sealFrame({ xPx: 0, yPx: 0, widthPx: canvas.widthPx, heightPx: canvas.heightPx });
}
@@ -201,7 +185,8 @@ function boundedCoordinate(position: number, contentSize: number, frameStart: nu
return Math.min(high, Math.max(low, position));
}
-export function fitContent(frame: SpatialFrame, extent: IntrinsicExtent, fit: ContentFit): FittedContent {
+/** Resolve a source-local pixel plane into the program picture plane. */
+export function resolveContentFit(frame: SpatialFrame, extent: IntrinsicExtent, fit: ContentFit): SpatialMap2D {
assertSpatialFrame(frame);
assertIntrinsicExtent(extent);
assertContentFit(fit);
@@ -221,18 +206,111 @@ export function fitContent(frame: SpatialFrame, extent: IntrinsicExtent, fit: Co
xPx = boundedCoordinate(xPx, widthPx, frame.xPx, frame.widthPx);
yPx = boundedCoordinate(yPx, heightPx, frame.yPx, frame.heightPx);
}
- const result: FittedContent = {
- contentFrame: sealFrame({ xPx, yPx, widthPx, heightPx }),
+ const result: SpatialMap2D = {
+ xx: widthPx / extent.widthPx,
+ xy: 0,
+ yx: 0,
+ yy: heightPx / extent.heightPx,
+ tx: xPx,
+ ty: yPx,
};
- assertFittedContent(result);
+ assertSpatialMap2D(result);
return result;
}
-export function sealCanvasSpace(value: CanvasSpace): CanvasSpace { assertCanvasSpace(value); return structuredClone(value); }
+export function mapSpatialPoint(point: SpatialPoint, mapping: SpatialMap2D): SpatialPoint {
+ assertSpatialPoint(point);
+ assertSpatialMap2D(mapping);
+ return sealSpatialPoint({
+ xPx: mapping.xx * point.xPx + mapping.xy * point.yPx + mapping.tx,
+ yPx: mapping.yx * point.xPx + mapping.yy * point.yPx + mapping.ty,
+ });
+}
+
+/** Compose mappings in application order: `first`, then `second`. */
+export function composeSpatialMaps(first: SpatialMap2D, second: SpatialMap2D): SpatialMap2D {
+ assertSpatialMap2D(first);
+ assertSpatialMap2D(second);
+ return sealSpatialMap2D({
+ xx: second.xx * first.xx + second.xy * first.yx,
+ xy: second.xx * first.xy + second.xy * first.yy,
+ yx: second.yx * first.xx + second.yy * first.yx,
+ yy: second.yx * first.xy + second.yy * first.yy,
+ tx: second.xx * first.tx + second.xy * first.ty + second.tx,
+ ty: second.yx * first.tx + second.yy * first.ty + second.ty,
+ });
+}
+
+function mapPathCommand(command: SpatialPath["commands"][number], mapping: SpatialMap2D): SpatialPath["commands"][number] {
+ const point = (xPx: number, yPx: number) => mapSpatialPoint({ xPx, yPx }, mapping);
+ if (command.kind === "close") return command;
+ if (command.kind === "move" || command.kind === "line") {
+ const mapped = point(command.xPx, command.yPx);
+ return { kind: command.kind, ...mapped };
+ }
+ if (command.kind === "quadratic") {
+ const control = point(command.controlX, command.controlY);
+ const end = point(command.xPx, command.yPx);
+ return { kind: "quadratic", controlX: control.xPx, controlY: control.yPx, ...end };
+ }
+ const control1 = point(command.control1X, command.control1Y);
+ const control2 = point(command.control2X, command.control2Y);
+ const end = point(command.xPx, command.yPx);
+ return {
+ kind: "cubic",
+ control1X: control1.xPx, control1Y: control1.yPx,
+ control2X: control2.xPx, control2Y: control2.yPx,
+ ...end,
+ };
+}
+
+export function mapSpatialPath(path: SpatialPath, mapping: SpatialMap2D): SpatialPath {
+ assertSpatialPath(path);
+ assertSpatialMap2D(mapping);
+ return sealSpatialPath({ commands: path.commands.map((command) => mapPathCommand(command, mapping)) });
+}
+
+/** Preserve an exact transformed rectangle as a closed Path. */
+export function mapSpatialFramePath(frame: SpatialFrame, mapping: SpatialMap2D): SpatialPath {
+ assertSpatialFrame(frame);
+ return mapSpatialPath({ commands: [
+ { kind: "move", xPx: frame.xPx, yPx: frame.yPx },
+ { kind: "line", xPx: frame.xPx + frame.widthPx, yPx: frame.yPx },
+ { kind: "line", xPx: frame.xPx + frame.widthPx, yPx: frame.yPx + frame.heightPx },
+ { kind: "line", xPx: frame.xPx, yPx: frame.yPx + frame.heightPx },
+ { kind: "close" },
+ ] }, mapping);
+}
+
+/** Return the axis-aligned bounds of a transformed Frame; rotation is not discarded silently. */
+export function mapSpatialFrameBounds(frame: SpatialFrame, mapping: SpatialMap2D): SpatialFrame {
+ const points = [
+ mapSpatialPoint({ xPx: frame.xPx, yPx: frame.yPx }, mapping),
+ mapSpatialPoint({ xPx: frame.xPx + frame.widthPx, yPx: frame.yPx }, mapping),
+ mapSpatialPoint({ xPx: frame.xPx + frame.widthPx, yPx: frame.yPx + frame.heightPx }, mapping),
+ mapSpatialPoint({ xPx: frame.xPx, yPx: frame.yPx + frame.heightPx }, mapping),
+ ];
+ const x = points.map((point) => point.xPx);
+ const y = points.map((point) => point.yPx);
+ const left = Math.min(...x);
+ const top = Math.min(...y);
+ return sealSpatialFrame({
+ xPx: left,
+ yPx: top,
+ widthPx: Math.max(...x) - left,
+ heightPx: Math.max(...y) - top,
+ });
+}
+
+export function mapIntrinsicExtentBounds(extent: IntrinsicExtent, mapping: SpatialMap2D): SpatialFrame {
+ assertIntrinsicExtent(extent);
+ return mapSpatialFrameBounds({ xPx: 0, yPx: 0, widthPx: extent.widthPx, heightPx: extent.heightPx }, mapping);
+}
+
+export function sealCanvas(value: Canvas): Canvas { assertCanvas(value); return structuredClone(value); }
export function sealSpatialPoint(value: SpatialPoint): SpatialPoint { assertSpatialPoint(value); return structuredClone(value); }
export function sealSpatialFrame(value: SpatialFrame): SpatialFrame { assertSpatialFrame(value); return structuredClone(value); }
-export function sealSpatialRegionTimeline(value: SpatialRegionTimeline): SpatialRegionTimeline { assertSpatialRegionTimeline(value); return structuredClone(value); }
export function sealSpatialPath(value: SpatialPath): SpatialPath { assertSpatialPath(value); return structuredClone(value); }
export function sealIntrinsicExtent(value: IntrinsicExtent): IntrinsicExtent { assertIntrinsicExtent(value); return structuredClone(value); }
+export function sealSpatialMap2D(value: SpatialMap2D): SpatialMap2D { assertSpatialMap2D(value); return structuredClone(value); }
export function sealContentFit(value: ContentFit): ContentFit { assertContentFit(value); return structuredClone(value); }
-export function sealFittedContent(value: FittedContent): FittedContent { assertFittedContent(value); return structuredClone(value); }
diff --git a/packages/spatial/src/index.ts b/packages/spatial/src/index.ts
index e3f1751e..0ae1a757 100644
--- a/packages/spatial/src/index.ts
+++ b/packages/spatial/src/index.ts
@@ -3,8 +3,7 @@ export { contentFitPropertyNames, decodeContentFitProperties } from "./author.js
export {
anchoredFrameFragment,
aspectFrameFragment,
- canvasFrameFragment,
- fitContentFragment,
+ contentFitFragment,
frameEdgesFragment,
} from "./fragment.js";
export * from "./geometry.js";
@@ -19,7 +18,7 @@ export {
contentFitSchema,
intrinsicExtentSchema,
spatialFrameSchema,
- spatialRegionTimelineSchema,
+ spatialMap2DSchema,
spatialPathSchema,
spatialPointSchema,
} from "./schema.js";
@@ -29,9 +28,8 @@ export {
decodeCanvasSurface,
decodeExtentSurface,
decodeFrameSurface,
+ decodeMapSurface,
decodePathSurface,
decodePointSurface,
- decodeRegionTimelineSurface,
} from "./surface.js";
-export { spatialRegionTimeline } from "./region-timeline.js";
export type * from "./types.js";
diff --git a/packages/spatial/src/manifest.ts b/packages/spatial/src/manifest.ts
index f786845a..1711894e 100644
--- a/packages/spatial/src/manifest.ts
+++ b/packages/spatial/src/manifest.ts
@@ -1,39 +1,34 @@
import type { ModuleManifest, ProducerRef, TypeRef } from "@hypit/protocol";
-import { svsRecipeType } from "@hypit/svs";
import {
anchoredFrameProgramSchema,
aspectFrameProgramSchema,
- canvasSpaceSchema,
+ canvasSchema,
contentFitSchema,
- fittedContentSchema,
frameEdgesProgramSchema,
intrinsicExtentSchema,
spatialFrameSchema,
spatialPathSchema,
spatialPointSchema,
- spatialRegionTimelineSchema,
} from "./schema.js";
export const spatialModuleRef = { name: "@hypit/spatial", version: "1" } as const;
export const spatialTypes = {
- canvas: { module: spatialModuleRef, name: "CanvasSpace" },
+ canvas: { module: spatialModuleRef, name: "Canvas" },
point: { module: spatialModuleRef, name: "SpatialPoint" },
frame: { module: spatialModuleRef, name: "SpatialFrame" },
- regionTimeline: { module: spatialModuleRef, name: "SpatialRegionTimeline" },
path: { module: spatialModuleRef, name: "SpatialPath" },
extent: { module: spatialModuleRef, name: "IntrinsicExtent" },
+ map2D: { module: spatialModuleRef, name: "SpatialMap2D" },
fit: { module: spatialModuleRef, name: "ContentFit" },
- fitted: { module: spatialModuleRef, name: "FittedContent" },
frameEdgesProgram: { module: spatialModuleRef, name: "FrameEdgesProgram" },
anchoredFrameProgram: { module: spatialModuleRef, name: "AnchoredFrameProgram" },
aspectFrameProgram: { module: spatialModuleRef, name: "AspectFrameProgram" },
} satisfies Record<string, TypeRef>;
export const spatialProducers = {
- canvasFrame: { module: spatialModuleRef, name: "canvas-frame" },
frameEdges: { module: spatialModuleRef, name: "frame-edges" },
anchoredFrame: { module: spatialModuleRef, name: "anchored-frame" },
aspectFrame: { module: spatialModuleRef, name: "aspect-frame" },
- fitContent: { module: spatialModuleRef, name: "fit-content" },
+ resolveContentFit: { module: spatialModuleRef, name: "resolve-content-fit" },
} satisfies Record<string, ProducerRef>;
const anchors = [
@@ -43,17 +38,17 @@ const anchors = [
] as const;
const lengthNote = "A length is a number followed by `px` or `%`; a percentage resolves against the parent Frame's width on the x axis and its height on the y axis.";
-const withinNote = "A Canvas written in `within` is first resolved to its own full-Canvas Frame, so every Frame is placed inside a Frame.";
+const withinNote = "`within` accepts one resolved SpatialFrame. Use a Canvas declaration's `.bounds` port for the complete picture.";
const emptyNote = "The element is empty; it accepts no children and no text.";
export const spatialMarkupSurfaces = [
{
- name: "canvas", tag: "Canvas", mode: "structured", outputs: [spatialTypes.canvas],
+ name: "canvas", tag: "Canvas", mode: "structured", outputs: [spatialTypes.canvas, spatialTypes.frame],
vocabulary: {
- summary: "Declares one Canvas: the pixel extent every Frame is measured inside.",
+ summary: "Declares the final raster viewport and publishes its full-picture Frame.",
attributes: [
{ name: "id", kind: "identifier", required: true,
- summary: "Names the CanvasSpace Record this element publishes." },
+ summary: "Names the Canvas Record this element publishes." },
{ name: "width", kind: "literal", required: true,
summary: "States how many pixels wide the Canvas is." },
{ name: "height", kind: "literal", required: true,
@@ -63,27 +58,33 @@ export const spatialMarkupSurfaces = [
notes: [
emptyNote,
"`width` and `height` are positive whole numbers of pixels.",
- "The coordinate system is fixed: the origin is top-left, x increases to the right, y increases downward and pixels are square.",
- "The CanvasSpace is published under the bare `id`.",
+ "The @1 picture-plane convention is fixed: the origin is top-left, x increases to the right, y increases downward and pixels are square. These are protocol rules, not repeated Canvas fields.",
+ "The viewport is published as `.canvas`; its canonical full-picture Frame is published as `.bounds`.",
+ ],
+ ports: [
+ { name: "canvas", type: spatialTypes.canvas,
+ summary: "The final raster viewport and pixel basis." },
+ { name: "bounds", type: spatialTypes.frame,
+ summary: "The deterministic full-picture Frame `{0, 0, width, height}`." },
],
},
},
{
name: "point", tag: "Point", mode: "structured", outputs: [spatialTypes.point],
vocabulary: {
- summary: "Names one position on the Canvas in pixels.",
+ summary: "Names one position in the program picture plane, in pixels.",
attributes: [
{ name: "id", kind: "identifier", required: true,
summary: "Names the SpatialPoint Record this element publishes." },
{ name: "x", kind: "literal", required: true,
- summary: "Places the Point this many pixels along the Canvas x axis." },
+ summary: "Places the Point this many pixels along the picture-plane x axis." },
{ name: "y", kind: "literal", required: true,
- summary: "Places the Point this many pixels down the Canvas y axis." },
+ summary: "Places the Point this many pixels down the picture-plane y axis." },
],
example: `<space:Point id="headline-origin" x="120" y="280"/>`,
notes: [
emptyNote,
- "`x` and `y` are finite pixel numbers, so a Point may be fractional, negative or outside the Canvas.",
+ "`x` and `y` are finite pixel numbers, so a Point may be fractional, negative or outside the final viewport.",
"The SpatialPoint is published under the bare `id`.",
],
},
@@ -91,7 +92,7 @@ export const spatialMarkupSurfaces = [
{
name: "path", tag: "Path", mode: "structured", outputs: [spatialTypes.path],
vocabulary: {
- summary: "Draws one Path in Canvas pixels from an ordered list of commands.",
+ summary: "Draws one Path in program-picture pixels from an ordered list of commands.",
attributes: [
{ name: "id", kind: "identifier", required: true,
summary: "Names the SpatialPath Record this element publishes." },
@@ -100,42 +101,42 @@ export const spatialMarkupSurfaces = [
{ tag: "Move", cardinality: "many", summary: "Lifts the pen and starts a new subpath at a point.",
attributes: [
{ name: "x", kind: "literal", required: true,
- summary: "Starts the subpath this many pixels along the Canvas x axis." },
+ summary: "Starts the subpath this many pixels along the picture-plane x axis." },
{ name: "y", kind: "literal", required: true,
- summary: "Starts the subpath this many pixels down the Canvas y axis." },
+ summary: "Starts the subpath this many pixels down the picture-plane y axis." },
] },
{ tag: "Line", cardinality: "many", summary: "Draws a straight segment to a point.",
attributes: [
{ name: "x", kind: "literal", required: true,
- summary: "Ends the segment this many pixels along the Canvas x axis." },
+ summary: "Ends the segment this many pixels along the picture-plane x axis." },
{ name: "y", kind: "literal", required: true,
- summary: "Ends the segment this many pixels down the Canvas y axis." },
+ summary: "Ends the segment this many pixels down the picture-plane y axis." },
] },
{ tag: "Quadratic", cardinality: "many", summary: "Draws a quadratic curve to a point through one control point.",
attributes: [
{ name: "control-x", kind: "literal", required: true,
- summary: "Places the control point this many pixels along the Canvas x axis." },
+ summary: "Places the control point this many pixels along the picture-plane x axis." },
{ name: "control-y", kind: "literal", required: true,
- summary: "Places the control point this many pixels down the Canvas y axis." },
+ summary: "Places the control point this many pixels down the picture-plane y axis." },
{ name: "x", kind: "literal", required: true,
- summary: "Ends the curve this many pixels along the Canvas x axis." },
+ summary: "Ends the curve this many pixels along the picture-plane x axis." },
{ name: "y", kind: "literal", required: true,
- summary: "Ends the curve this many pixels down the Canvas y axis." },
+ summary: "Ends the curve this many pixels down the picture-plane y axis." },
] },
{ tag: "Cubic", cardinality: "many", summary: "Draws a cubic curve to a point through two control points.",
attributes: [
{ name: "control1-x", kind: "literal", required: true,
- summary: "Places the control point leaving the current point this many pixels along the Canvas x axis." },
+ summary: "Places the control point leaving the current point this many pixels along the picture-plane x axis." },
{ name: "control1-y", kind: "literal", required: true,
- summary: "Places the control point leaving the current point this many pixels down the Canvas y axis." },
+ summary: "Places the control point leaving the current point this many pixels down the picture-plane y axis." },
{ name: "control2-x", kind: "literal", required: true,
- summary: "Places the control point entering the end point this many pixels along the Canvas x axis." },
+ summary: "Places the control point entering the end point this many pixels along the picture-plane x axis." },
{ name: "control2-y", kind: "literal", required: true,
- summary: "Places the control point entering the end point this many pixels down the Canvas y axis." },
+ summary: "Places the control point entering the end point this many pixels down the picture-plane y axis." },
{ name: "x", kind: "literal", required: true,
- summary: "Ends the curve this many pixels along the Canvas x axis." },
+ summary: "Ends the curve this many pixels along the picture-plane x axis." },
{ name: "y", kind: "literal", required: true,
- summary: "Ends the curve this many pixels down the Canvas y axis." },
+ summary: "Ends the curve this many pixels down the picture-plane y axis." },
] },
{ tag: "Close", cardinality: "many", summary: "Closes the open subpath back to where it began.",
attributes: [] },
@@ -173,42 +174,36 @@ export const spatialMarkupSurfaces = [
},
},
{
- name: "region-timeline", tag: "RegionTimeline", mode: "structured", outputs: [spatialTypes.regionTimeline],
+ name: "map", tag: "Map", mode: "structured", outputs: [spatialTypes.map2D],
vocabulary: {
- summary: "Resolves externally measured, normalized AABB sequences into one frame-exact set of named Canvas-space region tracks.",
+ summary: "Names one affine mapping from a local pixel plane into the program picture plane.",
attributes: [
- { name: "id", kind: "identifier", required: true,
- summary: "Names the SpatialRegionTimeline Record this element publishes." },
- { name: "within", kind: "reference", required: true, accepts: [spatialTypes.canvas],
- summary: "Chooses the Canvas that normalized regions are measured inside." },
- { name: "recipe", kind: "reference", required: true, accepts: [svsRecipeType],
- summary: "Chooses the external frame-indexed region data.",
- recipe: [
- { name: "frame-count", required: true,
- summary: "States the exact number of ProgramSpace Frames covered by every named track." },
- { name: "tracks", required: true,
- summary: "Lists objects shaped as {id, regions}; each regions array contains frame-count normalized [x, y, width, height] AABBs or null when the region is absent." },
- ] },
+ { name: "id", kind: "identifier", required: true, summary: "Names the SpatialMap2D Record this element publishes." },
+ { name: "xx", kind: "literal", required: true, summary: "Maps source x into picture x." },
+ { name: "xy", kind: "literal", required: true, summary: "Maps source y into picture x." },
+ { name: "yx", kind: "literal", required: true, summary: "Maps source x into picture y." },
+ { name: "yy", kind: "literal", required: true, summary: "Maps source y into picture y." },
+ { name: "tx", kind: "literal", required: true, summary: "Translates the result along picture x in pixels." },
+ { name: "ty", kind: "literal", required: true, summary: "Translates the result along picture y in pixels." },
],
- example: `<space:RegionTimeline id="heads" within={vertical} recipe={tracking.heads.default}/>` ,
+ ports: [{ name: "", type: spatialTypes.map2D, summary: "The resolved affine mapping, addressed by the element's own id." }],
+ example: `<space:Map id="turned" xx="0" xy="-0.5" yx="0.5" yy="0" tx="920" ty="180"/>`,
notes: [
emptyNote,
- "Detection and tracking happen before authoring; this Surface consumes finished numeric evidence and never invokes them during a Build.",
- "The array index is the ProgramSpace Frame; the Surface performs no timestamp conversion, interpolation, smoothing or identity inference.",
- "Each normalized AABB lies inside [0, 1] and is resolved into Canvas pixels during author compilation; null remains explicit absence.",
- "Track ids are ordinary external labels; a consumer may interpret them as Script Roles without Spatial knowing what a Role is.",
+ "The equations are `x' = xx*x + xy*y + tx` and `y' = yx*x + yy*y + ty`.",
+ "All six numbers are finite. The author is responsible for deliberate reflection, collapse or placement outside the Canvas.",
],
},
},
{
name: "frame", tag: "Frame", mode: "structured", outputs: [spatialTypes.frame, spatialTypes.frameEdgesProgram],
vocabulary: {
- summary: "Places one Frame by its four edges inside a Canvas or a parent Frame.",
+ summary: "Places one Frame by its four edges inside a parent Frame.",
attributes: [
{ name: "id", kind: "identifier", required: true,
summary: "Names the Frame this element publishes." },
- { name: "within", kind: "reference", required: true, accepts: [spatialTypes.canvas, spatialTypes.frame],
- summary: "Chooses the Canvas or parent Frame the four edges are measured against." },
+ { name: "within", kind: "reference", required: true, accepts: [spatialTypes.frame],
+ summary: "Chooses the parent Frame the four edges are measured against." },
{ name: "left", kind: "literal", required: true,
summary: "Places the left edge, measured from the parent's left." },
{ name: "top", kind: "literal", required: true,
@@ -222,7 +217,7 @@ export const spatialMarkupSurfaces = [
{ name: "", type: spatialTypes.frame,
summary: "The resolved Frame, addressed by the element's own id." },
],
- example: `<space:Frame id="safe" within={vertical} left="6%" top="4%" right="94%" bottom="96%"/>`,
+ example: `<space:Frame id="safe" within={vertical.bounds} left="6%" top="4%" right="94%" bottom="96%"/>`,
notes: [
emptyNote,
lengthNote,
@@ -238,8 +233,8 @@ export const spatialMarkupSurfaces = [
attributes: [
{ name: "id", kind: "identifier", required: true,
summary: "Names the Frame this element publishes." },
- { name: "within", kind: "reference", required: true, accepts: [spatialTypes.canvas, spatialTypes.frame],
- summary: "Chooses the Canvas or parent Frame the position and size are measured against." },
+ { name: "within", kind: "reference", required: true, accepts: [spatialTypes.frame],
+ summary: "Chooses the parent Frame the position and size are measured against." },
{ name: "x", kind: "literal", required: true,
summary: "Places the anchor point along the parent's width." },
{ name: "y", kind: "literal", required: true,
@@ -275,8 +270,8 @@ export const spatialMarkupSurfaces = [
attributes: [
{ name: "id", kind: "identifier", required: true,
summary: "Names the Frame this element publishes." },
- { name: "within", kind: "reference", required: true, accepts: [spatialTypes.canvas, spatialTypes.frame],
- summary: "Chooses the Canvas or parent Frame the position and size are measured against." },
+ { name: "within", kind: "reference", required: true, accepts: [spatialTypes.frame],
+ summary: "Chooses the parent Frame the position and size are measured against." },
{ name: "x", kind: "literal", required: true,
summary: "Places the anchor point along the parent's width." },
{ name: "y", kind: "literal", required: true,
@@ -315,27 +310,25 @@ export const spatialManifest: ModuleManifest = {
format: "hypit.module@1",
name: spatialModuleRef.name,
version: spatialModuleRef.version,
- dependencies: [{ module: svsRecipeType.module }],
+ dependencies: [],
types: [
{ name: spatialTypes.canvas.name },
{ name: spatialTypes.point.name },
{ name: spatialTypes.frame.name },
- { name: spatialTypes.regionTimeline.name },
{ name: spatialTypes.path.name },
{ name: spatialTypes.extent.name },
+ { name: spatialTypes.map2D.name },
{ name: spatialTypes.fit.name },
- { name: spatialTypes.fitted.name },
{ name: spatialTypes.frameEdgesProgram.name },
{ name: spatialTypes.anchoredFrameProgram.name },
{ name: spatialTypes.aspectFrameProgram.name },
],
capabilities: [],
producers: [
- { name: spatialProducers.canvasFrame.name, inputs: [{ name: "canvas", type: spatialTypes.canvas }], outputs: [{ name: "frame", type: spatialTypes.frame }], needs: [] },
{ name: spatialProducers.frameEdges.name, inputs: [{ name: "parent", type: spatialTypes.frame }, { name: "program", type: spatialTypes.frameEdgesProgram }], outputs: [{ name: "frame", type: spatialTypes.frame }], needs: [] },
{ name: spatialProducers.anchoredFrame.name, inputs: [{ name: "parent", type: spatialTypes.frame }, { name: "program", type: spatialTypes.anchoredFrameProgram }], outputs: [{ name: "frame", type: spatialTypes.frame }], needs: [] },
{ name: spatialProducers.aspectFrame.name, inputs: [{ name: "parent", type: spatialTypes.frame }, { name: "extent", type: spatialTypes.extent }, { name: "program", type: spatialTypes.aspectFrameProgram }], outputs: [{ name: "frame", type: spatialTypes.frame }], needs: [] },
- { name: spatialProducers.fitContent.name, inputs: [{ name: "frame", type: spatialTypes.frame }, { name: "extent", type: spatialTypes.extent }, { name: "fit", type: spatialTypes.fit }], outputs: [{ name: "fitted", type: spatialTypes.fitted }], needs: [] },
+ { name: spatialProducers.resolveContentFit.name, inputs: [{ name: "frame", type: spatialTypes.frame }, { name: "extent", type: spatialTypes.extent }, { name: "fit", type: spatialTypes.fit }], outputs: [{ name: "mapping", type: spatialTypes.map2D }], needs: [] },
],
};
export const spatialDependency = { module: spatialModuleRef } as const;
diff --git a/packages/spatial/src/region-timeline.ts b/packages/spatial/src/region-timeline.ts
deleted file mode 100644
index bfe5abdd..00000000
--- a/packages/spatial/src/region-timeline.ts
+++ /dev/null
@@ -1,69 +0,0 @@
-import type { CanonicalValue } from "@hypit/protocol";
-import type { SvsRecipe } from "@hypit/svs";
-
-import { assertCanvasSpace, sealSpatialRegionTimeline } from "./geometry.js";
-import type { CanvasSpace, SpatialFrame, SpatialRegionTimeline } from "./types.js";
-
-type CanonicalRecord = Readonly<Record<string, CanonicalValue>>;
-
-function record(value: CanonicalValue, label: string): CanonicalRecord {
- if (value === null || Array.isArray(value) || typeof value !== "object") throw new Error(`${label} must be a record.`);
- return value as CanonicalRecord;
-}
-
-function exact(value: CanonicalRecord, allowed: readonly string[], label: string): void {
- const unknown = Object.keys(value).find((name) => !allowed.includes(name));
- if (unknown !== undefined) throw new Error(`${label} does not accept ${unknown}.`);
-}
-
-function positiveInteger(value: CanonicalValue | undefined, label: string): number {
- if (typeof value !== "number" || !Number.isSafeInteger(value) || value <= 0) {
- throw new Error(`${label} must be a positive integer.`);
- }
- return value;
-}
-
-function normalizedRegion(value: CanonicalValue, canvas: CanvasSpace, label: string): SpatialFrame | null {
- if (value === null) return null;
- if (!Array.isArray(value) || value.length !== 4 || value.some((part) => typeof part !== "number" || !Number.isFinite(part))) {
- throw new Error(`${label} must be null or [x, y, width, height].`);
- }
- const [x, y, width, height] = value as unknown as readonly [number, number, number, number];
- if (x < 0 || y < 0 || width <= 0 || height <= 0 || x + width > 1 || y + height > 1) {
- throw new Error(`${label} must be a positive normalized region inside the Canvas.`);
- }
- return {
- xPx: x * canvas.widthPx,
- yPx: y * canvas.heightPx,
- widthPx: width * canvas.widthPx,
- heightPx: height * canvas.heightPx,
- };
-}
-
-/** Resolve normalized author data into frame-exact Canvas-pixel evidence. */
-export function spatialRegionTimeline(recipe: SvsRecipe, canvas: CanvasSpace): SpatialRegionTimeline {
- assertCanvasSpace(canvas);
- exact(recipe.properties, ["frame-count", "tracks"], `Spatial Region Timeline ${recipe.path}`);
- const frameCount = positiveInteger(recipe.properties["frame-count"], `${recipe.path}.frame-count`);
- const tracksValue = recipe.properties.tracks;
- if (!Array.isArray(tracksValue) || tracksValue.length === 0) throw new Error(`${recipe.path}.tracks must be a non-empty list.`);
- const tracks = tracksValue.map((value, trackIndex) => {
- const item = record(value, `${recipe.path}.tracks.${trackIndex + 1}`);
- exact(item, ["id", "regions"], `${recipe.path}.tracks.${trackIndex + 1}`);
- const id = item.id;
- if (typeof id !== "string" || !id.trim()) throw new Error(`${recipe.path}.tracks.${trackIndex + 1}.id must be non-empty text.`);
- const regions = item.regions;
- if (!Array.isArray(regions) || regions.length !== frameCount) {
- throw new Error(`${recipe.path}.tracks.${trackIndex + 1}.regions must contain exactly ${frameCount} Frames.`);
- }
- return {
- id,
- frames: regions.map((region, frame) => normalizedRegion(
- region,
- canvas,
- `${recipe.path}.${id}.regions.${frame}`,
- )),
- };
- });
- return sealSpatialRegionTimeline({ canvas, frameCount, tracks });
-}
diff --git a/packages/spatial/src/schema.ts b/packages/spatial/src/schema.ts
index b272461d..cc5bb3d9 100644
--- a/packages/spatial/src/schema.ts
+++ b/packages/spatial/src/schema.ts
@@ -7,25 +7,11 @@ const point = object({ x: { schema: { kind: "number", minimum: 0, maximum: 1 } }
const pixelPoint = object({ x: { schema: number }, y: { schema: number } });
const length = object({ unit: { schema: { kind: "string", enum: ["px", "percent"] } }, value: { schema: number } });
-export const canvasSpaceSchema = object({
+export const canvasSchema = object({
widthPx: { schema: positiveInteger }, heightPx: { schema: positiveInteger },
- origin: { schema: { kind: "literal", value: "top-left" } },
- xDirection: { schema: { kind: "literal", value: "right" } },
- yDirection: { schema: { kind: "literal", value: "down" } },
- pixelAspect: { schema: { kind: "literal", value: "square" } },
});
export const spatialPointSchema = object({ xPx: { schema: number }, yPx: { schema: number } });
export const spatialFrameSchema = object({ xPx: { schema: number }, yPx: { schema: number }, widthPx: { schema: number }, heightPx: { schema: number } });
-export const spatialRegionTimelineSchema = object({
- canvas: { schema: canvasSpaceSchema },
- frameCount: { schema: positiveInteger },
- tracks: { schema: { kind: "array", minItems: 1, items: object({
- id: { schema: { kind: "string", minLength: 1 } },
- frames: { schema: { kind: "array", minItems: 1, items: {
- kind: "oneOf", variants: [spatialFrameSchema, { kind: "null" }],
- } } },
- }) } },
-});
const pathCommand: ValueSchema = { kind: "oneOf", variants: [
object({ kind: { schema: { kind: "literal", value: "move" } }, xPx: { schema: number }, yPx: { schema: number } }),
object({ kind: { schema: { kind: "literal", value: "line" } }, xPx: { schema: number }, yPx: { schema: number } }),
@@ -35,12 +21,15 @@ const pathCommand: ValueSchema = { kind: "oneOf", variants: [
] };
export const spatialPathSchema = object({ commands: { schema: { kind: "array", minItems: 2, items: pathCommand } } });
export const intrinsicExtentSchema = object({ widthPx: { schema: number }, heightPx: { schema: number } });
+export const spatialMap2DSchema = object({
+ xx: { schema: number }, xy: { schema: number }, yx: { schema: number },
+ yy: { schema: number }, tx: { schema: number }, ty: { schema: number },
+});
export const contentFitSchema = object({
sizing: { schema: { kind: "string", enum: ["contain", "cover", "fit-width", "fit-height", "native", "scale-down", "stretch"] } },
framePoint: { schema: point }, contentPoint: { schema: point }, offsetPx: { schema: pixelPoint },
constraint: { schema: { kind: "string", enum: ["bounded", "free"] } },
});
-export const fittedContentSchema = object({ contentFrame: { schema: spatialFrameSchema } });
export const frameEdgesProgramSchema = object({ left: { schema: length }, top: { schema: length }, right: { schema: length }, bottom: { schema: length } });
const anchor = { kind: "string", enum: ["top-left", "top-center", "top-right", "middle-left", "center", "middle-right", "bottom-left", "bottom-center", "bottom-right"] } as const;
export const anchoredFrameProgramSchema = object({ x: { schema: length }, y: { schema: length }, width: { schema: length }, height: { schema: length }, anchor: { schema: anchor }, offsetPx: { schema: pixelPoint } });
diff --git a/packages/spatial/src/surface.ts b/packages/spatial/src/surface.ts
index ecef1540..271eb888 100644
--- a/packages/spatial/src/surface.ts
+++ b/packages/spatial/src/surface.ts
@@ -1,9 +1,6 @@
-import type { AuthorValueRef, GraphFragment } from "@hypit/elaborator";
import type { CanonicalValue } from "@hypit/protocol";
-import { svsRecipeType } from "@hypit/svs";
-import type { SvsRecipe } from "@hypit/svs";
+import type { AuthorValueRef } from "@hypit/elaborator";
import type {
- SurfaceComponentDraft,
StructuredElement,
StructuredSurfaceHandler,
SurfaceResolvedReference,
@@ -13,12 +10,10 @@ import type {
import {
anchoredFrameFragment,
aspectFrameFragment,
- canvasFrameFragment,
frameEdgesFragment,
} from "./fragment.js";
import { spatialTypes } from "./manifest.js";
-import { spatialRegionTimeline } from "./region-timeline.js";
-import { assertSpatialPath, sealCanvasSpace, sealIntrinsicExtent, sealSpatialPoint } from "./geometry.js";
+import { assertSpatialPath, canvasFrame, sealCanvas, sealIntrinsicExtent, sealSpatialMap2D, sealSpatialPoint } from "./geometry.js";
import type {
AnchoredFrameProgram,
AspectFrameProgram,
@@ -27,7 +22,6 @@ import type {
SpatialLength,
SpatialPath,
SpatialPathCommand,
- CanvasSpace,
} from "./types.js";
function sameType(left: SurfaceResolvedReference["type"], right: SurfaceResolvedReference["type"]): boolean {
@@ -92,44 +86,28 @@ function reference(
return result;
}
-function inline<T>(value: SurfaceResolvedReference, label: string): T {
- if (value.record?.value.kind !== "inline") throw new Error(`${label} must reference an authored inline Record.`);
- return value.record.value.value as unknown as T;
-}
-
-type ParentFrame = {
- readonly ref: AuthorValueRef;
- readonly components: readonly SurfaceComponentDraft[];
- readonly fragments: readonly GraphFragment[];
-};
-
function parentFrame(
- id: string,
element: StructuredElement,
parent: SurfaceResolvedReference,
-): ParentFrame {
- if (sameType(parent.type, spatialTypes.frame)) return { ref: parent.ref, components: [], fragments: [] };
- if (!sameType(parent.type, spatialTypes.canvas)) throw new Error(`${element.name}.within must reference CanvasSpace or SpatialFrame.`);
- const output = `${id}.__canvas-frame`;
- const component = `${id}.__canvas-frame-component`;
- return {
- ref: { kind: "component-output", component, output: "frame" },
- components: [{
- id: component, fragment: canvasFrameFragment.id,
- inputs: { canvas: parent.ref }, outputs: { frame: output }, range: element.range,
- }],
- fragments: [canvasFrameFragment],
- };
+): SurfaceResolvedReference["ref"] {
+ if (!sameType(parent.type, spatialTypes.frame)) throw new Error(`${element.name}.within must reference SpatialFrame.`);
+ return parent.ref;
}
export const decodeCanvasSurface: StructuredSurfaceHandler = ({ element }) => {
exact(element, ["id", "width", "height"], ["id", "width", "height"]);
const id = text(element, "id");
- const canvas = sealCanvasSpace({
+ const canvas = sealCanvas({
widthPx: positiveInteger(element, "width"), heightPx: positiveInteger(element, "height"),
- origin: "top-left", xDirection: "right", yDirection: "down", pixelAspect: "square",
});
- return { records: [{ id, type: spatialTypes.canvas, value: { kind: "inline", value: canvas as unknown as CanonicalValue }, range: element.range }], components: [], fragments: [] };
+ const bounds = canvasFrame(canvas);
+ return {
+ records: [
+ { id: `${id}.canvas`, type: spatialTypes.canvas, value: { kind: "inline" as const, value: canvas as unknown as CanonicalValue }, range: element.range },
+ { id: `${id}.bounds`, type: spatialTypes.frame, value: { kind: "inline" as const, value: bounds as unknown as CanonicalValue }, range: element.range },
+ ],
+ components: [], fragments: [],
+ };
};
export const decodePointSurface: StructuredSurfaceHandler = ({ element }) => {
@@ -216,21 +194,15 @@ export const decodeExtentSurface: StructuredSurfaceHandler = ({ element }) => {
return { records: [{ id, type: spatialTypes.extent, value: { kind: "inline", value: extent as unknown as CanonicalValue }, range: element.range }], components: [], fragments: [] };
};
-export const decodeRegionTimelineSurface: StructuredSurfaceHandler = ({ element, resolveReference }) => {
- exact(element, ["id", "within", "recipe"], ["id", "within", "recipe"]);
+export const decodeMapSurface: StructuredSurfaceHandler = ({ element }) => {
+ exact(element, ["id", "xx", "xy", "yx", "yy", "tx", "ty"], ["id", "xx", "xy", "yx", "yy", "tx", "ty"]);
const id = text(element, "id");
- const canvasReference = reference(element, "within", resolveReference);
- if (!sameType(canvasReference.type, spatialTypes.canvas)) throw new Error(`${element.name}.within must reference CanvasSpace.`);
- const recipeReference = reference(element, "recipe", resolveReference);
- if (!sameType(recipeReference.type, svsRecipeType)) throw new Error(`${element.name}.recipe must reference an SVS Recipe.`);
- const timeline = spatialRegionTimeline(
- inline<SvsRecipe>(recipeReference, `${element.name}.recipe`),
- inline<CanvasSpace>(canvasReference, `${element.name}.within`),
- );
- return {
- records: [{ id, type: spatialTypes.regionTimeline, value: { kind: "inline", value: timeline as unknown as CanonicalValue }, range: element.range }],
- components: [], fragments: [],
- };
+ const mapping = sealSpatialMap2D({
+ xx: number(element, "xx"), xy: number(element, "xy"),
+ yx: number(element, "yx"), yy: number(element, "yy"),
+ tx: number(element, "tx"), ty: number(element, "ty"),
+ });
+ return { records: [{ id, type: spatialTypes.map2D, value: { kind: "inline", value: mapping as unknown as CanonicalValue }, range: element.range }], components: [], fragments: [] };
};
function frameSurface(
@@ -241,15 +213,14 @@ function frameSurface(
fragment: typeof frameEdgesFragment | typeof anchoredFrameFragment,
) {
const id = text(element, "id");
- const parent = parentFrame(id, element, reference(element, "within", resolveReference));
+ const parent = parentFrame(element, reference(element, "within", resolveReference));
const programId = `${id}.__program`;
return {
records: [{ id: programId, type: programType, value: { kind: "inline" as const, value: program as unknown as CanonicalValue }, range: element.range }],
components: [
- ...parent.components,
- { id, fragment: fragment.id, inputs: { parent: parent.ref, program: { kind: "record" as const, id: programId } }, outputs: { frame: id }, range: element.range },
+ { id, fragment: fragment.id, inputs: { parent, program: { kind: "record" as const, id: programId } }, outputs: { frame: id }, range: element.range },
],
- fragments: [...parent.fragments, fragment],
+ fragments: [fragment],
exports: [id],
};
}
@@ -296,7 +267,7 @@ export const decodeAspectFrameSurface: StructuredSurfaceHandler = ({ element, re
const hasHeight = element.attributes.height !== undefined;
if (hasWidth === hasHeight) throw new Error(`${element.name} requires exactly one of width or height.`);
const id = text(element, "id");
- const parent = parentFrame(id, element, reference(element, "within", resolveReference));
+ const parent = parentFrame(element, reference(element, "within", resolveReference));
const extent = aspectExtent(id, element, resolveReference);
const program: AspectFrameProgram = {
x: length(element, "x"), y: length(element, "y"),
@@ -310,10 +281,9 @@ export const decodeAspectFrameSurface: StructuredSurfaceHandler = ({ element, re
{ id: programId, type: spatialTypes.aspectFrameProgram, value: { kind: "inline" as const, value: program as unknown as CanonicalValue }, range: element.range },
],
components: [
- ...parent.components,
- { id, fragment: aspectFrameFragment.id, inputs: { parent: parent.ref, extent: extent.ref, program: { kind: "record" as const, id: programId } }, outputs: { frame: id }, range: element.range },
+ { id, fragment: aspectFrameFragment.id, inputs: { parent, extent: extent.ref, program: { kind: "record" as const, id: programId } }, outputs: { frame: id }, range: element.range },
],
- fragments: [...parent.fragments, aspectFrameFragment],
+ fragments: [aspectFrameFragment],
exports: [id],
};
};
diff --git a/packages/spatial/src/types.ts b/packages/spatial/src/types.ts
index 9bf7797d..2000a624 100644
--- a/packages/spatial/src/types.ts
+++ b/packages/spatial/src/types.ts
@@ -1,10 +1,6 @@
-export type CanvasSpace = {
+export type Canvas = {
readonly widthPx: number;
readonly heightPx: number;
- readonly origin: "top-left";
- readonly xDirection: "right";
- readonly yDirection: "down";
- readonly pixelAspect: "square";
};
export type SpatialPoint = {
@@ -19,19 +15,6 @@ export type SpatialFrame = {
readonly heightPx: number;
};
-/** One named, frame-exact sequence of measured regions in one Canvas. */
-export type SpatialRegionTrack = {
- readonly id: string;
- readonly frames: readonly (SpatialFrame | null)[];
-};
-
-/** External spatial evidence indexed directly by ProgramSpace Frame. */
-export type SpatialRegionTimeline = {
- readonly canvas: CanvasSpace;
- readonly frameCount: number;
- readonly tracks: readonly SpatialRegionTrack[];
-};
-
export type SpatialPathCommand =
| { readonly kind: "move"; readonly xPx: number; readonly yPx: number }
| { readonly kind: "line"; readonly xPx: number; readonly yPx: number }
@@ -48,6 +31,22 @@ export type IntrinsicExtent = {
readonly heightPx: number;
};
+/**
+ * An affine mapping from a local two-dimensional plane into the program picture
+ * plane. It applies as:
+ *
+ * x' = xx * x + xy * y + tx
+ * y' = yx * x + yy * y + ty
+ */
+export type SpatialMap2D = {
+ readonly xx: number;
+ readonly xy: number;
+ readonly yx: number;
+ readonly yy: number;
+ readonly tx: number;
+ readonly ty: number;
+};
+
export type NormalizedPoint = {
readonly x: number;
readonly y: number;
@@ -61,10 +60,6 @@ export type ContentFit = {
readonly constraint: "bounded" | "free";
};
-export type FittedContent = {
- readonly contentFrame: SpatialFrame;
-};
-
export type SpatialLength = {
readonly unit: "px" | "percent";
readonly value: number;
diff --git a/packages/spatial/test/spatial.test.ts b/packages/spatial/test/spatial.test.ts
index 82a8f122..e6a8a177 100644
--- a/packages/spatial/test/spatial.test.ts
+++ b/packages/spatial/test/spatial.test.ts
@@ -10,7 +10,6 @@ import {
createMarkupAuthorFrontend,
} from "@hypit/markup";
import { createRecordAdmitter, TypeValidatorRegistry } from "@hypit/validation";
-import { svsFrontend, svsManifest } from "@hypit/svs";
import {
anchoredFrame,
@@ -19,11 +18,16 @@ import {
decodeAspectFrameSurface,
decodeCanvasSurface,
decodeFrameSurface,
+ decodeMapSurface,
decodePathSurface,
decodePointSurface,
- decodeRegionTimelineSurface,
- fitContent,
+ composeSpatialMaps,
+ mapIntrinsicExtentBounds,
+ mapSpatialFrameBounds,
+ mapSpatialFramePath,
+ mapSpatialPoint,
frameFromEdges,
+ resolveContentFit,
sealSpatialPath,
spatialComponent,
spatialManifest,
@@ -32,7 +36,7 @@ import {
spatialProducers,
spatialTypes,
} from "../src/index.js";
-import type { ContentFit, IntrinsicExtent, SpatialAnchor, SpatialFrame, SpatialRegionTimeline } from "../src/index.js";
+import type { ContentFit, IntrinsicExtent, SpatialAnchor, SpatialFrame } from "../src/index.js";
const parent: SpatialFrame = { xPx: 100, yPx: 200, widthPx: 800, heightPx: 1200 };
const portrait: IntrinsicExtent = { widthPx: 600, heightPx: 1000 };
@@ -42,6 +46,8 @@ const centered = (sizing: ContentFit["sizing"], constraint: ContentFit["constrai
framePoint: { x: 0.5, y: 0.5 }, contentPoint: { x: 0.5, y: 0.5 },
offsetPx: { x: 0, y: 0 }, constraint,
});
+const fittedBounds = (frame: SpatialFrame, extent: IntrinsicExtent, fit: ContentFit): SpatialFrame =>
+ mapIntrinsicExtentBounds(extent, resolveContentFit(frame, extent, fit));
test("Frame edges and anchored Frames resolve percentages against the explicit parent", () => {
assert.deepEqual(frameFromEdges(parent, {
@@ -79,19 +85,30 @@ test("AspectFrame preserves explicit or connected aspect without becoming Media"
}), { xPx: 660, yPx: 1000, widthPx: 240, heightPx: 400 });
});
-test("every ContentFit sizing mode resolves the independent Content Frame", () => {
+test("every ContentFit sizing mode resolves one source-to-picture mapping", () => {
const frame: SpatialFrame = { xPx: 0, yPx: 0, widthPx: 400, heightPx: 400 };
- assert.deepEqual(fitContent(frame, landscape, centered("contain")).contentFrame,
+ assert.deepEqual(fittedBounds(frame, landscape, centered("contain")),
{ xPx: 0, yPx: 87.5, widthPx: 400, heightPx: 225 });
- assert.deepEqual(fitContent(frame, landscape, centered("cover")).contentFrame,
+ assert.deepEqual(fittedBounds(frame, landscape, centered("cover")),
{ xPx: -155.55555555555554, yPx: 0, widthPx: 711.1111111111111, heightPx: 400 });
- assert.equal(fitContent(frame, portrait, centered("fit-width")).contentFrame.heightPx, 666.6666666666666);
- assert.equal(fitContent(frame, portrait, centered("fit-height")).contentFrame.widthPx, 240);
- assert.deepEqual(fitContent(frame, portrait, centered("native")).contentFrame,
+ assert.ok(Math.abs(fittedBounds(frame, portrait, centered("fit-width")).heightPx - 666.6666666666666) < 1e-9);
+ assert.equal(fittedBounds(frame, portrait, centered("fit-height")).widthPx, 240);
+ assert.deepEqual(fittedBounds(frame, portrait, centered("native")),
{ xPx: -100, yPx: -300, widthPx: 600, heightPx: 1000 });
- assert.deepEqual(fitContent({ ...frame, widthPx: 800, heightPx: 1200 }, portrait, centered("scale-down")).contentFrame,
+ assert.deepEqual(fittedBounds({ ...frame, widthPx: 800, heightPx: 1200 }, portrait, centered("scale-down")),
{ xPx: 100, yPx: 100, widthPx: 600, heightPx: 1000 });
- assert.deepEqual(fitContent(frame, portrait, centered("stretch")).contentFrame, frame);
+ assert.deepEqual(fittedBounds(frame, portrait, centered("stretch")), frame);
+});
+
+test("SpatialMap2D composes local geometry without attaching Canvas identity", () => {
+ const rotateQuarter = { xx: 0, xy: -1, yx: 1, yy: 0, tx: 0, ty: 0 };
+ const translate = { xx: 1, xy: 0, yx: 0, yy: 1, tx: 100, ty: 200 };
+ const mapping = composeSpatialMaps(rotateQuarter, translate);
+ assert.deepEqual(mapSpatialPoint({ xPx: 10, yPx: 20 }, mapping), { xPx: 80, yPx: 210 });
+ assert.deepEqual(mapSpatialFrameBounds({ xPx: 0, yPx: 0, widthPx: 30, heightPx: 20 }, mapping),
+ { xPx: 80, yPx: 200, widthPx: 20, heightPx: 30 });
+ assert.deepEqual(mapSpatialFramePath({ xPx: 0, yPx: 0, widthPx: 30, heightPx: 20 }, mapping).commands[1],
+ { kind: "line", xPx: 100, yPx: 230 });
});
test("the complete aspect, sizing and equal-point matrix preserves the two-frame equations", () => {
@@ -113,7 +130,7 @@ test("the complete aspect, sizing and equal-point matrix preserves the two-frame
for (const frame of frames) {
for (const extent of extents) {
for (const sizing of sizings) {
- const content = fitContent(frame, extent, centered(sizing)).contentFrame;
+ const content = fittedBounds(frame, extent, centered(sizing));
close(content.xPx + content.widthPx / 2, frame.xPx + frame.widthPx / 2, `${sizing} center x`);
close(content.yPx + content.heightPx / 2, frame.yPx + frame.heightPx / 2, `${sizing} center y`);
if (sizing !== "stretch") {
@@ -148,10 +165,10 @@ test("the complete aspect, sizing and equal-point matrix preserves the two-frame
const points = [0, 0.5, 1] as const;
for (const x of points) {
for (const y of points) {
- const content = fitContent(frame, extent, {
+ const content = fittedBounds(frame, extent, {
sizing: "native",
framePoint: { x, y }, contentPoint: { x, y }, offsetPx: { x: 0, y: 0 }, constraint: "bounded",
- }).contentFrame;
+ });
close(content.xPx + content.widthPx * x, frame.xPx + frame.widthPx * x, `equal point ${x},${y} x`);
close(content.yPx + content.heightPx * y, frame.yPx + frame.heightPx * y, `equal point ${x},${y} y`);
}
@@ -165,8 +182,8 @@ test("unequal focal points and bounded/free policies remain explicit", () => {
framePoint: { x: 0.5, y: 0.5 }, contentPoint: { x: 0.8, y: 0.35 },
offsetPx: { x: 20, y: -10 }, constraint: "free",
};
- const free = fitContent(frame, landscape, fit).contentFrame;
- const bounded = fitContent(frame, landscape, { ...fit, constraint: "bounded" }).contentFrame;
+ const free = fittedBounds(frame, landscape, fit);
+ const bounded = fittedBounds(frame, landscape, { ...fit, constraint: "bounded" });
assert.ok(Math.abs(free.xPx - (-196.66666666666666)) < 1e-9);
assert.ok(Math.abs(free.widthPx - 533.3333333333333) < 1e-9);
assert.deepEqual([free.yPx, free.heightPx], [55, 300]);
@@ -195,8 +212,8 @@ function source(text: string): AuthorSourceUnit {
return { id: "/project/main.svml", name: "main.svml", text: `<?svml using="@hypit/markup@1"?>\n${text}` };
}
-test("self-described Spatial Surfaces produce explicit static geometry and measured Region data", async () => {
- const closure = createResolvedClosure([spatialManifest, svsManifest]);
+test("self-described Spatial Surfaces produce explicit static geometry", async () => {
+ const closure = createResolvedClosure([spatialManifest]);
const surfaces = new MarkupSurfaceRegistry();
const register = (name: string, handler: Parameters<MarkupSurfaceRegistry["registerStructured"]>[0]["handler"]) => {
const declaration = spatialMarkupSurfaces.find((item) => item.name === name);
@@ -206,67 +223,44 @@ test("self-described Spatial Surfaces produce explicit static geometry and measu
register("canvas", decodeCanvasSurface);
register("point", decodePointSurface);
register("path", decodePathSurface);
- register("region-timeline", decodeRegionTimelineSurface);
+ register("map", decodeMapSurface);
register("frame", decodeFrameSurface);
register("anchored-frame", decodeAnchoredFrameSurface);
register("aspect-frame", decodeAspectFrameSurface);
const frontends = new AuthorFrontendRegistry();
frontends.register(createMarkupAuthorFrontend({ registry: surfaces, resolveModule: () => spatialModuleRef }));
- frontends.register(svsFrontend);
const validators = new TypeValidatorRegistry();
registerTypeValidatorFacets(validators, spatialComponent.validators ?? []);
const compiled = await compileSourceClosure({
entry: source(`<svml>
<import as="space" from="@hypit/spatial@1"/>
- <import as="tracking" source="./tracking.svs"/>
<space:Canvas id="vertical" width="1080" height="1920"/>
- <space:RegionTimeline id="heads" within={vertical} recipe={tracking.heads.default}/>
<space:Point id="headline-origin" x="120" y="280"/>
<space:Path id="headline-path">
<space:Move x="120" y="280"/>
<space:Cubic control1-x="360" control1-y="180" control2-x="720" control2-y="380" x="960" y="280"/>
</space:Path>
- <space:Frame id="safe" within={vertical} left="6%" top="4%" right="94%" bottom="96%"/>
+ <space:Map id="turned" xx="0" xy="-0.5" yx="0.5" yy="0" tx="920" ty="180"/>
+ <space:Frame id="safe" within={vertical.bounds} left="6%" top="4%" right="94%" bottom="96%"/>
<space:AnchoredFrame id="card" within={safe} x="50%" y="78%" width="82%" height="28%" anchor="center"/>
<space:AspectFrame id="sticker" within={safe} x="100%" y="100%" width="32%" aspect="9/16" anchor="bottom-right"/>
</svml>`),
closure,
frontends,
admitRecord: createRecordAdmitter(validators),
- resolveSource(_importer, request) {
- if (request.from !== "./tracking.svs") throw new Error(`unknown Spatial fixture source ${request.from}`);
- return {
- id: "/project/tracking.svs",
- name: "tracking.svs",
- text: `<?svml using="@hypit/svs@1"?>
-<sheet version="1">
-heads.default {
- frame-count: 3;
- tracks: [{"id":"BOY","regions":[[0.5,0.1,0.2,0.3],null,[0.52,0.11,0.2,0.3]]}];
-}
-</sheet>`,
- };
- },
+ resolveSource() { throw new Error("Spatial fixture imports no Source files."); },
});
- assert.equal(resolveCompiledSourceExport(compiled, "vertical", spatialTypes.canvas).ref.kind, "record");
+ assert.equal(resolveCompiledSourceExport(compiled, "vertical.canvas", spatialTypes.canvas).ref.kind, "record");
+ assert.equal(resolveCompiledSourceExport(compiled, "vertical.bounds", spatialTypes.frame).ref.kind, "record");
assert.equal(resolveCompiledSourceExport(compiled, "headline-origin", spatialTypes.point).ref.kind, "record");
assert.equal(resolveCompiledSourceExport(compiled, "headline-path", spatialTypes.path).ref.kind, "record");
- const regions = resolveCompiledSourceExport(compiled, "heads", spatialTypes.regionTimeline);
- assert.equal(regions.ref.kind, "record");
- const regionRecord = compiled.program.records.find((record) =>
- regions.ref.kind === "record" && record.id === regions.ref.id);
- const timeline = regionRecord?.value.kind === "inline"
- ? regionRecord.value.value as unknown as SpatialRegionTimeline
- : undefined;
- assert.deepEqual(timeline?.tracks[0]?.frames[0], { xPx: 540, yPx: 192, widthPx: 216, heightPx: 576 });
- assert.equal(timeline?.tracks[0]?.frames[1], null);
+ assert.equal(resolveCompiledSourceExport(compiled, "turned", spatialTypes.map2D).ref.kind, "record");
const sticker = resolveCompiledSourceExport(compiled, "sticker", spatialTypes.frame);
assert.equal(sticker.ref.kind, "logical-output");
const build = start(compiled.program, compiled.graph, sealBuildRequest({
targets: [{ output: sticker.ref.kind === "logical-output" ? sticker.ref.id : "" }],
}));
assert.deepEqual(build.plan.steps.map((step) => step.producer.name).sort(), [
- spatialProducers.canvasFrame.name,
spatialProducers.frameEdges.name,
spatialProducers.aspectFrame.name,
].sort());
diff --git a/packages/speech-alignment/README.md b/packages/speech-alignment/README.md
index 8f8498f9..caa0793e 100644
--- a/packages/speech-alignment/README.md
+++ b/packages/speech-alignment/README.md
@@ -1,29 +1,38 @@
# `@hypit/speech-alignment`
-Provider-neutral deterministic timing locator for one normalized Segment Take. The package does not
+Provider-neutral deterministic timing locator for one authored Segment on a normalized local temporal
+domain. The package does not
invoke Python, read audio, call a speech provider, use an LLM, infer speakers or retain multiple
candidate paths. A runtime adapter preserves its raw provider artifact and supplies the normalized
word, character, score and speech-activity evidence used here in exact 16 kHz sample coordinates.
-The locator aligns one explicitly connected Script Segment against the acoustic evidence from that
-same normalized Take. A bounded monotonic M:N dynamic
+The locator aligns one explicitly connected Script Segment against acoustic evidence carrying that
+same local domain identity and exact evidence sample span. A bounded monotonic M:N dynamic
program accepts exact, split, merge, replacement, source-omission and evidence-insertion groups.
Within a selected group, timed evidence characters determine Script token boundaries; word times
and speech-activity bounds are fallbacks. Missing token runs receive continuous weighted windows
between their measured neighbors instead of invented point timestamps. The result is quantized once
-into the Take's local frame domain and contains one timing for every Script token plus the Segment
-and token boundary anchors. Segment anchors are exactly frame `0` and the Take frame count.
+into the supplied local frame domain and contains one timing for every Script token plus the Segment
+and token boundaries. Segment boundaries are exactly frame `0` and the local domain frame count.
-The public Producer accepts Narrative, one Segment excerpt, `SynchronizedMedia` and
-`AlignedTranscriptEvidence` through explicit graph edges. Evidence carries no authored Segment
-identity; the deterministic semantic step performs that association locally.
+The public Producer accepts Narrative, one Segment excerpt, its `LocalTemporalDomain` and
+`AlignedTranscriptEvidence` through explicit graph edges. It does not reopen `SynchronizedMedia` to
+recover audio or duration. Evidence carries the measured domain identity and sample span but no
+authored Segment identity; the deterministic semantic step performs that association locally and
+rejects a mismatched domain or span.
-`speechAlignmentComponent` exposes this Segment-local projection as one enumerable deterministic Producer facet. Its
+`speechAlignmentComponent` exposes this Segment-local alignment as one enumerable deterministic Producer facet. Its
identity is checked against `speechAlignmentManifest` and executes through the host-neutral compute
-port. The package depends only on public video
-contracts and protocol utilities; it has no Core, Driver, Provider, Artifact, queue or credential
+port. The package depends only on Narrative, Temporal and provider-neutral Evidence
+contracts plus protocol utilities; it has no Media, Core, Driver, Provider, Artifact, queue or credential
authority.
-Caption display is outside this package. `@hypit/caption` composes the resulting complete speech
-map with Script's explicit whole-Atom `CaptionCorrespondence`; it never asks this locator to infer
-display text or display-Word timing.
+Caption display is outside this package. `@hypit/narrative-caption` combines an independently owned
+Caption document/binding with the resulting Narrative timing; it never asks this locator to infer
+display text or display-unit timing.
+
+The result is the `@hypit/narrative-temporal` `NarrativeAlignment`, not media and not a Timeline.
+An explicit Narrative Projection from that package later combines one or more
+`NarrativeAlignment + LocalTemporalDomain + equal-length Window` relations for a chosen Timeline. Visual,
+audio and caption consumers then request absolute Instants or Windows through that declared relation;
+Timeline and Core do not enumerate semantic event kinds.
diff --git a/packages/speech-alignment/package.json b/packages/speech-alignment/package.json
index 41d4f76f..50379b2f 100644
--- a/packages/speech-alignment/package.json
+++ b/packages/speech-alignment/package.json
@@ -12,12 +12,11 @@
},
"dependencies": {
"@hypit/component-kit": "workspace:*",
- "@hypit/media": "workspace:*",
"@hypit/narrative": "workspace:*",
- "@hypit/program-space": "workspace:*",
+ "@hypit/narrative-temporal": "workspace:*",
"@hypit/protocol": "workspace:*",
- "@hypit/speech": "workspace:*",
- "@hypit/speech-evidence": "workspace:*"
+ "@hypit/speech-evidence": "workspace:*",
+ "@hypit/temporal": "workspace:*"
},
"devDependencies": {
"@hypit/script": "workspace:*"
diff --git a/packages/speech-alignment/src/component.ts b/packages/speech-alignment/src/component.ts
index a03c20a9..37799322 100644
--- a/packages/speech-alignment/src/component.ts
+++ b/packages/speech-alignment/src/component.ts
@@ -1,11 +1,11 @@
import type { ComponentPackage } from "@hypit/component-kit";
-import type { SynchronizedMedia } from "@hypit/media";
import type { Narrative, NarrativeExcerpt } from "@hypit/narrative";
-import type { AlignedTranscriptEvidence } from "@hypit/speech-evidence";
import type { StoredValue } from "@hypit/protocol";
import { canonicalize } from "@hypit/protocol";
+import type { AlignedTranscriptEvidence } from "@hypit/speech-evidence";
+import type { LocalTemporalDomain } from "@hypit/temporal";
-import { alignSemanticTake } from "./local.js";
+import { alignNarrative } from "./local.js";
import { speechAlignmentProducers } from "./manifest.js";
function inline<T>(value: StoredValue | undefined, subject: string): T {
@@ -13,25 +13,19 @@ function inline<T>(value: StoredValue | undefined, subject: string): T {
return value.value as T;
}
-/** Provider-neutral deterministic alignment; acoustic measurement remains an explicit upstream Need. */
export const speechAlignmentComponent = {
- producers: [
- {
- producer: speechAlignmentProducers.alignTake,
- handler: ({ inputs }) => ({
- outputs: {
- take: {
- kind: "inline",
- value: canonicalize(alignSemanticTake(
- inline<Narrative>(inputs.narrative?.value, "Narrative"),
- inline<NarrativeExcerpt>(inputs.segment?.value, "NarrativeExcerpt"),
- inline<SynchronizedMedia>(inputs.media?.value, "SynchronizedMedia"),
- inline<AlignedTranscriptEvidence>(inputs.evidence?.value, "AlignedTranscriptEvidence"),
- )),
- },
- },
- needs: {},
- }),
+ producers: [{
+ producer: speechAlignmentProducers.alignNarrative,
+ handler: ({ inputs }) => {
+ const result = alignNarrative(
+ inline<Narrative>(inputs.narrative?.value, "Narrative"),
+ inline<NarrativeExcerpt>(inputs.segment?.value, "NarrativeExcerpt"),
+ inline<LocalTemporalDomain>(inputs.domain?.value, "LocalTemporalDomain"),
+ inline<AlignedTranscriptEvidence>(inputs.evidence?.value, "AlignedTranscriptEvidence"),
+ );
+ return { outputs: {
+ alignment: { kind: "inline", value: canonicalize(result) },
+ }, needs: {} };
},
- ],
+ }],
} satisfies ComponentPackage;
diff --git a/packages/speech-alignment/src/index.ts b/packages/speech-alignment/src/index.ts
index b78d9d2f..9e273f3c 100644
--- a/packages/speech-alignment/src/index.ts
+++ b/packages/speech-alignment/src/index.ts
@@ -1,7 +1,8 @@
export { alignWordGroups } from "./align.js";
export { speechAlignmentComponent } from "./component.js";
export { SpeechAlignmentError } from "./error.js";
-export { alignSemanticTake } from "./local.js";
-export { speechAlignmentManifest, speechAlignmentModuleRef, speechAlignmentProducers } from "./manifest.js";
+export { alignNarrative } from "./local.js";
+export { materializeNarrativeAlignment } from "./materialize.js";
+export { speechAlignmentDependency, speechAlignmentManifest, speechAlignmentModuleRef, speechAlignmentProducers } from "./manifest.js";
export { alignCharacters, alignmentCharacters, normalizeForAlignment } from "./normalize.js";
export type * from "./types.js";
diff --git a/packages/speech-alignment/src/local.ts b/packages/speech-alignment/src/local.ts
index 7bcce6b6..e291bbe6 100644
--- a/packages/speech-alignment/src/local.ts
+++ b/packages/speech-alignment/src/local.ts
@@ -1,72 +1,49 @@
-import type { SynchronizedMedia } from "@hypit/media";
import type { Narrative, NarrativeExcerpt } from "@hypit/narrative";
-import { sealProgramSpace } from "@hypit/program-space";
-import { materializeSemanticTake } from "@hypit/speech";
-import type { SemanticTake } from "@hypit/speech";
+import type { NarrativeAlignment } from "@hypit/narrative-temporal";
import type { AlignedTranscriptEvidence } from "@hypit/speech-evidence";
+import type { LocalTemporalDomain } from "@hypit/temporal";
import { locateAlignedSegmentTiming } from "./locate.js";
+import { materializeNarrativeAlignment } from "./materialize.js";
import type { AlignmentBasis } from "./locate.js";
function segmentNarrative(narrative: Narrative, excerpt: NarrativeExcerpt): Narrative {
- if (excerpt.kind !== "segment") throw new Error("SemanticTake alignment requires a Segment excerpt.");
+ if (excerpt.kind !== "segment") throw new Error("Narrative alignment requires a Segment excerpt.");
const segment = narrative.segments.find((candidate) => candidate.id === excerpt.id);
if (segment === undefined) throw new Error(`Narrative does not contain Segment ${excerpt.id}.`);
if (excerpt.tokenStart !== segment.tokenStart || excerpt.tokenEndExclusive !== segment.tokenEndExclusive) {
throw new Error(`NarrativeExcerpt ${excerpt.id} does not describe its authored Segment.`);
}
const tokens = narrative.tokens.slice(segment.tokenStart, segment.tokenEndExclusive);
- const units = narrative.caption.units.filter((unit) => unit.segmentId === segment.id);
- const unitIds = new Set(units.map((unit) => unit.id));
return {
id: narrative.id,
- caption: {
- ...narrative.caption,
- units,
- words: narrative.caption.words.filter((word) => unitIds.has(word.unitId)),
- cueBreaks: narrative.caption.cueBreaks.filter((cue) => unitIds.has(cue.afterUnitId)),
- },
segments: [{ ...segment, tokenStart: 0, tokenEndExclusive: tokens.length }],
tokens,
- turns: narrative.turns
- .filter((turn) => turn.segmentId === segment.id)
- .map((turn) => ({
- ...turn,
- tokenStart: turn.tokenStart - segment.tokenStart,
- tokenEndExclusive: turn.tokenEndExclusive - segment.tokenStart,
- })),
- selections: [],
- moments: [],
- semanticIndex: {
- anchors: narrative.semanticIndex.anchors.filter((anchor) => anchor.segmentId === segment.id),
- },
+ turns: narrative.turns.filter((turn) => turn.segmentId === segment.id).map((turn) => ({ ...turn,
+ tokenStart: turn.tokenStart - segment.tokenStart, tokenEndExclusive: turn.tokenEndExclusive - segment.tokenStart })),
+ selections: [], moments: [],
+ semanticIndex: { anchors: narrative.semanticIndex.anchors.filter((anchor) => anchor.segmentId === segment.id) },
};
}
-/** Align one normalized Take independently, then materialize its local semantic product. */
-export function alignSemanticTake(
+/** Align one normalized source locally without turning media into a semantic aggregate. */
+export function alignNarrative(
narrative: Narrative,
excerpt: NarrativeExcerpt,
- media: SynchronizedMedia,
+ domain: LocalTemporalDomain,
evidence: AlignedTranscriptEvidence,
-): SemanticTake {
- if (media.audio === undefined) throw new Error(`SemanticTake ${excerpt.id} has no normalized audio.`);
+): NarrativeAlignment {
const localNarrative = segmentNarrative(narrative, excerpt);
- const programSpace = sealProgramSpace({
- id: `${excerpt.narrativeId}.segment.${excerpt.id}`,
- durationSec: media.timeline.frameCount * media.timeline.frameRate.denominator
- / media.timeline.frameRate.numerator,
- frameRate: media.timeline.frameRate,
- });
+ if (evidence.domainId !== domain.id) {
+ throw new Error(`Narrative alignment ${excerpt.id} evidence belongs to another local domain.`);
+ }
const basis: AlignmentBasis = {
- programSpace,
- audio: media.audio.artifact,
- segments: [{ segmentId: excerpt.id, startFrame: 0, endFrameExclusive: media.timeline.frameCount }],
+ domainId: domain.id,
+ frameDomain: { frameRate: domain.frameRate, frameCount: domain.frameCount },
+ segments: [{ segmentId: excerpt.id, startFrame: 0, endFrameExclusive: domain.frameCount }],
};
const timing = locateAlignedSegmentTiming(localNarrative, basis, evidence);
- return materializeSemanticTake(localNarrative, {
- ...excerpt,
- tokenStart: 0,
- tokenEndExclusive: localNarrative.tokens.length,
- }, media, timing);
+ return materializeNarrativeAlignment(localNarrative, {
+ ...excerpt, tokenStart: 0, tokenEndExclusive: localNarrative.tokens.length,
+ }, domain, timing);
}
diff --git a/packages/speech-alignment/src/locate.ts b/packages/speech-alignment/src/locate.ts
index dea234d0..39fc5b1b 100644
--- a/packages/speech-alignment/src/locate.ts
+++ b/packages/speech-alignment/src/locate.ts
@@ -1,9 +1,5 @@
-import { isResourceId } from "@hypit/protocol";
-import type { BlobRef } from "@hypit/protocol";
import type { Narrative, NarrativeToken } from "@hypit/narrative";
-import { programFrameSampleBoundary, programSpaceFrameCount } from "@hypit/program-space";
-import type { ProgramSpace } from "@hypit/program-space";
-import type { SemanticTakeTimedToken, SemanticTakeTiming } from "@hypit/speech";
+import type { NarrativeAlignmentTiming } from "./types.js";
import type {
AlignedTranscriptEvidence,
SpeechActivitySpan,
@@ -17,14 +13,17 @@ import { SpeechAlignmentError } from "./error.js";
import { alignCharacters, alignmentCharacters } from "./normalize.js";
import type { AlignmentGroup, TimedSpeechSegment } from "./types.js";
-export type LocalTimedSpeechToken = SemanticTakeTimedToken;
-export type LocalSemanticTimePoint = SemanticTakeTiming["anchors"][number];
-export type LocalSemanticTiming = SemanticTakeTiming;
+export type LocalTimedSpeechToken = NarrativeAlignmentTiming["tokens"][number];
+export type LocalSemanticTimePoint = NarrativeAlignmentTiming["boundaries"][number];
+export type LocalSemanticTiming = NarrativeAlignmentTiming;
/** Package-private clock used while aligning exactly one normalized Segment Take. */
export type AlignmentBasis = {
- readonly programSpace: ProgramSpace;
- readonly audio: BlobRef;
+ readonly domainId: string;
+ readonly frameDomain: {
+ readonly frameRate: { readonly numerator: number; readonly denominator: number };
+ readonly frameCount: number;
+ };
readonly segments: readonly [{
readonly segmentId: string;
readonly startFrame: 0;
@@ -32,6 +31,17 @@ export type AlignmentBasis = {
}];
};
+function alignmentFrameSampleBoundary(basis: AlignmentBasis, frame: number): number {
+ if (!Number.isSafeInteger(frame) || frame < 0 || frame > basis.frameDomain.frameCount) {
+ fail("SPEECH_FRAME", "Speech frame boundary is outside normalized media.");
+ }
+ const numerator = BigInt(frame) * 16_000n * BigInt(basis.frameDomain.frameRate.denominator);
+ const denominator = BigInt(basis.frameDomain.frameRate.numerator);
+ const value = (numerator * 2n + denominator) / (denominator * 2n);
+ if (value > BigInt(Number.MAX_SAFE_INTEGER)) fail("SPEECH_FRAME", "Speech sample domain exceeds safe arithmetic.");
+ return Number(value);
+}
+
type MutableTiming = {
startSample: number;
endSampleExclusive: number;
@@ -82,24 +92,16 @@ function validateSampleWindow(
}
function evidenceSampleFrames(basis: AlignmentBasis): number {
- return programFrameSampleBoundary(
- basis.programSpace,
- programSpaceFrameCount(basis.programSpace),
- 16_000,
- );
+ return alignmentFrameSampleBoundary(basis, basis.frameDomain.frameCount);
}
function validateBasis(narrative: Narrative, basis: AlignmentBasis): void {
- const { numerator, denominator } = basis.programSpace.frameRate;
+ const { numerator, denominator } = basis.frameDomain.frameRate;
if (!Number.isSafeInteger(numerator) || numerator <= 0
|| !Number.isSafeInteger(denominator) || denominator <= 0) {
- fail("SPEECH_FRAME_RATE", "ProgramSpace frame rate must be a positive rational number.");
- }
- const frameCount = programSpaceFrameCount(basis.programSpace);
- if (basis.audio.kind !== "blob" || !isResourceId(basis.audio.resource)
- || basis.audio.mediaType !== "audio/wav" || !Number.isSafeInteger(basis.audio.size) || basis.audio.size < 0) {
- fail("SPEECH_AUDIO_DIGEST", "Speech alignment audio BlobRef is invalid.");
+ fail("SPEECH_FRAME_RATE", "Timeline frame rate must be a positive rational number.");
}
+ const frameCount = basis.frameDomain.frameCount;
if (narrative.segments.length !== 1 || basis.segments.length !== 1) {
fail("SPEECH_BASIS_SEGMENTS", "Speech alignment accepts exactly one normalized Segment Take.");
}
@@ -117,12 +119,18 @@ function validateBasis(narrative: Narrative, basis: AlignmentBasis): void {
previousEnd = segment.endFrameExclusive;
}
if (previousEnd !== frameCount) {
- fail("SPEECH_BASIS_SEGMENTS", "Alignment Segments must cover ProgramSpace exactly.");
+ fail("SPEECH_BASIS_SEGMENTS", "Alignment Segments must cover Timeline exactly.");
}
}
function validateEvidence(basis: AlignmentBasis, evidence: AlignedTranscriptEvidence): void {
const limit = evidenceSampleFrames(basis);
+ if (evidence.domainId !== basis.domainId) {
+ fail("SPEECH_EVIDENCE_DOMAIN", "Aligned transcript evidence belongs to another local domain.");
+ }
+ if (evidence.sampleFrames !== limit) {
+ fail("SPEECH_EVIDENCE_SPAN", "Aligned transcript evidence sample span differs from its local frame domain.");
+ }
for (const [passageIndex, passage] of evidence.passages.entries()) {
validateSampleWindow(passage, limit, `Passage ${passageIndex + 1}`);
for (const [wordIndex, word] of passage.words.entries()) {
@@ -157,8 +165,8 @@ function partitionEvidence(
): readonly SegmentEvidence[] {
const ranges = basis.segments.map((segment) => ({
segment,
- startSample: programFrameSampleBoundary(basis.programSpace, segment.startFrame, 16_000),
- endSampleExclusive: programFrameSampleBoundary(basis.programSpace, segment.endFrameExclusive, 16_000),
+ startSample: alignmentFrameSampleBoundary(basis, segment.startFrame),
+ endSampleExclusive: alignmentFrameSampleBoundary(basis, segment.endFrameExclusive),
}));
const buckets = ranges.map(({ segment }) => ({
sourceSegmentId: segment.segmentId,
@@ -342,8 +350,8 @@ function speechBounds(
end: Math.max(...spans.map((span) => span.endSampleExclusive)),
}
: {
- start: programFrameSampleBoundary(basis.programSpace, basisSegment.startFrame, 16_000),
- end: programFrameSampleBoundary(basis.programSpace, basisSegment.endFrameExclusive, 16_000),
+ start: alignmentFrameSampleBoundary(basis, basisSegment.startFrame),
+ end: alignmentFrameSampleBoundary(basis, basisSegment.endFrameExclusive),
};
}
@@ -382,16 +390,16 @@ function fillMissingTiming(
}
function floorFrameForEvidenceSample(basis: AlignmentBasis, sample: number): number {
- const numerator = BigInt(sample) * BigInt(basis.programSpace.frameRate.numerator);
- const denominator = 16_000n * BigInt(basis.programSpace.frameRate.denominator);
+ const numerator = BigInt(sample) * BigInt(basis.frameDomain.frameRate.numerator);
+ const denominator = 16_000n * BigInt(basis.frameDomain.frameRate.denominator);
const frame = numerator / denominator;
if (frame > BigInt(Number.MAX_SAFE_INTEGER)) fail("SPEECH_FRAME", "Speech evidence exceeds the frame domain.");
return Number(frame);
}
function ceilFrameForEvidenceSample(basis: AlignmentBasis, sample: number): number {
- const numerator = BigInt(sample) * BigInt(basis.programSpace.frameRate.numerator);
- const denominator = 16_000n * BigInt(basis.programSpace.frameRate.denominator);
+ const numerator = BigInt(sample) * BigInt(basis.frameDomain.frameRate.numerator);
+ const denominator = 16_000n * BigInt(basis.frameDomain.frameRate.denominator);
const frame = (numerator + denominator - 1n) / denominator;
if (frame > BigInt(Number.MAX_SAFE_INTEGER)) fail("SPEECH_FRAME", "Speech evidence exceeds the frame domain.");
return Number(frame);
@@ -402,7 +410,7 @@ function projectSampleTiming(
basis: AlignmentBasis,
timing: MutableTiming,
): { readonly startFrame: number; readonly endFrameExclusive: number } {
- const frameCount = programSpaceFrameCount(basis.programSpace);
+ const frameCount = basis.frameDomain.frameCount;
const startFrame = Math.min(frameCount, floorFrameForEvidenceSample(basis, timing.startSample));
const endFrameExclusive = Math.min(
frameCount,
@@ -455,19 +463,17 @@ export function locateAlignedSegmentTiming(
const tokensById = new Map(timedTokens.map((token) => [token.tokenId, token]));
const segmentsById = new Map(timedSegments.map((segment) => [segment.segmentId, segment]));
- const anchors: LocalSemanticTimePoint[] = narrative.semanticIndex.anchors.flatMap((anchor): LocalSemanticTimePoint[] => {
- // Program boundaries belong to the assembled Timeline, never to one Segment-local Take.
- if (anchor.kind === "program-start" || anchor.kind === "program-end") return [];
+ const boundaries: LocalSemanticTimePoint[] = narrative.semanticIndex.anchors.flatMap((anchor): LocalSemanticTimePoint[] => {
if (anchor.kind === "segment-start" || anchor.kind === "segment-end") {
const segment = segmentsById.get(anchor.segmentId)!;
return [anchor.kind === "segment-start"
- ? { identity: anchor.id, frame: segment.startFrame }
- : { identity: anchor.id, frame: segment.endFrameExclusive }];
+ ? { id: anchor.id, frame: segment.startFrame }
+ : { id: anchor.id, frame: segment.endFrameExclusive }];
}
const token = tokensById.get(anchor.tokenId!)!;
return [anchor.kind === "token-start"
- ? { identity: anchor.id, frame: token.startFrame }
- : { identity: anchor.id, frame: token.endFrameExclusive }];
+ ? { id: anchor.id, frame: token.startFrame }
+ : { id: anchor.id, frame: token.endFrameExclusive }];
});
- return { tokens: timedTokens, anchors };
+ return { tokens: timedTokens, boundaries };
}
diff --git a/packages/speech-alignment/src/manifest.ts b/packages/speech-alignment/src/manifest.ts
index c0cb6ce7..b2a0d982 100644
--- a/packages/speech-alignment/src/manifest.ts
+++ b/packages/speech-alignment/src/manifest.ts
@@ -1,37 +1,24 @@
-import { mediaDependency, mediaTypes } from "@hypit/media";
import { narrativeDependency, narrativeTypes } from "@hypit/narrative";
-import { speechDependency, speechTypes } from "@hypit/speech";
+import { narrativeTemporalDependency, narrativeTemporalTypes } from "@hypit/narrative-temporal";
import { speechEvidenceDependency, speechEvidenceTypes } from "@hypit/speech-evidence";
+import { temporalDependency, temporalTypes } from "@hypit/temporal";
import type { ModuleManifest, ProducerRef } from "@hypit/protocol";
export const speechAlignmentModuleRef = { name: "@hypit/speech-alignment", version: "1" } as const;
export const speechAlignmentProducers = {
- alignTake: { module: speechAlignmentModuleRef, name: "align-semantic-take" },
+ alignNarrative: { module: speechAlignmentModuleRef, name: "align-narrative" },
} satisfies Record<string, ProducerRef>;
export const speechAlignmentManifest: ModuleManifest = {
- format: "hypit.module@1",
- name: speechAlignmentModuleRef.name,
- version: speechAlignmentModuleRef.version,
- dependencies: [
- mediaDependency,
- narrativeDependency,
- speechDependency,
- speechEvidenceDependency,
- ],
- types: [],
- capabilities: [],
- producers: [
- {
- name: speechAlignmentProducers.alignTake.name,
- inputs: [
- { name: "narrative", type: narrativeTypes.narrative },
- { name: "segment", type: narrativeTypes.excerpt },
- { name: "media", type: mediaTypes.synchronized },
- { name: "evidence", type: speechEvidenceTypes.alignedTranscript },
- ],
- outputs: [{ name: "take", type: speechTypes.semanticTake }],
- needs: [],
- },
- ],
+ format: "hypit.module@1", name: speechAlignmentModuleRef.name, version: speechAlignmentModuleRef.version,
+ dependencies: [narrativeDependency, narrativeTemporalDependency, speechEvidenceDependency, temporalDependency],
+ types: [], capabilities: [], producers: [{
+ name: speechAlignmentProducers.alignNarrative.name,
+ inputs: [{ name: "narrative", type: narrativeTypes.narrative }, { name: "segment", type: narrativeTypes.excerpt },
+ { name: "domain", type: temporalTypes.localDomain },
+ { name: "evidence", type: speechEvidenceTypes.alignedTranscript }],
+ outputs: [{ name: "alignment", type: narrativeTemporalTypes.narrativeAlignment }],
+ needs: [],
+ }],
};
+export const speechAlignmentDependency = { module: speechAlignmentModuleRef } as const;
diff --git a/packages/speech-alignment/src/materialize.ts b/packages/speech-alignment/src/materialize.ts
new file mode 100644
index 00000000..d2f52513
--- /dev/null
+++ b/packages/speech-alignment/src/materialize.ts
@@ -0,0 +1,50 @@
+import type { Narrative, NarrativeExcerpt } from "@hypit/narrative";
+import { sealNarrativeAlignment } from "@hypit/narrative-temporal";
+import type { NarrativeAlignment } from "@hypit/narrative-temporal";
+import { assertLocalTemporalDomain } from "@hypit/temporal";
+import type { LocalTemporalDomain } from "@hypit/temporal";
+
+import type { NarrativeAlignmentTiming } from "./types.js";
+
+function authoredSegment(narrative: Narrative, excerpt: NarrativeExcerpt): Narrative["segments"][number] {
+ if (narrative.id !== excerpt.narrativeId) throw new Error(`NarrativeExcerpt ${excerpt.id} belongs to another Narrative.`);
+ if (excerpt.kind !== "segment") throw new Error("NarrativeAlignment materialization requires a Segment excerpt.");
+ const segment = narrative.segments.find((candidate) => candidate.id === excerpt.id);
+ if (segment === undefined) throw new Error(`Narrative does not contain Segment ${excerpt.id}.`);
+ if (excerpt.tokenStart !== segment.tokenStart || excerpt.tokenEndExclusive !== segment.tokenEndExclusive) {
+ throw new Error(`NarrativeExcerpt ${excerpt.id} does not describe its authored Segment.`);
+ }
+ return segment;
+}
+
+function localFrame(frame: number, domain: LocalTemporalDomain, label: string): number {
+ if (!Number.isSafeInteger(frame) || frame < 0 || frame > domain.frameCount) {
+ throw new Error(`${label} lies outside local domain ${domain.id}.`);
+ }
+ return frame;
+}
+
+export function materializeNarrativeAlignment(narrative: Narrative, excerpt: NarrativeExcerpt,
+ domain: LocalTemporalDomain, timing: NarrativeAlignmentTiming): NarrativeAlignment {
+ assertLocalTemporalDomain(domain);
+ const segment = authoredSegment(narrative, excerpt);
+ const timedById = new Map(timing.tokens.map((token) => [token.tokenId, token]));
+ const tokens = narrative.tokens.slice(segment.tokenStart, segment.tokenEndExclusive).map((token) => {
+ const timed = timedById.get(token.id);
+ if (timed === undefined || timed.segmentId !== segment.id) throw new Error(`Semantic timing does not locate Token ${token.id}.`);
+ const startFrame = localFrame(timed.startFrame, domain, `Token ${token.id}`);
+ const endFrameExclusive = localFrame(timed.endFrameExclusive, domain, `Token ${token.id}`);
+ if (endFrameExclusive <= startFrame) throw new Error(`Token ${token.id} has an empty or reversed frame window.`);
+ return { tokenId: token.id, segmentId: segment.id, text: token.text,
+ startBoundaryId: token.startAnchorId, endBoundaryId: token.endAnchorId };
+ });
+ const measuredById = new Map(timing.boundaries.map((boundary) => [boundary.id, boundary]));
+ const boundaries = narrative.semanticIndex.anchors.filter((anchor) => anchor.segmentId === segment.id).map((anchor) => {
+ const measured = measuredById.get(anchor.id);
+ if (measured === undefined) throw new Error(`Semantic timing does not locate Boundary ${anchor.id}.`);
+ return { id: anchor.id, frame: localFrame(measured.frame, domain, `Boundary ${anchor.id}`) };
+ });
+ return sealNarrativeAlignment({ narrativeId: narrative.id, domainId: domain.id,
+ segment: { segmentId: segment.id, startBoundaryId: segment.startAnchorId, endBoundaryId: segment.endAnchorId },
+ tokens, boundaries }, domain);
+}
diff --git a/packages/speech-alignment/src/types.ts b/packages/speech-alignment/src/types.ts
index 92d4054a..585493e8 100644
--- a/packages/speech-alignment/src/types.ts
+++ b/packages/speech-alignment/src/types.ts
@@ -5,7 +5,7 @@ export type {
SpeechTranscriptPassage,
SpeechWordEvidence,
} from "@hypit/speech-evidence";
-/** Private vocabulary of the alignment implementation, not part of SemanticTake. */
+/** Private vocabulary of the alignment implementation, not part of the public alignment value. */
export type AlignmentRelation =
| "exact"
| "split"
@@ -28,3 +28,14 @@ export type TimedSpeechSegment = {
readonly startFrame: number;
readonly endFrameExclusive: number;
};
+
+/** Private provider measurement resolved before publishing NarrativeAlignment. */
+export type NarrativeAlignmentTiming = {
+ readonly tokens: readonly {
+ readonly tokenId: string;
+ readonly segmentId: string;
+ readonly startFrame: number;
+ readonly endFrameExclusive: number;
+ }[];
+ readonly boundaries: readonly { readonly id: string; readonly frame: number }[];
+};
diff --git a/packages/speech-alignment/test/speech-align.test.ts b/packages/speech-alignment/test/speech-align.test.ts
index ebdab091..b2f1c7b0 100644
--- a/packages/speech-alignment/test/speech-align.test.ts
+++ b/packages/speech-alignment/test/speech-align.test.ts
@@ -1,16 +1,14 @@
import type { Narrative } from "@hypit/narrative";
-import { sealProgramSpace } from "@hypit/program-space";
-import { materializeSemanticTake } from "@hypit/speech";
import { sealAlignedTranscriptEvidence } from "@hypit/speech-evidence";
import type { AlignedTranscriptEvidence, SpeechCharacterEvidence, SpeechWordEvidence } from "@hypit/speech-evidence";
import assert from "node:assert/strict";
import test from "node:test";
-import { fixtureResource } from "../../../test/fixture-resource.js";
import { narrativeValue, parseScript as parseScriptSource } from "@hypit/script";
import {
SpeechAlignmentError,
alignWordGroups,
+ materializeNarrativeAlignment,
} from "@hypit/speech-alignment";
import { locateAlignedSegmentTiming } from "../src/locate.js";
import type { AlignmentBasis } from "../src/locate.js";
@@ -60,7 +58,10 @@ function evidence(args: {
readonly chars?: readonly SpeechCharacterEvidence[];
readonly vad?: readonly { readonly startSec: number; readonly endSec: number }[];
}): AlignedTranscriptEvidence {
+ const rate = args.basis.frameDomain.frameRate;
return sealAlignedTranscriptEvidence({
+ domainId: args.basis.domainId,
+ sampleFrames: Math.round(args.basis.frameDomain.frameCount * 16_000 * rate.denominator / rate.numerator),
passages: [
{
words: args.words.map(wordEvidence),
@@ -81,13 +82,10 @@ function speechBasis(
durationSec = 2,
): AlignmentBasis {
if (narrative.segments.length !== 1) throw new Error("Test alignment requires one Segment.");
- const programSpace = sealProgramSpace({ id: "test-space", durationSec,
- frameRate: { numerator: 1_000, denominator: 1 },
- });
- const audioDigest = fixtureResource(`fixture:audio:${narrative.segments.map((segment) => segment.id).join("+")}:${durationSec}`);
+ const frameDomain = { frameRate: { numerator: 1_000, denominator: 1 }, frameCount: Math.round(durationSec * 1_000) };
return {
- programSpace,
- audio: { kind: "blob", resource: audioDigest, size: 1, mediaType: "audio/wav" },
+ domainId: "test-domain",
+ frameDomain,
segments: [{
segmentId: narrative.segments[0]!.id,
startFrame: 0,
@@ -130,7 +128,7 @@ test("exact transcript words cover every Script and Segment anchor", () => {
});
assert.equal(map.tokens.length, 2);
- assert.equal(map.anchors.length, 2 * narrative.tokens.length + 2 * narrative.segments.length);
+ assert.equal(map.boundaries.length, 2 * narrative.tokens.length + 2 * narrative.segments.length);
assert.deepEqual(
map.tokens.map((token) => [token.startFrame, token.endFrameExclusive]),
[
@@ -138,10 +136,10 @@ test("exact transcript words cover every Script and Segment anchor", () => {
[500, 900],
],
);
- assert.equal(new Set(map.anchors.map((anchor) => anchor.identity)).size, map.anchors.length);
+ assert.equal(new Set(map.boundaries.map((boundary) => boundary.id)).size, map.boundaries.length);
});
-test("a measured Segment-local map becomes a self-contained SemanticTake", () => {
+test("a measured Segment-local map becomes a media-free NarrativeAlignment", () => {
const narrative = parseScript("materialize.svml", "<line>Hello world.</line>");
const basis = speechBasis(narrative, 2);
const map = locate(narrative, {
@@ -151,22 +149,17 @@ test("a measured Segment-local map becomes a self-contained SemanticTake", () =>
],
});
const segment = narrative.segments[0]!;
- const take = materializeSemanticTake(
+ const alignment = materializeNarrativeAlignment(
narrative,
{ narrativeId: narrative.id, kind: "segment", id: segment.id, tokenStart: segment.tokenStart, tokenEndExclusive: segment.tokenEndExclusive },
- {
- timeline: { frameRate: { numerator: 1_000, denominator: 1 }, frameCount: 2_000 },
- visual: { artifact: { kind: "blob", resource: fixtureResource("materialize:video"), size: 1, mediaType: "video/mp4" }, width: 720, height: 1280 },
- audio: { artifact: { kind: "blob", resource: fixtureResource("materialize:audio"), size: 1, mediaType: "audio/wav" } },
- },
+ { id: "speech-domain", frameRate: { numerator: 1_000, denominator: 1 }, frameCount: 2_000 },
map,
);
- assert.deepEqual(take.tokens.map((token) => [token.text, token.startFrame, token.endFrameExclusive]), [
- ["Hello", 100, 400],
- ["world", 500, 900],
- ]);
- assert.equal(take.segment.startFrame, 0);
- assert.equal(take.segment.endFrameExclusive, 2_000);
+ assert.deepEqual(alignment.tokens.map((token) => [token.text, token.startBoundaryId, token.endBoundaryId]),
+ narrative.tokens.map((token) => [token.text, token.startAnchorId, token.endAnchorId]));
+ assert.equal(alignment.boundaries.find((boundary) => boundary.id === segment.startAnchorId)?.frame, 0);
+ assert.equal(alignment.boundaries.find((boundary) => boundary.id === segment.endAnchorId)?.frame, 2_000);
+ assert.equal("media" in alignment, false);
});
test("M:1 uses evidence character times instead of dividing a merged word by length", () => {
@@ -326,12 +319,10 @@ test("a collapsed WhisperX word is assigned the available interval between its n
test("three Script words may share the two video frames covered by one evidence word", () => {
const narrative = parseScript("pigeonhole.svml", "<line>alpha beta gamma</line>");
const original = speechBasis(narrative, 1);
- const programSpace = sealProgramSpace({ id: "test-space", durationSec: 1,
- frameRate: { numerator: 32, denominator: 1 },
- });
+ const frameDomain = { frameRate: { numerator: 32, denominator: 1 }, frameCount: 32 };
const basis: AlignmentBasis = {
...original,
- programSpace,
+ frameDomain,
segments: [{ segmentId: "line", startFrame: 0, endFrameExclusive: 32 }],
};
const map = locateAlignedSegmentTiming(narrative, basis, evidence({
@@ -345,34 +336,30 @@ test("three Script words may share the two video frames covered by one evidence
]);
});
-test("Evidence is interpreted only through the explicitly connected alignment clock", () => {
+test("Evidence cannot be reinterpreted through another local frame domain", () => {
const narrative = parseScript("affinity.svml", "<line>Hello world.</line>");
const basis = speechBasis(narrative, 2);
const mismatched = evidence({
basis,
words: [{ text: "Hello", startSec: 0.1, endSec: 0.4 }, { text: "world", startSec: 0.5, endSec: 0.9 }],
});
- const anotherSpace = sealProgramSpace({ id: "test-space", durationSec: 2,
- frameRate: { numerator: 30, denominator: 1 },
- });
+ const anotherFrameDomain = { frameRate: { numerator: 30, denominator: 1 }, frameCount: 60 };
const anotherBasis: AlignmentBasis = {
...basis,
- programSpace: anotherSpace,
+ domainId: "another-domain",
+ frameDomain: anotherFrameDomain,
segments: [{ segmentId: "line", startFrame: 0, endFrameExclusive: 60 }],
};
- const map = locateAlignedSegmentTiming(narrative, anotherBasis, mismatched);
- assert.equal(map.tokens[0]?.startFrame, 3);
+ assert.throws(() => locateAlignedSegmentTiming(narrative, anotherBasis, mismatched), /another local domain/u);
});
-test("the final map is quantized once into the selected ProgramSpace", () => {
+test("the final map is quantized once into the selected Timeline", () => {
const narrative = parseScript("frames.svml", "<line>Hello.</line>");
const original = speechBasis(narrative, 1);
- const programSpace = sealProgramSpace({ id: "test-space", durationSec: 1,
- frameRate: { numerator: 30, denominator: 1 },
- });
+ const frameDomain = { frameRate: { numerator: 30, denominator: 1 }, frameCount: 30 };
const basis: AlignmentBasis = {
...original,
- programSpace,
+ frameDomain,
segments: [{ segmentId: "line", startFrame: 0, endFrameExclusive: 30 }],
};
const map = locateAlignedSegmentTiming(narrative, basis, evidence({
@@ -385,7 +372,7 @@ test("the final map is quantized once into the selected ProgramSpace", () => {
[map.tokens[0]?.startFrame, map.tokens[0]?.endFrameExclusive],
[3, 9],
);
- assert.equal(map.anchors.every((anchor) => Number.isSafeInteger(anchor.frame)), true);
+ assert.equal(map.boundaries.every((boundary) => Number.isSafeInteger(boundary.frame)), true);
});
test("a backwards character measurement is treated as missing token timing", () => {
diff --git a/packages/speech-evidence/README.md b/packages/speech-evidence/README.md
index f6a8600f..5fc9eee5 100644
--- a/packages/speech-evidence/README.md
+++ b/packages/speech-evidence/README.md
@@ -1,3 +1,12 @@
# `@hypit/speech-evidence`
Provider-neutral acoustic and word-alignment observations. Evidence is not the authored semantic truth.
+
+External package authors import these contracts from `@hypit/hypit/speech-evidence`; their logical
+Module identity remains `@hypit/speech-evidence@1`.
+
+`SpeechEvidenceAudio` carries canonical 16 kHz mono WAV bytes, their exact sample count and the
+`LocalTemporalDomain` identity from which they were projected. `AlignedTranscriptEvidence` preserves
+that domain identity and sample span while adding measured passages, words, characters and speech
+activity. Providers therefore return evidence for the same explicit source domain rather than an
+unidentified transcript that a later package must reconnect by inspecting Media.
diff --git a/packages/speech-evidence/package.json b/packages/speech-evidence/package.json
index 62f80447..aa4b59db 100644
--- a/packages/speech-evidence/package.json
+++ b/packages/speech-evidence/package.json
@@ -11,6 +11,10 @@
"activation": "./src/activation.ts"
},
"dependencies": {
+ "@hypit/component-kit": "workspace:*",
"@hypit/protocol": "workspace:*"
+ },
+ "devDependencies": {
+ "@hypit/timeline": "workspace:*"
}
}
diff --git a/packages/speech-evidence/src/activation.ts b/packages/speech-evidence/src/activation.ts
index 2a0a306e..173bd920 100644
--- a/packages/speech-evidence/src/activation.ts
+++ b/packages/speech-evidence/src/activation.ts
@@ -1,3 +1,8 @@
+import { speechEvidenceComponent } from "./component.js";
import { speechEvidenceManifest } from "./index.js";
-export const hypitPackage = { format: "hypit.node-package@1" as const, modules: [{ manifest: speechEvidenceManifest }] };
+export const hypitPackage = {
+ format: "hypit.node-package@1" as const,
+ modules: [{ manifest: speechEvidenceManifest }],
+ components: [speechEvidenceComponent],
+};
export default hypitPackage;
diff --git a/packages/speech-evidence/src/component.ts b/packages/speech-evidence/src/component.ts
new file mode 100644
index 00000000..c2b5dc7a
--- /dev/null
+++ b/packages/speech-evidence/src/component.ts
@@ -0,0 +1,23 @@
+import type { ComponentPackage } from "@hypit/component-kit";
+import type { StoredValue } from "@hypit/protocol";
+
+import {
+ assertAlignedTranscriptEvidenceIdentity,
+ assertSpeechEvidenceAudioIdentity,
+ speechEvidenceTypes,
+} from "./index.js";
+import type { AlignedTranscriptEvidence, SpeechEvidenceAudio } from "./index.js";
+
+function inline<T>(value: StoredValue, subject: string): T {
+ if (value.kind !== "inline") throw new Error(`${subject} must be inline.`);
+ return value.value as T;
+}
+
+export const speechEvidenceComponent = {
+ validators: [
+ { type: speechEvidenceTypes.audio,
+ handler: ({ value }) => assertSpeechEvidenceAudioIdentity(inline<SpeechEvidenceAudio>(value, "SpeechEvidenceAudio")) },
+ { type: speechEvidenceTypes.alignedTranscript,
+ handler: ({ value }) => assertAlignedTranscriptEvidenceIdentity(inline<AlignedTranscriptEvidence>(value, "AlignedTranscriptEvidence")) },
+ ],
+} satisfies ComponentPackage;
diff --git a/packages/speech-evidence/src/index.ts b/packages/speech-evidence/src/index.ts
index 47ee3c86..5bfb800f 100644
--- a/packages/speech-evidence/src/index.ts
+++ b/packages/speech-evidence/src/index.ts
@@ -1,4 +1,13 @@
-import type { ModuleManifest, TypeRef, ValueSchema } from "@hypit/protocol";
+import { isResourceId } from "@hypit/protocol";
+import type { BlobRef, ModuleManifest, TypeRef, ValueSchema } from "@hypit/protocol";
+
+export type SpeechEvidenceAudio = {
+ /** The exact local temporal domain from which this evidence audio was projected. */
+ readonly domainId: string;
+ readonly artifact: BlobRef;
+ /** Exact 16 kHz mono PCM sample count. */
+ readonly sampleFrames: number;
+};
/** Exact boundaries in the fixed 16 kHz Speech Evidence Audio sample domain. */
export type SpeechWordEvidence = {
@@ -36,6 +45,8 @@ export type SpeechTranscriptPassage = {
};
export type AlignedTranscriptEvidence = {
+ readonly domainId: string;
+ readonly sampleFrames: number;
readonly passages: readonly SpeechTranscriptPassage[];
};
@@ -65,6 +76,8 @@ const activity = object({
});
export const alignedTranscriptEvidenceFields = {
+ domainId: { schema: { kind: "string", minLength: 1 } },
+ sampleFrames: { schema: { kind: "number", integer: true, minimum: 1 } },
passages: {
schema: {
kind: "array",
@@ -82,6 +95,7 @@ export const alignedTranscriptEvidenceFields = {
export const alignedTranscriptEvidenceSchema: ValueSchema = object(alignedTranscriptEvidenceFields);
export const speechEvidenceModuleRef = { name: "@hypit/speech-evidence", version: "1" } as const;
export const speechEvidenceTypes = {
+ audio: { module: speechEvidenceModuleRef, name: "SpeechEvidenceAudio" },
alignedTranscript: { module: speechEvidenceModuleRef, name: "AlignedTranscriptEvidence" },
} satisfies Record<string, TypeRef>;
export const speechEvidenceManifest: ModuleManifest = {
@@ -89,7 +103,7 @@ export const speechEvidenceManifest: ModuleManifest = {
name: speechEvidenceModuleRef.name,
version: speechEvidenceModuleRef.version,
dependencies: [],
- types: [{ name: speechEvidenceTypes.alignedTranscript.name }],
+ types: [{ name: speechEvidenceTypes.audio.name }, { name: speechEvidenceTypes.alignedTranscript.name }],
capabilities: [],
producers: [],
};
@@ -100,3 +114,33 @@ export const speechEvidenceDependency = {
export function sealAlignedTranscriptEvidence(value: AlignedTranscriptEvidence): AlignedTranscriptEvidence {
return structuredClone(value);
}
+
+export function speechEvidenceSampleBoundary(masterSampleBoundary: number): number {
+ if (!Number.isSafeInteger(masterSampleBoundary) || masterSampleBoundary < 0) {
+ throw new Error("Speech evidence source sample boundary is invalid.");
+ }
+ const value = (BigInt(masterSampleBoundary) * 16_000n * 2n + 48_000n) / (48_000n * 2n);
+ if (value > BigInt(Number.MAX_SAFE_INTEGER)) throw new Error("Speech evidence sample boundary exceeds safe arithmetic.");
+ return Number(value);
+}
+
+export function sealSpeechEvidenceAudio(value: SpeechEvidenceAudio): SpeechEvidenceAudio {
+ return structuredClone(value);
+}
+
+export function assertSpeechEvidenceAudioIdentity(value: SpeechEvidenceAudio): void {
+ if (typeof value.domainId !== "string" || value.domainId.length === 0
+ || value.artifact.kind !== "blob" || !isResourceId(value.artifact.resource)
+ || !Number.isSafeInteger(value.artifact.size) || value.artifact.size < 0 || value.artifact.mediaType !== "audio/wav"
+ || !Number.isSafeInteger(value.sampleFrames) || value.sampleFrames < 1) {
+ throw new Error("SpeechEvidenceAudio identity is invalid.");
+ }
+}
+
+export function assertAlignedTranscriptEvidenceIdentity(value: AlignedTranscriptEvidence): void {
+ if (typeof value.domainId !== "string" || value.domainId.length === 0
+ || !Number.isSafeInteger(value.sampleFrames) || value.sampleFrames < 1
+ || !Array.isArray(value.passages)) {
+ throw new Error("AlignedTranscriptEvidence identity is invalid.");
+ }
+}
diff --git a/packages/speech/test/evidence.test.ts b/packages/speech-evidence/test/evidence.test.ts
similarity index 52%
rename from packages/speech/test/evidence.test.ts
rename to packages/speech-evidence/test/evidence.test.ts
index 8ac3dc74..1af01a75 100644
--- a/packages/speech/test/evidence.test.ts
+++ b/packages/speech-evidence/test/evidence.test.ts
@@ -1,24 +1,25 @@
-import { programSpaceSampleFrames, sealProgramSpace } from "@hypit/program-space";
-import { assertSpeechEvidenceAudioIdentity, sealSpeechEvidenceAudio, speechEvidenceSampleBoundary } from "@hypit/speech";
-import type { SpeechEvidenceAudio } from "@hypit/speech";
+import { timelineSampleFrames, sealTimeline } from "@hypit/timeline";
+import {
+ assertSpeechEvidenceAudioIdentity,
+ sealSpeechEvidenceAudio,
+ speechEvidenceSampleBoundary,
+} from "@hypit/speech-evidence";
import assert from "node:assert/strict";
import test from "node:test";
import { fixtureResource } from "../../../test/fixture-resource.js";
-
test("speech evidence uses integer rational boundary projection rather than floating duration arithmetic", () => {
assert.equal(speechEvidenceSampleBoundary(0), 0);
assert.equal(speechEvidenceSampleBoundary(480_000), 160_000);
assert.equal(speechEvidenceSampleBoundary(480_001), 160_000);
assert.equal(speechEvidenceSampleBoundary(480_002), 160_001);
- const ntsc = sealProgramSpace({ id: "test-space", durationSec: 1.001,
- frameRate: { numerator: 30_000, denominator: 1_001 },
- });
- assert.equal(programSpaceSampleFrames(ntsc, 48_000), 48_048);
+ const ntsc = sealTimeline({ id: "test-space", frameCount: 30, frameRate: { numerator: 30_000, denominator: 1_001 } });
+ assert.equal(timelineSampleFrames(ntsc, 48_000), 48_048);
});
-test("SpeechEvidenceAudio carries only normalized evidence bytes and their exact sample count", () => {
+test("SpeechEvidenceAudio identifies its source domain and exact sample span", () => {
const value = sealSpeechEvidenceAudio({
+ domainId: "speech-domain",
artifact: {
kind: "blob",
resource: fixtureResource("evidence"),
@@ -28,8 +29,6 @@ test("SpeechEvidenceAudio carries only normalized evidence bytes and their exact
sampleFrames: 16_000,
});
assert.doesNotThrow(() => assertSpeechEvidenceAudioIdentity(value));
- assert.throws(
- () => assertSpeechEvidenceAudioIdentity({ ...value, sampleFrames: 0 }),
- /media identity/u,
- );
+ assert.throws(() => assertSpeechEvidenceAudioIdentity({ ...value, domainId: "" }), /identity/u);
+ assert.throws(() => assertSpeechEvidenceAudioIdentity({ ...value, sampleFrames: 0 }), /identity/u);
});
diff --git a/packages/speech/README.md b/packages/speech/README.md
index afbc2255..2daa61d0 100644
--- a/packages/speech/README.md
+++ b/packages/speech/README.md
@@ -1,16 +1,19 @@
# `@hypit/speech`
-External components use `@hypit/hypit/speech` from their `@hypit/hypit` development dependency. The package
-owns the types and helpers below; Source imports retain the `@hypit/speech@1` Module identity.
+Provider-neutral speech generation duration contracts.
+External components use `@hypit/hypit/speech` from their `@hypit/hypit` development dependency.
+Source imports retain the `@hypit/speech@1` Module identity.
-Public contracts for speech duration, normalized semantic Takes and provider-neutral evidence audio.
-A `SemanticTake` contains one normalized media product, one authored Segment, its words and local
-frame anchors. Ordered Takes are assembled by `@hypit/timeline-author` into a `Timeline`, which is
-the complete Program range and Take placements, including gaps or overlap. `SpeechEvidenceAudio` carries canonical 16 kHz WAV bytes
-and their exact sample count; it never carries Script or Segment identity.
+`@hypit/speech-evidence` owns canonical evidence audio plus provider-neutral word, character, score
+and speech-activity observations in exact sample coordinates. Evidence carries its local domain
+identity, but no Script, Segment, film Timeline or presentation identity.
-The package also owns deterministic boundary materialization for a Segment with no Tokens. It maps
-the Segment start and end to the prepared media's frame domain and publishes the same
-`SemanticTake` type. The preview and real-media author surfaces both select this operation for an
-empty Segment. There are no word windows to predict or acoustic evidence to request.
+[`@hypit/speech-alignment`](../speech-alignment/README.md) deterministically combines acoustic
+evidence with one authored Segment and its `LocalTemporalDomain` to produce the
+`@hypit/narrative-temporal` `NarrativeAlignment`. The public Narrative timing contract is deliberately
+not owned here. An empty Segment needs no acoustic request: Narrative Temporal can materialize its
+boundaries directly over the supplied local domain with an empty token list.
+
+This package defines no provider, queue, credential, media normalization, Timeline assembly or
+visual/audio presentation policy.
diff --git a/packages/speech/package.json b/packages/speech/package.json
index e6576251..6dafac8d 100644
--- a/packages/speech/package.json
+++ b/packages/speech/package.json
@@ -12,8 +12,6 @@
},
"dependencies": {
"@hypit/component-kit": "workspace:*",
- "@hypit/media": "workspace:*",
- "@hypit/narrative": "workspace:*",
"@hypit/protocol": "workspace:*"
}
}
diff --git a/packages/speech/src/component.ts b/packages/speech/src/component.ts
index 370382c8..ce93f8f6 100644
--- a/packages/speech/src/component.ts
+++ b/packages/speech/src/component.ts
@@ -1,17 +1,9 @@
import type { ComponentPackage } from "@hypit/component-kit";
-import type { SynchronizedMedia } from "@hypit/media";
-import type { Narrative, NarrativeExcerpt } from "@hypit/narrative";
-import { canonicalize } from "@hypit/protocol";
import type { StoredValue } from "@hypit/protocol";
-import {
- assertSemanticTakeIdentity,
- assertSpeechDurationIdentity,
- assertSpeechEvidenceAudioIdentity,
-} from "./identity.js";
-import { materializeSegmentBoundaryTake } from "./materialize.js";
-import { speechProducers, speechTypes } from "./manifest.js";
-import type { SemanticTake, SpeechDuration, SpeechEvidenceAudio } from "./types.js";
+import { assertSpeechDurationIdentity } from "./identity.js";
+import { speechTypes } from "./manifest.js";
+import type { SpeechDuration } from "./types.js";
function inline<T>(value: StoredValue, subject: string): T {
if (value.kind !== "inline") throw new Error(`${subject} must be inline.`);
@@ -21,23 +13,5 @@ function inline<T>(value: StoredValue, subject: string): T {
export const speechComponent = {
validators: [
{ type: speechTypes.duration, handler: ({ value }) => assertSpeechDurationIdentity(inline<SpeechDuration>(value, "SpeechDuration")) },
- { type: speechTypes.evidenceAudio, handler: ({ value }) => assertSpeechEvidenceAudioIdentity(inline<SpeechEvidenceAudio>(value, "SpeechEvidenceAudio")) },
- { type: speechTypes.semanticTake, handler: ({ value }) => assertSemanticTakeIdentity(inline<SemanticTake>(value, "SemanticTake")) },
],
- producers: [{
- producer: speechProducers.materializeSegmentBoundaries,
- handler: ({ inputs }) => ({
- outputs: {
- take: {
- kind: "inline",
- value: canonicalize(materializeSegmentBoundaryTake(
- inline<Narrative>(inputs.narrative!.value, "Narrative"),
- inline<NarrativeExcerpt>(inputs.segment!.value, "NarrativeExcerpt"),
- inline<SynchronizedMedia>(inputs.media!.value, "SynchronizedMedia"),
- )),
- },
- },
- needs: {},
- }),
- }],
} satisfies ComponentPackage;
diff --git a/packages/speech/src/identity.ts b/packages/speech/src/identity.ts
index 91fef43f..d7de8056 100644
--- a/packages/speech/src/identity.ts
+++ b/packages/speech/src/identity.ts
@@ -1,73 +1,6 @@
-import { isResourceId } from "@hypit/protocol";
-import { verifySynchronizedMedia } from "@hypit/media";
-import type { SemanticTake, SpeechDuration, SpeechEvidenceAudio } from "./types.js";
+import type { SpeechDuration } from "./types.js";
+
export function sealSpeechDuration(value: SpeechDuration): SpeechDuration { return value; }
export function assertSpeechDurationIdentity(value: SpeechDuration): void {
if (!Number.isFinite(value) || value <= 0) throw new Error("SpeechDuration is invalid.");
}
-export function speechEvidenceSampleBoundary(masterSampleBoundary: number): number {
- if (!Number.isSafeInteger(masterSampleBoundary) || masterSampleBoundary < 0) throw new Error("Speech evidence source sample boundary is invalid.");
- const value = (BigInt(masterSampleBoundary) * 16_000n * 2n + 48_000n) / (48_000n * 2n);
- if (value > BigInt(Number.MAX_SAFE_INTEGER)) throw new Error("Speech evidence sample boundary exceeds safe arithmetic.");
- return Number(value);
-}
-export function sealSpeechEvidenceAudio(value: SpeechEvidenceAudio): SpeechEvidenceAudio { return structuredClone(value); }
-
-export function sealSemanticTake(value: SemanticTake): SemanticTake {
- const take = structuredClone(value);
- assertSemanticTakeIdentity(take);
- return take;
-}
-
-export function assertSemanticTakeIdentity(take: SemanticTake): void {
- if (!take.narrativeId.trim()) throw new Error("SemanticTake narrativeId must not be empty.");
- verifySynchronizedMedia(take.media);
- const frameCount = take.media.timeline.frameCount;
- const { segment } = take;
- if (!segment.segmentId || !segment.startAnchorId || !segment.endAnchorId
- || segment.startFrame !== 0 || segment.endFrameExclusive !== frameCount) {
- throw new Error("SemanticTake Segment must cover its local media frame domain.");
- }
- const anchorIds = new Set<string>();
- const anchorFrames = new Map<string, number>();
- for (const anchor of take.anchors) {
- if (!anchor.identity || anchorIds.has(anchor.identity) || !Number.isSafeInteger(anchor.frame)
- || anchor.frame < 0 || anchor.frame > frameCount) {
- throw new Error(`SemanticTake anchor ${anchor.identity || "<unnamed>"} is invalid.`);
- }
- anchorIds.add(anchor.identity);
- anchorFrames.set(anchor.identity, anchor.frame);
- }
- if (anchorFrames.get(segment.startAnchorId) !== 0
- || anchorFrames.get(segment.endAnchorId) !== frameCount) {
- throw new Error("SemanticTake Segment Anchors must equal its media boundaries.");
- }
- const tokenIds = new Set<string>();
- let previousStart = 0;
- let previousEnd = 0;
- for (const token of take.tokens) {
- if (!token.tokenId || !token.segmentId || token.segmentId !== segment.segmentId || !token.text
- || !token.startAnchorId || !token.endAnchorId || tokenIds.has(token.tokenId)
- || !Number.isSafeInteger(token.startFrame) || !Number.isSafeInteger(token.endFrameExclusive)
- || token.startFrame < 0 || token.endFrameExclusive < 0
- || token.startFrame > token.endFrameExclusive
- || token.startFrame > frameCount || token.endFrameExclusive > frameCount
- || token.startFrame < previousStart || token.endFrameExclusive < previousEnd) {
- throw new Error(`SemanticTake token ${token.tokenId || "<unnamed>"} is invalid.`);
- }
- if (anchorFrames.get(token.startAnchorId) !== token.startFrame
- || anchorFrames.get(token.endAnchorId) !== token.endFrameExclusive) {
- throw new Error(`SemanticTake token ${token.tokenId} disagrees with its Anchors.`);
- }
- tokenIds.add(token.tokenId);
- previousStart = token.startFrame;
- previousEnd = token.endFrameExclusive;
- }
-}
-export function assertSpeechEvidenceAudioIdentity(value: SpeechEvidenceAudio): void {
- if (value.artifact.kind !== "blob" || !isResourceId(value.artifact.resource)
- || !Number.isSafeInteger(value.artifact.size) || value.artifact.size < 0 || value.artifact.mediaType !== "audio/wav"
- || !Number.isSafeInteger(value.sampleFrames) || value.sampleFrames < 1) {
- throw new Error("SpeechEvidenceAudio media identity is invalid.");
- }
-}
diff --git a/packages/speech/src/index.ts b/packages/speech/src/index.ts
index ca413bfd..1e541c47 100644
--- a/packages/speech/src/index.ts
+++ b/packages/speech/src/index.ts
@@ -1,6 +1,5 @@
-export { assertSemanticTakeIdentity, assertSpeechDurationIdentity, assertSpeechEvidenceAudioIdentity, sealSemanticTake, sealSpeechDuration, sealSpeechEvidenceAudio, speechEvidenceSampleBoundary } from "./identity.js";
+export { assertSpeechDurationIdentity, sealSpeechDuration } from "./identity.js";
export { speechComponent } from "./component.js";
-export { materializeSegmentBoundaryTake, materializeSemanticTake } from "./materialize.js";
-export { speechDependency, speechManifest, speechModuleRef, speechProducers, speechTypes } from "./manifest.js";
-export { semanticTakeSchema, speechDurationSchema, speechEvidenceAudioSchema } from "./schema.js";
+export { speechDependency, speechManifest, speechModuleRef, speechTypes } from "./manifest.js";
+export { speechDurationSchema, speechEvidenceAudioSchema } from "./schema.js";
export type * from "./types.js";
diff --git a/packages/speech/src/manifest.ts b/packages/speech/src/manifest.ts
index ae17b07b..7e071298 100644
--- a/packages/speech/src/manifest.ts
+++ b/packages/speech/src/manifest.ts
@@ -1,30 +1,13 @@
-import { mediaDependency, mediaTypes } from "@hypit/media";
-import { narrativeDependency, narrativeTypes } from "@hypit/narrative";
-import type { ModuleManifest, ProducerRef, TypeRef } from "@hypit/protocol";
-import { semanticTakeSchema, speechDurationSchema, speechEvidenceAudioSchema } from "./schema.js";
+import type { ModuleManifest, TypeRef } from "@hypit/protocol";
+
export const speechModuleRef = { name: "@hypit/speech", version: "1" } as const;
export const speechTypes = {
duration: { module: speechModuleRef, name: "SpeechDuration" },
- evidenceAudio: { module: speechModuleRef, name: "SpeechEvidenceAudio" },
- semanticTake: { module: speechModuleRef, name: "SemanticTake" },
} satisfies Record<string, TypeRef>;
-export const speechProducers = {
- materializeSegmentBoundaries: { module: speechModuleRef, name: "materialize-segment-boundaries" },
-} satisfies Record<string, ProducerRef>;
-export const speechManifest: ModuleManifest = { format: "hypit.module@1", name: speechModuleRef.name, version: speechModuleRef.version,
- dependencies: [mediaDependency, narrativeDependency],
- types: [{ name: speechTypes.duration.name },
- { name: speechTypes.evidenceAudio.name },
- { name: speechTypes.semanticTake.name }],
- capabilities: [],
- producers: [{
- name: speechProducers.materializeSegmentBoundaries.name,
- inputs: [
- { name: "narrative", type: narrativeTypes.narrative },
- { name: "segment", type: narrativeTypes.excerpt },
- { name: "media", type: mediaTypes.synchronized },
- ],
- outputs: [{ name: "take", type: speechTypes.semanticTake }],
- needs: [],
- }] };
+export const speechManifest: ModuleManifest = {
+ format: "hypit.module@1", name: speechModuleRef.name, version: speechModuleRef.version,
+ dependencies: [],
+ types: [{ name: speechTypes.duration.name }],
+ capabilities: [], producers: [],
+};
export const speechDependency = { module: speechModuleRef } as const;
diff --git a/packages/speech/src/materialize.ts b/packages/speech/src/materialize.ts
deleted file mode 100644
index 2ee726c9..00000000
--- a/packages/speech/src/materialize.ts
+++ /dev/null
@@ -1,103 +0,0 @@
-import type { SynchronizedMedia } from "@hypit/media";
-import type { Narrative, NarrativeExcerpt } from "@hypit/narrative";
-
-import { assertSemanticTakeIdentity, sealSemanticTake } from "./identity.js";
-import type { SemanticTake, SemanticTakeTiming } from "./types.js";
-
-function authoredSegment(narrative: Narrative, excerpt: NarrativeExcerpt): Narrative["segments"][number] {
- if (narrative.id !== excerpt.narrativeId) {
- throw new Error(`NarrativeExcerpt ${excerpt.id} belongs to Narrative ${excerpt.narrativeId}, not ${narrative.id}.`);
- }
- if (excerpt.kind !== "segment") throw new Error("SemanticTake materialization requires a Segment excerpt.");
- const segment = narrative.segments.find((candidate) => candidate.id === excerpt.id);
- if (segment === undefined) throw new Error(`Narrative does not contain Segment ${excerpt.id}.`);
- if (excerpt.tokenStart !== segment.tokenStart || excerpt.tokenEndExclusive !== segment.tokenEndExclusive) {
- throw new Error(`NarrativeExcerpt ${excerpt.id} does not describe its authored Segment.`);
- }
- return segment;
-}
-
-function localFrame(frame: number, frameCount: number, label: string): number {
- if (!Number.isSafeInteger(frame) || frame < 0 || frame > frameCount) {
- throw new Error(`${label} lies outside its normalized Segment Take.`);
- }
- return frame;
-}
-
-/**
- * Copy one Segment-local timing result into a self-contained semantic Take.
- * How the timing was obtained remains the caller's explicit package meaning.
- */
-export function materializeSemanticTake(
- narrative: Narrative,
- excerpt: NarrativeExcerpt,
- media: SynchronizedMedia,
- timing: SemanticTakeTiming,
-): SemanticTake {
- const segment = authoredSegment(narrative, excerpt);
- const localFrameCount = media.timeline.frameCount;
- const timedById = new Map(timing.tokens.map((token) => [token.tokenId, token]));
- const tokens = narrative.tokens.slice(segment.tokenStart, segment.tokenEndExclusive).map((token) => {
- const timed = timedById.get(token.id);
- if (timed === undefined || timed.segmentId !== segment.id) {
- throw new Error(`Semantic timing does not locate authored Token ${token.id}.`);
- }
- const startFrame = localFrame(timed.startFrame, localFrameCount, `Token ${token.id}`);
- const endFrameExclusive = localFrame(timed.endFrameExclusive, localFrameCount, `Token ${token.id}`);
- if (endFrameExclusive <= startFrame) throw new Error(`Token ${token.id} has an empty or reversed frame window.`);
- return {
- tokenId: token.id,
- segmentId: segment.id,
- text: token.text,
- startAnchorId: token.startAnchorId,
- endAnchorId: token.endAnchorId,
- startFrame,
- endFrameExclusive,
- };
- });
- const anchorsById = new Map(timing.anchors.map((anchor) => [anchor.identity, anchor]));
- const anchors = narrative.semanticIndex.anchors
- .filter((anchor) => anchor.segmentId === segment.id)
- .map((anchor) => {
- const measured = anchorsById.get(anchor.id);
- if (measured === undefined) throw new Error(`Semantic timing does not locate authored Anchor ${anchor.id}.`);
- return {
- identity: anchor.id,
- frame: localFrame(measured.frame, localFrameCount, `Anchor ${anchor.id}`),
- };
- });
- const take = sealSemanticTake({
- narrativeId: narrative.id,
- media,
- segment: {
- segmentId: segment.id,
- startAnchorId: segment.startAnchorId,
- endAnchorId: segment.endAnchorId,
- startFrame: 0,
- endFrameExclusive: media.timeline.frameCount,
- },
- tokens,
- anchors,
- });
- assertSemanticTakeIdentity(take);
- return take;
-}
-
-/** Materialize the exact media boundaries of an authored Segment that contains no Tokens. */
-export function materializeSegmentBoundaryTake(
- narrative: Narrative,
- excerpt: NarrativeExcerpt,
- media: SynchronizedMedia,
-): SemanticTake {
- const segment = authoredSegment(narrative, excerpt);
- if (segment.tokenStart !== segment.tokenEndExclusive) {
- throw new Error(`Segment ${segment.id} contains spoken Tokens and needs token timing.`);
- }
- return materializeSemanticTake(narrative, excerpt, media, {
- tokens: [],
- anchors: [
- { identity: segment.startAnchorId, frame: 0 },
- { identity: segment.endAnchorId, frame: media.timeline.frameCount },
- ],
- });
-}
diff --git a/packages/speech/src/schema.ts b/packages/speech/src/schema.ts
index 860528b9..189ebf0d 100644
--- a/packages/speech/src/schema.ts
+++ b/packages/speech/src/schema.ts
@@ -1,42 +1,10 @@
-import { synchronizedMediaSchema } from "@hypit/media";
import type { ValueSchema } from "@hypit/protocol";
-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 digest = { kind: "string", minLength: 5, maxLength: 256 } as const;
const object = (fields: Readonly<Record<string, { readonly schema: ValueSchema; readonly optional?: boolean }>>): ValueSchema => ({ kind: "object", fields });
-const audioBlobRef = object({
- kind: { schema: { kind: "literal", value: "blob" } },
- resource: { schema: digest },
- size: { schema: integer },
- mediaType: { schema: { kind: "literal", value: "audio/wav" } },
-});
-const semanticTakeToken = object({
- tokenId: { schema: string },
- segmentId: { schema: string },
- text: { schema: string },
- startAnchorId: { schema: string },
- endAnchorId: { schema: string },
- startFrame: { schema: integer },
- endFrameExclusive: { schema: integer },
-});
-const semanticTakeAnchor = object({ identity: { schema: string }, frame: { schema: integer } });
-const semanticTakeSegment = object({
- segmentId: { schema: string },
- startAnchorId: { schema: string },
- endAnchorId: { schema: string },
- startFrame: { schema: integer },
- endFrameExclusive: { schema: integer },
-});
+const audioBlobRef = object({ kind: { schema: { kind: "literal", value: "blob" } },
+ resource: { schema: { kind: "string", minLength: 5, maxLength: 256 } }, size: { schema: integer },
+ mediaType: { schema: { kind: "literal", value: "audio/wav" } } });
export const speechDurationSchema: ValueSchema = number;
-export const speechEvidenceAudioSchema: ValueSchema = object({
- artifact: { schema: audioBlobRef },
- sampleFrames: { schema: { kind: "number", integer: true, minimum: 1 } },
-});
-export const semanticTakeSchema: ValueSchema = object({
- narrativeId: { schema: string },
- media: { schema: synchronizedMediaSchema },
- segment: { schema: semanticTakeSegment },
- tokens: { schema: { kind: "array", items: semanticTakeToken } },
- anchors: { schema: { kind: "array", items: semanticTakeAnchor } },
-});
+export const speechEvidenceAudioSchema: ValueSchema = object({ artifact: { schema: audioBlobRef },
+ sampleFrames: { schema: { kind: "number", integer: true, minimum: 1 } } });
diff --git a/packages/speech/src/types.ts b/packages/speech/src/types.ts
index d55d8a0b..eccc76c0 100644
--- a/packages/speech/src/types.ts
+++ b/packages/speech/src/types.ts
@@ -1,54 +1,2 @@
-import type { SynchronizedMedia } from "@hypit/media";
-import type { BlobRef } from "@hypit/protocol";
/** Positive seconds. The graph port's TypeRef already carries the SpeechDuration identity. */
export type SpeechDuration = number;
-export type SpeechEvidenceAudio = {
- readonly artifact: BlobRef;
- /** Exact 16 kHz mono PCM sample count. Format constants belong to this Type, not every value. */
- readonly sampleFrames: number;
-};
-
-/** One authored Script token located in one normalized Take's local frame domain. */
-export type SemanticTakeToken = {
- readonly tokenId: string;
- readonly segmentId: string;
- readonly text: string;
- readonly startAnchorId: string;
- readonly endAnchorId: string;
- readonly startFrame: number;
- readonly endFrameExclusive: number;
-};
-
-/**
- * A self-contained semantic media product. Media bytes remain ordinary BlobRefs
- * inside SynchronizedMedia; the authored word surface and its local frame
- * coordinates travel with this Take instead of requiring a second Script edge.
- */
-export type SemanticTake = {
- /** Author-visible Script identity carried through every semantic projection. */
- readonly narrativeId: string;
- readonly media: SynchronizedMedia;
- readonly segment: {
- readonly segmentId: string;
- readonly startAnchorId: string;
- readonly endAnchorId: string;
- readonly startFrame: number;
- readonly endFrameExclusive: number;
- };
- readonly tokens: readonly SemanticTakeToken[];
- readonly anchors: readonly { readonly identity: string; readonly frame: number }[];
-};
-
-/** One authored Token located in a Segment-local frame domain. */
-export type SemanticTakeTimedToken = {
- readonly tokenId: string;
- readonly segmentId: string;
- readonly startFrame: number;
- readonly endFrameExclusive: number;
-};
-
-/** Provider measurement and preview estimation both materialize through this narrow timing waist. */
-export type SemanticTakeTiming = {
- readonly tokens: readonly SemanticTakeTimedToken[];
- readonly anchors: readonly { readonly identity: string; readonly frame: number }[];
-};
diff --git a/packages/speech/test/identity.test.ts b/packages/speech/test/identity.test.ts
deleted file mode 100644
index 9d6bd0e1..00000000
--- a/packages/speech/test/identity.test.ts
+++ /dev/null
@@ -1,36 +0,0 @@
-import assert from "node:assert/strict";
-import test from "node:test";
-
-import { assertSemanticTakeIdentity } from "@hypit/speech";
-
-test("SemanticTake rejects Token frames that disagree with authored Anchors", () => {
- assert.throws(() => assertSemanticTakeIdentity({
- narrativeId: "story",
- media: {
- timeline: { frameRate: { numerator: 30, denominator: 1 }, frameCount: 30 },
- audio: {
- artifact: {
- kind: "blob",
- resource: "res_speech-identity",
- size: 1,
- mediaType: "audio/wav",
- },
- },
- },
- segment: {
- segmentId: "intro", startAnchorId: "intro:start", endAnchorId: "intro:end",
- startFrame: 0, endFrameExclusive: 30,
- },
- tokens: [{
- tokenId: "hello", segmentId: "intro", text: "hello",
- startAnchorId: "hello:start", endAnchorId: "hello:end",
- startFrame: 4, endFrameExclusive: 10,
- }],
- anchors: [
- { identity: "intro:start", frame: 0 },
- { identity: "hello:start", frame: 3 },
- { identity: "hello:end", frame: 10 },
- { identity: "intro:end", frame: 30 },
- ],
- }), /disagrees with its Anchors/u);
-});
diff --git a/packages/studio-adapter/README.md b/packages/studio-adapter/README.md
index 3d91cf3d..412af339 100644
--- a/packages/studio-adapter/README.md
+++ b/packages/studio-adapter/README.md
@@ -125,7 +125,7 @@ identity merely because it currently lines up.
Read [Ranking's Companion](../ranking-studio/src/index.ts) for board/reveal lanes,
[Caption Fine's](../caption-fine-studio/src/index.ts) for Cue text and Style selection, and
-[Media Track's](../media-track-studio/src/index.ts) for material and occupancy.
+[Visual Track's](../visual-track-studio/src/index.ts) for material and occupancy.
## Preserve executed temporal lineage
@@ -285,12 +285,12 @@ Studio resolves the actual reference and matches its Module/Surface. It prefixes
bindings and fields under the consumer reference; the example becomes `style.distance`.
Nested `referenced` and `recipe` bindings use the same composition. The Use retains its own
Window and time gestures. Several Uses referencing one Style edit the same source object.
-A project Style can therefore publish controls without replacing the Performance, Sound or
+A project Style can therefore publish controls without replacing the Visual, Audio or
Caption Track Companion. No parameter Companion means the reference remains visible with only
its consumer-declared fields.
A source or Recipe binding may declare a typed `fallback`, or a function of the authored
-properties for a dependent default. For example, Sound's end gain follows its start gain until
+properties for a dependent default. For example, an Audio Style's end gain follows its start gain until
authored explicitly. The field displays the fallback; the first edit inserts the attribute/property
in its owning SVML/SVS file. Source recompilation remains the owner of current values.
Only expose omitted defaults whose insertion preserves valid author semantics; geometry inputs
diff --git a/packages/studio-adapter/src/index.ts b/packages/studio-adapter/src/index.ts
index 6864b9c7..846301c5 100644
--- a/packages/studio-adapter/src/index.ts
+++ b/packages/studio-adapter/src/index.ts
@@ -39,17 +39,19 @@ export type StudioTimelinePresentation = {
};
export type StudioTemporalSource = {
- readonly spaceId: string;
+ readonly timelineId: string;
readonly narrativeId?: string;
- readonly kind: "program" | "selection" | "segment" | "moment";
+ /** Domain-owned Type and role; Studio does not enumerate future time domains. */
+ readonly type: TypeRef;
+ readonly kind: string;
readonly id: string;
};
export type StudioTemporalAuthority =
| {
- readonly kind: "semantic";
+ readonly kind: "domain";
readonly source: StudioTemporalSource;
- readonly boundary: "start" | "end" | "cue";
+ readonly boundary: string;
}
| {
readonly kind: "parameter";
@@ -61,11 +63,8 @@ export type StudioTemporalAuthority =
export type StudioTemporalInstantProjection = {
readonly kind: "instant";
readonly expression: string;
- readonly reference:
- | "program.start" | "program.end"
- | "selection.start" | "selection.end"
- | "segment.start" | "segment.end"
- | "moment.cue" | "absolute";
+ /** Domain-owned reference spelling, or one of Timeline's common expressions. */
+ readonly reference: string;
readonly frame: number;
readonly source: StudioTemporalSource;
readonly authority: StudioTemporalAuthority;
@@ -375,7 +374,7 @@ export type StudioCandidateProvenance = {
export type StudioSemanticAnchor = {
readonly id: string;
- readonly kind: "program-start" | "segment-start" | "segment-end" | "token-start" | "token-end" | "program-end";
+ readonly kind: "segment-start" | "segment-end" | "token-start" | "token-end";
readonly frame: number;
readonly segmentId?: string;
readonly tokenId?: string;
@@ -398,7 +397,7 @@ export type StudioSemanticToken = {
};
export type StudioSemanticTimeline = {
- readonly spaceId: string;
+ readonly timelineId: string;
readonly narrativeId: string;
readonly presentation: {
readonly family: StudioTrackFamily;
@@ -883,8 +882,50 @@ export function temporalLineageFor(
throw new Error(`Studio Temporal lineage is ambiguous for ${subjectId}${input === undefined ? "" : ` at ${input}`}.`);
}
const binding = found[0];
+ const authored = context.placement?.id === subjectId
+ ? context.placement
+ : context.placement?.children.find((child) => child.id === subjectId);
+ const authority = (
+ endpoint: StudioTemporalInstantProjection,
+ role: "instant" | "start" | "end",
+ ): StudioTemporalInstantProjection => {
+ if (authored === undefined) return { ...endpoint, authority: { kind: "fixed" } };
+ const attributes = authored.attributes;
+ const references = authored.referenceAttributes;
+ const parameter = (binding: string, relation: "direct" | "after-start" | "before-end" = "direct") =>
+ ({ kind: "parameter" as const, binding, relation });
+ const domain = endpoint.authority.kind === "domain" ? endpoint.authority : undefined;
+ if (role === "instant") {
+ if (attributes.instant !== undefined) return { ...endpoint, authority: parameter("instant") };
+ if (references.at !== undefined && domain !== undefined && domain.source.kind !== "segment") return endpoint;
+ if (attributes.at !== undefined) return { ...endpoint, authority: parameter("at") };
+ return { ...endpoint, authority: { kind: "fixed" } };
+ }
+ if (attributes.start !== undefined || attributes.end !== undefined) {
+ return { ...endpoint, authority: parameter(role) };
+ }
+ if (attributes.for !== undefined && (attributes.at !== undefined || references.at !== undefined)) {
+ if (role === "end") return { ...endpoint, authority: parameter("for", "after-start") };
+ if (references.at !== undefined && domain !== undefined) return endpoint;
+ return { ...endpoint, authority: parameter("at") };
+ }
+ if (attributes.for !== undefined && (attributes.until !== undefined || references.until !== undefined)) {
+ if (role === "start") return { ...endpoint, authority: parameter("for", "before-end") };
+ if (references.until !== undefined && domain !== undefined) return endpoint;
+ return { ...endpoint, authority: parameter("until") };
+ }
+ if (references.during !== undefined && domain?.source.kind === "selection") return endpoint;
+ return { ...endpoint, authority: { kind: "fixed" } };
+ };
+ const projection = binding?.projection.kind === "instant"
+ ? authority(binding.projection, "instant")
+ : binding === undefined ? undefined : {
+ ...binding.projection,
+ start: authority(binding.projection.start, "start"),
+ end: authority(binding.projection.end, "end"),
+ };
return binding === undefined ? undefined : {
- projection: binding.projection,
+ projection: projection!,
phases: [],
};
}
@@ -894,14 +935,14 @@ export function temporalSemanticSource(lineage: StudioTemporalLineage | undefine
if (lineage === undefined) return undefined;
const projection = lineage.projection;
const endpoints = projection.kind === "instant" ? [projection] : [projection.start, projection.end];
- const semantic = endpoints.flatMap((endpoint) => endpoint.authority.kind === "semantic"
+ const semantic = endpoints.flatMap((endpoint) => endpoint.authority.kind === "domain"
? [endpoint.authority.source]
: []);
const first = semantic[0];
if (first === undefined) return undefined;
return semantic.every((candidate) => candidate.kind === first.kind
&& candidate.id === first.id
- && candidate.spaceId === first.spaceId
+ && candidate.timelineId === first.timelineId
&& candidate.narrativeId === first.narrativeId)
? first
: undefined;
diff --git a/packages/studio/README.md b/packages/studio/README.md
index d23cc687..bbecca54 100644
--- a/packages/studio/README.md
+++ b/packages/studio/README.md
@@ -185,7 +185,7 @@ stops (distinct frame positions), so its duration may change. `at/for` moves its
offers a trailing duration trim; `until/for` offers the corresponding leading trim.
An Instant reference expression edits only its offset; a bare reference has an implicit zero offset.
`start/end` trims edit the corresponding expression; moving the window shifts both by the same
-frame delta. Edited clock values and offsets are written in frames at the current ProgramSpace rate.
+frame delta. Edited clock values and offsets are written in frames at the current Timeline rate.
The semantic marker Inspector exposes exact anchor identities and, where a
declared handle supports it, offers choices among coincident anchors.
See [temporal author forms](../temporal-markup/EDITING.md) for the complete behavior.
diff --git a/packages/studio/locales/en.json b/packages/studio/locales/en.json
index e31e846c..1a7b49cf 100644
--- a/packages/studio/locales/en.json
+++ b/packages/studio/locales/en.json
@@ -53,8 +53,6 @@
"common.waiting": "Waiting",
"inspector.add-color": "Add color",
"inspector.add-item": "Add item",
- "inspector.anchor.program-end": "Timeline end{detail}",
- "inspector.anchor.program-start": "Timeline start{detail}",
"inspector.anchor.segment-end": "Segment end{detail}",
"inspector.anchor.segment-start": "Segment start{detail}",
"inspector.anchor.token-end": "Word end{detail}",
diff --git a/packages/studio/locales/zh-CN.json b/packages/studio/locales/zh-CN.json
index 8b9e8f25..6a1f42d3 100644
--- a/packages/studio/locales/zh-CN.json
+++ b/packages/studio/locales/zh-CN.json
@@ -53,8 +53,6 @@
"common.waiting": "等待中",
"inspector.add-color": "添加颜色",
"inspector.add-item": "添加条目",
- "inspector.anchor.program-end": "时间线终点{detail}",
- "inspector.anchor.program-start": "时间线起点{detail}",
"inspector.anchor.segment-end": "段尾{detail}",
"inspector.anchor.segment-start": "段头{detail}",
"inspector.anchor.token-end": "词尾{detail}",
diff --git a/packages/studio/package.json b/packages/studio/package.json
index 68a28448..dfc72793 100644
--- a/packages/studio/package.json
+++ b/packages/studio/package.json
@@ -17,17 +17,15 @@
"@hypit/component-kit": "workspace:*",
"@hypit/composition": "workspace:*",
"@hypit/core": "workspace:*",
- "@hypit/deck-track-studio": "workspace:*",
+ "@hypit/depth-stack-studio": "workspace:*",
"@hypit/driver-node": "workspace:*",
"@hypit/elaborator": "workspace:*",
"@hypit/film-studio": "workspace:*",
"@hypit/hyperframes": "workspace:*",
"@hypit/markup": "workspace:*",
- "@hypit/media-track-studio": "workspace:*",
+ "@hypit/media-pipeline": "workspace:*",
+ "@hypit/visual-track-studio": "workspace:*",
"@hypit/package-loader-node": "workspace:*",
- "@hypit/performance-studio": "workspace:*",
- "@hypit/sound-studio": "workspace:*",
- "@hypit/program-space": "workspace:*",
"@hypit/project-context-node": "workspace:*",
"@hypit/protocol": "workspace:*",
"@hypit/ranking-studio": "workspace:*",
@@ -37,11 +35,12 @@
"@hypit/screen-overlay-studio": "workspace:*",
"@hypit/script-studio": "workspace:*",
"@hypit/speech": "workspace:*",
+ "@hypit/narrative-temporal": "workspace:*",
"@hypit/studio-adapter": "workspace:*",
"@hypit/svs": "workspace:*",
"@hypit/temporal": "workspace:*",
"@hypit/timeline": "workspace:*",
- "@hypit/typography-track-studio": "workspace:*",
+ "@hypit/text-fine-studio": "workspace:*",
"@hypit/validation": "workspace:*",
"@hypit/video-cli": "workspace:*",
"@hypit/workspace": "workspace:*",
diff --git a/packages/studio/src/parameters.ts b/packages/studio/src/parameters.ts
index b7a550bf..f3830230 100644
--- a/packages/studio/src/parameters.ts
+++ b/packages/studio/src/parameters.ts
@@ -539,16 +539,16 @@ export function resolveTimelineEditHandles(
const projection = temporal.projection;
const semanticTarget = (endpoints: readonly StudioTemporalInstantProjection[]) => {
- const sources = endpoints.flatMap((endpoint) => endpoint.authority.kind === "semantic"
+ const sources = endpoints.flatMap((endpoint) => endpoint.authority.kind === "domain"
? [endpoint.authority.source]
: []);
const first = sources[0];
if (first === undefined || first.narrativeId === undefined
- || first.spaceId !== semantic?.spaceId
+ || first.timelineId !== semantic?.timelineId
|| first.narrativeId !== semantic.narrativeId
|| !sources.every((candidate) => candidate.kind === first.kind
&& candidate.id === first.id
- && candidate.spaceId === first.spaceId
+ && candidate.timelineId === first.timelineId
&& candidate.narrativeId === first.narrativeId)) return undefined;
if (first.kind === "selection") {
const selection = semantic?.selections.find((candidate) => candidate.id === first.id);
@@ -596,7 +596,7 @@ export function resolveTimelineEditHandles(
if (missing !== undefined && "missing" in missing) {
return disabled(gesture, `投影参数 ${missing.missing} 在当前作者源码中不可写。`);
}
- const semanticEndpoints = affected.filter(({ endpoint }) => endpoint.authority.kind === "semantic").map(({ endpoint }) => endpoint);
+ const semanticEndpoints = affected.filter(({ endpoint }) => endpoint.authority.kind === "domain").map(({ endpoint }) => endpoint);
const target = semanticTarget(semanticEndpoints);
if (semanticEndpoints.length > 0 && target === undefined) {
return disabled(gesture, "语义端点在当前 Candidate 中没有可写的作者身份。");
diff --git a/packages/studio/src/preview/render.ts b/packages/studio/src/preview/render.ts
index 7a79e443..95d2610f 100644
--- a/packages/studio/src/preview/render.ts
+++ b/packages/studio/src/preview/render.ts
@@ -1,13 +1,14 @@
-import type { AudioTrack, Composition } from "@hypit/composition";
+import type { Composition } from "@hypit/composition";
import { compileHyperframesDocument, materializeHyperframesHtml } from "@hypit/hyperframes";
import type { HyperframesDocument } from "@hypit/hyperframes";
-import type { ProgramSpace } from "@hypit/program-space";
+import { compileAudioProgramPlan } from "@hypit/media-pipeline";
+import type { Timeline } from "@hypit/timeline";
import { injectRuntimeShim } from "./runtime-shim.js";
export type RenderInput = {
readonly composition: Composition;
- readonly space: ProgramSpace;
+ readonly timeline: Timeline;
/** Resources Studio can serve for material selected by the Run. */
readonly served?: ReadonlySet<string>;
};
@@ -25,7 +26,7 @@ export function renderPreview(input: RenderInput): string {
/** The same compiled picture serves immediate frame capture and interactive playback. */
export function renderStudioProgramme(input: RenderInput): { readonly document: HyperframesDocument; readonly html: string; readonly preview: string } {
- const document = compileHyperframesDocument(input.composition, input.space);
+ const document = compileHyperframesDocument(input.composition, input.timeline);
const html = materializeHyperframesHtml(document, (artifact) => {
// The only Artifacts a preview can reference are files the author already
// has. Anything else would be a Provider's output, which does not exist yet,
@@ -35,26 +36,25 @@ export function renderStudioProgramme(input: RenderInput): { readonly document:
}
return `/__studio/material/${artifact.resource}`;
});
- const audio = input.composition.tracks
- .filter((track): track is AudioTrack => track.kind === "audio")
- .flatMap((track) => track.clips)
+ const audio = compileAudioProgramPlan(input.composition, input.timeline).clips
.map((clip) => {
if (input.served?.has(clip.artifact.resource) !== true) {
throw new Error(`Preview audio references Artifact ${clip.artifact.resource}, which it cannot serve.`);
}
return `<audio class="hypit-studio-audio" preload="auto"
src="/__studio/material/${clip.artifact.resource}"
- data-start="${clip.target.startSample / 48_000}"
- data-duration="${(clip.target.endSampleExclusive - clip.target.startSample) / 48_000}"
- data-media-start="${clip.source.startSample / 48_000}"
- data-media-end="${clip.source.endSampleExclusive / 48_000}"
- data-loop="${clip.source.loop}"
- data-phase="${clip.source.phaseSample / 48_000}"
+ data-start="${clip.targetStartSample / 48_000}"
+ data-duration="${(clip.targetEndSampleExclusive - clip.targetStartSample) / 48_000}"
+ data-media-start="${clip.sourceStartSample / 48_000}"
+ data-media-end="${clip.sourceEndSampleExclusive / 48_000}"
+ data-loop="${clip.sourceLoop}"
+ data-phase="${clip.sourcePhaseSample / 48_000}"
data-playback-rate="${clip.playbackRate}"
data-gain="${clip.gain}"
- data-presentation="${encodeURIComponent(JSON.stringify({
+ data-level-automation="${encodeURIComponent(JSON.stringify({
gainEnvelope: clip.gainEnvelope, audibility: clip.audibility,
fadeInSamples: clip.fadeInSamples, fadeOutSamples: clip.fadeOutSamples,
+ mixStartSample: clip.mixStartSample, mixEndSampleExclusive: clip.mixEndSampleExclusive,
}))}"></audio>`;
}).join("");
return { document, html, preview: injectRuntimeShim(html, audio) };
diff --git a/packages/studio/src/preview/runtime-shim.ts b/packages/studio/src/preview/runtime-shim.ts
index 94147c3e..183d7dff 100644
--- a/packages/studio/src/preview/runtime-shim.ts
+++ b/packages/studio/src/preview/runtime-shim.ts
@@ -68,7 +68,7 @@ function shim(): string {
phase: parseFloat(element.getAttribute('data-phase') || '0') || 0,
rate: parseFloat(element.getAttribute('data-playback-rate') || '1') || 1,
gain: Number(element.getAttribute('data-gain') ?? '1'),
- presentation: JSON.parse(decodeURIComponent(element.getAttribute('data-presentation') || '%7B%7D'))
+ levelAutomation: JSON.parse(decodeURIComponent(element.getAttribute('data-level-automation') || '%7B%7D'))
});
}
@@ -93,8 +93,9 @@ function shim(): string {
}
var sample = seconds * 48000;
var now = audioContext.currentTime;
- var p = record.presentation;
- var start = record.start * 48000, end = (record.start + record.duration) * 48000;
+ var p = record.levelAutomation;
+ var start = p.mixStartSample ?? record.start * 48000;
+ var end = p.mixEndSampleExclusive ?? (record.start + record.duration) * 48000;
record.nodes[0].gain.setValueAtTime(record.gain, now);
scheduleEnvelope(record.nodes[1].gain, p.gainEnvelope, sample, now);
scheduleEnvelope(record.nodes[2].gain, p.fadeInSamples > 0
@@ -176,7 +177,10 @@ function shim(): string {
continue;
}
var target = record.mediaStart + (local + frameSeconds / 2) * record.rate;
- var discrete = scrubbing || programFrame === record.endFrame - 1;
+ // Browsers do not provide portable negative-rate playback. Reverse remains
+ // an ordinary source-time function: preview it through the same absolute
+ // frame seek used by scrubbing instead of weakening the author model.
+ var discrete = record.sourceRate[0] < 0n || scrubbing || programFrame === record.endFrame - 1;
if (discrete) {
// The renderer floors exact source-frame coordinates. The midpoint of a
// programme frame can cross that source boundary at fractional speeds.
diff --git a/packages/studio/src/programme.ts b/packages/studio/src/programme.ts
index 2be0fb99..21b646c1 100644
--- a/packages/studio/src/programme.ts
+++ b/packages/studio/src/programme.ts
@@ -3,15 +3,10 @@ import type { BlobRef, ResourceId, StoredValue } from "@hypit/protocol";
import { sameType } from "@hypit/protocol";
import type { Composition } from "@hypit/composition";
import { compositionTypes } from "@hypit/composition";
-import {
- projectTimelineSpace,
- semanticAnchorFrames,
- timelineSpans,
-} from "@hypit/timeline";
+import { timelineTypes, assertTimelineIdentity } from "@hypit/timeline";
import type { Timeline } from "@hypit/timeline";
-import { timelineTypes } from "@hypit/timeline";
-import { assertProgramSpaceIdentity } from "@hypit/program-space";
-import type { ProgramSpace } from "@hypit/program-space";
+import { narrativeTemporalTypes } from "@hypit/narrative-temporal";
+import type { NarrativeProjection } from "@hypit/narrative-temporal";
import type { StudioResolvedTrack, StudioTemporalBinding } from "@hypit/studio-adapter";
import type { RuntimeHostTransientExecution } from "@hypit/runtime-host-node";
@@ -43,7 +38,7 @@ export type Preview = {
readonly served: ReadonlyMap<string, ServedFile>;
readonly canvas: { readonly width: number; readonly height: number; readonly clearColor: string };
readonly frameRate: { readonly numerator: number; readonly denominator: number };
- readonly space: ProgramSpace;
+ readonly timeline: Timeline;
readonly anchors: ReadonlyMap<string, number>;
readonly tokens: readonly {
readonly id: string;
@@ -173,12 +168,9 @@ export async function preview(input: {
const timingValue = selectedValue(executed.state, input.timeRef);
if (timingValue?.kind !== "inline" || timingType === undefined) throw new Error("Studio requires a resolved film time source.");
if (!sameType(timingType, timelineTypes.track)) throw new Error("Studio requires the declared Timeline.");
- const semantic = timingValue.value as unknown as Timeline;
- const spans = timelineSpans(semantic);
- const anchors = semanticAnchorFrames(semantic);
- const space = projectTimelineSpace(semantic);
- assertProgramSpaceIdentity(space);
- const rate = space.frameRate;
+ const timeline = timingValue.value as unknown as Timeline;
+ assertTimelineIdentity(timeline);
+ const rate = timeline.frameRate;
const compositionValue = selectedValue(executed.state, input.compositionRef);
if (compositionValue?.kind !== "inline") {
throw new Error("Studio Film composition did not produce an inline Composition.");
@@ -235,6 +227,25 @@ export async function preview(input: {
values.set(record.id, record.value.value);
}
}
+ const narrativeProjections = input.projections.flatMap((view) => view.trace.references
+ .filter((reference) => sameType(reference.typeRef, narrativeTemporalTypes.narrativeProjection))
+ .flatMap((reference) => {
+ const stored = selectedValue(executed.state, reference.ref);
+ return stored?.kind === "inline" ? [stored.value as unknown as NarrativeProjection] : [];
+ }));
+ const anchors = new Map<string, number>();
+ const tokens: Preview["tokens"][number][] = [];
+ const narrativeIds = new Set<string>();
+ for (const projection of narrativeProjections) {
+ if (projection.timelineId !== timeline.id) continue;
+ narrativeIds.add(projection.narrativeId);
+ for (const boundary of projection.boundaries) anchors.set(boundary.id, boundary.frame);
+ tokens.push(...projection.tokens.map((token) => ({
+ id: token.tokenId,
+ startAnchorId: token.startBoundaryId,
+ endAnchorId: token.endBoundaryId,
+ })));
+ }
const timingCandidateId = satisfactions.get(input.timeRef);
return {
source: input.source,
@@ -242,19 +253,15 @@ export async function preview(input: {
values,
temporalBindings,
composition,
- ...(semantic.narrativeId === undefined ? {} : { narrativeId: semantic.narrativeId }),
- timingOutput: { name: timingOutput?.name ?? space.id, ref: input.timeRef },
+ ...(narrativeIds.size === 1 ? { narrativeId: [...narrativeIds][0] } : {}),
+ timingOutput: { name: timingOutput?.name ?? timeline.id, ref: input.timeRef },
...(timingCandidateId === undefined ? {} : { timingCandidateId }),
timingCandidateOrigin: timingCandidateId === undefined ? "source" : "run",
served,
canvas: composition.canvas,
frameRate: rate,
- space,
+ timeline,
anchors,
- tokens: spans.flatMap(({ item }) => item.take.tokens.map((token) => ({
- id: token.tokenId,
- startAnchorId: token.startAnchorId,
- endAnchorId: token.endAnchorId,
- }))),
+ tokens,
};
}
diff --git a/packages/studio/src/server.ts b/packages/studio/src/server.ts
index d7c394ea..ac8e48db 100644
--- a/packages/studio/src/server.ts
+++ b/packages/studio/src/server.ts
@@ -338,7 +338,7 @@ export function studioPlugin(options: StudioPluginOptions): Plugin {
handle.sources?.find((candidate) => candidate.role === role)?.source;
const frame = (value: number): string => `${value}f`;
const semanticFrame = (endpoint: StudioTemporalInstantProjection): number | undefined => {
- if (endpoint.authority.kind !== "semantic" || semanticTarget === undefined || handle.semantic === undefined) return undefined;
+ if (endpoint.authority.kind !== "domain" || semanticTarget === undefined || handle.semantic === undefined) return undefined;
if (endpoint.source.kind === "selection" && semanticTarget.kind === "selection"
&& endpoint.source.id === handle.semantic.id) {
const anchorId = endpoint.authority.boundary === "start"
@@ -354,8 +354,8 @@ export function studioPlugin(options: StudioPluginOptions): Plugin {
};
const projectionBaseFrame = (endpoint: StudioTemporalInstantProjection): number | undefined => {
if (endpoint.reference === "absolute") return undefined;
- if (endpoint.reference === "program.start") return 0;
- if (endpoint.reference === "program.end") return snapshot?.space.frameCount;
+ if (endpoint.reference === "timeline.start") return 0;
+ if (endpoint.reference === "timeline.end") return snapshot?.timeline.frameCount;
const id = endpoint.source.id;
if (id === undefined) return undefined;
if (endpoint.reference === "selection.start" || endpoint.reference === "selection.end") {
@@ -377,7 +377,7 @@ export function studioPlugin(options: StudioPluginOptions): Plugin {
): void => {
if (desired === endpoint.frame) return;
if (endpoint.authority.kind === "fixed") throw new Error(`The ${role} endpoint has no timeline write target.`);
- if (endpoint.authority.kind === "semantic") {
+ if (endpoint.authority.kind === "domain") {
if (semanticFrame(endpoint) !== desired) throw new Error(`The ${role} endpoint does not match its semantic Anchor.`);
return;
}
diff --git a/packages/studio/src/session.ts b/packages/studio/src/session.ts
index 2e757ef2..690ebe02 100644
--- a/packages/studio/src/session.ts
+++ b/packages/studio/src/session.ts
@@ -81,7 +81,7 @@ export async function readStudioSession(input: {
});
const rendered = renderStudioProgramme({
composition: built.composition,
- space: built.space as never,
+ timeline: built.timeline,
served: new Set(built.served.keys()),
});
const text = readFileSync(input.run.authorSource, "utf8");
diff --git a/packages/studio/src/shared.ts b/packages/studio/src/shared.ts
index 5155147d..66389be1 100644
--- a/packages/studio/src/shared.ts
+++ b/packages/studio/src/shared.ts
@@ -268,10 +268,14 @@ export type StudioSnapshot = {
readonly satisfactions: readonly { readonly output: string; readonly candidate: string }[];
};
readonly script?: ScriptMap;
- readonly space: {
- readonly canvasWidth: number;
- readonly canvasHeight: number;
+ /** The resolved picture plane. It is a preview snapshot, not another authored Canvas. */
+ readonly canvas: {
+ readonly width: number;
+ readonly height: number;
readonly clearColor: string;
+ };
+ /** The resolved playback domain. It is derived from the authored Timeline. */
+ readonly timeline: {
readonly frameRate: { readonly numerator: number; readonly denominator: number };
readonly frameCount: number;
readonly durationSec: number;
diff --git a/packages/studio/src/snapshot.ts b/packages/studio/src/snapshot.ts
index 25178cc0..5054efe2 100644
--- a/packages/studio/src/snapshot.ts
+++ b/packages/studio/src/snapshot.ts
@@ -9,7 +9,7 @@ import { relative } from "node:path";
import type { MarkupSurfaceRegistryLike } from "@hypit/markup";
import { compositionTypes } from "@hypit/composition";
-import { programSpaceFrameCount } from "@hypit/program-space";
+import { timelineFrameCount } from "@hypit/timeline";
import { sameModule, sameType } from "@hypit/protocol";
import type {
@@ -35,7 +35,7 @@ type Present = {
readonly id: string;
readonly subjectId?: string;
readonly span: { readonly startFrame: number; readonly endFrameExclusive: number };
- readonly stacking: { readonly order: number };
+ readonly z: number;
};
/** Sound is placed in samples rather than frames, in the canonical 48 kHz. */
@@ -63,7 +63,7 @@ function spans(
...(present.subjectId === undefined ? {} : { subjectId: present.subjectId }),
startFrame: present.span.startFrame,
endFrameExclusive: present.span.endFrameExclusive,
- stackOrder: present.stacking.order,
+ stackOrder: present.z,
}));
}
const perSecond = frameRate.numerator / frameRate.denominator;
@@ -162,7 +162,7 @@ function semanticTimeline(
errors: [],
};
return {
- spaceId: built.space.id,
+ timelineId: built.timeline.id,
narrativeId: built.narrativeId,
// The generic ruler presentation is independent of the authored Timeline id.
presentation: registry.semanticTimelinePresentation(),
@@ -304,7 +304,7 @@ export function snapshot(registry: StudioCompanionRegistry, built: Preview, inpu
// root that produced them in this list.
const rows = tracks.map((track, row) => ({ ...track, row }));
- const frameCount = programSpaceFrameCount(built.space);
+ const frameCount = timelineFrameCount(built.timeline);
return {
revision: input.revision,
source: {
@@ -320,10 +320,12 @@ export function snapshot(registry: StudioCompanionRegistry, built: Preview, inpu
},
run: input.run,
...(script === undefined ? {} : { script }),
- space: {
- canvasWidth: input.canvas.width,
- canvasHeight: input.canvas.height,
+ canvas: {
+ width: input.canvas.width,
+ height: input.canvas.height,
clearColor: input.canvas.clearColor,
+ },
+ timeline: {
frameRate: input.frameRate,
frameCount,
durationSec: frameCount * input.frameRate.denominator / input.frameRate.numerator,
diff --git a/packages/studio/src/temporal-edit.ts b/packages/studio/src/temporal-edit.ts
index e9bcf413..f75c593d 100644
--- a/packages/studio/src/temporal-edit.ts
+++ b/packages/studio/src/temporal-edit.ts
@@ -28,7 +28,7 @@ export function semanticGestureSpan(
const end = byId.get(target.endAnchorId);
if (!start || !end || start.order > end.order) return undefined;
if (temporal.kind === "instant") {
- if (temporal.authority.kind !== "semantic") return undefined;
+ if (temporal.authority.kind !== "domain") return undefined;
if (temporal.authority.boundary === "start" && target.endAnchorId !== semantic.endAnchorId
|| temporal.authority.boundary === "end" && target.startAnchorId !== semantic.startAnchorId) return undefined;
const frame = temporal.authority.boundary === "start" ? start.frame : end.frame;
@@ -111,7 +111,7 @@ export function chooseSemanticGesture(input: {
}
return undefined;
}
- const boundary = temporal.kind === "instant" && temporal.authority.kind === "semantic"
+ const boundary = temporal.kind === "instant" && temporal.authority.kind === "domain"
? temporal.authority.boundary : handle.gesture === "trim-start" ? "start" : "end";
const current = boundary === "start" ? start : end;
const candidates = ranked(anchors, current).sort((a, b) =>
diff --git a/packages/studio/src/temporal-graph.ts b/packages/studio/src/temporal-graph.ts
index c5965386..d52cb0ba 100644
--- a/packages/studio/src/temporal-graph.ts
+++ b/packages/studio/src/temporal-graph.ts
@@ -3,10 +3,8 @@ import type { BuildState, ProducerStep, StoredValue, TypedRecord } from "@hypit/
import { temporalModuleRef, temporalTypes } from "@hypit/temporal";
import type {
StudioTemporalBinding,
- StudioTemporalAuthority,
StudioTemporalInstantProjection,
StudioTemporalProjection,
- StudioTemporalSource,
} from "@hypit/studio-adapter";
type PointExpression = {
@@ -51,70 +49,88 @@ function expression(value: unknown): string {
return point.offset === undefined ? point.ref : `${point.ref}${signed(point.offset)}`;
}
-function source(value: unknown): StudioTemporalSource | undefined {
+function instant(
+ record: TypedRecord | undefined,
+ records: ReadonlyMap<string, TypedRecord>,
+ producers: ReadonlyMap<string, ProducerStep>,
+ fallback?: unknown,
+): StudioTemporalInstantProjection | undefined {
+ const value = record === undefined ? fallback : inline(record.value);
const held = value as {
- readonly spaceId?: unknown;
- readonly narrativeId?: unknown;
- readonly kind?: unknown;
readonly id?: unknown;
- } | undefined;
- if (held?.kind !== "program" && held?.kind !== "selection"
- && held?.kind !== "segment" && held?.kind !== "moment") return undefined;
- if (typeof held.spaceId !== "string" || typeof held.id !== "string") {
- return undefined;
- }
- return {
- spaceId: held.spaceId,
- ...(typeof held.narrativeId === "string" ? { narrativeId: held.narrativeId } : {}),
- kind: held.kind,
- id: held.id,
- };
-}
-
-function instant(value: unknown): StudioTemporalInstantProjection | undefined {
- const held = value as {
- readonly source?: unknown;
- readonly projection?: unknown;
- readonly authority?: {
- readonly kind?: unknown;
- readonly boundary?: unknown;
- readonly binding?: unknown;
- readonly relation?: unknown;
- };
+ readonly timelineId?: unknown;
readonly frame?: unknown;
} | undefined;
- if (held === undefined) return undefined;
- const temporalSource = source(held.source);
- if (temporalSource === undefined || !Number.isSafeInteger(held.frame)) return undefined;
- const point = held.projection as PointExpression | undefined;
- const reference = point?.ref;
- if (reference !== "program.start" && reference !== "program.end"
- && reference !== "selection.start" && reference !== "selection.end"
- && reference !== "segment.start" && reference !== "segment.end"
- && reference !== "moment.cue" && reference !== "absolute") return undefined;
- const authority = held?.authority;
- let resolvedAuthority: StudioTemporalAuthority | undefined;
- if (authority?.kind === "semantic"
- && (authority.boundary === "start" || authority.boundary === "end" || authority.boundary === "cue")) {
- resolvedAuthority = { kind: "semantic", source: temporalSource, boundary: authority.boundary };
- } else if (authority?.kind === "parameter" && typeof authority.binding === "string"
- && (authority.relation === "direct" || authority.relation === "after-start" || authority.relation === "before-end")) {
- resolvedAuthority = { kind: "parameter", binding: authority.binding, relation: authority.relation };
- } else if (authority?.kind === "fixed") {
- resolvedAuthority = { kind: "fixed" };
+ if (typeof held?.id !== "string" || typeof held.timelineId !== "string" || !Number.isSafeInteger(held.frame)) return undefined;
+ const step = record === undefined ? undefined : producers.get(record.id);
+ const specRecord = step?.inputs.spec === undefined ? undefined : records.get(step.inputs.spec);
+ const spec = specRecord === undefined ? undefined : inline(specRecord.value) as {
+ readonly projection?: PointExpression;
+ readonly reference?: unknown;
+ readonly boundary?: unknown;
+ readonly offset?: unknown;
+ } | undefined;
+ if (step?.producer.module.name === temporalModuleRef.name
+ && step.producer.module.version === temporalModuleRef.version
+ && step.producer.name === "project-program-instant"
+ && spec?.projection !== undefined) {
+ const timelineRecord = step.inputs.timeline === undefined ? undefined : records.get(step.inputs.timeline);
+ const timeline = timelineRecord === undefined ? undefined : inline(timelineRecord.value) as { readonly id?: unknown } | undefined;
+ const reference = spec.projection.ref;
+ if (typeof reference !== "string") return undefined;
+ return {
+ kind: "instant",
+ expression: expression(spec.projection),
+ reference,
+ frame: held.frame as number,
+ source: { timelineId: held.timelineId, type: timelineRecord?.type ?? record!.type,
+ kind: "timeline", id: typeof timeline?.id === "string" ? timeline.id : held.timelineId },
+ authority: { kind: "fixed" },
+ };
+ }
+ if (step !== undefined) {
+ const domainInput = Object.entries(step.inputs).find(([name]) =>
+ name !== "timeline" && name !== "projection" && name !== "spec");
+ if (domainInput !== undefined) {
+ const [kind, sourceId] = domainInput;
+ const sourceRecord = records.get(sourceId);
+ const sourceValue = sourceRecord === undefined ? undefined : inline(sourceRecord.value) as {
+ readonly id?: unknown; readonly narrativeId?: unknown;
+ } | undefined;
+ const boundary = typeof spec?.boundary === "string" ? spec.boundary : "point";
+ const reference = typeof spec?.reference === "string"
+ ? spec.reference
+ : `${kind}.${boundary === "cue" ? "cue" : boundary}`;
+ const point = { ref: reference, ...(spec?.offset === undefined ? {} : { offset: spec.offset }) };
+ if (sourceRecord !== undefined && typeof sourceValue?.id === "string") return {
+ kind: "instant",
+ expression: expression(point),
+ reference,
+ frame: held.frame as number,
+ source: { timelineId: held.timelineId, type: sourceRecord.type, kind, id: sourceValue.id,
+ ...(typeof sourceValue.narrativeId === "string" ? { narrativeId: sourceValue.narrativeId } : {}) },
+ authority: { kind: "domain", source: { timelineId: held.timelineId, type: sourceRecord.type,
+ kind, id: sourceValue.id,
+ ...(typeof sourceValue.narrativeId === "string" ? { narrativeId: sourceValue.narrativeId } : {}) }, boundary },
+ };
+ }
}
- if (resolvedAuthority === undefined) return undefined;
+ const type = record?.type ?? temporalTypes.instant;
return {
kind: "instant",
- expression: expression(held.projection),
- reference,
+ expression: `${held.frame as number}f`,
+ reference: "absolute",
frame: held.frame as number,
- source: temporalSource,
- authority: resolvedAuthority,
+ source: { timelineId: held.timelineId, type, kind: "resolved", id: held.id },
+ authority: { kind: "fixed" },
};
}
-function projection(record: TypedRecord): {
+function projection(
+ record: TypedRecord,
+ records: ReadonlyMap<string, TypedRecord>,
+ producers: ReadonlyMap<string, ProducerStep>,
+): {
readonly id: string;
readonly subjectId: string;
readonly projection: StudioTemporalProjection;
@@ -128,11 +144,14 @@ function projection(record: TypedRecord): {
} | undefined;
if (typeof held?.id !== "string" || typeof held.subjectId !== "string") return undefined;
if (sameType(record.type, temporalTypes.instant)) {
- const projected = instant(inline(record.value));
+ const projected = instant(record, records, producers);
return projected === undefined ? undefined : { id: held.id, subjectId: held.subjectId, projection: projected };
}
- const start = instant(held.start);
- const end = instant(held.end);
+ const step = producers.get(record.id);
+ const startRecord = step?.inputs.start === undefined ? undefined : records.get(step.inputs.start);
+ const endRecord = step?.inputs.end === undefined ? undefined : records.get(step.inputs.end);
+ const start = instant(startRecord, records, producers, held.start);
+ const end = instant(endRecord, records, producers, held.end);
if (start === undefined || end === undefined) return undefined;
if (!Number.isSafeInteger(held.span?.startFrame) || !Number.isSafeInteger(held.span?.endFrameExclusive)) return undefined;
return {
@@ -191,7 +210,7 @@ export function executedTemporalBindings(
return [...records.values()]
.filter((record) => sameType(record.type, temporalTypes.instant) || sameType(record.type, temporalTypes.window))
.flatMap((record): readonly StudioTemporalBinding[] => {
- const projected = projection(record);
+ const projected = projection(record, records, producers);
if (projected === undefined) return [];
const consumers = steps.flatMap((step) => Object.entries(step.inputs)
.filter(([, input]) => input === record.id)
diff --git a/packages/studio/src/ui/comments.ts b/packages/studio/src/ui/comments.ts
index 74fbb828..de99f0f6 100644
--- a/packages/studio/src/ui/comments.ts
+++ b/packages/studio/src/ui/comments.ts
@@ -61,7 +61,7 @@ export function createComments(store: Store, stage: Stage) {
const state = store.current();
if (state === undefined) return undefined;
return {
- at: state.playhead.frame * state.snapshot.space.frameRate.denominator / state.snapshot.space.frameRate.numerator,
+ at: state.playhead.frame * state.snapshot.timeline.frameRate.denominator / state.snapshot.timeline.frameRate.numerator,
};
};
const renderAnchor = (): void => {
@@ -81,7 +81,7 @@ export function createComments(store: Store, stage: Stage) {
stage.pause(); stage.showComposition();
const state = store.current();
if (state === undefined) return;
- const frame = Math.round(comment.at * state.snapshot.space.frameRate.numerator / state.snapshot.space.frameRate.denominator);
+ const frame = Math.round(comment.at * state.snapshot.timeline.frameRate.numerator / state.snapshot.timeline.frameRate.denominator);
store.seek(frame, "video");
selected = comment.id;
render();
diff --git a/packages/studio/src/ui/main.ts b/packages/studio/src/ui/main.ts
index eb0db7d2..f78b4e3b 100644
--- a/packages/studio/src/ui/main.ts
+++ b/packages/studio/src/ui/main.ts
@@ -776,7 +776,7 @@ function renderInspector(snapshot: StudioSnapshot, clipId: string | undefined):
if (clip === undefined) {
defaultWorkspaceHeading();
- const fps = snapshot.space.frameRate.numerator / snapshot.space.frameRate.denominator;
+ const fps = snapshot.timeline.frameRate.numerator / snapshot.timeline.frameRate.denominator;
inspector.replaceChildren(
uiGroup("inspector.project", [
property("inspector.author", snapshot.source.path, "property-code"),
@@ -785,13 +785,13 @@ function renderInspector(snapshot: StudioSnapshot, clipId: string | undefined):
property("inspector.tracks", String(snapshot.tracks.length), "property-number"),
]),
uiGroup("inspector.canvas", [
- property("inspector.resolution", `${snapshot.space.canvasWidth} × ${snapshot.space.canvasHeight}`, "property-number"),
- property("inspector.aspect-ratio", aspectRatio(snapshot.space.canvasWidth, snapshot.space.canvasHeight), "property-number"),
+ property("inspector.resolution", `${snapshot.canvas.width} × ${snapshot.canvas.height}`, "property-number"),
+ property("inspector.aspect-ratio", aspectRatio(snapshot.canvas.width, snapshot.canvas.height), "property-number"),
]),
uiGroup("inspector.timeline", [
- property("inspector.duration", `${snapshot.space.durationSec.toFixed(2)} s`, "property-number"),
+ property("inspector.duration", `${snapshot.timeline.durationSec.toFixed(2)} s`, "property-number"),
property("inspector.frame-rate", `${fps.toFixed(Number.isInteger(fps) ? 0 : 2)} fps`, "property-number"),
- property("inspector.frames", String(snapshot.space.frameCount), "property-number"),
+ property("inspector.frames", String(snapshot.timeline.frameCount), "property-number"),
]),
uiGroup("inspector.build", [
property("inspector.targets", snapshot.run.targets
@@ -1094,7 +1094,7 @@ window.addEventListener("keydown", (event) => {
if (event.key === "ArrowLeft" || event.key === ",") store.seek(state.playhead.frame - step, "timeline");
else if (event.key === "ArrowRight" || event.key === ".") store.seek(state.playhead.frame + step, "timeline");
else if (event.key === "Home") store.seek(0, "timeline");
- else if (event.key === "End") store.seek(state.snapshot.space.frameCount - 1, "timeline");
+ else if (event.key === "End") store.seek(state.snapshot.timeline.frameCount - 1, "timeline");
else if (event.key === "Escape") store.clearSelection();
else return;
event.preventDefault();
diff --git a/packages/studio/src/ui/overlay.ts b/packages/studio/src/ui/overlay.ts
index 75f888be..16f82f39 100644
--- a/packages/studio/src/ui/overlay.ts
+++ b/packages/studio/src/ui/overlay.ts
@@ -92,7 +92,7 @@ export function createOverlay(store: Store, measure: Measure): Overlay {
const draw = (): void => {
if (last === undefined) return;
const { snapshot, selected } = last;
- canvas = { width: snapshot.space.canvasWidth, height: snapshot.space.canvasHeight };
+ canvas = { width: snapshot.canvas.width, height: snapshot.canvas.height };
element.setAttribute("viewBox", `0 0 ${canvas.width} ${canvas.height}`);
element.replaceChildren();
// An editing interval can end before its visual representation disappears.
diff --git a/packages/studio/src/ui/scrub-preview.ts b/packages/studio/src/ui/scrub-preview.ts
index 91f38f87..1e43e504 100644
--- a/packages/studio/src/ui/scrub-preview.ts
+++ b/packages/studio/src/ui/scrub-preview.ts
@@ -62,7 +62,7 @@ export function createScrubPreview(container: HTMLElement) {
if (snapshot.revision !== revision) clear();
if (iframe === undefined) {
revision = snapshot.revision;
- const { canvasWidth, canvasHeight } = snapshot.space;
+ const { width: canvasWidth, height: canvasHeight } = snapshot.canvas;
const scale = Math.min(200 / canvasWidth, 170 / canvasHeight);
picture.style.width = `${canvasWidth * scale}px`;
picture.style.height = `${canvasHeight * scale}px`;
@@ -93,7 +93,7 @@ export function createScrubPreview(container: HTMLElement) {
const room = container.getBoundingClientRect();
const left = Math.max(0, Math.min(clientX - room.left - element.offsetWidth / 2, room.width - element.offsetWidth));
element.style.left = `${left}px`;
- time.textContent = feedbackClock(frame * snapshot.space.frameRate.denominator / snapshot.space.frameRate.numerator);
+ time.textContent = feedbackClock(frame * snapshot.timeline.frameRate.denominator / snapshot.timeline.frameRate.numerator);
if (frame !== displayed) {
iframe.style.visibility = "hidden";
uiText(status, "player.frame-loading");
diff --git a/packages/studio/src/ui/selection.ts b/packages/studio/src/ui/selection.ts
index 673e48b7..7016ab75 100644
--- a/packages/studio/src/ui/selection.ts
+++ b/packages/studio/src/ui/selection.ts
@@ -31,7 +31,7 @@ export type Store = {
load(snapshot: StudioSnapshot): void;
/** Select without moving the playhead; timeline inspection must not destroy position. */
select(clipId: string, origin: Origin): void;
- /** Select one authored SemanticTake without moving the playhead. */
+ /** Select one authored semantic relation without moving the playhead. */
selectSemanticSegment(segmentId: string, origin: Origin): void;
/** Select one authored Selection marker without moving the playhead. */
selectSemanticSelection(selectionId: string, origin: Origin): void;
@@ -92,7 +92,7 @@ export function createStore(): Store {
};
const clamp = (frame: number): number =>
- Math.max(0, Math.min(Math.round(frame), (snapshot?.space.frameCount ?? 1) - 1));
+ Math.max(0, Math.min(Math.round(frame), (snapshot?.timeline.frameCount ?? 1) - 1));
return {
current: () => snapshot === undefined ? undefined : { snapshot, selection, playhead },
diff --git a/packages/studio/src/ui/stage.ts b/packages/studio/src/ui/stage.ts
index da393fa9..56a8cb08 100644
--- a/packages/studio/src/ui/stage.ts
+++ b/packages/studio/src/ui/stage.ts
@@ -182,11 +182,11 @@ export function createStage(store: Store, selectedArtifact: (id: string | undefi
};
const fps = (snapshot: StudioSnapshot): number =>
- snapshot.space.frameRate.numerator / snapshot.space.frameRate.denominator;
+ snapshot.timeline.frameRate.numerator / snapshot.timeline.frameRate.denominator;
const fit = (): void => {
if (state === undefined) return;
- const { canvasWidth, canvasHeight } = state.snapshot.space;
+ const { width: canvasWidth, height: canvasHeight } = state.snapshot.canvas;
const room = viewport.getBoundingClientRect();
const scale = Math.min(
(room.width - 28) / canvasWidth,
@@ -221,7 +221,7 @@ export function createStage(store: Store, selectedArtifact: (id: string | undefi
playing = true;
setIcon(playIcon, "pause");
uiAttr(play, "aria-label", "player.pause");
- const total = state.snapshot.space.frameCount;
+ const total = state.snapshot.timeline.frameCount;
const rate = fps(state.snapshot);
fromFrame = state.playhead.frame >= total - 1 ? 0 : state.playhead.frame;
if (ready) (iframe.contentWindow as SeekWindow | null)?.__hypitPlayFrame?.(fromFrame);
@@ -262,7 +262,7 @@ export function createStage(store: Store, selectedArtifact: (id: string | undefi
const box = scrubber.getBoundingClientRect();
// Native range thumbs travel between their centers, not the input edges.
const fraction = Math.max(0, Math.min(1, (event.clientX - box.left - 6) / Math.max(1, box.width - 12)));
- const frame = Math.round(fraction * Math.max(0, state.snapshot.space.frameCount - 1));
+ const frame = Math.round(fraction * Math.max(0, state.snapshot.timeline.frameCount - 1));
scrubPreview.show(state.snapshot, frame, event.clientX);
});
scrubber.addEventListener("pointerleave", scrubPreview.hide);
@@ -301,10 +301,10 @@ export function createStage(store: Store, selectedArtifact: (id: string | undefi
progress.hidden = scrubber.hidden = time.hidden = false;
scrubber.disabled = !ready;
scrubber.step = String(1 / rate);
- scrubber.max = String(Math.max(0, state.snapshot.space.frameCount - 1) / rate);
+ scrubber.max = String(Math.max(0, state.snapshot.timeline.frameCount - 1) / rate);
scrubber.value = String(state.playhead.frame / rate);
uiAttr(scrubber, "aria-label", "player.composition-time");
- time.textContent = `${clock(state.playhead.frame / rate)} / ${clock(state.snapshot.space.frameCount / rate)}`;
+ time.textContent = `${clock(state.playhead.frame / rate)} / ${clock(state.snapshot.timeline.frameCount / rate)}`;
};
scrubber.addEventListener("input", () => {
if (artifactPreview.selected !== undefined) artifactPreview.seek(Number(scrubber.value));
diff --git a/packages/studio/src/ui/timeline.ts b/packages/studio/src/ui/timeline.ts
index fa02ac34..e709ad44 100644
--- a/packages/studio/src/ui/timeline.ts
+++ b/packages/studio/src/ui/timeline.ts
@@ -174,7 +174,7 @@ export function createTimeline(store: Store): Timeline {
const playheadFraction = (): number => {
if (state === undefined) return 0.5;
const shown = zoom.window();
- const at = state.playhead.frame / Math.max(1, state.snapshot.space.frameCount);
+ const at = state.playhead.frame / Math.max(1, state.snapshot.timeline.frameCount);
return Math.max(0, Math.min(1, (at - shown.start) / Math.max(1e-6, shown.end - shown.start)));
};
const zoomOut = (): void => zoom.pinch(playheadFraction(), 1.25);
@@ -185,13 +185,13 @@ export function createTimeline(store: Store): Timeline {
element.querySelector<HTMLButtonElement>("[data-zoom-fit]")!.addEventListener("click", fit);
const fps = (snapshot: StudioSnapshot): number =>
- snapshot.space.frameRate.numerator / snapshot.space.frameRate.denominator;
+ snapshot.timeline.frameRate.numerator / snapshot.timeline.frameRate.denominator;
const snapFrame = (frame: number): number => {
if (state === undefined || lanes.clientWidth <= 0) return frame;
const shown = zoom.window();
const threshold = Math.max(1, Math.ceil(
- (shown.end - shown.start) * state.snapshot.space.frameCount / lanes.clientWidth * 6,
+ (shown.end - shown.start) * state.snapshot.timeline.frameCount / lanes.clientWidth * 6,
));
let nearest = frame;
let distance = threshold + 1;
@@ -213,7 +213,7 @@ export function createTimeline(store: Store): Timeline {
const across = Math.max(0, Math.min(1, (clientX - box.left) / box.width));
const shown = zoom.window();
return Math.floor(
- (shown.start + across * (shown.end - shown.start)) * state.snapshot.space.frameCount,
+ (shown.start + across * (shown.end - shown.start)) * state.snapshot.timeline.frameCount,
);
};
const frameAt = (clientX: number): number => snapFrame(rawFrameAt(clientX));
@@ -240,7 +240,7 @@ export function createTimeline(store: Store): Timeline {
const semanticTarget = (edit: NonNullable<typeof activeEdit>, nextFrame: number) =>
state === undefined ? undefined : chooseSemanticGesture({
anchors: state.snapshot.semantic?.anchors ?? [], handle: edit.handle,
- pointerStart: edit.startFrame, pointerNow: nextFrame, frameCount: state.snapshot.space.frameCount,
+ pointerStart: edit.startFrame, pointerNow: nextFrame, frameCount: state.snapshot.timeline.frameCount,
});
const absoluteWindowTarget = (
@@ -253,7 +253,7 @@ export function createTimeline(store: Store): Timeline {
};
const rawDelta = nextFrame - edit.startFrame;
const delta = Math.max(-edit.clip.startFrame,
- Math.min(state.snapshot.space.frameCount - edit.clip.endFrameExclusive, rawDelta));
+ Math.min(state.snapshot.timeline.frameCount - edit.clip.endFrameExclusive, rawDelta));
if (edit.handle.gesture === "move") return {
startFrame: edit.clip.startFrame + delta,
endFrameExclusive: edit.clip.endFrameExclusive + delta,
@@ -298,7 +298,7 @@ export function createTimeline(store: Store): Timeline {
});
lanes.addEventListener("pointermove", (event) => {
const frame = frameAt(event.clientX);
- const at = place(frame, state?.snapshot.space.frameCount ?? 1, zoom.window()) * lanes.clientWidth;
+ const at = place(frame, state?.snapshot.timeline.frameCount ?? 1, zoom.window()) * lanes.clientWidth;
hover.style.transform = `translate3d(${at}px,0,0)`;
hoverTime.textContent = state === undefined ? "" : frameTimecode(state.snapshot, frame);
hover.classList.add("visible");
@@ -308,8 +308,8 @@ export function createTimeline(store: Store): Timeline {
: frameAt(event.clientX);
const preview = previewWindow(activeEdit, nextFrame);
if (preview !== undefined) {
- const from = place(preview.startFrame, state.snapshot.space.frameCount, zoom.window());
- const to = place(preview.endFrameExclusive, state.snapshot.space.frameCount, zoom.window());
+ const from = place(preview.startFrame, state.snapshot.timeline.frameCount, zoom.window());
+ const to = place(preview.endFrameExclusive, state.snapshot.timeline.frameCount, zoom.window());
activeEdit.node.style.left = `${from * 100}%`;
activeEdit.node.style.width = `max(2px, ${Math.max(0, to - from) * 100}%)`;
}
@@ -388,7 +388,7 @@ export function createTimeline(store: Store): Timeline {
const drawRuler = (snapshot: StudioSnapshot): void => {
ruler.replaceChildren();
- const frameCount = Math.max(1, snapshot.space.frameCount);
+ const frameCount = Math.max(1, snapshot.timeline.frameCount);
const shown = zoom.window();
const visibleFrames = Math.max(1, (shown.end - shown.start) * frameCount);
const widthPx = Math.max(1, lanes.clientWidth);
@@ -410,7 +410,7 @@ export function createTimeline(store: Store): Timeline {
const majorSeconds = secondCandidates.find((candidate) => candidate * pxPerSecond >= 112)
?? secondCandidates.at(-1)!;
const firstSecond = Math.max(0, Math.ceil(startSecond - 1e-6));
- const lastSecond = Math.min(Math.floor(snapshot.space.durationSec), Math.floor(endSecond + 1e-6));
+ const lastSecond = Math.min(Math.floor(snapshot.timeline.durationSec), Math.floor(endSecond + 1e-6));
for (let seconds = firstSecond; seconds <= lastSecond; seconds += 1) {
const frame = Math.min(frameCount, Math.round(seconds * exactRate));
const at = place(frame, frameCount, shown);
@@ -541,8 +541,8 @@ export function createTimeline(store: Store): Timeline {
const intentBand = lane.querySelector<HTMLElement>(".semantic-band-intent")!;
for (const segment of snapshot.semantic.segments) {
- const from = place(segment.startFrame, snapshot.space.frameCount, zoom.window());
- const to = place(segment.endFrameExclusive, snapshot.space.frameCount, zoom.window());
+ const from = place(segment.startFrame, snapshot.timeline.frameCount, zoom.window());
+ const to = place(segment.endFrameExclusive, snapshot.timeline.frameCount, zoom.window());
if (to <= 0 || from >= 1) continue;
const node = document.createElement("button");
node.type = "button";
@@ -571,8 +571,8 @@ export function createTimeline(store: Store): Timeline {
node.addEventListener("dblclick", (event) => {
event.stopPropagation();
zoom.focus(
- segment.startFrame / Math.max(1, snapshot.space.frameCount),
- segment.endFrameExclusive / Math.max(1, snapshot.space.frameCount),
+ segment.startFrame / Math.max(1, snapshot.timeline.frameCount),
+ segment.endFrameExclusive / Math.max(1, snapshot.timeline.frameCount),
);
});
node.addEventListener("keydown", (event) => {
@@ -584,8 +584,8 @@ export function createTimeline(store: Store): Timeline {
segmentBand.append(node);
}
for (const token of snapshot.semantic.tokens) {
- const wordFrom = place(token.startFrame, snapshot.space.frameCount, zoom.window());
- const wordTo = place(token.endFrameExclusive, snapshot.space.frameCount, zoom.window());
+ const wordFrom = place(token.startFrame, snapshot.timeline.frameCount, zoom.window());
+ const wordTo = place(token.endFrameExclusive, snapshot.timeline.frameCount, zoom.window());
if (wordTo <= 0 || wordFrom >= 1) continue;
const word = document.createElement("span");
word.className = "semantic-cell semantic-word";
@@ -622,8 +622,8 @@ export function createTimeline(store: Store): Timeline {
wordBand.append(word);
}
for (const selection of snapshot.semantic.selections) {
- const from = place(selection.startFrame, snapshot.space.frameCount, zoom.window());
- const to = place(selection.endFrameExclusive, snapshot.space.frameCount, zoom.window());
+ const from = place(selection.startFrame, snapshot.timeline.frameCount, zoom.window());
+ const to = place(selection.endFrameExclusive, snapshot.timeline.frameCount, zoom.window());
if (to <= 0 || from >= 1) continue;
const node = document.createElement("button");
node.type = "button";
@@ -649,7 +649,7 @@ export function createTimeline(store: Store): Timeline {
nextSemanticNodes.push({ node, id: selection.id, start: selection.startFrame, end: selection.endFrameExclusive, kind: "selection" });
}
for (const moment of snapshot.semantic.moments) {
- const at = place(moment.frame, snapshot.space.frameCount, zoom.window());
+ const at = place(moment.frame, snapshot.timeline.frameCount, zoom.window());
if (at < 0 || at > 1) continue;
const node = document.createElement("button");
node.type = "button";
@@ -744,8 +744,8 @@ export function createTimeline(store: Store): Timeline {
const laneWidth = lanes.clientWidth;
// Stable order preserves Companion projection order when stack levels tie.
for (const clip of track.clips.filter(clip => clip.band === band.id).sort((a, b) => a.stackOrder - b.stackOrder)) {
- const from = place(clip.startFrame, snapshot.space.frameCount, zoom.window());
- const to = place(clip.endFrameExclusive, snapshot.space.frameCount, zoom.window());
+ const from = place(clip.startFrame, snapshot.timeline.frameCount, zoom.window());
+ const to = place(clip.endFrameExclusive, snapshot.timeline.frameCount, zoom.window());
if (to <= 0 || from >= 1) continue;
const node = document.createElement("button");
node.type = "button";
@@ -862,7 +862,7 @@ export function createTimeline(store: Store): Timeline {
const paint = (): void => {
if (state === undefined) return;
const { snapshot, selection, playhead: head } = state;
- const position = place(head.frame, snapshot.space.frameCount, zoom.window()) * lanes.clientWidth;
+ const position = place(head.frame, snapshot.timeline.frameCount, zoom.window()) * lanes.clientWidth;
if (head.origin === "play" && position > lanes.clientWidth * 0.88 && zoom.window().end < 0.9999) {
zoom.slide(Math.max(0.25, position / Math.max(1, lanes.clientWidth) - 0.18));
return;
diff --git a/packages/studio/test/attribute-groups.test.ts b/packages/studio/test/attribute-groups.test.ts
index 4b75323f..ae71cbf3 100644
--- a/packages/studio/test/attribute-groups.test.ts
+++ b/packages/studio/test/attribute-groups.test.ts
@@ -17,29 +17,8 @@ function fields(text: string, companion: Pick<StudioTrackCompanion, "bindings" |
placement, draft, declarations: companion.bindings! }), companion.inspector!);
}
-test("a grouped mode edit adds and removes dependent attributes without changing other author facts", () => {
- let text = '<a:Item id="music" source={song.media} gain="0.4"/>';
- let field = fields(text).find(field => field.binding === "playback-settings")!;
- assert.deepEqual(field.value, { playback: "once" });
- const stretch = { playback: "stretch", "min-rate": 0.8, "max-rate": 1.2 };
- validateParameterValue(stretch, field.schema!, "Playback");
- assert.throws(() => validateParameterValue({ playback: "stretch" }, field.schema!, "Playback"));
- text = serializeAttributeGroup(field, stretch);
- field = fields(text).find(field => field.binding === "playback-settings")!;
- assert.deepEqual(field.value, stretch);
- text = serializeAttributeGroup(field, { playback: "loop" });
- assert.equal(text, '<a:Item playback="loop" id="music" source={song.media} gain="0.4"/>');
- for (let count = 0; count < 3; count++) {
- field = fields(text).find(field => field.binding === "playback-settings")!;
- text = serializeAttributeGroup(field, stretch);
- field = fields(text).find(field => field.binding === "playback-settings")!;
- text = serializeAttributeGroup(field, { playback: "loop" });
- }
- assert.equal(text, '<a:Item playback="loop" id="music" source={song.media} gain="0.4"/>');
-});
-
test("ordinary Audio defaults have real first-edit endpoints", () => {
- const held = fields('<a:Item id="music" source={song.media}/>');
+ const held = fields('<a:Clip id="music" source={song.media}/>');
assert.deepEqual(held.filter(field => ["gain", "fade-in", "fade-out"].includes(field.binding!)).map(field => [field.binding, field.value, field.edit?.source.prefix]),
[["gain", 1, ' gain="'], ["fade-in", "0f", ' fade-in="'], ["fade-out", "0f", ' fade-out="']]);
});
diff --git a/packages/studio/test/audio-preview.test.ts b/packages/studio/test/audio-preview.test.ts
index 5f0a5da4..a8617368 100644
--- a/packages/studio/test/audio-preview.test.ts
+++ b/packages/studio/test/audio-preview.test.ts
@@ -9,11 +9,11 @@ class Param {
setValueAtTime(value: number, time: number) { this.events.push({ kind: "set", value, time }); }
linearRampToValueAtTime(value: number, time: number) { this.events.push({ kind: "ramp", value, time }); }
}
-function player(gain: number, presentation: object = {}) {
+function player(gain: number, levelAutomation: object = {}) {
const nodes: { gain: Param; connect: () => void }[] = [];
const attrs: Record<string,string> = {
"data-start": "0", "data-duration": "4", "data-media-start": "0", "data-media-end": "4",
- "data-gain": String(gain), "data-presentation": encodeURIComponent(JSON.stringify(presentation)),
+ "data-gain": String(gain), "data-level-automation": encodeURIComponent(JSON.stringify(levelAutomation)),
};
const audio = { getAttribute: (name: string) => attrs[name] ?? null, currentTime: 0, readyState: 4,
paused: true, volume: 0, muted: false, pause() { this.paused = true; },
diff --git a/packages/studio/test/material-companions.test.ts b/packages/studio/test/material-companions.test.ts
index bc7e4720..0aaa4144 100644
--- a/packages/studio/test/material-companions.test.ts
+++ b/packages/studio/test/material-companions.test.ts
@@ -2,14 +2,14 @@ import assert from "node:assert/strict";
import test from "node:test";
import { compositionTypes } from "@hypit/composition";
import { audioTrackTypes } from "@hypit/audio-track";
-import { mediaTrackTypes } from "@hypit/media-track";
+import { visualTrackTypes } from "@hypit/visual-track";
import type { StudioTrackCompanionContext } from "@hypit/studio-adapter";
import { audioTrackStudioTrackCompanions } from "../../audio-track-studio/src/index.js";
-import { mediaTrackStudioTrackCompanions } from "../../media-track-studio/src/index.js";
+import { visualTrackStudioTrackCompanions } from "../../visual-track-studio/src/index.js";
-for (const kind of ["audio", "media"] as const) {
- test(`${kind} Item titles use explicit author names or exact source references without changing identity`, () => {
- const sourceType = kind === "audio" ? audioTrackTypes.clipSpec : mediaTrackTypes.itemSpec;
+for (const kind of ["audio", "visual"] as const) {
+ test(`${kind} Clip titles use explicit author names or exact source references without changing identity`, () => {
+ const sourceType = kind === "audio" ? audioTrackTypes.clipSpec : visualTrackTypes.clipSpec;
const subjects = ["my-chosen-name", "track.item.0002", "track.item.0003"];
const child = (id: string, index: number) => ({
...(index === 0 ? { id } : {}),
@@ -18,16 +18,15 @@ for (const kind of ["audio", "media"] as const) {
range: { start: index * 10, end: index * 10 + 9 },
values: [{ type: sourceType, value: { id } }],
});
- const program = {
- items: subjects.map((id, index) => ({
+ const clips = subjects.map((id, index) => ({
id: `projected.${index}`, subjectId: id,
window: { startFrame: index * 10, endFrameExclusive: index * 10 + 20 },
span: { startFrame: index * 10, endFrameExclusive: index * 10 + 20 },
- stacking: { order: index },
+ order: index, z: index,
source: { artifact: { resource: "res_audio" } },
layers: [{ kind: "sample", id: "picture", source: { kind: "still", artifact: { resource: "res_image" } } }],
- })), sequences: [],
- };
+ }));
+ const program = { id: `track.${kind}`, clips };
const context = {
track: { outputRef: `track.${kind}`, typeRef: kind === "audio" ? compositionTypes.audioTrack : compositionTypes.visualTrack,
trace: { outputPorts: [{ name: "program", ref: "track.program" }] } },
@@ -35,7 +34,7 @@ for (const kind of ["audio", "media"] as const) {
values: new Map([["track.program", program]]), spans: [], temporalBindings: [],
} as unknown as StudioTrackCompanionContext;
const companion = kind === "audio" ? audioTrackStudioTrackCompanions[0]!
- : mediaTrackStudioTrackCompanions.find((entry) => entry.id === "visual")!;
+ : visualTrackStudioTrackCompanions.find((entry) => entry.id === "visual")!;
const entities = companion.project!(context);
assert.deepEqual(entities.map((entry) => entry.display.title), ["my-chosen-name", "assets.shared.material", "assets.shared.material"]);
assert.deepEqual(entities.map((entry) => entry.authoredId), subjects);
@@ -45,11 +44,11 @@ for (const kind of ["audio", "media"] as const) {
});
}
-test("audio playback is one attribute group and gain stays a bounded mixing control", () => {
+test("audio source time stays explicit and gain remains a bounded mixing control", () => {
const companion = audioTrackStudioTrackCompanions[0]!;
- const group = companion.bindings!.find(binding => binding.name === "playback-settings")!;
- assert.deepEqual(group.attributes, ["playback", "min-rate", "max-rate"]);
- assert.equal(companion.inspector!.find(field => field.binding === group.name)?.domain, "when");
+ const sourceTime = companion.bindings!.find(binding => binding.name === "source-time")!;
+ assert.equal(sourceTime.writable, undefined);
+ assert.equal(companion.inspector!.some(field => field.binding === sourceTime.name), false);
const gain = companion.inspector!.find(field => field.binding === "gain")!;
assert.equal(gain.domain, "how"); assert.equal(gain.number?.scale, 100); assert.equal(gain.number?.maximum, 6400);
});
diff --git a/packages/studio/test/parameters.test.ts b/packages/studio/test/parameters.test.ts
index d9bb7403..40bdf188 100644
--- a/packages/studio/test/parameters.test.ts
+++ b/packages/studio/test/parameters.test.ts
@@ -11,7 +11,10 @@ import type { MarkupSurfaceRegistryLike, RegisteredSurface } from "@hypit/markup
import { inspectorFieldsForBindings, resolveTimelineEditHandles, sourceBindingsForDraft } from "../src/parameters.js";
import { serializeParameterValue, validateParameterValue } from "../src/parameter-values.js";
-const temporalIdentity = { spaceId: "speech", narrativeId: "story" } as const;
+const temporalIdentity = { timelineId: "speech", narrativeId: "story" } as const;
+const narrativeSourceIdentity = { ...temporalIdentity,
+ type: { module: { name: "@hypit/narrative", version: "1" }, name: "NarrativeReference" } } as const;
+const timelineSourceType = { module: { name: "@hypit/timeline", version: "1" }, name: "Timeline" } as const;
const semantic: StudioSemanticTimeline = {
...temporalIdentity,
@@ -53,13 +56,13 @@ test("timeline gestures resolve through the shared Selection identity", () => {
kind: "window",
start: {
kind: "instant", expression: "selection.start", reference: "selection.start", frame: 0,
- source: { ...temporalIdentity, kind: "selection", id: "claim" },
- authority: { kind: "semantic", source: { ...temporalIdentity, kind: "selection", id: "claim" }, boundary: "start" },
+ source: { ...narrativeSourceIdentity, kind: "selection", id: "claim" },
+ authority: { kind: "domain", source: { ...narrativeSourceIdentity, kind: "selection", id: "claim" }, boundary: "start" },
},
end: {
kind: "instant", expression: "selection.end", reference: "selection.end", frame: 12,
- source: { ...temporalIdentity, kind: "selection", id: "claim" },
- authority: { kind: "semantic", source: { ...temporalIdentity, kind: "selection", id: "claim" }, boundary: "end" },
+ source: { ...narrativeSourceIdentity, kind: "selection", id: "claim" },
+ authority: { kind: "domain", source: { ...narrativeSourceIdentity, kind: "selection", id: "claim" }, boundary: "end" },
},
startFrame: 0,
endFrameExclusive: 12,
@@ -86,8 +89,8 @@ test("moving a Moment projection resolves to the shared Moment identity", () =>
const handles = resolveTimelineEditHandles([], {
projection: {
kind: "instant", expression: "moment.cue", reference: "moment.cue", frame: 12,
- source: { ...temporalIdentity, kind: "moment", id: "beat" },
- authority: { kind: "semantic", source: { ...temporalIdentity, kind: "moment", id: "beat" }, boundary: "cue" },
+ source: { ...narrativeSourceIdentity, kind: "moment", id: "beat" },
+ authority: { kind: "domain", source: { ...narrativeSourceIdentity, kind: "moment", id: "beat" }, boundary: "cue" },
},
phases: [],
}, {
@@ -115,17 +118,17 @@ test("at/for and until/for derive complementary semantic and duration inverses",
};
const moment = {
kind: "instant" as const, expression: "moment.cue", reference: "moment.cue" as const, frame: 12,
- source: { ...temporalIdentity, kind: "moment" as const, id: "beat" },
- authority: { kind: "semantic" as const, source: { ...temporalIdentity, kind: "moment" as const, id: "beat" }, boundary: "cue" as const },
+ source: { ...narrativeSourceIdentity, kind: "moment" as const, id: "beat" },
+ authority: { kind: "domain" as const, source: { ...narrativeSourceIdentity, kind: "moment" as const, id: "beat" }, boundary: "cue" as const },
};
const after = {
kind: "instant" as const, expression: "moment.cue+8f", reference: "moment.cue" as const, frame: 20,
- source: { ...temporalIdentity, kind: "moment" as const, id: "beat" },
+ source: { ...narrativeSourceIdentity, kind: "moment" as const, id: "beat" },
authority: { kind: "parameter" as const, binding: "for", relation: "after-start" as const },
};
const before = {
kind: "instant" as const, expression: "moment.cue-8f", reference: "moment.cue" as const, frame: 4,
- source: { ...temporalIdentity, kind: "moment" as const, id: "beat" },
+ source: { ...narrativeSourceIdentity, kind: "moment" as const, id: "beat" },
authority: { kind: "parameter" as const, binding: "for", relation: "before-end" as const },
};
const atFor = resolveTimelineEditHandles([duration], {
@@ -168,11 +171,11 @@ test("absolute Window edits work without a semantic lane and use the Companion's
projection: {
kind: "window",
start: {
- kind: "instant", expression: "1f", reference: "absolute", frame: 1, source: { spaceId: "animation", kind: "program", id: "program" },
+ kind: "instant", expression: "1f", reference: "absolute", frame: 1, source: { timelineId: "animation", type: timelineSourceType, kind: "timeline", id: "animation" },
authority: { kind: "parameter", binding: "from", relation: "direct" },
},
end: {
- kind: "instant", expression: "20f", reference: "absolute", frame: 20, source: { spaceId: "animation", kind: "program", id: "program" },
+ kind: "instant", expression: "20f", reference: "absolute", frame: 20, source: { timelineId: "animation", type: timelineSourceType, kind: "timeline", id: "animation" },
authority: { kind: "parameter", binding: "until", relation: "direct" },
},
startFrame: 1, endFrameExclusive: 20,
@@ -199,7 +202,7 @@ test("independent reference endpoints expose local edits without claiming their
kind: "instant" as const, expression: index === 0 ? "selection.start" : "moment.cue",
reference: index === 0 ? "selection.start" as const : "moment.cue" as const,
frame: index === 0 ? 2 : 20,
- source: { ...temporalIdentity, kind: index === 0 ? "selection" as const : "moment" as const, id: index === 0 ? "claim" : "beat" },
+ source: { ...narrativeSourceIdentity, kind: index === 0 ? "selection" as const : "moment" as const, id: index === 0 ? "claim" : "beat" },
authority: { kind: "parameter" as const, binding: name, relation: "direct" as const },
}));
const bindings = (["start", "end"] as const).map((name, index) => ({
diff --git a/packages/studio/test/preflight.test.ts b/packages/studio/test/preflight.test.ts
index 4500c7a8..1c7fee18 100644
--- a/packages/studio/test/preflight.test.ts
+++ b/packages/studio/test/preflight.test.ts
@@ -1,9 +1,8 @@
-import { programSpaceTypes } from "@hypit/program-space";
+import { timelineTypes } from "@hypit/timeline";
import assert from "node:assert/strict";
import test from "node:test";
import { compositionTypes } from "@hypit/composition";
-import { timelineTypes } from "@hypit/timeline";
import type { StudioFilmCompanion, StudioPlacement } from "@hypit/studio-adapter";
import type { CompiledSource } from "../src/compile.js";
@@ -15,7 +14,7 @@ const filmModule = { name: "@example/film", version: "1" } as const;
const companion: StudioFilmCompanion = {
id: "film",
match: { module: filmModule, surface: "film", outputType: compositionTypes.composition },
- timeSources: [{ attribute: "semantic", type: timelineTypes.track }, { attribute: "space", type: programSpaceTypes.programSpace }],
+ timeSources: [{ attribute: "semantic", type: timelineTypes.track }, { attribute: "space", type: timelineTypes.track }],
tracks: { childSurface: "Track", sourceAttribute: "source", types: [compositionTypes.visualTrack] },
};
diff --git a/packages/studio/test/semantic-gesture.test.ts b/packages/studio/test/semantic-gesture.test.ts
index a4e3b0ad8..37192b08 100644
--- a/packages/studio/test/semantic-gesture.test.ts
+++ b/packages/studio/test/semantic-gesture.test.ts
@@ -9,13 +9,14 @@ import { chooseSemanticGesture, formatTemporalPointEdit, semanticGestureSpan } f
const source = '<one><HOST>@{proof} One two @{/proof} three.</one>';
const narrative = parseScript("gesture", source);
// Duplicate word/Segment boundaries count as one stop, not additional movement steps.
-const frames = [0, 0, 0, 5, 10, 20, 40, 55, 55, 55];
+const frames = [0, 0, 5, 10, 20, 40, 55, 55];
const anchors: readonly StudioSemanticAnchor[] = narrative.semanticIndex.anchors.map((anchor, index) => ({ ...anchor, frame: frames[index]! }));
const selection = narrative.selections[0]!;
-const temporalSource = { kind: "selection", id: "proof", narrativeId: "story", spaceId: "film" } as const;
+const narrativeType = { module: { name: "@hypit/narrative", version: "1" }, name: "NarrativeReference" } as const;
+const temporalSource = { kind: "selection", id: "proof", narrativeId: "story", timelineId: "film", type: narrativeType } as const;
const endpoint = (boundary: "start" | "end", frame: number): StudioTemporalInstantProjection => ({
kind: "instant", expression: `selection.${boundary}`, reference: `selection.${boundary}`, source: temporalSource, frame,
- authority: { kind: "semantic", source: temporalSource, boundary },
+ authority: { kind: "domain", source: temporalSource, boundary },
});
const handle: StudioEditHandle = {
id: "move", operation: "timeline.adjust", gesture: "move", enabled: true,
@@ -60,7 +61,7 @@ test("a directly selected boundary remains editable even when the raw range reve
test("dragging a bound Moment keeps an event-and-duration Window intact", () => {
const momentSource = { ...temporalSource, kind: "moment", id: "beat" } as const;
const moment: StudioTemporalInstantProjection = { kind: "instant", frame: 20, expression: "moment.cue", reference: "moment.cue", source: momentSource,
- authority: { kind: "semantic", source: momentSource, boundary: "cue" } };
+ authority: { kind: "domain", source: momentSource, boundary: "cue" } };
const timed: StudioEditHandle = { ...handle, semantic: { kind: "moment", id: "beat", narrativeId: "story", anchorId: selection.endAnchorId }, temporal: {
kind: "window", start: moment, end: { ...moment, frame: 28, authority: { kind: "parameter", binding: "for", relation: "after-start" } },
startFrame: 20, endFrameExclusive: 28,
@@ -79,10 +80,10 @@ test("offset edits cross zero without losing the explicit editable parameter", (
test("clock expressions retain units until edited and edited values reproject to the exact frame", () => {
for (const frameRate of [{ numerator: 30, denominator: 1 }, { numerator: 60, denominator: 1 }, { numerator: 30000, denominator: 1001 }]) {
- const space = { id: "clock", durationSec: 300 * frameRate.denominator / frameRate.numerator, frameRate };
+ const space = { id: "clock", frameCount: 300, frameRate };
const locate = (value: string) => projectProgramInstant({
- itemId: "point", subjectId: "point", timeline: { ...space, items: [] },
- projection: parseTemporalInstant(value, "point"), authority: { kind: "parameter", binding: "instant", relation: "direct" },
+ itemId: "point", subjectId: "point", timeline: { ...space },
+ projection: parseTemporalInstant(value, "point") as import("@hypit/temporal").TemporalInstantExpression,
}).frame;
assert.equal(locate("2s"), Math.round(2 * frameRate.numerator / frameRate.denominator));
assert.equal(locate("60f"), 60);
@@ -90,8 +91,8 @@ test("clock expressions retain units until edited and edited values reproject to
for (const delta of [3, -2, 0]) {
const desired = original + delta;
assert.equal(locate(formatTemporalPointEdit("absolute", desired)), desired);
- const base = locate("program.end");
- assert.equal(locate(formatTemporalPointEdit("program.end", desired, base)), desired);
+ const base = locate("timeline.end");
+ assert.equal(locate(formatTemporalPointEdit("timeline.end", desired, base)), desired);
}
}
});
diff --git a/packages/studio/test/snapshot-range.test.ts b/packages/studio/test/snapshot-range.test.ts
index 9a2ba351..1d34e2fc 100644
--- a/packages/studio/test/snapshot-range.test.ts
+++ b/packages/studio/test/snapshot-range.test.ts
@@ -9,16 +9,16 @@ import { fallbackStudioTrackCompanions } from "../src/fallback-companions.js";
test("a pure-MG work keeps its declared extent even when an editor entity extends beyond it", () => {
const built = { source: { observations: { placements: [], sourceMaps: [] } },
tracks: [{ outputRef: "art.visual", name: "art.visual", typeRef: compositionTypes.visualTrack,
- trace: { outputPorts: [], references: [] }, candidateOrigin: "source", value: { presents: [{ id: "scene", span: { startFrame: 0, endFrameExclusive: 150 }, stacking: { order: 0 } }] } }],
- space: { id: "work", durationSec: 3, frameRate: { numerator: 30, denominator: 1 } },
+ trace: { outputPorts: [], references: [] }, candidateOrigin: "source", value: { presents: [{ id: "scene", order: 0, z: 0, span: { startFrame: 0, endFrameExclusive: 150 } }] } }],
+ timeline: { id: "work", frameCount: 90, frameRate: { numerator: 30, denominator: 1 } },
values: new Map(), temporalBindings: new Map(),
} as unknown as Preview;
const result = snapshot(new StudioCompanionRegistry(fallbackStudioTrackCompanions), built, {
revision: 1, path: "main.svml", text: "", run: { path: "main.svrun", targets: [], satisfactions: [] },
- canvas: { width: 1080, height: 1920, clearColor: "#000000" }, frameRate: built.space.frameRate,
+ canvas: { width: 1080, height: 1920, clearColor: "#000000" }, frameRate: built.timeline.frameRate,
preview: { kind: "hyperframes", srcdoc: "" }, workspaceRoot: "/project", sourceFiles: [], surfaces: {} as never,
});
- assert.equal(result.space.frameCount, 90); assert.equal(result.space.durationSec, 3);
+ assert.equal(result.timeline.frameCount, 90); assert.equal(result.timeline.durationSec, 3);
assert.equal(result.tracks[0]!.clips[0]!.endFrameExclusive, 150);
assert.equal(result.semantic, undefined);
assert.equal("timing" in result.provenance, false);
diff --git a/packages/studio/test/studio-trace.test.ts b/packages/studio/test/studio-trace.test.ts
index 5470394e..8099d76b 100644
--- a/packages/studio/test/studio-trace.test.ts
+++ b/packages/studio/test/studio-trace.test.ts
@@ -2,7 +2,7 @@ import assert from "node:assert/strict";
import test from "node:test";
import { compositionTypes } from "@hypit/composition";
-import { narrativeTypes } from "@hypit/narrative";
+import { captionTypes } from "@hypit/caption";
import type { CompiledSource } from "../src/compile.js";
import { traceFor } from "../src/studio-trace.js";
@@ -13,7 +13,7 @@ test("Track traces retain direct references to author Records", () => {
program: {
records: [{
id: "source::record::story.caption",
- type: narrativeTypes.captionDocument,
+ type: captionTypes.document,
value: { kind: "inline", value: {} },
}],
},
@@ -25,7 +25,7 @@ test("Track traces retain direct references to author Records", () => {
},
observations: {
placements: [{
- tag: "caption-fine:Track",
+ tag: "caption-fine:Caption",
surface: "track",
module: { name: "@hypit/caption-fine", version: "1" },
id: "captions",
@@ -47,7 +47,7 @@ test("Track traces retain direct references to author Records", () => {
input: "document",
name: "story.caption",
ref: "source::record::story.caption",
- type: narrativeTypes.captionDocument.name,
- typeRef: narrativeTypes.captionDocument,
+ type: captionTypes.document.name,
+ typeRef: captionTypes.document,
}]);
});
diff --git a/packages/studio/test/temporal-graph.test.ts b/packages/studio/test/temporal-graph.test.ts
index 83cdca74..952e72d8 100644
--- a/packages/studio/test/temporal-graph.test.ts
+++ b/packages/studio/test/temporal-graph.test.ts
@@ -17,29 +17,28 @@ const step = (id: string, owner: string, name: string, inputs: ProducerStep["inp
test("Studio reads Instant lineage and author authority from executed graph edges", () => {
const program = [
- record("semantic", "@hypit/timeline", "Timeline", { id: "speech" }),
- record("moment", "@hypit/narrative", "NarrativeMoment", { id: "cue", anchorId: "cue-anchor" }),
- record("point-spec", "@hypit/temporal", "TemporalInstantSpec", {
- id: "deck.card", subjectId: "card", projection: { ref: "moment.cue" }, authority: { kind: "semantic", boundary: "cue" },
+ record("timeline", "@hypit/timeline", "Timeline", { id: "speech", frameRate: { numerator: 30, denominator: 1 }, frameCount: 100 }),
+ record("projection", "@hypit/narrative-temporal", "NarrativeProjection", { id: "story-on-speech", narrativeId: "story", timelineId: "speech", segments: [], tokens: [], boundaries: [] }),
+ record("moment", "@hypit/narrative", "NarrativeMoment", { narrativeId: "story", id: "cue", anchorId: "cue-anchor" }),
+ record("point-spec", "@hypit/narrative-temporal", "NarrativeInstantSpec", {
+ id: "deck.card::cue", subjectId: "card", boundary: "cue",
}),
- record("card-spec", "@hypit/deck-track", "DepthStackCardSpec", { id: "card" }),
+ record("card-spec", "@hypit/depth-stack", "DepthStackCardSpec", { id: "card" }),
];
const executed = [
record("point", "@hypit/temporal", "TemporalInstant", {
- id: "deck.card::cue", subjectId: "card", source: { spaceId: "speech", narrativeId: "story", kind: "moment", id: "cue" }, projection: { ref: "moment.cue" },
- authority: { kind: "semantic", boundary: "cue" }, frame: 42,
+ id: "deck.card::cue", subjectId: "card", timelineId: "speech", frame: 42,
}),
- record("cards", "@hypit/deck-track", "DepthStackCardSet", { cards: [{ id: "card", activationFrame: 42 }] }),
+ record("cards", "@hypit/depth-stack", "DepthStackCardSet", { cards: [{ id: "card", activationFrame: 42 }] }),
record("track", "@hypit/composition", "VisualTrack", { presents: [] }),
record("unused-point", "@hypit/temporal", "TemporalInstant", {
- id: "unused::cue", subjectId: "unused", source: { spaceId: "speech", narrativeId: "story", kind: "moment", id: "cue" }, projection: { ref: "moment.cue" },
- authority: { kind: "semantic", boundary: "cue" }, frame: 7,
+ id: "unused::cue", subjectId: "unused", timelineId: "speech", frame: 7,
}),
];
const steps = [
- step("project", "@hypit/temporal", "project-moment-instant", { semantic: "semantic", moment: "moment", spec: "point-spec" }, { instant: "point" }),
- step("append", "@hypit/deck-track", "append-depth-stack-card", { set: "empty", spec: "card-spec", activation: "point" }, { set: "cards" }),
- step("render", "@hypit/deck-track", "render-depth-stack", { program: "cards" }, { track: "track" }),
+ step("project", "@hypit/narrative-temporal", "project-moment-instant", { timeline: "timeline", projection: "projection", moment: "moment", spec: "point-spec" }, { instant: "point" }),
+ step("append", "@hypit/depth-stack", "append-depth-stack-card", { set: "empty", spec: "card-spec", activation: "point" }, { set: "cards" }),
+ step("render", "@hypit/depth-stack", "render-depth-stack", { program: "cards" }, { track: "track" }),
];
const state = {
format: "hypit.build@1",
@@ -61,17 +60,17 @@ test("Studio reads Instant lineage and author authority from executed graph edge
id: "deck.card::cue",
projection: {
kind: "instant", expression: "moment.cue", reference: "moment.cue", frame: 42,
- source: { spaceId: "speech", narrativeId: "story", kind: "moment", id: "cue" },
- authority: { kind: "semantic", source: { spaceId: "speech", narrativeId: "story", kind: "moment", id: "cue" }, boundary: "cue" },
+ source: { timelineId: "speech", narrativeId: "story", type: type("@hypit/narrative", "NarrativeMoment"), kind: "moment", id: "cue" },
+ authority: { kind: "domain", source: { timelineId: "speech", narrativeId: "story", type: type("@hypit/narrative", "NarrativeMoment"), kind: "moment", id: "cue" }, boundary: "cue" },
},
consumers: [{
step: "append",
- producer: producer("@hypit/deck-track", "append-depth-stack-card"),
+ producer: producer("@hypit/depth-stack", "append-depth-stack-card"),
input: "activation",
role: "domain",
inputs: [
{ name: "activation", record: "point", type: type("@hypit/temporal", "TemporalInstant"), value: executed[0]!.value.kind === "inline" ? executed[0]!.value.value : undefined },
- { name: "spec", record: "card-spec", type: type("@hypit/deck-track", "DepthStackCardSpec"), value: { id: "card" } },
+ { name: "spec", record: "card-spec", type: type("@hypit/depth-stack", "DepthStackCardSpec"), value: { id: "card" } },
],
}],
});
diff --git a/packages/studio/test/video-preview.test.ts b/packages/studio/test/video-preview.test.ts
index 964e2169..8ac62dfd 100644
--- a/packages/studio/test/video-preview.test.ts
+++ b/packages/studio/test/video-preview.test.ts
@@ -68,3 +68,36 @@ test("preview keeps a compact zero-rate sampling interval paused on its source f
assert.equal(plays, 0, "a held interval never hands its clock to native video playback");
assert.ok(pauses >= 3);
});
+
+test("preview evaluates reverse source time by absolute frame without assigning a negative browser rate", async () => {
+ const attrs: Record<string, string> = {
+ "data-start": "0", "data-duration": "1", "data-media-start": String(9.5 / 30), "data-playback-rate": "-1",
+ "data-hypit-start-frame": "0", "data-hypit-end-frame": "10", "data-hypit-source-frame": "9/1",
+ "data-hypit-source-rate": "-1/1", "data-hypit-source-fps": "30/1",
+ };
+ const listeners = new Map<string, () => void>();
+ let currentTime = 0;
+ let plays = 0;
+ let assignedRate: number | undefined;
+ const video = { style: {}, readyState: 4, duration: 10, paused: true,
+ getAttribute: (name: string) => attrs[name] ?? null, closest: () => null,
+ get currentTime() { return currentTime; },
+ set currentTime(value: number) { currentTime = value; queueMicrotask(() => listeners.get("seeked")?.()); },
+ set playbackRate(value: number) { assignedRate = value; },
+ pause() {}, play() { plays += 1; return Promise.resolve(); },
+ addEventListener(name: string, listener: () => void) { listeners.set(name, listener); },
+ removeEventListener(name: string) { listeners.delete(name); },
+ };
+ const root = { style: {}, getAttribute: (name: string) => ({ "data-fps": "30", "data-composition-id": "test" })[name] ?? null };
+ const window: Record<string, any> = { addEventListener() {}, dispatchEvent() {} };
+ const html = injectRuntimeShim("").trim();
+ vm.runInNewContext(html.slice("<script>".length, -"</script>".length), {
+ window, document: { querySelector: () => root,
+ querySelectorAll: (selector: string) => selector === ".hypit-visual-present video" ? [video] : [] },
+ CustomEvent: class {},
+ });
+ await window.__hypitPlayFrame(3);
+ assert.equal(currentTime, 6.5 / 30);
+ assert.equal(assignedRate, undefined);
+ assert.equal(plays, 0);
+});
diff --git a/packages/temporal-markup/EDITING.md b/packages/temporal-markup/EDITING.md
index 32105826..44e00cec 100644
--- a/packages/temporal-markup/EDITING.md
+++ b/packages/temporal-markup/EDITING.md
@@ -1,183 +1,43 @@
# Author-directed time editing
-The shared temporal author forms declare what Studio can edit. The tables below describe their
-implemented behavior; a component's Companion also supplies the actual Source bindings.
-The runtime projection types remain `@1`.
+Studio edits the declaration that produced an absolute time value; it does not ask the consuming
+component to reverse an arbitrary projection.
-## Relationships, expressions, and resolved time
-
-Selection and Moment name relationships in a Narrative. A Selection names two anchors; a Moment
-names one. Neither carries a duration measured in seconds. Segment and Program boundaries retain
-their structural meaning alongside word boundaries.
-
-A temporal expression describes how to obtain time from those relationships or from a clock.
-Projection resolves that description in a ProgramSpace. Its products are TemporalInstant and
-TemporalWindow, which a component consumes to implement its own schedule and appearance.
-
-In temporal author attributes, `{story.moment.reveal}` is a direct typed reference. Quoted values
-such as `"2s"` and `"moment.cue + 2f"` are clock descriptions. Quotation marks do not themselves
-produce an Instant or Window, and braces elsewhere in SVML can reference any public value type.
-Both semantic references and clock descriptions reach consumers through temporal projection.
-The consumer's role determines whether one Instant or a Window is needed.
-
-The editing rule is: **edit the relationship or parameter the author exposed, preserving the
-relationship they chose to depend on.** Knowing where a result came from does not by itself grant
-an inverse that changes that source.
-
-## Direct bindings
+## Direct absolute construction
| Author form | Move | Leading edge | Trailing edge |
| --- | --- | --- | --- |
-| `during={story.selection.proof}` | Move both Selection anchors by the same number of semantic stops; duration may change. | Change its start anchor. | Change its end anchor. |
-| `at={story.moment.reveal}` for an Instant | Change the Moment anchor. | Not applicable. | Not applicable. |
-| `at={story.selection.proof} boundary="start"` for an Instant | Change only the Selection start anchor. | Not applicable. | Not applicable. |
-| `at={story.selection.proof} boundary="end"` for an Instant | Change only the Selection end anchor. | Not applicable. | Not applicable. |
-| `during={story.segment.opening}` or `during="program"` | Follow the structural span; no timeline write. | No timeline write. | No timeline write. |
-| A directly selected Segment boundary | Follow that structural boundary; no timeline write. | Not applicable. | Not applicable. |
-
-A shared Selection or Moment is edited once in Script. All its consumers follow after compilation.
-An item's placement in a track does not make its own private copy of that relationship.
-
-Word starts, word ends, Segment starts, and Segment ends are equally eligible semantic anchors.
-Selection starts do not inherently prefer word starts; Selection ends do not inherently prefer
-word ends. Endpoints can include pauses by referring to the appropriate neighboring anchor.
-
-## An event and a duration
-
-These forms expose two independent decisions: an event or clock position, and a duration.
-
-| Author form | Move | Leading edge | Trailing edge |
-| --- | --- | --- | --- |
-| `at={story.moment.reveal} for="8f"` | Change the Moment; keep `for`. | No handle. | Change `for`; keep the Moment. |
-| `until={story.moment.reveal} for="8f"` | Change the Moment; keep `for`. | Change `for`; keep the Moment. | No handle. |
-| `at="2s" for="8f"` | Change `at`; keep `for`. | No handle. | Change `for`; keep `at`. |
-| `until="2s" for="8f"` | Change `until`; keep `for`. | Change `for`; keep `until`. | No handle. |
-
-Moving an event-and-duration window preserves duration. Moving a direct Selection window preserves
-semantic step displacement instead. These are different author decisions, so they have different
-behavior even when their current rectangles look identical.
-
-The unavailable edge does not secretly edit both the event and the duration. Duration editing is
-frame-based; semantic event editing selects an anchor. There is no `at` plus `until` Window form:
-current forms are `during`, `at/for`, `until/for`, and `start/end`.
-
-## Clock positions and explicit offsets
-
-A literal Instant such as `at="2s"` exposes one numeric time and can move by rewriting that value.
-A reference expression exposes a local offset while retaining its referenced event:
-
-```svml
-moment={story.moment.reveal}
-instant="moment.cue + 2f"
-```
-
-Moving this Instant changes the signed offset only. It does not relocate the Moment in Script.
-The same rule applies to an explicit offset from a selected boundary or a Program boundary.
-The expression's reference remains unchanged through the write.
-
-A bare reference expression such as `instant="moment.cue"` has an implicit zero offset. Moving it
-writes an offset such as `moment.cue+3f`; it leaves the Moment in Script unchanged. The direct
-binding `at={...}` is the form that edits the Moment itself.
-
-Bare references and explicit `+0f` have the same editing behavior. Writeback uses an explicit frame
-offset, including at zero. Positive, zero, and negative offsets belong to the same editing operation,
-subject to the resulting projection being usable.
-
-The existing syntax uses `instant` for expressions and a separate typed `moment`, `selection`, or
-`segment` attribute to bind their source. This design does not add an implicit name resolver or
-put arithmetic inside `{...}`. Unifying surface attribute spellings is a separate usability choice,
-not a prerequisite for establishing these edit semantics.
-
-## Independently authored endpoints
-
-`start="..." end="..."` expresses a deliberately assembled Window. Its expressions may use different
-sources, boundaries, absolute times, and offsets. This form remains available for production,
-including pure motion graphics and windows extending around a spoken passage.
-
-Each endpoint is edited exactly like an Instant expression: a literal changes its absolute time;
-a reference changes its local offset. A leading trim changes `start`, a trailing trim changes `end`,
-and a whole-window move shifts both endpoints by the same frame delta. Each expression retains its
-own reference, even when the endpoints depend on different sources. The referenced Script markers
-remain unchanged. Companion bindings identify the two writable source parameters.
-
-## Seconds and frames
-
-Seconds and milliseconds describe clock duration; frames describe steps at the ProgramSpace's
-frame rate. `2s` remains two seconds when the rate changes, whereas `60f` spans two seconds at 30fps
-and one second at 60fps. Parsing retains that authored unit. Projection uses exact rational arithmetic
-and rounds the resulting position to the nearest frame boundary, with half-frame ties rounding later.
-
-Timeline gestures operate on whole frames in the current ProgramSpace. A changed absolute value is
-written in frames, and a changed reference expression receives a frame offset. Unedited expressions
-retain their spelling and units. This makes a drag's result exact at the current frame rate without
-silently converting all authored clock durations into frame counts.
-
-## Semantic stops and coincident anchors
-
-Script order, anchor identity, and projected frame position are separate data:
-
-- Script order determines which inline Selection an author surface can express.
-- Projected frame position determines where an event appears in the current performance.
-- Anchor identity determines which relationship survives later changes to that performance.
-
-Build the gesture's semantic stops from distinct projected frame positions in chronological order.
-Several anchors at one frame occupy one stop but retain their individual identities. A direct
-Selection move advances both endpoints by the same signed number of stops. It does not shift a raw
-anchor-array index, assume one stop is one word, or preserve a duration measured in frames.
-
-Ties first retain the current anchor where it is still a candidate, then prefer its kind, then use
-a stable declared order. This is a default choice among coincident candidates, not a hierarchy of
-valid anchors. Selecting a semantic marker shows its exact anchors in the Inspector. Where declared
-handles allow it, a choice lists the other anchors at the same frame; horizontal mouse position alone
-cannot distinguish them. That explicit choice uses the same Script adjustment operation as dragging.
-
-Segment overlap or gaps can change temporal order without changing Script order. Stop construction
-must not assume contiguous Segments. Timeline places each prepared Take independently; semantic
-stops use those placed anchor frames, including coincident anchors from overlapping Takes.
-
-## Selection, projection, and consumption
+| `from="2s" for="8f"` | Rewrite `from`; retain `for`. | Rewrite `from`. | Rewrite `for`. |
+| `until="3s" for="8f"` | Rewrite `until`; retain `for`. | Rewrite `for`. | Rewrite `until`. |
+| `from="1s" until="3s"` | Shift both values. | Rewrite `from`. | Rewrite `until`. |
+| `during="timeline"` | No local write. | No local write. | No local write. |
+| `during={named-window}` | Follow the referenced value. | Edit its producer. | Edit its producer. |
-A Selection that is forward in Script may locate to equal or reversed frame endpoints. This does
-not alone establish whether every use of that Selection is invalid. A consumer may use only its
-start, or an expression may add offsets before composing a Window.
+`from` and `until` may also reference completed Instants. Those references remain fixed at the
+consumer; editing follows the Instant's producer. A resolved value does not grant the consumer an
+inverse operation over its source domain.
-Script validates the relationship it can express. Temporal projection validates the resulting
-Instant or Window in its ProgramSpace. Components validate their own use of those results.
-Studio offers only gestures with a declared inverse and candidate targets that preserve the
-edited object's usable projection. It does not add a global positive-duration rule to Selection.
+Frames and milliseconds are integral. Seconds may be rational decimals. Timeline conversion uses
+exact arithmetic and whole frame boundaries. Unedited values retain their authored unit.
-Both endpoints of a range adjustment are written in one operation. Recompilation remains the check
-for effects on other consumers of the shared relationship. An unsuccessful publication leaves the
-previous source and displayed state in place through the existing source transaction; this does not
-introduce a Build recovery workflow or a second mutable source of truth.
+## Domain-produced values
-A hidden or invalid initial object does not need an automatic repair interface. Conversely, a valid
-editable object must not disappear because the editor committed a target its own projection cannot
-represent. The relevant closure is over meaningful relationships and supported operations, not every
-possible raw spelling of the document.
+A domain package owns its own declared inverse. `@hypit/narrative-temporal`, for example, knows that
+one Instant came from a Moment or a particular Selection boundary. Music analysis could instead
+trace an Instant to a beat. Both publish the same `TemporalInstant`, but their editing rules remain
+with their projection declarations.
-## Implementation ownership
+Studio can recover this relationship from the producer graph and the projection package's metadata;
+the general visual/audio/text consumer needs no `semantic`, `beat`, or projector input. If several
+components consume the same named value, editing its declaration updates all of them after ordinary
+recompilation.
-The existing protocol already distinguishes `TemporalSource` from `TemporalInstantAuthority`.
-Preserve this separation. A source says what time depends on; authority identifies an intentional
-write target. The `fixed` case means no temporal gesture writes that endpoint, not that all author
-parameter editing is forbidden.
+This division is intentional:
-- `@hypit/script` owns tokenization, anchor identities, legal marker sites, and structural writeback.
- It relocates markers without rewriting unrelated prose whitespace, retains punctuation and attributes, writes coincident
- markers together, and preserves all unrelated relationships and caption information.
-- `@hypit/temporal-markup` owns the interpretation of each time form and declares its write targets.
- Direct semantic references expose semantic targets; quoted time expressions expose parameter
- targets, including implicit zero offsets and independent endpoints. Structural bindings retain
- their structural boundaries without a timeline write target.
-- `@hypit/temporal` resolves time and validates its results. It does not infer a user editing choice
- from invertibility or know Studio's UI.
-- Companion/Studio translates those declared relationships into the finite operations above.
- Existing `after-start` and `before-end` duration relationships already distinguish event-and-duration
- windows. Explicit source bindings remain the write allowlist. Component names and media types
- do not decide which operation is available.
+- `@hypit/temporal-markup` owns absolute literal/reference construction;
+- a domain package owns projection and domain-specific writeback;
+- `@hypit/temporal` validates resolved absolute values;
+- the component owns only what the value means for its behavior.
-Script tests exercise repeated marker moves and return trips across English, Chinese, Dual Text,
-punctuation, token attributes, and empty Segments. Temporal Markup tests check author authority;
-Studio tests check handles, semantic-stop movement, projected validity, and offset writes through zero.
-The same semantic gesture projection is used for the timeline preview and server-side validation.
+There is no automatic inverse, hidden compatibility fallback, or central registry of temporal
+lineage. Unsupported edits remain unavailable instead of mutating a guessed source.
diff --git a/packages/temporal-markup/README.md b/packages/temporal-markup/README.md
index 3dd8d171..726a7319 100644
--- a/packages/temporal-markup/README.md
+++ b/packages/temporal-markup/README.md
@@ -1,95 +1,98 @@
# `@hypit/temporal-markup`
-Shared SVML author-time projection helpers for `@hypit/temporal`. The Surface lowers authored
-Selection, Segment, Moment or explicit clock expressions to ordinary Instant projections and Window
-composition. A domain consumer receives the projected values and the shared Timeline; it does not
-locate Script words or infer a semantic source inside its renderer.
+Shared SVML author helpers for constructing ordinary absolute `TemporalInstant` and
+`TemporalWindow` values. This package knows the Timeline clock. It does not know Narrative,
+speech, media, captions, beats, or any other source domain.
-The package exports `createTemporalWindowProjection`, `createTemporalInstantProjection`,
-`resolveTemporalContext`, attribute vocabulary, and the exact duration/instant parsers. These are helpers for component
-Surfaces, not standalone author tags or a new Track.
+The package exports `resolveTemporalContext`, `createTemporalWindowConstruction`,
+`createTemporalInstantConstruction`, their attribute vocabularies, and exact duration/instant
+parsers. They are helpers for component Surfaces, not a Track and not a second Timeline model.
-The editing behavior is specified in [Author-directed time editing](EDITING.md).
-It separates direct bindings, durations, and explicit offsets from derived results, with a precise
-write target for each supported gesture.
+## The boundary
-## Time context
+A general component accepts:
-A Track Surface accepts `timeline={program.timeline}`. Resolve it with
-`resolveTemporalContext({ element, resolveReference })` and pass that context to each temporal
-projection helper. Wire `context.timeline.ref` directly into the component Fragment's Timeline port.
-Preserve the projections' returned records, components and fragments.
+- `timeline={film.timeline}` for the absolute coordinate system;
+- a `TemporalWindow` when it occupies an interval; or
+- a `TemporalInstant` when it reacts to an event.
-The context contains one required `timeline` reference. Program time and Script references both
-project against it. Pure animation uses a zero-Take Timeline with an authored extent. Script events
-use the anchors provided by its placed Takes. Drawing Producers receive that same Timeline and the
-projected Instants/Windows; they need no Script parser or separate time-range input.
+It never receives a Narrative projector and never interprets Selection, Segment or Moment values.
+A source-domain package performs that projection once and publishes an ordinary absolute value.
+The same component can therefore consume time from Narrative, music analysis, imported edit data,
+or a literal clock position without knowing which source produced it.
## Window forms
-A Surface using the shared Window vocabulary accepts one complete form:
+The common Window vocabulary has four attributes and one rule:
-| Authored attributes | Meaning |
+| Form | Result |
| --- | --- |
-| `during="program"` | The complete program Window. |
-| `during={story.segment.opening}` | A Segment's Window. |
-| `during={story.selection.proof}` | A Selection's Window, including its authored endpoint affinity. |
-| `at="2s" for="8f"` | Start two seconds into the program and last eight frames. |
-| `at={story.moment.reveal} for="8f"` | Start at a Moment and last eight program frames. |
-| `until={story.moment.reveal} for="250ms"` | End at a Moment after a span of 250 milliseconds. |
-| `start="program.start" end="moment.cue" moment={story.moment.reveal}` | Compose independently authored endpoints. |
-
-Do not combine forms: `during="program" until={...}` is not shorthand for a shortened program.
-Use explicit `start` and `end` for that relationship. Expressions can reference `program.start`,
-`program.end`, `selection.start`, `selection.end`, `segment.start`, `segment.end` or `moment.cue`.
-Bind the corresponding `selection`, `segment` or `moment` reference attribute when an expression
-uses it. An endpoint may also be an absolute duration from program start, such as `1.5s`.
-
-Offsets use an explicit sign and duration, for example `selection.start - 2f`. Frames and milliseconds
-are integers (`8f`, `250ms`); seconds may be fractional (`1.5s`). Projection preserves the expression
-and its authority. Invalid or out-of-program results are errors rather than silently clipped time.
+| `during="timeline"` | The complete Timeline Window. |
+| `during={story-time.proof}` | Reuse an already resolved Window. |
+| `from="2s" for="12f"` | Start at two seconds and last twelve frames. |
+| `until="3s" for="250ms"` | End at three seconds and extend 250 ms backwards. |
+| `from={cue} until="timeline.end"` | Compose two resolved or authored endpoints. |
+
+Outside `during`, supply exactly two of `from`, `until`, and `for`. `from` and `until` accept an
+existing `TemporalInstant` or an absolute expression. `for` accepts an exact duration literal or a
+resolved `TemporalExtent`.
+
+Absolute expressions are deliberately small: `start`, `end`, `timeline.start`, `timeline.end`, an
+absolute `12f`/`250ms`/`1.5s`, or one of those Timeline boundaries with a signed offset. There is no
+implicit lookup of domain names such as `moment.cue`; project that domain value upstream first.
## Instant forms
-An Instant consumer has a different job: an event or activation with one temporal point.
+An event consumer uses `at`:
-| Authored attributes | Meaning |
+| Form | Result |
| --- | --- |
-| `at={story.moment.reveal}` | The authored Moment. |
-| `at={story.selection.proof} boundary="start"` | An explicitly chosen Selection boundary. |
-| `at={story.segment.opening} boundary="end"` | An explicitly chosen Segment boundary. |
-| `at="2.6s"` | An authored event 2.6 seconds from program start. |
-| `instant="program.start + 8f"` | A projected clock expression. |
+| `at={story-time.claim}` | Reuse an already resolved Instant. |
+| `at="2.6s"` | An absolute point 2.6 seconds from Timeline start. |
+| `at="timeline.end-12f"` | Twelve frames before the exclusive end. |
+
+An Instant does not imply a visible duration. The receiving component decides whether the event
+starts an animation, changes persistent state, or ends an outer lifetime.
-The domain component decides what happens after that point. An answer may remain visible, a Sequence
-may replace its member, or a motion may run according to its own authored schedule. Instant projection
-does not impose the event's visible duration. A component whose public role requires a Script Moment
-can deliberately admit only that form; consumers need not expose unrelated temporal options.
+## Surface implementation
-## Component boundary
+Resolve the required Timeline once:
+
+```ts
+const context = resolveTemporalContext({ element, resolveReference });
+const timing = createTemporalWindowConstruction({
+ id: itemId,
+ element: child,
+ ...context,
+ resolveReference,
+});
+```
-The Surface supplies an author-facing `subjectId` for the actual item whose time is being projected,
-separately from graph-qualified operation ids. The graph wires the resulting Instant or Window and
-Timeline into the consumer. Keep projection outside the domain Producer: it consumes resolved
-time and implements its own schedule or state, while the shared temporal protocol retains where that
-time came from. An outer lifetime and child activations are separate inputs when a component persists
-between events.
+Preserve the returned records, components and fragments, then wire `timing.ref` to a
+`TemporalWindow` port. For an event, use `createTemporalInstantConstruction` and an Instant port.
+The consumer Producer receives only the completed value.
-Script's delimited `@{...}` Selection and Moment syntax belong to `@hypit/script`; media playback belongs
-to `@hypit/media-track`; a graphic component's reveal or preset semantics belong to that component.
+`subjectId` identifies the authored occurrence for inspection; it is not a nominal ownership lock.
+A deliberately named Window can be reused by several components. Timeline identity and interval
+validity are still checked.
-## Independently bound endpoints
+## Domain projections
-For a Window whose endpoints refer to different semantic sources, use `start-source` and
-`end-source`. The expression still states the kind and boundary; each binding supplies that source:
+Domain projection belongs to the domain package. For example,
+`@hypit/narrative-temporal` may publish:
```svml
-<example:Item start-source={story.segment.next} start="segment.start"
- end-source={story.segment.previous} end="segment.end"/>
+<semantic:Projection id="story-time" narrative={story} timeline={film.timeline}>
+ <semantic:Map alignment={speech.alignment} domain={speech-media.domain} window={film.speech}/>
+ <semantic:Window id="proof" selection={story.selection.proof}/>
+ <semantic:Instant id="claim" moment={story.moment.claim}/>
+</semantic:Projection>
+
+<visual:Clip media={proof-media.media} during={story-time.proof}
+ frame={proof-frame} appearance={proof-appearance}/>
+<deck:Card at={story-time.claim} .../>
```
-This describes an overlapping physical interval without authoring a backwards Script Selection.
-The same endpoint bindings accept Selections or Moments with their corresponding expressions.
-`segment`, `selection` and `moment` remain convenient shared bindings when both expressions use the
-same source. Explicit expressions retain local parameter writeback; these bindings do not move the
-referenced Script anchors when the expression's offset is edited.
+Only explicitly requested values cross that boundary. The completed projection contains absolute
+boundaries, not a reusable local-domain mapping. A visual, audio, caption, or typography component
+does not carry the projector merely to consume the resulting time.
diff --git a/packages/temporal-markup/package.json b/packages/temporal-markup/package.json
index f06671c5..7dfde1c4 100644
--- a/packages/temporal-markup/package.json
+++ b/packages/temporal-markup/package.json
@@ -10,9 +10,7 @@
"dependencies": {
"@hypit/elaborator": "workspace:*",
"@hypit/markup": "workspace:*",
- "@hypit/narrative": "workspace:*",
"@hypit/timeline": "workspace:*",
- "@hypit/temporal": "workspace:*",
- "@hypit/program-space": "workspace:*"
+ "@hypit/temporal": "workspace:*"
}
}
diff --git a/packages/temporal-markup/src/context.ts b/packages/temporal-markup/src/context.ts
new file mode 100644
index 00000000..06d40029
--- /dev/null
+++ b/packages/temporal-markup/src/context.ts
@@ -0,0 +1,23 @@
+import type { StructuredElement, SurfaceAttributeVocabulary, SurfaceResolvedReference } from "@hypit/markup";
+import { sameType } from "@hypit/protocol";
+import { timelineTypes } from "@hypit/timeline";
+
+export type TemporalContext = { readonly timeline: SurfaceResolvedReference };
+
+export const temporalContextAttributeVocabulary = [
+ { name: "timeline", kind: "reference", required: true, accepts: [timelineTypes.track],
+ summary: "The complete absolute film Timeline." },
+] as const satisfies readonly SurfaceAttributeVocabulary[];
+
+export function resolveTemporalContext(input: {
+ readonly element: StructuredElement;
+ readonly resolveReference: (path: string) => SurfaceResolvedReference | undefined;
+}): TemporalContext {
+ const raw = input.element.attributes.timeline;
+ if (typeof raw !== "object" || raw.kind !== "reference") throw new Error(`${input.element.name}.timeline must be a reference.`);
+ const found = input.resolveReference(raw.path);
+ if (found === undefined || !sameType(found.type, timelineTypes.track)) {
+ throw new Error(`${input.element.name}.timeline must reference a Timeline.`);
+ }
+ return { timeline: found };
+}
diff --git a/packages/temporal-markup/src/index.ts b/packages/temporal-markup/src/index.ts
index 4a22f32b..9353668d 100644
--- a/packages/temporal-markup/src/index.ts
+++ b/packages/temporal-markup/src/index.ts
@@ -1,152 +1,55 @@
import { sealGraphFragment } from "@hypit/elaborator";
-import type { FragmentOperation, GraphFragment } from "@hypit/elaborator";
+import type { FragmentOperation, FragmentOperationRef, GraphFragment } from "@hypit/elaborator";
import type {
- MarkupAttributeValue,
- StructuredElement,
- SurfaceComponentDraft,
- SurfaceAttributeVocabulary,
- SurfaceRecordDraft,
- SurfaceResolvedReference,
+ MarkupAttributeValue, StructuredElement, SurfaceAttributeVocabulary, SurfaceComponentDraft,
+ SurfaceRecordDraft, SurfaceResolvedReference,
} from "@hypit/markup";
-import { narrativeTypes } from "@hypit/narrative";
-export * from "./space.js";
+import { sameType, type TypeRef } from "@hypit/protocol";
+import { temporalProducers, temporalTypes } from "@hypit/temporal";
+import type { TemporalDuration, TemporalInstantExpression } from "@hypit/temporal";
import { timelineTypes } from "@hypit/timeline";
-import {
- temporalProducers,
- temporalTypes,
-} from "@hypit/temporal";
-import type {
- TemporalDuration,
- TemporalInstantAuthority,
- TemporalInstantExpression,
-} from "@hypit/temporal";
+
+export * from "./context.js";
type ResolveReference = (path: string) => SurfaceResolvedReference | undefined;
-type SourceKind = "program" | "selection" | "segment" | "moment";
+type InstantDraft =
+ | { readonly kind: "expression"; readonly expression: TemporalInstantExpression }
+ | { readonly kind: "reference"; readonly reference: SurfaceResolvedReference };
+type ExtentDraft =
+ | { readonly kind: "duration"; readonly duration: TemporalDuration }
+ | { readonly kind: "reference"; readonly reference: SurfaceResolvedReference };
-/** Complete author vocabulary for one Window consumer. Domain packages may only add non-time fields. */
+/** Absolute-only author vocabulary for a Window consumer. */
export const temporalWindowAttributeVocabulary: readonly SurfaceAttributeVocabulary[] = [
- { name: "during", kind: "expression", required: false, values: ["program"],
- accepts: [narrativeTypes.selection, narrativeTypes.excerpt],
- summary: "Uses the whole Program, or the exact window of a referenced Selection or Segment." },
- { name: "at", kind: "expression", required: false, accepts: [narrativeTypes.moment],
- summary: "Starts at a semantic Moment or authored time (2s, 60f); write it together with for." },
- { name: "until", kind: "expression", required: false, accepts: [narrativeTypes.moment],
- summary: "Ends at a semantic Moment or authored time; write it together with for." },
- { name: "for", kind: "literal", required: false,
- summary: "Sets the projected duration paired with at or until, such as 12f, 250ms or 1.5s." },
- { name: "start", kind: "literal", required: false,
- summary: "Sets a projected start expression; write it together with end." },
- { name: "end", kind: "literal", required: false,
- summary: "Sets a projected end expression; write it together with start." },
- ...["start-source", "end-source"].map(name => ({ name, kind: "reference" as const, required: false,
- accepts: [narrativeTypes.selection, narrativeTypes.excerpt, narrativeTypes.moment],
- summary: "Binds this endpoint's semantic source independently; its expression determines the boundary." })),
- { name: "selection", kind: "reference", required: false, accepts: [narrativeTypes.selection],
- summary: "Resolves selection.start or selection.end used by a projected start/end expression." },
- { name: "segment", kind: "reference", required: false, accepts: [narrativeTypes.excerpt],
- summary: "Resolves segment.start or segment.end used by a projected start/end expression." },
- { name: "moment", kind: "reference", required: false, accepts: [narrativeTypes.moment],
- summary: "Resolves moment.cue used by a projected start/end expression." },
+ { name: "during", kind: "expression", required: false, values: ["timeline"], accepts: [temporalTypes.window],
+ summary: "Uses the whole Timeline or an already resolved Window." },
+ { name: "from", kind: "expression", required: false, accepts: [temporalTypes.instant],
+ summary: "Sets the inclusive absolute start boundary." },
+ { name: "until", kind: "expression", required: false, accepts: [temporalTypes.instant],
+ summary: "Sets the exclusive absolute end boundary." },
+ { name: "for", kind: "expression", required: false, accepts: [temporalTypes.extent],
+ summary: "Sets an exact duration or resolved Extent." },
];
export const temporalWindowAttributeNames = temporalWindowAttributeVocabulary.map(({ name }) => name);
-/** Complete author vocabulary for a semantic or explicitly projected Instant. */
+/** Absolute-only author vocabulary for an Instant consumer. */
export const temporalInstantAttributeVocabulary: readonly SurfaceAttributeVocabulary[] = [
- { name: "at", kind: "expression", required: false,
- accepts: [narrativeTypes.moment, narrativeTypes.selection, narrativeTypes.excerpt],
- summary: "Uses a semantic Moment, a chosen Selection or Segment boundary, or an authored time such as 2s." },
- { name: "instant", kind: "literal", required: false,
- summary: "Uses a projected point expression, such as moment.cue + 12f or program.start + 2s." },
- { name: "boundary", kind: "literal", required: false, values: ["start", "end"],
- summary: "Chooses the start or end boundary when at references a Selection or Segment." },
- { name: "selection", kind: "reference", required: false, accepts: [narrativeTypes.selection],
- summary: "Resolves selection.start or selection.end used by an instant expression." },
- { name: "segment", kind: "reference", required: false, accepts: [narrativeTypes.excerpt],
- summary: "Resolves segment.start or segment.end used by an instant expression." },
- { name: "moment", kind: "reference", required: false, accepts: [narrativeTypes.moment],
- summary: "Resolves moment.cue used by an instant expression." },
+ { name: "at", kind: "expression", required: false, accepts: [temporalTypes.instant],
+ summary: "Uses an already resolved Instant or an absolute authored position." },
];
export const temporalInstantAttributeNames = temporalInstantAttributeVocabulary.map(({ name }) => name);
-function rejectUnusedTemporalAttributes(
- element: StructuredElement,
- universe: readonly string[],
- allowed: readonly string[],
-): void {
- const accepted = new Set(allowed);
- const unused = universe.filter((name) => element.attributes[name] !== undefined && !accepted.has(name));
- if (unused.length > 0) {
- throw new Error(`${element.name} timing form does not accept ${unused.join(", ")}.`);
- }
-}
-
-type InstantDraft = {
- readonly expression: TemporalInstantExpression;
- readonly authority: TemporalInstantAuthority;
- readonly source: SourceKind;
- readonly reference?: SurfaceResolvedReference;
-};
-
-export type TemporalMarkupProjection = {
+export type TemporalMarkupConstruction = {
readonly records: readonly SurfaceRecordDraft[];
readonly components: readonly SurfaceComponentDraft[];
readonly fragments: readonly GraphFragment[];
- readonly ref: { readonly kind: "component-output"; readonly component: string; readonly output: string };
+ readonly ref: SurfaceResolvedReference["ref"];
+ readonly startRef?: SurfaceResolvedReference["ref"];
+ readonly endRef?: SurfaceResolvedReference["ref"];
};
-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 resolve(
- raw: MarkupAttributeValue | undefined,
- label: string,
- expected: SurfaceResolvedReference["type"],
- resolveReference: ResolveReference,
-): SurfaceResolvedReference {
- if (typeof raw !== "object" || raw.kind !== "reference") throw new Error(`${label} must be a reference.`);
- const found = resolveReference(raw.path);
- if (found === undefined || !sameType(found.type, expected)) throw new Error(`${label} has the wrong Type.`);
- return found;
-}
-
-function resolveDuring(
- raw: MarkupAttributeValue,
- label: string,
- resolveReference: ResolveReference,
-): { readonly kind: "selection" | "segment"; readonly reference: SurfaceResolvedReference } {
- if (typeof raw !== "object" || raw.kind !== "reference") throw new Error(`${label} must be program or a reference.`);
- const found = resolveReference(raw.path);
- if (found !== undefined && sameType(found.type, narrativeTypes.selection)) {
- return { kind: "selection", reference: found };
- }
- if (found !== undefined && sameType(found.type, narrativeTypes.excerpt)) {
- return { kind: "segment", reference: found };
- }
- throw new Error(`${label} must reference a Selection or Segment.`);
-}
-
-function optionalText(element: StructuredElement, name: string): string | undefined {
- const value = element.attributes[name];
- if (value === undefined) return undefined;
- if (typeof value !== "string" || value.trim().length === 0) {
- throw new Error(`${element.name}.${name} must be text.`);
- }
- return value.trim();
-}
-
-function text(element: StructuredElement, name: string): string {
- const found = optionalText(element, name);
- if (found === undefined) throw new Error(`${element.name}.${name} is required.`);
- return found;
-}
-
function divisor(left: number, right: number): number {
- let a = Math.abs(left);
- let b = Math.abs(right);
+ let a = Math.abs(left), b = Math.abs(right);
while (b !== 0) [a, b] = [b, a % b];
return a;
}
@@ -154,9 +57,7 @@ function divisor(left: number, right: number): number {
export function parseTemporalDuration(value: string, label: string): TemporalDuration {
const match = /^(\d+)(?:\.(\d+))?(f|ms|s)$/u.exec(value.trim());
if (match === null) 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];
+ const whole = Number(match[1]), fraction = match[2] ?? "", 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.`);
@@ -164,28 +65,22 @@ export function parseTemporalDuration(value: string, label: string): TemporalDur
}
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.`);
- }
+ 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 negate(value: TemporalDuration): TemporalDuration {
- return value.unit === "seconds"
- ? { ...value, numerator: -value.numerator }
- : { ...value, value: -value.value };
+ return value.unit === "seconds" ? { ...value, numerator: -value.numerator } : { ...value, value: -value.value };
}
export function parseTemporalInstant(value: string, label: string): TemporalInstantExpression {
const trimmed = value.trim();
- const refs = [
- "program.start", "program.end", "selection.start", "selection.end",
- "segment.start", "segment.end", "moment.cue",
- ] as const;
- for (const ref of refs) {
- if (trimmed === ref) return { ref };
- const escaped = ref.replace(".", "\\.");
+ const aliases = [["start", "timeline.start"], ["end", "timeline.end"],
+ ["timeline.start", "timeline.start"], ["timeline.end", "timeline.end"]] as const;
+ for (const [spelling, ref] of aliases) {
+ if (trimmed === spelling) return { ref };
+ const escaped = spelling.replace(".", "\\.");
const match = new RegExp(`^${escaped}\\s*([+-])\\s*(.+)$`, "u").exec(trimmed);
if (match !== null) {
const offset = parseTemporalDuration(match[2]!, `${label} offset`);
@@ -195,338 +90,180 @@ export function parseTemporalInstant(value: string, label: string): TemporalInst
return { ref: "absolute", at: parseTemporalDuration(trimmed, label) };
}
-function expressionSource(expression: TemporalInstantExpression): SourceKind {
- if (expression.ref.startsWith("selection.")) return "selection";
- if (expression.ref.startsWith("segment.")) return "segment";
- if (expression.ref === "moment.cue") return "moment";
- return "program";
+function resolvedReference(raw: MarkupAttributeValue, label: string, type: SurfaceResolvedReference["type"],
+ resolveReference: ResolveReference): SurfaceResolvedReference {
+ if (typeof raw !== "object" || raw.kind !== "reference") throw new Error(`${label} must be a reference.`);
+ const found = resolveReference(raw.path);
+ if (found === undefined || !sameType(found.type, type)) throw new Error(`${label} has the wrong Type.`);
+ return found;
+}
+
+function instantDraft(raw: MarkupAttributeValue, label: string, resolveReference: ResolveReference): InstantDraft {
+ return typeof raw === "string"
+ ? { kind: "expression", expression: parseTemporalInstant(raw, label) }
+ : { kind: "reference", reference: resolvedReference(raw, label, temporalTypes.instant, resolveReference) };
}
-function sourceReference(
- element: StructuredElement,
- kind: SourceKind,
- resolveReference: ResolveReference,
- attribute = kind as string,
-): SurfaceResolvedReference | undefined {
- if (kind === "program") return undefined;
- const expected = kind === "selection"
- ? narrativeTypes.selection
- : kind === "segment" ? narrativeTypes.excerpt : narrativeTypes.moment;
- return resolve(element.attributes[attribute], `${element.name}.${attribute}`, expected, resolveReference);
+function extentDraft(raw: MarkupAttributeValue, label: string, resolveReference: ResolveReference): ExtentDraft {
+ return typeof raw === "string"
+ ? { kind: "duration", duration: parseTemporalDuration(raw, label) }
+ : { kind: "reference", reference: resolvedReference(raw, label, temporalTypes.extent, resolveReference) };
}
-function projectionFragment(input: {
- readonly output: "instant" | "window";
- readonly start: InstantDraft;
- readonly end?: InstantDraft;
-}): GraphFragment {
- const fragmentInput = (name: string) => ({ kind: "fragment-input" as const, name });
- const operation = (id: string) => ({ kind: "fragment-operation" as const, operation: id });
- const endpoints = input.end === undefined
- ? [["instant", input.start] as const]
- : [["start", input.start] as const, ["end", input.end] as const];
- const inputs = [
- { name: "timeline", type: timelineTypes.track },
- ...endpoints.map(([name]) => ({ name: `${name}-spec`, type: temporalTypes.instantSpec })),
- ...endpoints.flatMap(([name, endpoint]) => endpoint.source === "program" ? [] : [{
- name: `${name}-${endpoint.source}`,
- type: endpoint.source === "selection" ? narrativeTypes.selection
- : endpoint.source === "segment" ? narrativeTypes.excerpt : narrativeTypes.moment,
- }]),
- ...(input.end === undefined ? [] : [{ name: "window-spec", type: temporalTypes.windowSpec }]),
- ];
- const operations: FragmentOperation[] = endpoints.map(([name, endpoint]) => ({
- id: `temporal:${name}`,
- producer: endpoint.source === "program" ? temporalProducers.projectProgramInstant
- : endpoint.source === "selection" ? temporalProducers.projectSelectionInstant
- : endpoint.source === "segment" ? temporalProducers.projectSegmentInstant
- : temporalProducers.projectMomentInstant,
- inputs: {
- timeline: fragmentInput("timeline"),
- spec: fragmentInput(`${name}-spec`),
- ...(endpoint.source === "program" ? {} : {
- [endpoint.source]: fragmentInput(`${name}-${endpoint.source}`),
- }),
- },
- result: { kind: "output" as const, name: "instant" },
- }));
- if (input.end !== undefined) operations.push({
- id: "temporal:window",
- producer: temporalProducers.composeWindow,
- inputs: {
- spec: fragmentInput("window-spec"),
- start: operation("temporal:start"),
- end: operation("temporal:end"),
- },
- result: { kind: "output" as const, name: "window" },
- });
- return sealGraphFragment({
- inputs,
- operations,
- exports: [{
- name: input.output,
- type: input.output === "window" ? temporalTypes.window : temporalTypes.instant,
- root: operation(input.output === "window" ? "temporal:window" : "temporal:instant"),
- }],
- });
+function rejectUnused(element: StructuredElement, allowed: readonly string[]): void {
+ const accepted = new Set(allowed);
+ const unused = temporalWindowAttributeNames.filter((name) => element.attributes[name] !== undefined && !accepted.has(name));
+ if (unused.length > 0) throw new Error(`${element.name} timing form does not accept ${unused.join(", ")}.`);
}
-function projectionDraft(input: {
- readonly id: string;
- readonly subjectId?: string;
- readonly element: StructuredElement;
- readonly timeline: SurfaceResolvedReference;
- readonly start: InstantDraft;
- readonly end?: InstantDraft;
-}): TemporalMarkupProjection {
- const output = input.end === undefined ? "instant" : "window";
- const subjectId = input.subjectId ?? input.id;
- if (subjectId.length === 0) throw new Error("Temporal projection subjectId must not be empty.");
- const fragment = projectionFragment({ output, start: input.start, ...(input.end === undefined ? {} : { end: input.end }) });
- const componentId = `${input.id}.__temporal`;
- const records: SurfaceRecordDraft[] = [];
- const componentInputs: SurfaceComponentDraft["inputs"] extends infer _T
- ? Record<string, SurfaceResolvedReference["ref"] | { readonly kind: "record"; readonly id: string }>
- : never = { timeline: input.timeline.ref };
- const endpoints = input.end === undefined
- ? [["instant", input.start] as const]
- : [["start", input.start] as const, ["end", input.end] as const];
- for (const [name, endpoint] of endpoints) {
- const recordId = `${input.id}.__temporal.${name}`;
- records.push({
- id: recordId,
- type: temporalTypes.instantSpec,
- value: { kind: "inline", value: {
- id: `${input.id}.${name}`,
- subjectId,
- projection: endpoint.expression,
- authority: endpoint.authority,
- } },
- range: input.element.range,
- });
- componentInputs[`${name}-spec`] = { kind: "record", id: recordId };
- if (endpoint.source !== "program") {
- if (endpoint.reference === undefined) throw new Error(`${input.id}.${name} has no ${endpoint.source} source.`);
- componentInputs[`${name}-${endpoint.source}`] = endpoint.reference.ref;
+const fragmentInput = (name: string) => ({ kind: "fragment-input" as const, name });
+const operation = (id: string): FragmentOperationRef => ({ kind: "fragment-operation", operation: id });
+
+function constructWindow(value: {
+ readonly id: string; readonly subjectId: string; readonly element: StructuredElement;
+ readonly timeline: SurfaceResolvedReference; readonly start: InstantDraft; readonly end?: InstantDraft;
+ readonly extent?: ExtentDraft; readonly direction?: 1 | -1;
+}): TemporalMarkupConstruction {
+ const ports: Array<{ readonly name: string; readonly type: TypeRef }> = [
+ { name: "timeline", type: timelineTypes.track }, { name: "window-spec", type: temporalTypes.windowSpec },
+ ];
+ const bindings: Record<string, SurfaceResolvedReference["ref"] | { kind: "record"; id: string }> = {
+ timeline: value.timeline.ref, "window-spec": { kind: "record", id: `${value.id}.__temporal.window` },
+ };
+ const records: SurfaceRecordDraft[] = [{ id: `${value.id}.__temporal.window`, type: temporalTypes.windowSpec,
+ value: { kind: "inline", value: { id: value.id, subjectId: value.subjectId } }, range: value.element.range }];
+ const operations: FragmentOperation[] = [];
+ const materialize = (name: "start" | "end", draft: InstantDraft): FragmentOperationRef => {
+ if (draft.kind === "reference") {
+ const port = `${name}-instant`;
+ ports.push({ name: port, type: temporalTypes.instant });
+ bindings[port] = draft.reference.ref;
+ const operationId = `reuse-${name}`;
+ operations.push({ id: operationId, producer: temporalProducers.reuseInstant,
+ inputs: { instant: fragmentInput(port) }, result: { kind: "output", name: "instant" } });
+ return operation(operationId);
}
- }
- if (input.end !== undefined) {
- const windowSpecId = `${input.id}.__temporal.window`;
- records.push({
- id: windowSpecId,
- type: temporalTypes.windowSpec,
- value: { kind: "inline", value: { id: input.id, subjectId } },
- range: input.element.range,
- });
- componentInputs["window-spec"] = { kind: "record", id: windowSpecId };
- }
- return {
- records,
- components: [{
- id: componentId,
- fragment: fragment.id,
- inputs: componentInputs,
- outputs: { [output]: `${input.id}.__temporal.${output}` },
- range: input.element.range,
- }],
- fragments: [fragment],
- ref: { kind: "component-output", component: componentId, output },
+ const port = `${name}-spec`, recordId = `${value.id}.__temporal.${name}`;
+ ports.push({ name: port, type: temporalTypes.instantSpec });
+ bindings[port] = { kind: "record", id: recordId };
+ records.push({ id: recordId, type: temporalTypes.instantSpec, value: { kind: "inline", value: {
+ id: `${value.id}.${name}`, subjectId: value.subjectId, projection: draft.expression,
+ } }, range: value.element.range });
+ const operationId = `materialize-${name}`;
+ operations.push({ id: operationId, producer: temporalProducers.projectProgramInstant,
+ inputs: { timeline: fragmentInput("timeline"), spec: fragmentInput(port) }, result: { kind: "output", name: "instant" } });
+ return operation(operationId);
};
+ let start = materialize("start", value.start);
+ let end = value.end === undefined ? undefined : materialize("end", value.end);
+ if (value.extent !== undefined) {
+ let extentRef: FragmentOperationRef | ReturnType<typeof fragmentInput>;
+ if (value.extent.kind === "reference") {
+ ports.push({ name: "extent", type: temporalTypes.extent });
+ bindings.extent = value.extent.reference.ref;
+ extentRef = fragmentInput("extent");
+ } else {
+ ports.push({ name: "duration", type: temporalTypes.duration });
+ const durationId = `${value.id}.__temporal.duration`;
+ bindings.duration = { kind: "record", id: durationId };
+ records.push({ id: durationId, type: temporalTypes.duration,
+ value: { kind: "inline", value: value.extent.duration }, range: value.element.range });
+ operations.push({ id: "resolve-extent", producer: temporalProducers.extentFromDuration,
+ inputs: { timeline: fragmentInput("timeline"), duration: fragmentInput("duration") }, result: { kind: "output", name: "extent" } });
+ extentRef = operation("resolve-extent");
+ }
+ const direction = value.direction;
+ if (direction === undefined) throw new Error("Temporal Window shift has no direction.");
+ const base = direction === 1 ? start : end;
+ if (base === undefined) throw new Error("Temporal Window shift has no base Instant.");
+ ports.push({ name: "shift-spec", type: temporalTypes.shiftSpec });
+ const shiftId = `${value.id}.__temporal.shift`;
+ bindings["shift-spec"] = { kind: "record", id: shiftId };
+ records.push({ id: shiftId, type: temporalTypes.shiftSpec, value: { kind: "inline", value: {
+ id: `${value.id}.${direction === 1 ? "end" : "start"}`, subjectId: value.subjectId, direction,
+ } }, range: value.element.range });
+ operations.push({ id: "shift", producer: temporalProducers.shiftInstant,
+ inputs: { timeline: fragmentInput("timeline"), instant: base, extent: extentRef, spec: fragmentInput("shift-spec") },
+ result: { kind: "output", name: "instant" } });
+ if (direction === 1) end = operation("shift"); else start = operation("shift");
+ }
+ if (end === undefined) throw new Error("Temporal Window has no end Instant.");
+ operations.push({ id: "compose", producer: temporalProducers.composeWindow,
+ inputs: { spec: fragmentInput("window-spec"), start, end }, result: { kind: "output", name: "window" } });
+ const fragment = sealGraphFragment({ inputs: ports, operations, exports: [
+ { name: "window", type: temporalTypes.window, root: operation("compose") },
+ { name: "start", type: temporalTypes.instant, root: start },
+ { name: "end", type: temporalTypes.instant, root: end },
+ ] });
+ const componentId = `${value.id}.__temporal`;
+ return { records, components: [{ id: componentId, fragment: fragment.id, inputs: bindings,
+ outputs: { window: `${value.id}.__temporal.window.value`, start: `${value.id}.__temporal.start.value`,
+ end: `${value.id}.__temporal.end.value` }, range: value.element.range }], fragments: [fragment],
+ ref: { kind: "component-output", component: componentId, output: "window" },
+ startRef: { kind: "component-output", component: componentId, output: "start" },
+ endRef: { kind: "component-output", component: componentId, output: "end" } };
}
-/** Decode exactly one of during, at/for, until/for, or start/end. */
-export function createTemporalWindowProjection(input: {
- readonly id: string;
- readonly subjectId?: string;
- readonly element: StructuredElement;
- readonly timeline: SurfaceResolvedReference;
- readonly resolveReference: ResolveReference;
-}): TemporalMarkupProjection {
- const { element, resolveReference } = input;
- const during = element.attributes.during;
- const at = element.attributes.at;
- const until = element.attributes.until;
- const start = optionalText(element, "start");
- const end = optionalText(element, "end");
- const forms = Number(during !== undefined) + Number(at !== undefined)
- + Number(until !== undefined) + Number(start !== undefined || end !== undefined);
- if (forms !== 1) {
- throw new Error(`${element.name} requires exactly one of during, at/for, until/for, or start/end.`);
- }
+/** Construct or pass through one absolute Window. */
+export function createTemporalWindowConstruction(value: {
+ readonly id: string; readonly subjectId?: string; readonly element: StructuredElement;
+ readonly timeline: SurfaceResolvedReference; readonly resolveReference: ResolveReference;
+}): TemporalMarkupConstruction {
+ const { element, resolveReference } = value;
+ const during = element.attributes.during, from = element.attributes.from;
+ const until = element.attributes.until, length = element.attributes.for;
if (during !== undefined) {
- rejectUnusedTemporalAttributes(element, temporalWindowAttributeNames, ["during"]);
- if (typeof during === "string") {
- if (during.trim() !== "program") throw new Error(`${element.name}.during text must be program.`);
- return projectionDraft({
- ...input,
- start: { expression: { ref: "program.start" }, authority: { kind: "fixed" }, source: "program" },
- end: { expression: { ref: "program.end" }, authority: { kind: "fixed" }, source: "program" },
- });
+ rejectUnused(element, ["during"]);
+ if (typeof during !== "string") {
+ const found = resolvedReference(during, `${element.name}.during`, temporalTypes.window, resolveReference);
+ return { records: [], components: [], fragments: [], ref: found.ref };
}
- const bound = resolveDuring(during, `${element.name}.during`, resolveReference);
- const semantic = bound.kind === "selection";
- return projectionDraft({
- ...input,
- start: {
- expression: { ref: `${bound.kind}.start` },
- authority: semantic ? { kind: "semantic", boundary: "start" } : { kind: "fixed" },
- source: bound.kind,
- reference: bound.reference,
- },
- end: {
- expression: { ref: `${bound.kind}.end` },
- authority: semantic ? { kind: "semantic", boundary: "end" } : { kind: "fixed" },
- source: bound.kind,
- reference: bound.reference,
- },
- });
+ if (during.trim() !== "timeline") throw new Error(`${element.name}.during text must be timeline.`);
+ return constructWindow({ ...value, subjectId: value.subjectId ?? value.id,
+ start: { kind: "expression", expression: { ref: "timeline.start" } },
+ end: { kind: "expression", expression: { ref: "timeline.end" } } });
}
- if (at !== undefined || until !== undefined) {
- const name = at !== undefined ? "at" : "until";
- rejectUnusedTemporalAttributes(element, temporalWindowAttributeNames, [name, "for"]);
- const raw = at ?? until;
- const moment = typeof raw === "string" ? undefined : resolve(raw, `${element.name}.${name}`, narrativeTypes.moment, resolveReference);
- const length = parseTemporalDuration(text(element, "for"), `${element.name}.for`);
- const cue: InstantDraft = {
- expression: typeof raw === "string" ? { ref: "absolute", at: parseTemporalDuration(raw, `${element.name}.${name}`) } : { ref: "moment.cue" },
- authority: moment === undefined ? { kind: "parameter", binding: name, relation: "direct" } : { kind: "semantic", boundary: "cue" },
- source: moment === undefined ? "program" : "moment",
- ...(moment === undefined ? {} : { reference: moment }),
- };
- const derived: InstantDraft = {
- expression: { ...cue.expression, offset: at !== undefined ? length : negate(length) },
- authority: {
- kind: "parameter",
- binding: "for",
- relation: at !== undefined ? "after-start" : "before-end",
- },
- source: cue.source,
- ...(moment === undefined ? {} : { reference: moment }),
- };
- return projectionDraft({
- ...input,
- start: at !== undefined ? cue : derived,
- end: at !== undefined ? derived : cue,
- });
+ if (Number(from !== undefined) + Number(until !== undefined) + Number(length !== undefined) !== 2) {
+ throw new Error(`${element.name} requires during or exactly two of from, until and for.`);
}
- if (start === undefined || end === undefined) {
- throw new Error(`${element.name} explicit timing requires both start and end.`);
- }
- const startExpression = parseTemporalInstant(start, `${element.name}.start`);
- const endExpression = parseTemporalInstant(end, `${element.name}.end`);
- const startSource = expressionSource(startExpression);
- const endSource = expressionSource(endExpression);
- const startBinding = element.attributes["start-source"] === undefined ? startSource : "start-source";
- const endBinding = element.attributes["end-source"] === undefined ? endSource : "end-source";
- rejectUnusedTemporalAttributes(element, temporalWindowAttributeNames, [
- "start", "end",
- ...(startSource === "program" ? [] : [startBinding]),
- ...(endSource === "program" ? [] : [endBinding]),
- ]);
- const startReference = sourceReference(element, startSource, resolveReference, startBinding);
- const endReference = sourceReference(element, endSource, resolveReference, endBinding);
- return projectionDraft({
- ...input,
- start: {
- expression: startExpression,
- authority: { kind: "parameter", binding: "start", relation: "direct" },
- source: startSource,
- ...(startReference === undefined ? {} : { reference: startReference }),
- },
- end: {
- expression: endExpression,
- authority: { kind: "parameter", binding: "end", relation: "direct" },
- source: endSource,
- ...(endReference === undefined ? {} : { reference: endReference }),
- },
- });
+ rejectUnused(element, ["from", "until", "for"]);
+ const subjectId = value.subjectId ?? value.id;
+ if (from !== undefined && until !== undefined) return constructWindow({ ...value, subjectId,
+ start: instantDraft(from, `${element.name}.from`, resolveReference),
+ end: instantDraft(until, `${element.name}.until`, resolveReference) });
+ if (from !== undefined && length !== undefined) return constructWindow({ ...value, subjectId,
+ start: instantDraft(from, `${element.name}.from`, resolveReference),
+ extent: extentDraft(length, `${element.name}.for`, resolveReference), direction: 1 });
+ if (until === undefined || length === undefined) throw new Error(`${element.name} Window form is incomplete.`);
+ return constructWindow({ ...value, subjectId,
+ start: { kind: "expression", expression: { ref: "timeline.start" } },
+ end: instantDraft(until, `${element.name}.until`, resolveReference),
+ extent: extentDraft(length, `${element.name}.for`, resolveReference), direction: -1 });
}
-/** Decode a semantic reference, an authored at time, or a projected instant expression. */
-export function createTemporalInstantProjection(input: {
- readonly id: string;
- readonly subjectId?: string;
- readonly element: StructuredElement;
- readonly timeline: SurfaceResolvedReference;
- readonly resolveReference: ResolveReference;
- readonly semanticAttribute?: string;
- readonly boundaryAttribute?: string;
- readonly boundaryFallback?: "start" | "end";
- readonly projectedAttribute?: string | false;
-}): TemporalMarkupProjection {
- const semanticAttribute = input.semanticAttribute ?? "at";
- const boundaryAttribute = input.boundaryAttribute ?? "boundary";
- const projectedAttribute = input.projectedAttribute === undefined ? "instant" : input.projectedAttribute;
- const at = input.element.attributes[semanticAttribute];
- const explicit = projectedAttribute === false ? undefined : optionalText(input.element, projectedAttribute);
- const universe = [...new Set([
- ...temporalInstantAttributeNames,
- semanticAttribute,
- boundaryAttribute,
- ...(projectedAttribute === false ? [] : [projectedAttribute]),
- ])];
- if (Number(at !== undefined) + Number(explicit !== undefined) !== 1) {
- throw new Error(`${input.element.name} requires exactly one of ${semanticAttribute}${projectedAttribute === false ? "" : ` or ${projectedAttribute}`}.`);
- }
- if (at !== undefined) {
- if (typeof at === "string") {
- rejectUnusedTemporalAttributes(input.element, universe, [semanticAttribute]);
- return projectionDraft({ ...input, start: {
- expression: { ref: "absolute", at: parseTemporalDuration(at, `${input.element.name}.${semanticAttribute}`) },
- authority: { kind: "parameter", binding: semanticAttribute, relation: "direct" }, source: "program",
- } });
- }
- const found = input.resolveReference(at.path);
- if (found === undefined) throw new Error(`${input.element.name}.${semanticAttribute} is unresolved.`);
- if (sameType(found.type, narrativeTypes.moment)) {
- if (input.element.attributes[boundaryAttribute] !== undefined) {
- throw new Error(`${input.element.name}.${boundaryAttribute} is invalid for a Moment.`);
- }
- rejectUnusedTemporalAttributes(input.element, universe, [semanticAttribute]);
- return projectionDraft({
- ...input,
- start: {
- expression: { ref: "moment.cue" },
- authority: { kind: "semantic", boundary: "cue" },
- source: "moment",
- reference: found,
- },
- });
- }
- const source = sameType(found.type, narrativeTypes.selection) ? "selection"
- : sameType(found.type, narrativeTypes.excerpt) ? "segment" : undefined;
- if (source === undefined) {
- throw new Error(`${input.element.name}.${semanticAttribute} must reference a Moment, Selection or Segment.`);
- }
- const boundary = optionalText(input.element, boundaryAttribute) ?? input.boundaryFallback;
- if (boundary !== "start" && boundary !== "end") {
- throw new Error(`${input.element.name}.${boundaryAttribute} must be start or end.`);
- }
- rejectUnusedTemporalAttributes(input.element, universe, [semanticAttribute, boundaryAttribute]);
- return projectionDraft({
- ...input,
- start: {
- expression: { ref: `${source}.${boundary}` },
- authority: source === "selection" ? { kind: "semantic", boundary } : { kind: "fixed" },
- source,
- reference: found,
- },
- });
+/** Construct or pass through one absolute Instant. */
+export function createTemporalInstantConstruction(value: {
+ readonly id: string; readonly subjectId?: string; readonly element: StructuredElement;
+ readonly timeline: SurfaceResolvedReference; readonly resolveReference: ResolveReference; readonly attribute?: string;
+}): TemporalMarkupConstruction {
+ const attribute = value.attribute ?? "at", raw = value.element.attributes[attribute];
+ if (raw === undefined) throw new Error(`${value.element.name}.${attribute} is required.`);
+ if (typeof raw !== "string") {
+ const found = resolvedReference(raw, `${value.element.name}.${attribute}`, temporalTypes.instant, value.resolveReference);
+ return { records: [], components: [], fragments: [], ref: found.ref };
}
- const expression = parseTemporalInstant(explicit!, `${input.element.name}.${projectedAttribute || "instant"}`);
- const source = expressionSource(expression);
- rejectUnusedTemporalAttributes(input.element, universe, [
- projectedAttribute || "instant",
- ...(source === "program" ? [] : [source]),
- ]);
- const reference = source === "program" ? undefined : sourceReference(input.element, source, input.resolveReference);
- return projectionDraft({
- ...input,
- start: {
- expression,
- authority: { kind: "parameter", binding: projectedAttribute || "instant", relation: "direct" },
- source,
- ...(reference === undefined ? {} : { reference }),
- },
- });
+ const specId = `${value.id}.__temporal.instant`;
+ const fragment = sealGraphFragment({ inputs: [
+ { name: "timeline", type: timelineTypes.track }, { name: "spec", type: temporalTypes.instantSpec },
+ ], operations: [{ id: "materialize", producer: temporalProducers.projectProgramInstant,
+ inputs: { timeline: fragmentInput("timeline"), spec: fragmentInput("spec") }, result: { kind: "output", name: "instant" } }],
+ exports: [{ name: "instant", type: temporalTypes.instant, root: operation("materialize") }] });
+ const componentId = `${value.id}.__temporal`;
+ return { records: [{ id: specId, type: temporalTypes.instantSpec, value: { kind: "inline", value: {
+ id: value.id, subjectId: value.subjectId ?? value.id,
+ projection: parseTemporalInstant(raw, `${value.element.name}.${attribute}`),
+ } }, range: value.element.range }], components: [{ id: componentId, fragment: fragment.id,
+ inputs: { timeline: value.timeline.ref, spec: { kind: "record", id: specId } },
+ outputs: { instant: `${value.id}.__temporal.instant.value` }, range: value.element.range }], fragments: [fragment],
+ ref: { kind: "component-output", component: componentId, output: "instant" } };
}
diff --git a/packages/temporal-markup/src/space.ts b/packages/temporal-markup/src/space.ts
deleted file mode 100644
index 61a476d7..00000000
--- a/packages/temporal-markup/src/space.ts
+++ /dev/null
@@ -1,28 +0,0 @@
-import type { StructuredElement, SurfaceAttributeVocabulary, SurfaceResolvedReference } from "@hypit/markup";
-import { timelineTypes } from "@hypit/timeline";
-
-export type TemporalContext = {
- readonly timeline: SurfaceResolvedReference;
-};
-
-export const temporalContextAttributeVocabulary = [
- { name: "timeline", kind: "reference", required: true, accepts: [timelineTypes.track],
- summary: "The complete film Timeline, with any placed material and semantic anchors." },
-] as const satisfies readonly SurfaceAttributeVocabulary[];
-
-/** One author-facing Timeline; projections share its range and evidence. */
-export function resolveTemporalContext(input: {
- readonly element: StructuredElement;
- readonly resolveReference: (path: string) => SurfaceResolvedReference | undefined;
-}): TemporalContext {
- const { element, resolveReference } = input;
- const raw = element.attributes.timeline;
- if (typeof raw !== "object" || raw.kind !== "reference") throw new Error(`${element.name}.timeline must be a reference.`);
- const found = resolveReference(raw.path);
- const expected = timelineTypes.track;
- if (found === undefined || found.type.module.name !== expected.module.name
- || found.type.module.version !== expected.module.version || found.type.name !== expected.name) {
- throw new Error(`${element.name}.timeline must reference a Timeline.`);
- }
- return { timeline: found };
-}
diff --git a/packages/temporal-markup/test/temporal-markup.test.ts b/packages/temporal-markup/test/temporal-markup.test.ts
index 2903250e..e4201580 100644
--- a/packages/temporal-markup/test/temporal-markup.test.ts
+++ b/packages/temporal-markup/test/temporal-markup.test.ts
@@ -2,119 +2,75 @@ import assert from "node:assert/strict";
import test from "node:test";
import type { MarkupAttributeValue, StructuredElement, SurfaceResolvedReference } from "@hypit/markup";
-import { narrativeTypes } from "@hypit/narrative";
-import { programSpaceTypes } from "@hypit/program-space";
+import { temporalTypes } from "@hypit/temporal";
import { timelineTypes } from "@hypit/timeline";
-import type { TemporalInstantSpec } from "@hypit/temporal";
-import { createTemporalInstantProjection, createTemporalWindowProjection, resolveTemporalContext } from "../src/index.js";
+import { createTemporalInstantConstruction, createTemporalWindowConstruction, resolveTemporalContext } from "../src/index.js";
const range = { source: "main.svml", start: 0, end: 1 };
const reference = (path: string): MarkupAttributeValue => ({ kind: "reference", path });
const resolved = (path: string, type: SurfaceResolvedReference["type"]): SurfaceResolvedReference => ({
path, type, ref: { kind: "record", id: path },
});
-
const timeline = resolved("timeline", timelineTypes.track);
const references = new Map([
- ["selection", resolved("selection", narrativeTypes.selection)],
- ["segment", resolved("segment", narrativeTypes.excerpt)],
- ["moment", resolved("moment", narrativeTypes.moment)],
+ ["timeline", timeline],
+ ["start-instant", resolved("start-instant", temporalTypes.instant)],
+ ["end-instant", resolved("end-instant", temporalTypes.instant)],
+ ["extent", resolved("extent", temporalTypes.extent)],
+ ["window", resolved("window", temporalTypes.window)],
]);
const resolveReference = (path: string) => references.get(path);
const element = (attributes: Record<string, MarkupAttributeValue>): StructuredElement => ({
kind: "element", name: "example:Item", attributes, children: [], range,
});
-const specs = (projection: ReturnType<typeof createTemporalWindowProjection>) => projection.records
- .filter((record) => record.type.name === "TemporalInstantSpec")
- .map((record) => record.value.kind === "inline" ? record.value.value as unknown as TemporalInstantSpec : undefined);
+const inlineValues = (construction: ReturnType<typeof createTemporalWindowConstruction>, typeName: string) => construction.records
+ .filter((record) => record.type.name === typeName)
+ .map((record) => record.value.kind === "inline" ? record.value.value : undefined);
-test("the author bridge owns the four Window forms and the explicit Instant fallback", () => {
- assert.deepEqual(specs(createTemporalWindowProjection({
- id: "during", element: element({ during: reference("selection") }), timeline, resolveReference,
- })).map((spec) => spec?.authority), [
- { kind: "semantic", boundary: "start" },
- { kind: "semantic", boundary: "end" },
+test("whole Timeline and absolute literals lower without any domain projector", () => {
+ const whole = createTemporalWindowConstruction({ id: "whole", element: element({ during: "timeline" }), timeline, resolveReference });
+ assert.deepEqual(inlineValues(whole, "TemporalInstantSpec"), [
+ { id: "whole.start", subjectId: "whole", projection: { ref: "timeline.start" } },
+ { id: "whole.end", subjectId: "whole", projection: { ref: "timeline.end" } },
]);
+ assert.equal(whole.fragments[0]!.inputs.some((port) => port.type.module.name.includes("narrative")), false);
- assert.deepEqual(specs(createTemporalWindowProjection({
- id: "at", element: element({ at: reference("moment"), for: "8f" }), timeline, resolveReference,
- })).map((spec) => spec?.authority), [
- { kind: "semantic", boundary: "cue" },
- { kind: "parameter", binding: "for", relation: "after-start" },
- ]);
+ const literal = createTemporalWindowConstruction({ id: "literal", element: element({ from: "2.5s", for: "8f" }), timeline, resolveReference });
+ assert.deepEqual(inlineValues(literal, "TemporalDuration"), [{ unit: "frames", value: 8 }]);
+ assert.equal(literal.fragments[0]!.operations.some((operation) => operation.producer.name === "shift-instant"), true);
+});
- assert.deepEqual(specs(createTemporalWindowProjection({
- id: "until", element: element({ until: reference("moment"), for: "8f" }), timeline, resolveReference,
- })).map((spec) => spec?.authority), [
- { kind: "parameter", binding: "for", relation: "before-end" },
- { kind: "semantic", boundary: "cue" },
- ]);
+test("resolved Instants compose a Window and an Extent shifts either boundary", () => {
+ const between = createTemporalWindowConstruction({ id: "between",
+ element: element({ from: reference("start-instant"), until: reference("end-instant") }), timeline, resolveReference });
+ assert.deepEqual(between.components[0]!.inputs["start-instant"], references.get("start-instant")!.ref);
+ assert.deepEqual(between.components[0]!.inputs["end-instant"], references.get("end-instant")!.ref);
- assert.deepEqual(specs(createTemporalWindowProjection({
- id: "explicit",
- element: element({ start: "moment.cue+3f", end: "program.end", moment: reference("moment") }),
- timeline, resolveReference,
- })).map((spec) => spec?.authority), [
- { kind: "parameter", binding: "start", relation: "direct" },
- { kind: "parameter", binding: "end", relation: "direct" },
+ const after = createTemporalWindowConstruction({ id: "after",
+ element: element({ from: reference("start-instant"), for: reference("extent") }), timeline, resolveReference });
+ assert.deepEqual(after.components[0]!.inputs.extent, references.get("extent")!.ref);
+ assert.deepEqual(inlineValues(after, "TemporalShiftSpec"), [
+ { id: "after.end", subjectId: "after", direction: 1 },
]);
-
- const instant = createTemporalInstantProjection({
- id: "fallback", element: element({ instant: "moment.cue+3f", moment: reference("moment") }),
- timeline, resolveReference,
- });
- assert.deepEqual(specs(instant as ReturnType<typeof createTemporalWindowProjection>)[0]?.authority,
- { kind: "parameter", binding: "instant", relation: "direct" });
- assert.throws(() => createTemporalInstantProjection({
- id: "ambiguous", element: element({ at: "moment.cue+3f" }), timeline, resolveReference,
- }), /exact duration/u);
});
-test("authored time and Script events use the same Timeline with different projections", () => {
- const space = resolved("animation", programSpaceTypes.programSpace);
- const at = createTemporalInstantProjection({ id: "message", element: element({ at: "2.5s" }), timeline, resolveReference });
- const absolute = specs(at as ReturnType<typeof createTemporalWindowProjection>)[0]!;
- assert.deepEqual(absolute.projection, { ref: "absolute", at: { unit: "seconds", numerator: 5, denominator: 2 } });
- assert.deepEqual(absolute.authority, { kind: "parameter", binding: "at", relation: "direct" });
- assert.equal(at.fragments.at(-1)!.inputs.some(input => input.name === "timeline"), true);
- assert.deepEqual(at.components.at(-1)!.inputs.timeline, timeline.ref);
-
- const window = specs(createTemporalWindowProjection({
- id: "bubble", element: element({ at: "2.5s", for: "8f" }), timeline, resolveReference,
- }));
- assert.deepEqual(window[1]?.projection, { ref: "absolute", at: { unit: "seconds", numerator: 5, denominator: 2 }, offset: { unit: "frames", value: 8 } });
- const bound = createTemporalInstantProjection({ id: "message", element: element({ at: reference("moment") }), timeline, resolveReference });
- assert.equal(bound.fragments.at(-1)!.inputs.some(input => input.name === "timeline"), true);
- assert.deepEqual(bound.components.at(-1)!.inputs.timeline, timeline.ref);
-
- const context = resolveTemporalContext({ element: element({ timeline: reference("timeline") }), resolveReference: path => path === "timeline" ? timeline : undefined });
- assert.deepEqual(context, { timeline });
- assert.throws(() => resolveTemporalContext({
- element: element({ timeline: reference("animation") }), resolveReference: () => space,
- }), /must reference a Timeline/);
+test("resolved Window and Instant references pass directly through", () => {
+ const window = createTemporalWindowConstruction({ id: "use", element: element({ during: reference("window") }), timeline, resolveReference });
+ assert.deepEqual(window, { records: [], components: [], fragments: [], ref: references.get("window")!.ref });
+ const instant = createTemporalInstantConstruction({ id: "cue", element: element({ at: reference("start-instant") }), timeline, resolveReference });
+ assert.deepEqual(instant, { records: [], components: [], fragments: [], ref: references.get("start-instant")!.ref });
});
-
-test("bare references and explicit offsets expose the same local parameter edit", () => {
- for (const instant of ["moment.cue", "moment.cue + 0f", "moment.cue - 2f", "20f"]) {
- const projection = createTemporalInstantProjection({
- id: "event", element: element({ instant: instant!, ...(instant!.startsWith("moment") ? { moment: reference("moment") } : {}) }),
- timeline, resolveReference,
- });
- assert.deepEqual(specs(projection)[0]!.authority, { kind: "parameter", binding: "instant", relation: "direct" });
- }
+test("Instant literals use common Timeline arithmetic", () => {
+ const at = createTemporalInstantConstruction({ id: "message", element: element({ at: "2.5s" }), timeline, resolveReference });
+ assert.deepEqual(inlineValues(at, "TemporalInstantSpec"), [
+ { id: "message", subjectId: "message", projection: { ref: "absolute", at: { unit: "seconds", numerator: 5, denominator: 2 } } },
+ ]);
});
-test("Window endpoints can bind distinct Segments without reversing a Script Selection", () => {
- const before = resolved("before", narrativeTypes.excerpt), after = resolved("after", narrativeTypes.excerpt);
- const projection = createTemporalWindowProjection({ id: "overlap", timeline,
- element: element({ start: "segment.start", "start-source": reference("after"), end: "segment.end", "end-source": reference("before") }),
- resolveReference: path => path === "before" ? before : path === "after" ? after : undefined,
- });
- assert.deepEqual(projection.components[0]!.inputs["start-segment"], after.ref);
- assert.deepEqual(projection.components[0]!.inputs["end-segment"], before.ref);
- assert.deepEqual(specs(projection).map(spec => spec?.authority), [
- { kind: "parameter", binding: "start", relation: "direct" }, { kind: "parameter", binding: "end", relation: "direct" },
- ]);
+test("Temporal context resolves only the absolute Timeline", () => {
+ assert.deepEqual(resolveTemporalContext({ element: element({ timeline: reference("timeline") }), resolveReference }), { timeline });
+ const clock = resolved("clock", timelineTypes.clock);
+ assert.throws(() => resolveTemporalContext({ element: element({ timeline: reference("clock") }), resolveReference: () => clock }), /must reference a Timeline/);
});
diff --git a/packages/temporal/README.md b/packages/temporal/README.md
index 38c0f5ee..bb9e4d57 100644
--- a/packages/temporal/README.md
+++ b/packages/temporal/README.md
@@ -1,31 +1,34 @@
# `@hypit/temporal`
-Runtime protocol for projected video time.
-
-The public values are `TemporalInstant` and `TemporalWindow`. An Instant retains its runtime source,
-exact projection expression, resolved ProgramSpace frame and author authority. A Window is composed
-from two independently traced Instants; it has no synthetic single source.
-
-Every source names its exact `ProgramSpace`; semantic sources also name their `Narrative`. Every projection retains the
-consumer's public domain identity as `subjectId`. These are public provenance fields, not generated hashes
-or editor metadata. A graph-qualified projection `id` and its author-facing `subjectId` are separate
-on purpose.
-
-Author syntax does not live here. `@hypit/temporal-markup` lowers SVML timing forms into ordinary
-Instant projection and Window composition operations. The graph supplies one Timeline;
-domain components receive that Timeline plus the resulting Instant or Window and never locate a
-Selection, Segment or Moment themselves.
-
-Every official consumer verifies the projection at its public boundary: `subjectId` must name the
-domain object being built, both endpoints must retain one time-range identity, and that identity
-must equal the explicitly supplied Timeline. Timeline is therefore an ordinary graph input
-to the consumer, not ambient renderer state.
-
-Temporal rejects Instants outside ProgramSpace and Windows that are reversed or empty. It does not
-clip or repair author time. The package also provides sibling-window validation and triggered-stage
-scheduling, but no renderer, Provider, media policy or Studio behavior.
-
-All projection Producers receive Timeline. Program-bound projection uses its complete range;
-semantic-bound projection locates its Script anchors. Both produce the same Instant type; program-bound
-sources have no Narrative identity. A Window can combine a semantic endpoint with a program endpoint
-on the same time axis. `absolute` expressions may include a duration offset, as used by `at`/`for`.
+Common absolute-time protocol for video graphs.
+
+The public coordinate values are:
+
+- `TemporalInstant`: one resolved frame boundary on one Timeline;
+- `TemporalWindow`: one non-empty half-open `[start, end)` interval; and
+- `TemporalExtent`: an unpositioned frame count on an exact frame rate.
+
+These values contain the minimal facts needed by consumers. Their derivation—Narrative Moment,
+music beat, Timeline child, literal clock position, or another source—remains in the typed graph and
+the producing package. Temporal does not carry a closed source-kind union or a domain projector.
+
+`subjectId` identifies each authored value for inspection. A Window has its own identity while its
+endpoints retain the identities of the values from which it was composed; those three identities need
+not match. It is not an ownership lock on consumers: a named Window or Instant may deliberately feed
+several components. Consumers validate Timeline identity and bounds rather than requiring their own
+id to match the value.
+
+`TemporalExtent` lets an imported or generated result determine Timeline construction without making
+Timeline understand media, speech, or the operation that discovered the length. A domain projector
+may map one complete finite source-local domain onto an equal-length Window at native speed through
+the pure exact-projection helper. This total one-to-one operation keeps every local boundary
+projectable and produces no durable Placement value.
+
+Author syntax does not live here. `@hypit/temporal-markup` constructs absolute literals and composes
+Windows. Domain packages such as `@hypit/narrative-temporal` project their own values into these
+common types. Visual, audio, caption, typography and project components receive only the completed
+Instant or Window plus the Timeline they already consume.
+
+Temporal rejects Instants outside Timeline, Windows whose endpoint Timelines or stored span disagree,
+reversed or empty Windows, non-exact local-domain projection, and incompatible frame rates. It does not
+clip, repair, infer meaning, perform rendering, or define Studio behavior.
diff --git a/packages/temporal/package.json b/packages/temporal/package.json
index b80897fb..bfdc8f52 100644
--- a/packages/temporal/package.json
+++ b/packages/temporal/package.json
@@ -12,8 +12,6 @@
},
"dependencies": {
"@hypit/component-kit": "workspace:*",
- "@hypit/narrative": "workspace:*",
- "@hypit/program-space": "workspace:*",
"@hypit/protocol": "workspace:*",
"@hypit/timeline": "workspace:*"
}
diff --git a/packages/temporal/src/component.ts b/packages/temporal/src/component.ts
index 45e3b71b..75a5a343 100644
--- a/packages/temporal/src/component.ts
+++ b/packages/temporal/src/component.ts
@@ -1,18 +1,16 @@
import type { ComponentPackage, ProducerHandlerContext } from "@hypit/component-kit";
import { canonicalize } from "@hypit/protocol";
import type { StoredValue } from "@hypit/protocol";
-import type { NarrativeExcerpt, NarrativeMomentRef, NarrativeSelectionRef } from "@hypit/narrative";
import type { Timeline } from "@hypit/timeline";
import {
composeTemporalWindow,
- projectMomentInstant,
projectProgramInstant,
- projectSegmentInstant,
- projectSelectionInstant,
} from "./projection.js";
+import { temporalExtentFromDomain, temporalExtentFromDuration } from "./extent.js";
import { temporalProducers } from "./index.js";
-import type { ProjectedInstant, TemporalInstantSpec, TemporalWindowSpec } from "./types.js";
+import type { LocalTemporalDomain, TemporalDuration, TemporalExtent, TemporalInstant, TemporalInstantSpec, TemporalShiftSpec, TemporalWindowSpec } from "./types.js";
+import { shiftTemporalInstant } from "./projection.js";
function inline<T>(value: StoredValue | undefined, label: string): T {
if (value?.kind !== "inline") throw new Error(`${label} must be inline.`);
@@ -27,41 +25,32 @@ function instantSpec(inputs: ProducerHandlerContext["inputs"]): TemporalInstantS
export const temporalComponent = {
producers: [
+ { producer: temporalProducers.extentFromDomain, handler: ({ inputs }) => ({ outputs: { extent: output(
+ temporalExtentFromDomain(inline<LocalTemporalDomain>(inputs.domain?.value, "LocalTemporalDomain")),
+ ) }, needs: {} }) },
+ { producer: temporalProducers.extentFromDuration, handler: ({ inputs }) => ({ outputs: { extent: output(
+ temporalExtentFromDuration(inline<TemporalDuration>(inputs.duration?.value, "TemporalDuration"),
+ inline<Timeline>(inputs.timeline?.value, "Timeline")),
+ ) }, needs: {} }) },
{ producer: temporalProducers.projectProgramInstant, handler: ({ inputs }) => ({ outputs: { instant: output(projectProgramInstant({
itemId: instantSpec(inputs).id,
subjectId: instantSpec(inputs).subjectId,
timeline: inline<Timeline>(inputs.timeline?.value, "Timeline"),
projection: instantSpec(inputs).projection,
- authority: instantSpec(inputs).authority,
- })) }, needs: {} }) },
- { producer: temporalProducers.projectSelectionInstant, handler: ({ inputs }) => ({ outputs: { instant: output(projectSelectionInstant({
- itemId: instantSpec(inputs).id,
- subjectId: instantSpec(inputs).subjectId,
- timeline: inline<Timeline>(inputs.timeline?.value, "Timeline"),
- selection: inline<NarrativeSelectionRef>(inputs.selection?.value, "NarrativeSelection"),
- projection: instantSpec(inputs).projection,
- authority: instantSpec(inputs).authority,
- })) }, needs: {} }) },
- { producer: temporalProducers.projectSegmentInstant, handler: ({ inputs }) => ({ outputs: { instant: output(projectSegmentInstant({
- itemId: instantSpec(inputs).id,
- subjectId: instantSpec(inputs).subjectId,
- timeline: inline<Timeline>(inputs.timeline?.value, "Timeline"),
- segment: inline<NarrativeExcerpt>(inputs.segment?.value, "NarrativeExcerpt"),
- projection: instantSpec(inputs).projection,
- authority: instantSpec(inputs).authority,
- })) }, needs: {} }) },
- { producer: temporalProducers.projectMomentInstant, handler: ({ inputs }) => ({ outputs: { instant: output(projectMomentInstant({
- itemId: instantSpec(inputs).id,
- subjectId: instantSpec(inputs).subjectId,
- timeline: inline<Timeline>(inputs.timeline?.value, "Timeline"),
- moment: inline<NarrativeMomentRef>(inputs.moment?.value, "NarrativeMoment"),
- projection: instantSpec(inputs).projection,
- authority: instantSpec(inputs).authority,
})) }, needs: {} }) },
+ { producer: temporalProducers.shiftInstant, handler: ({ inputs }) => ({ outputs: { instant: output(shiftTemporalInstant(
+ inline<TemporalShiftSpec>(inputs.spec?.value, "TemporalShiftSpec"),
+ inline<Timeline>(inputs.timeline?.value, "Timeline"),
+ inline<TemporalInstant>(inputs.instant?.value, "TemporalInstant"),
+ inline<TemporalExtent>(inputs.extent?.value, "TemporalExtent"),
+ )) }, needs: {} }) },
+ { producer: temporalProducers.reuseInstant, handler: ({ inputs }) => ({ outputs: { instant: output(
+ inline<TemporalInstant>(inputs.instant?.value, "TemporalInstant"),
+ ) }, needs: {} }) },
{ producer: temporalProducers.composeWindow, handler: ({ inputs }) => ({ outputs: { window: output(composeTemporalWindow(
inline<TemporalWindowSpec>(inputs.spec?.value, "TemporalWindowSpec"),
- inline<ProjectedInstant>(inputs.start?.value, "TemporalInstant start"),
- inline<ProjectedInstant>(inputs.end?.value, "TemporalInstant end"),
+ inline<TemporalInstant>(inputs.start?.value, "TemporalInstant start"),
+ inline<TemporalInstant>(inputs.end?.value, "TemporalInstant end"),
)) }, needs: {} }) },
],
} satisfies ComponentPackage;
diff --git a/packages/temporal/src/domain.ts b/packages/temporal/src/domain.ts
new file mode 100644
index 00000000..49871a10
--- /dev/null
+++ b/packages/temporal/src/domain.ts
@@ -0,0 +1,57 @@
+import { assertClockIdentity, assertTimelineIdentity } from "@hypit/timeline";
+import type { Timeline } from "@hypit/timeline";
+
+import { assertTemporalWindowFor } from "./projection.js";
+import type { LocalTemporalDomain, TemporalWindow } 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.`);
+}
+
+export function sealLocalTemporalDomain(value: LocalTemporalDomain): LocalTemporalDomain {
+ assertLocalTemporalDomain(value);
+ return structuredClone(value);
+}
+
+export function assertLocalTemporalDomain(value: LocalTemporalDomain): void {
+ assertIdentity(value.id, "LocalTemporalDomain.id");
+ assertClockIdentity(value);
+ assert(Number.isSafeInteger(value.frameCount) && value.frameCount > 0,
+ "LocalTemporalDomain.frameCount is invalid.");
+}
+
+/**
+ * Verify the exact, total coordinate relation used by a domain-owned projector.
+ * The relation is deliberately not materialized as a reusable author value.
+ */
+export function assertExactDomainWindow(
+ domain: LocalTemporalDomain,
+ window: TemporalWindow,
+ timeline: Timeline,
+): void {
+ assertLocalTemporalDomain(domain);
+ assertTimelineIdentity(timeline);
+ assertTemporalWindowFor(window, { timeline });
+ assert(domain.frameRate.numerator === timeline.frameRate.numerator
+ && domain.frameRate.denominator === timeline.frameRate.denominator,
+ `Local temporal domain ${domain.id} is not normalized to Timeline ${timeline.id}.`);
+ assert(window.span.endFrameExclusive - window.span.startFrame === domain.frameCount,
+ `Window ${window.id} does not cover the complete local temporal domain ${domain.id}.`);
+}
+
+/** Project one closed local boundary through an exact domain-to-Window relation. */
+export function projectDomainFrame(
+ domain: LocalTemporalDomain,
+ window: TemporalWindow,
+ timeline: Timeline,
+ frame: number,
+): number {
+ assertExactDomainWindow(domain, window, timeline);
+ assert(Number.isSafeInteger(frame) && frame >= 0 && frame <= domain.frameCount,
+ `Local frame lies outside local temporal domain ${domain.id}.`);
+ return window.span.startFrame + frame;
+}
diff --git a/packages/temporal/src/extent.ts b/packages/temporal/src/extent.ts
new file mode 100644
index 00000000..8c276153
--- /dev/null
+++ b/packages/temporal/src/extent.ts
@@ -0,0 +1,43 @@
+import { assertClockIdentity } from "@hypit/timeline";
+import type { Clock } from "@hypit/timeline";
+
+import type { LocalTemporalDomain, TemporalDuration, TemporalExtent } from "./types.js";
+import type { Timeline } from "@hypit/timeline";
+import { assertTimelineIdentity } from "@hypit/timeline";
+import { durationInFrames } from "./rational.js";
+
+function assert(condition: unknown, message: string): asserts condition {
+ if (!condition) throw new Error(message);
+}
+
+export function assertTemporalExtent(value: TemporalExtent): void {
+ assertClockIdentity(value);
+ assert(Number.isSafeInteger(value.frameCount) && value.frameCount >= 0,
+ "TemporalExtent.frameCount is invalid.");
+}
+
+export function sealTemporalExtent(value: TemporalExtent): TemporalExtent {
+ assertTemporalExtent(value);
+ return structuredClone(value);
+}
+
+export function temporalExtentFromDomain(domain: LocalTemporalDomain): TemporalExtent {
+ return sealTemporalExtent({ frameRate: structuredClone(domain.frameRate), frameCount: domain.frameCount });
+}
+
+export function temporalExtentFromDuration(duration: TemporalDuration, timeline: Timeline): TemporalExtent {
+ assertTimelineIdentity(timeline);
+ const frames = durationInFrames(duration, timeline);
+ if (frames.denominator !== 1n || frames.numerator < 0n || frames.numerator > BigInt(Number.MAX_SAFE_INTEGER)) {
+ throw new Error("Temporal duration must resolve to an exact non-negative frame count.");
+ }
+ return { frameRate: structuredClone(timeline.frameRate), frameCount: Number(frames.numerator) };
+}
+
+export function assertTemporalExtentClock(extent: TemporalExtent, clock: Clock): void {
+ assertTemporalExtent(extent);
+ assertClockIdentity(clock);
+ assert(extent.frameRate.numerator === clock.frameRate.numerator
+ && extent.frameRate.denominator === clock.frameRate.denominator,
+ "TemporalExtent is not normalized to the selected Clock.");
+}
diff --git a/packages/temporal/src/index.ts b/packages/temporal/src/index.ts
index afa4295b..c0e3554a 100644
--- a/packages/temporal/src/index.ts
+++ b/packages/temporal/src/index.ts
@@ -1,7 +1,5 @@
import type { ModuleManifest, ProducerRef, TypeRef, ValueSchema } from "@hypit/protocol";
-import { narrativeDependency, narrativeTypes } from "@hypit/narrative";
import { timelineDependency, timelineTypes } from "@hypit/timeline";
-import { programSpaceDependency, programSpaceTypes } from "@hypit/program-space";
const string = { kind: "string", minLength: 1 } as const;
const unsignedInteger = { kind: "number", integer: true, minimum: 0 } as const;
@@ -13,35 +11,18 @@ const duration: ValueSchema = { kind: "oneOf", variants: [
object({ unit: { schema: { kind: "literal", value: "seconds" } }, numerator: { schema: integer }, denominator: { schema: { kind: "number", integer: true, minimum: 1 } } }),
] };
const instant: ValueSchema = { kind: "oneOf", variants: [
- ...["program.start", "program.end", "selection.start", "selection.end", "segment.start", "segment.end", "moment.cue"].map((ref) => object({
+ ...["timeline.start", "timeline.end"].map((ref) => object({
ref: { schema: { kind: "literal", value: ref } }, offset: { schema: duration, optional: true },
})),
object({ ref: { schema: { kind: "literal", value: "absolute" } }, at: { schema: duration }, offset: { schema: duration, optional: true } }),
] };
-const sourceSchema: ValueSchema = { kind: "oneOf", variants: [
- ...["program", "selection", "segment", "moment"].map((kind) => object({
- spaceId: { schema: string }, narrativeId: { schema: string, optional: true },
- kind: { schema: { kind: "literal", value: kind } }, id: { schema: string },
- })),
-] };
-const authoritySchema: ValueSchema = { kind: "oneOf", variants: [
- object({
- kind: { schema: { kind: "literal", value: "semantic" } },
- boundary: { schema: { kind: "string", enum: ["start", "end", "cue"] } },
- }),
- object({
- kind: { schema: { kind: "literal", value: "parameter" } },
- binding: { schema: string },
- relation: { schema: { kind: "string", enum: ["direct", "after-start", "before-end"] } },
- }),
- object({ kind: { schema: { kind: "literal", value: "fixed" } } }),
-] };
const frameSpanSchema: ValueSchema = object({
startFrame: { schema: unsignedInteger },
endFrameExclusive: { schema: { kind: "number", integer: true, minimum: 1 } },
});
-export * from "./location.js";
+export * from "./domain.js";
+export * from "./extent.js";
export * from "./projection.js";
export * from "./schedule.js";
export * from "./sample.js";
@@ -49,24 +30,33 @@ export type * from "./types.js";
export const temporalModuleRef = { name: "@hypit/temporal", version: "1" } as const;
export const temporalTypes = {
+ duration: { module: temporalModuleRef, name: "TemporalDuration" },
+ extent: { module: temporalModuleRef, name: "TemporalExtent" },
+ shiftSpec: { module: temporalModuleRef, name: "TemporalShiftSpec" },
+ localDomain: { module: temporalModuleRef, name: "LocalTemporalDomain" },
instantSpec: { module: temporalModuleRef, name: "TemporalInstantSpec" },
instant: { module: temporalModuleRef, name: "TemporalInstant" },
windowSpec: { module: temporalModuleRef, name: "TemporalWindowSpec" },
window: { module: temporalModuleRef, name: "TemporalWindow" },
} satisfies Record<string, TypeRef>;
export const temporalProducers = {
+ extentFromDomain: { module: temporalModuleRef, name: "extent-from-domain" },
+ extentFromDuration: { module: temporalModuleRef, name: "extent-from-duration" },
+ shiftInstant: { module: temporalModuleRef, name: "shift-instant" },
+ reuseInstant: { module: temporalModuleRef, name: "reuse-instant" },
projectProgramInstant: { module: temporalModuleRef, name: "project-program-instant" },
- projectSelectionInstant: { module: temporalModuleRef, name: "project-selection-instant" },
- projectSegmentInstant: { module: temporalModuleRef, name: "project-segment-instant" },
- projectMomentInstant: { module: temporalModuleRef, name: "project-moment-instant" },
composeWindow: { module: temporalModuleRef, name: "compose-window" },
} satisfies Record<string, ProducerRef>;
export const temporalManifest: ModuleManifest = {
format: "hypit.module@1",
name: temporalModuleRef.name,
version: temporalModuleRef.version,
- dependencies: [narrativeDependency, programSpaceDependency, timelineDependency],
+ dependencies: [timelineDependency],
types: [
+ { name: temporalTypes.duration.name },
+ { name: temporalTypes.extent.name },
+ { name: temporalTypes.shiftSpec.name },
+ { name: temporalTypes.localDomain.name },
{ name: temporalTypes.instantSpec.name },
{ name: temporalTypes.instant.name },
{ name: temporalTypes.windowSpec.name },
@@ -74,17 +64,21 @@ export const temporalManifest: ModuleManifest = {
],
capabilities: [],
producers: [
- { name: temporalProducers.projectProgramInstant.name,
- inputs: [{ name: "timeline", type: timelineTypes.track }, { name: "spec", type: temporalTypes.instantSpec }],
- outputs: [{ name: "instant", type: temporalTypes.instant }], needs: [] },
- { name: temporalProducers.projectSelectionInstant.name,
- inputs: [{ name: "timeline", type: timelineTypes.track }, { name: "selection", type: narrativeTypes.selection }, { name: "spec", type: temporalTypes.instantSpec }],
+ { name: temporalProducers.extentFromDomain.name,
+ inputs: [{ name: "domain", type: temporalTypes.localDomain }],
+ outputs: [{ name: "extent", type: temporalTypes.extent }], needs: [] },
+ { name: temporalProducers.extentFromDuration.name,
+ inputs: [{ name: "timeline", type: timelineTypes.track }, { name: "duration", type: temporalTypes.duration }],
+ outputs: [{ name: "extent", type: temporalTypes.extent }], needs: [] },
+ { name: temporalProducers.shiftInstant.name,
+ inputs: [{ name: "timeline", type: timelineTypes.track }, { name: "instant", type: temporalTypes.instant },
+ { name: "extent", type: temporalTypes.extent }, { name: "spec", type: temporalTypes.shiftSpec }],
outputs: [{ name: "instant", type: temporalTypes.instant }], needs: [] },
- { name: temporalProducers.projectSegmentInstant.name,
- inputs: [{ name: "timeline", type: timelineTypes.track }, { name: "segment", type: narrativeTypes.excerpt }, { name: "spec", type: temporalTypes.instantSpec }],
+ { name: temporalProducers.reuseInstant.name,
+ inputs: [{ name: "instant", type: temporalTypes.instant }],
outputs: [{ name: "instant", type: temporalTypes.instant }], needs: [] },
- { name: temporalProducers.projectMomentInstant.name,
- inputs: [{ name: "timeline", type: timelineTypes.track }, { name: "moment", type: narrativeTypes.moment }, { name: "spec", type: temporalTypes.instantSpec }],
+ { name: temporalProducers.projectProgramInstant.name,
+ inputs: [{ name: "timeline", type: timelineTypes.track }, { name: "spec", type: temporalTypes.instantSpec }],
outputs: [{ name: "instant", type: temporalTypes.instant }], needs: [] },
{ name: temporalProducers.composeWindow.name,
inputs: [{ name: "spec", type: temporalTypes.windowSpec }, { name: "start", type: temporalTypes.instant }, { name: "end", type: temporalTypes.instant }],
@@ -93,12 +87,33 @@ export const temporalManifest: ModuleManifest = {
};
export const temporalDependency = { module: temporalModuleRef } as const;
+export const localTemporalDomainSchema: ValueSchema = object({
+ id: { schema: string },
+ frameRate: { schema: object({
+ numerator: { schema: { kind: "number", integer: true, minimum: 1 } },
+ denominator: { schema: { kind: "number", integer: true, minimum: 1 } },
+ }) },
+ frameCount: { schema: { kind: "number", integer: true, minimum: 1 } },
+});
+export const temporalExtentSchema: ValueSchema = object({
+ frameRate: { schema: object({
+ numerator: { schema: { kind: "number", integer: true, minimum: 1 } },
+ denominator: { schema: { kind: "number", integer: true, minimum: 1 } },
+ }) },
+ frameCount: { schema: unsignedInteger },
+});
+export const temporalDurationSchema: ValueSchema = duration;
+export const temporalShiftSpecSchema: ValueSchema = object({
+ id: { schema: string }, subjectId: { schema: string },
+ direction: { schema: { kind: "oneOf", variants: [
+ { kind: "literal", value: 1 }, { kind: "literal", value: -1 },
+ ] } },
+});
export const temporalInstantSpecSchema: ValueSchema = object({
- id: { schema: string }, subjectId: { schema: string }, projection: { schema: instant }, authority: { schema: authoritySchema },
+ id: { schema: string }, subjectId: { schema: string }, projection: { schema: instant },
});
export const temporalInstantSchema: ValueSchema = object({
- id: { schema: string }, subjectId: { schema: string }, source: { schema: sourceSchema }, projection: { schema: instant },
- authority: { schema: authoritySchema }, frame: { schema: unsignedInteger },
+ id: { schema: string }, subjectId: { schema: string }, timelineId: { schema: string }, frame: { schema: unsignedInteger },
});
export const temporalWindowSpecSchema: ValueSchema = object({ id: { schema: string }, subjectId: { schema: string } });
export const temporalWindowSchema: ValueSchema = object({
diff --git a/packages/temporal/src/location.ts b/packages/temporal/src/location.ts
deleted file mode 100644
index 992e6731..00000000
--- a/packages/temporal/src/location.ts
+++ /dev/null
@@ -1,67 +0,0 @@
-import type { NarrativeExcerpt, NarrativeMomentRef, NarrativeSelectionRef } from "@hypit/narrative";
-import { programSpaceFrameCount } from "@hypit/program-space";
-import {
- momentFrame,
- projectTimelineSpace,
- segmentFrameSpan,
- selectionFrameSpan,
-} from "@hypit/timeline";
-import type { Timeline } from "@hypit/timeline";
-
-import type {
- LocatedMoment,
- LocatedProgram,
- LocatedSegment,
- LocatedSelection,
-} from "./types.js";
-
-function assertLocatedFrame(frame: number, totalFrames: number, label: string): void {
- if (!Number.isSafeInteger(frame) || frame < 0 || frame > totalFrames) {
- throw new Error(`${label} is outside ProgramSpace.`);
- }
-}
-
-export function locateSelection(
- semantic: Timeline,
- selection: NarrativeSelectionRef,
-): LocatedSelection {
- const space = projectTimelineSpace(semantic);
- const totalFrames = programSpaceFrameCount(space);
- const span = selectionFrameSpan(semantic, selection);
- assertLocatedFrame(span.startFrame, totalFrames, `NarrativeSelection ${selection.id} start`);
- assertLocatedFrame(span.endFrameExclusive, totalFrames, `NarrativeSelection ${selection.id} end`);
- return { id: selection.id, start: { frame: span.startFrame }, end: { frame: span.endFrameExclusive } };
-}
-
-export function locateMoment(
- semantic: Timeline,
- moment: NarrativeMomentRef,
-): LocatedMoment {
- const space = projectTimelineSpace(semantic);
- const totalFrames = programSpaceFrameCount(space);
- const frame = momentFrame(semantic, moment);
- assertLocatedFrame(frame, totalFrames, `NarrativeMoment ${moment.id} cue`);
- return { id: moment.id, cue: { frame } };
-}
-
-export function locateProgram(semantic: Timeline): LocatedProgram {
- const space = projectTimelineSpace(semantic);
- return { id: "program", start: { frame: 0 }, end: { frame: programSpaceFrameCount(space) } };
-}
-
-export function locateSegment(
- semantic: Timeline,
- segment: NarrativeExcerpt,
-): LocatedSegment {
- const space = projectTimelineSpace(semantic);
- const totalFrames = programSpaceFrameCount(space);
- const span = segmentFrameSpan(semantic, segment);
- assertLocatedFrame(span.startFrame, totalFrames, `Narrative Segment ${segment.id} start`);
- assertLocatedFrame(span.endFrameExclusive, totalFrames, `Narrative Segment ${segment.id} end`);
- if (span.endFrameExclusive <= span.startFrame) throw new Error(`Narrative Segment ${segment.id} has no positive frame span.`);
- return {
- id: segment.id,
- start: { frame: span.startFrame },
- end: { frame: span.endFrameExclusive },
- };
-}
diff --git a/packages/temporal/src/projection.ts b/packages/temporal/src/projection.ts
index e689b445..e33541c5 100644
--- a/packages/temporal/src/projection.ts
+++ b/packages/temporal/src/projection.ts
@@ -1,278 +1,115 @@
-import type { NarrativeExcerpt, NarrativeMomentRef, NarrativeSelectionRef } from "@hypit/narrative";
-import { assertProgramSpaceIdentity, programSpaceFrameCount } from "@hypit/program-space";
-import type { ProgramSpace } from "@hypit/program-space";
-import { projectTimelineSpace } from "@hypit/timeline";
+import { assertTimelineIdentity, timelineFrameCount } from "@hypit/timeline";
import type { Timeline } from "@hypit/timeline";
-import { locateMoment, locateProgram, locateSegment, locateSelection } from "./location.js";
import { add, compare, durationInFrames, quantizeBoundary, rational } from "./rational.js";
import type { Rational } from "./rational.js";
import type {
- LocatedMoment,
- LocatedProgram,
- LocatedSegment,
- LocatedSelection,
- ProjectedInstant,
- ProjectedWindow,
- TemporalInstantExpression,
- TemporalInstant,
- TemporalInstantSpec,
- TemporalSource,
- TemporalWindow,
- TemporalWindowSpec,
- WindowRelation,
+ TemporalInstantExpression, TemporalInstant,
+ TemporalInstantSpec, TemporalWindow, TemporalWindowSpec, WindowRelation,
+ TemporalExtent, TemporalShiftSpec,
} from "./types.js";
-export type TemporalConsumption = {
- readonly subjectId: string;
- readonly space?: ProgramSpace;
-};
+export type TemporalConsumption = { readonly timeline?: Timeline; readonly subjectId?: string };
-/** Verify the public identity carried across a Temporal consumer boundary. */
-export function assertTemporalInstantFor(
- instant: TemporalInstant,
- expected: TemporalConsumption,
-): void {
- if (!expected.subjectId || instant.subjectId !== expected.subjectId) {
- throw new Error(`Temporal Instant subject ${instant.subjectId} does not match ${expected.subjectId}.`);
- }
- if (!instant.source.spaceId) {
- throw new Error("Temporal Instant has no ProgramSpace identity.");
- }
- if (!Number.isSafeInteger(instant.frame) || instant.frame < 0) {
- throw new Error("Temporal Instant frame is invalid.");
- }
- if (expected.space !== undefined) {
- assertProgramSpaceIdentity(expected.space);
- if (instant.source.spaceId !== expected.space.id) {
- throw new Error("Temporal Instant belongs to a different ProgramSpace.");
- }
- if (instant.frame > programSpaceFrameCount(expected.space)) {
- throw new Error("Temporal Instant falls outside its ProgramSpace.");
- }
+export function assertTemporalInstantFor(instant: TemporalInstant, expected: TemporalConsumption): void {
+ if (!instant.timelineId) throw new Error("Temporal Instant has no Timeline identity.");
+ if (!Number.isSafeInteger(instant.frame) || instant.frame < 0) throw new Error("Temporal Instant frame is invalid.");
+ if (expected.timeline !== undefined) {
+ assertTimelineIdentity(expected.timeline);
+ if (instant.timelineId !== expected.timeline.id) throw new Error("Temporal Instant belongs to a different Timeline.");
+ if (instant.frame > timelineFrameCount(expected.timeline)) throw new Error("Temporal Instant falls outside its Timeline.");
}
}
-/** Verify both endpoint provenance and the materialized span consumed by a domain program. */
-export function assertTemporalWindowFor(
- window: TemporalWindow,
- expected: TemporalConsumption,
-): void {
- if (window.subjectId !== expected.subjectId
- || window.start.subjectId !== expected.subjectId
- || window.end.subjectId !== expected.subjectId) {
- throw new Error(`Temporal Window subject ${window.subjectId} does not match ${expected.subjectId}.`);
- }
+export function assertTemporalWindowFor(window: TemporalWindow, expected: TemporalConsumption): void {
+ if (!window.subjectId) throw new Error("Temporal Window has no authored identity.");
assertTemporalInstantFor(window.start, expected);
assertTemporalInstantFor(window.end, expected);
- if (window.start.source.spaceId !== window.end.source.spaceId) {
- throw new Error("Temporal Window endpoints belong to different ProgramSpaces.");
- }
- if (window.span.startFrame !== window.start.frame
- || window.span.endFrameExclusive !== window.end.frame
- || window.span.endFrameExclusive <= window.span.startFrame) {
- throw new Error("Temporal Window span disagrees with its endpoints.");
- }
+ if (window.start.timelineId !== window.end.timelineId) throw new Error("Temporal Window endpoints belong to different Timelines.");
+ if (window.span.startFrame !== window.start.frame || window.span.endFrameExclusive !== window.end.frame
+ || window.span.endFrameExclusive <= window.span.startFrame) throw new Error("Temporal Window span disagrees with its endpoints.");
}
-type InstantEnvironment = {
- readonly program: LocatedProgram;
- readonly selection?: LocatedSelection;
- readonly moment?: LocatedMoment;
- readonly segment?: LocatedSegment;
-};
-
-function evaluateInstant(
- expression: TemporalInstantExpression,
- environment: InstantEnvironment,
- space: ProgramSpace,
-): Rational {
+function evaluateProgramInstant(expression: TemporalInstantExpression, timeline: Timeline): Rational {
if (expression.ref === "absolute") {
- const at = durationInFrames(expression.at, space);
- return expression.offset === undefined ? at : add(at, durationInFrames(expression.offset, space));
+ const at = durationInFrames(expression.at, timeline);
+ return expression.offset === undefined ? at : add(at, durationInFrames(expression.offset, timeline));
}
let base: number;
- switch (expression.ref) {
- case "program.start": base = environment.program.start.frame; break;
- case "program.end": base = environment.program.end.frame; break;
- case "selection.start": {
- if (environment.selection === undefined) throw new Error("selection.start requires a Selection.");
- base = environment.selection.start.frame;
- break;
- }
- case "selection.end": {
- if (environment.selection === undefined) throw new Error("selection.end requires a Selection.");
- base = environment.selection.end.frame;
- break;
- }
- case "segment.start": {
- if (environment.segment === undefined) throw new Error("segment.start requires a Segment.");
- base = environment.segment.start.frame;
- break;
- }
- case "segment.end": {
- if (environment.segment === undefined) throw new Error("segment.end requires a Segment.");
- base = environment.segment.end.frame;
- break;
- }
- case "moment.cue": {
- if (environment.moment === undefined) throw new Error("moment.cue requires a Moment.");
- base = environment.moment.cue.frame;
- break;
- }
- }
- return expression.offset === undefined
- ? rational(BigInt(base))
- : add(rational(BigInt(base)), durationInFrames(expression.offset, space));
+ if (expression.ref === "timeline.start") base = 0;
+ else if (expression.ref === "timeline.end") base = timelineFrameCount(timeline);
+ else throw new Error("Unsupported Timeline projection expression.");
+ return expression.offset === undefined ? rational(BigInt(base))
+ : add(rational(BigInt(base)), durationInFrames(expression.offset, timeline));
}
-export function projectTemporalInstant(
- projection: TemporalInstantExpression,
- environment: InstantEnvironment,
- space: ProgramSpace,
-): number {
- assertProgramSpaceIdentity(space);
- const totalFrames = programSpaceFrameCount(space);
- const raw = evaluateInstant(projection, environment, space);
- const lower = rational(0n);
- const upper = rational(BigInt(totalFrames));
- if (compare(raw, lower) < 0 || compare(raw, upper) > 0) {
- throw new Error("Temporal Instant projection falls outside ProgramSpace.");
+export function projectTemporalInstant(expression: TemporalInstantExpression, timeline: Timeline): number {
+ assertTimelineIdentity(timeline);
+ const totalFrames = timelineFrameCount(timeline);
+ const raw = evaluateProgramInstant(expression, timeline);
+ if (compare(raw, rational(0n)) < 0 || compare(raw, rational(BigInt(totalFrames))) > 0) {
+ throw new Error("Temporal Instant projection falls outside Timeline.");
}
const frame = quantizeBoundary(raw);
- if (frame < 0 || frame > totalFrames) {
- throw new Error("Temporal Instant projection quantizes outside ProgramSpace.");
- }
+ if (frame < 0 || frame > totalFrames) throw new Error("Temporal Instant projection quantizes outside Timeline.");
return frame;
}
-function projectedId(itemId: string, sourceId: string): string {
- if (itemId.length === 0) throw new Error("Projected item id must not be empty.");
- return `${itemId}::${sourceId}`;
-}
-
-function projectedInstant(
- spec: TemporalInstantSpec,
- source: TemporalSource,
- frame: number,
-): ProjectedInstant {
- return {
- id: projectedId(spec.id, source.id),
- subjectId: spec.subjectId,
- source: { ...source },
- projection: structuredClone(spec.projection),
- authority: structuredClone(spec.authority),
- frame,
- };
-}
-
-export function projectSelectionInstant(input: {
- readonly itemId: string;
- readonly subjectId: string;
- readonly timeline: Timeline;
- readonly selection: NarrativeSelectionRef;
- readonly projection: TemporalInstantExpression;
- readonly authority: TemporalInstantSpec["authority"];
-}): ProjectedInstant {
- const space = projectTimelineSpace(input.timeline);
- const program = locateProgram(input.timeline);
- const selection = locateSelection(input.timeline, input.selection);
- return projectedInstant(
- { id: input.itemId, subjectId: input.subjectId, projection: input.projection, authority: input.authority },
- { spaceId: space.id, narrativeId: input.selection.narrativeId, kind: "selection", id: selection.id },
- projectTemporalInstant(input.projection, { program, selection }, space),
- );
-}
-
-export function projectMomentInstant(input: {
- readonly itemId: string;
- readonly subjectId: string;
- readonly timeline: Timeline;
- readonly moment: NarrativeMomentRef;
- readonly projection: TemporalInstantExpression;
- readonly authority: TemporalInstantSpec["authority"];
-}): ProjectedInstant {
- const space = projectTimelineSpace(input.timeline);
- const program = locateProgram(input.timeline);
- const moment = locateMoment(input.timeline, input.moment);
- return projectedInstant(
- { id: input.itemId, subjectId: input.subjectId, projection: input.projection, authority: input.authority },
- { spaceId: space.id, narrativeId: input.moment.narrativeId, kind: "moment", id: moment.id },
- projectTemporalInstant(input.projection, { program, moment }, space),
- );
+export function resolvedInstant(spec: Pick<TemporalInstantSpec, "id" | "subjectId">, timeline: Timeline, frame: number): TemporalInstant {
+ if (spec.id.length === 0) throw new Error("Temporal Instant id must not be empty.");
+ assertTimelineIdentity(timeline);
+ if (!Number.isSafeInteger(frame) || frame < 0 || frame > timelineFrameCount(timeline)) {
+ throw new Error("Temporal Instant falls outside Timeline.");
+ }
+ return { id: spec.id, subjectId: spec.subjectId, timelineId: timeline.id, frame };
}
export function projectProgramInstant(input: {
- readonly itemId: string;
- readonly subjectId: string;
- readonly timeline: Timeline;
+ readonly itemId: string; readonly subjectId: string; readonly timeline: Timeline;
readonly projection: TemporalInstantExpression;
- readonly authority: TemporalInstantSpec["authority"];
-}): ProjectedInstant {
- const space = projectTimelineSpace(input.timeline);
- const program = { id: "program" as const, start: { frame: 0 }, end: { frame: programSpaceFrameCount(space) } };
- return projectedInstant(
- { id: input.itemId, subjectId: input.subjectId, projection: input.projection, authority: input.authority },
- { spaceId: space.id, kind: "program", id: program.id },
- projectTemporalInstant(input.projection, { program }, space),
- );
+}): TemporalInstant {
+ return resolvedInstant({ id: input.itemId, subjectId: input.subjectId }, input.timeline,
+ projectTemporalInstant(input.projection, input.timeline));
}
-export function projectSegmentInstant(input: {
- readonly itemId: string;
- readonly subjectId: string;
- readonly timeline: Timeline;
- readonly segment: NarrativeExcerpt;
- readonly projection: TemporalInstantExpression;
- readonly authority: TemporalInstantSpec["authority"];
-}): ProjectedInstant {
- const space = projectTimelineSpace(input.timeline);
- const program = locateProgram(input.timeline);
- const segment = locateSegment(input.timeline, input.segment);
- return projectedInstant(
- { id: input.itemId, subjectId: input.subjectId, projection: input.projection, authority: input.authority },
- { spaceId: space.id, narrativeId: input.segment.narrativeId, kind: "segment", id: segment.id },
- projectTemporalInstant(input.projection, { program, segment }, space),
- );
+export function shiftTemporalInstant(
+ spec: TemporalShiftSpec,
+ timeline: Timeline,
+ base: TemporalInstant,
+ extent: TemporalExtent,
+): TemporalInstant {
+ assertTimelineIdentity(timeline);
+ assertTemporalInstantFor(base, { timeline });
+ if (spec.id.length === 0 || spec.subjectId.length === 0) throw new Error("Temporal shift identity is invalid.");
+ if (spec.direction !== 1 && spec.direction !== -1) throw new Error("Temporal shift direction is invalid.");
+ if (extent.frameRate.numerator !== timeline.frameRate.numerator
+ || extent.frameRate.denominator !== timeline.frameRate.denominator) {
+ throw new Error("Temporal shift Extent uses another frame rate.");
+ }
+ if (!Number.isSafeInteger(extent.frameCount) || extent.frameCount < 0) {
+ throw new Error("Temporal shift Extent is invalid.");
+ }
+ return resolvedInstant(spec, timeline, base.frame + spec.direction * extent.frameCount);
}
-export function composeTemporalWindow(
- spec: TemporalWindowSpec,
- start: ProjectedInstant,
- end: ProjectedInstant,
-): ProjectedWindow {
+export function composeTemporalWindow(spec: TemporalWindowSpec, start: TemporalInstant, end: TemporalInstant): TemporalWindow {
if (spec.id.length === 0) throw new Error("Temporal Window id must not be empty.");
- if (!spec.subjectId || start.subjectId !== spec.subjectId || end.subjectId !== spec.subjectId) {
- throw new Error("Temporal Window endpoints must explicitly name the Window subject.");
- }
- if (start.source.spaceId !== end.source.spaceId) {
- throw new Error("Temporal Window endpoints must belong to one ProgramSpace.");
- }
+ if (!spec.subjectId) throw new Error("Temporal Window subjectId must not be empty.");
+ if (start.timelineId !== end.timelineId) throw new Error("Temporal Window endpoints must belong to one Timeline.");
if (end.frame < start.frame) throw new Error("Temporal Window endpoints are reversed.");
if (end.frame === start.frame) throw new Error("Temporal Window endpoints produce a zero window.");
- return {
- id: spec.id,
- subjectId: spec.subjectId,
- start: structuredClone(start),
- end: structuredClone(end),
- span: { startFrame: start.frame, endFrameExclusive: end.frame },
- };
+ return { id: spec.id, subjectId: spec.subjectId, start: structuredClone(start), end: structuredClone(end),
+ span: { startFrame: start.frame, endFrameExclusive: end.frame } };
}
-export function assertWindowRelation(
- windows: readonly ProjectedWindow[],
- relation: WindowRelation,
-): readonly ProjectedWindow[] {
+export function assertWindowRelation(windows: readonly TemporalWindow[], relation: WindowRelation): readonly TemporalWindow[] {
if (relation === "independent") return windows;
- const ordered = [...windows].sort((left, right) =>
- left.span.startFrame - right.span.startFrame
- || left.span.endFrameExclusive - right.span.endFrameExclusive
- || left.id.localeCompare(right.id));
+ const ordered = [...windows].sort((left, right) => left.span.startFrame - right.span.startFrame
+ || left.span.endFrameExclusive - right.span.endFrameExclusive || left.id.localeCompare(right.id));
for (let index = 1; index < ordered.length; index += 1) {
const previous = ordered[index - 1];
const current = ordered[index];
- if (previous !== undefined && current !== undefined
- && current.span.startFrame < previous.span.endFrameExclusive) {
+ if (previous !== undefined && current !== undefined && current.span.startFrame < previous.span.endFrameExclusive) {
throw new Error(`Temporal windows ${previous.id} and ${current.id} overlap under disjoint policy.`);
}
}
diff --git a/packages/temporal/src/rational.ts b/packages/temporal/src/rational.ts
index c538abc3..b5565116 100644
--- a/packages/temporal/src/rational.ts
+++ b/packages/temporal/src/rational.ts
@@ -1,4 +1,4 @@
-import type { ProgramClock } from "@hypit/program-space";
+import type { Clock } from "@hypit/timeline";
import type { TemporalDuration } from "./types.js";
@@ -51,9 +51,9 @@ function safeInteger(value: number, label: string): bigint {
return BigInt(value);
}
-export function durationInFrames(duration: TemporalDuration, space: ProgramClock): Rational {
- const frameNumerator = safeInteger(space.frameRate.numerator, "ProgramClock frame-rate numerator");
- const frameDenominator = safeInteger(space.frameRate.denominator, "ProgramClock frame-rate denominator");
+export function durationInFrames(duration: TemporalDuration, clock: Clock): Rational {
+ const frameNumerator = safeInteger(clock.frameRate.numerator, "Clock frame-rate numerator");
+ const frameDenominator = safeInteger(clock.frameRate.denominator, "Clock frame-rate denominator");
switch (duration.unit) {
case "frames":
return rational(safeInteger(duration.value, "Frame duration"));
diff --git a/packages/temporal/src/sample.ts b/packages/temporal/src/sample.ts
index 7fdf92a2..482241bb 100644
--- a/packages/temporal/src/sample.ts
+++ b/packages/temporal/src/sample.ts
@@ -1,4 +1,4 @@
-import type { ProgramSpace } from "@hypit/program-space";
+import type { Timeline } from "@hypit/timeline";
import type { TemporalDuration } from "./types.js";
@@ -19,7 +19,7 @@ function roundedRatio(numerator: bigint, denominator: bigint, label: string): nu
/** Quantize one non-negative authored duration into the canonical sample domain exactly once. */
export function temporalDurationInSamples(
duration: TemporalDuration,
- space: ProgramSpace,
+ timeline: Timeline,
sampleRate = 48_000,
): number {
const rate = integer(sampleRate, "Sample rate");
@@ -27,8 +27,8 @@ export function temporalDurationInSamples(
switch (duration.unit) {
case "frames":
return roundedRatio(
- integer(duration.value, "Frame duration") * rate * integer(space.frameRate.denominator, "Frame-rate denominator"),
- integer(space.frameRate.numerator, "Frame-rate numerator"),
+ integer(duration.value, "Frame duration") * rate * integer(timeline.frameRate.denominator, "Frame-rate denominator"),
+ integer(timeline.frameRate.numerator, "Frame-rate numerator"),
"Frame duration",
);
case "milliseconds":
diff --git a/packages/temporal/src/types.ts b/packages/temporal/src/types.ts
index 54c2b46d..0d35ba5b 100644
--- a/packages/temporal/src/types.ts
+++ b/packages/temporal/src/types.ts
@@ -1,77 +1,21 @@
-export type FramePoint = {
- readonly frame: number;
-};
-
-export type LocatedSelection = {
- readonly id: string;
- readonly start: FramePoint;
- readonly end: FramePoint;
-};
-
-export type LocatedMoment = {
- readonly id: string;
- readonly cue: FramePoint;
-};
-
-export type LocatedProgram = {
- readonly id: "program";
- readonly start: FramePoint;
- readonly end: FramePoint;
-};
-
-export type LocatedSegment = {
- readonly id: string;
- readonly start: FramePoint;
- readonly end: FramePoint;
-};
-
/** Exact author duration. Decimal source spelling is reduced before reaching this value. */
export type TemporalDuration =
| { readonly unit: "frames"; readonly value: number }
| { readonly unit: "milliseconds"; readonly value: number }
| { readonly unit: "seconds"; readonly numerator: number; readonly denominator: number };
-/** A single projected boundary before it is resolved into ProgramSpace. */
+/** An authored coordinate on the Timeline itself, before exact resolution. */
export type TemporalInstantExpression =
- | { readonly ref: "program.start"; readonly offset?: TemporalDuration }
- | { readonly ref: "program.end"; readonly offset?: TemporalDuration }
- | { readonly ref: "selection.start"; readonly offset?: TemporalDuration }
- | { readonly ref: "selection.end"; readonly offset?: TemporalDuration }
- | { readonly ref: "segment.start"; readonly offset?: TemporalDuration }
- | { readonly ref: "segment.end"; readonly offset?: TemporalDuration }
- | { readonly ref: "moment.cue"; readonly offset?: TemporalDuration }
+ | { readonly ref: "timeline.start"; readonly offset?: TemporalDuration }
+ | { readonly ref: "timeline.end"; readonly offset?: TemporalDuration }
| { readonly ref: "absolute"; readonly at: TemporalDuration; readonly offset?: TemporalDuration };
-/** Runtime dependency used to resolve an Instant. This is not its authoring authority. */
-export type TemporalSource = {
- readonly spaceId: string;
- /** Present when the boundary originates in a Script. */
- readonly narrativeId?: string;
- readonly kind: "program" | "selection" | "segment" | "moment";
- readonly id: string;
-};
-
-/**
- * The author-owned inverse of one projected Instant. Runtime dependencies and
- * author authority are deliberately separate: an expression may read an
- * anchor while remaining writable only at its author parameter.
- */
-export type TemporalInstantAuthority =
- | { readonly kind: "semantic"; readonly boundary: "start" | "end" | "cue" }
- | {
- readonly kind: "parameter";
- readonly binding: string;
- readonly relation: "direct" | "after-start" | "before-end";
- }
- | { readonly kind: "fixed" };
-
/** Input value for an Instant projection producer. */
export type TemporalInstantSpec = {
readonly id: string;
/** Author/domain entity whose timing this projection controls. */
readonly subjectId: string;
readonly projection: TemporalInstantExpression;
- readonly authority: TemporalInstantAuthority;
};
/** Input value for composing two resolved Instants into a Window. */
@@ -86,29 +30,49 @@ export type FrameSpan = {
readonly endFrameExclusive: number;
};
-export type ProjectedInstant = {
+/**
+ * One resolved length on a discrete frame clock. It has no absolute position,
+ * source identity, media role or Timeline ownership.
+ */
+export type TemporalExtent = {
+ readonly frameRate: { readonly numerator: number; readonly denominator: number };
+ readonly frameCount: number;
+};
+
+/** Identity and direction for shifting one resolved Instant by an exact Extent. */
+export type TemporalShiftSpec = {
readonly id: string;
readonly subjectId: string;
- readonly source: TemporalSource;
- readonly projection: TemporalInstantExpression;
- readonly authority: TemporalInstantAuthority;
+ readonly direction: 1 | -1;
+};
+
+/**
+ * One finite, source-local frame coordinate system. A domain carries no media,
+ * semantic events or presentation role; those packages retain their own facts
+ * and refer to this identity when they need a common mapping authority.
+ */
+export type LocalTemporalDomain = {
+ readonly id: string;
+ readonly frameRate: { readonly numerator: number; readonly denominator: number };
+ readonly frameCount: number;
+};
+
+/** A resolved absolute coordinate. Its derivation remains in the author graph. */
+export type TemporalInstant = {
+ readonly id: string;
+ readonly subjectId: string;
+ readonly timelineId: string;
readonly frame: number;
};
-export type ProjectedWindow = {
+export type TemporalWindow = {
readonly id: string;
readonly subjectId: string;
- readonly start: ProjectedInstant;
- readonly end: ProjectedInstant;
+ readonly start: TemporalInstant;
+ readonly end: TemporalInstant;
readonly span: FrameSpan;
};
-/** Public projection protocol consumed by domain programs. */
-export type TemporalInstant = ProjectedInstant;
-
-/** Public projection protocol composed from two independently traced Instants. */
-export type TemporalWindow = ProjectedWindow;
-
export type WindowRelation = "independent" | "disjoint";
export type TriggerPoint = {
diff --git a/packages/temporal/test/temporal.test.ts b/packages/temporal/test/temporal.test.ts
index 80a57cfd..ad97e2c4 100644
--- a/packages/temporal/test/temporal.test.ts
+++ b/packages/temporal/test/temporal.test.ts
@@ -1,334 +1,133 @@
-import { projectTimelineSpace } from "@hypit/timeline";
import assert from "node:assert/strict";
import test from "node:test";
-import type { NarrativeMomentRef, NarrativeSelectionRef } from "@hypit/narrative";
-import { programFrameSampleBoundary, programSpaceSampleFrames } from "@hypit/program-space";
-import type { ProgramSpace } from "@hypit/program-space";
-import { timelineFixture } from "../../../test/timeline-fixture.js";
+import { timelineFrameSampleBoundary, timelineSampleFrames } from "@hypit/timeline";
+import type { Timeline } from "@hypit/timeline";
import {
- assertWindowRelation,
+ assertTemporalExtentClock,
assertTemporalInstantFor,
+ assertExactDomainWindow,
+ assertTemporalWindowFor,
+ assertWindowRelation,
composeTemporalWindow,
- locateSelection,
- projectMomentInstant,
+ projectDomainFrame,
projectProgramInstant,
- projectSelectionInstant,
- projectSegmentInstant,
resolveTriggeredSchedule,
temporalDurationInSamples,
+ temporalExtentFromDomain,
} from "../src/index.js";
-const space: ProgramSpace = {
- id: "test-space",
- durationSec: 10,
- frameRate: { numerator: 30, denominator: 1 },
-};
-
-const semantic = timelineFixture(space, { narrativeId: "test-narrative",
- segments: [
- { id: "opening", frameCount: 60 },
- { id: "answer", frameCount: 60 },
- { id: "ending", frameCount: 180 },
- ],
- anchors: [
- { identity: "a", frame: 30 },
- { identity: "b", frame: 60 },
- { identity: "c", frame: 90 },
- { identity: "d", frame: 120 },
- { identity: "late", frame: 240 },
- { identity: "end", frame: 300 },
- { identity: "segment:answer:start", frame: 60 },
- { identity: "segment:answer:end", frame: 120 },
- ],
-});
-
-const selection = (id: string, startAnchorId: string, endAnchorId: string): NarrativeSelectionRef => ({
- narrativeId: "test-narrative", id, startAnchorId, endAnchorId,
-});
-const moment = (id: string, anchorId: string): NarrativeMomentRef => ({ narrativeId: "test-narrative", id, anchorId });
+const timeline: Timeline = { id: "film", frameRate: { numerator: 30, denominator: 1 }, frameCount: 300 };
const frames = (value: number) => ({ unit: "frames" as const, value });
const seconds = (numerator: number, denominator = 1) => ({ unit: "seconds" as const, numerator, denominator });
-const fixed = { kind: "fixed" as const };
-type Projection = import("../src/index.js").TemporalInstantExpression;
-const projectProgramInstantFixture = (input: { itemId: string; semantic: typeof semantic; projection: Projection }) =>
- projectProgramInstant({ ...input, timeline: input.semantic, subjectId: input.itemId, authority: fixed });
-const projectMomentInstantFixture = (input: { itemId: string; semantic: typeof semantic; moment: NarrativeMomentRef; projection: Projection }) =>
- projectMomentInstant({ ...input, timeline: input.semantic, subjectId: input.itemId, authority: fixed });
-const projectSelectionInstantFixture = (input: { itemId: string; semantic: typeof semantic; selection: NarrativeSelectionRef; projection: Projection }) =>
- projectSelectionInstant({ ...input, timeline: input.semantic, subjectId: input.itemId, authority: fixed });
-const projectSelectionWindow = (input: {
- itemId: string; semantic: typeof semantic; selection: NarrativeSelectionRef;
- projection: { start: Projection; end: Projection };
-}) => composeTemporalWindow({ id: input.itemId, subjectId: input.itemId },
- projectSelectionInstant({ itemId: `${input.itemId}.start`, subjectId: input.itemId, timeline: input.semantic, selection: input.selection, projection: input.projection.start, authority: fixed }),
- input.projection.end.ref.startsWith("program.") || input.projection.end.ref === "absolute"
- ? projectProgramInstant({ itemId: `${input.itemId}.end`, subjectId: input.itemId, timeline: input.semantic, projection: input.projection.end, authority: fixed })
- : projectSelectionInstant({ itemId: `${input.itemId}.end`, subjectId: input.itemId, timeline: input.semantic, selection: input.selection, projection: input.projection.end, authority: fixed }));
-const projectMomentWindow = (input: {
- itemId: string; semantic: typeof semantic; moment: NarrativeMomentRef;
- projection: { start: Projection; end: Projection };
-}) => composeTemporalWindow({ id: input.itemId, subjectId: input.itemId },
- projectMomentInstant({ itemId: `${input.itemId}.start`, subjectId: input.itemId, timeline: input.semantic, moment: input.moment, projection: input.projection.start, authority: fixed }),
- projectMomentInstant({ itemId: `${input.itemId}.end`, subjectId: input.itemId, timeline: input.semantic, moment: input.moment, projection: input.projection.end, authority: fixed }));
-const projectSegmentWindow = (input: {
- itemId: string; semantic: typeof semantic; segment: import("@hypit/narrative").NarrativeExcerpt;
- projection: { start: Projection; end: Projection };
-}) => composeTemporalWindow({ id: input.itemId, subjectId: input.itemId },
- projectSegmentInstant({ itemId: `${input.itemId}.start`, subjectId: input.itemId, timeline: input.semantic, segment: input.segment, projection: input.projection.start, authority: fixed }),
- projectSegmentInstant({ itemId: `${input.itemId}.end`, subjectId: input.itemId, timeline: input.semantic, segment: input.segment, projection: input.projection.end, authority: fixed }));
-const projectProgramWindow = (input: {
- itemId: string; semantic: typeof semantic; projection: { start: Projection; end: Projection };
-}) => composeTemporalWindow({ id: input.itemId, subjectId: input.itemId },
- projectProgramInstant({ itemId: `${input.itemId}.start`, subjectId: input.itemId, timeline: input.semantic, projection: input.projection.start, authority: fixed }),
- projectProgramInstant({ itemId: `${input.itemId}.end`, subjectId: input.itemId, timeline: input.semantic, projection: input.projection.end, authority: fixed }));
-
-test("one Selection projects exact local points and stable source identity", () => {
- const result = projectSelectionWindow({
- itemId: "card",
- semantic,
- selection: selection("proof", "a", "b"),
- projection: { start: { ref: "selection.start" }, end: { ref: "selection.end" } },
- });
- assert.equal(result.id, "card");
- assert.equal(result.start.source.id, "proof");
- assert.equal(result.end.source.id, "proof");
- assert.deepEqual(result.span, { startFrame: 30, endFrameExclusive: 60 });
-});
+const instant = (id: string, projection: import("../src/index.js").TemporalInstantExpression) =>
+ projectProgramInstant({ itemId: id, subjectId: "subject", timeline, projection });
-test("points preserve source identity and admit both ProgramSpace boundaries", () => {
- assert.deepEqual(projectProgramInstantFixture({
- itemId: "terminal",
- semantic,
- projection: { ref: "program.end" },
- }), {
- id: "terminal::program",
- subjectId: "terminal",
- source: { spaceId: "test-space", kind: "program", id: "program" },
- projection: { ref: "program.end" },
- authority: fixed,
- frame: 300,
+test("TemporalExtent preserves only unpositioned length and Clock", () => {
+ const extent = temporalExtentFromDomain({
+ id: "voice-local", frameRate: timeline.frameRate, frameCount: 90,
});
- assert.deepEqual(projectMomentInstantFixture({
- itemId: "terminal",
- semantic,
- moment: moment("done", "end"),
- projection: { ref: "moment.cue" },
- }), {
- id: "terminal::done",
- subjectId: "terminal",
- source: { spaceId: "test-space", narrativeId: "test-narrative", kind: "moment", id: "done" },
- projection: { ref: "moment.cue" },
- authority: fixed,
- frame: 300,
+ assert.deepEqual(extent, { frameRate: timeline.frameRate, frameCount: 90 });
+ assert.doesNotThrow(() => assertTemporalExtentClock(extent, timeline));
+ assert.throws(() => assertTemporalExtentClock(extent, {
+ ...timeline, frameRate: { numerator: 24, denominator: 1 },
+ }), /selected Clock/u);
+});
+
+test("one domain projector is a total exact translation of one complete local domain", () => {
+ const domain = { id: "voice-local", frameRate: timeline.frameRate, frameCount: 90 };
+ const start = instant("voice.start", { ref: "absolute", at: frames(150) });
+ const end = instant("voice.end", { ref: "absolute", at: frames(240) });
+ const window = composeTemporalWindow({ id: "voice", subjectId: "voice" }, start, end);
+ assert.doesNotThrow(() => assertExactDomainWindow(domain, window, timeline));
+ assert.equal(projectDomainFrame(domain, window, timeline, 0), 150);
+ assert.equal(projectDomainFrame(domain, window, timeline, 90), 240);
+});
+
+test("domain projection rejects incompatible Clocks, unequal Windows and invalid local frames", () => {
+ const domain = { id: "voice-local", frameRate: { numerator: 24, denominator: 1 }, frameCount: 48 };
+ const start = instant("voice.start", { ref: "absolute", at: frames(30) });
+ const end = instant("voice.end", { ref: "absolute", at: frames(78) });
+ const window = composeTemporalWindow({ id: "voice", subjectId: "voice" }, start, end);
+ assert.throws(() => assertExactDomainWindow(domain, window, timeline), /not normalized/u);
+ const normalized = { ...domain, frameRate: timeline.frameRate };
+ const short = composeTemporalWindow({ id: "short", subjectId: "voice" }, start,
+ instant("short.end", { ref: "absolute", at: frames(77) }));
+ assert.throws(() => assertExactDomainWindow(normalized, short, timeline), /does not cover/u);
+ assert.throws(() => projectDomainFrame(normalized, window, timeline, -1), /outside local temporal domain/u);
+ assert.throws(() => projectDomainFrame(normalized, window, timeline, 49), /outside local temporal domain/u);
+});
+
+test("Timeline and absolute expressions resolve to minimal absolute Instants", () => {
+ assert.deepEqual(instant("start", { ref: "timeline.start" }), {
+ id: "start", subjectId: "subject", timelineId: "film", frame: 0,
});
- assert.equal(projectProgramInstantFixture({
- itemId: "start",
- semantic,
- projection: { ref: "program.start" },
- }).frame, 0);
-});
-
-test("Script Program Anchors resolve through the Timeline without entering a SemanticTake", () => {
- assert.deepEqual(locateSelection(semantic, selection("whole", "program:start", "program:end")), {
- id: "whole", start: { frame: 0 }, end: { frame: 300 },
- });
- assert.equal(projectMomentInstantFixture({
- itemId: "outro",
- semantic,
- moment: moment("outro", "program:end"),
- projection: { ref: "moment.cue" },
- }).frame, 300);
-});
-
-test("a point may consume one boundary of a crossed Selection", () => {
- const crossed = selection("crossed", "d", "a");
- assert.equal(projectSelectionInstantFixture({
- itemId: "boundary",
- semantic,
- selection: crossed,
- projection: { ref: "selection.end" },
- }).frame, 30);
-});
-
-test("points reject exact coordinates outside ProgramSpace", () => {
- assert.throws(() => projectProgramInstantFixture({
- itemId: "before",
- semantic,
- projection: { ref: "program.start", offset: frames(-1) },
- }), /falls outside ProgramSpace/u);
- assert.throws(() => projectProgramInstantFixture({
- itemId: "after",
- semantic,
- projection: { ref: "program.end", offset: frames(1) },
- }), /falls outside ProgramSpace/u);
-});
-
-test("one Segment projects from its own structural start and end anchors", () => {
- const result = projectSegmentWindow({
- itemId: "answer-card",
- semantic,
- segment: { kind: "segment", narrativeId: "test-narrative", id: "answer", tokenStart: 0, tokenEndExclusive: 1 },
- projection: { start: { ref: "segment.start" }, end: { ref: "segment.end" } },
+ assert.deepEqual(instant("end", { ref: "timeline.end" }), {
+ id: "end", subjectId: "subject", timelineId: "film", frame: 300,
});
- assert.equal(result.id, "answer-card");
- assert.equal(result.start.source.id, "answer");
- assert.equal(result.end.source.id, "answer");
- assert.deepEqual(result.span, { startFrame: 60, endFrameExclusive: 120 });
-});
-
-test("Instant endpoints outside ProgramSpace are rejected before Window composition", () => {
- assert.throws(() => projectMomentWindow({
- itemId: "lead",
- semantic,
- moment: moment("cue", "a"),
- projection: {
- start: { ref: "moment.cue", offset: seconds(-2) },
- end: { ref: "moment.cue", offset: { unit: "milliseconds", value: 550 } },
- },
- }), /falls outside ProgramSpace/u);
-});
-
-test("program and absolute projections use exact rational frame-rate arithmetic", () => {
- const ntsc: ProgramSpace = {
- id: "test-space", durationSec: 1.001,
- frameRate: { numerator: 30_000, denominator: 1_001 },
- };
- const result = projectProgramWindow({
- itemId: "absolute",
- semantic: timelineFixture(ntsc),
- projection: {
- start: { ref: "absolute", at: { unit: "milliseconds", value: 500 } },
- end: { ref: "absolute", at: seconds(1) },
- },
+ assert.equal(instant("absolute", { ref: "absolute", at: seconds(5, 2), offset: frames(8) }).frame, 83);
+});
+
+test("Instant projection uses exact rational clock arithmetic and rejects out-of-range points", () => {
+ const ntsc: Timeline = { id: "ntsc", frameRate: { numerator: 30_000, denominator: 1_001 }, frameCount: 30 };
+ assert.equal(projectProgramInstant({ itemId: "half", subjectId: "half", timeline: ntsc,
+ projection: { ref: "absolute", at: { unit: "milliseconds", value: 500 } } }).frame, 15);
+ assert.throws(() => instant("before", { ref: "timeline.start", offset: frames(-1) }), /falls outside Timeline/u);
+ assert.throws(() => instant("after", { ref: "timeline.end", offset: frames(1) }), /falls outside Timeline/u);
+});
+
+test("Window composition keeps its own identity while accepting independent endpoint origins", () => {
+ const start = projectProgramInstant({ itemId: "reveal", subjectId: "semantic.reveal", timeline,
+ projection: { ref: "absolute", at: frames(30) } });
+ const end = projectProgramInstant({ itemId: "answer-end", subjectId: "semantic.answer-end", timeline,
+ projection: { ref: "absolute", at: frames(90) } });
+ const window = composeTemporalWindow({ id: "window", subjectId: "authored.reveal-band" }, start, end);
+ assert.deepEqual(window, {
+ id: "window",
+ subjectId: "authored.reveal-band",
+ start,
+ end,
+ span: { startFrame: 30, endFrameExclusive: 90 },
});
- assert.deepEqual(result.span, { startFrame: 15, endFrameExclusive: 30 });
+ assert.doesNotThrow(() => assertTemporalWindowFor(window, { timeline }));
+ assert.throws(() => composeTemporalWindow({ id: "zero", subjectId: "subject" }, start, start), /zero window/u);
+ assert.throws(() => composeTemporalWindow({ id: "reverse", subjectId: "subject" }, end, start), /reversed/u);
});
-test("an authored clock needs no narrative and combines absolute time with frame offsets", () => {
- const point = (itemId: string, projection: Projection) => projectProgramInstant({ itemId, subjectId: "bubble", timeline: { ...space, items: [] }, projection, authority: fixed });
- const start = point("start", { ref: "absolute", at: seconds(5, 2) });
- const end = point("end", { ref: "absolute", at: seconds(5, 2), offset: frames(8) });
- assert.deepEqual(composeTemporalWindow({ id: "bubble", subjectId: "bubble" }, start, end).span,
- { startFrame: 75, endFrameExclusive: 83 });
- assert.equal(start.source.narrativeId, undefined);
-});
-
-test("shared physical time preserves semantic ownership and rejects another film clock", () => {
- const cue = projectMomentInstantFixture({
- itemId: "reveal", semantic, moment: moment("answer", "b"), projection: { ref: "moment.cue" },
- });
- const end = projectProgramInstant({
- itemId: "end", subjectId: "reveal", timeline: { ...space, items: [] },
- projection: { ref: "absolute", at: seconds(3) }, authority: fixed,
- });
- const window = composeTemporalWindow({ id: "reveal", subjectId: "reveal" }, cue, end);
- assert.deepEqual(window.span, { startFrame: 60, endFrameExclusive: 90 });
- assert.equal(window.start.source.narrativeId, "test-narrative");
- assert.equal(window.end.source.narrativeId, undefined);
- assert.throws(() => projectMomentInstantFixture({
- itemId: "reveal", semantic, moment: { ...moment("answer", "b"), narrativeId: "another-story" },
- projection: { ref: "moment.cue" },
- }), /belongs to Narrative another-story/u);
- assert.throws(() => assertTemporalInstantFor(cue, {
- subjectId: "reveal", space: { ...space, id: "another-film" },
- }), /different ProgramSpace/u);
+test("resolved Instants validate only absolute execution identity", () => {
+ const value = instant("point", { ref: "absolute", at: frames(40) });
+ assert.doesNotThrow(() => assertTemporalInstantFor(value, { subjectId: "subject", timeline }));
+ assert.throws(() => assertTemporalInstantFor(value, { subjectId: "subject", timeline: { ...timeline, id: "other" } }), /different Timeline/u);
});
test("frame and authored durations enter one exact sample-boundary rule", () => {
- const ntsc: ProgramSpace = {
- id: "test-space", durationSec: 1.001,
- frameRate: { numerator: 30_000, denominator: 1_001 },
- };
- assert.equal(programFrameSampleBoundary(ntsc, 15, 48_000), 24_024);
- assert.equal(programSpaceSampleFrames(ntsc, 48_000), 48_048);
+ const ntsc: Timeline = { id: "ntsc", frameRate: { numerator: 30_000, denominator: 1_001 }, frameCount: 30 };
+ assert.equal(timelineFrameSampleBoundary(ntsc, 15, 48_000), 24_024);
+ assert.equal(timelineSampleFrames(ntsc, 48_000), 48_048);
assert.equal(temporalDurationInSamples(frames(15), ntsc), 24_024);
assert.equal(temporalDurationInSamples({ unit: "milliseconds", value: 125 }, ntsc), 6_000);
assert.equal(temporalDurationInSamples(seconds(1, 3), ntsc), 16_000);
- const twentyFour: ProgramSpace = {
- id: "test-space", durationSec: 1,
- frameRate: { numerator: 24, denominator: 1 },
- };
- assert.equal(programFrameSampleBoundary(twentyFour, 1, 44_100), 1_838,
- "half-sample boundaries round to the later sample deterministically");
});
-test("crossed source anchors are allowed until a projection actually consumes the reversal", () => {
- const crossed = selection("crossed", "d", "a");
- assert.deepEqual(locateSelection(semantic, crossed), {
- id: "crossed", start: { frame: 120 }, end: { frame: 30 },
- });
- assert.throws(() => projectSelectionWindow({
- itemId: "identity", semantic, selection: crossed,
- projection: { start: { ref: "selection.start" }, end: { ref: "selection.end" } },
- }), /endpoints are reversed/u);
- assert.deepEqual(projectSelectionWindow({
- itemId: "persist", semantic, selection: crossed,
- projection: { start: { ref: "selection.start" }, end: { ref: "program.end" } },
- }).span, { startFrame: 120, endFrameExclusive: 300 });
-});
-
-test("zero, fully outside and sub-frame windows fail atomically", () => {
- assert.throws(() => projectProgramWindow({
- itemId: "zero", semantic,
- projection: { start: { ref: "program.start" }, end: { ref: "program.start" } },
- }), /zero window/u);
- assert.throws(() => projectProgramWindow({
- itemId: "outside", semantic,
- projection: { start: { ref: "program.end", offset: frames(1) }, end: { ref: "program.end", offset: frames(2) } },
- }), /falls outside ProgramSpace/u);
- assert.throws(() => projectProgramWindow({
- itemId: "tiny", semantic,
- projection: {
- start: { ref: "absolute", at: seconds(1, 100) },
- end: { ref: "absolute", at: seconds(7, 500) },
- },
- }), /zero window/u);
-});
-
-test("disjoint validation checks physical overlap without reordering the input", () => {
- const windows = [
- projectMomentWindow({
- itemId: "later", semantic, moment: moment("later", "c"),
- projection: { start: { ref: "moment.cue" }, end: { ref: "moment.cue", offset: seconds(3) } },
- }),
- projectMomentWindow({
- itemId: "earlier", semantic, moment: moment("earlier", "a"),
- projection: { start: { ref: "moment.cue" }, end: { ref: "moment.cue", offset: seconds(3) } },
- }),
- ];
+test("disjoint validation checks physical overlap without reordering input", () => {
+ const window = (id: string, start: number, end: number) => composeTemporalWindow({ id, subjectId: "subject" },
+ instant(`${id}.start`, { ref: "absolute", at: frames(start) }),
+ instant(`${id}.end`, { ref: "absolute", at: frames(end) }));
+ const windows = [window("later", 90, 180), window("earlier", 30, 120)];
assert.equal(assertWindowRelation(windows, "independent"), windows);
assert.throws(() => assertWindowRelation(windows, "disjoint"), /overlap under disjoint/u);
});
-test("triggered schedule derives cumulative, exclusive and settled windows from authored order", () => {
- const result = resolveTriggeredSchedule({
- outer: { startFrame: 0, endFrameExclusive: 300 },
- terminalFrame: 240,
- triggers: [{ id: "one", frame: 30 }, { id: "two", frame: 90 }, { id: "three", frame: 150 }],
- });
+test("triggered schedule derives cumulative and exclusive windows from authored order", () => {
+ const result = resolveTriggeredSchedule({ outer: { startFrame: 0, endFrameExclusive: 300 }, terminalFrame: 240,
+ triggers: [{ id: "one", frame: 30 }, { id: "two", frame: 90 }, { id: "three", frame: 150 }] });
assert.deepEqual(result.cumulative, [
- { startFrame: 30, endFrameExclusive: 300 },
- { startFrame: 90, endFrameExclusive: 300 },
- { startFrame: 150, endFrameExclusive: 300 },
+ { startFrame: 30, endFrameExclusive: 300 }, { startFrame: 90, endFrameExclusive: 300 }, { startFrame: 150, endFrameExclusive: 300 },
]);
assert.deepEqual(result.exclusive, [
- { startFrame: 30, endFrameExclusive: 90 },
- { startFrame: 90, endFrameExclusive: 150 },
- { startFrame: 150, endFrameExclusive: 240 },
+ { startFrame: 30, endFrameExclusive: 90 }, { startFrame: 90, endFrameExclusive: 150 }, { startFrame: 150, endFrameExclusive: 240 },
]);
-});
-
-test("triggered schedule rejects equal, reversed and out-of-bound points", () => {
- const outer = { startFrame: 20, endFrameExclusive: 200 };
- assert.throws(() => resolveTriggeredSchedule({
- outer, terminalFrame: 180, triggers: [{ id: "a", frame: 40 }, { id: "b", frame: 40 }],
- }), /strictly increasing/u);
- assert.throws(() => resolveTriggeredSchedule({
- outer, terminalFrame: 180, triggers: [{ id: "a", frame: 40 }, { id: "b", frame: 30 }],
- }), /strictly increasing/u);
- assert.throws(() => resolveTriggeredSchedule({
- outer, terminalFrame: 180, triggers: [{ id: "a", frame: 180 }],
- }), /outside/u);
+ assert.throws(() => resolveTriggeredSchedule({ outer: { startFrame: 20, endFrameExclusive: 200 }, terminalFrame: 180,
+ triggers: [{ id: "a", frame: 40 }, { id: "b", frame: 40 }] }), /strictly increasing/u);
});
diff --git a/packages/text-fine-studio/README.md b/packages/text-fine-studio/README.md
new file mode 100644
index 00000000..2a015f7a
--- /dev/null
+++ b/packages/text-fine-studio/README.md
@@ -0,0 +1,8 @@
+# `@hypit/text-fine-studio`
+
+Hypit Studio Companion for `@hypit/text-fine`.
+
+`Flow`, `Point` and `Path` are projected from their package-owned `.occurrence` value, so Studio can
+recover the authored text, absolute Window and spatial binding without reconstructing an aggregate
+Typography Track. The Inspector hides geometry-specific Recipe fields that the selected occurrence
+form cannot consume.
diff --git a/packages/typography-track-studio/package.json b/packages/text-fine-studio/package.json
similarity index 80%
rename from packages/typography-track-studio/package.json
rename to packages/text-fine-studio/package.json
index c3ae5dd0..4001f4ea 100644
--- a/packages/typography-track-studio/package.json
+++ b/packages/text-fine-studio/package.json
@@ -1,5 +1,5 @@
{
- "name": "@hypit/typography-track-studio",
+ "name": "@hypit/text-fine-studio",
"version": "0.0.0-dev",
"license": "SEE LICENSE IN LICENSE",
"private": true,
@@ -13,7 +13,7 @@
"dependencies": {
"@hypit/composition": "workspace:*",
"@hypit/studio-adapter": "workspace:*",
- "@hypit/typography-track": "workspace:*",
+ "@hypit/text-fine": "workspace:*",
"@hypit/fonts-open": "workspace:*"
}
}
diff --git a/packages/text-fine-studio/src/activation.ts b/packages/text-fine-studio/src/activation.ts
new file mode 100644
index 00000000..13c64434
--- /dev/null
+++ b/packages/text-fine-studio/src/activation.ts
@@ -0,0 +1,7 @@
+import { createStudioTrackCompanionHostFacet } from "@hypit/studio-adapter";
+import { textFineStudioTrackCompanions } from "./index.js";
+
+export default {
+ format: "hypit.node-package@1" as const,
+ hostFacets: [createStudioTrackCompanionHostFacet(textFineStudioTrackCompanions)],
+};
diff --git a/packages/text-fine-studio/src/index.ts b/packages/text-fine-studio/src/index.ts
new file mode 100644
index 00000000..7bcc120d
--- /dev/null
+++ b/packages/text-fine-studio/src/index.ts
@@ -0,0 +1,143 @@
+import { openFontStudioFields } from "@hypit/fonts-open/studio";
+import { textFineMarkupSurfaces, textFineModuleRef, textFineTypes } from "@hypit/text-fine";
+import type { FineTextOccurrence, TextItem } from "@hypit/text-fine";
+import { compositionTypes } from "@hypit/composition";
+import type { StudioTrackCompanion, StudioTrackCompanionContext, StudioEntityDraft, StudioInspectorFieldDeclaration, StudioSourceBindingDeclaration } from "@hypit/studio-adapter";
+import { childEntities, requiredSurfaceValue, temporalLineageFor, textLayer } from "@hypit/studio-adapter";
+
+const fontInspector = openFontStudioFields("style");
+
+const typographyProperties = (textFineMarkupSurfaces
+ .find((surface) => surface.name === "style")?.vocabulary.attributes
+ .find((attribute) => attribute.name === "recipe")?.recipe ?? []);
+
+function title(name: string): string {
+ return name.split("-").map((part) => `${part.slice(0, 1).toUpperCase()}${part.slice(1)}`).join(" ");
+}
+
+function valuesFor(property: typeof typographyProperties[number]): readonly string[] | undefined {
+ return "values" in property ? property.values : undefined;
+}
+
+type TypographyPlacement = Pick<StudioInspectorFieldDeclaration, "domain" | "page" | "section">;
+
+function typographyPlace(domain: "where" | "how", page: string, section: string): TypographyPlacement {
+ const id = section.toLowerCase().replaceAll(" ", "-");
+ return { domain, page: { id: page.toLowerCase(), label: page }, section: { id, label: section } };
+}
+
+const typographyPlacement = new Map<string, TypographyPlacement>();
+function placeTypography(names: readonly string[], domain: "where" | "how", page: string, section: string): void {
+ for (const name of names) typographyPlacement.set(name, typographyPlace(domain, page, section));
+}
+
+placeTypography([
+ "size", "weight", "font-style", "line-height", "tracking", "word-spacing", "kerning", "synthesis", "language",
+ "direction", "writing-mode", "baseline-shift", "vertical-align", "tab-size", "indent", "paragraph-before",
+ "paragraph-after", "transform", "caps", "cjk-spacing", "punctuation-trim",
+], "how", "Typography", "Typography");
+placeTypography(["fill"], "how", "Paint", "Fill");
+
+const typographyColorProperties = new Set(["fill"]);
+const typographyTextProperties = new Set(["language", "cjk-spacing", "punctuation-trim"]);
+
+const typographyInspector: readonly StudioInspectorFieldDeclaration[] = typographyProperties.map((property) => {
+ const placement = typographyPlacement.get(property.name);
+ if (placement === undefined) throw new Error(`Typography Studio has no explicit Inspector declaration for ${property.name}.`);
+ const options = valuesFor(property);
+ return {
+ binding: `style.${property.name}`, label: title(property.name), ...placement,
+ ...(property.summary === undefined ? {} : { summary: property.summary }),
+ control: options !== undefined ? "select" : typographyColorProperties.has(property.name) ? "color"
+ : typographyTextProperties.has(property.name) ? "text" : "number",
+ ...(options === undefined ? {} : { options }),
+ };
+});
+
+function textOf(item: Pick<TextItem, "document">): string {
+ return item.document.paragraphs.map((paragraph) => paragraph.inlines
+ .map((inline) => inline.kind === "text" ? inline.text : " ")
+ .join(""))
+ .join(" ")
+ .replace(/\s+/gu, " ")
+ .trim();
+}
+
+function projectFineText(context: StudioTrackCompanionContext): readonly StudioEntityDraft[] {
+ const occurrence = requiredSurfaceValue(context, "occurrence") as FineTextOccurrence;
+ const entity = childEntities(context, [{
+ id: occurrence.id,
+ startFrame: occurrence.span.startFrame,
+ endFrameExclusive: occurrence.span.endFrameExclusive,
+ stackOrder: occurrence.placement.z,
+ sourceTypes: [textFineTypes.itemSpec, textFineTypes.plainItemSpec],
+ }], "typography-item", "standard")[0];
+ if (entity === undefined) return [];
+ const label = textOf(occurrence);
+ const temporal = temporalLineageFor(context, occurrence.id, "window");
+ return [{
+ ...entity,
+ authoredId: context.placement?.id ?? occurrence.id,
+ display: { ...entity.display, title: context.placement?.id ?? occurrence.id, layers: label.length === 0 ? [] : [textLayer(label)] },
+ ...(context.placement === undefined ? {} : { elementRange: context.placement.range }),
+ ...(temporal === undefined ? {} : { temporal }),
+ }];
+}
+
+const placementBindings: Readonly<Record<"flow" | "point" | "path", readonly StudioSourceBindingDeclaration[]>> = {
+ flow: ["z", "inline-size", "block-size", "padding", "align", "block-align", "wrap", "overflow", "max-lines", "minimum-scale", "clip", "columns", "column-gap", "metric-edge"].map((name) => ({ name, writable: true })),
+ point: ["z", "anchor-inline", "anchor-block"].map((name) => ({ name, writable: true })),
+ path: ["z", "side", "orientation", "start-margin", "end-margin", "align", "reverse", "overflow"].map((name) => ({ name, writable: true })),
+};
+
+const placementOptions = new Map<string, readonly string[]>([
+ ["inline-size", ["hug", "fixed"]], ["block-size", ["hug", "fixed"]],
+ ["align:flow", ["start", "center", "end", "justify"]], ["align:path", ["start", "center", "end"]],
+ ["block-align", ["start", "center", "end"]], ["wrap", ["none", "word", "grapheme"]],
+ ["overflow:flow", ["visible", "clip", "ellipsis", "shrink"]], ["overflow:path", ["visible", "clip"]],
+ ["metric-edge", ["line-box", "cap-height", "ink"]], ["anchor-inline", ["start", "center", "end"]],
+ ["anchor-block", ["start", "center", "end"]], ["side", ["left", "right"]],
+ ["orientation", ["follow", "upright"]], ["reverse", ["true", "false"]], ["clip", ["true", "false"]],
+]);
+
+function occurrenceInspector(form: "flow" | "point" | "path"): readonly StudioInspectorFieldDeclaration[] {
+ const direct = placementBindings[form].map(({ name }) => {
+ const options = placementOptions.get(`${name}:${form}`) ?? placementOptions.get(name);
+ return {
+ binding: name, label: title(name), ...typographyPlace("where", "Layout", name === "z" ? "Stacking" : title(form)),
+ control: options === undefined ? (name === "padding" ? "text" as const : "number" as const) : "select" as const,
+ ...(options === undefined ? {} : { options }),
+ };
+ });
+ return [...direct, ...fontInspector.fields, ...typographyInspector];
+}
+
+function fineTextCompanion(form: "flow" | "point" | "path"): StudioTrackCompanion {
+ const geometry = form === "flow" ? "within" : form;
+ return {
+ id: form, role: "track",
+ output: { type: compositionTypes.visualTrack, surface: form, modules: [textFineModuleRef] },
+ family: "text", tone: "violet", icon: "text",
+ bindings: [
+ { name: geometry },
+ { name: "content" },
+ ...placementBindings[form],
+ {
+ name: "style",
+ referenced: [fontInspector.binding],
+ recipe: { through: ["recipe"], bindings: typographyProperties.map(({ name }) => ({ name })) },
+ },
+ { name: "motion" },
+ ...(form === "path" ? [{ name: "path-motion" }] : []),
+ ],
+ inspector: occurrenceInspector(form),
+ requiredValues: ["occurrence"], project: projectFineText,
+ lane: { heightPx: 48 },
+ };
+}
+
+export const textFineStudioTrackCompanions: readonly StudioTrackCompanion[] = [
+ fineTextCompanion("flow"),
+ fineTextCompanion("point"),
+ fineTextCompanion("path"),
+];
diff --git a/packages/text-fine/README.md b/packages/text-fine/README.md
new file mode 100644
index 00000000..baf0a58e
--- /dev/null
+++ b/packages/text-fine/README.md
@@ -0,0 +1,87 @@
+# `@hypit/text-fine`
+
+This package is the fine-text family for independently authored titles, labels and short editorial
+copy. Its preferred author surfaces are occurrences rather than an aggregate text Track:
+
+- `Flow` flows one document inside a SpatialFrame;
+- `Point` hangs one document from a SpatialPoint;
+- `Path` sets one document along a SpatialPath.
+
+Each occurrence takes an explicit Timeline and absolute Window, publishes its package-owned
+`.occurrence` for Studio and sibling text tools, and publishes `.visual` for Film. It does not own a
+Timeline, Narrative or semantic projection. A semantic, beat or other upstream domain can project
+its evidence into an ordinary Window and pass that Window through `during`.
+
+```svml
+<import as="copy" from="@hypit/text@1"/>
+<import as="typo" from="@hypit/text-fine@1"/>
+
+<copy:Value id="headline-copy">A useful idea, clearly shown.</copy:Value>
+
+<typo:Flow id="headline" timeline={film.timeline} within={layout.headline}
+ style={title-style} z="40" align="center" block-align="center"
+ during={story-hook} content={headline-copy}/>
+
+<typo:Point id="chapter" timeline={film.timeline} point={layout.chapter}
+ style={label-style} z="40" anchor-inline="start"
+ from="2s" for="90f">CHAPTER ONE</typo:Point>
+
+<typo:Path id="orbit" timeline={film.timeline} path={layout.orbit}
+ style={orbit-style} z="40" motion={orbit-motion}
+ from="timeline.start + 1s" until="timeline.end">
+ FOLLOW THE CURVE
+</typo:Path>
+```
+
+`during` accepts `timeline` or a resolved absolute Window. Otherwise exactly two of `from`, `until`
+and `for` author absolute timing directly. These surfaces deliberately have no `semantic`, `selection`,
+`segment` or `moment` attribute: semantic time is one possible producer of a Window, not a special
+capability every visual component must carry.
+
+For words displayed as they are spoken, use a [Caption family](../caption-fine/README.md). Caption
+Track remains useful because it aggregates a continuing CaptionDocument/CaptionTiming stream;
+unrelated titles do not acquire that lifecycle merely because they are text.
+
+The fine-text renderer supports rich documents, font stacks, Paint, wrapping, overflow and motion at
+occurrence, word or grapheme level. Placement and time are separate from the Style Recipe. The
+separate `typo:Mask` consumes one occurrence plus one owned still material and publishes `.visual`;
+read its vocabulary for its deliberately bounded mask forms.
+
+Flow, Point and Path are already geometry in the program picture plane; they are not pixel sources
+and do not acquire a redundant `SpatialMap2D`. The Mask's still material is different: it has an
+intrinsic local pixel plane, so its `contain`, `cover` or `fill` convenience resolves through the
+shared Spatial mapping algebra before the material is cut by the glyphs. Typography therefore reuses
+source mapping only where a real source plane exists.
+
+Content has two explicit author forms:
+
+```svml
+<import as="copy" from="@hypit/text@1"/>
+<import as="typo" from="@hypit/text-fine@1"/>
+
+<copy:Value id="headline-copy">A useful idea, clearly shown.</copy:Value>
+
+<typo:Flow id="headline" timeline={film.timeline} content={headline-copy}
+ within={layout.headline} style={title-style} z="40" during="timeline"/>
+
+<typo:Flow id="editorial" timeline={film.timeline} within={layout.editorial}
+ style={body-style} z="40" during="timeline">
+ <typo:P>Rich <typo:Span style={accent}>authored</typo:Span> typography.</typo:P>
+</typo:Flow>
+```
+
+`content={...}` consumes an ordinary graph `Text` and is exclusive with body content. It becomes
+one plain document run; the occurrence still owns placement, timing, appearance and motion. Inline body
+content owns a bounded rich `VisualTextDocument`. Dynamic rich text is intentionally not smuggled
+through generic `Text`; it would require a separate explicit rich-document contract.
+
+`<typo:P>`, `<typo:Span>` and `<typo:Break>` are declared children of every occurrence, so they are
+discoverable from the Surface vocabulary rather than from prose. A `style` on a `<typo:P>` or a
+`<typo:Span>` replaces the whole typography record, not only the paints: that paragraph or run is
+shaped with the referenced Style's own exact font at its own size, weight and slant, so one document
+can mix typefaces. Geometry, form-specific layout and `z` are direct occurrence attributes and never
+enter the reusable Style, so a paragraph or run cannot accidentally move or restack its occurrence.
+
+There is no aggregate Typography Track or Typography-owned collection Program. Several independent
+occurrences remain several explicit `.visual` contributions; a coordinated text-led visual role is
+one project component rather than an accidental collection of unrelated strings.
diff --git a/packages/typography-track/package.json b/packages/text-fine/package.json
similarity index 87%
rename from packages/typography-track/package.json
rename to packages/text-fine/package.json
index e7597c09..a285abdd 100644
--- a/packages/typography-track/package.json
+++ b/packages/text-fine/package.json
@@ -1,5 +1,5 @@
{
- "name": "@hypit/typography-track",
+ "name": "@hypit/text-fine",
"version": "0.0.0-dev",
"license": "SEE LICENSE IN LICENSE",
"private": true,
@@ -15,9 +15,7 @@
"@hypit/composition": "workspace:*",
"@hypit/elaborator": "workspace:*",
"@hypit/media": "workspace:*",
- "@hypit/narrative": "workspace:*",
"@hypit/protocol": "workspace:*",
- "@hypit/program-space": "workspace:*",
"@hypit/timeline": "workspace:*",
"@hypit/spatial": "workspace:*",
"@hypit/svs": "workspace:*",
diff --git a/packages/typography-track/preview/Mask.png b/packages/text-fine/preview/Mask.png
similarity index 100%
rename from packages/typography-track/preview/Mask.png
rename to packages/text-fine/preview/Mask.png
diff --git a/packages/typography-track/preview/Track.png b/packages/text-fine/preview/Track.png
similarity index 100%
rename from packages/typography-track/preview/Track.png
rename to packages/text-fine/preview/Track.png
diff --git a/packages/text-fine/src/activation.ts b/packages/text-fine/src/activation.ts
new file mode 100644
index 00000000..98263015
--- /dev/null
+++ b/packages/text-fine/src/activation.ts
@@ -0,0 +1,51 @@
+import { createMarkupSurfaceHostFacet } from "@hypit/markup";
+import {
+ decodeTypographyMotionSurface,
+ decodeTypographyPathMotionSurface,
+ decodeTypographyMaskSurface,
+ decodeTypographyFlowSurface,
+ decodeTypographyPointSurface,
+ decodeTypographyPathSurface,
+ decodeTypographyStyleSurface,
+ textFineComponent,
+ textFineManifest,
+ textFineModuleRef,
+ textFineMarkupSurfaces,
+} from "./index.js";
+
+export const hypitPackage = {
+ format: "hypit.node-package@1" as const,
+ modules: [{ manifest: textFineManifest }],
+ components: [textFineComponent],
+ hostFacets: [
+ createMarkupSurfaceHostFacet({
+ module: textFineModuleRef,
+ declaration: textFineMarkupSurfaces.find((item) => item.name === "style")!, handler: decodeTypographyStyleSurface,
+ }),
+ createMarkupSurfaceHostFacet({
+ module: textFineModuleRef,
+ declaration: textFineMarkupSurfaces.find((item) => item.name === "motion")!, handler: decodeTypographyMotionSurface,
+ }),
+ createMarkupSurfaceHostFacet({
+ module: textFineModuleRef,
+ declaration: textFineMarkupSurfaces.find((item) => item.name === "path-motion")!, handler: decodeTypographyPathMotionSurface,
+ }),
+ createMarkupSurfaceHostFacet({
+ module: textFineModuleRef,
+ declaration: textFineMarkupSurfaces.find((item) => item.name === "flow")!, handler: decodeTypographyFlowSurface,
+ }),
+ createMarkupSurfaceHostFacet({
+ module: textFineModuleRef,
+ declaration: textFineMarkupSurfaces.find((item) => item.name === "point")!, handler: decodeTypographyPointSurface,
+ }),
+ createMarkupSurfaceHostFacet({
+ module: textFineModuleRef,
+ declaration: textFineMarkupSurfaces.find((item) => item.name === "path")!, handler: decodeTypographyPathSurface,
+ }),
+ createMarkupSurfaceHostFacet({
+ module: textFineModuleRef,
+ declaration: textFineMarkupSurfaces.find((item) => item.name === "mask")!, handler: decodeTypographyMaskSurface,
+ }),
+ ],
+};
+export default hypitPackage;
diff --git a/packages/typography-track/src/component.ts b/packages/text-fine/src/component.ts
similarity index 50%
rename from packages/typography-track/src/component.ts
rename to packages/text-fine/src/component.ts
index 7bbf4289..cb52cdd7 100644
--- a/packages/typography-track/src/component.ts
+++ b/packages/text-fine/src/component.ts
@@ -6,18 +6,20 @@ import type { StoredValue } from "@hypit/protocol";
import type { Text } from "@hypit/text";
import { canonicalize } from "@hypit/protocol";
-import { typographyTrackProducers } from "./manifest.js";
-import { appendProjectedTextItem, bindAreaTextPlacement, bindPathTextPlacement, bindPointTextPlacement, createTypographyTrackSet, finalizeTypographyTrack, renderTypographyTrack, renderTextMaskTrack, materializePlainTextItem } from "./program.js";
+import { textFineProducers } from "./manifest.js";
+import { bindAreaTextPlacement, bindPathTextPlacement, bindPointTextPlacement, createFineTextOccurrence, renderFineTextMask, renderFineTextOccurrence, materializePlainTextItem } from "./program.js";
import type {
+ FineTextOccurrence,
TextItemSpec,
PlainTextItemSpec,
TextPlacement,
+ TextFlowPlacementPolicy,
TextMotion,
+ TextPathMotion,
+ TextPathPlacementPolicy,
+ TextPointPlacementPolicy,
TextMaskSpec,
TextStyle,
- TypographyTrackHeader,
- TypographyTrackProgram,
- TypographyTrackSet,
} from "./types.js";
import type { TemporalWindow } from "@hypit/temporal";
@@ -28,36 +30,40 @@ function inline<T>(value: StoredValue | undefined, subject: string): T {
const output = (value: unknown) => ({ kind: "inline" as const, value: canonicalize(value) });
-export const typographyTrackComponent = {
+export const textFineComponent = {
producers: [
{
- producer: typographyTrackProducers.materializePlainItem,
+ producer: textFineProducers.materializePlainItem,
handler: ({ inputs }) => ({ outputs: { spec: output(materializePlainTextItem(
inline<PlainTextItemSpec>(inputs.spec?.value, "PlainTextItemSpec"),
inline<Text>(inputs.content?.value, "Text"),
)) }, needs: {} }),
},
{
- producer: typographyTrackProducers.bindPoint,
- handler: ({ inputs }) => ({ outputs: { placement: output(bindPointTextPlacement(inline<SpatialPoint>(inputs.point?.value, "SpatialPoint"))) }, needs: {} }),
- },
- {
- producer: typographyTrackProducers.bindArea,
- handler: ({ inputs }) => ({ outputs: { placement: output(bindAreaTextPlacement(inline<SpatialFrame>(inputs.frame?.value, "SpatialFrame"))) }, needs: {} }),
+ producer: textFineProducers.bindPoint,
+ handler: ({ inputs }) => ({ outputs: { placement: output(bindPointTextPlacement(
+ inline<SpatialPoint>(inputs.point?.value, "SpatialPoint"),
+ inline<TextPointPlacementPolicy>(inputs.policy?.value, "TextPointPlacementPolicy"),
+ )) }, needs: {} }),
},
{
- producer: typographyTrackProducers.bindPath,
- handler: ({ inputs }) => ({ outputs: { placement: output(bindPathTextPlacement(inline<SpatialPath>(inputs.path?.value, "SpatialPath"))) }, needs: {} }),
+ producer: textFineProducers.bindArea,
+ handler: ({ inputs }) => ({ outputs: { placement: output(bindAreaTextPlacement(
+ inline<SpatialFrame>(inputs.frame?.value, "SpatialFrame"),
+ inline<TextFlowPlacementPolicy>(inputs.policy?.value, "TextFlowPlacementPolicy"),
+ )) }, needs: {} }),
},
{
- producer: typographyTrackProducers.createSet,
- handler: () => ({ outputs: { set: output(createTypographyTrackSet()) }, needs: {} }),
+ producer: textFineProducers.bindPath,
+ handler: ({ inputs }) => ({ outputs: { placement: output(bindPathTextPlacement(
+ inline<SpatialPath>(inputs.path?.value, "SpatialPath"),
+ inline<TextPathPlacementPolicy>(inputs.policy?.value, "TextPathPlacementPolicy"),
+ inline<TextPathMotion>(inputs.marginMotion?.value, "TextPathMotion"),
+ )) }, needs: {} }),
},
{
- producer: typographyTrackProducers.appendItem,
- handler: ({ inputs }) => ({ outputs: { set: output(appendProjectedTextItem(
- inline<TypographyTrackSet>(inputs.set?.value, "TypographyTrackSet"),
- inline<TypographyTrackHeader>(inputs.header?.value, "TypographyTrackHeader"),
+ producer: textFineProducers.createOccurrence,
+ handler: ({ inputs }) => ({ outputs: { occurrence: output(createFineTextOccurrence(
inline<Timeline>(inputs.timeline?.value, "Timeline"),
inline<TextPlacement>(inputs.placement?.value, "TextPlacement"),
inline<TextItemSpec>(inputs.spec?.value, "TextItemSpec"),
@@ -67,24 +73,17 @@ export const typographyTrackComponent = {
)) }, needs: {} }),
},
{
- producer: typographyTrackProducers.finalize,
- handler: ({ inputs }) => ({ outputs: { program: output(finalizeTypographyTrack(
- inline<TypographyTrackHeader>(inputs.header?.value, "TypographyTrackHeader"),
- inline<TypographyTrackSet>(inputs.set?.value, "TypographyTrackSet"),
- )) }, needs: {} }),
- },
- {
- producer: typographyTrackProducers.render,
- handler: ({ inputs }) => ({ outputs: { track: output(renderTypographyTrack(
+ producer: textFineProducers.renderOccurrence,
+ handler: ({ inputs }) => ({ outputs: { visual: output(renderFineTextOccurrence(
inline<Timeline>(inputs.timeline?.value, "Timeline"),
- inline<TypographyTrackProgram>(inputs.program?.value, "TypographyTrackProgram"),
+ inline<FineTextOccurrence>(inputs.occurrence?.value, "FineTextOccurrence"),
)) }, needs: {} }),
},
{
- producer: typographyTrackProducers.renderMask,
- handler: ({ inputs }) => ({ outputs: { track: output(renderTextMaskTrack(
+ producer: textFineProducers.renderOccurrenceMask,
+ handler: ({ inputs }) => ({ outputs: { visual: output(renderFineTextMask(
inline<Timeline>(inputs.timeline?.value, "Timeline"),
- inline<TypographyTrackProgram>(inputs.program?.value, "TypographyTrackProgram"),
+ inline<FineTextOccurrence>(inputs.occurrence?.value, "FineTextOccurrence"),
inline<CompositableSurfaceRef>(inputs.material?.value, "CompositableSurfaceRef"),
inline<TextMaskSpec>(inputs.spec?.value, "TextMaskSpec"),
)) }, needs: {} }),
diff --git a/packages/text-fine/src/index.ts b/packages/text-fine/src/index.ts
new file mode 100644
index 00000000..74df6211
--- /dev/null
+++ b/packages/text-fine/src/index.ts
@@ -0,0 +1,13 @@
+export { textFineComponent } from "./component.js";
+export { fineTextOccurrenceSchema, fineTextWindowAttributeVocabulary, textFineManifest, textFineMarkupSurfaces, textFineModuleRef, textFineProducers, textFineTypes } from "./manifest.js";
+export { assertFineTextOccurrenceIdentity, assertPlainTextItemSpec, bindAreaTextPlacement, bindPathTextPlacement, bindPointTextPlacement, assertTextItemSpec, assertTextMaskSpec, assertTextMotion, assertTextPathMotion, assertTextPlacement, assertTextStyle, createFineTextOccurrence, renderFineTextMask, renderFineTextOccurrence, sealTextItemSpec, sealPlainTextItemSpec, materializePlainTextItem, sealTextMotion, sealTextPathMotion, sealTextMaskSpec, sealTextPlacement, sealTextStyle, stillTextMotion, stillTextPathMotion } from "./program.js";
+export {
+ decodeTypographyMotionSurface,
+ decodeTypographyPathMotionSurface,
+ decodeTypographyFlowSurface,
+ decodeTypographyPointSurface,
+ decodeTypographyPathSurface,
+ decodeTypographyStyleSurface,
+ decodeTypographyMaskSurface,
+} from "./surface.js";
+export type * from "./types.js";
diff --git a/packages/typography-track/src/manifest.ts b/packages/text-fine/src/manifest.ts
similarity index 50%
rename from packages/typography-track/src/manifest.ts
rename to packages/text-fine/src/manifest.ts
index fcc812f0..78a25155 100644
--- a/packages/typography-track/src/manifest.ts
+++ b/packages/text-fine/src/manifest.ts
@@ -1,11 +1,6 @@
-import { timelineTypes } from "@hypit/timeline";
-import type { Timeline } from "@hypit/timeline";
-import { temporalContextAttributeVocabulary } from "@hypit/temporal-markup";
+import { timelineTypes, timelineDependency } from "@hypit/timeline";
import { readFile } from "node:fs/promises";
-import { narrativeDependency } from "@hypit/narrative";
-
-import { timelineDependency } from "@hypit/timeline";
import {
compositionDependency,
compositionTypes,
@@ -36,29 +31,29 @@ const previewImage = (file: string) => ({
open: async () => Uint8Array.from(await readFile(new URL(`../preview/${file}`, import.meta.url))),
});
-export const typographyTrackModuleRef = { name: "@hypit/typography-track", version: "1" } as const;
-export const typographyTrackTypes = {
- style: { module: typographyTrackModuleRef, name: "TextStyle" },
- motion: { module: typographyTrackModuleRef, name: "TextMotion" },
- placement: { module: typographyTrackModuleRef, name: "TextPlacement" },
- program: { module: typographyTrackModuleRef, name: "TypographyTrackProgram" },
- header: { module: typographyTrackModuleRef, name: "TypographyTrackHeader" },
- itemSpec: { module: typographyTrackModuleRef, name: "TextItemSpec" },
- plainItemSpec: { module: typographyTrackModuleRef, name: "PlainTextItemSpec" },
- set: { module: typographyTrackModuleRef, name: "TypographyTrackSet" },
- maskSpec: { module: typographyTrackModuleRef, name: "TextMaskSpec" },
+export const textFineModuleRef = { name: "@hypit/text-fine", version: "1" } as const;
+export const textFineTypes = {
+ style: { module: textFineModuleRef, name: "TextStyle" },
+ motion: { module: textFineModuleRef, name: "TextMotion" },
+ pathMotion: { module: textFineModuleRef, name: "TextPathMotion" },
+ flowPlacementPolicy: { module: textFineModuleRef, name: "TextFlowPlacementPolicy" },
+ pointPlacementPolicy: { module: textFineModuleRef, name: "TextPointPlacementPolicy" },
+ pathPlacementPolicy: { module: textFineModuleRef, name: "TextPathPlacementPolicy" },
+ placement: { module: textFineModuleRef, name: "TextPlacement" },
+ occurrence: { module: textFineModuleRef, name: "FineTextOccurrence" },
+ itemSpec: { module: textFineModuleRef, name: "TextItemSpec" },
+ plainItemSpec: { module: textFineModuleRef, name: "PlainTextItemSpec" },
+ maskSpec: { module: textFineModuleRef, name: "TextMaskSpec" },
} satisfies Record<string, TypeRef>;
-export const typographyTrackProducers = {
- bindPoint: { module: typographyTrackModuleRef, name: "bind-point-placement" },
- bindArea: { module: typographyTrackModuleRef, name: "bind-area-placement" },
- bindPath: { module: typographyTrackModuleRef, name: "bind-path-placement" },
- createSet: { module: typographyTrackModuleRef, name: "create-typography-track-set" },
- appendItem: { module: typographyTrackModuleRef, name: "append-text-item" },
- finalize: { module: typographyTrackModuleRef, name: "finalize-typography-track" },
- render: { module: typographyTrackModuleRef, name: "render-typography-track" },
- renderMask: { module: typographyTrackModuleRef, name: "render-text-mask-track" },
- materializePlainItem: { module: typographyTrackModuleRef, name: "materialize-plain-text-item" },
+export const textFineProducers = {
+ bindPoint: { module: textFineModuleRef, name: "bind-point-placement" },
+ bindArea: { module: textFineModuleRef, name: "bind-area-placement" },
+ bindPath: { module: textFineModuleRef, name: "bind-path-placement" },
+ materializePlainItem: { module: textFineModuleRef, name: "materialize-plain-text-item" },
+ createOccurrence: { module: textFineModuleRef, name: "create-fine-text-occurrence" },
+ renderOccurrence: { module: textFineModuleRef, name: "render-fine-text-occurrence" },
+ renderOccurrenceMask: { module: textFineModuleRef, name: "render-fine-text-mask" },
} satisfies Record<string, ProducerRef>;
const string = { kind: "string", minLength: 1 } as const;
@@ -91,38 +86,45 @@ const areaFlow = (() => {
})();
export const textStyleSchema: ValueSchema = object({
-
- id: { schema: string }, stackingOrder: { schema: signedInteger },
+ id: { schema: string },
typography: { schema: visualTextTypographySchema },
paints: { schema: { kind: "array", items: visualTextPaintSchema } },
- area: { schema: areaFlow },
- point: { schema: object({ anchorInline: { schema: enumString(["start", "center", "end"]) }, anchorBlock: { schema: enumString(["start", "center", "end"]) } }) },
- path: { schema: object({
- side: { schema: enumString(["left", "right"]) }, orientation: { schema: enumString(["follow", "upright"]) },
- startMarginPx: { schema: { kind: "number", minimum: 0 } }, endMarginPx: { schema: { kind: "number", minimum: 0 } },
- align: { schema: enumString(["start", "center", "end"]) }, reverse: { schema: { kind: "boolean" } },
- overflow: { schema: enumString(["visible", "clip"]) },
- }) },
});
export const textMotionSchema: ValueSchema = object({
id: { schema: string },
item: { schema: visualAnimation, optional: true },
sequences: { schema: { kind: "array", items: visualTextSequenceSchema } },
- pathMargin: { schema: object({ keyframes: { schema: { kind: "array", minItems: 2, items: object({
+});
+
+export const textPathMotionSchema: ValueSchema = object({
+ id: { schema: string },
+ keyframes: { schema: { kind: "array", items: object({
atFrame: { schema: integer }, startMarginPx: { schema: { kind: "number", minimum: 0 } },
easing: { schema: enumString(["linear", "ease-in", "ease-out", "ease-in-out"]), optional: true },
- }) } } }), optional: true },
+ }) } },
});
-const geometry: ValueSchema = { kind: "oneOf", variants: [
- object({ kind: { schema: { kind: "literal", value: "point" } }, point: { schema: spatialPointSchema } }),
- object({ kind: { schema: { kind: "literal", value: "area" } }, frame: { schema: spatialFrameSchema } }),
- object({ kind: { schema: { kind: "literal", value: "path" } }, path: { schema: spatialPathSchema } }),
-] };
-export const textPlacementSchema: ValueSchema = object({
- geometry: { schema: geometry },
+export const textFlowPlacementPolicySchema: ValueSchema = object({
+ z: { schema: signedInteger }, flow: { schema: areaFlow },
+});
+export const textPointPlacementPolicySchema: ValueSchema = object({
+ z: { schema: signedInteger },
+ anchorInline: { schema: enumString(["start", "center", "end"]) },
+ anchorBlock: { schema: enumString(["start", "center", "end"]) },
});
+export const textPathPlacementPolicySchema: ValueSchema = object({
+ z: { schema: signedInteger }, side: { schema: enumString(["left", "right"]) },
+ orientation: { schema: enumString(["follow", "upright"]) },
+ startMarginPx: { schema: { kind: "number", minimum: 0 } }, endMarginPx: { schema: { kind: "number", minimum: 0 } },
+ align: { schema: enumString(["start", "center", "end"]) }, reverse: { schema: { kind: "boolean" } },
+ overflow: { schema: enumString(["visible", "clip"]) },
+});
+export const textPlacementSchema: ValueSchema = { kind: "oneOf", variants: [
+ object({ kind: { schema: { kind: "literal", value: "flow" } }, z: { schema: signedInteger }, frame: { schema: spatialFrameSchema }, flow: { schema: areaFlow } }),
+ object({ kind: { schema: { kind: "literal", value: "point" } }, z: { schema: signedInteger }, point: { schema: spatialPointSchema }, anchorInline: { schema: enumString(["start", "center", "end"]) }, anchorBlock: { schema: enumString(["start", "center", "end"]) } }),
+ object({ kind: { schema: { kind: "literal", value: "path" } }, z: { schema: signedInteger }, path: { schema: spatialPathSchema }, side: { schema: enumString(["left", "right"]) }, orientation: { schema: enumString(["follow", "upright"]) }, startMarginPx: { schema: { kind: "number", minimum: 0 } }, endMarginPx: { schema: { kind: "number", minimum: 0 } }, align: { schema: enumString(["start", "center", "end"]) }, reverse: { schema: { kind: "boolean" } }, overflow: { schema: enumString(["visible", "clip"]) }, marginMotion: { schema: textPathMotionSchema, optional: true } }),
+] };
export const textItemSpecSchema: ValueSchema = object({
id: { schema: string },
document: { schema: visualTextDocumentSchema },
@@ -131,17 +133,11 @@ export const plainTextItemSpecSchema: ValueSchema = object({
id: { schema: string },
});
const span = object({ startFrame: { schema: integer }, endFrameExclusive: { schema: positiveInteger } });
-const item = object({
- id: { schema: string }, span: { schema: span }, geometry: { schema: geometry },
+export const fineTextOccurrenceSchema: ValueSchema = object({
+ timelineId: { schema: string },
+ id: { schema: string }, span: { schema: span }, placement: { schema: textPlacementSchema },
document: { schema: visualTextDocumentSchema }, style: { schema: textStyleSchema }, motion: { schema: textMotionSchema },
- tieBreak: { schema: string },
});
-export const typographyTrackProgramSchema: ValueSchema = object({
- id: { schema: string },
- items: { schema: { kind: "array", minItems: 1, items: item } },
-});
-const typographyTrackHeaderSchema = object({ id: { schema: string } });
-const typographyTrackSetSchema = object({ items: { schema: { kind: "array", items: item } } });
const textMaskSpecSchema = object({
id: { schema: string }, mode: { schema: enumString(["alpha", "luminance"]) },
@@ -149,13 +145,13 @@ const textMaskSpecSchema = object({
});
-/** The document an item owns, written the same way inside a Point, an Area or a Path. */
+/** The document an occurrence owns, written the same way inside a Point, Flow or Path. */
const documentChildren = [
{ tag: "P", cardinality: "many",
- summary: "One paragraph of the item's document. It holds direct text, Span runs and Break line breaks in the order they are written, and can be drawn in a Style of its own.",
+ summary: "One paragraph of the occurrence's document. It holds direct text, Span runs and Break line breaks in the order they are written, and can be drawn in a Style of its own.",
attributes: [
{ name: "id", kind: "identifier", required: false, summary: "Names this paragraph inside the document; an omitted id is generated from the paragraph's position." },
- { name: "style", kind: "reference", required: false, accepts: [typographyTrackTypes.style], summary: "Redraws the whole paragraph in another compiled Style, whose typography and Paint replace the item's: the paragraph is shaped with that Style's exact font and set at its size, weight and slant, and painted in its fills, outlines, glows, shadows, boxes and decorations. That Style's area, point, path and stacking-order properties are ignored here." },
+ { name: "style", kind: "reference", required: false, accepts: [textFineTypes.style], summary: "Redraws the whole paragraph in another compiled Style, whose typography and Paint replace the item's: the paragraph is shaped with that Style's exact font and set at its size, weight and slant, and painted in its fills, outlines, glows, shadows, boxes and decorations. Geometry, layout and stacking remain facts of the enclosing occurrence." },
],
text: "Direct text between the nested elements is one run of the paragraph, drawn in the paragraph's own Style.",
children: [
@@ -163,7 +159,7 @@ const documentChildren = [
summary: "One run of the paragraph set apart from its neighbours, drawn in a Style, shaped under a language or laid out in a writing direction of its own.",
attributes: [
{ name: "id", kind: "identifier", required: false, summary: "Names this run inside the paragraph; an omitted id is generated from the run's position." },
- { name: "style", kind: "reference", required: false, accepts: [typographyTrackTypes.style], summary: "Redraws this run alone in another compiled Style, whose typography and Paint replace the paragraph's: the run is shaped with that Style's exact font and set at its size, weight and slant, and painted in its fills, outlines, glows, shadows, boxes and decorations. That Style's area, point, path and stacking-order properties are ignored here." },
+ { name: "style", kind: "reference", required: false, accepts: [textFineTypes.style], summary: "Redraws this run alone in another compiled Style, whose typography and Paint replace the paragraph's: the run is shaped with that Style's exact font and set at its size, weight and slant, and painted in its fills, outlines, glows, shadows, boxes and decorations. Geometry, layout and stacking remain facts of the enclosing occurrence." },
{ name: "language", kind: "literal", required: false, summary: "Names the language tag this run alone is shaped under." },
{ name: "direction", kind: "literal", required: false, values: ["auto", "ltr", "rtl"], summary: "Decides the base writing direction of this run alone." },
],
@@ -173,18 +169,36 @@ const documentChildren = [
] },
] as const;
-export const typographyTrackMarkupSurfaces = [
- { name: "style", tag: "Style", mode: "structured", outputs: [typographyTrackTypes.style],
+/** Absolute timing only. Semantic sources remain free to project a Window first. */
+export const fineTextWindowAttributeVocabulary = [
+ ...temporalWindowAttributeVocabulary,
+] as const;
+
+const fineTextCommonAttributes = [
+ { name: "id", kind: "identifier", required: true, summary: "Names this independent text occurrence and both compiled outputs." },
+ { name: "timeline", kind: "reference", required: true, accepts: [timelineTypes.track], summary: "The absolute Timeline on which this occurrence is placed." },
+ { name: "style", kind: "reference", required: true, accepts: [textFineTypes.style], summary: "Chooses the compiled fine-text Style." },
+ { name: "z", kind: "literal", required: true, summary: "Sets this occurrence's absolute picture stacking position; it is not part of the reusable Style." },
+ { name: "motion", kind: "reference", required: false, accepts: [textFineTypes.motion], summary: "Chooses the Motion; an omitted Motion is still." },
+ { name: "content", kind: "reference", required: false, accepts: [textTypes.text], summary: "Reads ordinary graph Text as one plain run; otherwise the element owns its inline document." },
+ ...fineTextWindowAttributeVocabulary,
+] as const;
+
+const fineTextPorts = [
+ { name: "occurrence", type: textFineTypes.occurrence, summary: "The package-owned compiled occurrence used by Studio and sibling text tools." },
+ { name: "visual", type: compositionTypes.visualTrack, summary: "The occurrence rendered immediately as one ordinary peer VisualTrack." },
+] as const;
+
+export const textFineMarkupSurfaces = [
+ { name: "style", tag: "Style", mode: "structured", outputs: [textFineTypes.style],
vocabulary: {
- summary: "One named TextStyle: the typography and layout properties of an SVS Recipe, the exact font bytes text is shaped with, and the ordered Paint the glyphs are drawn in.",
+ summary: "One named bound TextStyle: reusable typography and ordered Paint, with exact font bytes. Placement, layout and stacking belong to each occurrence.",
attributes: [
{ name: "id", kind: "identifier", required: true,
- summary: "Names this Style, under which items and Spans reference it." },
+ summary: "Names this Style, under which occurrences and Spans reference it." },
{ name: "recipe", kind: "reference", required: true, accepts: [svsRecipeType],
- summary: "Chooses the Recipe that states the typography, area, point and path properties of this Style.",
+ summary: "Chooses the Recipe that states reusable typography and Paint properties of this Style.",
recipe: [
- { name: "stack-order", required: true,
- summary: "Fixes where the text drawn in this Style sits in the Track's paint order." },
{ name: "size", required: true,
summary: "Sets the type size in pixels, which must be positive." },
{ name: "weight", required: false, fallback: "400",
@@ -229,50 +243,6 @@ export const typographyTrackMarkupSurfaces = [
summary: "Decides which CJK punctuation is trimmed at the line edges, written as `none`, `start`, `end`, `adjacent` or `all`." },
{ name: "fill", required: false,
summary: "Paints one solid glyph fill in this color, ahead of the Paint children." },
- { name: "inline-size", required: false, fallback: "fixed", values: ["hug", "fixed"],
- summary: "Decides whether the text box hugs its content along the inline axis or fills its placement." },
- { name: "block-size", required: false, fallback: "fixed", values: ["hug", "fixed"],
- summary: "Decides whether the text box hugs its content along the block axis or fills its placement." },
- { name: "padding", required: false, fallback: "0",
- summary: "Insets the text from its placement edges, as one, two or four non-negative pixel values written top, right, bottom, left." },
- { name: "align", required: false, fallback: "center", values: ["start", "center", "end", "justify"],
- summary: "Aligns the text along the inline axis." },
- { name: "block-align", required: false, fallback: "center", values: ["start", "center", "end"],
- summary: "Aligns the text along the block axis." },
- { name: "wrap", required: false, fallback: "word", values: ["none", "word", "grapheme"],
- summary: "Decides where a line may break." },
- { name: "overflow", required: false, fallback: "visible", values: ["visible", "clip", "ellipsis", "shrink"],
- summary: "Decides what becomes of text that does not fit its placement." },
- { name: "max-lines", required: false,
- summary: "Caps the number of lines the text occupies, which only an `ellipsis` or `shrink` overflow accepts." },
- { name: "minimum-scale", required: false,
- summary: "Sets the smallest fraction of the type size a `shrink` overflow may reduce the text to, which that overflow requires and no other accepts." },
- { name: "clip", required: false, fallback: "false", values: ["true", "false"],
- summary: "Decides whether the text is clipped to its placement." },
- { name: "columns", required: false, fallback: "1",
- summary: "Divides the text box into this many columns." },
- { name: "column-gap", required: false, fallback: "0",
- summary: "Separates the columns by this many pixels." },
- { name: "metric-edge", required: false, fallback: "line-box", values: ["line-box", "cap-height", "ink"],
- summary: "Chooses which typographic edge the text is measured and aligned by." },
- { name: "point-anchor-inline", required: false, fallback: "center", values: ["start", "center", "end"],
- summary: "Anchors Point text along the inline axis of its Point." },
- { name: "point-anchor-block", required: false, fallback: "center", values: ["start", "center", "end"],
- summary: "Anchors Point text along the block axis of its Point." },
- { name: "path-side", required: false, fallback: "left", values: ["left", "right"],
- summary: "Chooses which side of the Path the glyphs sit on." },
- { name: "path-orientation", required: false, fallback: "follow", values: ["follow", "upright"],
- summary: "Decides whether the glyphs turn with the Path or stay upright." },
- { name: "path-start-margin", required: false, fallback: "0",
- summary: "Starts the text this many pixels along the Path, which must not be negative." },
- { name: "path-end-margin", required: false, fallback: "0",
- summary: "Ends the text this many pixels before the Path does, which must not be negative." },
- { name: "path-align", required: false, fallback: "start", values: ["start", "center", "end"],
- summary: "Aligns the text within the Path between its margins." },
- { name: "path-reverse", required: false, fallback: "false", values: ["true", "false"],
- summary: "Sets the text along the Path in the opposite direction." },
- { name: "path-overflow", required: false, fallback: "visible", values: ["visible", "clip"],
- summary: "Decides whether text longer than the Path is drawn or clipped." },
] },
{ name: "font", kind: "reference", required: true, accepts: [mediaTypes.fontArtifact, mediaTypes.fontStack],
summary: "Chooses the exact font bytes text is shaped with, either one face or one ordered stack of faces." },
@@ -358,27 +328,27 @@ export const typographyTrackMarkupSurfaces = [
],
},
},
- { name: "motion", tag: "Motion", mode: "structured", outputs: [typographyTrackTypes.motion],
+ { name: "motion", tag: "Motion", mode: "structured", outputs: [textFineTypes.motion],
vocabulary: {
- summary: "One named TextMotion: the keyframes an item plays as a whole, the Sequences that animate its document units, and the Path start margin over time.",
+ summary: "One named TextMotion shared by Flow, Point and Path: whole-occurrence keyframes and Sequences over document units.",
attributes: [
{ name: "id", kind: "identifier", required: true,
- summary: "Names this Motion, under which items reference it." },
+ summary: "Names this Motion, under which occurrences reference it." },
],
children: [
{ tag: "ItemKeyframe", cardinality: "many",
- summary: "Fixes the transform, opacity, blur, color or clip of the whole item at one frame.",
+ summary: "Fixes the transform, opacity, blur, color or clip of the whole occurrence at one frame.",
attributes: [
- { name: "at", kind: "literal", required: true, summary: "Lands this keyframe on an exact frame of the item's window." },
+ { name: "at", kind: "literal", required: true, summary: "Lands this keyframe on an exact frame of the occurrence's window." },
{ name: "easing", kind: "literal", required: false, summary: "Decides how the value travels into this keyframe." },
- { name: "x", kind: "literal", required: false, summary: "Translates the item horizontally, in pixels." },
- { name: "y", kind: "literal", required: false, summary: "Translates the item vertically, in pixels." },
- { name: "scale", kind: "literal", required: false, summary: "Scales the item uniformly; defaults to `1`." },
- { name: "rotate", kind: "literal", required: false, summary: "Rotates the item, in degrees." },
- { name: "skew-x", kind: "literal", required: false, summary: "Skews the item horizontally, in degrees." },
- { name: "skew-y", kind: "literal", required: false, summary: "Skews the item vertically, in degrees." },
- { name: "opacity", kind: "literal", required: false, summary: "Sets the item's opacity at this keyframe." },
- { name: "blur", kind: "literal", required: false, summary: "Blurs the item by this radius in pixels." },
+ { name: "x", kind: "literal", required: false, summary: "Translates the occurrence horizontally, in pixels." },
+ { name: "y", kind: "literal", required: false, summary: "Translates the occurrence vertically, in pixels." },
+ { name: "scale", kind: "literal", required: false, summary: "Scales the occurrence uniformly; defaults to `1`." },
+ { name: "rotate", kind: "literal", required: false, summary: "Rotates the occurrence, in degrees." },
+ { name: "skew-x", kind: "literal", required: false, summary: "Skews the occurrence horizontally, in degrees." },
+ { name: "skew-y", kind: "literal", required: false, summary: "Skews the occurrence vertically, in degrees." },
+ { name: "opacity", kind: "literal", required: false, summary: "Sets the occurrence's opacity at this keyframe." },
+ { name: "blur", kind: "literal", required: false, summary: "Blurs the occurrence by this radius in pixels." },
{ name: "color", kind: "literal", required: false, summary: "Sets the glyph color at this keyframe." },
{ name: "clip-top", kind: "literal", required: false, summary: "Insets the top edge of the reveal rectangle, as a percentage." },
{ name: "clip-right", kind: "literal", required: false, summary: "Insets the right edge of the reveal rectangle, as a percentage." },
@@ -399,13 +369,6 @@ export const typographyTrackMarkupSurfaces = [
{ name: "cycles", kind: "literal", required: false, summary: "Repeats one unit's animation this many times; defaults to `1`." },
{ name: "seed", kind: "literal", required: false, summary: "Fixes the draw a `random` order makes." },
] },
- { tag: "PathKeyframe", cardinality: "many",
- summary: "Fixes the start margin of Path text at one frame, moving the text along its Path.",
- attributes: [
- { name: "at", kind: "literal", required: true, summary: "Lands this keyframe on an exact frame of the item's window." },
- { name: "margin", kind: "literal", required: true, summary: "Sets how far along the Path the text begins, in pixels." },
- { name: "easing", kind: "literal", required: false, values: ["linear", "ease-in", "ease-out", "ease-in-out"], summary: "Decides how the margin travels into this keyframe." },
- ] },
],
example: `<text:Motion id="arrive">
<text:ItemKeyframe at="0" y="24" opacity="0"/>
@@ -417,142 +380,156 @@ export const typographyTrackMarkupSurfaces = [
</text:Motion>`,
notes: [
"An `<ItemKeyframe>` is written empty, and it and a `<Keyframe>` alike must animate at least one of `x`, `y`, `scale`, `rotate`, `skew-x`, `skew-y`, `opacity`, `blur`, `color` or a `clip-` inset.",
- "An item animation and a Path margin animation each need at least two keyframes.",
+ "A whole-occurrence animation needs at least two keyframes.",
"A `<Sequence>` accepts only `<Keyframe>` children and carries at least two of them; a `<Keyframe>` takes the same attributes as an `<ItemKeyframe>`, with `at` read as the progress from 0 to 1 through one unit.",
"The TextMotion Record is published under the bare `id`, and the element carries no text content.",
],
},
},
- { name: "track", tag: "Track", mode: "structured", outputs: [typographyTrackTypes.header, typographyTrackTypes.itemSpec, typographyTrackTypes.plainItemSpec, typographyTrackTypes.motion, typographyTrackTypes.set, typographyTrackTypes.placement, temporalTypes.instantSpec, temporalTypes.windowSpec, temporalTypes.instant, temporalTypes.window, typographyTrackTypes.program, compositionTypes.visualTrack],
+ { name: "path-motion", tag: "PathMotion", mode: "structured", outputs: [textFineTypes.pathMotion],
vocabulary: {
- summary: "One Typography Track: independently placed and timed text items on a shared Timeline, lowered to one addressable TypographyTrackProgram and one peer VisualTrack.",
- appearance: "Text alone on an otherwise empty Canvas: the glyphs, plus whatever Paint the Style puts around them — fills, outlines, glows, shadows and rounded, bordered, optionally tailed boxes drawn behind the frame, paragraph, line, run, word or grapheme. Each item holds its own region of the Canvas: a Point item is one unwrapped block that hugs its text and hangs off a single coordinate by its inline and block anchors, an Area item flows and wraps inside a rectangle under its own alignment, columns, clipping and overflow, and a Path item strings the glyphs along a curve, on one side of it, turning with it or standing upright. Items switch on and off at their own frame windows and overlap in the stacking order their Styles declare, so titles, labels and captions can occupy different corners at once and outlast or outlive one another. While an item is on screen it plays its Motion: the whole block translating, scaling, rotating, skewing, fading, blurring, recoloring or wiping open from an edge, and its paragraphs, lines, runs, words or graphemes arriving one behind another in a staggered run.",
- preview: previewImage("Track.png"),
+ summary: "One Path-specific margin relation; it moves Path text along its own geometry without entering general TextMotion.",
+ attributes: [{ name: "id", kind: "identifier", required: true, summary: "Names this PathMotion." }],
+ children: [{ tag: "Keyframe", cardinality: "many", summary: "Fixes the Path start margin at one occurrence-local frame.", attributes: [
+ { name: "at", kind: "literal", required: true, summary: "Lands this keyframe on an exact frame of the occurrence's Window." },
+ { name: "margin", kind: "literal", required: true, summary: "Sets the Path start margin in pixels." },
+ { name: "easing", kind: "literal", required: false, values: ["linear", "ease-in", "ease-out", "ease-in-out"], summary: "Decides how the margin travels into this keyframe." },
+ ] }],
+ example: `<text:PathMotion id="orbit-travel">
+ <text:Keyframe at="0" margin="0"/>
+ <text:Keyframe at="90" margin="120" easing="ease-in-out"/>
+</text:PathMotion>`,
+ notes: ["A PathMotion needs at least two ordered Keyframes and is accepted only by a Path occurrence."],
+ },
+ },
+ { name: "flow", tag: "Flow", mode: "structured", outputs: [textFineTypes.itemSpec, textFineTypes.plainItemSpec, textFineTypes.motion, textFineTypes.flowPlacementPolicy, textFineTypes.placement, temporalTypes.duration, temporalTypes.extent, temporalTypes.shiftSpec, temporalTypes.instantSpec, temporalTypes.windowSpec, temporalTypes.instant, temporalTypes.window, textFineTypes.occurrence, compositionTypes.visualTrack],
+ vocabulary: {
+ summary: "One independently timed fine-text occurrence flowing inside a SpatialFrame; no aggregate Text Track is created.",
attributes: [
- { name: "id", kind: "identifier", required: true,
- summary: "Names this Track and prefixes the identity of every item spec it seals." },
- ...temporalContextAttributeVocabulary,
+ ...fineTextCommonAttributes,
+ { name: "within", kind: "reference", required: true, accepts: [spatialTypes.frame], summary: "The Frame inside which this document flows and wraps." },
+ { name: "inline-size", kind: "literal", required: false, values: ["hug", "fixed"], summary: "Whether the text box hugs content or fills the Frame inline; defaults to fixed." },
+ { name: "block-size", kind: "literal", required: false, values: ["hug", "fixed"], summary: "Whether the text box hugs content or fills the Frame in the block direction; defaults to fixed." },
+ { name: "padding", kind: "literal", required: false, summary: "Insets text from the Frame as one, two or four pixel values; defaults to zero." },
+ { name: "align", kind: "literal", required: false, values: ["start", "center", "end", "justify"], summary: "Aligns text inline; defaults to center." },
+ { name: "block-align", kind: "literal", required: false, values: ["start", "center", "end"], summary: "Aligns text on the block axis; defaults to center." },
+ { name: "wrap", kind: "literal", required: false, values: ["none", "word", "grapheme"], summary: "Chooses line-breaking policy; defaults to word." },
+ { name: "overflow", kind: "literal", required: false, values: ["visible", "clip", "ellipsis", "shrink"], summary: "Chooses Flow overflow; defaults to visible." },
+ { name: "max-lines", kind: "literal", required: false, summary: "Caps lines for ellipsis or shrink overflow." },
+ { name: "minimum-scale", kind: "literal", required: false, summary: "Sets the minimum scale required by shrink overflow." },
+ { name: "clip", kind: "literal", required: false, values: ["true", "false"], summary: "Clips the Flow to its Frame; defaults to false." },
+ { name: "columns", kind: "literal", required: false, summary: "Sets a positive column count; defaults to one." },
+ { name: "column-gap", kind: "literal", required: false, summary: "Sets the non-negative gap between columns; defaults to zero." },
+ { name: "metric-edge", kind: "literal", required: false, values: ["line-box", "cap-height", "ink"], summary: "Chooses the typographic edge used for alignment; defaults to line-box." },
],
- children: [
- { tag: "Point", cardinality: "many",
- summary: "One text item anchored at a SpatialPoint. It owns its own document, written as direct text or as P children.",
- attributes: [
- { name: "id", kind: "identifier", required: true, summary: "Names this item and the spec the Track seals for it." },
- { name: "placement", kind: "reference", required: true, accepts: [spatialTypes.point], summary: "Anchors the item at this Point." },
- { name: "style", kind: "reference", required: true, accepts: [typographyTrackTypes.style], summary: "Chooses the compiled Style the item is drawn in." },
- { name: "motion", kind: "reference", required: false, accepts: [typographyTrackTypes.motion], summary: "Chooses the Motion the item plays; the Track supplies a still Motion otherwise." },
- { name: "content", kind: "reference", required: false, accepts: [textTypes.text], summary: "Reads an ordinary graph Text as one plain run, which requires the item to be written empty." },
- ...temporalWindowAttributeVocabulary,
- ],
- children: documentChildren,
- text: "Direct text is the item's whole document, read as one paragraph." },
- { tag: "Area", cardinality: "many",
- summary: "One text item flowed inside a SpatialFrame. It owns its own document, written as direct text or as P children.",
- attributes: [
- { name: "id", kind: "identifier", required: true, summary: "Names this item and the spec the Track seals for it." },
- { name: "placement", kind: "reference", required: true, accepts: [spatialTypes.frame], summary: "Flows the item inside this Frame." },
- { name: "style", kind: "reference", required: true, accepts: [typographyTrackTypes.style], summary: "Chooses the compiled Style the item is drawn in." },
- { name: "motion", kind: "reference", required: false, accepts: [typographyTrackTypes.motion], summary: "Chooses the Motion the item plays; the Track supplies a still Motion otherwise." },
- { name: "content", kind: "reference", required: false, accepts: [textTypes.text], summary: "Reads an ordinary graph Text as one plain run, which requires the item to be written empty." },
- ...temporalWindowAttributeVocabulary,
- ],
- children: documentChildren,
- text: "Direct text is the item's whole document, read as one paragraph." },
- { tag: "Path", cardinality: "many",
- summary: "One text item set along a SpatialPath. It owns its own document, written as direct text or as P children.",
- attributes: [
- { name: "id", kind: "identifier", required: true, summary: "Names this item and the spec the Track seals for it." },
- { name: "placement", kind: "reference", required: true, accepts: [spatialTypes.path], summary: "Sets the item along this Path." },
- { name: "style", kind: "reference", required: true, accepts: [typographyTrackTypes.style], summary: "Chooses the compiled Style the item is drawn in." },
- { name: "motion", kind: "reference", required: false, accepts: [typographyTrackTypes.motion], summary: "Chooses the Motion the item plays; the Track supplies a still Motion otherwise." },
- { name: "content", kind: "reference", required: false, accepts: [textTypes.text], summary: "Reads an ordinary graph Text as one plain run, which requires the item to be written empty." },
- ...temporalWindowAttributeVocabulary,
- ],
- children: documentChildren,
- text: "Direct text is the item's whole document, read as one paragraph." },
+ children: documentChildren,
+ text: "Direct text is the occurrence's whole document, read as one paragraph.",
+ ports: fineTextPorts,
+ example: `<text:Flow id="title" timeline={film.timeline} within={title-frame} style={title-style} z="40" align="center" block-align="center" during="timeline">EDIT MEANING</text:Flow>`,
+ notes: [
+ "This is one occurrence, not a container. Compose its `.visual` beside media, captions and other visual outputs.",
+ "Timing is absolute: use an existing Window with `during`, or author exactly two of `from`, `until` and `for`. A semantic package may project its own anchor into a Window first.",
],
- ports: [
- { name: "program", type: typographyTrackTypes.program,
- summary: "The sealed TypographyTrackProgram, which a Mask consumes." },
- { name: "track", type: compositionTypes.visualTrack,
- summary: "The rendered text, an ordinary peer VisualTrack." },
+ },
+ },
+ { name: "point", tag: "Point", mode: "structured", outputs: [textFineTypes.itemSpec, textFineTypes.plainItemSpec, textFineTypes.motion, textFineTypes.pointPlacementPolicy, textFineTypes.placement, temporalTypes.duration, temporalTypes.extent, temporalTypes.shiftSpec, temporalTypes.instantSpec, temporalTypes.windowSpec, temporalTypes.instant, temporalTypes.window, textFineTypes.occurrence, compositionTypes.visualTrack],
+ vocabulary: {
+ summary: "One independently timed fine-text occurrence anchored at a SpatialPoint; no aggregate Text Track is created.",
+ attributes: [
+ ...fineTextCommonAttributes,
+ { name: "point", kind: "reference", required: true, accepts: [spatialTypes.point], summary: "The Point from which the occurrence's anchors hang the text." },
+ { name: "anchor-inline", kind: "literal", required: false, values: ["start", "center", "end"], summary: "Anchors the text inline at the Point; defaults to center." },
+ { name: "anchor-block", kind: "literal", required: false, values: ["start", "center", "end"], summary: "Anchors the text on the block axis at the Point; defaults to center." },
],
- example: `<text:Track id="titles" timeline={speech.timeline}>
- <text:Area id="title" placement={title-frame} style={title-style} during="program">
- EDIT MEANING, NOT TIMELINES
- </text:Area>
- <text:Area id="standfirst" placement={standfirst-frame} style={body-style} during="program">
- <text:P>Edit meaning,<text:Break/>not <text:Span style={accent-serif}>timelines</text:Span>.</text:P>
- </text:Area>
-</text:Track>`,
- notes: [
- "A Track requires at least one `<Point>`, `<Area>` or `<Path>` and accepts no text content of its own.",
- "An item states exactly one window form: `during`, `at` with `for`, `until` with `for`, or `start` with `end`. Bind selection, segment and/or moment only when the start/end expressions use them; different endpoints can use different bindings.",
- "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.",
- "An item written without `content` owns its own document: direct text becomes one paragraph, and `<P>` children carry rich runs instead; a document mixes neither `<P>` children with direct text nor direct text with nested elements.",
- "Neither a `<P>` nor a `<Span>` may be empty, and a `style` on either must name a Style Record authored in this Source or imported from another, because its typography and Paint are copied into the document as the item is decoded.",
+ children: documentChildren,
+ text: "Direct text is the occurrence's whole document, read as one paragraph.",
+ ports: fineTextPorts,
+ example: `<text:Point id="label" timeline={film.timeline} point={label-point} style={label-style} z="40" anchor-inline="start" from="2s" for="90f">ORBIT</text:Point>`,
+ notes: ["This is one occurrence, not a container; semantic sources can supply a resolved Window without becoming part of this text surface."],
+ },
+ },
+ { name: "path", tag: "Path", mode: "structured", outputs: [textFineTypes.itemSpec, textFineTypes.plainItemSpec, textFineTypes.motion, textFineTypes.pathMotion, textFineTypes.pathPlacementPolicy, textFineTypes.placement, temporalTypes.duration, temporalTypes.extent, temporalTypes.shiftSpec, temporalTypes.instantSpec, temporalTypes.windowSpec, temporalTypes.instant, temporalTypes.window, textFineTypes.occurrence, compositionTypes.visualTrack],
+ vocabulary: {
+ summary: "One independently timed fine-text occurrence set along a SpatialPath; no aggregate Text Track is created.",
+ attributes: [
+ ...fineTextCommonAttributes,
+ { name: "path", kind: "reference", required: true, accepts: [spatialTypes.path], summary: "The Path along which the glyphs are set." },
+ { name: "side", kind: "literal", required: false, values: ["left", "right"], summary: "Chooses the side of the Path; defaults to left." },
+ { name: "orientation", kind: "literal", required: false, values: ["follow", "upright"], summary: "Chooses whether glyphs follow the Path or remain upright; defaults to follow." },
+ { name: "start-margin", kind: "literal", required: false, summary: "Starts text this many pixels along the Path; defaults to zero." },
+ { name: "end-margin", kind: "literal", required: false, summary: "Ends text this many pixels before the Path end; defaults to zero." },
+ { name: "align", kind: "literal", required: false, values: ["start", "center", "end"], summary: "Aligns text between Path margins; defaults to start." },
+ { name: "reverse", kind: "literal", required: false, values: ["true", "false"], summary: "Reverses Path direction; defaults to false." },
+ { name: "overflow", kind: "literal", required: false, values: ["visible", "clip"], summary: "Chooses whether text beyond the Path remains visible; defaults to visible." },
+ { name: "path-motion", kind: "reference", required: false, accepts: [textFineTypes.pathMotion], summary: "Moves the start margin along this Path; omitted means still." },
],
+ children: documentChildren,
+ text: "Direct text is the occurrence's whole document, read as one paragraph.",
+ ports: fineTextPorts,
+ example: `<text:Path id="orbit-copy" timeline={film.timeline} path={orbit} style={orbit-style} z="40" path-motion={orbit-travel} from="timeline.start + 1s" until="timeline.end">FOLLOW THE CURVE</text:Path>`,
+ notes: ["This is one occurrence, not a container; Path-specific layout and margin motion belong here, not to the reusable Style or general Motion."],
},
},
- { name: "mask", tag: "Mask", mode: "structured", outputs: [typographyTrackTypes.maskSpec, compositionTypes.visualTrack],
+ { name: "mask", tag: "Mask", mode: "structured", outputs: [textFineTypes.maskSpec, compositionTypes.visualTrack],
vocabulary: {
- summary: "Cuts one owned Surface to the shape of one authored TypographyTrackProgram and publishes the result as a peer VisualTrack.",
- appearance: "The words of the authored Text Program filled with a picture: each item's letterforms are cut out of the material Surface, and every pixel outside the glyphs is transparent. Only the glyph shapes carry across — the Style's own fills, outlines and boxes are not drawn — so what reads on screen is one horizontal line of type per item, set at the padding and inline and block alignment of its Frame, with the material scaled to contain, cover or fill that Frame behind it. Items appear and vanish on the same frames as the Text Program they take their shape from, and each plays that item's whole-item Motion, so the picture-filled type translates, scales, rotates, fades, blurs or wipes as one piece.",
+ summary: "Cuts one owned Surface to the shape of one fine-text occurrence and publishes the result as a peer VisualTrack.",
+ appearance: "The words of the authored occurrence filled with a picture: its letterforms are cut out of the material Surface, and every pixel outside the glyphs is transparent. Only the glyph shapes carry across — the Style's own fills, outlines and boxes are not drawn — so what reads on screen is one horizontal line of type set at the padding and inline and block alignment of its Frame, with the material scaled to contain, cover or fill that Frame behind it. It appears and vanishes with the occurrence and plays its whole-occurrence Motion.",
preview: previewImage("Mask.png"),
attributes: [
{ name: "id", kind: "identifier", required: true,
summary: "Names this Mask, under which its VisualTrack is published." },
- ...temporalContextAttributeVocabulary,
- { name: "text", kind: "reference", required: true, accepts: [typographyTrackTypes.program],
- summary: "Chooses the authored Text Program whose items give the mask its shape and timing." },
+ { name: "timeline", kind: "reference", required: true, accepts: [timelineTypes.track],
+ summary: "The absolute Timeline shared with the consumed occurrence." },
+ { name: "text", kind: "reference", required: true, accepts: [textFineTypes.occurrence],
+ summary: "Chooses the one authored fine-text occurrence that gives the mask its shape and timing." },
{ name: "material", kind: "reference", required: true, accepts: [mediaTypes.compositableSurface],
summary: "Chooses the Surface shown through the text." },
{ name: "mode", kind: "literal", required: false, values: ["alpha", "luminance"],
summary: "Whether the text masks by coverage or by brightness; defaults to `alpha`." },
{ name: "fit", kind: "literal", required: false, values: ["contain", "cover", "fill"],
- summary: "How the material occupies each masked item; defaults to `cover`." },
+ summary: "How the material occupies the masked occurrence; defaults to `cover`." },
],
ports: [
- { name: "track", type: compositionTypes.visualTrack,
+ { name: "visual", type: compositionTypes.visualTrack,
summary: "The masked picture, an ordinary peer VisualTrack." },
],
- example: `<text:Mask id="masked-titles" timeline={speech.timeline} text={mask-shape.program} material={material}/>`,
+ example: `<text:Mask id="masked-title" timeline={film.timeline} text={mask-shape.occurrence} material={material}/>`,
notes: [
"A Mask is written empty and accepts no children.",
"The material must be a still Surface; a timed material is refused and materializes through an independent package.",
- "Every item of the Text Program must be one Area holding one unstyled paragraph, without Sequence motion, and drawn in a Style that is fixed in both axes, unwrapped, single-column, horizontally written, undecorated, without `ellipsis` or `shrink` overflow, and whose weight and style match its primary exact font without synthesis; anything else is refused.",
+ "The occurrence must be one Flow holding one unstyled paragraph, without Sequence motion, and drawn in a Style that is fixed in both axes, unwrapped, single-column, horizontally written, undecorated, without `ellipsis` or `shrink` overflow, and whose weight and style match its primary exact font without synthesis; anything else is refused.",
],
},
},
] as const;
-export const typographyTrackManifest: ModuleManifest = {
+export const textFineManifest: ModuleManifest = {
format: "hypit.module@1",
- name: typographyTrackModuleRef.name,
- version: typographyTrackModuleRef.version,
- dependencies: [narrativeDependency, timelineDependency, spatialDependency, mediaDependency, compositionDependency, textDependency, temporalDependency],
+ name: textFineModuleRef.name,
+ version: textFineModuleRef.version,
+ dependencies: [timelineDependency, spatialDependency, mediaDependency, compositionDependency, textDependency, temporalDependency],
types: [
- { name: typographyTrackTypes.style.name },
- { name: typographyTrackTypes.motion.name },
- { name: typographyTrackTypes.placement.name },
- { name: typographyTrackTypes.program.name },
- { name: typographyTrackTypes.header.name },
- { name: typographyTrackTypes.itemSpec.name },
- { name: typographyTrackTypes.plainItemSpec.name },
- { name: typographyTrackTypes.set.name },
- { name: typographyTrackTypes.maskSpec.name },
+ { name: textFineTypes.style.name },
+ { name: textFineTypes.motion.name },
+ { name: textFineTypes.pathMotion.name },
+ { name: textFineTypes.flowPlacementPolicy.name },
+ { name: textFineTypes.pointPlacementPolicy.name },
+ { name: textFineTypes.pathPlacementPolicy.name },
+ { name: textFineTypes.placement.name },
+ { name: textFineTypes.occurrence.name },
+ { name: textFineTypes.itemSpec.name },
+ { name: textFineTypes.plainItemSpec.name },
+ { name: textFineTypes.maskSpec.name },
],
capabilities: [],
producers: [
- { name: typographyTrackProducers.materializePlainItem.name, inputs: [{ name: "spec", type: typographyTrackTypes.plainItemSpec }, { name: "content", type: textTypes.text }], outputs: [{ name: "spec", type: typographyTrackTypes.itemSpec }], needs: [] },
- { name: typographyTrackProducers.bindPoint.name, inputs: [{ name: "point", type: spatialTypes.point }], outputs: [{ name: "placement", type: typographyTrackTypes.placement }], needs: [] },
- { name: typographyTrackProducers.bindArea.name, inputs: [{ name: "frame", type: spatialTypes.frame }], outputs: [{ name: "placement", type: typographyTrackTypes.placement }], needs: [] },
- { name: typographyTrackProducers.bindPath.name, inputs: [{ name: "path", type: spatialTypes.path }], outputs: [{ name: "placement", type: typographyTrackTypes.placement }], needs: [] },
- { name: typographyTrackProducers.createSet.name, inputs: [], outputs: [{ name: "set", type: typographyTrackTypes.set }], needs: [] },
- { name: typographyTrackProducers.appendItem.name, inputs: [{ name: "set", type: typographyTrackTypes.set }, { name: "header", type: typographyTrackTypes.header }, { name: "timeline", type: timelineTypes.track }, { name: "placement", type: typographyTrackTypes.placement }, { name: "spec", type: typographyTrackTypes.itemSpec }, { name: "style", type: typographyTrackTypes.style }, { name: "motion", type: typographyTrackTypes.motion }, { name: "window", type: temporalTypes.window }], outputs: [{ name: "set", type: typographyTrackTypes.set }], needs: [] },
- { name: typographyTrackProducers.finalize.name, inputs: [{ name: "header", type: typographyTrackTypes.header }, { name: "set", type: typographyTrackTypes.set }], outputs: [{ name: "program", type: typographyTrackTypes.program }], needs: [] },
- { name: typographyTrackProducers.render.name, inputs: [{ name: "timeline", type: timelineTypes.track }, { name: "program", type: typographyTrackTypes.program }], outputs: [{ name: "track", type: compositionTypes.visualTrack }], needs: [] },
- { name: typographyTrackProducers.renderMask.name, inputs: [{ name: "timeline", type: timelineTypes.track }, { name: "program", type: typographyTrackTypes.program }, { name: "material", type: mediaTypes.compositableSurface }, { name: "spec", type: typographyTrackTypes.maskSpec }], outputs: [{ name: "track", type: compositionTypes.visualTrack }], needs: [] },
+ { name: textFineProducers.materializePlainItem.name, inputs: [{ name: "spec", type: textFineTypes.plainItemSpec }, { name: "content", type: textTypes.text }], outputs: [{ name: "spec", type: textFineTypes.itemSpec }], needs: [] },
+ { name: textFineProducers.bindPoint.name, inputs: [{ name: "point", type: spatialTypes.point }, { name: "policy", type: textFineTypes.pointPlacementPolicy }], outputs: [{ name: "placement", type: textFineTypes.placement }], needs: [] },
+ { name: textFineProducers.bindArea.name, inputs: [{ name: "frame", type: spatialTypes.frame }, { name: "policy", type: textFineTypes.flowPlacementPolicy }], outputs: [{ name: "placement", type: textFineTypes.placement }], needs: [] },
+ { name: textFineProducers.bindPath.name, inputs: [{ name: "path", type: spatialTypes.path }, { name: "policy", type: textFineTypes.pathPlacementPolicy }, { name: "marginMotion", type: textFineTypes.pathMotion }], outputs: [{ name: "placement", type: textFineTypes.placement }], needs: [] },
+ { name: textFineProducers.createOccurrence.name, inputs: [{ name: "timeline", type: timelineTypes.track }, { name: "placement", type: textFineTypes.placement }, { name: "spec", type: textFineTypes.itemSpec }, { name: "style", type: textFineTypes.style }, { name: "motion", type: textFineTypes.motion }, { name: "window", type: temporalTypes.window }], outputs: [{ name: "occurrence", type: textFineTypes.occurrence }], needs: [] },
+ { name: textFineProducers.renderOccurrence.name, inputs: [{ name: "timeline", type: timelineTypes.track }, { name: "occurrence", type: textFineTypes.occurrence }], outputs: [{ name: "visual", type: compositionTypes.visualTrack }], needs: [] },
+ { name: textFineProducers.renderOccurrenceMask.name, inputs: [{ name: "timeline", type: timelineTypes.track }, { name: "occurrence", type: textFineTypes.occurrence }, { name: "material", type: mediaTypes.compositableSurface }, { name: "spec", type: textFineTypes.maskSpec }], outputs: [{ name: "visual", type: compositionTypes.visualTrack }], needs: [] },
],
};
diff --git a/packages/typography-track/src/program.ts b/packages/text-fine/src/program.ts
similarity index 58%
rename from packages/typography-track/src/program.ts
rename to packages/text-fine/src/program.ts
index 1987dbcd..1570239a 100644
--- a/packages/typography-track/src/program.ts
+++ b/packages/text-fine/src/program.ts
@@ -1,13 +1,14 @@
+import { assertTimelineIdentity, timelineFrameCount } from "@hypit/timeline";
import type { Timeline } from "@hypit/timeline";
-import { assertProgramSpaceIdentity, programSpaceFrameCount } from "@hypit/program-space";
import {
assertSpatialFrame,
assertSpatialPath,
assertSpatialPoint,
+ resolveContentFit,
} from "@hypit/spatial";
import type { SpatialFrame, SpatialPath, SpatialPoint } from "@hypit/spatial";
import { assertTemporalWindowFor } from "@hypit/temporal";
-import type { ProjectedWindow } from "@hypit/temporal";
+import type { TemporalWindow } from "@hypit/temporal";
import {
assertVisualTrackIdentity,
sealVisualTrack,
@@ -27,17 +28,15 @@ import { verifyText } from "@hypit/text";
import type { Text } from "@hypit/text";
import type {
- TextGeometry,
+ FineTextOccurrence,
TextItem,
TextItemSpec,
PlainTextItemSpec,
TextMotion,
+ TextPathMotion,
TextMaskSpec,
TextPlacement,
TextStyle,
- TypographyTrackHeader,
- TypographyTrackProgram,
- TypographyTrackSet,
} from "./types.js";
function nonEmpty(value: string, label: string): void {
@@ -71,7 +70,6 @@ function assertDocument(document: TextItemSpec["document"], label: string): void
export function assertTextStyle(style: TextStyle): void {
nonEmpty(style.id, "TextStyle id");
- if (!Number.isSafeInteger(style.stackingOrder)) throw new Error("TextStyle stackingOrder must be a safe integer.");
finite(style.typography.sizePx, "TextStyle typography size");
if (style.typography.sizePx <= 0 || !Number.isSafeInteger(style.typography.weight)) {
throw new Error("TextStyle typography size or weight is invalid.");
@@ -79,35 +77,16 @@ export function assertTextStyle(style: TextStyle): void {
if (style.typography.fonts === undefined) {
throw new Error("Official TextStyle requires an exact declared font stack.");
}
- if (!["start", "center", "end"].includes(style.point.anchorInline)
- || !["start", "center", "end"].includes(style.point.anchorBlock)
- || !["left", "right"].includes(style.path.side)
- || !["follow", "upright"].includes(style.path.orientation)
- || !["start", "center", "end"].includes(style.path.align)
- || !["visible", "clip"].includes(style.path.overflow)) {
- throw new Error("TextStyle contains an unsupported Point or Path enum.");
- }
- if (style.area.overflow === "shrink") {
- if (style.area.minimumScale === undefined || style.area.minimumScale <= 0 || style.area.minimumScale > 1) {
- throw new Error("TextStyle shrink overflow requires minimumScale in (0, 1].");
- }
- } else if (style.area.minimumScale !== undefined) throw new Error("TextStyle minimumScale belongs only to shrink overflow.");
- if (style.area.maxLines !== undefined && style.area.overflow !== "ellipsis" && style.area.overflow !== "shrink") {
- throw new Error("TextStyle maxLines belongs only to ellipsis or shrink overflow.");
- }
- for (const value of [style.path.startMarginPx, style.path.endMarginPx]) {
- finite(value, "TextStyle path margin");
- if (value < 0) throw new Error("TextStyle path margins must not be negative.");
- }
assertVisualTrackIdentity({
kind: "visual",
- programSpaceId: "text-style-validation",
+ timelineId: "text-style-validation",
visualIr: "hypit.visual-ir@1",
id: "text-style-validation",
presents: [{
id: "style",
+ order: 0,
+ z: 0,
span: { startFrame: 0, endFrameExclusive: 1 },
- stacking: { order: style.stackingOrder, tieBreak: style.id },
elements: [
{ id: "root", kind: "box", order: 0, style: [] },
{
@@ -115,7 +94,12 @@ export function assertTextStyle(style: TextStyle): void {
document: { paragraphs: [{ id: "paragraph", inlines: [{ kind: "text", id: "run", text: "M" }] }] },
typography: style.typography,
paints: style.paints,
- flow: { ...style.area, form: { kind: "area" } },
+ flow: {
+ form: { kind: "area" }, inlineSize: "fixed", blockSize: "fixed",
+ paddingPx: { inlineStart: 0, inlineEnd: 0, blockStart: 0, blockEnd: 0 },
+ inlineAlign: "start", blockAlign: "start", wrap: "word", overflow: "visible",
+ clipToFrame: false, columns: 1, columnGapPx: 0, metricEdge: "line-box",
+ },
sequences: [],
},
],
@@ -137,20 +121,6 @@ export function assertTextMotion(motion: TextMotion): void {
if (ids.has(sequence.id)) throw new Error(`TextMotion repeats sequence ${sequence.id}.`);
ids.add(sequence.id);
}
- if (motion.pathMargin !== undefined) {
- if (motion.pathMargin.keyframes.length < 2) throw new Error("Path-margin motion requires two keyframes.");
- let previous = -1;
- for (const keyframe of motion.pathMargin.keyframes) {
- finite(keyframe.startMarginPx, "Path-margin start margin");
- if (!Number.isSafeInteger(keyframe.atFrame)
- || keyframe.atFrame <= previous
- || keyframe.startMarginPx < 0
- || (keyframe.easing !== undefined && !["linear", "ease-in", "ease-out", "ease-in-out"].includes(keyframe.easing))) {
- throw new Error("Path-margin motion keyframes are invalid.");
- }
- previous = keyframe.atFrame;
- }
- }
}
export function sealTextMotion(value: TextMotion): TextMotion {
@@ -165,6 +135,30 @@ export const stillTextMotion = (id = "still"): TextMotion => sealTextMotion({
sequences: [],
});
+export function assertTextPathMotion(motion: TextPathMotion): void {
+ nonEmpty(motion.id, "TextPathMotion id");
+ if (motion.keyframes.length === 1) throw new Error("TextPathMotion requires zero or at least two keyframes.");
+ let previous = -1;
+ for (const keyframe of motion.keyframes) {
+ finite(keyframe.startMarginPx, "TextPathMotion start margin");
+ if (!Number.isSafeInteger(keyframe.atFrame)
+ || keyframe.atFrame <= previous
+ || keyframe.startMarginPx < 0
+ || (keyframe.easing !== undefined && !["linear", "ease-in", "ease-out", "ease-in-out"].includes(keyframe.easing))) {
+ throw new Error("TextPathMotion keyframes are invalid.");
+ }
+ previous = keyframe.atFrame;
+ }
+}
+
+export function sealTextPathMotion(value: TextPathMotion): TextPathMotion {
+ const result = canonicalize(value) as unknown as TextPathMotion;
+ assertTextPathMotion(result);
+ return result;
+}
+
+export const stillTextPathMotion = (id = "still-path"): TextPathMotion => sealTextPathMotion({ id, keyframes: [] });
+
export function assertTextItemSpec(value: TextItemSpec): void {
nonEmpty(value.id, "TextItemSpec id");
assertDocument(value.document, `${value.id} document`);
@@ -202,25 +196,57 @@ export function materializePlainTextItem(spec: PlainTextItemSpec, content: Text)
});
}
-export function assertTypographyTrackHeader(value: TypographyTrackHeader): void {
- nonEmpty(value.id, "TypographyTrackHeader id");
-}
-
-export function sealTypographyTrackHeader(value: TypographyTrackHeader): TypographyTrackHeader {
- const result = canonicalize(value) as unknown as TypographyTrackHeader;
- assertTypographyTrackHeader(result);
- return result;
-}
-
-function assertGeometry(geometry: TextGeometry): void {
- if (geometry.kind === "point") assertSpatialPoint(geometry.point);
- else if (geometry.kind === "area") assertSpatialFrame(geometry.frame);
- else if (geometry.kind === "path") assertSpatialPath(geometry.path);
- else throw new Error("Text geometry is unsupported.");
-}
-
export function assertTextPlacement(value: TextPlacement): void {
- assertGeometry(value.geometry);
+ if (!Number.isSafeInteger(value.z)) throw new Error("Text placement z must be a safe integer.");
+ if (value.kind === "flow") {
+ assertSpatialFrame(value.frame);
+ const flow = value.flow;
+ if (!["hug", "fixed"].includes(flow.inlineSize) || !["hug", "fixed"].includes(flow.blockSize)
+ || !["start", "center", "end", "justify"].includes(flow.inlineAlign)
+ || !["start", "center", "end"].includes(flow.blockAlign)
+ || !["none", "word", "grapheme"].includes(flow.wrap)
+ || !["visible", "clip", "ellipsis", "shrink"].includes(flow.overflow)
+ || !["line-box", "cap-height", "ink"].includes(flow.metricEdge)
+ || !Number.isSafeInteger(flow.columns) || flow.columns < 1) {
+ throw new Error("Flow text placement contains an unsupported layout value.");
+ }
+ for (const amount of [...Object.values(flow.paddingPx), flow.columnGapPx]) {
+ finite(amount, "Flow text placement length");
+ if (amount < 0) throw new Error("Flow text placement lengths must not be negative.");
+ }
+ if (flow.overflow === "shrink") {
+ if (flow.minimumScale === undefined || flow.minimumScale <= 0 || flow.minimumScale > 1) {
+ throw new Error("Flow shrink overflow requires minimumScale in (0, 1].");
+ }
+ } else if (flow.minimumScale !== undefined) throw new Error("Flow minimumScale belongs only to shrink overflow.");
+ if (flow.maxLines !== undefined && (flow.maxLines < 1 || !Number.isSafeInteger(flow.maxLines)
+ || (flow.overflow !== "ellipsis" && flow.overflow !== "shrink"))) {
+ throw new Error("Flow maxLines belongs only to ellipsis or shrink overflow.");
+ }
+ return;
+ }
+ if (value.kind === "point") {
+ assertSpatialPoint(value.point);
+ if (!["start", "center", "end"].includes(value.anchorInline)
+ || !["start", "center", "end"].includes(value.anchorBlock)) {
+ throw new Error("Point text placement contains an unsupported anchor.");
+ }
+ return;
+ }
+ if (value.kind === "path") {
+ assertSpatialPath(value.path);
+ if (!["left", "right"].includes(value.side) || !["follow", "upright"].includes(value.orientation)
+ || !["start", "center", "end"].includes(value.align) || !["visible", "clip"].includes(value.overflow)) {
+ throw new Error("Path text placement contains an unsupported layout value.");
+ }
+ for (const amount of [value.startMarginPx, value.endMarginPx]) {
+ finite(amount, "Path text placement margin");
+ if (amount < 0) throw new Error("Path text placement margins must not be negative.");
+ }
+ if (value.marginMotion !== undefined) assertTextPathMotion(value.marginMotion);
+ return;
+ }
+ throw new Error("Text placement kind is unsupported.");
}
export function sealTextPlacement(value: TextPlacement): TextPlacement {
@@ -229,127 +255,86 @@ export function sealTextPlacement(value: TextPlacement): TextPlacement {
return result;
}
-export function bindPointTextPlacement(point: SpatialPoint): TextPlacement {
- assertSpatialPoint(point);
- return sealTextPlacement({ geometry: { kind: "point", point } });
-}
-
-export function bindAreaTextPlacement(frame: SpatialFrame): TextPlacement {
- assertSpatialFrame(frame);
- return sealTextPlacement({ geometry: { kind: "area", frame } });
+export function bindPointTextPlacement(
+ point: SpatialPoint,
+ policy: Omit<Extract<TextPlacement, { readonly kind: "point" }>, "kind" | "point">,
+): TextPlacement {
+ return sealTextPlacement({ kind: "point", point, ...policy });
}
-export function bindPathTextPlacement(path: SpatialPath): TextPlacement {
- assertSpatialPath(path);
- return sealTextPlacement({ geometry: { kind: "path", path } });
-}
-
-export function assertTypographyTrackSet(value: TypographyTrackSet): void {
- const ids = new Set<string>();
- for (const item of value.items) {
- if (ids.has(item.id)) throw new Error(`TypographyTrackSet repeats ${item.id}.`);
- ids.add(item.id);
- assertGeometry(item.geometry);
- assertDocument(item.document, `${item.id} document`);
- assertTextStyle(item.style);
- assertTextMotion(item.motion);
- }
+export function bindAreaTextPlacement(
+ frame: SpatialFrame,
+ policy: Omit<Extract<TextPlacement, { readonly kind: "flow" }>, "kind" | "frame">,
+): TextPlacement {
+ return sealTextPlacement({ kind: "flow", frame, ...policy });
}
-export function createTypographyTrackSet(): TypographyTrackSet {
- return { items: [] };
+export function bindPathTextPlacement(
+ path: SpatialPath,
+ policy: Omit<Extract<TextPlacement, { readonly kind: "path" }>, "kind" | "path" | "marginMotion">,
+ marginMotion: TextPathMotion,
+): TextPlacement {
+ assertTextPathMotion(marginMotion);
+ return sealTextPlacement({ kind: "path", path, ...policy, ...(marginMotion.keyframes.length === 0 ? {} : { marginMotion }) });
}
function projectedItem(
- header: TypographyTrackHeader,
spec: TextItemSpec,
style: TextStyle,
motion: TextMotion,
- geometry: TextGeometry,
- window: ProjectedWindow,
+ placement: TextPlacement,
+ window: TemporalWindow,
): TextItem {
return {
id: spec.id,
span: { ...window.span },
- geometry: structuredClone(geometry),
+ placement: structuredClone(placement),
document: structuredClone(spec.document),
style: structuredClone(style),
motion: structuredClone(motion),
- tieBreak: `${header.id}:${spec.id}`,
};
}
-function append(
- set: TypographyTrackSet,
- header: TypographyTrackHeader,
- spec: TextItemSpec,
- style: TextStyle,
- motion: TextMotion,
- geometry: TextGeometry,
- window: ProjectedWindow,
-): TypographyTrackSet {
- assertTypographyTrackSet(set);
- assertTypographyTrackHeader(header);
- assertTextItemSpec(spec);
- assertTextStyle(style);
- assertTextMotion(motion);
- assertGeometry(geometry);
- const existing = new Set(set.items.map((item) => item.id));
- const addition = projectedItem(header, spec, style, motion, geometry, window);
- if (existing.has(addition.id)) throw new Error(`TypographyTrackSet already contains ${spec.id}.`);
- return { items: [...set.items, addition] };
+function assertTextItemWithinTimeline(item: TextItem, timeline: Timeline): void {
+ const total = timelineFrameCount(timeline);
+ nonEmpty(item.id, "Text Item id");
+ if (item.span.startFrame < 0 || item.span.endFrameExclusive <= item.span.startFrame || item.span.endFrameExclusive > total) {
+ throw new Error(`${item.id} is outside Timeline.`);
+ }
+ assertTextPlacement(item.placement);
+ assertDocument(item.document, `${item.id} document`);
+ assertTextStyle(item.style);
+ assertTextMotion(item.motion);
}
-/** Component entry point: timing is supplied as a resolved TemporalWindow. */
-export function appendProjectedTextItem(
- set: TypographyTrackSet,
- header: TypographyTrackHeader,
+export function createFineTextOccurrence(
timeline: Timeline,
placement: TextPlacement,
spec: TextItemSpec,
style: TextStyle,
motion: TextMotion,
- window: ProjectedWindow,
-): TypographyTrackSet {
+ window: TemporalWindow,
+): FineTextOccurrence {
+ assertTimelineIdentity(timeline);
assertTextPlacement(placement);
- assertTemporalWindowFor(window, { subjectId: spec.id, space: timeline });
- return append(set, header, spec, style, motion, placement.geometry, window);
-}
-
-function programContent(value: TypographyTrackProgram): TypographyTrackProgram {
- return {
-
- id: value.id,
- items: [...value.items].map((item) => structuredClone(item)).sort((left, right) =>
- left.span.startFrame - right.span.startFrame
- || left.style.stackingOrder - right.style.stackingOrder
- || left.tieBreak.localeCompare(right.tieBreak)
- || left.id.localeCompare(right.id)),
- };
-}
-
-export function sealTypographyTrackProgram(value: TypographyTrackProgram): TypographyTrackProgram {
- return programContent(value);
-}
-
-export function assertTypographyTrackProgramIdentity(program: TypographyTrackProgram, timeline: Timeline): void {
- assertProgramSpaceIdentity(timeline);
- nonEmpty(program.id, "TypographyTrackProgram id");
- if (program.items.length === 0) throw new Error("TypographyTrackProgram has no Items.");
- const total = programSpaceFrameCount(timeline);
- const ids = new Set<string>();
- for (const item of program.items) {
- nonEmpty(item.id, "Text Item id");
- if (ids.has(item.id)) throw new Error(`TypographyTrackProgram repeats ${item.id}.`);
- ids.add(item.id);
- if (item.span.startFrame < 0 || item.span.endFrameExclusive <= item.span.startFrame || item.span.endFrameExclusive > total) {
- throw new Error(`${item.id} is outside Timeline.`);
- }
- assertGeometry(item.geometry);
- assertDocument(item.document, `${item.id} document`);
- assertTextStyle(item.style);
- assertTextMotion(item.motion);
+ assertTextItemSpec(spec);
+ assertTextStyle(style);
+ assertTextMotion(motion);
+ assertTemporalWindowFor(window, { subjectId: spec.id, timeline });
+ const occurrence = canonicalize({
+ timelineId: timeline.id,
+ ...projectedItem(spec, style, motion, placement, window),
+ }) as unknown as FineTextOccurrence;
+ assertFineTextOccurrenceIdentity(occurrence, timeline);
+ return occurrence;
+}
+
+export function assertFineTextOccurrenceIdentity(occurrence: FineTextOccurrence, timeline: Timeline): void {
+ assertTimelineIdentity(timeline);
+ if (occurrence.timelineId !== timeline.id) {
+ throw new Error(`FineTextOccurrence ${occurrence.id} belongs to ${occurrence.timelineId}, not ${timeline.id}.`);
}
+ assertTextItemWithinTimeline(occurrence, timeline);
}
export function assertTextMaskSpec(spec: TextMaskSpec): void {
@@ -364,25 +349,18 @@ export function sealTextMaskSpec(value: TextMaskSpec): TextMaskSpec {
return result;
}
-export function finalizeTypographyTrack(header: TypographyTrackHeader, set: TypographyTrackSet): TypographyTrackProgram {
- assertTypographyTrackHeader(header);
- assertTypographyTrackSet(set);
- if (set.items.length === 0) throw new Error("TypographyTrack requires at least one Item.");
- return sealTypographyTrackProgram({ id: header.id, items: set.items });
-}
-
-function baseBoxStyle(geometry: TextGeometry): VisualStyleDeclaration[] {
- if (geometry.kind === "area") return [
+function baseBoxStyle(placement: TextPlacement): VisualStyleDeclaration[] {
+ if (placement.kind === "flow") return [
{ name: "position", value: "absolute" },
- { name: "left", value: `${geometry.frame.xPx}px` },
- { name: "top", value: `${geometry.frame.yPx}px` },
- { name: "width", value: `${geometry.frame.widthPx}px` },
- { name: "height", value: `${geometry.frame.heightPx}px` },
+ { name: "left", value: `${placement.frame.xPx}px` },
+ { name: "top", value: `${placement.frame.yPx}px` },
+ { name: "width", value: `${placement.frame.widthPx}px` },
+ { name: "height", value: `${placement.frame.heightPx}px` },
];
- if (geometry.kind === "point") return [
+ if (placement.kind === "point") return [
{ name: "position", value: "absolute" },
- { name: "left", value: `${geometry.point.xPx}px` },
- { name: "top", value: `${geometry.point.yPx}px` },
+ { name: "left", value: `${placement.point.xPx}px` },
+ { name: "top", value: `${placement.point.yPx}px` },
{ name: "width", value: "max-content" },
{ name: "height", value: "max-content" },
];
@@ -390,9 +368,9 @@ function baseBoxStyle(geometry: TextGeometry): VisualStyleDeclaration[] {
}
function pointAnchorTransform(item: TextItem): string | undefined {
- if (item.geometry.kind !== "point") return undefined;
- const inline = item.style.point.anchorInline === "start" ? 0 : item.style.point.anchorInline === "center" ? -50 : -100;
- const block = item.style.point.anchorBlock === "start" ? 0 : item.style.point.anchorBlock === "center" ? -50 : -100;
+ if (item.placement.kind !== "point") return undefined;
+ const inline = item.placement.anchorInline === "start" ? 0 : item.placement.anchorInline === "center" ? -50 : -100;
+ const block = item.placement.anchorBlock === "start" ? 0 : item.placement.anchorBlock === "center" ? -50 : -100;
return `translate(${inline}%,${block}%)`;
}
@@ -406,10 +384,13 @@ function pathCommands(path: SpatialPath): VisualPathTextElement["path"] {
}
function pointFlow(item: TextItem): VisualTextFlowElement["flow"] {
- const { maxLines: _maxLines, minimumScale: _minimumScale, ...area } = item.style.area;
return {
- ...area,
- form: { kind: "point", ...item.style.point },
+ paddingPx: { inlineStart: 0, inlineEnd: 0, blockStart: 0, blockEnd: 0 },
+ inlineAlign: "start",
+ blockAlign: "start",
+ columnGapPx: 0,
+ metricEdge: "line-box",
+ form: { kind: "point", anchorInline: item.placement.kind === "point" ? item.placement.anchorInline : "start", anchorBlock: item.placement.kind === "point" ? item.placement.anchorBlock : "start" },
inlineSize: "hug",
blockSize: "hug",
wrap: "none",
@@ -420,7 +401,7 @@ function pointFlow(item: TextItem): VisualTextFlowElement["flow"] {
}
function terminalTextElement(item: TextItem, parent: string, order: number): VisualTextFlowElement | VisualPathTextElement {
- if (item.geometry.kind === "path") return {
+ if (item.placement.kind === "path") return {
id: "text",
parent,
kind: "path-text",
@@ -429,31 +410,37 @@ function terminalTextElement(item: TextItem, parent: string, order: number): Vis
document: item.document,
typography: item.style.typography,
paints: item.style.paints,
- path: pathCommands(item.geometry.path),
- ...item.style.path,
+ path: pathCommands(item.placement.path),
+ side: item.placement.side,
+ orientation: item.placement.orientation,
+ startMarginPx: item.placement.startMarginPx,
+ endMarginPx: item.placement.endMarginPx,
+ align: item.placement.align,
+ reverse: item.placement.reverse,
+ overflow: item.placement.overflow,
sequences: item.motion.sequences,
- ...(item.motion.pathMargin === undefined ? {} : { marginAnimation: item.motion.pathMargin }),
+ ...(item.placement.marginMotion === undefined ? {} : { marginAnimation: { keyframes: item.placement.marginMotion.keyframes } }),
};
return {
id: "text",
parent,
kind: "text-flow",
order,
- style: item.geometry.kind === "point"
+ style: item.placement.kind === "point"
? [{ name: "position", value: "relative" }]
: [{ name: "position", value: "absolute" }, { name: "inset", value: 0 }],
document: item.document,
typography: item.style.typography,
paints: item.style.paints,
- flow: item.geometry.kind === "point"
+ flow: item.placement.kind === "point"
? pointFlow(item)
- : { ...item.style.area, form: { kind: "area" } },
+ : { ...(item.placement.kind === "flow" ? item.placement.flow : {}), form: { kind: "area" } } as VisualTextFlowElement["flow"],
sequences: item.motion.sequences,
};
}
function maskText(item: TextItem): string {
- if (item.geometry.kind !== "area") throw new Error(`${item.id} non-Area Text Mask must be materialized by an independent package.`);
+ if (item.placement.kind !== "flow") throw new Error(`${item.id} non-Flow Text Mask must be materialized by an independent package.`);
if (item.motion.sequences.length !== 0) {
throw new Error(`${item.id} sequenced Text Mask must be materialized by an independent package.`);
}
@@ -476,7 +463,8 @@ function maskText(item: TextItem): string {
function maskTextElement(item: TextItem): VisualTextElement {
const typography = item.style.typography;
- const area = item.style.area;
+ if (item.placement.kind !== "flow") throw new Error(`${item.id} non-Flow Text Mask must be materialized by an independent package.`);
+ const area = item.placement.flow;
if (area.inlineSize !== "fixed" || area.blockSize !== "fixed" || area.wrap !== "none"
|| area.columns !== 1 || area.overflow === "ellipsis" || area.overflow === "shrink"
|| typography.writingMode !== "horizontal-tb" || typography.decorations.length !== 0) {
@@ -531,14 +519,8 @@ function maskTextElement(item: TextItem): VisualTextElement {
};
}
-function assertMotionDomain(item: TextItem): void {
- if (item.motion.pathMargin !== undefined) {
- if (item.geometry.kind !== "path") throw new Error(`${item.id} path-margin motion requires Path Text.`);
- }
-}
-
function elements(item: TextItem): VisualElement[] {
- const rootStyle = baseBoxStyle(item.geometry);
+ const rootStyle = baseBoxStyle(item.placement);
const anchor = pointAnchorTransform(item);
if (anchor !== undefined) rootStyle.push({ name: "transform", value: anchor });
const root: VisualElement = { id: "placement", kind: "box", order: 0, style: rootStyle };
@@ -547,57 +529,70 @@ function elements(item: TextItem): VisualElement[] {
parent: "placement",
kind: "box",
order: 1,
- style: item.geometry.kind === "point"
+ style: item.placement.kind === "point"
? [{ name: "position", value: "relative" }]
: [{ name: "position", value: "absolute" }, { name: "inset", value: 0 }],
...(item.motion.item === undefined ? {} : { animation: item.motion.item }),
};
- assertMotionDomain(item);
return [root, motion, terminalTextElement(item, "motion", 2)];
}
-export function renderTypographyTrack(timeline: Timeline, program: TypographyTrackProgram): VisualTrack {
- assertTypographyTrackProgramIdentity(program, timeline);
+export function renderFineTextOccurrence(timeline: Timeline, occurrence: FineTextOccurrence): VisualTrack {
+ assertFineTextOccurrenceIdentity(occurrence, timeline);
const track = sealVisualTrack({
- programSpaceId: timeline.id,
+ timelineId: timeline.id,
visualIr: "hypit.visual-ir@1",
- id: program.id,
- presents: program.items.map((item) => ({
- id: item.id,
- span: { ...item.span },
- stacking: { order: item.style.stackingOrder, tieBreak: item.tieBreak },
- elements: elements(item),
- })),
+ id: occurrence.id,
+ presents: [{
+ id: occurrence.id,
+ order: 0,
+ z: occurrence.placement.z,
+ span: { ...occurrence.span },
+ elements: elements(occurrence),
+ }],
});
assertVisualTrackIdentity(track, timeline);
return track;
}
-export function renderTextMaskTrack(
+function renderTextMaskItems(
timeline: Timeline,
- program: TypographyTrackProgram,
+ items: readonly TextItem[],
material: CompositableSurfaceRef,
spec: TextMaskSpec,
): VisualTrack {
- assertTypographyTrackProgramIdentity(program, timeline);
assertCompositableSurfaceRef(material);
assertTextMaskSpec(spec);
if (material.timing.kind !== "still") {
throw new Error("Official Text Mask requires one explicit still material Surface; timed materials use an independent package.");
}
const track = sealVisualTrack({
- programSpaceId: timeline.id,
+ timelineId: timeline.id,
visualIr: "hypit.visual-ir@1",
id: spec.id,
- presents: program.items.map((item) => {
- assertMotionDomain(item);
- const style = baseBoxStyle(item.geometry);
+ presents: items.map((item, order) => {
+ if (item.placement.kind !== "flow") {
+ throw new Error(`${item.id} non-Flow Text Mask must be materialized by an independent package.`);
+ }
+ const style = baseBoxStyle(item.placement);
const anchor = pointAnchorTransform(item);
if (anchor !== undefined) style.push({ name: "transform", value: anchor });
+ const mapping = resolveContentFit(
+ item.placement.frame,
+ { widthPx: material.width, heightPx: material.height },
+ {
+ sizing: spec.materialFit === "fill" ? "stretch" : spec.materialFit,
+ framePoint: { x: 0.5, y: 0.5 },
+ contentPoint: { x: 0.5, y: 0.5 },
+ offsetPx: { x: 0, y: 0 },
+ constraint: "bounded",
+ },
+ );
return {
id: item.id,
+ order,
+ z: item.placement.z,
span: { ...item.span },
- stacking: { order: item.style.stackingOrder, tieBreak: `${item.tieBreak}:mask` },
elements: [
{
id: "mask", kind: "mask", order: 0, mode: spec.mode,
@@ -608,9 +603,10 @@ export function renderTextMaskTrack(
{
id: "material", parent: "mask", kind: "surface", order: 2, surface: material,
style: [
- { name: "position", value: "absolute" }, { name: "inset", value: 0 },
- { name: "width", value: "100%" }, { name: "height", value: "100%" },
- { name: "object-fit", value: spec.materialFit },
+ { name: "position", value: "absolute" }, { name: "left", value: 0 }, { name: "top", value: 0 },
+ { name: "width", value: `${material.width}px` }, { name: "height", value: `${material.height}px` },
+ { name: "transform-origin", value: "0 0" },
+ { name: "transform", value: `matrix(${mapping.xx},${mapping.yx},${mapping.xy},${mapping.yy},${mapping.tx - item.placement.frame.xPx},${mapping.ty - item.placement.frame.yPx})` },
],
},
],
@@ -620,3 +616,13 @@ export function renderTextMaskTrack(
assertVisualTrackIdentity(track, timeline);
return track;
}
+
+export function renderFineTextMask(
+ timeline: Timeline,
+ occurrence: FineTextOccurrence,
+ material: CompositableSurfaceRef,
+ spec: TextMaskSpec,
+): VisualTrack {
+ assertFineTextOccurrenceIdentity(occurrence, timeline);
+ return renderTextMaskItems(timeline, [occurrence], material, spec);
+}
diff --git a/packages/typography-track/src/surface.ts b/packages/text-fine/src/surface.ts
similarity index 70%
rename from packages/typography-track/src/surface.ts
rename to packages/text-fine/src/surface.ts
index e944631f..733c844f 100644
--- a/packages/typography-track/src/surface.ts
+++ b/packages/text-fine/src/surface.ts
@@ -19,32 +19,39 @@ import {
import type { FontArtifactRef, FontStackRef } from "@hypit/media";
import { spatialTypes } from "@hypit/spatial";
import { sealGraphFragment } from "@hypit/elaborator";
-import type { AuthorValueRef, FragmentOperation, GraphFragment } from "@hypit/elaborator";
+import type { FragmentOperation, GraphFragment } from "@hypit/elaborator";
import { svsRecipeType } from "@hypit/svs";
import type { SvsRecipe } from "@hypit/svs";
import { textTypes } from "@hypit/text";
import type {
StructuredElement,
StructuredSurfaceHandler,
- SurfaceComponentDraft,
- SurfaceRecordDraft,
SurfaceResolvedReference,
MarkupAttributeValue,
} from "@hypit/markup";
import { temporalTypes } from "@hypit/temporal";
-import { createTemporalWindowProjection, temporalWindowAttributeNames } from "@hypit/temporal-markup";
+import { createTemporalWindowConstruction } from "@hypit/temporal-markup";
-import { typographyTrackProducers, typographyTrackTypes } from "./manifest.js";
+import { fineTextWindowAttributeVocabulary, textFineProducers, textFineTypes } from "./manifest.js";
import {
sealTextItemSpec,
sealPlainTextItemSpec,
sealTextMaskSpec,
sealTextMotion,
+ sealTextPathMotion,
sealTextStyle,
- sealTypographyTrackHeader,
stillTextMotion,
+ stillTextPathMotion,
} from "./program.js";
-import type { TextItemSpec, TextMotion, TextStyle } from "./types.js";
+import type {
+ TextFlowPlacementPolicy,
+ TextItemSpec,
+ TextMotion,
+ TextPathMotion,
+ TextPathPlacementPolicy,
+ TextPointPlacementPolicy,
+ TextStyle,
+} from "./types.js";
const input = (name: string) => ({ kind: "fragment-input" as const, name });
const operation = (id: string) => ({ kind: "fragment-operation" as const, operation: id });
@@ -343,13 +350,10 @@ function parsePaintLayer(element: StructuredElement): VisualTextPaintLayer {
}
const STYLE_PROPERTIES = new Set([
- "stack-order", "size", "weight", "font-style", "line-height", "tracking", "word-spacing",
+ "size", "weight", "font-style", "line-height", "tracking", "word-spacing",
"kerning", "synthesis", "language", "direction", "writing-mode", "baseline-shift", "vertical-align", "tab-size", "indent",
"paragraph-before", "paragraph-after", "transform", "caps", "cjk-spacing", "punctuation-trim",
- "fill", "inline-size", "block-size", "padding", "align", "block-align", "wrap", "overflow",
- "max-lines", "minimum-scale", "clip", "columns", "column-gap", "metric-edge",
- "point-anchor-inline", "point-anchor-block", "path-side", "path-orientation", "path-start-margin",
- "path-end-margin", "path-align", "path-reverse", "path-overflow",
+ "fill",
]);
export const decodeTypographyStyleSurface: StructuredSurfaceHandler = ({ element, resolveReference }) => {
@@ -359,8 +363,6 @@ export const decodeTypographyStyleSurface: StructuredSurfaceHandler = ({ element
const unknown = Object.keys(value.properties).filter((name) => !STYLE_PROPERTIES.has(name));
if (unknown.length > 0) throw new Error(`Text Recipe does not accept ${unknown[0]}.`);
const fonts = exactFonts(element, resolveReference);
- const padding = splitNumbers(propString(value, "padding", "0"), "Text Recipe padding", 4);
- const overflow = propString(value, "overflow", "visible") as TextStyle["area"]["overflow"];
const paints: VisualTextPaintLayer[] = [];
const axes: VisualTextTypography["axes"][number][] = [];
const features: VisualTextTypography["features"][number][] = [];
@@ -405,7 +407,6 @@ export const decodeTypographyStyleSurface: StructuredSurfaceHandler = ({ element
}
const style = sealTextStyle({
id,
- stackingOrder: propNumber(value, "stack-order"),
typography: {
fonts,
sizePx: propNumber(value, "size"), weight: propNumber(value, "weight", 400),
@@ -430,33 +431,8 @@ export const decodeTypographyStyleSurface: StructuredSurfaceHandler = ({ element
},
},
paints,
- area: {
- inlineSize: propString(value, "inline-size", "fixed") as "hug" | "fixed",
- blockSize: propString(value, "block-size", "fixed") as "hug" | "fixed",
- paddingPx: { inlineStart: padding[3]!, inlineEnd: padding[1]!, blockStart: padding[0]!, blockEnd: padding[2]! },
- inlineAlign: propString(value, "align", "center") as TextStyle["area"]["inlineAlign"],
- blockAlign: propString(value, "block-align", "center") as TextStyle["area"]["blockAlign"],
- wrap: propString(value, "wrap", "word") as TextStyle["area"]["wrap"],
- overflow,
- ...(value.properties["max-lines"] === undefined ? {} : { maxLines: propNumber(value, "max-lines") }),
- ...(overflow !== "shrink" ? {} : { minimumScale: propNumber(value, "minimum-scale") }),
- clipToFrame: propBoolean(value, "clip", false), columns: propNumber(value, "columns", 1),
- columnGapPx: propNumber(value, "column-gap", 0),
- metricEdge: propString(value, "metric-edge", "line-box") as TextStyle["area"]["metricEdge"],
- },
- point: {
- anchorInline: propString(value, "point-anchor-inline", "center") as TextStyle["point"]["anchorInline"],
- anchorBlock: propString(value, "point-anchor-block", "center") as TextStyle["point"]["anchorBlock"],
- },
- path: {
- side: propString(value, "path-side", "left") as "left" | "right",
- orientation: propString(value, "path-orientation", "follow") as "follow" | "upright",
- startMarginPx: propNumber(value, "path-start-margin", 0), endMarginPx: propNumber(value, "path-end-margin", 0),
- align: propString(value, "path-align", "start") as "start" | "center" | "end",
- reverse: propBoolean(value, "path-reverse", false), overflow: propString(value, "path-overflow", "visible") as "visible" | "clip",
- },
});
- return { records: [{ id, type: typographyTrackTypes.style, value: { kind: "inline", value: style }, range: element.range }], components: [], fragments: [] };
+ return { records: [{ id, type: textFineTypes.style, value: { kind: "inline", value: style }, range: element.range }], components: [], fragments: [] };
};
function keyframeStyle(element: StructuredElement): VisualStyleDeclaration[] {
@@ -486,11 +462,10 @@ export const decodeTypographyMotionSurface: StructuredSurfaceHandler = ({ elemen
allowed(element, ["id"], ["id"]);
const id = text(element, "id");
const itemKeyframes: NonNullable<TextMotion["item"]>["keyframes"][number][] = [];
- const pathKeyframes: NonNullable<TextMotion["pathMargin"]>["keyframes"][number][] = [];
const sequences: VisualTextSequenceAnimation[] = [];
for (const child of element.children) {
if (child.kind === "text") {
- if (child.value.trim()) throw new Error(`${element.name} accepts ItemKeyframe, PathKeyframe and Sequence children.`);
+ if (child.value.trim()) throw new Error(`${element.name} accepts ItemKeyframe and Sequence children.`);
continue;
}
const name = localName(child.name);
@@ -500,11 +475,6 @@ export const decodeTypographyMotionSurface: StructuredSurfaceHandler = ({ elemen
itemKeyframes.push({ atFrame: integer(child, "at"), ...(child.attributes.easing === undefined ? {} : { easing: text(child, "easing") as "linear" | "ease-in" | "ease-out" | "ease-in-out" }), style: keyframeStyle(child) });
continue;
}
- if (name === "PathKeyframe") {
- allowed(child, ["at", "margin", "easing"], ["at", "margin"]);
- pathKeyframes.push({ atFrame: integer(child, "at"), startMarginPx: numeric(child, "margin"), ...(child.attributes.easing === undefined ? {} : { easing: text(child, "easing") as "linear" | "ease-in" | "ease-out" | "ease-in-out" }) });
- continue;
- }
if (name !== "Sequence") throw new Error(`${element.name} does not accept ${child.name}.`);
allowed(child, ["id", "unit", "start-index", "end-index", "order", "start-frame", "duration-frames", "stagger-frames", "cycles", "seed"], ["id", "unit", "start-index", "end-index", "duration-frames"]);
const keyframes = child.children.flatMap((nested) => {
@@ -529,9 +499,30 @@ export const decodeTypographyMotionSurface: StructuredSurfaceHandler = ({ elemen
id,
...(itemKeyframes.length === 0 ? {} : { item: { keyframes: itemKeyframes } }),
sequences,
- ...(pathKeyframes.length === 0 ? {} : { pathMargin: { keyframes: pathKeyframes } }),
});
- return { records: [{ id, type: typographyTrackTypes.motion, value: { kind: "inline", value: motion }, range: element.range }], components: [], fragments: [] };
+ return { records: [{ id, type: textFineTypes.motion, value: { kind: "inline", value: motion }, range: element.range }], components: [], fragments: [] };
+};
+
+export const decodeTypographyPathMotionSurface: StructuredSurfaceHandler = ({ element }) => {
+ allowed(element, ["id"], ["id"]);
+ const id = text(element, "id");
+ const keyframes: TextPathMotion["keyframes"][number][] = [];
+ for (const child of element.children) {
+ if (child.kind === "text") {
+ if (child.value.trim()) throw new Error(`${element.name} accepts only Keyframe children.`);
+ continue;
+ }
+ if (localName(child.name) !== "Keyframe") throw new Error(`${element.name} accepts only Keyframe children.`);
+ allowed(child, ["at", "margin", "easing"], ["at", "margin"]);
+ empty(child);
+ keyframes.push({
+ atFrame: integer(child, "at"),
+ startMarginPx: numeric(child, "margin"),
+ ...(child.attributes.easing === undefined ? {} : { easing: enumText(child, "easing", ["linear", "ease-in", "ease-out", "ease-in-out"] as const) }),
+ });
+ }
+ const motion = sealTextPathMotion({ id, keyframes });
+ return { records: [{ id, type: textFineTypes.pathMotion, value: { kind: "inline", value: motion }, range: element.range }], components: [], fragments: [] };
};
function dedent(value: string): string {
@@ -589,7 +580,7 @@ function paragraph(element: StructuredElement, index: number, resolve: (path: st
if (child.children.some((nested) => nested.kind === "element")) throw new Error(`${child.name} cannot contain nested elements.`);
const spanText = child.children.map((nested) => nested.kind === "text" ? nested.value : "").join("");
if (spanText.length === 0) throw new Error(`${child.name} cannot be empty.`);
- const styleRef = child.attributes.style === undefined ? undefined : reference(child.attributes.style, `${child.name}.style`, typographyTrackTypes.style, resolve);
+ const styleRef = child.attributes.style === undefined ? undefined : reference(child.attributes.style, `${child.name}.style`, textFineTypes.style, resolve);
inlines.push({
kind: "text", id: optionalText(child, "id") ?? `run-${inlineIndex}`, text: spanText,
...(styleRef === undefined ? {} : { style: runStyle(styleRef) }),
@@ -598,7 +589,7 @@ function paragraph(element: StructuredElement, index: number, resolve: (path: st
});
}
if (inlines.length === 0) throw new Error(`${element.name} cannot be empty.`);
- const styleRef = element.attributes.style === undefined ? undefined : reference(element.attributes.style, `${element.name}.style`, typographyTrackTypes.style, resolve);
+ const styleRef = element.attributes.style === undefined ? undefined : reference(element.attributes.style, `${element.name}.style`, textFineTypes.style, resolve);
return { id: optionalText(element, "id") ?? `paragraph-${index}`, inlines, ...(styleRef === undefined ? {} : { style: runStyle(styleRef) }) };
}
@@ -615,211 +606,230 @@ function document(element: StructuredElement, resolve: (path: string) => Surface
return { paragraphs: [{ id: "paragraph-1", inlines: [{ kind: "text", id: "run-1", text: content }] }] };
}
-type FragmentItem = {
- readonly suffix: string;
- readonly windowName: string;
- readonly placementKind: "point" | "area" | "path";
- readonly geometryName: string;
- readonly specName: string;
- readonly contentName?: string;
- readonly styleName: string;
- readonly motionName: string;
-};
+type FineTextForm = "flow" | "point" | "path";
-function createTrackFragment(id: string, items: readonly FragmentItem[]): GraphFragment {
- const operations: FragmentOperation[] = [
- { id: "text:set:empty", producer: typographyTrackProducers.createSet, inputs: {}, result: { kind: "output", name: "set" } },
- ];
- let current = "text:set:empty";
- for (const [index, item] of items.entries()) {
- const bind = `text:placement:${String(index + 1).padStart(4, "0")}`;
- operations.push({
- id: bind,
- producer: item.placementKind === "point" ? typographyTrackProducers.bindPoint : item.placementKind === "area" ? typographyTrackProducers.bindArea : typographyTrackProducers.bindPath,
- inputs: { [item.placementKind === "point" ? "point" : item.placementKind === "area" ? "frame" : "path"]: input(item.geometryName) },
- result: { kind: "output", name: "placement" },
- });
- const materialized = `text:content:${String(index + 1).padStart(4, "0")}`;
- if (item.contentName !== undefined) {
- operations.push({
- id: materialized,
- producer: typographyTrackProducers.materializePlainItem,
- inputs: { spec: input(item.specName), content: input(item.contentName) },
- result: { kind: "output", name: "spec" },
- });
- }
- const append = `text:set:append:${String(index + 1).padStart(4, "0")}`;
- const common = {
- set: operation(current), header: input("header"), timeline: input("timeline"), placement: operation(bind),
- spec: item.contentName === undefined ? input(item.specName) : operation(materialized),
- style: input(item.styleName), motion: input(item.motionName), window: input(item.windowName),
- };
- operations.push({ id: append, producer: typographyTrackProducers.appendItem, inputs: common, result: { kind: "output", name: "set" } });
- current = append;
- }
+const fineTextWindowAttributeNames = fineTextWindowAttributeVocabulary.map(({ name }) => name);
+
+const FLOW_ATTRIBUTES = [
+ "inline-size", "block-size", "padding", "align", "block-align", "wrap", "overflow", "max-lines",
+ "minimum-scale", "clip", "columns", "column-gap", "metric-edge",
+] as const;
+const POINT_ATTRIBUTES = ["anchor-inline", "anchor-block"] as const;
+const PATH_ATTRIBUTES = ["side", "orientation", "start-margin", "end-margin", "align", "reverse", "overflow", "path-motion"] as const;
+
+function flowPlacementPolicy(element: StructuredElement): TextFlowPlacementPolicy {
+ const padding = splitNumbers(text(element, "padding", "0"), `${element.name}.padding`, 4);
+ const overflow = enumText(element, "overflow", ["visible", "clip", "ellipsis", "shrink"] as const, "visible");
+ return {
+ z: integer(element, "z"),
+ flow: {
+ inlineSize: enumText(element, "inline-size", ["hug", "fixed"] as const, "fixed"),
+ blockSize: enumText(element, "block-size", ["hug", "fixed"] as const, "fixed"),
+ paddingPx: { inlineStart: padding[3]!, inlineEnd: padding[1]!, blockStart: padding[0]!, blockEnd: padding[2]! },
+ inlineAlign: enumText(element, "align", ["start", "center", "end", "justify"] as const, "center"),
+ blockAlign: enumText(element, "block-align", ["start", "center", "end"] as const, "center"),
+ wrap: enumText(element, "wrap", ["none", "word", "grapheme"] as const, "word"),
+ overflow,
+ ...(element.attributes["max-lines"] === undefined ? {} : { maxLines: integer(element, "max-lines") }),
+ ...(element.attributes["minimum-scale"] === undefined ? {} : { minimumScale: numeric(element, "minimum-scale") }),
+ clipToFrame: booleanValue(element.attributes.clip, `${element.name}.clip`, false),
+ columns: integer(element, "columns", 1),
+ columnGapPx: numeric(element, "column-gap", 0),
+ metricEdge: enumText(element, "metric-edge", ["line-box", "cap-height", "ink"] as const, "line-box"),
+ },
+ };
+}
+
+function pointPlacementPolicy(element: StructuredElement): TextPointPlacementPolicy {
+ return {
+ z: integer(element, "z"),
+ anchorInline: enumText(element, "anchor-inline", ["start", "center", "end"] as const, "center"),
+ anchorBlock: enumText(element, "anchor-block", ["start", "center", "end"] as const, "center"),
+ };
+}
+
+function pathPlacementPolicy(element: StructuredElement): TextPathPlacementPolicy {
+ return {
+ z: integer(element, "z"),
+ side: enumText(element, "side", ["left", "right"] as const, "left"),
+ orientation: enumText(element, "orientation", ["follow", "upright"] as const, "follow"),
+ startMarginPx: numeric(element, "start-margin", 0),
+ endMarginPx: numeric(element, "end-margin", 0),
+ align: enumText(element, "align", ["start", "center", "end"] as const, "start"),
+ reverse: booleanValue(element.attributes.reverse, `${element.name}.reverse`, false),
+ overflow: enumText(element, "overflow", ["visible", "clip"] as const, "visible"),
+ };
+}
+
+function createFineTextFragment(form: FineTextForm, externalContent: boolean): GraphFragment {
+ const placementKind = form === "flow" ? "area" : form;
+ const geometryInput = form === "flow" ? "frame" : form;
+ const operations: FragmentOperation[] = [{
+ id: "text:placement",
+ producer: placementKind === "area" ? textFineProducers.bindArea
+ : placementKind === "point" ? textFineProducers.bindPoint : textFineProducers.bindPath,
+ inputs: {
+ [geometryInput]: input("geometry"),
+ policy: input("placementPolicy"),
+ ...(form === "path" ? { marginMotion: input("pathMotion") } : {}),
+ },
+ result: { kind: "output", name: "placement" },
+ }];
+ if (externalContent) operations.push({
+ id: "text:content",
+ producer: textFineProducers.materializePlainItem,
+ inputs: { spec: input("spec"), content: input("content") },
+ result: { kind: "output", name: "spec" },
+ });
operations.push(
- { id: "text:finalize", producer: typographyTrackProducers.finalize, inputs: { header: input("header"), set: operation(current) }, result: { kind: "output", name: "program" } },
- { id: "text:render", producer: typographyTrackProducers.render, inputs: { timeline: input("timeline"), program: operation("text:finalize") }, result: { kind: "output", name: "track" } },
+ {
+ id: "text:occurrence",
+ producer: textFineProducers.createOccurrence,
+ inputs: {
+ timeline: input("timeline"), placement: operation("text:placement"),
+ spec: externalContent ? operation("text:content") : input("spec"),
+ style: input("style"), motion: input("motion"), window: input("window"),
+ },
+ result: { kind: "output", name: "occurrence" },
+ },
+ {
+ id: "text:render",
+ producer: textFineProducers.renderOccurrence,
+ inputs: { timeline: input("timeline"), occurrence: operation("text:occurrence") },
+ result: { kind: "output", name: "visual" },
+ },
);
- const inputEntries = [
- { name: "timeline", type: timelineTypes.track },
- { name: "header", type: typographyTrackTypes.header },
- ...items.flatMap((item) => [
- { name: item.geometryName, type: item.placementKind === "point" ? spatialTypes.point : item.placementKind === "area" ? spatialTypes.frame : spatialTypes.path },
- { name: item.specName, type: item.contentName === undefined ? typographyTrackTypes.itemSpec : typographyTrackTypes.plainItemSpec },
- ...(item.contentName === undefined ? [] : [{ name: item.contentName, type: textTypes.text }]),
- { name: item.styleName, type: typographyTrackTypes.style },
- { name: item.motionName, type: typographyTrackTypes.motion },
- { name: item.windowName, type: temporalTypes.window },
- ]),
- ];
- const inputs = [...new Map(inputEntries.map((value) => [value.name, value])).values()];
return sealGraphFragment({
- inputs,
+ inputs: [
+ { name: "timeline", type: timelineTypes.track },
+ { name: "geometry", type: form === "flow" ? spatialTypes.frame : form === "point" ? spatialTypes.point : spatialTypes.path },
+ { name: "placementPolicy", type: form === "flow" ? textFineTypes.flowPlacementPolicy : form === "point" ? textFineTypes.pointPlacementPolicy : textFineTypes.pathPlacementPolicy },
+ ...(form === "path" ? [{ name: "pathMotion", type: textFineTypes.pathMotion }] : []),
+ { name: "spec", type: externalContent ? textFineTypes.plainItemSpec : textFineTypes.itemSpec },
+ ...(externalContent ? [{ name: "content", type: textTypes.text }] : []),
+ { name: "style", type: textFineTypes.style },
+ { name: "motion", type: textFineTypes.motion },
+ { name: "window", type: temporalTypes.window },
+ ],
operations,
exports: [
- {
- name: "program", type: typographyTrackTypes.program, root: operation("text:finalize"),
- },
- {
- name: "track", type: compositionTypes.visualTrack, root: operation("text:render"),
- },
+ { name: "occurrence", type: textFineTypes.occurrence, root: operation("text:occurrence") },
+ { name: "visual", type: compositionTypes.visualTrack, root: operation("text:render") },
],
});
}
-export const decodeTypographyTrackSurface: StructuredSurfaceHandler = ({ element, resolveReference }) => {
- allowed(element, ["id", "timeline"], ["id"]);
- const id = text(element, "id");
- const context = resolveTemporalContext({ element, resolveReference });
- const headerId = `${id}.__header`;
- const records: SurfaceRecordDraft[] = [{
- id: headerId, type: typographyTrackTypes.header,
- value: { kind: "inline", value: sealTypographyTrackHeader({ id }) }, range: element.range,
- }];
- const defaultMotionId = `${id}.__still-motion`;
- records.push({ id: defaultMotionId, type: typographyTrackTypes.motion, value: { kind: "inline", value: stillTextMotion(defaultMotionId) }, range: element.range });
- const temporalComponents: SurfaceComponentDraft[] = [];
- const temporalFragments: ReturnType<typeof createTemporalWindowProjection>["fragments"][number][] = [];
- const items: Array<FragmentItem & {
- readonly geometry: SurfaceResolvedReference;
- readonly style: SurfaceResolvedReference;
- readonly motion: AuthorValueRef;
- readonly window: ReturnType<typeof createTemporalWindowProjection>["ref"];
- readonly content?: SurfaceResolvedReference;
- readonly specId: string;
- }> = [];
- const sharedInputNames = new Map<string, string>();
- const sharedInputName = (prefix: string, ref: AuthorValueRef, suffix: string): string => {
- const key = `${prefix}:${JSON.stringify(ref)}`;
- const existing = sharedInputNames.get(key);
- if (existing !== undefined) return existing;
- const name = `item-${suffix}-${prefix}`;
- sharedInputNames.set(key, name);
- return name;
- };
- for (const child of element.children) {
- if (child.kind === "text") {
- if (child.value.trim()) throw new Error(`${element.name} accepts Point, Area and Path children.`);
- continue;
- }
- const form = localName(child.name);
- if (form !== "Point" && form !== "Area" && form !== "Path") throw new Error(`${element.name} accepts Point, Area and Path children.`);
- const index = items.length + 1;
- const suffix = String(index).padStart(4, "0");
- allowed(child, [
- "id", "content", "placement", "style", "motion", ...temporalWindowAttributeNames,
- ], ["id", "placement", "style"]);
- const itemId = text(child, "id");
- const temporal = createTemporalWindowProjection({ id: itemId, element: child, ...context, resolveReference });
- records.push(...temporal.records); temporalComponents.push(...temporal.components); temporalFragments.push(...temporal.fragments);
- const placementKind = form.toLowerCase() as "point" | "area" | "path";
- const geometry = reference(child.attributes.placement, `${child.name}.placement`, placementKind === "point" ? spatialTypes.point : placementKind === "area" ? spatialTypes.frame : spatialTypes.path, resolveReference);
- const style = reference(child.attributes.style, `${child.name}.style`, typographyTrackTypes.style, resolveReference);
- const motionRef = child.attributes.motion === undefined
+function decodeFineTextOccurrenceSurface(form: FineTextForm): StructuredSurfaceHandler {
+ return ({ element, resolveReference }) => {
+ const geometryAttribute = form === "flow" ? "within" : form;
+ const geometryType = form === "flow" ? spatialTypes.frame : form === "point" ? spatialTypes.point : spatialTypes.path;
+ allowed(element, [
+ "id", "timeline", geometryAttribute, "style", "motion", "content", "z",
+ ...(form === "flow" ? FLOW_ATTRIBUTES : form === "point" ? POINT_ATTRIBUTES : PATH_ATTRIBUTES),
+ ...fineTextWindowAttributeNames,
+ ], ["id", "timeline", geometryAttribute, "style", "z"]);
+ const id = text(element, "id");
+ const context = resolveTemporalContext({ element, resolveReference });
+ const temporal = createTemporalWindowConstruction({
+ id: `${id}.__window`, subjectId: id, element,
+ timeline: context.timeline, resolveReference,
+ });
+ const geometry = reference(element.attributes[geometryAttribute], `${element.name}.${geometryAttribute}`, geometryType, resolveReference);
+ const style = reference(element.attributes.style, `${element.name}.style`, textFineTypes.style, resolveReference);
+ const defaultMotionId = `${id}.__still-motion`;
+ const motion = element.attributes.motion === undefined
? ({ kind: "record", id: defaultMotionId } as const)
- : reference(child.attributes.motion, `${child.name}.motion`, typographyTrackTypes.motion, resolveReference).ref;
- const specId = `${id}.item.${suffix}.spec`;
- const windowName = `item-${suffix}-window`;
- const content = child.attributes.content === undefined
+ : reference(element.attributes.motion, `${element.name}.motion`, textFineTypes.motion, resolveReference).ref;
+ const content = element.attributes.content === undefined
? undefined
- : reference(child.attributes.content, `${child.name}.content`, textTypes.text, resolveReference);
- if (content !== undefined) empty(child);
+ : reference(element.attributes.content, `${element.name}.content`, textTypes.text, resolveReference);
+ if (content !== undefined) empty(element);
+ const specId = `${id}.__spec`;
+ const placementPolicyId = `${id}.__placement-policy`;
+ const placementPolicy = form === "flow" ? flowPlacementPolicy(element)
+ : form === "point" ? pointPlacementPolicy(element) : pathPlacementPolicy(element);
+ const defaultPathMotionId = `${id}.__still-path-motion`;
+ const pathMotion = form !== "path" ? undefined : element.attributes["path-motion"] === undefined
+ ? ({ kind: "record", id: defaultPathMotionId } as const)
+ : reference(element.attributes["path-motion"], `${element.name}.path-motion`, textFineTypes.pathMotion, resolveReference).ref;
const spec = content === undefined
- ? sealTextItemSpec({
- id: itemId,
- document: document(child, resolveReference),
- })
- : sealPlainTextItemSpec({
- id: itemId,
- });
- records.push({
- id: specId,
- type: content === undefined ? typographyTrackTypes.itemSpec : typographyTrackTypes.plainItemSpec,
- value: { kind: "inline", value: spec }, range: child.range,
- });
- items.push({
- suffix, placementKind, windowName,
- geometryName: sharedInputName("geometry", geometry.ref, suffix), specName: `item-${suffix}-spec`,
- styleName: sharedInputName("style", style.ref, suffix), motionName: sharedInputName("motion", motionRef, suffix),
- ...(content === undefined ? {} : { contentName: sharedInputName("content", content.ref, suffix), content }),
- geometry, style, motion: motionRef, specId, window: temporal.ref,
- });
- }
- if (items.length === 0) throw new Error(`${element.name} requires at least one Point, Area or Path.`);
- const fragmentItems: FragmentItem[] = items.map(({ suffix, placementKind, geometryName, specName, styleName, motionName, contentName, windowName }) => ({
- suffix, placementKind, geometryName, specName, styleName, motionName, windowName,
- ...(contentName === undefined ? {} : { contentName }),
- }));
- const fragment = createTrackFragment(id, fragmentItems);
- return {
- records,
- components: [...temporalComponents, {
- id, fragment: fragment.id,
- inputs: {
- timeline: context.timeline.ref, header: { kind: "record", id: headerId },
- ...Object.fromEntries(items.flatMap((item) => [
- [item.geometryName, item.geometry.ref], [item.specName, { kind: "record" as const, id: item.specId }],
- [item.windowName, item.window],
- [item.styleName, item.style.ref], [item.motionName, item.motion],
- ...(item.content === undefined ? [] : [[item.contentName!, item.content.ref] as const]),
- ])),
- },
- outputs: { program: `${id}.program`, track: `${id}.track` }, range: element.range,
- }],
- fragments: [...temporalFragments, fragment],
- exports: [`${id}.program`, `${id}.track`],
+ ? sealTextItemSpec({ id, document: document(element, resolveReference) })
+ : sealPlainTextItemSpec({ id });
+ const fragment = createFineTextFragment(form, content !== undefined);
+ return {
+ records: [
+ {
+ id: defaultMotionId, type: textFineTypes.motion,
+ value: { kind: "inline", value: stillTextMotion(defaultMotionId) }, range: element.range,
+ },
+ {
+ id: placementPolicyId,
+ type: form === "flow" ? textFineTypes.flowPlacementPolicy : form === "point" ? textFineTypes.pointPlacementPolicy : textFineTypes.pathPlacementPolicy,
+ value: { kind: "inline", value: placementPolicy }, range: element.range,
+ },
+ ...(form !== "path" ? [] : [{
+ id: defaultPathMotionId, type: textFineTypes.pathMotion,
+ value: { kind: "inline" as const, value: stillTextPathMotion(defaultPathMotionId) }, range: element.range,
+ }]),
+ {
+ id: specId, type: content === undefined ? textFineTypes.itemSpec : textFineTypes.plainItemSpec,
+ value: { kind: "inline", value: spec }, range: element.range,
+ },
+ ...temporal.records,
+ ],
+ components: [
+ ...temporal.components,
+ {
+ id, fragment: fragment.id,
+ inputs: {
+ timeline: context.timeline.ref, geometry: geometry.ref,
+ placementPolicy: { kind: "record", id: placementPolicyId },
+ ...(pathMotion === undefined ? {} : { pathMotion }),
+ spec: { kind: "record", id: specId },
+ ...(content === undefined ? {} : { content: content.ref }),
+ style: style.ref, motion, window: temporal.ref,
+ },
+ outputs: { occurrence: `${id}.occurrence`, visual: `${id}.visual` }, range: element.range,
+ },
+ ],
+ fragments: [...temporal.fragments, fragment],
+ exports: [`${id}.occurrence`, `${id}.visual`],
+ };
};
-};
+}
+
+export const decodeTypographyFlowSurface = decodeFineTextOccurrenceSurface("flow");
+export const decodeTypographyPointSurface = decodeFineTextOccurrenceSurface("point");
+export const decodeTypographyPathSurface = decodeFineTextOccurrenceSurface("path");
function createMaskFragment(id: string): GraphFragment {
const inputs = [
{ name: "timeline", type: timelineTypes.track },
- { name: "program", type: typographyTrackTypes.program },
+ { name: "occurrence", type: textFineTypes.occurrence },
{ name: "material", type: mediaTypes.compositableSurface },
- { name: "spec", type: typographyTrackTypes.maskSpec },
+ { name: "spec", type: textFineTypes.maskSpec },
];
return sealGraphFragment({
inputs,
operations: [
{
- id: "text-mask:render", producer: typographyTrackProducers.renderMask,
- inputs: { timeline: input("timeline"), program: input("program"), material: input("material"), spec: input("spec") },
- result: { kind: "output", name: "track" },
+ id: "text-mask:render", producer: textFineProducers.renderOccurrenceMask,
+ inputs: { timeline: input("timeline"), occurrence: input("occurrence"), material: input("material"), spec: input("spec") },
+ result: { kind: "output", name: "visual" },
},
],
exports: [{
- name: "track", type: compositionTypes.visualTrack, root: operation("text-mask:render"),
+ name: "visual", type: compositionTypes.visualTrack, root: operation("text-mask:render"),
}],
});
}
export const decodeTypographyMaskSurface: StructuredSurfaceHandler = ({ element, resolveReference }) => {
- allowed(element, ["id", "timeline", "text", "material", "mode", "fit"], ["id", "text", "material"]);
+ allowed(element, ["id", "timeline", "text", "material", "mode", "fit"], ["id", "timeline", "text", "material"]);
empty(element);
const id = text(element, "id");
const context = resolveTemporalContext({ element, resolveReference });
- const program = reference(element.attributes.text, `${element.name}.text`, typographyTrackTypes.program, resolveReference);
+ const occurrence = reference(element.attributes.text, `${element.name}.text`, textFineTypes.occurrence, resolveReference);
const material = reference(element.attributes.material, `${element.name}.material`, mediaTypes.compositableSurface, resolveReference);
const specId = `${id}.__spec`;
const spec = sealTextMaskSpec({
@@ -829,13 +839,13 @@ export const decodeTypographyMaskSurface: StructuredSurfaceHandler = ({ element,
});
const fragment = createMaskFragment(id);
return {
- records: [{ id: specId, type: typographyTrackTypes.maskSpec, value: { kind: "inline", value: spec }, range: element.range }],
+ records: [{ id: specId, type: textFineTypes.maskSpec, value: { kind: "inline", value: spec }, range: element.range }],
components: [{
id, fragment: fragment.id,
- inputs: { timeline: context.timeline.ref, program: program.ref, material: material.ref, spec: { kind: "record", id: specId } },
- outputs: { track: `${id}.track` }, range: element.range,
+ inputs: { timeline: context.timeline.ref, occurrence: occurrence.ref, material: material.ref, spec: { kind: "record", id: specId } },
+ outputs: { visual: `${id}.visual` }, range: element.range,
}],
fragments: [fragment],
- exports: [`${id}.track`],
+ exports: [`${id}.visual`],
};
};
diff --git a/packages/typography-track/src/types.ts b/packages/text-fine/src/types.ts
similarity index 50%
rename from packages/typography-track/src/types.ts
rename to packages/text-fine/src/types.ts
index 735aa30a..0812de24 100644
--- a/packages/typography-track/src/types.ts
+++ b/packages/text-fine/src/types.ts
@@ -19,47 +19,62 @@ export type TextAreaFlow = Omit<VisualTextFlow, "form">;
export type TextStyle = {
readonly id: string;
- readonly stackingOrder: number;
readonly typography: TextTypography;
readonly paints: readonly TextPaintLayer[];
- readonly area: TextAreaFlow;
- readonly point: {
- readonly anchorInline: "start" | "center" | "end";
- readonly anchorBlock: "start" | "center" | "end";
- };
- readonly path: {
- readonly side: "left" | "right";
- readonly orientation: "follow" | "upright";
- readonly startMarginPx: number;
- readonly endMarginPx: number;
- readonly align: "start" | "center" | "end";
- readonly reverse: boolean;
- readonly overflow: "visible" | "clip";
- };
};
export type TextMotion = {
readonly id: string;
readonly item?: VisualAnimation;
readonly sequences: readonly VisualTextSequenceAnimation[];
- readonly pathMargin?: {
- readonly keyframes: readonly {
- readonly atFrame: number;
- readonly startMarginPx: number;
- readonly easing?: "linear" | "ease-in" | "ease-out" | "ease-in-out";
- }[];
- };
};
-export type TextGeometry =
- | { readonly kind: "point"; readonly point: SpatialPoint }
- | { readonly kind: "area"; readonly frame: SpatialFrame }
- | { readonly kind: "path"; readonly path: SpatialPath };
+export type TextPathMotion = {
+ readonly id: string;
+ readonly keyframes: readonly {
+ readonly atFrame: number;
+ readonly startMarginPx: number;
+ readonly easing?: "linear" | "ease-in" | "ease-out" | "ease-in-out";
+ }[];
+};
-export type TextPlacement = {
- readonly geometry: TextGeometry;
+export type TextFlowPlacementPolicy = {
+ readonly z: number;
+ readonly flow: TextAreaFlow;
};
+export type TextPointPlacementPolicy = {
+ readonly z: number;
+ readonly anchorInline: "start" | "center" | "end";
+ readonly anchorBlock: "start" | "center" | "end";
+};
+
+export type TextPathPlacementPolicy = {
+ readonly z: number;
+ readonly side: "left" | "right";
+ readonly orientation: "follow" | "upright";
+ readonly startMarginPx: number;
+ readonly endMarginPx: number;
+ readonly align: "start" | "center" | "end";
+ readonly reverse: boolean;
+ readonly overflow: "visible" | "clip";
+};
+
+export type TextPlacement =
+ | {
+ readonly kind: "flow";
+ readonly frame: SpatialFrame;
+ } & TextFlowPlacementPolicy
+ | {
+ readonly kind: "point";
+ readonly point: SpatialPoint;
+ } & TextPointPlacementPolicy
+ | {
+ readonly kind: "path";
+ readonly path: SpatialPath;
+ readonly marginMotion?: TextPathMotion;
+ } & TextPathPlacementPolicy;
+
export type TextItemSpec = {
readonly id: string;
readonly document: TextDocument;
@@ -77,33 +92,28 @@ export type PlainTextItemSpec = {
export type TextItem = {
readonly id: string;
readonly span: FrameSpan;
- readonly geometry: TextGeometry;
+ readonly placement: TextPlacement;
readonly document: TextDocument;
readonly style: TextStyle;
readonly motion: TextMotion;
- readonly tieBreak: string;
};
-export type TypographyTrackProgram = {
- readonly id: string;
- readonly items: readonly TextItem[];
+/**
+ * One independently authored fine-text occurrence. It is a package-owned
+ * compiled value for authoring and Studio projection, not a Core Track or a
+ * second temporal model. Its span has already been resolved on `timelineId`.
+ */
+export type FineTextOccurrence = TextItem & {
+ readonly timelineId: string;
};
/**
* Separate graph contract for revealing one explicitly supplied owned Surface
- * through an already authored Text Program. It is not a TextStyle mode and it
- * never samples another Track or the final composite.
+ * through one already authored fine-text occurrence. It is not a TextStyle
+ * mode and it never samples another Track or the final composite.
*/
export type TextMaskSpec = {
readonly id: string;
readonly mode: "alpha" | "luminance";
readonly materialFit: "contain" | "cover" | "fill";
};
-
-export type TypographyTrackHeader = {
- readonly id: string;
-};
-
-export type TypographyTrackSet = {
- readonly items: readonly TextItem[];
-};
diff --git a/packages/typography-track/test/typography-track.test.ts b/packages/text-fine/test/text-fine.test.ts
similarity index 58%
rename from packages/typography-track/test/typography-track.test.ts
rename to packages/text-fine/test/text-fine.test.ts
index df255ad5..614cdd4b 100644
--- a/packages/typography-track/test/typography-track.test.ts
+++ b/packages/text-fine/test/text-fine.test.ts
@@ -1,67 +1,65 @@
-import { sealTimeline } from "@hypit/timeline";
+import { sealTimeline, timelineDependency, timelineTypes } from "@hypit/timeline";
import assert from "node:assert/strict";
import test from "node:test";
import { fixtureResource } from "../../../test/fixture-resource.js";
-import { timelineFixture } from "../../../test/timeline-fixture.js";
+import { narrativeProjectionFixture, timelineFixture } from "../../../test/timeline-fixture.js";
import { projectSelectionWindow } from "../../../test/temporal-fixture.js";
import { spatialComponent, videoContractManifests } from "../../../test/support/video-domain.js";
import { registerTypeValidatorFacets } from "@hypit/component-kit";
-import { compositionTypes, sealComposition, sealVisualTrack } from "@hypit/composition";
+import { compositionTypes, sealComposition } from "@hypit/composition";
import { createResolvedClosure, sealBuildRequest, start } from "@hypit/core";
import { AuthorFrontendRegistry, compileSourceClosure, resolveCompiledSourceExport } from "@hypit/elaborator";
import { compileHyperframesDocument } from "@hypit/hyperframes";
import { mediaDependency, mediaTypes } from "@hypit/media";
import type { CompositableSurfaceRef, FontArtifactRef } from "@hypit/media";
import type { NarrativeSelectionRef } from "@hypit/narrative";
-import { sealProgramSpace } from "@hypit/program-space";
-import { programSpaceDependency, programSpaceTypes } from "@hypit/program-space";
import type { ModuleManifest } from "@hypit/protocol";
-import { timelineDependency, timelineTypes } from "@hypit/timeline";
import {
- appendProjectedTextItem,
bindAreaTextPlacement,
- createTypographyTrackSet,
- finalizeTypographyTrack,
- assertTypographyTrackProgramIdentity,
- renderTypographyTrack,
- renderTextMaskTrack,
+ bindPathTextPlacement,
+ createFineTextOccurrence,
+ renderFineTextOccurrence,
+ renderFineTextMask,
sealTextItemSpec,
sealTextStyle,
- sealTypographyTrackHeader,
- sealTypographyTrackProgram,
stillTextMotion,
sealTextMotion,
+ sealTextPathMotion,
sealTextMaskSpec,
decodeTypographyMotionSurface,
+ decodeTypographyPathMotionSurface,
decodeTypographyMaskSurface,
+ decodeTypographyFlowSurface,
+ decodeTypographyPointSurface,
+ decodeTypographyPathSurface,
decodeTypographyStyleSurface,
- decodeTypographyTrackSurface,
- typographyTrackManifest,
- typographyTrackMarkupSurfaces,
- typographyTrackModuleRef,
- typographyTrackProducers,
- typographyTrackTypes,
-} from "@hypit/typography-track";
-import type { TextStyle } from "@hypit/typography-track";
+ textFineManifest,
+ textFineMarkupSurfaces,
+ textFineModuleRef,
+ textFineProducers,
+ textFineTypes,
+} from "@hypit/text-fine";
+import type { TextStyle } from "@hypit/text-fine";
import { spatialDependency, spatialTypes } from "@hypit/spatial";
import { svsManifest, svsRecipeType } from "@hypit/svs";
import { sealText, textComponent, textDependency, textManifest, textTypes } from "@hypit/text";
import { MarkupSurfaceRegistry, createMarkupAuthorFrontend } from "@hypit/markup";
import { createRecordAdmitter, TypeValidatorRegistry } from "@hypit/validation";
-const space = sealTimeline({ items: [], id: "test-space", durationSec: 5,
- frameRate: { numerator: 30, denominator: 1 },
+const space = sealTimeline({ id: "test-space", frameCount: 150, frameRate: { numerator: 30, denominator: 1 },
});
-const semantic = timelineFixture(space, { anchors: [
+const semanticOptions = { narrativeId: "script", segments: [{ id: "line", frameCount: 150 }], anchors: [
{ identity: "selection:start", frame: 30 },
{ identity: "selection:end", frame: 60 },
-] });
+] } as const;
+const semantic = timelineFixture(space, semanticOptions);
+const narrativeProjection = narrativeProjectionFixture(semantic, semanticOptions);
const exactTestFont: FontArtifactRef = {
sources: [{ artifact: {
kind: "blob",
- resource: fixtureResource("typography-track-test-font"),
+ resource: fixtureResource("text-fine-test-font"),
size: 1,
mediaType: "font/woff2",
} }],
@@ -72,7 +70,7 @@ const exactTestFont: FontArtifactRef = {
const exactTestSurface: CompositableSurfaceRef = {
artifact: {
kind: "blob",
- resource: fixtureResource("typography-track-test-surface"),
+ resource: fixtureResource("text-fine-test-surface"),
size: 1,
mediaType: "image/png",
},
@@ -83,11 +81,10 @@ const exactTestSurface: CompositableSurfaceRef = {
timing: { kind: "still" },
};
-function textStyle(id: string, stackingOrder = 50): TextStyle {
+function textStyle(id: string): TextStyle {
return sealTextStyle({
id,
- stackingOrder,
typography: {
fonts: [exactTestFont],
sizePx: 48,
@@ -127,113 +124,80 @@ function textStyle(id: string, stackingOrder = 50): TextStyle {
},
},
],
- area: {
- inlineSize: "fixed",
- blockSize: "fixed",
- paddingPx: { inlineStart: 0, inlineEnd: 0, blockStart: 0, blockEnd: 0 },
- inlineAlign: "center",
- blockAlign: "center",
- wrap: "word",
- overflow: "visible",
- clipToFrame: false,
- columns: 1,
- columnGapPx: 0,
- metricEdge: "line-box",
- },
- point: { anchorInline: "center", anchorBlock: "center" },
- path: {
- side: "left",
- orientation: "follow",
- startMarginPx: 0,
- endMarginPx: 0,
- align: "start",
- reverse: false,
- overflow: "visible",
- },
});
}
+const flowPolicy = (z: number, overrides: Partial<import("@hypit/text-fine").TextAreaFlow> = {}) => ({
+ z,
+ flow: {
+ inlineSize: "fixed" as const, blockSize: "fixed" as const,
+ paddingPx: { inlineStart: 0, inlineEnd: 0, blockStart: 0, blockEnd: 0 },
+ inlineAlign: "center" as const, blockAlign: "center" as const, wrap: "word" as const,
+ overflow: "visible" as const, clipToFrame: false, columns: 1, columnGapPx: 0,
+ metricEdge: "line-box" as const,
+ ...overrides,
+ },
+});
+
+const pathPolicy = (z: number) => ({
+ z, side: "left" as const, orientation: "follow" as const,
+ startMarginPx: 0, endMarginPx: 0, align: "start" as const,
+ reverse: false, overflow: "visible" as const,
+});
+
function document(text: string) {
return { paragraphs: [{ id: "paragraph", inlines: [{ kind: "text" as const, id: "run", text }] }] };
}
-test("persistent and timed Text Items lower to ordinary VisualTrack Presents", () => {
- const style = textStyle("editorial", 55);
- const program = sealTypographyTrackProgram({
-
- id: "editorial-text",
- items: [
- {
- id: "watermark",
- span: { startFrame: 0, endFrameExclusive: 150 },
- tieBreak: "watermark",
- geometry: { kind: "point", point: { xPx: 900, yPx: 80 } },
- document: document("SVML"),
- style: { ...style, id: "watermark", stackingOrder: 90 },
- motion: stillTextMotion(),
- },
- {
- id: "callout",
- span: { startFrame: 30, endFrameExclusive: 90 },
- tieBreak: "callout",
- geometry: { kind: "area", frame: { xPx: 108, yPx: 1248, widthPx: 864, heightPx: 230.4 } },
- document: document("Intent, not timeline"),
- style,
- motion: stillTextMotion(),
- },
- ],
- });
-
- assert.doesNotThrow(() => assertTypographyTrackProgramIdentity(program, space));
- const track = renderTypographyTrack(space, program);
- assert.deepEqual(track.presents.map((present) => present.id), ["watermark", "callout"]);
- assert.equal(track.presents[0]?.elements[2]?.kind, "text-flow");
+function absoluteWindow(subjectId: string, startFrame: number, endFrameExclusive: number) {
+ return {
+ id: `${subjectId}-window`, subjectId,
+ start: { id: `${subjectId}-window.start`, subjectId, timelineId: space.id, frame: startFrame },
+ end: { id: `${subjectId}-window.end`, subjectId, timelineId: space.id, frame: endFrameExclusive },
+ span: { startFrame, endFrameExclusive },
+ };
+}
- const lower = sealVisualTrack({ programSpaceId: "test-space",
- visualIr: "hypit.visual-ir@1",
- id: "lower",
- presents: [{
- id: "lower",
- span: { startFrame: 0, endFrameExclusive: 150 },
- stacking: { order: 40, tieBreak: "lower" },
- elements: [{ id: "root", kind: "box", order: 0, style: [] }],
- }],
- });
- const rendered = compileHyperframesDocument(sealComposition({
- id: "text-film",
- canvas: { width: 1080, height: 1920, clearColor: "#000000" },
- tracks: [track, lower],
- }), space);
- assert.match(rendered.html, /data-hypit-text-run="run"/u);
- assert.match(rendered.html, /background-image:linear-gradient\(#111111,#111111\)/u);
- assert.ok(rendered.html.indexOf('data-hypit-present-id="lower"') < rendered.html.indexOf('data-hypit-present-id="callout"'));
+test("one fine Text occurrence renders without an aggregate Typography program", () => {
+ const occurrence = createFineTextOccurrence(
+ space,
+ bindAreaTextPlacement({ xPx: 80, yPx: 220, widthPx: 920, heightPx: 520 }, flowPolicy(60)),
+ sealTextItemSpec({ id: "standalone", document: document("One truthful occurrence") }),
+ textStyle("standalone-style"),
+ stillTextMotion("standalone-motion"),
+ absoluteWindow("standalone", 30, 90),
+ );
+ assert.equal(occurrence.timelineId, space.id);
+ assert.deepEqual(occurrence.span, { startFrame: 30, endFrameExclusive: 90 });
+ const visual = renderFineTextOccurrence(space, occurrence);
+ assert.equal(visual.id, "standalone");
+ assert.equal(visual.presents.length, 1);
+ assert.equal(visual.presents[0]?.elements[2]?.kind, "text-flow");
});
-test("Text Mask explicitly consumes one authored Text Program and one owned still Surface", () => {
- const program = sealTypographyTrackProgram({
- id: "mask-shape",
- items: [{
- id: "mask-title",
- span: { startFrame: 0, endFrameExclusive: 150 }, tieBreak: "mask-title",
- geometry: { kind: "area", frame: { xPx: 100, yPx: 200, widthPx: 800, heightPx: 240 } },
- document: document("OWNED MASK"),
- style: (() => {
- const style = textStyle("mask-style", 75);
- return { ...style, area: { ...style.area, wrap: "none" as const } };
- })(),
- motion: stillTextMotion(),
- }],
- });
+test("Text Mask explicitly consumes one fine Text occurrence and one owned still Surface", () => {
+ const baseStyle = textStyle("mask-style");
+ const occurrence = createFineTextOccurrence(
+ space,
+ bindAreaTextPlacement({ xPx: 100, yPx: 200, widthPx: 800, heightPx: 240 }, flowPolicy(75, { wrap: "none" })),
+ sealTextItemSpec({ id: "mask-title", document: document("OWNED MASK") }),
+ baseStyle,
+ stillTextMotion(),
+ absoluteWindow("mask-title", 0, 150),
+ );
const material: CompositableSurfaceRef = {
artifact: { kind: "blob", resource: fixtureResource("text-mask-material"), size: 1, mediaType: "image/png" },
- width: 800, height: 240, colorSpace: "srgb", alphaMode: "straight", timing: { kind: "still" },
+ width: 400, height: 240, colorSpace: "srgb", alphaMode: "straight", timing: { kind: "still" },
};
- const track = renderTextMaskTrack(space, program, material, sealTextMaskSpec({
+ const track = renderFineTextMask(space, occurrence, material, sealTextMaskSpec({
id: "masked-title", mode: "alpha", materialFit: "cover",
}));
assert.equal(track.id, "masked-title");
assert.deepEqual(track.presents[0]?.elements.map((element) => element.kind), ["mask", "text", "surface"]);
assert.equal(track.presents[0]?.elements[2]?.parent, "mask");
+ assert.ok(track.presents[0]?.elements[2]?.style.some((entry) =>
+ entry.name === "transform" && entry.value === "matrix(2,0,0,2,0,-120)"));
+ assert.equal(track.presents[0]?.elements[2]?.style.some((entry) => entry.name === "object-fit"), false);
const html = compileHyperframesDocument(sealComposition({
id: "owned-mask-composition",
canvas: { width: 1080, height: 1920, clearColor: "#000000" }, tracks: [track],
@@ -241,39 +205,29 @@ test("Text Mask explicitly consumes one authored Text Program and one owned stil
assert.match(html, /<foreignObject/u);
assert.match(html, />OWNED MASK</u);
assert.match(html, /mask-type:alpha/u);
- assert.throws(() => renderTextMaskTrack(space, program, {
+ assert.throws(() => renderFineTextMask(space, occurrence, {
...material, artifact: { ...material.artifact, mediaType: "video/webm" },
timing: { kind: "frames", frameCount: 150, frameRate: { numerator: 30, denominator: 1 } },
}, sealTextMaskSpec({
id: "timed-mask", mode: "alpha", materialFit: "cover",
})), /requires one explicit still material Surface/u);
- assert.throws(() => renderTextMaskTrack(space, sealTypographyTrackProgram({
- ...program,
- id: "advanced-mask-shape",
- items: program.items.map((item) => ({
- ...item,
- style: { ...item.style, area: { ...item.style.area, overflow: "shrink", minimumScale: 0.7 } },
- })),
- }), material, sealTextMaskSpec({
+ assert.throws(() => renderFineTextMask(space, {
+ ...occurrence,
+ placement: occurrence.placement.kind === "flow"
+ ? { ...occurrence.placement, flow: { ...occurrence.placement.flow, overflow: "shrink", minimumScale: 0.7 } }
+ : occurrence.placement,
+ }, material, sealTextMaskSpec({
id: "advanced-mask", mode: "alpha", materialFit: "cover",
})), /must be materialized by an independent package/u);
});
-test("TypographyTrackProgram rejects a frame span outside Timeline", () => {
- const program = sealTypographyTrackProgram({
-
- id: "invalid-text",
- items: [{
- id: "late",
- span: { startFrame: 149, endFrameExclusive: 151 },
- tieBreak: "late",
- geometry: { kind: "area", frame: { xPx: 0, yPx: 0, widthPx: 1080, heightPx: 192 } },
- document: document("Too late"),
- style: textStyle("late"),
- motion: stillTextMotion(),
- }],
- });
- assert.throws(() => renderTypographyTrack(space, program), /outside Timeline/u);
+test("FineTextOccurrence rejects a frame span outside Timeline", () => {
+ assert.throws(() => createFineTextOccurrence(
+ space,
+ bindAreaTextPlacement({ xPx: 0, yPx: 0, widthPx: 1080, heightPx: 192 }, flowPolicy(50)),
+ sealTextItemSpec({ id: "late", document: document("Too late") }),
+ textStyle("late"), stillTextMotion(), absoluteWindow("late", 149, 151),
+ ), /outside/u);
});
test("Selection Text consumes explicit Selection, Timeline, Style, Motion and Placement edges", () => {
@@ -283,28 +237,26 @@ test("Selection Text consumes explicit Selection, Timeline, Style, Motion and Pl
startAnchorId: "selection:start",
endAnchorId: "selection:end",
};
- const header = sealTypographyTrackHeader({ id: "selected-text" });
const spec = sealTextItemSpec({
id: "meaning",
document: document("MEANING"),
});
- const program = finalizeTypographyTrack(header, appendProjectedTextItem(
- createTypographyTrackSet(),
- header,
+ const occurrence = createFineTextOccurrence(
space,
- bindAreaTextPlacement({ xPx: 108, yPx: 192, widthPx: 864, heightPx: 192 }),
+ bindAreaTextPlacement({ xPx: 108, yPx: 192, widthPx: 864, heightPx: 192 }, flowPolicy(80)),
spec,
- textStyle("meaning", 80),
+ textStyle("meaning"),
stillTextMotion(),
projectSelectionWindow({
itemId: spec.id,
semantic,
+ narrative: narrativeProjection,
selection,
projection: { start: { ref: "selection.start" }, end: { ref: "selection.end" } },
}),
- ));
- assert.deepEqual(program.items.map((item) => item.span), [{ startFrame: 30, endFrameExclusive: 60 }]);
+ );
+ assert.deepEqual(occurrence.span, { startFrame: 30, endFrameExclusive: 60 });
});
test("the self-described Markup Surfaces compile Style, Motion and all three spatial forms", async () => {
@@ -342,7 +294,7 @@ test("the self-described Markup Surfaces compile Style, Motion and all three spa
const closure = createResolvedClosure([
...videoContractManifests,
textManifest,
- typographyTrackManifest,
+ textFineManifest,
fixtureManifest,
]);
const surfaces = new MarkupSurfaceRegistry();
@@ -355,14 +307,8 @@ test("the self-described Markup Surfaces compile Style, Motion and all three spa
path: "text.editorial",
properties: {
- "stack-order": 70,
size: 44,
"line-height": 1.15,
- "inline-size": "fixed",
- "block-size": "fixed",
- wrap: "word",
- overflow: "shrink",
- "minimum-scale": 0.65,
},
} },
range: element.range,
@@ -374,13 +320,8 @@ test("the self-described Markup Surfaces compile Style, Motion and all three spa
path: "text.mask-editorial",
properties: {
- "stack-order": 75,
size: 100,
"line-height": 1,
- "inline-size": "fixed",
- "block-size": "fixed",
- wrap: "none",
- overflow: "visible",
},
} },
range: element.range,
@@ -399,14 +340,17 @@ test("the self-described Markup Surfaces compile Style, Motion and all three spa
components: [],
fragments: [],
}) });
- surfaces.registerStructured({ module: typographyTrackModuleRef, declaration: typographyTrackMarkupSurfaces.find((item) => item.name === "style")!, handler: decodeTypographyStyleSurface });
- surfaces.registerStructured({ module: typographyTrackModuleRef, declaration: typographyTrackMarkupSurfaces.find((item) => item.name === "motion")!, handler: decodeTypographyMotionSurface });
- surfaces.registerStructured({ module: typographyTrackModuleRef, declaration: typographyTrackMarkupSurfaces.find((item) => item.name === "track")!, handler: decodeTypographyTrackSurface });
- surfaces.registerStructured({ module: typographyTrackModuleRef, declaration: typographyTrackMarkupSurfaces.find((item) => item.name === "mask")!, handler: decodeTypographyMaskSurface });
+ surfaces.registerStructured({ module: textFineModuleRef, declaration: textFineMarkupSurfaces.find((item) => item.name === "style")!, handler: decodeTypographyStyleSurface });
+ surfaces.registerStructured({ module: textFineModuleRef, declaration: textFineMarkupSurfaces.find((item) => item.name === "motion")!, handler: decodeTypographyMotionSurface });
+ surfaces.registerStructured({ module: textFineModuleRef, declaration: textFineMarkupSurfaces.find((item) => item.name === "path-motion")!, handler: decodeTypographyPathMotionSurface });
+ surfaces.registerStructured({ module: textFineModuleRef, declaration: textFineMarkupSurfaces.find((item) => item.name === "flow")!, handler: decodeTypographyFlowSurface });
+ surfaces.registerStructured({ module: textFineModuleRef, declaration: textFineMarkupSurfaces.find((item) => item.name === "point")!, handler: decodeTypographyPointSurface });
+ surfaces.registerStructured({ module: textFineModuleRef, declaration: textFineMarkupSurfaces.find((item) => item.name === "path")!, handler: decodeTypographyPathSurface });
+ surfaces.registerStructured({ module: textFineModuleRef, declaration: textFineMarkupSurfaces.find((item) => item.name === "mask")!, handler: decodeTypographyMaskSurface });
const frontends = new AuthorFrontendRegistry();
frontends.register(createMarkupAuthorFrontend({
registry: surfaces,
- resolveModule: (request) => request.from === "example.text-inputs@1" ? fixtureModule : typographyTrackModuleRef,
+ resolveModule: (request) => request.from === "example.text-inputs@1" ? fixtureModule : textFineModuleRef,
}));
const validators = new TypeValidatorRegistry();
registerTypeValidatorFacets(validators, spatialComponent.validators ?? []);
@@ -418,7 +362,7 @@ test("the self-described Markup Surfaces compile Style, Motion and all three spa
text: `<?svml using="@hypit/markup@1"?>
<svml>
<import as="fixture" from="example.text-inputs@1"/>
- <import as="text" from="@hypit/typography-track@1"/>
+ <import as="text" from="@hypit/text-fine@1"/>
<fixture:Inputs/>
<text:Style id="poster" recipe={editorial} font={exact-font}>
<text:Fill color="#f8fafc"/>
@@ -436,17 +380,24 @@ test("the self-described Markup Surfaces compile Style, Motion and all three spa
<text:Keyframe at="1" opacity="1"/>
</text:Sequence>
</text:Motion>
- <text:Track id="titles" timeline={semantic}>
- <text:Point id="hook" content={copy} placement={title-point} style={poster} during="program"/>
- <text:Area id="body" placement={body-frame} style={poster} motion={arrive} during="program">
- <text:P id="first">Rich <text:Span style={poster}>inline text</text:Span><text:Break/>wraps.</text:P>
- </text:Area>
- <text:Path id="arc-title" placement={arc} style={poster} during="program">Along the path</text:Path>
- </text:Track>
- <text:Track id="mask-shape" timeline={semantic}>
- <text:Area id="mask-word" placement={body-frame} style={mask-shape-style} during="program">MASK</text:Area>
- </text:Track>
- <text:Mask id="masked-titles" timeline={semantic} text={mask-shape.program} material={material}/>
+ <text:PathMotion id="orbit-travel">
+ <text:Keyframe at="0" margin="0"/>
+ <text:Keyframe at="150" margin="120" easing="ease-in-out"/>
+ </text:PathMotion>
+ <text:Flow id="standalone-flow" timeline={semantic} within={body-frame} style={poster} z="70" overflow="shrink" minimum-scale="0.65" during="timeline">
+ Independent flow
+ </text:Flow>
+ <text:Point id="standalone-point" timeline={semantic} point={title-point} style={poster} z="70" content={copy} from="1s" for="30f"/>
+ <text:Path id="standalone-path" timeline={semantic} path={arc} style={poster} z="70" motion={arrive} path-motion={orbit-travel} from="0f" until="150f">
+ Independent path
+ </text:Path>
+ <text:Point id="hook" timeline={semantic} content={copy} point={title-point} style={poster} z="70" during="timeline"/>
+ <text:Flow id="body" timeline={semantic} within={body-frame} style={poster} z="70" overflow="shrink" minimum-scale="0.65" motion={arrive} during="timeline">
+ <text:P id="first">Rich <text:Span style={poster}>inline text</text:Span><text:Break/>wraps.</text:P>
+ </text:Flow>
+ <text:Path id="arc-title" timeline={semantic} path={arc} style={poster} z="70" during="timeline">Along the path</text:Path>
+ <text:Flow id="mask-shape" timeline={semantic} within={body-frame} style={mask-shape-style} z="75" wrap="none" during="timeline">MASK</text:Flow>
+ <text:Mask id="masked-titles" timeline={semantic} text={mask-shape.occurrence} material={material}/>
</svml>`,
},
closure,
@@ -454,28 +405,57 @@ test("the self-described Markup Surfaces compile Style, Motion and all three spa
admitRecord: createRecordAdmitter(validators),
resolveSource() { throw new Error("Text fixture has no source imports."); },
});
- const program = resolveCompiledSourceExport(compiled, "mask-shape.program", typographyTrackTypes.program);
- const ordinaryTrack = resolveCompiledSourceExport(compiled, "titles.track", compositionTypes.visualTrack);
- const track = resolveCompiledSourceExport(compiled, "masked-titles.track", compositionTypes.visualTrack);
- assert.equal(program.ref.kind, "logical-output");
- assert.equal(ordinaryTrack.ref.kind, "logical-output");
+ const maskOccurrence = resolveCompiledSourceExport(compiled, "mask-shape.occurrence", textFineTypes.occurrence);
+ const flowOccurrence = resolveCompiledSourceExport(compiled, "standalone-flow.occurrence", textFineTypes.occurrence);
+ const flowVisual = resolveCompiledSourceExport(compiled, "standalone-flow.visual", compositionTypes.visualTrack);
+ const pointVisual = resolveCompiledSourceExport(compiled, "standalone-point.visual", compositionTypes.visualTrack);
+ const pathVisual = resolveCompiledSourceExport(compiled, "standalone-path.visual", compositionTypes.visualTrack);
+ const track = resolveCompiledSourceExport(compiled, "masked-titles.visual", compositionTypes.visualTrack);
+ assert.equal(maskOccurrence.ref.kind, "logical-output");
+ assert.equal(flowOccurrence.ref.kind, "logical-output");
+ assert.equal(flowVisual.ref.kind, "logical-output");
+ assert.equal(pointVisual.ref.kind, "logical-output");
+ assert.equal(pathVisual.ref.kind, "logical-output");
assert.equal(track.ref.kind, "logical-output");
+ const occurrenceBuild = start(compiled.program, compiled.graph, sealBuildRequest({
+ targets: [flowVisual, pointVisual, pathVisual].map((value) => ({
+ output: value.ref.kind === "logical-output" ? value.ref.id : "",
+ })),
+ }));
+ const occurrenceProducers = occurrenceBuild.plan.steps.map((step) => step.producer.name);
+ assert.equal(occurrenceProducers.filter((name) => name === textFineProducers.createOccurrence.name).length, 3);
+ assert.equal(occurrenceProducers.filter((name) => name === textFineProducers.renderOccurrence.name).length, 3);
+ assert.equal(occurrenceProducers.includes("create-text-fine-set"), false);
+ assert.equal(occurrenceProducers.includes("append-text-item"), false);
+ assert.equal(occurrenceProducers.includes("finalize-text-fine"), false);
const build = start(compiled.program, compiled.graph, sealBuildRequest({
- targets: [
- { output: ordinaryTrack.ref.kind === "logical-output" ? ordinaryTrack.ref.id : "" },
- { output: track.ref.kind === "logical-output" ? track.ref.id : "" },
- ],
+ targets: [{ output: track.ref.kind === "logical-output" ? track.ref.id : "" }],
}));
const producers = build.plan.steps.map((step) => step.producer.name);
- assert.equal(producers.filter((name) => name === typographyTrackProducers.bindPoint.name).length, 1);
- assert.equal(producers.filter((name) => name === typographyTrackProducers.bindArea.name).length, 2);
- assert.equal(producers.filter((name) => name === typographyTrackProducers.bindPath.name).length, 1);
- assert.equal(producers.filter((name) => name === typographyTrackProducers.render.name).length, 1);
- assert.equal(producers.filter((name) => name === typographyTrackProducers.renderMask.name).length, 1);
+ assert.equal(producers.filter((name) => name === textFineProducers.bindArea.name).length, 1);
+ assert.equal(producers.filter((name) => name === textFineProducers.renderOccurrenceMask.name).length, 1);
+});
+
+test("fine Text occurrences expose only absolute timing vocabulary", () => {
+ for (const name of ["flow", "point", "path"] as const) {
+ const surface = textFineMarkupSurfaces.find((item) => item.name === name);
+ assert.ok(surface);
+ const attributes: readonly string[] = surface.vocabulary.attributes.map((attribute) => attribute.name);
+ assert.equal(attributes.includes("semantic"), false);
+ assert.equal(attributes.includes("selection"), false);
+ assert.equal(attributes.includes("segment"), false);
+ assert.equal(attributes.includes("moment"), false);
+ assert.deepEqual(attributes.filter((attribute) => ["during", "from", "until", "for"].includes(attribute)),
+ ["during", "from", "until", "for"]);
+ }
+ const mask = textFineMarkupSurfaces.find((item) => item.name === "mask");
+ assert.ok(mask);
+ const maskAttributes: readonly string[] = mask.vocabulary.attributes.map((attribute) => attribute.name);
+ assert.equal(maskAttributes.includes("semantic"), false);
});
test("rich Text lowers ordered glyph layers, boxes, bounded flow, sequences and Path Text", () => {
- const base = textStyle("rich", 75);
+ const base = textStyle("rich");
const rich = sealTextStyle({
...base,
typography: {
@@ -518,7 +498,6 @@ test("rich Text lowers ordered glyph layers, boxes, bounded flow, sequences and
},
},
],
- area: { ...base.area, overflow: "shrink", maxLines: 3, minimumScale: 0.6 },
});
const pathStyle = sealTextStyle({
...base,
@@ -554,18 +533,16 @@ test("rich Text lowers ordered glyph layers, boxes, bounded flow, sequences and
},
],
});
- const pathMotion = sealTextMotion({
- id: "path-motion", sequences: [],
- pathMargin: { keyframes: [{ atFrame: 0, startMarginPx: 0 }, { atFrame: 180, startMarginPx: 120, easing: "ease-in-out" }] },
+ const pathMotion = sealTextPathMotion({
+ id: "path-motion",
+ keyframes: [{ atFrame: 0, startMarginPx: 0 }, { atFrame: 180, startMarginPx: 120, easing: "ease-in-out" }],
});
- const track = renderTypographyTrack(space, sealTypographyTrackProgram({
-
- id: "rich-text",
- items: [
- {
- id: "area", span: { startFrame: 0, endFrameExclusive: 150 }, tieBreak: "area",
- geometry: { kind: "area", frame: { xPx: 80, yPx: 200, widthPx: 720, heightPx: 320 } },
- document: { paragraphs: [{
+ const area = createFineTextOccurrence(
+ space,
+ bindAreaTextPlacement({ xPx: 80, yPx: 200, widthPx: 720, heightPx: 320 }, flowPolicy(75, { overflow: "shrink", maxLines: 3, minimumScale: 0.6 })),
+ sealTextItemSpec({
+ id: "area",
+ document: { paragraphs: [{
id: "p1",
inlines: [
{ kind: "text", id: "latin", text: "Intent stays " },
@@ -574,24 +551,21 @@ test("rich Text lowers ordered glyph layers, boxes, bounded flow, sequences and
{ kind: "text", id: "rtl", text: "مرحبا 👩🏽‍💻 e\u0301", language: "ar", direction: "rtl" },
],
}] },
- style: rich,
- motion,
- },
- {
- id: "path", span: { startFrame: 0, endFrameExclusive: 150 }, tieBreak: "path",
- geometry: { kind: "path", path: { commands: [
- { kind: "move", xPx: 100, yPx: 700 },
- { kind: "quadratic", controlX: 540, controlY: 520, xPx: 980, yPx: 700 },
- ] } },
- document: document("Renderer-neutral Path Text"),
- style: pathStyle,
- motion: pathMotion,
- },
- ],
- }));
+ }),
+ rich, motion, absoluteWindow("area", 0, 150),
+ );
+ const path = createFineTextOccurrence(
+ space,
+ bindPathTextPlacement({ commands: [
+ { kind: "move", xPx: 100, yPx: 700 },
+ { kind: "quadratic", controlX: 540, controlY: 520, xPx: 980, yPx: 700 },
+ ] }, pathPolicy(75), pathMotion),
+ sealTextItemSpec({ id: "path", document: document("Renderer-neutral Path Text") }),
+ pathStyle, stillTextMotion("path-still"), absoluteWindow("path", 0, 150),
+ );
const rendered = compileHyperframesDocument(sealComposition({
- id: "rich-text-film",
- canvas: { width: 1080, height: 900, clearColor: "#000000" }, tracks: [track],
+ id: "rich-text-film", canvas: { width: 1080, height: 900, clearColor: "#000000" },
+ tracks: [renderFineTextOccurrence(space, area), renderFineTextOccurrence(space, path)],
}), space);
assert.match(rendered.html, /data-hypit-text-paint-layer="5"/u);
assert.match(rendered.html, /feMorphology/u);
@@ -619,14 +593,13 @@ test("a paragraph's source indentation is not part of its words", async () => {
types: [], capabilities: [], producers: [],
};
const closure = createResolvedClosure([
- ...videoContractManifests, textManifest, typographyTrackManifest, fixtureManifest,
+ ...videoContractManifests, textManifest, textFineManifest, fixtureManifest,
]);
const surfaces = new MarkupSurfaceRegistry();
surfaces.registerStructured({ module: fixtureModule, declaration: fixtureSurface, handler: ({ element }) => ({
records: [
{ id: "editorial", type: svsRecipeType, value: { kind: "inline", value: {
- path: "text.editorial", properties: { "stack-order": 70, size: 44, "line-height": 1.15,
- "inline-size": "fixed", "block-size": "fixed", wrap: "word", overflow: "shrink", "minimum-scale": 0.65 } } },
+ path: "text.editorial", properties: { size: 44, "line-height": 1.15 } } },
range: element.range },
{ id: "semantic", type: timelineTypes.track, value: { kind: "inline", value: semantic }, range: element.range },
{ id: "body-frame", type: spatialTypes.frame, value: { kind: "inline", value: { xPx: 80, yPx: 220, widthPx: 920, heightPx: 520 } }, range: element.range },
@@ -634,12 +607,12 @@ test("a paragraph's source indentation is not part of its words", async () => {
],
components: [], fragments: [],
}) });
- surfaces.registerStructured({ module: typographyTrackModuleRef, declaration: typographyTrackMarkupSurfaces.find((item) => item.name === "style")!, handler: decodeTypographyStyleSurface });
- surfaces.registerStructured({ module: typographyTrackModuleRef, declaration: typographyTrackMarkupSurfaces.find((item) => item.name === "track")!, handler: decodeTypographyTrackSurface });
+ surfaces.registerStructured({ module: textFineModuleRef, declaration: textFineMarkupSurfaces.find((item) => item.name === "style")!, handler: decodeTypographyStyleSurface });
+ surfaces.registerStructured({ module: textFineModuleRef, declaration: textFineMarkupSurfaces.find((item) => item.name === "flow")!, handler: decodeTypographyFlowSurface });
const frontends = new AuthorFrontendRegistry();
frontends.register(createMarkupAuthorFrontend({
registry: surfaces,
- resolveModule: (request) => request.from === "example.text-inputs@1" ? fixtureModule : typographyTrackModuleRef,
+ resolveModule: (request) => request.from === "example.text-inputs@1" ? fixtureModule : textFineModuleRef,
}));
const validators = new TypeValidatorRegistry();
registerTypeValidatorFacets(validators, spatialComponent.validators ?? []);
@@ -650,26 +623,24 @@ test("a paragraph's source indentation is not part of its words", async () => {
text: `<?svml using="@hypit/markup@1"?>
<svml>
<import as="fixture" from="example.text-inputs@1"/>
- <import as="text" from="@hypit/typography-track@1"/>
+ <import as="text" from="@hypit/text-fine@1"/>
<fixture:Inputs/>
<text:Style id="poster" recipe={editorial} font={exact-font}>
<text:Fill color="#f8fafc"/>
</text:Style>
- <text:Track id="titles" timeline={semantic}>
- <text:Area id="body" placement={body-frame} style={poster} during="program">
- <text:P id="first">
- Top 5 Most Popular
- Ways to <text:Span style={poster}>learn AI</text:Span>
- </text:P>
- </text:Area>
- </text:Track>
+ <text:Flow id="body" timeline={semantic} within={body-frame} style={poster} z="70" overflow="shrink" minimum-scale="0.65" during="timeline">
+ <text:P id="first">
+ Top 5 Most Popular
+ Ways to <text:Span style={poster}>learn AI</text:Span>
+ </text:P>
+ </text:Flow>
</svml>`,
},
closure, frontends,
admitRecord: createRecordAdmitter(validators),
resolveSource() { throw new Error("Text fixture has no source imports."); },
});
- const track = resolveCompiledSourceExport(compiled, "titles.track", compositionTypes.visualTrack);
+ const track = resolveCompiledSourceExport(compiled, "body.visual", compositionTypes.visualTrack);
assert.equal(track.ref.kind, "logical-output");
// The paragraph's words are the copy, not the indentation the file put around it.
const runs: unknown[] = [];
diff --git a/packages/text/README.md b/packages/text/README.md
index f654cbb0..b455b63a 100644
--- a/packages/text/README.md
+++ b/packages/text/README.md
@@ -37,7 +37,7 @@ such as model or resolution are ignored by the text program. No prompt-specific
needed.
`@hypit/markup` is the XML-like authoring Frontend and
-`@hypit/typography-track` renders text into video. They are deliberately
+`@hypit/text-fine` renders text into video. They are deliberately
separate packages.
## Graph consumers
@@ -45,7 +45,7 @@ separate packages.
`Text` is a small domain-neutral graph value, not a prompt-only type. Current consumers include:
- exact model prompt ports;
-- `@hypit/typography-track` Point, Area and Path content;
+- `@hypit/text-fine` Point, Flow and Path occurrence content;
- Ranking Column/TopThree labels;
- Comment Sticker comment, author, header and metadata copy;
- Deck Card labels.
diff --git a/packages/timeline-author/README.md b/packages/timeline-author/README.md
index 66d85e19..7cbc461f 100644
--- a/packages/timeline-author/README.md
+++ b/packages/timeline-author/README.md
@@ -1,68 +1,125 @@
# `@hypit/timeline-author`
-Declare one complete Timeline and place prepared Takes within it. Spoken work, mixed spoken/MG
-work and pure authored animation use the same declaration. The separate
-[Timeline value package](../timeline/README.md) owns the data and projections; this author package
-owns the markup and deterministic assembly.
+Construct one finite absolute Timeline from a small acyclic graph of named Instants and Windows.
+This package owns author syntax and lowering; [`@hypit/timeline`](../timeline/README.md) owns only the
+completed value `{ id, frameRate, frameCount }`.
+
+Timeline is not a media Track, clip list, semantic anchor registry or hidden schedule. Its author
+graph does only two jobs:
+
+1. resolve the program's exclusive `end`; and
+2. publish deliberately named absolute Instants and Windows for other graph nodes to consume.
```svml
<import as="time" from="@hypit/timeline-author@1"/>
+
<time:Clock id="clock" frame-rate="30"/>
-<time:Timeline id="program" clock={clock} end="content.end+2s">
- <time:Take source={opening.take} at="2s"/>
- <time:Take source={explanation.take} at="previous.end+3s"/>
- <time:Take source={closing.take} at="previous.end-12f"/>
+<time:Timeline id="program" clock={clock}
+ end="latest(speech.end,outro.end)">
+ <time:Window id="speech" from="start" for={voice.extent}/>
+ <time:Instant id="claim" at="speech.end-12f"/>
+ <time:Window id="outro" from="claim" for="3s"/>
</time:Timeline>
```
-The first Take begins at two seconds. The second starts three seconds after the preceding Take ends.
-The third overlaps its predecessor by twelve frames. The complete Timeline ends two seconds after
-all Takes have ended. Durations come from prepared material, so authoring these relations does not
-require knowing generated lengths beforehand or serializing generation.
+The Timeline declaration publishes:
-| Declaration | Meaning |
-| --- | --- |
-| `clock={clock}` | Required frame-rate input, also usable by upstream normalization. |
-| Take `source={clip.take}` | Complete normalized, semantically prepared local Take. A wordless Take is valid real media. |
-| First omitted `at` | `0f`. |
-| Later omitted `at` | `previous.end`. |
-| `at="20s"` | Absolute start. |
-| `at="previous.end+2s"` | Start relative to the preceding Take declaration's end. Negative offsets permit overlap. |
-| Omitted `end` | `content.end`, the maximum end across all placed Takes. |
-| `end="content.end+2s"` | Reserve a trailing interval after all Takes finish. |
-| `end="30s"` | Fixed complete extent, including every placed Take. |
-
-Positions and offsets accept seconds, milliseconds and frames, and must resolve to exact frame
-boundaries on the Clock. Negative placements, a missing predecessor, or a fixed end shorter than
-placed content produce an error. A positive predecessor offset does not promise globally empty
-time if another long Take remains active. Placement is translation at native speed; trimming or
-retiming material belongs before its semantic preparation.
-
-For ordinary sequential assembly, omit all Take `at` attributes and Timeline `end`. For wholly
-authored animation, supply the extent and no Takes:
+- `program.timeline`, the completed Timeline;
+- `program.window`, `program.start` and `program.end` for the complete range;
+- `program.speech`, plus `program.speech.start` and `program.speech.end`;
+- `program.claim`; and
+- `program.outro`, plus its boundaries.
+
+Every named child is naturally addressable. There is no author-facing `export` attribute. Internal
+construction points, spans and extents are compiler values and never become another public time
+model.
+
+## Timeline declarations
+
+| Form | Meaning | Published value |
+| --- | --- | --- |
+| `<time:Instant id="cue" at="…"/>` | Names one absolute boundary relationship. | `program.cue` |
+| `<time:Window id="tail" from="…" for="2s"/>` | Names one non-empty absolute interval relationship. | `program.tail`, `.start`, `.end` |
+
+A Window supplies exactly two of `from`, `until` and `for`. `for` accepts either an exact duration
+literal or a typed `TemporalExtent`. This gives forward placement, end alignment and intervals
+between existing boundaries without separate Block, Before, After or Place primitives:
```svml
-<time:Timeline id="animation" clock={clock} end="30s"/>
+<time:Timeline id="film" clock={clock} end="latest(voice.end,tail.end)">
+ <time:Window id="voice" from="start" for={voice-media.extent}/>
+ <time:Window id="last-three" until="end" for="3s"/>
+ <time:Window id="tail" from="voice.end" until="voice.end+3s"/>
+</time:Timeline>
```
-This produces no blank video or fabricated Script. Empty content cannot supply an implicit positive
-extent. Program boundaries remain available for MG, media, titles and sound.
+## Point expressions
-| Output | Use |
+`Instant.at`, Window boundaries and the required Timeline `end` share one restricted expression
+grammar:
+
+| Expression | Meaning |
| --- | --- |
-| `.timeline` | Complete time range and placed material/evidence, consumed through `timeline={program.timeline}`. |
-
-[Performance](../performance/README.md) presents footage already
-held by the Timeline. It can show it full-frame, in an inset or as a cutout; project components can
-own coordinated video and graphics. Sampling a new presentation Window preserves each Take's source
-position. Overlap supplies multiple sources, not an automatic dissolve. Independent Media Items
-still receive their own assets and may coexist. Caption reads the authored words and placed timing.
-
-[Sound](../sound/README.md) presents existing Timeline audio through ordered Uses.
-[Audio Track](../audio-track/README.md) handles independent music and effects. Include the wanted
-presentation outputs explicitly in Film. Timeline itself exports only `.timeline`; holding material
-does not add a picture or sound contribution.
-
-Timeline placement is authored with `at` and `end`. Studio shows placed Takes and the complete range
-as reference information. Use-window and Script-marker controls edit presentation timing and semantic
-anchors respectively; they do not move Takes or change the Timeline extent.
+| `start` | frame boundary zero |
+| `12f`, `250ms`, `1.5s` | absolute position from zero |
+| `speech.start`, `speech.end` | boundary of a named Window |
+| `claim` | a named Instant |
+| `claim+2s`, `speech.end-12f` | exact literal offset |
+| `earliest(a,b)`, `latest(a,b,c)` | earliest or latest of named boundaries |
+
+Declarations may refer forward. Source order is not execution order; dependencies determine graph
+evaluation. `end` may also be referenced by a Window such as `last-three`. If `end` then depends on
+that same Window, the author graph contains a real cycle and is rejected. Unknown references,
+non-positive Timeline ends, non-exact frame durations, empty Windows and values outside the final
+range are errors.
+
+The graph may have several roots, branches and leaves. It needs no clip ordering or single content
+root; it needs one resolvable `end`.
+
+## Unknown generated duration
+
+`TemporalExtent` is an unpositioned frame count on one frame rate. Normalization publishes it only
+after an imported or generated asset is available. A Timeline Window can consume that ordinary graph
+value, so an unknown voice or video length may determine later boundaries and the final `end` without
+a phase state machine, callback or second Source run:
+
+```svml
+<time:Timeline id="film" clock={clock} end="outro.end">
+ <time:Window id="voice" from="start" for={voice-media.extent}/>
+ <time:Window id="outro" from="voice.end" for="3s"/>
+</time:Timeline>
+```
+
+If generation itself requests this Timeline's end while the end depends on the generated result,
+that is a genuine dependency cycle rather than a scheduling problem.
+
+## Local domains contribute, then disappear
+
+A prepared source may supply the `TemporalExtent` that determines a Window. That is its complete
+relationship with Timeline construction. The Timeline does not retain the source, its local domain,
+or a public Placement object.
+
+When a domain package must project local evidence, it consumes the complete local domain and the
+equal-length Window directly. The relation is exact native-speed translation: local frame zero maps
+to the Window start and the local exclusive end maps to the Window end. A length mismatch is an error;
+projection does not clip, loop, hold, stretch, resample or hide a source tail. The projector publishes
+ordinary absolute Instants and Windows and erases the construction relation. Visual and Audio then
+place ordinary normalized media independently.
+
+A one-off component Window can still be authored directly on that component or supplied by another
+domain projection. Put a named child in Timeline when it participates in the construction DAG. When
+the Timeline is already complete and several consumers deliberately share a newly composed absolute
+range, publish it independently:
+
+```svml
+<time:Window id="reveal-band" timeline={film.timeline}
+ from={story-time.reveal} until={story-time.answer-end}/>
+<time:Instant id="credits" timeline={film.timeline} at="timeline.end-2s"/>
+
+<visual:Clip during={reveal-band} .../>
+```
+
+The standalone Window publishes `reveal-band`, `reveal-band.start` and `reveal-band.end`. A standalone
+Instant authors an absolute expression; an already resolved Instant needs no renaming and should be
+referenced directly. Absolute value Types are the common waist; Timeline and Narrative projection are
+only two possible producers of them.
diff --git a/packages/timeline-author/package.json b/packages/timeline-author/package.json
index fc5702cc..9ff3bd59 100644
--- a/packages/timeline-author/package.json
+++ b/packages/timeline-author/package.json
@@ -14,10 +14,8 @@
"@hypit/component-kit": "workspace:*",
"@hypit/elaborator": "workspace:*",
"@hypit/protocol": "workspace:*",
- "@hypit/speech": "workspace:*",
"@hypit/timeline": "workspace:*",
"@hypit/markup": "workspace:*",
- "@hypit/program-space": "workspace:*",
"@hypit/temporal": "workspace:*",
"@hypit/temporal-markup": "workspace:*"
},
diff --git a/packages/timeline-author/src/activation.ts b/packages/timeline-author/src/activation.ts
index 8d4f3a9f..ad7c855d 100644
--- a/packages/timeline-author/src/activation.ts
+++ b/packages/timeline-author/src/activation.ts
@@ -1,7 +1,6 @@
-import { decodeClockSurface } from "@hypit/program-space";
import { createMarkupSurfaceHostFacet } from "@hypit/markup";
import {
- decodeTimelineAuthorSurface, timelineAuthorComponent, timelineAuthorManifest,
+ decodeAbsoluteInstantSurface, decodeAbsoluteWindowSurface, decodeClockSurface, decodeTimelineAuthorSurface, timelineAuthorComponent, timelineAuthorManifest,
timelineAuthorModuleRef,
timelineAuthorMarkupSurfaces,
} from "./index.js";
@@ -17,6 +16,10 @@ export const hypitPackage = {
declaration: timelineAuthorMarkupSurfaces.find((item) => item.name === "timeline")!, handler: decodeTimelineAuthorSurface,
}), createMarkupSurfaceHostFacet({ module: timelineAuthorModuleRef,
declaration: timelineAuthorMarkupSurfaces.find(item => item.name === "clock")!, handler: decodeClockSurface,
+ }), createMarkupSurfaceHostFacet({ module: timelineAuthorModuleRef,
+ declaration: timelineAuthorMarkupSurfaces.find(item => item.name === "window")!, handler: decodeAbsoluteWindowSurface,
+ }), createMarkupSurfaceHostFacet({ module: timelineAuthorModuleRef,
+ declaration: timelineAuthorMarkupSurfaces.find(item => item.name === "instant")!, handler: decodeAbsoluteInstantSurface,
})],
};
export default hypitPackage;
diff --git a/packages/timeline-author/src/component.ts b/packages/timeline-author/src/component.ts
index 784238fa..97ee1841 100644
--- a/packages/timeline-author/src/component.ts
+++ b/packages/timeline-author/src/component.ts
@@ -1,47 +1,43 @@
-import type { ProgramClock } from "@hypit/program-space";
import type { ComponentPackage } from "@hypit/component-kit";
-import type { StoredValue } from "@hypit/protocol";
import { canonicalize } from "@hypit/protocol";
-import type { SemanticTake } from "@hypit/speech";
+import type { StoredValue } from "@hypit/protocol";
+import type { LocalTemporalDomain, TemporalDuration, TemporalExtent, TemporalWindow } from "@hypit/temporal";
+import type { Clock, Timeline } from "@hypit/timeline";
import { timelineAuthorProducers } from "./manifest.js";
-import { appendTimelineAuthorTake, assembleTimelineAuthor, createTimelineAuthorSet } from "./program.js";
-import type { TimelineAuthorHeader, TimelineAuthorSet } from "./types.js";
+import {
+ constructionAliasPoint, constructionDuration, constructionEarliest, constructionLatest, constructionOffset,
+ constructionOrigin, constructionResolvedExtent, constructionSpan, constructionSpanBetween,
+ constructionSpanEnd, constructionSpanEnding, constructionSpanStart,
+ finalizeTimeline, materializeInstant, materializeWindow,
+} from "./program.js";
+import type {
+ ConstructionExtent, ConstructionIdentitySpec, ConstructionOffsetSpec,
+ ConstructionPoint, ConstructionSpan, TimelineAuthorHeader,
+} from "./types.js";
function inline<T>(value: StoredValue | undefined, subject: string): T {
- if (value?.kind !== "inline") throw new Error(`${subject} must be inline`);
+ if (value?.kind !== "inline") throw new Error(`${subject} must be inline.`);
return value.value as unknown as T;
}
+const output = (value: unknown) => ({ kind: "inline" as const, value: canonicalize(value) });
export const timelineAuthorComponent = {
producers: [
- {
- producer: timelineAuthorProducers.createSet,
- handler: () => ({
- outputs: { set: { kind: "inline", value: canonicalize(createTimelineAuthorSet()) } },
- needs: {},
- }),
- },
- {
- producer: timelineAuthorProducers.appendTake,
- handler: ({ inputs }) => ({
- outputs: { set: { kind: "inline", value: canonicalize(appendTimelineAuthorTake(
- inline<TimelineAuthorSet>(inputs.set?.value, "TimelineAuthorSet"),
- inline<SemanticTake>(inputs.take?.value, "SemanticTake"),
- )) } },
- needs: {},
- }),
- },
- {
- producer: timelineAuthorProducers.assembleTrack,
- handler: ({ inputs }) => ({
- outputs: { track: { kind: "inline", value: canonicalize(assembleTimelineAuthor(
- inline<TimelineAuthorHeader>(inputs.header?.value, "TimelineAuthorHeader"),
- inline<TimelineAuthorSet>(inputs.set?.value, "TimelineAuthorSet"),
- inline<ProgramClock>(inputs.clock?.value, "ProgramClock"),
- )) } },
- needs: {},
- }),
- },
+ { producer: timelineAuthorProducers.origin, handler: ({ inputs }) => ({ outputs: { point: output(constructionOrigin(inline<Clock>(inputs.clock?.value, "Clock"))) }, needs: {} }) },
+ { producer: timelineAuthorProducers.duration, handler: ({ inputs }) => ({ outputs: { extent: output(constructionDuration(inline<Clock>(inputs.clock?.value, "Clock"), inline<TemporalDuration>(inputs.duration?.value, "ConstructionDurationSpec"))) }, needs: {} }) },
+ { producer: timelineAuthorProducers.resolvedExtent, handler: ({ inputs }) => ({ outputs: { extent: output(constructionResolvedExtent(inline<Clock>(inputs.clock?.value, "Clock"), inline<TemporalExtent>(inputs.extent?.value, "TemporalExtent"))) }, needs: {} }) },
+ { producer: timelineAuthorProducers.offset, handler: ({ inputs }) => ({ outputs: { point: output(constructionOffset(inline<ConstructionPoint>(inputs.point?.value, "ConstructionPoint"), inline<ConstructionExtent>(inputs.extent?.value, "ConstructionExtent"), inline<ConstructionOffsetSpec>(inputs.spec?.value, "ConstructionOffsetSpec"))) }, needs: {} }) },
+ { producer: timelineAuthorProducers.earliest, handler: ({ inputs }) => ({ outputs: { point: output(constructionEarliest(inline<ConstructionPoint>(inputs.left?.value, "ConstructionPoint"), inline<ConstructionPoint>(inputs.right?.value, "ConstructionPoint"))) }, needs: {} }) },
+ { producer: timelineAuthorProducers.latest, handler: ({ inputs }) => ({ outputs: { point: output(constructionLatest(inline<ConstructionPoint>(inputs.left?.value, "ConstructionPoint"), inline<ConstructionPoint>(inputs.right?.value, "ConstructionPoint"))) }, needs: {} }) },
+ { producer: timelineAuthorProducers.aliasPoint, handler: ({ inputs }) => ({ outputs: { point: output(constructionAliasPoint(inline<ConstructionPoint>(inputs.point?.value, "ConstructionPoint"))) }, needs: {} }) },
+ { producer: timelineAuthorProducers.span, handler: ({ inputs }) => ({ outputs: { span: output(constructionSpan(inline<ConstructionPoint>(inputs.start?.value, "ConstructionPoint"), inline<ConstructionExtent>(inputs.extent?.value, "ConstructionExtent"))) }, needs: {} }) },
+ { producer: timelineAuthorProducers.spanEnding, handler: ({ inputs }) => ({ outputs: { span: output(constructionSpanEnding(inline<ConstructionPoint>(inputs.end?.value, "ConstructionPoint"), inline<ConstructionExtent>(inputs.extent?.value, "ConstructionExtent"))) }, needs: {} }) },
+ { producer: timelineAuthorProducers.spanBetween, handler: ({ inputs }) => ({ outputs: { span: output(constructionSpanBetween(inline<ConstructionPoint>(inputs.start?.value, "ConstructionPoint"), inline<ConstructionPoint>(inputs.end?.value, "ConstructionPoint"))) }, needs: {} }) },
+ { producer: timelineAuthorProducers.spanStart, handler: ({ inputs }) => ({ outputs: { point: output(constructionSpanStart(inline<ConstructionSpan>(inputs.span?.value, "ConstructionSpan"))) }, needs: {} }) },
+ { producer: timelineAuthorProducers.spanEnd, handler: ({ inputs }) => ({ outputs: { point: output(constructionSpanEnd(inline<ConstructionSpan>(inputs.span?.value, "ConstructionSpan"))) }, needs: {} }) },
+ { producer: timelineAuthorProducers.finalize, handler: ({ inputs }) => ({ outputs: { timeline: output(finalizeTimeline(inline<TimelineAuthorHeader>(inputs.header?.value, "TimelineAuthorHeader"), inline<Clock>(inputs.clock?.value, "Clock"), inline<ConstructionPoint>(inputs.end?.value, "ConstructionPoint"))) }, needs: {} }) },
+ { producer: timelineAuthorProducers.instant, handler: ({ inputs }) => ({ outputs: { instant: output(materializeInstant(inline<Timeline>(inputs.timeline?.value, "Timeline"), inline<ConstructionPoint>(inputs.point?.value, "ConstructionPoint"), inline<ConstructionIdentitySpec>(inputs.spec?.value, "ConstructionIdentitySpec"))) }, needs: {} }) },
+ { producer: timelineAuthorProducers.window, handler: ({ inputs }) => ({ outputs: { window: output(materializeWindow(inline<Timeline>(inputs.timeline?.value, "Timeline"), inline<ConstructionSpan>(inputs.span?.value, "ConstructionSpan"), inline<ConstructionIdentitySpec>(inputs.spec?.value, "ConstructionIdentitySpec"))) }, needs: {} }) },
],
} satisfies ComponentPackage;
diff --git a/packages/timeline-author/src/fragment.ts b/packages/timeline-author/src/fragment.ts
index 10c6caaa..9a2c8edb 100644
--- a/packages/timeline-author/src/fragment.ts
+++ b/packages/timeline-author/src/fragment.ts
@@ -1,65 +1,274 @@
-import { programSpaceTypes } from "@hypit/program-space";
-import { speechTypes } from "@hypit/speech";
import { sealGraphFragment } from "@hypit/elaborator";
-import type { FragmentOperation } from "@hypit/elaborator";
-import { timelineTypes } from "@hypit/timeline";
+import type { FragmentOperation, FragmentOperationRef, GraphFragment } from "@hypit/elaborator";
import type { TypeRef } from "@hypit/protocol";
+import { temporalTypes } from "@hypit/temporal";
+import type { TemporalDuration } from "@hypit/temporal";
+import { timelineTypes } from "@hypit/timeline";
import { timelineAuthorProducers, timelineAuthorTypes } from "./manifest.js";
-import type { TimelineAuthorFragmentOptions } from "./types.js";
+import type { TimelineAuthorDeclaration, TimelineAuthorFragmentOptions } from "./types.js";
const input = (name: string) => ({ kind: "fragment-input" as const, name });
-const operation = (id: string) => ({ kind: "fragment-operation" as const, operation: id });
-
-export function createTimelineAuthorFragment(options: TimelineAuthorFragmentOptions) {
- const declaredInputs = new Map<string, TypeRef>();
- const addInput = (name: string, type: TypeRef): void => {
- if (!name) throw new Error("Timeline Fragment input names must not be empty");
- const previous = declaredInputs.get(name);
- if (previous !== undefined && (previous.module.name !== type.module.name
- || previous.module.version !== type.module.version || previous.name !== type.name)) {
- throw new Error(`Timeline Fragment input ${name} is reused with another Type`);
+const operation = (id: string): FragmentOperationRef => ({ kind: "fragment-operation", operation: id });
+
+export type TimelineAuthorInlineInput = {
+ readonly name: string;
+ readonly type: TypeRef;
+ readonly value: unknown;
+};
+
+export type TimelineAuthorFragmentPlan = {
+ readonly fragment: GraphFragment;
+ readonly inlineInputs: readonly TimelineAuthorInlineInput[];
+ readonly extentInputs: readonly { readonly name: string; readonly declarationId: string }[];
+ readonly outputNames: readonly { readonly port: string; readonly suffix: string }[];
+};
+
+function assert(condition: unknown, message: string): asserts condition {
+ if (!condition) throw new Error(message);
+}
+
+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 parseDuration(value: string, label: string): TemporalDuration {
+ const match = /^(\d+)(?:\.(\d+))?(f|ms|s)$/u.exec(value.trim());
+ if (match === null) 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 splitTopLevel(value: string, separator: string): string[] {
+ const result: string[] = [];
+ let depth = 0;
+ let start = 0;
+ for (let index = 0; index < value.length; index += 1) {
+ const char = value[index];
+ if (char === "(") depth += 1;
+ else if (char === ")") depth -= 1;
+ else if (char === separator && depth === 0) {
+ result.push(value.slice(start, index).trim());
+ start = index + 1;
}
- declaredInputs.set(name, type);
- };
- addInput("header", timelineAuthorTypes.header);
- addInput("clock", programSpaceTypes.clock);
- for (const take of options.takes) {
- addInput(take.takeName, speechTypes.semanticTake);
+ assert(depth >= 0, `Timeline expression has an unmatched parenthesis: ${value}`);
}
- const operations: FragmentOperation[] = [{
- id: "track:set:empty",
- producer: timelineAuthorProducers.createSet,
- inputs: {},
- result: { kind: "output", name: "set" },
- }];
- let current = "track:set:empty";
- options.takes.forEach((take, index) => {
- const id = `track:set:append:${String(index + 1).padStart(4, "0")}`;
- operations.push({
- id,
- producer: timelineAuthorProducers.appendTake,
- inputs: {
- set: operation(current),
- take: input(take.takeName),
- },
- result: { kind: "output", name: "set" },
- });
- current = id;
- });
- operations.push(
- {
- id: "track:semantic",
- producer: timelineAuthorProducers.assembleTrack,
- inputs: { header: input("header"), set: operation(current), clock: input("clock") },
- result: { kind: "output", name: "track" },
- },
- );
- return sealGraphFragment({
- inputs: [...declaredInputs.entries()].map(([name, type]) => ({ name, type })),
- operations,
- exports: [
- { name: "timeline", type: timelineTypes.track, root: operation("track:semantic") },
- ],
+ assert(depth === 0, `Timeline expression has an unmatched parenthesis: ${value}`);
+ result.push(value.slice(start).trim());
+ return result;
+}
+
+function splitOffset(expression: string): { readonly base: string; readonly direction?: 1 | -1; readonly duration?: string } {
+ const value = expression.trim();
+ let depth = 0;
+ for (let index = value.length - 1; index > 0; index -= 1) {
+ const char = value[index];
+ if (char === ")") depth += 1;
+ else if (char === "(") depth -= 1;
+ else if (depth === 0 && (char === "+" || char === "-")) {
+ const duration = value.slice(index + 1).trim();
+ if (/^\d+(?:\.\d+)?(?:f|ms|s)$/u.test(duration)) {
+ return { base: value.slice(0, index).trim(), direction: char === "+" ? 1 : -1, duration };
+ }
+ }
+ }
+ return { base: value };
+}
+
+export function compileTimelineAuthorFragment(options: TimelineAuthorFragmentOptions): TimelineAuthorFragmentPlan {
+ const declarations = new Map<string, TimelineAuthorDeclaration>();
+ const reserved = new Set(["start", "end", "timeline", "window"]);
+ for (const declaration of options.declarations) {
+ assert(!reserved.has(declaration.id), `Timeline declaration ${declaration.id} uses a reserved name.`);
+ assert(!declarations.has(declaration.id), `Timeline repeats declaration ${declaration.id}.`);
+ declarations.set(declaration.id, declaration);
+ }
+
+ const inputs: Array<{ name: string; type: TypeRef }> = [
+ { name: "header", type: timelineAuthorTypes.header },
+ { name: "clock", type: timelineTypes.clock },
+ ];
+ const operations: FragmentOperation[] = [];
+ const inlineInputs: TimelineAuthorInlineInput[] = [];
+ const extentInputs: { name: string; declarationId: string }[] = [];
+ const created = new Set<string>();
+ let generated = 0;
+
+ const addOperation = (value: FragmentOperation): FragmentOperationRef => {
+ if (!created.has(value.id)) {
+ created.add(value.id);
+ operations.push(value);
+ }
+ return operation(value.id);
+ };
+ const addInline = (type: TypeRef, value: unknown, stem: string): ReturnType<typeof input> => {
+ const name = `${stem}-${++generated}`;
+ inputs.push({ name, type });
+ inlineInputs.push({ name, type, value });
+ return input(name);
+ };
+ const identitySpec = (id: string, subjectId = id) =>
+ addInline(timelineAuthorTypes.identity, { id, subjectId }, "identity");
+ const originRef = (): FragmentOperationRef => addOperation({
+ id: "point:start", producer: timelineAuthorProducers.origin,
+ inputs: { clock: input("clock") }, result: { kind: "output", name: "point" },
});
+ const durationExtent = (raw: string): FragmentOperationRef => {
+ const duration = parseDuration(raw, "Timeline construction duration");
+ const durationInput = addInline(timelineAuthorTypes.duration, duration, "duration");
+ return addOperation({ id: `extent:duration:${generated}`, producer: timelineAuthorProducers.duration,
+ inputs: { clock: input("clock"), duration: durationInput }, result: { kind: "output", name: "extent" } });
+ };
+ const resolvedExtent = (declarationId: string, name: string): FragmentOperationRef => {
+ if (!extentInputs.some((item) => item.name === name)) {
+ inputs.push({ name, type: temporalTypes.extent });
+ extentInputs.push({ name, declarationId });
+ }
+ return addOperation({ id: `decl:${declarationId}:extent`, producer: timelineAuthorProducers.resolvedExtent,
+ inputs: { clock: input("clock"), extent: input(name) }, result: { kind: "output", name: "extent" } });
+ };
+ const declarationExtent = (declaration: Extract<TimelineAuthorDeclaration, { readonly kind: "window" }>): FragmentOperationRef => {
+ if (declaration.duration !== undefined) return durationExtent(declaration.duration);
+ assert(declaration.extentInput !== undefined, `Timeline Window ${declaration.id} requires for.`);
+ return resolvedExtent(declaration.id, declaration.extentInput);
+ };
+ const spanRef = (id: string): FragmentOperationRef => operation(`decl:${id}:span`);
+ const instantRef = (id: string): FragmentOperationRef => operation(`decl:${id}:point`);
+ const boundaryRef = (id: string, boundary: "start" | "end"): FragmentOperationRef => {
+ const declaration = declarations.get(id);
+ assert(declaration !== undefined, `Timeline expression references unknown declaration ${id}.`);
+ assert(declaration.kind === "window", `Timeline Instant ${id} has no ${boundary} boundary.`);
+ return addOperation({ id: `decl:${id}:${boundary}`,
+ producer: boundary === "start" ? timelineAuthorProducers.spanStart : timelineAuthorProducers.spanEnd,
+ inputs: { span: spanRef(id) }, result: { kind: "output", name: "point" } });
+ };
+ const pointExpression = (source: string): FragmentOperationRef => {
+ const { base, direction, duration } = splitOffset(source);
+ let ref: FragmentOperationRef;
+ if (base === "start") ref = originRef();
+ else if (base === "end") ref = operation("point:end");
+ else if (/^\d+(?:\.\d+)?(?:f|ms|s)$/u.test(base)) {
+ const extent = durationExtent(base);
+ const spec = addInline(timelineAuthorTypes.offset, { direction: 1 }, "offset");
+ ref = addOperation({ id: `point:absolute:${generated}`, producer: timelineAuthorProducers.offset,
+ inputs: { point: originRef(), extent, spec }, result: { kind: "output", name: "point" } });
+ } else {
+ const aggregate = /^(earliest|latest)\((.*)\)$/u.exec(base);
+ if (aggregate !== null) {
+ const terms = splitTopLevel(aggregate[2]!, ",").filter(Boolean);
+ assert(terms.length > 0, `${aggregate[1]}() requires at least one Point.`);
+ ref = pointExpression(terms[0]!);
+ for (const term of terms.slice(1)) {
+ ref = addOperation({ id: `point:${aggregate[1]}:${++generated}`,
+ producer: aggregate[1] === "earliest" ? timelineAuthorProducers.earliest : timelineAuthorProducers.latest,
+ inputs: { left: ref, right: pointExpression(term) }, result: { kind: "output", name: "point" } });
+ }
+ } else {
+ const boundary = /^([A-Za-z][A-Za-z0-9_.:#-]{0,191})\.(start|end)$/u.exec(base);
+ if (boundary !== null) ref = boundaryRef(boundary[1]!, boundary[2] as "start" | "end");
+ else {
+ const declaration = declarations.get(base);
+ assert(declaration?.kind === "instant", `Timeline expression ${base} is not an Instant.`);
+ ref = instantRef(base);
+ }
+ }
+ }
+ if (direction === undefined) return ref;
+ assert(duration !== undefined && duration.length > 0, `Timeline expression ${source} has no offset duration.`);
+ const extent = durationExtent(duration);
+ const spec = addInline(timelineAuthorTypes.offset, { direction }, "offset");
+ return addOperation({ id: `point:offset:${++generated}`, producer: timelineAuthorProducers.offset,
+ inputs: { point: ref, extent, spec }, result: { kind: "output", name: "point" } });
+ };
+
+ for (const declaration of options.declarations) {
+ if (declaration.kind === "instant") {
+ addOperation({ id: `decl:${declaration.id}:point`, producer: timelineAuthorProducers.aliasPoint,
+ inputs: { point: pointExpression(declaration.at) }, result: { kind: "output", name: "point" } });
+ continue;
+ }
+ const hasFrom = declaration.from !== undefined;
+ const hasUntil = declaration.until !== undefined;
+ const hasFor = declaration.duration !== undefined || declaration.extentInput !== undefined;
+ assert(Number(hasFrom) + Number(hasUntil) + Number(hasFor) === 2,
+ `Timeline Window ${declaration.id} requires exactly two of from, until and for.`);
+ if (hasFrom && hasUntil) {
+ addOperation({ id: `decl:${declaration.id}:span`, producer: timelineAuthorProducers.spanBetween,
+ inputs: { start: pointExpression(declaration.from!), end: pointExpression(declaration.until!) },
+ result: { kind: "output", name: "span" } });
+ } else if (hasFrom) {
+ addOperation({ id: `decl:${declaration.id}:span`, producer: timelineAuthorProducers.span,
+ inputs: { start: pointExpression(declaration.from!), extent: declarationExtent(declaration) },
+ result: { kind: "output", name: "span" } });
+ } else {
+ addOperation({ id: `decl:${declaration.id}:span`, producer: timelineAuthorProducers.spanEnding,
+ inputs: { end: pointExpression(declaration.until!), extent: declarationExtent(declaration) },
+ result: { kind: "output", name: "span" } });
+ }
+ }
+
+ addOperation({ id: "point:end", producer: timelineAuthorProducers.aliasPoint,
+ inputs: { point: pointExpression(options.end) }, result: { kind: "output", name: "point" } });
+ addOperation({ id: "timeline", producer: timelineAuthorProducers.finalize,
+ inputs: { header: input("header"), clock: input("clock"), end: operation("point:end") },
+ result: { kind: "output", name: "timeline" } });
+ addOperation({ id: "span:window", producer: timelineAuthorProducers.spanBetween,
+ inputs: { start: originRef(), end: operation("point:end") }, result: { kind: "output", name: "span" } });
+
+ const exports: { name: string; type: TypeRef; root: FragmentOperationRef }[] = [
+ { name: "timeline", type: timelineTypes.track, root: operation("timeline") },
+ ];
+ const outputNames: { port: string; suffix: string }[] = [{ port: "timeline", suffix: "timeline" }];
+ const exportInstant = (port: string, suffix: string, point: FragmentOperationRef, id: string, subjectId: string): void => {
+ const operationId = `materialize:${port}`;
+ addOperation({ id: operationId, producer: timelineAuthorProducers.instant,
+ inputs: { timeline: operation("timeline"), point, spec: identitySpec(id, subjectId) },
+ result: { kind: "output", name: "instant" } });
+ exports.push({ name: port, type: temporalTypes.instant, root: operation(operationId) });
+ outputNames.push({ port, suffix });
+ };
+ const exportWindow = (port: string, suffix: string, span: FragmentOperationRef, id: string): void => {
+ const operationId = `materialize:${port}`;
+ addOperation({ id: operationId, producer: timelineAuthorProducers.window,
+ inputs: { timeline: operation("timeline"), span, spec: identitySpec(id) },
+ result: { kind: "output", name: "window" } });
+ exports.push({ name: port, type: temporalTypes.window, root: operation(operationId) });
+ outputNames.push({ port, suffix });
+ };
+
+ exportWindow("window", "window", operation("span:window"), options.id);
+ exportInstant("start", "start", originRef(), `${options.id}.start`, options.id);
+ exportInstant("end", "end", operation("point:end"), `${options.id}.end`, options.id);
+ for (const declaration of options.declarations) {
+ const id = `${options.id}.${declaration.id}`;
+ if (declaration.kind === "instant") {
+ exportInstant(`anchor-${declaration.id}`, declaration.id, instantRef(declaration.id), id, id);
+ continue;
+ }
+ exportWindow(`anchor-${declaration.id}`, declaration.id, spanRef(declaration.id), id);
+ exportInstant(`anchor-${declaration.id}-start`, `${declaration.id}.start`, boundaryRef(declaration.id, "start"), `${id}.start`, id);
+ exportInstant(`anchor-${declaration.id}-end`, `${declaration.id}.end`, boundaryRef(declaration.id, "end"), `${id}.end`, id);
+ }
+
+ return { fragment: sealGraphFragment({ inputs, operations, exports }), inlineInputs, extentInputs, outputNames };
+}
+
+export function createTimelineAuthorFragment(options: TimelineAuthorFragmentOptions): GraphFragment {
+ return compileTimelineAuthorFragment(options).fragment;
}
diff --git a/packages/timeline-author/src/index.ts b/packages/timeline-author/src/index.ts
index 89cd8715..155af866 100644
--- a/packages/timeline-author/src/index.ts
+++ b/packages/timeline-author/src/index.ts
@@ -1,7 +1,23 @@
/** Official Timeline authoring and deterministic Timeline assembly. */
export { timelineAuthorComponent } from "./component.js";
-export { createTimelineAuthorFragment } from "./fragment.js";
-export { timelineAuthorManifest, timelineAuthorMarkupSurfaces, timelineAuthorModuleRef, timelineAuthorProducers, timelineAuthorTypes, timelineAuthorHeaderSchema, timelineAuthorSetSchema } from "./manifest.js";
-export { appendTimelineAuthorTake, assembleTimelineAuthor, assertTimelineAuthorHeader, assertTimelineAuthorSet, createTimelineAuthorSet, sealTimelineAuthorHeader } from "./program.js";
-export { decodeTimelineAuthorSurface } from "./surface.js";
+export { compileTimelineAuthorFragment, createTimelineAuthorFragment } from "./fragment.js";
+export { timelineAuthorManifest, timelineAuthorMarkupSurfaces, timelineAuthorModuleRef, timelineAuthorProducers, timelineAuthorTypes, timelineAuthorHeaderSchema } from "./manifest.js";
+export {
+ constructionAliasPoint,
+ constructionDuration,
+ constructionEarliest,
+ constructionLatest,
+ constructionOffset,
+ constructionOrigin,
+ constructionResolvedExtent,
+ constructionSpan,
+ constructionSpanBetween,
+ constructionSpanEnd,
+ constructionSpanEnding,
+ constructionSpanStart,
+ finalizeTimeline,
+ materializeInstant,
+ materializeWindow,
+} from "./program.js";
+export { decodeAbsoluteInstantSurface, decodeAbsoluteWindowSurface, decodeClockSurface, decodeTimelineAuthorSurface } from "./surface.js";
export type * from "./types.js";
diff --git a/packages/timeline-author/src/manifest.ts b/packages/timeline-author/src/manifest.ts
index 48d6117f..1a19ad19 100644
--- a/packages/timeline-author/src/manifest.ts
+++ b/packages/timeline-author/src/manifest.ts
@@ -1,78 +1,137 @@
-import { programSpaceDependency, programSpaceTypes, programSpaceMarkupSurfaces } from "@hypit/program-space";
-import { semanticTakeSchema, speechDependency, speechTypes } from "@hypit/speech";
+import type { ModuleManifest, ProducerRef, TypeRef, ValueSchema } from "@hypit/protocol";
+import { temporalDependency, temporalTypes } from "@hypit/temporal";
import { timelineDependency, timelineTypes } from "@hypit/timeline";
-import type { ModuleManifest, ValueSchema } from "@hypit/protocol";
+
export const timelineAuthorModuleRef = { name: "@hypit/timeline-author", version: "1" } as const;
export const timelineAuthorTypes = {
header: { module: timelineAuthorModuleRef, name: "TimelineAuthorHeader" },
- trackSet: { module: timelineAuthorModuleRef, name: "TimelineAuthorSet" },
-} as const;
+ point: { module: timelineAuthorModuleRef, name: "ConstructionPoint" },
+ extent: { module: timelineAuthorModuleRef, name: "ConstructionExtent" },
+ span: { module: timelineAuthorModuleRef, name: "ConstructionSpan" },
+ duration: { module: timelineAuthorModuleRef, name: "ConstructionDurationSpec" },
+ offset: { module: timelineAuthorModuleRef, name: "ConstructionOffsetSpec" },
+ identity: { module: timelineAuthorModuleRef, name: "ConstructionIdentitySpec" },
+} satisfies Record<string, TypeRef>;
+
export const timelineAuthorProducers = {
- createSet: { module: timelineAuthorModuleRef, name: "create-track-set" },
- appendTake: { module: timelineAuthorModuleRef, name: "append-track-take" },
- assembleTrack: { module: timelineAuthorModuleRef, name: "assemble-timeline" },
-} as const;
-export const timelineAuthorHeaderSchema: ValueSchema = { kind: "object", fields: { id: { schema: { kind: "string", minLength: 1 } }, at: { optional: true, schema: { kind: "array", items: { kind: "string" } } }, end: { optional: true, schema: { kind: "string" } } } };
-export const timelineAuthorSetSchema: ValueSchema = { kind: "object", fields: { takes: { schema: { kind: "array", items: { kind: "object", fields: { semantic: { schema: semanticTakeSchema } } } } } } };
-export const timelineAuthorMarkupSurfaces = [{
- name: "timeline", tag: "Timeline", mode: "structured",
- outputs: [timelineAuthorTypes.header, timelineTypes.track],
- vocabulary: {
- summary: "Declares one complete Timeline, with zero or more prepared Takes placed within it.",
- attributes: [
- { name: "id", kind: "identifier", required: true, summary: "Names the Timeline output." },
- { name: "clock", kind: "reference", required: true, accepts: [programSpaceTypes.clock], summary: "Frame rate, available before material generation." },
- { name: "end", kind: "literal", required: false, summary: "Program end: fixed time or content.end with an optional offset; defaults to content.end." },
- ],
- children: [{ tag: "Take", cardinality: "many", summary: "A prepared SemanticTake in performance order.",
- attributes: [{ name: "source", kind: "reference", required: true, accepts: [speechTypes.semanticTake], summary: "The normalized, aligned performance." },
- { name: "at", kind: "literal", required: false, summary: "Absolute position or previous.end with an offset. Defaults to zero for the first Take and previous.end thereafter." }] }],
- ports: [
- { name: "timeline", type: timelineTypes.track, summary: "The complete time range, retaining placed material and any semantic evidence." },
- ],
- example: '<time:Clock id="clock" frame-rate="30"/><time:Timeline id="program" clock={clock} end="content.end+2s"><time:Take source={opening.take} at="2s"/><time:Take source={answer.take}/></time:Timeline>',
- notes: ["Performance, Sound and Caption present existing pictures, audio and words independently. Include their contributions explicitly in Film."],
- },
-}, programSpaceMarkupSurfaces[0]] as const;
+ origin: { module: timelineAuthorModuleRef, name: "origin" },
+ duration: { module: timelineAuthorModuleRef, name: "duration-extent" },
+ resolvedExtent: { module: timelineAuthorModuleRef, name: "resolved-extent" },
+ offset: { module: timelineAuthorModuleRef, name: "offset-point" },
+ earliest: { module: timelineAuthorModuleRef, name: "earliest-point" },
+ latest: { module: timelineAuthorModuleRef, name: "latest-point" },
+ aliasPoint: { module: timelineAuthorModuleRef, name: "alias-point" },
+ span: { module: timelineAuthorModuleRef, name: "construct-span" },
+ spanEnding: { module: timelineAuthorModuleRef, name: "construct-span-ending" },
+ spanBetween: { module: timelineAuthorModuleRef, name: "construct-span-between" },
+ spanStart: { module: timelineAuthorModuleRef, name: "span-start" },
+ spanEnd: { module: timelineAuthorModuleRef, name: "span-end" },
+ finalize: { module: timelineAuthorModuleRef, name: "finalize-timeline" },
+ instant: { module: timelineAuthorModuleRef, name: "materialize-instant" },
+ window: { module: timelineAuthorModuleRef, name: "materialize-window" },
+} satisfies Record<string, ProducerRef>;
+
+const string = { kind: "string", minLength: 1 } as const;
+export const timelineAuthorHeaderSchema: ValueSchema = { kind: "object", fields: { id: { schema: string } } };
+
export const timelineAuthorManifest: ModuleManifest = {
format: "hypit.module@1",
name: timelineAuthorModuleRef.name,
version: timelineAuthorModuleRef.version,
- dependencies: [
- programSpaceDependency,
- speechDependency,
- timelineDependency,
- ],
- types: [
- { name: timelineAuthorTypes.header.name },
- { name: timelineAuthorTypes.trackSet.name },
- ],
+ dependencies: [timelineDependency, temporalDependency],
+ types: Object.values(timelineAuthorTypes).map((type) => ({ name: type.name })),
capabilities: [],
producers: [
- {
- name: timelineAuthorProducers.createSet.name,
- inputs: [],
- outputs: [{ name: "set", type: timelineAuthorTypes.trackSet }],
- needs: [],
- },
- {
- name: timelineAuthorProducers.appendTake.name,
- inputs: [
- { name: "set", type: timelineAuthorTypes.trackSet },
- { name: "take", type: speechTypes.semanticTake },
- ],
- outputs: [{ name: "set", type: timelineAuthorTypes.trackSet }],
- needs: [],
- },
- {
- name: timelineAuthorProducers.assembleTrack.name,
- inputs: [
- { name: "header", type: timelineAuthorTypes.header },
- { name: "clock", type: programSpaceTypes.clock },
- { name: "set", type: timelineAuthorTypes.trackSet },
- ],
- outputs: [{ name: "track", type: timelineTypes.track }],
- needs: [],
- },
+ { name: timelineAuthorProducers.origin.name, inputs: [{ name: "clock", type: timelineTypes.clock }], outputs: [{ name: "point", type: timelineAuthorTypes.point }], needs: [] },
+ { name: timelineAuthorProducers.duration.name, inputs: [{ name: "clock", type: timelineTypes.clock }, { name: "duration", type: timelineAuthorTypes.duration }], outputs: [{ name: "extent", type: timelineAuthorTypes.extent }], needs: [] },
+ { name: timelineAuthorProducers.resolvedExtent.name, inputs: [{ name: "clock", type: timelineTypes.clock }, { name: "extent", type: temporalTypes.extent }], outputs: [{ name: "extent", type: timelineAuthorTypes.extent }], needs: [] },
+ { name: timelineAuthorProducers.offset.name, inputs: [{ name: "point", type: timelineAuthorTypes.point }, { name: "extent", type: timelineAuthorTypes.extent }, { name: "spec", type: timelineAuthorTypes.offset }], outputs: [{ name: "point", type: timelineAuthorTypes.point }], needs: [] },
+ { name: timelineAuthorProducers.earliest.name, inputs: [{ name: "left", type: timelineAuthorTypes.point }, { name: "right", type: timelineAuthorTypes.point }], outputs: [{ name: "point", type: timelineAuthorTypes.point }], needs: [] },
+ { name: timelineAuthorProducers.latest.name, inputs: [{ name: "left", type: timelineAuthorTypes.point }, { name: "right", type: timelineAuthorTypes.point }], outputs: [{ name: "point", type: timelineAuthorTypes.point }], needs: [] },
+ { name: timelineAuthorProducers.aliasPoint.name, inputs: [{ name: "point", type: timelineAuthorTypes.point }], outputs: [{ name: "point", type: timelineAuthorTypes.point }], needs: [] },
+ { name: timelineAuthorProducers.span.name, inputs: [{ name: "start", type: timelineAuthorTypes.point }, { name: "extent", type: timelineAuthorTypes.extent }], outputs: [{ name: "span", type: timelineAuthorTypes.span }], needs: [] },
+ { name: timelineAuthorProducers.spanEnding.name, inputs: [{ name: "end", type: timelineAuthorTypes.point }, { name: "extent", type: timelineAuthorTypes.extent }], outputs: [{ name: "span", type: timelineAuthorTypes.span }], needs: [] },
+ { name: timelineAuthorProducers.spanBetween.name, inputs: [{ name: "start", type: timelineAuthorTypes.point }, { name: "end", type: timelineAuthorTypes.point }], outputs: [{ name: "span", type: timelineAuthorTypes.span }], needs: [] },
+ { name: timelineAuthorProducers.spanStart.name, inputs: [{ name: "span", type: timelineAuthorTypes.span }], outputs: [{ name: "point", type: timelineAuthorTypes.point }], needs: [] },
+ { name: timelineAuthorProducers.spanEnd.name, inputs: [{ name: "span", type: timelineAuthorTypes.span }], outputs: [{ name: "point", type: timelineAuthorTypes.point }], needs: [] },
+ { name: timelineAuthorProducers.finalize.name, inputs: [{ name: "header", type: timelineAuthorTypes.header }, { name: "clock", type: timelineTypes.clock }, { name: "end", type: timelineAuthorTypes.point }], outputs: [{ name: "timeline", type: timelineTypes.track }], needs: [] },
+ { name: timelineAuthorProducers.instant.name, inputs: [{ name: "timeline", type: timelineTypes.track }, { name: "point", type: timelineAuthorTypes.point }, { name: "spec", type: timelineAuthorTypes.identity }], outputs: [{ name: "instant", type: temporalTypes.instant }], needs: [] },
+ { name: timelineAuthorProducers.window.name, inputs: [{ name: "timeline", type: timelineTypes.track }, { name: "span", type: timelineAuthorTypes.span }, { name: "spec", type: timelineAuthorTypes.identity }], outputs: [{ name: "window", type: temporalTypes.window }], needs: [] },
],
};
+
+export const timelineAuthorMarkupSurfaces = [{
+ name: "timeline", tag: "Timeline", mode: "structured",
+ outputs: [...Object.values(timelineAuthorTypes), timelineTypes.track, temporalTypes.instant, temporalTypes.window],
+ vocabulary: {
+ summary: "Lowers a small acyclic Instant/Window author graph into one finite Timeline and scoped absolute anchors.",
+ attributes: [
+ { name: "id", kind: "identifier", required: true, summary: "Names the finalized Timeline." },
+ { name: "clock", kind: "reference", required: true, accepts: [timelineTypes.clock], summary: "Selects its exact frame clock." },
+ { name: "end", kind: "literal", required: true, summary: "Names the one Point expression that becomes frameCount." },
+ ],
+ children: [
+ { tag: "Instant", cardinality: "many", summary: "Names one absolute boundary relationship.", attributes: [
+ { name: "id", kind: "identifier", required: true, summary: "Scoped Instant name." },
+ { name: "at", kind: "literal", required: true, summary: "Restricted Point expression." },
+ ] },
+ { tag: "Window", cardinality: "many", summary: "Names one non-empty absolute interval from exactly two of from, until and for.", attributes: [
+ { name: "id", kind: "identifier", required: true, summary: "Scoped Window name." },
+ { name: "from", kind: "literal", required: false, summary: "Start Point expression." },
+ { name: "until", kind: "literal", required: false, summary: "End Point expression." },
+ { name: "for", kind: "expression", required: false, accepts: [temporalTypes.extent], summary: "Exact duration literal or typed TemporalExtent reference." },
+ ] },
+ ],
+ ports: [
+ { name: "timeline", type: timelineTypes.track, summary: "The finalized absolute Timeline." },
+ { name: "window", type: temporalTypes.window, summary: "The complete [start,end) Window." },
+ { name: "start/end", type: temporalTypes.instant, summary: "The complete Timeline boundaries." },
+ { name: "<name>", type: temporalTypes.instant, summary: "A named Instant child." },
+ { name: "<name>", type: temporalTypes.window, summary: "A named Window child, with .start and .end boundary ports." },
+ ],
+ example: `<time:Timeline id="program" clock={clock} end="latest(speech.end,outro.end)">
+ <time:Window id="speech" from="start" for={voice.extent}/>
+ <time:Instant id="claim" at="speech.end-12f"/>
+ <time:Window id="outro" from="claim" for="3s"/>
+</time:Timeline>`,
+ },
+}, {
+ name: "clock", tag: "Clock", mode: "structured", outputs: [timelineTypes.clock], vocabulary: {
+ summary: "Declares the discrete frame conversion law.",
+ attributes: [
+ { name: "id", kind: "identifier", required: true, summary: "Names the Clock." },
+ { name: "frame-rate", kind: "literal", required: true, summary: "Exact frames per second." },
+ ],
+ example: '<time:Clock id="clock" frame-rate="30"/>',
+ },
+}, {
+ name: "window", tag: "Window", mode: "structured", outputs: [temporalTypes.duration, temporalTypes.extent,
+ temporalTypes.shiftSpec, temporalTypes.instantSpec, temporalTypes.windowSpec, temporalTypes.instant, temporalTypes.window],
+ vocabulary: {
+ summary: "Publishes one reusable absolute Window without putting content on Timeline.",
+ attributes: [
+ { name: "id", kind: "identifier", required: true, summary: "Names the Window and its .start/.end Instants." },
+ { name: "timeline", kind: "reference", required: true, accepts: [timelineTypes.track], summary: "Selects the absolute coordinate system." },
+ { name: "from", kind: "expression", required: false, accepts: [temporalTypes.instant], summary: "Inclusive absolute start." },
+ { name: "until", kind: "expression", required: false, accepts: [temporalTypes.instant], summary: "Exclusive absolute end." },
+ { name: "for", kind: "expression", required: false, accepts: [temporalTypes.extent], summary: "Exact duration." },
+ ],
+ ports: [
+ { name: "<id>", type: temporalTypes.window, summary: "The resolved Window." },
+ { name: "<id>.start/end", type: temporalTypes.instant, summary: "Its resolved boundary Instants." },
+ ],
+ example: '<time:Window id="reveal-band" timeline={film.timeline} from={story-time.reveal} until={story-time.answer-end}/>',
+ },
+}, {
+ name: "instant", tag: "Instant", mode: "structured", outputs: [temporalTypes.instantSpec, temporalTypes.instant],
+ vocabulary: {
+ summary: "Publishes one reusable authored absolute Instant.",
+ attributes: [
+ { name: "id", kind: "identifier", required: true, summary: "Names the Instant." },
+ { name: "timeline", kind: "reference", required: true, accepts: [timelineTypes.track], summary: "Selects the absolute coordinate system." },
+ { name: "at", kind: "literal", required: true, summary: "Absolute time or Timeline-boundary expression." },
+ ],
+ ports: [{ name: "<id>", type: temporalTypes.instant, summary: "The resolved Instant." }],
+ example: '<time:Instant id="credits" timeline={film.timeline} at="timeline.end-2s"/>',
+ },
+}] as const;
diff --git a/packages/timeline-author/src/program.ts b/packages/timeline-author/src/program.ts
index 811fd689..8df93a32 100644
--- a/packages/timeline-author/src/program.ts
+++ b/packages/timeline-author/src/program.ts
@@ -1,107 +1,137 @@
-import { assertProgramClockIdentity, type ProgramClock } from "@hypit/program-space";
-import { durationInFrames } from "@hypit/temporal";
-import { parseTemporalDuration } from "@hypit/temporal-markup";
-import { assertSemanticTakeIdentity } from "@hypit/speech";
-import type { SemanticTake } from "@hypit/speech";
-import { sealTimeline } from "@hypit/timeline";
-import type { Timeline } from "@hypit/timeline";
-import type { TimelineAuthorHeader, TimelineAuthorSet, TimelineAuthorTake } from "./types.js";
+import {
+ assertTemporalExtentClock,
+ assertTemporalWindowFor,
+ composeTemporalWindow,
+ durationInFrames,
+ projectProgramInstant,
+} from "@hypit/temporal";
+import type {
+ LocalTemporalDomain,
+ TemporalExtent,
+ TemporalDuration,
+ TemporalInstant,
+ TemporalWindow,
+} from "@hypit/temporal";
+import { assertClockIdentity, sealTimeline } from "@hypit/timeline";
+import type { Clock, Timeline } from "@hypit/timeline";
+
+import type {
+ ConstructionExtent,
+ ConstructionIdentitySpec,
+ ConstructionOffsetSpec,
+ ConstructionPoint,
+ ConstructionSpan,
+ TimelineAuthorHeader,
+} from "./types.js";
+
function assert(condition: unknown, message: string): asserts condition {
if (!condition) throw new Error(message);
}
-export function sealTimelineAuthorHeader(value: TimelineAuthorHeader): TimelineAuthorHeader { return structuredClone(value); }
-export function assertTimelineAuthorHeader(value: TimelineAuthorHeader): void {
- assert(value.id.trim().length > 0, "TimelineAuthorHeader id must not be empty");
-}
-function sealTimelineAuthorSet(value: TimelineAuthorSet): TimelineAuthorSet { return structuredClone(value); }
-function assertTake(take: TimelineAuthorTake): void { assertSemanticTakeIdentity(take.semantic); }
-export function assertTimelineAuthorSet(value: TimelineAuthorSet): void {
- const segments = new Set<string>();
- for (const take of value.takes) {
- assertSemanticTakeIdentity(take.semantic);
- const segmentId = take.semantic.segment.segmentId;
- assert(!segments.has(segmentId), `Timeline repeats Segment ${segmentId}`);
- segments.add(segmentId);
- }
-}
-
-export function createTimelineAuthorSet(): TimelineAuthorSet {
- return sealTimelineAuthorSet({
- takes: [],
- });
+
+function identity(value: string, label: string): void {
+ assert(/^[A-Za-z][A-Za-z0-9_.:#-]{0,191}$/u.test(value), `${label} is invalid.`);
}
-function appendTake(
- set: TimelineAuthorSet,
- take: TimelineAuthorTake,
-): TimelineAuthorSet {
- assertTimelineAuthorSet(set);
- assertTake(take);
- assert(!set.takes.some((item) => item.semantic.segment.segmentId === take.semantic.segment.segmentId),
- `Timeline repeats Segment ${take.semantic.segment.segmentId}`);
- return sealTimelineAuthorSet({
- takes: [...set.takes, take],
- });
+export function constructionOrigin(clock: Clock): ConstructionPoint {
+ assertClockIdentity(clock);
+ return { frame: 0 };
}
-export function appendTimelineAuthorTake(set: TimelineAuthorSet, semantic: SemanticTake): TimelineAuthorSet {
- return appendTake(set, { semantic });
-}
-
-export function assembleTimelineAuthor(
- header: TimelineAuthorHeader,
- set: TimelineAuthorSet,
- clock: ProgramClock,
-): Timeline {
- assertTimelineAuthorHeader(header);
- assertTimelineAuthorSet(set);
- assertProgramClockIdentity(clock);
- if (header.at !== undefined && header.at.length !== set.takes.length) {
- throw new Error("Timeline placement declarations must correspond to its Takes.");
- }
- const narrativeId = set.takes[0]?.semantic.narrativeId;
- let previousEnd = 0;
- let contentEnd = 0;
- const items = set.takes.map((item, index) => {
- const at = header.at?.[index] ?? (index === 0 ? "0f" : "previous.end");
- const startFrame = placementFrame(at, clock, index === 0 ? undefined : previousEnd, "previous.end");
- previousEnd = startFrame + item.semantic.media.timeline.frameCount;
- contentEnd = Math.max(contentEnd, previousEnd);
- return { take: item.semantic, startFrame };
- });
- const endFrame = placementFrame(header.end ?? "content.end", clock, contentEnd, "content.end");
- assert(endFrame > 0, "Timeline needs a positive end; an empty Timeline requires an authored extent.");
- assert(endFrame >= contentEnd, "Timeline end precedes placed content; choose an end that includes its Takes.");
- return sealTimeline({
- id: header.id, frameRate: clock.frameRate,
- durationSec: endFrame * clock.frameRate.denominator / clock.frameRate.numerator,
- ...(narrativeId === undefined ? {} : { narrativeId }), items,
+export function constructionDuration(clock: Clock, duration: TemporalDuration): ConstructionExtent {
+ assertClockIdentity(clock);
+ const frames = durationInFrames(duration, clock);
+ assert(frames.denominator === 1n && frames.numerator >= 0n
+ && frames.numerator <= BigInt(Number.MAX_SAFE_INTEGER),
+ "Timeline construction duration must resolve to a non-negative exact frame extent.");
+ return { frameCount: Number(frames.numerator) };
+}
+
+export function constructionResolvedExtent(clock: Clock, extent: TemporalExtent): ConstructionExtent {
+ assertTemporalExtentClock(extent, clock);
+ return { frameCount: extent.frameCount };
+}
+
+export function constructionOffset(
+ point: ConstructionPoint,
+ extent: ConstructionExtent,
+ spec: ConstructionOffsetSpec,
+): ConstructionPoint {
+ const frame = point.frame + spec.direction * extent.frameCount;
+ assert(Number.isSafeInteger(frame) && frame >= 0, "Timeline construction Point resolves before start.");
+ return { frame };
+}
+
+export function constructionLatest(left: ConstructionPoint, right: ConstructionPoint): ConstructionPoint {
+ return { frame: Math.max(left.frame, right.frame) };
+}
+
+export function constructionEarliest(left: ConstructionPoint, right: ConstructionPoint): ConstructionPoint {
+ return { frame: Math.min(left.frame, right.frame) };
+}
+
+export function constructionAliasPoint(point: ConstructionPoint): ConstructionPoint {
+ return { frame: point.frame };
+}
+
+export function constructionSpan(start: ConstructionPoint, extent: ConstructionExtent): ConstructionSpan {
+ assert(extent.frameCount > 0, "Timeline construction Span must be non-empty.");
+ return { startFrame: start.frame, endFrameExclusive: start.frame + extent.frameCount };
+}
+
+export function constructionSpanEnding(end: ConstructionPoint, extent: ConstructionExtent): ConstructionSpan {
+ assert(extent.frameCount > 0, "Timeline construction Span must be non-empty.");
+ const startFrame = end.frame - extent.frameCount;
+ assert(startFrame >= 0, "Timeline construction Span resolves before start.");
+ return { startFrame, endFrameExclusive: end.frame };
+}
+
+export function constructionSpanBetween(start: ConstructionPoint, end: ConstructionPoint): ConstructionSpan {
+ assert(end.frame > start.frame, "Timeline construction Span must be non-empty and ordered.");
+ return { startFrame: start.frame, endFrameExclusive: end.frame };
+}
+
+export function constructionSpanStart(span: ConstructionSpan): ConstructionPoint {
+ return { frame: span.startFrame };
+}
+
+export function constructionSpanEnd(span: ConstructionSpan): ConstructionPoint {
+ return { frame: span.endFrameExclusive };
+}
+
+export function finalizeTimeline(header: TimelineAuthorHeader, clock: Clock, end: ConstructionPoint): Timeline {
+ identity(header.id, "Timeline id");
+ assertClockIdentity(clock);
+ assert(Number.isSafeInteger(end.frame) && end.frame > 0, "Timeline end must be a positive frame boundary.");
+ return sealTimeline({ id: header.id, frameRate: structuredClone(clock.frameRate), frameCount: end.frame });
+}
+
+export function materializeInstant(
+ timeline: Timeline,
+ point: ConstructionPoint,
+ spec: ConstructionIdentitySpec,
+): TemporalInstant {
+ identity(spec.id, "Instant id");
+ const subjectId = spec.subjectId ?? spec.id;
+ identity(subjectId, "Instant subject id");
+ return projectProgramInstant({
+ itemId: spec.id,
+ subjectId,
+ timeline,
+ projection: { ref: "absolute", at: { unit: "frames", value: point.frame } },
});
}
-/** Parse local placement syntax before any upstream material needs to run. */
-export function placementExpression(expression: string, reference: string) {
- const value = expression.trim();
- if (!value.startsWith(reference)) return { relative: false, sign: 1,
- duration: parseTemporalDuration(value, "Timeline position") };
- const offset = value.slice(reference.length).trim();
- if (offset === "") return { relative: true, sign: 1,
- duration: parseTemporalDuration("0f", "Timeline offset") };
- const match = /^([+-])\s*(.+)$/u.exec(offset);
- if (match === null) throw new Error(`Invalid Timeline position ${expression}.`);
- return { relative: true, sign: match[1] === "-" ? -1 : 1,
- duration: parseTemporalDuration(match[2]!, "Timeline offset") };
-}
-
-/** Resolve local assembly expressions before a complete Timeline exists. */
-export function placementFrame(expression: string, clock: ProgramClock, base: number | undefined, reference: string): number {
- const parsed = placementExpression(expression, reference);
- if (parsed.relative && base === undefined) throw new Error(`${reference} has no preceding Take.`);
- const frames = durationInFrames(parsed.duration, clock);
- if (frames.denominator !== 1n || frames.numerator > BigInt(Number.MAX_SAFE_INTEGER)) {
- throw new Error(`Timeline duration ${expression} must land on an exact frame boundary.`);
- }
- const frame = (parsed.relative ? base! : 0) + parsed.sign * Number(frames.numerator);
- if (!Number.isSafeInteger(frame) || frame < 0) throw new Error(`Timeline position ${expression} must resolve to a non-negative frame.`);
- return frame;
+export function materializeWindow(
+ timeline: Timeline,
+ span: ConstructionSpan,
+ spec: ConstructionIdentitySpec,
+): TemporalWindow {
+ identity(spec.id, "Window id");
+ return composeTemporalWindow(
+ { id: spec.id, subjectId: spec.id },
+ projectProgramInstant({ itemId: `${spec.id}.start`, subjectId: spec.id, timeline,
+ projection: { ref: "absolute", at: { unit: "frames", value: span.startFrame } } }),
+ projectProgramInstant({ itemId: `${spec.id}.end`, subjectId: spec.id, timeline,
+ projection: { ref: "absolute", at: { unit: "frames", value: span.endFrameExclusive } } }),
+ );
}
diff --git a/packages/timeline-author/src/surface.ts b/packages/timeline-author/src/surface.ts
index b71ca696..3e11fac1 100644
--- a/packages/timeline-author/src/surface.ts
+++ b/packages/timeline-author/src/surface.ts
@@ -1,46 +1,171 @@
-import { placementExpression } from "./program.js";
-import { programSpaceTypes } from "@hypit/program-space";
-import { assertAttributes, assertEmptyElement, localName, textAttribute, type StructuredSurfaceHandler } from "@hypit/markup";
-import { sameType } from "@hypit/protocol";
-import { speechTypes } from "@hypit/speech";
-import { createTimelineAuthorFragment } from "./fragment.js";
+import {
+ assertAttributes,
+ assertEmptyElement,
+ localName,
+ textAttribute,
+ type StructuredElement,
+ type StructuredSurfaceHandler,
+ type SurfaceResolvedReference,
+} from "@hypit/markup";
+import { canonicalize, sameType } from "@hypit/protocol";
+import { temporalTypes } from "@hypit/temporal";
+import {
+ createTemporalInstantConstruction,
+ createTemporalWindowConstruction,
+ resolveTemporalContext,
+} from "@hypit/temporal-markup";
+import { timelineTypes } from "@hypit/timeline";
+
+import { compileTimelineAuthorFragment } from "./fragment.js";
import { timelineAuthorTypes } from "./manifest.js";
+import type { TimelineAuthorDeclaration } from "./types.js";
+
+function reference(
+ element: StructuredElement,
+ name: string,
+ type: SurfaceResolvedReference["type"],
+ resolveReference: (path: string) => SurfaceResolvedReference | undefined,
+): SurfaceResolvedReference {
+ const raw = element.attributes[name];
+ if (typeof raw !== "object" || raw.kind !== "reference") throw new Error(`${element.name}.${name} must be a reference.`);
+ const found = resolveReference(raw.path);
+ if (found === undefined || !sameType(found.type, type)) throw new Error(`${element.name}.${name} has the wrong Type.`);
+ return found;
+}
+
+function optionalPointExpression(element: StructuredElement, name: string): string | undefined {
+ const raw = element.attributes[name];
+ if (raw === undefined) return undefined;
+ if (typeof raw !== "string" || raw.trim().length === 0) {
+ throw new Error(`${element.name}.${name} must be a Timeline Point expression.`);
+ }
+ return raw.trim();
+}
export const decodeTimelineAuthorSurface: StructuredSurfaceHandler = ({ element, resolveReference }) => {
assertAttributes(element, ["id", "clock", "end"]);
const id = textAttribute(element, "id");
- const rawClock = element.attributes.clock;
- const clock = typeof rawClock === "object" && rawClock.kind === "reference" ? resolveReference(rawClock.path) : undefined;
- if (clock === undefined || !sameType(clock.type, programSpaceTypes.clock)) throw new Error(`${element.name}.clock must reference a Clock.`);
- if (element.attributes.end !== undefined) placementExpression(textAttribute(element, "end"), "content.end");
- const at: string[] = [];
- const takes = element.children.flatMap(child => {
+ const clock = reference(element, "clock", timelineTypes.clock, resolveReference);
+ const end = textAttribute(element, "end");
+ const extentReferences = new Map<string, SurfaceResolvedReference>();
+ const declarations: TimelineAuthorDeclaration[] = [];
+
+ for (const [index, child] of element.children.entries()) {
if (child.kind === "text") {
- if (child.value.trim()) throw new Error("Timeline accepts only Take children.");
- return [];
+ if (child.value.trim()) throw new Error(`${element.name} accepts only Instant and Window children.`);
+ continue;
+ }
+ const tag = localName(child.name);
+ if (tag === "Instant") {
+ assertAttributes(child, ["id", "at"]);
+ assertEmptyElement(child);
+ declarations.push({ id: textAttribute(child, "id"), kind: "instant", at: textAttribute(child, "at") });
+ continue;
+ }
+ if (tag === "Window") {
+ assertAttributes(child, ["id", "from", "until", "for"], ["id"]);
+ assertEmptyElement(child);
+ const declarationId = textAttribute(child, "id");
+ const rawFor = child.attributes.for;
+ let duration: string | undefined;
+ let extentInput: string | undefined;
+ if (typeof rawFor === "string") duration = rawFor.trim();
+ else if (rawFor !== undefined) {
+ const found = reference(child, "for", temporalTypes.extent, resolveReference);
+ extentInput = `extent-${index + 1}`;
+ extentReferences.set(extentInput, found);
+ }
+ const from = optionalPointExpression(child, "from");
+ const until = optionalPointExpression(child, "until");
+ declarations.push({
+ id: declarationId,
+ kind: "window",
+ ...(from === undefined ? {} : { from }),
+ ...(until === undefined ? {} : { until }),
+ ...(duration === undefined ? {} : { duration }),
+ ...(extentInput === undefined ? {} : { extentInput }),
+ });
+ continue;
}
- if (localName(child.name) !== "Take") throw new Error("Timeline accepts only Take children.");
- assertAttributes(child, ["source", "at"]);
- at.push(child.attributes.at === undefined ? (at.length === 0 ? "0f" : "previous.end") : textAttribute(child, "at"));
- const position = placementExpression(at.at(-1)!, "previous.end");
- if (at.length === 1 && position.relative) throw new Error("The first Timeline Take has no previous.end.");
- assertEmptyElement(child);
- const source = child.attributes.source;
- if (typeof source !== "object" || source.kind !== "reference") throw new Error("Timeline Take source must be a reference.");
- const resolved = resolveReference(source.path);
- if (resolved === undefined || !sameType(resolved.type, speechTypes.semanticTake)) throw new Error("Timeline Take source must be a SemanticTake.");
- return [resolved];
- });
- const inputs = takes.map((_, index) => ({ takeName: `take-${index + 1}` }));
- const fragment = createTimelineAuthorFragment({ takes: inputs });
+ throw new Error(`${element.name} accepts only Instant and Window children.`);
+ }
+
+ const plan = compileTimelineAuthorFragment({ id, end, declarations });
+ const headerRecord = `${id}.__header`;
+ const records = [{ id: headerRecord, type: timelineAuthorTypes.header,
+ value: { kind: "inline" as const, value: canonicalize({ id }) }, range: element.range },
+ ...plan.inlineInputs.map((item) => ({ id: `${id}.__${item.name}`, type: item.type,
+ value: { kind: "inline" as const, value: canonicalize(item.value) }, range: element.range }))];
+ const inputs = {
+ header: { kind: "record" as const, id: headerRecord },
+ clock: clock.ref,
+ ...Object.fromEntries(plan.inlineInputs.map((item) => [item.name, { kind: "record" as const, id: `${id}.__${item.name}` }])),
+ ...Object.fromEntries(plan.extentInputs.map((item) => {
+ const extent = extentReferences.get(item.name);
+ if (extent === undefined) throw new Error(`Timeline Window ${item.declarationId} has no resolved Extent.`);
+ return [item.name, extent.ref];
+ })),
+ };
+ const outputs = Object.fromEntries(plan.outputNames.map((item) => [item.port, `${id}.${item.suffix}`]));
+ return {
+ records,
+ fragments: [plan.fragment],
+ components: [{ id, fragment: plan.fragment.id, inputs, outputs, range: element.range }],
+ exports: Object.values(outputs),
+ };
+};
+
+export const decodeClockSurface: StructuredSurfaceHandler = ({ element }) => {
+ assertAttributes(element, ["id", "frame-rate"]); assertEmptyElement(element);
+ const id = textAttribute(element, "id");
+ const raw = textAttribute(element, "frame-rate");
+ const match = /^(\d+)(?:\/(\d+))?$/u.exec(raw);
+ if (match === null) throw new Error(`${element.name}.frame-rate must be a positive rational.`);
+ const numerator = Number(match[1]);
+ const denominator = Number(match[2] ?? 1);
+ if (!Number.isSafeInteger(numerator) || numerator < 1 || !Number.isSafeInteger(denominator) || denominator < 1) {
+ throw new Error(`${element.name}.frame-rate must be a positive rational.`);
+ }
+ const value = { frameRate: { numerator, denominator } };
+ return { records: [{ id, type: timelineTypes.clock, value: { kind: "inline", value: canonicalize(value) }, range: element.range }],
+ components: [], fragments: [], exports: [id] };
+};
+
+/** Publish one reusable absolute Window independently of Timeline construction and consumers. */
+export const decodeAbsoluteWindowSurface: StructuredSurfaceHandler = ({ element, resolveReference }) => {
+ assertAttributes(element, ["id", "timeline", "from", "until", "for"], ["id", "timeline"]);
+ assertEmptyElement(element);
+ const id = textAttribute(element, "id");
+ const context = resolveTemporalContext({ element, resolveReference });
+ const construction = createTemporalWindowConstruction({ id, element, ...context, resolveReference });
+ if (construction.startRef === undefined || construction.endRef === undefined || construction.components.length !== 1) {
+ throw new Error(`${element.name} must construct a Window from exactly two of from, until and for.`);
+ }
+ const component = construction.components[0]!;
+ return {
+ records: construction.records,
+ fragments: construction.fragments,
+ components: [{ ...component, outputs: { window: id, start: `${id}.start`, end: `${id}.end` } }],
+ exports: [id, `${id}.start`, `${id}.end`],
+ };
+};
+
+/** Publish one reusable authored absolute Instant. Existing Instants can be referenced directly. */
+export const decodeAbsoluteInstantSurface: StructuredSurfaceHandler = ({ element, resolveReference }) => {
+ assertAttributes(element, ["id", "timeline", "at"], ["id", "timeline", "at"]);
+ assertEmptyElement(element);
+ if (typeof element.attributes.at !== "string") {
+ throw new Error(`${element.name}.at must be an authored absolute expression; reference an existing Instant directly.`);
+ }
+ const id = textAttribute(element, "id");
+ const context = resolveTemporalContext({ element, resolveReference });
+ const construction = createTemporalInstantConstruction({ id, element, ...context, resolveReference });
+ if (construction.components.length !== 1) throw new Error(`${element.name} did not construct an Instant.`);
+ const component = construction.components[0]!;
return {
- records: [{ id: `${id}.header`, type: timelineAuthorTypes.header, value: { kind: "inline", value: { id, at, ...(element.attributes.end === undefined ? {} : { end: textAttribute(element, "end") }) } }, range: element.range }],
- fragments: [fragment],
- components: [{ id, fragment: fragment.id, inputs: {
- clock: clock.ref,
- header: { kind: "record", id: `${id}.header` },
- ...Object.fromEntries(takes.map((take, index) => [inputs[index]!.takeName, take.ref])),
- }, outputs: { timeline: `${id}.timeline` }, range: element.range }],
- exports: [`${id}.timeline`],
+ records: construction.records,
+ fragments: construction.fragments,
+ components: [{ ...component, outputs: { instant: id } }],
+ exports: [id],
};
};
diff --git a/packages/timeline-author/src/types.ts b/packages/timeline-author/src/types.ts
index 521951f4..60d00dba 100644
--- a/packages/timeline-author/src/types.ts
+++ b/packages/timeline-author/src/types.ts
@@ -1,6 +1,30 @@
-import type { SemanticTake } from "@hypit/speech";
-export type TimelineAuthorHeader = { readonly id: string; readonly at?: readonly string[]; readonly end?: string };
-export type TimelineAuthorTake = { readonly semantic: SemanticTake };
-export type TimelineAuthorSet = { readonly takes: readonly TimelineAuthorTake[] };
-export type TimelineAuthorInput = { readonly takeName: string };
-export type TimelineAuthorFragmentOptions = { readonly takes: readonly TimelineAuthorInput[] };
+import type { TemporalDuration } from "@hypit/temporal";
+
+export type TimelineAuthorHeader = { readonly id: string };
+export type ConstructionPoint = { readonly frame: number };
+export type ConstructionExtent = { readonly frameCount: number };
+export type ConstructionSpan = { readonly startFrame: number; readonly endFrameExclusive: number };
+export type ConstructionOffsetSpec = { readonly direction: 1 | -1 };
+export type ConstructionIdentitySpec = { readonly id: string; readonly subjectId?: string };
+export type ConstructionDurationSpec = TemporalDuration;
+
+export type TimelineInstantDeclaration = {
+ readonly id: string;
+ readonly kind: "instant";
+ readonly at: string;
+};
+export type TimelineWindowDeclaration = {
+ readonly id: string;
+ readonly kind: "window";
+ readonly from?: string;
+ readonly until?: string;
+ readonly duration?: string;
+ readonly extentInput?: string;
+};
+export type TimelineAuthorDeclaration = TimelineInstantDeclaration | TimelineWindowDeclaration;
+
+export type TimelineAuthorFragmentOptions = {
+ readonly id: string;
+ readonly end: string;
+ readonly declarations: readonly TimelineAuthorDeclaration[];
+};
diff --git a/packages/timeline-author/test/program.test.ts b/packages/timeline-author/test/program.test.ts
index 58ee30f6..9f4e49c7 100644
--- a/packages/timeline-author/test/program.test.ts
+++ b/packages/timeline-author/test/program.test.ts
@@ -1,132 +1,99 @@
-import { projectTimelineAudio, projectTimelineMedia } from "@hypit/timeline";
import assert from "node:assert/strict";
import test from "node:test";
-import { fixtureResource } from "../../../test/fixture-resource.js";
+import { createResolvedClosure, link } from "@hypit/core";
+import { verifyGraphFragment } from "@hypit/elaborator";
+import { temporalExtentFromDomain } from "@hypit/temporal";
+import { videoContractManifests } from "../../../test/support/video-domain.js";
-import type { SynchronizedMedia } from "@hypit/media";
-import type { SemanticTake } from "@hypit/speech";
import {
- appendTimelineAuthorTake,
- assembleTimelineAuthor,
- createTimelineAuthorSet,
- sealTimelineAuthorHeader,
+ compileTimelineAuthorFragment,
+ constructionDuration,
+ constructionEarliest,
+ constructionLatest,
+ constructionOffset,
+ constructionOrigin,
+ constructionResolvedExtent,
+ constructionSpan,
+ constructionSpanBetween,
+ constructionSpanEnding,
+ finalizeTimeline,
+ materializeInstant,
+ materializeWindow,
+ timelineAuthorManifest,
} from "@hypit/timeline-author";
-function semantic(id: string, visual: boolean): SemanticTake {
- const media: SynchronizedMedia = {
- timeline: { frameRate: { numerator: 30, denominator: 1 }, frameCount: 30 },
- ...(visual ? { visual: {
- artifact: { kind: "blob", resource: fixtureResource(`${id}:video`), size: 1, mediaType: "video/mp4" },
- width: 720,
- height: 1280,
- } } : {}),
- audio: { artifact: { kind: "blob", resource: fixtureResource(`${id}:audio`), size: 1, mediaType: "audio/wav" } },
- };
- return {
- narrativeId: "test-narrative",
- media,
- segment: {
- segmentId: id,
- startAnchorId: `segment:${id}:start`,
- endAnchorId: `segment:${id}:end`,
- startFrame: 0,
- endFrameExclusive: 30,
- },
- tokens: [],
- anchors: [
- { identity: `segment:${id}:start`, frame: 0 },
- { identity: `segment:${id}:end`, frame: 30 },
- ],
- };
-}
+const clock = { frameRate: { numerator: 30, denominator: 1 } };
+const domain = { id: "voice", frameRate: clock.frameRate, frameCount: 90 };
-test("semantic assembly retains audio and material timing without requiring placement", () => {
- const track = assembleTimelineAuthor(sealTimelineAuthorHeader({ id: "speech" }),
- appendTimelineAuthorTake(appendTimelineAuthorTake(createTimelineAuthorSet(), semantic("voiceover", false)), semantic("answer", true)), { frameRate: { numerator: 30, denominator: 1 } });
- assert.deepEqual(track.items.map(item => item.take.segment.segmentId), ["voiceover", "answer"]);
- const audio = projectTimelineAudio(track);
- assert.deepEqual(audio.clips.map(clip => clip.target), [
- { startSample: 0, endSampleExclusive: 48000 }, { startSample: 48000, endSampleExclusive: 96000 },
- ]);
- const selected = projectTimelineMedia(track, { startFrame: 20, endFrameExclusive: 45 });
- assert.deepEqual(selected.map(({ span, source }) => ({ span, source })), [
- { span: { startFrame: 20, endFrameExclusive: 30 }, source: { startFrame: 20, endFrameExclusive: 30 } },
- { span: { startFrame: 30, endFrameExclusive: 45 }, source: { startFrame: 0, endFrameExclusive: 15 } },
- ]);
- assert.equal(selected[0]!.media.visual, undefined);
- assert.equal(selected[1]!.media.visual?.artifact.resource, fixtureResource("answer:video"));
+test("typed construction operations finalize Timeline before public values", () => {
+ const start = constructionOrigin(clock);
+ const speech = constructionSpan(start, constructionResolvedExtent(clock, temporalExtentFromDomain(domain)));
+ const tailStart = constructionOffset({ frame: speech.endFrameExclusive }, constructionDuration(clock, { unit: "frames", value: 12 }), { direction: 1 });
+ const tail = constructionSpan(tailStart, constructionDuration(clock, { unit: "seconds", numerator: 3, denominator: 1 }));
+ const timeline = finalizeTimeline({ id: "film" }, clock, constructionLatest({ frame: speech.endFrameExclusive }, { frame: tail.endFrameExclusive }));
+ const speechWindow = materializeWindow(timeline, speech, { id: "film.speech" });
+ assert.equal(timeline.frameCount, 192);
+ assert.equal(materializeInstant(timeline, tailStart, { id: "film.tail-start" }).frame, 102);
+ assert.deepEqual(materializeWindow(timeline, tail, { id: "film.tail" }).span, { startFrame: 102, endFrameExclusive: 192 });
});
-const clock = { frameRate: { numerator: 30, denominator: 1 } };
-function placed(end: string | undefined, at: readonly string[], lengths: readonly number[]) {
- let set = createTimelineAuthorSet();
- for (const [i, length] of lengths.entries()) {
- const take = semantic(`take-${i}`, true);
- set = appendTimelineAuthorTake(set, { ...take,
- media: { ...take.media, timeline: { ...take.media.timeline, frameCount: length } },
- segment: { ...take.segment, endFrameExclusive: length },
- anchors: [take.anchors[0]!, { ...take.anchors[1]!, frame: length }],
- });
- }
- return assembleTimelineAuthor({ id: "program", at, ...(end === undefined ? {} : { end }) }, set, clock);
-}
+test("Window construction covers forward, backward and boundary-pair forms", () => {
+ const extent = constructionDuration(clock, { unit: "frames", value: 12 });
+ assert.deepEqual(constructionSpan({ frame: 10 }, extent), { startFrame: 10, endFrameExclusive: 22 });
+ assert.deepEqual(constructionSpanEnding({ frame: 22 }, extent), { startFrame: 10, endFrameExclusive: 22 });
+ assert.deepEqual(constructionSpanBetween({ frame: 10 }, { frame: 22 }), { startFrame: 10, endFrameExclusive: 22 });
+ assert.deepEqual(constructionEarliest({ frame: 10 }, { frame: 22 }), { frame: 10 });
+ assert.throws(() => constructionSpanEnding({ frame: 5 }, extent), /before start/);
+});
-test("one Timeline supports leading, interior and trailing gaps without source material", () => {
- const timeline = placed("30s", ["2s", "22s"], [180, 180]);
- assert.equal(timeline.durationSec, 30);
- assert.deepEqual(timeline.items.map(item => item.startFrame), [60, 660]);
- for (const [startFrame, endFrameExclusive] of [[0, 60], [240, 660], [840, 900]]) {
- assert.deepEqual(projectTimelineMedia(timeline, { startFrame: startFrame!, endFrameExclusive: endFrameExclusive! }), []);
- }
- assert.deepEqual(projectTimelineAudio(timeline).clips.map(clip => clip.target), [
- { startSample: 96000, endSampleExclusive: 384000 },
- { startSample: 1056000, endSampleExclusive: 1344000 },
- ]);
+test("construction rejects negative Point", () => {
+ assert.throws(() => constructionOffset({ frame: 5 }, { frameCount: 6 }, { direction: -1 }), /before start/);
});
-test("overlap retains both sources; content end is the latest end rather than declaration order", () => {
- const timeline = placed("content.end+2s", ["2s", "previous.end-12f", "3s"], [180, 60, 30]);
- assert.deepEqual(timeline.items.map(item => item.startFrame), [60, 228, 90]);
- assert.equal(timeline.durationSec, 348 / 30);
- const samples = projectTimelineMedia(timeline, { startFrame: 228, endFrameExclusive: 240 });
- assert.deepEqual(samples.map(sample => sample.source), [
- { startFrame: 168, endFrameExclusive: 180 }, { startFrame: 0, endFrameExclusive: 12 },
+test("Surface planning lowers author Instants and Windows to typed graph operations", () => {
+ const plan = compileTimelineAuthorFragment({
+ id: "film",
+ end: "latest(speech.end,outro.end)",
+ declarations: [
+ { id: "outro", kind: "window", from: "claim", duration: "3s" },
+ { id: "claim", kind: "instant", at: "speech.end-12f" },
+ { id: "speech", kind: "window", from: "start", extentInput: "voice-extent" },
+ ],
+ });
+ assert.deepEqual(plan.outputNames.map((item) => item.suffix), [
+ "timeline", "window", "start", "end",
+ "outro", "outro.start", "outro.end", "claim", "speech", "speech.start", "speech.end",
]);
- assert.equal(projectTimelineAudio(timeline).clips.length, 3);
+ assert(plan.fragment.operations.some((item) => item.producer.name === "latest-point"));
+ assert(plan.fragment.operations.some((item) => item.id === "decl:claim:point"));
+ assert.deepEqual(plan.extentInputs, [{ name: "voice-extent", declarationId: "speech" }]);
+ assert.equal(JSON.stringify(plan.fragment).includes("speech.end-12f"), false);
+ verifyGraphFragment(link(createResolvedClosure([...videoContractManifests, timelineAuthorManifest]), []), plan.fragment);
});
-test("a zero-Take Timeline supplies its Clock and extent without a Narrative or audio", () => {
- const timeline = assembleTimelineAuthor({ id: "animation", end: "30s" }, createTimelineAuthorSet(), clock);
- assert.equal(timeline.narrativeId, undefined);
- assert.equal(timeline.durationSec, 30);
- assert.deepEqual(timeline.items, []);
- assert.deepEqual(projectTimelineMedia(timeline), []);
- assert.deepEqual(projectTimelineAudio(timeline).clips, []);
- assert.throws(() => assembleTimelineAuthor({ id: "animation" }, createTimelineAuthorSet(), clock), /positive end/);
-});
+test("typed graph verification rejects real cycles while named side anchors stay public", () => {
+ const program = link(createResolvedClosure([...videoContractManifests, timelineAuthorManifest]), []);
+ const cyclic = compileTimelineAuthorFragment({
+ id: "film",
+ end: "a",
+ declarations: [
+ { id: "a", kind: "instant", at: "b" },
+ { id: "b", kind: "instant", at: "a" },
+ ],
+ });
+ assert.throws(() => verifyGraphFragment(program, cyclic.fragment), /cycles through/);
-test("placement rejects missing predecessors, negative starts, fractional frames and clipped content", () => {
- assert.throws(() => placed(undefined, ["previous.end"], [30]), /no preceding/);
- assert.throws(() => placed(undefined, ["0f", "previous.end-2s"], [30, 30]), /non-negative/);
- assert.throws(() => placed(undefined, ["0.01s"], [30]), /exact frame/);
- assert.throws(() => placed("1s", ["2s"], [30]), /precedes placed content/);
-});
+ const endCycle = compileTimelineAuthorFragment({
+ id: "film",
+ end: "tail.end",
+ declarations: [{ id: "tail", kind: "window", until: "end", duration: "1s" }],
+ });
+ assert.throws(() => verifyGraphFragment(program, endCycle.fragment), /cycles through/);
-test("word and Selection locations translate with the Take without reordering authored endpoints", async () => {
- const { semanticAnchorFrames, selectionFrameSpan, momentFrame, tokenFrameSpan } = await import("@hypit/timeline");
- const base = semantic("opening", true);
- const take = { ...base, tokens: [{ tokenId: "word", segmentId: "opening", text: "Hello",
- startAnchorId: "word:start", endAnchorId: "word:end", startFrame: 5, endFrameExclusive: 20 }],
- anchors: [...base.anchors, { identity: "word:start", frame: 5 }, { identity: "word:end", frame: 20 }] };
- const timeline = assembleTimelineAuthor({ id: "program", at: ["2s"], end: "5s" },
- appendTimelineAuthorTake(createTimelineAuthorSet(), take), clock);
- assert.deepEqual(tokenFrameSpan(timeline, ["word"]), { startFrame: 65, endFrameExclusive: 80 });
- assert.equal(momentFrame(timeline, { narrativeId: take.narrativeId, id: "cue", anchorId: "word:start" }), 65);
- assert.deepEqual(selectionFrameSpan(timeline, { narrativeId: take.narrativeId, id: "selection",
- startAnchorId: "word:end", endAnchorId: "word:start" }), { startFrame: 80, endFrameExclusive: 65 });
- const anchors = semanticAnchorFrames(timeline);
- assert.equal(anchors.get("program:start"), 0);
- assert.equal(anchors.get("program:end"), 150);
- assert.equal(anchors.get(base.segment.startAnchorId), 60);
- assert.deepEqual(take.tokens[0], timeline.items[0]!.take.tokens[0]);
+ const sideAnchor = compileTimelineAuthorFragment({
+ id: "film",
+ end: "3s",
+ declarations: [{ id: "cue", kind: "instant", at: "1s" }],
+ });
+ assert.doesNotThrow(() => verifyGraphFragment(program, sideAnchor.fragment));
});
diff --git a/packages/timeline-author/test/surface.test.ts b/packages/timeline-author/test/surface.test.ts
index b9703b5c..2c27c6b9 100644
--- a/packages/timeline-author/test/surface.test.ts
+++ b/packages/timeline-author/test/surface.test.ts
@@ -1,71 +1,89 @@
-import { programSpaceTypes } from "@hypit/program-space";
import assert from "node:assert/strict";
import test from "node:test";
-import { fixtureResource } from "../../../test/fixture-resource.js";
-import type { StructuredElement, SurfaceResolvedReference } from "@hypit/markup";
-import type { SemanticTake } from "@hypit/speech";
-import { speechTypes } from "@hypit/speech";
-import { decodeTimelineAuthorSurface } from "@hypit/timeline-author";
+import { parseStructuredElement } from "@hypit/markup";
+import { temporalTypes } from "@hypit/temporal";
+import { timelineTypes } from "@hypit/timeline";
+import {
+ decodeAbsoluteInstantSurface,
+ decodeAbsoluteWindowSurface,
+ decodeTimelineAuthorSurface,
+ timelineAuthorMarkupSurfaces,
+ timelineAuthorTypes,
+} from "@hypit/timeline-author";
-const take: SemanticTake = {
- narrativeId: "test-narrative",
- media: {
- timeline: { frameRate: { numerator: 30, denominator: 1 }, frameCount: 30 },
- visual: {
- artifact: { kind: "blob", resource: fixtureResource("track:take:video"), size: 1, mediaType: "video/mp4" },
- width: 720,
- height: 1280,
- },
- audio: {
- artifact: { kind: "blob", resource: fixtureResource("track:take:audio"), size: 1, mediaType: "audio/wav" },
- },
- },
- segment: {
- segmentId: "opening",
- startAnchorId: "opening:start",
- endAnchorId: "opening:end",
- startFrame: 0,
- endFrameExclusive: 30,
- },
- tokens: [],
- anchors: [
- { identity: "opening:start", frame: 0 },
- { identity: "opening:end", frame: 30 },
- ],
-};
+const absoluteReferences = new Map([
+ ["film.timeline", { path: "film.timeline", type: timelineTypes.track, ref: { kind: "record" as const, id: "film.timeline" } }],
+ ["reveal", { path: "reveal", type: temporalTypes.instant, ref: { kind: "record" as const, id: "reveal" } }],
+ ["answer-end", { path: "answer-end", type: temporalTypes.instant, ref: { kind: "record" as const, id: "answer-end" } }],
+]);
-function resolved(path: string): SurfaceResolvedReference | undefined {
- if (path === "clock") return { path, type: programSpaceTypes.clock, ref: { kind: "record", id: path } };
- if (path === "opening.take") return {
- path,
- ref: { kind: "record", id: path },
- type: speechTypes.semanticTake,
- record: { id: path, type: speechTypes.semanticTake, value: { kind: "inline", value: take } },
- };
- return undefined;
-}
-
-test("Timeline accepts only already-semantic Segment Takes", async () => {
- const element: StructuredElement = {
- kind: "element",
- name: "time:Timeline",
- attributes: { id: "speech", clock: { kind: "reference", path: "clock" } },
- children: [{ kind: "element", name: "time:Take",
- attributes: { source: { kind: "reference", path: "opening.take" } }, children: [], range: { start: 20, end: 60 } }],
- range: { start: 0, end: 70 },
- };
+test("Timeline Surface publishes its range and every named Instant or Window", async () => {
+ const source = `<time:Timeline id="film" clock={clock} end="latest(speech.end,outro.end)">
+ <time:Window id="outro" from="private-cue" for="3s"/>
+ <time:Window id="speech" from="start" for={voice.extent}/>
+ <time:Instant id="private-cue" at="speech.end"/>
+ </time:Timeline>`;
+ const element = parseStructuredElement({ name: "timeline.svml", text: source }, 0).element;
+ const references = new Map([
+ ["clock", { path: "clock", type: timelineTypes.clock, ref: { kind: "record" as const, id: "clock" } }],
+ ["voice.extent", { path: "voice.extent", type: temporalTypes.extent, ref: { kind: "record" as const, id: "voice.extent" } }],
+ ]);
const output = await decodeTimelineAuthorSurface({
- sourceName: "main.svml",
- element,
- resolveReference: resolved,
- resolveAsset() { throw new Error("Timeline does not resolve assets"); },
+ sourceName: "timeline.svml", element,
+ resolveReference: (path) => references.get(path),
+ resolveAsset: async () => { throw new Error("unused"); },
});
- assert.deepEqual(output.components[0]?.outputs, {
- timeline: "speech.timeline",
+ assert.deepEqual(output.exports, [
+ "film.timeline", "film.window", "film.start", "film.end",
+ "film.outro", "film.outro.start", "film.outro.end",
+ "film.speech", "film.speech.start", "film.speech.end", "film.private-cue",
+ ]);
+ assert.equal(JSON.stringify(output.fragments).includes("speech.end"), false);
+ assert.equal(JSON.stringify(output.fragments).includes("3s"), false);
+});
+
+test("Timeline Window requires exactly two of from, until and for", () => {
+ const source = '<time:Timeline id="film" clock={clock} end="3s"><time:Window id="bad" from="start"/></time:Timeline>';
+ const element = parseStructuredElement({ name: "timeline.svml", text: source }, 0).element;
+ assert.throws(() => decodeTimelineAuthorSurface({
+ sourceName: "timeline.svml", element,
+ resolveReference: () => ({ path: "clock", type: timelineTypes.clock, ref: { kind: "record", id: "clock" } }),
+ resolveAsset: async () => { throw new Error("unused"); },
+ }), /exactly two/);
+});
+
+test("standalone Window publishes one reusable value and its boundaries", async () => {
+ const element = parseStructuredElement({ name: "timeline.svml", text:
+ '<time:Window id="reveal-band" timeline={film.timeline} from={reveal} until={answer-end}/>' }, 0).element;
+ const output = await decodeAbsoluteWindowSurface({
+ sourceName: "timeline.svml", element,
+ resolveReference: (path) => absoluteReferences.get(path),
+ resolveAsset: async () => { throw new Error("unused"); },
});
- assert.deepEqual(output.exports, ["speech.timeline"]);
- assert.deepEqual(output.fragments?.[0]?.exports.map(port => port.name), ["timeline"]);
- assert.equal(output.records.length, 1);
- assert.deepEqual(output.fragments?.[0]?.inputs.map(input => input.name), ["clock", "header", "take-1"]);
+ assert.deepEqual(output.exports, ["reveal-band", "reveal-band.start", "reveal-band.end"]);
+ assert.deepEqual(output.components[0]?.outputs,
+ { window: "reveal-band", start: "reveal-band.start", end: "reveal-band.end" });
+ assert.equal(output.fragments[0]?.exports.find((port) => port.name === "window")?.type.name, "TemporalWindow");
+ assert.equal(output.fragments[0]?.exports.filter((port) => port.type.name === "TemporalInstant").length, 2);
+});
+
+test("standalone Instant publishes an authored absolute point and does not alias another domain value", async () => {
+ const literal = parseStructuredElement({ name: "timeline.svml", text:
+ '<time:Instant id="credits" timeline={film.timeline} at="timeline.end-2s"/>' }, 0).element;
+ const output = await decodeAbsoluteInstantSurface({
+ sourceName: "timeline.svml", element: literal,
+ resolveReference: (path) => absoluteReferences.get(path),
+ resolveAsset: async () => { throw new Error("unused"); },
+ });
+ assert.deepEqual(output.exports, ["credits"]);
+ assert.deepEqual(output.components[0]?.outputs, { instant: "credits" });
+
+ const alias = parseStructuredElement({ name: "timeline.svml", text:
+ '<time:Instant id="renamed" timeline={film.timeline} at={reveal}/>' }, 0).element;
+ assert.throws(() => decodeAbsoluteInstantSurface({
+ sourceName: "timeline.svml", element: alias,
+ resolveReference: (path) => absoluteReferences.get(path),
+ resolveAsset: async () => { throw new Error("unused"); },
+ }), /reference an existing Instant directly/);
});
diff --git a/packages/timeline/README.md b/packages/timeline/README.md
index c1d1422d..5da0114e 100644
--- a/packages/timeline/README.md
+++ b/packages/timeline/README.md
@@ -1,31 +1,29 @@
# `@hypit/timeline`
-One Timeline describes the complete film time range and the prepared Takes placed within it.
-Semantic anchors exist wherever those Takes supply them; no second kind of time axis is needed
-for authored animation. The value stores `id`, `durationSec`, `frameRate`, optional `narrativeId`,
-and `items` containing `take` and `startFrame`. A zero-Take Timeline has no Narrative identity.
-
-Each Take retains its normalized local media and semantic evidence. Global positions are its
-placement start plus local positions. Items can leave gaps or overlap; their declaration order is
-preserved. Frame rates and Narrative ownership agree, identities remain unique, and every complete
-Take fits inside the positive Program range. Assembly is owned by
-[Timeline authoring](../timeline-author/README.md).
-
-`projectTimelineSpace` supplies the lightweight `ProgramSpace` range used by rendering.
-`semanticAnchorFrames`, `selectionFrameSpan`, `segmentFrameSpan`, `tokenFrameSpan` and `momentFrame`
-locate evidence without copying another word table. Program boundaries are available even with zero
-Takes. Selection endpoints retain their authored identities; projection/consumption determines
-whether a requested physical Window is usable.
-
-## Project prepared material
-
-`projectTimelineMedia(timeline, window?)` returns every intersecting Take's `media`, `segmentId`,
-global `span` and local `source` frame span. The default Window is the complete Timeline. Gaps
-return no source; overlaps return all intersecting sources. Audio-only Takes remain represented.
-Starting presentation inside a Take retains the matching source frame. This projection chooses no
-layout, winning picture, held frame or transition.
-
-`projectTimelineAudio` places original audio at each Take's position at native speed and gain.
-Takes without audio contribute no clip; gaps are silent and overlapping Takes contribute simultaneous
-clips. Film explicitly includes that audio contribution. These functions perform no media I/O,
-transcription, rendering or generation.
+Domain contract for one finite absolute program-time axis.
+
+A completed `Timeline` contains only:
+
+- `id`;
+- exact rational `frameRate`; and
+- positive finite `frameCount`.
+
+It contains no media, semantic anchors, Tracks, Canvas, author declarations or central event registry.
+Every consumer that shares program time receives the same Timeline value explicitly.
+
+[`@hypit/timeline-author`](../timeline-author/README.md) constructs this value from an acyclic graph
+of named Instants, Windows and typed Extents with one required exclusive `end`. Each named declaration
+naturally publishes an absolute sibling value after finalization. Local domains and media are never
+fields stored inside Timeline.
+
+Semantic time is an optional projection onto this absolute axis. A `NarrativeAlignment` locates Script
+anchors in a local temporal domain; the Narrative projector maps that domain through an equal-length
+Window to resolve absolute Instants and Windows. Other domains such as musical beats
+can provide peer adapters without extending Timeline.
+
+Media presentation is independent as well. Visual and Audio Clips consume ordinary normalized
+media with explicit absolute Windows, without asking Timeline to discover material or retaining whether
+that media's Extent helped construct it.
+
+This package validates and seals the completed value. It performs no media I/O, transcription,
+generation, rendering, projection policy or Studio behavior.
diff --git a/packages/timeline/package.json b/packages/timeline/package.json
index 97a1986f..3faf8296 100644
--- a/packages/timeline/package.json
+++ b/packages/timeline/package.json
@@ -12,11 +12,6 @@
},
"dependencies": {
"@hypit/component-kit": "workspace:*",
- "@hypit/composition": "workspace:*",
- "@hypit/media": "workspace:*",
- "@hypit/narrative": "workspace:*",
- "@hypit/program-space": "workspace:*",
- "@hypit/protocol": "workspace:*",
- "@hypit/speech": "workspace:*"
+ "@hypit/protocol": "workspace:*"
}
}
diff --git a/packages/timeline/src/component.ts b/packages/timeline/src/component.ts
index ef3e1b1a..7a3a5a2a 100644
--- a/packages/timeline/src/component.ts
+++ b/packages/timeline/src/component.ts
@@ -1,10 +1,7 @@
import type { ComponentPackage } from "@hypit/component-kit";
import type { StoredValue } from "@hypit/protocol";
-import { canonicalize } from "@hypit/protocol";
-
-import { timelineProducers, timelineTypes } from "./manifest.js";
+import { timelineTypes } from "./manifest.js";
import { assertTimelineIdentity } from "./identity.js";
-import { projectTimelineAudio, projectTimelineSpace } from "./projection.js";
import type { Timeline } from "./types.js";
function track(value: StoredValue | undefined): Timeline {
@@ -13,10 +10,7 @@ function track(value: StoredValue | undefined): Timeline {
}
export const timelineComponent = {
- producers: [
- { producer: timelineProducers.projectProgramSpace, handler: ({ inputs }) => ({ outputs: { space: { kind: "inline", value: canonicalize(projectTimelineSpace(track(inputs.track?.value))) } }, needs: {} }) },
- { producer: timelineProducers.projectAudio, handler: ({ inputs }) => ({ outputs: { audio: { kind: "inline", value: canonicalize(projectTimelineAudio(track(inputs.track?.value))) } }, needs: {} }) },
- ],
+ producers: [],
validators: [{
type: timelineTypes.track,
handler: ({ value }) => assertTimelineIdentity(track(value)),
diff --git a/packages/timeline/src/identity.ts b/packages/timeline/src/identity.ts
index 8ed4ec9a..b19fb571 100644
--- a/packages/timeline/src/identity.ts
+++ b/packages/timeline/src/identity.ts
@@ -1,60 +1,59 @@
-import { assertProgramSpaceIdentity, programSpaceFrameCount } from "@hypit/program-space";
-import { assertSemanticTakeIdentity } from "@hypit/speech";
+import type { Clock, Timeline } from "./types.js";
-import type { Timeline, TimelineSpan } from "./types.js";
+export function sealClock(value: Clock): Clock {
+ assertClockIdentity(value);
+ return structuredClone(value);
+}
+
+export function assertClockIdentity(clock: Clock): void {
+ const { numerator, denominator } = clock.frameRate;
+ if (!Number.isSafeInteger(numerator) || numerator <= 0
+ || !Number.isSafeInteger(denominator) || denominator <= 0) {
+ throw new Error("Clock is invalid.");
+ }
+}
export function sealTimeline(value: Timeline): Timeline {
- const track = structuredClone(value);
- assertTimelineIdentity(track);
- return track;
-}
-
-export function assertTimelineIdentity(track: Timeline): void {
- assertProgramSpaceIdentity(track);
- const frameCount = programSpaceFrameCount(track);
- if (track.items.length > 0 && !track.narrativeId?.trim()) throw new Error("A Timeline with Takes requires their Narrative identity.");
- if (track.items.length === 0 && track.narrativeId !== undefined) throw new Error("An empty Timeline has no Narrative identity.");
- const segmentIds = new Set<string>();
- const tokenIds = new Set<string>();
- const anchorIds = new Set<string>();
- const frameRate = track.frameRate;
- for (const item of track.items) {
- assertSemanticTakeIdentity(item.take);
- if (!Number.isSafeInteger(item.startFrame) || item.startFrame < 0
- || item.startFrame + item.take.media.timeline.frameCount > frameCount) {
- throw new Error(`Timeline placement for ${item.take.segment.segmentId} is outside its Program range.`);
- }
- if (item.take.narrativeId !== track.narrativeId) {
- throw new Error(`Timeline ${track.id} mixes Narrative ${item.take.narrativeId} into ${track.narrativeId}.`);
- }
- const rate = item.take.media.timeline.frameRate;
- if (frameRate.numerator !== rate.numerator || frameRate.denominator !== rate.denominator) {
- throw new Error("Timeline items must use one frame rate.");
- }
- const segmentId = item.take.segment.segmentId;
- if (segmentIds.has(segmentId)) throw new Error(`Timeline repeats Segment ${segmentId}.`);
- segmentIds.add(segmentId);
- for (const token of item.take.tokens) {
- if (tokenIds.has(token.tokenId)) throw new Error(`Timeline repeats Token ${token.tokenId}.`);
- tokenIds.add(token.tokenId);
- }
- for (const anchor of item.take.anchors) {
- if (anchor.identity === "program:start" || anchor.identity === "program:end") {
- throw new Error(`SemanticTake cannot declare reserved Program Anchor ${anchor.identity}.`);
- }
- if (anchorIds.has(anchor.identity)) throw new Error(`Timeline repeats Anchor ${anchor.identity}.`);
- anchorIds.add(anchor.identity);
- }
+ assertTimelineIdentity(value);
+ return structuredClone(value);
+}
+
+export function assertTimelineIdentity(timeline: Timeline): void {
+ assertClockIdentity(timeline);
+ if (!timeline.id.trim() || !Number.isSafeInteger(timeline.frameCount) || timeline.frameCount < 1) {
+ throw new Error("Timeline is invalid.");
}
}
-export function timelineSpans(track: Timeline): readonly TimelineSpan[] {
- assertTimelineIdentity(track);
- return track.items.map(item => ({ item, startFrame: item.startFrame,
- endFrameExclusive: item.startFrame + item.take.media.timeline.frameCount }));
+export function timelineFrameCount(timeline: Timeline): number {
+ assertTimelineIdentity(timeline);
+ return timeline.frameCount;
+}
+
+export function timelineDurationSeconds(timeline: Timeline): number {
+ assertTimelineIdentity(timeline);
+ return timeline.frameCount * timeline.frameRate.denominator / timeline.frameRate.numerator;
+}
+
+export function timelineSampleFrames(timeline: Timeline, sampleRate: number): number {
+ return timelineFrameSampleBoundary(timeline, timelineFrameCount(timeline), sampleRate);
+}
+
+export function timelineFrameSampleBoundary(timeline: Timeline, frame: number, sampleRate: number): number {
+ const frames = timelineFrameCount(timeline);
+ if (!Number.isSafeInteger(frame) || frame < 0 || frame > frames) {
+ throw new Error("Timeline frame boundary is invalid.");
+ }
+ return clockFrameSampleBoundary(timeline, frame, sampleRate);
}
-export function timelineFrameCount(track: Timeline): number {
- assertTimelineIdentity(track);
- return programSpaceFrameCount(track);
+export function clockFrameSampleBoundary(clock: Clock, frame: number, sampleRate: number): number {
+ assertClockIdentity(clock);
+ if (!Number.isSafeInteger(frame) || frame < 0) throw new Error("Clock frame boundary is invalid.");
+ if (!Number.isSafeInteger(sampleRate) || sampleRate <= 0) throw new Error("Timeline sample rate is invalid.");
+ const numerator = BigInt(frame) * BigInt(sampleRate) * BigInt(clock.frameRate.denominator);
+ const denominator = BigInt(clock.frameRate.numerator);
+ const value = (numerator * 2n + denominator) / (denominator * 2n);
+ if (value < 0n || value > BigInt(Number.MAX_SAFE_INTEGER)) throw new Error("Timeline sample domain exceeds safe arithmetic.");
+ return Number(value);
}
diff --git a/packages/timeline/src/index.ts b/packages/timeline/src/index.ts
index 6f1cf7a0..aa7fe875 100644
--- a/packages/timeline/src/index.ts
+++ b/packages/timeline/src/index.ts
@@ -1,6 +1,4 @@
export { timelineComponent } from "./component.js";
-export { assertTimelineIdentity, sealTimeline, timelineFrameCount, timelineSpans } from "./identity.js";
-export { assertNarrativeMomentIdentity, assertNarrativeSelectionIdentity, momentFrame, segmentFrameSpan, selectionFrameSpan, semanticAnchorFrames, tokenFrameSpan } from "./location.js";
-export { timelineDependency, timelineManifest, timelineModuleRef, timelineProducers, timelineSchema, timelineTypes } from "./manifest.js";
-export { projectTimelineAudio, projectTimelineSpace, projectTimelineMedia } from "./projection.js";
+export { assertClockIdentity, assertTimelineIdentity, clockFrameSampleBoundary, sealClock, sealTimeline, timelineDurationSeconds, timelineFrameCount, timelineFrameSampleBoundary, timelineSampleFrames } from "./identity.js";
+export { clockSchema, timelineDependency, timelineManifest, timelineModuleRef, timelineSchema, timelineTypes } from "./manifest.js";
export type * from "./types.js";
diff --git a/packages/timeline/src/location.ts b/packages/timeline/src/location.ts
deleted file mode 100644
index c7849d5f..00000000
--- a/packages/timeline/src/location.ts
+++ /dev/null
@@ -1,81 +0,0 @@
-import type { NarrativeExcerpt, NarrativeMomentRef, NarrativeSelectionRef } from "@hypit/narrative";
-
-import { assertTimelineIdentity, timelineFrameCount, timelineSpans } from "./identity.js";
-import type { LocatedFrameSpan, Timeline } from "./types.js";
-
-export function assertNarrativeSelectionIdentity(selection: NarrativeSelectionRef): void {
- if (!selection.narrativeId || !selection.id || !selection.startAnchorId || !selection.endAnchorId) throw new Error("NarrativeSelection is invalid");
-}
-
-export function assertNarrativeMomentIdentity(moment: NarrativeMomentRef): void {
- if (!moment.narrativeId || !moment.id || !moment.anchorId) throw new Error("NarrativeMoment is invalid");
-}
-
-function assertNarrativeOwner(track: Timeline, narrativeId: string, label: string): void {
- if (narrativeId !== track.narrativeId) {
- throw new Error(`${label} belongs to Narrative ${narrativeId}, not Timeline ${track.id}.`);
- }
-}
-
-export function semanticAnchorFrames(track: Timeline): ReadonlyMap<string, number> {
- assertTimelineIdentity(track);
- return new Map([
- ["program:start", 0] as const,
- ...timelineSpans(track).flatMap(({ item, startFrame }) =>
- item.take.anchors.map((anchor) => [anchor.identity, startFrame + anchor.frame] as const)),
- ["program:end", timelineFrameCount(track)] as const,
- ]);
-}
-
-function frameFor(frames: ReadonlyMap<string, number>, anchorId: string, owner: string): number {
- const frame = frames.get(anchorId);
- if (frame === undefined) throw new Error(`${owner} names Anchor ${anchorId}, which this Timeline does not contain.`);
- return frame;
-}
-
-export function selectionFrameSpan(
- track: Timeline,
- selection: NarrativeSelectionRef,
-): LocatedFrameSpan {
- assertTimelineIdentity(track);
- assertNarrativeSelectionIdentity(selection);
- assertNarrativeOwner(track, selection.narrativeId, `NarrativeSelection ${selection.id}`);
- const frames = semanticAnchorFrames(track);
- return {
- startFrame: frameFor(frames, selection.startAnchorId, `NarrativeSelection ${selection.id}`),
- endFrameExclusive: frameFor(frames, selection.endAnchorId, `NarrativeSelection ${selection.id}`),
- };
-}
-
-export function segmentFrameSpan(track: Timeline, segment: NarrativeExcerpt): LocatedFrameSpan {
- assertTimelineIdentity(track);
- if (segment.kind !== "segment" || !segment.id) throw new Error("Narrative Segment excerpt is invalid");
- assertNarrativeOwner(track, segment.narrativeId, `Narrative Segment ${segment.id}`);
- const found = timelineSpans(track).find(({ item }) => item.take.segment.segmentId === segment.id);
- if (found === undefined) throw new Error(`Timeline does not contain Segment ${segment.id}.`);
- return { startFrame: found.startFrame, endFrameExclusive: found.endFrameExclusive };
-}
-
-export function tokenFrameSpan(track: Timeline, tokenIds: readonly string[]): LocatedFrameSpan | undefined {
- assertTimelineIdentity(track);
- if (tokenIds.length === 0) return undefined;
- const timing = new Map(timelineSpans(track).flatMap(({ item, startFrame }) =>
- item.take.tokens.map((token) => [token.tokenId, {
- startFrame: startFrame + token.startFrame,
- endFrameExclusive: startFrame + token.endFrameExclusive,
- }] as const)));
- const located = tokenIds.map((id) => timing.get(id));
- if (located.some((item) => item === undefined)) return undefined;
- return {
- startFrame: located[0]!.startFrame,
- endFrameExclusive: located.at(-1)!.endFrameExclusive,
- };
-}
-
-export function momentFrame(track: Timeline, moment: NarrativeMomentRef): number {
- assertTimelineIdentity(track);
- assertNarrativeMomentIdentity(moment);
- assertNarrativeOwner(track, moment.narrativeId, `NarrativeMoment ${moment.id}`);
- const frames = semanticAnchorFrames(track);
- return frameFor(frames, moment.anchorId, `NarrativeMoment ${moment.id}`);
-}
diff --git a/packages/timeline/src/manifest.ts b/packages/timeline/src/manifest.ts
index 58cc1ce6..1fdffa2f 100644
--- a/packages/timeline/src/manifest.ts
+++ b/packages/timeline/src/manifest.ts
@@ -1,39 +1,33 @@
-import { compositionDependency, compositionTypes } from "@hypit/composition";
-import { narrativeDependency } from "@hypit/narrative";
-import { programSpaceDependency, programSpaceSchema, programSpaceTypes } from "@hypit/program-space";
-import type { ModuleManifest, ProducerRef, TypeRef, ValueSchema } from "@hypit/protocol";
-import { semanticTakeSchema, speechDependency } from "@hypit/speech";
+import type { ModuleManifest, TypeRef, ValueSchema } from "@hypit/protocol";
export const timelineModuleRef = { name: "@hypit/timeline", version: "1" } as const;
export const timelineTypes = {
track: { module: timelineModuleRef, name: "Timeline" },
+ clock: { module: timelineModuleRef, name: "Clock" },
} satisfies Record<string, TypeRef>;
-export const timelineProducers = {
- projectProgramSpace: { module: timelineModuleRef, name: "project-program-space" },
- projectAudio: { module: timelineModuleRef, name: "project-audio-track" },
-} satisfies Record<string, ProducerRef>;
const string = { kind: "string", minLength: 1 } as const;
+const positiveInteger = { kind: "number", integer: true, minimum: 1 } as const;
const object = (fields: Readonly<Record<string, { readonly schema: ValueSchema; readonly optional?: boolean }>>): ValueSchema => ({ kind: "object", fields });
+export const clockSchema: ValueSchema = object({
+ frameRate: { schema: object({
+ numerator: { schema: positiveInteger },
+ denominator: { schema: positiveInteger },
+ }) },
+});
export const timelineSchema: ValueSchema = object({
- ...(programSpaceSchema.kind === "object" ? programSpaceSchema.fields : {}),
- narrativeId: { schema: string, optional: true },
- items: { schema: { kind: "array", items: object({
- startFrame: { schema: { kind: "number", integer: true, minimum: 0 } },
- take: { schema: semanticTakeSchema },
- }) } },
+ id: { schema: string },
+ ...(clockSchema.kind === "object" ? clockSchema.fields : {}),
+ frameCount: { schema: positiveInteger },
});
export const timelineManifest: ModuleManifest = {
format: "hypit.module@1",
name: timelineModuleRef.name,
version: timelineModuleRef.version,
- dependencies: [speechDependency, narrativeDependency, programSpaceDependency, compositionDependency],
- types: [{ name: timelineTypes.track.name }],
+ dependencies: [],
+ types: [{ name: timelineTypes.track.name }, { name: timelineTypes.clock.name }],
capabilities: [],
- producers: [
- { name: timelineProducers.projectProgramSpace.name, inputs: [{ name: "track", type: timelineTypes.track }], outputs: [{ name: "space", type: programSpaceTypes.programSpace }], needs: [] },
- { name: timelineProducers.projectAudio.name, inputs: [{ name: "track", type: timelineTypes.track }], outputs: [{ name: "audio", type: compositionTypes.audioTrack }], needs: [] },
- ],
+ producers: [],
};
export const timelineDependency = { module: timelineModuleRef } as const;
diff --git a/packages/timeline/src/projection.ts b/packages/timeline/src/projection.ts
deleted file mode 100644
index 5f8c9c8f..00000000
--- a/packages/timeline/src/projection.ts
+++ /dev/null
@@ -1,71 +0,0 @@
-import { sealAudioTrack } from "@hypit/composition";
-import type { AudioTrack } from "@hypit/composition";
-import { synchronizedMediaSampleFrames } from "@hypit/media";
-import {
- programFrameSampleBoundary,
- sealProgramSpace,
-} from "@hypit/program-space";
-import type { ProgramSpace } from "@hypit/program-space";
-
-import { assertTimelineIdentity, timelineFrameCount, timelineSpans } from "./identity.js";
-import type { Timeline } from "./types.js";
-
-/** Prepared material in an authored program interval, with its original source position retained. */
-export function projectTimelineMedia(track: Timeline, window = {
- startFrame: 0, endFrameExclusive: timelineFrameCount(track),
-}) {
- assertTimelineIdentity(track);
- if (!Number.isSafeInteger(window.startFrame) || !Number.isSafeInteger(window.endFrameExclusive)
- || window.startFrame < 0 || window.endFrameExclusive <= window.startFrame
- || window.endFrameExclusive > timelineFrameCount(track)) throw new Error("Semantic media window is outside the performance.");
- return timelineSpans(track).flatMap(({ item, startFrame, endFrameExclusive }) => {
- const start = Math.max(window.startFrame, startFrame);
- const end = Math.min(window.endFrameExclusive, endFrameExclusive);
- return end <= start ? [] : [{
- segmentId: item.take.segment.segmentId,
- media: item.take.media,
- span: { startFrame: start, endFrameExclusive: end },
- source: { startFrame: start - startFrame, endFrameExclusive: end - startFrame },
- }];
- });
-}
-
-export function projectTimelineSpace(track: Timeline): ProgramSpace {
- assertTimelineIdentity(track);
- const frameRate = track.frameRate;
- return sealProgramSpace({
- id: track.id,
- durationSec: track.durationSec,
- frameRate,
- });
-}
-
-export function projectTimelineAudio(track: Timeline): AudioTrack {
- const space = projectTimelineSpace(track);
- const clips = timelineSpans(track).flatMap(({ item, startFrame, endFrameExclusive }) => {
- const audio = item.take.media.audio;
- if (audio === undefined) return [];
- const sourceSampleFrames = synchronizedMediaSampleFrames(item.take.media);
- const targetStartSample = programFrameSampleBoundary(space, startFrame, 48_000);
- const targetEndSampleExclusive = programFrameSampleBoundary(space, endFrameExclusive, 48_000);
- return [{
- id: item.take.segment.segmentId,
- subjectId: item.take.segment.segmentId,
- artifact: audio.artifact,
- target: { startSample: targetStartSample, endSampleExclusive: targetEndSampleExclusive },
- source: {
- sampleFrames: sourceSampleFrames,
- startSample: 0,
- endSampleExclusive: sourceSampleFrames,
- loop: false,
- phaseSample: 0,
- },
- playbackRate: 1,
- pitch: "preserve" as const,
- gain: 1,
- fadeInSamples: 0,
- fadeOutSamples: 0,
- }];
- });
- return sealAudioTrack({ programSpaceId: space.id, id: `${track.id}:audio`, clips });
-}
diff --git a/packages/timeline/src/types.ts b/packages/timeline/src/types.ts
index 382d1f1e..80ab191c 100644
--- a/packages/timeline/src/types.ts
+++ b/packages/timeline/src/types.ts
@@ -1,21 +1,14 @@
-import type { ProgramSpace } from "@hypit/program-space";
-import type { SemanticTake } from "@hypit/speech";
-
-export type TimelineItem = {
- readonly take: SemanticTake;
- readonly startFrame: number;
-};
-
-/** One complete film time range, with prepared material placed where it belongs. */
-export type Timeline = ProgramSpace & {
- readonly narrativeId?: string;
- readonly items: readonly TimelineItem[];
+/** The discrete sampling clock shared by one authored Timeline and its material. */
+export type Clock = {
+ readonly frameRate: { readonly numerator: number; readonly denominator: number };
};
-export type TimelineSpan = {
- readonly item: TimelineItem;
- readonly startFrame: number;
- readonly endFrameExclusive: number;
+/** One complete, content-independent absolute frame domain. */
+export type Timeline = Clock & {
+ /** Author-visible identity of this film time axis. */
+ readonly id: string;
+ /** Boundary after the final rendered frame. */
+ readonly frameCount: number;
};
export type LocatedFrameSpan = {
diff --git a/packages/typography-track-studio/README.md b/packages/typography-track-studio/README.md
deleted file mode 100644
index 0a931e29..00000000
--- a/packages/typography-track-studio/README.md
+++ /dev/null
@@ -1,3 +0,0 @@
-# `@hypit/typography-track-studio`
-
-Hypit Studio Companion for `@hypit/typography-track`.
diff --git a/packages/typography-track-studio/src/activation.ts b/packages/typography-track-studio/src/activation.ts
deleted file mode 100644
index befae114..00000000
--- a/packages/typography-track-studio/src/activation.ts
+++ /dev/null
@@ -1,7 +0,0 @@
-import { createStudioTrackCompanionHostFacet } from "@hypit/studio-adapter";
-import { typographyTrackStudioTrackCompanions } from "./index.js";
-
-export default {
- format: "hypit.node-package@1" as const,
- hostFacets: [createStudioTrackCompanionHostFacet(typographyTrackStudioTrackCompanions)],
-};
diff --git a/packages/typography-track-studio/src/index.ts b/packages/typography-track-studio/src/index.ts
deleted file mode 100644
index 96cb9f67..00000000
--- a/packages/typography-track-studio/src/index.ts
+++ /dev/null
@@ -1,120 +0,0 @@
-import { openFontStudioFields } from "@hypit/fonts-open/studio";
-import { typographyTrackMarkupSurfaces, typographyTrackModuleRef, typographyTrackTypes } from "@hypit/typography-track";
-import type { TypographyTrackProgram } from "@hypit/typography-track";
-import { compositionTypes } from "@hypit/composition";
-import type { StudioTrackCompanion, StudioTrackCompanionContext, StudioEntityDraft, StudioInspectorFieldDeclaration } from "@hypit/studio-adapter";
-import { childEntities, requiredSurfaceValue, temporalLineageFor, temporalSemanticSource, textLayer } from "@hypit/studio-adapter";
-
-const fontInspector = openFontStudioFields("style");
-
-const typographyProperties = (typographyTrackMarkupSurfaces
- .find((surface) => surface.name === "style")?.vocabulary.attributes
- .find((attribute) => attribute.name === "recipe")?.recipe ?? []);
-
-function title(name: string): string {
- return name.split("-").map((part) => `${part.slice(0, 1).toUpperCase()}${part.slice(1)}`).join(" ");
-}
-
-function valuesFor(property: typeof typographyProperties[number]): readonly string[] | undefined {
- return "values" in property ? property.values : undefined;
-}
-
-type TypographyPlacement = Pick<StudioInspectorFieldDeclaration, "domain" | "page" | "section">;
-
-function typographyPlace(domain: "where" | "how", page: string, section: string): TypographyPlacement {
- const id = section.toLowerCase().replaceAll(" ", "-");
- return { domain, page: { id: page.toLowerCase(), label: page }, section: { id, label: section } };
-}
-
-const typographyPlacement = new Map<string, TypographyPlacement>();
-function placeTypography(names: readonly string[], domain: "where" | "how", page: string, section: string): void {
- for (const name of names) typographyPlacement.set(name, typographyPlace(domain, page, section));
-}
-
-placeTypography(["stack-order"], "where", "Layout", "Stacking");
-placeTypography([
- "inline-size", "block-size", "padding", "align", "block-align", "wrap", "overflow", "max-lines",
- "minimum-scale", "clip", "columns", "column-gap",
-], "where", "Layout", "Area");
-placeTypography(["point-anchor-inline", "point-anchor-block"], "where", "Layout", "Point");
-placeTypography([
- "path-side", "path-orientation", "path-start-margin", "path-end-margin", "path-align", "path-reverse", "path-overflow",
-], "where", "Layout", "Path");
-placeTypography([
- "size", "weight", "font-style", "line-height", "tracking", "word-spacing", "kerning", "synthesis", "language",
- "direction", "writing-mode", "baseline-shift", "vertical-align", "tab-size", "indent", "paragraph-before",
- "paragraph-after", "transform", "caps", "cjk-spacing", "punctuation-trim", "metric-edge",
-], "how", "Typography", "Typography");
-placeTypography(["fill"], "how", "Paint", "Fill");
-
-const typographyColorProperties = new Set(["fill"]);
-const typographyTextProperties = new Set(["language", "cjk-spacing", "punctuation-trim", "padding"]);
-
-const typographyInspector: readonly StudioInspectorFieldDeclaration[] = typographyProperties.map((property) => {
- const placement = typographyPlacement.get(property.name);
- if (placement === undefined) throw new Error(`Typography Studio has no explicit Inspector declaration for ${property.name}.`);
- const options = valuesFor(property);
- return {
- binding: `style.${property.name}`, label: title(property.name), ...placement,
- ...(property.summary === undefined ? {} : { summary: property.summary }),
- control: options !== undefined ? "select" : typographyColorProperties.has(property.name) ? "color"
- : typographyTextProperties.has(property.name) ? "text" : "number",
- ...(options === undefined ? {} : { options }),
- };
-});
-
-function textOf(item: TypographyTrackProgram["items"][number]): string {
- return item.document.paragraphs.map((paragraph) => paragraph.inlines
- .map((inline) => inline.kind === "text" ? inline.text : " ")
- .join(""))
- .join(" ")
- .replace(/\s+/gu, " ")
- .trim();
-}
-
-function projectTypography(context: StudioTrackCompanionContext): readonly StudioEntityDraft[] {
- const program = requiredSurfaceValue(context, "program") as TypographyTrackProgram;
- const items = program.items.map((item) => ({
- id: item.id,
- startFrame: item.span.startFrame,
- endFrameExclusive: item.span.endFrameExclusive,
- stackOrder: item.style.stackingOrder,
- sourceTypes: [typographyTrackTypes.itemSpec, typographyTrackTypes.plainItemSpec],
- }));
- return childEntities(context, items, "typography-item", "standard").map((entity, index) => {
- const item = program.items[index];
- if (item === undefined) return entity;
- const label = textOf(item);
- const temporal = temporalLineageFor(context, item.id, "window");
- const semanticSource = temporalSemanticSource(temporal);
- return {
- ...entity,
- display: { ...entity.display, layers: label.length === 0 ? [] : [textLayer(label)] },
- ...(semanticSource?.id === undefined
- ? {}
- : { markerId: semanticSource.id }),
- ...(temporal === undefined ? {} : { temporal }),
- };
- });
-}
-
-export const typographyTrackStudioTrackCompanions: readonly StudioTrackCompanion[] = [
- {
- id: "track", role: "track",
- output: { type: compositionTypes.visualTrack, surface: "track", modules: [typographyTrackModuleRef] },
- family: "text", tone: "violet", icon: "text",
- bindings: [
- { name: "placement" },
- { name: "content" },
- {
- name: "style",
- referenced: [fontInspector.binding],
- recipe: { through: ["recipe"], bindings: typographyProperties.map(({ name }) => ({ name })) },
- },
- { name: "motion" },
- ],
- inspector: [...fontInspector.fields, ...typographyInspector],
- requiredValues: ["program"], project: projectTypography,
- lane: { heightPx: 48 },
- },
-];
diff --git a/packages/typography-track/README.md b/packages/typography-track/README.md
deleted file mode 100644
index 30b2040f..00000000
--- a/packages/typography-track/README.md
+++ /dev/null
@@ -1,50 +0,0 @@
-# `@hypit/typography-track`
-
-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.
-
-Place independently authored titles, labels, verdicts and other text in the video. Their lifetime
-can follow a Script Selection or Moment even when their wording differs from the speech. For words
-displayed as they are spoken, use a [Caption family](../caption-fine/README.md).
-
-The Track takes the shared `timeline`. Items use explicit Point, Frame or Path
-placement, exact fonts and Styles. Timing can follow a Segment, Selection, Moment with duration, the
-whole program or explicit clock expressions. `.program` describes the text presentation; `.track`
-is the VisualTrack to include in Film. Each item has its own lifetime and stacking order.
-
-The text program supports rich documents, font stacks, Paint, wrapping, overflow and motion at item,
-word or grapheme level. Placement and time are separate from the Style Recipe. `typo:Mask` is a
-separate component for an authored Text Program and an owned still surface; read its vocabulary for
-the supported mask forms.
-
-Content has two explicit author forms:
-
-```svml
-<import as="copy" from="@hypit/text@1"/>
-<import as="typo" from="@hypit/typography-track@1"/>
-
-<copy:Value id="headline-copy">A useful idea, clearly shown.</copy:Value>
-
-<typo:Track id="titles" timeline={speech.timeline}>
- <typo:Area id="headline" content={headline-copy}
- placement={layout.headline} style={title-style} during="program"/>
-
- <typo:Area id="editorial" placement={layout.editorial}
- style={body-style} during="program">
- <typo:P>Rich <typo:Span style={accent}>authored</typo:Span> typography.</typo:P>
- </typo:Area>
-</typo:Track>
-```
-
-`content={...}` consumes an ordinary graph `Text` and is exclusive with body content. It becomes
-one plain document run; the Track still owns placement, timing, appearance and motion. Inline body
-content owns a bounded rich `VisualTextDocument`. Dynamic rich text is intentionally not smuggled
-through generic `Text`; it would require a separate explicit rich-document contract.
-
-`<typo:P>`, `<typo:Span>` and `<typo:Break>` are declared children of every item, so they are
-discoverable from the Surface vocabulary rather than from prose. A `style` on a `<typo:P>` or a
-`<typo:Span>` replaces the whole typography record, not only the paints: that paragraph or run is
-shaped with the referenced Style's own exact font at its own size, weight and slant, so one document
-can mix typefaces. The Style's area, point, path and stacking-order properties are ignored there;
-those stay with the item.
diff --git a/packages/typography-track/src/activation.ts b/packages/typography-track/src/activation.ts
deleted file mode 100644
index 688a1149..00000000
--- a/packages/typography-track/src/activation.ts
+++ /dev/null
@@ -1,36 +0,0 @@
-import { createMarkupSurfaceHostFacet } from "@hypit/markup";
-import {
- decodeTypographyMotionSurface,
- decodeTypographyMaskSurface,
- decodeTypographyStyleSurface,
- decodeTypographyTrackSurface,
- typographyTrackComponent,
- typographyTrackManifest,
- typographyTrackModuleRef,
- typographyTrackMarkupSurfaces,
-} from "./index.js";
-
-export const hypitPackage = {
- format: "hypit.node-package@1" as const,
- modules: [{ manifest: typographyTrackManifest }],
- components: [typographyTrackComponent],
- hostFacets: [
- createMarkupSurfaceHostFacet({
- module: typographyTrackModuleRef,
- declaration: typographyTrackMarkupSurfaces.find((item) => item.name === "style")!, handler: decodeTypographyStyleSurface,
- }),
- createMarkupSurfaceHostFacet({
- module: typographyTrackModuleRef,
- declaration: typographyTrackMarkupSurfaces.find((item) => item.name === "motion")!, handler: decodeTypographyMotionSurface,
- }),
- createMarkupSurfaceHostFacet({
- module: typographyTrackModuleRef,
- declaration: typographyTrackMarkupSurfaces.find((item) => item.name === "track")!, handler: decodeTypographyTrackSurface,
- }),
- createMarkupSurfaceHostFacet({
- module: typographyTrackModuleRef,
- declaration: typographyTrackMarkupSurfaces.find((item) => item.name === "mask")!, handler: decodeTypographyMaskSurface,
- }),
- ],
-};
-export default hypitPackage;
diff --git a/packages/typography-track/src/fragment.ts b/packages/typography-track/src/fragment.ts
deleted file mode 100644
index 073fc984..00000000
--- a/packages/typography-track/src/fragment.ts
+++ /dev/null
@@ -1,31 +0,0 @@
-import { timelineTypes } from "@hypit/timeline";
-
-import { compositionTypes } from "@hypit/composition";
-import type { VisualTrack } from "@hypit/composition";
-import { sealGraphFragment } from "@hypit/elaborator";
-
-import { typographyTrackProducers, typographyTrackTypes } from "./manifest.js";
-
-const input = (name: string) => ({ kind: "fragment-input" as const, name });
-const operation = (id: string) => ({ kind: "fragment-operation" as const, operation: id });
-
-/** Provider-free official lowering from TypographyTrackProgram to one peer VisualTrack. */
-export const typographyTrackFragment = sealGraphFragment({
- inputs: [
- { name: "timeline", type: timelineTypes.track },
- { name: "program", type: typographyTrackTypes.program },
- ],
- operations: [
- {
- id: "render",
- producer: typographyTrackProducers.render,
- inputs: { timeline: input("timeline"), program: input("program") },
- result: { kind: "output", name: "track" },
- },
- ],
- exports: [{
- name: "track",
- type: compositionTypes.visualTrack,
- root: operation("render"),
- }],
-});
diff --git a/packages/typography-track/src/index.ts b/packages/typography-track/src/index.ts
deleted file mode 100644
index 4832832e..00000000
--- a/packages/typography-track/src/index.ts
+++ /dev/null
@@ -1,11 +0,0 @@
-export { typographyTrackFragment } from "./fragment.js";
-export { typographyTrackComponent } from "./component.js";
-export { typographyTrackManifest, typographyTrackMarkupSurfaces, typographyTrackModuleRef, typographyTrackProducers, typographyTrackProgramSchema, typographyTrackTypes } from "./manifest.js";
-export { appendProjectedTextItem, assertPlainTextItemSpec, bindAreaTextPlacement, bindPathTextPlacement, bindPointTextPlacement, assertTextItemSpec, assertTextMaskSpec, assertTextMotion, assertTextPlacement, assertTextStyle, assertTypographyTrackHeader, assertTypographyTrackProgramIdentity, assertTypographyTrackSet, createTypographyTrackSet, finalizeTypographyTrack, renderTypographyTrack, renderTextMaskTrack, sealTypographyTrackProgram, sealTypographyTrackHeader, sealTextItemSpec, sealPlainTextItemSpec, materializePlainTextItem, sealTextMotion, sealTextMaskSpec, sealTextPlacement, sealTextStyle, stillTextMotion } from "./program.js";
-export {
- decodeTypographyMotionSurface,
- decodeTypographyStyleSurface,
- decodeTypographyTrackSurface,
- decodeTypographyMaskSurface,
-} from "./surface.js";
-export type * from "./types.js";
diff --git a/packages/video-cli/README.md b/packages/video-cli/README.md
index 155d4b9b..f7c1b061 100644
--- a/packages/video-cli/README.md
+++ b/packages/video-cli/README.md
@@ -218,7 +218,7 @@ contain either Workspace or package-installation overrides.
`check` is usable for an Author Source or a complete Run Source. `plan` and `build` require a Run
Source because an Author Graph without execution intent is not a Build. The live example executes
-the Script-owned deterministic CaptionDocument alongside real local/remote Endpoints; the CLI never
+the deterministic CaptionDocument produced by Script alongside real local/remote Endpoints; the CLI never
fabricates a Target, Candidate or missing fact.
`build` compiles one immutable Build Definition and submits it to the configured Local Runtime with a
diff --git a/packages/video-cli/src/creation.ts b/packages/video-cli/src/creation.ts
index e02ee99d..86932f7c 100644
--- a/packages/video-cli/src/creation.ts
+++ b/packages/video-cli/src/creation.ts
@@ -16,8 +16,7 @@ import {
import type { CanonicalValue, CapabilityRef, Need, StoredValue } from "@hypit/protocol";
import type { ResourceStore } from "@hypit/runtime";
import type { RuntimeHostCapabilityProvider, RuntimeHostProviderQuery, RuntimeInvocationObservation } from "@hypit/runtime-host-node";
-import { sealSpeechEvidenceAudio } from "@hypit/speech";
-import { speechEvidenceTypes } from "@hypit/speech-evidence";
+import { sealSpeechEvidenceAudio, speechEvidenceTypes } from "@hypit/speech-evidence";
import type { AlignedTranscriptEvidence } from "@hypit/speech-evidence";
import { sealText } from "@hypit/text";
import { whisperXCapabilities, whisperXRequestForEvidenceAudio } from "@hypit/whisperx";
@@ -291,7 +290,7 @@ async function transcribe(argv: readonly string[], io: CliIo, environment: Creat
const evidence = await speechEvidenceBytes(source);
const resources = new MemoryResourceStore();
const artifact = await resources.put(evidence.bytes, "audio/wav");
- const audio = sealSpeechEvidenceAudio({ artifact, sampleFrames: evidence.sampleFrames });
+ const audio = sealSpeechEvidenceAudio({ domainId: "cli-transcribe", artifact, sampleFrames: evidence.sampleFrames });
const need: Need = {
id: "need:hypit-transcribe",
capability: whisperXCapabilities.alignment,
diff --git a/packages/video-cli/src/studio-distribution.ts b/packages/video-cli/src/studio-distribution.ts
index e76ccb4b..0f016127 100644
--- a/packages/video-cli/src/studio-distribution.ts
+++ b/packages/video-cli/src/studio-distribution.ts
@@ -8,13 +8,11 @@ export const videoStudioCompanionPackages = [
"@hypit/audio-track-studio",
"@hypit/caption-fine-studio",
"@hypit/comment-sticker-studio",
- "@hypit/deck-track-studio",
+ "@hypit/depth-stack-studio",
"@hypit/film-studio",
- "@hypit/media-track-studio",
- "@hypit/performance-studio",
+ "@hypit/visual-track-studio",
"@hypit/ranking-studio",
"@hypit/screen-overlay-studio",
"@hypit/script-studio",
- "@hypit/sound-studio",
- "@hypit/typography-track-studio",
+ "@hypit/text-fine-studio",
] as const;
diff --git a/packages/video-cli/test/cli.test.ts b/packages/video-cli/test/cli.test.ts
index ffad3a1a..c18db93c 100644
--- a/packages/video-cli/test/cli.test.ts
+++ b/packages/video-cli/test/cli.test.ts
@@ -43,7 +43,7 @@ test("source package selection follows Run and Author imports", async () => {
test("provider-free example plans from installed Source packages", async () => {
// The installed package preview exercises Timeline, composition and mux planning without
// requiring a generation account or an authored project copy.
- const fixture = join(process.cwd(), "packages", "media-track", "preview");
+ const fixture = join(process.cwd(), "packages", "visual-track", "preview");
let output = "";
await runCli([
"plan",
diff --git a/packages/video-cli/test/creation.test.ts b/packages/video-cli/test/creation.test.ts
index ec75f0f7..6ea2c7de 100644
--- a/packages/video-cli/test/creation.test.ts
+++ b/packages/video-cli/test/creation.test.ts
@@ -48,6 +48,8 @@ function host(seen: Need[]): CreationHost {
if (need.capability.name === "whisperx-alignment") {
const request = need.constraints as unknown as WhisperXAlignmentRequest;
return { value: { kind: "inline" as const, value: canonicalize(sealAlignedTranscriptEvidence({
+ domainId: request.domainId,
+ sampleFrames: request.sampleFrames,
passages: interpretWhisperXTranscript({
segments: [{ start: 0, end: 1.5, words: [{ text: "hello", start: 0.1, end: 0.5 }, { text: "world", start: 0.9, end: 1.4 }] }],
}, request.sampleFrames),
@@ -185,7 +187,10 @@ test("Chinese transcription explicitly sends zh and retains individual character
invoke: async (need) => {
const request = need.constraints as unknown as WhisperXAlignmentRequest;
assert.equal(request.language, "zh");
- return { value: { kind: "inline", value: canonicalize({ passages: interpretWhisperXTranscript({
+ return { value: { kind: "inline", value: canonicalize({
+ domainId: request.domainId,
+ sampleFrames: request.sampleFrames,
+ passages: interpretWhisperXTranscript({
segments: [{ words: [{ word: "你", start: 0.1, end: 0.24 }, { word: "好!", start: 0.5, end: 1.1 }] }],
}, request.sampleFrames) }) } };
},
diff --git a/packages/video-cli/test/packages.ts b/packages/video-cli/test/packages.ts
index 6add8072..41346cad 100644
--- a/packages/video-cli/test/packages.ts
+++ b/packages/video-cli/test/packages.ts
@@ -9,10 +9,11 @@ import generation from "../../generation/src/activation.js";
import renderHyperframes from "../../render-hyperframes/src/activation.js";
import hyperframes from "../../hyperframes/src/activation.js";
import mediaPipeline from "../../media-pipeline/src/activation.js";
-import mediaTrack from "../../media-track/src/activation.js";
+import mediaTrack from "../../visual-track/src/activation.js";
import media from "../../media/src/activation.js";
import narrative from "../../narrative/src/activation.js";
-import programSpace from "../../program-space/src/activation.js";
+import narrativeCaption from "../../narrative-caption/src/activation.js";
+import narrativeTemporal from "../../narrative-temporal/src/activation.js";
import text from "../../text/src/activation.js";
import runMarkup from "../../run-markup/src/activation.js";
import script from "../../script/src/activation.js";
@@ -26,7 +27,7 @@ import spatial from "../../spatial/src/activation.js";
import temporal from "../../temporal/src/activation.js";
import visualIr from "../../visual-ir/src/activation.js";
import svs from "../../svs/src/activation.js";
-import typographyTrack from "../../typography-track/src/activation.js";
+import textFine from "../../text-fine/src/activation.js";
import whisperX from "../../whisperx/src/activation.js";
import type { NodePackageContribution } from "@hypit/package-loader-node";
@@ -39,8 +40,9 @@ const bind = (specifier: string, contribution: NodePackageContribution) => ({
export const videoTestPackages = [
bind("@hypit/artifact", artifact),
bind("@hypit/narrative", narrative),
+ bind("@hypit/narrative-caption", narrativeCaption),
+ bind("@hypit/narrative-temporal", narrativeTemporal),
bind("@hypit/media", media),
- bind("@hypit/program-space", programSpace),
bind("@hypit/speech", speech),
bind("@hypit/speech-evidence", speechEvidence),
bind("@hypit/timeline", timeline),
@@ -60,8 +62,8 @@ export const videoTestPackages = [
bind("@hypit/whisperx", whisperX),
bind("@hypit/spatial", spatial),
bind("@hypit/temporal", temporal),
- bind("@hypit/media-track", mediaTrack),
- bind("@hypit/typography-track", typographyTrack),
+ bind("@hypit/visual-track", mediaTrack),
+ bind("@hypit/text-fine", textFine),
bind("@hypit/film", film),
bind("@hypit/hyperframes", hyperframes),
bind("@hypit/media-pipeline", mediaPipeline),
diff --git a/packages/visual-track-studio/README.md b/packages/visual-track-studio/README.md
new file mode 100644
index 00000000..f63cb1de
--- /dev/null
+++ b/packages/visual-track-studio/README.md
@@ -0,0 +1,18 @@
+# `@hypit/visual-track-studio`
+
+Hypit Studio Companion for `@hypit/visual-track`.
+
+Each Clip has a title and image or video body. An explicit author `id` supplies
+its title; otherwise the Companion displays its `image`, `media` or `surface`
+reference. Display names do not replace the Clip's identity or writeback
+endpoint.
+
+Visual and Audio Track share selection and temporal editing behavior. Visual
+Track composes Clips by draw order; Audio Track mixes overlapping Clips.
+
+The Inspector preserves the author model's orthogonal axes: Frame geometry,
+direct `z`/fit, source-time and treatment Recipe fields are separate bindings.
+Source-time is currently a read-only structural binding: Studio does not collapse an
+arbitrary piecewise relation back into a closed playback-mode control.
+`motion` is a typed Motion reference rather than a Recipe of named effects;
+Pose editing can evolve without restoring an enter/sustain/exit catalogue.
diff --git a/packages/media-track-studio/package.json b/packages/visual-track-studio/package.json
similarity index 65%
rename from packages/media-track-studio/package.json
rename to packages/visual-track-studio/package.json
index 8c77eb12..c80a05ae 100644
--- a/packages/media-track-studio/package.json
+++ b/packages/visual-track-studio/package.json
@@ -1,5 +1,5 @@
{
- "name": "@hypit/media-track-studio",
+ "name": "@hypit/visual-track-studio",
"version": "0.0.0-dev",
"license": "SEE LICENSE IN LICENSE",
"private": true,
@@ -7,9 +7,10 @@
"exports": { ".": "./src/index.ts" },
"hypit": { "activation": "./src/activation.ts" },
"dependencies": {
- "@hypit/media-track": "workspace:*",
+ "@hypit/visual-track": "workspace:*",
"@hypit/composition": "workspace:*",
"@hypit/protocol": "workspace:*",
- "@hypit/studio-adapter": "workspace:*"
+ "@hypit/studio-adapter": "workspace:*",
+ "@hypit/temporal": "workspace:*"
}
}
diff --git a/packages/visual-track-studio/src/activation.ts b/packages/visual-track-studio/src/activation.ts
new file mode 100644
index 00000000..4b476549
--- /dev/null
+++ b/packages/visual-track-studio/src/activation.ts
@@ -0,0 +1,10 @@
+import { createStudioCompanionHostFacet } from "@hypit/studio-adapter";
+import { visualTrackStudioTrackCompanions, visualTrackStudioParameterCompanions } from "./index.js";
+
+export default {
+ format: "hypit.node-package@1" as const,
+ hostFacets: [createStudioCompanionHostFacet({
+ tracks: visualTrackStudioTrackCompanions,
+ parameters: visualTrackStudioParameterCompanions,
+ })],
+};
diff --git a/packages/visual-track-studio/src/index.ts b/packages/visual-track-studio/src/index.ts
new file mode 100644
index 00000000..1e39da34
--- /dev/null
+++ b/packages/visual-track-studio/src/index.ts
@@ -0,0 +1,209 @@
+import { visualTreatmentDefaults, visualTrackMarkupSurfaces, visualTrackModuleRef, visualTrackTypes } from "@hypit/visual-track";
+import type { MediaLayerProgram, VisualTrackProgram } from "@hypit/visual-track";
+import { compositionTypes } from "@hypit/composition";
+import type {
+ StudioTrackCompanion,
+ StudioTrackCompanionContext,
+ StudioEntityDraft,
+ StudioInspectorFieldDeclaration,
+ StudioMaterialPreview,
+ StudioSourceBindingDeclaration,
+} from "@hypit/studio-adapter";
+import { artifactPreview, authoredItemTitle, childEntities, previewLayer, requiredSurfaceValue, temporalLineageFor, temporalSemanticSource } from "@hypit/studio-adapter";
+
+const frameParameters: readonly StudioSourceBindingDeclaration[] = [
+ { name: "within" },
+ { name: "left", writable: true },
+ { name: "top", writable: true },
+ { name: "right", writable: true },
+ { name: "bottom", writable: true },
+ { name: "x", writable: true },
+ { name: "y", writable: true },
+ { name: "width", writable: true },
+ { name: "height", writable: true },
+];
+
+const extentParameters: readonly StudioSourceBindingDeclaration[] = [
+ { name: "width", writable: true },
+ { name: "height", writable: true },
+];
+
+const visualTrackSurface = visualTrackMarkupSurfaces.find((surface) => surface.name === "track");
+const visualClipAttributes = visualTrackSurface?.vocabulary.children?.find((child) => child.tag === "Clip")?.attributes ?? [];
+
+function title(name: string): string {
+ return name.split("-").map((part) => `${part.slice(0, 1).toUpperCase()}${part.slice(1)}`).join(" ");
+}
+
+function valuesFor(property: { readonly name: string }): readonly string[] | undefined {
+ return "values" in property ? (property as { readonly values: readonly string[] }).values : undefined;
+}
+
+type MediaPlacement = Pick<StudioInspectorFieldDeclaration, "domain" | "page" | "section">;
+
+function mediaPlace(domain: "where" | "how" | "when", page: string, section: string): MediaPlacement {
+ const id = section.toLowerCase().replaceAll(" ", "-");
+ return { domain, page: { id: page.toLowerCase(), label: page }, section: { id, label: section } };
+}
+
+const mediaPlacement = new Map<string, MediaPlacement>();
+function placeMedia(names: readonly string[], domain: "where" | "how" | "when", page: string, section: string): void {
+ for (const name of names) mediaPlacement.set(name, mediaPlace(domain, page, section));
+}
+
+placeMedia(["clip", "radius", "padding"], "where", "Frame", "Geometry");
+placeMedia(["opacity", "blur", "brightness", "contrast", "saturation"], "how", "Image", "Image");
+placeMedia(["border-width", "border-style", "border-color", "shadows", "frame-paint"], "how", "Frame", "Paint");
+
+const mediaColorProperties = new Set(["border-color"]);
+const mediaTextProperties = new Set(["padding", "shadows", "frame-paint"]);
+const mediaPercentProperties = new Set(["opacity", "brightness", "contrast", "saturation"]);
+const mediaPixelProperties = new Set(["radius", "blur", "border-width"]);
+
+function treatmentRecipe(): {
+ readonly bindings: readonly import("@hypit/studio-adapter").StudioRecipeBindingDeclaration[];
+ readonly inspector: readonly StudioInspectorFieldDeclaration[];
+} {
+ const attribute = visualClipAttributes.find((candidate) => candidate.name === "treatment");
+ const properties = attribute !== undefined && "recipe" in attribute ? attribute.recipe : [];
+ return {
+ bindings: properties.map(({ name: property }) => ({ name: property,
+ ...(Object.hasOwn(visualTreatmentDefaults, property) ? { fallback: visualTreatmentDefaults[property as keyof typeof visualTreatmentDefaults] } : {}),
+ })),
+ inspector: properties.map((property) => {
+ const placement = mediaPlacement.get(property.name);
+ if (placement === undefined) throw new Error(`Media Studio has no explicit Inspector declaration for ${property.name}.`);
+ const options = valuesFor(property);
+ const control = options !== undefined ? "select" as const
+ : mediaColorProperties.has(property.name) ? "color" as const
+ : mediaTextProperties.has(property.name) ? "text" as const : "number" as const;
+ return {
+ binding: `treatment.${property.name}`,
+ label: title(property.name),
+ ...placement,
+ ...(property.summary === undefined ? {} : { summary: property.summary }),
+ control,
+ ...(mediaPercentProperties.has(property.name) ? { unit: "%", number: { scale: 100, step: 1 } } : {}),
+ ...(mediaPixelProperties.has(property.name) ? { unit: "px", number: { step: 1 } } : {}),
+ ...(options === undefined ? {} : { options }),
+ };
+ }),
+ };
+}
+
+export const visualClipTreatmentStudioFields = treatmentRecipe();
+
+function clipOptions(name: string): readonly string[] {
+ const attribute = visualClipAttributes.find((candidate) => candidate.name === name);
+ const options = attribute === undefined ? undefined : valuesFor(attribute);
+ if (options === undefined) throw new Error(`Visual Studio requires declared values for Clip.${name}.`);
+ return options;
+}
+
+const fitOptions = clipOptions("fit");
+const fitConstraintOptions = clipOptions("fit-constraint");
+const directClipBindings: readonly StudioSourceBindingDeclaration[] = [
+ { name: "z", writable: true },
+ { name: "fit", writable: true, fallback: "contain" },
+ ...["frame-x", "frame-y", "content-x", "content-y"].map((name) => ({ name, writable: true, fallback: 0.5 })),
+ ...["fit-offset-x", "fit-offset-y"].map((name) => ({ name, writable: true, fallback: 0 })),
+ { name: "fit-constraint", writable: true, fallback: "bounded" },
+ { name: "source-time" },
+];
+
+const directClipInspector: readonly StudioInspectorFieldDeclaration[] = [
+ { binding: "z", label: "Stack Order", ...mediaPlace("where", "Frame", "Stacking"), control: "number", number: { step: 1 } },
+ { binding: "fit", label: "Fit", ...mediaPlace("where", "Fit", "Fit"), control: "select", options: fitOptions },
+ ...["frame-x", "frame-y", "content-x", "content-y"].map((binding) => ({
+ binding, label: title(binding), ...mediaPlace("where", "Fit", "Alignment"), control: "number" as const,
+ unit: "%", number: { scale: 100, step: 1 },
+ })),
+ ...["fit-offset-x", "fit-offset-y"].map((binding) => ({
+ binding, label: title(binding), ...mediaPlace("where", "Fit", "Offset"), control: "number" as const,
+ unit: "px", number: { step: 1 },
+ })),
+ { binding: "fit-constraint", label: "Fit Constraint", ...mediaPlace("where", "Fit", "Fit"), control: "select", options: fitConstraintOptions },
+];
+
+function materialPreview(
+ layers: readonly MediaLayerProgram[],
+): StudioMaterialPreview | undefined {
+ const layer = layers.find((candidate) => candidate.kind === "sample");
+ if (layer?.kind !== "sample") return undefined;
+ if (layer.source.kind === "surface") return undefined;
+ return artifactPreview(layer.source.kind === "still" ? "image" : "video", layer.source.artifact.resource);
+}
+
+function projectVisualClips(context: StudioTrackCompanionContext): readonly StudioEntityDraft[] {
+ const program = requiredSurfaceValue(context, "program") as VisualTrackProgram;
+ const clips = program.clips.map((clip) => ({
+ id: clip.id,
+ subjectId: clip.subjectId,
+ startFrame: clip.span.startFrame,
+ endFrameExclusive: clip.span.endFrameExclusive,
+ stackOrder: clip.z,
+ preview: materialPreview(clip.layers),
+ temporalInput: "window",
+ sourceTypes: [visualTrackTypes.clipSpec],
+ }));
+ return childEntities(context, clips, "visual-clip", "standard")
+ .map((entity, index) => {
+ const clip = clips[index];
+ if (clip === undefined) return entity;
+ const temporal = temporalLineageFor(context, clip.id, clip.temporalInput);
+ const semanticSource = temporalSemanticSource(temporal);
+ return {
+ ...entity,
+ display: {
+ ...entity.display,
+ title: authoredItemTitle(context, entity.authoredId, clip.sourceTypes, ["image", "media", "surface"]),
+ ...(clip.preview === undefined ? {} : {
+ layers: [previewLayer(clip.preview, clip.preview.kind === "video" ? "storyboard" : "repeat-x")],
+ }),
+ },
+ ...(semanticSource?.id === undefined
+ ? {}
+ : { markerId: semanticSource.id }),
+ ...(temporal === undefined ? {} : { temporal }),
+ };
+ });
+}
+
+const frameSizeParameters = new Set(["width", "height"]);
+
+export const visualTrackStudioTrackCompanions: readonly StudioTrackCompanion[] = [
+ {
+ id: "visual", role: "track",
+ output: { type: compositionTypes.visualTrack, surface: "track", modules: [visualTrackModuleRef] },
+ family: "visual", tone: "blue", icon: "video",
+ bindings: [
+ { name: "extent", referenced: extentParameters },
+ { name: "clip" },
+ { name: "image" },
+ { name: "media" },
+ { name: "surface" },
+ { name: "frame", referenced: frameParameters },
+ ...directClipBindings,
+ { name: "treatment", recipe: { bindings: visualClipTreatmentStudioFields.bindings } },
+ { name: "motion" },
+ ],
+ inspector: [
+ ...frameParameters.filter(({ writable }) => writable === true).map(({ name }) => ({
+ binding: `frame.${name}`, label: title(name), domain: "where" as const,
+ page: { id: frameSizeParameters.has(name) ? "size" : "placement", label: frameSizeParameters.has(name) ? "Size" : "Placement" },
+ section: { id: "frame", label: "Frame" }, control: "number" as const, number: { suffixes: ["%", "px"], step: 1 },
+ })),
+ ...extentParameters.map(({ name }) => ({
+ binding: `extent.${name}`, label: title(name), domain: "where" as const,
+ page: { id: "size", label: "Size" }, section: { id: "extent", label: "Source Extent" },
+ control: "number" as const, unit: "px",
+ })),
+ ...directClipInspector,
+ ...visualClipTreatmentStudioFields.inspector,
+ ],
+ requiredValues: ["program"], project: projectVisualClips,
+ lane: { heightPx: 76 },
+ },
+];
+
+export const visualTrackStudioParameterCompanions = [];
diff --git a/packages/visual-track-studio/test/companion.test.ts b/packages/visual-track-studio/test/companion.test.ts
new file mode 100644
index 00000000..997b4311
--- /dev/null
+++ b/packages/visual-track-studio/test/companion.test.ts
@@ -0,0 +1,27 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import {
+ visualClipTreatmentStudioFields,
+ visualTrackStudioTrackCompanions,
+} from "../src/index.js";
+
+test("Visual Studio keeps occurrence facts, treatment and typed Motion separate", () => {
+ const companion = visualTrackStudioTrackCompanions[0]!;
+ assert.equal(companion.family, "visual");
+ const bindings = new Map((companion.bindings ?? []).map((binding) => [binding.name, binding]));
+
+ for (const name of ["z", "fit", "source-time", "treatment", "motion"]) {
+ assert.ok(bindings.has(name), `missing ${name}`);
+ }
+ assert.equal(bindings.has("appearance"), false);
+ assert.ok("recipe" in bindings.get("treatment")!);
+ assert.equal("recipe" in bindings.get("motion")!, false);
+
+ const treatmentNames = visualClipTreatmentStudioFields.bindings.map(({ name }) => name);
+ assert.deepEqual(treatmentNames, [
+ "opacity", "blur", "brightness", "contrast", "saturation",
+ "clip", "radius", "padding", "border-width", "border-style", "border-color", "shadows", "frame-paint",
+ ]);
+ assert.equal((companion.inspector ?? []).some(({ binding }) => /(?:enter|exit|sustain)/u.test(binding)), false);
+});
diff --git a/packages/visual-track/README.md b/packages/visual-track/README.md
new file mode 100644
index 00000000..40f80d08
--- /dev/null
+++ b/packages/visual-track/README.md
@@ -0,0 +1,122 @@
+# `@hypit/visual-track`
+
+Visual Track is the plain picture-placement package. Its author model is deliberately small:
+
+```text
+Visual Clip = one picture source + absolute Window + Frame
+ + z + spatial map + source-time + optional treatment + optional typed Motion
+Visual Track = ordered set of Visual Clips
+```
+
+The Track consumes one completed Timeline. It publishes `.program` for
+declared tooling and `.visual` for Film. It does not discover media or anchors from Timeline, infer
+semantic roles, select audio, or own multi-Clip transitions.
+
+```svml
+<visual:Motion id="gentle-push">
+ <visual:Pose at="start" scale="1.08" easing="ease-out"/>
+ <visual:Pose at="end" scale="1"/>
+</visual:Motion>
+
+<visual:Track id="picture" timeline={program.timeline}>
+ <visual:Clip id="speaker" media={speaker-media.media}
+ during={program.speaker} frame={full-frame} z="10" fit="cover"/>
+ <visual:Clip id="diagram" image={diagram} extent={diagram-extent}
+ during={story-time.explanation} frame={inset-frame} z="20" fit="contain"
+ treatment={recipes.visual.diagram} motion={gentle-push}/>
+</visual:Track>
+```
+
+A public Clip accepts exactly one direct source form—`image` plus `extent`, normalized `media`, or a
+typed `surface`. Moving media is normalized before authoring; its
+factual frame count and frame rate remain source truth. The destination Window states when this
+occurrence exists in program time.
+
+The ordinary source roles are intentionally equal. A-roll, B-roll, generated footage and imported
+graphics are all Clips. A source may have contributed duration and anchors while Timeline was built;
+that prior contribution does not give its later visual occurrence a special Type or placement route.
+
+## Frame and source mapping
+
+`frame` is the outer destination rectangle. Independent Clip attributes control placement and
+source-time; an optional treatment Recipe contains only reusable pixel and Frame treatment:
+
+| Properties | Meaning |
+| --- | --- |
+| `z` | Absolute picture stacking; required on the occurrence. |
+| `fit`, alignment, offsets and constraint | Convenient occurrence attributes that derive one source-to-picture `SpatialMap2D`. |
+| `mapping` | An explicit `SpatialMap2D` used instead of all fit attributes. |
+| `clip`, `radius`, `padding` | Outer geometry and the fitting inset. |
+| border, shadows and `frame-paint` | Decoration owned by this Clip. |
+| opacity, blur, brightness, contrast, saturation | Treatment of the sampled picture. |
+| `Map` / `source-time` | Optional Clip-local relation from target frames to timed-source frames. |
+
+Use distinct `z` values when relative paint order matters. Equal-`z` Clips are valid: the Track
+retains declaration order locally, and terminal rendering uses stable Track and Present identities
+as the remaining fallback. This guarantees deterministic execution without making Visual Track
+pretend it can prove every authored overlap aesthetically intentional.
+
+An authored spatial Path may replace the treatment clip with `clip={path}`. Path coordinates remain
+in program-picture pixels. A typed `Motion` transforms the whole framed Clip with affine/opacity
+`Pose` keyframes; inline `Pose` children express the same value. `Sampling` children animate the
+fitted source inside the Frame. Neither form names a closed aesthetic effect.
+
+The resolved Program never retains fit as a competing spatial authority. When the Clip Frame is
+known, ordinary fit resolves once against the Frame's deterministic border/padding inset; an
+explicit mapping passes through unchanged. Every sample in `.program` then carries the final
+`SpatialMap2D`, and rendering applies that complete matrix to the source-local extent. A rectangular
+content bound may be derived for diagnostics, but is not stored or rendered as a substitute for the
+map.
+
+For the open path, publish or receive a map and share the same value with every consumer that needs
+the identical projection:
+
+```svml
+<space:Map id="turned" xx="0" xy="-0.5" yx="0.5" yy="0" tx="920" ty="180"/>
+<visual:Clip image={diagram} extent={diagram-extent} mapping={turned}
+ during={story-time.explanation} frame={inset-frame} z="20"/>
+```
+
+The explicit map is already in program-picture coordinates. `frame` still independently owns the
+Clip's clipping and treatment boundary. This separation permits rotation, skew, reflection,
+off-Frame placement and exact reuse by source-local evidence without adding a layout mode.
+
+## Source time
+
+Omitting a Map means bounded partial identity: Clip-local target frame zero maps to source frame zero
+at native rate, and the picture becomes absent when either domain ends. There is no implicit hold,
+loop or stretch.
+
+One `Map` states an affine piece. `target-from`/`target-until` bound its target interval;
+`target-at`, `source-at` and the exact rational `rate` relate the two clocks;
+`source-from`/`source-until` bound the source domain. `wrap-from`/`wrap-until` make that source interval
+periodic. A Map without rate, anchors or wrap fits the selected source interval across its target
+interval. Multiple non-overlapping Maps form one partial function; uncovered target frames are
+transparent.
+
+```svml
+<visual:SourceTime id="native-loop">
+ <visual:Map rate="1" wrap-from="start" wrap-until="end"/>
+</visual:SourceTime>
+
+<visual:Clip media={shot.media} during={story.outro} frame={full} z="10">
+ <visual:Map target-at="end" source-at="end" rate="1"/>
+</visual:Clip>
+```
+
+Visual rates may be zero for a held frame or negative for reverse traversal. A still image has no
+source clock and refuses Map; it simply remains visually active throughout the Clip Window while
+Clip-local Motion may still animate it.
+
+Visual Track contains no generic `Presentation`, `Use`, `Sequence` or `Handoff`. A continuing
+presenter, crossfade, slideshow or coordinated reveal is shared behavior and therefore belongs to an
+ordinary project/author component. Such a component may use the public visual primitives and still
+publish the same terminal `VisualTrack`; Core and Film learn no new role.
+
+This is the package's incremental boundary: the plain Clip supplies the stable operations almost
+every picture occurrence needs, while a new visual role remains straightforward to author as a
+component. The Track does not force authors to start from raw Composition IR, and it does not turn
+today's effect names into tomorrow's ceiling.
+
+Audio from synchronized media is never selected implicitly. Author the corresponding occurrence
+independently through [`@hypit/audio-track`](../audio-track/README.md).
diff --git a/packages/performance/package.json b/packages/visual-track/package.json
similarity index 82%
rename from packages/performance/package.json
rename to packages/visual-track/package.json
index b2ef11de..58c0ebff 100644
--- a/packages/performance/package.json
+++ b/packages/visual-track/package.json
@@ -1,5 +1,5 @@
{
- "name": "@hypit/performance",
+ "name": "@hypit/visual-track",
"version": "0.0.0-dev",
"license": "SEE LICENSE IN LICENSE",
"private": true,
@@ -16,8 +16,6 @@
"@hypit/composition": "workspace:*",
"@hypit/elaborator": "workspace:*",
"@hypit/media": "workspace:*",
- "@hypit/narrative": "workspace:*",
- "@hypit/program-space": "workspace:*",
"@hypit/protocol": "workspace:*",
"@hypit/timeline": "workspace:*",
"@hypit/spatial": "workspace:*",
@@ -25,7 +23,6 @@
"@hypit/markup": "workspace:*",
"@hypit/temporal": "workspace:*",
"@hypit/temporal-markup": "workspace:*",
- "@hypit/media-track": "workspace:*",
"@hypit/visual-ir": "workspace:*"
}
}
diff --git a/packages/media-track/preview/Track.png b/packages/visual-track/preview/Track.png
similarity index 100%
rename from packages/media-track/preview/Track.png
rename to packages/visual-track/preview/Track.png
diff --git a/packages/media-track/preview/build.svrun b/packages/visual-track/preview/build.svrun
similarity index 100%
rename from packages/media-track/preview/build.svrun
rename to packages/visual-track/preview/build.svrun
diff --git a/packages/media-track/preview/flush.png b/packages/visual-track/preview/flush.png
similarity index 100%
rename from packages/media-track/preview/flush.png
rename to packages/visual-track/preview/flush.png
diff --git a/packages/media-track/preview/preview.svml b/packages/visual-track/preview/preview.svml
similarity index 51%
rename from packages/media-track/preview/preview.svml
rename to packages/visual-track/preview/preview.svml
index 8c70de52..eb38b76d 100644
--- a/packages/media-track/preview/preview.svml
+++ b/packages/visual-track/preview/preview.svml
@@ -3,25 +3,21 @@
The samples are the displayed content. Their frame treatments demonstrate fit,
padding, clipping and motion; build.svrun renders the same composition. -->
<svml>
- <import from="@hypit/script@1"/>
<import as="media" from="@hypit/media@1"/>
<import as="pipeline" from="@hypit/media-pipeline@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="visual" from="@hypit/visual-track@1"/>
<import as="space" from="@hypit/spatial@1"/>
- <import as="program" from="@hypit/program-space@1"/>
<import as="film" from="@hypit/film@1"/>
<import as="render" from="@hypit/render-hyperframes@1"/>
<import as="recipes" source="./recipes.svs"/>
- <script id="story"><empty></empty></script>
<space:Canvas id="vertical" width="720" height="1280"/>
- <program:Clock id="clock" frame-rate="30"/>
- <space:Frame id="full" within={vertical} left="0%" top="0%" right="100%" bottom="100%"/>
- <space:Frame id="card-a" within={vertical}
+ <time:Clock id="clock" frame-rate="30"/>
+ <space:Frame id="full" within={vertical.bounds} left="0%" top="0%" right="100%" bottom="100%"/>
+ <space:Frame id="card-a" within={vertical.bounds}
left="8%" top="16%" right="92%" bottom="46%"/>
- <space:Frame id="card-b" within={vertical}
+ <space:Frame id="card-b" within={vertical.bounds}
left="12%" top="52%" right="88%" bottom="78%"/>
<space:Extent id="picture-size" width="640" height="360"/>
<media:Image id="picture-a" src="./rounded.png"/>
@@ -30,17 +26,24 @@
<pipeline:StillVideo id="duration" source={picture-a} duration="5" clock={clock}/>
<pipeline:Normalize id="duration-media" source={duration.video} clock={clock}
video="primary-moving" audio="none" span-authority="video"/>
- <whisperx:SemanticTake id="showcase-time" narrative={story}
- segment={story.segment.empty} media={duration-media.media}/>
- <time:Timeline id="speech" clock={clock}><time:Take source={showcase-time.take}/></time:Timeline>
+ <time:Timeline id="speech" clock={clock} end="showcase.end">
+ <time:Window id="showcase" from="start" for={duration-media.extent}/>
+ </time:Timeline>
- <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} timeline={speech.timeline} appearance={recipes.film.vertical}>
+ <visual:Motion id="card-motion">
+ <visual:Pose at="start" y="80" opacity="0" easing="ease-out"/>
+ <visual:Pose at="5f" y="0" opacity="1"/>
+ <visual:Pose at="end-5f" y="0" opacity="1" easing="ease-in"/>
+ <visual:Pose at="end" y="0" opacity="0"/>
+ </visual:Motion>
+
+ <visual:Track id="showcase" timeline={speech.timeline}>
+ <visual:Clip id="rounded-card" image={picture-a} extent={picture-size} during="timeline"
+ frame={card-a} z="40" fit="cover" treatment={recipes.media.card} motion={card-motion}/>
+ <visual:Clip id="flush-card" image={picture-b} extent={picture-size} during="timeline"
+ frame={card-b} z="41" fit="cover" treatment={recipes.media.wide} motion={card-motion}/>
+ </visual:Track>
+ <film:Film id="main" canvas={vertical.canvas} timeline={speech.timeline} appearance={recipes.film.vertical}>
<film:Track source={showcase.visual}/>
</film:Film>
<render:Video id="final" composition={main.composition} timeline={speech.timeline}/>
diff --git a/packages/media-track/preview/recipes.svs b/packages/visual-track/preview/recipes.svs
similarity index 63%
rename from packages/media-track/preview/recipes.svs
rename to packages/visual-track/preview/recipes.svs
index 4a4e90eb..44d11283 100644
--- a/packages/media-track/preview/recipes.svs
+++ b/packages/visual-track/preview/recipes.svs
@@ -1,23 +1,16 @@
<?svml using="@hypit/svs@1"?>
<sheet version="1">
- media.performance { stack-order: 0; fit: cover; }
film.vertical { background: #09090B; }
/* Rounded and padded, so the painted content box is visibly inset from the
Placement Frame Studio draws as a guide. */
media.card {
- stack-order: 40; fit: cover;
frame-paint: #16161d; clip: rounded; radius: 24; padding: 12 12;
}
/* Square and flush, for contrast with media.card. */
media.wide {
- stack-order: 41; fit: cover;
frame-paint: #1d1620; clip: frame;
border-width: 2; border-color: #ee7b6255;
}
- motion.card {
- enter: slide; enter-frames: 5; enter-direction: up; enter-easing: ease-out;
- exit: fade; exit-frames: 5; exit-easing: ease-in;
- }
</sheet>
diff --git a/packages/media-track/preview/rounded.png b/packages/visual-track/preview/rounded.png
similarity index 100%
rename from packages/media-track/preview/rounded.png
rename to packages/visual-track/preview/rounded.png
diff --git a/packages/visual-track/src/activation.ts b/packages/visual-track/src/activation.ts
new file mode 100644
index 00000000..3183d879
--- /dev/null
+++ b/packages/visual-track/src/activation.ts
@@ -0,0 +1,34 @@
+import { createMarkupSurfaceHostFacet } from "@hypit/markup";
+import {
+ decodeVisualTrackSurface,
+ decodeVisualMotionSurface,
+ decodeVisualSourceTimeSurface,
+ visualTrackComponent,
+ visualTrackManifest,
+ visualTrackModuleRef,
+ visualTrackMarkupSurfaces,
+} from "./index.js";
+
+export const hypitPackage = {
+ format: "hypit.node-package@1" as const,
+ modules: [{ manifest: visualTrackManifest }],
+ components: [visualTrackComponent],
+ hostFacets: [
+ createMarkupSurfaceHostFacet({
+ module: visualTrackModuleRef,
+ declaration: visualTrackMarkupSurfaces.find((item) => item.name === "track")!,
+ handler: decodeVisualTrackSurface,
+ }),
+ createMarkupSurfaceHostFacet({
+ module: visualTrackModuleRef,
+ declaration: visualTrackMarkupSurfaces.find((item) => item.name === "motion")!,
+ handler: decodeVisualMotionSurface,
+ }),
+ createMarkupSurfaceHostFacet({
+ module: visualTrackModuleRef,
+ declaration: visualTrackMarkupSurfaces.find((item) => item.name === "source-time")!,
+ handler: decodeVisualSourceTimeSurface,
+ }),
+ ],
+};
+export default hypitPackage;
diff --git a/packages/visual-track/src/author.ts b/packages/visual-track/src/author.ts
new file mode 100644
index 00000000..9af03019
--- /dev/null
+++ b/packages/visual-track/src/author.ts
@@ -0,0 +1,204 @@
+import type { SvsRecipe } from "@hypit/svs";
+import { decodeContentFitProperties } from "@hypit/spatial";
+import type { ContentFit } from "@hypit/spatial";
+
+import {
+ sealMediaPaintLayerSpec,
+ sealMediaSampleLayerSpec,
+} from "./layers.js";
+import { sealVisualClipSpec } from "./program.js";
+import type {
+ VisualFrameTreatment,
+ VisualClipSpec,
+ MediaPaint,
+ MediaPaintLayerSpec,
+ MediaSampleLayerSpec,
+ MediaSampleAppearance,
+ VisualSourceTimeSpec,
+} from "./types.js";
+
+function fail(recipe: SvsRecipe, message: string): never {
+ throw new Error(`Media Recipe ${recipe.path} ${message}`);
+}
+
+function optionalNumber(recipe: SvsRecipe, name: string): number | undefined {
+ const value = recipe.properties[name];
+ if (value === undefined) return undefined;
+ if (typeof value !== "number" || !Number.isFinite(value)) fail(recipe, `${name} must be a finite number.`);
+ return value;
+}
+
+function number(recipe: SvsRecipe, name: string, fallback?: number): number {
+ const value = optionalNumber(recipe, name);
+ if (value === undefined && fallback !== undefined) return fallback;
+ if (value === undefined) fail(recipe, `requires ${name}.`);
+ return value;
+}
+
+function optionalString(recipe: SvsRecipe, name: string): string | undefined {
+ const value = recipe.properties[name];
+ if (value === undefined) return undefined;
+ if (typeof value !== "string" || value.trim().length === 0) fail(recipe, `${name} must be text.`);
+ return value.trim();
+}
+
+function string(recipe: SvsRecipe, name: string, fallback?: string): string {
+ const value = optionalString(recipe, name);
+ if (value === undefined && fallback !== undefined) return fallback;
+ if (value === undefined) fail(recipe, `requires ${name}.`);
+ return value;
+}
+
+function oneOf<T extends string>(recipe: SvsRecipe, name: string, values: readonly T[], fallback?: T): T {
+ const value = optionalString(recipe, name);
+ if (value === undefined && fallback !== undefined) return fallback;
+ if (value === undefined || !values.includes(value as T)) fail(recipe, `${name} must be ${values.join(" | ")}.`);
+ return value as T;
+}
+
+function assertKeys(recipe: SvsRecipe, allowed: readonly string[]): void {
+ const unknown = Object.keys(recipe.properties).filter((name) => !allowed.includes(name));
+ if (unknown.length > 0) fail(recipe, `does not accept ${unknown.join(", ")}.`);
+}
+
+function scalarList(recipe: SvsRecipe, name: string, allowed: readonly number[]): number[] {
+ const source = optionalString(recipe, name);
+ if (source === undefined) return [];
+ const values = source.split(/\s+/u).map(Number);
+ if (!allowed.includes(values.length) || values.some((value) => !Number.isFinite(value))) {
+ fail(recipe, `${name} requires ${allowed.join(" or ")} finite numbers.`);
+ }
+ return values;
+}
+
+function padding(recipe: SvsRecipe): VisualFrameTreatment["padding"] {
+ const values = scalarList(recipe, "padding", [1, 2, 4]);
+ if (values.length === 0) return { topPx: 0, rightPx: 0, bottomPx: 0, leftPx: 0 };
+ if (values.length === 1) return { topPx: values[0]!, rightPx: values[0]!, bottomPx: values[0]!, leftPx: values[0]! };
+ if (values.length === 2) return { topPx: values[0]!, rightPx: values[1]!, bottomPx: values[0]!, leftPx: values[1]! };
+ return { topPx: values[0]!, rightPx: values[1]!, bottomPx: values[2]!, leftPx: values[3]! };
+}
+
+function gradientStops(recipe: SvsRecipe, source: string): readonly { readonly offset: number; readonly color: string }[] {
+ const stops = source.split(",").map((entry) => {
+ const match = /^(.+?)@((?:0(?:\.\d+)?)|(?:1(?:\.0+)?))$/u.exec(entry.trim());
+ if (match === null) fail(recipe, "gradient stops must be color@offset inside [0,1].");
+ return { color: match[1]!.trim(), offset: Number(match[2]) };
+ });
+ if (stops.length < 2) fail(recipe, "gradient requires at least two stops.");
+ return stops;
+}
+
+function paint(recipe: SvsRecipe, property = "paint"): MediaPaint {
+ const source = string(recipe, property);
+ const linear = /^linear\(([-+]?\d+(?:\.\d+)?);(.+)\)$/u.exec(source);
+ if (linear !== null) {
+ return { kind: "linear-gradient", angleDeg: Number(linear[1]), stops: gradientStops(recipe, linear[2]!) };
+ }
+ const radial = /^radial\(((?:0(?:\.\d+)?)|(?:1(?:\.0+)?)),((?:0(?:\.\d+)?)|(?:1(?:\.0+)?));(.+)\)$/u.exec(source);
+ if (radial !== null) {
+ return { kind: "radial-gradient", center: { x: Number(radial[1]), y: Number(radial[2]) }, stops: gradientStops(recipe, radial[3]!) };
+ }
+ return { kind: "solid", color: source };
+}
+
+function shadows(recipe: SvsRecipe): VisualFrameTreatment["shadows"] {
+ const source = optionalString(recipe, "shadows");
+ if (source === undefined || source === "none") return [];
+ return source.split(";").map((entry) => {
+ const match = /^([-+]?\d+(?:\.\d+)?)\s+([-+]?\d+(?:\.\d+)?)\s+(\d+(?:\.\d+)?)\s+([-+]?\d+(?:\.\d+)?)\s+(.+)$/u.exec(entry.trim());
+ if (match === null) fail(recipe, "shadows entries require x y blur spread color.");
+ return {
+ offsetX: Number(match[1]), offsetY: Number(match[2]), blurPx: Number(match[3]),
+ spreadPx: Number(match[4]), color: match[5]!.trim(),
+ };
+ });
+}
+
+const FIT_KEYS = ["fit", "frame-x", "frame-y", "content-x", "content-y", "fit-offset-x", "fit-offset-y", "fit-constraint"] as const;
+const SAMPLE_KEYS = ["opacity", "blur", "brightness", "contrast", "saturation"] as const;
+const FRAME_KEYS = ["clip", "radius", "padding", "border-width", "border-style", "border-color", "shadows", "frame-paint"] as const;
+
+export function decodeMediaFit(recipe: SvsRecipe): ContentFit {
+ return decodeContentFitProperties(recipe.properties, `Media Recipe ${recipe.path}`);
+}
+
+export function decodeMediaSampleSpec(
+ recipe: SvsRecipe,
+ id: string,
+ sourceKind: "still" | "timed" | "surface",
+ samplingMotion?: MediaSampleLayerSpec["samplingMotion"],
+ combinedClipAppearance = false,
+ sourceTime?: VisualSourceTimeSpec,
+): MediaSampleLayerSpec {
+ assertKeys(recipe, [...FIT_KEYS, ...SAMPLE_KEYS, ...(combinedClipAppearance ? FRAME_KEYS : [])]);
+ if (sourceKind === "still" && sourceTime !== undefined) fail(recipe, "cannot apply source time to a still picture.");
+ return sealMediaSampleLayerSpec({
+ id,
+ ...(sourceTime === undefined ? {} : { sourceTime }),
+ appearance: decodeMediaSampleAppearance(recipe),
+ ...(samplingMotion === undefined ? {} : { samplingMotion }),
+ });
+}
+
+/** Decode visual-only sample styling without choosing playback or source trim. */
+/** Public authored defaults shared by decoding and optional editor fields. */
+export const visualTreatmentDefaults = {
+ 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", visualTreatmentDefaults.opacity),
+ filter: {
+ blurPx: number(recipe, "blur", visualTreatmentDefaults.blur), brightness: number(recipe, "brightness", visualTreatmentDefaults.brightness),
+ contrast: number(recipe, "contrast", visualTreatmentDefaults.contrast), saturation: number(recipe, "saturation", visualTreatmentDefaults.saturation),
+ },
+ };
+}
+
+export function decodeVisualFrameTreatment(recipe: SvsRecipe): VisualFrameTreatment {
+ const clip = oneOf(recipe, "clip", ["none", "frame", "rounded"] as const, visualTreatmentDefaults.clip);
+ const borderWidth = number(recipe, "border-width", 0);
+ return {
+ clip: clip === "rounded" ? { kind: "rounded", radiusPx: number(recipe, "radius", visualTreatmentDefaults.radius) } : { kind: clip },
+ padding: padding(recipe),
+ ...(borderWidth === 0 ? {} : { border: {
+ widthPx: borderWidth,
+ style: oneOf(recipe, "border-style", ["solid", "dashed", "dotted"] as const, "solid"),
+ color: string(recipe, "border-color"),
+ } }),
+ shadows: shadows(recipe),
+ };
+}
+
+export function decodeVisualClipSpec(
+ recipe: SvsRecipe,
+ input: Pick<VisualClipSpec, "id" | "motion" | "z">,
+): VisualClipSpec {
+ assertKeys(recipe, [...SAMPLE_KEYS, ...FRAME_KEYS]);
+ return sealVisualClipSpec({
+
+ id: input.id,
+ treatment: decodeVisualFrameTreatment(recipe),
+ ...(input.motion === undefined ? {} : { motion: input.motion }),
+ z: input.z,
+ });
+}
+
+export function decodeMediaFramePaint(recipe: SvsRecipe, id: string): MediaPaintLayerSpec | undefined {
+ const source = optionalString(recipe, "frame-paint");
+ if (source === undefined || source === "transparent") return undefined;
+ const adapted: SvsRecipe = { ...recipe, properties: { paint: source } };
+ return sealMediaPaintLayerSpec({ id, paint: paint(adapted), opacity: 1 });
+}
+
+export function decodeMediaPaintSpec(recipe: SvsRecipe, id: string): MediaPaintLayerSpec {
+ assertKeys(recipe, ["paint", "opacity"]);
+ return sealMediaPaintLayerSpec({
+ id, paint: paint(recipe), opacity: number(recipe, "opacity", visualTreatmentDefaults.opacity),
+ });
+}
+
+export const visualMaterialKeys = { fit: FIT_KEYS, sample: SAMPLE_KEYS, frame: FRAME_KEYS } as const;
diff --git a/packages/visual-track/src/component.ts b/packages/visual-track/src/component.ts
new file mode 100644
index 00000000..75d3cd22
--- /dev/null
+++ b/packages/visual-track/src/component.ts
@@ -0,0 +1,122 @@
+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 { ContentFit, IntrinsicExtent, SpatialFrame, SpatialMap2D, SpatialPath } from "@hypit/spatial";
+import type { TemporalWindow } from "@hypit/temporal";
+import type { Timeline } from "@hypit/timeline";
+
+import {
+ appendMediaPaintLayer,
+ appendMappedStillMediaLayer,
+ appendMappedSurfaceMediaLayer,
+ appendMappedTimedMediaLayer,
+ appendStillMediaLayer,
+ appendSurfaceMediaLayer,
+ appendTimedMediaLayer,
+ createMediaLayerSet,
+} from "./layers.js";
+import { visualTrackProducers, visualTrackTypes } from "./manifest.js";
+import {
+ appendVisualClip,
+ assertVisualTrackProgram,
+ bindVisualClipMotion,
+ bindVisualClipPath,
+ createVisualTrackSet,
+ finalizeVisualTrack,
+ projectVisualTrack,
+} from "./program.js";
+import type {
+ MediaLayerSet,
+ MediaPaintLayerSpec,
+ MediaSampleLayerSpec,
+ VisualClipMotion,
+ VisualClipSpec,
+ VisualTrackHeader,
+ VisualTrackProgram,
+ VisualTrackSet,
+} from "./types.js";
+
+function inline<T>(value: StoredValue | undefined, label: string): T {
+ if (value?.kind !== "inline") throw new Error(`${label} must be inline.`);
+ return value.value as unknown as T;
+}
+
+function blob(value: StoredValue | undefined): BlobRef {
+ if (value?.kind !== "blob") throw new Error("Visual source must be a BlobArtifact.");
+ return value;
+}
+
+const output = (value: unknown) => ({ kind: "inline" as const, value: canonicalize(value) });
+
+function clipInputs(inputs: ProducerHandlerContext["inputs"]) {
+ return {
+ set: inline<VisualTrackSet>(inputs.set?.value, "VisualTrackSet"),
+ header: inline<VisualTrackHeader>(inputs.header?.value, "VisualTrackHeader"),
+ timeline: inline<Timeline>(inputs.timeline?.value, "Timeline"),
+ layers: inline<MediaLayerSet>(inputs.layers?.value, "MediaLayerSet"),
+ frame: inline<SpatialFrame>(inputs.frame?.value, "SpatialFrame"),
+ spec: inline<VisualClipSpec>(inputs.spec?.value, "VisualClipSpec"),
+ window: inline<TemporalWindow>(inputs.window?.value, "TemporalWindow"),
+ };
+}
+
+export const visualTrackComponent = {
+ producers: [
+ { producer: visualTrackProducers.createLayers, handler: () => ({ outputs: { layers: output(createMediaLayerSet()) }, needs: {} }) },
+ { producer: visualTrackProducers.appendPaintLayer, handler: ({ inputs }) => ({ outputs: { layers: output(appendMediaPaintLayer(
+ inline<MediaLayerSet>(inputs.layers?.value, "MediaLayerSet"),
+ inline<MediaPaintLayerSpec>(inputs.spec?.value, "MediaPaintLayerSpec"),
+ )) }, needs: {} }) },
+ { producer: visualTrackProducers.appendStillLayer, handler: ({ inputs }) => ({ outputs: { layers: output(appendStillMediaLayer(
+ inline<MediaLayerSet>(inputs.layers?.value, "MediaLayerSet"), blob(inputs.source?.value),
+ inline<IntrinsicExtent>(inputs.extent?.value, "IntrinsicExtent"), inline<ContentFit>(inputs.fit?.value, "ContentFit"),
+ inline<MediaSampleLayerSpec>(inputs.spec?.value, "MediaSampleLayerSpec"),
+ )) }, needs: {} }) },
+ { producer: visualTrackProducers.appendMappedStillLayer, handler: ({ inputs }) => ({ outputs: { layers: output(appendMappedStillMediaLayer(
+ inline<MediaLayerSet>(inputs.layers?.value, "MediaLayerSet"), blob(inputs.source?.value),
+ inline<IntrinsicExtent>(inputs.extent?.value, "IntrinsicExtent"), inline<SpatialMap2D>(inputs.mapping?.value, "SpatialMap2D"),
+ inline<MediaSampleLayerSpec>(inputs.spec?.value, "MediaSampleLayerSpec"),
+ )) }, needs: {} }) },
+ { producer: visualTrackProducers.appendTimedLayer, handler: ({ inputs }) => ({ outputs: { layers: output(appendTimedMediaLayer(
+ inline<MediaLayerSet>(inputs.layers?.value, "MediaLayerSet"), inline<SynchronizedMedia>(inputs.source?.value, "SynchronizedMedia"),
+ inline<ContentFit>(inputs.fit?.value, "ContentFit"), inline<MediaSampleLayerSpec>(inputs.spec?.value, "MediaSampleLayerSpec"),
+ )) }, needs: {} }) },
+ { producer: visualTrackProducers.appendMappedTimedLayer, handler: ({ inputs }) => ({ outputs: { layers: output(appendMappedTimedMediaLayer(
+ inline<MediaLayerSet>(inputs.layers?.value, "MediaLayerSet"), inline<SynchronizedMedia>(inputs.source?.value, "SynchronizedMedia"),
+ inline<SpatialMap2D>(inputs.mapping?.value, "SpatialMap2D"), inline<MediaSampleLayerSpec>(inputs.spec?.value, "MediaSampleLayerSpec"),
+ )) }, needs: {} }) },
+ { producer: visualTrackProducers.appendSurfaceLayer, handler: ({ inputs }) => ({ outputs: { layers: output(appendSurfaceMediaLayer(
+ inline<MediaLayerSet>(inputs.layers?.value, "MediaLayerSet"), inline<CompositableSurfaceRef>(inputs.source?.value, "CompositableSurfaceRef"),
+ inline<ContentFit>(inputs.fit?.value, "ContentFit"), inline<MediaSampleLayerSpec>(inputs.spec?.value, "MediaSampleLayerSpec"),
+ )) }, needs: {} }) },
+ { producer: visualTrackProducers.appendMappedSurfaceLayer, handler: ({ inputs }) => ({ outputs: { layers: output(appendMappedSurfaceMediaLayer(
+ inline<MediaLayerSet>(inputs.layers?.value, "MediaLayerSet"), inline<CompositableSurfaceRef>(inputs.source?.value, "CompositableSurfaceRef"),
+ inline<SpatialMap2D>(inputs.mapping?.value, "SpatialMap2D"), inline<MediaSampleLayerSpec>(inputs.spec?.value, "MediaSampleLayerSpec"),
+ )) }, needs: {} }) },
+ { producer: visualTrackProducers.createSet, handler: () => ({ outputs: { set: output(createVisualTrackSet()) }, needs: {} }) },
+ { producer: visualTrackProducers.appendClip, handler: ({ inputs }) => {
+ const value = clipInputs(inputs);
+ return { outputs: { set: output(appendVisualClip(
+ value.set, value.header, value.timeline, value.layers, value.frame, value.spec, value.window,
+ )) }, needs: {} };
+ } },
+ { producer: visualTrackProducers.bindClipPath, handler: ({ inputs }) => ({ outputs: { spec: output(bindVisualClipPath(
+ inline<VisualClipSpec>(inputs.spec?.value, "VisualClipSpec"), inline<SpatialPath>(inputs.path?.value, "SpatialPath"),
+ )) }, needs: {} }) },
+ { producer: visualTrackProducers.bindMotion, handler: ({ inputs }) => ({ outputs: { spec: output(bindVisualClipMotion(
+ inline<VisualClipSpec>(inputs.spec?.value, "VisualClipSpec"), inline<VisualClipMotion>(inputs.motion?.value, "VisualClipMotion"),
+ )) }, needs: {} }) },
+ { producer: visualTrackProducers.finalize, handler: ({ inputs }) => ({ outputs: { program: output(finalizeVisualTrack(
+ inline<VisualTrackSet>(inputs.set?.value, "VisualTrackSet"), inline<VisualTrackHeader>(inputs.header?.value, "VisualTrackHeader"),
+ inline<Timeline>(inputs.timeline?.value, "Timeline"),
+ )) }, needs: {} }) },
+ { producer: visualTrackProducers.projectVisual, handler: ({ inputs }) => ({ outputs: { track: output(projectVisualTrack(
+ inline<Timeline>(inputs.timeline?.value, "Timeline"), inline<VisualTrackProgram>(inputs.program?.value, "VisualTrackProgram"),
+ )) }, needs: {} }) },
+ ],
+ validators: [{
+ type: visualTrackTypes.program,
+ handler: ({ value }) => assertVisualTrackProgram(inline<VisualTrackProgram>(value, "VisualTrackProgram")),
+ }],
+} satisfies ComponentPackage;
diff --git a/packages/visual-track/src/fragment.ts b/packages/visual-track/src/fragment.ts
new file mode 100644
index 00000000..8a81bf68
--- /dev/null
+++ b/packages/visual-track/src/fragment.ts
@@ -0,0 +1,56 @@
+import { timelineTypes } from "@hypit/timeline";
+
+import { artifactTypes } from "@hypit/artifact";
+import { compositionTypes } from "@hypit/composition";
+import { sealGraphFragment } from "@hypit/elaborator";
+import { spatialTypes } from "@hypit/spatial";
+import { temporalTypes } from "@hypit/temporal";
+
+import { visualTrackProducers, visualTrackTypes } from "./manifest.js";
+
+const input = (name: string) => ({ kind: "fragment-input" as const, name });
+const operation = (id: string) => ({ kind: "fragment-operation" as const, operation: id });
+
+/** Minimal complete graph witness; richer Surfaces generate the same primitive operations dynamically. */
+export const stillVisualTrackFragment = sealGraphFragment({
+ inputs: [
+ { name: "header", type: visualTrackTypes.header },
+ { name: "timeline", type: timelineTypes.track },
+ { name: "source", type: artifactTypes.blob },
+ { name: "extent", type: spatialTypes.extent },
+ { name: "frame", type: spatialTypes.frame },
+ { name: "fit", type: spatialTypes.fit },
+ { name: "sample-spec", type: visualTrackTypes.sampleLayerSpec },
+ { name: "clip-spec", type: visualTrackTypes.clipSpec },
+ { name: "window", type: temporalTypes.window },
+ ],
+ operations: [
+ { id: "layers", producer: visualTrackProducers.createLayers, inputs: {}, result: { kind: "output", name: "layers" } },
+ { id: "sample", producer: visualTrackProducers.appendStillLayer, inputs: {
+ layers: operation("layers"), source: input("source"), extent: input("extent"), fit: input("fit"), spec: input("sample-spec"),
+ }, result: { kind: "output", name: "layers" } },
+ { id: "set", producer: visualTrackProducers.createSet, inputs: {}, result: { kind: "output", name: "set" } },
+ { id: "append", producer: visualTrackProducers.appendClip, inputs: {
+ set: operation("set"), header: input("header"), timeline: input("timeline"), layers: operation("sample"),
+ frame: input("frame"), spec: input("clip-spec"), window: input("window"),
+ }, result: { kind: "output", name: "set" } },
+ { id: "finalize", producer: visualTrackProducers.finalize, inputs: {
+ set: operation("append"), header: input("header"), timeline: input("timeline"),
+ }, result: { kind: "output", name: "program" } },
+ { id: "visual", producer: visualTrackProducers.projectVisual, inputs: {
+ timeline: input("timeline"), program: operation("finalize"),
+ }, result: { kind: "output", name: "track" } },
+ ],
+ exports: [
+ { name: "program", type: visualTrackTypes.program, root: operation("finalize") },
+ { name: "visual", type: compositionTypes.visualTrack, root: operation("visual") },
+ ],
+});
+
+export const renderVisualTrackFragment = sealGraphFragment({
+ inputs: [{ name: "timeline", type: timelineTypes.track }, { name: "program", type: visualTrackTypes.program }],
+ operations: [
+ { id: "visual", producer: visualTrackProducers.projectVisual, inputs: { timeline: input("timeline"), program: input("program") }, result: { kind: "output", name: "track" } },
+ ],
+ exports: [{ name: "visual", type: compositionTypes.visualTrack, root: operation("visual") }],
+});
diff --git a/packages/media-track/src/presentation.ts b/packages/visual-track/src/frame-treatment.ts
similarity index 54%
rename from packages/media-track/src/presentation.ts
rename to packages/visual-track/src/frame-treatment.ts
index 0cadaed3..d4538e96 100644
--- a/packages/media-track/src/presentation.ts
+++ b/packages/visual-track/src/frame-treatment.ts
@@ -1,6 +1,7 @@
-import { assertSpatialPath } from "@hypit/spatial";
+import { assertSpatialFrame, assertSpatialPath } from "@hypit/spatial";
+import type { SpatialFrame } from "@hypit/spatial";
-import type { MediaFramePresentation } from "./types.js";
+import type { VisualFrameTreatment } from "./types.js";
function assert(condition: unknown, message: string): asserts condition {
if (!condition) throw new Error(message);
@@ -10,7 +11,7 @@ function finite(value: number, label: string): void {
assert(Number.isFinite(value), `${label} must be finite.`);
}
-export function assertMediaFramePresentation(value: MediaFramePresentation, label: string): void {
+export function assertVisualFrameTreatment(value: VisualFrameTreatment, label: string): void {
assert(["none", "frame", "rounded", "path"].includes(value.clip.kind), `${label}.clip is invalid.`);
if (value.clip.kind === "rounded") {
finite(value.clip.radiusPx, `${label}.clip.radiusPx`);
@@ -33,3 +34,22 @@ export function assertMediaFramePresentation(value: MediaFramePresentation, labe
assert(shadow.blurPx >= 0 && shadow.color.length > 0, `${label}.shadows.${index} is invalid.`);
}
}
+
+/**
+ * Derive the area used by ordinary ContentFit. This is not a second authored
+ * Frame: it is the deterministic inset of the Clip's one public Frame.
+ */
+export function visualContentFrame(frame: SpatialFrame, treatment: VisualFrameTreatment): SpatialFrame {
+ assertSpatialFrame(frame);
+ assertVisualFrameTreatment(treatment, "VisualFrameTreatment");
+ const border = treatment.border?.widthPx ?? 0;
+ const result = {
+ xPx: frame.xPx + border + treatment.padding.leftPx,
+ yPx: frame.yPx + border + treatment.padding.topPx,
+ widthPx: frame.widthPx - border * 2 - treatment.padding.leftPx - treatment.padding.rightPx,
+ heightPx: frame.heightPx - border * 2 - treatment.padding.topPx - treatment.padding.bottomPx,
+ };
+ assert(result.widthPx > 0 && result.heightPx > 0, "Visual treatment consumes its complete Frame.");
+ assertSpatialFrame(result);
+ return result;
+}
diff --git a/packages/visual-track/src/index.ts b/packages/visual-track/src/index.ts
new file mode 100644
index 00000000..5def1ad7
--- /dev/null
+++ b/packages/visual-track/src/index.ts
@@ -0,0 +1,45 @@
+export { visualTrackComponent } from "./component.js";
+export {
+ decodeMediaFit,
+ decodeVisualClipSpec,
+ decodeMediaFramePaint,
+ decodeVisualFrameTreatment,
+ decodeMediaSampleAppearance,
+ decodeMediaSampleSpec,
+ visualMaterialKeys,
+} from "./author.js";
+export { renderVisualTrackFragment, stillVisualTrackFragment } from "./fragment.js";
+export {
+ appendMappedStillMediaLayer,
+ appendMappedSurfaceMediaLayer,
+ appendMappedTimedMediaLayer,
+ appendMediaPaintLayer,
+ appendStillMediaLayer,
+ appendSurfaceMediaLayer,
+ appendTimedMediaLayer,
+ assertMediaLayerSet,
+ assertMediaPaintLayerSpec,
+ assertMediaSampleLayerSpec,
+ assertMediaVisualSource,
+ createMediaLayerSet,
+ sealMediaPaintLayerSpec,
+ sealMediaSampleLayerSpec,
+} from "./layers.js";
+export { assertMediaLayerPrograms, resolveMediaLayerPrograms } from "./spatial.js";
+export { lowerVisualClipElements } from "./lower.js";
+export { visualClipSpecSchema, visualClipMotionSchema, visualFrameTreatmentSchema, visualSourceTimeSpecSchema, mediaLayerSetSchema, mediaPaintLayerSpecSchema, mediaSampleAppearanceSchema, mediaSampleLayerSpecSchema, mediaSamplingMotionSchema, visualTrackDependency, visualTrackHeaderSchema, visualTrackManifest, visualTrackMarkupSurfaces, visualTrackModuleRef, visualTrackProducers, visualTrackProgramSchema, visualTrackSetSchema, visualTrackTypes } from "./manifest.js";
+export {
+ assertVisualClipMotion,
+ assertVisualMotionPosition,
+ poseAnimation,
+ resolveVisualMotionPosition,
+ sealVisualClipMotion,
+ samplingAnimation,
+} from "./motion.js";
+export { assertVisualFrameTreatment, visualContentFrame } from "./frame-treatment.js";
+export { appendVisualClip, bindVisualClipMotion, bindVisualClipPath, assertVisualClipSpec, assertVisualTrackHeader, assertVisualTrackProgram, assertVisualTrackProgramIdentity, assertVisualTrackSet, createVisualTrackSet, finalizeVisualTrack, projectVisualTrack, sealVisualClipSpec, sealVisualTrackHeader, sealVisualTrackProgram } from "./program.js";
+export { assertVisualSourceTimeSpec, defaultVisualSourceTimeSpec, resolveVisualSourceTime } from "./source-time.js";
+export { decodeMediaSamplingKeyframe, decodeVisualMotionSurface, decodeVisualPoseKeyframe, decodeVisualSourceTimeRelation, decodeVisualSourceTimeSurface, decodeVisualTrackSurface } from "./surface.js";
+export type * from "./types.js";
+
+export { visualTreatmentDefaults } from "./author.js";
diff --git a/packages/media-track/src/layers.ts b/packages/visual-track/src/layers.ts
similarity index 67%
rename from packages/media-track/src/layers.ts
rename to packages/visual-track/src/layers.ts
index 8792877f..ad77a960 100644
--- a/packages/media-track/src/layers.ts
+++ b/packages/visual-track/src/layers.ts
@@ -1,6 +1,5 @@
import {
assertCompositableSurfaceRef,
- synchronizedMediaSampleFrames,
verifySynchronizedMedia,
} from "@hypit/media";
import type { CompositableSurfaceRef, SynchronizedMedia } from "@hypit/media";
@@ -9,22 +8,22 @@ import type { BlobRef } from "@hypit/protocol";
import {
assertContentFit,
assertIntrinsicExtent,
+ assertSpatialMap2D,
} from "@hypit/spatial";
-import type { ContentFit, IntrinsicExtent } from "@hypit/spatial";
+import type { ContentFit, IntrinsicExtent, SpatialMap2D } from "@hypit/spatial";
import type {
MediaGradientStop,
- MediaLayerProgram,
+ MediaLayer,
MediaLayerSet,
MediaPaint,
MediaPaintLayerSpec,
- MediaSampleLayerProgram,
+ MediaSampleLayer,
MediaSampleLayerSpec,
MediaSamplingMotion,
- MediaVisualOccupancy,
MediaVisualSource,
- MediaVisualTrim,
} from "./types.js";
+import { assertVisualSourceTimeSpec, defaultVisualSourceTimeSpec } from "./source-time.js";
function assert(condition: unknown, message: string): asserts condition {
if (!condition) throw new Error(message);
@@ -80,18 +79,6 @@ export function assertMediaPaint(value: MediaPaint, label: string): void {
unit(value.center.y, `${label}.center.y`);
}
-export function assertMediaVisualTrim(value: MediaVisualTrim, sourceFrames: number, label: string): void {
- assert(Number.isSafeInteger(value.startFrame) && Number.isSafeInteger(value.endFrameExclusive)
- && value.startFrame >= 0 && value.endFrameExclusive > value.startFrame
- && value.endFrameExclusive <= sourceFrames, `${label} is outside its source.`);
-}
-
-export function assertMediaVisualOccupancy(value: MediaVisualOccupancy, label: string): void {
- if (value.mode === "stretch") return;
- assert(["once", "hold", "loop"].includes(value.mode)
- && (value.align === "start" || value.align === "end"), `${label} is invalid.`);
-}
-
export function assertMediaSamplingMotion(value: MediaSamplingMotion, label: string): void {
assert(value.keyframes.length >= 2, `${label} needs at least two keyframes.`);
let previous = -1;
@@ -131,11 +118,6 @@ export function assertMediaVisualSource(value: MediaVisualSource, label: string)
assert(Number.isSafeInteger(value.frameRate.numerator) && value.frameRate.numerator > 0
&& Number.isSafeInteger(value.frameRate.denominator) && value.frameRate.denominator > 0
&& Number.isSafeInteger(value.frameCount) && value.frameCount > 0, `${label} timing is invalid.`);
- if (value.audio !== undefined) {
- assertBlob(value.audio.artifact, `${label}.audio.artifact`, "audio/");
- assert(Number.isSafeInteger(value.audio.sampleFrames) && value.audio.sampleFrames > 0,
- `${label}.audio.sampleFrames is invalid.`);
- }
}
export function assertMediaSampleLayerSpec(value: MediaSampleLayerSpec): void {
@@ -148,7 +130,7 @@ export function assertMediaSampleLayerSpec(value: MediaSampleLayerSpec): void {
finite(filter.saturation, "MediaSampleLayerSpec.filter.saturation");
assert(filter.blurPx >= 0 && filter.brightness >= 0 && filter.contrast >= 0 && filter.saturation >= 0,
"MediaSampleLayerSpec filter values must be non-negative.");
- if (value.occupancy !== undefined) assertMediaVisualOccupancy(value.occupancy, "MediaSampleLayerSpec.occupancy");
+ if (value.sourceTime !== undefined) assertVisualSourceTimeSpec(value.sourceTime, "MediaSampleLayerSpec.sourceTime");
if (value.samplingMotion !== undefined) assertMediaSamplingMotion(value.samplingMotion, "MediaSampleLayerSpec.samplingMotion");
}
@@ -186,35 +168,32 @@ export function assertMediaLayerSet(value: MediaLayerSet): void {
}
assert(layer.kind === "sample", `Media layer ${layer.id} kind is unsupported.`);
assertMediaVisualSource(layer.source, `Media layer ${layer.id}.source`);
- assertContentFit(layer.fit);
+ if (layer.placement.kind === "fit") assertContentFit(layer.placement.fit);
+ else if (layer.placement.kind === "mapping") assertSpatialMap2D(layer.placement.mapping);
+ else assert(false, `Media layer ${layer.id} placement is unsupported.`);
if (layer.source.kind === "still") {
- assert(layer.trim === undefined && layer.occupancy === undefined,
- `Still Media layer ${layer.id} cannot have trim or occupancy.`);
+ assert(layer.sourceTime === undefined, `Still Media layer ${layer.id} cannot have source time.`);
} else {
const frames = layer.source.kind === "timed"
? layer.source.frameCount
: layer.source.surface.timing.kind === "frames" ? layer.source.surface.timing.frameCount : undefined;
if (frames === undefined) {
- assert(layer.trim === undefined && layer.occupancy === undefined,
- `Still Surface layer ${layer.id} cannot have trim or occupancy.`);
+ assert(layer.sourceTime === undefined, `Still Surface layer ${layer.id} cannot have source time.`);
} else {
- if (layer.trim !== undefined) assertMediaVisualTrim(layer.trim, frames, `Media layer ${layer.id}.trim`);
- assert(layer.occupancy !== undefined, `Timed Media layer ${layer.id} requires occupancy.`);
- assertMediaVisualOccupancy(layer.occupancy, `Media layer ${layer.id}.occupancy`);
+ assert(layer.sourceTime !== undefined, `Timed Media layer ${layer.id} requires source time.`);
+ if (layer.sourceTime.kind === "spec") assertVisualSourceTimeSpec(layer.sourceTime.value, `Media layer ${layer.id}.sourceTime`);
}
}
assertMediaSampleLayerSpec({
-
id: layer.id,
- ...(layer.trim === undefined ? {} : { trim: layer.trim }),
- ...(layer.occupancy === undefined ? {} : { occupancy: layer.occupancy }),
+ ...(layer.sourceTime?.kind !== "spec" ? {} : { sourceTime: layer.sourceTime.value }),
appearance: layer.appearance,
...(layer.samplingMotion === undefined ? {} : { samplingMotion: layer.samplingMotion }),
});
}
}
-function append(set: MediaLayerSet, layer: MediaLayerProgram): MediaLayerSet {
+function append(set: MediaLayerSet, layer: MediaLayer): MediaLayerSet {
assertMediaLayerSet(set);
assert(!set.layers.some((item) => item.id === layer.id), `MediaLayerSet already contains ${layer.id}.`);
const result = { layers: [...set.layers, layer] };
@@ -227,17 +206,21 @@ export function appendMediaPaintLayer(set: MediaLayerSet, spec: MediaPaintLayerS
return append(set, { id: spec.id, kind: "paint", paint: structuredClone(spec.paint), opacity: spec.opacity });
}
-function sampleLayer(source: MediaVisualSource, fit: ContentFit, spec: MediaSampleLayerSpec): MediaSampleLayerProgram {
+function sampleLayer(
+ source: MediaVisualSource,
+ placement: MediaSampleLayer["placement"],
+ spec: MediaSampleLayerSpec,
+): MediaSampleLayer {
assertMediaVisualSource(source, "Media sample source");
- assertContentFit(fit);
+ if (placement.kind === "fit") assertContentFit(placement.fit);
+ else assertSpatialMap2D(placement.mapping);
assertMediaSampleLayerSpec(spec);
- const layer: MediaSampleLayerProgram = {
+ const layer: MediaSampleLayer = {
id: spec.id,
kind: "sample",
source: structuredClone(source),
- fit: structuredClone(fit),
- ...(spec.trim === undefined ? {} : { trim: { ...spec.trim } }),
- ...(spec.occupancy === undefined ? {} : { occupancy: structuredClone(spec.occupancy) }),
+ placement: structuredClone(placement),
+ ...(spec.sourceTime === undefined ? {} : { sourceTime: { kind: "spec", value: structuredClone(spec.sourceTime) } as const }),
appearance: structuredClone(spec.appearance),
...(spec.samplingMotion === undefined ? {} : { samplingMotion: structuredClone(spec.samplingMotion) }),
};
@@ -253,9 +236,28 @@ export function appendStillMediaLayer(
): MediaLayerSet {
assertBlob(source, "Still Media source", "image/");
assertIntrinsicExtent(extent);
- assert(spec.trim === undefined && spec.occupancy === undefined,
- "Still Media source cannot have trim or occupancy.");
- return append(set, sampleLayer({ kind: "still", artifact: structuredClone(source), extent: { ...extent } }, fit, spec));
+ assert(spec.sourceTime === undefined, "Still Media source cannot have source time.");
+ return append(set, sampleLayer(
+ { kind: "still", artifact: structuredClone(source), extent: { ...extent } },
+ { kind: "fit", fit: structuredClone(fit) }, spec,
+ ));
+}
+
+export function appendMappedStillMediaLayer(
+ set: MediaLayerSet,
+ source: BlobRef,
+ extent: IntrinsicExtent,
+ mapping: SpatialMap2D,
+ spec: MediaSampleLayerSpec,
+): MediaLayerSet {
+ assertBlob(source, "Still Media source", "image/");
+ assertIntrinsicExtent(extent);
+ assertSpatialMap2D(mapping);
+ assert(spec.sourceTime === undefined, "Still Media source cannot have source time.");
+ return append(set, sampleLayer(
+ { kind: "still", artifact: structuredClone(source), extent: { ...extent } },
+ { kind: "mapping", mapping: structuredClone(mapping) }, spec,
+ ));
}
export function appendTimedMediaLayer(
@@ -266,7 +268,6 @@ export function appendTimedMediaLayer(
): MediaLayerSet {
verifySynchronizedMedia(media);
assert(media.visual !== undefined, "Timed Media source has no normalized visual member.");
- assert(spec.occupancy !== undefined, "Timed Media source requires explicit occupancy.");
const source: MediaVisualSource = {
kind: "timed",
artifact: structuredClone(media.visual.artifact),
@@ -274,14 +275,35 @@ export function appendTimedMediaLayer(
widthPx: media.visual.width,
heightPx: media.visual.height,
},
- frameRate: { ...media.timeline.frameRate },
- frameCount: media.timeline.frameCount,
- ...(media.audio === undefined ? {} : { audio: {
- artifact: structuredClone(media.audio.artifact),
- sampleFrames: synchronizedMediaSampleFrames(media),
- } }),
+ frameRate: { ...media.frameDomain.frameRate },
+ frameCount: media.frameDomain.frameCount,
+ };
+ return append(set, sampleLayer(source, { kind: "fit", fit: structuredClone(fit) }, {
+ ...spec,
+ sourceTime: spec.sourceTime ?? defaultVisualSourceTimeSpec(),
+ }));
+}
+
+export function appendMappedTimedMediaLayer(
+ set: MediaLayerSet,
+ media: SynchronizedMedia,
+ mapping: SpatialMap2D,
+ spec: MediaSampleLayerSpec,
+): MediaLayerSet {
+ verifySynchronizedMedia(media);
+ assert(media.visual !== undefined, "Timed Media source has no normalized visual member.");
+ assertSpatialMap2D(mapping);
+ const source: MediaVisualSource = {
+ kind: "timed",
+ artifact: structuredClone(media.visual.artifact),
+ extent: { widthPx: media.visual.width, heightPx: media.visual.height },
+ frameRate: { ...media.frameDomain.frameRate },
+ frameCount: media.frameDomain.frameCount,
};
- return append(set, sampleLayer(source, fit, spec));
+ return append(set, sampleLayer(source, { kind: "mapping", mapping: structuredClone(mapping) }, {
+ ...spec,
+ sourceTime: spec.sourceTime ?? defaultVisualSourceTimeSpec(),
+ }));
}
export function appendSurfaceMediaLayer(
@@ -293,16 +315,38 @@ export function appendSurfaceMediaLayer(
assertCompositableSurfaceRef(surface);
let effectiveSpec = spec;
if (surface.timing.kind === "frames") {
- effectiveSpec = spec.occupancy === undefined
- ? sealMediaSampleLayerSpec({ ...spec, occupancy: { mode: "once", align: "start" } })
+ effectiveSpec = spec.sourceTime === undefined
+ ? sealMediaSampleLayerSpec({ ...spec, sourceTime: defaultVisualSourceTimeSpec() })
+ : spec;
+ } else {
+ assert(spec.sourceTime === undefined, "Still Media Surface cannot have source time.");
+ }
+ return append(set, sampleLayer({
+ kind: "surface",
+ surface: structuredClone(surface),
+ extent: { widthPx: surface.width, heightPx: surface.height },
+ }, { kind: "fit", fit: structuredClone(fit) }, effectiveSpec));
+}
+
+export function appendMappedSurfaceMediaLayer(
+ set: MediaLayerSet,
+ surface: CompositableSurfaceRef,
+ mapping: SpatialMap2D,
+ spec: MediaSampleLayerSpec,
+): MediaLayerSet {
+ assertCompositableSurfaceRef(surface);
+ assertSpatialMap2D(mapping);
+ let effectiveSpec = spec;
+ if (surface.timing.kind === "frames") {
+ effectiveSpec = spec.sourceTime === undefined
+ ? sealMediaSampleLayerSpec({ ...spec, sourceTime: defaultVisualSourceTimeSpec() })
: spec;
} else {
- assert(spec.trim === undefined && spec.occupancy === undefined,
- "Still Media Surface cannot have trim or occupancy.");
+ assert(spec.sourceTime === undefined, "Still Media Surface cannot have source time.");
}
return append(set, sampleLayer({
kind: "surface",
surface: structuredClone(surface),
extent: { widthPx: surface.width, heightPx: surface.height },
- }, fit, effectiveSpec));
+ }, { kind: "mapping", mapping: structuredClone(mapping) }, effectiveSpec));
}
diff --git a/packages/media-track/src/lower.ts b/packages/visual-track/src/lower.ts
similarity index 55%
rename from packages/media-track/src/lower.ts
rename to packages/visual-track/src/lower.ts
index 438bfaa1..27887d67 100644
--- a/packages/media-track/src/lower.ts
+++ b/packages/visual-track/src/lower.ts
@@ -3,17 +3,17 @@ import type {
VisualAnimation,
VisualElement,
VisualStyleDeclaration,
- VisualTimedSampling,
+ VisualSourceTimeMap,
} from "@hypit/composition";
-import { fitContent } from "@hypit/spatial";
+import { mapSpatialPoint } from "@hypit/spatial";
import type { SpatialFrame, SpatialPath } from "@hypit/spatial";
-import { lifecycleAnimation, samplingAnimation, sustainAnimation } from "./motion.js";
-import { resolveVisualSampling } from "./sampling.js";
+import { poseAnimation, samplingAnimation } from "./motion.js";
+import { resolveVisualSourceTime } from "./source-time.js";
import type {
- MediaFramePresentation,
+ VisualFrameTreatment,
MediaGradientStop,
- MediaItemProgram,
+ VisualClipProgram,
MediaLayerProgram,
MediaPaint,
MediaSampleLayerProgram,
@@ -21,7 +21,7 @@ import type {
function px(value: number): string { return `${value}px`; }
-function box(id: string, order: number, parent: string | undefined, animation?: VisualAnimation): VisualElement {
+function box(id: string, order: number, parent: string | undefined, animation?: VisualAnimation, transformOrigin = "center center"): VisualElement {
return {
id,
...(parent === undefined ? {} : { parent }),
@@ -32,7 +32,7 @@ function box(id: string, order: number, parent: string | undefined, animation?:
{ name: "left", value: 0 },
{ name: "position", value: "absolute" },
{ name: "top", value: 0 },
- { name: "transform-origin", value: "center center" },
+ { name: "transform-origin", value: transformOrigin },
{ name: "width", value: "100%" },
],
...(animation === undefined ? {} : { animation }),
@@ -52,10 +52,10 @@ function paint(value: MediaPaint): string {
}
/**
- * A Path is drawn in Canvas pixels, and the element it clips is the Frame's own box — positioned at
- * the Frame's origin, so its coordinates start there. Handed the Canvas numbers unchanged, the clip
+ * A Path is drawn in program picture-plane pixels, and the element it clips is the Frame's own box — positioned at
+ * the Frame's origin, so its coordinates start there. Handed the absolute picture-plane numbers unchanged, the clip
* region lands one Frame origin down and to the right of where it was drawn, which for any Frame away
- * from the corner is entirely outside the box: the Item renders blank.
+ * from the corner is entirely outside the box: the Clip renders blank.
*/
function pathData(path: SpatialPath, origin: SpatialFrame): string {
const x = (value: number): number => value - origin.xPx;
@@ -71,7 +71,7 @@ function pathData(path: SpatialPath, origin: SpatialFrame): string {
}).join(" ");
}
-function frameStyles(value: MediaFramePresentation, frame: SpatialFrame): VisualStyleDeclaration[] {
+function frameStyles(value: VisualFrameTreatment, frame: SpatialFrame): VisualStyleDeclaration[] {
const styles: VisualStyleDeclaration[] = [
{ name: "box-sizing", value: "border-box" },
{ name: "height", value: "100%" },
@@ -99,25 +99,6 @@ function frameStyles(value: MediaFramePresentation, frame: SpatialFrame): Visual
return styles;
}
-/**
- * The box a layer is fitted into: the Frame less its border and its padding.
- *
- * The border was left out, and it is drawn inward — `box-sizing: border-box` puts it inside the
- * Frame's own rectangle — so a fitted picture was sized against a box wider and taller than the one
- * it had to sit in. What that looks like is the picture offset by the border width down and to the
- * right, with the same amount cut off its far edges, and a `contain` fit that no longer contains.
- */
-function innerFrame(item: MediaItemProgram): SpatialFrame {
- const { border, padding } = item.presentation;
- const edge = border?.widthPx ?? 0;
- return {
- xPx: item.frame.xPx + edge + padding.leftPx,
- yPx: item.frame.yPx + edge + padding.topPx,
- widthPx: item.frame.widthPx - edge * 2 - padding.leftPx - padding.rightPx,
- heightPx: item.frame.heightPx - edge * 2 - padding.topPx - padding.bottomPx,
- };
-}
-
function filter(layer: MediaSampleLayerProgram): string {
const value = layer.appearance.filter;
return [
@@ -130,35 +111,34 @@ function filter(layer: MediaSampleLayerProgram): string {
function sampleElements(
layer: MediaSampleLayerProgram,
- item: MediaItemProgram,
+ clip: VisualClipProgram,
parent: string,
order: { value: number },
timeline: Timeline,
- samplingOverrides: Readonly<Record<string, VisualTimedSampling>>,
+ sourceTimeOverrides: Readonly<Record<string, VisualSourceTimeMap>>,
samplingAnimationOverrides: Readonly<Record<string, VisualAnimation | null>>,
): VisualElement[] {
- const content = fitContent(innerFrame(item), layer.source.extent, layer.fit).contentFrame;
- const wrapper = `${layer.id}:sampling`;
- const durationFrames = item.span.endFrameExclusive - item.span.startFrame;
- const wrapperStyle: VisualStyleDeclaration[] = [
- { name: "height", value: px(content.heightPx) },
- { name: "left", value: px(content.xPx - item.frame.xPx) },
- { name: "position", value: "absolute" },
- { name: "top", value: px(content.yPx - item.frame.yPx) },
- { name: "transform-origin", value: "center center" },
- { name: "width", value: px(content.widthPx) },
- ];
- // A blur reads across the box and paints past it — roughly twice its radius — so a `contain` fit
- // that was letterboxed on purpose had its blurred copy spilling into the letterbox it was fitted
- // away from. Clipping the wrapper ends the overscan at the fitted rectangle; the Gaussian still
- // reads real content across the whole box, so only the spill goes.
- if (layer.appearance.filter.blurPx > 0) wrapperStyle.push({ name: "overflow", value: "hidden" });
- const wrapperElement: VisualElement = {
- id: wrapper,
+ const sourceCenter = mapSpatialPoint({
+ xPx: layer.source.extent.widthPx / 2,
+ yPx: layer.source.extent.heightPx / 2,
+ }, layer.mapping);
+ const sampling = `${layer.id}:sampling`;
+ const appearance = `${layer.id}:appearance`;
+ const mapping = `${layer.id}:mapping`;
+ const durationFrames = clip.span.endFrameExclusive - clip.span.startFrame;
+ const samplingElement: VisualElement = {
+ id: sampling,
parent,
order: order.value++,
kind: "box",
- style: wrapperStyle,
+ style: [
+ { name: "height", value: "100%" },
+ { name: "left", value: 0 },
+ { name: "position", value: "absolute" },
+ { name: "top", value: 0 },
+ { name: "transform-origin", value: `${px(sourceCenter.xPx - clip.frame.xPx)} ${px(sourceCenter.yPx - clip.frame.yPx)}` },
+ { name: "width", value: "100%" },
+ ],
...(() => {
const override = samplingAnimationOverrides[layer.id];
if (override === null) return {};
@@ -168,24 +148,70 @@ function sampleElements(
};
})(),
};
- // Blur samples are overscanned inside the owned frame before clipping. The
- // Gaussian kernel therefore never invents a transparent/dark border and still
- // cannot observe any pixel from a sibling Track.
+ const localTx = layer.mapping.tx - clip.frame.xPx;
+ const localTy = layer.mapping.ty - clip.frame.yPx;
+ const corners = [
+ { xPx: 0, yPx: 0 },
+ { xPx: layer.source.extent.widthPx, yPx: 0 },
+ { xPx: layer.source.extent.widthPx, yPx: layer.source.extent.heightPx },
+ { xPx: 0, yPx: layer.source.extent.heightPx },
+ ].map((point) => mapSpatialPoint(point, layer.mapping))
+ .map((point) => `${px(point.xPx - clip.frame.xPx)} ${px(point.yPx - clip.frame.yPx)}`);
+ const appearanceStyle: VisualStyleDeclaration[] = [
+ { name: "filter", value: filter(layer) },
+ { name: "height", value: "100%" },
+ { name: "left", value: 0 },
+ { name: "opacity", value: layer.appearance.opacity },
+ { name: "position", value: "absolute" },
+ { name: "top", value: 0 },
+ { name: "width", value: "100%" },
+ ];
+ if (layer.appearance.filter.blurPx > 0) {
+ appearanceStyle.push({ name: "clip-path", value: `polygon(${corners.join(",")})` });
+ }
+ const appearanceElement: VisualElement = {
+ id: appearance,
+ parent: sampling,
+ order: order.value++,
+ kind: "box",
+ style: appearanceStyle,
+ };
+ const mappingStyle: VisualStyleDeclaration[] = [
+ { name: "height", value: px(layer.source.extent.heightPx) },
+ { name: "left", value: 0 },
+ { name: "position", value: "absolute" },
+ { name: "top", value: 0 },
+ { name: "transform", value: `matrix(${layer.mapping.xx},${layer.mapping.yx},${layer.mapping.xy},${layer.mapping.yy},${localTx},${localTy})` },
+ { name: "transform-origin", value: "0 0" },
+ { name: "width", value: px(layer.source.extent.widthPx) },
+ ];
+ const mappingElement: VisualElement = {
+ id: mapping,
+ parent: appearance,
+ order: order.value++,
+ kind: "box",
+ style: mappingStyle,
+ };
+ // Filter lives after source mapping, so blur remains measured in program-picture pixels. The
+ // source is extended underneath the mapped outline before that outline clips the result; this
+ // keeps a blur from sampling transparent siblings or fading its own edge.
+ const xScale = Math.hypot(layer.mapping.xx, layer.mapping.yx);
+ const yScale = Math.hypot(layer.mapping.xy, layer.mapping.yy);
+ const positiveScales = [xScale, yScale].filter((value) => value > 0);
+ const minimumScale = positiveScales.length === 0 ? 1 : Math.min(...positiveScales);
const overscanPx = layer.appearance.filter.blurPx === 0
- ? 0 : Math.ceil(layer.appearance.filter.blurPx * 2);
+ ? 0 : Math.ceil(layer.appearance.filter.blurPx * 2 / minimumScale);
const mediaStyle: VisualStyleDeclaration[] = [
- { name: "filter", value: filter(layer) },
- { name: "height", value: overscanPx === 0 ? "100%" : px(content.heightPx + (overscanPx * 2)) },
+ { name: "height", value: overscanPx === 0 ? "100%" : px(layer.source.extent.heightPx + (overscanPx * 2)) },
{ name: "left", value: overscanPx === 0 ? 0 : px(-overscanPx) },
- { name: "opacity", value: layer.appearance.opacity },
{ name: "position", value: "absolute" },
{ name: "top", value: overscanPx === 0 ? 0 : px(-overscanPx) },
- { name: "width", value: overscanPx === 0 ? "100%" : px(content.widthPx + (overscanPx * 2)) },
+ { name: "width", value: overscanPx === 0 ? "100%" : px(layer.source.extent.widthPx + (overscanPx * 2)) },
];
if (layer.source.kind === "still") {
- return [wrapperElement, {
+ return [samplingElement, appearanceElement, mappingElement, {
id: layer.id,
- parent: wrapper,
+ parent: mapping,
order: order.value++,
kind: "image",
artifact: structuredClone(layer.source.artifact),
@@ -199,57 +225,57 @@ function sampleElements(
: undefined;
if (sourceTiming === undefined) {
if (layer.source.kind !== "surface") throw new Error(`Timed Media layer ${layer.id} has no timing.`);
- return [wrapperElement, {
+ return [samplingElement, appearanceElement, mappingElement, {
id: layer.id,
- parent: wrapper,
+ parent: mapping,
order: order.value++,
kind: "surface",
surface: structuredClone(layer.source.surface),
style: mediaStyle,
}];
}
- const sampling = samplingOverrides[layer.id] ?? layer.sampling ?? resolveVisualSampling({
+ const sourceTime = sourceTimeOverrides[layer.id]
+ ?? (layer.sourceTime?.kind === "map" ? layer.sourceTime.value : resolveVisualSourceTime({
timeline,
sourceFrameRate: sourceTiming.frameRate,
sourceFrameCount: sourceTiming.frameCount,
targetFrameCount: durationFrames,
- ...(layer.trim === undefined ? {} : { trim: layer.trim }),
- occupancy: layer.occupancy!,
- });
+ ...(layer.sourceTime?.kind !== "spec" ? {} : { spec: layer.sourceTime.value }),
+ }));
if (layer.source.kind === "timed") {
- return [wrapperElement, {
+ return [samplingElement, appearanceElement, mappingElement, {
id: layer.id,
- parent: wrapper,
+ parent: mapping,
order: order.value++,
kind: "video",
artifact: structuredClone(layer.source.artifact),
- sampling,
+ sourceTime,
muted: true,
style: mediaStyle,
}];
}
- return [wrapperElement, {
+ return [samplingElement, appearanceElement, mappingElement, {
id: layer.id,
- parent: wrapper,
+ parent: mapping,
order: order.value++,
kind: "surface",
surface: structuredClone(layer.source.surface),
- sampling,
+ sourceTime,
style: mediaStyle,
}];
}
function layerElements(
layer: MediaLayerProgram,
- item: MediaItemProgram,
+ clip: VisualClipProgram,
parent: string,
order: { value: number },
timeline: Timeline,
- samplingOverrides: Readonly<Record<string, VisualTimedSampling>>,
+ sourceTimeOverrides: Readonly<Record<string, VisualSourceTimeMap>>,
samplingAnimationOverrides: Readonly<Record<string, VisualAnimation | null>>,
): VisualElement[] {
if (layer.kind === "sample") {
- return sampleElements(layer, item, parent, order, timeline, samplingOverrides, samplingAnimationOverrides);
+ return sampleElements(layer, clip, parent, order, timeline, sourceTimeOverrides, samplingAnimationOverrides);
}
return [{
id: layer.id,
@@ -268,66 +294,52 @@ function layerElements(
}];
}
-/** Lower one independent Item through the fixed wrapper stack from the Media spec. */
-export function lowerMediaItemElements(
- item: MediaItemProgram,
+/** Lower one independent Clip through the fixed wrapper stack from the visual spec. */
+export function lowerVisualClipElements(
+ clip: VisualClipProgram,
timeline: Timeline,
options: {
- readonly includeHandoffWrapper?: boolean;
- readonly handoffAnimation?: VisualAnimation;
- readonly lifecycleAnimationOverride?: VisualAnimation | null;
- readonly sustainAnimationsOverride?: readonly (VisualAnimation | null)[];
+ readonly poseAnimationOverride?: VisualAnimation | null;
/** Implementation-level reuse hook for collection components with their own explicit clock. */
- readonly samplingOverrides?: Readonly<Record<string, VisualTimedSampling>>;
+ readonly sourceTimeOverrides?: Readonly<Record<string, VisualSourceTimeMap>>;
readonly samplingAnimationOverrides?: Readonly<Record<string, VisualAnimation | null>>;
- /** Attach the Media placement subtree below another component-owned wrapper. */
+ /** Attach the visual material subtree below another component-owned wrapper. */
readonly placementParent?: string;
} = {},
): readonly VisualElement[] {
- const durationFrames = item.span.endFrameExclusive - item.span.startFrame;
+ const durationFrames = clip.span.endFrameExclusive - clip.span.startFrame;
const order = { value: 0 };
- const root = `${item.id}:placement`;
+ const root = `${clip.id}:placement`;
const elements: VisualElement[] = [{
id: root,
...(options.placementParent === undefined ? {} : { parent: options.placementParent }),
order: order.value++,
kind: "box",
style: [
- { name: "height", value: px(item.frame.heightPx) },
- { name: "left", value: px(item.frame.xPx) },
+ { name: "height", value: px(clip.frame.heightPx) },
+ { name: "left", value: px(clip.frame.xPx) },
{ name: "position", value: "absolute" },
- { name: "top", value: px(item.frame.yPx) },
- { name: "width", value: px(item.frame.widthPx) },
+ { name: "top", value: px(clip.frame.yPx) },
+ { name: "width", value: px(clip.frame.widthPx) },
],
}];
- let parent = `${item.id}:lifecycle`;
- const lifecycle = options.lifecycleAnimationOverride === undefined
- ? lifecycleAnimation(item.motion, durationFrames)
- : options.lifecycleAnimationOverride ?? undefined;
- elements.push(box(parent, order.value++, root, lifecycle));
- for (const [index, sustain] of item.motion.sustain.entries()) {
- const id = `${item.id}:sustain:${index + 1}`;
- const animation = options.sustainAnimationsOverride === undefined
- ? sustainAnimation(sustain, durationFrames)
- : options.sustainAnimationsOverride[index] ?? undefined;
- elements.push(box(id, order.value++, parent, animation ?? undefined));
- parent = id;
- }
- if (options.includeHandoffWrapper === true) {
- const handoff = `${item.id}:handoff`;
- elements.push(box(handoff, order.value++, parent, options.handoffAnimation));
- parent = handoff;
- }
- const frame = `${item.id}:frame`;
- elements.push({ id: frame, parent, order: order.value++, kind: "box", style: frameStyles(item.presentation, item.frame) });
- for (const layer of item.layers) {
+ const parent = `${clip.id}:pose`;
+ const motion = options.poseAnimationOverride === undefined
+ ? poseAnimation(clip.motion, durationFrames)
+ : options.poseAnimationOverride ?? undefined;
+ const motionOrigin = clip.motion?.keyframes[0];
+ elements.push(box(parent, order.value++, root, motion,
+ motionOrigin === undefined ? "center center" : `${motionOrigin.originX * 100}% ${motionOrigin.originY * 100}%`));
+ const frame = `${clip.id}:frame`;
+ elements.push({ id: frame, parent, order: order.value++, kind: "box", style: frameStyles(clip.treatment, clip.frame) });
+ for (const layer of clip.layers) {
elements.push(...layerElements(
layer,
- item,
+ clip,
frame,
order,
timeline,
- options.samplingOverrides ?? {},
+ options.sourceTimeOverrides ?? {},
options.samplingAnimationOverrides ?? {},
));
}
diff --git a/packages/visual-track/src/manifest.ts b/packages/visual-track/src/manifest.ts
new file mode 100644
index 00000000..d6e0683c
--- /dev/null
+++ b/packages/visual-track/src/manifest.ts
@@ -0,0 +1,439 @@
+import { timelineDependency, timelineTypes } from "@hypit/timeline";
+import type { Timeline } from "@hypit/timeline";
+import { temporalContextAttributeVocabulary } from "@hypit/temporal-markup";
+import { visualSourceTimeMapSchema } from "@hypit/composition";
+import { readFile } from "node:fs/promises";
+
+import { artifactDependency, artifactTypes } from "@hypit/artifact";
+import { compositionDependency, compositionTypes } from "@hypit/composition";
+import {
+ compositableSurfaceSchema,
+ mediaDependency,
+ mediaTypes,
+} from "@hypit/media";
+
+import type { ModuleManifest, ProducerRef, TypeRef, ValueSchema } from "@hypit/protocol";
+import {
+ contentFitSchema,
+ intrinsicExtentSchema,
+ spatialDependency,
+ spatialFrameSchema,
+ spatialMap2DSchema,
+ spatialTypes,
+} from "@hypit/spatial";
+import { svsRecipeType } from "@hypit/svs";
+import { temporalDependency, temporalTypes } from "@hypit/temporal";
+import { temporalWindowAttributeVocabulary } from "@hypit/temporal-markup";
+
+const previewImage = (file: string) => ({
+ mediaType: "image/png",
+ path: `preview/${file}`,
+ open: async () => Uint8Array.from(await readFile(new URL(`../preview/${file}`, import.meta.url))),
+});
+
+export const visualTrackModuleRef = { name: "@hypit/visual-track", version: "1" } as const;
+export const visualTrackTypes = {
+ header: { module: visualTrackModuleRef, name: "VisualTrackHeader" },
+ motion: { module: visualTrackModuleRef, name: "VisualClipMotion" },
+ sourceTime: { module: visualTrackModuleRef, name: "VisualSourceTimeSpec" },
+ paintLayerSpec: { module: visualTrackModuleRef, name: "MediaPaintLayerSpec" },
+ sampleLayerSpec: { module: visualTrackModuleRef, name: "MediaSampleLayerSpec" },
+ layerSet: { module: visualTrackModuleRef, name: "MediaLayerSet" },
+ clipSpec: { module: visualTrackModuleRef, name: "VisualClipSpec" },
+ set: { module: visualTrackModuleRef, name: "VisualTrackSet" },
+ program: { module: visualTrackModuleRef, name: "VisualTrackProgram" },
+} satisfies Record<string, TypeRef>;
+
+export const visualTrackProducers = {
+ createLayers: { module: visualTrackModuleRef, name: "create-media-layer-set" },
+ appendPaintLayer: { module: visualTrackModuleRef, name: "append-media-paint-layer" },
+ appendStillLayer: { module: visualTrackModuleRef, name: "append-still-media-layer" },
+ appendMappedStillLayer: { module: visualTrackModuleRef, name: "append-mapped-still-media-layer" },
+ appendTimedLayer: { module: visualTrackModuleRef, name: "append-timed-media-layer" },
+ appendMappedTimedLayer: { module: visualTrackModuleRef, name: "append-mapped-timed-media-layer" },
+ appendSurfaceLayer: { module: visualTrackModuleRef, name: "append-surface-media-layer" },
+ appendMappedSurfaceLayer: { module: visualTrackModuleRef, name: "append-mapped-surface-media-layer" },
+ createSet: { module: visualTrackModuleRef, name: "create-visual-track-set" },
+ appendClip: { module: visualTrackModuleRef, name: "append-visual-clip" },
+ bindClipPath: { module: visualTrackModuleRef, name: "bind-visual-clip-path" },
+ bindMotion: { module: visualTrackModuleRef, name: "bind-visual-clip-motion" },
+ finalize: { module: visualTrackModuleRef, name: "finalize-visual-track" },
+ projectVisual: { module: visualTrackModuleRef, name: "project-visual-track" },
+} satisfies Record<string, ProducerRef>;
+
+const string = { kind: "string", minLength: 1 } as const;
+const number = { kind: "number" } as const;
+const unsigned = { kind: "number", minimum: 0 } as const;
+const integer = { kind: "number", integer: true } as const;
+const unsignedInteger = { kind: "number", integer: true, minimum: 0 } as const;
+const positiveInteger = { kind: "number", integer: true, minimum: 1 } as const;
+const object = (fields: Readonly<Record<string, { readonly schema: ValueSchema; readonly optional?: boolean }>>): ValueSchema => ({ kind: "object", fields });
+const blob = object({
+ kind: { schema: { kind: "literal", value: "blob" } },
+ resource: { schema: { kind: "string", minLength: 5, maxLength: 256 } },
+ size: { schema: unsignedInteger },
+ mediaType: { schema: string },
+});
+const rational = object({ numerator: { schema: positiveInteger }, denominator: { schema: positiveInteger } });
+const extent = intrinsicExtentSchema;
+const signedRational = object({ numerator: { schema: integer }, denominator: { schema: positiveInteger } });
+const sourceTimePoint = object({
+ edge: { schema: { kind: "string", enum: ["start", "end"] } },
+ offsetFrames: { schema: integer },
+});
+const sourceTimeBounds = object({ from: { schema: sourceTimePoint }, until: { schema: sourceTimePoint } });
+const sourceTimeRelation: ValueSchema = { kind: "oneOf", variants: [
+ object({
+ kind: { schema: { kind: "literal", value: "rate" } }, target: { schema: sourceTimeBounds },
+ targetAt: { schema: sourceTimePoint }, sourceAt: { schema: sourceTimePoint },
+ rate: { schema: signedRational }, source: { schema: sourceTimeBounds },
+ wrap: { schema: sourceTimeBounds, optional: true },
+ }),
+ object({
+ kind: { schema: { kind: "literal", value: "fit" } }, target: { schema: sourceTimeBounds },
+ source: { schema: sourceTimeBounds },
+ }),
+] };
+export const visualSourceTimeSpecSchema: ValueSchema = object({
+ relations: { schema: { kind: "array", minItems: 1, items: sourceTimeRelation } },
+});
+const stops = { kind: "array", minItems: 2, items: object({ offset: { schema: unsigned }, color: { schema: string } }) } as const;
+const paint: ValueSchema = { kind: "oneOf", variants: [
+ object({ kind: { schema: { kind: "literal", value: "solid" } }, color: { schema: string } }),
+ object({ kind: { schema: { kind: "literal", value: "linear-gradient" } }, angleDeg: { schema: number }, stops: { schema: stops } }),
+ object({ kind: { schema: { kind: "literal", value: "radial-gradient" } }, center: { schema: object({ x: { schema: unsigned }, y: { schema: unsigned } }) }, stops: { schema: stops } }),
+] };
+export const mediaSampleAppearanceSchema: ValueSchema = object({
+ opacity: { schema: unsigned },
+ filter: { schema: object({
+ blurPx: { schema: unsigned }, brightness: { schema: unsigned }, contrast: { schema: unsigned }, saturation: { schema: unsigned },
+ }) },
+});
+const samplingKeyframe = object({
+ atProgress: { schema: { kind: "number", minimum: 0, maximum: 1 } }, zoom: { schema: { kind: "number", minimum: 0.000001 } },
+ offsetX: { schema: number }, offsetY: { schema: number }, rotationDeg: { schema: number },
+ easing: { schema: { kind: "string", enum: ["linear", "ease-in", "ease-out", "ease-in-out"] }, optional: true },
+});
+export const mediaSamplingMotionSchema: ValueSchema = object({
+ keyframes: { schema: { kind: "array", minItems: 2, items: samplingKeyframe } },
+});
+export const mediaPaintLayerSpecSchema: ValueSchema = object({
+
+ id: { schema: string }, paint: { schema: paint }, opacity: { schema: unsigned },
+});
+export const mediaSampleLayerSpecSchema: ValueSchema = object({
+
+ id: { schema: string }, sourceTime: { schema: visualSourceTimeSpecSchema, optional: true },
+ appearance: { schema: mediaSampleAppearanceSchema }, samplingMotion: { schema: mediaSamplingMotionSchema, optional: true },
+});
+const visualSource: ValueSchema = { kind: "oneOf", variants: [
+ object({ kind: { schema: { kind: "literal", value: "still" } }, artifact: { schema: blob }, extent: { schema: extent } }),
+ object({
+ kind: { schema: { kind: "literal", value: "timed" } }, artifact: { schema: blob }, extent: { schema: extent },
+ frameRate: { schema: rational }, frameCount: { schema: positiveInteger },
+ }),
+ object({ kind: { schema: { kind: "literal", value: "surface" } }, surface: { schema: compositableSurfaceSchema }, extent: { schema: extent } }),
+] };
+const paintLayer = object({ id: { schema: string }, kind: { schema: { kind: "literal", value: "paint" } }, paint: { schema: paint }, opacity: { schema: unsigned } });
+const sampleLayer = object({
+ id: { schema: string }, kind: { schema: { kind: "literal", value: "sample" } }, source: { schema: visualSource },
+ sourceTime: { schema: { kind: "oneOf", variants: [
+ object({ kind: { schema: { kind: "literal", value: "spec" } }, value: { schema: visualSourceTimeSpecSchema } }),
+ object({ kind: { schema: { kind: "literal", value: "map" } }, value: { schema: visualSourceTimeMapSchema } }),
+ ] }, optional: true },
+ placement: { schema: { kind: "oneOf", variants: [
+ object({ kind: { schema: { kind: "literal", value: "fit" } }, fit: { schema: contentFitSchema } }),
+ object({ kind: { schema: { kind: "literal", value: "mapping" } }, mapping: { schema: spatialMap2DSchema } }),
+ ] } },
+ appearance: { schema: mediaSampleAppearanceSchema }, samplingMotion: { schema: mediaSamplingMotionSchema, optional: true },
+});
+const layer = { kind: "oneOf", variants: [paintLayer, sampleLayer] } as const;
+export const mediaLayerSetSchema: ValueSchema = object({
+
+ layers: { schema: { kind: "array", items: layer } },
+});
+const resolvedSampleLayer = object({
+ id: { schema: string }, kind: { schema: { kind: "literal", value: "sample" } }, source: { schema: visualSource },
+ sourceTime: { schema: { kind: "oneOf", variants: [
+ object({ kind: { schema: { kind: "literal", value: "spec" } }, value: { schema: visualSourceTimeSpecSchema } }),
+ object({ kind: { schema: { kind: "literal", value: "map" } }, value: { schema: visualSourceTimeMapSchema } }),
+ ] }, optional: true },
+ mapping: { schema: spatialMap2DSchema },
+ appearance: { schema: mediaSampleAppearanceSchema }, samplingMotion: { schema: mediaSamplingMotionSchema, optional: true },
+});
+const resolvedLayer = { kind: "oneOf", variants: [paintLayer, resolvedSampleLayer] } as const;
+
+const path = { kind: "object", fields: {}, allowUnknown: true } as const;
+const clip: ValueSchema = { kind: "oneOf", variants: [
+ object({ kind: { schema: { kind: "literal", value: "none" } } }),
+ object({ kind: { schema: { kind: "literal", value: "frame" } } }),
+ object({ kind: { schema: { kind: "literal", value: "rounded" } }, radiusPx: { schema: unsigned } }),
+ object({ kind: { schema: { kind: "literal", value: "path" } }, path: { schema: path } }),
+] };
+const padding = object({ topPx: { schema: unsigned }, rightPx: { schema: unsigned }, bottomPx: { schema: unsigned }, leftPx: { schema: unsigned } });
+export const visualFrameTreatmentSchema: ValueSchema = object({
+ clip: { schema: clip }, padding: { schema: padding },
+ border: { schema: object({ widthPx: { schema: unsigned }, style: { schema: { kind: "string", enum: ["solid", "dashed", "dotted"] } }, color: { schema: string } }), optional: true },
+ shadows: { schema: { kind: "array", items: object({ offsetX: { schema: number }, offsetY: { schema: number }, blurPx: { schema: unsigned }, spreadPx: { schema: number }, color: { schema: string } }) } },
+});
+const motionPosition: ValueSchema = { kind: "oneOf", variants: [
+ object({ kind: { schema: { kind: "literal", value: "progress" } }, value: { schema: { kind: "number", minimum: 0, maximum: 1 } } }),
+ object({ kind: { schema: { kind: "literal", value: "start" } }, offsetFrames: { schema: unsignedInteger } }),
+ object({ kind: { schema: { kind: "literal", value: "end" } }, offsetFrames: { schema: { kind: "number", integer: true, maximum: 0 } } }),
+] };
+const poseKeyframe = object({
+ at: { schema: motionPosition }, translateX: { schema: number }, translateY: { schema: number },
+ scaleX: { schema: { kind: "number", minimum: 0.000001 } }, scaleY: { schema: { kind: "number", minimum: 0.000001 } },
+ rotationDeg: { schema: number }, opacity: { schema: { kind: "number", minimum: 0, maximum: 1 } },
+ originX: { schema: { kind: "number", minimum: 0, maximum: 1 } }, originY: { schema: { kind: "number", minimum: 0, maximum: 1 } },
+ easing: { schema: { kind: "string", enum: ["linear", "ease-in", "ease-out", "ease-in-out"] }, optional: true },
+});
+export const visualClipMotionSchema: ValueSchema = object({
+ keyframes: { schema: { kind: "array", minItems: 2, items: poseKeyframe } },
+});
+export const visualClipSpecSchema: ValueSchema = object({
+ id: { schema: string },
+ treatment: { schema: visualFrameTreatmentSchema }, motion: { schema: visualClipMotionSchema, optional: true }, z: { schema: integer },
+});
+const frameSpan = object({ startFrame: { schema: unsignedInteger }, endFrameExclusive: { schema: positiveInteger } });
+const resolvedClip = object({
+ id: { schema: string }, subjectId: { schema: string }, span: { schema: frameSpan }, frame: { schema: spatialFrameSchema },
+ treatment: { schema: visualFrameTreatmentSchema }, layers: { schema: { kind: "array", minItems: 1, items: resolvedLayer } }, motion: { schema: visualClipMotionSchema, optional: true },
+ order: { schema: unsignedInteger }, z: { schema: integer },
+});
+export const visualTrackSetSchema: ValueSchema = object({
+ clips: { schema: { kind: "array", items: resolvedClip } },
+});
+export const visualTrackProgramSchema: ValueSchema = object({
+ id: { schema: string },
+ clips: { schema: { kind: "array", items: resolvedClip } },
+});
+export const visualTrackHeaderSchema: ValueSchema = object({
+ id: { schema: string },
+});
+
+const clipInputs = [
+ { name: "set", type: visualTrackTypes.set }, { name: "header", type: visualTrackTypes.header },
+ { name: "timeline", type: timelineTypes.track },
+ { name: "layers", type: visualTrackTypes.layerSet },
+ { name: "frame", type: spatialTypes.frame }, { name: "spec", type: visualTrackTypes.clipSpec },
+ { name: "window", type: temporalTypes.window },
+] as const;
+
+const treatmentRecipeProperties = [
+ { name: "opacity", required: false, fallback: "1",
+ summary: "Sets how opaque the sampled picture is drawn." },
+ { name: "blur", required: false, fallback: "0",
+ summary: "Blurs the sampled picture by a pixel radius." },
+ { name: "brightness", required: false, fallback: "1",
+ summary: "Scales the brightness of the sampled picture." },
+ { name: "contrast", required: false, fallback: "1",
+ summary: "Scales the contrast of the sampled picture." },
+ { name: "saturation", required: false, fallback: "1",
+ summary: "Scales the saturation of the sampled picture." },
+ { name: "clip", required: false, values: ["none", "frame", "rounded"], fallback: "frame",
+ summary: "Decides how the picture is clipped to the Frame." },
+ { name: "radius", required: false, fallback: "0",
+ summary: "Rounds the clipped corners by a pixel radius, and is read only for a `rounded` clip." },
+ { name: "padding", required: false, fallback: "0",
+ summary: "Insets the picture from the Frame edges. It admits one, two or four values — all sides, then vertical and horizontal, then each side — which no single number can carry, so it is written as text: `padding: \"14\"` and `padding: \"8 12\"`. A bare number is refused." },
+ { name: "border-width", required: false, fallback: "0",
+ summary: "Draws a border of this pixel width, and draws none at `0`." },
+ { name: "border-style", required: false, values: ["solid", "dashed", "dotted"], fallback: "solid",
+ summary: "Chooses how the border is stroked." },
+ { name: "border-color", required: false,
+ summary: "Paints the border, which a non-zero `border-width` requires." },
+ { name: "shadows", required: false, fallback: "none",
+ summary: "Casts shadows behind the Frame, written as `x y blur spread color` entries separated by semicolons." },
+ { name: "frame-paint", required: false, fallback: "transparent",
+ summary: "Fills the whole Frame behind every layer with a color, `linear(angle;stops)` or `radial(x,y;stops)`." },
+] as const;
+
+export const visualTrackMarkupSurfaces = [{
+ name: "track", tag: "Track", mode: "structured",
+ outputs: [spatialTypes.fit, visualTrackTypes.header, visualTrackTypes.paintLayerSpec, visualTrackTypes.sampleLayerSpec,
+ visualTrackTypes.layerSet, visualTrackTypes.clipSpec, visualTrackTypes.set,
+ temporalTypes.duration, temporalTypes.extent, temporalTypes.shiftSpec, temporalTypes.instantSpec,
+ temporalTypes.windowSpec, temporalTypes.instant, temporalTypes.window, visualTrackTypes.program,
+ compositionTypes.visualTrack],
+ vocabulary: {
+ summary: "Places ordinary visual Clips on one completed Timeline and composes them by explicit stack order.",
+ appearance: "Each Clip owns one source, one absolute Window and one Frame. Source-time, space, paint order, treatment and optional local motion remain independent choices.",
+ preview: previewImage("Track.png"),
+ attributes: [
+ { name: "id", kind: "identifier", required: true,
+ summary: "Names this Track and prefixes the identity of every Clip and layer that does not name itself." },
+ ...temporalContextAttributeVocabulary,
+ ],
+ children: [
+ { tag: "Clip", cardinality: "many",
+ summary: "One independently timed source on its own Frame, optionally carrying Sampling and Pose keyframes.",
+ attributes: [
+ { name: "id", kind: "identifier", required: false,
+ summary: "Names this Clip; the Track derives `<track>.clip.<index>` when it is absent." },
+ { name: "frame", kind: "reference", required: true, accepts: [spatialTypes.frame],
+ summary: "Chooses the Frame the Clip occupies in the program picture plane." },
+ { name: "z", kind: "literal", required: true,
+ summary: "Sets this occurrence's absolute picture stacking order." },
+ { name: "treatment", kind: "reference", required: false, accepts: [svsRecipeType],
+ summary: "Optionally chooses reusable image and Frame treatment; timing, fitting and stacking do not belong to it.",
+ recipe: treatmentRecipeProperties },
+ { name: "motion", kind: "reference", required: false, accepts: [visualTrackTypes.motion],
+ summary: "Optionally applies a reusable typed Motion. Inline Pose children express the same value." },
+ { name: "clip", kind: "reference", required: false, accepts: [spatialTypes.path],
+ summary: "Clips the Clip to an authored Path." },
+ { name: "image", kind: "reference", required: false, accepts: [artifactTypes.blob],
+ summary: "Shows a durationless still image as the Clip's direct source." },
+ { name: "media", kind: "reference", required: false, accepts: [mediaTypes.synchronized],
+ summary: "Shows an explicitly prepared timed source." },
+ { name: "surface", kind: "reference", required: false, accepts: [mediaTypes.compositableSurface],
+ summary: "Shows an alpha-aware still or timed Surface." },
+ { name: "source-time", kind: "reference", required: false, accepts: [visualTrackTypes.sourceTime],
+ summary: "Applies one reusable partial source-time relation. Inline Map children express the same value." },
+ { name: "extent", kind: "reference", required: false, accepts: [spatialTypes.extent],
+ summary: "Gives the still image its authored pixel Extent. The `fit` scales this Extent into the Frame, so what it decides is the shape: its width-to-height ratio has to be the picture's, and the pixel numbers themselves only have to hold that ratio. A generated picture's own size is the generator's to choose and is not knowable when the Source is written, so write the ratio you asked that generator for." },
+ { name: "mapping", kind: "reference", required: false, accepts: [spatialTypes.map2D],
+ summary: "Uses one explicit affine map from source-local pixels into the program picture plane instead of deriving one from fit attributes." },
+ { name: "fit", kind: "literal", required: false,
+ values: ["contain", "cover", "fit-width", "fit-height", "native", "scale-down", "stretch"],
+ summary: "Chooses contain, cover, fit-width, fit-height, native, scale-down or stretch; defaults to contain." },
+ { name: "frame-x", kind: "literal", required: false, summary: "Sets normalized horizontal destination alignment." },
+ { name: "frame-y", kind: "literal", required: false, summary: "Sets normalized vertical destination alignment." },
+ { name: "content-x", kind: "literal", required: false, summary: "Sets normalized horizontal source anchor." },
+ { name: "content-y", kind: "literal", required: false, summary: "Sets normalized vertical source anchor." },
+ { name: "fit-offset-x", kind: "literal", required: false, summary: "Offsets fitted content horizontally in pixels." },
+ { name: "fit-offset-y", kind: "literal", required: false, summary: "Offsets fitted content vertically in pixels." },
+ { name: "fit-constraint", kind: "literal", required: false, values: ["bounded", "free"], summary: "Chooses bounded or free alignment." },
+ ...temporalWindowAttributeVocabulary,
+ ] },
+ ],
+ ports: [
+ { name: "program", type: visualTrackTypes.program,
+ summary: "The resolved authored Clips retained for declared consumers such as Studio." },
+ { name: "visual", type: compositionTypes.visualTrack,
+ summary: "The rendered picture, an ordinary peer VisualTrack." },
+ ],
+ example: `<visual:Motion id="gentle-push">
+ <visual:Pose at="start" scale="1.08" easing="ease-out"/>
+ <visual:Pose at="end" scale="1"/>
+</visual:Motion>
+
+<visual:Track id="cutaways" timeline={speech.timeline}>
+ <visual:Clip media={prepared.media} during="timeline" frame={full} z="10" fit="cover"/>
+ <visual:Clip id="bags" media={cutaway-bags.media} during={story-time.bags}
+ frame={full} z="20" fit="cover" treatment={recipes.visual.cutaway} motion={gentle-push}/>
+</visual:Track>`,
+ notes: [
+ "A Track requires at least one Clip and accepts no text content.",
+ "A Clip uses an existing Window with `during`, or supplies exactly two of `from`, `until` and `for`.",
+ "An absolute point is a resolved Instant, `start`, `end`, or a bare duration read from Timeline start.",
+ "A Clip names exactly one of `image`, `media` or `surface`; `extent` is required with `image` and refused otherwise.",
+ "`z`, fitting and source time belong to the occurrence and cannot hide inside a treatment Recipe.",
+ "An explicit `mapping` is mutually exclusive with every fit attribute. It is already in program-picture coordinates; the Frame still owns clipping and treatment.",
+ "Omitting source time means bounded partial identity. Map children are refused on durationless still material.",
+ "Map children control timed source coordinates, Sampling children animate source crop inside the Frame, and Pose children animate the complete framed Clip.",
+ "Audio is authored independently through Audio Track; Visual Track never selects or emits it implicitly.",
+ ],
+ },
+ }, {
+ name: "motion", tag: "Motion", mode: "structured",
+ outputs: [visualTrackTypes.motion],
+ vocabulary: {
+ summary: "Authors one reusable Clip-local affine and opacity Motion without naming an aesthetic effect.",
+ attributes: [{ name: "id", kind: "identifier", required: true, summary: "Names this Motion value." }],
+ children: [{
+ tag: "Pose", cardinality: "many", summary: "One complete visual state on the consuming Clip's local clock.",
+ attributes: [
+ { name: "at", kind: "literal", required: true, summary: "Places this state at start, end, Nf, end-Nf or a percentage." },
+ { name: "x", kind: "literal", required: false, summary: "Translates horizontally in picture pixels." },
+ { name: "y", kind: "literal", required: false, summary: "Translates vertically in picture pixels." },
+ { name: "scale", kind: "literal", required: false, summary: "Scales both axes." },
+ { name: "scale-x", kind: "literal", required: false, summary: "Scales the horizontal axis." },
+ { name: "scale-y", kind: "literal", required: false, summary: "Scales the vertical axis." },
+ { name: "rotate", kind: "literal", required: false, summary: "Rotates in degrees." },
+ { name: "opacity", kind: "literal", required: false, summary: "Sets opacity inside [0,1]." },
+ { name: "origin-x", kind: "literal", required: false, summary: "Sets normalized horizontal transform origin." },
+ { name: "origin-y", kind: "literal", required: false, summary: "Sets normalized vertical transform origin." },
+ { name: "easing", kind: "literal", required: false, summary: "Shapes the interval leaving this Pose." },
+ ],
+ }],
+ example: `<visual:Motion id="gentle-push">
+ <visual:Pose at="start" scale="1.08" easing="ease-out"/>
+ <visual:Pose at="end" scale="1"/>
+</visual:Motion>`,
+ notes: ["A Motion needs at least two ordered Poses and must resolve from the consuming Clip's start through its end."],
+ },
+ }, {
+ name: "source-time", tag: "SourceTime", mode: "structured",
+ outputs: [visualTrackTypes.sourceTime],
+ vocabulary: {
+ summary: "Authors a reusable partial relation from Clip-local target frames to source-local frames.",
+ attributes: [{ name: "id", kind: "identifier", required: true, summary: "Names this SourceTime relation." }],
+ children: [{
+ tag: "Map", cardinality: "many", summary: "One affine piece; uncovered target frames are transparent.",
+ attributes: [
+ { name: "target-from", kind: "literal", required: false, summary: "Starts the target interval; defaults to start." },
+ { name: "target-until", kind: "literal", required: false, summary: "Ends the target interval exclusively; defaults to end." },
+ { name: "target-at", kind: "literal", required: false, summary: "Names the target anchor paired with source-at." },
+ { name: "source-at", kind: "literal", required: false, summary: "Names the source anchor paired with target-at." },
+ { name: "rate", kind: "literal", required: false, summary: "Exact signed source frames per target frame." },
+ { name: "source-from", kind: "literal", required: false, summary: "Starts the permitted or fitted source interval." },
+ { name: "source-until", kind: "literal", required: false, summary: "Ends the permitted or fitted source interval exclusively." },
+ { name: "wrap-from", kind: "literal", required: false, summary: "Starts an explicitly periodic source interval." },
+ { name: "wrap-until", kind: "literal", required: false, summary: "Ends an explicitly periodic source interval exclusively." },
+ ],
+ }],
+ example: `<visual:SourceTime id="native-loop">
+ <visual:Map source-at="start" rate="1" wrap-from="start" wrap-until="end"/>
+</visual:SourceTime>`,
+ notes: [
+ "Without rate, anchors or wrap, a Map fits source-from..source-until across its target interval.",
+ "With rate or anchors, missing points default to start and missing bounds default to the complete domain.",
+ ],
+ },
+ }] as const;
+
+
+export const visualTrackManifest: ModuleManifest = {
+ format: "hypit.module@1",
+ name: visualTrackModuleRef.name,
+ version: visualTrackModuleRef.version,
+ dependencies: [
+ artifactDependency,
+ mediaDependency,
+ timelineDependency,
+ temporalDependency,
+ spatialDependency,
+ compositionDependency,
+ ],
+ types: [
+ { name: visualTrackTypes.header.name },
+ { name: visualTrackTypes.motion.name },
+ { name: visualTrackTypes.sourceTime.name },
+ { name: visualTrackTypes.paintLayerSpec.name },
+ { name: visualTrackTypes.sampleLayerSpec.name },
+ { name: visualTrackTypes.layerSet.name },
+ { name: visualTrackTypes.clipSpec.name },
+ { name: visualTrackTypes.set.name },
+ { name: visualTrackTypes.program.name },
+ ],
+ capabilities: [],
+ producers: [
+ { name: visualTrackProducers.createLayers.name, inputs: [], outputs: [{ name: "layers", type: visualTrackTypes.layerSet }], needs: [] },
+ { name: visualTrackProducers.appendPaintLayer.name, inputs: [{ name: "layers", type: visualTrackTypes.layerSet }, { name: "spec", type: visualTrackTypes.paintLayerSpec }], outputs: [{ name: "layers", type: visualTrackTypes.layerSet }], needs: [] },
+ { name: visualTrackProducers.appendStillLayer.name, inputs: [{ name: "layers", type: visualTrackTypes.layerSet }, { name: "source", type: artifactTypes.blob }, { name: "extent", type: spatialTypes.extent }, { name: "fit", type: spatialTypes.fit }, { name: "spec", type: visualTrackTypes.sampleLayerSpec }], outputs: [{ name: "layers", type: visualTrackTypes.layerSet }], needs: [] },
+ { name: visualTrackProducers.appendMappedStillLayer.name, inputs: [{ name: "layers", type: visualTrackTypes.layerSet }, { name: "source", type: artifactTypes.blob }, { name: "extent", type: spatialTypes.extent }, { name: "mapping", type: spatialTypes.map2D }, { name: "spec", type: visualTrackTypes.sampleLayerSpec }], outputs: [{ name: "layers", type: visualTrackTypes.layerSet }], needs: [] },
+ { name: visualTrackProducers.appendTimedLayer.name, inputs: [{ name: "layers", type: visualTrackTypes.layerSet }, { name: "source", type: mediaTypes.synchronized }, { name: "fit", type: spatialTypes.fit }, { name: "spec", type: visualTrackTypes.sampleLayerSpec }], outputs: [{ name: "layers", type: visualTrackTypes.layerSet }], needs: [] },
+ { name: visualTrackProducers.appendMappedTimedLayer.name, inputs: [{ name: "layers", type: visualTrackTypes.layerSet }, { name: "source", type: mediaTypes.synchronized }, { name: "mapping", type: spatialTypes.map2D }, { name: "spec", type: visualTrackTypes.sampleLayerSpec }], outputs: [{ name: "layers", type: visualTrackTypes.layerSet }], needs: [] },
+ { name: visualTrackProducers.appendSurfaceLayer.name, inputs: [{ name: "layers", type: visualTrackTypes.layerSet }, { name: "source", type: mediaTypes.compositableSurface }, { name: "fit", type: spatialTypes.fit }, { name: "spec", type: visualTrackTypes.sampleLayerSpec }], outputs: [{ name: "layers", type: visualTrackTypes.layerSet }], needs: [] },
+ { name: visualTrackProducers.appendMappedSurfaceLayer.name, inputs: [{ name: "layers", type: visualTrackTypes.layerSet }, { name: "source", type: mediaTypes.compositableSurface }, { name: "mapping", type: spatialTypes.map2D }, { name: "spec", type: visualTrackTypes.sampleLayerSpec }], outputs: [{ name: "layers", type: visualTrackTypes.layerSet }], needs: [] },
+ { name: visualTrackProducers.createSet.name, inputs: [], outputs: [{ name: "set", type: visualTrackTypes.set }], needs: [] },
+ { name: visualTrackProducers.appendClip.name, inputs: clipInputs, outputs: [{ name: "set", type: visualTrackTypes.set }], needs: [] },
+ { name: visualTrackProducers.bindClipPath.name, inputs: [{ name: "spec", type: visualTrackTypes.clipSpec }, { name: "path", type: spatialTypes.path }], outputs: [{ name: "spec", type: visualTrackTypes.clipSpec }], needs: [] },
+ { name: visualTrackProducers.bindMotion.name, inputs: [{ name: "spec", type: visualTrackTypes.clipSpec }, { name: "motion", type: visualTrackTypes.motion }], outputs: [{ name: "spec", type: visualTrackTypes.clipSpec }], needs: [] },
+ { name: visualTrackProducers.finalize.name, inputs: [{ name: "set", type: visualTrackTypes.set }, { name: "header", type: visualTrackTypes.header }, { name: "timeline", type: timelineTypes.track }], outputs: [{ name: "program", type: visualTrackTypes.program }], needs: [] },
+ { name: visualTrackProducers.projectVisual.name, inputs: [{ name: "timeline", type: timelineTypes.track }, { name: "program", type: visualTrackTypes.program }], outputs: [{ name: "track", type: compositionTypes.visualTrack }], needs: [] },
+ ],
+};
+
+export const visualTrackDependency = { module: visualTrackModuleRef } as const;
diff --git a/packages/visual-track/src/motion.ts b/packages/visual-track/src/motion.ts
new file mode 100644
index 00000000..9a0e8c83
--- /dev/null
+++ b/packages/visual-track/src/motion.ts
@@ -0,0 +1,145 @@
+import type {
+ VisualAnimation,
+ VisualStyleDeclaration,
+} from "@hypit/composition";
+import { canonicalize } from "@hypit/protocol";
+
+import type {
+ MediaSamplingMotion,
+ VisualClipMotion,
+ VisualMotionPosition,
+ VisualPoseKeyframe,
+} from "./types.js";
+
+function assert(condition: unknown, message: string): asserts condition {
+ if (!condition) throw new Error(message);
+}
+
+function finite(value: number, label: string): void {
+ assert(Number.isFinite(value), `${label} must be finite.`);
+}
+
+function unit(value: number, label: string): void {
+ finite(value, label);
+ assert(value >= 0 && value <= 1, `${label} must be inside [0, 1].`);
+}
+
+export function assertVisualMotionPosition(value: VisualMotionPosition, label: string): void {
+ if (value.kind === "progress") {
+ unit(value.value, `${label}.value`);
+ return;
+ }
+ assert(value.kind === "start" || value.kind === "end", `${label}.kind is invalid.`);
+ assert(Number.isSafeInteger(value.offsetFrames), `${label}.offsetFrames must be an integer.`);
+ assert(value.kind === "start" ? value.offsetFrames >= 0 : value.offsetFrames <= 0,
+ `${label} points away from its ${value.kind} boundary.`);
+}
+
+export function resolveVisualMotionPosition(value: VisualMotionPosition, durationFrames: number): number {
+ assertVisualMotionPosition(value, "Visual motion position");
+ assert(Number.isSafeInteger(durationFrames) && durationFrames > 0, "Visual motion duration is invalid.");
+ const frame = value.kind === "progress"
+ ? Math.round(value.value * durationFrames)
+ : value.kind === "start" ? value.offsetFrames : durationFrames + value.offsetFrames;
+ assert(frame >= 0 && frame <= durationFrames, "Visual motion position is outside its Clip Window.");
+ return frame;
+}
+
+function assertPose(value: VisualPoseKeyframe, label: string): void {
+ assertVisualMotionPosition(value.at, `${label}.at`);
+ finite(value.translateX, `${label}.translateX`);
+ finite(value.translateY, `${label}.translateY`);
+ finite(value.scaleX, `${label}.scaleX`);
+ finite(value.scaleY, `${label}.scaleY`);
+ assert(value.scaleX > 0 && value.scaleY > 0, `${label} scale must be positive.`);
+ finite(value.rotationDeg, `${label}.rotationDeg`);
+ unit(value.opacity, `${label}.opacity`);
+ unit(value.originX, `${label}.originX`);
+ unit(value.originY, `${label}.originY`);
+ if (value.easing !== undefined) {
+ assert(["linear", "ease-in", "ease-out", "ease-in-out"].includes(value.easing), `${label}.easing is invalid.`);
+ }
+}
+
+/** Validate a reusable Motion without assuming the duration of the Clip that will consume it. */
+export function assertVisualClipMotion(value: VisualClipMotion, label: string): void {
+ assert(Array.isArray(value.keyframes) && value.keyframes.length >= 2, `${label} needs at least two keyframes.`);
+ for (const [index, keyframe] of value.keyframes.entries()) assertPose(keyframe, `${label}.keyframes.${index}`);
+ const origin = value.keyframes[0]!;
+ assert(value.keyframes.every((keyframe) => keyframe.originX === origin.originX && keyframe.originY === origin.originY),
+ `${label} transform origin must remain constant; animate sampling or author a component when the pivot itself changes.`);
+}
+
+export function sealVisualClipMotion(value: VisualClipMotion): VisualClipMotion {
+ assertVisualClipMotion(value, "VisualClipMotion");
+ return canonicalize(value) as unknown as VisualClipMotion;
+}
+
+/** Resolve and validate one Motion against the local clock of a concrete Clip. */
+function resolvedKeyframes(value: VisualClipMotion, durationFrames: number): readonly {
+ readonly frame: number;
+ readonly pose: VisualPoseKeyframe;
+}[] {
+ assertVisualClipMotion(value, "Visual motion");
+ let previous = -1;
+ const resolved = value.keyframes.map((pose, index) => {
+ const frame = resolveVisualMotionPosition(pose.at, durationFrames);
+ assert(frame > previous,
+ `Visual motion keyframe ${index + 1} collapses or is out of order on this Clip clock.`);
+ previous = frame;
+ return { frame, pose };
+ });
+ assert(resolved[0]!.frame === 0 && resolved.at(-1)!.frame === durationFrames,
+ "Visual motion must cover the complete Clip-local clock from start through end.");
+ return resolved;
+}
+
+function clean(value: number): number {
+ const rounded = Math.round(value * 1_000_000) / 1_000_000;
+ return Object.is(rounded, -0) ? 0 : rounded;
+}
+
+function poseStyle(value: Omit<VisualPoseKeyframe, "at" | "easing">): readonly VisualStyleDeclaration[] {
+ const transform = value.translateX === 0 && value.translateY === 0
+ && value.rotationDeg === 0 && value.scaleX === 1 && value.scaleY === 1
+ ? "none"
+ : `translate(${clean(value.translateX)}px,${clean(value.translateY)}px) rotate(${clean(value.rotationDeg)}deg) scale(${clean(value.scaleX)},${clean(value.scaleY)})`;
+ return [
+ { name: "opacity", value: clean(value.opacity) },
+ { name: "transform", value: transform },
+ ];
+}
+
+export function poseAnimation(value: VisualClipMotion | undefined, durationFrames: number): VisualAnimation | undefined {
+ if (value === undefined) return undefined;
+ return {
+ keyframes: resolvedKeyframes(value, durationFrames).map(({ frame, pose }) => ({
+ atFrame: frame,
+ ...(pose.easing === undefined ? {} : { easing: pose.easing }),
+ style: poseStyle(pose),
+ })),
+ };
+}
+
+export function samplingAnimation(value: MediaSamplingMotion, durationFrames: number): VisualAnimation {
+ assert(value.keyframes.length >= 2, "Media sampling motion requires keyframes.");
+ assert(value.keyframes[0]?.atProgress === 0 && value.keyframes.at(-1)?.atProgress === 1,
+ "Media sampling motion must cover normalized progress [0, 1].");
+ let previous = -1;
+ return {
+ keyframes: value.keyframes.map((keyframe, index) => {
+ const atFrame = Math.round(keyframe.atProgress * durationFrames);
+ assert(atFrame > previous,
+ `Media sampling keyframe ${index + 1} collapses after frame quantization; use fewer or wider-spaced keyframes.`);
+ previous = atFrame;
+ return {
+ atFrame,
+ ...(keyframe.easing === undefined ? {} : { easing: keyframe.easing }),
+ style: [{
+ name: "transform",
+ value: `translate(${keyframe.offsetX}px,${keyframe.offsetY}px) rotate(${keyframe.rotationDeg}deg) scale(${keyframe.zoom})`,
+ }],
+ };
+ }),
+ };
+}
diff --git a/packages/visual-track/src/program.ts b/packages/visual-track/src/program.ts
new file mode 100644
index 00000000..485f0c54
--- /dev/null
+++ b/packages/visual-track/src/program.ts
@@ -0,0 +1,215 @@
+import { assertVisualTrackIdentity, sealVisualTrack } from "@hypit/composition";
+import type { VisualTrack } from "@hypit/composition";
+import { canonicalize } from "@hypit/protocol";
+import { assertSpatialFrame, assertSpatialPath } from "@hypit/spatial";
+import type { SpatialPath } from "@hypit/spatial";
+import { assertTemporalWindowFor } from "@hypit/temporal";
+import type { TemporalWindow } from "@hypit/temporal";
+import { assertTimelineIdentity, timelineFrameCount } from "@hypit/timeline";
+import type { Timeline } from "@hypit/timeline";
+
+import {
+ assertMediaIdentity,
+ assertMediaLayerSet,
+} from "./layers.js";
+import { lowerVisualClipElements } from "./lower.js";
+import { assertVisualClipMotion, poseAnimation } from "./motion.js";
+import { assertVisualFrameTreatment } from "./frame-treatment.js";
+import { assertMediaLayerPrograms, assertResolvedSampleLayer, resolveMediaLayerPrograms } from "./spatial.js";
+import type {
+ MediaLayerSet,
+ MediaSampleLayerProgram,
+ VisualClipProgram,
+ VisualClipMotion,
+ VisualClipSpec,
+ VisualTrackHeader,
+ VisualTrackProgram,
+ VisualTrackSet,
+} from "./types.js";
+
+function assert(condition: unknown, message: string): asserts condition {
+ if (!condition) throw new Error(message);
+}
+
+export function bindVisualClipPath(spec: VisualClipSpec, path: SpatialPath): VisualClipSpec {
+ assertVisualClipSpec(spec);
+ assertSpatialPath(path);
+ return sealVisualClipSpec({
+ ...spec,
+ treatment: { ...spec.treatment, clip: { kind: "path", path: structuredClone(path) } },
+ });
+}
+
+export function bindVisualClipMotion(spec: VisualClipSpec, motion: VisualClipMotion): VisualClipSpec {
+ assertVisualClipSpec(spec);
+ assertVisualClipMotion(motion, "VisualClipMotion");
+ return sealVisualClipSpec({ ...spec, motion: structuredClone(motion) });
+}
+
+export function assertVisualClipSpec(value: VisualClipSpec): void {
+ assertMediaIdentity(value.id, "VisualClipSpec.id");
+ assertVisualFrameTreatment(value.treatment, "VisualClipSpec.treatment");
+ if (value.motion !== undefined) assertVisualClipMotion(value.motion, "VisualClipSpec.motion");
+ assert(Number.isSafeInteger(value.z), "VisualClipSpec.z must be an integer.");
+}
+
+export function sealVisualClipSpec(value: VisualClipSpec): VisualClipSpec {
+ assertVisualClipSpec(value);
+ return canonicalize(value) as unknown as VisualClipSpec;
+}
+
+export function sealVisualTrackHeader(value: VisualTrackHeader): VisualTrackHeader {
+ assertVisualTrackHeader(value);
+ return canonicalize(value) as unknown as VisualTrackHeader;
+}
+
+export function assertVisualTrackHeader(value: VisualTrackHeader): void {
+ assertMediaIdentity(value.id, "VisualTrackHeader.id");
+}
+
+export function createVisualTrackSet(): VisualTrackSet {
+ return { clips: [] };
+}
+
+export function assertVisualTrackSet(value: VisualTrackSet): void {
+ assert(Array.isArray(value.clips), "VisualTrackSet is invalid.");
+}
+
+/** Component entry point: source facts, absolute placement and visual treatment are already explicit. */
+export function appendVisualClip(
+ set: VisualTrackSet,
+ header: VisualTrackHeader,
+ timeline: Timeline,
+ layers: MediaLayerSet,
+ frame: VisualClipProgram["frame"],
+ spec: VisualClipSpec,
+ window: TemporalWindow,
+): VisualTrackSet {
+ assertVisualTrackSet(set);
+ assertVisualTrackHeader(header);
+ assertTimelineIdentity(timeline);
+ assertMediaLayerSet(layers);
+ assert(layers.layers.length > 0, `Visual Clip ${spec.id} requires at least one layer.`);
+ assertSpatialFrame(frame);
+ assertVisualClipSpec(spec);
+ assertTemporalWindowFor(window, { subjectId: spec.id, timeline });
+ const resolvedLayers = resolveMediaLayerPrograms(layers, frame, spec.treatment);
+ const duration = window.span.endFrameExclusive - window.span.startFrame;
+ if (spec.motion !== undefined) {
+ assertVisualClipMotion(spec.motion, `Visual Clip ${spec.id} motion`);
+ poseAnimation(spec.motion, duration);
+ }
+ const addition: VisualClipProgram = {
+ id: window.id,
+ subjectId: spec.id,
+ span: { ...window.span },
+ frame: { ...frame },
+ treatment: structuredClone(spec.treatment),
+ layers: structuredClone(resolvedLayers),
+ ...(spec.motion === undefined ? {} : { motion: structuredClone(spec.motion) }),
+ order: set.clips.length,
+ z: spec.z,
+ };
+ assert(!set.clips.some((clip) => clip.id === addition.id), `Visual Track ${header.id} already contains ${addition.id}.`);
+ return { clips: [...set.clips, addition] };
+}
+
+function assertSampleLayerForTimeline(layer: MediaSampleLayerProgram, timeline: Timeline, label: string): void {
+ assertResolvedSampleLayer(layer, label);
+ const timing = layer.source.kind === "timed"
+ ? { frameRate: layer.source.frameRate, frameCount: layer.source.frameCount }
+ : layer.source.kind === "surface" && layer.source.surface.timing.kind === "frames"
+ ? layer.source.surface.timing
+ : undefined;
+ if (timing === undefined) {
+ assert(layer.sourceTime === undefined, `${label} is still material and cannot have source time.`);
+ return;
+ }
+ assert(
+ timing.frameRate.numerator === timeline.frameRate.numerator
+ && timing.frameRate.denominator === timeline.frameRate.denominator,
+ `${label} is not normalized to Timeline frame rate.`,
+ );
+ assert(layer.sourceTime !== undefined, `${label} requires source time.`);
+}
+
+function assertClip(clip: VisualClipProgram, timeline: Timeline, label: string): void {
+ assertMediaIdentity(clip.id, `${label}.id`);
+ assertMediaIdentity(clip.subjectId, `${label}.subjectId`);
+ assert(
+ Number.isSafeInteger(clip.span.startFrame)
+ && Number.isSafeInteger(clip.span.endFrameExclusive)
+ && clip.span.startFrame >= 0
+ && clip.span.endFrameExclusive > clip.span.startFrame
+ && clip.span.endFrameExclusive <= timelineFrameCount(timeline),
+ `${label}.span is invalid.`,
+ );
+ assertSpatialFrame(clip.frame);
+ assertVisualFrameTreatment(clip.treatment, `${label}.treatment`);
+ if (clip.motion !== undefined) {
+ assertVisualClipMotion(clip.motion, `${label}.motion`);
+ poseAnimation(clip.motion, clip.span.endFrameExclusive - clip.span.startFrame);
+ }
+ assert(Number.isSafeInteger(clip.order) && clip.order >= 0, `${label}.order is invalid.`);
+ assert(Number.isSafeInteger(clip.z), `${label}.z is invalid.`);
+ assert(clip.layers.length > 0, `${label} requires layers.`);
+ assertMediaLayerPrograms(clip.layers);
+ for (const layer of clip.layers) {
+ if (layer.kind === "sample") assertSampleLayerForTimeline(layer, timeline, `${label}.${layer.id}`);
+ }
+}
+
+function normalizeProgram(value: VisualTrackProgram): VisualTrackProgram {
+ return {
+ id: value.id,
+ clips: [...value.clips].map((clip) => structuredClone(clip)).sort((left, right) => left.id.localeCompare(right.id)),
+ };
+}
+
+export function sealVisualTrackProgram(value: VisualTrackProgram, timeline: Timeline): VisualTrackProgram {
+ const normalized = normalizeProgram(value);
+ assertVisualTrackProgramIdentity(normalized, timeline);
+ return canonicalize(normalized) as unknown as VisualTrackProgram;
+}
+
+export function finalizeVisualTrack(set: VisualTrackSet, header: VisualTrackHeader, timeline: Timeline): VisualTrackProgram {
+ assertVisualTrackSet(set);
+ assertVisualTrackHeader(header);
+ assert(set.clips.length > 0, "Visual Track requires at least one Clip.");
+ return sealVisualTrackProgram({ id: header.id, clips: set.clips }, timeline);
+}
+
+export function assertVisualTrackProgram(value: VisualTrackProgram): void {
+ assertMediaIdentity(value.id, "VisualTrackProgram.id");
+ assert(Array.isArray(value.clips) && value.clips.length > 0, "VisualTrackProgram is empty.");
+}
+
+export function assertVisualTrackProgramIdentity(value: VisualTrackProgram, timeline: Timeline): void {
+ assertVisualTrackProgram(value);
+ assertTimelineIdentity(timeline);
+ const ids = new Set<string>();
+ for (const clip of value.clips) {
+ assert(!ids.has(clip.id), `VisualTrackProgram repeats ${clip.id}.`);
+ ids.add(clip.id);
+ assertClip(clip, timeline, `Visual Clip ${clip.id}`);
+ }
+}
+
+export function projectVisualTrack(timeline: Timeline, program: VisualTrackProgram): VisualTrack {
+ assertVisualTrackProgramIdentity(program, timeline);
+ const track = sealVisualTrack({
+ timelineId: timeline.id,
+ visualIr: "hypit.visual-ir@1",
+ id: program.id,
+ presents: program.clips.map((clip) => ({
+ id: clip.id,
+ order: clip.order,
+ z: clip.z,
+ subjectId: clip.subjectId,
+ span: { ...clip.span },
+ elements: lowerVisualClipElements(clip, timeline),
+ })),
+ });
+ assertVisualTrackIdentity(track, timeline);
+ return track;
+}
diff --git a/packages/visual-track/src/source-time.ts b/packages/visual-track/src/source-time.ts
new file mode 100644
index 00000000..fe23b377
--- /dev/null
+++ b/packages/visual-track/src/source-time.ts
@@ -0,0 +1,241 @@
+import type {
+ VisualSourceTimeMap,
+ VisualSourceTimePiece,
+ VisualSourceTimeRational,
+} from "@hypit/composition";
+import { assertTimelineIdentity } from "@hypit/timeline";
+import type { Timeline } from "@hypit/timeline";
+
+import type {
+ VisualSourceTimeBounds,
+ VisualSourceTimePoint,
+ VisualSourceTimeRelation,
+ VisualSourceTimeSpec,
+} from "./types.js";
+
+function assert(condition: unknown, message: string): asserts condition {
+ if (!condition) throw new Error(message);
+}
+
+function gcd(left: bigint, right: bigint): bigint {
+ let a = left < 0n ? -left : left;
+ let b = right < 0n ? -right : right;
+ while (b !== 0n) [a, b] = [b, a % b];
+ return a;
+}
+
+function rational(numerator: bigint, denominator = 1n): VisualSourceTimeRational {
+ assert(denominator > 0n, "Visual source-time rational has an invalid denominator.");
+ const divisor = gcd(numerator, denominator);
+ const reducedNumerator = numerator / divisor;
+ const reducedDenominator = denominator / divisor;
+ assert(reducedNumerator >= BigInt(Number.MIN_SAFE_INTEGER)
+ && reducedNumerator <= BigInt(Number.MAX_SAFE_INTEGER)
+ && reducedDenominator <= BigInt(Number.MAX_SAFE_INTEGER),
+ "Visual source-time rational exceeds safe wire arithmetic.");
+ return { numerator: Number(reducedNumerator), denominator: Number(reducedDenominator) };
+}
+
+const START: VisualSourceTimePoint = { edge: "start", offsetFrames: 0 };
+const END: VisualSourceTimePoint = { edge: "end", offsetFrames: 0 };
+const FULL: VisualSourceTimeBounds = { from: START, until: END };
+
+export function defaultVisualSourceTimeSpec(): VisualSourceTimeSpec {
+ return {
+ relations: [{
+ kind: "rate",
+ target: FULL,
+ targetAt: START,
+ sourceAt: START,
+ rate: { numerator: 1, denominator: 1 },
+ source: FULL,
+ }],
+ };
+}
+
+function assertPoint(value: VisualSourceTimePoint, label: string): void {
+ assert(value.edge === "start" || value.edge === "end", `${label}.edge is invalid.`);
+ assert(Number.isSafeInteger(value.offsetFrames), `${label}.offsetFrames is invalid.`);
+ assert(value.edge === "start" ? value.offsetFrames >= 0 : value.offsetFrames <= 0,
+ `${label} must point inward from its named edge.`);
+}
+
+function assertBounds(value: VisualSourceTimeBounds, label: string): void {
+ assertPoint(value.from, `${label}.from`);
+ assertPoint(value.until, `${label}.until`);
+}
+
+export function assertVisualSourceTimeSpec(value: VisualSourceTimeSpec, label = "VisualSourceTimeSpec"): void {
+ assert(Array.isArray(value.relations) && value.relations.length > 0, `${label} requires at least one relation.`);
+ for (const [index, relation] of value.relations.entries()) {
+ const item = `${label}.relations.${index}`;
+ assertBounds(relation.target, `${item}.target`);
+ assertBounds(relation.source, `${item}.source`);
+ if (relation.kind === "fit") continue;
+ assert(relation.kind === "rate", `${item}.kind is invalid.`);
+ assertPoint(relation.targetAt, `${item}.targetAt`);
+ assertPoint(relation.sourceAt, `${item}.sourceAt`);
+ assert(Number.isSafeInteger(relation.rate.numerator)
+ && Number.isSafeInteger(relation.rate.denominator) && relation.rate.denominator > 0,
+ `${item}.rate is invalid.`);
+ if (relation.wrap !== undefined) assertBounds(relation.wrap, `${item}.wrap`);
+ }
+}
+
+function point(value: VisualSourceTimePoint, length: number, label: string): number {
+ const result = (value.edge === "start" ? 0 : length) + value.offsetFrames;
+ assert(Number.isSafeInteger(result) && result >= 0 && result <= length, `${label} is outside its domain.`);
+ return result;
+}
+
+function bounds(value: VisualSourceTimeBounds, length: number, label: string): { startFrame: number; endFrameExclusive: number } {
+ const startFrame = point(value.from, length, `${label}.from`);
+ const endFrameExclusive = point(value.until, length, `${label}.until`);
+ assert(endFrameExclusive > startFrame, `${label} is empty or reversed.`);
+ return { startFrame, endFrameExclusive };
+}
+
+function sourceAt(
+ sourceAnchor: number,
+ targetAnchor: number,
+ rate: VisualSourceTimeRational,
+ target: number,
+): VisualSourceTimeRational {
+ return rational(
+ BigInt(sourceAnchor) * BigInt(rate.denominator)
+ + BigInt(target - targetAnchor) * BigInt(rate.numerator),
+ BigInt(rate.denominator),
+ );
+}
+
+function compareToInteger(value: VisualSourceTimeRational, integer: number): number {
+ const difference = BigInt(value.numerator) - BigInt(integer) * BigInt(value.denominator);
+ return difference < 0n ? -1 : difference > 0n ? 1 : 0;
+}
+
+function firstTrue(from: number, until: number, predicate: (value: number) => boolean): number {
+ let left = from;
+ let right = until;
+ while (left < right) {
+ const middle = left + Math.floor((right - left) / 2);
+ if (predicate(middle)) right = middle;
+ else left = middle + 1;
+ }
+ return left;
+}
+
+function validTargetInterval(
+ target: { startFrame: number; endFrameExclusive: number },
+ source: { startFrame: number; endFrameExclusive: number },
+ sourceAnchor: number,
+ targetAnchor: number,
+ rate: VisualSourceTimeRational,
+): { startFrame: number; endFrameExclusive: number } | undefined {
+ const at = (frame: number) => sourceAt(sourceAnchor, targetAnchor, rate, frame);
+ if (rate.numerator === 0) {
+ const sample = at(target.startFrame);
+ return compareToInteger(sample, source.startFrame) >= 0
+ && compareToInteger(sample, source.endFrameExclusive) < 0 ? target : undefined;
+ }
+ if (rate.numerator > 0) {
+ const startFrame = firstTrue(target.startFrame, target.endFrameExclusive,
+ (frame) => compareToInteger(at(frame), source.startFrame) >= 0);
+ const endFrameExclusive = firstTrue(startFrame, target.endFrameExclusive,
+ (frame) => compareToInteger(at(frame), source.endFrameExclusive) >= 0);
+ return endFrameExclusive > startFrame ? { startFrame, endFrameExclusive } : undefined;
+ }
+ const startFrame = firstTrue(target.startFrame, target.endFrameExclusive,
+ (frame) => compareToInteger(at(frame), source.endFrameExclusive) < 0);
+ const endFrameExclusive = firstTrue(startFrame, target.endFrameExclusive,
+ (frame) => compareToInteger(at(frame), source.startFrame) < 0);
+ return endFrameExclusive > startFrame ? { startFrame, endFrameExclusive } : undefined;
+}
+
+function modulo(value: bigint, modulus: bigint): bigint {
+ return ((value % modulus) + modulus) % modulus;
+}
+
+function wrapSource(value: VisualSourceTimeRational, wrap: { startFrame: number; endFrameExclusive: number }): VisualSourceTimeRational {
+ const start = BigInt(wrap.startFrame) * BigInt(value.denominator);
+ const length = BigInt(wrap.endFrameExclusive - wrap.startFrame) * BigInt(value.denominator);
+ return rational(start + modulo(BigInt(value.numerator) - start, length), BigInt(value.denominator));
+}
+
+function resolveRateRelation(
+ relation: Extract<VisualSourceTimeRelation, { readonly kind: "rate" }>,
+ targetLength: number,
+ sourceLength: number,
+ label: string,
+): VisualSourceTimePiece {
+ const authoredTarget = bounds(relation.target, targetLength, `${label}.target`);
+ const sourceBounds = bounds(relation.source, sourceLength, `${label}.source`);
+ const targetAnchor = point(relation.targetAt, targetLength, `${label}.targetAt`);
+ const sourceAnchor = point(relation.sourceAt, sourceLength, `${label}.sourceAt`);
+ const wrap = relation.wrap === undefined ? undefined : bounds(relation.wrap, sourceLength, `${label}.wrap`);
+ const target = wrap === undefined
+ ? validTargetInterval(authoredTarget, sourceBounds, sourceAnchor, targetAnchor, relation.rate)
+ : authoredTarget;
+ assert(target !== undefined, `${label} does not sample any source frame.`);
+ const rawStart = sourceAt(sourceAnchor, targetAnchor, relation.rate, target.startFrame);
+ return {
+ target,
+ sourceAtStart: wrap === undefined ? rawStart : wrapSource(rawStart, wrap),
+ rate: { ...relation.rate },
+ ...(wrap === undefined ? {} : { wrap }),
+ };
+}
+
+function resolveRelation(
+ relation: VisualSourceTimeRelation,
+ targetLength: number,
+ sourceLength: number,
+ label: string,
+): VisualSourceTimePiece {
+ if (relation.kind === "rate") return resolveRateRelation(relation, targetLength, sourceLength, label);
+ const target = bounds(relation.target, targetLength, `${label}.target`);
+ const source = bounds(relation.source, sourceLength, `${label}.source`);
+ return {
+ target,
+ sourceAtStart: { numerator: source.startFrame, denominator: 1 },
+ rate: rational(
+ BigInt(source.endFrameExclusive - source.startFrame),
+ BigInt(target.endFrameExclusive - target.startFrame),
+ ),
+ };
+}
+
+/** Resolve symbolic author relations into the exact stateless function consumed by renderers. */
+export function resolveVisualSourceTime(input: {
+ readonly timeline: Timeline;
+ readonly sourceFrameRate: { readonly numerator: number; readonly denominator: number };
+ readonly sourceFrameCount: number;
+ readonly targetFrameCount: number;
+ readonly spec?: VisualSourceTimeSpec;
+}): VisualSourceTimeMap {
+ assertTimelineIdentity(input.timeline);
+ assert(Number.isSafeInteger(input.sourceFrameCount) && input.sourceFrameCount > 0,
+ "Timed visual source frame count is invalid.");
+ assert(Number.isSafeInteger(input.targetFrameCount) && input.targetFrameCount > 0,
+ "Timed visual target frame count is invalid.");
+ assert(input.sourceFrameRate.numerator === input.timeline.frameRate.numerator
+ && input.sourceFrameRate.denominator === input.timeline.frameRate.denominator,
+ "Timed visual source must be normalized to Timeline frame rate before Visual authoring.");
+ const spec = input.spec ?? defaultVisualSourceTimeSpec();
+ assertVisualSourceTimeSpec(spec);
+ const pieces = spec.relations.map((relation, index) => resolveRelation(
+ relation,
+ input.targetFrameCount,
+ input.sourceFrameCount,
+ `VisualSourceTimeSpec.relations.${index}`,
+ )).sort((left, right) => left.target.startFrame - right.target.startFrame);
+ let previousEnd = 0;
+ for (const [index, piece] of pieces.entries()) {
+ assert(piece.target.startFrame >= previousEnd, `Visual source-time pieces ${index - 1} and ${index} overlap.`);
+ previousEnd = piece.target.endFrameExclusive;
+ }
+ return {
+ sourceFrameRate: { ...input.sourceFrameRate },
+ sourceFrameCount: input.sourceFrameCount,
+ pieces,
+ };
+}
diff --git a/packages/visual-track/src/spatial.ts b/packages/visual-track/src/spatial.ts
new file mode 100644
index 00000000..a067ad08
--- /dev/null
+++ b/packages/visual-track/src/spatial.ts
@@ -0,0 +1,77 @@
+import {
+ assertSpatialFrame,
+ assertSpatialMap2D,
+ resolveContentFit,
+} from "@hypit/spatial";
+import type { SpatialFrame } from "@hypit/spatial";
+
+import { assertVisualFrameTreatment, visualContentFrame } from "./frame-treatment.js";
+import {
+ assertMediaLayerSet,
+ assertMediaPaintLayerSpec,
+ assertMediaSampleLayerSpec,
+ assertMediaVisualSource,
+} from "./layers.js";
+import type {
+ MediaLayerProgram,
+ MediaLayerSet,
+ MediaSampleLayerProgram,
+ VisualFrameTreatment,
+} from "./types.js";
+
+function assert(condition: unknown, message: string): asserts condition {
+ if (!condition) throw new Error(message);
+}
+
+/** Resolve every author placement exactly once, at the point its Clip Frame is known. */
+export function resolveMediaLayerPrograms(
+ set: MediaLayerSet,
+ frame: SpatialFrame,
+ treatment: VisualFrameTreatment,
+): readonly MediaLayerProgram[] {
+ assertMediaLayerSet(set);
+ assertSpatialFrame(frame);
+ assertVisualFrameTreatment(treatment, "VisualFrameTreatment");
+ const fitFrame = set.layers.some((layer) => layer.kind === "sample" && layer.placement.kind === "fit")
+ ? visualContentFrame(frame, treatment)
+ : undefined;
+ return set.layers.map((layer): MediaLayerProgram => {
+ if (layer.kind === "paint") return structuredClone(layer);
+ let mapping;
+ if (layer.placement.kind === "fit") {
+ assert(fitFrame !== undefined, `Media layer ${layer.id} has no fitting Frame.`);
+ mapping = resolveContentFit(fitFrame, layer.source.extent, layer.placement.fit);
+ } else {
+ mapping = layer.placement.mapping;
+ }
+ assertSpatialMap2D(mapping);
+ const { placement: _placement, ...rest } = layer;
+ return { ...structuredClone(rest), mapping: structuredClone(mapping) };
+ });
+}
+
+export function assertMediaLayerPrograms(value: readonly MediaLayerProgram[]): void {
+ assert(Array.isArray(value) && value.length > 0, "Resolved Media layers are empty.");
+ const ids = new Set<string>();
+ for (const layer of value) {
+ assert(!ids.has(layer.id), `Resolved Media layers repeat ${layer.id}.`);
+ ids.add(layer.id);
+ if (layer.kind === "paint") {
+ assertMediaPaintLayerSpec(layer);
+ continue;
+ }
+ assertMediaVisualSource(layer.source, `Media layer ${layer.id}.source`);
+ assertSpatialMap2D(layer.mapping);
+ assertMediaSampleLayerSpec({
+ id: layer.id,
+ ...(layer.sourceTime?.kind !== "spec" ? {} : { sourceTime: layer.sourceTime.value }),
+ appearance: layer.appearance,
+ ...(layer.samplingMotion === undefined ? {} : { samplingMotion: layer.samplingMotion }),
+ });
+ }
+}
+
+export function assertResolvedSampleLayer(value: MediaSampleLayerProgram, label: string): void {
+ assertMediaVisualSource(value.source, `${label}.source`);
+ assertSpatialMap2D(value.mapping);
+}
diff --git a/packages/visual-track/src/surface.ts b/packages/visual-track/src/surface.ts
new file mode 100644
index 00000000..34be7898
--- /dev/null
+++ b/packages/visual-track/src/surface.ts
@@ -0,0 +1,689 @@
+import { resolveTemporalContext } from "@hypit/temporal-markup";
+import {
+ assertEmptyElement as empty,
+ assertAttributes as allowed,
+ textAttribute as text,
+ optionalTextAttribute as optionalText,
+ type StructuredElement,
+ type StructuredSurfaceHandler,
+ type SurfaceComponentDraft,
+ type SurfaceRecordDraft,
+ type SurfaceResolvedReference,
+ type MarkupAttributeValue,
+} from "@hypit/markup";
+import { sameType, type CanonicalValue, type TypeRef } from "@hypit/protocol";
+import { artifactTypes } from "@hypit/artifact";
+import { compositionTypes } from "@hypit/composition";
+import { sealGraphFragment } from "@hypit/elaborator";
+import type { FragmentOperation } from "@hypit/elaborator";
+import { mediaTypes } from "@hypit/media";
+import { spatialTypes } from "@hypit/spatial";
+import { svsRecipeType } from "@hypit/svs";
+import type { SvsRecipe } from "@hypit/svs";
+import { temporalTypes } from "@hypit/temporal";
+import { createTemporalWindowConstruction, temporalWindowAttributeNames } from "@hypit/temporal-markup";
+
+import {
+ decodeMediaFit,
+ decodeMediaFramePaint,
+ decodeVisualClipSpec,
+ decodeMediaSampleSpec,
+} from "./author.js";
+import { sealVisualClipMotion } from "./motion.js";
+import { sealVisualTrackHeader } from "./program.js";
+import { assertVisualSourceTimeSpec } from "./source-time.js";
+import { visualTrackProducers, visualTrackTypes } from "./manifest.js";
+import type {
+ MediaSamplingMotion,
+ VisualClipMotion,
+ VisualMotionPosition,
+ VisualSourceTimeBounds,
+ VisualSourceTimePoint,
+ VisualSourceTimeRelation,
+ VisualSourceTimeSpec,
+} from "./types.js";
+
+const input = (name: string) => ({ kind: "fragment-input" as const, name });
+const operation = (id: string) => ({ kind: "fragment-operation" as const, operation: id });
+
+function numberValue(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 integerValue(element: StructuredElement, name: string): number {
+ const value = numberValue(element, name);
+ if (!Number.isSafeInteger(value)) throw new Error(`${element.name}.${name} must be an integer.`);
+ return value;
+}
+
+function motionPosition(element: StructuredElement): VisualMotionPosition {
+ const source = text(element, "at");
+ if (source === "start") return { kind: "start", offsetFrames: 0 };
+ if (source === "end") return { kind: "end", offsetFrames: 0 };
+ const percentage = /^(\d+(?:\.\d+)?)%$/u.exec(source);
+ if (percentage !== null) return { kind: "progress", value: Number(percentage[1]) / 100 };
+ const fromStart = /^(?:start\+)?(\d+)f$/u.exec(source);
+ if (fromStart !== null) return { kind: "start", offsetFrames: Number(fromStart[1]) };
+ const fromEnd = /^end-(\d+)f$/u.exec(source);
+ if (fromEnd !== null) return { kind: "end", offsetFrames: -Number(fromEnd[1]) };
+ throw new Error(`${element.name}.at must be start, end, a percentage, an exact frame from start, or end-Nf.`);
+}
+
+export function decodeVisualPoseKeyframe(element: StructuredElement): VisualClipMotion["keyframes"][number] {
+ allowed(element, ["at", "x", "y", "scale", "scale-x", "scale-y", "rotate", "opacity", "origin-x", "origin-y", "easing"]);
+ empty(element);
+ const scale = optionalText(element, "scale");
+ if (scale !== undefined && (element.attributes["scale-x"] !== undefined || element.attributes["scale-y"] !== undefined)) {
+ throw new Error(`${element.name}.scale cannot be combined with scale-x or scale-y.`);
+ }
+ const easing = optionalText(element, "easing");
+ if (easing !== undefined && !["linear", "ease-in", "ease-out", "ease-in-out"].includes(easing)) {
+ throw new Error(`${element.name}.easing is invalid.`);
+ }
+ const uniformScale = scale === undefined ? undefined : Number(scale);
+ if (uniformScale !== undefined && !Number.isFinite(uniformScale)) throw new Error(`${element.name}.scale must be finite.`);
+ return {
+ at: motionPosition(element),
+ translateX: numberValue(element, "x", 0),
+ translateY: numberValue(element, "y", 0),
+ scaleX: uniformScale ?? numberValue(element, "scale-x", 1),
+ scaleY: uniformScale ?? numberValue(element, "scale-y", 1),
+ rotationDeg: numberValue(element, "rotate", 0),
+ opacity: numberValue(element, "opacity", 1),
+ originX: numberValue(element, "origin-x", 0.5),
+ originY: numberValue(element, "origin-y", 0.5),
+ ...(easing === undefined ? {} : { easing: easing as "linear" | "ease-in" | "ease-out" | "ease-in-out" }),
+ };
+}
+
+function inlineMotion(element: StructuredElement): VisualClipMotion | undefined {
+ const keyframes = element.children.flatMap((child) => child.kind === "element"
+ && (child.name.endsWith(":Pose") || child.name === "Pose") ? [decodeVisualPoseKeyframe(child)] : []);
+ return keyframes.length === 0 ? undefined : sealVisualClipMotion({ keyframes });
+}
+
+export const decodeVisualMotionSurface: StructuredSurfaceHandler = ({ element }) => {
+ allowed(element, ["id"]);
+ const id = text(element, "id");
+ for (const child of element.children) {
+ if (child.kind === "text") {
+ if (child.value.trim().length > 0) throw new Error(`${element.name} accepts only Pose children.`);
+ continue;
+ }
+ if (!child.name.endsWith(":Pose") && child.name !== "Pose") {
+ throw new Error(`${element.name} accepts only Pose children.`);
+ }
+ }
+ const motion = inlineMotion(element);
+ if (motion === undefined) throw new Error(`${element.name} requires at least two Pose children.`);
+ return {
+ records: [{ id, type: visualTrackTypes.motion, value: { kind: "inline", value: motion as never }, range: element.range }],
+ components: [], fragments: [], exports: [id],
+ };
+};
+
+function reference(
+ raw: MarkupAttributeValue | undefined,
+ label: string,
+ expected: TypeRef,
+ 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 recipe(value: SurfaceResolvedReference, label: string): SvsRecipe {
+ if (!sameType(value.type, svsRecipeType) || value.record?.value.kind !== "inline") {
+ throw new Error(`${label} must be an authored SVS Recipe.`);
+ }
+ return value.record.value.value as unknown as SvsRecipe;
+}
+
+const FIT_ATTRIBUTES = ["fit", "frame-x", "frame-y", "content-x", "content-y", "fit-offset-x", "fit-offset-y", "fit-constraint"] as const;
+const NUMERIC_CLIP_ATTRIBUTES = new Set(["frame-x", "frame-y", "content-x", "content-y", "fit-offset-x", "fit-offset-y"]);
+
+function sourceRecipe(element: StructuredElement, treatment: SvsRecipe): SvsRecipe {
+ const properties: Record<string, CanonicalValue> = { ...treatment.properties };
+ for (const name of FIT_ATTRIBUTES) {
+ const raw = optionalText(element, name);
+ if (raw !== undefined) properties[name] = NUMERIC_CLIP_ATTRIBUTES.has(name) ? Number(raw) : raw;
+ }
+ return { path: `${treatment.path}:source`, properties };
+}
+
+const SOURCE_TIME_MAP_ATTRIBUTES = [
+ "target-from", "target-until", "target-at", "source-at", "rate",
+ "source-from", "source-until", "wrap-from", "wrap-until",
+] as const;
+
+function sourceTimePoint(raw: string | undefined, fallback: "start" | "end", label: string): VisualSourceTimePoint {
+ const value = raw ?? fallback;
+ if (value === "start") return { edge: "start", offsetFrames: 0 };
+ if (value === "end") return { edge: "end", offsetFrames: 0 };
+ const fromStart = /^(?:start\+)?(\d+)f$/u.exec(value);
+ if (fromStart !== null) return { edge: "start", offsetFrames: Number(fromStart[1]) };
+ const fromEnd = /^end-(\d+)f$/u.exec(value);
+ if (fromEnd !== null) return { edge: "end", offsetFrames: -Number(fromEnd[1]) };
+ throw new Error(`${label} must be start, end, Nf, start+Nf or end-Nf.`);
+}
+
+function sourceTimeBounds(
+ element: StructuredElement,
+ prefix: "target" | "source" | "wrap",
+ required = false,
+): VisualSourceTimeBounds | undefined {
+ const from = optionalText(element, `${prefix}-from`);
+ const until = optionalText(element, `${prefix}-until`);
+ if (!required && from === undefined && until === undefined) return undefined;
+ return {
+ from: sourceTimePoint(from, "start", `${element.name}.${prefix}-from`),
+ until: sourceTimePoint(until, "end", `${element.name}.${prefix}-until`),
+ };
+}
+
+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 sourceTimeRate(raw: string, label: string): { readonly numerator: number; readonly denominator: number } {
+ const fraction = /^(-?\d+)\/([1-9]\d*)$/u.exec(raw);
+ if (fraction !== null) {
+ const numerator = Number(fraction[1]);
+ const denominator = Number(fraction[2]);
+ if (!Number.isSafeInteger(numerator) || !Number.isSafeInteger(denominator)) throw new Error(`${label} is outside safe arithmetic.`);
+ const common = divisor(numerator, denominator);
+ return { numerator: numerator / common, denominator: denominator / common };
+ }
+ const decimal = /^(-?)(\d+)(?:\.(\d+))?$/u.exec(raw);
+ if (decimal === null) throw new Error(`${label} must be an exact integer, decimal or fraction.`);
+ const fractional = decimal[3] ?? "";
+ const denominator = 10 ** fractional.length;
+ const magnitude = Number(decimal[2]) * denominator + (fractional.length === 0 ? 0 : Number(fractional));
+ const numerator = decimal[1] === "-" ? -magnitude : magnitude;
+ if (!Number.isSafeInteger(numerator) || !Number.isSafeInteger(denominator)) throw new Error(`${label} is outside safe arithmetic.`);
+ const common = divisor(numerator, denominator);
+ return { numerator: numerator / common, denominator: denominator / common };
+}
+
+export function decodeVisualSourceTimeRelation(element: StructuredElement): VisualSourceTimeRelation {
+ allowed(element, SOURCE_TIME_MAP_ATTRIBUTES);
+ empty(element);
+ const target = sourceTimeBounds(element, "target", true)!;
+ const source = sourceTimeBounds(element, "source", true)!;
+ const hasRateRelation = element.attributes.rate !== undefined
+ || element.attributes["target-at"] !== undefined
+ || element.attributes["source-at"] !== undefined
+ || element.attributes["wrap-from"] !== undefined
+ || element.attributes["wrap-until"] !== undefined;
+ if (!hasRateRelation) return { kind: "fit", target, source };
+ const wrap = sourceTimeBounds(element, "wrap");
+ const relation: VisualSourceTimeRelation = {
+ kind: "rate",
+ target,
+ targetAt: sourceTimePoint(optionalText(element, "target-at"), "start", `${element.name}.target-at`),
+ sourceAt: sourceTimePoint(optionalText(element, "source-at"), "start", `${element.name}.source-at`),
+ rate: sourceTimeRate(optionalText(element, "rate") ?? "1", `${element.name}.rate`),
+ source,
+ ...(wrap === undefined ? {} : { wrap }),
+ };
+ return relation;
+}
+
+function inlineSourceTime(element: StructuredElement): VisualSourceTimeSpec | undefined {
+ const relations = element.children.flatMap((child) => child.kind === "element"
+ && (child.name.endsWith(":Map") || child.name === "Map") ? [decodeVisualSourceTimeRelation(child)] : []);
+ if (relations.length === 0) return undefined;
+ const value = { relations };
+ assertVisualSourceTimeSpec(value);
+ return value;
+}
+
+function sourceTimeFrom(
+ element: StructuredElement,
+ resolve: (path: string) => SurfaceResolvedReference | undefined,
+): VisualSourceTimeSpec | undefined {
+ const inline = inlineSourceTime(element);
+ if (element.attributes["source-time"] === undefined) return inline;
+ if (inline !== undefined) throw new Error(`${element.name} cannot combine source-time={SourceTime} with inline Map children.`);
+ const value = reference(element.attributes["source-time"], `${element.name}.source-time`, visualTrackTypes.sourceTime, resolve);
+ if (value.record?.value.kind !== "inline") throw new Error(`${element.name}.source-time must resolve to an inline SourceTime value.`);
+ const spec = value.record.value.value as unknown as VisualSourceTimeSpec;
+ assertVisualSourceTimeSpec(spec);
+ return spec;
+}
+
+export const decodeVisualSourceTimeSurface: StructuredSurfaceHandler = ({ element }) => {
+ allowed(element, ["id"]);
+ const id = text(element, "id");
+ const relations: VisualSourceTimeRelation[] = [];
+ for (const child of element.children) {
+ if (child.kind === "text") {
+ if (child.value.trim().length > 0) throw new Error(`${element.name} accepts only Map children.`);
+ continue;
+ }
+ if (!child.name.endsWith(":Map") && child.name !== "Map") throw new Error(`${element.name} accepts only Map children.`);
+ relations.push(decodeVisualSourceTimeRelation(child));
+ }
+ const value = { relations };
+ assertVisualSourceTimeSpec(value);
+ return {
+ records: [{ id, type: visualTrackTypes.sourceTime, value: { kind: "inline", value: value as never }, range: element.range }],
+ components: [], fragments: [], exports: [id],
+ };
+};
+
+function treatmentRecipe(
+ element: StructuredElement,
+ resolve: (path: string) => SurfaceResolvedReference | undefined,
+): SvsRecipe {
+ if (element.attributes.treatment === undefined) return { path: `${element.name}:default-treatment`, properties: {} };
+ return recipe(reference(element.attributes.treatment, `${element.name}.treatment`, svsRecipeType, resolve), `${element.name}.treatment`);
+}
+
+type FragmentLayer =
+ | { readonly kind: "paint"; readonly specName: string }
+ | { readonly kind: "still"; readonly sourceName: string; readonly extentName: string; readonly placementKind: "fit" | "mapping"; readonly placementName: string; readonly specName: string }
+ | { readonly kind: "timed" | "surface"; readonly sourceName: string; readonly placementKind: "fit" | "mapping"; readonly placementName: string; readonly specName: string };
+
+type FragmentClip = {
+ readonly suffix: string;
+ readonly windowName: string;
+ readonly frameName: string;
+ readonly specName: string;
+ readonly clipPathName?: string;
+ readonly motionName?: string;
+ readonly layers: readonly FragmentLayer[];
+};
+
+function appendLayers(operations: FragmentOperation[], prefix: string, layers: readonly FragmentLayer[]): string {
+ const emptyId = `${prefix}:layers:empty`;
+ operations.push({ id: emptyId, producer: visualTrackProducers.createLayers, inputs: {}, result: { kind: "output", name: "layers" } });
+ let current = emptyId;
+ for (const [index, layer] of layers.entries()) {
+ const id = `${prefix}:layers:${String(index + 1).padStart(4, "0")}`;
+ const common = { layers: operation(current), spec: input(layer.specName) };
+ if (layer.kind === "paint") {
+ operations.push({ id, producer: visualTrackProducers.appendPaintLayer, inputs: common, result: { kind: "output", name: "layers" } });
+ } else if (layer.kind === "still") {
+ operations.push({ id, producer: layer.placementKind === "fit"
+ ? visualTrackProducers.appendStillLayer : visualTrackProducers.appendMappedStillLayer, inputs: {
+ ...common, source: input(layer.sourceName), extent: input(layer.extentName),
+ [layer.placementKind === "fit" ? "fit" : "mapping"]: input(layer.placementName),
+ }, result: { kind: "output", name: "layers" } });
+ } else {
+ const producer = layer.kind === "timed"
+ ? layer.placementKind === "fit" ? visualTrackProducers.appendTimedLayer : visualTrackProducers.appendMappedTimedLayer
+ : layer.placementKind === "fit" ? visualTrackProducers.appendSurfaceLayer : visualTrackProducers.appendMappedSurfaceLayer;
+ operations.push({ id, producer, inputs: {
+ ...common, source: input(layer.sourceName),
+ [layer.placementKind === "fit" ? "fit" : "mapping"]: input(layer.placementName),
+ }, result: { kind: "output", name: "layers" } });
+ }
+ current = id;
+ }
+ return current;
+}
+
+function createVisualTrackSurfaceFragment(inputTypes: readonly { readonly name: string; readonly type: TypeRef }[], clips: readonly FragmentClip[]) {
+ const operations: FragmentOperation[] = [
+ { id: "track:set:empty", producer: visualTrackProducers.createSet, inputs: {}, result: { kind: "output", name: "set" } },
+ ];
+ let set = "track:set:empty";
+ for (const clip of clips) {
+ const prefix = `clip:${clip.suffix}`;
+ const layers = appendLayers(operations, prefix, clip.layers);
+ const appendId = `${prefix}:append`;
+ let spec: FragmentOperation["inputs"][string] = input(clip.specName);
+ if (clip.clipPathName !== undefined) {
+ const bindId = `${prefix}:bind-clip-path`;
+ operations.push({ id: bindId, producer: visualTrackProducers.bindClipPath, inputs: {
+ spec, path: input(clip.clipPathName),
+ }, result: { kind: "output", name: "spec" } });
+ spec = operation(bindId);
+ }
+ if (clip.motionName !== undefined) {
+ const bindId = `${prefix}:bind-motion`;
+ operations.push({ id: bindId, producer: visualTrackProducers.bindMotion, inputs: {
+ spec, motion: input(clip.motionName),
+ }, result: { kind: "output", name: "spec" } });
+ spec = operation(bindId);
+ }
+ const common = {
+ set: operation(set), header: input("header"), timeline: input("timeline"),
+ layers: operation(layers), frame: input(clip.frameName), spec, window: input(clip.windowName),
+ };
+ operations.push({ id: appendId, producer: visualTrackProducers.appendClip,
+ inputs: common, result: { kind: "output", name: "set" } });
+ set = appendId;
+ }
+ operations.push(
+ { id: "track:finalize", producer: visualTrackProducers.finalize, inputs: { set: operation(set), header: input("header"), timeline: input("timeline") }, result: { kind: "output", name: "program" } },
+ { id: "track:visual", producer: visualTrackProducers.projectVisual, inputs: { timeline: input("timeline"), program: operation("track:finalize") }, result: { kind: "output", name: "track" } },
+ );
+ return sealGraphFragment({
+ inputs: inputTypes,
+ operations,
+ exports: [
+ { name: "program", type: visualTrackTypes.program, root: operation("track:finalize") },
+ { name: "visual", type: compositionTypes.visualTrack, root: operation("track:visual") },
+ ],
+ });
+}
+
+type SurfaceBuilder = {
+ readonly records: SurfaceRecordDraft[];
+ readonly inputs: Record<string, SurfaceResolvedReference["ref"] | { readonly kind: "record"; readonly id: string }>;
+ readonly inputTypes: { name: string; type: TypeRef }[];
+ addReference(name: string, value: SurfaceResolvedReference): void;
+ addRecord(name: string, id: string, type: TypeRef, value: unknown, range: StructuredElement["range"]): void;
+ addValue(name: string, value: SurfaceResolvedReference["ref"], type: TypeRef): void;
+};
+
+function builder(): SurfaceBuilder {
+ const records: SurfaceRecordDraft[] = [];
+ const inputs: SurfaceBuilder["inputs"] = {};
+ const inputTypes: SurfaceBuilder["inputTypes"] = [];
+ return {
+ records,
+ inputs,
+ inputTypes,
+ addReference(name, value) {
+ if (inputs[name] !== undefined) throw new Error(`Media Surface repeats input ${name}.`);
+ inputs[name] = value.ref;
+ inputTypes.push({ name, type: value.type });
+ },
+ addRecord(name, id, type, value, range) {
+ if (inputs[name] !== undefined) throw new Error(`Media Surface repeats input ${name}.`);
+ records.push({ id, type, value: { kind: "inline", value: value as never }, range });
+ inputs[name] = { kind: "record", id };
+ inputTypes.push({ name, type });
+ },
+ addValue(name, value, type) {
+ if (inputs[name] !== undefined) throw new Error(`Media Surface repeats input ${name}.`);
+ inputs[name] = value;
+ inputTypes.push({ name, type });
+ },
+ };
+}
+
+function suffix(index: number): string {
+ return String(index).padStart(4, "0");
+}
+
+type SourceLayerContext = {
+ readonly trackId: string;
+ readonly unitSuffix: string;
+ readonly defaultRecipe: SvsRecipe;
+ readonly sourceElement: StructuredElement;
+ readonly source?: DeclaredVisualSource;
+ readonly sourceTime?: VisualSourceTimeSpec;
+ readonly ignoreSiblingChildren?: boolean;
+ readonly defaultLayerId?: string;
+ readonly mapping?: SurfaceResolvedReference;
+};
+
+type DeclaredVisualSource =
+ | { readonly kind: "image"; readonly value: SurfaceResolvedReference; readonly extent: SurfaceResolvedReference }
+ | { readonly kind: "media"; readonly value: SurfaceResolvedReference }
+ | { readonly kind: "surface"; readonly value: SurfaceResolvedReference };
+
+const VISUAL_SOURCE_ATTRIBUTES = ["image", "media", "surface"] as const;
+
+function declaredVisualSource(
+ element: StructuredElement,
+ resolve: (path: string) => SurfaceResolvedReference | undefined,
+ required = false,
+): DeclaredVisualSource | undefined {
+ const present = VISUAL_SOURCE_ATTRIBUTES.filter((name) => element.attributes[name] !== undefined);
+ if (present.length === 0) {
+ if (element.attributes.extent !== undefined) throw new Error(`${element.name}.extent requires image={Artifact}.`);
+ if (element.attributes.audio !== undefined) throw new Error(`${element.name}.audio is no longer accepted; normalize the source explicitly and use media={...}.`);
+ if (required) throw new Error(`${element.name} requires exactly one of image, media or surface.`);
+ return undefined;
+ }
+ if (present.length !== 1) throw new Error(`${element.name} requires exactly one of image, media or surface.`);
+ const kind = present[0]!;
+ if (kind === "image") {
+ if (element.attributes.audio !== undefined) throw new Error(`${element.name}.audio is no longer accepted; normalize the source explicitly and use media={...}.`);
+ return {
+ kind,
+ value: reference(element.attributes.image, `${element.name}.image`, artifactTypes.blob, resolve),
+ extent: reference(element.attributes.extent, `${element.name}.extent`, spatialTypes.extent, resolve),
+ };
+ }
+ if (element.attributes.extent !== undefined) throw new Error(`${element.name}.extent is only valid with image={Artifact}.`);
+ if (element.attributes.audio !== undefined) throw new Error(`${element.name}.audio is no longer accepted; normalize the source explicitly and use media={...}.`);
+ return kind === "media"
+ ? { kind, value: reference(element.attributes.media, `${element.name}.media`, mediaTypes.synchronized, resolve) }
+ : { kind, value: reference(element.attributes.surface, `${element.name}.surface`, mediaTypes.compositableSurface, resolve) };
+}
+
+export function decodeMediaSamplingKeyframe(element: StructuredElement): MediaSamplingMotion["keyframes"][number] {
+ allowed(element, ["at", "zoom", "x", "y", "rotate", "easing"]);
+ empty(element);
+ const at = text(element, "at");
+ const percentage = /^(\d+(?:\.\d+)?)%$/u.exec(at);
+ const atProgress = at === "start" ? 0 : at === "end" ? 1
+ : percentage === null ? Number.NaN : Number(percentage[1]) / 100;
+ if (!Number.isFinite(atProgress) || atProgress < 0 || atProgress > 1) {
+ throw new Error(`${element.name}.at must be start, end or a percentage inside 0%..100%.`);
+ }
+ const easing = optionalText(element, "easing");
+ if (easing !== undefined && !["linear", "ease-in", "ease-out", "ease-in-out"].includes(easing)) {
+ throw new Error(`${element.name}.easing is invalid.`);
+ }
+ return {
+ atProgress, zoom: numberValue(element, "zoom", 1), offsetX: numberValue(element, "x", 0),
+ offsetY: numberValue(element, "y", 0), rotationDeg: numberValue(element, "rotate", 0),
+ ...(easing === undefined ? {} : { easing: easing as "linear" | "ease-in" | "ease-out" | "ease-in-out" }),
+ };
+}
+
+function decodeSamplingMotion(element: StructuredElement, ignoreSiblingChildren = false): MediaSamplingMotion | undefined {
+ const keyframes = element.children.flatMap((child) => {
+ if (child.kind === "text") {
+ if (child.value.trim().length > 0) throw new Error(`${element.name} accepts only Sampling children.`);
+ return [];
+ }
+ if (!child.name.endsWith(":Sampling") && child.name !== "Sampling") {
+ if (ignoreSiblingChildren) return [];
+ throw new Error(`${element.name} accepts only Sampling children.`);
+ }
+ return [decodeMediaSamplingKeyframe(child)];
+ });
+ return keyframes.length === 0 ? undefined : { keyframes };
+}
+
+function sourceLayer(
+ state: SurfaceBuilder,
+ context: SourceLayerContext,
+ layerIndex: number,
+ resolve: (path: string) => SurfaceResolvedReference | undefined,
+): FragmentLayer {
+ const element = context.sourceElement;
+ const source = context.source ?? declaredVisualSource(element, resolve, true)!;
+ const appearance = element.attributes.appearance === undefined
+ ? context.defaultRecipe
+ : recipe(reference(element.attributes.appearance, `${element.name}.appearance`, svsRecipeType, resolve), `${element.name}.appearance`);
+ const motion = decodeSamplingMotion(element, context.ignoreSiblingChildren);
+ const layerSuffix = `${context.unitSuffix}-layer-${suffix(layerIndex)}`;
+ const layerId = context.defaultLayerId ?? optionalText(element, "id") ?? `${context.trackId}.${layerSuffix}`;
+ const placementKind = context.mapping === undefined ? "fit" : "mapping";
+ const placementName = `${layerSuffix}-${placementKind}`;
+ const specName = `${layerSuffix}-spec`;
+ if (context.mapping === undefined) {
+ state.addRecord(placementName, `${context.trackId}.${layerSuffix}.fit`, spatialTypes.fit, decodeMediaFit(appearance), element.range);
+ } else {
+ state.addReference(placementName, context.mapping);
+ }
+ const sourceKind = source.kind === "image" ? "still"
+ : source.kind === "surface" ? "surface" : "timed";
+ const spec = decodeMediaSampleSpec(
+ appearance,
+ layerId,
+ sourceKind,
+ motion,
+ context.source !== undefined,
+ context.sourceTime,
+ );
+ state.addRecord(specName, `${context.trackId}.${layerSuffix}.spec`, visualTrackTypes.sampleLayerSpec, spec, element.range);
+ const sourceName = `${layerSuffix}-source`;
+ state.addReference(sourceName, source.value);
+ if (sourceKind === "still") {
+ const extentName = `${layerSuffix}-extent`;
+ state.addReference(extentName, (source as Extract<DeclaredVisualSource, { readonly kind: "image" }>).extent);
+ return { kind: "still", sourceName, extentName, placementKind, placementName, specName };
+ }
+ return { kind: sourceKind, sourceName, placementKind, placementName, specName };
+}
+
+function unitLayers(
+ state: SurfaceBuilder,
+ input: {
+ readonly trackId: string;
+ readonly unitSuffix: string;
+ readonly element: StructuredElement;
+ readonly appearance: SvsRecipe;
+ readonly directSource: DeclaredVisualSource;
+ readonly sourceTime?: VisualSourceTimeSpec;
+ readonly mapping?: SurfaceResolvedReference;
+ readonly allowFramePaint: boolean;
+ },
+ resolve: (path: string) => SurfaceResolvedReference | undefined,
+): readonly FragmentLayer[] {
+ const layers: FragmentLayer[] = [];
+ if (input.allowFramePaint) {
+ const framePaint = decodeMediaFramePaint(input.appearance, `${input.trackId}.${input.unitSuffix}.frame-paint`);
+ if (framePaint !== undefined) {
+ const name = `${input.unitSuffix}-frame-paint`;
+ state.addRecord(name, `${input.trackId}.${input.unitSuffix}.frame-paint`, visualTrackTypes.paintLayerSpec, framePaint, input.element.range);
+ layers.push({ kind: "paint", specName: name });
+ }
+ }
+ layers.push(sourceLayer(state, {
+ trackId: input.trackId, unitSuffix: input.unitSuffix, defaultRecipe: input.appearance,
+ sourceElement: input.element, source: input.directSource,
+ ...(input.mapping === undefined ? {} : { mapping: input.mapping }),
+ ...(input.sourceTime === undefined ? {} : { sourceTime: input.sourceTime }),
+ ignoreSiblingChildren: true,
+ defaultLayerId: "content",
+ }, 1, resolve));
+ return layers;
+}
+
+function validateUnitChildren(element: StructuredElement): void {
+ for (const child of element.children) {
+ if (child.kind === "text") {
+ if (child.value.trim().length > 0) throw new Error(`${element.name} cannot contain text.`);
+ continue;
+ }
+ const samplingChild = child.name.endsWith(":Sampling") || child.name === "Sampling";
+ const poseChild = child.name.endsWith(":Pose") || child.name === "Pose";
+ const mapChild = child.name.endsWith(":Map") || child.name === "Map";
+ if (samplingChild || poseChild || mapChild) continue;
+ throw new Error(`${element.name} has unsupported child ${child.name}.`);
+ }
+}
+
+export const decodeVisualTrackSurface: StructuredSurfaceHandler = ({ element, resolveReference }) => {
+ allowed(element, ["id", "timeline"]);
+ const trackId = text(element, "id");
+ const state = builder();
+ const context = resolveTemporalContext({ element, resolveReference });
+ state.addReference("timeline", context.timeline);
+ const headerId = `${trackId}.header`;
+ state.addRecord("header", headerId, visualTrackTypes.header,
+ sealVisualTrackHeader({ id: trackId }), element.range);
+ const clips: FragmentClip[] = [];
+ const temporalComponents: SurfaceComponentDraft[] = [];
+ const temporalFragments: ReturnType<typeof createTemporalWindowConstruction>["fragments"][number][] = [];
+ let clipIndex = 0;
+ for (const child of element.children) {
+ if (child.kind === "text") {
+ if (child.value.trim().length > 0) throw new Error(`${element.name} accepts only Clip children.`);
+ continue;
+ }
+ if (child.name.endsWith(":Clip") || child.name === "Clip") {
+ clipIndex += 1;
+ const clipSuffix = suffix(clipIndex);
+ allowed(child, [
+ "id", "frame", "treatment", "motion", "z",
+ "image", "media", "surface", "extent",
+ "clip", "source-time", "mapping", ...FIT_ATTRIBUTES, ...temporalWindowAttributeNames,
+ ]);
+ const id = optionalText(child, "id") ?? `${trackId}.clip.${clipSuffix}`;
+ const treatment = treatmentRecipe(child, resolveReference);
+ const sourceAppearance = sourceRecipe(child, treatment);
+ const clipPathName = child.attributes.clip === undefined ? undefined : `clip-${clipSuffix}-clip-path`;
+ if (clipPathName !== undefined) {
+ if (treatment.properties.clip !== undefined) throw new Error(`${child.name} cannot combine clip={Path} with treatment clip.`);
+ state.addReference(clipPathName, reference(child.attributes.clip, `${child.name}.clip`, spatialTypes.path, resolveReference));
+ }
+ const authoredMotion = inlineMotion(child);
+ if (authoredMotion !== undefined && child.attributes.motion !== undefined) {
+ throw new Error(`${child.name} cannot combine motion={Motion} with Pose children.`);
+ }
+ const motionName = authoredMotion === undefined && child.attributes.motion === undefined ? undefined : `clip-${clipSuffix}-motion`;
+ if (motionName !== undefined) {
+ if (authoredMotion !== undefined) {
+ state.addRecord(motionName, `${trackId}.clip.${clipSuffix}.motion`, visualTrackTypes.motion, authoredMotion, child.range);
+ } else {
+ state.addReference(motionName, reference(child.attributes.motion, `${child.name}.motion`, visualTrackTypes.motion, resolveReference));
+ }
+ }
+ const temporal = createTemporalWindowConstruction({ id, element: child, ...context, resolveReference });
+ state.records.push(...temporal.records); temporalComponents.push(...temporal.components); temporalFragments.push(...temporal.fragments);
+ const directSource = declaredVisualSource(child, resolveReference, true)!;
+ const sourceTime = sourceTimeFrom(child, resolveReference);
+ const mapping = child.attributes.mapping === undefined ? undefined
+ : reference(child.attributes.mapping, `${child.name}.mapping`, spatialTypes.map2D, resolveReference);
+ if (mapping !== undefined && FIT_ATTRIBUTES.some((name) => child.attributes[name] !== undefined)) {
+ throw new Error(`${child.name} cannot combine mapping={SpatialMap2D} with fit attributes.`);
+ }
+ validateUnitChildren(child);
+ const layers = unitLayers(state, { trackId, unitSuffix: `clip-${clipSuffix}`, element: child, appearance: sourceAppearance,
+ directSource, ...(sourceTime === undefined ? {} : { sourceTime }), ...(mapping === undefined ? {} : { mapping }),
+ allowFramePaint: true }, resolveReference);
+ const specName = `clip-${clipSuffix}-spec`;
+ const windowName = `clip-${clipSuffix}-window`;
+ state.addValue(windowName, temporal.ref, temporalTypes.window);
+ state.addRecord(specName, `${trackId}.clip.${clipSuffix}.spec`, visualTrackTypes.clipSpec,
+ decodeVisualClipSpec(treatment, { id, z: integerValue(child, "z") }), child.range);
+ const frameName = `clip-${clipSuffix}-frame`;
+ state.addReference(frameName, reference(child.attributes.frame, `${child.name}.frame`, spatialTypes.frame, resolveReference));
+ clips.push({ suffix: clipSuffix, windowName, frameName, specName,
+ ...(clipPathName === undefined ? {} : { clipPathName }),
+ ...(motionName === undefined ? {} : { motionName }), layers });
+ continue;
+ }
+ throw new Error(`${element.name} accepts only Clip children.`);
+ }
+ if (clips.length === 0) {
+ throw new Error(`${element.name} requires at least one Clip.`);
+ }
+ const fragment = createVisualTrackSurfaceFragment(state.inputTypes, clips);
+ return {
+ records: state.records,
+ components: [...temporalComponents, {
+ id: trackId,
+ fragment: fragment.id,
+ inputs: state.inputs,
+ outputs: { visual: `${trackId}.visual`, program: `${trackId}.program` },
+ range: element.range,
+ }],
+ fragments: [...temporalFragments, fragment],
+ exports: [
+ `${trackId}.program`,
+ `${trackId}.visual`,
+ ],
+ };
+};
diff --git a/packages/visual-track/src/types.ts b/packages/visual-track/src/types.ts
new file mode 100644
index 00000000..0db7f065
--- /dev/null
+++ b/packages/visual-track/src/types.ts
@@ -0,0 +1,252 @@
+import type { FrameSpan, VisualEasing, VisualSourceTimeMap, VisualSourceTimeRational } from "@hypit/composition";
+import type { CompositableSurfaceRef, MediaRational } from "@hypit/media";
+import type { BlobRef } from "@hypit/protocol";
+import type {
+ ContentFit,
+ IntrinsicExtent,
+ SpatialFrame,
+ SpatialMap2D,
+ SpatialPath,
+} from "@hypit/spatial";
+
+/** Intrinsic visual truth resolved before Media authoring; never a Provider or lineage envelope. */
+export type MediaVisualSource =
+ | {
+ readonly kind: "still";
+ readonly artifact: BlobRef;
+ readonly extent: IntrinsicExtent;
+ }
+ | {
+ readonly kind: "timed";
+ readonly artifact: BlobRef;
+ readonly extent: IntrinsicExtent;
+ readonly frameRate: MediaRational;
+ readonly frameCount: number;
+ }
+ | {
+ readonly kind: "surface";
+ readonly surface: CompositableSurfaceRef;
+ readonly extent: IntrinsicExtent;
+ };
+
+/** Start/end-relative point in one target or source frame domain. */
+export type VisualSourceTimePoint = {
+ readonly edge: "start" | "end";
+ /** Positive from start, negative from end; zero names the edge itself. */
+ readonly offsetFrames: number;
+};
+
+export type VisualSourceTimeBounds = {
+ readonly from: VisualSourceTimePoint;
+ readonly until: VisualSourceTimePoint;
+};
+
+/** One author relation. Unknown target/source lengths are resolved only when the Clip is lowered. */
+export type VisualSourceTimeRelation =
+ | {
+ readonly kind: "rate";
+ readonly target: VisualSourceTimeBounds;
+ readonly targetAt: VisualSourceTimePoint;
+ readonly sourceAt: VisualSourceTimePoint;
+ readonly rate: VisualSourceTimeRational;
+ readonly source: VisualSourceTimeBounds;
+ readonly wrap?: VisualSourceTimeBounds;
+ }
+ | {
+ readonly kind: "fit";
+ readonly target: VisualSourceTimeBounds;
+ readonly source: VisualSourceTimeBounds;
+ };
+
+export type VisualSourceTimeSpec = {
+ readonly relations: readonly VisualSourceTimeRelation[];
+};
+
+export type MediaVisualSourceTime =
+ | { readonly kind: "spec"; readonly value: VisualSourceTimeSpec }
+ | { readonly kind: "map"; readonly value: VisualSourceTimeMap };
+
+export type MediaGradientStop = {
+ readonly offset: number;
+ readonly color: string;
+};
+
+export type MediaPaint =
+ | { readonly kind: "solid"; readonly color: string }
+ | {
+ readonly kind: "linear-gradient";
+ readonly angleDeg: number;
+ readonly stops: readonly MediaGradientStop[];
+ }
+ | {
+ readonly kind: "radial-gradient";
+ readonly center: { readonly x: number; readonly y: number };
+ readonly stops: readonly MediaGradientStop[];
+ };
+
+export type MediaSampleAppearance = {
+ readonly opacity: number;
+ readonly filter: {
+ readonly blurPx: number;
+ readonly brightness: number;
+ readonly contrast: number;
+ readonly saturation: number;
+ };
+};
+
+export type MediaSamplingKeyframe = {
+ /** Normalized position inside the resolved Clip envelope. */
+ readonly atProgress: number;
+ readonly zoom: number;
+ readonly offsetX: number;
+ readonly offsetY: number;
+ readonly rotationDeg: number;
+ readonly easing?: "linear" | "ease-in" | "ease-out" | "ease-in-out";
+};
+
+export type MediaSamplingMotion = {
+ readonly keyframes: readonly MediaSamplingKeyframe[];
+};
+
+export type MediaPaintLayerProgram = {
+ readonly id: string;
+ readonly kind: "paint";
+ readonly paint: MediaPaint;
+ readonly opacity: number;
+};
+
+/** Author relation retained only until the Clip's destination Frame is known. */
+export type MediaSamplePlacement =
+ | { readonly kind: "fit"; readonly fit: ContentFit }
+ | { readonly kind: "mapping"; readonly mapping: SpatialMap2D };
+
+export type MediaSampleLayer = {
+ readonly id: string;
+ readonly kind: "sample";
+ /** Absent exactly for still material; timed material always carries source-time intent. */
+ readonly sourceTime?: MediaVisualSourceTime;
+ readonly source: MediaVisualSource;
+ readonly placement: MediaSamplePlacement;
+ readonly appearance: MediaSampleAppearance;
+ readonly samplingMotion?: MediaSamplingMotion;
+};
+
+export type MediaLayer = MediaPaintLayerProgram | MediaSampleLayer;
+
+/** Resolved source-to-picture fact consumed by rendering and spatial evidence adapters. */
+export type MediaSampleLayerProgram = Omit<MediaSampleLayer, "placement"> & {
+ readonly mapping: SpatialMap2D;
+};
+
+export type MediaLayerProgram = MediaPaintLayerProgram | MediaSampleLayerProgram;
+
+export type MediaPaintLayerSpec = {
+ readonly id: string;
+ readonly paint: MediaPaint;
+ readonly opacity: number;
+};
+
+export type MediaSampleLayerSpec = {
+ readonly id: string;
+ /** Omission means bounded partial identity for timed material. */
+ readonly sourceTime?: VisualSourceTimeSpec;
+ readonly appearance: MediaSampleAppearance;
+ readonly samplingMotion?: MediaSamplingMotion;
+};
+
+export type MediaLayerSet = {
+ readonly layers: readonly MediaLayer[];
+};
+
+export type MediaPadding = {
+ readonly topPx: number;
+ readonly rightPx: number;
+ readonly bottomPx: number;
+ readonly leftPx: number;
+};
+
+export type MediaFrameClip =
+ | { readonly kind: "none" }
+ | { readonly kind: "frame" }
+ | { readonly kind: "rounded"; readonly radiusPx: number }
+ | { readonly kind: "path"; readonly path: SpatialPath };
+
+export type VisualFrameTreatment = {
+ readonly clip: MediaFrameClip;
+ readonly padding: MediaPadding;
+ readonly border?: {
+ readonly widthPx: number;
+ readonly style: "solid" | "dashed" | "dotted";
+ readonly color: string;
+ };
+ readonly shadows: readonly {
+ readonly offsetX: number;
+ readonly offsetY: number;
+ readonly blurPx: number;
+ readonly spreadPx: number;
+ readonly color: string;
+ }[];
+};
+
+/**
+ * A position on a Clip-local clock. Frame offsets keep authored entrances and exits exact while
+ * normalized progress lets one Motion adapt to differently sized Windows.
+ */
+export type VisualMotionPosition =
+ | { readonly kind: "progress"; readonly value: number }
+ | { readonly kind: "start"; readonly offsetFrames: number }
+ | { readonly kind: "end"; readonly offsetFrames: number };
+
+/** One complete affine/opacity state. There are no named aesthetic operators in the base model. */
+export type VisualPoseKeyframe = {
+ readonly at: VisualMotionPosition;
+ readonly translateX: number;
+ readonly translateY: number;
+ readonly scaleX: number;
+ readonly scaleY: number;
+ readonly rotationDeg: number;
+ readonly opacity: number;
+ readonly originX: number;
+ readonly originY: number;
+ readonly easing?: VisualEasing;
+};
+
+/** Reusable Clip-local visual motion. Components may construct the same value directly. */
+export type VisualClipMotion = {
+ readonly keyframes: readonly VisualPoseKeyframe[];
+};
+
+export type VisualClipSpec = {
+ readonly id: string;
+ readonly treatment: VisualFrameTreatment;
+ readonly motion?: VisualClipMotion;
+ readonly z: number;
+};
+
+export type VisualClipProgram = {
+ readonly id: string;
+ /** One author-owned Clip occurrence realized by this absolute Window. */
+ readonly subjectId: string;
+ readonly span: FrameSpan;
+ readonly frame: SpatialFrame;
+ readonly treatment: VisualFrameTreatment;
+ readonly layers: readonly MediaLayerProgram[];
+ readonly motion?: VisualClipMotion;
+ /** Stable declaration order inside the owning Visual Track. */
+ readonly order: number;
+ /** Author-owned absolute picture stacking position. */
+ readonly z: number;
+};
+
+export type VisualTrackProgram = {
+ readonly id: string;
+ readonly clips: readonly VisualClipProgram[];
+};
+
+export type VisualTrackHeader = {
+ readonly id: string;
+};
+
+export type VisualTrackSet = {
+ readonly clips: readonly VisualClipProgram[];
+};
diff --git a/packages/visual-track/test/visual-track.test.ts b/packages/visual-track/test/visual-track.test.ts
new file mode 100644
index 00000000..728cb4ff
--- /dev/null
+++ b/packages/visual-track/test/visual-track.test.ts
@@ -0,0 +1,721 @@
+import { sealTimeline, timelineTypes } from "@hypit/timeline";
+import assert from "node:assert/strict";
+import test from "node:test";
+import { fixtureResource } from "../../../test/fixture-resource.js";
+import { narrativeProjectionFixture, timelineFixture } from "../../../test/timeline-fixture.js";
+import { projectMomentWindow, projectProgramWindow, projectSegmentWindow, projectSelectionWindow } from "../../../test/temporal-fixture.js";
+import type { TemporalWindowProjection } from "../../../test/temporal-fixture.js";
+
+import { sealComposition } from "@hypit/composition";
+import { compileHyperframesDocument } from "@hypit/hyperframes";
+import { mediaTypes } from "@hypit/media";
+import type { CompositableSurfaceRef, SynchronizedMedia } from "@hypit/media";
+import { artifactTypes } from "@hypit/artifact";
+import { temporalTypes } from "@hypit/temporal";
+import {
+ appendMediaPaintLayer,
+ appendMappedStillMediaLayer,
+ appendVisualClip,
+ appendStillMediaLayer,
+ appendSurfaceMediaLayer,
+ appendTimedMediaLayer,
+ bindVisualClipPath,
+ createMediaLayerSet,
+ createVisualTrackSet,
+ decodeVisualTrackSurface,
+ finalizeVisualTrack,
+ projectVisualTrack,
+ poseAnimation,
+ resolveVisualSourceTime,
+ sealVisualClipSpec,
+ sealMediaPaintLayerSpec,
+ sealMediaSampleLayerSpec,
+ sealVisualTrackHeader,
+ stillVisualTrackFragment,
+ visualTrackManifest,
+ visualTrackMarkupSurfaces,
+ visualTrackTypes,
+} from "@hypit/visual-track";
+import type { VisualClipSpec, MediaLayerSet, VisualSourceTimeSpec } from "@hypit/visual-track";
+import type { NarrativeMomentRef, NarrativeSelectionRef } from "@hypit/narrative";
+import type { BlobRef } from "@hypit/protocol";
+import { spatialTypes } from "@hypit/spatial";
+import { svsRecipeType } from "@hypit/svs";
+import type { SvsRecipe } from "@hypit/svs";
+import type { StructuredElement, StructuredNode, SurfaceResolvedReference, MarkupAttributeValue } from "@hypit/markup";
+
+const space = sealTimeline({ id: "test-space", frameCount: 120, frameRate: { numerator: 30, denominator: 1 },
+});
+const canvas = {
+ widthPx: 1080,
+ heightPx: 1920,
+};
+const header = sealVisualTrackHeader({ id: "proof" });
+const semanticOptions = {
+ narrativeId: "script",
+ segments: [
+ { id: "opening", frameCount: 30 },
+ { id: "answer", frameCount: 60 },
+ { id: "ending", frameCount: 30 },
+ ],
+ anchors: [
+ { identity: "a", frame: 15 }, { identity: "b", frame: 45 },
+ { identity: "c", frame: 60 }, { identity: "d", frame: 105 },
+ ],
+} as const;
+const semantic = timelineFixture(space, semanticOptions);
+const narrativeProjection = narrativeProjectionFixture(semantic, semanticOptions);
+const source: BlobRef = {
+ kind: "blob",
+ resource: fixtureResource("media-track:still"),
+ size: 4_096,
+ mediaType: "image/png",
+};
+const extent = { widthPx: 800, heightPx: 800 };
+const frame = { xPx: 100, yPx: 200, widthPx: 400, heightPx: 300 };
+const fit = {
+ sizing: "contain" as const,
+ framePoint: { x: 0.5, y: 0.5 },
+ contentPoint: { x: 0.5, y: 0.5 },
+ offsetPx: { x: 0, y: 0 },
+ constraint: "bounded" as const,
+};
+const appearance = {
+ opacity: 1,
+ filter: { blurPx: 0, brightness: 1, contrast: 1, saturation: 1 },
+};
+
+type NarrativeWindowProjection = Parameters<typeof projectSelectionWindow>[0]["projection"];
+type TestVisualClipSpec = VisualClipSpec & { readonly projection: TemporalWindowProjection | NarrativeWindowProjection };
+const defaultClipProjection: TemporalWindowProjection = {
+ start: { ref: "timeline.start" }, end: { ref: "timeline.end" },
+};
+
+function clipSpec(overrides: Partial<TestVisualClipSpec> = {}): TestVisualClipSpec {
+ const { projection = defaultClipProjection, ...clipOverrides } = overrides;
+ return {
+ ...sealVisualClipSpec({
+
+ id: "product",
+ treatment: {
+ clip: { kind: "rounded", radiusPx: 20 },
+ padding: { topPx: 10, rightPx: 10, bottomPx: 10, leftPx: 10 },
+ border: { widthPx: 2, style: "solid", color: "#ffffff" },
+ shadows: [{ offsetX: 0, offsetY: 8, blurPx: 20, spreadPx: 0, color: "#00000080" }],
+ },
+ z: 40,
+ ...clipOverrides,
+ }),
+ projection,
+ };
+}
+
+function appendProgramVisualClip(
+ set: ReturnType<typeof createVisualTrackSet>, trackHeader: typeof header, timeline: typeof semantic,
+ layers: MediaLayerSet, frameValue: typeof frame, authored: VisualClipSpec | TestVisualClipSpec,
+) {
+ const projection = "projection" in authored ? authored.projection : defaultClipProjection;
+ const { projection: _ignored, ...spec } = authored as TestVisualClipSpec;
+ return appendVisualClip(set, trackHeader, space, layers, frameValue, spec,
+ projectProgramWindow({ itemId: spec.id, semantic: timeline, projection: projection as TemporalWindowProjection }));
+}
+
+function appendSelectionVisualClip(
+ set: ReturnType<typeof createVisualTrackSet>, trackHeader: typeof header, timeline: typeof semantic,
+ layers: MediaLayerSet, frameValue: typeof frame, selection: NarrativeSelectionRef,
+ authored: TestVisualClipSpec,
+) {
+ const { projection, ...spec } = authored;
+ return appendVisualClip(set, trackHeader, space, layers, frameValue, spec,
+ projectSelectionWindow({ itemId: spec.id, semantic: timeline, narrative: narrativeProjection, selection,
+ projection: projection as NarrativeWindowProjection }));
+}
+
+function appendSegmentVisualClip(
+ set: ReturnType<typeof createVisualTrackSet>, trackHeader: typeof header, timeline: typeof semantic,
+ layers: MediaLayerSet, frameValue: typeof frame, segment: { narrativeId: string; kind: "segment"; id: string; tokenStart: number; tokenEndExclusive: number },
+ authored: TestVisualClipSpec,
+) {
+ const { projection, ...spec } = authored;
+ return appendVisualClip(set, trackHeader, space, layers, frameValue, spec,
+ projectSegmentWindow({ itemId: spec.id, semantic: timeline, narrative: narrativeProjection, segment,
+ projection: projection as NarrativeWindowProjection }));
+}
+
+function appendMomentVisualClip(
+ set: ReturnType<typeof createVisualTrackSet>, trackHeader: typeof header, timeline: typeof semantic,
+ layers: MediaLayerSet, frameValue: typeof frame, moment: NarrativeMomentRef,
+ authored: TestVisualClipSpec,
+) {
+ const { projection, ...spec } = authored;
+ return appendVisualClip(set, trackHeader, space, layers, frameValue, spec,
+ projectMomentWindow({ itemId: spec.id, semantic: timeline, narrative: narrativeProjection, moment,
+ projection: projection as NarrativeWindowProjection }));
+}
+
+function stillLayers(): MediaLayerSet {
+ let layers = createMediaLayerSet();
+ layers = appendMediaPaintLayer(layers, sealMediaPaintLayerSpec({
+
+ id: "backing",
+ paint: { kind: "linear-gradient", angleDeg: 90, stops: [
+ { offset: 0, color: "#101010" }, { offset: 1, color: "#303030" },
+ ] },
+ opacity: 1,
+ }));
+ layers = appendStillMediaLayer(layers, source, extent, fit, sealMediaSampleLayerSpec({
+
+ id: "content",
+ appearance,
+ }));
+ return layers;
+}
+
+function timed(id = "timed", withAudio = true): SynchronizedMedia {
+ const sampleFrames = 96_000;
+ return {
+ frameDomain: {
+ frameRate: { numerator: 30, denominator: 1 },
+ frameCount: 60,
+ },
+ visual: {
+ artifact: { kind: "blob", resource: fixtureResource(`video:${id}`), size: 10_000, mediaType: "video/mp4" },
+ width: 720,
+ height: 1280,
+ },
+ ...(withAudio ? { audio: {
+ artifact: { kind: "blob" as const, resource: fixtureResource(`audio:${id}`), size: sampleFrames * 4, mediaType: "audio/wav" },
+ } } : {}),
+ };
+}
+
+function timedLayers(id: string, withAudio = true): MediaLayerSet {
+ return appendTimedMediaLayer(createMediaLayerSet(), timed(id, withAudio), fit, sealMediaSampleLayerSpec({
+
+ id: "video",
+ sourceTime: loopSourceTime(),
+ appearance,
+ }));
+}
+
+const startPoint = (offsetFrames = 0) => ({ edge: "start" as const, offsetFrames });
+const endPoint = (offsetFrames = 0) => ({ edge: "end" as const, offsetFrames });
+const fullBounds = () => ({ from: startPoint(), until: endPoint() });
+
+function loopSourceTime(): VisualSourceTimeSpec {
+ return { relations: [{
+ kind: "rate",
+ target: fullBounds(),
+ targetAt: startPoint(),
+ sourceAt: startPoint(),
+ rate: { numerator: 1, denominator: 1 },
+ source: fullBounds(),
+ wrap: fullBounds(),
+ }] };
+}
+
+test("a Clip keeps ordered Paint/sample layers, two-frame fit and frame treatment package-owned", () => {
+ const program = finalizeVisualTrack(appendProgramVisualClip(
+ createVisualTrackSet(), header, semantic, stillLayers(), frame, clipSpec(),
+ ), header, space);
+ assert.deepEqual(program.clips[0]?.span, { startFrame: 0, endFrameExclusive: 120 });
+ assert.deepEqual(program.clips[0]?.layers.map((layer) => layer.id), ["backing", "content"]);
+ const track = projectVisualTrack(space, program);
+ assert.deepEqual({ order: track.presents[0]?.order, z: track.presents[0]?.z }, { order: 0, z: 40 });
+ const elements = track.presents[0]!.elements;
+ assert.deepEqual(elements.slice(0, 3).map((element) => element.id), [
+ "product:placement", "product:pose", "product:frame",
+ ]);
+ const media = elements.find((element) => element.id === "content");
+ assert.equal(media?.kind, "image");
+ const sample = program.clips[0]!.layers.find((layer) => layer.kind === "sample");
+ assert.deepEqual(sample?.kind === "sample" ? sample.mapping : undefined,
+ { xx: 0.345, xy: 0, yx: 0, yy: 0.345, tx: 162, ty: 212 });
+ const sampling = elements.find((element) => element.id === "content:sampling");
+ assert.deepEqual(sampling?.style, [
+ { name: "height", value: "100%" },
+ { name: "left", value: 0 },
+ { name: "position", value: "absolute" },
+ { name: "top", value: 0 },
+ { name: "transform-origin", value: "200px 150px" },
+ { name: "width", value: "100%" },
+ ]);
+ const mapping = elements.find((element) => element.id === "content:mapping");
+ assert.deepEqual(mapping?.style, [
+ { name: "height", value: "800px" },
+ { name: "left", value: 0 },
+ { name: "position", value: "absolute" },
+ { name: "top", value: 0 },
+ { name: "transform", value: "matrix(0.345,0,0,0.345,62,12)" },
+ { name: "transform-origin", value: "0 0" },
+ { name: "width", value: "800px" },
+ ]);
+});
+
+test("an owned clip path is an explicit Visual input and lowers only over the Clip's pixels", () => {
+ // A Path is drawn in program-picture pixels. The Frame
+ // sits at 100,200, so a trapezoid filling it is written from there and arrives at the Frame's own
+ // box translated back to 0,0.
+ const clipped = bindVisualClipPath(clipSpec(), {
+ commands: [
+ { kind: "move", xPx: 100, yPx: 200 },
+ { kind: "line", xPx: 500, yPx: 200 },
+ { kind: "line", xPx: 460, yPx: 500 },
+ { kind: "line", xPx: 140, yPx: 500 },
+ { kind: "close" },
+ ],
+ });
+ const track = projectVisualTrack(space, finalizeVisualTrack(appendProgramVisualClip(
+ createVisualTrackSet(), header, semantic, stillLayers(), frame, clipped,
+ ), header, space));
+ const frameElement = track.presents[0]!.elements.find((element) => element.id.endsWith(":frame"));
+ assert.equal(frameElement?.style.find((entry) => entry.name === "clip-path")?.value,
+ 'path("M 0 0 L 400 0 L 360 300 L 40 300 Z")');
+});
+
+test("an explicit source mapping survives Program resolution and renderer lowering without becoming a content box", () => {
+ const mapping = { xx: 0, xy: -0.5, yx: 0.5, yy: 0, tx: 420, ty: 240 };
+ const layers = appendMappedStillMediaLayer(
+ createMediaLayerSet(), source, extent, mapping,
+ sealMediaSampleLayerSpec({ id: "mapped", appearance }),
+ );
+ const program = finalizeVisualTrack(appendProgramVisualClip(
+ createVisualTrackSet(), header, semantic, layers, frame,
+ clipSpec({ treatment: { clip: { kind: "frame" }, padding: { topPx: 0, rightPx: 0, bottomPx: 0, leftPx: 0 }, shadows: [] } }),
+ ), header, space);
+ const sample = program.clips[0]!.layers.find((layer) => layer.kind === "sample");
+ assert.deepEqual(sample?.kind === "sample" ? sample.mapping : undefined, mapping);
+ const rendered = projectVisualTrack(space, program);
+ const element = rendered.presents[0]!.elements.find((candidate) => candidate.id === "mapped:mapping");
+ assert.ok(element?.style.some((entry) => entry.name === "transform"
+ && entry.value === "matrix(0,0.5,-0.5,0,320,40)"));
+});
+
+test("self-blur is two explicit samples of one Resource and collection keeps one reference", () => {
+ let layers = createMediaLayerSet();
+ layers = appendStillMediaLayer(layers, source, extent, { ...fit, sizing: "cover" }, sealMediaSampleLayerSpec({
+ id: "blurred", appearance: {
+ opacity: 1, filter: { blurPx: 24, brightness: 0.7, contrast: 1, saturation: 0.8 },
+ },
+ }));
+ layers = appendStillMediaLayer(layers, source, extent, fit, sealMediaSampleLayerSpec({
+ id: "foreground", appearance,
+ }));
+ const track = projectVisualTrack(space, finalizeVisualTrack(appendProgramVisualClip(
+ createVisualTrackSet(), header, semantic, layers, frame, clipSpec(),
+ ), header, space));
+ const document = compileHyperframesDocument(sealComposition({
+ id: "media",
+ canvas: { width: 1080, height: 1920, clearColor: "#000000" },
+ tracks: [track],
+ }), space);
+ assert.equal(document.artifacts.length, 1);
+ assert.equal((document.html.match(new RegExp(source.resource, "gu")) ?? []).length, 2,
+ "HTML names the same declared Resource at both sampling sites");
+ assert.equal((document.html.match(/hypit-resource:\/\/res_/gu) ?? []).length, 2);
+ const blurAppearance = track.presents[0]!.elements.find((element) => element.id === "blurred:appearance");
+ assert.equal(blurAppearance?.style.find((entry) => entry.name === "filter")?.value,
+ "blur(24px) brightness(0.7) saturate(0.8)");
+ const blurred = track.presents[0]!.elements.find((element) => element.id === "blurred");
+ assert.equal(blurred?.style.find((entry) => entry.name === "left")?.value, "-103px");
+ assert.equal(blurred?.style.find((entry) => entry.name === "top")?.value, "-103px");
+});
+
+test("piecewise source time, Clip pose and picture sampling remain separate wrapper channels", () => {
+ let layers = createMediaLayerSet();
+ layers = appendTimedMediaLayer(layers, timed(), fit, sealMediaSampleLayerSpec({
+
+ id: "video",
+ sourceTime: { relations: [
+ {
+ kind: "rate",
+ target: { from: startPoint(), until: startPoint(30) },
+ targetAt: startPoint(),
+ sourceAt: startPoint(10),
+ rate: { numerator: 1, denominator: 1 },
+ source: { from: startPoint(10), until: startPoint(40) },
+ },
+ {
+ kind: "rate",
+ target: { from: startPoint(30), until: endPoint() },
+ targetAt: startPoint(30),
+ sourceAt: startPoint(39),
+ rate: { numerator: 0, denominator: 1 },
+ source: { from: startPoint(10), until: startPoint(40) },
+ },
+ ] },
+ appearance,
+ samplingMotion: { keyframes: [
+ { atProgress: 0, zoom: 1, offsetX: 0, offsetY: 0, rotationDeg: 0 },
+ { atProgress: 0.5, zoom: 1.1, offsetX: 10, offsetY: -5, rotationDeg: 1 },
+ { atProgress: 1, zoom: 1.2, offsetX: 20, offsetY: -10, rotationDeg: 2, easing: "ease-out" },
+ ] },
+ }));
+ const program = finalizeVisualTrack(appendProgramVisualClip(createVisualTrackSet(), header, semantic, layers, frame, clipSpec({
+ motion: {
+ keyframes: [
+ { at: { kind: "start", offsetFrames: 0 }, translateX: 0, translateY: 120, scaleX: 1, scaleY: 1,
+ rotationDeg: 0, opacity: 0, originX: 0.5, originY: 0.5, easing: "ease-out" },
+ { at: { kind: "start", offsetFrames: 12 }, translateX: 0, translateY: 0, scaleX: 1, scaleY: 1,
+ rotationDeg: 0, opacity: 1, originX: 0.5, originY: 0.5 },
+ { at: { kind: "end", offsetFrames: -10 }, translateX: 0, translateY: 0, scaleX: 1, scaleY: 1,
+ rotationDeg: 0, opacity: 1, originX: 0.5, originY: 0.5, easing: "ease-in" },
+ { at: { kind: "end", offsetFrames: 0 }, translateX: 0, translateY: 0, scaleX: 1, scaleY: 1,
+ rotationDeg: 0, opacity: 0, originX: 0.5, originY: 0.5 },
+ ],
+ },
+ })), header, space);
+ const elements = projectVisualTrack(space, program).presents[0]!.elements;
+ assert.ok(elements.find((element) => element.id.endsWith(":pose"))?.animation);
+ const samplingWrapper = elements.find((element) => element.id === "video:sampling");
+ assert.ok(samplingWrapper?.animation);
+ assert.deepEqual(samplingWrapper?.animation?.keyframes.map((entry) => entry.atFrame), [0, 60, 120]);
+ const video = elements.find((element) => element.id === "video");
+ assert.equal(video?.kind, "video");
+ assert.deepEqual(video.kind === "video" ? video.sourceTime?.pieces : undefined, [
+ { target: { startFrame: 0, endFrameExclusive: 30 }, sourceAtStart: { numerator: 10, denominator: 1 }, rate: { numerator: 1, denominator: 1 } },
+ { target: { startFrame: 30, endFrameExclusive: 120 }, sourceAtStart: { numerator: 39, denominator: 1 }, rate: { numerator: 0, denominator: 1 } },
+ ]);
+});
+
+test("Visual Track discards the audio member of synchronized media and exposes no audio facet", () => {
+ const layers = appendTimedMediaLayer(createMediaLayerSet(), timed("with-audio"), fit, sealMediaSampleLayerSpec({
+ id: "video", appearance,
+ }));
+ const program = finalizeVisualTrack(appendProgramVisualClip(
+ createVisualTrackSet(), header, semantic, layers, frame, clipSpec(),
+ ), header, space);
+ const sample = program.clips[0]!.layers[0]!;
+ assert.equal(sample.kind, "sample");
+ assert.equal(sample.kind === "sample" && "audio" in sample.source, false);
+ assert.equal(projectVisualTrack(space, program).presents.length, 1);
+ const trackSurface = visualTrackMarkupSurfaces.find((surface) => surface.name === "track")!;
+ assert.equal(trackSurface.outputs.some((type) => type.name === "AudioTrack"), false);
+});
+
+test("still and animated typed Surfaces use the same layer law without browser format guesses", () => {
+ const still: CompositableSurfaceRef = {
+ artifact: { kind: "blob", resource: fixtureResource("surface:still"), size: 500, mediaType: "image/png" },
+ width: 100,
+ height: 100,
+ colorSpace: "srgb",
+ alphaMode: "straight",
+ timing: { kind: "still" },
+ };
+ const animated: CompositableSurfaceRef = {
+ ...still,
+ artifact: { kind: "blob", resource: fixtureResource("surface:animated"), size: 2_000, mediaType: "video/webm" },
+ timing: { kind: "frames", frameRate: { numerator: 30, denominator: 1 }, frameCount: 30 },
+ };
+ let layers = appendSurfaceMediaLayer(createMediaLayerSet(), still, fit, sealMediaSampleLayerSpec({
+ id: "still", appearance,
+ }));
+ layers = appendSurfaceMediaLayer(layers, animated, fit, sealMediaSampleLayerSpec({
+ id: "animated", sourceTime: loopSourceTime(), appearance,
+ }));
+ const elements = projectVisualTrack(space, finalizeVisualTrack(appendProgramVisualClip(
+ createVisualTrackSet(), header, semantic, layers, frame, clipSpec(),
+ ), header, space)).presents[0]!.elements;
+ assert.equal(elements.find((element) => element.id === "still")?.kind, "surface");
+ const moving = elements.find((element) => element.id === "animated");
+ assert.equal(moving?.kind, "surface");
+ assert.ok(moving?.kind === "surface" && moving.sourceTime !== undefined);
+ const defaulted = appendSurfaceMediaLayer(createMediaLayerSet(), animated, fit, sealMediaSampleLayerSpec({
+ id: "defaulted", appearance,
+ }));
+ assert.equal(defaulted.layers[0]?.kind === "sample" ? defaulted.layers[0].sourceTime?.kind : undefined, "spec");
+ assert.deepEqual(defaulted.layers[0]?.kind === "sample" && defaulted.layers[0].sourceTime?.kind === "spec"
+ ? defaulted.layers[0].sourceTime.value.relations : undefined, [{
+ kind: "rate",
+ target: fullBounds(),
+ targetAt: startPoint(),
+ sourceAt: startPoint(),
+ rate: { numerator: 1, denominator: 1 },
+ source: fullBounds(),
+ }]);
+});
+
+test("Visual Clips consume independent absolute Windows without becoming an exclusive lane", () => {
+ const selection: NarrativeSelectionRef = {
+ narrativeId: "script",
+ id: "mentions",
+ startAnchorId: "a",
+ endAnchorId: "b",
+ };
+ const selected = appendSelectionVisualClip(createVisualTrackSet(), header, semantic, stillLayers(), frame,
+ selection, clipSpec({
+ id: "mention",
+ projection: { start: { ref: "selection.start" }, end: { ref: "selection.end" } },
+ }));
+ assert.deepEqual(selected.clips.map((item) => item.span), [{ startFrame: 15, endFrameExclusive: 45 }]);
+ const moment: NarrativeMomentRef = {
+ narrativeId: "script",
+ id: "cue", anchorId: "b",
+ };
+ const overlapping = appendMomentVisualClip(selected, header, semantic, stillLayers(), frame,
+ moment, clipSpec({
+ id: "popup",
+ projection: { start: { ref: "moment.cue", offset: { unit: "frames", value: -10 } }, end: { ref: "moment.cue", offset: { unit: "frames", value: 20 } } },
+ z: 41,
+ }));
+ assert.deepEqual(overlapping.clips[1]?.span, { startFrame: 35, endFrameExclusive: 65 });
+ const track = projectVisualTrack(space, finalizeVisualTrack(overlapping, header, space));
+ assert.deepEqual(track.presents.map((present) => present.z), [40, 41]);
+
+ const absolute = appendProgramVisualClip(
+ createVisualTrackSet(), header, semantic, stillLayers(), frame,
+ clipSpec({
+ id: "absolute",
+ projection: {
+ start: { ref: "absolute", at: { unit: "frames", value: 7 } },
+ end: { ref: "absolute", at: { unit: "frames", value: 19 } },
+ },
+ }),
+ );
+ assert.deepEqual(absolute.clips[0]?.span, { startFrame: 7, endFrameExclusive: 19 });
+});
+
+test("overlapping Clips may share z and retain their authored local order", () => {
+ const first = appendProgramVisualClip(
+ createVisualTrackSet(), header, semantic, stillLayers(), frame,
+ clipSpec({ id: "first", projection: {
+ start: { ref: "absolute", at: { unit: "frames", value: 10 } },
+ end: { ref: "absolute", at: { unit: "frames", value: 40 } },
+ } }),
+ );
+ const second = appendProgramVisualClip(
+ first, header, semantic, stillLayers(), frame,
+ clipSpec({ id: "second", projection: {
+ start: { ref: "absolute", at: { unit: "frames", value: 30 } },
+ end: { ref: "absolute", at: { unit: "frames", value: 50 } },
+ } }),
+ );
+ const program = finalizeVisualTrack(second, header, space);
+ assert.deepEqual(program.clips.map(({ order, z }) => ({ order, z })), [
+ { order: 0, z: 40 }, { order: 1, z: 40 },
+ ]);
+});
+
+test("a Visual Clip can consume one whole Narrative Segment without a synthetic Selection", () => {
+ const result = appendSegmentVisualClip(
+ createVisualTrackSet(), header, semantic, stillLayers(), frame,
+ { narrativeId: "script", kind: "segment", id: "answer", tokenStart: 0, tokenEndExclusive: 1 },
+ clipSpec({
+ id: "whole-answer",
+ projection: { start: { ref: "segment.start" }, end: { ref: "segment.end" } },
+ }),
+ );
+ assert.deepEqual(result.clips.map((item) => item.span), [{ startFrame: 30, endFrameExclusive: 90 }]);
+});
+
+test("typed Pose motion lowers arbitrary affine states without an effect catalogue or outer Frame", () => {
+ const animation = poseAnimation({ keyframes: [
+ { at: { kind: "start", offsetFrames: 0 }, translateX: -500, translateY: 20, scaleX: 0.8, scaleY: 1.1,
+ rotationDeg: -12, opacity: 0, originX: 0.5, originY: 0.5, easing: "ease-out" },
+ { at: { kind: "progress", value: 0.5 }, translateX: 18, translateY: -4, scaleX: 1.04, scaleY: 0.98,
+ rotationDeg: 2, opacity: 1, originX: 0.5, originY: 0.5, easing: "ease-in-out" },
+ { at: { kind: "end", offsetFrames: 0 }, translateX: 0, translateY: 0, scaleX: 1, scaleY: 1,
+ rotationDeg: 0, opacity: 1, originX: 0.5, originY: 0.5 },
+ ] }, 30)!;
+ assert.deepEqual(animation.keyframes.map((entry) => entry.atFrame), [0, 15, 30]);
+ assert.match(String(animation.keyframes[0]!.style.find((item) => item.name === "transform")?.value), /translate\(-500px,20px\)/u);
+});
+
+test("every documented Visual frame and fit remains one ordinary Clip instead of a mode", () => {
+ const frames = [
+ { xPx: 0, yPx: 0, widthPx: 1080, heightPx: 1920 },
+ { xPx: 0, yPx: 0, widthPx: 540, heightPx: 1920 },
+ { xPx: 80, yPx: 1280, widthPx: 920, heightPx: 500 },
+ { xPx: 760, yPx: 80, widthPx: 260, heightPx: 360 },
+ { xPx: -120, yPx: 1400, widthPx: 500, heightPx: 600 },
+ ];
+ const sizings = ["contain", "cover", "fit-width", "fit-height", "native", "scale-down", "stretch"] as const;
+ let set = createVisualTrackSet();
+ for (const [index, sizing] of sizings.entries()) {
+ const localFit = { ...fit, sizing,
+ framePoint: { x: index % 2 === 0 ? 0.2 : 0.8, y: 0.75 },
+ contentPoint: { x: 0.65, y: 0.1 },
+ constraint: index % 2 === 0 ? "bounded" as const : "free" as const,
+ };
+ const layers = appendStillMediaLayer(createMediaLayerSet(), source,
+ { widthPx: index % 3 === 0 ? 400 : index % 3 === 1 ? 1200 : 800,
+ heightPx: index % 3 === 0 ? 1200 : index % 3 === 1 ? 400 : 800 },
+ localFit, sealMediaSampleLayerSpec({ id: `sample-${index}`, appearance }));
+ set = appendProgramVisualClip(set, header, semantic, layers, frames[index % frames.length]!, clipSpec({
+ id: `fit-${sizing}`, z: 100 + index,
+ treatment: { clip: { kind: "none" }, padding: { topPx: 0, rightPx: 0, bottomPx: 0, leftPx: 0 }, shadows: [] },
+ }));
+ }
+ const track = projectVisualTrack(space, finalizeVisualTrack(set, header, space));
+ assert.equal(track.presents.length, sizings.length);
+ for (const present of track.presents) {
+ const placement = present.elements[0]!;
+ assert.equal(placement.kind, "box");
+ assert.ok(placement.style.some((entry) => entry.name === "width" && typeof entry.value === "string"));
+ assert.ok(placement.style.some((entry) => entry.name === "height" && typeof entry.value === "string"));
+ }
+});
+
+test("transparent, Paint, self-blur and alternate-source backing are only ordered owned layers", () => {
+ const alternate: BlobRef = { kind: "blob", resource: fixtureResource("media-track:alternate"), size: 2_048, mediaType: "image/webp" };
+ let layers = createMediaLayerSet();
+ layers = appendMediaPaintLayer(layers, sealMediaPaintLayerSpec({
+ id: "solid", paint: { kind: "solid", color: "#101018" }, opacity: 1,
+ }));
+ layers = appendStillMediaLayer(layers, source, extent, { ...fit, sizing: "cover" }, sealMediaSampleLayerSpec({
+ id: "self-blur", appearance: {
+ opacity: 1, filter: { blurPx: 32, brightness: 0.7, contrast: 1.1, saturation: 0.8 },
+ },
+ }));
+ layers = appendStillMediaLayer(layers, alternate, { ...extent, widthPx: 1200, heightPx: 600 }, { ...fit, sizing: "cover" },
+ sealMediaSampleLayerSpec({ id: "alternate", appearance }));
+ layers = appendStillMediaLayer(layers, source, extent, fit,
+ sealMediaSampleLayerSpec({ id: "foreground", appearance }));
+ const track = projectVisualTrack(space, finalizeVisualTrack(appendProgramVisualClip(
+ createVisualTrackSet(), header, semantic, layers, frame, clipSpec(),
+ ), header, space));
+ const document = compileHyperframesDocument(sealComposition({
+ id: "layer-matrix", canvas: { width: 1080, height: 1920, clearColor: "#000000" }, tracks: [track],
+ }), space);
+ assert.deepEqual(track.presents[0]!.elements.filter((element) => element.kind === "image").map((element) => element.id),
+ ["self-blur", "alternate", "foreground"]);
+ assert.equal(document.artifacts.length, 2, "repeated samples share bytes while the alternate source remains explicit");
+
+ const transparent = projectVisualTrack(space, finalizeVisualTrack(appendProgramVisualClip(
+ createVisualTrackSet(), header, semantic,
+ appendStillMediaLayer(createMediaLayerSet(), source, extent, fit,
+ sealMediaSampleLayerSpec({ id: "only", appearance })),
+ frame, clipSpec(),
+ ), header, space));
+ assert.equal(transparent.presents[0]!.elements.some((element) =>
+ element.kind === "box" && element.style.some((entry) => entry.name === "background")), false);
+});
+
+test("timed visual sources remain visual whether normalized media has audio or not", () => {
+ const silent = timedLayers("silent", false);
+ const program = finalizeVisualTrack(appendProgramVisualClip(
+ createVisualTrackSet(), header, semantic, silent, frame, clipSpec(),
+ ), header, space);
+ assert.equal(projectVisualTrack(space, program).presents[0]!.elements.some((element) => element.kind === "video"), true);
+ const audible = timedLayers("audible", true).layers[0]!;
+ assert.equal(audible.kind === "sample" && "audio" in audible.source, false);
+});
+
+test("visual source-time relations resolve partial identity, alignment, wrap, fit and reverse exactly", () => {
+ const resolve = (spec?: VisualSourceTimeSpec) => resolveVisualSourceTime({
+ timeline: space,
+ sourceFrameRate: { numerator: 30, denominator: 1 },
+ sourceFrameCount: 30,
+ targetFrameCount: 50,
+ ...(spec === undefined ? {} : { spec }),
+ });
+ assert.deepEqual(resolve().pieces.map((item) => item.target), [{ startFrame: 0, endFrameExclusive: 30 }]);
+ const endAligned: VisualSourceTimeSpec = { relations: [{
+ kind: "rate", target: fullBounds(), targetAt: endPoint(), sourceAt: endPoint(),
+ rate: { numerator: 1, denominator: 1 }, source: fullBounds(),
+ }] };
+ assert.deepEqual(resolve(endAligned).pieces.map((item) => item.target), [{ startFrame: 20, endFrameExclusive: 50 }]);
+ assert.deepEqual(resolve({ relations: [{
+ kind: "rate", target: fullBounds(), targetAt: endPoint(), sourceAt: endPoint(),
+ rate: { numerator: 1, denominator: 1 }, source: fullBounds(), wrap: fullBounds(),
+ }] })
+ .pieces[0]?.sourceAtStart, { numerator: 10, denominator: 1 });
+ assert.deepEqual(resolve({ relations: [{ kind: "fit", target: fullBounds(), source: fullBounds() }] })
+ .pieces[0]?.rate, { numerator: 3, denominator: 5 });
+ assert.deepEqual(resolve({ relations: [{
+ kind: "rate", target: fullBounds(), targetAt: startPoint(), sourceAt: endPoint(-1),
+ rate: { numerator: -1, denominator: 1 }, source: fullBounds(),
+ }] }).pieces[0], {
+ target: { startFrame: 0, endFrameExclusive: 30 },
+ sourceAtStart: { numerator: 29, denominator: 1 },
+ rate: { numerator: -1, denominator: 1 },
+ });
+ assert.throws(() => resolveVisualSourceTime({
+ timeline: space, sourceFrameRate: { numerator: 24, denominator: 1 }, sourceFrameCount: 24, targetFrameCount: 30,
+ }), /normalized to Timeline frame rate/u);
+});
+
+test("the graph keeps every source, extent, fit, frame, time and treatment input explicit", () => {
+ assert.deepEqual(stillVisualTrackFragment.inputs.map((input) => input.name), [
+ "clip-spec", "extent", "fit", "frame", "header", "sample-spec", "source", "timeline", "window",
+ ]);
+});
+
+test("the Visual author Surface emits explicit graph edges for layers, absolute time and Clip layers", async () => {
+ const range = { source: "media-surface.svml", start: 0, end: 1 };
+ const ref = (path: string): MarkupAttributeValue => ({ kind: "reference", path });
+ const node = (name: string, attributes: Record<string, MarkupAttributeValue>, children: StructuredNode[] = []): StructuredElement => ({
+ kind: "element", name, attributes, children, range,
+ });
+ const appearance = (path: string, properties: SvsRecipe["properties"]): SurfaceResolvedReference => ({
+ path,
+ ref: { kind: "record", id: path },
+ type: svsRecipeType,
+ record: { value: { kind: "inline", value: { path, properties } } } as never,
+ });
+ const plain = (path: string, type: SurfaceResolvedReference["type"]): SurfaceResolvedReference => ({
+ path, ref: { kind: "record", id: path }, type,
+ });
+ const references = new Map<string, SurfaceResolvedReference>([
+ ["semantic", plain("semantic", timelineTypes.track)],
+ ["frame", plain("frame", spatialTypes.frame)],
+ ["mapping", plain("mapping", spatialTypes.map2D)],
+ ["clip-path", plain("clip-path", spatialTypes.path)],
+ ["still", plain("still", artifactTypes.blob)],
+ ["extent", plain("extent", spatialTypes.extent)],
+ ["video", plain("video", mediaTypes.synchronized)],
+ ["surface", plain("surface", mediaTypes.compositableSurface)],
+ ["selection", plain("selection", temporalTypes.window)],
+ ["answer-segment", plain("answer-segment", temporalTypes.window)],
+ ["still-style", appearance("still-style", {})],
+ ["card-style", appearance("card-style", { clip: "frame", "frame-paint": "#111111" })],
+ ["surface-style", appearance("surface-style", {})],
+ ["motion", plain("motion", visualTrackTypes.motion)],
+ ]);
+ const root = node("visual:Track", { id: "editorial", timeline: ref("semantic") }, [
+ node("visual:Clip", { id: "still-card", image: ref("still"), extent: ref("extent"), frame: ref("frame"), clip: ref("clip-path"), treatment: ref("still-style"), z: "20", fit: "contain", during: "timeline" }),
+ node("visual:Clip", { id: "segment-card", image: ref("still"), extent: ref("extent"), frame: ref("frame"), mapping: ref("mapping"), treatment: ref("still-style"), z: "21", during: ref("answer-segment") }),
+ node("visual:Clip", { id: "proof", media: ref("video"), frame: ref("frame"), treatment: ref("card-style"), motion: ref("motion"), z: "30", fit: "cover", during: ref("selection") }, [
+ node("visual:Map", { rate: "1", "wrap-from": "start", "wrap-until": "end" }),
+ node("visual:Sampling", { at: "start", zoom: "1" }),
+ node("visual:Sampling", { at: "end", zoom: "1.1", y: "-10", easing: "ease-out" }),
+ ]),
+ node("visual:Clip", { image: ref("still"), extent: ref("extent"), id: "presenter", frame: ref("frame"), clip: ref("clip-path"), treatment: ref("still-style"), z: "31", during: ref("answer-segment") }, [
+ node("visual:Sampling", { at: "start", zoom: "1" }),
+ node("visual:Sampling", { at: "end", zoom: "1.08", x: "6" }),
+ node("visual:Pose", { at: "start", opacity: "0" }),
+ node("visual:Pose", { at: "end", opacity: "1" }),
+ ]),
+ node("visual:Clip", { image: ref("still"), extent: ref("extent"), id: "inset", frame: ref("frame"), treatment: ref("still-style"), z: "32", from: "12f", for: "2s" }),
+ node("visual:Clip", { surface: ref("surface"), id: "alpha-overlay", frame: ref("frame"), treatment: ref("surface-style"), z: "35", fit: "cover", during: "timeline" }, [
+ node("visual:Map", { rate: "1", "wrap-from": "start", "wrap-until": "end" }),
+ ]),
+ ]);
+ const result = await decodeVisualTrackSurface({
+ sourceName: "media-surface.svml",
+ element: root,
+ resolveReference: (path) => references.get(path),
+ resolveAsset: async () => { throw new Error("no asset resolution expected"); },
+ });
+ const component = result.components.find((candidate) => candidate.outputs.visual !== undefined);
+ assert.ok(component !== undefined);
+ assert.deepEqual(Object.keys(component.outputs).sort(), ["program", "visual"]);
+ const fragment = result.fragments.find((candidate) => candidate.exports.some((output) => output.name === "visual"))!;
+ const producers = fragment.operations.map((entry) => entry.producer.name);
+ assert.ok(producers.includes("append-still-media-layer"));
+ assert.ok(producers.includes("append-mapped-still-media-layer"));
+ assert.ok(producers.includes("append-visual-clip"));
+ assert.ok(producers.includes("append-timed-media-layer"));
+ assert.ok(producers.includes("append-surface-media-layer"));
+ assert.ok(producers.includes("bind-visual-clip-path"));
+ assert.ok(producers.includes("bind-visual-clip-motion"));
+ assert.equal(result.fragments.some((candidate) => candidate.operations.some((operation) =>
+ operation.producer.module.name === "@hypit/narrative-temporal")), false);
+ assert.equal(producers.some((name) => name.includes("sound") || name.includes("audio")), false);
+ assert.ok(fragment.inputs.some((entry) => entry.type.name === artifactTypes.blob.name));
+ assert.ok(fragment.inputs.some((entry) => entry.type.name === mediaTypes.synchronized.name));
+ assert.ok(fragment.inputs.some((entry) => entry.type.name === spatialTypes.path.name));
+ const clipSpecs = result.records.filter((entry) => entry.type.name === "VisualClipSpec");
+ assert.equal(clipSpecs.length, 6);
+ assert.ok(visualTrackMarkupSurfaces.some((surface) => surface.name === "track"));
+});
diff --git a/packages/volcengine-matting/README.md b/packages/volcengine-matting/README.md
index cb92c3db..8eb740f6 100644
--- a/packages/volcengine-matting/README.md
+++ b/packages/volcengine-matting/README.md
@@ -16,41 +16,51 @@ formats. The service's flat-background MP4 option is a different output treatmen
## Prepare the processed clip for its role
```svml
-<import as="program" from="@hypit/program-space@1"/>
<import as="pipeline" from="@hypit/media-pipeline@1"/>
<import as="whisperx" from="@hypit/whisperx@1"/>
+<import as="semantic" from="@hypit/narrative-temporal@1"/>
+<import as="media" from="@hypit/media@1"/>
-<program:Clock id="clock" frame-rate="30"/>
+<time:Clock id="clock" frame-rate="30"/>
<pipeline:Normalize id="cutout-media" source={cutout.video} clock={clock}
video="primary-moving" audio="default" span-authority="video"/>
-<whisperx:SemanticTake id="opening-semantic" narrative={story}
- segment={story.segment.opening} media={cutout-media.media} language="en"/>
+<whisperx:Alignment id="opening-alignment" narrative={story}
+ segment={story.segment.opening} media={cutout-media.media}
+ domain={cutout-media.domain} language="en"/>
+<time:Timeline id="speech" clock={clock} end="opening.end">
+ <time:Window id="opening" from="start" for={cutout-media.extent}/>
+</time:Timeline>
+<semantic:Projection id="story-time" narrative={story} timeline={speech.timeline}>
+ <semantic:Map alignment={opening-alignment.alignment}
+ domain={cutout-media.domain} window={speech.opening}/>
+</semantic:Projection>
```
-This excerpt assumes the performance and Script exist. Normalize keeps the transparent picture
-and prepares the selected embedded audio on the program clock. WhisperX and semantic alignment
-associate that prepared performance with the Script. Use `opening-semantic.take` in
-[Timeline assembly](../timeline-author/README.md); its screen position and stack order are independent
-of its role as A-roll.
+This excerpt assumes the performance and Script exist. Normalize keeps the transparent picture and
+prepares the selected embedded audio. WhisperX associates the Script Segment with the media-local
+domain; Timeline uses its Extent while semantic projection consumes the equal-length domain/Window
+relation and then discards it. Use `cutout-media.media` with `during={speech.opening}` in independent
+Visual and Audio Clips. Screen position and stack order remain visual choices.
-For B-roll, normalize `cutout.video` with `audio="none"` when its sound is unwanted, then use
-`cutout-media.media` in [Media Track](../media-track/README.md). No SemanticTake is needed for
-that overlay. Existing transparency can enter Normalize directly.
+For independently timed footage, normalize `cutout.video` with `audio="none"` when its sound is
+unwanted, then use `cutout-media.media` in a [Visual Clip](../visual-track/README.md). No semantic
+alignment is needed for that overlay. Existing transparency can enter Normalize directly.
For example, this alternative uses the existing program's Timeline and an authored Selection:
```svml
-<import as="media-track" from="@hypit/media-track@1"/>
+<import as="visual" from="@hypit/visual-track@1"/>
<pipeline:Normalize id="overlay-media" source={cutout.video} clock={clock}
video="primary-moving" audio="none" span-authority="video"/>
-<media-track:Track id="overlay" timeline={speech.timeline} canvas={canvas}>
- <media-track:Item media={overlay-media.media} during={story.selection.example}
- frame={overlay-frame} appearance={look.media.overlay}/>
-</media-track:Track>
+<visual:Track id="overlay" timeline={speech.timeline}>
+ <visual:Clip media={overlay-media.media} during={story-time.example}
+ frame={overlay-frame} z="30" fit="contain" treatment={look.visual.overlay}/>
+</visual:Track>
```
-The Frame, Recipe and Selection belong to the composition. Add `overlay.visual` to Film and set
-its stacking order in the Recipe. The performance underneath continues to supply semantic time.
+The Frame, treatment Recipe and Selection belong to the composition. Add `overlay.visual` to Film;
+the Clip's direct `z` sets its stacking order. The performance underneath continues to supply
+semantic time.
The same processed clip can serve either role; matting does not choose its Track or timeline.
The local media Provider's Transform currently emits opaque MP4. When a clip also needs trimming
diff --git a/packages/whisperx/README.md b/packages/whisperx/README.md
index bbd25fd1..224c9a4d 100644
--- a/packages/whisperx/README.md
+++ b/packages/whisperx/README.md
@@ -1,63 +1,39 @@
-# @hypit/whisperx
+# `@hypit/whisperx`
-Explicit WhisperX model-family capability for the official speech program. Importing this package
-selects WhisperX; Runtime registration only binds the resulting alignment Need to a concrete
-execution endpoint. The default Hypit Skill path uses the HypiHub-hosted WhisperX endpoint; the
-trusted local worker remains an explicit deployment choice.
+Explicit WhisperX model-family capability for speech alignment. Importing this package selects
+WhisperX; Runtime registration binds the resulting evidence Need to a concrete Endpoint. The package
+contains no credentials, Python environment or queue.
-The package contains no credentials, Python environment or queue. Providers translate the typed
-request directly into provider-neutral `AlignedTranscriptEvidence`. There is no vendor-shaped
-Evidence wrapper or pass-through normalization node in the graph.
-
-`<whisperx:SemanticTake>` is the real-media semantic Surface. It consumes one normalized
-`SynchronizedMedia` and exactly one Script Segment. When that Segment contains Tokens, it also
-requires an explicit lowercase two- or three-letter language code, such as `language="ko"`.
-This package checks the code's form, not a cross-Provider support list. The language is passed directly to
-WhisperX; Script text and audio are not used to choose it implicitly. `@hypit/media-pipeline`
-projects the Take's audio to canonical 16 kHz mono `SpeechEvidenceAudio`; WhisperX sees only those
-bytes. A deterministic local alignment then combines the returned evidence with the Segment and
-emits one self-contained `SemanticTake`.
-
-For Chinese speech, select `zh` (also `hypit transcribe --language zh` for a reference). WhisperX's
-Chinese alignment emits character-sized words, including letters inside some Latin names. The
-evidence adapter preserves those windows; the local alignment maps them onto Script's units, so
-a complete Latin name can consume several evidence words while neighboring Han characters retain
-their own times. Caption gets its displayed wording and Cue breaks from Script, independently of
-the recognizer's punctuation or simplified/traditional spelling.
-
-When the authored Segment has no Tokens, write the same Surface without `language`. Its start and
-end Anchors map directly to the prepared media's first and final frame. There are no words to align,
-so this branch requests no evidence audio and no WhisperX capability:
+`<whisperx:Alignment>` consumes one normalized `SynchronizedMedia`, its `LocalTemporalDomain`, one
+authored Script Segment and the owning Narrative. For a Segment containing Tokens it also requires an
+explicit lowercase two- or three-letter language code. The provider receives canonical evidence audio
+tagged with the selected local domain identity and returns provider-neutral
+`AlignedTranscriptEvidence` preserving that identity and exact sample span; deterministic local alignment publishes one
+`NarrativeAlignment`:
```svml
-<whisperx:SemanticTake id="pause" narrative={story}
- segment={story.segment.pause} media={pause-media.media}/>
+<whisperx:Alignment id="opening" narrative={story}
+ segment={story.segment.opening}
+ media={opening-media.media} domain={opening-media.domain}
+ language="ko"/>
```
-There is no whole-program WhisperX pass. Timeline assembly only receives already-semantic Takes and later
-translates their local frames when assembling the final ProgramSpace and complete semantic map.
+The result is `opening.alignment`. It contains semantic timing on the media-local domain, not media,
+not a Timeline and not presentation policy. `@hypit/narrative-temporal` Projection explicitly combines
+one or more `NarrativeAlignment + LocalTemporalDomain + equal-length Window` relations for a chosen
+Timeline and publishes absolute values without a durable Placement product.
-`@hypit/provider-hypihub` is the default concrete adapter; it uploads the canonical evidence audio
-and requests verbose JSON with segment- and word-level timestamps. `@hypit/provider-whisperx-local`
-remains available as an explicit local deployment.
+When the Segment has no Tokens, omit `language`. Its start and end map directly to the local domain's
+first and final frame, no evidence audio or WhisperX capability is requested, and the same
+`NarrativeAlignment` type is published.
+For Chinese speech use `zh`. WhisperX may emit character-sized evidence units; local alignment maps
+them to Script's authored units while Caption continues to use Script's display wording and Cue breaks.
+The package validates only the language-code form; the selected Endpoint owns actual language support.
-## Language selection and local preparation
+## Local deployment
-```svml
-<whisperx:SemanticTake id="opening" narrative={story}
- segment={story.segment.opening} media={opening-media.media} language="ko"/>
-```
-
-The selected service owns which languages it can align. The local service uses its pinned WhisperX
-version's default language-to-alignment-model mapping: the author does not choose weight URLs in
-SVML. ASR size and hardware are separate deployment choices (`expectedModel`, `expectedDevice`,
-`expectedCompute`). A multilingual ASR such as `small` can serve Korean; an English-only `.en`
-model cannot and is rejected explicitly. Unknown alignment languages fail in the service without
-switching language, model family or Provider. Locale aliases such as `zh-CN`, language names and
-`auto` are not interpreted by this Surface; use the service's explicit code.
-
-For local execution, merge this into the existing Runtime Profile:
+`@hypit/provider-hypihub` is the normal hosted adapter. A local deployment may bind the same Need:
```json
{
@@ -73,22 +49,12 @@ For local execution, merge this into the existing Runtime Profile:
}
```
-`alignmentLanguages` declares resources to prepare on this machine. Each SVML `language` states
-what that particular Take uses; the preparation list never supplies an implicit author language.
-
```bash
hypit programs prepare --runtime hypit.runtime.json --endpoint whisperx.local
hypit runtime up --runtime hypit.runtime.json --endpoint whisperx.local
hypit build video.svrun --runtime hypit.runtime.json --follow
```
-The Run references the authored SVML. Preparation downloads missing resources without starting the
-service; `runtime up` prepares if needed and starts the helper and Worker. Build only uses prepared
-resources. Adding a language to the same cache requires preparation, not a service restart.
-See the [local Provider README](../provider-whisperx-local/README.md) for cache and hardware choices.
-Other Endpoints needed by the Run must also be prepared and available.
-
-For reference analysis rather than an authored SemanticTake, use the same language code with
-`hypit transcribe source.mp4 --language ko --to transcript.json --runtime hypit.runtime.json`.
-Hosted execution uses the selected hosted deployment's models and preparation; the local
-`alignmentLanguages` option does not configure a remote service.
+The Provider README owns model cache and hardware choices. For reference analysis rather than an
+authored alignment, use `hypit transcribe source.mp4 --language ko --to transcript.json` with the
+selected Runtime.
diff --git a/packages/whisperx/package.json b/packages/whisperx/package.json
index fd25a7d0..1a74c6e9 100644
--- a/packages/whisperx/package.json
+++ b/packages/whisperx/package.json
@@ -16,13 +16,14 @@
"@hypit/media-pipeline": "workspace:*",
"@hypit/media": "workspace:*",
"@hypit/narrative": "workspace:*",
+ "@hypit/narrative-temporal": "workspace:*",
"@hypit/protocol": "workspace:*",
- "@hypit/speech": "workspace:*",
"@hypit/speech-alignment": "workspace:*",
"@hypit/speech-evidence": "workspace:*",
- "@hypit/markup": "workspace:*"
+ "@hypit/markup": "workspace:*",
+ "@hypit/temporal": "workspace:*"
},
"devDependencies": {
- "@hypit/program-space": "workspace:*"
+ "@hypit/timeline": "workspace:*"
}
}
diff --git a/packages/whisperx/src/activation.ts b/packages/whisperx/src/activation.ts
index 4b2d223a..dcf13646 100644
--- a/packages/whisperx/src/activation.ts
+++ b/packages/whisperx/src/activation.ts
@@ -1,6 +1,6 @@
import { createMarkupSurfaceHostFacet } from "@hypit/markup";
import {
- decodeWhisperXSemanticTakeSurface, whisperXComponent,
+ decodeWhisperXAlignmentSurface, whisperXComponent,
whisperXManifest, whisperXModuleRef,
whisperXMarkupSurfaces,
} from "./index.js";
@@ -11,8 +11,8 @@ export const hypitPackage = {
components: [whisperXComponent],
hostFacets: [createMarkupSurfaceHostFacet({
module: whisperXModuleRef,
- declaration: whisperXMarkupSurfaces.find((item) => item.name === "semantic-take")!,
- handler: decodeWhisperXSemanticTakeSurface,
+ declaration: whisperXMarkupSurfaces.find((item) => item.name === "alignment")!,
+ handler: decodeWhisperXAlignmentSurface,
})],
};
export default hypitPackage;
diff --git a/packages/whisperx/src/component.ts b/packages/whisperx/src/component.ts
index 3d547118..27f2b62f 100644
--- a/packages/whisperx/src/component.ts
+++ b/packages/whisperx/src/component.ts
@@ -1,6 +1,6 @@
import { plannedNeedInputs } from "@hypit/component-kit";
import type { ComponentPackage } from "@hypit/component-kit";
-import type { SpeechEvidenceAudio } from "@hypit/speech";
+import type { SpeechEvidenceAudio } from "@hypit/speech-evidence";
import type { CanonicalValue, StoredValue } from "@hypit/protocol";
import { canonicalize } from "@hypit/protocol";
diff --git a/packages/whisperx/src/evidence.ts b/packages/whisperx/src/evidence.ts
index 04550464..59e4096b 100644
--- a/packages/whisperx/src/evidence.ts
+++ b/packages/whisperx/src/evidence.ts
@@ -1,5 +1,5 @@
-import { assertSpeechEvidenceAudioIdentity } from "@hypit/speech";
-import type { SpeechEvidenceAudio } from "@hypit/speech";
+import { assertSpeechEvidenceAudioIdentity } from "@hypit/speech-evidence";
+import type { SpeechEvidenceAudio } from "@hypit/speech-evidence";
import type { WhisperXAlignmentRequest, WhisperXLanguage } from "./types.js";
import { parseWhisperXLanguage } from "./types.js";
@@ -12,7 +12,8 @@ export function verifyWhisperXAlignmentRequest(value: unknown): WhisperXAlignmen
assert(value !== null && typeof value === "object" && !Array.isArray(value),
"WhisperX alignment request must be an object");
const request = value as WhisperXAlignmentRequest;
- assert(request.audio?.kind === "blob"
+ assert(typeof request.domainId === "string" && request.domainId.length > 0
+ && request.audio?.kind === "blob"
&& request.audio.mediaType === "audio/wav"
&& Number.isSafeInteger(request.sampleFrames)
&& request.sampleFrames > 0,
@@ -63,6 +64,7 @@ export function whisperXRequestForEvidenceAudio(
): WhisperXAlignmentRequest {
assertSpeechEvidenceAudioIdentity(evidence);
return {
+ domainId: evidence.domainId,
audio: evidence.artifact,
sampleFrames: evidence.sampleFrames,
language: parseWhisperXLanguage(options.language),
diff --git a/packages/whisperx/src/fragment.ts b/packages/whisperx/src/fragment.ts
index 98bd424c..3e9bd32e 100644
--- a/packages/whisperx/src/fragment.ts
+++ b/packages/whisperx/src/fragment.ts
@@ -1,76 +1,40 @@
import { narrativeTypes } from "@hypit/narrative";
+import { narrativeTemporalProducers, narrativeTemporalTypes } from "@hypit/narrative-temporal";
import { mediaTypes } from "@hypit/media";
-import { speechProducers, speechTypes } from "@hypit/speech";
import { sealGraphFragment } from "@hypit/elaborator";
import { mediaPipelineProducers } from "@hypit/media-pipeline";
import { speechAlignmentProducers } from "@hypit/speech-alignment";
+import { temporalTypes } from "@hypit/temporal";
import { whisperXProducers, whisperXTypes } from "./manifest.js";
const input = (name: string) => ({ kind: "fragment-input" as const, name });
const operation = (id: string) => ({ kind: "fragment-operation" as const, operation: id });
-/** Normalize one Take's audio evidence, measure it, then project one Script Segment locally. */
-export const whisperXSemanticTakeFragment = sealGraphFragment({
- inputs: [
- { name: "narrative", type: narrativeTypes.narrative },
- { name: "segment", type: narrativeTypes.excerpt },
- { name: "media", type: mediaTypes.synchronized },
- { name: "language", type: whisperXTypes.language },
- ],
+export const whisperXAlignmentFragment = sealGraphFragment({
+ inputs: [{ name: "narrative", type: narrativeTypes.narrative }, { name: "segment", type: narrativeTypes.excerpt },
+ { name: "media", type: mediaTypes.synchronized }, { name: "domain", type: temporalTypes.localDomain },
+ { name: "language", type: whisperXTypes.language }],
operations: [
- {
- id: "prepare-evidence-audio",
- producer: mediaPipelineProducers.projectSpeechEvidenceAudio,
- inputs: { media: input("media") },
- result: { kind: "need", name: "evidenceAudio" },
- },
- {
- id: "request-whisperx",
- producer: whisperXProducers.request,
- inputs: {
- evidence: operation("prepare-evidence-audio"),
- language: input("language"),
- },
- result: { kind: "need", name: "alignment" },
- },
- {
- id: "align-semantic-take",
- producer: speechAlignmentProducers.alignTake,
- inputs: {
- narrative: input("narrative"),
- segment: input("segment"),
- media: input("media"),
- evidence: operation("request-whisperx"),
- },
- result: { kind: "output", name: "take" },
- },
- ],
- exports: [
- {
- name: "take",
- type: speechTypes.semanticTake,
- root: operation("align-semantic-take"),
- },
+ { id: "prepare-evidence-audio", producer: mediaPipelineProducers.projectSpeechEvidenceAudio,
+ inputs: { media: input("media"), domain: input("domain") }, result: { kind: "need", name: "evidenceAudio" } },
+ { id: "request-whisperx", producer: whisperXProducers.request,
+ inputs: { evidence: operation("prepare-evidence-audio"), language: input("language") }, result: { kind: "need", name: "alignment" } },
+ { id: "align-narrative", producer: speechAlignmentProducers.alignNarrative,
+ inputs: { narrative: input("narrative"), segment: input("segment"),
+ domain: input("domain"), evidence: operation("request-whisperx") },
+ result: { kind: "output", name: "alignment" } },
],
+ exports: [{ name: "alignment", type: narrativeTemporalTypes.narrativeAlignment, root: operation("align-narrative") }],
});
-/** The zero-Token branch of the same real-media Surface; media boundaries need no acoustic Need. */
-export const whisperXBoundarySemanticTakeFragment = sealGraphFragment({
- inputs: [
- { name: "narrative", type: narrativeTypes.narrative },
- { name: "segment", type: narrativeTypes.excerpt },
- { name: "media", type: mediaTypes.synchronized },
+export const whisperXBoundaryAlignmentFragment = sealGraphFragment({
+ inputs: [{ name: "narrative", type: narrativeTypes.narrative }, { name: "segment", type: narrativeTypes.excerpt },
+ { name: "domain", type: temporalTypes.localDomain }],
+ operations: [
+ { id: "materialize-boundaries", producer: narrativeTemporalProducers.materializeSegmentBoundaries,
+ inputs: { narrative: input("narrative"), segment: input("segment"), domain: input("domain") },
+ result: { kind: "output", name: "alignment" } },
],
- operations: [{
- id: "materialize-boundaries",
- producer: speechProducers.materializeSegmentBoundaries,
- inputs: {
- narrative: input("narrative"),
- segment: input("segment"),
- media: input("media"),
- },
- result: { kind: "output", name: "take" },
- }],
- exports: [{ name: "take", type: speechTypes.semanticTake, root: operation("materialize-boundaries") }],
+ exports: [{ name: "alignment", type: narrativeTemporalTypes.narrativeAlignment, root: operation("materialize-boundaries") }],
});
diff --git a/packages/whisperx/src/index.ts b/packages/whisperx/src/index.ts
index 0e5a2c2a..9fd90879 100644
--- a/packages/whisperx/src/index.ts
+++ b/packages/whisperx/src/index.ts
@@ -1,14 +1,14 @@
export {
whisperXComponent,
} from "./component.js";
-export { whisperXBoundarySemanticTakeFragment, whisperXSemanticTakeFragment } from "./fragment.js";
+export { whisperXAlignmentFragment, whisperXBoundaryAlignmentFragment } from "./fragment.js";
export {
assertWhisperXEvidenceWav,
verifyWhisperXAlignmentRequest,
whisperXRequestForEvidenceAudio,
} from "./evidence.js";
export { whisperXCapabilities, whisperXManifest, whisperXMarkupSurfaces, whisperXModuleRef, whisperXProducers, whisperXTypes } from "./manifest.js";
-export { decodeWhisperXSemanticTakeSurface } from "./surface.js";
+export { decodeWhisperXAlignmentSurface } from "./surface.js";
export { interpretWhisperXTranscript } from "./transcript.js";
export type { WhisperXTranscriptResponse } from "./transcript.js";
export type * from "./types.js";
diff --git a/packages/whisperx/src/manifest.ts b/packages/whisperx/src/manifest.ts
index 58025cae..f6da188c 100644
--- a/packages/whisperx/src/manifest.ts
+++ b/packages/whisperx/src/manifest.ts
@@ -1,10 +1,11 @@
-import { speechDependency, speechTypes } from "@hypit/speech";
import { mediaDependency, mediaTypes } from "@hypit/media";
import { narrativeDependency, narrativeTypes } from "@hypit/narrative";
+import { narrativeTemporalDependency, narrativeTemporalTypes } from "@hypit/narrative-temporal";
import { speechEvidenceDependency, speechEvidenceTypes } from "@hypit/speech-evidence";
import type { CapabilityRef, ModuleManifest, ProducerRef, TypeRef } from "@hypit/protocol";
import { mediaPipelineManifest, mediaPipelineModuleRef } from "@hypit/media-pipeline";
-import { speechAlignmentManifest, speechAlignmentModuleRef } from "@hypit/speech-alignment";
+import { speechAlignmentModuleRef } from "@hypit/speech-alignment";
+import { temporalDependency, temporalTypes } from "@hypit/temporal";
export const whisperXModuleRef = { name: "@hypit/whisperx", version: "1" } as const;
export const whisperXTypes = {
@@ -18,16 +19,16 @@ export const whisperXProducers = {
} satisfies Record<string, ProducerRef>;
export const whisperXMarkupSurfaces = [{
- name: "semantic-take",
- tag: "SemanticTake",
+ name: "alignment",
+ tag: "Alignment",
mode: "structured",
- outputs: [whisperXTypes.language, speechTypes.semanticTake],
+ outputs: [whisperXTypes.language, narrativeTemporalTypes.narrativeAlignment],
vocabulary: {
summary:
- "Publishes a real-media SemanticTake: WhisperX-aligned words for speech, or exact prepared-media boundaries for an empty Segment.",
+ "Publishes source-local NarrativeAlignment: WhisperX-aligned words for speech, or exact prepared-media boundaries for an empty Segment.",
attributes: [
{ name: "id", kind: "identifier", required: true,
- summary: "Names this alignment and prefixes the bindings it publishes." },
+ summary: "Names the alignment it publishes." },
{ name: "narrative", kind: "reference", required: true,
accepts: [narrativeTypes.narrative],
summary: "Selects the authored Narrative that owns the Segment and Token identities." },
@@ -37,18 +38,22 @@ export const whisperXMarkupSurfaces = [{
{ name: "media", kind: "reference", required: true,
accepts: [mediaTypes.synchronized],
summary: "Selects the already normalized SynchronizedMedia represented by this Segment." },
+ { name: "domain", kind: "reference", required: true,
+ accepts: [temporalTypes.localDomain],
+ summary: "Selects that normalized media's single local temporal domain." },
{ name: "language", kind: "literal", required: false,
summary: "For a Segment with Tokens, explicitly states its spoken language code. The selected service owns the available alignment models." },
],
ports: [
- { name: "take", type: speechTypes.semanticTake,
- summary: "The normalized media plus this Segment's authored words and local frame anchors." },
+ { name: "alignment", type: narrativeTemporalTypes.narrativeAlignment,
+ summary: "This Segment's authored boundary identities on the local domain, without media." },
],
- example: `<whisperx:SemanticTake id="opening" narrative={story}
- segment={story.segment.opening} media={opening-media.media} language="en"/>`,
+ example: `<whisperx:Alignment id="opening" narrative={story}
+ segment={story.segment.opening} media={opening-media.media}
+ domain={opening-media.domain} language="en"/>`,
notes: [
"A Segment with Tokens states all five attributes and sends its prepared audio for alignment.",
- "An empty Segment omits language and maps its authored start/end Anchors directly to the prepared-media boundaries.",
+ "An empty Segment omits media and language and maps its authored start/end Anchors directly to the selected domain boundaries.",
"For speech, each alignment call states an explicit lowercase two- or three-letter language code; language is not inferred from Script text or audio.",
"Importing this package is what selects the WhisperX model family; the Runtime separately binds the alignment Need to an Endpoint.",
],
@@ -61,12 +66,13 @@ export const whisperXManifest: ModuleManifest = {
name: whisperXModuleRef.name,
version: whisperXModuleRef.version,
dependencies: [
- speechDependency,
speechEvidenceDependency,
mediaDependency,
narrativeDependency,
+ narrativeTemporalDependency,
{ module: mediaPipelineModuleRef },
{ module: speechAlignmentModuleRef },
+ temporalDependency,
],
types: [{ name: whisperXTypes.language.name }],
capabilities: [{
@@ -77,7 +83,7 @@ export const whisperXManifest: ModuleManifest = {
{
name: whisperXProducers.request.name,
inputs: [
- { name: "evidence", type: speechTypes.evidenceAudio },
+ { name: "evidence", type: speechEvidenceTypes.audio },
{ name: "language", type: whisperXTypes.language },
],
outputs: [],
diff --git a/packages/whisperx/src/surface.ts b/packages/whisperx/src/surface.ts
index 10dcb9c8..08df27fd 100644
--- a/packages/whisperx/src/surface.ts
+++ b/packages/whisperx/src/surface.ts
@@ -1,87 +1,49 @@
-import {
- assertExactAttributes as exactAttributes,
- textAttribute as stringAttribute,
- type StructuredElement,
- type StructuredSurfaceHandler,
- type SurfaceResolvedReference,
- type MarkupAttributeValue,
-} from "@hypit/markup";
+import { assertExactAttributes as exactAttributes, textAttribute as stringAttribute,
+ type StructuredElement, type StructuredSurfaceHandler, type SurfaceResolvedReference, type SurfaceRecordDraft, type MarkupAttributeValue } from "@hypit/markup";
import { sameType } from "@hypit/protocol";
import { narrativeTypes } from "@hypit/narrative";
import type { NarrativeExcerpt } from "@hypit/narrative";
import { mediaTypes } from "@hypit/media";
+import { temporalTypes } from "@hypit/temporal";
-import { whisperXBoundarySemanticTakeFragment, whisperXSemanticTakeFragment } from "./fragment.js";
+import { whisperXAlignmentFragment, whisperXBoundaryAlignmentFragment } from "./fragment.js";
import { whisperXTypes } from "./manifest.js";
import { parseWhisperXLanguage } from "./types.js";
-function reference(
- element: StructuredElement,
- name: string,
- expected: SurfaceResolvedReference["type"],
- resolveReference: (path: string) => SurfaceResolvedReference | undefined,
-): SurfaceResolvedReference {
+function reference(element: StructuredElement, name: string, expected: SurfaceResolvedReference["type"],
+ resolveReference: (path: string) => SurfaceResolvedReference | undefined): SurfaceResolvedReference {
const raw: MarkupAttributeValue | undefined = element.attributes[name];
if (typeof raw !== "object" || raw.kind !== "reference") throw new Error(`${element.name}.${name} must be a whole-value reference`);
const value = resolveReference(raw.path);
- if (value === undefined) throw new Error(`${element.name}.${name} cannot resolve ${raw.path}`);
- if (!sameType(value.type, expected)) throw new Error(`${element.name}.${name} has the wrong type`);
+ if (value === undefined || !sameType(value.type, expected)) throw new Error(`${element.name}.${name} has the wrong type`);
return value;
}
-
function authoredExcerpt(value: SurfaceResolvedReference): NarrativeExcerpt | undefined {
- return value.record?.value.kind === "inline"
- ? value.record.value.value as unknown as NarrativeExcerpt
- : undefined;
+ return value.record?.value.kind === "inline" ? value.record.value.value as unknown as NarrativeExcerpt : undefined;
}
-export const decodeWhisperXSemanticTakeSurface: StructuredSurfaceHandler = ({ element, resolveReference }) => {
+export const decodeWhisperXAlignmentSurface: StructuredSurfaceHandler = ({ element, resolveReference }) => {
const narrative = reference(element, "narrative", narrativeTypes.narrative, resolveReference);
const segment = reference(element, "segment", narrativeTypes.excerpt, resolveReference);
- const media = reference(element, "media", mediaTypes.synchronized, resolveReference);
+ const domain = reference(element, "domain", temporalTypes.localDomain, resolveReference);
const excerpt = authoredExcerpt(segment);
const hasNoTokens = excerpt !== undefined && excerpt.tokenStart === excerpt.tokenEndExclusive;
- exactAttributes(element, hasNoTokens
- ? ["id", "narrative", "segment", "media"]
- : ["id", "narrative", "segment", "media", "language"]);
- if (element.children.some((child) => child.kind === "element" || child.value.trim())) {
- throw new Error(`${element.name} does not accept children`);
- }
+ exactAttributes(element, hasNoTokens ? ["id", "narrative", "segment", "domain"] : ["id", "narrative", "segment", "media", "domain", "language"]);
+ if (element.children.some((child) => child.kind === "element" || child.value.trim())) throw new Error(`${element.name} does not accept children`);
const id = stringAttribute(element, "id");
- if (hasNoTokens) {
- return {
- records: [],
- components: [{
- id,
- fragment: whisperXBoundarySemanticTakeFragment.id,
- inputs: { narrative: narrative.ref, segment: segment.ref, media: media.ref },
- outputs: { take: `${id}.take` },
- range: element.range,
- }],
- fragments: [whisperXBoundarySemanticTakeFragment],
- };
- }
- const language = parseWhisperXLanguage(stringAttribute(element, "language"), `${element.name}.language`);
- const languageId = `${id}.language`;
- return {
- records: [{
- id: languageId,
- type: whisperXTypes.language,
- value: { kind: "inline", value: language },
- range: element.range,
- }],
- components: [{
- id,
- fragment: whisperXSemanticTakeFragment.id,
- inputs: {
- narrative: narrative.ref,
- segment: segment.ref,
- media: media.ref,
- language: { kind: "record", id: languageId },
- },
- outputs: { take: `${id}.take` },
- range: element.range,
- }],
- fragments: [whisperXSemanticTakeFragment],
+ const fragment = hasNoTokens ? whisperXBoundaryAlignmentFragment : whisperXAlignmentFragment;
+ const records: SurfaceRecordDraft[] = [];
+ const inputs: Record<string, SurfaceResolvedReference["ref"] | { kind: "record"; id: string }> = {
+ narrative: narrative.ref, segment: segment.ref, domain: domain.ref,
};
+ if (!hasNoTokens) {
+ inputs.media = reference(element, "media", mediaTypes.synchronized, resolveReference).ref;
+ const language = parseWhisperXLanguage(stringAttribute(element, "language"), `${element.name}.language`);
+ const languageId = `${id}.language`;
+ records.push({ id: languageId, type: whisperXTypes.language, value: { kind: "inline", value: language }, range: element.range });
+ inputs.language = { kind: "record", id: languageId };
+ }
+ return { records, components: [{ id, fragment: fragment.id, inputs,
+ outputs: { alignment: `${id}.alignment` }, range: element.range }],
+ fragments: [fragment], exports: [`${id}.alignment`] };
};
diff --git a/packages/whisperx/src/types.ts b/packages/whisperx/src/types.ts
index fb6c84bf..f8d7c323 100644
--- a/packages/whisperx/src/types.ts
+++ b/packages/whisperx/src/types.ts
@@ -1,4 +1,4 @@
-import type { SpeechEvidenceAudio } from "@hypit/speech";
+import type { SpeechEvidenceAudio } from "@hypit/speech-evidence";
/** Explicit language code. Executable language support belongs to the selected service. */
export type WhisperXLanguage = string;
@@ -11,6 +11,7 @@ export function parseWhisperXLanguage(value: unknown, subject = "WhisperX langua
}
export type WhisperXAlignmentRequest = {
+ readonly domainId: string;
readonly audio: SpeechEvidenceAudio["artifact"];
readonly sampleFrames: number;
readonly language: WhisperXLanguage;
diff --git a/packages/whisperx/test/whisperx.test.ts b/packages/whisperx/test/whisperx.test.ts
index 652b393e..5ac12e5c 100644
--- a/packages/whisperx/test/whisperx.test.ts
+++ b/packages/whisperx/test/whisperx.test.ts
@@ -3,14 +3,16 @@ import { parseStructuredElement } from "@hypit/markup";
import type { SurfaceResolvedReference } from "@hypit/markup";
import { narrativeTypes } from "@hypit/narrative";
import type { Narrative } from "@hypit/narrative";
-import { sealSpeechEvidenceAudio, speechProducers } from "@hypit/speech";
-import type { SpeechEvidenceAudio } from "@hypit/speech";
+import { narrativeTemporalProducers } from "@hypit/narrative-temporal";
+import { sealSpeechEvidenceAudio } from "@hypit/speech-evidence";
+import type { SpeechEvidenceAudio } from "@hypit/speech-evidence";
+import { temporalTypes } from "@hypit/temporal";
import assert from "node:assert/strict";
import test from "node:test";
import { fixtureResource } from "../../../test/fixture-resource.js";
import {
- decodeWhisperXSemanticTakeSurface,
+ decodeWhisperXAlignmentSurface,
whisperXRequestForEvidenceAudio,
whisperXComponent,
verifyWhisperXAlignmentRequest,
@@ -19,6 +21,7 @@ import {
function evidenceAudio(): SpeechEvidenceAudio {
return sealSpeechEvidenceAudio({
+ domainId: "speech-domain",
artifact: {
kind: "blob",
resource: fixtureResource("whisperx-test:evidence-audio"),
@@ -33,6 +36,7 @@ test("WhisperX receives normalized bytes without authored Segment truth", () =>
const valid = evidenceAudio();
const request = whisperXRequestForEvidenceAudio(valid, { language: "es" });
assert.equal(request.audio.resource, valid.artifact.resource);
+ assert.equal(request.domainId, valid.domainId);
assert.equal("segments" in request, false);
assert.equal(request.sampleFrames, 16_000);
assert.equal(request.language, "es");
@@ -43,20 +47,21 @@ test("SVML language reaches the alignment request without a service-support tabl
["story", { path: "story", ref: { kind: "record", id: "story" }, type: narrativeTypes.narrative }],
["excerpt", { path: "excerpt", ref: { kind: "record", id: "excerpt" }, type: narrativeTypes.excerpt }],
["media", { path: "media", ref: { kind: "record", id: "media" }, type: mediaTypes.synchronized }],
+ ["domain", { path: "domain", ref: { kind: "record", id: "domain" }, type: temporalTypes.localDomain }],
]);
// "zzz" deliberately tests expression independently of a deployment's supported languages.
for (const language of ["en", "zh", "es", "ko", "ja", "id", "yue", "zzz"]) {
- const output = await decodeWhisperXSemanticTakeSurface({
+ const output = await decodeWhisperXAlignmentSurface({
sourceName: "speech.svml",
element: parseStructuredElement({ name: "speech.svml", text:
- `<whisperx:SemanticTake id="speech" narrative={story} segment={excerpt} media={media} language="${language}"/>`,
+ `<whisperx:Alignment id="speech" narrative={story} segment={excerpt} media={media} domain={domain} language="${language}"/>`,
}, 0).element,
resolveReference: (path) => refs.get(path),
resolveAsset: () => { throw new Error("No assets expected"); },
});
const result = await whisperXComponent.producers[0]!.handler({ inputs: {
evidence: { value: { kind: "inline", value: evidenceAudio() } },
- language: { value: output.records[0]!.value },
+ language: { value: output.records.find((record) => record.type.name === "WhisperXLanguage")!.value },
} } as never);
assert.equal(verifyWhisperXAlignmentRequest(result.needs!.alignment).language, language);
}
@@ -74,7 +79,6 @@ test("language spelling is explicit; auto-detection and locale aliases are not g
test("the real-media Surface materializes an empty Segment from its media domain", async () => {
const narrative: Narrative = {
id: "wordless-real",
- caption: { id: "wordless-real.caption", narrativeId: "wordless-real", units: [], words: [], cueBreaks: [] },
segments: [{
id: "pause",
startAnchorId: "pause:start",
@@ -96,7 +100,7 @@ test("the real-media Surface materializes an empty Segment from its media domain
tokenEndExclusive: 0,
};
const media = sealSynchronizedMedia({
- timeline: { frameRate: { numerator: 30, denominator: 1 }, frameCount: 90 },
+ frameDomain: { frameRate: { numerator: 30, denominator: 1 }, frameCount: 90 },
visual: {
artifact: { kind: "blob", resource: fixtureResource("whisperx:wordless"), size: 1, mediaType: "video/mp4" },
width: 1_080,
@@ -116,18 +120,21 @@ test("the real-media Surface materializes an empty Segment from its media domain
const refs = new Map<string, SurfaceResolvedReference>([
["story", authored("story", narrativeTypes.narrative, narrative)],
["story.segment.pause", authored("story.segment.pause", narrativeTypes.excerpt, excerpt)],
- ["pause-media.media", authored("pause-media.media", mediaTypes.synchronized, media)],
+ ["pause-media.domain", authored("pause-media.domain", temporalTypes.localDomain, {
+ id: "pause-media", frameRate: media.frameDomain.frameRate, frameCount: media.frameDomain.frameCount,
+ })],
]);
- const output = await decodeWhisperXSemanticTakeSurface({
+ const output = await decodeWhisperXAlignmentSurface({
sourceName: "real.svml",
element: parseStructuredElement({ name: "real.svml", text:
- '<whisperx:SemanticTake id="pause" narrative={story} segment={story.segment.pause} media={pause-media.media}/>',
+ '<whisperx:Alignment id="pause" narrative={story} segment={story.segment.pause} domain={pause-media.domain}/>',
}, 0).element,
resolveReference: (path) => refs.get(path),
resolveAsset: () => { throw new Error("No assets are resolved by this test."); },
});
assert.equal(output.records.length, 0);
- assert.equal(output.fragments[0]?.operations[0]?.producer.name, speechProducers.materializeSegmentBoundaries.name);
- assert.deepEqual(Object.keys(output.components[0]?.inputs ?? {}).sort(), ["media", "narrative", "segment"]);
+ assert.equal(output.fragments[0]?.operations[0]?.producer.name, narrativeTemporalProducers.materializeSegmentBoundaries.name);
+ assert.deepEqual(Object.keys(output.components[0]?.inputs ?? {}).sort(), ["domain", "narrative", "segment"]);
+ assert.deepEqual(output.components[0]?.outputs, { alignment: "pause.alignment" });
});
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 24810773..cfc4e0ea 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -96,12 +96,12 @@ importers:
'@hypit/credential-store-platform':
specifier: workspace:*
version: link:packages/credential-store-platform
- '@hypit/deck-track':
+ '@hypit/depth-stack':
specifier: workspace:*
- version: link:packages/deck-track
- '@hypit/deck-track-studio':
+ version: link:packages/depth-stack
+ '@hypit/depth-stack-studio':
specifier: workspace:*
- version: link:packages/deck-track-studio
+ version: link:packages/depth-stack-studio
'@hypit/elevenlabs-speech':
specifier: workspace:*
version: link:packages/elevenlabs-speech
@@ -150,12 +150,6 @@ importers:
'@hypit/media-pipeline':
specifier: workspace:*
version: link:packages/media-pipeline
- '@hypit/media-track':
- specifier: workspace:*
- version: link:packages/media-track
- '@hypit/media-track-studio':
- specifier: workspace:*
- version: link:packages/media-track-studio
'@hypit/mimo-speech':
specifier: workspace:*
version: link:packages/mimo-speech
@@ -168,18 +162,15 @@ importers:
'@hypit/narrative':
specifier: workspace:*
version: link:packages/narrative
- '@hypit/performance':
+ '@hypit/narrative-caption':
specifier: workspace:*
- version: link:packages/performance
- '@hypit/performance-studio':
+ version: link:packages/narrative-caption
+ '@hypit/narrative-temporal':
specifier: workspace:*
- version: link:packages/performance-studio
+ version: link:packages/narrative-temporal
'@hypit/pixverse':
specifier: workspace:*
version: link:packages/pixverse
- '@hypit/program-space':
- specifier: workspace:*
- version: link:packages/program-space
'@hypit/project-context-node':
specifier: workspace:*
version: link:packages/project-context-node
@@ -225,6 +216,9 @@ importers:
'@hypit/raster':
specifier: workspace:*
version: link:packages/raster
+ '@hypit/region-track':
+ specifier: workspace:*
+ version: link:packages/region-track
'@hypit/render-hyperframes':
specifier: workspace:*
version: link:packages/render-hyperframes
@@ -267,12 +261,6 @@ importers:
'@hypit/seedream':
specifier: workspace:*
version: link:packages/seedream
- '@hypit/sound':
- specifier: workspace:*
- version: link:packages/sound
- '@hypit/sound-studio':
- specifier: workspace:*
- version: link:packages/sound-studio
'@hypit/spatial':
specifier: workspace:*
version: link:packages/spatial
@@ -309,15 +297,21 @@ importers:
'@hypit/timeline-author':
specifier: workspace:*
version: link:packages/timeline-author
- '@hypit/typography-track':
+ '@hypit/text-fine':
specifier: workspace:*
- version: link:packages/typography-track
- '@hypit/typography-track-studio':
+ version: link:packages/text-fine
+ '@hypit/text-fine-studio':
specifier: workspace:*
- version: link:packages/typography-track-studio
+ version: link:packages/text-fine-studio
'@hypit/visual-ir':
specifier: workspace:*
version: link:packages/visual-ir
+ '@hypit/visual-track':
+ specifier: workspace:*
+ version: link:packages/visual-track
+ '@hypit/visual-track-studio':
+ specifier: workspace:*
+ version: link:packages/visual-track-studio
'@hypit/volcengine-matting':
specifier: workspace:*
version: link:packages/volcengine-matting
@@ -343,15 +337,32 @@ importers:
specifier: ^1.6.4
- examples/complex-explainer/packages/launch-scenes: {}
+ examples/complex-explainer/packages/launch-scenes:
+ dependencies:
+ '@hypit/hypit':
+ specifier: workspace:*
+ version: link:../../../..
examples/complex-explainer/packages/opening-system:
dependencies:
'@explainer/visual-language':
specifier: file:../visual-language
version: link:../visual-language
+ '@hypit/hypit':
+ specifier: workspace:*
+ version: link:../../../..
- examples/complex-explainer/packages/single-line-captions: {}
+ examples/complex-explainer/packages/single-line-captions:
+ dependencies:
+ '@hypit/caption-fine':
+ specifier: workspace:*
+ version: link:../../../../packages/caption-fine
+ '@hypit/caption-fine-studio':
+ specifier: workspace:*
+ version: link:../../../../packages/caption-fine-studio
+ '@hypit/hypit':
+ specifier: workspace:*
+ version: link:../../../..
examples/complex-explainer/packages/visual-language: {}
@@ -360,6 +371,9 @@ importers:
'@explainer/visual-language':
specifier: file:../visual-language
version: link:../visual-language
+ '@hypit/hypit':
+ specifier: workspace:*
+ version: link:../../../..
examples/minimal-author-package/packages/example-component:
devDependencies:
@@ -415,18 +429,6 @@ importers:
specifier: 5.9.3
version: 5.9.3
- examples/semantic-composition/packages/performance-styles:
- devDependencies:
- '@hypit/hypit':
- specifier: workspace:*
- version: link:../../../..
- '@types/node':
- specifier: 24.10.1
- version: 24.10.1
- typescript:
- specifier: 5.9.3
- version: 5.9.3
-
examples/semantic-composition/packages/responsive-explainer:
devDependencies:
'@hypit/hypit':
@@ -439,18 +441,6 @@ importers:
specifier: 5.9.3
version: 5.9.3
- examples/semantic-composition/packages/sound-styles:
- devDependencies:
- '@hypit/hypit':
- specifier: workspace:*
- version: link:../../../..
- '@types/node':
- specifier: 24.10.1
- version: 24.10.1
- typescript:
- specifier: 5.9.3
- version: 5.9.3
-
packages/artifact:
dependencies:
'@hypit/protocol':
@@ -474,12 +464,6 @@ importers:
'@hypit/media':
specifier: workspace:*
version: link:../media
- '@hypit/narrative':
- specifier: workspace:*
- version: link:../narrative
- '@hypit/program-space':
- specifier: workspace:*
- version: link:../program-space
'@hypit/protocol':
specifier: workspace:*
version: link:../protocol
@@ -529,6 +513,9 @@ importers:
'@hypit/studio-adapter':
specifier: workspace:*
version: link:../studio-adapter
+ '@hypit/temporal':
+ specifier: workspace:*
+ version: link:../temporal
packages/author-kit:
dependencies:
@@ -625,40 +612,15 @@ importers:
'@hypit/component-kit':
specifier: workspace:*
version: link:../component-kit
- '@hypit/elaborator':
- specifier: workspace:*
- version: link:../elaborator
'@hypit/markup':
specifier: workspace:*
version: link:../markup
- '@hypit/narrative':
- specifier: workspace:*
- version: link:../narrative
'@hypit/protocol':
specifier: workspace:*
version: link:../protocol
'@hypit/temporal':
specifier: workspace:*
version: link:../temporal
- '@hypit/timeline':
- specifier: workspace:*
- version: link:../timeline
- devDependencies:
- '@hypit/program-space':
- specifier: workspace:*
- version: link:../program-space
- '@hypit/script':
- specifier: workspace:*
- version: link:../script
- '@hypit/speech':
- specifier: workspace:*
- version: link:../speech
- '@hypit/speech-alignment':
- specifier: workspace:*
- version: link:../speech-alignment
- '@hypit/speech-evidence':
- specifier: workspace:*
- version: link:../speech-evidence
packages/caption-fine:
dependencies:
@@ -683,15 +645,12 @@ importers:
'@hypit/media':
specifier: workspace:*
version: link:../media
- '@hypit/narrative':
- specifier: workspace:*
- version: link:../narrative
- '@hypit/program-space':
- specifier: workspace:*
- version: link:../program-space
'@hypit/protocol':
specifier: workspace:*
version: link:../protocol
+ '@hypit/region-track':
+ specifier: workspace:*
+ version: link:../region-track
'@hypit/spatial':
specifier: workspace:*
version: link:../spatial
@@ -726,9 +685,6 @@ importers:
'@hypit/fonts-open':
specifier: workspace:*
version: link:../fonts-open
- '@hypit/narrative':
- specifier: workspace:*
- version: link:../narrative
'@hypit/studio-adapter':
specifier: workspace:*
version: link:../studio-adapter
@@ -823,12 +779,6 @@ importers:
'@hypit/media':
specifier: workspace:*
version: link:../media
- '@hypit/narrative':
- specifier: workspace:*
- version: link:../narrative
- '@hypit/program-space':
- specifier: workspace:*
- version: link:../program-space
'@hypit/protocol':
specifier: workspace:*
version: link:../protocol
@@ -946,12 +896,12 @@ importers:
'@hypit/media':
specifier: workspace:*
version: link:../media
- '@hypit/program-space':
- specifier: workspace:*
- version: link:../program-space
'@hypit/protocol':
specifier: workspace:*
version: link:../protocol
+ '@hypit/timeline':
+ specifier: workspace:*
+ version: link:../timeline
'@hypit/visual-ir':
specifier: workspace:*
version: link:../visual-ir
@@ -1029,7 +979,7 @@ importers:
specifier: workspace:*
version: link:../runtime-kit
- packages/deck-track:
+ packages/depth-stack:
dependencies:
'@hypit/artifact':
specifier: workspace:*
@@ -1049,15 +999,6 @@ importers:
'@hypit/media':
specifier: workspace:*
version: link:../media
- '@hypit/media-track':
- specifier: workspace:*
- version: link:../media-track
- '@hypit/narrative':
- specifier: workspace:*
- version: link:../narrative
- '@hypit/program-space':
- specifier: workspace:*
- version: link:../program-space
'@hypit/protocol':
specifier: workspace:*
version: link:../protocol
@@ -1079,6 +1020,9 @@ importers:
'@hypit/timeline':
specifier: workspace:*
version: link:../timeline
+ '@hypit/visual-track':
+ specifier: workspace:*
+ version: link:../visual-track
devDependencies:
'@hypit/core':
specifier: workspace:*
@@ -1087,14 +1031,14 @@ importers:
specifier: workspace:*
version: link:../media-pipeline
- packages/deck-track-studio:
+ packages/depth-stack-studio:
dependencies:
'@hypit/composition':
specifier: workspace:*
version: link:../composition
- '@hypit/deck-track':
+ '@hypit/depth-stack':
specifier: workspace:*
- version: link:../deck-track
+ version: link:../depth-stack
'@hypit/studio-adapter':
specifier: workspace:*
version: link:../studio-adapter
@@ -1203,9 +1147,6 @@ importers:
'@hypit/markup':
specifier: workspace:*
version: link:../markup
- '@hypit/program-space':
- specifier: workspace:*
- version: link:../program-space
'@hypit/protocol':
specifier: workspace:*
version: link:../protocol
@@ -1237,9 +1178,9 @@ importers:
'@hypit/text':
specifier: workspace:*
version: link:../text
- '@hypit/typography-track':
+ '@hypit/text-fine':
specifier: workspace:*
- version: link:../typography-track
+ version: link:../text-fine
'@hypit/validation':
specifier: workspace:*
version: link:../validation
@@ -1252,9 +1193,6 @@ importers:
'@hypit/film':
specifier: workspace:*
version: link:../film
- '@hypit/program-space':
- specifier: workspace:*
- version: link:../program-space
'@hypit/studio-adapter':
specifier: workspace:*
version: link:../studio-adapter
@@ -1297,7 +1235,6 @@ importers:
'@hypit/protocol':
specifier: workspace:*
version: link:../protocol
- devDependencies:
'@hypit/studio-adapter':
specifier: workspace:*
version: link:../studio-adapter
@@ -1688,9 +1625,6 @@ importers:
'@hypit/narrative':
specifier: workspace:*
version: link:../narrative
- '@hypit/program-space':
- specifier: workspace:*
- version: link:../program-space
'@hypit/raster':
specifier: workspace:*
version: link:../raster
@@ -1706,6 +1640,9 @@ importers:
'@hypit/speech':
specifier: workspace:*
version: link:../speech
+ '@hypit/timeline':
+ specifier: workspace:*
+ version: link:../timeline
packages/gpt-image-kits:
devDependencies:
@@ -1753,12 +1690,12 @@ importers:
'@hypit/media':
specifier: workspace:*
version: link:../media
- '@hypit/program-space':
- specifier: workspace:*
- version: link:../program-space
'@hypit/protocol':
specifier: workspace:*
version: link:../protocol
+ '@hypit/timeline':
+ specifier: workspace:*
+ version: link:../timeline
'@hypit/visual-ir':
specifier: workspace:*
version: link:../visual-ir
@@ -1766,18 +1703,12 @@ importers:
'@hypit/caption':
specifier: workspace:*
version: link:../caption
- '@hypit/caption-fine':
+ '@hypit/depth-stack':
specifier: workspace:*
- version: link:../caption-fine
- '@hypit/deck-track':
- specifier: workspace:*
- version: link:../deck-track
+ version: link:../depth-stack
'@hypit/fonts-open':
specifier: workspace:*
version: link:../fonts-open
- '@hypit/media-track':
- specifier: workspace:*
- version: link:../media-track
'@hypit/ranking':
specifier: workspace:*
version: link:../ranking
@@ -1793,9 +1724,12 @@ importers:
'@hypit/svs':
specifier: workspace:*
version: link:../svs
- '@hypit/typography-track':
+ '@hypit/text-fine':
+ specifier: workspace:*
+ version: link:../text-fine
+ '@hypit/visual-track':
specifier: workspace:*
- version: link:../typography-track
+ version: link:../visual-track
packages/image-compose:
dependencies:
@@ -1859,12 +1793,6 @@ importers:
'@hypit/markup':
specifier: workspace:*
version: link:../markup
- '@hypit/narrative':
- specifier: workspace:*
- version: link:../narrative
- '@hypit/program-space':
- specifier: workspace:*
- version: link:../program-space
'@hypit/protocol':
specifier: workspace:*
version: link:../protocol
@@ -1907,12 +1835,18 @@ importers:
'@hypit/component-kit':
specifier: workspace:*
version: link:../component-kit
+ '@hypit/elaborator':
+ specifier: workspace:*
+ version: link:../elaborator
'@hypit/markup':
specifier: workspace:*
version: link:../markup
'@hypit/protocol':
specifier: workspace:*
version: link:../protocol
+ '@hypit/temporal':
+ specifier: workspace:*
+ version: link:../temporal
packages/media-execution:
dependencies:
@@ -1922,15 +1856,15 @@ importers:
'@hypit/media-pipeline':
specifier: workspace:*
version: link:../media-pipeline
- '@hypit/program-space':
- specifier: workspace:*
- version: link:../program-space
'@hypit/protocol':
specifier: workspace:*
version: link:../protocol
- '@hypit/speech':
+ '@hypit/speech-evidence':
specifier: workspace:*
- version: link:../speech
+ version: link:../speech-evidence
+ '@hypit/timeline':
+ specifier: workspace:*
+ version: link:../timeline
packages/media-pipeline:
dependencies:
@@ -1955,9 +1889,6 @@ importers:
'@hypit/narrative':
specifier: workspace:*
version: link:../narrative
- '@hypit/program-space':
- specifier: workspace:*
- version: link:../program-space
'@hypit/protocol':
specifier: workspace:*
version: link:../protocol
@@ -1967,70 +1898,19 @@ importers:
'@hypit/speech':
specifier: workspace:*
version: link:../speech
- '@hypit/svs':
- specifier: workspace:*
- version: link:../svs
-
- packages/media-track:
- dependencies:
- '@hypit/artifact':
- specifier: workspace:*
- version: link:../artifact
- '@hypit/component-kit':
- specifier: workspace:*
- version: link:../component-kit
- '@hypit/composition':
- specifier: workspace:*
- version: link:../composition
- '@hypit/elaborator':
- specifier: workspace:*
- version: link:../elaborator
- '@hypit/markup':
- specifier: workspace:*
- version: link:../markup
- '@hypit/media':
- specifier: workspace:*
- version: link:../media
- '@hypit/narrative':
- specifier: workspace:*
- version: link:../narrative
- '@hypit/program-space':
- specifier: workspace:*
- version: link:../program-space
- '@hypit/protocol':
- specifier: workspace:*
- version: link:../protocol
- '@hypit/spatial':
+ '@hypit/speech-evidence':
specifier: workspace:*
- version: link:../spatial
+ version: link:../speech-evidence
'@hypit/svs':
specifier: workspace:*
version: link:../svs
'@hypit/temporal':
specifier: workspace:*
version: link:../temporal
- '@hypit/temporal-markup':
- specifier: workspace:*
- version: link:../temporal-markup
'@hypit/timeline':
specifier: workspace:*
version: link:../timeline
- packages/media-track-studio:
- dependencies:
- '@hypit/composition':
- specifier: workspace:*
- version: link:../composition
- '@hypit/media-track':
- specifier: workspace:*
- version: link:../media-track
- '@hypit/protocol':
- specifier: workspace:*
- version: link:../protocol
- '@hypit/studio-adapter':
- specifier: workspace:*
- version: link:../studio-adapter
-
packages/mimo-speech:
dependencies:
'@hypit/artifact':
@@ -2127,62 +2007,71 @@ importers:
specifier: workspace:*
version: link:../protocol
- packages/package-loader-node:
+ packages/narrative-alignment-adjust:
dependencies:
'@hypit/component-kit':
specifier: workspace:*
version: link:../component-kit
- '@hypit/host':
+ '@hypit/elaborator':
specifier: workspace:*
- version: link:../host
+ version: link:../elaborator
+ '@hypit/markup':
+ specifier: workspace:*
+ version: link:../markup
+ '@hypit/narrative':
+ specifier: workspace:*
+ version: link:../narrative
+ '@hypit/narrative-temporal':
+ specifier: workspace:*
+ version: link:../narrative-temporal
'@hypit/protocol':
specifier: workspace:*
version: link:../protocol
- cjs-module-lexer:
- specifier: 2.2.1
- version: 2.2.1
- typescript:
- specifier: 5.9.3
- version: 5.9.3
+ '@hypit/temporal':
+ specifier: workspace:*
+ version: link:../temporal
- packages/performance:
+ packages/narrative-caption:
dependencies:
- '@hypit/artifact':
+ '@hypit/caption':
specifier: workspace:*
- version: link:../artifact
+ version: link:../caption
'@hypit/component-kit':
specifier: workspace:*
version: link:../component-kit
- '@hypit/composition':
- specifier: workspace:*
- version: link:../composition
'@hypit/elaborator':
specifier: workspace:*
version: link:../elaborator
'@hypit/markup':
specifier: workspace:*
version: link:../markup
- '@hypit/media':
- specifier: workspace:*
- version: link:../media
- '@hypit/media-track':
- specifier: workspace:*
- version: link:../media-track
'@hypit/narrative':
specifier: workspace:*
version: link:../narrative
- '@hypit/program-space':
+ '@hypit/narrative-temporal':
specifier: workspace:*
- version: link:../program-space
+ version: link:../narrative-temporal
'@hypit/protocol':
specifier: workspace:*
version: link:../protocol
- '@hypit/spatial':
+
+ packages/narrative-temporal:
+ dependencies:
+ '@hypit/component-kit':
specifier: workspace:*
- version: link:../spatial
- '@hypit/svs':
+ version: link:../component-kit
+ '@hypit/elaborator':
specifier: workspace:*
- version: link:../svs
+ version: link:../elaborator
+ '@hypit/markup':
+ specifier: workspace:*
+ version: link:../markup
+ '@hypit/narrative':
+ specifier: workspace:*
+ version: link:../narrative
+ '@hypit/protocol':
+ specifier: workspace:*
+ version: link:../protocol
'@hypit/temporal':
specifier: workspace:*
version: link:../temporal
@@ -2192,30 +2081,24 @@ importers:
'@hypit/timeline':
specifier: workspace:*
version: link:../timeline
- '@hypit/visual-ir':
- specifier: workspace:*
- version: link:../visual-ir
- packages/performance-studio:
+ packages/package-loader-node:
dependencies:
- '@hypit/composition':
- specifier: workspace:*
- version: link:../composition
- '@hypit/media-track-studio':
- specifier: workspace:*
- version: link:../media-track-studio
- '@hypit/performance':
- specifier: workspace:*
- version: link:../performance
- '@hypit/studio-adapter':
+ '@hypit/component-kit':
specifier: workspace:*
- version: link:../studio-adapter
- '@hypit/temporal':
+ version: link:../component-kit
+ '@hypit/host':
specifier: workspace:*
- version: link:../temporal
- '@hypit/timeline':
+ version: link:../host
+ '@hypit/protocol':
specifier: workspace:*
- version: link:../timeline
+ version: link:../protocol
+ cjs-module-lexer:
+ specifier: 2.2.1
+ version: 2.2.1
+ typescript:
+ specifier: 5.9.3
+ version: 5.9.3
packages/pixverse:
dependencies:
@@ -2238,15 +2121,6 @@ importers:
specifier: workspace:*
version: link:../text
- packages/program-space:
- dependencies:
- '@hypit/markup':
- specifier: workspace:*
- version: link:../markup
- '@hypit/protocol':
- specifier: workspace:*
- version: link:../protocol
-
packages/project-context-node: {}
packages/protocol: {}
@@ -2370,9 +2244,9 @@ importers:
'@hypit/driver-node':
specifier: workspace:*
version: link:../driver-node
- '@hypit/program-space':
+ '@hypit/timeline':
specifier: workspace:*
- version: link:../program-space
+ version: link:../timeline
packages/provider-hypihub:
dependencies:
@@ -2486,9 +2360,9 @@ importers:
'@hypit/runtime-kit':
specifier: workspace:*
version: link:../runtime-kit
- '@hypit/speech':
+ '@hypit/speech-evidence':
specifier: workspace:*
- version: link:../speech
+ version: link:../speech-evidence
devDependencies:
'@hypit/driver-node':
specifier: workspace:*
@@ -2635,12 +2509,6 @@ importers:
'@hypit/media':
specifier: workspace:*
version: link:../media
- '@hypit/narrative':
- specifier: workspace:*
- version: link:../narrative
- '@hypit/program-space':
- specifier: workspace:*
- version: link:../program-space
'@hypit/protocol':
specifier: workspace:*
version: link:../protocol
@@ -2694,6 +2562,30 @@ importers:
specifier: workspace:*
version: link:../spatial
+ packages/region-track:
+ dependencies:
+ '@hypit/component-kit':
+ specifier: workspace:*
+ version: link:../component-kit
+ '@hypit/elaborator':
+ specifier: workspace:*
+ version: link:../elaborator
+ '@hypit/markup':
+ specifier: workspace:*
+ version: link:../markup
+ '@hypit/protocol':
+ specifier: workspace:*
+ version: link:../protocol
+ '@hypit/spatial':
+ specifier: workspace:*
+ version: link:../spatial
+ '@hypit/svs':
+ specifier: workspace:*
+ version: link:../svs
+ '@hypit/timeline':
+ specifier: workspace:*
+ version: link:../timeline
+
packages/render-hyperframes:
dependencies:
'@hypit/artifact':
@@ -2720,9 +2612,6 @@ importers:
'@hypit/media-pipeline':
specifier: workspace:*
version: link:../media-pipeline
- '@hypit/program-space':
- specifier: workspace:*
- version: link:../program-space
'@hypit/protocol':
specifier: workspace:*
version: link:../protocol
@@ -2857,6 +2746,9 @@ importers:
packages/runtime-local:
dependencies:
+ '@hypit/build-result':
+ specifier: workspace:*
+ version: link:../build-result
'@hypit/build-result-fs':
specifier: workspace:*
version: link:../build-result-fs
@@ -2903,9 +2795,6 @@ importers:
specifier: 3.2.1
version: 3.2.1
devDependencies:
- '@hypit/build-result':
- specifier: workspace:*
- version: link:../build-result
'@hypit/credential-store-env':
specifier: workspace:*
version: link:../credential-store-env
@@ -2924,12 +2813,6 @@ importers:
'@hypit/markup':
specifier: workspace:*
version: link:../markup
- '@hypit/narrative':
- specifier: workspace:*
- version: link:../narrative
- '@hypit/program-space':
- specifier: workspace:*
- version: link:../program-space
'@hypit/protocol':
specifier: workspace:*
version: link:../protocol
@@ -2982,12 +2865,18 @@ importers:
packages/script:
dependencies:
+ '@hypit/caption':
+ specifier: workspace:*
+ version: link:../caption
'@hypit/markup':
specifier: workspace:*
version: link:../markup
'@hypit/narrative':
specifier: workspace:*
version: link:../narrative
+ '@hypit/narrative-caption':
+ specifier: workspace:*
+ version: link:../narrative-caption
'@hypit/protocol':
specifier: workspace:*
version: link:../protocol
@@ -3068,78 +2957,6 @@ importers:
specifier: workspace:*
version: link:../text
- packages/semantic-take-adjust:
- dependencies:
- '@hypit/component-kit':
- specifier: workspace:*
- version: link:../component-kit
- '@hypit/elaborator':
- specifier: workspace:*
- version: link:../elaborator
- '@hypit/markup':
- specifier: workspace:*
- version: link:../markup
- '@hypit/narrative':
- specifier: workspace:*
- version: link:../narrative
- '@hypit/protocol':
- specifier: workspace:*
- version: link:../protocol
- '@hypit/speech':
- specifier: workspace:*
- version: link:../speech
-
- packages/sound:
- dependencies:
- '@hypit/component-kit':
- specifier: workspace:*
- version: link:../component-kit
- '@hypit/composition':
- specifier: workspace:*
- version: link:../composition
- '@hypit/elaborator':
- specifier: workspace:*
- version: link:../elaborator
- '@hypit/markup':
- specifier: workspace:*
- version: link:../markup
- '@hypit/narrative':
- specifier: workspace:*
- version: link:../narrative
- '@hypit/program-space':
- specifier: workspace:*
- version: link:../program-space
- '@hypit/protocol':
- specifier: workspace:*
- version: link:../protocol
- '@hypit/temporal':
- specifier: workspace:*
- version: link:../temporal
- '@hypit/temporal-markup':
- specifier: workspace:*
- version: link:../temporal-markup
- '@hypit/timeline':
- specifier: workspace:*
- version: link:../timeline
-
- packages/sound-studio:
- dependencies:
- '@hypit/composition':
- specifier: workspace:*
- version: link:../composition
- '@hypit/sound':
- specifier: workspace:*
- version: link:../sound
- '@hypit/studio-adapter':
- specifier: workspace:*
- version: link:../studio-adapter
- '@hypit/temporal':
- specifier: workspace:*
- version: link:../temporal
- '@hypit/timeline':
- specifier: workspace:*
- version: link:../timeline
-
packages/source:
dependencies:
'@hypit/protocol':
@@ -3160,9 +2977,6 @@ importers:
'@hypit/protocol':
specifier: workspace:*
version: link:../protocol
- '@hypit/svs':
- specifier: workspace:*
- version: link:../svs
devDependencies:
'@hypit/core':
specifier: workspace:*
@@ -3176,12 +2990,6 @@ importers:
'@hypit/component-kit':
specifier: workspace:*
version: link:../component-kit
- '@hypit/media':
- specifier: workspace:*
- version: link:../media
- '@hypit/narrative':
- specifier: workspace:*
- version: link:../narrative
'@hypit/protocol':
specifier: workspace:*
version: link:../protocol
@@ -3191,24 +2999,21 @@ importers:
'@hypit/component-kit':
specifier: workspace:*
version: link:../component-kit
- '@hypit/media':
- specifier: workspace:*
- version: link:../media
'@hypit/narrative':
specifier: workspace:*
version: link:../narrative
- '@hypit/program-space':
+ '@hypit/narrative-temporal':
specifier: workspace:*
- version: link:../program-space
+ version: link:../narrative-temporal
'@hypit/protocol':
specifier: workspace:*
version: link:../protocol
- '@hypit/speech':
- specifier: workspace:*
- version: link:../speech
'@hypit/speech-evidence':
specifier: workspace:*
version: link:../speech-evidence
+ '@hypit/temporal':
+ specifier: workspace:*
+ version: link:../temporal
devDependencies:
'@hypit/script':
specifier: workspace:*
@@ -3216,9 +3021,16 @@ importers:
packages/speech-evidence:
dependencies:
+ '@hypit/component-kit':
+ specifier: workspace:*
+ version: link:../component-kit
'@hypit/protocol':
specifier: workspace:*
version: link:../protocol
+ devDependencies:
+ '@hypit/timeline':
+ specifier: workspace:*
+ version: link:../timeline
packages/store-sqlite:
dependencies:
@@ -3261,9 +3073,9 @@ importers:
'@hypit/core':
specifier: workspace:*
version: link:../core
- '@hypit/deck-track-studio':
+ '@hypit/depth-stack-studio':
specifier: workspace:*
- version: link:../deck-track-studio
+ version: link:../depth-stack-studio
'@hypit/driver-node':
specifier: workspace:*
version: link:../driver-node
@@ -3279,18 +3091,15 @@ importers:
'@hypit/markup':
specifier: workspace:*
version: link:../markup
- '@hypit/media-track-studio':
+ '@hypit/media-pipeline':
+ specifier: workspace:*
+ version: link:../media-pipeline
+ '@hypit/narrative-temporal':
specifier: workspace:*
- version: link:../media-track-studio
+ version: link:../narrative-temporal
'@hypit/package-loader-node':
specifier: workspace:*
version: link:../package-loader-node
- '@hypit/performance-studio':
- specifier: workspace:*
- version: link:../performance-studio
- '@hypit/program-space':
- specifier: workspace:*
- version: link:../program-space
'@hypit/project-context-node':
specifier: workspace:*
version: link:../project-context-node
@@ -3315,9 +3124,6 @@ importers:
'@hypit/script-studio':
specifier: workspace:*
version: link:../script-studio
- '@hypit/sound-studio':
- specifier: workspace:*
- version: link:../sound-studio
'@hypit/speech':
specifier: workspace:*
version: link:../speech
@@ -3333,15 +3139,18 @@ importers:
'@hypit/timeline':
specifier: workspace:*
version: link:../timeline
- '@hypit/typography-track-studio':
+ '@hypit/text-fine-studio':
specifier: workspace:*
- version: link:../typography-track-studio
+ version: link:../text-fine-studio
'@hypit/validation':
specifier: workspace:*
version: link:../validation
'@hypit/video-cli':
specifier: workspace:*
version: link:../video-cli
+ '@hypit/visual-track-studio':
+ specifier: workspace:*
+ version: link:../visual-track-studio
'@hypit/workspace':
specifier: workspace:*
version: link:../workspace
@@ -3382,12 +3191,6 @@ importers:
'@hypit/component-kit':
specifier: workspace:*
version: link:../component-kit
- '@hypit/narrative':
- specifier: workspace:*
- version: link:../narrative
- '@hypit/program-space':
- specifier: workspace:*
- version: link:../program-space
'@hypit/protocol':
specifier: workspace:*
version: link:../protocol
@@ -3403,12 +3206,6 @@ importers:
'@hypit/markup':
specifier: workspace:*
version: link:../markup
- '@hypit/narrative':
- specifier: workspace:*
- version: link:../narrative
- '@hypit/program-space':
- specifier: workspace:*
- version: link:../program-space
'@hypit/temporal':
specifier: workspace:*
version: link:../temporal
@@ -3442,24 +3239,9 @@ importers:
'@hypit/component-kit':
specifier: workspace:*
version: link:../component-kit
- '@hypit/composition':
- specifier: workspace:*
- version: link:../composition
- '@hypit/media':
- specifier: workspace:*
- version: link:../media
- '@hypit/narrative':
- specifier: workspace:*
- version: link:../narrative
- '@hypit/program-space':
- specifier: workspace:*
- version: link:../program-space
'@hypit/protocol':
specifier: workspace:*
version: link:../protocol
- '@hypit/speech':
- specifier: workspace:*
- version: link:../speech
packages/timeline-author:
dependencies:
@@ -3472,15 +3254,9 @@ importers:
'@hypit/markup':
specifier: workspace:*
version: link:../markup
- '@hypit/program-space':
- specifier: workspace:*
- version: link:../program-space
'@hypit/protocol':
specifier: workspace:*
version: link:../protocol
- '@hypit/speech':
- specifier: workspace:*
- version: link:../speech
'@hypit/temporal':
specifier: workspace:*
version: link:../temporal
@@ -3513,7 +3289,7 @@ importers:
specifier: workspace:*
version: link:../protocol
- packages/typography-track:
+ packages/text-fine:
dependencies:
'@hypit/component-kit':
specifier: workspace:*
@@ -3530,12 +3306,6 @@ importers:
'@hypit/media':
specifier: workspace:*
version: link:../media
- '@hypit/narrative':
- specifier: workspace:*
- version: link:../narrative
- '@hypit/program-space':
- specifier: workspace:*
- version: link:../program-space
'@hypit/protocol':
specifier: workspace:*
version: link:../protocol
@@ -3568,7 +3338,7 @@ importers:
specifier: workspace:*
version: link:../validation
- packages/typography-track-studio:
+ packages/text-fine-studio:
dependencies:
'@hypit/composition':
specifier: workspace:*
@@ -3579,9 +3349,9 @@ importers:
'@hypit/studio-adapter':
specifier: workspace:*
version: link:../studio-adapter
- '@hypit/typography-track':
+ '@hypit/text-fine':
specifier: workspace:*
- version: link:../typography-track
+ version: link:../text-fine
packages/validation:
dependencies:
@@ -3706,6 +3476,66 @@ importers:
specifier: workspace:*
version: link:../protocol
+ packages/visual-track:
+ dependencies:
+ '@hypit/artifact':
+ specifier: workspace:*
+ version: link:../artifact
+ '@hypit/component-kit':
+ specifier: workspace:*
+ version: link:../component-kit
+ '@hypit/composition':
+ specifier: workspace:*
+ version: link:../composition
+ '@hypit/elaborator':
+ specifier: workspace:*
+ version: link:../elaborator
+ '@hypit/markup':
+ specifier: workspace:*
+ version: link:../markup
+ '@hypit/media':
+ specifier: workspace:*
+ version: link:../media
+ '@hypit/protocol':
+ specifier: workspace:*
+ version: link:../protocol
+ '@hypit/spatial':
+ specifier: workspace:*
+ version: link:../spatial
+ '@hypit/svs':
+ specifier: workspace:*
+ version: link:../svs
+ '@hypit/temporal':
+ specifier: workspace:*
+ version: link:../temporal
+ '@hypit/temporal-markup':
+ specifier: workspace:*
+ version: link:../temporal-markup
+ '@hypit/timeline':
+ specifier: workspace:*
+ version: link:../timeline
+ '@hypit/visual-ir':
+ specifier: workspace:*
+ version: link:../visual-ir
+
+ packages/visual-track-studio:
+ dependencies:
+ '@hypit/composition':
+ specifier: workspace:*
+ version: link:../composition
+ '@hypit/protocol':
+ specifier: workspace:*
+ version: link:../protocol
+ '@hypit/studio-adapter':
+ specifier: workspace:*
+ version: link:../studio-adapter
+ '@hypit/temporal':
+ specifier: workspace:*
+ version: link:../temporal
+ '@hypit/visual-track':
+ specifier: workspace:*
+ version: link:../visual-track
+
packages/volcengine-matting:
dependencies:
'@hypit/artifact':
@@ -3765,22 +3595,25 @@ importers:
'@hypit/narrative':
specifier: workspace:*
version: link:../narrative
+ '@hypit/narrative-temporal':
+ specifier: workspace:*
+ version: link:../narrative-temporal
'@hypit/protocol':
specifier: workspace:*
version: link:../protocol
- '@hypit/speech':
- specifier: workspace:*
- version: link:../speech
'@hypit/speech-alignment':
specifier: workspace:*
version: link:../speech-alignment
'@hypit/speech-evidence':
specifier: workspace:*
version: link:../speech-evidence
+ '@hypit/temporal':
+ specifier: workspace:*
+ version: link:../temporal
devDependencies:
- '@hypit/program-space':
+ '@hypit/timeline':
specifier: workspace:*
- version: link:../program-space
+ version: link:../timeline
packages/workspace:
dependencies:
diff --git a/test/narrative-caption.test.ts b/test/narrative-caption.test.ts
new file mode 100644
index 00000000..7be7643d
--- /dev/null
+++ b/test/narrative-caption.test.ts
@@ -0,0 +1,115 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { mediaLocalTemporalDomain } from "@hypit/media";
+import type { Narrative } from "@hypit/narrative";
+import { captionUnitsForNarrativeSelection, projectNarrativeCaptionTiming } from "@hypit/narrative-caption";
+import { captionDocument, narrativeCaptionBinding, narrativeValue, parseScript } from "@hypit/script";
+import { createNarrativeProjection, projectNarrativeAlignment, selectionFrameSpan } from "@hypit/narrative-temporal";
+import { alignNarrative } from "@hypit/speech-alignment";
+import type { Timeline } from "@hypit/timeline";
+import { interpretWhisperXTranscript } from "@hypit/whisperx";
+
+import { fixtureResource } from "./fixture-resource.js";
+
+test("Caption uses complete Narrative selections and authored cue breaks", () => {
+ const parsed = parseScript("caption.svml", "<line>one @{focus} two three @{/focus} || four</line>");
+ const narrative = narrativeValue(parsed, "story") as unknown as Narrative;
+ const document = captionDocument(parsed, "story.caption", "story");
+ const binding = narrativeCaptionBinding(parsed, "story.caption", "story");
+ const selection = narrative.selections[0]!;
+ const subset = captionUnitsForNarrativeSelection(document, binding, narrative, selection);
+ assert.equal(subset.unitIds.length, 2);
+ assert.equal(document.cueBreaks.length, 1);
+});
+
+test("Caption selects complete Segments and the program through structural anchors", () => {
+ const parsed = parseScript("caption-ranges.svml", `@{~whole}
+@{opening} <intro><HOST>One idea.</intro> @{/opening}
+<answer><GUEST>Another view.</answer>
+@{/whole~}`);
+ const narrative = narrativeValue(parsed, "story") as unknown as Narrative;
+ const document = captionDocument(parsed, "story.caption", "story");
+ const binding = narrativeCaptionBinding(parsed, "story.caption", "story");
+ const whole = narrative.selections.find((selection) => selection.id === "whole")!;
+ const opening = narrative.selections.find((selection) => selection.id === "opening")!;
+ assert.deepEqual(captionUnitsForNarrativeSelection(document, binding, narrative, whole).unitIds,
+ document.units.map((unit) => unit.id));
+ assert.deepEqual(captionUnitsForNarrativeSelection(document, binding, narrative, opening).unitIds,
+ document.units.filter((unit) => unit.groupId?.startsWith("intro:")).map((unit) => unit.id));
+});
+
+for (const grouped of [false, true]) test(`Chinese Script projects Caption timing through explicit alignments and domain Windows (shared groups: ${grouped})`, () => {
+ const parsed = parseScript("mixed-zh.svml", `<opening><HOST>用@{brand} ElevenLabs @{/brand}做${grouped ? '<视频|>' : '视频'},|| 真方便。</opening>
+<answer><GUEST>今年<2026|二零二六>年,這個很好。</answer>`);
+ const narrative = narrativeValue(parsed, "story") as unknown as Narrative;
+ const document = captionDocument(parsed, "story.caption", "story");
+ const binding = narrativeCaptionBinding(parsed, "story.caption", "story");
+ const phrases = ["用ElevenLabs做视频真方便", "今年二零二六年这个很好"];
+ const durations = [4000, 3000];
+ const timeline: Timeline = { id: "speech", frameRate: { numerator: 1000, denominator: 1 }, frameCount: 7000 };
+ const evidenceWindows: Array<Array<[number, number]>> = [];
+ const entries = [] as Parameters<typeof createNarrativeProjection>[3][number][];
+ let targetStartFrame = 0;
+
+ for (const [index, segment] of narrative.segments.entries()) {
+ let cursor = 100;
+ const words = [...phrases[index]!].map((word, characterIndex) => {
+ const start = cursor;
+ cursor += characterIndex % 3 === 0 ? 190 : 90;
+ const end = cursor;
+ cursor += characterIndex % 4 === 0 ? 80 : 20;
+ return { word, start: start / 1000, end: end / 1000 };
+ });
+ evidenceWindows.push(words.map((word) => [Math.round(word.start * 1000), Math.round(word.end * 1000)]));
+ const frameCount = durations[index]!;
+ const sampleFrames = frameCount * 16;
+ const media = {
+ frameDomain: { frameRate: timeline.frameRate, frameCount },
+ audio: { artifact: { kind: "blob" as const, resource: fixtureResource(`zh:${index}`), size: 1, mediaType: "audio/wav" } },
+ };
+ const domain = mediaLocalTemporalDomain(`zh:${index}:domain`, media);
+ const excerpt = { narrativeId: narrative.id, kind: "segment" as const, id: segment.id,
+ tokenStart: segment.tokenStart, tokenEndExclusive: segment.tokenEndExclusive };
+ const alignment = alignNarrative(narrative, excerpt, domain, {
+ domainId: domain.id,
+ sampleFrames,
+ passages: interpretWhisperXTranscript({ language: "zh", segments: [{ start: 0, end: frameCount / 1000, words }] }, sampleFrames),
+ });
+ const endFrameExclusive = targetStartFrame + frameCount;
+ const window = {
+ id: `zh:${index}:window`, subjectId: segment.id,
+ start: { id: `zh:${index}:start`, subjectId: segment.id, timelineId: timeline.id, frame: targetStartFrame },
+ end: { id: `zh:${index}:end`, subjectId: segment.id, timelineId: timeline.id, frame: endFrameExclusive },
+ span: { startFrame: targetStartFrame, endFrameExclusive },
+ };
+ entries.push(projectNarrativeAlignment(alignment, domain, window, timeline));
+ targetStartFrame += frameCount;
+ }
+
+ const narrativeProjection = createNarrativeProjection("speech-semantic", narrative.id, timeline, entries);
+ const timing = projectNarrativeCaptionTiming(document, binding, narrativeProjection);
+ const wordText = new Map(document.words.map((word) => [word.id, word.text]));
+ const unitText = new Map(document.units.map((unit) => [unit.id, unit.wordIds.map((id) => wordText.get(id)!).join("")]));
+ assert.deepEqual(timing.cues.map((cue) => cue.units.map((unit) => unitText.get(unit.unitId)).join("")),
+ ["用ElevenLabs做视频,", "真方便。", "今年2026年,這個很好。"]);
+ const units = timing.cues.flatMap((cue) => cue.units);
+ const windowsFor = (text: string) => units.filter((unit) => unitText.get(unit.unitId) === text)
+ .map((unit) => [unit.startFrame, unit.endFrameExclusive]);
+ const first = evidenceWindows[0]!;
+ assert.deepEqual(windowsFor("用"), [first[0]]);
+ assert.deepEqual(windowsFor("ElevenLabs"), [[first[1]![0], first[10]![1]]]);
+ assert.deepEqual(windowsFor("做"), [first[11]]);
+ if (grouped) assert.deepEqual(windowsFor("视频,"), [[first[12]![0], first[13]![1]]]);
+ const alignedFirst = entries[0]!;
+ const framesByBoundary = new Map(alignedFirst.boundaries.map((boundary) => [boundary.id, boundary.frame]));
+ assert.deepEqual(alignedFirst.tokens.filter((token) => ["做", "视", "频"].includes(token.text))
+ .map((token) => [framesByBoundary.get(token.startBoundaryId), framesByBoundary.get(token.endBoundaryId)]), first.slice(11, 14));
+ assert.deepEqual(selectionFrameSpan(narrativeProjection, { ...narrative.selections[0]!, narrativeId: narrative.id }),
+ { startFrame: first[1]![0], endFrameExclusive: first[10]![1] });
+ const second = evidenceWindows[1]!;
+ assert.deepEqual(windowsFor("2026"), [[4000 + second[2]![0], 4000 + second[5]![1]]]);
+ assert.deepEqual(windowsFor("這"), [[4000 + second[7]![0], 4000 + second[7]![1]]]);
+ assert.deepEqual(windowsFor("個"), [[4000 + second[8]![0], 4000 + second[8]![1]]]);
+ assert.equal(document.units[0]!.role, "HOST");
+});
diff --git a/test/support/video-domain.ts b/test/support/video-domain.ts
index 2f193a81..207678f1 100644
--- a/test/support/video-domain.ts
+++ b/test/support/video-domain.ts
@@ -2,10 +2,11 @@ import { artifactManifest } from "@hypit/artifact";
import { compositionComponent, compositionManifest } from "@hypit/composition";
import { mediaComponent, mediaManifest } from "@hypit/media";
import { narrativeManifest } from "@hypit/narrative";
-import { programSpaceManifest } from "@hypit/program-space";
+import { narrativeTemporalManifest } from "@hypit/narrative-temporal";
import { timelineManifest } from "@hypit/timeline";
import { spatialComponent, spatialManifest } from "@hypit/spatial";
import { speechManifest } from "@hypit/speech";
+import { speechAlignmentManifest } from "@hypit/speech-alignment";
import { speechEvidenceManifest } from "@hypit/speech-evidence";
import { svsManifest } from "@hypit/svs";
import { temporalManifest } from "@hypit/temporal";
@@ -15,9 +16,10 @@ import { visualIrManifest } from "@hypit/visual-ir";
export const videoContractManifests = [
artifactManifest,
narrativeManifest,
+ narrativeTemporalManifest,
mediaManifest,
- programSpaceManifest,
speechManifest,
+ speechAlignmentManifest,
speechEvidenceManifest,
svsManifest,
timelineManifest,
diff --git a/test/temporal-fixture.ts b/test/temporal-fixture.ts
index 6e52ce26..1b64d8e1 100644
--- a/test/temporal-fixture.ts
+++ b/test/temporal-fixture.ts
@@ -1,21 +1,22 @@
-import { projectTimelineSpace } from "@hypit/timeline";
import type { NarrativeExcerpt, NarrativeMomentRef, NarrativeSelectionRef } from "@hypit/narrative";
import type { Timeline } from "@hypit/timeline";
import {
composeTemporalWindow,
- projectMomentInstant,
projectProgramInstant,
- projectSegmentInstant,
- projectSelectionInstant,
} from "@hypit/temporal";
import type { TemporalInstantExpression } from "@hypit/temporal";
+import { projectNarrativeInstant } from "@hypit/narrative-temporal";
+import type { NarrativeProjection } from "@hypit/narrative-temporal";
export type TemporalWindowProjection = {
readonly start: TemporalInstantExpression;
readonly end: TemporalInstantExpression;
};
-
-const fixed = { kind: "fixed" as const };
+type NarrativeInstantExpression = {
+ readonly ref: "selection.start" | "selection.end" | "segment.start" | "segment.end" | "moment.cue";
+ readonly offset?: import("@hypit/temporal").TemporalDuration;
+};
+type NarrativeWindowProjection = { readonly start: NarrativeInstantExpression; readonly end: NarrativeInstantExpression };
export function projectProgramInstantFixture(input: {
readonly itemId: string;
@@ -23,17 +24,20 @@ export function projectProgramInstantFixture(input: {
readonly semantic: Timeline;
readonly projection: TemporalInstantExpression;
}) {
- return projectProgramInstant({ ...input, timeline: input.semantic, subjectId: input.subjectId ?? input.itemId, authority: fixed });
+ return projectProgramInstant({ ...input, timeline: input.semantic, subjectId: input.subjectId ?? input.itemId });
}
export function projectMomentInstantFixture(input: {
readonly itemId: string;
readonly subjectId?: string;
readonly semantic: Timeline;
+ readonly narrative: NarrativeProjection;
readonly moment: NarrativeMomentRef;
- readonly projection: TemporalInstantExpression;
+ readonly projection: NarrativeInstantExpression;
}) {
- return projectMomentInstant({ ...input, timeline: input.semantic, subjectId: input.subjectId ?? input.itemId, authority: fixed });
+ return projectNarrativeInstant({ timeline: input.semantic, narrative: input.narrative,
+ source: input.moment, sourceKind: "moment", spec: { id: input.itemId, subjectId: input.subjectId ?? input.itemId,
+ boundary: "cue", ...(input.projection.offset === undefined ? {} : { offset: input.projection.offset }) } });
}
export function projectProgramWindow(input: {
@@ -44,45 +48,60 @@ export function projectProgramWindow(input: {
}) {
const subjectId = input.subjectId ?? input.itemId;
return composeTemporalWindow({ id: input.itemId, subjectId },
- projectProgramInstant({ itemId: `${input.itemId}.start`, subjectId, timeline: input.semantic, projection: input.projection.start, authority: fixed }),
- projectProgramInstant({ itemId: `${input.itemId}.end`, subjectId, timeline: input.semantic, projection: input.projection.end, authority: fixed }));
+ projectProgramInstant({ itemId: `${input.itemId}.start`, subjectId, timeline: input.semantic, projection: input.projection.start }),
+ projectProgramInstant({ itemId: `${input.itemId}.end`, subjectId, timeline: input.semantic, projection: input.projection.end }));
}
export function projectSelectionWindow(input: {
readonly itemId: string;
readonly subjectId?: string;
readonly semantic: Timeline;
+ readonly narrative: NarrativeProjection;
readonly selection: NarrativeSelectionRef;
- readonly projection: TemporalWindowProjection;
+ readonly projection: NarrativeWindowProjection;
}) {
const subjectId = input.subjectId ?? input.itemId;
return composeTemporalWindow({ id: input.itemId, subjectId },
- projectSelectionInstant({ itemId: `${input.itemId}.start`, subjectId, timeline: input.semantic, selection: input.selection, projection: input.projection.start, authority: fixed }),
- projectSelectionInstant({ itemId: `${input.itemId}.end`, subjectId, timeline: input.semantic, selection: input.selection, projection: input.projection.end, authority: fixed }));
+ projectNarrativeInstant({ timeline: input.semantic, narrative: input.narrative,
+ source: input.selection, sourceKind: "selection", spec: narrativeSpec(`${input.itemId}.start`, subjectId, input.projection.start) }),
+ projectNarrativeInstant({ timeline: input.semantic, narrative: input.narrative,
+ source: input.selection, sourceKind: "selection", spec: narrativeSpec(`${input.itemId}.end`, subjectId, input.projection.end) }));
}
export function projectSegmentWindow(input: {
readonly itemId: string;
readonly subjectId?: string;
readonly semantic: Timeline;
+ readonly narrative: NarrativeProjection;
readonly segment: NarrativeExcerpt;
- readonly projection: TemporalWindowProjection;
+ readonly projection: NarrativeWindowProjection;
}) {
const subjectId = input.subjectId ?? input.itemId;
return composeTemporalWindow({ id: input.itemId, subjectId },
- projectSegmentInstant({ itemId: `${input.itemId}.start`, subjectId, timeline: input.semantic, segment: input.segment, projection: input.projection.start, authority: fixed }),
- projectSegmentInstant({ itemId: `${input.itemId}.end`, subjectId, timeline: input.semantic, segment: input.segment, projection: input.projection.end, authority: fixed }));
+ projectNarrativeInstant({ timeline: input.semantic, narrative: input.narrative,
+ source: input.segment, sourceKind: "segment", spec: narrativeSpec(`${input.itemId}.start`, subjectId, input.projection.start) }),
+ projectNarrativeInstant({ timeline: input.semantic, narrative: input.narrative,
+ source: input.segment, sourceKind: "segment", spec: narrativeSpec(`${input.itemId}.end`, subjectId, input.projection.end) }));
}
export function projectMomentWindow(input: {
readonly itemId: string;
readonly subjectId?: string;
readonly semantic: Timeline;
+ readonly narrative: NarrativeProjection;
readonly moment: NarrativeMomentRef;
- readonly projection: TemporalWindowProjection;
+ readonly projection: NarrativeWindowProjection;
}) {
const subjectId = input.subjectId ?? input.itemId;
return composeTemporalWindow({ id: input.itemId, subjectId },
- projectMomentInstant({ itemId: `${input.itemId}.start`, subjectId, timeline: input.semantic, moment: input.moment, projection: input.projection.start, authority: fixed }),
- projectMomentInstant({ itemId: `${input.itemId}.end`, subjectId, timeline: input.semantic, moment: input.moment, projection: input.projection.end, authority: fixed }));
+ projectNarrativeInstant({ timeline: input.semantic, narrative: input.narrative,
+ source: input.moment, sourceKind: "moment", spec: narrativeSpec(`${input.itemId}.start`, subjectId, input.projection.start) }),
+ projectNarrativeInstant({ timeline: input.semantic, narrative: input.narrative,
+ source: input.moment, sourceKind: "moment", spec: narrativeSpec(`${input.itemId}.end`, subjectId, input.projection.end) }));
+}
+
+function narrativeSpec(id: string, subjectId: string, expression: NarrativeInstantExpression) {
+ return { id, subjectId,
+ boundary: expression.ref === "moment.cue" ? "cue" as const : expression.ref.endsWith(".start") ? "start" as const : "end" as const,
+ ...(expression.offset === undefined ? {} : { offset: expression.offset }) };
}
diff --git a/test/timeline-fixture.ts b/test/timeline-fixture.ts
index 13288be5..de0c8a2c 100644
--- a/test/timeline-fixture.ts
+++ b/test/timeline-fixture.ts
@@ -1,81 +1,92 @@
-import type { ProgramSpace } from "@hypit/program-space";
+import { sealTimeline } from "@hypit/timeline";
import type { Timeline } from "@hypit/timeline";
+import { createNarrativeProjection, projectNarrativeAlignment } from "@hypit/narrative-temporal";
+import type { NarrativeProjection } from "@hypit/narrative-temporal";
-type FixtureSegment = {
- readonly id: string;
- readonly frameCount: number;
-};
+type FixtureSegment = { readonly id: string; readonly frameCount: number };
+type FixtureAnchor = { readonly identity: string; readonly frame: number };
-type FixtureAnchor = {
- readonly identity: string;
- readonly frame: number;
-};
-
-const audioArtifact = {
- kind: "blob" as const,
- resource: "res_timeline-fixture" as const,
- size: 1,
- mediaType: "audio/wav",
-};
-
-/** Minimal real Timeline for tests whose subject is timing rather than speech recognition. */
+/**
+ * Minimal absolute Timeline for tests whose subject is not timeline construction.
+ * Semantic fixture data is deliberately not embedded; use the projection helper
+ * when a test actually needs Narrative boundaries.
+ */
export function timelineFixture(
- space: ProgramSpace,
+ space: {
+ readonly id: string;
+ readonly frameRate: Timeline["frameRate"];
+ readonly frameCount?: number;
+ readonly durationSec?: number;
+ },
options: {
readonly id?: string;
readonly narrativeId?: string;
readonly segments?: readonly FixtureSegment[];
readonly anchors?: readonly FixtureAnchor[];
} = {},
-): Timeline & { readonly narrativeId: string } {
- const totalFrames = Math.round(space.durationSec * space.frameRate.numerator / space.frameRate.denominator);
- const segments = options.segments ?? [{ id: "fixture", frameCount: totalFrames }];
- if (segments.reduce((sum, segment) => sum + segment.frameCount, 0) !== totalFrames) {
- throw new Error("Timeline fixture segments must fill ProgramSpace exactly.");
+): Timeline {
+ const frameCount = space.frameCount ?? Math.round(
+ (space.durationSec ?? 0) * space.frameRate.numerator / space.frameRate.denominator,
+ );
+ if (!Number.isSafeInteger(frameCount) || frameCount < 1) {
+ throw new Error("Timeline fixture requires a positive exact frame count.");
+ }
+ if (options.segments !== undefined
+ && options.segments.reduce((sum, segment) => sum + segment.frameCount, 0) !== frameCount) {
+ throw new Error("Timeline fixture segments must fill Timeline exactly.");
}
- const anchors = options.anchors ?? [];
- const structuralAnchorIds = new Set(segments.flatMap((segment) => [
- `segment:${segment.id}:start`,
- `segment:${segment.id}:end`,
- ]));
- let startFrame = 0;
- return {
- // A Timeline is the author-visible identity of the ProgramSpace it projects.
- ...space,
- id: options.id ?? space.id,
- narrativeId: options.narrativeId ?? "script",
- items: segments.map((segment, index) => {
- const endFrameExclusive = startFrame + segment.frameCount;
- const startAnchorId = `segment:${segment.id}:start`;
- const endAnchorId = `segment:${segment.id}:end`;
- const localAnchors = anchors
- .filter((anchor) => !structuralAnchorIds.has(anchor.identity)
- && anchor.frame >= startFrame
- && (index === segments.length - 1 ? anchor.frame <= endFrameExclusive : anchor.frame < endFrameExclusive))
- .map((anchor) => ({ identity: anchor.identity, frame: anchor.frame - startFrame }));
- const take = {
- narrativeId: options.narrativeId ?? "script",
- media: {
- timeline: { frameRate: space.frameRate, frameCount: segment.frameCount },
- audio: { artifact: audioArtifact },
- },
- segment: {
- segmentId: segment.id,
- startAnchorId,
- endAnchorId,
- startFrame: 0,
- endFrameExclusive: segment.frameCount,
- },
- tokens: [],
- anchors: [
- { identity: startAnchorId, frame: 0 },
- { identity: endAnchorId, frame: segment.frameCount },
- ...localAnchors.filter((anchor) => anchor.identity !== startAnchorId && anchor.identity !== endAnchorId),
- ],
- };
- const placement = { take, startFrame };
- startFrame = endFrameExclusive;
- return placement;
- }),
- };
+ for (const anchor of options.anchors ?? []) {
+ if (!Number.isSafeInteger(anchor.frame) || anchor.frame < 0 || anchor.frame > frameCount) {
+ throw new Error(`Timeline fixture anchor ${anchor.identity} is outside the Timeline.`);
+ }
+ }
+ return sealTimeline({ id: options.id ?? space.id, frameRate: space.frameRate, frameCount });
+}
+
+/** Explicit semantic relation for tests that actually exercise Narrative projection. */
+export function narrativeProjectionFixture(
+ timeline: Timeline,
+ options: {
+ readonly id?: string;
+ readonly narrativeId?: string;
+ readonly segments: readonly FixtureSegment[];
+ readonly anchors?: readonly FixtureAnchor[];
+ },
+): NarrativeProjection {
+ const narrativeId = options.narrativeId ?? "test-narrative";
+ let cursor = 0;
+ const unassigned = [...(options.anchors ?? [])];
+ const entries = options.segments.map((segment) => {
+ const startFrame = cursor;
+ const endFrameExclusive = startFrame + segment.frameCount;
+ cursor = endFrameExclusive;
+ const claimed = unassigned.filter((anchor) => anchor.identity.startsWith(`segment:${segment.id}:`)
+ ? anchor.frame >= startFrame && anchor.frame <= endFrameExclusive
+ : anchor.frame > startFrame && anchor.frame <= endFrameExclusive || startFrame === 0 && anchor.frame === 0);
+ for (const anchor of claimed) unassigned.splice(unassigned.indexOf(anchor), 1);
+ const startBoundaryId = `segment:${segment.id}:start`;
+ const endBoundaryId = `segment:${segment.id}:end`;
+ const boundaries = [
+ ...claimed.map((anchor) => ({ id: anchor.identity, frame: anchor.frame - startFrame })),
+ ...(claimed.some((anchor) => anchor.identity === startBoundaryId) ? [] : [{ id: startBoundaryId, frame: 0 }]),
+ ...(claimed.some((anchor) => anchor.identity === endBoundaryId) ? [] : [{ id: endBoundaryId, frame: segment.frameCount }]),
+ ];
+ const domainId = `fixture:${segment.id}:domain`;
+ const domain = { id: domainId, frameRate: timeline.frameRate, frameCount: segment.frameCount };
+ const window = {
+ id: `fixture:${segment.id}:window`, subjectId: segment.id,
+ start: { id: `fixture:${segment.id}:start`, subjectId: segment.id, timelineId: timeline.id, frame: startFrame },
+ end: { id: `fixture:${segment.id}:end`, subjectId: segment.id, timelineId: timeline.id, frame: endFrameExclusive },
+ span: { startFrame, endFrameExclusive },
+ };
+ return projectNarrativeAlignment(
+ { narrativeId, domainId, segment: { segmentId: segment.id, startBoundaryId, endBoundaryId }, tokens: [], boundaries },
+ domain,
+ window,
+ timeline,
+ );
+ });
+ if (cursor !== timeline.frameCount) throw new Error("Narrative projection fixture segments must fill Timeline exactly.");
+ if (unassigned.length > 0) throw new Error(`Narrative projection fixture cannot place ${unassigned[0]!.identity}.`);
+ return createNarrativeProjection(options.id ?? `${timeline.id}:narrative`, narrativeId, timeline, entries);
}