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 where how when protocol

kashorina12d5fa70914
diff --git a/docs/quickstart/tracks.md b/docs/quickstart/tracks.md
index 1662c04f..4a2b82f7 100644
--- a/docs/quickstart/tracks.md
+++ b/docs/quickstart/tracks.md
@@ -35,10 +35,13 @@ A Style is a rendering intent resolved from one package-owned SVS Recipe:
```svs
caption.primary {
stack-order: 70; x: 0.5; y: 0.88; width: 0.84;
+ height: 0.22;
anchor-x: center; anchor-y: bottom;
size: 58;
line-height: 0.96; letter-spacing: -0.5; word-gap: 14;
- align: center; direction: ltr;
+ align: center; block-align: end; inline-size: fixed;
+ wrap: word; overflow: clip; max-lines: 2; max-words-per-line: 4;
+ direction: ltr;
fill: #FFFFFF; opacity: 1;
stroke-color: #09090B; stroke-width: 2;
shadow-color: #000000; shadow-opacity: 0.72;
@@ -58,6 +61,7 @@ caption.primary {
cue-enter: fade; cue-enter-frames: 4; cue-exit: fade; cue-exit-frames: 4;
atom-reveal: all;
active-response: pop; active-response-frames: 5; active-scale: 1.08;
+ lead-frames: 4; tail-frames: 4; handoff: cut;
}
```
@@ -82,6 +86,12 @@ glow and underline; Cue/Pill Paint; three independent glyph/Pill/underline activ
and layered Cue, Alignment-Unit, active-response and loop motion. Missing optional dimensions resolve
deterministically to no decoration or motion. Unknown properties are rejected.
+The package groups those properties as **Where**, **How** and **When** in its Surface declaration,
+so Studio can present the same author contract without maintaining a Caption-specific property list.
+`lead-frames` and `tail-frames` form an explicit visible Schedule around the spoken Cue;
+`handoff: cut` prevents adjacent visible envelopes from competing, while `overlap` preserves both.
+Neither form changes the Word frames used by Karaoke.
+
`karaoke` is `off`, `current` or `trail`; `karaoke-transition` is `step` or `wipe`. Timing is always
whole-Alignment-Unit timing already proven by Caption. A normal one-word unit therefore highlights
per word, while a Dual Text unit remains one indivisible visible unit. Fine never guesses internal
@@ -92,9 +102,15 @@ one capsule per activated Alignment Unit; `joined` turns a trail into one ordere
continuous on each real browser line. Thus trail-colored text with a current-only Pill is one
Recipe—not a second renderer.
-Fine wraps only between complete Alignment Units and never clips author text. Cue boundaries come
-from Script segments, turns, Style changes and authored `||`; use Track width and font size to
-control density.
+With `wrap: word`, Fine wraps between complete Alignment Units and falls back inside a single
+over-wide display unit so it cannot escape the Region. `max-lines` is accepted only with the explicit
+`overflow: clip`; without that opt-in Fine does not silently discard author text. Cue boundaries come
+from Script segments, turns, Style changes and authored `||`.
+
+Fine is the uniform-flow family: every token follows the same Recipe and may differ only by time,
+index or play state. A Cue with authored internal roles—different font/layout groups, full-frame
+inversion, tearing or cross-clause composition—requires another Caption package rather than a hidden
+Fine exception.
CJK dialogue can be written directly. For a display-only emoji that still follows speech timing,
author the correspondence explicitly, such as `<🌐 | globe>`; the system will not invent a spoken
diff --git a/docs/zh/quickstart/tracks.md b/docs/zh/quickstart/tracks.md
index f5777f16..f511be0b 100644
--- a/docs/zh/quickstart/tracks.md
+++ b/docs/zh/quickstart/tracks.md
@@ -34,8 +34,11 @@ SemanticTrack 时间拼接。Fine 是一种样式族,负责自己的几何、
```svs
caption.primary {
stack-order: 70; x: 0.5; y: 0.88; width: 0.84;
+ height: 0.22;
anchor-x: center; anchor-y: bottom;
- size: 58; line-height: 1; align: center;
+ size: 58; line-height: 1;
+ align: center; block-align: end; inline-size: fixed;
+ wrap: word; overflow: clip; max-lines: 2; max-words-per-line: 4;
fill: #FFFFFF; stroke-color: #09090B; stroke-width: 2;
background: #00000000; padding: 0; radius: 0;
karaoke: trail; karaoke-transition: wipe; active-fill: #FFD54A;
@@ -44,6 +47,7 @@ caption.primary {
active-underline: current; active-underline-color: #FFFFFF;
cue-enter: spring; cue-enter-frames: 6;
active-response: pop; active-response-frames: 5; active-scale: 1.08;
+ lead-frames: 4; tail-frames: 4; handoff: cut;
}
```
@@ -63,8 +67,11 @@ Cue 边界由 Script 的 Segment、Role、样式变化和作者写出的 `||`
Fine 不是一组互斥预设。基础/激活渐变、描边、阴影、长阴影、外发光、下划线、Pill
和动画均为正交维度。文字、下划线和 Pill 各自选择 `off | current | trail`;因此可以直接表达“文字保留已读色,但 Pill 只跟随当前词”。`active-box-continuity: joined` 会把已读前缀在每个真实换行片段内连成一个背景,而不是给每个词分别套胶囊。
-Fine 只在完整 Alignment Unit 之间自然换行,永不裁掉作者文字。需要控制行数时,应调整
-Track 宽度与字号;Cue 分界由 Script 的结构和 `||` 决定。
+包在 Surface 声明中把参数分成 **Where / How / When**,Studio 直接消费这份作者协议,无需再维护字幕专用参数全集。`lead-frames`、`tail-frames` 先产生显式可见 Schedule;`handoff: cut` 负责相邻 Cue 的交接,`overlap` 则保留双方包络。二者都不会修改 Karaoke 使用的原始词帧。
+
+`wrap: word` 优先在完整 Alignment Unit 之间换行;单个显示单元若比 Region 还宽,会继续在内部回退换行,不会逃出范围。只有显式同时写出 `max-lines` 与 `overflow: clip` 才允许裁掉超出的行;否则不会静默丢字。Cue 分界由 Script 的结构和 `||` 决定。
+
+Fine 是“统一文字流”字幕:同一 Cue 的每个 token 遵守同一 Recipe,只允许时间、顺序和播放状态驱动差异。若 Cue 内存在不同字体/布局角色、全屏反色、撕裂或前后语块之间的合成关系,就应新建另一个 Caption 包,而不是给 Fine 塞隐藏例外。
CJK 口播可以直接书写。若一个只负责显示的 emoji 仍需跟随语音计时,应显式写出对应,例如 `<🌐 | globe>`;系统不会替裸符号虚构一个口播词。
diff --git a/examples/talking-film-graph-check/recipes.svs b/examples/talking-film-graph-check/recipes.svs
index 4f094ce7..e9f6f1fb 100644
--- a/examples/talking-film-graph-check/recipes.svs
+++ b/examples/talking-film-graph-check/recipes.svs
@@ -12,14 +12,17 @@
exit: fade; exit-frames: 4; exit-easing: ease-in;
}
caption.base {
- stack-order: 70; x: 0.5; y: 0.88; width: 0.84; anchor-x: center; anchor-y: bottom;
- size: 58; line-height: 1; align: center;
+ stack-order: 70; x: 0.5; y: 0.88; width: 0.84; height: 0.22;
+ anchor-x: center; anchor-y: bottom;
+ size: 58; line-height: 1; align: center; block-align: end; inline-size: fixed;
+ wrap: word; overflow: clip; max-lines: 2; max-words-per-line: 4;
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-enter-frames: 4; cue-exit: fade; cue-exit-frames: 4;
+ lead-frames: 4; tail-frames: 4; handoff: cut;
}
text.title {
stack-order: 90;
diff --git a/packages/caption-fine/README.md b/packages/caption-fine/README.md
index b701c830..e4403206 100644
--- a/packages/caption-fine/README.md
+++ b/packages/caption-fine/README.md
@@ -1,6 +1,8 @@
# `@hypit/caption-fine`
-The fine-grained Caption Style family. It renders a timed `CaptionDocument` as a VisualTrack.
+The uniform-flow Caption family. It renders authored Cues whose tokens all obey the same layout,
+type, Paint and motion rules. Spoken time and token order may change the state of that rule; a token
+does not carry a private visual role.
```xml
<caption-fine:Style id="primary" recipe={recipes.caption.primary} font={caption-font}/>
@@ -9,5 +11,32 @@ The fine-grained Caption Style family. It renders a timed `CaptionDocument` as a
semantic={speech.semantic} program={captions}/>
```
-The family owns geometry, typography and active-word painting. Cue grouping is authored by Script
-segments, turns, Style changes and `||`; it is not delegated to an LLM.
+One SVS Recipe freezes three public dimensions:
+
+- **Where**: Region position, anchors, extent, block/inline alignment, wrapping and line limits.
+- **How**: the exact font stack, typography, base/active glyph Paint, Cue box and decoration.
+- **When**: the visible lead/tail envelope, handoff, Cue/Atom motion, reveal, Karaoke and loops.
+
+Caption first projects authored Script units onto semantic Word timing. Fine then produces an
+explicit visible Schedule and renders that Schedule. Lead and tail never change the semantic Word
+times used by Karaoke.
+
+Cue grouping is authored by Script segments, turns, Style changes and `||`; it is not delegated to
+an LLM. Fine rejects word-specific Style runs. A caption whose Cue contains structural roles or
+relationships—an emphasis group with another font and layout, alternating full-frame inversion, or
+one clause tearing through another—belongs in a separate Caption family that consumes the common
+Caption contract. It is not a Fine preset.
+
+```svs
+caption.primary {
+ stack-order: 70;
+ x: 0.5; y: 0.9; width: 0.84; height: 0.22;
+ anchor-x: center; anchor-y: bottom;
+ align: center; block-align: end; inline-size: fixed;
+ wrap: word; overflow: clip; max-lines: 2; max-words-per-line: 4;
+ size: 58; line-height: 1; fill: #FFFFFF;
+ background: #00000000; padding: 0; radius: 0;
+ karaoke: current; active-fill: #FFD54A;
+ lead-frames: 4; tail-frames: 4; handoff: cut;
+}
+```
diff --git a/packages/caption-fine/src/component.ts b/packages/caption-fine/src/component.ts
index c8c818dd..a2aca67e 100644
--- a/packages/caption-fine/src/component.ts
+++ b/packages/caption-fine/src/component.ts
@@ -8,6 +8,8 @@ import { canonicalize } from "@hypit/protocol";
import { captionFineProducers } from "./manifest.js";
import { renderFineCaption } from "./render.js";
+import { scheduleFineCaption } from "./schedule.js";
+import type { FineCaptionSchedule } from "./types.js";
function inline<T>(value: StoredValue | undefined, subject: string): T {
if (value?.kind !== "inline") throw new Error(`${subject} must be inline`);
@@ -15,16 +17,29 @@ function inline<T>(value: StoredValue | undefined, subject: string): T {
}
export const captionFineComponent = {
- producers: [{
- producer: captionFineProducers.render,
- handler: ({ inputs }) => ({
- outputs: { track: { kind: "inline", value: canonicalize(renderFineCaption(
- inline<TimedCaptionProjection>(inputs.caption?.value, "TimedCaptionProjection"),
- inline<CaptionProgram>(inputs.program?.value, "CaptionProgram"),
- inline<CaptionDocument>(inputs.document?.value, "CaptionDocument"),
- projectSemanticProgramSpace(inline<SemanticTrack>(inputs.semantic?.value, "SemanticTrack")),
- )) } },
- needs: {},
- }),
- }],
+ producers: [
+ {
+ producer: captionFineProducers.schedule,
+ handler: ({ inputs }) => ({
+ outputs: { schedule: { kind: "inline", value: canonicalize(scheduleFineCaption(
+ inline<TimedCaptionProjection>(inputs.caption?.value, "TimedCaptionProjection"),
+ inline<CaptionProgram>(inputs.program?.value, "CaptionProgram"),
+ inline<CaptionDocument>(inputs.document?.value, "CaptionDocument"),
+ )) } },
+ needs: {},
+ }),
+ },
+ {
+ producer: captionFineProducers.render,
+ 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"),
+ projectSemanticProgramSpace(inline<SemanticTrack>(inputs.semantic?.value, "SemanticTrack")),
+ )) } },
+ needs: {},
+ }),
+ },
+ ],
} satisfies ComponentPackage;
diff --git a/packages/caption-fine/src/fragment.ts b/packages/caption-fine/src/fragment.ts
index 368497da..ca2815c7 100644
--- a/packages/caption-fine/src/fragment.ts
+++ b/packages/caption-fine/src/fragment.ts
@@ -25,11 +25,19 @@ export const fineCaptionTrackFragment = sealGraphFragment({
},
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.render,
inputs: {
- caption: operation("caption:temporalize-document"), program: input("program"),
+ schedule: operation("caption-fine:schedule"), program: input("program"),
document: input("document"), semantic: input("semantic"),
},
result: { kind: "output", name: "track" },
diff --git a/packages/caption-fine/src/index.ts b/packages/caption-fine/src/index.ts
index 1a7ce53a..e2066c44 100644
--- a/packages/caption-fine/src/index.ts
+++ b/packages/caption-fine/src/index.ts
@@ -1,7 +1,8 @@
export { captionFineComponent } from "./component.js";
export { fineCaptionTrackFragment } from "./fragment.js";
-export { captionFineManifest, captionFineMarkupSurfaces, captionFineModuleRef, captionFineProducers } from "./manifest.js";
+export { captionFineManifest, captionFineMarkupSurfaces, captionFineModuleRef, captionFineProducers, captionFineTypes } from "./manifest.js";
export { renderFineCaption } from "./render.js";
+export { assertFineCaptionSchedule, scheduleFineCaption } from "./schedule.js";
export {
fineCaptionOneShotMotions,
fineCaptionOptionalRecipeProperties,
diff --git a/packages/caption-fine/src/manifest.ts b/packages/caption-fine/src/manifest.ts
index 1b92372c..ca750143 100644
--- a/packages/caption-fine/src/manifest.ts
+++ b/packages/caption-fine/src/manifest.ts
@@ -2,11 +2,12 @@ import { readFile } from "node:fs/promises";
import { captionManifest, captionModuleRef, captionTypes } from "@hypit/caption";
import { compositionDependency, compositionTypes } from "@hypit/composition";
+import type { SurfaceRecipePropertyVocabulary } from "@hypit/markup";
import { mediaDependency, mediaTypes } from "@hypit/media";
import { narrativeDependency, narrativeTypes } from "@hypit/narrative";
+import type { ModuleManifest, ProducerRef } from "@hypit/protocol";
import { semanticTrackDependency, semanticTrackTypes } from "@hypit/semantic-track";
import { svsRecipeType } from "@hypit/svs";
-import type { ModuleManifest, ProducerRef } from "@hypit/protocol";
import { fineCaptionOneShotMotions } from "./recipe.js";
@@ -16,8 +17,63 @@ const previewImage = (file: string) => ({
open: async () => Uint8Array.from(await readFile(new URL(`../preview/${file}`, import.meta.url))),
});
+const WHERE_PROPERTIES = new Set([
+ "stack-order", "x", "y", "width", "height", "anchor-x", "anchor-y", "align", "block-align",
+ "inline-size", "wrap", "overflow", "max-lines", "max-words-per-line", "direction", "line-height",
+ "letter-spacing", "word-gap",
+]);
+
+const TIMED_ACTIVE_BOX_PROPERTIES = new Set([
+ "active-box",
+ "active-box-continuity",
+ "active-box-enter",
+ "active-box-exit",
+ "active-box-transition-frames",
+]);
+
+function fineCaptionRecipeGroup(name: string): "where" | "how" | "when" {
+ if (WHERE_PROPERTIES.has(name)) return "where";
+ if (name === "lead-frames" || name === "tail-frames" || name === "handoff"
+ || name === "karaoke" || name === "karaoke-transition"
+ || name === "active-underline"
+ || name.startsWith("cue-enter") || name.startsWith("cue-exit")
+ || name.startsWith("atom-") || name.startsWith("active-response")
+ || name.startsWith("loop") || name === "slide-distance" || name === "active-scale"
+ || TIMED_ACTIVE_BOX_PROPERTIES.has(name)) return "when";
+ return "how";
+}
+
+function fineCaptionRecipeSection(name: string, group: "where" | "how" | "when"): string {
+ if (group === "where") return ["x", "y", "width", "height", "anchor-x", "anchor-y", "stack-order"].includes(name)
+ ? "region" : "flow";
+ if (group === "when") {
+ if (["lead-frames", "tail-frames", "handoff"].includes(name)) return "envelope";
+ if (name.startsWith("cue-")) return "cue";
+ if (name.startsWith("loop")) return "loop";
+ return "token";
+ }
+ if (["size", "kerning", "caps", "text-transform"].includes(name)) return "typography";
+ if (name === "background" || name === "border-color" || name === "border-width" || name === "padding"
+ || name === "radius" || name.startsWith("cue-shadow")) return "cue-box";
+ if (name.startsWith("active-box") || name.includes("underline")) return "decoration";
+ return name.startsWith("active-") ? "active-paint" : "base-paint";
+}
+
+function withFineCaptionRecipeGroups<const T extends readonly SurfaceRecipePropertyVocabulary[]>(
+ properties: T,
+): readonly SurfaceRecipePropertyVocabulary[] {
+ return properties.map((property) => {
+ const group = fineCaptionRecipeGroup(property.name);
+ return { ...property, group, section: fineCaptionRecipeSection(property.name, group) };
+ });
+}
+
export const captionFineModuleRef = { name: "@hypit/caption-fine", version: "1" } as const;
+export const captionFineTypes = {
+ schedule: { module: captionFineModuleRef, name: "FineCaptionSchedule" },
+} as const;
export const captionFineProducers = {
+ schedule: { module: captionFineModuleRef, name: "schedule-fine-caption" },
render: { module: captionFineModuleRef, name: "render-fine-caption" },
} satisfies Record<string, ProducerRef>;
@@ -31,7 +87,7 @@ export const captionFineMarkupSurfaces = [
summary: "Names this Style so a Caption Program can assign it." },
{ name: "recipe", kind: "reference", required: true, accepts: [svsRecipeType],
summary: "Chooses the Recipe that carries Cue geometry, Paint and local motion.",
- recipe: [
+ recipe: withFineCaptionRecipeGroups([
{ name: "stack-order", required: true,
summary: "Places this Style's Cues in the Track's drawing order, low behind high." },
{ name: "x", required: true,
@@ -40,12 +96,26 @@ export const captionFineMarkupSurfaces = [
summary: "Places the Cue box vertically as a fraction of the Canvas height." },
{ name: "width", required: true,
summary: "Sets the Cue box width as a fraction of the Canvas width." },
+ { name: "height", required: false,
+ summary: "Optionally gives the Caption Region a fixed fraction of Canvas height; without it the Region hugs its Cue." },
{ name: "anchor-x", required: false, values: ["left", "center", "right"], fallback: "left",
summary: "Decides which horizontal edge of the Cue box sits on the placement point." },
{ name: "anchor-y", required: false, values: ["top", "center", "bottom"], fallback: "top",
summary: "Decides which vertical edge of the Cue box sits on the placement point." },
{ name: "align", required: true, values: ["left", "center", "right"],
summary: "Aligns the Words within each line of the Cue." },
+ { name: "block-align", required: false, values: ["start", "center", "end"], fallback: "center",
+ summary: "Aligns the Cue vertically inside a fixed-height Caption Region." },
+ { name: "inline-size", required: false, values: ["hug", "fixed"], fallback: "hug",
+ summary: "Chooses whether the Cue hugs its text up to the Region width or fills the Region width." },
+ { name: "wrap", required: false, values: ["word", "grapheme"], fallback: "word",
+ summary: "Wraps at Word boundaries, falling back for an over-wide Word, or permits a break at any grapheme." },
+ { name: "overflow", required: false, values: ["visible", "clip"], fallback: "visible",
+ summary: "Keeps Paint overflow visible or clips the Cue to its declared line envelope." },
+ { name: "max-lines", required: false,
+ summary: "Caps the Cue's visible line boxes; it is accepted only together with overflow: clip." },
+ { name: "max-words-per-line", required: false,
+ summary: "Forces a new line after this many display Words while preserving authored Cue boundaries." },
{ name: "direction", required: false, values: ["ltr", "rtl"], fallback: "ltr",
summary: "Sets the writing direction the Words are laid out in." },
{ name: "line-height", required: true,
@@ -56,7 +126,11 @@ export const captionFineMarkupSurfaces = [
summary: "Sets the pixel gap between neighbouring Words." },
{ name: "size", required: true,
summary: "Sets the type size in pixels." },
- { name: "text-transform", required: false, values: ["none", "uppercase", "lowercase"], fallback: "none",
+ { name: "kerning", required: false, values: ["auto", "normal", "none"], fallback: "auto",
+ summary: "Controls font kerning for the complete uniform Cue flow." },
+ { name: "caps", required: false, values: ["normal", "small-caps", "all-small-caps"], fallback: "normal",
+ summary: "Chooses the OpenType caps presentation for every Word." },
+ { name: "text-transform", required: false, values: ["none", "uppercase", "lowercase", "capitalize"], fallback: "none",
summary: "Recases every display Word before it is drawn." },
{ name: "fill", required: true,
summary: "Paints the glyph body of an ordinary Word, as an RGB or RGBA hex color." },
@@ -82,6 +156,8 @@ export const captionFineMarkupSurfaces = [
summary: "Offsets the glyph drop shadow vertically in pixels." },
{ name: "shadow-blur", required: false, fallback: "0",
summary: "Softens the glyph drop shadow by this many pixels. A shadow that only has to lift the caption off the picture is soft and short — a blur near a tenth of `size` with an offset a fraction of that. Much more and the shadow stops being an edge and becomes a grey cloud the letters sit in, which costs the contrast the shadow was there to protect." },
+ { name: "shadow-spread", required: false, fallback: "0",
+ summary: "Expands or contracts the glyph shadow shape before it is blurred." },
{ name: "long-shadow-color", required: false, fallback: "#000000",
summary: "Paints the solid extruded shadow trailing each glyph." },
{ name: "long-shadow-opacity", required: false, fallback: "0",
@@ -96,6 +172,8 @@ export const captionFineMarkupSurfaces = [
summary: "Sets how strongly the glyph halo reads." },
{ name: "glow-blur", required: false, fallback: "0",
summary: "Spreads the glyph halo by this many pixels. A halo reads as a halo while it stays close to the glyph — near a tenth of `size`. Spread wide it stops tracing the letters, fills the space between them and washes the caption into a bright smear; the gaps between letters go first, exactly as they do under a heavy outline." },
+ { name: "glow-spread", required: false, fallback: "0",
+ summary: "Expands the glyph alpha before the halo is blurred." },
{ name: "active-fill", required: false, fallback: "#FFD54A",
summary: "Paints the glyph body of the Word being spoken." },
{ name: "active-opacity", required: false, fallback: "opacity",
@@ -120,6 +198,8 @@ export const captionFineMarkupSurfaces = [
summary: "Offsets the active drop shadow vertically in pixels." },
{ name: "active-shadow-blur", required: false, fallback: "shadow-blur",
summary: "Softens the active drop shadow by this many pixels." },
+ { name: "active-shadow-spread", required: false, fallback: "shadow-spread",
+ summary: "Expands or contracts the active glyph shadow before blur." },
{ name: "active-long-shadow-color", required: false, fallback: "long-shadow-color",
summary: "Paints the extruded shadow trailing the Word being spoken." },
{ name: "active-long-shadow-opacity", required: false, fallback: "long-shadow-opacity",
@@ -134,6 +214,8 @@ export const captionFineMarkupSurfaces = [
summary: "Sets how strongly the active halo reads." },
{ name: "active-glow-blur", required: false, fallback: "glow-blur",
summary: "Spreads the active halo by this many pixels. Widening it is the usual way of trying to make the spoken Word stand out, and the usual way of losing it: the halo leaves the glyph, fills the gaps to its neighbours and blurs the very Word it was meant to pick out. The Word is already picked out by its own Paint — leave this near `glow-blur`." },
+ { name: "active-glow-spread", required: false, fallback: "glow-spread",
+ summary: "Expands the active glyph alpha before its halo is blurred." },
{ name: "background", required: true,
summary: "Paints the Cue box behind the Words, as an RGB or RGBA hex color." },
{ name: "border-color", required: false, fallback: "#00000000",
@@ -144,6 +226,18 @@ export const captionFineMarkupSurfaces = [
summary: "Insets the Words from the Cue box edge, as one pixel number or a vertical and horizontal pair." },
{ name: "radius", required: true,
summary: "Rounds the Cue box corners by this many pixels." },
+ { name: "cue-shadow-color", required: false, fallback: "#000000",
+ summary: "Paints the shadow cast by the Cue box rather than by its glyphs." },
+ { name: "cue-shadow-opacity", required: false, fallback: "0",
+ summary: "Sets the Cue box shadow opacity." },
+ { name: "cue-shadow-x", required: false, fallback: "0",
+ summary: "Offsets the Cue box shadow horizontally in pixels." },
+ { name: "cue-shadow-y", required: false, fallback: "0",
+ summary: "Offsets the Cue box shadow vertically in pixels." },
+ { name: "cue-shadow-blur", required: false, fallback: "0",
+ summary: "Blurs the Cue box shadow in pixels." },
+ { name: "cue-shadow-spread", required: false, fallback: "0",
+ summary: "Expands or contracts the Cue box shadow in pixels." },
{ name: "underline", required: false, values: ["off", "always"], fallback: "off",
summary: "Decides whether every Word carries a rule beneath it." },
{ name: "underline-color", required: false, fallback: "fill",
@@ -219,7 +313,13 @@ export const captionFineMarkupSurfaces = [
summary: "Sets how many Frames one cycle of the looping motion takes." },
{ name: "loop-intensity", required: false, fallback: "1",
summary: "Scales how far the looping motion carries." },
- ] },
+ { name: "lead-frames", required: false, fallback: "0",
+ summary: "Makes the Cue visible this many Frames before its first semantic Word without moving any Word timing." },
+ { name: "tail-frames", required: false, fallback: "0",
+ summary: "Keeps the Cue visible this many Frames after its last semantic Word without extending any Word timing." },
+ { name: "handoff", required: false, values: ["cut", "overlap"], fallback: "cut",
+ summary: "Chooses whether adjacent Cue visibility envelopes meet without overlap or may coexist." },
+ ]) },
{ name: "font", kind: "reference", required: true,
accepts: [mediaTypes.fontArtifact, mediaTypes.fontStack],
summary: "Chooses the primary face, or a whole reusable stack that already carries its own fallbacks." },
@@ -284,17 +384,29 @@ export const captionFineManifest: ModuleManifest = {
narrativeDependency,
semanticTrackDependency,
],
- types: [],
+ types: [{ name: captionFineTypes.schedule.name }],
capabilities: [],
- producers: [{
- name: captionFineProducers.render.name,
- inputs: [
- { name: "caption", type: captionTypes.timedProjection },
- { name: "program", type: captionTypes.program },
- { name: "document", type: narrativeTypes.captionDocument },
- { name: "semantic", type: semanticTrackTypes.track },
- ],
- outputs: [{ name: "track", type: compositionTypes.visualTrack }],
- needs: [],
- }],
+ producers: [
+ {
+ name: captionFineProducers.schedule.name,
+ inputs: [
+ { name: "caption", type: captionTypes.timedProjection },
+ { name: "program", type: captionTypes.program },
+ { name: "document", type: narrativeTypes.captionDocument },
+ ],
+ outputs: [{ name: "schedule", type: captionFineTypes.schedule }],
+ needs: [],
+ },
+ {
+ name: captionFineProducers.render.name,
+ inputs: [
+ { name: "schedule", type: captionFineTypes.schedule },
+ { name: "program", type: captionTypes.program },
+ { name: "document", type: narrativeTypes.captionDocument },
+ { name: "semantic", type: semanticTrackTypes.track },
+ ],
+ outputs: [{ name: "track", type: compositionTypes.visualTrack }],
+ needs: [],
+ },
+ ],
};
diff --git a/packages/caption-fine/src/recipe.ts b/packages/caption-fine/src/recipe.ts
index e420965b..401586de 100644
--- a/packages/caption-fine/src/recipe.ts
+++ b/packages/caption-fine/src/recipe.ts
@@ -11,17 +11,19 @@ const paired = (...names: readonly string[]): readonly string[] =>
const colors = new Set([
...paired("fill", "glow-color", "gradient-from", "gradient-to", "long-shadow-color", "shadow-color", "stroke-color"),
- "background", "border-color", "underline-color",
+ "background", "border-color", "cue-shadow-color", "underline-color",
"active-box-background", "active-box-border-color", "active-underline-color",
]);
const unitFractions = new Set([
- "x", "y", "width",
+ "cue-shadow-opacity", "height", "x", "y", "width",
...paired("opacity", "glow-opacity", "long-shadow-opacity", "shadow-opacity"),
]);
const integers = new Set([
"stack-order",
+ "lead-frames", "tail-frames",
+ "max-lines", "max-words-per-line",
"active-box-transition-frames", "active-response-frames",
"atom-enter-frames", "atom-exit-frames", "cue-enter-frames", "cue-exit-frames",
"loop-period-frames",
@@ -29,20 +31,28 @@ 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",
"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", "gradient-angle", "long-shadow-angle", "long-shadow-distance",
- "shadow-blur", "shadow-x", "shadow-y", "stroke-width"),
+ ...paired("glow-blur", "glow-spread", "gradient-angle", "long-shadow-angle", "long-shadow-distance",
+ "shadow-blur", "shadow-spread", "shadow-x", "shadow-y", "stroke-width"),
]);
const strings = new Set(["padding", "active-box-padding"]);
const enums: Readonly<Record<string, readonly string[]>> = {
+ "handoff": ["cut", "overlap"],
"align": ["left", "center", "right"],
+ "block-align": ["start", "center", "end"],
"anchor-x": ["left", "center", "right"],
"anchor-y": ["top", "center", "bottom"],
"direction": ["ltr", "rtl"],
- "text-transform": ["none", "uppercase", "lowercase"],
+ "inline-size": ["hug", "fixed"],
+ "wrap": ["word", "grapheme"],
+ "overflow": ["visible", "clip"],
+ "kerning": ["auto", "normal", "none"],
+ "caps": ["normal", "small-caps", "all-small-caps"],
+ "text-transform": ["none", "uppercase", "lowercase", "capitalize"],
"atom-reveal": ["all", "on-start", "typewriter"],
"karaoke": ["off", "current", "trail"],
"karaoke-transition": ["step", "wipe"],
@@ -70,18 +80,20 @@ export const fineCaptionOptionalRecipeProperties = [
"active-box", "active-box-background", "active-box-border-color", "active-box-border-width",
"active-box-continuity", "active-box-enter", "active-box-exit", "active-box-padding", "active-box-radius",
"active-box-transition-frames", "active-fill", "active-glow-blur", "active-glow-color", "active-glow-opacity",
+ "active-glow-spread",
"active-gradient-angle", "active-gradient-from", "active-gradient-to", "active-long-shadow-angle",
"active-long-shadow-color", "active-long-shadow-distance", "active-long-shadow-opacity", "active-opacity",
"active-response", "active-response-frames", "active-scale", "active-shadow-blur", "active-shadow-color", "active-shadow-opacity",
- "active-shadow-x", "active-shadow-y", "active-stroke-color", "active-stroke-width", "active-underline",
+ "active-shadow-spread", "active-shadow-x", "active-shadow-y", "active-stroke-color", "active-stroke-width", "active-underline",
"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", "border-color", "border-width", "cue-enter",
+ "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",
- "glow-opacity", "gradient-angle", "gradient-from", "gradient-to", "karaoke", "karaoke-transition",
- "letter-spacing", "long-shadow-angle", "long-shadow-color", "long-shadow-distance", "long-shadow-opacity",
- "loop", "loop-intensity", "loop-period-frames", "loop-target", "opacity", "shadow-blur", "shadow-color",
- "shadow-opacity", "shadow-x", "shadow-y", "slide-distance", "stroke-color", "stroke-width", "text-transform",
- "underline", "underline-color", "underline-offset", "underline-thickness", "word-gap",
+ "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", "overflow", "shadow-blur", "shadow-color",
+ "shadow-opacity", "shadow-spread", "shadow-x", "shadow-y", "slide-distance", "stroke-color", "stroke-width", "text-transform",
+ "tail-frames", "underline", "underline-color", "underline-offset", "underline-thickness", "word-gap", "wrap",
] as const;
function schemaFor(name: string): ValueSchema {
diff --git a/packages/caption-fine/src/render.ts b/packages/caption-fine/src/render.ts
index 96a4a7ac..61267645 100644
--- a/packages/caption-fine/src/render.ts
+++ b/packages/caption-fine/src/render.ts
@@ -1,5 +1,5 @@
-import { applyCaptionMute, assertCaptionProgramForDocument, assertTimedCaptionProjection } from "@hypit/caption";
-import type { CaptionProgram, TimedCaptionProjection } from "@hypit/caption";
+import { assertCaptionProgramForDocument } from "@hypit/caption";
+import type { CaptionProgram } from "@hypit/caption";
import { assertVisualTrackIdentity, sealVisualTrack } from "@hypit/composition";
import type {
VisualAnimation,
@@ -17,11 +17,13 @@ import { assertProgramSpaceIdentity, programSpaceFrameCount } from "@hypit/progr
import type { ProgramSpace } from "@hypit/program-space";
import { assertFineCaptionParameters, FINE_CAPTION_FAMILY } from "./style.js";
+import { assertFineCaptionSchedule } from "./schedule.js";
import type {
FineCaptionActiveUnderline,
FineCaptionGlyphPaint,
FineCaptionOneShotMotion,
FineCaptionParameters,
+ FineCaptionSchedule,
FineCaptionUnderline,
} from "./types.js";
@@ -44,6 +46,8 @@ function alphaColor(hex: string, opacity: number): string {
function typographyStyle(parameters: FineCaptionParameters): VisualStyleDeclaration[] {
return [
{ name: "font-size", value: `${compactNumber(parameters.typography.fontSizePx)}px` },
+ { name: "font-kerning", value: parameters.typography.kerning },
+ { name: "font-variant-caps", value: parameters.typography.variantCaps },
{ name: "letter-spacing", value: `${compactNumber(parameters.layout.letterSpacingPx)}px` },
{ name: "line-height", value: parameters.layout.lineHeight },
{ name: "text-transform", value: parameters.typography.textTransform },
@@ -110,7 +114,7 @@ function softPaints(paint: FineCaptionGlyphPaint): VisualTextPaintLayer[] {
kind: "glow",
paint: { kind: "solid", color: alphaColor(paint.glow.color, paint.glow.opacity) },
blurPx: deviationFromBlurRadius(paint.glow.blurPx),
- spreadPx: 0,
+ spreadPx: paint.glow.spreadPx,
});
}
if (paint.shadow.opacity > 0) {
@@ -120,14 +124,14 @@ function softPaints(paint: FineCaptionGlyphPaint): VisualTextPaintLayer[] {
offsetX: paint.shadow.offsetXPx,
offsetY: paint.shadow.offsetYPx,
blurPx: deviationFromBlurRadius(paint.shadow.blurPx),
- spreadPx: 0,
+ spreadPx: paint.shadow.spreadPx,
});
}
return layers;
}
function glyphPaints(paint: FineCaptionGlyphPaint): VisualTextPaintLayer[] | undefined {
- if (paint.stroke.widthPx === 0) return undefined;
+ if (paint.stroke.widthPx === 0 && paint.shadow.spreadPx === 0 && paint.glow.spreadPx === 0) return undefined;
const fill: VisualColorPaint = paint.gradient === undefined
? { kind: "solid", color: paint.fill }
: {
@@ -142,7 +146,12 @@ function glyphPaints(paint: FineCaptionGlyphPaint): VisualTextPaintLayer[] | und
// outside the letter, and the body sits over its own outline.
return [
...softPaints(paint),
- { kind: "stroke", placement: "outside", widthPx: paint.stroke.widthPx, paint: { kind: "solid", color: paint.stroke.color } },
+ ...(paint.stroke.widthPx === 0 ? [] : [{
+ kind: "stroke" as const,
+ placement: "outside" as const,
+ widthPx: paint.stroke.widthPx,
+ paint: { kind: "solid" as const, color: paint.stroke.color },
+ }]),
{ kind: "fill", paint: fill },
];
}
@@ -189,8 +198,9 @@ function glyphStyle(
return [
...(painted ? [] : [{ name: "color", value: paint.fill }] as const),
...typographyStyle(parameters),
+ { name: "min-width", value: "0" },
{ name: "opacity", value: paint.opacity },
- { name: "white-space", value: "nowrap" },
+ { name: "white-space", value: "normal" },
...(painted || paint.gradient === undefined ? [] : [
{ name: "background-image", value: `linear-gradient(${compactNumber(paint.gradient.angleDeg)}deg,${paint.gradient.from},${paint.gradient.to})` },
{ name: "background-clip", value: "text" },
@@ -211,7 +221,8 @@ function transparentGlyphStyle(
return [
{ name: "color", value: "#00000000" },
...typographyStyle(parameters),
- { name: "white-space", value: "nowrap" },
+ { name: "min-width", value: "0" },
+ { name: "white-space", value: "normal" },
...(underline === undefined ? [] : underlineStyle(underline)),
];
}
@@ -549,8 +560,8 @@ function cueElements(
atomFrames: ReadonlyMap<string, { readonly start: number; readonly end: number }>,
parameters: FineCaptionParameters,
wordText: ReadonlyMap<string, string>,
- wordParameters: ReadonlyMap<string, FineCaptionParameters>,
durationFrames: number,
+ styleId: string,
): VisualElement[] {
type UnorderedVisualElement = Omit<VisualBoxElement, "order"> | Omit<VisualTextElement, "order">;
const elements: VisualElement[] = [];
@@ -567,13 +578,17 @@ function cueElements(
id: "placement",
kind: "box",
style: [
- { name: "align-items", value: "center" },
+ { name: "align-items", value: parameters.layout.blockAlign === "start" ? "flex-start"
+ : parameters.layout.blockAlign === "end" ? "flex-end" : "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)}%` },
+ ...(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)}%` },
],
@@ -598,6 +613,11 @@ function cueElements(
kind: "box",
style: [
{ name: "background", value: parameters.cueBox.background },
+ ...(parameters.cueBox.shadow.opacity === 0 ? [] : [{
+ name: "box-shadow",
+ value: `${compactNumber(parameters.cueBox.shadow.offsetXPx)}px ${compactNumber(parameters.cueBox.shadow.offsetYPx)}px ${compactNumber(parameters.cueBox.shadow.blurPx)}px ${compactNumber(parameters.cueBox.shadow.spreadPx)}px ${alphaColor(parameters.cueBox.shadow.color, parameters.cueBox.shadow.opacity)}`,
+ }] as const),
+ { name: "box-sizing", value: "border-box" },
{ name: "border-color", value: parameters.cueBox.borderColor },
{ name: "border-radius", value: `${compactNumber(parameters.cueBox.radiusPx)}px` },
{ name: "border-style", value: "solid" },
@@ -608,10 +628,18 @@ function cueElements(
{ name: "flex-wrap", value: "wrap" },
{ name: "justify-content", value: parameters.layout.textAlign === "left" ? "flex-start"
: parameters.layout.textAlign === "right" ? "flex-end" : "center" },
+ { name: "max-width", value: "100%" },
+ ...(parameters.layout.maxLines === undefined ? [] : [{
+ name: "max-height",
+ value: `${compactNumber(parameters.typography.fontSizePx * parameters.layout.lineHeight * parameters.layout.maxLines + parameters.cueBox.paddingYPx * 2)}px`,
+ }] as const),
+ { name: "overflow", value: parameters.layout.overflow === "clip" ? "hidden" : "visible" },
{ name: "padding", value: `${compactNumber(parameters.cueBox.paddingYPx)}px ${compactNumber(parameters.cueBox.paddingXPx)}px` },
{ name: "position", value: "relative" },
{ name: "text-align", value: parameters.layout.textAlign },
+ { name: "width", value: parameters.layout.inlineSize === "fixed" ? "100%" : "max-content" },
],
+ attributes: [{ name: "data-caption-style", value: styleId }],
});
if (parameters.activeBox.mode === "trail" && parameters.activeBox.continuity === "joined") {
@@ -666,6 +694,7 @@ function cueElements(
}
}
+ let wordsOnLine = 0;
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}`);
@@ -675,6 +704,17 @@ function cueElements(
const typewriterId = `${atomId}-typewriter`;
const loopId = `${atomId}-loop`;
const responseId = `${atomId}-response`;
+ if (parameters.layout.maxWordsPerLine !== undefined
+ && wordsOnLine > 0
+ && wordsOnLine + atom.wordIds.length > parameters.layout.maxWordsPerLine) {
+ push({
+ id: `line-break-${atomIndex}`,
+ parent: "cue",
+ kind: "box",
+ style: [{ name: "flex-basis", value: "100%" }, { name: "height", value: "0" }],
+ });
+ wordsOnLine = 0;
+ }
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"
@@ -686,6 +726,7 @@ function cueElements(
kind: "box",
style: [
{ name: "display", value: "inline-flex" },
+ { name: "min-width", value: "0" },
{ name: "transform-origin", value: "center center" },
],
...(entryAnimation === undefined ? {} : { animation: entryAnimation }),
@@ -696,6 +737,7 @@ function cueElements(
kind: "box",
style: [
{ name: "display", value: "inline-flex" },
+ { name: "min-width", value: "0" },
{ name: "transform-origin", value: parameters.layout.direction === "rtl" ? "right center" : "left center" },
],
...(writerAnimation === undefined ? {} : { animation: writerAnimation }),
@@ -704,14 +746,22 @@ function cueElements(
id: loopId,
parent: typewriterId,
kind: "box",
- style: [{ name: "display", value: "inline-flex" }, { name: "transform-origin", value: "center center" }],
+ style: [
+ { name: "display", value: "inline-flex" },
+ { name: "min-width", value: "0" },
+ { name: "transform-origin", value: "center center" },
+ ],
...(atomLoop === undefined ? {} : { animation: atomLoop }),
});
push({
id: responseId,
parent: loopId,
kind: "box",
- style: [{ name: "display", value: "inline-flex" }, { name: "transform-origin", value: "center center" }],
+ style: [
+ { name: "display", value: "inline-flex" },
+ { name: "min-width", value: "0" },
+ { name: "transform-origin", value: "center center" },
+ ],
...(responseAnimation === undefined ? {} : { animation: responseAnimation }),
});
push({
@@ -721,8 +771,11 @@ function cueElements(
style: [
{ name: "column-gap", value: `${compactNumber(parameters.layout.wordGapPx)}px` },
{ name: "display", value: "inline-flex" },
+ { name: "min-width", value: "0" },
+ { name: "overflow-wrap", value: "anywhere" },
{ name: "position", value: "relative" },
- { name: "white-space", value: "nowrap" },
+ { name: "white-space", value: "normal" },
+ { name: "word-break", value: parameters.layout.wrap === "grapheme" ? "break-all" : "normal" },
],
attributes: [{ name: "data-caption-atom", value: atom.id }],
});
@@ -753,14 +806,13 @@ function cueElements(
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}`);
- const wordStyle = wordParameters.get(wordId) ?? parameters;
push({
id: `${atomId}-base-${wordIndex + 1}`,
parent: atomId,
kind: "text",
text,
- style: glyphStyle(wordStyle, wordStyle.basePaint, wordStyle.underline),
- ...glyphPaintFields(wordStyle.basePaint),
+ style: glyphStyle(parameters, parameters.basePaint, parameters.underline),
+ ...glyphPaintFields(parameters.basePaint),
fonts,
attributes: [{ name: "data-caption-word", value: wordId }],
});
@@ -809,31 +861,26 @@ function cueElements(
if (parameters.activeUnderline.mode !== "off") {
addActivatedTextLayer("underline", parameters.activeUnderline.mode, "underline");
}
+ wordsOnLine += atom.wordIds.length;
}
return elements;
}
export function renderFineCaption(
- projection: TimedCaptionProjection,
+ schedule: FineCaptionSchedule,
program: CaptionProgram,
document: CaptionDocument,
space: ProgramSpace,
): VisualTrack {
- assertTimedCaptionProjection(projection);
+ assertFineCaptionSchedule(schedule);
assertCaptionProgramForDocument(program, document);
- if (projection.documentId !== document.id) throw new Error("Fine Caption received another CaptionDocument");
- const visibleProjection = applyCaptionMute(projection, program, document);
+ if (schedule.documentId !== document.id) throw new Error("Fine Caption received another CaptionDocument");
+ if (program.wordRuns.length !== 0) {
+ throw new Error("Fine Caption accepts one uniform token rule and cannot consume word-specific Style runs");
+ }
assertProgramSpaceIdentity(space);
const styles = new Map(program.styles.map((style) => [style.id, style]));
const wordText = new Map(document.words.map((word) => [word.id, word.text]));
- const wordParameters = new Map<string, FineCaptionParameters>();
- for (const run of program.wordRuns) {
- const style = styles.get(run.styleId);
- if (style === undefined) throw new Error(`Fine Caption word run ${run.id} references unknown Style ${run.styleId}`);
- const parameters = style.rendering.parameters as unknown as FineCaptionParameters;
- assertFineCaptionParameters(parameters);
- for (const wordId of run.wordIds) wordParameters.set(wordId, parameters);
- }
const atomById = new Map(document.units.map((atom) => [atom.id, atom]));
for (const style of styles.values()) {
if (style.rendering.family !== FINE_CAPTION_FAMILY) {
@@ -842,15 +889,15 @@ export function renderFineCaption(
assertFineCaptionParameters(style.rendering.parameters as unknown as FineCaptionParameters);
}
const totalFrames = programSpaceFrameCount(space);
- const presents = visibleProjection.cues.flatMap((cue) => {
+ 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`);
const resolvedAtoms = atoms.map((atom) => atom!);
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;
- const startFrame = Math.max(0, cue.startFrame);
- const measuredEnd = Math.min(totalFrames, cue.endFrameExclusive);
+ const startFrame = Math.max(0, cue.visibleStartFrame);
+ const measuredEnd = Math.min(totalFrames, cue.visibleEndFrameExclusive);
const endFrameExclusive = Math.min(totalFrames, Math.max(startFrame + 1, measuredEnd));
if (startFrame >= totalFrames || endFrameExclusive <= startFrame) return [];
const durationFrames = endFrameExclusive - startFrame;
@@ -862,7 +909,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, wordParameters, durationFrames),
+ elements: cueElements(resolvedAtoms, atomFrames, parameters, wordText, durationFrames, cue.styleId),
}];
});
const track = sealVisualTrack({
diff --git a/packages/caption-fine/src/schedule.ts b/packages/caption-fine/src/schedule.ts
new file mode 100644
index 00000000..900b0c89
--- /dev/null
+++ b/packages/caption-fine/src/schedule.ts
@@ -0,0 +1,116 @@
+import { applyCaptionMute, assertCaptionProgramForDocument, assertTimedCaptionProjection } from "@hypit/caption";
+import type { CaptionProgram, TimedCaptionProjection } from "@hypit/caption";
+import type { CaptionDocument } from "@hypit/narrative";
+
+import { assertFineCaptionParameters, FINE_CAPTION_FAMILY } from "./style.js";
+import type { FineCaptionParameters, FineCaptionSchedule, FineCaptionScheduledCue } from "./types.js";
+
+function assertIntegerFrame(value: number, label: string): void {
+ if (!Number.isSafeInteger(value) || value < 0) throw new Error(`${label} must be a non-negative integer Frame`);
+}
+
+/**
+ * Resolve visible Cue envelopes before the renderer runs.
+ *
+ * Semantic unit timing stays untouched. `leadFrames` and `tailFrames` only
+ * widen the visible envelope, and `cut` prevents adjacent Cues from competing
+ * for the same handoff interval without shortening either Cue's spoken time.
+ */
+export function scheduleFineCaption(
+ projection: TimedCaptionProjection,
+ program: CaptionProgram,
+ document: CaptionDocument,
+): FineCaptionSchedule {
+ assertTimedCaptionProjection(projection);
+ assertCaptionProgramForDocument(program, document);
+ if (projection.documentId !== document.id) throw new Error("Fine Caption Schedule received another CaptionDocument");
+ if (program.wordRuns.length !== 0) {
+ throw new Error("Fine Caption accepts one uniform token rule and cannot consume word-specific Style runs");
+ }
+ const visibleProjection = applyCaptionMute(projection, program, document);
+
+ const parameters = new Map<string, FineCaptionParameters>();
+ for (const style of program.styles) {
+ if (style.rendering.family !== FINE_CAPTION_FAMILY) {
+ throw new Error(`Fine Caption cannot schedule Style family ${style.rendering.family}`);
+ }
+ const value = style.rendering.parameters as unknown as FineCaptionParameters;
+ assertFineCaptionParameters(value);
+ parameters.set(style.id, value);
+ }
+
+ const desired = visibleProjection.cues.map((cue): FineCaptionScheduledCue => {
+ const style = parameters.get(cue.styleId);
+ if (style === undefined) throw new Error(`Fine Caption Cue ${cue.id} references unknown Style ${cue.styleId}`);
+ const visibleStartFrame = Math.max(0, cue.startFrame - style.timing.leadFrames);
+ const visibleEndFrameExclusive = cue.endFrameExclusive + style.timing.tailFrames;
+ return {
+ id: cue.id,
+ styleId: cue.styleId,
+ semanticStartFrame: cue.startFrame,
+ semanticEndFrameExclusive: cue.endFrameExclusive,
+ visibleStartFrame,
+ visibleEndFrameExclusive,
+ units: cue.units,
+ };
+ });
+
+ const cues: FineCaptionScheduledCue[] = [];
+ for (const wanted of desired) {
+ let cue = wanted;
+ const previous = cues.at(-1);
+ if (previous !== undefined) {
+ const previousStyle = parameters.get(previous.styleId)!;
+ const currentStyle = parameters.get(cue.styleId)!;
+ if (previousStyle.timing.handoff === "cut" || currentStyle.timing.handoff === "cut") {
+ const previousEnd = Math.max(
+ previous.semanticEndFrameExclusive,
+ Math.min(previous.visibleEndFrameExclusive, cue.semanticStartFrame),
+ );
+ cues[cues.length - 1] = { ...previous, visibleEndFrameExclusive: previousEnd };
+ cue = { ...cue, visibleStartFrame: Math.min(cue.semanticStartFrame, Math.max(cue.visibleStartFrame, previousEnd)) };
+ }
+ }
+ cues.push(cue);
+ }
+
+ const ids = new Set<string>();
+ for (const cue of cues) {
+ if (ids.has(cue.id)) throw new Error(`Fine Caption Schedule repeats Cue ${cue.id}`);
+ ids.add(cue.id);
+ assertIntegerFrame(cue.semanticStartFrame, `Fine Caption Cue ${cue.id} semantic start`);
+ assertIntegerFrame(cue.semanticEndFrameExclusive, `Fine Caption Cue ${cue.id} semantic end`);
+ assertIntegerFrame(cue.visibleStartFrame, `Fine Caption Cue ${cue.id} visible start`);
+ assertIntegerFrame(cue.visibleEndFrameExclusive, `Fine Caption Cue ${cue.id} visible end`);
+ if (cue.semanticEndFrameExclusive <= cue.semanticStartFrame
+ || cue.visibleStartFrame > cue.semanticStartFrame
+ || cue.visibleEndFrameExclusive < cue.semanticEndFrameExclusive
+ || cue.visibleEndFrameExclusive <= cue.visibleStartFrame) {
+ throw new Error(`Fine Caption Cue ${cue.id} has an invalid visible envelope`);
+ }
+ }
+ return { documentId: document.id, cues };
+}
+
+export function assertFineCaptionSchedule(value: FineCaptionSchedule): void {
+ if (!value.documentId) throw new Error("Fine Caption Schedule document identity is empty");
+ const ids = new Set<string>();
+ for (const cue of value.cues) {
+ if (!cue.id || !cue.styleId || ids.has(cue.id) || cue.units.length === 0) {
+ throw new Error("Fine Caption Schedule contains an invalid Cue");
+ }
+ ids.add(cue.id);
+ for (const [label, frame] of [
+ ["semantic start", cue.semanticStartFrame],
+ ["semantic end", cue.semanticEndFrameExclusive],
+ ["visible start", cue.visibleStartFrame],
+ ["visible end", cue.visibleEndFrameExclusive],
+ ] as const) assertIntegerFrame(frame, `Fine Caption Cue ${cue.id} ${label}`);
+ if (cue.semanticEndFrameExclusive <= cue.semanticStartFrame
+ || cue.visibleStartFrame > cue.semanticStartFrame
+ || cue.visibleEndFrameExclusive < cue.semanticEndFrameExclusive
+ || cue.visibleEndFrameExclusive <= cue.visibleStartFrame) {
+ throw new Error(`Fine Caption Cue ${cue.id} has an invalid visible envelope`);
+ }
+ }
+}
diff --git a/packages/caption-fine/src/style.ts b/packages/caption-fine/src/style.ts
index 6d52e992..754d6377 100644
--- a/packages/caption-fine/src/style.ts
+++ b/packages/caption-fine/src/style.ts
@@ -115,6 +115,7 @@ function glyphPaint(recipe: SvsRecipe, prefix: "" | "active-", base?: FineCaptio
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),
+ spreadPx: number(recipe, `${prefix}shadow-spread`, baseShadow?.spreadPx ?? 0),
},
longShadow: {
color: color(recipe, `${prefix}long-shadow-color`, baseLongShadow?.color ?? "#000000"),
@@ -126,6 +127,7 @@ function glyphPaint(recipe: SvsRecipe, prefix: "" | "active-", base?: FineCaptio
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),
+ spreadPx: number(recipe, `${prefix}glow-spread`, baseGlow?.spreadPx ?? 0),
},
};
}
@@ -151,10 +153,12 @@ function assertPaint(value: FineCaptionGlyphPaint, label: string): void {
for (const [name, metric] of [
["stroke width", value.stroke.widthPx], ["shadow blur", value.shadow.blurPx],
["long shadow distance", value.longShadow.distancePx], ["glow blur", value.glow.blurPx],
+ ["glow spread", value.glow.spreadPx],
] as const) {
if (!Number.isFinite(metric) || metric < 0) throw new Error(`${label} ${name} is invalid`);
}
- if (!Number.isFinite(value.shadow.offsetXPx) || !Number.isFinite(value.shadow.offsetYPx)) {
+ if (!Number.isFinite(value.shadow.offsetXPx) || !Number.isFinite(value.shadow.offsetYPx)
+ || !Number.isFinite(value.shadow.spreadPx)) {
throw new Error(`${label} shadow offset is invalid`);
}
if (!Number.isFinite(value.longShadow.angleDeg)) throw new Error(`${label} long shadow angle is invalid`);
@@ -184,19 +188,29 @@ export function fineCaptionParameters(
x: number(recipe, "x"),
y: number(recipe, "y"),
width: number(recipe, "width"),
+ ...(Object.hasOwn(recipe.properties, "height") ? { height: number(recipe, "height") } : {}),
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),
+ blockAlign: choice(recipe, "block-align", ["start", "center", "end"] as const, "center"),
direction: choice(recipe, "direction", ["ltr", "rtl"] as const, "ltr"),
+ inlineSize: choice(recipe, "inline-size", ["hug", "fixed"] as const, "hug"),
+ wrap: choice(recipe, "wrap", ["word", "grapheme"] as const, "word"),
+ overflow: choice(recipe, "overflow", ["visible", "clip"] as const, "visible"),
+ ...(Object.hasOwn(recipe.properties, "max-lines") ? { maxLines: integer(recipe, "max-lines") } : {}),
+ ...(Object.hasOwn(recipe.properties, "max-words-per-line")
+ ? { maxWordsPerLine: integer(recipe, "max-words-per-line") } : {}),
lineHeight: number(recipe, "line-height"),
letterSpacingPx: number(recipe, "letter-spacing", 0),
wordGapPx: number(recipe, "word-gap", fontSizePx * 0.25),
},
typography: {
fontSizePx,
- textTransform: choice(recipe, "text-transform", ["none", "uppercase", "lowercase"] as const, "none"),
+ kerning: choice(recipe, "kerning", ["auto", "normal", "none"] as const, "auto"),
+ variantCaps: choice(recipe, "caps", ["normal", "small-caps", "all-small-caps"] as const, "normal"),
+ textTransform: choice(recipe, "text-transform", ["none", "uppercase", "lowercase", "capitalize"] as const, "none"),
exactFonts: [...exactFonts],
},
basePaint,
@@ -220,6 +234,14 @@ export function fineCaptionParameters(
paddingXPx: pad.x,
paddingYPx: pad.y,
radiusPx: number(recipe, "radius"),
+ shadow: {
+ color: color(recipe, "cue-shadow-color", "#000000"),
+ opacity: number(recipe, "cue-shadow-opacity", 0),
+ offsetXPx: number(recipe, "cue-shadow-x", 0),
+ offsetYPx: number(recipe, "cue-shadow-y", 0),
+ blurPx: number(recipe, "cue-shadow-blur", 0),
+ spreadPx: number(recipe, "cue-shadow-spread", 0),
+ },
},
karaoke: {
mode: choice(recipe, "karaoke", ["off", "current", "trail"] as const, "off"),
@@ -257,6 +279,11 @@ export function fineCaptionParameters(
loopPeriodFrames: integer(recipe, "loop-period-frames", 12),
loopIntensity: number(recipe, "loop-intensity", 1),
},
+ timing: {
+ leadFrames: integer(recipe, "lead-frames", 0),
+ tailFrames: integer(recipe, "tail-frames", 0),
+ handoff: choice(recipe, "handoff", ["cut", "overlap"] as const, "cut"),
+ },
};
assertFineCaptionParameters(parameters);
return parameters;
@@ -276,15 +303,21 @@ export function assertFineCaptionParameters(value: FineCaptionParameters): void
value.motion.cueEnterFrames, value.motion.cueExitFrames, value.motion.atomEnterFrames, value.motion.atomExitFrames,
value.motion.activeResponseFrames,
value.motion.slideDistancePx, value.motion.loopPeriodFrames, value.motion.loopIntensity,
+ value.timing.leadFrames, value.timing.tailFrames,
+ value.cueBox.shadow.blurPx,
];
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.placement.height !== undefined && (!Number.isFinite(value.placement.height) || value.placement.height <= 0 || value.placement.height > 1))
|| value.typography.fontSizePx <= 0 || value.layout.lineHeight <= 0
|| !Number.isSafeInteger(value.motion.cueEnterFrames) || !Number.isSafeInteger(value.motion.cueExitFrames)
|| !Number.isSafeInteger(value.motion.atomEnterFrames) || !Number.isSafeInteger(value.motion.atomExitFrames)
|| !Number.isSafeInteger(value.motion.loopPeriodFrames)
|| !Number.isSafeInteger(value.motion.activeResponseFrames)
|| !Number.isSafeInteger(value.activeBox.transitionFrames) || value.motion.loopPeriodFrames <= 0
+ || !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.activeScale <= 0
|| !Number.isFinite(value.motion.activeScale) || !Number.isFinite(value.layout.letterSpacingPx)) {
throw new Error("Fine Caption parameters contain invalid numeric bounds");
@@ -297,8 +330,15 @@ export function assertFineCaptionParameters(value: FineCaptionParameters): void
if (faces.has(identity)) throw new Error("Fine Caption exact Font stack contains a duplicate face");
faces.add(identity);
}
+ if (value.layout.maxLines !== undefined && value.layout.overflow !== "clip") {
+ throw new Error("Fine Caption max-lines requires overflow: clip");
+ }
assertColor(value.cueBox.background, "Fine Caption background");
assertColor(value.cueBox.borderColor, "Fine Caption border color");
+ assertColor(value.cueBox.shadow.color, "Fine Caption Cue shadow color");
+ assertOpacity(value.cueBox.shadow.opacity, "Fine Caption Cue shadow opacity");
+ if (![value.cueBox.shadow.offsetXPx, value.cueBox.shadow.offsetYPx, value.cueBox.shadow.spreadPx]
+ .every(Number.isFinite)) throw new Error("Fine Caption Cue shadow contains an invalid metric");
assertColor(value.underline.color, "Fine Caption underline color");
assertColor(value.activeUnderline.color, "Fine Caption active underline color");
assertColor(value.activeBox.background, "Fine Caption active box background");
diff --git a/packages/caption-fine/src/types.ts b/packages/caption-fine/src/types.ts
index 38d017ad..2d4b87de 100644
--- a/packages/caption-fine/src/types.ts
+++ b/packages/caption-fine/src/types.ts
@@ -1,3 +1,4 @@
+import type { TimedCaptionUnit } from "@hypit/caption";
import type { FontArtifactRef } from "@hypit/media";
export type FineCaptionGlyphPaint = {
@@ -18,6 +19,7 @@ export type FineCaptionGlyphPaint = {
readonly offsetXPx: number;
readonly offsetYPx: number;
readonly blurPx: number;
+ readonly spreadPx: number;
};
readonly longShadow: {
readonly color: string;
@@ -29,6 +31,7 @@ export type FineCaptionGlyphPaint = {
readonly color: string;
readonly opacity: number;
readonly blurPx: number;
+ readonly spreadPx: number;
};
};
@@ -89,19 +92,28 @@ export type FineCaptionParameters = {
readonly x: number;
readonly y: number;
readonly width: number;
+ readonly height?: number;
readonly anchorX: "left" | "center" | "right";
readonly anchorY: "top" | "center" | "bottom";
};
readonly layout: {
readonly textAlign: "left" | "center" | "right";
+ readonly blockAlign: "start" | "center" | "end";
readonly direction: "ltr" | "rtl";
+ readonly inlineSize: "hug" | "fixed";
+ readonly wrap: "word" | "grapheme";
+ readonly overflow: "visible" | "clip";
+ readonly maxLines?: number;
+ readonly maxWordsPerLine?: number;
readonly lineHeight: number;
readonly letterSpacingPx: number;
readonly wordGapPx: number;
};
readonly typography: {
readonly fontSizePx: number;
- readonly textTransform: "none" | "uppercase" | "lowercase";
+ readonly kerning: "auto" | "normal" | "none";
+ readonly variantCaps: "normal" | "small-caps" | "all-small-caps";
+ readonly textTransform: "none" | "uppercase" | "lowercase" | "capitalize";
readonly exactFonts: readonly FontArtifactRef[];
};
readonly basePaint: FineCaptionGlyphPaint;
@@ -115,6 +127,14 @@ export type FineCaptionParameters = {
readonly paddingXPx: number;
readonly paddingYPx: number;
readonly radiusPx: number;
+ readonly shadow: {
+ readonly color: string;
+ readonly opacity: number;
+ readonly offsetXPx: number;
+ readonly offsetYPx: number;
+ readonly blurPx: number;
+ readonly spreadPx: number;
+ };
};
readonly karaoke: {
readonly mode: "off" | "current" | "trail";
@@ -140,4 +160,30 @@ export type FineCaptionParameters = {
readonly loopPeriodFrames: number;
readonly loopIntensity: number;
};
+ /**
+ * Public rules for projecting semantic Cue time into its visible envelope.
+ * The renderer never expands a Cue on its own; the package's schedule
+ * Producer resolves these rules before rendering.
+ */
+ readonly timing: {
+ readonly leadFrames: number;
+ readonly tailFrames: number;
+ readonly handoff: "cut" | "overlap";
+ };
+};
+
+export type FineCaptionScheduledCue = {
+ readonly id: string;
+ readonly styleId: string;
+ readonly semanticStartFrame: number;
+ readonly semanticEndFrameExclusive: number;
+ readonly visibleStartFrame: number;
+ readonly visibleEndFrameExclusive: number;
+ readonly units: readonly TimedCaptionUnit[];
+};
+
+/** Explicit projection consumed by the Fine renderer. */
+export type FineCaptionSchedule = {
+ readonly documentId: string;
+ readonly cues: readonly FineCaptionScheduledCue[];
};
diff --git a/packages/caption-fine/test/caption-fine.test.ts b/packages/caption-fine/test/caption-fine.test.ts
new file mode 100644
index 00000000..276b3eec
--- /dev/null
+++ b/packages/caption-fine/test/caption-fine.test.ts
@@ -0,0 +1,166 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+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 { SvsRecipe } from "@hypit/svs";
+
+import { fixtureDigest } from "../../../test/fixture-digest.js";
+import {
+ captionFineMarkupSurfaces,
+ fineCaptionParameters,
+ fineCaptionStyle,
+ renderFineCaption,
+ scheduleFineCaption,
+} from "../src/index.js";
+
+const font: FontArtifactRef = {
+ sources: [{ artifact: {
+ kind: "blob",
+ digest: fixtureDigest("caption-fine-font"),
+ size: 1_024,
+ mediaType: "font/woff2",
+ } }],
+ weight: 800,
+ style: "normal",
+};
+
+const recipe: SvsRecipe = {
+ path: "caption.base",
+ properties: {
+ "stack-order": 70,
+ x: 0.5,
+ y: 0.9,
+ width: 0.8,
+ height: 0.24,
+ "anchor-x": "center",
+ "anchor-y": "bottom",
+ align: "center",
+ "block-align": "end",
+ "inline-size": "fixed",
+ wrap: "word",
+ overflow: "clip",
+ "max-lines": 2,
+ "max-words-per-line": 1,
+ size: 56,
+ "line-height": 1.05,
+ fill: "#FFFFFF",
+ "shadow-color": "#000000",
+ "shadow-opacity": 0.7,
+ "shadow-blur": 8,
+ "shadow-spread": 1,
+ background: "#000000CC",
+ padding: "8 12",
+ radius: 10,
+ "cue-shadow-color": "#000000",
+ "cue-shadow-opacity": 0.4,
+ "cue-shadow-y": 4,
+ "cue-shadow-blur": 10,
+ "lead-frames": 4,
+ "tail-frames": 6,
+ handoff: "cut",
+ },
+};
+
+function fixture() {
+ const parsed = parseScript("caption-fine.svml", "<line>one two || three four</line>");
+ const document = captionDocument(parsed, "story.caption");
+ const style = fineCaptionStyle("plain", recipe, [font]);
+ const program: CaptionProgram = {
+ id: "captions",
+ documentId: document.id,
+ styles: [style],
+ runs: [{ id: "captions:run:1", styleId: style.id, unitIds: document.units.map((unit) => unit.id) }],
+ wordRuns: [],
+ mutedUnitIds: [],
+ };
+ const [first, second, third, fourth] = document.units;
+ assert.ok(first && second && third && fourth);
+ const projection: TimedCaptionProjection = {
+ documentId: document.id,
+ cues: [
+ {
+ id: "captions:cue:1", styleId: style.id, startFrame: 10, endFrameExclusive: 30,
+ units: [
+ { unitId: first.id, startFrame: 10, endFrameExclusive: 20 },
+ { unitId: second.id, startFrame: 20, endFrameExclusive: 30 },
+ ],
+ },
+ {
+ id: "captions:cue:2", styleId: style.id, startFrame: 36, endFrameExclusive: 56,
+ units: [
+ { unitId: third.id, startFrame: 36, endFrameExclusive: 46 },
+ { unitId: fourth.id, startFrame: 46, endFrameExclusive: 56 },
+ ],
+ },
+ ],
+ };
+ return { document, program, projection };
+}
+
+test("Fine Caption freezes complete Where, How and visible-envelope parameters", () => {
+ const parameters = fineCaptionParameters(recipe, [font]);
+ assert.deepEqual(parameters.placement, {
+ x: 0.5, y: 0.9, width: 0.8, height: 0.24, anchorX: "center", anchorY: "bottom",
+ });
+ assert.equal(parameters.layout.maxLines, 2);
+ assert.equal(parameters.layout.maxWordsPerLine, 1);
+ assert.equal(parameters.typography.exactFonts[0]?.weight, 800);
+ assert.equal(parameters.basePaint.shadow.spreadPx, 1);
+ assert.deepEqual(parameters.timing, { leadFrames: 4, tailFrames: 6, handoff: "cut" });
+
+ const vocabulary = captionFineMarkupSurfaces.find((surface) => surface.name === "style")!
+ .vocabulary.attributes.find((attribute) => attribute.name === "recipe")!.recipe!;
+ const declared = (name: string) => vocabulary.find((property) => property.name === name);
+ assert.equal(declared("x")?.group, "where");
+ assert.equal(declared("cue-shadow-blur")?.group, "how");
+ assert.equal(declared("active-box-background")?.group, "how");
+ assert.equal(declared("active-box-enter")?.group, "when");
+ assert.equal(declared("cue-enter")?.group, "when");
+});
+
+test("Fine Caption schedules visibility outside semantic Word timing and cuts only the handoff", () => {
+ const { document, program, projection } = fixture();
+ const schedule = scheduleFineCaption(projection, program, document);
+ assert.deepEqual(schedule.cues.map((cue) => ({
+ semantic: [cue.semanticStartFrame, cue.semanticEndFrameExclusive],
+ visible: [cue.visibleStartFrame, cue.visibleEndFrameExclusive],
+ })), [
+ { semantic: [10, 30], visible: [6, 36] },
+ { semantic: [36, 56], visible: [36, 62] },
+ ]);
+
+ const track = renderFineCaption(schedule, program, document,
+ sealProgramSpace({ durationSec: 3, frameRate: { numerator: 30, denominator: 1 } }));
+ assert.deepEqual(track.presents.map((present) => present.span), [
+ { startFrame: 6, endFrameExclusive: 36 },
+ { startFrame: 36, endFrameExclusive: 62 },
+ ]);
+ assert.ok(track.presents[0]?.elements.some((element) => element.id === "line-break-1"));
+ const atom = track.presents[0]?.elements.find((element) => element.id === "atom-1");
+ assert.equal(atom?.style.find((declaration) => declaration.name === "white-space")?.value, "normal");
+ assert.equal(atom?.style.find((declaration) => declaration.name === "overflow-wrap")?.value, "anywhere");
+});
+
+test("Fine Caption applies authored mute before it schedules the visible envelope", () => {
+ const { document, program, projection } = fixture();
+ const muted: CaptionProgram = { ...program, mutedUnitIds: [projection.cues[0]!.units[0]!.unitId] };
+ const schedule = scheduleFineCaption(projection, muted, document);
+ assert.deepEqual(schedule.cues[0]?.units, [projection.cues[0]!.units[1]]);
+ assert.equal(schedule.cues[0]?.semanticStartFrame, projection.cues[0]!.units[1]!.startFrame);
+});
+
+test("Fine Caption rejects token-specific Style runs instead of disguising a structural caption", () => {
+ const { document, program, projection } = fixture();
+ const word = document.words[0]!;
+ const styled: CaptionProgram = {
+ ...program,
+ wordRuns: [{ id: "captions:word-run:1", styleId: "plain", wordIds: [word.id] }],
+ };
+ assert.throws(
+ () => scheduleFineCaption(projection, styled, document),
+ /one uniform token rule/u,
+ );
+});
diff --git a/packages/caption/README.md b/packages/caption/README.md
index 9208d292..2467be14 100644
--- a/packages/caption/README.md
+++ b/packages/caption/README.md
@@ -14,5 +14,6 @@ by a Role or a semantic Selection, then joins those units to a `SemanticTrack` f
There is no planner, model call or frame range in this authoring contract. A Selection is projected
to complete alignment units before timing; a Selection that cuts through an N:M unit is rejected.
-Script-native word attributes are resolved separately as local word styles and do not create another
-timing source.
+Script-native word attributes are resolved separately as local word Style runs and do not create
+another timing source. They are part of the common Caption contract for structural Caption families;
+`@hypit/caption-fine` deliberately rejects them because Fine requires one uniform token rule per Cue.
diff --git a/packages/markup/src/types.ts b/packages/markup/src/types.ts
index c447064a..4013ed3c 100644
--- a/packages/markup/src/types.ts
+++ b/packages/markup/src/types.ts
@@ -126,6 +126,10 @@ export type SurfaceRecipePropertyVocabulary = {
readonly name: string;
readonly required: boolean;
readonly summary: string;
+ /** Stable Inspector page owned by the component package. */
+ readonly group?: "where" | "how" | "when" | string;
+ /** Optional package-owned subsection inside the page. */
+ readonly section?: string;
readonly values?: readonly string[];
readonly fallback?: string;
};