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: split quickstart into per-component sub-pages
rpone5348844381bf
diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.tsindex d66cccb0..d5fa7692 100644--- a/docs/.vitepress/config.ts+++ b/docs/.vitepress/config.ts@@ -14,7 +14,19 @@ const enTheme = {],sidebar: {"/quickstart": [- { text: "Getting Started", items: [{ text: "Quickstart", link: "/quickstart" }] },+ {+ text: "Getting Started",+ items: [+ { text: "Overview", link: "/quickstart" },+ { text: "Script", link: "/quickstart/script" },+ { text: "SVS Stylesheets", link: "/quickstart/styles" },+ { text: "Media & Generation", link: "/quickstart/generation" },+ { text: "Timing & Assembly", link: "/quickstart/timing" },+ { text: "Caption, B-roll & Text", link: "/quickstart/tracks" },+ { text: "Film & Rendering", link: "/quickstart/composition" },+ { text: "Run Source & Builds", link: "/quickstart/run" },+ ],+ },],"/guide/": [{@@ -44,7 +56,19 @@ const zhTheme = {],sidebar: {"/zh/quickstart": [- { text: "开始使用", items: [{ text: "Quickstart", link: "/zh/quickstart" }] },+ {+ text: "开始使用",+ items: [+ { text: "概览", link: "/zh/quickstart" },+ { text: "Script", link: "/zh/quickstart/script" },+ { text: "SVS 样式表", link: "/zh/quickstart/styles" },+ { text: "媒体与生成", link: "/zh/quickstart/generation" },+ { text: "时序与装配", link: "/zh/quickstart/timing" },+ { text: "字幕、B-roll 与文字", link: "/zh/quickstart/tracks" },+ { text: "Film 与渲染", link: "/zh/quickstart/composition" },+ { text: "Run Source 与 Build", link: "/zh/quickstart/run" },+ ],+ },],"/zh/guide/": [{diff --git a/docs/quickstart.md b/docs/quickstart.mdindex 77c3d0ad..e473bef8 100644--- a/docs/quickstart.md+++ b/docs/quickstart.md@@ -37,17 +37,15 @@ Every Build takes three separate inputs:Author Source says *what*. Run Source says *which*. Runtime Profile says *where*.-## Check a video graph (free)+## Your first graph checkThe `talking-film-graph-check` example compiles a complete video graph — Script, Seedance, Speech,WhisperX, Gemini Caption, B-roll, Text, Film, HyperFrames — without calling any external service.```bash-# Compile the Author Source.pnpm narratage check examples/talking-film-graph-check/main.svml \--package-lock examples/talking-film-graph-check/svml.packages.lock --root .-# Compile the Run Source and inspect the frozen plan.pnpm narratage plan examples/talking-film-graph-check/build.svrun \--package-lock examples/talking-film-graph-check/svml.packages.lock --root .```@@ -56,84 +54,17 @@ pnpm narratage plan examples/talking-film-graph-check/build.svrun \and outputs the frozen BuildPlan — every Operation and Needs the Scheduler would issue. Inspect itbefore spending money.-## Run a real Build (paid)--The `echo-pro-aroll` example is a four-take Seedance Mini talking-head film.--Prerequisites:--- `KIE_API_KEY`, `GOOGLE_CLOUD_PROJECT`, `GOOGLE_APPLICATION_CREDENTIALS_JSON` in env-- `ffmpeg`, `ffprobe`, Chrome-- Local WhisperX service running (see `services/whisperx/README.md`)-- Local assets in `examples/echo-pro-aroll/assets/` (not committed)--```bash-# Diagnose the Runtime environment.-pnpm narratage doctor examples/echo-pro-aroll/svml.runtime.json--# Submit the Build.-pnpm narratage build examples/echo-pro-aroll/build.svrun \- --runtime examples/echo-pro-aroll/svml.runtime.json \- --package-lock examples/echo-pro-aroll/svml.packages.lock \- --root . \- --build-id echo-pro-film-001 \- --follow--# Retrieve the final video.-pnpm narratage get echo-pro-film-001 \- --runtime examples/echo-pro-aroll/svml.runtime.json \- --name final.video \- --to examples/echo-pro-aroll/output/final.mp4-```--Every accepted intermediate Record and Artifact is archived before the Build completes. `get`-makes an optional copy of an already durable Record.--## Reuse previous results--Narratage has no implicit cache. Reusing a result is explicit Run Graph authoring — declare zero-input-Candidates backed by historical Records and connect them through Satisfaction edges:--```xml-<?svml using="@narratage/run-text@1"?>-<svrun version="1" targets="delivery">- <author source="./main.svml"/>- <target-set id="delivery">- <target output="final.video" accepts="substitute"/>- </target-set>-- <build-record id="hook-video"- build="echo-pro-film-001" output="hook-take.video"/>- <satisfy output="hook-take.video"- candidate="hook-video" fidelity="substitute"/>-</svrun>-```--The compiled plan prunes all upstream Operations that the substitute Candidates replace. This is a-new Build, not a continuation.--```bash-pnpm narratage build examples/echo-pro-aroll/reuse-generated.svrun \- --runtime examples/echo-pro-aroll/svml.runtime.json \- --package-lock examples/echo-pro-aroll/svml.packages.lock \- --root . --build-id echo-pro-film-reuse-001 --follow-```--## CLI reference--```text-narratage lock-packages <lock> --package name [--package name ...] [--root dir]-narratage doctor <runtime.json>-narratage gc <runtime.json> [--apply]-narratage check <source> [--package-lock file] [--root dir]-narratage plan <run-source> [--package-lock file] [--root dir]-narratage build <run-source> --runtime profile [--build-id id] [--follow]-narratage status <build-id> --runtime profile-narratage builds --runtime profile-narratage inspect <build-id> --runtime profile-narratage get <build-id> --runtime profile [--name x|--record x|--output x|--artifact x] [--to path]-narratage cancel <build-id> --runtime profile-```+## Guide contents++| 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, B-roll, text, speech and fonts |+| [Media & Generation](./quickstart/generation.md) | media:Image, media:Audio, estimate:Speech, Seedance, speaker:Take |+| [Timing & Assembly](./quickstart/timing.md) | speech:Spine, whisperx:Alignment, ProgramSpace, SemanticMap |+| [Caption, B-roll & Text](./quickstart/tracks.md) | caption:Style/Program/Planner/Track, broll:Track, text:Track |+| [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 |## Nextdiff --git a/docs/quickstart/composition.md b/docs/quickstart/composition.mdnew file mode 100644index 00000000..87ad65d7--- /dev/null+++ b/docs/quickstart/composition.md@@ -0,0 +1,239 @@+---+title: Film & Rendering+description: Composing tracks into a film and rendering to video.+---++# Film & Rendering++Film is the final assembly stage. It takes all peer Tracks, validates them, and produces a+Composition. The renderer then compiles that Composition into an MP4 video.++```svml+<import as="film" from="@narratage/film@1"/>+<import as="render" from="@narratage/render-hyperframes@1"/>+```++## film:Film++Assembles all Tracks into a single Composition. Film itself has no domain knowledge — it does not+know what a caption is, what B-roll is, or what speech is. It takes any VisualTrack or AudioTrack+and layers them by stacking order.++```svml+<film:Film id="main" space={speech.space} appearance={studio.film.vertical}>+ <film:Track source={speech.visual}/>+ <film:Track source={speech.audioTrack}/>+ <film:Track source={captions.track}/>+ <film:Track source={product-broll.visual}/>+ <film:Track source={titles.track}/>+</film:Film>+```++| Attribute | Required | Description |+|---|---|---|+| `id` | yes | Unique identifier |+| `space` | yes | ProgramSpace from `speech:Spine` — defines duration and frame rate |+| `appearance` | yes | SVS film Recipe — canvas width, height, frame rate, background |++### film:Track++Each `<film:Track>` child adds a Track source to the composition:++| Attribute | Required | Description |+|---|---|---|+| `source` | yes | A VisualTrack or AudioTrack from any upstream component |++Common Track sources:++| Source | Type | From |+|---|---|---|+| `{speech.visual}` | VisualTrack | `speech:Spine` — full-screen talking head |+| `{speech.audioTrack}` | AudioTrack | `speech:Spine` — synchronized audio |+| `{captions.track}` | VisualTrack | `caption:Track` — timed captions |+| `{cards.visual}` | VisualTrack | `broll:Track` — B-roll overlays |+| `{titles.track}` | VisualTrack | `text:Track` — text overlays |++### Track stacking++Tracks are **flat** — there is no nesting or grouping. Z-ordering is determined entirely by the+`stack-order` property in each Track's SVS Recipe. Lower values go behind; higher values render on+top.++Typical stacking order:++| stack-order | Content |+|---|---|+| 10 | Speech visual (full-screen talking head) |+| 40 | B-roll overlays |+| 70 | Captions |+| 90 | Text overlays |++One component can emit multiple visual elements (Presents) at different z-positions, which+interleave with other components' Presents. The final render flattens all Presents, sorts by+absolute stacking key, and paints them onto one canvas.++**Output:** `{main.composition}` — the complete Composition, passed to the renderer.++## render:Video++Compiles the Composition into a finished video via the HyperFrames renderer.++```svml+<render:Video id="final" composition={main.composition} space={speech.space}/>+```++| Attribute | Required | Description |+|---|---|---|+| `id` | yes | Unique identifier |+| `composition` | yes | Composition from `film:Film` |+| `space` | yes | ProgramSpace from `speech:Spine` |++The renderer:++1. Compiles the Composition into a `HyperframesDocument` — an HTML representation of every frame+2. Renders each frame through Chrome/Chromium+3. Encodes the frame sequence into video+4. Mixes the audio Tracks+5. Muxes video + audio into the final MP4++**Output:** `{final.video}` — the finished video file. This is the most common Build Target.++## Full pipeline walkthrough++The complete data flow from Script to rendered video. This example is based on+`examples/talking-film-graph-check/` — the smallest complete graph.++### Author Source (`main.svml`)++```svml+<?svml using="@narratage/text@1"?>++<svml>+ <import from="@narratage/script@1"/>+ <import as="seedance" from="@narratage/seedance@1"/>+ <import as="speech" from="@narratage/speech-spine@1"/>+ <import as="whisperx" from="@narratage/whisperx@1"/>+ <import as="caption" from="@narratage/caption@1"/>+ <import as="caption-ai" from="@narratage/caption-gemini@1"/>+ <import as="broll" from="@narratage/broll@1"/>+ <import as="text" from="@narratage/text-track@1"/>+ <import as="film" from="@narratage/film@1"/>+ <import as="render" from="@narratage/render-hyperframes@1"/>+ <import as="studio" source="./studio.svs"/>++ <!-- 1. Script: the semantic truth -->+ <script id="story">+ <opening><HOST>Meaning @demo becomes the source @/demo.</opening>+ </script>++ <!-- 2. Generation: Seedance talking head + standalone video -->+ <seedance:Prompt id="direction">+ Locked medium close-up in a quiet daylight studio.+ </seedance:Prompt>+ <seedance:Speech id="take" model="mini"+ dialogue={story.segment.opening.dialogue}+ prompt={direction} duration="5"/>+ <seedance:Video id="motion" model="mini"+ prompt={direction} duration="5"/>++ <!-- 3. Timing: assemble spine and align words -->+ <speech:Spine id="speech">+ <speech:Take source={take} segment={story.segment.opening}/>+ </speech:Spine>+ <whisperx:Alignment id="timing" narrative={story} audio={speech.audio}/>++ <!-- 4. Tracks: captions, B-roll, text -->+ <caption:Style id="base-caption" appearance={studio.caption.base}>+ <caption:Cues>Prefer short complete semantic phrases.</caption:Cues>+ <caption:Field id="important" type="boolean"+ min-per-cue="0" max-per-cue="2">+ Select zero, one, or two words whose emphasis best communicates+ this Cue.+ </caption:Field>+ </caption:Style>+ <caption:Program id="caption-program" narrative={story}+ default={base-caption}/>+ <caption-ai:Planner id="cue-plan" narrative={story}+ program={caption-program} model="gemini-2.5-flash"/>+ <caption:Track id="captions" narrative={story} map={timing.map}+ space={speech.space} plan={cue-plan.plan} program={caption-program}/>++ <broll:Track id="cards" map={timing.map} space={speech.space}>+ <broll:Item source={motion.video} during={story.selection.demo}+ appearance={studio.broll.card}/>+ </broll:Track>++ <text:Track id="titles" space={speech.space}>+ <text:Item text="MEANING" during="full"+ appearance={studio.text.title}/>+ </text:Track>++ <!-- 5. Film: compose all tracks -->+ <film:Film id="main" 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>++ <!-- 6. Render: compile to MP4 -->+ <render:Video id="final" composition={main.composition}+ space={speech.space}/>+</svml>+```++### Stylesheet (`studio.svs`)++```svs+<?svml using="@narratage/svs@1"?>++<sheet version="1">+ film.vertical {+ width: 1080; height: 1920; frame-rate: 30; background: #09090B;+ }+ broll.card {+ stack-order: 40; x: 0.1; y: 0.2; width: 0.8; height: 0.5;+ fit: cover; background: #111116; radius: 20;+ enter: slide-up 4f; exit: fade 4f;+ }+ caption.base {+ stack-order: 70; x: 0.08; y: 0.76; width: 0.84;+ font: Inter; weight: 600; size: 58; line-height: 1; align: center;+ fill: #FFFFFF; background: #09090BCC; padding: 16 24; radius: 18;+ }+ text.title {+ stack-order: 90; x: 0.06; y: 0.06; width: 0.88; height: 0.1;+ font: Inter; weight: 900; size: 64; align: center;+ fill: #FFFFFF; tracking: -1;+ }+</sheet>+```++### Run Source (`build.svrun`)++```svml+<?svml using="@narratage/run-text@1"?>++<svrun version="1" targets="delivery">+ <author source="./main.svml"/>+ <target-set id="delivery">+ <target output="final.video" accepts="exact"/>+ </target-set>+</svrun>+```++### Compile and verify++```bash+pnpm narratage check examples/talking-film-graph-check/main.svml \+ --package-lock examples/talking-film-graph-check/svml.packages.lock --root .++pnpm narratage plan examples/talking-film-graph-check/build.svrun \+ --package-lock examples/talking-film-graph-check/svml.packages.lock --root .+```++`check` compiles the Author Graph — validates all imports, types, and graph edges without calling+any external service. `plan` additionally compiles the Run Source and outputs the frozen BuildPlan+showing every Operation the Scheduler would issue. Inspect the plan before spending money.diff --git a/docs/quickstart/generation.md b/docs/quickstart/generation.mdnew file mode 100644index 00000000..18618ac9--- /dev/null+++ b/docs/quickstart/generation.md@@ -0,0 +1,286 @@+---+title: Media & Generation+description: Declaring media assets and generating video with Seedance.+---++# Media & Generation++This page covers components that declare static assets and generate new media — the raw materials+that flow into the timing and track stages downstream.++Every component shown here must be imported by its package specifier before use:++```svml+<import as="media" from="@narratage/media@1"/>+<import as="estimate" from="@narratage/estimate@1"/>+<import as="seedance" from="@narratage/seedance@1"/>+<import as="speaker" from="@narratage/seedance-speaker@1"/>+```++## media:Image++Declares a content-addressed image asset from a local file.++```svml+<media:Image id="presenter" src="./assets/presenter.png"/>+```++| Attribute | Required | Description |+|---|---|---|+| `id` | yes | Unique identifier for the component |+| `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.++## media:Audio++Declares a content-addressed audio asset from a local file.++```svml+<media:Audio id="presenter-voice" src="./assets/presenter-voice.mp3"/>+```++| Attribute | Required | Description |+|---|---|---|+| `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`.++## estimate:Speech++Deterministic speech duration estimation from Script text. No external service call — the estimate is+computed locally from word count and pace parameters.++```svml+<estimate:Speech id="hook-duration"+ source={story.segment.hook.speech}+ policy={studio.speech.normal}/>+```++| Attribute | Required | Description |+|---|---|---|+| `id` | yes | Unique identifier |+| `source` | yes | Script text to estimate — typically `{script.segment.NAME.speech}` |+| `policy` | yes | SVS speech Recipe controlling pace and bounds |++The `policy` references an SVS Recipe (see [SVS Stylesheets](./styles.md#speech-estimation)):++```svs+speech.normal {+ language: en;+ pace: normal;+ padding: 0.3;+ min: 4;+ max: 15;+ rounding: ceil;+}+```++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"/>+```++**Output:** `{hook-duration.duration}` — the estimated duration in seconds, passed to generation+components.++## seedance:Prompt++A reusable text block that provides visual direction for Seedance generation.++```svml+<seedance:Prompt 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>+```++| 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.++## seedance:Speech++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.++```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>+```++| 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++Child element that provides a reference image for character consistency:++```svml+<seedance:Reference image={alice-reference} role="character"/>+```++| 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:Video++Generates a standalone video clip (not a talking-head — no dialogue lip-sync).++```svml+<seedance:Video id="product-motion" model="mini"+ prompt={product-direction} duration="5">+ <seedance:Reference image={product-reference} role="subject"/>+</seedance:Video>+```++| 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.++## speaker:Take++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.++```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.echo-pro}+ kit={ugc.official-ugc-v1}>+ <speaker:Reference image={presenter-clean} role="character-and-scene"/>+ <speaker:Reference audio={presenter-voice} role="voice-timbre"/>+</speaker:Take>+```++| 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 |++### speaker:Reference++Child element providing reference media. Accepts both images and audio:++```svml+<speaker:Reference image={presenter-clean} role="character-and-scene"/>+<speaker:Reference audio={presenter-voice} role="voice-timbre"/>+```++| 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` |++**Output:** `{hook-take.video}` — the generated video, passed to `speech:Spine`.++### Prompt Kits++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`.++The kit is imported using the Prompt Kit SVS parser:++```svs+<?svml using="@narratage/prompt-kit/svs@1"?>+```++The Recipe in `studio.svs` sets the axis parameter values (composition-stability, camera-motion,+edit-rhythm, performance, gesture, voice-mode), and the kit assembles them into a complete prompt+automatically.++## Combination example++A four-take setup with estimated durations feeding into `speaker:Take` 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="studio" source="./studio.svs"/>+<import as="ugc" source="../../packages/seedance-speaker/kits/official-ugc-v1.svs"/>++<media:Image id="presenter-clean" src="./assets/presenter-clean.png"/>+<media:Image id="presenter-with-echo" src="./assets/presenter-with-echo.png"/>+<media:Audio id="presenter-voice" src="./assets/presenter-voice.mp3"/>++<estimate:Speech id="hook-duration"+ 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.echo-pro}+ 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.echo-pro}+ kit={ugc.official-ugc-v1}>+ <speaker:Reference image={presenter-with-echo} 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.echo-pro}+ kit={ugc.official-ugc-v1}>+ <speaker:Reference image={presenter-with-echo} 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.echo-pro}+ kit={ugc.official-ugc-v1}>+ <speaker:Reference image={presenter-clean} role="character-and-scene"/>+ <speaker:Reference audio={presenter-voice} role="voice-timbre"/>+</speaker:Take>+```++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.diff --git a/docs/quickstart/run.md b/docs/quickstart/run.mdnew file mode 100644index 00000000..7538da7c--- /dev/null+++ b/docs/quickstart/run.md@@ -0,0 +1,308 @@+---+title: Run Source & Builds+description: Declaring build targets, reusing results and configuring the runtime.+---++# Run Source & Builds++The Run Source (`.svrun`) declares **what to build** — which outputs to demand, what fidelity to+accept, and optionally how to reuse results from prior Builds. The Runtime Profile+(`svml.runtime.json`) declares **where to run** — endpoints, credentials, concurrency, and+permissions.++Neither of these changes what the video **is**. That is the Author Source's job.++## Run Source syntax++Every `.svrun` file begins with its processing instruction:++```svml+<?svml using="@narratage/run-text@1"?>+```++### Minimal Run Source++```svml+<?svml using="@narratage/run-text@1"?>++<svrun version="1" targets="delivery">+ <author source="./main.svml"/>+ <target-set id="delivery">+ <target output="final.video" accepts="exact"/>+ </target-set>+</svrun>+```++| Element | Description |+|---|---|+| `<svrun>` | Root element. `version="1"`, `targets` names the active target-set |+| `<author>` | Mandatory. `source` points to the `.svml` Author Source |+| `<target-set>` | A named set of demanded outputs |+| `<target>` | One demanded output: `output` names a Logical Output, `accepts` sets fidelity |++### Targets++A **Target** names an output required by the Build and the worst fidelity it accepts:++- `accepts="exact"` — the output must be exactly what the author declared+- `accepts="substitute"` — an acceptable replacement is allowed (e.g. a prior generation)++There is no privileged "final video" root. Any public Logical Output from any component can be a+Target. The compiler only executes Operations needed to satisfy the demanded Targets — everything+else is pruned.++### Multiple targets++You can demand multiple outputs from one Build:++```svml+<target-set id="delivery">+ <target output="final.video" accepts="exact"/>+ <target output="captions.track" accepts="exact"/>+</target-set>+```++Or define multiple target-sets and switch between them:++```svml+<svrun version="1" targets="preview">+ <author source="./main.svml"/>++ <target-set id="preview">+ <target output="captions.track" accepts="substitute"/>+ </target-set>++ <target-set id="delivery">+ <target output="final.video" accepts="exact"/>+ </target-set>+</svrun>+```++The `targets` attribute on `<svrun>` selects which set is active.++## Reusing results++Narratage has no implicit cache. Reusing a result is explicit Run Graph authoring — you declare+historical Records as zero-input Candidates and connect them through Satisfaction edges.++```svml+<?svml using="@narratage/run-text@1"?>++<svrun version="1" targets="delivery">+ <author source="./main.svml"/>+ <target-set id="delivery">+ <target output="final.video" accepts="substitute"/>+ </target-set>++ <build-record id="hook-video"+ build="echo-pro-film-001" output="hook-take.video"/>+ <build-record id="meeting-video"+ build="echo-pro-film-001" output="meeting-take.video"/>+ <build-record id="evidence-video"+ build="echo-pro-film-001" output="evidence-take.video"/>+ <build-record id="payoff-video"+ build="echo-pro-film-001" output="payoff-take.video"/>++ <satisfy output="hook-take.video"+ candidate="hook-video" fidelity="substitute"/>+ <satisfy output="meeting-take.video"+ candidate="meeting-video" fidelity="substitute"/>+ <satisfy output="evidence-take.video"+ candidate="evidence-video" fidelity="substitute"/>+ <satisfy output="payoff-take.video"+ candidate="payoff-video" fidelity="substitute"/>+</svrun>+```++### build-record++Declares a zero-input Candidate backed by a historical Record from a previous Build:++| Attribute | Description |+|---|---|+| `id` | Local Candidate id within this Run Source |+| `build` | The build-id of the previous Build |+| `output` | The Logical Output name from that Build |++### satisfy++Connects a Candidate to a Logical Output:++| Attribute | Description |+|---|---|+| `output` | The Logical Output to satisfy |+| `candidate` | The Candidate id (from `build-record`) |+| `fidelity` | `exact` or `substitute` |++The compiled plan prunes all upstream Operations that the substitute Candidates replace. This is a+new Build, not a continuation of the old one. Downstream processing (normalization, WhisperX,+captioning, rendering) still runs against the reused media.++### Fidelity model++- **`exact`** — the Candidate precisely matches what the author declared+- **`substitute`** — the Candidate is an acceptable replacement++Substitute fidelity is **monotonic**: once a substitute enters the graph, it propagates downstream.+You cannot wash it back to exact. If the final target accepts `substitute`, downstream Operations+that consume substitute inputs produce substitute results.++## Runtime Profile++The Runtime Profile (`svml.runtime.json`) tells the system **where** to run each type of work:++```json+{+ "format": "svml.runtime-config@1",+ "packageLock": "./svml.packages.lock",+ "runtimePackageLock": "./svml.runtime-packages.lock",+ "endpoints": [+ {+ "use": "@narratage/provider-kie",+ "instance": "kie.main",+ "lane": "generation",+ "config": {+ "apiKeyEnv": "KIE_API_KEY",+ "defaultConcurrency": 2+ }+ },+ {+ "use": "@narratage/provider-media-local",+ "instance": "media.main",+ "lane": "media",+ "config": { "defaultConcurrency": 2 }+ },+ {+ "use": "@narratage/provider-whisperx-local",+ "instance": "whisperx.main",+ "lane": "alignment",+ "config": { "defaultConcurrency": 1 }+ },+ {+ "use": "@narratage/provider-google-vertex",+ "instance": "vertex.main",+ "lane": "planning",+ "config": {+ "projectEnv": "GOOGLE_CLOUD_PROJECT",+ "credentialsEnv": "GOOGLE_APPLICATION_CREDENTIALS_JSON",+ "location": "global",+ "defaultConcurrency": 1+ }+ },+ {+ "use": "@narratage/provider-hyperframes-local",+ "instance": "hyperframes.main",+ "lane": "render",+ "config": {+ "workers": 2,+ "quality": "standard",+ "defaultConcurrency": 1+ }+ }+ ],+ "permissions": [+ "filesystem:whisperx-staging",+ "network:aiplatform.googleapis.com",+ "network:api.kie.ai",+ "network:kieai.redpandaai.co",+ "network:whisperx-loopback",+ "process:hyperframes",+ "process:media"+ ],+ "scheduling": {+ "maxConcurrency": 4,+ "lanes": {+ "generation": 2,+ "media": 2,+ "alignment": 1,+ "planning": 1,+ "render": 1+ }+ }+}+```++### Endpoints++Each endpoint binds a Provider package to a named instance with a concurrency lane:++| Field | Description |+|---|---|+| `use` | Provider package name (e.g. `@narratage/provider-kie`) |+| `instance` | Unique instance identifier |+| `lane` | Scheduling lane for concurrency control |+| `config` | Provider-specific configuration (API keys, concurrency, etc.) |++### Permissions++Explicit grants for filesystem, network, and process access. The scheduler refuses Operations that+require permissions not listed here.++### Scheduling++`maxConcurrency` limits total parallel Operations. `lanes` sets per-lane concurrency limits to+prevent one type of work from starving others.++## Build workflow++### 1. Diagnose the environment++```bash+pnpm narratage doctor examples/echo-pro-aroll/svml.runtime.json+```++Doctor checks that every endpoint is reachable, credentials are valid, and required executables+(`ffmpeg`, `ffprobe`, Chrome) are available.++### 2. Inspect the plan++```bash+pnpm narratage plan examples/echo-pro-aroll/build.svrun \+ --package-lock examples/echo-pro-aroll/svml.packages.lock --root .+```++Review the frozen BuildPlan before spending money. The plan shows every Operation and Needs the+Scheduler would issue.++### 3. Submit the Build++```bash+pnpm narratage build examples/echo-pro-aroll/build.svrun \+ --runtime examples/echo-pro-aroll/svml.runtime.json \+ --package-lock examples/echo-pro-aroll/svml.packages.lock \+ --root . \+ --build-id echo-pro-film-001 \+ --follow+```++| Flag | Description |+|---|---|+| `--runtime` | Path to the Runtime Profile |+| `--package-lock` | Path to the package lock file |+| `--root` | Workspace root directory |+| `--build-id` | User-chosen identifier for this Build (used for retrieval and reuse) |+| `--follow` | Stream Build progress to the terminal |++### 4. Retrieve results++```bash+pnpm narratage get echo-pro-film-001 \+ --runtime examples/echo-pro-aroll/svml.runtime.json \+ --name final.video \+ --to examples/echo-pro-aroll/output/final.mp4+```++Every accepted intermediate Record and Artifact is archived before the Build completes. `get` makes+a copy of an already durable Record.++### 5. Reuse in a new Build++Create a new `.svrun` file that references the completed Build's Records (see [Reusing results](#reusing-results)+above), then submit it:++```bash+pnpm narratage build examples/echo-pro-aroll/reuse-generated.svrun \+ --runtime examples/echo-pro-aroll/svml.runtime.json \+ --package-lock examples/echo-pro-aroll/svml.packages.lock \+ --root . --build-id echo-pro-film-reuse-001 --follow+```diff --git a/docs/quickstart/script.md b/docs/quickstart/script.mdnew file mode 100644index 00000000..4ceefaab--- /dev/null+++ b/docs/quickstart/script.md@@ -0,0 +1,262 @@+---+title: Script+description: The Script Surface — Segments, Role Cues, Dual Text, Selections, Moments and text projections.+---++# Script++The `<script>` element holds every word the narrator or speakers say. Script is **prose-first**: it+contains no timecodes, no media references, no styling, no generation parameters. Everything else in+the pipeline reads the Script; the Script reads nothing.++```svml+<import from="@narratage/script@1"/>++<script id="story">+ <opening>+ <HOST> Hello world.+ </opening>+</script>+```++The import `@narratage/script@1` activates the Script Surface. The `id` attribute lets other+components refer to the Script and its parts.++## Segments++Segments are ordered blocks of spoken content. The tag name **is** the id — it must be unique within+a Script.++```svml+<script id="story">+ <opening>+ Hello world.+ </opening>++ <pause/>++ <middle>+ This is the second part.+ </middle>++ <close>+ Goodbye.+ </close>+</script>+```++- A Segment can be self-closing (`<pause/>`). An empty Segment has structure but no speech tokens; it+ does not imply silence or any default duration.+- Segments cannot nest — every Segment is a top-level child of `<script>`.+- Segment names follow XML naming rules: letters, digits, hyphens, underscores.++Other components reference individual Segments via `{story.segment.opening}` and their text+projections via `{story.segment.opening.dialogue}` or `{story.segment.opening.speech}`.++## Role Cues++Role Cues identify **who says what** inside a Segment. They are not speaker entities, do not select a+voice, and do not create characters.++```svml+<dialogue>+ <ALICE> What time is it?+ <BOB> It's 8:30.+</dialogue>+```++- A Role Cue has **no close tag**. A turn continues until the next Role Cue or the end of the Segment.+- A Segment must be either entirely with or entirely without Role Cues — mixing is an error.+- The label is 1–32 characters.++Role Cues produce different text projections:++| Projection | Output for the example above |+|---|---|+| **dialogue** | `ALICE: What time is it?`<br>`BOB: It's 8:30.` |+| **speech** | `What time is it?`<br>`It's 8:30.` |+| **caption** | `What time is it?`<br>`It's 8:30.` |++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++When what is displayed on screen differs from what is spoken:++```svml+<explanation>+ <HOST> We call it <SVML | semantic video markup language>.+</explanation>+```++The left side goes to the **caption** projection; the right side goes to **dialogue** and **speech**.++| Projection | Output |+|---|---|+| **caption** | `We call it SVML.` |+| **speech** | `We call it semantic video markup language.` |++An empty left side is legal:++```svml+<HOST> I was < | um> saying that this works.+```++This means "um" is spoken but never displayed as a caption. The two sides can have different word+counts — this is an N:M text mapping, not a 1:1 substitution.++## Selections++Selections are named time **ranges** declared inline:++```svml+<script id="story">+ @whole+ <opening>+ <HOST> @problem Current tools make agents operate a timeline. @/problem+ </opening>++ <answer>+ <HOST> @solution SVML removes that editing loop. @/solution+ </answer>+ @/whole~+</script>+```++### Syntax++| Marker | Meaning |+|---|---|+| `@id` | Open, right-absorbing (starts at the next word) |+| `~@id` | Open, left-absorbing (starts at the previous word's end) |+| `@/id` | Close, left-absorbing (ends at the previous word's end) |+| `@/id~` | Close, right-absorbing (ends at the next word's start) |++The `~` suffix/prefix controls whether the boundary snaps to the left or right. Default open is+right-absorbing; default close is left-absorbing.++### Non-contiguous Selections++The same id can appear multiple times to create a Selection with gaps:++```svml+<demo>+ <HOST> @beat First point. @/beat Then something else. @beat Third point. @/beat+</demo>+```++`{story.selection.beat}` now covers two disjoint ranges.++### Crossing Selections++Selections are not required to nest like XML tags. They can cross each other:++```svml+<demo>+ <HOST> @a One @b two @/a three @/b.+</demo>+```++Selection markers are zero-width and never appear in any text projection. They compile into+`SelectionSet` values containing `Range[]`. Script itself contains no seconds or frame numbers —+timing comes from WhisperX alignment.++Other components reference Selections via `{story.selection.problem}` to bind visual content to+semantic moments in the narrative.++## Moments++Moments are named time **points** (not ranges):++```svml+<ecosystem>+ <HOST> @ranking! Image generation, video generation, captions and B-roll+ all become reusable components.+</ecosystem>+```++| Marker | Meaning |+|---|---|+| `@id!` | Right-absorbing (point at the next word's start) |+| `~@id!` | Left-absorbing (point at the previous word's end) |++Moments compile into `MomentSet` values containing `Point[]`. Selection and Moment share the same+name namespace — the same id cannot be used for both.++Other components reference Moments via `{story.moment.ranking}`.++## Slots++Variable interpolation for templated Scripts:++```svml+<intro>+ <HOST> Meet <${product} | ${product_pronunciation}>.+</intro>+```++Slot ids are 1–64 characters, starting with a letter or underscore. Binding values are literal+text — they cannot inject SVML syntax. Slots are parsed first, then bound.++## Comments and escaping++```svml+<!-- This is a comment. Comments never enter any projection. -->++<demo>+ <HOST> Follow us \@svml on social media.+</demo>+```++Reserved syntax starters must be escaped:++| Escape | Produces |+|---|---|+| `\@` | literal `@` |+| `\<` | literal `<` |+| `\${` | literal `${` |+| `\\` | literal `\` |++Inside Dual Text, also escape `\|` and `\>`.++## Combination example++A complete Script using all constructs together:++```svml+<script id="story">+ @whole+ <hook>+ <HOST> @problem Girls, you need to hear this. Never let anyone take credit+ for your work. @/problem+ </hook>++ <meeting>+ <HOST> @solution Then I found <Echo Pro | echo pro>: a card-sized recorder+ that snaps onto the back of my phone. @ranking! I brought it to one+ meeting. @/solution+ </meeting>++ <evidence>+ <HOST> That gave me @emphasis the courage I was missing @/emphasis.+ </evidence>++ <payoff>+ <HOST> And guess what? I'm sitting in my old boss's chair now.+ </payoff>+ @/whole~+</script>+```++This Script declares:++- Four Segments: `hook`, `meeting`, `evidence`, `payoff`+- One Role Cue: `HOST` (consistent across all Segments)+- One Dual Text: `<Echo Pro | echo pro>` (displayed as "Echo Pro", spoken as "echo pro")+- Three Selections: `whole` (entire Script), `problem`, `solution`, `emphasis`+- One Moment: `ranking` (marks the instant "I brought it to one meeting")++Downstream components reference these by name: `{story.segment.hook.dialogue}` for generation,+`{story.selection.problem}` for B-roll timing, `{story.moment.ranking}` for a visual card reveal.diff --git a/docs/quickstart/styles.md b/docs/quickstart/styles.mdnew file mode 100644index 00000000..7e18dfdd--- /dev/null+++ b/docs/quickstart/styles.md@@ -0,0 +1,400 @@+---+title: SVS Stylesheets+description: The SVS Recipe language — CSS-like stylesheets for film, caption, B-roll, text and generation settings.+---++# SVS Stylesheets++SVS (`.svs`) files define reusable, typed configuration values using a CSS-like syntax. They+configure film dimensions, caption appearance, B-roll layout, text styling, speech estimation+parameters, generation settings, and custom fonts. SVS values are called **Recipes** — they are+immutable typed Records that consuming components validate and interpret.++## Basic syntax++```svs+<?svml using="@narratage/svs@1"?>++<sheet version="1" id="studio">+ film.vertical {+ width: 1080;+ height: 1920;+ frame-rate: 30;+ background: #09090B;+ }++ /* Comments use CSS-style block syntax. */+ caption.primary {+ fill: #FFFFFF;+ size: 58;+ }+</sheet>+```++- The processing instruction `<?svml using="@narratage/svs@1"?>` selects the SVS parser.+- The `<sheet>` element wraps all declarations. The `id` attribute becomes the top-level namespace.+- Each block is `namespace.name { ... }` with `;`-terminated key-value properties.+- Comments use `/* ... */`.++## Importing and referencing++Import an SVS file in your `.svml` source with a namespace prefix:++```svml+<import as="studio" source="./studio.svs"/>+```++Then reference individual Recipes via `{studio.film.vertical}`, `{studio.caption.primary}`, etc.+The prefix comes from the `as=` attribute; the path comes from `namespace.name` in the sheet.++## Film++Film appearance — canvas dimensions and background color.++```svs+film.vertical {+ width: 1080;+ height: 1920;+ frame-rate: 30;+ background: #09090B;+}+```++| Property | Description |+|---|---|+| `width` | Canvas width in pixels |+| `height` | Canvas height in pixels |+| `frame-rate` | Frames per second (typically 30) |+| `background` | Canvas clear color (hex) |++Referenced by `film:Film` via the `appearance` attribute:++```svml+<film:Film id="main" space={speech.space} appearance={studio.film.vertical}>+```++## Caption++Caption visual appearance — position, typography, and container styling.++```svs+caption.dialogue {+ stack-order: 70;+ x: 0.08;+ y: 0.76;+ width: 0.84;+ font: Inter;+ weight: 600;+ size: 58;+ line-height: 0.96;+ align: center;+ fill: #FFFFFF;+ background: #09090BCC;+ padding: 16 24;+ radius: 18;+}+```++| Property | Description |+|---|---|+| `stack-order` | Z-stacking order among all Tracks (higher = on top) |+| `x`, `y` | Position as fraction of canvas (0–1) |+| `width` | Width as fraction of canvas |+| `font` | Font family name or SVS font reference |+| `weight` | Font weight (400–900) |+| `size` | Font size in pixels |+| `line-height` | Line height multiplier |+| `align` | Text alignment: `left`, `center`, `right` |+| `fill` | Text color (hex, supports alpha) |+| `background` | Container background color (hex, supports alpha like `#09090BCC`) |+| `padding` | Container padding in pixels (single value or `vertical horizontal`) |+| `radius` | Container border radius in pixels |++Referenced by `caption:Style` via the `appearance` attribute:++```svml+<caption:Style id="primary-caption" appearance={studio.caption.dialogue}>+```++### Per-role caption styles++Define multiple caption Recipes for different speakers:++```svs+caption.alice {+ stack-order: 70;+ x: 0.08; y: 0.76; width: 0.84;+ font: Inter; weight: 600; size: 58;+ fill: #73FBD3;+ background: #09090BCC;+ padding: 16 24; radius: 18;+}++caption.bob {+ stack-order: 70;+ x: 0.08; y: 0.76; width: 0.84;+ font: Inter; weight: 600; size: 58;+ fill: #FFD166;+ background: #09090BCC;+ padding: 16 24; radius: 18;+}+```++Then assign them via `caption:Program`:++```svml+<caption:Program id="caption-program" narrative={story} default={studio.caption.dialogue}>+ <caption:Use role="ALICE" style={alice-caption}/>+ <caption:Use role="BOB" style={bob-caption}/>+</caption:Program>+```++## B-roll++B-roll item appearance — position, fit, container, and enter/exit animations.++```svs+broll.product {+ stack-order: 40;+ x: 0.08;+ y: 0.20;+ width: 0.84;+ height: 0.48;+ fit: contain;+ background: #111116;+ radius: 28;+ enter: slide-up 8f;+ exit: fade 6f;+}+```++| Property | Description |+|---|---|+| `stack-order` | Z-stacking order |+| `x`, `y` | Position as fraction of canvas |+| `width`, `height` | Size as fraction of canvas |+| `fit` | How the source fits the container: `cover`, `contain` |+| `background` | Container background color |+| `radius` | Container border radius |+| `enter` | Enter animation: `slide-up Nf`, `fade Nf` (N = frames) |+| `exit` | Exit animation: `fade Nf`, `slide-down Nf` |++Referenced by `broll:Item` via the `appearance` attribute:++```svml+<broll:Item source={motion.video} during={story.selection.demo}+ appearance={studio.broll.product}/>+```++## Text++Text overlay appearance — position, typography.++```svs+text.title {+ stack-order: 90;+ x: 0.06;+ y: 0.06;+ width: 0.88;+ height: 0.10;+ font: Inter;+ weight: 900;+ size: 64;+ align: center;+ fill: #FFFFFF;+ tracking: -1;+}+```++| Property | Description |+|---|---|+| `stack-order` | Z-stacking order |+| `x`, `y` | Position as fraction of canvas |+| `width`, `height` | Size as fraction of canvas |+| `font` | Font family name |+| `weight` | Font weight |+| `size` | Font size in pixels |+| `align` | Text alignment |+| `fill` | Text color |+| `tracking` | Letter spacing adjustment |++Referenced by `text:Item` via the `appearance` attribute:++```svml+<text:Item text="MEANING" during="full" appearance={studio.text.title}/>+```++## Speech estimation++Parameters for deterministic speech duration estimation.++```svs+speech.normal {+ language: en;+ pace: normal;+ padding: 0.3;+ min: 4;+ max: 15;+ rounding: ceil;+}+```++| Property | Description |+|---|---|+| `language` | Language code (e.g. `en`) |+| `pace` | Speaking pace: `slow`, `normal`, `fast` |+| `padding` | Extra padding in seconds added to the estimate |+| `min` | Minimum duration in seconds |+| `max` | Maximum duration in seconds |+| `rounding` | Rounding mode: `ceil`, `floor`, `round` |++Referenced by `estimate:Speech` via the `policy` attribute:++```svml+<estimate:Speech id="hook-duration" source={story.segment.hook.speech}+ policy={studio.speech.normal}/>+```++## Speaker++Seedance Speaker generation settings — the Recipe that controls how `speaker:Take` generates a+talking-head clip.++```svs+speaker.echo-pro {+ kind: ugc-talking-head;+ model: mini;+ resolution: 720p;+ aspect-ratio: 9:16;+ composition-stability: soft-locked;+ camera-motion: none;+ edit-rhythm: continuous-take;+ performance: natural-explainer;+ gesture: natural;+ voice-mode: single-speaker;+}+```++| Property | Description |+|---|---|+| `kind` | Generation kind (e.g. `ugc-talking-head`) |+| `model` | Model name: `mini` |+| `resolution` | Output resolution: `480p`, `720p`, `1080p` |+| `aspect-ratio` | Output aspect ratio: `9:16`, `16:9`, `1:1` |+| `composition-stability` | Camera/composition consistency: `flexible-ugc`, `soft-locked`, `strict-locked` |+| `camera-motion` | Camera movement: `none`, `subtle-punch-in-return` |+| `edit-rhythm` | Editing style: `continuous-take`, `pause-trim-jump-cuts` |+| `performance` | Acting style: `natural-explainer`, `high-energy-ugc`, `calm-authority`, `reactive-playful` |+| `gesture` | Gesture intensity: `restrained`, `compact`, `natural`, `expressive` |+| `voice-mode` | Voice configuration: `single-speaker` |++Referenced by `speaker:Take` via the `recipe` attribute:++```svml+<speaker:Take id="hook-take" dialogue={story.segment.hook.dialogue}+ duration={hook-duration.duration} recipe={studio.speaker.echo-pro} kit={ugc.official-ugc-v1}>+```++## Font declarations++Declare local font files for use in captions and text overlays.++```svs+font.inter-semibold {+ src: ./assets/Inter-SemiBold.woff2;+ weight: 600;+ style: normal;+}++font.inter-black {+ src: ./assets/Inter-Black.woff2;+ weight: 900;+ style: normal;+}+```++| Property | Description |+|---|---|+| `src` | Path to the font file (relative to the SVS file) |+| `weight` | Font weight this file provides |+| `style` | Font style: `normal`, `italic` |++Font paths are resolved at compile time and become `FontArtifactRef` values. Reference them by name+in other SVS blocks:++```svs+caption.dialogue {+ font: inter-semibold;+ /* ... */+}+```++## Combination example++A complete `studio.svs` file for a four-take talking-head project:++```svs+<?svml using="@narratage/svs@1"?>++<sheet version="1" id="studio">+ speech.normal {+ language: en;+ pace: normal;+ padding: 0.3;+ min: 4;+ max: 15;+ rounding: ceil;+ }++ speaker.echo-pro {+ kind: ugc-talking-head;+ model: mini;+ resolution: 720p;+ aspect-ratio: 9:16;+ composition-stability: soft-locked;+ camera-motion: none;+ edit-rhythm: continuous-take;+ performance: natural-explainer;+ gesture: natural;+ voice-mode: single-speaker;+ }++ film.vertical {+ width: 720;+ height: 1280;+ frame-rate: 30;+ background: #09090B;+ }++ caption.primary {+ stack-order: 70;+ x: 0.08;+ y: 0.74;+ width: 0.84;+ font: Inter;+ weight: 800;+ size: 44;+ line-height: 1;+ align: center;+ fill: #FFFFFF;+ background: #09090BCC;+ padding: 14 20;+ radius: 16;+ }+</sheet>+```++This file is imported once in the `.svml` source and its values are referenced throughout:++```svml+<import as="studio" source="./studio.svs"/>++<estimate:Speech id="hook-duration" source={story.segment.hook.speech}+ policy={studio.speech.normal}/>++<speaker:Take id="hook-take" ... recipe={studio.speaker.echo-pro} .../>++<caption:Style id="primary-caption" appearance={studio.caption.primary} .../>++<film:Film id="main" space={speech.space} appearance={studio.film.vertical}>+```diff --git a/docs/quickstart/timing.md b/docs/quickstart/timing.mdnew file mode 100644index 00000000..a11dbc39--- /dev/null+++ b/docs/quickstart/timing.md@@ -0,0 +1,161 @@+---+title: Timing & Assembly+description: Speech Spine assembly and WhisperX alignment — connecting generated takes to a unified timeline.+---++# Timing & Assembly++After generation, individual takes must be concatenated into one continuous A/V coordinate space,+and the spoken words must be measured against the actual audio to create a timing map. These two+steps produce the **ProgramSpace** and **SemanticMap** that every downstream component depends on.++```svml+<import as="speech" from="@narratage/speech-spine@1"/>+<import as="whisperx" from="@narratage/whisperx@1"/>+```++## speech:Spine++Concatenates multiple takes into one ordered audio/visual coordinate space. The Spine defines the+program order — the final sequence of Segments in the finished video.++```svml+<speech:Spine id="speech">+ <speech:Take source={hook-take.video} segment={story.segment.hook}/>+ <speech:Take source={meeting-take.video} segment={story.segment.meeting}/>+ <speech:Take source={evidence-take.video} segment={story.segment.evidence}/>+ <speech:Take source={payoff-take.video} segment={story.segment.payoff}/>+</speech:Spine>+```++| Attribute | Required | Description |+|---|---|---|+| `id` | yes | Unique identifier |++### speech:Take++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. |+| `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+time zero; each subsequent take follows immediately.++### Outputs++The Spine produces four outputs used by downstream components:++| Output | Type | Used by |+|---|---|---|+| `{speech.visual}` | VisualTrack | `film:Film` — the full-screen talking-head video |+| `{speech.audio}` | Audio | `whisperx:Alignment` — raw audio for word timing |+| `{speech.audioTrack}` | AudioTrack | `film:Film` — the synchronized audio |+| `{speech.space}` | ProgramSpace | Everything — the unified duration and frame domain |++## whisperx:Alignment++Measures word-level timing by running WhisperX speech-to-text alignment on the Spine's audio output.+This produces the **SemanticMap** — the bridge between Script text and physical time.++```svml+<whisperx:Alignment id="timing" narrative={story} audio={speech.audio}/>+```++| Attribute | Required | Description |+|---|---|---|+| `id` | yes | Unique identifier |+| `narrative` | yes | The Script component — e.g. `{story}` |+| `audio` | yes | Audio from the Speech Spine — `{speech.audio}` |++### Output++| Output | Type | Used by |+|---|---|---|+| `{timing.map}` | CompleteSemanticMap | `caption:Track`, `broll: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+in the Script become real time ranges and points for downstream visual components.++## ProgramSpace++ProgramSpace is not a component you declare — it is produced by `speech:Spine` and flows to every+component that needs to know the total program duration and frame domain.++```svml+<film:Film id="main" space={speech.space} ...>+<caption:Track id="captions" ... space={speech.space} .../>+<text:Track id="titles" space={speech.space}>+<render:Video id="final" composition={main.composition} space={speech.space}/>+```++ProgramSpace owns:++- **Duration** — the total program length+- **Frame rate** — rational frame rate (e.g. 30fps)+- **Frame domain** — exact frame numbers for the entire program++Every component that operates in the time domain takes a `space` attribute pointing to+`{speech.space}`.++## SemanticMap++The SemanticMap is the typed bridge between Script text and physical time. When you write+`during={story.selection.demo}` on a B-roll 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.++Components that use the map take it via the `map` attribute:++```svml+<broll:Track id="cards" map={timing.map} ...>+<caption:Track id="captions" ... map={timing.map} .../>+```++Each point in the map can be:++- **measured** — directly observed by WhisperX alignment+- **derived** — computed from measured points via interpolation+- **estimated** — from the initial duration estimate (used before alignment runs)++## Combination example++The complete timing stage, from generated takes to map and space:++```svml+<import as="speech" from="@narratage/speech-spine@1"/>+<import as="whisperx" from="@narratage/whisperx@1"/>++<!-- Assemble takes in program order -->+<speech:Spine id="speech">+ <speech:Take source={opening-take} segment={story.segment.opening}/>+ <speech:Take source={answer-take} segment={story.segment.answer}/>+</speech:Spine>++<!-- Measure word timing -->+<whisperx:Alignment id="timing" narrative={story} audio={speech.audio}/>++<!-- Downstream components now reference: -->+<!-- {speech.space} — ProgramSpace for duration/frame domain -->+<!-- {speech.visual} — VisualTrack for the talking-head video -->+<!-- {speech.audioTrack} — AudioTrack for synchronized audio -->+<!-- {timing.map} — SemanticMap for Selection/Moment timing -->+```++The data flow:++```text+speaker:Take outputs ──► speech:Spine ──► whisperx:Alignment+ │ │+ .visual .map (SemanticMap)+ .audio │+ .audioTrack ▼+ .space ──────────► caption:Track+ │ broll:Track+ │ text:Track+ ▼ film:Film+ film:Film render:Video+```diff --git a/docs/quickstart/tracks.md b/docs/quickstart/tracks.mdnew file mode 100644index 00000000..a4f11cfa--- /dev/null+++ b/docs/quickstart/tracks.md@@ -0,0 +1,357 @@+---+title: Caption, B-roll & Text+description: Visual track components — captions, B-roll overlays and text overlays.+---++# Caption, B-roll & Text++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 the three main visual Track types: captions, B-roll, and text overlays.++## Caption system++Captions are built from four components that form a pipeline:++```text+caption:Style → caption:Program → caption-ai:Planner → caption:Track+```++```svml+<import as="caption" from="@narratage/caption@1"/>+<import as="caption-ai" from="@narratage/caption-gemini@1"/>+```++### caption:Style++Declares a complete visual appearance plus planning instructions for one style of caption.++```svml+<caption:Style id="primary-caption" appearance={studio.caption.primary}+ mode="proportional-word">+ <caption:Cues>+ Split each Script Segment into short complete semantic phrases of two to+ seven words. Never cross a sentence or Segment boundary.+ </caption:Cues>+ <caption:Field id="important" type="boolean" min-per-cue="1" max-per-cue="2">+ Select one or two words whose emphasis best communicates this Cue.+ </caption:Field>+</caption:Style>+```++| Attribute | Required | Description |+|---|---|---|+| `id` | yes | Unique identifier |+| `appearance` | yes | SVS caption Recipe — position, font, colors, container |+| `mode` | no | Caption timing mode, e.g. `proportional-word` |++**Children:**++- `<caption:Cues>` — natural-language instructions for the AI planner telling it how to split text+ into cues. The planner receives display text (left side of Dual Text) and these instructions, but+ never audio or timing data.+- `<caption:Field>` — declares a typed per-atom annotation. The planner assigns these fields to+ individual words within each cue.++| `<caption:Field>` attribute | Description |+|---|---|+| `id` | Field name (e.g. `important`) |+| `type` | Field type: `boolean` |+| `min-per-cue` | Minimum annotations per cue |+| `max-per-cue` | Maximum annotations per cue |++The element body of `<caption:Field>` is a natural-language instruction for the planner.++### caption:Program++Assigns caption styles to the narrative. Declares a default style and optional per-role or+per-Selection overrides.++```svml+<caption:Program id="caption-program" narrative={story} default={primary-caption}>+ <caption:Use role="ALICE" style={alice-caption}/>+ <caption:Use role="BOB" style={bob-caption}/>+ <caption:Use on={story.selection.product-demo} style={dialogue-caption}/>+</caption:Program>+```++| Attribute | Required | Description |+|---|---|---|+| `id` | yes | Unique identifier |+| `narrative` | yes | The Script component |+| `default` | yes | Default `caption:Style` for all text |++**Children:**++`<caption:Use>` applies style overrides. Rules are applied in source order — last match wins.++| `<caption:Use>` attribute | Description |+|---|---|+| `role` | Match by Role Cue label (e.g. `"ALICE"`) |+| `on` | Match by Selection reference (e.g. `{story.selection.product-demo}`) |+| `style` | The `caption:Style` to apply |++Use `role=` to give different speakers different caption colors. Use `on=` to override style during+specific Selections (e.g. a product demo section uses a different caption style).++### caption-ai:Planner++AI-driven cue planning via Gemini. The planner receives the display text atoms, the Style+instructions, and the Program assignments. It splits text into cues and assigns Field values.++```svml+<caption-ai:Planner id="caption-plan" narrative={story}+ program={caption-program} model="gemini-2.5-flash"/>+```++| Attribute | Required | Description |+|---|---|---|+| `id` | yes | Unique identifier |+| `narrative` | yes | The Script component |+| `program` | yes | The `caption:Program` |+| `model` | yes | Gemini model: `gemini-2.5-flash` |++The planner never receives audio, timing data, or the speech side of Dual Text. It works entirely+from the caption (display) projection.++**Output:** `{caption-plan.plan}` — the cue plan, passed to `caption:Track`.++### caption:Track++Joins the cue plan, SemanticMap, ProgramSpace, and Program to produce a timed VisualTrack.++```svml+<caption:Track id="captions" narrative={story} map={timing.map}+ space={speech.space} program={caption-program} plan={caption-plan.plan}/>+```++| Attribute | Required | Description |+|---|---|---|+| `id` | yes | Unique identifier |+| `narrative` | yes | The Script component |+| `map` | yes | SemanticMap from `whisperx:Alignment` |+| `space` | yes | ProgramSpace from `speech:Spine` |+| `program` | yes | The `caption:Program` |+| `plan` | yes | Cue plan from `caption-ai:Planner` |++**Output:** `{captions.track}` — a VisualTrack added to `film:Film`.++### Caption combination example++The full caption pipeline with per-role styles:++```svml+<caption:Style id="dialogue-caption" appearance={studio.caption.dialogue}>+ <caption:Cues>Use short complete semantic phrases, two to five words.</caption:Cues>+</caption:Style>++<caption:Style id="alice-caption" appearance={studio.caption.alice}>+ <caption:Cues>Use short complete semantic phrases, two to five words.</caption:Cues>+ <caption:Field id="important" type="boolean" min-per-cue="0" max-per-cue="2">+ Select at most two words whose emphasis best communicates this Cue.+ </caption:Field>+</caption:Style>++<caption:Style id="bob-caption" appearance={studio.caption.bob}>+ <caption:Cues>Use short complete semantic phrases, two to five words.</caption:Cues>+</caption:Style>++<caption:Program id="caption-program" narrative={story} default={dialogue-caption}>+ <caption:Use role="ALICE" style={alice-caption}/>+ <caption:Use role="BOB" style={bob-caption}/>+ <caption:Use on={story.selection.product-demo} style={dialogue-caption}/>+</caption:Program>++<caption-ai:Planner id="caption-plan" narrative={story}+ program={caption-program} model="gemini-2.5-flash"/>++<caption:Track id="captions" narrative={story} map={timing.map}+ space={speech.space} program={caption-program} plan={caption-plan.plan}/>+```++ALICE gets green captions (`#73FBD3`), BOB gets gold (`#FFD166`), and during the product-demo+Selection both switch to the neutral dialogue style. The `important` Field only applies to ALICE's+style — her emphasized words get special treatment.++## B-roll++B-roll overlays generated or provided video/images at semantic time positions.++```svml+<import as="broll" from="@narratage/broll@1"/>+```++### broll:Track++Container for B-roll items. Takes the SemanticMap for timing resolution.++```svml+<broll:Track id="product-broll" map={timing.map} space={speech.space}>+ <broll:Item source={product-motion.video}+ during={story.selection.product-demo}+ appearance={studio.broll.product}/>+</broll:Track>+```++| Attribute | Required | Description |+|---|---|---|+| `id` | yes | Unique identifier |+| `map` | yes | SemanticMap from `whisperx:Alignment` |+| `space` | no | ProgramSpace (required by some configurations) |++### broll:Item++Each item places a source at a semantic time position with styled appearance:++```svml+<broll:Item source={product-motion.video}+ during={story.selection.product-demo}+ appearance={studio.broll.product}/>+```++| Attribute | Required | Description |+|---|---|---|+| `source` | yes | Video or image — from `seedance:Video`, `media:Image`, etc. |+| `during` | yes | Selection reference — when this item appears |+| `appearance` | yes | SVS broll Recipe — position, size, fit, animations |++The `during` attribute takes a Selection reference like `{story.selection.product-demo}`. The B-roll+item appears on screen for exactly the duration of that Selection, as resolved through the+SemanticMap.++The appearance Recipe controls enter/exit animations:++```svs+broll.product {+ stack-order: 40;+ x: 0.08; y: 0.20; width: 0.84; height: 0.48;+ fit: contain;+ background: #111116;+ radius: 28;+ enter: slide-up 8f;+ exit: fade 6f;+}+```++**Output:** `{product-broll.visual}` — a VisualTrack added to `film:Film`.++### B-roll example++B-roll with a generated Seedance video appearing during a Script Selection:++```svml+<seedance:Prompt id="product-direction">+ A clean vertical product film: the written script becomes semantic regions,+ then those regions assemble into a finished video.+</seedance:Prompt>++<seedance:Video id="product-motion" model="mini"+ prompt={product-direction} duration="5">+ <seedance:Reference image={product-reference} role="subject"/>+</seedance:Video>++<broll:Track id="product-broll" map={timing.map}>+ <broll:Item source={product-motion.video}+ during={story.selection.product-demo}+ appearance={studio.broll.product}/>+</broll:Track>+```++## Text overlays++Static or timed text displayed on screen — titles, callouts, lower thirds.++```svml+<import as="text" from="@narratage/text-track@1"/>+```++### text:Track++Container for text items.++```svml+<text:Track id="titles" space={speech.space}>+ <text:Item text="EDIT MEANING, NOT TIMELINES" during="full"+ appearance={studio.text.title}/>+</text:Track>+```++| Attribute | Required | Description |+|---|---|---|+| `id` | yes | Unique identifier |+| `space` | yes | ProgramSpace from `speech:Spine` |+| `map` | no | SemanticMap — needed when items use Selection-based timing |++### text:Item++Each item is a text string placed at a time position:++```svml+<text:Item text="MEANING" during="full" appearance={studio.text.title}/>+```++| Attribute | Required | Description |+|---|---|---|+| `text` | yes | The text string to display |+| `during` | yes | When to show: `"full"` (entire program) or a Selection reference |+| `appearance` | yes | SVS text Recipe — position, font, size, color |++The `during` attribute accepts either the literal string `"full"` for the entire program duration, or+a Selection reference for semantic timing:++```svml+<text:Track id="callout" space={speech.space} map={timing.map}>+ <text:Item text="EXACTLY THE RIGHT MOMENT"+ during={story.selection.callout}+ appearance={studio.text.callout}/>+</text:Track>+```++**Output:** `{titles.track}` — a VisualTrack added to `film:Film`.++## Combination example++All three track types together in one source file:++```svml+<import as="caption" from="@narratage/caption@1"/>+<import as="caption-ai" from="@narratage/caption-gemini@1"/>+<import as="broll" from="@narratage/broll@1"/>+<import as="text" from="@narratage/text-track@1"/>++<!-- Captions: primary style for all text -->+<caption:Style id="base-caption" appearance={studio.caption.base}>+ <caption:Cues>Prefer short complete semantic phrases.</caption:Cues>+ <caption:Field id="important" type="boolean" min-per-cue="0" max-per-cue="2">+ Select zero, one, or two words whose emphasis best communicates this Cue.+ </caption:Field>+</caption:Style>+<caption:Program id="caption-program" narrative={story} default={base-caption}/>+<caption-ai:Planner id="cue-plan" narrative={story}+ program={caption-program} model="gemini-2.5-flash"/>+<caption:Track id="captions" narrative={story} map={timing.map}+ space={speech.space} plan={cue-plan.plan} program={caption-program}/>++<!-- B-roll: generated video during a Selection -->+<broll:Track id="cards" map={timing.map} space={speech.space}>+ <broll:Item source={motion.video} during={story.selection.demo}+ appearance={studio.broll.card}/>+</broll:Track>++<!-- Text: persistent title overlay -->+<text:Track id="titles" space={speech.space}>+ <text:Item text="MEANING" during="full" appearance={studio.text.title}/>+</text:Track>++<!-- All three tracks feed into Film -->+<film:Film id="main" 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, B-roll at 40,+captions at 70, text at 90. Higher values render on top.diff --git a/docs/zh/quickstart.md b/docs/zh/quickstart.mdindex 76dec191..adaf6451 100644--- a/docs/zh/quickstart.md+++ b/docs/zh/quickstart.md@@ -35,17 +35,15 @@ pnpm testAuthor Source 说明*做什么*。Run Source 说明*要哪些*。Runtime Profile 说明*在哪里做*。-## 检查一张视频图(免费)+## 第一次图检查`talking-film-graph-check` 示例会编译一张完整的视频图 —— Script、Seedance、Speech、WhisperX、Gemini Caption、B-roll、Text、Film、HyperFrames —— 全程不调用任何外部服务。```bash-# 编译 Author Source。pnpm narratage check examples/talking-film-graph-check/main.svml \--package-lock examples/talking-film-graph-check/svml.packages.lock --root .-# 编译 Run Source 并查看冻结后的 plan。pnpm narratage plan examples/talking-film-graph-check/build.svrun \--package-lock examples/talking-film-graph-check/svml.packages.lock --root .```@@ -53,84 +51,17 @@ pnpm narratage plan examples/talking-film-graph-check/build.svrun \`check` 产出带类型的 Author Graph。`plan` 绑定 Author Graph 与 Run Graph,解析 Targets,并输出冻结的 BuildPlan —— 其中包含 Scheduler 将会发出的每一个 Operation 与 Needs。花钱之前先检查它。-## 跑一次真实的 Build(付费)--`echo-pro-aroll` 示例是一部由四条 take 构成的 Seedance Mini 口播人像影片。--前置条件:--- 环境变量中配置 `KIE_API_KEY`、`GOOGLE_CLOUD_PROJECT`、`GOOGLE_APPLICATION_CREDENTIALS_JSON`-- `ffmpeg`、`ffprobe`、Chrome-- 本地 WhisperX 服务正在运行(参见 `services/whisperx/README.md`)-- `examples/echo-pro-aroll/assets/` 下的本地素材(未纳入版本库)--```bash-# 诊断 Runtime 环境。-pnpm narratage doctor examples/echo-pro-aroll/svml.runtime.json--# 提交 Build。-pnpm narratage build examples/echo-pro-aroll/build.svrun \- --runtime examples/echo-pro-aroll/svml.runtime.json \- --package-lock examples/echo-pro-aroll/svml.packages.lock \- --root . \- --build-id echo-pro-film-001 \- --follow--# 取回最终视频。-pnpm narratage get echo-pro-film-001 \- --runtime examples/echo-pro-aroll/svml.runtime.json \- --name final.video \- --to examples/echo-pro-aroll/output/final.mp4-```--每一个被接受的中间 Record 与 Artifact 都会在 Build 完成之前归档。`get` 只是对一个已经持久化的-Record 做一次可选的复制。--## 复用既有结果--SVML 没有隐式缓存。复用结果是显式的 Run Graph 编写工作 —— 声明由历史 Records 支撑的零输入-Candidates,再用 Satisfaction edges 把它们接起来:--```xml-<?svml using="@narratage/run-text@1"?>-<svrun version="1" targets="delivery">- <author source="./main.svml"/>- <target-set id="delivery">- <target output="final.video" accepts="substitute"/>- </target-set>-- <build-record id="hook-video"- build="echo-pro-film-001" output="hook-take.video"/>- <satisfy output="hook-take.video"- candidate="hook-video" fidelity="substitute"/>-</svrun>-```--编译出的 plan 会剪掉所有被 substitute Candidates 取代的上游 Operations。这是一次新的 Build,-而不是对上一次的续跑。--```bash-pnpm narratage build examples/echo-pro-aroll/reuse-generated.svrun \- --runtime examples/echo-pro-aroll/svml.runtime.json \- --package-lock examples/echo-pro-aroll/svml.packages.lock \- --root . --build-id echo-pro-film-reuse-001 --follow-```--## CLI 参考--```text-narratage lock-packages <lock> --package name [--package name ...] [--root dir]-narratage doctor <runtime.json>-narratage gc <runtime.json> [--apply]-narratage check <source> [--package-lock file] [--root dir]-narratage plan <run-source> [--package-lock file] [--root dir]-narratage build <run-source> --runtime profile [--build-id id] [--follow]-narratage status <build-id> --runtime profile-narratage builds --runtime profile-narratage inspect <build-id> --runtime profile-narratage get <build-id> --runtime profile [--name x|--record x|--output x|--artifact x] [--to path]-narratage cancel <build-id> --runtime profile-```+## 指南目录++| 指南 | 主题 |+|---|---|+| [Script](./quickstart/script.md) | Segment、Role Cue、Dual Text、Selection、Moment、文字投影 |+| [SVS 样式表](./quickstart/styles.md) | CSS 风格的 Recipe:film、caption、B-roll、text、speech、字体 |+| [媒体与生成](./quickstart/generation.md) | media:Image、media:Audio、estimate:Speech、Seedance、speaker:Take |+| [时序与装配](./quickstart/timing.md) | speech:Spine、whisperx:Alignment、ProgramSpace、SemanticMap |+| [字幕、B-roll 与文字](./quickstart/tracks.md) | caption:Style/Program/Planner/Track、broll:Track、text:Track |+| [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.mdnew file mode 100644index 00000000..1c0e19f4--- /dev/null+++ b/docs/zh/quickstart/composition.md@@ -0,0 +1,235 @@+---+title: Film 与渲染+description: 将 Track 组合为 Film 并渲染为视频。+---++# Film 与渲染++Film 是最终的组装阶段。它接收所有对等的 Track,对其进行验证,并生成一个+Composition。然后渲染器将该 Composition 编译为 MP4 视频。++```svml+<import as="film" from="@narratage/film@1"/>+<import as="render" from="@narratage/render-hyperframes@1"/>+```++## film:Film++将所有 Track 组装为单一的 Composition。Film 本身没有领域知识——它不知道什么是字幕、+什么是 B-roll、什么是语音。它接收任何 VisualTrack 或 AudioTrack,并按堆叠顺序将它们分层。++```svml+<film:Film id="main" space={speech.space} appearance={studio.film.vertical}>+ <film:Track source={speech.visual}/>+ <film:Track source={speech.audioTrack}/>+ <film:Track source={captions.track}/>+ <film:Track source={product-broll.visual}/>+ <film:Track source={titles.track}/>+</film:Film>+```++| 属性 | 必填 | 说明 |+|---|---|---|+| `id` | 是 | 唯一标识符 |+| `space` | 是 | 来自 `speech:Spine` 的 ProgramSpace——定义时长和帧率 |+| `appearance` | 是 | SVS Film Recipe——画布宽度、高度、帧率、背景 |++### film:Track++每个 `<film:Track>` 子元素向 Composition 添加一个 Track 来源:++| 属性 | 必填 | 说明 |+|---|---|---|+| `source` | 是 | 来自任何上游组件的 VisualTrack 或 AudioTrack |++常见的 Track 来源:++| 来源 | 类型 | 来自 |+|---|---|---|+| `{speech.visual}` | VisualTrack | `speech:Spine`——全屏说话人画面 |+| `{speech.audioTrack}` | AudioTrack | `speech:Spine`——同步音频 |+| `{captions.track}` | VisualTrack | `caption:Track`——定时字幕 |+| `{cards.visual}` | VisualTrack | `broll:Track`——B-roll 叠加层 |+| `{titles.track}` | VisualTrack | `text:Track`——文字叠加层 |++### Track 堆叠++Track 是**扁平的**——没有嵌套或分组。Z 轴排序完全由每个 Track 的 SVS Recipe 中的+`stack-order` 属性决定。较低的值在后面;较高的值渲染在上面。++典型的堆叠顺序:++| stack-order | 内容 |+|---|---|+| 10 | 语音画面(全屏说话人画面) |+| 40 | B-roll 叠加层 |+| 70 | 字幕 |+| 90 | 文字叠加层 |++一个组件可以在不同的 z 位置发出多个视觉元素(Presents),这些元素会与其他组件的 Presents+交错排列。最终渲染会将所有 Presents 展平,按绝对堆叠键排序,然后绘制到一个画布上。++**输出:** `{main.composition}`——完整的 Composition,传递给渲染器。++## render:Video++通过 HyperFrames 渲染器将 Composition 编译为最终视频。++```svml+<render:Video id="final" composition={main.composition} space={speech.space}/>+```++| 属性 | 必填 | 说明 |+|---|---|---|+| `id` | 是 | 唯一标识符 |+| `composition` | 是 | 来自 `film:Film` 的 Composition |+| `space` | 是 | 来自 `speech:Spine` 的 ProgramSpace |++渲染器:++1. 将 Composition 编译为 `HyperframesDocument`——每一帧的 HTML 表示+2. 通过 Chrome/Chromium 渲染每一帧+3. 将帧序列编码为视频+4. 混合音频 Track+5. 将视频和音频混合封装为最终的 MP4++**输出:** `{final.video}`——最终的视频文件。这是最常见的 Build Target。++## 完整的管线流程++从 Script 到渲染视频的完整数据流。本示例基于+`examples/talking-film-graph-check/`——最小的完整图。++### Author Source (`main.svml`)++```svml+<?svml using="@narratage/text@1"?>++<svml>+ <import from="@narratage/script@1"/>+ <import as="seedance" from="@narratage/seedance@1"/>+ <import as="speech" from="@narratage/speech-spine@1"/>+ <import as="whisperx" from="@narratage/whisperx@1"/>+ <import as="caption" from="@narratage/caption@1"/>+ <import as="caption-ai" from="@narratage/caption-gemini@1"/>+ <import as="broll" from="@narratage/broll@1"/>+ <import as="text" from="@narratage/text-track@1"/>+ <import as="film" from="@narratage/film@1"/>+ <import as="render" from="@narratage/render-hyperframes@1"/>+ <import as="studio" source="./studio.svs"/>++ <!-- 1. Script: the semantic truth -->+ <script id="story">+ <opening><HOST>Meaning @demo becomes the source @/demo.</opening>+ </script>++ <!-- 2. Generation: Seedance talking head + standalone video -->+ <seedance:Prompt id="direction">+ Locked medium close-up in a quiet daylight studio.+ </seedance:Prompt>+ <seedance:Speech id="take" model="mini"+ dialogue={story.segment.opening.dialogue}+ prompt={direction} duration="5"/>+ <seedance:Video id="motion" model="mini"+ prompt={direction} duration="5"/>++ <!-- 3. Timing: assemble spine and align words -->+ <speech:Spine id="speech">+ <speech:Take source={take} segment={story.segment.opening}/>+ </speech:Spine>+ <whisperx:Alignment id="timing" narrative={story} audio={speech.audio}/>++ <!-- 4. Tracks: captions, B-roll, text -->+ <caption:Style id="base-caption" appearance={studio.caption.base}>+ <caption:Cues>Prefer short complete semantic phrases.</caption:Cues>+ <caption:Field id="important" type="boolean"+ min-per-cue="0" max-per-cue="2">+ Select zero, one, or two words whose emphasis best communicates+ this Cue.+ </caption:Field>+ </caption:Style>+ <caption:Program id="caption-program" narrative={story}+ default={base-caption}/>+ <caption-ai:Planner id="cue-plan" narrative={story}+ program={caption-program} model="gemini-2.5-flash"/>+ <caption:Track id="captions" narrative={story} map={timing.map}+ space={speech.space} plan={cue-plan.plan} program={caption-program}/>++ <broll:Track id="cards" map={timing.map} space={speech.space}>+ <broll:Item source={motion.video} during={story.selection.demo}+ appearance={studio.broll.card}/>+ </broll:Track>++ <text:Track id="titles" space={speech.space}>+ <text:Item text="MEANING" during="full"+ appearance={studio.text.title}/>+ </text:Track>++ <!-- 5. Film: compose all tracks -->+ <film:Film id="main" 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>++ <!-- 6. Render: compile to MP4 -->+ <render:Video id="final" composition={main.composition}+ space={speech.space}/>+</svml>+```++### 样式表 (`studio.svs`)++```svs+<?svml using="@narratage/svs@1"?>++<sheet version="1">+ film.vertical {+ width: 1080; height: 1920; frame-rate: 30; background: #09090B;+ }+ broll.card {+ stack-order: 40; x: 0.1; y: 0.2; width: 0.8; height: 0.5;+ fit: cover; background: #111116; radius: 20;+ enter: slide-up 4f; exit: fade 4f;+ }+ caption.base {+ stack-order: 70; x: 0.08; y: 0.76; width: 0.84;+ font: Inter; weight: 600; size: 58; line-height: 1; align: center;+ fill: #FFFFFF; background: #09090BCC; padding: 16 24; radius: 18;+ }+ text.title {+ stack-order: 90; x: 0.06; y: 0.06; width: 0.88; height: 0.1;+ font: Inter; weight: 900; size: 64; align: center;+ fill: #FFFFFF; tracking: -1;+ }+</sheet>+```++### Run Source (`build.svrun`)++```svml+<?svml using="@narratage/run-text@1"?>++<svrun version="1" targets="delivery">+ <author source="./main.svml"/>+ <target-set id="delivery">+ <target output="final.video" accepts="exact"/>+ </target-set>+</svrun>+```++### 编译与验证++```bash+pnpm narratage check examples/talking-film-graph-check/main.svml \+ --package-lock examples/talking-film-graph-check/svml.packages.lock --root .++pnpm narratage plan examples/talking-film-graph-check/build.svrun \+ --package-lock examples/talking-film-graph-check/svml.packages.lock --root .+```++`check` 编译 Author Graph——验证所有导入、类型和图的边,而不调用任何外部服务。`plan`+还会额外编译 Run Source 并输出冻结的 BuildPlan,展示调度器将发出的每个 Operation。在花费资金之前请先检查计划。diff --git a/docs/zh/quickstart/generation.md b/docs/zh/quickstart/generation.mdnew file mode 100644index 00000000..a091b3ed--- /dev/null+++ b/docs/zh/quickstart/generation.md@@ -0,0 +1,273 @@+---+title: 媒体与生成+description: 声明媒体资源并使用 Seedance 生成视频。+---++# 媒体与生成++本页介绍用于声明静态资源和生成新媒体的组件——这些是流入下游时序和 Track 阶段的原始素材。++此处展示的每个组件在使用前都必须通过包标识符导入:++```svml+<import as="media" from="@narratage/media@1"/>+<import as="estimate" from="@narratage/estimate@1"/>+<import as="seedance" from="@narratage/seedance@1"/>+<import as="speaker" from="@narratage/seedance-speaker@1"/>+```++## media:Image++声明一个来自本地文件的内容寻址图片资源。++```svml+<media:Image id="presenter" src="./assets/presenter.png"/>+```++| 属性 | 必填 | 说明 |+|---|---|---|+| `id` | 是 | 组件的唯一标识符 |+| `src` | 是 | 图片文件路径,相对于 `.svml` 源文件 |++该图片在下游通过 `{presenter}` 引用——例如,作为 `seedance:Speech` 中的角色参考或作为 B-roll 来源。++## media:Audio++声明一个来自本地文件的内容寻址音频资源。++```svml+<media:Audio id="presenter-voice" src="./assets/presenter-voice.mp3"/>+```++| 属性 | 必填 | 说明 |+|---|---|---|+| `id` | 是 | 唯一标识符 |+| `src` | 是 | 音频文件路径,相对于 `.svml` 源文件 |++通常用作 `speaker:Take` 的语音音色参考。++## estimate:Speech++基于 Script 文本的确定性语音时长估算。无需外部服务调用——估算根据字数和语速参数在本地计算。++```svml+<estimate:Speech id="hook-duration"+ source={story.segment.hook.speech}+ policy={studio.speech.normal}/>+```++| 属性 | 必填 | 说明 |+|---|---|---|+| `id` | 是 | 唯一标识符 |+| `source` | 是 | 要估算的 Script 文本——通常为 `{script.segment.NAME.speech}` |+| `policy` | 是 | 控制语速和边界的 SVS 语音 Recipe |++`policy` 引用一个 SVS Recipe(参见 [SVS 样式表](./styles.md#speech-estimation)):++```svs+speech.normal {+ language: en;+ pace: normal;+ padding: 0.3;+ min: 4;+ max: 15;+ rounding: ceil;+}+```++你也可以直接内联指定估算参数,而不使用 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"/>+```++**输出:** `{hook-duration.duration}`——估算的时长(秒),传递给生成组件。++## seedance:Prompt++一个可复用的文本块,为 Seedance 生成提供视觉指导。++```svml+<seedance:Prompt 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>+```++| 属性 | 必填 | 说明 |+|---|---|---|+| `id` | 是 | 唯一标识符 |++元素主体即为提示文本。通过 `seedance:Speech` 和 `seedance:Video` 的 `prompt` 属性引用。++## seedance:Speech++通过 Seedance 模型生成说话人头部视频片段。这是低层级的生成组件——直接指定对话、提示和时长。++```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>+```++| 属性 | 必填 | 说明 |+|---|---|---|+| `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:Reference++提供参考图片以保持角色一致性的子元素:++```svml+<seedance:Reference image={alice-reference} role="character"/>+```++| 属性 | 必填 | 说明 |+|---|---|---|+| `image` | 是 | 引用 `media:Image` 组件 |+| `role` | 是 | 该参考的用途:`character`、`subject` |++**输出:** `{alice-take}` 或 `{alice-take.video}`——生成的视频,传递给 `speech:Spine`。++## seedance:Video++生成独立的视频片段(非说话人头部——无对话口型同步)。++```svml+<seedance:Video id="product-motion" model="mini"+ prompt={product-direction} duration="5">+ <seedance:Reference image={product-reference} role="subject"/>+</seedance:Video>+```++| 属性 | 必填 | 说明 |+|---|---|---|+| `id` | 是 | 唯一标识符 |+| `model` | 是 | Seedance 模型名称:`mini` |+| `prompt` | 是 | 视觉指导——引用 `seedance:Prompt` |+| `duration` | 是 | 片段时长(秒) |++同样接受 `<seedance:Reference>` 子元素作为参考图片。++**输出:** `{product-motion.video}`——用作 B-roll 来源。++## speaker:Take++基于 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.echo-pro}+ kit={ugc.official-ugc-v1}>+ <speaker:Reference image={presenter-clean} role="character-and-scene"/>+ <speaker:Reference audio={presenter-voice} role="voice-timbre"/>+</speaker:Take>+```++| 属性 | 必填 | 说明 |+|---|---|---|+| `id` | 是 | 唯一标识符 |+| `dialogue` | 是 | Script 文本——通常为 `{script.segment.NAME.dialogue}` |+| `duration` | 是 | 来自 `estimate:Speech` 的估算时长 |+| `recipe` | 是 | SVS speaker Recipe(参见 [SVS 样式表](./styles.md#speaker)) |+| `kit` | 是 | Prompt Kit SVS——用于组装提示的模板 |++### speaker:Reference++提供参考媒体的子元素。同时接受图片和音频:++```svml+<speaker:Reference image={presenter-clean} role="character-and-scene"/>+<speaker:Reference audio={presenter-voice} role="voice-timbre"/>+```++| 属性 | 必填 | 说明 |+|---|---|---|+| `image` | image/audio 二选一 | 引用 `media:Image` |+| `audio` | image/audio 二选一 | 引用 `media:Audio` |+| `role` | 是 | 参考用途:`character-and-scene`、`voice-timbre` |++**输出:** `{hook-take.video}`——生成的视频,传递给 `speech:Spine`。++### Prompt Kits++Prompt Kit 是一种特殊的 SVS 文件,定义了包含有序块、变体选择、轴参数和 Slot 的结构化提示模板。官方 Kit 位于 `packages/seedance-speaker/kits/official-ugc-v1.svs`。++该 Kit 使用 Prompt Kit SVS 解析器导入:++```svs+<?svml using="@narratage/prompt-kit/svs@1"?>+```++`studio.svs` 中的 Recipe 设置轴参数值(composition-stability、camera-motion、edit-rhythm、performance、gesture、voice-mode),Kit 会自动将它们组装成完整的提示。++## 组合示例++一个四段拍摄的设置,估算时长作为输入传递给 `speaker:Take` 生成:++```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="studio" source="./studio.svs"/>+<import as="ugc" source="../../packages/seedance-speaker/kits/official-ugc-v1.svs"/>++<media:Image id="presenter-clean" src="./assets/presenter-clean.png"/>+<media:Image id="presenter-with-echo" src="./assets/presenter-with-echo.png"/>+<media:Audio id="presenter-voice" src="./assets/presenter-voice.mp3"/>++<estimate:Speech id="hook-duration"+ 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.echo-pro}+ 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.echo-pro}+ kit={ugc.official-ugc-v1}>+ <speaker:Reference image={presenter-with-echo} 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.echo-pro}+ kit={ugc.official-ugc-v1}>+ <speaker:Reference image={presenter-with-echo} 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.echo-pro}+ 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` 生成一个 `{*.video}` 输出,传递给下一阶段的 `speech:Spine`。不同的拍摄段可以使用不同的参考图片(例如,演示者在某些 Segment 中持有产品而在其他段中没有),同时共享相同的语音音色和生成 Recipe。diff --git a/docs/zh/quickstart/run.md b/docs/zh/quickstart/run.mdnew file mode 100644index 00000000..c28b422f--- /dev/null+++ b/docs/zh/quickstart/run.md@@ -0,0 +1,292 @@+---+title: Run Source 与 Build+description: 声明 Build 目标、复用结果以及配置运行时环境。+---++# Run Source 与 Build++Run Source(`.svrun`)声明**要构建什么**——需要哪些输出、接受什么保真度,以及可选地如何复用先前 Build 的结果。Runtime Profile(`svml.runtime.json`)声明**在哪里运行**——endpoint、凭证、并发数和权限。++这两者都不会改变视频**是什么**。那是 Author Source 的职责。++## Run Source 语法++每个 `.svrun` 文件都以其处理指令开头:++```svml+<?svml using="@narratage/run-text@1"?>+```++### 最简 Run Source++```svml+<?svml using="@narratage/run-text@1"?>++<svrun version="1" targets="delivery">+ <author source="./main.svml"/>+ <target-set id="delivery">+ <target output="final.video" accepts="exact"/>+ </target-set>+</svrun>+```++| 元素 | 说明 |+|---|---|+| `<svrun>` | 根元素。`version="1"`,`targets` 指定活跃的 target-set |+| `<author>` | 必需。`source` 指向 `.svml` Author Source |+| `<target-set>` | 一组命名的需求输出集合 |+| `<target>` | 单个需求输出:`output` 指定逻辑输出名,`accepts` 设置保真度 |++### Target++**Target** 指定 Build 所需的输出及其可接受的最低保真度:++- `accepts="exact"` ——输出必须与作者声明的完全一致+- `accepts="substitute"` ——允许使用可接受的替代品(例如先前生成的结果)++不存在特权化的"最终视频"根节点。任何组件的任何公开逻辑输出都可以作为 Target。编译器仅执行满足所需 Target 所必要的 Operation——其余一切均被裁剪。++### 多个 Target++可以在一次 Build 中请求多个输出:++```svml+<target-set id="delivery">+ <target output="final.video" accepts="exact"/>+ <target output="captions.track" accepts="exact"/>+</target-set>+```++也可以定义多个 target-set 并在它们之间切换:++```svml+<svrun version="1" targets="preview">+ <author source="./main.svml"/>++ <target-set id="preview">+ <target output="captions.track" accepts="substitute"/>+ </target-set>++ <target-set id="delivery">+ <target output="final.video" accepts="exact"/>+ </target-set>+</svrun>+```++`<svrun>` 上的 `targets` 属性选择当前活跃的集合。++## 复用结果++Narratage 没有隐式缓存。复用结果是显式的运行图编写——你将历史 Record 声明为零输入 Candidate,并通过 Satisfaction 边将它们连接起来。++```svml+<?svml using="@narratage/run-text@1"?>++<svrun version="1" targets="delivery">+ <author source="./main.svml"/>+ <target-set id="delivery">+ <target output="final.video" accepts="substitute"/>+ </target-set>++ <build-record id="hook-video"+ build="echo-pro-film-001" output="hook-take.video"/>+ <build-record id="meeting-video"+ build="echo-pro-film-001" output="meeting-take.video"/>+ <build-record id="evidence-video"+ build="echo-pro-film-001" output="evidence-take.video"/>+ <build-record id="payoff-video"+ build="echo-pro-film-001" output="payoff-take.video"/>++ <satisfy output="hook-take.video"+ candidate="hook-video" fidelity="substitute"/>+ <satisfy output="meeting-take.video"+ candidate="meeting-video" fidelity="substitute"/>+ <satisfy output="evidence-take.video"+ candidate="evidence-video" fidelity="substitute"/>+ <satisfy output="payoff-take.video"+ candidate="payoff-video" fidelity="substitute"/>+</svrun>+```++### build-record++声明一个由先前 Build 的历史 Record 支持的零输入 Candidate:++| 属性 | 说明 |+|---|---|+| `id` | 此 Run Source 内的本地 Candidate 标识符 |+| `build` | 先前 Build 的 build-id |+| `output` | 该 Build 中的逻辑输出名 |++### satisfy++将 Candidate 连接到逻辑输出:++| 属性 | 说明 |+|---|---|+| `output` | 要满足的逻辑输出 |+| `candidate` | Candidate 标识符(来自 `build-record`) |+| `fidelity` | `exact` 或 `substitute` |++编译后的计划会裁剪所有被替代 Candidate 取代的上游 Operation。这是一次新的 Build,而非旧 Build 的延续。下游处理(归一化、WhisperX、字幕生成、渲染)仍然会对复用的媒体执行。++### 保真度模型++- **`exact`** ——Candidate 与作者声明的内容精确匹配+- **`substitute`** ——Candidate 是一个可接受的替代品++替代保真度是**单调的**:一旦替代品进入图中,它会向下游传播。你无法将其恢复为 exact。如果最终 Target 接受 `substitute`,那么消费替代输入的下游 Operation 也会产生替代结果。++## Runtime Profile++Runtime Profile(`svml.runtime.json`)告诉系统**在哪里**执行每种类型的工作:++```json+{+ "format": "svml.runtime-config@1",+ "packageLock": "./svml.packages.lock",+ "runtimePackageLock": "./svml.runtime-packages.lock",+ "endpoints": [+ {+ "use": "@narratage/provider-kie",+ "instance": "kie.main",+ "lane": "generation",+ "config": {+ "apiKeyEnv": "KIE_API_KEY",+ "defaultConcurrency": 2+ }+ },+ {+ "use": "@narratage/provider-media-local",+ "instance": "media.main",+ "lane": "media",+ "config": { "defaultConcurrency": 2 }+ },+ {+ "use": "@narratage/provider-whisperx-local",+ "instance": "whisperx.main",+ "lane": "alignment",+ "config": { "defaultConcurrency": 1 }+ },+ {+ "use": "@narratage/provider-google-vertex",+ "instance": "vertex.main",+ "lane": "planning",+ "config": {+ "projectEnv": "GOOGLE_CLOUD_PROJECT",+ "credentialsEnv": "GOOGLE_APPLICATION_CREDENTIALS_JSON",+ "location": "global",+ "defaultConcurrency": 1+ }+ },+ {+ "use": "@narratage/provider-hyperframes-local",+ "instance": "hyperframes.main",+ "lane": "render",+ "config": {+ "workers": 2,+ "quality": "standard",+ "defaultConcurrency": 1+ }+ }+ ],+ "permissions": [+ "filesystem:whisperx-staging",+ "network:aiplatform.googleapis.com",+ "network:api.kie.ai",+ "network:kieai.redpandaai.co",+ "network:whisperx-loopback",+ "process:hyperframes",+ "process:media"+ ],+ "scheduling": {+ "maxConcurrency": 4,+ "lanes": {+ "generation": 2,+ "media": 2,+ "alignment": 1,+ "planning": 1,+ "render": 1+ }+ }+}+```++### Endpoint++每个 endpoint 将一个 Provider 包绑定到具有并发通道的命名实例:++| 字段 | 说明 |+|---|---|+| `use` | Provider 包名(例如 `@narratage/provider-kie`) |+| `instance` | 唯一的实例标识符 |+| `lane` | 用于并发控制的调度通道 |+| `config` | Provider 专属配置(API 密钥、并发数等) |++### 权限++对文件系统、网络和进程访问的显式授权。调度器会拒绝需要未在此列出的权限的 Operation。++### 调度++`maxConcurrency` 限制总的并行 Operation 数。`lanes` 设置每个通道的并发上限,以防止某一类工作饿死其他工作。++## Build 工作流++### 1. 诊断环境++```bash+pnpm narratage doctor examples/echo-pro-aroll/svml.runtime.json+```++Doctor 检查每个 endpoint 是否可达、凭证是否有效,以及所需的可执行文件(`ffmpeg`、`ffprobe`、Chrome)是否可用。++### 2. 检查计划++```bash+pnpm narratage plan examples/echo-pro-aroll/build.svrun \+ --package-lock examples/echo-pro-aroll/svml.packages.lock --root .+```++在花费资金之前审查冻结的 BuildPlan。该计划展示调度器将发出的每个 Operation 和 Needs。++### 3. 提交 Build++```bash+pnpm narratage build examples/echo-pro-aroll/build.svrun \+ --runtime examples/echo-pro-aroll/svml.runtime.json \+ --package-lock examples/echo-pro-aroll/svml.packages.lock \+ --root . \+ --build-id echo-pro-film-001 \+ --follow+```++| 标志 | 说明 |+|---|---|+| `--runtime` | Runtime Profile 的路径 |+| `--package-lock` | 包锁定文件的路径 |+| `--root` | 工作区根目录 |+| `--build-id` | 用户为此 Build 选择的标识符(用于检索和复用) |+| `--follow` | 将 Build 进度流式输出到终端 |++### 4. 获取结果++```bash+pnpm narratage get echo-pro-film-001 \+ --runtime examples/echo-pro-aroll/svml.runtime.json \+ --name final.video \+ --to examples/echo-pro-aroll/output/final.mp4+```++每个被接受的中间 Record 和 Artifact 在 Build 完成前都会被归档。`get` 会复制一份已持久化的 Record。++### 5. 在新 Build 中复用++创建一个引用已完成 Build 的 Record 的新 `.svrun` 文件(参见上文[复用结果](#复用结果)),然后提交:++```bash+pnpm narratage build examples/echo-pro-aroll/reuse-generated.svrun \+ --runtime examples/echo-pro-aroll/svml.runtime.json \+ --package-lock examples/echo-pro-aroll/svml.packages.lock \+ --root . --build-id echo-pro-film-reuse-001 --follow+```diff --git a/docs/zh/quickstart/script.md b/docs/zh/quickstart/script.mdnew file mode 100644index 00000000..11e568e2--- /dev/null+++ b/docs/zh/quickstart/script.md@@ -0,0 +1,245 @@+---+title: Script+description: Script Surface——Segment、Role Cue、Dual Text、Selection、Moment 与文本投影。+---++# Script++`<script>` 元素承载旁白或讲者说出的每一个字。Script 以**散文为先**:它不包含时间码、不引用媒体、不设定样式、不携带生成参数。管线中的其他组件都会读取 Script;Script 本身不读取任何内容。++```svml+<import from="@narratage/script@1"/>++<script id="story">+ <opening>+ <HOST> Hello world.+ </opening>+</script>+```++引入 `@narratage/script@1` 会激活 Script Surface。`id` 属性让其他组件可以引用该 Script 及其各部分。++## Segment++Segment 是按顺序排列的语音内容块。标签名**即**其 id——在同一个 Script 内必须唯一。++```svml+<script id="story">+ <opening>+ Hello world.+ </opening>++ <pause/>++ <middle>+ This is the second part.+ </middle>++ <close>+ Goodbye.+ </close>+</script>+```++- Segment 可以是自闭合标签(`<pause/>`)。空的 Segment 拥有结构但没有语音词元;它并不意味着静音或任何默认时长。+- Segment 不能嵌套——每个 Segment 都是 `<script>` 的顶层子元素。+- Segment 名称遵循 XML 命名规则:字母、数字、连字符、下划线。++其他组件通过 `{story.segment.opening}` 引用单个 Segment,通过 `{story.segment.opening.dialogue}` 或 `{story.segment.opening.speech}` 引用其文本投影。++## Role Cue++Role Cue 标识 Segment 内部**谁说了什么**。它们不是讲者实体,不选择语音,也不创建角色。++```svml+<dialogue>+ <ALICE> What time is it?+ <BOB> It's 8:30.+</dialogue>+```++- Role Cue **没有关闭标签**。一段话从当前 Role Cue 开始,延续到下一个 Role Cue 或 Segment 结尾为止。+- 一个 Segment 必须全部使用或全部不使用 Role Cue——混用会导致错误。+- 标签长度为 1–32 个字符。++Role Cue 会产生不同的文本投影:++| 投影 | 上例的输出 |+|---|---|+| **dialogue** | `ALICE: What time is it?`<br>`BOB: It's 8:30.` |+| **speech** | `What time is it?`<br>`It's 8:30.` |+| **caption** | `What time is it?`<br>`It's 8:30.` |++dialogue 投影包含 Role Cue 前缀。speech 和 caption 投影会去除前缀。像 `seedance:Speech` 这样的组件使用 `{story.segment.dialogue.dialogue}`(带标签),而 `caption:Track` 使用 caption 投影(不带标签)。++## Dual Text++当屏幕上显示的文字与实际说出的文字不同时:++```svml+<explanation>+ <HOST> We call it <SVML | semantic video markup language>.+</explanation>+```++左侧进入 **caption** 投影;右侧进入 **dialogue** 和 **speech** 投影。++| 投影 | 输出 |+|---|---|+| **caption** | `We call it SVML.` |+| **speech** | `We call it semantic video markup language.` |++左侧为空是合法的:++```svml+<HOST> I was < | um> saying that this works.+```++这意味着 "um" 会被说出但永远不会显示为字幕。两侧可以有不同的单词数量——这是一种 N:M 文本映射,而非 1:1 替换。++## Selection++Selection 是内联声明的具名时间**范围**:++```svml+<script id="story">+ @whole+ <opening>+ <HOST> @problem Current tools make agents operate a timeline. @/problem+ </opening>++ <answer>+ <HOST> @solution SVML removes that editing loop. @/solution+ </answer>+ @/whole~+</script>+```++### 语法++| 标记 | 含义 |+|---|---|+| `@id` | 打开,右吸附(从下一个单词开始) |+| `~@id` | 打开,左吸附(从前一个单词的末尾开始) |+| `@/id` | 关闭,左吸附(在前一个单词的末尾结束) |+| `@/id~` | 关闭,右吸附(在下一个单词的起始处结束) |++`~` 后缀/前缀控制边界是吸附到左边还是右边。默认的打开标记为右吸附;默认的关闭标记为左吸附。++### 非连续 Selection++同一个 id 可以多次出现,以创建带有间隔的 Selection:++```svml+<demo>+ <HOST> @beat First point. @/beat Then something else. @beat Third point. @/beat+</demo>+```++`{story.selection.beat}` 现在覆盖两个不相邻的范围。++### 交叉 Selection++Selection 不要求像 XML 标签那样嵌套,它们可以互相交叉:++```svml+<demo>+ <HOST> @a One @b two @/a three @/b.+</demo>+```++Selection 标记是零宽度的,不会出现在任何文本投影中。它们编译为包含 `Range[]` 的 `SelectionSet` 值。Script 本身不包含秒数或帧号——时间信息来自 WhisperX 对齐。++其他组件通过 `{story.selection.problem}` 引用 Selection,将视觉内容绑定到叙事中的语义时刻。++## Moment++Moment 是具名的时间**点**(不是范围):++```svml+<ecosystem>+ <HOST> @ranking! Image generation, video generation, captions and B-roll+ all become reusable components.+</ecosystem>+```++| 标记 | 含义 |+|---|---|+| `@id!` | 右吸附(时间点位于下一个单词的起始处) |+| `~@id!` | 左吸附(时间点位于前一个单词的末尾) |++Moment 编译为包含 `Point[]` 的 `MomentSet` 值。Selection 和 Moment 共享同一命名空间——同一个 id 不能同时用于两者。++其他组件通过 `{story.moment.ranking}` 引用 Moment。++## Slot++用于模板化 Script 的变量插值:++```svml+<intro>+ <HOST> Meet <${product} | ${product_pronunciation}>.+</intro>+```++Slot id 为 1–64 个字符,以字母或下划线开头。绑定值为纯文本——它们无法注入 SVML 语法。Slot 先被解析,再进行绑定。++## 注释与转义++```svml+<!-- This is a comment. Comments never enter any projection. -->++<demo>+ <HOST> Follow us \@svml on social media.+</demo>+```++保留语法起始符必须转义:++| 转义 | 产生 |+|---|---|+| `\@` | 字面量 `@` |+| `\<` | 字面量 `<` |+| `\${` | 字面量 `${` |+| `\\` | 字面量 `\` |++在 Dual Text 内部,还需转义 `\|` 和 `\>`。++## 综合示例++一个使用所有语法构造的完整 Script:++```svml+<script id="story">+ @whole+ <hook>+ <HOST> @problem Girls, you need to hear this. Never let anyone take credit+ for your work. @/problem+ </hook>++ <meeting>+ <HOST> @solution Then I found <Echo Pro | echo pro>: a card-sized recorder+ that snaps onto the back of my phone. @ranking! I brought it to one+ meeting. @/solution+ </meeting>++ <evidence>+ <HOST> That gave me @emphasis the courage I was missing @/emphasis.+ </evidence>++ <payoff>+ <HOST> And guess what? I'm sitting in my old boss's chair now.+ </payoff>+ @/whole~+</script>+```++此 Script 声明了:++- 四个 Segment:`hook`、`meeting`、`evidence`、`payoff`+- 一个 Role Cue:`HOST`(在所有 Segment 中保持一致)+- 一个 Dual Text:`<Echo Pro | echo pro>`(显示为 "Echo Pro",说出为 "echo pro")+- 三个 Selection:`whole`(整个 Script)、`problem`、`solution`、`emphasis`+- 一个 Moment:`ranking`(标记 "I brought it to one meeting" 这一瞬间)++下游组件通过名称引用这些内容:`{story.segment.hook.dialogue}` 用于生成,`{story.selection.problem}` 用于 B-roll 时间绑定,`{story.moment.ranking}` 用于视觉卡片揭示。diff --git a/docs/zh/quickstart/styles.md b/docs/zh/quickstart/styles.mdnew file mode 100644index 00000000..771a64f6--- /dev/null+++ b/docs/zh/quickstart/styles.md@@ -0,0 +1,394 @@+---+title: SVS 样式表+description: SVS Recipe 语言——用于影片、字幕、B-roll、文本及生成设置的类 CSS 样式表。+---++# SVS 样式表++SVS(`.svs`)文件使用类 CSS 语法定义可复用的类型化配置值。它们用于配置影片尺寸、字幕外观、B-roll 布局、文本样式、语音估算参数、生成设置和自定义字体。SVS 中的值称为 **Recipe**——它们是不可变的类型化记录,由消费组件进行验证和解释。++## 基本语法++```svs+<?svml using="@narratage/svs@1"?>++<sheet version="1" id="studio">+ film.vertical {+ width: 1080;+ height: 1920;+ frame-rate: 30;+ background: #09090B;+ }++ /* Comments use CSS-style block syntax. */+ caption.primary {+ fill: #FFFFFF;+ size: 58;+ }+</sheet>+```++- 处理指令 `<?svml using="@narratage/svs@1"?>` 用于选择 SVS 解析器。+- `<sheet>` 元素包裹所有声明。`id` 属性成为顶层命名空间。+- 每个块的格式为 `namespace.name { ... }`,属性以 `;` 结尾的键值对形式书写。+- 注释使用 `/* ... */`。++## 导入与引用++在 `.svml` 源文件中通过命名空间前缀导入 SVS 文件:++```svml+<import as="studio" source="./studio.svs"/>+```++然后通过 `{studio.film.vertical}`、`{studio.caption.primary}` 等方式引用各个 Recipe。前缀来自 `as=` 属性;路径来自样式表中的 `namespace.name`。++## Film++Film 外观——画布尺寸和背景颜色。++```svs+film.vertical {+ width: 1080;+ height: 1920;+ frame-rate: 30;+ background: #09090B;+}+```++| 属性 | 描述 |+|---|---|+| `width` | 画布宽度(像素) |+| `height` | 画布高度(像素) |+| `frame-rate` | 每秒帧数(通常为 30) |+| `background` | 画布清除颜色(十六进制) |++通过 `film:Film` 的 `appearance` 属性引用:++```svml+<film:Film id="main" space={speech.space} appearance={studio.film.vertical}>+```++## 字幕++字幕视觉外观——位置、排版和容器样式。++```svs+caption.dialogue {+ stack-order: 70;+ x: 0.08;+ y: 0.76;+ width: 0.84;+ font: Inter;+ weight: 600;+ size: 58;+ line-height: 0.96;+ align: center;+ fill: #FFFFFF;+ background: #09090BCC;+ padding: 16 24;+ radius: 18;+}+```++| 属性 | 描述 |+|---|---|+| `stack-order` | 所有 Track 之间的 Z 轴层叠顺序(值越大越靠前) |+| `x`、`y` | 位置,以画布比例表示(0–1) |+| `width` | 宽度,以画布比例表示 |+| `font` | 字体族名称或 SVS 字体引用 |+| `weight` | 字体粗细(400–900) |+| `size` | 字体大小(像素) |+| `line-height` | 行高倍数 |+| `align` | 文本对齐方式:`left`、`center`、`right` |+| `fill` | 文本颜色(十六进制,支持透明度) |+| `background` | 容器背景颜色(十六进制,支持透明度,如 `#09090BCC`) |+| `padding` | 容器内边距(像素)(单个值或 `垂直 水平`) |+| `radius` | 容器圆角半径(像素) |++通过 `caption:Style` 的 `appearance` 属性引用:++```svml+<caption:Style id="primary-caption" appearance={studio.caption.dialogue}>+```++### 按角色设置字幕样式++为不同说话者定义多个字幕 Recipe:++```svs+caption.alice {+ stack-order: 70;+ x: 0.08; y: 0.76; width: 0.84;+ font: Inter; weight: 600; size: 58;+ fill: #73FBD3;+ background: #09090BCC;+ padding: 16 24; radius: 18;+}++caption.bob {+ stack-order: 70;+ x: 0.08; y: 0.76; width: 0.84;+ font: Inter; weight: 600; size: 58;+ fill: #FFD166;+ background: #09090BCC;+ padding: 16 24; radius: 18;+}+```++然后通过 `caption:Program` 进行分配:++```svml+<caption:Program id="caption-program" narrative={story} default={studio.caption.dialogue}>+ <caption:Use role="ALICE" style={alice-caption}/>+ <caption:Use role="BOB" style={bob-caption}/>+</caption:Program>+```++## B-roll++B-roll 项目外观——位置、适配方式、容器以及进入/退出动画。++```svs+broll.product {+ stack-order: 40;+ x: 0.08;+ y: 0.20;+ width: 0.84;+ height: 0.48;+ fit: contain;+ background: #111116;+ radius: 28;+ enter: slide-up 8f;+ exit: fade 6f;+}+```++| 属性 | 描述 |+|---|---|+| `stack-order` | Z 轴层叠顺序 |+| `x`、`y` | 位置,以画布比例表示 |+| `width`、`height` | 尺寸,以画布比例表示 |+| `fit` | 源内容适配容器的方式:`cover`、`contain` |+| `background` | 容器背景颜色 |+| `radius` | 容器圆角半径 |+| `enter` | 进入动画:`slide-up Nf`、`fade Nf`(N = 帧数) |+| `exit` | 退出动画:`fade Nf`、`slide-down Nf` |++通过 `broll:Item` 的 `appearance` 属性引用:++```svml+<broll:Item source={motion.video} during={story.selection.demo}+ appearance={studio.broll.product}/>+```++## 文本++文本叠加层外观——位置、排版。++```svs+text.title {+ stack-order: 90;+ x: 0.06;+ y: 0.06;+ width: 0.88;+ height: 0.10;+ font: Inter;+ weight: 900;+ size: 64;+ align: center;+ fill: #FFFFFF;+ tracking: -1;+}+```++| 属性 | 描述 |+|---|---|+| `stack-order` | Z 轴层叠顺序 |+| `x`、`y` | 位置,以画布比例表示 |+| `width`、`height` | 尺寸,以画布比例表示 |+| `font` | 字体族名称 |+| `weight` | 字体粗细 |+| `size` | 字体大小(像素) |+| `align` | 文本对齐方式 |+| `fill` | 文本颜色 |+| `tracking` | 字间距调整 |++通过 `text:Item` 的 `appearance` 属性引用:++```svml+<text:Item text="MEANING" during="full" appearance={studio.text.title}/>+```++## 语音估算++确定性语音时长估算的参数。++```svs+speech.normal {+ language: en;+ pace: normal;+ padding: 0.3;+ min: 4;+ max: 15;+ rounding: ceil;+}+```++| 属性 | 描述 |+|---|---|+| `language` | 语言代码(如 `en`) |+| `pace` | 语速:`slow`、`normal`、`fast` |+| `padding` | 添加到估算值的额外填充时间(秒) |+| `min` | 最小时长(秒) |+| `max` | 最大时长(秒) |+| `rounding` | 取整模式:`ceil`、`floor`、`round` |++通过 `estimate:Speech` 的 `policy` 属性引用:++```svml+<estimate:Speech id="hook-duration" source={story.segment.hook.speech}+ policy={studio.speech.normal}/>+```++## Speaker++Seedance Speaker 生成设置——控制 `speaker:Take` 如何生成说话人头像片段的 Recipe。++```svs+speaker.echo-pro {+ kind: ugc-talking-head;+ model: mini;+ resolution: 720p;+ aspect-ratio: 9:16;+ composition-stability: soft-locked;+ camera-motion: none;+ edit-rhythm: continuous-take;+ performance: natural-explainer;+ gesture: natural;+ voice-mode: single-speaker;+}+```++| 属性 | 描述 |+|---|---|+| `kind` | 生成类型(如 `ugc-talking-head`) |+| `model` | 模型名称:`mini` |+| `resolution` | 输出分辨率:`480p`、`720p`、`1080p` |+| `aspect-ratio` | 输出宽高比:`9:16`、`16:9`、`1:1` |+| `composition-stability` | 镜头/构图一致性:`flexible-ugc`、`soft-locked`、`strict-locked` |+| `camera-motion` | 镜头运动:`none`、`subtle-punch-in-return` |+| `edit-rhythm` | 剪辑风格:`continuous-take`、`pause-trim-jump-cuts` |+| `performance` | 表演风格:`natural-explainer`、`high-energy-ugc`、`calm-authority`、`reactive-playful` |+| `gesture` | 手势强度:`restrained`、`compact`、`natural`、`expressive` |+| `voice-mode` | 语音配置:`single-speaker` |++通过 `speaker:Take` 的 `recipe` 属性引用:++```svml+<speaker:Take id="hook-take" dialogue={story.segment.hook.dialogue}+ duration={hook-duration.duration} recipe={studio.speaker.echo-pro} kit={ugc.official-ugc-v1}>+```++## 字体声明++声明本地字体文件,以便在字幕和文本叠加层中使用。++```svs+font.inter-semibold {+ src: ./assets/Inter-SemiBold.woff2;+ weight: 600;+ style: normal;+}++font.inter-black {+ src: ./assets/Inter-Black.woff2;+ weight: 900;+ style: normal;+}+```++| 属性 | 描述 |+|---|---|+| `src` | 字体文件路径(相对于 SVS 文件) |+| `weight` | 该文件提供的字体粗细 |+| `style` | 字体样式:`normal`、`italic` |++字体路径在编译时解析,并成为 `FontArtifactRef` 值。在其他 SVS 块中通过名称引用:++```svs+caption.dialogue {+ font: inter-semibold;+ /* ... */+}+```++## 综合示例++一个完整的 `studio.svs` 文件,用于四段式说话人头像项目:++```svs+<?svml using="@narratage/svs@1"?>++<sheet version="1" id="studio">+ speech.normal {+ language: en;+ pace: normal;+ padding: 0.3;+ min: 4;+ max: 15;+ rounding: ceil;+ }++ speaker.echo-pro {+ kind: ugc-talking-head;+ model: mini;+ resolution: 720p;+ aspect-ratio: 9:16;+ composition-stability: soft-locked;+ camera-motion: none;+ edit-rhythm: continuous-take;+ performance: natural-explainer;+ gesture: natural;+ voice-mode: single-speaker;+ }++ film.vertical {+ width: 720;+ height: 1280;+ frame-rate: 30;+ background: #09090B;+ }++ caption.primary {+ stack-order: 70;+ x: 0.08;+ y: 0.74;+ width: 0.84;+ font: Inter;+ weight: 800;+ size: 44;+ line-height: 1;+ align: center;+ fill: #FFFFFF;+ background: #09090BCC;+ padding: 14 20;+ radius: 16;+ }+</sheet>+```++该文件在 `.svml` 源文件中导入一次,其值在整个文件中被引用:++```svml+<import as="studio" source="./studio.svs"/>++<estimate:Speech id="hook-duration" source={story.segment.hook.speech}+ policy={studio.speech.normal}/>++<speaker:Take id="hook-take" ... recipe={studio.speaker.echo-pro} .../>++<caption:Style id="primary-caption" appearance={studio.caption.primary} .../>++<film:Film id="main" space={speech.space} appearance={studio.film.vertical}>+```diff --git a/docs/zh/quickstart/timing.md b/docs/zh/quickstart/timing.mdnew file mode 100644index 00000000..54a7aaa4--- /dev/null+++ b/docs/zh/quickstart/timing.md@@ -0,0 +1,149 @@+---+title: 时序与装配+description: Speech Spine 装配与 WhisperX 对齐——将生成的片段连接到统一时间线。+---++# 时序与装配++生成完成后,各个片段必须拼接成一个连续的音视频坐标空间,并且需要将语音内容与实际音频进行比对,以创建时序映射。这两个步骤产生 **ProgramSpace** 和 **SemanticMap**,所有下游组件均依赖于它们。++```svml+<import as="speech" from="@narratage/speech-spine@1"/>+<import as="whisperx" from="@narratage/whisperx@1"/>+```++## speech:Spine++将多个片段拼接成一个有序的音视频坐标空间。Spine 定义了节目顺序——即最终视频中 Segment 的排列序列。++```svml+<speech:Spine id="speech">+ <speech:Take source={hook-take.video} segment={story.segment.hook}/>+ <speech:Take source={meeting-take.video} segment={story.segment.meeting}/>+ <speech:Take source={evidence-take.video} segment={story.segment.evidence}/>+ <speech:Take source={payoff-take.video} segment={story.segment.payoff}/>+</speech:Spine>+```++| 属性 | 必填 | 描述 |+|---|---|---|+| `id` | 是 | 唯一标识符 |++### speech:Take++每个 `<speech:Take>` 子元素将一个生成的视频绑定到一个 Script Segment:++| 属性 | 必填 | 描述 |+|---|---|---|+| `source` | 是 | 生成的视频——来自 `seedance:Speech`、`speaker:Take` 等 |+| `segment` | 是 | 此片段对应的 Script Segment——例如 `{story.segment.hook}` |++`<speech:Take>` 子元素的排列顺序**决定了节目顺序**。第一个片段从时间零点开始;后续片段依次紧接。++### 输出++Spine 产生四个输出,供下游组件使用:++| 输出 | 类型 | 使用方 |+|---|---|---|+| `{speech.visual}` | VisualTrack | `film:Film`——全屏真人出镜视频 |+| `{speech.audio}` | Audio | `whisperx:Alignment`——用于词级时序的原始音频 |+| `{speech.audioTrack}` | AudioTrack | `film:Film`——同步音频 |+| `{speech.space}` | ProgramSpace | 所有组件——统一的时长和帧域 |++## whisperx:Alignment++通过对 Spine 的音频输出运行 WhisperX 语音转文本对齐,测量词级时序。这将产生 **SemanticMap**——连接 Script 文本与物理时间的桥梁。++```svml+<whisperx:Alignment id="timing" narrative={story} audio={speech.audio}/>+```++| 属性 | 必填 | 描述 |+|---|---|---|+| `id` | 是 | 唯一标识符 |+| `narrative` | 是 | Script 组件——例如 `{story}` |+| `audio` | 是 | 来自 Speech Spine 的音频——`{speech.audio}` |++### 输出++| 输出 | 类型 | 使用方 |+|---|---|---|+| `{timing.map}` | CompleteSemanticMap | `caption:Track`、`broll:Track`、`text:Track`——定时放置 |++SemanticMap 将每个 Script 中标注的锚点映射到一个时间点。它覆盖所有 `2M + 2N` 个标识(其中 M = 语音词元总数,N = Segment 数量)。这就是 Script 中声明的 Selection 和 Moment 如何转化为下游视觉组件所需的实际时间范围和时间点。++## ProgramSpace++ProgramSpace 不是一个需要声明的组件——它由 `speech:Spine` 产生,并传递给每个需要知道总节目时长和帧域的组件。++```svml+<film:Film id="main" space={speech.space} ...>+<caption:Track id="captions" ... space={speech.space} .../>+<text:Track id="titles" space={speech.space}>+<render:Video id="final" composition={main.composition} space={speech.space}/>+```++ProgramSpace 包含:++- **时长**——节目总长度+- **帧率**——有理帧率(例如 30fps)+- **帧域**——整个节目的精确帧编号++每个在时间域中运行的组件都通过 `space` 属性指向 `{speech.space}`。++## SemanticMap++SemanticMap 是连接 Script 文本与物理时间的类型化桥梁。当你在 B-roll 项上写 `during={story.selection.demo}` 时,组件会使用 SemanticMap 查找该 Selection 覆盖的精确帧范围。没有 SemanticMap,Selection 和 Moment 就没有物理意义。++使用该映射的组件通过 `map` 属性接收它:++```svml+<broll:Track id="cards" map={timing.map} ...>+<caption:Track id="captions" ... map={timing.map} .../>+```++映射中的每个点可以是:++- **测量值**——由 WhisperX 对齐直接观测得到+- **推导值**——通过插值从测量值计算得出+- **估算值**——来自初始时长估计(在对齐运行之前使用)++## 组合示例++完整的时序阶段,从生成的片段到映射和空间:++```svml+<import as="speech" from="@narratage/speech-spine@1"/>+<import as="whisperx" from="@narratage/whisperx@1"/>++<!-- Assemble takes in program order -->+<speech:Spine id="speech">+ <speech:Take source={opening-take} segment={story.segment.opening}/>+ <speech:Take source={answer-take} segment={story.segment.answer}/>+</speech:Spine>++<!-- Measure word timing -->+<whisperx:Alignment id="timing" narrative={story} audio={speech.audio}/>++<!-- Downstream components now reference: -->+<!-- {speech.space} — ProgramSpace for duration/frame domain -->+<!-- {speech.visual} — VisualTrack for the talking-head video -->+<!-- {speech.audioTrack} — AudioTrack for synchronized audio -->+<!-- {timing.map} — SemanticMap for Selection/Moment timing -->+```++数据流向:++```text+speaker:Take outputs ──► speech:Spine ──► whisperx:Alignment+ │ │+ .visual .map (SemanticMap)+ .audio │+ .audioTrack ▼+ .space ──────────► caption:Track+ │ broll:Track+ │ text:Track+ ▼ film:Film+ film:Film render:Video+```diff --git a/docs/zh/quickstart/tracks.md b/docs/zh/quickstart/tracks.mdnew file mode 100644index 00000000..0e7977f0--- /dev/null+++ b/docs/zh/quickstart/tracks.md@@ -0,0 +1,342 @@+---+title: 字幕、B-roll 与文字+description: 视觉 Track 组件——字幕、B-roll 叠加层和文字叠加层。+---++# 字幕、B-roll 与文字++每个进入最终合成的视听内容都是一个对等的 **Track**。Track 是扁平的(无嵌套),其 z 轴顺序由 SVS 中的 `stack-order` 属性决定。本页介绍三种主要的视觉 Track 类型:字幕、B-roll 和文字叠加层。++## 字幕系统++字幕由四个组件构成一条流水线:++```text+caption:Style → caption:Program → caption-ai:Planner → caption:Track+```++```svml+<import as="caption" from="@narratage/caption@1"/>+<import as="caption-ai" from="@narratage/caption-gemini@1"/>+```++### caption:Style++声明一种字幕样式的完整视觉外观及规划指令。++```svml+<caption:Style id="primary-caption" appearance={studio.caption.primary}+ mode="proportional-word">+ <caption:Cues>+ Split each Script Segment into short complete semantic phrases of two to+ seven words. Never cross a sentence or Segment boundary.+ </caption:Cues>+ <caption:Field id="important" type="boolean" min-per-cue="1" max-per-cue="2">+ Select one or two words whose emphasis best communicates this Cue.+ </caption:Field>+</caption:Style>+```++| 属性 | 必填 | 描述 |+|---|---|---|+| `id` | 是 | 唯一标识符 |+| `appearance` | 是 | SVS 字幕 Recipe——位置、字体、颜色、容器 |+| `mode` | 否 | 字幕计时模式,例如 `proportional-word` |++**子元素:**++- `<caption:Cues>` —— 给 AI 规划器的自然语言指令,告诉它如何将文本拆分为提示单元。规划器接收显示文本(Dual Text 的左侧)和这些指令,但不会接收音频或时间数据。+- `<caption:Field>` —— 声明一个有类型的逐词注解。规划器将这些字段分配给每个提示单元中的各个词。++| `<caption:Field>` 属性 | 描述 |+|---|---|+| `id` | 字段名称(例如 `important`) |+| `type` | 字段类型:`boolean` |+| `min-per-cue` | 每个提示单元的最少注解数 |+| `max-per-cue` | 每个提示单元的最多注解数 |++`<caption:Field>` 的元素主体是给规划器的自然语言指令。++### caption:Program++将字幕样式分配给叙事。声明一个默认样式,并可选择按角色或按 Selection 覆盖。++```svml+<caption:Program id="caption-program" narrative={story} default={primary-caption}>+ <caption:Use role="ALICE" style={alice-caption}/>+ <caption:Use role="BOB" style={bob-caption}/>+ <caption:Use on={story.selection.product-demo} style={dialogue-caption}/>+</caption:Program>+```++| 属性 | 必填 | 描述 |+|---|---|---|+| `id` | 是 | 唯一标识符 |+| `narrative` | 是 | Script 组件 |+| `default` | 是 | 所有文本的默认 `caption:Style` |++**子元素:**++`<caption:Use>` 用于应用样式覆盖。规则按源代码顺序应用——后匹配优先。++| `<caption:Use>` 属性 | 描述 |+|---|---|+| `role` | 按 Role Cue 标签匹配(例如 `"ALICE"`) |+| `on` | 按 Selection 引用匹配(例如 `{story.selection.product-demo}`) |+| `style` | 要应用的 `caption:Style` |++使用 `role=` 为不同说话者设置不同的字幕颜色。使用 `on=` 在特定 Selection 期间覆盖样式(例如产品演示部分使用不同的字幕样式)。++### caption-ai:Planner++通过 Gemini 驱动的 AI 提示单元规划。规划器接收显示文本原子、Style 指令和 Program 分配,将文本拆分为提示单元并分配 Field 值。++```svml+<caption-ai:Planner id="caption-plan" narrative={story}+ program={caption-program} model="gemini-2.5-flash"/>+```++| 属性 | 必填 | 描述 |+|---|---|---|+| `id` | 是 | 唯一标识符 |+| `narrative` | 是 | Script 组件 |+| `program` | 是 | `caption:Program` |+| `model` | 是 | Gemini 模型:`gemini-2.5-flash` |++规划器不会接收音频、时间数据或 Dual Text 的语音侧。它完全基于字幕(显示)投影进行工作。++**输出:**`{caption-plan.plan}` —— 提示单元计划,传递给 `caption:Track`。++### caption:Track++将提示单元计划、SemanticMap、ProgramSpace 和 Program 组合在一起,生成一个带时间信息的 VisualTrack。++```svml+<caption:Track id="captions" narrative={story} map={timing.map}+ space={speech.space} program={caption-program} plan={caption-plan.plan}/>+```++| 属性 | 必填 | 描述 |+|---|---|---|+| `id` | 是 | 唯一标识符 |+| `narrative` | 是 | Script 组件 |+| `map` | 是 | 来自 `whisperx:Alignment` 的 SemanticMap |+| `space` | 是 | 来自 `speech:Spine` 的 ProgramSpace |+| `program` | 是 | `caption:Program` |+| `plan` | 是 | 来自 `caption-ai:Planner` 的提示单元计划 |++**输出:**`{captions.track}` —— 添加到 `film:Film` 的 VisualTrack。++### 字幕组合示例++包含按角色样式的完整字幕流水线:++```svml+<caption:Style id="dialogue-caption" appearance={studio.caption.dialogue}>+ <caption:Cues>Use short complete semantic phrases, two to five words.</caption:Cues>+</caption:Style>++<caption:Style id="alice-caption" appearance={studio.caption.alice}>+ <caption:Cues>Use short complete semantic phrases, two to five words.</caption:Cues>+ <caption:Field id="important" type="boolean" min-per-cue="0" max-per-cue="2">+ Select at most two words whose emphasis best communicates this Cue.+ </caption:Field>+</caption:Style>++<caption:Style id="bob-caption" appearance={studio.caption.bob}>+ <caption:Cues>Use short complete semantic phrases, two to five words.</caption:Cues>+</caption:Style>++<caption:Program id="caption-program" narrative={story} default={dialogue-caption}>+ <caption:Use role="ALICE" style={alice-caption}/>+ <caption:Use role="BOB" style={bob-caption}/>+ <caption:Use on={story.selection.product-demo} style={dialogue-caption}/>+</caption:Program>++<caption-ai:Planner id="caption-plan" narrative={story}+ program={caption-program} model="gemini-2.5-flash"/>++<caption:Track id="captions" narrative={story} map={timing.map}+ space={speech.space} program={caption-program} plan={caption-plan.plan}/>+```++ALICE 使用绿色字幕(`#73FBD3`),BOB 使用金色字幕(`#FFD166`),在 product-demo Selection 期间两者都切换为中性对话样式。`important` Field 仅应用于 ALICE 的样式——她的强调词会获得特殊处理。++## B-roll++B-roll 在语义时间位置叠加生成的或预先提供的视频/图像。++```svml+<import as="broll" from="@narratage/broll@1"/>+```++### broll:Track++B-roll 项目的容器。接收 SemanticMap 用于时间解析。++```svml+<broll:Track id="product-broll" map={timing.map} space={speech.space}>+ <broll:Item source={product-motion.video}+ during={story.selection.product-demo}+ appearance={studio.broll.product}/>+</broll:Track>+```++| 属性 | 必填 | 描述 |+|---|---|---|+| `id` | 是 | 唯一标识符 |+| `map` | 是 | 来自 `whisperx:Alignment` 的 SemanticMap |+| `space` | 否 | ProgramSpace(某些配置需要) |++### broll:Item++每个项目将一个来源放置在语义时间位置上,并附带样式外观:++```svml+<broll:Item source={product-motion.video}+ during={story.selection.product-demo}+ appearance={studio.broll.product}/>+```++| 属性 | 必填 | 描述 |+|---|---|---|+| `source` | 是 | 视频或图像——来自 `seedance:Video`、`media:Image` 等 |+| `during` | 是 | Selection 引用——该项目何时出现 |+| `appearance` | 是 | SVS B-roll Recipe——位置、大小、适配方式、动画 |++`during` 属性接收一个 Selection 引用,如 `{story.selection.product-demo}`。B-roll 项目在屏幕上显示的时长恰好等于该 Selection 的持续时间,通过 SemanticMap 解析确定。++外观 Recipe 控制进场/退场动画:++```svs+broll.product {+ stack-order: 40;+ x: 0.08; y: 0.20; width: 0.84; height: 0.48;+ fit: contain;+ background: #111116;+ radius: 28;+ enter: slide-up 8f;+ exit: fade 6f;+}+```++**输出:**`{product-broll.visual}` —— 添加到 `film:Film` 的 VisualTrack。++### B-roll 示例++B-roll 搭配生成的 Seedance 视频,在 Script Selection 期间出现:++```svml+<seedance:Prompt id="product-direction">+ A clean vertical product film: the written script becomes semantic regions,+ then those regions assemble into a finished video.+</seedance:Prompt>++<seedance:Video id="product-motion" model="mini"+ prompt={product-direction} duration="5">+ <seedance:Reference image={product-reference} role="subject"/>+</seedance:Video>++<broll:Track id="product-broll" map={timing.map}>+ <broll:Item source={product-motion.video}+ during={story.selection.product-demo}+ appearance={studio.broll.product}/>+</broll:Track>+```++## 文字叠加层++在屏幕上显示的静态或定时文字——标题、标注、下方三分之一字幕条。++```svml+<import as="text" from="@narratage/text-track@1"/>+```++### text:Track++文字项目的容器。++```svml+<text:Track id="titles" space={speech.space}>+ <text:Item text="EDIT MEANING, NOT TIMELINES" during="full"+ appearance={studio.text.title}/>+</text:Track>+```++| 属性 | 必填 | 描述 |+|---|---|---|+| `id` | 是 | 唯一标识符 |+| `space` | 是 | 来自 `speech:Spine` 的 ProgramSpace |+| `map` | 否 | SemanticMap——当项目使用基于 Selection 的计时时需要 |++### text:Item++每个项目是放置在某个时间位置的一段文本字符串:++```svml+<text:Item text="MEANING" during="full" appearance={studio.text.title}/>+```++| 属性 | 必填 | 描述 |+|---|---|---|+| `text` | 是 | 要显示的文本字符串 |+| `during` | 是 | 何时显示:`"full"`(整个节目时长)或 Selection 引用 |+| `appearance` | 是 | SVS 文字 Recipe——位置、字体、大小、颜色 |++`during` 属性接受字面字符串 `"full"`(表示整个节目时长),或 Selection 引用(用于语义计时):++```svml+<text:Track id="callout" space={speech.space} map={timing.map}>+ <text:Item text="EXACTLY THE RIGHT MOMENT"+ during={story.selection.callout}+ appearance={studio.text.callout}/>+</text:Track>+```++**输出:**`{titles.track}` —— 添加到 `film:Film` 的 VisualTrack。++## 组合示例++三种 Track 类型在一个源文件中协同使用:++```svml+<import as="caption" from="@narratage/caption@1"/>+<import as="caption-ai" from="@narratage/caption-gemini@1"/>+<import as="broll" from="@narratage/broll@1"/>+<import as="text" from="@narratage/text-track@1"/>++<!-- Captions: primary style for all text -->+<caption:Style id="base-caption" appearance={studio.caption.base}>+ <caption:Cues>Prefer short complete semantic phrases.</caption:Cues>+ <caption:Field id="important" type="boolean" min-per-cue="0" max-per-cue="2">+ Select zero, one, or two words whose emphasis best communicates this Cue.+ </caption:Field>+</caption:Style>+<caption:Program id="caption-program" narrative={story} default={base-caption}/>+<caption-ai:Planner id="cue-plan" narrative={story}+ program={caption-program} model="gemini-2.5-flash"/>+<caption:Track id="captions" narrative={story} map={timing.map}+ space={speech.space} plan={cue-plan.plan} program={caption-program}/>++<!-- B-roll: generated video during a Selection -->+<broll:Track id="cards" map={timing.map} space={speech.space}>+ <broll:Item source={motion.video} during={story.selection.demo}+ appearance={studio.broll.card}/>+</broll:Track>++<!-- Text: persistent title overlay -->+<text:Track id="titles" space={speech.space}>+ <text:Item text="MEANING" during="full" appearance={studio.text.title}/>+</text:Track>++<!-- All three tracks feed into Film -->+<film:Film id="main" 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,B-roll 为 40,字幕为 70,文字为 90。数值越高,渲染层越靠上。