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
Consolidate bilingual docs and refine locale routing
rponeb0d36e76aa2a
diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.tsindex 80189554..a8ff2fc2 100644--- a/docs/.vitepress/config.ts+++ b/docs/.vitepress/config.ts@@ -28,57 +28,57 @@ const sharedTheme = {search: { provider: "local" as const },};-const zhTheme = {+const enTheme = {...sharedTheme,nav: [- { text: "快速开始", link: "/quickstart" },- { text: "开发指南", link: "/guide/components" },+ { text: "Quickstart", link: "/quickstart" },+ { text: "Develop", link: "/guide/components" },],sidebar: {"/quickstart": [- { text: "开始使用", items: [{ text: "Quickstart", link: "/quickstart" }] },+ { text: "Getting Started", items: [{ text: "Quickstart", link: "/quickstart" }] },],"/guide/": [{- text: "开发指南",+ text: "Develop",items: [- { text: "创建组件", link: "/guide/components" },- { text: "运行时与 Provider", link: "/guide/runtime" },+ { text: "Components", link: "/guide/components" },+ { text: "Runtime & Providers", link: "/guide/runtime" },],},],},- outline: { level: [2, 3] as [number, number], label: "本页目录" },- docFooter: { prev: "上一页", next: "下一页" },+ outline: { level: [2, 3] as [number, number], label: "On this page" },+ docFooter: { prev: "Previous", next: "Next" },};-const enTheme = {+const zhTheme = {...sharedTheme,nav: [- { text: "Quickstart", link: "/en/quickstart" },- { text: "Develop", link: "/en/guide/components" },+ { text: "快速开始", link: "/zh/quickstart" },+ { text: "开发指南", link: "/zh/guide/components" },],sidebar: {- "/en/quickstart": [- { text: "Getting Started", items: [{ text: "Quickstart", link: "/en/quickstart" }] },+ "/zh/quickstart": [+ { text: "开始使用", items: [{ text: "Quickstart", link: "/zh/quickstart" }] },],- "/en/guide/": [+ "/zh/guide/": [{- text: "Develop",+ text: "开发指南",items: [- { text: "Components", link: "/en/guide/components" },- { text: "Runtime & Providers", link: "/en/guide/runtime" },+ { text: "创建组件", link: "/zh/guide/components" },+ { text: "运行时与 Provider", link: "/zh/guide/runtime" },],},],},- outline: { level: [2, 3] as [number, number], label: "On this page" },- docFooter: { prev: "Previous", next: "Next" },+ outline: { level: [2, 3] as [number, number], label: "本页目录" },+ docFooter: { prev: "上一页", next: "下一页" },};export default defineConfig({base: "/docs/",- lang: "zh-CN",+ lang: "en-US",title: "Narratage",description: "Write the story. Compile the video.",appearance: false,@@ -100,7 +100,7 @@ export default defineConfig({["script",{},- `(function(){var p=location.pathname,b="/docs/",k="narratage-locale",l;try{l=localStorage.getItem(k)}catch(e){}if(!l)l=(navigator.language||"").toLowerCase().indexOf("zh")===0?"zh":"en";if(p===b&&l==="en")location.replace(b+"en/"+location.search+location.hash)})()`,+ `(function(){var p=location.pathname,b="/docs/",k="narratage-locale",h="narratage-hero-intro-seen",l;try{if(sessionStorage.getItem(h)==="1")document.documentElement.classList.add("hero-intro-seen");l=localStorage.getItem(k)}catch(e){}if(!l)l=(navigator.language||"").toLowerCase().indexOf("zh")===0?"zh":"en";if(p===b&&l==="zh")location.replace(b+"zh/"+location.search+location.hash)})()`,],["link", { rel: "preconnect", href: "https://fonts.googleapis.com" }],["link", { rel: "preconnect", href: "https://fonts.gstatic.com", crossorigin: "" }],@@ -120,8 +120,8 @@ export default defineConfig({],],locales: {- root: { label: "简体中文", lang: "zh-CN", themeConfig: zhTheme },- en: { label: "English", lang: "en-US", link: "/en/", themeConfig: enTheme },+ root: { label: "English", lang: "en-US", themeConfig: enTheme },+ zh: { label: "简体中文", lang: "zh-CN", link: "/zh/", themeConfig: zhTheme },},- themeConfig: zhTheme,+ themeConfig: enTheme,});diff --git a/docs/.vitepress/theme/components/LocalePreference.vue b/docs/.vitepress/theme/components/LocalePreference.vueindex 551391a0..294b8ecf 100644--- a/docs/.vitepress/theme/components/LocalePreference.vue+++ b/docs/.vitepress/theme/components/LocalePreference.vue@@ -2,9 +2,10 @@import { onBeforeUnmount, onMounted } from "vue";const storageKey = "narratage-locale";+const heroIntroKey = "narratage-hero-intro-seen";function localeFromPath(pathname: string) {- return pathname.startsWith("/docs/en/") ? "en" : "zh";+ return pathname === "/docs/zh" || pathname.startsWith("/docs/zh/") ? "zh" : "en";}function rememberLocale(event: MouseEvent) {@@ -13,11 +14,21 @@ function rememberLocale(event: MouseEvent) {if (!link) return;const url = new URL(link.href, window.location.href);if (!url.pathname.startsWith("/docs/")) return;+ const nextLocale = localeFromPath(url.pathname);+ const currentLocale = localeFromPath(window.location.pathname);try {- window.localStorage.setItem(storageKey, localeFromPath(url.pathname));+ window.localStorage.setItem(storageKey, nextLocale);} catch {// Storage can be unavailable in private or restricted browser contexts.}+ if (nextLocale !== currentLocale) {+ document.documentElement.classList.add("hero-intro-seen");+ try {+ window.sessionStorage.setItem(heroIntroKey, "1");+ } catch {+ // The in-document class still skips the animation for SPA navigation.+ }+ }}onMounted(() => {diff --git a/docs/.vitepress/theme/style.css b/docs/.vitepress/theme/style.cssindex df0bc52a..1c88f8a6 100644--- a/docs/.vitepress/theme/style.css+++ b/docs/.vitepress/theme/style.css@@ -190,6 +190,13 @@ body {}@keyframes wordmark-type { to { width: calc(9ch - .495em); } }@keyframes wordmark-cursor-blink { 50% { opacity: 0; } }+.hero-intro-seen .wordmark-reveal {+ width: calc(9ch - .495em);+ animation: none;+}+.hero-intro-seen .wordmark-cursor {+ animation: wordmark-cursor-blink .48s step-end infinite;+}.hero-statement-viewport { position: relative; width: min(100%,900px); overflow: hidden; }.hero-statement-viewport-en { height: clamp(61.2px,8.16vw,106.08px); }.hero-statement-viewport-zh { height: var(--hero-zh-line); margin-top: var(--hero-zh-gap); }@@ -209,6 +216,16 @@ body {.VPHome .carousel-heading { animation-delay: 1.45s; }.VPHome .demo-carousel-stage { animation-delay: 1.59s; }.VPHome .demo-carousel-controls { animation-delay: 1.73s; }+.hero-intro-seen .hero-statement-viewport-en,+.hero-intro-seen .hero-statement-viewport-zh,+.hero-intro-seen .VPHome .VPHero .actions,+.hero-intro-seen .VPHome .carousel-heading,+.hero-intro-seen .VPHome .demo-carousel-stage,+.hero-intro-seen .VPHome .demo-carousel-controls {+ opacity: 1;+ transform: none;+ animation: none;+}@keyframes hero-content-rise {to { opacity: 1; transform: translateY(0); }}diff --git a/docs/en/guide/components.md b/docs/en/guide/components.mddeleted file mode 100644index 0d8c7134..00000000--- a/docs/en/guide/components.md+++ /dev/null@@ -1,53 +0,0 @@-----title: Create SVK Components-description: Package recurring video treatments as reusable components.------# Create SVK Components--SVK is the reusable component format for SVML. Authors describe what they want; the component decides how to produce it.--## A minimal component--Suppose we want to package a ranking card. The author only needs to write:--```xml-<script>- <segment id="ranking">- <HOST>Here is @winner our number one pick @/winner.- </segment>-</script>--<ranking-card- title="Top 5 tools"- during={script.selection.winner}-/>-```--The component owns its typography, layout, entrance behavior, and output Track. Video authors do not need to rebuild the node graph or tune a dozen parameters every time.--## What a component should hide--- Repeated internal wiring and defaults-- Visual styling, animation, and media placement-- The concrete HyperFrames output implementation--## What a component should not hide--- Choices that materially change the author's intent-- Whether a transition is a hard cut, fade, or push-- Which part of the spoken script the card should bind to--Good components expose a small set of clear choices:--```xml-<ranking-card- during={script.selection.winner}- enter="fade 200ms"- exit="push-left 300ms"-/>-```--## Next--Components that call video-generation APIs also ship with a Runtime implementation. Authors declare the content; the Runtime handles requests, queues, and downloads. See [Runtime & Providers](/en/guide/runtime).diff --git a/docs/en/guide/runtime.md b/docs/en/guide/runtime.mddeleted file mode 100644index 124cfe7e..00000000--- a/docs/en/guide/runtime.md+++ /dev/null@@ -1,46 +0,0 @@-----title: Runtime & Providers-description: How components connect to external generation services such as Seedance.------# Runtime & Providers--Ordinary video authors should not need to initialize a Runtime or put API keys in project files.--## Author workflow--Sign in to a Provider once:--```bash-svml provider login seedance-```--Then import and use its component in a video:--```xml-<svml>- <import as="seedance" from="@svml/seedance@1"/>-- <seedance:speaker- script={story.segment.opening}- character="./host.png"- direction="Speak naturally to camera"- />-</svml>-```--Build normally:--```bash-svml build main.svml-```--## Who calls the API--The `@svml/seedance` package carries its own Runtime implementation for queueing, requesting, polling, and downloading. The official CLI loads it automatically when it encounters the component. Keys remain in the system keychain or the user's global SVML configuration; they never enter `.svml` files, lockfiles, or Git.--::: info Not implemented yet-This is the planned author workflow, not a command set already provided by the current repository. The existing implementation accepts prepared local media and capability artifacts only.-:::--Only developers embedding SVML inside another product need to work directly with APIs such as `createRuntime()`.diff --git a/docs/en/quickstart.md b/docs/en/quickstart.mddeleted file mode 100644index c640e19e..00000000--- a/docs/en/quickstart.md+++ /dev/null@@ -1,70 +0,0 @@-----title: Quickstart-description: Check and compile your first SVML video in minutes.------# Quickstart--Start with a spoken script and compile it into a video page ready for HyperFrames to render.--## Install--SVML currently requires Node.js 22 and pnpm.--```bash-pnpm install-pnpm build-```--## Start with a real example--The Ranking example in this repository uses `@name … @/name` to declare semantic ranges in the spoken script, then lets components consume those ranges. Here is the core excerpt:--```xml-<svml version="1">- <import from="../../stdlib/ranking-column.svk"/>-- <script>- <segment id="ranking">- <NARRATOR> @photoshop Photoshop.- <SPEAKER> Powerful, but only if you know how to use it.- Otherwise it becomes a three-hour project @/photoshop.- </segment>- </script>-- <ranking-column id="ranking" z="42">- <item- id="photoshop"- rank="5"- image={ranking-icon-5}- during={script.selection.photoshop}- />- </ranking-column>-</svml>-```--There is no hand-written “second 3 to second 7.” The locator resolves the `photoshop` Selection against the spoken script and media into the real time range for this build.--## Check and compile--```bash-pnpm svml check examples/regen-ranking/regen-ranking.svml-pnpm svml lock examples/regen-ranking/regen-ranking.svml --out svml.lock-pnpm svml compile examples/regen-ranking/regen-ranking.svml \- --lock svml.lock \- --out build/index.html-```--`check` verifies that the declarations are complete; `lock` freezes the inputs actually used by this build; `compile` produces deterministic HyperFrames HTML.--## Render--```bash-pnpm svml render build/index.html --out build/video.mp4-```--::: warning Current status-The executable example requires its local media and alignment evidence. Automatic loading from online Providers is not implemented yet.-:::--Continue to [Components](/en/guide/components) to learn how recurring visual treatments can be packaged as SVK components.diff --git a/docs/guide/components.md b/docs/guide/components.mdindex b31ce15c..602fa29b 100644--- a/docs/guide/components.md+++ b/docs/guide/components.md@@ -1,15 +1,15 @@----title: 创建 SVK 组件-description: 把重复的视频表现封装成可复用组件。+title: Create SVK Components+description: Package recurring video treatments as reusable components.----# 创建 SVK 组件+# Create SVK Components-SVK 是 SVML 的可复用组件。作者写“我要什么”,组件决定“具体怎样做”。+SVK is the reusable component format for SVML. Authors describe what they want; the component decides how to produce it.-## 一个最小组件+## A minimal component-假设我们想封装一个排名卡片。作者只需要写:+Suppose we want to package a ranking card. The author only needs to write:```xml<script>@@ -24,21 +24,21 @@ SVK 是 SVML 的可复用组件。作者写“我要什么”,组件决定“/>```-组件内部负责字体、布局、入场方式和输出的 Track。换句话说,视频作者不需要每次重新搭节点或手调十几个参数。+The component owns its typography, layout, entrance behavior, and output Track. Video authors do not need to rebuild the node graph or tune a dozen parameters every time.-## 组件应该隐藏什么+## What a component should hide-- 重复的内部接线和默认值-- 视觉样式、动画和媒体摆放-- 对 HyperFrames 输出的具体实现+- Repeated internal wiring and defaults+- Visual styling, animation, and media placement+- The concrete HyperFrames output implementation-## 组件不应该隐藏什么+## What a component should not hide-- 会明显改变作者意图的选择-- 例如硬切、淡入淡出或推拉转场-- 例如这个卡片应该绑定哪一段口播稿+- Choices that materially change the author's intent+- Whether a transition is a hard cut, fade, or push+- Which part of the spoken script the card should bind to-好的组件会提供简单但清楚的选择:+Good components expose a small set of clear choices:```xml<ranking-card@@ -48,6 +48,6 @@ SVK 是 SVML 的可复用组件。作者写“我要什么”,组件决定“/>```-## 下一步+## Next-需要调用视频生成 API 的组件,还会带一个 Runtime 实现。作者侧只声明内容,Runtime 侧负责请求、排队和下载。参见[运行时与 Provider](/guide/runtime)。+Components that call video-generation APIs also ship with a Runtime implementation. Authors declare the content; the Runtime handles requests, queues, and downloads. See [Runtime & Providers](/guide/runtime).diff --git a/docs/guide/runtime.md b/docs/guide/runtime.mdindex cd4ba710..124cfe7e 100644--- a/docs/guide/runtime.md+++ b/docs/guide/runtime.md@@ -1,21 +1,21 @@----title: 运行时与 Provider-description: 组件怎样连接 Seedance 等外部生成服务。+title: Runtime & Providers+description: How components connect to external generation services such as Seedance.----# 运行时与 Provider+# Runtime & Providers-普通视频作者不需要初始化 Runtime,也不需要在项目文件里写 API Key。+Ordinary video authors should not need to initialize a Runtime or put API keys in project files.-## 作者怎么用+## Author workflow-登录一次 Provider:+Sign in to a Provider once:```bashsvml provider login seedance```-然后在视频里导入和使用组件:+Then import and use its component in a video:```xml<svml>@@ -24,23 +24,23 @@ svml provider login seedance<seedance:speakerscript={story.segment.opening}character="./host.png"- direction="正对镜头自然说话"+ direction="Speak naturally to camera"/></svml>```-最后正常构建:+Build normally:```bashsvml build main.svml```-## 谁负责请求 API+## Who calls the API-`@svml/seedance` 包自己携带 Runtime 实现,负责排队、请求、轮询和下载。官方 CLI 在看到这个组件后自动加载它。Key 保存在系统钥匙串或用户的全局 SVML 配置里,不进入 `.svml`、锁文件或 Git。+The `@svml/seedance` package carries its own Runtime implementation for queueing, requesting, polling, and downloading. The official CLI loads it automatically when it encounters the component. Keys remain in the system keychain or the user's global SVML configuration; they never enter `.svml` files, lockfiles, or Git.-::: info 尚未实现-这是计划中的普通用户体验,不是当前仓库已经提供的命令。现有实现只接受已经准备好的本地媒体与能力产物。+::: info Not implemented yet+This is the planned author workflow, not a command set already provided by the current repository. The existing implementation accepts prepared local media and capability artifacts only.:::-只有把 SVML 嵌入自己产品的开发者,才需要接触 `createRuntime()` 之类的开发接口。+Only developers embedding SVML inside another product need to work directly with APIs such as `createRuntime()`.diff --git a/docs/index.md b/docs/index.mdindex f33661d3..cefca32f 100644--- a/docs/index.md+++ b/docs/index.md@@ -5,10 +5,10 @@ hero:name: "Narratage"actions:- theme: brand- text: 快速开始+ text: Quickstartlink: /quickstart- theme: alt- text: 开发指南+ text: Developlink: /guide/components---diff --git a/docs/public/narratage-logo-vector.svg b/docs/public/narratage-logo-vector.svgnew file mode 100644index 00000000..870c8251--- /dev/null+++ b/docs/public/narratage-logo-vector.svg@@ -0,0 +1,22 @@+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 603 296" role="img" aria-labelledby="title desc">+ <title id="title">Narratage mark and wordmark</title>+ <desc id="desc">A clean black vector mark combining an at sign, a film strip, and the NARRA TAGE wordmark.</desc>+ <g fill="#000" fill-rule="evenodd">+ <circle cx="130" cy="84" r="90" fill="none" stroke="#000" stroke-width="29"/>+ <circle cx="130" cy="84" r="39" fill="none" stroke="#000" stroke-width="39"/>+ <path d="M163 137h62a14 14 0 0 1 0 28h-62z"/>+ <path d="M10 190h216a10 10 0 0 1 10 10v86a10 10 0 0 1-10 10H10A10 10 0 0 1 0 286v-86a10 10 0 0 1 10-10zm48 96h148v-86h-72c-44 0-76 29-76 68zm-40-76h20v20H18zm0 34h20v20H18zm0 34h20v20H18zm164-68h20v20h-20zm0 34h20v20h-20zm0 34h20v20h-20z"/>+ </g>+ <g fill="#000">+ <path d="M108 0V1544H506L715 1002Q732 954 753.5 892.0Q775 830 801 749L844 613Q821 814 809.0 957.0Q797 1100 797 1197V1544H1195V0H797L587 568Q554 659 527.5 738.5Q501 818 481 890Q494 727 500.0 606.0Q506 485 506 394V0Z" transform="translate(258.000,149) scale(0.0553,-0.067)"/>+ <path d="M1220 0H789L758 196H477L443 0H12L383 1544H893ZM709 527 682 707Q681 708 678 734Q676 756 657 908Q655 925 652.0 954.5Q649 984 644 1029L631 1175Q629 1154 625.5 1128.0Q622 1102 618 1071Q611 1009 608.0 985.0Q605 961 604 956L575 769L533 527Z" transform="translate(330.056,149) scale(0.0553,-0.067)"/>+ <path d="M1206 0H755L549 550Q546 564 538.5 587.0Q531 610 520 642L523 540V0H108V1544H535Q817 1544 957 1433Q1135 1291 1135 1029Q1135 749 896 642ZM525 829H553Q625 829 673.0 884.0Q721 939 721 1024Q721 1197 540 1197H525Z" transform="translate(398.241,149) scale(0.0553,-0.067)"/>+ <path d="M1206 0H755L549 550Q546 564 538.5 587.0Q531 610 520 642L523 540V0H108V1544H535Q817 1544 957 1433Q1135 1291 1135 1029Q1135 749 896 642ZM525 829H553Q625 829 673.0 884.0Q721 939 721 1024Q721 1197 540 1197H525Z" transform="translate(466.592,149) scale(0.0553,-0.067)"/>+ <path d="M1220 0H789L758 196H477L443 0H12L383 1544H893ZM709 527 682 707Q681 708 678 734Q676 756 657 908Q655 925 652.0 954.5Q649 984 644 1029L631 1175Q629 1154 625.5 1128.0Q622 1102 618 1071Q611 1009 608.0 985.0Q605 961 604 956L575 769L533 527Z" transform="translate(534.942,149) scale(0.0553,-0.067)"/>+ <path d="M647 0H230V1174H0V1544H886V1174H647Z" transform="translate(351.000,286) scale(0.0576,-0.067)"/>+ <path d="M1220 0H789L758 196H477L443 0H12L383 1544H893ZM709 527 682 707Q681 708 678 734Q676 756 657 908Q655 925 652.0 954.5Q649 984 644 1029L631 1175Q629 1154 625.5 1128.0Q622 1102 618 1071Q611 1009 608.0 985.0Q605 961 604 956L575 769L533 527Z" transform="translate(402.034,286) scale(0.0576,-0.067)"/>+ <path d="M645 893H1227V829Q1227 383 1094 187Q949 -27 665 -27Q386 -27 227 183Q69 395 69 765Q69 1140 228.0 1356.0Q387 1572 663 1572Q1029 1572 1194 1190L790 1042Q781 1115 748.5 1157.5Q716 1200 667 1200Q495 1200 495 727Q495 526 533.0 435.0Q571 344 654 344Q687 344 714.0 360.0Q741 376 759.5 405.0Q778 434 788.5 475.5Q799 517 799 568H645Z" transform="translate(473.054,286) scale(0.0576,-0.067)"/>+ <path d="M108 0V1544H883V1181H525V956H846V607H525V371H883V0Z" transform="translate(547.762,286) scale(0.0576,-0.067)"/>+ </g>+</svg>+diff --git a/docs/quickstart.md b/docs/quickstart.mdindex 9c535944..26089282 100644--- a/docs/quickstart.md+++ b/docs/quickstart.md@@ -1,24 +1,24 @@---title: Quickstart-description: 在几分钟内检查并编译第一支 SVML 视频。+description: Check and compile your first SVML video in minutes.---# Quickstart-从一份口播稿开始,编译出可交给 HyperFrames 渲染的视频页面。+Start with a spoken script and compile it into a video page ready for HyperFrames to render.-## 安装+## Install-SVML 目前需要 Node.js 22 和 pnpm。+SVML currently requires Node.js 22 and pnpm.```bashpnpm installpnpm build```-## 先看一个真实例子+## Start with a real example-仓库里的 Ranking 示例用 `@name … @/name` 在口播稿中声明语义范围,再让组件消费这个范围。下面是核心节选:+The Ranking example in this repository uses `@name … @/name` to declare semantic ranges in the spoken script, then lets components consume those ranges. Here is the core excerpt:```xml<svml version="1">@@ -43,9 +43,9 @@ pnpm build</svml>```-这里没有手写“第 3 秒到第 7 秒”。定位器会根据口播与媒体,把 `photoshop` Selection 解析成这次构建的真实时间。+There is no hand-written “second 3 to second 7.” The locator resolves the `photoshop` Selection against the spoken script and media into the real time range for this build.-## 检查与编译+## Check and compile```bashpnpm svml check examples/regen-ranking/regen-ranking.svml@@ -55,16 +55,16 @@ pnpm svml compile examples/regen-ranking/regen-ranking.svml \--out build/index.html```-`check` 检查声明是否完整;`lock` 固定本次构建实际使用的输入;`compile` 生成确定的 HyperFrames HTML。+`check` verifies that the declarations are complete; `lock` freezes the inputs actually used by this build; `compile` produces deterministic HyperFrames HTML.-## 渲染+## Render```bashpnpm svml render build/index.html --out build/video.mp4```-::: warning 当前状态-可执行示例需要其本地媒体和对齐证据。在线 Provider 自动加载尚未实现。+::: warning Current status+The executable example requires its local media and alignment evidence. Automatic loading from online Providers is not implemented yet.:::-接下来可以去[开发指南](/guide/components),了解怎样把常用视觉封装成 SVK 组件。+Continue to [Components](/guide/components) to learn how recurring visual treatments can be packaged as SVK components.diff --git a/docs/zh/guide/components.md b/docs/zh/guide/components.mdnew file mode 100644index 00000000..2433e1df--- /dev/null+++ b/docs/zh/guide/components.md@@ -0,0 +1,53 @@+---+title: 创建 SVK 组件+description: 把重复的视频表现封装成可复用组件。+---++# 创建 SVK 组件++SVK 是 SVML 的可复用组件。作者写“我要什么”,组件决定“具体怎样做”。++## 一个最小组件++假设我们想封装一个排名卡片。作者只需要写:++```xml+<script>+ <segment id="ranking">+ <HOST>Here is @winner our number one pick @/winner.+ </segment>+</script>++<ranking-card+ title="Top 5 tools"+ during={script.selection.winner}+/>+```++组件内部负责字体、布局、入场方式和输出的 Track。换句话说,视频作者不需要每次重新搭节点或手调十几个参数。++## 组件应该隐藏什么++- 重复的内部接线和默认值+- 视觉样式、动画和媒体摆放+- 对 HyperFrames 输出的具体实现++## 组件不应该隐藏什么++- 会明显改变作者意图的选择+- 例如硬切、淡入淡出或推拉转场+- 例如这个卡片应该绑定哪一段口播稿++好的组件会提供简单但清楚的选择:++```xml+<ranking-card+ during={script.selection.winner}+ enter="fade 200ms"+ exit="push-left 300ms"+/>+```++## 下一步++需要调用视频生成 API 的组件,还会带一个 Runtime 实现。作者侧只声明内容,Runtime 侧负责请求、排队和下载。参见[运行时与 Provider](/zh/guide/runtime)。diff --git a/docs/zh/guide/runtime.md b/docs/zh/guide/runtime.mdnew file mode 100644index 00000000..cd4ba710--- /dev/null+++ b/docs/zh/guide/runtime.md@@ -0,0 +1,46 @@+---+title: 运行时与 Provider+description: 组件怎样连接 Seedance 等外部生成服务。+---++# 运行时与 Provider++普通视频作者不需要初始化 Runtime,也不需要在项目文件里写 API Key。++## 作者怎么用++登录一次 Provider:++```bash+svml provider login seedance+```++然后在视频里导入和使用组件:++```xml+<svml>+ <import as="seedance" from="@svml/seedance@1"/>++ <seedance:speaker+ script={story.segment.opening}+ character="./host.png"+ direction="正对镜头自然说话"+ />+</svml>+```++最后正常构建:++```bash+svml build main.svml+```++## 谁负责请求 API++`@svml/seedance` 包自己携带 Runtime 实现,负责排队、请求、轮询和下载。官方 CLI 在看到这个组件后自动加载它。Key 保存在系统钥匙串或用户的全局 SVML 配置里,不进入 `.svml`、锁文件或 Git。++::: info 尚未实现+这是计划中的普通用户体验,不是当前仓库已经提供的命令。现有实现只接受已经准备好的本地媒体与能力产物。+:::++只有把 SVML 嵌入自己产品的开发者,才需要接触 `createRuntime()` 之类的开发接口。diff --git a/docs/en/index.md b/docs/zh/index.mdsimilarity index 57%rename from docs/en/index.mdrename to docs/zh/index.mdindex c386c9c8..cc2920e5 100644--- a/docs/en/index.md+++ b/docs/zh/index.md@@ -5,11 +5,11 @@ hero:name: "Narratage"actions:- theme: brand- text: Quickstart- link: /en/quickstart+ text: 快速开始+ link: /zh/quickstart- theme: alt- text: Develop- link: /en/guide/components+ text: 开发指南+ link: /zh/guide/components---<ClientOnly>diff --git a/docs/zh/quickstart.md b/docs/zh/quickstart.mdnew file mode 100644index 00000000..1287cd9e--- /dev/null+++ b/docs/zh/quickstart.md@@ -0,0 +1,70 @@+---+title: Quickstart+description: 在几分钟内检查并编译第一支 SVML 视频。+---++# Quickstart++从一份口播稿开始,编译出可交给 HyperFrames 渲染的视频页面。++## 安装++SVML 目前需要 Node.js 22 和 pnpm。++```bash+pnpm install+pnpm build+```++## 先看一个真实例子++仓库里的 Ranking 示例用 `@name … @/name` 在口播稿中声明语义范围,再让组件消费这个范围。下面是核心节选:++```xml+<svml version="1">+ <import from="../../stdlib/ranking-column.svk"/>++ <script>+ <segment id="ranking">+ <NARRATOR> @photoshop Photoshop.+ <SPEAKER> Powerful, but only if you know how to use it.+ Otherwise it becomes a three-hour project @/photoshop.+ </segment>+ </script>++ <ranking-column id="ranking" z="42">+ <item+ id="photoshop"+ rank="5"+ image={ranking-icon-5}+ during={script.selection.photoshop}+ />+ </ranking-column>+</svml>+```++这里没有手写“第 3 秒到第 7 秒”。定位器会根据口播与媒体,把 `photoshop` Selection 解析成这次构建的真实时间。++## 检查与编译++```bash+pnpm svml check examples/regen-ranking/regen-ranking.svml+pnpm svml lock examples/regen-ranking/regen-ranking.svml --out svml.lock+pnpm svml compile examples/regen-ranking/regen-ranking.svml \+ --lock svml.lock \+ --out build/index.html+```++`check` 检查声明是否完整;`lock` 固定本次构建实际使用的输入;`compile` 生成确定的 HyperFrames HTML。++## 渲染++```bash+pnpm svml render build/index.html --out build/video.mp4+```++::: warning 当前状态+可执行示例需要其本地媒体和对齐证据。在线 Provider 自动加载尚未实现。+:::++接下来可以去[开发指南](/zh/guide/components),了解怎样把常用视觉封装成 SVK 组件。