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.

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.md
index 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 answers
generation, 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, read
diff --git a/.agents/skills/hypit/references/preview.md b/.agents/skills/hypit/references/preview.md
index 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 unit
Source, and it reads the Author SVML back out of it. Pass `--runtime` only when the Author Source
reuses 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.md
index 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 whether
wired at all. Every failure this check reports must be repaired until the check passes. Repair as
many 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 requires
unresolved 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 fix
Render 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 typeface
that does not match, a colour that is off, a shape that is misplaced — reports no error here, because
diff --git a/.agents/skills/hypit/references/reconstruction/index.md b/.agents/skills/hypit/references/reconstruction/index.md
index 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, alignment
run. Those belong to a later step that the author starts deliberately, after reading what was
written.
-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 its
elements are drawn on, whatever that is — is produced while the package is authored, with
diff --git a/.agents/skills/hypit/references/reconstruction/reconstruction-loop.md b/.agents/skills/hypit/references/reconstruction/reconstruction-loop.md
index 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-ch
without any attempt ceiling. A graph that does not trace is not a difference to weigh; it is work
that 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. This
diff --git a/.agents/skills/hypit/scripts/preview-check.mjs b/.agents/skills/hypit/scripts/preview-check.mjs
index 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 this
diff --git a/docs/quickstart/composition.md b/docs/quickstart/composition.md
index 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.md
index 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 never
writes 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.
```bash
pnpm 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" || true
Use `--port` when you genuinely want two Runs side by side.
:::
-## What Studio will and will not do
+## What Studio draws
Studio builds the deterministic closure of the Run and nothing else. Opening it never invokes a
Provider 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 card
in 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 from
Selecting 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 work
If 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 it
diff --git a/docs/quickstart/timing.md b/docs/quickstart/timing.md
index 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 Moment
for 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}`.
```text
raw take ─► Normalize ─► SynchronizedMedia ─► SemanticTake ─┐
diff --git a/docs/quickstart/tracks.md b/docs/quickstart/tracks.md
index 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 least
one 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 says
what ends the deck: the literal `"program.end"`, a Moment, or a Selection. Only with a Selection may
you 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 occurrence
of 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 the
enter/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 overlay
above. Its copy is either the `comment=` attribute or the element's own text — both is refused. The
diff --git a/docs/zh/quickstart/composition.md b/docs/zh/quickstart/composition.md
index 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.md
index 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。
```bash
pnpm 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.md
index 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.md
index 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.md
index 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 one
Source, 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.md
index 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 a
The Source is complete, so it builds like any other example once a Runtime
Profile 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`.