Skip to content

armgit / hypit

Public Imported from GitHub
0

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.

docs: teach the quickstart to preview before it generates

rponeaa65bb66db9f
diff --git a/.agents/skills/narratage/SKILL.md b/.agents/skills/narratage/SKILL.md
index 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-reco
then review the frozen plan before paid downstream work. Candidate selection has no Pin state or
fidelity 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.md
index 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 th
take. Every insert must earn its place in the story and remain independent from editorial text and
program 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, show
diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts
index 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.md
new file mode 100644
index 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.md
new file mode 100644
index 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) 讲解代码、时间线与画面之间的三方联动,嵌套层级的配色、
+键盘走带控制,以及声音是怎么处理的。