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(script): support shared display and speech alignment units

kashorin395775536ddd
diff --git a/docs/quickstart/script.md b/docs/quickstart/script.md
index 4244546f..d9d0dbc6 100644
--- a/docs/quickstart/script.md
+++ b/docs/quickstart/script.md
@@ -104,10 +104,26 @@ An empty left side is legal:
```
This means "um" is spoken but never displayed as a caption. The two sides can have different word
-counts — this is an N:M Alignment Unit, not a 1:1 substitution. A Selection cannot split that unit.
+counts — this is an N:M Alignment Unit, not a 1:1 substitution. Its displayed unit stays complete
+even when a semantic marker locates a word within the spoken side.
-Markers belong to the spoken side of Dual Text. The display side is literal; an unescaped `@` there
-is rejected. Escape it as `\@` when the at-sign should be shown.
+When both sides are written, markers belong to the spoken side of Dual Text. The display side is
+literal; an unescaped `@` there is rejected. Escape it as `\@` when the at-sign should be shown.
+
+When both wordings are identical, omit the speech after the pipe:
+
+```svml
+<explanation><HOST>把<动效|><组件化|>。|| 以后就能<直接复用|>。</explanation>
+```
+
+`<组件化|>` means `<组件化|组件化>`: one complete Caption unit, with the same three individually
+timed spoken characters. Caption Styles can highlight the group together. Ordinary text remains
+valid without grouping, and `||` still chooses the Cue handoff. This works for phrases and names
+in other languages too, such as `<Git Hub|>`.
+
+Here the left side also supplies speech, so markers can be written and moved there:
+`<组@beat!件化|>`. Markers and display attributes never become spoken text. An explicit spoken side
+still owns its own markers. Both sides empty is invalid.
`||` is the **Caption Cue Break** syntax. It records a boundary between complete Alignment Units;
it cannot appear inside Dual Text or split an N:M unit. Cue timing is still obtained later by
diff --git a/docs/zh/quickstart/script.md b/docs/zh/quickstart/script.md
index f700b349..fda47df6 100644
--- a/docs/zh/quickstart/script.md
+++ b/docs/zh/quickstart/script.md
@@ -97,11 +97,25 @@ dialogue `Text` 包含 Role Cue 前缀,speech `Text` 和 CaptionDocument 会
```
这意味着 "um" 会被说出但永远不会显示为字幕。两侧可以有不同的单词数量——这是一种 N:M
-对齐单元,而非 1:1 替换;Selection 不能切开这个单元。
+对齐单元,而非 1:1 替换;即使语义标记定位到口播内部的一个词,显示单元仍然保持完整。
-标记只能出现在 Dual Text 的 spoken side。display side 是字面文本,未转义的 `@` 会报错;
+两侧都明确书写时,标记只能出现在 Dual Text 的 spoken side。display side 是字面文本,未转义的 `@` 会报错;
如果确实要显示 at-sign,请写成 `\@`。
+两边文案相同时,可以省略竖线后面的口播:
+
+```svml
+<explanation><HOST>把<动效|><组件化|>。|| 以后就能<直接复用|>。</explanation>
+```
+
+`<组件化|>` 等价于 `<组件化|组件化>`:字幕是一个完整单元,口播中的三个字仍各自保留时间。
+字幕样式可以让这组文字一起高亮;普通文本仍然可以直接书写,不必逐词包裹。`||` 继续决定
+Cue 的切换。这同样适用于其他语言的短语或名字,例如 `<Git Hub|>`。
+
+这时左侧同时提供口播,因此标记也可以放在左侧,Studio 会回写到实际文字上:
+`<组@beat!件化|>`。标记和显示属性不会成为口播内容。若明确写了右侧口播,标记仍然属于
+右侧。两侧都没有口播文字时无效。
+
`||` 是 **Caption Cue Break** 语法,只能位于完整对齐单元之间,不能写进 Dual Text 或切开
N:M 单元。字幕稍后才把 CaptionDocument 与 Timeline 汇合得到帧时间。
diff --git a/packages/caption-fine/README.md b/packages/caption-fine/README.md
index 57330b64..58feb8c0 100644
--- a/packages/caption-fine/README.md
+++ b/packages/caption-fine/README.md
@@ -87,6 +87,13 @@ individual Han characters as Display Words; punctuation stays with its display w
those units for timing and active Paint, while authored Cues remain complete reading phrases.
Dual Text retains its complete alignment unit even when it displays or speaks several words.
+`<组件化|>` authors the same unit as `<组件化|组件化>` without repeating the speech. Fine's `step`
+karaoke, active underline and active box treat that unit together using its first-to-last speech
+interval. Ordinary Chinese characters around it retain their own activation times. This is an
+explicit authored group, not a renderer-selected segmentation, and does not introduce a new Cue.
+The underlying character anchors remain available to other Timeline consumers. `wipe` and
+`typewriter` still animate inside the complete unit over its interval when deliberately selected.
+
`word-gap` applies between Latin words and at Chinese/Latin boundaries. Adjacent Han characters and
full-width punctuation carry no extra word gap. `letter-spacing` controls glyph tracking. Exact
font fallbacks supply the required glyphs; the layout does not select a font by language.
diff --git a/packages/caption-fine/test/caption-fine.test.ts b/packages/caption-fine/test/caption-fine.test.ts
index 75b3614b..640dce2b 100644
--- a/packages/caption-fine/test/caption-fine.test.ts
+++ b/packages/caption-fine/test/caption-fine.test.ts
@@ -328,6 +328,31 @@ function numericStyleAt(element: import("@hypit/composition").VisualElement, fra
: value(left) + (value(right) - value(left)) * (frame - left.atFrame) / (right.atFrame - left.atFrame);
}
+for (const mode of ["current", "trail"] as const) test(`shared-text groups use existing ${mode} whole-unit caption effects`, () => {
+ const make = (script: string) => {
+ const { document, program, projection } = fixture(script);
+ const style = fineCaptionStyle("plain", { ...recipe, properties: { ...recipe.properties,
+ karaoke: mode, "karaoke-transition": "step", "active-box": mode, "active-underline": mode,
+ } }, [font]);
+ const styled = { ...program, styles: [style] };
+ return renderFineCaption(scheduleFineCaption(projection, styled, document), styled, document,
+ sealTimeline({ items: [], id: "test-space", durationSec: 3, frameRate: { numerator: 30, denominator: 1 } }));
+ };
+ const track = make('<line><动效|><组件化|> || <直接|><复用|></line>');
+ assert.deepEqual(track, make('<line><动效|动效><组件化|组件化> || <直接|直接><复用|复用></line>'));
+ const present = track.presents[0]!;
+ for (const [index, [start, end]] of [[10, 20], [20, 30]].entries()) {
+ for (const suffix of ["active", "underline", "box"]) {
+ const element = present.elements.find(item => item.id === `atom-${index + 1}-${suffix}`)!;
+ assert.ok(element);
+ for (let frame = present.span.startFrame; frame < present.span.endFrameExclusive; frame++) {
+ assert.equal(numericStyleAt(element, frame - present.span.startFrame, "opacity"),
+ Number(frame >= start! && (mode === "trail" || frame < end!)));
+ }
+ }
+ }
+});
+
for (const mode of ["current", "trail"] as const) {
test(`Chinese ${mode} karaoke, underline and boxes follow unequal character times and pauses`, () => {
const { track, windows } = unevenChineseCaption({
diff --git a/packages/caption/test/chinese-pipeline.test.ts b/packages/caption/test/chinese-pipeline.test.ts
index fc0b1a0d..d08fa371 100644
--- a/packages/caption/test/chinese-pipeline.test.ts
+++ b/packages/caption/test/chinese-pipeline.test.ts
@@ -9,8 +9,8 @@ import { selectionFrameSpan } from "@hypit/timeline";
import { temporalizeCaptionDocument } from "../src/index.js";
import { fixtureResource } from "../../../test/fixture-resource.js";
-test("Chinese Script, WhisperX response, semantic assembly and captions preserve words, cue breaks and timing", () => {
- const parsed = parseScript("mixed-zh.svml", `<opening><HOST>用@brand ElevenLabs @/brand做视频,|| 真方便。</opening>
+for (const grouped of [false, true]) test(`Chinese Script through WhisperX and Timeline preserves caption timing (shared groups: ${grouped})`, () => {
+ const parsed = parseScript("mixed-zh.svml", `<opening><HOST>用@brand ElevenLabs @/brand做${grouped ? '<视频|>' : '视频'},|| 真方便。</opening>
<answer><GUEST>今年<2026|二零二六>年,這個很好。</answer>`);
const narrative = narrativeValue(parsed, "story") as unknown as Narrative;
const document = captionDocument(parsed, "story.caption", "story");
@@ -54,6 +54,9 @@ test("Chinese Script, WhisperX response, semantic assembly and captions preserve
assert.deepEqual(windowsFor("用"), [first[0]]);
assert.deepEqual(windowsFor("ElevenLabs"), [[first[1]![0], first[10]![1]]]);
assert.deepEqual(windowsFor("做"), [first[11]]);
+ if (grouped) assert.deepEqual(windowsFor("视频,"), [[first[12]![0], first[13]![1]]]);
+ assert.deepEqual(semantic.items[0]!.take.tokens.filter(token => ["做", "视", "频"].includes(token.text))
+ .map(token => [token.startFrame, token.endFrameExclusive]), first.slice(11, 14));
const span = selectionFrameSpan(semantic, { ...narrative.selections[0]!, narrativeId: narrative.id });
assert.deepEqual(span, { startFrame: first[1]![0], endFrameExclusive: first[10]![1] });
const second = evidenceWindows[1]!;
diff --git a/packages/script/README.md b/packages/script/README.md
index 764b6824..c0e52cdb 100644
--- a/packages/script/README.md
+++ b/packages/script/README.md
@@ -64,7 +64,7 @@ CaptionDocument contracts.
- **Role Cue**: a speaker turn, written as a bare tag such as `<ALICE>` inside a Segment. The next
Role Cue or the Segment close ends that turn.
- **Dual Text**: one authored speech span with separate display and spoken projections, written
- `<display text | spoken text>`.
+ `<display text | spoken text>`. In `<display text|>`, omitted speech inherits the displayed prose.
- **Selection marker**: a named semantic range, written `@name ... @/name`.
- **Moment marker**: a named semantic point, written `@name!`.
- **CaptionDocument**: the Script-owned caption truth; it contains **Display Words**,
@@ -73,11 +73,23 @@ CaptionDocument contracts.
`really{emphasis,importance=2,tone=warm}`. Values may be strings, finite numbers or booleans. It
becomes `CaptionDisplayWord.attributes`; it is not a Selection and does not carry timing.
-Within Dual Text, an unescaped `@` is legal only on the spoken side. The display side is literal; write
-`\@` if an at-sign must be shown. An empty display side, such as `< | spoken words>`, keeps the speech
+Within Dual Text, an unescaped `@` belongs to the source of spoken text: the right side when supplied,
+or the shared left side in `<display text|>`. Write `\@` if an at-sign must be shown. An empty display side, such as `< | spoken words>`, keeps the speech
tokens and omits them from Caption. `||` is an authored Caption Cue Break and must occur between
complete Alignment Units.
+`<组件化|>` is shorthand for `<组件化|组件化>`, using the same exported Caption Alignment Unit.
+It groups the displayed expression without merging its individual speech Tokens or time anchors.
+For example, `把<动效|><组件化|>。|| 之后<直接复用|>。` authors groups inside two Cues.
+Use groups where the expression should be treated together; ordinary prose needs no extra markup.
+Caption Styles choose whether to highlight, reveal or keep the text steady.
+
+In a shared side, markers and display attributes do not enter either text projection. Its speech
+Tokens retain offsets into the actually written left-hand text, so Studio can move an anchor inside
+`<组@beat!件化|>` without expanding the shorthand. Attributes still annotate the preceding display
+word, not the whole group. Whitespace-only speech is omitted; a group with no spoken text on either
+side is invalid. This adds no new public value type or protocol version.
+
## Segments, turns and Cues are different boundaries
A Segment names a structural production passage. It can contain several Role turns and be performed
diff --git a/packages/script/src/manifest.ts b/packages/script/src/manifest.ts
index 9d2dd50b..ec8a618c 100644
--- a/packages/script/src/manifest.ts
+++ b/packages/script/src/manifest.ts
@@ -64,7 +64,8 @@ export const scriptMarkupSurfaces = [
"A Script requires at least one Segment, and natural-language text is refused outside a Segment.",
"A Segment is opened by its own lower-case name and closed by that exact name, or written self-closing as `<pause/>`; the name is the Segment id, must be unique within the Script, and `script` is reserved. Segments do not nest.",
"A Role Cue such as `<HOST>` is a bare tag inside a Segment with no close; its turn runs until the next Cue or the end of the Segment, and a Cue may not follow unowned speech in the same Segment. Role state resets when the Segment closes.",
- "Dual Text is written `<display | speech>`: the left side reaches the caption projection and the right side reaches dialogue and speech. The spoken side must not be empty; the displayed side may be, which speaks a word that is never displayed.",
+ "Dual Text is written `<display | speech>`: the left side reaches Caption and the right side reaches dialogue and speech. `<display|>` inherits speech from the displayed prose and forms the same complete alignment unit; its word times remain individual. `<|speech>` speaks without displaying. Both sides empty is invalid.",
+ "Inside Dual Text, semantic markers belong to the source of spoken text: the explicit right side, or the shared left side when speech is omitted. Display attributes remain visual metadata and never enter spoken text.",
"A flat token attribute follows a complete display token as `{name}` or `{name=value}`; multiple attributes use one comma-separated block. Attributes do not nest, do not carry timing, and never split a Dual Alignment Unit.",
"Selection and Moment markers are zero-width, share one name namespace, and may not split a speech token:",
[
diff --git a/packages/script/src/parser.ts b/packages/script/src/parser.ts
index 839ef74c..d7c2ab08 100644
--- a/packages/script/src/parser.ts
+++ b/packages/script/src/parser.ts
@@ -499,16 +499,22 @@ export function parseScript(
const consumeSpeechSide = (
raw: string,
absoluteStart: number,
- caption: string,
+ caption: string | undefined,
marks: ParsedCaptionRegion["marks"] = [],
): void => {
const startToken = tokens.length;
+ // An omitted speech side shares the written display source. Keep its original offsets:
+ // marker edits target these words, not a synthetic copy beyond the pipe.
+ const shared = caption === undefined;
+ const spokenParts: string[] = [];
+ const sharedMarks: Array<ParsedCaptionRegion["marks"][number]> = [];
let partStart = 0;
let index = 0;
let emittedCaption = false;
const addLiteral = (part: string, start: number): void => {
for (const piece of literalPieces(part, start, true)) {
- addText(piece.value, emittedCaption ? "" : caption, piece.start, piece.end, false, piece.positions);
+ spokenParts.push(piece.value);
+ addText(piece.value, shared ? piece.value : emittedCaption ? "" : caption!, piece.start, piece.end, false, piece.positions);
emittedCaption = true;
}
};
@@ -520,6 +526,29 @@ export function parseScript(
if (raw.startsWith("||", index)) {
fail("SCRIPT_CAPTION_BREAK_DUAL", "Caption Cue break cannot occur inside Dual Text; split the Dual Text into separate units.", absoluteStart + index);
}
+ if (shared && raw[index] === "{") {
+ const before = raw.slice(partStart, index);
+ if (!before || /\s$/u.test(before)) {
+ fail("SCRIPT_ATTRIBUTE_TARGET", "A token attribute must immediately follow a display token.", absoluteStart + index);
+ }
+ addLiteral(before, absoluteStart + partStart);
+ const block = parseAttributeBlock(raw.slice(index), absoluteStart + index);
+ const displayIndex = displayWordSurfaces(spokenParts.join("")).length - 1;
+ if (displayIndex < 0 || tokens.length === startToken) {
+ fail("SCRIPT_ATTRIBUTE_TARGET", "A token attribute must follow a visible display token.", absoluteStart + index);
+ }
+ if (sharedMarks.some(mark => mark.displayIndex === displayIndex)) {
+ fail("SCRIPT_ATTRIBUTE_OVERLAP", "A display token cannot receive two separate attribute blocks.", absoluteStart + index);
+ }
+ sharedMarks.push({ displayIndex, attributes: block.attributes });
+ const token = tokens.at(-1)!;
+ tokens[tokens.length - 1] = { ...token, editRange: {
+ start: token.editRange.start, end: sourceOffset + absoluteStart + index + block.length,
+ } };
+ index += block.length;
+ partStart = index;
+ continue;
+ }
const marker = parseMarker(raw, index);
if (!marker) {
if (raw[index] === "@") fail("SCRIPT_MARKER", "Unescaped @ must begin a valid marker.", absoluteStart + index);
@@ -532,15 +561,19 @@ export function parseScript(
partStart = index;
}
addLiteral(raw.slice(partStart), absoluteStart + partStart);
+ const display = caption ?? spokenParts.join("");
+ if (shared && tokens.length === startToken) {
+ fail("SCRIPT_DUAL_EMPTY", "Dual Text with omitted speech must contain spoken text on its display side.", absoluteStart);
+ }
if (tokens.length > startToken) {
addCaptionRegion(
- caption,
+ display,
current!.id,
startToken,
tokens.length,
- cleanProjection(caption) ? "alias" : "hidden",
+ cleanProjection(display) ? "alias" : "hidden",
{ start: sourceOffset + absoluteStart, end: sourceOffset + absoluteStart + raw.length },
- marks,
+ shared ? sharedMarks : marks,
);
}
};
@@ -636,10 +669,16 @@ export function parseScript(
const pipe = findUnescaped(inside, "|");
if (pipe >= 0) {
finishLexicalRun();
+ const speech = inside.slice(pipe + 1);
+ if (!speech.trim()) {
+ consumeSpeechSide(inside.slice(0, pipe), offset + 1, undefined);
+ finishLexicalRun();
+ offset = end + 1;
+ continue;
+ }
assertDualDisplayLiteral(inside.slice(0, pipe), offset + 1);
const markedDisplay = parseMarkedDisplay(inside.slice(0, pipe), offset + 1);
const display = markedDisplay.display;
- const speech = inside.slice(pipe + 1);
if (!speech.replace(/~?@\/?[A-Za-z_][A-Za-z0-9_.-]*!?~?/gu, "").trim()) {
fail("SCRIPT_DUAL_EMPTY", "Dual Text speech side must not be empty.", offset);
}
diff --git a/packages/script/test/edit.test.ts b/packages/script/test/edit.test.ts
index 9be4ac54..efe600ef 100644
--- a/packages/script/test/edit.test.ts
+++ b/packages/script/test/edit.test.ts
@@ -16,6 +16,8 @@ const fixtures = [
'<one>Find \\@hypit now. @beat!</one>',
'<one>Use \\{braces\\} here. @beat!</one>',
'<one><Hypit|Hai \\@ Pit> works. @beat!</one>',
+ '<one><HOST>把<动效|><组件化|>。@beat!</one>',
+ '<one><HOST><Git Hub|> <图{emphasis}像|> <\\@Hypit|>。@beat!</one>',
];
test("horizontal formatting preserves lexical distinctions and line breaks", () => {
@@ -88,6 +90,7 @@ for (const source of [
'<one>A ~@s B . @/s</one>',
'<one>@s A @/s B .</one>',
'<one>@s A @/s~ B .</one>',
+ '<one><HOST>@s <动效|><组件化|> @/s</one>',
]) test(`Selection affinity survives every structural round trip: ${source}`, () => {
const original = parseScript("edit", source);
const selection = original.selections[0]!;
diff --git a/packages/script/test/narrative-views.test.ts b/packages/script/test/narrative-views.test.ts
index dbd141f8..30d69a16 100644
--- a/packages/script/test/narrative-views.test.ts
+++ b/packages/script/test/narrative-views.test.ts
@@ -1,6 +1,7 @@
import assert from "node:assert/strict";
import test from "node:test";
-import { decodeScriptSurface, narrativeValue, parseScript } from "@hypit/script";
+import { captionDocument, decodeScriptSurface, formatScript, narrativeDialogueTextValue,
+ narrativeSpeechTextValue, narrativeValue, parseScript } from "@hypit/script";
import { assertNarrativeIdentity, narrativeAnchorTokenBoundary, narrativeSelectionTokenRange,
narrativeTokensForSelection, narrativeTypes } from "@hypit/narrative";
import type { Narrative, NarrativeSelectionRef } from "@hypit/narrative";
@@ -8,6 +9,8 @@ import { captionUnitsForSelection, captionTypes, decodeHiddenCaptionStyleSurface
import type { CaptionProgram } from "@hypit/caption";
import { parseStructuredElement } from "@hypit/markup";
import type { SurfaceResolvedReference } from "@hypit/markup";
+import { countSpeechEstimateUnits } from "@hypit/estimate";
+import type { Text } from "@hypit/text";
const body = `<intro><HOST>Try @brand <hypit|Hai-Pit> @/brand today. ||</intro>
<gap/>
@@ -17,6 +20,42 @@ function authored() {
return narrativeValue(parseScript("views.svml", body), "story") as unknown as Narrative;
}
+test("omitted speech shares display prose while retaining ordinary Narrative and caption exports", () => {
+ for (const [short, expanded] of [
+ ['把<动效|><组件化|>。|| <直接复用|>。', '把<动效|动效><组件化|组件化>。|| <直接复用|直接复用>。'],
+ ['<Git Hub|> 和 <API|A P I>。<|只说不显示>', '<Git Hub|Git Hub> 和 <API|A P I>。<|只说不显示>'],
+ ['<图{emphasis}像|> 与 <\\@Hypit|>。', '<图{emphasis}像|图像> 与 <\\@Hypit|\\@Hypit>。'],
+ ]) {
+ const body = `<intro><HOST>${short}</intro>`;
+ const parsed = parseScript("short.svml", body);
+ const full = parseScript("full.svml", `<intro><HOST>${expanded}</intro>`);
+ assert.deepEqual(narrativeValue(parsed, "story"), narrativeValue(full, "story"));
+ assert.deepEqual(narrativeSpeechTextValue(parsed.segments[0]!), narrativeSpeechTextValue(full.segments[0]!));
+ assert.deepEqual(narrativeDialogueTextValue(parsed.segments[0]!), narrativeDialogueTextValue(full.segments[0]!));
+ const speech = narrativeSpeechTextValue(parsed.segments[0]!) as unknown as Text;
+ assert.equal(countSpeechEstimateUnits(speech.value, "zh"), countSpeechEstimateUnits(full.serializations.speech, "zh"));
+ assert.deepEqual(narrativeValue(parseScript("formatted", formatScript("short", body)), "story"), narrativeValue(parsed, "story"));
+ const source = `<script id="story">${body}</script>`;
+ const decoded = decodeScriptSurface({ sourceName: "short.svml", source, tag: "script",
+ attributes: { id: "story" }, openingStart: 0, contentStart: source.indexOf(">") + 1 });
+ assert.deepEqual(decoded.records.find(record => record.id === "story")?.value,
+ { kind: "inline", value: narrativeValue(parsed, "story") });
+ }
+});
+
+test("shared text permits semantic markers without changing display; empty groups still fail", () => {
+ const parsed = parseScript("shared", '<intro><HOST><组@part 件@/part化|></intro>');
+ assert.equal(parsed.serializations.speech, "组件化");
+ assert.equal(parsed.captionProjection.text, "组件化");
+ assert.equal(parsed.selections[0]!.startAnchorId, parsed.tokens[1]!.startAnchorId);
+ assert.equal(captionDocument(parsed, "caption", "story").units[0]!.sourceTokenIds.length, 3);
+ for (const body of ['<|>', '< | >', '<@beat!|>', '<...|>']) {
+ assert.throws(() => parseScript("empty", `<intro>${body}</intro>`), /omitted speech must contain spoken text/u);
+ }
+ assert.throws(() => parseScript("cue", '<intro><动效|动||效></intro>'), /Cue break cannot occur inside/u);
+ assert.throws(() => parseScript("explicit", '<intro><@bad 字|word></intro>'), /spoken text, not the Dual display side/u);
+});
+
test("Script exports complete author content and a caption view from that same value", () => {
const source = `<script id="story">${body}</script>`;
const result = decodeScriptSurface({ sourceName: "views.svml", source, tag: "script",
diff --git a/skills/hypit/references/creation/script-and-time.md b/skills/hypit/references/creation/script-and-time.md
index cab4c2a7..5f9f529e 100644
--- a/skills/hypit/references/creation/script-and-time.md
+++ b/skills/hypit/references/creation/script-and-time.md
@@ -61,6 +61,7 @@ The author-facing forms are:
| `<pause/>` | A self-closing Segment with identity and boundaries but no words. |
| `<HOST>` | A Role Cue inside the current Segment; it applies until another Role Cue or the Segment end. |
| `<display text \| spoken text>` | One Dual Text unit with separate visible and pronounced wording. |
+| `<display text\|>` | One complete display/speech unit using the same wording for both; individual spoken word times remain available. |
| `< \| spoken text>` | Spoken words that keep semantic timing while contributing no visible Caption words. |
| `||` | A Caption Cue handoff between complete Alignment Units. |
| `word{emphasis,keyword}` | Boolean attributes on one complete display word for a Caption family to interpret. |
@@ -82,6 +83,17 @@ complete Dual Text unit, not inside it. Attributes for a displayed Dual Text wor
display side before the pipe. Inside that display side, use `\@` when the visible text itself needs an
at-sign.
+When the wording is identical, `<组件化|>` is shorthand for `<组件化|组件化>`. It can group a name,
+compound or phrase for Caption presentation while leaving its spoken Tokens and timing intact:
+`把<动效|><组件化|>。|| 以后就能<直接复用|>。` Choose groups for the intended expression; ordinary
+Chinese prose does not require word-by-word markup. The group's Style determines its visual response;
+`||` still controls which reading phrases appear as separate Cues.
+
+With speech omitted, the left side supplies both projections, so semantic markers can be placed
+there and Studio writes back there: `<组@beat!件化|>`. Display attributes and markers are metadata,
+not spoken words. Attributes still apply to the preceding display word rather than the whole group.
+With an explicit spoken side, markers continue to belong on that right-hand side.
+
Script comments use ordinary Markup comments outside the prose:
```svml
diff --git a/skills/hypit/references/playbooks/craft/captions.md b/skills/hypit/references/playbooks/craft/captions.md
index 8055821e..0fec5fd6 100644
--- a/skills/hypit/references/playbooks/craft/captions.md
+++ b/skills/hypit/references/playbooks/craft/captions.md
@@ -137,6 +137,13 @@ Choose `trail` instead of `current` when the already spoken characters should st
sweeps inside its glyphs. Both follow each unit's own speech time, including uneven delivery and
pauses. Making a Cue longer changes its reading group, not its character timing.
+When a compound, name or short phrase should respond together, author it as `<组件化|>` in Script.
+The omitted spoken side inherits the same words. Fine's existing whole-unit `step` highlighting,
+underline and active box then follow that group's first-to-last speech interval, while each spoken
+character keeps its own Timeline anchors. A Cue can mix these groups with ordinary characters.
+Use this for deliberate whole-expression treatment, not as a requirement to annotate every Chinese
+word. `||` remains the reading handoff; group markup does not create another Cue.
+
Text appearing and text changing color are separate choices. `atom-reveal: all` keeps the complete
Cue available to read while Karaoke supplies emphasis; `on-start` reveals whole spoken units, and
`typewriter` reveals whole graphemes within them. A pronunciation span such as `<API|A P I>`