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
Say what the tools take, not what they stopped taking
rpone429a2275e9ef
diff --git a/.agents/skills/hypit/references/playbooks/craft/b-roll.md b/.agents/skills/hypit/references/playbooks/craft/b-roll.mdindex 62247764..bdec7abd 100644--- a/.agents/skills/hypit/references/playbooks/craft/b-roll.md+++ b/.agents/skills/hypit/references/playbooks/craft/b-roll.md@@ -12,9 +12,8 @@ picture are all decided by the Source, not by the footage. Hypit Studio answersgeneration, provided the Run satisfies the material it places: cut points come from the aligned`SemanticTrack`, so where a cutaway falls against the speech is measured rather than guessed.-Studio does not stand anything in. An Item whose material no Candidate supplies makes the Run-unopenable rather than appearing as a placeholder, so satisfy the B-roll outputs in the Run Source-with whatever footage you already have before expecting to see the placement.+Satisfy the B-roll outputs in the Run Source with whatever footage you already have before expecting+to see the placement: an Item whose material no Candidate supplies makes the whole Run unopenable.Do this after placing a Selection and before paying for a generation. Startup and arguments are in`docs/quickstart/preview.md`; for how to see placed items against their real frames, readdiff --git a/.agents/skills/hypit/references/preview.md b/.agents/skills/hypit/references/preview.mdindex 1fec63bf..09662935 100644--- a/.agents/skills/hypit/references/preview.md+++ b/.agents/skills/hypit/references/preview.md@@ -13,7 +13,7 @@ Read the startup output for the chosen port. `--run` is required: Studio's unitSource, and it reads the Author SVML back out of it. Pass `--runtime` only when the Author Sourcereuses accepted Build records.-Studio does not degrade. It has no stand-ins and no estimated timing — when a projection is missing-it refuses to open and names the issue, so a Run that opens is a Run whose Tracks all resolved.+Studio opens a Run whose material is satisfied. When a projection is missing it names the issue and+stops, so a Run that opens is a Run whose Tracks all resolved.`docs/quickstart/preview.md` is authoritative.diff --git a/.agents/skills/hypit/references/reconstruction/final-sources.md b/.agents/skills/hypit/references/reconstruction/final-sources.mdindex bb419ae2..37d349f8 100644--- a/.agents/skills/hypit/references/reconstruction/final-sources.md+++ b/.agents/skills/hypit/references/reconstruction/final-sources.md@@ -88,10 +88,10 @@ how *well* a wired element is tuned to the reference; it does not govern whetherwired at all. Every failure this check reports must be repaired until the check passes. Repair asmany times as the failure needs, then re-run the check.-**One refusal is a pass, and it is the one you will see most.** Studio does not degrade: it has no-stand-ins, no black frames and no estimated timing, so a Source that still declares generation-cannot be opened at all. That is the ordinary state of a reconstruction nobody has paid a Build for,-and treating it as a failure would make this gate unsatisfiable.+**One refusal is a pass, and it is the one you will see most.** A Source that declares its generation+rather than performing it — which is this route's own rule — leaves the closure waiting on Providers,+and Studio requires the whole closure before it will open. That is the expected state of a delivery,+not a defect in it.So the check separates the two. When every issue is `the Studio projection closure requiresunresolved capabilities: …`, the graph traced all the way to a Film and a semantic spine and what@@ -108,11 +108,10 @@ Any other refusal means the graph is wrong and no amount of generation will fixRender target, a target that is not an output of the current SVML, no traceable Film composition, no`SemanticTake` / Speech Track chain. Those exit non-zero and have no attempt ceiling.-What this gate therefore proves is narrower than it used to be: that the graph is **wired**, not that-every track **draws**. A Producer that refuses the media kind it is handed will not be caught here,-because it is never handed anything until the Build runs. Verify those on the real Build, say so-plainly rather than reporting the check as more than it is, and do not let it stand in for the-delivery measurements in `../playbooks/craft/production-gates.md`.+What this gate proves is that the graph is **wired**, not that every track **draws**. A Producer that+refuses the media kind it is handed is not caught here, because nothing is handed to it until the+Build runs. Verify those on the real Build, report the check as exactly what it is, and do not let+it stand in for the delivery measurements in `../playbooks/craft/production-gates.md`.What this check cannot see is equally important: a track that *builds* but looks wrong — a typefacethat does not match, a colour that is off, a shape that is misplaced — reports no error here, becausediff --git a/.agents/skills/hypit/references/reconstruction/index.md b/.agents/skills/hypit/references/reconstruction/index.mdindex 0ba4dee3..02d0a72c 100644--- a/.agents/skills/hypit/references/reconstruction/index.md+++ b/.agents/skills/hypit/references/reconstruction/index.md@@ -14,10 +14,9 @@ submitted for the pictures, and no video generation, speech synthesis, alignmentrun. Those belong to a later step that the author starts deliberately, after reading what waswritten.-Because nothing has been generated, the author cannot open the delivered sources in Studio — Studio-has no stand-ins and refuses a Source whose shots are still declared. Seeing the reconstruction is-what the author's first Build is for. What is *not* deferred is that the graph traces, which is the-part a Build cannot repair.+Seeing the reconstruction is what the author's first Build is for: Studio opens a Run whose material+is satisfied, and until that Build runs this one's is not. What is *not* deferred is that the graph+traces, which is the part a Build cannot repair.One exception, because it is not a generation of the video: a component's own surface — the field itselements are drawn on, whatever that is — is produced while the package is authored, withdiff --git a/.agents/skills/hypit/references/reconstruction/reconstruction-loop.md b/.agents/skills/hypit/references/reconstruction/reconstruction-loop.mdindex 3052d305..d6e6e7a7 100644--- a/.agents/skills/hypit/references/reconstruction/reconstruction-loop.md+++ b/.agents/skills/hypit/references/reconstruction/reconstruction-loop.md@@ -10,9 +10,9 @@ element is *wired at all* is a different gate with a different rule: `preview-chwithout any attempt ceiling. A graph that does not trace is not a difference to weigh; it is workthat is not done.-Note what that gate no longer covers. Studio has no stand-ins, so nothing is drawn before a Build-and `preview-check` proves the graph is wired rather than that every track draws. A Producer that-refuses the media it is handed surfaces on the real Build, not here.+Note what that gate covers: `preview-check` proves the graph is wired, not that every track draws.+Nothing is handed to a Producer until the Build runs, so a Producer that refuses the media it+receives surfaces there rather than here.The difference between the two gates is what each reports. `preview-check` names the graph failure —the target that does not trace, the chain that is missing — so its repairs are not guessing. Thisdiff --git a/.agents/skills/hypit/scripts/preview-check.mjs b/.agents/skills/hypit/scripts/preview-check.mjsindex 6568a2a7..6f8c9ea4 100644--- a/.agents/skills/hypit/scripts/preview-check.mjs+++ b/.agents/skills/hypit/scripts/preview-check.mjs@@ -15,18 +15,15 @@* the Run — it reads the Author SVML back out of it — so a check that took the* `.svml` would be checking something Studio never opens.*- * Studio does not degrade. It has no stand-ins and no estimated timing: when a- * projection is missing it refuses to open and names the issue, so preflight- * throwing is itself the failure report rather than something to inspect around.- *- * That refusal alone would make this gate unsatisfiable, because a Source that- * still declares generation always has unresolved capabilities — which is the- * ordinary state of a reconstruction before anybody has paid for a Build. So the- * two are separated here: an unresolved *capability* means the graph is sound- * and waiting for a Provider, while every other issue means the graph is wrong- * and no amount of generation will fix it. Only the second kind fails this- * check. `StudioPreflightError` carries `issues` as an array precisely so the- * two can be told apart rather than matched out of one joined message.+ * Studio names what it cannot resolve and stops, so preflight throwing is itself+ * the report rather than something to inspect around. Two kinds of issue come+ * back, and they mean opposite things. An unresolved *capability* means the+ * graph traced all the way to a Film and a semantic spine, and what remains is+ * work a Provider has to do — the ordinary state of a Source that declares its+ * generation rather than performing it. Every other issue means the graph is+ * wrong and no amount of generation will fix it. Only the second kind fails.+ * `StudioPreflightError` carries `issues` as an array so the two can be told+ * apart rather than matched out of one joined message.** Run it from the repository root. `tsx` is the repository's own dependency, so* a working directory outside the repository fails to resolve it before thisdiff --git a/docs/quickstart/composition.md b/docs/quickstart/composition.mdindex d82de83c..ff5b5e30 100644--- a/docs/quickstart/composition.md+++ b/docs/quickstart/composition.md@@ -35,7 +35,7 @@ and layers them by stacking order.|---|---|---|| `id` | yes | Unique identifier || `canvas` | yes | Explicit CanvasSpace shared with Track layout |-| `space` | yes | ProgramSpace from `speech:Track` — defines duration and frame rate |+| `semantic` | yes | SemanticTrack from `speech:Track` — defines duration and frame rate || `appearance` | yes | SVS Film Recipe — the canvas clear color |### film:Track@@ -89,7 +89,7 @@ Compiles the Composition into a finished video via the HyperFrames renderer.|---|---|---|| `id` | yes | Unique identifier || `composition` | yes | Composition from `film:Film` |-| `space` | yes | ProgramSpace from `speech:Track` |+| `semantic` | yes | SemanticTrack from `speech:Track` |The renderer:diff --git a/docs/quickstart/preview.md b/docs/quickstart/preview.mdindex 7afa55d8..f0d15806 100644--- a/docs/quickstart/preview.md+++ b/docs/quickstart/preview.md@@ -9,20 +9,18 @@ description: Read a Run whose material exists as an editable timeline.and draws them — the code on the right, the picture top-left, a timeline bottom-left. It neverwrites anything but the Author SVML, and it never calls a Provider.-That last clause is the one to read twice. Studio builds only what it can derive deterministically-from Candidates the Run already supplies, so **a Source that still declares ungenerated shots will-not open.** Studio is where you inspect and adjust a programme whose material exists; it is not a-way to look at one before the material does.+Studio builds only what it can derive deterministically from Candidates the Run already supplies, so+it needs a Run whose material is satisfied — every generated output either produced by an accepted+Build or standing against a file. That is what you point it at.```bashpnpm studio -- --run path/to/build.svrun# ➜ http://localhost:5179/```-::: warning No example in this repository currently opens-Every Run Source under `examples/` is either pre-generation — its shots still need Seedance, GPT-Image, WhisperX or caption planning — or depends on footage under `examples/**/assets/`, which is-not committed. Both cases refuse. Point Studio at a Run of your own whose outputs are satisfied.+::: warning The examples in this repository need material first+Every Run Source under `examples/` still names shots a Provider has to make, or footage under+`examples/**/assets/`, which is not committed. Satisfy those in a Run of your own before opening it.:::| Argument | Meaning |@@ -47,7 +45,7 @@ pkill -f "@hypit/studio" || trueUse `--port` when you genuinely want two Runs side by side.:::-## What Studio will and will not do+## What Studio drawsStudio builds the deterministic closure of the Run and nothing else. Opening it never invokes aProvider and never creates a Build, so every projection it draws was either supplied by the Run as@@ -57,19 +55,17 @@ a Candidate or derived deterministically from one.layout are computed by the same functions a build calls, from your Source and your Recipes. A cardin the wrong part of the frame is wrong here too.-**Timings are measured, always.** The timeline comes from the `SemanticTrack` — the aligned Takes-themselves — so a cut point you see is the cut point a build produces. There is no estimated mode.+**Every timing is measured.** The timeline comes from the `SemanticTrack` — the aligned Takes+themselves — so a cut point you see is the cut point a build produces.-**Nothing stands in.** Studio has no placeholder pictures, no black frames and no fabricated-timings. This is the deliberate half of the trade: rather than draw something it cannot justify and-label it, Studio refuses to open and says what is missing.+When something the closure needs is missing, Studio says so and stops:```Studio cannot start:- the Studio projection closure requires unresolved capabilities: seedance.video```-The refusals you are likely to meet:+What it asks for:| Refusal | What it means || --- | --- |@@ -80,9 +76,8 @@ The refusals you are likely to meet:| `Render target … is an opaque media Candidate; Studio needs the current Film graph` | The Run points at a finished video file. Studio edits the graph, not the output. |The fourth is the one you will meet most, and it is all-or-nothing: one unresolved capability-anywhere in the closure refuses the whole Run, rather than that Track alone going dark. So a-programme becomes openable in one step — when the last of its generated outputs is satisfied — and-not gradually.+anywhere in the closure refuses the whole Run. A programme becomes openable in one step, when the+last of its generated outputs is satisfied.## Supplying material you already have@@ -95,29 +90,20 @@ not gradually.A `<build-record>` candidate names something an earlier Build made rather than a path, and needs`--runtime` to find it.-## Reading the badges--The header carries two claims, and on a Run that opens they are both `measured` — that is what-opening means. They stay in the interface because they say *what* they are standing for:--| Badge | Meaning |-| --- | --- |-| `timing: measured` | Read from the aligned `SemanticTrack`. |-| `picture: measured` | Every element shows real material. |+## Where a Track came fromSelecting a Track names the Candidate that produced it and where it came from — the Run, the Source,-or neither.+or neither. The header carries the same claim for the programme as a whole: `timing: measured` reads+from the aligned `SemanticTrack`, `picture: measured` that every element shows real material.## When an agent is doing the workIf you are working through the [Hypit skill](https://github.com/hypit-ai/hypit/blob/main/.agents/skills/hypit/SKILL.md),the agent starts Studio for you and sends you the link after a step that changes the Source — a-Script edit, a Frame moved, a B-roll placed, a Recipe adjusted — once the Run it is working against-opens at all.+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. On a Run whose material exists this-is the cheapest moment to say "that card is too high"; on one whose shots are still declared, the-agent has nothing to show you and will say so rather than send a link.+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".## Moving around itdiff --git a/docs/quickstart/timing.md b/docs/quickstart/timing.mdindex 7b078fe1..3640d01a 100644--- a/docs/quickstart/timing.md+++ b/docs/quickstart/timing.md@@ -11,8 +11,7 @@ Hypit's timing authority is a `SemanticTrack`. Build it in segment-sized pieces:2. align that normalized media with its authored Script Segment to create a self-contained `SemanticTake`;3. assemble the Semantic Takes in program order with `speech:Track`.-There is no whole-program transcription pass after concatenation. Every Take is already semantic-before it enters the Track.+Every Take is already semantic before it enters the Track.```svml<import as="program" from="@hypit/program-space@1"/>@@ -120,7 +119,7 @@ deterministic Track:Use `during={story.segment.answer}` for a whole Segment, a Selection for an authored range, a Momentfor a point event, and `during="program"` for the complete SemanticTrack domain. Components consume-`semantic={speech.semantic}`; they do not receive separate `map` and `space` values.+`semantic={speech.semantic}`.```textraw take ─► Normalize ─► SynchronizedMedia ─► SemanticTake ─┐diff --git a/docs/quickstart/tracks.md b/docs/quickstart/tracks.mdindex a81057e2..2d3ecb3b 100644--- a/docs/quickstart/tracks.md+++ b/docs/quickstart/tracks.md@@ -233,10 +233,9 @@ then choose its exact program window and occupancy:| Attribute | Required | Description ||---|---|---|| `Track.id` | yes | Stable Audio Track identity |-| `Track.space` | yes | ProgramSpace that defines the exact sample and frame domain |+| `Track.semantic` | yes | SemanticTrack that defines the exact sample and frame domain || `Clip.source` | yes | Explicitly selected and normalized `SynchronizedMedia` || `during`, `at`/`for`, or `start`/`end` | exactly one form | Whole-program, Selection, Moment, or explicit window |-| `map` | for Selection/Moment | SemanticMap used to resolve semantic timing || `playback` | no | `once`, `once-end`, `loop`, `loop-end`, or bounded `stretch` || `occurrences` | no | `one` or `each` when a semantic source has multiple occurrences || `trim-start`, `trim-end` | no | Exact source trim |@@ -275,8 +274,7 @@ Container for text items.| Attribute | Required | Description ||---|---|---|| `id` | yes | Unique identifier |-| `space` | yes | ProgramSpace from `speech:Track` |-| `map` | no | SemanticMap — needed when items use Selection-based timing |+| `semantic` | yes | SemanticTrack from `speech:Track` — also resolves Selection-based item timing |### text:Point, text:Area and text:Path@@ -351,14 +349,17 @@ against the variant, so a Column recipe on a TierBoard is refused by name.| Attribute | Takes ||---|---|-| `map` | the Semantic Map that places words |-| `space` | the Program Space |-| `frame` | a `space:Frame` |+| `semantic` | the SemanticTrack the board is timed against |+| `frame` | a `space:Frame` — for `Column`, the fixed ranking rail || `during` | a Selection — the board is on screen for it |-| `triggers` | a Moment — rows move on it |-| `terminal` | a Moment — the board settles on it || `style` | the matching style record, and only that variant's || `appear-sound`, `move-sound` | optional Synchronized Media |+| `triggers`, `terminal` | Moments — rows move on one, the board settles on the other. `TierBoard` and `TopThree` only |+| `canvas` | a `space:Canvas` — the reveal stage. `Column` only |++`Column` separates placement from reveal time, so it takes neither `triggers` nor `terminal`: each+item carries its own reveal window instead, and the Column resolves siblings into non-overlapping+windows inside the container's `during` span.`move-sound` is refused on `TopThree`, which has no move phase. On a `TierBoard` it needs at leastone item with `entry="stage"` — a sound with nothing to sound on is an authoring mistake, not a@@ -370,17 +371,23 @@ Each variant takes its own, at least one, and ids must be unique within a board.- **`TierItem`** — `tier` (required, matching a row id in the recipe), `icon` (required), optional`entry="direct" | "stage"` and `stack`. Row labels come from the recipe, not the tag.-- **`ColumnItem`** and **`TopThreeItem`** — `label` (required: a string or a Text reference), optional- `icon` and `stack`. `TopThree` takes at most three.+- **`TopThreeItem`** — `label` (required: a string or a Text reference), optional `icon` and `stack`.+ At most three.+- **`ColumnItem`** — `label` (required) and `rank` (required, a positive integer that decides the+ numbered row and nothing else), optional `icon` and `stack`. Each item also owns its reveal time:+ `during` names a Selection whose projected window is when it prefers to appear, and+ `preset="true"` marks a row that starts already placed. Exactly one of the two — an item with+ neither, or with both, is refused by name.```svml<ranking:ColumnStyle id="board-style" recipe={recipes.ranking.board} font={ui-font}/>-<ranking:Column id="board" semantic={speech.semantic} frame={board-frame}- during={story.selection.board} triggers={story.moment.place} terminal={story.moment.done}- style={board-style}>- <ranking:ColumnItem id="row-regen" label="ReGen" icon={icon-regen}/>- <ranking:ColumnItem id="row-chatgpt" label="ChatGPT" icon={icon-chatgpt}/>- <ranking:ColumnItem id="row-remini" label="Remini" icon={icon-remini}/>+<ranking:Column id="board" semantic={speech.semantic} canvas={vertical} frame={board-frame}+ during={story.selection.board} style={board-style}>+ <ranking:ColumnItem id="row-regen" rank="1" label="ReGen" icon={icon-regen}+ during={story.selection.regen-reveal}/>+ <ranking:ColumnItem id="row-chatgpt" rank="2" label="ChatGPT" icon={icon-chatgpt}+ during={story.selection.chatgpt-reveal}/>+ <ranking:ColumnItem id="row-remini" rank="3" preset="true" label="Remini" icon={icon-remini}/></ranking:Column>```@@ -399,7 +406,7 @@ same Frame and moves the whole stack.### deck:DepthStack-`id`, `map`, `space`, `canvas`, `frame` and `appearance` are all required, as is `until`, which says+`id`, `semantic`, `canvas`, `frame` and `appearance` are all required, as is `until`, which sayswhat ends the deck: the literal `"program.end"`, a Moment, or a Selection. Only with a Selection mayyou add `until-boundary="start" | "end"` to choose which edge of it ends the deck; the default is`end`, and giving the attribute in the other two cases is refused rather than ignored.@@ -452,7 +459,7 @@ empty, each with a required `z` for stacking order and a window that is one of:| A Moment, for a length | `at={story.moment.x} for="12f"` on an item whose Track has `semantic={speech.semantic}` || An explicit span | `start="…" end="…"`, optionally against a `selection=` or `moment=` |-Anything bound to the Script needs `map`; an explicit span with no Script source must not have one.+The Track takes `id`, `canvas` and `semantic`.Lengths are `12f`, `250ms` or `1.5s`, and `occurrences="each"` repeats an effect at every occurrenceof its marker rather than the first.@@ -484,8 +491,7 @@ optional metadata line.card's whole appearance — background, border, radius, tail, avatar, the three text rows, and theenter/hold/exit motion — and every key has a default, so a recipe may set only what it changes.-`comment:Track` takes `id`, `canvas` and `space`. It takes `map` only if one of its stickers binds to-the Script, and giving `map` when none does is refused rather than ignored.+`comment:Track` takes `id`, `canvas` and `semantic`, all three required.`comment:Sticker` requires `id`, `frame` and `style`, and takes the same windows as a screen overlayabove. Its copy is either the `comment=` attribute or the element's own text — both is refused. Thediff --git a/docs/zh/quickstart/composition.md b/docs/zh/quickstart/composition.mdindex f0f4f9b7..db62aa8c 100644--- a/docs/zh/quickstart/composition.md+++ b/docs/zh/quickstart/composition.md@@ -34,7 +34,7 @@ Composition。然后渲染器将该 Composition 编译为 MP4 视频。|---|---|---|| `id` | 是 | 唯一标识符 || `canvas` | 是 | 与 Track 布局共享的显式 CanvasSpace |-| `space` | 是 | 来自 `speech:Track` 的 ProgramSpace——定义时长和帧率 |+| `semantic` | 是 | 来自 `speech:Track` 的 SemanticTrack——定义时长和帧率 || `appearance` | 是 | SVS Film Recipe——画布清除颜色 |### film:Track@@ -86,7 +86,7 @@ Track 是**扁平的**——没有嵌套或分组。Z 轴排序完全由每个 T|---|---|---|| `id` | 是 | 唯一标识符 || `composition` | 是 | 来自 `film:Film` 的 Composition |-| `space` | 是 | 来自 `speech:Track` 的 ProgramSpace |+| `semantic` | 是 | 来自 `speech:Track` 的 SemanticTrack |渲染器:diff --git a/docs/zh/quickstart/preview.md b/docs/zh/quickstart/preview.mdindex 2581e909..7c0c2325 100644--- a/docs/zh/quickstart/preview.md+++ b/docs/zh/quickstart/preview.md@@ -7,15 +7,15 @@ description: 把一个素材已经存在的 Run 当作可编辑的时间线来**Hypit Studio** 打开一个 Run,把它的 Film 或 Render target 回溯到自己能编辑的那些投影,然后画出来——右侧是代码,左上是画面,左下是时间线。除了 Author SVML 之外它不写入任何东西,也从不调用 Provider。-最后这半句值得读两遍。Studio 只构建它能从 Run 已经提供的 Candidate 确定性推导出来的东西,因此**一份仍然声明着未生成镜头的 Source 是打不开的**。Studio 是你检视并调整一个素材已经存在的节目的地方;它不是一个在素材出现之前先看看它的办法。+Studio 只构建它能从 Run 已经提供的 Candidate 确定性推导出来的东西,因此它需要一个素材已被满足的 Run——每一个生成 output 要么由一次已接受的 Build 产出,要么由一个文件顶上。你指向的就是这样一个 Run。```bashpnpm studio -- --run path/to/build.svrun# ➜ http://localhost:5179/```-::: warning 本仓库当前没有任何示例能打开-`examples/` 下的每一个 Run Source,要么处于生成之前——它的镜头仍然需要 Seedance、GPT Image、WhisperX 或字幕规划——要么依赖 `examples/**/assets/` 下的素材,而那些素材并未提交。这两种情况都会被拒绝。请把 Studio 指向你自己的、output 已被满足的 Run。+::: warning 本仓库的示例需要先有素材+`examples/` 下的每一个 Run Source,都还指名着需要 Provider 去做的镜头,或者 `examples/**/assets/` 下未提交的素材。先在你自己的 Run 里满足它们,再打开。:::| 参数 | 含义 |@@ -37,22 +37,22 @@ pkill -f "@hypit/studio" || true确实想并排看两个 Run 时,再用 `--port`。:::-## Studio 会做什么,不会做什么+## Studio 画什么Studio 只构建 Run 的确定性闭包,除此之外什么都不做。打开 Studio 从不调用 Provider,也从不创建 Build,因此它画出的每一个投影,要么由 Run 作为 Candidate 提供,要么可以从这样一个 Candidate 确定性地推导出来。**所有结构性的东西都是真的。** Placement Frame、padding、堆叠顺序、动效以及 Track 布局,都由构建时调用的同一批函数、从你的 Source 和 Recipe 算出。一张卡片如果在画面里的位置不对,在这里同样是不对的。-**时序永远是实测的。** 时间线来自 `SemanticTrack`——也就是已对齐的那些 Take 本身——所以你看到的剪切点就是构建产出的剪切点。这里没有估算模式。+**每一处时序都是实测的。** 时间线来自 `SemanticTrack`——也就是已对齐的那些 Take 本身——所以你看到的剪切点就是构建产出的剪切点。-**没有任何东西会有替身。** Studio 没有占位图片、没有黑场、也不会伪造时序。这是这笔交易里刻意的那一半:与其画出一个自己无法交代的东西再给它贴个标签,Studio 宁可拒绝打开,并说清楚缺的是什么。+当闭包需要的某样东西缺失时,Studio 会说明并停下:```Studio cannot start:- the Studio projection closure requires unresolved capabilities: seedance.video```-你比较可能遇到的几种拒绝:+它要求的是:| 拒绝 | 含义 || --- | --- |@@ -62,7 +62,7 @@ Studio cannot start:| `the Studio projection closure requires unresolved capabilities: …` | 某条 Track 需要 Provider 才能存在。要么在 Run 里满足它,要么接受一次 Build。 || `Render target … is an opaque media Candidate; Studio needs the current Film graph` | Run 指向的是一个已经渲染好的视频文件。Studio 编辑的是图,不是产物。 |-第四条是你最常遇到的,而且它是全有或全无:闭包里任何一个未解决的 capability 都会拒绝整个 Run,而不是让那一条 Track 单独变黑。所以一个节目是在某一步里整个变得可打开的——当它最后一个生成 output 被满足时——而不是逐步变得可打开。+第四条是你最常遇到的,而且它是全有或全无:闭包里任何一个未解决的 capability 都会拒绝整个 Run。一个节目是在某一步里整个变得可打开的——当它最后一个生成 output 被满足时。## 提供你已经有的素材@@ -74,22 +74,15 @@ Studio cannot start:`<build-record>` 候选指名的是早先某次 Build 做出的东西而非一个路径,需要 `--runtime` 才能找到。-## 读懂徽章+## 一条 Track 从哪来-顶部有两个判断;在一个能被打开的 Run 上它们都是 `measured`——能打开本身就意味着如此。它们仍然留在界面里,是因为它们说明了自己代表的是什么:--| 徽章 | 含义 |-| --- | --- |-| `timing: measured` | 读自已对齐的 `SemanticTrack`。 |-| `picture: measured` | 每个元素展示的都是真实素材。 |--选中一条 Track,会说明是哪个 Candidate 产出了它,以及它从哪里来——Run、Source,或者都不是。+选中一条 Track,会说明是哪个 Candidate 产出了它,以及它从哪里来——Run、Source,或者都不是。顶部对整个节目给出同样的判断:`timing: measured` 读自已对齐的 `SemanticTrack`,`picture: measured` 表示每个元素展示的都是真实素材。## 当由 agent 来做这件事时-如果你正在通过 [Hypit skill](https://github.com/hypit-ai/hypit/blob/main/.agents/skills/hypit/SKILL.md)工作,那么当某个步骤改动了 Source——改了 Script、移了 Frame、放了 B-roll、调了 Recipe——只要它所针对的那个 Run 本身能打开,agent 就会为你启动 Studio 并把链接发给你。+如果你正在通过 [Hypit skill](https://github.com/hypit-ai/hypit/blob/main/.agents/skills/hypit/SKILL.md)工作,那么每当某个步骤改动了 Source——改了 Script、移了 Frame、放了 B-roll、调了 Recipe——agent 会为你启动 Studio 并把链接发给你。-读 diff 和亲眼看见空镜落在哪里不是一回事。在一个素材已经存在的 Run 上,此刻正是说出"那张卡片太靠上了"的最便宜的时机;而在一个镜头仍然只是被声明的 Run 上,agent 没有任何东西可以给你看,它会如实说明,而不是发一个链接过来。+读 diff 和亲眼看见空镜落在哪里不是一回事,而此刻正是说出"那张卡片太靠上了"的最便宜的时机。## 在里面移动diff --git a/docs/zh/quickstart/timing.md b/docs/zh/quickstart/timing.mdindex d31781d7..5df0fc5e 100644--- a/docs/zh/quickstart/timing.md+++ b/docs/zh/quickstart/timing.md@@ -11,7 +11,7 @@ Hypit 的时间真相是 `SemanticTrack`。它按 Segment 粒度构建:2. 将归一化媒体与对应的 Script Segment 对齐,得到自包含的 `SemanticTake`;3. 用 `speech:Track` 按节目顺序装配这些 Semantic Take。-系统不再先拼接整段节目、再做一次全局转录。每个 Take 在进入 Track 之前就已经具有语义。+每个 Take 在进入 Track 之前就已经具有语义。```svml<import as="program" from="@hypit/program-space@1"/>@@ -111,9 +111,7 @@ SemanticTrack,并在构建确定性 Track 时把这些身份投影成帧:composition={main.composition} semantic={speech.semantic}/>```-整段使用 `during={story.segment.answer}`,作者范围使用 Selection,点事件使用 Moment,完整节目-使用 `during="program"`。组件统一消费 `semantic={speech.semantic}`,不再同时接收分离的 `map`-和 `space`。+整段使用 `during={story.segment.answer}`,作者范围使用 Selection,点事件使用 Moment,完整节目使用 `during="program"`。组件统一消费 `semantic={speech.semantic}`。```text原始 Take ─► Normalize ─► SynchronizedMedia ─► SemanticTake ─┐diff --git a/docs/zh/quickstart/tracks.md b/docs/zh/quickstart/tracks.mdindex c54c5158..7fc53452 100644--- a/docs/zh/quickstart/tracks.md+++ b/docs/zh/quickstart/tracks.md@@ -181,10 +181,9 @@ Operation。需要共享或特殊选流时仍可显式写 `<pipeline:Normalize>`| 属性 | 必填 | 描述 ||---|---|---|| `Track.id` | 是 | 稳定的 Audio Track 身份 |-| `Track.space` | 是 | 定义精确采样域与帧域的 ProgramSpace |+| `Track.semantic` | 是 | 定义精确采样域与帧域的 SemanticTrack || `Clip.source` | 是 | 显式选流并规范化后的 `SynchronizedMedia` || `during`、`at`/`for` 或 `start`/`end` | 三种形式选一 | 全节目、Selection、Moment 或显式窗口 |-| `map` | Selection/Moment 必填 | 用于解析语义时间的 SemanticMap || `playback` | 否 | `once`、`once-end`、`loop`、`loop-end` 或有界 `stretch` || `occurrences` | 否 | 语义来源有多次出现时选择 `one` 或 `each` || `trim-start`、`trim-end` | 否 | 精确源裁切 |@@ -222,8 +221,7 @@ Track 都会作为独立输入进入 Film。输出 `{music-bed.track}` 是普通| 属性 | 必填 | 描述 ||---|---|---|| `id` | 是 | 唯一标识符 |-| `space` | 是 | 来自 `speech:Track` 的 ProgramSpace |-| `map` | 否 | SemanticMap——当项目使用基于 Selection 的计时时需要 |+| `semantic` | 是 | 来自 `speech:Track` 的 SemanticTrack——也用于解析基于 Selection 的项目计时 |### text:Point、text:Area 与 text:Path@@ -293,13 +291,12 @@ Run 时,继续使用内联 `P`/`Span`/`Break`。| 属性 | 取值 ||---|---|-| `map` | 安放词语的 Semantic Map |-| `space` | Program Space |-| `frame` | 一个 `space:Frame` |+| `semantic` | 板据以计时的 SemanticTrack |+| `frame` | 一个 `space:Frame`——对 `Column` 来说是固定的排名轨 || `during` | 一个 Selection——板在此期间留在画面上 |-| `triggers` | 一个 Moment——行在它上面移动 |-| `terminal` | 一个 Moment——板在它上面定格 || `style` | 对应的样式记录,且只接受本变体的 |+| `triggers`、`terminal` | 两个 Moment——行在前者上移动,板在后者上定格。仅 `TierBoard` 与 `TopThree` |+| `canvas` | 一个 `space:Canvas`——揭示舞台。仅 `Column` || `appear-sound`、`move-sound` | 可选,Synchronized Media |`move-sound` 在 `TopThree` 上会被拒绝——它没有移动阶段。在 `TierBoard` 上它要求至少有一个 `entry="stage"` 的条目:声音没有可响之处是创作错误,而不是静默的空操作。@@ -334,7 +331,7 @@ Run 时,继续使用内联 `P`/`Span`/`Break`。### deck:DepthStack-`id`、`map`、`space`、`canvas`、`frame` 与 `appearance` 全部必填,`until` 同样必填——它说明什么结束这叠卡片:字面量 `"program.end"`、一个 Moment,或一个 Selection。只有在指向 Selection 时才可以再加 `until-boundary="start" | "end"` 来选择用它的哪一端结束,默认是 `end`;在另外两种情况下给出这个属性会被拒绝,而不是被忽略。+`id`、`semantic`、`canvas`、`frame` 与 `appearance` 全部必填,`until` 同样必填——它说明什么结束这叠卡片:字面量 `"program.end"`、一个 Moment,或一个 Selection。只有在指向 Selection 时才可以再加 `until-boundary="start" | "end"` 来选择用它的哪一端结束,默认是 `end`;在另外两种情况下给出这个属性会被拒绝,而不是被忽略。### deck:Card@@ -380,7 +377,7 @@ DepthStack 的直接子元素,自闭合,至少一张,按书写顺序发出| 一个 Moment,持续一段时长 | 在带有 `semantic={speech.semantic}` 的 Track 内写 `at={story.moment.x} for="12f"` || 显式区间 | `start="…" end="…"`,可另外指定 `selection=` 或 `moment=` |-凡是绑定到 Script 的都需要 `map`;不带 Script 来源的显式区间则不能给 `map`。时长写作 `12f`、`250ms` 或 `1.5s`,`occurrences="each"` 让效果在标记的每一次出现处重复,而不只是第一次。+Track 接受 `id`、`canvas` 与 `semantic`。时长写作 `12f`、`250ms` 或 `1.5s`,`occurrences="each"` 让效果在标记的每一次出现处重复,而不只是第一次。可用的效果有十一种——`Flash`、`ColorWash`、`Vignette`、`ScanLines`、`DirectionalMatte`、`WhipVeil`、`GlitchVeil`、`Grain`、`LightLeak`、`Bokeh` 与 `TVStatic`——每种各有自己的必填属性,例如 `Flash` 的 `color` / `intensity` / `attack` / `hold` / `decay`,或 `Vignette` 的 `center-x` / `center-y` / `radius-x` / `radius-y` / `softness` / `color` / `opacity`。它们都没有默认值:一个效果要么把自己的形状说全,要么被拒绝。@@ -403,7 +400,7 @@ DepthStack 的直接子元素,自闭合,至少一张,按书写顺序发出`comment:Style` 必须为空,接受 `id`、`recipe` 与 `font`,全部必填。Recipe 承载整张卡的外观——背景、描边、圆角、气泡尾、头像、三行文字,以及进入/停留/退出的动效——每个键都有默认值,所以一份 recipe 只需写它要改的部分。-`comment:Track` 接受 `id`、`canvas` 与 `space`。只有当它的某张贴纸绑定到 Script 时才接受 `map`;没有任何贴纸绑定却给了 `map` 会被拒绝,而不是被忽略。+`comment:Track` 接受 `id`、`canvas` 与 `semantic`,三者皆为必填。`comment:Sticker` 必填 `id`、`frame` 与 `style`,时间窗与上面的屏幕叠加层相同。它的文案来自 `comment=` 属性或元素自身的文字,两个都给会被拒绝。可选的 `author`、`header` 与 `meta` 各接受字符串或 Text 引用,`avatar` 接受一张图片;这里没有 `z`,层叠顺序来自 recipe 的 `stack-order`。diff --git a/examples/all-components-preview/README.md b/examples/all-components-preview/README.mdindex 6f41c687..0a715ee7 100644--- a/examples/all-components-preview/README.md+++ b/examples/all-components-preview/README.md@@ -8,18 +8,6 @@ It exists to exercise the vocabulary: every Track kind declared once, in oneSource, so a change that breaks one of them breaks something a reader can see.`hypit check` proves it is legal, and the graph-shape tests read it.-**It does not currently open in Studio.** Studio builds only the deterministic-closure of a Run, so a Source in this state — no footage, no recording, no-caption plan — refuses:--```-Studio cannot start:-- the Studio projection closure requires unresolved capabilities:- @hypit/caption-gemini@1#gemini-caption-planning, @hypit/gpt-image@1#gpt-image-2,- @hypit/media-pipeline@1#inspect-media, @hypit/media-pipeline@1#normalize-media,- @hypit/media-pipeline@1#project-speech-evidence-audio,- @hypit/seedance@1#seedance-2-mini, @hypit/whisperx@1#whisperx-alignment-```--Opening it means satisfying those outputs in a Run Source, or accepting a Build-that produced them. See `docs/quickstart/preview.md`.+Opening it in Studio means satisfying its generated outputs first — seven+capabilities, from `gpt-image-2` through `whisperx-alignment` — in a Run Source+or an accepted Build. See `docs/quickstart/preview.md`.diff --git a/examples/talking-film-broll-preview/README.md b/examples/talking-film-broll-preview/README.mdindex 8436b52b..4add06fd 100644--- a/examples/talking-film-broll-preview/README.md+++ b/examples/talking-film-broll-preview/README.md@@ -30,6 +30,5 @@ insets. `card-a` spans `left="8%"` to `right="92%"` — 86.4px to 993.6px of aThe Source is complete, so it builds like any other example once a RuntimeProfile and credentials are in place.-There is no Run Source here, and Studio requires one — so this example cannot be-opened in Studio as it stands. Write a `.svrun` that satisfies its generated-outputs first; see `docs/quickstart/preview.md`.+Studio opens a Run, so seeing this one means writing a `.svrun` that satisfies+its generated outputs; see `docs/quickstart/preview.md`.