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.

feat(caption-fine): add tracked cue presentation

kashorinedddf3b612a8
diff --git a/docs/quickstart/tracks.md b/docs/quickstart/tracks.md
index ca3847bb..31e75d4f 100644
--- a/docs/quickstart/tracks.md
+++ b/docs/quickstart/tracks.md
@@ -58,7 +58,9 @@ caption.primary {
active-box-background: #FFD54ACC; active-box-padding: 4 8; active-box-radius: 8;
active-underline: current; active-underline-color: #FFFFFF;
active-underline-thickness: 3; active-underline-offset: 5;
- cue-enter: fade; cue-enter-frames: 4; cue-exit: fade; cue-exit-frames: 4;
+ cue-enter: spring; cue-enter-frames: 4;
+ cue-enter-start-scale: 0.75;
+ cue-exit: none; cue-exit-frames: 0;
atom-reveal: all;
active-response: pop; active-response-frames: 5; active-scale: 1.08;
lead-frames: 4; tail-frames: 4; handoff: cut;
diff --git a/packages/caption-fine-studio/src/index.ts b/packages/caption-fine-studio/src/index.ts
index 1c4e4dd6..09f40413 100644
--- a/packages/caption-fine-studio/src/index.ts
+++ b/packages/caption-fine-studio/src/index.ts
@@ -66,7 +66,9 @@ placeCaption([
"active-box-border-width", "active-box-padding", "active-box-radius",
], "how", "decoration", "decoration");
placeCaption(["lead-frames", "tail-frames", "handoff"], "when", "cue", "envelope");
-placeCaption(["cue-enter", "cue-enter-frames", "cue-exit", "cue-exit-frames"], "when", "cue", "cue");
+placeCaption([
+ "cue-enter", "cue-enter-frames", "cue-enter-start-scale", "cue-exit", "cue-exit-frames",
+], "when", "cue", "cue");
placeCaption([
"karaoke", "karaoke-transition", "active-underline", "active-box", "active-box-continuity", "active-box-enter",
"active-box-exit", "active-box-transition-frames", "atom-enter", "atom-enter-frames", "atom-exit", "atom-exit-frames",
diff --git a/packages/caption-fine/README.md b/packages/caption-fine/README.md
index 7c3bd6a0..55c844c4 100644
--- a/packages/caption-fine/README.md
+++ b/packages/caption-fine/README.md
@@ -11,6 +11,24 @@ does not carry a private visual role.
semantic={speech.semantic} program={captions}/>
```
+An optional Spatial Region Timeline replaces only the moving placement point:
+
+```xml
+<space:RegionTimeline id="heads" within={vertical} recipe={tracking.heads.default}/>
+<caption-fine:Track id="captions-track" document={story.caption}
+ semantic={speech.semantic} program={captions} regions={heads}/>
+```
+
+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
+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;
+anchor-y: bottom` puts the Caption immediately above a measured region. The Timeline is finished
+external evidence: Fine does not detect people, associate identities, smooth motion, interpolate
+missing Frames or invoke a Provider. Without `regions`, the ordinary Recipe `x` and `y` behavior is
+unchanged.
+
One SVS Recipe freezes three public dimensions:
- **Where**: Region position, anchors, extent, block/inline alignment, wrapping and line limits.
@@ -41,6 +59,9 @@ caption.primary {
size: 58; line-height: 1; fill: #FFFFFF;
background: #00000000; padding: 0; radius: 0;
karaoke: current; active-fill: #FFD54A;
+ cue-enter: spring; cue-enter-frames: 4;
+ cue-enter-start-scale: 0.75;
+ cue-exit: none;
lead-frames: 4; tail-frames: 4; handoff: cut;
}
```
diff --git a/packages/caption-fine/package.json b/packages/caption-fine/package.json
index b03a1ad1..3938d09d 100644
--- a/packages/caption-fine/package.json
+++ b/packages/caption-fine/package.json
@@ -20,6 +20,7 @@
"@hypit/program-space": "workspace:*",
"@hypit/protocol": "workspace:*",
"@hypit/semantic-track": "workspace:*",
+ "@hypit/spatial": "workspace:*",
"@hypit/svs": "workspace:*",
"@hypit/markup": "workspace:*"
},
diff --git a/packages/caption-fine/src/component.ts b/packages/caption-fine/src/component.ts
index 538f6ed7..330a1309 100644
--- a/packages/caption-fine/src/component.ts
+++ b/packages/caption-fine/src/component.ts
@@ -4,6 +4,7 @@ import type { CaptionDocument } from "@hypit/narrative";
import type { ProgramSpace } from "@hypit/program-space";
import type { StoredValue } from "@hypit/protocol";
import { canonicalize } from "@hypit/protocol";
+import type { SpatialRegionTimeline } from "@hypit/spatial";
import { captionFineProducers } from "./manifest.js";
import { renderFineCaption } from "./render.js";
@@ -40,5 +41,18 @@ export const captionFineComponent = {
needs: {},
}),
},
+ {
+ producer: captionFineProducers.renderWithRegions,
+ handler: ({ inputs }) => ({
+ outputs: { track: { kind: "inline", value: canonicalize(renderFineCaption(
+ inline<FineCaptionSchedule>(inputs.schedule?.value, "FineCaptionSchedule"),
+ inline<CaptionProgram>(inputs.program?.value, "CaptionProgram"),
+ inline<CaptionDocument>(inputs.document?.value, "CaptionDocument"),
+ inline<ProgramSpace>(inputs.space?.value, "ProgramSpace"),
+ inline<SpatialRegionTimeline>(inputs.regions?.value, "SpatialRegionTimeline"),
+ )) } },
+ needs: {},
+ }),
+ },
],
} satisfies ComponentPackage;
diff --git a/packages/caption-fine/src/fragment.ts b/packages/caption-fine/src/fragment.ts
index a0c11ad6..79b88f98 100644
--- a/packages/caption-fine/src/fragment.ts
+++ b/packages/caption-fine/src/fragment.ts
@@ -3,6 +3,7 @@ import { compositionTypes } from "@hypit/composition";
import { sealGraphFragment } from "@hypit/elaborator";
import { narrativeTypes } from "@hypit/narrative";
import { semanticTrackProducers, semanticTrackTypes } from "@hypit/semantic-track";
+import { spatialTypes } from "@hypit/spatial";
import { captionFineProducers, captionFineTypes } from "./manifest.js";
@@ -62,3 +63,50 @@ 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: "semantic", type: semanticTrackTypes.track },
+ { name: "program", type: captionTypes.program },
+ { name: "regions", type: spatialTypes.regionTimeline },
+ ],
+ operations: [
+ {
+ id: "caption:space",
+ producer: semanticTrackProducers.projectProgramSpace,
+ inputs: { track: input("semantic") },
+ result: { kind: "output", name: "space" },
+ },
+ {
+ id: "caption:temporalize-document",
+ producer: captionProducers.temporalizeDocument,
+ inputs: {
+ document: input("document"), semantic: input("semantic"), program: input("program"),
+ },
+ result: { kind: "output", name: "caption" },
+ },
+ {
+ id: "caption-fine:schedule",
+ producer: captionFineProducers.schedule,
+ inputs: {
+ caption: operation("caption:temporalize-document"), program: input("program"), document: input("document"),
+ },
+ result: { kind: "output", name: "schedule" },
+ },
+ {
+ id: "caption-fine:render",
+ producer: captionFineProducers.renderWithRegions,
+ inputs: {
+ schedule: operation("caption-fine:schedule"), program: input("program"),
+ document: input("document"), space: operation("caption:space"), 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") },
+ ],
+});
diff --git a/packages/caption-fine/src/index.ts b/packages/caption-fine/src/index.ts
index e2066c44..5ff635f6 100644
--- a/packages/caption-fine/src/index.ts
+++ b/packages/caption-fine/src/index.ts
@@ -1,5 +1,5 @@
export { captionFineComponent } from "./component.js";
-export { fineCaptionTrackFragment } from "./fragment.js";
+export { fineCaptionRegionTrackFragment, fineCaptionTrackFragment } from "./fragment.js";
export { captionFineManifest, captionFineMarkupSurfaces, captionFineModuleRef, captionFineProducers, captionFineTypes } from "./manifest.js";
export { renderFineCaption } from "./render.js";
export { assertFineCaptionSchedule, scheduleFineCaption } from "./schedule.js";
diff --git a/packages/caption-fine/src/manifest.ts b/packages/caption-fine/src/manifest.ts
index 794a0ef8..8dfe83a7 100644
--- a/packages/caption-fine/src/manifest.ts
+++ b/packages/caption-fine/src/manifest.ts
@@ -7,6 +7,7 @@ import { narrativeDependency, narrativeTypes } from "@hypit/narrative";
import { programSpaceDependency, programSpaceTypes } from "@hypit/program-space";
import type { ModuleManifest, ProducerRef } from "@hypit/protocol";
import { semanticTrackDependency, semanticTrackTypes } from "@hypit/semantic-track";
+import { spatialDependency, spatialTypes } from "@hypit/spatial";
import { svsRecipeType } from "@hypit/svs";
import { fineCaptionOneShotMotions } from "./recipe.js";
@@ -24,6 +25,7 @@ export const captionFineTypes = {
export const captionFineProducers = {
schedule: { module: captionFineModuleRef, name: "schedule-fine-caption" },
render: { module: captionFineModuleRef, name: "render-fine-caption" },
+ renderWithRegions: { module: captionFineModuleRef, name: "render-fine-caption-with-regions" },
} satisfies Record<string, ProducerRef>;
export const captionFineMarkupSurfaces = [
@@ -229,6 +231,8 @@ export const captionFineMarkupSurfaces = [
summary: "Plays this motion as a Cue arrives." },
{ name: "cue-enter-frames", required: false, fallback: "0",
summary: "Sets how many Frames the Cue entrance runs for." },
+ { name: "cue-enter-start-scale", required: false,
+ summary: "Overrides the Cue entrance motion's initial uniform scale while preserving that motion's own curve; 0.55 begins at fifty-five percent size and settles at one." },
{ name: "cue-exit", required: false, values: fineCaptionOneShotMotions, fallback: "none",
summary: "Plays this motion as a Cue leaves." },
{ name: "cue-exit-frames", required: false, fallback: "0",
@@ -305,6 +309,8 @@ export const captionFineMarkupSurfaces = [
summary: "Chooses the continuous SemanticTrack whose Word anchors give every Cue its time." },
{ name: "program", kind: "reference", required: true, accepts: [captionTypes.program],
summary: "Chooses the Style assignment that decides which Style each run is rendered in." },
+ { name: "regions", kind: "reference", required: false, accepts: [spatialTypes.regionTimeline],
+ 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." },
],
ports: [
{ name: "schedule", type: captionFineTypes.schedule,
@@ -316,6 +322,8 @@ export const captionFineMarkupSurfaces = [
notes: [
"The element is empty; it accepts no children and no text.",
"One Track renders the Program's default Style and every ordered replacement together.",
+ "Without regions, Recipe x/y placement is unchanged. With regions, a measured region overrides x/y for that Frame; a null Frame on that Role track hides the Cue, while a missing Role track retains authored x/y.",
+ "The tracked point replaces Recipe x/y while width and the Recipe anchor still decide the Caption box geometry; anchor-x=center and anchor-y=bottom place the box immediately above the measured region.",
],
},
},
@@ -333,6 +341,7 @@ export const captionFineManifest: ModuleManifest = {
narrativeDependency,
programSpaceDependency,
semanticTrackDependency,
+ spatialDependency,
],
types: [{ name: captionFineTypes.schedule.name }],
capabilities: [],
@@ -358,5 +367,17 @@ export const captionFineManifest: ModuleManifest = {
outputs: [{ name: "track", type: compositionTypes.visualTrack }],
needs: [],
},
+ {
+ name: captionFineProducers.renderWithRegions.name,
+ inputs: [
+ { name: "schedule", type: captionFineTypes.schedule },
+ { name: "program", type: captionTypes.program },
+ { name: "document", type: narrativeTypes.captionDocument },
+ { name: "space", type: programSpaceTypes.programSpace },
+ { name: "regions", type: spatialTypes.regionTimeline },
+ ],
+ outputs: [{ name: "track", type: compositionTypes.visualTrack }],
+ needs: [],
+ },
],
};
diff --git a/packages/caption-fine/src/recipe.ts b/packages/caption-fine/src/recipe.ts
index af30ab84..3a215938 100644
--- a/packages/caption-fine/src/recipe.ts
+++ b/packages/caption-fine/src/recipe.ts
@@ -32,6 +32,7 @@ const integers = new Set([
const numbers = new Set([
"size", "radius", "line-height", "border-width", "letter-spacing", "loop-intensity",
"cue-shadow-blur", "cue-shadow-spread", "cue-shadow-x", "cue-shadow-y",
+ "cue-enter-start-scale",
"slide-distance", "word-gap", "active-box-border-width", "active-box-radius", "active-scale",
"underline-offset", "underline-thickness", "active-underline-offset", "active-underline-thickness",
...paired("glow-blur", "glow-spread", "gradient-angle", "long-shadow-angle", "long-shadow-distance",
@@ -87,7 +88,7 @@ export const fineCaptionOptionalRecipeProperties = [
"active-underline-color", "active-underline-offset", "active-underline-thickness", "anchor-x", "anchor-y",
"atom-enter", "atom-enter-frames", "atom-exit", "atom-exit-frames", "atom-reveal", "block-align", "border-color", "border-width", "caps", "cue-enter",
"cue-shadow-blur", "cue-shadow-color", "cue-shadow-opacity", "cue-shadow-spread", "cue-shadow-x", "cue-shadow-y",
- "cue-enter-frames", "cue-exit", "cue-exit-frames", "direction", "glow-blur", "glow-color",
+ "cue-enter-frames", "cue-enter-start-scale", "cue-exit", "cue-exit-frames", "direction", "glow-blur", "glow-color",
"glow-opacity", "glow-spread", "gradient-angle", "gradient-from", "gradient-to", "height", "inline-size", "karaoke", "karaoke-transition", "kerning",
"handoff", "lead-frames", "letter-spacing", "long-shadow-angle", "long-shadow-color", "long-shadow-distance", "long-shadow-opacity",
"loop", "loop-intensity", "loop-period-frames", "loop-target", "max-lines", "max-words-per-line", "opacity", "shadow-blur", "shadow-color",
diff --git a/packages/caption-fine/src/render.ts b/packages/caption-fine/src/render.ts
index a7b3cb3e..6cf7d0d4 100644
--- a/packages/caption-fine/src/render.ts
+++ b/packages/caption-fine/src/render.ts
@@ -15,6 +15,8 @@ import type {
import type { CaptionAlignmentUnit, CaptionDocument } from "@hypit/narrative";
import { assertProgramSpaceIdentity, programSpaceFrameCount } from "@hypit/program-space";
import type { ProgramSpace } from "@hypit/program-space";
+import { assertSpatialRegionTimeline } from "@hypit/spatial";
+import type { CanvasSpace, SpatialFrame, SpatialRegionTimeline } from "@hypit/spatial";
import { assertFineCaptionParameters, FINE_CAPTION_FAMILY } from "./style.js";
import { assertFineCaptionSchedule } from "./schedule.js";
@@ -298,41 +300,73 @@ function wipes(kind: FineCaptionOneShotMotion): boolean {
return kind === "wipe-left" || kind === "wipe-right" || kind === "wipe-up" || kind === "wipe-down";
}
-function motionSnapshot(kind: FineCaptionOneShotMotion, progress: number, distancePx: number): MotionSnapshot {
+function motionSnapshot(
+ kind: FineCaptionOneShotMotion,
+ progress: number,
+ distancePx: number,
+ startScale?: number,
+): MotionSnapshot {
const value = clamp(progress, 0, 1);
const eased = easeOut(value);
const state = (opacity: number, transform = "none", filter = "none", clipPath = neutralMotion.clipPath): MotionSnapshot =>
({ opacity, transform, filter, clipPath });
+ const scaleFrom = (fallback: number, motionProgress: number): string =>
+ `scale(${compactNumber((startScale ?? fallback) + (1 - (startScale ?? fallback)) * motionProgress)})`;
+ const optionalScale = (): string => startScale === undefined ? "" : ` ${scaleFrom(1, eased)}`;
if (kind === "none") return neutralMotion;
- if (kind === "fade") return state(eased);
- if (kind === "blur-in") return state(eased, `scale(${compactNumber(0.96 + 0.04 * eased)})`, `blur(${compactNumber((1 - eased) * 16)}px)`);
- if (kind === "pop") return state(eased, `scale(${compactNumber(0.6 + 0.4 * easeOutBack(value))})`);
- if (kind === "scale") return state(eased, `scale(${compactNumber(0.2 + 0.8 * eased)})`);
+ if (kind === "fade") return state(eased, startScale === undefined ? "none" : scaleFrom(1, eased));
+ if (kind === "blur-in") return state(eased, scaleFrom(0.96, eased), `blur(${compactNumber((1 - eased) * 16)}px)`);
+ if (kind === "pop") return state(eased, scaleFrom(0.6, easeOutBack(value)));
+ if (kind === "scale") return state(eased, scaleFrom(0.2, eased));
if (kind === "spring") {
const settled = value >= 1 ? 1 : 1 - Math.exp(-5 * value) * Math.cos(10 * value);
- return state(eased, `scale(${compactNumber(0.72 + 0.28 * settled)})`);
+ return state(eased, scaleFrom(0.72, settled));
}
- if (kind === "bounce") return state(eased, `scale(${compactNumber(easeOutBounce(value))})`);
- if (kind === "elastic") return state(eased, `scale(${compactNumber(easeOutElastic(value))})`);
- if (kind === "stamp") return state(eased, `scale(${compactNumber(1.35 - 0.35 * easeOutBack(value))})`);
- if (kind === "tilt") return state(eased, `rotate(${compactNumber((1 - eased) * -8)}deg) scale(${compactNumber(0.94 + 0.06 * eased)})`);
- if (kind === "zoom-blur") return state(eased, `scale(${compactNumber(1.18 - 0.18 * eased)})`, `blur(${compactNumber((1 - eased) * 18)}px)`);
- if (kind === "flip-x") return state(eased, `perspective(600px) rotateX(${compactNumber((1 - eased) * 88)}deg) scale(${compactNumber(0.92 + 0.08 * eased)})`);
- if (kind === "flip-y") return state(eased, `perspective(600px) rotateY(${compactNumber((1 - eased) * -88)}deg) scale(${compactNumber(0.92 + 0.08 * eased)})`);
- if (kind === "spin") return state(eased, `rotate(${compactNumber((1 - eased) * -180)}deg) scale(${compactNumber(0.55 + 0.45 * eased)})`);
- if (kind === "squash") return state(eased, `scaleX(${compactNumber(1.28 - 0.28 * easeOutBack(value))}) scaleY(${compactNumber(0.48 + 0.52 * easeOutBack(value))})`);
- if (kind === "stretch") return state(eased, `scaleX(${compactNumber(0.5 + 0.5 * easeOutBack(value))}) scaleY(${compactNumber(1.35 - 0.35 * easeOutBack(value))})`);
+ if (kind === "bounce") return state(eased, scaleFrom(0, easeOutBounce(value)));
+ if (kind === "elastic") return state(eased, scaleFrom(0, easeOutElastic(value)));
+ if (kind === "stamp") return state(eased, scaleFrom(1.35, easeOutBack(value)));
+ if (kind === "tilt") return state(eased, `rotate(${compactNumber((1 - eased) * -8)}deg) ${scaleFrom(0.94, eased)}`);
+ if (kind === "zoom-blur") return state(eased, scaleFrom(1.18, eased), `blur(${compactNumber((1 - eased) * 18)}px)`);
+ if (kind === "flip-x") return state(eased, `perspective(600px) rotateX(${compactNumber((1 - eased) * 88)}deg) ${scaleFrom(0.92, eased)}`);
+ if (kind === "flip-y") return state(eased, `perspective(600px) rotateY(${compactNumber((1 - eased) * -88)}deg) ${scaleFrom(0.92, eased)}`);
+ if (kind === "spin") return state(eased, `rotate(${compactNumber((1 - eased) * -180)}deg) ${scaleFrom(0.55, eased)}`);
+ if (kind === "squash") return state(eased, `scaleX(${compactNumber(1.28 - 0.28 * easeOutBack(value))}) scaleY(${compactNumber(0.48 + 0.52 * easeOutBack(value))})${optionalScale()}`);
+ if (kind === "stretch") return state(eased, `scaleX(${compactNumber(0.5 + 0.5 * easeOutBack(value))}) scaleY(${compactNumber(1.35 - 0.35 * easeOutBack(value))})${optionalScale()}`);
const hidden = compactNumber((1 - eased) * 100);
- if (kind === "wipe-left") return state(1, "none", "none", `inset(0% 0% 0% ${hidden}%)`);
- if (kind === "wipe-right") return state(1, "none", "none", `inset(0% ${hidden}% 0% 0%)`);
- if (kind === "wipe-up") return state(1, "none", "none", `inset(0% 0% ${hidden}% 0%)`);
- if (kind === "wipe-down") return state(1, "none", "none", `inset(${hidden}% 0% 0% 0%)`);
+ const wipeTransform = startScale === undefined ? "none" : scaleFrom(1, eased);
+ if (kind === "wipe-left") return state(1, wipeTransform, "none", `inset(0% 0% 0% ${hidden}%)`);
+ if (kind === "wipe-right") return state(1, wipeTransform, "none", `inset(0% ${hidden}% 0% 0%)`);
+ if (kind === "wipe-up") return state(1, wipeTransform, "none", `inset(0% 0% ${hidden}% 0%)`);
+ if (kind === "wipe-down") return state(1, wipeTransform, "none", `inset(${hidden}% 0% 0% 0%)`);
const remaining = compactNumber((1 - value) * distancePx);
const transform = kind === "slide-left" ? `translateX(-${remaining}px)`
: kind === "slide-right" ? `translateX(${remaining}px)`
: kind === "slide-up" ? `translateY(-${remaining}px)`
: `translateY(${remaining}px)`;
- return state(eased, transform);
+ return state(eased, `${transform}${optionalScale()}`);
+}
+
+function cueEntranceSnapshot(
+ parameters: FineCaptionParameters,
+ progress: number,
+): MotionSnapshot {
+ const value = clamp(progress, 0, 1);
+ const authored = motionSnapshot(
+ parameters.motion.cueEnter,
+ value,
+ parameters.motion.slideDistancePx,
+ parameters.motion.cueEnterStartScale,
+ );
+ const snapshot = parameters.motion.cueEnter !== "spring" ? authored : (() => {
+ const start = parameters.motion.cueEnterStartScale ?? 0.72;
+ const scale = value <= 0.5
+ ? start + (1.05 - start) * value / 0.5
+ : value <= 0.75
+ ? 1.05 + (0.95 - 1.05) * (value - 0.5) / 0.25
+ : 0.95 + (1 - 0.95) * (value - 0.75) / 0.25;
+ return { ...authored, opacity: 1, transform: `scale(${compactNumber(scale)})` };
+ })();
+ return snapshot;
}
function snapshotStyle(snapshot: MotionSnapshot, clipped = true): VisualStyleDeclaration[] {
@@ -363,7 +397,7 @@ function cueAnimation(parameters: FineCaptionParameters, durationFrames: number)
return animationFrom(durationFrames, offsets, (frame) => {
const enterProgress = enterFrames === 0 ? 1 : clamp(frame / enterFrames, 0, 1);
const exitProgress = exitFrames === 0 ? 1 : clamp((durationFrames - frame) / exitFrames, 0, 1);
- const enter = motionSnapshot(parameters.motion.cueEnter, enterProgress, parameters.motion.slideDistancePx);
+ const enter = cueEntranceSnapshot(parameters, enterProgress);
const exit = motionSnapshot(parameters.motion.cueExit, exitProgress, parameters.motion.slideDistancePx);
return snapshotStyle(enterProgress < 1 ? enter : exit, clipped);
});
@@ -470,7 +504,7 @@ function activeResponseAnimation(
durationFrames: number,
): VisualAnimation | undefined {
const response = parameters.motion.activeResponse;
- if (response === "none") return undefined;
+ if (response === "none" || endFrame <= startFrame) return undefined;
if (response === "scale") {
return animationFrom(durationFrames, stepOffsets(startFrame, endFrame), (frame) => {
const active = frame >= startFrame && (frame < endFrame || (endFrame === durationFrames && frame === durationFrames));
@@ -575,6 +609,35 @@ function anchorTransform(parameters: FineCaptionParameters): string | undefined
return x === 0 && y === 0 ? undefined : `translate(${x}%,${y}%)`;
}
+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;
+ return `translate(${compactNumber(xPx)}px,${compactNumber(yPx)}px)${anchor === undefined ? "" : ` ${anchor}`}`;
+ };
+ const keyframes: VisualKeyframe[] = frames.map((frame, atFrame) => ({
+ atFrame,
+ style: [
+ { name: "transform", value: transform(frame) },
+ { name: "opacity", value: frame === null ? 0 : 1 },
+ ],
+ }));
+ keyframes.push({
+ atFrame: frames.length,
+ style: [
+ { name: "transform", value: transform(frames.at(-1)!) },
+ { name: "opacity", value: frames.at(-1) === null ? 0 : 1 },
+ ],
+ });
+ return { keyframes };
+}
+
function structuralRowCount(
atoms: readonly CaptionAlignmentUnit[],
maxWordsPerLine: number,
@@ -591,6 +654,30 @@ function structuralRowCount(
return rows;
}
+/**
+ * Acoustic Word windows may overlap. Preserve those measurements in the
+ * SemanticTrack, but give every current-only visual state one unambiguous
+ * owner: as soon as the next authored unit starts, the previous one stops.
+ */
+function exclusiveActivationFrames(
+ atoms: readonly CaptionAlignmentUnit[],
+ atomFrames: ReadonlyMap<string, { readonly start: number; readonly end: number }>,
+): ReadonlyMap<string, { readonly start: number; readonly end: number }> {
+ return new Map(atoms.map((atom, index) => {
+ const timing = atomFrames.get(atom.id);
+ if (timing === undefined) throw new Error(`Fine Caption is missing timing for Atom ${atom.id}`);
+ const next = atoms[index + 1];
+ const nextStart = next === undefined ? undefined : atomFrames.get(next.id)?.start;
+ if (next !== undefined && nextStart === undefined) {
+ throw new Error(`Fine Caption is missing timing for Atom ${next.id}`);
+ }
+ return [atom.id, {
+ start: timing.start,
+ end: nextStart === undefined ? timing.end : Math.min(timing.end, nextStart),
+ }];
+ }));
+}
+
function cueElements(
atoms: readonly CaptionAlignmentUnit[],
atomFrames: ReadonlyMap<string, { readonly start: number; readonly end: number }>,
@@ -598,6 +685,10 @@ function cueElements(
wordText: ReadonlyMap<string, string>,
durationFrames: number,
styleId: string,
+ trackedPlacement?: {
+ readonly frames: readonly (SpatialFrame | null)[];
+ readonly canvas: CanvasSpace;
+ },
): VisualElement[] {
type UnorderedVisualElement = Omit<VisualBoxElement, "order"> | Omit<VisualTextElement, "order">;
const elements: VisualElement[] = [];
@@ -606,9 +697,19 @@ function cueElements(
elements.push({ ...element, order } as VisualElement);
order += 1;
};
- const transform = anchorTransform(parameters);
+ const placementAnimation = trackedPlacement === undefined
+ ? undefined
+ : trackedPlacementAnimation(parameters, trackedPlacement.frames, trackedPlacement.canvas);
+ const transform = placementAnimation === undefined
+ ? anchorTransform(parameters)
+ : (() => {
+ const value = placementAnimation.keyframes[0]?.style.find((declaration) => declaration.name === "transform")?.value;
+ if (typeof value !== "string") throw new Error("Fine Caption tracked placement has no initial transform");
+ return value;
+ })();
const cueMotion = cueAnimation(parameters, durationFrames);
const cueLoop = parameters.motion.loopTarget === "cue" ? loopAnimation(parameters, durationFrames) : undefined;
+ const activationFrames = exclusiveActivationFrames(atoms, atomFrames);
const gapPx = `${compactNumber(parameters.layout.wordGapPx)}px`;
const atomSurfaces = atoms.map((atom) => atom.wordIds.map((wordId) => wordText.get(wordId) ?? ""));
// A Cue whose boundaries all agree carries one `column-gap`, which is also what keeps a row that
@@ -638,28 +739,33 @@ 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: `${compactNumber(parameters.placement.x * 100)}%` },
+ { name: "left", value: placementAnimation === undefined ? `${compactNumber(parameters.placement.x * 100)}%` : "0px" },
{ name: "position", value: "absolute" },
- { name: "top", value: `${compactNumber(parameters.placement.y * 100)}%` },
+ { name: "top", value: placementAnimation === undefined ? `${compactNumber(parameters.placement.y * 100)}%` : "0px" },
...(parameters.placement.height === undefined ? [] : [
{ name: "height", value: `${compactNumber(parameters.placement.height * 100)}%` },
] as const),
...(transform === undefined ? [] : [{ name: "transform", value: transform }] as const),
{ name: "width", value: `${compactNumber(parameters.placement.width * 100)}%` },
],
+ ...(placementAnimation === undefined ? {} : { animation: placementAnimation }),
});
push({
id: "cue-motion",
parent: "placement",
kind: "box",
- style: [{ name: "display", value: "inline-flex" }, { name: "transform-origin", value: "center center" }],
+ style: [{ name: "display", value: "inline-grid" }, { name: "transform-origin", value: "center center" }],
...(cueMotion === undefined ? {} : { animation: cueMotion }),
});
push({
id: "cue-loop",
parent: "cue-motion",
kind: "box",
- style: [{ name: "display", value: "inline-flex" }, { name: "transform-origin", value: "center center" }],
+ style: [
+ { name: "display", value: "inline-flex" },
+ { name: "grid-area", value: "1 / 1" },
+ { name: "transform-origin", value: "center center" },
+ ],
...(cueLoop === undefined ? {} : { animation: cueLoop }),
});
push({
@@ -753,6 +859,8 @@ function cueElements(
for (const [atomIndex, atom] of atoms.entries()) {
const timing = atomFrames.get(atom.id);
if (timing === undefined) throw new Error(`Fine Caption is missing timing for Atom ${atom.id}`);
+ const activationTiming = activationFrames.get(atom.id);
+ if (activationTiming === undefined) throw new Error(`Fine Caption is missing activation timing for Atom ${atom.id}`);
const atomId = `atom-${atomIndex + 1}`;
const surfaces = atomSurfaces[atomIndex] ?? [];
// The base glyphs and the activated copy stacked over them are laid out from this one list, so
@@ -778,8 +886,13 @@ function cueElements(
const entryAnimation = atomLifecycleAnimation(parameters, timing.start, timing.end, durationFrames);
const writerAnimation = typewriterAnimation(atomText, parameters, timing.start, timing.end, durationFrames);
const atomLoop = parameters.motion.loopTarget === "active-atom"
- ? loopAnimation(parameters, durationFrames, timing) : undefined;
- const responseAnimation = activeResponseAnimation(parameters, timing.start, timing.end, durationFrames);
+ ? loopAnimation(parameters, durationFrames, activationTiming) : undefined;
+ const responseAnimation = activeResponseAnimation(
+ parameters,
+ activationTiming.start,
+ activationTiming.end,
+ durationFrames,
+ );
push({
id: entryId,
parent: "cue",
@@ -861,7 +974,12 @@ function cueElements(
{ name: "top", value: `${compactNumber(-parameters.activeBox.paddingYPx)}px` },
{ name: "transform-origin", value: "center center" },
],
- animation: activeBoxAnimation(parameters, timing.start, timing.end, durationFrames),
+ animation: activeBoxAnimation(
+ parameters,
+ parameters.activeBox.mode === "current" ? activationTiming.start : timing.start,
+ parameters.activeBox.mode === "current" ? activationTiming.end : timing.end,
+ durationFrames,
+ ),
attributes: [{ name: "data-caption-active-box", value: "isolated" }],
});
}
@@ -887,6 +1005,7 @@ function cueElements(
kind: "glyph" | "underline",
): void => {
const activeId = `${atomId}-${suffix}`;
+ const activeTiming = mode === "current" ? activationTiming : timing;
push({
id: activeId,
parent: atomId,
@@ -901,8 +1020,8 @@ function cueElements(
{ name: "position", value: "absolute" },
],
animation: kind === "glyph" && parameters.karaoke.transition === "wipe"
- ? karaokeWipeAnimation(parameters, mode, timing.start, timing.end, durationFrames)
- : activationStepAnimation(mode, timing.start, timing.end, durationFrames),
+ ? karaokeWipeAnimation(parameters, mode, activeTiming.start, activeTiming.end, durationFrames)
+ : activationStepAnimation(mode, activeTiming.start, activeTiming.end, durationFrames),
attributes: [{ name: kind === "glyph" ? "data-caption-karaoke" : "data-caption-active-underline", value: mode }],
});
for (const [wordIndex, wordId] of atom.wordIds.entries()) {
@@ -939,6 +1058,7 @@ export function renderFineCaption(
program: CaptionProgram,
document: CaptionDocument,
space: ProgramSpace,
+ regions?: SpatialRegionTimeline,
): VisualTrack {
assertFineCaptionSchedule(schedule);
assertCaptionProgramForDocument(program, document);
@@ -961,6 +1081,13 @@ export function renderFineCaption(
assertFineCaptionParameters(style.rendering.parameters as unknown as FineCaptionParameters);
}
const totalFrames = programSpaceFrameCount(space);
+ const regionTracks = regions === undefined ? undefined : (() => {
+ assertSpatialRegionTimeline(regions);
+ if (regions.frameCount !== totalFrames) {
+ throw new Error(`Fine Caption regions cover ${regions.frameCount} Frames but ProgramSpace has ${totalFrames}`);
+ }
+ return new Map(regions.tracks.map((track) => [track.id, track]));
+ })();
const presents = schedule.cues.flatMap((cue) => {
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`);
@@ -973,6 +1100,18 @@ export function renderFineCaption(
const endFrameExclusive = Math.min(totalFrames, Math.max(startFrame + 1, measuredEnd));
if (startFrame >= totalFrames || endFrameExclusive <= startFrame) return [];
const durationFrames = endFrameExclusive - startFrame;
+ const trackedPlacement = regionTracks === undefined ? undefined : (() => {
+ const role = resolvedAtoms[0]?.role;
+ if (role === undefined || resolvedAtoms.some((atom) => atom.role !== role)) {
+ throw new Error(`Fine Caption Cue ${cue.id} must contain exactly one Script Role to follow regions`);
+ }
+ const track = regionTracks.get(role);
+ 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, {
start: clamp(atom.startFrame - startFrame, 0, durationFrames),
end: clamp(Math.max(atom.endFrameExclusive - startFrame, atom.startFrame - startFrame + 1), 0, durationFrames),
@@ -981,7 +1120,7 @@ export function renderFineCaption(
id: cue.id,
span: { startFrame, endFrameExclusive },
stacking: { order: parameters.stackingOrder, tieBreak: `${program.id}:${cue.id}` },
- elements: cueElements(resolvedAtoms, atomFrames, parameters, wordText, durationFrames, cue.styleId),
+ elements: cueElements(resolvedAtoms, atomFrames, parameters, wordText, durationFrames, cue.styleId, trackedPlacement),
}];
});
const track = sealVisualTrack({
diff --git a/packages/caption-fine/src/style.ts b/packages/caption-fine/src/style.ts
index 24119f4d..5e4a2de8 100644
--- a/packages/caption-fine/src/style.ts
+++ b/packages/caption-fine/src/style.ts
@@ -181,6 +181,7 @@ export function fineCaptionParameters(
const activeBoxPadding = padding(string(recipe, "active-box-padding", "0"));
const fontSizePx = number(recipe, "size");
const basePaint = glyphPaint(recipe, "");
+ const cueEnter = choice(recipe, "cue-enter", fineCaptionOneShotMotions, "none");
const parameters: FineCaptionParameters = {
stackingOrder: integer(recipe, "stack-order"),
@@ -260,10 +261,12 @@ export function fineCaptionParameters(
transitionFrames: integer(recipe, "active-box-transition-frames", 0),
},
motion: {
- cueEnter: choice(recipe, "cue-enter", fineCaptionOneShotMotions, "none"),
+ cueEnter,
cueExit: choice(recipe, "cue-exit", fineCaptionOneShotMotions, "none"),
cueEnterFrames: integer(recipe, "cue-enter-frames", 0),
cueExitFrames: integer(recipe, "cue-exit-frames", 0),
+ ...(Object.hasOwn(recipe.properties, "cue-enter-start-scale")
+ ? { cueEnterStartScale: number(recipe, "cue-enter-start-scale") } : {}),
atomEnter: choice(recipe, "atom-enter", fineCaptionOneShotMotions, "none"),
atomEnterFrames: integer(recipe, "atom-enter-frames", 0),
atomExit: choice(recipe, "atom-exit", fineCaptionOneShotMotions, "none"),
@@ -317,10 +320,16 @@ export function assertFineCaptionParameters(value: FineCaptionParameters): void
|| !Number.isSafeInteger(value.timing.leadFrames) || !Number.isSafeInteger(value.timing.tailFrames)
|| (value.layout.maxLines !== undefined && (!Number.isSafeInteger(value.layout.maxLines) || value.layout.maxLines <= 0))
|| (value.layout.maxWordsPerLine !== undefined && (!Number.isSafeInteger(value.layout.maxWordsPerLine) || value.layout.maxWordsPerLine <= 0))
+ || (value.motion.cueEnterStartScale !== undefined
+ && (!Number.isFinite(value.motion.cueEnterStartScale) || value.motion.cueEnterStartScale < 0))
|| value.motion.activeScale <= 0
|| !Number.isFinite(value.motion.activeScale) || !Number.isFinite(value.layout.letterSpacingPx)) {
throw new Error("Fine Caption parameters contain invalid numeric bounds");
}
+ if (value.motion.cueEnter === "none"
+ && value.motion.cueEnterStartScale !== undefined) {
+ throw new Error("Fine Caption Cue entrance modifiers require a Cue entrance motion");
+ }
if (value.typography.exactFonts.length === 0) throw new Error("Fine Caption exact Font stack is empty");
const faces = new Set<string>();
for (const [index, font] of value.typography.exactFonts.entries()) {
diff --git a/packages/caption-fine/src/surface.ts b/packages/caption-fine/src/surface.ts
index 55b91573..0390f2ba 100644
--- a/packages/caption-fine/src/surface.ts
+++ b/packages/caption-fine/src/surface.ts
@@ -3,6 +3,7 @@ import { assertFontArtifactRef, assertFontStackRef, mediaTypes } from "@hypit/me
import type { FontArtifactRef, FontStackRef } from "@hypit/media";
import { narrativeTypes } from "@hypit/narrative";
import { semanticTrackTypes } from "@hypit/semantic-track";
+import { spatialTypes } from "@hypit/spatial";
import { svsRecipeType } from "@hypit/svs";
import type { SvsRecipe } from "@hypit/svs";
import type {
@@ -12,7 +13,7 @@ import type {
MarkupAttributeValue,
} from "@hypit/markup";
-import { fineCaptionTrackFragment } from "./fragment.js";
+import { fineCaptionRegionTrackFragment, fineCaptionTrackFragment } from "./fragment.js";
import { fineCaptionStyle } from "./style.js";
function sameType(left: SurfaceResolvedReference["type"], right: SurfaceResolvedReference["type"]): boolean {
@@ -113,7 +114,7 @@ export const decodeFineCaptionStyleSurface: StructuredSurfaceHandler = ({ elemen
};
export const decodeFineCaptionTrackSurface: StructuredSurfaceHandler = ({ element, resolveReference }) => {
- attributes(element, ["id", "document", "semantic", "program"]);
+ attributes(element, ["id", "document", "semantic", "program"], ["regions"]);
if (element.children.some((child) => child.kind === "element" || child.value.trim())) {
throw new Error(`${element.name} does not accept children`);
}
@@ -121,6 +122,20 @@ export const decodeFineCaptionTrackSurface: StructuredSurfaceHandler = ({ elemen
const document = reference(element, "document", narrativeTypes.captionDocument, resolveReference);
const semantic = reference(element, "semantic", semanticTrackTypes.track, resolveReference);
const program = reference(element, "program", captionTypes.program, resolveReference);
+ if (element.attributes.regions !== undefined) {
+ const regions = reference(element, "regions", spatialTypes.regionTimeline, resolveReference);
+ return {
+ records: [],
+ components: [{
+ id,
+ fragment: fineCaptionRegionTrackFragment.id,
+ inputs: { document: document.ref, semantic: semantic.ref, program: program.ref, regions: regions.ref },
+ outputs: { schedule: `${id}.schedule`, track: `${id}.track` },
+ range: element.range,
+ }],
+ fragments: [fineCaptionRegionTrackFragment],
+ };
+ }
return {
records: [],
components: [{
diff --git a/packages/caption-fine/src/types.ts b/packages/caption-fine/src/types.ts
index 4eb9c37a..cb388334 100644
--- a/packages/caption-fine/src/types.ts
+++ b/packages/caption-fine/src/types.ts
@@ -145,6 +145,7 @@ export type FineCaptionParameters = {
readonly cueExit: FineCaptionOneShotMotion;
readonly cueEnterFrames: number;
readonly cueExitFrames: number;
+ readonly cueEnterStartScale?: number;
readonly atomEnter: FineCaptionOneShotMotion;
readonly atomEnterFrames: number;
readonly atomExit: FineCaptionOneShotMotion;
diff --git a/packages/caption-fine/test/caption-fine.test.ts b/packages/caption-fine/test/caption-fine.test.ts
index fa64fb3f..897b536d 100644
--- a/packages/caption-fine/test/caption-fine.test.ts
+++ b/packages/caption-fine/test/caption-fine.test.ts
@@ -5,6 +5,7 @@ import type { CaptionProgram, TimedCaptionProjection } 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 { SvsRecipe } from "@hypit/svs";
import { fixtureDigest } from "../../../test/fixture-digest.js";
@@ -63,8 +64,8 @@ const recipe: SvsRecipe = {
},
};
-function fixture() {
- const parsed = parseScript("caption-fine.svml", "<line>one two || three four</line>");
+function fixture(script = "<line>one two || three four</line>") {
+ const parsed = parseScript("caption-fine.svml", script);
const document = captionDocument(parsed, "story.caption", "story");
const style = fineCaptionStyle("plain", recipe, [font]);
const program: CaptionProgram = {
@@ -140,6 +141,96 @@ test("Fine Caption schedules visibility outside semantic Word timing and cuts on
assert.equal(atom?.style.find((declaration) => declaration.name === "overflow-wrap")?.value, "anywhere");
});
+test("Fine Caption uniformly springs the whole Cue through exact scales", () => {
+ const { document, program, projection } = fixture();
+ const style = fineCaptionStyle("plain", {
+ ...recipe,
+ properties: {
+ ...recipe.properties,
+ "cue-enter": "spring",
+ "cue-enter-frames": 4,
+ "cue-enter-start-scale": 0.75,
+ },
+ }, [font]);
+ const animatedProgram: CaptionProgram = { ...program, styles: [style] };
+ const track = renderFineCaption(
+ scheduleFineCaption(projection, animatedProgram, document),
+ animatedProgram,
+ document,
+ sealProgramSpace({ id: "test-space", narrativeId: "story", durationSec: 3,
+ 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");
+ const cue = track.presents[0]?.elements.find((element) => element.id === "cue");
+ const declarationAt = (frame: number, name: string): string | number | undefined =>
+ cueMotion?.animation?.keyframes.find((keyframe) => keyframe.atFrame === frame)
+ ?.style.find((declaration) => declaration.name === name)?.value;
+ const scaleAt = (frame: number): number => {
+ const transform = declarationAt(frame, "transform");
+ assert.ok(typeof transform === "string");
+ const match = /^scale\(([^)]+)\)$/u.exec(transform);
+ assert.ok(match);
+ return Number(match[1]);
+ };
+
+ assert.equal(declarationAt(0, "opacity"), 1);
+ assert.equal(scaleAt(0), 0.75);
+ assert.equal(scaleAt(2), 1.05);
+ assert.equal(scaleAt(3), 0.95);
+ assert.equal(declarationAt(0, "filter"), "none");
+ assert.equal(cueLoop?.parent, cueMotion?.id);
+ assert.equal(cue?.parent, cueLoop?.id);
+ assert.equal(declarationAt(4, "transform"), "none");
+ assert.equal(declarationAt(4, "filter"), "none");
+});
+
+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 = sealProgramSpace({ id: "test-space", narrativeId: "story", 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: "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 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;
+ assert.equal(placement?.style.find((declaration) => declaration.name === "left")?.value, "0px");
+ assert.equal(placement?.style.find((declaration) => declaration.name === "top")?.value, "0px");
+ assert.equal(declarationAt(0, "transform"), "translate(206px,306px) translate(-50%,-100%)");
+ assert.equal(declarationAt(0, "opacity"), 1);
+ assert.equal(declarationAt(1, "opacity"), 0);
+ assert.equal(declarationAt(2, "opacity"), 1);
+});
+
+test("Fine Caption keeps authored placement when a Cue Role has no measured track", () => {
+ const { document, program, projection } = fixture(`<line>
+ <BOY>one two || three four
+</line>`);
+ const space = sealProgramSpace({ id: "test-space", narrativeId: "story", 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 track = renderFineCaption(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?.animation, undefined);
+});
+
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", {
@@ -164,6 +255,41 @@ test("Fine Caption applies authored mute before it schedules the visible envelop
assert.equal(schedule.cues[0]?.semanticStartFrame, projection.cues[0]!.units[1]!.startFrame);
});
+test("Fine Caption gives overlapping acoustic Words one current Karaoke owner", () => {
+ const { document, program, projection } = fixture();
+ const style = fineCaptionStyle("plain", {
+ ...recipe,
+ properties: { ...recipe.properties, karaoke: "current", "karaoke-transition": "step" },
+ }, [font]);
+ const karaokeProgram: CaptionProgram = { ...program, styles: [style] };
+ const firstCue = projection.cues[0]!;
+ const overlapped: TimedCaptionProjection = {
+ ...projection,
+ cues: [{
+ ...firstCue,
+ units: [
+ { ...firstCue.units[0]!, endFrameExclusive: 21 },
+ firstCue.units[1]!,
+ ],
+ }, projection.cues[1]!],
+ };
+ const track = renderFineCaption(
+ scheduleFineCaption(overlapped, karaokeProgram, document),
+ karaokeProgram,
+ document,
+ sealProgramSpace({ id: "test-space", narrativeId: "story", durationSec: 3,
+ 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");
+ const opacityAt = (element: typeof firstActive, frame: number): string | number | undefined =>
+ element?.animation?.keyframes.find((keyframe) => keyframe.atFrame === frame)
+ ?.style.find((declaration) => declaration.name === "opacity")?.value;
+ // Cue visibility starts at Frame 6, so global handoff Frame 20 is local Frame 14.
+ assert.equal(opacityAt(firstActive, 14), 0);
+ assert.equal(opacityAt(secondActive, 14), 1);
+});
+
test("Fine Caption rejects token-specific Style runs instead of disguising a structural caption", () => {
const { document, program, projection } = fixture();
const word = document.words[0]!;