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
Add standard bilingual documentation routes
rpone930ce9a30e9b
diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.tsindex ed8703da..80189554 100644--- a/docs/.vitepress/config.ts+++ b/docs/.vitepress/config.ts@@ -22,8 +22,63 @@ const noctisBordo = {],};+const sharedTheme = {+ siteTitle: "NARRATAGE",+ socialLinks: [{ icon: "github" as const, link: "https://github.com/cashdiffusion/svml" }],+ search: { provider: "local" as const },+};++const zhTheme = {+ ...sharedTheme,+ nav: [+ { text: "快速开始", link: "/quickstart" },+ { text: "开发指南", link: "/guide/components" },+ ],+ sidebar: {+ "/quickstart": [+ { text: "开始使用", items: [{ text: "Quickstart", link: "/quickstart" }] },+ ],+ "/guide/": [+ {+ text: "开发指南",+ items: [+ { text: "创建组件", link: "/guide/components" },+ { text: "运行时与 Provider", link: "/guide/runtime" },+ ],+ },+ ],+ },+ outline: { level: [2, 3] as [number, number], label: "本页目录" },+ docFooter: { prev: "上一页", next: "下一页" },+};++const enTheme = {+ ...sharedTheme,+ nav: [+ { text: "Quickstart", link: "/en/quickstart" },+ { text: "Develop", link: "/en/guide/components" },+ ],+ sidebar: {+ "/en/quickstart": [+ { text: "Getting Started", items: [{ text: "Quickstart", link: "/en/quickstart" }] },+ ],+ "/en/guide/": [+ {+ text: "Develop",+ items: [+ { text: "Components", link: "/en/guide/components" },+ { text: "Runtime & Providers", link: "/en/guide/runtime" },+ ],+ },+ ],+ },+ outline: { level: [2, 3] as [number, number], label: "On this page" },+ docFooter: { prev: "Previous", next: "Next" },+};+export default defineConfig({base: "/docs/",+ lang: "zh-CN",title: "Narratage",description: "Write the story. Compile the video.",appearance: false,@@ -42,6 +97,11 @@ export default defineConfig({},head: [["meta", { name: "theme-color", content: "#2C2126" }],+ [+ "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)})()`,+ ],["link", { rel: "preconnect", href: "https://fonts.googleapis.com" }],["link", { rel: "preconnect", href: "https://fonts.gstatic.com", crossorigin: "" }],[@@ -59,32 +119,9 @@ export default defineConfig({},],],- themeConfig: {- siteTitle: "NARRATAGE",- nav: [- { text: "快速开始", link: "/quickstart" },- { text: "开发指南", link: "/guide/components" },- ],- sidebar: {- "/quickstart": [- {- text: "开始使用",- items: [{ text: "Quickstart", link: "/quickstart" }],- },- ],- "/guide/": [- {- text: "开发指南",- items: [- { text: "创建组件", link: "/guide/components" },- { text: "运行时与 Provider", link: "/guide/runtime" },- ],- },- ],- },- socialLinks: [{ icon: "github", link: "https://github.com/cashdiffusion/svml" }],- search: { provider: "local" },- outline: { level: [2, 3], label: "本页目录" },- docFooter: { prev: "上一页", next: "下一页" },+ locales: {+ root: { label: "简体中文", lang: "zh-CN", themeConfig: zhTheme },+ en: { label: "English", lang: "en-US", link: "/en/", themeConfig: enTheme },},+ themeConfig: zhTheme,});diff --git a/docs/.vitepress/theme/components/HeroStatement.vue b/docs/.vitepress/theme/components/HeroStatement.vueindex 86f22d30..fdb26a0d 100644--- a/docs/.vitepress/theme/components/HeroStatement.vue+++ b/docs/.vitepress/theme/components/HeroStatement.vue@@ -1,5 +1,6 @@<script setup lang="ts">-import { onBeforeUnmount, onMounted, ref } from "vue";+import { computed, onBeforeUnmount, onMounted, ref } from "vue";+import { useData } from "vitepress";const statements = [{@@ -41,6 +42,8 @@ const statements = [];const activeIndex = ref(0);+const { lang } = useData();+const showChinese = computed(() => lang.value.toLowerCase().startsWith("zh"));let rotationTimer: ReturnType<typeof setInterval> | undefined;onMounted(() => {@@ -70,7 +73,7 @@ onBeforeUnmount(() => {</Transition></div>- <div class="hero-statement-viewport hero-statement-viewport-zh">+ <div class="hero-statement-viewport hero-statement-viewport-zh" :class="{ 'is-locale-hidden': !showChinese }"><Transition name="hero-statement-swap"><p :key="activeIndex" class="hero-statement-zh"><span class="hero-statement-line">{{ statements[activeIndex].zhBefore }}<span class="hero-statement-accent">{{ statements[activeIndex].zhAudience }}</span>{{ statements[activeIndex].zhConnector }}{{ statements[activeIndex].zhConcept }}{{ statements[activeIndex].zhAfter }}</span>diff --git a/docs/.vitepress/theme/components/LocalePreference.vue b/docs/.vitepress/theme/components/LocalePreference.vuenew file mode 100644index 00000000..551391a0--- /dev/null+++ b/docs/.vitepress/theme/components/LocalePreference.vue@@ -0,0 +1,35 @@+<script setup lang="ts">+import { onBeforeUnmount, onMounted } from "vue";++const storageKey = "narratage-locale";++function localeFromPath(pathname: string) {+ return pathname.startsWith("/docs/en/") ? "en" : "zh";+}++function rememberLocale(event: MouseEvent) {+ const target = event.target as HTMLElement | null;+ const link = target?.closest<HTMLAnchorElement>("a[href]");+ if (!link) return;+ const url = new URL(link.href, window.location.href);+ if (!url.pathname.startsWith("/docs/")) return;+ try {+ window.localStorage.setItem(storageKey, localeFromPath(url.pathname));+ } catch {+ // Storage can be unavailable in private or restricted browser contexts.+ }+}++onMounted(() => {+ try {+ window.localStorage.setItem(storageKey, localeFromPath(window.location.pathname));+ } catch {+ // Storage can be unavailable in private or restricted browser contexts.+ }+ document.addEventListener("click", rememberLocale, true);+});++onBeforeUnmount(() => document.removeEventListener("click", rememberLocale, true));+</script>++<template></template>diff --git a/docs/.vitepress/theme/components/SemanticVideoDemo.vue b/docs/.vitepress/theme/components/SemanticVideoDemo.vueindex 8eddbcfc..107a414c 100644--- a/docs/.vitepress/theme/components/SemanticVideoDemo.vue+++ b/docs/.vitepress/theme/components/SemanticVideoDemo.vue@@ -11,6 +11,7 @@ import { goodBetterBestMedia, resolveDemoMedia } from "./demo-media";import { demoPointerIsInside } from "./demo-pointer";import { wordAtTime } from "./demo-word-timing";import { useSourcePanelInteraction } from "./source-panel-interaction";+import { useData } from "vitepress";import {semanticVideoDemos,type DemoId,@@ -29,6 +30,8 @@ const props = withDefaults(defineProps<{ demo: DemoId; active?: boolean; showHeashowHeading: true,});const emit = defineEmits<{ ended: [] }>();+const { lang } = useData();+const isChinese = computed(() => lang.value.toLowerCase().startsWith("zh"));const config = semanticVideoDemos[props.demo];const sourceLines = config.lines;const sceneSelections = config.selections.filter((selection) => selection.layer === "scene");@@ -598,9 +601,9 @@ onBeforeUnmount(() => {</script><template>- <section class="svml-demo semantic-video-demo" aria-label="SVML 交互式实时渲染预览">+ <section class="svml-demo semantic-video-demo" :aria-label="isChinese ? 'SVML 交互式实时渲染预览' : 'Interactive SVML live-render preview'"><header v-if="props.showHeading" class="demo-heading">- <h2><span class="hover-interaction-copy">悬停标记范围,查看对应画面</span><span class="touch-interaction-copy">点击标记范围,查看对应画面</span></h2>+ <h2><span class="hover-interaction-copy">{{ isChinese ? "悬停标记范围,查看对应画面" : "Hover a marked range to see the corresponding frame" }}</span><span class="touch-interaction-copy">{{ isChinese ? "点击标记范围,查看对应画面" : "Tap a marked range to see the corresponding frame" }}</span></h2></header><div class="demo-shell real-demo-shell">@@ -626,9 +629,13 @@ onBeforeUnmount(() => {</div></div><div class="source-follow-hint">- {{ sourceUsesHover- ? (sourceFollowEnabled ? "移入查看所有源码" : "移出查看精简视图")- : (sourceFollowEnabled ? "点击代码查看所有源码" : "点击空白处返回精简视图") }}+ {{ isChinese+ ? (sourceUsesHover+ ? (sourceFollowEnabled ? "移入查看所有源码" : "移出查看精简视图")+ : (sourceFollowEnabled ? "点击代码查看所有源码" : "点击空白处返回精简视图"))+ : (sourceUsesHover+ ? (sourceFollowEnabled ? "Move in to view all source" : "Move out for the compact view")+ : (sourceFollowEnabled ? "Tap the code to view all source" : "Tap outside for the compact view")) }}</div><div ref="codeScrollElement" class="code-scroll" aria-label="SVML source code" @scroll="updateRangeGeometry"><svgdiff --git a/docs/.vitepress/theme/components/SvmlDemoCarousel.vue b/docs/.vitepress/theme/components/SvmlDemoCarousel.vueindex c7656064..11b417b6 100644--- a/docs/.vitepress/theme/components/SvmlDemoCarousel.vue+++ b/docs/.vitepress/theme/components/SvmlDemoCarousel.vue@@ -7,14 +7,18 @@ import {type DemoMediaManifest,} from "./demo-media";import { clearDemoPointer, updateDemoPointer } from "./demo-pointer";+import { useData } from "vitepress";import SemanticVideoDemo from "./SemanticVideoDemo.vue";import SvmlPlayground from "./SvmlPlayground.vue";const cards = [- { component: SvmlPlayground, props: undefined, label: "AI 图片应用排名" },- { component: SemanticVideoDemo, props: { demo: "street" as const }, label: "街头采访" },- { component: SemanticVideoDemo, props: { demo: "good-better-best" as const }, label: "Good Better Best" },+ { component: SvmlPlayground, props: undefined, labelZh: "AI 图片应用排名", labelEn: "AI photo app ranking" },+ { component: SemanticVideoDemo, props: { demo: "street" as const }, labelZh: "街头采访", labelEn: "Street interview" },+ { component: SemanticVideoDemo, props: { demo: "good-better-best" as const }, labelZh: "Good Better Best", labelEn: "Good Better Best" },];+const { lang } = useData();+const isChinese = computed(() => lang.value.toLowerCase().startsWith("zh"));+const cardLabel = (card: (typeof cards)[number]) => isChinese.value ? card.labelZh : card.labelEn;const selectedIndex = ref(0);const playingIndex = ref<number | null>(null);const loadedIndices = ref<Set<number>>(new Set());@@ -132,13 +136,13 @@ onBeforeUnmount(() => { activationId += 1; });@pointerleave="clearDemoPointer"><header class="demo-heading carousel-heading">- <h2><span class="hover-interaction-copy">悬停标记范围,查看对应画面</span><span class="touch-interaction-copy">点击标记范围,查看对应画面</span></h2>+ <h2><span class="hover-interaction-copy">{{ isChinese ? "悬停标记范围,查看对应画面" : "Hover a marked range to see the corresponding frame" }}</span><span class="touch-interaction-copy">{{ isChinese ? "点击标记范围,查看对应画面" : "Tap a marked range to see the corresponding frame" }}</span></h2></header><div class="demo-carousel-stage"><articlev-for="(card, index) in cards"- :key="card.label"+ :key="card.labelEn"class="demo-card":class="cardPosition(index)":aria-hidden="index !== selectedIndex"@@ -147,13 +151,13 @@ onBeforeUnmount(() => { activationId += 1; });v-if="index !== selectedIndex"class="demo-card-select"type="button"- :aria-label="`查看${card.label}演示`"+ :aria-label="isChinese ? `查看${cardLabel(card)}演示` : `View the ${cardLabel(card)} demo`"@click="activateDemo(index)"></button><div v-if="!loadedIndices.has(index)" class="demo-loading" role="status" aria-live="polite"><span class="demo-loading-spinner" aria-hidden="true"></span>- <span>加载演示素材…</span>+ <span>{{ isChinese ? "加载演示素材…" : "Loading demo media…" }}</span></div><divv-else@@ -171,22 +175,22 @@ onBeforeUnmount(() => { activationId += 1; });</article></div>- <nav class="demo-carousel-controls" aria-label="切换示例">- <button class="arrow-button" type="button" aria-label="上一个示例" @click="move(-1)">+ <nav class="demo-carousel-controls" :aria-label="isChinese ? '切换示例' : 'Switch demos'">+ <button class="arrow-button" type="button" :aria-label="isChinese ? '上一个示例' : 'Previous demo'" @click="move(-1)"><svg viewBox="0 0 24 24" aria-hidden="true"><path d="M14.7 5.3 8 12l6.7 6.7 1.4-1.4-5.3-5.3 5.3-5.3z"/></svg></button>- <div class="demo-carousel-dots" aria-label="选择示例">+ <div class="demo-carousel-dots" :aria-label="isChinese ? '选择示例' : 'Choose a demo'"><buttonv-for="(card, index) in cards"- :key="card.label"+ :key="card.labelEn"type="button":class="{ active: index === selectedIndex }"- :aria-label="`查看${card.label}演示`"+ :aria-label="isChinese ? `查看${cardLabel(card)}演示` : `View the ${cardLabel(card)} demo`":aria-current="index === selectedIndex ? 'true' : undefined"@click="activateDemo(index)"></button></div>- <button class="arrow-button" type="button" aria-label="下一个示例" @click="move(1)">+ <button class="arrow-button" type="button" :aria-label="isChinese ? '下一个示例' : 'Next demo'" @click="move(1)"><svg viewBox="0 0 24 24" aria-hidden="true"><path d="m9.3 5.3-1.4 1.4 5.3 5.3-5.3 5.3 1.4 1.4L16 12z"/></svg></button></nav>diff --git a/docs/.vitepress/theme/components/SvmlPlayground.vue b/docs/.vitepress/theme/components/SvmlPlayground.vueindex 69e43fce..52ba8494 100644--- a/docs/.vitepress/theme/components/SvmlPlayground.vue+++ b/docs/.vitepress/theme/components/SvmlPlayground.vue@@ -13,6 +13,7 @@ import { createDemoTimeline } from "./demo-timeline";import { wordAtTime } from "./demo-word-timing";import { wordCues as rawWordCues, type WordCue } from "./regen-ranking-cues";import { useSourcePanelInteraction } from "./source-panel-interaction";+import { useData } from "vitepress";import {buildFoldedSourceView,buildFullSourceView,@@ -24,6 +25,8 @@ const props = withDefaults(defineProps<{ active?: boolean; showHeading?: booleanshowHeading: true,});const emit = defineEmits<{ ended: [] }>();+const { lang } = useData();+const isChinese = computed(() => lang.value.toLowerCase().startsWith("zh"));type RankingSelectionId = "photoshop" | "facetune" | "remini" | "chatgpt" | "regen";type BrollSelectionId = "handsome-1" | "handsome-2" | "dating-photo" | "linkedin-headshot" | "instagram-post";@@ -836,9 +839,9 @@ onBeforeUnmount(() => {</script><template>- <section class="svml-demo" aria-label="SVML 交互式实时渲染预览">+ <section class="svml-demo" :aria-label="isChinese ? 'SVML 交互式实时渲染预览' : 'Interactive SVML live-render preview'"><header v-if="props.showHeading" class="demo-heading">- <h2><span class="hover-interaction-copy">悬停标记范围,查看对应画面</span><span class="touch-interaction-copy">点击标记范围,查看对应画面</span></h2>+ <h2><span class="hover-interaction-copy">{{ isChinese ? "悬停标记范围,查看对应画面" : "Hover a marked range to see the corresponding frame" }}</span><span class="touch-interaction-copy">{{ isChinese ? "点击标记范围,查看对应画面" : "Tap a marked range to see the corresponding frame" }}</span></h2></header><div@@ -868,9 +871,13 @@ onBeforeUnmount(() => {</div></div><div class="source-follow-hint">- {{ sourceUsesHover- ? (sourceFollowEnabled ? "移入查看所有源码" : "移出查看精简视图")- : (sourceFollowEnabled ? "点击代码查看所有源码" : "点击空白处返回精简视图") }}+ {{ isChinese+ ? (sourceUsesHover+ ? (sourceFollowEnabled ? "移入查看所有源码" : "移出查看精简视图")+ : (sourceFollowEnabled ? "点击代码查看所有源码" : "点击空白处返回精简视图"))+ : (sourceUsesHover+ ? (sourceFollowEnabled ? "Move in to view all source" : "Move out for the compact view")+ : (sourceFollowEnabled ? "Tap the code to view all source" : "Tap outside for the compact view")) }}</div><div ref="codeScrollElement" class="code-scroll" aria-label="SVML source code" @scroll="updateRangeGeometry"><svgdiff --git a/docs/.vitepress/theme/index.ts b/docs/.vitepress/theme/index.tsindex 061a8a6a..f61013a1 100644--- a/docs/.vitepress/theme/index.ts+++ b/docs/.vitepress/theme/index.ts@@ -2,6 +2,7 @@ import DefaultTheme from "vitepress/theme";import type { Theme } from "vitepress";import { h } from "vue";import HeroStatement from "./components/HeroStatement.vue";+import LocalePreference from "./components/LocalePreference.vue";import SvmlDemoCarousel from "./components/SvmlDemoCarousel.vue";import "./style.css";@@ -9,6 +10,7 @@ export default {extends: DefaultTheme,Layout: () =>h(DefaultTheme.Layout, null, {+ "layout-top": () => h(LocalePreference),"home-hero-info": () => h(HeroStatement),}),enhanceApp({ app }) {diff --git a/docs/.vitepress/theme/style.css b/docs/.vitepress/theme/style.cssindex b58ebe2c..df0bc52a 100644--- a/docs/.vitepress/theme/style.css+++ b/docs/.vitepress/theme/style.css@@ -45,6 +45,7 @@}html { background: var(--paper); }+.hero-statement-viewport-zh.is-locale-hidden { height: 0 !important; margin-top: 0; visibility: hidden; opacity: 0 !important; transform: none !important; pointer-events: none; }body {background: var(--paper);color: var(--ink);diff --git a/docs/en/guide/components.md b/docs/en/guide/components.mdnew file mode 100644index 00000000..0d8c7134--- /dev/null+++ b/docs/en/guide/components.md@@ -0,0 +1,53 @@+---+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.mdnew file mode 100644index 00000000..124cfe7e--- /dev/null+++ b/docs/en/guide/runtime.md@@ -0,0 +1,46 @@+---+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/index.md b/docs/en/index.mdnew file mode 100644index 00000000..c386c9c8--- /dev/null+++ b/docs/en/index.md@@ -0,0 +1,17 @@+---+layout: home++hero:+ name: "Narratage"+ actions:+ - theme: brand+ text: Quickstart+ link: /en/quickstart+ - theme: alt+ text: Develop+ link: /en/guide/components+---++<ClientOnly>+ <SvmlDemoCarousel />+</ClientOnly>diff --git a/docs/en/quickstart.md b/docs/en/quickstart.mdnew file mode 100644index 00000000..c640e19e--- /dev/null+++ b/docs/en/quickstart.md@@ -0,0 +1,70 @@+---+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.