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: align production guidance with the 0.3 model

kashorin91fd9328f5bc
diff --git a/docs/guide/studio-companion-architecture.md b/docs/guide/studio-companion-architecture.md
index 7c0d3a89..3af6a64f 100644
--- a/docs/guide/studio-companion-architecture.md
+++ b/docs/guide/studio-companion-architecture.md
@@ -29,7 +29,7 @@ internal drawing value.
Studio supplies the controls and interactions. A Companion selects scalar, list or record controls
and binds them to source values. A Film Companion identifies the Film's time source and Tracks;
a Script Companion supports the source mapping needed to relocate Selection and Moment markers.
-The same Timeline supports animation with no Takes or Script lane; its authored end defines the extent.
+The same Timeline supports animation with no performance media or Script lane; its authored end defines the extent.
## Make edits meaningful
diff --git a/docs/guide/studio-temporal-windows.md b/docs/guide/studio-temporal-windows.md
index e8ea8b00..61cf8ad2 100644
--- a/docs/guide/studio-temporal-windows.md
+++ b/docs/guide/studio-temporal-windows.md
@@ -14,11 +14,12 @@ the source domain.
| `from="2s" for="8f"` | `from`; duration remains eight frames | `from` or `for` |
| `until="3s" for="8f"` | `until`; duration remains eight frames | `for` or `until` |
| `from="1s" until="3s"` | both endpoints by the same delta | the selected endpoint |
-| `during="timeline"` | no local write | no local write |
-| `during={named-window}` | the named value's producer | the named value's producer |
+| named Window declared with `from`/`until`/`for` | the named declaration | the selected relation |
+| component `during={named-window}` | the named value's producer | the named value's producer |
-An Instant reference behaves the same way: `at={claim}` follows the declaration that produced
-`claim`; `at="2s"` edits its own clock literal.
+An Instant reference behaves the same way: component `at={claim}` follows the declaration that
+produced `claim`. Clock literals belong on named Timeline or standalone declarations, not on the
+component surface.
## Domain-produced values
diff --git a/docs/quickstart/composition.md b/docs/quickstart/composition.md
index 807e0819..80d2ad56 100644
--- a/docs/quickstart/composition.md
+++ b/docs/quickstart/composition.md
@@ -110,12 +110,15 @@ Timeline does not require speech or media:
<import as="time" from="@hypit/timeline-author@1"/>
<time:Clock id="animation-clock" frame-rate="30"/>
-<time:Timeline id="animation" clock={animation-clock} end="8s"/>
+<time:Timeline id="animation" clock={animation-clock} end="8s">
+ <time:Instant id="question" at="0.5s"/>
+ <time:Instant id="answer" at="2s"/>
+</time:Timeline>
<chat:Scene id="conversation" timeline={animation.timeline} within={canvas.bounds}
- during="timeline">
- <chat:Message id="question" at="0.5s" sender="Maya" text="Ready?"/>
- <chat:Message id="answer" at="2s" sender="Leo" text="Let's go."/>
+ during={animation.window}>
+ <chat:Message id="question" at={animation.question} sender="Maya" text="Ready?"/>
+ <chat:Message id="answer" at={animation.answer} sender="Leo" text="Let's go."/>
</chat:Scene>
<film:Film id="main" canvas={canvas.canvas} timeline={animation.timeline}
diff --git a/docs/quickstart/preview.md b/docs/quickstart/preview.md
index a0dbba01..ff734faf 100644
--- a/docs/quickstart/preview.md
+++ b/docs/quickstart/preview.md
@@ -30,9 +30,10 @@ It changes the interface, while your Script, video captions and comments keep th
| `--project <directory>` | Set the project boundary for Source access and edits. |
| `--port <number>` | Request a browser-server port; the default is `5179`. |
-The selected target must lead to one Film and its Timeline. Placed Takes add their semantic anchors;
-an animation can use a Timeline with an explicit end and no Takes. Both support visual components and
-property editing. The material needed to display the composition must already be available through
+The selected target must lead to one Film and its Timeline. Prepared media can establish Timeline
+extent, and optional semantic projection can add Script anchors when the composition uses them. An
+animation can use a Timeline with an explicit end and no performance media. Both support visual
+components and property editing. The material needed to display the composition must already be available through
the Run. Studio can perform media preparation supported by the selected Runtime; submit generation
and encoded renders through `hypit build`.
diff --git a/docs/quickstart/run.md b/docs/quickstart/run.md
index b887679f..00db2792 100644
--- a/docs/quickstart/run.md
+++ b/docs/quickstart/run.md
@@ -199,7 +199,7 @@ The Planner reads the complete Author Graph and Run Graph together. It prunes de
that selected Candidates replace while retaining any Author Outputs the selected Candidate itself
still consumes. This is a
new Build, not a continuation of the old one. Reusing generated video leaves normalization and
-alignment downstream. Reusing normalized media, its local domain and NarrativeAlignment retains those
+any required alignment downstream. Reusing normalized media, its local domain and NarrativeAlignment retains those
facts independently without freezing Timeline placement or presentation. Caption, MG and rendering
recompute where they remain on the selected route. Choose the Outputs whose meanings match what should
stay unchanged.
diff --git a/docs/quickstart/styles.md b/docs/quickstart/styles.md
index 789c2b23..db742721 100644
--- a/docs/quickstart/styles.md
+++ b/docs/quickstart/styles.md
@@ -230,7 +230,7 @@ Compiled with exact font bytes into a `text:Style`, then referenced by a concret
<fonts:Face id="title-font" package="@fontsource-variable/inter" weight="900" style="normal"/>
<text:Style id="title-style" recipe={recipes.text.title} font={title-font}/>
<text:Flow id="meaning" timeline={speech.timeline} within={title-frame}
- style={title-style} z="90" align="center" during="timeline">
+ style={title-style} z="90" align="center" during={speech.window}>
MEANING
</text:Flow>
```
diff --git a/docs/quickstart/timing.md b/docs/quickstart/timing.md
index cb4d8ea6..c6583eca 100644
--- a/docs/quickstart/timing.md
+++ b/docs/quickstart/timing.md
@@ -6,12 +6,12 @@ description: Construct absolute program time, then present media and project opt
Hypit has one program-time axis: `Timeline`. It is only `{ id, frameRate, frameCount }`.
It contains no clips, words, Tracks or central event registry.
-For spoken work, four independent facts meet around that axis:
+For spoken work, independent facts meet around that axis:
1. Normalize accepted media into `SynchronizedMedia` plus a finite local temporal domain.
-2. Align a Script Segment on that local domain, producing `NarrativeAlignment`.
-3. Construct Timeline from a DAG of named Instants, Windows and Extents with one required `end`.
-4. Project each Alignment through its equal-length Window; present ordinary media through independent Visual and Audio sources.
+2. Construct Timeline from a DAG of named Instants, Windows and Extents with one required `end`.
+3. When a consumer needs positions inside performed speech, align its Script Segment on the local domain.
+4. Project requested semantic values through the equal-length Window; present ordinary media through independent Visual and Audio sources.
This separation is useful: moving a passage changes absolute relationships without changing its media or local
word evidence; reframing picture does not change audio; a pure animation needs Timeline but no media
@@ -41,7 +41,11 @@ The Clock fixes the frame rate shared by the final Timeline and every local doma
Normalization establishes media facts. It contains no Script meaning or program placement.
-## Align meaning on each local domain
+## Align meaning when the composition consumes it
+
+Timeline construction needs the media Extent, not semantic alignment. Add Alignment when Caption,
+semantic picture changes, sound events or another consumer needs Script positions inside the
+accepted performance:
```svml
<whisperx:Alignment id="opening-alignment" narrative={story}
@@ -110,8 +114,7 @@ optional projection source; direct seconds, frames and named Timeline values rem
</audio:Track>
```
-There is no separate Performance, Sound or generic Presentation protocol. Visual and Audio Clips are
-peer occurrences. The same normalized media can feed both, but selecting its picture never makes its audio
+Visual and Audio Clips are peer occurrences. The same normalized media can feed both, but selecting its picture never makes its audio
audible automatically.
```text
diff --git a/docs/quickstart/tracks.md b/docs/quickstart/tracks.md
index 2d188385..d32a494a 100644
--- a/docs/quickstart/tracks.md
+++ b/docs/quickstart/tracks.md
@@ -14,7 +14,8 @@ Caption uses a source-neutral document produced by Script and a replaceable Styl
```text
Script → CaptionDocument + NarrativeCaptionBinding
-Binding + NarrativeProjection → CaptionTiming → Use presentation
+Binding + NarrativeProjection → complete Unit CaptionTiming
+CaptionDocument + CaptionTiming + Uses → family Cue schedule → VisualTrack
```
```svml
@@ -25,8 +26,8 @@ Binding + NarrativeProjection → CaptionTiming → Use presentation
```
`@hypit/caption` owns the common CaptionDocument contract, complete-unit Selection/Role projection,
-Style assignment and the timing join. `@hypit/caption-fine` is one Style family: it owns geometry,
-glyph/Cue/Pill Paint and layered local motion.
+Style assignment and the flat timing join. `@hypit/caption-fine` is one Style family: it forms Cues
+and owns their geometry, glyph/Cue/Pill Paint and layered local motion.
### caption-fine:Style
@@ -240,7 +241,7 @@ then choose its exact program Window and source-time relation:
video="none" audio="default" span-authority="audio" clock={clock}/>
<audio:Track id="music-bed" timeline={speech.timeline}>
- <audio:Clip source={music-media.media} during="timeline"
+ <audio:Clip source={music-media.media} during={speech.window}
gain="0.28" fade-in="600ms" fade-out="800ms">
<audio:Map target-at="end" source-at="end" rate="1"
wrap-from="start" wrap-until="end"/>
@@ -253,7 +254,7 @@ then choose its exact program Window and source-time relation:
| `Track.id` | yes | Stable Audio Track identity |
| `Track.timeline` | yes | Timeline 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 |
+| `during` | yes | A named absolute Window |
| `source-time` or `Map` children | no | Reusable or inline partial target-to-source relation; omission is bounded partial identity |
| `gain`, `fade-in`, `fade-out` | no | Explicit per-Clip mix values |
@@ -282,7 +283,7 @@ piece of editorial copy is one occurrence and one ordinary VisualTrack contribut
<fonts:Face id="title-font" package="@fontsource-variable/inter" weight="900" style="normal"/>
<text:Style id="title-style" recipe={recipes.text.title} font={title-font}/>
<text:Flow id="title" timeline={speech.timeline} within={title-frame}
- style={title-style} z="90" align="center" during="timeline">
+ style={title-style} z="90" align="center" during={speech.window}>
EDIT MEANING, NOT TIMELINES
</text:Flow>
```
@@ -291,7 +292,7 @@ piece of editorial copy is one occurrence and one ordinary VisualTrack contribut
|---|---|---|
| `id` | yes | Unique identifier |
| `timeline` | yes | Absolute Timeline that owns the occurrence window |
-| `during`, `at`/`for`, or `start`/`end` | exactly one form | An absolute Window, Instant plus duration, or authored boundaries |
+| `during` | yes | A named absolute Window |
| `within`, `point`, or `path` | yes | Placement matching `Flow`, `Point`, or `Path` |
| `style` | yes | Style compiled from an SVS Recipe plus exact font bytes |
| `z` | yes | Absolute stacking for this occurrence; it is not part of Style |
@@ -302,7 +303,7 @@ Each occurrence has one explicit placement form, one exact Style and one absolut
```svml
<text:Flow id="meaning" timeline={speech.timeline} within={title-frame}
- style={title-style} z="90" align="center" during="timeline">
+ style={title-style} z="90" align="center" during={speech.window}>
MEANING
</text:Flow>
```
@@ -311,14 +312,14 @@ Each occurrence has one explicit placement form, one exact Style and one absolut
|---|---|---|
| `id` | yes | Stable item identity |
| child content or `content` | yes | Inline plain/rich content, or an ordinary graph `Text` reference; the two forms are exclusive |
-| timing | yes | `during="timeline"`, an absolute Window, or `at`/`for`, `until`/`for`, `start`/`end` |
+| timing | yes | `during={named-window}` |
| placement | yes | `SpatialPoint`, `SpatialFrame` or `SpatialPath`, matching the occurrence form |
| `style` | yes | A `text:Style` compiled from an SVS Recipe plus exact font bytes |
| `z` | yes | Absolute stacking for this occurrence |
| form layout | no | Direct layout attributes declared by the selected `Flow`, `Point` or `Path` form |
-`during="timeline"` covers the complete Timeline. An authored Timeline Window or an upstream semantic,
-beat or other projection can instead supply an ordinary absolute Window. The fine-text component
+`speech.window` covers the complete Timeline. An authored Timeline Window or an upstream semantic,
+beat or other projection can supply any other ordinary absolute Window. The fine-text component
does not know which domain produced it:
```svml
@@ -334,7 +335,7 @@ Graph-produced copy remains visible as an edge:
```svml
<wording:Value id="headline">EXACTLY THE RIGHT MOMENT</wording:Value>
<text:Flow id="callout-copy" timeline={speech.timeline} content={headline}
- within={callout-frame} style={callout-style} z="90" during="timeline"/>
+ within={callout-frame} style={callout-style} z="90" during={speech.window}/>
```
The generic Text value supplies only characters. Typography still owns the item document wrapper,
@@ -535,7 +536,7 @@ All four track families together in one source file:
<!-- Text: persistent title overlay -->
<text:Style id="title-style" recipe={recipes.text.title} font={title-font}/>
<text:Flow id="meaning" timeline={speech.timeline} within={title-frame}
- style={title-style} z="90" align="center" during="timeline">
+ style={title-style} z="90" align="center" during={speech.window}>
MEANING
</text:Flow>
@@ -544,7 +545,7 @@ All four track families together in one source file:
<mediaop:Normalize id="music-media" source={music}
video="none" audio="default" span-authority="audio" clock={clock}/>
<audio:Track id="music-bed" timeline={speech.timeline}>
- <audio:Clip source={music-media.media} during="timeline"
+ <audio:Clip source={music-media.media} during={speech.window}
gain="0.28" fade-in="600ms" fade-out="800ms">
<audio:Map target-at="end" source-at="end" rate="1"
wrap-from="start" wrap-until="end"/>
diff --git a/docs/zh/guide/author-packages.md b/docs/zh/guide/author-packages.md
index b0662d6a..96d77784 100644
--- a/docs/zh/guide/author-packages.md
+++ b/docs/zh/guide/author-packages.md
@@ -22,7 +22,7 @@ npm run build
公开另一个视频作者真正会改的决定:内容、素材、位置、外观和有意义的事件。转场可以接收一个 Moment,决定何时改变布局;接收一个 Selection,决定整个场景何时存在。纯动画则可以接收作者指定的事件时间。将这些输入投影到选定时钟,再按得到的调度绘制场景。
-呈现已有说话表演时,消费它的 Timeline,让画面采样与口播使用相同的 Take 和素材位置。其他视频输入以归一化媒体进入时间线。[响应式讲解场景](https://github.com/hypit-ai/hypit/tree/main/examples/semantic-composition/packages/responsive-explainer) 展示持续播放的视频如何在 HTML 场景里从全屏移到侧边竖屏。[聊天示例](https://github.com/hypit-ai/hypit/tree/main/examples/semantic-composition/packages/chat-scene) 展示同一个事件接口如何接受作者时间或 Script Moment。
+呈现已有说话表演时,消费它的 Timeline,让画面采样与口播使用相同的规范化媒体和素材位置。其他视频输入同样以规范化媒体进入时间线。[响应式讲解场景](https://github.com/hypit-ai/hypit/tree/main/examples/semantic-composition/packages/responsive-explainer) 展示持续播放的视频如何在 HTML 场景里从全屏移到侧边竖屏。[聊天示例](https://github.com/hypit-ai/hypit/tree/main/examples/semantic-composition/packages/chat-scene) 展示同一个事件接口如何接受作者时间或 Script Moment。
Style 一类 Surface 在裸作者 id 下公开其值,例如 `style={board-style}`;独立输出可以使用 `.visual`、`.audio`、`.track` 等有意义的后缀。在组件自己的 vocabulary 和 README 中说明名称与可用值。
diff --git a/docs/zh/guide/studio-companion-architecture.md b/docs/zh/guide/studio-companion-architecture.md
index ee24e8e0..8eda359d 100644
--- a/docs/zh/guide/studio-companion-architecture.md
+++ b/docs/zh/guide/studio-companion-architecture.md
@@ -15,7 +15,7 @@ Companion 是应用贡献。项目组件可以在同一个物理包中,以独
Track Companion 匹配组件的终端 Type 与作者 Surface,使用组件公开值描述时间线实体、标签、素材预览和 Inspector 字段。图形可以公开外观、内容、位置和事件时间,而不必暴露每一个内部绘制数值。
-控件与交互由 Studio 提供,Companion 选择标量、列表或记录控件,并将其绑定到 Source 值。Film Companion 指明 Film 的 Timeline 与 Track;Script Companion 支持移动 Selection、Moment 标记所需的源码映射。同一种 Timeline 也支持没有 Take 和 Script 行的动画,其作者声明的结束时间定义完整范围。
+控件与交互由 Studio 提供,Companion 选择标量、列表或记录控件,并将其绑定到 Source 值。Film Companion 指明 Film 的 Timeline 与 Track;Script Companion 支持移动 Selection、Moment 标记所需的源码映射。同一种 Timeline 也支持没有表演媒体和 Script 行的动画,其作者声明的结束时间定义完整范围。
## 让编辑保留含义
diff --git a/docs/zh/guide/studio-temporal-windows.md b/docs/zh/guide/studio-temporal-windows.md
index ce379d55..488932f9 100644
--- a/docs/zh/guide/studio-temporal-windows.md
+++ b/docs/zh/guide/studio-temporal-windows.md
@@ -13,10 +13,11 @@ description: 修改产生绝对 Instant 或 Window 的声明。
| `from="2s" for="8f"` | 改 `from`,时长仍为八帧 | `from` 或 `for` |
| `until="3s" for="8f"` | 改 `until`,时长仍为八帧 | `for` 或 `until` |
| `from="1s" until="3s"` | 两个端点移动相同帧数 | 被选择的端点 |
-| `during="timeline"` | 不提供局部写回 | 不提供局部写回 |
-| `during={named-window}` | 修改具名值的生产者 | 修改具名值的生产者 |
+| 使用 `from`/`until`/`for` 声明的具名 Window | 修改该具名声明 | 修改所选端点关系 |
+| 组件 `during={named-window}` | 修改具名值的生产者 | 修改具名值的生产者 |
-Instant 引用遵循同样规则:`at={claim}` 跟随产生 `claim` 的声明;`at="2s"` 修改自己的时钟值。
+Instant 引用遵循同样规则:组件的 `at={claim}` 跟随产生 `claim` 的声明。时钟字面量写在
+Timeline 子声明或独立具名声明上,不写在组件表面。
## 领域产生的时间值
diff --git a/docs/zh/quickstart/composition.md b/docs/zh/quickstart/composition.md
index 7c17174f..75c9acf6 100644
--- a/docs/zh/quickstart/composition.md
+++ b/docs/zh/quickstart/composition.md
@@ -105,12 +105,15 @@ Timeline 不要求语音或媒体:
<import as="time" from="@hypit/timeline-author@1"/>
<time:Clock id="animation-clock" frame-rate="30"/>
-<time:Timeline id="animation" clock={animation-clock} end="8s"/>
+<time:Timeline id="animation" clock={animation-clock} end="8s">
+ <time:Instant id="question" at="0.5s"/>
+ <time:Instant id="answer" at="2s"/>
+</time:Timeline>
<chat:Scene id="conversation" timeline={animation.timeline} within={canvas.bounds}
- during="timeline">
- <chat:Message id="question" at="0.5s" sender="Maya" text="Ready?"/>
- <chat:Message id="answer" at="2s" sender="Leo" text="Let's go."/>
+ during={animation.window}>
+ <chat:Message id="question" at={animation.question} sender="Maya" text="Ready?"/>
+ <chat:Message id="answer" at={animation.answer} sender="Leo" text="Let's go."/>
</chat:Scene>
<film:Film id="main" canvas={canvas.canvas} timeline={animation.timeline}
diff --git a/docs/zh/quickstart/generation.md b/docs/zh/quickstart/generation.md
index ef752ef7..6eb60276 100644
--- a/docs/zh/quickstart/generation.md
+++ b/docs/zh/quickstart/generation.md
@@ -106,7 +106,7 @@ Seedance 2.5 复用同样的 Surface,而不是由 Runtime 把别的模型偷
<seedance:TextVideo id="ambient" model="mini"
prompt={ambient-direction} duration="5" web-search="false"/>
```
-对于反复出现的人物、产品或场景,先制作参考图能给视频模型明确的视觉方向。多个 Take 可以复用这些参考,再由 Script 与 action Prompt 指导各段表演。当场景可以直接描述、不需要保持特定视觉身份时,也可以使用 TextVideo。
+对于反复出现的人物、产品或场景,先制作参考图能给视频模型明确的视觉方向。多个生成片段可以复用这些参考,再由 Script 与 action Prompt 指导各段表演。当场景可以直接描述、不需要保持特定视觉身份时,也可以使用 TextVideo。
### seedance:FrameVideo
@@ -313,5 +313,5 @@ dialogue/action 由普通 Text 模块组装,结果再像其他生成任务一
</seedance:ReferenceVideo>
```
-每个 `seedance:ReferenceVideo` 产出 `{*.video}`,进入下一阶段的 `time:Timeline`。不同 Take
+每个 `seedance:ReferenceVideo` 产出 `{*.video}`,进入下一阶段的 `time:Timeline`。不同生成片段
可以使用不同参考图,同时共享相同的音色与 Prompt Recipe。
diff --git a/docs/zh/quickstart/preview.md b/docs/zh/quickstart/preview.md
index 4c432bc2..42b52fd3 100644
--- a/docs/zh/quickstart/preview.md
+++ b/docs/zh/quickstart/preview.md
@@ -23,7 +23,7 @@ hypit studio --run build.svrun
| `--project <directory>` | 设置 Source 访问与修改的项目边界。 |
| `--port <number>` | 指定浏览器服务端口,默认请求 `5179`。 |
-所选目标需要指向一个 Film 及其 Timeline。放入的 Take 带来对应的语义锚点;纯动画也使用 Timeline,声明结束时间、不放入 Take 即可。两者都支持视觉组件与属性编辑。显示编排所需的素材应已通过 Run 提供。Studio 可以完成所选 Runtime 支持的媒体准备;生成和编码渲染通过 `hypit build` 提交。
+所选目标需要指向一个 Film 及其 Timeline。规范化媒体可以提供 Timeline Extent;当作品消费语义位置时,可选投影再发布对应的 Script 锚点。纯动画同样使用 Timeline,只需声明结束时间,不需要表演媒体。两者都支持视觉组件与属性编辑。显示编排所需的素材应已通过 Run 提供。Studio 可以完成所选 Runtime 支持的媒体准备;生成和编码渲染通过 `hypit build` 提交。
## 在 Comments 一起看作品
diff --git a/docs/zh/quickstart/run.md b/docs/zh/quickstart/run.md
index 8dfff11b..55cf05e1 100644
--- a/docs/zh/quickstart/run.md
+++ b/docs/zh/quickstart/run.md
@@ -100,7 +100,7 @@ Target 表达这次 Build 的最终意图,通常是成片或另一个真正的
Hypit 没有隐式缓存。复用结果是显式的运行图编写:把某个旧 Build Result 里的一个具名 Output 声明为零输入 Candidate,再通过 Satisfaction 边连接到当前输出。
-生成图片或 Take 一完成,就能在下一份 `.svrun` 中用 `build-record` 与 `satisfy` 显式复用,并在启动付费下游工作前检查 plan。
+生成图片或视频一完成,就能在下一份 `.svrun` 中用 `build-record` 与 `satisfy` 显式复用,并在启动付费下游工作前检查 plan。
```svml
<?svml using="@hypit/markup/run@1"?>
@@ -170,7 +170,7 @@ Hypit 永远不会猜测两个名字代表同一份作者意图。每次执行 `
| `output` | 要满足的逻辑输出 |
| `candidate` | 由 `build-record`、`file`、`value` 或 Fragment 导出声明的 Candidate 标识符 |
-Planner 会同时读取完整 Author Graph 与 Run Graph:裁剪所选 Candidate 替代掉的默认 Operation,同时保留该 Candidate 自身仍然消费的 Author Output。这是一次新的 Build,而非旧 Build 的延续。复用生成视频时,归一化和对齐仍在下游;分别复用规范化媒体、局部时间域和 NarrativeAlignment 时,会保留这些事实,但不会冻结之后的 Timeline 放置或呈现。字幕、MG 和渲染只在仍被所选路线需要时计算。选择哪些 Output,取决于哪些内容应该保留不变。
+Planner 会同时读取完整 Author Graph 与 Run Graph:裁剪所选 Candidate 替代掉的默认 Operation,同时保留该 Candidate 自身仍然消费的 Author Output。这是一次新的 Build,而非旧 Build 的延续。复用生成视频时,归一化以及作品确实需要的对齐仍在下游;分别复用规范化媒体、局部时间域和 NarrativeAlignment 时,会保留这些事实,但不会冻结之后的 Timeline 放置或呈现。字幕、MG 和渲染只在仍被所选路线需要时计算。选择哪些 Output,取决于哪些内容应该保留不变。
Core 不再给 Candidate 标注 `exact` 或 `substitute`。选择 Candidate 本身就是这次运行的明确实现决定。系统校验类型兼容性,但不猜测创作等价性,也不把这种判断作为冗余元信息沿整条图传播。
diff --git a/docs/zh/quickstart/styles.md b/docs/zh/quickstart/styles.md
index 8691db94..9d810c93 100644
--- a/docs/zh/quickstart/styles.md
+++ b/docs/zh/quickstart/styles.md
@@ -223,7 +223,7 @@ text.title {
<fonts:Face id="title-font" package="@fontsource-variable/inter" weight="900" style="normal"/>
<text:Style id="title-style" recipe={recipes.text.title} font={title-font}/>
<text:Flow id="meaning" timeline={speech.timeline} within={title-frame}
- style={title-style} z="90" align="center" during="timeline">
+ style={title-style} z="90" align="center" during={speech.window}>
MEANING
</text:Flow>
```
diff --git a/docs/zh/quickstart/timing.md b/docs/zh/quickstart/timing.md
index 4b665ed0..d14af355 100644
--- a/docs/zh/quickstart/timing.md
+++ b/docs/zh/quickstart/timing.md
@@ -6,12 +6,12 @@ description: 先构造绝对节目时间,再显式放置媒体并按需投影
Hypit 只有一条节目时间轴:`Timeline`。它只是 `{ id, frameRate, frameCount }`,不包含素材、
单词、Track 或中央事件注册表。
-对于语音作品,四类独立事实围绕这条绝对时间轴组合:
+对于语音作品,几类独立事实围绕这条绝对时间轴组合:
1. 把已接受素材规范化为 `SynchronizedMedia` 与有限的局部时间域;
-2. 在该局部时间域上对齐 Script Segment,得到 `NarrativeAlignment`;
-3. 用具名 Instant、Window 与 Extent 构造一个包含必需 `end` 的 Timeline DAG;
-4. 把每个 Alignment 通过等长 Window 投影,并让普通媒体独立进入 Visual 与 Audio Source。
+2. 用具名 Instant、Window 与 Extent 构造一个包含必需 `end` 的 Timeline DAG;
+3. 当消费者需要表演内部的语义位置时,在局部时间域上对齐对应 Script Segment;
+4. 把所需语义值通过等长 Window 投影,并让普通媒体独立进入 Visual 与 Audio Source。
这种分离很重要:移动一段内容不改变媒体和局部词时序;改变画面构图不改变声音;纯动效
只需要 Timeline,不需要媒体或 Script。
@@ -40,7 +40,10 @@ Clock 固定最终 Timeline 与所有局部时间域共享的帧率:
规范化只建立媒体事实,不包含 Script 含义或节目中的位置。
-## 在局部时间域上对齐语义
+## 在作品消费语义位置时进行对齐
+
+Timeline 构造只需要媒体 Extent,不要求语义对齐。只有 Caption、语义画面变化、声音事件或其他消费者
+需要已接受表演内部的 Script 位置时,才增加 Alignment:
```svml
<whisperx:Alignment id="opening-alignment" narrative={story}
@@ -107,8 +110,7 @@ Timeline 声明是无环构造图。`end` 必填;每个具名 Instant 或 Wind
</audio:Track>
```
-不再存在独立的 Performance、Sound 或通用 Presentation 协议。Visual 与 Audio Clip 是
-平等的媒体出现关系。同一份规范化媒体可以同时供两边使用,但选择画面绝不会自动让声音
+Visual 与 Audio Clip 是平等的媒体出现关系。同一份规范化媒体可以同时供两边使用,但选择画面绝不会自动让声音
进入成片。
```text
diff --git a/docs/zh/quickstart/tracks.md b/docs/zh/quickstart/tracks.md
index 43aae7cf..553a2cd3 100644
--- a/docs/zh/quickstart/tracks.md
+++ b/docs/zh/quickstart/tracks.md
@@ -14,7 +14,8 @@ Track 的作者语法。
```text
Script → CaptionDocument + NarrativeCaptionBinding
-绑定 + NarrativeProjection → CaptionTiming → Use 呈现
+绑定 + NarrativeProjection → 完整 Unit CaptionTiming
+CaptionDocument + CaptionTiming + Uses → 家族 Cue Schedule → VisualTrack
```
```svml
@@ -24,8 +25,8 @@ Script → CaptionDocument + NarrativeCaptionBinding
<import as="fonts" from="@hypit/fontsource@1"/>
```
-公共 Caption 负责 CaptionDocument、完整 Alignment Unit 的 Selection/Role 投影、样式分配与
-Timeline 时间拼接。Fine 是一种样式族,负责自己的几何、字形/Cue/Pill Paint 与局部动画。
+公共 Caption 负责 CaptionDocument、完整 Alignment Unit 的 Selection/Role 投影、样式分配与扁平
+Timeline 时间连接。Fine 是一种样式族,负责形成 Cue,并拥有自己的几何、字形/Cue/Pill Paint 与局部动画。
### caption-fine:Style
@@ -184,7 +185,7 @@ Clip 模型也能表达全屏切换、分屏和角落小窗。公开 Clip 只有
video="none" audio="default" span-authority="audio" clock={clock}/>
<audio:Track id="music-bed" timeline={speech.timeline}>
- <audio:Clip source={music-media.media} during="timeline"
+ <audio:Clip source={music-media.media} during={speech.window}
gain="0.28" fade-in="600ms" fade-out="800ms">
<audio:Map target-at="end" source-at="end" rate="1"
wrap-from="start" wrap-until="end"/>
@@ -225,7 +226,7 @@ Track 都会作为独立输入进入 Film。输出 `{music-bed.audio}` 是普通
<fonts:Face id="title-font" package="@fontsource-variable/inter" weight="900" style="normal"/>
<text:Style id="title-style" recipe={recipes.text.title} font={title-font}/>
<text:Flow id="title" timeline={speech.timeline} within={title-frame}
- style={title-style} z="90" align="center" during="timeline">
+ style={title-style} z="90" align="center" during={speech.window}>
EDIT MEANING, NOT TIMELINES
</text:Flow>
```
@@ -234,7 +235,7 @@ Track 都会作为独立输入进入 Film。输出 `{music-bed.audio}` 是普通
|---|---|---|
| `id` | 是 | 唯一标识符 |
| `timeline` | 是 | 拥有 occurrence 窗口的绝对 Timeline |
-| `during`、`at`/`for` 或 `start`/`end` | 三选一 | 绝对 Window、Instant 加时长,或作者声明的边界 |
+| `during` | 是 | 一个具名绝对 Window |
| `within`、`point` 或 `path` | 是 | 与 `Flow`、`Point` 或 `Path` 对应的位置 |
| `style` | 是 | 由 SVS Recipe 与精确字体字节编译出的 Style |
| `z` | 是 | 这个 occurrence 的绝对层叠顺序;它不属于 Style |
@@ -245,7 +246,7 @@ Track 都会作为独立输入进入 Film。输出 `{music-bed.audio}` 是普通
```svml
<text:Flow id="meaning" timeline={speech.timeline} within={title-frame}
- style={title-style} z="90" align="center" during="timeline">
+ style={title-style} z="90" align="center" during={speech.window}>
MEANING
</text:Flow>
```
@@ -254,13 +255,13 @@ Track 都会作为独立输入进入 Film。输出 `{music-bed.audio}` 是普通
|---|---|---|
| `id` | 是 | 稳定的文字 occurrence 身份 |
| 子内容或 `content` | 是 | 内联纯文本/富文本,或普通图 `Text` 引用;两种形式互斥 |
-| 时间 | 是 | `during="timeline"`、绝对 Window,或 `at`/`for`、`until`/`for`、`start`/`end` |
+| 时间 | 是 | `during={具名 Window}` |
| 位置 | 是 | 与 occurrence 形式匹配的 `SpatialPoint`、`SpatialFrame` 或 `SpatialPath` |
| `style` | 是 | 由 SVS Recipe 与精确字体字节共同编译出的 `text:Style` |
| `z` | 是 | 这个 occurrence 的绝对层叠顺序 |
| 形式布局 | 否 | 所选 `Flow`、`Point` 或 `Path` 直接声明的布局属性 |
-`during="timeline"` 表示完整 Timeline。作者声明的 Timeline Window,或者上游语义、节拍等
+`speech.window` 表示完整 Timeline。作者声明的 Timeline Window,或者上游语义、节拍等
领域的投影,也可以提供普通的绝对 Window;细粒度文字组件不认识这个 Window 来自哪个领域:
```svml
@@ -276,7 +277,7 @@ Track 都会作为独立输入进入 Film。输出 `{music-bed.audio}` 是普通
```svml
<wording:Value id="headline">EXACTLY THE RIGHT MOMENT</wording:Value>
<text:Flow id="callout-copy" timeline={speech.timeline} content={headline}
- within={callout-frame} style={callout-style} z="90" during="timeline"/>
+ within={callout-frame} style={callout-style} z="90" during={speech.window}/>
```
通用 `Text` 只提供字符;Typography 仍然拥有文档包装、位置、时间、样式与动画。作者需要富文本
@@ -455,7 +456,7 @@ DepthStack 的直接子元素,自闭合,至少一张,按书写顺序发出
<!-- Text: persistent title overlay -->
<text:Style id="title-style" recipe={recipes.text.title} font={title-font}/>
<text:Flow id="meaning" timeline={speech.timeline} within={title-frame}
- style={title-style} z="90" align="center" during="timeline">
+ style={title-style} z="90" align="center" during={speech.window}>
MEANING
</text:Flow>
@@ -464,7 +465,7 @@ DepthStack 的直接子元素,自闭合,至少一张,按书写顺序发出
<mediaop:Normalize id="music-media" source={music}
video="none" audio="default" span-authority="audio" clock={clock}/>
<audio:Track id="music-bed" timeline={speech.timeline}>
- <audio:Clip source={music-media.media} during="timeline"
+ <audio:Clip source={music-media.media} during={speech.window}
gain="0.28" fade-in="600ms" fade-out="800ms">
<audio:Map target-at="end" source-at="end" rate="1"
wrap-from="start" wrap-until="end"/>
diff --git a/examples/README.md b/examples/README.md
index 94f3305d..aa427e1c 100644
--- a/examples/README.md
+++ b/examples/README.md
@@ -6,16 +6,17 @@ Adapt those relationships to a new work; its scene list and styling are choices
| Example | What to learn | Starting material |
| --- | --- | --- |
-| [Football ranking](ranking-football/README.md) | Independent speaking Takes, a persistent tier board and timed reveals | Generate from `reference.svrun` |
+| [Football ranking](ranking-football/README.md) | Independent speaking clips, a persistent tier board and timed reveals | Generate from `reference.svrun` |
| [Podcast](podcast/README.md) | Related host views, product references, motivated cuts and a lifestyle montage | Generate from `reference.svrun` |
| [Street interview](interview/README.md) | A shared encounter, derived close views, coordinated Moments and Caption tracking | Generate from `reference.svrun` |
-| [Complex spoken explainer](complex-explainer/README.md) | Coordinated project scenes, moving presenter framing, independent Caption, semantic graphic events and Take-free intervals | Download its accepted media/Result bundle; render locally |
+| [Complex spoken explainer](complex-explainer/README.md) | Coordinated project scenes, moving presenter framing, independent Caption, semantic graphic events and graphics-only intervals | Download its accepted media/Result bundle; render locally |
The three generation entries use `reference.svml` and an adjacent `reference.svrun`. They generate
-their main images, recurring voice references and video Takes, then normalize media, align the Script
-and compose the video. They need no earlier Build Result or manually supplied presenter, host or scene
-image. The explainer instead opens a complete 137-second production with 17 accepted Takes, recorded
-demonstrations, pixel graphics and sound; its default Run reuses the supplied material.
+their main images, recurring voice references and generated clips, then normalize media, align the
+Script where needed, and compose the video. They need no earlier Build Result or manually supplied
+presenter, host or scene image. The explainer instead opens a complete 137-second production with 17
+accepted performance clips, recorded demonstrations, pixel graphics and sound; its default Run reuses
+the supplied material.
Self-contained here means a project directory: SVML, its imported SVS/Kits and the selected local
assets. The installed Hypit Distribution supplies the imported packages. A Runtime Profile and
diff --git a/packages/narrative-speech-alignment/src/locate.ts b/packages/narrative-speech-alignment/src/locate.ts
index d5fae7db..a2885f1d 100644
--- a/packages/narrative-speech-alignment/src/locate.ts
+++ b/packages/narrative-speech-alignment/src/locate.ts
@@ -17,7 +17,7 @@ export type LocalTimedSpeechToken = NarrativeAlignmentTiming["tokens"][number];
export type LocalSemanticTimePoint = NarrativeAlignmentTiming["boundaries"][number];
export type LocalSemanticTiming = NarrativeAlignmentTiming;
-/** Package-private clock used while aligning exactly one normalized Segment Take. */
+/** Package-private clock used while aligning exactly one Segment's normalized media. */
export type AlignmentBasis = {
readonly domainId: string;
readonly frameDomain: {
@@ -103,7 +103,7 @@ function validateBasis(narrative: Narrative, basis: AlignmentBasis): void {
}
const frameCount = basis.frameDomain.frameCount;
if (narrative.segments.length !== 1 || basis.segments.length !== 1) {
- fail("SPEECH_BASIS_SEGMENTS", "Speech alignment accepts exactly one normalized Segment Take.");
+ fail("SPEECH_BASIS_SEGMENTS", "Speech alignment accepts normalized media for exactly one Segment.");
}
let previousEnd = 0;
for (const [index, segment] of basis.segments.entries()) {
diff --git a/packages/provider-hypihub/README.md b/packages/provider-hypihub/README.md
index 606f52d0..a8686c6f 100644
--- a/packages/provider-hypihub/README.md
+++ b/packages/provider-hypihub/README.md
@@ -94,7 +94,8 @@ For moving portraits, [Volcengine Matting](../volcengine-matting/README.md) maps
Both formats carry transparency. The source video uses the same upload transport as other video
references; the returned job uses the same polling and asset collection lifecycle. The selected
account's `/v1/models` establishes availability. The processed video enters ordinary Normalize,
-then either semantic alignment for a Script performance or a Visual Clip for independently timed footage.
+then a Visual Clip or another ordinary media consumer; add semantic alignment separately when a
+Script relationship needs positions inside that performance.
Runtime Profile example:
diff --git a/packages/script/README.md b/packages/script/README.md
index 96313166..7aca8173 100644
--- a/packages/script/README.md
+++ b/packages/script/README.md
@@ -41,8 +41,8 @@ numbers; capitalization does not distinguish Roles from Segments.
An empty Segment such as `<empty></empty>` (or `<empty/>`) is valid. `empty` is an ordinary
author-chosen name, not a reserved keyword. It retains the Segment identity and both boundary anchors
while contributing no Tokens or spoken text. This supports wordless passages in the same semantic
-model: an associated local temporal domain determines duration, while NarrativeAlignment supplies
-the Segment boundary relation with no word units.
+model: associated prepared media can determine duration, and NarrativeAlignment can supply the
+Segment boundary relation with no word units when another contribution consumes that identity.
The package exports its Manifest, `parseScript`, semantic/source-map projection helpers, a
semantic-preserving formatter and the raw `decodeScriptSurface` handler. Source ranges and parser
@@ -63,7 +63,7 @@ The Surface exports one full Narrative plus narrow, immutable views:
`@hypit/narrative-caption` relates the separately exported Caption units to Narrative Tokens and
projects them through explicit Narrative time. Seedance consumes dialogue `Text`,
-Estimate and TTS consume speech `Text`, and semantic preparation consumes the Segment excerpt. None imports
+Estimate and TTS consume speech `Text`, and optional semantic preparation consumes the Segment excerpt. None imports
Script's parser AST. Another authoring package may produce the same ordinary Text, Narrative and
CaptionDocument contracts.
@@ -102,8 +102,8 @@ side is invalid. This adds no new public value type or protocol version.
## Segments, turns and Cues are different boundaries
A Segment names a structural production passage. It can contain several Role turns and be performed
-by one Take with several edited shots. A Role Cue changes who speaks; it neither creates a character
-asset nor requires another generated Take. `||` changes Caption grouping between complete Alignment
+in one generated clip with several edited shots. A Role Cue changes who speaks; it neither creates a character
+asset nor requires another generated clip. `||` changes Caption grouping between complete Alignment
Units; it does not split the Segment, cut the picture or end a Selection.
```svml
diff --git a/packages/script/src/manifest.ts b/packages/script/src/manifest.ts
index 09ee3c1c..a7f361d0 100644
--- a/packages/script/src/manifest.ts
+++ b/packages/script/src/manifest.ts
@@ -38,7 +38,7 @@ export const scriptMarkupSurfaces = [
{ name: "", type: narrativeType,
summary: "The complete authored Narrative, including speech structure, semantic anchors and its CaptionDocument, addressed by the element's own id." },
{ name: "segment.<id>", type: narrativeSegmentRefType,
- summary: "One Segment as a narrow Excerpt, used to associate a generated Take with that Segment." },
+ summary: "One Segment as a narrow Excerpt, used to associate generated or supplied performance media with that Segment." },
{ name: "segment.<id>.dialogue", type: textTypes.text,
summary: "One Segment as display-independent dialogue, keeping Role Cue labels and the spoken side of Dual Text." },
{ name: "segment.<id>.speech", type: textTypes.text,
diff --git a/packages/seedance-kits/README.md b/packages/seedance-kits/README.md
index 67cc5bfc..6660f2fc 100644
--- a/packages/seedance-kits/README.md
+++ b/packages/seedance-kits/README.md
@@ -88,7 +88,7 @@ Script Segment's `.dialogue` Text, retaining pronunciation and Role turns. Optio
this passage's attitude, vocal delivery, attention, interaction and any motivated cuts admitted by
the Kit. In Speaker, `performance` selects the recurring approach to voice and visible expression;
`gesture` selects body language, while `action` directs the particular thought and response.
-Do not retype the complete spoken text into action or treat each Role turn as a required new Take.
+Do not retype the complete spoken text into action or treat each Role turn as a required new generated clip.
For B-roll, `story` carries the silent visual events rather than spoken dialogue.
These files are reusable packaged authoring material. When one production needs a different prompt
@@ -104,8 +104,8 @@ For ordinary direct-to-camera social video, explicitly select
for the directing judgment, and the [Speaker template](kits/speaker-v1.svs) for the exact wording of
its Recipe choices. Choose `performance` and `gesture` for the character's intended presence.
-Reuse the same person-and-scene image and voice for ordinary Takes belonging to one UGC performance.
-Each Take can begin from that shared reference and meet the others at a natural cut. There is no
+Reuse the same person-and-scene image and voice for ordinary generated clips belonging to one UGC performance.
+Each clip can begin from that shared reference and meet the others at a natural cut. There is no
required previous-tail-frame chain. Independent generation follows the intended edited form.
For example, a lively ranking host can use:
diff --git a/packages/seedance/README.md b/packages/seedance/README.md
index 9f805830..70e50800 100644
--- a/packages/seedance/README.md
+++ b/packages/seedance/README.md
@@ -24,10 +24,30 @@ All three preserve the remote result as one atomic `GeneratedVideoSet`, then exp
member as an ordinary `Blob`. Their prompt ports consume ordinary `Text`, so a Script projection,
generic Text Template or third-party author module can feed them without becoming part of Seedance.
-`standard`, `fast`, `mini` and `2.5` select model variants independently of the invocation shape. Duration is
-the author's literal, in whole seconds inside the model's declared range; measure the spoken line first
-with `hypit estimate` and write the number here. Nothing in the graph computes it, so a Build plan is
-complete before it starts.
+`standard`, `fast`, `mini` and `2.5` select model variants independently of the invocation shape.
+Duration is the author's literal inside the model's declared range: `standard`, `fast` and `mini`
+accept 4–15 whole seconds, while `2.5` accepts 4–30 whole seconds or `-1` for its automatic source-edit
+contract. Measure a spoken line first with `hypit estimate` when the request is sized by delivery and
+write the number here. Nothing in the graph computes it, so a Build plan is complete before it starts.
+
+## Video reference relationships
+
+All four variants expose video references through `ReferenceVideo`. A video reference can transfer a
+named temporal property—such as motion, camera behavior, performance rhythm or effect evolution—while
+the request creates new material. Seedance 2.5 can also treat a supplied video as the material being
+edited while preserving the relationships the prompt does not ask to change. For that strict
+source-edit relationship, author `duration="-1"` and `aspect-ratio="adaptive"`:
+
+```xml
+<seedance:ReferenceVideo id="edit" model="2.5" prompt={direction}
+ duration="-1" aspect-ratio="adaptive">
+ <seedance:Reference video={source.video} person-reference="true"/>
+</seedance:ReferenceVideo>
+```
+
+This pair is not a default for every video reference or every clone. Use an ordinary authored
+duration and aspect ratio when the request is transferring selected behavior into newly generated
+material. The selected Provider owns whether and how it implements each exact model contract.
## Reference audio
diff --git a/packages/speech-estimate/README.md b/packages/speech-estimate/README.md
index ea8bff51..fe8d6c10 100644
--- a/packages/speech-estimate/README.md
+++ b/packages/speech-estimate/README.md
@@ -73,7 +73,7 @@ selected model's supported values in mind.
`SpeechEstimatePolicy` holds the language, pace or rate, rounding and optional padding used by the
estimation API. `speechEstimatePolicyFromRecipe` reads those values from a Recipe for package authors.
The calculation produces a duration estimate for authoring; actual word positions come from the
-performed media's semantic preparation.
+performed media's semantic preparation when downstream relationships need those positions.
```ts
import { estimateSpeechDuration, sealSpeechEstimatePolicy, speechEstimatePolicyFromRecipe } from "@hypit/speech-estimate";
diff --git a/packages/studio/README.md b/packages/studio/README.md
index 1f133f95..a8838200 100644
--- a/packages/studio/README.md
+++ b/packages/studio/README.md
@@ -176,8 +176,8 @@ parsed anchors and preserve unrelated prose, whitespace and word attributes; the
words are not a replacement text source. Recipe parameter reads use the same Source Header preparation
as compilation, preserving UTF-16 offsets for the exact property being edited.
-The Timeline owns the editor's complete range; displayed objects do not extend it. Take placement
-and complete extent are reference information in Studio.
+The Timeline owns the editor's complete range; displayed objects do not extend it. Placed media and
+their complete extents are reference information in Studio.
Timeline gestures use explicit temporal authority. Moving a shared Selection or
Moment edits Script and moves its consumers after recompilation. A parameter-based
diff --git a/packages/studio/src/ui/selection.ts b/packages/studio/src/ui/selection.ts
index a18ab53d..179abefd 100644
--- a/packages/studio/src/ui/selection.ts
+++ b/packages/studio/src/ui/selection.ts
@@ -49,7 +49,7 @@ export type Store = {
*
* A Script intent wins over the element that binds it: `@{claim} … @{/claim}` sits
* inside the `<script>` element, so without that preference every click in the
- * prose would select the Speech Take instead of the B-roll. Ties break toward
+ * prose would select the speech performance instead of the B-roll. Ties break toward
* the tightest range, which is the most specific thing under the cursor.
*/
export function clipAtOffset(snapshot: StudioSnapshot, offset: number): Clip | undefined {
diff --git a/packages/whisperx/src/manifest.ts b/packages/whisperx/src/manifest.ts
index bd943893..3d5a531d 100644
--- a/packages/whisperx/src/manifest.ts
+++ b/packages/whisperx/src/manifest.ts
@@ -33,7 +33,7 @@ export const whisperXMarkupSurfaces = [{
summary: "Selects the authored Narrative that owns the Segment and Token identities." },
{ name: "segment", kind: "reference", required: true,
accepts: [narrativeTypes.segmentRef],
- summary: "Selects the single authored Segment performed by this Take." },
+ summary: "Selects the single authored Segment performed by this media." },
{ name: "media", kind: "reference", required: true,
accepts: [mediaTypes.synchronized],
summary: "Selects the already normalized SynchronizedMedia represented by this Segment." },
diff --git a/skills/hypit/SKILL.md b/skills/hypit/SKILL.md
index 1e1ab19f..d8111e89 100644
--- a/skills/hypit/SKILL.md
+++ b/skills/hypit/SKILL.md
@@ -73,6 +73,10 @@ answers or payoffs. This is Hypit's strong production prior: a new wording or de
presentation with its meaning. Preserve what each event responds to. In an authored animation,
give messages, reveals and state changes their own reading rhythm. Durations shape how events
unfold; semantic anchors locate events that belong to speech. A piece can use both relationships.
+Treat reference footage as evidence first. Connect a selected passage to a generation request only
+when the new material must preserve or transfer continuous temporal behavior that prose, stills or
+authored components would lose. [Video direction](references/playbooks/craft/video-direction.md#let-footage-carry-temporal-behavior-that-matters)
+owns that decision and the distinction between understanding footage and using it as model input.
A-roll names the performance carrying a passage. Its normalized Extent may construct Timeline and its
local domain may project meaning; after those contributions, picture and sound use the same ordinary
@@ -186,8 +190,9 @@ runs. Plan shared framing needs in Treatment and direction; judge the actual ove
graphics once the production media is available.
Build around the directed material and existing Outputs. Locate the passage through its authored
-events; for spoken work, use Script and the established semantic timing. Watch how MG, Caption, B-roll, Typography
-and Effects work together in the current picture. Prefer [snapshots](references/production/snapshots.md)
+events; for spoken work, use Script and any semantic timing the current composition actually
+consumes. Watch how MG, Caption, B-roll, Typography and Effects work together in the current picture.
+Prefer [snapshots](references/production/snapshots.md)
for detailed states and continuous frame grids, and Studio playback for the passage with sound: the graphics make the idea clear,
the Caption is easy to read, and the pictures and effects appear where and when they serve the
passage. Adjust the owning Source or component to improve those relationships. Reuse produced media
diff --git a/skills/hypit/references/creation/script-and-time.md b/skills/hypit/references/creation/script-and-time.md
index 073737fe..4df21d48 100644
--- a/skills/hypit/references/creation/script-and-time.md
+++ b/skills/hypit/references/creation/script-and-time.md
@@ -136,23 +136,24 @@ Script also represents passages without speech:
```
`empty` is an ordinary Segment name; a name such as `product-detail` can express the passage's role.
-No words does not mean no semantics: the Segment retains its identity. Associated normalized media
-provides a local duration, and its NarrativeAlignment can have an empty unit array while still mapping
-the Segment boundaries.
+No words does not mean no semantics: the Segment retains its identity, and associated normalized
+media can provide its local duration. When a consumer needs that identity projected through the
+actual media, NarrativeAlignment can have an empty unit array while still mapping the Segment
+boundaries; the Segment's existence alone does not require Alignment.
The same Timeline and Track timing vocabulary apply to a wordless passage or an entire
piece made from prepared media. The empty tag itself declares neither a zero-length interval nor a duration.
For an interval made only of component animation, use Timeline placement and extent instead; it
needs no media-backed Segment. Spoken, wordless-media and graphics-only passages can share one work.
Choose Segment boundaries from natural production passages and delivery length, not from every
-picture cut. One Segment and Take can carry several speaking turns, camera cuts or a split-screen
+picture cut. One Segment and one generated clip can carry several speaking turns, camera cuts or a split-screen
conversation. One continuous narration can carry many B-roll changes through Selections. Edited UGC
-can deliberately use several Takes driven by the same character-and-scene image; a natural cut is
+can deliberately use several generated clips driven by the same character-and-scene image; a natural cut is
often part of its appeal. A Role change or `||` does not require another generation.
When retained recorded speech carries the passage, a file cut changes that performed material but
does not automatically create a Segment. Several retained stretches can form one passage; distinct
-passages can use separate Takes. Write the Script for the final performed words and align the
-prepared result on its own local clock.
+passages can use separate performance clips. Write the Script for the final performed words and,
+when downstream relationships need their positions, align the prepared result on its own local clock.
## Time an authored animation
@@ -218,11 +219,12 @@ energy while finding a performable shape, then estimate the affected wording aga
applies this judgment to the selected model's request range.
The estimate balances the intended speaking density and sizes generation; it supplies no timeline
-anchors. Once a generated clip is accepted, normalize it, align its actual speech to its Script Segment,
-construct an equal-length Timeline Window and map the alignment through that domain/Window relation. The literal duration answers how much
-media to request. The aligned words answer where Caption, B-roll, MG, and Effects belong in that actual
-media. Alignment measures real word positions inside that media envelope; it does not reproduce an
-estimated distribution of words.
+anchors. Once a generated clip is accepted, normalize it and use its actual extent to construct an
+equal-length Timeline Window. When Caption, B-roll, MG, Effects or another consumer needs word
+positions, align the actual speech to its Script Segment and map that evidence through the
+domain/Window relation. The literal duration answers how much media to request. Alignment answers
+where words occurred inside accepted media; it does not reproduce an estimated distribution of words
+and is not required when no downstream relationship consumes those positions.
For a wordless Segment, choose the requested duration from the action, music or visual rhythm.
Speech-rate estimation has no role there; the resulting media still determines its Segment span.
@@ -250,5 +252,5 @@ the target or preserve an incidental lead/lag unless that offset itself is part
Timing seen in Studio or a real Result may expose one of several different problems. A wrong Cue or
semantic anchor changes Script. A sound performance that changes the intended rhythm may change the
duration choice or Treatment. A correct Selection rendered badly changes the component or Recipe. An
-unusable generated Take changes its prompt, reference, Candidate, or shot design. Put each correction
+unusable generated clip changes its prompt, reference, Candidate, or shot design. Put each correction
where its fact is owned.
diff --git a/skills/hypit/references/creation/transformations.md b/skills/hypit/references/creation/transformations.md
index e69916d0..a3c08e09 100644
--- a/skills/hypit/references/creation/transformations.md
+++ b/skills/hypit/references/creation/transformations.md
@@ -59,13 +59,15 @@ these together. Changing the person is common; a narrow substitution may leave m
relationships intact. When a new body, object or story changes what an action means, reshape the
action to serve the target's intention. Brief and Treatment hold the requested change and the new
creative answer; the source footage remains evidence rather than a ready-made target timeline.
+That evidence may remain observational, or a selected excerpt may become an actual generation input
+when the target must preserve or transfer its temporal behavior. These are different decisions.
In a comic speaking reference, an unusual camera angle may work together with role-played vocal
phrasing, expression and gesture. Put the intended words in Script, choose whose voice belongs to
the target, and direct how the visible performance delivers the joke. A supplied portrait establishes
appearance, not the voice or delivery. [Voice direction](../playbooks/craft/voice-direction.md) owns
casting; [video direction](../playbooks/craft/video-direction.md#let-footage-carry-temporal-behavior-that-matters)
-owns when a selected source excerpt should condition the new shot.
+owns when and how a selected source excerpt should condition the new shot.
## "Make this with my face"
@@ -74,7 +76,7 @@ the spoken argument and comic reveals may already suit the new presenter. Bring
camera image with the reference's teasing confidence, useful framing, and room for the board. Keep
the full [image craft](../playbooks/craft/image-direction.md), directing the supplied person's appeal
and presence with the same care as any leading performer in this work. That image can carry all
-ordinary talking Takes and supply the person's other appearances.
+ordinary talking clips and supply the person's other appearances.
A joke about the original presenter's appearance or personal story needs another look: decide how
its setup and payoff fit the new casting and Brief. The new person may invite a different delivery or
@@ -113,7 +115,7 @@ asset came from. The normal task is to create the target media.
External references become essential when public world knowledge cannot determine exact identity:
the user, a private or obscure product, a proprietary interface, an exact Logo or data display. An
-accepted generated image, Take, or sound can then become authority for later work.
+accepted generated image, video or sound can then become authority for later work.
Prefer reference-conditioned video generation when identity, art direction, composition, or product
continuity matters. The input guides the shot without having to appear as its literal first or last
diff --git a/skills/hypit/references/playbooks/craft/b-roll.md b/skills/hypit/references/playbooks/craft/b-roll.md
index 831e44ef..26321d21 100644
--- a/skills/hypit/references/playbooks/craft/b-roll.md
+++ b/skills/hypit/references/playbooks/craft/b-roll.md
@@ -12,7 +12,7 @@ Creator-led video often shows the speaker's life while their performed words con
studying, travelling, using a product or reacting in another situation. Those pictures make the
person and world more tangible. The person visible in a lifestyle image or silent clip may be the
same person whose voice is heard; the placed performance still owns the words. A different passage
-may use a visible speaking Take whose own delivery carries the words. [Voice and performance](voice-and-performance.md)
+may use a visible speaking performance whose own delivery carries the words. [Voice and performance](voice-and-performance.md)
owns that distinction.
An image can hold a product fact while the speaker makes a claim. A moving demonstration can show
diff --git a/skills/hypit/references/playbooks/craft/caption-tracking.md b/skills/hypit/references/playbooks/craft/caption-tracking.md
index 7097b3e2..3759b24e 100644
--- a/skills/hypit/references/playbooks/craft/caption-tracking.md
+++ b/skills/hypit/references/playbooks/craft/caption-tracking.md
@@ -15,7 +15,7 @@ to keep their earlier words on screen.
Measure whichever available picture lets those relationships be mapped accurately:
-- A supplied clip or prepared Take gives source-local positions that must follow its placement,
+- A supplied or prepared clip gives source-local positions that must follow its placement,
playback, crop and any moving view into the composition.
- A composed view already contains its camera framing and program time, provided graphics do not
obscure the person being measured.
@@ -55,7 +55,7 @@ the first or largest face alone can attach the guest's Caption to the interviewe
Transform the useful observations into ordinary project data, with these decisions explicit:
- **Clock:** sample the observations on the Timeline's frame clock using the actual source playback
- mapping. For a prepared Take on the same clock at native speed, add its actual placement start,
+ mapping. For prepared media on the same clock at native speed, add its actual placement start,
including any gap or overlap. Apply any source trim or rate change when measuring other footage.
Final-video measurements already use that rendered program's clock.
- **Geometry:** convert detector edges to `[x, y, width, height]` using width `right - left` and height
diff --git a/skills/hypit/references/playbooks/craft/captions.md b/skills/hypit/references/playbooks/craft/captions.md
index ed4402b9..12bcc451 100644
--- a/skills/hypit/references/playbooks/craft/captions.md
+++ b/skills/hypit/references/playbooks/craft/captions.md
@@ -43,9 +43,10 @@ performed speech. The following sections connect these decisions to the actual p
## Keep wording and timing in their owners
Script owns display words, speaking Roles, Dual Text units, attributes and `||` Cue Breaks. Its
-CaptionDocument contains no seconds or frames. A source-domain adapter produces CaptionTiming on the actual Timeline;
-a visual family then presents the timed units. Reuse those units rather than retyping spoken words
-into independent Typography merely because it can draw the desired shape.
+CaptionDocument contains no seconds or frames. A source-domain adapter produces complete, flat Unit
+CaptionTiming on the actual Timeline; a visual family then forms and presents its Cues from those
+timed units. Reuse those units rather than retyping spoken words into independent Typography merely
+because it can draw the desired shape.
Use the produced performance's normalized and aligned audio. A change to that audio, its speed or
its cuts can change word timing and requires corresponding alignment. A visual-only restyle can
diff --git a/skills/hypit/references/playbooks/craft/examples/conversation-images.md b/skills/hypit/references/playbooks/craft/examples/conversation-images.md
index a2efe398..8574e0fb 100644
--- a/skills/hypit/references/playbooks/craft/examples/conversation-images.md
+++ b/skills/hypit/references/playbooks/craft/examples/conversation-images.md
@@ -215,4 +215,4 @@ the views needed, state what each parent preserves, and connect authoritative re
production needs exact private or factual identity.
The podcast branches change camera, prop state or daily situation for different reasons. The
interview branches change attention while keeping a shared encounter. Neither graph asks for a
-chain of generated video end frames, and neither requires redrawing all materials for every Take.
+chain of generated video end frames, and neither requires redrawing all materials for every generated clip.
diff --git a/skills/hypit/references/playbooks/craft/generated-dependencies.md b/skills/hypit/references/playbooks/craft/generated-dependencies.md
index 797fc9b2..ada882be 100644
--- a/skills/hypit/references/playbooks/craft/generated-dependencies.md
+++ b/skills/hypit/references/playbooks/craft/generated-dependencies.md
@@ -21,7 +21,7 @@ The first host view can also meet a product image in another request. In that pi
## Give each new picture the references it needs
-A useful first camera image can establish person and place together. It may show one person, several people or the whole encounter. When another view needs that world, carry its atmosphere, palette, materials and spatial relationships into the view the new camera should see. Several Takes can then use the resulting images.
+A useful first camera image can establish person and place together. It may show one person, several people or the whole encounter. When another view needs that world, carry its atmosphere, palette, materials and spatial relationships into the view the new camera should see. Several video requests can then use the resulting images.
A new location can begin with a camera image that already places the people in that setting. Their established views can supply identity or styling; a product or continuing prop can supply its form and state. The new picture establishes the location and composition together, while the prior images carry the facts that persist across the move. A character reference can also carry identity directly into video direction when the new place does not need its own key image.
@@ -35,4 +35,4 @@ Keep useful prompts and source images with the project when later views may need
## Carry the shared world into motion
-The image graph records visual facts to carry forward, not the video work's shot order or request boundaries. One camera image may guide a passage with several views or multiple Takes in the same world; several images may contribute different facts to one request. A video excerpt can carry performed action or camera behavior that a still cannot show; [video direction](video-direction.md#let-footage-carry-temporal-behavior-that-matters) owns those input choices and the requested action. [Voice and performance](voice-and-performance.md) and [B-roll](b-roll.md) own the resulting footage's roles in the work.
+The image graph records visual facts to carry forward, not the video work's shot order or request boundaries. One camera image may guide a passage with several views or multiple generated clips in the same world; several images may contribute different facts to one request. A video excerpt can carry performed action or camera behavior that a still cannot show; [video direction](video-direction.md#let-footage-carry-temporal-behavior-that-matters) owns those input choices and the requested action. [Voice and performance](voice-and-performance.md) and [B-roll](b-roll.md) own the resulting footage's roles in the work.
diff --git a/skills/hypit/references/playbooks/craft/sound-mix.md b/skills/hypit/references/playbooks/craft/sound-mix.md
index 0879f347..13a7f898 100644
--- a/skills/hypit/references/playbooks/craft/sound-mix.md
+++ b/skills/hypit/references/playbooks/craft/sound-mix.md
@@ -6,7 +6,7 @@ owns who performs the words and where that voice comes from.
## Start with the sound the material already carries
-In speaking-video A-roll, the person's picture, words and voice belong to the same performed Take.
+In speaking-video A-roll, the person's picture, words and voice belong to the same performed media.
Its sound continues at the current Timeline position while B-roll, graphics or a different view
changes the picture. Audio-only A-roll likewise supplies performed speech, with its picture authored
separately. A wordless performance may carry its own sound or be silent. Present the selected source's
@@ -60,7 +60,7 @@ their exact playback, trigger and gain syntax.
## Preserve continuity across picture changes
A picture cut need not cut the acoustic world. Room tone can continue across views of one place,
-music can bind a montage, and a speaking Take can remain audible as another picture takes the frame.
+music can bind a montage, and a speaking performance can remain audible as another picture takes the frame.
A change of place, speaker perspective or narrative state may instead call for an audible handoff
even when the picture changes gently. Follow the listener's sense of the encounter.
diff --git a/skills/hypit/references/playbooks/craft/video-direction.md b/skills/hypit/references/playbooks/craft/video-direction.md
index 0f9af6d1..730eab05 100644
--- a/skills/hypit/references/playbooks/craft/video-direction.md
+++ b/skills/hypit/references/playbooks/craft/video-direction.md
@@ -11,13 +11,15 @@ outgoing or restrained.
## Let footage carry temporal behavior that matters
-Choose generation inputs from what the new shot must actually realize. A still can establish a
-person, object, place or composition; prose can direct an action and its expressive purpose. When a
-particular unfolding in time is essential to the result—its performed rhythm, path, contact,
-coordination or camera relationship—and prose and stills would lose that information, use the
-relevant source footage as a video reference to a model that accepts it. This judgment follows the
-action the work needs, whether or not the user names a generation method. A broadly described action
-can leave more freedom to the model when its exact movement is not the point.
+Reference footage is evidence before it is a generation input. Watch and listen to understand the
+work, whether or not any of its frames will enter a model request. Choose generation inputs from what
+the new shot must actually realize. A still can establish a person, object, place or composition;
+prose can direct an action and its expressive purpose. When a particular unfolding in time is
+essential to the result—its performed rhythm, path, contact, coordination, effect evolution or
+camera relationship—and prose, stills or authored components would lose that information, use the
+relevant source footage as a video reference to a model that accepts it. The fact that a task is
+called a clone does not by itself make the whole reference video a generation input. A broadly
+described action can leave more freedom to the model when its exact movement is not the point.
Replacing a person is a common case; the target may instead change an object, world, words or sound.
A comic speaking performance can depend on the relation between vocal phrasing, face, gesture and
@@ -30,15 +32,21 @@ establish the new visible facts and the prompt directs their relationship.
new work keeps and reshapes. Watching a reference to understand a work is distinct from connecting
a selected excerpt as an actual generation input.
+Name the relationship the excerpt contributes. In **reference transfer**, it supplies a temporal
+property such as motion, camera behavior, performance rhythm or effect evolution while the request
+creates new material. In **strict source editing**, the supplied footage is itself the material being
+changed, and the direction states what changes and which motion, framing, timing or sound remains.
+A request can combine evidence from several materials, but each one still needs a stated job. These
+are model-input relationships, not separate kinds of Hypit work. An accepted result is ordinary Media
+and enters normalization, Timeline and presentation like any other material.
+
Choose an excerpt that contains the useful action and, when relevant, its preparation or settling.
Its range follows the relationship to preserve, the intended new duration and the selected model's
reference limits. Connect the actual footage in Source; describing it in prose does not supply
its temporal behavior to the model. The selected model and Provider determine supported combinations
and media requirements; read their installed vocabulary and package documentation for the exact
-request. Seedance requires `person-reference="true|false"` on each image/video reference: true if
-the supplied material contains a person, false otherwise.
-Inspect the selected excerpt, not just its first frame. Audio must omit the field; the installed
-Seedance README owns the corresponding required first/last-frame attributes.
+request, including reference metadata and any strict-edit duration or aspect contract. Inspect the
+selected excerpt, not just its first frame.
For a longer action, distinguish the duration of source footage the model can accept from the
duration it can produce in one request. Use one request when the model's capability and the work's
@@ -93,7 +101,7 @@ in the new Script. This preserves the expressive relationship while letting the
their own movements and phrasing. Phrase-level emphasis should fit the performed language's tones
and cadence; a source-language stress pattern is not a universal performance instruction.
-Carry the character, voice and useful physical relationships across Takes while directing the
+Carry the character, voice and useful physical relationships across generated clips while directing the
attitude each passage calls for. The same speaker can invite, question, tease and persuade as the
argument develops. Shared direction can preserve their manner; the passage supplies the particular
response. Carry forward production continuity, and reconsider the expressive intention whenever the
@@ -236,6 +244,8 @@ useful images can already establish people, scenes, products, composition and vi
requested performance then makes that world move. Text-directed or first-/last-frame generation remains
useful when its relationship is genuinely the one the shot needs; a last frame belongs when arriving
at that exact image is part of the intended action.
+Reference transfer and strict source editing are two uses within reference-directed generation, not
+additional invocation shapes or finished-work categories.
Model-specific Surfaces and Prompt Kits are implementations of these relationships, not the Craft
itself. Kits produce ordinary Text; Source connects that Text and the actual references to the selected
@@ -260,7 +270,7 @@ guest and use the interviewer view for a reaction. An unfolding action or a held
its effect from a continuous shot; choose that temporal shape when it serves the passage.
One generated video can contain multiple shots, several speaking turns or a split-screen composition.
-One Segment is not one speaker turn or one camera shot. Conversely, several Takes can reuse the same
+One Segment is not one speaker turn or one camera shot. Conversely, several generated clips can reuse the same
character-and-scene image and meet at natural editorial cuts. A genuinely continuous shot calls for
the model relationship and direction that preserve that action. See
[Reference relationships](generated-dependencies.md) when deciding which visual or motion evidence
@@ -298,6 +308,7 @@ question and answer may belong together, a short line may gain a meaningful reac
exchange may divide where its thought turns. Preserve the intended meaning and energy, then choose a
supported duration.
-After production, normalized media supplies the real envelope and alignment supplies word positions.
-Use that material and timing to compose the piece. [Composition review](../../production/review.md)
+After production, normalized media supplies the real envelope. When the composition needs word
+positions, alignment supplies them from the accepted performance. Use the material and any required
+timing to compose the piece. [Composition review](../../production/review.md)
owns judging how Caption, MG, B-roll and other layers work with the produced performance.
diff --git a/skills/hypit/references/playbooks/craft/voice-and-performance.md b/skills/hypit/references/playbooks/craft/voice-and-performance.md
index e053dd3a..7572dc4a 100644
--- a/skills/hypit/references/playbooks/craft/voice-and-performance.md
+++ b/skills/hypit/references/playbooks/craft/voice-and-performance.md
@@ -8,7 +8,8 @@ or whether an off-screen passage continues an A-roll performance or uses indepen
A Segment is one authored passage in the Script. Before production it has identity and meaning but no
seconds. A-roll names the performance carrying that passage. Its prepared media supplies duration;
-spoken words acquire local timing through semantic preparation. Visible performance can carry
+spoken words can acquire local timing through semantic preparation when the composition needs their
+positions. Visible performance can carry
picture and sound together; audio-only performance carries the passage while other contributions
supply its picture.
@@ -28,7 +29,8 @@ how many semantic clocks exist.
A recurring presenter, podcast speaker, interview participant, or dramatic character continues to
own their own lines even while another picture covers them. Visual handoffs, coverage, Caption, MG,
and Effects are authored against the time that performance established. If an edit changes the
-performance's actual length, prepare and align the edited media before assembly.
+performance's actual length, prepare the edited media before assembly and realign it when those
+dependent layers use semantic timing.
A wordless Segment can identify a real performed passage, such as a dance or reaction. Its prepared
media supplies a local domain without spoken words. A graphics-only interval can instead contribute
@@ -66,13 +68,13 @@ their visual hierarchy, and [Spatial layout](../../production/spatial.md) owns g
The usual A-roll assembly places Segment performances one after another without consuming either
side of their duration. This fits how the work is authored: `hypit estimate` helps size each request so
its words, delivery and action belong naturally in that generated passage, and speaking video models
-normally use the requested clip to perform the line. Asking one Take to remain silent for a synthetic
+normally use the requested clip to perform the line. Asking one generated clip to remain silent for a synthetic
half-second handle at its beginning or end works against both that sizing and the model's performance.
-A duration-consuming crossfade between neighboring A-roll Takes can eat into the word windows that
+A duration-consuming crossfade between neighboring A-roll clips can eat into the word windows that
each performance established. The result may contain simultaneous speech at a boundary and weaken
the listening rhythm. For ordinary creator speech, podcast turns, interviews and short drama, this
-makes a direct join between the prepared Segment Takes a practical starting point. Visual coverage
+makes a direct join between the prepared Segment performances a practical starting point. Visual coverage
and effects can still cross that seam without changing the underlying speech time.
Deliberate interruption, overlapping dialogue or musical phrasing can use explicit Window positions.
@@ -84,7 +86,8 @@ choice for creator speech.
## Give a recurring person one accepted voice
When the intended work retains a person's recorded delivery, prepare that passage and align its
-actual sound to Script; its picture, if retained, is available to Visual Clip. A supplied recording
+actual sound to Script when downstream relationships need word or boundary positions; its picture,
+if retained, is available to Visual Clip. A supplied recording
may instead guide a new performance or provide a short Voice Reference. Voice Design can make such
a reference when a new performance needs one and none was supplied; Voice Clone can then perform
independently narrated lines from Script. The intended use of the recording, not its mere presence,
@@ -127,14 +130,14 @@ visible A-roll audio-only A-roll
```
An A-roll-capable video model receives the short reference and the actual Script while generating
-the person's visible speaking Take. Voice Clone receives the same reference and the passage's Script
+the person's visible speaking clip. Voice Clone receives the same reference and the passage's Script
when the work needs independent speech; it generates that passage's audio, whose length follows the
passage and the selected speech model's request limits rather than the short reference's duration.
These are two uses of one ordinary Resource, not two voice identities.
A work may combine them. A host can perform visible A-roll and later narrate a passage that has no
underlying on-camera performance; using the same Voice Reference makes both sound like the same
-person. Another passage covered by B-roll may still be audio from the A-roll Take beneath it. Decide
+person. Another passage covered by B-roll may still be audio from the A-roll performance beneath it. Decide
from the passage's expressive construction, not from whether the face happens to be visible at that
instant.
@@ -149,7 +152,8 @@ Audio-only A-roll is useful when a Segment is constructed without an on-camera s
performance: a desktop point-of-view demonstration, a narration-led montage, a pure MG explanation,
or a product-explanation passage inside an otherwise presenter-led work. Voice Clone
uses the person's existing Voice Reference and the Segment's actual Script to produce that passage.
-The resulting audio is normalized and aligned like any other performed media. An Audio Clip
+The resulting audio is normalized like any other performed media and aligned when Caption or another
+semantic consumer needs positions inside it. An Audio Clip
Source pairs that ordinary media with its exact Window while Visual Clips, Typography, MG, or another visual Track supplies what the
viewer sees; no compound audio-only semantic object is required.
@@ -193,7 +197,7 @@ with animated steps, labels and panels:
while the paper composition supplies its picture. This is an independent-narration-led module.
- When a ranking host says a brief “Top one: the product” over a paper reveal and then appears on
camera to continue the same judgment, the host's performance normally owns the whole passage. The
- paper reveal is MG coverage over that A-roll, and the sound remains the host Take's sound.
+ paper reveal is MG coverage over that A-roll, and the sound remains the host performance's sound.
Duration can support the reading but does not decide it. Ask what carries the argument, attitude and
progression, and whether an on-camera performance exists whose words naturally continue through the
@@ -212,8 +216,8 @@ other relationships.
## Give real performance real semantic time
-`../../creation/script-and-time.md` owns duration estimation, literal duration, and alignment. Once the
-accepted performance has semantic time, its dependent layers follow the delivery that really
+`../../creation/script-and-time.md` owns duration estimation, literal duration, and alignment. When
+the accepted performance has semantic timing, its dependent layers follow the delivery that really
happened.
## Carry the character through the performance
diff --git a/skills/hypit/references/playbooks/formats/presenter-led-explainer.md b/skills/hypit/references/playbooks/formats/presenter-led-explainer.md
index d42ddca5..fba4d751 100644
--- a/skills/hypit/references/playbooks/formats/presenter-led-explainer.md
+++ b/skills/hypit/references/playbooks/formats/presenter-led-explainer.md
@@ -28,8 +28,9 @@ number or comparison helps the viewer read that demonstration.
## Compose the performance and its presentation independently
A generated clip supplies accepted performance media. Normalization supplies its local domain and
-Extent; alignment supplies local word timing; an equal-length Window locates it in Timeline and lets
-the projector publish absolute meaning. The picture's arrangement can change several times during
+Extent; an equal-length Window locates it in Timeline. When demonstrations or graphics follow the
+performed words, alignment supplies local word timing and lets the projector publish their absolute
+values. The picture's arrangement can change several times during
that same Window. A new layout usually calls for a
presentation change, while a different spoken line or acted beat may call for new material. One
scene may also develop across several source occurrences. Spoken Segment boundaries do not prescribe
@@ -144,7 +145,7 @@ review the changed action and its handoffs; export the encoded film when that de
## Study one complete production
The [complex spoken explainer](https://github.com/hypit-ai/hypit/tree/main/examples/complex-explainer)
-is a finished 137-second example with 17 accepted Takes. Its guide links the film, editable sources,
+is a finished 137-second example with 17 accepted performance clips. Its guide links the film, editable sources,
media archive and project packages. Reading its code and notes needs no media download; opening the
full picture uses the supplied media/Result archive. The default Run reuses that accepted material.
diff --git a/skills/hypit/references/playbooks/formats/short-drama.md b/skills/hypit/references/playbooks/formats/short-drama.md
index 6d4fbe1d..6e6c6590 100644
--- a/skills/hypit/references/playbooks/formats/short-drama.md
+++ b/skills/hypit/references/playbooks/formats/short-drama.md
@@ -12,7 +12,7 @@ meaning, an action creates a consequence, or a reveal changes what the viewer un
silence, reaction and physical business can all carry that movement.
A Segment is a performable dramatic passage, not a required camera shot or speaker turn. One Segment
-can contain several people and cuts; several generated Takes can also reuse the same camera views when
+can contain several people and cuts; several generated clips can also reuse the same camera views when
the passage is better produced in parts. Choose the shape that lets the intended action and exchange
remain legible.
@@ -26,7 +26,7 @@ owns how the selected model's request range informs the performable passage.
Reference-conditioned generation is a strong starting point when the work depends on recognizable
people, a shared world, staging or composition. A key image can establish the character, a complete
-story view with the characters in their setting, or both. Direct images and Takes in natural language
+story view with the characters in their setting, or both. Direct images and video passages in natural language
for the current dramatic intention. Free direction suits the variety of dramatic scenes; a reusable
Prompt Kit becomes useful when repeated productions reveal a stable prompt relationship worth preserving.
@@ -38,15 +38,15 @@ views from the images that hold the facts they need:
- one story view can carry a costume, prop or spatial relationship into the next;
- a supplied image can serve directly when it already expresses the intended character and shot.
-Within one location, a small set of useful views can support many Takes. In a living-room dialogue,
+Within one location, a small set of useful views can support many generated clips. In a living-room dialogue,
one view for each conversational side may preserve everything the passage needs; modest reframing,
performance and camera changes can happen in video. Another image becomes useful when a new view must
establish an important fact, such as a changed relationship, decisive prop state or plot-bearing part
of the space.
-Decide separately which views to establish and which dramatic action to generate together. One Take
+Decide separately which views to establish and which dramatic action to generate together. One generated clip
can move among several shots or places while key images establish the people, objects, composition
-or continuity that need explicit visual direction; one view can also guide several Takes. A new
+or continuity that need explicit visual direction; one view can also guide several generated clips. A new
place merits an image when the story needs that particular view established, while other moves and
cuts can develop within the video passage. The image graph follows those visual dependencies rather
than the count of locations or edits.
diff --git a/skills/hypit/references/playbooks/formats/street-interview.md b/skills/hypit/references/playbooks/formats/street-interview.md
index ff017857..e6de7762 100644
--- a/skills/hypit/references/playbooks/formats/street-interview.md
+++ b/skills/hypit/references/playbooks/formats/street-interview.md
@@ -22,7 +22,7 @@ The [worked image directions](../craft/examples/conversation-images.md#street-in
show how little the derived prompts need to add once the shared image is doing its job.
`street-interview-v1` uses this supplied set: interviewer A, guest B, shared view, then the two voices
-in A/B order. All ordinary Takes reuse it. Its three-view limit is the design of this Kit, not a
+in A/B order. All ordinary generated clips reuse it. Its three-view limit is the design of this Kit, not a
restriction on every street interview or on Hypit. The interviewer keeps the microphone and moves
it toward whoever speaks; extending it to the guest is not handing over ownership.
@@ -33,7 +33,7 @@ can stay in the shared view; disbelief or an emotionally important challenge ear
close view. This directs attention rather than alternating cameras on a timer.
Action can specify cuts between the Kit's supplied setups. Several questions and answers fit in one
-Segment and one generated Take. Keep the chosen framing behavior within each setup and let the cut
+Segment and one generated clip. Keep the chosen framing behavior within each setup and let the cut
move directly to the next; an invented travel shot between cameras changes the scene's grammar.
## Give the encounter a before and an after
@@ -59,7 +59,7 @@ interested and spontaneous rather than theatrical; he continues to hold and posi
On the final passage, a short additional direction can return to her close view and let her begin
turning away after the punchline. The opening and ending actions belong to those actual passages;
-intermediate Takes carry the behavior of their own exchange.
+intermediate clips carry the behavior of their own exchange.
For the middle, give a few readable gestures a purpose: amused certainty, a compact shrug, a glance
that registers a surprising answer. Avoid exaggerated emotion, constant motion and exact numerical
diff --git a/skills/hypit/references/playbooks/formats/talking-head.md b/skills/hypit/references/playbooks/formats/talking-head.md
index e6229ca8..17e9468e 100644
--- a/skills/hypit/references/playbooks/formats/talking-head.md
+++ b/skills/hypit/references/playbooks/formats/talking-head.md
@@ -24,13 +24,13 @@ or rotation. A vivid attitude and an easy speaking gesture give this settled vie
to addressing the viewer; the generated performance can move and react within the encounter.
Cast the person's vocal appeal with [Voice direction](../craft/voice-direction.md).
-Use that same image and the person's recurring voice reference for every ordinary talking Take.
-Each Take can return to the same useful visual premise and contribute another piece of the edited
+Use that same image and the person's recurring voice reference for every ordinary talking clip.
+Each clip can return to the same useful visual premise and contribute another piece of the edited
performance.
Natural cuts are part of the desired result. A small change in pose between passages can make the
video feel like a creator's edited recording. Stable character-and-scene references can support each
-Take independently because this work wants edited speech rather than an unbroken simulated recording.
+clip independently because this work wants edited speech rather than an unbroken simulated recording.
## Use the tested Speaker Kit when its shape fits
@@ -65,7 +65,7 @@ See [Generated video direction](../craft/video-direction.md) for listeners, gest
## Let speech and graphics do different work
-Write natural stages in Script. For newly generated Takes, estimate each Segment before choosing a
+Write natural stages in Script. For newly generated clips, estimate each Segment before choosing a
literal generation duration. When the work retains recorded speech, its edited delivery supplies
the actual duration; [media preparation](../../production/media.md) explains how to prepare and
align it. A Segment can contain several edited shots, Caption Cue Breaks, graphic changes and
diff --git a/skills/hypit/references/playbooks/formats/two-person-podcast.md b/skills/hypit/references/playbooks/formats/two-person-podcast.md
index 91b2eb02..db0591ea 100644
--- a/skills/hypit/references/playbooks/formats/two-person-podcast.md
+++ b/skills/hypit/references/playbooks/formats/two-person-podcast.md
@@ -33,7 +33,7 @@ Source.
[Podcast and interview image examples](../craft/examples/conversation-images.md) preserve the
concrete English production directions and explain what each reference is responsible for.
-## Direct conversation inside a Take
+## Direct conversation inside a generated clip
`podcast-v1` takes two final camera views and two voices, in matching A/B order. Map the Script's
actual Role names to those hosts explicitly in action direction. Script remains the sole dialogue
@@ -76,9 +76,9 @@ toward him as she listens. She remains silent. Let both panels feel like the sam
already underway, without large gestures or a frozen listener.
```
-The split reference and its matching video direction form one authored opening Take that can carry
+The split reference and its matching video direction form one authored opening clip that can carry
both people and a speaker change. The ordinary two-view Podcast Kit suits the later exchange. Use a
-split-screen opening when that attention device serves the work; use another component or Take shape
+split-screen opening when that attention device serves the work; use another component or request shape
for a different layout.
## Coverage can follow a thought rather than every noun
diff --git a/skills/hypit/references/production/audio-clips.md b/skills/hypit/references/production/audio-clips.md
index ac0ba2ac..e5cb2297 100644
--- a/skills/hypit/references/production/audio-clips.md
+++ b/skills/hypit/references/production/audio-clips.md
@@ -1,57 +1,52 @@
# Place sound through Audio Track
Read this for normalized speech, music, ambience and effects. [Sound direction](../playbooks/craft/sound-mix.md)
-owns the mix judgment; this page owns the plain author relation.
+owns mix judgment; this page owns the ordinary author relation.
-## The ordinary relation is one Clip occurrence
+## Place one ordinary Clip occurrence
```text
-Audio Clip = normalized audio source + absolute Window + sampling + mix
+Audio Clip = normalized audio source + absolute Window + source-time + mix
Audio Track = additive set of Audio Clips
```
```svml
+<time:Window id="reveal-hit-window" timeline={program.timeline}
+ from={story-time.reveal} for="600ms"/>
+
<audio:Track id="mix" timeline={program.timeline}>
<audio:Clip id="voice" source={speaker-media.media} during={program.speaker}/>
- <audio:Clip id="music" source={music-media.media} during="timeline"
+ <audio:Clip id="music" source={music-media.media} during={program.window}
gain="0.18" fade-in="12f" fade-out="18f">
<audio:Map target-at="end" source-at="end" rate="1"
wrap-from="start" wrap-until="end"/>
</audio:Clip>
<audio:Clip id="reveal-hit" source={hit-media.media}
- from={story-time.reveal} for="600ms" gain="0.45" fade-out="3f"/>
+ during={reveal-hit-window} gain="0.45" fade-out="3f"/>
</audio:Track>
```
-Speech, music, ambience and effects are equal Clips. `during` consumes an absolute Window or the
-complete Timeline. The alternate form supplies exactly two of `from`, `until` and `for`. Semantic,
-beat or other coordinates must first be projected to ordinary Instants or Windows by their owner.
+Speech, music, ambience and effects use the same Clip form. `during` accepts a named absolute Window;
+Timeline authoring or a domain projector creates it upstream.
-Timeline contribution and audio placement are separate relations. A source that supplied unknown
-duration earlier leaves no marker here; the Clip explicitly chooses whether its sound is heard.
-Using the same normalized source in two Clips creates two independent occurrences.
+A source can determine Timeline duration and still require an explicit Audio Clip before its sound
+is heard. Reusing the same source in two Clips creates two audible occurrences.
-## Sampling and mix stay explicit
+## Keep sampling and mix explicit
-Omission means bounded partial identity: target start maps to source start at native rate and excess
-Window time is silent. `Map` children express other relations with target/source bounds, paired
-anchors and an exact positive rate. `wrap-from`/`wrap-until` makes a source interval periodic. A Map
-without rate, anchors or wrap fits its source interval into its target interval while preserving
-pitch; optional `min-rate`/`max-rate` bounds make an unsafe fit fail. Multiple non-overlapping Maps
-form one piecewise relation and gaps stay silent.
+Omission uses bounded native playback from source start; source that ends before the Window leaves
+silence. `audio:Map` expresses target/source bounds, paired anchors, rate and optional periodic wrap.
+A fit Map stretches its source interval over its target while preserving pitch; `min-rate` and
+`max-rate` can bound the accepted change. Multiple non-overlapping Maps form one piecewise relation.
-`gain` is a linear multiplier; fade lengths default to zero and remain measured against the whole
-Clip Window even when source-time has several pieces. Overlapping Clips mix as peers. Audio Track
-does not extract streams, normalize files, infer ducking, choose a bus or apply a last-source-wins
-rule.
+`gain` is a linear multiplier. Fade lengths apply to the whole Clip Window. Overlapping Clips mix as
+peers.
-## Relationships spanning Clips are components
+## Put shared behavior in a component
-Audio Track has no generic Presentation, Style or Use. Ducking, crossfades, speaker handoffs and
-other behavior spanning several Clips belong to a project or reusable author component. It may
-calculate envelopes or publish its own terminal `AudioTrack`; Core and Film still see an ordinary
-audio contribution.
+Ducking, crossfades, speaker handoffs and other behavior spanning several Clips belong to a project
+or reusable component. It can calculate envelopes or publish its own AudioTrack for Film.
-Audio Track emits `.audio` and `.program`. Film includes `.audio` explicitly. Using synchronized
-media in [Visual Track](visual-clips.md) does not make its sound audible, and using its audio does not
-reveal its picture. Avoid routing the same voice through two selected audio contributions.
+Audio Track publishes `.audio` for Film and `.program` for declared tooling. Film includes audio
+outputs explicitly. Using synchronized media in [Visual Track](visual-clips.md) does not select its
+audio, so include one intended voice path and avoid accidental duplication.
diff --git a/skills/hypit/references/production/authoring.md b/skills/hypit/references/production/authoring.md
index 305b79b6..c7b8b275 100644
--- a/skills/hypit/references/production/authoring.md
+++ b/skills/hypit/references/production/authoring.md
@@ -40,10 +40,10 @@ with [motion graphics](../playbooks/craft/motion-graphics.md) for changes within
These pages establish what the authored relationship should accomplish. Installed vocabulary then
supplies the exact language for expressing it.
-For a performance-led work, including pure A-roll or short drama, prefer Script and semantic
-preparation even when the presentation is simple. Preserve the actual event relationships when
-additional Caption, sound or visual direction is introduced. A standalone asset edit can instead
-end at its requested media Output.
+For a performance-led work, including pure A-roll or short drama, keep the intended passages in
+Script and let accepted media establish their actual extent. Add semantic preparation when Caption,
+sound or visual relationships need positions inside that performance. A standalone asset edit can
+instead end at its requested media Output.
Author those relationships explicitly. Script Selections and Moments carry meaning through placed
performances into real time; authored positions locate independently timed events on the same Timeline.
@@ -105,7 +105,7 @@ imports select author vocabulary; Runtime configuration selects external facilit
A Target marks where this Run asks the graph to become real. For ordinary commissioned production,
the demanded Output is usually the finished video, and the Build produces its required media
-dependencies through the same graph. A public image, Take, audio item, or other intermediate Output
+dependencies through the same graph. A public image, prepared video, audio item, or other intermediate Output
is also a normal Target when the user requested that deliverable or the work genuinely needs it
independently now.
@@ -194,7 +194,7 @@ Do not satisfy a changed Track or final composition with its old rendered Output
the current edit. Type compatibility alone cannot establish that an old performance or timing still fits.
After a person or product swap, review existing Candidate selections against the new target. A Run
-that still selects the old presenter's Take will keep that person on screen even after the image
+that still selects the old presenter's video will keep that person on screen even after the image
prompt changes. Preserve unrelated work while selecting or generating the media the adaptation needs.
For example, correcting three wrong B-roll selections means replacing those selections while keeping
diff --git a/skills/hypit/references/production/browser-capture.md b/skills/hypit/references/production/browser-capture.md
index 625f86f0..49893c62 100644
--- a/skills/hypit/references/production/browser-capture.md
+++ b/skills/hypit/references/production/browser-capture.md
@@ -107,6 +107,6 @@ placing it in the composition.
Keep captures in project assets and record the source page and its purpose in the project notes.
An image enters through `media:Image`; a recording enters through `media:Video` and the ordinary
[normalization path](media.md). Place them with
-[Media presentation](visual-clips.md#keep-display-time-and-source-playback-distinct) and the Script's
+[Visual Clips](visual-clips.md#keep-destination-time-and-source-sampling-distinct) and the Script's
Selections or Moments as appropriate. Their visibility, crop, scroll and transitions belong to the
composition, so those changes can reuse the captured file.
diff --git a/skills/hypit/references/production/caption-authoring.md b/skills/hypit/references/production/caption-authoring.md
index 4beb7bf7..33e83d0d 100644
--- a/skills/hypit/references/production/caption-authoring.md
+++ b/skills/hypit/references/production/caption-authoring.md
@@ -52,9 +52,9 @@ and evaluate its state at the requested frame. Keep separately useful overlays a
```text
Script → CaptionDocument (displayed words, Cue breaks and word attributes)
NarrativeCaptionBinding + NarrativeProjection → CaptionTiming
-CaptionDocument + CaptionTiming → complete timed Cues and original word times
Track Uses → resolved time windows, Styles and optional speaker filters
-complete Cues + Uses + family parameters → family schedule → VisualTrack
+CaptionDocument + complete unit Timing + Uses + family parameters
+ → family-owned Cues and schedule → VisualTrack
```
Consume each display word's `separatorBefore` with its `text`; never rebuild wording by joining
@@ -63,10 +63,11 @@ a displayed Cue/line. Use the same authored boundaries in base glyphs, active la
Separators are display content, not timed Tokens.
Use `@hypit/hypit/caption` for content timing and Use coverage, and `@hypit/hypit/narrative` for
-Script document types. A family Track accepts `document`, `timeline` and ordered `Use` children:
+Script document types. A family Track accepts `document`, resolved `timing`, `timeline` and ordered
+`Use` children:
```svml
-<keyword:Track id="captions" document={story.caption} timeline={program.timeline}>
+<keyword:Track id="captions" document={story.caption} timing={story-captions} timeline={program.timeline}>
<keyword:Use style={base-style}/>
<keyword:Use role="GUEST" style={guest-style}/>
<keyword:Use during={story-time.punchline} style={punchline-style}/>
@@ -96,10 +97,11 @@ Its layout then computes the two groups together. Decide what happens with no ke
keywords, long text and an N:M pronunciation span. Make author correction possible through word
attributes, `||` and Style configuration instead of inventing missing text or dropping words.
-The common projection respects authored Cue breaks and structural boundaries. Visual line wrapping
-is a separate operation. A narrow width should not silently rewrite the Script into new spoken Cues.
-If the family needs an additional grouping rule, give that rule explicit parameters and preserve the
-original word/unit associations in the schedule.
+The projection publishes every complete Unit's absolute boundaries and does not form Cues. The
+family schedule respects authored Cue breaks and structural boundaries while forming its readable
+groups. Visual line wrapping is a separate operation. A narrow width should not silently rewrite the
+Script into new spoken Cues. If the family needs an additional grouping rule, give that rule explicit
+parameters and preserve the original word/unit associations in the schedule.
Display Words reflect Script's lexical units: a Han character is normally one Word, while an
English word is normally one Word. Keep that timing granularity separate from visual grouping.
diff --git a/skills/hypit/references/production/caption-presentation.md b/skills/hypit/references/production/caption-presentation.md
index 4e35fc09..ffea94b0 100644
--- a/skills/hypit/references/production/caption-presentation.md
+++ b/skills/hypit/references/production/caption-presentation.md
@@ -4,21 +4,22 @@ Read this to apply subtitle treatments, change them during a passage, or hide th
[Caption craft](../playbooks/craft/captions.md) owns visual direction;
[Caption authoring](caption-authoring.md) explains creating a new family.
-**Script organizes content; Use organizes presentation in time.** `||` determines which words belong
-together. An upstream adapter resolves the document's unit timing once; the Track consumes that
-`CaptionTiming` without knowing whether it came from Narrative, SRT/VTT or authored absolute time.
-Each Use selects a complete Style inside an already resolved time window.
+**Script organizes content; the family forms Cues; Use organizes presentation in time.** `||` gives
+the family a hard content break. An upstream adapter resolves every document Unit's timing once; the
+Track consumes that flat `CaptionTiming` without knowing whether it came from Narrative, SRT/VTT or
+authored absolute time. Each Use selects a complete Style inside an already resolved time window.
```svml
<caption:Hidden id="hidden"/>
<narrative-caption:Timing id="story-captions" document={story.caption}
binding={story.caption-binding} projection={story-time.projection}/>
+<time:Window id="impact-window" timeline={program.timeline} from="12s" for="2s"/>
<caption-fine:Caption id="captions" document={story.caption} timing={story-captions} timeline={program.timeline} within={canvas.bounds}>
<caption-fine:Use style={base-style}/>
<caption-fine:Use role="GUEST" style={guest-style}/>
<caption-fine:Use during={answer-window} style={answer-style}/>
<caption-fine:Use during={demonstration-window} style={hidden}/>
- <caption-fine:Use from="12s" for="2s" style={impact-style}/>
+ <caption-fine:Use during={impact-window} style={impact-style}/>
</caption-fine:Caption>
```
@@ -33,8 +34,8 @@ caption can use a project family with its own layout and behavior.
| Follow a semantic passage | Project it once, then `during={answer-window}` |
| Follow a placed Segment | Project it once, then `during={answer-window}` |
| Start at a meaningful word, for a fixed duration | Project it once, then use the resolved Window |
-| End at a meaningful event | Project it once, then `until={story-time.key} for="12f"` |
-| Explicit window | `from="8s" until="10s"` |
+| End at a meaningful event | Declare a named Window from that event, then consume it |
+| Explicit window | Declare it once with `time:Window`, then `during={named-window}` |
| A particular speaker | Add `role="GUEST"` to any of these |
[Timing](timing.md) owns the shared expressions and semantic references.
diff --git a/skills/hypit/references/production/component-visuals.md b/skills/hypit/references/production/component-visuals.md
index ad051d16..97a14046 100644
--- a/skills/hypit/references/production/component-visuals.md
+++ b/skills/hypit/references/production/component-visuals.md
@@ -147,5 +147,4 @@ these independently; the Producer receives a Window and an Instant. The installe
moves from full screen to a side viewport while a diagram enters, with Caption available as a peer.
The HTML visual format belongs to the renderer package. `hypit.html-visual@1` runs in the
-HTML renderer browser; another renderer implements the formats it supports. Core still schedules
-ordinary Needs and has no knowledge of scenes, video windows or browser layout.
+HTML renderer browser; another renderer implements the formats it supports.
diff --git a/skills/hypit/references/production/fonts-and-text.md b/skills/hypit/references/production/fonts-and-text.md
index bf494329..c0c26278 100644
--- a/skills/hypit/references/production/fonts-and-text.md
+++ b/skills/hypit/references/production/fonts-and-text.md
@@ -105,9 +105,9 @@ The following excerpt assumes the named Fonts, layout Frames, Timeline and Recip
```
Include `opening-title.visual` in Film. The Style supplies reusable typography and Paint; the
-occurrence supplies content, placement, form-specific layout, layer order and absolute time. Use `during="timeline"` for a title that
-lasts throughout the program, a named Timeline Window such as `speech.opening`, or the
-component's direct `at/for`, `until/for` and `start/end` forms for a shorter appearance. A semantic
+occurrence supplies content, placement, form-specific layout, layer order and absolute time. Use the
+Timeline's named full Window for a title that lasts throughout the program, or another named Window
+such as `speech.opening` for a shorter appearance. A semantic
or musical domain projects its own evidence to a Window before a fine-text occurrence consumes it.
For the example above, `look.text.title` can be the Recipe
diff --git a/skills/hypit/references/production/image-operations.md b/skills/hypit/references/production/image-operations.md
index 2fbee11c..7882a077 100644
--- a/skills/hypit/references/production/image-operations.md
+++ b/skills/hypit/references/production/image-operations.md
@@ -67,10 +67,10 @@ Use correction to express a known production choice. A prompt problem remains ow
direction and its Prompt Kit; a different composition remains owned by the shot or reference
relationship.
-## Keep operation and presentation distinct
+## Keep operation and Clip use distinct
-Composing or correcting image bytes changes the reusable image itself. A Visual Clip instead places
-an image in a Frame for a Window and may animate that presentation. Choose the former when several
+Composing or correcting image bytes changes the reusable image itself. A Visual Clip places
+an image in a Frame for a Window and may animate that occurrence. Choose the former when several
downstream consumers should receive the same prepared pixels; choose the latter when the change
belongs only to how this video presents the image.
diff --git a/skills/hypit/references/production/index.md b/skills/hypit/references/production/index.md
index 3ef5d83a..907392cd 100644
--- a/skills/hypit/references/production/index.md
+++ b/skills/hypit/references/production/index.md
@@ -4,10 +4,11 @@ Enter at the question the current work raises. These groups locate knowledge; th
that every task must complete. [System relationships](system.md) explains the common model.
Creation and the relevant [Format/Craft](../playbooks/index.md) supply the creative decisions.
-For performance-led work, including pure A-roll and short drama, prefer Script plus normalized media
-and NarrativeAlignment. Place each local domain in Timeline, project its semantic boundaries, then
-present explicit placed picture and sound through Visual and Audio Tracks. Caption and other
-contributions join where useful. Semantic organization remains valuable even with no MG.
+For performance-led work, including pure A-roll and short drama, author the intended passage in
+Script and let accepted normalized media establish its real extent. Place that extent in Timeline,
+then present explicit picture and sound through Visual and Audio Tracks. Add NarrativeAlignment when
+Caption, semantic timing or another consumer needs positions inside the performed passage. Semantic
+organization remains valuable even when no consumer needs word-level timing or MG.
For a standalone asset edit, follow the actual material operation and deliver its output.
## Express the work
diff --git a/skills/hypit/references/production/media.md b/skills/hypit/references/production/media.md
index 8ba49d81..dc394eb6 100644
--- a/skills/hypit/references/production/media.md
+++ b/skills/hypit/references/production/media.md
@@ -1,7 +1,7 @@
# Preparing media for a production
Read this when admitting files, connecting generated media, choosing streams, or editing a clip
-before using it in a component or a model reference. [Media presentation](visual-clips.md)
+before using it in a component or a model reference. [Visual Clips](visual-clips.md)
owns independent picture placement and playback; [Tracks](tracks.md) routes other content relationships.
For a source video at a link, read [video download](video-downloads.md).
For acquiring website screenshots, page recordings or local HTML graphics, read
@@ -9,7 +9,7 @@ For acquiring website screenshots, page recordings or local HTML graphics, read
## Choose preparation from the intended use
-Keep source facts, preparation and presentation distinct:
+Keep source facts, preparation and use distinct:
| Material or use | What the next consumer needs |
| --- | --- |
@@ -62,12 +62,14 @@ hypit media cut assets/voice.wav --keep 0.3:4.1 --keep 4.6:9.2 --to assets/narra
The first form retains one interval; repeated `--keep` joins selected parts of the *same* recording.
The command keeps existing audio and picture together and can write an ordinary MP4 or audio-only
WAV. Import that output as `asset:Video` or `asset:Audio` for its intended use. If the edited
-delivery is a Script performance, normalize it and align its local domain as described below.
-Independent footage can instead enter Media or another visual component, with source sound included
+delivery is a Script performance, normalize it; align its local domain when another contribution
+needs positions inside that performance, as described below.
+Independent footage can instead enter a Visual Clip or another visual component, with source sound included
when the work needs it. A file cut does not choose Script or Segment boundaries. The installed Video
CLI README owns exact options and output behavior. `hypit transcribe` accepts either audio or video
when a transcript helps inspect the recording; its word times refer to that input file, while a
-retained edited performance receives its own semantic alignment in the Build.
+retained edited performance receives its own semantic alignment in the Build when the composition
+consumes that timing.
An image reference can enter a model directly. A still placed as a Visual Clip needs its actual
IntrinsicExtent as well. Inspect its dimensions with `hypit media probe <file>` and declare them
@@ -92,7 +94,7 @@ The following excerpt prepares a performance and an independent soundtrack:
```
The Clock is an authored rate; the prepared media supplies the resulting length. Share the Clock
-across Takes that will join one program.
+across media that will join one program.
- `video` selects the moving-picture stream, or `none` for audio-only material.
- `audio` selects the embedded audio, or `none` when the material should carry no sound.
@@ -107,9 +109,10 @@ with an exact local frame count, optional picture and optional audio on the chos
prepared as a 48 kHz render stem with its level preserved. Balance, fades and music ducking remain
mix decisions in [Audio Track and sound mix](../playbooks/craft/sound-mix.md).
-## Associate a performance with Script
+## Associate a performance with Script when its timing is consumed
-For performance-led work, Script preserves wording and meaningful events while alignment locates
+Script preserves wording and meaningful events for performance-led work. When Caption, semantic
+picture changes, sound events or another consumer needs their actual positions, alignment locates
them on the accepted media's local domain:
```svml
@@ -140,10 +143,14 @@ semantic projection:
After projection, picture and sound use the ordinary normalized media with explicit absolute Windows.
They do not retain or inspect this semantic relation. Audio-only A-roll uses the same projection chain
-without a dummy picture. A wordless Segment can align directly to its local
-domain boundaries without transcription; it contributes the real Segment start/end identities and
-no Tokens. A silent action inside that passage needs its own authored or measured event if another
-component must respond to it.
+without a dummy picture.
+
+## Project a wordless Segment when its identity is consumed
+
+A wordless Segment can align directly to its complete local domain without transcription when a
+consumer needs that Segment's boundaries. The alignment contributes the real Segment start/end
+identities and no Tokens; the media Extent can construct Timeline without it. A silent action inside
+that passage needs its own authored or measured event if another component must respond to it.
## Give a still a duration when that is its role
@@ -177,7 +184,8 @@ is assigned by the downstream Source relationships just like any other video.
Transform applies its operations in order. These Outputs are Blobs; normalize an edited
clip again when feeding it into a prepared-media input, and realign the edited performance when its
-timing changed. Extracted audio or a frame can directly feed a compatible model reference port.
+timing changed and downstream consumers use that alignment. Extracted audio or a frame can directly
+feed a compatible model reference port.
`ExtractFrame` also accepts `first`, `frame:<index>` and `time:<seconds>`.
Use graph operations for repeatable preparation belonging to the production. `hypit media` commands
@@ -188,11 +196,11 @@ the operation that matches the asset's intended use.
## Keep original and processed material explicit
A crop, background removal or flattened composite produces a selected asset. Normalization prepares
-that output; it does not make original pixels recoverable through another presentation Style. A
-transparent video enters the same normalization and presentation paths as opaque video. A circular clip or
-rounded Frame instead masks presentation geometry; it does not remove the source background.
+that output; retain the original whenever the production may still need its pixels. A transparent
+video enters the same normalization and Visual Clip path as opaque video. A circular Clip or
+rounded Frame instead masks Clip geometry; it does not remove the source background.
-When original and processed pictures both appear, retain both and bind each as an explicit media
+When original and processed pictures both appear, retain both and connect each as an explicit media
input. If a picture-only transformation preserves the same frame correspondence, a project
preparation component may reuse the accepted local domain and alignment while publishing a new
visual source. This is an authored relation, never automatic variant inheritance.
@@ -213,9 +221,10 @@ preserves input alpha, while its Transform emits opaque MP4. When using that Tra
or retiming a cutout performance, perform it before matting. Read the selected operation's output
behavior rather than assuming every video operation preserves transparency.
-Trimming, retiming or replacing the performance changes the temporal relation and requires a new
-local domain and timing prepared for that result. [Reuse boundaries](authoring.md#reuse-produced-work-explicitly)
-explain which completed Output can remain selected.
+Trimming, retiming or replacing the performance changes its local temporal relation and requires a
+new local domain. Prepare new semantic timing as well when downstream consumers use it.
+[Reuse boundaries](authoring.md#reuse-produced-work-explicitly) explain which completed Output can
+remain selected.
Choose source proportions and framing for the actual footage the work needs. A full-frame spoken
piece can start from the final aspect ratio; a later inset or split does not dictate the generated
diff --git a/skills/hypit/references/production/prompt-kits.md b/skills/hypit/references/production/prompt-kits.md
index 15986f6e..ea92d108 100644
--- a/skills/hypit/references/production/prompt-kits.md
+++ b/skills/hypit/references/production/prompt-kits.md
@@ -1,7 +1,7 @@
# Choosing and authoring Prompt Kits
Read this when choosing a reusable prompt treatment, assembling its Text inputs, or preserving useful
-direction in a new Kit. A Kit can preserve proven wording even for one image or Take. Ordinary
+direction in a new Kit. A Kit can preserve proven wording even for one image or passage. Ordinary
`text:Value` elements carry the parts authored specifically for the current work.
A Prompt Kit is a data-only TextTemplate Source. It owns reusable wording and meaningful choices;
diff --git a/skills/hypit/references/production/rendering.md b/skills/hypit/references/production/rendering.md
index 122e852d..0128ce8b 100644
--- a/skills/hypit/references/production/rendering.md
+++ b/skills/hypit/references/production/rendering.md
@@ -35,27 +35,30 @@ Layer order is authored in the Visual Tracks' Presents, so moving these Film chi
reorder the picture.
`main.composition` is the assembled work, usable in Studio. `final.video` asks for an encoded video.
-A compatible Composition from another component can also feed the render Surface. Pure A-roll may
+A compatible Composition from another component can also feed the HTML Video Surface. Pure A-roll may
need only one Visual Clip and one Audio Clip, with Caption when wanted. Additional coverage
and graphics in this excerpt illustrate optional independent contributions.
## Compose an authored animation
A Film needs a time axis, whether or not it contains speech or prepared media. For a speech-led piece,
-continue to pass `timeline={speech.timeline}`: it provides both the real performance time and the
+continue to pass `timeline={speech.timeline}`: it provides both the complete film time and the
context in which Tracks resolve Script references. For a pure MG piece, author a Timeline with an
-explicit end and pass it to the components, Film and Render:
+explicit end and pass it to the components, Film and HTML Video:
```svml
<import as="time" from="@hypit/timeline-author@1"/>
<time:Clock id="animation-clock" frame-rate="30"/>
-<time:Timeline id="animation" clock={animation-clock} end="8s"/>
+<time:Timeline id="animation" clock={animation-clock} end="8s">
+ <time:Instant id="question" at="0.5s"/>
+ <time:Instant id="answer" at="2s"/>
+</time:Timeline>
<!-- conversation is the project's own visual component. -->
<chat:Scene id="conversation" timeline={animation.timeline} within={canvas.bounds} font={font}
- during="timeline" title="Launch crew">
- <chat:Message id="question" sender="Maya" side="left" at="0.5s" text="Ready?"/>
- <chat:Message id="answer" sender="Leo" side="right" at="2s" text="Let's go."/>
+ during={animation.window} title="Launch crew">
+ <chat:Message id="question" sender="Maya" side="left" at={animation.question} text="Ready?"/>
+ <chat:Message id="answer" sender="Leo" side="right" at={animation.answer} text="Let's go."/>
</chat:Scene>
<film:Film id="main" canvas={canvas.canvas} timeline={animation.timeline} appearance={look.film.main}>
<film:Track source={conversation.visual}/>
diff --git a/skills/hypit/references/production/review.md b/skills/hypit/references/production/review.md
index 0e860790..21aa6dd6 100644
--- a/skills/hypit/references/production/review.md
+++ b/skills/hypit/references/production/review.md
@@ -58,11 +58,11 @@ a person actually moves and speaks. A working preview can support either discuss
current scope clear so the user can give useful direction, and continue the remaining work within
the agreed commission. [Service selection](../environment/model-and-provider.md#choose-the-practical-capability-path-with-the-user) owns unresolved service choices.
-Read missing behavior through its material and presentation together. For intended speech, listen to
+Read missing behavior through its material and use together. For intended speech, listen to
the selected Film: an available audio file establishes material, while admission and the chosen
Audio contribution establish whether that material reaches the Film. For intended physical
action, examine the footage itself as well as the viewport animation. Use
-[media admission](media.md), [sound presentation](audio-clips.md) and [Film assembly](rendering.md)
+[media admission](media.md), [Audio Clips](audio-clips.md) and [Film assembly](rendering.md)
to complete those relationships. Silence or stillness can equally be intentional when they serve the Brief.
Look at the complete Film at its intended delivery size as well as the components inside it. A component that looks
@@ -97,7 +97,7 @@ media supplies that evidence.
Inspect the relationships that make the composition work:
- **performance** — the selected footage actually contains the intended speech, action and reaction;
- presentation motion does not substitute for missing action in the material;
+ Clip or component motion does not substitute for missing action in the material;
- **picture and coverage** — B-roll supports the passage and its display window carries the intended
explanation or handoff;
- **semantic timing and motion** — cuts, Caption Cues, MG states and Effects occur on the
diff --git a/skills/hypit/references/production/runs.md b/skills/hypit/references/production/runs.md
index d8e0b839..a7a4bac1 100644
--- a/skills/hypit/references/production/runs.md
+++ b/skills/hypit/references/production/runs.md
@@ -44,7 +44,7 @@ not Run declarations.
</svrun>
```
-Replace `bld_...` with the actual Build id found through Results. The historical `output` is the
+Replace `bld_...` with the actual Build id found through Results. The `output` from the earlier Result is the
name in that Result; the `satisfy output` is the current Author Output. These selections preserve
media, its duration and its NarrativeAlignment without pretending they are one compound object.
A changed Caption or MG can then recompute downstream. Marker and display-only edits may also
@@ -67,7 +67,7 @@ A file can replace a byte-producing Output:
Here the file replaces the generated video bytes. Normalization and alignment still follow it.
Selecting completed normalized media, local-domain and alignment Outputs preserves those facts
-without preserving their later Timeline placement or presentation. Choose the Outputs whose meaning
+without preserving their later Timeline placement or Visual/Audio Clip use. Choose the Outputs whose meaning
matches what should stay; the receiving Type identifies which kind of value fits each position.
## Use a Fragment when a Candidate needs computation
diff --git a/skills/hypit/references/production/script-syntax.md b/skills/hypit/references/production/script-syntax.md
index 6d4c41be..ca2d00ce 100644
--- a/skills/hypit/references/production/script-syntax.md
+++ b/skills/hypit/references/production/script-syntax.md
@@ -45,7 +45,7 @@ A Script contains one or more uniquely named Segments matching `[a-z][a-z0-9_-]{
carries a wordless passage. A Role Cue is a bare turn marker: the next Role Cue begins the next turn,
and closing the Segment ends the final turn
and resets its Role. When a Segment uses Roles, place the first Role before that Segment's first
-spoken text. One Segment can contain several Role turns without requiring several generated Takes. A bare tag
+spoken text. One Segment can contain several Role turns without requiring several generated clips. A bare tag
inside a Segment is a Role Cue by context, not by capitalization: `<host>`, `<主持人>` and
`<진행자>` can name speakers. The label directs the request through dialogue; it selects no voice
or character asset by itself.
diff --git a/skills/hypit/references/production/spatial.md b/skills/hypit/references/production/spatial.md
index 0081cbc2..81bf6b53 100644
--- a/skills/hypit/references/production/spatial.md
+++ b/skills/hypit/references/production/spatial.md
@@ -11,14 +11,14 @@ the destination geometry for Visual Clips and project scenes alike.
The Canvas gives the final image's pixel dimensions. The shared `@1` picture-plane convention gives
the coordinate basis. Introduce Frames and
component scopes where they help organize the picture; they need not tile the canvas or remain
-separate rectangles. Components can overlap, share motion and own local trees. Canvas itself does
-not contain a central list of layers. Each rendered Present supplies its own paint order.
+separate rectangles. Components can overlap, share motion and own local trees. Each visual
+contribution publishes Presents with its own paint order.
An IntrinsicExtent gives a source image's actual dimensions. A Frame gives the destination rectangle
a consumer should occupy. A landscape image can retain its real extent while appearing in a portrait
composition. An A-roll source has no prescribed Frame or crop. For performance remaining mostly
full-screen, its intended final aspect can guide source direction; later insets or splits remain
-presentation choices. Translate required source framing into visible camera facts before generation.
+visual placement choices. Translate required source framing into visible camera facts before generation.
```svml
<import as="space" from="@hypit/spatial@1"/>
@@ -59,8 +59,8 @@ Visual Clips keep three different spatial facts separate:
- A **SpatialMap2D** maps positions from that local plane into the program picture plane.
- The destination **Frame** owns the Clip's outer treatment and clipping boundary.
-There is no second authored “content Frame”. Ordinary `fit` controls are a concise way to derive the
-SpatialMap2D after the source Extent and Clip Frame are both known. The resolved Visual Program keeps
+Ordinary `fit` controls derive the SpatialMap2D after the source Extent and Clip Frame are both
+known. The resolved Visual Program keeps
that mapping, not a parallel fitted rectangle. A still image therefore needs an Extent; prepared
moving media and compositable Surfaces already carry their dimensions. Border and padding produce a
deterministic inset used by the fit calculation, rather than another independently authored Frame.
@@ -68,7 +68,7 @@ deterministic inset used by the fit calculation, rather than another independent
For example, with no border or padding, a `1600 × 900` image fitted into a `600 × 600` Frame becomes
`600 × 337.5` under `contain`, leaving room above and below when centered. Under `cover`, it becomes
about `1066.7 × 600`; a frame clip shows the middle square. Moving the destination moves the whole
-presentation; changing content alignment changes which part of that image occupies the square.
+Clip; changing content alignment changes which part of that image occupies the square.
Choose ordinary fitting directly on the Clip:
@@ -165,7 +165,7 @@ the frame's paint and decoration have their own appearance.
## Move the frame or move its contents
-A typed `Motion` moves or fades the complete framed presentation, including its border and paint.
+A typed `Motion` moves or fades the complete framed occurrence, including its border and paint.
`Sampling` children pan, zoom or rotate the mapped picture under that frame. Use Sampling
for a moving crop or a slow push-in while a card's outline stays still:
@@ -184,19 +184,17 @@ degrees, and `at` follows the source unit's active span from `start` to `end`, w
intermediate keys. Sampling acts after the resolved static mapping; its movement can expose space inside the
Frame. Choose the crop and motion together for the intended coverage.
-[Visual Track](visual-clips.md) places explicit footage through Clips. A scene that
+[Visual Track](visual-clips.md) places explicit footage through Clips and owns their source-time
+inputs. Read its installed vocabulary for complete appearance and motion fields. A scene that
coordinates the viewport with surrounding graphics can own the shared motion in its
[component program](component-visuals.md#compose-video-and-graphics-in-one-html-visual).
-[Visual Track](visual-clips.md) owns its content and source-time inputs. Read its installed
-vocabulary for complete appearance and motion fields.
-
## Carry measured regions through explicit peer evidence
Region Evidence contains already prepared boxes indexed by Timeline Frame. It is not part of static
Spatial geometry. Its Recipe uses normalized `[x, y, width, height]` boxes and `null` for absent
measurements, resolved inside an explicit Frame. Source-local measurements need their actual time
-placement and the source-to-picture mapping produced by the real presentation before they can
+placement and the source-to-picture mapping used by the actual visual occurrence before they can
position text correctly.
[Caption tracking](../playbooks/craft/caption-tracking.md) explains producing and applying head
diff --git a/skills/hypit/references/production/studio-companions.md b/skills/hypit/references/production/studio-companions.md
index 815d4376..06761f89 100644
--- a/skills/hypit/references/production/studio-companions.md
+++ b/skills/hypit/references/production/studio-companions.md
@@ -19,7 +19,7 @@ AudioTrack entities are enough for ordinary Clip occurrences. Use `project(conte
domain meaning that the terminal drawing no longer contains. A Surface preview supplies a useful
static recognition image; live entities and editable bindings come from the Companion.
-Generic presentation recognizes the terminal Type, not the component's creative role. A custom
+Generic Studio projection recognizes the terminal Type, not the component's creative role. A custom
Caption can therefore render correct subtitles yet appear as a generic blue visual lane with
opaque ids when its package has no matching Companion. Inspect the selected Companion and its
Module/Surface match before treating this as misplaced content or moving visuals between Tracks.
@@ -65,7 +65,7 @@ bands: [{ id: "uses", placement: "after", heightPx: 15, display: "label" }]
```
Use `attachments` for independent child objects such as Ranking reveals. Use a Band for another
-aspect of the same Track such as its presentation choices. Both use ordinary entity selection,
+aspect of the same Track such as its appearance choices. Both use ordinary entity selection,
overlap order, field declarations and time editing. Each entity chooses one declared band or lane.
## Connect the picture to the entity
@@ -131,7 +131,7 @@ A Style can own its controls independently of the Track that consumes it. The Tr
`createStudioCompanionFacet({ parameters: [{ id, match: { module, surface }, bindings, inspector }] })`.
Its field names are local to that Style. Studio follows the reference and combines those fields
with the Use's time controls. This works for a new project motion Style as well as a familiar
-framed presentation. Shared Style edits continue to affect its other Uses.
+framed visual. Shared Style edits continue to affect its other Uses.
A binding's typed `fallback` exposes an omitted default; first editing it writes the property or
attribute into its owning source. A fallback function can express a dependent default from the
diff --git a/skills/hypit/references/production/studio.md b/skills/hypit/references/production/studio.md
index 884831f1..4dfb2fff 100644
--- a/skills/hypit/references/production/studio.md
+++ b/skills/hypit/references/production/studio.md
@@ -16,7 +16,7 @@ hypit studio --run build.svrun
Supply `--runtime <profile>` when intentionally using a different Profile from the project's
`hypit runtime use` selection. Studio needs a Run whose selected targets reach one Film with resolved
composition and time. The Timeline supplies the clock and any placed Script anchors for component
-lanes, including a pure animation with no Takes. An image-generation-only Run is not a Film view; several distinct
+lanes, including a pure animation with no performance clips. An image-generation-only Run is not a Film view; several distinct
Films need separate Runs or sessions.
Open the URL actually printed by the process and retain it with the Run it serves. For review, open
@@ -95,7 +95,7 @@ seconds, `text`, and optional `resolved` (false when omitted). For example:
The UI displays notes in time order; its `#` labels follow submission order within that Run. Identify
file edits by `id` and preserve the array order and unrelated entries. Clicking a note seeks to its
-saved time. Interpret that time with its words and the reviewed composition: changing Script or Take
+saved time. Interpret that time with its words and the reviewed composition: changing Script or media
placement can move the intended event. Comments retain the reviewed seconds rather than silently
following new semantic timing.
@@ -243,7 +243,7 @@ Composition edits return to the ordinary Sources; they do not create a second St
A Companion makes the component's own production relationships legible and editable: a board's
lifetime, a reveal event, a Cue's actual Style, or a scene's layout choices. Its Producers still own
-the rendered work. Generic Track presentation is useful when no additional authoring concepts are
+the rendered work. Generic Track projection is useful when no additional authoring concepts are
needed; a component with meaningful child events or controls can publish those directly.
Read [Companion authoring](studio-companions.md) for entities and child lanes, picture selection,
diff --git a/skills/hypit/references/production/system.md b/skills/hypit/references/production/system.md
index 7002b13b..cfe3e000 100644
--- a/skills/hypit/references/production/system.md
+++ b/skills/hypit/references/production/system.md
@@ -1,122 +1,104 @@
# How a Hypit production fits together
-Read this for the relationships among material, meaning, time, space, presentation and execution.
-[Production navigation](index.md) routes each current question to its detailed owner.
+Read this when deciding which relationship owns material, meaning, time, space, picture, sound or
+delivery. [Production navigation](index.md) routes each relationship to its detailed authoring page.
-The work has one finite Timeline and one Canvas. Neither is a container for the work's content.
-Attach events to their meaning; introduce component boundaries where content shares useful layout,
-state or motion. Semantic coverage need not fill time, and components need not partition Canvas.
+## Material becomes useful through explicit relationships
-## Materials acquire roles through use
+A supplied file, generated Output and reused Result can provide the same material Type. Normalize
+timed media to select its streams, establish a finite local temporal domain and publish its Extent.
+The work then decides how to use those facts.
-A supplied file, generated Output and reused Result can supply the same material Type. Normalization
-selects streams and establishes a finite local temporal domain. A model reference, performed passage,
-independent illustration and soundtrack are uses of material, not separate file classes.
-
-For performance-led work, Script names meaningful passages and events. `NarrativeAlignment` locates
-one Segment's boundaries on a local domain; it carries no picture or sound. `SynchronizedMedia`
-carries factual streams and no Script meaning. They may describe the same recording through separate
-graph edges.
+For spoken work, Script names meaningful passages and events. `NarrativeAlignment` locates one
+Segment on a source-local domain. The normalized medium independently supplies picture and sound.
+Their relationship is explicit, so the same recording can support semantic timing, visible picture
+and audible speech without becoming a special media class.
A-roll names the performance carrying a passage. Its picture may fill the frame, move, disappear or
-be absent; its sound may continue independently. That role does not choose a component type. A later
-replay may use the same bytes through another media occurrence without duplicating the semantic event.
-[Media preparation](media.md) owns these relations.
-
-## Timeline is the absolute execution coordinate
+be absent while its sound and semantic relationships continue. B-roll, generated shots, imported
+pictures, narration, music and effects use the same ordinary media values in their own roles.
+[Media preparation](media.md) owns admission, normalization and processed variants.
-Timeline is `{ id, frameRate, frameCount }`: one finite frame domain. Its author DAG resolves one
-exclusive `end` and naturally publishes its named Instants and Windows as sibling graph values.
-Timeline contains no Takes, media, semantic anchors, Track list or presentation rules.
+## Timeline publishes absolute time
-A local media Extent can determine a Window even when its length was unknown before generation.
-After finalization, a domain projector may map its complete local domain through an equal-length
-Timeline Window at native speed. It immediately emits absolute values instead of publishing a durable
-mapping object. Gaps, overlap and ranges with no material are valid. A wholly authored animation uses
-the same Timeline.
+Timeline supplies the work's finite frame domain and the named Instants and Windows the author wants
+to share. Its author graph can use known durations or Extents resolved after media generation.
-Meaning arrives through explicit adapters. A Narrative Projection combines declared
-`NarrativeAlignment + LocalTemporalDomain + Window` relations and resolves Script Selections or Moments to absolute
-Instants/Windows. Future beat, subtitle or motion domains can build peer adapters without adding event
-kinds to Timeline. Components consume the resulting absolute values; they do not reverse-search
-numeric coordinates for meaning. [Timeline](timeline.md) owns construction and [Timing](timing.md)
-owns projection and event expressions.
+Semantic timing is one source of absolute values. A Narrative projection combines Alignment, its
+local domain and an equal-length Timeline Window, then publishes the requested Selection, Moment or
+Segment boundaries as ordinary Instants and Windows. Musical beats and other local domains can offer
+parallel projectors. Components consume the resolved values.
-## Contribution does not classify media
+[Timeline](timeline.md) owns construction; [Timing](timing.md) owns choosing direct or projected time
+and the forms accepted by components.
-Timeline may consume a normalized source's Extent, and a semantic projector may consume its local
-domain. Those operations do not wrap or reclassify the media. Afterwards Visual and Audio each declare
-an independent occurrence from ordinary normalized media and an exact absolute Window.
+## Canvas publishes picture coordinates
-```text
-SynchronizedMedia + Window -> Visual Clip
-SynchronizedMedia + Window -> Audio Clip
+Canvas supplies the final dimensions and coordinate system. A Frame identifies a destination;
+SpatialMap2D identifies how source geometry reaches it. Components own the layout and motion shared
+by their internal objects, while independent visual contributions remain peers.
-NarrativeAlignment + LocalDomain + Window -> absolute Narrative time
-```
+Time, visual scope and paint order are separate choices. One scene can respond to several events,
+and several components can respond to the same event. [Spatial layout](spatial.md) owns geometry;
+[component design](component-design.md) owns useful visual scope.
-Visual and Audio Clips explicitly receive the sources they need. Timeline never supplies an
-implicit “all footage” query. Selecting picture does not select sound, and vice versa. Downstream
-consumers cannot tell whether a source previously helped construct Timeline.
+## Visual and Audio Clips place ordinary occurrences
-## Canvas is the picture coordinate
+A Visual Clip combines one picture source, an absolute Window, a destination Frame, paint order and
+source sampling. An Audio Clip combines one audio source, an absolute Window, source sampling and
+mix treatment. The same synchronized medium can feed both through separate explicit occurrences.
-Canvas supplies dimensions and coordinates. A Frame locates a destination; fitting maps source extent
-into it. Components own internal layout and motion. A presenter and diagram can share a scene while an
-independent title remains a peer.
+Keep three times distinct:
-Canvas is not an asset store or central layer tree. Each visual contribution publishes Presents with
-their own lifetimes, paint order and internal trees. Time authority and visual scope are independent:
-one scene may follow several semantic events, and several components may share one Moment.
-[Spatial layout](spatial.md) owns geometry; [component design](component-design.md) owns visual scope.
+- Timeline time locates the contribution in the film;
+- source time selects a media sample;
+- component-local time drives its visible state.
-## Visual and Audio Tracks own ordinary occurrences
+Behavior spanning several occurrences—such as a continuing presenter, slideshow, crossfade or
+ducking relationship—belongs to a component. It can publish ordinary VisualTrack and/or AudioTrack
+outputs for Film. [Tracks](tracks.md) routes ordinary Clips and richer components.
-Both base Tracks use the same small author algebra: a Track contains peer Clips. Each Clip combines
-one explicit source, one absolute destination Window and medium-owned sampling/treatment. Picture and
-sound retain separate physical Types and laws; there is no universal Track Type in Core.
+Caption is another peer relation: a document owns displayed text and hard breaks, CaptionTiming owns
+complete absolute Unit boundaries, and a Caption family owns Cue formation, visible scheduling and
+drawing.
-Behavior spanning Clips—continuing presenter identity, crossfades, ducking, replacement or richer
-layout—belongs to a project or reusable component. It may publish ordinary VisualTrack and/or
-AudioTrack outputs without adding effect kinds to the base Track grammar. [Tracks](tracks.md) routes
-these choices.
+## Give each part the direction it can realize
-Keep three times distinct: Timeline time locates the contribution, source time identifies the media
-sample, and local animation time determines presentation state. A source whose Window begins at second five is at
-source second two at program second seven only when an authored sampling relation says so. Every Clip
-declares its playback policy; Timeline placement never implies source sampling.
+Keep the whole creative intention in Treatment, then translate it into the facts each producer can
+realize. An image or video request needs visible subjects, setting, framing, action, camera behavior
+and reference roles. A voice request needs audible character, delivery and language. A component
+needs its content, Frame, events and the treatment choices its behavior exposes.
-Caption is a peer relation: a document owns displayed text, CaptionTiming owns resolved unit Windows,
-and a Caption family owns visual scheduling. Semantic speech is one possible timing source, not a
-Timeline requirement.
+Composition goals still guide these inputs: a generated presenter can leave useful room for a later
+diagram, and a voice can carry the attitude the edit should support. State that consequence as a
+property of the requested material, then author the later relationship through its actual component,
+time and space inputs. Review the accepted material before relying on a detail the producer did not
+establish.
-## Components express relationships worth preserving
+## Components preserve shared behavior
-A component owns shared behavior. Its inputs connect real dependencies and useful directing choices:
-assets, important events, placement or treatment. Decorative geometry and fixed local design may
-remain internal. A one-off scene is ordinary production work; cross-project reuse is separate.
+A component owns content that needs shared layout, state or motion. Its inputs connect real
+dependencies and useful directing choices: assets, important events, placement and treatment.
+Decorative geometry and fixed local design can remain internal.
-Critical internal events retain separate semantic relations when they answer different words.
-Interpolation and local motion can follow those events without exposing every number as a control.
-[Component design](component-design.md#let-meaning-drive-the-behavior) explains the boundary;
-[Track authoring](track-authoring.md) explains implementation.
+Responsibility, parameterization and distribution are separate. A one-off project scene can be a
+well-formed component with few controls; cross-project reuse is decided only when it becomes useful.
+[Component design](component-design.md) explains that boundary, and [Track authoring](track-authoring.md)
+implements it.
-Film explicitly selects peer VisualTrack and AudioTrack outputs and combines them with Timeline and
-Canvas into Composition. Including picture never includes sibling sound. Source nesting, component
-scope, paint order and graph dependency are different relations and need not share boundaries.
+Film explicitly selects its Timeline, Canvas and required visual/audio outputs. Source nesting,
+component scope, paint order and execution dependencies keep their own meanings.
## Source, Run, Runtime and Studio
-Author Source connects material requests, timing relations, components and deliverables. Recipes
-provide authored treatment. A Run selects public Outputs as Targets and may reuse exact file or Result
-Candidates. Reuse the narrowest completed value whose facts remain true: generated media,
-NarrativeAlignment and downstream presentation can be retained or recomputed independently.
+Author Source connects material requests, time and space values, components and deliverables.
+Recipes hold reusable treatments. A Run selects public Outputs as Targets and can reuse exact files
+or completed Result Outputs as Candidates. Reuse the narrowest value whose facts still serve the
+current edit.
-A Build executes selected graph work; Result retains completed public Outputs. External work is a
-Need implemented by Providers and Endpoints chosen in a Runtime Profile. None of that execution
-machinery enters Timeline, media presentation or component domain values.
+A Build executes the demanded graph and records completed public Outputs in its Result. Runtime
+Profiles select already installed Providers, Endpoints and credentials for external work.
-Studio inspects the same graph. Package Companions follow actual producer and input edges to expose
-recognizable entities and author controls. They do not reverse-engineer pixels, query a global anchor
-table or transfer edit authority from Script or Style to a numeric Timeline coordinate.
+Studio reads the authored and executed relationships exposed by the selected packages. Companions
+give useful entities and controls to a component by following its real inputs and outputs.
[Authoring](authoring.md), [Runs](runs.md), [Builds](builds.md) and [Studio](studio.md) own those workflows.
diff --git a/skills/hypit/references/production/timeline.md b/skills/hypit/references/production/timeline.md
index fdf11475..db1fb7bc 100644
--- a/skills/hypit/references/production/timeline.md
+++ b/skills/hypit/references/production/timeline.md
@@ -1,13 +1,11 @@
# Construct the program Timeline
-Read this when deciding complete duration, placing unknown-length prepared media, or sharing absolute
-Instants and Windows. [Media preparation](media.md) produces neutral local domains and Extents;
-[timing](timing.md) explains absolute values and semantic projection; [Visual](visual-clips.md)
-and [Audio](audio-clips.md) explain presentation.
+Read this when deciding complete duration or naming absolute Instants and Windows. [Media
+preparation](media.md) publishes local domains and Extents; [Timing](timing.md) explains direct and
+projected values; [Visual](visual-clips.md) and [Audio](audio-clips.md) place media in the resolved work.
-The production Timeline is a small absolute value: identity, frame rate and finite frame count. It
-contains no Takes, media, words, anchor registry or Tracks. Its author declaration is a small acyclic
-Instant/Window construction graph with one required `end`.
+Timeline is the work's finite absolute frame domain. Its author declaration is an acyclic graph of
+Instant and Window expressions with one required `end`.
```svml
<import as="time" from="@hypit/timeline-author@1"/>
@@ -21,63 +19,53 @@ Instant/Window construction graph with one required `end`.
</time:Timeline>
```
-Every named declaration is naturally published: `program.opening` is a Window,
-`program.opening.start` and `.end` are its boundary Instants, and `program.claim` is an Instant.
-`program.window`, `.start` and `.end` describe the complete Timeline. There is no `export` attribute
-and no nested Place declaration.
+Each named declaration publishes an ordinary value: `program.opening` is a Window,
+`program.opening.start` and `.end` are boundary Instants, and `program.claim` is an Instant.
+`program.window`, `.start` and `.end` describe the complete Timeline.
-A Window supplies exactly two of `from`, `until` and `for`. `for` accepts an exact `f`, `ms` or `s`
-duration, or a typed Extent such as `opening-media.extent`. Point expressions may use `start`, the
-resolved `end`, literal positions, named Instants, a named Window's `.start`/`.end`, exact `+`/`-`
-literal offsets, `earliest(...)` and `latest(...)`.
+A Window supplies exactly two of `from`, `until` and `for`. `for` accepts an exact frame, millisecond
+or second duration, or a typed Extent. Point expressions can use `start`, the resolved `end`, literal
+positions, named Instants, Window boundaries, exact offsets, `earliest(...)` and `latest(...)`.
-Forward references are valid because dependencies, not source order, determine evaluation. A final
-Window may depend on `end`; if `end` also depends on that Window, the real graph cycle is rejected.
-Unknown references, values outside the final range, empty Windows and a non-positive end are errors.
-
-The graph may have several roots, branches and leaves. It needs no single content root or last clip.
-Use `latest(...)` when several branches can determine final extent. A pure animation can be:
+Dependencies determine evaluation, so declarations can refer forward. Use `latest(...)` when several
+branches can determine complete duration. A wholly authored animation can simply declare:
```svml
<time:Timeline id="animation" clock={clock} end="30s"/>
```
-## Unknown material length is an ordinary dependency
+## Let resolved material determine duration
+
+Generated speech or video can publish its Extent after the Source has been written. A Window consumes
+that Extent, and any dependent boundary resolves through ordinary graph evaluation:
-Generated speech or video need not reveal its length while Source is written. Normalization later
-publishes a finite `TemporalExtent`; a Window consumes it, and dependent boundaries wait through
-ordinary graph evaluation. No phase state machine, callback or second Source run is needed. If a
-generation request depends on Timeline end while that same end depends on the generated result, the
-author has created a real cycle and should change that relationship.
+```svml
+<time:Window id="speech" from="start" for={speech-media.extent}/>
+```
-After Timeline finalization, a domain projector may combine one complete local domain with one
-equal-length Window. This is exact native-speed translation, consumed immediately by that projector;
-it does not produce a durable Placement value. Trim, retime, loop, hold, frame-rate conversion and
-piecewise speed belong to explicit material preparation or medium-specific sampling, not implicit
-Timeline arithmetic.
+Keep dependencies acyclic: a generation request that depends on Timeline end cannot also determine
+that same end. Unknown references, empty Windows, values outside the final range and a non-positive
+end are author errors.
-## Keep meaning, media and presentation separate
+## Project local evidence after Timeline resolves
-A `NarrativeAlignment` says where one Segment's boundaries lie on a local domain. A semantic
-Projection combines explicit `NarrativeAlignment + local domain + equal-length Window` relations to
-locate Script Selections and Moments on this Timeline. Once the absolute values are published, that
-construction relation disappears. Visual and Audio receive ordinary normalized media plus explicit
-absolute Windows:
+Map one complete local domain to one equal-length Window when its self-contained evidence needs an
+absolute position. Narrative projection uses this relation to publish requested Script Selections,
+Moments or boundaries:
```text
-NarrativeAlignment + LocalDomain + Window -> absolute Instants/Windows
-SynchronizedMedia + Window -> visual / audio occurrence
-Timeline -> finite absolute range only
+NarrativeAlignment + LocalDomain + Window -> absolute Instants / Windows
```
-Replaying media creates another media occurrence; it does not silently duplicate one semantic event.
-If the same words genuinely occur twice, author distinct Script identities. Musical beats, subtitle
-timing and future domains may build peer projection adapters without adding event kinds to Timeline.
+This mapping preserves the local endpoints at native speed. Prepare trims, retiming or other altered
+media before projecting evidence whose endpoints must remain meaningful.
-Put a shared Instant or Window in Timeline when it determines extent or several consumers deliberately
-reuse it. Write a one-off component time directly on that component. This prevents Timeline from
-becoming a central schedule of every clip and effect.
+Visual and Audio placement is a separate decision:
+
+```text
+SynchronizedMedia + Window -> visual / audio occurrence
+```
-The project document `TIMELINE.md` remains the production team's human record of reference evidence
-and creative meaning; it is not the runtime Timeline value. Reference timestamps describe observed
-material, while the Source declaration constructs the new work.
+Put a named Instant or Window in Timeline when it determines extent or several consumers deliberately
+share it. Write one-off component timing directly on that component. The project `TIMELINE.md` can
+retain human observations and their meaning; Source constructs the executable Timeline.
diff --git a/skills/hypit/references/production/timing.md b/skills/hypit/references/production/timing.md
index 04dc3eff..085f0d88 100644
--- a/skills/hypit/references/production/timing.md
+++ b/skills/hypit/references/production/timing.md
@@ -1,18 +1,17 @@
-# Timing authored relationships
+# Author timing relationships
-Read this when deciding when a component acts. [Script syntax](script-syntax.md) names Narrative
-relationships; [Timeline](timeline.md) constructs the complete absolute domain. Components consume
-absolute Instants and Windows.
+Read this when deciding when a component exists or acts. [Script syntax](script-syntax.md) names
+Narrative relationships; [Timeline](timeline.md) constructs the finite absolute domain. Components
+consume absolute Instants and Windows.
-## Start from the production decision
+## Choose the time source that matches the event
Use Narrative time when a picture or event should follow meaning as wording or performance changes.
-Use absolute time when it should follow the film clock. Both choices eventually produce the same
-absolute value types; neither is mandatory for the other.
+Use direct Timeline time when it should follow the film clock. Both choices resolve to the same
+absolute value types.
-NarrativeAlignment locates Script boundaries in a source-local domain. `semantic:Projection` maps
-that domain exactly onto an equal-length Timeline Window and publishes only the Narrative
-Instants and Windows the production asks for:
+`semantic:Projection` maps aligned local evidence into Timeline and publishes only the values this
+production asks to reuse:
```svml
<semantic:Projection id="story-time" narrative={story} timeline={film.timeline}>
@@ -23,58 +22,50 @@ Instants and Windows the production asks for:
</semantic:Projection>
```
-General components then use `story-time.proof`, `story-time.claim`, and `story-time.answer-end` as
-ordinary `TemporalWindow` or `TemporalInstant` values. They do not receive `story-time.projection`
-and do not interpret Script objects.
+Components then use `story-time.proof`, `story-time.claim` and `story-time.answer-end` as ordinary
+Window and Instant values.
-## Window forms
+## Declare, then consume
-Surfaces using the common Window vocabulary accept one of these forms:
+Timeline authoring and domain projectors produce named values. Components only consume them:
| Form | Result |
| --- | --- |
-| `during="timeline"` | The complete film Window. |
-| `during={story-time.proof}` | An already resolved Window. |
-| `from="2s" for="12f"` | A Window beginning at two seconds and lasting twelve frames. |
-| `until="3s" for="250ms"` | A 250 ms Window ending at three seconds. |
-| `from={story-time.claim} until={story-time.answer-end}` | A Window between two resolved Instants. |
+| `<time:Window id="beat" timeline={film.timeline} from="2s" for="12f"/>` | A named absolute Window |
+| `<time:Window id="answer" timeline={film.timeline} from={story-time.claim} until={story-time.answer-end}/>` | A named Window between projected Instants |
+| `during={story-time.proof}` | Consume a projected Window |
+| `during={beat}` | Consume a directly authored Window |
-Outside `during`, supply exactly two of `from`, `until`, and `for`. `for` may also reference a
-`TemporalExtent`, including the measured duration of generated media. This does not put media on
-Timeline; it only lets an ordinary graph result determine an interval.
+Window declarations supply exactly two of `from`, `until` and `for`. `for` can also reference a
+TemporalExtent, including generated media duration. The complete film is already named as
+`film.window`.
## Instant forms
-An event component uses one Instant:
-
| Form | Result |
| --- | --- |
-| `at={story-time.claim}` | A domain-projected event. |
-| `at="2s"` or `at="12f"` | An absolute clock event. |
-| `at="timeline.end-12f"` | An event relative to a Timeline boundary. |
-
-The component decides what the event does. A card may remain visible, a slideshow component may switch pictures,
-or a motion may begin. The Instant itself has no visible duration.
+| `at={story-time.claim}` | A projected event |
+| `<time:Instant id="cut" timeline={film.timeline} at="2s"/>` | A named direct clock event |
+| `<time:Instant id="credits" timeline={film.timeline} at="timeline.end-12f"/>` | A named event relative to the Timeline boundary |
+| `at={cut}` | Consume the named event |
-## Name only what needs a name
+The component decides what the event changes and whether that state persists.
-Write timing directly on a single consumer when it is local to that occurrence. Publish a named
-Timeline Window/Instant when it helps determine the film end or is deliberately shared. Publish a
-domain-projected value when its source identity matters. Do not copy every possible semantic anchor
-into a central table.
+## Name shared values
-## Editing
+Name even a single-use absolute value outside the consuming component. Put it in Timeline when it
+helps determine film extent; otherwise use a standalone declaration against the completed Timeline.
+Publish a projected value when its domain identity matters to the production.
-Studio follows the producer of the value:
+## Choose what a later edit changes
-- an absolute literal edits that literal;
-- a named Timeline value edits its Timeline declaration;
-- a Narrative-produced value edits the declared Narrative mapping that produced it;
-- a reused value is edited once at its producer, so every consumer follows after recompilation.
+The authored value determines the editing relationship:
-The consumer does not carry an inverse projector. If a source domain offers no declared inverse,
-Studio does not guess one. A resolved value remains fully usable even when it is not editable.
+- editing a direct literal changes that literal;
+- editing a named Timeline value changes its Timeline declaration;
+- editing a Narrative-produced value changes the mapping or Narrative source that produced it;
+- editing a reused value changes its producer and all consumers follow after recompilation.
-Frames use the selected film clock. Seconds and milliseconds express clock duration. Keep semantic
-relationships, absolute offsets, and response duration as separate author decisions rather than
-collapsing them into one hidden policy.
+Studio can display any resolved value. It offers source editing only where the package declares a
+meaningful author relation. Keep semantic relationships, absolute offsets and response duration as
+separate decisions.
diff --git a/skills/hypit/references/production/track-authoring.md b/skills/hypit/references/production/track-authoring.md
index f77fa526..32d876a4 100644
--- a/skills/hypit/references/production/track-authoring.md
+++ b/skills/hypit/references/production/track-authoring.md
@@ -29,7 +29,7 @@ This existing answer-strip vocabulary illustrates a concrete choice:
```svml
<emoji:EmojiReveal id="answers" timeline={speech.timeline} within={canvas.bounds}
- style={answer-style} placeholder={question-icon} during="timeline">
+ style={answer-style} placeholder={question-icon} during={speech.window}>
<emoji:Item id="known" icon={known-icon} preset="true"/>
<emoji:Item id="surprise" icon={answer-icon} at={story-time.reveal}/>
</emoji:EmojiReveal>
@@ -39,11 +39,11 @@ Its outer Window owns visibility; source order owns slots; preset answers exist
each activation Instant changes only its slot and the answer persists. A chart or scoreboard can instead own
repeated updates or simultaneous events.
-## Keep domain projection and consumption distinct
+## Keep selection projection and consumption distinct
Script names Narrative meaning: a Selection, Segment or Moment. `@hypit/narrative-temporal`
combines Alignment, its local domain and an equal-length Window and publishes requested absolute Instants or Windows. The
-component's Surface accepts those values—or constructs direct clock values—and its Fragment and
+component's Surface accepts those values, and its Fragment and
Producers decide what to do with them.
```text
@@ -60,14 +60,14 @@ component to search for a word, carry a projector or inspect the Script parser.
Use `resolveTemporalContext` from `@hypit/hypit/temporal/markup` to resolve the component's
`timeline` input. Pass that same Timeline to its Fragment and Producers, alongside projected
-Instants/Windows. A component can combine literal times and domain-produced events without switching time
-models. The installed `examples/semantic-composition/packages/chat-scene` demonstrates repeated
+Instants/Windows. A component can combine directly authored and domain-produced named values without switching
+time models. The installed `examples/semantic-composition/packages/chat-scene` demonstrates repeated
content children with their own events and a picture drawn entirely in code.
-For a Window consumer, `during={story-time.example}` reuses a projected interval.
-`from={story-time.answer} for="8f"` starts a short effect at a projected event. An Instant consumer
-may accept `at={story-time.answer}` with no duration because it owns a state transition. Read the
-actual Surface: Window and Instant consumers deliberately expose different vocabulary.
+For a Window consumer, `during={story-time.example}` reuses a projected interval. To start a short
+effect at an Instant, first declare a named Window from that Instant, then pass it through `during`.
+An Instant consumer may accept `at={story-time.answer}` because it owns a state transition. Read the
+actual Surface: Window and Instant consumers deliberately expose different reference vocabulary.
[Timing](timing.md) describes the shared forms.
## Separate lifetime, activation and persistent state
@@ -75,7 +75,7 @@ actual Surface: Window and Instant consumers deliberately expose different vocab
For a board that stays on screen, author its outer Window independently of individual reveals.
Then decide what its children mean:
-- an Item window may mean “draw only during this interval,” as with ordinary Media;
+- an Item window may mean “draw only during this interval,” as with an ordinary Clip;
- an activation window may stage an item's entrance and movement, after which it remains in a board;
- a Moment may replace a question mark with an answer that persists until the outer Window ends;
- a preset item may already occupy the initial state and need no reveal trigger.
@@ -88,15 +88,14 @@ The interview's project emoji strip illustrates this design: one outer Window, o
items, a placeholder asset and one icon per answer. Each Moment changes its own slot. The Track does
not decide when the spoken answer occurred; it consumes the already projected event.
-## Use absolute time without turning Timeline into a media container
+## Use absolute time with explicit media inputs
The [Timeline](timeline.md) resolves Instants and Windows from literal or typed Extents. A domain
projector may translate a complete local domain through an equal-length Window, then publish ordinary
absolute values and discard that relation. Media is not bound to this projection; a Visual or Audio
Clip declares its own ordinary media occurrence with an absolute Window. Sequential ranges,
-head/interior/tail space and simultaneous branches therefore remain temporal relationships rather
-than a central list of clips. A project scene consumes the Timeline, media and the Instants or Windows
-its behavior actually needs.
+head/interior/tail space and simultaneous branches remain temporal relationships. A project scene
+consumes the Timeline, media and the Instants or Windows its behavior actually needs.
A different material operation, such as trimming or retiming a performance, changes the local media
and its preparation. A display operation, such as crossfading two available sources, belongs to the
@@ -111,8 +110,8 @@ per-frame regions already resolved in the program picture plane. These are disti
which owns the complete time range.
Keep image dimensions, placement and crop transformations visible so a measured head or a reserved
-MG area maps into the actual composition. Take the production's Canvas and the placement inputs the role needs. Derive related internal
-geometry from their common owner. A project scene may keep a fixed layout and speaker arrangement;
+MG area maps into the actual composition. Take the production's Canvas and the placement inputs the
+role needs. Derive related internal geometry from their common owner. A project scene may keep a fixed layout and speaker arrangement;
a reusable behavior exposes the variation its real uses require. Keep renderer viewport selection
and any detector in their own execution or measurement boundary.
@@ -135,7 +134,7 @@ The Surface exposes author intent and lowers absolute temporal forms through
`createTemporalWindowConstruction` or `createTemporalInstantConstruction`. The Fragment wires the
completed value, the shared Timeline, explicit placement Frames and authored values into the
component's Producers. Narrative, beat or other domain packages project their own values upstream;
-the component does not accept those projectors. The Producer owns the visual/state behavior, while
+the component accepts their projected absolute values. The Producer owns the visual/state behavior, while
Studio follows the graph back to the value's actual declaration for editing.
Wire supplied media, Script content and event references through Source. Expose other content or
@@ -160,8 +159,7 @@ The useful pieces of a project package are:
Resolve the Track's `timeline` through `resolveTemporalContext` and wire `context.timeline.ref`
directly to its Timeline input. Source footage is supplied explicitly through media inputs. The
-visual Producer consumes Timeline and absolute time values, not Script syntax, a NarrativeProjection,
-or media hidden inside Timeline.
+visual Producer consumes Timeline, explicit media and absolute time values.
For each Window, call `createTemporalWindowConstruction`; for an event, use
`createTemporalInstantConstruction`. Pass the resolved context, the child element and
@@ -171,8 +169,9 @@ returned `ref` into the domain Fragment. Window consumers support `during` or ex
or absolute expressions only. A Narrative package must publish its selected boundary first.
Keep each child's `subjectId` meaningful for inspection while qualifying graph ids by its owning
-Track, so multiple instances can coexist. Do not use it to reject a deliberately shared Window. A finite create/append/finalize graph supports any authored
-number of messages or cards with ordinary fixed Producer ports. The exact helpers and vocabulary
+Track, so multiple instances can coexist. Do not use it to reject a deliberately shared Window. A
+finite create/append/finalize graph supports any authored number of messages or cards with ordinary
+fixed Producer ports. The exact helpers and vocabulary
live in `@hypit/hypit/temporal/markup`; the `@example/chat-scene` package demonstrates authored and semantic events on one Timeline.
A scene may publish computed event times when another component needs them, just as it publishes a
@@ -184,7 +183,7 @@ draw nothing; inside it, each slot shows its preset/activated answer or its plac
entrance motion relative to that slot's activation frame. Deriving state directly from declared inputs
and the requested frame keeps Studio scrubbing and partial or concurrent rendering deterministic.
-Emit the public VisualTrack representation through `@hypit/hypit/composition` and `@hypit/hypit/composition`.
+Emit the public VisualTrack representation through `@hypit/hypit/composition`.
[Component visuals](component-visuals.md) explains Presents, element trees, local animation,
prepared surfaces and a complete drawing function. [Spatial layout](spatial.md) explains incoming
Frames, and [Fonts and text](fonts-and-text.md) explains font resources.
@@ -198,7 +197,7 @@ Document which Outputs are public, including useful deterministic program values
## Verify the behavior the component introduced
-When the new role needs its own timeline presentation or Inspector, read
+When the new role needs its own timeline entities or Inspector, read
[Companion authoring](studio-companions.md). Expose the domain
schedule and temporal identities at their actual boundaries so the editor consumes them directly
instead of reconstructing them from pixels.
@@ -219,7 +218,6 @@ those exercise the new behavior.
When behavior spans several source occurrences, make that relation the component's own vocabulary.
A continuing Presenter may own explicit Source and Use children; a crossfade may own outgoing and
incoming roles; a slideshow may own its replacement policy. The component receives Timeline, Frames,
-media and events through normal typed inputs and publishes an ordinary VisualTrack. Its local grammar
-does not add Presentation, Sequence or effect kinds to [Visual Track](visual-clips.md), and a larger
-scene coordinating footage and graphics can remain one project component. Both paths use the same
-rendering capabilities.
+media and events through normal typed inputs and publishes an ordinary VisualTrack. Its package owns
+the local grammar for that relation, while a larger scene coordinating footage and graphics can remain
+one project component. Both paths use the same rendering capabilities.
diff --git a/skills/hypit/references/production/tracks.md b/skills/hypit/references/production/tracks.md
index 11961ca7..207ea3f8 100644
--- a/skills/hypit/references/production/tracks.md
+++ b/skills/hypit/references/production/tracks.md
@@ -1,54 +1,47 @@
-# Choose and compose contributions
+# Choose and compose picture and sound
-Read this to decide how content enters picture or sound. [System](system.md) explains the model;
-[media preparation](media.md), [timing](timing.md) and [spatial layout](spatial.md) own shared inputs.
-A new shared behavior belongs in a [project component](component-design.md).
+Read this to decide how content enters the finished picture or mix. [System](system.md) explains the
+whole model; [media preparation](media.md), [timing](timing.md) and [spatial layout](spatial.md) own
+shared inputs.
## Choose by relationship
| Relationship | Starting point | Output |
| --- | --- | --- |
-| Place an image, normalized video or surface | [Visual Clip](visual-clips.md) | `.visual` |
-| Place speech, music, narration, ambience or effects | [Audio Clip](audio-clips.md) | `.audio` |
-| Coordinate continuing sources, transitions, ducking or richer layout | [Project component](track-authoring.md) | declared `.visual` and/or `.audio` |
-| Present authored display words at resolved Cue times | [Caption](caption-presentation.md) | package-owned VisualTrack |
+| Place an image, normalized video or surface | [Visual Clip](visual-clips.md) | VisualTrack |
+| Place speech, music, narration, ambience or effects | [Audio Clip](audio-clips.md) | AudioTrack |
+| Present Script display words at resolved Cue times | [Caption](caption-presentation.md) | package-owned VisualTrack |
| Supply independent writing | [Typography/Text](fonts-and-text.md) | package-owned VisualTrack |
-| Coordinate new layout, state or motion | [Project component](track-authoring.md) | declared VisualTrack and/or AudioTrack |
+| Coordinate continuing sources, transitions, ducking, layout or state | [Project component](track-authoring.md) | declared VisualTrack and/or AudioTrack |
-This is not a closed catalogue. A board, effect or whole scene is a component whose behavior owns
-its inputs and outputs. Images, text and video may share one scene when their behavior is shared.
+These are starting points, not a catalogue of visual roles. Images, text and video can share a scene
+when they share behavior.
-## Reuse one normalized source without binding picture and sound
+## Use synchronized media through independent occurrences
-Normalization can establish synchronized visual and audio streams on one local domain. Timeline may
-use its Extent, while Visual and Audio Clips independently pair the same media with an absolute
-Window:
+Normalization can establish picture and sound streams on one local domain. Timeline may use its
+Extent, while Visual and Audio Clips independently pair the media with an absolute Window:
```text
normalized media + Window + visual sampling -> Visual Clip -> VisualTrack
normalized media + Window + audio sampling -> Audio Clip -> AudioTrack
```
-This makes the common A-roll case concise without giving Timeline hidden media contents. Picture may
-be covered or reframed while speech continues; audio-only and picture-only material need no dummy
-peer. Do not route one voice through two selected audio contributions.
+This supports A-roll without coupling picture and sound. The picture can be covered or reframed
+while speech continues; audio-only and picture-only material need only their real contribution.
-## Let events and behavior determine organization
+## Let shared behavior determine scope
A picture can occupy a projected Selection, a sound can follow a Moment, and a board can retain its
-answer after a reveal. All ultimately consume absolute Timeline Instants or Windows. Semantic meaning
-arrives through an explicit projection relation, not through a special kind of Track.
+answer after a reveal. Components receive the resolved absolute values they need. Shared motion or
+state can justify one component; independent contributions can remain peers while using the same
+event.
-An outer Window describes component lifetime. Separate meaningful internal events keep their own
-triggers; persistent state may continue after one event. Shared movement or state can justify one
-component. Independent contributions may remain peers while consuming the same Moment.
+## Assemble the intended film
-## Assemble only what the film needs
-
-Film receives Canvas, Timeline and each selected visual/audio output. Timeline establishes the finite
-extent; components establish appearances and paint order. Including picture never includes sibling
-sound automatically. Film child order does not move a picture to the front: every Present owns its
-absolute stacking and internal tree.
+Film receives Canvas, Timeline and each selected visual/audio output. Components establish appearance
+and paint order. Include picture and sound explicitly, and select one intended route for each audible
+source.
[Rendering](rendering.md#assemble-the-picture-and-sound) shows Film assembly and delivery.
-[Review](review.md) judges the selected picture, performance boundaries and complete mix.
+[Review](review.md) judges the resulting picture, performance and complete mix.
diff --git a/skills/hypit/references/production/visual-clips.md b/skills/hypit/references/production/visual-clips.md
index f40a10bd..7eaaccf7 100644
--- a/skills/hypit/references/production/visual-clips.md
+++ b/skills/hypit/references/production/visual-clips.md
@@ -1,17 +1,15 @@
# Place pictures through Visual Track
-Read this when an existing image, normalized video or compositable Surface should appear in the
-finished picture. [Media preparation](media.md) owns incoming material, [spatial layout](spatial.md)
-owns destination Frames, and [timing](timing.md) owns absolute and projected event time.
+Read this when an image, normalized video or compositable Surface should appear in the finished
+picture. [Media preparation](media.md) owns source facts, [spatial layout](spatial.md) owns destination
+Frames, and [timing](timing.md) owns absolute and projected time.
-## The ordinary relation is one Clip occurrence
-
-Visual Track has one base child form:
+## Place one ordinary Clip occurrence
```text
-Visual Clip = one picture source + absolute Window + Frame
- + z + spatial mapping + source-time + optional treatment + optional typed Motion
-Visual Track = ordered set of Visual Clips
+Visual Clip = picture source + absolute Window + Frame
+ + z + spatial mapping + source-time + optional treatment + optional Motion
+Visual Track = a set of Visual Clips
```
```svml
@@ -29,31 +27,36 @@ Visual Track = ordered set of Visual Clips
</visual:Track>
```
-An A-roll picture, B-roll insert, generated shot and imported graphic are equal after their inputs
-exist. A medium may earlier have supplied Timeline extent or local-domain evidence; that contribution
-does not create a special rendering route. The Clip names the source again because rendering is a
-separate relation: the author explicitly chooses what becomes visible.
+An A-roll picture, B-roll insert, generated shot and imported graphic use the same occurrence model.
+The Clip explicitly chooses what becomes visible, even when the source earlier supplied Timeline
+extent or semantic evidence.
+
+A Clip takes one source form:
+
+- `image` with its pixel `extent` for a still;
+- normalized `media` for timed picture;
+- a typed `surface` for compositable pixels.
-A Clip takes exactly one direct source form—`image` with `extent`, normalized `media`, or a typed
-`surface`. `during` consumes an absolute Window or the complete
-Timeline. The alternate temporal form supplies exactly two of `from`, `until` and `for`.
+`during` accepts a resolved Window or the complete Timeline. The alternate form supplies exactly two
+of `from`, `until` and `for`.
-Spatially, ordinary fit and alignment attributes derive a source-local-to-program `SpatialMap2D`.
-If that vocabulary is insufficient, pass an explicitly authored `<space:Map>` through `mapping`.
-The Clip Frame remains the independent treatment and clipping boundary. See
-[spatial layout](spatial.md#map-a-source-plane-and-treat-its-frame) for the complete relation.
+Ordinary fit and alignment attributes derive the source-to-picture SpatialMap2D. Supply an authored
+`space:Map` through `mapping` when the production already owns the exact relation. The Clip Frame
+remains the treatment and clipping boundary. [Spatial layout](spatial.md#map-a-source-plane-and-treat-its-frame)
+explains the relation.
## Keep destination time and source sampling distinct
-The Window says when the occurrence may contribute. It does not silently prove an anchor mapping.
-For moving media, omission means bounded partial identity: target start maps to source start at native
-rate, and excess destination time is empty.
+The Window states when the occurrence contributes. For moving media, omission uses bounded native
+playback from source start; source that ends before the Window leaves the remaining picture empty.
-Use `visual:Map` children when the temporal relation differs. `target-from`/`target-until` select Clip-local target
-frames; `source-from`/`source-until` select source frames; `target-at`, `source-at` and an exact `rate`
-relate the clocks. `wrap-from`/`wrap-until` makes a source interval periodic. A Map with only source
-and target bounds fits one interval across the other. Multiple non-overlapping Maps create one
-piecewise relation and gaps stay transparent.
+Use `visual:Map` children for another relation. Target bounds select Clip-local time; source bounds
+select source frames; paired anchors and an exact rate relate the two clocks. `wrap-from` and
+`wrap-until` make a source interval periodic. Multiple non-overlapping Maps form one piecewise
+relation and retain transparent gaps.
+
+Use rate zero to hold a frame and a negative rate for reverse traversal. A Map with source and
+target bounds but no rate, anchors or wrap fits the selected source interval across its target.
```svml
<visual:Clip media={shot.media} during={story.outro} frame={layout.full} z="10">
@@ -61,36 +64,23 @@ piecewise relation and gaps stay transparent.
</visual:Clip>
```
-Stills reject `visual:Map` because they have no source clock. This temporal child is unrelated to a
-`space:Map` supplied through the `mapping` attribute. `z`, spatial mapping and source time are direct
-occurrence facts. A treatment Recipe contains only image/Frame paint. A typed Motion contains affine
-and opacity Pose keyframes over the Clip-local clock; it is not an enter/sustain/exit effect catalogue.
-
-Use distinct `z` values whenever the relative paint relation matters. Equal-`z` Clips are legal and
-follow stable declaration and identity order; choosing that tie is the author's responsibility.
-Sampling children move the crop inside the Frame; Pose children or `motion={Motion}` move the complete
-framed Clip.
-
-Exact one-to-one mapping is required only when another package claims that local semantic endpoints
-project exactly into an absolute Window. Ordinary picture placement is not that proof operation.
+Stills have no source clock and therefore use no temporal Map. `space:Map` and `visual:Map` answer
+different questions.
-## Relationships spanning Clips are components
+Use distinct `z` values when relative paint order matters. Equal-`z` Clips are legal and use stable
+declaration and identity order. Sampling changes which source pixels appear; Pose or `motion` moves
+the complete framed occurrence.
-Visual Track has no generic Presentation, Style/Use, Sequence or Handoff ontology. A continuing
-presenter, crossfade, slideshow or coordinated reveal owns behavior across several occurrences, so
-it belongs to a project or reusable author component. The component may use Visual Track's public
-builders and publish the same terminal `VisualTrack`; Film and Core do not learn a catalogue of roles
-or effects.
+## Put shared behavior in a component
-This does not ban a component-local child named `Use`. Caption retains Use because one persistent
-CaptionDocument and Timing stream is real shared content. A project Presenter may also define Source
-and Use because continuing presenter identity is its behavior. Those local grammars do not become
-base Visual Track syntax.
+A continuing presenter, crossfade, slideshow or coordinated reveal owns behavior across several
+occurrences. Implement that relationship as a project or reusable component, using Visual Track
+builders where useful and publishing a VisualTrack for Film.
-Visual Track emits `.visual` and `.program`, never audio. Place desired sound independently through
-[Audio Track](audio-clips.md). Using both streams from one normalized medium therefore remains an
-explicit author decision.
+Components can define local author vocabularies that fit their shared content. Caption, for example,
+uses a persistent document and timed Uses; a presenter component may similarly expose its own roles
+and treatments. These are component relationships, not requirements for an ordinary Clip.
-When footage and graphics form one coordinated scene, author a project component whose boundary owns
-that relationship. [Track authoring](track-authoring.md) explains how components publish ordinary
-terminal tracks without changing Core.
+Visual Track publishes `.visual` for Film and `.program` for declared tooling. It emits picture only;
+place desired sound independently through [Audio Track](audio-clips.md). [Track authoring](track-authoring.md)
+explains how a component publishes a visual contribution.
diff --git a/skills/hypit/references/production/vocabulary.md b/skills/hypit/references/production/vocabulary.md
index 0126084e..3f6f3df7 100644
--- a/skills/hypit/references/production/vocabulary.md
+++ b/skills/hypit/references/production/vocabulary.md
@@ -99,7 +99,7 @@ For existing Track composition, read [Tracks](tracks.md). For a new Track,
state, preset content and peer visual/audio outputs. [Caption authoring](caption-authoring.md) covers
a new speech-text family without rebuilding its transcript or timing.
-[Studio and Companions](studio.md) covers timeline presentation and Inspector editing for the new
+[Studio and Companions](studio.md) covers timeline entities and Inspector editing for the new
component.
[Component visuals](component-visuals.md) explains the actual Track and element representation,