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.

Revert "docs: align all documentation with v2-bootstrap package restructure"

rpone1c363c377132
diff --git a/docs/guide/packages.md b/docs/guide/packages.md
index 61f16a32..f07cc636 100644
--- a/docs/guide/packages.md
+++ b/docs/guide/packages.md
@@ -75,7 +75,6 @@ Depends on Layer 1 and 2 but not on any Provider.
@narratage/model-kit model family abstractions
@narratage/seedance Seedance model family + author Surface
@narratage/seedance-kits data-only Seedance semantic Text Templates
-@narratage/seedance-speaker Seedance Speaker binding
@narratage/minimax-h3 MiniMax H3 model family
@narratage/gemini-omni Gemini Omni model family
@narratage/grok-imagine Grok Imagine model family
@@ -103,7 +102,6 @@ Depends on Layer 1 and 2 but not on any Provider.
@narratage/deck-track depth-stack collection Track
@narratage/ranking four ranking component families
@narratage/screen-overlay self-contained full-canvas overlays
-@narratage/comment-sticker anchored comment sticker overlay
@narratage/film Film composition
@narratage/composition peer Track composition
@narratage/visual-ir renderer-neutral visual vocabulary
@@ -131,7 +129,7 @@ never on exact-model packages or the CLI.
@narratage/provider-hyperframes-aws-lambda recoverable distributed rendering
@narratage/provider-image-opencv-local local OpenCV Raster execution
@narratage/provider-media-aws-lambda synchronous AWS media execution
-@narratage/provider-xiaomi-mimo official Xiaomi MiMo TTS API
+@narratage/provider-xiaomi-mimo official Xiaomi MiMo TTS API
```
### Layer 5: Application
@@ -152,7 +150,7 @@ never on exact-model packages or the CLI.
3. **CLI independence.** Neither `@narratage/cli` nor `@narratage/video-cli` transitively depends on any
Provider package. The video CLI also does not depend on any author-level video package
- (`@narratage/script`, `@narratage/seedance-speaker`, `@narratage/media-track`, `@narratage/typography-track`, `@narratage/film`).
+ (`@narratage/script`, `@narratage/seedance`, `@narratage/media-track`, `@narratage/typography-track`, `@narratage/film`).
Author packages are activated through the explicit package lock, not compile-time CLI
dependencies.
diff --git a/docs/guide/playground.md b/docs/guide/playground.md
index 29abf4fe..1321ae04 100644
--- a/docs/guide/playground.md
+++ b/docs/guide/playground.md
@@ -22,12 +22,14 @@ no credentials, no local services.
|---|---|
| Component list | Every module that can put pixels on a frame |
| W / H / fps / sec | The canvas and the frame domain |
-| Canvas from a stylesheet | Adopt a `.svs` file's frame size |
+| Appearance from a stylesheet | Adopt a `.svs` Film Recipe's background |
| Input forms | One per input the component takes |
| Scrubber | Frame-exact; the counter shows `frame / last` |
-The preview is the real thing. Each component's own renderer runs and
-`compileHyperframesDocument` produces the same document a Build would render.
+The preview uses the installed modules' real Producer handlers. For example,
+Fine Caption, Media Track, Screen Overlay, Speech Basis and Typography Track
+all lower to `VisualTrack`, then `compileHyperframesDocument` produces the same
+document a Build would render.
## It lists nothing
@@ -70,16 +72,17 @@ A `format: "digest"` field takes a file. The playground hashes it with SHA-256
and registers a real content-addressed identity, because a compiled document
cross-checks every Artifact reference and would reject a stub.
-Modules that draw supplied footage — media track items, speaker footage —
-therefore have no default: a module has no bytes to point at, so it says nothing
-rather than inventing a digest. Until you choose a file those components draw
-nothing, which is a state to pass through and not an error.
+Modules that draw supplied footage — B-roll, speaker footage — therefore have no
+default: a module has no bytes to point at, so it says nothing rather than
+inventing a digest. Until you choose a file those components draw nothing, which
+is a state to pass through and not an error.
## Stylesheets
-Choosing a `.svs` file reads **only its Film Recipe**, and only for the frame
-size. Point it at a studio stylesheet and the canvas becomes its configured
-dimensions and background.
+Choosing a `.svs` file reads **only its Film Recipe**, and only for Film
+appearance. Point it at `examples/talking-film-golden/studio.svs` and the
+preview adopts that Recipe's background. Canvas dimensions and time remain
+explicit preview-environment controls.
Nothing else in the sheet is read. What a component looks like comes from the
module that owns it, not from a stylesheet the playground happened to open.
diff --git a/docs/quickstart.md b/docs/quickstart.md
index 7dfc1854..6c3f922c 100644
--- a/docs/quickstart.md
+++ b/docs/quickstart.md
@@ -13,14 +13,16 @@ a montage of scenes to match.
That is exactly what this system does. The author writes a narrated Script with semantic anchors,
and the compiler assembles generated video, captions, B-roll, text and audio into a finished film.
Author Sources are written in SVML (Semantic Video Markup Language) and carry the `.svml`
-extension; the workspace packages are published under the `@narratage` scope.
+extension; development packages in this workspace reserve the `@narratage` scope. They have not
+been published to npm yet.
## Install
Requires Node.js 22+ and pnpm.
```bash
-pnpm install
+corepack enable
+pnpm install --frozen-lockfile
pnpm check
pnpm test
```
@@ -59,10 +61,9 @@ before spending money.
| Guide | Topic |
|---|---|
| [Script](./quickstart/script.md) | Segments, Role Cues, Dual Text, Selections, Moments, text projections |
-| [SVS Stylesheets](./quickstart/styles.md) | CSS-like Recipes for film, caption, media, text, speech and fonts |
-| [Media & Generation](./quickstart/generation.md) | media:Image, media:Audio, estimate:Speech, Seedance, speaker:Take |
+| [SVS Stylesheets](./quickstart/styles.md) | CSS-like Recipes for film, caption, B-roll, text, speech and fonts |
+| [Media & Generation](./quickstart/generation.md) | media:Image, media:Audio, estimate:Speech, Text Templates, Seedance |
| [Timing & Assembly](./quickstart/timing.md) | speech:Spine, whisperx:Alignment, ProgramSpace, SemanticMap |
| [Caption, Media & Text](./quickstart/tracks.md) | caption-fine:Style/Track, caption:Program, Planner, Media Track and Text |
| [Film & Rendering](./quickstart/composition.md) | film:Film, render:Video, full pipeline walkthrough |
| [Run Source & Builds](./quickstart/run.md) | .svrun syntax, targets, reuse, runtime profile, build workflow |
-
diff --git a/docs/quickstart/generation.md b/docs/quickstart/generation.md
index 8ccc0af4..3c7312f5 100644
--- a/docs/quickstart/generation.md
+++ b/docs/quickstart/generation.md
@@ -12,9 +12,11 @@ Every component shown here must be imported by its package specifier before use:
```svml
<import as="media" from="@narratage/media@1"/>
+<import as="mediaop" from="@narratage/media-pipeline@1"/>
<import as="estimate" from="@narratage/estimate@1"/>
+<import as="text" from="@narratage/text@1"/>
<import as="seedance" from="@narratage/seedance@1"/>
-<import as="speaker" from="@narratage/seedance-speaker@1"/>
+<import as="speaker-kit" source="../../packages/seedance-kits/kits/speaker-v1.svs"/>
```
## media:Image
@@ -31,7 +33,7 @@ Declares a content-addressed image asset from a local file.
| `src` | yes | Path to the image file, relative to the `.svml` source |
The image is referenced downstream via `{presenter}` — for example, as a character reference in
-`seedance:Speech` or as a B-roll source.
+`seedance:ReferenceVideo` or as a B-roll source.
## media:Audio
@@ -46,12 +48,12 @@ Declares a content-addressed audio asset from a local file.
| `id` | yes | Unique identifier |
| `src` | yes | Path to the audio file, relative to the `.svml` source |
-Typically used as a voice-timbre reference for `speaker:Take`.
+Typically used as a voice-timbre reference for `seedance:ReferenceVideo`.
## estimate:Speech
-Deterministic speech duration estimation from Script text. No external service call — the estimate is
-computed locally from word count and pace parameters.
+Deterministic speech duration planning from Script pronunciation text. No external service call — the
+duration is computed locally from pronunciation units and a delivery-density policy.
```svml
<estimate:Speech id="hook-duration"
@@ -63,7 +65,7 @@ computed locally from word count and pace parameters.
|---|---|---|
| `id` | yes | Unique identifier |
| `source` | yes | Script text to estimate — typically `{script.segment.NAME.speech}` |
-| `policy` | yes | SVS speech Recipe controlling pace and bounds |
+| `policy` | no | SVS speech Recipe controlling pace and bounds; omit it to use inline parameters |
The `policy` references an SVS Recipe (see [SVS Stylesheets](./styles.md#speech-estimation)):
@@ -71,10 +73,9 @@ The `policy` references an SVS Recipe (see [SVS Stylesheets](./styles.md#speech-
speech.normal {
language: en;
pace: normal;
- padding: 0.3;
min: 4;
max: 15;
- rounding: ceil;
+ rounding: round;
}
```
@@ -83,154 +84,189 @@ You can also specify estimation parameters inline instead of using an SVS policy
```svml
<estimate:Speech id="opening-duration"
source={story.segment.opening.speech}
- language="en" pace="normal" padding="0.3" min="4" max="15" rounding="ceil"/>
+ language="en" pace="normal" min="4" max="15" rounding="round"/>
```
+For English, the official pace presets are `slow = 4.2`, `normal = 4.6`, and
+`fast = 5.0` syllables per second. `rate="4.75"` may be used instead of `pace`
+when a project needs a value between the named presets. `pace` and `rate` are
+mutually exclusive.
+
+There are no implicit policy values: `language`, `min`, `max`, `rounding`, and
+exactly one of `pace` or `rate` must be present either inline or in the referenced Recipe.
+
**Output:** `{hook-duration.duration}` — the estimated duration in seconds, passed to generation
components.
-## seedance:Prompt
+## text:Value
-A reusable text block that provides visual direction for Seedance generation.
+A reusable literal `Text` value. It is model-neutral and can feed Seedance, GPT Image or any other
+declared text port.
```svml
-<seedance:Prompt id="alice-direction">
+<import as="text" from="@narratage/text@1"/>
+
+<text:Value id="alice-direction">
Locked medium close-up. Alice speaks directly to camera in a quiet daylight studio.
Calm, curious delivery; natural breathing and restrained hand movement.
-</seedance:Prompt>
+ Spoken dialogue — say exactly: What if editing began with meaning?
+</text:Value>
```
| Attribute | Required | Description |
|---|---|---|
| `id` | yes | Unique identifier |
-The element body is the prompt text. Referenced by `seedance:Speech` and `seedance:Video` via their
-`prompt` attribute.
+The element body is the exact Text value. `text:Render` can produce the same type from a template
+and explicit graph inputs.
+
+## Seedance invocation shapes
+
+Seedance exposes model capabilities, not creative usages. `standard`, `fast` and `mini` choose the
+model variant independently of three invocation shapes. All shapes consume a complete ordinary
+`Text` prompt and output `{id.video}`.
-## seedance:Speech
+### seedance:TextVideo
-Generates a talking-head video clip via the Seedance model. This is the low-level generation
-component — it directly specifies the dialogue, prompt, and duration.
+Prompt-only generation. This is the only shape that accepts `web-search`.
```svml
-<seedance:Speech id="alice-take" model="mini"
- dialogue={story.segment.opening.dialogue}
- prompt={alice-direction}
- duration="8">
- <seedance:Reference image={alice-reference} role="character"/>
-</seedance:Speech>
+<seedance:TextVideo id="ambient" model="mini"
+ prompt={ambient-direction} duration="5" web-search="false"/>
```
-| Attribute | Required | Description |
-|---|---|---|
-| `id` | yes | Unique identifier |
-| `model` | yes | Seedance model name: `mini` |
-| `dialogue` | yes | Script text to lip-sync — typically `{script.segment.NAME.dialogue}` |
-| `prompt` | yes | Visual direction — reference to a `seedance:Prompt` |
-| `duration` | yes | Clip duration in seconds (number or `{estimate.duration}` reference) |
-| `resolution` | no | Output resolution: `480p`, `720p` (default varies by model) |
-| `aspect-ratio` | no | Output aspect ratio: `9:16`, `16:9`, `1:1` |
-
-### seedance:Reference
+### seedance:FrameVideo
-Child element that provides a reference image for character consistency:
+First-frame generation with an optional last frame:
```svml
-<seedance:Reference image={alice-reference} role="character"/>
+<seedance:FrameVideo id="transition" model="fast"
+ prompt={transition-direction} duration="5"
+ first-frame={opening-image} last-frame={closing-image}/>
```
-| Attribute | Required | Description |
-|---|---|---|
-| `image` | yes | Reference to a `media:Image` component |
-| `role` | yes | How this reference is used: `character`, `subject` |
-
-**Output:** `{alice-take}` or `{alice-take.video}` — the generated video, passed to `speech:Spine`.
+### seedance:ReferenceVideo
-## seedance:Video
-
-Generates a standalone video clip (not a talking-head — no dialogue lip-sync).
+Multimodal reference generation. It requires at least one `Reference` child and accepts image,
+video and audio references within the model's declared limits.
```svml
-<seedance:Video id="product-motion" model="mini"
- prompt={product-direction} duration="5">
- <seedance:Reference image={product-reference} role="subject"/>
-</seedance:Video>
+<seedance:ReferenceVideo id="alice-take" model="mini"
+ prompt={alice-direction}
+ duration={alice-duration.duration}
+ generate-audio="true">
+ <seedance:Reference image={alice-reference}/>
+ <seedance:Reference audio={alice-voice}/>
+</seedance:ReferenceVideo>
```
-| Attribute | Required | Description |
-|---|---|---|
-| `id` | yes | Unique identifier |
-| `model` | yes | Seedance model name: `mini` |
-| `prompt` | yes | Visual direction — reference to a `seedance:Prompt` |
-| `duration` | yes | Clip duration in seconds |
-
-Also accepts `<seedance:Reference>` children for reference images.
-
-**Output:** `{product-motion.video}` — used as a B-roll source.
+The component does not know that this is a talking head. That meaning lives in the supplied Text.
-## speaker:Take
+Common attributes are `id`, `model`, `prompt`, `duration`, `resolution`, `aspect-ratio` and
+`generate-audio`. `duration` may be literal or an explicit `{estimate.duration}` edge.
-A higher-level talking-head component built on top of Prompt Kit. Instead of writing a raw prompt,
-you provide a Recipe with generation settings and a Kit that assembles the prompt automatically.
+The audio generated in an earlier take can be reused as a later reference through an ordinary graph
+edge. Extraction does not turn it into speech evidence or attach speaker meaning:
```svml
-<import as="speaker" from="@narratage/seedance-speaker@1"/>
-<import as="ugc" source="../../packages/seedance-speaker/kits/official-ugc-v1.svs"/>
-
-<speaker:Take id="hook-take"
- dialogue={story.segment.hook.dialogue}
- duration={hook-duration.duration}
- recipe={studio.speaker.host}
- kit={ugc.official-ugc-v1}>
- <speaker:Reference image={presenter-clean} role="character-and-scene"/>
- <speaker:Reference audio={presenter-voice} role="voice-timbre"/>
-</speaker:Take>
+<mediaop:ExtractAudio id="voice-from-opening"
+ source={opening.video} audio="default"/>
+
+<seedance:ReferenceVideo id="follow-up" model="mini"
+ prompt={follow-up-direction} duration="5" generate-audio="true">
+ <seedance:Reference image={presenter-reference}/>
+ <seedance:Reference audio={voice-from-opening.audio}/>
+</seedance:ReferenceVideo>
```
-| Attribute | Required | Description |
-|---|---|---|
-| `id` | yes | Unique identifier |
-| `dialogue` | yes | Script text — typically `{script.segment.NAME.dialogue}` |
-| `duration` | yes | Estimated duration from `estimate:Speech` |
-| `recipe` | yes | SVS speaker Recipe (see [SVS Stylesheets](./styles.md#speaker)) |
-| `kit` | yes | Prompt Kit SVS — the template that assembles the prompt |
+The same media-operation package exposes `Transform` for ordered trim/retime and `ExtractFrame` for
+first, last, indexed or timestamped still extraction. Local FFmpeg and AWS Lambda are interchangeable
+Runtime Endpoints for these exact Needs; neither changes the author graph.
-### speaker:Reference
+## Seedance semantic Kits
-Child element providing reference media. Accepts both images and audio:
+`@narratage/seedance-kits` contains seven data-only Text Templates. A Kit is not a model wrapper: use
+generic `text:Render` to produce the prompt, then connect that Text and the real media references to
+the low-level Seedance Surface.
```svml
-<speaker:Reference image={presenter-clean} role="character-and-scene"/>
-<speaker:Reference audio={presenter-voice} role="voice-timbre"/>
+<import as="text" from="@narratage/text@1"/>
+<import as="seedance" from="@narratage/seedance@1"/>
+<import as="broll-kit" source="../../packages/seedance-kits/kits/broll-v1.svs"/>
+
+<text:Render id="demo-prompt"
+ template={broll-kit.broll-v1}
+ recipe={studio.broll.product-demo}>
+ <text:Set name="story" text={copy.product-demo}/>
+</text:Render>
+
+<seedance:ReferenceVideo id="demo" model="mini"
+ prompt={demo-prompt}
+ duration={demo-duration.duration}
+ resolution="720p"
+ aspect-ratio="9:16"
+ generate-audio="false">
+ <seedance:Reference image={scene}/>
+ <seedance:Reference image={product}/>
+</seedance:ReferenceVideo>
```
-| Attribute | Required | Description |
-|---|---|---|
-| `image` | one of image/audio | Reference to a `media:Image` |
-| `audio` | one of image/audio | Reference to a `media:Audio` |
-| `role` | yes | Reference purpose: `character-and-scene`, `voice-timbre` |
+The project Recipe selects axes such as `material-mode`, `story-shape` and `camera-language`.
+`text:Render` reads only properties declared by the template; an explicit `text:Param` overrides a
+Recipe value. Dynamic story/dialogue/action/extra content remains a `Text` edge through `Set`.
-**Output:** `{hook-take.video}` — the generated video, passed to `speech:Spine`.
+Available templates are `speaker-v1`, `broll-v1`, `podcast-v1`, `call-v1`, `street-interview-v1`,
+`motion-reference-v1` and `camera-reference-v1`. Podcast and Call expect two ordered image
+references plus two ordered audio references; Street Interview expects one scene image plus two
+ordered voices; the two reference-transfer templates expect one subject image and one reference
+video. Those shapes are visible in `seedance:ReferenceVideo`, not hidden in Kit execution code.
-### Prompt Kits
+## Talking-head prompt assembly
-A Prompt Kit is a special SVS file that defines a structured prompt template with ordered blocks,
-variant choices, axis parameters, and slots. The official kit is at
-`packages/seedance-speaker/kits/official-ugc-v1.svs`.
+Talking-head authoring does not need a special executable component. The data-only `speaker-v1`
+Template, the project's Recipe and the per-take dialogue/action are assembled by the ordinary Text
+module. The result enters Seedance through the same explicit `prompt` edge as any other generation.
-The project Recipe selects axes such as `material-mode`, `story-shape` and `camera-language`.
-The template reads only declared properties; explicit parameters override Recipe values.
+```svml
+<import as="text" from="@narratage/text@1"/>
+<import as="seedance" from="@narratage/seedance@1"/>
+<import as="speaker-kit" source="../../packages/seedance-kits/kits/speaker-v1.svs"/>
+
+<text:Value id="hook-action">
+ Begin with urgent direct eye contact, then let the final admission land more quietly.
+</text:Value>
+
+<text:Render id="hook-prompt"
+ template={speaker-kit.speaker-v1}
+ recipe={studio.speaker.host}>
+ <text:Set name="dialogue" text={story.segment.hook.dialogue}/>
+ <text:Set name="action" text={hook-action}/>
+</text:Render>
+
+<seedance:ReferenceVideo id="hook-take" model="mini"
+ prompt={hook-prompt}
+ duration={hook-duration.duration}
+ resolution="720p" aspect-ratio="9:16" generate-audio="true">
+ <seedance:Reference image={presenter-clean}/>
+ <seedance:Reference audio={presenter-voice}/>
+</seedance:ReferenceVideo>
+```
+
+`speaker-v1.svs` selects its own Text Template Frontend. `studio.svs` supplies the named axis values;
+`dialogue` and `action` remain ordinary graph inputs. Neither the Kit nor Text chooses a model,
+reference media or generation endpoint.
## Combination example
-A four-take setup with estimated durations feeding into `speaker:Take` generation:
+A two-take setup with estimated durations feeding explicit Text assembly and Seedance generation:
```svml
<import as="media" from="@narratage/media@1"/>
<import as="estimate" from="@narratage/estimate@1"/>
-<import as="speaker" from="@narratage/seedance-speaker@1"/>
+<import as="text" from="@narratage/text@1"/>
+<import as="seedance" from="@narratage/seedance@1"/>
<import as="studio" source="./studio.svs"/>
-<import as="ugc" source="../../packages/seedance-speaker/kits/official-ugc-v1.svs"/>
+<import as="speaker-kit" source="../../packages/seedance-kits/kits/speaker-v1.svs"/>
<media:Image id="presenter-clean" src="./assets/presenter-clean.png"/>
<media:Image id="presenter-alt" src="./assets/presenter-alt.png"/>
@@ -240,40 +276,30 @@ A four-take setup with estimated durations feeding into `speaker:Take` generatio
source={story.segment.hook.speech} policy={studio.speech.normal}/>
<estimate:Speech id="meeting-duration"
source={story.segment.meeting.speech} policy={studio.speech.normal}/>
-<estimate:Speech id="evidence-duration"
- source={story.segment.evidence.speech} policy={studio.speech.normal}/>
-<estimate:Speech id="payoff-duration"
- source={story.segment.payoff.speech} policy={studio.speech.normal}/>
-
-<speaker:Take id="hook-take" dialogue={story.segment.hook.dialogue}
- duration={hook-duration.duration} recipe={studio.speaker.host}
- kit={ugc.official-ugc-v1}>
- <speaker:Reference image={presenter-clean} role="character-and-scene"/>
- <speaker:Reference audio={presenter-voice} role="voice-timbre"/>
-</speaker:Take>
-
-<speaker:Take id="meeting-take" dialogue={story.segment.meeting.dialogue}
- duration={meeting-duration.duration} recipe={studio.speaker.host}
- kit={ugc.official-ugc-v1}>
- <speaker:Reference image={presenter-alt} role="character-and-scene"/>
- <speaker:Reference audio={presenter-voice} role="voice-timbre"/>
-</speaker:Take>
-
-<speaker:Take id="evidence-take" dialogue={story.segment.evidence.dialogue}
- duration={evidence-duration.duration} recipe={studio.speaker.host}
- kit={ugc.official-ugc-v1}>
- <speaker:Reference image={presenter-alt} role="character-and-scene"/>
- <speaker:Reference audio={presenter-voice} role="voice-timbre"/>
-</speaker:Take>
-
-<speaker:Take id="payoff-take" dialogue={story.segment.payoff.dialogue}
- duration={payoff-duration.duration} recipe={studio.speaker.host}
- kit={ugc.official-ugc-v1}>
- <speaker:Reference image={presenter-clean} role="character-and-scene"/>
- <speaker:Reference audio={presenter-voice} role="voice-timbre"/>
-</speaker:Take>
+<text:Value id="hook-action">Start urgently, then become quieter.</text:Value>
+<text:Value id="meeting-action">Indicate the product, then return to the lens.</text:Value>
+
+<text:Render id="hook-prompt" template={speaker-kit.speaker-v1} recipe={studio.speaker.host}>
+ <text:Set name="dialogue" text={story.segment.hook.dialogue}/>
+ <text:Set name="action" text={hook-action}/>
+</text:Render>
+<text:Render id="meeting-prompt" template={speaker-kit.speaker-v1} recipe={studio.speaker.host}>
+ <text:Set name="dialogue" text={story.segment.meeting.dialogue}/>
+ <text:Set name="action" text={meeting-action}/>
+</text:Render>
+
+<seedance:ReferenceVideo id="hook-take" model="mini" prompt={hook-prompt}
+ duration={hook-duration.duration} resolution="720p" aspect-ratio="9:16" generate-audio="true">
+ <seedance:Reference image={presenter-clean}/>
+ <seedance:Reference audio={presenter-voice}/>
+</seedance:ReferenceVideo>
+<seedance:ReferenceVideo id="meeting-take" model="mini" prompt={meeting-prompt}
+ duration={meeting-duration.duration} resolution="720p" aspect-ratio="9:16" generate-audio="true">
+ <seedance:Reference image={presenter-alt}/>
+ <seedance:Reference audio={presenter-voice}/>
+</seedance:ReferenceVideo>
```
-Each `speaker:Take` produces a `{*.video}` output that feeds into `speech:Spine` in the next stage.
-Different takes can use different reference images (e.g. the presenter holding a product in some
-Segments but not others) while sharing the same voice timbre and generation recipe.
+Each `seedance:ReferenceVideo` produces a `{*.video}` output that feeds into `speech:Spine` in the
+next stage. Different takes can use different reference images while sharing the same voice timbre
+and prompt Recipe.
diff --git a/docs/quickstart/script.md b/docs/quickstart/script.md
index 79cfa4b8..1f9e598e 100644
--- a/docs/quickstart/script.md
+++ b/docs/quickstart/script.md
@@ -77,10 +77,9 @@ Role Cues produce different text projections:
| **speech** | `What time is it?`<br>`It's 8:30.` |
| **caption** | `What time is it?`<br>`It's 8:30.` |
-The dialogue `Text` includes Role Cue prefixes. Speech `Text` and caption projection strip them.
-Prompt programs feeding `seedance:ReferenceVideo` may use `{story.segment.dialogue.dialogue}` (with labels). Script also
-emits `{story.caption}` as the ordered display Atom/Word universe and
-`{story.caption.correspondence}` as the separate Atom-to-speech edge used only when timing joins.
+The dialogue projection includes Role Cue prefixes. Speech and caption projections strip them.
+Components like `seedance:Speech` use `{story.segment.dialogue.dialogue}` (with labels) while
+`caption:Track` uses the caption projection (without labels).
## Dual Text
diff --git a/docs/quickstart/timing.md b/docs/quickstart/timing.md
index 2c8cb413..2f51da57 100644
--- a/docs/quickstart/timing.md
+++ b/docs/quickstart/timing.md
@@ -33,7 +33,7 @@ program order — the final sequence of Segments in the finished video.
| Attribute | Required | Description |
|---|---|---|
| `id` | yes | Unique identifier |
-| `canvas` | yes | CanvasSpace used explicitly by constrained Media visual projections |
+| `canvas` | yes | Explicit CanvasSpace used by the restricted Media visual projection |
### speech:Take
@@ -41,7 +41,7 @@ Each `<speech:Take>` child binds a generated video to a Script Segment:
| Attribute | Required | Description |
|---|---|---|
-| `source` | yes | Generated video — from `seedance:Speech`, `speaker:Take`, etc. |
+| `source` | yes | Generated video — for example, from `seedance:ReferenceVideo` |
| `segment` | yes | Script Segment this take corresponds to — e.g. `{story.segment.hook}` |
The order of `<speech:Take>` children **determines the program order**. The first take starts at
@@ -77,7 +77,7 @@ This produces the **SemanticMap** — the bridge between Script text and physica
| Output | Type | Used by |
|---|---|---|
-| `{timing.map}` | CompleteSemanticMap | `caption-fine:Track`, `media-track:Track`, `text:Track` — timed placement |
+| `{timing.map}` | CompleteSemanticMap | Caption Style-family Tracks, `media-track:Track`, `text:Track` — timed placement |
The SemanticMap maps every authored Script anchor to a time point. It covers all `2M + 2N` identities
(where M = total speech tokens, N = number of Segments). This is how Selections and Moments declared
@@ -107,7 +107,7 @@ Every component that operates in the time domain takes a `space` attribute point
## SemanticMap
The SemanticMap is the typed bridge between Script text and physical time. When you write
-`during={story.selection.demo}` on a Media item, the component uses the SemanticMap to look up the
+`during={story.selection.demo}` on a Media Item, the component uses the SemanticMap to look up the
exact frame range that Selection covers. Without a SemanticMap, Selections and Moments have no
physical meaning.
@@ -118,10 +118,10 @@ Components that use the map take it via the `map` attribute:
<caption-fine:Track id="captions" ... map={timing.map} .../>
```
-The Map contains only the final word windows and semantic anchors — it does not propagate
-"measured, derived, estimated" labels. WhisperX Evidence and the deterministic M:N aligner are
-responsible for making full use of recorded evidence; downstream Tracks receive one complete Map
-and no longer interpret how each point was obtained.
+The map contains final token windows and semantic anchor points only. It does not propagate
+`measured`, `derived` or `estimated` labels. WhisperX evidence and the deterministic M:N aligner are
+responsible for using the available recording evidence; downstream Tracks receive one complete map
+and do not reinterpret how each point was obtained.
## Combination example
@@ -152,7 +152,7 @@ The complete timing stage, from generated takes to map and space:
The data flow:
```text
-speaker:Take outputs ──► speech:Spine ──► whisperx:Alignment
+generated video(s) ─────► speech:Spine ──► whisperx:Alignment
│ │
.visual .map (SemanticMap)
.audio │
diff --git a/docs/quickstart/tracks.md b/docs/quickstart/tracks.md
index 1055122c..5cbcf3ec 100644
--- a/docs/quickstart/tracks.md
+++ b/docs/quickstart/tracks.md
@@ -5,6 +5,10 @@ description: Visual track components — captions, media overlays and typography
# Caption, Media & Typography
+> **Pre-release note:** Caption Fine, Media Track and Typography Track execute their declared author Surfaces.
+> Their author APIs may still evolve; the shared terminal Track/Visual IR waist is frozen inside the
+> repository but has not been published as an npm ABI.
+
Every audiovisual contribution entering the final composition is a peer **Track**. Tracks are flat
(no nesting), and their z-order is determined by the `stack-order` property in SVS. This page
covers three official visual Track packages: captions, media, and typography overlays.
@@ -21,6 +25,7 @@ Script Display → Caption Program → Planner + measured Atom timing → Style-
<import as="caption" from="@narratage/caption@1"/>
<import as="caption-fine" from="@narratage/caption-fine@1"/>
<import as="caption-ai" from="@narratage/caption-gemini@1"/>
+<import as="media" from="@narratage/media@1"/>
<import as="fonts" from="@narratage/fonts-open@1"/>
```
@@ -33,29 +38,97 @@ family: it owns geometry, glyph/Cue/Pill Paint and layered local motion.
A Style is one indivisible pair of planning requirements and rendering parameters. Fine resolves
both from one package-owned SVS Recipe:
+```svs
+caption.primary {
+ cue-min-words: 2;
+ cue-max-words: 7;
+ stack-order: 70; x: 0.5; y: 0.88; width: 0.84;
+ anchor-x: center; anchor-y: bottom;
+ font: Inter; weight: 700; size: 58; font-style: normal;
+ line-height: 0.96; letter-spacing: -0.5; word-gap: 14;
+ align: center; direction: ltr;
+ fill: #FFFFFF; opacity: 1;
+ stroke-color: #09090B; stroke-width: 2;
+ shadow-color: #000000; shadow-opacity: 0.72;
+ shadow-x: 0; shadow-y: 3; shadow-blur: 8;
+ glow-color: #FFFFFF; glow-opacity: 0.12; glow-blur: 8;
+ gradient-from: #FFFFFF; gradient-to: #93C5FD; gradient-angle: 120;
+ long-shadow-color: #111827; long-shadow-opacity: 0.35;
+ long-shadow-distance: 8; long-shadow-angle: 45;
+ background: #09090BCC; border-color: #FFFFFF20; border-width: 1;
+ padding: 16 24; radius: 18;
+ karaoke: trail; karaoke-transition: wipe;
+ active-fill: #FFD54A;
+ active-box: current; active-box-continuity: isolated;
+ active-box-background: #FFD54ACC; active-box-padding: 4 8; active-box-radius: 8;
+ active-underline: current; active-underline-color: #FFFFFF;
+ active-underline-thickness: 3; active-underline-offset: 5;
+ cue-enter: fade; cue-enter-frames: 4; cue-exit: fade; cue-exit-frames: 4;
+ atom-reveal: all;
+ active-response: pop; active-response-frames: 5; active-scale: 1.08;
+}
+```
+
```svml
-<fonts:Stack id="caption-fonts" family="inter" weight="700" style="normal"/>
+<fonts:Stack id="caption-fonts" family="inter" weight="700" style="normal" emoji="color">
+ <fonts:Fallback family="noto-sans-sc" weight="700" style="normal"/>
+</fonts:Stack>
<caption-fine:Style id="primary-caption" recipe={studio.caption.primary}
font={caption-fonts}/>
```
-The required `font=` edge carries one byte-reproducible `FontStackRef`. Fine rejects a Style
+The required `font=` edge carries one byte-reproducible `FontStackRef`. The primary face must match
+the Recipe's weight/style; each fallback retains its own exact face metadata. Fine rejects a Style
without that stack instead of falling back to machine fonts.
+Another Caption package may define completely different planning fields and visual parameters
+without changing the common package.
+
+Fine's properties are orthogonal: Cue planning; normalized placement and anchor; layout and
+typography; base/active solid or gradient glyph Paint; stroke, shadow, directional long shadow,
+glow and underline; Cue/Pill Paint; three independent glyph/Pill/underline activation channels;
+and layered Cue, Atom, active-response and loop motion. Missing optional dimensions resolve
+deterministically to no decoration or motion. Unknown properties are rejected.
+
+`karaoke` is `off`, `current` or `trail`; `karaoke-transition` is `step` or `wipe`. Timing is always
+whole-Atom timing already proven by Caption. A normal one-word Atom therefore highlights per word,
+while a Dual Text Atom remains one indivisible visible unit. Fine never guesses internal time.
+
+`active-box` is independently `off`, `current` or `trail`. `active-box-continuity: isolated` paints
+one capsule per activated Atom; `joined` turns a trail into one ordered prefix whose background is
+continuous on each real browser line. Thus trail-colored text with a current-only Pill, the original
+Twinit behavior, is one Recipe—not a second renderer.
+
+Fine wraps only between complete Atoms and never clips author text. It intentionally has no
+`max-lines`; use Cue bounds, Track width and font size to control density.
+
+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
+word for a bare symbol.
+
### caption:Program
The Program starts from the complete ordered display-word universe emitted by Script. One explicit
-default Style covers every word.
+default Style covers every word; no `@whole` Selection or complement is required. Ordered `Use`
+rules replace the whole Style on a Role or explicit Caption word subset, with the last match winning.
```svml
<caption:Program id="caption-program" display={story.caption}
default={primary-caption}>
<caption:Use role="ALICE" style={alice-caption}/>
<caption:Use role="BOB" style={bob-caption}/>
+ <caption:Use words={story.caption.selection.product-demo}
+ style={dialogue-caption}/>
<caption:Mute words={story.caption.selection.private}/>
</caption:Program>
```
+`role=` is convenient author syntax for a word subset, not a temporal condition. `words=` consumes
+the Caption-specific projection of a Script Selection; the public time Selection remains only a
+pair of semantic anchors. Partial ownership of an indivisible Dual Text display word is rejected.
+`Mute` uses that same exact word projection, stays out of Gemini, and hides those complete Atoms
+after Cue planning without regrouping the Cue.
+
### caption-ai:Planner
```svml
@@ -64,7 +137,9 @@ default Style covers every word.
```
The planner receives immutable display Atoms/Words and already-resolved Style runs. It may only cut
-each run between whole Atoms and attach declared fields to Word ids. Fine declares no fields.
+each run between whole Atoms and attach declared fields to Word ids. Fine declares no fields. The
+planner cannot rewrite text, select Styles, see audio or invent time. Its output is
+`{caption-plan.plan}`.
### caption-fine:Track
@@ -76,14 +151,15 @@ each run between whole Atoms and attach declared fields to Word ids. Fine declar
The common Caption timing step joins the Plan to the independent SemanticMap. Fine then renders all
default and override Styles into one ordinary peer `VisualTrack`: `{captions.track}`.
-## Media overlays
+## Media overlays and B-roll
-One Item can place a normalized image, video, animation or compositable Surface at a semantic or
-absolute window.
+B-roll is an editorial use of the generic Media Track, not a separate Track family. One Item can
+place a normalized image, video, animation or compositable Surface at a semantic or absolute window.
```svml
<import as="pipeline" from="@narratage/media-pipeline@1"/>
<import as="media-track" from="@narratage/media-track@1"/>
+<import as="wording" from="@narratage/text@1"/>
```
### media-track:Track and media-track:Item
@@ -91,6 +167,16 @@ absolute window.
Placement is an explicit Spatial Frame edge; appearance and motion remain reusable SVS values.
```svml
+<wording:Value id="product-direction">
+ A clean vertical product film: the written script becomes semantic regions,
+ then those regions assemble into a finished video.
+</wording:Value>
+
+<seedance:ReferenceVideo id="product-motion" model="mini"
+ prompt={product-direction} duration="5">
+ <seedance:Reference image={product-reference}/>
+</seedance:ReferenceVideo>
+
<pipeline:Normalize id="product-media" source={product-motion.video}
video="primary-moving" audio="none" span-authority="video" frame-rate="30"/>
@@ -106,7 +192,9 @@ Placement is an explicit Spatial Frame edge; appearance and motion remain reusab
</media-track:Track>
```
-The same Item model covers full-canvas cutaways, split screens and corner overlays.
+The Selection contributes semantic points; Media performs the package-owned window projection.
+The same Item model also covers full-canvas cutaways, split screens and corner overlays. Ordered
+child layers, source occupancy and explicit Sequences are available when one source is not enough.
**Outputs:** `{product-broll.visual}` and, only when explicitly authored, `{product-broll.audio}`.
@@ -116,6 +204,7 @@ Static or timed text displayed on screen — titles, callouts, lower thirds.
```svml
<import as="text" from="@narratage/typography-track@1"/>
+<import as="wording" from="@narratage/text@1"/>
```
### text:Track
@@ -123,6 +212,7 @@ Static or timed text displayed on screen — titles, callouts, lower thirds.
Container for text items.
```svml
+<space:Canvas id="vertical" width="1080" height="1920"/>
<space:Frame id="title-frame" within={vertical}
left="6%" top="6%" right="6%" bottom="84%"/>
<fonts:Stack id="title-font" family="inter" weight="900" style="normal"/>
@@ -140,9 +230,10 @@ Container for text items.
| `space` | yes | ProgramSpace from `speech:Spine` |
| `map` | no | SemanticMap — needed when items use Selection-based timing |
-### text:Area
+### text:Point, text:Area and text:Path
-Places flowing text inside a `SpatialFrame`:
+Each item has one explicit placement form, one exact Style and one temporal projection. `Area`
+places flowing text inside a `SpatialFrame`:
```svml
<text:Area id="meaning" placement={title-frame} style={title-style} during="program">
@@ -153,16 +244,42 @@ Places flowing text inside a `SpatialFrame`:
| Attribute | Required | Description |
|---|---|---|
| `id` | yes | Stable item identity |
-| child content or `content` | yes | Inline plain/rich content, or an ordinary graph `Text` reference |
-| `during` | yes | `"program"` or a Selection reference |
-| `placement` | yes | A `SpatialFrame` |
+| child content or `content` | yes | Inline plain/rich content, or an ordinary graph `Text` reference; the two forms are exclusive |
+| `during` | yes | `"program"` or a Selection reference; `at` and explicit `start`/`end` are also available |
+| `placement` | yes | `SpatialPoint`, `SpatialFrame` or `SpatialPath`, matching the item form |
| `style` | yes | A `text:Style` compiled from an SVS Recipe plus exact font bytes |
+The `during` attribute accepts either the literal string `"program"` for the complete ProgramSpace,
+or a Selection reference for semantic timing:
+
+```svml
+<text:Style id="callout-style" recipe={studio.text.callout} font={title-font}/>
+<text:Track id="callout" space={speech.space} map={timing.map}>
+ <text:Area id="callout-copy" placement={callout-frame}
+ style={callout-style} during={story.selection.callout}>
+ EXACTLY THE RIGHT MOMENT
+ </text:Area>
+</text:Track>
+```
+
+Graph-produced copy remains visible as an edge:
+
+```svml
+<wording:Value id="headline">EXACTLY THE RIGHT MOMENT</wording:Value>
+<text:Track id="callout" space={speech.space}>
+ <text:Area id="callout-copy" content={headline}
+ placement={callout-frame} style={callout-style} during="program"/>
+</text:Track>
+```
+
+The generic Text value supplies only characters. Typography still owns the item document wrapper,
+placement, timing, style and motion. Use inline `P`/`Span`/`Break` when the author needs rich runs.
+
**Output:** `{titles.track}` — a VisualTrack added to `film:Film`.
## Combination example
-All three track types together:
+All three track types together in one source file:
```svml
<import as="caption" from="@narratage/caption@1"/>
@@ -174,14 +291,9 @@ All three track types together:
<import as="text" from="@narratage/typography-track@1"/>
<import as="space" from="@narratage/spatial@1"/>
-<space:Canvas id="vertical" width="1080" height="1920"/>
-<space:Frame id="title-frame" within={vertical}
- left="6%" top="6%" right="6%" bottom="84%"/>
-<space:Frame id="card-frame" within={vertical}
- left="10%" top="20%" right="10%" bottom="30%"/>
-
-<!-- Captions -->
+<!-- Captions: primary style for all text -->
<fonts:Stack id="caption-font" family="inter" weight="700" style="normal"/>
+<fonts:Stack id="title-font" family="inter" weight="900" style="normal"/>
<caption-fine:Style id="base-caption" recipe={studio.caption.base} font={caption-font}/>
<caption:Program id="caption-program" display={story.caption} default={base-caption}/>
<caption-ai:Planner id="cue-plan" display={story.caption}
@@ -189,7 +301,14 @@ All three track types together:
<caption-fine:Track id="captions" display={story.caption} correspondence={story.caption.correspondence} map={timing.map}
space={speech.space} plan={cue-plan.plan} program={caption-program}/>
-<!-- Media overlay -->
+<!-- Shared placement is an explicit edge, separate from Text appearance. -->
+<space:Canvas id="vertical" width="1080" height="1920"/>
+<space:Frame id="title-frame" within={vertical}
+ left="6%" top="6%" right="6%" bottom="84%"/>
+<space:Frame id="card-frame" within={vertical}
+ left="10%" top="20%" right="10%" bottom="30%"/>
+
+<!-- Media: one ordinary Item used editorially as B-roll -->
<pipeline:Normalize id="motion-media" source={motion.video}
video="primary-moving" audio="none" span-authority="video" frame-rate="30"/>
<media-track:Track id="cards" map={timing.map} space={speech.space} canvas={vertical}>
@@ -197,14 +316,22 @@ All three track types together:
during={story.selection.demo} appearance={studio.media.card} motion={studio.motion.card}/>
</media-track:Track>
-<!-- Text overlay -->
-<fonts:Stack id="title-font" family="inter" weight="900" style="normal"/>
+<!-- Text: persistent title overlay -->
<text:Style id="title-style" recipe={studio.text.title} font={title-font}/>
<text:Track id="titles" space={speech.space}>
<text:Area id="meaning" placement={title-frame} style={title-style} during="program">
MEANING
</text:Area>
</text:Track>
+
+<!-- All three tracks feed into Film -->
+<film:Film id="main" canvas={vertical} space={speech.space} appearance={studio.film.vertical}>
+ <film:Track source={speech.visual}/>
+ <film:Track source={speech.audioTrack}/>
+ <film:Track source={cards.visual}/>
+ <film:Track source={captions.track}/>
+ <film:Track source={titles.track}/>
+</film:Film>
```
The `stack-order` in each SVS Recipe determines z-ordering: speech visual at 10, media at 40,
diff --git a/docs/zh/guide/develop.md b/docs/zh/guide/develop.md
index d743477c..15d3e2f0 100644
--- a/docs/zh/guide/develop.md
+++ b/docs/zh/guide/develop.md
@@ -10,18 +10,19 @@ description: 开始 Narratage 开发工作。
| 工具 | 版本 | 用于 |
|---|---|---|
| Node.js | 22+ | 所有工作 |
-| pnpm | 9+ | workspace 管理 |
+| pnpm | 10.33.x | workspace 管理;由根目录 `packageManager` 字段选择 |
| Python | 3.10–3.13 | WhisperX 与 OpenCV [本地服务](./services.md) |
| uv | latest | Python 环境管理 |
| ffmpeg / ffprobe | 较新的稳定版 | 媒体处理 |
-| Chrome / Chromium | 较新的稳定版 | HyperFrames 渲染 |
+| Chrome / Chromium | 由 HyperFrames 管理 | 本地 HyperFrames 渲染 |
只有 Node.js 与 pnpm 是硬性要求。其余都只在跑真实 Builds 时才需要。
## 日常工作流
```bash
-pnpm install # 拉取代码或改动依赖之后
+corepack enable
+pnpm install --frozen-lockfile # 拉取代码或改动依赖之后
pnpm check # TypeScript 类型检查
pnpm test # 完整测试套件
```
@@ -29,7 +30,7 @@ pnpm test # 完整测试套件
| 命令 | 实际执行什么 |
|---|---|
| `pnpm check` | `tsc -p tsconfig.json --noEmit` |
-| `pnpm test` | `node --import tsx --test 'packages/*/test/**/*.test.ts' 'tools/*.test.mjs'` |
+| `pnpm test` | 通过 Node test runner 运行 package、service-adapter 与仓库边界测试 |
关于受环境开关控制的测试与测试写法,参见[测试](./testing.md)。
@@ -37,7 +38,7 @@ pnpm test # 完整测试套件
```text
narratage/
-├── packages/ 86 workspace packages
+├── packages/ 82 workspace packages
├── spec/ 16 normative specification documents
├── docs/ VitePress documentation site
├── examples/ runnable example sources
diff --git a/docs/zh/guide/packages.md b/docs/zh/guide/packages.md
index aa351bca..b6752e67 100644
--- a/docs/zh/guide/packages.md
+++ b/docs/zh/guide/packages.md
@@ -70,7 +70,6 @@ Sticker、Deck 或任何模型家族。
@narratage/model-kit model family abstractions
@narratage/seedance Seedance model family + author Surface
@narratage/seedance-kits 数据化的 Seedance 语义 Text Template
-@narratage/seedance-speaker Seedance Speaker binding
@narratage/minimax-h3 MiniMax H3 model family
@narratage/gemini-omni Gemini Omni model family
@narratage/grok-imagine Grok Imagine model family
@@ -98,7 +97,6 @@ Sticker、Deck 或任何模型家族。
@narratage/deck-track depth-stack collection Track
@narratage/ranking four ranking component families
@narratage/screen-overlay self-contained full-canvas overlays
-@narratage/comment-sticker 锚定评论贴纸叠加
@narratage/film Film composition
@narratage/composition peer Track composition
@narratage/visual-ir renderer-neutral visual vocabulary
@@ -125,7 +123,7 @@ Sticker、Deck 或任何模型家族。
@narratage/provider-hyperframes-aws-lambda recoverable distributed rendering
@narratage/provider-image-opencv-local 本地 OpenCV 光栅执行
@narratage/provider-media-aws-lambda synchronous AWS media execution
-@narratage/provider-xiaomi-mimo Xiaomi 官方 MiMo TTS API
+@narratage/provider-xiaomi-mimo Xiaomi 官方 MiMo TTS API
```
### Layer 5:应用层
@@ -143,7 +141,7 @@ Sticker、Deck 或任何模型家族。
2. **领域无关闭包。** 每个 Layer 1 包的传递闭包只包含 Layer 1 的包。`@narratage/core` 只依赖 `@narratage/protocol`。
-3. **CLI 独立性。** `@narratage/cli` 和 `@narratage/video-cli` 都不会传递依赖任何 Provider 包。video CLI 同样不依赖任何作者层的视频包(`@narratage/script`、`@narratage/seedance-speaker`、`@narratage/media-track`、`@narratage/typography-track`、`@narratage/film`)。作者包通过显式的 package lock 被 activate,而不是通过编译期的 CLI 依赖。
+3. **CLI 独立性。** `@narratage/cli` 和 `@narratage/video-cli` 都不会传递依赖任何 Provider 包。video CLI 同样不依赖任何作者层的视频包(`@narratage/script`、`@narratage/seedance`、`@narratage/media-track`、`@narratage/typography-track`、`@narratage/film`)。作者包通过显式的 package lock 被 activate,而不是通过编译期的 CLI 依赖。
## 包的结构
diff --git a/docs/zh/guide/playground.md b/docs/zh/guide/playground.md
index 6f312731..bf6beafa 100644
--- a/docs/zh/guide/playground.md
+++ b/docs/zh/guide/playground.md
@@ -20,12 +20,13 @@ pnpm playground
|---|---|
| 组件下拉 | 所有能在画面上产生像素的模块 |
| W / H / fps / sec | 画布与帧域 |
-| Canvas from a stylesheet | 采用某个 `.svs` 的画幅 |
+| Appearance from a stylesheet | 采用某个 `.svs` Film Recipe 的背景 |
| 输入表单 | 组件每个输入各一份 |
| 刻度条 | 帧精确,计数显示为 `当前帧 / 末帧` |
-预览的是真实结果。跑的是各组件自己的渲染器,再由 `compileHyperframesDocument` 产出与
-Build 相同的文档。
+预览运行的是已安装模块真正的 Producer handler。例如 Fine Caption、Media Track、
+Screen Overlay、Speech Basis 和 Typography Track 都会降低为 `VisualTrack`,再由
+`compileHyperframesDocument` 产出与 Build 相同的文档。
## 它不维护任何清单
@@ -63,13 +64,14 @@ Playground 里没有组件列表。它读取各 manifest,把所有声明了「
`format: "digest"` 的字段接受一个文件。Playground 用 SHA-256 计算并注册真实的内容寻址标识——
编译产出的文档会交叉校验每一个 Artifact 引用,占位值会被拒绝。
-因此绘制外部素材的模块(媒体轨道项、说话人画面)**没有默认值**:模块手里没有那些字节,与其编造一个
+因此绘制外部素材的模块(B-roll、说话人画面)**没有默认值**:模块手里没有那些字节,与其编造一个
digest,不如什么都不说。在你选择文件之前这些组件不画任何东西,这是一个可以经过的状态,不是错误。
## 样式表
-选择 `.svs` 文件**只读其中的 Film Recipe**,且只用于画幅。指向某个 studio 样式表,画布就会
-变成其配置的尺寸和背景色。
+选择 `.svs` 文件**只读其中的 Film Recipe**,且只用于 Film 外观。指向
+`examples/talking-film-golden/studio.svs`,预览会采用该 Recipe 的背景色;画布尺寸与时间仍由
+预览环境的显式控件决定。
表里其余内容一概不读。组件长什么样由拥有它的模块决定,而不是由 Playground 恰好打开的某张样式表决定。
diff --git a/docs/zh/quickstart.md b/docs/zh/quickstart.md
index c5ea0ddb..c2d7df65 100644
--- a/docs/zh/quickstart.md
+++ b/docs/zh/quickstart.md
@@ -11,14 +11,15 @@ Glory*》的一篇影评。那位影评人造出这个词,用来描述当时
这套系统做的正是这件事。作者写下带有语义锚点的口播 Script,编译器则把生成的视频、字幕、B-roll、
文字与音频组装成一部完成的影片。Author Source 使用 SVML(Semantic Video Markup Language)编写,
-扩展名为 `.svml`;工作区包则发布在 `@narratage` 作用域下。
+扩展名为 `.svml`;当前工作区的开发包预留 `@narratage` 作用域,但尚未发布到 npm。
## 安装
需要 Node.js 22+ 与 pnpm。
```bash
-pnpm install
+corepack enable
+pnpm install --frozen-lockfile
pnpm check
pnpm test
```
@@ -38,7 +39,7 @@ Author Source 说明*做什么*。Run Source 说明*要哪些*。Runtime Profile
## 第一次图检查
`talking-film-graph-check` 示例会编译一张完整的视频图 —— Script、Seedance、Speech、
-WhisperX、Gemini Caption、Media Track、Text、Film、HyperFrames —— 全程不调用任何外部服务。
+WhisperX、Gemini Caption、B-roll、Text、Film、HyperFrames —— 全程不调用任何外部服务。
```bash
pnpm narratage check examples/talking-film-graph-check/main.svml \
@@ -56,10 +57,9 @@ pnpm narratage plan examples/talking-film-graph-check/build.svrun \
| 指南 | 主题 |
|---|---|
| [Script](./quickstart/script.md) | Segment、Role Cue、Dual Text、Selection、Moment、文字投影 |
-| [SVS 样式表](./quickstart/styles.md) | CSS 风格的 Recipe:film、caption、media、text、speech、字体 |
-| [媒体与生成](./quickstart/generation.md) | media:Image、media:Audio、estimate:Speech、Seedance、speaker:Take |
+| [SVS 样式表](./quickstart/styles.md) | CSS 风格的 Recipe:film、caption、B-roll、text、speech、字体 |
+| [媒体与生成](./quickstart/generation.md) | media:Image、media:Audio、estimate:Speech、Text Template、Seedance |
| [时序与装配](./quickstart/timing.md) | speech:Spine、whisperx:Alignment、ProgramSpace、SemanticMap |
| [字幕、Media 与文字](./quickstart/tracks.md) | caption-fine:Style/Track、caption:Program、Planner、Media Track 与 Text |
| [Film 与渲染](./quickstart/composition.md) | film:Film、render:Video、完整流水线演练 |
| [Run Source 与 Build](./quickstart/run.md) | .svrun 语法、targets、复用、runtime profile、build 工作流 |
-
diff --git a/docs/zh/quickstart/composition.md b/docs/zh/quickstart/composition.md
index 078e6caa..9dc37ac9 100644
--- a/docs/zh/quickstart/composition.md
+++ b/docs/zh/quickstart/composition.md
@@ -52,7 +52,7 @@ Composition。然后渲染器将该 Composition 编译为 MP4 视频。
| `{speech.visual}` | VisualTrack | `speech:Spine`——全屏说话人画面 |
| `{speech.audioTrack}` | AudioTrack | `speech:Spine`——同步音频 |
| `{captions.track}` | VisualTrack | Caption 样式族 Track——定时字幕 |
-| `{cards.visual}` | VisualTrack | `media-track:Track`——Media 叠加层 |
+| `{cards.visual}` | VisualTrack | `media-track:Track`——Media 叠加层或 B-roll |
| `{titles.track}` | VisualTrack | `text:Track`——文字叠加层 |
### Track 堆叠
diff --git a/docs/zh/quickstart/generation.md b/docs/zh/quickstart/generation.md
index f97b4a56..224567aa 100644
--- a/docs/zh/quickstart/generation.md
+++ b/docs/zh/quickstart/generation.md
@@ -11,9 +11,11 @@ description: 声明媒体资源并使用 Seedance 生成视频。
```svml
<import as="media" from="@narratage/media@1"/>
+<import as="mediaop" from="@narratage/media-pipeline@1"/>
<import as="estimate" from="@narratage/estimate@1"/>
+<import as="text" from="@narratage/text@1"/>
<import as="seedance" from="@narratage/seedance@1"/>
-<import as="speaker" from="@narratage/seedance-speaker@1"/>
+<import as="speaker-kit" source="../../packages/seedance-kits/kits/speaker-v1.svs"/>
```
## media:Image
@@ -29,7 +31,7 @@ description: 声明媒体资源并使用 Seedance 生成视频。
| `id` | 是 | 组件的唯一标识符 |
| `src` | 是 | 图片文件路径,相对于 `.svml` 源文件 |
-该图片在下游通过 `{presenter}` 引用——例如,作为 `seedance:Speech` 中的角色参考或作为 B-roll 来源。
+该图片在下游通过 `{presenter}` 引用——例如,作为 `seedance:ReferenceVideo` 中的角色参考或作为 B-roll 来源。
## media:Audio
@@ -44,11 +46,11 @@ description: 声明媒体资源并使用 Seedance 生成视频。
| `id` | 是 | 唯一标识符 |
| `src` | 是 | 音频文件路径,相对于 `.svml` 源文件 |
-通常用作 `speaker:Take` 的语音音色参考。
+通常用作 `seedance:ReferenceVideo` 的语音音色参考。
## estimate:Speech
-基于 Script 文本的确定性语音时长估算。无需外部服务调用——估算根据字数和语速参数在本地计算。
+基于 Script 实际读音文本的确定性语音时长规划。无需外部服务调用——时长根据读音单位和口播密度策略在本地计算。
```svml
<estimate:Speech id="hook-duration"
@@ -60,7 +62,7 @@ description: 声明媒体资源并使用 Seedance 生成视频。
|---|---|---|
| `id` | 是 | 唯一标识符 |
| `source` | 是 | 要估算的 Script 文本——通常为 `{script.segment.NAME.speech}` |
-| `policy` | 是 | 控制语速和边界的 SVS 语音 Recipe |
+| `policy` | 否 | 控制语速和边界的 SVS 语音 Recipe;省略时使用内联参数 |
`policy` 引用一个 SVS Recipe(参见 [SVS 样式表](./styles.md#speech-estimation)):
@@ -68,10 +70,9 @@ description: 声明媒体资源并使用 Seedance 生成视频。
speech.normal {
language: en;
pace: normal;
- padding: 0.3;
min: 4;
max: 15;
- rounding: ceil;
+ rounding: round;
}
```
@@ -80,145 +81,169 @@ speech.normal {
```svml
<estimate:Speech id="opening-duration"
source={story.segment.opening.speech}
- language="en" pace="normal" padding="0.3" min="4" max="15" rounding="ceil"/>
+ language="en" pace="normal" min="4" max="15" rounding="round"/>
```
+英语官方档位为 `slow = 4.2`、`normal = 4.6`、`fast = 5.0` 音节/秒。
+项目需要档位之间的连续值时,可以用 `rate="4.75"` 代替 `pace`;二者不能同时出现。
+策略没有隐式值:无论内联还是引用 Recipe,都必须写明 `language`、`min`、`max`、
+`rounding`,并且在 `pace` 和 `rate` 中恰好选择一个。
+
**输出:** `{hook-duration.duration}`——估算的时长(秒),传递给生成组件。
-## seedance:Prompt
+## text:Value
-一个可复用的文本块,为 Seedance 生成提供视觉指导。
+一个可复用的字面 `Text` 值。它与模型无关,可以进入 Seedance、GPT Image 或任何声明的文字端口。
```svml
-<seedance:Prompt id="alice-direction">
+<import as="text" from="@narratage/text@1"/>
+
+<text:Value id="alice-direction">
Locked medium close-up. Alice speaks directly to camera in a quiet daylight studio.
Calm, curious delivery; natural breathing and restrained hand movement.
-</seedance:Prompt>
+ Spoken dialogue — say exactly: What if editing began with meaning?
+</text:Value>
```
| 属性 | 必填 | 说明 |
|---|---|---|
| `id` | 是 | 唯一标识符 |
-元素主体即为提示文本。通过 `seedance:Speech` 和 `seedance:Video` 的 `prompt` 属性引用。
-
-## seedance:Speech
-
-通过 Seedance 模型生成说话人头部视频片段。这是低层级的生成组件——直接指定对话、提示和时长。
+元素主体就是精确的 Text 值。`text:Render` 也能用模板和显式图输入产出同一类型。
-```svml
-<seedance:Speech id="alice-take" model="mini"
- dialogue={story.segment.opening.dialogue}
- prompt={alice-direction}
- duration="8">
- <seedance:Reference image={alice-reference} role="character"/>
-</seedance:Speech>
-```
+## Seedance 三种调用形状
-| 属性 | 必填 | 说明 |
-|---|---|---|
-| `id` | 是 | 唯一标识符 |
-| `model` | 是 | Seedance 模型名称:`mini` |
-| `dialogue` | 是 | 要进行口型同步的 Script 文本——通常为 `{script.segment.NAME.dialogue}` |
-| `prompt` | 是 | 视觉指导——引用 `seedance:Prompt` |
-| `duration` | 是 | 片段时长(秒)(数字或 `{estimate.duration}` 引用) |
-| `resolution` | 否 | 输出分辨率:`480p`、`720p`(默认值因模型而异) |
-| `aspect-ratio` | 否 | 输出宽高比:`9:16`、`16:9`、`1:1` |
+Seedance 只暴露模型能力,不暴露“口播”“B-roll”等创作用途。`standard`、`fast`、`mini`
+选择模型版本;调用形状则独立分为三种。三者都消费完整的普通 `Text` Prompt,并输出
+`{id.video}`。
-### seedance:Reference
+### seedance:TextVideo
-提供参考图片以保持角色一致性的子元素:
+纯 Prompt 生成。只有这种形状允许 `web-search`:
```svml
-<seedance:Reference image={alice-reference} role="character"/>
+<seedance:TextVideo id="ambient" model="mini"
+ prompt={ambient-direction} duration="5" web-search="false"/>
```
-| 属性 | 必填 | 说明 |
-|---|---|---|
-| `image` | 是 | 引用 `media:Image` 组件 |
-| `role` | 是 | 该参考的用途:`character`、`subject` |
-
-**输出:** `{alice-take}` 或 `{alice-take.video}`——生成的视频,传递给 `speech:Spine`。
-
-## seedance:Video
+### seedance:FrameVideo
-生成独立的视频片段(非说话人头部——无对话口型同步)。
+必须给首帧,可以额外给尾帧:
```svml
-<seedance:Video id="product-motion" model="mini"
- prompt={product-direction} duration="5">
- <seedance:Reference image={product-reference} role="subject"/>
-</seedance:Video>
+<seedance:FrameVideo id="transition" model="fast"
+ prompt={transition-direction} duration="5"
+ first-frame={opening-image} last-frame={closing-image}/>
```
-| 属性 | 必填 | 说明 |
-|---|---|---|
-| `id` | 是 | 唯一标识符 |
-| `model` | 是 | Seedance 模型名称:`mini` |
-| `prompt` | 是 | 视觉指导——引用 `seedance:Prompt` |
-| `duration` | 是 | 片段时长(秒) |
+### seedance:ReferenceVideo
-同样接受 `<seedance:Reference>` 子元素作为参考图片。
+多模态参考生成。至少需要一个 `Reference` 子元素,可以显式接入图片、视频和音频:
-**输出:** `{product-motion.video}`——用作 B-roll 来源。
+```svml
+<seedance:ReferenceVideo id="alice-take" model="mini"
+ prompt={alice-direction}
+ duration={alice-duration.duration}
+ generate-audio="true">
+ <seedance:Reference image={alice-reference}/>
+ <seedance:Reference audio={alice-voice}/>
+</seedance:ReferenceVideo>
+```
-## speaker:Take
+这个低层组件并不知道它被用来做口播;用途只存在于传入的 Text 中。公共属性包括
+`id`、`model`、`prompt`、`duration`、`resolution`、
+`aspect-ratio`、`generate-audio`;`duration` 可以是字面量或显式 `{estimate.duration}` 边。
-基于 Prompt Kit 构建的更高层级说话人头部组件。无需编写原始提示,你只需提供一个包含生成设置的 Recipe 和一个自动组装提示的 Kit。
+可以直接抽取前一段生成视频里的音频,并通过普通图边给后续片段当作参考。这个操作不会
+把音频提升成语音证据,也不会凭空附加说话人语义:
```svml
-<import as="speaker" from="@narratage/seedance-speaker@1"/>
-<import as="ugc" source="../../packages/seedance-speaker/kits/official-ugc-v1.svs"/>
-
-<speaker:Take id="hook-take"
- dialogue={story.segment.hook.dialogue}
- duration={hook-duration.duration}
- recipe={studio.speaker.host}
- kit={ugc.official-ugc-v1}>
- <speaker:Reference image={presenter-clean} role="character-and-scene"/>
- <speaker:Reference audio={presenter-voice} role="voice-timbre"/>
-</speaker:Take>
+<mediaop:ExtractAudio id="voice-from-opening"
+ source={opening.video} audio="default"/>
+
+<seedance:ReferenceVideo id="follow-up" model="mini"
+ prompt={follow-up-direction} duration="5" generate-audio="true">
+ <seedance:Reference image={presenter-reference}/>
+ <seedance:Reference audio={voice-from-opening.audio}/>
+</seedance:ReferenceVideo>
```
-| 属性 | 必填 | 说明 |
-|---|---|---|
-| `id` | 是 | 唯一标识符 |
-| `dialogue` | 是 | Script 文本——通常为 `{script.segment.NAME.dialogue}` |
-| `duration` | 是 | 来自 `estimate:Speech` 的估算时长 |
-| `recipe` | 是 | SVS speaker Recipe(参见 [SVS 样式表](./styles.md#speaker)) |
-| `kit` | 是 | Prompt Kit SVS——用于组装提示的模板 |
+同一个媒体操作包还提供 `Transform`(按顺序截取、变速)和 `ExtractFrame`(首帧、尾帧、
+指定帧或指定时间取图)。本地 FFmpeg 与 AWS Lambda 只是这些精确 Need 的可互换 Runtime
+Endpoint,不会改变作者图。
-### speaker:Reference
+## Seedance 语义 Kit
-提供参考媒体的子元素。同时接受图片和音频:
+`@narratage/seedance-kits` 包含七个纯数据 Text Template。Kit 不是模型包装器:先用通用
+`text:Render` 生成 prompt,再把该 Text 与真实媒体引用显式接入低层 Seedance Surface。
```svml
-<speaker:Reference image={presenter-clean} role="character-and-scene"/>
-<speaker:Reference audio={presenter-voice} role="voice-timbre"/>
+<import as="text" from="@narratage/text@1"/>
+<import as="seedance" from="@narratage/seedance@1"/>
+<import as="broll-kit" source="../../packages/seedance-kits/kits/broll-v1.svs"/>
+
+<text:Render id="demo-prompt"
+ template={broll-kit.broll-v1}
+ recipe={studio.broll.product-demo}>
+ <text:Set name="story" text={copy.product-demo}/>
+</text:Render>
+
+<seedance:ReferenceVideo id="demo" model="mini"
+ prompt={demo-prompt} duration={demo-duration.duration}
+ resolution="720p" aspect-ratio="9:16" generate-audio="false">
+ <seedance:Reference image={scene}/>
+ <seedance:Reference image={product}/>
+</seedance:ReferenceVideo>
```
-| 属性 | 必填 | 说明 |
-|---|---|---|
-| `image` | image/audio 二选一 | 引用 `media:Image` |
-| `audio` | image/audio 二选一 | 引用 `media:Audio` |
-| `role` | 是 | 参考用途:`character-and-scene`、`voice-timbre` |
+项目 Recipe 选择模板声明的轴;显式 `text:Param` 可以覆盖 Recipe。动态 story、dialogue、
+action 和 extra 仍经由 `text:Set` 作为图边进入。现有模板包括 `speaker-v1`、`broll-v1`、`podcast-v1`、
+`call-v1`、`street-interview-v1`、`motion-reference-v1`、`camera-reference-v1`。
+媒体数量与顺序仍清楚地写在 `seedance:ReferenceVideo` 里,不藏进 Kit 代码。
-**输出:** `{hook-take.video}`——生成的视频,传递给 `speech:Spine`。
+## 口播 Prompt 组装
-### Prompt Kits
+口播创作不需要一个特殊的可执行组件。数据化的 `speaker-v1` Template、项目 Recipe 与每段的
+dialogue/action 由普通 Text 模块组装,结果再像其他生成任务一样通过显式 `prompt` 边进入 Seedance。
-项目 Recipe 选择 `material-mode`、`story-shape`、`camera-language` 等轴。模板只读取自己声明的属性;显式参数覆盖 Recipe 值。
+```svml
+<import as="text" from="@narratage/text@1"/>
+<import as="seedance" from="@narratage/seedance@1"/>
+<import as="speaker-kit" source="../../packages/seedance-kits/kits/speaker-v1.svs"/>
+
+<text:Value id="hook-action">
+ 先紧迫地直视镜头,最后一句收住声音。
+</text:Value>
+
+<text:Render id="hook-prompt"
+ template={speaker-kit.speaker-v1}
+ recipe={studio.speaker.host}>
+ <text:Set name="dialogue" text={story.segment.hook.dialogue}/>
+ <text:Set name="action" text={hook-action}/>
+</text:Render>
+
+<seedance:ReferenceVideo id="hook-take" model="mini"
+ prompt={hook-prompt} duration={hook-duration.duration}
+ resolution="720p" aspect-ratio="9:16" generate-audio="true">
+ <seedance:Reference image={presenter-clean}/>
+ <seedance:Reference audio={presenter-voice}/>
+</seedance:ReferenceVideo>
+```
+
+`speaker-v1.svs` 自己选择 Text Template Frontend。`studio.svs` 提供具名轴值,`dialogue` 与
+`action` 保持为普通图输入。Kit 和 Text 都不选择模型、参考素材或 Provider。
## 组合示例
-一个四段拍摄的设置,估算时长作为输入传递给 `speaker:Take` 生成:
+一个两段拍摄的设置,估算时长进入显式 Text 组装与 Seedance 生成:
```svml
<import as="media" from="@narratage/media@1"/>
<import as="estimate" from="@narratage/estimate@1"/>
-<import as="speaker" from="@narratage/seedance-speaker@1"/>
+<import as="text" from="@narratage/text@1"/>
+<import as="seedance" from="@narratage/seedance@1"/>
<import as="studio" source="./studio.svs"/>
-<import as="ugc" source="../../packages/seedance-speaker/kits/official-ugc-v1.svs"/>
+<import as="speaker-kit" source="../../packages/seedance-kits/kits/speaker-v1.svs"/>
<media:Image id="presenter-clean" src="./assets/presenter-clean.png"/>
<media:Image id="presenter-alt" src="./assets/presenter-alt.png"/>
@@ -228,38 +253,29 @@ speech.normal {
source={story.segment.hook.speech} policy={studio.speech.normal}/>
<estimate:Speech id="meeting-duration"
source={story.segment.meeting.speech} policy={studio.speech.normal}/>
-<estimate:Speech id="evidence-duration"
- source={story.segment.evidence.speech} policy={studio.speech.normal}/>
-<estimate:Speech id="payoff-duration"
- source={story.segment.payoff.speech} policy={studio.speech.normal}/>
-
-<speaker:Take id="hook-take" dialogue={story.segment.hook.dialogue}
- duration={hook-duration.duration} recipe={studio.speaker.host}
- kit={ugc.official-ugc-v1}>
- <speaker:Reference image={presenter-clean} role="character-and-scene"/>
- <speaker:Reference audio={presenter-voice} role="voice-timbre"/>
-</speaker:Take>
-
-<speaker:Take id="meeting-take" dialogue={story.segment.meeting.dialogue}
- duration={meeting-duration.duration} recipe={studio.speaker.host}
- kit={ugc.official-ugc-v1}>
- <speaker:Reference image={presenter-alt} role="character-and-scene"/>
- <speaker:Reference audio={presenter-voice} role="voice-timbre"/>
-</speaker:Take>
-
-<speaker:Take id="evidence-take" dialogue={story.segment.evidence.dialogue}
- duration={evidence-duration.duration} recipe={studio.speaker.host}
- kit={ugc.official-ugc-v1}>
- <speaker:Reference image={presenter-alt} role="character-and-scene"/>
- <speaker:Reference audio={presenter-voice} role="voice-timbre"/>
-</speaker:Take>
-
-<speaker:Take id="payoff-take" dialogue={story.segment.payoff.dialogue}
- duration={payoff-duration.duration} recipe={studio.speaker.host}
- kit={ugc.official-ugc-v1}>
- <speaker:Reference image={presenter-clean} role="character-and-scene"/>
- <speaker:Reference audio={presenter-voice} role="voice-timbre"/>
-</speaker:Take>
+<text:Value id="hook-action">紧迫开场,最后一句放轻。</text:Value>
+<text:Value id="meeting-action">示意产品,然后回到镜头。</text:Value>
+
+<text:Render id="hook-prompt" template={speaker-kit.speaker-v1} recipe={studio.speaker.host}>
+ <text:Set name="dialogue" text={story.segment.hook.dialogue}/>
+ <text:Set name="action" text={hook-action}/>
+</text:Render>
+<text:Render id="meeting-prompt" template={speaker-kit.speaker-v1} recipe={studio.speaker.host}>
+ <text:Set name="dialogue" text={story.segment.meeting.dialogue}/>
+ <text:Set name="action" text={meeting-action}/>
+</text:Render>
+
+<seedance:ReferenceVideo id="hook-take" model="mini" prompt={hook-prompt}
+ duration={hook-duration.duration} resolution="720p" aspect-ratio="9:16" generate-audio="true">
+ <seedance:Reference image={presenter-clean}/>
+ <seedance:Reference audio={presenter-voice}/>
+</seedance:ReferenceVideo>
+<seedance:ReferenceVideo id="meeting-take" model="mini" prompt={meeting-prompt}
+ duration={meeting-duration.duration} resolution="720p" aspect-ratio="9:16" generate-audio="true">
+ <seedance:Reference image={presenter-alt}/>
+ <seedance:Reference audio={presenter-voice}/>
+</seedance:ReferenceVideo>
```
-每个 `speaker:Take` 生成一个 `{*.video}` 输出,传递给下一阶段的 `speech:Spine`。不同的拍摄段可以使用不同的参考图片(例如,演示者在某些 Segment 中持有产品而在其他段中没有),同时共享相同的语音音色和生成 Recipe。
+每个 `seedance:ReferenceVideo` 产出 `{*.video}`,进入下一阶段的 `speech:Spine`。不同 Take
+可以使用不同参考图,同时共享相同的音色与 Prompt Recipe。
diff --git a/docs/zh/quickstart/script.md b/docs/zh/quickstart/script.md
index ef8b7b45..4c5ddce6 100644
--- a/docs/zh/quickstart/script.md
+++ b/docs/zh/quickstart/script.md
@@ -70,7 +70,7 @@ Role Cue 会产生不同的文本投影:
| **speech** | `What time is it?`<br>`It's 8:30.` |
| **caption** | `What time is it?`<br>`It's 8:30.` |
-dialogue `Text` 包含 Role Cue 前缀,speech `Text` 和 caption 投影会去除前缀。给 `seedance:ReferenceVideo` 提供输入的 Prompt Program 可以使用 `{story.segment.dialogue.dialogue}`(带标签)。Script 还会显式输出 `{story.caption}` 作为有序的显示 Atom/Word 全集,并以 `{story.caption.correspondence}` 单独提供 Atom 到口播 token 的对应;只有定时汇合处需要后者。
+dialogue 投影包含 Role Cue 前缀。speech 和 caption 投影会去除前缀。像 `seedance:Speech` 这样的组件使用 `{story.segment.dialogue.dialogue}`(带标签),而 `caption:Track` 使用 caption 投影(不带标签)。
## Dual Text
diff --git a/docs/zh/quickstart/timing.md b/docs/zh/quickstart/timing.md
index 86f29185..c395ad8b 100644
--- a/docs/zh/quickstart/timing.md
+++ b/docs/zh/quickstart/timing.md
@@ -38,7 +38,7 @@ description: Speech Spine 装配与 WhisperX 对齐——将生成的片段连
| 属性 | 必填 | 描述 |
|---|---|---|
-| `source` | 是 | 生成的视频——来自 `seedance:Speech`、`speaker:Take` 等 |
+| `source` | 是 | 生成的视频——例如来自 `seedance:ReferenceVideo` |
| `segment` | 是 | 此片段对应的 Script Segment——例如 `{story.segment.hook}` |
`<speech:Take>` 子元素的排列顺序**决定了节目顺序**。第一个片段从时间零点开始;后续片段依次紧接。
@@ -81,7 +81,7 @@ SemanticMap 将每个 Script 中标注的锚点映射到一个时间点。它覆
ProgramSpace 不是一个需要声明的组件——它由 `speech:Spine` 产生,并传递给每个需要知道总节目时长和帧域的组件。
```svml
-<film:Film id="main" space={speech.space} ...>
+<film:Film id="main" canvas={vertical} space={speech.space} ...>
<caption-fine:Track id="captions" ... space={speech.space} .../>
<text:Track id="titles" space={speech.space}>
<render:Video id="final" composition={main.composition} space={speech.space}/>
@@ -106,7 +106,7 @@ SemanticMap 是连接 Script 文本与物理时间的类型化桥梁。当你在
<caption-fine:Track id="captions" ... map={timing.map} .../>
```
-Map 只包含最终词窗口和语义锚点,不传播"测量、推导、估算"标签。WhisperX Evidence
+Map 只包含最终词窗口和语义锚点,不传播“测量、推导、估算”标签。WhisperX Evidence
与确定性的 M:N 对齐器负责充分使用录音证据;下游 Track 只接收一份完整 Map,不再解释
每个点是如何获得的。
@@ -139,7 +139,7 @@ Map 只包含最终词窗口和语义锚点,不传播"测量、推导、估算
数据流向:
```text
-speaker:Take outputs ──► speech:Spine ──► whisperx:Alignment
+生成的视频 ─────────────► speech:Spine ──► whisperx:Alignment
│ │
.visual .map (SemanticMap)
.audio │
diff --git a/docs/zh/quickstart/tracks.md b/docs/zh/quickstart/tracks.md
index e8ce7a50..1cb04b23 100644
--- a/docs/zh/quickstart/tracks.md
+++ b/docs/zh/quickstart/tracks.md
@@ -5,6 +5,10 @@ description: 视觉 Track 组件——字幕、媒体叠加层和排版叠加层
# 字幕、Media 与 Typography
+> **发布前说明:** Caption Fine、Media Track 与 Typography Track 都执行各自声明的作者 Surface。
+> 它们的作者 API 仍可演进;共享终端 Track/Visual IR 窄腰已在仓库内冻结,但尚未作为
+> npm ABI 发布。
+
每个进入最终合成的视听内容都是一个对等的 **Track**。Track 是扁平的(无嵌套),其 z 轴顺序由 SVS 中的 `stack-order` 属性决定。本页介绍三个官方视觉 Track 包:字幕、Media 和 Typography 叠加层。
## 字幕系统
@@ -19,36 +23,83 @@ Script 显示全集 → Caption Program → Planner + Atom 实测时间 → 样
<import as="caption" from="@narratage/caption@1"/>
<import as="caption-fine" from="@narratage/caption-fine@1"/>
<import as="caption-ai" from="@narratage/caption-gemini@1"/>
+<import as="media" from="@narratage/media@1"/>
<import as="fonts" from="@narratage/fonts-open@1"/>
```
-公共 Caption 只负责 Cue 字数边界、可选的通用逐词字段、完整样式分配、Plan 校验与时间拼接。Fine 是第一种无字段样式族,负责自己的几何、字形/Cue/Pill Paint 与局部动画。
+公共 Caption 只负责 Cue 字数边界、可选的通用逐词字段、完整样式分配、Plan 校验与时间
+拼接。Fine 是第一种无字段样式族,负责自己的几何、字形/Cue/Pill Paint 与局部动画。
### caption-fine:Style
-一个 Style 是不可拆分的"规划要求 + 渲染参数"。Fine 从一个包自有的 SVS Recipe 同时解析两者:
+一个 Style 是不可拆分的“规划要求 + 渲染参数”。Fine 从一个包自有的 SVS Recipe
+同时解析两者:
+
+```svs
+caption.primary {
+ cue-min-words: 2; cue-max-words: 7;
+ stack-order: 70; x: 0.5; y: 0.88; width: 0.84;
+ anchor-x: center; anchor-y: bottom;
+ font: Inter; weight: 700; size: 58; line-height: 1; align: center;
+ fill: #FFFFFF; stroke-color: #09090B; stroke-width: 2;
+ background: #00000000; padding: 0; radius: 0;
+ karaoke: trail; karaoke-transition: wipe; active-fill: #FFD54A;
+ active-box: current; active-box-continuity: isolated;
+ active-box-background: #FFD54ACC; active-box-padding: 4 8; active-box-radius: 8;
+ 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;
+}
+```
```svml
-<fonts:Stack id="caption-fonts" family="inter" weight="700" style="normal"/>
+<fonts:Stack id="caption-fonts" family="inter" weight="700" style="normal" emoji="color">
+ <fonts:Fallback family="noto-sans-sc" weight="700" style="normal"/>
+</fonts:Stack>
<caption-fine:Style id="primary-caption" recipe={studio.caption.primary}
font={caption-fonts}/>
```
-必填的 `font=` 边携带一个按字节复现的 `FontStackRef`。Fine 省略字体栈会在编译时失败,不会退回当前机器上的同名字体。
+必填的 `font=` 边携带一个按字节复现的 `FontStackRef`。主字体必须与 Recipe
+的 weight/style 一致;每个 Fallback 保留自己的真实字体信息。省略字体栈会在编译时
+失败,不会退回当前机器上的同名字体。
+
+Recipe 同时包含 `cue-min-words`、`cue-max-words` 和完整字体/框参数。Fine 不声明任何
+逐词字段;其他字幕包可以定义完全不同的字段和渲染方式,无需修改公共 Caption。
+
+Fine 不是一组互斥预设。基础/激活渐变、描边、阴影、长阴影、外发光、下划线、Pill
+和动画均为正交维度。文字、下划线和 Pill 各自选择 `off | current | trail`;因此可以
+直接表达“文字保留已读色,但 Pill 只跟随当前词”。`active-box-continuity: joined` 会把
+已读前缀在每个真实换行片段内连成一个背景,而不是给每个词分别套胶囊。
+
+Fine 只在完整 Atom 之间自然换行,永不裁掉作者文字,因此有意不提供 `max-lines`。
+需要控制行数时,应调整 Cue 字数边界、Track 宽度与字号。
+
+CJK 口播可以直接书写。若一个只负责显示的 emoji 仍需跟随语音计时,应显式写出对应,
+例如 `<🌐 | globe>`;系统不会替裸符号虚构一个口播词。
### caption:Program
-Program 消费 Script 显式输出的完整有序显示词全集。一个必填的默认 Style 自动覆盖所有词。
+Program 消费 Script 显式输出的完整有序显示词全集。一个必填的默认 Style 自动覆盖
+所有词,不需要作者制造 `@whole` 或补集。`Use` 按源码顺序替换整个 Style,后命中
+者获胜。
```svml
<caption:Program id="caption-program" display={story.caption}
default={primary-caption}>
<caption:Use role="ALICE" style={alice-caption}/>
<caption:Use role="BOB" style={bob-caption}/>
+ <caption:Use words={story.caption.selection.product-demo}
+ style={dialogue-caption}/>
<caption:Mute words={story.caption.selection.private}/>
</caption:Program>
```
+`role=` 是词子集查询的作者语法,不是时间条件。`words=` 接收 Selection 的字幕专用
+词投影;通用 Selection 的公开值仍只有语义首尾锚点。
+`Mute` 消费同一份精确词投影,不进入 Gemini;它在 Cue 规划完成后隐藏这些完整 Atom,
+既不重新分 Cue,也不把字幕可见性变成 Core 的通用时间遮罩。
+
### caption-ai:Planner
```svml
@@ -56,7 +107,9 @@ Program 消费 Script 显式输出的完整有序显示词全集。一个必填
program={caption-program} model="gemini-2.5-flash"/>
```
-Planner 只接收不可改写的显示 Atom/Word 与已解析好的 Style runs。它只能在完整 Atom 之间分 Cue,并给 Word id 附上样式声明的字段;Fine 没有字段。
+Planner 只接收不可改写的显示 Atom/Word 与已解析好的 Style runs。它只能在完整 Atom
+之间分 Cue,并给 Word id 附上样式声明的字段;Fine 没有字段。它看不到音频、时间或
+Dual Text 右侧。
### caption-fine:Track
@@ -65,15 +118,18 @@ Planner 只接收不可改写的显示 Atom/Word 与已解析好的 Style runs
space={speech.space} program={caption-program} plan={caption-plan.plan}/>
```
-公共 Caption 先把 Plan 与独立 SemanticMap 拼接,Fine 再把所有默认/覆盖样式渲染成一个普通的对等 `VisualTrack`:`{captions.track}`。
+公共 Caption 先把 Plan 与独立 SemanticMap 拼接,Fine 再把所有默认/覆盖样式渲染成
+一个普通的对等 `VisualTrack`:`{captions.track}`。
-## Media 叠加层
+## Media 叠加层与 B-roll
-一个 Item 可以在语义或绝对窗口内放置规范化图片、视频、动画或 Compositable Surface。
+B-roll 是通用 Media Track 的一种剪辑用途,不是独立 Track 家族。一个 Item 可以在语义
+或绝对窗口内放置规范化图片、视频、动画或 Compositable Surface。
```svml
<import as="pipeline" from="@narratage/media-pipeline@1"/>
<import as="media-track" from="@narratage/media-track@1"/>
+<import as="wording" from="@narratage/text@1"/>
```
### media-track:Track 与 media-track:Item
@@ -81,6 +137,16 @@ Planner 只接收不可改写的显示 Atom/Word 与已解析好的 Style runs
位置是一条显式 Spatial Frame 边,外观和运动则是可复用的 SVS 值:
```svml
+<wording:Value id="product-direction">
+ A clean vertical product film: the written script becomes semantic regions,
+ then those regions assemble into a finished video.
+</wording:Value>
+
+<seedance:ReferenceVideo id="product-motion" model="mini"
+ prompt={product-direction} duration="5">
+ <seedance:Reference image={product-reference}/>
+</seedance:ReferenceVideo>
+
<pipeline:Normalize id="product-media" source={product-motion.video}
video="primary-moving" audio="none" span-authority="video" frame-rate="30"/>
@@ -96,9 +162,11 @@ Planner 只接收不可改写的显示 Atom/Word 与已解析好的 Style runs
</media-track:Track>
```
-同一个 Item 模型也能表达全屏切换、分屏和角落小窗。
+Selection 只贡献语义点;Media 包负责将这些点投影为窗口。同一个 Item 模型也能表达全屏
+切换、分屏和角落小窗。需要多个素材时,可以使用有序局部 Layer 或显式 Sequence。
-**输出:**`{product-broll.visual}`;只有作者显式选择了源音频时才会出现 `{product-broll.audio}`。
+**输出:**`{product-broll.visual}`;只有作者显式选择了源音频或 SFX 时才会出现
+`{product-broll.audio}`。
## 文字叠加层
@@ -106,6 +174,7 @@ Planner 只接收不可改写的显示 Atom/Word 与已解析好的 Style runs
```svml
<import as="text" from="@narratage/typography-track@1"/>
+<import as="wording" from="@narratage/text@1"/>
```
### text:Track
@@ -113,6 +182,7 @@ Planner 只接收不可改写的显示 Atom/Word 与已解析好的 Style runs
文字项目的容器。
```svml
+<space:Canvas id="vertical" width="1080" height="1920"/>
<space:Frame id="title-frame" within={vertical}
left="6%" top="6%" right="6%" bottom="84%"/>
<fonts:Stack id="title-font" family="inter" weight="900" style="normal"/>
@@ -130,9 +200,10 @@ Planner 只接收不可改写的显示 Atom/Word 与已解析好的 Style runs
| `space` | 是 | 来自 `speech:Spine` 的 ProgramSpace |
| `map` | 否 | SemanticMap——当项目使用基于 Selection 的计时时需要 |
-### text:Area
+### text:Point、text:Area 与 text:Path
-把流式文字放入 `SpatialFrame`:
+每个 Item 都明确选择一种放置形式、一份精确 Style 和一种时间投影。`Area` 把流式文字放入
+`SpatialFrame`:
```svml
<text:Area id="meaning" placement={title-frame} style={title-style} during="program">
@@ -143,11 +214,36 @@ Planner 只接收不可改写的显示 Atom/Word 与已解析好的 Style runs
| 属性 | 必填 | 描述 |
|---|---|---|
| `id` | 是 | 稳定的 Item 身份 |
-| 子内容或 `content` | 是 | 内联纯文本/富文本,或普通图 `Text` 引用 |
-| `during` | 是 | `"program"` 或 Selection 引用 |
-| `placement` | 是 | 一个 `SpatialFrame` |
+| 子内容或 `content` | 是 | 内联纯文本/富文本,或普通图 `Text` 引用;两种形式互斥 |
+| `during` | 是 | `"program"` 或 Selection 引用;也可使用 `at` 与显式 `start`/`end` |
+| `placement` | 是 | 与 Item 形式匹配的 `SpatialPoint`、`SpatialFrame` 或 `SpatialPath` |
| `style` | 是 | 由 SVS Recipe 与精确字体字节共同编译出的 `text:Style` |
+`during` 属性接受字面字符串 `"program"`(表示完整 ProgramSpace),或用于语义计时的 Selection 引用:
+
+```svml
+<text:Style id="callout-style" recipe={studio.text.callout} font={title-font}/>
+<text:Track id="callout" space={speech.space} map={timing.map}>
+ <text:Area id="callout-copy" placement={callout-frame}
+ style={callout-style} during={story.selection.callout}>
+ EXACTLY THE RIGHT MOMENT
+ </text:Area>
+</text:Track>
+```
+
+图中产生的文字会保留为显式边:
+
+```svml
+<wording:Value id="headline">EXACTLY THE RIGHT MOMENT</wording:Value>
+<text:Track id="callout" space={speech.space}>
+ <text:Area id="callout-copy" content={headline}
+ placement={callout-frame} style={callout-style} during="program"/>
+</text:Track>
+```
+
+通用 `Text` 只提供字符;Typography 仍然拥有文档包装、位置、时间、样式与动画。作者需要富文本
+Run 时,继续使用内联 `P`/`Span`/`Break`。
+
**输出:**`{titles.track}` —— 添加到 `film:Film` 的 VisualTrack。
## 组合示例
@@ -164,14 +260,9 @@ Planner 只接收不可改写的显示 Atom/Word 与已解析好的 Style runs
<import as="text" from="@narratage/typography-track@1"/>
<import as="space" from="@narratage/spatial@1"/>
-<space:Canvas id="vertical" width="1080" height="1920"/>
-<space:Frame id="title-frame" within={vertical}
- left="6%" top="6%" right="6%" bottom="84%"/>
-<space:Frame id="card-frame" within={vertical}
- left="10%" top="20%" right="10%" bottom="30%"/>
-
-<!-- Captions -->
+<!-- Captions: primary style for all text -->
<fonts:Stack id="caption-font" family="inter" weight="700" style="normal"/>
+<fonts:Stack id="title-font" family="inter" weight="900" style="normal"/>
<caption-fine:Style id="base-caption" recipe={studio.caption.base} font={caption-font}/>
<caption:Program id="caption-program" display={story.caption} default={base-caption}/>
<caption-ai:Planner id="cue-plan" display={story.caption}
@@ -179,7 +270,14 @@ Planner 只接收不可改写的显示 Atom/Word 与已解析好的 Style runs
<caption-fine:Track id="captions" display={story.caption} correspondence={story.caption.correspondence} map={timing.map}
space={speech.space} plan={cue-plan.plan} program={caption-program}/>
-<!-- Media overlay -->
+<!-- 共享位置是显式边,与 Media/Text 外观分开。 -->
+<space:Canvas id="vertical" width="1080" height="1920"/>
+<space:Frame id="title-frame" within={vertical}
+ left="6%" top="6%" right="6%" bottom="84%"/>
+<space:Frame id="card-frame" within={vertical}
+ left="10%" top="20%" right="10%" bottom="30%"/>
+
+<!-- Media:Selection 期间显示一个普通 Item -->
<pipeline:Normalize id="motion-media" source={motion.video}
video="primary-moving" audio="none" span-authority="video" frame-rate="30"/>
<media-track:Track id="cards" map={timing.map} space={speech.space} canvas={vertical}>
@@ -187,14 +285,22 @@ Planner 只接收不可改写的显示 Atom/Word 与已解析好的 Style runs
during={story.selection.demo} appearance={studio.media.card} motion={studio.motion.card}/>
</media-track:Track>
-<!-- Text overlay -->
-<fonts:Stack id="title-font" family="inter" weight="900" style="normal"/>
+<!-- Text: persistent title overlay -->
<text:Style id="title-style" recipe={studio.text.title} font={title-font}/>
<text:Track id="titles" space={speech.space}>
<text:Area id="meaning" placement={title-frame} style={title-style} during="program">
MEANING
</text:Area>
</text:Track>
+
+<!-- All three tracks feed into Film -->
+<film:Film id="main" canvas={vertical} space={speech.space} appearance={studio.film.vertical}>
+ <film:Track source={speech.visual}/>
+ <film:Track source={speech.audioTrack}/>
+ <film:Track source={cards.visual}/>
+ <film:Track source={captions.track}/>
+ <film:Track source={titles.track}/>
+</film:Film>
```
每个 SVS Recipe 中的 `stack-order` 决定 z 轴排序:语音视觉层为 10,Media 为 40,字幕为 70,文字为 90。数值越高,渲染层越靠上。