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: complete fine caption rendering

kashorin6ac042df6d12
diff --git a/docs/quickstart/tracks.md b/docs/quickstart/tracks.md
index 0ccdb749..2e7c835d 100644
--- a/docs/quickstart/tracks.md
+++ b/docs/quickstart/tracks.md
@@ -25,7 +25,7 @@ Script Display → Caption Program → Planner + measured Atom timing → Style-
`@narratage/caption` owns only common Cue bounds, generic optional per-Word fields, total Style
assignment, Plan validation and the timing join. `@narratage/caption-fine` is one field-free Style
-family: it owns its font/box parameters and uniform Cue rendering.
+family: it owns geometry, glyph/Cue-box Paint, restrained motion and optional whole-Atom karaoke.
### caption-fine:Style
@@ -36,11 +36,22 @@ both from one package-owned SVS Recipe:
caption.primary {
cue-min-words: 2;
cue-max-words: 7;
- stack-order: 70;
- x: 0.08; y: 0.76; width: 0.84;
- font: Inter; weight: 600; size: 58; line-height: 0.96;
- align: center; fill: #FFFFFF; background: #09090BCC;
+ stack-order: 70; x: 0.5; y: 0.88; width: 0.84;
+ anchor-x: center; anchor-y: bottom;
+ font: Inter; weight: 700; size: 58; font-style: normal;
+ line-height: 0.96; letter-spacing: -0.5; word-gap: 14;
+ align: center; direction: ltr;
+ fill: #FFFFFF; opacity: 1;
+ stroke-color: #09090B; stroke-width: 2;
+ shadow-color: #000000; shadow-opacity: 0.72;
+ shadow-x: 0; shadow-y: 3; shadow-blur: 8;
+ glow-color: #FFFFFF; glow-opacity: 0.12; glow-blur: 8;
+ background: #09090BCC; border-color: #FFFFFF20; border-width: 1;
padding: 16 24; radius: 18;
+ karaoke: trail; karaoke-transition: wipe;
+ active-fill: #FFD54A; active-scale: 1.04;
+ cue-enter: fade; cue-exit: fade; cue-transition-frames: 4;
+ atom-reveal: all;
}
```
@@ -51,6 +62,16 @@ caption.primary {
Another Caption package may define completely different planning fields and visual parameters
without changing the common package.
+Fine's properties are orthogonal: Cue planning; normalized placement and anchor; layout and
+typography; base glyph Paint; Cue-box Paint; active glyph Paint; karaoke timing; and restrained
+local motion. Active Paint supports the same `fill`/`opacity`/`stroke-*`/`shadow-*`/`glow-*`
+dimensions using the `active-` prefix. Missing optional dimensions resolve deterministically to no
+decoration or motion. Unknown properties are rejected.
+
+`karaoke` is `off`, `current` or `trail`; `karaoke-transition` is `step` or `wipe`. Timing is always
+whole-Atom timing already proven by Caption. A normal one-word Atom therefore highlights per word,
+while a Dual Text Atom remains one indivisible visible unit. Fine never guesses internal time.
+
### caption:Program
The Program starts from the complete ordered display-word universe emitted by Script. One explicit
diff --git a/examples/talking-film-graph-check/studio.svs b/examples/talking-film-graph-check/studio.svs
index 4e0ea301..05663baf 100644
--- a/examples/talking-film-graph-check/studio.svs
+++ b/examples/talking-film-graph-check/studio.svs
@@ -8,9 +8,14 @@
}
caption.base {
cue-min-words: 1; cue-max-words: 5;
- stack-order: 70; x: 0.08; y: 0.76; width: 0.84; font: Inter; weight: 600;
- size: 58; line-height: 1; align: center; fill: #FFFFFF;
- background: #09090BCC; padding: 16 24; radius: 18;
+ stack-order: 70; x: 0.5; y: 0.88; width: 0.84; anchor-x: center; anchor-y: bottom;
+ font: Inter; weight: 700; size: 58; line-height: 1; align: center;
+ fill: #FFFFFF; stroke-color: #09090B; stroke-width: 2;
+ shadow-color: #000000; shadow-opacity: 0.72; shadow-x: 0; shadow-y: 3; shadow-blur: 8;
+ glow-color: #FFFFFF; glow-opacity: 0.12; glow-blur: 8;
+ background: #09090BCC; border-color: #FFFFFF20; border-width: 1; padding: 16 24; radius: 18;
+ karaoke: trail; karaoke-transition: wipe; active-fill: #FFD54A;
+ cue-enter: fade; cue-exit: fade; cue-transition-frames: 4;
}
text.title {
stack-order: 90; x: 0.06; y: 0.06; width: 0.88; height: 0.1; font: Inter;
diff --git a/examples/talking-film-graph-check/svml.packages.lock b/examples/talking-film-graph-check/svml.packages.lock
index afb4ba4a..cb9703a9 100644
--- a/examples/talking-film-graph-check/svml.packages.lock
+++ b/examples/talking-film-graph-check/svml.packages.lock
@@ -14,7 +14,7 @@
{
"name": "@narratage/caption-fine",
"version": "0.0.0-dev",
- "digest": "sha256:bd101448eeae8bdd8a3f9e7db98d85a2900020bf7ee6a4c7317e6d3826f4073d"
+ "digest": "sha256:0452abadd910c04ffe197aaf574dab31e86aa5b7ecbb290b96e707dc56270301"
},
{
"name": "@narratage/caption-gemini",
@@ -64,7 +64,7 @@
{
"name": "@narratage/hyperframes",
"version": "0.0.0-dev",
- "digest": "sha256:79b9ff48fe9b48247ed58a250db96c2a1e56f09f1138293c126c154a3c221daa"
+ "digest": "sha256:0820d7ff158593d190a7d111a51575bb0134e3e6aadbc369ac2cd7462e2027ff"
},
{
"name": "@narratage/media-pipeline",
@@ -221,8 +221,8 @@
"name": "@narratage/caption-fine",
"version": "0.0.0-dev"
},
- "facetsDigest": "sha256:acb8acf3319ff676999190b6440776fb8ce65949d7890f7ad5f1f1bcffcbaaee",
- "closureDigest": "sha256:7ef6b0f639f236c21c2107148343719ac69da211b9ef1f28ccbfee283ae134f3"
+ "facetsDigest": "sha256:932f0dc0aeb21c2725938e909fdcb725f78cfb9e84acdde757312ecd4c6bf98b",
+ "closureDigest": "sha256:6f4255b153c991ebaf98505f385ddcea258fef7f43372d5795d239060b6aa85f"
},
{
"specifier": "@narratage/caption-gemini",
@@ -267,7 +267,7 @@
"version": "0.0.0-dev"
},
"facetsDigest": "sha256:34bcacd52b6d396bf53f3b9709b43d54377a48c3b0332180079c3488a7fbe6ec",
- "closureDigest": "sha256:278ff28b7121f641e2df2bee6a891b3f4365aa8c58a08ee87c03adcc81d6d58c"
+ "closureDigest": "sha256:42d6b8d39c487e32626945db0064babdd7f833277d8c22f0f5f1cce01b9ab926"
},
{
"specifier": "@narratage/media",
@@ -312,7 +312,7 @@
"version": "0.0.0-dev"
},
"facetsDigest": "sha256:146a78ac53e7d5bf6910c62534e729d7567043636068ac9026e6ee6002cbc947",
- "closureDigest": "sha256:1c80bcca6dff9ceea096c5b0c0b15536ec5ba1f68f92e6ee2cb087f12c4a3eaa"
+ "closureDigest": "sha256:19ffeb84182908e096d97aa96d33420e80c9626b653711cbf55b87dededdbf4d"
},
{
"specifier": "@narratage/run-text",
@@ -432,5 +432,5 @@
"closureDigest": "sha256:c6634d4fdc7dfafb8b16e4219018957528f27e581c892a9344f894c820bde296"
}
],
- "digest": "sha256:b7da0d1b0c3e83d40b208922f6e4009c64343668b7fc02ec098897bc4f14cdf4"
+ "digest": "sha256:8b85a7310c8dce55f460d1505e427f19f3ca644185b30c6c4372aa1c4f927273"
}
diff --git a/examples/talking-film-live/svml.packages.lock b/examples/talking-film-live/svml.packages.lock
index 6e09e25e..84841948 100644
--- a/examples/talking-film-live/svml.packages.lock
+++ b/examples/talking-film-live/svml.packages.lock
@@ -9,7 +9,7 @@
{
"name": "@narratage/caption-fine",
"version": "0.0.0-dev",
- "digest": "sha256:bd101448eeae8bdd8a3f9e7db98d85a2900020bf7ee6a4c7317e6d3826f4073d"
+ "digest": "sha256:0452abadd910c04ffe197aaf574dab31e86aa5b7ecbb290b96e707dc56270301"
},
{
"name": "@narratage/caption-gemini",
@@ -64,7 +64,7 @@
{
"name": "@narratage/hyperframes",
"version": "0.0.0-dev",
- "digest": "sha256:79b9ff48fe9b48247ed58a250db96c2a1e56f09f1138293c126c154a3c221daa"
+ "digest": "sha256:0820d7ff158593d190a7d111a51575bb0134e3e6aadbc369ac2cd7462e2027ff"
},
{
"name": "@narratage/media-pipeline",
@@ -212,8 +212,8 @@
"name": "@narratage/caption-fine",
"version": "0.0.0-dev"
},
- "facetsDigest": "sha256:acb8acf3319ff676999190b6440776fb8ce65949d7890f7ad5f1f1bcffcbaaee",
- "closureDigest": "sha256:7ef6b0f639f236c21c2107148343719ac69da211b9ef1f28ccbfee283ae134f3"
+ "facetsDigest": "sha256:932f0dc0aeb21c2725938e909fdcb725f78cfb9e84acdde757312ecd4c6bf98b",
+ "closureDigest": "sha256:6f4255b153c991ebaf98505f385ddcea258fef7f43372d5795d239060b6aa85f"
},
{
"specifier": "@narratage/caption-gemini",
@@ -267,7 +267,7 @@
"version": "0.0.0-dev"
},
"facetsDigest": "sha256:34bcacd52b6d396bf53f3b9709b43d54377a48c3b0332180079c3488a7fbe6ec",
- "closureDigest": "sha256:278ff28b7121f641e2df2bee6a891b3f4365aa8c58a08ee87c03adcc81d6d58c"
+ "closureDigest": "sha256:42d6b8d39c487e32626945db0064babdd7f833277d8c22f0f5f1cce01b9ab926"
},
{
"specifier": "@narratage/media",
@@ -312,7 +312,7 @@
"version": "0.0.0-dev"
},
"facetsDigest": "sha256:146a78ac53e7d5bf6910c62534e729d7567043636068ac9026e6ee6002cbc947",
- "closureDigest": "sha256:1c80bcca6dff9ceea096c5b0c0b15536ec5ba1f68f92e6ee2cb087f12c4a3eaa"
+ "closureDigest": "sha256:19ffeb84182908e096d97aa96d33420e80c9626b653711cbf55b87dededdbf4d"
},
{
"specifier": "@narratage/run-text",
@@ -432,5 +432,5 @@
"closureDigest": "sha256:c6634d4fdc7dfafb8b16e4219018957528f27e581c892a9344f894c820bde296"
}
],
- "digest": "sha256:ba1796603708eefed02adc16db787a018bd81379fbfee172cbe09f7dbb9e0510"
+ "digest": "sha256:1a1c839057fe0c4a575f5dc660868d8008cdf33a1f9a6e690c046abb3a04ecc0"
}
diff --git a/examples/talking-head-aroll/svml.packages.lock b/examples/talking-head-aroll/svml.packages.lock
index 680d9f1f..c0313a61 100644
--- a/examples/talking-head-aroll/svml.packages.lock
+++ b/examples/talking-head-aroll/svml.packages.lock
@@ -9,7 +9,7 @@
{
"name": "@narratage/caption-fine",
"version": "0.0.0-dev",
- "digest": "sha256:bd101448eeae8bdd8a3f9e7db98d85a2900020bf7ee6a4c7317e6d3826f4073d"
+ "digest": "sha256:0452abadd910c04ffe197aaf574dab31e86aa5b7ecbb290b96e707dc56270301"
},
{
"name": "@narratage/caption-gemini",
@@ -64,7 +64,7 @@
{
"name": "@narratage/hyperframes",
"version": "0.0.0-dev",
- "digest": "sha256:79b9ff48fe9b48247ed58a250db96c2a1e56f09f1138293c126c154a3c221daa"
+ "digest": "sha256:0820d7ff158593d190a7d111a51575bb0134e3e6aadbc369ac2cd7462e2027ff"
},
{
"name": "@narratage/media-pipeline",
@@ -217,8 +217,8 @@
"name": "@narratage/caption-fine",
"version": "0.0.0-dev"
},
- "facetsDigest": "sha256:acb8acf3319ff676999190b6440776fb8ce65949d7890f7ad5f1f1bcffcbaaee",
- "closureDigest": "sha256:7ef6b0f639f236c21c2107148343719ac69da211b9ef1f28ccbfee283ae134f3"
+ "facetsDigest": "sha256:932f0dc0aeb21c2725938e909fdcb725f78cfb9e84acdde757312ecd4c6bf98b",
+ "closureDigest": "sha256:6f4255b153c991ebaf98505f385ddcea258fef7f43372d5795d239060b6aa85f"
},
{
"specifier": "@narratage/caption-gemini",
@@ -272,7 +272,7 @@
"version": "0.0.0-dev"
},
"facetsDigest": "sha256:34bcacd52b6d396bf53f3b9709b43d54377a48c3b0332180079c3488a7fbe6ec",
- "closureDigest": "sha256:278ff28b7121f641e2df2bee6a891b3f4365aa8c58a08ee87c03adcc81d6d58c"
+ "closureDigest": "sha256:42d6b8d39c487e32626945db0064babdd7f833277d8c22f0f5f1cce01b9ab926"
},
{
"specifier": "@narratage/media",
@@ -326,7 +326,7 @@
"version": "0.0.0-dev"
},
"facetsDigest": "sha256:146a78ac53e7d5bf6910c62534e729d7567043636068ac9026e6ee6002cbc947",
- "closureDigest": "sha256:1c80bcca6dff9ceea096c5b0c0b15536ec5ba1f68f92e6ee2cb087f12c4a3eaa"
+ "closureDigest": "sha256:19ffeb84182908e096d97aa96d33420e80c9626b653711cbf55b87dededdbf4d"
},
{
"specifier": "@narratage/run-text",
@@ -446,5 +446,5 @@
"closureDigest": "sha256:c6634d4fdc7dfafb8b16e4219018957528f27e581c892a9344f894c820bde296"
}
],
- "digest": "sha256:9459e7a8b5c06ff90185db72ec3e4fc24d832e2e02082543f80d2413a08f55f8"
+ "digest": "sha256:b745b8193c9659e651cb612d17550702cb3deaedfd37c7cca01061d20a188af1"
}
diff --git a/packages/caption-fine/README.md b/packages/caption-fine/README.md
index 55b2b66d..c4c63e40 100644
--- a/packages/caption-fine/README.md
+++ b/packages/caption-fine/README.md
@@ -1,11 +1,12 @@
# `@narratage/caption-fine`
-The first official fine-grained Caption Style family. It turns an SVS Recipe into one complete
-`CaptionStyle` and lowers timed Cues into one ordinary `VisualTrack`.
+The official field-free fine-grained Caption Style family. It turns one SVS Recipe into a complete
+`CaptionStyle` and lowers timed whole Atoms into one ordinary peer `VisualTrack`.
-Fine means short semantic Cues with deterministic geometry, typography and paint. Every Word in a
-Cue has one uniform static appearance. This family declares no planning fields and has no
-`important`, karaoke, random sizing or per-Word motion semantics.
+Fine owns Cue geometry, typography, base/active glyph Paint, Cue box Paint and restrained local
+motion. Its optional karaoke is `current | trail` by `step | wipe`; ordinary single-Word Atoms get
+per-word timing while a Dual Text Atom remains one honest indivisible activation unit. It declares
+no planning fields and has no `important`, random sizing or inferred Word timestamps.
```xml
<fine:Style id="primary" recipe={studio.caption.primary}/>
@@ -23,5 +24,6 @@ Cue has one uniform static appearance. This family declares no planning fields a
/>
```
-One Track handles the default and ordered Style replacements and emits one peer `VisualTrack`.
-Common Caption, Media, Composition and Core know none of Fine's Recipe fields or layout policy.
+One Track handles the default and ordered Style replacements. Common Caption, Media, Composition
+and Core know none of Fine's Recipe fields or layout policy. See `spec/caption-fine.md` for the full
+parameter surface, defaults, non-goals and remaining visual evidence gates.
diff --git a/packages/caption-fine/src/manifest.ts b/packages/caption-fine/src/manifest.ts
index acbabbc2..36cd7ce5 100644
--- a/packages/caption-fine/src/manifest.ts
+++ b/packages/caption-fine/src/manifest.ts
@@ -12,7 +12,7 @@ export const captionFineModuleRef = { name: "@narratage/caption-fine", version:
export const captionFineProducers = {
render: { module: captionFineModuleRef, name: "render-fine-caption" },
} satisfies Record<string, ProducerRef>;
-export const captionFineStyleSurfaceImplementationDigest = digestOf("@narratage/caption-fine/field-free-style-surface@1");
+export const captionFineStyleSurfaceImplementationDigest = digestOf("@narratage/caption-fine/complete-style-surface@1");
export const captionFineTrackSurfaceImplementationDigest = digestOf("@narratage/caption-fine/whole-atom-track-surface@1");
export const captionFineManifest: ModuleManifest = {
diff --git a/packages/caption-fine/src/render.ts b/packages/caption-fine/src/render.ts
index c6dc0dc3..0defd29d 100644
--- a/packages/caption-fine/src/render.ts
+++ b/packages/caption-fine/src/render.ts
@@ -1,90 +1,292 @@
import { assertCaptionProgramForDisplay, assertTimedCaptionProjection } from "@narratage/caption";
import type { CaptionProgram, TimedCaptionProjection } from "@narratage/caption";
import { assertVisualTrackIdentity, sealVisualTrack } from "@narratage/composition";
-import type { VisualElement, VisualStyleDeclaration, VisualTrack } from "@narratage/composition";
-import type { CaptionDisplaySequence } from "@narratage/narrative";
+import type {
+ VisualAnimation,
+ VisualBoxElement,
+ VisualElement,
+ VisualKeyframe,
+ VisualStyleDeclaration,
+ VisualTextElement,
+ VisualTrack,
+} from "@narratage/composition";
+import type { CaptionDisplayAtom, CaptionDisplaySequence } from "@narratage/narrative";
import { assertProgramSpaceIdentity, programSpaceFrameCount } from "@narratage/program-space";
import type { ProgramSpace } from "@narratage/program-space";
import { digestOf } from "@narratage/protocol";
import { assertFineCaptionParameters, FINE_CAPTION_FAMILY } from "./style.js";
-import type { FineCaptionParameters } from "./types.js";
+import type { FineCaptionGlyphPaint, FineCaptionParameters } from "./types.js";
-export const renderFineCaptionImplementationDigest = digestOf("@narratage/caption-fine/render-field-free-atoms@1");
+export const renderFineCaptionImplementationDigest = digestOf("@narratage/caption-fine/render-atom-paint-karaoke@1");
function frameAt(space: ProgramSpace, seconds: number): number {
return Math.round(seconds * space.frameRate.numerator / space.frameRate.denominator);
}
-function captionPieces(wordIds: readonly string[], wordText: ReadonlyMap<string, string>): string[] {
- return wordIds.map((wordId, index) => {
- const text = wordText.get(wordId);
- if (text === undefined) throw new Error(`Fine Caption Cue references unknown word ${wordId}`);
- return index === wordIds.length - 1 ? text : `${text} `;
- });
+function clamp(value: number, minimum: number, maximum: number): number {
+ return Math.max(minimum, Math.min(maximum, value));
+}
+
+function compactNumber(value: number): string {
+ return String(Math.round(value * 1_000_000) / 1_000_000);
}
-function textStyle(parameters: FineCaptionParameters): VisualStyleDeclaration[] {
+function alphaColor(hex: string, opacity: number): string {
+ const red = Number.parseInt(hex.slice(1, 3), 16);
+ const green = Number.parseInt(hex.slice(3, 5), 16);
+ const blue = Number.parseInt(hex.slice(5, 7), 16);
+ const authoredAlpha = hex.length === 9 ? Number.parseInt(hex.slice(7, 9), 16) / 255 : 1;
+ return `rgba(${red},${green},${blue},${compactNumber(authoredAlpha * opacity)})`;
+}
+
+function glyphStyle(parameters: FineCaptionParameters, paint: FineCaptionGlyphPaint): VisualStyleDeclaration[] {
+ const shadows: string[] = [];
+ if (paint.shadow.opacity > 0) {
+ shadows.push([
+ `${compactNumber(paint.shadow.offsetXPx)}px`,
+ `${compactNumber(paint.shadow.offsetYPx)}px`,
+ `${compactNumber(paint.shadow.blurPx)}px`,
+ alphaColor(paint.shadow.color, paint.shadow.opacity),
+ ].join(" "));
+ }
+ if (paint.glow.opacity > 0) {
+ shadows.push(`0 0 ${compactNumber(paint.glow.blurPx)}px ${alphaColor(paint.glow.color, paint.glow.opacity)}`);
+ }
return [
- { name: "color", value: parameters.typography.fill },
+ { name: "color", value: paint.fill },
{ name: "font-family", value: parameters.typography.fontFamily },
- { name: "font-size", value: `${parameters.typography.fontSizePx}px` },
+ { name: "font-size", value: `${compactNumber(parameters.typography.fontSizePx)}px` },
+ { name: "font-style", value: parameters.typography.fontStyle },
{ name: "font-weight", value: parameters.typography.fontWeight },
- { name: "line-height", value: parameters.typography.lineHeight },
- { name: "white-space", value: "pre-wrap" },
+ { name: "letter-spacing", value: `${compactNumber(parameters.layout.letterSpacingPx)}px` },
+ { name: "line-height", value: parameters.layout.lineHeight },
+ { name: "opacity", value: paint.opacity },
+ { name: "white-space", value: "nowrap" },
+ ...(paint.stroke.widthPx === 0 ? [] : [
+ { name: "-webkit-text-stroke-color", value: paint.stroke.color },
+ { name: "-webkit-text-stroke-width", value: `${compactNumber(paint.stroke.widthPx)}px` },
+ ] as const),
+ ...(shadows.length === 0 ? [] : [{ name: "text-shadow", value: shadows.join(",") }] as const),
];
}
+function styleIdentity(style: readonly VisualStyleDeclaration[]): string {
+ return JSON.stringify(style);
+}
+
+function animationFrom(
+ durationFrames: number,
+ offsets: Iterable<number>,
+ styleAt: (frame: number) => readonly VisualStyleDeclaration[],
+): VisualAnimation | undefined {
+ const keyframes = [...new Set([0, durationFrames, ...offsets])]
+ .filter((frame) => Number.isSafeInteger(frame) && frame >= 0 && frame <= durationFrames)
+ .sort((left, right) => left - right)
+ .map((atFrame): VisualKeyframe => ({ atFrame, style: styleAt(atFrame) }));
+ if (new Set(keyframes.map((keyframe) => styleIdentity(keyframe.style))).size === 1) return undefined;
+ return { keyframes };
+}
+
+function stepOffsets(...boundaries: number[]): number[] {
+ return boundaries.flatMap((boundary) => [boundary - 1, boundary]);
+}
+
+function cueAnimation(parameters: FineCaptionParameters, durationFrames: number): VisualAnimation | undefined {
+ const requested = parameters.motion.cueTransitionFrames;
+ const enterFrames = parameters.motion.cueEnter === "fade" ? Math.min(requested, Math.floor(durationFrames / 2)) : 0;
+ const exitFrames = parameters.motion.cueExit === "fade" ? Math.min(requested, Math.floor(durationFrames / 2)) : 0;
+ return animationFrom(durationFrames, [enterFrames, durationFrames - exitFrames], (frame) => {
+ const enter = enterFrames === 0 ? 1 : clamp(frame / enterFrames, 0, 1);
+ const exit = exitFrames === 0 ? 1 : clamp((durationFrames - frame) / exitFrames, 0, 1);
+ return [{ name: "opacity", value: Math.min(enter, exit) }];
+ });
+}
+
+function atomAnimation(
+ parameters: FineCaptionParameters,
+ startFrame: number,
+ endFrame: number,
+ durationFrames: number,
+): VisualAnimation | undefined {
+ if (parameters.motion.atomReveal === "all" && parameters.motion.activeScale === 1) return undefined;
+ return animationFrom(durationFrames, stepOffsets(startFrame, endFrame), (frame) => {
+ const active = frame >= startFrame && (frame < endFrame || (endFrame === durationFrames && frame === durationFrames));
+ const revealed = parameters.motion.atomReveal === "all" || frame >= startFrame;
+ return [
+ { name: "opacity", value: revealed ? 1 : 0 },
+ { name: "transform", value: `scale(${compactNumber(active ? parameters.motion.activeScale : 1)})` },
+ ];
+ });
+}
+
+function karaokeStepAnimation(
+ parameters: FineCaptionParameters,
+ startFrame: number,
+ endFrame: number,
+ durationFrames: number,
+): VisualAnimation {
+ return animationFrom(durationFrames, stepOffsets(startFrame, endFrame), (frame) => {
+ const active = parameters.karaoke.mode === "trail"
+ ? frame >= startFrame
+ : frame >= startFrame && (frame < endFrame || (endFrame === durationFrames && frame === durationFrames));
+ return [{ name: "opacity", value: active ? 1 : 0 }];
+ }) ?? { keyframes: [
+ { atFrame: 0, style: [{ name: "opacity", value: 1 }] },
+ { atFrame: durationFrames, style: [{ name: "opacity", value: 1 }] },
+ ] };
+}
+
+function wipeClip(progress: number, direction: FineCaptionParameters["layout"]["direction"]): string {
+ const hidden = compactNumber((1 - clamp(progress, 0, 1)) * 100);
+ return direction === "rtl" ? `inset(0 0 0 ${hidden}%)` : `inset(0 ${hidden}% 0 0)`;
+}
+
+function karaokeWipeAnimation(
+ parameters: FineCaptionParameters,
+ startFrame: number,
+ endFrame: number,
+ durationFrames: number,
+): VisualAnimation {
+ if (parameters.karaoke.mode === "current" && endFrame - startFrame <= 1) {
+ return karaokeStepAnimation(parameters, startFrame, endFrame, durationFrames);
+ }
+ const revealEnd = parameters.karaoke.mode === "current" ? endFrame - 1 : endFrame;
+ return animationFrom(durationFrames, [startFrame, revealEnd, endFrame], (frame) => {
+ let progress = 0;
+ if (frame >= startFrame && frame <= revealEnd) {
+ progress = revealEnd === startFrame ? 1 : (frame - startFrame) / (revealEnd - startFrame);
+ } else if (parameters.karaoke.mode === "trail" && frame > revealEnd) {
+ progress = 1;
+ }
+ return [{ name: "clip-path", value: wipeClip(progress, parameters.layout.direction) }];
+ }) ?? { keyframes: [
+ { atFrame: 0, style: [{ name: "clip-path", value: wipeClip(1, parameters.layout.direction) }] },
+ { atFrame: durationFrames, style: [{ name: "clip-path", value: wipeClip(1, parameters.layout.direction) }] },
+ ] };
+}
+
+function anchorTransform(parameters: FineCaptionParameters): string | undefined {
+ const x = parameters.placement.anchorX === "left" ? 0 : parameters.placement.anchorX === "center" ? -50 : -100;
+ const y = parameters.placement.anchorY === "top" ? 0 : parameters.placement.anchorY === "center" ? -50 : -100;
+ return x === 0 && y === 0 ? undefined : `translate(${x}%,${y}%)`;
+}
+
function cueElements(
- wordIds: readonly string[],
+ atoms: readonly CaptionDisplayAtom[],
+ atomFrames: ReadonlyMap<string, { readonly start: number; readonly end: number }>,
parameters: FineCaptionParameters,
wordText: ReadonlyMap<string, string>,
+ durationFrames: number,
): VisualElement[] {
- const pieces = captionPieces(wordIds, wordText);
- return [
- {
- id: "placement",
- order: 0,
+ type UnorderedVisualElement = Omit<VisualBoxElement, "order"> | Omit<VisualTextElement, "order">;
+ const elements: VisualElement[] = [];
+ let order = 0;
+ const push = (element: UnorderedVisualElement): void => {
+ elements.push({ ...element, order } as VisualElement);
+ order += 1;
+ };
+ const transform = anchorTransform(parameters);
+ const cueMotion = cueAnimation(parameters, durationFrames);
+ push({
+ id: "placement",
+ kind: "box",
+ style: [
+ { name: "align-items", value: "center" },
+ { 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: "position", value: "absolute" },
+ { name: "top", value: `${compactNumber(parameters.placement.y * 100)}%` },
+ ...(transform === undefined ? [] : [{ name: "transform", value: transform }] as const),
+ { name: "width", value: `${compactNumber(parameters.placement.width * 100)}%` },
+ ],
+ });
+ push({
+ id: "cue",
+ parent: "placement",
+ kind: "box",
+ style: [
+ { name: "background", value: parameters.cueBox.background },
+ { name: "border-color", value: parameters.cueBox.borderColor },
+ { name: "border-radius", value: `${compactNumber(parameters.cueBox.radiusPx)}px` },
+ { name: "border-style", value: "solid" },
+ { name: "border-width", value: `${compactNumber(parameters.cueBox.borderWidthPx)}px` },
+ { name: "column-gap", value: `${compactNumber(parameters.layout.wordGapPx)}px` },
+ { name: "direction", value: parameters.layout.direction },
+ { name: "display", value: "flex" },
+ { name: "flex-wrap", value: "wrap" },
+ { name: "justify-content", value: parameters.layout.textAlign === "left" ? "flex-start"
+ : parameters.layout.textAlign === "right" ? "flex-end" : "center" },
+ { name: "padding", value: `${compactNumber(parameters.cueBox.paddingYPx)}px ${compactNumber(parameters.cueBox.paddingXPx)}px` },
+ { name: "text-align", value: parameters.layout.textAlign },
+ ],
+ ...(cueMotion === undefined ? {} : { animation: cueMotion }),
+ });
+
+ 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 atomId = `atom-${atomIndex + 1}`;
+ const animation = atomAnimation(parameters, timing.start, timing.end, durationFrames);
+ push({
+ id: atomId,
+ parent: "cue",
kind: "box",
style: [
- { name: "align-items", value: "center" },
- { name: "display", value: "flex" },
- { name: "justify-content", value: parameters.typography.textAlign === "left" ? "flex-start"
- : parameters.typography.textAlign === "right" ? "flex-end" : "center" },
- { name: "left", value: `${parameters.placement.x * 100}%` },
- { name: "position", value: "absolute" },
- { name: "top", value: `${parameters.placement.y * 100}%` },
- { name: "width", value: `${parameters.placement.width * 100}%` },
+ { name: "column-gap", value: `${compactNumber(parameters.layout.wordGapPx)}px` },
+ { name: "display", value: "inline-flex" },
+ { name: "position", value: "relative" },
+ { name: "transform-origin", value: "center center" },
+ { name: "white-space", value: "nowrap" },
],
- },
- {
- id: "cue",
- parent: "placement",
- order: 1,
+ ...(animation === undefined ? {} : { animation }),
+ attributes: [{ name: "data-caption-atom", value: atom.id }],
+ });
+ for (const [wordIndex, wordId] of atom.wordIds.entries()) {
+ const text = wordText.get(wordId);
+ if (text === undefined) throw new Error(`Fine Caption Atom references unknown word ${wordId}`);
+ push({
+ id: `${atomId}-base-${wordIndex + 1}`,
+ parent: atomId,
+ kind: "text",
+ text,
+ style: glyphStyle(parameters, parameters.basePaint),
+ attributes: [{ name: "data-caption-word", value: wordId }],
+ });
+ }
+ if (parameters.karaoke.mode === "off") continue;
+ const activeId = `${atomId}-active`;
+ push({
+ id: activeId,
+ parent: atomId,
kind: "box",
style: [
- { name: "background", value: parameters.box.background },
- { name: "border-radius", value: `${parameters.box.radiusPx}px` },
- { name: "display", value: "flex" },
- { name: "flex-wrap", value: "wrap" },
- { name: "justify-content", value: parameters.typography.textAlign === "left" ? "flex-start"
- : parameters.typography.textAlign === "right" ? "flex-end" : "center" },
- { name: "padding", value: `${parameters.box.paddingYPx}px ${parameters.box.paddingXPx}px` },
- { name: "text-align", value: parameters.typography.textAlign },
+ { name: "column-gap", value: `${compactNumber(parameters.layout.wordGapPx)}px` },
+ { name: "display", value: "inline-flex" },
+ { name: "inset", value: "0" },
+ { name: "overflow", value: "hidden" },
+ { name: "position", value: "absolute" },
],
- },
- ...wordIds.map((wordId, index): VisualElement => {
- return {
- id: `word-${index + 1}`,
- parent: "cue",
- order: index + 2,
+ animation: parameters.karaoke.transition === "step"
+ ? karaokeStepAnimation(parameters, timing.start, timing.end, durationFrames)
+ : karaokeWipeAnimation(parameters, timing.start, timing.end, durationFrames),
+ attributes: [{ name: "data-caption-karaoke", value: parameters.karaoke.mode }],
+ });
+ for (const [wordIndex, wordId] of atom.wordIds.entries()) {
+ const text = wordText.get(wordId)!;
+ push({
+ id: `${atomId}-active-${wordIndex + 1}`,
+ parent: activeId,
kind: "text",
- text: pieces[index]!,
- style: textStyle(parameters),
- attributes: [{ name: "data-caption-word", value: wordId }],
- };
- }),
- ];
+ text,
+ style: glyphStyle(parameters, parameters.activePaint),
+ attributes: [{ name: "data-caption-active-word", value: wordId }],
+ });
+ }
+ }
+ return elements;
}
export function renderFineCaption(
@@ -111,7 +313,6 @@ export function renderFineCaption(
const atoms = cue.atoms.map((timing) => atomById.get(timing.atomId));
if (atoms.some((atom) => atom === undefined)) throw new Error(`Fine Caption Cue ${cue.id} references unknown Atom`);
const resolvedAtoms = atoms.map((atom) => atom!);
- const wordIds = resolvedAtoms.flatMap((atom) => atom.wordIds);
const style = styles.get(cue.styleId);
if (style === undefined) throw new Error(`Fine Caption Cue ${cue.id} references unknown Style ${cue.styleId}`);
const parameters = style.rendering.parameters as unknown as FineCaptionParameters;
@@ -120,11 +321,16 @@ export function renderFineCaption(
const measuredEnd = Math.min(totalFrames, frameAt(space, cue.endSec));
const endFrameExclusive = Math.min(totalFrames, Math.max(startFrame + 1, measuredEnd));
if (startFrame >= totalFrames || endFrameExclusive <= startFrame) return [];
+ const durationFrames = endFrameExclusive - startFrame;
+ const atomFrames = new Map(cue.atoms.map((atom) => [atom.atomId, {
+ start: clamp(frameAt(space, atom.startSec) - startFrame, 0, durationFrames),
+ end: clamp(Math.max(frameAt(space, atom.endSec) - startFrame, frameAt(space, atom.startSec) - startFrame + 1), 0, durationFrames),
+ }]));
return [{
id: cue.id,
span: { startFrame, endFrameExclusive },
stacking: { order: parameters.stackingOrder, tieBreak: `${program.id}:${cue.id}` },
- elements: cueElements(wordIds, parameters, wordText),
+ elements: cueElements(resolvedAtoms, atomFrames, parameters, wordText, durationFrames),
}];
});
const track = sealVisualTrack({
diff --git a/packages/caption-fine/src/style.ts b/packages/caption-fine/src/style.ts
index 17f01f09..575ea829 100644
--- a/packages/caption-fine/src/style.ts
+++ b/packages/caption-fine/src/style.ts
@@ -2,34 +2,67 @@ import type { CaptionStyleIntent } from "@narratage/caption";
import { sealCaptionStyle } from "@narratage/caption";
import type { SvsRecipe } from "@narratage/svs";
-import type { FineCaptionParameters } from "./types.js";
+import type { FineCaptionGlyphPaint, FineCaptionParameters } from "./types.js";
export const FINE_CAPTION_FAMILY = "@narratage/caption-fine@1";
-function number(value: SvsRecipe, name: string): number {
- const property = value.properties[name];
+const REQUIRED_PROPERTIES = [
+ "align", "background", "cue-max-words", "cue-min-words", "fill", "font",
+ "line-height", "padding", "radius", "size", "stack-order", "weight", "width", "x", "y",
+] as const;
+
+const OPTIONAL_PROPERTIES = [
+ "active-fill", "active-glow-blur", "active-glow-color", "active-glow-opacity", "active-opacity",
+ "active-scale", "active-shadow-blur", "active-shadow-color", "active-shadow-opacity", "active-shadow-x",
+ "active-shadow-y", "active-stroke-color", "active-stroke-width", "anchor-x", "anchor-y", "atom-reveal",
+ "border-color", "border-width", "cue-enter", "cue-exit", "cue-transition-frames", "direction", "font-style",
+ "glow-blur", "glow-color", "glow-opacity", "karaoke", "karaoke-transition", "letter-spacing", "opacity",
+ "shadow-blur", "shadow-color", "shadow-opacity", "shadow-x", "shadow-y", "stroke-color", "stroke-width",
+ "word-gap",
+] as const;
+
+const ALLOWED_PROPERTIES = new Set<string>([...REQUIRED_PROPERTIES, ...OPTIONAL_PROPERTIES]);
+
+function required(value: SvsRecipe, name: string): unknown {
+ if (!Object.hasOwn(value.properties, name)) throw new Error(`Fine Caption Recipe requires ${name}`);
+ return value.properties[name];
+}
+
+function number(value: SvsRecipe, name: string, fallback?: number): number {
+ const property = Object.hasOwn(value.properties, name) ? value.properties[name] : fallback;
if (typeof property !== "number" || !Number.isFinite(property)) {
throw new Error(`Fine Caption Recipe ${name} must be a number`);
}
return property;
}
-function integer(value: SvsRecipe, name: string): number {
- const property = number(value, name);
+function integer(value: SvsRecipe, name: string, fallback?: number): number {
+ const property = number(value, name, fallback);
if (!Number.isSafeInteger(property)) throw new Error(`Fine Caption Recipe ${name} must be an integer`);
return property;
}
-function string(value: SvsRecipe, name: string): string {
- const property = value.properties[name];
+function string(value: SvsRecipe, name: string, fallback?: string): string {
+ const property = Object.hasOwn(value.properties, name) ? value.properties[name] : fallback;
if (typeof property !== "string" || !property.trim()) {
throw new Error(`Fine Caption Recipe ${name} must be a string`);
}
return property.trim();
}
-function color(value: SvsRecipe, name: string): string {
- const property = string(value, name);
+function choice<const T extends readonly string[]>(
+ value: SvsRecipe,
+ name: string,
+ choices: T,
+ fallback?: T[number],
+): T[number] {
+ const property = string(value, name, fallback);
+ if (!choices.includes(property)) throw new Error(`Fine Caption Recipe ${name} is invalid`);
+ return property as T[number];
+}
+
+function color(value: SvsRecipe, name: string, fallback?: string): string {
+ const property = string(value, name, fallback);
if (!/^#[0-9a-f]{6}(?:[0-9a-f]{2})?$/iu.test(property)) {
throw new Error(`Fine Caption Recipe ${name} must be an RGB or RGBA hex color`);
}
@@ -44,37 +77,111 @@ function padding(value: string): { readonly x: number; readonly y: number } {
return { y: parts[0]!, x: parts[1] ?? parts[0]! };
}
-export function fineCaptionParameters(recipe: SvsRecipe): FineCaptionParameters {
- const expected = [
- "align", "background", "cue-max-words", "cue-min-words", "fill", "font",
- "line-height", "padding", "radius", "size", "stack-order", "weight", "width", "x", "y",
- ];
- if (Object.keys(recipe.properties).sort().join("\0") !== expected.sort().join("\0")) {
- throw new Error(`Fine Caption Recipe requires exactly ${expected.join(", ")}`);
+function glyphPaint(recipe: SvsRecipe, prefix: "" | "active-", base?: FineCaptionGlyphPaint): FineCaptionGlyphPaint {
+ const fallback = <K extends keyof FineCaptionGlyphPaint>(key: K): FineCaptionGlyphPaint[K] | undefined => base?.[key];
+ const baseShadow = fallback("shadow") as FineCaptionGlyphPaint["shadow"] | undefined;
+ const baseGlow = fallback("glow") as FineCaptionGlyphPaint["glow"] | undefined;
+ const baseStroke = fallback("stroke") as FineCaptionGlyphPaint["stroke"] | undefined;
+ return {
+ fill: color(recipe, `${prefix}fill`, prefix === "active-" ? "#FFD54A" : base?.fill),
+ opacity: number(recipe, `${prefix}opacity`, base?.opacity ?? 1),
+ stroke: {
+ color: color(recipe, `${prefix}stroke-color`, baseStroke?.color ?? "#000000"),
+ widthPx: number(recipe, `${prefix}stroke-width`, baseStroke?.widthPx ?? 0),
+ },
+ shadow: {
+ color: color(recipe, `${prefix}shadow-color`, baseShadow?.color ?? "#000000"),
+ opacity: number(recipe, `${prefix}shadow-opacity`, baseShadow?.opacity ?? 0),
+ offsetXPx: number(recipe, `${prefix}shadow-x`, baseShadow?.offsetXPx ?? 0),
+ offsetYPx: number(recipe, `${prefix}shadow-y`, baseShadow?.offsetYPx ?? 0),
+ blurPx: number(recipe, `${prefix}shadow-blur`, baseShadow?.blurPx ?? 0),
+ },
+ glow: {
+ color: color(recipe, `${prefix}glow-color`, baseGlow?.color ?? "#FFFFFF"),
+ opacity: number(recipe, `${prefix}glow-opacity`, baseGlow?.opacity ?? 0),
+ blurPx: number(recipe, `${prefix}glow-blur`, baseGlow?.blurPx ?? 0),
+ },
+ };
+}
+
+function assertColor(value: string, label: string): void {
+ if (!/^#[0-9a-f]{6}(?:[0-9a-f]{2})?$/iu.test(value)) throw new Error(`${label} is invalid`);
+}
+
+function assertOpacity(value: number, label: string): void {
+ if (!Number.isFinite(value) || value < 0 || value > 1) throw new Error(`${label} must be between 0 and 1`);
+}
+
+function assertPaint(value: FineCaptionGlyphPaint, label: string): void {
+ assertColor(value.fill, `${label} fill`);
+ assertOpacity(value.opacity, `${label} opacity`);
+ assertColor(value.stroke.color, `${label} stroke color`);
+ assertColor(value.shadow.color, `${label} shadow color`);
+ assertColor(value.glow.color, `${label} glow color`);
+ assertOpacity(value.shadow.opacity, `${label} shadow opacity`);
+ assertOpacity(value.glow.opacity, `${label} glow opacity`);
+ for (const [name, metric] of [
+ ["stroke width", value.stroke.widthPx], ["shadow blur", value.shadow.blurPx], ["glow blur", value.glow.blurPx],
+ ] as const) {
+ if (!Number.isFinite(metric) || metric < 0) throw new Error(`${label} ${name} is invalid`);
}
- const align = string(recipe, "align");
- if (align !== "left" && align !== "center" && align !== "right") {
- throw new Error("Fine Caption Recipe align is invalid");
+ if (!Number.isFinite(value.shadow.offsetXPx) || !Number.isFinite(value.shadow.offsetYPx)) {
+ throw new Error(`${label} shadow offset is invalid`);
}
+}
+
+export function fineCaptionParameters(recipe: SvsRecipe): FineCaptionParameters {
+ for (const name of REQUIRED_PROPERTIES) required(recipe, name);
+ const unknown = Object.keys(recipe.properties).filter((name) => !ALLOWED_PROPERTIES.has(name));
+ if (unknown.length > 0) throw new Error(`Fine Caption Recipe contains unknown property ${unknown[0]}`);
+
const pad = padding(string(recipe, "padding"));
+ const fontSizePx = number(recipe, "size");
+ const basePaint = glyphPaint(recipe, "");
const parameters: FineCaptionParameters = {
contract: "svml.caption-fine-parameters@1",
stackingOrder: integer(recipe, "stack-order"),
- placement: { x: number(recipe, "x"), y: number(recipe, "y"), width: number(recipe, "width") },
+ placement: {
+ x: number(recipe, "x"),
+ y: number(recipe, "y"),
+ width: number(recipe, "width"),
+ anchorX: choice(recipe, "anchor-x", ["left", "center", "right"] as const, "left"),
+ anchorY: choice(recipe, "anchor-y", ["top", "center", "bottom"] as const, "top"),
+ },
+ layout: {
+ textAlign: choice(recipe, "align", ["left", "center", "right"] as const),
+ direction: choice(recipe, "direction", ["ltr", "rtl"] as const, "ltr"),
+ lineHeight: number(recipe, "line-height"),
+ letterSpacingPx: number(recipe, "letter-spacing", 0),
+ wordGapPx: number(recipe, "word-gap", fontSizePx * 0.25),
+ },
typography: {
fontFamily: string(recipe, "font"),
- fontSizePx: number(recipe, "size"),
+ fontSizePx,
fontWeight: integer(recipe, "weight"),
- lineHeight: number(recipe, "line-height"),
- textAlign: align,
- fill: color(recipe, "fill"),
+ fontStyle: choice(recipe, "font-style", ["normal", "italic"] as const, "normal"),
},
- box: {
+ basePaint,
+ activePaint: glyphPaint(recipe, "active-", basePaint),
+ cueBox: {
background: color(recipe, "background"),
+ borderColor: color(recipe, "border-color", "#00000000"),
+ borderWidthPx: number(recipe, "border-width", 0),
paddingXPx: pad.x,
paddingYPx: pad.y,
radiusPx: number(recipe, "radius"),
},
+ karaoke: {
+ mode: choice(recipe, "karaoke", ["off", "current", "trail"] as const, "off"),
+ transition: choice(recipe, "karaoke-transition", ["step", "wipe"] as const, "step"),
+ },
+ motion: {
+ cueEnter: choice(recipe, "cue-enter", ["none", "fade"] as const, "none"),
+ cueExit: choice(recipe, "cue-exit", ["none", "fade"] as const, "none"),
+ cueTransitionFrames: integer(recipe, "cue-transition-frames", 0),
+ atomReveal: choice(recipe, "atom-reveal", ["all", "on-start"] as const, "all"),
+ activeScale: number(recipe, "active-scale", 1),
+ },
};
assertFineCaptionParameters(parameters);
return parameters;
@@ -85,20 +192,25 @@ export function assertFineCaptionParameters(value: FineCaptionParameters): void
if (!Number.isSafeInteger(value.stackingOrder) || value.stackingOrder < 0) {
throw new Error("Fine Caption stacking order is invalid");
}
- const numeric = [
+ const nonNegative = [
value.placement.x, value.placement.y, value.placement.width, value.typography.fontSizePx,
- value.typography.fontWeight, value.typography.lineHeight, value.box.paddingXPx, value.box.paddingYPx,
- value.box.radiusPx,
+ value.typography.fontWeight, value.layout.lineHeight, value.layout.wordGapPx, value.cueBox.paddingXPx,
+ value.cueBox.paddingYPx, value.cueBox.radiusPx, value.cueBox.borderWidthPx, value.motion.cueTransitionFrames,
];
- if (numeric.some((item) => !Number.isFinite(item) || item < 0)
+ if (nonNegative.some((item) => !Number.isFinite(item) || item < 0)
|| value.placement.x > 1 || value.placement.y > 1 || value.placement.width <= 0 || value.placement.width > 1
- || value.typography.fontSizePx <= 0 || value.typography.lineHeight <= 0) {
+ || value.typography.fontSizePx <= 0 || value.layout.lineHeight <= 0
+ || !Number.isSafeInteger(value.motion.cueTransitionFrames) || 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.typography.fontFamily.trim()) throw new Error("Fine Caption font family is empty");
- for (const colorValue of [value.typography.fill, value.box.background]) {
- if (!/^#[0-9a-f]{6}(?:[0-9a-f]{2})?$/iu.test(colorValue)) throw new Error("Fine Caption color is invalid");
+ if (!value.typography.fontFamily.trim() || value.typography.fontWeight < 1 || value.typography.fontWeight > 1000) {
+ throw new Error("Fine Caption typography is invalid");
}
+ assertColor(value.cueBox.background, "Fine Caption background");
+ assertColor(value.cueBox.borderColor, "Fine Caption border color");
+ assertPaint(value.basePaint, "Fine Caption base Paint");
+ assertPaint(value.activePaint, "Fine Caption active Paint");
}
export function fineCaptionStyle(id: string, recipe: SvsRecipe): CaptionStyleIntent {
@@ -114,7 +226,7 @@ export function fineCaptionStyle(id: string, recipe: SvsRecipe): CaptionStyleInt
cue: {
minimumWords,
maximumWords,
- instruction: `Split into complete semantic phrases of ${minimumWords} to ${maximumWords} display words. Never cross punctuation when avoidable.`,
+ instruction: `Split into complete semantic phrases of ${minimumWords} to ${maximumWords} display words. Never cut inside an Atom and avoid crossing punctuation. An indivisible Atom may exceed the requested maximum.`,
},
fields: [],
},
diff --git a/packages/caption-fine/src/types.ts b/packages/caption-fine/src/types.ts
index 38c464e8..a1de7466 100644
--- a/packages/caption-fine/src/types.ts
+++ b/packages/caption-fine/src/types.ts
@@ -1,3 +1,24 @@
+export type FineCaptionGlyphPaint = {
+ readonly fill: string;
+ readonly opacity: number;
+ readonly stroke: {
+ readonly color: string;
+ readonly widthPx: number;
+ };
+ readonly shadow: {
+ readonly color: string;
+ readonly opacity: number;
+ readonly offsetXPx: number;
+ readonly offsetYPx: number;
+ readonly blurPx: number;
+ };
+ readonly glow: {
+ readonly color: string;
+ readonly opacity: number;
+ readonly blurPx: number;
+ };
+};
+
export type FineCaptionParameters = {
readonly contract: "svml.caption-fine-parameters@1";
readonly stackingOrder: number;
@@ -5,19 +26,41 @@ export type FineCaptionParameters = {
readonly x: number;
readonly y: number;
readonly width: number;
+ readonly anchorX: "left" | "center" | "right";
+ readonly anchorY: "top" | "center" | "bottom";
+ };
+ readonly layout: {
+ readonly textAlign: "left" | "center" | "right";
+ readonly direction: "ltr" | "rtl";
+ readonly lineHeight: number;
+ readonly letterSpacingPx: number;
+ readonly wordGapPx: number;
};
readonly typography: {
readonly fontFamily: string;
readonly fontSizePx: number;
readonly fontWeight: number;
- readonly lineHeight: number;
- readonly textAlign: "left" | "center" | "right";
- readonly fill: string;
+ readonly fontStyle: "normal" | "italic";
};
- readonly box: {
+ readonly basePaint: FineCaptionGlyphPaint;
+ readonly activePaint: FineCaptionGlyphPaint;
+ readonly cueBox: {
readonly background: string;
+ readonly borderColor: string;
+ readonly borderWidthPx: number;
readonly paddingXPx: number;
readonly paddingYPx: number;
readonly radiusPx: number;
};
+ readonly karaoke: {
+ readonly mode: "off" | "current" | "trail";
+ readonly transition: "step" | "wipe";
+ };
+ readonly motion: {
+ readonly cueEnter: "none" | "fade";
+ readonly cueExit: "none" | "fade";
+ readonly cueTransitionFrames: number;
+ readonly atomReveal: "all" | "on-start";
+ readonly activeScale: number;
+ };
};
diff --git a/packages/caption-fine/test/caption-fine.test.ts b/packages/caption-fine/test/caption-fine.test.ts
index c011d180..92f0da95 100644
--- a/packages/caption-fine/test/caption-fine.test.ts
+++ b/packages/caption-fine/test/caption-fine.test.ts
@@ -3,7 +3,7 @@ import test from "node:test";
import { resolveCaptionProgram } from "@narratage/caption";
import type { TimedCaptionProjection } from "@narratage/caption";
-import { fineCaptionStyle, renderFineCaption } from "@narratage/caption-fine";
+import { fineCaptionParameters, fineCaptionStyle, renderFineCaption } from "@narratage/caption-fine";
import { sealProgramSpace } from "@narratage/program-space";
import { captionDisplaySequence, parseScript } from "@narratage/script";
import type { SvsRecipe } from "@narratage/svs";
@@ -60,9 +60,183 @@ test("one Fine renderer handles uniform Cue appearance as one peer VisualTrack",
const wordElements = track.presents[0]!.elements.filter((element) => element.kind === "text");
assert.equal(wordElements.length, 3);
assert.deepEqual(wordElements.map((element) => element.kind === "text" ? element.text : undefined),
- ["Meaning ", "becomes ", "visible."]);
+ ["Meaning", "becomes", "visible."]);
assert.equal(wordElements.every((element) => element.style.some((declaration) =>
declaration.name === "color" && declaration.value === "#FFFFFF")), true);
assert.equal(wordElements.every((element) =>
element.style.every((declaration) => declaration.name !== "transform")), true);
+ assert.equal(fineCaptionParameters(recipe).activePaint.fill, "#FFD54A");
+});
+
+test("Fine resolves the complete orthogonal Paint, anchor, karaoke and motion surface", () => {
+ const parameters = fineCaptionParameters({
+ ...recipe,
+ properties: {
+ ...recipe.properties,
+ "anchor-x": "center",
+ "anchor-y": "bottom",
+ direction: "rtl",
+ "letter-spacing": -1.5,
+ "word-gap": 11,
+ "font-style": "italic",
+ opacity: 0.9,
+ "stroke-color": "#101010",
+ "stroke-width": 3,
+ "shadow-color": "#000000",
+ "shadow-opacity": 0.75,
+ "shadow-x": 2,
+ "shadow-y": 4,
+ "shadow-blur": 8,
+ "glow-color": "#5CE1E6",
+ "glow-opacity": 0.6,
+ "glow-blur": 12,
+ "border-color": "#FFFFFF80",
+ "border-width": 2,
+ karaoke: "trail",
+ "karaoke-transition": "wipe",
+ "active-fill": "#FFDD00",
+ "active-opacity": 0.95,
+ "active-stroke-color": "#401000",
+ "active-stroke-width": 1,
+ "active-shadow-color": "#FF8800",
+ "active-shadow-opacity": 0.5,
+ "active-shadow-x": 0,
+ "active-shadow-y": 2,
+ "active-shadow-blur": 5,
+ "active-glow-color": "#FFFFFF",
+ "active-glow-opacity": 0.7,
+ "active-glow-blur": 10,
+ "cue-enter": "fade",
+ "cue-exit": "fade",
+ "cue-transition-frames": 6,
+ "atom-reveal": "on-start",
+ "active-scale": 1.08,
+ },
+ });
+
+ assert.deepEqual(parameters.placement, {
+ x: 0.08, y: 0.76, width: 0.84, anchorX: "center", anchorY: "bottom",
+ });
+ assert.equal(parameters.layout.direction, "rtl");
+ assert.equal(parameters.typography.fontStyle, "italic");
+ assert.equal(parameters.basePaint.stroke.widthPx, 3);
+ assert.equal(parameters.basePaint.glow.blurPx, 12);
+ assert.equal(parameters.activePaint.fill, "#FFDD00");
+ assert.equal(parameters.activePaint.shadow.offsetYPx, 2);
+ assert.deepEqual(parameters.karaoke, { mode: "trail", transition: "wipe" });
+ assert.deepEqual(parameters.motion, {
+ cueEnter: "fade", cueExit: "fade", cueTransitionFrames: 6, atomReveal: "on-start", activeScale: 1.08,
+ });
+});
+
+test("karaoke uses one active overlay per whole Atom and never invents Dual Text word timing", () => {
+ const narrative = parseScript("karaoke.svml", "<line>Hello <New York City | new york city> today.</line>");
+ const display = captionDisplaySequence(narrative, "story.caption");
+ const style = fineCaptionStyle("karaoke", {
+ ...recipe,
+ properties: {
+ ...recipe.properties,
+ karaoke: "trail",
+ "karaoke-transition": "wipe",
+ "active-fill": "#FFD54A",
+ "atom-reveal": "on-start",
+ "active-scale": 1.04,
+ "cue-enter": "fade",
+ "cue-exit": "fade",
+ "cue-transition-frames": 4,
+ },
+ });
+ const program = resolveCaptionProgram(display, "karaoke-captions", style, []);
+ const projection: TimedCaptionProjection = {
+ contract: "svml.timed-caption-projection@1",
+ displaySequenceId: display.id,
+ cues: [{
+ id: "cue:karaoke",
+ runId: program.runs[0]!.id,
+ styleId: style.id,
+ segmentId: "line",
+ startSec: 0,
+ endSec: 3,
+ atoms: display.atoms.map((atom, index) => ({ atomId: atom.id, startSec: index, endSec: index + 1 })),
+ fields: [],
+ }],
+ };
+ const space = sealProgramSpace({
+ contract: "svml.program-space@1",
+ durationSec: 3,
+ frameRate: { numerator: 30, denominator: 1 },
+ });
+
+ const track = renderFineCaption(projection, program, display, space);
+ const elements = track.presents[0]!.elements;
+ const dualAtom = display.atoms.find((atom) => atom.wordIds.length === 3)!;
+ const dualContainer = elements.find((element) =>
+ element.attributes?.some((attribute) => attribute.name === "data-caption-atom" && attribute.value === dualAtom.id));
+ assert.ok(dualContainer);
+ const activeLayer = elements.find((element) => element.parent === dualContainer.id
+ && element.attributes?.some((attribute) => attribute.name === "data-caption-karaoke"));
+ assert.ok(activeLayer?.animation);
+ assert.equal(activeLayer.animation.keyframes.some((keyframe) => keyframe.style.some((item) =>
+ item.name === "clip-path" && String(item.value).includes("inset"))), true);
+ assert.equal(elements.filter((element) => element.parent === activeLayer.id && element.kind === "text").length, 3);
+ assert.equal(elements.filter((element) => element.attributes?.some((attribute) =>
+ attribute.name === "data-caption-karaoke")).length, display.atoms.length);
+});
+
+test("Fine rejects unknown or obsolete Recipe dimensions instead of silently accepting them", () => {
+ assert.throws(() => fineCaptionStyle("bad", {
+ ...recipe,
+ properties: { ...recipe.properties, important: true },
+ }), /unknown property important/u);
+});
+
+test("current/trail by step/wipe have four distinct frame-exact Atom histories", () => {
+ const narrative = parseScript("modes.svml", "<line>First second.</line>");
+ const display = captionDisplaySequence(narrative, "story.caption");
+ const space = sealProgramSpace({
+ contract: "svml.program-space@1",
+ durationSec: 2,
+ frameRate: { numerator: 10, denominator: 1 },
+ });
+ const render = (mode: "current" | "trail", transition: "step" | "wipe") => {
+ const style = fineCaptionStyle(`${mode}-${transition}`, {
+ ...recipe,
+ properties: { ...recipe.properties, karaoke: mode, "karaoke-transition": transition },
+ });
+ const program = resolveCaptionProgram(display, `program-${mode}-${transition}`, style, []);
+ const projection: TimedCaptionProjection = {
+ contract: "svml.timed-caption-projection@1",
+ displaySequenceId: display.id,
+ cues: [{
+ id: "cue:modes",
+ runId: program.runs[0]!.id,
+ styleId: style.id,
+ segmentId: "line",
+ startSec: 0,
+ endSec: 2,
+ atoms: display.atoms.map((atom, index) => ({ atomId: atom.id, startSec: index, endSec: index + 1 })),
+ fields: [],
+ }],
+ };
+ const track = renderFineCaption(projection, program, display, space);
+ return track.presents[0]!.elements.find((element) => element.id === "atom-1-active")!.animation!.keyframes;
+ };
+ const at = (keyframes: ReturnType<typeof render>, frame: number, property: string) =>
+ keyframes.find((keyframe) => keyframe.atFrame === frame)!.style.find((item) => item.name === property)!.value;
+
+ const currentStep = render("current", "step");
+ assert.equal(at(currentStep, 0, "opacity"), 1);
+ assert.equal(at(currentStep, 10, "opacity"), 0);
+ const trailStep = render("trail", "step");
+ assert.equal(at(trailStep, 0, "opacity"), 1);
+ assert.equal(at(trailStep, 20, "opacity"), 1);
+
+ const currentWipe = render("current", "wipe");
+ assert.equal(at(currentWipe, 0, "clip-path"), "inset(0 100% 0 0)");
+ assert.equal(at(currentWipe, 9, "clip-path"), "inset(0 0% 0 0)");
+ assert.equal(at(currentWipe, 10, "clip-path"), "inset(0 100% 0 0)");
+ const trailWipe = render("trail", "wipe");
+ assert.equal(at(trailWipe, 0, "clip-path"), "inset(0 100% 0 0)");
+ assert.equal(at(trailWipe, 10, "clip-path"), "inset(0 0% 0 0)");
+ assert.equal(at(trailWipe, 20, "clip-path"), "inset(0 0% 0 0)");
});
diff --git a/packages/hyperframes/test/browser-visual.test.ts b/packages/hyperframes/test/browser-visual.test.ts
index 8934fe88..003f1c71 100644
--- a/packages/hyperframes/test/browser-visual.test.ts
+++ b/packages/hyperframes/test/browser-visual.test.ts
@@ -1,10 +1,14 @@
import { spawnSync } from "node:child_process";
import { createHash } from "node:crypto";
+import { createRequire } from "node:module";
import { copyFile, mkdir, mkdtemp, readdir, rm, writeFile } from "node:fs/promises";
import os from "node:os";
import path from "node:path";
import test from "node:test";
import { deflateSync } from "node:zlib";
+import { resolveCaptionProgram } from "@narratage/caption";
+import type { TimedCaptionProjection } from "@narratage/caption";
+import { fineCaptionStyle, renderFineCaption } from "@narratage/caption-fine";
import type { FontArtifactRef } from "@narratage/media";
import { sealProgramSpace } from "@narratage/program-space";
import { sealComposition, sealVisualTrack } from "@narratage/composition";
@@ -14,10 +18,14 @@ import {
materializeHyperframesHtml,
} from "@narratage/hyperframes";
import type { Digest } from "@narratage/protocol";
+import { captionDisplaySequence, parseScript } from "@narratage/script";
+import type { SvsRecipe } from "@narratage/svs";
const enabled = process.env.SVML_BROWSER_TESTS === "1";
const localFont = process.env.SVML_TEST_FONT_PATH
?? (process.platform === "darwin" ? "/System/Library/Fonts/SFNSMono.ttf" : undefined);
+const hyperframesCli = createRequire(path.join(process.cwd(), "packages/provider-hyperframes-local/package.json"))
+ .resolve("hyperframes/bin/hyperframes.mjs");
function digest(bytes: Uint8Array): Digest {
return `sha256:${createHash("sha256").update(bytes).digest("hex")}` as Digest;
@@ -81,6 +89,31 @@ async function findPng(directory: string): Promise<string | undefined> {
return undefined;
}
+async function collectPngs(directory: string): Promise<string[]> {
+ const result: string[] = [];
+ for (const entry of await readdir(directory, { withFileTypes: true })) {
+ const absolute = path.join(directory, entry.name);
+ if (entry.isDirectory()) result.push(...await collectPngs(absolute));
+ else if (entry.name.endsWith(".png")) result.push(absolute);
+ }
+ return result.sort();
+}
+
+function yellowPixels(file: string, width: number, height: number): number {
+ const decoded = spawnSync("ffmpeg", [
+ "-v", "error", "-i", file, "-f", "rawvideo", "-pix_fmt", "rgba", "pipe:1",
+ ], { encoding: "buffer", timeout: 30_000 });
+ assert.equal(decoded.status, 0, decoded.stderr.toString());
+ assert.equal(decoded.stdout.byteLength, width * height * 4);
+ let count = 0;
+ for (let index = 0; index < decoded.stdout.byteLength; index += 4) {
+ if (decoded.stdout[index]! > 180 && decoded.stdout[index + 1]! > 130 && decoded.stdout[index + 2]! < 140) {
+ count += 1;
+ }
+ }
+ return count;
+}
+
test("locked font and straight-alpha Surface survive one real Hyperframes browser frame", {
skip: !enabled || localFont === undefined,
timeout: 120_000,
@@ -191,7 +224,7 @@ test("locked font and straight-alpha Surface survive one real Hyperframes browse
const output = path.join(temp, "frames");
await mkdir(output);
const render = spawnSync(process.execPath, [
- path.join(process.cwd(), "node_modules/hyperframes/bin/hyperframes.mjs"),
+ hyperframesCli,
"render",
temp,
"--format", "png-sequence",
@@ -232,3 +265,73 @@ test("locked font and straight-alpha Surface survive one real Hyperframes browse
await rm(temp, { recursive: true, force: true });
}
});
+
+test("Fine Caption Paint and trail wipe survive real frame rendering", {
+ skip: !enabled,
+ timeout: 120_000,
+}, async () => {
+ const temp = await mkdtemp(path.join(os.tmpdir(), "svml-caption-fine-visual-"));
+ try {
+ const width = 360;
+ const height = 180;
+ const space = sealProgramSpace({
+ contract: "svml.program-space@1",
+ durationSec: 2,
+ frameRate: { numerator: 10, denominator: 1 },
+ });
+ const narrative = parseScript("visual.svml", "<line>First second.</line>");
+ const display = captionDisplaySequence(narrative, "visual.caption");
+ const recipe: SvsRecipe = {
+ contract: "svml.svs-recipe@1",
+ path: "caption.visual",
+ properties: {
+ "cue-min-words": 1, "cue-max-words": 4,
+ "stack-order": 10, x: 0.5, y: 0.82, width: 0.92,
+ "anchor-x": "center", "anchor-y": "bottom",
+ font: "Arial", weight: 800, size: 44, "line-height": 1,
+ align: "center", fill: "#FFFFFF",
+ "stroke-color": "#000000", "stroke-width": 2,
+ "shadow-color": "#000000", "shadow-opacity": 0.8,
+ "shadow-x": 0, "shadow-y": 2, "shadow-blur": 4,
+ background: "#111111CC", padding: "10 14", radius: 10,
+ karaoke: "trail", "karaoke-transition": "wipe", "active-fill": "#FFD54A",
+ },
+ };
+ const style = fineCaptionStyle("visual", recipe);
+ const program = resolveCaptionProgram(display, "visual-program", style, []);
+ const projection: TimedCaptionProjection = {
+ contract: "svml.timed-caption-projection@1",
+ displaySequenceId: display.id,
+ cues: [{
+ id: "visual-cue", runId: program.runs[0]!.id, styleId: style.id, segmentId: "line",
+ startSec: 0, endSec: 2,
+ atoms: display.atoms.map((atom, index) => ({ atomId: atom.id, startSec: index, endSec: index + 1 })),
+ fields: [],
+ }],
+ };
+ const track = renderFineCaption(projection, program, display, space);
+ const document = compileHyperframesDocument(sealComposition({
+ contract: "svml.composition@1",
+ id: "caption-fine-visual",
+ canvas: { width, height, clearColor: "#000000" },
+ tracks: [track],
+ }), space);
+ await writeFile(path.join(temp, "index.html"), document.html);
+ const output = path.join(temp, "frames");
+ await mkdir(output);
+ const render = spawnSync(process.execPath, [
+ hyperframesCli, "render", temp,
+ "--format", "png-sequence", "--output", output, "--fps", "10", "--workers", "1",
+ "--no-browser-gpu", "--no-best-effort", "--quiet",
+ ], { encoding: "utf8", timeout: 110_000 });
+ assert.equal(render.status, 0, `${render.stdout}\n${render.stderr}`);
+ const frames = await collectPngs(output);
+ assert.equal(frames.length, 20);
+ const initialYellow = yellowPixels(frames[0]!, width, height);
+ const finalYellow = yellowPixels(frames.at(-1)!, width, height);
+ assert.ok(initialYellow < 10, `first wipe frame unexpectedly painted ${initialYellow} active pixels`);
+ assert.ok(finalYellow > 100, `trail wipe painted only ${finalYellow} active pixels at the end`);
+ } finally {
+ await rm(temp, { recursive: true, force: true });
+ }
+});
diff --git a/spec/caption-fine.md b/spec/caption-fine.md
index 516bfd75..f61e27d4 100644
--- a/spec/caption-fine.md
+++ b/spec/caption-fine.md
@@ -1,64 +1,155 @@
# Fine Caption Style Family
-Status: implemented baseline; parameter surface remains deliberately small and pre-release.
+Status: complete public design recorded; implementation proceeds by the evidence gates below.
-## Purpose
+## Purpose and boundary
-`@narratage/caption-fine` is one concrete Caption Style family. In this family, "fine-grained"
-means that immutable Script display words are divided into short semantic Cues. It does not mean
-that individual words receive ornamental semantic classes.
+`@narratage/caption-fine` is the official field-free, fine-grained Caption Style family. "Fine"
+means that immutable display Atoms are planned into short semantic Cues and then rendered through
+one deterministic visual system. It does **not** mean `important`, semantic emphasis classes or
+random per-word styling.
-Every word in one Cue uses one uniform static appearance. This family declares:
+The package consumes three facts which already exist:
-```text
-planning.fields = []
-```
+1. a `CaptionProgram`, which assigns one complete Style to every display Word;
+2. a `TimedCaptionProjection`, which gives every Cue and whole Atom a proven time window;
+3. a `CaptionDisplaySequence`, which preserves the author's exact visible text and punctuation.
-It has no `important`, emphasis, active-word, karaoke or random-size semantics. Another package may
-declare fields or motion without changing this family or the common Caption contract.
-
-## Package boundary
+It emits one ordinary peer `VisualTrack`. It never changes text, calls a model, infers time inside a
+Dual Text Atom or adds Caption metadata to another contract.
| Owner | Responsibility |
|---|---|
-| `@narratage/caption` | generic Style envelope, Cue/field Plan law, total Style assignment and SemanticMap timing join |
-| `@narratage/caption-fine` | Fine Recipe schema, deterministic layout/paint interpretation and VisualTrack lowering |
-| `@narratage/media` | renderable byte identities such as the existing `FontArtifactRef`, never Caption typography policy |
-| `@narratage/visual-ir` | closed terminal element/style/keyframe vocabulary |
+| `@narratage/caption` | generic Style envelope, Cue/field Plan law, total Style assignment and Atom timing join |
+| `@narratage/caption-fine` | Fine Recipe schema, layout, Paint, local motion and VisualTrack lowering |
+| `@narratage/media` | exact reusable bytes such as `FontArtifactRef`, never Fine typography policy |
+| `@narratage/visual-ir` | closed code-free terminal element/style/keyframe vocabulary |
| Core | graph demand, validation, derivation and execution only; no Caption meaning |
-Using a Type owned by Caption or Media does not transfer implementation ownership. Removing a Fine
-field, changing a Fine anchor or revising its box layout must not modify Caption, Media, Visual IR,
-Composition or Core when the existing public Types can already carry the result.
+Changing a Fine shadow, anchor, karaoke mode or Cue box must not modify Caption, Media,
+Composition, Visual IR or Core while their existing public contracts can express the result.
+
+## Complete orthogonal surface
+
+The complete restrained family has these independent dimensions. Properties not listed here are
+not deferred accidents: they are deliberate non-goals for this family.
+
+### 1. Cue planning
+
+- `cue-min-words`
+- `cue-max-words`
+
+The planner may only cut between whole Atoms. An indivisible author Atom may exceed the preferred
+maximum; it is never split to satisfy a number.
+
+### 2. Placement and layout
+
+- normalized `x`, `y`, `width`
+- `anchor-x: left | center | right`
+- `anchor-y: top | center | bottom`
+- `align: left | center | right`
+- `direction: ltr | rtl`
+- `line-height`, `letter-spacing`, `word-gap`
+- absolute `stack-order`
+
+The Cue naturally wraps only between Atoms. Words inside one Atom never wrap apart. A hard
+`max-lines` control is intentionally unavailable until exact font bytes and browser-measured layout
+can fail the build rather than silently clip or truncate authored text.
+
+### 3. Typography
+
+- `font`, `weight`, `size`, `font-style: normal | italic`
+
+The current Recipe names an environment font. Exact `FontArtifactRef` input is a shared typography
+reproducibility gate and remains visible in the implementation table below.
+
+### 4. Base glyph Paint
+
+- solid `fill` and `opacity`
+- one outline: `stroke-color`, `stroke-width`
+- one shadow: color, opacity, x/y offset and blur
+- one glow: color, opacity and blur
+
+Shadow and glow are two independently authored contributions lowered into one deterministic
+`text-shadow` declaration. Multiple arbitrary layers, textures, gradients, bevel, extrusion and
+long-shadow generators are outside this restrained family.
+
+### 5. Cue box Paint
+
+- solid `background`
+- `border-color`, `border-width`
+- horizontal/vertical `padding`
+- `radius`
+
+Backdrop sampling is forbidden because it would make this Track inspect another Track's pixels.
+
+### 6. Karaoke Paint and timing
+
+- `karaoke: off | current | trail`
+- `karaoke-transition: step | wipe`
+- a complete active glyph Paint with the same fill/opacity/stroke/shadow/glow shape as base Paint
+
+`current` activates only the Atom whose measured window contains the frame. `trail` retains every
+activated Atom through the end of the Cue. `step` swaps the whole Atom; `wipe` reveals its active
+layer across that Atom's measured window. RTL reverses the wipe direction.
+
+Karaoke is deliberately Atom-grained. In ordinary text an Atom is normally one visible Word. In
+`<45% | forty five percent>` the authored visible `45%` is one Atom and activates as one unit. In a
+multi-word display Atom, the whole authored Atom activates together. No downstream package invents
+internal Word timestamps that the author and audio evidence never supplied.
+
+### 7. Restrained local motion
+
+- Cue enter/exit: `none | fade`, with one frame duration
+- Atom reveal: `all | on-start`
+- active Atom scale
+
+These motions affect only Fine's own elements. Typewriter, bounce, rotation, path motion and random
+variation are intentionally excluded until a concrete reusable style needs them.
+
+## One renderer, one layout tree
+
+Static and karaoke output share this structure:
+
+```text
+placement
+└── cue box
+ ├── atom
+ │ ├── base words
+ │ └── active overlay (only when karaoke is enabled)
+ │ └── active words
+ └── atom ...
+```
-## Accepted dimensions
+The active overlay reuses the same Atom geometry; karaoke does not fork a second DOM renderer.
+Every animation lowers to frame-addressed `VisualTrack` keyframes before HyperFrames sees it.
-The Style-family surface will be designed across four independent concerns:
+## Defaults and compatibility
-1. Cue planning: only minimum/maximum display-word bounds and a fixed no-rewrite planning law.
-2. Geometry: placement anchor, bounded range, alignment, line packing and absolute stack order.
-3. Typography: deterministic font choice and ordinary size/spacing metrics.
-4. Paint: restrained readability controls such as solid fill, outline, shadow and an optional
- content background.
+The original fifteen baseline properties remain required, so a minimal Recipe is explicit about
+planning, geometry, typography and its visible box. New dimensions are optional and resolve to a
+complete immutable parameter object:
-The exact property names, defaults and bounds are not frozen by this document. Motion, gradients,
-glow, long shadow, backdrop sampling, case rewriting, random variation and field-dependent paint
-must not enter merely to reproduce the old engine's option count.
+- top-left anchor, LTR, normal font, zero letter spacing and a one-quarter-em word gap;
+- no stroke, shadow, glow or border;
+- karaoke off, Cue motion off, all Atoms visible, scale 1;
+- when karaoke is enabled without another active Paint, active fill defaults to `#FFD54A` and the
+ other active Paint dimensions inherit base Paint.
-Cue timing is not a fifth Style dimension. It comes from the independent `TimedCaptionProjection`:
-the first and last included whole-Atom windows determine the Cue window. Fine adds no hidden hold,
-lead, fade or provider-dependent timing, and it receives no display-Word timestamps.
+Unknown properties are rejected. Defaults are package implementation policy and therefore covered
+by its implementation digest; they are not hidden Runtime behavior.
-## Font boundary
+## Evidence gates and implementation order
-The current executable Fine baseline names an environment font in its Recipe. Exact font bytes are
-a separate reproducibility problem shared by Text, Caption, Ranking and future typography
-components. `@narratage/media` already defines `FontArtifactRef`; adding an author Surface for local
-font files and connecting that value explicitly is separate work. It must not be smuggled into the
-Fine redesign as a Caption-specific Media contract.
+This is one complete design, delivered progressively rather than three incompatible versions:
-## Remaining visual evidence
+1. **Resolved model and static lowering** — complete parameters, anchors, layout, base/active Paint,
+ Cue box and strict validation.
+2. **Timed lowering** — current/trail, step/wipe, Cue fades, Atom reveal and active scale using only
+ proven whole-Atom time.
+3. **Reproducibility freeze** — exact Font Artifact input, real browser/pixel fixtures for wrapping,
+ outline/glow and all karaoke modes, then decide whether measured `max-lines` can be exposed
+ without clipping.
-The field-free contract is executable. Before freezing the family's visual surface, add real
-browser/pixel evidence for placement, wrapping and basic paint and review whether the current
-bounded left/top geometry is the smallest useful public parameter set.
+The first two gates require no common-contract change. The third may add an explicit Font input to
+the Fine Surface/fragment, but still does not belong in Core or common Caption.
diff --git a/spec/caption-program.md b/spec/caption-program.md
index 80cfa43e..b7bd1764 100644
--- a/spec/caption-program.md
+++ b/spec/caption-program.md
@@ -144,8 +144,8 @@ Each timed Cue selects the complete rendering payload of its resolved Style. One
renderer returns one ordinary `VisualTrack`. In the first contract, all Styles in one Program use
the same rendering family.
-`@narratage/caption-fine` is the first official family. It declares no fields and uses one uniform
-static appearance for all Words in a Cue. Another package may define karaoke or field-dependent
+`@narratage/caption-fine` is the first official family. It declares no fields and owns restrained
+uniform Cue appearance plus optional whole-Atom karaoke. Another package may define field-dependent
paint without modifying Script, Caption, Composition or Core.
Film does not recognize Caption specially. It folds the resulting peer Track beside Speech,