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.
TypeScript agentic-aiaiai-agentsai-videocompilerdslffmpeggenerative-aillmmarkup-languagemonorepoplugin-systemprogramming-languagetext-to-videotypescriptvideovideo-automationvideo-clonevideo-editingvideo-generation
docs: document the components a reader could not find
rponecca2df02f1e5
diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.tsindex 4b6ce2ee..9a8a940c 100644--- a/docs/.vitepress/config.ts+++ b/docs/.vitepress/config.ts@@ -139,8 +139,9 @@ const enTheme = {{ text: "Script", link: "/quickstart/script" },{ text: "SVS Stylesheets", link: "/quickstart/styles" },{ text: "Media & Generation", link: "/quickstart/generation" },+ { text: "Image Operations", link: "/quickstart/images" },{ text: "Timing & Assembly", link: "/quickstart/timing" },- { text: "Caption, Media, Typography & Audio Tracks", link: "/quickstart/tracks" },+ { text: "Tracks", link: "/quickstart/tracks" },{ text: "Film & Rendering", link: "/quickstart/composition" },{ text: "Live Preview", link: "/quickstart/preview" },{ text: "Run Source & Builds", link: "/quickstart/run" },@@ -183,8 +184,9 @@ const zhTheme = {{ text: "Script", link: "/zh/quickstart/script" },{ text: "SVS 样式表", link: "/zh/quickstart/styles" },{ text: "媒体与生成", link: "/zh/quickstart/generation" },+ { text: "图片操作", link: "/zh/quickstart/images" },{ text: "时序与装配", link: "/zh/quickstart/timing" },- { text: "字幕、Media、Typography 与 Audio 轨道", link: "/zh/quickstart/tracks" },+ { text: "轨道", link: "/zh/quickstart/tracks" },{ text: "Film 与渲染", link: "/zh/quickstart/composition" },{ text: "实时预览", link: "/zh/quickstart/preview" },{ text: "Run Source 与 Build", link: "/zh/quickstart/run" },diff --git a/docs/quickstart/images.md b/docs/quickstart/images.mdnew file mode 100644index 00000000..971a8180--- /dev/null+++ b/docs/quickstart/images.md@@ -0,0 +1,102 @@+---+title: Image Operations+description: Compose, correct and cut out images before they reach a generator or a Track.+---++# Image Operations++Three packages work on a picture and hand back a picture. None of them produces a Track: each output+is an image you reference downstream — as a Seedance reference frame, as a Media Item, or as the+source of another operation.++They all need an endpoint. `image-compose` and `image-transform` ask for the raster capability, which+`@narratage/provider-image-opencv-local` answers by running OpenCV in a bounded Python process on+your own machine; `background-removal` asks for its own capability, which `@narratage/provider-kie`+answers remotely. No example in this repository binds either, so add the endpoint to your+[Runtime Profile](/guide/runtime-profile) before planning a Build that uses one.++## Composing layers++`compose:Image` paints layers onto one canvas, in the order they are written, and hands back a PNG.++```svml+<import as="compose" from="@narratage/image-compose@1"/>+```++The element takes `id` and `canvas`, and optionally `background` — which must carry alpha, as+`#RRGGBBAA`, and defaults to fully transparent. Its children are `compose:Layer`, at least one and at+most sixty-four, each empty:++| Attribute | Takes |+|---|---|+| `source` | required — an image |+| `frame` | required — a `space:Frame` |+| `fit` | optional — `contain` (default), `cover` or `stretch` |+| `interpolation` | optional — `nearest`, `linear`, `cubic`, `area` or `lanczos` (default) |+| `opacity` | optional — 0 to 1, default 1 |++```svml+<compose:Image id="card" canvas={portrait} background="#00000000">+ <compose:Layer source={background.image} frame={full} fit="cover"/>+ <compose:Layer source={product.image} frame={product-frame} fit="contain"/>+</compose:Image>+```++**Output:** `{card.image}` — an image, not a Track.++## Correcting an image++An `image:Program` is a named list of operations; an `image:Transform` runs one over a source. The+split is deliberate: a program written once is applied to every shot that needs the same treatment.++```svml+<import as="image" from="@narratage/image-transform@1"/>+```++`image:Program` takes only `id`, and holds its operations as children, applied in the order written:++| Operation | Attributes |+|---|---|+| `Crop` | `x`, `y`, `width`, `height`; optional `unit="fraction" \| "pixel"` |+| `Resize` | `width`, `height`; optional `fit`, `interpolation`, `background` |+| `Rotate` | `degrees`, which must be `90`, `180` or `270` |+| `Flip` | optional `axis="horizontal" \| "vertical" \| "both"` |+| `Denoise` | optional `luma`, `chroma`, `template-window`, `search-window`, `saturation-recovery` |+| `Color` | optional `exposure-stops`, `contrast`, `saturation`, `temperature`, `tint`, `gamma` |+| `Sharpen` | optional `amount`, `radius`, `threshold` |+| `Blur` | `sigma` |+| `Alpha` | optional `mode="preserve" \| "flatten"`; `background` is required by `flatten` and refused by `preserve` |+| `Encode` | optional `format="png" \| "jpeg" \| "webp"`, `quality`, `background` |++A program may hold at most one `Encode`, and it must be last. Every operation but `Blur`, `Rotate`+and `Crop` runs on defaults alone, so `<image:Denoise/>` is a complete instruction.++`image:Transform` takes `id`, `source` and `program`, all required.++```svml+<image:Program id="clean-gpt-image">+ <image:Denoise/>+ <image:Encode format="png"/>+</image:Program>++<image:Transform id="clean-shot" source={shot.image} program={clean-gpt-image}/>+```++**Output:** `{clean-shot.image}`. The program on its own produces no image — it is a recipe, and+naming it in a `Transform` is what runs it.++## Removing a background++```svml+<import as="remove" from="@narratage/background-removal@1"/>+```++`remove:Background` is empty and takes `id` and `source`. It picks no model, threshold or storage —+that is the endpoint's business, not the Source's.++```svml+<remove:Background id="cutout" source={portrait.image}/>+```++**Output:** `{cutout.image}` — typically fed to a Media Item so a presenter sits over the picture+rather than in a box.diff --git a/docs/quickstart/tracks.md b/docs/quickstart/tracks.mdindex 7fba5737..38186502 100644--- a/docs/quickstart/tracks.md+++ b/docs/quickstart/tracks.md@@ -1,9 +1,9 @@----title: Caption, Media, Typography & Audio Tracks+title: Tracksdescription: Peer track components — captions, media, typography and authored audio.----# Caption, Media, Typography & Audio Tracks+# TracksEvery audiovisual contribution entering the final composition is a peer **Track**. Tracks are flat(no nesting), and visual z-order is determined by the `stack-order` property in SVS. This page@@ -327,6 +327,190 @@ placement, timing, style and motion. Use inline `P`/`Span`/`Break` when the auth**Output:** `{titles.track}` — a VisualTrack added to `film:Film`.+## Ranking boards++A board animates an ordered list against the Script: it enters on a Selection, moves on Moments, and+settles on a Moment that ends it. Four variants share one shape — a container, its own item tag, and+its own style tag.++| Container | Item | Style |+|---|---|---|+| `ranking:TierBoard` | `ranking:TierItem` | `ranking:TierBoardStyle` |+| `ranking:Column` | `ranking:ColumnItem` | `ranking:ColumnStyle` |+| `ranking:TopThree` | `ranking:TopThreeItem` | `ranking:TopThreeStyle` |+| `ranking:TypewriterList` | `ranking:TypewriterItem` | `ranking:TypewriterListStyle` |++```svml+<import as="ranking" from="@narratage/ranking@1"/>+```++### The style tag++Empty, and all three attributes required: `id`, `recipe` (an SVS Recipe) and `font` (a Font Stack or+Font artifact). The recipe carries the board's own keys — rows, colours, motion — and is validated+against the variant, so a Column recipe on a TierBoard is refused by name.++### The container tag++| Attribute | Takes |+|---|---|+| `map` | the Semantic Map that places words |+| `space` | the Program Space |+| `frame` | a `space:Frame` |+| `during` | a Selection — the board is on screen for it |+| `triggers` | a Moment — rows move on it |+| `terminal` | a Moment — the board settles on it |+| `style` | the matching style record, and only that variant's |+| `title` | `TypewriterList` only, and required there: a string or a Text reference |+| `appear-sound`, `move-sound` | optional Synchronized Media |++`move-sound` is refused on `TopThree`, which has no move phase. On a `TierBoard` it needs at least+one item with `entry="stage"`, and on a `TypewriterList` at least one `winner="true"` — a sound with+nothing to sound on is an authoring mistake, not a silent no-op.++### The item tags++Each variant takes its own, at least one, and ids must be unique within a board.++- **`TierItem`** — `tier` (required, matching a row id in the recipe), `icon` (required), optional+ `entry="direct" | "stage"` and `stack`. Row labels come from the recipe, not the tag.+- **`ColumnItem`** and **`TopThreeItem`** — `label` (required: a string or a Text reference), optional+ `icon` and `stack`. `TopThree` takes at most three.+- **`TypewriterItem`** — copy comes from `text=` or from the element's own text, one or the other;+ optional `winner="true"`, `stack`, and `emphasis-start` / `emphasis-end`, which are counted in+ graphemes and must be given together.++```svml+<ranking:ColumnStyle id="board-style" recipe={studio.ranking.board} font={ui-font}/>+<ranking:Column id="board" map={timing.map} space={speech.space} frame={board-frame}+ during={story.selection.board} triggers={story.moment.place} terminal={story.moment.done}+ style={board-style}>+ <ranking:ColumnItem id="row-regen" label="ReGen" icon={icon-regen}/>+ <ranking:ColumnItem id="row-chatgpt" label="ChatGPT" icon={icon-chatgpt}/>+ <ranking:ColumnItem id="row-remini" label="Remini" icon={icon-remini}/>+</ranking:Column>+```++**Output:** `{board.visual}` — a VisualTrack. A board given a sound also exports `{board.audio}`, an+AudioTrack; without one there is no audio output to add.++## Card decks++A deck holds cards in depth: one is in front, the others recede behind it, and each new card is dealt+on a Moment. Where a Media Item places one shot in one Frame, a deck keeps a stack of them in the+same Frame and moves the whole stack.++```svml+<import as="deck" from="@narratage/deck-track@1"/>+```++### deck:DepthStack++`id`, `map`, `space`, `canvas`, `frame` and `appearance` are all required, as is `until`, which says+what ends the deck: the literal `"program.end"`, a Moment, or a Selection. Only with a Selection may+you add `until-boundary="start" | "end"` to choose which edge of it ends the deck; the default is+`end`, and giving the attribute in the other two cases is refused rather than ignored.++### deck:Card++A direct child of the stack, self-closing, at least one, and dealt in document order.++| Attribute | Takes |+|---|---|+| `source` | required — a still image, a Synchronized Medium, or a Compositable Surface |+| `extent` | required for a still image and refused for anything else |+| `at` | required — the Moment the card is dealt on |+| `appearance` | optional — its own Recipe, otherwise the stack's |+| `label` | optional — a `deck:Label` record |++### deck:Label++`id` and `font` are required. The copy is either the `content=` reference or the element's own text —+give both and it is refused. `size`, `color`, `align`, `block` and `padding` are optional.++```svml+<space:Frame id="deck-frame" within={vertical} left="44%" top="60%" right="98%" bottom="88%"/>+<deck:DepthStack id="deck" map={timing.map} space={speech.space} canvas={vertical}+ frame={deck-frame} appearance={studio.deck.stack} until={story.moment.done}>+ <deck:Card id="card-spatial" source={icon-spatial} extent={square} at={story.moment.deal-one}/>+ <deck:Card id="card-type" source={icon-type} extent={square} at={story.moment.deal-two}/>+</deck:DepthStack>+```++**Output:** `{deck.track}` — a VisualTrack, an ordinary peer of every other Track in the Film.++## Screen overlays++Effects that cover the picture rather than sit in a Frame: a flash on a cut, a vignette that holds+for a Selection, grain over the whole programme. One Track carries them all, and each child is one+effect bound to its own window.++```svml+<import as="screen" from="@narratage/screen-overlay@1"/>+```++`screen:Track` takes `id`, `canvas` and `space`. Its children are the effects, at least one, each+empty, each with a required `z` for stacking order and a window that is one of:++| Window | Written |+|---|---|+| The whole programme | `during="program"` |+| A Selection | `during={story.selection.x} map={timing.map}` |+| A Moment, for a length | `at={story.moment.x} for="12f" map={timing.map}` |+| An explicit span | `start="…" end="…"`, optionally against a `selection=` or `moment=` |++Anything bound to the Script needs `map`; an explicit span with no Script source must not have one.+Lengths are `12f`, `250ms` or `1.5s`, and `occurrences="each"` repeats an effect at every occurrence+of its marker rather than the first.++Eleven effects are available — `Flash`, `ColorWash`, `Vignette`, `ScanLines`, `DirectionalMatte`,+`WhipVeil`, `GlitchVeil`, `Grain`, `LightLeak`, `Bokeh` and `TVStatic` — and each carries its own+required attributes, such as `color` / `intensity` / `attack` / `hold` / `decay` on a `Flash`, or+`center-x` / `center-y` / `radius-x` / `radius-y` / `softness` / `color` / `opacity` on a `Vignette`.+None have defaults: an effect states its whole shape or is refused.++```svml+<screen:Track id="effects" space={speech.space} canvas={vertical}>+ <screen:Flash during={story.selection.overlay} map={timing.map} z="80"+ color="#ffffff" intensity="0.6" attack="2" hold="2" decay="6"/>+</screen:Track>+```++**Output:** `{effects.track}` — a VisualTrack.++## Comment stickers++Social-style comment cards placed in a Frame: an avatar, an author, the comment itself, and an+optional metadata line.++```svml+<import as="comment" from="@narratage/comment-sticker@1"/>+```++`comment:Style` is empty and takes `id`, `recipe` and `font`, all required. The recipe carries the+card's whole appearance — background, border, radius, tail, avatar, the three text rows, and the+enter/hold/exit motion — and every key has a default, so a recipe may set only what it changes.++`comment:Track` takes `id`, `canvas` and `space`. It takes `map` only if one of its stickers binds to+the Script, and giving `map` when none does is refused rather than ignored.++`comment:Sticker` requires `id`, `frame` and `style`, and takes the same windows as a screen overlay+above. Its copy is either the `comment=` attribute or the element's own text — both is refused. The+optional `author`, `header` and `meta` each take a string or a Text reference, `avatar` takes an+image, and there is no `z`: stacking order comes from the recipe's `stack-order`.++```svml+<comment:Style id="social" recipe={studio.comment} font={ui-font}/>+<comment:Track id="comments" canvas={vertical} space={speech.space} map={timing.map}>+ <comment:Sticker id="one" frame={comment-frame} style={social} avatar={viewer-avatar}+ author="@viewer" meta="Featured" during={story.selection.reaction}>+ Wait, it pinned the caption to the word, not the second.+ </comment:Sticker>+</comment:Track>+```++**Output:** `{comments.track}` — a VisualTrack.+## Combination exampleAll four track families together in one source file:diff --git a/docs/zh/quickstart/images.md b/docs/zh/quickstart/images.mdnew file mode 100644index 00000000..a926dc8a--- /dev/null+++ b/docs/zh/quickstart/images.md@@ -0,0 +1,89 @@+---+title: 图片操作+description: 在图片流向生成器或 Track 之前,对它做合成、校正与抠图。+---++# 图片操作++有三个包接收一张图片、交还一张图片。它们都不产出 Track:每个输出都是一张可供下游引用的图片——作为 Seedance 的参考帧、作为 Media Item,或作为下一次操作的来源。++它们都需要 endpoint。`image-compose` 与 `image-transform` 索取 raster 能力,由 `@narratage/provider-image-opencv-local` 在你自己机器上以受限的 Python 进程运行 OpenCV 来满足;`background-removal` 索取的是它自己声明的能力,由 `@narratage/provider-kie` 远程满足。本仓库没有任何示例绑定过这两者,所以在 plan 一次用到它们的 Build 之前,先把 endpoint 加进你的 [Runtime Profile](/zh/guide/runtime-profile)。++## 合成图层++`compose:Image` 按书写顺序把各图层画到同一张画布上,交还一张 PNG。++```svml+<import as="compose" from="@narratage/image-compose@1"/>+```++元素接受 `id` 与 `canvas`,以及可选的 `background`——它必须带 alpha,写作 `#RRGGBBAA`,默认为完全透明。子元素是 `compose:Layer`,至少一个、至多六十四个,各自为空:++| 属性 | 取值 |+|---|---|+| `source` | 必填——一张图片 |+| `frame` | 必填——一个 `space:Frame` |+| `fit` | 可选——`contain`(默认)、`cover` 或 `stretch` |+| `interpolation` | 可选——`nearest`、`linear`、`cubic`、`area` 或 `lanczos`(默认) |+| `opacity` | 可选——0 到 1,默认 1 |++```svml+<compose:Image id="card" canvas={portrait} background="#00000000">+ <compose:Layer source={background.image} frame={full} fit="cover"/>+ <compose:Layer source={product.image} frame={product-frame} fit="contain"/>+</compose:Image>+```++**输出:** `{card.image}`——一张图片,不是 Track。++## 校正图片++`image:Program` 是一份具名的操作清单,`image:Transform` 把它作用在某个来源上。这样拆开是有意的:一份写好的 program 可以套用到每一个需要同样处理的镜头上。++```svml+<import as="image" from="@narratage/image-transform@1"/>+```++`image:Program` 只接受 `id`,操作以子元素形式书写,按书写顺序依次施加:++| 操作 | 属性 |+|---|---|+| `Crop` | `x`、`y`、`width`、`height`;可选 `unit="fraction" \| "pixel"` |+| `Resize` | `width`、`height`;可选 `fit`、`interpolation`、`background` |+| `Rotate` | `degrees`,只能是 `90`、`180` 或 `270` |+| `Flip` | 可选 `axis="horizontal" \| "vertical" \| "both"` |+| `Denoise` | 可选 `luma`、`chroma`、`template-window`、`search-window`、`saturation-recovery` |+| `Color` | 可选 `exposure-stops`、`contrast`、`saturation`、`temperature`、`tint`、`gamma` |+| `Sharpen` | 可选 `amount`、`radius`、`threshold` |+| `Blur` | `sigma` |+| `Alpha` | 可选 `mode="preserve" \| "flatten"`;`flatten` 要求给出 `background`,`preserve` 则拒绝它 |+| `Encode` | 可选 `format="png" \| "jpeg" \| "webp"`、`quality`、`background` |++一份 program 至多只能有一个 `Encode`,且必须放在最后。除 `Blur`、`Rotate` 与 `Crop` 之外,每个操作都能仅凭默认值运行,所以 `<image:Denoise/>` 本身就是一条完整的指令。++`image:Transform` 接受 `id`、`source` 与 `program`,全部必填。++```svml+<image:Program id="clean-gpt-image">+ <image:Denoise/>+ <image:Encode format="png"/>+</image:Program>++<image:Transform id="clean-shot" source={shot.image} program={clean-gpt-image}/>+```++**输出:** `{clean-shot.image}`。program 本身不产出任何图片——它是一份配方,在 `Transform` 中指名它才会真正运行。++## 去除背景++```svml+<import as="remove" from="@narratage/background-removal@1"/>+```++`remove:Background` 必须为空,接受 `id` 与 `source`。它不挑选模型、阈值或存储——那是 endpoint 的事,不是 Source 的事。++```svml+<remove:Background id="cutout" source={portrait.image}/>+```++**输出:** `{cutout.image}`——通常喂给一个 Media Item,好让出镜者叠在画面上,而不是待在一个方框里。diff --git a/docs/zh/quickstart/tracks.md b/docs/zh/quickstart/tracks.mdindex 7bd1a7e9..fccb5dff 100644--- a/docs/zh/quickstart/tracks.md+++ b/docs/zh/quickstart/tracks.md@@ -1,9 +1,9 @@----title: 字幕、Media、Typography 与 Audio 轨道+title: 轨道description: 对等 Track 组件——字幕、媒体、排版与作者声明的音频。----# 字幕、Media、Typography 与 Audio 轨道+# 轨道每个进入最终合成的视听内容都是一个对等的 **Track**。Track 是扁平的(无嵌套);视觉层的z 轴顺序由 SVS 中的 `stack-order` 属性决定。本页介绍 Caption、Media、Typography 与 Audio@@ -273,6 +273,157 @@ Run 时,继续使用内联 `P`/`Span`/`Break`。**输出:**`{titles.track}` —— 添加到 `film:Film` 的 VisualTrack。+## 榜单板++榜单板让一份有序列表跟着 Script 动起来:在某个 Selection 期间出现,在 Moment 上移动,在另一个 Moment 上定格。四个变体共用同一套形状——一个容器、它专属的条目标签、以及它专属的样式标签。++| 容器 | 条目 | 样式 |+|---|---|---|+| `ranking:TierBoard` | `ranking:TierItem` | `ranking:TierBoardStyle` |+| `ranking:Column` | `ranking:ColumnItem` | `ranking:ColumnStyle` |+| `ranking:TopThree` | `ranking:TopThreeItem` | `ranking:TopThreeStyle` |+| `ranking:TypewriterList` | `ranking:TypewriterItem` | `ranking:TypewriterListStyle` |++```svml+<import as="ranking" from="@narratage/ranking@1"/>+```++### 样式标签++标签必须为空,三个属性全部必填:`id`、`recipe`(一份 SVS Recipe)与 `font`(Font Stack 或字体产物)。Recipe 承载这块板自己的键——行、配色、动效——并且会按变体校验,把 Column 的 recipe 给 TierBoard 会被指名拒绝。++### 容器标签++| 属性 | 取值 |+|---|---|+| `map` | 安放词语的 Semantic Map |+| `space` | Program Space |+| `frame` | 一个 `space:Frame` |+| `during` | 一个 Selection——板在此期间留在画面上 |+| `triggers` | 一个 Moment——行在它上面移动 |+| `terminal` | 一个 Moment——板在它上面定格 |+| `style` | 对应的样式记录,且只接受本变体的 |+| `title` | 仅 `TypewriterList` 有,且必填:字符串或 Text 引用 |+| `appear-sound`、`move-sound` | 可选,Synchronized Media |++`move-sound` 在 `TopThree` 上会被拒绝——它没有移动阶段。在 `TierBoard` 上它要求至少有一个 `entry="stage"` 的条目,在 `TypewriterList` 上要求至少有一个 `winner="true"`:声音没有可响之处是创作错误,而不是静默的空操作。++### 条目标签++每个变体只接受自己的那一种,至少一个,且 id 在同一块板内不可重复。++- **`TierItem`** —— `tier`(必填,须与 recipe 中某一行的 id 对上)、`icon`(必填),可选 `entry="direct" | "stage"` 与 `stack`。行的文字来自 recipe,不写在标签上。+- **`ColumnItem`** 与 **`TopThreeItem`** —— `label`(必填:字符串或 Text 引用),可选 `icon` 与 `stack`。`TopThree` 最多三条。+- **`TypewriterItem`** —— 文案来自 `text=` 或元素自身的文字,二者取其一;可选 `winner="true"`、`stack`,以及 `emphasis-start` / `emphasis-end`,二者按字素计数且必须成对出现。++```svml+<ranking:ColumnStyle id="board-style" recipe={studio.ranking.board} font={ui-font}/>+<ranking:Column id="board" map={timing.map} space={speech.space} frame={board-frame}+ during={story.selection.board} triggers={story.moment.place} terminal={story.moment.done}+ style={board-style}>+ <ranking:ColumnItem id="row-regen" label="ReGen" icon={icon-regen}/>+ <ranking:ColumnItem id="row-chatgpt" label="ChatGPT" icon={icon-chatgpt}/>+ <ranking:ColumnItem id="row-remini" label="Remini" icon={icon-remini}/>+</ranking:Column>+```++**输出:** `{board.visual}`——一条 VisualTrack。带了声音的板还会导出 `{board.audio}`,一条 AudioTrack;没有声音时就没有这个输出。++## 卡片堆++卡片堆按深度排布卡片:一张在最前,其余向后退去,每张新卡在一个 Moment 上发出。Media Item 是把一个镜头放进一个 Frame,而卡片堆是在同一个 Frame 里维持一叠并整体移动它们。++```svml+<import as="deck" from="@narratage/deck-track@1"/>+```++### deck:DepthStack++`id`、`map`、`space`、`canvas`、`frame` 与 `appearance` 全部必填,`until` 同样必填——它说明什么结束这叠卡片:字面量 `"program.end"`、一个 Moment,或一个 Selection。只有在指向 Selection 时才可以再加 `until-boundary="start" | "end"` 来选择用它的哪一端结束,默认是 `end`;在另外两种情况下给出这个属性会被拒绝,而不是被忽略。++### deck:Card++DepthStack 的直接子元素,自闭合,至少一张,按书写顺序发出。++| 属性 | 取值 |+|---|---|+| `source` | 必填——静态图片、Synchronized Medium 或 Compositable Surface |+| `extent` | 静态图片必填,其余情况给了会被拒绝 |+| `at` | 必填——这张卡发出的 Moment |+| `appearance` | 可选——它自己的 Recipe,否则沿用整叠的 |+| `label` | 可选——一条 `deck:Label` 记录 |++### deck:Label++`id` 与 `font` 必填。文案来自 `content=` 引用或元素自身的文字,两个都给会被拒绝。`size`、`color`、`align`、`block`、`padding` 可选。++```svml+<space:Frame id="deck-frame" within={vertical} left="44%" top="60%" right="98%" bottom="88%"/>+<deck:DepthStack id="deck" map={timing.map} space={speech.space} canvas={vertical}+ frame={deck-frame} appearance={studio.deck.stack} until={story.moment.done}>+ <deck:Card id="card-spatial" source={icon-spatial} extent={square} at={story.moment.deal-one}/>+ <deck:Card id="card-type" source={icon-type} extent={square} at={story.moment.deal-two}/>+</deck:DepthStack>+```++**输出:** `{deck.track}`——一条 VisualTrack,与 Film 中其它每一条 Track 平级。++## 屏幕叠加层++覆盖在整个画面之上、而非落在某个 Frame 里的效果:切点上的一次闪白、持续整个 Selection 的暗角、铺满全片的颗粒。一条 Track 承载全部,每个子元素是一个效果加它自己的时间窗。++```svml+<import as="screen" from="@narratage/screen-overlay@1"/>+```++`screen:Track` 接受 `id`、`canvas` 与 `space`。它的子元素就是各个效果,至少一个,各自为空,都必须带 `z` 决定层叠顺序,并且各有一个时间窗,形式是以下之一:++| 时间窗 | 写法 |+|---|---|+| 整个节目 | `during="program"` |+| 一个 Selection | `during={story.selection.x} map={timing.map}` |+| 一个 Moment,持续一段时长 | `at={story.moment.x} for="12f" map={timing.map}` |+| 显式区间 | `start="…" end="…"`,可另外指定 `selection=` 或 `moment=` |++凡是绑定到 Script 的都需要 `map`;不带 Script 来源的显式区间则不能给 `map`。时长写作 `12f`、`250ms` 或 `1.5s`,`occurrences="each"` 让效果在标记的每一次出现处重复,而不只是第一次。++可用的效果有十一种——`Flash`、`ColorWash`、`Vignette`、`ScanLines`、`DirectionalMatte`、`WhipVeil`、`GlitchVeil`、`Grain`、`LightLeak`、`Bokeh` 与 `TVStatic`——每种各有自己的必填属性,例如 `Flash` 的 `color` / `intensity` / `attack` / `hold` / `decay`,或 `Vignette` 的 `center-x` / `center-y` / `radius-x` / `radius-y` / `softness` / `color` / `opacity`。它们都没有默认值:一个效果要么把自己的形状说全,要么被拒绝。++```svml+<screen:Track id="effects" space={speech.space} canvas={vertical}>+ <screen:Flash during={story.selection.overlay} map={timing.map} z="80"+ color="#ffffff" intensity="0.6" attack="2" hold="2" decay="6"/>+</screen:Track>+```++**输出:** `{effects.track}`——一条 VisualTrack。++## 评论贴纸++放置在 Frame 中的社交风格评论卡:头像、作者、评论正文,以及可选的一行附注。++```svml+<import as="comment" from="@narratage/comment-sticker@1"/>+```++`comment:Style` 必须为空,接受 `id`、`recipe` 与 `font`,全部必填。Recipe 承载整张卡的外观——背景、描边、圆角、气泡尾、头像、三行文字,以及进入/停留/退出的动效——每个键都有默认值,所以一份 recipe 只需写它要改的部分。++`comment:Track` 接受 `id`、`canvas` 与 `space`。只有当它的某张贴纸绑定到 Script 时才接受 `map`;没有任何贴纸绑定却给了 `map` 会被拒绝,而不是被忽略。++`comment:Sticker` 必填 `id`、`frame` 与 `style`,时间窗与上面的屏幕叠加层相同。它的文案来自 `comment=` 属性或元素自身的文字,两个都给会被拒绝。可选的 `author`、`header` 与 `meta` 各接受字符串或 Text 引用,`avatar` 接受一张图片;这里没有 `z`,层叠顺序来自 recipe 的 `stack-order`。++```svml+<comment:Style id="social" recipe={studio.comment} font={ui-font}/>+<comment:Track id="comments" canvas={vertical} space={speech.space} map={timing.map}>+ <comment:Sticker id="one" frame={comment-frame} style={social} avatar={viewer-avatar}+ author="@viewer" meta="Featured" during={story.selection.reaction}>+ 原来它把字幕钉在词上,而不是钉在秒上。+ </comment:Sticker>+</comment:Track>+```++**输出:** `{comments.track}`——一条 VisualTrack。+## 组合示例四类 Track 在一个源文件中协同使用: