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: add a Chinese README and cut explanatory filler
rpone632d1e1ad5ea
diff --git a/.agents/skills/narratage/references/playbooks/craft/captions.md b/.agents/skills/narratage/references/playbooks/craft/captions.mdindex e3514eb9..72cbd02e 100644--- a/.agents/skills/narratage/references/playbooks/craft/captions.md+++ b/.agents/skills/narratage/references/playbooks/craft/captions.md@@ -84,3 +84,33 @@ captions, omit the Caption components entirely.overlap with Media/Text Tracks.- Listen while reviewing: a visually plausible Caption Track still fails if it leads or trails theactual spoken word.++## Show it in a browser only when style is genuinely in question++Caption Playground is a local visual editor that reads and writes the same `.svml` and `.svs` files+a Build compiles, so edits land in the author source rather than a side format.++Start it in two situations only:++- the user asks to see or tune captions visually;+- you cannot settle a styling decision from the source alone — size, padding, fill, safe-zone+ collision, line wrapping against real speech timing — and a rendered frame would settle it.++Otherwise author the Recipe directly. Every field the playground exposes is writable from the+source, and starting a server nobody asked for interrupts the user for nothing.++```bash+pnpm caption:playground -- \+ --source main.svml \+ --package-lock svml.packages.lock \+ --style base-caption \+ --display story.caption \+ --recipe studio.svs#caption.base \+ --font main.svml#caption-font \+ --canvas 1080x1920 \+ --fps 30+```++It serves `http://localhost:5178`. You cannot see that page yourself: give the user the URL, say+which Recipe fields you want judged, and wait for their answer before continuing. Every argument is+an explicit selection — `docs/guide/caption-playground.md` lists what each one selects.diff --git a/README.md b/README.mdindex 5fda9c77..5f88efa8 100644--- a/README.md+++ b/README.md@@ -5,10 +5,11 @@<p align="center"><em>“First, there was narration. Then, there were montages.”</em></p><p align="center">- <a href="https://narratage.hypit.ai/">Documentation</a> ·- <a href="https://narratage.hypit.ai/zh/">中文文档</a> ·- <a href="https://narratage.hypit.ai/quickstart">Quickstart</a> ·- <a href="./examples/README.md">Examples</a>+ <a href="https://narratage.hypit.ai/quickstart">Quickstart</a>+ + <a href="https://narratage.hypit.ai/guide/develop">Develop</a>+ + <a href="./README.zh-CN.md">简体中文</a></p>Narratage is a semantic, graph-native system for making AI video. You write the story, choose the@@ -94,8 +95,8 @@ instead of nesting. `tagline` shows that a Segment may be roleless. Repeating thcreates multiple non-contiguous occurrences.Marker names carry no built-in behavior: `@silence` does not mute audio; an Audio, Caption or Trackcomponent must explicitly consume that Selection. The complete escape set and Slot parser contract-are documented in [Script](https://narratage.hypit.ai/quickstart/script); Slot binding is not yet exposed by the-author-facing `<script>` Surface, so the README does not pretend it is usable source syntax today.+are documented in [Script](https://narratage.hypit.ai/quickstart/script). Slot binding is not yet+exposed by the author-facing `<script>` Surface.The outer component lines are deliberately an excerpt: they show how generated media, alignment andTracks consume Script projections. See the complete, checkable@@ -138,8 +139,6 @@ WhisperX, OpenCV or HyperFrames.| `svml.packages.lock` | Generated lock for author and compute packages || `svml.runtime-packages.lock` | Generated lock for Runtime and Provider packages |-The boundaries are deliberate:-- SVML says what the author means and explicitly chooses model families where that choice matters.- SVRUN says what this Run should produce and which compatible results should satisfy its outputs.- The Runtime Profile says where those operations execute.diff --git a/README.zh-CN.md b/README.zh-CN.mdnew file mode 100644index 00000000..912d177b--- /dev/null+++ b/README.zh-CN.md@@ -0,0 +1,262 @@+<p align="center">+ <img alt="Narratage" src="docs/public/narratage-logo.svg" width="420">+</p>++<p align="center"><em>“First, there was narration. Then, there were montages.”</em></p>++<p align="center">+ <a href="https://narratage.hypit.ai/zh/quickstart">快速开始</a>+ + <a href="https://narratage.hypit.ai/zh/guide/develop">开发</a>+ + <a href="./README.md">English</a>+</p>++Narratage 是一套面向 AI 视频创作的语义化、图原生系统。你写下故事,选择模型与视觉组件,声明想要哪些+输出;Narratage 把这份意图变成一张有限的执行计划,只运行结果真正依赖的工作,并把每一个已接受的输出+保留下来,供后续 Run 使用。++SVML 是创作语言,Narratage 是围绕它的编译器、运行时与包生态。++Narratage 目前从源码仓库运行,npm 包与 CLI 尚未发布。++## 它写起来是什么样++Script 始终是可读的散文。Segment 组织故事,Role Cue 指明谁在说话,Dual Text 把观众看到的文字与说话者+念出的内容分开,Selection 与 Moment 为语义区间和时间点命名——全程不引入时间码。++```xml+<script id="story">+ @whole++ <opening>+ <MARA> @mystery @beat At <2:13 A.M. | two thirteen in the morning>,+ every billboard in the city began telling the same story. @/beat @/mystery+ </opening>++ <reveal>+ <!-- The screens wake before the city does. -->+ @claim+ <NOAH> Whose story?+ <MARA> Mine. They spent ten years ~@proof cutting me out of @flash!+ every photograph. @/claim So I put myself back into all of them @/proof~.+ <NOAH> @beat You rewrote the whole city? @/beat+ <MARA> I < | only> changed one thing ~@cut!: the ending.+ I signed it \@midnight.+ </reveal>++ @silence+ <pause/>+ @/silence++ <tagline>+ By sunrise, the city remembered the woman history had erased.+ </tagline>++ @/whole~+</script>++<seedance:TextVideo id="take"+ model="mini"+ prompt={story.segment.opening.dialogue}+ duration="5"+ generate-audio="true"/>++<whisperx:Alignment id="timing"+ narrative={story}+ audio={speech.audio}/>++<media-track:Item+ video={motion.video}+ during={story.selection.proof}+ frame={card-frame}/>+```++这段 Script 展示了完整的标记词汇:++| 写法 | 含义 |+|---|---|+| `<opening>...</opening>` / `<pause/>` | 有台词的 Segment 与空 Segment |+| `<MARA>` | Role Cue,持续到下一个 Cue 或 Segment 结束 |+| `<2:13 A.M. \| two thirteen in the morning>` | 左侧为显示文字,右侧为念出的文字 |+| `< \| only>` | 只念不显示的口语衬词 |+| `@mystery ... @/mystery` | 边界向内吸收的 Selection |+| `~@proof ... @/proof~` | 边界向外吸收的 Selection |+| 重复的 `@beat ... @/beat` | 一个 Selection 的多次不连续出现 |+| `@flash!` / `~@cut!` | 附着在下一个词开头 / 上一个词结尾的 Moment |+| `\@midnight` | 字面量 `@midnight`,不是标记 |+| `<!-- ... -->` | 源码注释,不进入任何文字投影 |++`@whole` 跨越了 Segment 边界;`@claim` 与 `proof` 表明 Selection 可以交叉而非只能嵌套;`tagline`+说明 Segment 可以没有角色。重复同一个 Selection id 会产生多次不连续的出现。+标记名本身不带行为:`@silence` 不会让音频静音,必须由 Audio、Caption 或 Track 组件显式消费这个+Selection。完整的转义规则与 Slot 解析契约见 [Script](https://narratage.hypit.ai/zh/quickstart/script)。+面向作者的 `<script>` Surface 目前尚未暴露 Slot 绑定。++外层的组件行是刻意节选的,用来展示生成媒体、对齐与 Track 如何消费 Script 的投影。完整且可检查的源码+见 [`talking-film-graph-check`](./examples/talking-film-graph-check/main.svml),其中包含 import、+布局、字幕、Film 与渲染。带命名空间的组件都来自包,Core 不硬编码 Seedance、WhisperX、Caption 或 Film。++## 不需要 API Key 也能试++需要 Node.js 22+ 与 pnpm 10.33.x。下面的命令会安装源码工作区,并在不启动任何 Provider、不产生任何+付费请求的前提下编译出一张完整的视频图:++```bash+git clone https://github.com/hypit-ai/narratage.git+cd narratage+corepack enable+pnpm install --frozen-lockfile++node --run narratage -- check examples/talking-film-graph-check/main.svml \+ --package-lock examples/talking-film-graph-check/svml.packages.lock++node --run narratage -- plan examples/talking-film-graph-check/build.svrun \+ --package-lock examples/talking-film-graph-check/svml.packages.lock+```++`check` 校验 Author Source 并打印它的类型化输出。`plan` 展示被真正需要的子图,以及一次真实 Build 会+用到的每一项外部能力。Plan 阶段永远不会启动外部工作。++如果 Corepack 不可用,或者你想运行本地 media、WhisperX、OpenCV 或 HyperFrames,请看+[快速开始](https://narratage.hypit.ai/zh/quickstart)。++## 你掌控的文件++| 文件 | 用途 |+|---|---|+| `main.svml` | 这支视频:Script、所选模型、Track 与 Composition |+| `studio.svs` | 可选。由 Author Source 导入的可复用视觉与提示词 Recipe |+| `build.svrun` | 一次 Run 需要的输出,包括显式复用或替换的 Candidate |+| `svml.runtime.json` | 机器环境:Store、Endpoint、凭据与并发 |+| `svml.packages.lock` | 生成的 Author 与计算包 lock |+| `svml.runtime-packages.lock` | 生成的 Runtime 与 Provider 包 lock |++- SVML 表达作者的意图,并在模型族的选择会影响结果时显式作出选择。+- SVRUN 表达这次 Run 要产出什么,以及哪些既有结果可以满足这些输出。+- Runtime Profile 表达这些 Operation 在哪里执行。+- Provider 把精确的能力请求翻译成本地程序或远程 API,不会重新解释作者的创作选择。++## 从源码到成品++```text+main.svml + studio.svs+ │+ ▼+ Author Graph ◀──── build.svrun 选择 Target 与 Candidate+ │+ ▼+ 冻结的 BuildPlan 此时尚未启动任何外部工作+ │+ ▼+ Runtime Profile ─────── Worker、Store 与确切的 Provider Endpoint+ │+ ▼+ 已接受的 Record ────── 可检查、可复用,或用 `get` 取出+```++不存在特权化的“最终视频”根节点。一次 Run 的 Target 可以是一张生成的图片、一份转写映射、一条 Track,+也可以是完成的成片。编译器从这些 Target 反向追溯依赖,不调度无关的工作。++## 跑一个真实项目++把视频项目放在 Narratage 仓库之外。源码开发阶段,从项目目录调用仓库里的轻量启动器:++```bash+cd /path/to/my-video++# 一次性配置,之后只在 import 或 Runtime 包选择变化后重复。+/path/to/narratage/narratage packages sync build.svrun \+ --runtime svml.runtime.json++# 看清这次 Run 选中的确切工作。+/path/to/narratage/narratage plan build.svrun \+ --runtime svml.runtime.json++/path/to/narratage/narratage build build.svrun \+ --runtime svml.runtime.json \+ --build-id my-video-001 \+ --follow++/path/to/narratage/narratage get my-video-001 \+ --runtime svml.runtime.json \+ --name final.video \+ --to output/final.mp4+```++`build` 提交持久化的工作,并确保选定的 Worker 可用。`--follow` 只是观察这次 Build,关闭观察端不会取消+它。用 `status`、`queue`、`operations` 与 `inspect` 查看正在发生什么。`check` 用于编辑源码,+`doctor` 用于配置和排查部署——它们都不是每次 Build 前必须重复的仪式。++第一次付费 Build 之前,请先读+[Run Source 与 Build](https://narratage.hypit.ai/zh/quickstart/run),其中涵盖 Runtime Profile、+凭据、并发、取消,以及对既有输出的显式复用。++## 为什么用图语言++AI 生成慢、贵、易错,而且不确定;它的输出常常又是下一步的输入。线性脚本或隐藏的工作流执行器无法清楚+回答下面这些问题:++- 作者到底请求了什么?+- 此刻真正需要哪个结果?+- 由哪个实现、哪个 Provider 产出?+- 哪张既有图片或视频应当被有意复用?+- 什么可以并行,什么在等待上游结果?+- 最终被接受的输出究竟由什么产生?++Narratage 把这些选择呈现为两张平级的图:Author Graph 表达工作本身,Run Graph 为一次 Build 选择+Target 与实现。Core 只负责解析、校验并推进由此得到的状态机;视频领域的概念都留在可独立安装的包里。++规范性的最小法则见 [Core Kernel 规范](./spec/core-kernel.md)。++## 不改 Core 也能扩展++包可以各自独立地贡献:++- 面向作者的 Surface 及其图下降;+- 与其他包共享的类型化契约;+- 确定性的计算 Operation;+- 本地或远程的 Provider Endpoint;+- Scheduler、凭据 Store 或 Artifact Store 的实现。++Core 不维护视频模型、Track 或 Provider 的中央名单。已安装的包之间通过名义类型与显式的图边通信。++按你要做的事选择指南:++- [创作一支视频](https://narratage.hypit.ai/zh/quickstart)+- [理解包的边界](https://narratage.hypit.ai/zh/guide/packages)+- [添加一个 Author 包](https://narratage.hypit.ai/zh/guide/author-packages)+- [添加一个 Provider](https://narratage.hypit.ai/zh/guide/providers)+- [配置 Runtime Profile](https://narratage.hypit.ai/zh/guide/runtime-profile)+- [开发 Narratage 本身](https://narratage.hypit.ai/zh/guide/develop)++## 仓库结构++```text+packages/ Core、编译器、Runtime、视频包与 Provider 适配器+services/ WhisperX、OpenCV 等本地外部程序+examples/ 可检查的源码与完整的 Runtime 示例+docs/ narratage.hypit.ai 文档站点的源码+spec/ 规范性的协议与视频包契约+tools/ 仓库检查与专用开发工具+```++## 开发++下面的命令用于修改 Narratage 本身,不是用来做视频的:++```bash+pnpm check+pnpm test+pnpm docs:build+```++## 许可++Narratage 以 [Narratage 开源许可](./LICENSE) 发布,基于 Apache 2.0 并附加额外条款。你可以在自己的+基础设施上运行它,包括用于所在组织的商业工作;也可以 fork、修改并以相同条款公开源码。将 Narratage+作为多租户或托管服务运营,以及为商业利益向第三方提供它,都需要商业授权。你用 Narratage 产出的内容+归你所有。++以英文 [`LICENSE`](./LICENSE) 文本为准。商业授权请联系+[[email protected]](mailto:[email protected]?subject=%5BGitHub%5DNarratage%20Commercial%20License%20Inquiry)。diff --git a/docs/quickstart.md b/docs/quickstart.mdindex a8465ec1..4872651d 100644--- a/docs/quickstart.md+++ b/docs/quickstart.md@@ -12,8 +12,7 @@ a montage of scenes to match.That is exactly what this system does. The author writes a narrated Script with semantic anchors,and the compiler assembles generated video, captions, B-roll, text and audio into a finished film.-Words are the semantic spine; visual contributions remain independently authored Tracks. Author-Sources are written in SVML (Semantic Video Markup Language) and carry the `.svml` extension.+Author Sources are written in SVML (Semantic Video Markup Language) and carry the `.svml` extension.Narratage turns that source into a visible execution graph. Before any model or external serviceruns, you can check the source, choose a Run, and inspect the exact work it would require. This@@ -21,8 +20,7 @@ page gets you to that first safe plan: it needs no API keys and makes no paid ca## Use the Narratage skill-If you use a coding agent, ask it to use the repository's `narratage` skill. The skill follows the-same files and commands; it does not introduce a separate workflow. Send it this:+If you use a coding agent, send it this:```textInstall and use the narratage skill from this repository. Set up my environment, ask for only thediff --git a/docs/zh/quickstart.md b/docs/zh/quickstart.mdindex d9b1d7c8..bf74717e 100644--- a/docs/zh/quickstart.md+++ b/docs/zh/quickstart.md@@ -10,8 +10,8 @@ Glory*》的一篇影评。那位影评人造出这个词,用来描述当时**Narration + Montage** —— 旁白的声音推动故事前进,同时画面组接出与之呼应的蒙太奇。这套系统做的正是这件事。作者写下带有语义锚点的口播 Script,编译器则把生成的视频、字幕、B-roll、-文字与音频组装成一部完成的影片。文字是语义主轴,所有视觉内容以彼此平级的 Track 参与作品。-Author Source 使用 SVML(Semantic Video Markup Language)编写,扩展名为 `.svml`。+文字与音频组装成一部完成的影片。Author Source 使用 SVML(Semantic Video Markup Language)编写,+扩展名为 `.svml`。Narratage 把这份源码编译成一张可见的执行图。在任何模型或外部服务开始工作之前,你可以先检查源码、选择一次 Run,并看清这次 Build 究竟需要执行什么。本页先带你得到第一份安全的 Plan:不需要 API Key,@@ -19,8 +19,7 @@ Narratage 把这份源码编译成一张可见的执行图。在任何模型或## 使用 Narratage skill-如果使用编程 Agent,可以要求它使用仓库中的 `narratage` skill。Skill 遵循的仍然是同一套文件和命令,-不会创造另一套工作流。把下面这段发给它:+如果使用编程 Agent,把下面这段发给它:```text安装并使用这个仓库里的 narratage skill。配置我的环境,只向我索取当前 Runtime Profile