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: teach the quickstart to preview before it generates
rponeaa65bb66db9f
diff --git a/.agents/skills/narratage/SKILL.md b/.agents/skills/narratage/SKILL.mdindex 1eb3538a..f9449d08 100644--- a/.agents/skills/narratage/SKILL.md+++ b/.agents/skills/narratage/SKILL.md@@ -20,6 +20,8 @@ Source, and the declarative `svml.runtime.json` Runtime Profile separate.`references/playbooks/craft/visual-continuity.md`, then the relevant craft/format file.- Reference-video reconstruction → read `references/reference-vlm.md`; emit `main.svml`, optional`studio.svs`, and `build.svrun` directly.+- Showing an author what they have so far → start the SVML Playground and send them the link.+ See "Show the work" below.- Execution, Runtime control, Build inspection, or output retrieval → read`references/runtime.md`; diagnose and start the durable Runtime, `check` Author Source, `plan`before paid work, then submit, inspect, and retrieve the Build.@@ -46,5 +48,32 @@ Reuse any accepted generated image or take in the next `.svrun` with `build-recothen review the frozen plan before paid downstream work. Candidate selection has no Pin state orfidelity label.+## Show the work++After each step that changes a Source — a Script edit, a Frame moved, a B-roll placed, a Recipe+adjusted — start the Playground and give the author the link. Reading a diff is not the same as+seeing where a cutaway lands, and a Source draws before any Provider has run: an unmade shot stands+in as the picture it names, held for the length it declares.++```bash+pkill -f svml-playground || true # never leave the old one holding the port+pnpm svml:playground -- --source path/to/main.svml \+ --run path/to/build.svrun \+ --runtime path/to/svml.runtime.json &+# then send the author: http://localhost:5179/+```++Kill the previous server first. A second one silently picks another port, and the author ends up+looking at a stale preview while you describe a new one. Pass `--port` only when the author asked to+compare two Sources side by side, and send the port you actually used — read it from the startup+line rather than assuming `5179`.++Both extra arguments are optional and each answers one question. `--run` says which material and+which timings to read the Source with. `--runtime` says where material earlier Builds produced is+kept, and is needed only by a Source that reuses an accepted shot through `<build-record>`; without+it that one shot is refused by name and everything else still draws.++`docs/quickstart/preview.md` is the page to point an author at.+Preserve unrelated changes. Keep credentials, generated media, runtime state, and logs out of commits.The repository's docs remain the syntax authority.diff --git a/.agents/skills/narratage/references/playbooks/craft/b-roll.md b/.agents/skills/narratage/references/playbooks/craft/b-roll.mdindex d2c5d9f0..7426ef9b 100644--- a/.agents/skills/narratage/references/playbooks/craft/b-roll.md+++ b/.agents/skills/narratage/references/playbooks/craft/b-roll.md@@ -5,6 +5,18 @@ B-roll is authored visual evidence, context, or emotional progression outside thtake. Every insert must earn its place in the story and remain independent from editorial text andprogram audio.+## See it before you generate it++Where a cutaway lands, how long it holds, and whether its Frame sits in the right part of the+picture are all decided by the Source, not by the footage. The SVML Playground answers all three+without a generation: an Item whose material exists shows real frames, and one whose material does+not is still placed, still scrubbable, and marked as standing in. Timings are estimated until a+build or a Run Source supplies measured ones, and an estimated cut point will move once WhisperX has+heard the audio.++Do this after placing a Selection and before paying for a generation. Startup and arguments are in+`docs/quickstart/preview.md`; the routine is under "Show the work" in `SKILL.md`.+## Choose the story beats first- Write the shot list before writing prompts. Give every shot one clear job: establish context, showdiff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.tsindex 8ddf7893..30c16705 100644--- a/docs/.vitepress/config.ts+++ b/docs/.vitepress/config.ts@@ -139,6 +139,7 @@ const enTheme = {{ text: "Script", link: "/quickstart/script" },{ text: "SVS Stylesheets", link: "/quickstart/styles" },{ text: "Media & Generation", link: "/quickstart/generation" },+ { text: "Live Preview", link: "/quickstart/preview" },{ text: "Timing & Assembly", link: "/quickstart/timing" },{ text: "Caption, Media & Text", link: "/quickstart/tracks" },{ text: "Film & Rendering", link: "/quickstart/composition" },@@ -183,6 +184,7 @@ const zhTheme = {{ text: "Script", link: "/zh/quickstart/script" },{ text: "SVS 样式表", link: "/zh/quickstart/styles" },{ text: "媒体与生成", link: "/zh/quickstart/generation" },+ { text: "实时预览", link: "/zh/quickstart/preview" },{ text: "时序与装配", link: "/zh/quickstart/timing" },{ text: "字幕、Media 与文字", link: "/zh/quickstart/tracks" },{ text: "Film 与渲染", link: "/zh/quickstart/composition" },diff --git a/docs/quickstart/preview.md b/docs/quickstart/preview.mdnew file mode 100644index 00000000..7e2d2e67--- /dev/null+++ b/docs/quickstart/preview.md@@ -0,0 +1,131 @@+---+title: Live Preview+description: Read a Source as a timeline before anything has been generated.+---++# Live Preview++Everything up to this point has been declarative: a Script, some Recipes, a request for a generated+shot. None of it has produced a picture, and a Seedance take costs money and minutes.++The **SVML Playground** reads the Source itself and draws it — the code on the right, the picture+top-left, a timeline bottom-left. It never writes, and it never calls a Provider.++```bash+pnpm svml:playground -- --source examples/all-components-preview/main.svml+# ➜ http://localhost:5179/+```++| Argument | Meaning |+| --- | --- |+| `--source <main.svml>` | The Author Source to read. Required. |+| `--run <build.svrun>` | A Run Source, read for material and timings it already names. |+| `--runtime <svml.runtime.json>` | Where material earlier Builds produced is kept. Only a Source that reuses an accepted shot through `<build-record>` needs one. |+| `--port <number>` | Defaults to `5179`. |++Both optional arguments are additive. With neither, the Playground still runs on a directory holding+nothing but `main.svml` and its `.svs` style sheet — no package lock, no Runtime Profile, no build.++::: tip Start one server, not four+A second Playground silently takes another port, and you end up reading a stale preview while+describing a new one. Stop the old one first:++```bash+pkill -f svml-playground || true+```++Use `--port` when you genuinely want two Sources side by side.+:::++## Why it can draw a video nobody has made++A Track cannot be built without the material it places. Refusing to draw anything until every shot+exists would make the preview useless for exactly the part of the work it is meant for, so the+Playground separates what it **knows** from what it **assumes**, and says which is which.++**Everything structural is real.** Placement Frames, padding, stacking order, motion and the Track+layout are computed by the same functions a build calls, from your Source and your style sheet. A+card in the wrong part of the frame is wrong here too.++**Timings are estimated** until a build has aligned real audio. Word durations come from+`@narratage/estimate`, the same syllable model the pipeline uses before generation. An estimated+timeline is a proportion, not a prediction — real cut points move once WhisperX has run.++**Missing material stands in**, and each stand-in is announced rather than presented as fact:++| Missing | Shown instead |+| --- | --- |+| A generated shot that names a picture | That picture, held for the length the shot declares |+| A generated shot that names nothing | A black frame of the programme's shape |+| Caption phrasing nobody has planned | The words cut every few Atoms, in the Program's own runs |++The first row is the one that makes this worth opening early. Take the chain from+[Media & Generation](./generation):++```svml+<gpt:Image id="presenter" prompt={look} aspect-ratio="9:16" resolution="2K"/>++<seedance:ReferenceVideo id="take-opening" model="mini" prompt={direction} duration="8">+ <seedance:Reference image={presenter.image}/>+</seedance:ReferenceVideo>+```++`take-opening.video` does not exist until Seedance runs. But the Source says what it will be made+from — `presenter.image` — and how long it will last: `duration="8"`. So the Playground draws the+reference picture, held for eight seconds, in the Frame the take is placed in.++That is not the take. It is the right subject, in the right shape, for the right length, which is+enough to answer whether the framing works and whether the cutaway lands where the speech needs it —+**before** the picture flows into video generation, and before you have paid for a take that turns+out to be cut at the wrong moment.++A declared duration is honoured wherever one exists. Where none does, words are placed at an+ordinary delivery pace and the remaining time is divided evenly.++Drawing stand-ins needs `ffmpeg` on your `PATH`. Without it the shots stay unmade and the Tracks say+so, rather than the preview pretending they were drawn.++## Reading the badges++The header carries two separate claims, because they answer different questions:++| Badge | Meaning |+| --- | --- |+| `timing: measured` | Read from a completed build's aligned transcript. |+| `timing: estimated` | Derived from the Script text at normal delivery pace. |+| `picture: measured` | Every element shows real material. |+| `picture: estimated` | Some shots have not been made, and stand in. |++A Source can have all its footage and still have an estimated timeline: where a cut lands is a+question about speech, not about files. On the timeline itself each Track says whether it was+`made`, is a `stand-in`, or is a black frame, and selecting a clip names the reason in full.++## Feeding it what you already have++As material accumulates, the same preview gets more real without any change to `main.svml`. What a+Source is read with is an authoring decision, so it is made in a Run Source — see+[Run Source & Builds](./run):++```svml+<file id="take-1" type="@narratage/artifact@1#BlobArtifact"+ from="./assets/take-1.mp4" media-type="video/mp4"/>+<satisfy output="take-opening.video" candidate="take-1"/>+```++Point the Playground at it with `--run`, and that shot stops standing in. A `<build-record>`+candidate names something an earlier Build made rather than a path, and needs `--runtime` to find+it; without one, that shot alone is refused **by name** and everything else still draws.++## When an agent is doing the work++If you are working through the [Narratage skill](https://github.com/hypit-ai/narratage/blob/main/.agents/skills/narratage/SKILL.md),+the agent starts the Playground for you and sends you the link after each step that changes the+Source — a Script edit, a Frame moved, a B-roll placed, a Recipe adjusted.++Reading a diff is not the same as seeing where a cutaway lands, and this is the cheapest moment to+say "that card is too high" — before a single Provider has run.++## Next++[SVML Playground](/guide/svml-playground) covers the three-way selection between code, timeline and+picture, the nesting colours, keyboard transport, and how sound is handled.diff --git a/docs/zh/quickstart/preview.md b/docs/zh/quickstart/preview.mdnew file mode 100644index 00000000..56d2fcd2--- /dev/null+++ b/docs/zh/quickstart/preview.md@@ -0,0 +1,122 @@+---+title: 实时预览+description: 在任何素材生成之前,把 Source 当作时间线来读。+---++# 实时预览++到这里为止的一切都还是声明式的:一段 Script、若干 Recipe、一个生成镜头的请求。它们都还没有产出任何+画面,而一次 Seedance 生成既花钱又花时间。++**SVML Playground** 直接读取 Source 并把它画出来——右侧是代码,左上是画面,左下是时间线。它从不写入+任何东西,也从不调用 Provider。++```bash+pnpm svml:playground -- --source examples/all-components-preview/main.svml+# ➜ http://localhost:5179/+```++| 参数 | 含义 |+| --- | --- |+| `--source <main.svml>` | 要读取的 Author Source。必填。 |+| `--run <build.svrun>` | 一个 Run Source,从中读取它已经指名的素材与时序。 |+| `--runtime <svml.runtime.json>` | 早先 Build 产出的素材存放在哪里。只有通过 `<build-record>` 复用已接受镜头的 Source 才需要。 |+| `--port <number>` | 默认 `5179`。 |++两个可选参数是叠加的。两个都不给时,Playground 依然能在一个只有 `main.svml` 和 `.svs` 样式表的目录上+运行——不需要包锁、不需要 Runtime Profile、不需要任何构建。++::: tip 只开一个服务,不要开四个+第二个 Playground 会悄悄占用另一个端口,于是你一边读着过期的预览,一边描述着新的改动。先把旧的停掉:++```bash+pkill -f svml-playground || true+```++确实想并排看两个 Source 时,再用 `--port`。+:::++## 为什么它能画出还没人做出来的视频++一条 Track 离开它所安放的素材就无法构建。但如果非要等到每个镜头都存在才肯画,预览恰好会在它最该派上+用场的那个阶段变得毫无用处。所以 Playground 把**已知**的和**假设**的分开,并明确告诉你哪个是哪个。++**所有结构性的东西都是真的。** Placement Frame、padding、堆叠顺序、动效以及 Track 布局,都由构建时调用+的同一批函数、从你的 Source 和样式表算出。一张卡片如果在画面里的位置不对,在这里同样是不对的。++**时序是估算的**,直到某次构建对真实音频做过对齐为止。词的时长来自 `@narratage/estimate`——正是流水线在+生成之前使用的那套音节模型。估算出的时间线是一种比例,而不是一个预言:等 WhisperX 对齐了真实音频,实际+的剪切点会移动。++**缺失的素材会有替身**,而且每个替身都会被明确标注,不会被当作事实呈现:++| 缺失的 | 代之以 |+| --- | --- |+| 一个指名了参考图片的生成镜头 | 那张图片,按镜头声明的时长持续 |+| 一个什么都没指名的生成镜头 | 一帧符合节目画幅的黑场 |+| 无人规划过的字幕分句 | 按 Program 自己的 run,每隔几个 Atom 切一次 |++第一行正是值得你尽早打开它的理由。看[媒体与生成](./generation)里的这条链路:++```svml+<gpt:Image id="presenter" prompt={look} aspect-ratio="9:16" resolution="2K"/>++<seedance:ReferenceVideo id="take-opening" model="mini" prompt={direction} duration="8">+ <seedance:Reference image={presenter.image}/>+</seedance:ReferenceVideo>+```++在 Seedance 跑起来之前,`take-opening.video` 并不存在。但 Source 说清楚了它将由什么做成——+`presenter.image`——以及它会持续多久:`duration="8"`。于是 Playground 就把那张参考图画出来,持续八秒,+放在这个镜头所在的 Frame 里。++那不是最终的镜头。但它是**正确的主体、正确的画幅、正确的时长**,这已经足以回答构图对不对、以及这个空镜+是否落在语音需要它的位置上——**在**这张图片流入视频生成之前,也在你为一个剪切点其实不对的镜头付钱之前。++凡是存在声明时长的地方都会被遵守。没有声明的地方,词按正常语速安放,剩余时间平均分配。++绘制替身需要 `PATH` 上有 `ffmpeg`。没有它,这些镜头就保持未绘制状态、Track 会如实说明,而不是假装它们+已经画好了。++## 读懂徽章++顶部有两个彼此独立的判断,因为它们回答的是不同的问题:++| 徽章 | 含义 |+| --- | --- |+| `timing: measured` | 读自一次已完成构建的对齐转录。 |+| `timing: estimated` | 由 Script 文本按正常语速推导。 |+| `picture: measured` | 每个元素展示的都是真实素材。 |+| `picture: estimated` | 有镜头尚未做出来,正由替身顶替。 |++一个 Source 完全可能素材齐备、时间线却仍是估算的:剪切点落在哪里是关于语音的问题,不是关于文件的问题。+在时间线上,每条 Track 会标明自己是 `made`、是 `stand-in`、还是黑场;选中某个片段则会完整说明原因。++## 把已有的素材喂给它++随着素材逐渐积累,同一个预览会越来越接近真实,而 `main.svml` 一个字都不用改。用什么去读一个 Source 是+一项创作决策,因此它写在 Run Source 里——见 [Run Source 与构建](./run):++```svml+<file id="take-1" type="@narratage/artifact@1#BlobArtifact"+ from="./assets/take-1.mp4" media-type="video/mp4"/>+<satisfy output="take-opening.video" candidate="take-1"/>+```++用 `--run` 指向它,那个镜头就不再是替身。`<build-record>` 候选指名的是早先某次 Build 做出的东西而非+一个路径,需要 `--runtime` 才能找到;没有 `--runtime` 时,**只有那一个**镜头会被指名拒绝,其余一切照常+绘制。++## 当由 agent 来做这件事时++如果你正在通过 [Narratage skill](https://github.com/hypit-ai/narratage/blob/main/.agents/skills/narratage/SKILL.md)+工作,那么每当某个步骤改动了 Source——改了 Script、移了 Frame、放了 B-roll、调了 Recipe——agent 会为你+启动 Playground 并把链接发给你。++读 diff 和亲眼看见空镜落在哪里不是一回事,而此刻正是说出"那张卡片太靠上了"的最便宜的时机——在任何一个+Provider 跑起来之前。++## 下一步++[SVML Playground](/zh/guide/svml-playground) 讲解代码、时间线与画面之间的三方联动,嵌套层级的配色、+键盘走带控制,以及声音是怎么处理的。